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
fix(workflow): read tall automatic stacks at page width
tt-a1ib7efd0414d8b
diff --git a/archify/renderers/workflow/README.md b/archify/renderers/workflow/README.mdindex 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 inv2; an infeasible pin returns `workflow/explicit-pin-conflict` rather than beingdiff --git a/archify/renderers/workflow/workflow-compiler.mjs b/archify/renderers/workflow/workflow-compiler.mjsindex 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.mdnew file mode 100644index 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.pngnew file mode 100644index 00000000..7f65d56aBinary files /dev/null and b/docs/assets/reviews/workflow-reader-width/execution-failure-stack-after.png differdiff --git a/docs/assets/reviews/workflow-reader-width/execution-failure-stack-before.png b/docs/assets/reviews/workflow-reader-width/execution-failure-stack-before.pngnew file mode 100644index 00000000..264928d9Binary files /dev/null and b/docs/assets/reviews/workflow-reader-width/execution-failure-stack-before.png differdiff --git a/docs/assets/reviews/workflow-reader-width/five-stage-stack-after.png b/docs/assets/reviews/workflow-reader-width/five-stage-stack-after.pngnew file mode 100644index 00000000..b612658fBinary files /dev/null and b/docs/assets/reviews/workflow-reader-width/five-stage-stack-after.png differdiff --git a/docs/assets/reviews/workflow-reader-width/five-stage-stack-before.png b/docs/assets/reviews/workflow-reader-width/five-stage-stack-before.pngnew file mode 100644index 00000000..605ad15cBinary files /dev/null and b/docs/assets/reviews/workflow-reader-width/five-stage-stack-before.png differdiff --git a/docs/assets/reviews/workflow-reader-width/measurements.json b/docs/assets/reviews/workflow-reader-width/measurements.jsonnew file mode 100644index 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.mjsnew file mode 100644index 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.mjsindex 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 rconst 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.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.mjsindex 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 boundparticipants: [{ 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 boundelse 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.mjsindex 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.mdindex 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 declareautomatic 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 retainvertical 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 capenlargement at 1.5 times the authored SVG width without reducing the outerreading area. Capped SVGs are centered inside that area; uncapped diagramsretain their existing natural flow. In a capped reader area, the original