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
fix: preserve legacy geometry and shared output safeguards
WangHao43abaa4ae35b
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 70e2527c..2d39c3ce 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -6,7 +6,7 @@ All notable changes are documented here. Format loosely follows [Keep a Changelo### Improved reading-- Sequence message names use larger primary type and matching label plates; real browser readability checks now include message labels.+- Showcase sequence message names use larger primary type and matching label plates; real browser readability checks now include message labels.- Optional `atlas` packages checked overview/detail HTML with explicit node links, keyboard navigation, preserved overview position, synchronized themes and artifact fingerprints. Browser and perceptual acceptance remain separate.> Development identity: `v2.17.0-dev.1`. Not a stable release.diff --git a/README.md b/README.mdindex 78caf1d9..c4d952c9 100644--- a/README.md+++ b/README.md@@ -269,7 +269,7 @@ The complete generation and viewer contract lives in [`archify/SKILL.md`](archif- [Schema reference](archify/schemas/README.md) · [Skill](archify/SKILL.md) · [Examples](archify/examples/) · [Agent cookbook](docs/authoring-cookbook.md)- [Changelog](CHANGELOG.md)- [Roadmap](ROADMAP.md)-- [Layered reading](archify/references/layered-reading.md): an offline overview with explicit detail links, preserved reading position and shared themes.+- [Layered reading](archify/references/layered-reading.md)- [Generated Proof Lab](https://tt-a1i.github.io/archify/gallery.html)Automatic Mermaid parsing, general-purpose auto-layout, hosted sharing, and WYSIWYG editing are intentionally outside the current scope.diff --git a/README_EN.md b/README_EN.mdindex 78caf1d9..c4d952c9 100644--- a/README_EN.md+++ b/README_EN.md@@ -269,7 +269,7 @@ The complete generation and viewer contract lives in [`archify/SKILL.md`](archif- [Schema reference](archify/schemas/README.md) · [Skill](archify/SKILL.md) · [Examples](archify/examples/) · [Agent cookbook](docs/authoring-cookbook.md)- [Changelog](CHANGELOG.md)- [Roadmap](ROADMAP.md)-- [Layered reading](archify/references/layered-reading.md): an offline overview with explicit detail links, preserved reading position and shared themes.+- [Layered reading](archify/references/layered-reading.md)- [Generated Proof Lab](https://tt-a1i.github.io/archify/gallery.html)Automatic Mermaid parsing, general-purpose auto-layout, hosted sharing, and WYSIWYG editing are intentionally outside the current scope.diff --git a/archify.zip b/archify.zipindex 13ef23f5..cb962703 100644Binary files a/archify.zip and b/archify.zip differdiff --git a/archify/SKILL.md b/archify/SKILL.mdindex 4011ba54..a689eedc 100644--- a/archify/SKILL.md+++ b/archify/SKILL.md@@ -115,6 +115,8 @@ node bin/archify.mjs preview <type> <input>.json <output>.html --quality showcasNever start preview by default. Read `references/delivery-contract.md` when using preview, repository evidence, export receipts, visual review, or post-commit opening.+For separately authored overview/detail diagrams, read [layered reading](references/layered-reading.md) and use its explicit atlas manifest. Prefer existing Focus, Views and Story when one topology can explain the detail.+## Optional viewer capabilitiesGenerated HTML already contains theme switching, pan/zoom, search, focus, relationship tracing, semantic views, presentation, and truthful exports. These are reader capabilities, not extra authoring work. `meta.animation: "trace"` is opt-in; `meta.views` is optional and should contain at most five curated chapters.diff --git a/archify/assets/atlas.html b/archify/assets/atlas.htmlindex af66b199..ea3798a2 100644--- a/archify/assets/atlas.html+++ b/archify/assets/atlas.html@@ -25,8 +25,7 @@background: var(--bg);color: var(--ink);font:- 14px system-ui,- sans-serif;+ 14px "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;}iframe {position: absolute;diff --git a/archify/bin/atlas.mjs b/archify/bin/atlas.mjsindex 7ebe7693..3a7bdb7c 100644--- a/archify/bin/atlas.mjs+++ b/archify/bin/atlas.mjs@@ -3,6 +3,7 @@ import path from "node:path";import { createHash } from "node:crypto";import { spawnSync } from "node:child_process";import { fileURLToPath } from "node:url";+import { resolveOutputPath } from "../renderers/shared/output-path.mjs";const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");const fingerprint = (bytes) => ({@@ -28,15 +29,10 @@ function fields(value, names, subject) {for (const key of Object.keys(value))if (!names.includes(key)) reject(`Unknown field "${key}".`, subject);}-function canonical(file) {- return fs.existsSync(file)- ? fs.realpathSync(file)- : path.join(fs.realpathSync(path.dirname(file)), path.basename(file));-}export function buildAtlas(input, output) {const inputPath = fs.realpathSync(input),- outputPath = path.resolve(output);+ outputPath = resolveOutputPath({ requestedOutput: output, inputPaths: [inputPath] }).outputPath;const manifestBytes = fs.readFileSync(inputPath);const manifest = JSON.parse(manifestBytes);fields(@@ -134,10 +130,8 @@ export function buildAtlas(input, output) {!manifest.links.some((link) => link.details.includes(id)))reject("Every detail must be reachable from the overview.", { id });- if (inputs.includes(canonical(outputPath)))- reject("Output must not replace the manifest or a child artifact.", {- output,- });+ const outputRequest = { requestedOutput: outputPath, inputPaths: inputs };+ resolveOutputPath(outputRequest);const data = JSON.stringify({ ...manifest, diagrams }).replace(/</g,"\\u003c",@@ -155,6 +149,7 @@ export function buildAtlas(input, output) {try {const candidate = path.join(staging, "atlas.html");fs.writeFileSync(candidate, html);+ resolveOutputPath(outputRequest);fs.renameSync(candidate, outputPath);} finally {fs.rmSync(staging, { recursive: true, force: true });@@ -187,7 +182,7 @@ export function commandAtlas(args) {: `Atlas written: ${receipt.artifact.path}; browser and perceptual review pending`,);} catch (error) {- const diagnostic = error.diagnostic || {+ const diagnostic = error.diagnostic || error.archifyDiagnostics?.[0] || {code: "atlas/input-or-delivery",severity: "error",message: error.message,diff --git a/archify/renderers/sequence/render-sequence.mjs b/archify/renderers/sequence/render-sequence.mjsindex 56e22afb..ee748b7c 100644--- a/archify/renderers/sequence/render-sequence.mjs+++ b/archify/renderers/sequence/render-sequence.mjs@@ -38,6 +38,10 @@ const colGap = columnFit === 'spread' && participantCount > 1? Math.max(108, (viewBox[0] - 40 - sideMargin - participantW) / (participantCount - 1)): 108;+// Showcase is the fast-authoring default; standard retains legacy label geometry.+const readableMessages = sequence.meta?.quality_profile === 'showcase';+const messageFontSize = readableMessages ? 11 : 9;+const messageUnitWidth = readableMessages ? 6.6 : 5.2;const layout = {topY: 72,participantW,@@ -47,7 +51,7 @@ const layout = {legendY: viewBox[1] - 54,leftX: columnFit === 'spread' ? sideMargin + participantW / 2 : sideMargin,colGap,- labelH: 18+ labelH: readableMessages ? 18 : 16};const participantBoxWidthNote = columnFit === 'spread'@@ -90,7 +94,7 @@ function messageGeometry(message) {function messageLabelBox(message, relationIndex = null) {const geometry = messageGeometry(message);if (!geometry) return null;- const width = Math.max(34, textUnits(message.label) * 6.6 + 12);+ const width = Math.max(34, textUnits(message.label) * messageUnitWidth + 12);return {relation: message,relationIndex,@@ -361,7 +365,7 @@ function messageLabel(message, x1, x2) {const box = messageLabelBox(message);const center = box ? box.x + box.width / 2 : (x1 + x2) / 2;const y = message.y - 10;- const labelW = box?.width || Math.max(34, textUnits(message.label) * 6.6 + 12);+ const labelW = box?.width || Math.max(34, textUnits(message.label) * messageUnitWidth + 12);const accent = message.variant === 'security'? 't-security': message.variant === 'dashed'@@ -371,7 +375,7 @@ function messageLabel(message, x1, x2) {: 't-backend';return ` <g data-detail="context"><rect x="${center - labelW / 2}" y="${y - 10}" width="${labelW}" height="${layout.labelH}" rx="3" class="c-mask"/>- <text x="${center}" y="${y}" class="${accent}" font-size="11" text-anchor="middle">${esc(message.label)}</text>+ <text x="${center}" y="${y}" class="${accent}" font-size="${messageFontSize}" text-anchor="middle">${esc(message.label)}</text></g>`;}diff --git a/archify/test/atlas-browser.test.mjs b/archify/test/atlas-browser.test.mjsindex bc40e4c8..4f95ea01 100644--- a/archify/test/atlas-browser.test.mjs+++ b/archify/test/atlas-browser.test.mjs@@ -173,6 +173,10 @@ test(true,);}+ await evaluate(`${frame}.contentWindow.Archify.exportMenu.run('svg')`);+ assert.equal(await evaluate(`${frame}.contentDocument.documentElement.getAttribute('data-last-export-canonical')`), 'true');+ assert.equal(await evaluate(`${frame}.contentDocument.documentElement.getAttribute('data-last-export-format')`), 'svg');+ assert.ok(await evaluate(`${frame}.contentDocument.querySelectorAll('span[data-atlas-icon] svg').length`) > 0);if (process.env.ARCHIFY_READING_EVIDENCE) {fs.mkdirSync(process.env.ARCHIFY_READING_EVIDENCE, { recursive: true });for (const mode of ["light", "dark"]) {diff --git a/archify/test/atlas.test.mjs b/archify/test/atlas.test.mjsindex 18115ebd..9f0429d0 100644--- a/archify/test/atlas.test.mjs+++ b/archify/test/atlas.test.mjs@@ -80,3 +80,17 @@ test("atlas refuses to overwrite a source or manifest", (t) => {assert.equal(run(child).status, 1);assert.deepEqual(fs.readFileSync(child), before);});++test('atlas preserves non-HTML targets and uses shared path diagnostics', (t) => {+ const { run, output } = setup(t);+ const target = path.join(path.dirname(output), 'existing.json');+ fs.writeFileSync(target, '{"keep":true}');+ const direct = run(target);+ assert.equal(direct.status, 1);+ assert.equal(direct.receipt.diagnostics[0].code, 'output/cli-extension');+ fs.symlinkSync(target, output);+ const linked = run();+ assert.equal(linked.status, 1);+ assert.equal(linked.receipt.diagnostics[0].code, 'output/cli-resolved-extension');+ assert.equal(fs.readFileSync(target, 'utf8'), '{"keep":true}');+});diff --git a/archify/test/sequence-column-fit.test.mjs b/archify/test/sequence-column-fit.test.mjsindex cbf28a33..29e300ce 100644--- a/archify/test/sequence-column-fit.test.mjs+++ b/archify/test/sequence-column-fit.test.mjs@@ -137,9 +137,24 @@ test('the fast authoring path explains when to opt into spread', () => {});test('message names use readable primary type with a plate wide enough for the same text', () => {- const html = render(wideSequence('spread'));+ const doc = wideSequence('spread');+ doc.meta.quality_profile = 'showcase';+ const html = render(doc);const match = html.match(/<rect x="[^"]+" y="[^"]+" width="([^"]+)" height="[^"]+" rx="3" class="c-mask"\/>\s*<text[^>]*font-size="([^"]+)"[^>]*>authorize<\/text>/);assert.ok(match, 'message and its plate are present');assert.ok(Number(match[2]) >= 11, 'primary message text should be at least 11 source px');assert.ok(Number(match[1]) >= 9 * 6.4 + 12, 'plate must fit the larger monospace text');});+++test('standard retains acceptance for parallel schema-v1 labels with legacy spacing', () => {+ const doc = {+ schema_version: 1, diagram_type: 'sequence', meta: { title: 'Parallel requests' },+ participants: ['a', 'b', 'c', 'd'].map(id => ({ id, type: 'backend', label: id })),+ messages: [+ { from: 'a', to: 'b', y: 200, label: '123456789012345678901234567890123' },+ { from: 'c', to: 'd', y: 200, label: '123456789012345678901234567890123' },+ ],+ };+ assert.equal(renderOutcome(doc).code, 0);+});diff --git a/docs/assets/archify-live-proof.gif b/docs/assets/archify-live-proof.gifindex 3f0f7d64..36ccf1e9 100644Binary files a/docs/assets/archify-live-proof.gif and b/docs/assets/archify-live-proof.gif differdiff --git a/docs/assets/archify-live-proof.json b/docs/assets/archify-live-proof.jsonindex 9b47db9b..85c58a65 100644--- a/docs/assets/archify-live-proof.json+++ b/docs/assets/archify-live-proof.json@@ -7,8 +7,8 @@"fps": 10,"frameCount": 54,"durationSeconds": 5.4,- "bytes": 1629621,- "sha256": "ede2e0c6f3d5ef9f1d3aa9324a3ba55d23a8628c340d8ef50c6b7e3ce09610d5",+ "bytes": 1823983,+ "sha256": "0dc7b8fe26c79c8d67a2da94bfa1278d11f958ce4eae3f79bc61a58d679e4c1a","scenes": [{"id": "signal-flow",@@ -31,7 +31,7 @@{"id": "classic","artifact": "docs/gallery/artifacts/cache-miss.sequence.html",- "artifactSha256": "7c5c8f5c39c10dc8148591f654cd79a05ff49bb70166a4c45607414ca02cbe3a",+ "artifactSha256": "62fac8cc0bc21c5f9b134d09009fe6fde3a9d756bc3941e9c01be2eaa03b958a","view": "cache-fallback","eyebrow": "SEQUENCE · CLASSIC","title": "Cache Miss Request",diff --git a/docs/reading-evidence/README.md b/docs/reading-evidence/README.mdnew file mode 100644index 00000000..1a830c1e--- /dev/null+++ b/docs/reading-evidence/README.md@@ -0,0 +1,43 @@+# Reading evidence++Comparison base: `10722002bb8777ecb639d93c49586fae4adf3ae4`.++The fixed input is `archify/examples/cache-miss-request.sequence.json`.+`sequence-before.png` and `sequence-after.png` compare its base and candidate+artifacts at 1440×900, Classic/light, READ/Still, in the same Chrome environment.+Message type increases from 9 to 11 source pixels with matching plates; the+participants, routes, labels and topology are retained. Standard inputs retain+legacy message metrics, covered by a parallel-label regression.++`layered-light.png` and `layered-dark.png` show the separate-detail reader at+2048×1320 after an offline browser run. The browser fixture uses three copies+of the checked sequence to exercise single-target and multi-target navigation+without introducing unverified domain relationships. The runnable product+sample `archify/references/request-reading.atlas.json` instead links the web+application's API node to its cache-miss sequence.++Reproduce interaction evidence:++```sh+ARCHIFY_CHROME="/path/to/chrome" ARCHIFY_READING_EVIDENCE="/tmp/reading-evidence" \+ node --test archify/test/atlas-browser.test.mjs+```++That test blocks HTTP/HTTPS and exercises Enter activation, explicit detail+choice, return camera/focus, shell/child theme synchronization, four desktop+sizes, icon painting and canonical SVG export. Its second case deliberately+shrinks message text to prove that browser readability detects the defect.++Run `archify/test/desktop-reader-browser.test.mjs` with the same Chrome setting+for all packaged diagrams and the production architecture readability case.++Perceptual review: screenshots were inspected with an image-capable reviewer.+The enlarged messages remain distinct from auxiliary labels, no new message+collision was observed in the comparison, and both atlas themes show visible+controls and a contained diagram. This is bounded evidence for the fixtures,+not a guarantee for arbitrary supplied HTML, all exports or every browser.++Independent review disposition: the shared output-path guard replaces bespoke+alias handling; CLI tests cover non-HTML and symlink-resolved non-HTML targets.+The standard-v1 parallel-message compatibility finding is fixed by retaining+legacy sizing outside showcase. Atlas chrome uses the project's mono stack.diff --git a/docs/reading-evidence/layered-dark.png b/docs/reading-evidence/layered-dark.pngnew file mode 100644index 00000000..b90c272dBinary files /dev/null and b/docs/reading-evidence/layered-dark.png differdiff --git a/docs/reading-evidence/layered-light.png b/docs/reading-evidence/layered-light.pngnew file mode 100644index 00000000..25be6680Binary files /dev/null and b/docs/reading-evidence/layered-light.png differdiff --git a/docs/reading-evidence/sequence-after.png b/docs/reading-evidence/sequence-after.pngnew file mode 100644index 00000000..4d7f8a59Binary files /dev/null and b/docs/reading-evidence/sequence-after.png differdiff --git a/docs/reading-evidence/sequence-before.png b/docs/reading-evidence/sequence-before.pngnew file mode 100644index 00000000..95ddfc0fBinary files /dev/null and b/docs/reading-evidence/sequence-before.png differdiff --git a/docs/specs/readability-layered-reading.md b/docs/specs/readability-layered-reading.mdindex aceff955..cfdd6f80 100644--- a/docs/specs/readability-layered-reading.md+++ b/docs/specs/readability-layered-reading.md@@ -4,7 +4,7 @@ Agreed scope: improve default reading quality and let readers move from an overv## Acceptance-- Sequence message names are primary reading content. Use a readable default size, measure matching label plates, preserve authored messages and geometry, and include message text in real browser readability evidence.+- Sequence message names are primary reading content. Use a readable showcase size, retain standard legacy sizing, measure matching label plates, preserve authored messages and geometry, and include message text in real browser readability evidence.- Preserve standard schema-v1 input compatibility. New geometry acceptance restrictions must not be introduced merely for taste.- An opt-in `atlas` CLI packages existing checked Archify HTML files with explicit overview-node-to-detail associations in one offline HTML. Existing Focus/Views/Story remain the right choice for detail within the same topology.- Readers can choose among multiple explicitly linked details, return to the exact overview reading state, and keep a common theme. Keyboard navigation is supported. No inferred relationships, automatic diagram splitting, hosted runtime, editing interface, or permanent directory panel.