# Changelog All notable changes are documented here. Format loosely follows [Keep a Changelog](https://keepachangelog.com/). ## [Unreleased] ### Added - **Exact-ID Architecture Delta Review Navigator.** Every validated Architecture Delta proof now keeps a compact Overview / Previous / Review / Next strip above the unchanged three-state canvas and turns its deterministic authored-change list into native exact-ID controls. Selecting a component, relationship, or boundary highlights only matching `data-node-id`, `data-edge-id`, or derived boundary identity; one deliberate Review activation advances through the same stable order once at 1400ms per change, never loops, and yields to manual navigation, view changes, page hiding, print, or dynamic reduced motion. Generation and runtime validators require one unambiguous primary identity with the receipt's exact state and classification, otherwise the navigator fails closed while the static Before / Delta / After proof remains usable. Roving keyboard navigation, Overview/Escape cleanup, dark/light and all three presets add no URL, history, storage, schema, comparator inference, dependency, GitHub integration, risk claim, or mobile product surface. - **Architecture Delta / PR Proof.** The zero-dependency CLI now exposes `archify compare architecture [output.html] --json`: it validates both snapshots independently, pairs components and relationships only by authored stable IDs, classifies semantic, evidence, scope, topology, geometry, provenance, and presentation changes separately, and emits deterministic Before / Delta / After HTML plus a complete machine receipt. Removed nodes and relationships retain baseline geometry, moved nodes keep a `MOVE FROM` phantom, endpoint changes show old and new routes, and `+ / ~ / − / ↔` plus line patterns keep meaning independent of color or motion. Formatting, object-key, entity-order, `wraps`, and `sources` set changes preserve the semantic hash and artifact bytes; failures preserve the previous artifact. Repository mismatches, zero shared component IDs, missing relationship IDs, and ambiguous boundary keys fail closed. The proof says `AUTHORED SNAPSHOTS` or, after both repository-evidence gates pass, `REVISION-PINNED INPUTS`; it never claims risk, blast radius, safety, mergeability, or verified PR impact. No sixth diagram type, GitHub API, Git ref parser, LLM, Graphviz, hosted service, dependency, telemetry, or mobile product surface was added. - **Deployment Ownership Engineering Profile.** Architecture diagrams may opt into `meta.engineering_profile: "deployment-ownership"` when the user explicitly wants a fail-closed deployment review. The zero-dependency loader then requires named owners for every non-external component, exactly one region per workload, region and security-group boundaries, private placement for every database, one shared region per security group, and a real label for every connection that changes region/security-group membership. Human and JSON validate/deliver receipts name the passing profile; failures use stable diagnostic codes, exact subjects, evidence, and supported repairs. The Production Deployment proof now exercises the contract and publishes one compact Gallery receipt. The committed ZIP smoke is shared by Ubuntu, macOS, and Windows and runs doctor, all five validators, the deployment render/check path, atomic delivery, open fallback, and an invalid-schema rejection without installing dependencies. Profile-less v1 inputs remain unchanged, and the profile does not infer facts or claim repository/live-environment verification. No new renderer, diagram type, visual preset, dependency, hosted service, telemetry, or mobile product surface was added. - **First-class Cursor onboarding.** README EN/ZH, the landing quick start, and the generated Start surface now name Cursor beside Codex, Claude Code, and OpenCode while keeping one portable `archify/SKILL.md`. The Start page adds a URL-stable, keyboard-operable agent selector that produces explicit global and repository-local `skills` CLI commands with bounded scope and copy mode; it does not advertise the unsupported `skills use --agent cursor` launcher or promise one physical global directory. A pinned `skills@1.5.20` canary verifies the canonical `.agents/skills/archify` package path, `doctor`, and all five zero-dependency validators. A fresh Cursor Agent CLI `2026.07.20-8cc9c0b` session then discovered that Skill, ran doctor, authored six-component typed Architecture JSON, and delivered a 9/9-check showcase artifact; independent browser review confirmed the main and failure paths, authored chapter, and zero console warnings/errors. No Cursor-only Skill, renderer, schema, hosted service, telemetry, or mobile surface was added. - **Structured Repair Receipt.** `archify validate --json` and `archify deliver --json` now return exactly one versioned JSON object on both success and failure. Each failure carries additive `diagnostics[]` with a stable rule code, severity, exact subject, measured evidence, and only renderer-supported repairs for input parsing, schema, repository evidence, Clean Flow, composition, artifact checks, and delivery stages; unclassified internal failures are explicit and offer no guessed fix. Human CLI and Last-Good Preview format the same facts without exposing Node stacks, while Atomic Verified Delivery still removes the candidate and preserves the prior artifact byte-for-byte. Five-mode schema fixtures, validate/deliver Clean Flow parity, evidence failure, checker failure, installed-skill smoke, and the existing two-round perceptual boundary are covered. No auto-fix, LLM call, retry expansion, schema/IR change, renderer geometry change, viewer panel, dependency, hosted service, telemetry, or mobile surface was added. - **Reach Share Card.** An active Upstream or Downstream Authored Reachability result now reveals one contextual **Export → Reach Share Card** item. It copies the already resolved origin, direction, stable node/edge identity, minimum depths, and maximum hops without rerunning traversal, then applies only static `data-share-reach-*` decoration to a finite canonical clone before producing a 1200×630 PNG. The full diagram remains as dimmed context; the header names `Authored upstream/downstream`, origin, nodes, links, and hops; upstream uses repository violet, downstream uses proof green, and Blueprint stays filter-free. Missing, empty, stale, duplicate, conflicting, or tampered state fails closed. The truthful receipt uses `format=share-card`, `variant=reach`, `canonical=false`, and a dedicated reach-state-clean proof. Ordinary exports remain canonical. This is download-only and adds no schema, parser, traversal, format, panel, toolbar control, dependency, network, storage, hosted service, geometry change, or mobile product surface. - **Authored Reachability.** A focused node's existing Semantic Passport now offers compact `Upstream` and `Downstream` actions that reveal the deterministic transitive closure of authored relationships, report matched nodes, links, and maximum hops, and round-trip through `#focus=&reach=upstream|downstream` plus Copy link. The viewer deduplicates parallel SVG fragments by stable edge key, terminates cycles, preserves authored DOM order, supports keyboard and browser-history navigation, and remains legible across Classic, Signal Flow, Blueprint, dark, and light. SVG, raster, Share Card, WebM backgrounds, and print strip the temporary state. This is explicitly authored reachability—not blast radius, breakage, repository impact, or runtime causality—and adds no parser, crawler, schema, panel, permanent toolbar action, dependency, hosted runtime, storage, geometry change, or mobile product surface. - **Verified Source Beacons.** Evidence-backed Architecture nodes now show one quiet viewer-only `SRC n` marker derived exclusively from the already verified repository payload. The node remains the single focus target and opens the existing Semantic Passport; screen-reader labels disclose the count, focus/routes/stories/guided views keep one coherent node state, and Classic, Signal Flow, Blueprint, dark, and light reuse the same proof-green vocabulary. Ordinary artifacts remain unchanged, while SVG, raster, Share Card, and WebM backgrounds strip the marker and restore the canonical node label. No parser, crawler, inferred relationship, panel, toolbar control, schema expansion, dependency, hosted runtime, or mobile product surface was added. - **Revision-verified Repository Evidence Passport.** Architecture diagrams can opt into public GitHub source links by declaring a repository URL, a full commit SHA, and one to three repo-relative sources per component, then passing `--repo-root` to `render`, `deliver`, `preview`, or `validate`. Archify verifies the local origin, commit, blobs, and optional line ranges before publishing; verified links appear in Semantic Passport and Node Finder while staying outside the canonical SVG and every visual export. Plain diagrams remain the default, other diagram modes reject the option, and private or unpinned evidence is deliberately out of scope. ### Fixed - Architecture Delta now preflights the HTML and receipt destinations as one pair, backs up both existing regular files, and restores the pair if either commit fails. A blocked receipt target can no longer report failure after silently replacing the previous trusted HTML. - The landing Live Proof now runs in a least-privilege script-only sandbox and starts its bounded chapter in the artifact's first load. This removes parent/child DOM reach-through and avoids a browser-visible `MutationObserver.observe(null)` injection race while preserving one-shot and reduced-motion behavior. - Existing custom templates remain compatible when repository evidence is unused; only the opt-in evidence path requires the new HTML payload slot. Evidence paths reject control characters, and line verification no longer treats a trailing newline as an extra source line. ## [2.12.0] — 2026-07-23 ### Added - **Real-repository proof.** A source-backed MCO runtime case now maps the public `mco-org/mco` repository at commit `9f1a1cf` into a validated, interactive architecture artifact with three guided views and a checked 1200×630 Share Card. Every README links the exact typed source and live GitHub Pages artifact so the core promise is demonstrated on code rather than a prompt-only mockup. - **Last-Good Live Preview.** The zero-dependency CLI now exposes `archify preview [output.html]` for an explicit desktop authoring loop. A random `127.0.0.1` status shell watches one named JSON source with content-digest polling plus bounded event debounce, snapshots each stable generation's exact bytes, runs that immutable input through the existing renderer, composition gates, artifact checker, and SHA-256 receipt, then rechecks the named source digest at the atomic commit point so only the latest passing artifact can reload. Invalid, deleted, half-written, failed, or superseded candidates keep the prior verified diagram visible and byte-identical while reporting the real generation and failure stage; repairs recover automatically, identical source bytes do not rebuild, and identical artifact bytes do not reload. The server rejects external Host values, arbitrary paths, and write methods; canonical future-path checks prevent input/output aliasing; `--no-open` supports tests or manual URL handoff; SIGINT/SIGTERM allow a bounded graceful drain, terminate a stuck delivery, and then remove the loopback server and private same-directory staging directory. All five renderers and an installed ZIP without `node_modules` are covered. Preview state never enters the self-contained HTML or any canonical export, and no schema, renderer, layout, viewer runtime, dependency, hosted network, storage, or mobile product surface changed. - **Route Share Card export.** A resolved Route Probe now reveals one contextual **Export → Route Share Card** item that downloads the exact shortest authored path as a 1200×630 PNG while retaining the complete diagram as dimmed context. The exporter consumes Route Probe's ordered node list and stable edge keys directly, applies only static `data-share-route-*` decoration to a finite canonical clone, and never re-runs pathfinding or carries Journey position, motion overlay, camera, Focus, Lens, or Story state. Clear, unreachable, stale, duplicate, and conflicting snapshots fail closed; five-renderer and parallel-edge browser smoke prove exact route identity, full-context retention, PNG pixels, and Journey-state invariance. The receipt remains `format=share-card`, adds `variant=route`, reports `canonical=false` plus `route-state-clean=true`, and the next ordinary export clears the variant. The first slice is download-only and adds no format, schema, layout, dependency, URL, storage, or mobile product surface. - **Clean Label Gate.** Relationship label masks are now measured against every other authored relationship route across all five typed renderers and again in the final HTML checker. `standard` records sub-2px clearance as an exact warning, while `showcase` rejects sub-4px clearance before write and at delivery with both relationship identities, the hit segment, label rectangle, measured distance, threshold, and supported repair controls. A label's own path fragments remain exempt, but shared source/target fan-out does not hide another route. The one real Event Stream collision moved to a clear authored label position, and Proof Lab now publishes 99/99 checks with zero label-route debt. No auto-layout, route rewrite, schema, viewer, export, dependency, or mobile surface was added. - **Copy Share Card.** The Export menu can now copy the existing canonical 1200×630 Share Card directly as `image/png`, reusing one rasterization promise and preserving the current theme, preset, full-diagram containment, and cleanup contract. A successful clipboard write records the same exact dimensions, bytes, and canonical receipt as download. Unsupported image clipboard APIs disable only the copy action; Share Card download and full-diagram Copy PNG remain unchanged. Real Chrome smoke coverage reads back the copied PNG signature and dimensions without adding a toolbar button, dependency, server, storage, schema, layout, or mobile surface. - **Verified Open.** `archify deliver ... --open` now hands the exact committed absolute HTML path to the native macOS, Linux, or Windows opener only after render, artifact checks, receipt creation, and atomic replacement succeed. The option is off by default, uses bounded argument arrays without shell interpolation, and never runs on a failed delivery. Missing, unsupported, timed-out, or failed openers leave the verified artifact successful, add a truthful `open.status` to the one-object JSON receipt, and print the manual absolute path to stderr. No viewer, server, watcher, dependency, network, storage, schema, renderer, layout, export, or mobile surface was added. - **Share Card export.** Every ordinary artifact can now export one canonical 1200×630 PNG for README, release, social, and launch previews. The fixed card chrome fits title and subtitle while the full diagram uses contain-only placement without cropping, preserves the current theme and visual preset, and reuses canonical cleanup so temporary viewer state never enters the image. Exact dimensions, bytes, filename, and canonical state are recorded without claiming validation. Wide-architecture and tall-sequence pixel smoke tests reject blank or malformed cards. - **Atomic Verified Delivery.** The zero-dependency CLI now exposes `archify deliver [output.html]`: it renders into a unique candidate beside the target, runs the complete artifact and composition checks, computes an exact byte count and SHA-256 receipt, and atomically replaces the target only after every deterministic gate passes. `--json` returns stable success or input/prepare/render/check/receipt/commit failure facts for agents and CI. Any failure removes the candidate and preserves the previous artifact byte-for-byte. Existing `render`, `validate`, and `check` behavior remains available for iteration and diagnosis; no schema, renderer, layout, viewer, dependency, network, storage, export, or mobile surface changed. The ZIP builder now also resolves caller-relative output paths before entering its temporary staging directory, and CI exercises that exact packaged path. - **Live Visual Style Try-on.** Every generated artifact now exposes one compact `Style` control and S shortcut that cycles the existing Classic, Signal Flow, and Blueprint presets over the exact same authored topology. The page and canonical SVG update together, so an explicit reader choice reaches PNG/JPEG/WebP/SVG/WebM export without moving a node or relationship. The authored preset remains the reload default; no preference, URL, source JSON, schema, layout, dependency, fourth style, or dedicated mobile surface is added, and passive embeds/print remain control-free. A same-topology regression proves canonical SVG geometry is identical across all three presets. - **Ambiguous Relationship Corridor Gate.** Unrelated relationships that overlap along the same orthogonal lane for at least 8px now produce exact `composition/ambiguous-corridor` evidence instead of silently reading as a false merge or branch. `standard` keeps dense engineering diagrams renderable and records the finding as a warning; `showcase` rejects it before write and in the final artifact check. Relationships sharing a semantic endpoint, point touches, and shorter overlaps remain legal. Two canonical outer-rail routes were repaired without heuristic rerouting, all five renderers share the same detector, and Proof Lab grows to 88/88 checks with zero corridor debt. - **Artifact-to-install start loop.** The existing viewer footer now offers one restrained, viewer-only `Create yours` link carrying only the typed diagram mode and suppressing its document referrer. A focused bilingual `/start` page turns that mode into canonical install commands, one exact bounded prompt, required evidence, and a verified Proof Lab example without receiving repository content, diagram data, titles, paths, or source JSON; print and canonical exports remain clean. - **Semantic Story Carrier.** Every unambiguous forward/reverse Story Beat now reuses the same five-kind semantic token vocabulary as Relationship Preview, so calls, data movement, events, security boundaries, and lifecycle transitions remain distinguishable while the guided camera advances. Story first deduplicates path and label fragments by stable authored edge key, preventing one labeled relationship from being misclassified as `multiple`; the carrier then follows only that exact authored geometry for Story's existing finite 780ms pulse. A dedicated viewer overlay keeps it above edges and below nodes, while generation-owned cleanup rejects stale animation callbacks. It runs only in ordinary desktop artifacts and explicit `?play=1` share playback; passive embeds, Still, reduced motion, hidden/print state, and canonical/raster export remain static and clean. No schema, IR, renderer layout, dependency, authored geometry, or mobile product surface was added. - **Semantic Flow Tokens.** Every exact-edge Relationship Preview now carries one compact inline SVG token along the authored source-to-target geometry: paired chevrons for calls, a framed block for data, a three-car train for events, a checked shield for security boundaries, and a ringed dot for lifecycle state changes. Classification uses only compiled edge variants and renderer-owned endpoint kinds with fail-closed precedence (`security > event > data > state > call`); labels, product names, and pixel geometry never decide meaning. The token shares Relationship Preview's single finite 1.2-second motion owner and cleanup path, rotates with the real line/path/polyline, respects Live/Still and reduced motion, and leaves no embed, print, canonical SVG, raster, schema, IR, dependency, layout, or authored-geometry residue. This is a desktop reading and presentation enhancement; mobile remains only a contained fallback. - **Semantic Sigils.** Every primary node in all five typed renderers now carries one small, theme-aware inline SVG role stamp: windows for frontend, brackets for backend, cylinder rings for data, a cloud contour, shield, transit rails, external portal, and distinct lifecycle start/active/wait/success/failure/neutral cues. The sigils reuse existing semantic color tokens across Classic, Signal Flow, Blueprint, dark, and light; remain static under trace motion; survive canonical SVG/raster export; and add no brand assets, product-name matching, schema field, layout box, focus target, interaction owner, dependency, or network request. Archify stays desktop-first: mobile remains a basic containment fallback rather than a dedicated product surface. - **Readable Route Rhythm.** Composition validation now distinguishes cramped turns from harmless endpoint stubs instead of applying one borrowed minimum to every polyline segment. In `showcase`, any segment below 8px and any interior turn segment below 16px fails before write and in the final artifact checker with the exact relationship, segment role/index, coordinates, length, and renderer-specific repair controls; `standard` records the same evidence as warnings. Endpoint stubs from 8–15px remain legal because fixed swimlane gaps can require them. The receipt now separates endpoint/interior shorts and micro segments while bend/stretch stay neutral. Three canonical routes were repaired: the event-stream dead-letter path fell from five bends to three, a deployment route lost its 5px hook and third bend, and lifecycle failure routing now enters through a clean side corridor. Proof Lab grows to 77/77 checks. - **Clear Container Corridor.** Architecture boundaries, workflow lanes/groups, data-flow stages, and sequence segments now carry typed structural-frame geometry into one shared pre-write gate and the final SVG checker. A semantic relationship may cross a frame perpendicularly, touch it at a point, or meet a rounded corner, but any positive collinear border run fails both `standard` and `showcase` with `composition/container-border-run`, exact relationship/frame/side/segment geometry, and renderer-specific repair controls. Lifecycle separators remain reading guides rather than containers. Two canonical routes were moved into open corridors; the Composition Receipt now also records neutral normalized bend, Manhattan stretch, and shortest-segment evidence without making borrowed Fireworks budgets into warnings. - **Composition Receipt + showcase quality profile.** Every rendered SVG now carries a named `standard` or `showcase` profile, and the artifact checker emits a structured composition receipt alongside its six artifact checks. Proper interior X crossings between unrelated relationships are warnings in default `standard` and blocking `composition/proper-crossing` errors in opt-in `showcase`; shared semantic endpoints, endpoint touches, and collinear relationship corridors remain outside the proper-X rule, with corridor ambiguity evaluated separately by the later named gate. `archify render` and `archify validate` accept `--quality standard|showcase`, all 11 canonical proofs opt into showcase, four visible route crossings were repaired (including one introduced only by rounded `Q` geometry), and the Proof Lab now publishes 66/66 artifact checks plus a separate `SHOWCASE · PASS` receipt. - **Clean Flow Gate.** All five typed renderers now share one generation-time relationship/obstacle contract: a connection, edge, flow, transition, or message may terminate on its own endpoints but cannot pass through an unrelated semantic node box. Failures carry the stable `clean-flow/edge-through-node` code, exact collection/index and authored ID, obstacle ID, first intersecting segment coordinates, 2px clearance, and renderer-specific repair knobs before any artifact is written. Architecture boundaries, workflow lanes/phases/groups, data-flow stages, lifecycle bands, and sequence segments/lifelines/activations remain intentional pass-through geometry; endpoint boxes are exempt. Six previously accepted canonical routes now use explicit clean corridors, all 11 proof scenarios remain valid, and edge-edge crossings are handled separately by the named composition profile instead of being promoted to a universal correctness rule. - **Story Shelf.** Guided artifacts now open with a compact, canvas-first shelf that keeps the useful `Guided views` identity, `Play story`, and every authored chapter visible while removing inactive Previous/Next, Copy moment, Show all, and generic instructional copy. The existing `data-active-view="all"` state is established before first paint; selecting a chapter, starting playback, or restoring a valid deep link immediately expands the complete Story Director, while Show all and Escape return to the shelf. In the measured workflow proof the panel shrinks from about 128px to 55px on desktop and 172px to 107px on mobile, moving the 390×844 diagram start from about y=389 to y=324 so the complete first diagram fits above the fold. Play and chapter targets remain 44px, chapter scrolling stays contained, and no panel, toggle, storage, schema, IR, renderer branch, dependency, motion owner, canonical SVG, or export state was added. - **Settled Flow.** Ordinary trace artifacts now spend their ambient motion budget once: edges, nodes, and Signal Flow scan complete one finite pass, then the viewer marks the canvas settled and restores every authored relationship style—including solid lines, security `5,5`, and async `4,4` dashes. The pass cannot replay when `Still` returns to `Live`; Story, Route, Lens, previews, embed, hidden pages, and reduced-motion continue to take priority. Long graphs cap visual delay without reordering semantic data. Canonical SVG/raster exports stay static, while WebM explicitly samples the same authored relationship geometry into its own repeatable finite canvas timeline. No schema, IR, renderer branch, layout, control, or dependency was added. - **First-fold Proof Aperture.** The GitHub Pages hero now tightens its normal-flow vertical rhythm so the existing generated Live Proof exposes real diagram canvas—not just its border and chrome—inside the initial 1280×720 and 390×844 viewports. One eager, script-only sandboxed iframe loads the same finite `play=1` named story exactly once and delegates reduced-motion behavior to the generated artifact itself; it neither reaches into the parent DOM nor grants same-origin privileges. The complete bilingual promise, both 44px actions, three explicit proof tabs, deliberate tab playback, stable authored views, validation receipts, and canvas heights remain intact, with no carousel, scroll polling, second motion region, schema/renderer/export change, or new dependency. - **Story Horizon.** Every non-final Story Beat now distinguishes one exact immediate-next stop from the farther pending story: the next authored node receives a restrained static state, and only the exact already-resolved connector set for that next transition follows it. Grouped transitions preview the real node without inventing an edge; multiple transitions retain every authored edge. The Director Strip names the next stop in its existing desktop footprint, while mobile relies on the same canvas hierarchy with no new row or lost touch height. Final beats clear the horizon, rapid navigation rewrites it atomically, and Still/reduced motion keep the same static meaning. Camera ownership, JSON, schema, IR, layout, dependencies, authored edge styling/geometry, ordinary embeds, print, and canonical SVG/raster/WebM export remain unchanged. - **Story Director Strip.** Every active Story Beat now receives one stable viewer-only caption with its exact position, real previous/current node route, authored edge label where present, and current node responsibility/context. Forward, reverse, multiple, and grouped/no-link states reuse Story Beat's fail-closed classification; the strip never invents a relationship or changes JSON. Automatic playback disables live announcements, while paused, manual, and exact-link states use polite updates. Desktop Presentation playback now keeps Previous, Next, and Pause but hides the chapter rail, Story Trail, Copy moment, and Show all until paused, shrinking the guided surface from about 155px to 82px in the 1280×720 proof and returning roughly 16% more height to the diagram. Still/reduced motion, mobile, ordinary embed, print, canonical SVG/raster/WebM export, schema, IR, renderer layout, dependencies, and authored geometry remain clean. - **Story Follow Camera.** Guided Story playback and deliberate Story Beat activation now frame an authored local window instead of leaving the current stop tiny inside the whole diagram: the first beat shows current + next, middle beats preserve previous + current + next, and the last beat keeps previous + current. The existing Semantic Camera owns the one finite 320ms move with 64px padding and a 1.65× cap; every beat receives at least 1100ms of readable dwell, so the camera settles before the story advances. Pause, manual pan/zoom, chapter replacement, hidden/print state, and Motion Still cancel follow ownership without a stale callback. `Still` and reduced-motion explicitly disable automatic Story playback while keeping manual beat inspection as an instant static frame. Exact `#view=&beat=` restoration waits one frame for the shared camera, then restores the paused moment without pulse or autoplay. Ordinary embeds keep their stable cold open; explicit share playback may follow. Schema, IR, renderer layout, authored geometry, dependencies, storage, and canonical SVG/raster/WebM export remain clean. - **Route Journey.** A completed Route Probe is now directly inspectable one position at a time: every receipt stop is a native button with one roving Tab stop, while Previous, Next, Journey/Pause/Replay, and Overview controls keep the full shortest authored route visible as context. Position zero owns the source; every later position owns exactly `activeEdges[index - 1]`, so the current incoming relationship can run one finite 780ms signal without endpoint re-query or invented geometry. Explicit playback uses one generation-owned finite scheduler, preserves remaining dwell on pause, and yields to manual pan/zoom, path focus, Guide, Motion Still, dynamic reduced motion, hidden pages, and print. Semantic Camera frames the previous/current/next slice; layered Escape pauses, returns to Overview, then clears. `#route=~` stays endpoint-only and restores without autoplay. Manual inspection remains available in Still mode, mobile controls retain 44px targets, and embed, print, canonical SVG/raster/WebM export, schema, IR, renderer layout, dependencies, storage, and authored geometry remain clean. - **Stable Relationship Links.** Architecture `connections`, workflow `edges`, sequence `messages`, data-flow `flows`, and lifecycle `transitions` now accept an optional author-controlled `id`. Renderers preserve that identity as canonical `data-edge-id` beside the private source-order runtime key; duplicate authored IDs fail closed before output. Pinning a named relationship restores and copies `#relation=`, so a shared explanation survives relationship reordering without exposing numeric runtime keys. ID-less documents remain valid, their pins stay local, and Copy falls back to the source node. Runtime hit rails and signal clones strip the durable ID, while ordinary embeds, print, raster/WebM output, layout, dependencies, storage, and visible geometry retain their existing boundaries. - **Direct Relationship Pin.** Every unique compiled relationship is now a directly operable viewer target over its exact authored geometry. A runtime-only 24px non-scaling rail keeps thin paths practical for mouse, pen, and touch without widening the visible stroke; one roving Tab stop plus Arrow keys, Home, and End reaches every relationship, while fine-pointer hover and keyboard focus reuse the existing exact-edge preview. Click, tap, Enter, or Space opens the source Semantic Passport and pins the exact existing Relationship Lens row; activating the same relationship, the background, Clear, or Escape removes it. ID-less pins remain local because their source-order key is private; the later Stable Relationship Links slice adds durable URLs only when authors opt into stable IDs. Conflicting duplicate metadata fails closed, stronger Story/Route/Lens/Focus owners retain priority, and embed, print, canonical SVG/raster/WebM export, renderer layout, dependencies, storage, and authored geometry remain clean. - **Shareable Story Moment.** A new viewer-only `Copy moment` action turns the active Story Beat into a stable `#view=&beat=` link. Static links restore the exact authored node only after the winning chapter handoff, never pulse or autoplay, and fail closed to the chapter when the beat is missing, stale, or belongs elsewhere. Copying during playback freezes the visible beat and deliberately removes `play=1`; an explicit `?play=1` link can still continue the remaining beats of that chapter once. Static embeds reuse Share Chapter Cue as a truthful `Pinned` receipt, while reduced motion, rapid hash replacement, mobile geometry, print, canonical SVG/raster/WebM export, schema, IR, renderer layout, dependencies, and authored graph data retain their existing boundaries. - **Story Beat Navigator.** Every resolved Story Trail stop is now a native, directly activatable beat control with an exact two-digit position, stable-ID node label, 24px desktop / 32px mobile target, visible focus state, and one truthful `aria-current="step"`. Click, tap, Enter, or Space pauses any running story and pins that beat without changing the chapter, selected focus IDs, camera, diagram/page scroll, URL, or authored graph; keyboard focus alone pauses at the current playhead without selecting. Adjacent stops are classified fail-closed as starting point, one forward edge, one reverse edge, grouped with no direct authored relationship, or multiple authored edges. Only one unambiguous exact edge may run one finite 780ms source-to-target signal; grouped and multiple steps stay static. Playback now uses one generation-owned scheduler, preserves elapsed dwell on pause, resumes from the same beat, waits for Shared Anchor Handoff before starting the next chapter, and rejects stale callbacks. Still, dynamic reduced motion, hidden/print state, ordinary embeds, Presentation, canonical SVG/raster/WebM export, schema, IR, renderer layout, dependencies, and authored geometry keep their established boundaries. The current 11-proof corpus exposes 33 chapters and 150 directly inspectable stops. - **Chapter Delta Preview.** Named Chapter Rail now explains the exact focus-set cost of every possible move before activation. The current chapter keeps its truthful stop count; each candidate shows compact `=stay +enter −leave` evidence derived from unique existing stable IDs, including explicit zeroes for discontinuities. Fine-pointer hover and keyboard focus apply one static, viewer-only comparison without changing `activeIndex`, semantic focus, Story Trail/Beat, camera, contained scroll, URL, `aria-current`, or `aria-pressed`; Escape dismisses it in place, touch still activates on the first tap, and click/Enter/Space continue through Shared Anchor Handoff. Latest pointer/focus intent wins, playback pauses without auto-resuming, stronger Route/Lens/Relationship/Intent owners defer the preview, and hidden/print lifecycles clean it atomically. Across the current 11 Proof Lab artifacts, 22 adjacent chapter moves contain 19 real shared-ID transitions and 3 honest `=0` discontinuities. Still, reduced motion, mobile 44px rail geometry, Presentation, ordinary embeds, print, canonical SVG/raster export, schema, IR, renderer layout, dependencies, and authored graph geometry keep their established boundaries. - **Shared Anchor Chapter Handoff.** Guided chapter-to-chapter navigation now preserves one real stable-ID node through a short 110ms orientation hold, names the continuity as `NN → NN · via `, and settles the existing Semantic Camera with one interruptible 420ms transaction. The current Story Beat wins when it exists in both chapters; otherwise the latest shared outgoing stop is used. Chapters with no shared node publish an honest `no-anchor` retarget with no fabricated ring or connector. Latest intent wins under rapid navigation, manual pan/zoom takes over without a stale callback, and Story timing begins only after the winning camera settles. Live/Still, dynamic reduced motion, hidden pages, ordinary embeds, print, canonical SVG/raster export, mobile contained scroll, schema, IR, renderer layout, and dependencies keep their established boundaries. - **Reader-controlled Motion Governor.** Trace-enabled artifacts now expose one persistent `Live` / `Still` control that governs the complete viewer motion contract without changing authored SVG. Ambient pulse, scan, edge, and node loops yield whenever Story, Chapter, Route, Lens, Relationship Preview, Intent Trace, Focus, or Legend has stronger semantic intent; switching to `Still` resets those effects to a readable static state, pauses an active story at its exact beat, and never auto-restarts it when `Live` returns. Dynamic reduced-motion and page-visibility changes use the same stop path, tokenized `claim` / `release` / `suspend` hooks reject stale cleanup, Route Probe now resolves after one finite signal instead of looping, and 44px mobile controls keep `Live` / `Still` explicit at 320px. Static artifacts never start decorative motion, embeds remain calm unless a bounded `?play=1` chapter was requested, and print, canonical SVG, raster export, schema, IR, layout, WebM, and dependencies remain unchanged. - **Named Chapter Rail for Guided Views.** Every artifact with authored `meta.views` now reveals all available chapters up front as a runtime-built navigation rail with a two-digit position, exact authored title, and truthful stop count. The rail mirrors the existing `activeIndex` rather than owning parallel state, delegates activation to the existing guided-view controls, supports roving Left/Right/Home/End focus, pauses playback when a reader takes over, and keeps current/before/after state distinguishable without color. Phones get 44px horizontal snap targets that center the active chapter without widening the page; embed, print, canonical SVG, raster export, schema, IR, layout, and dependencies remain unchanged. - **Selective Semantic Legend Bridge.** Architecture, workflow, and lifecycle artifacts now turn only exact node-kind legend rows into counted, keyboard-operable entrances to Semantic Lens. Fine-pointer hover or keyboard focus previews the matching nodes, touching authored relationships, and connected peers without starting motion; click, tap, Enter, or Space pins the same kind in the existing Lens. Counts come from compiled semantic nodes at runtime, selected rows retain a dashed non-color cue, and sequence/data-flow legends remain deliberately static where their rows describe edge or mixed semantics. Embed, print, reduced motion, canonical SVG, and raster export stay clean, with no schema, IR, layout, graph-copy, or dependency change. - **Exact-edge Directional Flow Pulse for Relationship Preview.** Entering a named Relationship Lens row with a fine pointer or keyboard now sends one 1.2-second source-to-target signal over that exact stable-keyed authored path, including incoming and bent relationships, before returning to the existing static edge and endpoint emphasis. The runtime-only marker-free clone preserves geometry and preset identity, clears on replacement, exit, animation end/cancel, page hiding, and live reduced-motion changes, while touch keeps direct one-tap navigation and embed, print, canonical SVG, and raster exports remain clean. There is no replay control, timer loop, schema, IR, layout, graph-copy, or dependency change. - **Selection-triggered Semantic Flow.** An active Semantic Lens now reuses the exact matched authored path geometry for a short, direction-aware pulse instead of adding ambient motion to the full canvas. One-kind views distinguish outgoing, incoming, and within-kind traffic; two-kind views preserve authored forward/reverse direction. Classic, Signal Flow, and Blueprint each keep their own motion character, while one-shot playback, a 24-edge density guard, reduced-motion static fallback, embed/print suppression, marker-free pointer-free runtime clones, and canonical export cleanup preserve stability without adding schema, IR, renderer-layout, graph-copy, or dependency surface. Passive Intent Trace now also completes one bounded pass instead of looping forever under a parked pointer or keyboard focus. - **Semantic Lens for counted role comparison.** Every renderer-backed artifact now turns existing `data-node-kind` semantics into an accessible `LENS` panel and L shortcut. One kind reveals its exact nodes, touching relationships, and connected peers; two kinds isolate direct authored links and report both directions separately. The soft-dimmed mental map, two-selection limit, arrow-key navigation, explicit reset, copyable/restorable `#lens=~` state, Reading Depth override, mobile containment, embed restoration, stronger-intent arbitration, and clean print/export contract require no schema, IR, renderer-layout, graph-copy, or dependency changes. - **Reading Depth semantic zoom.** Every renderer-backed artifact now opens in a quiet `MAP` layer, reveals responsibilities and relationship labels at `READ` (125%), and adds tags, steps, notes, and classifications at `FULL` (175%). Node focus, Semantic Lens, Intent Trace, Route Probe, Story Trail, and Relationship Preview reveal the exact detail they need regardless of scale, while print and canonical exports always retain the complete authored diagram. The five renderers own the context/fine classification; the viewer adds no schema, IR, layout, command-parser, or dependency surface and respects reduced-motion preferences. - **Diagram Guide for artifact-first discovery.** Every renderer-backed artifact now exposes a `?` control and ? shortcut that reports exact compiled semantic-node, relationship, and guided-view counts, then runs six existing reader tasks—Find, Route, Radar, Lens, Story, and Presentation—from outcome-oriented action rows. Arrow/Home/End navigation, direct action shortcuts, honest no-story disabling, playback pause, predictable Escape focus restoration, mobile Route receipt avoidance, reduced-motion behavior, and embed/print/export isolation are built in without adding schema, IR, layout, command-parser, or dependency surface. - **Searchable Route Probe endpoints.** While Route Probe is choosing a source or destination, /, the normal Finder control, or the receipt's contextual action now turns Node Finder into an endpoint picker. Source suggestions omit nodes without authored outgoing routes; destination suggestions contain only nodes reachable in authored direction and preview the deterministic shortest hop count. Selection hands back to the existing Route Probe result, Escape preserves the in-progress question, mobile temporarily recedes the underlying receipt, and normal Finder focus behavior remains unchanged outside route picking. The integration is viewer-only and adds no schema, IR, layout, export, or dependency surface. - **Route Probe for exact two-node questions.** Every renderer-backed artifact now lets readers press R or use `PATH`, choose a source, see its directed reachable destinations, and trace the deterministic fewest-hop authored route to a target. The viewer preserves ordered node/edge identity, frames the result with Semantic Camera, renders a compact route receipt, restores/copies `#route=~`, and animates cloned `pathLength="1"` edge geometry without mutating the diagram. Pointer and keyboard selection are equivalent, no-route states stay explicit, reduced motion becomes static, and embed/print/canonical SVG exports remain clean without schema, IR, layout, or dependency changes. - **Intent Trace before committed focus.** Fine-pointer hover or keyboard focus now previews a node's exact one-hop incoming, outgoing, and self-loop traffic before selection. Related topology stays clear while a direction-colored, `pathLength="1"` runtime overlay sends a restrained signal over cloned edge geometry; click/Enter hands off to the existing Semantic Passport and camera. Touch remains tap-to-focus, reduced-motion uses a static highlight, embed/story/pan/focus states suppress the preview, and every transient attribute and overlay is removed from canonical exports without changing JSON IR or authored geometry. - **Semantic Radar overview navigation.** Every renderer-backed artifact now exposes a dependency-free, type-colored overview from the `MAP` control or M. The runtime-built radar shows the live desktop camera or contained-mobile width, focuses stable semantic nodes, supports pointer and keyboard recentering, docks within the visible diagram, and collision-avoids the focused node and Passport when space permits. It is absent from embed, print, static SVG counts, and canonical exports; no schema or authored geometry changed. - **Semantic Passport and copyable focus links.** Single-node focus now exposes the renderer-owned semantic kind, responsibility sublabel, authored tag, stable ID, and structural scope (boundary, workflow lane/phase, sequence role, data-flow stage, or lifecycle lane) above the existing Relationship Lens. Node Finder searches and displays the same facts, inline SVG nodes retain a native details tooltip, and one action copies the existing `#focus=` deep link with a dependency-free clipboard fallback. Narrow screens keep the compact Passport clear of the selected node and reveal the full relationship list only through an explicit count button. No schema, layout, or canonical geometry changed. - **Semantic Story Beats.** Guided playback now advances through the existing authored node order instead of pulsing the whole selected subgraph at once. Current, past, and pending nodes plus their real relationships receive distinct viewer-only states; an edge activates only after both endpoints are reached, Share Chapter Cue names the current `Step NN / NN`, pause freezes the exact beat, completion restores the full readable subgraph, and reduced-motion readers skip the timeline entirely. - **Share Chapter Cue for meaningful motion.** One-shot embed links now name the authored chapter, show its exact Story Trail route, report Ready/Playing/Settled/Paused/Still state, and expose a truthful 3.2-second progress rail. The zero-dependency HTML layer stays outside canonical SVG/export geometry, freezes at the actual reader-interruption point, and reserves its own top band on phones instead of covering nodes. - **Share-ready one-shot chapters.** `?play=1#view=` now activates and plays only the requested Story Trail chapter for 3.2 seconds, then stops without advancing or leaving ambient trace loops running. Missing hashes fall back to the first authored view, OS reduced-motion preferences keep the chapter static, reader interaction interrupts immediately, and `data-autoplay` exposes pending/playing/complete/interrupted states for deterministic browser proof. - **Path-aware Story Trail.** Every named guided view now exposes its ordered semantic stops as a compact reader rail. Real forward and reverse relationships use directional arrows, thematic gaps use neutral separators, and Play animates a viewer-only overlay over every real edge inside the selected subgraph. The authored edge colors, dash patterns, markers, geometry, reduced-motion behavior, and canonical exports remain unchanged across all five renderers. - **Semantic Camera.** Node focus, relationship traversal, Finder selection, and guided views now frame their exact semantic bounds with a padded, capped, reduced-motion-aware viewport transition. The camera reserves room for Relationship Lens, labels itself only when it actually zooms, resets on overview, follows responsive layout changes, and pauses guided playback the moment a reader manually zooms, pans, or swipes. Mobile keeps its contained 100% horizontal-reading model instead of stacking transform zoom on top. - **Relationship Lens and exact-path preview.** Single-node focus now opens a keyboard-navigable incoming/outgoing/self-loop relationship panel backed by stable semantic edge keys across all five renderers. Pointer hover and keyboard focus temporarily isolate the exact edge plus its source and target; narrow screens collapse the list into a one-row Peek card on the opposite side of the focused node. Activation follows the relationship, while embed, print, SVG export, and base geometry remain clean. - **Verified README motion reel.** The repository hero now plays a compact 5.4-second GIF assembled from three current Proof Lab artifacts—Signal Flow workflow, Blueprint architecture, and Classic sequence—rather than a static mockup. A zero-npm-dependency Chrome DevTools Protocol capture script regenerates the reel, writes a source-digest receipt, and a binary parser test enforces 960×540 dimensions, 54 frames, continuous looping, a 3 MB ceiling, and exact source-artifact freshness across all README languages. - **Landing-page Live Proof Stage.** The GitHub Pages hero now embeds three real, trace-enabled Proof Lab artifacts instead of a static screenshot: Signal Flow agent orchestration, Blueprint deployment ownership, and a Classic cache-miss sequence. The bilingual, keyboard-operable selector keeps each preview clickable, links to its named guided view, and is guarded by manifest-backed tests for preset, graph receipt, animation, artifact presence, and validation status. - **Semantic Node Finder.** Every generated artifact now exposes a zero-dependency node navigator from the diagram controls or /. It searches labels, sublabels, and stable IDs; reports semantic type and unique relationship count; supports full keyboard navigation; releases guided playback; resets and reveals the chosen node; and delegates selection to the existing shareable `#focus=` contract without touching SVG geometry or canonical export. - **Shareable Presentation Stage.** Every generated diagram can now enter a viewport-filling live stage from the toolbar or F. The stage preserves theme, semantic focus, guided-story playback, pan/zoom, and canonical export; hides supporting cards; supports `?present=1#view=` deep links; and lets Escape unwind the active view/focus before exiting. Desktop and contained wide-mobile layouts share the same zero-dependency contract. - **Blueprint engineering preset.** All five renderers now accept `visual_preset: "blueprint"`, a geometry-preserving drafting identity with coordinated dark/light variables, precise grids, squared review materials, boundary notation, and restrained trace motion. The deployment-ownership proof and scenario recipe exercise the preset end to end. - **Question-first scenario guide.** A single bilingual recipe source now powers `archify guide` and a generated GitHub Pages chooser. Eleven bounded recipes across all five diagram modes explain what each view answers, evidence it must contain, when not to use it, suggested motion/views, and a copy-ready prompt without runtime dependencies. - **Signal Flow presentation and browser-native motion export.** Renderer-backed diagrams can opt into a luminous `signal-flow` visual preset, and trace-enabled artifacts can record a six-second WebM directly in the browser without Puppeteer or ffmpeg. - **Semantic focus explorer.** All five renderers emit deterministic node IDs and relationship endpoints. Generated HTML supports click/Enter/Space one-hop focus, shareable `#focus=` links, Escape/Clear reset, and 100–300% pan/zoom while canonical exports remain unaffected. - **Typed guided views.** All five schemas accept up to five named `meta.views` over existing semantic IDs. Generated HTML adds an accessible story strip, previous/next/overview controls, [/] navigation, `#view=` deep links, and deterministic validation for duplicate or dangling references without changing base SVG geometry. - **Timed guided-story playback.** Guided views now include Play/Pause and a progress rail, advance every 3.2 seconds, stop after the final authored view, pause on hidden pages or reader exploration, expose a P shortcut, and preserve the same immutable base geometry and canonical export boundary. - **Accessible SVG identity.** Generated SVGs include deterministic node DOM IDs plus native `` and `<desc>` metadata derived from typed diagram metadata. - **Generated Proof Lab.** `node scripts/build-gallery.mjs` now regenerates 11 live scenario proofs across all five diagram modes, their exact JSON sources, 77 artifact checks, composition receipts, byte sizes, SHA-256 digests, and three-step reader stories. A dedicated test fails when any recipe lacks a proof or any checked-in artifact drifts. ### Changed - Architecture `auto` routing now preserves its existing H-V-H dogleg when safe, but deterministically tries the complementary in-bounds V-H-V dogleg when the first candidate would cross an unrelated component. Explicit `via`, `straight`, `orthogonal-h`, and `orthogonal-v` choices remain authoritative; if both bounded candidates are blocked, Clean Flow still fails closed with the existing actionable error. - The Skill delivery loop now treats a successful render as a candidate: after deterministic validation it requires a final browser/raster readback when available, allows at most two focused correction rounds, and reports explicit `validation`, `visual_review`, and `correction_rounds` evidence. Environments without an image reader must say the review was skipped instead of claiming visual approval. - Embedded artifacts now pause ambient trace loops by default. The landing-page Live Proof Stage opts into one named chapter at a time, gallery cards stay static and cheap, direct proof actions open a self-playing Presentation Stage, and the README reel captures the same bounded chapter contract. - Wide diagrams now use a contained 720px mobile reading surface instead of shrinking labels into an unreadable thumbnail. Guided views auto-center the authored path, internal swiping never widens the page, and zoom/focus controls remain pinned while the diagram moves underneath. - The landing page now shows a real moving, explorable artifact before leading uncertain users into the scenario chooser; the full Proof Lab remains the broader evidence surface for rendered capability. - Every scenario-guide result now links to its matching generated proof card, and every proof exposes a shareable named view rather than a generic gallery landing page. - The GitHub Pages landing page now links the Proof Lab and documents guided views, semantic focus, pan/zoom, Signal Flow, and WebM alongside the existing export surfaces. - Generated diagrams support `?embed=1`, a chrome-free read-only surface used by the live gallery previews. ### Fixed - The Skill frontmatter description now stays within the 1024-character metadata limit used by GitHub Copilot and other Agent Skill runtimes, while retaining all five diagram-mode and Mermaid discovery triggers. A regression test protects both the portable size budget and searchable trigger vocabulary. - Clean Flow is now a universal semantic correctness invariant instead of an opt-in composition gate. Profile-less default rendering rejects a relationship whose routed geometry passes through an unrelated opaque node, including the real auto-route regression from #24, while explicit waypoints around the obstacle remain valid. `standard` and `showcase` still control only the stricter composition budgets. - East Asian text measurement now includes wide vertical punctuation and supplementary script blocks while keeping halfwidth Katakana at one unit. Regression coverage preserves Hiragana, Katakana, Bopomofo, Hangul compatibility letters, fullwidth forms, emoji, and supplementary CJK behavior. - WebM export now renders an explicit time-varying canvas scene over the static canonical diagram instead of repeatedly drawing one browser-cached SVG image frame. Signals follow the real authored `path` / `line` / `polyline` geometry, node pulses retain authored order, and the six-second browser-native recording is visibly animated without mutating the SVG, adding dependencies, or leaking viewer state. - WebM export now requests a final encoder flush before stopping. Embedded browser shells that still report MediaRecorder support but return an empty stream fail with a machine-readable receipt, disable the unavailable menu item, and show a non-blocking toast instead of trapping the reader in repeated alert dialogs; animated SVG and the rest of the export surface remain available. - Guided-view and node-focus state now follows same-document `#view=` / `#focus=` hash changes, so browser history and manually edited deep links cannot leave the address bar and diagram out of sync. - SVG export receipts now inspect the cloned DOM before serialization, proving temporary focus and viewport state was removed without mistaking embedded CSS selectors for live state. - The degraded-install test excludes another test's short-lived `.validator-check-*` fixture, eliminating a concurrent copy/remove race. ## [2.11.0] — 2026-07-16 ### Added - **Zero-install schema validation.** All five JSON Schemas are compiled at development time into committed standalone ESM validators. Installed skills now enforce the full schema contract without `npm install`, `node_modules`, or a network connection; CI verifies the packaged ZIP rejects invalid input in this dependency-free state. - **First-run CLI commands.** `archify doctor` checks the installed runtime surface, and `archify demo [output-directory]` generates a ready-to-open example plus the next render command. ### Changed - **60-second quick start.** README and GitHub Pages now lead with `npx skills add tt-a1i/archify -g`, a temporary `skills use` path, and three copy-ready prompts before the manual ZIP instructions. ### Fixed - **Packaged CLI and validation hardening ([#21](https://github.com/tt-a1i/archify/pull/21)).** Installed ZIPs now keep `archify examples` on the packaged path, enforce standalone schema validation without development dependencies, and cover the clean-consumer CLI flow in CI. Thanks to [@ShiroKSH](https://github.com/ShiroKSH). ## [2.10.0] — 2026-07-05 ### Added - **Actionable validator hints (#7).** Architecture layout errors now include concrete `Suggested fix` coordinates (`labelAt`, `labelDy`, nudged `pos`) so agents can patch JSON in one pass. - **Architecture grid placement (#8).** Optional `layout.mode: "grid"` with `row`/`col` per component; explicit `pos` still overrides a cell. Example: `examples/archify-repo-grid.architecture.json`. - **Layout inspect (#9).** `archify inspect architecture <file.json>` (alias: `validate --layout-json`) prints computed component rects, boundaries, connection paths, and label boxes as JSON. ## [2.9.0] — 2026-07-05 ### Added - **Unified CLI entrypoint.** Added `bin/archify.mjs` with `render`, `validate`, `check`, and `examples` commands so renderer-backed workflows have a single product-facing command surface. - **Architecture examples.** Added self-diagram (`examples/archify-repo.*`) and a third-party sample (`examples/maka-architecture.*`) demonstrating clean main-path layout on real repos. ## [2.8.0] — 2026-07-03 ### Added - **Opt-in trace animation.** Renderer-backed diagrams can set `meta.animation: "trace"` to animate marked arrows and nodes inside the generated HTML/SVG. The default output remains static, and the CSS respects `prefers-reduced-motion`. - **Workflow route guard.** Workflow rendering now rejects edges that cross through non-endpoint nodes, so crowded or long return routes fail with an actionable routing hint instead of producing confusing line artifacts. ## [2.7.0] — 2026-07-03 ### Added - **Post-render artifact checker.** Added `scripts/check-render-output.mjs`, a zero-dependency final HTML/SVG gate that checks for a single SVG block, non-finite SVG values, accidental two-point diagonal arrows, and arrows crossing the legend. - **Workflow phase headers, groups, and exception lanes.** Workflow JSON now supports `phases`, `groups`, and `lane.variant: "exception"` so diagrams can make story beats, branch areas, and human/policy stop paths explicit. - **Workflow `mainPath` lint.** The workflow renderer can validate that happy-path node ids are linked in order and do not accidentally move backward. - **Artifact-check tests.** `test/render-output-checks.test.mjs` covers the new checker, including the legend-collision case that visual review exposed. ### Changed - The renderer loop in `SKILL.md` and the workflow README now includes the post-render artifact checker as a standard delivery step. - The workflow example was regenerated to demonstrate phases, groups, an exception lane, and clearer return/trace paths. ### Fixed - **Same-lane offset routing.** Default same-lane workflow edges with different `yOffset` values now route orthogonally instead of drawing a two-point diagonal. - **Legend collision in generated workflow previews.** The generated Archify renderer-pipeline preview now routes the compare path through a lane gap instead of crossing the legend. ## [2.6.0] — 2026-06-12 ### Added - **Architecture renderer.** The default, highest-traffic mode now has a constrained renderer (`renderers/architecture/render-architecture.mjs`) and JSON Schema (`schemas/architecture.schema.json`), bringing it to validation parity with the four typed modes — without auto-layout. Claude still picks all coordinates (`pos`/`size`); the renderer handles the mechanical work: the two-rect `c-mask` pattern, arrows-before-boxes z-order, an auto-built legend, and an auto-fitted `viewBox`. - **Boundaries from `wraps`.** A `region` or `security-group` boundary lists the component ids it encloses; the renderer computes the box with correct 30/50 padding automatically, eliminating the hand-arithmetic that caused the v2.2.1 padding bug. - **Architecture example.** Added `archify/examples/web-app.architecture.json` rendered to `examples/web-app-rendered.html`, wired into the golden suite (5th entry). - **Geometry unit tests.** `archify/test/geometry.test.mjs` directly tests the pure helpers every renderer depends on (`rectsOverlap`, `anchor`, `roundedPath`, `labelPoint`, `chosenSide`, `textUnits`, …) — previously covered only transitively by golden byte-compares. - **Layout-rule coverage matrix.** `archify/test/layout-rules.test.mjs` drives one minimal-violation case per high-value layout rule across all five modes and asserts the error message carries its numeric threshold and remediation hint (the LLM-facing DX contract). - **Degraded-mode fuzz net.** `archify/test/degraded.test.mjs` asserts that type-wrong-but-JSON-legal input always fails friendly (non-zero exit, no `TypeError`, no `NaN`/`undefined` written) and that valid order-shuffles always render. ### Changed - `npm test` now runs the golden suite plus `node --test test/*.test.mjs` (geometry, layout-rules, degraded). The `architecture` schema is registered in `validator.mjs` and covered by `render:examples`. - `textUnits` now counts supplementary-plane CJK and emoji as double-width (added the `u` flag and astral ranges). ### Fixed - **Degraded-mode robustness (no ajv).** A type-wrong top-level field (e.g. `nodes: "oops"`) or a missing coordinate field (e.g. a node with no `col`) previously threw a raw `TypeError` before the friendly checks ran, or exited 0 while writing `<rect x="NaN">` into the HTML. Renderers now coerce non-array fields via `asArray`, guard non-finite coordinates with `isFinitePoint`, and validate `cards`/`messages`/`segments`/`activations` are arrays — so malformed input always produces an actionable message instead of a crash or silent corruption. ## [2.5.0] — 2026-06-11 ### Added - **Workflow diagram mode.** Archify now includes a renderer-backed workflow diagram type for technical flows, approval chains, tool calls, CI/CD paths, runbooks, and process ownership diagrams. Workflow diagrams use a JSON IR with lanes, nodes, routed edges, and summary cards, then render into the same standalone HTML shell with theme toggle and export menu. - **Workflow JSON Schema.** Added `archify/schemas/workflow.schema.json` to document and validate the workflow IR shape. - **Workflow example.** Added a rendered agent tool-call workflow example at `examples/workflow-agent-tool-call-rendered.html`. - **Sequence diagram mode.** Added a renderer-backed sequence diagram type for API call chains, request lifecycles, cache fallback paths, authentication checks, async trace emission, and service interactions over time. - **Sequence JSON Schema.** Added `archify/schemas/sequence.schema.json` to document and validate the sequence IR shape. - **Sequence example.** Added a rendered cache-miss request sequence example at `examples/sequence-cache-miss-request.html`. - **Sequence README preview.** Added a rendered sequence screenshot to the README preview flow. - **Data-flow diagram mode.** Added a renderer-backed data-flow diagram type for analytics pipelines, ETL/ELT, PII isolation, governance boundaries, data lineage, warehouse sync, and downstream consumers. - **Data-flow JSON Schema.** Added `archify/schemas/dataflow.schema.json` to document and validate the data-flow IR shape. - **Data-flow example.** Added a rendered product analytics data-flow example at `examples/dataflow-product-analytics.html`, plus a README preview screenshot. - **Lifecycle diagram mode.** Added a renderer-backed lifecycle/state-machine diagram type for object lifecycles, wait states, retries, cancellation, timeout, terminal states, and recovery paths. - **Lifecycle JSON Schema.** Added `archify/schemas/lifecycle.schema.json` to document and validate the lifecycle IR shape. - **Lifecycle example.** Added a rendered agent-run lifecycle example at `examples/lifecycle-agent-run.html`, plus a README preview screenshot. - **Runtime JSON Schema validation.** All four typed renderers validate their JSON IR against the published schemas via ajv (draft 2020-12); violations exit non-zero with path-prefixed error messages, and error paths carry element ids (e.g. `/nodes/3 (id/label: "router")`). When dependencies aren't installed, the renderer warns and skips schema validation gracefully — layout checks still run. - **GitHub Pages landing page.** Added a product landing site under `docs/` plus a repository social preview image. - **Mermaid as an input dialect.** New `SKILL.md` section maps `flowchart` → workflow, `sequenceDiagram` → sequence, and `stateDiagram` → lifecycle so Claude can accept pasted Mermaid and lay out from scratch (prompt engineering, no parser) — closing roadmap item P2. - **Label collision detection.** New validation checks flag label-vs-node and label-vs-label collisions, plus node labels overflowing their boxes. - **CJK-aware text width estimation.** Full-width characters count as 2 units, and the template plus exported-SVG font stacks gained PingFang SC / Microsoft YaHei / Noto Sans CJK SC fallbacks. - **Golden test suite.** `archify/test/golden.mjs` byte-compares the four rendered examples, runs 6 negative validation cases (schema + layout), and checks `web-app.html` template freshness and version sync — wired to `npm test`. - **Example re-render script.** `archify/test/render-examples.mjs` re-renders every example in one shot via `npm run render:examples`. - **CI workflow.** `.github/workflows/ci.yml` runs the test suite on a Node 20/22 matrix and verifies `archify.zip` freshness by rebuilding and diffing. - **Release workflow.** `.github/workflows/release.yml` builds the zip on `v*` tags, verifies the tag matches `package.json`, and attaches the artifact to the GitHub Release. - **Zip build script.** `scripts/build-zip.sh` builds `archify.zip` from `archify/` (including `package.json`, the lockfile, and the newly bundled `archify/LICENSE`; excluding `node_modules`). `package.json` declares `engines.node >= 18`. - **Workflow preview image.** Added `docs/assets/archify-workflow.png` (4× dark export) — workflow was the only diagram type without a preview screenshot. - **Generator metadata & accessibility.** Generated HTML carries `<meta name="generator" content="archify 2.5.0">`; the SVG root gets `role="img"` + `aria-label`, toasts get `role="status"`, and the export menu fixes focus return to the trigger, ArrowDown-to-open, and separator ARIA. - **Async Google Fonts loading.** The `media="print"` onload trick plus preconnect and a noscript fallback mean an offline or slow network no longer blocks first paint. - **Theme FOUC guard.** An early script in `<head>` applies the stored theme before first paint, and pages without an explicit preference now follow live system theme changes. - **`--text-faint` UI variable.** Menu hints and the footer now meet contrast standards; the SVG `t-dim` color is unchanged. ### Changed - **Template responsive polish.** The shared HTML template now handles narrow viewports better: the toolbar no longer overlaps the title, diagrams can scale down to the available width, and cards stack cleanly on mobile. - **Subtle swimlane styling.** Added `c-lane` for workflow/process swimlanes so workflow boundaries do not visually overpower the main path. - **Lifecycle diagram reworked as a phase map.** The lifecycle visual model was redesigned across several composition passes: phase bands, decluttered middle lanes, and refined transition labels. - **Shared renderer code.** The typed renderers share `utils.mjs` (with hardened template slot replacement), and this release extracts `renderers/shared/geometry.mjs` (geometry/class maps), `cli.mjs` (CLI head/tail), and `schemas/common.schema.json` (`$ref`-shared id/point/componentType/variant/cards definitions). ajv now runs in strict mode. - **Validation error messages rewritten.** Every check now reports numeric thresholds, the valid range, and which field to change. - **`SKILL.md` restructured (433 → ~205 lines).** New Setup section (npm install, graceful degradation, architecture-mode fallback when no shell is available), per-mode JSON examples upgraded from empty skeletons to renderable snippets (all verified to pass first try), per-mode layout budgets (columns/rows/coordinate ranges/spacing), documented lifecycle reserved-lane (`main`/`terminal`) semantics, a 6-item machine-checkable architecture-mode checklist, a pointer to the renderer README for depth, and corrected viewBox guidance. Frontmatter version is 2.5 and the description gained Mermaid/flowchart trigger words. - **Lifecycle band titles.** Band titles now render from lane labels (the schema-required field is finally used), the main track length derives from actually occupied columns, and a missing `main` lane is a validation error. - **Sequence timeline scaling.** The timeline scales with viewBox height (taller viewBox = more timeline room), and segments are validated (`to > from`, within the canvas). - **Workflow sizing defaults.** Omitting the viewBox now auto-computes height from the lane count, and the default width dropped 1000 → 720, eliminating 320px of dead space. - **Schema limits tightened.** Column caps added (workflow `col ≤ 5`, lifecycle `col ≤ 4`), sequence messages require `y ≥ 160`, and viewBox minimums are stricter. - **Exported SVG embeds only SVG-relevant CSS.** ~9 KB of toolbar/cards/print rules are stripped from `.svg` downloads. - **Download filename cleanup.** The redundant `-diagram` suffix is stripped from export filenames. - **Docs images consolidated under `docs/assets/`.** `examples/images/` is removed, the orphaned `archify-print.png` deleted, and `archify-lifecycle.png` regenerated with the new band titles. - **Docs accuracy.** README's "~3 KB embedded JS" corrected to ~19 KB; "4× export" is now documented as *up to* 4× (oversized diagrams automatically step down to 3×/2× via `pickSafeScale`); and "zero dependencies" is scoped to the generated HTML only — the renderers need `npm install` for ajv. ### Fixed - **`applyTemplate` slot corruption.** Slot replacement now uses a function replacer, so `$&`, `$'`, `` $` ``, and `$$` in titles or labels no longer corrupt the output. - **Lifecycle overlap detection across lanes.** Overlap checks now compare all state pairs across lanes — previously, identical coordinates in different lanes produced zero errors. - **Sequence vertical-spacing false positives.** The spacing check now only fires for messages whose horizontal spans actually overlap, eliminating false reports on parallel messages. - **Zero values swallowed.** `bias: 0` / `channelX: 0` / `channelY: 0` now use `??` instead of `||`, so schema-legal zero values are respected. - **Workflow `fromSide`/`toSide: "auto"`.** Removed from the schema and normalized in code — an explicit `"auto"` used to anchor edges to the wrong side. - **Route enums converged.** Workflow drops `drop-right`/`drop-left`/`same-lane` (byte-identical output to `drop`/`straight`); lifecycle drops `raise`, removes the dead `bias` field, and adds `cornerRadius` (the renderer read it but the schema rejected it). - **Light-theme exports kept dark swimlanes.** The export pipeline now scans the stylesheet for CSS variables at runtime instead of using a hardcoded list — `--lane-fill`/`--lane-stroke` were slipping through, and newly added variables can no longer be missed. - **Safari Copy PNG.** `ClipboardItem` is now constructed synchronously inside the user gesture (with a `Promise<Blob>` value), with a fallback path. - **`localStorage` guarded.** All access is wrapped in try/catch, so disabled storage no longer takes down theme, export, and keyboard shortcuts together. - **Print palette completed.** Print styles now carry a full light palette (no more neon strokes when printing from the dark theme), and the footer keyboard-shortcut hints are hidden in print. - **Stale `archify.zip`.** Rebuilt — it had fallen 3 commits behind and was missing `renderers/shared/` and `package.json`; CI now enforces zip freshness. ## [2.4.0] — 2026-04-18 ### Changed - **Download SVG is now dual-theme self-contained.** The exported `.svg` ships with BOTH dark and light CSS variable sets plus a `@media (prefers-color-scheme: light)` rule. Embedding the file via `<img src="x.svg">` in a GitHub README (or any host that exposes a color scheme) makes it follow the reader's dark/light preference automatically — no more shipping two PNGs wrapped in `<picture>`. The root `<svg>` no longer carries a `data-theme` attribute, so the media query can actually take effect; downstream consumers can still force a theme via `svg[data-theme="light"]` / `svg[data-theme="dark"]`. - **`serializeSvg(scale, opts)`** grew a second argument: `opts.autoTheme: true` switches on the new dual-theme path. The raster pipeline (PNG / JPEG / WebP / Copy to clipboard) explicitly does NOT set it, so those paths keep locking colors to the viewer's current theme — canvas rasterization needs deterministic output and a raster can't react to `prefers-color-scheme` after encoding. - **Background rect in auto-theme mode** now carries `class="c-bg-rect"` + `rect.c-bg-rect { fill: var(--bg); }` instead of a baked-in color, so the backdrop swaps along with the variables. ### Why The v2.0 SVG export was good, but single-theme — users who wanted README embedding still had to export one PNG per theme and wrap them in `<picture><source media="(prefers-color-scheme: dark)">`. A single SVG that already knows both themes cuts that down to `![](archify.svg)`. ## [2.3.1] — 2026-04-15 ### Fixed - **Stale docs referencing the removed scale selector.** `SKILL.md` frontmatter version bumped `2.0` → `2.3`; the two "2x retina" bullets (lines 18, 233) rewritten to describe the current 4× native pipeline + clipboard copy. `README.md` cleaned up in four places: intro paragraph, "What's new" table (now includes v2.2 column), "Export menu" description (no more "scale selector"), and technical-details section (accurate 4× native-rasterization description, not `Image + 2x canvas`). - **Canvas-size clamp for large diagrams.** `rasterize()` now picks the largest integer scale in `{4,3,2,1}` whose `viewBox × scale × scale` fits under a 16 Mpx cap — enough to cover older iOS Safari's silent "blank canvas" ceiling. Default diagrams (viewBox ≈ 1000×680) stay at 4×; only unusually large viewBoxes (say, 1600×1200) step down to 3× automatically. - **`?openExport=1` race with font loading.** Replaced the 60 ms `setTimeout(open)` with `document.fonts.ready.then(open)` (+ double `requestAnimationFrame` to let layout settle). Slow connections no longer get a flashed / mispositioned menu on first paint. ### Added - **Export menu visual grouping.** Two `<hr role="separator">` dividers split the menu into three sections: *Copy to clipboard*, *Download raster (PNG / JPEG / WebP)*, *Download vector (SVG)*. Makes scanning faster and disambiguates "Copy PNG" vs "Download PNG" at a glance. - **Renamed "Copy PNG" → "Copy to clipboard"** with `PNG` moved to the hint badge on the right. The destination ("clipboard") is now in the primary label instead of inferred from context. - **Print stylesheet polish.** Added `@page { size: landscape; margin: 1.5cm; }`, expanded container width in print, switched the summary-card grid to two columns in print so the third card doesn't orphan onto a second page, and added `page-break-inside: avoid` for older browsers that don't understand `break-inside`. ## [2.3.0] — 2026-04-15 ### Fixed - **Raster exports are now genuinely sharp.** Previously the browser rasterized the serialized SVG at its natural `viewBox` dimensions (e.g., 1000×680), and then `ctx.drawImage(img, 0, 0, width*scale, height*scale)` bitmap-upsampled that raster onto the canvas — which just blew up the pixels and produced a soft image. The new flow sets the serialized SVG's `width`/`height` to `4 × viewBox` so the browser rasterizes the vectors at target resolution natively; the canvas then draws at the image's natural size with no scaling. Result: text edges, arrow heads, and stroke details that are actually crisp at 4×. ### Removed - **Scale selector (1× / 2× / 4×).** The selector introduced in 2.1 encouraged picking a low scale to "save file size", which (combined with the upsampling bug above) always produced the softest output. Replaced with a single hardcoded 4× render on every raster export. PNG file sizes grow ~3–4× but the output is visibly sharper. A typical diagram exports to 4000×2720 (~300–700 KB PNG). - `Left` / `Right` arrow key binding (used by the selector) removed from the menu keyboard nav. Up/Down/Home/End/Esc/Tab all preserved. - `archify-export-scale` localStorage key is no longer read or written (old values are harmless leftovers). ### Changed - Toast no longer includes the scale suffix — now just "Copied PNG to clipboard" since the scale is always 4×. - JPEG/WebP quality bumped from 0.92 to 0.95 (file-size delta is tiny at 4× but the encoded edges look cleaner). ## [2.2.1] — 2026-04-15 ### Fixed - **Security group label crowding.** The `sg-name :port` label on the dashed rose boundary sat only ~1px above the Load Balancer box inside it (boundary `y=265 h=80`, inner box `y=280`, label baseline `y=279`). Bumped the boundary to `y=250 h=100` and moved the label to `y=268`, giving ~12px clear gap between the label baseline and the inner component. Same pattern documented in `SKILL.md` so Claude stops generating crowded boundaries. ### Changed - `SKILL.md`: new **Security Group & Region Boundary Padding** section with the 30/50 offset rule (boundary `y = inner.y - 30`, `h = inner.h + 50`, label baseline 18px below boundary top) and a concrete code example. ## [2.2.0] — 2026-04-15 ### Added - **Print stylesheet.** <kbd>Cmd</kbd>+<kbd>P</kbd> (or browser print) now produces a clean, print-ready page: toolbar and toasts hidden, dark background replaced with white, grid removed, card/container borders switched to light gray, `break-inside: avoid` on diagram + cards so nothing splits mid-element. Works regardless of current theme. - **Font fallback improvement for exported images.** The serialized SVG now includes a `local()`-only `@font-face` block for JetBrains Mono at weights 400/500/600/700 so that raster exports can pick up a locally-installed JetBrains Mono (common on developer machines) and fall through cleanly to `ui-monospace` / Menlo otherwise. Previously the sandboxed image-rendering context couldn't reach the Google Fonts URL in the `<link>`, resulting in plain monospace even when users had the font installed. - `archify-print.png` screenshot wired into the README preview section. ## [2.1.0] — 2026-04-15 ### Added - **Copy PNG to clipboard.** New menu action writes the diagram straight to the system clipboard via `ClipboardItem` / `navigator.clipboard.write` so it can be pasted into Slack, Notion, GitHub, Figma, Keynote, etc. Item is dimmed on browsers that don't support clipboard image writes. - **Export scale selector (1× / 2× / 4×)** at the top of the Export menu. Raster downloads and Copy use the selected scale. Selection persists in `localStorage`. Keyboard: <kbd>←</kbd> / <kbd>→</kbd> switch scale. - **Toast feedback** — brief "Copied PNG to clipboard (2×)" confirmation after successful copy. - **URL parameter `?openExport=1`** — auto-opens the Export menu on load. Primarily for deterministic screenshots and live demos. - Screenshot showing the Export menu open (`examples/images/archify-menu.png`) wired into the README preview section. ### Changed - Export menu items renamed from `PNG / JPEG / WebP / SVG` to `Download PNG / JPEG / WebP / SVG` to disambiguate from the new `Copy PNG` action above. - `SCALE` constant replaced by `getScale()` reading from the radiogroup; scale flows through `rasterize()` and clipboard copy alike. ## [2.0.0] — 2026-04-15 First Archify release. Fork / rewrite of [`Cocoon-AI/architecture-diagram-generator`](https://github.com/Cocoon-AI/architecture-diagram-generator) v1.0 (MIT). ### Added - **Dark / Light theme toggle** on every generated diagram. Persists in `localStorage`, respects `prefers-color-scheme` on first visit, overridable per-page via `?theme=dark|light` URL parameter. - **Client-side export menu**: PNG, JPEG, WebP (all 2× retina) and SVG (vector, styles inlined). - **Keyboard shortcuts**: <kbd>T</kbd> toggles theme, <kbd>E</kbd> opens the Export menu. Menu supports <kbd>Arrow</kbd> / <kbd>Home</kbd> / <kbd>End</kbd> / <kbd>Esc</kbd> / <kbd>Tab</kbd>. - **WebP support detection** — menu item is disabled on browsers that can't encode WebP (older Safari) instead of silently saving a mislabeled PNG. - **CSS-variable theme system**: every color lives in a `:root` / `[data-theme="light"]` pair, so both themes render from one SVG markup. - **Semantic SVG classes** in the template: `.c-frontend` / `.c-backend` / `.c-database` / `.c-cloud` / `.c-security` / `.c-messagebus` / `.c-external` plus matching `t-*` text color helpers, `a-*` arrow variants, and `c-mask` / `c-security-group` / `c-region` boundary classes. - **Accessibility**: ARIA roles on the toolbar (`role="toolbar"`, `role="menu"`, `role="menuitem"`), `aria-expanded` / `aria-haspopup` / `aria-pressed` wired up, `:focus-visible` outline, full keyboard navigation. - `v2.0.0` zip package renamed to `archify.zip`; skill identifier is now `archify` so it doesn't collide with users who still have the v1 skill installed. - `CHANGELOG.md` (this file). ### Changed - `SKILL.md` rewritten to steer Claude toward the class-based, themeable system. Contains an explicit "Cardinal Rule: Use CSS Classes, Not Inline Colors" section and a full class reference. - `README.md` rewritten around the new feature set; adds an Attribution section linking the original project. - Example page (`examples/web-app.html`) regenerated using the v2 template so the live demo actually exhibits the theme toggle and export menu. ### Removed - Hardcoded `fill` / `stroke` attributes on SVG components — they broke theme switching and are banned by the new `SKILL.md`. - v1.0 example HTMLs (dark-only, no toolbar) to avoid showing stale output. ### Fixed - **Light-mode exports rendered in dark mode.** The serialized SVG injected the resolved theme variables *before* the host stylesheet, which placed the `:root, [data-theme="dark"] { ... }` rule later in the cascade and overrode the chosen theme. The export pipeline now appends the resolved `:root, svg { ... }` variable block *after* the host CSS so it wins cascade order. - Filename sanitizer now strips leading and trailing hyphens (previously left artifacts like `-project-name-.png` when the title still contained placeholder brackets). ### Known limitations - Exported raster images render text in the system monospace fallback (`ui-monospace` / Menlo / Consolas), not JetBrains Mono. The browser's sandboxed image-rendering context can't fetch Google Fonts. Install JetBrains Mono locally for pixel-perfect exports. --- Original v1.0 design (dark theme, palette, grid background, summary-card layout, JetBrains Mono typography) belongs to Cocoon AI and is preserved.