@laitszkin/apollo-toolkit 3.11.0 → 3.11.2

package/CHANGELOG.md

@@ -10,6 +10,35 @@ All notable changes to this repository are documented in this file.
 
 ### Fixed
 
+## [v3.11.2] - 2026-05-11
+
+### Fixed
+
+- `apltk architecture` / `resolveProjectRoot`: auto-create `resources/project-architecture/` on every command; when no atlas marker is found walking parent directories, use the current working directory as the project root (explicit `--project` still wins). `open` renders a fresh `index.html` when the file is missing so an empty tree bootstraps in one step.
+- Legacy `init-project-html/scripts/architecture.js` `open` / `diff`: same directory creation and one-shot `render` bootstrap via `architecture-bootstrap-render.js` when `index.html` is absent.
+
+### Added
+
+- `init-project-html/scripts/architecture-bootstrap-render.js` helper invoked by the legacy sync `open` path.
+- Tests: `test/atlas-cli.test.js` covers `--project` on a bare directory (layout + `index.html`); `test/architecture-script.test.js` expects legacy `open` to exit 0 when `index.html` is missing after bootstrap.
+
+## [v3.11.1] - 2026-05-11
+
+### Added
+
+- `dataflow add` optional `--fn`, `--reads`, and `--writes` (comma-separated variable names): each internal step can reference a declared function and read/write declared variables in the same sub-module; `validate` rejects unknown names. The renderer draws a function pill plus reads/writes chips on sub-module internal flow diagrams.
+- `init-project-html` / `spec-to-project-html`: **Acceptance criteria** for macro edges (call/return/data-row/failure) and for sub-module diagrams (function flow + variable state); Rule 2 and CLI verb table updated; `TEMPLATE_SPEC.md` documents object-shaped `dataflow` steps and new CSS hooks.
+- Macro atlas UX: each sub-module rectangle is an `<a href="features/<feature>/<sub>.html">` with `aria-label`, nested SVG `<title>` tooltip, `cursor: pointer`, and clearer hover/focus styles.
+
+### Changed
+
+- `layout.js`: `measureSubmodule()` computes per-node width/height from slug, kind label, and `role` so elkjs lays out boxes that fit wrapped role text (replaces fixed 240×92 and the old single-line truncation).
+- `render.js`: macro SVG draws slug, kind, and multi-line role using the same `measureSubmodule()` output as layout; sub-dataflow SVG renders enriched steps with fn pill and reads/writes chips (from prior work in this release train, now validated and documented).
+
+### Fixed
+
+- `viewer.client.js`: defer pointer capture until the pointer moves past a small drag threshold so clicks on macro sub-module links navigate; swallow the synthetic click after an actual drag so pan does not accidentally open a page.
+
 ## [v3.11.0] - 2026-05-11
 
 ### Added

package/init-project-html/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: init-project-html
 description: >-
-  Declare the project HTML architecture atlas through `apltk architecture` CLI verbs instead of hand-writing SVG/HTML. The tool owns layout, no-overlap, DOM, CSS, and pan/zoom; the agent only declares features, sub-modules, functions, variables, dataflow steps, errors, and edges. Macro `index.html` always shows feature clusters with their sub-modules and every cross/intra-feature edge; each sub-module page describes only itself (function I/O + variables-with-business-purpose + internal dataflow + local errors); feature index pages stay lightweight. Read strategy avoids context loss: list feature modules first, then either dispatch one read-only subagent per feature and aggregate summaries before declaring, or process one feature at a time end-to-end. Anchor every declaration to repo evidence.
+  Declare the project HTML architecture atlas through `apltk architecture` CLI verbs instead of hand-writing SVG/HTML. Two acceptance criteria gate completion: (1) the macro diagram clearly shows feature × sub-module relationships — data flow, call/return interaction logic, error handling, rollback — all expressed as `--kind call|return|data-row|failure` edges; (2) each sub-module's internal diagram clearly shows function-level interactions inside it — function-to-function flow via `dataflow add --fn <declared-fn>`, variable state transitions via `--reads`/`--writes` referencing declared variables, and the resulting local data flow. The tool owns layout, CSS, and pan/zoom for both diagrams; `validate` rejects any step that references an undeclared function or variable. With subagents, each owns one feature and declares every intra-feature interaction itself; the main agent only declares cross-feature edges. Anchor every declaration to repo evidence.
 ---
 
 # Init Project HTML
@@ -19,25 +19,36 @@ description: >-
 
 The atlas state lives in `resources/project-architecture/atlas/` (`atlas.index.yaml` + per-feature YAMLs). Every change goes through `apltk architecture <verb> ...`. After any mutation, the CLI re-renders `resources/project-architecture/**/*.html` with the correct layout, CSS, pan/zoom, and ARIA — agents **MUST NOT** edit those HTML files by hand or invent additional ones.
 
-### Rule 2 — Sub-module pages describe only themselves
+### Rule 2 — Sub-module pages describe only themselves; the internal-dataflow diagram is zoomable and structurally typed
 
 What the CLI emits on each sub-module page is fixed:
 
 - function I/O table (`function add --feature X --submodule Y --name fn --in ... --out ... --side ... --purpose ...`),
 - variables-with-business-purpose table (`variable add --name v --type T --scope call|tx|persist|instance|loop --purpose ...`),
-- internal dataflow steps (`dataflow add --step "..."`),
+- internal dataflow diagram — ordered steps the renderer lays out as a numbered top-to-bottom flow inside a pan/zoom viewport with +/−/Fit controls, exactly like the macro SVG. Each step is `dataflow add --step "..." [--fn <declared-fn>] [--reads "v1,v2"] [--writes "v3,v4"]`. The renderer surfaces `--fn` as a pill at the top of the step box, `--reads` as a green chip on the bottom-left, and `--writes` as an orange chip on the bottom-right — so a single SVG simultaneously shows the function-to-function flow inside the sub-module AND the variable state transitions across the run,
 - local errors (`error add --name ErrX --when ... --means ...`).
 
-Cross-boundary narratives ("I call X", "Y calls me") **MUST** be expressed as macro edges (`edge add --from X/sub --to Y/sub --kind call|return|data-row|failure --label ...`), never as sub-module page prose. The CLI enforces this by design — there is no verb to add cross-boundary text to a sub-module page.
+Schema rules the CLI enforces on every `dataflow add` (so the diagram never lies):
 
-### Rule 3 — Read order: never let the codebase wipe the context window
+- `--fn <name>` must match a function declared **in the same sub-module** via `function add`. If it does not, `validate` fails — declare the function first.
+- Every name in `--reads` / `--writes` must match a variable declared **in the same sub-module** via `variable add`. If it does not, `validate` fails — declare the variable first.
+- `--fn` / `--reads` / `--writes` are optional but additive: omitting them is allowed for purely descriptive steps, but for any non-trivial sub-module the function-and-variable structure **MUST** be filled in so the diagram conveys the function-to-function flow and the variable state transitions.
 
-Real production codebases dwarf the main agent's context. Reading the whole repo before declaring pushes early details out by the end, making macro edges and sub-module declarations contradict each other. **MUST** follow one of:
+Cross-boundary narratives ("I call X", "Y calls me") **MUST** be expressed as edges (`edge add --from X/sub --to Y/sub --kind call|return|data-row|failure --label ...`), never as sub-module page prose. The CLI enforces this by design — there is no verb to add cross-boundary text to a sub-module page.
 
-- **With subagents (preferred):** first enumerate the **feature-module list** (slug + entry + boundary resources only). Then dispatch **one read-only subagent per feature**. Each subagent deep-reads and returns ONLY a structured summary (sub-module list with kind/role; per sub-module: function I/O, variables-with-business-purpose, internal dataflow steps, errors; outbound edges to other features). The main agent collects every summary first, then drives the CLI in one pass to declare every component.
-- **Without subagents:** process features **one at a time** — read feature A end-to-end, then declare it via the CLI (`feature add`, `submodule add`, `function add`, `variable add`, `dataflow add`, `error add`, intra-feature `edge add`). For cross-feature edges that point at not-yet-declared features, declare the placeholder feature with `feature add --slug <future> --title <future>` first, then add the edge; subsequent passes set the real title/story. Drop A's function-level details from working memory before reading feature B.
+### Rule 3 — Read order: never let the codebase wipe the context window; subagents own their own feature
 
-Both paths share one invariant: at any moment the main agent only holds *current-feature details + cross-feature boundary notes*. Run `apltk architecture validate` after the last feature to catch dangling edges, unknown endpoints, or missing required fields.
+Real production codebases dwarf the main agent's context. Reading the whole repo before declaring pushes early details out by the end, making macro edges and sub-module declarations contradict each other. The split below also draws a hard responsibility line between the worker and the orchestrator. **MUST** follow one of:
+
+- **With subagents (preferred):** first enumerate the **feature-module list** (slug + entry + boundary resources only). Then dispatch **one (write-capable) subagent per feature**. Each subagent:
+  - deep-reads its own feature,
+  - declares **everything intra-feature** itself via `apltk architecture ... --feature <slug>` (sub-modules; per sub-module functions / variables / internal dataflow / errors; **every intra-feature edge** — function calls between sub-modules, error edges, rollback / compensation edges; variable state transitions are captured as ordered `dataflow add` steps on each sub-module),
+  - returns ONLY a structured summary of (i) the sub-module list and (ii) the **outbound boundaries** the main agent needs to wire (calls / data-rows / failure edges to other features' sub-modules, including direction and the consuming/producing endpoints).
+
+  The main agent never re-reads source for that feature. It collects every subagent's outbound-boundary summary and declares **only the cross-feature edges** (and any cross-feature actors / meta) itself, then runs `apltk architecture validate`.
+- **Without subagents:** process features **one at a time** — read feature A end-to-end, declare its sub-modules, functions, variables, internal dataflow, errors, and intra-feature edges via the CLI, then move on. For cross-feature edges that point at not-yet-declared features, declare the placeholder feature with `feature add --slug <future> --title <future>` first, then add the edge; subsequent passes set the real title/story. Drop A's function-level details from working memory before reading feature B.
+
+Both paths share one invariant: at any moment the agent doing the deep read only holds *that feature's details + cross-feature boundary notes*. The main agent's working set, in subagent mode, is **boundaries only**. Run `apltk architecture validate` after the last feature to catch dangling edges, unknown endpoints, or missing required fields.
 
 ### Rule 4 — Evidence over invention
 
@@ -51,6 +62,22 @@ Both paths share one invariant: at any moment the main agent only holds *current
 - **Quality**: macro SVG carries every cross-feature data-row edge that exists in the system; sub-module declarations are self-only; pan/zoom + Fit work in the rendered HTML; `apltk architecture validate` returns OK.
 - **Output**: `resources/project-architecture/atlas/` (YAML state) + `resources/project-architecture/**/*.html` (renderer output) — both managed by the CLI.
 
+## Acceptance criteria
+
+The atlas is only complete when both of the following are demonstrably true on the rendered HTML (open `resources/project-architecture/index.html` and one representative sub-module page to verify):
+
+1. **Macro diagram clearly shows the relationships between features and sub-modules**, including:
+   - **Data flow** — every cross-feature DB row, queue topic, or cache key hand-off is a `--kind data-row` edge between the producing and consuming sub-modules (not free-form prose).
+   - **Interaction logic** — synchronous request/response paths are paired `--kind call` (outbound) and `--kind return` (response) edges with a label that names the call site or response shape.
+   - **Error handling and rollback** — every failure / compensation / retry path that crosses a sub-module boundary is a `--kind failure` edge with a label that names what is being rolled back or compensated.
+   - No interaction is captured *only* in sub-module page prose — if it crosses a sub-module boundary it MUST appear as an edge so the macro SVG carries it.
+2. **Each sub-module's internal diagram clearly shows the function-level interactions inside the sub-module**, including:
+   - **Function-to-function flow** — every step that does non-trivial work carries `--fn <declared-fn>`. The sequence of pills along the steps reveals which function is active at each point in the flow.
+   - **Variable state transitions during the run** — every variable that is read or mutated by a step is declared via `variable add`, and that step lists it in `--reads` (the value flows in) or `--writes` (the value is created/updated). Reading the steps top-to-bottom traces each variable's life cycle.
+   - **Local data flow** — the ordered step boxes (with reads/writes chips) read as a directed flowchart, ending at the sub-module boundary (returning a value, persisting a row, emitting an event).
+
+`apltk architecture validate` MUST return OK before reporting completion — it enforces both criteria's structural pieces (unknown sub-modules on edges, unknown functions/variables referenced by dataflow steps).
+
 ## How to use `apltk architecture`
 
 Each verb is a single mutation; the CLI auto-renders after every change. Pass `--no-render` when batching mutations. Global flags: `--project <root>`, `--spec <spec_dir>` (writes to overlay; see `spec-to-project-html`), `--no-render`, `--no-open`.
@@ -63,7 +90,7 @@ Each verb is a single mutation; the CLI auto-renders after every change. Pass `-
 | `apltk architecture submodule add --feature <slug> --slug <kebab> --kind ui\|api\|service\|db\|pure-fn\|queue\|external --role "..."` | Declare a sub-module under a feature. |
 | `apltk architecture function add --feature X --submodule Y --name fn --in "T1, T2" --out "R \| ErrX" --side pure\|io\|write\|tx\|lock\|network --purpose "..."` | Add a function I/O row. |
 | `apltk architecture variable add --feature X --submodule Y --name v --type T --scope call\|tx\|persist\|instance\|loop --purpose "..."` | Add a variable-with-business-purpose row. |
-| `apltk architecture dataflow add --feature X --submodule Y --step "..." [--at N]` | Append (or insert at index `N`) an internal dataflow step. |
+| `apltk architecture dataflow add --feature X --submodule Y --step "..." [--fn <declared-fn>] [--reads "v1,v2"] [--writes "v3,v4"] [--at N]` | Append (or insert at index `N`) an internal dataflow step. `--fn` must match a previously declared `function`; every name in `--reads` / `--writes` must match a previously declared `variable` in the same sub-module — the renderer surfaces them as a function pill + reads/writes chips so the diagram shows function-to-function flow and variable state transitions. |
 | `apltk architecture dataflow reorder --feature X --submodule Y --from i --to j` | Move a step within the same sub-module. |
 | `apltk architecture error add --feature X --submodule Y --name ErrCode --when "..." --means "..."` | Add a local error row. |
 | `apltk architecture edge add --from <feature>[/sub] --to <feature>[/sub] --kind call\|return\|data-row\|failure --label "..." [--id <stable>]` | Add an edge. Intra-feature edges (both endpoints in the same feature with sub-modules) land in the feature YAML; cross-feature edges land in `atlas.index.yaml`. |
@@ -86,25 +113,32 @@ Scan the shipped source for **user-visible capabilities** (each one = one featur
 
 ### 2) Branch the deep-read by environment (Rule 3)
 
-#### 2A) With subagents (preferred)
+#### 2A) With subagents (preferred) — workers own their feature; main agent owns the macro seams
 
-Dispatch one read-only subagent per feature. Require this summary template (no source-code excerpts):
+Dispatch one **write-capable** subagent per feature, plus the main agent for the macro layer. Hand each subagent: its feature slug, the feature-module list from step 1 (so it knows other features' slugs for outbound edges), and access to `apltk architecture`. Each subagent **declares its own feature end-to-end** and only reports outbound boundaries upward:
 
-> **Feature `<slug>` summary**
-> - Sub-module list: one row per `<sub-module-slug>` (kind: ui / api / service / db / pure-fn / queue / external; one-line role).
-> - Per sub-module: function signatures (in / out / side / purpose), variables-with-business-purpose, internal dataflow steps, errors raised.
-> - **Outbound boundaries**: call edges to other features' sub-modules; data-row edges through shared DB tables / topics / cache keys with another feature; mark direction.
+> **Feature `<slug>` subagent contract**
+> - Read every sub-module of this feature.
+> - Run `feature add --slug <slug> --title "..." --story "..." --no-render` (or `feature set` if a placeholder already exists).
+> - For every sub-module: `submodule add` with the right `--kind`, then add its `function`, `variable`, `dataflow` (ordered — these steps carry the variable state transitions through the flow), and `error` rows.
+> - For every intra-feature interaction between sub-modules — function calls, returns, error propagation, rollback / compensation — emit `edge add --from <slug>/<a> --to <slug>/<b> --kind call|return|data-row|failure --label "..."`. Failure / rollback flows belong here: model them as additional `--kind failure` edges or as ordered `dataflow add` steps on the affected sub-modules, whichever maps to the real code path.
+> - Run `apltk architecture validate` (scoped to this feature) before returning.
+> - **Return ONLY**: (i) sub-module list (slug + kind + one-line role), (ii) outbound boundaries to *other* features' sub-modules (direction + edge kind + suggested label). No source excerpts, no function bodies.
 
-Main agent collects every summary, then drives the CLI in one pass:
+Main agent — after every subagent returns — declares **only** macro-level state from the aggregated outbound boundaries:
 
 ```bash
 apltk architecture meta set --title "..." --summary "..." --no-render
-apltk architecture feature add --slug <slug> --title "..." --story "..." --no-render
-# repeat submodule / function / variable / dataflow / error / edge add for the whole atlas
+# only when an actor is shared across multiple features:
+apltk architecture actor add --id <id> --label "..." --no-render
+# one edge per cross-feature interaction reported by the subagents:
+apltk architecture edge add --from <featA>/<subA> --to <featB>/<subB> --kind call|return|data-row|failure --label "..." --no-render
 apltk architecture render
 apltk architecture validate
 ```
 
+The main agent **MUST NOT** re-declare a subagent's intra-feature components, and **MUST NOT** open source files for any feature it delegated.
+
 #### 2B) Without subagents — feature-by-feature read-declare loop
 
 Process the list from step 1 one feature at a time (topological hint: read-from data sources and pure helpers first, user-facing entries last). Per feature:
@@ -126,8 +160,10 @@ Report: feature count, sub-module count, macro edge counts (call / return / data
 ## Sample hints
 
 - Multiple SQL paths on `service ↔ db` → call `edge add` once per SQL path so the macro shows them as separate edges.
-- Retry loops between `service ↔ generator(pure)` → call/return pair in the macro plus a dataflow step in the service describing the retry budget.
+- Retry loops between `service ↔ generator(pure)` → call/return pair in the macro plus a `dataflow add` step in the service with `--fn issueCode --writes "code"` describing the retry budget; a follow-up step `--fn issueCode --reads "code" --writes "row"` then captures the persistence attempt.
+- Variable state transitions inside one function (e.g. `code` is computed, persisted, then returned) → emit one `dataflow add` per logical mutation, with `--fn` constant and `--reads` / `--writes` listing every variable that changes shape at that point. The sub-module page chips trace each variable's life cycle top-to-bottom.
 - Cross-feature DB hand-off (A writes, B reads) → declare both sides' `INSERT_*` / `SELECT_*` functions on the `db` sub-module, then `edge add --kind data-row` from producer feature/submodule to consumer feature/submodule.
+- Rollback / compensation across sub-modules → `edge add --kind failure --label "rollback on dup"`; rollback *within* a single sub-module belongs in `dataflow add` (with `--fn` set to whichever function owns the cleanup).
 - Third-party systems → declare as `--kind external` sub-modules; the trust boundary becomes visible because the renderer styles them differently.
 
 ## References

package/init-project-html/agents/openai.yaml

@@ -3,11 +3,11 @@ interface:
   short_description: "Declare the project HTML architecture atlas through `apltk architecture` CLI verbs"
   default_prompt: >-
     Use $init-project-html. Its `SKILL.md` is the authoritative rulebook; `references/TEMPLATE_SPEC.md` is a component-schema cheat sheet.
-    NEVER hand-author files under `resources/project-architecture/**/*.html`. The atlas state lives in YAML under `resources/project-architecture/atlas/` and every mutation goes through `apltk architecture <verb> ...`; the CLI owns layout, no-overlap, DOM, CSS, ARIA, and pan/zoom.
-    Read strategy to avoid context loss on large codebases. STEP 1: enumerate the feature-module list (slug + entry + boundary resources) WITHOUT diving into function bodies.
+    NEVER hand-author files under `resources/project-architecture/**/*.html`. The atlas state lives in YAML under `resources/project-architecture/atlas/` and every mutation goes through `apltk architecture <verb> ...`; the CLI owns layout, no-overlap, DOM, CSS, ARIA, and pan/zoom — both the macro SVG and each sub-module's internal-dataflow diagram are zoomable.
+    Read strategy to avoid context loss AND to enforce a hard responsibility split. STEP 1: enumerate the feature-module list (slug + entry + boundary resources) WITHOUT diving into function bodies.
     STEP 2: branch by environment.
-    (2A, preferred) if subagents are available, dispatch ONE read-only subagent per feature; each returns ONLY a structured summary (sub-modules with kind/role; per sub-module: function I/O, variables-with-business-purpose, internal dataflow steps, errors raised; outbound edges to other features). The main agent collects every summary first, then runs the CLI in one batched pass.
-    (2B, no subagents) process features ONE AT A TIME — deep-read feature A, IMMEDIATELY drive the CLI (`feature add`, `submodule add` x N, `function add` / `variable add` / `dataflow add` / `error add` rows, intra-feature `edge add`), drop A's function-level details from working memory, then move to feature B. For cross-feature edges pointing at a not-yet-declared feature, declare a placeholder with `feature add --slug <future> --title <future>` first and refine its title/story on a later pass.
+    (2A, preferred) if subagents are available, dispatch ONE write-capable subagent per feature. Each subagent deep-reads ITS OWN feature and declares EVERY intra-feature interaction itself via `apltk architecture ... --feature <slug>`: `submodule add` (with the right `--kind`), `function add` / `variable add` / `dataflow add` (ordered — these steps carry the variable state transitions through the flow) / `error add` rows on every sub-module, and **every intra-feature edge** between its sub-modules (function calls, returns, error propagation, rollback / compensation — model failure / rollback paths as `--kind failure` edges and/or as ordered `dataflow add` steps). The subagent returns ONLY (i) sub-module list (slug + kind + one-line role) and (ii) outbound boundaries to other features' sub-modules (direction + edge kind + suggested label). The main agent never re-reads source for a delegated feature and never re-declares its components — it batches ONLY cross-feature `edge add` (and any shared `actor` / `meta`) from the aggregated outbound summaries, then runs `apltk architecture render` and `apltk architecture validate`.
+    (2B, no subagents) process features ONE AT A TIME — deep-read feature A, IMMEDIATELY drive the CLI (`feature add`, `submodule add` x N, `function add` / `variable add` / `dataflow add` / `error add` rows, intra-feature `edge add` including failure / rollback edges), drop A's function-level details from working memory, then move to feature B. For cross-feature edges pointing at a not-yet-declared feature, declare a placeholder with `feature add --slug <future> --title <future>` first and refine its title/story on a later pass.
     CLI verbs to declare components (always kebab-case slugs; pass `--no-render` to batch then call `apltk architecture render` once at the end):
     `apltk architecture meta set --title "..." --summary "..."`,
     `apltk architecture actor add --id <kebab> --label "..."`,
@@ -15,8 +15,8 @@ interface:
     `apltk architecture submodule add --feature X --slug Y --kind ui|api|service|db|pure-fn|queue|external --role "..."`,
     `apltk architecture function add --feature X --submodule Y --name fn --in "T1, T2" --out "R | ErrX" --side pure|io|write|tx|lock|network --purpose "..."`,
     `apltk architecture variable add --feature X --submodule Y --name v --type T --scope call|tx|persist|instance|loop --purpose "..."`,
-    `apltk architecture dataflow add --feature X --submodule Y --step "..." [--at N]`,
+    `apltk architecture dataflow add --feature X --submodule Y --step "..." [--fn <declared-fn>] [--reads "v1,v2"] [--writes "v3,v4"] [--at N]` (use `--fn` to surface function-to-function flow inside the sub-module; use `--reads` / `--writes` to surface variable state transitions — every name MUST match a `function`/`variable` already declared in the SAME sub-module or `validate` fails),
     `apltk architecture error add --feature X --submodule Y --name ErrCode --when "..." --means "..."`,
     `apltk architecture edge add --from <feature>[/sub] --to <feature>[/sub] --kind call|return|data-row|failure --label "..." [--id <stable>]`.
     Intra-feature edges (both endpoints in the same feature with sub-modules) land in the feature YAML; cross-feature edges land in `atlas.index.yaml`. After the last mutation run `apltk architecture validate` — must return OK; resolve every reported error before reporting completion.
-    Each sub-module page describes ONLY itself (`sub-io` function I/O + `sub-vars` variables-with-business-purpose + `sub-dataflow` internal flow + `sub-errors` local errors) — express any cross-boundary interaction as a macro edge, never as sub-module page prose. Anchor every declaration to a concrete path / symbol / SQL / config; mark TBD when evidence is missing; record scanned roots and deliberate omissions in `meta.summary`. Report which read strategy (2A or 2B) was actually used and the location of the rendered atlas (`resources/project-architecture/index.html`).
+    Each sub-module page describes ONLY itself (`sub-io` function I/O + `sub-vars` variables-with-business-purpose + `sub-dataflow` zoomable internal flow with fn pill + reads/writes chips + `sub-errors` local errors) — express any cross-boundary interaction as an edge, never as sub-module page prose. Two acceptance criteria gate completion: (1) the macro diagram clearly shows feature×sub-module relationships — data flow, call/return interaction logic, error handling, rollback — all as `--kind call|return|data-row|failure` edges (no cross-boundary path expressed only as prose); (2) every non-trivial sub-module's internal diagram clearly shows function-level interactions — `dataflow add --fn <declared-fn>` for function-to-function flow + `--reads` / `--writes` for variable state transitions through the run. Anchor every declaration to a concrete path / symbol / SQL / config; mark TBD when evidence is missing; record scanned roots and deliberate omissions in `meta.summary`. Report which read strategy (2A or 2B) was actually used and the location of the rendered atlas (`resources/project-architecture/index.html`).

package/init-project-html/lib/atlas/assets/architecture.css

@@ -74,11 +74,17 @@ p { line-height: 1.55; color: var(--text); }
 /* ---- SVG macro ---- */
 .m-cluster__bg { fill: rgba(15, 23, 42, 0.55); stroke: var(--border); stroke-width: 1; }
 .m-cluster__title { font-family: ui-sans-serif, system-ui, sans-serif; font-size: 14px; fill: var(--text); font-weight: 600; letter-spacing: 0.04em; text-transform: uppercase; }
-.m-node rect { fill: var(--panel-soft); stroke: var(--border); stroke-width: 1; transition: stroke 120ms ease; }
-.m-node:hover rect { stroke: var(--accent); }
+.m-node { cursor: pointer; }
+.m-node rect { fill: var(--panel-soft); stroke: var(--border); stroke-width: 1; transition: stroke 120ms ease, fill 120ms ease; }
+.m-node:hover rect,
+.m-node:focus rect,
+.m-node:focus-visible rect { stroke: var(--accent); stroke-width: 1.6; fill: rgba(56, 189, 248, 0.08); }
+.m-node:focus { outline: none; }
 .m-node__title { font-size: 13px; font-weight: 600; fill: var(--text); }
 .m-node__kind { font-size: 11px; fill: var(--muted); }
 .m-node__role { font-size: 11px; fill: var(--muted); }
+.m-node:hover .m-node__title,
+.m-node:focus .m-node__title { fill: var(--accent); }
 
 .m-node--ui rect { stroke: var(--kind-ui); }
 .m-node--api rect { stroke: var(--kind-api); }
@@ -133,8 +139,23 @@ p { line-height: 1.55; color: var(--text); }
 
 .sub-section__empty { color: var(--muted); font-style: italic; font-size: 13px; }
 
-.sub-dataflow__svg { width: 100%; max-width: 480px; }
-.sub-dataflow__step rect { fill: var(--panel); stroke: var(--border); }
-.sub-dataflow__step text { fill: var(--text); font-size: 13px; }
-.sub-dataflow__arrow { stroke: var(--muted); stroke-width: 1.4; }
+.sub-dataflow__canvas { position: relative; background: var(--panel); border: 1px solid var(--border); border-radius: 12px; padding: 16px; }
+.sub-dataflow__toolbar { position: absolute; top: 16px; right: 16px; display: flex; gap: 4px; z-index: 2; }
+.sub-dataflow__toolbar button { background: var(--panel-soft); color: var(--text); border: 1px solid var(--border); padding: 4px 12px; border-radius: 6px; cursor: pointer; font-size: 13px; }
+.sub-dataflow__toolbar button:hover { border-color: var(--accent); color: var(--accent); }
+.sub-dataflow__viewport { width: 100%; max-height: 60vh; overflow: hidden; border-radius: 8px; background: #0b1220; }
+.sub-dataflow__viewport.is-grabbing { cursor: grabbing; }
+.sub-dataflow__viewport:not(.is-grabbing) { cursor: grab; }
+.sub-dataflow__svg { width: 100%; height: auto; max-height: 60vh; display: block; user-select: none; touch-action: none; }
+.sub-dataflow__badge { fill: var(--panel-soft); stroke: var(--accent); stroke-width: 1.4; }
+.sub-dataflow__badge-text { font-family: ui-sans-serif, system-ui, sans-serif; font-size: 13px; font-weight: 600; fill: var(--accent); }
+.sub-dataflow__step .sub-dataflow__box { fill: var(--panel-soft); stroke: var(--border); stroke-width: 1; }
+.sub-dataflow__step:hover .sub-dataflow__box { stroke: var(--accent); }
+.sub-dataflow__text { font-family: ui-sans-serif, system-ui, sans-serif; font-size: 14px; fill: var(--text); }
+.sub-dataflow__arrow { stroke: var(--muted); stroke-width: 1.6; }
+.sub-dataflow__fn-bg { fill: rgba(56, 189, 248, 0.12); stroke: var(--accent); stroke-width: 1; }
+.sub-dataflow__fn-text { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 11px; font-weight: 600; fill: var(--accent); letter-spacing: 0.02em; }
+.sub-dataflow__chip { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 11px; font-weight: 500; }
+.sub-dataflow__chip--reads { fill: var(--kind-service); }
+.sub-dataflow__chip--writes { fill: var(--kind-db); }
 .sub-dataflow__empty { color: var(--muted); font-style: italic; }

package/init-project-html/lib/atlas/assets/viewer.client.js

@@ -1,93 +1,136 @@
-/* viewer.client.js — pan/zoom for the macro atlas SVG. No deps; wires
- * onto any element marked [data-pan-zoom-viewport] containing one
- * [data-atlas-svg] SVG. Mouse wheel zooms around the cursor; drag pans;
- * toolbar buttons handle +/-/Fit; keyboard arrows pan. */
+/* viewer.client.js — pan/zoom for every atlas SVG on the page.
+ *
+ * Each `[data-pan-zoom-viewport]` element gets its own state and
+ * handlers, so a single page can host the macro atlas SVG AND
+ * sub-module-internal dataflow SVGs simultaneously. Toolbar buttons
+ * (`[data-pan-zoom="zoom-in|zoom-out|fit"]`) are scoped to the
+ * containing `[data-pan-zoom-container]` (falls back to the viewport's
+ * direct parent), so multiple toolbars on one page do not collide.
+ * Keyboard shortcuts (`←` / `→` / `↑` / `↓` / `+` / `−` / `0`) drive
+ * the page's first viewport — the "primary" diagram of that page
+ * (macro SVG on `index.html`; sub-dataflow SVG on a sub-module page).
+ */
 
 (function () {
   'use strict';
 
-  const viewport = document.querySelector('[data-pan-zoom-viewport]');
-  if (!viewport) return;
-  const svg = viewport.querySelector('[data-atlas-svg]');
-  if (!svg) return;
+  const viewports = Array.from(document.querySelectorAll('[data-pan-zoom-viewport]'));
+  const controllers = viewports.map(setupViewport).filter(Boolean);
+  if (controllers.length === 0) return;
 
-  const initial = svg.getAttribute('viewBox');
-  if (!initial) return;
-  const [ix, iy, iw, ih] = initial.split(/\s+/).map(Number);
-  const state = { x: ix, y: iy, w: iw, h: ih };
-
-  function apply() {
-    svg.setAttribute('viewBox', `${state.x} ${state.y} ${state.w} ${state.h}`);
-  }
+  const primary = controllers[0];
+  document.addEventListener('keydown', function (evt) {
+    if (evt.target && (evt.target.tagName === 'INPUT' || evt.target.tagName === 'TEXTAREA')) return;
+    if (evt.key === 'ArrowLeft') { primary.pan(-1, 0); }
+    else if (evt.key === 'ArrowRight') { primary.pan(1, 0); }
+    else if (evt.key === 'ArrowUp') { primary.pan(0, -1); }
+    else if (evt.key === 'ArrowDown') { primary.pan(0, 1); }
+    else if (evt.key === '+' || evt.key === '=') { primary.zoom(1 / 1.2); }
+    else if (evt.key === '-' || evt.key === '_') { primary.zoom(1.2); }
+    else if (evt.key === '0') { primary.fit(); }
+  });
 
-  function zoom(factor, cx, cy) {
-    const newW = Math.max(40, Math.min(state.w * factor, iw * 8));
-    const newH = newW * (state.h / state.w);
-    if (cx == null) { cx = state.x + state.w / 2; cy = state.y + state.h / 2; }
-    state.x = cx - (cx - state.x) * (newW / state.w);
-    state.y = cy - (cy - state.y) * (newH / state.h);
-    state.w = newW;
-    state.h = newH;
-    apply();
-  }
+  function setupViewport(viewport) {
+    const svg = viewport.querySelector('[data-atlas-svg]');
+    if (!svg) return null;
+    const initial = svg.getAttribute('viewBox');
+    if (!initial) return null;
+    const [ix, iy, iw, ih] = initial.split(/\s+/).map(Number);
+    const state = { x: ix, y: iy, w: iw, h: ih };
 
-  function clientToSvg(evt) {
-    const rect = svg.getBoundingClientRect();
-    const xRatio = (evt.clientX - rect.left) / rect.width;
-    const yRatio = (evt.clientY - rect.top) / rect.height;
-    return { x: state.x + xRatio * state.w, y: state.y + yRatio * state.h };
-  }
+    function apply() {
+      svg.setAttribute('viewBox', `${state.x} ${state.y} ${state.w} ${state.h}`);
+    }
+    function fit() {
+      state.x = ix; state.y = iy; state.w = iw; state.h = ih;
+      apply();
+    }
+    function zoom(factor, cx, cy) {
+      const newW = Math.max(40, Math.min(state.w * factor, iw * 8));
+      const newH = newW * (state.h / state.w);
+      if (cx == null) { cx = state.x + state.w / 2; cy = state.y + state.h / 2; }
+      state.x = cx - (cx - state.x) * (newW / state.w);
+      state.y = cy - (cy - state.y) * (newH / state.h);
+      state.w = newW;
+      state.h = newH;
+      apply();
+    }
+    function pan(dirX, dirY) {
+      const stepX = state.w * 0.08;
+      const stepY = state.h * 0.08;
+      state.x += dirX * stepX;
+      state.y += dirY * stepY;
+      apply();
+    }
+    function clientToSvg(evt) {
+      const rect = svg.getBoundingClientRect();
+      const xRatio = (evt.clientX - rect.left) / rect.width;
+      const yRatio = (evt.clientY - rect.top) / rect.height;
+      return { x: state.x + xRatio * state.w, y: state.y + yRatio * state.h };
+    }
 
-  viewport.addEventListener('wheel', function (evt) {
-    if (!evt.ctrlKey && !evt.metaKey && Math.abs(evt.deltaY) < 4 && Math.abs(evt.deltaX) < 4) return;
-    evt.preventDefault();
-    const factor = evt.deltaY > 0 ? 1.1 : 1 / 1.1;
-    const pt = clientToSvg(evt);
-    zoom(factor, pt.x, pt.y);
-  }, { passive: false });
+    viewport.addEventListener('wheel', function (evt) {
+      if (!evt.ctrlKey && !evt.metaKey && Math.abs(evt.deltaY) < 4 && Math.abs(evt.deltaX) < 4) return;
+      evt.preventDefault();
+      const factor = evt.deltaY > 0 ? 1.1 : 1 / 1.1;
+      const pt = clientToSvg(evt);
+      zoom(factor, pt.x, pt.y);
+    }, { passive: false });
 
-  let dragging = null;
-  viewport.addEventListener('pointerdown', function (evt) {
-    if (evt.button !== 0) return;
-    dragging = { x: evt.clientX, y: evt.clientY };
-    viewport.classList.add('is-grabbing');
-    viewport.setPointerCapture(evt.pointerId);
-  });
-  viewport.addEventListener('pointermove', function (evt) {
-    if (!dragging) return;
-    const rect = svg.getBoundingClientRect();
-    const dx = ((evt.clientX - dragging.x) / rect.width) * state.w;
-    const dy = ((evt.clientY - dragging.y) / rect.height) * state.h;
-    state.x -= dx;
-    state.y -= dy;
-    dragging = { x: evt.clientX, y: evt.clientY };
-    apply();
-  });
-  function endDrag(evt) {
-    if (!dragging) return;
-    dragging = null;
-    viewport.classList.remove('is-grabbing');
-    try { viewport.releasePointerCapture(evt.pointerId); } catch (e) { /* ignore */ }
-  }
-  viewport.addEventListener('pointerup', endDrag);
-  viewport.addEventListener('pointercancel', endDrag);
-  viewport.addEventListener('pointerleave', endDrag);
+    // Drag-pan: defer the pointer capture (and the "is-grabbing" class)
+    // until the pointer actually moves past a small threshold. Without
+    // this, a single click on an SVG <a> (sub-module link) would be
+    // captured by the viewport and never reach the link.
+    const DRAG_THRESHOLD_PX = 4;
+    let pending = null;
+    let dragging = null;
+    viewport.addEventListener('pointerdown', function (evt) {
+      if (evt.button !== 0) return;
+      pending = { x: evt.clientX, y: evt.clientY, pointerId: evt.pointerId };
+    });
+    viewport.addEventListener('pointermove', function (evt) {
+      if (!dragging && pending && pending.pointerId === evt.pointerId) {
+        const dx = evt.clientX - pending.x;
+        const dy = evt.clientY - pending.y;
+        if (Math.hypot(dx, dy) < DRAG_THRESHOLD_PX) return;
+        dragging = { x: pending.x, y: pending.y, pointerId: pending.pointerId };
+        pending = null;
+        viewport.classList.add('is-grabbing');
+        try { viewport.setPointerCapture(dragging.pointerId); } catch (e) { /* ignore */ }
+      }
+      if (!dragging || dragging.pointerId !== evt.pointerId) return;
+      evt.preventDefault();
+      const rect = svg.getBoundingClientRect();
+      const dx = ((evt.clientX - dragging.x) / rect.width) * state.w;
+      const dy = ((evt.clientY - dragging.y) / rect.height) * state.h;
+      state.x -= dx;
+      state.y -= dy;
+      dragging.x = evt.clientX;
+      dragging.y = evt.clientY;
+      apply();
+    });
+    function endDrag(evt) {
+      pending = null;
+      if (!dragging) return;
+      const draggedId = dragging.pointerId;
+      dragging = null;
+      viewport.classList.remove('is-grabbing');
+      try { viewport.releasePointerCapture(draggedId); } catch (e) { /* ignore */ }
+      // Suppress the synthetic click that would follow a drag-release
+      // on top of a sub-module <a>; only the no-movement case should
+      // navigate.
+      const swallow = (e) => { e.preventDefault(); e.stopPropagation(); };
+      viewport.addEventListener('click', swallow, { capture: true, once: true });
+    }
+    viewport.addEventListener('pointerup', endDrag);
+    viewport.addEventListener('pointercancel', endDrag);
+    viewport.addEventListener('pointerleave', endDrag);
 
-  document.addEventListener('keydown', function (evt) {
-    if (evt.target && (evt.target.tagName === 'INPUT' || evt.target.tagName === 'TEXTAREA')) return;
-    const step = state.w * 0.08;
-    if (evt.key === 'ArrowLeft') { state.x -= step; apply(); }
-    else if (evt.key === 'ArrowRight') { state.x += step; apply(); }
-    else if (evt.key === 'ArrowUp') { state.y -= step; apply(); }
-    else if (evt.key === 'ArrowDown') { state.y += step; apply(); }
-    else if (evt.key === '+' || evt.key === '=') { zoom(1 / 1.2); }
-    else if (evt.key === '-' || evt.key === '_') { zoom(1.2); }
-    else if (evt.key === '0') { state.x = ix; state.y = iy; state.w = iw; state.h = ih; apply(); }
-  });
+    const container = viewport.closest('[data-pan-zoom-container]') || viewport.parentElement || document;
+    container.querySelectorAll('[data-pan-zoom="zoom-in"]').forEach((btn) => btn.addEventListener('click', () => zoom(1 / 1.2)));
+    container.querySelectorAll('[data-pan-zoom="zoom-out"]').forEach((btn) => btn.addEventListener('click', () => zoom(1.2)));
+    container.querySelectorAll('[data-pan-zoom="fit"]').forEach((btn) => btn.addEventListener('click', fit));
 
-  document.querySelectorAll('[data-pan-zoom="zoom-in"]').forEach((btn) => btn.addEventListener('click', () => zoom(1 / 1.2)));
-  document.querySelectorAll('[data-pan-zoom="zoom-out"]').forEach((btn) => btn.addEventListener('click', () => zoom(1.2)));
-  document.querySelectorAll('[data-pan-zoom="fit"]').forEach((btn) => btn.addEventListener('click', () => {
-    state.x = ix; state.y = iy; state.w = iw; state.h = ih; apply();
-  }));
+    return { zoom, fit, pan };
+  }
 })();