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: spread shared automatic ports (#41)
tt-a1i1021de54676a
diff --git a/README.md b/README.mdindex dc9fa335..930c6bf6 100644--- a/README.md+++ b/README.md@@ -138,7 +138,7 @@ Architecture examples: [`web-app`](examples/web-app.html) · [`Archify pipeline`## Why Archify-- **Layout judgment over generic auto-layout** — the agent chooses hierarchy, spacing, routes, and emphasis for the story.+- **Layout judgment over generic auto-layout** — the agent chooses hierarchy, spacing, routes, and emphasis; shared automatic endpoints spread deterministically instead of piling arrows on one midpoint.- **Typed JSON IR** — every renderer-backed mode has a schema and reproducible source.- **Atomic validation before delivery** — schema, layout, HTML/SVG, route, and optional showcase checks must all pass before a final artifact replaces the last known good output.- **Truthful interaction** — focus, routes, role comparison, and stories reuse authored nodes and relationships instead of inventing topology.diff --git a/README_EN.md b/README_EN.mdindex dc9fa335..930c6bf6 100644--- a/README_EN.md+++ b/README_EN.md@@ -138,7 +138,7 @@ Architecture examples: [`web-app`](examples/web-app.html) · [`Archify pipeline`## Why Archify-- **Layout judgment over generic auto-layout** — the agent chooses hierarchy, spacing, routes, and emphasis for the story.+- **Layout judgment over generic auto-layout** — the agent chooses hierarchy, spacing, routes, and emphasis; shared automatic endpoints spread deterministically instead of piling arrows on one midpoint.- **Typed JSON IR** — every renderer-backed mode has a schema and reproducible source.- **Atomic validation before delivery** — schema, layout, HTML/SVG, route, and optional showcase checks must all pass before a final artifact replaces the last known good output.- **Truthful interaction** — focus, routes, role comparison, and stories reuse authored nodes and relationships instead of inventing topology.diff --git a/README_ZH.md b/README_ZH.mdindex a8488b12..18682126 100644--- a/README_ZH.md+++ b/README_ZH.md@@ -134,7 +134,7 @@ Architecture 示例:[`Web App`](examples/web-app.html) · [`Archify Pipeline`]## 为什么用 Archify-- **用布局判断代替通用自动布局** —— Agent 根据故事选择层级、留白、线路和强调关系。+- **用布局判断代替通用自动布局** —— Agent 根据故事选择层级、留白、线路和强调关系;共享的自动端点会确定性展开,不再让多支箭头堆在同一个中点。- **Typed JSON IR** —— 每种 Renderer 模式都有 Schema 和可复现的源文件。- **原子交付前校验** —— Schema、布局、HTML/SVG、线路和可选 Showcase 检查必须全部通过,成品才会替换上一份可信结果。- **交互不编造拓扑** —— 聚焦、路径、角色对比和故事都复用作者定义的节点与关系。diff --git a/archify.zip b/archify.zipindex 6df0fef1..fb7da72b 100644Binary files a/archify.zip and b/archify.zip differdiff --git a/archify/SKILL.md b/archify/SKILL.mdindex 25315ad1..4ed9dcdc 100644--- a/archify/SKILL.md+++ b/archify/SKILL.md@@ -82,6 +82,8 @@ All five modes follow the same loop: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 established 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. A relationship passing through an unrelated opaque semantic node is always a hard correctness failure, even when neither `meta.quality_profile` nor CLI `--quality` is present: paint order must never make one authored relationship look like a different topology. The shared Clean Flow Gate reports `clean-flow/edge-through-node`, the exact collection/index and optional relationship ID, obstacle ID, first intersecting segment, 2px clearance, and supported routing/placement knobs before output is written. Stricter composition preferences remain profile-aware. For new or edited work, choose `standard` or `showcase` explicitly; structural container-border rules apply to both explicit profiles, unrelated proper X crossings and unrelated collinear overlaps of at least 8px warn in `standard` and fail in `showcase`, and showcase also fails any sub-8px route segment and sub-16px interior turn while preserving ordinary 8–15px endpoint stubs. Collinear corridors are not proper crossings; the separate `composition/ambiguous-corridor` rule exempts relationships with a shared semantic endpoint, point touches, and overlaps below 8px. Source/target boxes are endpoints; boundaries, lanes, stages, lifecycle bands, sequence segments/lifelines/activations, and other containers remain intentional pass-through geometry. CJK text is measured at double width automatically.+Automatic Port Spread is a default renderer behavior for architecture, workflow, data-flow, and lifecycle diagrams. When two or more eligible automatic relationships share one node-side midpoint, assign deterministic, symmetric edge ports ordered by the opposite endpoint, while preserving a 16px corner gutter. It does not apply to sequence messages, a single relationship, or any relationship with explicit `via`, `channelX`, `channelY`, `labelAt`, or a non-`auto` route; authored geometry always wins. This is bounded endpoint separation, not a graph layout engine, and it must not change topology, schema, labels, presets, viewer state, or export behavior.+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 plus one explicit 44px `Live` / `Still` Motion Governor. Ambient scan, edge, and node motion must run one finite pass, permanently settle for that document generation, and restore every authored solid/security/async dash style; switching `Still` back to `Live` must not replay it. Story, Chapter, Route, Lens, Relationship Preview, Intent Trace, Focus, and Legend remain stronger semantic owners. `Still` must reset every effect to complete static meaning, pause active Story playback at its exact beat, persist the reader choice when storage is available, and never auto-resume playback. Dynamic `prefers-reduced-motion` and page hiding use the same stop path. Static artifacts must never start decorative motion or show the control; embed remains calm unless `?play=1` explicitly requests one bounded chapter. Route Probe uses one finite signal and then leaves the exact route static. Canonical SVG and raster exports remain still; only the isolated WebM clone may explicitly opt into the repeatable finite trace timeline. Motion ownership is viewer-only, tokenized for stale-safe cleanup, and never enters schema, IR, renderer layout, or authored geometry.Use `meta.views` when one overview needs a short, curated reading sequence. Each view is a label plus a set of existing semantic node IDs; it never changes layout, geometry, or styling. Keep the collection intentionally small (maximum five):@@ -299,7 +301,7 @@ Output includes component rects, boundaries, connection point paths, and label p- **Free coordinates** — `pos: [x, y]` is the component's top-left; `size: [w, h]` defaults to `[120, 60]`. Unlike the typed modes there is no lane/stage grid — asymmetric placement is yours to choose. `meta.viewBox` is optional (auto-fitted to your components + a legend row).- **Grid placement** — optional `layout.mode: "grid"` with `row`/`col` per component (see above). Not dagre; fixed cell spacing only.- **Boundaries from `wraps`** — list the component ids a `region` (dashed amber) or `security-group` (dashed rose) encloses; the renderer computes the box with correct 30/50 padding automatically. Never hand-arithmetic a boundary again.-- **Connections** route like edges (`variant`, `fromSide`/`toSide`, `route: straight|orthogonal-h|orthogonal-v|auto`, `via`, `labelDx/labelDy/labelAt`). Architecture `auto` preserves the original H-V-H dogleg when it is clear and tries the complementary in-bounds V-H-V dogleg only when the first would cross an unrelated component; explicit routing is never rewritten. For a vertical labeled connection, push the label into the gap with `labelDy` (the validator will tell you if it lands on a box).+- **Connections** route like edges (`variant`, `fromSide`/`toSide`, `route: straight|orthogonal-h|orthogonal-v|auto`, `via`, `labelDx/labelDy/labelAt`). Architecture `auto` preserves the original H-V-H dogleg when it is clear and tries the complementary in-bounds V-H-V dogleg only when the first would cross an unrelated component; eligible shared automatic endpoints use the bounded Automatic Port Spread rule above, while explicit routing is never rewritten. For a vertical labeled connection, push the label into the gap with `labelDy` (the validator will tell you if it lands on a box).- The renderer auto-emits the two-rect `c-mask` pattern, draws arrows before boxes (z-order), builds the legend from the component types you used, and **fails fast on component overlap, off-canvas components/boundaries, unknown wraps/connection ids, label-vs-component collisions, and non-finite coordinates** — the same reliability the other four modes already had.### Hand-placed fallback (no renderer available)diff --git a/archify/renderers/architecture/render-architecture.mjs b/archify/renderers/architecture/render-architecture.mjsindex 673ba0bb..e8fd995a 100644--- a/archify/renderers/architecture/render-architecture.mjs+++ b/archify/renderers/architecture/render-architecture.mjs@@ -17,6 +17,7 @@ import {suggestLabelObstacleFix,suggestComponentSeparation,anchor,+ automaticPortSpread,defaultFromSide,defaultToSide,chosenSide,@@ -350,12 +351,14 @@ function routeVia(conn, from, to, start, end) {}const pathCache = new Map();+const automaticPorts = automaticPortSpread(arch.connections, components);function pathFor(conn) {if (pathCache.has(conn)) return pathCache.get(conn);const from = components.get(conn.from);const to = components.get(conn.to);- const start = anchor(from, chosenSide(conn.fromSide, defaultFromSide(from, to)));- const end = anchor(to, chosenSide(conn.toSide, defaultToSide(from, to)));+ const ports = automaticPorts.get(conn);+ const start = ports?.from || anchor(from, chosenSide(conn.fromSide, defaultFromSide(from, to)));+ const end = ports?.to || anchor(to, chosenSide(conn.toSide, defaultToSide(from, to)));const points = [start, ...routeVia(conn, from, to, start, end), end];const routed = { d: roundedPath(points, 8), points };pathCache.set(conn, routed);diff --git a/archify/renderers/dataflow/render-dataflow.mjs b/archify/renderers/dataflow/render-dataflow.mjsindex dbfd7133..ae94b4f4 100644--- a/archify/renderers/dataflow/render-dataflow.mjs+++ b/archify/renderers/dataflow/render-dataflow.mjs@@ -14,6 +14,7 @@ import {suggestLabelObstacleFix,suggestLabelPairFix,anchor,+ automaticPortSpread,defaultFromSide,defaultToSide,chosenSide,@@ -264,13 +265,15 @@ function routeVia(flow, from, to, start, end) {}const pathCache = new Map();+const automaticPorts = automaticPortSpread(dataflow.flows, nodes);function pathFor(flow) {if (pathCache.has(flow)) return pathCache.get(flow);const from = nodes.get(flow.from);const to = nodes.get(flow.to);- const start = anchor(from, chosenSide(flow.fromSide, defaultFromSide(from, to)));- const end = anchor(to, chosenSide(flow.toSide, defaultToSide(from, to)));+ const ports = automaticPorts.get(flow);+ const start = ports?.from || anchor(from, chosenSide(flow.fromSide, defaultFromSide(from, to)));+ const end = ports?.to || anchor(to, chosenSide(flow.toSide, defaultToSide(from, to)));const points = [start, ...routeVia(flow, from, to, start, end), end];const routed = { d: polylinePath(points), points };pathCache.set(flow, routed);diff --git a/archify/renderers/lifecycle/render-lifecycle.mjs b/archify/renderers/lifecycle/render-lifecycle.mjsindex b1d780e9..191164b1 100644--- a/archify/renderers/lifecycle/render-lifecycle.mjs+++ b/archify/renderers/lifecycle/render-lifecycle.mjs@@ -14,6 +14,7 @@ import {suggestLabelObstacleFix,suggestLabelPairFix,anchor,+ automaticPortSpread,defaultFromSide,defaultToSide,chosenSide,@@ -307,14 +308,21 @@ function routeVia(transition, from, to, start, end) {}const pathCache = new Map();+const automaticPorts = automaticPortSpread(lifecycle.transitions, states);function pathFor(transition) {if (pathCache.has(transition)) return pathCache.get(transition);const from = states.get(transition.from);const to = states.get(transition.to);- const start = anchor(from, chosenSide(transition.fromSide, defaultFromSide(from, to)));- const end = anchor(to, chosenSide(transition.toSide, defaultToSide(from, to)));- const points = [start, ...routeVia(transition, from, to, start, end), end];+ const ports = automaticPorts.get(transition);+ const start = ports?.from || anchor(from, chosenSide(transition.fromSide, defaultFromSide(from, to)));+ const end = ports?.to || anchor(to, chosenSide(transition.toSide, defaultToSide(from, to)));+ let via = routeVia(transition, from, to, start, end);+ if (ports && !via.length && Math.abs(start[0] - end[0]) >= 4 && Math.abs(start[1] - end[1]) >= 4) {+ const midX = (start[0] + end[0]) / 2;+ via = [[midX, start[1]], [midX, end[1]]];+ }+ const points = [start, ...via, end];const routed = {d: roundedPath(points, transition.cornerRadius ?? 10),pointsdiff --git a/archify/renderers/shared/geometry.mjs b/archify/renderers/shared/geometry.mjsindex 323eb6c3..6d9818cf 100644--- a/archify/renderers/shared/geometry.mjs+++ b/archify/renderers/shared/geometry.mjs@@ -608,6 +608,63 @@ export function anchor(rect, side) {}}+// Keep conservative auto-routed fan-out/fan-in relationships visually+// distinct without changing authored route controls. The returned map only+// contains endpoints that belong to a shared automatic midpoint anchor.+export function automaticPortSpread(relations, boxes, { gutter = 16, maxSpacing = 14 } = {}) {+ const groups = new Map();+ const spread = new Map();++ const add = (relation, endpoint, rect, side, counterpart) => {+ const key = `${rect.id}\u0000${side}`;+ const items = groups.get(key) || [];+ items.push({ relation, endpoint, rect, side, counterpart });+ groups.set(key, items);+ };++ for (const relation of asArray(relations)) {+ if (!relation || (relation.route && relation.route !== 'auto')) continue;+ if (relation.via || relation.channelX !== undefined || relation.channelY !== undefined || relation.labelAt) continue;+ const from = boxes.get(relation.from);+ const to = boxes.get(relation.to);+ if (!from || !to) continue;+ const fromSide = chosenSide(relation.fromSide, defaultFromSide(from, to));+ const toSide = chosenSide(relation.toSide, defaultToSide(from, to));+ add(relation, 'from', from, fromSide, to);+ add(relation, 'to', to, toSide, from);+ }++ for (const items of groups.values()) {+ if (items.length < 2) continue;+ const verticalSide = items[0].side === 'left' || items[0].side === 'right';+ items.sort((a, b) => {+ const aCoordinate = verticalSide ? a.counterpart.cy : a.counterpart.cx;+ const bCoordinate = verticalSide ? b.counterpart.cy : b.counterpart.cx;+ if (aCoordinate !== bCoordinate) return aCoordinate - bCoordinate;+ const aKey = `${a.relation.id || ''}\u0000${a.relation.from}\u0000${a.relation.to}\u0000${a.relation.label || ''}`;+ const bKey = `${b.relation.id || ''}\u0000${b.relation.from}\u0000${b.relation.to}\u0000${b.relation.label || ''}`;+ return aKey < bKey ? -1 : aKey > bKey ? 1 : 0;+ });++ const extent = verticalSide ? items[0].rect.height : items[0].rect.width;+ const usable = Math.max(0, extent - gutter * 2);+ const spacing = Math.min(maxSpacing, usable / (items.length - 1));+ if (!(spacing > 0)) continue;++ for (const [index, item] of items.entries()) {+ const offset = (index - (items.length - 1) / 2) * spacing;+ const point = anchor(item.rect, item.side);+ if (verticalSide) point[1] += offset;+ else point[0] += offset;+ const endpoints = spread.get(item.relation) || {};+ endpoints[item.endpoint] = point;+ spread.set(item.relation, endpoints);+ }+ }++ return spread;+}+export function defaultFromSide(from, to) {if (to.cx < from.cx) return 'left';if (to.cx > from.cx) return 'right';diff --git a/archify/renderers/workflow/render-workflow.mjs b/archify/renderers/workflow/render-workflow.mjsindex 68ce54cf..394d006a 100644--- a/archify/renderers/workflow/render-workflow.mjs+++ b/archify/renderers/workflow/render-workflow.mjs@@ -14,6 +14,7 @@ import {suggestLabelObstacleFix,suggestLabelPairFix,anchor,+ automaticPortSpread,defaultFromSide,defaultToSide,chosenSide,@@ -434,13 +435,15 @@ function routeVia(edge, from, to, start, end) {}const pathCache = new Map();+const automaticPorts = automaticPortSpread(workflow.edges, nodes);function pathFor(edge) {if (pathCache.has(edge)) return pathCache.get(edge);const from = nodes.get(edge.from);const to = nodes.get(edge.to);- const start = anchor(from, chosenSide(edge.fromSide, defaultFromSide(from, to)));- const end = anchor(to, chosenSide(edge.toSide, defaultToSide(from, to)));+ const ports = automaticPorts.get(edge);+ const start = ports?.from || anchor(from, chosenSide(edge.fromSide, defaultFromSide(from, to)));+ const end = ports?.to || anchor(to, chosenSide(edge.toSide, defaultToSide(from, to)));const points = [start, ...routeVia(edge, from, to, start, end), end];const routed = { d: polylinePath(points), points };pathCache.set(edge, routed);diff --git a/archify/test/automatic-port-spread.test.mjs b/archify/test/automatic-port-spread.test.mjsnew file mode 100644index 00000000..f0b6d34f--- /dev/null+++ b/archify/test/automatic-port-spread.test.mjs@@ -0,0 +1,212 @@+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, '..');++function render(mode, doc) {+ const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-port-spread-'));+ const input = path.join(tmp, 'input.json');+ const output = path.join(tmp, 'output.html');+ fs.writeFileSync(input, JSON.stringify(doc));+ try {+ execFileSync('node', [+ path.join(skillRoot, `renderers/${mode}/render-${mode}.mjs`),+ input,+ output,+ ], { stdio: ['ignore', 'ignore', 'pipe'] });+ return fs.readFileSync(output, 'utf8');+ } finally {+ fs.rmSync(tmp, { recursive: true, force: true });+ }+}++function connectionPoints(html, id) {+ const pattern = new RegExp(`data-edge-id="${id}"[^>]+data-composition-points="([^"]+)"`);+ const match = html.match(pattern);+ assert.ok(match, `missing rendered connection ${id}`);+ return match[1].split(';').map((point) => point.split(',').map(Number));+}++function fanOutArchitecture(connections) {+ return {+ schema_version: 1,+ diagram_type: 'architecture',+ meta: { title: 'Automatic port spread' },+ components: [+ { id: 'hub', type: 'backend', label: 'Hub', pos: [100, 280], size: [120, 60] },+ { id: 'upper', type: 'external', label: 'Upper', pos: [500, 100], size: [120, 60] },+ { id: 'middle', type: 'database', label: 'Middle', pos: [500, 280], size: [120, 60] },+ { id: 'lower', type: 'cloud', label: 'Lower', pos: [500, 460], size: [120, 60] },+ ],+ connections,+ };+}++test('architecture: automatic fan-out uses distinct symmetric ports with corner clearance', () => {+ const html = render('architecture', fanOutArchitecture([+ { id: 'to-upper', from: 'hub', to: 'upper' },+ { id: 'to-middle', from: 'hub', to: 'middle' },+ { id: 'to-lower', from: 'hub', to: 'lower' },+ ]));++ assert.deepEqual(connectionPoints(html, 'to-upper')[0], [220, 296]);+ assert.deepEqual(connectionPoints(html, 'to-middle')[0], [220, 310]);+ assert.deepEqual(connectionPoints(html, 'to-lower')[0], [220, 324]);+});++test('architecture: automatic port assignment is stable when relationship input order changes', () => {+ const connections = [+ { id: 'to-upper', from: 'hub', to: 'upper' },+ { id: 'to-middle', from: 'hub', to: 'middle' },+ { id: 'to-lower', from: 'hub', to: 'lower' },+ ];+ const forward = render('architecture', fanOutArchitecture(connections));+ const reversed = render('architecture', fanOutArchitecture([...connections].reverse()));++ for (const connection of connections) {+ assert.deepEqual(+ connectionPoints(forward, connection.id),+ connectionPoints(reversed, connection.id),+ `${connection.id} moved after input reordering`,+ );+ }+});++test('architecture: single and explicitly positioned relationships keep legacy anchors', () => {+ const doc = fanOutArchitecture([+ { id: 'single', from: 'hub', to: 'middle' },+ { id: 'via', from: 'hub', to: 'upper', via: [[300, 310], [300, 130]] },+ { id: 'fixed-route', from: 'hub', to: 'lower', route: 'orthogonal-h' },+ { id: 'fixed-label', from: 'hub', to: 'upper', label: 'contract', labelAt: [360, 200] },+ ]);+ const html = render('architecture', doc);++ assert.deepEqual(connectionPoints(html, 'single'), [[220, 310], [500, 310]]);+ assert.deepEqual(connectionPoints(html, 'via'), [[220, 310], [300, 310], [300, 130], [500, 130]]);+ assert.deepEqual(connectionPoints(html, 'fixed-route'), [[220, 310], [360, 310], [360, 490], [500, 490]]);+ assert.deepEqual(connectionPoints(html, 'fixed-label'), [[220, 310], [360, 310], [360, 130], [500, 130]]);+});++test('workflow: automatic cross-lane fan-out spreads the shared source port', () => {+ const html = render('workflow', {+ schema_version: 1,+ diagram_type: 'workflow',+ meta: { title: 'Workflow port spread' },+ lanes: [+ { id: 'upper-lane', label: 'Upper' },+ { id: 'hub-lane', label: 'Hub' },+ { id: 'lower-lane', label: 'Lower' },+ ],+ nodes: [+ { id: 'hub', lane: 'hub-lane', col: 0, type: 'backend', label: 'Hub' },+ { id: 'upper', lane: 'upper-lane', col: 3, type: 'external', label: 'Upper' },+ { id: 'middle', lane: 'hub-lane', col: 3, type: 'database', label: 'Middle' },+ { id: 'lower', lane: 'lower-lane', col: 3, type: 'cloud', label: 'Lower' },+ ],+ edges: [+ { id: 'to-upper', from: 'hub', to: 'upper' },+ { id: 'to-middle', from: 'hub', to: 'middle' },+ { id: 'to-lower', from: 'hub', to: 'lower' },+ ],+ });++ assert.deepEqual(connectionPoints(html, 'to-upper')[0], [134, 233]);+ assert.deepEqual(connectionPoints(html, 'to-middle')[0], [134, 243]);+ assert.deepEqual(connectionPoints(html, 'to-lower')[0], [134, 253]);+});++test('dataflow: automatic fan-out spreads flows without changing their authored topology', () => {+ const html = render('dataflow', {+ schema_version: 1,+ diagram_type: 'dataflow',+ meta: { title: 'Data-flow port spread' },+ stages: [{ label: 'Source' }, { label: 'Transform' }, { label: 'Sinks' }],+ nodes: [+ { id: 'hub', type: 'backend', label: 'Hub', stage: 0, row: 2 },+ { id: 'upper', type: 'external', label: 'Upper', stage: 2, row: 0 },+ { id: 'middle', type: 'database', label: 'Middle', stage: 2, row: 2 },+ { id: 'lower', type: 'cloud', label: 'Lower', stage: 2, row: 4 },+ ],+ flows: [+ { id: 'to-upper', from: 'hub', to: 'upper', label: 'upper feed' },+ { id: 'to-middle', from: 'hub', to: 'middle', label: 'middle feed' },+ { id: 'to-lower', from: 'hub', to: 'lower', label: 'lower feed' },+ ],+ });++ assert.deepEqual(connectionPoints(html, 'to-upper')[0], [156, 372]);+ assert.deepEqual(connectionPoints(html, 'to-middle')[0], [156, 385]);+ assert.deepEqual(connectionPoints(html, 'to-lower')[0], [156, 398]);+});++test('lifecycle: automatic fan-out spreads transitions across lifecycle bands', () => {+ const html = render('lifecycle', {+ schema_version: 1,+ diagram_type: 'lifecycle',+ meta: { title: 'Lifecycle port spread' },+ lanes: [+ { id: 'main', label: 'Main' },+ { id: 'event', label: 'Events' },+ { id: 'terminal', label: 'Outcomes' },+ ],+ states: [+ { id: 'hub', type: 'active', label: 'Hub', lane: 'event', col: 0 },+ { id: 'upper', type: 'waiting', label: 'Upper', lane: 'main', col: 4 },+ { id: 'middle', type: 'success', label: 'Middle', lane: 'event', col: 2 },+ { id: 'lower', type: 'failure', label: 'Lower', lane: 'terminal', col: 2 },+ ],+ transitions: [+ { id: 'to-upper', from: 'hub', to: 'upper' },+ { id: 'to-middle', from: 'hub', to: 'middle' },+ { id: 'to-lower', from: 'hub', to: 'lower' },+ ],+ });++ assert.deepEqual(connectionPoints(html, 'to-upper')[0], [465, 294]);+ assert.deepEqual(connectionPoints(html, 'to-middle')[0], [465, 307]);+ assert.deepEqual(connectionPoints(html, 'to-lower')[0], [465, 320]);+});++test('lifecycle: same-band port spread remains orthogonal', () => {+ const html = render('lifecycle', {+ schema_version: 1,+ diagram_type: 'lifecycle',+ meta: { title: 'Orthogonal same-band spread' },+ lanes: [{ id: 'main', label: 'Main' }],+ states: [+ { id: 'hub', type: 'active', label: 'Hub', lane: 'main', col: 0 },+ { id: 'upper', type: 'waiting', label: 'Upper', lane: 'main', col: 2, yOffset: -50 },+ { id: 'lower', type: 'success', label: 'Lower', lane: 'main', col: 4, yOffset: 50 },+ ],+ transitions: [+ { id: 'to-upper', from: 'hub', to: 'upper' },+ { id: 'to-lower', from: 'hub', to: 'lower' },+ ],+ });++ assert.deepEqual(connectionPoints(html, 'to-upper'), [+ [153, 150], [248, 150], [248, 107], [343, 107],+ ]);+ assert.deepEqual(connectionPoints(html, 'to-lower'), [+ [153, 164], [402, 164], [402, 207], [651, 207],+ ]);+});++test('skill and READMEs describe automatic port spread as bounded default behavior', () => {+ const skill = fs.readFileSync(path.join(skillRoot, 'SKILL.md'), 'utf8');+ assert.match(skill, /Automatic Port Spread is a default renderer behavior/);+ assert.match(skill, /single relationship|single relationships/);+ assert.match(skill, /explicit `via`.*`channelX`.*`channelY`.*`labelAt`/);++ const repoRoot = path.resolve(skillRoot, '..');+ for (const file of ['README.md', 'README_EN.md']) {+ assert.match(fs.readFileSync(path.join(repoRoot, file), 'utf8'), /shared automatic endpoints spread deterministically/);+ }+ assert.match(fs.readFileSync(path.join(repoRoot, 'README_ZH.md'), 'utf8'), /共享的自动端点会确定性展开/);+});