@urun-sh/core 0.2.55 → 0.2.57

package/CHANGELOG.md

@@ -1,6 +1,71 @@
 # Changelog
 
-## Unreleased
+## 0.2.57
+
+- **FIX: `jitterBufferTarget` range guard (0–4000ms).** The W3C
+  `RTCRtpReceiver.jitterBufferTarget` attribute is specified over [0, 4000]ms
+  and an out-of-range assignment THROWS a RangeError. The consume path set the
+  target with no range check, so an out-of-range configured value threw inside
+  `_onConsume` — reached through the un-awaited `_handleMessage`, that throw
+  surfaced only as an UNHANDLED REJECTION while the lane was never
+  `resumeConsumer`'d: a silent dead media lane over a config typo. Out-of-range
+  targets are now refused with the same posture as the existing non-finite
+  guard (a default-visible `*-jitter-buffer-invalid` warning naming the value;
+  the receiver is left alone; media flows), and the signaling `onmessage`
+  dispatch now attaches a rejection handler to `_handleMessage` (same `error`
+  surface as its synchronous parse failures — the fire-and-forget shape is
+  unchanged).
+
+- **Opt-in steady-state session stats** (`sessionStats?: { pollMs? }` on
+  `TransportSessionOptions` AND `AppOptions`, threaded through `App()`; new
+  `Session.onStats(handler)` — optional on the interface, the `onActivation`
+  additive precedent). When enabled, inbound RTP stats are sampled PER MEDIA
+  KIND every `pollMs` (default 2000ms) and emitted as a `SessionStatsSample`
+  on a NEW `stats` transport event: per-kind `InboundStatsSample`s plus
+  **`avSyncMs` = video − audio `estimatedPlayoutTimestamp`** — the first-class
+  measurement of the standing audio-behind-video delay class (liveavatar
+  measured 2.2–2.7s). Off by default: no sampler runs at all unless asked for.
+  Deliberately its OWN timer and event: never the join-probe timer (whose
+  contract is settle-then-disarm; the stats timer is stopped at every teardown
+  site the probe is) and never the diagnostic channel (each diagnostic is a
+  default-visible console line and, with an events reporter wired, an HTTP
+  POST per event). `readInboundSample` no longer gates per-field aggregation
+  to video-only (audio fields were structurally invisible — null forever), and
+  the inbound field set gains `estimatedPlayoutTimestamp`,
+  `jitterBufferTargetDelay`, `jitterBufferMinimumDelay`, `concealedSamples`,
+  `insertedSamplesForDeceleration`. `avSyncMs` is measured WITHIN ONE STREAM:
+  a session can carry several named streams at once, so the sampled lanes are
+  grouped by A/V pair key (the parent name of a `{parent}--audio` /
+  `{parent}--video` derived-leg pair) and the busiest group carrying BOTH
+  kinds is the one measured — differencing two unrelated streams' playout
+  instants would be a fabricated offset that reads like a real measurement.
+  The chosen pair is named on the sample as `stream` (null for unnamed legacy
+  lanes). `estimatedPlayoutTimestamp` aggregates as the LATEST instant across
+  a report's `inbound-rtp` entries rather than a sum (it is an NTP-anchored
+  instant, not a cumulative counter — summing fabricates a timestamp); the
+  other new fields are genuine counters and stay additive. A THROWING `stats`
+  subscriber is routed to the transport `error` surface instead of becoming an
+  unhandled rejection on every sampling tick, and sampling continues.
+
+- **Per-kind playout knob — MECHANISM ONLY** (`videoPlayout?:
+  VideoPlayoutOptions`, additive beside `audioPlayout` at every thread point).
+  `_capAudioJitterBuffer` is generalized to `_capJitterBuffer(consumer, kind)`
+  with per-kind target resolution: audio keeps its 300ms default UNCHANGED;
+  video's default is **UNSET** — no hidden number. Video receivers remain
+  untouched unless `videoPlayout` is explicitly passed ("video renders on
+  arrival" stays the default behavior; formally amending that commitment is a
+  queued owner ruling). CAVEAT, verbatim from the review: under a
+  single-element muxed playout the browser resolves the effective
+  jitter-buffer target as the max() across the element's receivers — a small
+  VIDEO target can RAISE the AUDIO leg's standing delay to match. Defaults
+  await `avSyncMs` measurement. Cap-before-`resumeConsumer` ordering is
+  preserved. Receipts: every capped/unsupported/invalid diagnostic now carries
+  `mediaKind` + `transportId`, and the previously-silent no-RTCRtpReceiver
+  path (node/werift legs) emits a `debug` receipt. Audio diagnostic kind
+  strings (`audio-jitter-buffer-*`) are unchanged — consumers string-match
+  them; video uses the new parallel `video-jitter-buffer-*` family.
+
+## 0.2.53
 
 - **Audio receiver jitter-buffer cap** (`AudioPlayoutOptions`, new export). A
   muxed A/V egress reaches the browser as TWO RTP tracks with independent