@joewinke/jatui 0.11.0 → 0.13.0

package/dist/video/audio/rider.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Loudness matching — the pure half (mos-5lzns.31). Ported from
+ * extension-library `library.js` §Loudness matching (audioLevel / audioTick)
+ * and FEATURES.md §Loudness matching; every number below is the extension's.
+ *
+ * Shape: a gated RMS estimate of the programme's LOUD level drives a slow,
+ * asymmetric gain rider toward a target. The graph (./graph.ts) feeds this
+ * module the analyser's time-domain buffer every AUDIO_TICK_MS and lands the
+ * returned ride on the gain param; nothing here touches WebAudio.
+ *
+ * Not true LUFS — no K-weighting, no channel weighting. The thing being
+ * corrected is "this video is louder than the last one", and RMS answers that
+ * honestly at a fraction of the cost.
+ */
+/** How often the rider reads the meter. fftSize 2048 is ~46ms at 44.1kHz. */
+export declare const AUDIO_TICK_MS = 200;
+export declare const AUDIO_FFT_SIZE = 2048;
+/** Where matching aims, dBFS RMS. At −20 an ordinary video is left at ~1.0×. */
+export declare const AUDIO_TARGET_DEFAULT = -20;
+export declare const AUDIO_TARGET_MIN = -30;
+export declare const AUDIO_TARGET_MAX = -12;
+/** Below this RMS a window is silence — it carries no vote about level. */
+export declare const SILENCE_RMS = 0.00001;
+/**
+ * The gate is the whole difference between working and shouting. A 46ms
+ * window of speech runs ~−15 dB, the pause between sentences ~−40; driving
+ * gain off the instantaneous level climbs through every gap and blares the
+ * next word. So the estimate only listens to material within GATE_DB of what
+ * it already believes the loud level to be (EBU R128's relative-gate idea).
+ */
+export declare const GATE_DB = 12;
+/** Rise toward a louder reading quickly … */
+export declare const LOUD_RISE = 0.08;
+/** … and forget a quiet one very slowly (a new video does NOT reset it). */
+export declare const LOUD_FORGET = 0.01;
+/**
+ * The clamp. 1.35 is a deliberate ceiling, not a round number: measured
+ * across the extension's library, target −20 leaves normal material at 1.0×,
+ * lifts a quiet podcast by the full +2.6 dB and pulls a hot one down 10 dB.
+ * Matching may rescue a quiet mix by a few dB; it may NOT become an amplifier.
+ */
+export declare const GAIN_MIN = 0.3;
+export declare const GAIN_MAX = 1.35;
+/**
+ * Asymmetric ride — the opposite way round from night dimming: coming DOWN
+ * off something too loud is quick, going up is slow enough to be inaudible.
+ */
+export declare const RIDE_DOWN = 0.15;
+export declare const RIDE_UP = 0.02;
+/** setTargetAtTime constant the ride lands with, so the param smooths between ticks. */
+export declare const RIDE_TAU = 0.25;
+/**
+ * The limiter — the fast half. High ratio, knee 0, fast attack: it does
+ * nothing until something actually peaks. Off moves the threshold to 0 dBFS
+ * rather than rewiring the graph (rewiring a live graph clicks); the move is
+ * RAMPED (LIMITER_TAU), never a `.value` write.
+ *
+ * Not a straight wire on its own: DynamicsCompressorNode applies automatic
+ * makeup gain (see `compressorMakeupDb`) — ~+1.7 dB at −3 dBFS / 20:1 — so the
+ * graph follows the limiter with a trim GainNode at the inverse. Without the
+ * trim, "limiter on" is a 1.7 dB level jump, which is exactly the kind of
+ * trace a feature must not leave.
+ */
+export declare const LIMITER: Readonly<{
+    threshold: -3;
+    knee: 0;
+    ratio: 20;
+    attack: 0.003;
+    release: 0.25;
+}>;
+export declare const LIMITER_OFF_THRESHOLD = 0;
+/** Ramp constant for limiter threshold/trim moves — under an event, over a click. */
+export declare const LIMITER_TAU = 0.15;
+/**
+ * Silence watchdog: a routed element whose analyser reads EXACT zeros for this
+ * long while it is playing, audible, its clock advancing AND with positive
+ * evidence that decoded audio is flowing is reported as silent — the
+ * signature of a source that became CORS-tainted after routing (the node
+ * outputs zeros, never noise). Without that evidence (no audio track, or a
+ * browser that can't tell us) it never fires. Exact digital silence in a real
+ * track (a muted-mic screen recording) can still trip it, which is why the
+ * report asks for a notice, never a remount.
+ */
+export declare const SILENT_AFTER_MS = 4000;
+/**
+ * Short-term RMS of a time-domain buffer, in dBFS. `null` for silence (below
+ * SILENCE_RMS), an empty buffer or junk — never −Infinity, never NaN.
+ */
+export declare function rmsDb(buf: ArrayLike<number> | null | undefined): number | null;
+/**
+ * One step of the gated loud-level estimate. `loud` null means "no estimate
+ * yet" — the first real reading seeds it. A null/junk `level` (silence) leaves
+ * the estimate exactly where it was.
+ */
+export declare function gateLoud(loud: number | null, level: number | null): number | null;
+/** Clamp a target to the declared range; junk falls back to the default. */
+export declare function clampTarget(target: unknown): number;
+/**
+ * The gain that would put the measured loud level at `target`, clamped to
+ * [GAIN_MIN, GAIN_MAX]. No estimate yet ⇒ 1 (neutral): we never guess.
+ */
+export declare function wantGain(loud: number | null, target: unknown): number;
+/** One asymmetric step of the ride toward `want`. Junk in ⇒ neutral 1. */
+export declare function rideStep(ride: number, want: number): number;
+/** A ride as dB — for readouts. 1 ⇒ 0 dB; junk ⇒ 0. */
+export declare function gainDb(ride: number): number;
+/**
+ * DynamicsCompressorNode's automatic makeup gain, dB, for knee 0 — the Web
+ * Audio spec's "makeup gain" step (as Chromium/WebKit/Gecko implement it):
+ * fullRangeGain = the curve's output for a 0 dBFS input, makeup =
+ * (1 / fullRangeGain) ^ 0.6. For knee 0 the curve at 0 dBFS is
+ * threshold + (0 − threshold) / ratio, so the makeup is
+ * 0.6 × (−threshold) × (1 − 1/ratio): +1.71 dB at −3 dBFS / 20:1, 0 at a
+ * 0 dBFS threshold. Junk ⇒ 0.
+ */
+export declare function compressorMakeupDb(threshold: unknown, ratio: unknown): number;
+/** The trim gain (linear) that cancels a limiter's makeup at this threshold. */
+export declare function limiterTrim(threshold: number): number;
+/**
+ * Can this element's audio be routed through WebAudio without going SILENT?
+ *
+ * A media response that isn't CORS-clean makes a MediaElementAudioSourceNode
+ * output zeros — and routing is a one-way door, so that is silence with no
+ * way back. A same-origin URL is NOT enough: it may 302 to a signed storage
+ * URL on another origin (MardukOS file routes do exactly that), and without
+ * `crossorigin` the redirected response is opaque. So:
+ *
+ * · 'ok'   — blob:/data: (never leave the page's origin), or the element asked
+ *            for a CORS load (`crossorigin` set — the load is then CORS-clean
+ *            or it fails outright, never silently).
+ * · 'wait' — no source yet; nothing to decide.
+ * · 'cors' — anything else: refuse, play unprocessed.
+ */
+export declare function routeSafety(mediaUrl: unknown, crossorigin: unknown): 'ok' | 'wait' | 'cors';

package/dist/video/audio/rider.js

@@ -0,0 +1,187 @@
+/**
+ * Loudness matching — the pure half (mos-5lzns.31). Ported from
+ * extension-library `library.js` §Loudness matching (audioLevel / audioTick)
+ * and FEATURES.md §Loudness matching; every number below is the extension's.
+ *
+ * Shape: a gated RMS estimate of the programme's LOUD level drives a slow,
+ * asymmetric gain rider toward a target. The graph (./graph.ts) feeds this
+ * module the analyser's time-domain buffer every AUDIO_TICK_MS and lands the
+ * returned ride on the gain param; nothing here touches WebAudio.
+ *
+ * Not true LUFS — no K-weighting, no channel weighting. The thing being
+ * corrected is "this video is louder than the last one", and RMS answers that
+ * honestly at a fraction of the cost.
+ */
+/** How often the rider reads the meter. fftSize 2048 is ~46ms at 44.1kHz. */
+export const AUDIO_TICK_MS = 200;
+export const AUDIO_FFT_SIZE = 2048;
+/** Where matching aims, dBFS RMS. At −20 an ordinary video is left at ~1.0×. */
+export const AUDIO_TARGET_DEFAULT = -20;
+export const AUDIO_TARGET_MIN = -30;
+export const AUDIO_TARGET_MAX = -12;
+/** Below this RMS a window is silence — it carries no vote about level. */
+export const SILENCE_RMS = 1e-5;
+/**
+ * The gate is the whole difference between working and shouting. A 46ms
+ * window of speech runs ~−15 dB, the pause between sentences ~−40; driving
+ * gain off the instantaneous level climbs through every gap and blares the
+ * next word. So the estimate only listens to material within GATE_DB of what
+ * it already believes the loud level to be (EBU R128's relative-gate idea).
+ */
+export const GATE_DB = 12;
+/** Rise toward a louder reading quickly … */
+export const LOUD_RISE = 0.08;
+/** … and forget a quiet one very slowly (a new video does NOT reset it). */
+export const LOUD_FORGET = 0.01;
+/**
+ * The clamp. 1.35 is a deliberate ceiling, not a round number: measured
+ * across the extension's library, target −20 leaves normal material at 1.0×,
+ * lifts a quiet podcast by the full +2.6 dB and pulls a hot one down 10 dB.
+ * Matching may rescue a quiet mix by a few dB; it may NOT become an amplifier.
+ */
+export const GAIN_MIN = 0.3;
+export const GAIN_MAX = 1.35;
+/**
+ * Asymmetric ride — the opposite way round from night dimming: coming DOWN
+ * off something too loud is quick, going up is slow enough to be inaudible.
+ */
+export const RIDE_DOWN = 0.15;
+export const RIDE_UP = 0.02;
+/** setTargetAtTime constant the ride lands with, so the param smooths between ticks. */
+export const RIDE_TAU = 0.25;
+/**
+ * The limiter — the fast half. High ratio, knee 0, fast attack: it does
+ * nothing until something actually peaks. Off moves the threshold to 0 dBFS
+ * rather than rewiring the graph (rewiring a live graph clicks); the move is
+ * RAMPED (LIMITER_TAU), never a `.value` write.
+ *
+ * Not a straight wire on its own: DynamicsCompressorNode applies automatic
+ * makeup gain (see `compressorMakeupDb`) — ~+1.7 dB at −3 dBFS / 20:1 — so the
+ * graph follows the limiter with a trim GainNode at the inverse. Without the
+ * trim, "limiter on" is a 1.7 dB level jump, which is exactly the kind of
+ * trace a feature must not leave.
+ */
+export const LIMITER = Object.freeze({
+    threshold: -3,
+    knee: 0,
+    ratio: 20,
+    attack: 0.003,
+    release: 0.25
+});
+export const LIMITER_OFF_THRESHOLD = 0;
+/** Ramp constant for limiter threshold/trim moves — under an event, over a click. */
+export const LIMITER_TAU = 0.15;
+/**
+ * Silence watchdog: a routed element whose analyser reads EXACT zeros for this
+ * long while it is playing, audible, its clock advancing AND with positive
+ * evidence that decoded audio is flowing is reported as silent — the
+ * signature of a source that became CORS-tainted after routing (the node
+ * outputs zeros, never noise). Without that evidence (no audio track, or a
+ * browser that can't tell us) it never fires. Exact digital silence in a real
+ * track (a muted-mic screen recording) can still trip it, which is why the
+ * report asks for a notice, never a remount.
+ */
+export const SILENT_AFTER_MS = 4000;
+const finite = (n) => typeof n === 'number' && Number.isFinite(n);
+/**
+ * Short-term RMS of a time-domain buffer, in dBFS. `null` for silence (below
+ * SILENCE_RMS), an empty buffer or junk — never −Infinity, never NaN.
+ */
+export function rmsDb(buf) {
+    if (!buf || !(buf.length > 0))
+        return null;
+    let sum = 0;
+    for (let i = 0; i < buf.length; i++) {
+        const s = buf[i];
+        if (!finite(s))
+            return null;
+        sum += s * s;
+    }
+    const rms = Math.sqrt(sum / buf.length);
+    if (!(rms >= SILENCE_RMS))
+        return null;
+    return 20 * Math.log10(rms);
+}
+/**
+ * One step of the gated loud-level estimate. `loud` null means "no estimate
+ * yet" — the first real reading seeds it. A null/junk `level` (silence) leaves
+ * the estimate exactly where it was.
+ */
+export function gateLoud(loud, level) {
+    if (!finite(level))
+        return finite(loud) ? loud : null;
+    if (!finite(loud))
+        return level;
+    if (level > loud - GATE_DB) {
+        return loud + (level - loud) * (level > loud ? LOUD_RISE : LOUD_FORGET);
+    }
+    return loud;
+}
+/** Clamp a target to the declared range; junk falls back to the default. */
+export function clampTarget(target) {
+    if (!finite(target))
+        return AUDIO_TARGET_DEFAULT;
+    return Math.min(AUDIO_TARGET_MAX, Math.max(AUDIO_TARGET_MIN, target));
+}
+/**
+ * The gain that would put the measured loud level at `target`, clamped to
+ * [GAIN_MIN, GAIN_MAX]. No estimate yet ⇒ 1 (neutral): we never guess.
+ */
+export function wantGain(loud, target) {
+    if (!finite(loud))
+        return 1;
+    const want = Math.pow(10, (clampTarget(target) - loud) / 20);
+    return Math.min(GAIN_MAX, Math.max(GAIN_MIN, want));
+}
+/** One asymmetric step of the ride toward `want`. Junk in ⇒ neutral 1. */
+export function rideStep(ride, want) {
+    const r = finite(ride) ? ride : 1;
+    if (!finite(want))
+        return r;
+    return r + (want - r) * (want < r ? RIDE_DOWN : RIDE_UP);
+}
+/** A ride as dB — for readouts. 1 ⇒ 0 dB; junk ⇒ 0. */
+export function gainDb(ride) {
+    return finite(ride) && ride > 0 ? 20 * Math.log10(ride) : 0;
+}
+/**
+ * DynamicsCompressorNode's automatic makeup gain, dB, for knee 0 — the Web
+ * Audio spec's "makeup gain" step (as Chromium/WebKit/Gecko implement it):
+ * fullRangeGain = the curve's output for a 0 dBFS input, makeup =
+ * (1 / fullRangeGain) ^ 0.6. For knee 0 the curve at 0 dBFS is
+ * threshold + (0 − threshold) / ratio, so the makeup is
+ * 0.6 × (−threshold) × (1 − 1/ratio): +1.71 dB at −3 dBFS / 20:1, 0 at a
+ * 0 dBFS threshold. Junk ⇒ 0.
+ */
+export function compressorMakeupDb(threshold, ratio) {
+    if (!finite(threshold) || !finite(ratio) || ratio < 1 || threshold >= 0)
+        return 0;
+    return 0.6 * -threshold * (1 - 1 / ratio);
+}
+/** The trim gain (linear) that cancels a limiter's makeup at this threshold. */
+export function limiterTrim(threshold) {
+    return Math.pow(10, -compressorMakeupDb(threshold, LIMITER.ratio) / 20);
+}
+/**
+ * Can this element's audio be routed through WebAudio without going SILENT?
+ *
+ * A media response that isn't CORS-clean makes a MediaElementAudioSourceNode
+ * output zeros — and routing is a one-way door, so that is silence with no
+ * way back. A same-origin URL is NOT enough: it may 302 to a signed storage
+ * URL on another origin (MardukOS file routes do exactly that), and without
+ * `crossorigin` the redirected response is opaque. So:
+ *
+ * · 'ok'   — blob:/data: (never leave the page's origin), or the element asked
+ *            for a CORS load (`crossorigin` set — the load is then CORS-clean
+ *            or it fails outright, never silently).
+ * · 'wait' — no source yet; nothing to decide.
+ * · 'cors' — anything else: refuse, play unprocessed.
+ */
+export function routeSafety(mediaUrl, crossorigin) {
+    if (typeof mediaUrl !== 'string' || mediaUrl === '')
+        return 'wait';
+    if (crossorigin === 'anonymous' || crossorigin === 'use-credentials' || crossorigin === '') {
+        return 'ok';
+    }
+    return /^(blob|data):/i.test(mediaUrl.trim()) ? 'ok' : 'cors';
+}

package/dist/video/audio.d.ts

@@ -1,29 +1,40 @@
 /**
- * Audio module — CONTRACT ONLY (mos-5lzns.28). Implemented by mos-5lzns.31
- * ("audio graph — loudness matching, quiet listening, limiter").
+ * Audio module (mos-5lzns.31) — loudness matching, quiet listening, limiter.
+ * Ported from extension-library FEATURES.md §Loudness matching, §Quiet
+ * listening (library.js audioEnsure / audioTick / applyAudioSettings).
  *
- * What lands here (extension-library FEATURES.md §Loudness matching,
- * §Quiet listening), as ADVISORS + an audio graph builder:
+ * Layout:
  *
- * · loudness matching — a gated RMS meter drives a slow gain rider toward a
- *   target (~−20 dB). The gate forgets slowly so a new video doesn't reset
- *   the meter mid-lesson; the correction is measured, not a strength slider.
- * · quiet listening — loudness-compensated tone (two shelves + presence
- *   peak + gentle compressor), amount rising as volume drops, a floor after
- *   dark. Amount 0 rebuilds nothing: splicing a live graph mid-playback
- *   clicks — a constant few ms of silence is the trade.
- * · limiter — threshold −3 dBFS, catching what the slow rider cannot.
+ * · audio/rider.ts — pure, node-testable: short-term RMS in dBFS, the gated
+ *   loud-level estimate (12 dB relative gate, rise 0.08 / forget 0.01), the
+ *   clamped want-gain (0.3–1.35), the asymmetric ride (down 0.15 / up 0.02),
+ *   the limiter constants + `compressorMakeupDb`/`limiterTrim` (the
+ *   compressor's automatic makeup gain, cancelled by a trim node), and
+ *   `routeSafety` (only blob:/data: or a `crossorigin` load may be routed).
+ * · audio/graph.ts — `createAudioSession`, the graph builder + its state
+ *   machine: source → gain → quiet chain (advisors/quiet-listening) →
+ *   limiter → trim → destination, analyser tapping the source. Context
+ *   first, route last: the element is taken only once a feature is on, the
+ *   source is route-safe AND the context is `running`; gestures retry. After
+ *   routing, an unsafe src or bit-exact silence is reported `broken`. A
+ *   construction failure is a permanent `broken` that still plays plain
+ *   audio. Disabled = no trace on the param timeline.
  *
  * Module rules (README): no <video> access, no settings reads, no DOM. The
- * graph builder is the one exception that may touch AudioContext — it takes
- * a MediaElementAudioSourceNode the component creates, never the element.
- * Disabled ⇒ the graph is bypassed entirely: no residual filter, no half
- * ramp, no stale param (cancelScheduledValues before restoring). Off must be
- * indistinguishable from never having run.
+ * graph is the one exception that touches AudioContext — and even it never
+ * sees the element: the component passes a `context()` factory and a
+ * `route(ctx)` closure that calls createMediaElementSource.
+ *
+ * ⚠ CORS: WebAudio outputs SILENCE for a source that isn't CORS-clean — and
+ * a same-origin URL may redirect to one. The host must serve the media with
+ * Access-Control-Allow-Origin and pass `crossorigin="anonymous"` (or use a
+ * blob:/data: src); otherwise the player refuses to route (status 'cors')
+ * and plays the audio unprocessed.
  */
 /**
  * Neutral advisor product — the multiplicative identity every composer and
- * caller must get when audio correction is off or unmeasured. Exported so
- * .31's rate-relevant advisors (if any) share the exact collapse value.
+ * caller must get when audio correction is off or unmeasured.
  */
 export declare const AUDIO_NEUTRAL = 1;
+export * from './audio/rider';
+export * from './audio/graph';

package/dist/video/audio.js

@@ -1,29 +1,40 @@
 /**
- * Audio module — CONTRACT ONLY (mos-5lzns.28). Implemented by mos-5lzns.31
- * ("audio graph — loudness matching, quiet listening, limiter").
+ * Audio module (mos-5lzns.31) — loudness matching, quiet listening, limiter.
+ * Ported from extension-library FEATURES.md §Loudness matching, §Quiet
+ * listening (library.js audioEnsure / audioTick / applyAudioSettings).
  *
- * What lands here (extension-library FEATURES.md §Loudness matching,
- * §Quiet listening), as ADVISORS + an audio graph builder:
+ * Layout:
  *
- * · loudness matching — a gated RMS meter drives a slow gain rider toward a
- *   target (~−20 dB). The gate forgets slowly so a new video doesn't reset
- *   the meter mid-lesson; the correction is measured, not a strength slider.
- * · quiet listening — loudness-compensated tone (two shelves + presence
- *   peak + gentle compressor), amount rising as volume drops, a floor after
- *   dark. Amount 0 rebuilds nothing: splicing a live graph mid-playback
- *   clicks — a constant few ms of silence is the trade.
- * · limiter — threshold −3 dBFS, catching what the slow rider cannot.
+ * · audio/rider.ts — pure, node-testable: short-term RMS in dBFS, the gated
+ *   loud-level estimate (12 dB relative gate, rise 0.08 / forget 0.01), the
+ *   clamped want-gain (0.3–1.35), the asymmetric ride (down 0.15 / up 0.02),
+ *   the limiter constants + `compressorMakeupDb`/`limiterTrim` (the
+ *   compressor's automatic makeup gain, cancelled by a trim node), and
+ *   `routeSafety` (only blob:/data: or a `crossorigin` load may be routed).
+ * · audio/graph.ts — `createAudioSession`, the graph builder + its state
+ *   machine: source → gain → quiet chain (advisors/quiet-listening) →
+ *   limiter → trim → destination, analyser tapping the source. Context
+ *   first, route last: the element is taken only once a feature is on, the
+ *   source is route-safe AND the context is `running`; gestures retry. After
+ *   routing, an unsafe src or bit-exact silence is reported `broken`. A
+ *   construction failure is a permanent `broken` that still plays plain
+ *   audio. Disabled = no trace on the param timeline.
  *
  * Module rules (README): no <video> access, no settings reads, no DOM. The
- * graph builder is the one exception that may touch AudioContext — it takes
- * a MediaElementAudioSourceNode the component creates, never the element.
- * Disabled ⇒ the graph is bypassed entirely: no residual filter, no half
- * ramp, no stale param (cancelScheduledValues before restoring). Off must be
- * indistinguishable from never having run.
+ * graph is the one exception that touches AudioContext — and even it never
+ * sees the element: the component passes a `context()` factory and a
+ * `route(ctx)` closure that calls createMediaElementSource.
+ *
+ * ⚠ CORS: WebAudio outputs SILENCE for a source that isn't CORS-clean — and
+ * a same-origin URL may redirect to one. The host must serve the media with
+ * Access-Control-Allow-Origin and pass `crossorigin="anonymous"` (or use a
+ * blob:/data: src); otherwise the player refuses to route (status 'cors')
+ * and plays the audio unprocessed.
  */
 /**
  * Neutral advisor product — the multiplicative identity every composer and
- * caller must get when audio correction is off or unmeasured. Exported so
- * .31's rate-relevant advisors (if any) share the exact collapse value.
+ * caller must get when audio correction is off or unmeasured.
  */
 export const AUDIO_NEUTRAL = 1;
+export * from './audio/rider';
+export * from './audio/graph';

package/dist/video/keys.d.ts

@@ -7,10 +7,10 @@
  * Space play/pause, ←/→ seek, ↑/↓ volume, M mute, −/= speed, Backspace reset
  * speed, </> frame step, [/] chapter jumps, B bookmark, T transcript, ?
  * shortcuts, Home/End. Deliberately NOT ported: F/M (favourite/file-under —
- * library-app verbs, not player verbs), N (night cycle — no night module
- * until mos-5lzns.33; add it THERE, with its own row here), `,` (settings —
+ * library-app verbs, not player verbs), `,` (settings —
  * jatui is prop-driven; a settings module arrives with the features that need
- * one), `/` (transcript search — the pane has none yet).
+ * one), `/` (transcript search — the pane has none yet). N (night cycle)
+ * landed with the night module (mos-5lzns.33), gated on the host opting in.
  */
 export interface PlayerKeyRow {
     /** Keycap label as shown in the help overlay — `/`-separated alternates. */
@@ -20,7 +20,7 @@ export interface PlayerKeyRow {
      * Availability gate: the row is only advertised (and the key only bound)
      * when the feature's data exists. Undefined ⇒ always active.
      */
-    when?: 'chapters' | 'bookmarks' | 'transcript' | 'comments';
+    when?: 'chapters' | 'bookmarks' | 'transcript' | 'comments' | 'night';
 }
 /** Order follows the help overlay: transport, seek, volume, speed, structure. */
 export declare const PLAYER_KEYS: PlayerKeyRow[];

package/dist/video/keys.js

@@ -7,10 +7,10 @@
  * Space play/pause, ←/→ seek, ↑/↓ volume, M mute, −/= speed, Backspace reset
  * speed, </> frame step, [/] chapter jumps, B bookmark, T transcript, ?
  * shortcuts, Home/End. Deliberately NOT ported: F/M (favourite/file-under —
- * library-app verbs, not player verbs), N (night cycle — no night module
- * until mos-5lzns.33; add it THERE, with its own row here), `,` (settings —
+ * library-app verbs, not player verbs), `,` (settings —
  * jatui is prop-driven; a settings module arrives with the features that need
- * one), `/` (transcript search — the pane has none yet).
+ * one), `/` (transcript search — the pane has none yet). N (night cycle)
+ * landed with the night module (mos-5lzns.33), gated on the host opting in.
  */
 /** Order follows the help overlay: transport, seek, volume, speed, structure. */
 export const PLAYER_KEYS = [
@@ -28,6 +28,7 @@ export const PLAYER_KEYS = [
     { keys: '{ / }', description: 'Previous / next comment', when: 'comments' },
     { keys: 'B', description: 'Bookmark at the current time', when: 'bookmarks' },
     { keys: 'T', description: 'Show / hide the transcript', when: 'transcript' },
+    { keys: 'N', description: 'Night dimming: auto / on / off', when: 'night' },
     { keys: 'Home / End', description: 'Jump to start / end' },
     { keys: '?', description: 'Toggle this help' }
 ];

package/dist/video/night/clock.d.ts

@@ -0,0 +1,31 @@
+/**
+ * What arms night dimming (mos-5lzns.33).
+ *
+ * The extension asked the desktop (hyprsunset's colour temperature) and fell
+ * back to the clock. A component in a web app has no desktop to ask, so the
+ * signal is re-based (docs/videos-module-viability.md §6): the LOCAL clock,
+ * plus a manual toggle. `prefers-color-scheme: dark` can only WIDEN the
+ * window (18:00–08:00 instead of 20:00–07:00), never be the trigger — a lot
+ * of desktops report dark around the clock.
+ *
+ * `N` cycles auto → on → off. `auto` follows the clock; `on` ignores it;
+ * `off` leaves no trace.
+ */
+export type NightMode = 'auto' | 'on' | 'off';
+export declare const NIGHT_MODES: readonly NightMode[];
+export interface NightWindow {
+    /** Hour (0–24, fractional ok) the night starts. */
+    from: number;
+    /** Hour the night ends (next morning when < from). */
+    to: number;
+}
+export declare const NIGHT_WINDOW: Readonly<NightWindow>;
+export declare const NIGHT_WINDOW_DARK: Readonly<NightWindow>;
+/** Any unknown mode is treated as off — a bad value must never switch dimming ON. */
+export declare function coerceNightMode(mode: unknown): NightMode;
+export declare function nextNightMode(mode: unknown): NightMode;
+/** Is `date` inside the night window? Handles windows that wrap midnight (and ones that don't). */
+export declare function inNightWindow(date: Date, prefersDark?: boolean, win?: NightWindow | null): boolean;
+export declare function nightArmed(mode: unknown, date: Date, prefersDark?: boolean, win?: NightWindow | null): boolean;
+/** The OSD / aria text for a mode, as the user will read it. */
+export declare function nightModeLabel(mode: unknown, armed: boolean): string;

package/dist/video/night/clock.js

@@ -0,0 +1,58 @@
+/**
+ * What arms night dimming (mos-5lzns.33).
+ *
+ * The extension asked the desktop (hyprsunset's colour temperature) and fell
+ * back to the clock. A component in a web app has no desktop to ask, so the
+ * signal is re-based (docs/videos-module-viability.md §6): the LOCAL clock,
+ * plus a manual toggle. `prefers-color-scheme: dark` can only WIDEN the
+ * window (18:00–08:00 instead of 20:00–07:00), never be the trigger — a lot
+ * of desktops report dark around the clock.
+ *
+ * `N` cycles auto → on → off. `auto` follows the clock; `on` ignores it;
+ * `off` leaves no trace.
+ */
+export const NIGHT_MODES = ['auto', 'on', 'off'];
+export const NIGHT_WINDOW = Object.freeze({ from: 20, to: 7 });
+export const NIGHT_WINDOW_DARK = Object.freeze({ from: 18, to: 8 });
+/** Any unknown mode is treated as off — a bad value must never switch dimming ON. */
+export function coerceNightMode(mode) {
+    return mode === 'auto' || mode === 'on' || mode === 'off' ? mode : 'off';
+}
+export function nextNightMode(mode) {
+    const m = coerceNightMode(mode);
+    return NIGHT_MODES[(NIGHT_MODES.indexOf(m) + 1) % NIGHT_MODES.length];
+}
+/** Is `date` inside the night window? Handles windows that wrap midnight (and ones that don't). */
+export function inNightWindow(date, prefersDark = false, win) {
+    const t = date instanceof Date ? date.getTime() : NaN;
+    if (!Number.isFinite(t))
+        return false;
+    const w = validWindow(win) ?? (prefersDark ? NIGHT_WINDOW_DARK : NIGHT_WINDOW);
+    const h = date.getHours() + date.getMinutes() / 60;
+    if (w.from === w.to)
+        return false;
+    return w.from > w.to ? h >= w.from || h < w.to : h >= w.from && h < w.to;
+}
+export function nightArmed(mode, date, prefersDark = false, win) {
+    const m = coerceNightMode(mode);
+    if (m === 'on')
+        return true;
+    if (m === 'off')
+        return false;
+    return inNightWindow(date, prefersDark, win);
+}
+/** The OSD / aria text for a mode, as the user will read it. */
+export function nightModeLabel(mode, armed) {
+    const m = coerceNightMode(mode);
+    if (m === 'on')
+        return 'Night · always on';
+    if (m === 'off')
+        return 'Night · off';
+    return armed ? 'Night · auto, dimming now' : 'Night · auto, until dark';
+}
+function validWindow(w) {
+    if (!w)
+        return null;
+    const ok = (h) => typeof h === 'number' && Number.isFinite(h) && h >= 0 && h <= 24;
+    return ok(w.from) && ok(w.to) ? { from: w.from, to: w.to } : null;
+}