Skip to content

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

fix(viewer): preserve architecture title reading size before page fitting

tt-a1i4bbc86cc7e4a
diff --git a/archify/assets/template.html b/archify/assets/template.html
index 77c9df6d..d3e2852c 100644
--- a/archify/assets/template.html
+++ b/archify/assets/template.html
@@ -11282,6 +11282,7 @@ OTHER DEALINGS IN THE FONT SOFTWARE.
var requestedMinimumText = Number.isFinite(declaredMinimumText)
? Math.max(MIN_PROJECTED_NODE_TEXT_PX, declaredMinimumText)
: MIN_PROJECTED_NODE_TEXT_PX;
+ var declaredPrimaryText = svg ? parseFloat(svg.getAttribute('data-reader-primary-text') || '') : null;
var SAFE_BOTTOM_GAP = 12;
if (diagram && ratio >= WIDE_RATIO) {
@@ -11320,6 +11321,20 @@ OTHER DEALINGS IN THE FONT SOFTWARE.
? Math.min(1, requestedMinimumText / sourceMinimum)
: 1;
}
+ function primaryReadingWidth() {
+ if (!measuredHeightFit || !Number.isFinite(declaredPrimaryText) || declaredPrimaryText <= 0) return 0;
+ var sourcePrimary = null;
+ Array.from(svg.querySelectorAll('text[data-node-label]')).forEach(function (text) {
+ var size = parseFloat(text.getAttribute('font-size') || '');
+ if (Number.isFinite(size) && size > 0) sourcePrimary = sourcePrimary == null ? size : Math.max(sourcePrimary, size);
+ });
+ // Primary labels should remain comfortable to read when cards or
+ // auxiliary rows make a one-screen fit too small. Ordinary page
+ // scroll preserves that reading size; viewport width still caps it.
+ // A long title may already use a smaller fitted font. Preserve that
+ // hierarchy rather than enlarging every other node to compensate.
+ return sourcePrimary == null ? 0 : viewBox.width * declaredPrimaryText / sourcePrimary;
+ }
function eligible() {
return Boolean(
shell && diagram && svg && (ratio >= WIDE_RATIO || measuredHeightFit) &&
@@ -11401,6 +11416,8 @@ OTHER DEALINGS IN THE FONT SOFTWARE.
} else {
minWidth = Math.min(readableMinimumWidth, viewportCap);
}
+ var primaryWidth = primaryReadingWidth();
+ if (primaryWidth > 0) minWidth = Math.max(minWidth, Math.min(maxWidth, primaryWidth + chrome.diagramX));
var fixedHeight = chrome.bodyY + chrome.diagramY + SAFE_BOTTOM_GAP +
outerHeight(header) + outerHeight(guided) + outerHeight(cards);
var availableSvgHeight = Math.max(1, window.innerHeight - fixedHeight);
diff --git a/archify/renderers/architecture/render-architecture.mjs b/archify/renderers/architecture/render-architecture.mjs
index 538b9477..38bfb20a 100644
--- a/archify/renderers/architecture/render-architecture.mjs
+++ b/archify/renderers/architecture/render-architecture.mjs
@@ -925,7 +925,8 @@ function renderSvg() {
// keep its common-desktop text at a comfortable reading size instead of
// shrinking a semantically rich graph to the universal emergency floor.
const readerMinimumText = arch.meta?.viewBox ? '' : ' data-reader-min-text="7.5"';
- return ` <svg viewBox="0 0 ${viewBox[0]} ${viewBox[1]}" ${svgRootAttrs(arch.meta)}${readerFit}${readerMinimumText}>
+ const readerPrimaryText = arch.meta?.viewBox ? '' : ' data-reader-primary-text="14"';
+ return ` <svg viewBox="0 0 ${viewBox[0]} ${viewBox[1]}" ${svgRootAttrs(arch.meta)}${readerFit}${readerMinimumText}${readerPrimaryText}>
${svgAccessibleText(arch.meta, 'architecture')}
${renderDefinitions()}
diff --git a/archify/test/architecture-reading-size-browser.test.mjs b/archify/test/architecture-reading-size-browser.test.mjs
new file mode 100644
index 00000000..20d38c75
--- /dev/null
+++ b/archify/test/architecture-reading-size-browser.test.mjs
@@ -0,0 +1,105 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { ChromeVisualBrowser, findChrome } from '../bin/visual-check.mjs';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+test('automatic architectures preserve primary reading size when fitting the full page would shrink text', async (t) => {
+ if (!Object.hasOwn(process.env, 'ARCHIFY_CHROME')) return t.skip('Set ARCHIFY_CHROME for real browser checks');
+ const chrome = findChrome();
+ assert.ok(chrome);
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-primary-reading-size-'));
+ const spec = JSON.parse(fs.readFileSync(path.join(root, 'examples/web-app.architecture.json'), 'utf8'));
+ spec.meta.title = 'Service map';
+ delete spec.meta.subtitle;
+ const input = path.join(dir, 'input.json');
+ const output = path.join(dir, 'output.html');
+ fs.writeFileSync(input, JSON.stringify(spec));
+ execFileSync(process.execPath, [path.join(root, 'bin/archify.mjs'), 'render', 'architecture', input, output]);
+ const browser = new ChromeVisualBrowser(chrome);
+ try {
+ const session = await browser.sessionPromise;
+ const send = (method, params = {}) => browser.cdp.send(method, params, session);
+ const evaluate = async (expression) => {
+ const result = await send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true });
+ assert.equal(result.exceptionDetails, undefined);
+ return result.result?.value;
+ };
+ let geometry;
+ for (const [width, height] of [[1440, 900], [1600, 900], [2048, 1320]]) {
+ await send('Emulation.setDeviceMetricsOverride', { width, height, deviceScaleFactor: 1, mobile: false });
+ const loaded = browser.cdp.waitFor('Page.loadEventFired', session);
+ await send('Page.navigate', { url: pathToFileURL(output).href });
+ await loaded;
+ for (const theme of ['light', 'dark']) {
+ const observed = await evaluate(`(async () => {
+ await document.fonts.ready;
+ if (document.documentElement.dataset.theme !== '${theme}') document.getElementById('btn-theme').click();
+ await Archify.layoutStability.whenStable();
+ const toolbar = document.querySelector('.toolbar').getBoundingClientRect();
+ const guide = document.querySelector('.guided-views').getBoundingClientRect();
+ const svg = document.querySelector('.diagram-container > svg');
+ return { rail: document.documentElement.dataset.navStageRail,
+ toolbarBottom: toolbar.bottom, guideTop: guide.top, guideWidth: guide.width,
+ primaryFont: Math.min(...Array.from(svg.querySelectorAll('text[data-node-label]')).map(text => parseFloat(text.getAttribute('font-size')) * svg.getBoundingClientRect().width / svg.viewBox.baseVal.width)),
+ scrollWidth: document.documentElement.scrollWidth,
+ geometry: [svg.getAttribute('viewBox'), ...Array.from(svg.querySelectorAll('[data-node-id]')).map(node =>
+ [node.getAttribute('transform'), ...Array.from(node.querySelectorAll('text')).map(text => text.getAttribute('font-size'))])] };
+ })()`);
+ const label = `${width}x${height}/${theme}`;
+ assert.equal(observed.rail, 'true', label + ': fixture must exercise the compact rail');
+ assert.ok(observed.guideWidth > 0, label + ': guide must be visible');
+ assert.ok(observed.guideTop >= observed.toolbarBottom + 4, label + ': toolbar overlaps guide ' + JSON.stringify(observed));
+ assert.ok(observed.scrollWidth <= width, label + ': horizontal overflow');
+ assert.ok(observed.primaryFont >= 13.5, label + ': full-page fitting made primary text too small: ' + observed.primaryFont);
+ if (geometry) assert.deepEqual(observed.geometry, geometry, label + ': authored node geometry/font changed');
+ else geometry = observed.geometry;
+ }
+ }
+ } finally {
+ await browser.close();
+ fs.rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+test('one long label does not enlarge the other titles in a narrow tall architecture', async (t) => {
+ if (!Object.hasOwn(process.env, 'ARCHIFY_CHROME')) return t.skip('Set ARCHIFY_CHROME for real browser checks');
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-reading-size-stress-'));
+ const input = path.join(dir, 'input.json');
+ const output = path.join(dir, 'output.html');
+ fs.writeFileSync(input, JSON.stringify({
+ schema_version: 1, diagram_type: 'architecture',
+ meta: { title: 'Tall architecture', output: 'output.html', quality_profile: 'showcase' },
+ components: [
+ { id: 'client', type: 'frontend', label: 'Authentication worker', pos: [40, 40], size: [140, 60] },
+ { id: 'api', type: 'backend', label: 'API', pos: [40, 340], size: [120, 60] },
+ { id: 'db', type: 'database', label: 'Store', pos: [40, 640], size: [120, 60] },
+ ],
+ connections: [{ from: 'client', to: 'api' }, { from: 'api', to: 'db' }],
+ }));
+ execFileSync(process.execPath, [path.join(root, 'bin/archify.mjs'), 'render', 'architecture', input, output]);
+ const browser = new ChromeVisualBrowser(findChrome());
+ try {
+ const metrics = await browser.inspect({ artifactPath: output, width: 1440, height: 900, theme: 'light' });
+ const session = await browser.sessionPromise;
+ const result = await browser.cdp.send('Runtime.evaluate', { returnByValue: true, expression: `(() => {
+ const svg = document.querySelector('.diagram-container > svg');
+ const scale = svg.getBoundingClientRect().width / svg.viewBox.baseVal.width;
+ return [...svg.querySelectorAll('text[data-node-label]')].map(text => ({
+ source: Number(text.getAttribute('font-size')), projected: Number(text.getAttribute('font-size')) * scale }));
+ })()` }, session);
+ assert.equal(result.exceptionDetails, undefined);
+ const sizes = result.result.value;
+ assert.ok(sizes[0].source < sizes[1].source, 'fixture must contain a fitted long title');
+ assert.ok(sizes[1].projected >= 13.5 && sizes[1].projected <= 14.2, JSON.stringify(sizes));
+ assert.ok(metrics.scrollWidth <= 1440);
+ assert.ok(metrics.scrollHeight > 900, 'preserve ordinary scroll instead of shrinking the tall graph');
+ } finally {
+ await browser.close();
+ fs.rmSync(dir, { recursive: true, force: true });
+ }
+});
diff --git a/archify/test/desktop-reader-browser.test.mjs b/archify/test/desktop-reader-browser.test.mjs
index 0fd2bb8a..411801dc 100644
--- a/archify/test/desktop-reader-browser.test.mjs
+++ b/archify/test/desktop-reader-browser.test.mjs
@@ -183,8 +183,8 @@ test('production showcase is readable in the real 1440 by 900 adaptive reader',
const artifactSource = fs.readFileSync(artifact, 'utf8');
const svgRoot = artifactSource.match(/<svg\b[^>]*>/)?.[0];
assert.ok(svgRoot, 'production fixture must contain an SVG root');
- // With 8px edge text across a 1376px SVG, the declared 7.5px floor
- // requires a 1290px diagram plus 30px of Reader chrome.
+ // The comfortable primary-text preference uses the available width here;
+ // the viewport cap still wins over the preferred reading size.
assert.match(svgRoot, /viewBox="0 0 1376 728"/);
assert.match(svgRoot, /data-reader-fit="intrinsic-height"/);
assert.match(svgRoot, /data-reader-min-text="7\.5"/);
@@ -203,9 +203,9 @@ test('production showcase is readable in the real 1440 by 900 adaptive reader',
));
for (const observation of [desktop, darkDesktop]) {
assert.ok(observation);
- assert.equal(observation.readerWidth, 1320);
+ assert.equal(observation.readerWidth, 1376);
assert.ok(observation.readerWidth <= 1376);
- assert.equal(observation.diagramWidth, 1290);
+ assert.equal(observation.diagramWidth, 1346);
assert.equal(observation.viewBoxWidth, 1376);
assert.ok(Number.isFinite(observation.minimumProjectedNodeTextPx));
assert.ok(observation.minimumProjectedNodeTextPx >= MIN_PROJECTED_NODE_TEXT_PX);
@@ -229,7 +229,7 @@ test('production showcase is readable in the real 1440 by 900 adaptive reader',
}
});
-test('route-expanded intrinsic architecture fits every required desktop viewport', {
+test('route-expanded intrinsic architecture preserves reading size with ordinary page scroll', {
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-'));
@@ -264,8 +264,7 @@ test('route-expanded intrinsic architecture fits every required desktop viewport
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.equal(viewport.overflowY, viewport.verticalScrollAccepted, JSON.stringify(viewport, null, 2));
for (const [field, floor] of [
['minimumProjectedNonEdgeTextPx', 7.5 - 0.01],
['minimumProjectedEdgeTextPx', MIN_PROJECTED_NODE_TEXT_PX],
@@ -280,7 +279,8 @@ test('route-expanded intrinsic architecture fits every required desktop viewport
&& height === DESKTOP_READABILITY_VIEWPORT.height
));
assert.ok(desktop);
- assert.ok(desktop.diagramWidth < desktop.viewBoxWidth, JSON.stringify(desktop, null, 2));
+ assert.ok(desktop.diagramWidth >= desktop.viewBoxWidth, JSON.stringify(desktop, null, 2));
+ assert.equal(desktop.verticalScrollAccepted, true, JSON.stringify(desktop, null, 2));
} finally {
fs.rmSync(tmp, { recursive: true, force: true });
}
diff --git a/scripts/run-browser-tests.mjs b/scripts/run-browser-tests.mjs
index 13474011..a8698d6b 100644
--- a/scripts/run-browser-tests.mjs
+++ b/scripts/run-browser-tests.mjs
@@ -16,6 +16,7 @@ const testFiles = [
'joint-layout-browser.test.mjs',
'sequence-header-clearance.test.mjs',
'compact-header-clearance.test.mjs',
+ 'architecture-reading-size-browser.test.mjs',
'lifecycle-rail-browser.test.mjs',
'export-cleanup-browser.test.mjs',
'offline-font-browser.test.mjs',
diff --git a/viewer/reader-layout.js b/viewer/reader-layout.js
index b089dc32..c8f77ca7 100644
--- a/viewer/reader-layout.js
+++ b/viewer/reader-layout.js
@@ -27,6 +27,7 @@
var requestedMinimumText = Number.isFinite(declaredMinimumText)
? Math.max(MIN_PROJECTED_NODE_TEXT_PX, declaredMinimumText)
: MIN_PROJECTED_NODE_TEXT_PX;
+ var declaredPrimaryText = svg ? parseFloat(svg.getAttribute('data-reader-primary-text') || '') : null;
var SAFE_BOTTOM_GAP = 12;
if (diagram && ratio >= WIDE_RATIO) {
@@ -65,6 +66,20 @@
? Math.min(1, requestedMinimumText / sourceMinimum)
: 1;
}
+ function primaryReadingWidth() {
+ if (!measuredHeightFit || !Number.isFinite(declaredPrimaryText) || declaredPrimaryText <= 0) return 0;
+ var sourcePrimary = null;
+ Array.from(svg.querySelectorAll('text[data-node-label]')).forEach(function (text) {
+ var size = parseFloat(text.getAttribute('font-size') || '');
+ if (Number.isFinite(size) && size > 0) sourcePrimary = sourcePrimary == null ? size : Math.max(sourcePrimary, size);
+ });
+ // Primary labels should remain comfortable to read when cards or
+ // auxiliary rows make a one-screen fit too small. Ordinary page
+ // scroll preserves that reading size; viewport width still caps it.
+ // A long title may already use a smaller fitted font. Preserve that
+ // hierarchy rather than enlarging every other node to compensate.
+ return sourcePrimary == null ? 0 : viewBox.width * declaredPrimaryText / sourcePrimary;
+ }
function eligible() {
return Boolean(
shell && diagram && svg && (ratio >= WIDE_RATIO || measuredHeightFit) &&
@@ -146,6 +161,8 @@
} else {
minWidth = Math.min(readableMinimumWidth, viewportCap);
}
+ var primaryWidth = primaryReadingWidth();
+ if (primaryWidth > 0) minWidth = Math.max(minWidth, Math.min(maxWidth, primaryWidth + chrome.diagramX));
var fixedHeight = chrome.bodyY + chrome.diagramY + SAFE_BOTTOM_GAP +
outerHeight(header) + outerHeight(guided) + outerHeight(cards);
var availableSvgHeight = Math.max(1, window.innerHeight - fixedHeight);