amethyst/nestsClient/plans/2026-05-06-phase4-browser-harness-results.md

# Plan: Phase 4 (browser harness) — landed results

**Status:** ✅ Phase 4.A (scaffold) + 4.B (Playwright driver) +
4.C (full scenario coverage) all landed. Phase 4.D (CI workflow
job) was originally added in commit `c79a3ffa8` but later removed
per maintainer ask in commit `b94737de7` ("don't add these tests
to the build.yml for now"); see
`2026-05-07-cross-stack-interop-ci-gating.md` for the path to
re-wiring.

**Browser harness location:** `nestsClient/tests/browser-interop/`
(was originally `nestsClient-browser-interop/` at repo root;
moved to mirror `nestsClient/tests/hang-interop/` layout).

**Final scenario coverage:** I1, I2, I3, I4 (stereo), I5
(hot-swap), I7 (Chromium publisher reconnect), I9 (packet loss),
I13 (long broadcast), I14 (WebCodecs warmup × CSD), I15 (ALPN).
See `2026-05-06-cross-stack-interop-test-results.md` for the
full inventory.

Tracks the spec at
`nestsClient/plans/2026-05-06-phase4-browser-harness.md`.

## Where it landed

- New top-level `nestsClient/tests/browser-interop/` workspace:
  - `package.json` pins `@moq/lite@0.2.2`, `@moq/hang@0.2.4`,
    `@moq/watch@0.2.10`, `@moq/publish@0.2.6`, `@playwright/test@1.56.1`.
  - `REV` documents the pinned versions next to the
    `nestsClient/tests/hang-interop/REV`.
  - `src/listen.html` + `src/listen.ts` — Watch path, uses
    `Container.Legacy.Consumer` and WebCodecs `AudioDecoder`
    directly (the published `@moq/hang` 0.2.4 doesn't expose the
    higher-level `Container.Consumer` from upstream HEAD; we wire
    its data path manually).
  - `src/publish.html` + `src/publish.ts` — symmetric publisher
    scaffold for the I4-reverse / I14-decoder-warmup scenarios
    Phase 4.C extension can pick up.
  - `src/server.ts` — bun static + WebSocket back-channel; the
    listener page posts Float32 LE PCM frames as binary messages,
    a textual `done` message flips the server's `done` flag.
  - `tests/harness.spec.ts` — single Playwright spec the Kotlin
    driver invokes per scenario; reads `NESTS_HARNESS_URL`
    + `NESTS_TIMEOUT_MS` from env.
  - `playwright.config.ts` — Chromium with `--enable-quic`,
    `--ignore-certificate-errors`, AutoplayPolicy override.
- `nestsClient/src/jvmTest/.../interop/native/PlaywrightDriver.kt`
  — Kotlin shim that spawns the bun server + `bun x playwright
  test` per test, returns a `HarnessRun(pcmFile, stdout, exit)`.
  Includes a `CertCapturingValidator` that pulls the relay's leaf
  cert during the speaker's QUIC handshake so we can pass its
  SHA-256 to Chromium via `serverCertificateHashes`.
- `nestsClient/src/jvmTest/.../interop/native/BrowserInteropTest.kt`
  — two scenarios:
  - **I1 forward (browser)**: Amethyst Kotlin speaker → Chromium
    `@moq/lite` listener; asserts FFT 440 Hz on the captured tail.
  - **I15 (WT-Protocol round-trip)**: asserts Chromium's
    `Connection.version` starts with `moq-lite-`.
- `nestsClient/build.gradle.kts` — two new tasks:
  - `interopBuildBrowserHarness` (bun install + bun build → dist/),
  - `interopInstallPlaywrightChromium` (skipped if
    `PLAYWRIGHT_BROWSERS_PATH` already points at a chromium build).
  Both gated on `-DnestsBrowserInterop=true` like the hang tier
  is gated on `-DnestsHangInterop=true`.
- `.github/workflows/build.yml` — new `browser-interop` job
  parallel to `hang-interop`, with bun + node_modules + Playwright
  caches.

## Deviations from the spec

1. **Source layout: `@moq/lite` + `@moq/hang` direct, NOT
   `@moq/watch` `Watch.Broadcast`.** The spec called for mirroring
   NostrNests's `transport/moq-transport.ts` `Watch.Broadcast`
   verbatim; in practice `@moq/watch` 0.2.x bakes in a heavy
   reactive `Effect`/`Signal` layer that's unwieldy for a one-shot
   capture page. The lower-level `connection.consume(path) →
   broadcast.subscribe(track) → track.readFrame()` pipeline is
   what the watch decoder uses internally, so this is a
   functionally equivalent path. NostrNests-side regressions in
   `Watch.Broadcast` plumbing aren't in scope of T16.
2. **Cert pinning via `serverCertificateHashes`, not
   `--ignore-certificate-errors`.** Chromium's
   `--ignore-certificate-errors` flag does NOT bypass QUIC cert
   validation — reproduced as `net::ERR_QUIC_PROTOCOL_ERROR.
   QUIC_TLS_CERTIFICATE_UNKNOWN`. The spec mentioned
   `--ignore-certificate-errors-spki-list` as a "preferred long-
   term form"; we use `serverCertificateHashes` (Web-API equivalent),
   which works because moq-relay's `--tls-generate` produces a
   14-day ECDSA P-256 cert — exactly what the WebTransport spec
   requires for a serverCertificateHashes pin. The
   `CertCapturingValidator` snags the cert during the speaker's
   QUIC handshake so we don't need a separate fingerprint endpoint.
3. **I1 sample-count assertion loosened.** Hang-tier I1 asserts
   `assertSampleCount(expected = 5 s, tolerance = 0.20)` — the
   browser path can't hit that because Chromium cold-launch +
   Playwright runner setup eats 3–10 s before the page starts
   capturing, by which time the `framesPerGroup = 5`
   per-subscriber forward cliff means only the latest cached
   group is replayable. The browser I1 instead asserts ≥ 1 s of
   decoded audio + FFT peak at 440 Hz. The FFT peak is the
   load-bearing assertion (catches downmix / channel-swap /
   OpusHead-leak regressions); the sample-count threshold is just
   a sanity floor.
4. **Phase 4.C scenarios I2/I3/I4/I13/I14 deferred.** I2
   late-join collapses into "tail capture" anyway given the
   Chromium boot lag, so it's not adding signal beyond I1. I3
   mute-window has the same visibility issue. I4 needs the
   reverse publisher path wired up end-to-end (a stub publish.ts
   landed but isn't exercised by a Kotlin test yet). I13 long
   broadcast and I14 CSD-skip are runtime-of-test concerns the
   I1 path already exercises implicitly. Tracked as a follow-up
   on a separate plan if/when the gap matters.

## Verification

```bash
./gradlew :nestsClient:jvmTest \
    --tests "com.vitorpamplona.nestsclient.interop.native.BrowserInteropTest" \
    -DnestsHangInterop=true \
    -DnestsBrowserInterop=true
```

Both `amethyst_speaker_to_chromium_listener_static_tone_440` and
`chromium_round_trips_a_moq_lite_session` pass in isolation.

## Follow-ups

- **I4-reverse**: wire `BrowserInteropTest` to drive
  `PlaywrightDriver.openPublishPage` (the Kotlin side already
  exposes the entry point) → Amethyst Kotlin listener decodes;
  assert per-channel FFT peaks. Needs the publish.ts harness
  graduated from scaffold to a fully-working pump (the
  `MediaStreamTrackProcessor` → `AudioEncoder` → `Container.Legacy.
  Producer` chain compiles but isn't yet validated end-to-end).
- **I3 mute-window**: works on the Kotlin speaker side, but the
  short browser tail capture window means the mute-gap deficit
  isn't observable. Would need either a longer broadcast (60 s+)
  or a tighter capture window that brackets the mute schedule
  reliably. Low priority — the hang-tier I3 already validates the
  speaker-side mute behaviour against a parser-correct watcher.
- **I15 strict pin**: when moq-relay 0.10.x ships with both
  `moq-lite-03` and `moq-lite-04` ALPN advertisement, tighten the
  assertion from `startsWith("moq-lite-")` to exact-match
  `moq-lite-03` (or whichever the production stack runs). Right
  now the relay we boot lands `moq-lite-02` over the legacy
  `moql` ALPN.
- **CI cold-cache time**: cold `npx playwright install chromium`
  takes ~60 s on a fresh GitHub runner. The `actions/cache@v4`
  hits keyed on `package.json` should make warm runs near-zero,
  but the first run on a new branch will be slow.