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(checker): preserve explicitly authored straight route intent
tt-a1i4f8e59416a44
diff --git a/archify.zip b/archify.zipindex 20cff800..a610c64e 100644Binary files a/archify.zip and b/archify.zip differdiff --git a/archify/references/authoring-contract.md b/archify/references/authoring-contract.mdindex 70fb1584..82913041 100644--- a/archify/references/authoring-contract.md+++ b/archify/references/authoring-contract.md@@ -105,6 +105,7 @@ in the generated viewer.- Node anchors start at side midpoints. `left`/`right` change the horizontal endpoint; `top`/`bottom` change the vertical endpoint. For an automatic Architecture relationship, unobstructed facing ports whose axis offset is under 16px may share one horizontal or vertical axis when both endpoints retain the 16px corner gutter. If exactly one endpoint belongs to a spread group, only its unshared counterpart moves; relationships spread at both endpoints keep their distinct ports and outside bridge.- A side is a direction contract. The first and final route segment must be perpendicular and outward/inward in the named direction.+- In architecture, data-flow, and lifecycle diagrams, explicit `route: "straight"` requests one direct segment, which may be diagonal when endpoint sides are not pinned. The artifact checker preserves this intent; explicit sides, opaque-node clearance, and other quality gates still apply. `via` takes precedence and retains existing rules, including data-flow's requirement for orthogonal via segments.- Automatic Port Spread is a default renderer behavior for architecture, workflow, data-flow, and lifecycle diagrams. Shared automatic endpoints spread deterministically and symmetrically with a 16px corner gutter. It does not apply to sequence messages, single relationships, or explicit `via`, `channelX`, `channelY`, `labelAt`, or non-`auto` routes.- Showcase route rhythm: every nonzero segment must be at least 8px; every interior segment must be at least 16px. When spread ports are nearly parallel, the router uses a 24px endpoint stub and a 16px outside bridge instead of manufacturing a tiny dogleg.- Shared endpoint corridors are allowed only when they remain semantically unambiguous. Unrelated collinear overlap of 8px or more fails showcase.diff --git a/archify/renderers/architecture/render-architecture.mjs b/archify/renderers/architecture/render-architecture.mjsindex b21ac8e4..9bc0a752 100644--- a/archify/renderers/architecture/render-architecture.mjs+++ b/archify/renderers/architecture/render-architecture.mjs@@ -34,6 +34,7 @@ import {normalizeRoutePoints,polylinePath,routePointsValue,+ authoredStraightRouteAttrs,roundedPath,labelPoint,componentFill,@@ -965,7 +966,7 @@ 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 ${focusEdgeAttrs(conn.from, conn.to, conn.label, index, conn.id)} data-composition-points="${routePointsValue(routed.points)}" d="${routed.d}" class="${cls}"${animateAttr(arch.meta, 'edge', index)} stroke-width="${strokeWidth}" marker-end="url(#${marker})"/>`;+ return ` <path ${focusEdgeAttrs(conn.from, conn.to, conn.label, index, conn.id)} data-composition-points="${routePointsValue(routed.points)}"${authoredStraightRouteAttrs(conn, routed.points)} d="${routed.d}" class="${cls}"${animateAttr(arch.meta, 'edge', index)} stroke-width="${strokeWidth}" marker-end="url(#${marker})"/>`;}function renderConnectionLabel(conn, index) {diff --git a/archify/renderers/dataflow/render-dataflow.mjs b/archify/renderers/dataflow/render-dataflow.mjsindex 3eda9d4a..a16ced96 100644--- a/archify/renderers/dataflow/render-dataflow.mjs+++ b/archify/renderers/dataflow/render-dataflow.mjs@@ -27,6 +27,7 @@ import {chosenSide,polylinePath,routePointsValue,+ authoredStraightRouteAttrs,labelPoint,componentFill,componentText,@@ -399,7 +400,7 @@ 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 ${focusEdgeAttrs(flow.from, flow.to, flow.label, index, flow.id)} data-composition-points="${routePointsValue(routed.points)}" d="${routed.d}" class="${cls}"${animateAttr(dataflow.meta, 'edge', index)} stroke-width="${strokeWidth}" marker-end="url(#${marker})"/>`;+ return ` <path ${focusEdgeAttrs(flow.from, flow.to, flow.label, index, flow.id)} data-composition-points="${routePointsValue(routed.points)}"${authoredStraightRouteAttrs(flow, routed.points)} d="${routed.d}" class="${cls}"${animateAttr(dataflow.meta, 'edge', index)} stroke-width="${strokeWidth}" marker-end="url(#${marker})"/>`;}function renderFlowLabel(flow, index) {diff --git a/archify/renderers/lifecycle/README.md b/archify/renderers/lifecycle/README.mdindex b66a7ddf..733d2960 100644--- a/archify/renderers/lifecycle/README.md+++ b/archify/renderers/lifecycle/README.md@@ -89,8 +89,9 @@ corners; tune them with `cornerRadius` (default 10, `0` for sharp bends).- Use lower lanes only for interruptions, recovery, and terminal exits.- Keep transition labels out of the main SVG unless the label is essential;prefer node labels, tags, legend entries, and summary cards.-- Avoid diagonal and crossing lines. Terminal exits should drop vertically from- their source event whenever possible.+- Prefer axis-aligned lines and avoid crossings. Terminal exits should drop+ vertically from their source event whenever possible. Explicit `straight`+ routes remain supported; see the [authored routing contract](../../references/authoring-contract.md#executable-geometry-rules).- Use `success` for completion, `failure` for failure/terminal exits,`waiting` for pauses, and `decision` for quality gates.diff --git a/archify/renderers/lifecycle/render-lifecycle.mjs b/archify/renderers/lifecycle/render-lifecycle.mjsindex eb7922c4..dffc7a2e 100644--- a/archify/renderers/lifecycle/render-lifecycle.mjs+++ b/archify/renderers/lifecycle/render-lifecycle.mjs@@ -27,6 +27,7 @@ import {chosenSide,roundedPath,routePointsValue,+ authoredStraightRouteAttrs,labelPoint,arrowClassMap,variantAccent@@ -465,7 +466,7 @@ 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 ${focusEdgeAttrs(transition.from, transition.to, transition.label, index, transition.id)} data-composition-points="${routePointsValue(routed.points)}" d="${routed.d}" class="${cls}"${animateAttr(lifecycle.meta, 'edge', index)} stroke-width="${strokeWidth}" marker-end="url(#${marker})"/>`;+ return ` <path ${focusEdgeAttrs(transition.from, transition.to, transition.label, index, transition.id)} data-composition-points="${routePointsValue(routed.points)}"${authoredStraightRouteAttrs(transition, routed.points)} d="${routed.d}" class="${cls}"${animateAttr(lifecycle.meta, 'edge', index)} stroke-width="${strokeWidth}" marker-end="url(#${marker})"/>`;}function renderTransitionLabel(transition, index) {diff --git a/archify/renderers/shared/geometry.mjs b/archify/renderers/shared/geometry.mjsindex 733129c2..6a1abbb1 100644--- a/archify/renderers/shared/geometry.mjs+++ b/archify/renderers/shared/geometry.mjs@@ -1300,6 +1300,16 @@ export function routePointsValue(points) {.join(';');}+// Only a direct, explicitly authored diagonal needs an artifact-check exception.+// Nonempty via takes precedence; empty via adds no intermediate geometry.+export function authoredStraightRouteAttrs(relation, points) {+ if (relation.route !== 'straight' || relation.via?.length || points.length !== 2) return '';+ const [start, end] = points;+ return Math.abs(start[0] - end[0]) > 0.01 && Math.abs(start[1] - end[1]) > 0.01+ ? ' data-composition-route="straight"'+ : '';+}+export function roundedPath(points, radius) {if (points.length < 3 || radius <= 0) {return polylinePath(points);diff --git a/archify/scripts/check-render-output.mjs b/archify/scripts/check-render-output.mjsindex d24ce7f6..0b79e837 100644--- a/archify/scripts/check-render-output.mjs+++ b/archify/scripts/check-render-output.mjs@@ -81,7 +81,7 @@ if (svgMatches.length === 1) {addCheck('orthogonal_arrows',diagonal.length === 0,- diagonal.map(({ arrow, segmentIndex }) => `${arrow.kind} ${arrow.index} segment ${segmentIndex + 1}: ${arrow.raw}`),+ diagonal.map(({ arrow, segmentIndex }) => `${arrow.kind} ${arrow.index} segment ${segmentIndex + 1}: expected an orthogonal segment or an explicitly authored direct straight route; ${arrow.raw}`),);const relationshipCrossings = collectRelationshipCrossings(arrows);const compositionFrames = collectCompositionFrames(beforeLegend);@@ -295,6 +295,12 @@ function collectArrows(fragment) {kind: tag[1].toLowerCase(),index: index += 1,raw,+ // Trust route intent only for a semantic edge with one visible direct+ // segment. A stale marker on bent/curved geometry cannot waive the gate.+ authoredStraight: attrs['data-composition-route'] === 'straight'+ && Boolean(attrs['data-edge-from'] && attrs['data-edge-to'])+ && segments.length === 1 && borderSegments.length === 1+ && (tag[1].toLowerCase() === 'line' || /^\s*M\s+[-+\d.eE]+\s+[-+\d.eE]+\s+L\s+[-+\d.eE]+\s+[-+\d.eE]+\s*$/.test(attrs.d || '')),segments,borderSegments,routePoints: parseRoutePoints(attrs['data-composition-points']) || (@@ -556,6 +562,7 @@ function straightPathSegments(d) {}function diagonalStraightSegments(arrow) {+ if (arrow.authoredStraight) return [];return arrow.borderSegments.flatMap(({ start, end }, segmentIndex) => (Math.abs(start[0] - end[0]) > 0.01 && Math.abs(start[1] - end[1]) > 0.01? [{ segmentIndex, start, end }]diff --git a/archify/test/authored-straight-routes.test.mjs b/archify/test/authored-straight-routes.test.mjsnew file mode 100644index 00000000..77dadf01--- /dev/null+++ b/archify/test/authored-straight-routes.test.mjs@@ -0,0 +1,151 @@+import { after, test } from 'node:test';+import assert from 'node:assert/strict';+import { spawnSync } 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 skillRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-straight-routes-'));+after(() => fs.rmSync(tmp, { recursive: true, force: true }));+const common = { schema_version: 1, meta: { title: 'Direct handoff', quality_profile: 'standard' } };+const cases = {+ lifecycle: {+ document: {+ ...common, diagram_type: 'lifecycle',+ lanes: [{ id: 'main', label: 'Work' }, { id: 'recovery', label: 'Recovery' }],+ states: [+ { id: 'start', type: 'waiting', label: 'Waiting', lane: 'main', col: 1 },+ { id: 'end', type: 'failure', label: 'Failed', lane: 'recovery', col: 1 },+ ],+ transitions: [{ id: 'direct', from: 'start', to: 'end', route: 'straight' }],+ },+ collection: 'transitions', points: '307,157;493,307', d: 'M 307 157 L 493 307',+ },+ dataflow: {+ document: {+ ...common, diagram_type: 'dataflow', stages: [{ label: 'Input' }, { label: 'Output' }],+ nodes: [+ { id: 'start', type: 'frontend', label: 'Client', stage: 0, row: 0 },+ { id: 'end', type: 'database', label: 'Store', stage: 1, row: 1 },+ ],+ flows: [{ id: 'direct', from: 'start', to: 'end', label: 'payload', route: 'straight' }],+ },+ collection: 'flows', points: '156,157;259,271', d: 'M 156 157 L 259 271',+ },+ architecture: {+ document: {+ ...common, diagram_type: 'architecture', meta: { ...common.meta, viewBox: [640, 480] },+ components: [+ { id: 'start', type: 'frontend', label: 'Client', pos: [70, 70], size: [120, 54] },+ { id: 'end', type: 'database', label: 'Store', pos: [350, 230], size: [120, 54] },+ ],+ connections: [{ id: 'direct', from: 'start', to: 'end', route: 'straight' }],+ },+ collection: 'connections', points: '190,97;350,257', d: 'M 190 97 L 350 257',+ },+};++function run(...args) {+ return spawnSync(process.execPath, [path.join(skillRoot, 'bin/archify.mjs'), ...args], { encoding: 'utf8' });+}+function orthogonalCheck(result) {+ return JSON.parse(result.stdout).checks.find((check) => check.name === 'orthogonal_arrows');+}+function inputFor(name, document) {+ const input = path.join(tmp, `${name}.json`);+ fs.writeFileSync(input, JSON.stringify(document));+ return input;+}+function assertPassed(result) {+ assert.equal(result.status, 0, result.stderr + result.stdout);+}++for (const [type, { document, collection, points, d }] of Object.entries(cases)) {+ for (const quality of ['standard', 'showcase']) {+ test(`${type}: authored straight retains geometry through render, validate, check and deliver (${quality})`, () => {+ const input = inputFor(`${type}-${quality}`, { ...document, meta: { ...document.meta, quality_profile: quality } });+ const output = path.join(tmp, `${type}-${quality}.html`);+ assertPassed(run('render', type, input, output));+ const html = fs.readFileSync(output, 'utf8');+ assert.ok(html.includes(`data-composition-points="${points}" data-composition-route="straight" d="${d}"`));+ assertPassed(run('check', output));+ assertPassed(run('validate', type, input, '--json'));+ assertPassed(run('deliver', type, input, output, '--json'));+ assert.equal(fs.readFileSync(output, 'utf8'), html, 'delivery must retain the rendered geometry');++ fs.writeFileSync(output, html.replace(' data-composition-route="straight"', ''));+ const unmarked = run('check', output);+ assert.equal(unmarked.status, 1);+ assert.equal(orthogonalCheck(unmarked).ok, false, 'same geometry without authored intent must still fail');+ });+ }++ test(`${type}: automatic routes retain orthogonal behavior and explicit sides remain enforced`, () => {+ const automatic = structuredClone(document);+ delete automatic[collection][0].route;+ const input = inputFor(`${type}-auto`, automatic);+ const output = path.join(tmp, `${type}-auto.html`);+ assertPassed(run('render', type, input, output));+ const html = fs.readFileSync(output, 'utf8');+ assert.doesNotMatch(html, /data-composition-route="straight"/);+ assertPassed(run('check', output));++ const pinned = structuredClone(document);+ pinned[collection][0].fromSide = 'right';+ const rejected = run('render', type, inputFor(`${type}-pinned`, pinned), output);+ assert.equal(rejected.status, 1);+ assert.match(rejected.stderr, /clean-flow\/endpoint-side-direction/);+ });+}++for (const type of ['lifecycle', 'architecture']) {+ test(`${type}: an empty via preserves the explicitly authored direct straight route`, () => {+ const { document, collection, d } = cases[type];+ const withEmptyVia = structuredClone(document);+ withEmptyVia[collection][0].via = [];+ const output = path.join(tmp, `${type}-empty-via.html`);+ assertPassed(run('deliver', type, inputFor(`${type}-empty-via`, withEmptyVia), output, '--json'));+ assert.ok(fs.readFileSync(output, 'utf8').includes(`data-composition-route="straight" d="${d}"`));+ });+}++test('lifecycle: via overrides straight without granting a direct-route exception', () => {+ const document = structuredClone(cases.lifecycle.document);+ document.transitions[0].via = [[360, 195], [425, 250]];+ const input = inputFor('lifecycle-via', document);+ const output = path.join(tmp, 'lifecycle-via.html');+ assertPassed(run('render', 'lifecycle', input, output));+ const html = fs.readFileSync(output, 'utf8');+ assert.match(html, /data-composition-points="307,157;360,195;425,250;493,307"/);+ assert.doesNotMatch(html, /data-composition-route="straight"/);+ const checked = run('check', output);+ assert.equal(checked.status, 1);+ assert.equal(orthogonalCheck(checked).ok, false);+});++test('dataflow: via overrides straight and diagonal via still fails during rendering', () => {+ const document = structuredClone(cases.dataflow.document);+ document.flows[0].via = [[200, 200]];+ const rejected = run('render', 'dataflow', inputFor('dataflow-via', document), path.join(tmp, 'dataflow-via.html'));+ assert.equal(rejected.status, 1);+ assert.match(rejected.stderr, /diagonal segment/);+});++test('a straight intent marker cannot exempt bent, curved or unidentified diagonals', () => {+ const paths = [+ 'data-edge-from="a" data-edge-to="b" d="M 20 20 L 60 40 L 100 40"',+ 'data-edge-from="a" data-edge-to="b" d="M 20 20 L 60 40 Q 80 40 100 70"',+ 'd="M 20 20 L 120 80"',+ ];+ for (const [index, attrs] of paths.entries()) {+ const output = path.join(tmp, `stale-marker-${index}.html`);+ fs.writeFileSync(output, `<svg viewBox="0 0 240 160"><path ${attrs} data-composition-route="straight" class="a-default" marker-end="url(#arrowhead)"/></svg>`);+ const checked = run('check', output);+ assert.equal(checked.status, 1);+ const check = orthogonalCheck(checked);+ assert.equal(check.ok, false);+ assert.match(check.details[0], /expected an orthogonal segment or an explicitly authored direct straight route/);+ }+});