@joewinke/jatui 0.13.0 → 0.15.0

package/dist/components/VideoPlayer.svelte

@@ -17,6 +17,11 @@
 	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';
+	// mos-5lzns.34 — presence (wind-down, resume-at-sentence, FLIP open).
+	export type { WindDownState, WindDownPhase, PresenceSource, VideoResumeStore, FlipSource } from '../video/presence';
+	export type { ResumePoint } from '../video/advisors/resume-point';
 </script>
 
 <script lang="ts">
@@ -137,7 +142,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,
@@ -166,6 +189,36 @@
 		type AudioBrokenReason,
 		type AudioState
 	} from '../video/audio';
+	import {
+		desktopPresent,
+		idleDetectionPermission,
+		localResumeStore,
+		planResumeSnap,
+		posterBackground,
+		requestIdleDetection,
+		resumeToSave,
+		shouldBeginWindDown,
+		startDesktopWatch,
+		toResumeCtx,
+		coerceResumeSec,
+		flipOpen,
+		windDownAfterMs,
+		windDownHint,
+		windDownLevels,
+		windDownProgress,
+		RESUME_SAVE_MS,
+		RESUME_WHEEL_SEC,
+		WIND_DOWN_AFTER_DEFAULT,
+		WIND_DOWN_PROBE_MS,
+		type DesktopSignal,
+		type DesktopWatch,
+		type FlipSource,
+		type PresenceSource,
+		type VideoResumeStore,
+		type WindDownPhase,
+		type WindDownState
+	} from '../video/presence';
+	import type { ResumePoint } from '../video/advisors/resume-point';
 
 	let {
 		src,
@@ -229,6 +282,24 @@
 		limiter = undefined,
 		onAudioState = undefined,
 		onAudioBroken = undefined,
+		smartSpeed = false,
+		speakerPace = false,
+		speakerRates = null,
+		adSpans = null,
+		skipAds = false,
+		onRateChange = undefined,
+		windDown = undefined,
+		windDownAfter = WIND_DOWN_AFTER_DEFAULT,
+		windDownNightOnly = true,
+		idleDetection = false,
+		onWindDown = undefined,
+		resumeKey = null,
+		resumeStore = undefined,
+		resumeSnap = true,
+		onResume = undefined,
+		openFrom = undefined,
+		openPoster = null,
+		openMotion = true,
 		class: className = ''
 	}: {
 		src: string;
@@ -405,6 +476,108 @@
 		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;
+		/**
+		 * Wind-down (mos-5lzns.34): when nobody is there, the picture and sound
+		 * fade over 20s and the video pauses, keeping your place. The fade IS
+		 * the prompt — any input anywhere on the page (or the desktop coming
+		 * back) cancels it and brings everything straight back. Omitted/false ⇒
+		 * the feature does not exist on this player: no listeners, no timers,
+		 * no variables.
+		 *
+		 * The evidence of absence is the DESKTOP when `idleDetection` is on and
+		 * granted (Chromium's Idle Detection API: system-wide idle, and a locked
+		 * screen skips the wait entirely); otherwise it is PAGE presence — no
+		 * input on this page for `windDownAfter` minutes — which is weaker
+		 * evidence (a video legitimately plays for an hour untouched), and is
+		 * reported as `source: 'page'` so the host can label it.
+		 */
+		windDown?: boolean;
+		/** Minutes of absence before the fade begins, 10–90 (default 30). */
+		windDownAfter?: number;
+		/**
+		 * Only wind down while night is armed (default true — falling asleep
+		 * mid-video is a night problem). Uses the `night` mode when present,
+		 * else the local-clock auto window.
+		 */
+		windDownNightOnly?: boolean;
+		/**
+		 * Opt in to the Idle Detection API (Chromium only; permission-gated).
+		 * The player NEVER prompts without this. Already granted ⇒ it starts at
+		 * once; still `prompt` ⇒ the permission is requested on the next click
+		 * or key inside the player (the API needs a user gesture). Better: call
+		 * `requestIdleDetection()` from the click that enables the setting.
+		 * Unsupported or denied ⇒ the page-presence fallback, reported.
+		 */
+		idleDetection?: boolean;
+		/** Phase/source changes: `off` | `watching` | `fading` | `paused`, and `desktop` | `page`. */
+		onWindDown?: (state: WindDownState) => void;
+		/**
+		 * Resume (mos-5lzns.34): present ⇒ the player remembers where this video
+		 * was left under this key and returns there when it opens again. An
+		 * explicit `startAt` or a `?t=` deep link always wins over a stored point.
+		 */
+		resumeKey?: string | null;
+		/**
+		 * Where resume points live — `{ load(key), save(key, sec | null) }`,
+		 * either may be async. Default: this browser's localStorage. jatui never
+		 * calls an API; a host with per-user server state passes its own.
+		 */
+		resumeStore?: VideoResumeStore;
+		/**
+		 * Snap the resume point back to the nearest sentence / speaker turn /
+		 * chapter within 15s once that data lands, and say the line you're
+		 * walking back into (quoted, never paraphrased). Stands down if you've
+		 * moved the playhead yourself. Default on; off ⇒ the raw second.
+		 */
+		resumeSnap?: boolean;
+		/** The player moved the playhead for a resume: `from` the stored second, to `point`. */
+		onResume?: (from: number, point: ResumePoint) => void;
+		/**
+		 * Open like an object (mos-5lzns.34): the clicked card (an element or a
+		 * rect snapshot). Present ⇒ on mount the stage grows out of that
+		 * rectangle (FLIP over WAAPI, 260ms) with `openPoster` painted over the
+		 * video until its first frame decodes. `null` ⇒ the poster only. The
+		 * poster paints on EVERY path — under prefers-reduced-motion, with
+		 * `openMotion` off, or with the card scrolled away — because a black
+		 * rectangle is a bug at any motion setting. Omitted ⇒ nothing changes.
+		 */
+		openFrom?: FlipSource | null;
+		/** The card's (already-loaded) thumbnail. Defaults to `poster`. */
+		openPoster?: string | null;
+		/** Run the motion half of the open (default true). Off ⇒ poster only. */
+		openMotion?: boolean;
 		class?: string;
 	} = $props();
 
@@ -640,11 +813,15 @@
 		zoomTimer = setTimeout(() => (zoomLabelOn = false), 900);
 	}
 
-	function flashOsd(text: string) {
+	function flashOsd(text: string, ms = 900) {
+		if (osdTimer) clearTimeout(osdTimer);
+		if (!text || ms <= 0) {
+			osdOn = false;
+			return;
+		}
 		osd = text;
 		osdOn = true;
-		if (osdTimer) clearTimeout(osdTimer);
-		osdTimer = setTimeout(() => (osdOn = false), 900);
+		osdTimer = setTimeout(() => (osdOn = false), ms);
 	}
 
 	// ── Seeking ─────────────────────────────────────────────────────────────
@@ -655,25 +832,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
@@ -697,7 +1017,10 @@
 				};
 				return {
 					playing: !v.paused && !v.ended,
-					hidden: document.hidden,
+					// A wind-down fade is not the mix getting quieter: hold the
+					// rider's estimate exactly as a hidden tab does, or it rides
+					// the gain back up against the fade.
+					hidden: document.hidden || windPhase === 'fading',
 					audible: !v.muted && v.volume > 0,
 					time: v.currentTime,
 					audioDecoded: typeof m.webkitAudioDecodedByteCount === 'number' ? m.webkitAudioDecodedByteCount : null,
@@ -709,7 +1032,9 @@
 			onBroken: (reason) => onAudioBroken?.(reason)
 		});
 		audio = s;
-		const sync = () => untrack(() => s.apply(audioOpts(v)));
+		// Mid-fade the ~400 volume writes are ours, not the user's: skip them
+		// (the restore at cancel/finish lands after the phase flips, and syncs).
+		const sync = () => untrack(() => windPhase !== 'fading' && s.apply(audioOpts(v)));
 		const gesture = () => s.gesture();
 		const media = ['volumechange', 'loadstart', 'loadedmetadata'];
 		const gestures = ['pointerdown', 'pointerup', 'keydown', 'touchend'];
@@ -730,7 +1055,8 @@
 			target: loudnessTarget,
 			limiter: limiter === true,
 			quiet: quietListening === true,
-			volume: v.volume,
+			// Quiet listening reads the volume the USER chose — not the fade's.
+			volume: windPhase === 'fading' ? windSavedVolume : v.volume,
 			muted: v.muted,
 			night: nightArmedNow
 		};
@@ -1092,6 +1418,380 @@
 		});
 	});
 
+	// ── Presence (video/presence/*, mos-5lzns.34) ───────────────────────────
+	// Three optional behaviours, each absent until its prop says otherwise:
+	// wind-down (`windDown`), resume-at-sentence (`resumeKey`), FLIP open
+	// (`openFrom`). The modules advise; everything that touches the element
+	// happens here.
+
+	// Wind-down. `windProgress` > 0 is the only thing that paints (the
+	// --vp-wind-down variable); 0 leaves no trace. The fade is driven by a
+	// 50ms interval rather than rAF on purpose: a locked screen hides the
+	// document, rAF stops dead in a hidden document, and a fade that freezes
+	// at 10% while the video plays on is the one outcome worse than no fade.
+	// Timers only get throttled (≈1/s) there, so the fade still completes.
+	let windPhase: WindDownPhase = $state('off');
+	let windProgress = $state(0);
+	let windSource: PresenceSource | null = $state(null);
+	let desktopSignal: DesktopSignal | null = null;
+	let desktopWatch: DesktopWatch | null = null;
+	let idleAskPending = false;
+	let lastInputAt = Date.now();
+	let windSavedVolume = 1;
+	// The element the fade is acting on — held so a teardown (unmount, src
+	// swap) can hand the volume back even after bind:this has let go.
+	let windEl: HTMLVideoElement | null = null;
+	let windFadeStart = 0;
+	let windFadeTimer: ReturnType<typeof setInterval> | null = null;
+
+	const windOn = $derived(windDown === true);
+
+	function windArmed(): boolean {
+		if (!windOn) return false;
+		if (!windDownNightOnly) return true;
+		return nightArmed(night ?? 'auto', new Date(), prefersDark, nightWindow);
+	}
+
+	function stopWindFade() {
+		if (windFadeTimer) clearInterval(windFadeTimer);
+		windFadeTimer = null;
+	}
+
+	function windBegin() {
+		const v = videoEl;
+		if (!v || windPhase === 'fading') return;
+		windPhase = 'fading';
+		windEl = v;
+		windSavedVolume = v.volume;
+		windFadeStart = Date.now();
+		const hint = windDownHint('fading', windSource ?? 'page');
+		flashOsd(hint, 6000);
+		announce(hint);
+		stopWindFade();
+		windFadeTimer = setInterval(windStep, 50);
+		windStep();
+	}
+
+	function windStep() {
+		const v = videoEl;
+		if (!v || windPhase !== 'fading') return stopWindFade();
+		const p = windDownProgress(Date.now() - windFadeStart);
+		const lv = windDownLevels(p);
+		v.volume = Math.max(0, Math.min(1, windSavedVolume * lv.volume));
+		windProgress = p;
+		if (p < 1) return;
+		// Pause, hand the volume back for next time, and leave the picture dark
+		// until something happens. The phase flips BEFORE pause() so the pause
+		// handler doesn't read our own pause as the user cancelling.
+		stopWindFade();
+		windPhase = 'paused';
+		v.pause();
+		v.volume = windSavedVolume;
+		const hint = windDownHint('paused', windSource ?? 'page');
+		flashOsd(hint, 8000);
+		announce(hint);
+	}
+
+	/** Anything that says you're here: restore, and (mid-fade) playback simply carries on. */
+	function windCancel() {
+		if (windPhase === 'fading') {
+			stopWindFade();
+			if (windEl) windEl.volume = windSavedVolume;
+			flashOsd('', 0);
+		}
+		windEl = null;
+		if (windPhase === 'fading' || windPhase === 'paused') windPhase = windOn ? 'watching' : 'off';
+		windProgress = 0;
+	}
+
+	function windProbe() {
+		const v = videoEl;
+		if (!windOn || !v) return;
+		const begin = shouldBeginWindDown({
+			armed: windArmed(),
+			playing: !v.paused && !v.ended,
+			active: windPhase === 'fading',
+			source: windSource ?? 'page',
+			desktop: desktopSignal,
+			quietMs: Date.now() - lastInputAt,
+			afterMs: windDownAfterMs(windDownAfter),
+			hidden: typeof document !== 'undefined' && document.hidden
+		});
+		if (begin) windBegin();
+	}
+
+	function onDesktopSignal(sig: DesktopSignal | null) {
+		desktopSignal = sig;
+		if (desktopPresent(sig)) {
+			if (windPhase === 'fading') windCancel();
+		} else if (sig) {
+			windProbe();
+		}
+	}
+
+	function startDesktop() {
+		desktopWatch?.stop();
+		const w = startDesktopWatch({ thresholdMs: windDownAfterMs(windDownAfter), onChange: onDesktopSignal });
+		desktopWatch = w;
+		void w.ready.then((ok) => {
+			if (desktopWatch !== w) return;
+			windSource = ok ? 'desktop' : 'page';
+			if (!ok) desktopSignal = null;
+		});
+	}
+
+	function stopDesktop() {
+		desktopWatch?.stop();
+		desktopWatch = null;
+		desktopSignal = null;
+	}
+
+	// The only path to a permission prompt: the host opted in AND this is a
+	// user gesture inside the player. Called synchronously from the handler,
+	// so the browser still sees the activation.
+	//
+	// Wired to pointerdown, pointerup, click and keydown: which of them grants
+	// activation depends on the input (a touch pointerdown grants none; its
+	// pointerup does). An ask the browser refused for want of activation
+	// ('unsupported' while the permission still reads 'prompt') re-arms for
+	// the next gesture; a 'denied' is an answer and is never re-asked.
+	let idleAskInFlight = false;
+	function maybeAskIdle() {
+		if (!idleAskPending || idleAskInFlight || !windOn || idleDetection !== true) return;
+		idleAskPending = false;
+		idleAskInFlight = true;
+		void requestIdleDetection().then(async (r) => {
+			idleAskInFlight = false;
+			if (!windOn || idleDetection !== true) return;
+			if (r === 'granted') startDesktop();
+			else if (r === 'unsupported' && (await idleDetectionPermission()) === 'prompt') idleAskPending = true;
+		});
+	}
+
+	// Feature lifecycle: on ⇒ page listeners + the probe; off ⇒ every trace
+	// removed (a fade in progress is cancelled and the volume handed back).
+	$effect(() => {
+		if (!windOn) {
+			untrack(() => {
+				windCancel();
+				windPhase = 'off';
+				windSource = null;
+			});
+			return;
+		}
+		untrack(() => {
+			if (windPhase === 'off') windPhase = 'watching';
+			if (windSource === null) windSource = 'page';
+			lastInputAt = Date.now();
+		});
+		// Page input only ever CANCELS a fade (and resets the page-presence
+		// clock); for the desktop source it never postpones the probe.
+		const onInput = () => {
+			lastInputAt = Date.now();
+			if (windPhase === 'fading' || windPhase === 'paused') windCancel();
+		};
+		const evs = ['pointermove', 'pointerdown', 'keydown', 'wheel', 'touchstart'] as const;
+		for (const ev of evs) window.addEventListener(ev, onInput, { passive: true, capture: true });
+		// Coming back to the tab is presence too: the page clock restarts, so a
+		// long stretch spent in another tab can't wind down the moment you return.
+		const onVisible = () => {
+			if (document.visibilityState === 'visible') lastInputAt = Date.now();
+		};
+		document.addEventListener('visibilitychange', onVisible);
+		const probe = setInterval(windProbe, WIND_DOWN_PROBE_MS);
+		return () => {
+			for (const ev of evs) window.removeEventListener(ev, onInput, { capture: true });
+			document.removeEventListener('visibilitychange', onVisible);
+			clearInterval(probe);
+			// Off or unmounted mid-fade: nothing may outlive the feature.
+			windCancel();
+		};
+	});
+
+	// The desktop source: only with the explicit opt-in, never prompting here.
+	$effect(() => {
+		const on = windOn && idleDetection === true;
+		void windDownAfter; // the detector's threshold — restart on change
+		if (!on) return;
+		let cancelled = false;
+		untrack(() => {
+			void idleDetectionPermission().then((perm) => {
+				if (cancelled) return;
+				if (perm === 'granted') startDesktop();
+				else if (perm === 'prompt') idleAskPending = true;
+				else windSource = 'page';
+			});
+		});
+		return () => {
+			cancelled = true;
+			idleAskPending = false;
+			stopDesktop();
+			if (windOn) windSource = 'page';
+		};
+	});
+
+	// A new source is a new video: nothing carries over.
+	$effect(() => {
+		void src;
+		untrack(() => {
+			if (windPhase === 'fading' || windPhase === 'paused') windCancel();
+		});
+	});
+
+	let lastWindReport = '';
+	$effect(() => {
+		const state: WindDownState = { phase: windPhase, source: windOn ? windSource : null };
+		const sig = state.phase + '|' + state.source;
+		if (sig === lastWindReport) return;
+		const first = lastWindReport === '';
+		lastWindReport = sig;
+		// Absent feature: never report (it doesn't exist on this player).
+		if (first && state.phase === 'off') return;
+		untrack(() => onWindDown?.(state));
+	});
+
+	// Resume. The stored point is applied once per key, after metadata, unless
+	// an explicit startAt / ?t= says otherwise or you've already moved; the
+	// snap (advisors/resume-point via presence/resume.ts) waits for the
+	// boundaries to land. Nothing is written until the stored point has been
+	// read AND applied — closing a video before its metadata loads must never
+	// clobber the good point with a 0.
+	const fallbackResumeStore = localResumeStore();
+	const resumeOn = $derived(typeof resumeKey === 'string' && resumeKey.length > 0);
+	const activeResumeStore = $derived(resumeStore ?? fallbackResumeStore);
+	const resumeCtx = $derived(resumeOn ? toResumeCtx(transcript, speakers, chapters) : null);
+	let resumeActiveKey: string | null = null;
+	let resumeLoaded = false;
+	let resumeFrom: number | null = null;
+	let pendingSnap: number | null = null;
+	let resumeLastSave = 0;
+	// The element whose position is being remembered — kept so the final write
+	// on unmount still lands after bind:this has let go of it.
+	let resumeEl: HTMLVideoElement | null = null;
+
+	function applyStoredResume() {
+		const v = videoEl;
+		if (resumeFrom == null || !v) return;
+		if (startAt != null || urlStartAt != null) {
+			resumeFrom = null; // the host's / the link's intent wins
+			return;
+		}
+		if (v.readyState < 1) return; // onLoadedMetadata calls again
+		const at = resumeFrom;
+		resumeFrom = null;
+		if (v.currentTime > RESUME_WHEEL_SEC) return; // you already moved — leave it
+		seekTo(at);
+		onResume?.(at, { at, reason: 'exact', label: '' });
+		if (resumeSnap) {
+			pendingSnap = at;
+			trySnap();
+		}
+	}
+
+	function trySnap() {
+		const v = videoEl;
+		if (pendingSnap == null || !v || !resumeCtx) return;
+		const plan = planResumeSnap(pendingSnap, v.currentTime, resumeCtx);
+		if (plan.kind === 'wait') return;
+		const from = pendingSnap;
+		pendingSnap = null;
+		if (plan.kind !== 'seek') return;
+		seekTo(plan.point.at);
+		if (plan.point.label) {
+			flashOsd(plan.point.label, 5000);
+			announce(plan.point.label);
+		}
+		onResume?.(from, plan.point);
+	}
+
+	function saveResume(force: boolean) {
+		const key = resumeActiveKey;
+		const v = videoEl ?? resumeEl;
+		if (videoEl) resumeEl = videoEl;
+		if (!key || !resumeLoaded || resumeFrom != null || !v || v.readyState < 1) return;
+		const now = Date.now();
+		if (!force && now - resumeLastSave < RESUME_SAVE_MS) return;
+		const sec = resumeToSave(v.currentTime, effectiveDuration);
+		if (sec === undefined) return;
+		resumeLastSave = now;
+		try {
+			void Promise.resolve(activeResumeStore.save(key, sec)).catch(() => {});
+		} catch {
+			/* a host store that throws is a missed save, never a broken player */
+		}
+	}
+
+	$effect(() => {
+		const key = resumeOn ? (resumeKey as string) : null;
+		const store = activeResumeStore;
+		untrack(() => {
+			if (key === resumeActiveKey) return;
+			saveResume(true); // the outgoing key's last position, if still readable
+			resumeActiveKey = key;
+			resumeLoaded = false;
+			resumeFrom = null;
+			pendingSnap = null;
+			resumeLastSave = 0;
+			if (!key) return;
+			let loaded: ReturnType<VideoResumeStore['load']>;
+			try {
+				loaded = store.load(key);
+			} catch {
+				loaded = null;
+			}
+			Promise.resolve(loaded).then(
+				(val) => {
+					if (resumeActiveKey !== key) return;
+					resumeLoaded = true;
+					resumeFrom = coerceResumeSec(val);
+					applyStoredResume();
+				},
+				() => {
+					if (resumeActiveKey === key) resumeLoaded = true;
+				}
+			);
+		});
+	});
+
+	// The snap runs when the boundaries land, not at open.
+	$effect(() => {
+		void resumeCtx;
+		untrack(trySnap);
+	});
+
+	// A hidden tab may never come back — write the position on the way out.
+	$effect(() => {
+		if (!resumeOn) return;
+		const flush = () => saveResume(true);
+		const onVis = () => {
+			if (document.visibilityState === 'hidden') flush();
+		};
+		window.addEventListener('pagehide', flush);
+		document.addEventListener('visibilitychange', onVis);
+		return () => {
+			flush();
+			window.removeEventListener('pagehide', flush);
+			document.removeEventListener('visibilitychange', onVis);
+		};
+	});
+
+	// FLIP open. Read once, at open — this is about how the player ARRIVES.
+	// The poster paints on every path and clears on the first decoded frame.
+	let stageWrapEl: HTMLDivElement | undefined = $state();
+	let openPosterOn = $state(false);
+	let openDone = false;
+	const openPosterImage = $derived(posterBackground(openPoster ?? poster));
+	$effect(() => {
+		const shell = stageWrapEl;
+		if (!shell || openDone) return;
+		untrack(() => {
+			openDone = true;
+			if (openFrom === undefined) return;
+			openPosterOn = !!openPosterImage && !(videoEl && videoEl.readyState >= 2);
+			void flipOpen({ from: openMotion ? openFrom : null, shell, hasPoster: openPosterOn });
+		});
+	});
+
 	// ── Band pointer handlers ───────────────────────────────────────────────
 	function canvasSec(e: MouseEvent): { sec: number; x: number; width: number } | null {
 		const canvas = canvasEl;
@@ -1497,6 +2197,7 @@
 				seekTo(start);
 			}
 		}
+		applyStoredResume();
 	}
 
 	/**
@@ -1527,6 +2228,7 @@
 			viewStart = follow.start;
 			viewEnd = follow.end;
 		}
+		if (resumeOn) saveResume(false);
 		if (videoEl) onTimeUpdate?.(videoEl);
 	}
 
@@ -1577,9 +2279,13 @@
 	aria-label="Video player"
 	tabindex="-1"
 	onkeydown={onRootKeyDown}
+	onpointerdowncapture={maybeAskIdle}
+	onpointerupcapture={maybeAskIdle}
+	onclickcapture={maybeAskIdle}
+	onkeydowncapture={maybeAskIdle}
 >
 	<div class="vp-main">
-		<div class="vp-stage-wrap">
+		<div class="vp-stage-wrap" bind:this={stageWrapEl}>
 		{#if nightPresent}
 			<!-- Bias light: the frame's own colours, blurred, spilled behind the
 			     picture. Earlier in the DOM than the (positioned) stage, so the
@@ -1603,6 +2309,7 @@
 			style:--vp-night-sat={nightFrame ? nightFrame.levels.sat.toFixed(3) : undefined}
 			style:--vp-night-warm={nightLayersOn && nightFrame ? nightFrame.levels.warm.toFixed(3) : undefined}
 			style:--vp-night-vig={nightLayersOn && nightFrame ? nightFrame.levels.vig.toFixed(3) : undefined}
+			style:--vp-wind-down={windProgress > 0 ? windProgress.toFixed(3) : undefined}
 			onwheel={onStageWheel}
 		>
 			<video
@@ -1617,8 +2324,19 @@
 				}}
 				onplay={() => {
 					if (nightPresent || guardPresent) nightTick();
+					if (windPhase === 'paused') windCancel();
+					if (windOn) windProbe();
+				}}
+				onpause={() => {
+					syncUrlNow();
+					// You paused mid-fade: that's an answer too — hand the volume back.
+					if (windPhase === 'fading') windCancel();
+					if (resumeOn) saveResume(true);
+				}}
+				onended={() => {
+					if (resumeOn) saveResume(true);
 				}}
-				onpause={syncUrlNow}
+				onloadeddata={() => (openPosterOn = false)}
 				{src}
 				{loop}
 				crossorigin={crossorigin ?? undefined}
@@ -1636,6 +2354,13 @@
 				     menu but isn't painted on top of the frames' own text (jat-abwim). -->
 				<track kind="captions" src={captionsSrc ?? undefined} srclang={captionsLang} label={captionsLabel} default={!!captionsSrc && captionsDefault} />
 			</video>
+			{#if openPosterOn}
+				<!-- Open-like-an-object poster (mos-5lzns.34): the card's own
+				     thumbnail OVER the video's opaque letterbox until the first frame
+				     decodes — a layer behind it would be hidden by the very box it
+				     exists to cover. Below the night veils and the OSD by DOM order. -->
+				<div class="vp-open-poster" style:--vp-open-poster={openPosterImage} aria-hidden="true"></div>
+			{/if}
 			{#if nightPresent}
 				<!-- Night veils. Both MULTIPLY: a grey scrim would raise the black
 				     point and fog the picture; multiplying leaves blacks black. At
@@ -1643,6 +2368,15 @@
 				<div class="vp-night-layer vp-night-warm" aria-hidden="true"></div>
 				<div class="vp-night-layer vp-night-vignette" aria-hidden="true"></div>
 			{/if}
+			{#if windProgress > 0}
+				<!-- Wind-down veil (mos-5lzns.34): DARKENS toward neutral over the
+				     picture and the night veils. The video itself is never made
+				     translucent — whatever sits behind it (the page, the bias
+				     light) would show through and the fade would brighten. A DOM
+				     layer, so the night meter still reads raw frames. Under the
+				     OSD, which carries the hint. Gone the instant progress is 0. -->
+				<div class="vp-wind-veil" aria-hidden="true"></div>
+			{/if}
 			<div class="vp-osd" class:on={osdOn} aria-hidden="true">{osd}</div>
 		</div>
 		</div>
@@ -2585,6 +3319,35 @@
 		position: relative;
 	}
 
+	/* ── Presence (mos-5lzns.34) ──────────────────────────────────────────
+	   Wind-down: a neutral veil driven frame by frame from script, so no
+	   transition to fight.
+	   Its own variable, never folded into --vp-night-bright: "this is bright"
+	   and "you are not here" are different statements, and one must not be
+	   able to cancel the other out. Unset ⇒ opacity 1, no pixel changed. */
+	.vp-wind-veil {
+		position: absolute;
+		inset: 0;
+		pointer-events: none;
+		border-radius: inherit;
+		background: var(--color-neutral);
+		opacity: calc(0.92 * var(--vp-wind-down, 0));
+		transition: none;
+	}
+
+	/* The open poster: a stand-in for the first frame, so it sits exactly
+	   where the video will put its picture (contain, not cover). */
+	.vp-open-poster {
+		position: absolute;
+		inset: 0;
+		pointer-events: none;
+		border-radius: inherit;
+		background-image: var(--vp-open-poster, none);
+		background-repeat: no-repeat;
+		background-position: center;
+		background-size: contain;
+	}
+
 	/* Bias light: peripheral light, so the blur is large on purpose — any
 	   detail in it reads as a distracting second image. */
 	.vp-bias {