Skip to content

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

fix(workflow): read tall automatic stacks at page width

tt-a1ib7efd0414d8b
diff --git a/archify/renderers/workflow/README.md b/archify/renderers/workflow/README.md
index 4033b427..5237c507 100644
--- a/archify/renderers/workflow/README.md
+++ b/archify/renderers/workflow/README.md
@@ -181,14 +181,13 @@ their offsets around zero:
```
An implicit readable-v2 vertical stack whose measured lane height exceeds the
-104px baseline opts into the desktop Viewer's height budget. This decision
-comes from compiled geometry, not an authored sizing field. 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.
-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.
+104px baseline declares `data-reader-fit="width-first"`. The desktop Viewer uses
+available reading width and normal page scrolling to keep tall stages readable,
+with the existing 1.5× automatic enlargement cap. This changes only displayed
+size: canonical SVG geometry and explicit `meta.viewBox` workflows retain their
+authored contracts. Embed, Present, and print retain their existing fitting modes.
+`visual-check` still checks readability, horizontal containment, and clipping;
+the declaration does not weaken node or route validation.
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/renderers/workflow/workflow-compiler.mjs b/archify/renderers/workflow/workflow-compiler.mjs
index ae7cd7c0..7dea826c 100644
--- a/archify/renderers/workflow/workflow-compiler.mjs
+++ b/archify/renderers/workflow/workflow-compiler.mjs
@@ -4896,7 +4896,7 @@ function renderSvg() {
&& !workflow.meta?.viewBox
&& hasVerticalStack(workflow)
&& asArray(layout.laneHeights).some((height) => height > 104)
- ? ' data-reader-fit="intrinsic-height"'
+ ? ' data-reader-fit="width-first"'
: '';
const contract = workflow.schema_version === 2 ? ' data-layout-contract="readable-v2"' : '';
return ` <svg viewBox="0 0 ${viewBox[0]} ${viewBox[1]}"${readerFit}${contract} ${svgRootAttrs(workflow.meta, resolvedQualityProfile)}>
diff --git a/docs/assets/reviews/workflow-reader-width/README.md b/docs/assets/reviews/workflow-reader-width/README.md
new file mode 100644
index 00000000..bf177786
--- /dev/null
+++ b/docs/assets/reviews/workflow-reader-width/README.md
@@ -0,0 +1,31 @@
+# Workflow stack reading width
+
+Comparison base: `e23fc2c5c8cf1aaa3864e7966f8b8ec43dc2bebd` (`dev`). The candidate changes only the existing automatic stacked-Workflow Reader declaration from `intrinsic-height` to `width-first`. The inputs are original synthetic public examples, not redactions or copies of a private project. They illustrate two layout shapes; they are not an agent generation benchmark and do not establish a first-pass success rate.
+
+All four screenshots use Chrome, **1440 × 1000**, light theme, `signal-flow`, showcase quality, camera **100%**, and page top. No private source or internal project content is included. The browser waits for fonts and layout settling, then captures the viewport. The JSON records actual primary-label pixel font sizes from computed fonts and SVG screen transforms, document scrolling, horizontal overflow, and a separate bottom-scroll observation.
+
+| Synthetic input | dev before | Candidate after | Minimum actual primary-label font | Document scroll beyond viewport | Horizontal overflow |
+| --- | --- | --- | --- | --- | --- |
+| [One lane, five stages](../../../../test/fixtures/reader-readability/five-stage-stack.workflow.json) | [Before](five-stage-stack-before.png) | [After](five-stage-stack-after.png) | 12.04 → 15.00 px | 136 → 289 px | false → false |
+| [Execution and failure lanes](../../../../test/fixtures/reader-readability/execution-failure-stack.workflow.json) | [Before](execution-failure-stack-before.png) | [After](execution-failure-stack-after.png) | 10.24 → 15.00 px | 199 → 549 px | false → false |
+
+Both candidates reach the existing 1.5× SVG enlargement cap. Larger labels cost more vertical page scrolling. The Dock temporarily overlays the SVG area at the viewport floor on the initial screen; no primary node rectangles intersect the Dock in these examples. Bottom scrolling exposes the remaining stages completely. This evidence does not establish that the balance is optimal: maintainers should judge the before/after images and the readability-versus-overview tradeoff. The existing `visual-check` reports minimum projected text conservatively with a scale capped at 1, so its 8px result is distinct from the actual displayed primary-label font measurements above.
+
+## Reproduce
+
+Use official Node 22, Chrome, and install both root and `archify/` dependencies in the candidate. Use a clean checkout or archive of the pinned base as `/tmp/archify-pr4-baseline`, with its renderer dependencies installed. From the candidate repository root:
+
+```sh
+export ARCHIFY_CHROME='/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'
+node scripts/capture-workflow-reader-width.mjs /tmp/archify-pr4-baseline /tmp/workflow-reader-width-evidence
+node archify/bin/archify.mjs render workflow test/fixtures/reader-readability/five-stage-stack.workflow.json /tmp/five-stage-stack.html --quality showcase
+node archify/bin/archify.mjs render workflow test/fixtures/reader-readability/execution-failure-stack.workflow.json /tmp/execution-failure-stack.html --quality showcase
+node archify/bin/archify.mjs visual-check /tmp/five-stage-stack.html --json
+node archify/bin/archify.mjs visual-check /tmp/execution-failure-stack.html --json
+node --test test/workflow-compiler.test.mjs
+node test/golden.mjs
+npm --prefix archify run check:validators
+node --test test/desktop-reader-browser.test.mjs test/reader-layout-browser.test.mjs
+```
+
+The capture output directory must not already contain the screenshot names (the browser writes them exclusively). [Measurements](measurements.json) preserve the full per-label values. Browser checks establish containment, readability floors, the enlargement cap, and retained authored geometry; they are separate from maintainer perceptual review. Embed, Present, and print remain on their previous layout path.
diff --git a/docs/assets/reviews/workflow-reader-width/execution-failure-stack-after.png b/docs/assets/reviews/workflow-reader-width/execution-failure-stack-after.png
new file mode 100644
index 00000000..7f65d56a
Binary files /dev/null and b/docs/assets/reviews/workflow-reader-width/execution-failure-stack-after.png differ
diff --git a/docs/assets/reviews/workflow-reader-width/execution-failure-stack-before.png b/docs/assets/reviews/workflow-reader-width/execution-failure-stack-before.png
new file mode 100644
index 00000000..264928d9
Binary files /dev/null and b/docs/assets/reviews/workflow-reader-width/execution-failure-stack-before.png differ
diff --git a/docs/assets/reviews/workflow-reader-width/five-stage-stack-after.png b/docs/assets/reviews/workflow-reader-width/five-stage-stack-after.png
new file mode 100644
index 00000000..b612658f
Binary files /dev/null and b/docs/assets/reviews/workflow-reader-width/five-stage-stack-after.png differ
diff --git a/docs/assets/reviews/workflow-reader-width/five-stage-stack-before.png b/docs/assets/reviews/workflow-reader-width/five-stage-stack-before.png
new file mode 100644
index 00000000..605ad15c
Binary files /dev/null and b/docs/assets/reviews/workflow-reader-width/five-stage-stack-before.png differ
diff --git a/docs/assets/reviews/workflow-reader-width/measurements.json b/docs/assets/reviews/workflow-reader-width/measurements.json
new file mode 100644
index 00000000..51411252
--- /dev/null
+++ b/docs/assets/reviews/workflow-reader-width/measurements.json
@@ -0,0 +1,213 @@
+{
+ "baseline": "e23fc2c5c8cf1aaa3864e7966f8b8ec43dc2bebd",
+ "records": [
+ {
+ "name": "five-stage-stack",
+ "revision": "before",
+ "screenshot": "five-stage-stack-before.png",
+ "viewport": [
+ 1440,
+ 1000
+ ],
+ "theme": "light",
+ "preset": "signal-flow",
+ "readerFit": "intrinsic-height",
+ "svgWidth": 925,
+ "viewBoxWidth": 768,
+ "gateMinimumProjectedNodeTextPx": 8,
+ "scrollY": 0,
+ "scrollHeight": 1136,
+ "pageScrollPx": 136,
+ "overflowX": false,
+ "zoom": "100%",
+ "minimumActualNodeFontPx": 12.044229233226837,
+ "fonts": [
+ {
+ "text": "Build preview",
+ "pixelFont": 12.887325279552716
+ },
+ {
+ "text": "Check format",
+ "pixelFont": 13.248652156549522
+ },
+ {
+ "text": "Collect input",
+ "pixelFont": 12.887325279552716
+ },
+ {
+ "text": "Publish result",
+ "pixelFont": 12.044229233226837
+ },
+ {
+ "text": "Review output",
+ "pixelFont": 12.887325279552716
+ }
+ ],
+ "dockCoveredNodesAtPageTop": [],
+ "dockOverlapsSvgAtPageTop": false,
+ "bottomScroll": {
+ "scrollY": 136,
+ "lowestNodeBottom": 596.4901123046875,
+ "allNodesAboveViewportBottom": true
+ }
+ },
+ {
+ "name": "five-stage-stack",
+ "revision": "after",
+ "screenshot": "five-stage-stack-after.png",
+ "viewport": [
+ 1440,
+ 1000
+ ],
+ "theme": "light",
+ "preset": "signal-flow",
+ "readerFit": "width-first",
+ "svgWidth": 1152,
+ "viewBoxWidth": 768,
+ "gateMinimumProjectedNodeTextPx": 8,
+ "scrollY": 0,
+ "scrollHeight": 1289,
+ "pageScrollPx": 289,
+ "overflowX": false,
+ "zoom": "100%",
+ "minimumActualNodeFontPx": 15,
+ "fonts": [
+ {
+ "text": "Build preview",
+ "pixelFont": 16.049999999999997
+ },
+ {
+ "text": "Check format",
+ "pixelFont": 16.5
+ },
+ {
+ "text": "Collect input",
+ "pixelFont": 16.049999999999997
+ },
+ {
+ "text": "Publish result",
+ "pixelFont": 15
+ },
+ {
+ "text": "Review output",
+ "pixelFont": 16.049999999999997
+ }
+ ],
+ "dockCoveredNodesAtPageTop": [],
+ "dockOverlapsSvgAtPageTop": true,
+ "bottomScroll": {
+ "scrollY": 289,
+ "lowestNodeBottom": 590.6875,
+ "allNodesAboveViewportBottom": true
+ }
+ },
+ {
+ "name": "execution-failure-stack",
+ "revision": "before",
+ "screenshot": "execution-failure-stack-before.png",
+ "viewport": [
+ 1440,
+ 1000
+ ],
+ "theme": "light",
+ "preset": "signal-flow",
+ "readerFit": "intrinsic-height",
+ "svgWidth": 799,
+ "viewBoxWidth": 780,
+ "gateMinimumProjectedNodeTextPx": 8,
+ "scrollY": 0,
+ "scrollHeight": 1199,
+ "pageScrollPx": 199,
+ "overflowX": false,
+ "zoom": "100%",
+ "minimumActualNodeFontPx": 10.243503736413045,
+ "fonts": [
+ {
+ "text": "Execute job",
+ "pixelFont": 11.26785411005435
+ },
+ {
+ "text": "Store result",
+ "pixelFont": 11.26785411005435
+ },
+ {
+ "text": "Prepare job",
+ "pixelFont": 11.26785411005435
+ },
+ {
+ "text": "Inspect error",
+ "pixelFont": 10.960548997961956
+ },
+ {
+ "text": "Record failure",
+ "pixelFont": 10.243503736413045
+ },
+ {
+ "text": "Queue retry",
+ "pixelFont": 11.26785411005435
+ }
+ ],
+ "dockCoveredNodesAtPageTop": [],
+ "dockOverlapsSvgAtPageTop": false,
+ "bottomScroll": {
+ "scrollY": 199,
+ "lowestNodeBottom": 556.4925537109375,
+ "allNodesAboveViewportBottom": true
+ }
+ },
+ {
+ "name": "execution-failure-stack",
+ "revision": "after",
+ "screenshot": "execution-failure-stack-after.png",
+ "viewport": [
+ 1440,
+ 1000
+ ],
+ "theme": "light",
+ "preset": "signal-flow",
+ "readerFit": "width-first",
+ "svgWidth": 1170,
+ "viewBoxWidth": 780,
+ "gateMinimumProjectedNodeTextPx": 8,
+ "scrollY": 0,
+ "scrollHeight": 1549,
+ "pageScrollPx": 549,
+ "overflowX": false,
+ "zoom": "100%",
+ "minimumActualNodeFontPx": 15,
+ "fonts": [
+ {
+ "text": "Execute job",
+ "pixelFont": 16.5
+ },
+ {
+ "text": "Store result",
+ "pixelFont": 16.5
+ },
+ {
+ "text": "Prepare job",
+ "pixelFont": 16.5
+ },
+ {
+ "text": "Inspect error",
+ "pixelFont": 16.049999999999997
+ },
+ {
+ "text": "Record failure",
+ "pixelFont": 15
+ },
+ {
+ "text": "Queue retry",
+ "pixelFont": 16.5
+ }
+ ],
+ "dockCoveredNodesAtPageTop": [],
+ "dockOverlapsSvgAtPageTop": true,
+ "bottomScroll": {
+ "scrollY": 549,
+ "lowestNodeBottom": 495.6875,
+ "allNodesAboveViewportBottom": true
+ }
+ }
+ ]
+}
diff --git a/scripts/capture-workflow-reader-width.mjs b/scripts/capture-workflow-reader-width.mjs
new file mode 100644
index 00000000..896ad047
--- /dev/null
+++ b/scripts/capture-workflow-reader-width.mjs
@@ -0,0 +1,69 @@
+// Public synthetic evidence, fixed input and browser conditions on both revisions.
+import fs from 'node:fs';
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+import { ChromeVisualBrowser, findChrome } from '../archify/bin/visual-check.mjs';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const beforeRoot = process.argv[2];
+if (!beforeRoot) throw new Error('Usage: node scripts/capture-workflow-reader-width.mjs <baseline-checkout> [output-directory]');
+const output = path.resolve(process.argv[3] || path.join(root, 'docs/assets/reviews/workflow-reader-width'));
+fs.mkdirSync(output, { recursive: true });
+const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-workflow-width-'));
+const browser = new ChromeVisualBrowser(findChrome());
+const records = [];
+try {
+ for (const name of ['five-stage-stack', 'execution-failure-stack']) {
+ const input = path.join(root, 'test/fixtures/reader-readability', `${name}.workflow.json`);
+ let baselineHtml;
+ for (const [revision, checkout] of [['before', path.resolve(beforeRoot)], ['after', root]]) {
+ const artifact = path.join(scratch, `${name}-${revision}.html`);
+ execFileSync(process.execPath, [path.join(checkout, 'archify/bin/archify.mjs'), 'render', 'workflow', input, artifact, '--quality', 'showcase']);
+ const html = fs.readFileSync(artifact, 'utf8');
+ if (revision === 'before') baselineHtml = html;
+ else assert.equal(html.replace('data-reader-fit="width-first"', 'data-reader-fit="intrinsic-height"'), baselineHtml, 'Only the reader-fit declaration may differ');
+ const screenshot = `${name}-${revision}.png`;
+ const metrics = await browser.inspect({ artifactPath: artifact, width: 1440, height: 1000,
+ theme: 'light', screenshotPath: path.join(output, screenshot) });
+ const session = await browser.sessionPromise;
+ const measured = await browser.cdp.send('Runtime.evaluate', { returnByValue: true, expression: `(() => {
+ const svg = document.querySelector('.diagram-container svg');
+ const fonts = [...svg.querySelectorAll('text[data-node-label]')].map(el => {
+ const matrix = el.getScreenCTM();
+ return {text: el.textContent.trim(), pixelFont: parseFloat(getComputedStyle(el).fontSize) * Math.hypot(matrix.a, matrix.b)};
+ });
+ const dock = document.querySelector('.diagram-nav');
+ const rect = dock && dock.getBoundingClientRect();
+ const coveredNodes = rect ? [...svg.querySelectorAll('g[data-node-id]')].filter(el => {
+ const r = el.getBoundingClientRect();
+ return r.right > rect.left && r.left < rect.right && r.bottom > rect.top && r.top < rect.bottom;
+ }).map(el => el.getAttribute('data-node-id')) : [];
+ return {scrollY, scrollHeight: document.documentElement.scrollHeight,
+ pageScrollPx: document.documentElement.scrollHeight - innerHeight,
+ overflowX: document.documentElement.scrollWidth > innerWidth,
+ zoom: document.querySelector('[data-view-percent]')?.textContent || null,
+ minimumActualNodeFontPx: Math.min(...fonts.map(f => f.pixelFont)), fonts, dockCoveredNodesAtPageTop: coveredNodes,
+ dockOverlapsSvgAtPageTop: Boolean(rect && svg.getBoundingClientRect().bottom > rect.top && svg.getBoundingClientRect().right > rect.left)};
+ })()` }, session);
+ assert.equal(measured.result.value.zoom, '100%');
+ assert.equal(measured.result.value.scrollY, 0);
+ assert.equal(measured.result.value.overflowX, false);
+ const scroll = await browser.cdp.send('Runtime.evaluate', {returnByValue: true, awaitPromise: true, expression: `(async () => {
+ scrollTo(0, document.documentElement.scrollHeight); await new Promise(r => requestAnimationFrame(() => requestAnimationFrame(r)));
+ const bottoms = [...document.querySelectorAll('.diagram-container svg g[data-node-id]')].map(el => el.getBoundingClientRect().bottom);
+ return {scrollY, lowestNodeBottom: Math.max(...bottoms), allNodesAboveViewportBottom: Math.max(...bottoms) <= innerHeight};
+ })()`}, session);
+ records.push({name, revision, screenshot, viewport: [1440,1000], theme:'light', preset:'signal-flow',
+ readerFit: metrics.readerFit, svgWidth: metrics.diagramWidth, viewBoxWidth: metrics.viewBoxWidth,
+ gateMinimumProjectedNodeTextPx: metrics.minimumProjectedNodeTextPx,
+ ...measured.result.value, bottomScroll: scroll.result.value});
+ }
+ }
+ fs.writeFileSync(path.join(output, 'measurements.json'), JSON.stringify({baseline: 'e23fc2c5c8cf1aaa3864e7966f8b8ec43dc2bebd', records}, null, 2) + '\n');
+} finally {
+ await browser.close();
+ fs.rmSync(scratch, {recursive:true, force:true});
+}
diff --git a/test/desktop-reader-browser.test.mjs b/test/desktop-reader-browser.test.mjs
index 2e8f2d2a..ddf62c58 100644
--- a/test/desktop-reader-browser.test.mjs
+++ b/test/desktop-reader-browser.test.mjs
@@ -414,7 +414,7 @@ test('offline intrinsic workflows fit while authored overflow still identifies l
}
});
-test('issue #250 tall intrinsic workflow fits every required desktop viewport', {
+test('issue #250 tall intrinsic workflow uses reading width and permits readable page scroll', {
skip: chromePath ? false : 'Set ARCHIFY_CHROME to run the real browser regression.',
}, async () => {
const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-issue-250-reader-'));
@@ -440,8 +440,10 @@ test('issue #250 tall intrinsic workflow fits every required desktop viewport',
assert.equal(result.receipt.containment.viewports.length, 4);
for (const viewport of result.receipt.containment.viewports) {
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.readerFit, 'width-first');
+ assert.equal(viewport.overflowY, viewport.verticalScrollAccepted, JSON.stringify(viewport, null, 2));
+ assert.ok(viewport.scrollHeight >= viewport.height, JSON.stringify(viewport, null, 2));
+ assert.ok(viewport.diagramWidth <= viewport.viewBoxWidth * 1.5 + 1);
assert.ok(viewport.minimumProjectedNodeTextPx >= MIN_PROJECTED_NODE_TEXT_PX);
}
assert.deepEqual(
@@ -460,7 +462,7 @@ test('issue #250 tall intrinsic workflow fits every required desktop viewport',
}
});
-test('issue #250 five-stage stack fits below source scale without crossing the readability floor', {
+test('issue #250 five-stage stack retains reading scale within the automatic enlargement cap', {
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-'));
@@ -481,15 +483,18 @@ test('issue #250 five-stage stack fits below source scale without crossing the r
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.overflowX, false, JSON.stringify(viewport, null, 2));
+ assert.equal(viewport.readerFit, 'width-first');
+ assert.equal(viewport.overflowY, viewport.verticalScrollAccepted, JSON.stringify(viewport, null, 2));
+ assert.ok(viewport.scrollHeight >= viewport.height, JSON.stringify(viewport, null, 2));
+ assert.ok(viewport.diagramWidth <= viewport.viewBoxWidth * 1.5 + 1);
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));
+ assert.ok(desktop.diagramWidth >= desktop.viewBoxWidth, 'use available reading width instead of shrinking the stack: ' + JSON.stringify(desktop, null, 2));
} finally {
fs.rmSync(tmp, { recursive: true, force: true });
}
diff --git a/test/fixtures/reader-readability/execution-failure-stack.workflow.json b/test/fixtures/reader-readability/execution-failure-stack.workflow.json
new file mode 100644
index 00000000..5817231e
--- /dev/null
+++ b/test/fixtures/reader-readability/execution-failure-stack.workflow.json
@@ -0,0 +1,120 @@
+{
+ "schema_version": 2,
+ "diagram_type": "workflow",
+ "meta": {
+ "title": "Execution and failure workflow",
+ "subtitle": "Synthetic example: execute a job or retain a failure record",
+ "output": "execution-failure-stack.html",
+ "visual_preset": "signal-flow",
+ "legend": {
+ "mode": "hidden"
+ }
+ },
+ "lanes": [
+ {
+ "id": "execution",
+ "label": "Job execution"
+ },
+ {
+ "id": "failure",
+ "label": "Failure recovery",
+ "variant": "exception"
+ }
+ ],
+ "nodes": [
+ {
+ "id": "prepare",
+ "lane": "execution",
+ "col": 1,
+ "type": "backend",
+ "label": "Prepare job",
+ "sublabel": "Validated input",
+ "yOffset": -90
+ },
+ {
+ "id": "execute",
+ "lane": "execution",
+ "col": 1,
+ "type": "backend",
+ "label": "Execute job",
+ "sublabel": "Bounded work",
+ "yOffset": 0
+ },
+ {
+ "id": "finish",
+ "lane": "execution",
+ "col": 1,
+ "type": "backend",
+ "label": "Store result",
+ "sublabel": "Completed job",
+ "yOffset": 90
+ },
+ {
+ "id": "record",
+ "lane": "failure",
+ "col": 1,
+ "type": "security",
+ "label": "Record failure",
+ "sublabel": "Reason and trace",
+ "yOffset": -90
+ },
+ {
+ "id": "inspect",
+ "lane": "failure",
+ "col": 1,
+ "type": "security",
+ "label": "Inspect error",
+ "sublabel": "Manual diagnosis",
+ "yOffset": 0
+ },
+ {
+ "id": "retry",
+ "lane": "failure",
+ "col": 1,
+ "type": "security",
+ "label": "Queue retry",
+ "sublabel": "Fresh attempt",
+ "yOffset": 90
+ }
+ ],
+ "edges": [
+ {
+ "id": "prepare-execute",
+ "from": "prepare",
+ "to": "execute",
+ "fromSide": "bottom",
+ "toSide": "top"
+ },
+ {
+ "id": "execute-finish",
+ "from": "execute",
+ "to": "finish",
+ "fromSide": "bottom",
+ "toSide": "top"
+ },
+ {
+ "id": "execute-record",
+ "from": "execute",
+ "to": "record",
+ "role": "error",
+ "variant": "security",
+ "fromSide": "right",
+ "toSide": "right",
+ "route": "outside-right"
+ },
+ {
+ "id": "record-inspect",
+ "from": "record",
+ "to": "inspect",
+ "fromSide": "bottom",
+ "toSide": "top"
+ },
+ {
+ "id": "inspect-retry",
+ "from": "inspect",
+ "to": "retry",
+ "fromSide": "bottom",
+ "toSide": "top"
+ }
+ ]
+}
diff --git a/test/fixtures/reader-readability/five-stage-stack.workflow.json b/test/fixtures/reader-readability/five-stage-stack.workflow.json
new file mode 100644
index 00000000..12c2f5b3
--- /dev/null
+++ b/test/fixtures/reader-readability/five-stage-stack.workflow.json
@@ -0,0 +1,96 @@
+{
+ "schema_version": 2,
+ "diagram_type": "workflow",
+ "meta": {
+ "title": "Five-stage public workflow",
+ "subtitle": "Synthetic example: a small publishing pipeline",
+ "output": "five-stage-stack.html",
+ "visual_preset": "signal-flow",
+ "legend": {
+ "mode": "hidden"
+ }
+ },
+ "lanes": [
+ {
+ "id": "pipeline",
+ "label": "Publishing pipeline"
+ }
+ ],
+ "nodes": [
+ {
+ "id": "collect",
+ "lane": "pipeline",
+ "col": 1,
+ "type": "backend",
+ "label": "Collect input",
+ "sublabel": "Public draft",
+ "yOffset": -180
+ },
+ {
+ "id": "check",
+ "lane": "pipeline",
+ "col": 1,
+ "type": "backend",
+ "label": "Check format",
+ "sublabel": "Schema rules",
+ "yOffset": -90
+ },
+ {
+ "id": "build",
+ "lane": "pipeline",
+ "col": 1,
+ "type": "backend",
+ "label": "Build preview",
+ "sublabel": "Local artifact",
+ "yOffset": 0
+ },
+ {
+ "id": "review",
+ "lane": "pipeline",
+ "col": 1,
+ "type": "backend",
+ "label": "Review output",
+ "sublabel": "Human inspection",
+ "yOffset": 90
+ },
+ {
+ "id": "publish",
+ "lane": "pipeline",
+ "col": 1,
+ "type": "backend",
+ "label": "Publish result",
+ "sublabel": "Public page",
+ "yOffset": 180
+ }
+ ],
+ "edges": [
+ {
+ "id": "collect-check",
+ "from": "collect",
+ "to": "check",
+ "fromSide": "bottom",
+ "toSide": "top"
+ },
+ {
+ "id": "check-build",
+ "from": "check",
+ "to": "build",
+ "fromSide": "bottom",
+ "toSide": "top"
+ },
+ {
+ "id": "build-review",
+ "from": "build",
+ "to": "review",
+ "fromSide": "bottom",
+ "toSide": "top"
+ },
+ {
+ "id": "review-publish",
+ "from": "review",
+ "to": "publish",
+ "fromSide": "bottom",
+ "toSide": "top"
+ }
+ ]
+}
diff --git a/test/reader-layout-browser.test.mjs b/test/reader-layout-browser.test.mjs
index d1e147dd..0e983059 100644
--- a/test/reader-layout-browser.test.mjs
+++ b/test/reader-layout-browser.test.mjs
@@ -609,7 +609,13 @@ test('Reader Layout preserves final-artifact behavior across its ownership bound
participants: [{ id: 'a', type: 'external', label: 'Client' }, { id: 'b', type: 'backend', label: 'Server' }],
messages: [{ from: 'a', to: 'b', y: 160, label: 'ping' }] };
const waterfall = JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples/checkout-request.waterfall.json'), 'utf8'));
- for (const [mode, doc] of [['sequence', sequence], ['waterfall', waterfall]]) {
+ const workflow = { schema_version: 2, diagram_type: 'workflow',
+ meta: { title: 'Reader stacked workflow', output: 'reader-workflow.html', legend: { mode: 'hidden' } },
+ lanes: [{ id: 'runtime', label: 'Runtime' }],
+ nodes: [-180, -90, 0, 90, 180].map((yOffset, index) => ({
+ id: `stage-${index}`, lane: 'runtime', col: 2, type: 'backend', label: `Stage ${index + 1}`, yOffset,
+ })), edges: [] };
+ for (const [mode, doc] of [['sequence', sequence], ['waterfall', waterfall], ['workflow', workflow]]) {
const input = path.join(scratch, `${mode}-automatic.json`);
const output = path.join(scratch, `${mode}-automatic.html`);
fs.writeFileSync(input, JSON.stringify(doc));
@@ -629,8 +635,15 @@ test('Reader Layout preserves final-artifact behavior across its ownership bound
else assert.ok(fallback.receipt.width <= declared.receipt.width);
for (const query of ['&embed=1', '&present=1']) {
await load(output, { query });
- inactive(await snapshot(`${mode}-${query}`), declared.receipt.ratio >= 1.55);
+ const alternate = await snapshot(`${mode}-${query}`);
+ inactive(alternate, declared.receipt.ratio >= 1.55);
+ assert.deepEqual(alternate.geometry, declared.geometry);
}
+ await load(output, { print: true });
+ const printed = await snapshot(`${mode}-print`);
+ inactive(printed, declared.receipt.ratio >= 1.55);
+ assert.deepEqual(printed.geometry, declared.geometry);
+ await media();
}
});
await t.test('desktop budgets, extreme content and limited horizontal space preserve geometry', async () => {
diff --git a/test/workflow-compiler.test.mjs b/test/workflow-compiler.test.mjs
index cc60e57c..bef0cc07 100644
--- a/test/workflow-compiler.test.mjs
+++ b/test/workflow-compiler.test.mjs
@@ -481,27 +481,31 @@ test('absolute route pins retain shared-height readable-v2 geometry', () => {
assert.deepEqual([0, 1, 2].map((index) => laneFrameRect(result.svg, index).height), [276, 270, 270]);
});
-test('a measured intrinsic readable-v2 tall lane opts into height-aware reader fitting', () => {
+test('an automatic readable-v2 vertical stack opts into width-first reader fitting', () => {
const result = compileSuccessfully(stackedGroupWorkflow({
schemaVersion: 2,
offsets: [-90, 0, 90],
}));
const svgRoot = result.svg.match(/<svg\b[^>]*>/)?.[0];
assert.ok(svgRoot, 'expected an SVG root');
- assert.equal(attribute(svgRoot, 'data-reader-fit'), 'intrinsic-height');
+ assert.equal(attribute(svgRoot, 'data-reader-fit'), 'width-first');
});
-test('height-aware reader fitting stays off for authored canvases, fixed-v1, and baseline lanes', () => {
+test('stack reader fitting stays off for authored canvases, fixed-v1, and workflows without a vertical stack', () => {
const authoredCanvas = stackedGroupWorkflow({ schemaVersion: 2, offsets: [-90, 0, 90] });
authoredCanvas.meta.viewBox = [768, 452];
+ const tallWithoutStack = adjacentWorkflow();
+ tallWithoutStack.nodes.forEach((node) => { node.height = 130; });
const cases = [
['authored readable-v2 canvas', authoredCanvas],
['fixed-v1 workflow', stackedGroupWorkflow({ offsets: [0] })],
['baseline readable-v2 lane', adjacentWorkflow()],
+ ['tall readable-v2 lane without a vertical stack', tallWithoutStack],
];
for (const [description, workflow] of cases) {
const result = compileSuccessfully(workflow);
+ if (workflow === tallWithoutStack) assert.ok(laneFrameRect(result.svg, 0).height > 104);
const svgRoot = result.svg.match(/<svg\b[^>]*>/)?.[0];
assert.ok(svgRoot, `${description}: expected an SVG root`);
assert.equal(
diff --git a/viewer/README.md b/viewer/README.md
index 1c9c5e36..4259244e 100644
--- a/viewer/README.md
+++ b/viewer/README.md
@@ -586,12 +586,14 @@ The source split narrows maintenance scope while preserving runtime dependencies
`data-reader-fit="width-first"` selects available desktop reading width;
`data-reader-fit="intrinsic-height"` selects height fitting. Both declare
automatic canvases and share the existing readability and enlargement limits.
- Automatic Sequence and Waterfall canvases declare `width-first` and retain
+ Automatic Sequence and Waterfall canvases, and intrinsic v2 Workflow canvases
+ with expanded vertical stacks, declare `width-first` and retain
vertical page scroll;
overflow settling must not shrink them back to fit the viewport height.
Undeclared SVGs retain the ordinary ratio-based eligibility and fit; UI or
- column attributes alone do not opt into either automatic fit. Other diagram
- families retain height fitting. All automatic canvases cap
+ column attributes alone do not opt into either automatic fit. Other automatic
+ canvases retain height fitting. Explicit Workflow canvases retain their existing
+ fitting behavior. All automatic canvases cap
enlargement at 1.5 times the authored SVG width without reducing the outer
reading area. Capped SVGs are centered inside that area; uncapped diagrams
retain their existing natural flow. In a capped reader area, the original