fix(spf): pin @caprid/moq-media 0.1.0 and address #75 review

Merged
MM
25d ago
+26-25

Refs #75

Summary

Follow-ups to #75, which merged before its review comments were addressed. The main fix is size: #75's @caprid/moq-media 0.1.1 bump grew the /moq entry from 31.6 kB to 102.6 kB brotli. That growth is a libopus WebAssembly module the player had already turned off. Pinning 0.1.0 brings the entry back to 32.9 kB.

Changes

  • Pin @caprid/moq-media to exactly 0.1.0.
    • 0.1.1 statically imports opus-decoder-wasm.js, 152 kB minified of base64 for packet-loss concealment. Brotli can't compress it, and sideEffects: false can't shake it out, because audio-player.js references it.
    • #75 already passed lossConcealment: false, because that decoder is single-stream and would turn multistream Opus into noise. So we shipped the bytes and never ran them.
    • Diffing the two versions shows 0.1.1's only code change is that concealment path, so 0.1.0 is functionally identical.
    • The pin is exact because ^0.1.0 resolves to 0.1.1. The lossConcealment option and its test go away with it, since 0.1.0 has no such option.
    • moq-media 0.1.0 depends on @caprid/moq-core 0.1.0, so the install now carries that version beside our 0.1.1. No moq-media module imports moq-core, so it never reaches the bundle.
  • Sandbox loopback relay, from cubic's comments:
    • The page text said draft-20.
    • The FIN comment cited §6.4.2.3 as if a FIN were a cancellation, which §6.4.2.2 rules out. It now says the loopback ends the subscription on either, and why that's harmless with this player.
    • The vi64 note now covers the 9-byte form.

Bundle size (@videojs/spf/moq, esbuild minify + brotli, same as the CI report)

minifiedbrotli
before #75 (local network/moqt, moq-media 0.1.0)—31.56 kB
after #75 (moq-core 0.1.1, moq-media 0.1.1)269.4 kB102.55 kB
this PR (moq-core 0.1.1, moq-media 0.1.0)114.2 kB32.92 kB

Review comments on #75 not acted on

  • engines: node >=24 vs the root >=22.19.0 (cubic, P2). This mismatch was already accepted in #72 for @caprid/moq-media, and moq-core adds the same constraint. Left as is.
  • Delete .agents/plans/moq-transport-20-migration.md and moq-engine-implementation.md (cubic, P3). These are deliberately kept on the MoQ integration branches. Left as is.
  • Add 9-byte vi64 encoding to the loopback (cubic, P3). Not needed: the decoder already reads the 9-byte form, and the encoder's 8-byte form holds 56 bits, which covers every integer a JS number represents exactly (2^53). The comment is corrected instead.

Testing

  • pnpm -F @videojs/spf test: 2305 tests pass, with no type errors.
  • pnpm build:packages, pnpm typecheck and pnpm lint all pass.
  • codex review --base mmcc/moq found no issues.
  • Live, relay.mux.global, moq-media 0.1.0. A synthetic VP8 and Opus broadcast, published with @caprid/moq-core, played through createMoqEngine. Both connections negotiated moqt-22. Over 20 s: 590 video frames decoded with 0 dropped, 0 audio underruns, and the audio clock advanced 14915 ms over 15025 ms of wall time.

🤖 Generated with Claude Code

https://claude.ai/code/session_01DaH4ieYHRP2Agar6P9KSCB


Summary by cubic

Fixes the /moq bundle size by pinning @caprid/moq-media to exactly 0.1.0 and corrects the sandbox loopback relay notes per #75's review.

  • moq-media 0.1.1 statically imports a base64 libopus WebAssembly module for packet-loss concealment, growing the /moq entry from 31.6 kB to 102.6 kB brotli. #75 already disabled concealment (the decoder is single-stream and would decode a multistream Opus track as noise), and 0.1.1's only code change is that path, so 0.1.0 is functionally identical at a third of the size. The pin is exact because ^0.1.0 resolves to 0.1.1; the now-absent lossConcealment option and its test are removed. moq-media 0.1.0 depends on moq-core 0.1.0, so both versions get installed, but no moq-media module imports moq-core, so the spare copy never reaches the bundle.
  • The relay page now says draft-22 instead of draft-20, and the FIN comment cites §6.4.2.2 rather than describing a FIN as a cancellation.
  • The loopback varint encoder now rejects non-safe integers with a RangeError instead of mis-encoding them, since some doubles larger than 2^53 (e.g. 2^56) fit in 8 bytes but would encode wrongly; the vi64 comment covers the 9-byte form and why encoding stops at 8.