Skip to content

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

fix(viewer): enforce readable workflow evidence

sunsunsun86389781ab67
diff --git a/archify/assets/template.html b/archify/assets/template.html
index ad454dc4..24283f95 100644
--- a/archify/assets/template.html
+++ b/archify/assets/template.html
@@ -10840,6 +10840,7 @@
var MIN_DESKTOP_WIDTH = 1024;
var MIN_READER_WIDTH = 960;
var MAX_READER_WIDTH = 1920;
+ var MIN_PROJECTED_NODE_TEXT_PX = 6;
var SAFE_BOTTOM_GAP = 12;
if (diagram && ratio >= WIDE_RATIO) {
@@ -10859,6 +10860,21 @@
var style = window.getComputedStyle(element);
return element.getBoundingClientRect().height + number(style.marginTop) + number(style.marginBottom);
}
+ function minimumReadableScale() {
+ var sourceMinimum = null;
+ Array.from(svg.querySelectorAll(
+ 'text[data-node-label], text[data-boundary-label], text[data-detail="context"]'
+ )).forEach(function (text) {
+ if (text.getAttribute('data-detail') === 'context' && !text.closest('[data-node-id]')) return;
+ var sourceFontPx = parseFloat(text.getAttribute('font-size') || '');
+ if (Number.isFinite(sourceFontPx)) {
+ sourceMinimum = sourceMinimum == null ? sourceFontPx : Math.min(sourceMinimum, sourceFontPx);
+ }
+ });
+ return sourceMinimum != null
+ ? Math.min(1, MIN_PROJECTED_NODE_TEXT_PX / sourceMinimum)
+ : 1;
+ }
function eligible() {
return Boolean(
shell && diagram && svg && (ratio >= WIDE_RATIO || intrinsicHeightFit) &&
@@ -10921,11 +10937,11 @@
}
var chrome = chromeMetrics();
var viewportCap = Math.max(0, window.innerWidth - chrome.bodyX);
- var sourceWidth = viewBox && viewBox.width > 0
- ? viewBox.width + chrome.diagramX
+ var readableWidth = viewBox && viewBox.width > 0
+ ? viewBox.width * minimumReadableScale() + chrome.diagramX
: MIN_READER_WIDTH;
var minWidth = Math.min(
- intrinsicHeightFit && ratio < WIDE_RATIO ? sourceWidth : MIN_READER_WIDTH,
+ intrinsicHeightFit && ratio < WIDE_RATIO ? readableWidth : MIN_READER_WIDTH,
viewportCap
);
var maxWidth = Math.min(MAX_READER_WIDTH, viewportCap);
diff --git a/archify/bin/visual-check.mjs b/archify/bin/visual-check.mjs
index 8adb154b..226d5f5d 100644
--- a/archify/bin/visual-check.mjs
+++ b/archify/bin/visual-check.mjs
@@ -394,6 +394,51 @@ export class ChromeVisualBrowser {
var viewBox = svg && svg.viewBox && svg.viewBox.baseVal;
var diagramWidth = svg ? svg.getBoundingClientRect().width : 0;
var viewBoxWidth = viewBox ? viewBox.width : 0;
+ var diagramClientWidth = diagram ? diagram.clientWidth : 0;
+ var diagramClientHeight = diagram ? diagram.clientHeight : 0;
+ var diagramScrollWidth = diagram ? diagram.scrollWidth : 0;
+ var diagramScrollHeight = diagram ? diagram.scrollHeight : 0;
+ var stageClientWidth = stage ? stage.clientWidth : 0;
+ var stageClientHeight = stage ? stage.clientHeight : 0;
+ var stageScrollWidth = stage ? stage.scrollWidth : 0;
+ var stageScrollHeight = stage ? stage.scrollHeight : 0;
+ var internalScrollOk = (
+ diagramScrollWidth <= diagramClientWidth + 1
+ && diagramScrollHeight <= diagramClientHeight + 1
+ && stageScrollWidth <= stageClientWidth + 1
+ && stageScrollHeight <= stageClientHeight + 1
+ );
+ var diagramRect = diagram ? diagram.getBoundingClientRect() : null;
+ var svgRect = svg ? svg.getBoundingClientRect() : null;
+ var viewportRect = {
+ left: 0,
+ top: 0,
+ right: window.innerWidth,
+ bottom: window.innerHeight
+ };
+ function containsRect(outer, inner) {
+ if (!outer || !inner || !inner.width || !inner.height) return false;
+ return inner.left >= outer.left - 1
+ && inner.top >= outer.top - 1
+ && inner.right <= outer.right + 1
+ && inner.bottom <= outer.bottom + 1;
+ }
+ var clippedContent = svg ? Array.from(svg.querySelectorAll(
+ '[data-node-id], [data-composition-frame-kind="group"]'
+ )).filter(function (element) {
+ var rect = element.getBoundingClientRect();
+ return !containsRect(svgRect, rect)
+ || !containsRect(diagramRect, rect)
+ || !containsRect(viewportRect, rect);
+ }).map(function (element) {
+ if (element.hasAttribute('data-node-id')) {
+ return 'node:' + element.getAttribute('data-node-id');
+ }
+ return 'frame:'
+ + element.getAttribute('data-composition-frame-kind') + ':'
+ + element.getAttribute('data-composition-frame-id');
+ }) : [];
+ var contentVisibilityOk = clippedContent.length === 0;
var scale = viewBoxWidth > 0 ? Math.min(1, diagramWidth / viewBoxWidth) : 0;
var minimum = null;
if (svg && scale > 0) {
@@ -441,6 +486,17 @@ export class ChromeVisualBrowser {
readerWidth: reader ? reader.getBoundingClientRect().width : 0,
diagramWidth: diagramWidth,
viewBoxWidth: viewBoxWidth,
+ diagramClientWidth: diagramClientWidth,
+ diagramClientHeight: diagramClientHeight,
+ diagramScrollWidth: diagramScrollWidth,
+ diagramScrollHeight: diagramScrollHeight,
+ stageClientWidth: stageClientWidth,
+ stageClientHeight: stageClientHeight,
+ stageScrollWidth: stageScrollWidth,
+ stageScrollHeight: stageScrollHeight,
+ internalScrollOk: internalScrollOk,
+ contentVisibilityOk: contentVisibilityOk,
+ clippedContent: clippedContent,
minimumProjectedNodeTextPx: minimum ? minimum.projectedFontPx : null,
minimumProjectedNodeText: minimum ? minimum.text : null,
minimumProjectedNodeTextDetail: minimum ? minimum.detail : null,
@@ -507,6 +563,11 @@ function observation({ width, height, theme, metrics }) {
: Number(metrics.minimumProjectedNodeTextPx);
const readabilityOk = minimumProjectedNodeTextPx == null
|| minimumProjectedNodeTextPx >= MIN_PROJECTED_NODE_TEXT_PX;
+ const internalScrollOk = metrics.internalScrollOk !== false;
+ const contentVisibilityOk = metrics.contentVisibilityOk !== false;
+ const clippedContent = Array.isArray(metrics.clippedContent) ? metrics.clippedContent : [];
+ const resolvedTheme = metrics.resolvedTheme || '';
+ const themeOk = resolvedTheme === theme;
const legendDockIntersectionArea = Number(metrics.legendDockIntersectionArea) || 0;
const dockStageIntersectionArea = Number(metrics.dockStageIntersectionArea) || 0;
const dockStageGap = metrics.dockStageGap == null ? null : Number(metrics.dockStageGap);
@@ -530,10 +591,21 @@ function observation({ width, height, theme, metrics }) {
scrollHeight,
overflowX,
overflowY,
- ok: !overflowX && !overflowY,
+ ok: !overflowX && !overflowY && internalScrollOk && contentVisibilityOk,
readerWidth: Number(metrics.readerWidth) || null,
diagramWidth: Number(metrics.diagramWidth) || null,
viewBoxWidth: Number(metrics.viewBoxWidth) || null,
+ diagramClientWidth: Number(metrics.diagramClientWidth) || 0,
+ diagramClientHeight: Number(metrics.diagramClientHeight) || 0,
+ diagramScrollWidth: Number(metrics.diagramScrollWidth) || 0,
+ diagramScrollHeight: Number(metrics.diagramScrollHeight) || 0,
+ stageClientWidth: Number(metrics.stageClientWidth) || 0,
+ stageClientHeight: Number(metrics.stageClientHeight) || 0,
+ stageScrollWidth: Number(metrics.stageScrollWidth) || 0,
+ stageScrollHeight: Number(metrics.stageScrollHeight) || 0,
+ internalScrollOk,
+ contentVisibilityOk,
+ clippedContent,
minimumProjectedNodeTextPx,
minimumProjectedNodeText: metrics.minimumProjectedNodeText || null,
minimumProjectedNodeTextDetail: metrics.minimumProjectedNodeTextDetail || null,
@@ -549,7 +621,8 @@ function observation({ width, height, theme, metrics }) {
viewerChromeReserve: Number(metrics.viewerChromeReserve) || 0,
viewerChromeActive: Boolean(metrics.viewerChromeActive),
viewerChromeOk,
- resolvedTheme: metrics.resolvedTheme || theme,
+ resolvedTheme,
+ themeOk,
};
}
@@ -592,7 +665,7 @@ function failureDiagnostic({ code, message, subject, evidence, supportedFixes, s
function observationDiagnostics({ artifact, allObservations, readabilityObservations }) {
const diagnostics = [];
for (const entry of allObservations) {
- if (!entry.ok) {
+ if (entry.overflowX || entry.overflowY) {
diagnostics.push(failureDiagnostic({
code: 'viewer/viewport-overflow',
message: `The rendered artifact overflows the ${entry.width}x${entry.height} ${entry.theme} viewport.`,
@@ -610,6 +683,51 @@ function observationDiagnostics({ artifact, allObservations, readabilityObservat
],
}));
}
+ if (!entry.internalScrollOk) {
+ diagnostics.push(failureDiagnostic({
+ code: 'viewer/internal-scroll',
+ message: `The diagram introduces an internal scroll range at ${entry.width}x${entry.height} (${entry.theme}).`,
+ subject: viewportSubject(artifact, entry),
+ evidence: {
+ diagramClientWidth: entry.diagramClientWidth,
+ diagramClientHeight: entry.diagramClientHeight,
+ diagramScrollWidth: entry.diagramScrollWidth,
+ diagramScrollHeight: entry.diagramScrollHeight,
+ stageClientWidth: entry.stageClientWidth,
+ stageClientHeight: entry.stageClientHeight,
+ stageScrollWidth: entry.stageScrollWidth,
+ stageScrollHeight: entry.stageScrollHeight,
+ },
+ supportedFixes: [
+ 'remove the diagram or SVG stage scroll range without clipping content, then rerun visual-check',
+ ],
+ }));
+ }
+ if (!entry.contentVisibilityOk) {
+ diagnostics.push(failureDiagnostic({
+ code: 'viewer/content-clipping',
+ message: `Rendered workflow content is clipped at ${entry.width}x${entry.height} (${entry.theme}).`,
+ subject: viewportSubject(artifact, entry),
+ evidence: { clippedContent: entry.clippedContent },
+ supportedFixes: [
+ 'keep every workflow group and node inside the SVG, diagram panel, and viewport, then rerun visual-check',
+ ],
+ }));
+ }
+ if (!entry.themeOk) {
+ diagnostics.push(failureDiagnostic({
+ code: 'viewer/theme-mismatch',
+ message: `The Viewer resolved ${entry.resolvedTheme || 'no theme'} instead of the requested ${entry.theme} theme.`,
+ subject: viewportSubject(artifact, entry),
+ evidence: {
+ requestedTheme: entry.theme,
+ resolvedTheme: entry.resolvedTheme,
+ },
+ supportedFixes: [
+ `make the Viewer resolve the requested ${entry.theme} theme before capturing evidence`,
+ ],
+ }));
+ }
if (entry.legendDockIntersectionArea > 0.5) {
diagnostics.push(failureDiagnostic({
code: 'viewer/chrome-legend-clearance',
@@ -784,6 +902,7 @@ export async function runVisualCheck({
const containmentPass = allObservations.every((entry) => entry.ok);
const readabilityPass = receipt.readability.viewports.every((entry) => entry.readabilityOk);
const viewerChromePass = allObservations.every((entry) => entry.viewerChromeOk);
+ const capturePass = allObservations.every((entry) => entry.themeOk);
receipt.diagnostics = observationDiagnostics({
artifact,
allObservations,
@@ -792,10 +911,10 @@ export async function runVisualCheck({
receipt.containment.status = containmentPass ? 'pass' : 'fail';
receipt.readability.status = readabilityPass ? 'pass' : 'fail';
receipt.viewerChrome.status = viewerChromePass ? 'pass' : 'fail';
- receipt.captures.status = 'pass';
+ receipt.captures.status = capturePass ? 'pass' : 'fail';
receipt.captures.contactSheet = path.basename(outputs.contactSheet);
- receipt.status = containmentPass && readabilityPass && viewerChromePass ? 'pass' : 'fail';
- receipt.ok = containmentPass && readabilityPass && viewerChromePass;
+ receipt.status = containmentPass && readabilityPass && viewerChromePass && capturePass ? 'pass' : 'fail';
+ receipt.ok = containmentPass && readabilityPass && viewerChromePass && capturePass;
writeAtomic(outputs.contactSheet, contactSheetHtml({
artifactPath: artifact,
receipt,
diff --git a/archify/references/delivery-contract.md b/archify/references/delivery-contract.md
index 31f2c1dc..b13b015e 100644
--- a/archify/references/delivery-contract.md
+++ b/archify/references/delivery-contract.md
@@ -36,6 +36,9 @@ node bin/archify.mjs visual-check <output.html> --json
The zero-dependency command uses Chrome/Chromium through the DevTools pipe. It
measures light-theme containment at 1440×900, 1600×1000, 1920×1080, and
2048×1320, then captures light/dark screenshots at 1440×900 and 2048×1320. It
+watches both page and diagram/SVG-stage scroll ranges, verifies that workflow
+groups and nodes remain inside the SVG, diagram panel, and viewport, and
+confirms that each capture resolved the requested theme. It
writes four PNG sidecars, one relative-path HTML contact sheet, and one JSON
receipt beside the artifact. The receipt binds the source artifact SHA-256 and
byte count, identifies `evidenceKind: "automated-browser"`, records READ plus
diff --git a/archify/renderers/workflow/README.md b/archify/renderers/workflow/README.md
index 98345f2e..6519fcc1 100644
--- a/archify/renderers/workflow/README.md
+++ b/archify/renderers/workflow/README.md
@@ -149,7 +149,11 @@ When an authored `lane.height` makes an implicit readable-v2 canvas taller
than the 104px baseline, the compiled SVG opts into the desktop Viewer's
height budget. The Viewer changes only the outer reader width so the complete
lane remains on screen; canonical SVG geometry and explicit `meta.viewBox`
-workflows retain their authored contracts.
+workflows retain their authored contracts. When necessary, the Viewer may
+scale below the intrinsic 1:1 width only as far as the 6px projected node-text
+floor. If the complete workflow still cannot fit at that readable scale,
+`visual-check` reports the remaining viewport overflow instead of clipping or
+introducing an internal scroller.
Authored `via`, `labelAt`, `channelX`, and `channelY` are absolute hard pins in
v2; an infeasible pin returns `workflow/explicit-pin-conflict` rather than being
diff --git a/archify/test/adaptive-reader-layout.test.mjs b/archify/test/adaptive-reader-layout.test.mjs
index 4e7cdcfd..1e8a9dd0 100644
--- a/archify/test/adaptive-reader-layout.test.mjs
+++ b/archify/test/adaptive-reader-layout.test.mjs
@@ -36,8 +36,9 @@ test('wide desktop diagrams use one height-budgeted reader shell instead of brea
test('compiler-approved intrinsic tall workflows reuse the height budget without widening eligibility', () => {
assert.match(reader, /svg\.getAttribute\('data-reader-fit'\) === 'intrinsic-height'/);
assert.match(reader, /ratio >= WIDE_RATIO \|\| intrinsicHeightFit/);
- assert.match(reader, /intrinsicHeightFit && ratio < WIDE_RATIO \? sourceWidth : MIN_READER_WIDTH/);
- assert.match(reader, /viewBox\.width \+ chrome\.diagramX/);
+ assert.match(reader, /var MIN_PROJECTED_NODE_TEXT_PX = 6/);
+ assert.match(reader, /viewBox\.width \* minimumReadableScale\(\) \+ chrome\.diagramX/);
+ assert.match(reader, /intrinsicHeightFit && ratio < WIDE_RATIO \? readableWidth : MIN_READER_WIDTH/);
assert.doesNotMatch(reader, /function eligible\(\)[\s\S]{0,240}ratio > 0/);
});
diff --git a/archify/test/desktop-reader-browser.test.mjs b/archify/test/desktop-reader-browser.test.mjs
index 63f3f2a4..c1ff9e82 100644
--- a/archify/test/desktop-reader-browser.test.mjs
+++ b/archify/test/desktop-reader-browser.test.mjs
@@ -37,6 +37,25 @@ const issue250TallGroup = {
],
};
+const issue250FiveStageGroup = {
+ ...issue250TallGroup,
+ meta: { title: 'Issue 250 five stacked stages' },
+ mainPath: ['stageA', 'stageB', 'stageC', 'stageD', 'stageE'],
+ nodes: [
+ { id: 'stageA', lane: 'cage', col: 2, type: 'security', label: 'stageA', yOffset: 0 },
+ { id: 'stageB', lane: 'cage', col: 2, type: 'security', label: 'stageB', yOffset: 90 },
+ { id: 'stageC', lane: 'cage', col: 2, type: 'security', label: 'stageC', yOffset: 180 },
+ { id: 'stageD', lane: 'cage', col: 2, type: 'security', label: 'stageD', yOffset: 270 },
+ { id: 'stageE', lane: 'cage', col: 2, type: 'security', label: 'stageE', yOffset: 360 },
+ ],
+ edges: [
+ { id: 'stage-a-b', from: 'stageA', to: 'stageB', role: 'main', fromSide: 'bottom', toSide: 'top' },
+ { id: 'stage-b-c', from: 'stageB', to: 'stageC', role: 'main', fromSide: 'bottom', toSide: 'top' },
+ { id: 'stage-c-d', from: 'stageC', to: 'stageD', role: 'main', fromSide: 'bottom', toSide: 'top' },
+ { id: 'stage-d-e', from: 'stageD', to: 'stageE', role: 'main', fromSide: 'bottom', toSide: 'top' },
+ ],
+};
+
test('production showcase is readable in the real 1440 by 900 adaptive reader', {
skip: chromePath ? false : 'Set ARCHIFY_CHROME to run the real browser regression.',
}, async () => {
@@ -109,18 +128,61 @@ test('issue #250 tall intrinsic workflow fits every required desktop viewport',
assert.equal(viewport.overflowX, false, JSON.stringify(viewport, null, 2));
assert.equal(viewport.overflowY, false, JSON.stringify(viewport, null, 2));
assert.equal(viewport.scrollHeight, viewport.height, JSON.stringify(viewport, null, 2));
+ assert.equal(viewport.internalScrollOk, true, JSON.stringify(viewport, null, 2));
+ assert.equal(viewport.contentVisibilityOk, true, JSON.stringify(viewport, null, 2));
+ assert.deepEqual(viewport.clippedContent, [], JSON.stringify(viewport, null, 2));
assert.ok(viewport.minimumProjectedNodeTextPx >= MIN_PROJECTED_NODE_TEXT_PX);
}
assert.deepEqual(
- result.receipt.captures.screenshots.map(({ width, height, theme }) => ({ width, height, theme })),
+ result.receipt.captures.screenshots.map(({ width, height, theme, resolvedTheme }) => ({
+ width, height, theme, resolvedTheme,
+ })),
[
- { width: 1440, height: 900, theme: 'light' },
- { width: 1440, height: 900, theme: 'dark' },
- { width: 2048, height: 1320, theme: 'light' },
- { width: 2048, height: 1320, theme: 'dark' },
+ { width: 1440, height: 900, theme: 'light', resolvedTheme: 'light' },
+ { width: 1440, height: 900, theme: 'dark', resolvedTheme: 'dark' },
+ { width: 2048, height: 1320, theme: 'light', resolvedTheme: 'light' },
+ { width: 2048, height: 1320, theme: 'dark', resolvedTheme: 'dark' },
],
);
} finally {
fs.rmSync(tmp, { recursive: true, force: true });
}
});
+
+test('issue #250 five-stage stack fits below source scale without crossing the readability floor', {
+ skip: chromePath ? false : 'Set ARCHIFY_CHROME to run the real browser regression.',
+}, async () => {
+ const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-issue-250-five-stage-'));
+ const input = path.join(tmp, 'issue-250-five-stage.workflow.json');
+ const artifact = path.join(tmp, 'issue-250-five-stage.html');
+ try {
+ fs.writeFileSync(input, `${JSON.stringify(issue250FiveStageGroup, null, 2)}\n`);
+ execFileSync(process.execPath, [
+ path.join(skillRoot, 'bin', 'archify.mjs'),
+ 'render',
+ 'workflow',
+ input,
+ artifact,
+ '--quality',
+ 'showcase',
+ ], { cwd: skillRoot, encoding: 'utf8' });
+
+ const result = await runVisualCheck({ artifactPath: artifact, chromePath });
+ assert.equal(result.exitCode, 0, JSON.stringify(result.receipt, null, 2));
+ for (const viewport of result.receipt.containment.viewports) {
+ assert.equal(viewport.overflowY, false, JSON.stringify(viewport, null, 2));
+ assert.equal(viewport.scrollHeight, viewport.height, JSON.stringify(viewport, null, 2));
+ assert.equal(viewport.internalScrollOk, true, JSON.stringify(viewport, null, 2));
+ assert.equal(viewport.contentVisibilityOk, true, JSON.stringify(viewport, null, 2));
+ assert.deepEqual(viewport.clippedContent, [], JSON.stringify(viewport, null, 2));
+ assert.ok(viewport.minimumProjectedNodeTextPx >= MIN_PROJECTED_NODE_TEXT_PX);
+ }
+ const desktop = result.receipt.containment.viewports.find(({ width, height }) => (
+ width === DESKTOP_READABILITY_VIEWPORT.width && height === DESKTOP_READABILITY_VIEWPORT.height
+ ));
+ assert.ok(desktop);
+ assert.ok(desktop.diagramWidth < desktop.viewBoxWidth, JSON.stringify(desktop, null, 2));
+ } finally {
+ fs.rmSync(tmp, { recursive: true, force: true });
+ }
+});
diff --git a/archify/test/visual-check.test.mjs b/archify/test/visual-check.test.mjs
index 2f488144..0a839846 100644
--- a/archify/test/visual-check.test.mjs
+++ b/archify/test/visual-check.test.mjs
@@ -31,7 +31,17 @@ function sha256(file) {
return createHash('sha256').update(fs.readFileSync(file)).digest('hex');
}
-function fakeBrowser({ overflowAt, unreadableAt, chromeCollisionAt, stageCollisionAt, stageGapAt, screenshotFailure } = {}) {
+function fakeBrowser({
+ overflowAt,
+ unreadableAt,
+ internalScrollAt,
+ clippedContentAt,
+ themeMismatchAt,
+ chromeCollisionAt,
+ stageCollisionAt,
+ stageGapAt,
+ screenshotFailure,
+} = {}) {
const calls = [];
return {
calls,
@@ -43,6 +53,8 @@ function fakeBrowser({ overflowAt, unreadableAt, chromeCollisionAt, stageCollisi
if (screenshotPath) fs.writeFileSync(screenshotPath, png);
const overflow = overflowAt?.({ width, height, theme }) || false;
const unreadable = unreadableAt?.({ width, height, theme }) || false;
+ const internalScroll = internalScrollAt?.({ width, height, theme }) || false;
+ const clippedContent = clippedContentAt?.({ width, height, theme }) || false;
const chromeCollision = chromeCollisionAt?.({ width, height, theme }) || false;
const stageCollision = stageCollisionAt?.({ width, height, theme }) || false;
const dockStageGap = stageGapAt?.({ width, height, theme }) ?? (stageCollision ? -12 : 10);
@@ -52,10 +64,23 @@ function fakeBrowser({ overflowAt, unreadableAt, chromeCollisionAt, stageCollisi
innerHeight: height,
scrollWidth: width + (overflow ? 1 : 0),
scrollHeight: height,
- resolvedTheme: theme,
+ resolvedTheme: themeMismatchAt?.({ width, height, theme })
+ ? (theme === 'dark' ? 'light' : 'dark')
+ : theme,
readerWidth: 960,
diagramWidth: 930,
viewBoxWidth: 1300,
+ diagramClientWidth: 930,
+ diagramClientHeight: 620,
+ diagramScrollWidth: 930 + (internalScroll ? 20 : 0),
+ diagramScrollHeight: 620 + (internalScroll ? 20 : 0),
+ stageClientWidth: 930,
+ stageClientHeight: 560,
+ stageScrollWidth: 930,
+ stageScrollHeight: 560,
+ internalScrollOk: !internalScroll,
+ contentVisibilityOk: !clippedContent,
+ clippedContent: clippedContent ? ['node:stageC'] : [],
minimumProjectedNodeTextPx: unreadable ? 5.72 : 6.44,
minimumProjectedNodeText: unreadable ? 'Compact node' : 'Readable node',
minimumProjectedNodeTextDetail: unreadable ? 'primary' : 'context',
@@ -238,6 +263,80 @@ test('visual-check returns 1 and preserves evidence when any viewport overflows'
assert.equal(fs.existsSync(sidecarPaths(input).contactSheet), true);
});
+test('visual-check rejects an internal diagram scroll range even when the page fits', async () => {
+ const input = artifact('internal-scroll.html');
+ const result = await runVisualCheck({
+ artifactPath: input,
+ chromePath: '/fake/chrome',
+ browserFactory: async () => fakeBrowser({
+ internalScrollAt: ({ width, height, theme }) => (
+ width === 1440 && height === 900 && theme === 'light'
+ ),
+ }),
+ });
+
+ assert.equal(result.exitCode, 1);
+ assert.equal(result.receipt.containment.status, 'fail');
+ const diagnostic = result.receipt.diagnostics.find(
+ (entry) => entry.code === 'viewer/internal-scroll',
+ );
+ assert.deepEqual(diagnostic?.evidence, {
+ diagramClientWidth: 930,
+ diagramClientHeight: 620,
+ diagramScrollWidth: 950,
+ diagramScrollHeight: 640,
+ stageClientWidth: 930,
+ stageClientHeight: 560,
+ stageScrollWidth: 930,
+ stageScrollHeight: 560,
+ });
+});
+
+test('visual-check rejects clipped workflow content even when page and panel dimensions fit', async () => {
+ const input = artifact('clipped-content.html');
+ const result = await runVisualCheck({
+ artifactPath: input,
+ chromePath: '/fake/chrome',
+ browserFactory: async () => fakeBrowser({
+ clippedContentAt: ({ width, height, theme }) => (
+ width === 1440 && height === 900 && theme === 'light'
+ ),
+ }),
+ });
+
+ assert.equal(result.exitCode, 1);
+ assert.equal(result.receipt.containment.status, 'fail');
+ const diagnostic = result.receipt.diagnostics.find(
+ (entry) => entry.code === 'viewer/content-clipping',
+ );
+ assert.deepEqual(diagnostic?.evidence, {
+ clippedContent: ['node:stageC'],
+ });
+});
+
+test('visual-check rejects a capture whose resolved theme differs from the requested theme', async () => {
+ const input = artifact('theme-mismatch.html');
+ const result = await runVisualCheck({
+ artifactPath: input,
+ chromePath: '/fake/chrome',
+ browserFactory: async () => fakeBrowser({
+ themeMismatchAt: ({ width, height, theme }) => (
+ width === 1440 && height === 900 && theme === 'dark'
+ ),
+ }),
+ });
+
+ assert.equal(result.exitCode, 1);
+ assert.equal(result.receipt.captures.status, 'fail');
+ const diagnostic = result.receipt.diagnostics.find(
+ (entry) => entry.code === 'viewer/theme-mismatch',
+ );
+ assert.deepEqual(diagnostic?.evidence, {
+ requestedTheme: 'dark',
+ resolvedTheme: 'light',
+ });
+});
+
test('visual-check returns 1 when the real reader projects node text below 6px', async () => {
const input = artifact('unreadable.html');
const result = await runVisualCheck({