docs(codeviz): add hyperframes timelapse/review-walkthrough export capability

docs/proposals/codebase-visualization-tool.md

@@ -267,7 +267,7 @@ Acceptance outcomes:
 
 ### Capability: SPA render scaffold (rendering choice via prototype phase)
 
-A TypeScript + Vite SPA. The primary canvas implementation is selected via the `/prototype-feature` skill, which produces competing working skeletons across four candidate render layers — Cytoscape.js 2D (fcose layout), Sigma.js + graphology (WebGL), three.js CodeCity 3D, and Observable Framework + d3 — each fed the same subgraph payload from a stubbed HTTP API. Variants are scored on initial-render performance, layout stability, interaction richness (selection, lasso, semantic zoom), and developer ergonomics; the winning variant is promoted to production and the others retained as feature-flagged experimental views. Semantic coloring by layer (Python / TS / SQL / config / docs), hover tooltips, click selection, lasso multi-select, and pan/zoom with semantic zoom levels (repo → service → module → file → symbol) are required of the production variant. Depends on the HTTP API server.
+A TypeScript + Vite SPA. The primary canvas implementation is selected via the `/prototype-feature` skill, which produces competing working skeletons across four candidate render layers — Cytoscape.js 2D (fcose layout), Sigma.js + graphology (WebGL), three.js CodeCity 3D, and Observable Framework + d3 — each fed the same subgraph payload from a stubbed HTTP API. Variants are scored on initial-render performance, layout stability, interaction richness (selection, lasso, semantic zoom), developer ergonomics, and deterministic headless capture (frame-reproducibility under headless Chrome, which supports the Action API's reproducible-headless-screenshot requirement); the winning variant is promoted to production and the others retained as feature-flagged experimental views. Semantic coloring by layer (Python / TS / SQL / config / docs), hover tooltips, click selection, lasso multi-select, and pan/zoom with semantic zoom levels (repo → service → module → file → symbol) are required of the production variant. Depends on the HTTP API server.
 
 **Semantic-zoom outcomes (renderer-agnostic).** Each prototype variant chooses its own implementation strategy for semantic zoom (D3 domain rescaling, Cytoscape zoom-event hooks, three.js camera + LOD swap, Observable layered render — whatever fits the variant's idiom). The variants are judged on outcomes, not implementation: readable labels and edge connections at every zoom level, stable node positions across zoom transitions, predictable thresholds for detail reveal, visually constant stroke width and label font size across zoom decades, and a preserved mental map (a node that was upper-left at scale N is still upper-left at scale N+1). Variants that achieve these outcomes via different mechanisms are equally acceptable.
 
@@ -279,6 +279,7 @@ Acceptance outcomes:
 - Production layout MUST be deterministic across page reloads given the same data (seeded RNG or persisted positions).
 - Selection state MUST be reflected in the URL.
 - The variant comparison MUST score prototypes on three reviewer tasks (defined in `task-based-ux-study.md`): (a) "find every function that depends on Symbol X", (b) "summarize what changed in this PR's blast radius", (c) "navigate from a security finding to the responsible commit". Task success rate and time-to-completion MUST be reported alongside performance metrics.
+- The variant comparison MUST additionally score **deterministic headless capture** — whether the renderer produces frame-stable, pixel-reproducible output under headless Chrome (Puppeteer), since this supports the Action API's reproducible-headless-screenshot requirement. (Note: `timelapse-review-export` uses its own standalone capture composition and does NOT depend on the production renderer, so this criterion is about screenshot reproducibility, not video export.) Canvas2D/SVG renderers (Cytoscape, d3) are expected to score higher than WebGL renderers (Sigma, three.js) whose headless-GPU output may vary; the score MUST be recorded in `render-comparison.md` even though it does not by itself decide the winner.
 
 ### Capability: Source viewer panel with deep links
 
@@ -503,6 +504,21 @@ Acceptance outcomes:
 - Every interactive state MUST be restorable from URL alone.
 - Saved views MUST round-trip through the YAML file with no loss.
 
+### Capability: Timelapse and review-walkthrough export
+
+Render shareable MP4 walkthroughs of code evolution as a **standalone capture composition** fed the same subgraph data the SPA consumes. This capability **adopts** [hyperframes](https://github.com/heygen-com/hyperframes) — an HTML-native, deterministic video renderer (a seekable, frame-accurate animation clock driven over headless Chrome + FFmpeg, with a non-interactive CLI designed for agent use) — as the **export/render layer only**. It does NOT replace the in-app temporal scrubber (`temporal-snapshot-scrubber`), which remains the surface for live, interactive review; the two serve different use cases (live scrub vs. shareable async deliverable). Rather than embed the production SPA renderer, the composition reads at-commit subgraphs from the HTTP API (`/repos/{id}/at/{commit_sha}/subgraph`) plus the `diff-graph.json` artifact, and renders them through its **own deterministic Canvas2D/SVG path** — decoupling frame-reproducibility from the production renderer's choice (which may be WebGL and not headless-deterministic). To preserve visual parity with the SPA, the composition MUST reuse the same layout algorithm and seed so node positions match what reviewers see live. It binds hyperframes' seekable clock to a sequence of codeviz states — advancing `valid_from_commit` across a commit range, fading the diff classification in by `change_kind`, materializing ghost nodes, and growing the blast-radius Sankey. Because hyperframes pauses each animation timeline and advances it frame-by-frame, motion *between* commit snapshots is interpolated and smooth rather than a discrete jump. Two render modes ship: **scrub-export** (a raw timelapse of a commit range or a saved view's scrub track) and **review-walkthrough** (a templated narrative driven by the `diff-graph.json` event artifact for a single PR or OpenSpec change — title card with the change-id, the call/dataflow network rewiring as edges appear and disappear, contract-changes flagged, and closing validation-outcome badges). The renderer is driven headlessly through the `action-api-for-agents` Action API so an agent can produce a walkthrough as a review deliverable and attach it to a PR. Local-first is preserved: rendering runs locally via the bundled CLI, and hyperframes' optional AWS Lambda cloud render is opt-in and defaults off. Because the composition injects untrusted repo-derived strings (commit messages, symbol names, diff text) into HTML executed by headless Chrome, all such strings MUST be escaped before injection and the render context MUST be network-isolated; this attack surface is covered by an explicit `threat-model-artifact` entry. Depends on `http-api-server`, `temporal-snapshot-scrubber` (for the persisted multi-commit snapshot store), `diff-graph-artifact`, `action-api-for-agents`, and `saved-views-url-state`.
+
+Acceptance outcomes:
+- A `codeviz-timelapse` CLI MUST render an MP4 from a saved-view URL plus a commit range with no interactive input, reproducibly (same inputs produce frame-identical output, independent of the production SPA renderer).
+- Scrub-export MUST animate across a commit range, applying the SPA's layout seed so positions match the live view and stay stable across frames (no relayout jitter for symbols that persist across commits).
+- Review-walkthrough MUST consume a single PR's or OpenSpec change's `diff-graph.json` and render its `change_kind` classification (refactoring / micro-change / contract-change / test-impact / runtime-risk / ordinary) using the same `change_kind` color mapping as the diff overlay.
+- All repo-derived strings (commit messages, symbol names, diff text) injected into the composition MUST be escaped before rendering, and the headless render context MUST be network-isolated; this surface MUST be listed in `docs/codeviz/threat-model.md`.
+- Render cost MUST be bounded for long histories: a configurable max-frame budget (with commit-sampling beyond a threshold, mirroring the >50-commit scatterplot mini-map) MUST cap total frames so a wide commit range cannot produce an unbounded render.
+- Cloud rendering (hyperframes AWS Lambda) MUST be opt-in behind an explicit flag and default to local render; the core render path MUST work offline.
+- The export MUST be classified `reversible-write` by the shared `op_reversibility` classifier (it produces a deletable artifact) and MUST emit an audit event; it MUST NOT mutate graph state.
+- Rendered MP4s MUST be written to the operational storage tier (a gitignored cache such as `.codeviz-cache/walkthroughs/`), never committed to git, per the storage-tier policy; only a small sidecar JSON carrying the mandatory artifact header (source view URL, commit range, renderer version, output digest) is committed as an event artifact under `docs/codeviz/walkthroughs/<YYYY-MM-DD>/<run-id>.json`.
+- The capability MUST document the added toolchain dependency (Node ≥ 22, FFmpeg, headless Chrome via Puppeteer) and MUST fail with an actionable error when FFmpeg or Chrome is missing rather than producing a partial render.
+
 ### Capability: Optional CodeCity 3D view (experimental)
 
 A toggle that switches the canvas to a three.js CodeCity-style 3D treemap — buildings as classes/files, districts as packages, height as LOC (from `code-metrics-enrichment`), color as complexity or recent-change heat. Flagged as experimental; not the default surface. Supports **WASDFQ spatial navigation**: WASD for planar movement across the city, F/Q for ascending/descending hierarchical layers (zoom-out to repo / zoom-in to module). This binding is chosen over arrow keys to avoid conflicting with screen-reader shortcuts and to remain accessible.

openspec/roadmaps/codeviz/proposal.md

@@ -267,7 +267,7 @@ Acceptance outcomes:
 
 ### Capability: SPA render scaffold (rendering choice via prototype phase)
 
-A TypeScript + Vite SPA. The primary canvas implementation is selected via the `/prototype-feature` skill, which produces competing working skeletons across four candidate render layers — Cytoscape.js 2D (fcose layout), Sigma.js + graphology (WebGL), three.js CodeCity 3D, and Observable Framework + d3 — each fed the same subgraph payload from a stubbed HTTP API. Variants are scored on initial-render performance, layout stability, interaction richness (selection, lasso, semantic zoom), and developer ergonomics; the winning variant is promoted to production and the others retained as feature-flagged experimental views. Semantic coloring by layer (Python / TS / SQL / config / docs), hover tooltips, click selection, lasso multi-select, and pan/zoom with semantic zoom levels (repo → service → module → file → symbol) are required of the production variant. Depends on the HTTP API server.
+A TypeScript + Vite SPA. The primary canvas implementation is selected via the `/prototype-feature` skill, which produces competing working skeletons across four candidate render layers — Cytoscape.js 2D (fcose layout), Sigma.js + graphology (WebGL), three.js CodeCity 3D, and Observable Framework + d3 — each fed the same subgraph payload from a stubbed HTTP API. Variants are scored on initial-render performance, layout stability, interaction richness (selection, lasso, semantic zoom), developer ergonomics, and deterministic headless capture (frame-reproducibility under headless Chrome, which supports the Action API's reproducible-headless-screenshot requirement); the winning variant is promoted to production and the others retained as feature-flagged experimental views. Semantic coloring by layer (Python / TS / SQL / config / docs), hover tooltips, click selection, lasso multi-select, and pan/zoom with semantic zoom levels (repo → service → module → file → symbol) are required of the production variant. Depends on the HTTP API server.
 
 **Semantic-zoom outcomes (renderer-agnostic).** Each prototype variant chooses its own implementation strategy for semantic zoom (D3 domain rescaling, Cytoscape zoom-event hooks, three.js camera + LOD swap, Observable layered render — whatever fits the variant's idiom). The variants are judged on outcomes, not implementation: readable labels and edge connections at every zoom level, stable node positions across zoom transitions, predictable thresholds for detail reveal, visually constant stroke width and label font size across zoom decades, and a preserved mental map (a node that was upper-left at scale N is still upper-left at scale N+1). Variants that achieve these outcomes via different mechanisms are equally acceptable.
 
@@ -279,6 +279,7 @@ Acceptance outcomes:
 - Production layout MUST be deterministic across page reloads given the same data (seeded RNG or persisted positions).
 - Selection state MUST be reflected in the URL.
 - The variant comparison MUST score prototypes on three reviewer tasks (defined in `task-based-ux-study.md`): (a) "find every function that depends on Symbol X", (b) "summarize what changed in this PR's blast radius", (c) "navigate from a security finding to the responsible commit". Task success rate and time-to-completion MUST be reported alongside performance metrics.
+- The variant comparison MUST additionally score **deterministic headless capture** — whether the renderer produces frame-stable, pixel-reproducible output under headless Chrome (Puppeteer), since this supports the Action API's reproducible-headless-screenshot requirement. (Note: `timelapse-review-export` uses its own standalone capture composition and does NOT depend on the production renderer, so this criterion is about screenshot reproducibility, not video export.) Canvas2D/SVG renderers (Cytoscape, d3) are expected to score higher than WebGL renderers (Sigma, three.js) whose headless-GPU output may vary; the score MUST be recorded in `render-comparison.md` even though it does not by itself decide the winner.
 
 ### Capability: Source viewer panel with deep links
 
@@ -503,6 +504,21 @@ Acceptance outcomes:
 - Every interactive state MUST be restorable from URL alone.
 - Saved views MUST round-trip through the YAML file with no loss.
 
+### Capability: Timelapse and review-walkthrough export
+
+Render shareable MP4 walkthroughs of code evolution as a **standalone capture composition** fed the same subgraph data the SPA consumes. This capability **adopts** [hyperframes](https://github.com/heygen-com/hyperframes) — an HTML-native, deterministic video renderer (a seekable, frame-accurate animation clock driven over headless Chrome + FFmpeg, with a non-interactive CLI designed for agent use) — as the **export/render layer only**. It does NOT replace the in-app temporal scrubber (`temporal-snapshot-scrubber`), which remains the surface for live, interactive review; the two serve different use cases (live scrub vs. shareable async deliverable). Rather than embed the production SPA renderer, the composition reads at-commit subgraphs from the HTTP API (`/repos/{id}/at/{commit_sha}/subgraph`) plus the `diff-graph.json` artifact, and renders them through its **own deterministic Canvas2D/SVG path** — decoupling frame-reproducibility from the production renderer's choice (which may be WebGL and not headless-deterministic). To preserve visual parity with the SPA, the composition MUST reuse the same layout algorithm and seed so node positions match what reviewers see live. It binds hyperframes' seekable clock to a sequence of codeviz states — advancing `valid_from_commit` across a commit range, fading the diff classification in by `change_kind`, materializing ghost nodes, and growing the blast-radius Sankey. Because hyperframes pauses each animation timeline and advances it frame-by-frame, motion *between* commit snapshots is interpolated and smooth rather than a discrete jump. Two render modes ship: **scrub-export** (a raw timelapse of a commit range or a saved view's scrub track) and **review-walkthrough** (a templated narrative driven by the `diff-graph.json` event artifact for a single PR or OpenSpec change — title card with the change-id, the call/dataflow network rewiring as edges appear and disappear, contract-changes flagged, and closing validation-outcome badges). The renderer is driven headlessly through the `action-api-for-agents` Action API so an agent can produce a walkthrough as a review deliverable and attach it to a PR. Local-first is preserved: rendering runs locally via the bundled CLI, and hyperframes' optional AWS Lambda cloud render is opt-in and defaults off. Because the composition injects untrusted repo-derived strings (commit messages, symbol names, diff text) into HTML executed by headless Chrome, all such strings MUST be escaped before injection and the render context MUST be network-isolated; this attack surface is covered by an explicit `threat-model-artifact` entry. Depends on `http-api-server`, `temporal-snapshot-scrubber` (for the persisted multi-commit snapshot store), `diff-graph-artifact`, `action-api-for-agents`, and `saved-views-url-state`.
+
+Acceptance outcomes:
+- A `codeviz-timelapse` CLI MUST render an MP4 from a saved-view URL plus a commit range with no interactive input, reproducibly (same inputs produce frame-identical output, independent of the production SPA renderer).
+- Scrub-export MUST animate across a commit range, applying the SPA's layout seed so positions match the live view and stay stable across frames (no relayout jitter for symbols that persist across commits).
+- Review-walkthrough MUST consume a single PR's or OpenSpec change's `diff-graph.json` and render its `change_kind` classification (refactoring / micro-change / contract-change / test-impact / runtime-risk / ordinary) using the same `change_kind` color mapping as the diff overlay.
+- All repo-derived strings (commit messages, symbol names, diff text) injected into the composition MUST be escaped before rendering, and the headless render context MUST be network-isolated; this surface MUST be listed in `docs/codeviz/threat-model.md`.
+- Render cost MUST be bounded for long histories: a configurable max-frame budget (with commit-sampling beyond a threshold, mirroring the >50-commit scatterplot mini-map) MUST cap total frames so a wide commit range cannot produce an unbounded render.
+- Cloud rendering (hyperframes AWS Lambda) MUST be opt-in behind an explicit flag and default to local render; the core render path MUST work offline.
+- The export MUST be classified `reversible-write` by the shared `op_reversibility` classifier (it produces a deletable artifact) and MUST emit an audit event; it MUST NOT mutate graph state.
+- Rendered MP4s MUST be written to the operational storage tier (a gitignored cache such as `.codeviz-cache/walkthroughs/`), never committed to git, per the storage-tier policy; only a small sidecar JSON carrying the mandatory artifact header (source view URL, commit range, renderer version, output digest) is committed as an event artifact under `docs/codeviz/walkthroughs/<YYYY-MM-DD>/<run-id>.json`.
+- The capability MUST document the added toolchain dependency (Node ≥ 22, FFmpeg, headless Chrome via Puppeteer) and MUST fail with an actionable error when FFmpeg or Chrome is missing rather than producing a partial render.
+
 ### Capability: Optional CodeCity 3D view (experimental)
 
 A toggle that switches the canvas to a three.js CodeCity-style 3D treemap — buildings as classes/files, districts as packages, height as LOC (from `code-metrics-enrichment`), color as complexity or recent-change heat. Flagged as experimental; not the default surface. Supports **WASDFQ spatial navigation**: WASD for planar movement across the city, F/Q for ascending/descending hierarchical layers (zoom-out to repo / zoom-in to module). This binding is chosen over arrow keys to avoid conflicting with screen-reader shortcuts and to remain accessible.