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

Plan: Phase 4 (browser harness) — landed results

Status: 4.A scaffold + 4.B Playwright driver + first Kotlin test green; 4.C ships I15; 4.D ships the CI workflow job. 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

./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.