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

Plan: Phase 4 — browser-side cross-stack harness (T16)

Status: ✅ Landed. Browser harness lives at nestsClient/tests/browser-interop/; tests are BrowserInteropTest.kt covering I1, I2, I3, I4 (stereo), I5 (hot-swap), I7 (publisher reconnect), I9 (packet loss), I13 (long broadcast), I14 (WebCodecs warmup × CSD), I15 (ALPN). Companion landed-results doc: 2026-05-06-phase4-browser-harness-results.md.

The spec text below is preserved for archaeology; some pieces shifted during implementation:

• @moq/watch / @moq/publish weren't directly used; the harness uses @moq/lite + @moq/hang Container.Legacy.Consumer/Producer because the published @moq/hang 0.2.4 didn't expose the high-level Container.Consumer API.
• Cert pinning uses serverCertificateHashes not --ignore-certificate-errors because Chromium's flag does NOT bypass QUIC cert validation.
• Phase 4.C originally deferred I2/I3/I4/I13/I14 — those subsequently landed, see results doc.

Origin: parent plan nestsClient/plans/2026-05-06-cross-stack-interop-test.md, "Phase 4 — Browser harness (1.5 days)".

Branch convention: new branch — don't fold into the cross-stack-test branch. Suggested name feat/nests-browser-interop.

Why a browser path

hang-listen validates the wire format against the canonical Rust kixelated/moq parser. The browser path additionally validates:

• Chromium's QUIC + WebTransport stack (different implementation from quinn / :quic),
• WebCodecs AudioDecoder (different from libopus — different look-ahead, different first-frame handling behaviour, same OpusHead regression risk per T8/T14),
• AudioWorklet rendering timing (200 ms playback buffer + AudioContext clock drift),
• WT-Available-Protocols / WT-Protocol ALPN negotiation over Chromium's WebTransport — completely separate from quinn's TLS-ALPN exchange.

The reference NostrNests web app runs on @moq/watch / @moq/publish — this is the actual production stack the project ships against. A wire-byte round-trip through hang-listen alone doesn't catch a Chromium quirk that breaks real users.

Goal

End-to-end verify:

1. forward — Amethyst Kotlin speaker → headless Chromium listener (@moq/watch), tone recoverable from PCM tap.
2. reverse — headless Chromium publisher (@moq/publish) → Amethyst Kotlin listener, tone recoverable.
3. browser-only scenarios I13 (framesPerGroup=50 long broadcast against Container.Consumer), I14 (WebCodecs warmup × CSD-skip interaction), I15 (WT-Available-Protocols Chromium round-trip).

All scenarios drive the same NativeMoqRelayHarness from Phase 1 — no Docker, no second relay, no fake auth sidecar.

Architecture

                    Test runner (Gradle :nestsClient:jvmTest)
                                    │
            ┌───────────────────────┼─────────────────────────────────┐
            │                       │                                 │
            ▼                       ▼                                 ▼
 ┌──────────────────────┐   ┌──────────────────┐         ┌─────────────────────────────┐
 │ NativeMoqRelayHarness│   │ Kotlin in-proc   │         │ Browser harness             │
 │ (existing — Phase 1) │   │ speaker / listener│        │ nestsClient/tests/browser-interop/│
 │ moq-relay subprocess │   │ via               │         │  - bun static + WS server   │
 │ 127.0.0.1:<rand>     │   │ connectNestsSpeaker        │  - listen.html + listen.ts  │
 │ --auth-public ""     │   │ connectNestsListener       │  - publish.html+publish.ts  │
 │ --tls-generate       │   │                  │         │  - pcm-tap-worklet.ts       │
 └──────────▲───────────┘   └──────────────────┘         │  - Playwright driver         │
            │ WebTransport over UDP                       │  - PCM capture via WS back- │
            │                                             │    channel                   │
            │                                             └─────────────────────────────┘
            └─────────────────────────────────────────────┘

Components

1. nestsClient/tests/browser-interop/ — bun + Playwright workspace

New top-level directory, mirrors the parent plan's specification. Contents:

nestsClient/tests/browser-interop/
├── package.json
├── tsconfig.json
├── bun.lockb                           # pinned via REV file
├── REV                                 # @moq/* npm versions
├── src/
│   ├── listen.html                     # static page driving Watch.Broadcast
│   ├── publish.html                    # static page driving Publish.Broadcast
│   ├── listen.ts                       # imports @moq/watch + @moq/lite + PCM tap
│   ├── publish.ts                      # imports @moq/publish + @moq/lite + Oscillator src
│   ├── pcm-tap-worklet.ts              # AudioWorklet that posts Float32Array on every
│   │                                   #   inputs[0] frame to the main thread
│   └── server.ts                       # bun static server + WebSocket back-channel
└── playwright.config.ts                # Chromium-only; --enable-quic flags

Pin all @moq/* deps to the same versions nostrnests/nests ships in NestsUI-v2/package.json. Document the rev in nestsClient/tests/browser-interop/REV (parallel to nestsClient/tests/hang-interop/REV).

2. listen.ts — browser listener

Mirrors NostrNests' transport/moq-transport.ts Watch.Broadcast configuration verbatim where possible. Reads relay, path, jwt (optional), ws, duration from query params. Sets up an AudioContext, registers pcm-tap-worklet, hooks the worklet into broadcast.audio.root, posts every inputs[0] Float32Array over the WebSocket back-channel as a binary frame. Closes when duration elapses.

3. publish.ts — browser publisher

Reads same params plus freqHz and channels. Builds an OscillatorNode at freqHz connected to a MediaStreamAudioDestinationNode. Passes the resulting MediaStream's audio track into Publish.Broadcast's audio.source. Closes after duration.

4. server.ts — bun static + WebSocket back-channel

Bun HTTP server: serves listen.html, publish.html, and the bundled JS from dist/. Bun WebSocket on a separate path (e.g. /pcm): receives PCM chunks from the harness page and appends them to a file the Gradle test reads. Argv: --port <int> --out-pcm <path>.

5. playwright.config.ts — Chromium with QUIC enabled

import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    launchOptions: {
      args: [
        '--enable-quic',
        '--ignore-certificate-errors',  // self-signed harness cert
        '--enable-features=AutoplayPolicy=NoUserGestureRequired',
        // For tighter cert pinning:
        // '--ignore-certificate-errors-spki-list=<sha256-of-test-cert>',
      ],
    },
  },
});

--ignore-certificate-errors is acceptable for a test-only Chromium instance; preferred form --ignore-certificate-errors-spki-list=<base64-sha256> is documented but optional (cert SPKI is hard to compute from the relay's auto-generated cert without parsing).

6. interopBuildBrowserHarness Gradle task

nestsClient/build.gradle.kts parallel to interopBuildHangSidecars:

val interopBuildBrowserHarness by tasks.registering(Exec::class) {
    description = "bun install && bun build for the browser interop harness"
    group = "interop"
    workingDir = file("nestsClient/tests/browser-interop")
    commandLine("bash", "-c", "bun install && bun build src/listen.ts src/publish.ts src/pcm-tap-worklet.ts --outdir dist --target browser")
    inputs.files(
        fileTree("nestsClient/tests/browser-interop") {
            include("package.json", "bun.lockb", "src/**/*")
        }
    )
    outputs.dir("nestsClient/tests/browser-interop/dist")
}

A second task installs Playwright's Chromium:

val interopInstallPlaywrightChromium by tasks.registering(Exec::class) {
    description = "Install Playwright Chromium + dependencies"
    group = "interop"
    workingDir = file("nestsClient/tests/browser-interop")
    commandLine("bash", "-c", "npx playwright install --with-deps chromium")
    onlyIf {
        // Skip if Chromium binary exists in the cache
        val home = System.getProperty("user.home")
        !file("$home/.cache/ms-playwright/chromium-*").exists() // glob matches if any
    }
}

Forward to test workers:

tasks.withType<Test>().configureEach {
    val isBrowserInterop = System.getProperty("nestsBrowserInterop") == "true"
    if (isBrowserInterop) {
        dependsOn(interopBuildBrowserHarness, interopInstallPlaywrightChromium)
    }
    systemProperty(
        "nestsBrowserInteropHarnessDir",
        file("nestsClient/tests/browser-interop").absolutePath,
    )
    System.getProperty("nestsBrowserInterop")?.let {
        systemProperty("nestsBrowserInterop", it)
    }
}

7. Kotlin-side PlaywrightDriver + BrowserInteropTest

Path: nestsClient/src/jvmTest/.../interop/native/PlaywrightDriver.kt (new) and nestsClient/src/jvmTest/.../interop/native/BrowserInteropTest.kt (new).

PlaywrightDriver shells out to npx playwright test (or uses playwright-java from Maven Central — verify availability at implementation time). Returns when the harness page reports completion via a final WebSocket message or a console log.

object PlaywrightDriver {
    fun openListenPage(
        harnessUrl: String,
        relayUrl: String,
        path: String,
        jwt: String?,
        durationSec: Int,
        wsOutPcm: File,
    ): Process { … }

    fun openPublishPage(
        harnessUrl: String,
        relayUrl: String,
        path: String,
        jwt: String?,
        freqHz: Int,
        channels: Int,
        durationSec: Int,
    ): Process { … }
}

Each invocation:

1. Runs the bun static server on a random port (one per test for isolation; reuses the same :0-bound socket pattern as NativeMoqRelayHarness).
2. Spawns npx playwright test with --config playwright.config.ts and a per-test runner that opens the right URL with the right query params.
3. Plays through durationSec seconds; WS server appends PCM frames to wsOutPcm as native-endian Float32 LE.
4. Returns the Process so the test can kill it cleanly.

8. BrowserInteropTest scenarios

Mirror of HangInteropTest's shape. P0 scenarios per the parent plan:

ID	Direction	Speaker	Listener	Asserts
I1 browser	A→ref	Amethyst Kotlin	Chromium @moq/watch	FFT 440 Hz
I2 browser	both	…	…	late-join still gets tail
I3 browser	A→ref	Amethyst Kotlin	Chromium	mute window
I4 browser	both	Amethyst (stereo)	Chromium	per-channel FFT
I13	A→ref	Amethyst	Chromium	60 s, no eviction-driven silence
I14	A→ref	Amethyst	Chromium	WebCodecs 3-frame warmup × T8 CSD-skip
I15	A→ref	Amethyst	Chromium	WT-Protocol matches moq-lite-03

I1–I4 reuse the existing runSpeakerToHangListen harness infrastructure but swap the listener subprocess from hang-listen to PlaywrightDriver.openListenPage. The harness already exposes relayUrl + relay UDP loopback; no new harness API needed.

Phases

Total: ~1.5 days.

Phase 4.A — bun harness scaffold (~3 hr)

1. bun init in nestsClient/tests/browser-interop/. Pin @moq/lite, @moq/watch, @moq/publish, @moq/hang to the versions nostrnests/nests NestsUI-v2/package.json ships at the time of implementation. Document in REV.
2. Write listen.ts + pcm-tap-worklet.ts + listen.html. Mirror NostrNests' transport/moq-transport.ts Watch.Broadcast configuration verbatim.
3. Write publish.ts + publish.html (sine source via OscillatorNode → MediaStreamAudioDestinationNode).
4. Write server.ts (bun static + WebSocket back-channel, writes PCM to a file on disk).
5. Wire interopBuildBrowserHarness Gradle task.

Verify by running the bun server manually + opening http://localhost:<port>/listen.html in a desktop Chromium with the --enable-quic + --ignore-certificate-errors flags; confirm a manual moq-relay + hang-publish behind it delivers tone.

Phase 4.B — Playwright driver + Kotlin tests (~3 hr)

6. Add Playwright (@playwright/test) to the bun harness's dev deps. Wire interopInstallPlaywrightChromium Gradle task.
7. Write PlaywrightDriver.kt shelling out to npx playwright test (or playwright-java if available). Cert-pin via --ignore-certificate-errors for the test-only Chromium instance.
8. Write BrowserInteropTest.kt with the I1 forward scenario as the smoke test (Amethyst speaker → Chromium listener, FFT 440 Hz on the captured PCM).

Verify green via:

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

Phase 4.C — additional P0 scenarios (~3 hr)

9. I2 (late-join), I3 (mute), I4 (stereo if I4 stereo plan has landed; else skip and unblock when stereo merges).
10. I13 (framesPerGroup=50 long broadcast — interesting because the Chromium path may have a different per-group cliff threshold than hang-listen; this scenario likely NEEDS framesPerGroup=5 like the hang-listen ones).
11. I14 (WebCodecs warmup × CSD-skip): assert that with T8's CODEC_CONFIG filter active, the browser receives a normal decode after the standard 3-frame warmup — no extra warmup penalty.
12. I15 (WT-Available-Protocols round-trip): Playwright's browser.newContext() exposes the response headers; assert WT-Protocol matches moq-lite-03.

Per-scenario commits (one per BrowserInteropTest test method).

Phase 4.D — CI integration (~1 hr)

13. Add browser-interop job to .github/workflows/build.yml parallel to hang-interop. Cache nestsClient/tests/browser-interop/node_modules and ~/.cache/ms-playwright on the bun.lockb hash.
14. Run ./gradlew :nestsClient:jvmTest -DnestsBrowserInterop=true on Linux runners. macOS / Windows would double the matrix cost without catching new defects (Chromium QUIC behaviour is consistent across platforms in the test scenarios we care about).

Risks + mitigations

Risk	Mitigation
Chromium WebTransport rejects self-signed cert	Use --ignore-certificate-errors for test-only Chromium. Long-term, --ignore-certificate-errors-spki-list=<sha256> is preferable but needs SPKI extraction from the relay's auto-generated cert.
WebCodecs AudioDecoder not available in headless Chromium	WebCodecs is in stable Chromium since 94 (2021); Playwright bundles current Chromium. Verify on PR.
AudioWorklet on a headless context — AudioContext.resume() requires user gesture in some Chromium configs	Pass --enable-features=AutoplayPolicy=NoUserGestureRequired (already in playwright.config.ts) AND call AudioContext.resume() explicitly in the harness page before adding the audio source.
@moq/watch API changes between bun.lockb pins	Pin to specific versions matching nostrnests/nests. Bump deliberately.
Bun → Playwright integration weird on CI runners	Fall back to node if bun doesn't ship Playwright runner properly; the harness server doesn't depend on bun-specific APIs.
WS back-channel binary frames vs JSON: Playwright captures only stdout, not WS	Server.ts writes PCM directly to disk; the test reads the file path forwarded from the runner. No WS-from-test path.
Cold cache: 60s+ for npx playwright install --with-deps chromium	Cache ~/.cache/ms-playwright on package.json hash. Document the cold cost in CI docs.

Definition of done

1. nestsClient/tests/browser-interop/ directory complete with bun + Playwright + sources building cleanly via interopBuildBrowserHarness.
2. P0 scenarios green: I1 forward, I2, I3, I13, I14 (and I4 if the stereo plan landed).
3. P1 scenarios green: I15 (WT-Protocol round-trip).
4. CI: browser-interop job green on PRs and main.
5. nestsClient/plans/2026-05-06-phase4-browser-harness-results.md summarising what landed, deviations, and follow-ups.
6. nestsClient/plans/2026-05-06-cross-stack-interop-test-results.md gets a "Phase 4" section appended.
7. The hang-tier scenarios (HangInteropTest) stay green when -DnestsBrowserInterop=true is OFF — no regression.

Out of scope (intentionally)

• iOS Safari WebKit — not on Playwright's main browser list, separate matrix.
• Mobile Chromium variants (Android Chrome, Samsung Internet) — desktop Chromium is what the production stack ships against today.
• Real device microphone in the publisher path — sine via OscillatorNode is enough for wire-format and decoder correctness. Real-microphone parity is a field-test concern.
• moq-lite-04 ALPN bump — the parent plan's out-of-scope, separate task. Pin --client-version moq-lite-03 (matches the existing hang-tier scenarios).

When picking up

This plan is self-contained. The agent should:

1. Read nestsClient/plans/2026-05-06-cross-stack-interop-test.md (parent) and nestsClient/plans/2026-05-06-cross-stack-interop-test-results.md (Phase 1–3 status) for context on the harness.
2. Skim nestsClient/src/jvmTest/.../interop/native/HangInteropTest.kt for the existing scenario shape — BrowserInteropTest reuses runSpeakerToHangListen's harness orchestration pattern.
3. Re-clone kixelated/moq to /tmp/moq for reference: git clone --depth=1 https://github.com/kixelated/moq.git /tmp/moq. Confirm /tmp/moq/js/watch, /tmp/moq/js/publish, /tmp/moq/js/lite, /tmp/moq/js/hang are present (sparse checkout if needed). The browser harness's listen.ts / publish.ts mirror that JS.
4. Verify bun --version ≥ 1.3 and npx playwright --version available on the host. The cargo + Rust toolchain from Phase 1 stays unchanged.
5. Implement Phase 4.A first (scaffolding + manual verification), then 4.B (driver + first Kotlin test). Don't proceed to scenario expansion (4.C) until 4.B is green.
6. Each scenario commits separately. The harness setup (4.A + 4.B) is one logical chunk.