@joewinke/jatui 0.11.0 → 0.13.0

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;

package/dist/video/night/track.js

@@ -0,0 +1,138 @@
+/**
+ * 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 { lumaPeak } from '../band/luma';
+import { deeperLevels, guardLevels, isNeutral, nightLevels, NIGHT_BLIND_LUMA, NIGHT_NEUTRAL_LEVELS } from './levels';
+/** Seconds of look-ahead: long enough to ease, short enough to still be about the moment you are in. */
+export const LUMA_LOOKAHEAD = 0.9;
+/** The guard is already down this long before the first flash… */
+export const FLASH_LEAD = 0.4;
+/** …and stays down this long after the last. */
+export const FLASH_TAIL = 0.3;
+/** The level the guard pins to across a flash interval. */
+export const FLASH_LUMA = 0.92;
+/** Fraction of the gap closed per tick when the level is coming back UP. */
+export 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 function lumaAhead(series, t, horizonSec = 0) {
+    if (!series || !Number.isFinite(t))
+        return null;
+    const h = Number.isFinite(horizonSec) && horizonSec > 0 ? horizonSec : 0;
+    if (t > series.durationSec)
+        return null;
+    return lumaPeak(series, Math.max(0, t), Math.max(0, t) + LUMA_LOOKAHEAD + h);
+}
+/**
+ * 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 function normalizeFlashes(track) {
+    const raw = track?.flashes;
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const f of raw) {
+        if (!Array.isArray(f) || f.length < 2)
+            continue;
+        const s = f[0], e = f[1];
+        if (typeof s !== 'number' || typeof e !== 'number' || !Number.isFinite(s) || !Number.isFinite(e))
+            continue;
+        out.push(s <= e ? [s, e] : [e, s]);
+    }
+    return out.sort((a, b) => a[0] - b[0]);
+}
+/**
+ * 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 function inFlash(flashes, t, horizonSec = 0) {
+    if (!flashes.length || !Number.isFinite(t))
+        return false;
+    const h = Number.isFinite(horizonSec) && horizonSec > 0 ? horizonSec : 0;
+    for (const [s, e] of flashes) {
+        if (s - FLASH_LEAD > t + h)
+            return false; // sorted: nothing later can match
+        if (t <= e + FLASH_TAIL)
+            return true;
+    }
+    return false;
+}
+export const NIGHT_IDLE = Object.freeze({ luma: 0, guardLuma: 0 });
+/**
+ * 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 function composeNight(prev, input) {
+    const pNight = finite01(prev?.luma ?? 0);
+    const pGuard = finite01(prev?.guardLuma ?? 0);
+    const flash = !!input.flash;
+    let nightTarget = 0;
+    if (input.armed) {
+        const base = input.blind ? NIGHT_BLIND_LUMA : finite01(input.meter);
+        nightTarget = Math.max(base, input.ahead == null ? 0 : finite01(input.ahead));
+    }
+    // Disarmed (the auto window just ended) ⇒ night's level releases per tick
+    // like any other brightening rather than dropping to 0 in one step. An
+    // explicit `off` is the component's to clear at once — that is a statement.
+    const luma = step(pNight, nightTarget);
+    const guardLuma = step(pGuard, flash ? FLASH_LUMA : 0);
+    const guardL = guardLevels(guardLuma);
+    const nightL = nightLevels(luma, input.depth);
+    // While releasing after disarm only the level drop carries over; the
+    // warm/vignette veils fade out on their own CSS ramp.
+    const levels = input.armed
+        ? deeperLevels(nightL, guardL)
+        : deeperLevels({ bright: nightL.bright, sat: nightL.sat, warm: 0, vig: 0 }, guardL);
+    if (!input.armed && isNeutral(levels)) {
+        return { luma: 0, guardLuma: 0, levels: { ...NIGHT_NEUTRAL_LEVELS }, mode: 'none', guard: false };
+    }
+    // Settle a released guard to exactly 0 once it no longer changes a pixel.
+    const g = isNeutral(guardL) && !flash ? 0 : guardLuma;
+    return { luma, guardLuma: g, levels, mode: input.armed ? 'night' : 'guard', guard: flash };
+}
+/** Darker lands at once; brighter is released a fraction per tick. */
+function step(prev, target) {
+    return target >= prev ? target : prev + (target - prev) * OUTPUT_RELEASE;
+}
+function finite01(v) {
+    return typeof v === 'number' && Number.isFinite(v) ? Math.max(0, Math.min(1, v)) : 0;
+}

package/dist/video/night.d.ts

@@ -1,26 +1,31 @@
 /**
- * Night module — CONTRACT ONLY (mos-5lzns.28). Implemented by mos-5lzns.33
- * ("night dimming, bias light, predictive dimming, strobe guard").
+ * Night module (mos-5lzns.33) — night dimming, bias light, predictive
+ * dimming (the luma track), strobe guard. Ported from extension-library
+ * FEATURES.md §Night dimming, §Bias light, §The light track.
  *
- * What lands here (extension-library FEATURES.md §Night dimming, §Bias light,
- * §The light track), as ADVISORS + paint helpers:
+ * Layout (every file pure and node-testable — `npm run test:unit`):
  *
- * · night dimming — every ~900ms while playing, sample the frame's actual
- *   brightness (downscaled canvas read), drive filter: brightness() toward
- *   `1 − 0.5·depth·excess`. Attack fast, release slow, so a dark cut inside a
- *   bright video doesn't flash. `N` cycles auto/on/off — add its row to
- *   keys.ts PLAYER_KEYS when the reader lands, not before.
- * · bias light — the frame's own colours, blurred, behind the player
- *   (radial-gradient cells at z-index −1).
- * · predictive dimming — the pre-scanned luma track read ~1s ahead so
- *   dimming starts BEFORE a bright cut; the light ribbon rides the same
- *   track on whichever axis owns scrubbing (mos-5lzns.30's one-axis).
- * · strobe guard — hold the level down across detected flash intervals.
+ * · night/meter.ts  — 32×18 frame bytes → Rec.709 luma (+ blown-out share),
+ *   asymmetric smoothing (attack 0.5, release 0.12), and the 3×3 bias-light
+ *   cells read from the SAME bytes.
+ * · night/levels.ts — luma → brightness / saturation / warmth / vignette off
+ *   NIGHT_FLOOR 0.34; the blind fixed level; the surround level that re-tunes
+ *   night for LIGHT themes.
+ * · night/clock.ts  — what arms it: local clock (prefers-color-scheme dark only
+ *   widens the window) + the manual auto/on/off cycle (`N`). No hyprsunset.
+ * · night/track.ts  — prediction (can only ADD dimming), flash intervals, and
+ *   `composeNight`, the one-tick decision: darker lands at once, brighter is
+ *   released per tick, so nothing ever brightens in a jump.
  *
- * The measuring code is an advisor: it reads no settings, touches no
- * <video>, and returns safe neutral values on garbage input (CORS-tainted
- * canvas ⇒ escalate to the caller, never silently guess brightness). The
- * component decides and applies. Respect prefers-reduced-motion where it
- * applies: the correction is the feature, the ramp is only how it arrives.
+ * The advisor rule (README): nothing here reads a setting, touches the
+ * <video>, or draws. The component samples the frame (crossorigin="anonymous"
+ * is the host's call), escalates a tainted canvas via `onNightBlind`, and
+ * applies the numbers as CSS variables that exist only while night acts — off
+ * leaves no trace. prefers-reduced-motion drops the ramps, never the
+ * correction: the dimming is the feature, the ramp is only how it arrives.
  */
 export declare const NIGHT_NEUTRAL = 1;
+export * from './night/meter';
+export * from './night/levels';
+export * from './night/clock';
+export * from './night/track';