@joewinke/jatui 0.14.0 → 0.16.0

package/dist/components/VideoPlayer.svelte

@@ -19,6 +19,11 @@
 	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';
+	// mos-5lzns.35 — settings registry + panel.
+	export type { VideoSettingsStore, SettingValue, SettingSpec } from '../video/settings';
 </script>
 
 <script lang="ts">
@@ -186,6 +191,47 @@
 		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';
+	import { idleDetectionSupported } from '../video/presence';
+	import {
+		createSettingsSession,
+		panelGroups,
+		VIDEO_SETTINGS,
+		type SettingAvailability,
+		type SettingsSession,
+		type SettingValue,
+		type VideoSettingsStore
+	} from '../video/settings';
+	import SettingsPanel from '../video/settings/SettingsPanel.svelte';
 
 	let {
 		src,
@@ -229,7 +275,7 @@
 		syncUrlTime = false,
 		luma = null,
 		markers = [],
-		oneAxis = true,
+		oneAxis: oneAxisProp = true,
 		onBandChange = undefined,
 		onMarkerClick = undefined,
 		onTimeUpdate = undefined,
@@ -238,23 +284,39 @@
 		night = $bindable(),
 		nightDepth = $bindable(NIGHT_DEPTH_DEFAULT),
 		nightWindow = null,
-		biasLight = true,
-		predictive = true,
-		strobeGuard = true,
+		biasLight: biasLightProp = true,
+		predictive: predictiveProp = true,
+		strobeGuard: strobeGuardProp = true,
 		onNightModeChange = undefined,
 		onNightBlind = undefined,
-		loudness = undefined,
-		loudnessTarget = AUDIO_TARGET_DEFAULT,
-		quietListening = undefined,
-		limiter = undefined,
+		loudness: loudnessProp = undefined,
+		loudnessTarget: loudnessTargetProp = AUDIO_TARGET_DEFAULT,
+		quietListening: quietListeningProp = undefined,
+		limiter: limiterProp = undefined,
 		onAudioState = undefined,
 		onAudioBroken = undefined,
-		smartSpeed = false,
-		speakerPace = false,
+		smartSpeed: smartSpeedProp = false,
+		speakerPace: speakerPaceProp = false,
 		speakerRates = null,
 		adSpans = null,
-		skipAds = false,
+		skipAds: skipAdsProp = false,
 		onRateChange = undefined,
+		windDown: windDownProp = undefined,
+		windDownAfter: windDownAfterProp = WIND_DOWN_AFTER_DEFAULT,
+		windDownNightOnly: windDownNightOnlyProp = true,
+		idleDetection: idleDetectionProp = false,
+		onWindDown = undefined,
+		resumeKey = null,
+		resumeStore = undefined,
+		resumeSnap: resumeSnapProp = true,
+		onResume = undefined,
+		openFrom = undefined,
+		openPoster = null,
+		openMotion: openMotionProp = true,
+		settingsStore = undefined,
+		settingsPanel = false,
+		settingsHelpHref = null,
+		onSettingChange = undefined,
 		class: className = ''
 	}: {
 		src: string;
@@ -463,9 +525,138 @@
 		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;
+		/**
+		 * Settings (mos-5lzns.35): where the viewer's standing choices live —
+		 * `{ get(id), set(id, value) }`, either may be async, keyed by the ids
+		 * in `VIDEO_SETTINGS`. jatui never persists on its own (no
+		 * localStorage, no API): a host with per-user state passes its own
+		 * adapter. Every stored value is coerced; junk reads as nothing.
+		 *
+		 * A stored choice overrides the matching prop — the prop is the
+		 * host's DEFAULT, the stored value is the viewer's decision. It never
+		 * creates a feature the host left out: a stored `audio.level` does
+		 * nothing on a player with no `loudness` prop. `night.mode` /
+		 * `night.depth` are written into the bindable `night` / `nightDepth`,
+		 * and `N` / the moon wheel are saved back through the store.
+		 */
+		settingsStore?: VideoSettingsStore;
+		/**
+		 * Show the settings panel (default off — inert): a gear in the control
+		 * strip and the `,` key open it. The panel is generated from the
+		 * registry and shows only rows for features THIS player has (host
+		 * opted in and the data exists). Without a `settingsStore`, choices
+		 * last while the player is mounted.
+		 */
+		settingsPanel?: boolean;
+		/** A host page explaining the settings — linked from the panel's footer. */
+		settingsHelpHref?: string | null;
+		/** The viewer changed a setting (panel, `N`, the moon wheel). Coerced value. */
+		onSettingChange?: (id: string, value: SettingValue) => void;
 		class?: string;
 	} = $props();
 
+	// ── Settings overlay (mos-5lzns.35) ─────────────────────────────────────
+	// The viewer's stored/panel choices, coerced, keyed by registry id. Each
+	// feature reads the EFFECTIVE value below under its prop's own name, so
+	// no reader changed: the choice wins over the host's prop, but a
+	// presence-gated feature (prop left undefined) stays absent whatever is
+	// stored. night / nightDepth are bindable and written directly instead.
+	let userSettings = $state<Record<string, SettingValue>>({});
+	function chosen<T>(id: string, prop: T): T {
+		const v = userSettings[id];
+		return (v === undefined ? prop : v) as T;
+	}
+	function chosenIfPresent<T>(id: string, prop: T | undefined): T | undefined {
+		return prop === undefined ? undefined : chosen(id, prop);
+	}
+	const oneAxis = $derived(chosen('player.oneAxis', oneAxisProp));
+	const biasLight = $derived(chosen('night.bias', biasLightProp));
+	const predictive = $derived(chosen('player.predictive', predictiveProp));
+	const strobeGuard = $derived(chosen('player.strobeGuard', strobeGuardProp));
+	const loudness = $derived(chosenIfPresent('audio.level', loudnessProp));
+	const loudnessTarget = $derived(chosen('audio.target', loudnessTargetProp));
+	const quietListening = $derived(chosenIfPresent('audio.quiet', quietListeningProp));
+	const limiter = $derived(chosenIfPresent('audio.limiter', limiterProp));
+	const smartSpeed = $derived(chosen('player.smartSpeed', smartSpeedProp));
+	const speakerPace = $derived(chosen('player.speakerRate', speakerPaceProp));
+	const skipAds = $derived(chosen('player.skipAds', skipAdsProp));
+	const windDown = $derived(chosenIfPresent('sleep.enabled', windDownProp));
+	const windDownAfter = $derived(chosen('sleep.after', windDownAfterProp));
+	const windDownNightOnly = $derived(chosen('sleep.nightOnly', windDownNightOnlyProp));
+	const idleDetection = $derived(chosen('sleep.desktopIdle', idleDetectionProp));
+	const resumeSnap = $derived(chosen('player.resumeSnap', resumeSnapProp));
+	const openMotion = $derived(chosen('player.openMotion', openMotionProp));
+
 	// prefers-reduced-motion gate for autoplay: an autoplaying clip IS motion, so
 	// under the reduce preference the video holds on its poster instead. Tracked
 	// live (media query listener) so a mid-session preference flip is honoured, and
@@ -663,6 +854,7 @@
 			if (row.when === 'transcript') return sortedSegments.length > 0;
 			if (row.when === 'comments') return socialMarkers.comments.length > 0;
 			if (row.when === 'night') return nightPresent;
+			if (row.when === 'settings') return settingsPanel;
 			return true;
 		})
 	);
@@ -698,11 +890,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 ─────────────────────────────────────────────────────────────
@@ -898,7 +1094,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,
@@ -910,7 +1109,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'];
@@ -931,7 +1132,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
 		};
@@ -1129,6 +1331,7 @@
 	function setNightMode(mode: NightMode) {
 		night = mode;
 		onNightModeChange?.(mode);
+		rememberSetting('night.mode', mode);
 	}
 	function cycleNight() {
 		if (night === undefined) return;
@@ -1143,6 +1346,7 @@
 		e.stopPropagation();
 		if (!nightArmedNow) setNightMode('on');
 		nightDepth = nudgeDepth(nightDepth, e.deltaY < 0 ? 1 : -1);
+		rememberSetting('night.depth', nightDepth);
 		flashOsd(`Night ${Math.round(clampDepth(nightDepth) * 100)}%`);
 	}
 
@@ -1293,6 +1497,523 @@
 		});
 	});
 
+	// ── 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';
+		};
+	});
+
+	// ── Settings session + panel (mos-5lzns.35) ─────────────────────────────
+	// No store and no panel ⇒ no session: the player behaves exactly as
+	// before. The session reads the host's store once per store identity,
+	// coerces every value, and lets a choice made on screen beat a late read.
+	let settingsSession: SettingsSession | null = null;
+	let settingsOpen = $state(false);
+	let settingsBtnEl: HTMLButtonElement | undefined = $state();
+	let rootEl: HTMLDivElement | undefined = $state();
+
+	/** Land one coerced value: bindables are written, everything else overlays its prop. */
+	function applySetting(id: string, v: SettingValue) {
+		if (id === 'night.mode') {
+			if (night !== undefined && night !== v) {
+				night = v as NightMode;
+				onNightModeChange?.(night);
+			}
+			return;
+		}
+		if (id === 'night.depth') {
+			if (night !== undefined) nightDepth = v as number;
+			return;
+		}
+		userSettings[id] = v;
+	}
+
+	$effect(() => {
+		const store = settingsStore;
+		if (!store && !settingsPanel) return;
+		const session = untrack(() =>
+			createSettingsSession({
+				store,
+				onValue: (id, v, source) => {
+					applySetting(id, v);
+					if (source === 'user') onSettingChange?.(id, v);
+				}
+			})
+		);
+		settingsSession = session;
+		return () => {
+			session.close();
+			if (settingsSession === session) settingsSession = null;
+		};
+	});
+
+	/** A viewer choice from outside the panel (N, the moon wheel) — saved like a panel change. */
+	function rememberSetting(id: string, v: SettingValue) {
+		settingsSession?.change(id, v);
+	}
+
+	/** Rows exist only for features this player has: host opted in AND the data is here. */
+	const settingsAvailable = $derived<SettingAvailability>({
+		waveform: hasWave,
+		speakers: sortedTurns.length > 0 && sortedSegments.length > 0,
+		ads: normalizeAdSpans(adSpans, speakers).length > 0,
+		loudness: loudnessProp !== undefined,
+		quiet: quietListeningProp !== undefined,
+		limiter: limiterProp !== undefined,
+		night: nightPresent,
+		nightLuma: nightPresent && lumaSeries != null,
+		flashes: nightFlashes.length > 0,
+		windDown: windDownProp !== undefined,
+		idle: windDownProp !== undefined && idleDetectionSupported(),
+		resume: resumeKey != null,
+		open: openFrom !== undefined
+	});
+	const settingsGroups = $derived(settingsOpen ? panelGroups(settingsAvailable) : []);
+	/** What the player is doing right now, per id — the panel shows exactly this. */
+	const settingsValues = $derived.by(() => {
+		const byProp: Record<string, SettingValue | undefined> = {
+			night,
+			nightDepth,
+			biasLight,
+			predictive,
+			strobeGuard,
+			loudness,
+			loudnessTarget,
+			quietListening,
+			limiter,
+			smartSpeed,
+			speakerPace,
+			skipAds,
+			windDown,
+			windDownAfter,
+			windDownNightOnly,
+			idleDetection,
+			resumeSnap,
+			openMotion,
+			oneAxis
+		};
+		const out: Record<string, SettingValue> = {};
+		for (const spec of VIDEO_SETTINGS) {
+			const v = byProp[spec.prop];
+			out[spec.id] = v === undefined || v === null ? spec.default : v;
+		}
+		return out;
+	});
+
+	function openSettings() {
+		if (!settingsPanel) return;
+		keysOpen = false;
+		settingsOpen = true;
+	}
+	function closeSettings() {
+		settingsOpen = false;
+		settingsSession?.flush();
+		// Focus goes back where it came from (the gear), else the player —
+		// never to a detached node (the gear is gone when the host turned
+		// the panel off).
+		queueMicrotask(() => (settingsBtnEl?.isConnected ? settingsBtnEl : rootEl)?.focus());
+	}
+	// The host turned the panel off while it was open: close it properly, so
+	// focus is handed back instead of being dropped with the dialog.
+	$effect(() => {
+		if (!settingsPanel && untrack(() => settingsOpen)) untrack(closeSettings);
+	});
+
+	function desktopWanted(): boolean {
+		return windOn && idleDetection === true;
+	}
+
+	function onPanelChange(id: string, v: SettingValue) {
+		// Turning the desktop signal on is the ONE place the panel may lead to a
+		// permission prompt: an explicit opt-in, asked synchronously inside the
+		// click that made it (the API needs the gesture). Never on load.
+		if (id === 'sleep.desktopIdle' && v === true && idleDetection !== true && !idleAskInFlight) {
+			// In flight: the gesture listeners must not ask again while this
+			// prompt is still unanswered (maybeAskIdle checks the same flag).
+			idleAskInFlight = true;
+			idleAskPending = false;
+			void requestIdleDetection().then((r) => {
+				idleAskInFlight = false;
+				// Read at resolve time: by then the change below has landed.
+				if (r === 'granted' && desktopWanted()) {
+					idleAskPending = false;
+					startDesktop();
+				} else if (r === 'denied') {
+					idleAskPending = false;
+				}
+			});
+		}
+		settingsSession?.change(id, v);
+	}
+
+	// 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;
@@ -1560,6 +2281,10 @@
 		const v = videoEl;
 		if (!v) return;
 
+		// The settings panel stops its own keys; anything that still arrives
+		// while it is open (focus on the backdrop) must not drive the player.
+		if (settingsOpen) return;
+
 		// The help overlay takes over Escape while it's open.
 		if (keysOpen) {
 			if (e.key === 'Escape' || e.key === '?') {
@@ -1574,6 +2299,11 @@
 				e.preventDefault();
 				keysOpen = true;
 				return;
+			case ',':
+				if (!settingsPanel) break;
+				e.preventDefault();
+				openSettings();
+				return;
 			case ' ':
 			case 'k':
 				v.paused ? v.play() : v.pause();
@@ -1698,6 +2428,7 @@
 				seekTo(start);
 			}
 		}
+		applyStoredResume();
 	}
 
 	/**
@@ -1728,6 +2459,7 @@
 			viewStart = follow.start;
 			viewEnd = follow.end;
 		}
+		if (resumeOn) saveResume(false);
 		if (videoEl) onTimeUpdate?.(videoEl);
 	}
 
@@ -1768,6 +2500,7 @@
 <!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
 <div
 	class="vp-root {className}"
+	bind:this={rootEl}
 	class:vp-side={transcriptPosition === 'side' && sortedSegments.length > 0 && transcriptVisible}
 	class:vp-one-axis={nativeBarHidden}
 	class:vp-night-capable={nightPresent}
@@ -1778,9 +2511,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
@@ -1804,6 +2541,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
@@ -1818,8 +2556,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}
@@ -1837,6 +2586,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
@@ -1844,6 +2600,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>
@@ -1989,6 +2754,25 @@
 						</svg>
 					</button>
 				{/if}
+				{#if settingsPanel}
+					<button
+						type="button"
+						class="vp-night-btn vp-settings-btn"
+						class:active={settingsOpen}
+						aria-label="Settings"
+						aria-haspopup="dialog"
+						aria-expanded={settingsOpen}
+						title="Settings · ,"
+						bind:this={settingsBtnEl}
+						onclick={() => (settingsOpen ? closeSettings() : openSettings())}
+					>
+						<svg viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+							<path d="M4 7h10M18 7h2M4 17h4M12 17h8" />
+							<circle cx="16" cy="7" r="2" />
+							<circle cx="10" cy="17" r="2" />
+						</svg>
+					</button>
+				{/if}
 			</span>
 			<span>{formatTime(effectiveDuration, useHours)}</span>
 		</div>
@@ -2127,6 +2911,17 @@
 			</div>
 		</div>
 	{/if}
+
+	{#if settingsOpen}
+		<SettingsPanel
+			groups={settingsGroups}
+			values={settingsValues}
+			onchange={onPanelChange}
+			onclose={closeSettings}
+			helpHref={settingsHelpHref}
+			persisted={!!settingsStore}
+		/>
+	{/if}
 </div>
 
 <style>
@@ -2786,6 +3581,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 {