feat(01-11): wave-2 — Puppeteer harness scaffolding + A0 GREEN, popup-bridge architecture

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

Harness file tree (tests/uat/):
- harness.test.ts: tsx-runnable top-to-bottom harness entry point.
  Runs A0 inline (filesystem grep gate, abort-on-fail T-1-11-01),
  then launches Chrome + opens popup bridge + queries manifest, then
  iterates A1-A13 stubs. Each stub throws "NOT YET IMPLEMENTED —
  Plan 01-11 Task N wires this assertion". Exit code = 0 on full
  pass, 1 otherwise. Final line: "UAT harness: N/14 assertions passed".
- lib/launch.ts: launchHarnessBrowser() — wraps puppeteer.launch with
  enableExtensions:[dist-test/], headless default (HEADLESS=0
  override), --no-sandbox + --auto-select-desktop-capture-source flags.
  Polls browser.extensions() until the extension registers (empirically
  ~100ms but the first call right after launch returns Map(0)).
  Opens both a blank page (for triggerExtensionAction) AND the popup
  page (the bridge surface). Returns { browser, extension, extensionId,
  sw, downloadsDir, page, popup }.
- lib/extension.ts: waitForOffscreenTarget + attachToOffscreen +
  countOffscreenTargets. Offscreen attach uses target.type() ===
  'background_page' + .asPage() (NOT .page() — RESEARCH §4 Pitfall 1).
- lib/sw.ts: chrome.* state queries via the POPUP page handle (NOT
  the WebWorker handle — see architecture note below). getBadgeText,
  getPopup, getManifest, getIconSize, getIsRecording (side-channeled
  through badge text), fireOnStartup (via __mokoshTestQuery bridge),
  sendSyntheticRecordingError, getNotificationSnapshot (via bridge),
  keepalivePing (no-op message to wake SW for ~30s).
- lib/offscreen.ts: getDisplaySurface, simulateUserStop (the
  dispatchEvent('ended') path per RESEARCH §7 BLOCKER — DO NOT REFACTOR
  to track.stop()), getSegmentCount.
- lib/assertions.ts: runAssertion(idx, name, buffers, fn) wrapper —
  records pass/fail/duration; on failure dumps last 30 lines of SW
  + offscreen console buffers to stderr before rethrowing. assertEqual
  / assertMatch / assertTrue / assertGte / waitFor polling helper.
- lib/zip.ts: jszip-based assertArchiveShape + extractEntryToFile for
  assertions 12 + 13.
- README.md: runtime + local-debug + CI semantics + locale gotcha
  + dev-dep size note + assertion catalog table.
- tsconfig.json: per-tree type-check config (mirrors root tsconfig.json
  compiler options but includes the harness tree explicitly).

Architecture refinement (DEVIATION from RESEARCH §1 — Rule 1+3 inline fix):
- RESEARCH §1 sketched `sw.evaluate(() => chrome.action.getBadgeText({}))`
  as the chrome.* query path. Empirical probes during Task 3 execution
  against Puppeteer 25.0.2 + Chrome 148 + --headless=true revealed two
  blockers:
    1. Puppeteer's WebWorker.evaluate runs in an ISOLATED WORLD that
       carries SW globals (clients, registration, ...) but NOT the
       extension's full chrome.* API surface. Object.keys(chrome) inside
       sw.evaluate returns ["loadTimes","csi"] — the public webpage
       chrome, not the extension chrome.
    2. Chrome 148's headless mode aggressively suspends MV3 service
       workers; subsequent swTarget.worker() calls return
       "Protocol error: No target with given id found".
- WORKAROUND: open the popup page (chrome-extension://<id>/src/popup/
  index.html) as a separate Puppeteer Page. The popup has full
  chrome.* access (it's an extension context with same privileges as
  the SW) AND stable Puppeteer lifetime. For SW-globalThis state
  (__mokoshTest in the SW isolate, NOT in the popup), bridge via
  chrome.runtime.sendMessage. The popup sends
  { type: '__mokoshTestQuery', op: 'snapshot' | 'fire-on-startup' |
  'handler-types' }; the SW hook's onMessage handler responds.
- Bridge implementation added to src/test-hooks/sw-hooks.ts — registers
  AFTER the production listeners so it never intercepts production
  messages (__mokoshTest* type is unambiguously test-only). Tier-1
  grep gate (no-test-hooks-in-prod-bundle.test.ts) continues to enforce
  ZERO __mokoshTest occurrences in dist/ — the bridge handler is
  tree-shaken alongside the rest of the hook module via the
  __MOKOSH_UAT__ gate.

Other configuration changes:
- vitest.config.ts: exclude tests/uat/** from vitest discovery. The
  Puppeteer harness is invoked via `npm run test:uat` (not vitest);
  running it under vitest would try to launch real Chrome inside a
  vitest worker. The .test.ts suffix is retained for editor +
  naming-convention consistency with the rest of the tree.

Verification:
- npx tsc --noEmit (src/): exit 0
- npx tsc --noEmit -p tests/uat: exit 0
- npm run build: exit 0
- grep -rln '__mokoshTest|simulateUserStop|getSegmentCount|setCurrentStream|setSegmentCountGetter|__mokoshTestQuery|__mokoshKeepalive' dist/: ZERO matches
- npm run build:test: exit 0; dist-test/ populated with the new bridge code
- SKIP_BUILD=1 npx vitest run: 89/89 GREEN
- SKIP_PROD_REBUILD=1 npx tsx tests/uat/harness.test.ts:
  → A0 [PASS]: production bundle has no test-hook leaks (19ms)
  → Browser launches; popup opens; manifest read succeeds
  → A1-A13 [FAIL]: NOT YET IMPLEMENTED — Plan 01-11 Task N wires this
  → "UAT harness: 1/14 assertions passed, 13 failed (first failure: A1)"
  → Exit code: 1 (expected — 13 RED stubs intentional)

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

tests/uat/lib/assertions.ts

@@ -0,0 +1,199 @@
+// tests/uat/lib/assertions.ts — Plan 01-11 harness assertion runner.
+//
+// Centralizes:
+//   - `assertEqual` / `assertMatch` / `assertTrue` — thin wrappers
+//     over `node:assert/strict` with explicit Plan 01-11 diagnostic
+//     framing (cite the bug-class on Bug A / Bug B assertions).
+//   - `runAssertion(name, fn)` — wraps each assertion in a try/catch
+//     so the harness can collect a per-assertion pass/fail map AND
+//     dump SW/offscreen console buffers on the FIRST failure (bail
+//     semantics per RESEARCH §5).
+//   - `waitFor(probe, predicate, timeoutMs)` — polling helper used by
+//     assertions that need to wait for async state transitions
+//     (badge changes, downloads, etc.).
+//
+// References:
+//   - node:assert/strict: https://nodejs.org/api/assert.html#strict-assertion-mode
+
+import { strict as assert } from 'node:assert';
+
+/**
+ * Per-assertion outcome record. Accumulated by runAssertion + flushed
+ * to the harness's final summary line.
+ */
+export interface AssertionRecord {
+  readonly index: number;
+  readonly name: string;
+  readonly passed: boolean;
+  readonly errorMessage: string;
+  readonly durationMs: number;
+}
+
+/**
+ * Console buffers captured from SW + offscreen contexts. The harness
+ * wires `sw.on('console', ...)` + `offPage.on('console', ...)` at
+ * launch + before each assertion-relevant phase; on failure these
+ * buffers are dumped to stderr for triage.
+ */
+export interface ConsoleBuffers {
+  swLines: string[];
+  offscreenLines: string[];
+}
+
+/**
+ * Run a single assertion, capturing its outcome + duration. On error,
+ * dump the per-context console buffers to stderr BEFORE rethrowing so
+ * the harness's top-level catch sees the diagnostic context.
+ *
+ * @param index - 0-13 (0 = grep gate, 1-13 = functional).
+ * @param name - Human-readable assertion title.
+ * @param buffers - Console buffers to dump on failure (may be empty).
+ * @param fn - Async assertion body.
+ * @returns Outcome record.
+ */
+export async function runAssertion(
+  index: number,
+  name: string,
+  buffers: ConsoleBuffers,
+  fn: () => Promise<void>,
+): Promise<AssertionRecord> {
+  const start = Date.now();
+  try {
+    await fn();
+    const durationMs = Date.now() - start;
+    process.stdout.write(`  [PASS] A${index}: ${name} (${durationMs}ms)\n`);
+    return {
+      index,
+      name,
+      passed: true,
+      errorMessage: '',
+      durationMs,
+    };
+  } catch (err) {
+    const durationMs = Date.now() - start;
+    const errorMessage =
+      err instanceof Error ? `${err.name}: ${err.message}` : String(err);
+    process.stderr.write(`  [FAIL] A${index}: ${name} (${durationMs}ms)\n`);
+    process.stderr.write(`         ${errorMessage}\n`);
+    dumpBuffers(buffers, index);
+    return {
+      index,
+      name,
+      passed: false,
+      errorMessage,
+      durationMs,
+    };
+  }
+}
+
+/**
+ * Dump SW + offscreen console buffers to stderr with structured framing.
+ * Cap at the last 30 lines per context to keep failure output readable.
+ *
+ * @param buffers - The accumulating buffers.
+ * @param assertionIndex - For framing the dump preamble.
+ */
+function dumpBuffers(buffers: ConsoleBuffers, assertionIndex: number): void {
+  const TAIL = 30;
+  const swTail = buffers.swLines.slice(-TAIL);
+  const offTail = buffers.offscreenLines.slice(-TAIL);
+  if (swTail.length > 0) {
+    process.stderr.write(
+      `         --- SW console (last ${swTail.length} lines, assertion A${assertionIndex}) ---\n`,
+    );
+    for (const line of swTail) {
+      process.stderr.write(`           ${line}\n`);
+    }
+  }
+  if (offTail.length > 0) {
+    process.stderr.write(
+      `         --- Offscreen console (last ${offTail.length} lines, assertion A${assertionIndex}) ---\n`,
+    );
+    for (const line of offTail) {
+      process.stderr.write(`           ${line}\n`);
+    }
+  }
+}
+
+/**
+ * Strict equality with a context-bearing message. Wraps
+ * `assert.strictEqual` so the failure surface is uniform across
+ * assertions.
+ *
+ * @param actual - Observed value.
+ * @param expected - Expected value.
+ * @param msg - Context for the failure diagnostic.
+ */
+export function assertEqual<T>(actual: T, expected: T, msg: string): void {
+  assert.strictEqual(actual, expected, msg);
+}
+
+/**
+ * Assert that `actual` matches `regex`. Wraps `assert.match`.
+ *
+ * @param actual - String to test.
+ * @param regex - Pattern.
+ * @param msg - Context for the failure diagnostic.
+ */
+export function assertMatch(actual: string, regex: RegExp, msg: string): void {
+  assert.match(actual, regex, msg);
+}
+
+/**
+ * Assert that `cond` is truthy. Wraps `assert.ok`.
+ *
+ * @param cond - Boolean expression.
+ * @param msg - Context for the failure diagnostic.
+ */
+export function assertTrue(cond: boolean, msg: string): void {
+  assert.ok(cond, msg);
+}
+
+/**
+ * Assert that the actual value is greater than or equal to expected.
+ * Used by assertion 9 (icon size floors) + assertion 11 (segment count).
+ *
+ * @param actual - Observed value.
+ * @param expected - Minimum acceptable value.
+ * @param msg - Context for the failure diagnostic.
+ */
+export function assertGte(actual: number, expected: number, msg: string): void {
+  assert.ok(
+    actual >= expected,
+    `${msg} — expected >= ${expected}, got ${actual}`,
+  );
+}
+
+/**
+ * Poll `probe` until `predicate(probe())` returns true OR timeoutMs
+ * elapses. Throws on timeout with a structured diagnostic.
+ *
+ * @param probe - Async function producing a value to test.
+ * @param predicate - Returns true when the value satisfies the wait.
+ * @param timeoutMs - Maximum wait time.
+ * @param description - Human-readable description for the diagnostic.
+ * @param pollIntervalMs - Interval between probe calls (default 100ms).
+ * @returns The last probed value that satisfied the predicate.
+ * @throws If timeoutMs elapses without predicate satisfaction.
+ */
+export async function waitFor<T>(
+  probe: () => Promise<T>,
+  predicate: (v: T) => boolean,
+  timeoutMs: number,
+  description: string,
+  pollIntervalMs: number = 100,
+): Promise<T> {
+  const start = Date.now();
+  let lastValue: T | undefined;
+  while (Date.now() - start < timeoutMs) {
+    lastValue = await probe();
+    if (predicate(lastValue)) {
+      return lastValue;
+    }
+    await new Promise((r) => setTimeout(r, pollIntervalMs));
+  }
+  throw new Error(
+    `waitFor timeout ${timeoutMs}ms — ${description}; ` +
+      `last probed value: ${JSON.stringify(lastValue)}`,
+  );
+}