mokosh/.planning/phases/01-stabilize-video-pipeline/01-CONTEXT.md

Phase 1: Stabilize Video Pipeline — Context

Gathered: 2026-05-15 Status: Ready for planning

## Phase Boundary

Stabilize the video-capture pipeline so the extension continuously records the operator's session into a ring buffer and produces a playable WebM on demand. The phase ends when:

1. The video buffer is alive end-to-end with one authoritative source of truth for the recorder code (no parallel offscreen implementations).
2. The MediaRecorder lifecycle is correct (no shadowed bindings, predictable start/stop).
3. The buffer holds at most 30 s of footage at any moment AND concatenating the retained chunks produces a file that ffprobe -v error accepts as playable.
4. State (the buffer itself) survives the MV3 service-worker idle unload cycle without losing video.

Scope anchor from ROADMAP.md — Phase 2 (DOM/event privacy), Phase 3 (export UX), Phase 4 (smoke verification), and Phase 5 (P1/P2 hardening) are explicitly out of scope here.

## Implementation Decisions

Capture API — AMENDS DEC-003

This phase REPLACES the SPEC-locked chrome.tabCapture choice with getDisplayMedia() capture. Done eyes-open: the operator gains broader capture coverage at the cost of the SPEC §1 "silent operation" property. The doc cascade is enumerated in the Doc Amendments (precede code) subsection below.

• D-01: Capture mechanism is navigator.mediaDevices.getDisplayMedia() invoked inside the offscreen document. No more chrome.tabCapture.getMediaStreamId, no more SW-side gesture juggling.
• D-02: Offscreen document is created with chrome.offscreen.Reason.DISPLAY_MEDIA (replaces USER_MEDIA).
• D-03: One-time source picker on session start; the operator picks "screen" or "window" once. If they later click the Chrome "Stop sharing" banner or the captured source disappears, the offscreen surfaces an error to the SW and the popup re-prompts on next interaction. (Exact error-UX copy is deferred to Phase 3 — see Deferred Ideas.)
• D-04: Operator UX is NOT silent. Chrome's permanent "Sharing your screen" indicator is shown while recording. We accept this as the cost of the API choice.
• D-05: manifest.json permissions follow the new API: desktopCapture replaces tabCapture; activeTab becomes unnecessary for the video pipeline but stays for chrome.tabs.captureVisibleTab (screenshot path, Phase 3 concern — kept).

Offscreen source-of-truth location

• D-06: Recorder code lives at src/offscreen/recorder.ts as a real TypeScript module with strict type-check, source maps, and IDE support.
• D-07: offscreen/index.html is rewritten to load the bundled module via crxjs. The runtime path remains offscreen/index.html (referenced from SW via chrome.runtime.getURL('offscreen/index.html')).
• D-08: DELETE offscreen/index.ts (orphaned dead code) and the entire copy-offscreen plugin block in vite.config.ts:11-184. crxjs picks up the new TS entry through the HTML reference.

Ring-buffer mechanism

• D-09: Single continuous MediaRecorder for the whole session. mediaRecorder.start(2000) so chunks land on cluster boundaries per the spec timeslice (DEC-003, SPEC §4.1). No restart strategy at this point.
• D-10: Retain the first emitted chunk (the chunk produced by the first dataavailable event after start()) indefinitely — it carries the EBML header plus the initial cluster. CON-webm-header-retention.
• D-11: Drop later chunks once they are older than 30 s, by chunk arrival timestamp. Keep header + every chunk newer than now - 30000 ms.
• D-12: Acceptance gate for Phase 1: ffprobe -v error -f matroska -i <last_30sec.webm> must return exit 0 with no decoder warnings on a fresh-export sample. Plan-checker enforces this as a phase success criterion.
• D-13: Fallback if D-12 fails: revise the plan mid-phase to use restart-segments (stop + restart the MediaRecorder every 10 s, keep the 3 most-recent self-contained segments, concat on save). Documented as a known fallback so the planner can pre-stage the alternative structure in PLAN.md.

Tab-switch behavior

• D-14: Not applicable under the new capture API. getDisplayMedia() captures a screen or window, not a tab — there is nothing to re-attach on chrome.tabs.onActivated. Phase 1 explicitly removes any tab-switch handling from src/background/index.ts.
• D-15: Operator switching tabs no longer interrupts the recording — the buffer keeps filling regardless of active tab.

State survival across SW unload

• D-16: Video buffer ownership moves to the offscreen document. The offscreen survives SW unloads because it holds the DISPLAY_MEDIA-reason capture; chunks accumulate there.
• D-17: A long-lived chrome.runtime.connect port from offscreen → SW serves as the keepalive (this is the only mechanism that actually resets the SW idle timer — chrome.alarms callbacks do not, contrary to DEC-010).
• D-18: DELETE the chrome.alarms keepalive (src/background/index.ts:171-178). DEC-010 and CON-service-worker-keepalive are amended in the doc cascade below.
• D-19: On export, SW requests the buffer from offscreen over the port (or one-shot chrome.runtime.sendMessage). SW does NOT cache chunks. CON-buffer-storage is honored — buffer is plain JS variable in offscreen memory, no chrome.storage.session, no IndexedDB. The existing IndexedDB code path in vite.config.ts:43-104 is DELETED along with the inline plugin.

Doc Amendments (precede code)

These document edits MUST ship before any code-touching task in this phase, so downstream phases see a consistent baseline:

• D-A1: Amend .planning/intel/decisions.md DEC-003 to record the getDisplayMedia replacement, with rationale and the explicit silent- operation trade-off. Amend DEC-010 to record port keepalive replacing alarms keepalive.
• D-A2: Amend .planning/intel/constraints.md to RETIRE CON-tab-capture-binding and CON-service-worker-keepalive. Add new CON-display-capture-binding (one-time picker, "Sharing" indicator).
• D-A3: Amend .planning/PROJECT.md Key Decisions table (DEC-003, DEC-010) and Constraints section accordingly.
• D-A4: Amend .planning/REQUIREMENTS.md REQ-video-ring-buffer to remove "active-tab" wording and update API binding.
• D-A5: Amend .planning/ROADMAP.md Phase 1 description and Success Criterion #2 (drop the "tab re-attach" clause).
• D-A6: Amend manifest.json: swap tabCapture → desktopCapture in permissions. Keep activeTab for the screenshot path.

Claude's Discretion

• Exact protocol choice for offscreen↔SW messaging (port for keepalive + sendMessage for one-shot vs port-only).
• Codec strictness: enforce video/webm; codecs=vp9 via MediaRecorder.isTypeSupported; fail loud if unsupported (no fallback chain — current code's vp9→vp8→h264→default fallback is removed).
• Internal naming for the new buffer-owning module (offscreen-recorder vs display-recorder etc.).
• Code-style choices around TS strictness within src/offscreen/ (already on "strict": true per tsconfig).

## Specific Ideas

• "Fail loud" on missing getDisplayMedia support — log a clear error to the SW console with the failing user-agent string. No silent fallback.
• The ffprobe verification gate is a real CLI invocation in the plan's acceptance, not a hand-wave — Phase 1 success requires producing a sample WebM and running ffprobe against it.
• The "stop sharing" recovery path: when the offscreen detects MediaStreamTrack.onended, it should clear the buffer, send a RECORDING_STOPPED message to SW, and stop attempting to record. The popup will re-prompt next time the user clicks save (Phase 3 territory).
• The OFFSCREEN_READY Message type is already declared in src/shared/types.ts:18 but never used. Phase 1 wires up an actual handshake so SW doesn't fire START_RECORDING before the offscreen listener is registered (this fixes audit item P1 #12 in passing).

<canonical_refs>

Canonical References

Downstream agents MUST read these before planning or implementing.

Project baseline (current state, will be amended by D-A1..D-A6)

• .planning/PROJECT.md — overall project context. Note that DEC-003, DEC-010, and the Constraints section will be amended by this phase.
• .planning/REQUIREMENTS.md §"Video" — REQ-video-ring-buffer wording changes in this phase.
• .planning/ROADMAP.md §"Phase 1" — phase definition and success criteria (Success Criterion #2 changes).
• .planning/intel/SYNTHESIS.md — entry point for ingested intel.
• .planning/intel/decisions.md §DEC-003, §DEC-009, §DEC-010.
• .planning/intel/constraints.md §CON-video-window, §CON-video-codec, §CON-webm-header-retention, §CON-tab-capture-binding (RETIRED), §CON-service-worker-keepalive (RETIRED), §CON-buffer-storage.

Authoritative SPEC

• Тз расширение фаза1.md §2 (stack), §4.1 (video buffer parameters), §7 (manifest permissions), §8 row 3 (tab-capture binding — being AMENDED), §10 acceptance criteria #2, #3, #7.

Audit

• /home/parf/.claude/plans/dear-claude-there-is-snazzy-fox.md — full P0 analysis. Key spots: P0-1 (offscreen duality + mediaRecorder shadow, vite.config.ts:113/vite.config.ts:208), P0-2 (WebM ring buffer + 200 ms timeslice issue), P0-3 (always-on capture), P1 #8 (alarms keepalive ineffective), P1 #12 (OFFSCREEN_READY handshake missing).

Chrome APIs (read before researching)

• MDN: MediaDevices.getDisplayMedia() — capture semantics, picker UX, MediaStreamTrack.onended.
• Chrome docs: chrome.offscreen API, especially Reason.DISPLAY_MEDIA (Chrome 116+).
• Chrome docs: Service worker lifecycle in MV3 — confirm chrome.alarms vs chrome.runtime.connect port behavior with respect to idle timer.
• WebM/Matroska EBML format — cluster boundary semantics; needed only if the D-13 fallback (restart-segments) activates.

</canonical_refs>

<code_context>

Existing Code Insights

Reusable assets

• src/background/index.ts:16-73 — videoBuffer: VideoChunk[] array + cleanupVideoBuffer(). Structural pattern (header retention + age trim) is kept; the implementation is moved to src/offscreen/recorder.ts.
• src/shared/types.ts — Message, VideoChunk, VideoBufferResponse, OFFSCREEN_READY, RECORDING_ERROR. Reuse as-is; wire up OFFSCREEN_READY and RECORDING_ERROR in Phase 1.
• src/shared/logger.ts — Logger (SW context) and ContentLogger (content-script context). Add an OffscreenLogger or reuse Logger with prefix [Offscreen:...].

Established patterns

• Strict TS with noUnusedLocals/noUnusedParameters (tsconfig.json). New code must comply — no as any, no @ts-ignore (audit item P1 #13 informs this).
• Russian comments inline are acceptable per project provenance (see Тз расширение фаза1.md, the user-facing UI strings in REQ-popup-ui).

Files to DELETE in this phase

• offscreen/index.ts — dead code (audit P2 #18).
• offscreen/index.html — REPLACED by a crxjs-managed equivalent pointing at the new src/offscreen/recorder.ts. (Path stays the same in dist; source moves.)
• vite.config.ts:11-184 — the entire copy-offscreen inline plugin block including the embedded JS string + IndexedDB plumbing. Replaces with a small note + the standard crx() invocation.
• src/background/index.ts:171-178 — setupKeepalive() and its chrome.alarms registration.
• src/background/index.ts:445-475 — loadChunkFromIndexedDB() and openIndexedDB() (the SW-side IDB plumbing).
• src/background/index.ts:432-442 — the VIDEO_CHUNK message handler that expected Blob over chrome.runtime.sendMessage (the fundamentally broken path from audit P0 #2 — never reachable today but documented to delete).

Files to CREATE

• src/offscreen/recorder.ts — new module owning getDisplayMedia + MediaRecorder + ring buffer + keepalive port.
• src/offscreen/index.html (or amended offscreen/index.html) — minimal HTML that loads the new module via crxjs.

Files to MODIFY heavily

• src/background/index.ts — owns offscreen lifecycle, port handling, export-time buffer fetch. Most of the file shrinks.
• manifest.json — permissions swap, offscreen already present.
• vite.config.ts — collapse to a clean crxjs invocation, no inline plugin.

</code_context>

## Deferred Ideas

• Error UX for "user stopped sharing" mid-session. The popup needs a state for this — Phase 3 territory (REQ-popup-ui state machine extension).
• Audio capture. getDisplayMedia() makes audio capture trivial (audio: true), but SPEC §9 explicitly excludes audio from Phase 1 (Phase 2 work — CAP-01). Capture this as an easier-now-than-before follow-up.
• Per-tab silent capture mode as an opt-in via config.json. Could re-introduce tabCapture for installations that prioritize silent operation over broad coverage. Future phase if there's demand.
• Cluster-aware EBML trim (ts-ebml). Not needed for Phase 1 if continuous + age-trim verifies via ffprobe. Keep on the shelf as a third fallback under D-13.
• chrome.storage.session cold-start recovery. Buffer pointer rehydration after offscreen crash. Phase 5 (Harden + clean up) territory.

---

Phase: 01-stabilize-video-pipeline Context gathered: 2026-05-15