@joewinke/jatui 0.10.0 → 0.12.0

package/dist/video/advisors/speaker-rate.js

@@ -0,0 +1,322 @@
+/**
+ * Per-speaker playback rate, measured rather than guessed. Ported verbatim
+ * from extension-library `lib/speaker-rate.js` (mos-5lzns.27).
+ *
+ * The manual version of this feature is a speed slider, and a speed slider is
+ * a chore: you nudge it up for the slow host, forget, and then the guest who
+ * talks at 200 wpm arrives sounding auctioned. The premise here is the one
+ * behind loudness matching, one sense over — the app can MEASURE the thing you
+ * were about to compensate for. Words per minute falls straight out of a
+ * diarised transcript (words in a segment, seconds of that segment, attributed
+ * to whoever was talking), so it can propose the rates that put everyone at one
+ * pace and let you keep or discard them. Nobody has to guess "is 1.2 too much
+ * for this one".
+ *
+ * Pure advisor, deliberately (src/lib/video/README.md doctrine): no DOM, no
+ * <video>, no settings reads, no motion (so nothing here for
+ * prefers-reduced-motion to reduce). It answers "how fast is each person
+ * talking, and what would even them out" and stops there — the component
+ * decides whether to apply any of it, and every function returns a safe
+ * neutral value rather than throwing when the data is missing or malformed,
+ * because half this library's videos have no diarisation at all.
+ *
+ *   speakerPace(transcript, speakers)
+ *     -> { bySpeaker: { name: { wpm, words, seconds } }, medianWpm }
+ *   suggestRates(pace, { targetWpm, min, max, step })  -> { name: rate }
+ *   rateAt(t, turns, rates, fallback)                  -> multiplier at time t
+ *   describeRates(pace, rates)                         -> ["Darren 168 wpm → 0.9x", …]
+ *
+ * Input shapes: segments/turns are the same duration-bearing objects the
+ * component already holds (VideoTranscriptSegment / VideoSpeakerTurn read
+ * structurally — `start`/`end` seconds, `text`, `speaker`/`name`, `ad`), so
+ * meeting and scribe data flows straight through. Field names are read with
+ * the extension's spellings (`start`/`end`/`text`/`speaker`/`name`/`ad`);
+ * mos-5lzns.32's wiring maps the component's `Sec`-suffixed props at the call
+ * site if they ever differ.
+ */
+// Under this many words a WPM is an artefact of segment boundaries rather than
+// a speaking style: "Right." alone on a four-second segment reads as 15 wpm,
+// and a three-word interjection inside someone else's sentence reads as 400.
+// Twenty words is roughly eight seconds of continuous speech — the shortest
+// sample that has ever looked like a pace instead of a coincidence.
+const MIN_WORDS = 20;
+// Within ±7% of target, do nothing at all. 1.05 is audible on music and
+// essentially inaudible on speech, so a rate that close buys nothing — and
+// since turns hand off every few seconds, a hair-trigger would have the pitch
+// stepping on every handoff. A rate that flickers 1.0 → 1.05 → 1.0 is worse
+// than no feature; leaving someone alone is a real answer.
+const DEADZONE = 0.07;
+const DEFAULTS = { min: 0.75, max: 1.5, step: 0.05 };
+// finite-or-null: the single gate every external number passes through, so
+// "0.9", undefined, NaN and {} all collapse to one thing callers can test
+function num(v) {
+    const n = typeof v === "number" ? v : parseFloat(v);
+    return Number.isFinite(n) ? n : null;
+}
+function labelOf(v) {
+    if (typeof v !== "string")
+        return null;
+    const s = v.trim();
+    return s || null;
+}
+// Whitespace tokens, and nothing cleverer. Stripping punctuation or filtering
+// "um" would make the number prettier and less true — WPM is only useful here
+// as a RATIO between two speakers counted the same way, and both of them say um.
+function countWords(text) {
+    if (typeof text !== "string")
+        return 0;
+    const s = text.trim();
+    return s ? s.split(/\s+/).length : 0;
+}
+function flattenTurns(turns) {
+    const list = [];
+    for (const t of turns) {
+        if (!t || typeof t !== "object")
+            continue;
+        const start = num(t.start);
+        const end = num(t.end);
+        if (start == null || end == null || end <= start)
+            continue;
+        list.push({
+            start,
+            end,
+            name: t.ad ? null : labelOf(t.name),
+        });
+    }
+    if (!list.length)
+        return [];
+    // hosts promise sorted input; sorting anyway costs O(n log n) once per array
+    // and takes the promise out of the contract, which is cheaper than a support
+    // thread about rates being off by one speaker
+    list.sort((a, b) => a.start - b.start);
+    const cuts = [];
+    for (const t of list)
+        cuts.push(t.start, t.end);
+    cuts.sort((a, b) => a - b);
+    const flat = [];
+    let ti = 0;
+    let open = [];
+    for (let i = 0; i < cuts.length - 1; i++) {
+        const a = cuts[i];
+        const b = cuts[i + 1];
+        if (b <= a)
+            continue; // duplicate boundary — zero-width slice, nothing to own
+        while (ti < list.length && list[ti].start <= a)
+            open.push(list[ti++]);
+        open = open.filter((t) => t.end > a); // bounded by overlap depth, not by n
+        if (!open.length)
+            continue;
+        let win = open[0];
+        for (const t of open)
+            if (t.start >= win.start)
+                win = t;
+        const prev = flat[flat.length - 1];
+        // merge across cut points: the interesting boundaries are handoffs, and a
+        // speaker interrupted-then-resumed should read as one stretch, not three
+        if (prev && prev.name === win.name && prev.end === a)
+            prev.end = b;
+        else
+            flat.push({ start: a, end: b, name: win.name });
+    }
+    return flat;
+}
+// rateAt runs on every timeupdate, so the flatten is memoised against the array
+// identity the host handed us. Fingerprinting length + endpoints catches the
+// realistic staleness (a fresh array from setSpeakers, a re-diarise); an
+// in-place edit that preserves both would go unseen, which is why the host
+// replaces this array rather than mutating it.
+const flatCache = new WeakMap();
+function prepared(turns) {
+    if (!Array.isArray(turns) || !turns.length)
+        return [];
+    const mark = turns.length +
+        ":" +
+        turns[0]?.start +
+        ":" +
+        turns[turns.length - 1]?.end;
+    const hit = flatCache.get(turns);
+    if (hit && hit.mark === mark)
+        return hit.flat;
+    const flat = flattenTurns(turns);
+    flatCache.set(turns, { mark, flat });
+    return flat;
+}
+// last slice starting at or before sec, then a coverage check — [start, end),
+// so a time landing exactly on a handoff belongs to the person taking over
+function segAt(flat, sec) {
+    let lo = 0;
+    let hi = flat.length - 1;
+    let found = -1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        if (flat[mid].start <= sec) {
+            found = mid;
+            lo = mid + 1;
+        }
+        else
+            hi = mid - 1;
+    }
+    if (found < 0)
+        return null;
+    const seg = flat[found];
+    return sec < seg.end ? seg : null;
+}
+// Weighted by talk time, not a plain median of the speakers. Two speakers with
+// a plain median land on the midpoint and BOTH get resampled — the worst of the
+// three options, since the voice you hear most is the one you're least likely
+// to want altered. Weighted, the dominant speaker sits at the target and stays
+// at 1x, and the occasional guest is the one who moves. An exact tie splits the
+// difference so a two-hander doesn't arbitrarily crown whoever is slower.
+function weightedMedian(rows) {
+    const list = rows.slice().sort((a, b) => a.wpm - b.wpm);
+    const total = list.reduce((s, r) => s + r.seconds, 0);
+    if (!(total > 0))
+        return 0;
+    const half = total / 2;
+    let acc = 0;
+    for (let i = 0; i < list.length; i++) {
+        acc += list[i].seconds;
+        if (acc > half)
+            return list[i].wpm;
+        if (acc === half) {
+            const next = list[i + 1];
+            return next ? (list[i].wpm + next.wpm) / 2 : list[i].wpm;
+        }
+    }
+    return list[list.length - 1].wpm;
+}
+const round1 = (n) => Math.round(n * 10) / 10;
+export function speakerPace(transcript, speakers) {
+    const empty = { bySpeaker: Object.create(null), medianWpm: 0 };
+    if (!Array.isArray(transcript) || !transcript.length)
+        return empty;
+    const flat = prepared(speakers);
+    const acc = new Map();
+    for (const seg of transcript) {
+        if (!seg || typeof seg !== "object")
+            continue;
+        const start = num(seg.start);
+        const end = num(seg.end);
+        if (start == null || end == null || end <= start)
+            continue;
+        const words = countWords(seg.text);
+        if (!words)
+            continue;
+        // Midpoint, not start: a segment straddling a handoff belongs to whoever
+        // did most of the talking in it, and with no per-word timings the midpoint
+        // is the cheapest honest proxy. Turns win over segment.speaker when both
+        // exist — the diarisation pass that produced the turns is the one that
+        // resolved LABEL → display name and marked the ads.
+        const covering = flat.length ? segAt(flat, (start + end) / 2) : null;
+        // covering with a null name is an ad read: known, and deliberately not a
+        // person. Falling through to seg.speaker here would file the sponsor's
+        // words under the host.
+        const name = covering
+            ? covering.name
+            : labelOf(seg.speaker);
+        if (!name)
+            continue;
+        const row = acc.get(name) || { words: 0, seconds: 0 };
+        row.words += words;
+        row.seconds += end - start;
+        acc.set(name, row);
+    }
+    // null-prototype: a speaker literally named "__proto__" (names are
+    // user-editable — the rename menu accepts anything) would otherwise assign
+    // to the object's prototype slot instead of creating a key, leaving
+    // bySpeaker self-inconsistent: readable by name, invisible to Object.keys
+    // (the empty return above is null-prototype for the same reason — both
+    // Object.create(null) sites are deliberate, not style)
+    const bySpeaker = Object.create(null);
+    const rows = [];
+    for (const [name, row] of acc) {
+        if (row.words < MIN_WORDS || !(row.seconds > 0))
+            continue;
+        const wpm = round1((row.words / row.seconds) * 60);
+        bySpeaker[name] = {
+            wpm,
+            words: row.words,
+            seconds: Math.round(row.seconds * 100) / 100,
+        };
+        rows.push({ wpm, seconds: row.seconds });
+    }
+    return {
+        bySpeaker,
+        medianWpm: rows.length ? round1(weightedMedian(rows)) : 0,
+    };
+}
+export function suggestRates(pace, opts) {
+    const out = {};
+    const by = pace && typeof pace === "object" ? pace.bySpeaker : null;
+    if (!by || typeof by !== "object")
+        return out;
+    const o = opts && typeof opts === "object" ? opts : {};
+    const target = num(o.targetWpm) ?? num(pace.medianWpm);
+    if (!(target !== null && target > 0))
+        return out;
+    const a = num(o.min) ?? DEFAULTS.min;
+    const b = num(o.max) ?? DEFAULTS.max;
+    const lo = Math.min(a, b);
+    const hi = Math.max(a, b); // an inverted range is a typo, not an instruction to return nothing
+    const step = num(o.step) ?? DEFAULTS.step;
+    for (const [name, p] of Object.entries(by)) {
+        const wpm = num(p && p.wpm);
+        if (wpm == null || wpm <= 0)
+            continue;
+        const raw = target / wpm;
+        if (Math.abs(raw - 1) <= DEADZONE && raw >= lo && raw <= hi) {
+            // exactly 1, not 0.9999 — the host compares against 1. Gated on the
+            // range: an unmodified 1 is only the right answer if 1 is a rate the
+            // caller actually allows. With min 1.2 it isn't, and returning it anyway
+            // silently broke the one promise this function makes about its output.
+            out[name] = 1;
+            continue;
+        }
+        // snap first, then clamp: snapping a clamped value can walk it back over
+        // the limit, and the limit is the promise the user actually set
+        const snapped = step > 0 ? Math.round(raw / step) * step : raw;
+        const rate = Math.round(Math.min(hi, Math.max(lo, snapped)) * 1000) / 1000;
+        out[name] = Math.abs(rate - 1) < 1e-9 ? 1 : rate;
+    }
+    return out;
+}
+export function rateAt(t, turns, rates, fallback = 1) {
+    const fb = num(fallback) ?? 1;
+    const sec = num(t);
+    if (sec == null)
+        return fb;
+    const flat = prepared(turns);
+    if (!flat.length)
+        return fb;
+    const seg = segAt(flat, sec);
+    // no turn covering t, or an ad read (name === null): nobody to match, so
+    // normal speed. Silence between turns is the one place a rate change would
+    // be inaudible anyway, and holding the last speaker's rate through it makes
+    // the next handoff land late.
+    if (!seg || !seg.name)
+        return fb;
+    const r = rates && typeof rates === "object"
+        ? num(rates[seg.name])
+        : null;
+    return r != null && r > 0 ? r : fb;
+}
+// Sorted by talk time because that's the order you think about the people in:
+// the host first, the guest who said four sentences last. Someone already on
+// pace still gets a line — seeing that they were measured and left alone is
+// the point, and a list that only shows the changed speakers reads like the
+// others were missed.
+export function describeRates(pace, rates) {
+    const by = pace && typeof pace === "object" ? pace.bySpeaker : null;
+    if (!by || typeof by !== "object")
+        return [];
+    const rows = Object.entries(by).filter(([, p]) => p && num(p.wpm) != null);
+    rows.sort((x, y) => (num(y[1].seconds) ?? 0) - (num(x[1].seconds) ?? 0) ||
+        x[0].localeCompare(y[0]));
+    return rows.map(([name, p]) => {
+        const wpm = Math.round(num(p.wpm));
+        const r = rates && typeof rates === "object" ? num(rates[name]) : null;
+        if (r == null || Math.abs(r - 1) < 1e-9)
+            return `${name} ${wpm} wpm · on pace`;
+        return `${name} ${wpm} wpm → ${+r.toFixed(2)}x`;
+    });
+}

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