@joewinke/jatui 0.15.0 → 0.16.0

package/dist/video/settings/registry.js

@@ -0,0 +1,331 @@
+/**
+ * The settings registry (mos-5lzns.35) — extension-library's `settings.js`
+ * ported: one array declares every standing CHOICE the player's automatic
+ * behaviours read, and the settings panel is generated from it, so a knob
+ * added here shows up in the UI by existing.
+ *
+ * Three rules carried over verbatim:
+ *
+ * · `coerce` never throws and never returns junk. A bool accepts
+ *   true/"1"/"true" (and their false twins); a range parses and clamps to
+ *   [min, max]; an enum must match a declared option. Anything else returns
+ *   undefined and the caller falls back to the default. A corrupted blob in
+ *   a host's store degrades to defaults, never to a broken player.
+ * · The hint is mandatory. The sentence saying what the thing actually does
+ *   is the entire reason a settings screen exists rather than a list of
+ *   switches; a spec without one fails the unit suite.
+ * · A knob lands WITH its reader. `wired: true` means the `prop` it names is
+ *   read by VideoPlayer today — a switch that visibly does nothing is the
+ *   one thing this registry must never contain. (That is why the extension's
+ *   `night.page`, `night.sunset` and `player.smartSpeedBoost` are absent: the
+ *   player has no reader for them.)
+ *
+ * Labels and hints here are the single source for the panel AND any help
+ * page a host renders (MOS's /help reads `VIDEO_SETTINGS` directly) — never
+ * restate them elsewhere.
+ *
+ * Ephemeral UI state (transcript layout, volume, whether a pane was left
+ * open) is deliberately NOT here: remembering those is not the same thing as
+ * being configurable, and mixing them makes a settings screen that reads
+ * like a debug dump.
+ */
+const pct = (v) => Math.round(v * 100) + '%';
+/** Groups in panel order. */
+export const SETTING_GROUPS = ['Night', 'Sound', 'Wind-down', 'Playback'];
+export const VIDEO_SETTINGS = [
+    // ── Night (mos-5lzns.33) — video/night/* ────────────────────────────────
+    {
+        id: 'night.mode',
+        group: 'Night',
+        label: 'Night dimming',
+        type: 'enum',
+        options: [
+            { value: 'auto', label: 'After dark' },
+            { value: 'on', label: 'Always' },
+            { value: 'off', label: 'Off' }
+        ],
+        default: 'auto',
+        prop: 'night',
+        when: 'night',
+        hint: 'Measures how bright the picture actually is, about once a second, and pulls the level down in proportion — warming it as it goes. A dark scene passes through untouched. After dark follows the local clock — 20:00 to 07:00, or 18:00 to 08:00 when your system prefers a dark theme. N cycles it anywhere in the player.',
+        owner: 'mos-5lzns.33',
+        wired: true
+    },
+    {
+        id: 'night.depth',
+        group: 'Night',
+        label: 'How far it goes',
+        type: 'range',
+        min: 0.2,
+        max: 1,
+        step: 0.1,
+        default: 0.7,
+        format: pct,
+        prop: 'nightDepth',
+        when: 'night',
+        hint: 'The far end of the dial takes a full-white frame down to about half brightness. Scrolling the moon button on the player does the same thing.',
+        owner: 'mos-5lzns.33',
+        wired: true
+    },
+    {
+        id: 'night.bias',
+        group: 'Night',
+        label: 'Bias light',
+        type: 'bool',
+        default: true,
+        prop: 'biasLight',
+        when: 'night',
+        hint: "A soft glow of the frame's own colours spilled behind the player while night dimming acts. What strains your eyes in a dark room is the gap between the screen and the wall behind it, not the screen alone — filling that gap in lets you keep more picture.",
+        owner: 'mos-5lzns.33',
+        wired: true
+    },
+    {
+        id: 'player.predictive',
+        group: 'Night',
+        label: 'See bright cuts coming',
+        type: 'bool',
+        default: true,
+        prop: 'predictive',
+        when: 'nightLuma',
+        hint: "This video has been scanned for a per-second light track, so night dimming can start easing a moment BEFORE a cut to white instead of reacting after it lands. It only ever adds dimming. The same track draws the light ribbon on the timeline.",
+        owner: 'mos-5lzns.33',
+        wired: true
+    },
+    {
+        id: 'player.strobeGuard',
+        group: 'Night',
+        label: 'Smooth hard flashing',
+        type: 'bool',
+        default: true,
+        prop: 'strobeGuard',
+        when: 'flashes',
+        hint: 'Rapid light/dark alternation — strobes, camera flashes, some transitions — is held down to about half brightness while it lasts, day or night. It reduces flashing; it cannot promise a video is safe. Reads as a photosensitivity guard because it is one.',
+        owner: 'mos-5lzns.33',
+        wired: true
+    },
+    // ── Sound (mos-5lzns.31) — video/audio/* ────────────────────────────────
+    {
+        id: 'audio.level',
+        group: 'Sound',
+        label: 'Loudness matching',
+        type: 'bool',
+        default: true,
+        prop: 'loudness',
+        when: 'loudness',
+        hint: 'Rides the gain toward a steady target, so a whispered documentary and a video that opens on a blasting intro sting arrive at the same volume. Quiet passages are lifted a little, loud ones held back — the same idea as night dimming, one sense over.',
+        owner: 'mos-5lzns.31',
+        wired: true
+    },
+    {
+        id: 'audio.target',
+        group: 'Sound',
+        label: 'Target loudness',
+        type: 'range',
+        min: -30,
+        max: -12,
+        step: 2,
+        default: -20,
+        format: (v) => v + ' dB',
+        prop: 'loudnessTarget',
+        when: 'loudness',
+        hint: 'Where matching aims. At −20 an ordinary video is left alone and a quiet one is lifted by a few dB at most, while a blaring one comes down as far as it needs to. Turning down has far more room than turning up — matching never becomes an amplifier.',
+        owner: 'mos-5lzns.31',
+        wired: true
+    },
+    {
+        id: 'audio.quiet',
+        group: 'Sound',
+        label: 'Quiet listening',
+        type: 'bool',
+        default: true,
+        prop: 'quietListening',
+        when: 'quiet',
+        hint: "At low volume your ears lose the bottom and top of the spectrum, so dialogue goes muddy and you keep nudging the volume up and back down. This compensates that tilt, so speech stays clear at a level that won't wake the house. Comes in as the volume drops, and sits partly on after dark.",
+        owner: 'mos-5lzns.31',
+        wired: true
+    },
+    {
+        id: 'audio.limiter',
+        group: 'Sound',
+        label: 'Tame sudden peaks',
+        type: 'bool',
+        default: true,
+        prop: 'limiter',
+        when: 'limiter',
+        hint: "A limiter across the output, so a jump-scare or an ad break can't spike past the level you set. Costs nothing when nothing is peaking.",
+        owner: 'mos-5lzns.31',
+        wired: true
+    },
+    // ── Wind-down (mos-5lzns.34) — video/presence/* ─────────────────────────
+    {
+        id: 'sleep.enabled',
+        group: 'Wind-down',
+        label: "Wind down when you're gone",
+        type: 'bool',
+        default: true,
+        prop: 'windDown',
+        when: 'windDown',
+        hint: 'Fades the picture and sound out over twenty seconds and pauses, keeping your place. The fade is the prompt: any input at all cancels it and brings everything straight back.',
+        owner: 'mos-5lzns.34',
+        wired: true
+    },
+    {
+        id: 'sleep.after',
+        group: 'Wind-down',
+        label: 'Wait this long first',
+        type: 'range',
+        min: 10,
+        max: 90,
+        step: 5,
+        default: 30,
+        format: (v) => v + ' min',
+        prop: 'windDownAfter',
+        when: 'windDown',
+        hint: "How long nobody has to be there before the fade begins. Without the desktop signal below this counts input on this page only — weaker evidence, since a video legitimately plays for an hour without anyone touching a key.",
+        owner: 'mos-5lzns.34',
+        wired: true
+    },
+    {
+        id: 'sleep.nightOnly',
+        group: 'Wind-down',
+        label: 'Only after dark',
+        type: 'bool',
+        default: true,
+        prop: 'windDownNightOnly',
+        when: 'windDown',
+        hint: "Falling asleep mid-video is a night problem. During the day, a long quiet stretch usually just means you're watching.",
+        owner: 'mos-5lzns.34',
+        wired: true
+    },
+    {
+        id: 'sleep.desktopIdle',
+        group: 'Wind-down',
+        label: 'Watch the whole desktop',
+        type: 'bool',
+        default: false,
+        prop: 'idleDetection',
+        when: 'idle',
+        hint: 'Measures idle time across the whole computer instead of this page, and a locked screen skips the wait entirely. Turning it on asks the browser for permission — once, from that click. Declined, it falls back to page input.',
+        owner: 'mos-5lzns.34',
+        wired: true
+    },
+    // ── Playback (.30 / .32 / .34) ──────────────────────────────────────────
+    {
+        id: 'player.smartSpeed',
+        group: 'Playback',
+        label: 'Speed through silence',
+        type: 'bool',
+        default: false,
+        prop: 'smartSpeed',
+        when: 'waveform',
+        hint: "A flat 1.5× turns everyone into a chipmunk. This reads the waveform instead and only speeds up where nothing is being said, holding your chosen pace through speech — so a talk loses its dead air and none of its voice. The speed readout keeps showing the pace you chose.",
+        owner: 'mos-5lzns.32',
+        wired: true
+    },
+    {
+        id: 'player.speakerRate',
+        group: 'Playback',
+        label: 'Even out speaking pace',
+        type: 'bool',
+        default: false,
+        prop: 'speakerPace',
+        when: 'speakers',
+        hint: "Some people talk much faster than others. This measures each speaker's words per minute from the transcript and nudges playback per speaker so everyone lands at one comfortable pace — loudness matching, for speed. Anyone already close is left exactly alone.",
+        owner: 'mos-5lzns.32',
+        wired: true
+    },
+    {
+        id: 'player.skipAds',
+        group: 'Playback',
+        label: 'Skip ad reads',
+        type: 'bool',
+        default: false,
+        prop: 'skipAds',
+        when: 'ads',
+        hint: "When playback runs into a sponsor read it jumps to the end, and says so. Seeking into one yourself is honoured — only playing into an ad skips it.",
+        owner: 'mos-5lzns.32',
+        wired: true
+    },
+    {
+        id: 'player.resumeSnap',
+        group: 'Playback',
+        label: 'Resume at a sentence',
+        type: 'bool',
+        default: true,
+        prop: 'resumeSnap',
+        when: 'resume',
+        hint: "Coming back to a video drops you mid-word, so you scrub backwards to get your bearings. This snaps the resume point back to the nearest sentence, speaker turn or chapter within fifteen seconds, and says what you're walking back into.",
+        owner: 'mos-5lzns.34',
+        wired: true
+    },
+    {
+        id: 'player.openMotion',
+        group: 'Playback',
+        label: 'Open like an object',
+        type: 'bool',
+        default: true,
+        prop: 'openMotion',
+        when: 'open',
+        hint: "The card you clicked expands into the player, with its own thumbnail painted underneath so there's never a black flash while the first frame decodes. Off, or with reduced motion, the thumbnail still paints — that half isn't decoration.",
+        owner: 'mos-5lzns.34',
+        wired: true
+    },
+    {
+        id: 'player.oneAxis',
+        group: 'Playback',
+        label: 'Scrub on the waveform',
+        type: 'bool',
+        default: true,
+        prop: 'oneAxis',
+        when: 'waveform',
+        hint: 'One time axis instead of two. The waveform is always on screen and already seeks, so the progress bar stands down and hands it the job — and comes back as an overview while the waveform is zoomed. Turn this off to keep both bars.',
+        owner: 'mos-5lzns.30',
+        wired: true
+    }
+];
+const BY_ID = new Map(VIDEO_SETTINGS.map((s) => [s.id, s]));
+/** The spec for an id, or undefined. */
+export function settingSpec(id) {
+    return BY_ID.get(id);
+}
+/** Coerce a raw stored value against a spec — never throws, never returns junk. */
+export function coerce(spec, raw) {
+    try {
+        if (!spec || raw == null)
+            return undefined;
+        if (spec.type === 'bool') {
+            if (raw === true || raw === 1 || raw === '1' || raw === 'true')
+                return true;
+            if (raw === false || raw === 0 || raw === '0' || raw === 'false')
+                return false;
+            return undefined;
+        }
+        if (spec.type === 'range') {
+            // Only numbers and numeric strings: Number() on an object runs its
+            // valueOf/toString, and on a Symbol it throws.
+            const n = typeof raw === 'number' ? raw : typeof raw === 'string' && raw.trim() !== '' ? Number(raw) : NaN;
+            if (!Number.isFinite(n))
+                return undefined;
+            const min = Number.isFinite(spec.min) ? spec.min : -Infinity;
+            const max = Number.isFinite(spec.max) ? spec.max : Infinity;
+            return Math.min(max, Math.max(min, n));
+        }
+        if (spec.type === 'enum') {
+            if (typeof raw !== 'string')
+                return undefined;
+            return spec.options?.some((o) => o.value === raw) ? raw : undefined;
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A stored value for an id, coerced; the spec's default when absent or junk. */
+export function settingValue(id, raw) {
+    const spec = BY_ID.get(id);
+    if (!spec)
+        return undefined;
+    const v = coerce(spec, raw);
+    return v === undefined ? spec.default : v;
+}

package/dist/video/settings/store.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Where settings live (mos-5lzns.35) — host-supplied, exactly like
+ * `VideoResumeStore`. jatui never touches localStorage or calls an API for
+ * settings: a host with per-user server state (MOS's user prefs) passes its
+ * own adapter; a host that passes none gets choices that last as long as the
+ * player does.
+ *
+ * `createSettingsSession` is the one place the player reads and writes
+ * through that adapter, and holds the three ordering rules:
+ *
+ * · Every value that comes back is coerced against its spec — a store
+ *   holding junk (or throwing, or rejecting) reads as "nothing stored".
+ * · A change the user makes before the load resolves WINS. The late read
+ *   must never undo a choice that was made on screen.
+ * · Writes are debounced per id: a range dragged across twenty steps is one
+ *   write, not twenty. `flush()` (unmount) sends whatever is pending.
+ */
+import { type SettingSpec, type SettingValue } from './registry';
+/**
+ * Host persistence: `get(id)` returns whatever was stored (any shape — it
+ * is coerced), `set(id, value)` stores a value that has already been
+ * coerced. Either may be async; a throw or rejection is swallowed.
+ */
+export interface VideoSettingsStore {
+    get(id: string): unknown | Promise<unknown>;
+    set(id: string, value: SettingValue): void | Promise<void>;
+}
+export type SettingValues = Record<string, SettingValue>;
+export interface SettingsSession {
+    /** Resolves once every stored value has been read (never rejects). */
+    ready: Promise<void>;
+    /** The user changed a setting. Returns the coerced value, or undefined if it was junk. */
+    change(id: string, raw: unknown): SettingValue | undefined;
+    /** Send pending writes now. */
+    flush(): void;
+    /** Stop: pending writes are flushed, late loads are ignored. */
+    close(): void;
+}
+export interface SettingsSessionOpts {
+    store?: VideoSettingsStore | null;
+    /** Every value that lands — from the store or the user — coerced. */
+    onValue: (id: string, value: SettingValue, source: 'store' | 'user') => void;
+    specs?: SettingSpec[];
+    /** Debounce per id, ms (default 400). */
+    writeDelayMs?: number;
+}
+export declare const SETTINGS_WRITE_DELAY_MS = 400;
+export declare function createSettingsSession(opts: SettingsSessionOpts): SettingsSession;
+/**
+ * A plain in-memory store — for demos and tests, and for a host that wants
+ * to hold the values itself (read them back with `.values`).
+ */
+export declare function memorySettingsStore(initial?: Record<string, unknown>): VideoSettingsStore & {
+    values: Record<string, unknown>;
+};

package/dist/video/settings/store.js

@@ -0,0 +1,116 @@
+/**
+ * Where settings live (mos-5lzns.35) — host-supplied, exactly like
+ * `VideoResumeStore`. jatui never touches localStorage or calls an API for
+ * settings: a host with per-user server state (MOS's user prefs) passes its
+ * own adapter; a host that passes none gets choices that last as long as the
+ * player does.
+ *
+ * `createSettingsSession` is the one place the player reads and writes
+ * through that adapter, and holds the three ordering rules:
+ *
+ * · Every value that comes back is coerced against its spec — a store
+ *   holding junk (or throwing, or rejecting) reads as "nothing stored".
+ * · A change the user makes before the load resolves WINS. The late read
+ *   must never undo a choice that was made on screen.
+ * · Writes are debounced per id: a range dragged across twenty steps is one
+ *   write, not twenty. `flush()` (unmount) sends whatever is pending.
+ */
+import { coerce, VIDEO_SETTINGS } from './registry';
+export const SETTINGS_WRITE_DELAY_MS = 400;
+export function createSettingsSession(opts) {
+    const specs = opts.specs ?? VIDEO_SETTINGS;
+    const byId = new Map(specs.map((s) => [s.id, s]));
+    const store = opts.store ?? null;
+    const delay = Number.isFinite(opts.writeDelayMs) ? Math.max(0, opts.writeDelayMs) : SETTINGS_WRITE_DELAY_MS;
+    const touched = new Set();
+    const pending = new Map();
+    const timers = new Map();
+    let closed = false;
+    const write = (id) => {
+        timers.delete(id);
+        if (!pending.has(id))
+            return;
+        const v = pending.get(id);
+        pending.delete(id);
+        if (!store)
+            return;
+        try {
+            const r = store.set(id, v);
+            if (r && typeof r.catch === 'function')
+                r.catch(() => { });
+        }
+        catch {
+            /* a store that throws is a store that didn't save — never an error in the player */
+        }
+    };
+    const readOne = async (spec) => {
+        if (!store)
+            return;
+        let raw;
+        try {
+            raw = await store.get(spec.id);
+        }
+        catch {
+            return;
+        }
+        if (closed || touched.has(spec.id))
+            return;
+        const v = coerce(spec, raw);
+        if (v === undefined)
+            return;
+        try {
+            opts.onValue(spec.id, v, 'store');
+        }
+        catch {
+            /* the host's handler is not ours to crash on */
+        }
+    };
+    const flush = () => {
+        for (const [id, t] of timers) {
+            clearTimeout(t);
+            write(id);
+        }
+        timers.clear();
+    };
+    const ready = store ? Promise.all(specs.map(readOne)).then(() => undefined) : Promise.resolve();
+    return {
+        ready,
+        change(id, raw) {
+            const spec = byId.get(id);
+            if (!spec || closed)
+                return undefined;
+            const v = coerce(spec, raw);
+            if (v === undefined)
+                return undefined;
+            touched.add(id);
+            opts.onValue(id, v, 'user');
+            if (store) {
+                pending.set(id, v);
+                const t = timers.get(id);
+                if (t)
+                    clearTimeout(t);
+                timers.set(id, setTimeout(() => write(id), delay));
+            }
+            return v;
+        },
+        flush,
+        close() {
+            flush();
+            closed = true;
+        }
+    };
+}
+/**
+ * A plain in-memory store — for demos and tests, and for a host that wants
+ * to hold the values itself (read them back with `.values`).
+ */
+export function memorySettingsStore(initial = {}) {
+    const values = { ...initial };
+    return {
+        values,
+        get: (id) => values[id],
+        set: (id, v) => {
+            values[id] = v;
+        }
+    };
+}

package/dist/video/settings.d.ts

@@ -1,50 +1,19 @@
 /**
- * Settings plumbing for VideoPlayer (mos-5lzns.28) — ported discipline from
- * extension-library's `settings.js`, adapted to a prop-driven component.
+ * Settings for VideoPlayer — the barrel (mos-5lzns.28 skeleton, filled in by
+ * mos-5lzns.35). The pieces live in `settings/`:
  *
- * The extension's registry exists so the settings panel is generated from one
- * array and "a setting added there appears in the UI by existing". jatui's
- * player is prop-driven (the HOST owns the panel), so this module owns the
- * smaller half of the contract that still matters here:
+ * · `registry.ts` — `VIDEO_SETTINGS`: every standing choice the player's
+ *   automatic behaviours read, with its label, hint, group, the prop it
+ *   drives and the availability gate. `coerce` never throws.
+ * · `store.ts` — the host-supplied `VideoSettingsStore` (get/set) and the
+ *   session that reads/writes through it. jatui never persists on its own.
+ * · `panel.ts` — which rows a given player can offer, and how values read.
+ * · `SettingsPanel.svelte` — the panel, generated wholly from the registry.
  *
- * · `coerce` never throws and never returns junk. A bool accepts
- *   true/"1"/"true"; a range parses and clamps to [min, max]; an enum must
- *   match a declared option or the value is discarded. Anything
- *   unrecognised returns undefined and the caller falls back to the
- *   declared default. A corrupted blob degrades to defaults, not to a
- *   broken player.
- * · One registry (`VIDEO_SETTINGS`) lists every knob the player's automatic
- *   behaviours read, with the sub-task that owns each. A knob that is here
- *   but unread by any module is a switch that visibly does nothing — the
- *   extension calls that "declared but not yet wired" and refuses to fix it
- *   quietly. Keep the same discipline: land the knob WITH its reader.
- *
- * Nothing under src/lib/video/ reads a setting directly except through the
- * value its owning feature passes in as an `opts` argument — the advisor
- * rule (see README). That keeps every module node-testable and keeps the
- * arbitration in the component.
- */
-export type SettingType = 'bool' | 'range' | 'enum';
-export interface SettingSpec {
-    id: string;
-    type: SettingType;
-    default: boolean | number | string;
-    /** range only */
-    min?: number;
-    max?: number;
-    step?: number;
-    /** enum only */
-    options?: string[];
-    /** Which sub-task wires the reader. A spec without a live reader is a lie. */
-    owner: string;
-    /** Set true once the owning task lands (check: grep the module for the id). */
-    wired?: boolean;
-}
-/**
- * The registry. Populated as the behaviours land — .30 oneAxis, .31 audio,
- * .32 rate/speaker/silence, .33 night, .34 presence. An empty registry is
- * the honest state while every behaviour is prop-driven.
+ * Nothing under src/lib/video/ reads a setting directly: the component maps
+ * each value onto the prop it names and the feature reads that — the
+ * advisor rule (see README).
  */
-export declare const VIDEO_SETTINGS: SettingSpec[];
-/** Coerce a raw stored value against a spec — never throws, never returns junk. */
-export declare function coerce<T extends SettingSpec>(spec: T, raw: unknown): T['default'] | undefined;
+export * from './settings/registry';
+export * from './settings/store';
+export * from './settings/panel';