Skip to content

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

feat(architecture): place and route for clearer layouts

tt-a1i45ef2da0a1e8
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d7e559dc..7e667afc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,7 @@ All notable changes are documented here. Format loosely follows [Keep a Changelo
### Improved reading
- Showcase sequence message names use larger primary type and matching label plates; real browser readability checks now include message labels.
+- **Clearer Architecture layouts.** Authoring defaults now classify each relationship (main path, branch or store, return, second entrance, fan-out) before placement, with a measured side length for fan-out ports. A passing `finalize` receipt with crossings adds node-move `hints`, backed by new `routeReview` evidence (`sharedNode` on crossings, `crowdedSides` when a side faces more neighbours than it has ports); the Skill allows one bounded, position-only repair for crossings. Automatic routing steps fan-out siblings into free parallel channels and reaches a blocked row of neighbours through one vertical side instead of wrapping around it.
> Development identity: `v2.17.0-dev.1`. Not a stable release.
diff --git a/archify.zip b/archify.zip
index 26a81362..af2eff0a 100644
Binary files a/archify.zip and b/archify.zip differ
diff --git a/archify/SKILL.md b/archify/SKILL.md
index 4405a87c..23259d8d 100644
--- a/archify/SKILL.md
+++ b/archify/SKILL.md
@@ -76,6 +76,8 @@ Use the `finalize` command above for the first candidate and after a repair.
`finalize` stops at the first non-passing gate. Its compact stdout and `<output-stem>.finalize-summary.json` are ordinary evidence. A passing run creates no screenshots and reports `visualReview: "not-requested"`.
+When a passing Architecture receipt reports `visualReviewRecommendation.signals.resolvedCrossovers`, copy the candidate aside and apply the hints in one edit that changes only node positions and sizes: every node, relationship (including its `from` and `to`), label, and source stays as it was. Rerun the complete `finalize` once with `--out-dir <output-stem>.review-2`, because the previous HTML already owns its browser evidence. If that run fails or reports more crossings, restore the copy and finalize it with `--out-dir <output-stem>.review-3`. Do not start a second placement round. Hints about extra bends alone are optional.
+
Perceptual review is optional for ordinary generation, including a newly positioned Architecture. Use [Optional capture evidence](references/delivery-contract.md#optional-capture-evidence) when the user requests visual review, during development audits, or for a concrete route/browser concern. `visualReviewRecommendation` is advisory. Inspect captures before claiming visual quality; otherwise report automated checks only.
Read [Delivery contract](references/delivery-contract.md) for failed gates, standalone commands, provenance/recovery, repeated delivery, exports, or opening. Recovery follows `deliver` → strict provenance `check` → `browser-check`; captures require strict provenance.
diff --git a/archify/bin/finalize.mjs b/archify/bin/finalize.mjs
index 592c6974..effadf9d 100644
--- a/archify/bin/finalize.mjs
+++ b/archify/bin/finalize.mjs
@@ -466,6 +466,28 @@ function reservedFinalizePaths({ input, output, outDir, deliveryPaths }) {
return [path.resolve(input), path.resolve(output), ...Object.values(deliveryPaths(output)), browser.receipt];
}
+// Node moves that remove the measured crossings and detours, most specific
+// first. Only positions and sizes change; every relationship keeps its endpoints.
+function placementHints({ crossings = [], detours = [], crowdedSides = [] }) {
+ const name = (relation) => `${relation.from} → ${relation.to}`;
+ const other = (relation, shared) => (relation.from === shared ? relation.to : relation.from);
+ const hints = [];
+ for (const side of crowdedSides) {
+ hints.push(`${side.node} has ${side.relationships} relationships facing its ${side.side} side, which fits ${Math.max(1, Math.floor((side.sidePx - 32) / 14) + 1)} ports: make that side at least ${side.neededPx}px, or move some of those neighbours so they face another side of ${side.node}.`);
+ }
+ for (const crossing of crossings) {
+ const shared = crossing.sharedNode;
+ hints.push(shared
+ ? `${name(crossing.left)} and ${name(crossing.right)} cross next to ${shared}: move node ${other(crossing.left, shared)} or ${other(crossing.right, shared)} so the two reach ${shared} from different sides (for example one level with it, one directly above or below it).`
+ : `${name(crossing.left)} crosses ${name(crossing.right)}: move the node of whichever is a branch, return, or second entrance to the other side of the main path, so that relationship runs through an empty corridor.`);
+ }
+ for (const detour of detours) {
+ if (detour.directCorridorBlockers?.length) continue;
+ hints.push(`${name(detour.relationship)} needs ${detour.bends} bends: move node ${detour.relationship.from} or ${detour.relationship.to} so they share a row or column with matching centers, or sit diagonally with a clear corner.`);
+ }
+ return [...new Set(hints)].slice(0, 8);
+}
+
export function compactFinalizeReceipt(receipt) {
const gates = {};
for (const stage of FINALIZE_STAGES) gates[stage] = receipt.stages?.[stage]?.status || 'not-run';
@@ -538,6 +560,7 @@ export function compactFinalizeReceipt(receipt) {
.map((key) => [key, metrics[key]]));
if (receipt.ok && Object.keys(reviewSignals).length) {
const routeReview = receipt.stages?.check?.receipt?.composition?.routeReview;
+ const hints = routeReview ? placementHints(routeReview) : [];
compact.visualReviewRecommendation = {
action: 'inspect-route-readability',
signals: reviewSignals,
@@ -548,6 +571,7 @@ export function compactFinalizeReceipt(receipt) {
detours: routeReview.detours.slice(0, 8),
truncated: routeReview.crossings.length > 8 || routeReview.detours.length > 8,
},
+ ...(hints.length ? { hints } : {}),
repair: 'Trace these relationships at the desktop viewport. For Architecture, use references/architecture-layout-repair.md: reflow a blocked main path or tangled connected scene, and repair an isolated defect locally only when the surrounding composition is accepted. Preserve all semantic content and user-fixed geometry. Rerun finalize once after the edit.',
} : {}),
};
diff --git a/archify/references/authoring-defaults.md b/archify/references/authoring-defaults.md
index fd4e9da4..8c6dd418 100644
--- a/archify/references/authoring-defaults.md
+++ b/archify/references/authoring-defaults.md
@@ -12,7 +12,15 @@ Relationship labels carry meaning. Give them clear space and preserve action, pr
## Layout and routing
-Place Architecture nodes by their actual connections before assigning coordinates. Keep main-path neighbors adjacent, put each branch beside its owner and shared stores near their readers and writers, and reserve an outside corridor for real returns. Trace every relationship against that placement before writing positions; the router cannot rearrange boxes. Let a medium main path step through meaningful rows instead of making a shallow horizontal strip. Start the main actor and its first connected step together near the canvas origin; use content rows for vertical rhythm. Omit `meta.viewBox` for a fresh Architecture so the Reader measures intrinsic height. Keep supplied fixed geometry authoritative.
+Place Architecture nodes by their actual connections before assigning coordinates; the router cannot rearrange boxes, so placement decides whether lines stay straight. Classify each relationship first, then place:
+
+- **Main path**: the reader's main journey, neighbors adjacent in reading order. Let a medium path step through meaningful rows instead of making a shallow horizontal strip.
+- **Branch or store**: directly above or below the node that owns, reads, or writes it, centered on that node so the edge is one straight segment. Keep all stores and branches of one row on the same side of it.
+- **Return** (back to an earlier main-path node): put its source on the side of the main path with no branches or stores, so it runs through an empty corridor instead of crossing them.
+- **Second entrance** into a node that already has an incoming edge: place the new source so it reaches that node from another side, usually directly below or above it.
+- **Fan-out**: a side with k relationships needs at least `32 + 14 × (k − 1)`px (four need 74px). Spread a hub's counterparts over two or three sides, or enlarge the hub. Center a parent on its children and align a child with its only parent.
+
+Before writing positions, trace each non-main relationship: its straight or one-bend corridor must not pass another node or cross another relationship. If it does, move the endpoint that is off the main path. Start the main actor and its first connected step together near the canvas origin; use content rows for vertical rhythm. Omit `meta.viewBox` for a fresh Architecture so the Reader measures intrinsic height. Keep supplied fixed geometry authoritative.
Start with automatic routes and endpoint sides. Pin a side only for a necessary branch, return, or supplied geometry. Reserve `via`, `channelX`, `channelY`, and label coordinates for measured defects. Before writing positions, budget each labeled main-path edge at `6.5px × ASCII units + 21px` of clear gap, counting CJK as two units; use its own label length, not a row-wide fixed gap. Size Architecture sublabels for their preferred 9px text at `5.4px × text units + 8px`, with CJK counting twice; keep supporting copy concise without dropping required facts. Do not trade readability or meaning for fewer crossings. The [Geometry reference](authoring-contract.md#executable-geometry-rules) has measured spacing, port, canvas, and route rules for a diagnosed layout problem.
diff --git a/archify/renderers/architecture/routing.mjs b/archify/renderers/architecture/routing.mjs
index fbb85597..f2de2875 100644
--- a/archify/renderers/architecture/routing.mjs
+++ b/archify/renderers/architecture/routing.mjs
@@ -384,6 +384,14 @@ export function createRouter(components, connections = [], {
return { start, end };
}
+ // A reciprocal pair is repaired jointly after planning, so crossings that
+ // involve it are not final yet; keep the established first choice there.
+ const reciprocal = (conn) => connections.some((other) => other.from === conn.to && other.to === conn.from);
+ function siblingCrossings(conn, points, resolvedRoutes) {
+ if (reciprocal(conn)) return 0;
+ return crossingCount(conn, points, resolvedRoutes.filter((entry) => !reciprocal(entry.conn)));
+ }
+
function routeVia(conn, from, to, start, end, fromSide, toSide, resolvedRoutes = []) {
if (conn.via) return conn.via;
switch (conn.route || 'auto') {
@@ -486,7 +494,35 @@ export function createRouter(components, connections = [], {
if (routeClearsEndpointComponents(points, from, to)
&& routeClearsComponents(conn, points)
&& routeMeetsCompositionFloors(points)
- && !routeConflictsWithResolved(conn, points, resolvedRoutes)) return candidate;
+ && !routeConflictsWithResolved(conn, points, resolvedRoutes)
+ && (!distinctAutomaticPorts || (!routeOverlapsResolved(conn, points, resolvedRoutes)
+ && !siblingCrossings(conn, points, resolvedRoutes)))) return candidate;
+ }
+ // Siblings fanning out from one side all want the same midpoint
+ // channel. Step outward through the corridor to a free parallel
+ // channel before searching.
+ if (distinctAutomaticPorts) {
+ const channels = (from, to, mid) => {
+ const [low, high] = [Math.min(from, to) + 24, Math.max(from, to) - 24];
+ const values = [];
+ for (let offset = 16; mid - offset >= low || mid + offset <= high; offset += 16) {
+ values.push(...[mid + offset, mid - offset].filter((value) => value >= low && value <= high));
+ }
+ return values;
+ };
+ for (const candidate of [
+ ...channels(start[0], end[0], midX).map((x) => [[x, start[1]], [x, end[1]]]),
+ ...channels(start[1], end[1], midY).map((y) => [[start[0], y], [end[0], y]]),
+ ]) {
+ const points = [start, ...candidate, end];
+ if (routeHonorsEndpointSides(points, fromSide, toSide)
+ && routeClearsEndpointComponents(points, from, to)
+ && routeClearsComponents(conn, points)
+ && routeMeetsCompositionFloors(points)
+ && !routeConflictsWithResolved(conn, points, resolvedRoutes)
+ && !routeOverlapsResolved(conn, points, resolvedRoutes)
+ && !siblingCrossings(conn, points, resolvedRoutes)) return candidate;
+ }
}
// Two-bend doglegs are deliberately cheap, but a real architecture can
@@ -587,16 +623,61 @@ export function createRouter(components, connections = [], {
}
}
+ // A node's neighbours laid out as one row below (or above) it read as a
+ // fan-out: reach them all through the same vertical side. Center-based
+ // inference alone sends the outer ones sideways around their siblings.
+ const neighbourRects = new Map();
+ for (const conn of connections) {
+ const from = components.get(conn.from);
+ const to = components.get(conn.to);
+ if (!from || !to || from === to) continue;
+ for (const [node, other] of [[from, to], [to, from]]) {
+ neighbourRects.set(node.id, [...(neighbourRects.get(node.id) || []), other]);
+ }
+ }
+ function rowFanOutSides(from, to) {
+ if (!preferReadableRoutes) return null;
+ const verticalSides = (node, other) => {
+ const below = other.y >= node.y + node.height;
+ if (!below && other.y + other.height > node.y) return null;
+ if (['top', 'bottom'].includes(defaultFromSide(node, other))) return null;
+ const rowSibling = (neighbourRects.get(node.id) || []).some((sibling) => sibling !== other
+ && Math.abs(sibling.cy - other.cy) < 1
+ && defaultFromSide(node, sibling) === (below ? 'bottom' : 'top'));
+ // Only when a node of that row blocks a sideways route to one of the
+ // neighbours on this side; otherwise side exits stay clear and keep the
+ // vertical side free. Decide per side so a row never mixes both styles.
+ const blocked = (target) => {
+ const [gapStart, gapEnd] = target.cx < node.cx
+ ? [target.x + target.width, node.x] : [node.x + node.width, target.x];
+ return [...components.values()].some((rect) => rect !== node && rect !== target
+ && rect.y < target.y + target.height && rect.y + rect.height > target.y
+ && rect.x < gapEnd && rect.x + rect.width > gapStart);
+ };
+ const sameSide = (neighbourRects.get(node.id) || []).filter((sibling) => Math.abs(sibling.cy - other.cy) < 1
+ && defaultFromSide(node, sibling) === defaultFromSide(node, other));
+ return rowSibling && sameSide.some(blocked) ? (below ? 'bottom' : 'top') : null;
+ };
+ const opposite = { top: 'bottom', bottom: 'top' };
+ const fromSide = verticalSides(from, to);
+ if (fromSide) return { fromSide, toSide: opposite[fromSide] };
+ const toSide = verticalSides(to, from);
+ return toSide ? { fromSide: opposite[toSide], toSide } : null;
+ }
+
const pathCache = new Map();
const selectedSides = new Map();
const stroke = (relation) => relation.width || (relation.variant === 'emphasis' ? 1.8 : 1.5);
const markerSpacing = (left, right) => 3.5 * (stroke(left) + stroke(right));
const portSpacing = (left, right) => Math.max(14, markerSpacing(left, right) + 3.5);
- const automaticPorts = automaticPortSpread(connections, components,
+ const automaticPorts = automaticPortSpread(connections, components, {
+ sideFor: (relation, endpoint) => rowFanOutSides(components.get(relation.from), components.get(relation.to))
+ ?.[endpoint === 'source' ? 'fromSide' : 'toSide'],
// Preserve the established initial placement for ordinary markers; only
// widen groups whose arrowheads cannot fit the legacy 14px slots.
- distinctAutomaticPorts ? { spacingFor: (left, right) =>
- markerSpacing(left, right) > 14 ? portSpacing(left, right) : 14 } : {});
+ ...(distinctAutomaticPorts ? { spacingFor: (left, right) =>
+ markerSpacing(left, right) > 14 ? portSpacing(left, right) : 14 } : {}),
+ });
const incidentEndpoints = new Map();
for (const conn of connections) {
if (!components.has(conn.from) || !components.has(conn.to)) continue;
@@ -609,9 +690,10 @@ export function createRouter(components, connections = [], {
function inferredConnectionSides(conn) {
const from = components.get(conn.from);
const to = components.get(conn.to);
+ const fanOut = rowFanOutSides(from, to);
return {
- fromSide: chosenSide(conn.fromSide, defaultFromSide(from, to)),
- toSide: chosenSide(conn.toSide, defaultToSide(from, to)),
+ fromSide: chosenSide(conn.fromSide, fanOut?.fromSide || defaultFromSide(from, to)),
+ toSide: chosenSide(conn.toSide, fanOut?.toSide || defaultToSide(from, to)),
};
}
diff --git a/archify/scripts/check-render-output.mjs b/archify/scripts/check-render-output.mjs
index 3c29ee2b..e46fe287 100644
--- a/archify/scripts/check-render-output.mjs
+++ b/archify/scripts/check-render-output.mjs
@@ -155,6 +155,9 @@ if (svgMatches.length === 1) {
.map((arrow) => ({ relation: arrow, relationIndex: arrow.index, points: arrow.routePoints }));
const nodeRects = svgAttrs.transform ? [] : collectUntransformedNodeRects(beforeLegend);
const routeMetrics = routeBudgetMetrics({ routedRelations: routedRelationships });
+ // Architecture marks only one of its two Reader fits with its type.
+ const crowdedSides = svgAttrs['data-diagram-type'] === 'architecture' || svgAttrs['data-reader-primary-text'] === '14'
+ ? crowdedNodeSides(arrows, nodeRects) : [];
const routeRhythmIssues = collectRouteRhythmIssues({ routedRelations: routedRelationships });
const ambiguousCorridors = collectAmbiguousCorridors({
routedRelations: routedRelationships,
@@ -240,11 +243,16 @@ if (svgMatches.length === 1) {
// These are review evidence, not new pass/fail thresholds: a short, clear
// crossover can be preferable to a long crossing-free detour.
routeReview: {
- crossings: resolvedCrossovers.map((hit) => ({
- left: relationshipRecord(hit.left),
- right: relationshipRecord(hit.right),
- point: hit.point,
- })),
+ crossings: resolvedCrossovers.map((hit) => {
+ const shared = [hit.left.from, hit.left.to].find((id) => id && (id === hit.right.from || id === hit.right.to));
+ return {
+ left: relationshipRecord(hit.left),
+ right: relationshipRecord(hit.right),
+ point: hit.point,
+ ...(shared ? { sharedNode: shared } : {}),
+ };
+ }),
+ ...(crowdedSides.length ? { crowdedSides } : {}),
detours: routedRelationships.flatMap((entry) => {
const metrics = routeBudgetMetrics({ routedRelations: [entry] });
const blockers = directCorridorBlockers(entry.relation, nodeRects);
@@ -651,6 +659,34 @@ function directCorridorBlockers(relation, nodes) {
&& node.box[cross] < a[cross] && node.box[cross] + node.box[cross + 2] > a[cross]);
}
+// Automatic ports need a 16px corner gutter and 14px between neighbours, so a
+// side facing more counterparts than that fits pushes routes onto other sides.
+function crowdedNodeSides(arrows, nodes) {
+ const byId = new Map(nodes.map((node) => [node.id, node]));
+ const demand = new Map();
+ for (const arrow of arrows) {
+ const from = byId.get(arrow.from);
+ const to = byId.get(arrow.to);
+ if (!from || !to || from === to) continue;
+ for (const [node, other] of [[from, to], [to, from]]) {
+ const [x, y, w, h] = node.box;
+ const dx = other.box[0] + other.box[2] / 2 - (x + w / 2);
+ const dy = other.box[1] + other.box[3] / 2 - (y + h / 2);
+ const side = dx !== 0 && Math.abs(dx) >= Math.abs(dy) ? (dx < 0 ? 'left' : 'right') : (dy > 0 ? 'bottom' : 'top');
+ const key = `${node.id}\u0000${side}`;
+ const entry = demand.get(key) || { node, side, relationships: 0 };
+ entry.relationships += 1;
+ demand.set(key, entry);
+ }
+ }
+ return [...demand.values()].flatMap(({ node, side, relationships }) => {
+ const sidePx = side === 'left' || side === 'right' ? node.box[3] : node.box[2];
+ const neededPx = 32 + 14 * (relationships - 1);
+ return relationships > 1 && sidePx < neededPx
+ ? [{ node: node.id, label: node.label, side, relationships, sidePx, neededPx }] : [];
+ });
+}
+
function relationshipRecord(arrow) {
const stableIndex = Number(arrow.key);
return {
diff --git a/archify/test/architecture-leading-space.test.mjs b/archify/test/architecture-leading-space.test.mjs
index ae8f94f8..a46a2853 100644
--- a/archify/test/architecture-leading-space.test.mjs
+++ b/archify/test/architecture-leading-space.test.mjs
@@ -88,3 +88,26 @@ test('authored viewBox and transformed SVGs are not suggested for automatic revi
fs.writeFileSync(automatic.output, html);
assert.equal(automatic.read().composition.leadingSpace.reviewSuggested, false, 'other diagram modes do not qualify');
});
+
+test('automatic Architecture reports a node side facing more neighbours than it has ports', t => {
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-crowded-side-'));
+ t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+ const render = (hubHeight) => {
+ const source = path.join(dir, `hub-${hubHeight}.json`);
+ const output = path.join(dir, `hub-${hubHeight}.html`);
+ fs.writeFileSync(source, JSON.stringify({
+ schema_version: 1, diagram_type: 'architecture',
+ meta: { title: 'Crowded side', quality_profile: 'standard', output: path.basename(output) },
+ components: [
+ { id: 'hub', type: 'backend', label: 'Hub', pos: [40, 190], size: [140, hubHeight] },
+ ...[0, 1, 2, 3].map((index) => ({ id: `n${index}`, type: 'backend', label: `N${index}`, pos: [420, 40 + index * 110], size: [120, 60] })),
+ ],
+ connections: [0, 1, 2, 3].map((index) => ({ from: 'hub', to: `n${index}` })),
+ }));
+ const rendered = spawnSync(process.execPath, [cli, 'render', 'architecture', source, output], { encoding: 'utf8' });
+ assert.equal(rendered.status, 0, rendered.stdout + rendered.stderr);
+ return run([checker, output]).composition.routeReview.crowdedSides;
+ };
+ assert.deepEqual(render(64), [{ node: 'hub', label: 'Hub', side: 'right', relationships: 4, sidePx: 64, neededPx: 74 }]);
+ assert.equal(render(80), undefined);
+});
diff --git a/archify/test/architecture-readable-routing.test.mjs b/archify/test/architecture-readable-routing.test.mjs
index a2816a6e..20f5f28d 100644
--- a/archify/test/architecture-readable-routing.test.mjs
+++ b/archify/test/architecture-readable-routing.test.mjs
@@ -32,7 +32,7 @@ test('architecture improves complete-scene crossings and bends without extra gri
distinctAutomaticPorts: true, preferReadableRoutes,
}));
const routes = routers.map((router) => connections.map((conn) => router.pathFor(conn).points));
- assert.equal(crossings(routes[0]), 11, 'fixture exposes the first-legal-route regression');
+ assert.equal(crossings(routes[0]), 10, 'fixture exposes the first-legal-route regression');
assert.equal(crossings(routes[1]), 9);
const metrics = routes.map((points) => routeBudgetMetrics({ routedRelations: points.map((route) => ({ points: route })) }));
assert.ok(metrics[1].routesOverSuggestedBends < metrics[0].routesOverSuggestedBends);
@@ -57,3 +57,24 @@ test('readability sweep preserves explicit geometry and endpoint-side contracts'
assert.deepEqual(routers[1].pathFor(connections[0]), routers[0].pathFor(connections[0]));
assert.deepEqual(routers[1].connectionSides(connections[3]), { fromSide: 'bottom', toSide: 'top' });
});
+
+test('a fan-out sibling takes a free parallel channel instead of a detour', () => {
+ const box = (id, x, y, width) => [id, { id, x, y, width, height: 64, cx: x + width / 2, cy: y + 32 }];
+ const boxes = new Map([box('entry', 350, 80, 160), box('hub', 610, 80, 190), box('store', 950, 80, 180),
+ box('left', 300, 270, 170), box('middle', 530, 270, 170), box('right', 760, 270, 180), box('far', 1000, 270, 170)]);
+ const connections = ['store', 'left', 'middle', 'right', 'far'].map((to) => ({ id: `hub-${to}`, from: 'hub', to }));
+ connections.unshift({ id: 'entry-hub', from: 'entry', to: 'hub' });
+ const router = createRouter(boxes, connections, { distinctAutomaticPorts: true, preferReadableRoutes: true });
+ const routes = connections.map((conn) => router.pathFor(conn).points);
+ assert.ok(routes[2].length <= 4, `hub → left keeps at most two bends: ${JSON.stringify(routes[2])}`);
+ assert.equal(crossings(routes), 0);
+});
+
+test('a row neighbour with a clear sideways corridor keeps its side exit', () => {
+ const box = (id, x, y, width) => [id, { id, x, y, width, height: 64, cx: x + width / 2, cy: y + 32 }];
+ const boxes = new Map([box('hub', 780, 80, 180), box('below', 780, 300, 180), box('store', 440, 300, 180)]);
+ const connections = [{ id: 'main', from: 'hub', to: 'below' }, { id: 'write', from: 'hub', to: 'store' }];
+ const router = createRouter(boxes, connections, { distinctAutomaticPorts: true, preferReadableRoutes: true });
+ assert.deepEqual(router.connectionSides(connections[1]), { fromSide: 'left', toSide: 'right' });
+ assert.equal(router.pathFor(connections[0]).points.length, 2, 'the main edge stays straight');
+});
diff --git a/archify/test/finalize.test.mjs b/archify/test/finalize.test.mjs
index d07de020..0a679f6c 100644
--- a/archify/test/finalize.test.mjs
+++ b/archify/test/finalize.test.mjs
@@ -318,6 +318,32 @@ test('compact success bounds review context and preserves relationship identity'
assert.match(compact.visualReviewRecommendation.repair, /architecture-layout-repair\.md/);
});
+test('compact success turns route evidence into node-move hints that keep relationships', () => {
+ const routeReview = {
+ crossings: [
+ { left: { from: 'desktop', to: 'http' }, right: { from: 'tunnel', to: 'http' }, sharedNode: 'http' },
+ { left: { from: 'teamcli', to: 'http' }, right: { from: 'runtime', to: 'sqlite' } },
+ ],
+ crowdedSides: [{ node: 'app', side: 'right', relationships: 4, sidePx: 70, neededPx: 74 }],
+ detours: [
+ { relationship: { from: 'registry', to: 'shim' }, bends: 3 },
+ { relationship: { from: 'worker', to: 'api' }, bends: 4, directCorridorBlockers: [{ id: 'store' }] },
+ ],
+ };
+ const { hints } = compactFinalizeReceipt({ ok: true, stages: { check: { receipt: { composition: {
+ metrics: { resolvedCrossovers: 2, routesOverSuggestedBends: 2 }, routeReview,
+ } } } } }).visualReviewRecommendation;
+ assert.equal(hints.length, 4, 'a detour with named corridor blockers keeps its existing repair path');
+ assert.match(hints[0], /app has 4 relationships facing its right side, which fits 3 ports: make that side at least 74px/);
+ assert.match(hints[1], /move node desktop or tunnel so the two reach http from different sides/);
+ assert.match(hints[2], /teamcli → http crosses runtime → sqlite/);
+ assert.match(hints[3], /move node registry or shim/);
+ assert.ok(hints.every((hint) => !/endpoint/.test(hint)), 'hints move nodes, never re-attach relationships');
+ assert.equal('hints' in compactFinalizeReceipt({ ok: true, stages: { check: { receipt: { composition: {
+ metrics: { resolvedCrossovers: 1 }, routeReview: { crossings: [], detours: [] },
+ } } } } }).visualReviewRecommendation, false);
+});
+
test('compact failure receipts retain diverse actionable subjects without embedding full stage evidence', () => {
const diagnostics = Array.from({ length: 20 }, (_, index) => ({
code: 'composition/proper-crossing',
diff --git a/archify/test/render-output-checks.test.mjs b/archify/test/render-output-checks.test.mjs
index b40c3ddb..2c5bd01d 100644
--- a/archify/test/render-output-checks.test.mjs
+++ b/archify/test/render-output-checks.test.mjs
@@ -701,6 +701,8 @@ test('render output check: independent shared-endpoint crossings still recommend
assert.equal(affected.crossings[0].left.id, 'first');
assert.equal(affected.crossings[0].right.id, 'second');
assert.deepEqual(affected.crossings[0].point, [120, 80]);
+ assert.equal(affected.crossings[0].sharedNode, 'hub');
+ assert.match(summary.visualReviewRecommendation.hints[0], /move node a or b so the two reach hub from different sides/);
assert.deepEqual(affected.detours, []);
assert.equal(affected.truncated, false);
assert.equal(summary.visualReview, 'not-requested');