@joewinke/jatui 0.13.0 → 0.14.0

package/dist/components/VideoPlayer.svelte

@@ -17,6 +17,8 @@
 	export type { NightMode, NightWindow } from '../video/night/clock';
 	// mos-5lzns.31 — audio graph.
 	export type { AudioState, AudioStatus, AudioBrokenReason } from '../video/audio/graph';
+	// mos-5lzns.32 — rate composer (smart speed, speaker pace, skip ad reads).
+	export type { VideoAdSpan, RateReport } from '../video/rate';
 </script>
 
 <script lang="ts">
@@ -137,7 +139,25 @@
 	import { dragCancel, dragEnd, dragMove, dragStart, type DragState } from '../video/band/drag';
 	import { createBandLayerCache } from '../video/band/memo';
 	import { BAND_KEYS, PLAYER_KEYS, chapterJump, FRAME_STEP_SEC } from '../video/keys';
-	import { composeRate, formatSpeedLabel, stepRate } from '../video/rate';
+	import {
+		adMaxStep,
+		adSkipTarget,
+		adviseRate,
+		advisorsActive,
+		composeRate,
+		formatSpeedLabel,
+		normalizeAdSpans,
+		RATE_TICK_MS,
+		shouldWriteRate,
+		silenceMapFor,
+		smartSpeedLabel,
+		speakerRateMap,
+		stepRate,
+		toRateSegments,
+		toRateTurns,
+		type RateReport,
+		type VideoAdSpan
+	} from '../video/rate';
 	import { readTimeParam, WRITE_THROTTLE_MS, writeTimeParam } from '../video/deepLink';
 	import {
 		biasCells,
@@ -229,6 +249,12 @@
 		limiter = undefined,
 		onAudioState = undefined,
 		onAudioBroken = undefined,
+		smartSpeed = false,
+		speakerPace = false,
+		speakerRates = null,
+		adSpans = null,
+		skipAds = false,
+		onRateChange = undefined,
 		class: className = ''
 	}: {
 		src: string;
@@ -405,6 +431,38 @@
 		onAudioState?: (state: AudioState) => void;
 		/** Entered `broken`: 'build-failed' | 'unsafe-src' | 'silent' (see above). */
 		onAudioBroken?: (reason: AudioBrokenReason) => void;
+		/**
+		 * Rate composer (mos-5lzns.32): `rate = base × speaker × silence`. The
+		 * speed readout only ever reports `base` — the rate a human chose — so it
+		 * keeps saying `1×` while a gap is taken at 2.2×. Every advisor is off by
+		 * default and collapses to 1 until its data arrives: off, the element
+		 * plays at exactly `base`.
+		 *
+		 * Smart speed: run the silences between sentences at 2.2×, found off the
+		 * `waveform` envelope. Speech stays at `base`.
+		 */
+		smartSpeed?: boolean;
+		/**
+		 * Per-speaker pace: level everyone to the median words-per-minute,
+		 * measured from the diarised `transcript` + `speakers`. Ad reads and
+		 * gaps between turns play at `base`.
+		 */
+		speakerPace?: boolean;
+		/**
+		 * Hand-set speaker rates keyed by speaker NAME (the legend's display
+		 * name). They always beat measured ones, and like them apply only while
+		 * `speakerPace` is on — off means off. Range 0.0625–16.
+		 */
+		speakerRates?: Record<string, number> | null;
+		/** Host-detected ad reads. Merged with any `ad: true` speaker turns. */
+		adSpans?: VideoAdSpan[] | null;
+		/**
+		 * Skip ad reads: when playback runs into an ad span it jumps to its end
+		 * (the OSD says so). A seek that lands inside an ad is honoured.
+		 */
+		skipAds?: boolean;
+		/** The composed rate changed (real change only). `base` is what the UI shows. */
+		onRateChange?: (report: RateReport) => void;
 		class?: string;
 	} = $props();
 
@@ -655,25 +713,168 @@
 		if (videoEl) videoEl.currentTime = t;
 	}
 
-	// ── Speed ───────────────────────────────────────────────────────────────
+	// ── Speed + rate composer (video/rate/*, mos-5lzns.32) ──────────────────
+	// rate = base × speaker × silence. `base` is the only rate a human chose
+	// and the only one the OSD reports; the advisors multiply into the APPLIED
+	// rate from their own 120ms loop, which runs only while one of them (or ad
+	// skipping) can act. Off, every factor is 1 and the element plays at
+	// exactly `base` — the contract in video/rate/compose.ts.
+	const rateTurns = $derived(toRateTurns(speakers));
+	const rateSegments = $derived(toRateSegments(transcript));
+	const rateAdvisors = $derived({
+		speakerRates: speakerPace
+			? speakerRateMap({ turns: rateTurns, segments: rateSegments, manual: speakerRates, measure: true })
+			: null,
+		turns: rateTurns,
+		silence: smartSpeed ? silenceMapFor(waveform, effectiveDuration) : null
+	});
+	const adRanges = $derived(skipAds ? normalizeAdSpans(adSpans, speakers) : []);
+	const rateLoopOn = $derived(advisorsActive(rateAdvisors) || adRanges.length > 0);
+	/** Playing in a visible tab — the only time the 120ms loop has anything to do. */
+	let rateRunning = $state(false);
+	// Plain (non-reactive): written and read inside one tick.
+	let rateSpeaker = 1;
+	let rateSilence = 1;
 	/**
-	 * Apply the base rate. No advisors exist yet (mos-5lzns.32 fills the
-	 * speaker/silence ones) — composeRate collapses them to 1, so today this is
-	 * exactly `base`. When they land, the composer multiplies and this keeps
-	 * reporting `base` on the OSD — the contract in video/rate.ts.
+	 * `ratechange` events this component still owes itself: every write that
+	 * changes the value fires exactly one. Anything beyond them is a human (the
+	 * native speed menu) — even one that picks the very value we last wrote.
 	 */
+	let rateSelfWrites = 0;
+	let reportedBase = Number.NaN;
+	let reportedRate = Number.NaN;
+	/** Last playhead sample while playing; null after a seek/pause ⇒ never an ad skip. */
+	let adPrev: number | null = null;
+	let adPrevAt = 0;
+
 	function applyRate() {
 		const v = videoEl;
 		if (!v) return;
-		const { rate } = composeRate(baseRate, 1, 1);
+		const { rate } = composeRate(baseRate, rateSpeaker, rateSilence);
 		// Only real changes are written — playbackRate is a live audio parameter.
-		if (v.playbackRate !== rate) v.playbackRate = rate;
+		if (shouldWriteRate(v.playbackRate, rate, baseRate)) {
+			rateSelfWrites++;
+			v.playbackRate = rate;
+		}
+		if (baseRate !== reportedBase || rate !== reportedRate) {
+			reportedBase = baseRate;
+			reportedRate = rate;
+			onRateChange?.({ base: baseRate, speaker: rateSpeaker, silence: rateSilence, rate });
+		}
 	}
 	function stepSpeed(direction: 1 | -1) {
 		baseRate = stepRate(baseRate, direction);
 		applyRate();
 		flashOsd(formatSpeedLabel(baseRate));
 	}
+	function rateTick() {
+		const v = videoEl;
+		if (!v) return;
+		const t = v.currentTime || 0;
+		if (v.paused || v.seeking || adRanges.length === 0) adPrev = null;
+		else {
+			const now = performance.now();
+			const hop = adSkipTarget(adPrev, t, adRanges, adMaxStep(now - adPrevAt, v.playbackRate));
+			adPrevAt = now;
+			adPrev = t;
+			if (hop) {
+				adPrev = null;
+				seekTo(hop.to);
+				flashOsd(`Skipped ad · ${formatDuration(hop.to - hop.from)}`);
+				return;
+			}
+		}
+		const a = adviseRate(baseRate, t, rateAdvisors);
+		rateSpeaker = a.speaker;
+		rateSilence = a.silence;
+		applyRate();
+	}
+	$effect(() => {
+		const v = videoEl;
+		if (!v) return;
+		rateSelfWrites = 0;
+		const syncRunning = () => {
+			const on = !v.paused && !v.ended && !document.hidden;
+			if (rateRunning !== on) rateRunning = on;
+		};
+		const onSeeking = () => (adPrev = null);
+		// A paused scrub re-advises once, so the frame you land on already
+		// carries its rate when play resumes (the loop itself is stopped).
+		const onSeeked = () => {
+			if (rateLoopOn && !rateRunning) rateTick();
+		};
+		// A rate this component didn't write came from a human (the native
+		// controls' speed menu): it becomes the new base, so the advisors keep
+		// multiplying on top of it instead of fighting it.
+		const onNativeRate = () => {
+			if (rateSelfWrites > 0) {
+				rateSelfWrites--;
+				return;
+			}
+			const r = v.playbackRate;
+			if (!Number.isFinite(r) || r < 0) return;
+			baseRate = r;
+			applyRate();
+		};
+		syncRunning();
+		for (const ev of ['play', 'pause', 'ended']) v.addEventListener(ev, syncRunning);
+		document.addEventListener('visibilitychange', syncRunning);
+		v.addEventListener('seeking', onSeeking);
+		v.addEventListener('seeked', onSeeked);
+		v.addEventListener('ratechange', onNativeRate);
+		return () => {
+			for (const ev of ['play', 'pause', 'ended']) v.removeEventListener(ev, syncRunning);
+			document.removeEventListener('visibilitychange', syncRunning);
+			v.removeEventListener('seeking', onSeeking);
+			v.removeEventListener('seeked', onSeeked);
+			v.removeEventListener('ratechange', onNativeRate);
+		};
+	});
+	// Armed: advise once now (so the first frame after play is already right),
+	// and off leaves no trace — every factor back to 1, the element to base.
+	$effect(() => {
+		if (!videoEl || !rateLoopOn) return;
+		untrack(rateTick);
+		return () => {
+			untrack(() => {
+				rateSpeaker = 1;
+				rateSilence = 1;
+				adPrev = null;
+				applyRate();
+			});
+		};
+	});
+	// The 120ms loop runs only while armed AND playing in a visible tab —
+	// paused, ended or hidden, there is no rate to steer.
+	$effect(() => {
+		if (!videoEl || !rateLoopOn || !rateRunning) return;
+		const id = setInterval(rateTick, RATE_TICK_MS);
+		untrack(rateTick);
+		return () => {
+			clearInterval(id);
+			adPrev = null;
+		};
+	});
+	// Nothing acts without something the user can see: an advisor announces
+	// itself once on the OSD when it arms (and again only after it disarms).
+	let rateAnnounced = { silence: false, speaker: false };
+	$effect(() => {
+		const { silence, speakerRates: table } = rateAdvisors;
+		const levelled = table ? Object.values(table).filter((r) => r !== 1).length : 0;
+		untrack(() => {
+			if (!silence) rateAnnounced.silence = false;
+			else if (!rateAnnounced.silence) {
+				rateAnnounced.silence = true;
+				const label = smartSpeedLabel(silence);
+				if (label) flashOsd(label);
+			}
+			if (!levelled) rateAnnounced.speaker = false;
+			else if (!rateAnnounced.speaker) {
+				rateAnnounced.speaker = true;
+				flashOsd(`Speaker pace · ${levelled} adjusted`);
+			}
+		});
+	});
 
 	// ── Audio (video/audio/*) ───────────────────────────────────────────────
 	// The session owns the graph and its one-way door; this block only hands

package/dist/components/VideoPlayer.svelte.d.ts

@@ -4,10 +4,12 @@ export type { VideoLumaTrack } from '../video/band/luma';
 export type { VideoMarker } from '../video/band/markers';
 export type { NightMode, NightWindow } from '../video/night/clock';
 export type { AudioState, AudioStatus, AudioBrokenReason } from '../video/audio/graph';
+export type { VideoAdSpan, RateReport } from '../video/rate';
 import type { VideoBookmark, VideoChapter, VideoSpeakerTalkTime, VideoSpeakerTurn, VideoTranscriptSegment, VideoWaveform } from '../video/types';
 import { type BandState } from '../video/band/axis';
 import { type VideoLumaTrack } from '../video/band/luma';
 import { type VideoMarker } from '../video/band/markers';
+import { type RateReport, type VideoAdSpan } from '../video/rate';
 import { type NightMode, type NightWindow } from '../video/night/clock';
 import { type AudioBrokenReason, type AudioState } from '../video/audio';
 type $$ComponentProps = {
@@ -180,6 +182,38 @@ type $$ComponentProps = {
     onAudioState?: (state: AudioState) => void;
     /** Entered `broken`: 'build-failed' | 'unsafe-src' | 'silent' (see above). */
     onAudioBroken?: (reason: AudioBrokenReason) => void;
+    /**
+     * Rate composer (mos-5lzns.32): `rate = base × speaker × silence`. The
+     * speed readout only ever reports `base` — the rate a human chose — so it
+     * keeps saying `1×` while a gap is taken at 2.2×. Every advisor is off by
+     * default and collapses to 1 until its data arrives: off, the element
+     * plays at exactly `base`.
+     *
+     * Smart speed: run the silences between sentences at 2.2×, found off the
+     * `waveform` envelope. Speech stays at `base`.
+     */
+    smartSpeed?: boolean;
+    /**
+     * Per-speaker pace: level everyone to the median words-per-minute,
+     * measured from the diarised `transcript` + `speakers`. Ad reads and
+     * gaps between turns play at `base`.
+     */
+    speakerPace?: boolean;
+    /**
+     * Hand-set speaker rates keyed by speaker NAME (the legend's display
+     * name). They always beat measured ones, and like them apply only while
+     * `speakerPace` is on — off means off. Range 0.0625–16.
+     */
+    speakerRates?: Record<string, number> | null;
+    /** Host-detected ad reads. Merged with any `ad: true` speaker turns. */
+    adSpans?: VideoAdSpan[] | null;
+    /**
+     * Skip ad reads: when playback runs into an ad span it jumps to its end
+     * (the OSD says so). A seek that lands inside an ad is honoured.
+     */
+    skipAds?: boolean;
+    /** The composed rate changed (real change only). `base` is what the UI shows. */
+    onRateChange?: (report: RateReport) => void;
     class?: string;
 };
 declare const VideoPlayer: import("svelte").Component<$$ComponentProps, {

package/dist/index.d.ts

@@ -12,7 +12,8 @@ export type { ChapterBlock } from './components/replay/ChapterTimeline.svelte';
 export { default as TranscriptPlayer } from './components/TranscriptPlayer.svelte';
 export type { TranscriptSegment, TranscriptBookmark, TranscriptChapter, TranscriptSpeakerTalkTime, } from './components/TranscriptPlayer.svelte';
 export { default as VideoPlayer } from './components/VideoPlayer.svelte';
-export type { VideoChapter, VideoSpeakerTurn, VideoTranscriptSegment, VideoBookmark, VideoWaveform, VideoSpeakerTalkTime, VideoLumaTrack, VideoMarker, BandState, BandAxis, NightMode, NightWindow, AudioState, AudioStatus, AudioBrokenReason, } from './components/VideoPlayer.svelte';
+export type { VideoChapter, VideoSpeakerTurn, VideoTranscriptSegment, VideoBookmark, VideoWaveform, VideoSpeakerTalkTime, VideoLumaTrack, VideoMarker, BandState, BandAxis, NightMode, NightWindow, AudioState, AudioStatus, AudioBrokenReason, VideoAdSpan, RateReport, } from './components/VideoPlayer.svelte';
+export { speakerRateMap, toRateTurns, toRateSegments } from './video/rate';
 export { buildSilenceMap, boostAt, estimateSaving, type SilenceMap, type SilenceWave, type SilenceOpts, type BoostOpts } from './video/advisors/smart-speed';
 export { speakerPace, suggestRates, rateAt, describeRates, type SpeakerPace, type SpeakerPaceRow, type RateMap, type RateTurn, type RateSegment, type SuggestOpts } from './video/advisors/speaker-rate';
 export { snapResume, resumeLabel, type ResumePoint, type ResumeReason, type ResumeCtx, type ResumeOpts } from './video/advisors/resume-point';

package/dist/index.js

@@ -13,6 +13,10 @@ export { default as TranscriptPlayer } from './components/TranscriptPlayer.svelt
 // optional so a bare mp4 still gets the full playback UX. TranscriptPlayer
 // stays exported unchanged — meetings already depends on it.
 export { default as VideoPlayer } from './components/VideoPlayer.svelte';
+// Rate composer (mos-5lzns.32): the same name → rate table the player applies
+// under `speakerPace` (manual beats measured), for a host drawing its own
+// per-speaker speed UI.
+export { speakerRateMap, toRateTurns, toRateSegments } from './video/rate';
 // Pure advisors (mos-5lzns.27): the extension-library self-test modules,
 // ported verbatim. They measure and advise; the player's feature tasks
 // (.31 audio / .32 rate / .34 presence) consume them. qrCanvas is the one

package/dist/video/README.md

@@ -17,7 +17,7 @@ props + callback surfaces.
 | `band.ts` | .28 (done) — extended by **.30** | The timeline band: zoom window (`BandWindow`, `zoomAt`, `followPlayhead`), hit tests (`segmentAt`, `chapterAt`, `biasToSegmentStart`, `nearestBookmark`), and `paintBand` (canvas). .30 adds one-axis arbitration + the light ribbon; its state lives HERE. |
 | `band/` | **.30** (done) | `window.ts` — the zoom-window math (moved out of band.ts, re-exported there; shared by every band layer without an import cycle). `axis.ts` — one-axis four-state arbitration (`resolveAxis`, `BandState`, the churn-guarded microtask `createBandReporter`), `playheadX` (the one "where you are" mapping — ≤0.2px agreement) and `overviewBracket`. `luma.ts` — the light track (`VideoLumaTrack`, the sidecar verbatim) → ribbon (`v² × 0.55`, max-per-interval). `markers.ts` — `VideoMarker` comments (clustered dots) + like heat. |
 | `keys.ts` | .28 (done) | The keyboard map — `PLAYER_KEYS` (the `?` overlay renders it), `chapterJump`, `FRAME_STEP_SEC`. Every key that exists is in the map; a key not in the map doesn't exist. |
-| `rate.ts` | .28 (done) — filled by **.32** | The rate composer contract (`composeRate`, deadband, clamp), the `SPEED_STEPS` staircase, `formatSpeedLabel`. .32 adds the speaker-pace and silence-map advisors — they never write `playbackRate`; they advise. |
+| `rate.ts` + `rate/` | .28 contract — **.32** (done) | `rate.ts` is the barrel. `compose.ts` — the contract (`composeRate`, clamp [0.0625, 16], `shouldWriteRate`'s 0.001 deadband with an exact return to base), the `SPEED_STEPS` staircase, `formatSpeedLabel`. `speaker.ts` — props → `advisors/speaker-rate`; manual rates keyed by NAME always beat measured. `silence.ts` — waveform → `advisors/smart-speed` map + boost + the OSD saving claim. `ads.ts` — `adSpans` ∪ `ad: true` turns; skip only when PLAYBACK runs into an ad, never when a seek lands in one. `tick.ts` — the component's own 120ms loop's one-tick decision. None of them write `playbackRate`; they advise. |
 | `deepLink.ts` | .28 (done) | `?t=` parse/format/read/write (replaceState, throttled, other params preserved). |
 | `settings.ts` | shared — knobs added by .30–.34 | `coerce` (never throws, never junk) + `VIDEO_SETTINGS` registry. A knob lands WITH its reader. |
 | `audio.ts` + `audio/` | **.31** (done) | `audio.ts` is the barrel. `rider.ts` — pure: RMS dBFS (silence → null), the 12 dB relative-gated loud estimate (rise 0.08 / forget 0.01), want-gain clamped 0.3–1.35, the asymmetric ride (down 0.15 / up 0.02), limiter constants + `compressorMakeupDb`/`limiterTrim` (DynamicsCompressor's automatic makeup, cancelled by a trim node), `routeSafety` (only blob:/data: or a `crossorigin` load — a same-origin URL may redirect cross-origin and route to SILENCE). `graph.ts` — `createAudioSession`: source → gain → quiet chain → limiter → trim → destination, analyser on the source. Context first, route last: the element is taken only when a feature is on, the source is route-safe and `ctx.state === 'running'` (gestures resume + retry; never navigator.userActivation). After routing it watches: an unsafe src or bit-exact zeros while audibly playing ⇒ `broken` (`unsafe-src` / `silent`) via `onBroken`. A construction throw is a permanent `build-failed` (context closed if the element wasn't taken; kept with source → destination if it was). Level off cancels before it sets; limiter moves are ramped. The element never enters the module — the component passes a `route` closure. |
@@ -27,7 +27,7 @@ props + callback surfaces.
 
 Sub-task map: **.30** scrubbing/one-axis/ribbon/markers → `band.ts` (+ its own
 paint layers); **.31** audio graph → `audio.ts`; **.32** rate composer →
-`rate.ts` advisors; **.33** night → `night.ts`; **.34** presence/wind-down →
+`rate.ts` + `rate/`; **.33** night → `night.ts`; **.34** presence/wind-down →
 `presence.ts`. **.27** (landed) ports the advisors themselves — .31's chain
 builder and `amountFor` live in `advisors/quiet-listening`, .32's two advisor
 modules in `advisors/smart-speed` + `advisors/speaker-rate`, .34's snapping in

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);
+}

package/dist/video/rate.d.ts

@@ -1,69 +1,26 @@
 /**
- * Playback-rate arbitration for VideoPlayer (mos-5lzns.28 internal split).
+ * Rate module (mos-5lzns.32) — the rate composer and its advisors: smart
+ * speed, per-speaker pace, skip ad reads. Ported from extension-library
+ * FEATURES.md §The rate composer.
  *
- * 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:
+ *   rate = base × speaker × silence        (clamp [0.0625, 16], 0.001 deadband)
  *
- * 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)
+ * `base` is the only factor a human chose and the only one the UI reports.
  *
- * They contribute to a product:  rate = base × speaker × silence
+ * Layout (every file pure and node-testable — `npm run test:unit`):
  *
- * `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.
+ * · rate/compose.ts — the contract: SPEED_STEPS staircase, formatSpeedLabel,
+ *   composeRate (base 0 is a state, advisors collapse to 1, clamp), and
+ *   shouldWriteRate (deadband, except an exact return to base).
+ * · rate/speaker.ts — props → advisors/speaker-rate; manual rates keyed by
+ *   NAME always beat measured ones.
+ * · rate/silence.ts — waveform → advisors/smart-speed map + boost factor.
+ * · rate/ads.ts     — adSpans ∪ `ad: true` turns; skip only when PLAYBACK
+ *   runs into an ad, never when a seek lands in one.
+ * · rate/tick.ts    — the 120ms loop's one-tick decision.
  */
-export declare function composeRate(base: number, speaker: number, silence: number): ComposedRate;
+export * from './rate/compose';
+export * from './rate/speaker';
+export * from './rate/silence';
+export * from './rate/ads';
+export * from './rate/tick';

package/dist/video/rate.js

@@ -1,88 +1,26 @@
 /**
- * Playback-rate arbitration for VideoPlayer (mos-5lzns.28 internal split).
+ * Rate module (mos-5lzns.32) — the rate composer and its advisors: smart
+ * speed, per-speaker pace, skip ad reads. Ported from extension-library
+ * FEATURES.md §The rate composer.
  *
- * 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:
+ *   rate = base × speaker × silence        (clamp [0.0625, 16], 0.001 deadband)
  *
- * 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)
+ * `base` is the only factor a human chose and the only one the UI reports.
  *
- * They contribute to a product:  rate = base × speaker × silence
+ * Layout (every file pure and node-testable — `npm run test:unit`):
  *
- * `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.
+ * · rate/compose.ts — the contract: SPEED_STEPS staircase, formatSpeedLabel,
+ *   composeRate (base 0 is a state, advisors collapse to 1, clamp), and
+ *   shouldWriteRate (deadband, except an exact return to base).
+ * · rate/speaker.ts — props → advisors/speaker-rate; manual rates keyed by
+ *   NAME always beat measured ones.
+ * · rate/silence.ts — waveform → advisors/smart-speed map + boost factor.
+ * · rate/ads.ts     — adSpans ∪ `ad: true` turns; skip only when PLAYBACK
+ *   runs into an ad, never when a seek lands in one.
+ * · rate/tick.ts    — the 120ms loop's one-tick decision.
  */
-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 };
-}
+export * from './rate/compose';
+export * from './rate/speaker';
+export * from './rate/silence';
+export * from './rate/ads';
+export * from './rate/tick';

package/dist/video/settings.js

@@ -40,7 +40,14 @@ export const VIDEO_SETTINGS = [
     { id: 'audio.target', type: 'range', default: -20, min: -30, max: -12, step: 2, owner: 'mos-5lzns.31', wired: true },
     { id: 'audio.quiet', type: 'bool', default: true, owner: 'mos-5lzns.31', wired: true },
     { id: 'audio.limiter', type: 'bool', default: true, owner: 'mos-5lzns.31', wired: true },
-    // { id: 'player.speakerRate', type: 'bool', default: false, owner: 'mos-5lzns.32' },
+    // Read by VideoPlayer's `smartSpeed` / `speakerPace` (+ `speakerRates`) /
+    // `skipAds` (+ `adSpans`) props → video/rate/* (silenceMapFor + silenceFactor,
+    // speakerRateMap + speakerFactor, normalizeAdSpans + adSkipTarget), composed
+    // by rate/compose.ts composeRate. All default off: an automatic rate change
+    // is the host's opt-in.
+    { id: 'player.smartSpeed', type: 'bool', default: false, owner: 'mos-5lzns.32', wired: true },
+    { id: 'player.speakerRate', type: 'bool', default: false, owner: 'mos-5lzns.32', wired: true },
+    { id: 'player.skipAds', type: 'bool', default: false, owner: 'mos-5lzns.32', wired: true },
     // Read by VideoPlayer's `night` / `nightDepth` / `biasLight` / `predictive` /
     // `strobeGuard` props → video/night/* (clock.nightArmed, levels.nightLevels,
     // meter.biasCells, track.lumaAhead / inFlash / composeNight). Unlike the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joewinke/jatui",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "private": false,
   "description": "Shared Svelte 5 component library for JAT projects",
   "type": "module",