@joewinke/jatui 0.13.0 → 0.15.0

package/dist/video/presence.js

@@ -1,25 +1,29 @@
 /**
- * Presence module — CONTRACT ONLY (mos-5lzns.28). Implemented by mos-5lzns.34
- * ("wind-down (Idle Detection API), resume-at-sentence, FLIP open").
+ * Presence (mos-5lzns.34) — the barrel. Three behaviours about whether you
+ * are there and where you were, each an OPTIONAL VideoPlayer prop that is
+ * inert when absent (extension-library FEATURES.md §Wind-down, §Resume at a
+ * sentence, §Open like an object):
  *
- * What lands here (extension-library FEATURES.md §Wind-down,
- * §Resume at a sentence, §Open like an object), as ADVISORS + pure helpers:
+ * · `presence/winddown.ts` — pure: the begin decision, fade levels, hint.
+ *   The desktop says nobody is there → picture and sound fade over 20s and
+ *   the video pauses. The fade IS the prompt; any input cancels it.
+ * · `presence/idle.ts` — the desktop signal: Chromium's Idle Detection API,
+ *   feature-detected, never prompting unless the host opted in (and then
+ *   only from a gesture). Elsewhere the player falls back to page presence,
+ *   reported as `source: 'page'` so the host can label it.
+ * · `presence/resume.ts` — resume-at-sentence glue around .27's
+ *   `advisors/resume-point` (the snapping is NOT duplicated here): the
+ *   host-supplied store (localStorage default), the data mapping, and the
+ *   two integration rules — snap when the boundaries land, stand down once
+ *   the user has taken the wheel.
+ * · `presence/flip.ts` — FLIP open/close over WAAPI with the poster painted
+ *   on every path; a no-op under prefers-reduced-motion except the poster.
  *
- * · 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.
+ * Advisors and mechanics: they read no settings and touch no <video>; the
+ * component passes knobs in and applies what comes back, and every one of
+ * them fails toward doing nothing.
  */
-export const PRESENCE_NEUTRAL = 1;
+export { WIND_DOWN_FADE_MS, WIND_DOWN_DEPTH, WIND_DOWN_AFTER_DEFAULT, WIND_DOWN_AFTER_MIN, WIND_DOWN_AFTER_MAX, WIND_DOWN_PROBE_MS, windDownAfterMs, shouldBeginWindDown, desktopPresent, windDownProgress, windDownLevels, windDownHint } from './presence/winddown';
+export { IDLE_THRESHOLD_MIN_MS, idleDetectionSupported, idleDetectionPermission, requestIdleDetection, startDesktopWatch, toDesktopSignal } from './presence/idle';
+export { RESUME_WHEEL_SEC, RESUME_MAX_BACK, RESUME_SAVE_MS, RESUME_FLOOR_SEC, RESUME_TAIL_SEC, localResumeStore, coerceResumeSec, resumeToSave, toResumeCtx, hasBoundaries, planResumeSnap } from './presence/resume';
+export { FLIP_EASE, FLIP_OPEN_MS, FLIP_CLOSE_MS, FLIP_FADE_WITH_POSTER, FLIP_FADE_BARE, FLIP_POSTER_CLASS, flipOpen, flipClose, clearPoster, posterBackground, rectOf, onScreen, flipGeometry, awayFrame, homeFrame } from './presence/flip';

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;

package/dist/video/rate/silence.js

@@ -0,0 +1,48 @@
+/**
+ * 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 { boostAt, buildSilenceMap, estimateSaving } from '../advisors/smart-speed';
+/**
+ * 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 function silenceMapFor(waveform, durationSec) {
+    if (!waveform || !waveform.peaks || !waveform.peaks.length)
+        return null;
+    const d = Number.isFinite(waveform.durationSec) && waveform.durationSec > 0
+        ? waveform.durationSec
+        : durationSec;
+    if (!(Number.isFinite(d) && d > 0))
+        return null;
+    const map = buildSilenceMap({ duration: d, peaks: waveform.peaks });
+    return map.ranges.length ? map : null;
+}
+/** The silence factor at time t: `boost` inside a gap, 1 everywhere else. */
+export function silenceFactor(t, map, opts) {
+    if (!map)
+        return 1;
+    const b = boostAt(t, map, opts ?? null);
+    return Number.isFinite(b) && b >= 1 ? b : 1;
+}
+/**
+ * "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 function smartSpeedLabel(map, opts) {
+    const saved = map ? estimateSaving(map, opts ?? null) : 0;
+    if (!(saved >= 1))
+        return '';
+    if (saved < 60)
+        return `Smart speed · ${Math.round(saved)}s shorter`;
+    return `Smart speed · ~${Math.round(saved / 60)} min shorter`;
+}

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

@@ -0,0 +1,54 @@
+/**
+ * Per-speaker pace — the `speaker` factor of the rate composer (mos-5lzns.32).
+ *
+ * The measuring is `../advisors/speaker-rate` (ported verbatim by .27); this
+ * file is the adapter that feeds it the component's props and decides which
+ * rate wins for a name:
+ *
+ *   · MANUAL rates are keyed by speaker NAME (the display name a human sees
+ *     in the legend, not a diarisation label) and ALWAYS beat measured ones.
+ *     A person who set "Darren 1.3×" meant it; a measurement that disagrees
+ *     is the thing that is wrong.
+ *   · MEASURED rates come from `suggestRates(speakerPace(...))` — words per
+ *     minute off the diarised transcript, levelled to the median pace — and
+ *     fill only the names nobody set by hand.
+ *
+ * The advisor collapses to 1 whenever it has nothing to say: feature off, no
+ * turns, a gap between turns, an ad read, or a name with no rate. `1` is the
+ * composer's identity, so there is no "feature absent" branch anywhere.
+ *
+ * Pure: no DOM, no <video>, no settings reads (src/lib/video/README.md).
+ */
+import { type RateMap, type RateSegment, type RateTurn, type SuggestOpts } from '../advisors/speaker-rate';
+import type { VideoSpeakerTurn, VideoTranscriptSegment } from '../types';
+/**
+ * The name a rate is keyed by — the display name when there is one, else the
+ * identity. Deliberately the same precedence for turns and segments, so a
+ * measured row and a manual entry for the same person share a key.
+ */
+export declare function speakerNameOf(s: {
+    speakerName?: string | null;
+    speakerIdentity?: string | null;
+}): string | null;
+/** Component turns → the advisor's shape. Ad reads keep their flag (never a person). */
+export declare function toRateTurns(turns: readonly VideoSpeakerTurn[] | null | undefined): RateTurn[];
+/** Component transcript → the advisor's shape. */
+export declare function toRateSegments(segments: readonly VideoTranscriptSegment[] | null | undefined): RateSegment[];
+export interface SpeakerRateInput {
+    turns: RateTurn[];
+    segments: RateSegment[];
+    /** Hand-set rates by NAME. Always win. */
+    manual?: Record<string, number> | null;
+    /** Measure the rest from the transcript (false ⇒ manual only). */
+    measure?: boolean;
+    opts?: SuggestOpts | null;
+}
+/**
+ * name → rate. Measured first (if asked), then every valid manual entry laid
+ * over it — so manual beats measured by construction, not by a comparison.
+ * Null-prototype for the same reason the advisor's maps are: a speaker named
+ * "__proto__" is a key, not a prototype write.
+ */
+export declare function speakerRateMap(input: SpeakerRateInput): RateMap;
+/** The speaker factor at time t. 1 when nobody (or an ad) is talking, or no rate is known. */
+export declare function speakerFactor(t: number, turns: RateTurn[], rates: RateMap | null): number;

package/dist/video/rate/speaker.js

@@ -0,0 +1,94 @@
+/**
+ * Per-speaker pace — the `speaker` factor of the rate composer (mos-5lzns.32).
+ *
+ * The measuring is `../advisors/speaker-rate` (ported verbatim by .27); this
+ * file is the adapter that feeds it the component's props and decides which
+ * rate wins for a name:
+ *
+ *   · MANUAL rates are keyed by speaker NAME (the display name a human sees
+ *     in the legend, not a diarisation label) and ALWAYS beat measured ones.
+ *     A person who set "Darren 1.3×" meant it; a measurement that disagrees
+ *     is the thing that is wrong.
+ *   · MEASURED rates come from `suggestRates(speakerPace(...))` — words per
+ *     minute off the diarised transcript, levelled to the median pace — and
+ *     fill only the names nobody set by hand.
+ *
+ * The advisor collapses to 1 whenever it has nothing to say: feature off, no
+ * turns, a gap between turns, an ad read, or a name with no rate. `1` is the
+ * composer's identity, so there is no "feature absent" branch anywhere.
+ *
+ * Pure: no DOM, no <video>, no settings reads (src/lib/video/README.md).
+ */
+import { rateAt, speakerPace, suggestRates } from '../advisors/speaker-rate';
+import { RATE_MAX, RATE_MIN } from './compose';
+/**
+ * The name a rate is keyed by — the display name when there is one, else the
+ * identity. Deliberately the same precedence for turns and segments, so a
+ * measured row and a manual entry for the same person share a key.
+ */
+export function speakerNameOf(s) {
+    const n = (s.speakerName ?? '').trim() || (s.speakerIdentity ?? '').trim();
+    return n || null;
+}
+/** Component turns → the advisor's shape. Ad reads keep their flag (never a person). */
+export function toRateTurns(turns) {
+    if (!Array.isArray(turns))
+        return [];
+    const out = [];
+    for (const t of turns) {
+        if (!t || typeof t !== 'object')
+            continue;
+        out.push({ start: t.startSec, end: t.endSec, name: t.ad ? null : speakerNameOf(t), ad: !!t.ad });
+    }
+    return out;
+}
+/** Component transcript → the advisor's shape. */
+export function toRateSegments(segments) {
+    if (!Array.isArray(segments))
+        return [];
+    const out = [];
+    for (const s of segments) {
+        if (!s || typeof s !== 'object')
+            continue;
+        out.push({ start: s.startSec, end: s.endSec, text: s.text, speaker: speakerNameOf(s) });
+    }
+    return out;
+}
+/** A usable multiplier, or null. The composer's clamp range is the only sane one. */
+function rateOrNull(v) {
+    const n = typeof v === 'number' ? v : Number.NaN;
+    return Number.isFinite(n) && n >= RATE_MIN && n <= RATE_MAX ? n : null;
+}
+/**
+ * name → rate. Measured first (if asked), then every valid manual entry laid
+ * over it — so manual beats measured by construction, not by a comparison.
+ * Null-prototype for the same reason the advisor's maps are: a speaker named
+ * "__proto__" is a key, not a prototype write.
+ */
+export function speakerRateMap(input) {
+    const out = Object.create(null);
+    if (input.measure) {
+        const measured = suggestRates(speakerPace(input.segments, input.turns), input.opts ?? null);
+        for (const [name, r] of Object.entries(measured)) {
+            const v = rateOrNull(r);
+            if (v != null)
+                out[name] = v;
+        }
+    }
+    const manual = input.manual;
+    if (manual && typeof manual === 'object') {
+        for (const [name, r] of Object.entries(manual)) {
+            const key = name.trim();
+            const v = rateOrNull(r);
+            if (key && v != null)
+                out[key] = v;
+        }
+    }
+    return out;
+}
+/** The speaker factor at time t. 1 when nobody (or an ad) is talking, or no rate is known. */
+export function speakerFactor(t, turns, rates) {
+    if (!rates || !turns.length)
+        return 1;
+    return rateOrNull(rateAt(t, turns, rates, 1)) ?? 1;
+}

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

@@ -0,0 +1,38 @@
+/**
+ * The rate loop's one-tick decision (mos-5lzns.32).
+ *
+ * The component runs its OWN 120ms interval for rate — separate from
+ * timeupdate (~4Hz, too coarse: a 0.35s gap would be half over before the
+ * boost arrived) and from night's ~1s meter. Each tick it reads the playhead
+ * and asks this module for the two advisor factors; `composeRate` does the
+ * multiplication and `shouldWriteRate` the deadband. This file only bundles
+ * the per-tick inputs so the component block stays a few lines long.
+ *
+ * Pure: no DOM, no <video>, no settings reads (src/lib/video/README.md).
+ */
+import type { BoostOpts, SilenceMap } from '../advisors/smart-speed';
+import type { RateMap, RateTurn } from '../advisors/speaker-rate';
+/** The rate loop's cadence. */
+export declare const RATE_TICK_MS = 120;
+export interface RateAdvisors {
+    /** null ⇒ the speaker advisor is off (collapses to 1). */
+    speakerRates: RateMap | null;
+    turns: RateTurn[];
+    /** null ⇒ smart speed is off or has no map yet (collapses to 1). */
+    silence: SilenceMap | null;
+    boost?: BoostOpts | null;
+}
+export interface RateAdvice {
+    speaker: number;
+    silence: number;
+    /** base × speaker × silence, clamped — what the element should play at. */
+    rate: number;
+}
+/** What `onRateChange` reports. `base` is the only factor the UI shows. */
+export interface RateReport extends RateAdvice {
+    base: number;
+}
+/** The composed rate at playhead `t` for the human's `base`. */
+export declare function adviseRate(base: number, t: number, a: RateAdvisors): RateAdvice;
+/** Is any advisor able to move the rate? False ⇒ the loop need not run. */
+export declare function advisorsActive(a: RateAdvisors): boolean;

package/dist/video/rate/tick.js

@@ -0,0 +1,15 @@
+import { composeRate } from './compose';
+import { silenceFactor } from './silence';
+import { speakerFactor } from './speaker';
+/** The rate loop's cadence. */
+export const RATE_TICK_MS = 120;
+/** The composed rate at playhead `t` for the human's `base`. */
+export function adviseRate(base, t, a) {
+    const speaker = speakerFactor(t, a.turns, a.speakerRates);
+    const silence = silenceFactor(t, a.silence, a.boost ?? null);
+    return { speaker, silence, rate: composeRate(base, speaker, silence).rate };
+}
+/** Is any advisor able to move the rate? False ⇒ the loop need not run. */
+export function advisorsActive(a) {
+    return !!a.silence || (!!a.speakerRates && a.turns.length > 0 && Object.keys(a.speakerRates).length > 0);
+}