Skip to content

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

experiment: compare grouped bottom node index rows

杨嘉伟d4ce3461c266
diff --git a/experiments/node-index-rows/README.md b/experiments/node-index-rows/README.md
new file mode 100644
index 00000000..56fda390
--- /dev/null
+++ b/experiments/node-index-rows/README.md
@@ -0,0 +1,53 @@
+# Bottom Node index row prototype (#664)
+
+Review-only experiment from dev `7a3e1f3a`. It does not change the default
+viewer, generated template, ZIP, or diagram renderers.
+
+`prototype.css` replaces bottom-index columns with full-width group sections
+and a wrapping grid of items. Existing group/node order, counts, text,
+category colors, buttons, and event handlers are reused. Labels and sublabels
+wrap without reducing their font size. Side and overlay selectors are untouched.
+
+Run the matched comparison with an installed Chrome and an output directory
+outside the checkout:
+
+```powershell
+$env:ARCHIFY_CHROME = 'C:\Program Files\Google\Chrome\Application\chrome.exe'
+node experiments/node-index-rows/compare.mjs C:\Temp\archify-node-index-review
+```
+
+The script saves HTML, PNG, and JSON observations for Sample Web App and a
+26-node uneven-group fixture with long Chinese/English text. Both use
+1440×900 and 390×900, light/dark, ordinary mode, and unchanged SVG contents.
+It checks text/order/color identity, SVG identity, document width, text
+clipping, programmatic focus, pointer-enter preview, and click selection
+against the column baseline. Native Tab/Enter and panel-toggle interaction
+still need an integration pass before adopting this as a default.
+
+## Results and tradeoffs
+
+At 1440px, Sample Web App's index height changes from 338.69px to 289.38px
+(about 15% less); the uneven 26-node fixture changes from 852.69px to
+610.38px (about 28% less). Node labels/subtitles remain at existing font sizes.
+
+At 390px, preserving all text increases height: Sample Web App becomes
+667.38px instead of 435.25px, and the long-text fixture becomes 1726.38px
+instead of 934.25px. This is an explicit tradeoff for readable wrapping
+rather than single-line truncation. No horizontal page overflow was observed.
+
+Current dev hides the reader rail below its desktop eligibility breakpoint.
+For narrow comparison only, both HTML copies expose the existing bottom CSS
+using a separate experiment attribute. These screenshots test the CSS proposal,
+not a shipped narrow-screen reader behavior. Whether to expose that index on
+mobile remains a product decision.
+
+The browser reports no persistent focus preview after a frame on either the
+baseline or candidate, while pointer-enter preview and click selection work.
+This unchanged baseline behavior must not be reported as a newly fixed
+keyboard-preview feature.
+
+Visually reviewed the unselected Sample Web App desktop comparison and the
+long-text narrow candidate. Group membership is clear; desktop whitespace is
+used better, and narrow labels wrap. Exact spacing remains open for review.
+
+Related issue: https://github.com/tt-a1i/archify/issues/664
diff --git a/experiments/node-index-rows/compare.mjs b/experiments/node-index-rows/compare.mjs
new file mode 100644
index 00000000..46e75999
--- /dev/null
+++ b/experiments/node-index-rows/compare.mjs
@@ -0,0 +1,116 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { ChromeVisualBrowser, findChrome } from '../../archify/bin/visual-check.mjs';
+
+const experiment = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(experiment, '../..');
+const output = process.argv[2];
+assert.ok(output, 'Pass an output directory outside the repository');
+fs.mkdirSync(output, { recursive: true });
+const bottomSelector = 'html[data-reader-rail="bottom"]';
+const comparisonSelector = 'html:is([data-reader-rail="bottom"], [data-node-index-prototype-narrow])';
+const css = fs.readFileSync(path.join(experiment, 'prototype.css'), 'utf8').replaceAll(bottomSelector, comparisonSelector);
+const fixtures = new Map([['sample-web-app', fs.readFileSync(path.join(root, 'examples/web-app-rendered.html'), 'utf8')]]);
+const stress = {
+ schema_version: 1, diagram_type: 'architecture',
+ meta: { title: 'Uneven groups and long bilingual labels', output: 'stress.html', viewBox: [2500, 1250] },
+ components: Array.from({ length: 26 }, (_, i) => ({
+ id: `node-${i}`, type: i % 3 ? 'backend' : 'database',
+ label: i % 2 ? `Authorization policy and audit service ${i}` : `跨区域订单处理与权限校验服务节点 ${i}`,
+ sublabel: i % 2 ? 'Tenant-aware policy decisions with durable audit records' : '用于跨区域处理、审计追踪与长期持久化的内部服务',
+ pos: [50 + (i % 4) * 340, 85 + Math.floor(i / 4) * 155], size: [310, 75],
+ })),
+ boundaries: [
+ { kind: 'region', label: 'Small group', wraps: ['node-0', 'node-1'] },
+ { kind: 'region', label: '跨区域服务分组 / Long English service group', wraps: Array.from({ length: 24 }, (_, i) => `node-${i + 2}`) },
+ ],
+ connections: [],
+};
+const input = path.join(output, 'stress.json');
+const rendered = path.join(output, 'stress-source.html');
+fs.writeFileSync(input, JSON.stringify(stress));
+execFileSync(process.execPath, [path.join(root, 'archify/bin/archify.mjs'), 'render', 'architecture', input, rendered]);
+fixtures.set('stress', fs.readFileSync(rendered, 'utf8'));
+const browser = new ChromeVisualBrowser(findChrome());
+const observations = [];
+try {
+ const session = await browser.sessionPromise;
+ const send = (method, params = {}) => browser.cdp.send(method, params, session);
+ for (const [name, original] of fixtures) {
+ for (const width of [1440, 390]) {
+ for (const theme of ['light', 'dark']) {
+ let baseline;
+ let baselineInteraction;
+ for (const candidate of [false, true]) {
+ // Expose the existing bottom CSS under a separate experiment attribute
+ // at narrow widths; the reader does not own or clear this attribute.
+ const comparison = original.replaceAll(bottomSelector, comparisonSelector).replace('</head>',
+ '<script>if(innerWidth<768)document.documentElement.setAttribute("data-node-index-prototype-narrow", "")</script></head>');
+ const html = candidate ? comparison.replace('</head>', `<style>${css}</style></head>`) : comparison;
+ const label = `${name}-${width}-${theme}-${candidate ? 'rows' : 'columns'}`;
+ const artifact = path.join(output, `${label}.html`);
+ fs.writeFileSync(artifact, html);
+ await send('Emulation.setDeviceMetricsOverride', { width, height: 900, deviceScaleFactor: 1, mobile: width < 768 });
+ const url = pathToFileURL(artifact); url.searchParams.set('theme', theme);
+ const loaded = browser.cdp.waitFor('Page.loadEventFired', session);
+ await send('Page.navigate', { url: url.href }); await loaded;
+ const measured = await send('Runtime.evaluate', { awaitPromise: true, returnByValue: true, expression: `(async () => {
+ await document.fonts.ready; await Archify.layoutStability.whenStable();
+ const panel = document.getElementById('node-outline');
+ const items = [...panel.querySelectorAll('[data-outline-node]')];
+ const svg = document.querySelector('.diagram-container > svg');
+ return {
+ rail: document.documentElement.getAttribute('data-reader-rail'),
+ narrowPanelExperiment: document.documentElement.hasAttribute('data-node-index-prototype-narrow'),
+ scrollWidth: document.documentElement.scrollWidth,
+ panelHeight: panel.getBoundingClientRect().height,
+ svg: svg.outerHTML,
+ items: items.map(item => ({id:item.dataset.outlineNode, text:item.textContent, tone:item.style.getPropertyValue('--outline-tone')})),
+ clipped: items.flatMap(item => [...item.querySelectorAll('strong,small')]).filter(el => el.scrollWidth > el.clientWidth + 1).map(el => el.textContent)
+ };
+ })()` });
+ assert.equal(measured.exceptionDetails, undefined);
+ const value = measured.result.value;
+ if (!candidate) baseline = structuredClone(value);
+ else {
+ assert.deepEqual(value.items, baseline.items, `${label}: order, text or category changed`);
+ assert.equal(value.svg, baseline.svg, `${label}: SVG changed`);
+ assert.ok(value.scrollWidth <= width, `${label}: horizontal overflow`);
+ assert.deepEqual(value.clipped, [], `${label}: clipped index text`);
+ }
+ const interaction = await send('Runtime.evaluate', { awaitPromise: true, returnByValue: true, expression: `(async () => {
+ Archify.focus.clear(); Archify.routeProbe.clear();
+ const button=document.querySelector('[data-outline-node]');
+ button.focus(); await new Promise(r=>requestAnimationFrame(r));
+ const focused=document.activeElement===button;
+ const focusPreview=document.querySelector('.diagram-container > svg').getAttribute('data-intent-trace-active');
+ button.dispatchEvent(new PointerEvent('pointerenter'));
+ const hoverPreview=document.querySelector('.diagram-container > svg').getAttribute('data-intent-trace-active');
+ button.click(); await new Promise(r=>requestAnimationFrame(r));
+ return {focused, focusPreview, hoverPreview, id:button.dataset.outlineNode, selected:button.getAttribute('aria-current')};
+ })()` });
+ assert.equal(interaction.result.value.focused, true);
+ assert.equal(interaction.result.value.selected, 'true');
+ if (!candidate) baselineInteraction = interaction.result.value;
+ else assert.deepEqual(interaction.result.value, baselineInteraction, `${label}: interaction changed`);
+ value.interaction = interaction.result.value;
+ // Restore the same unselected state before taking the comparison.
+ const resetLoaded = browser.cdp.waitFor('Page.loadEventFired', session);
+ await send('Page.navigate', { url: url.href }); await resetLoaded;
+ await send('Runtime.evaluate', { awaitPromise: true, expression: 'document.fonts.ready.then(()=>Archify.layoutStability.whenStable())' });
+ const shot = await send('Page.captureScreenshot', { format: 'png', captureBeyondViewport: true });
+ fs.writeFileSync(path.join(output, `${label}.png`), Buffer.from(shot.data, 'base64'));
+ delete value.svg;
+ observations.push({ label, ...value });
+ }
+ }
+ }
+ }
+} finally {
+ await browser.close();
+ fs.writeFileSync(path.join(output, 'observations.json'), JSON.stringify(observations, null, 2));
+}
+console.log(`Saved matched comparisons to ${output}`);
diff --git a/experiments/node-index-rows/prototype.css b/experiments/node-index-rows/prototype.css
new file mode 100644
index 00000000..2da69a9e
--- /dev/null
+++ b/experiments/node-index-rows/prototype.css
@@ -0,0 +1,37 @@
+/* Review-only experiment for #664. All selectors are scoped to the bottom rail. */
+html[data-reader-rail="bottom"] .node-outline-list {
+ columns: auto;
+ display: grid;
+ gap: 0.75rem;
+}
+html[data-reader-rail="bottom"] .node-outline-group > ul {
+ display: grid;
+ grid-template-columns: repeat(auto-fill, minmax(min(100%, 18rem), 1fr));
+ gap: 0.25rem 0.75rem;
+}
+html[data-reader-rail="bottom"] .node-outline-group > ul::before { display: none; }
+html[data-reader-rail="bottom"] .node-outline-heading {
+ justify-content: flex-start;
+ gap: 0.5rem;
+}
+html[data-reader-rail="bottom"] .node-outline-heading > span { overflow-wrap: anywhere; }
+html[data-reader-rail="bottom"] .node-outline-item {
+ height: 100%;
+ grid-template-columns: 0.625rem minmax(0, 1fr) 0.75rem;
+ row-gap: 0.125rem;
+ align-content: start;
+ padding-block: 0.5rem;
+}
+html[data-reader-rail="bottom"] .node-outline-item strong {
+ grid-column: 2;
+ white-space: normal;
+ overflow-wrap: anywhere;
+}
+html[data-reader-rail="bottom"] .node-outline-item small {
+ grid-column: 2;
+ grid-row: 2;
+ text-align: left;
+ white-space: normal;
+ overflow-wrap: anywhere;
+}
+html[data-reader-rail="bottom"] .node-outline-item::after { grid-column: 3; grid-row: 1; }