Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.
HTML agent-skillsai-agentsarchitecture-diagramclaude-codeclaude-skillscodexcoding-agentsdeepseek-harnessdeveloper-toolsdiagramsdiagrams-as-codedsh-pluginflowchartllmmermaidopencodesequence-diagramsoftware-architecturesystem-designvisualization
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { parseFragment } from 'parse5';
import { execFileSync } from 'node:child_process';
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { compactFinalizeReceipt } from '../archify/bin/finalize.mjs';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const skillRoot = path.resolve(__dirname, '..', 'archify');
const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-output-checks-'));
const checker = path.join(skillRoot, 'scripts/check-render-output.mjs');
test('render output check: finite_svg preserves slashes in unquoted HTML attribute values', () => {
for (const [markup, expected] of [
['<line x1=NaN/>', 'NaN/'],
['<line x1=NaN />', 'NaN'],
['<line x1="NaN"/>', 'NaN'],
['<line x1=NaN/ x2=10 />', 'NaN/'],
['<line x1=NaN/></line>', 'NaN/'],
]) {
const svg = parseFragment(`<svg>${markup}</svg>`).childNodes[0];
const value = svg.childNodes[0].attrs.find((attr) => attr.name === 'x1').value;
assert.equal(value, expected, markup);
const { result } = checkHtml('unquoted-attribute-slash', markup);
const check = result.checks.find((entry) => entry.name === 'finite_svg');
assert.equal(check.ok, false, markup);
assert.deepEqual(check.details, [`line x1="${value}"`], markup);
}
});
// 240x154 keeps the default fixture at the 1.55 wide ratio, so the fixed-width
// viewport-height rule stays out of tests that target other composition rules.
function checkHtml(name, svgBody, profile = 'standard', viewBox = '0 0 240 154', head = '', svgAttributes = '') {
const htmlPath = path.join(tmp, `${name}.html`);
fs.writeFileSync(htmlPath, `<!doctype html><html><head>${head}</head><body><svg viewBox="${viewBox}" data-quality-profile="${profile}"${svgAttributes}>${svgBody}</svg></body></html>`);
try {
const stdout = execFileSync('node', [checker, htmlPath], { encoding: 'utf8' });
return { code: 0, result: JSON.parse(stdout) };
} catch (err) {
return { code: err.status ?? 1, result: JSON.parse(String(err.stdout || '{}')) };
}
}
test('render output check: showcase rejects node copy that becomes illegible at 1440px', () => {
const { code, result } = checkHtml('showcase-desktop-readability', `
<g data-node-id="tool-runtime">
<rect x="1398" y="266" width="194" height="70" rx="6" class="c-mask"/>
<text data-detail-anchor x="1495" y="299" class="t-primary" font-size="11">ToolRuntime</text>
<text data-detail="context" x="1495" y="315" class="t-muted" font-size="8.1">permissions and recovery</text>
</g>
`, 'showcase', '0 0 1994 804');
assert.notEqual(code, 0);
const issue = result.composition.issues.find(
(item) => item.code === 'composition/desktop-readability',
);
assert.equal(issue?.severity, 'error');
assert.equal(issue?.viewportWidth, 1440);
assert.ok(issue?.projectedFontPx < issue?.minimumProjectedFontPx);
});
test('render output check: predicts the certain 1440x900 overflow of a fixed-width portrait canvas', () => {
const node = `
<g data-node-id="a">
<rect x="20" y="20" width="200" height="60" rx="6" class="c-mask"/>
<text data-node-label x="120" y="55" class="t-primary" font-size="12">Node</text>
</g>
`;
// 1080x780 dataflow: measured in Chrome at 972px SVG / 1159px page before cards.
const portrait = checkHtml('viewport-height-portrait', node, 'showcase', '0 0 1080 780', '', '');
const issue = portrait.result.composition.issues.find((item) => item.code === 'composition/viewport-height');
assert.equal(issue?.severity, 'warning', 'new rule surfaces as evidence first');
assert.equal(portrait.code, 0);
assert.equal(issue.svgHeightPx, 972);
assert.equal(issue.fixedChromePx, 126);
assert.equal(issue.pageHeightPx, 1098);
assert.match(issue.detail, /meta\.viewBox height is at most 696 at this width/);
assert.match(issue.detail, /width is at least 1209 at this height/);
assert.equal(portrait.result.composition.summary.warnings, 1);
const declaredFit = checkHtml('viewport-height-fit', node, 'showcase', '0 0 1080 780', '', ' data-reader-fit="intrinsic-height"');
assert.equal(declaredFit.result.composition.issues.some((item) => item.code === 'composition/viewport-height'), false, 'a Reader-declared fit can scroll readably');
// Long automatic rows already have readable document scrolling; declaration
// changes must not invent fixed-canvas warnings for the same geometry.
for (const fit of ['intrinsic-height', 'width-first']) {
const tallAutomatic = checkHtml(`viewport-tall-${fit}`, node, 'showcase', '0 0 920 2400', '', ` data-reader-fit="${fit}"`);
assert.equal(tallAutomatic.result.composition.issues.some(item => item.code === 'composition/viewport-height'), false);
}
for (const attributes of ['', ' data-reader-fit="unknown"', ' data-sequence-column-fit="fixed"', ' data-waterfall-ui=""']) {
const tallUndeclared = checkHtml('viewport-tall-undeclared', node, 'showcase', '0 0 920 2400', '', attributes);
const warning = tallUndeclared.result.composition.issues.find(item => item.code === 'composition/viewport-height');
assert.equal(warning?.severity, 'warning');
assert.ok(warning?.pageHeightPx > 3000);
}
for (const type of ['architecture', 'workflow', '']) {
const fixed = checkHtml(`viewport-authored-${type}`, node, 'showcase', '0 0 1080 780', '',
` data-reader-fit="authored-height" data-diagram-type="${type}"`);
assert.equal(fixed.result.composition.issues.some(item => item.code === 'composition/viewport-height'), type !== 'architecture');
}
const wide = checkHtml('viewport-height-wide', node, 'showcase', '0 0 1600 900');
assert.equal(wide.result.composition.issues.some((item) => item.code === 'composition/viewport-height'), false, 'a wide canvas is narrowed by the Reader instead');
assert.equal(wide.result.composition.metrics.viewportHeightIssues, 0);
});
test('render output check: compares exact projected size before rounding diagnostics', () => {
const sourceFontPx = 8.1;
const viewBoxWidth = 1260;
assert.ok(sourceFontPx * 930 / viewBoxWidth < 6);
const { code, result } = checkHtml('showcase-desktop-readability-borderline', `
<g data-node-id="tool-runtime">
<rect x="100" y="100" width="194" height="70" rx="6" class="c-mask"/>
<text data-detail="context" x="197" y="140" class="t-muted" font-size="${sourceFontPx}">permissions and recovery</text>
</g>
`, 'showcase', `0 0 ${viewBoxWidth} 804`);
assert.notEqual(code, 0);
const issue = result.composition.issues.find(
(item) => item.code === 'composition/desktop-readability',
);
assert.equal(issue?.severity, 'error');
assert.ok(issue?.projectedFontPx < issue?.minimumProjectedFontPx);
});
test('render output check: includes primary node labels in desktop readability', () => {
const { code, result } = checkHtml('showcase-primary-desktop-readability', `
<g data-node-id="compact-node">
<rect x="100" y="100" width="120" height="48" rx="6" class="c-mask"/>
<text data-node-label x="160" y="126" class="t-primary" font-size="8">Compact node</text>
</g>
`, 'showcase', '0 0 1300 700');
assert.notEqual(code, 0);
const issue = result.composition.issues.find(
(item) => item.code === 'composition/desktop-readability',
);
assert.equal(issue?.text, 'Compact node');
assert.equal(issue?.detail, 'primary');
assert.equal(issue?.availableDiagramWidth, 930);
assert.ok(issue?.projectedFontPx < issue?.minimumProjectedFontPx);
});
test('render output check: includes semantic boundary labels in desktop readability', () => {
const { code, result } = checkHtml('showcase-boundary-desktop-readability', `
<g data-graph-role="structural-frame-label">
<rect data-graph-role="structural-frame-label-mask" x="100" y="100" width="180" height="16" class="c-mask"/>
<text x="104" y="113" class="t-cloud" font-size="8.4" data-boundary-label>Disaster recovery boundary</text>
</g>
`, 'showcase', '0 0 1376 728');
assert.notEqual(code, 0);
const issue = result.composition.issues.find(
(item) => item.code === 'composition/desktop-readability',
);
assert.equal(issue?.text, 'Disaster recovery boundary');
assert.equal(issue?.detail, 'boundary');
assert.ok(issue?.projectedFontPx < issue?.minimumProjectedFontPx);
});
test('render output check: recognized declared-wide Reader admits the hard floor but records an unmet 7.5 target', () => {
const { code, result } = checkHtml('recognized-declared-wide-edge', `
<g data-edge-from="listener" data-edge-to="handler" data-detail="context">
<text x="120" y="160" class="t-muted" font-size="8">method path body</text>
<text data-detail="fine" x="120" y="172" class="t-dim" font-size="1">fine annotation</text>
</g>
`, 'showcase', '0 0 1438 800', '<meta name="archify-reader-contract" content="declared-wide-v1">', ' data-reader-fit="intrinsic-height" data-reader-min-text="7.5"');
assert.equal(code, 0, JSON.stringify(result, null, 2));
assert.equal(result.composition.desktopReadability.budgetBasis, 'recognized-declared-wide');
assert.equal(result.composition.desktopReadability.availableDiagramWidth, 1346);
assert.equal(result.composition.desktopReadability.minimumOwner.kind, 'edge');
assert.equal(result.composition.desktopReadability.minimumOwner.id, null);
assert.equal(result.composition.desktopReadability.semanticTextCount, 1);
assert.equal(result.composition.desktopReadability.hardFloorMet, true);
assert.equal(result.composition.desktopReadability.requestedTargetPx, 7.5);
assert.equal(result.composition.desktopReadability.requestedTargetMet, false);
assert.ok(result.composition.desktopReadability.minimumProjectedTextPx < 7.5);
});
test('render output check: width-first preserves the intrinsic declared-wide readability budget', () => {
const body = '<g data-node-id="node"><text data-node-label x="160" y="126" class="t-primary" font-size="8">Node</text></g>';
const head = '<meta name="archify-reader-contract" content="declared-wide-v1">';
const intrinsic = checkHtml('intrinsic-budget', body, 'showcase', '0 0 1438 800', head, ' data-reader-fit="intrinsic-height" data-reader-min-text="7.5"');
const widthFirst = checkHtml('width-first-budget', body, 'showcase', '0 0 1438 800', head, ' data-reader-fit="width-first" data-reader-min-text="7.5"');
assert.equal(widthFirst.code, intrinsic.code);
assert.deepEqual(widthFirst.result.composition.desktopReadability, intrinsic.result.composition.desktopReadability);
for (const marker of ['data-sequence-column-fit="fixed"', 'data-waterfall-ui=""', 'data-reader-fit="unknown"']) {
const undeclared = checkHtml('undeclared-budget', body, 'showcase', '0 0 1438 800', head, ` ${marker} data-reader-min-text="7.5"`);
assert.equal(undeclared.result.composition.desktopReadability.budgetBasis, 'legacy-930');
}
});
test('render output check: ordinary metadata preserves legacy readability and bare semantic markers', () => {
const { code, result } = checkHtml('ordinary-meta-legacy-primary', `
<g data-node-id="compact-node">
<text data-node-label x="160" y="126" class="t-primary" font-size="8">Compact node</text>
</g>
`, 'showcase', '0 0 1300 700', '<meta name="viewport" content="width=device-width">');
assert.notEqual(code, 0);
assert.equal(result.composition.desktopReadability.budgetBasis, 'legacy-930');
const issue = result.composition.issues.find((item) => item.code === 'composition/desktop-readability');
assert.equal(issue?.detail, 'primary');
assert.equal(issue?.owner.kind, 'node');
});
test('render output check: marker recognition is exact and old fit/min-only HTML keeps the 930px floor', () => {
const body = `
<g data-edge-from="listener" data-edge-to="handler" data-detail="context">
<text x="120" y="160" class="t-muted" font-size="8">method path body</text>
</g>
`;
const svgAttributes = ' data-reader-fit="intrinsic-height" data-reader-min-text="7.5"';
for (const [name, head, attributes] of [
['old-fit-min-only', '', svgAttributes],
['unknown-reader-contract', '<meta name="archify-reader-contract" content="declared-wide-v2">', svgAttributes],
['duplicate-reader-contract', '<meta name="archify-reader-contract" content="declared-wide-v1"><meta name="archify-reader-contract" content="declared-wide-v1">', svgAttributes],
['invalid-reader-minimum', '<meta name="archify-reader-contract" content="declared-wide-v1">', ' data-reader-fit="intrinsic-height" data-reader-min-text="NaN"'],
['explicit-viewbox-geometry', '<meta name="archify-reader-contract" content="declared-wide-v1">', ' data-reader-min-text="7.5"'],
]) {
const { code, result } = checkHtml(name, body, 'showcase', '0 0 1438 800', head, attributes);
assert.notEqual(code, 0, name);
assert.equal(result.composition.desktopReadability.budgetBasis, 'legacy-930', name);
assert.equal(result.composition.issues.find((item) => item.code === 'composition/desktop-readability')?.detail, 'edge', name);
}
});
test('render output check: an edge below 6 remains warning in standard and error in showcase', () => {
const body = `
<g data-edge-from="listener" data-edge-to="handler" data-detail="context">
<text x="120" y="160" class="t-muted" font-size="5">short semantic edge label</text>
</g>
`;
const head = '<meta name="archify-reader-contract" content="declared-wide-v1">';
const svgAttributes = ' data-reader-fit="intrinsic-height" data-reader-min-text="7.5"';
const standard = checkHtml('declared-wide-standard-edge', body, 'standard', '0 0 1438 800', head, svgAttributes);
const showcase = checkHtml('declared-wide-showcase-edge', body, 'showcase', '0 0 1438 800', head, svgAttributes);
assert.equal(standard.code, 0);
assert.equal(standard.result.composition.issues.find((item) => item.code === 'composition/desktop-readability')?.severity, 'warning');
assert.notEqual(showcase.code, 0);
assert.equal(showcase.result.composition.issues.find((item) => item.code === 'composition/desktop-readability')?.severity, 'error');
});
test('render output check: finite non-positive semantic text remains below the 6px floor', () => {
const contract = '<meta name="archify-reader-contract" content="declared-wide-v1">';
const attributes = ' data-reader-fit="intrinsic-height" data-reader-min-text="7.5"';
for (const [name, body] of [
['zero-only', '<g data-edge-from="a" data-edge-to="b" data-detail="context"><text x="1" y="1" font-size="0">zero</text></g>'],
['negative-only', '<g data-edge-from="a" data-edge-to="b" data-detail="context"><text x="1" y="1" font-size="-1">negative</text></g>'],
['zero-with-normal', '<g data-edge-from="a" data-edge-to="b" data-detail="context"><text x="1" y="1" font-size="8">ordinary</text><text x="1" y="2" font-size="0">zero</text></g>'],
]) {
const showcase = checkHtml(`${name}-showcase`, body, 'showcase', '0 0 1438 800', contract, attributes);
const standard = checkHtml(`${name}-standard`, body, 'standard', '0 0 1438 800', contract, attributes);
assert.notEqual(showcase.code, 0, name);
assert.equal(showcase.result.composition.desktopReadability.budgetBasis, 'legacy-930', name);
assert.equal(showcase.result.composition.issues.find((item) => item.code === 'composition/desktop-readability')?.severity, 'error', name);
assert.equal(standard.code, 0, name);
assert.equal(standard.result.composition.issues.find((item) => item.code === 'composition/desktop-readability')?.severity, 'warning', name);
}
});
test('render output check: fine detail on a context edge is excluded before ownership classification', () => {
const { code, result } = checkHtml('fine-context-edge', `
<g data-edge-from="a" data-edge-to="b" data-detail="context">
<text x="1" y="1" font-size="8">ordinary relationship label</text>
<g data-detail="fine"><text x="1" y="2" font-size="1">fine nested note</text></g>
</g>
`, 'showcase', '0 0 1438 800', '<meta name="archify-reader-contract" content="declared-wide-v1">', ' data-reader-fit="intrinsic-height" data-reader-min-text="7.5"');
assert.equal(code, 0, JSON.stringify(result, null, 2));
assert.equal(result.composition.desktopReadability.minimumOwner.kind, 'edge');
assert.equal(result.composition.desktopReadability.semanticTextCount, 1);
assert.ok(result.composition.desktopReadability.minimumProjectedTextPx >= 6);
});
test('render output check: accepts orthogonal arrows away from legend', () => {
const { code, result } = checkHtml('clean', `
<path d="M 20 20 L 120 20 L 120 60" class="a-default" stroke-width="1.4" marker-end="url(#arrowhead)"/>
<!-- Legend -->
<text x="40" y="120" class="t-primary" font-size="10">Legend</text>
<rect x="40" y="132" width="14" height="9" class="c-backend"/>
<text x="60" y="140" class="t-muted" font-size="7">Backend</text>
`);
assert.equal(code, 0);
assert.equal(result.ok, true);
});
test('render output check: rejects two-point diagonal arrows', () => {
const { code, result } = checkHtml('diagonal', `
<path d="M 20 20 L 120 80" class="a-default" stroke-width="1.4" marker-end="url(#arrowhead)"/>
<!-- Legend -->
<text x="40" y="120" class="t-primary" font-size="10">Legend</text>
`);
assert.notEqual(code, 0);
const check = result.checks.find((item) => item.name === 'orthogonal_arrows');
assert.equal(check.ok, false);
assert.match(check.details[0], /path 1/);
});
test('render output check: rejects a diagonal segment inside a polyline', () => {
const { code, result } = checkHtml('polyline-diagonal', `
<path d="M 20 20 L 60 35 L 120 35" class="a-default" stroke-width="1.4" marker-end="url(#arrowhead)"/>
<!-- Legend -->
<text x="40" y="120" class="t-primary" font-size="10">Legend</text>
`);
assert.notEqual(code, 0);
const check = result.checks.find((item) => item.name === 'orthogonal_arrows');
assert.equal(check.ok, false);
assert.match(check.details[0], /path 1/);
assert.match(check.details[0], /segment 1/);
});
test('render output check: measures a non-Latin legend label with the shared text model', () => {
// The renderer's footprint for "\u03a3\u03cd\u03c3\u03c4\u03b7\u03bc\u03b1" at font-size 10 ends near x=103
// (measured with textUnits), so a route that begins at x=160 is clear of it. A
// Latin-1-only heuristic bills those seven characters at 1.8 units each and
// stretches the box to x=186, reporting a crossing that does not exist.
const { code, result } = checkHtml('legend-non-latin-clear', `
<path d="M 200 140 L 160 140" class="a-default" stroke-width="1.4" marker-end="url(#arrowhead)"/>
<!-- Legend -->
<text x="40" y="120" class="t-primary" font-size="10">Legend</text>
<rect x="40" y="132" width="14" height="9" class="c-backend"/>
<text x="60" y="140" class="t-muted" font-size="10">\u03a3\u03cd\u03c3\u03c4\u03b7\u03bc\u03b1</text>
`);
const clearance = result.checks.find((entry) => entry.name === 'legend_clearance');
assert.equal(code, 0, JSON.stringify(clearance, null, 2));
assert.equal(result.ok, true);
});
test('render output check: rejects arrows crossing legend text', () => {
const { code, result } = checkHtml('legend-crossing', `
<path d="M 20 112 L 180 112" class="a-dashed" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
<!-- Legend -->
<text x="40" y="120" class="t-primary" font-size="10">Legend</text>
<rect x="40" y="132" width="14" height="9" class="c-backend"/>
<text x="60" y="140" class="t-muted" font-size="7">Backend</text>
`);
assert.notEqual(code, 0);
const check = result.checks.find((item) => item.name === 'legend_clearance');
assert.equal(check.ok, false);
assert.match(check.details[0], /Legend/);
});
test('render output check: ignores unmarked sequence lifelines near legend', () => {
const { code, result } = checkHtml('lifeline-near-legend', `
<path d="M 60 20 L 60 126" class="a-default" stroke-width="0.8" stroke-dasharray="3,7"/>
<!-- Legend -->
<text x="40" y="120" class="t-primary" font-size="10">Legend</text>
<path d="M 120 136 L 154 136" class="a-default" stroke-width="1.4" stroke-dasharray="3,5" marker-end="url(#arrowhead)"/>
<text x="163" y="139" class="t-muted" font-size="8">return</text>
`);
assert.equal(code, 0);
assert.equal(result.ok, true);
});
test('render output check: standard records a proper X as a composition warning', () => {
const { code, result } = checkHtml('standard-crossing', `
<path data-edge-from="a" data-edge-to="b" d="M 20 60 L 200 60" class="a-default" marker-end="url(#arrowhead)"/>
<path data-edge-from="c" data-edge-to="d" d="M 103 20 L 103 120" class="a-dashed" marker-end="url(#arrowhead-dashed)"/>
`);
assert.equal(code, 0);
assert.equal(result.composition.profile, 'standard');
assert.deepEqual(result.composition.summary, { errors: 0, warnings: 1 });
assert.equal(result.composition.metrics.properCrossings, 1);
assert.equal(result.composition.issues[0].code, 'composition/proper-crossing');
assert.equal(result.composition.issues[0].severity, 'warning');
});
test('render output check: showcase rejects a proper X with semantic identities', () => {
const { code, result } = checkHtml('showcase-crossing', `
<path data-edge-id="left" data-edge-from="a" data-edge-to="b" d="M 20 60 L 200 60" class="a-default" marker-end="url(#arrowhead)"/>
<path data-edge-id="right" data-edge-from="c" data-edge-to="d" d="M 100 20 L 100 120" class="a-dashed" marker-end="url(#arrowhead-dashed)"/>
`, 'showcase');
assert.notEqual(code, 0);
const check = result.checks.find((item) => item.name === 'relationship_crossings');
assert.equal(check.ok, false);
assert.match(check.details[0], /\[composition\/proper-crossing\] showcase/);
assert.match(check.details[0], /relationship id "left"/);
assert.deepEqual(result.composition.summary, { errors: 1, warnings: 0 });
});
test('render output check: verified automatic crossover halos resolve a proper X', () => {
const { code, result } = checkHtml('showcase-verified-crossover-halo', `
<path data-graph-role="automatic-crossover-underlay" d="M 20 60 L 200 60" fill="none" stroke="var(--mask)" stroke-width="5.5" pointer-events="none"/>
<path data-edge-id="left" data-edge-from="a" data-edge-to="b" data-composition-crossover="halo" d="M 20 60 L 200 60" class="a-default" stroke-width="1.5" marker-end="url(#arrowhead)"/>
<path data-graph-role="automatic-crossover-underlay" d="M 100 20 L 100 120" fill="none" stroke="var(--mask)" stroke-width="5.5" pointer-events="none"/>
<path data-edge-id="right" data-edge-from="c" data-edge-to="d" data-composition-crossover="halo" d="M 100 20 L 100 120" class="a-dashed" stroke-width="1.5" marker-end="url(#arrowhead-dashed)"/>
`, 'showcase');
assert.equal(code, 0, JSON.stringify(result.composition.issues));
assert.equal(result.composition.metrics.properCrossings, 0);
assert.equal(result.composition.metrics.resolvedCrossovers, 1);
assert.deepEqual(result.composition.summary, { errors: 0, warnings: 0 });
});
test('render output check: crossover halos fail closed when sibling adjacency is interrupted', () => {
const underlay = '<path data-graph-role="automatic-crossover-underlay" d="M 20 60 L 200 60" fill="none" stroke="var(--mask)" stroke-width="5.5" pointer-events="none"/>';
const route = '<path data-edge-id="left" data-edge-from="a" data-edge-to="b" data-composition-crossover="halo" d="M 20 60 L 200 60" class="a-default" stroke-width="1.5" marker-end="url(#arrowhead)"/>';
const rightUnderlay = '<path data-graph-role="automatic-crossover-underlay" d="M 100 20 L 100 120" fill="none" stroke="var(--mask)" stroke-width="5.5" pointer-events="none"/>';
const rightRoute = '<path data-edge-id="right" data-edge-from="c" data-edge-to="d" data-composition-crossover="halo" d="M 100 20 L 100 120" class="a-dashed" stroke-width="1.5" marker-end="url(#arrowhead-dashed)"/>';
for (const [name, separator] of [
['comment', '<!-- an intervening comment -->'],
['element', '<path d="M 1 1 L 2 2"/>'],
['group', '<g></g>'],
]) {
const { code, result } = checkHtml(`showcase-crossover-nonadjacent-${name}`, `
${underlay}
${separator}
${route}
${rightUnderlay}
${rightRoute}
`, 'showcase');
assert.notEqual(code, 0, name);
assert.equal(result.composition.metrics.properCrossings, 1, name);
assert.equal(result.composition.metrics.resolvedCrossovers, 0, name);
}
});
test('render output check: a crossover marker without a matching underlay fails closed', () => {
const { code, result } = checkHtml('showcase-unverified-crossover-halo', `
<path data-graph-role="automatic-crossover-underlay" d="M 20 61 L 200 61" fill="none" stroke="var(--mask)" stroke-width="5.5" pointer-events="none"/>
<path data-edge-id="left" data-edge-from="a" data-edge-to="b" data-composition-crossover="halo" d="M 20 60 L 200 60" class="a-default" stroke-width="1.5" marker-end="url(#arrowhead)"/>
<path data-graph-role="automatic-crossover-underlay" d="M 100 20 L 100 120" fill="none" stroke="var(--mask)" stroke-width="5.5" pointer-events="none"/>
<path data-edge-id="right" data-edge-from="c" data-edge-to="d" data-composition-crossover="halo" d="M 100 20 L 100 120" class="a-dashed" stroke-width="1.5" marker-end="url(#arrowhead-dashed)"/>
`, 'showcase');
assert.notEqual(code, 0);
assert.equal(result.composition.metrics.properCrossings, 1);
assert.equal(result.composition.metrics.resolvedCrossovers, 0);
const crossing = result.composition.issues.find((item) => item.code === 'composition/proper-crossing');
assert.equal(crossing?.severity, 'error');
});
test('render output check: shared endpoints and endpoint touches pass showcase', () => {
const { code, result } = checkHtml('showcase-exemptions', `
<path data-edge-from="a" data-edge-to="b" d="M 20 60 L 200 60" class="a-default" marker-end="url(#arrowhead)"/>
<path data-edge-from="a" data-edge-to="c" d="M 100 20 L 100 90" class="a-dashed" marker-end="url(#arrowhead-dashed)"/>
<path data-edge-from="d" data-edge-to="e" d="M 20 100 L 100 100" class="a-default" marker-end="url(#arrowhead)"/>
<path data-edge-from="f" data-edge-to="g" d="M 100 100 L 100 140" class="a-default" marker-end="url(#arrowhead)"/>
`, 'showcase');
assert.equal(code, 0);
assert.equal(result.composition.metrics.properCrossings, 0);
assert.equal(result.composition.metrics.ambiguousCorridors, 0);
});
test('render output check: relationship labels cannot hide another shared-source route', () => {
for (const profile of ['standard', 'showcase']) {
const { code, result } = checkHtml(`label-route-${profile}`, `
<path data-edge-key="0" data-edge-id="approved" data-edge-from="dlq" data-edge-to="replay" data-composition-points="20,60;200,60" d="M 20 60 L 200 60" class="a-default" marker-end="url(#arrowhead)"/>
<path data-edge-key="1" data-edge-id="sample" data-edge-from="dlq" data-edge-to="ops" data-composition-points="70,55;150,55" d="M 70 55 L 150 55" class="a-dashed" marker-end="url(#arrowhead-dashed)"/>
<g data-detail="context" data-edge-key="0" data-edge-id="approved" data-edge-from="dlq" data-edge-to="replay" data-edge-label="approved replay">
<rect x="80" y="48" width="60" height="14" rx="3" class="c-mask"/>
<text x="110" y="58">approved replay</text>
</g>
`, profile);
assert.equal(result.composition.metrics.labelRouteClearanceIssues, 1);
assert.equal(result.composition.metrics.minLabelRouteClearance, 0);
const issue = result.composition.issues.find((item) => item.code === 'composition/label-route-clearance');
assert.deepEqual(issue.labelRelationship, { id: 'approved', from: 'dlq', to: 'replay', label: 'approved replay', collectionIndex: 0, artifactIndex: 1 });
assert.deepEqual(issue.otherRelationship, { id: 'sample', from: 'dlq', to: 'ops', label: '', collectionIndex: 1, artifactIndex: 2 });
assert.equal(issue.segmentIndex, 0);
assert.deepEqual(issue.labelRect, { x: 80, y: 48, width: 60, height: 14 });
assert.equal(issue.clearance, 0);
assert.equal(issue.intersectionLength, 60);
assert.equal(issue.threshold, profile === 'showcase' ? 4 : 2);
const check = result.checks.find((item) => item.name === 'label_route_clearance');
if (profile === 'standard') {
assert.equal(code, 0);
assert.equal(check.ok, true);
assert.equal(issue.severity, 'warning');
assert.deepEqual(result.composition.summary, { errors: 0, warnings: 1 });
} else {
assert.notEqual(code, 0);
assert.equal(check.ok, false);
assert.match(check.details[0], /approved.*sample/);
assert.match(check.details[0], /labelAt.*labelDx.*labelDy.*labelSegment/);
assert.equal(issue.severity, 'error');
assert.deepEqual(result.composition.summary, { errors: 1, warnings: 0 });
}
}
});
// `check` also runs against artifacts it did not produce, so a label the SVG
// canvas clips has to be measurable from the emitted markup alone.
test('render output check: a relationship label cannot leave the canvas', () => {
for (const profile of ['standard', 'showcase']) {
const { code, result } = checkHtml(`label-canvas-${profile}`, `
<path data-edge-key="0" data-edge-id="approved" data-edge-from="dlq" data-edge-to="replay" data-composition-points="20,60;200,60" d="M 20 60 L 200 60" class="a-default" marker-end="url(#arrowhead)"/>
<g data-detail="context" data-edge-key="0" data-edge-id="approved" data-edge-from="dlq" data-edge-to="replay" data-edge-label="approved replay">
<rect x="200" y="48" width="60" height="14" rx="3" class="c-mask"/>
<text x="230" y="58">approved replay</text>
</g>
`, profile);
assert.equal(result.composition.metrics.labelCanvasOverflowIssues, 1);
const issue = result.composition.issues.find((item) => item.code === 'composition/label-canvas-containment');
assert.equal(issue.label, 'approved replay');
assert.deepEqual(issue.labelRect, { x: 200, y: 48, width: 60, height: 14 });
assert.deepEqual(issue.viewBox, [240, 154]);
assert.deepEqual(issue.overflowPx, { right: 20 });
assert.match(issue.detail, /extends past the right edge by 20px/);
// The rule owns no named check: it fails the receipt through composition,
// exactly like composition/desktop-readability.
assert.equal(result.checks.length, 9);
assert.ok(result.checks.every((check) => check.ok));
if (profile === 'standard') {
assert.equal(code, 0);
assert.equal(issue.severity, 'warning');
assert.deepEqual(result.composition.summary, { errors: 0, warnings: 1 });
} else {
assert.notEqual(code, 0);
assert.equal(issue.severity, 'error');
assert.deepEqual(result.composition.summary, { errors: 1, warnings: 0 });
assert.equal(result.ok, false);
}
}
});
test('render output check: a contained relationship label reports no overflow', () => {
const { code, result } = checkHtml('label-canvas-contained', `
<path data-edge-key="0" data-edge-id="approved" data-edge-from="dlq" data-edge-to="replay" data-composition-points="20,60;200,60" d="M 20 60 L 200 60" class="a-default" marker-end="url(#arrowhead)"/>
<g data-detail="context" data-edge-key="0" data-edge-id="approved" data-edge-from="dlq" data-edge-to="replay" data-edge-label="approved replay">
<rect x="170" y="48" width="60" height="14" rx="3" class="c-mask"/>
<text x="200" y="58">approved replay</text>
</g>
`, 'showcase');
assert.equal(code, 0);
assert.equal(result.composition.metrics.labelCanvasOverflowIssues, 0);
});
// A foreign artifact may author a legal non-zero viewBox origin, so containment
// is measured against [min-x, min-x + width], not [0, width]: measuring from
// zero passed a label the canvas clips and rejected a contained one.
test('render output check: label containment respects a positive viewBox origin', () => {
const svgFor = (rect) => `
<path data-edge-key="0" data-edge-from="a" data-edge-to="b" data-composition-points="110,80;330,80" d="M 110 80 L 330 80" class="a-default" marker-end="url(#arrowhead)"/>
<g data-edge-key="0" data-edge-from="a" data-edge-to="b" data-edge-label="ship">
<rect x="${rect.x}" y="${rect.y}" width="${rect.width}" height="${rect.height}" rx="3" class="c-mask"/>
<text x="${rect.x + rect.width / 2}" y="${rect.y + 10}">ship</text>
</g>
`;
const contained = checkHtml('origin-positive-contained', svgFor({ x: 280, y: 48, width: 40, height: 14 }), 'showcase', '100 0 240 160');
assert.equal(contained.code, 0, JSON.stringify(contained.result.composition.issues));
assert.equal(contained.result.composition.metrics.labelCanvasOverflowIssues, 0);
const clipped = checkHtml('origin-positive-clipped', svgFor({ x: 80, y: 48, width: 60, height: 14 }), 'showcase', '100 0 240 160');
assert.notEqual(clipped.code, 0);
const issue = clipped.result.composition.issues.find((item) => item.code === 'composition/label-canvas-containment');
assert.deepEqual(issue.overflowPx, { left: 20 });
assert.deepEqual(issue.viewBoxOrigin, [100, 0]);
assert.match(issue.detail, /extends past the left edge by 20px \(label rect \[80, 48, 60, 14\]; viewBox 240x160 at 100,0\)/);
});
test('render output check: label containment respects a negative viewBox origin', () => {
const svgFor = (rect) => `
<path data-edge-key="0" data-edge-from="a" data-edge-to="b" data-composition-points="-40,80;170,80" d="M -40 80 L 170 80" class="a-default" marker-end="url(#arrowhead)"/>
<g data-edge-key="0" data-edge-from="a" data-edge-to="b" data-edge-label="ship">
<rect x="${rect.x}" y="${rect.y}" width="${rect.width}" height="${rect.height}" rx="3" class="c-mask"/>
<text x="${rect.x + rect.width / 2}" y="${rect.y + 10}">ship</text>
</g>
`;
const contained = checkHtml('origin-negative-contained', svgFor({ x: -50, y: -30, width: 40, height: 14 }), 'showcase', '-60 -40 240 160');
assert.equal(contained.code, 0, JSON.stringify(contained.result.composition.issues));
assert.equal(contained.result.composition.metrics.labelCanvasOverflowIssues, 0);
const clipped = checkHtml('origin-negative-clipped', svgFor({ x: 150, y: 48, width: 60, height: 14 }), 'showcase', '-60 -40 240 160');
assert.notEqual(clipped.code, 0);
const issue = clipped.result.composition.issues.find((item) => item.code === 'composition/label-canvas-containment');
assert.deepEqual(issue.overflowPx, { right: 30 });
assert.deepEqual(issue.viewBoxOrigin, [-60, -40]);
assert.match(issue.detail, /extends past the right edge by 30px \(label rect \[150, 48, 60, 14\]; viewBox 240x160 at -60,-40\)/);
});
test('render output check: repeated endpoint messages keep their own stable owner identity', () => {
const { code, result } = checkHtml('sequence-repeated-endpoints', `
<g data-edge-key="0" data-edge-from="client" data-edge-to="api" data-edge-label="first request">
<path data-composition-edge-from="client" data-composition-edge-to="api" data-composition-points="20,20;200,20" d="M 20 20 L 200 20" class="a-default" marker-end="url(#arrowhead)"/>
<g data-detail="context"><rect x="70" y="2" width="80" height="16" class="c-mask"/></g>
</g>
<g data-edge-key="1" data-edge-from="client" data-edge-to="api" data-edge-label="second request">
<path data-composition-edge-from="client" data-composition-edge-to="api" data-composition-points="20,60;200,60" d="M 20 60 L 200 60" class="a-default" marker-end="url(#arrowhead)"/>
<g data-detail="context"><rect x="70" y="72" width="80" height="16" class="c-mask"/></g>
</g>
<path data-edge-key="2" data-edge-from="worker" data-edge-to="store" data-composition-points="20,80;200,80" d="M 20 80 L 200 80" class="a-dashed" marker-end="url(#arrowhead-dashed)"/>
`, 'showcase');
assert.notEqual(code, 0);
const issues = result.composition.issues.filter((item) => item.code === 'composition/label-route-clearance');
assert.equal(issues.length, 1);
assert.equal(issues[0].label, 'second request');
assert.equal(issues[0].labelRelationship.collectionIndex, 1);
assert.equal(issues[0].otherRelationship.collectionIndex, 2);
});
test('render output check: duplicate fragments of the owning relationship stay exempt', () => {
const { code, result } = checkHtml('label-owner-fragments', `
<path data-edge-key="0" data-edge-id="approved" data-edge-from="dlq" data-edge-to="replay" data-composition-points="20,60;200,60" d="M 20 60 L 200 60" class="a-default" marker-end="url(#arrowhead)"/>
<path data-edge-key="0" data-edge-id="approved" data-edge-from="dlq" data-edge-to="replay" data-composition-points="20,60;200,60" d="M 20 60 L 200 60" class="a-default" marker-end="url(#arrowhead)"/>
<g data-detail="context" data-edge-key="0" data-edge-id="approved" data-edge-from="dlq" data-edge-to="replay" data-edge-label="approved replay">
<rect x="80" y="48" width="60" height="14" rx="3" class="c-mask"/>
<text x="110" y="58">approved replay</text>
</g>
`, 'showcase');
assert.equal(code, 0);
assert.equal(result.composition.metrics.labelRouteClearanceIssues, 0);
assert.equal(result.composition.metrics.minLabelRouteClearance, null);
});
test('render output check: duplicate fragments of another relationship count once', () => {
const { result } = checkHtml('label-other-fragments', `
<path data-edge-key="0" data-edge-id="approved" data-edge-from="dlq" data-edge-to="replay" data-composition-points="20,60;200,60" d="M 20 60 L 200 60" class="a-default" marker-end="url(#arrowhead)"/>
<path data-edge-key="1" data-edge-id="sample" data-edge-from="dlq" data-edge-to="ops" data-composition-points="70,55;150,55" d="M 70 55 L 150 55" class="a-dashed" marker-end="url(#arrowhead-dashed)"/>
<path data-edge-key="1" data-edge-id="sample" data-edge-from="dlq" data-edge-to="ops" data-composition-points="70,55;150,55" d="M 70 55 L 150 55" class="a-dashed" marker-end="url(#arrowhead-dashed)"/>
<g data-detail="context" data-edge-key="0" data-edge-id="approved" data-edge-from="dlq" data-edge-to="replay" data-edge-label="approved replay">
<rect x="80" y="48" width="60" height="14" rx="3" class="c-mask"/>
<text x="110" y="58">approved replay</text>
</g>
`, 'showcase');
assert.equal(result.composition.metrics.labelRouteClearanceIssues, 1);
});
test('render output check: label-route thresholds include exact 2px and 4px boundaries', () => {
const body = (otherY) => `
<path data-edge-key="0" data-edge-from="a" data-edge-to="b" data-composition-points="20,70;200,70" d="M 20 70 L 200 70" class="a-default" marker-end="url(#arrowhead)"/>
<path data-edge-key="1" data-edge-from="c" data-edge-to="d" data-composition-points="70,${otherY};150,${otherY}" d="M 70 ${otherY} L 150 ${otherY}" class="a-dashed" marker-end="url(#arrowhead-dashed)"/>
<g data-detail="context" data-edge-key="0" data-edge-from="a" data-edge-to="b" data-edge-label="handoff">
<rect x="80" y="48" width="60" height="14" rx="3" class="c-mask"/>
<text x="110" y="58">handoff</text>
</g>
`;
const standardAtTwo = checkHtml('label-standard-two', body(64), 'standard');
assert.equal(standardAtTwo.code, 0);
assert.equal(standardAtTwo.result.composition.metrics.labelRouteClearanceIssues, 0);
assert.equal(standardAtTwo.result.composition.metrics.minLabelRouteClearance, 2);
const standardBelowTwo = checkHtml('label-standard-one-nine', body(63.9), 'standard');
assert.equal(standardBelowTwo.code, 0);
assert.equal(standardBelowTwo.result.composition.metrics.labelRouteClearanceIssues, 1);
assert.equal(standardBelowTwo.result.composition.summary.warnings, 1);
const showcaseAtTwo = checkHtml('label-showcase-two', body(64), 'showcase');
assert.notEqual(showcaseAtTwo.code, 0);
assert.equal(showcaseAtTwo.result.composition.metrics.labelRouteClearanceIssues, 1);
assert.equal(showcaseAtTwo.result.composition.issues.find((item) => item.code === 'composition/label-route-clearance').threshold, 4);
const showcaseAtFour = checkHtml('label-showcase-four', body(66), 'showcase');
assert.equal(showcaseAtFour.code, 0);
assert.equal(showcaseAtFour.result.composition.metrics.labelRouteClearanceIssues, 0);
assert.equal(showcaseAtFour.result.composition.metrics.minLabelRouteClearance, 4);
const showcaseBelowFour = checkHtml('label-showcase-three-nine', body(65.9), 'showcase');
assert.notEqual(showcaseBelowFour.code, 0);
assert.equal(showcaseBelowFour.result.composition.metrics.labelRouteClearanceIssues, 1);
assert.equal(showcaseBelowFour.result.composition.summary.errors, 1);
});
function automaticArrow(id, from, to, points, width = 1.5) {
const d = points.map(([x, y], index) => `${index ? 'L' : 'M'} ${x} ${y}`).join(' ');
return `<path data-graph-role="automatic-crossover-underlay" d="${d}" fill="none" stroke="var(--mask)" stroke-width="${width + 4}" pointer-events="none"/>
<path data-edge-id="${id}" data-edge-from="${from}" data-edge-to="${to}" data-composition-points="${points.map((point) => point.join(',')).join(';')}" data-composition-crossover="halo" data-composition-independent="true" d="${d}" class="a-default" stroke-width="${width}" marker-end="url(#arrowhead)"/>`;
}
function automaticWorkflowArrow(id, from, to, points) {
const d = points.map(([x, y], index) => `${index ? 'L' : 'M'} ${x} ${y}`).join(' ');
return `<path data-edge-id="${id}" data-edge-from="${from}" data-edge-to="${to}" data-composition-routing="workflow-v2-auto" data-composition-points="${points.map((point) => point.join(',')).join(';')}" d="${d}" class="a-default" marker-end="url(#arrowhead)"/>`;
}
test('render output check: automatic workflow counterflow warns in standard and fails showcase without a halo', () => {
const markup = automaticWorkflowArrow('admission', 'a', 'hub', [[60, 20], [60, 100]])
+ automaticWorkflowArrow('dispatch', 'hub', 'b', [[60, 100], [60, 49], [140, 49]]);
for (const profile of ['standard', 'showcase']) {
const { code, result } = checkHtml(`workflow-counterflow-${profile}`, markup, profile);
assert.equal(code, profile === 'showcase' ? 1 : 0);
const issue = result.composition.issues.find((entry) => entry.code === 'composition/ambiguous-corridor');
assert.equal(issue?.severity, profile === 'showcase' ? 'error' : 'warning');
assert.equal(issue?.overlapLength, 51);
assert.deepEqual([issue?.relationship.id, issue?.otherRelationship.id], ['admission', 'dispatch']);
assert.deepEqual(result.composition.summary, profile === 'showcase'
? { errors: 1, warnings: 0 } : { errors: 0, warnings: 1 });
}
for (const preserved of [
markup.replaceAll(' data-composition-routing="workflow-v2-auto"', ''),
markup.replace(' data-composition-routing="workflow-v2-auto"', ''),
markup.replaceAll('workflow-v2-auto', 'workflow-v1'),
]) {
const { code, result } = checkHtml('workflow-authored-counterflow', preserved, 'showcase');
assert.equal(code, 0, JSON.stringify(result));
assert.equal(result.composition.metrics.ambiguousCorridors, 0);
}
const sharedTrunk = automaticWorkflowArrow('first', 'hub', 'a', [[60, 20], [60, 100]])
+ automaticWorkflowArrow('second', 'hub', 'b', [[60, 20], [60, 70], [140, 70]]);
const sameDirection = checkHtml('workflow-shared-trunk', sharedTrunk, 'showcase');
assert.equal(sameDirection.code, 0, JSON.stringify(sameDirection.result));
assert.equal(sameDirection.result.composition.metrics.ambiguousCorridors, 0);
});
test('render output check: automatic workflow shared-endpoint X is checked independently of halo claims', () => {
const markup = automaticWorkflowArrow('first', 'a', 'hub', [[20, 20], [80, 20], [80, 80], [140, 80]])
+ automaticWorkflowArrow('second', 'b', 'hub', [[20, 100], [120, 100], [120, 40], [140, 40]]);
for (const profile of ['standard', 'showcase']) {
const { code, result } = checkHtml(`workflow-shared-crossing-${profile}`, markup, profile);
assert.equal(code, profile === 'showcase' ? 1 : 0);
assert.equal(result.composition.metrics.properCrossings, 1);
assert.equal(result.composition.metrics.resolvedCrossovers, 0);
const issue = result.composition.issues.find((entry) => entry.code === 'composition/proper-crossing');
assert.equal(issue?.severity, profile === 'showcase' ? 'error' : 'warning');
assert.deepEqual(issue?.point, [120, 80]);
}
const mixed = checkHtml('workflow-mixed-shared-crossing', markup.replace(' data-composition-routing="workflow-v2-auto"', ''), 'showcase');
assert.equal(mixed.code, 0, JSON.stringify(mixed.result));
const falseHalo = markup.replaceAll('data-composition-routing=', 'data-composition-crossover="halo" data-composition-independent="true" data-composition-routing=');
const forged = checkHtml('workflow-false-halo', falseHalo, 'showcase');
assert.equal(forged.code, 1, 'routing provenance cannot certify an absent crossover halo');
assert.equal(forged.result.composition.metrics.properCrossings, 1);
assert.equal(forged.result.composition.metrics.resolvedCrossovers, 0);
const unrelated = markup.replace('data-edge-to="hub"', 'data-edge-to="other"');
const marked = checkHtml('workflow-marked-unrelated-crossing', unrelated, 'showcase');
const unmarked = checkHtml('workflow-unmarked-unrelated-crossing', unrelated.replaceAll(' data-composition-routing="workflow-v2-auto"', ''), 'showcase');
assert.equal(marked.code, 1);
assert.equal(unmarked.code, 1, 'an automatic marker only tightens existing crossing acceptance');
});
test('render output check: independent shared-endpoint crossings still recommend visual review', () => {
const markup = automaticArrow('first', 'a', 'hub', [[20, 20], [80, 20], [80, 80], [140, 80]])
+ automaticArrow('second', 'b', 'hub', [[20, 100], [120, 100], [120, 40], [140, 40]]);
const { code, result } = checkHtml('independent-shared-crossing', markup, 'showcase');
assert.equal(code, 0, JSON.stringify(result));
assert.equal(result.composition.metrics.resolvedCrossovers, 1);
assert.equal(result.composition.metrics.properCrossings, 0);
assert.equal(result.composition.metrics.routesOverSuggestedBends, 0);
assert.equal(result.composition.metrics.routesOverSuggestedStretch, 0);
const summary = compactFinalizeReceipt({ ok: true, stages: { check: { receipt: result } } });
assert.deepEqual(summary.visualReviewRecommendation.signals, { resolvedCrossovers: 1 });
const affected = summary.visualReviewRecommendation.affectedRoutes;
assert.equal(affected.crossings.length, 1);
assert.equal(affected.crossings[0].left.id, 'first');
assert.equal(affected.crossings[0].right.id, 'second');
assert.deepEqual(affected.crossings[0].point, [120, 80]);
assert.equal(affected.crossings[0].sharedNode, 'hub');
assert.match(summary.visualReviewRecommendation.hints[0], /move node a or b so the two reach hub from different sides/);
assert.deepEqual(affected.detours, []);
assert.equal(affected.truncated, false);
assert.equal(summary.visualReview, 'not-requested');
// A legacy/authored shared junction must keep its existing interpretation.
for (const preserved of [
markup.replaceAll(' data-composition-independent="true"', ''),
markup.replace(' data-composition-independent="true"', ''),
]) {
const legacy = checkHtml('legacy-shared-crossing', preserved, 'showcase');
assert.equal(legacy.code, 0, JSON.stringify(legacy.result));
assert.equal(legacy.result.composition.metrics.resolvedCrossovers, 0);
}
});
test('render output check: automatic shared destinations do not excuse long merged corridors', () => {
const markup = automaticArrow('first', 'a', 'hub', [[20, 20], [100, 20], [100, 140]])
+ automaticArrow('second', 'b', 'hub', [[180, 60], [100, 60], [100, 120], [140, 120], [140, 140]]);
const { code, result } = checkHtml('automatic-shared-corridor', markup, 'showcase');
assert.equal(code, 1);
const issue = result.composition.issues.find((entry) => entry.code === 'composition/ambiguous-corridor');
assert.equal(issue?.overlapLength, 60);
// Explicit junctions retain their historical compatibility contract.
const authored = checkHtml('authored-shared-corridor', markup.replaceAll('data-composition-crossover="halo"', ''), 'showcase');
assert.equal(authored.code, 0, JSON.stringify(authored.result));
});
test('render output check: incoming automatic markers must fit their actual stroke width', () => {
for (const [spacing, width, collision] of [[7, 1.5, true], [14, 1.5, false], [14, 4, true], [32, 4, false]]) {
const markup = automaticArrow('first', 'a', 'hub', [[100, 40], [100, 120]], width)
+ automaticArrow('second', 'b', 'hub', [[100 + spacing, 40], [100 + spacing, 120]], width);
const { code, result } = checkHtml(`markers-${spacing}-${width}`, markup, 'showcase');
assert.equal(code, collision ? 1 : 0, JSON.stringify(result));
const issue = result.composition.issues.find((entry) => entry.code === 'composition/arrowhead-collision');
assert.equal(Boolean(issue), collision);
if (issue) {
assert.equal(issue.distancePx, spacing);
assert.equal(issue.minimumPx, width * 7);
}
}
});
test('render output check: unrelated shared corridors warn in standard and fail showcase', () => {
for (const profile of ['standard', 'showcase']) {
const { code, result } = checkHtml(`corridor-${profile}`, `
<path data-edge-id="first" data-edge-from="a" data-edge-to="b" data-composition-points="20,60;140,60;140,100" d="M 20 60 L 140 60 L 140 100" class="a-default" marker-end="url(#arrowhead)"/>
<path data-edge-id="second" data-edge-from="c" data-edge-to="d" data-composition-points="60,60;180,60;180,100" d="M 60 60 L 180 60 L 180 100" class="a-dashed" marker-end="url(#arrowhead-dashed)"/>
`, profile);
assert.equal(result.composition.metrics.ambiguousCorridors, 1);
assert.equal(result.composition.issues[0].code, 'composition/ambiguous-corridor');
assert.equal(result.composition.issues[0].overlapLength, 80);
assert.deepEqual(result.composition.issues[0].from, [60, 60]);
assert.deepEqual(result.composition.issues[0].to, [140, 60]);
const check = result.checks.find((item) => item.name === 'relationship_corridors');
if (profile === 'standard') {
assert.equal(code, 0);
assert.equal(check.ok, true);
assert.deepEqual(result.composition.summary, { errors: 0, warnings: 1 });
assert.equal(result.composition.issues[0].severity, 'warning');
} else {
assert.notEqual(code, 0);
assert.equal(check.ok, false);
assert.match(check.details[0], /\[composition\/ambiguous-corridor\] showcase/);
assert.match(check.details[0], /relationship id "first".*relationship id "second"/);
assert.deepEqual(result.composition.summary, { errors: 1, warnings: 0 });
assert.equal(result.composition.issues[0].severity, 'error');
}
}
});
test('render output check: visible quadratic crossing is caught in showcase', () => {
const { code, result } = checkHtml('showcase-quadratic-crossing', `
<path data-edge-from="a" data-edge-to="b" d="M 20 90 Q 100 10 180 90" class="a-default" marker-end="url(#arrowhead)"/>
<path data-edge-from="c" data-edge-to="d" d="M 103 20 L 103 120" class="a-dashed" marker-end="url(#arrowhead-dashed)"/>
`, 'showcase');
assert.notEqual(code, 0);
assert.equal(result.composition.metrics.properCrossings, 1);
assert.equal(result.composition.status, 'fail');
});
test('render output check: container border runs fail both profiles with frame identity', () => {
for (const profile of ['standard', 'showcase']) {
const { code, result } = checkHtml(`border-run-${profile}`, `
<rect data-composition-frame-kind="stage" data-composition-frame-id="sources" x="40" y="40" width="160" height="80" rx="10"/>
<path data-edge-id="events" data-edge-from="web" data-edge-to="edge" data-composition-points="60,40;150,40" d="M 60 40 L 150 40" class="a-default" marker-end="url(#arrowhead)"/>
`, profile);
assert.notEqual(code, 0);
const check = result.checks.find((item) => item.name === 'container_border_runs');
assert.equal(check.ok, false);
assert.match(check.details[0], /\[composition\/container-border-run\].*relationship id "events"/);
assert.match(check.details[0], /stage "sources" top border for 90px/);
assert.equal(result.composition.summary.errors, 1);
assert.equal(result.composition.metrics.containerBorderRuns, 1);
assert.equal(result.composition.issues[0].code, 'composition/container-border-run');
}
});
test('render output check: perpendicular crossings, rounded-corner touches, and tangent Q curves pass', () => {
const { code, result } = checkHtml('border-run-exemptions', `
<rect data-composition-frame-kind="group" data-composition-frame-id="safe" x="40" y="40" width="160" height="80" rx="10"/>
<path data-edge-from="a" data-edge-to="b" d="M 100 10 L 100 80" class="a-default" marker-end="url(#arrowhead)"/>
<path data-edge-from="c" data-edge-to="d" d="M 40 40 L 49 40" class="a-default" marker-end="url(#arrowhead)"/>
<path data-edge-from="e" data-edge-to="f" d="M 20 70 Q 40 40 60 40" class="a-default" marker-end="url(#arrowhead)"/>
`, 'showcase');
assert.equal(code, 0);
assert.equal(result.composition.metrics.containerBorderRuns, 0);
});
test('render output check: a fully collinear quadratic primitive is a border run', () => {
const { code, result } = checkHtml('border-run-collinear-q', `
<rect data-composition-frame-kind="segment" data-composition-frame-id="retry" x="40" y="40" width="160" height="80" rx="10"/>
<path data-edge-from="a" data-edge-to="b" d="M 60 40 Q 100 40 140 40" class="a-default" marker-end="url(#arrowhead)"/>
`);
assert.notEqual(code, 0);
assert.equal(result.composition.metrics.containerBorderRuns, 1);
});
test('render output check: composition receipt records neutral normalized route metrics', () => {
const { code, result } = checkHtml('route-metrics', `
<path data-edge-from="a" data-edge-to="b" data-composition-points="0,20;10,20;30,20;30,28;50,28;50,50" d="M 0 20 L 30 20 L 30 28 L 50 28 L 50 50" class="a-default" marker-end="url(#arrowhead)"/>
`);
assert.equal(code, 0);
assert.equal(result.composition.metrics.maxBends, 3);
assert.equal(result.composition.metrics.routesOverSuggestedBends, 1);
assert.equal(result.composition.metrics.minSegmentPx, 8);
assert.equal(result.composition.metrics.shortSegmentCount, 1);
assert.equal(result.composition.metrics.shortInteriorSegmentCount, 1);
assert.equal(result.composition.metrics.shortEndpointSegmentCount, 0);
assert.equal(result.composition.metrics.microSegmentCount, 0);
assert.deepEqual(result.composition.suggestedLimits, { bendsPerRelationship: 2, stretch: 1.35, segmentPx: 16, microSegmentPx: 8 });
});
test('render output check: detours identify intervening nodes without failing valid routing', () => {
for (const vertical of [false, true]) {
const point = (x, y) => vertical ? [y, x] : [x, y];
const rect = (id, x, y, extra = '') => {
const [left, top] = point(x, y);
return `<g data-node-id="${id}" data-node-label="${id} role" ${extra}><rect class="c-mask" x="${left}" y="${top}" width="40" height="40"/></g>`;
};
const points = [[50, 70], [70, 70], [70, 20], [190, 20], [190, 70], [210, 70]].map(([x, y]) => point(x, y));
const edge = `<path data-edge-from="a" data-edge-to="b" data-composition-points="${points.map(p => p.join(',')).join(';')}" d="M ${points.map(p => p.join(' ')).join(' L ')}" class="a-default" marker-end="url(#arrowhead)"/>`;
const endpoints = rect('a', 10, 50) + rect('b', 210, 50);
const { code, result } = checkHtml(`blocked-direct-${vertical}`, endpoints + rect('blocker', 110, 50) + rect('off-row', 110, 100) + edge, 'showcase', '0 0 560 280');
assert.equal(code, 0, 'a legal route around an intervening node is still valid');
assert.deepEqual(result.composition.summary, { errors: 0, warnings: 0 });
assert.deepEqual(result.composition.routeReview.detours[0].directCorridorBlockers, [{
id: 'blocker', label: 'blocker role', box: [...point(110, 50), 40, 40],
}]);
const transformed = checkHtml(`transformed-blocker-${vertical}`, endpoints + `<g transform="translate(100 100)">${rect('blocker', 110, 50)}</g>` + edge, 'showcase', '0 0 560 280');
assert.equal(transformed.result.composition.routeReview.detours[0].directCorridorBlockers, undefined, 'unresolved coordinate spaces are not guessed');
const offset = checkHtml(`offset-endpoints-${vertical}`, rect('a', 10, 40) + rect('b', 210, 50) + rect('blocker', 110, 50) + edge, 'showcase', '0 0 560 280');
assert.equal(offset.result.composition.routeReview.detours[0].directCorridorBlockers, undefined, 'different rows have no single direct corridor');
}
});
test('render output check: endpoint stubs from 8px pass while cramped interior turns are profile-aware', () => {
const clean = checkHtml('endpoint-stubs', `
<path data-edge-id="lane-hop" data-edge-from="a" data-edge-to="b" data-composition-points="0,20;13,20;13,60;80,60;80,73" d="M 0 20 L 13 20 L 13 60 L 80 60 L 80 73" class="a-default" marker-end="url(#arrowhead)"/>
`, 'showcase');
assert.equal(clean.code, 0);
assert.equal(clean.result.composition.metrics.shortEndpointSegmentCount, 2);
assert.equal(clean.result.composition.metrics.shortInteriorSegmentCount, 0);
const standard = checkHtml('short-turn-standard', `
<path data-edge-id="tight" data-edge-from="a" data-edge-to="b" data-composition-points="0,20;24,20;24,29;80,29" d="M 0 20 L 24 20 L 24 29 L 80 29" class="a-default" marker-end="url(#arrowhead)"/>
`, 'standard');
assert.equal(standard.code, 0);
assert.deepEqual(standard.result.composition.summary, { errors: 0, warnings: 1 });
assert.equal(standard.result.composition.issues[0].code, 'composition/short-interior-segment');
assert.equal(standard.result.checks.find((item) => item.name === 'route_rhythm').ok, true);
const showcase = checkHtml('short-turn-showcase', `
<path data-edge-id="tight" data-edge-from="a" data-edge-to="b" data-composition-points="0,20;24,20;24,29;80,29" d="M 0 20 L 24 20 L 24 29 L 80 29" class="a-default" marker-end="url(#arrowhead)"/>
`, 'showcase');
assert.notEqual(showcase.code, 0);
assert.deepEqual(showcase.result.composition.summary, { errors: 1, warnings: 0 });
const rhythm = showcase.result.checks.find((item) => item.name === 'route_rhythm');
assert.equal(rhythm.ok, false);
assert.match(rhythm.details[0], /\[composition\/short-interior-segment\] showcase relationship id "tight"/);
});
process.on('exit', () => fs.rmSync(tmp, { recursive: true, force: true }));
test('readability node ownership survives nested groups and does not leak after closing', () => {
const nested = checkHtml('nested-owner', `
<g data-node-id="outer"><g/><g><text data-detail="context" font-size="7">Repeated</text></g></g>
`, 'showcase', '0 0 1200 400');
assert.equal(nested.result.composition.issues[0].nodeId, 'outer');
const loose = checkHtml('closed-owner', `
<g data-node-id="outer"><g><text data-node-label font-size="12">Readable</text></g></g>
<text data-boundary-label font-size="7">Repeated</text>
`, 'showcase', '0 0 1200 400');
assert.equal(loose.result.composition.issues[0].nodeId, undefined);
});
for (const position of ['before', 'after']) {
test(`render output check: finite_svg ignores HTML numeric attributes ${position} SVG`, () => {
const htmlPath = path.join(tmp, `finite-html-${position}.html`);
const html = '<div x="NaN" width="Infinity"><input width="NaN"><br></div>';
const svg = '<svg viewBox="0 0 240 160"><rect x="10" y="10" width="20" height="20"/></svg>';
fs.writeFileSync(htmlPath, `<!doctype html><html><body>${position === 'before' ? html + svg : svg + html}</body></html>`);
const result = JSON.parse(execFileSync('node', [checker, htmlPath], { encoding: 'utf8' }));
const check = result.checks.find(item => item.name === 'finite_svg');
assert.equal(check.ok, true);
assert.deepEqual(check.details, []);
});
}
test('render output check: finite_svg ignores comments and CDATA but still checks real elements', () => {
const { result } = checkHtml('finite-non-elements', `
<!-- <rect x="NaN"/> -->
<![CDATA[<path d="Infinity"/>]]>
<rect x="12" y="20" width="50" height="40"/>
<circle cx="NaN" cy="20" r="5"/>
`);
const check = result.checks.find(item => item.name === 'finite_svg');
assert.equal(check.ok, false);
assert.deepEqual(check.details, ['circle cx="NaN"']);
});
test('render output check: finite_svg decodes numeric references once and reports raw evidence', () => {
const { result } = checkHtml('finite-encoded-values', `
<rect x="NaN" y="Infinity"/>
<circle cx="ӪN" cy="&#78;aN" r="10"/>
<path d="M 0 0 L NaN 12"/>
<text x="10" y="10" data-note="NaN">NaN</text>
`);
const check = result.checks.find(item => item.name === 'finite_svg');
assert.equal(check.ok, false);
assert.deepEqual(check.details, [
'rect x="NaN"',
'rect y="Infinity"',
'path d="M 0 0 L NaN 12"',
]);
});
test('render output check: finite_svg separates foreignObject HTML from SVG geometry', () => {
const { result } = checkHtml('finite-foreign-object', `
<foreignObject x="NaN" y="0" width="100" height="100">
<div xmlns="http://www.w3.org/1999/xhtml" x="NaN" width="Infinity">
<input width="NaN"><br><div y="Infinity">HTML content</div>
</div>
</foreignObject>
<rect x="Infinity"/>
`);
const check = result.checks.find(item => item.name === 'finite_svg');
assert.equal(check.ok, false);
assert.deepEqual(check.details, ['foreignObject x="NaN"', 'rect x="Infinity"']);
const nested = checkHtml('finite-foreign-nested-svg', `
<foreignObject><div x="NaN"><svg><rect x="NaN"/></svg></div></foreignObject>
`).result.checks.find(item => item.name === 'finite_svg');
assert.deepEqual(nested.details, ['rect x="NaN"']);
});
test('render output check: finite_svg ignores prose that mentions NaN or Infinity', () => {
const { result } = checkHtml('finite-prose', `
<g data-node-id="solver" data-node-tag="returns a NaN leaf" aria-label="Focus Solver">
<title>Solver · returns a NaN leaf · Infinity guard</title>
<rect x="40" y="40" width="200" height="74" rx="6" class="c-mask"/>
<text x="140" y="70" class="t-primary" font-size="11" text-anchor="middle">Solver</text>
<text data-detail="fine" x="140" y="106" class="t-backend" font-size="7">returns a NaN leaf</text>
</g>
<!-- Legend -->
<text x="40" y="140" class="t-primary" font-size="10">Legend</text>
`);
const check = result.checks.find((item) => item.name === 'finite_svg');
assert.equal(check.ok, true);
assert.deepEqual(check.details, []);
});
test('render output check: finite_svg reports the attribute carrying a non-finite value', () => {
const { code, result } = checkHtml('finite-attr', `
<rect x="NaN" y="40" width="200" height="74" rx="6" class="c-mask"/>
<path d="M 20 20 L undefined 20" class="a-default" stroke-width="1.4"/>
<text x="140" y="Infinity" class="t-primary" font-size="11">Solver</text>
<!-- Legend -->
<text x="40" y="140" class="t-primary" font-size="10">Legend</text>
`);
assert.notEqual(code, 0);
const check = result.checks.find((item) => item.name === 'finite_svg');
assert.equal(check.ok, false);
assert.deepEqual(check.details, [
'rect x="NaN"',
'path d="M 20 20 L undefined 20"',
'text y="Infinity"',
]);
});
test('render output check: finite_svg parses quoted angle brackets and HTML attribute quoting', () => {
const { code, result } = checkHtml('finite-attr-syntax', `
<rect aria-label="greater > lesser" x="NaN" y="40" width="200" height="74"/>
<circle cx='Infinity' cy='40' r='6'/>
<line x1=undefined y1=10 x2=20 y2=10/>
`);
assert.notEqual(code, 0);
const check = result.checks.find((item) => item.name === 'finite_svg');
assert.equal(check.ok, false);
assert.deepEqual(check.details, [
'rect x="NaN"',
'circle cx="Infinity"',
'line x1="undefined"',
]);
});
test('render output check: finite_svg covers extended SVG numeric attributes', () => {
const { code, result } = checkHtml('finite-extended-attrs', `
<path d="M 0 0 L 10 0" pathLength="NaN"/>
<radialGradient fr="-Infinity"/>
<feGaussianBlur stdDeviation="undefined"/>
`);
assert.notEqual(code, 0);
const check = result.checks.find((item) => item.name === 'finite_svg');
assert.equal(check.ok, false);
assert.deepEqual(check.details, [
'path pathLength="NaN"',
'radialGradient fr="-Infinity"',
'feGaussianBlur stdDeviation="undefined"',
]);
});
test('render output check: finite_svg covers element-specific filter numeric attributes', () => {
const { code, result } = checkHtml('finite-element-specific-filter-attrs', `
<filter id="lighting">
<feDiffuseLighting><fePointLight x="10" y="10" z="NaN"/></feDiffuseLighting>
<feSpecularLighting><feSpotLight x="10" y="10" z="-Infinity"/></feSpecularLighting>
<feColorMatrix type="saturate" values="undefined"/>
</filter>
`);
assert.notEqual(code, 0);
const check = result.checks.find((item) => item.name === 'finite_svg');
assert.equal(check.ok, false);
assert.deepEqual(check.details, [
'fePointLight z="NaN"',
'feSpotLight z="-Infinity"',
'feColorMatrix values="undefined"',
]);
});
test('render output check: finite_svg keeps context-sensitive values attributes scoped', () => {
const { code, result } = checkHtml('finite-context-sensitive-values', `
<animate attributeName="data-node-tag" values="NaN;Infinity" dur="1s"/>
`);
assert.equal(code, 0);
const check = result.checks.find((item) => item.name === 'finite_svg');
assert.equal(check.ok, true);
assert.deepEqual(check.details, []);
});
for (const [name, markup] of [
['comment-open', '<!-- <g data-node-id="other"> -->'],
['comment-close', '<!-- </g> -->'],
['cdata', '<![CDATA[<g data-node-id="other"></g></g>]]>'],
]) {
test(`readability node ownership ignores ${name}`, () => {
const { result } = checkHtml(`owner-${name}`, `
<g data-node-id="actual">${markup}<text data-detail="context" font-size="7">Repeated</text></g>
`, 'showcase', '0 0 1200 400');
const issue = result.composition.issues.find(item => item.code === 'composition/desktop-readability');
assert.equal(issue.nodeId, 'actual');
assert.equal(issue.text, 'Repeated');
assert.equal(issue.projectedFontPx, 5.425);
});
}