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.

---

Amendment (Phase 01-stabilize-video-pipeline, 2026-05-16) — D-17-port-lifecycle

• AMENDED-BY: debug session empty-archive-port-race (Option C, resolved 2026-05-16)
• Replaces nothing. D-17 above stands as the original port-keepalive contract. This amendment narrows the port LIFECYCLE shape that was Claude's-discretion at Phase 1 plan time.
• Background. UAT Test 3 surfaced two coupled defects: 3× Uncaught "Attempting to use a disconnected port object" in the offscreen console starting at the 290 s pre-emptive reconnect mark, AND a silent empty-video archive shipping to the operator. Bisect proved the H1 port race was introduced by Plan 01-04 (commit b064a21) and the H2 silent-skip in createArchive was an upstream defect from commit 555eb05 that the port race amplified from latent to fatal. Full lineage and strategy rationale: .planning/debug/resolved/empty-archive-port-race.md.
• Architectural commitments retired:
  • The legacy 290 000 ms pre-emptive setTimeout reconnect (Pitfall 4) is RETIRED. Its race window between the synchronous .disconnect() and the onDisconnect handler firing was the proximate cause of H1 — see the bisect notes.
• Architectural commitments added:
  • Port health probe (PING ↔ PONG). The offscreen PORT_PING_MS interval doubles as a liveness probe; each PING expects a PONG echo from the SW. The offscreen tracks missedPongs and reconnects cleanly when the count exceeds MAX_MISSED_PONGS = 3 (~75 s of unresponsive SW — well past Chrome's ~30 s idle threshold, so a real disconnect would already have surfaced its own onDisconnect). The SW echoes PONG on every PING via the onConnect-level message sink.
  • Request-id'd REQUEST_BUFFER / BUFFER. Every REQUEST_BUFFER carries a SW-generated requestId (crypto.randomUUID with Math.random fallback). The offscreen echoes the same requestId on the BUFFER response. The SW routes BUFFER → pending request via a module-level Map<requestId, PendingBufferRequest> — port- agnostic, so port replacement does not lose the response.
  • Retry on port replacement. Every onConnect (post-bootstrap) scans pendingBufferRequests and re-issues REQUEST_BUFFER on the fresh port with the SAME requestId. The offscreen posts BUFFER on the CURRENT keepalivePort, the sink matches by id, and the request resolves. This retires the H2 silent-drop class architecturally.
  • Outer hard-timeout bumped 2 s → 10 s. The legacy per-port BUFFER_FETCH_TIMEOUT_MS = 2000 was too tight to cover a retry across a reconnect. The new outer budget covers EVERY retry across port replacements; the inner per-port round-trip is still ~100-200 ms.
  • Operator-visible failure surface. createArchive throws EmptyVideoBufferError when the video buffer is empty. saveArchive catches and emits {type:'RECORDING_ERROR', error:'empty-video-buffer'} via chrome.runtime.sendMessage for the popup, AND returns {success:false, error} in the direct-response path. Replaces the upstream silent-skip branch in createArchive that shipped a video-less archive in silence.
• Pinning contracts added:
  • tests/offscreen/port-health-probe.test.ts — pins the PING/PONG + request-id'd encode contract on the offscreen side (4 tests).
  • tests/background/request-id-protocol.test.ts — pins the SW-side request-id routing + retry + error-surface contract (5 tests).
  • tests/background/port-lifecycle-continuous.test.ts — continuous 600 s end-to-end simulation: 12 ping/pong cycles + 2 forced reconnects + 3 SAVE_ARCHIVE round-trips, asserts no Uncaught and every BUFFER carries segments.
  • tests/offscreen/port-reconnect-race.test.ts (refactored): H1.b no longer pins the retired 290 s setTimeout path — it now pins the externally-disconnected-port → ping try/catch → reconnect path that the H1 fix delivers.

---

Amendment (Phase 01-stabilize-video-pipeline, 2026-05-16 second batch) — Plans 01-08 / 01-09 / 01-10 charter

Context. On 2026-05-16 Phase 1 was REOPENED after UAT Test 3 re-attempt revealed two compounding gaps in the 2026-05-15 closure:

1. D-13's concat-of-self-contained-WebM-segments architecture produces a multi-EBML-header file that mpv, Chrome's HTMLMediaElement, and ffprobe's format=duration all play as ~9.94 s (the first segment's Info.Duration only) instead of ~30 s. The "operator-confirmed clean Chrome playback" check from 2026-05-15 verified playback ran without freezing but did not measure total duration. SPEC §10 #7 (last_30sec.webm plays back in a browser) is not actually satisfied. See .planning/debug/d13-multi-ebml-concat-unplayable.md for the byte-level EBML probe + library-survey + decision rationale.

2. The operator UX is unsatisfactory at the picker stage (tab-share footgun: "Share this tab instead" affordance) and at the activation stage (3 clicks per session: toolbar → popup open → Start button → picker). These were flagged in UAT Test 3's advisory section and deferred to Phase 5 at closure time; the reopen reclassifies them as Phase 1 deliverables because the same fix-cycle window is available.

The orchestrator's "add-more-plans" routing on 2026-05-16 adds three plans (01-08, 01-09, 01-10) to close these gaps without re-litigating the seven plans (01-01..01-07) that already landed.

D-14-remux: WebM remux via ts-ebml + webm-muxer (supersedes D-13's file-concat).

• AMENDED-BY: debug session d13-multi-ebml-concat-unplayable (root-cause confirmed 2026-05-16). Remediation lands via Plan 01-08.
• Replaces partial. D-13's recorder-side restart-segments lifecycle (the part that fixed the orphan-P-frame freeze observed in debug session webm-playback-freeze) is PRESERVED. Only D-13's file-concat merge on the SW save path is retired. Original D-13 text above remains intact for provenance.
• Architectural commitments retired: D-13 file-concat byte-stream merge in src/background/index.ts:mergeVideoSegments is RETIRED. Concat of self-contained WebM segments does NOT produce a single playable 30 s WebM in any common consumer-grade player.
• Architectural commitments added:
  • remuxSegments(segments: VideoSegment[]): Promise<Blob> in src/background/webm-remux.ts replaces mergeVideoSegments. Parses each segment via ts-ebml's Decoder, walks the EBML tree, extracts each Cluster's SimpleBlock children (VP9 frame bytes + keyframe flag + cluster Timecode + block offset), and re-mixes into a single output WebM via webm-muxer's Muxer<ArrayBufferTarget>.addVideoChunkRaw(data, type, timestampUs). Each frame's timestamp is adjusted to be monotonic against a single global timeline.
  • Library choice (LOCKED): ts-ebml ^3.0.2 (parse) + webm-muxer ^5.1.4 (write). Both MIT, both actively maintained (last releases 2025-09-28 and 2025-07-02 respectively), both SW-compatible (no DOM globals on the hot path). Combined gzipped weight ~100 KB. Verified by tests/background/webm-remux-deps.test.ts.
  • createArchive becomes async on the merge path. videoBlob = await remuxSegments(...) replaces synchronous mergeVideoSegments(...). The existing EmptyVideoBufferError throw (Option C, D-17-port-lifecycle amendment) is preserved AND extended to fire on a zero-byte remux output.
• D-13 recorder-side lifecycle UNCHANGED. The offscreen-side src/offscreen/recorder.ts keeps the restart-segments rotation (SEGMENT_DURATION_MS = 10_000 ms, MAX_SEGMENTS = 3), which remains the canonical fix for the orphan-P-frame freeze from debug session webm-playback-freeze. The remux happens only on export, only in the SW.
• Pinning contracts added (Plan 01-08):
  • tests/background/webm-remux-deps.test.ts (2 tests — library presence + SW-compat).
  • tests/background/webm-remux.test.ts (5 tests — single-EBML invariant, monotonic timestamps, size sanity, ffprobe duration

    = 25 s, frame-count tolerance).

  • tests/offscreen/webm-playback.test.ts lines 231-316 (the 2 RED tests landed by the d13 debug session) flip GREEN against the regenerated tests/fixtures/last_30sec.webm.
• D-13 status: PARTIALLY RETIRED. Recorder lifecycle preserved; file-concat merge retired. CONTEXT.md D-13 text above stands for historical provenance; downstream readers reaching D-13 must ALSO read this D-14-remux amendment.

D-15-display-surface: Whole-desktop constraint + post-grant validation (replaces operator-discretion picker).

• AMENDED-BY: UAT Test 3 advisory finding (2026-05-16): "Share this tab instead" Chrome affordance is a one-click footgun that redirects the recording target mid-session. Reclassified from Phase 5 advisory to Phase 1 deliverable via Plan 01-09.
• Replaces nothing structurally. D-01's getDisplayMedia choice stands; this amendment narrows the constraints object passed to it.
• Architectural commitments added:
  • getDisplayMedia is invoked with constraints {video: { displaySurface: 'monitor', cursor: 'always' }, audio: false}. The displaySurface: 'monitor' constraint hints Chrome's picker to default to entire-screen selection; the cursor: 'always' constraint includes the operator's screen cursor in captured frames (this lifts the Phase 5 cursor-visibility refinement opportunistically — STATE.md Decisions entry [Phase 01-07-deferred-to-5]).
  • Post-grant validation reads track.getSettings().displaySurface. If the operator overrode the hint and picked a tab or window, the recorder tears down the stream, nulls mediaStream, and throws Error('wrong-display-surface: got "<observed>"'). The throw routes through classifyCaptureError (extended with a 'wrong-display-surface' branch added to the CaptureErrorCode union) into the existing RECORDING_ERROR channel.
  • The CaptureErrorCode union grows by one member: 'wrong-display-surface' (joins the existing seven).
• Pinning contract added (Plan 01-09):
  • tests/offscreen/display-surface-constraint.test.ts (4 tests: constraints applied; wrong-displaySurface emits RECORDING_ERROR; monitor-displaySurface does NOT emit; classifyCaptureError branch).

D-16-toolbar: Toolbar-onClicked + popup-SAVE-only + badge state machine + onStartup/recovery notifications (replaces popup-Start-button activation).

• AMENDED-BY: UAT Test 3 ergonomics observation; operator-experience goal "per-session click count from 3 to 2" surfaced by user on 2026-05-16. Reclassified from soft-deferred UX-polish to Phase 1 deliverable via Plan 01-09.
• Replaces nothing structurally. The existing popup → SW REQUEST_PERMISSIONS → startVideoCapture flow stands; this amendment changes WHICH UI surface triggers REQUEST_PERMISSIONS.
• Architectural commitments added:
  • chrome.action.onClicked listener registered at SW module load. When isRecording === false, the handler invokes startVideoCapture() directly (the toolbar click counts as the user gesture for getDisplayMedia).
  • Dynamic chrome.action.setPopup swap: empty string ('') in OFF mode (so toolbar click triggers onClicked); pointing to src/popup/index.html in REC mode (so toolbar click opens the popup for SAVE). The SAVE-only popup retires the auto-prompt behavior in src/popup/index.ts:checkPermissions.
  • Badge state machine with three states. REC: green background (#00C853), text 'REC', tooltip "Recording — last 30 s buffered. Click to save." OFF: red background (#D32F2F), empty text, tooltip "Not recording. Click to start." ERROR: yellow background (#F9A825), text 'ERR', tooltip "Recording error. Click to try again."
  • chrome.runtime.onStartup fires chrome.notifications.create once per browser startup with a 'mokosh-startup-'-prefixed id, inviting the operator to click to start.
  • chrome.notifications.onClicked validates the id prefix ('mokosh-'), drains the notification via chrome.notifications.clear, and triggers startVideoCapture() (notification click is also a user gesture under Chrome's documented activation model).
  • On RECORDING_ERROR receipt, the SW transitions badge to ERROR and emits a 'mokosh-recovery-'-prefixed recovery notification inviting a fresh start.
  • manifest.json adds notifications to permissions. default_popup retained for the SAVE flow.
• Popup role change. src/popup/index.ts no longer auto-requests permissions on init. checkPermissions / requestPermissions functions are removed from the init path. Empty-state copy updated to direct operator to the toolbar icon.
• Smoke harness update. smoke.sh's auto-select target string changes from the tab title to an entire-screen string (e.g. "Entire screen" or "Screen 1" depending on Chrome locale). If the auto-select fails under a non-English Chrome, a one-time manual pick is documented as the fallback.
• Pinning contracts added (Plan 01-09):
  • tests/background/toolbar-action.test.ts (4 tests: onClicked routing; setPopup dance).
  • tests/background/badge-state-machine.test.ts (4 tests: three badge states + RECORDING_ERROR transition).
  • tests/background/onstartup-notification.test.ts (4 tests: onStartup → create notification; onClicked → start recording; RECORDING_ERROR → recovery notification).

D-17 (NEW — distinct from the port-lifecycle D-17 amendment above): Onboarding welcome tab on first install.

NB: this is a SEPARATE D-17 marker, scoped to Plan 01-10. The earlier D-17 amendment block (port lifecycle) is also labeled D-17 in its historical context (it amends the original D-17 from the 2026-05-15 decisions block above). To disambiguate downstream readers, this Plan 01-10 marker is referenced as D-17-onboarding in cross-citations; the port-lifecycle marker is referenced as D-17-port-lifecycle.

• Trigger: Plan 01-09's UX is operator-facing at runtime; Plan 01-10 adds the install-time activation path so the operator's very first interaction with the extension is also one-click.
• Architectural commitments added:
  • chrome.runtime.onInstalled handler extended: on details.reason === 'install' AND chrome.storage.local 'onboarding-completed' flag absent, open src/welcome/welcome.html via chrome.tabs.create({url: chrome.runtime.getURL(...)}). After the tab opens, set the 'onboarding-completed' flag so future installs or reloads do NOT re-open the welcome.
  • New welcome page bundle: src/welcome/welcome.{html,ts,css}. Vanilla DOM per project style; single 'Начать запись' button that sends REQUEST_PERMISSIONS (the install-time click counts as user gesture for getDisplayMedia).
  • manifest.json adds web_accessible_resources array with entry for src/welcome/welcome.html so chrome.runtime.getURL resolves. 'storage' permission already present (no change needed).
  • vite.config.ts rollupOptions.input gains a welcome: 'src/welcome/welcome.html' entry so crxjs bundles the page.
• Pinning contract added (Plan 01-10):
  • tests/background/onboarding.test.ts (3 tests: first install creates welcome tab; subsequent install does NOT; already-completed flag suppresses).

---

Phase: 01-stabilize-video-pipeline Context gathered: 2026-05-15 Amended: 2026-05-16 (debug session empty-archive-port-race, Option C — D-17-port-lifecycle narrowing) Amended: 2026-05-16 (Plans 01-08 / 01-09 / 01-10 charter — D-14-remux WebM remux supersedes D-13 file-concat; D-15-display-surface whole-desktop + cursor; D-16-toolbar toolbar + badge + notifications; D-17-onboarding welcome tab)