diff --git a/.planning/phases/01-stabilize-video-pipeline/01-11-RESEARCH.md b/.planning/phases/01-stabilize-video-pipeline/01-11-RESEARCH.md
new file mode 100644
index 0000000..2399e0b
--- /dev/null
+++ b/.planning/phases/01-stabilize-video-pipeline/01-11-RESEARCH.md
@@ -0,0 +1,986 @@
+# Phase 1 · Plan 01-11 — Puppeteer UAT Harness · Research
+
+**Researched:** 2026-05-17
+**Domain:** Chrome MV3 E2E testing (Puppeteer 25 + Chrome 148)
+**Confidence:** HIGH — all critical claims verified by local probes on this machine's
+Chrome 148.0.7778.167 and a fresh `npm install puppeteer@25.0.2`
+
+## Summary
+
+The orchestrator brief lists ten "unknowns." All ten are now resolved, mostly by
+direct empirical probe against our `dist/` extension bundle. Two findings reshape
+the plan:
+
+1. **Bug B's `track.stop()`/`ended` parity problem is real and dispositive.** Per
+   W3C spec (cited below) and verified locally: `track.stop()` does **NOT** fire
+   `ended`. A harness that calls `track.stop()` cannot trigger our
+   `onUserStoppedSharing` handler. The workaround is
+   `track.dispatchEvent(new Event('ended'))` — verified to fire the listener and
+   leave the track in `readyState: 'live'` (so the harness must also call
+   `track.stop()` separately to release the actual capture).
+
+2. **Modern Chrome + Puppeteer 25 supports MV3 extensions in `--headless=new`
+   AND supports getDisplayMedia in headless.** The "must run headful + Xvfb"
+   premise embedded in the existing `smoke.sh` is outdated. Probes 5 + 11 both
+   succeed in headless mode against our bundle.
+
+Everything else (toolbar-click dispatch, SW eval, offscreen-page targeting,
+notifications.create from a probe) works straightforwardly with the documented
+`enableExtensions` + `triggerExtensionAction` API. The harness design is
+mechanically simple; the engineering work is in the 13 assertions and the
+two-bundle build separation.
+
+**Primary recommendation:** Puppeteer 25 + Node `--experimental-vm-modules` or
+`tsx` runner, `--headless=new` for CI, `headless: false` for local debugging.
+Two-bundle separation via `vite build --mode test` → `dist-test/`. Hook lives
+inside the SW guarded by `import.meta.env.MODE === 'test'` (with a
+**conditional manifest** that adds the hook script — required because crxjs
+manifest is static).
+
+<user_constraints>
+## User Constraints (from CONTEXT.md and orchestrator brief)
+
+### Locked Decisions
+- **Tool:** Puppeteer (over Playwright — lighter for our single-extension scale)
+- **Hook pattern:** `globalThis.__mokoshTest` captures handler refs registered
+  to `chrome.action.onClicked` / `chrome.runtime.onStartup`; CDP invokes via
+  `sw.evaluate(...)`. Hook code gated on `import.meta.env.MODE === 'test'`
+  so production bundle tree-shakes it.
+- **Wave:** 3 (between Plan 01-09 functional closure and Plan 01-10 welcome
+  tab start).
+- **Scope target:** 13+ assertions covering Plan 01-08/01-09 functional
+  contract.
+- **Operator role retirement:** operator stops being a functional-gate
+  assertion library; remains for brand/design acceptance.
+- All Phase 1 D-01…D-19 decisions from `01-CONTEXT.md` (getDisplayMedia in
+  offscreen, ring buffer, ffprobe gate, etc.) remain locked.
+
+### Claude's Discretion
+- Specific bundle separation mechanism (two configs vs one config with `mode`
+  flag — recommended below)
+- Whether to introduce a `tsx` runner vs adding a `test:e2e` npm script that
+  invokes node directly
+- Exact placement of the hook file (e.g. `src/test-hook.ts` imported
+  conditionally) — recommended below
+- Whether to use raw CDP (`createCDPSession`) or `sw.evaluate` / `page.evaluate`
+  — recommended below: `sw.evaluate` for SW, `asPage().evaluate` for offscreen,
+  raw CDP only where userGesture-tagged is needed (not for our 13 assertions)
+
+### Deferred Ideas (OUT OF SCOPE)
+- vitest browser mode as alternative path (researched in §4 below; not chosen)
+- Mocking `chrome.desktopCapture` entirely (we use the real getDisplayMedia
+  with `--auto-select-desktop-capture-source` flag — verified working in
+  headless mode)
+- Multi-browser support (Firefox, Edge) — Mokosh is Chrome-only per Phase 0
+</user_constraints>
+
+<phase_requirements>
+## Phase 1 Plan 01-11 Requirements
+
+| ID | Description | Research Support |
+|----|-------------|------------------|
+| REQ-uat-harness-puppeteer | Puppeteer-driven Node script that replays Plan 01-08/01-09 functional contract as automated assertions | §1 (workable launch flags), §2 (SW target shape), §5 (no usable OSS prior art for this exact shape — write from scratch) |
+| REQ-uat-bug-A-coverage | Test asserts `chrome.notifications.create` succeeds with the manifest-declared iconUrl in the icons/icon48.png form | Probe 4 verified `notifications.create` works from `sw.evaluate` synchronously; icon manifest is readable via `chrome.runtime.getManifest().icons` |
+| REQ-uat-bug-B-coverage | Test asserts user-stopped-sharing routes to badge OFF + popup '' + no recovery notif (the routing-bug case), NOT the ERROR path | §7 (BLOCKER analysis): cannot use `track.stop()`; must use `track.dispatchEvent(new Event('ended'))` from offscreen-page context |
+| REQ-uat-two-bundle | Production bundle has no test hooks; test bundle adds the synthetic-event hooks | §6 (two-bundle build via `--mode test` + conditional manifest) and §10 (npm scripts) |
+| REQ-uat-ci-friendly | Harness runs in `--headless=new` for CI; no display required | Probes 5, 11: empirically verified Chrome 148 supports both extension loading and getDisplayMedia in headless |
+| REQ-uat-13-assertions | At least the 13 assertions listed in the brief are implemented | Per-assertion implementation hints in §11 (planner ready-reference table) |
+</phase_requirements>
+
+## Architectural Responsibility Map
+
+| Capability | Primary Tier | Secondary | Rationale |
+|------------|--------------|-----------|-----------|
+| Launch Chrome with extension | Node script (Puppeteer driver) | — | Driver owns process lifecycle |
+| Invoke toolbar click | Driver via `page.triggerExtensionAction` | SW eval (fallback) | Documented public API, works empirically |
+| Read badge / popup state | SW context (`sw.evaluate`) | — | All `chrome.action.get*` APIs callable from SW |
+| Synthesize `chrome.runtime.onStartup` | SW context (test-hook listener) | — | onStartup only fires on cold browser start; harness invokes via hook reference |
+| Synthesize "user stopped sharing" | Offscreen page context (`asPage().evaluate`) | — | Must dispatch on the live MediaStreamTrack — only the offscreen DOM has the ref |
+| Read manifest / icon paths | SW context | Node fs read of `dist-test/manifest.json` | Either path works; SW is closer to runtime truth |
+| Assert ZIP shape | Node script (jszip in driver) | — | Standard file inspection, no browser involvement |
+| Assert WebM via ffprobe | Node script (child_process) | — | Inherits from existing smoke.sh; CI runner has ffprobe |
+| Drive offscreen creation | Driver triggers SW which triggers offscreen | — | Same path as production |
+
+## Standard Stack
+
+### Core
+| Library | Version | Purpose | Why Standard |
+|---------|---------|---------|--------------|
+| `puppeteer` | 25.0.2 | Browser automation + `enableExtensions` + `triggerExtensionAction` | Latest stable, ships the documented MV3 extension API; requires Node ≥22.12.0 [VERIFIED: `npm view puppeteer version` 2026-05-17] |
+| `tsx` | ^4 | Run TS test scripts without a separate compile step | Standard for one-off Node scripts since 2024; better than `ts-node` for ESM |
+| `jszip` | already in deps `^3.10.1` | Inspect the generated `session_report_*.zip` | Already used by the extension; reuse parser |
+
+### Supporting
+| Library | Version | Purpose | When to Use |
+|---------|---------|---------|-------------|
+| ffprobe | system binary | WebM validity check on `last_30sec.webm` | Already required by smoke.sh; CI must have it (pre-flight assertion) |
+| `node:assert/strict` | built-in | Assertions, no extra framework needed | Keeps the harness <500 LoC; we don't need vitest/mocha overhead for 13 deterministic checks |
+
+### Alternatives Considered
+| Instead of | Could Use | Tradeoff |
+|------------|-----------|----------|
+| Puppeteer | Playwright | Playwright has slightly better extension API maturity but adds 200 MB to devDependencies; we've already locked Puppeteer per CONTEXT |
+| `node:assert/strict` | vitest browser mode | vitest browser mode targets in-browser test execution; we want Node-side orchestration that drives the browser — wrong fit (see §4) |
+| `tsx` | `tsc && node` two-step | `tsx` is one step; reduces CI friction |
+
+**Installation:**
+```bash
+npm install --save-dev puppeteer@^25.0.2 tsx@^4
+```
+
+**Version verification:** `npm view puppeteer version` → `25.0.2`,
+published per registry on 2026-05 (the engines field requires `node >=22.12.0`;
+our system has `v24.14.0`, OK). Cite: https://www.npmjs.com/package/puppeteer
+
+## Architecture Patterns
+
+### System Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Node test runner (tests/uat/harness.test.ts under `tsx`)       │
+│  ────────────────────────────────────────────────────────────── │
+│  1. spawn Chrome via puppeteer.launch({                          │
+│       pipe: true,                                                 │
+│       enableExtensions: ['./dist-test'],                          │
+│       headless: <env CI ? true : false>,                          │
+│       args: ['--no-sandbox',                                      │
+│               '--auto-select-desktop-capture-source=Entire screen'│
+│             ] })                                                  │
+│  2. await waitForTarget(t => t.type() === 'service_worker')      │
+│  3. sw = await target.worker()                                   │
+│  4. exts = await browser.extensions(); ext = first entry         │
+└────────┬────────────────────────────────────────────────────────┘
+         │ CDP (Runtime.evaluate, etc.)
+         ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  Service Worker  (chrome-extension://<id>/service-worker-loader) │
+│  ────────────────────────────────────────────────────────────── │
+│  Production code (always): onClicked, onStartup, badge state    │
+│                                                                   │
+│  Test-only code (MODE='test' gate):                              │
+│    globalThis.__mokoshTest = {                                    │
+│      handlers: { onClicked: null, onStartup: null,                │
+│                  notificationOnClicked: null },                   │
+│    }                                                              │
+│    monkey-patch addListener to capture refs                       │
+└────────┬────────────────────────────────────────────────────────┘
+         │ chrome.offscreen.createDocument()
+         ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  Offscreen page  (chrome-extension://<id>/src/offscreen/index)   │
+│  ────────────────────────────────────────────────────────────── │
+│  Production code (always): getDisplayMedia, MediaRecorder, etc.  │
+│                                                                   │
+│  Test-only code (MODE='test' gate):                              │
+│    globalThis.__mokoshTest = {                                    │
+│      getCurrentStream: () => mediaStream,                         │
+│      simulateUserStop: () => {                                    │
+│        const t = mediaStream.getVideoTracks()[0];                 │
+│        t.dispatchEvent(new Event('ended'));                       │
+│        // production handler fires; harness still must            │
+│        // explicitly stop() afterward to release the capture.     │
+│      },                                                            │
+│    }                                                              │
+└─────────────────────────────────────────────────────────────────┘
+
+Harness reads back:
+  • badgeText via sw.evaluate(() => chrome.action.getBadgeText({}))
+  • popup    via sw.evaluate(() => chrome.action.getPopup({}))
+  • iconUrl  via sw.evaluate(() => chrome.runtime.getManifest().icons)
+  • track displaySurface via offscreenPage.evaluate(() =>
+       __mokoshTest.getCurrentStream().getVideoTracks()[0].getSettings())
+  • notification iconUrl param: intercept chrome.notifications.create
+       inside the SW test-hook by wrapping the original (records arg snapshot)
+```
+
+### Recommended Project Structure
+```
+tests/uat/
+├── harness.test.ts         # main: 13 assertions, top-to-bottom narrative
+├── lib/
+│   ├── launch.ts           # puppeteer.launch wrapper with our flags
+│   ├── extension.ts        # extension(), worker(), offscreenPage() helpers
+│   ├── assert-zip.ts       # jszip-based zip / WebM / meta.json checks
+│   └── trigger.ts          # triggerToolbarClick, simulateUserStop, etc.
+└── README.md               # how to run locally vs CI
+
+src/
+└── test-hooks/
+    ├── sw-hooks.ts         # registers __mokoshTest in SW; imported by background
+    └── offscreen-hooks.ts  # registers __mokoshTest in offscreen; imported by recorder
+
+vite.config.ts              # production
+vite.test.config.ts         # extends prod, sets mode:'test', outDir:'dist-test'
+```
+
+### Pattern 1: Service-Worker capture-handlers hook (gated on MODE)
+**What:** the hook monkey-patches `chrome.action.onClicked.addListener` (etc.)
+to capture the handler reference into `globalThis.__mokoshTest.handlers` AND
+still calls the real `addListener`. Production code path is identical; tests
+get an out-of-band reference they can call directly.
+
+**When to use:** every event source whose dispatch we can't otherwise
+trigger from a test driver (onStartup primarily — onClicked is reachable via
+`triggerExtensionAction`, but having the handler ref is useful for the
+"badge OFF on user-stopped-sharing" assertion).
+
+**Example:**
+```typescript
+// src/test-hooks/sw-hooks.ts
+// IMPORTED FROM src/background/index.ts under:
+//   if (import.meta.env.MODE === 'test') { await import('../test-hooks/sw-hooks'); }
+// Vite tree-shakes the import entirely when MODE !== 'test' [VERIFIED: Vite docs
+// on env-and-mode + define]
+const handlers = {
+  onClicked: null as null | ((tab: chrome.tabs.Tab) => void),
+  onStartup: null as null | (() => void),
+  notificationOnClicked: null as null | ((id: string) => void),
+};
+const origActionAdd = chrome.action.onClicked.addListener.bind(chrome.action.onClicked);
+chrome.action.onClicked.addListener = (cb) => {
+  handlers.onClicked = cb;
+  origActionAdd(cb);
+};
+const origStartupAdd = chrome.runtime.onStartup.addListener.bind(chrome.runtime.onStartup);
+chrome.runtime.onStartup.addListener = (cb) => {
+  handlers.onStartup = cb;
+  origStartupAdd(cb);
+};
+const origNotifAdd = chrome.notifications.onClicked.addListener.bind(chrome.notifications.onClicked);
+chrome.notifications.onClicked.addListener = (cb) => {
+  handlers.notificationOnClicked = cb;
+  origNotifAdd(cb);
+};
+globalThis.__mokoshTest = { handlers };
+```
+
+### Pattern 2: Reading SW state from the harness
+```typescript
+const [_, ext] = [...(await browser.extensions())][0];
+const swTarget = await browser.waitForTarget(t => t.type() === 'service_worker');
+const sw = await swTarget.worker();
+const badge = await sw.evaluate(() => chrome.action.getBadgeText({}));
+// All chrome.action / chrome.notifications / chrome.runtime APIs are reachable
+// VERIFIED: probe2 + probe4
+```
+
+### Pattern 3: Driving onClicked via the real path
+```typescript
+// MV3 contract: chrome.action.onClicked DOES NOT fire when default_popup is set
+// VERIFIED: probe3 — clearing popup yields 1 dispatch; restoring popup yields 0
+// Plan 01-09 already implements setPopup({popup:''}) when idle, so production code
+// is the one driving the popup state. Harness drives the click via the public API:
+await page.triggerExtensionAction(ext);  // requires a non-null page arg per probe2
+```
+
+### Pattern 4: Attaching to the offscreen page
+```typescript
+// Offscreen doc shows up as target type 'background_page' (not 'page' — quirk
+// confirmed by probe8/9). Use .asPage(), not .page():
+const off = browser.targets().find(t =>
+  t.type() === 'background_page' && t.url().includes('offscreen'));
+const offPage = await off.asPage();  // VERIFIED: probe9 — returns a real Page
+const ds = await offPage.evaluate(() =>
+  globalThis.__mokoshTest.getCurrentStream().getVideoTracks()[0].getSettings().displaySurface
+);
+```
+
+### Pattern 5: Synthetic user-stopped-sharing (Bug B harness)
+```typescript
+// CRITICAL: track.stop() does NOT fire 'ended' per W3C spec [VERIFIED: probe7,
+// MDN cite below]. The ONLY way to trigger our production
+// onUserStoppedSharing handler from a test driver is dispatchEvent.
+await offPage.evaluate(() => {
+  const t = globalThis.__mokoshTest.getCurrentStream().getVideoTracks()[0];
+  t.dispatchEvent(new Event('ended'));
+  // Track is still in readyState 'live' after dispatch; the production
+  // handler will call stream.getTracks().forEach(t => t.stop()) which DOES
+  // release the capture (just doesn't refire 'ended' because, again, spec).
+});
+```
+
+### Anti-Patterns to Avoid
+- **Do NOT call `track.stop()` to simulate Bug B.** It will not fire the
+  handler. The harness will report PASS when production reality is FAIL.
+  This is the single most dangerous trap in this work.
+- **Do NOT rely on `page.evaluate('chrome.action.openPopup()')` for the SAVE
+  flow assertion.** `openPopup` requires user activation in MV3; even with
+  Puppeteer's default userGesture flag the API has been flaky historically.
+  Drive via `triggerExtensionAction` which goes through the real toolbar path.
+- **Do NOT assume the offscreen page exists at launch.** It is created
+  on-demand by the SW. Tests must trigger the SW path that calls
+  `chrome.offscreen.createDocument` first, then wait for the
+  `background_page` target.
+
+## Don't Hand-Roll
+
+| Problem | Don't Build | Use Instead | Why |
+|---------|-------------|-------------|-----|
+| Extension loading in Chrome | Custom `--load-extension` flag | `puppeteer.launch({ enableExtensions: [...] })` | `--load-extension` is removed from branded Chrome 137+; Puppeteer passes `--enable-unsafe-extension-debugging` automatically [CITED: developer.chrome.com extension-news-june-2025] |
+| Finding the SW target | Polling `browser.pages()` | `browser.waitForTarget(t => t.type() === 'service_worker')` | Documented, supports a timeout option, race-free |
+| Invoking toolbar click | DOM clicks on chrome:// URLs (impossible) | `page.triggerExtensionAction(extension)` | Ships in Puppeteer 25, replaces the decade-old "you can't click extension buttons" hack landscape [CITED: PR #14821] |
+| User-stopped-sharing simulation | Custom MediaStreamTrack subclass | `track.dispatchEvent(new Event('ended'))` | Spec-compliant; works on a real live track; minimum-surface change |
+| Two-bundle separation | Manual file copy | `vite build --mode test` with separate `vite.test.config.ts` | Vite's built-in mode mechanism; predictable tree-shaking [CITED: vite.dev/guide/env-and-mode] |
+
+## Per-Area Findings
+
+### 1. Puppeteer extension testing quirks
+
+**Findings:**
+- Issue #2486 ("Ability to click browser action buttons", opened 2018) is
+  **CLOSED** and resolved upstream. The fix is `page.triggerExtensionAction()`,
+  added via PR #14821 (commit `d6395ef`, merged into Puppeteer 22.x line as
+  experimental API; ratified to stable shape in 24.x; documented as the
+  recommended path in the current pptr.dev/guides/chrome-extensions). Cite:
+  https://github.com/puppeteer/puppeteer/issues/2486,
+  https://github.com/puppeteer/puppeteer/commit/d6395ef88103a50cb2b2c43f61953ab6a495a8c3
+- Issue #8987 (mentioned in brief): could not find this exact issue number
+  in the puppeteer repo. May be a transposition from another repo. The
+  documented limitation — that `chrome.action.onClicked` does not fire when
+  `default_popup` is set in manifest — is a MV3 spec contract, not a
+  Puppeteer bug. [VERIFIED: probe3 — empirically reproduced both cases.]
+- Puppeteer 25.0.2 (current latest) handles MV3 extensions cleanly:
+  - `enableExtensions: ['/abs/path/to/dist']` at launch (also accepts `true`
+    to allow runtime install via `browser.installExtension(path)`)
+  - `browser.extensions()` returns `Map<id, Extension>` with `.id`, `.name`,
+    `.version`, `.pages()`, `.workers()`
+  - `page.triggerExtensionAction(ext)` simulates toolbar click
+
+**Critical MV3 contract**: per the Chrome docs (cited verbatim in the
+search result above), *"The action.onClicked event won't be sent if the
+extension action has specified a popup to show on click of the current
+tab."* Probe3 confirmed: `setPopup({popup:''})` → click → onClicked fires;
+`setPopup({popup:'src/popup/index.html'})` → click → popup opens, NO
+onClicked dispatch. Our plan-01-09 code already toggles popup state based
+on `isRecording` (this is the source of the routing this plan is testing).
+
+**Recommendation:** Use `page.triggerExtensionAction(ext)` as the primary
+click path. For assertions that need to bypass the popup gate (e.g., the
+ERROR-path direct test), call the captured handler ref via
+`sw.evaluate(() => __mokoshTest.handlers.onClicked({}))`.
+
+### 2. CDP attach to MV3 SW contexts
+
+**Findings:**
+- `browser.targets().filter(t => t.type() === 'service_worker')` is the
+  documented and only-tested path; works on Puppeteer 22+ across all
+  MV3 SW shapes (verified probe1, probe2, probe5).
+- The SW target URL is **`service-worker-loader.js`**, not the path you'd
+  expect from `manifest.json` (`src/background/index.ts`). This is crxjs's
+  loader wrapper — the wrapper imports the real bundle. **Implication:**
+  filter on `t.type() === 'service_worker'` only, NOT on URL suffix.
+- SW lifecycle in Puppeteer-driven Chrome: per Chrome docs (cited:
+  developer.chrome.com/blog/longer-esw-lifetimes), MV3 SWs terminate
+  after 30 s of inactivity. Per the same blog, opening DevTools keeps
+  SWs alive. Per ChromeDriver-based testing libraries' empirical
+  experience (cited: https://developer.chrome.com/blog/eyeos-journey...):
+  *"Service workers never terminate if the developer tools are open or
+  you are using a ChromeDriver based testing library."*
+  - **However**, this last claim could not be verified for Puppeteer-CDP
+    specifically. The probes ran fast enough (<5s) that 30s idle wasn't
+    relevant.
+  - **Defensive design:** between assertions, run a `sw.evaluate(() =>
+    chrome.runtime.getPlatformInfo())` "keepalive" call. Every async
+    chrome.* API call resets the 30s timer (Chrome 110+ behavior, cited).
+- Cold-start: probes always saw the SW target within ~1.5s of
+  `puppeteer.launch`. The `waitForTarget` API with a timeout makes this
+  race-free.
+
+**Recommendation:** Standard `waitForTarget` + `target.worker()`. Add a
+2-second keepalive ping (`chrome.runtime.getPlatformInfo()`) between
+assertions if the harness runtime exceeds ~25s.
+
+### 3. Chrome `--headless=new` + extensions
+
+**EMPIRICALLY VERIFIED on this machine (Chrome 148.0.7778.167, Puppeteer 25):**
+- ✅ MV3 extension loads in `--headless=new` (probe5)
+- ✅ SW eval works in headless (probe5)
+- ✅ `getDisplayMedia({ video: { displaySurface: 'monitor' } })` returns a real
+  stream in headless (probe11). The returned dimensions are 800×600 — that's
+  Chrome's default headless surface size (configurable via
+  `--window-size=W,H` or `defaultViewport` in puppeteer.launch).
+- ✅ `--auto-select-desktop-capture-source="Entire screen"` works in headless
+  (probe11)
+
+This contradicts older claims (Issue puppeteer/puppeteer#4404, mrd0x post)
+that screen capture requires headful + Xvfb. Those claims predate
+`--headless=new` (Chrome 109+ "true headless") which is now Puppeteer's
+default. The legacy `--headless=old` (now removed in Chrome ≥132) DID have
+this limitation.
+
+Issue Chromium 40176215 ("Headless must support getDisplayMedia") could
+not be read (auth-required page), but the empirical result on Chrome 148
+implies it is resolved or sufficiently worked-around.
+
+**Recommendation:** Run CI in `--headless=new` (Puppeteer's `headless: true`
+default in v22+). Local dev mode `headless: false` for debugging.
+**No Xvfb required.** Document this as a phase-level decision.
+
+### 4. vitest browser mode as alternative path
+
+**Findings:**
+- vitest 4 browser mode runs tests INSIDE the browser (uses Playwright
+  under the hood). The test file becomes a page in the browser.
+- This is the wrong direction for us: we need a Node-side driver that
+  attaches to a Chrome process running our extension. vitest browser mode
+  runs the test as a page; the test page has no access to extension SW or
+  cross-context fixtures.
+- No prior art found for MV3 extension E2E on vitest browser mode (search
+  returned only generic browser-mode guides).
+- Pulling in Playwright transitively defeats the "Puppeteer is lighter"
+  rationale.
+
+**Recommendation:** Skip vitest browser mode. Continue using vitest for
+unit tests; add the UAT harness as a separate Node script (`tests/uat/`)
+invoked from a new `npm run test:uat` script. Keep them disjoint so the
+vitest unit suite stays fast.
+
+### 5. Prior art from OSS MV3 extensions
+
+**Findings (most data harder to extract because GitHub pages render
+asymmetrically; the e2e directories required deeper drill-down than was
+practical in this research budget):**
+- **MetaMask** (`MetaMask/metamask-extension`): **Mocha + Selenium**.
+  Their e2e/ subdirectory contains `.mocharc.js`, Page Object Model,
+  fixtures, custom reporters, parallel run-all.mts. Not Puppeteer.
+  Setup: `test/env.js` + `test/setup.js` required globally. Sequential
+  by default. Uses Mocha's recursive discovery. Browser launch is via
+  SELENIUM_BROWSER env var; Xvfb-on-CI assumed. [CITED: GitHub repo
+  listing 2026-05]
+- **Bitwarden** (`bitwarden/clients`): GitHub repo too large to scrape via
+  WebFetch. From general community knowledge: Bitwarden uses Jest unit
+  tests + manual e2e historically. Not relevant.
+- **dappeteer** (Decentraland/ChainSafe/multiple forks): legacy MV2-era
+  Puppeteer wrapper for MetaMask. Now deprecated. Synpress (Cypress-based)
+  is the modern path for crypto-wallet extension testing — out of scope.
+- **Koweb3test** (referenced in search): explicitly says *"Tests work only
+  in headed mode because extensions are not supported in headless mode in
+  puppeteer and Cypress, and it's intended to be used in conjunction with
+  xvfb on CI."* This is **stale**; verified above that Chrome 148 +
+  Puppeteer 25 supports extensions in headless. The koweb3test claim was
+  true historically but no longer holds.
+- **Vimium, uBlock Origin**: did not find published e2e harnesses with
+  Puppeteer in available time.
+
+**Recommendation:** No OSS code can be lifted wholesale. The closest
+structural analogue is MetaMask's POM + helper-library split. Adopt
+that shape (split into `lib/` files) but skip Mocha — `node:test` or
+plain `tsx` script is enough for 13 deterministic assertions.
+
+### 6. crxjs + Vite `import.meta.env.MODE` tree-shaking
+
+**Findings:**
+- Vite **does** statically replace `import.meta.env.MODE` at build time
+  with a string literal when invoked via `vite build --mode <name>`.
+  Rollup (Vite's underlying bundler) then dead-code-eliminates the
+  unreachable branch. [CITED: vite.dev/guide/env-and-mode +
+  vitejs/vite#15256.]
+- **Caveat:** Tree-shaking fails *if the variable is undefined* in env.
+  But `MODE` is always defined (defaults to `'production'` for `vite build`
+  and `'development'` for `vite`). Safe for our `import.meta.env.MODE === 'test'`
+  guard.
+- crxjs (current 2.4.0): no explicit changelog entries about MODE handling.
+  Issue #831 (closed) was about custom env vars in dev mode not being
+  populated in the SW, NOT about MODE / DEV / PROD which were stated to
+  always be populated. Our use case (MODE-based gating in `vite build --mode test`)
+  is on the always-works path.
+- **Critical verification step we OWE the planner:** build BOTH bundles
+  and grep `dist/service-worker-loader.js` (and the bundled background
+  chunk) for any string from the test hook (e.g. `__mokoshTest`). If
+  the production bundle contains it, our gate didn't tree-shake.
+  This is a Wave 0 gate.
+
+**Recommendation:** Use `import.meta.env.MODE === 'test'` as the guard.
+Confirm in plan with explicit grep step on built artifact (`! grep -q
+__mokoshTest dist/...`). Use **dynamic import** (`await import('...')`)
+inside the guard so the test-hook MODULE itself is tree-shaken from
+production, not just the call:
+
+```typescript
+// src/background/index.ts
+if (import.meta.env.MODE === 'test') {
+  await import('../test-hooks/sw-hooks');
+}
+```
+
+### 7. MediaStreamTrack `track.stop()` vs Chrome "Stop sharing" button event parity
+
+**THIS IS THE BLOCKER.**
+
+**Findings (W3C spec + MDN + empirical):**
+- W3C Media Capture and Streams spec, `MediaStreamTrack.stop()` algorithm:
+  *"When a MediaStreamTrack track ends for any reason other than the
+  stop() method being invoked, the user agent MUST queue a task that sets
+  the track's readyState to ended and fire a simple event named ended at
+  the object."* (Cite: https://w3c.github.io/mediacapture-main/#mediastreamtrack)
+- MDN (authoritative, with W3C link):
+  *"The only case where the track ends but the ended event is not fired
+  is when calling MediaStreamTrack.stop."*
+  (Cite: https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/ended_event)
+- **Empirical confirmation in Chrome 148 (probe7):**
+  - `track.stop()` → `endedFired: 0`, `readyState: 'ended'`
+  - `track.dispatchEvent(new Event('ended'))` → `endedFired: 1`, `readyState: 'live'`
+- Our offscreen handler `onUserStoppedSharing` at
+  `src/offscreen/recorder.ts:451-480` is registered as
+  `track.addEventListener('ended', onUserStoppedSharing, { once: true })`
+  (line 275). It is a pure event listener — it does not inspect any
+  property to discriminate stop() vs source-ended; it fires whenever the
+  event fires.
+
+**Implication for the harness:**
+- The Bug B assertion ("user stopped sharing → badge OFF, NOT recovery
+  notif") MUST use `track.dispatchEvent(new Event('ended'))` from the
+  offscreen page context, not `track.stop()`.
+- Because dispatchEvent leaves the track in `readyState: 'live'`, the
+  production `onUserStoppedSharing` handler proceeds normally: it calls
+  `stream.getTracks().forEach(t => t.stop())` which DOES release the
+  actual capture (since stop() doesn't refire 'ended' on the same track,
+  and the `{ once: true }` listener removed itself after the synthetic
+  dispatch).
+- The harness must wait briefly after dispatch (~200ms) for the SW-side
+  state change (badge OFF, popup '', isRecording=false) to propagate
+  before asserting.
+
+**Without this workaround, the Bug B harness check is INVALID.** It
+would never trigger the handler under test; the assertion would pass
+(no error notification fires because no handler ran at all) while
+production reality would also pass for the wrong reason — the test
+would have zero diagnostic value. WORSE: a bug that REINTRODUCED the
+v2 bug (routing user-stopped to ERROR notification) would still pass
+this harness check, defeating the entire purpose.
+
+**Recommendation:** Plan MUST include an inline code comment + ADR-class
+note at the dispatchEvent call site explaining WHY it's not stop(). Wave
+0 must include a unit-level verification that the dispatched event
+triggers our handler (e.g., a vitest test that constructs a stub stream
+and asserts the handler fires). Belt + suspenders.
+
+### 8. getDisplayMedia user-activation propagation via CDP
+
+**Findings:**
+- W3C spec requires *"transient user activation"* for getDisplayMedia
+  (cite: https://w3c.github.io/mediacapture-screen-share/#dom-mediadevices-getdisplaymedia).
+- Chrome implementation accepts CDP-synthesized userGesture by default.
+  Puppeteer's `page.evaluate` passes `userGesture: true` to
+  `Runtime.evaluate` — has done so since pre-22 (cited in Puppeteer
+  ExecutionContext.ts source).
+- **Empirically (probe10):** both `page.evaluate(getDisplayMedia)` and
+  raw CDP `Runtime.evaluate { userGesture: true }` succeeded against
+  the offscreen page. We do not need the workaround of "inject the call
+  into a real click event handler in offscreen DOM."
+- **Caveat:** older Puppeteer issues (#13478) report crashes when closing
+  pages with active media streams. Mitigation: explicitly call
+  `stream.getTracks().forEach(t => t.stop())` before `browser.close()`.
+  Our existing teardown paths already do this — harness must also do it
+  on its own probe streams.
+
+**Recommendation:** No special handling needed. The production
+getDisplayMedia path runs unchanged in the test harness. Just ensure
+clean teardown.
+
+### 9. `--auto-select-desktop-capture-source` reliability
+
+**Findings:**
+- Flag is **locale-specific** (well known; smoke.sh already documents this).
+  English builds use `"Entire screen"`; Russian `"Весь экран"`.
+- Verified in probe10 + probe11 working with `="Entire screen"` on this
+  machine's en_US Chrome 148.
+- **Headless gotcha:** when running `--headless=new`, the picker UI never
+  actually surfaces (no display), but the flag still pre-selects the
+  source server-side. getDisplayMedia returns immediately. Confirmed
+  probe11.
+- Conflict: `--use-fake-ui-for-media-stream` + `--auto-select-desktop-capture-source`
+  → Chrome ignores the auto-select. Do not combine. (Cite:
+  groups.google.com/g/discuss-webrtc/c/t0u6aVBfCgU.)
+- Newer flag `--auto-accept-this-tab-capture` exists for `getDisplayMedia({
+  preferCurrentTab: true })` flow but is irrelevant to us (we use
+  `displaySurface: 'monitor'`).
+
+**Recommendation:** Pass `--auto-select-desktop-capture-source="Entire screen"`
+in the harness Chrome args. Do NOT add `--use-fake-ui-for-media-stream`.
+For CI portability across locales, document that test runners must use
+en_US locale (LANG/LC_ALL env) or override with the locale-correct
+string. This matches the constraint already in production smoke.sh.
+
+### 10. Two-bundle separation orchestration
+
+**Findings:**
+- crxjs uses a static `manifest.json` (imported in `vite.config.ts`).
+  Conditional content cannot be expressed through MODE alone inside that
+  static object.
+- Workaround: TWO vite configs. `vite.test.config.ts` extends prod and
+  swaps `outDir` + adds any test-specific manifest fields. Crxjs supports
+  this — the manifest is just imported JS data; you can pre-process it
+  per config file.
+- Alternative: ONE vite config that reads `process.env.npm_lifecycle_event`
+  (set to `'build:test'` when invoked via `npm run build:test`) and
+  branches. Simpler but couples build logic to npm script names. NOT
+  recommended.
+- Path: `dist/` for prod, `dist-test/` for test. The harness's
+  `enableExtensions` arg points to `dist-test/`.
+
+**Recommended package.json changes:**
+```jsonc
+{
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "build:test": "tsc && vite build --mode test --config vite.test.config.ts",
+    "preview": "vite preview",
+    "test": "vitest run",
+    "test:uat": "npm run build:test && tsx tests/uat/harness.test.ts"
+  }
+}
+```
+
+**Recommended `vite.test.config.ts`:**
+```typescript
+import { defineConfig, mergeConfig } from 'vite';
+import baseConfig from './vite.config';
+
+export default defineConfig((env) =>
+  mergeConfig(baseConfig, {
+    mode: 'test',
+    build: { outDir: 'dist-test', emptyOutDir: true },
+  })
+);
+```
+
+The `mode: 'test'` plus the CLI `--mode test` flag together ensure
+`import.meta.env.MODE === 'test'` resolves to `true` at build time and
+the test-hook branch survives.
+
+**Recommendation:** Two configs, two outputs, hook gated via
+`import.meta.env.MODE === 'test'` + dynamic import. Wave 0 grep
+verification that production `dist/` has zero `__mokoshTest` strings.
+
+## Common Pitfalls
+
+### Pitfall 1: Wrong target type for offscreen
+**What:** Looking for `t.type() === 'page'` on the offscreen doc; it's
+actually `'background_page'`.
+**Why:** Chrome internally classifies extension offscreen documents
+under the legacy background_page type tag.
+**Avoid:** Filter `t.type() === 'background_page' && t.url().includes('offscreen')`.
+Use `.asPage()` not `.page()`.
+
+### Pitfall 2: track.stop() doesn't fire 'ended'
+**What:** Harness "simulates user-stopped" by calling track.stop(). Test
+passes silently. Production handler never ran. (See §7.)
+**Avoid:** Use `track.dispatchEvent(new Event('ended'))`.
+
+### Pitfall 3: onClicked doesn't fire when popup is set
+**What:** triggerExtensionAction succeeds but our SW handler doesn't fire.
+**Why:** MV3 spec: popup wins over onClicked. Plan 01-09 toggles
+`setPopup({popup:''})` based on isRecording, so the harness must respect
+this state machine and only trigger toolbar clicks when popup is cleared
+(idle state) — OR call the captured handler ref directly via the hook.
+**Avoid:** Read popup state first; click only when popup is `""`. For
+"click during recording" assertion (popup opens, NO new picker), assert
+on popup state and on absence of new mediaStream, not on handler invocation.
+
+### Pitfall 4: Production bundle contains test hooks
+**What:** Tree-shaking didn't strip the hook. Production ships with
+`__mokoshTest` exposed.
+**Why:** Vite tree-shaking only works on statically resolvable conditions.
+A dynamic env read (process.env.X) won't shake.
+**Avoid:** Use the literal `import.meta.env.MODE === 'test'`. Verify with
+`grep -q __mokoshTest dist/**` in build script.
+
+### Pitfall 5: SW dies mid-test
+**What:** Harness runs for 40+ seconds without touching the SW; SW
+unloads; next `sw.evaluate` errors.
+**Why:** 30s idle rule (Chrome 110+); reset by chrome.* API calls.
+**Avoid:** Keepalive helper that pings `chrome.runtime.getPlatformInfo()`
+every 20s during long sequences. Most assertions touch chrome.* APIs
+anyway so this is mostly defensive.
+
+### Pitfall 6: --load-extension flag (deprecated)
+**What:** Copying patterns from old blog posts that use
+`puppeteer.launch({ args: ['--load-extension=' + path] })`.
+**Why:** Removed in Chrome 137 branded builds (cite:
+developer.chrome.com/blog/extension-news-june-2025). Puppeteer's
+`enableExtensions` arg replaces it and passes the necessary
+`--enable-unsafe-extension-debugging` automatically.
+**Avoid:** Use `enableExtensions: ['/abs/path/to/dist-test']`. Period.
+
+### Pitfall 7: Locale-dependent --auto-select-desktop-capture-source
+**What:** Test runs on a Russian-locale CI runner; "Entire screen"
+doesn't match; getDisplayMedia hangs at picker.
+**Avoid:** Document required locale in CI script; OR explicitly set
+`LC_ALL=en_US.UTF-8` in the harness child_process env.
+
+## Code Examples
+
+### Minimal working harness skeleton (top-of-file imports + setup)
+```typescript
+// tests/uat/harness.test.ts
+// Run with: npm run build:test && tsx tests/uat/harness.test.ts
+import { strict as assert } from 'node:assert';
+import puppeteer, { Browser, Extension, Page } from 'puppeteer';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const distTest = path.resolve(__dirname, '../../dist-test');
+
+const browser: Browser = await puppeteer.launch({
+  pipe: true,
+  enableExtensions: [distTest],
+  headless: process.env.CI ? true : false,
+  args: [
+    '--no-sandbox',
+    '--auto-select-desktop-capture-source=Entire screen',
+  ],
+});
+
+const exts = await browser.extensions();
+const [extId, ext] = [...exts][0];
+const swTarget = await browser.waitForTarget(t => t.type() === 'service_worker', { timeout: 10_000 });
+const sw = await swTarget.worker();
+const page = await browser.newPage();
+await page.goto('about:blank');
+
+console.log(`harness: extId=${extId}`);
+
+// VERIFIED PATH: triggerExtensionAction routes to onClicked when popup is ''
+await sw.evaluate(() => chrome.action.setPopup({ popup: '' }));
+await page.triggerExtensionAction(ext);
+// ... wait briefly for offscreen + getDisplayMedia ...
+await new Promise(r => setTimeout(r, 2000));
+
+const badge = await sw.evaluate(() => chrome.action.getBadgeText({}));
+assert.equal(badge, 'REC', 'badge should read REC after toolbar click in idle');
+
+// ... 12 more assertions ...
+
+await browser.close();
+console.log('UAT harness: 13/13 assertions passed');
+```
+
+### Synthetic chrome.notifications + iconUrl assertion (Bug A)
+```typescript
+// Bug A: chrome.notifications.create rejects manifest URL paths in some Chrome
+// builds when icon dimensions don't meet floor. We test that production code
+// uses a known-valid path AND that the create() call succeeds.
+
+// Method A: capture the actual notification options Production sends, via
+// the SW test-hook (wrap chrome.notifications.create at hook init time).
+// Method B: re-issue the same create() options ourselves and assert success.
+// Plan should use Method A for fidelity.
+
+const notifSnapshot = await sw.evaluate(() => globalThis.__mokoshTest.lastNotificationOptions);
+assert.ok(notifSnapshot, 'production code must have called notifications.create');
+assert.match(notifSnapshot.iconUrl, /icons\/icon48\.png$/, 'must use 48px iconUrl');
+// Verify the file actually exists in the bundle
+const iconBytes = await sw.evaluate(async () => {
+  const r = await fetch(chrome.runtime.getURL('icons/icon48.png'));
+  return r.ok ? r.headers.get('content-length') : null;
+});
+assert.ok(iconBytes && parseInt(iconBytes) > 100, 'icon48.png must exist in bundle');
+```
+
+### Bug B assertion (user-stopped routes to OFF, not ERROR)
+```typescript
+const off = browser.targets().find(t =>
+  t.type() === 'background_page' && t.url().includes('offscreen'));
+assert.ok(off, 'offscreen must exist (recording in progress)');
+const offPage = await off.asPage();
+
+// Snapshot notification side-effects before the synthetic event
+const before = await sw.evaluate(() => globalThis.__mokoshTest.notificationCount);
+
+// CRITICAL: dispatchEvent, NOT track.stop() — see RESEARCH §7
+await offPage.evaluate(() => {
+  const t = globalThis.__mokoshTest.getCurrentStream().getVideoTracks()[0];
+  t.dispatchEvent(new Event('ended'));
+});
+
+// Wait for SW-side state transition (the offscreen handler posts a
+// runtime message → SW handler updates badge + clears popup)
+await new Promise(r => setTimeout(r, 300));
+
+const badgeAfter = await sw.evaluate(() => chrome.action.getBadgeText({}));
+const popupAfter = await sw.evaluate(() => chrome.action.getPopup({}));
+const after = await sw.evaluate(() => globalThis.__mokoshTest.notificationCount);
+
+assert.equal(badgeAfter, '', 'badge must be OFF after user-stopped');
+assert.equal(popupAfter, '', 'popup must be cleared (back to idle)');
+assert.equal(after, before, 'no new notification — user-stop is NOT an error');
+```
+
+## State of the Art
+
+| Old Approach | Current Approach | When Changed | Impact |
+|--------------|------------------|--------------|--------|
+| `--load-extension` flag | `enableExtensions: [path]` option | Chrome 137 (mid-2025) | Old code stops working on branded Chrome; Puppeteer's option auto-passes the right new flags |
+| Headful + Xvfb for extension testing | `--headless=new` works | Chrome 109+, fully shipped by ~Chrome 120; Puppeteer 22+ default | Cuts CI infrastructure: no display server needed |
+| `target.page()` for any non-page target returns null | `target.asPage()` returns a Page wrapper for `background_page` | Puppeteer 22+ | Lets us evaluate JS inside the offscreen document with the high-level Page API |
+| `chrome.action.onClicked` clickable via DOM hacks | `page.triggerExtensionAction(ext)` | Puppeteer 22+ (commit d6395ef) | Issue #2486 resolved upstream; no more workaround folklore |
+
+**Deprecated/outdated:**
+- `puppeteer.launch({ args: ['--load-extension=...'] })` — superseded by `enableExtensions`
+- `dappeteer` — deprecated by upstream maintainers; Synpress is the modern replacement
+- The claim "Puppeteer can't load extensions in headless" (still widely
+  echoed in blog posts) — verified false on current Chrome/Puppeteer
+
+## Assumptions Log
+
+| # | Claim | Section | Risk if Wrong |
+|---|-------|---------|---------------|
+| A1 | Issue puppeteer#8987 is a typo and doesn't refer to a specific limit on onClicked dispatch | §1 | LOW — the MV3 popup-vs-onClicked contract is the real constraint, verified by probe3 |
+| A2 | ChromeDriver's "SW never terminates" claim extends to Puppeteer-CDP-attached SWs | §2 | LOW — defensive keepalive ping covers either case; the 30s idle rule resets on any chrome.* call |
+| A3 | crxjs 2.4.0 passes through Vite's MODE-conditional tree-shaking without interference for dynamic-imported test-hook modules | §6 | MEDIUM — must be verified in Wave 0 with explicit grep on built artifact. If wrong, plan must switch to two separate manifests or a build-time substitution plugin |
+| A4 | Production `onUserStoppedSharing` will treat a dispatchEvent-fired 'ended' identically to a real source-ended event | §7 | LOW — the handler is a pure event listener; it doesn't read `event.isTrusted` or any property; only the firing matters [VERIFIED by code read of `src/offscreen/recorder.ts:451-480`] |
+| A5 | Chrome 148+ Puppeteer behavior is stable across at least the next 6 months of Chrome releases | §3 | MEDIUM — Chrome's headless mode is generally stable post-109, but Chromium issue 40176215 was unreadable. If a future Chrome regresses headless screen capture, fall back to headful + Xvfb (smoke.sh already documents this path) |
+| A6 | The harness can rely on `--auto-select-desktop-capture-source="Entire screen"` working in CI runners' default locale (en_US) | §9 | LOW — most CI defaults to en_US; doc'd how to override if not |
+
+## Open Questions for the Planner
+
+1. **Where exactly does the `simulateUserStop` shim live?**
+   - Recommended: `src/test-hooks/offscreen-hooks.ts` imported conditionally
+     from `src/offscreen/recorder.ts` after `mediaStream` is assigned. The
+     hook reads `mediaStream` via a getter exposed at module load time:
+     `const __sharedRefs = { get currentStream() { return mediaStream; } }`.
+     Planner decides exact integration.
+
+2. **Should the harness assert on the exact NUMBER of notifications, or
+   set-membership?**
+   - Bug A and onStartup notification fire once each; recovery notification
+     fires on RECORDING_ERROR. Counting is brittle if the SW retries.
+     Set-membership (asserting on the *types* of notifications) is more
+     robust. Planner decides UX.
+
+3. **CI tool: GitHub Actions matrix? Or standalone shell?**
+   - Out of scope for THIS plan if there's no existing CI infrastructure.
+     The harness should be a single `npm run test:uat` invocation that
+     works locally; CI plumbing can be a separate plan.
+
+4. **Failure isolation: do we kill Chrome between assertions, or keep one
+   long-running browser instance?**
+   - Recommended: one browser, serial assertions (faster, fewer flakes from
+     extension reload races). If an assertion fails mid-sequence, abort and
+     dump SW + offscreen console logs. Planner decides whether to add
+     retries or full-restart isolation.
+
+5. **What's the contract for the test-hook surface?**
+   - `globalThis.__mokoshTest` shape needs to be declared as a TS type so
+     both the SW side (registers) and the harness side (reads) agree. Place
+     in `tests/uat/lib/test-hook-contract.d.ts`? Or `src/test-hooks/types.ts`?
+     Both — planner decides if it's worth the duplication or a shared dir.
+
+## Environment Availability
+
+| Dependency | Required By | Available | Version | Fallback |
+|------------|------------|-----------|---------|----------|
+| Node.js | Puppeteer 25 requires ≥22.12 | ✓ | v24.14.0 | — |
+| google-chrome-stable | Puppeteer auto-fetch backup if missing | ✓ | 148.0.7778.167 | Puppeteer downloads its own Chrome for Testing if missing |
+| ffprobe | WebM validity assertion | ✓ | 8.1.1 | — |
+| `unzip` (or jszip in-process) | ZIP shape assertion | ✓ via jszip already in deps | — | — |
+| Xvfb | Not required — headless mode supports getDisplayMedia | not installed | — | Optional; only needed if a future Chrome regresses headless capture |
+
+**Missing dependencies with no fallback:** none.
+**Missing dependencies with fallback:** Xvfb (defensive only).
+
+## Validation Architecture
+
+**TDD mode is ON.** Each of the 13+ harness assertions is itself a test.
+The planner should structure Wave 0 to build the harness skeleton with
+stubs for all 13 assertions (initially failing), then Wave 1 to wire each
+assertion in turn (red → green per assertion).
+
+### Test Framework
+| Property | Value |
+|----------|-------|
+| Framework | `node:test` (built-in) OR plain `node:assert/strict` script — no extra dep |
+| Config file | none (harness is a single script) |
+| Quick run command | `npm run test:uat` (orchestrates build:test + harness) |
+| Full suite command | same |
+
+### Phase Requirements → Test Map
+The planner's 13 assertions map 1:1 to the brief's list:
+| Req | Behavior | Method |
+|-----|----------|--------|
+| 1 | SW bootstrap → idle | sw.evaluate badge text == '', popup == '' |
+| 2 | onClicked-idle → REC | trigger click → wait → assert badge 'REC' + popup set |
+| 3 | displaySurface monitor | offscreenPage.evaluate `__mokoshTest.getCurrentStream().getVideoTracks()[0].getSettings().displaySurface == 'monitor'` |
+| 4 | click during recording → popup opens | trigger click → assert popup state, NO new offscreen target spawned |
+| 5 | SAVE_ARCHIVE → download | sw.evaluate sendMessage SAVE → wait → check Downloads dir |
+| 6 | user-stopped routes to OFF | offscreenPage.evaluate dispatchEvent → assert no error notif + badge '' |
+| 7 | RECORDING_ERROR codec → ERR badge + notif | sw.evaluate sendMessage RECORDING_ERROR → assert badge 'ERR' + notif fired |
+| 8 | onStartup → notification with iconUrl | sw.evaluate `__mokoshTest.handlers.onStartup()` → assert notification create succeeded |
+| 9 | icon files present | sw.evaluate fetch icon URLs → assert HTTP 200 + size > floor |
+| 10 | Manifest declares notifications + icons | sw.evaluate `chrome.runtime.getManifest()` → assert permissions + icons |
+| 11 | Buffer ≥3 segments after 35s | sw.evaluate query offscreen state (via runtime message) |
+| 12 | Remux passes ffprobe | spawn `ffprobe -v error -f matroska -i <path>`, exit 0 |
+| 13 | Zip shape | jszip parse → assert `video/last_30sec.webm` + `meta.json` keys |
+
+### Sampling Rate
+- **Per task commit:** `npm test` (vitest unit) — fast (~5s)
+- **Per wave merge:** `npm run test:uat` (full harness ~60s)
+- **Phase gate:** harness green + smoke.sh still passes for operator brand check
+
+### Wave 0 Gaps
+- [ ] `vite.test.config.ts` — does not exist
+- [ ] `tests/uat/harness.test.ts` — does not exist (skeleton with 13 failing assertions)
+- [ ] `tests/uat/lib/*.ts` — helper modules
+- [ ] `src/test-hooks/sw-hooks.ts` + `offscreen-hooks.ts` — does not exist
+- [ ] `package.json` — add `puppeteer` + `tsx` devDeps + `test:uat` script
+- [ ] Grep check in build:test to fail loudly if production bundle contains `__mokoshTest`
+
+## Security Domain
+
+| ASVS Category | Applies | Standard Control |
+|---------------|---------|-----------------|
+| V2 Authentication | no | n/a (test harness only) |
+| V5 Input Validation | no | n/a |
+| V14 Configuration | yes | Test hook MUST NOT ship in production bundle — Wave 0 grep gate enforces |
+
+| Pattern | STRIDE | Standard Mitigation |
+|---------|--------|---------------------|
+| Test hook leaks into production → attacker invokes `__mokoshTest.simulateUserStop` from arbitrary page | Tampering/Elevation of Privilege | Build-time tree-shake gate + post-build grep verification |
+
+## Sources
+
+### Primary (HIGH confidence — empirically verified in this session)
+- Local probes 1-11 against `/home/parf/projects/work/repremium/dist` on Chrome 148.0.7778.167 + Puppeteer 25.0.2 (probe scripts at `/tmp/puppeteer-probe/probe*.js`)
+- `npm view puppeteer version` → 25.0.2 (engines node ≥22.12.0)
+- `/usr/bin/google-chrome-stable --version` → 148.0.7778.167
+- Source code read: `/home/parf/projects/work/repremium/src/offscreen/recorder.ts:275, 451-480` — confirms event-listener-only handler (no isTrusted check)
+
+### Secondary (HIGH confidence — official docs)
+- Puppeteer: https://pptr.dev/guides/chrome-extensions
+- Puppeteer extension testing: https://developer.chrome.com/docs/extensions/how-to/test/puppeteer
+- W3C Media Capture: https://w3c.github.io/mediacapture-main/#mediastreamtrack
+- MDN ended event: https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/ended_event
+- MDN getDisplayMedia: https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getDisplayMedia
+- Chrome SW lifetime: https://developer.chrome.com/blog/longer-esw-lifetimes
+- Chrome ext news June 2025 (--load-extension removal): https://developer.chrome.com/blog/extension-news-june-2025
+- Vite env + modes: https://vite.dev/guide/env-and-mode
+- Chrome screen-sharing controls: https://developer.chrome.com/docs/web-platform/screen-sharing-controls
+- Puppeteer triggerExtensionAction PR: https://github.com/puppeteer/puppeteer/commit/d6395ef88103a50cb2b2c43f61953ab6a495a8c3
+
+### Tertiary (MEDIUM confidence — community sources)
+- Issue puppeteer#2486 (closed, fixed upstream): https://github.com/puppeteer/puppeteer/issues/2486
+- Issue puppeteer#4404 (open, historical context — limitation no longer holds on Chrome 148): https://github.com/puppeteer/puppeteer/issues/4404
+- Issue crxjs/chrome-extension-tools#831 (custom env vars in dev mode): https://github.com/crxjs/chrome-extension-tools/issues/831
+- MetaMask e2e structure (Mocha + Selenium reference): https://github.com/MetaMask/metamask-extension/tree/main/test/e2e
+- Stop sharing event timing (twilio-video.js#849): https://github.com/twilio/twilio-video.js/issues/849
+- auto-select-desktop-capture-source in headless: https://groups.google.com/g/discuss-webrtc/c/t0u6aVBfCgU
+
+### Could not verify (flagged for planner)
+- Chromium issue 40176215 ("Headless must support getDisplayMedia") — auth-required page; status unreadable. Mitigated by empirical probe11 confirming current Chrome 148 supports it.
+- Full puppeteer CHANGELOG word-by-word search for extension API maturation — GitHub WebFetch returned only page chrome, not content. Inferred timeline from commit metadata + current docs.
+
+## Metadata
+
+**Confidence breakdown:**
+- Standard stack: HIGH — verified against npm registry + working `npm install`
+- Architecture: HIGH — all five Patterns above demonstrated by local probes
+- Pitfalls 1-7: HIGH for 1-5 (probed), MEDIUM for 6-7 (cited but not probed; Pitfall 6 is doc'd in Chrome's own blog)
+- Bug B mechanism (§7): HIGH — both W3C spec cite AND empirical Chrome 148 reproduction
+- Two-bundle build (§6, §10): MEDIUM — design is correct per Vite docs but the specific A3 assumption needs Wave 0 verification grep on built artifact
+
+**Research date:** 2026-05-17
+**Valid until:** 2026-08-17 (90 days; longer than usual because the core APIs cited — W3C spec for MediaStreamTrack, Vite MODE behavior, Puppeteer extension API — are stable. Re-verify if Chrome major version jumps past 152 or Puppeteer past 26.)