Skip to content

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

feat: improve sequence readability and add explicit layered reading

WangHaoc840ce430ebc
diff --git a/CHANGELOG.md b/CHANGELOG.md
index bd03a391..70e2527c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,11 @@ All notable changes are documented here. Format loosely follows [Keep a Changelo
## [Unreleased]
+### Improved reading
+
+- 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.
### Fixed
diff --git a/README.md b/README.md
index 5983178b..78caf1d9 100644
--- a/README.md
+++ b/README.md
@@ -269,6 +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.
- [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 5983178b..78caf1d9 100644
--- a/README_EN.md
+++ b/README_EN.md
@@ -269,6 +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.
- [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_ZH.md b/README_ZH.md
index cb5a5d26..7a08fab2 100644
--- a/README_ZH.md
+++ b/README_ZH.md
@@ -272,6 +272,7 @@ Claude.ai 中的上传入口:
- [Agent 编图手册](docs/authoring-cookbook.zh-CN.md) · [English](docs/authoring-cookbook.md)
- [版本历史](CHANGELOG.md)
- [路线图](ROADMAP.md)
+- [分层阅读](archify/references/layered-reading.md):离线总览与显式细节关联,保留阅读位置并统一主题。
- [自动生成的 Proof Lab](https://tt-a1i.github.io/archify/gallery.html)
自动 Mermaid Parser、通用自动布局、托管分享服务和 WYSIWYG 编辑器目前都不在产品范围内。
diff --git a/archify.zip b/archify.zip
index 1b21ad02..13ef23f5 100644
Binary files a/archify.zip and b/archify.zip differ
diff --git a/archify/assets/atlas.html b/archify/assets/atlas.html
new file mode 100644
index 00000000..af66b199
--- /dev/null
+++ b/archify/assets/atlas.html
@@ -0,0 +1,307 @@
+<!doctype html>
+<html lang="en">
+ <head>
+ <meta charset="utf-8" />
+ <meta name="viewport" content="width=device-width,initial-scale=1" />
+ <title>Archify</title>
+ <style>
+ :root {
+ color-scheme: light;
+ --bg: #f8fafc;
+ --ink: #172438;
+ --line: #cbd5e1;
+ }
+ html[data-theme="dark"] {
+ color-scheme: dark;
+ --bg: #101827;
+ --ink: #e2e8f0;
+ --line: #475569;
+ }
+ * {
+ box-sizing: border-box;
+ }
+ body {
+ margin: 0;
+ background: var(--bg);
+ color: var(--ink);
+ font:
+ 14px system-ui,
+ sans-serif;
+ }
+ iframe {
+ position: absolute;
+ inset: 0;
+ width: 100%;
+ height: 100%;
+ border: 0;
+ }
+ iframe[hidden] {
+ display: none;
+ }
+ nav {
+ position: fixed;
+ bottom: 12px;
+ left: 12px;
+ z-index: 2;
+ display: flex;
+ gap: 8px;
+ padding: 6px;
+ background: var(--bg);
+ border: 1px solid var(--line);
+ border-radius: 8px;
+ max-width: calc(100% - 24px);
+ }
+ button {
+ font: inherit;
+ cursor: pointer;
+ color: var(--ink);
+ background: var(--bg);
+ border: 1px solid var(--line);
+ border-radius: 5px;
+ padding: 8px 12px;
+ }
+ button:focus-visible {
+ outline: 3px solid #0891b2;
+ outline-offset: 2px;
+ }
+ button[hidden] {
+ display: none;
+ }
+ dialog {
+ color: var(--ink);
+ background: var(--bg);
+ border: 1px solid var(--line);
+ border-radius: 10px;
+ max-width: calc(100% - 32px);
+ }
+ dialog::backdrop {
+ background: #0007;
+ }
+ h2 {
+ font-size: 18px;
+ }
+ #choices {
+ display: grid;
+ gap: 8px;
+ margin-bottom: 16px;
+ }
+ #status {
+ position: fixed;
+ top: 12px;
+ left: 12px;
+ background: var(--bg);
+ padding: 8px;
+ }
+ #status:empty {
+ display: none;
+ }
+ @media print {
+ nav,
+ dialog,
+ #status {
+ display: none;
+ }
+ }
+ </style>
+ </head>
+ <body>
+ <main id="diagrams"></main>
+ <nav aria-label="Diagram navigation">
+ <button id="back" hidden></button><button id="theme"></button>
+ </nav>
+ <p id="status" role="status"></p>
+ <dialog id="details">
+ <h2 id="detail-title"></h2>
+ <div id="choices"></div>
+ <button id="close"></button>
+ </dialog>
+ <script id="atlas-data" type="application/json">
+ __ARCHIFY_ATLAS_DATA__
+ </script>
+ <script>
+ (() => {
+ "use strict";
+ const data = JSON.parse(
+ document.getElementById("atlas-data").textContent,
+ ),
+ frames = new Map();
+ const zh = data.locale === "zh-CN",
+ back = document.getElementById("back"),
+ themeButton = document.getElementById("theme"),
+ dialog = document.getElementById("details"),
+ status = document.getElementById("status");
+ document.documentElement.lang = zh ? "zh-CN" : "en";
+ document.title = data.title;
+ document
+ .querySelector("nav")
+ .setAttribute("aria-label", zh ? "图表导航" : "Diagram navigation");
+ back.textContent = zh ? "返回总览" : "Back to overview";
+ document.getElementById("close").textContent = zh ? "关闭" : "Close";
+ let current = data.overview,
+ opener = null;
+ let theme = matchMedia("(prefers-color-scheme: light)").matches
+ ? "light"
+ : "dark";
+ try {
+ const saved = localStorage.getItem("archify-theme");
+ if (["light", "dark"].includes(saved)) theme = saved;
+ } catch {}
+ function syncTheme(value) {
+ theme = value;
+ document.documentElement.dataset.theme = value;
+ themeButton.textContent =
+ value === "dark" ? (zh ? "浅色" : "Light") : zh ? "深色" : "Dark";
+ try {
+ localStorage.setItem("archify-theme", value);
+ } catch {}
+ for (const frame of frames.values()) {
+ const win = frame.contentWindow,
+ d = frame.contentDocument;
+ if (
+ win?.Archify?.theme &&
+ d.documentElement.dataset.theme !== value
+ )
+ win.Archify.theme.toggle();
+ }
+ }
+ // Chrome file:// srcdoc does not reliably paint CSS data-URI masks.
+ // Adapt viewer chrome only; the diagram SVG and canonical exports stay intact.
+ function paintIcons(frame) {
+ const d = frame.contentDocument;
+ for (const icon of d.querySelectorAll('span')) {
+ if (icon.dataset.atlasIcon) {
+ icon.style.removeProperty('mask-image');
+ icon.style.removeProperty('-webkit-mask-image');
+ icon.style.removeProperty('background');
+ }
+ const mask = frame.contentWindow.getComputedStyle(icon).maskImage;
+ const match = /^url\("data:image\/svg\+xml,([^"\n]+)"\)$/.exec(mask);
+ if (!match) continue;
+ const svg = new DOMParser().parseFromString(decodeURIComponent(match[1]), 'image/svg+xml').documentElement;
+ if (svg.localName !== 'svg') continue;
+ for (const element of [svg, ...svg.querySelectorAll('*')]) {
+ for (const attribute of ['fill', 'stroke']) {
+ if (element.getAttribute(attribute) === 'black') element.setAttribute(attribute, 'currentColor');
+ }
+ }
+ svg.setAttribute('width', '100%'); svg.setAttribute('height', '100%');
+ icon.dataset.atlasIcon = 'true';
+ icon.style.maskImage = 'none'; icon.style.webkitMaskImage = 'none';
+ icon.style.background = 'transparent';
+ icon.replaceChildren(d.importNode(svg, true));
+ }
+ }
+ function show(id) {
+ if (!data.diagrams.some((item) => item.id === id)) id = data.overview;
+ current = id;
+ for (const [key, frame] of frames) frame.hidden = key !== id;
+ if (!frames.has(id)) {
+ const item = data.diagrams.find((item) => item.id === id),
+ frame = document.createElement("iframe");
+ frame.title = item.title;
+ frame.dataset.diagramId = id;
+ frames.set(id, frame);
+ frame.addEventListener("load", () => {
+ const d = frame.contentDocument;
+ if (!frame.contentWindow.Archify?.theme) {
+ status.textContent = zh
+ ? "图表加载失败"
+ : "Diagram could not be loaded";
+ return;
+ }
+ syncTheme(theme);
+ paintIcons(frame);
+ const icons = new MutationObserver(() => paintIcons(frame));
+ for (const element of [d.documentElement, d.body]) icons.observe(element, {attributes:true, attributeFilter:['data-theme','data-preset','class']});
+ new MutationObserver(() => {
+ const value = d.documentElement.dataset.theme;
+ if (value !== theme && ["light", "dark"].includes(value))
+ syncTheme(value);
+ }).observe(d.documentElement, {
+ attributes: true,
+ attributeFilter: ["data-theme"],
+ });
+ if (id === data.overview)
+ for (const link of data.links) {
+ const node = [...d.querySelectorAll("[data-node-id]")].find(
+ (node) => node.dataset.nodeId === link.node,
+ );
+ if (!node) continue;
+ const hint = zh ? "查看细节" : "Open details";
+ node.setAttribute(
+ "aria-label",
+ (node.getAttribute("aria-label") || link.node) +
+ " — " +
+ hint,
+ );
+ node.setAttribute(
+ "aria-haspopup",
+ link.details.length > 1 ? "dialog" : "true",
+ );
+ function activate(event) {
+ if (
+ event.type === "keydown" &&
+ !["Enter", " "].includes(event.key)
+ )
+ return;
+ event.preventDefault();
+ event.stopImmediatePropagation();
+ opener = node;
+ if (link.details.length === 1) {
+ location.hash = link.details[0];
+ return;
+ }
+ document.getElementById("detail-title").textContent =
+ node.dataset.nodeLabel || link.node;
+ const choices = document.getElementById("choices");
+ choices.replaceChildren();
+ for (const target of link.details) {
+ const button = document.createElement("button");
+ button.textContent = data.diagrams.find(
+ (item) => item.id === target,
+ ).title;
+ button.addEventListener("click", () => {
+ dialog.close();
+ location.hash = target;
+ });
+ choices.append(button);
+ }
+ dialog.showModal();
+ }
+ node.addEventListener("click", activate, true);
+ node.addEventListener("keydown", activate, true);
+ }
+ frame.dataset.ready = "true";
+ if (current === id) status.textContent = "";
+ });
+ frame.srcdoc = item.html;
+ document.getElementById("diagrams").append(frame);
+ }
+ back.hidden = id === data.overview;
+ status.textContent = frames.get(id).dataset.ready
+ ? ""
+ : zh
+ ? "正在载入…"
+ : "Loading…";
+ if (id === data.overview && opener)
+ requestAnimationFrame(() => opener.focus());
+ }
+ back.addEventListener("click", () => {
+ location.hash = data.overview;
+ });
+ themeButton.addEventListener("click", () =>
+ syncTheme(theme === "dark" ? "light" : "dark"),
+ );
+ document
+ .getElementById("close")
+ .addEventListener("click", () => dialog.close());
+ dialog.addEventListener("close", () => opener?.focus());
+ window.addEventListener("hashchange", () =>
+ show(location.hash.slice(1)),
+ );
+ syncTheme(theme);
+ show(location.hash.slice(1) || data.overview);
+ })();
+ </script>
+ </body>
+</html>
diff --git a/archify/bin/archify.mjs b/archify/bin/archify.mjs
index cb6c40f5..b6b6ce7f 100755
--- a/archify/bin/archify.mjs
+++ b/archify/bin/archify.mjs
@@ -20,6 +20,7 @@ function usage() {
archify preview <type> <input.json> [output.html] [--no-open] [--quality standard|showcase] [--repo-root path (architecture only)]
archify validate <type> <input.json> [--json] [--layout-json] [--quality standard|showcase] [--repo-root path (architecture only)]
archify migrate workflow <old.json> <new.json> --to-schema 2 [--json]
+ archify atlas <manifest.json> <output.html> [--json]
archify inspect <type> <input.json>
archify check <output.html>
archify visual-check <output.html> [--json]
@@ -2060,6 +2061,9 @@ try {
case 'check':
commandCheck(args);
break;
+ case 'atlas':
+ (await import('./atlas.mjs')).commandAtlas(args);
+ break;
case 'visual-check':
await commandVisualCheck(args);
break;
diff --git a/archify/bin/atlas.mjs b/archify/bin/atlas.mjs
new file mode 100644
index 00000000..7ebe7693
--- /dev/null
+++ b/archify/bin/atlas.mjs
@@ -0,0 +1,210 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const fingerprint = (bytes) => ({
+ sha256: createHash("sha256").update(bytes).digest("hex"),
+ bytes: bytes.length,
+});
+const identifier = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
+function reject(message, subject = {}) {
+ const error = new Error(message);
+ error.diagnostic = {
+ code: "atlas/invalid-input",
+ severity: "error",
+ message,
+ subject,
+ evidence: {},
+ supportedFixes: ["correct the named manifest entry and rerun atlas"],
+ };
+ throw error;
+}
+function fields(value, names, subject) {
+ if (!value || typeof value !== "object" || Array.isArray(value))
+ reject("Expected an object.", 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);
+ const manifestBytes = fs.readFileSync(inputPath);
+ const manifest = JSON.parse(manifestBytes);
+ fields(
+ manifest,
+ ["schema_version", "title", "locale", "overview", "diagrams", "links"],
+ { input },
+ );
+ if (manifest.schema_version !== 1) reject("schema_version must be 1.");
+ if (typeof manifest.title !== "string" || !manifest.title.trim())
+ reject("title must be nonempty.");
+ if (
+ manifest.locale !== undefined &&
+ !["en", "zh-CN"].includes(manifest.locale)
+ )
+ reject("locale must be en or zh-CN.");
+ if (
+ !Array.isArray(manifest.diagrams) ||
+ manifest.diagrams.length < 2 ||
+ manifest.diagrams.length > 20
+ )
+ reject("Provide 2 to 20 diagrams.");
+ if (!Array.isArray(manifest.links) || !manifest.links.length)
+ reject("Provide explicit overview links.");
+ const ids = new Set(),
+ inputs = [inputPath];
+ const diagrams = manifest.diagrams.map((entry, index) => {
+ const subject = { diagram: index };
+ fields(entry, ["id", "title", "file"], subject);
+ if (!identifier.test(entry.id || "") || ids.has(entry.id))
+ reject("Diagram IDs must be unique identifiers.", subject);
+ ids.add(entry.id);
+ if (
+ typeof entry.title !== "string" ||
+ !entry.title.trim() ||
+ typeof entry.file !== "string"
+ )
+ reject("Each diagram needs a title and local HTML file.", subject);
+ const file = fs.realpathSync(
+ path.resolve(path.dirname(inputPath), entry.file),
+ );
+ inputs.push(file);
+ const bytes = fs.readFileSync(file),
+ html = bytes.toString("utf8");
+ if (!html.includes("data-node-id=") || !html.includes("Archify.theme"))
+ reject("Expected a renderer-backed Archify HTML artifact.", subject);
+ // Check a private snapshot: the bytes checked must be exactly the bytes embedded.
+ const snapshot = fs.mkdtempSync(
+ path.join(path.dirname(outputPath), ".archify-atlas-check-"),
+ );
+ try {
+ const candidate = path.join(snapshot, "diagram.html");
+ fs.writeFileSync(candidate, bytes);
+ const check = spawnSync(
+ process.execPath,
+ [path.join(root, "bin/archify.mjs"), "check", candidate],
+ { encoding: "utf8" },
+ );
+ if (check.status !== 0)
+ reject("Child artifact checks failed.", {
+ ...subject,
+ reason: check.stderr || check.stdout,
+ });
+ } finally {
+ fs.rmSync(snapshot, { recursive: true, force: true });
+ }
+ return { id: entry.id, title: entry.title, html, ...fingerprint(bytes) };
+ });
+ if (!ids.has(manifest.overview)) reject("overview must name a diagram.");
+ const overview = diagrams.find((entry) => entry.id === manifest.overview);
+ const nodes = [...overview.html.matchAll(/\bdata-node-id="([^"]+)"/g)].map(
+ (match) => match[1],
+ );
+ const linked = new Set();
+ for (const [index, link] of manifest.links.entries()) {
+ const subject = { link: index };
+ fields(link, ["node", "details"], subject);
+ if (
+ !identifier.test(link.node || "") ||
+ linked.has(link.node) ||
+ nodes.filter((node) => node === link.node).length !== 1
+ )
+ reject("Link must name one unique overview node.", subject);
+ linked.add(link.node);
+ if (
+ !Array.isArray(link.details) ||
+ !link.details.length ||
+ new Set(link.details).size !== link.details.length ||
+ link.details.some((id) => !ids.has(id) || id === manifest.overview)
+ )
+ reject("details must name distinct non-overview diagrams.", subject);
+ }
+ for (const id of ids)
+ if (
+ id !== manifest.overview &&
+ !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 data = JSON.stringify({ ...manifest, diagrams }).replace(
+ /</g,
+ "\\u003c",
+ );
+ const template = fs.readFileSync(
+ path.join(root, "assets/atlas.html"),
+ "utf8",
+ );
+ const html = Buffer.from(
+ template.replace("__ARCHIFY_ATLAS_DATA__", () => data),
+ );
+ const staging = fs.mkdtempSync(
+ path.join(path.dirname(outputPath), ".archify-atlas-"),
+ );
+ try {
+ const candidate = path.join(staging, "atlas.html");
+ fs.writeFileSync(candidate, html);
+ fs.renameSync(candidate, outputPath);
+ } finally {
+ fs.rmSync(staging, { recursive: true, force: true });
+ }
+ return {
+ schemaVersion: 1,
+ command: "atlas",
+ status: "pass",
+ specification: fingerprint(manifestBytes),
+ artifact: { path: outputPath, ...fingerprint(html) },
+ children: diagrams.map(({ id, sha256, bytes }) => ({ id, sha256, bytes })),
+ browser_evidence: "pending",
+ visual_review: "pending",
+ };
+}
+
+export function commandAtlas(args) {
+ const json = args.includes("--json"),
+ positional = args.filter((arg) => arg !== "--json");
+ try {
+ if (
+ positional.length !== 2 ||
+ positional.some((arg) => arg.startsWith("--"))
+ )
+ reject("Usage: archify atlas <manifest.json> <output.html> [--json]");
+ const receipt = buildAtlas(...positional);
+ console.log(
+ json
+ ? JSON.stringify(receipt)
+ : `Atlas written: ${receipt.artifact.path}; browser and perceptual review pending`,
+ );
+ } catch (error) {
+ const diagnostic = error.diagnostic || {
+ code: "atlas/input-or-delivery",
+ severity: "error",
+ message: error.message,
+ subject: {},
+ evidence: { reason: error.message },
+ supportedFixes: [
+ "check manifest JSON, input paths and output directory permissions",
+ ],
+ };
+ const receipt = {
+ schemaVersion: 1,
+ command: "atlas",
+ status: "fail",
+ diagnostics: [diagnostic],
+ };
+ if (json) console.log(JSON.stringify(receipt));
+ else console.error(diagnostic.message);
+ process.exitCode = 1;
+ }
+}
diff --git a/archify/bin/visual-check.mjs b/archify/bin/visual-check.mjs
index 8adb154b..ea5e4abc 100644
--- a/archify/bin/visual-check.mjs
+++ b/archify/bin/visual-check.mjs
@@ -397,8 +397,8 @@ export class ChromeVisualBrowser {
var scale = viewBoxWidth > 0 ? Math.min(1, diagramWidth / viewBoxWidth) : 0;
var minimum = null;
if (svg && scale > 0) {
- Array.from(svg.querySelectorAll('text[data-node-label], text[data-boundary-label], text[data-detail="context"]')).forEach(function (text) {
- var detail = text.hasAttribute('data-node-label')
+ Array.from(svg.querySelectorAll('text[data-node-label], text[data-boundary-label], text[data-detail="context"], [data-edge-id] g[data-detail="context"] > text')).forEach(function (text) {
+ var detail = text.closest('[data-edge-id]') ? 'message' : text.hasAttribute('data-node-label')
? 'primary'
: text.hasAttribute('data-boundary-label') ? 'boundary' : 'context';
if (detail === 'context' && !text.closest('[data-node-id]')) return;
diff --git a/archify/examples/sequence-cache-miss-request.html b/archify/examples/sequence-cache-miss-request.html
index 47a66b5f..2b53c7c3 100644
--- a/archify/examples/sequence-cache-miss-request.html
+++ b/archify/examples/sequence-cache-miss-request.html
@@ -5189,96 +5189,96 @@ OTHER DEALINGS IN THE FONT SOFTWARE.
<g data-edge-from="user" data-edge-to="web" data-edge-label="open page" data-edge-key="0" data-edge-id="open-page">
<path data-composition-edge-from="user" data-composition-edge-to="web" data-composition-edge-id="open-page" data-composition-points="125.5,160;255.66666666666663,160" d="M 125.5 160 L 255.66666666666663 160" class="a-default" data-animate="edge" style="--step:0" stroke-width="1.4" marker-end="url(#arrowhead)"/>
<g data-detail="context">
- <rect x="161.1833333333333" y="140" width="58.800000000000004" height="16" rx="3" class="c-mask"/>
- <text x="190.58333333333331" y="150" class="t-backend" font-size="9" text-anchor="middle">open page</text>
+ <rect x="154.88333333333333" y="140" width="71.4" height="18" rx="3" class="c-mask"/>
+ <text x="190.58333333333331" y="150" class="t-backend" font-size="11" text-anchor="middle">open page</text>
</g>
</g>
<g data-edge-from="web" data-edge-to="api" data-edge-label="GET /dashboard" data-edge-key="1" data-edge-id="dashboard-request">
<path data-composition-edge-from="web" data-composition-edge-to="api" data-composition-edge-id="dashboard-request" data-composition-points="269.66666666666663,185;399.8333333333333,185" d="M 269.66666666666663 185 L 399.8333333333333 185" class="a-emphasis" data-animate="edge" style="--step:1" stroke-width="1.8" marker-end="url(#arrowhead-emphasis)"/>
<g data-detail="context">
- <rect x="292.35" y="165" width="84.8" height="16" rx="3" class="c-mask"/>
- <text x="334.75" y="175" class="t-backend" font-size="9" text-anchor="middle">GET /dashboard</text>
+ <rect x="282.55" y="165" width="104.39999999999999" height="18" rx="3" class="c-mask"/>
+ <text x="334.75" y="175" class="t-backend" font-size="11" text-anchor="middle">GET /dashboard</text>
</g>
</g>
<g data-edge-from="api" data-edge-to="auth" data-edge-label="verify JWT" data-edge-key="2" data-edge-id="verify-jwt">
<path data-composition-edge-from="api" data-composition-edge-to="auth" data-composition-edge-id="verify-jwt" data-composition-points="413.8333333333333,210;544,210" d="M 413.8333333333333 210 L 544 210" class="a-security" data-animate="edge" style="--step:2" stroke-width="1.4" marker-end="url(#arrowhead-security)"/>
<g data-detail="context">
- <rect x="446.91666666666663" y="190" width="64" height="16" rx="3" class="c-mask"/>
- <text x="478.91666666666663" y="200" class="t-security" font-size="9" text-anchor="middle">verify JWT</text>
+ <rect x="439.91666666666663" y="190" width="78" height="18" rx="3" class="c-mask"/>
+ <text x="478.91666666666663" y="200" class="t-security" font-size="11" text-anchor="middle">verify JWT</text>
</g>
</g>
<g data-edge-from="auth" data-edge-to="api" data-edge-label="claims ok" data-edge-key="3" data-edge-id="auth-claims">
<path data-composition-edge-from="auth" data-composition-edge-to="api" data-composition-edge-id="auth-claims" data-composition-points="544,238;413.8333333333333,238" d="M 544 238 L 413.8333333333333 238" class="a-default" data-animate="edge" style="--step:3" stroke-width="1.4" stroke-dasharray="3,5" marker-end="url(#arrowhead)"/>
<g data-detail="context">
- <rect x="449.51666666666665" y="218" width="58.800000000000004" height="16" rx="3" class="c-mask"/>
- <text x="478.91666666666663" y="228" class="t-muted" font-size="9" text-anchor="middle">claims ok</text>
+ <rect x="443.21666666666664" y="218" width="71.4" height="18" rx="3" class="c-mask"/>
+ <text x="478.91666666666663" y="228" class="t-muted" font-size="11" text-anchor="middle">claims ok</text>
</g>
</g>
<g data-edge-from="api" data-edge-to="redis" data-edge-label="read cache" data-edge-key="4" data-edge-id="cache-read">
<path data-composition-edge-from="api" data-composition-edge-to="redis" data-composition-edge-id="cache-read" data-composition-points="413.8333333333333,270;688.1666666666666,270" d="M 413.8333333333333 270 L 688.1666666666666 270" class="a-default" data-animate="edge" style="--step:4" stroke-width="1.4" marker-end="url(#arrowhead)"/>
<g data-detail="context">
- <rect x="519" y="250" width="64" height="16" rx="3" class="c-mask"/>
- <text x="551" y="260" class="t-backend" font-size="9" text-anchor="middle">read cache</text>
+ <rect x="512" y="250" width="78" height="18" rx="3" class="c-mask"/>
+ <text x="551" y="260" class="t-backend" font-size="11" text-anchor="middle">read cache</text>
</g>
</g>
<g data-edge-from="redis" data-edge-to="api" data-edge-label="miss" data-edge-key="5" data-edge-id="cache-miss">
<path data-composition-edge-from="redis" data-composition-edge-to="api" data-composition-edge-id="cache-miss" data-composition-points="688.1666666666666,298;413.8333333333333,298" d="M 688.1666666666666 298 L 413.8333333333333 298" class="a-default" data-animate="edge" style="--step:5" stroke-width="1.4" stroke-dasharray="3,5" marker-end="url(#arrowhead)"/>
<g data-detail="context">
- <rect x="534" y="278" width="34" height="16" rx="3" class="c-mask"/>
- <text x="551" y="288" class="t-muted" font-size="9" text-anchor="middle">miss</text>
+ <rect x="531.8" y="278" width="38.4" height="18" rx="3" class="c-mask"/>
+ <text x="551" y="288" class="t-muted" font-size="11" text-anchor="middle">miss</text>
</g>
</g>
<g data-edge-from="api" data-edge-to="db" data-edge-label="query profile + metrics" data-edge-key="6" data-edge-id="profile-query">
<path data-composition-edge-from="api" data-composition-edge-to="db" data-composition-edge-id="profile-query" data-composition-points="413.8333333333333,330;832.3333333333333,330" d="M 413.8333333333333 330 L 832.3333333333333 330" class="a-emphasis" data-animate="edge" style="--step:6" stroke-width="1.8" marker-end="url(#arrowhead-emphasis)"/>
<g data-detail="context">
- <rect x="557.2833333333333" y="310" width="131.60000000000002" height="16" rx="3" class="c-mask"/>
- <text x="623.0833333333333" y="320" class="t-backend" font-size="9" text-anchor="middle">query profile + metrics</text>
+ <rect x="541.1833333333333" y="310" width="163.79999999999998" height="18" rx="3" class="c-mask"/>
+ <text x="623.0833333333333" y="320" class="t-backend" font-size="11" text-anchor="middle">query profile + metrics</text>
</g>
</g>
<g data-edge-from="db" data-edge-to="api" data-edge-label="rows" data-edge-key="7" data-edge-id="profile-rows">
<path data-composition-edge-from="db" data-composition-edge-to="api" data-composition-edge-id="profile-rows" data-composition-points="832.3333333333333,358;413.8333333333333,358" d="M 832.3333333333333 358 L 413.8333333333333 358" class="a-default" data-animate="edge" style="--step:7" stroke-width="1.4" stroke-dasharray="3,5" marker-end="url(#arrowhead)"/>
<g data-detail="context">
- <rect x="606.0833333333333" y="338" width="34" height="16" rx="3" class="c-mask"/>
- <text x="623.0833333333333" y="348" class="t-muted" font-size="9" text-anchor="middle">rows</text>
+ <rect x="603.8833333333332" y="338" width="38.4" height="18" rx="3" class="c-mask"/>
+ <text x="623.0833333333333" y="348" class="t-muted" font-size="11" text-anchor="middle">rows</text>
</g>
</g>
<g data-edge-from="api" data-edge-to="redis" data-edge-label="set cache" data-edge-key="8" data-edge-id="cache-write">
<path data-composition-edge-from="api" data-composition-edge-to="redis" data-composition-edge-id="cache-write" data-composition-points="413.8333333333333,390;688.1666666666666,390" d="M 413.8333333333333 390 L 688.1666666666666 390" class="a-dashed" data-animate="edge" style="--step:8" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
<g data-detail="context">
- <rect x="521.6" y="370" width="58.800000000000004" height="16" rx="3" class="c-mask"/>
- <text x="551" y="380" class="t-messagebus" font-size="9" text-anchor="middle">set cache</text>
+ <rect x="515.3" y="370" width="71.4" height="18" rx="3" class="c-mask"/>
+ <text x="551" y="380" class="t-messagebus" font-size="11" text-anchor="middle">set cache</text>
</g>
</g>
<g data-edge-from="api" data-edge-to="trace" data-edge-label="emit trace" data-edge-key="9" data-edge-id="trace-emit">
<path data-composition-edge-from="api" data-composition-edge-to="trace" data-composition-edge-id="trace-emit" data-composition-points="413.8333333333333,418;976.5,418" d="M 413.8333333333333 418 L 976.5 418" class="a-dashed" data-animate="edge" style="--step:9" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
<g data-detail="context">
- <rect x="663.1666666666666" y="398" width="64" height="16" rx="3" class="c-mask"/>
- <text x="695.1666666666666" y="408" class="t-messagebus" font-size="9" text-anchor="middle">emit trace</text>
+ <rect x="656.1666666666666" y="398" width="78" height="18" rx="3" class="c-mask"/>
+ <text x="695.1666666666666" y="408" class="t-messagebus" font-size="11" text-anchor="middle">emit trace</text>
</g>
</g>
<g data-edge-from="api" data-edge-to="web" data-edge-label="200 JSON" data-edge-key="10" data-edge-id="dashboard-response">
<path data-composition-edge-from="api" data-composition-edge-to="web" data-composition-edge-id="dashboard-response" data-composition-points="399.8333333333333,443;269.66666666666663,443" d="M 399.8333333333333 443 L 269.66666666666663 443" class="a-default" data-animate="edge" style="--step:10" stroke-width="1.4" stroke-dasharray="3,5" marker-end="url(#arrowhead)"/>
<g data-detail="context">
- <rect x="307.95" y="423" width="53.6" height="16" rx="3" class="c-mask"/>
- <text x="334.75" y="433" class="t-muted" font-size="9" text-anchor="middle">200 JSON</text>
+ <rect x="302.35" y="423" width="64.8" height="18" rx="3" class="c-mask"/>
+ <text x="334.75" y="433" class="t-muted" font-size="11" text-anchor="middle">200 JSON</text>
</g>
</g>
<g data-edge-from="web" data-edge-to="user" data-edge-label="render" data-edge-key="11" data-edge-id="page-render">
<path data-composition-edge-from="web" data-composition-edge-to="user" data-composition-edge-id="page-render" data-composition-points="255.66666666666663,468;125.5,468" d="M 255.66666666666663 468 L 125.5 468" class="a-default" data-animate="edge" style="--step:11" stroke-width="1.4" stroke-dasharray="3,5" marker-end="url(#arrowhead)"/>
<g data-detail="context">
- <rect x="168.98333333333332" y="448" width="43.2" height="16" rx="3" class="c-mask"/>
- <text x="190.58333333333331" y="458" class="t-muted" font-size="9" text-anchor="middle">render</text>
+ <rect x="164.7833333333333" y="448" width="51.599999999999994" height="18" rx="3" class="c-mask"/>
+ <text x="190.58333333333331" y="458" class="t-muted" font-size="11" text-anchor="middle">render</text>
</g>
</g>
diff --git a/archify/references/delivery-contract.md b/archify/references/delivery-contract.md
index 301d7df7..9f4ab0c9 100644
--- a/archify/references/delivery-contract.md
+++ b/archify/references/delivery-contract.md
@@ -118,3 +118,7 @@ correction_rounds: 0|1|2
Derive `browser_evidence` only from the latest artifact-bound `visual-check` receipt. Record any manual browser work separately with its artifact binding, viewport/theme scope, and observations; never use it or `visual_review` to overwrite the automated status.
Opening, preview status, Share Cards, and other viewer exports are not validation claims.
+
+## Multiple authored diagrams
+
+For an overview linked to separately authored details, see [layered reading](layered-reading.md). The atlas receipt covers composition and exact embedded child bytes; child `visual-check` results do not establish atlas browser acceptance.
diff --git a/archify/references/layered-reading.md b/archify/references/layered-reading.md
new file mode 100644
index 00000000..3fdbf99b
--- /dev/null
+++ b/archify/references/layered-reading.md
@@ -0,0 +1,54 @@
+# Layered reading
+
+Use Focus, Views and Story when the same diagram topology can explain the detail.
+Use an atlas only when a module needs a separate authored diagram. An atlas is a
+portable reading artifact, not a diagram editor or a repository browser.
+
+Deliver each child HTML first, then author a manifest:
+
+```json
+{
+ "schema_version": 1,
+ "title": "Request processing",
+ "locale": "en",
+ "overview": "overview",
+ "diagrams": [
+ { "id": "overview", "title": "Request overview", "file": "overview.html" },
+ { "id": "worker", "title": "Worker execution", "file": "worker.html" }
+ ],
+ "links": [{ "node": "worker", "details": ["worker"] }]
+}
+```
+
+```sh
+node bin/archify.mjs atlas atlas.json atlas.html --json
+```
+
+A [runnable sample](request-reading.atlas.json) links the packaged web application to its cache-miss sequence.
+
+Paths resolve relative to the manifest. IDs start with a letter and contain only
+letters, digits, `_` or `-`. Supply 2–20 diagrams. Every detail must be explicitly
+reachable from a unique overview node. Multiple detail IDs open a choice dialog;
+one opens directly. Unlinked nodes retain their ordinary Focus behavior. Linked
+nodes use click or Enter/Space to open details. Return restores the overview's
+existing camera and keyboard focus. The compact theme control and child theme
+controls stay synchronized. Locale is `en` (default) or `zh-CN` for atlas chrome;
+child content is not translated. The atlas preserves the child HTML bytes and
+never adjusts their typography or geometry. A viewer-chrome adapter paints existing CSS mask icons as inline SVG in local `srcdoc` frames; diagram SVG is unchanged.
+
+The command checks private snapshots of all child artifacts before atomically
+replacing the atlas. Invalid manifests, links or children preserve the previous
+output. The JSON receipt binds the manifest, all embedded children and output by
+SHA-256 and byte count. Keep that receipt with the output. This is artifact
+validation, not a browser or perceptual verdict: both remain `pending`.
+
+Open the final atlas offline and check keyboard entry, multi-detail choice,
+return position, both themes, child export behavior and desktop containment.
+`visual-check` is a single-diagram tool; do not present its child receipts as
+atlas acceptance. Record atlas browser evidence against its final hash, then
+inspect screenshots independently. Atlas exports remain the active child's
+canonical exports; the navigation shell is not part of them.
+
+Only package trusted, locally authored Archify HTML. Child scripts execute in the
+same local reading context; the atlas is not an isolation boundary for untrusted
+HTML. It introduces no hosted dependency or automatic relationship discovery.
diff --git a/archify/references/request-reading.atlas.json b/archify/references/request-reading.atlas.json
new file mode 100644
index 00000000..926b47ed
--- /dev/null
+++ b/archify/references/request-reading.atlas.json
@@ -0,0 +1,10 @@
+{
+ "schema_version": 1,
+ "title": "Web request processing",
+ "overview": "overview",
+ "diagrams": [
+ { "id": "overview", "title": "Web application", "file": "../examples/web-app-rendered.html" },
+ { "id": "request", "title": "Cache miss request", "file": "../examples/sequence-cache-miss-request.html" }
+ ],
+ "links": [{ "node": "api", "details": ["request"] }]
+}
diff --git a/archify/renderers/sequence/render-sequence.mjs b/archify/renderers/sequence/render-sequence.mjs
index 1cfc032a..56e22afb 100644
--- a/archify/renderers/sequence/render-sequence.mjs
+++ b/archify/renderers/sequence/render-sequence.mjs
@@ -47,7 +47,7 @@ const layout = {
legendY: viewBox[1] - 54,
leftX: columnFit === 'spread' ? sideMargin + participantW / 2 : sideMargin,
colGap,
- labelH: 16
+ labelH: 18
};
const participantBoxWidthNote = columnFit === 'spread'
@@ -90,7 +90,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) * 5.2 + 12);
+ const width = Math.max(34, textUnits(message.label) * 6.6 + 12);
return {
relation: message,
relationIndex,
@@ -361,7 +361,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) * 5.2 + 12);
+ const labelW = box?.width || Math.max(34, textUnits(message.label) * 6.6 + 12);
const accent = message.variant === 'security'
? 't-security'
: message.variant === 'dashed'
@@ -371,7 +371,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="9" text-anchor="middle">${esc(message.label)}</text>
+ <text x="${center}" y="${y}" class="${accent}" font-size="11" text-anchor="middle">${esc(message.label)}</text>
</g>`;
}
diff --git a/archify/test/atlas-browser.test.mjs b/archify/test/atlas-browser.test.mjs
new file mode 100644
index 00000000..bc40e4c8
--- /dev/null
+++ b/archify/test/atlas-browser.test.mjs
@@ -0,0 +1,234 @@
+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 { pathToFileURL, fileURLToPath } from "node:url";
+import {
+ ChromeVisualBrowser,
+ findChrome,
+ runVisualCheck,
+} from "../bin/visual-check.mjs";
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const chrome = process.env.ARCHIFY_CHROME ? findChrome() : null;
+
+test(
+ "offline layered reading preserves overview state, keyboard access and themes",
+ { skip: !chrome },
+ async (t) => {
+ const dir = fs.mkdtempSync(
+ path.join(os.tmpdir(), "archify-layered-browser-"),
+ );
+ t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+ const child = path.join(dir, "sequence.html");
+ execFileSync(process.execPath, [
+ path.join(root, "bin/archify.mjs"),
+ "deliver",
+ "sequence",
+ path.join(root, "examples/cache-miss-request.sequence.json"),
+ child,
+ ]);
+ const html = fs.readFileSync(child, "utf8"),
+ nodes = [...html.matchAll(/data-node-id="([^"]+)"/g)].map((m) => m[1]);
+ const manifest = {
+ schema_version: 1,
+ title: "Request details",
+ overview: "overview",
+ diagrams: ["overview", "detail", "alternative"].map((id) => ({
+ id,
+ title: id,
+ file: child,
+ })),
+ links: [
+ { node: nodes[0], details: ["detail"] },
+ { node: nodes[1], details: ["detail", "alternative"] },
+ ],
+ };
+ const input = path.join(dir, "atlas.json"),
+ output = path.join(dir, "atlas.html");
+ fs.writeFileSync(input, JSON.stringify(manifest));
+ execFileSync(process.execPath, [
+ path.join(root, "bin/archify.mjs"),
+ "atlas",
+ input,
+ output,
+ ]);
+ const browser = new ChromeVisualBrowser(chrome);
+ t.after(() => browser.close());
+ const session = await browser.sessionPromise,
+ send = (method, params = {}) => browser.cdp.send(method, params, session);
+ const evaluate = async (expression) => {
+ const r = await send("Runtime.evaluate", {
+ expression,
+ returnByValue: true,
+ awaitPromise: true,
+ });
+ if (r.exceptionDetails) throw Error(JSON.stringify(r.exceptionDetails));
+ return r.result.value;
+ };
+ const ready = () =>
+ evaluate(
+ `new Promise((resolve,reject)=>{let count=0;const timer=setInterval(()=>{const f=document.querySelector('iframe:not([hidden])');if(f?.dataset.ready==='true'){clearInterval(timer);resolve(true)}else if(++count>100){clearInterval(timer);reject(Error('frame timeout'))}},50)})`,
+ );
+ await send("Network.enable");
+ await send("Network.setBlockedURLs", { urls: ["http://*", "https://*"] });
+ await send("Emulation.setDeviceMetricsOverride", {
+ width: 1440,
+ height: 900,
+ deviceScaleFactor: 1,
+ mobile: false,
+ });
+ await send("Page.navigate", { url: pathToFileURL(output).href });
+ await ready();
+ const frame = `document.querySelector('iframe:not([hidden])')`;
+ await evaluate(`${frame}.contentWindow.Archify.view.zoomIn()`);
+ const before = await evaluate(
+ `${frame}.contentDocument.querySelector('.diagram-container svg').style.transform`,
+ );
+ await evaluate(
+ `${frame}.contentDocument.querySelector('[data-node-id="${nodes[0]}"]').focus()`,
+ );
+ await send("Input.dispatchKeyEvent", {
+ type: "keyDown",
+ key: "Enter",
+ code: "Enter",
+ windowsVirtualKeyCode: 13,
+ });
+ await send("Input.dispatchKeyEvent", {
+ type: "keyUp",
+ key: "Enter",
+ code: "Enter",
+ windowsVirtualKeyCode: 13,
+ });
+ await new Promise((r) => setTimeout(r, 100));
+ await ready();
+ assert.equal(await evaluate(`${frame}.dataset.diagramId`), "detail");
+ await evaluate(`document.getElementById('theme').click()`);
+ const theme = await evaluate(`document.documentElement.dataset.theme`);
+ assert.equal(
+ await evaluate(`${frame}.contentDocument.documentElement.dataset.theme`),
+ theme,
+ );
+ await evaluate(`document.getElementById('back').click()`);
+ await new Promise((r) => setTimeout(r, 100));
+ await ready();
+ assert.equal(await evaluate(`${frame}.dataset.diagramId`), "overview");
+ assert.equal(
+ await evaluate(
+ `${frame}.contentDocument.querySelector('.diagram-container svg').style.transform`,
+ ),
+ before,
+ );
+ assert.equal(
+ await evaluate(`${frame}.contentDocument.activeElement.dataset.nodeId`),
+ nodes[0],
+ );
+ await evaluate(
+ `${frame}.contentDocument.querySelector('[data-node-id="${nodes[1]}"]').dispatchEvent(new MouseEvent('click',{bubbles:true}))`,
+ );
+ assert.equal(
+ await evaluate(`document.getElementById('details').open`),
+ true,
+ );
+ assert.equal(
+ await evaluate(`document.getElementById('choices').children.length`),
+ 2,
+ );
+ await evaluate(
+ `document.getElementById('choices').lastElementChild.click()`,
+ );
+ await new Promise((r) => setTimeout(r, 100));
+ await ready();
+ assert.equal(await evaluate(`${frame}.dataset.diagramId`), "alternative");
+ await evaluate(`${frame}.contentWindow.Archify.theme.toggle()`);
+ await new Promise((r) => setTimeout(r, 100));
+ assert.notEqual(
+ await evaluate(`document.documentElement.dataset.theme`),
+ theme,
+ );
+ for (const [width, height] of [
+ [1440, 900],
+ [1600, 1000],
+ [1920, 1080],
+ [2048, 1320],
+ ]) {
+ await send("Emulation.setDeviceMetricsOverride", {
+ width,
+ height,
+ deviceScaleFactor: 1,
+ mobile: false,
+ });
+ await new Promise((r) => setTimeout(r, 350));
+ assert.equal(
+ await evaluate(
+ `document.documentElement.scrollWidth<=innerWidth&&document.documentElement.scrollHeight<=innerHeight`,
+ ),
+ true,
+ );
+ assert.equal(
+ await evaluate(
+ `(()=>{const w=${frame}.contentWindow,d=w.document.documentElement;return d.scrollWidth<=w.innerWidth&&d.scrollHeight<=w.innerHeight})()`,
+ ),
+ true,
+ );
+ }
+ if (process.env.ARCHIFY_READING_EVIDENCE) {
+ fs.mkdirSync(process.env.ARCHIFY_READING_EVIDENCE, { recursive: true });
+ for (const mode of ["light", "dark"]) {
+ await evaluate(
+ `if(document.documentElement.dataset.theme!=='${mode}')document.getElementById('theme').click()`,
+ );
+ await new Promise((r) => setTimeout(r, 150));
+ const shot = await send("Page.captureScreenshot", { format: "png" });
+ fs.writeFileSync(
+ path.join(
+ process.env.ARCHIFY_READING_EVIDENCE,
+ `layered-${mode}.png`,
+ ),
+ Buffer.from(shot.data, "base64"),
+ );
+ }
+ }
+ },
+);
+
+test(
+ "real visual-check catches unreadable sequence message text",
+ { skip: !chrome },
+ async (t) => {
+ const dir = fs.mkdtempSync(
+ path.join(os.tmpdir(), "archify-message-browser-"),
+ );
+ t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+ const child = path.join(dir, "sequence.html");
+ execFileSync(process.execPath, [
+ path.join(root, "bin/archify.mjs"),
+ "render",
+ "sequence",
+ path.join(root, "examples/cache-miss-request.sequence.json"),
+ child,
+ ]);
+ // Simulate a regression in an artifact, independently of renderer constants.
+ fs.writeFileSync(
+ child,
+ fs
+ .readFileSync(child, "utf8")
+ .replace(
+ /(<text[^>]*class="t-backend"[^>]*font-size=")11("[^>]*>)/g,
+ "$13$2",
+ ),
+ );
+ const result = await runVisualCheck({
+ artifactPath: child,
+ chromePath: chrome,
+ });
+ assert.equal(result.exitCode, 1);
+ assert.equal(result.receipt.readability.status, "fail");
+ assert.ok(
+ result.receipt.readability.viewports.some(
+ (v) => v.minimumProjectedNodeTextDetail === "message",
+ ),
+ );
+ },
+);
diff --git a/archify/test/atlas.test.mjs b/archify/test/atlas.test.mjs
new file mode 100644
index 00000000..18115ebd
--- /dev/null
+++ b/archify/test/atlas.test.mjs
@@ -0,0 +1,82 @@
+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 { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const sha = (b) => createHash("sha256").update(b).digest("hex");
+function setup(t) {
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), "archify-atlas-test-"));
+ t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+ const child = path.join(root, "examples/sequence-cache-miss-request.html");
+ const html = fs.readFileSync(child, "utf8"),
+ node = html.match(/data-node-id="([^"]+)"/)[1];
+ const manifest = {
+ schema_version: 1,
+ title: "Reading </script> safely",
+ overview: "overview",
+ diagrams: [
+ { id: "overview", title: "Overview", file: child },
+ { id: "detail", title: "Detail", file: child },
+ ],
+ links: [{ node, details: ["detail"] }],
+ };
+ const input = path.join(dir, "atlas.json"),
+ output = path.join(dir, "atlas.html");
+ const run = (out = output) => {
+ fs.writeFileSync(input, JSON.stringify(manifest));
+ const r = spawnSync(
+ process.execPath,
+ [path.join(root, "bin/archify.mjs"), "atlas", input, out, "--json"],
+ { encoding: "utf8" },
+ );
+ return { ...r, receipt: JSON.parse(r.stdout) };
+ };
+ return { manifest, input, output, run, child };
+}
+test("atlas packages exact checked child bytes and binds a portable receipt", (t) => {
+ const { run, output, input, child } = setup(t),
+ r = run();
+ assert.equal(r.status, 0, r.stdout + r.stderr);
+ const bytes = fs.readFileSync(output),
+ html = bytes.toString(),
+ payload = JSON.parse(
+ html.match(
+ /<script id="atlas-data" type="application\/json">([\s\S]*?)<\/script>/,
+ )[1],
+ );
+ assert.equal(payload.diagrams[0].html, fs.readFileSync(child, "utf8"));
+ assert.equal(payload.title, "Reading </script> safely");
+ assert.equal(r.receipt.artifact.sha256, sha(bytes));
+ assert.equal(r.receipt.specification.sha256, sha(fs.readFileSync(input)));
+ assert.equal(r.receipt.browser_evidence, "pending");
+});
+test("invalid explicit references preserve the last good atlas", (t) => {
+ const { run, output, manifest } = setup(t);
+ assert.equal(run().status, 0);
+ const before = fs.readFileSync(output);
+ for (const mutate of [
+ () => (manifest.links[0].node = "missing"),
+ () => {
+ manifest.links[0].node = "still_missing";
+ manifest.diagrams[1].id = "overview";
+ },
+ ]) {
+ mutate();
+ const r = run();
+ assert.equal(r.status, 1);
+ assert.equal(r.receipt.status, "fail");
+ assert.ok(r.receipt.diagnostics[0].supportedFixes.length);
+ assert.deepEqual(fs.readFileSync(output), before);
+ }
+});
+test("atlas refuses to overwrite a source or manifest", (t) => {
+ const { run, input, child } = setup(t);
+ const before = fs.readFileSync(child);
+ assert.equal(run(input).status, 1);
+ assert.equal(run(child).status, 1);
+ assert.deepEqual(fs.readFileSync(child), before);
+});
diff --git a/archify/test/sequence-column-fit.test.mjs b/archify/test/sequence-column-fit.test.mjs
index e8917d87..cbf28a33 100644
--- a/archify/test/sequence-column-fit.test.mjs
+++ b/archify/test/sequence-column-fit.test.mjs
@@ -135,3 +135,11 @@ test('the fast authoring path explains when to opt into spread', () => {
assert.match(rendererReadme, /Use `"spread"` when a wide/);
assert.match(rendererReadme, /try `meta\.column_fit: "spread"` before shortening/);
});
+
+test('message names use readable primary type with a plate wide enough for the same text', () => {
+ const html = render(wideSequence('spread'));
+ 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');
+});
diff --git a/docs/gallery.html b/docs/gallery.html
index 0fc8e9b2..d680414b 100644
--- a/docs/gallery.html
+++ b/docs/gallery.html
@@ -357,7 +357,7 @@
<div class="receipt-cell"><span class="receipt-label">Artifact</span><span class="receipt-value ok">9/9 pass</span></div>
<div class="receipt-cell"><span class="receipt-label">Composition</span><span class="receipt-value ok" title="0 crossings · 0 border runs · 0 micro segments · 0 cramped turns">SHOWCASE · PASS</span></div>
<div class="receipt-cell"><span class="receipt-label">Graph</span><span class="receipt-value">7N · 12E</span></div>
- <div class="receipt-cell"><span class="receipt-label">SHA-256</span><span class="receipt-value" title="7c5c8f5c39c10dc8148591f654cd79a05ff49bb70166a4c45607414ca02cbe3a">7c5c8f5c39c1</span></div>
+ <div class="receipt-cell"><span class="receipt-label">SHA-256</span><span class="receipt-value" title="62fac8cc0bc21c5f9b134d09009fe6fde3a9d756bc3941e9c01be2eaa03b958a">62fac8cc0bc2</span></div>
</div>
<div class="card-actions">
<a class="card-link primary" href="gallery/artifacts/cache-miss.sequence.html?present=1&amp;play=1#view=cache-fallback" target="_blank" rel="noopener" data-en="Play named chapter ↗" data-zh="播放命名章节 ↗">Play named chapter ↗</a>
@@ -473,7 +473,7 @@
<div class="receipt-cell"><span class="receipt-label">Artifact</span><span class="receipt-value ok">9/9 pass</span></div>
<div class="receipt-cell"><span class="receipt-label">Composition</span><span class="receipt-value ok" title="0 crossings · 0 border runs · 0 micro segments · 0 cramped turns">SHOWCASE · PASS</span></div>
<div class="receipt-cell"><span class="receipt-label">Graph</span><span class="receipt-value">7N · 14E</span></div>
- <div class="receipt-cell"><span class="receipt-label">SHA-256</span><span class="receipt-value" title="8fb45b739efdc45b56f7f9a0cf2f7bf95573d382897198731f4b4b2f33567930">8fb45b739efd</span></div>
+ <div class="receipt-cell"><span class="receipt-label">SHA-256</span><span class="receipt-value" title="2515889e53c5342e315aa1c39b9a1cf24df4e0026c8aaa46287fa047c933e17c">2515889e53c5</span></div>
</div>
<div class="card-actions">
<a class="card-link primary" href="gallery/artifacts/async-job-roundtrip.sequence.html?present=1&amp;play=1#view=work-and-retry" target="_blank" rel="noopener" data-en="Play named chapter ↗" data-zh="播放命名章节 ↗">Play named chapter ↗</a>
@@ -875,8 +875,8 @@ receipt 99 checks / 11 artifacts / deterministic hashes</pre>
"engineeringProfile": null,
"nodeCount": 7,
"edgeCount": 12,
- "artifactBytes": 813020,
- "artifactSha256": "7c5c8f5c39c10dc8148591f654cd79a05ff49bb70166a4c45607414ca02cbe3a",
+ "artifactBytes": 813024,
+ "artifactSha256": "62fac8cc0bc21c5f9b134d09009fe6fde3a9d756bc3941e9c01be2eaa03b958a",
"sourceBytes": 4374,
"sourceSha256": "9a799a3661c16cd6ab4f6373ff6a04da95a9ab70d93b0a349b668466f4912fd7",
"checks": [
@@ -1275,8 +1275,8 @@ receipt 99 checks / 11 artifacts / deterministic hashes</pre>
"engineeringProfile": null,
"nodeCount": 7,
"edgeCount": 14,
- "artifactBytes": 812111,
- "artifactSha256": "8fb45b739efdc45b56f7f9a0cf2f7bf95573d382897198731f4b4b2f33567930",
+ "artifactBytes": 812142,
+ "artifactSha256": "2515889e53c5342e315aa1c39b9a1cf24df4e0026c8aaa46287fa047c933e17c",
"sourceBytes": 4370,
"sourceSha256": "545f20920c89b69c2bb1f15508d5543fddbeb15cffba61e102206e04bd5a5cd9",
"checks": [
diff --git a/docs/gallery/artifacts/async-job-roundtrip.sequence.html b/docs/gallery/artifacts/async-job-roundtrip.sequence.html
index 1b399ab7..a07edebd 100644
--- a/docs/gallery/artifacts/async-job-roundtrip.sequence.html
+++ b/docs/gallery/artifacts/async-job-roundtrip.sequence.html
@@ -5191,112 +5191,112 @@ OTHER DEALINGS IN THE FONT SOFTWARE.
<g data-edge-from="client" data-edge-to="api" data-edge-label="POST /jobs" data-edge-key="0">
<path data-composition-edge-from="client" data-composition-edge-to="api" data-composition-points="69,180;163,180" d="M 69 180 L 163 180" class="a-emphasis" data-animate="edge" style="--step:0" stroke-width="1.8" marker-end="url(#arrowhead-emphasis)"/>
<g data-detail="context">
- <rect x="84" y="160" width="64" height="16" rx="3" class="c-mask"/>
- <text x="116" y="170" class="t-backend" font-size="9" text-anchor="middle">POST /jobs</text>
+ <rect x="77" y="160" width="78" height="18" rx="3" class="c-mask"/>
+ <text x="116" y="170" class="t-backend" font-size="11" text-anchor="middle">POST /jobs</text>
</g>
</g>
<g data-edge-from="api" data-edge-to="queue" data-edge-label="enqueue job" data-edge-key="1">
<path data-composition-edge-from="api" data-composition-edge-to="queue" data-composition-points="177,222;271,222" d="M 177 222 L 271 222" class="a-emphasis" data-animate="edge" style="--step:1" stroke-width="1.8" marker-end="url(#arrowhead-emphasis)"/>
<g data-detail="context">
- <rect x="189.4" y="202" width="69.2" height="16" rx="3" class="c-mask"/>
- <text x="224" y="212" class="t-backend" font-size="9" text-anchor="middle">enqueue job</text>
+ <rect x="181.7" y="202" width="84.6" height="18" rx="3" class="c-mask"/>
+ <text x="224" y="212" class="t-backend" font-size="11" text-anchor="middle">enqueue job</text>
</g>
</g>
<g data-edge-from="api" data-edge-to="client" data-edge-label="202 + job id" data-edge-key="2">
<path data-composition-edge-from="api" data-composition-edge-to="client" data-composition-points="163,264;69,264" d="M 163 264 L 69 264" class="a-default" data-animate="edge" style="--step:2" stroke-width="1.4" stroke-dasharray="3,5" marker-end="url(#arrowhead)"/>
<g data-detail="context">
- <rect x="78.8" y="244" width="74.4" height="16" rx="3" class="c-mask"/>
- <text x="116" y="254" class="t-muted" font-size="9" text-anchor="middle">202 + job id</text>
+ <rect x="70.4" y="244" width="91.19999999999999" height="18" rx="3" class="c-mask"/>
+ <text x="116" y="254" class="t-muted" font-size="11" text-anchor="middle">202 + job id</text>
</g>
</g>
<g data-edge-from="queue" data-edge-to="worker" data-edge-label="deliver" data-edge-key="3">
<path data-composition-edge-from="queue" data-composition-edge-to="worker" data-composition-points="285,326;379,326" d="M 285 326 L 379 326" class="a-emphasis" data-animate="edge" style="--step:3" stroke-width="1.8" marker-end="url(#arrowhead-emphasis)"/>
<g data-detail="context">
- <rect x="307.8" y="306" width="48.4" height="16" rx="3" class="c-mask"/>
- <text x="332" y="316" class="t-backend" font-size="9" text-anchor="middle">deliver</text>
+ <rect x="302.9" y="306" width="58.199999999999996" height="18" rx="3" class="c-mask"/>
+ <text x="332" y="316" class="t-backend" font-size="11" text-anchor="middle">deliver</text>
</g>
</g>
<g data-edge-from="worker" data-edge-to="provider" data-edge-label="perform work" data-edge-key="4">
<path data-composition-edge-from="worker" data-composition-edge-to="provider" data-composition-points="393,368;487,368" d="M 393 368 L 487 368" class="a-default" data-animate="edge" style="--step:4" stroke-width="1.4" marker-end="url(#arrowhead)"/>
<g data-detail="context">
- <rect x="402.8" y="348" width="74.4" height="16" rx="3" class="c-mask"/>
- <text x="440" y="358" class="t-backend" font-size="9" text-anchor="middle">perform work</text>
+ <rect x="394.4" y="348" width="91.19999999999999" height="18" rx="3" class="c-mask"/>
+ <text x="440" y="358" class="t-backend" font-size="11" text-anchor="middle">perform work</text>
</g>
</g>
<g data-edge-from="provider" data-edge-to="worker" data-edge-label="result / timeout" data-edge-key="5">
<path data-composition-edge-from="provider" data-composition-edge-to="worker" data-composition-points="487,410;393,410" d="M 487 410 L 393 410" class="a-default" data-animate="edge" style="--step:5" stroke-width="1.4" stroke-dasharray="3,5" marker-end="url(#arrowhead)"/>
<g data-detail="context">
- <rect x="392.4" y="390" width="95.2" height="16" rx="3" class="c-mask"/>
- <text x="440" y="400" class="t-muted" font-size="9" text-anchor="middle">result / timeout</text>
+ <rect x="381.2" y="390" width="117.6" height="18" rx="3" class="c-mask"/>
+ <text x="440" y="400" class="t-muted" font-size="11" text-anchor="middle">result / timeout</text>
</g>
</g>
<g data-edge-from="worker" data-edge-to="queue" data-edge-label="retry if timeout" data-edge-key="6">
<path data-composition-edge-from="worker" data-composition-edge-to="queue" data-composition-points="379,452;285,452" d="M 379 452 L 285 452" class="a-dashed" data-animate="edge" style="--step:6" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
<g data-detail="context">
- <rect x="284.4" y="432" width="95.2" height="16" rx="3" class="c-mask"/>
- <text x="332" y="442" class="t-messagebus" font-size="9" text-anchor="middle">retry if timeout</text>
+ <rect x="273.2" y="432" width="117.6" height="18" rx="3" class="c-mask"/>
+ <text x="332" y="442" class="t-messagebus" font-size="11" text-anchor="middle">retry if timeout</text>
</g>
</g>
<g data-edge-from="worker" data-edge-to="store" data-edge-label="persist final state" data-edge-key="7">
<path data-composition-edge-from="worker" data-composition-edge-to="store" data-composition-points="393,494;595,494" d="M 393 494 L 595 494" class="a-emphasis" data-animate="edge" style="--step:7" stroke-width="1.8" marker-end="url(#arrowhead-emphasis)"/>
<g data-detail="context">
- <rect x="438.6" y="474" width="110.8" height="16" rx="3" class="c-mask"/>
- <text x="494" y="484" class="t-backend" font-size="9" text-anchor="middle">persist final state</text>
+ <rect x="425.3" y="474" width="137.39999999999998" height="18" rx="3" class="c-mask"/>
+ <text x="494" y="484" class="t-backend" font-size="11" text-anchor="middle">persist final state</text>
</g>
</g>
<g data-edge-from="worker" data-edge-to="notify" data-edge-label="job.completed" data-edge-key="8">
<path data-composition-edge-from="worker" data-composition-edge-to="notify" data-composition-points="393,566;703,566" d="M 393 566 L 703 566" class="a-dashed" data-animate="edge" style="--step:8" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
<g data-detail="context">
- <rect x="508.2" y="546" width="79.60000000000001" height="16" rx="3" class="c-mask"/>
- <text x="548" y="556" class="t-messagebus" font-size="9" text-anchor="middle">job.completed</text>
+ <rect x="499.1" y="546" width="97.8" height="18" rx="3" class="c-mask"/>
+ <text x="548" y="556" class="t-messagebus" font-size="11" text-anchor="middle">job.completed</text>
</g>
</g>
<g data-edge-from="notify" data-edge-to="client" data-edge-label="signed webhook" data-edge-key="9">
<path data-composition-edge-from="notify" data-composition-edge-to="client" data-composition-points="703,608;69,608" d="M 703 608 L 69 608" class="a-dashed" data-animate="edge" style="--step:9" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
<g data-detail="context">
- <rect x="343.6" y="588" width="84.8" height="16" rx="3" class="c-mask"/>
- <text x="386" y="598" class="t-messagebus" font-size="9" text-anchor="middle">signed webhook</text>
+ <rect x="333.8" y="588" width="104.39999999999999" height="18" rx="3" class="c-mask"/>
+ <text x="386" y="598" class="t-messagebus" font-size="11" text-anchor="middle">signed webhook</text>
</g>
</g>
<g data-edge-from="client" data-edge-to="api" data-edge-label="GET /jobs/:id" data-edge-key="10">
<path data-composition-edge-from="client" data-composition-edge-to="api" data-composition-points="69,650;163,650" d="M 69 650 L 163 650" class="a-default" data-animate="edge" style="--step:10" stroke-width="1.4" marker-end="url(#arrowhead)"/>
<g data-detail="context">
- <rect x="76.19999999999999" y="630" width="79.60000000000001" height="16" rx="3" class="c-mask"/>
- <text x="116" y="640" class="t-backend" font-size="9" text-anchor="middle">GET /jobs/:id</text>
+ <rect x="67.1" y="630" width="97.8" height="18" rx="3" class="c-mask"/>
+ <text x="116" y="640" class="t-backend" font-size="11" text-anchor="middle">GET /jobs/:id</text>
</g>
</g>
<g data-edge-from="api" data-edge-to="store" data-edge-label="read status" data-edge-key="11">
<path data-composition-edge-from="api" data-composition-edge-to="store" data-composition-points="177,692;595,692" d="M 177 692 L 595 692" class="a-default" data-animate="edge" style="--step:11" stroke-width="1.4" marker-end="url(#arrowhead)"/>
<g data-detail="context">
- <rect x="351.4" y="672" width="69.2" height="16" rx="3" class="c-mask"/>
- <text x="386" y="682" class="t-backend" font-size="9" text-anchor="middle">read status</text>
+ <rect x="343.7" y="672" width="84.6" height="18" rx="3" class="c-mask"/>
+ <text x="386" y="682" class="t-backend" font-size="11" text-anchor="middle">read status</text>
</g>
</g>
<g data-edge-from="store" data-edge-to="api" data-edge-label="completed" data-edge-key="12">
<path data-composition-edge-from="store" data-composition-edge-to="api" data-composition-points="595,734;177,734" d="M 595 734 L 177 734" class="a-default" data-animate="edge" style="--step:12" stroke-width="1.4" stroke-dasharray="3,5" marker-end="url(#arrowhead)"/>
<g data-detail="context">
- <rect x="356.6" y="714" width="58.800000000000004" height="16" rx="3" class="c-mask"/>
- <text x="386" y="724" class="t-muted" font-size="9" text-anchor="middle">completed</text>
+ <rect x="350.3" y="714" width="71.4" height="18" rx="3" class="c-mask"/>
+ <text x="386" y="724" class="t-muted" font-size="11" text-anchor="middle">completed</text>
</g>
</g>
<g data-edge-from="api" data-edge-to="client" data-edge-label="200 final result" data-edge-key="13">
<path data-composition-edge-from="api" data-composition-edge-to="client" data-composition-points="163,776;69,776" d="M 163 776 L 69 776" class="a-default" data-animate="edge" style="--step:12" stroke-width="1.4" stroke-dasharray="3,5" marker-end="url(#arrowhead)"/>
<g data-detail="context">
- <rect x="68.4" y="756" width="95.2" height="16" rx="3" class="c-mask"/>
- <text x="116" y="766" class="t-muted" font-size="9" text-anchor="middle">200 final result</text>
+ <rect x="57.2" y="756" width="117.6" height="18" rx="3" class="c-mask"/>
+ <text x="116" y="766" class="t-muted" font-size="11" text-anchor="middle">200 final result</text>
</g>
</g>
diff --git a/docs/gallery/artifacts/cache-miss.sequence.html b/docs/gallery/artifacts/cache-miss.sequence.html
index 47a66b5f..2b53c7c3 100644
--- a/docs/gallery/artifacts/cache-miss.sequence.html
+++ b/docs/gallery/artifacts/cache-miss.sequence.html
@@ -5189,96 +5189,96 @@ OTHER DEALINGS IN THE FONT SOFTWARE.
<g data-edge-from="user" data-edge-to="web" data-edge-label="open page" data-edge-key="0" data-edge-id="open-page">
<path data-composition-edge-from="user" data-composition-edge-to="web" data-composition-edge-id="open-page" data-composition-points="125.5,160;255.66666666666663,160" d="M 125.5 160 L 255.66666666666663 160" class="a-default" data-animate="edge" style="--step:0" stroke-width="1.4" marker-end="url(#arrowhead)"/>
<g data-detail="context">
- <rect x="161.1833333333333" y="140" width="58.800000000000004" height="16" rx="3" class="c-mask"/>
- <text x="190.58333333333331" y="150" class="t-backend" font-size="9" text-anchor="middle">open page</text>
+ <rect x="154.88333333333333" y="140" width="71.4" height="18" rx="3" class="c-mask"/>
+ <text x="190.58333333333331" y="150" class="t-backend" font-size="11" text-anchor="middle">open page</text>
</g>
</g>
<g data-edge-from="web" data-edge-to="api" data-edge-label="GET /dashboard" data-edge-key="1" data-edge-id="dashboard-request">
<path data-composition-edge-from="web" data-composition-edge-to="api" data-composition-edge-id="dashboard-request" data-composition-points="269.66666666666663,185;399.8333333333333,185" d="M 269.66666666666663 185 L 399.8333333333333 185" class="a-emphasis" data-animate="edge" style="--step:1" stroke-width="1.8" marker-end="url(#arrowhead-emphasis)"/>
<g data-detail="context">
- <rect x="292.35" y="165" width="84.8" height="16" rx="3" class="c-mask"/>
- <text x="334.75" y="175" class="t-backend" font-size="9" text-anchor="middle">GET /dashboard</text>
+ <rect x="282.55" y="165" width="104.39999999999999" height="18" rx="3" class="c-mask"/>
+ <text x="334.75" y="175" class="t-backend" font-size="11" text-anchor="middle">GET /dashboard</text>
</g>
</g>
<g data-edge-from="api" data-edge-to="auth" data-edge-label="verify JWT" data-edge-key="2" data-edge-id="verify-jwt">
<path data-composition-edge-from="api" data-composition-edge-to="auth" data-composition-edge-id="verify-jwt" data-composition-points="413.8333333333333,210;544,210" d="M 413.8333333333333 210 L 544 210" class="a-security" data-animate="edge" style="--step:2" stroke-width="1.4" marker-end="url(#arrowhead-security)"/>
<g data-detail="context">
- <rect x="446.91666666666663" y="190" width="64" height="16" rx="3" class="c-mask"/>
- <text x="478.91666666666663" y="200" class="t-security" font-size="9" text-anchor="middle">verify JWT</text>
+ <rect x="439.91666666666663" y="190" width="78" height="18" rx="3" class="c-mask"/>
+ <text x="478.91666666666663" y="200" class="t-security" font-size="11" text-anchor="middle">verify JWT</text>
</g>
</g>
<g data-edge-from="auth" data-edge-to="api" data-edge-label="claims ok" data-edge-key="3" data-edge-id="auth-claims">
<path data-composition-edge-from="auth" data-composition-edge-to="api" data-composition-edge-id="auth-claims" data-composition-points="544,238;413.8333333333333,238" d="M 544 238 L 413.8333333333333 238" class="a-default" data-animate="edge" style="--step:3" stroke-width="1.4" stroke-dasharray="3,5" marker-end="url(#arrowhead)"/>
<g data-detail="context">
- <rect x="449.51666666666665" y="218" width="58.800000000000004" height="16" rx="3" class="c-mask"/>
- <text x="478.91666666666663" y="228" class="t-muted" font-size="9" text-anchor="middle">claims ok</text>
+ <rect x="443.21666666666664" y="218" width="71.4" height="18" rx="3" class="c-mask"/>
+ <text x="478.91666666666663" y="228" class="t-muted" font-size="11" text-anchor="middle">claims ok</text>
</g>
</g>
<g data-edge-from="api" data-edge-to="redis" data-edge-label="read cache" data-edge-key="4" data-edge-id="cache-read">
<path data-composition-edge-from="api" data-composition-edge-to="redis" data-composition-edge-id="cache-read" data-composition-points="413.8333333333333,270;688.1666666666666,270" d="M 413.8333333333333 270 L 688.1666666666666 270" class="a-default" data-animate="edge" style="--step:4" stroke-width="1.4" marker-end="url(#arrowhead)"/>
<g data-detail="context">
- <rect x="519" y="250" width="64" height="16" rx="3" class="c-mask"/>
- <text x="551" y="260" class="t-backend" font-size="9" text-anchor="middle">read cache</text>
+ <rect x="512" y="250" width="78" height="18" rx="3" class="c-mask"/>
+ <text x="551" y="260" class="t-backend" font-size="11" text-anchor="middle">read cache</text>
</g>
</g>
<g data-edge-from="redis" data-edge-to="api" data-edge-label="miss" data-edge-key="5" data-edge-id="cache-miss">
<path data-composition-edge-from="redis" data-composition-edge-to="api" data-composition-edge-id="cache-miss" data-composition-points="688.1666666666666,298;413.8333333333333,298" d="M 688.1666666666666 298 L 413.8333333333333 298" class="a-default" data-animate="edge" style="--step:5" stroke-width="1.4" stroke-dasharray="3,5" marker-end="url(#arrowhead)"/>
<g data-detail="context">
- <rect x="534" y="278" width="34" height="16" rx="3" class="c-mask"/>
- <text x="551" y="288" class="t-muted" font-size="9" text-anchor="middle">miss</text>
+ <rect x="531.8" y="278" width="38.4" height="18" rx="3" class="c-mask"/>
+ <text x="551" y="288" class="t-muted" font-size="11" text-anchor="middle">miss</text>
</g>
</g>
<g data-edge-from="api" data-edge-to="db" data-edge-label="query profile + metrics" data-edge-key="6" data-edge-id="profile-query">
<path data-composition-edge-from="api" data-composition-edge-to="db" data-composition-edge-id="profile-query" data-composition-points="413.8333333333333,330;832.3333333333333,330" d="M 413.8333333333333 330 L 832.3333333333333 330" class="a-emphasis" data-animate="edge" style="--step:6" stroke-width="1.8" marker-end="url(#arrowhead-emphasis)"/>
<g data-detail="context">
- <rect x="557.2833333333333" y="310" width="131.60000000000002" height="16" rx="3" class="c-mask"/>
- <text x="623.0833333333333" y="320" class="t-backend" font-size="9" text-anchor="middle">query profile + metrics</text>
+ <rect x="541.1833333333333" y="310" width="163.79999999999998" height="18" rx="3" class="c-mask"/>
+ <text x="623.0833333333333" y="320" class="t-backend" font-size="11" text-anchor="middle">query profile + metrics</text>
</g>
</g>
<g data-edge-from="db" data-edge-to="api" data-edge-label="rows" data-edge-key="7" data-edge-id="profile-rows">
<path data-composition-edge-from="db" data-composition-edge-to="api" data-composition-edge-id="profile-rows" data-composition-points="832.3333333333333,358;413.8333333333333,358" d="M 832.3333333333333 358 L 413.8333333333333 358" class="a-default" data-animate="edge" style="--step:7" stroke-width="1.4" stroke-dasharray="3,5" marker-end="url(#arrowhead)"/>
<g data-detail="context">
- <rect x="606.0833333333333" y="338" width="34" height="16" rx="3" class="c-mask"/>
- <text x="623.0833333333333" y="348" class="t-muted" font-size="9" text-anchor="middle">rows</text>
+ <rect x="603.8833333333332" y="338" width="38.4" height="18" rx="3" class="c-mask"/>
+ <text x="623.0833333333333" y="348" class="t-muted" font-size="11" text-anchor="middle">rows</text>
</g>
</g>
<g data-edge-from="api" data-edge-to="redis" data-edge-label="set cache" data-edge-key="8" data-edge-id="cache-write">
<path data-composition-edge-from="api" data-composition-edge-to="redis" data-composition-edge-id="cache-write" data-composition-points="413.8333333333333,390;688.1666666666666,390" d="M 413.8333333333333 390 L 688.1666666666666 390" class="a-dashed" data-animate="edge" style="--step:8" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
<g data-detail="context">
- <rect x="521.6" y="370" width="58.800000000000004" height="16" rx="3" class="c-mask"/>
- <text x="551" y="380" class="t-messagebus" font-size="9" text-anchor="middle">set cache</text>
+ <rect x="515.3" y="370" width="71.4" height="18" rx="3" class="c-mask"/>
+ <text x="551" y="380" class="t-messagebus" font-size="11" text-anchor="middle">set cache</text>
</g>
</g>
<g data-edge-from="api" data-edge-to="trace" data-edge-label="emit trace" data-edge-key="9" data-edge-id="trace-emit">
<path data-composition-edge-from="api" data-composition-edge-to="trace" data-composition-edge-id="trace-emit" data-composition-points="413.8333333333333,418;976.5,418" d="M 413.8333333333333 418 L 976.5 418" class="a-dashed" data-animate="edge" style="--step:9" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
<g data-detail="context">
- <rect x="663.1666666666666" y="398" width="64" height="16" rx="3" class="c-mask"/>
- <text x="695.1666666666666" y="408" class="t-messagebus" font-size="9" text-anchor="middle">emit trace</text>
+ <rect x="656.1666666666666" y="398" width="78" height="18" rx="3" class="c-mask"/>
+ <text x="695.1666666666666" y="408" class="t-messagebus" font-size="11" text-anchor="middle">emit trace</text>
</g>
</g>
<g data-edge-from="api" data-edge-to="web" data-edge-label="200 JSON" data-edge-key="10" data-edge-id="dashboard-response">
<path data-composition-edge-from="api" data-composition-edge-to="web" data-composition-edge-id="dashboard-response" data-composition-points="399.8333333333333,443;269.66666666666663,443" d="M 399.8333333333333 443 L 269.66666666666663 443" class="a-default" data-animate="edge" style="--step:10" stroke-width="1.4" stroke-dasharray="3,5" marker-end="url(#arrowhead)"/>
<g data-detail="context">
- <rect x="307.95" y="423" width="53.6" height="16" rx="3" class="c-mask"/>
- <text x="334.75" y="433" class="t-muted" font-size="9" text-anchor="middle">200 JSON</text>
+ <rect x="302.35" y="423" width="64.8" height="18" rx="3" class="c-mask"/>
+ <text x="334.75" y="433" class="t-muted" font-size="11" text-anchor="middle">200 JSON</text>
</g>
</g>
<g data-edge-from="web" data-edge-to="user" data-edge-label="render" data-edge-key="11" data-edge-id="page-render">
<path data-composition-edge-from="web" data-composition-edge-to="user" data-composition-edge-id="page-render" data-composition-points="255.66666666666663,468;125.5,468" d="M 255.66666666666663 468 L 125.5 468" class="a-default" data-animate="edge" style="--step:11" stroke-width="1.4" stroke-dasharray="3,5" marker-end="url(#arrowhead)"/>
<g data-detail="context">
- <rect x="168.98333333333332" y="448" width="43.2" height="16" rx="3" class="c-mask"/>
- <text x="190.58333333333331" y="458" class="t-muted" font-size="9" text-anchor="middle">render</text>
+ <rect x="164.7833333333333" y="448" width="51.599999999999994" height="18" rx="3" class="c-mask"/>
+ <text x="190.58333333333331" y="458" class="t-muted" font-size="11" text-anchor="middle">render</text>
</g>
</g>
diff --git a/docs/gallery/manifest.json b/docs/gallery/manifest.json
index 9c6fd65b..76eea13a 100644
--- a/docs/gallery/manifest.json
+++ b/docs/gallery/manifest.json
@@ -227,8 +227,8 @@
"engineeringProfile": null,
"nodeCount": 7,
"edgeCount": 12,
- "artifactBytes": 813020,
- "artifactSha256": "7c5c8f5c39c10dc8148591f654cd79a05ff49bb70166a4c45607414ca02cbe3a",
+ "artifactBytes": 813024,
+ "artifactSha256": "62fac8cc0bc21c5f9b134d09009fe6fde3a9d756bc3941e9c01be2eaa03b958a",
"sourceBytes": 4374,
"sourceSha256": "9a799a3661c16cd6ab4f6373ff6a04da95a9ab70d93b0a349b668466f4912fd7",
"checks": [
@@ -627,8 +627,8 @@
"engineeringProfile": null,
"nodeCount": 7,
"edgeCount": 14,
- "artifactBytes": 812111,
- "artifactSha256": "8fb45b739efdc45b56f7f9a0cf2f7bf95573d382897198731f4b4b2f33567930",
+ "artifactBytes": 812142,
+ "artifactSha256": "2515889e53c5342e315aa1c39b9a1cf24df4e0026c8aaa46287fa047c933e17c",
"sourceBytes": 4370,
"sourceSha256": "545f20920c89b69c2bb1f15508d5543fddbeb15cffba61e102206e04bd5a5cd9",
"checks": [
diff --git a/docs/specs/readability-layered-reading.md b/docs/specs/readability-layered-reading.md
new file mode 100644
index 00000000..aceff955
--- /dev/null
+++ b/docs/specs/readability-layered-reading.md
@@ -0,0 +1,12 @@
+# Readability and layered reading
+
+Agreed scope: improve default reading quality and let readers move from an overview to explicitly authored detail diagrams. The requesting contributor approved implementation and PR creation. Upstream maintainer acceptance remains pending; submit as Draft for scope review.
+
+## 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.
+- 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.
+- Reject invalid manifests, duplicate identities, missing nodes/files and output/input aliases before replacing output. Bind the receipt to manifest, child bytes and final HTML. Child checks do not claim final browser or perceptual acceptance.
+- Verify through CLI artifacts/diagnostics and real browser behavior. Include a small synthetic, redistributable sequence example; do not publish private task content.
diff --git a/examples/sequence-cache-miss-request.html b/examples/sequence-cache-miss-request.html
index 47a66b5f..2b53c7c3 100644
--- a/examples/sequence-cache-miss-request.html
+++ b/examples/sequence-cache-miss-request.html
@@ -5189,96 +5189,96 @@ OTHER DEALINGS IN THE FONT SOFTWARE.
<g data-edge-from="user" data-edge-to="web" data-edge-label="open page" data-edge-key="0" data-edge-id="open-page">
<path data-composition-edge-from="user" data-composition-edge-to="web" data-composition-edge-id="open-page" data-composition-points="125.5,160;255.66666666666663,160" d="M 125.5 160 L 255.66666666666663 160" class="a-default" data-animate="edge" style="--step:0" stroke-width="1.4" marker-end="url(#arrowhead)"/>
<g data-detail="context">
- <rect x="161.1833333333333" y="140" width="58.800000000000004" height="16" rx="3" class="c-mask"/>
- <text x="190.58333333333331" y="150" class="t-backend" font-size="9" text-anchor="middle">open page</text>
+ <rect x="154.88333333333333" y="140" width="71.4" height="18" rx="3" class="c-mask"/>
+ <text x="190.58333333333331" y="150" class="t-backend" font-size="11" text-anchor="middle">open page</text>
</g>
</g>
<g data-edge-from="web" data-edge-to="api" data-edge-label="GET /dashboard" data-edge-key="1" data-edge-id="dashboard-request">
<path data-composition-edge-from="web" data-composition-edge-to="api" data-composition-edge-id="dashboard-request" data-composition-points="269.66666666666663,185;399.8333333333333,185" d="M 269.66666666666663 185 L 399.8333333333333 185" class="a-emphasis" data-animate="edge" style="--step:1" stroke-width="1.8" marker-end="url(#arrowhead-emphasis)"/>
<g data-detail="context">
- <rect x="292.35" y="165" width="84.8" height="16" rx="3" class="c-mask"/>
- <text x="334.75" y="175" class="t-backend" font-size="9" text-anchor="middle">GET /dashboard</text>
+ <rect x="282.55" y="165" width="104.39999999999999" height="18" rx="3" class="c-mask"/>
+ <text x="334.75" y="175" class="t-backend" font-size="11" text-anchor="middle">GET /dashboard</text>
</g>
</g>
<g data-edge-from="api" data-edge-to="auth" data-edge-label="verify JWT" data-edge-key="2" data-edge-id="verify-jwt">
<path data-composition-edge-from="api" data-composition-edge-to="auth" data-composition-edge-id="verify-jwt" data-composition-points="413.8333333333333,210;544,210" d="M 413.8333333333333 210 L 544 210" class="a-security" data-animate="edge" style="--step:2" stroke-width="1.4" marker-end="url(#arrowhead-security)"/>
<g data-detail="context">
- <rect x="446.91666666666663" y="190" width="64" height="16" rx="3" class="c-mask"/>
- <text x="478.91666666666663" y="200" class="t-security" font-size="9" text-anchor="middle">verify JWT</text>
+ <rect x="439.91666666666663" y="190" width="78" height="18" rx="3" class="c-mask"/>
+ <text x="478.91666666666663" y="200" class="t-security" font-size="11" text-anchor="middle">verify JWT</text>
</g>
</g>
<g data-edge-from="auth" data-edge-to="api" data-edge-label="claims ok" data-edge-key="3" data-edge-id="auth-claims">
<path data-composition-edge-from="auth" data-composition-edge-to="api" data-composition-edge-id="auth-claims" data-composition-points="544,238;413.8333333333333,238" d="M 544 238 L 413.8333333333333 238" class="a-default" data-animate="edge" style="--step:3" stroke-width="1.4" stroke-dasharray="3,5" marker-end="url(#arrowhead)"/>
<g data-detail="context">
- <rect x="449.51666666666665" y="218" width="58.800000000000004" height="16" rx="3" class="c-mask"/>
- <text x="478.91666666666663" y="228" class="t-muted" font-size="9" text-anchor="middle">claims ok</text>
+ <rect x="443.21666666666664" y="218" width="71.4" height="18" rx="3" class="c-mask"/>
+ <text x="478.91666666666663" y="228" class="t-muted" font-size="11" text-anchor="middle">claims ok</text>
</g>
</g>
<g data-edge-from="api" data-edge-to="redis" data-edge-label="read cache" data-edge-key="4" data-edge-id="cache-read">
<path data-composition-edge-from="api" data-composition-edge-to="redis" data-composition-edge-id="cache-read" data-composition-points="413.8333333333333,270;688.1666666666666,270" d="M 413.8333333333333 270 L 688.1666666666666 270" class="a-default" data-animate="edge" style="--step:4" stroke-width="1.4" marker-end="url(#arrowhead)"/>
<g data-detail="context">
- <rect x="519" y="250" width="64" height="16" rx="3" class="c-mask"/>
- <text x="551" y="260" class="t-backend" font-size="9" text-anchor="middle">read cache</text>
+ <rect x="512" y="250" width="78" height="18" rx="3" class="c-mask"/>
+ <text x="551" y="260" class="t-backend" font-size="11" text-anchor="middle">read cache</text>
</g>
</g>
<g data-edge-from="redis" data-edge-to="api" data-edge-label="miss" data-edge-key="5" data-edge-id="cache-miss">
<path data-composition-edge-from="redis" data-composition-edge-to="api" data-composition-edge-id="cache-miss" data-composition-points="688.1666666666666,298;413.8333333333333,298" d="M 688.1666666666666 298 L 413.8333333333333 298" class="a-default" data-animate="edge" style="--step:5" stroke-width="1.4" stroke-dasharray="3,5" marker-end="url(#arrowhead)"/>
<g data-detail="context">
- <rect x="534" y="278" width="34" height="16" rx="3" class="c-mask"/>
- <text x="551" y="288" class="t-muted" font-size="9" text-anchor="middle">miss</text>
+ <rect x="531.8" y="278" width="38.4" height="18" rx="3" class="c-mask"/>
+ <text x="551" y="288" class="t-muted" font-size="11" text-anchor="middle">miss</text>
</g>
</g>
<g data-edge-from="api" data-edge-to="db" data-edge-label="query profile + metrics" data-edge-key="6" data-edge-id="profile-query">
<path data-composition-edge-from="api" data-composition-edge-to="db" data-composition-edge-id="profile-query" data-composition-points="413.8333333333333,330;832.3333333333333,330" d="M 413.8333333333333 330 L 832.3333333333333 330" class="a-emphasis" data-animate="edge" style="--step:6" stroke-width="1.8" marker-end="url(#arrowhead-emphasis)"/>
<g data-detail="context">
- <rect x="557.2833333333333" y="310" width="131.60000000000002" height="16" rx="3" class="c-mask"/>
- <text x="623.0833333333333" y="320" class="t-backend" font-size="9" text-anchor="middle">query profile + metrics</text>
+ <rect x="541.1833333333333" y="310" width="163.79999999999998" height="18" rx="3" class="c-mask"/>
+ <text x="623.0833333333333" y="320" class="t-backend" font-size="11" text-anchor="middle">query profile + metrics</text>
</g>
</g>
<g data-edge-from="db" data-edge-to="api" data-edge-label="rows" data-edge-key="7" data-edge-id="profile-rows">
<path data-composition-edge-from="db" data-composition-edge-to="api" data-composition-edge-id="profile-rows" data-composition-points="832.3333333333333,358;413.8333333333333,358" d="M 832.3333333333333 358 L 413.8333333333333 358" class="a-default" data-animate="edge" style="--step:7" stroke-width="1.4" stroke-dasharray="3,5" marker-end="url(#arrowhead)"/>
<g data-detail="context">
- <rect x="606.0833333333333" y="338" width="34" height="16" rx="3" class="c-mask"/>
- <text x="623.0833333333333" y="348" class="t-muted" font-size="9" text-anchor="middle">rows</text>
+ <rect x="603.8833333333332" y="338" width="38.4" height="18" rx="3" class="c-mask"/>
+ <text x="623.0833333333333" y="348" class="t-muted" font-size="11" text-anchor="middle">rows</text>
</g>
</g>
<g data-edge-from="api" data-edge-to="redis" data-edge-label="set cache" data-edge-key="8" data-edge-id="cache-write">
<path data-composition-edge-from="api" data-composition-edge-to="redis" data-composition-edge-id="cache-write" data-composition-points="413.8333333333333,390;688.1666666666666,390" d="M 413.8333333333333 390 L 688.1666666666666 390" class="a-dashed" data-animate="edge" style="--step:8" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
<g data-detail="context">
- <rect x="521.6" y="370" width="58.800000000000004" height="16" rx="3" class="c-mask"/>
- <text x="551" y="380" class="t-messagebus" font-size="9" text-anchor="middle">set cache</text>
+ <rect x="515.3" y="370" width="71.4" height="18" rx="3" class="c-mask"/>
+ <text x="551" y="380" class="t-messagebus" font-size="11" text-anchor="middle">set cache</text>
</g>
</g>
<g data-edge-from="api" data-edge-to="trace" data-edge-label="emit trace" data-edge-key="9" data-edge-id="trace-emit">
<path data-composition-edge-from="api" data-composition-edge-to="trace" data-composition-edge-id="trace-emit" data-composition-points="413.8333333333333,418;976.5,418" d="M 413.8333333333333 418 L 976.5 418" class="a-dashed" data-animate="edge" style="--step:9" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
<g data-detail="context">
- <rect x="663.1666666666666" y="398" width="64" height="16" rx="3" class="c-mask"/>
- <text x="695.1666666666666" y="408" class="t-messagebus" font-size="9" text-anchor="middle">emit trace</text>
+ <rect x="656.1666666666666" y="398" width="78" height="18" rx="3" class="c-mask"/>
+ <text x="695.1666666666666" y="408" class="t-messagebus" font-size="11" text-anchor="middle">emit trace</text>
</g>
</g>
<g data-edge-from="api" data-edge-to="web" data-edge-label="200 JSON" data-edge-key="10" data-edge-id="dashboard-response">
<path data-composition-edge-from="api" data-composition-edge-to="web" data-composition-edge-id="dashboard-response" data-composition-points="399.8333333333333,443;269.66666666666663,443" d="M 399.8333333333333 443 L 269.66666666666663 443" class="a-default" data-animate="edge" style="--step:10" stroke-width="1.4" stroke-dasharray="3,5" marker-end="url(#arrowhead)"/>
<g data-detail="context">
- <rect x="307.95" y="423" width="53.6" height="16" rx="3" class="c-mask"/>
- <text x="334.75" y="433" class="t-muted" font-size="9" text-anchor="middle">200 JSON</text>
+ <rect x="302.35" y="423" width="64.8" height="18" rx="3" class="c-mask"/>
+ <text x="334.75" y="433" class="t-muted" font-size="11" text-anchor="middle">200 JSON</text>
</g>
</g>
<g data-edge-from="web" data-edge-to="user" data-edge-label="render" data-edge-key="11" data-edge-id="page-render">
<path data-composition-edge-from="web" data-composition-edge-to="user" data-composition-edge-id="page-render" data-composition-points="255.66666666666663,468;125.5,468" d="M 255.66666666666663 468 L 125.5 468" class="a-default" data-animate="edge" style="--step:11" stroke-width="1.4" stroke-dasharray="3,5" marker-end="url(#arrowhead)"/>
<g data-detail="context">
- <rect x="168.98333333333332" y="448" width="43.2" height="16" rx="3" class="c-mask"/>
- <text x="190.58333333333331" y="458" class="t-muted" font-size="9" text-anchor="middle">render</text>
+ <rect x="164.7833333333333" y="448" width="51.599999999999994" height="18" rx="3" class="c-mask"/>
+ <text x="190.58333333333331" y="458" class="t-muted" font-size="11" text-anchor="middle">render</text>
</g>
</g>