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): fit intrinsic tall workflows

sunsunsun2f19ae83e69a
diff --git a/archify/assets/template.html b/archify/assets/template.html
index 28c151c1..ad454dc4 100644
--- a/archify/assets/template.html
+++ b/archify/assets/template.html
@@ -601,10 +601,11 @@
color: var(--frontend-stroke);
}
- /* The reader owns only the outer scale. Wide diagrams keep one authored
- SVG/viewBox while the runtime chooses a desktop width from the actual
- vertical budget. This avoids device-specific files and breakpoint
- jumps between a laptop and a tall monitor. */
+ /* The reader owns only the outer scale. Wide diagrams and compiler-marked
+ intrinsic tall workflows keep one authored SVG/viewBox while the runtime
+ chooses a desktop width from the actual vertical budget. This avoids
+ device-specific files and breakpoint jumps between a laptop and a tall
+ monitor. */
.container {
width: 100%;
max-width: var(--archify-reader-width, 1440px);
@@ -10775,10 +10776,10 @@
/* ============================================================
Adaptive Reader Shell — one diagram across laptop and monitor.
The canonical SVG and viewBox never change. On ordinary desktop pages,
- wide diagrams receive only enough outer width to use the available
- height without pushing summary cards below the viewport. Mobile,
- embed, presentation, print, and non-wide diagrams retain their own
- established layout contracts.
+ wide diagrams and compiler-approved intrinsic tall workflows receive
+ only enough outer width to use the available height without pushing
+ summary cards below the viewport. Mobile, embed, presentation, print,
+ and unmarked non-wide diagrams retain their established contracts.
============================================================ */
Archify.waitForStableLayout = function (options) {
options = options || {};
@@ -10831,6 +10832,7 @@
var cards = shell && shell.querySelector('.cards');
var viewBox = svg && svg.viewBox && svg.viewBox.baseVal;
var ratio = viewBox && viewBox.height > 0 ? viewBox.width / viewBox.height : 0;
+ var intrinsicHeightFit = svg && svg.getAttribute('data-reader-fit') === 'intrinsic-height';
var frame = 0;
var settleFrame = 0;
var lastWidth = 0;
@@ -10859,7 +10861,7 @@
}
function eligible() {
return Boolean(
- shell && diagram && svg && ratio >= WIDE_RATIO &&
+ shell && diagram && svg && (ratio >= WIDE_RATIO || intrinsicHeightFit) &&
window.innerWidth >= MIN_DESKTOP_WIDTH &&
html.getAttribute('data-embed') !== 'true' &&
html.getAttribute('data-present') !== 'true' &&
@@ -10919,7 +10921,13 @@
}
var chrome = chromeMetrics();
var viewportCap = Math.max(0, window.innerWidth - chrome.bodyX);
- var minWidth = Math.min(MIN_READER_WIDTH, viewportCap);
+ var sourceWidth = viewBox && viewBox.width > 0
+ ? viewBox.width + chrome.diagramX
+ : MIN_READER_WIDTH;
+ var minWidth = Math.min(
+ intrinsicHeightFit && ratio < WIDE_RATIO ? sourceWidth : MIN_READER_WIDTH,
+ viewportCap
+ );
var maxWidth = Math.min(MAX_READER_WIDTH, viewportCap);
var fixedHeight = chrome.bodyY + chrome.diagramY + SAFE_BOTTOM_GAP +
outerHeight(header) + outerHeight(guided) + outerHeight(cards);
diff --git a/archify/renderers/workflow/README.md b/archify/renderers/workflow/README.md
index 126ec229..98345f2e 100644
--- a/archify/renderers/workflow/README.md
+++ b/archify/renderers/workflow/README.md
@@ -145,6 +145,12 @@ growth with a legal channel instead of widening every downstream rank. Measured
multi-row legends participate in intrinsic height and explicit viewBox
capacity.
+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.
+
Authored `via`, `labelAt`, `channelX`, and `channelY` are absolute hard pins in
v2; an infeasible pin returns `workflow/explicit-pin-conflict` rather than being
silently moved. `fromSide` and `toSide` remain direction constraints. A route
diff --git a/archify/renderers/workflow/workflow-compiler.mjs b/archify/renderers/workflow/workflow-compiler.mjs
index b628b19c..cc767ab3 100644
--- a/archify/renderers/workflow/workflow-compiler.mjs
+++ b/archify/renderers/workflow/workflow-compiler.mjs
@@ -4486,7 +4486,14 @@ function renderLegend() {
}
function renderSvg() {
- return ` <svg viewBox="0 0 ${viewBox[0]} ${viewBox[1]}" ${svgRootAttrs(workflow.meta, 'workflow diagram')}>
+ const readerFit = workflow.schema_version === 2
+ && !workflow.meta?.viewBox
+ && asArray(workflow.lanes).some((lane, index) => (
+ Number.isFinite(lane.height) && laneHeight(index) > 104
+ ))
+ ? ' data-reader-fit="intrinsic-height"'
+ : '';
+ return ` <svg viewBox="0 0 ${viewBox[0]} ${viewBox[1]}"${readerFit} ${svgRootAttrs(workflow.meta, 'workflow diagram')}>
${svgAccessibleText(workflow.meta, 'workflow')}
${renderDefinitions()}
diff --git a/archify/test/adaptive-reader-layout.test.mjs b/archify/test/adaptive-reader-layout.test.mjs
index 6a8fa7a1..4e7cdcfd 100644
--- a/archify/test/adaptive-reader-layout.test.mjs
+++ b/archify/test/adaptive-reader-layout.test.mjs
@@ -33,6 +33,14 @@ test('wide desktop diagrams use one height-budgeted reader shell instead of brea
assert.match(reader, /html\.style\.setProperty\('--archify-reader-width', rounded \+ 'px'\)/);
});
+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.doesNotMatch(reader, /function eligible\(\)[\s\S]{0,240}ratio > 0/);
+});
+
test('desktop readability budget matches the minimum adaptive reader at 1440 by 900', () => {
assert.deepEqual(DESKTOP_READABILITY_VIEWPORT, { width: 1440, height: 900 });
assert.equal(DESKTOP_READER_MIN_WIDTH, 960);
diff --git a/archify/test/desktop-reader-browser.test.mjs b/archify/test/desktop-reader-browser.test.mjs
index 867a7cb4..63f3f2a4 100644
--- a/archify/test/desktop-reader-browser.test.mjs
+++ b/archify/test/desktop-reader-browser.test.mjs
@@ -13,6 +13,30 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
const skillRoot = path.resolve(__dirname, '..');
const chromePath = process.env.ARCHIFY_CHROME ? findChrome() : null;
+const issue250TallGroup = {
+ schema_version: 2,
+ diagram_type: 'workflow',
+ meta: { title: 'Issue 250 stacked stages' },
+ lanes: [{ id: 'cage', label: 'One cage', height: 104 }],
+ groups: [{
+ id: 'group', label: 'Cage', lane: 'cage', fromCol: 1, toCol: 3, variant: 'security',
+ }],
+ mainPath: ['stageA', 'stageB', 'stageC'],
+ 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 },
+ ],
+ 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',
+ },
+ ],
+};
+
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 () => {
@@ -56,3 +80,47 @@ test('production showcase is readable in the real 1440 by 900 adaptive reader',
fs.rmSync(tmp, { recursive: true, force: true });
}
});
+
+test('issue #250 tall intrinsic workflow fits every required desktop viewport', {
+ 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-'));
+ const input = path.join(tmp, 'issue-250.workflow.json');
+ const artifact = path.join(tmp, 'issue-250.html');
+ try {
+ fs.writeFileSync(input, `${JSON.stringify(issue250TallGroup, 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));
+ assert.equal(result.receipt.containment.status, 'pass');
+ assert.equal(result.receipt.readability.status, 'pass');
+ assert.equal(result.receipt.viewerChrome.status, 'pass');
+ 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.ok(viewport.minimumProjectedNodeTextPx >= MIN_PROJECTED_NODE_TEXT_PX);
+ }
+ assert.deepEqual(
+ result.receipt.captures.screenshots.map(({ width, height, theme }) => ({ width, height, theme })),
+ [
+ { width: 1440, height: 900, theme: 'light' },
+ { width: 1440, height: 900, theme: 'dark' },
+ { width: 2048, height: 1320, theme: 'light' },
+ { width: 2048, height: 1320, theme: 'dark' },
+ ],
+ );
+ } finally {
+ fs.rmSync(tmp, { recursive: true, force: true });
+ }
+});
diff --git a/archify/test/workflow-compiler.test.mjs b/archify/test/workflow-compiler.test.mjs
index f270ddc3..678e73a7 100644
--- a/archify/test/workflow-compiler.test.mjs
+++ b/archify/test/workflow-compiler.test.mjs
@@ -438,6 +438,41 @@ test('issue #250: readable-v2 expands only the lane containing a vertical stack'
}
});
+test('issue #250: an intrinsic readable-v2 tall lane opts into height-aware reader fitting', () => {
+ const workflow = stackedGroupWorkflow({
+ schemaVersion: 2,
+ laneHeight: 104,
+ });
+
+ const result = compileSuccessfully(workflow);
+ const svgRoot = result.svg.match(/<svg\b[^>]*>/)?.[0];
+ assert.ok(svgRoot, 'expected an SVG root');
+ assert.equal(attribute(svgRoot, 'data-reader-fit'), 'intrinsic-height');
+});
+
+test('height-aware reader fitting stays off for authored canvases, fixed-v1, and baseline lanes', () => {
+ const intrinsicTall = stackedGroupWorkflow({ schemaVersion: 2, laneHeight: 104 });
+ const intrinsicResult = compileSuccessfully(intrinsicTall);
+ const authoredCanvas = clone(intrinsicTall);
+ authoredCanvas.meta.viewBox = [...intrinsicResult.receipt.requiredViewBox];
+
+ const cases = [
+ ['authored readable-v2 canvas', authoredCanvas],
+ ['fixed-v1 workflow', stackedGroupWorkflow({ laneHeight: 458 })],
+ ['baseline readable-v2 lane', adjacentWorkflow()],
+ ];
+ for (const [description, workflow] of cases) {
+ const result = compileSuccessfully(workflow);
+ const svgRoot = result.svg.match(/<svg\b[^>]*>/)?.[0];
+ assert.ok(svgRoot, `${description}: expected an SVG root`);
+ assert.equal(
+ attributeOrUndefined(svgRoot, 'data-reader-fit'),
+ undefined,
+ `${description}: must retain the established Viewer contract`,
+ );
+ }
+});
+
test('workflow lane.height is schema-validated as a 104px minimum', () => {
const workflow = adjacentWorkflow();
workflow.lanes[0].height = 103;