Skip to content

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

feat: add bounded safe auto routing (#33)

tt-a1i316220d45747
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0141802e..384912f5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -58,6 +58,7 @@ All notable changes are documented here. Format loosely follows [Keep a Changelo
- **Generated Proof Lab.** `node scripts/build-gallery.mjs` now regenerates 11 live scenario proofs across all five diagram modes, their exact JSON sources, 77 artifact checks, composition receipts, byte sizes, SHA-256 digests, and three-step reader stories. A dedicated test fails when any recipe lacks a proof or any checked-in artifact drifts.
### Changed
+- Architecture `auto` routing now preserves its existing H-V-H dogleg when safe, but deterministically tries the complementary in-bounds V-H-V dogleg when the first candidate would cross an unrelated component. Explicit `via`, `straight`, `orthogonal-h`, and `orthogonal-v` choices remain authoritative; if both bounded candidates are blocked, Clean Flow still fails closed with the existing actionable error.
- The Skill delivery loop now treats a successful render as a candidate: after deterministic validation it requires a final browser/raster readback when available, allows at most two focused correction rounds, and reports explicit `validation`, `visual_review`, and `correction_rounds` evidence. Environments without an image reader must say the review was skipped instead of claiming visual approval.
- Embedded artifacts now pause ambient trace loops by default. The landing-page Live Proof Stage opts into one named chapter at a time, gallery cards stay static and cheap, direct proof actions open a self-playing Presentation Stage, and the README reel captures the same bounded chapter contract.
- Wide diagrams now use a contained 720px mobile reading surface instead of shrinking labels into an unreadable thumbnail. Guided views auto-center the authored path, internal swiping never widens the page, and zoom/focus controls remain pinned while the diagram moves underneath.
diff --git a/archify.zip b/archify.zip
index 0ce82e9d..eceb9109 100644
Binary files a/archify.zip and b/archify.zip differ
diff --git a/archify/SKILL.md b/archify/SKILL.md
index 4a641352..2ba1a918 100644
--- a/archify/SKILL.md
+++ b/archify/SKILL.md
@@ -297,7 +297,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`). 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; 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)
@@ -327,7 +327,7 @@ Typography inherits JetBrains Mono from the SVG root. Sizes: 11–12px component
- **Two-rect pattern everywhere**: opaque `c-mask` rect first, styled `c-<type>` rect on top — semi-transparent fills otherwise let arrows bleed through.
- **Arrows before components** in document order (SVG paints in order; arrows must sit behind boxes).
-- **Clean flow before delivery**: with or without a quality profile, a relationship may touch its own source/target boxes but must not pass through any unrelated semantic node. Fix `clean-flow/edge-through-node` with `fromSide`/`toSide`, a route/channel, explicit `via`, or node placement; do not hide the defect with paint order. This semantic correctness rule is universal, while older profile-less schema-v1 inputs retain advisory handling for stricter composition preferences.
+- **Clean flow before delivery**: with or without a quality profile, a relationship may touch its own source/target boxes but must not pass through any unrelated semantic node. If both bounded architecture auto candidates are blocked, fix `clean-flow/edge-through-node` with `fromSide`/`toSide`, a route/channel, explicit `via`, or node placement; do not hide the defect with paint order. This semantic correctness rule is universal, while older profile-less schema-v1 inputs retain advisory handling for stricter composition preferences.
- **Choose a composition profile deliberately with the user**: `standard` keeps dense engineering topologies renderable and records route-rhythm/proper-X findings as warnings; `showcase` fails unrelated proper X crossings, any segment below 8px, and interior turn segments below 16px. Both explicit profiles enforce structural border-run checks; universal Clean Flow applies before profile selection. Endpoint stubs from 8–15px remain valid because fixed lane gaps can require them. Use `meta.quality_profile` or CLI `--quality`, then repair with route/channel/via/side or placement controls. Do not silently add a profile to an existing v1 file.
- **Vertical stacking**: ≥40px gap between components; inline connectors (message buses, 20px tall) live inside the gap, never overlapping boxes.
- **Boundary padding**: boundary `y` = inner `y` − 30, boundary `height` = inner `height` + 50, label baseline 18px below the boundary top.
diff --git a/archify/renderers/architecture/render-architecture.mjs b/archify/renderers/architecture/render-architecture.mjs
index 136fbdac..c839a179 100644
--- a/archify/renderers/architecture/render-architecture.mjs
+++ b/archify/renderers/architecture/render-architecture.mjs
@@ -8,6 +8,7 @@ import {
asArray,
isFinitePoint,
rectsOverlap,
+ segmentIntersectsRect,
cleanFlowProblems,
cleanCrossingProblems,
cleanBorderRunProblems,
@@ -292,6 +293,19 @@ function buildLayoutReport() {
}
// ---- Connection routing ------------------------------------------------------
+function routeClearsComponents(conn, points, clearance = 2) {
+ const endpointIds = new Set([conn.from, conn.to]);
+ for (const component of components.values()) {
+ if (endpointIds.has(component.id)) continue;
+ for (let index = 0; index < points.length - 1; index += 1) {
+ if (segmentIntersectsRect({ start: points[index], end: points[index + 1] }, component, clearance)) {
+ return false;
+ }
+ }
+ }
+ return true;
+}
+
function routeVia(conn, from, to, start, end) {
if (conn.via) return conn.via;
switch (conn.route || 'auto') {
@@ -310,7 +324,17 @@ function routeVia(conn, from, to, start, end) {
// Direct line unless the anchors are clearly orthogonal-friendly.
if (Math.abs(start[0] - end[0]) < 4 || Math.abs(start[1] - end[1]) < 4) return [];
const midX = (start[0] + end[0]) / 2;
- return [[midX, start[1]], [midX, end[1]]];
+ const horizontalFirst = [[midX, start[1]], [midX, end[1]]];
+ if (routeClearsComponents(conn, [start, ...horizontalFirst, end])) return horizontalFirst;
+
+ // The only fallback is the complementary in-bounds dogleg. Both
+ // candidates stay between the authored anchors, preserve two bends, and
+ // remain deterministic. If neither is safe, keep the original route so
+ // the universal Clean Flow gate returns the actionable hard failure.
+ const midY = (start[1] + end[1]) / 2;
+ const verticalFirst = [[start[0], midY], [end[0], midY]];
+ if (routeClearsComponents(conn, [start, ...verticalFirst, end])) return verticalFirst;
+ return horizontalFirst;
}
}
}
diff --git a/archify/test/layout-rules.test.mjs b/archify/test/layout-rules.test.mjs
index d6430dcc..f1e69136 100644
--- a/archify/test/layout-rules.test.mjs
+++ b/archify/test/layout-rules.test.mjs
@@ -223,13 +223,32 @@ function autoRoutePassThroughDocument(connection) {
};
}
-test('architecture: default delivery rejects an auto-routed connection through an unrelated component', () => {
+test('architecture: default auto route selects a safe orthogonal candidate around an unrelated component', () => {
const d = autoRoutePassThroughDocument({ from: 'api', to: 'queue', variant: 'dashed' });
+ const { code, stderr, outPath } = render('architecture', d);
+ assert.equal(code, 0, stderr);
+ const html = fs.readFileSync(outPath, 'utf8');
+ assert.match(html, /data-composition-points="560,318;560,239;880,239;880,160"/);
+});
+
+test('architecture: explicit orthogonal route remains authoritative when it crosses a component', () => {
+ const d = autoRoutePassThroughDocument({
+ from: 'api',
+ to: 'queue',
+ variant: 'dashed',
+ route: 'orthogonal-h',
+ });
+ const { code, stderr } = render('architecture', d);
+ assert.notEqual(code, 0, `expected non-zero exit; stderr:\n${stderr}`);
+ assert.match(stderr, /connections\[0\] "api" -> "queue" crosses component "cache"/);
+});
+
+test('architecture: auto route still fails closed when both bounded doglegs are blocked', () => {
+ const d = autoRoutePassThroughDocument({ from: 'api', to: 'queue', variant: 'dashed' });
+ d.components.push({ id: 'guard', type: 'security', label: 'Guard', pos: [790, 215], size: [60, 50] });
const { code, stderr } = render('architecture', d);
assert.notEqual(code, 0, `expected non-zero exit; stderr:\n${stderr}`);
- assert.match(stderr, /\[clean-flow\/edge-through-node\] architecture connections\[0\] "api" -> "queue"/);
- assert.match(stderr, /crosses component "cache"/);
- assert.match(stderr, /fromSide\/toSide/);
+ assert.match(stderr, /connections\[0\] "api" -> "queue" crosses component "cache"/);
});
test('architecture: explicit waypoints around an obstacle remain valid by default', () => {