Browser Runtime

Phase 6 browser runtime boundary for Flow Player.

Current scope:

Worker protocol for init, play, pause, push-chunk, and graceful destroy/destroyed shutdown.
Capability probing for WebCodecs, MSE, WebGL2, WebGPU, OffscreenCanvas, and Worker support.
WebGL2 renderer baseline for hard-decoded VideoFrame and soft-decoded I420 planes.
Runtime metrics helpers for chunk ingest, first frame marking, and decode/upload/render A/B sampling summaries.
WASM playback event bridge for FLV H264/HEVC demux, WebCodecs decode, and WebGL2 render.

The metrics helpers are intentionally small building blocks for browser A/B sampling reports. They do not start automatic browser collection by themselves.

The runtime intentionally has no npm dependencies. Vite is used only as a dev/build dependency for producing the npm-grade package output, while TypeScript declarations are shipped beside the ESM implementation so the Jessibuca-compatible API layer and direct runtime consumers can use this package without taking extra runtime dependencies.

Frontend projects consume @flow-player/browser-runtime as an npm/browser runtime package. The public package surface is the ESM entrypoint, TypeScript declarations, and the module worker script exposed at @flow-player/browser-runtime/worker.

The Rust flow-player-wasm crate is the backend boundary for the WASM build and dist pipeline. Business frontend code should not operate on that crate directly, and the package exports still do not expose a .wasm bundle.

Raw WASM artifact build:

pnpm --filter @flow-player/browser-runtime build:wasm
npm --prefix packages/browser-runtime run build:wasm

This builds flow-player-wasm for wasm32-unknown-unknown without wasm-bindgen, then copies the artifact to target/browser-runtime/flow_player_wasm.wasm. Use -- --out-dir <path> or -- --profile dev|release to override the output directory or profile. If the Rust target is missing, install it with rustup target add wasm32-unknown-unknown.

Deployable dist build:

pnpm --filter @flow-player/browser-runtime build:dist
npm --prefix packages/browser-runtime run build:dist

This creates dist/browser-runtime with browser-ready ESM runtime files, tsc --emitDeclarationOnly declarations generated from src/**/*.ts, bundled delivery docs, manifest, and wasm/flow_player_wasm.wasm. Use -- --wasm-path <path> to package an already-built WASM artifact without running cargo. The dist manifest records sourceCommit and sourceDirty so release jobs can reject dirty source builds.

NPM-grade package build:

pnpm --filter @flow-player/browser-runtime build:package
npm --prefix packages/browser-runtime run build:package

This creates dist/browser-runtime-package, an npm pack-ready package root. Its package exports point at built dist/index.js, generated dist/index.d.ts, dist/worker/player-worker.js, and generated dist/worker/player-worker.d.ts; the WASM artifact is included at wasm/flow_player_wasm.wasm for static deployment, but remains outside package exports. The default release profile minifies the ESM output through Vite. Use -- --profile dev when you need readable output for debugging package path issues. The package build requires Node.js >=24.0.0 because repository scripts are native .ts entrypoints executed directly by Node 24.

Package publish check:

pnpm --filter @flow-player/browser-runtime publish:check
npm --prefix packages/browser-runtime run publish:check

This rebuilds the ESM package and verifies publish metadata, exports, TypeScript declarations, worker entry, WASM artifact, bundled docs, npm pack --dry-run, and a clean source manifest. It does not run npm publish. The check intentionally keeps npm pack/install verification inside verify-package.ts, even when the source workspace is managed by pnpm.

Tooling check:

pnpm --filter @flow-player/browser-runtime check

This runs the current OXC format gate, Oxlint gate, TypeScript tsc --noEmit gate, and declaration-generation check. During the P1 tooling phase, the OXC format gate is intentionally scoped to files that are already OXC-clean and does not format package manifest JSON; wider formatting should be done as a separate zero-behavior formatting slice.

Local browser verification:

npm --prefix packages/browser-runtime run dev:cert
npm --prefix packages/browser-runtime run dev

dev:cert writes the default mkcert certificate pair to /tmp/flow-player-local.pem and /tmp/flow-player-local-key.pem. dev starts the local HTTPS static server and H.264/HEVC playback proxy on https://127.0.0.1:4176; this server is retained for artifact smoke and package-path checks. Real browser playback validation should use the player demo in apps/player-demo/src/App.tsx so playback UI, query params, and runtime observations stay in one frontend.

Smoke check:

pnpm --filter @flow-player/browser-runtime test:smoke
npm --prefix packages/browser-runtime run test:smoke

Benchmark baseline:

npm --prefix packages/browser-runtime run benchmark
npm --silent --prefix packages/browser-runtime run benchmark -- --json --iterations 10 --warmup 2

Reference: