Skip to content

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

feat: spread shared automatic ports (#41)

tt-a1i1021de54676a
diff --git a/README.md b/README.md
index 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.md
index 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.md
index 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.zip
index 6df0fef1..fb7da72b 100644
Binary files a/archify.zip and b/archify.zip differ
diff --git a/archify/SKILL.md b/archify/SKILL.md
index 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.mjs
index 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.mjs
index 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.mjs
index 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),
points
diff --git a/archify/renderers/shared/geometry.mjs b/archify/renderers/shared/geometry.mjs
index 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.mjs
index 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.mjs
new file mode 100644
index 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'), /共享的自动端点会确定性展开/);
+});