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
feat: add trace animation mode
tt-a1i808f84e931e6
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 37a6ea7e..8d0d00fb 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,6 +4,10 @@ All notable changes are documented here. Format loosely follows [Keep a Changelo## [Unreleased]+### Added+- **Opt-in trace animation.** Renderer-backed diagrams can set `meta.animation: "trace"` to animate marked arrows and nodes inside the generated HTML/SVG. The default output remains static, and the CSS respects `prefers-reduced-motion`.+- **Workflow route guard.** Workflow rendering now rejects edges that cross through non-endpoint nodes, so crowded or long return routes fail with an actionable routing hint instead of producing confusing line artifacts.+## [2.7.0] — 2026-07-03### Addeddiff --git a/README.md b/README.mdindex aa45f038..a3e5f953 100644--- a/README.md+++ b/README.md@@ -173,6 +173,14 @@ node scripts/check-render-output.mjs output.htmlThat final gate inspects the generated HTML/SVG for malformed output, non-finite SVG values, accidental two-point diagonal arrows, and arrows crossing the legend.+Renderer-backed diagrams can also opt into lightweight motion for demos:++```json+{ "meta": { "title": "Release Flow", "animation": "trace" } }+```++Trace animation runs inside the generated HTML/SVG: arrows flow in order, nodes pulse lightly, and `prefers-reduced-motion` disables movement for users who request it. Omit `animation` for the default static diagram.+**Claude.ai Projects (alternative):**Upload [`archify.zip`](archify.zip) to your Project Knowledge.diff --git a/README_EN.md b/README_EN.mdindex aa45f038..a3e5f953 100644--- a/README_EN.md+++ b/README_EN.md@@ -173,6 +173,14 @@ node scripts/check-render-output.mjs output.htmlThat final gate inspects the generated HTML/SVG for malformed output, non-finite SVG values, accidental two-point diagonal arrows, and arrows crossing the legend.+Renderer-backed diagrams can also opt into lightweight motion for demos:++```json+{ "meta": { "title": "Release Flow", "animation": "trace" } }+```++Trace animation runs inside the generated HTML/SVG: arrows flow in order, nodes pulse lightly, and `prefers-reduced-motion` disables movement for users who request it. Omit `animation` for the default static diagram.+**Claude.ai Projects (alternative):**Upload [`archify.zip`](archify.zip) to your Project Knowledge.diff --git a/README_ZH.md b/README_ZH.mdindex a52b0ecf..f48cc6d9 100644--- a/README_ZH.md+++ b/README_ZH.md@@ -177,6 +177,14 @@ node scripts/check-render-output.mjs output.html这道最终闸门会检查 HTML/SVG 是否结构异常、SVG 是否出现非有限值、是否误生成两点斜线箭头,以及箭头是否穿过图例。+渲染器生成的图也可以按需开启轻量动效,适合 demo 或演示场景:++```json+{ "meta": { "title": "Release Flow", "animation": "trace" } }+```++Trace animation 直接运行在生成的 HTML/SVG 里:箭头按顺序流动,节点轻微 pulse;用户开启 `prefers-reduced-motion` 时会自动禁用运动。默认不写 `animation`,输出仍是静态图。+**Claude.ai Projects:**把 [`archify.zip`](archify.zip) 上传到 Project Knowledge 就行。diff --git a/archify.zip b/archify.zipindex b1dbc891..90cd9ee7 100644Binary files a/archify.zip and b/archify.zip differdiff --git a/archify/SKILL.md b/archify/SKILL.mdindex 93401523..c524dc87 100644--- a/archify/SKILL.md+++ b/archify/SKILL.md@@ -60,7 +60,9 @@ All four modes follow the same loop:4. Check the generated artifact: `node scripts/check-render-output.mjs <output>.html`. This catches malformed SVG output, non-finite SVG values, two-point diagonal arrows, and arrows crossing the legend.5. If either step fails, the error names the JSON path or the fix (thresholds, valid ranges, which knob to change). Fix the JSON and re-run; never edit the renderer.-Schema violations exit non-zero with path-prefixed messages like `/nodes/3 (id/label: "router") must NOT have additional properties`. The renderers additionally fail fast on layout problems: node/state overlap (including cross-lane), labels colliding with nodes or other labels, labels wider than their node, out-of-range columns/rows, too-short edges, and legends outside the viewBox. CJK text is measured at double width automatically.+Schema violations exit non-zero with path-prefixed messages like `/nodes/3 (id/label: "router") must NOT have additional properties`. The renderers additionally fail fast on layout problems: node/state overlap (including cross-lane), labels colliding with nodes or other labels, labels wider than their node, out-of-range columns/rows, too-short edges, workflow edges crossing unrelated nodes, and legends outside the viewBox. CJK text is measured at double width automatically.++Set `meta.animation: "trace"` only when the user asks for motion or a presentation/demo view. It adds lightweight SVG/CSS trace animation to renderer-marked arrows and nodes, respects `prefers-reduced-motion`, and leaves the default static output unchanged.### Workflowdiff --git a/archify/assets/template.html b/archify/assets/template.htmlindex 5d6ce9a6..ab480429 100644--- a/archify/assets/template.html+++ b/archify/assets/template.html@@ -455,6 +455,37 @@.c-security-group { fill: transparent; stroke: var(--security-stroke); stroke-dasharray: 4,4; }.c-region { fill: rgba(251, 191, 36, 0.05); stroke: var(--cloud-stroke); stroke-dasharray: 8,4; }.c-lane { fill: var(--lane-fill); stroke: var(--lane-stroke); stroke-dasharray: 6,6; }++ /* Optional trace animation, enabled only by meta.animation = "trace".+ Static diagrams do not carry data-animation and render exactly as before. */+ svg[data-animation="trace"] [data-animate="edge"] {+ stroke-dasharray: 10 8;+ stroke-dashoffset: 54;+ animation: archify-edge-flow 2.4s linear infinite;+ animation-delay: calc(var(--step, 0) * 160ms);+ }+ svg[data-animation="trace"] [data-animate="node"] {+ transform-box: fill-box;+ transform-origin: center;+ animation: archify-node-pulse 3.6s ease-in-out infinite;+ animation-delay: calc(var(--step, 0) * 160ms);+ }+ @keyframes archify-edge-flow {+ to { stroke-dashoffset: 0; }+ }+ @keyframes archify-node-pulse {+ 0%, 72%, 100% { filter: none; stroke-width: 1.5; }+ 18%, 36% {+ filter: drop-shadow(0 0 8px var(--arrow-emphasis));+ stroke-width: 2.4;+ }+ }+ @media (prefers-reduced-motion: reduce) {+ svg[data-animation="trace"] [data-animate] {+ animation: none !important;+ stroke-dashoffset: 0;+ }+ }</style></head><body>diff --git a/archify/examples/agent-tool-call.workflow.json b/archify/examples/agent-tool-call.workflow.jsonindex cfe5b1c9..eb13d731 100644--- a/archify/examples/agent-tool-call.workflow.json+++ b/archify/examples/agent-tool-call.workflow.json@@ -45,7 +45,7 @@{ "from": "chat", "to": "planner", "label": "plan", "variant": "emphasis", "fromSide": "bottom", "toSide": "top", "route": "drop", "labelSegment": 1 },{ "from": "planner", "to": "router", "variant": "default" },{ "from": "router", "to": "approval", "label": "needs approval?", "variant": "security", "fromSide": "bottom", "toSide": "top", "route": "drop", "labelSegment": 0, "labelDx": 34, "labelDy": 18 },- { "from": "approval", "to": "tool", "variant": "emphasis", "fromSide": "bottom", "toSide": "top", "route": "drop" },+ { "from": "approval", "to": "tool", "variant": "emphasis", "fromSide": "left", "toSide": "left", "route": "return-left" },{ "from": "approval", "to": "blocked", "label": "denied", "variant": "security", "role": "error", "fromSide": "bottom", "toSide": "top", "route": "drop", "labelSegment": 1, "labelDy": 12 },{ "from": "blocked", "to": "retry", "variant": "dashed", "role": "branch" },{ "from": "tool", "to": "external", "variant": "default" },diff --git a/archify/renderers/architecture/render-architecture.mjs b/archify/renderers/architecture/render-architecture.mjsindex 7e2745e9..b25765d4 100644--- a/archify/renderers/architecture/render-architecture.mjs+++ b/archify/renderers/architecture/render-architecture.mjs@@ -1,7 +1,7 @@import path from 'node:path';import { fileURLToPath } from 'node:url';import { esc, renderDefinitions, textUnits } from '../shared/utils.mjs';-import { loadDiagram, writeDiagram, svgRootAttrs } from '../shared/cli.mjs';+import { animateAttr, loadDiagram, writeDiagram, svgRootAttrs } from '../shared/cli.mjs';import {asArray,isFinitePoint,@@ -45,6 +45,14 @@ function measureComponent(c) {}const components = new Map(asArray(arch.components).map((c) => [c.id, measureComponent(c)]));+const componentSteps = new Map();+for (const [index, conn] of asArray(arch.connections).entries()) {+ if (!componentSteps.has(conn.from)) componentSteps.set(conn.from, index);+ if (!componentSteps.has(conn.to)) componentSteps.set(conn.to, index + 1);+}+for (const [index, c] of asArray(arch.components).entries()) {+ if (!componentSteps.has(c.id)) componentSteps.set(c.id, index);+}// ---- Boundaries computed from the `wraps` id list ---------------------------function boundaryRect(boundary) {@@ -218,11 +226,11 @@ function renderBoundary(b) {<text x="${b.x + 8}" y="${b.y + 18}" class="${labelCls}" font-size="9" font-weight="600">${esc(b.label)}</text>`;}-function renderConnectionPath(conn) {+function renderConnectionPath(conn, index) {const [cls, marker] = arrowClassMap[conn.variant || 'default'] || arrowClassMap.default;const routed = pathFor(conn);const strokeWidth = conn.width || (conn.variant === 'emphasis' ? 1.8 : 1.5);- return ` <path d="${routed.d}" class="${cls}" stroke-width="${strokeWidth}" marker-end="url(#${marker})"/>`;+ return ` <path d="${routed.d}" class="${cls}"${animateAttr(arch.meta, 'edge', index)} stroke-width="${strokeWidth}" marker-end="url(#${marker})"/>`;}function renderConnectionLabel(conn) {@@ -246,7 +254,7 @@ function renderComponent(c) {? `\n <text x="${cx}" y="${c.y + c.height - 8}" class="${accent}" font-size="7" text-anchor="middle">${esc(c.tag)}</text>`: '';return ` <rect x="${c.x}" y="${c.y}" width="${c.width}" height="${c.height}" rx="6" class="c-mask"/>- <rect x="${c.x}" y="${c.y}" width="${c.width}" height="${c.height}" rx="6" class="${fill}" stroke-width="1.5"/>+ <rect x="${c.x}" y="${c.y}" width="${c.width}" height="${c.height}" rx="6" class="${fill}"${animateAttr(arch.meta, 'node', componentSteps.get(c.id))} stroke-width="1.5"/><text x="${cx}" y="${labelY}" class="t-primary" font-size="11" font-weight="600" text-anchor="middle">${esc(c.label)}</text>${sub}${tag}`;}diff --git a/archify/renderers/dataflow/render-dataflow.mjs b/archify/renderers/dataflow/render-dataflow.mjsindex f5307005..f0921361 100644--- a/archify/renderers/dataflow/render-dataflow.mjs+++ b/archify/renderers/dataflow/render-dataflow.mjs@@ -1,7 +1,7 @@import path from 'node:path';import { fileURLToPath } from 'node:url';import { esc, renderDefinitions, textUnits } from '../shared/utils.mjs';-import { loadDiagram, writeDiagram, svgRootAttrs } from '../shared/cli.mjs';+import { animateAttr, loadDiagram, writeDiagram, svgRootAttrs } from '../shared/cli.mjs';import {asArray,isFinitePoint,@@ -60,6 +60,14 @@ function measureNode(node) {}const nodes = new Map(asArray(dataflow.nodes).map((node) => [node.id, measureNode(node)]));+const nodeSteps = new Map();+for (const [index, flow] of asArray(dataflow.flows).entries()) {+ if (!nodeSteps.has(flow.from)) nodeSteps.set(flow.from, index);+ if (!nodeSteps.has(flow.to)) nodeSteps.set(flow.to, index + 1);+}+for (const [index, node] of asArray(dataflow.nodes).entries()) {+ if (!nodeSteps.has(node.id)) nodeSteps.set(node.id, index);+}function validateDataflow() {const problems = [];@@ -212,16 +220,16 @@ function renderNode(node) {? `\n <text x="${node.cx}" y="${node.y + node.height - 11}" class="${accent}" font-size="7" text-anchor="middle">${esc(node.tag)}</text>`: '';return ` <rect x="${node.x}" y="${node.y}" width="${node.width}" height="${node.height}" rx="6" class="c-mask"/>- <rect x="${node.x}" y="${node.y}" width="${node.width}" height="${node.height}" rx="6" class="${fill}" stroke-width="1.5"/>+ <rect x="${node.x}" y="${node.y}" width="${node.width}" height="${node.height}" rx="6" class="${fill}"${animateAttr(dataflow.meta, 'node', nodeSteps.get(node.id))} stroke-width="1.5"/><text x="${node.cx}" y="${node.y + 21}" class="t-primary" font-size="10" font-weight="600" text-anchor="middle">${esc(node.label)}</text><text x="${node.cx}" y="${node.y + 37}" class="t-muted" font-size="7" text-anchor="middle">${esc(node.sublabel || '')}</text>${tag}`;}-function renderFlowPath(flow) {+function renderFlowPath(flow, index) {const [cls, marker] = arrowClassMap[flow.variant || 'default'] || arrowClassMap.default;const routed = pathFor(flow);const strokeWidth = flow.width || (flow.variant === 'emphasis' ? 1.8 : 1.4);- return ` <path d="${routed.d}" class="${cls}" stroke-width="${strokeWidth}" marker-end="url(#${marker})"/>`;+ return ` <path d="${routed.d}" class="${cls}"${animateAttr(dataflow.meta, 'edge', index)} stroke-width="${strokeWidth}" marker-end="url(#${marker})"/>`;}function renderFlowLabel(flow) {diff --git a/archify/renderers/lifecycle/render-lifecycle.mjs b/archify/renderers/lifecycle/render-lifecycle.mjsindex 4016710d..43e14ded 100644--- a/archify/renderers/lifecycle/render-lifecycle.mjs+++ b/archify/renderers/lifecycle/render-lifecycle.mjs@@ -1,7 +1,7 @@import path from 'node:path';import { fileURLToPath } from 'node:url';import { esc, renderDefinitions, textUnits } from '../shared/utils.mjs';-import { loadDiagram, writeDiagram, svgRootAttrs } from '../shared/cli.mjs';+import { animateAttr, loadDiagram, writeDiagram, svgRootAttrs } from '../shared/cli.mjs';import {asArray,isFinitePoint,@@ -98,6 +98,14 @@ function measureState(state) {}const states = new Map(asArray(lifecycle.states).map((state) => [state.id, measureState(state)]));+const stateSteps = new Map();+for (const [index, transition] of asArray(lifecycle.transitions).entries()) {+ if (!stateSteps.has(transition.from)) stateSteps.set(transition.from, index);+ if (!stateSteps.has(transition.to)) stateSteps.set(transition.to, index + 1);+}+for (const [index, state] of asArray(lifecycle.states).entries()) {+ if (!stateSteps.has(state.id)) stateSteps.set(state.id, index);+}function validateLifecycle() {const problems = [];@@ -288,16 +296,16 @@ function renderState(state) {? `\n <text x="${state.x + 10}" y="${state.y + 14}" class="${accent}" font-size="7" font-weight="700">${esc(state.step)}</text>`: '';return ` <rect x="${state.x}" y="${state.y}" width="${state.width}" height="${state.height}" rx="7" class="c-mask"/>- <rect x="${state.x}" y="${state.y}" width="${state.width}" height="${state.height}" rx="7" class="${fill}" stroke-width="1.5"/>${step}+ <rect x="${state.x}" y="${state.y}" width="${state.width}" height="${state.height}" rx="7" class="${fill}"${animateAttr(lifecycle.meta, 'node', stateSteps.get(state.id))} stroke-width="1.5"/>${step}<text x="${state.cx}" y="${state.y + 21}" class="t-primary" font-size="10" font-weight="600" text-anchor="middle">${esc(state.label)}</text><text x="${state.cx}" y="${state.y + 37}" class="t-muted" font-size="7" text-anchor="middle">${esc(state.sublabel || '')}</text>${tag}`;}-function renderTransitionPath(transition) {+function renderTransitionPath(transition, index) {const [cls, marker] = arrowClassMap[transition.variant || 'default'] || arrowClassMap.default;const routed = pathFor(transition);const strokeWidth = transition.width || (transition.variant === 'emphasis' ? 2 : 1.1);- return ` <path d="${routed.d}" class="${cls}" stroke-width="${strokeWidth}" marker-end="url(#${marker})"/>`;+ return ` <path d="${routed.d}" class="${cls}"${animateAttr(lifecycle.meta, 'edge', index)} stroke-width="${strokeWidth}" marker-end="url(#${marker})"/>`;}function renderTransitionLabel(transition) {diff --git a/archify/renderers/sequence/render-sequence.mjs b/archify/renderers/sequence/render-sequence.mjsindex 28e38e2b..3f0c22bf 100644--- a/archify/renderers/sequence/render-sequence.mjs+++ b/archify/renderers/sequence/render-sequence.mjs@@ -1,7 +1,7 @@import path from 'node:path';import { fileURLToPath } from 'node:url';import { esc, renderDefinitions, textUnits } from '../shared/utils.mjs';-import { loadDiagram, writeDiagram, svgRootAttrs } from '../shared/cli.mjs';+import { animateAttr, loadDiagram, writeDiagram, svgRootAttrs } from '../shared/cli.mjs';import { componentFill, arrowClassMap, rectsOverlap, asArray, isFinitePoint } from '../shared/geometry.mjs';const __dirname = path.dirname(fileURLToPath(import.meta.url));@@ -151,7 +151,7 @@ function validateSequence() {function renderParticipant(participant) {const fill = componentFill[participant.type] || 'c-external';return ` <rect x="${participant.x}" y="${layout.topY}" width="${layout.participantW}" height="${layout.participantH}" rx="6" class="c-mask"/>- <rect x="${participant.x}" y="${layout.topY}" width="${layout.participantW}" height="${layout.participantH}" rx="6" class="${fill}" stroke-width="1.5"/>+ <rect x="${participant.x}" y="${layout.topY}" width="${layout.participantW}" height="${layout.participantH}" rx="6" class="${fill}"${animateAttr(sequence.meta, 'node', participant.index)} stroke-width="1.5"/><text x="${participant.cx}" y="${layout.topY + 22}" class="t-primary" font-size="11" font-weight="600" text-anchor="middle">${esc(participant.label)}</text><text x="${participant.cx}" y="${layout.topY + 39}" class="t-muted" font-size="7" text-anchor="middle">${esc(participant.sublabel)}</text>`;}@@ -189,7 +189,7 @@ function messageLabel(message, x1, x2) {<text x="${center}" y="${y}" class="${accent}" font-size="9" text-anchor="middle">${esc(message.label)}</text>`;}-function renderMessage(message) {+function renderMessage(message, index) {const from = participants.get(message.from);const to = participants.get(message.to);const direction = to.cx > from.cx ? 1 : -1;@@ -201,7 +201,7 @@ function renderMessage(message) {const note = message.note? `\n <text x="${Math.min(start, end) + 12}" y="${message.y + 18}" class="t-dim" font-size="7">${esc(message.note)}</text>`: '';- return ` <path d="M ${start} ${message.y} L ${end} ${message.y}" class="${cls}" stroke-width="${strokeWidth}"${dash} marker-end="url(#${marker})"/>+ return ` <path d="M ${start} ${message.y} L ${end} ${message.y}" class="${cls}"${animateAttr(sequence.meta, 'edge', index)} stroke-width="${strokeWidth}"${dash} marker-end="url(#${marker})"/>${messageLabel(message, start, end)}${note}`;}diff --git a/archify/renderers/shared/cli.mjs b/archify/renderers/shared/cli.mjsindex 41e89b9a..a4fd8fc6 100644--- a/archify/renderers/shared/cli.mjs+++ b/archify/renderers/shared/cli.mjs@@ -33,5 +33,12 @@ export function writeDiagram({ outPath, template, meta, footerLabel, svg, cards// Accessible name for the generated diagram SVG.export function svgRootAttrs(meta, kind) {const name = meta.subtitle ? `${meta.title} — ${meta.subtitle}` : meta.title;- return `role="img" aria-label="${esc(`${name} (${kind})`)}"`;+ const animation = meta.animation === 'trace' ? ' data-animation="trace"' : '';+ return `role="img" aria-label="${esc(`${name} (${kind})`)}"${animation}`;+}++export function animateAttr(meta, kind, step) {+ if (meta.animation !== 'trace') return '';+ const safeStep = Number.isFinite(step) && step >= 0 ? Math.floor(step) : 0;+ return ` data-animate="${kind}" style="--step:${safeStep}"`;}diff --git a/archify/renderers/shared/geometry.mjs b/archify/renderers/shared/geometry.mjsindex 7a89b6b0..3fee0e49 100644--- a/archify/renderers/shared/geometry.mjs+++ b/archify/renderers/shared/geometry.mjs@@ -24,6 +24,56 @@ export function rectsOverlap(a, b, gap = 0) {);}+export function segmentIntersectsRect(segment, rect, gap = 0) {+ const box = {+ x1: rect.x - gap,+ y1: rect.y - gap,+ x2: rect.x + rect.width + gap,+ y2: rect.y + rect.height + gap+ };+ const [a, b] = [segment.start, segment.end];+ if (pointInBox(a, box) || pointInBox(b, box)) return true;+ return (+ segmentsIntersect(a, b, [box.x1, box.y1], [box.x2, box.y1]) ||+ segmentsIntersect(a, b, [box.x2, box.y1], [box.x2, box.y2]) ||+ segmentsIntersect(a, b, [box.x2, box.y2], [box.x1, box.y2]) ||+ segmentsIntersect(a, b, [box.x1, box.y2], [box.x1, box.y1])+ );+}++function pointInBox(point, box) {+ return point[0] >= box.x1 && point[0] <= box.x2 && point[1] >= box.y1 && point[1] <= box.y2;+}++function segmentsIntersect(a, b, c, d) {+ const o1 = orientation(a, b, c);+ const o2 = orientation(a, b, d);+ const o3 = orientation(c, d, a);+ const o4 = orientation(c, d, b);++ if (o1 === 0 && onSegment(a, c, b)) return true;+ if (o2 === 0 && onSegment(a, d, b)) return true;+ if (o3 === 0 && onSegment(c, a, d)) return true;+ if (o4 === 0 && onSegment(c, b, d)) return true;++ return o1 !== o2 && o3 !== o4;+}++function orientation(a, b, c) {+ const value = (b[1] - a[1]) * (c[0] - b[0]) - (b[0] - a[0]) * (c[1] - b[1]);+ if (Math.abs(value) < 0.0001) return 0;+ return value > 0 ? 1 : 2;+}++function onSegment(a, b, c) {+ return (+ b[0] <= Math.max(a[0], c[0]) &&+ b[0] >= Math.min(a[0], c[0]) &&+ b[1] <= Math.max(a[1], c[1]) &&+ b[1] >= Math.min(a[1], c[1])+ );+}+export function anchor(rect, side) {switch (side) {case 'left': return [rect.x, rect.cy];diff --git a/archify/renderers/workflow/render-workflow.mjs b/archify/renderers/workflow/render-workflow.mjsindex f4094a8b..3c3398af 100644--- a/archify/renderers/workflow/render-workflow.mjs+++ b/archify/renderers/workflow/render-workflow.mjs@@ -1,11 +1,12 @@import path from 'node:path';import { fileURLToPath } from 'node:url';import { esc, renderDefinitions, textUnits } from '../shared/utils.mjs';-import { loadDiagram, writeDiagram, svgRootAttrs } from '../shared/cli.mjs';+import { animateAttr, loadDiagram, writeDiagram, svgRootAttrs } from '../shared/cli.mjs';import {asArray,isFinitePoint,rectsOverlap,+ segmentIntersectsRect,anchor,defaultFromSide,defaultToSide,@@ -77,6 +78,18 @@ function measureNode(node) {const nodes = new Map(asArray(workflow.nodes).map((node) => [node.id, measureNode(node)]));+const mainPathSteps = new Map(asArray(workflow.mainPath).map((id, index) => [id, index]));+const edgeSteps = new Map(asArray(workflow.edges).map((edge, index) => {+ const fromStep = mainPathSteps.get(edge.from);+ const toStep = mainPathSteps.get(edge.to);+ const mainStep = Number.isInteger(fromStep) && toStep === fromStep + 1 ? fromStep : null;+ return [edge, mainStep ?? asArray(workflow.mainPath).length + index];+}));++function nodeStep(node) {+ return mainPathSteps.get(node.id) ?? asArray(workflow.mainPath).length + asArray(workflow.nodes).findIndex((item) => item.id === node.id);+}+function validateWorkflow() {const problems = [];if (workflow.schema_version !== 1) {@@ -217,6 +230,16 @@ function validateWorkflow() {problems.push(`Edge "${edge.from}" -> "${edge.to}" is too short (${Math.round(segmentLength)}px; minimum 28px) — drop its label or route it through a channel.`);}}+ const segments = [];+ for (let i = 1; i < routed.points.length; i += 1) {+ segments.push({ start: routed.points[i - 1], end: routed.points[i] });+ }+ for (const node of nodes.values()) {+ if (node.id === edge.from || node.id === edge.to) continue;+ if (segments.some((segment) => segmentIntersectsRect(segment, node, 2))) {+ problems.push(`Edge "${edge.from}" -> "${edge.to}" crosses node "${node.id}" — adjust fromSide/toSide, route it through a channel, or move one node to a clearer lane/column.`);+ }+ }}}@@ -379,7 +402,7 @@ function renderNode(node) {? `\n <text x="${node.cx}" y="${node.y + node.height - 12}" class="${accent}" font-size="7" text-anchor="middle">${esc(node.tag)}</text>`: '';return ` <rect x="${node.x}" y="${node.y}" width="${node.width}" height="${node.height}" rx="6" class="c-mask"/>- <rect x="${node.x}" y="${node.y}" width="${node.width}" height="${node.height}" rx="6" class="${fill}" stroke-width="1.5"/>+ <rect x="${node.x}" y="${node.y}" width="${node.width}" height="${node.height}" rx="6" class="${fill}"${animateAttr(workflow.meta, 'node', nodeStep(node))} stroke-width="1.5"/><text x="${node.cx}" y="${node.y + 21}" class="t-primary" font-size="11" font-weight="600" text-anchor="middle">${esc(node.label)}</text><text x="${node.cx}" y="${node.y + 38}" class="t-muted" font-size="8" text-anchor="middle">${esc(node.sublabel || '')}</text>${tag}`;}@@ -388,7 +411,7 @@ function renderEdgePath(edge) {const [cls, marker] = arrowClassMap[edge.variant || 'default'] || arrowClassMap.default;const routed = pathFor(edge);const strokeWidth = edge.width || (edge.variant === 'emphasis' ? 1.8 : 1.4);- return ` <path d="${routed.d}" class="${cls}" stroke-width="${strokeWidth}" marker-end="url(#${marker})"/>`;+ return ` <path d="${routed.d}" class="${cls}"${animateAttr(workflow.meta, 'edge', edgeSteps.get(edge))} stroke-width="${strokeWidth}" marker-end="url(#${marker})"/>`;}function renderEdgeLabel(edge) {diff --git a/archify/schemas/README.md b/archify/schemas/README.mdindex 88f8ddf8..8f6a3634 100644--- a/archify/schemas/README.md+++ b/archify/schemas/README.md@@ -19,6 +19,9 @@ Every diagram schema requires `schema_version`, `diagram_type`, `meta` (with`cards`, which are optional — and sets `additionalProperties: false` at everylevel, so unknown fields are rejected rather than silently ignored.+Every `meta` object also accepts `animation: "trace"` for opt-in SVG/CSS motion+in generated HTML. Omit it, or set `"none"`, for the default static output.+## schema_version policy`schema_version` is `"const": 1`. The constant pins the IR contract: a filediff --git a/archify/schemas/architecture.schema.json b/archify/schemas/architecture.schema.jsonindex 1bc1184d..73abb915 100644--- a/archify/schemas/architecture.schema.json+++ b/archify/schemas/architecture.schema.json@@ -16,6 +16,7 @@"title": { "type": "string", "minLength": 1 },"subtitle": { "type": "string" },"output": { "type": "string" },+ "animation": { "enum": ["trace", "none"] },"viewBox": {"type": "array","prefixItems": [diff --git a/archify/schemas/dataflow.schema.json b/archify/schemas/dataflow.schema.jsonindex 930ccb82..7317d25f 100644--- a/archify/schemas/dataflow.schema.json+++ b/archify/schemas/dataflow.schema.json@@ -36,6 +36,12 @@"output": {"type": "string"},+ "animation": {+ "enum": [+ "trace",+ "none"+ ]+ },"viewBox": {"type": "array","prefixItems": [diff --git a/archify/schemas/lifecycle.schema.json b/archify/schemas/lifecycle.schema.jsonindex cea6fc98..8b212196 100644--- a/archify/schemas/lifecycle.schema.json+++ b/archify/schemas/lifecycle.schema.json@@ -36,6 +36,12 @@"output": {"type": "string"},+ "animation": {+ "enum": [+ "trace",+ "none"+ ]+ },"viewBox": {"type": "array","prefixItems": [diff --git a/archify/schemas/sequence.schema.json b/archify/schemas/sequence.schema.jsonindex 96a19ef2..b3325631 100644--- a/archify/schemas/sequence.schema.json+++ b/archify/schemas/sequence.schema.json@@ -35,6 +35,12 @@"output": {"type": "string"},+ "animation": {+ "enum": [+ "trace",+ "none"+ ]+ },"viewBox": {"type": "array","prefixItems": [diff --git a/archify/schemas/workflow.schema.json b/archify/schemas/workflow.schema.jsonindex 1ea46ceb..fb14c51b 100644--- a/archify/schemas/workflow.schema.json+++ b/archify/schemas/workflow.schema.json@@ -36,6 +36,12 @@"output": {"type": "string"},+ "animation": {+ "enum": [+ "trace",+ "none"+ ]+ },"viewBox": {"type": "array","prefixItems": [diff --git a/archify/test/animation.test.mjs b/archify/test/animation.test.mjsnew file mode 100644index 00000000..835507ce--- /dev/null+++ b/archify/test/animation.test.mjs@@ -0,0 +1,53 @@+import { test } from 'node:test';+import assert from 'node:assert/strict';+import { execFileSync } from 'node:child_process';+import fs from 'node:fs';+import os from 'node:os';+import path from 'node:path';+import { fileURLToPath } from 'node:url';++const __dirname = path.dirname(fileURLToPath(import.meta.url));+const skillRoot = path.resolve(__dirname, '..');+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-animation-'));++const CASES = {+ architecture: 'web-app.architecture.json',+ workflow: 'agent-tool-call.workflow.json',+ sequence: 'cache-miss-request.sequence.json',+ dataflow: 'product-analytics.dataflow.json',+ lifecycle: 'agent-run.lifecycle.json',+};++function render(mode, example, animation = 'trace') {+ const doc = JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples', example), 'utf8'));+ if (animation) doc.meta = { ...doc.meta, animation };+ const suffix = animation || 'static';+ const input = path.join(tmp, `${mode}-${suffix}.json`);+ const output = path.join(tmp, `${mode}-${suffix}.html`);+ fs.writeFileSync(input, JSON.stringify(doc));+ execFileSync('node', [path.join(skillRoot, `renderers/${mode}/render-${mode}.mjs`), input, output], {+ stdio: ['ignore', 'ignore', 'pipe'],+ });+ return fs.readFileSync(output, 'utf8');+}++function svgBlock(html) {+ return html.match(/<svg\b[\s\S]*?<\/svg>/)?.[0] || '';+}++test('static output omits animation attributes', () => {+ const svg = svgBlock(render('workflow', CASES.workflow, null));+ assert.doesNotMatch(svg, /data-animation=/);+ assert.doesNotMatch(svg, /data-animate=/);+});++for (const [mode, example] of Object.entries(CASES)) {+ test(`${mode}: trace animation annotates svg, edges, and nodes`, () => {+ const svg = svgBlock(render(mode, example));+ assert.match(svg, /<svg[^>]+data-animation="trace"/);+ assert.match(svg, /data-animate="edge" style="--step:0"/);+ assert.match(svg, /data-animate="node" style="--step:0"/);+ });+}++process.on('exit', () => fs.rmSync(tmp, { recursive: true, force: true }));diff --git a/archify/test/geometry.test.mjs b/archify/test/geometry.test.mjsindex 34622011..69ebffb5 100644--- a/archify/test/geometry.test.mjs+++ b/archify/test/geometry.test.mjs@@ -9,6 +9,7 @@ import { test } from 'node:test';import assert from 'node:assert/strict';import {rectsOverlap,+ segmentIntersectsRect,asArray,isFinitePoint,anchor,@@ -49,6 +50,11 @@ test('rectsOverlap: negative gap shrinks the hit box (label-collision conventionassert.equal(rectsOverlap(rect(0, 0, 10, 10), rect(7, 0, 10, 10), -2), true);});+test('segmentIntersectsRect: detects an edge crossing a node box', () => {+ assert.equal(segmentIntersectsRect({ start: [0, 5], end: [20, 5] }, rect(8, 0, 4, 10)), true);+ assert.equal(segmentIntersectsRect({ start: [0, 20], end: [20, 20] }, rect(8, 0, 4, 10)), false);+});+test('asArray coerces non-arrays to [] (degraded-mode guard)', () => {assert.deepEqual(asArray([1, 2]), [1, 2]);assert.deepEqual(asArray('oops'), []);diff --git a/archify/test/layout-rules.test.mjs b/archify/test/layout-rules.test.mjsindex 3da22e63..812629e4 100644--- a/archify/test/layout-rules.test.mjs+++ b/archify/test/layout-rules.test.mjs@@ -169,4 +169,23 @@ test('workflow: same-lane offset auto edge stays orthogonal', () => {assert.match(html, /M 236 105 L 260 105 L 260 133 L 284 133/);});+test('workflow: edge crossing a non-endpoint node is rejected', () => {+ const d = {+ schema_version: 1,+ diagram_type: 'workflow',+ meta: { title: 'Crossing edge route' },+ lanes: [{ id: 'main', label: 'Main lane' }],+ nodes: [+ { id: 'left', lane: 'main', col: 0, type: 'backend', label: 'Left', width: 60 },+ { id: 'middle', lane: 'main', col: 2, type: 'database', label: 'Middle', width: 70 },+ { id: 'right', lane: 'main', col: 4, type: 'backend', label: 'Right', width: 60 },+ ],+ edges: [{ from: 'left', to: 'right', route: 'straight' }],+ };+ const { code, stderr } = render('workflow', d);+ assert.notEqual(code, 0, `expected non-zero exit; stderr:\n${stderr}`);+ assert.match(stderr, /crosses node "middle"/);+ assert.match(stderr, /fromSide\/toSide|channel|lane\/column/);+});+process.on('exit', () => fs.rmSync(tmp, { recursive: true, force: true }));diff --git a/examples/dataflow-product-analytics.html b/examples/dataflow-product-analytics.htmlindex 2dd24601..6b9344a9 100644--- a/examples/dataflow-product-analytics.html+++ b/examples/dataflow-product-analytics.html@@ -455,6 +455,37 @@.c-security-group { fill: transparent; stroke: var(--security-stroke); stroke-dasharray: 4,4; }.c-region { fill: rgba(251, 191, 36, 0.05); stroke: var(--cloud-stroke); stroke-dasharray: 8,4; }.c-lane { fill: var(--lane-fill); stroke: var(--lane-stroke); stroke-dasharray: 6,6; }++ /* Optional trace animation, enabled only by meta.animation = "trace".+ Static diagrams do not carry data-animation and render exactly as before. */+ svg[data-animation="trace"] [data-animate="edge"] {+ stroke-dasharray: 10 8;+ stroke-dashoffset: 54;+ animation: archify-edge-flow 2.4s linear infinite;+ animation-delay: calc(var(--step, 0) * 160ms);+ }+ svg[data-animation="trace"] [data-animate="node"] {+ transform-box: fill-box;+ transform-origin: center;+ animation: archify-node-pulse 3.6s ease-in-out infinite;+ animation-delay: calc(var(--step, 0) * 160ms);+ }+ @keyframes archify-edge-flow {+ to { stroke-dashoffset: 0; }+ }+ @keyframes archify-node-pulse {+ 0%, 72%, 100% { filter: none; stroke-width: 1.5; }+ 18%, 36% {+ filter: drop-shadow(0 0 8px var(--arrow-emphasis));+ stroke-width: 2.4;+ }+ }+ @media (prefers-reduced-motion: reduce) {+ svg[data-animation="trace"] [data-animate] {+ animation: none !important;+ stroke-dashoffset: 0;+ }+ }</style></head><body>diff --git a/examples/lifecycle-agent-run.html b/examples/lifecycle-agent-run.htmlindex ace0d2f9..293c85d4 100644--- a/examples/lifecycle-agent-run.html+++ b/examples/lifecycle-agent-run.html@@ -455,6 +455,37 @@.c-security-group { fill: transparent; stroke: var(--security-stroke); stroke-dasharray: 4,4; }.c-region { fill: rgba(251, 191, 36, 0.05); stroke: var(--cloud-stroke); stroke-dasharray: 8,4; }.c-lane { fill: var(--lane-fill); stroke: var(--lane-stroke); stroke-dasharray: 6,6; }++ /* Optional trace animation, enabled only by meta.animation = "trace".+ Static diagrams do not carry data-animation and render exactly as before. */+ svg[data-animation="trace"] [data-animate="edge"] {+ stroke-dasharray: 10 8;+ stroke-dashoffset: 54;+ animation: archify-edge-flow 2.4s linear infinite;+ animation-delay: calc(var(--step, 0) * 160ms);+ }+ svg[data-animation="trace"] [data-animate="node"] {+ transform-box: fill-box;+ transform-origin: center;+ animation: archify-node-pulse 3.6s ease-in-out infinite;+ animation-delay: calc(var(--step, 0) * 160ms);+ }+ @keyframes archify-edge-flow {+ to { stroke-dashoffset: 0; }+ }+ @keyframes archify-node-pulse {+ 0%, 72%, 100% { filter: none; stroke-width: 1.5; }+ 18%, 36% {+ filter: drop-shadow(0 0 8px var(--arrow-emphasis));+ stroke-width: 2.4;+ }+ }+ @media (prefers-reduced-motion: reduce) {+ svg[data-animation="trace"] [data-animate] {+ animation: none !important;+ stroke-dashoffset: 0;+ }+ }</style></head><body>diff --git a/examples/sequence-cache-miss-request.html b/examples/sequence-cache-miss-request.htmlindex cab5c4b8..e3aaee17 100644--- a/examples/sequence-cache-miss-request.html+++ b/examples/sequence-cache-miss-request.html@@ -455,6 +455,37 @@.c-security-group { fill: transparent; stroke: var(--security-stroke); stroke-dasharray: 4,4; }.c-region { fill: rgba(251, 191, 36, 0.05); stroke: var(--cloud-stroke); stroke-dasharray: 8,4; }.c-lane { fill: var(--lane-fill); stroke: var(--lane-stroke); stroke-dasharray: 6,6; }++ /* Optional trace animation, enabled only by meta.animation = "trace".+ Static diagrams do not carry data-animation and render exactly as before. */+ svg[data-animation="trace"] [data-animate="edge"] {+ stroke-dasharray: 10 8;+ stroke-dashoffset: 54;+ animation: archify-edge-flow 2.4s linear infinite;+ animation-delay: calc(var(--step, 0) * 160ms);+ }+ svg[data-animation="trace"] [data-animate="node"] {+ transform-box: fill-box;+ transform-origin: center;+ animation: archify-node-pulse 3.6s ease-in-out infinite;+ animation-delay: calc(var(--step, 0) * 160ms);+ }+ @keyframes archify-edge-flow {+ to { stroke-dashoffset: 0; }+ }+ @keyframes archify-node-pulse {+ 0%, 72%, 100% { filter: none; stroke-width: 1.5; }+ 18%, 36% {+ filter: drop-shadow(0 0 8px var(--arrow-emphasis));+ stroke-width: 2.4;+ }+ }+ @media (prefers-reduced-motion: reduce) {+ svg[data-animation="trace"] [data-animate] {+ animation: none !important;+ stroke-dashoffset: 0;+ }+ }</style></head><body>diff --git a/examples/web-app-rendered.html b/examples/web-app-rendered.htmlindex 923c1ca9..1f1b2cc0 100644--- a/examples/web-app-rendered.html+++ b/examples/web-app-rendered.html@@ -455,6 +455,37 @@.c-security-group { fill: transparent; stroke: var(--security-stroke); stroke-dasharray: 4,4; }.c-region { fill: rgba(251, 191, 36, 0.05); stroke: var(--cloud-stroke); stroke-dasharray: 8,4; }.c-lane { fill: var(--lane-fill); stroke: var(--lane-stroke); stroke-dasharray: 6,6; }++ /* Optional trace animation, enabled only by meta.animation = "trace".+ Static diagrams do not carry data-animation and render exactly as before. */+ svg[data-animation="trace"] [data-animate="edge"] {+ stroke-dasharray: 10 8;+ stroke-dashoffset: 54;+ animation: archify-edge-flow 2.4s linear infinite;+ animation-delay: calc(var(--step, 0) * 160ms);+ }+ svg[data-animation="trace"] [data-animate="node"] {+ transform-box: fill-box;+ transform-origin: center;+ animation: archify-node-pulse 3.6s ease-in-out infinite;+ animation-delay: calc(var(--step, 0) * 160ms);+ }+ @keyframes archify-edge-flow {+ to { stroke-dashoffset: 0; }+ }+ @keyframes archify-node-pulse {+ 0%, 72%, 100% { filter: none; stroke-width: 1.5; }+ 18%, 36% {+ filter: drop-shadow(0 0 8px var(--arrow-emphasis));+ stroke-width: 2.4;+ }+ }+ @media (prefers-reduced-motion: reduce) {+ svg[data-animation="trace"] [data-animate] {+ animation: none !important;+ stroke-dashoffset: 0;+ }+ }</style></head><body>diff --git a/examples/web-app.html b/examples/web-app.htmlindex 16f7b046..7a5ef8ff 100644--- a/examples/web-app.html+++ b/examples/web-app.html@@ -455,6 +455,37 @@.c-security-group { fill: transparent; stroke: var(--security-stroke); stroke-dasharray: 4,4; }.c-region { fill: rgba(251, 191, 36, 0.05); stroke: var(--cloud-stroke); stroke-dasharray: 8,4; }.c-lane { fill: var(--lane-fill); stroke: var(--lane-stroke); stroke-dasharray: 6,6; }++ /* Optional trace animation, enabled only by meta.animation = "trace".+ Static diagrams do not carry data-animation and render exactly as before. */+ svg[data-animation="trace"] [data-animate="edge"] {+ stroke-dasharray: 10 8;+ stroke-dashoffset: 54;+ animation: archify-edge-flow 2.4s linear infinite;+ animation-delay: calc(var(--step, 0) * 160ms);+ }+ svg[data-animation="trace"] [data-animate="node"] {+ transform-box: fill-box;+ transform-origin: center;+ animation: archify-node-pulse 3.6s ease-in-out infinite;+ animation-delay: calc(var(--step, 0) * 160ms);+ }+ @keyframes archify-edge-flow {+ to { stroke-dashoffset: 0; }+ }+ @keyframes archify-node-pulse {+ 0%, 72%, 100% { filter: none; stroke-width: 1.5; }+ 18%, 36% {+ filter: drop-shadow(0 0 8px var(--arrow-emphasis));+ stroke-width: 2.4;+ }+ }+ @media (prefers-reduced-motion: reduce) {+ svg[data-animation="trace"] [data-animate] {+ animation: none !important;+ stroke-dashoffset: 0;+ }+ }</style></head><body>diff --git a/examples/workflow-agent-tool-call-rendered.html b/examples/workflow-agent-tool-call-rendered.htmlindex e5b074ee..d823e61b 100644--- a/examples/workflow-agent-tool-call-rendered.html+++ b/examples/workflow-agent-tool-call-rendered.html@@ -455,6 +455,37 @@.c-security-group { fill: transparent; stroke: var(--security-stroke); stroke-dasharray: 4,4; }.c-region { fill: rgba(251, 191, 36, 0.05); stroke: var(--cloud-stroke); stroke-dasharray: 8,4; }.c-lane { fill: var(--lane-fill); stroke: var(--lane-stroke); stroke-dasharray: 6,6; }++ /* Optional trace animation, enabled only by meta.animation = "trace".+ Static diagrams do not carry data-animation and render exactly as before. */+ svg[data-animation="trace"] [data-animate="edge"] {+ stroke-dasharray: 10 8;+ stroke-dashoffset: 54;+ animation: archify-edge-flow 2.4s linear infinite;+ animation-delay: calc(var(--step, 0) * 160ms);+ }+ svg[data-animation="trace"] [data-animate="node"] {+ transform-box: fill-box;+ transform-origin: center;+ animation: archify-node-pulse 3.6s ease-in-out infinite;+ animation-delay: calc(var(--step, 0) * 160ms);+ }+ @keyframes archify-edge-flow {+ to { stroke-dashoffset: 0; }+ }+ @keyframes archify-node-pulse {+ 0%, 72%, 100% { filter: none; stroke-width: 1.5; }+ 18%, 36% {+ filter: drop-shadow(0 0 8px var(--arrow-emphasis));+ stroke-width: 2.4;+ }+ }+ @media (prefers-reduced-motion: reduce) {+ svg[data-animation="trace"] [data-animate] {+ animation: none !important;+ stroke-dashoffset: 0;+ }+ }</style></head><body>@@ -568,7 +599,7 @@<path d="M 220 145 L 220 166 L 300 166 L 300 209" class="a-emphasis" stroke-width="1.8" marker-end="url(#arrowhead-emphasis)"/><path d="M 346 243 L 384 243" class="a-default" stroke-width="1.4" marker-end="url(#arrowhead)"/><path d="M 430 269 L 430 290 L 430 290 L 430 333" class="a-security" stroke-width="1.4" marker-end="url(#arrowhead-security)"/>- <path d="M 430 401 L 430 476 L 500 476 L 500 581" class="a-emphasis" stroke-width="1.8" marker-end="url(#arrowhead-emphasis)"/>+ <path d="M 384 367 L 356 367 L 356 615 L 454 615" class="a-emphasis" stroke-width="1.8" marker-end="url(#arrowhead-emphasis)"/><path d="M 430 401 L 430 414 L 500 414 L 500 465" class="a-security" stroke-width="1.4" marker-end="url(#arrowhead-security)"/><path d="M 546 491 L 579 491" class="a-dashed" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/><path d="M 546 615 L 579 615" class="a-default" stroke-width="1.4" marker-end="url(#arrowhead)"/>