mokosh/.planning/phases/01-stabilize-video-pipeline/01-09-SUMMARY.md

---
phase: 01-stabilize-video-pipeline
plan: 09
subsystem: offscreen-recorder + background-sw + popup + manifest
tags:
  - getDisplayMedia
  - displaySurface
  - cursor
  - toolbar
  - chrome.action.onClicked
  - chrome.notifications
  - chrome.runtime.onStartup
  - badge-state-machine
  - manifest
  - popup-save-only
  - D-15-display-surface
requires:
  - 01-08 (Plan 01-08 SUMMARY + Tier-1 SW-bundle-import gate GREEN)
provides:
  - REQ-video-ring-buffer:closure-via-D-15-display-surface
  - operator-facing badge state machine (REC/OFF/ERROR) + recovery notifications
  - getDisplayMedia constraint hint (displaySurface:'monitor', cursor:'always')
    + post-grant enforcement (wrong-display-surface RECORDING_ERROR)
  - toolbar-onClicked direct-to-picker flow (popup SAVE-only)
  - onStartup notification inviting fresh recording on browser launch
affects:
  - src/offscreen/recorder.ts (CaptureErrorCode union + classifyCaptureError
    + getDisplayMedia call site + post-grant validation block)
  - src/background/index.ts (badge state machine + 3 mode helpers + 3 new
    listener registrations + RECORDING_ERROR onMessage branch +
    initialize() setIdleMode call)
  - src/popup/index.ts (SAVE-only — checkPermissions + requestPermissions
    removed; popupState defaults to hasPermissions:true so SAVE is enabled)
  - manifest.json (added 'notifications' permission)
  - smoke.sh (SHARE_TARGET monitor mode + locale-fallback comment +
    HTML stub instruction updates; T+/wall overlay preserved)
tech-stack:
  added:
    - chrome.action.onClicked (MV3)
    - chrome.notifications.create / clear / onClicked
    - chrome.runtime.onStartup
    - MediaTrackConstraints displaySurface + cursor (Screen Capture spec)
  patterns:
    - 3-state badge state machine driven by setBadgeState helper
    - setPopup('' ⇄ html) dance gating onClicked vs popup-open
    - Constraint-hint-vs-enforcement gap: getDisplayMedia constraints are
      HINTS per W3C spec; post-grant track.getSettings().displaySurface
      check is the actual enforcement
    - Notification id prefix namespace ('mokosh-startup-', 'mokosh-recovery-')
      for spoofing mitigation (T-1-09-01)
    - Defense-in-depth try/catch around all chrome.* listener registrations
      so unit-test stubs that don't define every surface don't crash SW load
key-files:
  created:
    - tests/offscreen/display-surface-constraint.test.ts (4 tests)
    - tests/background/toolbar-action.test.ts (5 tests inc. W-02 Test E)
    - tests/background/badge-state-machine.test.ts (4 tests)
    - tests/background/onstartup-notification.test.ts (4 tests)
  modified:
    - src/offscreen/recorder.ts (CaptureErrorCode + getDisplayMedia + validation)
    - src/background/index.ts (~150 LOC of helpers + listeners + handler)
    - src/popup/index.ts (~50 LOC removed, defaults flipped)
    - manifest.json (1 permission added)
    - smoke.sh (3 string literals + 14 comment lines)
decisions:
  - displaySurface constraint is shipped with strict deep-equality test
    pinning the EXACT constraints object {video:{displaySurface:'monitor',
    cursor:'always'},audio:false} — a future refactor that drops either
    constraint silently fails loudly. cursor:'always' was opportunistically
    lifted from the Phase 5 deferral list per the I-03 fix.
  - Post-grant validation is the actual enforcement (spec treats
    displaySurface as a hint, not a hard constraint). Stream tracks are
    stopped + mediaStream nulled + Error thrown — the existing catch
    block routes it through classifyCaptureError + RECORDING_ERROR.
  - setPopup '' ⇄ html dance chosen over removing default_popup entirely
    (Option B per the plan interfaces): keeps the manifest stable +
    lets the SW dynamically gate onClicked vs popup-open per state.
  - Popup defaults flipped to hasPermissions:true / isRecording:true
    because under the SAVE-only charter the popup only opens when
    recording is already active (setPopup html path is set by
    setRecordingMode/setErrorMode).
  - All Plan 01-09 listener registrations wrapped in try/catch to
    preserve the 6 pre-existing background tests (request-id-protocol +
    port-lifecycle-continuous) whose chrome stubs predate
    chrome.action/notifications/onStartup. Production MV3 always
    provides these surfaces.
  - smoke.sh SHARE_TARGET set to English 'Entire screen' with a 14-line
    locale-fallback comment citing chromium/grit generated_resources.grd
    as the authoritative source. Per W-04 fix the prior citation to
    desktop_capture_device_uma_types.cc (UMA enums) was wrong and dropped.
metrics:
  duration: ~35 minutes (executor agent)
  completed: 2026-05-17
  task_count: 4 autonomous (Task 5 is operator-gated checkpoint, deferred)
  files_modified: 9 (4 created + 5 modified)
  net_loc: +1200 (~887 test LOC + ~310 src LOC + ~14 smoke comment lines)
---

# Phase 1 Plan 9: Toolbar-onClicked Direct-to-Picker + Display-Surface Monitor + Badge State Machine + Notifications + SAVE-only Popup

Activation-cost reduction (3 clicks → 2) + footgun retirement (operator-picks-tab no longer reaches recording) + operator-visible recording state via badge + OS notifications inviting fresh starts and surfacing errors.

## One-Liner

`displaySurface:'monitor' + cursor:'always'` getDisplayMedia constraints with post-grant enforcement; `chrome.action.onClicked` toolbar-to-picker flow (popup SAVE-only); 3-state badge machine (REC/OFF/ERROR) + `chrome.runtime.onStartup` notification + `chrome.notifications.onClicked` recovery flow.

## What Landed

### Tests (17 new, all GREEN end-of-plan)

| Test File | Tests | Contract Pinned |
| --- | --- | --- |
| `tests/offscreen/display-surface-constraint.test.ts` | 4 | getDisplayMedia exact constraints + non-monitor pick teardown + monitor over-fire guard + classifyCaptureError branch |
| `tests/background/toolbar-action.test.ts` | 5 (A-E) | onClicked registered + no-record→start + recording→no-double-start + setPopup state-machine + popup SAVE-only init contract (W-02 Test E) |
| `tests/background/badge-state-machine.test.ts` | 4 | REC palette + OFF palette (init) + ERROR palette + RECORDING_ERROR-triggered ERROR transition |
| `tests/background/onstartup-notification.test.ts` | 4 | onStartup registered + creates mokosh-startup- notification + onClicked clears + START_RECORDING + RECORDING_ERROR triggers mokosh-recovery- |

### Source Changes

- **`src/offscreen/recorder.ts`** — `CaptureErrorCode` union extended with `'wrong-display-surface'`; `classifyCaptureError` matches the prefix; `getDisplayMedia` call carries `{video:{displaySurface:'monitor',cursor:'always'},audio:false}` (typed via explicit widening cast — lib.dom.d.ts omits `cursor`); post-grant validation reads `track.getSettings().displaySurface`, on mismatch tears down stream + nulls mediaStream + throws `wrong-display-surface` Error which routes through the existing catch+RECORDING_ERROR pipeline.

- **`src/background/index.ts`** — Added badge palette constants (SCREAMING_SNAKE), `setBadgeState(state: 'REC'|'OFF'|'ERROR')` helper (3-state machine), `setIdleMode`/`setRecordingMode`/`setErrorMode` mode helpers, `startVideoCapture` wires `setRecordingMode` on success and `setErrorMode` in catch, `chrome.action.onClicked` direct-to-picker listener, `chrome.runtime.onStartup` notification creator, `chrome.notifications.onClicked` mokosh-prefix-gated handler, RECORDING_ERROR onMessage branch with recovery notification, `initialize()` calls `setIdleMode` at boot. All registrations defensively wrapped in try/catch.

- **`src/popup/index.ts`** — Removed `checkPermissions` + `requestPermissions` functions; `popupState` defaults to `hasPermissions:true, isRecording:true` under SAVE-only charter; `init()` no longer fires REQUEST_PERMISSIONS; empty-state copy points operator back to toolbar icon.

- **`manifest.json`** — Added `"notifications"` to permissions array.

- **`smoke.sh`** — `SHARE_TARGET="Entire screen"` (locale-English) + 14-line locale-fallback comment block citing Chromium grit generated_resources.grd as authoritative source for IDS_DESKTOP_MEDIA_PICKER_SOURCE_TYPE_SCREEN identifier (locale strings drift across Chrome versions); HTML title made distinct from screen-source string; `<ol>` and intro paragraph updated to reflect entire-screen sharing. T+/wall timer overlay (commit 923aaca) preserved.

## Test Counts

- Baseline before Plan 01-09: 15 files / 64 tests / all GREEN.
- After Task 1 RED commit: 16 files / 68 tests / 4 RED (Tests 1, 2, 3, 4 → only Test 3 GREEN because no over-fire from a non-existent validation block).
- After Task 2 GREEN: 16 files / 68 tests / all GREEN.
- After Task 3 RED commit: 18 files / 81 tests / 13 RED.
- After Task 4 GREEN: 18 files / 81 tests / all GREEN.

## Deviations from Plan

### Auto-fixed Issues

**1. [Rule 3 - Blocking] Vitest node env: `navigator` getter-only**
- **Found during:** Task 1 (running the preserved RED test).
- **Issue:** `globalThis.navigator` in Vitest's node env has only a getter; direct assignment throws `Cannot set property navigator of #<Object> which has only a getter`. All 4 preserved tests failed at the env-setup step instead of for the right contract reasons.
- **Fix:** Added `installNavigatorStub(spy)` helper that uses `Object.defineProperty(globalThis, 'navigator', {value, configurable:true, writable:true})` instead of direct assignment. All 4 navigator assignments rewired to the helper.
- **Files modified:** `tests/offscreen/display-surface-constraint.test.ts`
- **Commit:** 333e0dc

**2. [Rule 3 - Blocking] jsdom not installed; W-02 Test E refactored to node-env**
- **Found during:** Task 3 (running the new test files).
- **Issue:** The plan's W-02 Test E originally used `@vitest-environment jsdom` pragma but `jsdom` is not in `node_modules`. Installing it would be an unscoped dependency add.
- **Fix:** Refactored Test E to a node-env-friendly form that manually stubs the document surface the popup module touches (`getElementById('saveButton'/'statusMessage')`, `querySelector('.button-text')`, `addEventListener` on both button and document, plus a `_docListeners` map so the test can synthesize the `DOMContentLoaded` event). Test E still pins both contracts (E1: no REQUEST_PERMISSIONS at popup-open; E2: saveButton enabled).
- **Files modified:** `tests/background/toolbar-action.test.ts`
- **Commit:** 2d7ff7d

**3. [Rule 1 - Bug] TypeScript: `cursor` not in `MediaTrackConstraints`**
- **Found during:** Task 2 (post-source-edit `npx tsc --noEmit`).
- **Issue:** lib.dom.d.ts's `MediaTrackConstraints` type omits `cursor` (the Screen Capture spec defines it but TypeScript's bundled types lag; cited MDN). Initial GREEN edit failed TSC with `TS2353: Object literal may only specify known properties`.
- **Fix:** Used explicit type-widening cast `as DisplayMediaStreamOptions & {video:{displaySurface:'monitor';cursor:'always'}}` (NOT `as any` per project style — CLAUDE.md "Don't ignore lint/type errors without researching proper fixes first") to add the field precisely.
- **Files modified:** `src/offscreen/recorder.ts`
- **Commit:** de162b4

**4. [Rule 1 - Bug] Pre-existing background tests broken by new chrome.* listener registrations**
- **Found during:** Task 4 (full-suite run after GREEN edit).
- **Issue:** 6 pre-existing background tests (5 in `request-id-protocol.test.ts`, 1 in `port-lifecycle-continuous.test.ts`) crashed at module load with `TypeError: Cannot read properties of undefined (reading 'onClicked')` because their chrome stubs predate `chrome.action`, `chrome.notifications`, `chrome.runtime.onStartup`.
- **Fix:** Wrapped each of the 3 new top-level listener `addListener` calls in `try/catch` (matches the existing defensive pattern in the file, e.g. `chrome.offscreen?.hasDocument` check at line 673). Production MV3 always provides these surfaces.
- **Files modified:** `src/background/index.ts`
- **Commit:** 06dee24

## Tier-1 SW-Bundle-Import Gate

GREEN throughout. The gate exercises `npm run build` + Layer 1 (SW module loads under jsdom-like environment) + Layer 2 (`remuxSegments` runs with the Buffer polyfill). The Plan 01-09 changes (new listener registrations, badge state machine, popup SAVE-only) compile and bundle cleanly; the Buffer polyfill from Plan 01-08 commit dd7bf00 + ebml CJS resolution from cc6e81a both remain intact (no `vite.config.ts` edits in this plan).

## Task 5 Status: Operator Checkpoint — Deferred

Task 5 (`checkpoint:human-verify`) requires an operator to run `npm run build` + `./smoke.sh`, open Chrome, load the unpacked extension, and walk through 13 end-to-end verification steps covering: notification at browser startup, monitor-only picker, badge transitions REC/OFF/ERROR, recovery notification on stop-sharing, popup-opens-when-recording, idle-toolbar-click-triggers-picker. The how-to-verify section in the plan file lists all 13 steps + the resume-signal contract.

The autonomous side (Tasks 1-4) is complete with 17/17 new tests GREEN and full suite 18 files / 81 tests / all GREEN. tsc clean; build clean; `dist/manifest.json` carries the `notifications` permission.

## Architectural Notes Worth Carrying Forward

- **Constraint-hint-vs-enforcement gap.** `getDisplayMedia({video:{displaySurface:'monitor',...}})` is a HINT to Chrome's picker, NOT a hard constraint — operators can still pick a tab or window. Post-grant `track.getSettings().displaySurface` is the actual enforcement. Future plans that add new MediaTrackConstraints should treat constraints as preferences and add post-grant validation for anything load-bearing.

- **setPopup '' ⇄ html dance.** chrome.action.onClicked.addListener fires ONLY when no default_popup is set (or it's been cleared via `chrome.action.setPopup({popup:''})`). Dynamically swapping the popup is the canonical Chrome pattern for "click-action depends on state" toolbar buttons. The SAVE-only popup charter relies on this — when recording is OFF the click does start-action; when REC it opens SAVE.

- **mokosh- notification id namespace.** All Plan 01-09 notifications use `mokosh-startup-` or `mokosh-recovery-` prefixes with `Date.now()` suffix for uniqueness. The onClicked handler validates the prefix before any side effect (T-1-09-01 spoofing mitigation). Future notification work should keep extending this namespace (e.g. `mokosh-savefail-` for save-error toasts).

- **Defense-in-depth chrome.* try/catch.** Every chrome API call that touches a surface a unit-test stub might not fully implement is wrapped in try/catch + a logger.warn. This is now the project's documented pattern (per the deviation 4 footnote) — unit tests should be able to load the SW module without crashing even if they only stub the subset they care about.

## Self-Check: PASSED

- FOUND: tests/offscreen/display-surface-constraint.test.ts
- FOUND: tests/background/toolbar-action.test.ts
- FOUND: tests/background/badge-state-machine.test.ts
- FOUND: tests/background/onstartup-notification.test.ts
- FOUND: .planning/phases/01-stabilize-video-pipeline/01-09-SUMMARY.md
- FOUND: 333e0dc (Task 1 RED)
- FOUND: de162b4 (Task 2 GREEN)
- FOUND: 2d7ff7d (Task 3 RED)
- FOUND: 06dee24 (Task 4 GREEN)

## Known Stubs

None. The popup empty-state copy points operators to use the toolbar icon — this is intentional UX, not a stub (the toolbar icon is the start path; the popup is the save path). No placeholder data or hardcoded empty values flowing to UI.