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: add bounded safe auto routing (#33)
tt-a1i316220d45747
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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.zipindex 0ce82e9d..eceb9109 100644Binary files a/archify.zip and b/archify.zip differdiff --git a/archify/SKILL.md b/archify/SKILL.mdindex 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.mjsindex 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.mjsindex 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', () => {