Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

fix(brands): preserve icons after XHTML empty elements

asts-top1bcf60f41276
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 39a2434d..68eaa6f6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,7 +8,7 @@ All notable changes are documented here. Format loosely follows [Keep a Changelo
### Fixed
-- **Inactive brand icon declarations.** Capture ignores icon markup in comments, raw text (including `noscript` for `text/html`), quoted attributes and templates, so inactive page edits cannot replace the selected image or break its pinned digest. Complete link attributes keep quoted delimiters and distinguish `href` from `data-href`; XHTML `noscript` discovery is unchanged.
+- **Inactive brand icon declarations.** Capture ignores icon markup in comments, raw text (including `noscript` for `text/html`), quoted attributes and templates, so inactive page edits cannot replace the selected image or break its pinned digest. Complete link attributes keep quoted delimiters and distinguish `href` from `data-href`; XHTML `noscript` discovery and links after empty elements are preserved. Old pins to inactive markup may require inspecting and explicitly recapturing the intended icon; digest checking remains enforced.
- **Brand ICO data bounds (#585).** Capture and pinned re-fetches reject empty, directory-overlapping or out-of-bounds image ranges in ICO directory entries, while preserving valid PNG/DIB payloads and normal icon fallback.
### Changed
diff --git a/archify.zip b/archify.zip
index 5ab1e0a0..64dcb1e1 100644
Binary files a/archify.zip and b/archify.zip differ
diff --git a/archify/references/brand-marks.md b/archify/references/brand-marks.md
index 33d0665e..b09b8952 100644
--- a/archify/references/brand-marks.md
+++ b/archify/references/brand-marks.md
@@ -64,7 +64,9 @@ cannot supply icon declarations; quoted `>` characters stay within their tags.
For `text/html`, discovery treats `noscript` contents as raw text, matching
scripting-enabled HTML parsing; capture does not execute scripts. This exclusion
does not apply to `application/xhtml+xml`, where `noscript` links remain
-discoverable.
+discoverable. XHTML empty elements such as `<script />` and `<template />` do not
+hide following links; the same trailing slash does not close those elements in
+`text/html`.
Unknown URL capture accepts only bounded raster image formats, blocks
credentials, nonstandard public ports, and private or link-local destinations,
uses bounded concurrency and one total deadline, and returns the captured
@@ -72,6 +74,13 @@ content digest. Later render and validate operations require that exact digest;
blocked, unavailable, changed, oversized, or unsafe content fails closed instead
of silently changing the artifact.
+After upgrading from a version that captured inactive HTML markup (including
+`noscript`), an existing URL pin may fail with `brand/digest-mismatch` because
+discovery now selects a different icon. Inspect the intended icon, rerun the
+capture command above for the same URL, and explicitly replace the authored
+`brand` value with the returned pin. Existing pins are not rewritten
+automatically, and digest verification remains enforced.
+
For ICO captures, every directory entry must reference a non-empty image range
after the complete directory and within the downloaded file. This bounds check
also applies when reproducing a pinned capture. PNG/DIB payloads, multiple
diff --git a/archify/renderers/shared/brand-marks.mjs b/archify/renderers/shared/brand-marks.mjs
index 26771b6e..9bdb1ada 100644
--- a/archify/renderers/shared/brand-marks.mjs
+++ b/archify/renderers/shared/brand-marks.mjs
@@ -280,7 +280,7 @@ async function readLimited(response, maximum) {
// bytes once so many tiny chunks cannot cause repeated concatenation/rescanning.
// Collect link tags in the same pass: markup in comments, raw text, attributes
// or templates must not become an icon candidate or an early head ending.
-async function readHtmlHeadLinks(response, maximum, htmlScriptingEnabled) {
+async function readHtmlHeadLinks(response, maximum, mediaType) {
const chunks = response.body && typeof response.body[Symbol.asyncIterator] === 'function'
? response.body : [await readLimited(response, maximum)];
const buffer = Buffer.alloc(maximum);
@@ -341,12 +341,13 @@ async function readHtmlHeadLinks(response, maximum, htmlScriptingEnabled) {
response.body?.destroy?.();
return links;
}
- if (/^<template(?=[\t\n\f\r />])/i.test(tag)) templateDepth += 1;
+ const emptyXhtmlElement = mediaType === 'application/xhtml+xml' && tag.endsWith('/>');
+ if (!emptyXhtmlElement && /^<template(?=[\t\n\f\r />])/i.test(tag)) templateDepth += 1;
else if (/^<\/template(?=[\t\n\f\r />])/i.test(tag)) templateDepth = Math.max(0, templateDepth - 1);
else if (!templateDepth && /^<link(?=[\t\n\f\r />])/i.test(tag)) links.push(tag);
const raw = /^<(script|style|title|textarea|xmp|iframe|noembed|noframes)(?=[\t\n\f\r />])/i.exec(tag)
- || (htmlScriptingEnabled && /^<(noscript)(?=[\t\n\f\r />])/i.exec(tag));
- if (raw) rawClosing = `</${raw[1].toLowerCase()}`;
+ || (mediaType === 'text/html' && /^<(noscript)(?=[\t\n\f\r />])/i.exec(tag));
+ if (raw && !emptyXhtmlElement) rawClosing = `</${raw[1].toLowerCase()}`;
tagStart = -1;
}
}
@@ -506,9 +507,9 @@ async function captureRemoteBrand(value, deadline = Date.now() + captureTimeoutM
page.response.body?.destroy?.();
return fallback('linked page is not HTML');
}
- // Match scripting-enabled HTML parsing for noscript without executing scripts.
- const htmlScriptingEnabled = pageType.split(';')[0].trim() === 'text/html';
- const links = await readHtmlHeadLinks(page.response, MAX_HTML_BYTES, htmlScriptingEnabled);
+ // Distinguish HTML noscript and XHTML empty elements without executing scripts.
+ const mediaType = pageType.split(';')[0].trim();
+ const links = await readHtmlHeadLinks(page.response, MAX_HTML_BYTES, mediaType);
const iconErrors = [];
for (const candidate of iconCandidates(links, page.finalUrl)) {
try {
diff --git a/test/brand-icon-contexts.test.mjs b/test/brand-icon-contexts.test.mjs
index 28c3a60f..a45e9d3a 100644
--- a/test/brand-icon-contexts.test.mjs
+++ b/test/brand-icon-contexts.test.mjs
@@ -36,7 +36,7 @@ function run(args) {
});
}
-async function fixture(t, markup, { byteChunks = false, contentType = 'text/html; charset=utf-8' } = {}) {
+async function fixture(t, markup, { byteChunks = false, contentType = 'text/html; charset=utf-8', fallbackIcon = icon } = {}) {
const data = { markup, requests: [] };
const server = http.createServer(async (request, response) => {
data.requests.push(request.url);
@@ -53,9 +53,12 @@ async function fixture(t, markup, { byteChunks = false, contentType = 'text/html
response.write(html);
}
response.end();
- } else if (['/active.png', '/active.png?a=1&b=2', '/favicon.ico'].includes(request.url)) {
+ } else if (['/active.png', '/active.png?a=1&b=2'].includes(request.url)) {
response.writeHead(200, { 'content-type': 'image/png' });
response.end(icon);
+ } else if (request.url === '/favicon.ico' && fallbackIcon) {
+ response.writeHead(200, { 'content-type': 'image/png' });
+ response.end(fallbackIcon);
} else if (request.url === '/inactive.png') {
response.writeHead(200, { 'content-type': 'image/png' });
response.end(inactiveIcon);
@@ -121,6 +124,38 @@ for (const contentType of ['application/xhtml+xml', 'Application/XHTML+XML; char
});
}
+for (const [name, prefix] of [
+ ['script', '<script src="/app.js" />'],
+ ['template', '<template />'],
+]) {
+ for (const [fallback, fallbackIcon] of [['different', inactiveIcon], ['missing', null]]) {
+ test(`capture reads icons after an empty XHTML ${name} with a ${fallback} favicon`, async (t) => {
+ const markup = prefix + '<link rel="icon" href="/active.png" />';
+ await capture(await fixture(t, markup, { contentType: 'application/xhtml+xml', fallbackIcon }));
+ });
+ }
+
+ test(`empty-element syntax does not close an HTML ${name}`, async (t) => {
+ const markup = prefix + activeLink;
+ await capture(await fixture(t, markup, { fallbackIcon: inactiveIcon }), ['/favicon.ico'], inactiveDigest);
+ });
+
+ test(`an empty XHTML ${name} survives one-byte response chunks`, { timeout: 20000 }, async (t) => {
+ const markup = prefix + '<link rel="icon" href="/active.png" />';
+ await capture(await fixture(t, markup, {
+ byteChunks: true,
+ contentType: 'Application/XHTML+XML; charset=utf-8; profile="text/html"',
+ fallbackIcon: inactiveIcon,
+ }));
+ });
+}
+
+test('an empty XHTML template does not change the enclosing template depth', async (t) => {
+ const markup = '<template><template /><link rel="icon" href="/inactive.png" /></template>'
+ + '<link rel="icon" href="/active.png" />';
+ await capture(await fixture(t, markup, { contentType: 'application/xhtml+xml', fallbackIcon: inactiveIcon }));
+});
+
for (const [name, markup] of [
['ordinary icon', activeLink],
['quoted greater-than', '<link title="size > zero" rel="icon" href="/active.png">'],
@@ -136,6 +171,34 @@ for (const [name, markup] of [
});
}
+test('old noscript pins fail closed until explicitly recaptured', { timeout: 45000 }, async (t) => {
+ const temporary = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-brand-recapture-'));
+ t.after(() => fs.rmSync(temporary, { recursive: true, force: true }));
+ const data = await fixture(t, noscriptLink + activeLink);
+ const diagram = JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples/web-app.architecture.json'), 'utf8'));
+ diagram.components[0].brand = { url: data.url, sha256: inactiveDigest };
+ const input = path.join(temporary, 'diagram.json');
+ const original = JSON.stringify(diagram);
+ fs.writeFileSync(input, original);
+
+ const outdated = await run(['validate', 'architecture', input, '--json']);
+ assert.notEqual(outdated.status, 0, outdated.stderr || outdated.stdout);
+ assert.ok(JSON.parse(outdated.stdout).diagnostics.some((entry) => entry.code === 'brand/digest-mismatch'));
+ assert.deepEqual(data.requests, ['/studio', '/active.png']);
+ assert.equal(fs.readFileSync(input, 'utf8'), original, 'validation must not rewrite an existing pin');
+
+ data.requests.length = 0;
+ const recaptured = await capture(data);
+ assert.equal(fs.readFileSync(input, 'utf8'), original, 'capture must not rewrite authored diagrams');
+ diagram.components[0].brand = recaptured;
+ fs.writeFileSync(input, JSON.stringify(diagram));
+ data.requests.length = 0;
+ const updated = await run(['validate', 'architecture', input, '--json']);
+ assert.equal(updated.status, 0, updated.stderr || updated.stdout);
+ assert.equal(JSON.parse(updated.stdout).ok, true);
+ assert.deepEqual(data.requests, ['/studio', '/active.png']);
+});
+
test('inactive declarations do not consume the five icon candidate slots', async (t) => {
const removed = Array.from({ length: 5 }, (_, index) => `<link rel="icon" href="/missing-${index}.png">`).join('');
await capture(await fixture(t, `<!-- ${removed} -->${activeLink}`));