@joewinke/jatui 0.10.0 → 0.12.0

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';

package/dist/video/night.js

@@ -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 const NIGHT_NEUTRAL = 1;
+export * from './night/meter';
+export * from './night/levels';
+export * from './night/clock';
+export * from './night/track';

package/dist/video/settings.js

@@ -34,7 +34,16 @@ export const VIDEO_SETTINGS = [
     { id: 'player.oneAxis', type: 'bool', default: true, owner: 'mos-5lzns.30', wired: true },
     // { id: 'audio.level', type: 'bool', default: true, owner: 'mos-5lzns.31' },
     // { id: 'player.speakerRate', type: 'bool', default: false, owner: 'mos-5lzns.32' },
-    // { id: 'night.mode', type: 'enum', default: 'auto', options: ['auto','on','off'], owner: 'mos-5lzns.33' },
+    // Read by VideoPlayer's `night` / `nightDepth` / `biasLight` / `predictive` /
+    // `strobeGuard` props → video/night/* (clock.nightArmed, levels.nightLevels,
+    // meter.biasCells, track.lumaAhead / inFlash / composeNight). Unlike the
+    // extension, night.mode's DEFAULT here is the host's opt-in: an absent `night`
+    // prop means the feature does not exist on that player.
+    { id: 'night.mode', type: 'enum', default: 'auto', options: ['auto', 'on', 'off'], owner: 'mos-5lzns.33', wired: true },
+    { id: 'night.depth', type: 'range', default: 0.7, min: 0.2, max: 1, step: 0.1, owner: 'mos-5lzns.33', wired: true },
+    { id: 'night.bias', type: 'bool', default: true, owner: 'mos-5lzns.33', wired: true },
+    { id: 'player.predictive', type: 'bool', default: true, owner: 'mos-5lzns.33', wired: true },
+    { id: 'player.strobeGuard', type: 'bool', default: true, owner: 'mos-5lzns.33', wired: true },
     // { id: 'sleep.enabled', type: 'bool', default: true, owner: 'mos-5lzns.34' },
 ];
 /** Coerce a raw stored value against a spec — never throws, never returns junk. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joewinke/jatui",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "private": false,
   "description": "Shared Svelte 5 component library for JAT projects",
   "type": "module",
@@ -76,7 +76,8 @@
     "check:demos": "node scripts/check-demo-coverage.mjs",
     "guard": "node scripts/check-demo-coverage.mjs",
     "test:dist": "svelte-kit sync && vitest run --config vitest.dist.config.ts",
-    "test:unit": "node --import ./tests/unit/register.mjs --test tests/unit/",
+    "test:unit": "node --import ./tests/unit/register.mjs --test tests/unit/*.test.ts",
+    "test:advisors": "svelte-kit sync && vitest run --config vitest.unit.config.ts",
     "prepublishOnly": "node scripts/guard-ci-publish.mjs && npm run package"
   },
   "peerDependencies": {