Skip to content

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

revert(atlas): defer layered reading while retaining sequence readability

tt-a1ibe5ddfbb3493
diff --git a/CHANGELOG.md b/CHANGELOG.md
index cc56462a..1d9fae2b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,7 +7,6 @@ All notable changes are documented here. Format loosely follows [Keep a Changelo
### Improved reading
- Showcase sequence message names use larger primary type and matching label plates; real browser readability checks now include message labels.
-- Optional `atlas` packages checked overview/detail HTML with explicit node links, keyboard navigation, preserved overview position, synchronized themes and artifact fingerprints. Browser and perceptual acceptance remain separate.
> Development identity: `v2.17.0-dev.1`. Not a stable release.
diff --git a/README.md b/README.md
index 833221ec..5f241a2c 100644
--- a/README.md
+++ b/README.md
@@ -273,7 +273,6 @@ Generation and Viewer contracts: [`archify/SKILL.md`](archify/SKILL.md).
- [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)
- [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 833221ec..5f241a2c 100644
--- a/README_EN.md
+++ b/README_EN.md
@@ -273,7 +273,6 @@ Generation and Viewer contracts: [`archify/SKILL.md`](archify/SKILL.md).
- [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)
- [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 a07fb29b..d1d952ad 100644
--- a/README_ZH.md
+++ b/README_ZH.md
@@ -272,7 +272,7 @@ Claude.ai 中的上传入口:
- [Schema 说明](archify/schemas/README.md)
- [Skill 与 Renderer 契约](archify/SKILL.md)
-- [示例](archify/examples/) · [分层阅读](archify/references/layered-reading.md):离线总览与显式细节关联。
+- [示例](archify/examples/)
- [Agent 编图手册](docs/authoring-cookbook.zh-CN.md) · [English](docs/authoring-cookbook.md)
- [版本历史](CHANGELOG.md)
- [路线图](ROADMAP.md)
diff --git a/archify.zip b/archify.zip
index 72fc7abb..e8d5ae6c 100644
Binary files a/archify.zip and b/archify.zip differ
diff --git a/archify/SKILL.md b/archify/SKILL.md
index 72a93f09..d74b0b47 100644
--- a/archify/SKILL.md
+++ b/archify/SKILL.md
@@ -130,8 +130,6 @@ node bin/archify.mjs preview <type> <input>.json <output>.html --quality showcas
Never start preview by default. Read `references/delivery-contract.md` when using preview, repository evidence, export receipts, visual review, or post-delivery opening.
-For separately authored overview/detail diagrams, read [layered reading](references/layered-reading.md) and use its explicit atlas manifest. Prefer existing Focus, Views and Story when one topology can explain the detail.
-
## Optional viewer capabilities
Generated HTML already contains theme switching, pan/zoom, search, focus, relationship tracing, semantic views, presentation, and truthful exports. These are reader capabilities, not extra authoring work. `meta.animation: "trace"` is opt-in; `meta.views` is optional and should contain at most five curated chapters.
diff --git a/archify/assets/atlas.html b/archify/assets/atlas.html
deleted file mode 100644
index dd9ef5d1..00000000
--- a/archify/assets/atlas.html
+++ /dev/null
@@ -1,312 +0,0 @@
-<!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 "JetBrains Mono", ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
- }
- #diagrams {
- position: absolute;
- inset: 0 0 44px;
- }
- iframe {
- position: absolute;
- inset: 0;
- width: 100%;
- height: 100%;
- border: 0;
- }
- iframe[hidden] {
- display: none;
- }
- nav {
- position: fixed;
- bottom: 4px;
- left: 12px;
- z-index: 2;
- display: flex;
- gap: 8px;
- padding: 4px;
- background: var(--bg);
- border: 1px solid var(--line);
- border-radius: 8px;
- max-width: calc(100% - 24px);
- }
- button {
- font: inherit;
- font-size: 13px;
- cursor: pointer;
- color: var(--ink);
- background: var(--bg);
- border: 1px solid var(--line);
- border-radius: 5px;
- padding: 6px 10px;
- }
- 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 {
- #diagrams { inset: 0; }
- 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 5278ffb1..78451fe0 100755
--- a/archify/bin/archify.mjs
+++ b/archify/bin/archify.mjs
@@ -663,7 +663,6 @@ function usage() {
archify preview <type> <input.json> [output.html] [--no-open] [--quality standard|showcase] [--repo-root path]
archify validate <type> <input.json> [--json] [--layout-json] [--quality standard|showcase] [--repo-root path]
archify migrate workflow <old.json> <new.json> --to-schema 2 [--json] [--repo-root path]
- archify atlas <manifest.json> <output.html> [--json]
archify inspect <type> <input.json>
archify check <output.html> [--require-provenance]
archify visual-check <output.html> [--json] [--require-provenance] [--out-dir <dir>]
@@ -3296,9 +3295,6 @@ 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
deleted file mode 100644
index 3a7bdb7c..00000000
--- a/archify/bin/atlas.mjs
+++ /dev/null
@@ -1,205 +0,0 @@
-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";
-import { resolveOutputPath } from "../renderers/shared/output-path.mjs";
-
-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);
-}
-
-export function buildAtlas(input, output) {
- const inputPath = fs.realpathSync(input),
- outputPath = resolveOutputPath({ requestedOutput: output, inputPaths: [inputPath] }).outputPath;
- 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 });
- const outputRequest = { requestedOutput: outputPath, inputPaths: inputs };
- resolveOutputPath(outputRequest);
- 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);
- resolveOutputPath(outputRequest);
- 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 || error.archifyDiagnostics?.[0] || {
- 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/references/delivery-contract.md b/archify/references/delivery-contract.md
index e0261ddf..1c4bf83c 100644
--- a/archify/references/delivery-contract.md
+++ b/archify/references/delivery-contract.md
@@ -277,7 +277,3 @@ 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
deleted file mode 100644
index 3fdbf99b..00000000
--- a/archify/references/layered-reading.md
+++ /dev/null
@@ -1,54 +0,0 @@
-# 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
deleted file mode 100644
index 926b47ed..00000000
--- a/archify/references/request-reading.atlas.json
+++ /dev/null
@@ -1,10 +0,0 @@
-{
- "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/test/atlas-browser.test.mjs b/archify/test/atlas-browser.test.mjs
deleted file mode 100644
index b73fd31b..00000000
--- a/archify/test/atlas-browser.test.mjs
+++ /dev/null
@@ -1,242 +0,0 @@
-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 = Object.hasOwn(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(`${frame}.getBoundingClientRect().bottom <= document.querySelector('nav').getBoundingClientRect().top`),
- true,
- "atlas navigation must not cover child reading content",
- );
- 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,
- JSON.stringify(await evaluate(`(()=>{const w=${frame}.contentWindow,d=w.document.documentElement;return {width:innerWidth,height:innerHeight,child:[w.innerWidth,w.innerHeight,d.scrollWidth,d.scrollHeight],overflow:d.dataset.readerOverflow}})()`)),
- );
- }
- await evaluate(`${frame}.contentWindow.Archify.exportMenu.run('svg')`);
- assert.equal(await evaluate(`${frame}.contentDocument.documentElement.getAttribute('data-last-export-canonical')`), 'true');
- assert.equal(await evaluate(`${frame}.contentDocument.documentElement.getAttribute('data-last-export-format')`), 'svg');
- assert.ok(await evaluate(`${frame}.contentDocument.querySelectorAll('span[data-atlas-icon] svg').length`) > 0);
- if (process.env.ARCHIFY_READING_EVIDENCE) {
- fs.mkdirSync(process.env.ARCHIFY_READING_EVIDENCE, { recursive: true });
- for (const mode of ["light", "dark"]) {
- 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.
- const original = fs.readFileSync(child, "utf8");
- const unreadable = original.replace(
- /(<text[^>]*class="t-backend"[^>]*font-size=")11("[^>]*>)/g,
- "$13$2",
- );
- assert.notEqual(unreadable, original, "the negative fixture must shrink message text");
- fs.writeFileSync(child, unreadable);
- 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
deleted file mode 100644
index 9f0429d0..00000000
--- a/archify/test/atlas.test.mjs
+++ /dev/null
@@ -1,96 +0,0 @@
-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);
-});
-
-test('atlas preserves non-HTML targets and uses shared path diagnostics', (t) => {
- const { run, output } = setup(t);
- const target = path.join(path.dirname(output), 'existing.json');
- fs.writeFileSync(target, '{"keep":true}');
- const direct = run(target);
- assert.equal(direct.status, 1);
- assert.equal(direct.receipt.diagnostics[0].code, 'output/cli-extension');
- fs.symlinkSync(target, output);
- const linked = run();
- assert.equal(linked.status, 1);
- assert.equal(linked.receipt.diagnostics[0].code, 'output/cli-resolved-extension');
- assert.equal(fs.readFileSync(target, 'utf8'), '{"keep":true}');
-});
diff --git a/docs/reading-evidence/README.md b/docs/reading-evidence/README.md
index 1a830c1e..825ca27b 100644
--- a/docs/reading-evidence/README.md
+++ b/docs/reading-evidence/README.md
@@ -1,5 +1,7 @@
# Reading evidence
+> Historical proposal/evidence: Atlas is deferred and is not included in the current Skill or CLI. Atlas paths and commands below describe the earlier implementation; they are not current usage instructions. Sequence readability improvements remain enabled.
+
Comparison base: `10722002bb8777ecb639d93c49586fae4adf3ae4`.
The fixed input is `archify/examples/cache-miss-request.sequence.json`.
diff --git a/docs/reading-evidence/merge-2026-09-11.md b/docs/reading-evidence/merge-2026-09-11.md
index 4271f513..f3050c7a 100644
--- a/docs/reading-evidence/merge-2026-09-11.md
+++ b/docs/reading-evidence/merge-2026-09-11.md
@@ -1,5 +1,7 @@
# Main integration verification — 2026-09-11
+> Historical proposal/evidence: Atlas is deferred and is not included in the current Skill or CLI. Atlas paths and commands below describe the earlier implementation; they are not current usage instructions. Sequence readability improvements remain enabled.
+
Integrated upstream `8c3af8a11318d3e0f46bb123149c4863d358f830` into PR #362,
retaining the original `43abaa4` commits. Upstream extracts Viewer maintenance
sources into `viewer/` and refreshes sponsor content. The PR's atlas runtime,
diff --git a/docs/specs/readability-layered-reading.md b/docs/specs/readability-layered-reading.md
index cfdd6f80..51464a59 100644
--- a/docs/specs/readability-layered-reading.md
+++ b/docs/specs/readability-layered-reading.md
@@ -1,5 +1,7 @@
# Readability and layered reading
+> Historical proposal/evidence: Atlas is deferred and is not included in the current Skill or CLI. Atlas paths and commands below describe the earlier implementation; they are not current usage instructions. Sequence readability improvements remain enabled.
+
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
diff --git a/scripts/run-browser-tests.mjs b/scripts/run-browser-tests.mjs
index 838b837f..b9f84e36 100644
--- a/scripts/run-browser-tests.mjs
+++ b/scripts/run-browser-tests.mjs
@@ -9,7 +9,6 @@ const skillRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..
// Shared by PR CI and tag releases. WebM decoding stays in test:webm.
const testFiles = [
'desktop-reader-browser.test.mjs',
- 'atlas-browser.test.mjs',
'reader-layout-browser.test.mjs',
'sequence-header-clearance.test.mjs',
'lifecycle-rail-browser.test.mjs',