@joewinke/jatui 0.11.0 → 0.13.0

package/dist/components/VideoPlayer.svelte

@@ -13,6 +13,10 @@
 	export type { BandAxis, BandState } from '../video/band/axis';
 	export type { VideoLumaTrack } from '../video/band/luma';
 	export type { VideoMarker } from '../video/band/markers';
+	// mos-5lzns.33 — night dimming.
+	export type { NightMode, NightWindow } from '../video/night/clock';
+	// mos-5lzns.31 — audio graph.
+	export type { AudioState, AudioStatus, AudioBrokenReason } from '../video/audio/graph';
 </script>
 
 <script lang="ts">
@@ -135,6 +139,33 @@
 	import { BAND_KEYS, PLAYER_KEYS, chapterJump, FRAME_STEP_SEC } from '../video/keys';
 	import { composeRate, formatSpeedLabel, stepRate } from '../video/rate';
 	import { readTimeParam, WRITE_THROTTLE_MS, writeTimeParam } from '../video/deepLink';
+	import {
+		biasCells,
+		biasGradient,
+		frameLuma,
+		METER_START,
+		NIGHT_H,
+		NIGHT_W,
+		smoothMeter
+	} from '../video/night/meter';
+	import { NIGHT_DEPTH_DEFAULT, clampDepth, nudgeDepth, relativeLuminance, surroundLevel } from '../video/night/levels';
+	import { nextNightMode, nightArmed, nightModeLabel, type NightMode, type NightWindow } from '../video/night/clock';
+	import {
+		composeNight,
+		inFlash,
+		lumaAhead,
+		NIGHT_IDLE,
+		normalizeFlashes,
+		type NightFrame,
+		type NightState
+	} from '../video/night/track';
+	import {
+		createAudioSession,
+		routeSafety,
+		AUDIO_TARGET_DEFAULT,
+		type AudioBrokenReason,
+		type AudioState
+	} from '../video/audio';
 
 	let {
 		src,
@@ -184,6 +215,20 @@
 		onTimeUpdate = undefined,
 		onAddBookmark = undefined,
 		onBookmarkContext = undefined,
+		night = $bindable(),
+		nightDepth = $bindable(NIGHT_DEPTH_DEFAULT),
+		nightWindow = null,
+		biasLight = true,
+		predictive = true,
+		strobeGuard = true,
+		onNightModeChange = undefined,
+		onNightBlind = undefined,
+		loudness = undefined,
+		loudnessTarget = AUDIO_TARGET_DEFAULT,
+		quietListening = undefined,
+		limiter = undefined,
+		onAudioState = undefined,
+		onAudioBroken = undefined,
 		class: className = ''
 	}: {
 		src: string;
@@ -281,6 +326,85 @@
 			clientX: number,
 			clientY: number
 		) => void;
+		/**
+		 * Night dimming (mos-5lzns.33) — a METER, not a preference: ~1×/s while
+		 * playing it reads the frame's actual brightness (32×18 canvas) and pulls
+		 * the picture down in proportion, warming it through multiply layers so
+		 * blacks stay black. A dark scene passes through untouched.
+		 *
+		 * `'auto'` arms it from the local clock (20:00–07:00; 18:00–08:00 when the
+		 * OS prefers dark), `'on'` always, `'off'` never. Omitted (default) ⇒ the
+		 * feature does not exist on this player: no N key, no button, no layers.
+		 * Bindable — `N` and the moon button cycle it; `onNightModeChange` reports.
+		 *
+		 * Frame reading needs a CORS-clean load: pass `crossorigin="anonymous"`
+		 * for cross-origin media. A tainted canvas runs night on a fixed level
+		 * (no meter, no bias light) and calls `onNightBlind`.
+		 */
+		night?: NightMode;
+		/** How far night goes, 0.2–1 (default 0.7). Bindable — scrolling the moon button sets it. */
+		nightDepth?: number;
+		/** Override the auto window, local hours `{ from, to }` (wraps midnight when from > to). */
+		nightWindow?: NightWindow | null;
+		/** While night acts, spill the frame's own colours, blurred, behind the player. */
+		biasLight?: boolean;
+		/** Read the `luma` track ~1s ahead so dimming starts BEFORE a bright cut. Only ever adds dimming. */
+		predictive?: boolean;
+		/**
+		 * Photosensitivity guard: across the `luma` track's flash intervals,
+		 * drop the picture to about 55% brightness (instant in, released per
+		 * tick — never a jump back up). Always at full strength: it does NOT
+		 * follow `nightDepth`, and it acts whether night is on, off or absent,
+		 * whenever the track carries `flashes`. `false` to disable.
+		 *
+		 * It REDUCES flashes; it does not make content WCAG 2.3.1-safe. Flash
+		 * DETECTION is the host's job — the player guards only the intervals the
+		 * host supplies in `luma.flashes`.
+		 */
+		strobeGuard?: boolean;
+		onNightModeChange?: (mode: NightMode) => void;
+		/** Frame readback was refused (CORS-tainted canvas) — night fell back to a fixed level. */
+		onNightBlind?: () => void;
+		/**
+		 * Audio graph (mos-5lzns.31) — all three default OFF (absent = the
+		 * feature does not exist on this player and nothing is ever routed).
+		 *
+		 * `loudness`: a gated RMS meter rides the gain slowly toward
+		 * `loudnessTarget` (dBFS, −30…−12, default −20) so a whispered video and
+		 * a blaring one arrive at the same level; clamped 0.3–1.35×, it rescues a
+		 * quiet mix by a few dB and never becomes an amplifier.
+		 * `quietListening`: loudness-compensated tone that rises as the volume
+		 * drops (and sits a little on while night is armed).
+		 * `limiter`: catches peaks above −3 dBFS that the slow rider can't.
+		 *
+		 * ⚠ Routing into WebAudio is permanent for the element, and a source
+		 * that isn't CORS-clean routes to SILENCE. So the player routes only
+		 * when the src is blob:/data: or `crossorigin` is set ("anonymous" /
+		 * "use-credentials", with the server answering Access-Control-Allow-
+		 * Origin) — a same-origin URL is NOT enough, since it may redirect to
+		 * storage on another origin. Anything else is refused and plays
+		 * unprocessed (`status: 'cors'`). It also waits for the AudioContext to
+		 * be `running` (a user gesture); until then native audio plays.
+		 *
+		 * After routing it cannot be undone, so the player reports
+		 * `status: 'broken'` and calls `onAudioBroken(reason)`:
+		 * · 'unsafe-src' — the src later changed to one that isn't route-safe
+		 *   (or `crossorigin` was removed). Remount the player (a fresh element)
+		 *   for that source.
+		 * · 'silent' — bit-exact silence for 4s while the video plays audibly
+		 *   AND the browser shows decoded audio flowing (a video with no audio
+		 *   track never fires). Show a notice and/or turn the audio features
+		 *   off for that src — do NOT remount; it would loop.
+		 * · 'build-failed' — construction threw: plain audio for the session.
+		 */
+		loudness?: boolean;
+		loudnessTarget?: number;
+		quietListening?: boolean;
+		limiter?: boolean;
+		/** Graph status + the rider's live gain (≤5×/s while matching acts). */
+		onAudioState?: (state: AudioState) => void;
+		/** Entered `broken`: 'build-failed' | 'unsafe-src' | 'silent' (see above). */
+		onAudioBroken?: (reason: AudioBrokenReason) => void;
 		class?: string;
 	} = $props();
 
@@ -292,6 +416,8 @@
 	// Autoplay forces muted — browsers refuse to autoplay audible video, and a
 	// silent presentation clip is the point of the primitive anyway.
 	const effectiveAutoplay = $derived(autoplay && !reduceMotion);
+	// The stage's locked ratio (null ⇒ the video's intrinsic ratio drives the box).
+	const stageAspect = $derived(aspectRatioCss(aspect));
 	// `(pointer: coarse)` — a fingertip gets a wider comment-dot target.
 	let coarsePointer = $state(false);
 
@@ -478,6 +604,7 @@
 			if (row.when === 'bookmarks') return onAddBookmark != null;
 			if (row.when === 'transcript') return sortedSegments.length > 0;
 			if (row.when === 'comments') return socialMarkers.comments.length > 0;
+			if (row.when === 'night') return nightPresent;
 			return true;
 		})
 	);
@@ -548,6 +675,276 @@
 		flashOsd(formatSpeedLabel(baseRate));
 	}
 
+	// ── Audio (video/audio/*) ───────────────────────────────────────────────
+	// The session owns the graph and its one-way door; this block only hands
+	// it the element (inside `route`) and re-applies on every input it reads.
+	// Inert until a feature is on: no context, no routing. Gestures anywhere
+	// on the page resume a suspended context and retry a pending route.
+	let audio: ReturnType<typeof createAudioSession> | null = null;
+	$effect(() => {
+		const v = videoEl;
+		if (!v) return;
+		const s = createAudioSession({
+			// The attribute is what will load next; currentSrc lags it until loadstart.
+			routable: () => routeSafety(v.getAttribute('src') || v.currentSrc, v.getAttribute('crossorigin')),
+			context: () => new AudioContext(),
+			route: (ctx) => (ctx as AudioContext).createMediaElementSource(v),
+			playback: () => {
+				const m = v as HTMLVideoElement & {
+					webkitAudioDecodedByteCount?: number;
+					mozHasAudio?: boolean;
+					audioTracks?: { length: number };
+				};
+				return {
+					playing: !v.paused && !v.ended,
+					hidden: document.hidden,
+					audible: !v.muted && v.volume > 0,
+					time: v.currentTime,
+					audioDecoded: typeof m.webkitAudioDecodedByteCount === 'number' ? m.webkitAudioDecodedByteCount : null,
+					audioPresent:
+						typeof m.mozHasAudio === 'boolean' ? m.mozHasAudio : m.audioTracks ? m.audioTracks.length > 0 : null
+				};
+			},
+			onState: (st) => onAudioState?.(st),
+			onBroken: (reason) => onAudioBroken?.(reason)
+		});
+		audio = s;
+		const sync = () => untrack(() => s.apply(audioOpts(v)));
+		const gesture = () => s.gesture();
+		const media = ['volumechange', 'loadstart', 'loadedmetadata'];
+		const gestures = ['pointerdown', 'pointerup', 'keydown', 'touchend'];
+		for (const e of media) v.addEventListener(e, sync);
+		v.addEventListener('play', gesture);
+		for (const e of gestures) window.addEventListener(e, gesture, { capture: true, passive: true });
+		return () => {
+			for (const e of media) v.removeEventListener(e, sync);
+			v.removeEventListener('play', gesture);
+			for (const e of gestures) window.removeEventListener(e, gesture, { capture: true });
+			s.dispose();
+			audio = null;
+		};
+	});
+	function audioOpts(v: HTMLVideoElement) {
+		return {
+			level: loudness === true,
+			target: loudnessTarget,
+			limiter: limiter === true,
+			quiet: quietListening === true,
+			volume: v.volume,
+			muted: v.muted,
+			night: nightArmedNow
+		};
+	}
+	$effect(() => {
+		const v = videoEl;
+		void crossorigin; // a CORS opt-in clears a 'cors' refusal; removing it after routing is 'unsafe-src'
+		void src;
+		const o = v ? audioOpts(v) : null;
+		if (o) untrack(() => audio?.apply(o));
+	});
+
+	// ── Night (video/night/*) ───────────────────────────────────────────────
+	// The modules decide; this block samples the frame and applies the answer
+	// as CSS variables that exist ONLY while night (or the strobe guard) is
+	// acting — off leaves no trace. The meter canvas and the running levels
+	// are plain (non-reactive): written and read inside one tick.
+	const NIGHT_TICK_MS = 900;
+	/** Bias light refreshes at most this often — peripheral light, not a second picture. */
+	const BIAS_EVERY_MS = 1800;
+	const nightPresent = $derived(night !== undefined);
+	const nightFlashes = $derived(normalizeFlashes(luma));
+	const guardPresent = $derived(strobeGuard && nightFlashes.length > 0);
+	let prefersDark = $state(false);
+	let nightArmedNow = $state(false);
+	let nightBlind = $state(false);
+	let nightFrame = $state<NightFrame | null>(null);
+	let biasImage = $state('');
+	let surroundLuma = $state(0);
+	let nightMeter = METER_START;
+	/** The composer's running state — night's level and the guard's, released independently. */
+	let nightOut: NightState = { ...NIGHT_IDLE };
+	let biasAt = 0;
+	let meterCtx: CanvasRenderingContext2D | null = null;
+
+	/** 32×18 RGBA bytes of the current frame, or null (no frame yet / canvas tainted). */
+	function sampleFrame(v: HTMLVideoElement): Uint8ClampedArray | null {
+		if (v.readyState < 2 || !v.videoWidth || !v.videoHeight) return null;
+		if (!meterCtx) {
+			const c = document.createElement('canvas');
+			c.width = NIGHT_W;
+			c.height = NIGHT_H;
+			meterCtx = c.getContext('2d', { willReadFrequently: true });
+			if (!meterCtx) return null;
+		}
+		try {
+			meterCtx.drawImage(v, 0, 0, NIGHT_W, NIGHT_H);
+			return meterCtx.getImageData(0, 0, NIGHT_W, NIGHT_H).data;
+		} catch (err) {
+			// Only a SecurityError means the canvas is tainted (cross-origin
+			// without CORS). Anything else — a decoder hiccup, a frame mid-swap —
+			// is transient: skip this sample and try again next tick.
+			if (!(err instanceof DOMException && err.name === 'SecurityError')) return null;
+			// Tainted: escalate to the host (it owns `crossorigin`) and run blind
+			// on a fixed level — never guess brightness. Bias light has nothing to
+			// sample, so it stands down.
+			nightBlind = true;
+			biasImage = '';
+			onNightBlind?.();
+			return null;
+		}
+	}
+
+	function nightTick() {
+		const v = videoEl;
+		if (!v) return;
+		const armed = night !== undefined && nightArmed(night, new Date(), prefersDark, nightWindow);
+		if (nightArmedNow !== armed) nightArmedNow = armed;
+		const hidden = typeof document !== 'undefined' && document.hidden;
+		const t = v.currentTime || 0;
+		// One tick's worth of media time: prediction and the guard look this
+		// much further ahead, so a coarse tick can never let the first flash through.
+		const horizon = (NIGHT_TICK_MS / 1000) * (v.playbackRate > 0 ? v.playbackRate : 1);
+		const flash = strobeGuard && inFlash(nightFlashes, t, horizon);
+		if (armed && !nightBlind && !v.paused && !hidden) {
+			const px = sampleFrame(v);
+			if (px) {
+				nightMeter = smoothMeter(nightMeter, frameLuma(px));
+				// The bias light reads the bytes the meter JUST drew — any other
+				// time the canvas is stale or empty, and empty reads as pitch black.
+				// Frozen while the guard is down: the glow's background-image swap
+				// is un-faded, and a strobe would drive it at the strobe's own rate.
+				if (biasLight && !flash && Date.now() - biasAt > BIAS_EVERY_MS) {
+					const g = biasGradient(biasCells(px));
+					if (g) {
+						biasImage = g;
+						biasAt = Date.now();
+					}
+				}
+			}
+		}
+		const f = composeNight(nightOut, {
+			armed,
+			blind: nightBlind,
+			meter: nightMeter,
+			ahead: armed && predictive ? lumaAhead(lumaSeries, t, horizon) : null,
+			flash,
+			depth: nightDepth
+		});
+		nightOut = { luma: f.luma, guardLuma: f.guardLuma };
+		nightFrame = f.mode === 'none' ? null : f;
+	}
+
+	/**
+	 * Drop night's traces at once. The guard's level is kept unless `all`:
+	 * switching night off is a statement about night, and must not cut short a
+	 * guard that is still releasing (that would be a jump back up).
+	 */
+	function nightClear(all = false) {
+		nightOut = { luma: 0, guardLuma: all ? 0 : nightOut.guardLuma };
+		nightFrame = null;
+		biasImage = '';
+		biasAt = 0;
+	}
+
+	// The tick runs only while the feature exists on this player (night opted
+	// in, or a track with flashes for the guard). Visibility changes re-tick at
+	// once so a returning tab doesn't wait out the interval.
+	$effect(() => {
+		const on = nightPresent || guardPresent;
+		const v = videoEl;
+		if (!on || !v) return;
+		const id = setInterval(nightTick, NIGHT_TICK_MS);
+		const onVis = () => nightTick();
+		document.addEventListener('visibilitychange', onVis);
+		return () => {
+			clearInterval(id);
+			document.removeEventListener('visibilitychange', onVis);
+			untrack(() => nightClear(true));
+		};
+	});
+
+	// A new source (or CORS mode) is a new picture: forget the meter, the
+	// blind verdict and the glow.
+	$effect(() => {
+		void src;
+		void crossorigin;
+		untrack(() => {
+			nightBlind = false;
+			nightMeter = METER_START;
+			nightClear(true);
+		});
+	});
+
+	// Knob changes re-evaluate now. Switching night off clears at once rather
+	// than releasing tick by tick — off is a statement, not a fade.
+	$effect(() => {
+		const mode = night;
+		void nightDepth;
+		void nightWindow;
+		void predictive;
+		void strobeGuard;
+		void biasLight;
+		void prefersDark;
+		void videoEl;
+		untrack(() => {
+			if (mode === 'off' || mode === undefined) nightClear();
+			else if (!biasLight) biasImage = '';
+			nightTick();
+		});
+	});
+
+	// The theme's surround (base-200) as relative luminance: on a light theme
+	// the surround is pulled down with the picture (levels.ts surroundLevel).
+	$effect(() => {
+		void themeTick;
+		if (!nightPresent) return;
+		untrack(() => {
+			surroundLuma = colorLuminance(getDaisyUIColor('base-200'));
+		});
+	});
+
+	/** Any CSS colour → relative luminance, via a 1×1 same-origin canvas (never tainted). */
+	function colorLuminance(color: string): number {
+		if (typeof document === 'undefined') return 0;
+		try {
+			const c = document.createElement('canvas');
+			c.width = c.height = 1;
+			const ctx = c.getContext('2d', { willReadFrequently: true });
+			if (!ctx) return 0;
+			ctx.fillStyle = color; // unparseable ⇒ stays the default black ⇒ 0 ⇒ surround untouched
+			ctx.fillRect(0, 0, 1, 1);
+			const [r, g, b] = ctx.getImageData(0, 0, 1, 1).data;
+			return relativeLuminance(r, g, b);
+		} catch {
+			return 0;
+		}
+	}
+
+	const nightLayersOn = $derived(nightFrame?.mode === 'night');
+	const biasOn = $derived(nightLayersOn && biasLight && !nightBlind && biasImage !== '');
+	const surroundMix = $derived(nightLayersOn ? surroundLevel(surroundLuma, nightDepth) : 0);
+	const nightLabel = $derived(nightModeLabel(night, nightArmedNow));
+
+	function setNightMode(mode: NightMode) {
+		night = mode;
+		onNightModeChange?.(mode);
+	}
+	function cycleNight() {
+		if (night === undefined) return;
+		const next = nextNightMode(night);
+		setNightMode(next);
+		flashOsd(nightModeLabel(next, nightArmed(next, new Date(), prefersDark, nightWindow)));
+	}
+	/** Scroll the moon: the depth dial. Reaching for it means you want to see it work, whatever the clock says. */
+	function onNightWheel(e: WheelEvent) {
+		if (night === undefined) return;
+		e.preventDefault();
+		e.stopPropagation();
+		if (!nightArmedNow) setNightMode('on');
+		nightDepth = nudgeDepth(nightDepth, e.deltaY < 0 ? 1 : -1);
+		flashOsd(`Night ${Math.round(clampDepth(nightDepth) * 100)}%`);
+	}
+
 	// ── Canvas ──────────────────────────────────────────────────────────────
 	// Repaint on any input the canvas reads. Deps are listed explicitly and the
 	// body is untracked — letting paintState's own reads register as deps is
@@ -628,6 +1025,15 @@
 			mq.addEventListener('change', onChange);
 			stopReduce = () => mq.removeEventListener('change', onChange);
 		}
+		let stopDark: (() => void) | undefined;
+		if (typeof window !== 'undefined' && window.matchMedia) {
+			// Only ever WIDENS night's auto window (night/clock.ts) — never the trigger.
+			const mq = window.matchMedia('(prefers-color-scheme: dark)');
+			prefersDark = mq.matches;
+			const onChange = () => (prefersDark = mq.matches);
+			mq.addEventListener('change', onChange);
+			stopDark = () => mq.removeEventListener('change', onChange);
+		}
 		let stopCoarse: (() => void) | undefined;
 		if (typeof window !== 'undefined' && window.matchMedia) {
 			const mq = window.matchMedia('(pointer: coarse)');
@@ -641,6 +1047,7 @@
 			stopTheme();
 			stopReduce?.();
 			stopCoarse?.();
+			stopDark?.();
 			if (dragRaf) cancelAnimationFrame(dragRaf);
 			if (zoomTimer) clearTimeout(zoomTimer);
 			if (osdTimer) clearTimeout(osdTimer);
@@ -1060,6 +1467,13 @@
 					flashOsd(transcriptVisible ? 'Transcript shown' : 'Transcript hidden');
 				}
 				return;
+			case 'n':
+			case 'N':
+				if (night !== undefined) {
+					e.preventDefault();
+					cycleNight();
+				}
+				return;
 			case 'Home':
 				seekTo(0);
 				break;
@@ -1155,6 +1569,9 @@
 	class="vp-root {className}"
 	class:vp-side={transcriptPosition === 'side' && sortedSegments.length > 0 && transcriptVisible}
 	class:vp-one-axis={nativeBarHidden}
+	class:vp-night-capable={nightPresent}
+	class:vp-night-surround={surroundMix > 0.001}
+	style:--vp-night-surround={surroundMix > 0.001 ? surroundMix.toFixed(3) : undefined}
 	data-band-axis={currentBandState.axis}
 	role="region"
 	aria-label="Video player"
@@ -1162,11 +1579,30 @@
 	onkeydown={onRootKeyDown}
 >
 	<div class="vp-main">
+		<div class="vp-stage-wrap">
+		{#if nightPresent}
+			<!-- Bias light: the frame's own colours, blurred, spilled behind the
+			     picture. Earlier in the DOM than the (positioned) stage, so the
+			     stage paints over it with no z-index and no stacking context. -->
+			<div
+				class="vp-bias"
+				class:on={biasOn}
+				style:--vp-bias-image={biasOn ? biasImage : undefined}
+				aria-hidden="true"
+			></div>
+		{/if}
 		<!-- svelte-ignore a11y_no_static_element_interactions -->
 		<div
 			class="vp-stage"
-			class:vp-stage-locked={aspectRatioCss != null}
-			style={aspectRatioCss != null ? `--vp-aspect: ${aspectRatioCss};` : undefined}
+			class:vp-stage-locked={stageAspect != null}
+			class:vp-night-capable={nightPresent || guardPresent}
+			class:vp-night-on={nightFrame != null}
+			class:vp-flash-guard={nightFrame?.guard === true}
+			style={stageAspect != null ? `--vp-aspect: ${stageAspect};` : undefined}
+			style:--vp-night-bright={nightFrame ? nightFrame.levels.bright.toFixed(3) : undefined}
+			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}
 			onwheel={onStageWheel}
 		>
 			<video
@@ -1175,7 +1611,13 @@
 				bind:duration
 				ontimeupdate={handleTimeUpdate}
 				onloadedmetadata={onLoadedMetadata}
-				onseeked={syncUrlNow}
+				onseeked={() => {
+					syncUrlNow();
+					if (nightPresent || guardPresent) nightTick();
+				}}
+				onplay={() => {
+					if (nightPresent || guardPresent) nightTick();
+				}}
 				onpause={syncUrlNow}
 				{src}
 				{loop}
@@ -1194,8 +1636,16 @@
 				     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 nightPresent}
+				<!-- Night veils. Both MULTIPLY: a grey scrim would raise the black
+				     point and fog the picture; multiplying leaves blacks black. At
+				     opacity 0 (their variables unset) they change no pixel. -->
+				<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}
 			<div class="vp-osd" class:on={osdOn} aria-hidden="true">{osd}</div>
 		</div>
+		</div>
 
 		<!-- The band: one time axis for the envelope, chapters, speakers and
 		     bookmarks. Its height is reserved from the first frame, so data
@@ -1314,11 +1764,31 @@
 
 		<div class="vp-times">
 			<span>{formatTime(currentTime, useHours)}</span>
-			{#if isZoomedNow()}
-				<button type="button" class="vp-reset-zoom" onclick={() => { resetZoom(); flashZoomLabel(); }}>
-					Reset zoom
-				</button>
-			{/if}
+			<span class="vp-times-mid">
+				{#if isZoomedNow()}
+					<button type="button" class="vp-reset-zoom" onclick={() => { resetZoom(); flashZoomLabel(); }}>
+						Reset zoom
+					</button>
+				{/if}
+				{#if nightPresent}
+					<!-- The veil's switch: click (or N) cycles auto → on → off; scroll
+					     sets the depth. Lit in the ribbon's warm token while dimming. -->
+					<button
+						type="button"
+						class="vp-night-btn"
+						class:active={nightLayersOn}
+						aria-label={nightLabel}
+						title="{nightLabel} · N cycles, scroll sets depth"
+						onclick={cycleNight}
+						onwheel={onNightWheel}
+					>
+						<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="M20 14.5A8.5 8.5 0 1 1 9.5 4a6.8 6.8 0 0 0 10.5 10.5Z" />
+							{#if night === 'off'}<path d="M4 20 20 4" />{/if}
+						</svg>
+					</button>
+				{/if}
+			</span>
 			<span>{formatTime(effectiveDuration, useHours)}</span>
 		</div>
 
@@ -2053,4 +2523,153 @@
 			transition: none;
 		}
 	}
+
+	/* ── Night (mos-5lzns.33) ─────────────────────────────────────────────
+	   Every value arrives as a custom property that exists ONLY while night
+	   (or the strobe guard) acts; unset, each layer falls back to identity —
+	   brightness(1), opacity 0 — so off changes no pixel. The long ramps are
+	   the point: the eye must never catch the change, only notice afterwards
+	   that the room got easier. */
+
+	/* The transition lives on the video whenever the feature exists and the
+	   filter only under .vp-night-on, so switching off eases back up the way
+	   it came down (a rule carrying both would snap on the way out). */
+	.vp-night-capable .vp-video {
+		transition: filter 900ms var(--motion-glide, cubic-bezier(0.25, 1, 0.5, 1));
+	}
+
+	.vp-night-on .vp-video {
+		filter: brightness(var(--vp-night-bright, 1)) saturate(var(--vp-night-sat, 1));
+	}
+
+	.vp-night-layer {
+		position: absolute;
+		inset: 0;
+		pointer-events: none;
+		border-radius: inherit;
+		mix-blend-mode: multiply;
+		opacity: 0;
+		transition: opacity 900ms var(--motion-glide, cubic-bezier(0.25, 1, 0.5, 1));
+	}
+
+	/* Warmth: multiplying by the warm token (the ribbon's own colour, so the
+	   ribbon reads as "how much night is coming") leaves red intact and takes
+	   most of the blue — the night-shift lever, applied per pixel. */
+	.vp-night-warm {
+		background: var(--color-warning);
+		opacity: var(--vp-night-warm, 0);
+	}
+
+	/* A lens falloff, off-centre high where a face usually sits; nothing until
+	   42% out, so the subject never darkens. */
+	.vp-night-vignette {
+		background: radial-gradient(
+			ellipse 82% 86% at 50% 44%,
+			transparent 42%,
+			color-mix(in oklch, var(--color-neutral) 55%, transparent) 100%
+		);
+		opacity: var(--vp-night-vig, 0);
+	}
+
+	/* Strobe guard: protection has to arrive before the flash, so this one
+	   moment is fast. Everything else about night is deliberately slow. */
+	.vp-flash-guard .vp-video {
+		transition-duration: 120ms;
+	}
+
+	.vp-flash-guard .vp-night-layer {
+		transition-duration: 160ms;
+	}
+
+	.vp-stage-wrap {
+		position: relative;
+	}
+
+	/* Bias light: peripheral light, so the blur is large on purpose — any
+	   detail in it reads as a distracting second image. */
+	.vp-bias {
+		position: absolute;
+		inset: -6% -4%;
+		pointer-events: none;
+		background-image: var(--vp-bias-image, none);
+		filter: blur(46px) saturate(1.15);
+		opacity: 0;
+		transition: opacity 1200ms var(--motion-glide, cubic-bezier(0.25, 1, 0.5, 1));
+	}
+
+	.vp-bias.on {
+		opacity: 0.5;
+	}
+
+	/* The surround. On a LIGHT theme a dimmed picture in a white frame makes
+	   the screen-to-surround ratio worse, so the player's own surface is pulled
+	   toward neutral with it (levels.ts surroundLevel — zero on dark themes,
+	   capped well short of dark because text sits here). */
+	.vp-root.vp-night-capable {
+		transition: background-color 900ms var(--motion-glide, cubic-bezier(0.25, 1, 0.5, 1));
+	}
+
+	.vp-root.vp-night-surround {
+		background-color: color-mix(
+			in oklch,
+			var(--color-base-200),
+			var(--color-neutral) calc(var(--vp-night-surround, 0) * 100%)
+		);
+	}
+
+	.vp-times-mid {
+		display: inline-flex;
+		align-items: center;
+		gap: var(--jatui-space-base, 8px);
+	}
+
+	.vp-night-btn {
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
+		background: none;
+		border: none;
+		padding: var(--jatui-space-xs, 2px);
+		border-radius: var(--jatui-radius-field, 0.25rem);
+		color: inherit;
+		cursor: pointer;
+		transition: color var(--motion-move, 300ms) var(--motion-glide, ease-out);
+	}
+
+	.vp-night-btn:hover {
+		color: var(--color-base-content);
+	}
+
+	.vp-night-btn:focus-visible {
+		outline: 2px solid var(--color-primary);
+		outline-offset: 1px;
+	}
+
+	/* Lit in the veil's own warm token while dimming is actually happening. */
+	.vp-night-btn.active {
+		color: var(--color-warning);
+	}
+
+	/* Under reduced motion the veil still dims — the dimming IS the feature —
+	   but the long 900ms/1200ms ramps shrink to a short luminance fade. A
+	   change in brightness is not motion, and a hard step every tick would be
+	   harsher on the eye than the fade it replaced. The strobe guard keeps its
+	   own faster ramp. (The composer also releases brightness a fraction per
+	   tick, so the end of a dim is never a jump back up.) */
+	@media (prefers-reduced-motion: reduce) {
+		.vp-night-capable .vp-video,
+		.vp-night-layer,
+		.vp-bias,
+		.vp-root.vp-night-capable {
+			transition-duration: 150ms;
+		}
+
+		.vp-flash-guard .vp-video {
+			transition-duration: 120ms;
+		}
+
+		.vp-night-btn {
+			transition: none;
+		}
+	}
 </style>