Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.
HTML agent-skillsai-agentsarchitecture-diagramclaude-codeclaude-skillscodexcoding-agentsdeepseek-harnessdeveloper-toolsdiagramsdiagrams-as-codedsh-pluginflowchartllmmermaidopencodesequence-diagramsoftware-architecturesystem-designvisualization
feat: improve sequence readability and add explicit layered reading
WangHaoc840ce430ebc
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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.### Fixeddiff --git a/README.md b/README.mdindex 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.mdindex 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.mdindex 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.zipindex 1b21ad02..13ef23f5 100644Binary files a/archify.zip and b/archify.zip differdiff --git a/archify/assets/atlas.html b/archify/assets/atlas.htmlnew file mode 100644index 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.mjsindex 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.mjsnew file mode 100644index 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.mjsindex 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.htmlindex 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.mdindex 301d7df7..9f4ab0c9 100644--- a/archify/references/delivery-contract.md+++ b/archify/references/delivery-contract.md@@ -118,3 +118,7 @@ correction_rounds: 0|1|2Derive `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.mdnew file mode 100644index 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.jsonnew file mode 100644index 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.mjsindex 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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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.mjsindex 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.htmlindex 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&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&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.htmlindex 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.htmlindex 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.jsonindex 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.mdnew file mode 100644index 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.htmlindex 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>