@joewinke/jatui 0.12.0 → 0.14.0

package/dist/video/audio/rider.js

@@ -0,0 +1,187 @@
+/**
+ * Loudness matching — the pure half (mos-5lzns.31). Ported from
+ * extension-library `library.js` §Loudness matching (audioLevel / audioTick)
+ * and FEATURES.md §Loudness matching; every number below is the extension's.
+ *
+ * Shape: a gated RMS estimate of the programme's LOUD level drives a slow,
+ * asymmetric gain rider toward a target. The graph (./graph.ts) feeds this
+ * module the analyser's time-domain buffer every AUDIO_TICK_MS and lands the
+ * returned ride on the gain param; nothing here touches WebAudio.
+ *
+ * Not true LUFS — no K-weighting, no channel weighting. The thing being
+ * corrected is "this video is louder than the last one", and RMS answers that
+ * honestly at a fraction of the cost.
+ */
+/** How often the rider reads the meter. fftSize 2048 is ~46ms at 44.1kHz. */
+export const AUDIO_TICK_MS = 200;
+export const AUDIO_FFT_SIZE = 2048;
+/** Where matching aims, dBFS RMS. At −20 an ordinary video is left at ~1.0×. */
+export const AUDIO_TARGET_DEFAULT = -20;
+export const AUDIO_TARGET_MIN = -30;
+export const AUDIO_TARGET_MAX = -12;
+/** Below this RMS a window is silence — it carries no vote about level. */
+export const SILENCE_RMS = 1e-5;
+/**
+ * The gate is the whole difference between working and shouting. A 46ms
+ * window of speech runs ~−15 dB, the pause between sentences ~−40; driving
+ * gain off the instantaneous level climbs through every gap and blares the
+ * next word. So the estimate only listens to material within GATE_DB of what
+ * it already believes the loud level to be (EBU R128's relative-gate idea).
+ */
+export const GATE_DB = 12;
+/** Rise toward a louder reading quickly … */
+export const LOUD_RISE = 0.08;
+/** … and forget a quiet one very slowly (a new video does NOT reset it). */
+export const LOUD_FORGET = 0.01;
+/**
+ * The clamp. 1.35 is a deliberate ceiling, not a round number: measured
+ * across the extension's library, target −20 leaves normal material at 1.0×,
+ * lifts a quiet podcast by the full +2.6 dB and pulls a hot one down 10 dB.
+ * Matching may rescue a quiet mix by a few dB; it may NOT become an amplifier.
+ */
+export const GAIN_MIN = 0.3;
+export const GAIN_MAX = 1.35;
+/**
+ * Asymmetric ride — the opposite way round from night dimming: coming DOWN
+ * off something too loud is quick, going up is slow enough to be inaudible.
+ */
+export const RIDE_DOWN = 0.15;
+export const RIDE_UP = 0.02;
+/** setTargetAtTime constant the ride lands with, so the param smooths between ticks. */
+export const RIDE_TAU = 0.25;
+/**
+ * The limiter — the fast half. High ratio, knee 0, fast attack: it does
+ * nothing until something actually peaks. Off moves the threshold to 0 dBFS
+ * rather than rewiring the graph (rewiring a live graph clicks); the move is
+ * RAMPED (LIMITER_TAU), never a `.value` write.
+ *
+ * Not a straight wire on its own: DynamicsCompressorNode applies automatic
+ * makeup gain (see `compressorMakeupDb`) — ~+1.7 dB at −3 dBFS / 20:1 — so the
+ * graph follows the limiter with a trim GainNode at the inverse. Without the
+ * trim, "limiter on" is a 1.7 dB level jump, which is exactly the kind of
+ * trace a feature must not leave.
+ */
+export const LIMITER = Object.freeze({
+    threshold: -3,
+    knee: 0,
+    ratio: 20,
+    attack: 0.003,
+    release: 0.25
+});
+export const LIMITER_OFF_THRESHOLD = 0;
+/** Ramp constant for limiter threshold/trim moves — under an event, over a click. */
+export const LIMITER_TAU = 0.15;
+/**
+ * Silence watchdog: a routed element whose analyser reads EXACT zeros for this
+ * long while it is playing, audible, its clock advancing AND with positive
+ * evidence that decoded audio is flowing is reported as silent — the
+ * signature of a source that became CORS-tainted after routing (the node
+ * outputs zeros, never noise). Without that evidence (no audio track, or a
+ * browser that can't tell us) it never fires. Exact digital silence in a real
+ * track (a muted-mic screen recording) can still trip it, which is why the
+ * report asks for a notice, never a remount.
+ */
+export const SILENT_AFTER_MS = 4000;
+const finite = (n) => typeof n === 'number' && Number.isFinite(n);
+/**
+ * Short-term RMS of a time-domain buffer, in dBFS. `null` for silence (below
+ * SILENCE_RMS), an empty buffer or junk — never −Infinity, never NaN.
+ */
+export function rmsDb(buf) {
+    if (!buf || !(buf.length > 0))
+        return null;
+    let sum = 0;
+    for (let i = 0; i < buf.length; i++) {
+        const s = buf[i];
+        if (!finite(s))
+            return null;
+        sum += s * s;
+    }
+    const rms = Math.sqrt(sum / buf.length);
+    if (!(rms >= SILENCE_RMS))
+        return null;
+    return 20 * Math.log10(rms);
+}
+/**
+ * One step of the gated loud-level estimate. `loud` null means "no estimate
+ * yet" — the first real reading seeds it. A null/junk `level` (silence) leaves
+ * the estimate exactly where it was.
+ */
+export function gateLoud(loud, level) {
+    if (!finite(level))
+        return finite(loud) ? loud : null;
+    if (!finite(loud))
+        return level;
+    if (level > loud - GATE_DB) {
+        return loud + (level - loud) * (level > loud ? LOUD_RISE : LOUD_FORGET);
+    }
+    return loud;
+}
+/** Clamp a target to the declared range; junk falls back to the default. */
+export function clampTarget(target) {
+    if (!finite(target))
+        return AUDIO_TARGET_DEFAULT;
+    return Math.min(AUDIO_TARGET_MAX, Math.max(AUDIO_TARGET_MIN, target));
+}
+/**
+ * The gain that would put the measured loud level at `target`, clamped to
+ * [GAIN_MIN, GAIN_MAX]. No estimate yet ⇒ 1 (neutral): we never guess.
+ */
+export function wantGain(loud, target) {
+    if (!finite(loud))
+        return 1;
+    const want = Math.pow(10, (clampTarget(target) - loud) / 20);
+    return Math.min(GAIN_MAX, Math.max(GAIN_MIN, want));
+}
+/** One asymmetric step of the ride toward `want`. Junk in ⇒ neutral 1. */
+export function rideStep(ride, want) {
+    const r = finite(ride) ? ride : 1;
+    if (!finite(want))
+        return r;
+    return r + (want - r) * (want < r ? RIDE_DOWN : RIDE_UP);
+}
+/** A ride as dB — for readouts. 1 ⇒ 0 dB; junk ⇒ 0. */
+export function gainDb(ride) {
+    return finite(ride) && ride > 0 ? 20 * Math.log10(ride) : 0;
+}
+/**
+ * DynamicsCompressorNode's automatic makeup gain, dB, for knee 0 — the Web
+ * Audio spec's "makeup gain" step (as Chromium/WebKit/Gecko implement it):
+ * fullRangeGain = the curve's output for a 0 dBFS input, makeup =
+ * (1 / fullRangeGain) ^ 0.6. For knee 0 the curve at 0 dBFS is
+ * threshold + (0 − threshold) / ratio, so the makeup is
+ * 0.6 × (−threshold) × (1 − 1/ratio): +1.71 dB at −3 dBFS / 20:1, 0 at a
+ * 0 dBFS threshold. Junk ⇒ 0.
+ */
+export function compressorMakeupDb(threshold, ratio) {
+    if (!finite(threshold) || !finite(ratio) || ratio < 1 || threshold >= 0)
+        return 0;
+    return 0.6 * -threshold * (1 - 1 / ratio);
+}
+/** The trim gain (linear) that cancels a limiter's makeup at this threshold. */
+export function limiterTrim(threshold) {
+    return Math.pow(10, -compressorMakeupDb(threshold, LIMITER.ratio) / 20);
+}
+/**
+ * Can this element's audio be routed through WebAudio without going SILENT?
+ *
+ * A media response that isn't CORS-clean makes a MediaElementAudioSourceNode
+ * output zeros — and routing is a one-way door, so that is silence with no
+ * way back. A same-origin URL is NOT enough: it may 302 to a signed storage
+ * URL on another origin (MardukOS file routes do exactly that), and without
+ * `crossorigin` the redirected response is opaque. So:
+ *
+ * · 'ok'   — blob:/data: (never leave the page's origin), or the element asked
+ *            for a CORS load (`crossorigin` set — the load is then CORS-clean
+ *            or it fails outright, never silently).
+ * · 'wait' — no source yet; nothing to decide.
+ * · 'cors' — anything else: refuse, play unprocessed.
+ */
+export function routeSafety(mediaUrl, crossorigin) {
+    if (typeof mediaUrl !== 'string' || mediaUrl === '')
+        return 'wait';
+    if (crossorigin === 'anonymous' || crossorigin === 'use-credentials' || crossorigin === '') {
+        return 'ok';
+    }
+    return /^(blob|data):/i.test(mediaUrl.trim()) ? 'ok' : 'cors';
+}

package/dist/video/audio.d.ts

@@ -1,29 +1,40 @@
 /**
- * Audio module — CONTRACT ONLY (mos-5lzns.28). Implemented by mos-5lzns.31
- * ("audio graph — loudness matching, quiet listening, limiter").
+ * Audio module (mos-5lzns.31) — loudness matching, quiet listening, limiter.
+ * Ported from extension-library FEATURES.md §Loudness matching, §Quiet
+ * listening (library.js audioEnsure / audioTick / applyAudioSettings).
  *
- * What lands here (extension-library FEATURES.md §Loudness matching,
- * §Quiet listening), as ADVISORS + an audio graph builder:
+ * Layout:
  *
- * · loudness matching — a gated RMS meter drives a slow gain rider toward a
- *   target (~−20 dB). The gate forgets slowly so a new video doesn't reset
- *   the meter mid-lesson; the correction is measured, not a strength slider.
- * · quiet listening — loudness-compensated tone (two shelves + presence
- *   peak + gentle compressor), amount rising as volume drops, a floor after
- *   dark. Amount 0 rebuilds nothing: splicing a live graph mid-playback
- *   clicks — a constant few ms of silence is the trade.
- * · limiter — threshold −3 dBFS, catching what the slow rider cannot.
+ * · audio/rider.ts — pure, node-testable: short-term RMS in dBFS, the gated
+ *   loud-level estimate (12 dB relative gate, rise 0.08 / forget 0.01), the
+ *   clamped want-gain (0.3–1.35), the asymmetric ride (down 0.15 / up 0.02),
+ *   the limiter constants + `compressorMakeupDb`/`limiterTrim` (the
+ *   compressor's automatic makeup gain, cancelled by a trim node), and
+ *   `routeSafety` (only blob:/data: or a `crossorigin` load may be routed).
+ * · audio/graph.ts — `createAudioSession`, the graph builder + its state
+ *   machine: source → gain → quiet chain (advisors/quiet-listening) →
+ *   limiter → trim → destination, analyser tapping the source. Context
+ *   first, route last: the element is taken only once a feature is on, the
+ *   source is route-safe AND the context is `running`; gestures retry. After
+ *   routing, an unsafe src or bit-exact silence is reported `broken`. A
+ *   construction failure is a permanent `broken` that still plays plain
+ *   audio. Disabled = no trace on the param timeline.
  *
  * Module rules (README): no <video> access, no settings reads, no DOM. The
- * graph builder is the one exception that may touch AudioContext — it takes
- * a MediaElementAudioSourceNode the component creates, never the element.
- * Disabled ⇒ the graph is bypassed entirely: no residual filter, no half
- * ramp, no stale param (cancelScheduledValues before restoring). Off must be
- * indistinguishable from never having run.
+ * graph is the one exception that touches AudioContext — and even it never
+ * sees the element: the component passes a `context()` factory and a
+ * `route(ctx)` closure that calls createMediaElementSource.
+ *
+ * ⚠ CORS: WebAudio outputs SILENCE for a source that isn't CORS-clean — and
+ * a same-origin URL may redirect to one. The host must serve the media with
+ * Access-Control-Allow-Origin and pass `crossorigin="anonymous"` (or use a
+ * blob:/data: src); otherwise the player refuses to route (status 'cors')
+ * and plays the audio unprocessed.
  */
 /**
  * Neutral advisor product — the multiplicative identity every composer and
- * caller must get when audio correction is off or unmeasured. Exported so
- * .31's rate-relevant advisors (if any) share the exact collapse value.
+ * caller must get when audio correction is off or unmeasured.
  */
 export declare const AUDIO_NEUTRAL = 1;
+export * from './audio/rider';
+export * from './audio/graph';

package/dist/video/audio.js

@@ -1,29 +1,40 @@
 /**
- * Audio module — CONTRACT ONLY (mos-5lzns.28). Implemented by mos-5lzns.31
- * ("audio graph — loudness matching, quiet listening, limiter").
+ * Audio module (mos-5lzns.31) — loudness matching, quiet listening, limiter.
+ * Ported from extension-library FEATURES.md §Loudness matching, §Quiet
+ * listening (library.js audioEnsure / audioTick / applyAudioSettings).
  *
- * What lands here (extension-library FEATURES.md §Loudness matching,
- * §Quiet listening), as ADVISORS + an audio graph builder:
+ * Layout:
  *
- * · loudness matching — a gated RMS meter drives a slow gain rider toward a
- *   target (~−20 dB). The gate forgets slowly so a new video doesn't reset
- *   the meter mid-lesson; the correction is measured, not a strength slider.
- * · quiet listening — loudness-compensated tone (two shelves + presence
- *   peak + gentle compressor), amount rising as volume drops, a floor after
- *   dark. Amount 0 rebuilds nothing: splicing a live graph mid-playback
- *   clicks — a constant few ms of silence is the trade.
- * · limiter — threshold −3 dBFS, catching what the slow rider cannot.
+ * · audio/rider.ts — pure, node-testable: short-term RMS in dBFS, the gated
+ *   loud-level estimate (12 dB relative gate, rise 0.08 / forget 0.01), the
+ *   clamped want-gain (0.3–1.35), the asymmetric ride (down 0.15 / up 0.02),
+ *   the limiter constants + `compressorMakeupDb`/`limiterTrim` (the
+ *   compressor's automatic makeup gain, cancelled by a trim node), and
+ *   `routeSafety` (only blob:/data: or a `crossorigin` load may be routed).
+ * · audio/graph.ts — `createAudioSession`, the graph builder + its state
+ *   machine: source → gain → quiet chain (advisors/quiet-listening) →
+ *   limiter → trim → destination, analyser tapping the source. Context
+ *   first, route last: the element is taken only once a feature is on, the
+ *   source is route-safe AND the context is `running`; gestures retry. After
+ *   routing, an unsafe src or bit-exact silence is reported `broken`. A
+ *   construction failure is a permanent `broken` that still plays plain
+ *   audio. Disabled = no trace on the param timeline.
  *
  * Module rules (README): no <video> access, no settings reads, no DOM. The
- * graph builder is the one exception that may touch AudioContext — it takes
- * a MediaElementAudioSourceNode the component creates, never the element.
- * Disabled ⇒ the graph is bypassed entirely: no residual filter, no half
- * ramp, no stale param (cancelScheduledValues before restoring). Off must be
- * indistinguishable from never having run.
+ * graph is the one exception that touches AudioContext — and even it never
+ * sees the element: the component passes a `context()` factory and a
+ * `route(ctx)` closure that calls createMediaElementSource.
+ *
+ * ⚠ CORS: WebAudio outputs SILENCE for a source that isn't CORS-clean — and
+ * a same-origin URL may redirect to one. The host must serve the media with
+ * Access-Control-Allow-Origin and pass `crossorigin="anonymous"` (or use a
+ * blob:/data: src); otherwise the player refuses to route (status 'cors')
+ * and plays the audio unprocessed.
  */
 /**
  * Neutral advisor product — the multiplicative identity every composer and
- * caller must get when audio correction is off or unmeasured. Exported so
- * .31's rate-relevant advisors (if any) share the exact collapse value.
+ * caller must get when audio correction is off or unmeasured.
  */
 export const AUDIO_NEUTRAL = 1;
+export * from './audio/rider';
+export * from './audio/graph';

package/dist/video/rate/ads.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Skip ad reads (mos-5lzns.32).
+ *
+ * Ad spans come from two places, merged: the host's `adSpans` prop (MOS fills
+ * it from its enrichment pass) and any speaker turn flagged `ad: true` — the
+ * band already paints those as not-a-person, so a player that paints an ad
+ * and then plays it through with skipping on would contradict itself.
+ *
+ * THE ONE RULE: only PLAYBACK that runs into an ad is skipped. A seek that
+ * lands inside one is a person asking to watch it, and is honoured. The
+ * component forgets its previous sample on every `seeking` event; this module
+ * additionally refuses any step larger than `maxStep` media-seconds, so even
+ * a seek that raced the event can't be mistaken for crossing the start.
+ *
+ * Pure: no DOM, no <video>, no settings reads (src/lib/video/README.md).
+ */
+import type { VideoSpeakerTurn } from '../types';
+/** A host-detected ad read, `[startSec, endSec)`. */
+export interface VideoAdSpan {
+    startSec: number;
+    endSec: number;
+}
+/** Sorted, merged, finite `[start, end)` pairs. Touching/overlapping spans become one. */
+export declare function normalizeAdSpans(spans: readonly VideoAdSpan[] | null | undefined, turns?: readonly VideoSpeakerTurn[] | null): [number, number][];
+/**
+ * Where to jump, or null. Skips when playback moved forward from `prev`
+ * (outside, before the span) to `now` (inside it) in one step of at most
+ * `maxStep` seconds. `prev === null` means "no trustworthy previous sample"
+ * (just seeked, just started, new source) and never skips.
+ */
+export declare function adSkipTarget(prev: number | null, now: number, spans: readonly [number, number][], maxStep: number): {
+    from: number;
+    to: number;
+} | null;
+/** Wall-clock tick → the largest media step that still counts as "playing through". */
+export declare function adMaxStep(elapsedMs: number, rate: number): number;

package/dist/video/rate/ads.js

@@ -0,0 +1,59 @@
+/** Sorted, merged, finite `[start, end)` pairs. Touching/overlapping spans become one. */
+export function normalizeAdSpans(spans, turns) {
+    const raw = [];
+    const push = (a, b) => {
+        if (typeof a !== 'number' || typeof b !== 'number')
+            return;
+        if (!Number.isFinite(a) || !Number.isFinite(b) || b <= a)
+            return;
+        raw.push([Math.max(0, a), b]);
+    };
+    if (Array.isArray(spans))
+        for (const s of spans)
+            if (s)
+                push(s.startSec, s.endSec);
+    if (Array.isArray(turns))
+        for (const t of turns)
+            if (t && t.ad)
+                push(t.startSec, t.endSec);
+    if (!raw.length)
+        return raw;
+    raw.sort((x, y) => x[0] - y[0]);
+    const out = [[raw[0][0], raw[0][1]]];
+    for (let i = 1; i < raw.length; i++) {
+        const last = out[out.length - 1];
+        const [a, b] = raw[i];
+        if (a <= last[1])
+            last[1] = Math.max(last[1], b);
+        else
+            out.push([a, b]);
+    }
+    return out;
+}
+/**
+ * Where to jump, or null. Skips when playback moved forward from `prev`
+ * (outside, before the span) to `now` (inside it) in one step of at most
+ * `maxStep` seconds. `prev === null` means "no trustworthy previous sample"
+ * (just seeked, just started, new source) and never skips.
+ */
+export function adSkipTarget(prev, now, spans, maxStep) {
+    if (prev == null || !Number.isFinite(prev) || !Number.isFinite(now))
+        return null;
+    if (now <= prev || now - prev > maxStep)
+        return null;
+    for (const [a, b] of spans) {
+        if (a > now)
+            break;
+        if (now < b && prev < a)
+            return { from: a, to: b };
+    }
+    return null;
+}
+/** Wall-clock tick → the largest media step that still counts as "playing through". */
+export function adMaxStep(elapsedMs, rate) {
+    const ms = Number.isFinite(elapsedMs) && elapsedMs > 0 ? elapsedMs : 0;
+    const r = Number.isFinite(rate) && rate > 0 ? rate : 1;
+    // 1.5× slack for timer jitter, plus a floor so a background-throttled tab
+    // (setInterval clamped to ≥1s) still recognises its own playback.
+    return (ms / 1000) * r * 1.5 + 0.5;
+}

package/dist/video/rate/compose.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Playback-rate arbitration for VideoPlayer (mos-5lzns.28 internal split;
+ * moved under rate/ by mos-5lzns.32, which fills the advisors).
+ *
+ * THE RATE COMPOSER CONTRACT (extension-library FEATURES.md — "The rate
+ * composer") — this is the one non-obvious rule, stated up front because it
+ * looks like a bug from the outside:
+ *
+ * Three features want `playbackRate`, and NONE of them writes it:
+ *   · you        — the speed keys (−/=/Backspace, alt+wheel)
+ *   · speaker    — "this person talks fast"        (mos-5lzns.32 fills)
+ *   · silence    — "nothing is being said here"    (mos-5lzns.32 fills)
+ *
+ * They contribute to a product:  rate = base × speaker × silence
+ *
+ * `base` is the only one a human chose, and therefore the only one the UI
+ * reports. The speed readout must keep saying `1×` while a gap is being taken
+ * at 2.2×, or the label becomes a strobe.
+ *
+ *   1. Both advisors collapse to `1` the moment their setting is off or their
+ *      data has not arrived — `1` is the multiplicative identity, so the
+ *      composer runs identically on a video with no transcript, no waveform
+ *      and no speakers. There is no "feature absent" branch anywhere.
+ *   2. `base === 0` is a state, not a level (the frozen-frame end of the
+ *      staircase) — it returns early, before any multiplication, because no
+ *      advisor gets to un-pause the video by multiplying its way out of zero.
+ *   3. Only real changes are written. `playbackRate` is a live audio
+ *      parameter: writing a *slightly* different value is audible as a wobble.
+ *      Hence the 0.001 deadband.
+ *   4. The clamp is [0.0625, 16] — the range HTML media elements actually
+ *      support. A product of three multipliers can leave it; a single one
+ *      cannot.
+ *
+ * The SPEED_STEPS staircase and formatSpeedLabel are ported from the
+ * extension's theater (linear 0.1 steps below 1×, all the way down to 0 —
+ * playbackRate=0 is a genuine frozen frame; above 1× the familiar jumps).
+ */
+/** The speed staircase — one step per press of −/=, Backspace resets to 1. */
+export declare const SPEED_STEPS: number[];
+/**
+ * "A quarter speed" reads faster as "−.75" than "0.25×" — below 1× the label
+ * is the delta, not the multiplier. The 0 step is the frozen-frame end of the
+ * staircase — a state, not a level — and the label says so ("0×"), because a
+ * frozen frame labeled "1×" lies. Garbage degrades to `1×`.
+ */
+export declare function formatSpeedLabel(rate: number): string;
+/**
+ * One step along the staircase. A rate OFF the staircase (1.25 from the
+ * native controls' speed menu, say) steps to its nearest staircase neighbour
+ * in the pressed direction — never back to 1×, which from 1.25 would make
+ * "faster" slower. Past either end there is no further step: the rate holds.
+ * Garbage (NaN, negative) is treated as 1×.
+ */
+export declare function stepRate(current: number, direction: 1 | -1): number;
+/** The clamp the composer applies — the range HTML media elements actually support. */
+export declare const RATE_MIN = 0.0625;
+export declare const RATE_MAX = 16;
+/** Writes only on real change — a slightly-different write is audible as a wobble. */
+export declare const RATE_DEADBAND = 0.001;
+export interface ComposedRate {
+    rate: number;
+    /** False when the deadband swallowed the write (keep the previous rate). */
+    changed: boolean;
+}
+/**
+ * The whole arbitration. `speaker` and `silence` are advisor products in
+ * [0.0625, 16] that COLLAPSE TO 1 when their feature is off or its data has
+ * not arrived (rate/speaker.ts, rate/silence.ts — mos-5lzns.32); with both
+ * at 1 this is exactly `base`.
+ *
+ * `base === 0` returns early: a frozen frame is a state, not a level.
+ */
+export declare function composeRate(base: number, speaker: number, silence: number): ComposedRate;
+/**
+ * Should the component write `next` over the element's `current` rate?
+ * Only on a real change (> RATE_DEADBAND) — a slightly-different write is
+ * audible as a wobble. The one exception is landing EXACTLY on `base`: when
+ * every advisor has collapsed to 1 the applied rate must be the human's rate
+ * to the last bit (doctrine 1 — an off feature leaves no trace), so a residue
+ * inside the deadband is still cleared.
+ */
+export declare function shouldWriteRate(current: number, next: number, base: number): boolean;

package/dist/video/rate/compose.js

@@ -0,0 +1,114 @@
+/**
+ * Playback-rate arbitration for VideoPlayer (mos-5lzns.28 internal split;
+ * moved under rate/ by mos-5lzns.32, which fills the advisors).
+ *
+ * THE RATE COMPOSER CONTRACT (extension-library FEATURES.md — "The rate
+ * composer") — this is the one non-obvious rule, stated up front because it
+ * looks like a bug from the outside:
+ *
+ * Three features want `playbackRate`, and NONE of them writes it:
+ *   · you        — the speed keys (−/=/Backspace, alt+wheel)
+ *   · speaker    — "this person talks fast"        (mos-5lzns.32 fills)
+ *   · silence    — "nothing is being said here"    (mos-5lzns.32 fills)
+ *
+ * They contribute to a product:  rate = base × speaker × silence
+ *
+ * `base` is the only one a human chose, and therefore the only one the UI
+ * reports. The speed readout must keep saying `1×` while a gap is being taken
+ * at 2.2×, or the label becomes a strobe.
+ *
+ *   1. Both advisors collapse to `1` the moment their setting is off or their
+ *      data has not arrived — `1` is the multiplicative identity, so the
+ *      composer runs identically on a video with no transcript, no waveform
+ *      and no speakers. There is no "feature absent" branch anywhere.
+ *   2. `base === 0` is a state, not a level (the frozen-frame end of the
+ *      staircase) — it returns early, before any multiplication, because no
+ *      advisor gets to un-pause the video by multiplying its way out of zero.
+ *   3. Only real changes are written. `playbackRate` is a live audio
+ *      parameter: writing a *slightly* different value is audible as a wobble.
+ *      Hence the 0.001 deadband.
+ *   4. The clamp is [0.0625, 16] — the range HTML media elements actually
+ *      support. A product of three multipliers can leave it; a single one
+ *      cannot.
+ *
+ * The SPEED_STEPS staircase and formatSpeedLabel are ported from the
+ * extension's theater (linear 0.1 steps below 1×, all the way down to 0 —
+ * playbackRate=0 is a genuine frozen frame; above 1× the familiar jumps).
+ */
+/** The speed staircase — one step per press of −/=, Backspace resets to 1. */
+export const SPEED_STEPS = [
+    0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1, 1.1, 1.2, 1.3, 1.4, 1.5, 1.75, 2, 2.5, 5, 10
+];
+/**
+ * "A quarter speed" reads faster as "−.75" than "0.25×" — below 1× the label
+ * is the delta, not the multiplier. The 0 step is the frozen-frame end of the
+ * staircase — a state, not a level — and the label says so ("0×"), because a
+ * frozen frame labeled "1×" lies. Garbage degrades to `1×`.
+ */
+export function formatSpeedLabel(rate) {
+    if (!Number.isFinite(rate) || rate < 0)
+        return '1×';
+    if (rate === 0)
+        return '0×';
+    if (rate < 1) {
+        return (rate - 1).toFixed(2).replace(/\.?0+$/, '').replace(/^-0\./, '-.') + '×';
+    }
+    return rate.toFixed(2).replace(/\.?0+$/, '') + '×';
+}
+/**
+ * One step along the staircase. A rate OFF the staircase (1.25 from the
+ * native controls' speed menu, say) steps to its nearest staircase neighbour
+ * in the pressed direction — never back to 1×, which from 1.25 would make
+ * "faster" slower. Past either end there is no further step: the rate holds.
+ * Garbage (NaN, negative) is treated as 1×.
+ */
+export function stepRate(current, direction) {
+    const cur = Number.isFinite(current) && current >= 0 ? current : 1;
+    const i = SPEED_STEPS.indexOf(cur);
+    if (i !== -1)
+        return SPEED_STEPS[Math.min(SPEED_STEPS.length - 1, Math.max(0, i + direction))];
+    if (direction > 0)
+        return SPEED_STEPS.find((s) => s > cur) ?? cur;
+    for (let j = SPEED_STEPS.length - 1; j >= 0; j--)
+        if (SPEED_STEPS[j] < cur)
+            return SPEED_STEPS[j];
+    return cur;
+}
+/** The clamp the composer applies — the range HTML media elements actually support. */
+export const RATE_MIN = 0.0625;
+export const RATE_MAX = 16;
+/** Writes only on real change — a slightly-different write is audible as a wobble. */
+export const RATE_DEADBAND = 0.001;
+/**
+ * The whole arbitration. `speaker` and `silence` are advisor products in
+ * [0.0625, 16] that COLLAPSE TO 1 when their feature is off or its data has
+ * not arrived (rate/speaker.ts, rate/silence.ts — mos-5lzns.32); with both
+ * at 1 this is exactly `base`.
+ *
+ * `base === 0` returns early: a frozen frame is a state, not a level.
+ */
+export function composeRate(base, speaker, silence) {
+    if (!Number.isFinite(base) || base <= 0) {
+        return { rate: Math.max(0, Number.isFinite(base) ? base : 0), changed: false };
+    }
+    const sp = Number.isFinite(speaker) && speaker > 0 ? speaker : 1;
+    const si = Number.isFinite(silence) && silence > 0 ? silence : 1;
+    const rate = Math.min(RATE_MAX, Math.max(RATE_MIN, base * sp * si));
+    const changed = Math.abs(rate - base) > RATE_DEADBAND;
+    return { rate: changed ? rate : base, changed };
+}
+/**
+ * Should the component write `next` over the element's `current` rate?
+ * Only on a real change (> RATE_DEADBAND) — a slightly-different write is
+ * audible as a wobble. The one exception is landing EXACTLY on `base`: when
+ * every advisor has collapsed to 1 the applied rate must be the human's rate
+ * to the last bit (doctrine 1 — an off feature leaves no trace), so a residue
+ * inside the deadband is still cleared.
+ */
+export function shouldWriteRate(current, next, base) {
+    if (!Number.isFinite(next) || current === next)
+        return false;
+    if (!Number.isFinite(current))
+        return true;
+    return Math.abs(current - next) > RATE_DEADBAND || next === base;
+}

package/dist/video/rate/silence.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Smart speed — the `silence` factor of the rate composer (mos-5lzns.32).
+ *
+ * The measuring is `../advisors/smart-speed` (ported verbatim by .27): hold
+ * 1× through speech, run the gaps between sentences at `boost` (2.2× by
+ * default), found off the waveform envelope the band already draws. This
+ * file adapts the component's `VideoWaveform` prop and collapses to 1 when
+ * the feature is off or the envelope has not arrived.
+ *
+ * Pure: no DOM, no <video>, no settings reads (src/lib/video/README.md).
+ */
+import { type BoostOpts, type SilenceMap } from '../advisors/smart-speed';
+import type { VideoWaveform } from '../types';
+/**
+ * The silence map for a waveform, or null when there is nothing to map (no
+ * peaks, no known duration, or no qualifying gap at all — a map with zero
+ * ranges can never boost, so the caller may as well not hold one).
+ */
+export declare function silenceMapFor(waveform: VideoWaveform | null | undefined, durationSec: number): SilenceMap | null;
+/** The silence factor at time t: `boost` inside a gap, 1 everywhere else. */
+export declare function silenceFactor(t: number, map: SilenceMap | null, opts?: BoostOpts | null): number;
+/**
+ * "Smart speed · about 6 min shorter" — the visible surface for an automatic
+ * correction (doctrine 2). Empty when the saving would round to nothing, so
+ * the caller never flashes a claim it can't back.
+ */
+export declare function smartSpeedLabel(map: SilenceMap | null, opts?: BoostOpts | null): string;