Skip to content

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

Fit compiler-measured architectures to desktop height

tt-a1i1b7aa692f54f
diff --git a/archify/examples/web-app-rendered.html b/archify/examples/web-app-rendered.html
index 4d901dfb..9ff7b527 100644
--- a/archify/examples/web-app-rendered.html
+++ b/archify/examples/web-app-rendered.html
@@ -5167,7 +5167,7 @@ OTHER DEALINGS IN THE FONT SOFTWARE.
<!-- Main Diagram -->
<div class="diagram-container" data-detail-level="read"
data-preset-badge-editorial-plate="ARCHIFY / PLATE 04">
- <svg viewBox="0 0 1080 588" role="img" lang="en" aria-labelledby="archify-diagram-title archify-diagram-description" data-preset="classic" data-quality-profile="showcase">
+ <svg viewBox="0 0 1080 588" role="img" lang="en" aria-labelledby="archify-diagram-title archify-diagram-description" data-preset="classic" data-quality-profile="showcase" data-reader-fit="intrinsic-height">
<title id="archify-diagram-title">Sample Web App</title>
<desc id="archify-diagram-description">An architecture diagram generated by Archify.</desc>
<!-- Definitions -->
diff --git a/archify/renderers/architecture/render-architecture.mjs b/archify/renderers/architecture/render-architecture.mjs
index 0d5780c4..f1b34912 100644
--- a/archify/renderers/architecture/render-architecture.mjs
+++ b/archify/renderers/architecture/render-architecture.mjs
@@ -821,7 +821,13 @@ function renderLegend() {
}
function renderSvg() {
- return ` <svg viewBox="0 0 ${viewBox[0]} ${viewBox[1]}" ${svgRootAttrs(arch.meta)}>
+ // An automatic architecture canvas is compiler-measured geometry. Let the
+ // Reader spend the real desktop height budget on it, including when an
+ // outer route makes the canvas taller than the ordinary wide-diagram
+ // threshold. Authored viewBoxes remain authoritative and keep the
+ // established Viewer contract.
+ const readerFit = arch.meta?.viewBox ? '' : ' data-reader-fit="intrinsic-height"';
+ return ` <svg viewBox="0 0 ${viewBox[0]} ${viewBox[1]}" ${svgRootAttrs(arch.meta)}${readerFit}>
${svgAccessibleText(arch.meta, 'architecture')}
${renderDefinitions()}
diff --git a/archify/test/desktop-reader-browser.test.mjs b/archify/test/desktop-reader-browser.test.mjs
index 89ea2386..16bb8b13 100644
--- a/archify/test/desktop-reader-browser.test.mjs
+++ b/archify/test/desktop-reader-browser.test.mjs
@@ -122,6 +122,55 @@ test('production showcase is readable in the real 1440 by 900 adaptive reader',
}
});
+test('route-expanded intrinsic architecture fits every required desktop viewport', {
+ skip: chromePath ? false : 'Set ARCHIFY_CHROME to run the real browser regression.',
+}, async () => {
+ const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-route-expanded-reader-'));
+ const input = path.join(
+ skillRoot,
+ 'test/fixtures/architecture-viewport/route-expanded-worldscope.architecture.json',
+ );
+ const artifact = path.join(tmp, 'route-expanded-worldscope.html');
+ try {
+ execFileSync(process.execPath, [
+ path.join(skillRoot, 'bin', 'archify.mjs'),
+ 'deliver',
+ 'architecture',
+ input,
+ artifact,
+ '--quality',
+ 'showcase',
+ '--json',
+ ], { cwd: skillRoot, encoding: 'utf8' });
+
+ const html = fs.readFileSync(artifact, 'utf8');
+ const svgRoot = html.match(/<svg\b[^>]*>/)?.[0];
+ assert.ok(svgRoot, 'expected an SVG root');
+ assert.match(svgRoot, /viewBox="0 0 980 678"/);
+ assert.match(svgRoot, /data-reader-fit="intrinsic-height"/);
+
+ const result = await runVisualCheck({ artifactPath: artifact, chromePath });
+ assert.equal(result.exitCode, 0, JSON.stringify(result.receipt, null, 2));
+ assert.equal(result.receipt.containment.status, 'pass');
+ assert.equal(result.receipt.readability.status, 'pass');
+ assert.equal(result.receipt.viewerChrome.status, 'pass');
+ for (const viewport of result.receipt.containment.viewports) {
+ assert.equal(viewport.overflowX, false, JSON.stringify(viewport, null, 2));
+ assert.equal(viewport.overflowY, false, JSON.stringify(viewport, null, 2));
+ assert.equal(viewport.scrollHeight, viewport.height, JSON.stringify(viewport, null, 2));
+ assert.ok(viewport.minimumProjectedNodeTextPx >= MIN_PROJECTED_NODE_TEXT_PX);
+ }
+ const desktop = result.receipt.containment.viewports.find(({ width, height }) => (
+ width === DESKTOP_READABILITY_VIEWPORT.width
+ && height === DESKTOP_READABILITY_VIEWPORT.height
+ ));
+ assert.ok(desktop);
+ assert.ok(desktop.diagramWidth < desktop.viewBoxWidth, JSON.stringify(desktop, null, 2));
+ } finally {
+ fs.rmSync(tmp, { recursive: true, force: true });
+ }
+});
+
test('offline intrinsic workflows fit while authored overflow still identifies lane frames', {
skip: chromePath ? false : 'Set ARCHIFY_CHROME to run the real browser regression.',
}, async () => {
diff --git a/archify/test/fixtures/architecture-viewport/route-expanded-worldscope.architecture.json b/archify/test/fixtures/architecture-viewport/route-expanded-worldscope.architecture.json
new file mode 100644
index 00000000..c20dbe34
--- /dev/null
+++ b/archify/test/fixtures/architecture-viewport/route-expanded-worldscope.architecture.json
@@ -0,0 +1,121 @@
+{
+ "schema_version": 1,
+ "diagram_type": "architecture",
+ "meta": {
+ "title": "WorldScope 系统架构",
+ "locale": "zh-CN",
+ "quality_profile": "showcase"
+ },
+ "components": [
+ {
+ "id": "browser",
+ "type": "frontend",
+ "label": "React 工作台",
+ "sublabel": "浏览器端交互界面",
+ "pos": [60, 110],
+ "size": [150, 64]
+ },
+ {
+ "id": "api",
+ "type": "backend",
+ "label": "读取模型 API",
+ "sublabel": "FastAPI",
+ "pos": [290, 110],
+ "size": [150, 64]
+ },
+ {
+ "id": "agent",
+ "type": "backend",
+ "label": "地图 Agent",
+ "sublabel": "Agent 编排",
+ "pos": [530, 110],
+ "size": [150, 64]
+ },
+ {
+ "id": "llm",
+ "type": "external",
+ "label": "模型端点",
+ "sublabel": "外部 LLM 服务",
+ "pos": [790, 110],
+ "size": [150, 64]
+ },
+ {
+ "id": "sources",
+ "type": "external",
+ "label": "公开数据源",
+ "sublabel": "外部公开数据",
+ "pos": [60, 300],
+ "size": [150, 64]
+ },
+ {
+ "id": "worker",
+ "type": "backend",
+ "label": "采集 Worker",
+ "sublabel": "定时采集任务",
+ "pos": [410, 300],
+ "size": [150, 64]
+ },
+ {
+ "id": "cache",
+ "type": "database",
+ "label": "Redis",
+ "sublabel": "缓存 / last-good",
+ "pos": [290, 480],
+ "size": [150, 64]
+ },
+ {
+ "id": "context",
+ "type": "database",
+ "label": "World Context",
+ "sublabel": "PostgreSQL + PostGIS",
+ "pos": [560, 480],
+ "size": [170, 64]
+ }
+ ],
+ "connections": [
+ { "id": "browser-to-api", "from": "browser", "to": "api", "label": "REST / SSE" },
+ { "id": "api-to-agent", "from": "api", "to": "agent", "label": "受信附件身份" },
+ { "id": "agent-to-llm", "from": "agent", "to": "llm", "label": "流式回答" },
+ { "id": "api-to-context", "from": "api", "to": "context", "label": "事实检索" },
+ { "id": "agent-to-context", "from": "agent", "to": "context", "label": "证据检索" },
+ { "id": "api-to-cache", "from": "api", "to": "cache", "label": "读取缓存" },
+ {
+ "id": "sources-to-worker",
+ "from": "sources",
+ "to": "worker",
+ "label": "定时采集",
+ "fromSide": "bottom",
+ "toSide": "bottom",
+ "via": [[135, 610], [485, 610]]
+ },
+ { "id": "worker-to-context", "from": "worker", "to": "context", "label": "写入证据" },
+ { "id": "worker-to-cache", "from": "worker", "to": "cache", "label": "刷新 last-good" }
+ ],
+ "boundaries": [
+ {
+ "kind": "region",
+ "label": "后端服务",
+ "wraps": ["api", "agent", "worker"]
+ }
+ ],
+ "cards": [
+ {
+ "dot": "cyan",
+ "title": "读取路径",
+ "items": [
+ "React 工作台经 REST / SSE 访问 FastAPI",
+ "API 直查 World Context 事实库并读穿 Redis 缓存",
+ "地图 Agent 携受信附件身份向模型端点流式提问"
+ ]
+ },
+ {
+ "dot": "emerald",
+ "title": "采集路径",
+ "items": [
+ "Worker 定时从公开数据源采集证据",
+ "证据写入 PostgreSQL + PostGIS 持久事实库",
+ "同时刷新 Redis 的 last-good 快照"
+ ]
+ }
+ ]
+}
diff --git a/archify/test/layout-rules.test.mjs b/archify/test/layout-rules.test.mjs
index 1d5a721c..3e5c813e 100644
--- a/archify/test/layout-rules.test.mjs
+++ b/archify/test/layout-rules.test.mjs
@@ -1301,6 +1301,24 @@ test('architecture: an auto viewBox grows to contain a wide connection label', (
assert.match(pinned.stderr, /\[composition\/label-canvas-containment\]/);
});
+test('architecture: measured auto canvases opt into height-aware reader fitting', () => {
+ const automatic = load('architecture');
+ delete automatic.meta.viewBox;
+ const rendered = render('architecture', automatic);
+ assert.equal(rendered.code, 0, rendered.stderr);
+ const automaticSvg = fs.readFileSync(rendered.outPath, 'utf8').match(/<svg\b[^>]*>/)?.[0];
+ assert.ok(automaticSvg, 'expected an SVG root for the automatic canvas');
+ assert.match(automaticSvg, /data-reader-fit="intrinsic-height"/);
+
+ const authored = structuredClone(automatic);
+ authored.meta.viewBox = [1080, 620];
+ const pinned = render('architecture', authored);
+ assert.equal(pinned.code, 0, pinned.stderr);
+ const authoredSvg = fs.readFileSync(pinned.outPath, 'utf8').match(/<svg\b[^>]*>/)?.[0];
+ assert.ok(authoredSvg, 'expected an SVG root for the authored canvas');
+ assert.doesNotMatch(authoredSvg, /data-reader-fit=/);
+});
+
// Boundary-title fonts are resolved against the same width the canvas actually
// renders into. When a connection label alone widens the auto canvas past the
// desktop reader width, the title font must rise with it — otherwise validate
diff --git a/docs/gallery/artifacts/production-deployment.architecture.html b/docs/gallery/artifacts/production-deployment.architecture.html
index b62878ca..7c05b4ca 100644
--- a/docs/gallery/artifacts/production-deployment.architecture.html
+++ b/docs/gallery/artifacts/production-deployment.architecture.html
@@ -5167,7 +5167,7 @@ OTHER DEALINGS IN THE FONT SOFTWARE.
<!-- Main Diagram -->
<div class="diagram-container" data-detail-level="read"
data-preset-badge-editorial-plate="ARCHIFY / PLATE 04">
- <svg viewBox="0 0 1376 728" role="img" lang="en" aria-labelledby="archify-diagram-title archify-diagram-description" data-animation="trace" data-preset="blueprint" data-engineering-profile="deployment-ownership" data-quality-profile="showcase">
+ <svg viewBox="0 0 1376 728" role="img" lang="en" aria-labelledby="archify-diagram-title archify-diagram-description" data-animation="trace" data-preset="blueprint" data-engineering-profile="deployment-ownership" data-quality-profile="showcase" data-reader-fit="intrinsic-height">
<title id="archify-diagram-title">Production Deployment Ownership</title>
<desc id="archify-diagram-description">An architecture diagram generated by Archify.</desc>
<!-- Definitions -->
diff --git a/docs/gallery/artifacts/web-app.architecture.html b/docs/gallery/artifacts/web-app.architecture.html
index 4d901dfb..9ff7b527 100644
--- a/docs/gallery/artifacts/web-app.architecture.html
+++ b/docs/gallery/artifacts/web-app.architecture.html
@@ -5167,7 +5167,7 @@ OTHER DEALINGS IN THE FONT SOFTWARE.
<!-- Main Diagram -->
<div class="diagram-container" data-detail-level="read"
data-preset-badge-editorial-plate="ARCHIFY / PLATE 04">
- <svg viewBox="0 0 1080 588" role="img" lang="en" aria-labelledby="archify-diagram-title archify-diagram-description" data-preset="classic" data-quality-profile="showcase">
+ <svg viewBox="0 0 1080 588" role="img" lang="en" aria-labelledby="archify-diagram-title archify-diagram-description" data-preset="classic" data-quality-profile="showcase" data-reader-fit="intrinsic-height">
<title id="archify-diagram-title">Sample Web App</title>
<desc id="archify-diagram-description">An architecture diagram generated by Archify.</desc>
<!-- Definitions -->
diff --git a/examples/checkout-platform-delta.html b/examples/checkout-platform-delta.html
index 59358250..d1a58f89 100644
--- a/examples/checkout-platform-delta.html
+++ b/examples/checkout-platform-delta.html
@@ -10031,7 +10031,7 @@ OTHER DEALINGS IN THE FONT SOFTWARE.
&lt;!-- Main Diagram --&gt;
&lt;div class=&quot;diagram-container&quot; data-detail-level=&quot;read&quot;
data-preset-badge-editorial-plate=&quot;ARCHIFY / PLATE 04&quot;&gt;
- &lt;svg viewBox=&quot;0 0 1020 548&quot; role=&quot;img&quot; lang=&quot;en&quot; aria-labelledby=&quot;archify-diagram-title archify-diagram-description&quot; data-preset=&quot;signal-flow&quot; data-quality-profile=&quot;showcase&quot;&gt;
+ &lt;svg viewBox=&quot;0 0 1020 548&quot; role=&quot;img&quot; lang=&quot;en&quot; aria-labelledby=&quot;archify-diagram-title archify-diagram-description&quot; data-preset=&quot;signal-flow&quot; data-quality-profile=&quot;showcase&quot; data-reader-fit=&quot;intrinsic-height&quot;&gt;
&lt;title id=&quot;archify-diagram-title&quot;&gt;Checkout Platform — Baseline&lt;/title&gt;
&lt;desc id=&quot;archify-diagram-description&quot;&gt;An architecture diagram generated by Archify.&lt;/desc&gt;
&lt;!-- Definitions --&gt;
@@ -20038,7 +20038,7 @@ OTHER DEALINGS IN THE FONT SOFTWARE.
&lt;/script&gt;
&lt;/body&gt;
&lt;/html&gt;
-"></iframe></section><section class="canvas" data-view="delta"><svg viewBox="0 0 1044 592" role="img" lang="en" aria-labelledby="delta-head-archify-diagram-title delta-head-archify-diagram-description" data-preset="signal-flow" data-quality-profile="showcase">
+"></iframe></section><section class="canvas" data-view="delta"><svg viewBox="0 0 1044 592" role="img" lang="en" aria-labelledby="delta-head-archify-diagram-title delta-head-archify-diagram-description" data-preset="signal-flow" data-quality-profile="showcase" data-reader-fit="intrinsic-height">
<title id="delta-head-archify-diagram-title">Checkout Platform — Fraud Gate</title>
<desc id="delta-head-archify-diagram-description">An architecture diagram generated by Archify.</desc>
<!-- Definitions -->
@@ -25503,7 +25503,7 @@ OTHER DEALINGS IN THE FONT SOFTWARE.
&lt;!-- Main Diagram --&gt;
&lt;div class=&quot;diagram-container&quot; data-detail-level=&quot;read&quot;
data-preset-badge-editorial-plate=&quot;ARCHIFY / PLATE 04&quot;&gt;
- &lt;svg viewBox=&quot;0 0 1020 568&quot; role=&quot;img&quot; lang=&quot;en&quot; aria-labelledby=&quot;archify-diagram-title archify-diagram-description&quot; data-preset=&quot;signal-flow&quot; data-quality-profile=&quot;showcase&quot;&gt;
+ &lt;svg viewBox=&quot;0 0 1020 568&quot; role=&quot;img&quot; lang=&quot;en&quot; aria-labelledby=&quot;archify-diagram-title archify-diagram-description&quot; data-preset=&quot;signal-flow&quot; data-quality-profile=&quot;showcase&quot; data-reader-fit=&quot;intrinsic-height&quot;&gt;
&lt;title id=&quot;archify-diagram-title&quot;&gt;Checkout Platform — Fraud Gate&lt;/title&gt;
&lt;desc id=&quot;archify-diagram-description&quot;&gt;An architecture diagram generated by Archify.&lt;/desc&gt;
&lt;!-- Definitions --&gt;
diff --git a/examples/web-app-rendered.html b/examples/web-app-rendered.html
index 4d901dfb..9ff7b527 100644
--- a/examples/web-app-rendered.html
+++ b/examples/web-app-rendered.html
@@ -5167,7 +5167,7 @@ OTHER DEALINGS IN THE FONT SOFTWARE.
<!-- Main Diagram -->
<div class="diagram-container" data-detail-level="read"
data-preset-badge-editorial-plate="ARCHIFY / PLATE 04">
- <svg viewBox="0 0 1080 588" role="img" lang="en" aria-labelledby="archify-diagram-title archify-diagram-description" data-preset="classic" data-quality-profile="showcase">
+ <svg viewBox="0 0 1080 588" role="img" lang="en" aria-labelledby="archify-diagram-title archify-diagram-description" data-preset="classic" data-quality-profile="showcase" data-reader-fit="intrinsic-height">
<title id="archify-diagram-title">Sample Web App</title>
<desc id="archify-diagram-description">An architecture diagram generated by Archify.</desc>
<!-- Definitions -->