Skip to content

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

fix: preserve legacy geometry and shared output safeguards

WangHao43abaa4ae35b
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.md
index 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.md
index 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.zip
index 13ef23f5..cb962703 100644
Binary files a/archify.zip and b/archify.zip differ
diff --git a/archify/SKILL.md b/archify/SKILL.md
index 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 showcas
Never 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 capabilities
Generated 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.html
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.gif
index 3f0f7d64..36ccf1e9 100644
Binary files a/docs/assets/archify-live-proof.gif and b/docs/assets/archify-live-proof.gif differ
diff --git a/docs/assets/archify-live-proof.json b/docs/assets/archify-live-proof.json
index 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.md
new file mode 100644
index 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.png
new file mode 100644
index 00000000..b90c272d
Binary files /dev/null and b/docs/reading-evidence/layered-dark.png differ
diff --git a/docs/reading-evidence/layered-light.png b/docs/reading-evidence/layered-light.png
new file mode 100644
index 00000000..25be6680
Binary files /dev/null and b/docs/reading-evidence/layered-light.png differ
diff --git a/docs/reading-evidence/sequence-after.png b/docs/reading-evidence/sequence-after.png
new file mode 100644
index 00000000..4d7f8a59
Binary files /dev/null and b/docs/reading-evidence/sequence-after.png differ
diff --git a/docs/reading-evidence/sequence-before.png b/docs/reading-evidence/sequence-before.png
new file mode 100644
index 00000000..95ddfc0f
Binary files /dev/null and b/docs/reading-evidence/sequence-before.png differ
diff --git a/docs/specs/readability-layered-reading.md b/docs/specs/readability-layered-reading.md
index 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.