Skip to content

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

fix(dataflow): honor CLI quality and fit all automatic canvas widths

tt-a1i22e6bef44402
diff --git a/archify/references/authoring-contract.md b/archify/references/authoring-contract.md
index f497fa3c..358dc5e5 100644
--- a/archify/references/authoring-contract.md
+++ b/archify/references/authoring-contract.md
@@ -322,6 +322,14 @@ Participants are ordered by conversation role. Messages own their vertical order
Stages express transformation or custody. Rows separate parallel streams. Label only data contracts, classifications, or cross-boundary movement that is not obvious.
+Omit `meta.viewBox` to fit canvas width to all stages and nodes in either quality
+profile, including explicit node widths. The 940px minimum and 24px right padding
+remain; left-edge overflow still needs a node repair. An authored viewBox stays
+fixed. Showcase node growth, readable typography, content height, port bridges
+and bounded label placement apply only when the canvas and all node widths are
+omitted. `--quality` overrides `meta.quality_profile`; without it, the renderer
+uses `ARCHIFY_QUALITY_PROFILE` when set, otherwise the JSON profile.
+
### ERD
Treat a schema ERD as a table catalogue as well as a relationship map. If the
diff --git a/archify/renderers/dataflow/README.md b/archify/renderers/dataflow/README.md
index f7604e1a..e48960ca 100644
--- a/archify/renderers/dataflow/README.md
+++ b/archify/renderers/dataflow/README.md
@@ -58,7 +58,7 @@ without a database node keeps it visual-only.
| Constant | Value |
|----------|-------|
-| viewBox | default `[940, 720]`; fully automatic showcase width covers all stage frames with 24px right padding (five stages need 1068), and height fits content; schema minimum `[360, 360]` |
+| viewBox | omitted width fits all stage frames and nodes, including authored widths, with a 940px floor and 24px right padding (five default-width stages need 1068); height defaults to 720 and fits content in fully automatic showcase; schema minimum `[360, 360]` |
| Stages (2–5) | centers at x = 100 + stage×215; stage band 168 wide, header at y 46 |
| Row tops (`row` 0–4) | y = 128, 242, 356, 470, 584 (plus `yOffset`) |
| Default node | 112×58 |
@@ -70,9 +70,16 @@ without a database node keeps it visual-only.
Route presets for flows: `straight`, `vertical-channel`, `bottom-channel`,
`top-channel`, explicit `via` points, or the default `auto` (midpoint elbow).
-Showcase improvements apply only when `meta.viewBox` and every node's `width`
-are omitted. Any authored canvas or node width preserves the established
-whole-diagram layout, as does `standard`.
+An authored `meta.viewBox` remains authoritative. When it is omitted, canvas
+width fits stage frames and nodes in both `standard` and `showcase`, including
+explicit node widths. Enlarging width cannot repair left-edge overflow.
+
+Showcase node sizing, typography, automatic height, port bridges and label
+placement apply only when `meta.viewBox` and every node's `width` are omitted.
+An authored canvas or node width preserves those established layout behaviors,
+as does `standard`. The effective quality profile is
+`process.env.ARCHIFY_QUALITY_PROFILE || meta.quality_profile`; the public CLI's
+`--quality standard|showcase` sets the environment override.
For a fully automatic showcase, node widths can grow within their stage and
canvas budget to keep supporting text readable at desktop projection. Height
diff --git a/archify/renderers/dataflow/render-dataflow.mjs b/archify/renderers/dataflow/render-dataflow.mjs
index a9cd2f27..3d9d5b8c 100644
--- a/archify/renderers/dataflow/render-dataflow.mjs
+++ b/archify/renderers/dataflow/render-dataflow.mjs
@@ -68,14 +68,18 @@ const layout = {
labelH: 16
};
-// Explicit geometry opts the whole diagram into the established layout. This
-// also preserves the spacing and typography around partially pinned nodes.
-const automaticShowcase = dataflow.meta?.quality_profile === 'showcase'
+// Explicit geometry preserves established node sizing, typography, height,
+// routing and label placement. An omitted canvas width still fits its content
+// in either profile, including authored node widths.
+const qualityProfile = process.env.ARCHIFY_QUALITY_PROFILE || dataflow.meta?.quality_profile;
+const automaticShowcase = qualityProfile === 'showcase'
&& dataflow.meta?.viewBox === undefined
&& !asArray(dataflow.nodes).some(node => node.width !== undefined);
const stageRight = stageX(asArray(dataflow.stages).length - 1) + layout.stageW / 2;
+const nodeRights = asArray(dataflow.nodes).map(node =>
+ stageX(node.stage) + (node.width || layout.nodeW) / 2).filter(Number.isFinite);
const viewBox = dataflow.meta?.viewBox || [
- automaticShowcase ? Math.max(940, Math.ceil(stageRight + 24)) : 940,
+ Math.max(940, Math.ceil(Math.max(stageRight, ...nodeRights) + 24)),
720,
];
const contextFontMinimum = automaticShowcase
diff --git a/test/dataflow-automatic-layout.test.mjs b/test/dataflow-automatic-layout.test.mjs
index e34ee419..0417f136 100644
--- a/test/dataflow-automatic-layout.test.mjs
+++ b/test/dataflow-automatic-layout.test.mjs
@@ -9,16 +9,20 @@ import test from 'node:test';
import { fileURLToPath } from 'node:url';
const cli = fileURLToPath(new URL('../archify/bin/archify.mjs', import.meta.url));
-function inspect(t, diagram) {
+function inspect(t, diagram, { quality, envQuality } = {}) {
const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-dataflow-auto-'));
t.after(() => fs.rmSync(cwd, { recursive: true, force: true }));
const input = path.join(cwd, 'source.json');
const source = JSON.stringify(diagram);
fs.writeFileSync(input, source);
- const result = spawnSync(process.execPath, [cli, 'validate', 'dataflow', input, '--json'], { encoding: 'utf8' });
+ const env = { ...process.env };
+ delete env.ARCHIFY_QUALITY_PROFILE;
+ if (envQuality !== undefined) env.ARCHIFY_QUALITY_PROFILE = envQuality;
+ const qualityArgs = quality ? ['--quality', quality] : [];
+ const result = spawnSync(process.execPath, [cli, 'validate', 'dataflow', input, '--json', ...qualityArgs], { encoding: 'utf8', env });
assert.equal(fs.readFileSync(input, 'utf8'), source, 'automatic layout must not rewrite authored input');
const receipt = JSON.parse(result.stdout);
- return { result, receipt, input, output: path.join(cwd, 'diagram.html') };
+ return { result, receipt, input, output: path.join(cwd, 'diagram.html'), env, qualityArgs };
}
function pipeline() {
return {
@@ -184,14 +188,82 @@ function smallFootprintDiagram(flow) {
};
}
-function footprintSvg(t, diagram) {
- const { result, input, output } = inspect(t, diagram);
+function footprintSvg(t, diagram, options) {
+ const { result, input, output, env, qualityArgs } = inspect(t, diagram, options);
assert.equal(result.status, 0, result.stdout + result.stderr);
- const render = spawnSync(process.execPath, [cli, 'render', 'dataflow', input, output], { encoding: 'utf8' });
+ const render = spawnSync(process.execPath, [cli, 'render', 'dataflow', input, output, ...qualityArgs], { encoding: 'utf8', env });
assert.equal(render.status, 0, render.stderr);
return fs.readFileSync(output, 'utf8').match(/<svg\b[^]*?<\/svg>/)[0];
}
+for (const [name, metaQuality, options] of [
+ ['CLI showcase without JSON profile', undefined, { quality: 'showcase' }],
+ ['CLI showcase overrides JSON standard', 'standard', { quality: 'showcase' }],
+ ['environment showcase overrides JSON standard', 'standard', { envQuality: 'showcase' }],
+ ['CLI showcase overrides environment standard', 'standard', { quality: 'showcase', envQuality: 'standard' }],
+]) {
+ test(`${name} enables the complete automatic showcase layout`, t => {
+ const diagram = pipeline();
+ if (metaQuality === undefined) delete diagram.meta.quality_profile;
+ else diagram.meta.quality_profile = metaQuality;
+ const svg = footprintSvg(t, diagram, options);
+ assert.match(svg, /viewBox="0 0 1068 512"/);
+ assert.match(svg, /data-reader-fit="intrinsic-height"/);
+ assert.ok(svg.includes(diagram.nodes[5].sublabel));
+ assert.equal(svg, footprintSvg(t, pipeline()), 'CLI/environment selection must match JSON showcase geometry');
+ });
+}
+
+function fiveStageDiagram(profile = 'standard') {
+ const diagram = pipeline();
+ diagram.meta.quality_profile = profile;
+ diagram.nodes = diagram.stages.map((_, stage) => ({ id: `n${stage}`, type: 'backend', label: 'Node', stage, row: 0 }));
+ diagram.flows = diagram.nodes.slice(1).map((node, index) => ({ id: `f${index}`, from: `n${index}`, to: node.id, label: 'd' }));
+ return diagram;
+}
+
+for (const [name, profile, options] of [
+ ['JSON standard fallback', 'standard', undefined],
+ ['missing profile standard default', undefined, undefined],
+ ['CLI standard overrides JSON showcase', 'showcase', { quality: 'standard' }],
+ ['environment standard overrides JSON showcase', 'showcase', { envQuality: 'standard' }],
+ ['CLI standard overrides environment showcase', 'showcase', { quality: 'standard', envQuality: 'showcase' }],
+]) {
+ test(`${name} fits five stages while preserving standard sizing and height`, t => {
+ const diagram = fiveStageDiagram(profile);
+ if (profile === undefined) delete diagram.meta.quality_profile;
+ const svg = footprintSvg(t, diagram, options);
+ assert.match(svg, /viewBox="0 0 1068 720"/);
+ assert.equal((svg.match(/width="112" height="58" rx="6" class="c-mask"/g) || []).length, 5);
+ assert.equal((svg.match(/data-composition-frame-kind="stage"/g) || []).length, 5);
+ });
+}
+
+for (const profile of ['standard', 'showcase']) {
+ test(`${profile} automatic width contains mixed authored and default node widths`, t => {
+ const diagram = fiveStageDiagram(profile);
+ diagram.nodes[0].width = 152;
+ diagram.nodes[4].width = 220;
+ const svg = footprintSvg(t, diagram);
+ assert.match(svg, /viewBox="0 0 1094 720"/);
+ assert.match(svg, /x="24" y="128" width="152" height="58"/);
+ assert.match(svg, /x="850" y="128" width="220" height="58"/);
+ assert.equal((svg.match(/width="112" height="58" rx="6" class="c-mask"/g) || []).length, 3);
+ });
+}
+
+test('an explicit insufficient canvas retains its width and bounds diagnostics', t => {
+ const diagram = fiveStageDiagram('showcase');
+ diagram.meta.viewBox = [940, 720];
+ const { result, receipt, input, output } = inspect(t, diagram, { quality: 'showcase' });
+ assert.equal(result.status, 1);
+ assert.ok(receipt.diagnostics.some(({ message }) => /Node "n4" exceeds the horizontal bounds/.test(message)));
+ assert.ok(receipt.diagnostics.some(({ message }) => /Stages exceed viewBox width/.test(message)));
+ const render = spawnSync(process.execPath, [cli, 'render', 'dataflow', input, output, '--quality', 'showcase'], { encoding: 'utf8' });
+ assert.equal(render.status, 1);
+ assert.equal(fs.existsSync(output), false, 'a fixed insufficient canvas must remain rejected');
+});
+
test('straight ignores inactive channelY in both route and natural height', t => {
const plain = footprintSvg(t, smallFootprintDiagram({ route: 'straight' }));
const inactive = footprintSvg(t, smallFootprintDiagram({ route: 'straight', channelY: 1500 }));