@joewinke/jatui 0.11.0 → 0.12.0

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.11.0",
+  "version": "0.12.0",
   "private": false,
   "description": "Shared Svelte 5 component library for JAT projects",
   "type": "module",