@joewinke/jatui 0.8.5 → 0.9.0

package/dist/video/deepLink.js

@@ -0,0 +1,111 @@
+/**
+ * `?t=` deep-link support for VideoPlayer (mos-5lzns.28).
+ *
+ * extension-library parity: every video there is addressable to the second —
+ * `?play=<file>&t=<sec>` — and "Continue on phone" builds exactly that link.
+ * In jatui the FILE is the host page's job (a route, a modal, a share token);
+ * the player owns the TIMESTAMP: `?t=` on the current URL.
+ *
+ * Opt-in via the `syncUrlTime` prop (default false — a component library must
+ * not rewrite the host page's URL history uninvited). When on:
+ *
+ * · READ — on mount, a `t` param seeds the start position (an explicit
+ *   `startAt` prop still wins: the host knows its own intent).
+ * · WRITE — during playback the URL is kept in step via
+ *   `history.replaceState` (never pushState — a timestamp is a position, not
+ *   a page; Back must mean "previous page", not "10 seconds ago"). Other
+ *   query params are preserved verbatim. Writes are throttled (TIMEUPDATE is
+ *   ~4Hz; rewriting the URL on every tick churns both the history machinery
+ *   and any devtools watching it) and floored to whole seconds — the link's
+ *   promise is "picks up at 1:23", not "1:22.87".
+ *
+ * Format accepts both `?t=90` and `?t=90s` (the extension writes the `s`
+ * suffix, YouTube-style). Garbage degrades to "no time", never a throw.
+ */
+/** Parse a `t` param value → seconds, or null. Accepts `90`, `90s`, `1:30`, `1:02:30`. */
+export function parseTimeParam(raw) {
+    if (raw == null)
+        return null;
+    const s = String(raw).trim().replace(/s$/i, '');
+    if (s === '')
+        return null;
+    // h:mm:ss / m:ss clock form
+    if (s.includes(':')) {
+        const parts = s.split(':');
+        if (parts.length > 3)
+            return null;
+        let total = 0;
+        for (const part of parts) {
+            const n = Number(part);
+            if (!Number.isFinite(n) || n < 0)
+                return null;
+            total = total * 60 + n;
+        }
+        return total;
+    }
+    const n = Number(s);
+    if (!Number.isFinite(n) || n < 0)
+        return null;
+    return n;
+}
+/** Floor to whole seconds — the deep link promises second precision. */
+export function formatTimeParam(sec) {
+    return `${Math.max(0, Math.floor(sec))}s`;
+}
+/** Read the current `?t=` from a URL (or the document location). */
+export function readTimeParam(url = typeof location !== 'undefined' ? location.href : null) {
+    if (!url)
+        return null;
+    try {
+        const u = new URL(String(url), typeof location !== 'undefined' ? location.href : undefined);
+        return parseTimeParam(u.searchParams.get('t'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Rewrite the current URL's `t` param in place, preserving every other
+ * query param. Returns false when there was nothing to change (SSR, no
+ * history API, same second) so the caller can skip the replaceState.
+ */
+export function writeTimeParam(sec, url = typeof location !== 'undefined' ? location.href : null) {
+    if (typeof history === 'undefined' || typeof history.replaceState !== 'function')
+        return false;
+    if (!url)
+        return false;
+    let u;
+    try {
+        u = new URL(String(url), typeof location !== 'undefined' ? location.href : undefined);
+    }
+    catch {
+        return false;
+    }
+    const next = formatTimeParam(sec);
+    if (u.searchParams.get('t') === next)
+        return false;
+    u.searchParams.set('t', next);
+    history.replaceState(history.state, '', u);
+    return true;
+}
+/** Strip the `t` param (e.g. when the host unmounts the player opt-in). */
+export function clearTimeParam(url = typeof location !== 'undefined' ? location.href : null) {
+    if (typeof history === 'undefined' || typeof history.replaceState !== 'function')
+        return false;
+    if (!url)
+        return false;
+    let u;
+    try {
+        u = new URL(String(url), typeof location !== 'undefined' ? location.href : undefined);
+    }
+    catch {
+        return false;
+    }
+    if (!u.searchParams.has('t'))
+        return false;
+    u.searchParams.delete('t');
+    history.replaceState(history.state, '', u);
+    return true;
+}
+/** Throttle for URL writes: at most one replaceState per WRITE_THROTTLE_MS. */
+export const WRITE_THROTTLE_MS = 2000;

package/dist/video/keys.d.ts

@@ -0,0 +1,43 @@
+/**
+ * VideoPlayer keyboard map (mos-5lzns.28) — the single source the keydown
+ * handler and the `?` help overlay both read, so a key that exists is always
+ * documented and a documented key always exists.
+ *
+ * Map parity is with extension-library's theater handler (FEATURES.md):
+ * Space play/pause, ←/→ seek, ↑/↓ volume, M mute, −/= speed, Backspace reset
+ * speed, </> frame step, [/] chapter jumps, B bookmark, T transcript, ?
+ * shortcuts, Home/End. Deliberately NOT ported: F/M (favourite/file-under —
+ * library-app verbs, not player verbs), N (night cycle — no night module
+ * until mos-5lzns.33; add it THERE, with its own row here), `,` (settings —
+ * jatui is prop-driven; a settings module arrives with the features that need
+ * one), `/` (transcript search — the pane has none yet).
+ */
+export interface PlayerKeyRow {
+    /** Keycap label as shown in the help overlay — `/`-separated alternates. */
+    keys: string;
+    description: string;
+    /**
+     * Availability gate: the row is only advertised (and the key only bound)
+     * when the feature's data exists. Undefined ⇒ always active.
+     */
+    when?: 'chapters' | 'bookmarks' | 'transcript';
+}
+/** Order follows the help overlay: transport, seek, volume, speed, structure. */
+export declare const PLAYER_KEYS: PlayerKeyRow[];
+/** Band-local keys (band focused): advertised by the band's aria, not the overlay. */
+export declare const BAND_KEYS: PlayerKeyRow[];
+/** mpv-faithful frame step — pause first; the stepped frame is visible in the video itself. */
+export declare const FRAME_STEP_SEC: number;
+/**
+ * Previous / next chapter boundary relative to the playhead. `]` jumps past a
+ * 0.25s grace so pressing it on a chapter's first frames doesn't stick; `[`
+ * uses a 0.75s grace so it lands on the PREVIOUS chapter rather than snapping
+ * to the current one's start. Returns null when there is nowhere to go.
+ */
+export declare function chapterJump(current: number, chapters: {
+    startSec: number;
+    title: string;
+}[], direction: 1 | -1): {
+    startSec: number;
+    title: string;
+} | null;

package/dist/video/keys.js

@@ -0,0 +1,62 @@
+/**
+ * VideoPlayer keyboard map (mos-5lzns.28) — the single source the keydown
+ * handler and the `?` help overlay both read, so a key that exists is always
+ * documented and a documented key always exists.
+ *
+ * Map parity is with extension-library's theater handler (FEATURES.md):
+ * Space play/pause, ←/→ seek, ↑/↓ volume, M mute, −/= speed, Backspace reset
+ * speed, </> frame step, [/] chapter jumps, B bookmark, T transcript, ?
+ * shortcuts, Home/End. Deliberately NOT ported: F/M (favourite/file-under —
+ * library-app verbs, not player verbs), N (night cycle — no night module
+ * until mos-5lzns.33; add it THERE, with its own row here), `,` (settings —
+ * jatui is prop-driven; a settings module arrives with the features that need
+ * one), `/` (transcript search — the pane has none yet).
+ */
+/** Order follows the help overlay: transport, seek, volume, speed, structure. */
+export const PLAYER_KEYS = [
+    { keys: 'Space / K', description: 'Play / pause' },
+    { keys: '← / →', description: 'Seek ±5s (Shift for ±10s)' },
+    { keys: 'J / L', description: 'Seek ±5s (Shift for ±10s)' },
+    { keys: '↑ / ↓', description: 'Volume ±5%' },
+    { keys: 'M', description: 'Mute / unmute' },
+    { keys: '− / =', description: 'Speed down / up one step' },
+    { keys: 'Backspace', description: 'Reset speed to 1×' },
+    { keys: '< / >', description: 'Frame step (pauses; ~1/30s per press)' },
+    { keys: '[ / ]', description: 'Previous / next chapter', when: 'chapters' },
+    { keys: 'B', description: 'Bookmark at the current time', when: 'bookmarks' },
+    { keys: 'T', description: 'Show / hide the transcript', when: 'transcript' },
+    { keys: 'Home / End', description: 'Jump to start / end' },
+    { keys: '?', description: 'Toggle this help' }
+];
+/** Band-local keys (band focused): advertised by the band's aria, not the overlay. */
+export const BAND_KEYS = [
+    { keys: '← / →', description: 'Seek ±5s (Shift for ±10s)' },
+    { keys: 'Home / End', description: 'Jump to start / end' },
+    { keys: 'Esc', description: 'Reset zoom' }
+];
+/** mpv-faithful frame step — pause first; the stepped frame is visible in the video itself. */
+export const FRAME_STEP_SEC = 1 / 30;
+/**
+ * Previous / next chapter boundary relative to the playhead. `]` jumps past a
+ * 0.25s grace so pressing it on a chapter's first frames doesn't stick; `[`
+ * uses a 0.75s grace so it lands on the PREVIOUS chapter rather than snapping
+ * to the current one's start. Returns null when there is nowhere to go.
+ */
+export function chapterJump(current, chapters, direction) {
+    if (chapters.length === 0)
+        return null;
+    if (direction === 1) {
+        return chapters.find((c) => c.startSec > current + 0.25) ?? null;
+    }
+    let target = 0;
+    let hit = null;
+    for (const c of chapters) {
+        if (c.startSec < current - 0.75) {
+            target = c.startSec;
+            hit = c;
+        }
+        else
+            break;
+    }
+    return hit ?? { startSec: target, title: 'Start' };
+}

package/dist/video/model.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Speaker/model derivation for VideoPlayer (mos-5lzns.28 internal split).
+ *
+ * Pure, DOM-free transforms over the optional intelligence props: the ordered
+ * speaker registry (palette-stable across band, lane, legend and transcript),
+ * the identity→colour map, and talk-time totals. The component binds these
+ * with `$derived`; the band paint reads the results.
+ */
+import type { VideoSpeakerTalkTime, VideoSpeakerTurn, VideoTranscriptSegment } from './types.ts';
+export declare const ALL_KEY = "__all__";
+export declare const UNKNOWN_KEY = "__unknown__";
+/**
+ * Speaker identity palette — the same small distinct oklch set TranscriptPlayer
+ * cycles, so a speaker reads as the same colour in both components.
+ */
+export declare const SPEAKER_PALETTE: string[];
+export type SpeakerLike = {
+    speakerIdentity?: string | null;
+    speakerName?: string | null;
+};
+export declare function speakerKeyOf(s: SpeakerLike): string;
+/**
+ * Ordered speaker registry, built from turns first then transcript, so the
+ * palette index is stable across both panes and the legend.
+ */
+export declare function buildSpeakerIndex(turns: VideoSpeakerTurn[], segments: VideoTranscriptSegment[]): Map<string, {
+    key: string;
+    name: string;
+    hue: number | null;
+}>;
+/**
+ * key → identity colour, resolved ONCE per data change. draw() asks for a
+ * colour per rendered column and reruns on every playhead tick, so this must
+ * never be an indexOf scan at call time.
+ */
+export declare function buildSpeakerColors(speakerIndex: Map<string, {
+    key: string;
+    name: string;
+    hue: number | null;
+}>): Map<string, string>;
+/** Ascending sort of the optional data arrays — the only normalization every consumer agrees on. */
+export declare function sortChapters<T extends {
+    startSec: number;
+}>(chapters: T[]): T[];
+export declare function sortTurns<T extends VideoSpeakerTurn>(turns: T[]): T[];
+export declare function sortSegments<T extends {
+    startSec: number;
+}>(segments: T[]): T[];
+export declare function sortBookmarks<T extends {
+    playbackSec: number;
+}>(bookmarks: T[]): T[];
+/** Does the active solo/mute filter recede this turn's paint? */
+export declare function filterDims(key: string | null, ad: boolean, soloKey: string, mutedKeys: Set<string>): boolean;
+/** Talk-time totals: host-supplied, else derived from turns (then segments). */
+export declare function buildTalkTime(talkTime: VideoSpeakerTalkTime[], turns: VideoSpeakerTurn[], segments: VideoTranscriptSegment[]): (VideoSpeakerTalkTime & {
+    key: string;
+})[];

package/dist/video/model.js

@@ -0,0 +1,109 @@
+export const ALL_KEY = '__all__';
+export const UNKNOWN_KEY = '__unknown__';
+/**
+ * Speaker identity palette — the same small distinct oklch set TranscriptPlayer
+ * cycles, so a speaker reads as the same colour in both components.
+ */
+export const SPEAKER_PALETTE = [
+    'oklch(0.70 0.16 250)', // blue
+    'oklch(0.68 0.18 145)', // green
+    'oklch(0.78 0.16 85)', // amber
+    'oklch(0.68 0.19 25)', // red
+    'oklch(0.68 0.16 300)', // violet
+    'oklch(0.72 0.14 200)' // cyan
+];
+export function speakerKeyOf(s) {
+    return s.speakerIdentity ?? s.speakerName ?? UNKNOWN_KEY;
+}
+/**
+ * Ordered speaker registry, built from turns first then transcript, so the
+ * palette index is stable across both panes and the legend.
+ */
+export function buildSpeakerIndex(turns, segments) {
+    const map = new Map();
+    const add = (identity, name, hue) => {
+        const key = identity ?? name ?? UNKNOWN_KEY;
+        const existing = map.get(key);
+        if (existing) {
+            if (existing.hue == null && hue != null)
+                existing.hue = hue;
+            return;
+        }
+        map.set(key, { key, name: name ?? 'Unknown speaker', hue: hue ?? null });
+    };
+    for (const t of turns) {
+        if (t.ad)
+            continue;
+        add(t.speakerIdentity, t.speakerName, t.hue ?? null);
+    }
+    for (const s of segments)
+        add(s.speakerIdentity, s.speakerName, null);
+    return map;
+}
+/**
+ * key → identity colour, resolved ONCE per data change. draw() asks for a
+ * colour per rendered column and reruns on every playhead tick, so this must
+ * never be an indexOf scan at call time.
+ */
+export function buildSpeakerColors(speakerIndex) {
+    const map = new Map();
+    let i = 0;
+    for (const [key, entry] of speakerIndex) {
+        map.set(key, entry.hue != null
+            ? `oklch(0.72 0.14 ${entry.hue})`
+            : SPEAKER_PALETTE[i % SPEAKER_PALETTE.length]);
+        i++;
+    }
+    return map;
+}
+/** Ascending sort of the optional data arrays — the only normalization every consumer agrees on. */
+export function sortChapters(chapters) {
+    return [...chapters]
+        .filter((c) => c && Number.isFinite(c.startSec) && c.startSec >= 0)
+        .sort((a, b) => a.startSec - b.startSec);
+}
+export function sortTurns(turns) {
+    return [...turns]
+        .filter((t) => t && Number.isFinite(t.startSec) && Number.isFinite(t.endSec) && t.endSec > t.startSec)
+        .sort((a, b) => a.startSec - b.startSec);
+}
+export function sortSegments(segments) {
+    return [...segments]
+        .filter((s) => s && Number.isFinite(s.startSec))
+        .sort((a, b) => a.startSec - b.startSec);
+}
+export function sortBookmarks(bookmarks) {
+    return [...bookmarks]
+        .filter((b) => b && Number.isFinite(b.playbackSec) && b.playbackSec >= 0)
+        .sort((a, b) => a.playbackSec - b.playbackSec);
+}
+/** Does the active solo/mute filter recede this turn's paint? */
+export function filterDims(key, ad, soloKey, mutedKeys) {
+    if (soloKey !== ALL_KEY)
+        return !(key != null && !ad && key === soloKey);
+    return !!(key != null && !ad && mutedKeys.has(key));
+}
+/** Talk-time totals: host-supplied, else derived from turns (then segments). */
+export function buildTalkTime(talkTime, turns, segments) {
+    if (talkTime.length > 0) {
+        return [...talkTime]
+            .map((t) => ({ ...t, key: speakerKeyOf(t) }))
+            .sort((a, b) => b.seconds - a.seconds);
+    }
+    const totals = new Map();
+    const bump = (identity, name, secs) => {
+        const key = identity ?? name ?? UNKNOWN_KEY;
+        const existing = totals.get(key);
+        if (existing)
+            existing.seconds += secs;
+        else
+            totals.set(key, { key, speakerIdentity: identity ?? null, speakerName: name ?? null, seconds: secs });
+    };
+    const source = turns.length > 0 ? turns : segments;
+    for (const s of source) {
+        if ('ad' in s && s.ad)
+            continue;
+        bump(s.speakerIdentity, s.speakerName, Math.max(0, s.endSec - s.startSec));
+    }
+    return [...totals.values()].sort((a, b) => b.seconds - a.seconds);
+}

package/dist/video/night.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Night module — CONTRACT ONLY (mos-5lzns.28). Implemented by mos-5lzns.33
+ * ("night dimming, bias light, predictive dimming, strobe guard").
+ *
+ * What lands here (extension-library FEATURES.md §Night dimming, §Bias light,
+ * §The light track), as ADVISORS + paint helpers:
+ *
+ * · night dimming — every ~900ms while playing, sample the frame's actual
+ *   brightness (downscaled canvas read), drive filter: brightness() toward
+ *   `1 − 0.5·depth·excess`. Attack fast, release slow, so a dark cut inside a
+ *   bright video doesn't flash. `N` cycles auto/on/off — add its row to
+ *   keys.ts PLAYER_KEYS when the reader lands, not before.
+ * · bias light — the frame's own colours, blurred, behind the player
+ *   (radial-gradient cells at z-index −1).
+ * · predictive dimming — the pre-scanned luma track read ~1s ahead so
+ *   dimming starts BEFORE a bright cut; the light ribbon rides the same
+ *   track on whichever axis owns scrubbing (mos-5lzns.30's one-axis).
+ * · strobe guard — hold the level down across detected flash intervals.
+ *
+ * The measuring code is an advisor: it reads no settings, touches no
+ * <video>, and returns safe neutral values on garbage input (CORS-tainted
+ * canvas ⇒ escalate to the caller, never silently guess brightness). The
+ * component decides and applies. Respect prefers-reduced-motion where it
+ * applies: the correction is the feature, the ramp is only how it arrives.
+ */
+export declare const NIGHT_NEUTRAL = 1;

package/dist/video/night.js

@@ -0,0 +1,26 @@
+/**
+ * Night module — CONTRACT ONLY (mos-5lzns.28). Implemented by mos-5lzns.33
+ * ("night dimming, bias light, predictive dimming, strobe guard").
+ *
+ * What lands here (extension-library FEATURES.md §Night dimming, §Bias light,
+ * §The light track), as ADVISORS + paint helpers:
+ *
+ * · night dimming — every ~900ms while playing, sample the frame's actual
+ *   brightness (downscaled canvas read), drive filter: brightness() toward
+ *   `1 − 0.5·depth·excess`. Attack fast, release slow, so a dark cut inside a
+ *   bright video doesn't flash. `N` cycles auto/on/off — add its row to
+ *   keys.ts PLAYER_KEYS when the reader lands, not before.
+ * · bias light — the frame's own colours, blurred, behind the player
+ *   (radial-gradient cells at z-index −1).
+ * · predictive dimming — the pre-scanned luma track read ~1s ahead so
+ *   dimming starts BEFORE a bright cut; the light ribbon rides the same
+ *   track on whichever axis owns scrubbing (mos-5lzns.30's one-axis).
+ * · strobe guard — hold the level down across detected flash intervals.
+ *
+ * The measuring code is an advisor: it reads no settings, touches no
+ * <video>, and returns safe neutral values on garbage input (CORS-tainted
+ * canvas ⇒ escalate to the caller, never silently guess brightness). The
+ * component decides and applies. Respect prefers-reduced-motion where it
+ * applies: the correction is the feature, the ramp is only how it arrives.
+ */
+export const NIGHT_NEUTRAL = 1;

package/dist/video/presence.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Presence module — CONTRACT ONLY (mos-5lzns.28). Implemented by mos-5lzns.34
+ * ("wind-down (Idle Detection API), resume-at-sentence, FLIP open").
+ *
+ * What lands here (extension-library FEATURES.md §Wind-down,
+ * §Resume at a sentence, §Open like an object), as ADVISORS + pure helpers:
+ *
+ * · wind-down — the desktop says nobody is there (Idle Detection API / user
+ *   activity), the player fades picture and sound over ~20s and pauses. The
+ *   fade IS the prompt — cancelling it is how you come back.
+ * · resume-at-sentence — snap a resume point back to the nearest sentence /
+ *   speaker turn / chapter within 15s (CLOSEST wins, not most-specific);
+ *   quote the line, never paraphrase; stand down if the user has taken the
+ *   wheel (>2.5s from the stored point). Runs when the transcript lands, not
+ *   at open.
+ * · FLIP open — the clicked card's rectangle → the player shell, WAAPI, two
+ *   keyframes, transform-origin top-left, poster painted under the video on
+ *   EVERY path (a black rectangle is a bug at any motion setting); no-op
+ *   under prefers-reduced-motion except the poster.
+ *
+ * All three are advisors/mechanics: they read no settings, touch no
+ * <video> outside the callbacks the component passes, and fail toward doing
+ * nothing.
+ */
+export declare const PRESENCE_NEUTRAL = 1;

package/dist/video/presence.js

@@ -0,0 +1,25 @@
+/**
+ * Presence module — CONTRACT ONLY (mos-5lzns.28). Implemented by mos-5lzns.34
+ * ("wind-down (Idle Detection API), resume-at-sentence, FLIP open").
+ *
+ * What lands here (extension-library FEATURES.md §Wind-down,
+ * §Resume at a sentence, §Open like an object), as ADVISORS + pure helpers:
+ *
+ * · wind-down — the desktop says nobody is there (Idle Detection API / user
+ *   activity), the player fades picture and sound over ~20s and pauses. The
+ *   fade IS the prompt — cancelling it is how you come back.
+ * · resume-at-sentence — snap a resume point back to the nearest sentence /
+ *   speaker turn / chapter within 15s (CLOSEST wins, not most-specific);
+ *   quote the line, never paraphrase; stand down if the user has taken the
+ *   wheel (>2.5s from the stored point). Runs when the transcript lands, not
+ *   at open.
+ * · FLIP open — the clicked card's rectangle → the player shell, WAAPI, two
+ *   keyframes, transform-origin top-left, poster painted under the video on
+ *   EVERY path (a black rectangle is a bug at any motion setting); no-op
+ *   under prefers-reduced-motion except the poster.
+ *
+ * All three are advisors/mechanics: they read no settings, touch no
+ * <video> outside the callbacks the component passes, and fail toward doing
+ * nothing.
+ */
+export const PRESENCE_NEUTRAL = 1;

package/dist/video/rate.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Playback-rate arbitration for VideoPlayer (mos-5lzns.28 internal split).
+ *
+ * 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. Unknown current rate snaps to 1 first (a
+ * hand-set rate off the staircase still steps from where the user expects).
+ */
+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 — mos-5lzns.32 fills both; until then they are always 1 and
+ * 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;

package/dist/video/rate.js

@@ -0,0 +1,88 @@
+/**
+ * Playback-rate arbitration for VideoPlayer (mos-5lzns.28 internal split).
+ *
+ * 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. Unknown current rate snaps to 1 first (a
+ * hand-set rate off the staircase still steps from where the user expects).
+ */
+export function stepRate(current, direction) {
+    const i = SPEED_STEPS.indexOf(current);
+    const cur = i === -1 ? SPEED_STEPS.indexOf(1) : i;
+    return SPEED_STEPS[Math.min(SPEED_STEPS.length - 1, Math.max(0, cur + direction))];
+}
+/** 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 — mos-5lzns.32 fills both; until then they are always 1 and
+ * 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 };
+}