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
Wrap long linear workflows and mark decision nodes
tt-a1i28004f73d17e
diff --git a/archify/explainer/diagrams.mjs b/archify/explainer/diagrams.mjsindex fc7de7a0..eb693617 100644--- a/archify/explainer/diagrams.mjs+++ b/archify/explainer/diagrams.mjs@@ -191,6 +191,8 @@ export function compileExplainerDiagram(diagramType, rows, { title, id, line = 1// a narrower node drops the label below the icon, out of line with its neighbours.const labelWidth = Math.ceil(Math.max(textUnits(node.label) * 6.8 + 12, minimumNodeTextWidth(node.label, 11) + 2 * (SEMANTIC_SIGIL_FOOTPRINT + 2)));if (diagramType === 'workflow' && labelWidth > 92) node.width = labelWidth;+ // A question is a decision point: the native decision mark tells it apart from a step.+ if (diagramType === 'workflow' && /[??]$/u.test(node.label)) node.icon = 'decision';if (entry.parts[3]) nodeLanes.set(node.id, { lane: safeId(entry.parts[3], entry.context), context: entry.context });nodes.push(node);}@@ -235,9 +237,24 @@ export function compileExplainerDiagram(diagramType, rows, { title, id, line = 1if (spec.nodes.some(node => node.col > 5)) fail(context, 'diagram-shorthand-limit', 'A workflow lane holds at most six nodes.', 'Split the process into another lane.');spec.edges = edges;} else {- if (placed.some(node => node.col > 5)) fail(context, 'diagram-shorthand-limit', 'Native workflow columns are limited to 0–5.', 'Declare phase lanes with "lane <id> | label" rows and assign nodes to them.');- spec.lanes = Array.from({ length: Math.max(1, ...placed.map(node => node.row + 1)) }, (_, row) => ({ id: `lane-${row}`, label: row ? `分支 ${row}` : spec.meta.title }));- spec.nodes = placed.map(({ row, ...node }) => ({ ...node, lane: `lane-${row}` }));+ // A linear process too wide for one readable row wraps into rows of equal size, stepping down+ // where six columns allow, the same way declared phases do.+ const fits = laid => laid.every(node => node.col <= 5) && workflowWidth(laid, edges) <= READABLE_WORKFLOW_WIDTH;+ let wrapped;+ if (placed.every(node => node.row === 0) && !fits(placed)) {+ const ordered = [...placed].sort((a, b) => a.col - b.col);+ for (let size = 5; size >= 2 && !wrapped; size--) {+ const groups = Array.from({ length: Math.ceil(ordered.length / size) }, (_, i) => ordered.slice(i * size, i * size + size));+ for (const stair of [true, false]) {+ const laid = groups.flatMap((group, row) => group.map((node, i) => ({ ...node, row, col: (stair ? groups.slice(0, row).reduce((sum, g) => sum + g.length - 1, 0) : 0) + i })));+ if (fits(laid)) { wrapped = laid; break; }+ }+ }+ }+ const rows = wrapped || placed;+ if (rows.some(node => node.col > 5)) fail(context, 'diagram-shorthand-limit', 'Native workflow columns are limited to 0–5.', 'Declare phase lanes with "lane <id> | label" rows and assign nodes to them.');+ spec.lanes = Array.from({ length: Math.max(1, ...rows.map(node => node.row + 1)) }, (_, row) => ({ id: `lane-${row}`, label: wrapped ? `${spec.meta.title} · ${row + 1}` : row ? `分支 ${row}` : spec.meta.title }));+ spec.nodes = rows.map(({ row, ...node }) => ({ ...node, lane: `lane-${row}` }));spec.edges = edges;}} else if (diagramType === 'tree') {diff --git a/archify/explainer/reader.css b/archify/explainer/reader.cssindex 75780ba3..34ddc68f 100644--- a/archify/explainer/reader.css+++ b/archify/explainer/reader.css@@ -151,8 +151,9 @@ meter{width:100%;height:8px;accent-color:var(--accent)}.diagram-preview{flex:1;min-width:0;max-width:100%;overflow:auto;display:flex;align-items:center;padding:0}.diagram-preview>svg{display:block;width:min(100%,calc(var(--native-width,100vw) * 1.25))!important;margin-inline:auto;height:auto!important;min-height:0!important;max-height:none!important;max-width:none!important}.diagram-preview>svg>rect[fill^="url("],.diagram-preview [data-legend]{display:none}-/* A single lane is the whole diagram: the caption already names it, so its frame is noise. */-.single-lane rect[data-composition-frame-kind=lane],.single-lane rect[data-composition-frame-kind=lane]+text{display:none}+/* A single lane is the whole diagram, and lanes the shorthand adds only to stack branches carry no+ meaning: the caption names the diagram, so their frames and numbered labels are noise. */+.bare-lanes rect[data-composition-frame-kind=lane],.bare-lanes rect[data-composition-frame-kind=lane]+text{display:none}/* Phase labels then sit just above the nodes instead of above the hidden lane header. */.single-lane .phase-rule,.single-lane .phase-chip,.single-lane .phase-chip+text{transform:translateY(30px)}.diagram-preview text{font-family:var(--sans)!important}diff --git a/archify/explainer/render.mjs b/archify/explainer/render.mjsindex 6acbcf32..c2a4685c 100644--- a/archify/explainer/render.mjs+++ b/archify/explainer/render.mjs@@ -56,7 +56,7 @@ export function renderExplainer(document, options = {}) {break;}case 'steps': body = `<ol class="steps">${block.items.map(item => `<li id="${escape(item.id)}"><b>${item.target ? nativeLink(item.target,i(item.text)) : i(item.text)}</b>${item.detail ? `<p>${i(item.detail)}</p>` : ''}</li>`).join('')}</ol>`; break;- case 'diagram': { const diagram = diagrams[block.id]; if (!diagram?.svg || !diagram?.html) unavailable(block,`Missing prepared native diagram: ${block.id}`); const title = diagram.spec?.meta?.title || block.id; const svg = staticSvg(diagram.svg, block.id); const previewClass = previewPrefix(block.id); const nativeStyle = scopeNativeCss(diagram.styles ?? nativeStyles(diagram.html), '.' + previewClass, previewClass + '-', diagram.svg); const nativeWidth = Number(diagram.svg.match(/viewBox=["'][^"']*?[\d.-]+[ ,]+[\d.-]+[ ,]+([\d.]+)/)?.[1]); const singleLane = diagram.spec?.lanes?.length === 1 ? ' single-lane' : ''; body = `<figure class="diagram"><div class="diagram-preview ${previewClass}${singleLane}" role="img" aria-label="${escape(title)}"${nativeWidth > 0 ? ` style="--native-width:${Math.round(nativeWidth)}px"` : ''}><style>${nativeStyle}</style>${svg}</div><figcaption><span>${escape(title)}</span><button class="text-button interactive" type="button" data-open-diagram="${escape(block.id)}">${words.explore} ↗</button></figcaption></figure><p class="diagram-fit-status fine" role="status" hidden></p><details class="diagram-semantics" open><summary>${words.graph}</summary><ul>${(diagram.semantic?.nodes || []).map(node => `<li>${escape(node.label || node.id)} <code>${escape(node.id)}</code></li>`).join('')}${(diagram.semantic?.edges || []).map(edge => `<li><code>${escape(edge.from)}</code> → <code>${escape(edge.to)}</code>${edge.label ? ` · ${escape(edge.label)}` : ''}</li>`).join('')}</ul></details>${block.changes?.length ? `<dl class="changes"><dt>${words.changes}</dt>${block.changes.map(change => `<dd><span class="chip ${escape(change.change)}">${words[change.change]}</span> <code>${escape(change.target)}</code></dd>`).join('')}</dl>` : ''}`; break; }+ case 'diagram': { const diagram = diagrams[block.id]; if (!diagram?.svg || !diagram?.html) unavailable(block,`Missing prepared native diagram: ${block.id}`); const title = diagram.spec?.meta?.title || block.id; const svg = staticSvg(diagram.svg, block.id); const previewClass = previewPrefix(block.id); const nativeStyle = scopeNativeCss(diagram.styles ?? nativeStyles(diagram.html), '.' + previewClass, previewClass + '-', diagram.svg); const nativeWidth = Number(diagram.svg.match(/viewBox=["'][^"']*?[\d.-]+[ ,]+[\d.-]+[ ,]+([\d.]+)/)?.[1]); const lanes = diagram.spec?.lanes || [], singleLane = lanes.length === 1 ? ' single-lane bare-lanes' : lanes.length && lanes.every(lane => /^lane-\d+$/.test(lane.id)) ? ' bare-lanes' : ''; body = `<figure class="diagram"><div class="diagram-preview ${previewClass}${singleLane}" role="img" aria-label="${escape(title)}"${nativeWidth > 0 ? ` style="--native-width:${Math.round(nativeWidth)}px"` : ''}><style>${nativeStyle}</style>${svg}</div><figcaption><span>${escape(title)}</span><button class="text-button interactive" type="button" data-open-diagram="${escape(block.id)}">${words.explore} ↗</button></figcaption></figure><p class="diagram-fit-status fine" role="status" hidden></p><details class="diagram-semantics" open><summary>${words.graph}</summary><ul>${(diagram.semantic?.nodes || []).map(node => `<li>${escape(node.label || node.id)} <code>${escape(node.id)}</code></li>`).join('')}${(diagram.semantic?.edges || []).map(edge => `<li><code>${escape(edge.from)}</code> → <code>${escape(edge.to)}</code>${edge.label ? ` · ${escape(edge.label)}` : ''}</li>`).join('')}</ul></details>${block.changes?.length ? `<dl class="changes"><dt>${words.changes}</dt>${block.changes.map(change => `<dd><span class="chip ${escape(change.change)}">${words[change.change]}</span> <code>${escape(change.target)}</code></dd>`).join('')}</dl>` : ''}`; break; }case 'chart': { const chart = compileExplainerChart(block.text); if (chart.error) unavailable(block, chart.error); body = `<figure class="chart" style="--native-width:${Math.round(chart.width)}px">${chart.svg.replace(/^<svg\b[^>]*>/, tag => tag.replace(/\s(?:width|height)="[^"]*"/g, ''))}${block.title ? `<figcaption>${i(block.title)}</figcaption>` : ''}</figure>`; break; }case 'snippet': body = `<figure class="snippet"><figcaption><span class="snippet-label">${block.title ? i(block.title) : ''}${block.language ? `<code class="snippet-language">${escape(block.language)}</code>` : ''}</span><button class="text-button interactive" type="button" data-copy>${words.copy}</button></figcaption><pre><code${block.language ? ` class="language-${escape(block.language)}"` : ''}>${escape(block.text)}</code></pre></figure>`; break;case 'code': { const source = sources[block.source]; if (!source?.path || typeof source.text !== 'string') unavailable(block,`Code requires a Git excerpt: ${block.source}`); body = `<figure class="code"><figcaption>${i(`[](source:${block.source})`)}<span>${escape(source.path)}:${escape(source.lines?.join('–'))}</span></figcaption><pre><code${block.language ? ` class="language-${escape(block.language)}"` : ''}>${escape(source.text)}</code></pre></figure>`; break; }diff --git a/archify/references/explainer-authoring.md b/archify/references/explainer-authoring.mdindex 4e872c46..794ff982 100644--- a/archify/references/explainer-authoring.md+++ b/archify/references/explainer-authoring.md@@ -131,7 +131,7 @@ Actor rows: `actor <id> | label | type`. Message rows: `from | to | label | vari| trace > fix | cause found | emphasis |```-Node rows: `id | label | type?`. Edge rows: `from > to | label? | variant?`. Nodes widen to fit their labels, so a node label names the step in a few words (up to about 10 Chinese characters or 4 English words) and `@steps` carries the detail. Keep edge labels to one or two words.+Node rows: `id | label | type?`. Edge rows: `from > to | label? | variant?`. Nodes widen to fit their labels, so a node label names the step in a few words (up to about 10 Chinese characters or 4 English words) and `@steps` carries the detail. Keep edge labels to one or two words. A node label ending in `?` is drawn as a decision; label its outgoing edges with the answers (`yes`, `no`, `是`, `否`).Group the steps of a process into phases: declare `lane <id> | label` rows, then give each workflow node its phase as a fourth cell. Up to six nodes draw as one row with the phase labels above it; a longer process wraps into one row per phase.diff --git a/test/explainer-diagrams.test.mjs b/test/explainer-diagrams.test.mjsindex 7b22c2df..3179806b 100644--- a/test/explainer-diagrams.test.mjs+++ b/test/explainer-diagrams.test.mjs@@ -210,3 +210,16 @@ test('explainer diagrams: sequence phase rows become native segments over the foassert.ok(spec.segments[1].from < spec.messages[2].y && spec.segments[1].to > spec.messages[2].y);assert.throws(() => compileExplainerDiagram('sequence', ['b | s | SYN', 'phase | Empty'], { id: 'empty' }), error => (error.archifyDiagnostics || error.diagnostics || []).some(item => /phase needs/.test(item.message)));});++test('explainer diagrams: a linear workflow too wide for one row wraps into rows; questions get the decision mark', () => {+ const long = (i) => `step${i} | Step ${i} with a deliberately long label for width | backend`;+ const rows = [1, 2, 3, 4, 5, 6, 7].map(long).concat([1, 2, 3, 4, 5, 6].map(i => `step${i} > step${i + 1}`));+ const spec = compileExplainerDiagram('workflow', rows, { id: 'wrapped' });+ assert.ok(spec.lanes.length > 1, 'the chain wraps into several rows');+ assert.ok(spec.nodes.every(node => node.col <= 5));+ assert.deepEqual(spec.nodes.map(node => node.id), ['step1', 'step2', 'step3', 'step4', 'step5', 'step6', 'step7'], 'reading order is kept');+ const short = compileExplainerDiagram('workflow', ['ask | Needs scaling? | backend', 'keep | Keep it | backend', 'ask > keep | no'], { id: 'short' });+ assert.equal(short.lanes.length, 1);+ assert.equal(short.nodes[0].icon, 'decision');+ assert.equal(short.nodes[1].icon, undefined);+});