.planning/REQUIREMENTS.md

@@ -16,21 +16,28 @@ Requirements for the Phase 1 SPEC. Each maps to one phase in ROADMAP.md.
 
 ### Video
 
-- [ ] **REQ-video-ring-buffer**: The extension maintains an in-memory ring
+- [x] **REQ-video-ring-buffer**: The extension maintains an in-memory ring
   buffer containing the most recent 30 seconds of captured video. AMENDED in
   Phase 01: video is acquired via `navigator.mediaDevices.getDisplayMedia()`
   invoked from the offscreen document (with `chrome.offscreen.Reason.DISPLAY_MEDIA`),
   NOT `chrome.tabCapture` as originally specified. The captured stream is
   screen-or-window-scoped per the operator's one-time selection in Chrome's
   native picker, and continues unchanged across tab switches. Encoding is
-  unchanged: `video/webm; codecs=vp9` @ 400 000 bps with a `MediaRecorder`
+  `video/webm; codecs=vp9` @ 400 000 bps. Ring-buffer mechanism FURTHER
-  timeslice of 2000 ms; a single continuous recorder runs for the whole
+  AMENDED in Phase 01 fix-a3 (debug session webm-playback-freeze, resolved
-  session. The first emitted chunk (WebM header) is retained indefinitely;
+  2026-05-15): the original D-09..D-11 single-continuous-`MediaRecorder` +
-  subsequent chunks rotate out by the 30-second TTL rule. Bindings: DEC-003
+  age-trim approach was retired in favor of D-13 restart-segments — the
-  (AMENDED), DEC-009, CON-video-window, CON-video-codec,
+  recorder stop()/start()s every 10 s on the same `MediaStream`, keeping
-  CON-webm-header-retention, CON-display-capture-binding (replaces RETIRED
+  the last 3 self-contained ~10 s WebM segments (3 × 10 s = 30 s window).
-  CON-tab-capture-binding).
+  Each segment carries its own EBML header + seed VP9 keyframe and is
-  - SPEC §10 acceptance criteria: #2, #3, #7.
+  independently decodable, eliminating the orphan-P-frame freeze observed
+  with the trim approach. Bindings: DEC-003 (AMENDED), DEC-009,
+  CON-video-window, CON-video-codec, CON-display-capture-binding (replaces
+  RETIRED CON-tab-capture-binding). CON-webm-header-retention RETIRED in
+  favor of D-13 per-segment header isolation.
+  - SPEC §10 acceptance criteria: #2, #3, #7 — all green 2026-05-15
+    (D-12 ffprobe gate + operator-confirmed Chrome playback + ffmpeg dry-run
+    exit 0 with zero decoder errors against `tests/fixtures/last_30sec.webm`).
 
 ### DOM Capture
 
@@ -186,7 +193,7 @@ Which phase covers which requirement. See ROADMAP.md for phase details.
 
 | Requirement | Phase | Status |
 |-------------|-------|--------|
-| REQ-video-ring-buffer | Phase 1 | In Progress |
+| REQ-video-ring-buffer | Phase 1 | Complete |
 | REQ-rrweb-dom-buffer | Phase 2 | Pending |
 | REQ-user-event-log | Phase 2 | Pending |
 | REQ-password-confidentiality | Phase 2 | Pending |
@@ -210,4 +217,4 @@ RAM-ceiling check.
 
 ---
 *Requirements defined: 2026-05-15*
-*Last updated: 2026-05-15 after initial bootstrap from intel synthesis*
+*Last updated: 2026-05-15 — REQ-video-ring-buffer marked Complete on Phase 1 closure*

.planning/ROADMAP.md

@@ -22,7 +22,7 @@ working export → green §10 smoke → harden + clean up**.
 
 Decimal phases appear between their surrounding integers in numeric order.
 
-- [ ] **Phase 1: Stabilize video pipeline** — Collapse offscreen duality, fix MediaRecorder shadow, fix WebM ring buffer playability, replace `chrome.tabCapture` with offscreen `getDisplayMedia` (AMENDED from original DEC-003)
+- [x] **Phase 1: Stabilize video pipeline** — Collapse offscreen duality, fix MediaRecorder shadow, fix WebM ring buffer playability, replace `chrome.tabCapture` with offscreen `getDisplayMedia` (AMENDED from original DEC-003). **Closed 2026-05-15** — D-12 ffprobe gate + A3 empirical-playback gate both green against `tests/fixtures/last_30sec.webm` (1.6 MB VP9 1142×1038); D-13 restart-segments retired D-09..D-11 mid-phase; 30/30 vitest green, tsc clean. SPEC §10 #2, #3, #7 functionally satisfied (end-to-end Phase 4 smoke remains owner of §10).
 - [ ] **Phase 2: Stabilize DOM + event capture privacy** — Migrate rrweb to v2 `maskInputFn`, plug `content/index.ts setupInputLogging` password leak
 - [ ] **Phase 3: Stabilize export pipeline** — Restore user-activation gesture in popup, delete dead `permissions.request`, replace base64 `data:` URL with Blob URL minted in offscreen
 - [ ] **Phase 4: SPEC §10 smoke verification** — End-to-end install-and-record-and-export pass against all 9 acceptance criteria
@@ -52,19 +52,23 @@ directory + `vite.config.ts` inline string + `src/background/`.
   not on popup open (CON-tab-capture-binding, REQ-video-ring-buffer).
 
 **Success Criteria** (what must be TRUE):
-  1. There is exactly one source of truth for the offscreen document; rebuilding
+  1. [x] There is exactly one source of truth for the offscreen document; rebuilding
      `vite.config.ts` does not regenerate a divergent inline duplicate, and
      `stopRecording` runs without `mediaRecorder is undefined` shadow errors.
-  2. With the extension loaded and an operator session active, a single
+  2. [x] With the extension loaded and an operator session active, a `MediaRecorder`
-     continuous `MediaRecorder` is running on the operator-selected
+     is running on the operator-selected screen/window source. AMENDED 2026-05-15
-     screen/window source with timeslice 2000 ms; the recorder continues
+     (D-13 fix-a3 activation): the recorder cycles in 10 s self-contained segments
-     unchanged across tab switches (no tab re-attach logic; AMENDED from the
+     (stop+restart on the same `MediaStream`) instead of a single continuous
-     original wording). The WebM container header is retained in the ring
+     recorder — replaces D-09..D-11 to fix VP9 keyframe orphan-P-frame freezes.
-     buffer indefinitely.
+     Recording continues unchanged across tab switches (no tab re-attach logic;
-  3. The in-memory video ring buffer at any instant contains the WebM header
+     AMENDED from the original wording).
-     chunk plus the most recent 30 s of subsequent chunks (no more, no less);
+  3. [x] The in-memory video ring buffer at any instant contains at most 3 of the
-     concatenating header + buffered chunks yields a byte sequence a browser
+     most recent 10 s WebM segments (3 × 10 s = 30 s window, no more, no less);
-     would play.
+     concatenating segments sequentially yields a multi-EBML-header WebM that
+     Chrome plays end-to-end (SPEC §10 #7 — operator confirmed clean playback
+     2026-05-15; ffmpeg `-v warning -i fixture -f null -` exit 0 with zero
+     decoder errors, only expected muxer DTS-monotonicity warnings at segment
+     join boundaries).
 
 **Plans**: 7 plans
 - [x] 01-01-PLAN.md — Doc cascade: amend DEC-003 / DEC-010 / RETIRE constraints / swap manifest permissions (D-A1..D-A6)
@@ -73,7 +77,7 @@ directory + `vite.config.ts` inline string + `src/background/`.
 - [x] 01-04-PLAN.md — Port keepalive + OFFSCREEN_READY handshake (TDD): replaces alarms keepalive on offscreen side
 - [x] 01-05-PLAN.md — SW shrink: delete legacy buffer + alarms + IndexedDB + tabCapture paths; wire SW-side onConnect host
 - [x] 01-06-PLAN.md — Build pipeline collapse: delete vite.config.ts inline plugin + top-level offscreen/ dir; declare rollupOptions.input
-- [ ] 01-07-PLAN.md — Manual smoke + ffprobe D-12 acceptance gate; commit regression fixture
+- [x] 01-07-PLAN.md — Manual smoke + ffprobe D-12 acceptance gate + A3 empirical-playback gate; D-12 + A3 debug sessions resolved mid-execution via pre-staged base64 wire format + D-13 restart-segments; regression fixture committed; SPEC §10 #2/#3/#7 functionally green (Closed 2026-05-15)
 
 ### Phase 2: Stabilize DOM + event capture privacy
 **Goal**: rrweb captures DOM events on typical pages and the user-event log
@@ -199,6 +203,13 @@ finalized at plan time):
 - Dead-code cleanup (the `permissions.request` dance removed in Phase 3 may
   have stranded helpers; the offscreen duality removed in Phase 1 may have
   stranded shims).
+- `getDisplayMedia` cursor visibility constraint (`video: { cursor: 'always' }`)
+  — refines capture quality for diagnostic UX; surfaced during Phase 1 smoke
+  (2026-05-15) as a user observation. Operator's screen cursor was absent
+  from captured frames despite being the highest-signal cue when reproducing
+  pointer-driven bugs. Constraint is opt-in per the `getDisplayMedia` spec
+  and Chrome implements it via the `CursorCaptureConstraint` enum (`always`
+  / `motion` / `never`).
 
 **Success Criteria** (what must be TRUE):
   1. After running the extension idle for >5 minutes, then exporting, the
@@ -224,7 +235,7 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5.
 
 | Phase | Plans Complete | Status | Completed |
 |-------|----------------|--------|-----------|
-| 1. Stabilize video pipeline | 6/7 | In Progress|  |
+| 1. Stabilize video pipeline | 7/7 | Complete | 2026-05-15 |
 | 2. Stabilize DOM + event capture privacy | 0/TBD | Not started | - |
 | 3. Stabilize export pipeline | 0/TBD | Not started | - |
 | 4. SPEC §10 smoke verification | 0/TBD | Not started | - |

.planning/STATE.md

@@ -2,16 +2,16 @@
 gsd_state_version: 1.0
 milestone: v2.0.0
 milestone_name: milestone
-status: executing
+status: phase_complete
-stopped_at: D-13 restart-segments activated (debug session webm-playback-freeze resolved). Six commits on gsd/phase-01-stabilize-video-pipeline (5530292, 6a1a034, 670daa3, f81438d, 87909d9 + this docs commit). 28/30 vitest pass — the 2 reds are the empirical ffmpeg dry-runs in tests/offscreen/webm-playback.test.ts; they stay RED until the operator regenerates tests/fixtures/last_30sec.webm via ./smoke.sh. The production-driven RED block in segment-keyframes.test.ts is fully GREEN (getSegments exported, MAX_SEGMENTS=3 contract met). 8 new tests in segment-rotation.test.ts pin the new ring-buffer invariants. tsc clean, npm run build succeeds. D-09..D-11 retired; old API surface (addChunk/trimAged/firstChunkSaved/isFirst) fully removed. Plan 07 §10 #7 still owned by operator: re-run ./smoke.sh, verify playback in Chrome + ffmpeg-clean stderr, then close REQ-video-ring-buffer.
+stopped_at: "Phase 1 closure 2026-05-15: D-12 ffprobe gate + A3 empirical-playback gate both green against tests/fixtures/last_30sec.webm (1.6 MB VP9 1142×1038, 3-segment multi-EBML-header concat). D-13 restart-segments retired D-09..D-11 mid-phase. 30/30 vitest green incl. empirical webm-playback dry-runs; tsc clean; ffmpeg -v warning -i fixture -f null - exit 0 with zero decoder errors (only expected muxer DTS-monotonicity warnings at segment join boundaries); operator confirmed clean Chrome playback end-to-end. REQ-video-ring-buffer marked Complete. Ready to plan Phase 2 (DOM + event-capture privacy)."
-last_updated: "2026-05-15T21:18:00.000Z"
+last_updated: "2026-05-15T21:42:00.000Z"
-last_activity: 2026-05-15
+last_activity: "2026-05-15 — Phase 1 closure: D-12 + A3 gates green; REQ-video-ring-buffer complete; ready for Phase 2"
 progress:
   total_phases: 5
-  completed_phases: 0
+  completed_phases: 1
   total_plans: 7
-  completed_plans: 6
+  completed_plans: 7
-  percent: 86
+  percent: 100
 ---
 
 # Project State
@@ -27,13 +27,13 @@ no server, no password leaks.
 
 ## Current Position
 
-Phase: 1 (Stabilize Video Pipeline) — EXECUTING
+Phase: 1 of 5 (Stabilize Video Pipeline) — COMPLETE 2026-05-15
-Plan: 7 of 7
+Next phase: 2 of 5 (Stabilize DOM + event-capture privacy)
-Status: Ready to execute
+Plan: 7 of 7 complete (Phase 1 closed)
+Status: Phase 1 complete; ready to plan Phase 2
 Last activity: 2026-05-15
-REQUIREMENTS.md, ROADMAP.md, STATE.md written)
 
-Progress: [█████████░] 86%
+Progress: [██████████] 100% (Phase 1) — 1/5 phases complete (20% milestone)
 
 ## Performance Metrics
 
@@ -47,7 +47,7 @@ Progress: [█████████░] 86%
 
 | Phase | Plans | Total | Avg/Plan |
 |-------|-------|-------|----------|
-| 1. Stabilize video pipeline | 0 | — | — |
+| 1. Stabilize video pipeline | 7 | ~50 min (+ 2 debug sessions ~45 min) | 7 min |
 | 2. Stabilize DOM + event capture privacy | 0 | — | — |
 | 3. Stabilize export pipeline | 0 | — | — |
 | 4. SPEC §10 smoke verification | 0 | — | — |
@@ -55,8 +55,8 @@ Progress: [█████████░] 86%
 
 **Recent Trend:**
 
-- Last 5 plans: —
+- Last 5 plans: 4min, 4min, 8min, 3min, ~10min (Plan 07 closure incl. debug-session arbitration)
-- Trend: —
+- Trend: stable execution time; complexity surfaced in debug sessions (pre-staged fallbacks activated cleanly)
 
 *Updated after each plan completion*
 | Phase 01 P01 | 4min | 6 tasks | 6 files |
@@ -65,6 +65,7 @@ Progress: [█████████░] 86%
 | Phase 01 P04 | 4min | 3 tasks | 1 files |
 | Phase 01 P05 | 8min | 2 tasks | 1 files |
 | Phase 1 P06 | 3min | 2 tasks | 2 files |
+| Phase 1 P07 | ~10min closure + 2 debug sessions (D-12 + A3) | 2 tasks (checkpoint + auto) | 6 files (fixture + REQUIREMENTS + ROADMAP + STATE + SUMMARY + plan-final-commit) |
 
 ## Accumulated Context
 
@@ -103,6 +104,8 @@ current work:
 - [Phase ?]: [Phase 01-06]: crxjs Outcome A confirmed — dist/src/offscreen/index.html (preserves src/ prefix from rollupOptions.input key). SW URL adjusted to chrome.runtime.getURL('src/offscreen/index.html'); RESEARCH.md Pitfall 5 binding empirically verified
 - [Phase 01-07-debug-d12]: D-12 port-blob serialization fixed via base64 wire-format encode/decode (debug session d12-blob-port-transfer-fails resolved 2026-05-15). chrome.runtime.Port JSON-serializes payloads across extension contexts so Blob payloads were silently corrupted (JSON.stringify(blob) === "{}" → SW saw [{}, {}, ...] → new Blob([...]) coerced each to "[object Object]" → 75-byte text instead of WebM). Added src/shared/binary.ts (blobToBase64 / base64ToBlob), TransferredVideoChunk wire-format type, offscreen encode side, SW decode side. All 15 tests green incl. 6-test port-serialization spec. Re-run smoke.sh + ffprobe still required for end-to-end verification.
 - [Phase 01-07-debug-a3]: D-13 restart-segments activated (debug session webm-playback-freeze resolved 2026-05-15). Plan 07 smoke retest after D-12 landed revealed the next-layer A3 failure: the ffprobe-valid WebM froze ~1 s into playback in Chrome because the single-continuous-recorder + 30 s age-trim lifecycle (D-09..D-11) evicted middle chunks containing VP9 keyframe references for retained tail chunks (orphan P-frames). Activated the pre-staged D-13 skeleton in src/offscreen/recorder.ts: stop+restart MediaRecorder every SEGMENT_DURATION_MS=10_000 ms on the same MediaStream, keep last MAX_SEGMENTS=3 self-contained WebM segments (3×10s=30s window preserved). Each segment fresh-encoded → own EBML header + seed keyframe → independently decodable. Side-effect: .stop() per segment fixes the "File ended prematurely" Matroska finalization gap. Type renames propagated: TransferredVideoChunk → TransferredVideoSegment, VideoChunk → VideoSegment, PortMessage.chunks → PortMessage.segments, VideoBufferResponse.chunks → VideoBufferResponse.segments; the header-pin flag from D-09..D-11 is dropped entirely. D-09..D-11 retired in favor of D-13. 28/30 tests pass; the 2 remaining reds are the empirical ffmpeg dry-runs against the still-stale committed fixture (operator regen required). REQ-video-ring-buffer NOT marked complete — Plan 07 still owns that, gated on the operator running ./smoke.sh then verifying Chrome playback + ffmpeg-clean stderr.
+- [Phase 01-07-closure]: Phase 1 closed 2026-05-15: D-12 + A3 acceptance gates both passed. Operator-confirmed Chrome playback clean (no ~1 s freeze); ffmpeg `-v warning -i tests/fixtures/last_30sec.webm -f null -` exit 0 with zero decoder errors (only expected muxer DTS-monotonicity warnings at segment join boundaries — non-blocking, documented D-13 trade-off for multi-EBML-header concat); ffprobe + empirical playback both green; 30/30 vitest green (the 2 webm-playback empirical dry-runs flipped GREEN after the fresh fixture committed in cd61cbc); REQ-video-ring-buffer marked Complete; SPEC §10 #2, #3, #7 functionally satisfied (end-to-end Phase 4 smoke still owns the full §10 sweep). Three atomic closure commits land the fixture + REQ/STATE/ROADMAP flip + SUMMARY. Process note: Plan 01-07 surfaced TWO unanticipated-cascade failures (D-12 then A3); both had pre-staged fallbacks (base64 wire-format and D-13 restart-segments) that activated cleanly. Candidate retro: should `/gsd-plan-phase` auto-inject empirical-acceptance gates (ffmpeg dry-run + Chrome playback) before merging a phase when RESEARCH.md flags HIGH-risk assumptions?
+- [Phase 01-07-deferred-to-5]: getDisplayMedia cursor visibility constraint (`video: { cursor: 'always' }`) surfaced as a user observation during Phase 1 smoke 2026-05-15. Captured frames lack the screen cursor despite it being the highest-signal cue for reproducing pointer-driven bugs. Constraint is opt-in per the getDisplayMedia spec; Chrome implements CursorCaptureConstraint (always/motion/never). Logged to Phase 5 P1/P2 hardening list — not blocking Phase 1 closure.
 
 ### Pending Todos
 
@@ -125,6 +128,16 @@ Items acknowledged and carried forward from previous milestone close:
 
 ## Session Continuity
 
-Last session: 2026-05-15T21:18:00.000Z
+Last session: 2026-05-15T21:42:00.000Z
-Stopped at: D-13 restart-segments activated (debug session webm-playback-freeze resolved). 6 commits on gsd/phase-01-stabilize-video-pipeline (5530292, 6a1a034, 670daa3, f81438d, 87909d9 + the docs commit landing the resolution). 28/30 vitest pass; the 2 reds are fixture-empirical and stay RED until operator regens tests/fixtures/last_30sec.webm via ./smoke.sh. tsc clean; npm run build succeeds. REQ-video-ring-buffer NOT marked complete — Plan 07 §10 #7 still owns that, gated on operator re-running ./smoke.sh then verifying (i) Chrome playback end-to-end, (ii) ffmpeg dry-run produces empty stderr, (iii) the 2 webm-playback.test.ts REDs flip GREEN. After those three, Phase 1 can close.
+Stopped at: Phase 1 closed. D-12 + A3 acceptance gates both passed; operator-confirmed clean Chrome playback; ffmpeg dry-run exit 0 with zero decoder errors; 30/30 vitest green; tsc clean; REQ-video-ring-buffer marked Complete; ROADMAP Phase 1 row marked Complete 2026-05-15; cursor-visibility refinement appended to Phase 5 P1/P2 list. Next workflow steps per user settings: deep code-review gate + verifier on the Phase 1 branch before Phase 2 planning.
-Resume file: .planning/debug/resolved/webm-playback-freeze.md
+Resume file: .planning/phases/01-stabilize-video-pipeline/01-07-SUMMARY.md
+
+## Phase 1 Closure Notes
+
+- **ffprobe exit code:** 0 (`ffprobe -v error -f matroska -i tests/fixtures/last_30sec.webm`)
+- **ffmpeg dry-run exit code:** 0 (`ffmpeg -v warning -i tests/fixtures/last_30sec.webm -f null -`) — stderr contains only the expected muxer DTS-monotonicity warnings at segment join boundaries; no decoder errors. Documented D-13 trade-off for multi-EBML-header WebM concatenation; Chrome's MSE pipeline handles this natively (SPEC §10 #7 scope: "plays back in a browser" — Chrome confirmed).
+- **Fixture:** `tests/fixtures/last_30sec.webm` = 1 633 459 bytes (1.6 MB), VP9 codec, Profile 0, 1142×1038, color space bt709, time_base 1/1000, start_pts 0. Captured against the D-13 restart-segments recorder (3 × ~10 s self-contained segments).
+- **Test suite:** 30/30 green across 8 files (`tests/offscreen/`); both empirical ffmpeg dry-runs in `webm-playback.test.ts` flipped GREEN after the fresh fixture committed in cd61cbc.
+- **Phase 1 outcome:** SPEC §10 acceptance criteria #2 (continuous capture), #3 (≤ 30 s window), and #7 (last_30sec.webm plays in a browser) are functionally green at the Phase 1 level. End-to-end §10 smoke verification remains owned by Phase 4 (all 9 criteria sweep).
+- **Phase 2 onwards:** Phase 2 owns the DOM/event-capture privacy slice (REQ-rrweb-dom-buffer, REQ-user-event-log, REQ-password-confidentiality). Phase 3 owns the popup state machine + base64-URL replacement. Phase 4 runs the full SPEC §10 smoke pass. Phase 5 absorbs P1/P2 hardening (now includes the `getDisplayMedia` cursor visibility refinement surfaced 2026-05-15).
+- **Process retro candidate:** Plan 07 surfaced two cascade failures (D-12 binary transfer + A3 cluster alignment). Both had pre-staged fallbacks (base64 wire-format and D-13 restart-segments) which activated cleanly. The smoke-test step ended up doing the empirical-acceptance-gate work that RESEARCH.md flagged as HIGH-risk. Worth raising in a GSD-framework retro: should `/gsd-plan-phase` auto-inject empirical-acceptance gates (ffmpeg dry-run + Chrome playback) BEFORE merging a phase when RESEARCH.md flags HIGH-risk assumptions, rather than discovering it via Plan 07's smoke step?