@joewinke/jatui 0.11.0 → 0.12.0

package/dist/video/README.md

@@ -21,7 +21,7 @@ props + callback surfaces.
 | `deepLink.ts` | .28 (done) | `?t=` parse/format/read/write (replaceState, throttled, other params preserved). |
 | `settings.ts` | shared — knobs added by .30–.34 | `coerce` (never throws, never junk) + `VIDEO_SETTINGS` registry. A knob lands WITH its reader. |
 | `audio.ts` | **.31** | Loudness matching, quiet listening, limiter — audio-graph contract is in the file header. |
-| `night.ts` | **.33** | Night dimming, bias light, predictive dimming (luma track), strobe guard. |
+| `night.ts` + `night/` | **.33** (done) | `night.ts` is the barrel. `meter.ts` — 32×18 frame bytes → Rec.709 luma + blown share, asymmetric smoothing, bias-light cells from the same bytes. `levels.ts` — luma → brightness/saturation/warmth/vignette off `NIGHT_FLOOR` 0.34, blind fixed level, the light-theme surround. `clock.ts` — local-clock `auto` window + the `N` auto/on/off cycle (no hyprsunset). `track.ts` — prediction (only ever adds dimming), flash intervals, `composeNight` (darker at once, brighter released per tick — never a jump). |
 | `presence.ts` | **.34** | Wind-down (Idle Detection), resume-at-sentence, FLIP open. |
 | `advisors/` | **.27 (done)** | The five extension-library pure advisors, ported verbatim: `smart-speed` (silence map + boost), `speaker-rate` (measured wpm + suggested rates), `resume-point` (sentence-snapping + the label), `quiet-listening` (tone-only chain + `amountFor`), `qr` (ISO 18004 encoder v1–10). Each has its own README row in `advisors/README.md`; the `--self-test` suites live on as vitest in `tests/unit/advisors/` (`npm run test:advisors`). |
 

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

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

@@ -0,0 +1,78 @@
+/**
+ * Scene luma → the night layers (mos-5lzns.33).
+ *
+ * extension-library FEATURES.md §Night dimming, `nightLevels()`: everything
+ * scales off `over` — how far past NIGHT_FLOOR the frame is — eased `over^0.75`
+ * so the first bit of brightness barely registers and the last bit lands hard.
+ *
+ * | level  | formula          | layer                                             |
+ * |--------|------------------|---------------------------------------------------|
+ * | bright | 1 − 0.5·d·e      | `filter: brightness()` on the video itself        |
+ * | sat    | 1 − 0.18·d·e     | `saturate()` — bright AND loud is what stings     |
+ * | warm   | d·(0.1 + 0.24·e) | warm pane, `mix-blend-mode: multiply`             |
+ * | vig    | d·(0.2 + 0.34·e) | soft vignette, multiply                           |
+ *
+ * Every layer MULTIPLIES. A grey scrim on top raises the black point (blacks
+ * go grey, the picture fogs); multiplying by a warm colour leaves red intact
+ * and takes most of the blue. Blacks stay black.
+ *
+ * The strobe guard uses the `bright`/`sat` half only (`guardLevels`), at a
+ * FIXED depth of 1 whatever the night dial says: it is a photosensitivity
+ * guard, not night — it has no business warming the picture, and a comfort
+ * setting must never weaken it.
+ */
+/** Scenes dimmer than this are already easy on the eye; touching them is correction for its own sake. */
+export declare const NIGHT_FLOOR = 0.34;
+/** Depth 1 takes a full-white frame to about half brightness — lamp-in-a-dark-room. */
+export declare const NIGHT_DEPTH_MIN = 0.2;
+export declare const NIGHT_DEPTH_MAX = 1;
+export declare const NIGHT_DEPTH_DEFAULT = 0.7;
+export declare const NIGHT_DEPTH_STEP = 0.1;
+/** Frame readback refused (tainted canvas) ⇒ run on this fixed level: dimming without a meter beats a white wall at 1am. */
+export declare const NIGHT_BLIND_LUMA = 0.62;
+export interface NightLevels {
+    bright: number;
+    sat: number;
+    warm: number;
+    vig: number;
+}
+export declare const NIGHT_NEUTRAL_LEVELS: Readonly<NightLevels>;
+/** Clamp a depth knob; garbage ⇒ the default (never a junk level). */
+export declare function clampDepth(depth: unknown): number;
+/** One wheel/keyboard notch on the depth dial, rounded so repeated nudges don't drift. */
+export declare function nudgeDepth(depth: unknown, dir: number): number;
+/** 0 at/below the floor, eased toward 1 at full white. */
+export declare function nightExcess(luma: number): number;
+export declare function nightLevels(luma: number, depth: number): NightLevels;
+/**
+ * The strobe guard's depth. FIXED at the dial's maximum and deliberately NOT
+ * the user's night depth: the dial is a comfort setting, the guard is a
+ * photosensitivity protection, and turning comfort down must never weaken it.
+ */
+export declare const GUARD_DEPTH = 1;
+/** The strobe guard's half: the level drop only, always at GUARD_DEPTH. No warmth, no vignette. */
+export declare function guardLevels(luma: number): NightLevels;
+/** Per-channel strongest of two level sets — the guard and night stack, the deeper one wins. */
+export declare function deeperLevels(a: NightLevels, b: NightLevels): NightLevels;
+/** True when a set of levels would change no pixel — the caller then removes every trace. */
+export declare function isNeutral(L: NightLevels, eps?: number): boolean;
+/**
+ * The surround — the player's own chrome around the picture.
+ *
+ * The extension's page layer assumed a dark app: dim the video and the room
+ * gets easier. On a LIGHT theme the player sits on a near-white surface, so
+ * dimming only the picture makes the screen-to-surround ratio WORSE — a
+ * dimmed video in a white frame. So on a light surface the surround is pulled
+ * toward the theme's neutral in proportion to how light it is and how deep
+ * the dial is; on a dark surface it is left alone (it is already the room).
+ *
+ * `surfaceLuma` is the surround colour's relative luminance, 0–1 (the
+ * component resolves it from the theme token). Returns the mix fraction
+ * (0 … SURROUND_MAX) toward neutral. Capped well short of dark: text sits on
+ * this surface, and after dark contrast is the one thing you still have.
+ */
+export declare const SURROUND_FROM = 0.35;
+export declare const SURROUND_MAX = 0.3;
+export declare function surroundLevel(surfaceLuma: number, depth: number): number;
+/** Relative luminance (sRGB → linear, Rec.709 weights) of 0–255 channels. */
+export declare function relativeLuminance(r: number, g: number, b: number): number;

package/dist/video/night/levels.js

@@ -0,0 +1,117 @@
+/**
+ * Scene luma → the night layers (mos-5lzns.33).
+ *
+ * extension-library FEATURES.md §Night dimming, `nightLevels()`: everything
+ * scales off `over` — how far past NIGHT_FLOOR the frame is — eased `over^0.75`
+ * so the first bit of brightness barely registers and the last bit lands hard.
+ *
+ * | level  | formula          | layer                                             |
+ * |--------|------------------|---------------------------------------------------|
+ * | bright | 1 − 0.5·d·e      | `filter: brightness()` on the video itself        |
+ * | sat    | 1 − 0.18·d·e     | `saturate()` — bright AND loud is what stings     |
+ * | warm   | d·(0.1 + 0.24·e) | warm pane, `mix-blend-mode: multiply`             |
+ * | vig    | d·(0.2 + 0.34·e) | soft vignette, multiply                           |
+ *
+ * Every layer MULTIPLIES. A grey scrim on top raises the black point (blacks
+ * go grey, the picture fogs); multiplying by a warm colour leaves red intact
+ * and takes most of the blue. Blacks stay black.
+ *
+ * The strobe guard uses the `bright`/`sat` half only (`guardLevels`), at a
+ * FIXED depth of 1 whatever the night dial says: it is a photosensitivity
+ * guard, not night — it has no business warming the picture, and a comfort
+ * setting must never weaken it.
+ */
+/** Scenes dimmer than this are already easy on the eye; touching them is correction for its own sake. */
+export const NIGHT_FLOOR = 0.34;
+/** Depth 1 takes a full-white frame to about half brightness — lamp-in-a-dark-room. */
+export const NIGHT_DEPTH_MIN = 0.2;
+export const NIGHT_DEPTH_MAX = 1;
+export const NIGHT_DEPTH_DEFAULT = 0.7;
+export const NIGHT_DEPTH_STEP = 0.1;
+/** Frame readback refused (tainted canvas) ⇒ run on this fixed level: dimming without a meter beats a white wall at 1am. */
+export const NIGHT_BLIND_LUMA = 0.62;
+export const NIGHT_NEUTRAL_LEVELS = Object.freeze({ bright: 1, sat: 1, warm: 0, vig: 0 });
+/** Clamp a depth knob; garbage ⇒ the default (never a junk level). */
+export function clampDepth(depth) {
+    const d = typeof depth === 'number' ? depth : Number(depth);
+    if (!Number.isFinite(d))
+        return NIGHT_DEPTH_DEFAULT;
+    return Math.min(NIGHT_DEPTH_MAX, Math.max(NIGHT_DEPTH_MIN, d));
+}
+/** One wheel/keyboard notch on the depth dial, rounded so repeated nudges don't drift. */
+export function nudgeDepth(depth, dir) {
+    const step = dir > 0 ? NIGHT_DEPTH_STEP : dir < 0 ? -NIGHT_DEPTH_STEP : 0;
+    return clampDepth(+(clampDepth(depth) + step).toFixed(2));
+}
+/** 0 at/below the floor, eased toward 1 at full white. */
+export function nightExcess(luma) {
+    if (!Number.isFinite(luma))
+        return 0;
+    const over = Math.max(0, Math.min(1, luma) - NIGHT_FLOOR) / (1 - NIGHT_FLOOR);
+    return Math.pow(over, 0.75);
+}
+export function nightLevels(luma, depth) {
+    const e = nightExcess(luma);
+    const d = clampDepth(depth);
+    return {
+        bright: 1 - 0.5 * d * e,
+        sat: 1 - 0.18 * d * e,
+        warm: d * (0.1 + 0.24 * e),
+        vig: d * (0.2 + 0.34 * e)
+    };
+}
+/**
+ * The strobe guard's depth. FIXED at the dial's maximum and deliberately NOT
+ * the user's night depth: the dial is a comfort setting, the guard is a
+ * photosensitivity protection, and turning comfort down must never weaken it.
+ */
+export const GUARD_DEPTH = 1;
+/** The strobe guard's half: the level drop only, always at GUARD_DEPTH. No warmth, no vignette. */
+export function guardLevels(luma) {
+    const L = nightLevels(luma, GUARD_DEPTH);
+    return { bright: L.bright, sat: L.sat, warm: 0, vig: 0 };
+}
+/** Per-channel strongest of two level sets — the guard and night stack, the deeper one wins. */
+export function deeperLevels(a, b) {
+    return {
+        bright: Math.min(a.bright, b.bright),
+        sat: Math.min(a.sat, b.sat),
+        warm: Math.max(a.warm, b.warm),
+        vig: Math.max(a.vig, b.vig)
+    };
+}
+/** True when a set of levels would change no pixel — the caller then removes every trace. */
+export function isNeutral(L, eps = 0.001) {
+    return (Math.abs(L.bright - 1) < eps && Math.abs(L.sat - 1) < eps && L.warm < eps && L.vig < eps);
+}
+/**
+ * The surround — the player's own chrome around the picture.
+ *
+ * The extension's page layer assumed a dark app: dim the video and the room
+ * gets easier. On a LIGHT theme the player sits on a near-white surface, so
+ * dimming only the picture makes the screen-to-surround ratio WORSE — a
+ * dimmed video in a white frame. So on a light surface the surround is pulled
+ * toward the theme's neutral in proportion to how light it is and how deep
+ * the dial is; on a dark surface it is left alone (it is already the room).
+ *
+ * `surfaceLuma` is the surround colour's relative luminance, 0–1 (the
+ * component resolves it from the theme token). Returns the mix fraction
+ * (0 … SURROUND_MAX) toward neutral. Capped well short of dark: text sits on
+ * this surface, and after dark contrast is the one thing you still have.
+ */
+export const SURROUND_FROM = 0.35;
+export const SURROUND_MAX = 0.3;
+export function surroundLevel(surfaceLuma, depth) {
+    if (!Number.isFinite(surfaceLuma) || surfaceLuma <= SURROUND_FROM)
+        return 0;
+    const light = Math.min(1, (surfaceLuma - SURROUND_FROM) / (1 - SURROUND_FROM));
+    return SURROUND_MAX * clampDepth(depth) * light;
+}
+/** Relative luminance (sRGB → linear, Rec.709 weights) of 0–255 channels. */
+export function relativeLuminance(r, g, b) {
+    const lin = (c) => {
+        const s = Math.max(0, Math.min(255, Number.isFinite(c) ? c : 0)) / 255;
+        return s <= 0.04045 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+    };
+    return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+}

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

@@ -0,0 +1,53 @@
+/**
+ * The night meter + bias-light sampler (mos-5lzns.33) — pixel math only.
+ *
+ * extension-library FEATURES.md §Night dimming / §Bias light. The component
+ * draws the current frame into a NIGHT_W × NIGHT_H canvas (576 px — an
+ * average does not get truer with more pixels, it just gets hotter) and hands
+ * the RGBA bytes here. This module never sees the <video> or the canvas: it
+ * takes an array of bytes and returns numbers, so it is node-testable and a
+ * tainted canvas is the COMPONENT's problem to escalate (getImageData throws
+ * there, before anything reaches this file).
+ *
+ * Bias light reads the SAME bytes the meter just read. That is the
+ * extension's hard-won rule: the sampler's canvas is only meaningful right
+ * after a fresh draw — read it any other time and it is empty, and an empty
+ * canvas reads as pitch black, which kills the glow.
+ */
+export declare const NIGHT_W = 32;
+export declare const NIGHT_H = 18;
+/** A pixel brighter than this counts as blown out. */
+export declare const BLOWN_AT = 0.82;
+/** How much say the blown-out share gets on top of the mean. */
+export declare const BLOWN_WEIGHT = 0.25;
+/** Smoothing: bright arrives fast (it is the thing that hurts)… */
+export declare const METER_ATTACK = 0.5;
+/** …and releases slowly, so a dark cut inside a bright video does not flash the level back up. */
+export declare const METER_RELEASE = 0.12;
+/** The meter's resting value before the first reading (extension parity). */
+export declare const METER_START = 0.55;
+/** Colour push for bias cells: an average is always muddier than the scene it came from. */
+export declare const BIAS_SATURATE = 1.6;
+type Bytes = ArrayLike<number>;
+/**
+ * Rec.709 mean luma of an RGBA byte array, plus a term for the blown-out
+ * share: `min(1, mean + blownShare × 0.25)`. The mean alone under-reads the
+ * case that actually hurts — a dark page with one white pane in it.
+ * Returns null for anything that is not a whole number of RGBA pixels.
+ */
+export declare function frameLuma(px: Bytes | null | undefined): number | null;
+/** One asymmetric smoothing step. A null/garbage reading leaves the value where it was. */
+export declare function smoothMeter(prev: number, reading: number | null | undefined): number;
+/**
+ * Nine cells (3×3, row-major) of the frame's own colours, each pushed toward
+ * saturation: `mean + (channel − mean) × 1.6`. A grey halo behind a video
+ * reads as fog, not light. Returns null on a buffer that does not match w×h.
+ */
+export declare function biasCells(px: Bytes | null | undefined, w?: number, h?: number): Array<[number, number, number]> | null;
+/**
+ * The glow as one CSS background-image: eight radial gradients (every cell
+ * but the centre, which the video itself covers). These rgb() values are the
+ * FRAME's colours — data, like a speaker hue — not theme colours.
+ */
+export declare function biasGradient(cells: Array<[number, number, number]> | null | undefined): string;
+export {};

package/dist/video/night/meter.js

@@ -0,0 +1,115 @@
+/**
+ * The night meter + bias-light sampler (mos-5lzns.33) — pixel math only.
+ *
+ * extension-library FEATURES.md §Night dimming / §Bias light. The component
+ * draws the current frame into a NIGHT_W × NIGHT_H canvas (576 px — an
+ * average does not get truer with more pixels, it just gets hotter) and hands
+ * the RGBA bytes here. This module never sees the <video> or the canvas: it
+ * takes an array of bytes and returns numbers, so it is node-testable and a
+ * tainted canvas is the COMPONENT's problem to escalate (getImageData throws
+ * there, before anything reaches this file).
+ *
+ * Bias light reads the SAME bytes the meter just read. That is the
+ * extension's hard-won rule: the sampler's canvas is only meaningful right
+ * after a fresh draw — read it any other time and it is empty, and an empty
+ * canvas reads as pitch black, which kills the glow.
+ */
+export const NIGHT_W = 32;
+export const NIGHT_H = 18;
+/** A pixel brighter than this counts as blown out. */
+export const BLOWN_AT = 0.82;
+/** How much say the blown-out share gets on top of the mean. */
+export const BLOWN_WEIGHT = 0.25;
+/** Smoothing: bright arrives fast (it is the thing that hurts)… */
+export const METER_ATTACK = 0.5;
+/** …and releases slowly, so a dark cut inside a bright video does not flash the level back up. */
+export const METER_RELEASE = 0.12;
+/** The meter's resting value before the first reading (extension parity). */
+export const METER_START = 0.55;
+/** Colour push for bias cells: an average is always muddier than the scene it came from. */
+export const BIAS_SATURATE = 1.6;
+/**
+ * Rec.709 mean luma of an RGBA byte array, plus a term for the blown-out
+ * share: `min(1, mean + blownShare × 0.25)`. The mean alone under-reads the
+ * case that actually hurts — a dark page with one white pane in it.
+ * Returns null for anything that is not a whole number of RGBA pixels.
+ */
+export function frameLuma(px) {
+    if (!px || typeof px.length !== 'number' || px.length < 4 || px.length % 4 !== 0)
+        return null;
+    let sum = 0;
+    let blown = 0;
+    const n = px.length / 4;
+    for (let i = 0; i < px.length; i += 4) {
+        const r = px[i], g = px[i + 1], b = px[i + 2];
+        if (!Number.isFinite(r) || !Number.isFinite(g) || !Number.isFinite(b))
+            return null;
+        const l = (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255;
+        sum += l;
+        if (l > BLOWN_AT)
+            blown++;
+    }
+    return clamp01(sum / n + (blown / n) * BLOWN_WEIGHT);
+}
+/** One asymmetric smoothing step. A null/garbage reading leaves the value where it was. */
+export function smoothMeter(prev, reading) {
+    const p = Number.isFinite(prev) ? clamp01(prev) : METER_START;
+    if (typeof reading !== 'number' || !Number.isFinite(reading))
+        return p;
+    const l = clamp01(reading);
+    return p + (l - p) * (l > p ? METER_ATTACK : METER_RELEASE);
+}
+/**
+ * Nine cells (3×3, row-major) of the frame's own colours, each pushed toward
+ * saturation: `mean + (channel − mean) × 1.6`. A grey halo behind a video
+ * reads as fog, not light. Returns null on a buffer that does not match w×h.
+ */
+export function biasCells(px, w = NIGHT_W, h = NIGHT_H) {
+    if (!px || !(w >= 3) || !(h >= 3) || px.length !== w * h * 4)
+        return null;
+    const cells = [];
+    for (let cy = 0; cy < 3; cy++) {
+        for (let cx = 0; cx < 3; cx++) {
+            let r = 0, g = 0, b = 0, n = 0;
+            const x0 = Math.floor((cx * w) / 3), x1 = Math.floor(((cx + 1) * w) / 3);
+            const y0 = Math.floor((cy * h) / 3), y1 = Math.floor(((cy + 1) * h) / 3);
+            for (let y = y0; y < y1; y++) {
+                for (let x = x0; x < x1; x++) {
+                    const i = (y * w + x) * 4;
+                    r += px[i];
+                    g += px[i + 1];
+                    b += px[i + 2];
+                    n++;
+                }
+            }
+            if (!n)
+                return null;
+            const avg = [r / n, g / n, b / n];
+            const mean = (avg[0] + avg[1] + avg[2]) / 3;
+            const push = avg.map((c) => Math.round(Math.max(0, Math.min(255, mean + (c - mean) * BIAS_SATURATE))));
+            cells.push([push[0], push[1], push[2]]);
+        }
+    }
+    return cells;
+}
+/**
+ * The glow as one CSS background-image: eight radial gradients (every cell
+ * but the centre, which the video itself covers). These rgb() values are the
+ * FRAME's colours — data, like a speaker hue — not theme colours.
+ */
+export function biasGradient(cells) {
+    if (!cells || cells.length !== 9)
+        return '';
+    const at = ['0% 0%', '50% 0%', '100% 0%', '0% 50%', '', '100% 50%', '0% 100%', '50% 100%', '100% 100%'];
+    const parts = [];
+    for (let i = 0; i < 9; i++) {
+        if (i === 4)
+            continue;
+        const [r, g, b] = cells[i];
+        parts.push(`radial-gradient(60% 60% at ${at[i]}, rgb(${r} ${g} ${b}) 0%, transparent 70%)`);
+    }
+    return parts.join(', ');
+}
+function clamp01(v) {
+    return v < 0 ? 0 : v > 1 ? 1 : v;
+}

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

@@ -0,0 +1,105 @@
+/**
+ * Predictive dimming + the strobe guard + the composer (mos-5lzns.33).
+ *
+ * extension-library FEATURES.md §The light track. The live meter is honest but
+ * always a beat late: the bright frame reaches your eye, THEN the level comes
+ * down. With the host's pre-scanned light track (the same `luma` prop the
+ * ribbon paints — band/luma.ts) the player reads ahead and starts easing
+ * BEFORE the cut lands.
+ *
+ * Two rules carry the whole design:
+ *
+ * 1. **Prediction can only ever ADD dimming.** `composeNight` takes the max of
+ *    the meter and the prediction, so a stale or wrong track degrades to the
+ *    live meter alone — never to a brighter picture than the meter asked for.
+ * 2. **Nothing here ever brightens in a jump.** Darkening lands at once (a
+ *    sudden drop in light is never the photosensitivity hazard; the CSS ramp
+ *    eases it anyway). Brightening is released a fraction per tick, so the end
+ *    of a predicted cut or a flash interval can't snap the level back up —
+ *    even under `prefers-reduced-motion`, where the CSS ramp shrinks to a
+ *    short luminance fade.
+ *
+ * The strobe guard widens each detected flash interval by a lead and a tail
+ * and pins its own level to FLASH_LUMA at a FIXED depth of 1 across it —
+ * independent of the night dial and of whether night is on at all. The lead
+ * also covers one tick of look-ahead (`horizonSec`), because a guard that
+ * arrives after the strobe is commentary rather than protection. It REDUCES a
+ * flash; it does not make content WCAG 2.3.1-safe, and detecting the flashes
+ * is the host's job (the sidecar's `flashes` intervals).
+ */
+import { type LumaSeries, type VideoLumaTrack } from '../band/luma';
+import { type NightLevels } from './levels';
+/** Seconds of look-ahead: long enough to ease, short enough to still be about the moment you are in. */
+export declare const LUMA_LOOKAHEAD = 0.9;
+/** The guard is already down this long before the first flash… */
+export declare const FLASH_LEAD = 0.4;
+/** …and stays down this long after the last. */
+export declare const FLASH_TAIL = 0.3;
+/** The level the guard pins to across a flash interval. */
+export declare const FLASH_LUMA = 0.92;
+/** Fraction of the gap closed per tick when the level is coming back UP. */
+export declare const OUTPUT_RELEASE = 0.25;
+/**
+ * Peak brightness due over the next LUMA_LOOKAHEAD (+ one tick's horizon),
+ * 0–1, or null without a track. Reuses the ribbon's own max-per-interval
+ * reader so the ribbon and the prediction can never disagree.
+ */
+export declare function lumaAhead(series: LumaSeries | null | undefined, t: number, horizonSec?: number): number | null;
+/**
+ * Validate the sidecar's flash intervals: finite, ordered pairs, sorted by
+ * start. Garbage entries are dropped (never guessed at) — a missing guard is
+ * degraded, a guard in the wrong place is wrong.
+ */
+export declare function normalizeFlashes(track: VideoLumaTrack | null | undefined): Array<[number, number]>;
+/**
+ * Is the guard down at `t`? True inside `[start − lead, end + tail]` of any
+ * interval, where the lead is widened by `horizonSec` (the gap until the next
+ * evaluation) so a coarse tick can't let the first flash through.
+ */
+export declare function inFlash(flashes: ReadonlyArray<[number, number]>, t: number, horizonSec?: number): boolean;
+export interface NightInput {
+    /** Night dimming is armed right now (mode on, or auto inside the window). */
+    armed: boolean;
+    /** Frame readback was refused — run on NIGHT_BLIND_LUMA instead of the meter. */
+    blind: boolean;
+    /** The smoothed live meter, 0–1. */
+    meter: number;
+    /** Predicted peak ahead (null = no track / prediction off). */
+    ahead: number | null;
+    /** The strobe guard is down (host-detected flash interval, strobeGuard on). */
+    flash: boolean;
+    /** The user's night depth — night only; the guard never reads it. */
+    depth: number;
+}
+/**
+ * The composer's running state — two independent levels. Night's and the
+ * guard's are kept apart so each releases on its own terms: a guard ending
+ * inside a lighter night must not hand the picture straight back to night's
+ * (shallower) level in one step.
+ */
+export interface NightState {
+    /** Night's applied luma. */
+    luma: number;
+    /** The guard's applied luma (FLASH_LUMA while down, released after). */
+    guardLuma: number;
+}
+export declare const NIGHT_IDLE: Readonly<NightState>;
+export interface NightFrame extends NightState {
+    levels: NightLevels;
+    /** Which surface is acting: night (all four layers), the guard alone (level drop only), or nothing. */
+    mode: 'night' | 'guard' | 'none';
+    /** The guard is down right now — the component switches to the fast ramp and freezes the bias light. */
+    guard: boolean;
+}
+/**
+ * One tick of the composer. The component owns the state (feed the frame
+ * back as `prev`) and the application; this decides. `mode: 'none'` ⇒ remove
+ * every trace.
+ *
+ * Night: target = max(meter or blind level, prediction) at the user's depth.
+ * Guard: target = FLASH_LUMA at GUARD_DEPTH (1) while down, whatever night is
+ * doing — armed, disarmed or off. The two stack per channel, the deeper wins.
+ * Each level lands darker at once and releases brighter by OUTPUT_RELEASE per
+ * tick.
+ */
+export declare function composeNight(prev: Partial<NightState> | null | undefined, input: NightInput): NightFrame;