Skip to content

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

Fit architecture canvases to outer routes and diagnose clipped showcase paths

tt-a1i51fd4088b4f7
diff --git a/archify/references/authoring-contract.md b/archify/references/authoring-contract.md
index e2c5991a..9891ceb4 100644
--- a/archify/references/authoring-contract.md
+++ b/archify/references/authoring-contract.md
@@ -196,6 +196,12 @@ negative coordinates need an inward move; increasing viewBox width/height only
addresses right/bottom overflow. Boundaries may wrap members across rows. Keep
real membership intact and recheck connected routes after moving members.
+Automatic architecture canvases include route points as well as nodes, frames,
+and labels. An authored viewBox remains authoritative. In showcase,
+`layout/route-out-of-bounds` identifies clipped route points; negative coordinates
+need an inward route, while right/bottom overflow can also use a larger authored
+canvas. Recheck desktop readability after enlarging a canvas.
+
When several crossing/corridor diagnoses involve the same nodes, consider their
placement together before adding route controls. Apply one coherent repair and
validate it; independent label nudges cannot fix a shared layout bottleneck.
diff --git a/archify/renderers/architecture/render-architecture.mjs b/archify/renderers/architecture/render-architecture.mjs
index cea118b9..3b2f2fa4 100644
--- a/archify/renderers/architecture/render-architecture.mjs
+++ b/archify/renderers/architecture/render-architecture.mjs
@@ -195,7 +195,7 @@ function resolvedViewBoxWidth(candidateBoundaries) {
if (Array.isArray(arch.meta?.viewBox) && Number.isFinite(arch.meta.viewBox[0])) {
return arch.meta.viewBox[0];
}
- return autoViewBoxFor(candidateBoundaries, connectionLabels)[0];
+ return autoViewBoxFor(candidateBoundaries, connectionGeometry)[0];
}
function expandBoundaryForReadableTitle(boundary, minimumFontSize) {
@@ -302,6 +302,14 @@ const { pathFor, connectionSides, connectionEndpointSide } = createRouter(compon
// The auto canvas has to cover these rects; an authored viewBox is never
// resized to fit them — there the containment rule reports the clipping.
const connectionLabels = connectionLabelRects();
+// Unlabelled outer corridors are geometry too. Fitting only nodes and labels
+// can clip a valid explicit via route while every browser overflow check passes.
+const connectionGeometry = [
+ ...connectionLabels,
+ ...asArray(arch.connections)
+ .filter((conn) => components.has(conn.from) && components.has(conn.to))
+ .flatMap((conn) => pathFor(conn).points.map(([x, y]) => ({ x, y, width: 0, height: 0 }))),
+];
const rawBoundaries = asArray(arch.boundaries).map(boundaryRect).filter(Boolean);
function resolveBoundaryTitles() {
@@ -360,7 +368,7 @@ function componentContext(component) {
// Connection labels are diagram content, so an auto canvas that stopped at the
// component/boundary bbox would clip them; the label rects join the fit here
// and in the title convergence above, which sizes fonts for this same width.
-const viewBox = arch.meta?.viewBox || autoViewBoxFor(boundaries, connectionLabels);
+const viewBox = arch.meta?.viewBox || autoViewBoxFor(boundaries, connectionGeometry);
const legendY = () => viewBox[1] - 16;
// ---- Validation: mechanical correctness, never layout taste -----------------
@@ -560,6 +568,17 @@ function validateArchitecture() {
if (!components.has(conn.to)) problems.push(`Connection "${conn.label || conn.to}" references unknown target "${conn.to}".`);
if (components.has(conn.from) && components.has(conn.to)) {
const routed = pathFor(conn);
+ const outsidePoints = routed.points.filter(([x, y]) => x < 0 || y < 0 || x > viewBox[0] || y > viewBox[1]);
+ if (arch.meta?.quality_profile === 'showcase' && outsidePoints.length) {
+ const message = `Connection "${conn.id || `${conn.from}->${conn.to}`}" extends outside the viewBox — move the measured outside route points inward or enlarge an authored viewBox for right/bottom overflow.`;
+ diagnostics.push({
+ code: 'layout/route-out-of-bounds', severity: 'error', message,
+ subject: { diagramType: 'architecture', collection: 'connections', index: asArray(arch.connections).indexOf(conn), ...(conn.id ? { id: conn.id } : {}), from: conn.from, to: conn.to },
+ evidence: { viewBox: [...viewBox], outsidePoints, points: routed.points },
+ supportedFixes: ['move negative route coordinates inside the canvas; for right/bottom overflow, enlarge meta.viewBox or reroute inward; preserve endpoints, direction and labels, then revalidate'],
+ });
+ problems.push(message);
+ }
const [start, end] = [routed.points[0], routed.points[routed.points.length - 1]];
const distance = Math.hypot(end[0] - start[0], end[1] - start[1]);
if (distance < 24) problems.push(`Connection "${conn.label || `${conn.from}->${conn.to}`}" is too short (${Math.round(distance)}px; minimum 24px) — place its components farther apart.`);
diff --git a/archify/test/architecture-repair-evidence.test.mjs b/archify/test/architecture-repair-evidence.test.mjs
index adcd9818..3549562f 100644
--- a/archify/test/architecture-repair-evidence.test.mjs
+++ b/archify/test/architecture-repair-evidence.test.mjs
@@ -122,3 +122,50 @@ test('successful layout keeps existing fields; malformed input never masquerades
assert.equal(invalid.receipt.components, undefined);
assert.ok(invalid.receipt.diagnostics.some(d => d.code === 'input/json-parse'));
});
+
+function outerRoute(t) {
+ const { cwd, input, diagram } = setup(t, [[80, 70], [350, 70]]);
+ delete diagram.meta.viewBox;
+ diagram.meta.quality_profile = 'showcase';
+ delete diagram.boundaries;
+ diagram.connections = [{ id: 'outer', from: 'n0', to: 'n1', fromSide: 'bottom', toSide: 'bottom', via: [[140, 300], [410, 300]] }];
+ fs.writeFileSync(input, JSON.stringify(diagram));
+ return { cwd, input, diagram };
+}
+
+test('auto canvas includes an outer route even when no label reaches its corridor', t => {
+ const { cwd, input } = outerRoute(t);
+ const { result, receipt } = validate(input, cwd, ['--layout-json']);
+ assert.equal(result.status, 0, result.stdout);
+ assert.ok(receipt.viewBox[1] > 300, JSON.stringify(receipt));
+ assert.deepEqual(receipt.connections[0].points, [[140, 130], [140, 300], [410, 300], [410, 130]]);
+ assert.equal(validate(input, cwd).result.status, 0);
+});
+
+test('showcase reports clipped explicit routes without rewriting their geometry or authored canvas', t => {
+ const { cwd, input, diagram } = outerRoute(t);
+ diagram.meta.viewBox = [600, 220];
+ fs.writeFileSync(input, JSON.stringify(diagram));
+ const { result, receipt } = validate(input, cwd, ['--layout-json']);
+ assert.equal(result.status, 1);
+ const diagnosis = receipt.diagnostics.find(d => d.code === 'layout/route-out-of-bounds');
+ assert.ok(diagnosis);
+ assert.deepEqual(diagnosis.evidence.outsidePoints, [[140, 300], [410, 300]]);
+ assert.equal(diagnosis.subject.id, 'outer');
+ assert.deepEqual(receipt.viewBox, [600, 220]);
+ assert.deepEqual(JSON.parse(fs.readFileSync(input)), diagram);
+ // Standard retains its previous acceptance; stricter clipping diagnostics
+ // belong to showcase, just like label canvas containment.
+ diagram.meta.quality_profile = 'standard';
+ fs.writeFileSync(input, JSON.stringify(diagram));
+ assert.equal(validate(input, cwd).result.status, 0);
+});
+
+test('auto canvas does not hide a negative route by growing right or down', t => {
+ const { cwd, input, diagram } = outerRoute(t);
+ diagram.connections[0] = { id: 'outer', from: 'n0', to: 'n1', fromSide: 'top', toSide: 'top', via: [[140, -40], [410, -40]] };
+ fs.writeFileSync(input, JSON.stringify(diagram));
+ const { result, receipt } = validate(input, cwd, ['--layout-json']);
+ assert.equal(result.status, 1);
+ assert.ok(receipt.diagnostics.some(d => d.code === 'layout/route-out-of-bounds' && d.evidence.outsidePoints.every(([, y]) => y < 0)));
+});