feat(01-11): wave-1 — gated test hooks for SW + offscreen, dist/ stays hook-free

Task 2 of Plan 01-11 (Puppeteer UAT harness).

Test hook surface:
- src/test-hooks/types.ts: canonical MokoshTestSurface — handlers
  (onClicked, onStartup, notificationOnClicked), notificationCount,
  lastNotificationOptions<true>, notificationIds, getCurrentStream,
  getSegmentCount. globalThis.__mokoshTest ambient declaration.
- src/test-hooks/sw-hooks.ts: SW-side hook. Monkey-patches addListener
  on chrome.action.onClicked / chrome.runtime.onStartup / chrome
  .notifications.onClicked to capture handler refs while chaining to
  the original. Wraps chrome.notifications.create across all four
  overload shapes (id+options+cb, options+cb, id+options→Promise,
  options→Promise) to increment notificationCount, save
  lastNotificationOptions, push resolved id into notificationIds.
- src/test-hooks/offscreen-hooks.ts: offscreen-side hook. Exports
  setCurrentStream + setSegmentCountGetter; the recorder calls both
  inside startRecording after the mediaStream + segments assignments.
  getCurrentStream getter closes over the cell so the harness reads
  the live MediaStream for displaySurface inspection + 'ended'
  dispatch (Bug B BLOCKER per RESEARCH §7).
- tests/uat/lib/test-hook-contract.d.ts: manual harness-side mirror of
  MokoshTestSurface (decoupled from src/ to keep tests/ import-clean
  per RESEARCH §11 resolution 5; drift risk documented inline).

Production-side wires (gated by __MOKOSH_UAT__ token):
- src/background/index.ts top-of-module: `if (__MOKOSH_UAT__) { await
  import('../test-hooks/sw-hooks'); }`. MUST run before any chrome.*
  addListener call below — top-of-module placement satisfies this.
- src/offscreen/recorder.ts top-of-module: symmetric gated dynamic
  import + module-scoped testHooks reference.
- src/offscreen/recorder.ts inside startRecording (after mediaStream
  assignment): `if (__MOKOSH_UAT__) { testHooks?.setCurrentStream(stream);
  testHooks?.setSegmentCountGetter(() => segments.length); }`
- src/offscreen/recorder.ts inside onUserStoppedSharing (after
  mediaStream = null): `if (__MOKOSH_UAT__) { testHooks?.setCurrentStream(null); }`
  — T-1-11-05 (Repudiation: stale stream ref) mitigation.

Build-time token wiring:
- vite.config.ts: declares `define: { __MOKOSH_UAT__: 'false' }` (prod
  default) + bumps `build.target: 'es2022'` so the top-level await in
  the gated dynamic imports compiles (MDN: Chrome 89 / Edge 89 /
  Firefox 89 / Safari 15 support TLA; MV3 floor Chrome 88 is
  effectively Chrome 89+ in field — comfortably inside the envelope).
- vite.test.config.ts: overrides `define: { __MOKOSH_UAT__: 'true' }`
  so the test bundle has the hooks active.
- vitest.config.ts: declares `define: { __MOKOSH_UAT__: 'false' }` for
  vitest's own source-loading runs. CRITICAL — without this, vitest
  would throw `ReferenceError: __MOKOSH_UAT__ is not defined` when
  loading src/background/index.ts; OR if we'd used `import.meta.env.MODE
  === 'test'` (RESEARCH §6's initial guidance), vitest's default
  MODE='test' would have ACTIVATED the hooks under unit tests +
  clobbered every existing vi.fn() chrome.notifications.create mock.
  The dedicated `__MOKOSH_UAT__` token sidesteps both failure modes
  cleanly — a refinement on RESEARCH §6 documented in the comment
  preambles of all three configs.
- globals.d.ts: declares `__MOKOSH_UAT__: boolean` ambient so
  `npx tsc --noEmit` passes without per-file annotations.
- tsconfig.json: include adds `globals.d.ts`.

Notification options generic refinement:
- chrome.notifications.NotificationOptions is declared with a
  `<true | false>` generic distinguishing "create" (all required —
  true) from "update" (all optional — false). Plan 01-11's production
  code always uses the create shape; types.ts + sw-hooks.ts pin to
  `NotificationOptions<true>` so the harness reads iconUrl etc. as
  definitely-present.

Verification:
- npx tsc --noEmit: exit 0
- npm run build: exit 0
- grep -rln '__mokoshTest\|simulateUserStop\|getSegmentCount\|setCurrentStream\|setSegmentCountGetter' dist/:
  ZERO matches (Tier-1 gate stays GREEN)
- npm run build:test: exit 0; dist-test/ emits separate sw-hooks-*.js
  + offscreen-hooks-*.js chunks (the gated dynamic imports survive
  tree-shaking when __MOKOSH_UAT__ === true)
- grep -rln '__mokoshTest' dist-test/: 2 matches
  (assets/sw-hooks-*.js + assets/offscreen-hooks-*.js)
- SKIP_BUILD=1 npx vitest run: 89/89 GREEN
  (83 baseline + 6 Tier-1 hook-leak surfaces)
- sw-bundle-import.test.ts: GREEN (the gated dynamic import does not
  break production module init — the `if (false)` branch is never
  reachable so the await + import are dead code in dist/)

In-flight bugs auto-fixed (Rule 1 + Rule 3):
- Rule 3: original RESEARCH §6 plan called for `import.meta.env.MODE
  === 'test'` as the gate; switched to `__MOKOSH_UAT__` define-token
  after observing vitest contamination (vitest defaults MODE='test'
  → hooks activated under unit tests → 8 existing tests broke with
  "Cannot read properties of undefined (reading 'calls')" because the
  hook wrapper replaced vi.fn() mocks). Documented in the comment
  preambles of all three configs as a refinement on RESEARCH §6.
- Rule 3: esbuild rejected TLA against the default ES2020 target;
  bumped to es2022 (Chrome 89+ supports TLA per MDN — inside MV3
  envelope). Recorded in vite.config.ts preamble.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/test-hooks/offscreen-hooks.ts

@@ -0,0 +1,91 @@
+// src/test-hooks/offscreen-hooks.ts — Plan 01-11 Task 2 (offscreen-side test hook).
+//
+// Installs `globalThis.__mokoshTest` in the offscreen document's isolate.
+// The harness reads this surface via `offPage.evaluate(...)` to:
+//   - read `getCurrentStream().getVideoTracks()[0].getSettings().displaySurface`
+//     (assertion 3 — verifies monitor-only enforcement);
+//   - dispatch `new Event('ended')` on the video track (assertion 6 —
+//     the Bug B simulation per RESEARCH §7 BLOCKER. `track.stop()` does
+//     NOT fire 'ended' per W3C spec, so the production
+//     onUserStoppedSharing handler would never run — that is the trap
+//     this hook exists to expose);
+//   - read `getSegmentCount()` (assertion 11 — verifies 30s ring buffer
+//     per D-13).
+//
+// The offscreen recorder wires the runtime references via the two
+// setters exported below. These imports are gated by the same
+// `import.meta.env.MODE === 'test'` literal-comparison guard in
+// src/offscreen/recorder.ts as the SW-side hook; production builds
+// tree-shake the entire module away (Tier-1 grep gate verifies).
+//
+// Cross-isolate note: SW and offscreen are SEPARATE isolates with
+// SEPARATE `globalThis`. The SW-side sw-hooks.ts installs handler
+// captures + notification observability on the SW's globalThis;
+// this file installs stream + segment-count observability on the
+// offscreen's globalThis. The harness queries the appropriate isolate
+// per assertion. handlers / notificationCount / notificationIds /
+// lastNotificationOptions in this offscreen surface are present-but-
+// inert (initialized to empty values) to keep the type uniform across
+// isolates — the harness never reads them off the offscreen surface.
+//
+// Reference for MediaStreamTrack 'ended' event:
+//   https://developer.mozilla.org/docs/Web/API/MediaStreamTrack/ended_event
+// Reference for offscreen document isolation in MV3:
+//   https://developer.chrome.com/docs/extensions/reference/api/offscreen
+
+import type { MokoshTestSurface } from './types';
+
+// Module-level mutable cells holding the runtime references. The
+// recorder calls the setters; the surface getters close over the cells.
+let currentStream: MediaStream | null = null;
+let segmentCountGetter: () => number = () => 0;
+
+/**
+ * Wire the current MediaStream into the test surface. Called by
+ * src/offscreen/recorder.ts:startRecording immediately after the
+ * `mediaStream = stream` assignment AND on stream teardown (with
+ * null) so the surface tracks the live recording lifecycle.
+ *
+ * Idempotent — calling with the same value is a no-op equivalent.
+ *
+ * @param stream - The active MediaStream, or null when teardown.
+ */
+export function setCurrentStream(stream: MediaStream | null): void {
+  currentStream = stream;
+}
+
+/**
+ * Wire the segment-count getter into the test surface. Called once
+ * by src/offscreen/recorder.ts when the test bundle is active. The
+ * recorder holds a `let segments: Blob[]` module-local; the getter
+ * captures it by closure so the harness reads the live count without
+ * needing to import the recorder's source from the harness side.
+ *
+ * @param getter - Closure returning the current segments.length.
+ */
+export function setSegmentCountGetter(getter: () => number): void {
+  segmentCountGetter = getter;
+}
+
+// ─── Install the global surface ───────────────────────────────────────
+// Note: the offscreen isolate's globalThis is FRESH per offscreen
+// document creation (each createDocument restart resets it). The
+// gated dynamic import in recorder.ts top-of-module runs once per
+// offscreen lifetime, so each new offscreen document gets a fresh
+// surface install — there is no cross-lifetime contamination.
+globalThis.__mokoshTest = {
+  handlers: {
+    onClicked: null,
+    onStartup: null,
+    notificationOnClicked: null,
+  },
+  notificationCount: 0,
+  lastNotificationOptions: null,
+  get notificationIds() {
+    return [];
+  },
+  getCurrentStream: () => currentStream,
+  getSegmentCount: () => segmentCountGetter(),
+} as MokoshTestSurface;
+
+export {};