Skip to content

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

fix(architecture): preserve authored canvas scale through delivery checks

tt-a1ic61f62e7585e
diff --git a/archify/bin/archify.mjs b/archify/bin/archify.mjs
index 11ac64ba..ac785d62 100755
--- a/archify/bin/archify.mjs
+++ b/archify/bin/archify.mjs
@@ -4861,6 +4861,9 @@ async function commandDeliver(args) {
...(engineeringProfile ? { engineeringProfile } : {}),
errors: result.composition.summary.errors,
warnings: result.composition.summary.warnings,
+ ...(result.composition.summary.warnings ? {
+ compositionIssues: result.composition.issues.filter((issue) => issue.severity === 'warning'),
+ } : {}),
},
...(sourceEvidence ? {
evidence: {
diff --git a/archify/bin/finalize.mjs b/archify/bin/finalize.mjs
index 88620a9f..9ab078f5 100644
--- a/archify/bin/finalize.mjs
+++ b/archify/bin/finalize.mjs
@@ -159,7 +159,7 @@ function validBrowserEvidence(receipt) {
&& entry.resolvedTheme === expected.theme);
}
-function validDeliveryValidation(receipt, quality) {
+function validDeliveryValidation(receipt, quality, { allowShowcaseWarnings = false } = {}) {
const validation = receipt?.validation;
return isReceiptObject(validation)
&& Number.isInteger(validation.checkCount)
@@ -168,10 +168,10 @@ function validDeliveryValidation(receipt, quality) {
&& validation.compositionStatus === 'pass'
&& validation.errors === 0
&& validation.compositionProfile === quality
- && (quality !== 'showcase' || validation.warnings === 0);
+ && (quality !== 'showcase' || allowShowcaseWarnings || validation.warnings === 0);
}
-function validStageReceipt(stage, receipt, quality) {
+function validStageReceipt(stage, receipt, quality, options) {
if (!isReceiptObject(receipt) || receipt.ok !== true) return false;
if (receipt.status && receipt.status !== 'pass') return false;
if (stage === 'validate') return receipt.command === 'validate' && Array.isArray(receipt.checks);
@@ -182,7 +182,7 @@ function validStageReceipt(stage, receipt, quality) {
&& isReceiptObject(receipt.specification)
&& validIdentity(receipt.specification)
&& validIdentity(receipt.artifact)
- && validDeliveryValidation(receipt, quality);
+ && validDeliveryValidation(receipt, quality, options);
}
if (stage === 'check') {
return validIdentity(receipt.artifact)
@@ -221,6 +221,35 @@ function identityMismatchDiagnostic({ stage, expected, actual, expectedReceiptId
};
}
+function showcaseWarningDiagnostics(receipt) {
+ const issues = receipt.validation.compositionIssues;
+ const warnings = receipt.validation.warnings;
+ if (!Array.isArray(issues) || issues.length !== warnings
+ || !issues.every((issue) => isReceiptObject(issue)
+ && issue.severity === 'warning'
+ && typeof issue.code === 'string'
+ && issue.code.startsWith('composition/')
+ && typeof issue.detail === 'string' && issue.detail.trim())) {
+ return [{
+ code: 'finalize/showcase-warnings', severity: 'error',
+ message: `Showcase delivery reported ${warnings} composition warning(s), but did not provide matching issue details.`,
+ subject: { stage: 'deliver', check: 'composition' },
+ evidence: { warnings, reportedIssues: Array.isArray(issues) ? issues.length : null },
+ supportedFixes: ['run validate on the frozen candidate to inspect the composition warnings, repair them, then rerun finalize'],
+ }];
+ }
+ return issues.map((issue) => {
+ const { code, severity, detail, ...evidence } = issue;
+ return {
+ code, severity: 'error',
+ message: `Showcase delivery reported ${code}; zero warnings are required.`,
+ subject: { stage: 'deliver', check: 'composition', ...(issue.nodeId ? { nodeId: issue.nodeId } : {}) },
+ evidence: { reportedSeverity: severity, ...evidence },
+ supportedFixes: [detail.replace(/^\[[^\]]+\]\s*/, '')],
+ };
+ });
+}
+
function stageBindingDiagnostic({ stage, receipt, expectedArtifact, expectedReceiptId, output, specification, type, deliveryValidation }) {
if (stage === 'deliver') {
if (receipt.type !== type) {
@@ -689,6 +718,14 @@ export async function runFinalize({
deliveryValidation: deliveryReceipt?.validation,
});
if (bindingDiagnostic) stageDiagnostics = [bindingDiagnostic];
+ } else if (stage === 'deliver' && code === 0 && quality === 'showcase'
+ && Number.isSafeInteger(stageReceipt?.validation?.warnings)
+ && stageReceipt.validation.warnings > 0
+ && validStageReceipt(stage, stageReceipt, quality, { allowShowcaseWarnings: true })) {
+ const bindingDiagnostic = stageBindingDiagnostic({
+ stage, receipt: stageReceipt, output: resolvedOutput, specification, type,
+ });
+ stageDiagnostics = bindingDiagnostic ? [bindingDiagnostic] : showcaseWarningDiagnostics(stageReceipt);
}
if (stageDiagnostics) {
status = 'fail';
diff --git a/archify/bin/visual-check.mjs b/archify/bin/visual-check.mjs
index a6391602..18b90e26 100644
--- a/archify/bin/visual-check.mjs
+++ b/archify/bin/visual-check.mjs
@@ -1740,6 +1740,16 @@ export class ChromeVisualBrowser {
cardsPx: Math.round(outerHeight(reader && reader.querySelector('.cards'))),
viewBoxHeight: viewBox ? viewBox.height : 0
};
+ var svgRect = svg && svg.getBoundingClientRect();
+ var diagramRect = diagram && diagram.getBoundingClientRect();
+ var documentScrollUnclipped = Boolean(svgRect && diagramRect
+ && svgRect.top >= diagramRect.top - 1 && svgRect.left >= diagramRect.left - 1
+ && svgRect.bottom <= diagramRect.bottom + 1 && svgRect.right <= diagramRect.right + 1
+ && diagram.scrollHeight <= diagram.clientHeight + 1
+ && diagram.scrollWidth <= diagram.clientWidth + 1
+ && [document.documentElement, document.body].every(function (element) {
+ return !['hidden', 'clip'].includes(window.getComputedStyle(element).overflowY);
+ }));
return {
pageComposition: pageComposition,
innerWidth: window.innerWidth,
@@ -1750,6 +1760,8 @@ export class ChromeVisualBrowser {
readerLayout: document.documentElement.getAttribute('data-reader-layout') || null,
readerOverflow: document.documentElement.getAttribute('data-reader-overflow') || null,
readerFit: svg ? svg.getAttribute('data-reader-fit') : null,
+ diagramType: svg ? svg.getAttribute('data-diagram-type') : null,
+ documentScrollUnclipped: documentScrollUnclipped,
readerWidth: reader ? reader.getBoundingClientRect().width : 0,
diagramWidth: diagramWidth,
viewBoxWidth: viewBoxWidth,
@@ -1860,11 +1872,13 @@ function observation({ width, height, theme, metrics }) {
&& !overflowX
&& readabilityOk
&& Number.isFinite(minimumProjectedNodeTextPx)
- && readerLayout === 'adaptive'
- && readerOverflow === 'authored'
- && readerFit === 'intrinsic-height'
+ && ((readerLayout === 'adaptive' && readerOverflow === 'authored' && readerFit === 'intrinsic-height')
+ || (readerFit === 'authored-height' && metrics.diagramType === 'architecture'
+ && metrics.documentScrollUnclipped === true))
);
- const containmentOk = !overflowX && (!overflowY || verticalScrollAccepted);
+ const authoredClipped = readerFit === 'authored-height' && metrics.diagramType === 'architecture'
+ && metrics.documentScrollUnclipped !== true;
+ const containmentOk = !authoredClipped && !overflowX && (!overflowY || verticalScrollAccepted);
const legendDockIntersectionArea = Number(metrics.legendDockIntersectionArea) || 0;
const dockStageIntersectionArea = Number(metrics.dockStageIntersectionArea) || 0;
const dockStageGap = metrics.dockStageGap == null ? null : Number(metrics.dockStageGap);
@@ -1889,12 +1903,13 @@ function observation({ width, height, theme, metrics }) {
overflowX,
overflowY,
verticalScrollAccepted,
- overflowDisposition: overflowX || (overflowY && !verticalScrollAccepted)
+ overflowDisposition: authoredClipped || overflowX || (overflowY && !verticalScrollAccepted)
? 'unexpected-overflow'
: verticalScrollAccepted ? 'readable-vertical-scroll' : 'contained',
readerLayout,
readerOverflow,
readerFit,
+ ...(readerFit === 'authored-height' ? { diagramType: metrics.diagramType, documentScrollUnclipped: metrics.documentScrollUnclipped === true } : {}),
ok: containmentOk,
readerWidth: Number(metrics.readerWidth) || null,
diagramWidth: Number(metrics.diagramWidth) || null,
@@ -2035,10 +2050,16 @@ function observationDiagnostics({ artifact, allObservations, readabilityObservat
}));
}
if (!entry.ok) {
- const budgetFixes = verticalBudgetFixes(entry);
+ const authoredClipped = entry.readerFit === 'authored-height' && entry.diagramType === 'architecture'
+ && !entry.documentScrollUnclipped;
+ const budgetFixes = authoredClipped
+ ? ['restore the full SVG inside the diagram panel and allow normal document scrolling; remove internal scrollers and clipping without changing authored geometry']
+ : verticalBudgetFixes(entry);
diagnostics.push(failureDiagnostic({
- code: 'viewer/viewport-overflow',
- message: `The rendered artifact overflows the ${entry.width}x${entry.height} ${entry.theme} viewport.`,
+ code: authoredClipped ? 'viewer/diagram-clipped' : 'viewer/viewport-overflow',
+ message: authoredClipped
+ ? `The authored Architecture canvas is clipped or cannot scroll in the document at ${entry.width}x${entry.height} (${entry.theme}).`
+ : `The rendered artifact overflows the ${entry.width}x${entry.height} ${entry.theme} viewport.`,
subject: viewportSubject(artifact, entry),
evidence: {
innerWidth: entry.innerWidth,
@@ -2051,6 +2072,7 @@ function observationDiagnostics({ artifact, allObservations, readabilityObservat
readerLayout: entry.readerLayout,
readerOverflow: entry.readerOverflow,
readerFit: entry.readerFit,
+ ...(authoredClipped ? { documentScrollUnclipped: false } : {}),
...(entry.overflowY && entry.pageComposition ? {
pageComposition: entry.pageComposition,
pageCompositionMeasurement: 'CSS pixels at this viewport; body padding, header, guided-views strip, diagram chrome, SVG and cards stack vertically and sum to scrollHeight',
diff --git a/archify/references/delivery-contract.md b/archify/references/delivery-contract.md
index e8736b35..9a6b8195 100644
--- a/archify/references/delivery-contract.md
+++ b/archify/references/delivery-contract.md
@@ -366,20 +366,20 @@ The receipt binds the artifact SHA-256 and byte count, identifies
`evidenceKind: "automated-browser"`, and reports
`visualReview: "not-requested"`.
-Horizontal overflow always fails. Vertical overflow normally fails as well. One
-bounded exception preserves readability for renderer-owned canvases that declare
-intrinsic-height (omitted `meta.viewBox`, whether compiler-measured or the
-type's default canvas): after the adaptive
-Reader reaches its projected text floor and exposes
-`data-reader-layout="adaptive"` with
-`data-reader-overflow="authored"`, normal
-page-level vertical scrolling may pass. The SVG must also expose
-`data-reader-fit="intrinsic-height"`, projected text must still pass, and the
-receipt records `verticalScrollAccepted: true` with
-`overflowDisposition: "readable-vertical-scroll"`. Missing declarations,
-explicit authored viewBoxes, horizontal overflow, unreadable text, clipping, and
-Viewer chrome collisions remain failures. Do not add an internal diagram
-scroller or hide overflow.
+Horizontal overflow always fails. Normal document-level vertical scrolling is
+accepted only with a renderer-declared contract and measured readable text.
+Automatic canvases declare `data-reader-fit="intrinsic-height"`; their adaptive
+Reader must reach its readable width and expose `data-reader-overflow="authored"`.
+Architecture with an explicit `meta.viewBox` instead declares
+`data-diagram-type="architecture"` and `data-reader-fit="authored-height"`:
+its SVG coordinates, aspect ratio and existing Reader width behavior stay
+unchanged. Its full SVG must remain inside the diagram panel without internal
+scrolling or clipping, and the document must permit vertical scrolling.
+The receipt records `verticalScrollAccepted: true` and
+`overflowDisposition: "readable-vertical-scroll"`. Missing or unknown declarations,
+explicit viewBoxes in other modes, unreadable text, horizontal overflow,
+clipping and Viewer chrome collisions remain failures. Do not add an internal
+diagram scroller or hide overflow.
`browser_evidence` in the handoff records only the outcome of this automated
command:
diff --git a/archify/renderers/architecture/render-architecture.mjs b/archify/renderers/architecture/render-architecture.mjs
index 8f8a9659..01333504 100644
--- a/archify/renderers/architecture/render-architecture.mjs
+++ b/archify/renderers/architecture/render-architecture.mjs
@@ -935,9 +935,11 @@ function renderSvg() {
// An automatic architecture canvas is compiler-measured geometry. Let the
// Reader spend the real desktop height budget on it, including when an
// outer route makes the canvas taller than the ordinary wide-diagram
- // threshold. Authored viewBoxes remain authoritative and keep the
- // established Viewer contract.
- const readerFit = arch.meta?.viewBox ? '' : ' data-reader-fit="intrinsic-height"';
+ // threshold. Authored viewBoxes keep their geometry and existing Reader width policy;
+ // their declared height may use readable document scrolling without reflow.
+ const readerFit = arch.meta?.viewBox
+ ? ' data-diagram-type="architecture" data-reader-fit="authored-height"'
+ : ' data-reader-fit="intrinsic-height"';
// A complete repository architecture is allowed to use normal page scroll;
// keep its common-desktop text at a comfortable reading size instead of
// shrinking a semantically rich graph to the universal emergency floor.
diff --git a/archify/renderers/shared/desktop-readability.mjs b/archify/renderers/shared/desktop-readability.mjs
index 90ddc272..8c6e33d6 100644
--- a/archify/renderers/shared/desktop-readability.mjs
+++ b/archify/renderers/shared/desktop-readability.mjs
@@ -97,6 +97,7 @@ export function predictedFixedWidthOverflow({
viewBoxWidth,
viewBoxHeight,
readerFit,
+ diagramType,
hasGuidedViews = false,
viewport = DESKTOP_READABILITY_VIEWPORT,
bodyHorizontalPx = DECLARED_WIDE_REFERENCE_BODY_HORIZONTAL_PX,
@@ -105,7 +106,9 @@ export function predictedFixedWidthOverflow({
} = {}) {
if (![viewBoxWidth, viewBoxHeight].every(Number.isFinite) || viewBoxWidth <= 0 || viewBoxHeight <= 0) return null;
const ratio = viewBoxWidth / viewBoxHeight;
- if (readerFit === 'intrinsic-height' || ratio >= DECLARED_WIDE_READER_RATIO) return null;
+ if (readerFit === 'intrinsic-height'
+ || (readerFit === 'authored-height' && diagramType === 'architecture')
+ || ratio >= DECLARED_WIDE_READER_RATIO) return null;
const svgWidthPx = viewport.width - bodyHorizontalPx - diagramHorizontalPx;
const svgHeightPx = Math.round(svgWidthPx * viewBoxHeight / viewBoxWidth);
const fixedChromePx = chrome.body + chrome.header + chrome.diagram + (hasGuidedViews ? chrome.guidedViews : 0);
diff --git a/archify/scripts/check-render-output.mjs b/archify/scripts/check-render-output.mjs
index 10d6e26d..a6d8920f 100644
--- a/archify/scripts/check-render-output.mjs
+++ b/archify/scripts/check-render-output.mjs
@@ -121,6 +121,7 @@ if (svgMatches.length === 1) {
viewBoxWidth: viewBoxSize(svgAttrs)[0],
viewBoxHeight: viewBoxSize(svgAttrs)[1],
readerFit: svgAttrs['data-reader-fit'] || null,
+ diagramType: svgAttrs['data-diagram-type'] || null,
hasGuidedViews: /class="guided-views/.test(html),
});
const arrows = collectArrows(beforeLegend);
diff --git a/archify/test/delivery-contract.test.mjs b/archify/test/delivery-contract.test.mjs
index eb59bc8d..8d1b0ed6 100644
--- a/archify/test/delivery-contract.test.mjs
+++ b/archify/test/delivery-contract.test.mjs
@@ -55,7 +55,9 @@ test('required browser evidence stays deterministic and capture-free', () => {
assert.match(browserSection, /1440×900, 1600×1000, 1920×1080, and\s+2048×1320/);
assert.match(browserSection, /creates one\s+`<output-stem>\.browser-check\.json` receipt and no screenshots or contact sheet/i);
assert.match(browserSection, /visualReview: "not-requested"/);
- assert.match(browserSection, /Reader reaches its projected text floor/i);
+ assert.match(browserSection, /Reader must reach its readable width/i);
+ assert.match(browserSection, /Architecture with an explicit `meta.viewBox`[\s\S]*data-reader-fit="authored-height"/);
+ assert.match(browserSection, /explicit viewBoxes in other modes[\s\S]*remain failures/);
});
test('delivery, browser evidence, capture evidence, and perceptual review remain distinct', () => {
diff --git a/archify/test/desktop-reader-browser.test.mjs b/archify/test/desktop-reader-browser.test.mjs
index 411801dc..8beb614d 100644
--- a/archify/test/desktop-reader-browser.test.mjs
+++ b/archify/test/desktop-reader-browser.test.mjs
@@ -491,3 +491,49 @@ test('issue #250 five-stage stack fits below source scale without crossing the r
fs.rmSync(tmp, { recursive: true, force: true });
}
});
+
+test('authored Architecture canvas keeps its scale and accepts readable document scrolling', {
+ skip: chromePath ? false : 'Set ARCHIFY_CHROME to run the real browser regression.',
+}, async t => {
+ const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-authored-reader-'));
+ t.after(() => fs.rmSync(tmp, { recursive: true, force: true }));
+ const input = path.join(tmp, 'fixed.json');
+ const artifact = path.join(tmp, 'fixed.html');
+ const doc = {
+ schema_version: 1, diagram_type: 'architecture',
+ meta: { title: 'Authored overview', output: 'fixed.html', viewBox: [1040, 700], quality_profile: 'showcase' },
+ components: [
+ { id: 'client', type: 'frontend', label: 'Client', pos: [40, 80], size: [130, 60] },
+ { id: 'api', type: 'backend', label: 'API', pos: [300, 80], size: [140, 64] },
+ { id: 'store', type: 'database', label: 'Store', pos: [300, 470], size: [140, 64] },
+ ],
+ connections: [{ from: 'client', to: 'api', label: 'request' }, { from: 'api', to: 'store', label: 'persist' }],
+ };
+ fs.writeFileSync(input, JSON.stringify(doc));
+ execFileSync(process.execPath, [path.join(skillRoot, 'bin/archify.mjs'), 'render', 'architecture', input, artifact]);
+ const html = fs.readFileSync(artifact, 'utf8');
+ assert.match(html, /viewBox="0 0 1040 700"/);
+ assert.match(html, /<rect x="300" y="470" width="140" height="64"/);
+ const baseline = path.join(tmp, 'legacy.html');
+ fs.writeFileSync(baseline, html.replace(' data-reader-fit="authored-height"', ''));
+ const old = await runVisualCheck({ artifactPath: baseline, chromePath });
+ assert.equal(old.exitCode, 1, 'legacy page rejects ordinary document overflow');
+ const result = await runVisualCheck({ artifactPath: artifact, chromePath });
+ assert.equal(result.exitCode, 0, JSON.stringify(result.receipt.diagnostics));
+ for (const viewport of result.receipt.containment.viewports) {
+ const before = old.receipt.containment.viewports.find(v => v.width === viewport.width);
+ assert.equal(viewport.diagramWidth, before.diagramWidth, 'keep the approved page scale');
+ assert.equal(viewport.readerWidth, before.readerWidth);
+ assert.equal(viewport.readerLayout, before.readerLayout);
+ assert.equal(viewport.readerFit, 'authored-height');
+ assert.equal(viewport.overflowX, false);
+ if (viewport.overflowY) assert.equal(viewport.verticalScrollAccepted, true);
+ }
+ for (const overflow of ['hidden', 'auto']) {
+ const clipped = path.join(tmp, `clipped-${overflow}.html`);
+ fs.writeFileSync(clipped, html.replace('</head>', `<style>.diagram-container { height: 300px !important; overflow: ${overflow} !important; }</style></head>`));
+ const failed = await runVisualCheck({ artifactPath: clipped, chromePath });
+ assert.equal(failed.exitCode, 1);
+ assert.ok(failed.receipt.diagnostics.some(d => d.code === 'viewer/diagram-clipped'), JSON.stringify(failed.receipt.diagnostics));
+ }
+});
diff --git a/archify/test/finalize.test.mjs b/archify/test/finalize.test.mjs
index 03384fd4..932d6450 100644
--- a/archify/test/finalize.test.mjs
+++ b/archify/test/finalize.test.mjs
@@ -1,9 +1,11 @@
import test from 'node:test';
import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
import fs from 'node:fs';
import { createHash } from 'node:crypto';
import os from 'node:os';
import path from 'node:path';
+import { fileURLToPath } from 'node:url';
import {
FINALIZE_STAGES,
@@ -428,6 +430,137 @@ test('finalize fails closed when a stage exits zero without a valid passing rece
}
});
+test('showcase delivery warnings name the checker issue without advancing to later gates', async t => {
+ const directory = workspace(t);
+ const input = path.join(directory, 'diagram.json');
+ const output = path.join(directory, 'diagram.html');
+ const source = '{"meta":{"quality_profile":"showcase"}}';
+ fs.writeFileSync(input, source);
+ const calls = [];
+ const issue = {
+ severity: 'warning', code: 'composition/viewport-height',
+ viewBoxHeight: 700, overflowPx: 193,
+ detail: '[composition/viewport-height] Preserve every node and compact vertical spacing to fit the Reader.',
+ };
+ const finalized = await runFinalize({
+ cliPath: '/fake/archify.mjs', type: 'architecture', input, output,
+ runCommand: ({ stage }) => {
+ calls.push(stage);
+ const delivery = passingDelivery({ input, output, source });
+ delivery.validation.warnings = 1;
+ delivery.validation.compositionIssues = [issue];
+ return result(delivery);
+ },
+ });
+
+ assert.equal(finalized.exitCode, 1);
+ assert.deepEqual(calls, ['deliver']);
+ assert.equal(finalized.receipt.failedStage, 'deliver');
+ assert.equal(finalized.summary.gates.deliver, 'fail');
+ assert.equal(finalized.summary.gates.check, 'not-run');
+ assert.equal(finalized.summary.diagnostics[0].code, issue.code);
+ assert.equal(finalized.summary.diagnostics[0].evidence.overflowPx, 193);
+ assert.match(finalized.summary.diagnostics[0].supportedFixes[0], /compact vertical spacing/);
+ assert.equal(finalized.summary.diagnostics[0].evidence.reportedSeverity, 'warning');
+ assert.equal(JSON.parse(fs.readFileSync(finalized.summary.evidence.receipt)).diagnostics[0].code, issue.code);
+});
+
+test('showcase warning diagnostic never masks a mismatched delivery artifact', async t => {
+ const directory = workspace(t);
+ const input = path.join(directory, 'diagram.json');
+ const output = path.join(directory, 'diagram.html');
+ const source = '{}';
+ fs.writeFileSync(input, source);
+ const finalized = await runFinalize({
+ cliPath: '/fake/archify.mjs', type: 'architecture', input, output,
+ runCommand: () => {
+ const delivery = passingDelivery({ input, output, source });
+ delivery.validation.warnings = 1;
+ delivery.validation.compositionIssues = [{
+ severity: 'warning', code: 'composition/viewport-height', detail: 'Reduce height.',
+ }];
+ delivery.artifact = artifactIdentity('another artifact');
+ return result(delivery);
+ },
+ });
+ assert.equal(finalized.exitCode, 1);
+ assert.equal(finalized.summary.diagnostics[0].code, 'finalize/artifact-binding-mismatch');
+});
+
+test('showcase warning count without matching issue details still fails with a quality diagnostic', async t => {
+ const directory = workspace(t);
+ const input = path.join(directory, 'diagram.json');
+ const output = path.join(directory, 'diagram.html');
+ const source = '{}';
+ fs.writeFileSync(input, source);
+ const calls = [];
+ const finalized = await runFinalize({
+ cliPath: '/fake/archify.mjs', type: 'workflow', input, output,
+ runCommand: ({ stage }) => {
+ calls.push(stage);
+ const delivery = passingDelivery({ input, output, source, type: 'workflow' });
+ delivery.validation.warnings = 1;
+ delivery.validation.compositionIssues = [{ severity: 'warning', code: 'composition/viewport-height' }];
+ return result(delivery);
+ },
+ });
+ assert.equal(finalized.exitCode, 1);
+ assert.deepEqual(calls, ['deliver']);
+ assert.equal(finalized.summary.diagnostics[0].code, 'finalize/showcase-warnings');
+ assert.equal(finalized.summary.diagnostics[0].evidence.warnings, 1);
+});
+
+test('public deliver and finalize CLI propagate a real workflow viewport warning', t => {
+ const directory = workspace(t);
+ const input = path.join(directory, 'warning.workflow.json');
+ const output = path.join(directory, 'warning.html');
+ const cli = fileURLToPath(new URL('../bin/archify.mjs', import.meta.url));
+ fs.writeFileSync(input, `${JSON.stringify({
+ schema_version: 1,
+ diagram_type: 'workflow',
+ meta: {
+ title: 'Viewport warning fixture', output: 'warning.html',
+ quality_profile: 'showcase', viewBox: [1080, 780], legend: { mode: 'hidden' },
+ },
+ lanes: [{ id: 'work', label: 'Work' }],
+ nodes: [
+ { id: 'start', lane: 'work', col: 0, type: 'frontend', label: 'Start' },
+ { id: 'finish', lane: 'work', col: 2, type: 'backend', label: 'Finish' },
+ ],
+ edges: [{ id: 'flow', from: 'start', to: 'finish' }],
+ }, null, 2)}\n`);
+ const run = (command) => spawnSync(process.execPath, [
+ cli, command, 'workflow', input, ...(command === 'validate' ? [] : [output]),
+ '--quality', 'showcase', '--json',
+ ], { encoding: 'utf8', timeout: 30000 });
+
+ const validated = run('validate');
+ assert.equal(validated.status, 0, validated.stderr || validated.stdout);
+ const validation = JSON.parse(validated.stdout);
+ assert.equal(validation.checks.length, 9);
+ assert.equal(validation.checks.every((check) => check.ok), true);
+ assert.deepEqual(validation.composition.summary, { errors: 0, warnings: 1 });
+
+ const delivered = run('deliver');
+ assert.equal(delivered.status, 0, delivered.stderr || delivered.stdout);
+ const delivery = JSON.parse(delivered.stdout);
+ assert.equal(delivery.validation.checksPassed, 9);
+ assert.equal(delivery.validation.errors, 0);
+ assert.equal(delivery.validation.warnings, 1);
+ assert.equal(delivery.validation.compositionIssues.length, 1);
+ assert.equal(delivery.validation.compositionIssues[0].code, 'composition/viewport-height');
+
+ const finalized = run('finalize');
+ assert.equal(finalized.status, 1, finalized.stderr || finalized.stdout);
+ const summary = JSON.parse(finalized.stdout);
+ assert.equal(summary.failedStage, 'deliver');
+ assert.equal(summary.gates.check, 'not-run');
+ assert.equal(summary.diagnostics[0].code, 'composition/viewport-height');
+ assert.equal(summary.diagnostics[0].evidence.overflowPx, validation.composition.issues[0].overflowPx);
+ assert.match(summary.diagnostics[0].supportedFixes[0], /meta\.viewBox height/);
+ assert.equal(JSON.parse(fs.readFileSync(summary.evidence.receipt)).diagnostics[0].code, 'composition/viewport-height');
+});
+
test('finalize rejects an interleaved delivery whose check proves another artifact and receipt', async t => {
const directory = workspace(t);
const input = path.join(directory, 'a.json');
diff --git a/archify/test/layout-rules.test.mjs b/archify/test/layout-rules.test.mjs
index 3edfd9a0..f777519d 100644
--- a/archify/test/layout-rules.test.mjs
+++ b/archify/test/layout-rules.test.mjs
@@ -1317,7 +1317,8 @@ test('architecture: measured auto canvases opt into height-aware reader fitting'
assert.equal(pinned.code, 0, pinned.stderr);
const authoredSvg = fs.readFileSync(pinned.outPath, 'utf8').match(/<svg\b[^>]*>/)?.[0];
assert.ok(authoredSvg, 'expected an SVG root for the authored canvas');
- assert.doesNotMatch(authoredSvg, /data-reader-fit=/);
+ assert.match(authoredSvg, /data-reader-fit="authored-height"/);
+ assert.match(authoredSvg, /data-diagram-type="architecture"/);
assert.doesNotMatch(authoredSvg, /data-reader-min-text=/);
});
diff --git a/archify/test/render-output-checks.test.mjs b/archify/test/render-output-checks.test.mjs
index 6a67843b..be8e4977 100644
--- a/archify/test/render-output-checks.test.mjs
+++ b/archify/test/render-output-checks.test.mjs
@@ -87,6 +87,12 @@ test('render output check: predicts the certain 1440x900 overflow of a fixed-wid
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');
+ 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);
diff --git a/archify/test/visual-check.test.mjs b/archify/test/visual-check.test.mjs
index d5a9f323..ef33381c 100644
--- a/archify/test/visual-check.test.mjs
+++ b/archify/test/visual-check.test.mjs
@@ -52,6 +52,9 @@ function fakeBrowser({
overflowAt,
tallAt,
readableScrollAt,
+ authoredScrollAt,
+ authoredDiagramType = 'architecture',
+ authoredUnclipped = true,
unreadableAt,
chromeCollisionAt,
stageCollisionAt,
@@ -74,6 +77,7 @@ function fakeBrowser({
const overflow = overflowAt?.({ width, height, theme }) || false;
const tall = tallAt?.({ width, height, theme }) || false;
const readableScroll = readableScrollAt?.({ width, height, theme }) || false;
+ const authoredScroll = authoredScrollAt?.({ width, height, theme }) || false;
const unreadable = unreadableAt?.({ width, height, theme }) || false;
const chromeCollision = chromeCollisionAt?.({ width, height, theme }) || false;
const stageCollision = stageCollisionAt?.({ width, height, theme }) || false;
@@ -83,7 +87,7 @@ function fakeBrowser({
innerWidth: width,
innerHeight: height,
scrollWidth: width + (overflow ? 1 : 0),
- scrollHeight: height + (readableScroll ? 240 : 0) + (tall ? 300 : 0),
+ scrollHeight: height + (readableScroll || authoredScroll ? 240 : 0) + (tall ? 300 : 0),
resolvedTheme: resolvedThemeAt?.({ width, height, theme }) ?? theme,
...(tall ? {
pageComposition: {
@@ -93,7 +97,9 @@ function fakeBrowser({
} : {}),
readerLayout: readableScroll ? 'adaptive' : null,
readerOverflow: readableScroll ? 'authored' : null,
- readerFit: readableScroll ? 'intrinsic-height' : null,
+ readerFit: readableScroll ? 'intrinsic-height' : authoredScroll ? 'authored-height' : null,
+ diagramType: authoredScroll ? authoredDiagramType : null,
+ documentScrollUnclipped: authoredScroll && authoredUnclipped,
readerWidth: 960,
diagramWidth: 930,
viewBoxWidth: 1300,
@@ -3127,3 +3133,27 @@ for (const [command, run] of [['browser-check', runBrowserCheck], ['visual-check
});
}
}
+
+
+test('authored Architecture scroll requires readable unclipped document flow and preserves other modes', async () => {
+ const input = artifact('authored-scroll.html');
+ const target = ({ width, theme }) => width === 1440 && theme === 'light';
+ for (const [name, options, accepted] of [
+ ['readable document', {}, true],
+ ['other diagram mode', { authoredDiagramType: 'workflow' }, false],
+ ['missing mode', { authoredDiagramType: null }, false],
+ ['clipped or internally scrolled SVG', { authoredUnclipped: false }, false],
+ ['unreadable text', { unreadableAt: target }, false],
+ ['horizontal overflow', { overflowAt: target }, false],
+ ]) {
+ const result = await runVisualCheck({
+ artifactPath: input, outDir: path.join(tmp, `authored-${name.replace(/[^a-z]/g, '-')}`),
+ chromePath: '/fake/chrome',
+ browserFactory: async () => fakeBrowser({ authoredScrollAt: target, ...options }),
+ });
+ const viewport = result.receipt.containment.viewports.find(({ width }) => width === 1440);
+ assert.equal(result.exitCode, accepted ? 0 : 1, name);
+ assert.equal(viewport.verticalScrollAccepted, accepted, name);
+ assert.equal(viewport.readerLayout, null, 'the fixed canvas does not acquire adaptive scaling');
+ }
+});