@joewinke/jatui 0.14.0 → 0.15.0

package/dist/video/presence/idle.js

@@ -0,0 +1,145 @@
+/**
+ * The desktop signal for wind-down (mos-5lzns.34): Chromium's Idle Detection
+ * API (`IdleDetector`) — system-wide user idle + screen locked, the browser's
+ * near-exact equivalent of the extension's `hyprctl cursorpos` + `hyprlock`.
+ *
+ * Three rules, all load-bearing:
+ *
+ * 1. **Feature-detect, never assume.** `IdleDetector` exists only in
+ *    Chromium, only in a secure context, and only where the
+ *    `idle-detection` permissions policy allows it (a cross-origin iframe
+ *    without `allow="idle-detection"` is refused). Every entry point here
+ *    fails toward "no desktop signal", which the caller turns into the
+ *    labelled page-presence fallback — never into a guess.
+ * 2. **Never prompt uninvited.** `requestIdleDetection()` is the ONLY call
+ *    that can surface a permission prompt, and it is only ever made because
+ *    the host opted in (the player's `idleDetection` prop). It needs a user
+ *    gesture (transient activation) — call it from the click that enables
+ *    the setting. `startDesktopWatch()` never asks: it starts only when the
+ *    permission is already granted.
+ * 3. **The caller decides.** Like the extension's host (`desktop_idle()`
+ *    reports two raw facts and keeps no state), this reports `{ idle,
+ *    locked }` and nothing else. How long the video has been playing, and
+ *    whether that adds up to absence, is the component's call
+ *    (./winddown.ts).
+ *
+ * The global is injectable (`g`) so node:test can drive a fake detector —
+ * the same seam the audio graph uses for AudioContext.
+ */
+/** The API's floor: `threshold` below 60s is rejected by the browser. */
+export const IDLE_THRESHOLD_MIN_MS = 60_000;
+function ctorOf(g) {
+    if (!g || typeof g !== 'object')
+        return null;
+    if (g.isSecureContext === false)
+        return null;
+    const C = g.IdleDetector;
+    return typeof C === 'function' ? C : null;
+}
+const defaultGlobals = () => typeof globalThis === 'undefined' ? undefined : globalThis;
+/** Does this browser have the Idle Detection API at all? (Chromium, secure context.) */
+export function idleDetectionSupported(g = defaultGlobals()) {
+    return ctorOf(g) !== null;
+}
+/**
+ * The current permission state WITHOUT prompting. `'unsupported'` when the
+ * API or the Permissions API is missing, or the query throws (an unknown
+ * permission name throws in browsers that don't know it).
+ */
+export async function idleDetectionPermission(g = defaultGlobals()) {
+    if (!ctorOf(g))
+        return 'unsupported';
+    const query = g?.navigator?.permissions?.query;
+    if (typeof query !== 'function')
+        return 'unsupported';
+    try {
+        const r = await query.call(g.navigator.permissions, { name: 'idle-detection' });
+        const s = r?.state;
+        return s === 'granted' || s === 'denied' || s === 'prompt' ? s : 'unsupported';
+    }
+    catch {
+        return 'unsupported';
+    }
+}
+/**
+ * Ask for the permission. MUST be called from a user gesture, and only
+ * because the user opted in — this is the one call that can show a prompt.
+ * Resolves `'granted'` / `'denied'`, or `'unsupported'` (no API, or the
+ * browser refused to ask: no activation, policy-blocked frame).
+ */
+export async function requestIdleDetection(g = defaultGlobals()) {
+    const C = ctorOf(g);
+    if (!C || typeof C.requestPermission !== 'function')
+        return 'unsupported';
+    try {
+        const s = await C.requestPermission();
+        return s === 'granted' ? 'granted' : 'denied';
+    }
+    catch {
+        return 'unsupported';
+    }
+}
+/** Map the API's two strings onto the two facts. Unknown ⇒ null (no reading). */
+export function toDesktopSignal(userState, screenState) {
+    if (userState !== 'active' && userState !== 'idle')
+        return null;
+    return { idle: userState === 'idle', locked: screenState === 'locked' };
+}
+/**
+ * Start watching the desktop. Never prompts: `start()` rejects with
+ * NotAllowedError unless the permission is already granted, and that
+ * rejection becomes `ready → false`. `thresholdMs` is clamped up to the
+ * API's 60s floor. `onChange` fires with each new reading.
+ */
+export function startDesktopWatch(opts) {
+    const g = opts.g ?? defaultGlobals();
+    const C = ctorOf(g);
+    let latest = null;
+    let stopped = false;
+    if (!C)
+        return { ready: Promise.resolve(false), read: () => null, stop: () => { } };
+    const AC = g?.AbortController ?? (typeof AbortController === 'function' ? AbortController : undefined);
+    const abort = AC ? new AC() : null;
+    let detector = null;
+    const onChange = () => {
+        if (stopped || !detector)
+            return;
+        latest = toDesktopSignal(detector.userState, detector.screenState);
+        opts.onChange(latest);
+    };
+    const t = Number(opts.thresholdMs);
+    const threshold = Math.max(IDLE_THRESHOLD_MIN_MS, Number.isFinite(t) ? t : IDLE_THRESHOLD_MIN_MS);
+    const ready = (async () => {
+        try {
+            detector = new C();
+            detector.addEventListener('change', onChange);
+            await detector.start({ threshold, signal: abort?.signal });
+            if (stopped)
+                return false;
+            onChange(); // the state as of start — no change event is owed for it
+            return true;
+        }
+        catch {
+            detector?.removeEventListener?.('change', onChange);
+            detector = null;
+            return false;
+        }
+    })();
+    return {
+        ready,
+        read: () => latest,
+        stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            latest = null;
+            try {
+                abort?.abort();
+            }
+            catch {
+                /* already aborted */
+            }
+            detector?.removeEventListener?.('change', onChange);
+        }
+    };
+}

package/dist/video/presence/resume.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Resume at a sentence — the component-side glue (mos-5lzns.34) around
+ * `advisors/resume-point` (.27). The snapping itself — CLOSEST wins, the 15s
+ * ceiling, ads never a landing, the quoted line — lives in the advisor and
+ * is NOT re-derived here. This file only:
+ *
+ * · defines the host-supplied persistence adapter (`VideoResumeStore`) and
+ *   its localStorage default — jatui never calls an API; a host that keeps
+ *   resume points server-side (MOS's `video_user_state`) passes its own;
+ * · maps the player's `startSec/endSec` data onto the advisor's extension
+ *   spellings (`start/end/text/speaker`, `name/ad`, `start/title`);
+ * · holds the two library.js integration decisions as pure functions:
+ *   (1) the snap runs when the boundaries LAND, not at open, and
+ *   (2) it stands down if the user has taken the wheel (> 2.5s from the
+ *       stored point by the time the data arrives).
+ */
+import { type ResumeCtx, type ResumePoint } from '../advisors/resume-point';
+import type { VideoChapter, VideoSpeakerTurn, VideoTranscriptSegment } from '../types';
+/** You moved the playhead yourself — a snap now would yank it out from under you. */
+export declare const RESUME_WHEEL_SEC = 2.5;
+/** The advisor's hard ceiling, passed explicitly so the contract is visible here. */
+export declare const RESUME_MAX_BACK = 15;
+/** How often playback writes the position while it plays. */
+export declare const RESUME_SAVE_MS = 5000;
+/** Below this there is nothing to resume (the advisor's START_FLOOR). */
+export declare const RESUME_FLOOR_SEC = 2;
+/** Within this of the end, the video is finished — clear the point. */
+export declare const RESUME_TAIL_SEC = 10;
+/**
+ * Where resume points live. Host-supplied; either method may be async. A
+ * `save(key, null)` clears the point (the video was finished, or never
+ * really started). Both are called defensively: a throw or a rejection is
+ * swallowed and reads as "nothing stored".
+ */
+export interface VideoResumeStore {
+    load(key: string): number | null | undefined | Promise<number | null | undefined>;
+    save(key: string, sec: number | null): void | Promise<void>;
+}
+/**
+ * The default store: this browser's localStorage, one entry per key. Every
+ * access is guarded — private mode, a full quota, or SSR degrade to "nothing
+ * stored", never to a thrown error in the player.
+ */
+export declare function localResumeStore(storage?: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'> | null): VideoResumeStore;
+/** A stored value → a resumable second, or null. Never throws. */
+export declare function coerceResumeSec(raw: unknown): number | null;
+/**
+ * What to persist for a position: the second itself, or null (clear) when
+ * the video is effectively unstarted or finished. Junk ⇒ undefined (write
+ * nothing — never overwrite a good point with garbage).
+ */
+export declare function resumeToSave(t: unknown, duration: unknown): number | null | undefined;
+/** The player's data → the advisor's input (extension spellings). */
+export declare function toResumeCtx(transcript: readonly VideoTranscriptSegment[] | null | undefined, speakers: readonly VideoSpeakerTurn[] | null | undefined, chapters: readonly VideoChapter[] | null | undefined): ResumeCtx;
+/** Is there anything to snap to yet? The snap waits for this. */
+export declare function hasBoundaries(ctx: ResumeCtx): boolean;
+/** What the player should do with a pending snap. */
+export type ResumeSnapPlan = {
+    kind: 'wait';
+} | {
+    kind: 'drop';
+    why: 'wheel' | 'no-move';
+} | {
+    kind: 'seek';
+    point: ResumePoint;
+};
+/**
+ * The library.js `applyResumeSnap`, pure. `stored` is the second the player
+ * resumed at; `current` where the playhead is now.
+ * · no boundaries yet ⇒ wait (it runs when they land, not at open);
+ * · the user moved > 2.5s ⇒ drop, never yank the playhead;
+ * · "exact"/"start", or a landing that isn't meaningfully earlier ⇒ drop
+ *   (no seek, and so no label — a toast on a no-op trains you to ignore it);
+ * · otherwise seek to the advisor's point and say its line.
+ */
+export declare function planResumeSnap(stored: number, current: number, ctx: ResumeCtx): ResumeSnapPlan;

package/dist/video/presence/resume.js

@@ -0,0 +1,139 @@
+/**
+ * Resume at a sentence — the component-side glue (mos-5lzns.34) around
+ * `advisors/resume-point` (.27). The snapping itself — CLOSEST wins, the 15s
+ * ceiling, ads never a landing, the quoted line — lives in the advisor and
+ * is NOT re-derived here. This file only:
+ *
+ * · defines the host-supplied persistence adapter (`VideoResumeStore`) and
+ *   its localStorage default — jatui never calls an API; a host that keeps
+ *   resume points server-side (MOS's `video_user_state`) passes its own;
+ * · maps the player's `startSec/endSec` data onto the advisor's extension
+ *   spellings (`start/end/text/speaker`, `name/ad`, `start/title`);
+ * · holds the two library.js integration decisions as pure functions:
+ *   (1) the snap runs when the boundaries LAND, not at open, and
+ *   (2) it stands down if the user has taken the wheel (> 2.5s from the
+ *       stored point by the time the data arrives).
+ */
+import { snapResume } from '../advisors/resume-point';
+/** You moved the playhead yourself — a snap now would yank it out from under you. */
+export const RESUME_WHEEL_SEC = 2.5;
+/** The advisor's hard ceiling, passed explicitly so the contract is visible here. */
+export const RESUME_MAX_BACK = 15;
+/** How often playback writes the position while it plays. */
+export const RESUME_SAVE_MS = 5_000;
+/** Below this there is nothing to resume (the advisor's START_FLOOR). */
+export const RESUME_FLOOR_SEC = 2;
+/** Within this of the end, the video is finished — clear the point. */
+export const RESUME_TAIL_SEC = 10;
+const LS_PREFIX = 'jatui.video.resume:';
+/**
+ * The default store: this browser's localStorage, one entry per key. Every
+ * access is guarded — private mode, a full quota, or SSR degrade to "nothing
+ * stored", never to a thrown error in the player.
+ */
+export function localResumeStore(storage) {
+    const ls = () => {
+        if (storage !== undefined)
+            return storage;
+        try {
+            return typeof localStorage === 'undefined' ? null : localStorage;
+        }
+        catch {
+            return null;
+        }
+    };
+    return {
+        load(key) {
+            try {
+                const raw = ls()?.getItem(LS_PREFIX + key);
+                return coerceResumeSec(raw);
+            }
+            catch {
+                return null;
+            }
+        },
+        save(key, sec) {
+            try {
+                const s = ls();
+                if (!s)
+                    return;
+                if (sec == null)
+                    s.removeItem(LS_PREFIX + key);
+                else
+                    s.setItem(LS_PREFIX + key, String(Math.round(sec * 10) / 10));
+            }
+            catch {
+                /* quota / private mode — resume is a convenience, never an error */
+            }
+        }
+    };
+}
+/** A stored value → a resumable second, or null. Never throws. */
+export function coerceResumeSec(raw) {
+    if (raw == null || raw === '')
+        return null;
+    const n = typeof raw === 'number' ? raw : Number(raw);
+    return Number.isFinite(n) && n >= RESUME_FLOOR_SEC ? n : null;
+}
+/**
+ * What to persist for a position: the second itself, or null (clear) when
+ * the video is effectively unstarted or finished. Junk ⇒ undefined (write
+ * nothing — never overwrite a good point with garbage).
+ */
+export function resumeToSave(t, duration) {
+    const s = Number(t);
+    if (!Number.isFinite(s) || s < 0)
+        return undefined;
+    if (s < RESUME_FLOOR_SEC)
+        return null;
+    const d = Number(duration);
+    if (Number.isFinite(d) && d > 0 && s >= d - Math.min(RESUME_TAIL_SEC, d * 0.03 + 1))
+        return null;
+    return s;
+}
+/** The player's data → the advisor's input (extension spellings). */
+export function toResumeCtx(transcript, speakers, chapters) {
+    return {
+        transcript: (transcript ?? []).map((s) => ({
+            start: s.startSec,
+            end: s.endSec,
+            text: s.text,
+            speaker: s.speakerName ?? undefined
+        })),
+        speakers: (speakers ?? []).map((t) => ({
+            start: t.startSec,
+            end: t.endSec,
+            name: t.speakerName ?? undefined,
+            ad: t.ad === true
+        })),
+        chapters: (chapters ?? []).map((c) => ({ start: c.startSec, title: c.title }))
+    };
+}
+/** Is there anything to snap to yet? The snap waits for this. */
+export function hasBoundaries(ctx) {
+    const n = (x) => (Array.isArray(x) ? x.length : 0);
+    return n(ctx.transcript) + n(ctx.speakers) + n(ctx.chapters) > 0;
+}
+/**
+ * The library.js `applyResumeSnap`, pure. `stored` is the second the player
+ * resumed at; `current` where the playhead is now.
+ * · no boundaries yet ⇒ wait (it runs when they land, not at open);
+ * · the user moved > 2.5s ⇒ drop, never yank the playhead;
+ * · "exact"/"start", or a landing that isn't meaningfully earlier ⇒ drop
+ *   (no seek, and so no label — a toast on a no-op trains you to ignore it);
+ * · otherwise seek to the advisor's point and say its line.
+ */
+export function planResumeSnap(stored, current, ctx) {
+    if (!Number.isFinite(stored) || !Number.isFinite(current))
+        return { kind: 'drop', why: 'no-move' };
+    if (Math.abs(current - stored) > RESUME_WHEEL_SEC)
+        return { kind: 'drop', why: 'wheel' };
+    if (!hasBoundaries(ctx))
+        return { kind: 'wait' };
+    const point = snapResume(stored, ctx, { maxBack: RESUME_MAX_BACK });
+    if (point.reason === 'exact' || point.reason === 'start')
+        return { kind: 'drop', why: 'no-move' };
+    if (point.at >= stored - 0.05)
+        return { kind: 'drop', why: 'no-move' };
+    return { kind: 'seek', point };
+}

package/dist/video/presence/winddown.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Wind-down — the pure half (mos-5lzns.34). extension-library FEATURES.md
+ * §Wind-down, re-based from `hyprctl cursorpos` + `hyprlock` onto the
+ * browser's two signals (see ./idle.ts for how they are gathered).
+ *
+ * The signal question is the whole design. Page input cannot answer it on
+ * its own: a video legitimately plays for two hours with nobody touching a
+ * key, so "no input here" describes watching exactly as well as it
+ * describes sleeping. The DESKTOP can answer it — Chromium's Idle Detection
+ * API reports system-wide user idle and a locked screen. Everywhere else the
+ * player falls back to page presence, and says so (`source: 'page'`): the
+ * behaviour is the same, the evidence is weaker, and the host must be able
+ * to label it as such.
+ *
+ * It never just stops. `WIND_DOWN_FADE_MS` of frames: volume falls linearly
+ * to zero while a neutral veil over the picture rises to `0.92·p` — a veil,
+ * never the video's own opacity, which would let whatever is behind the
+ * player (the page, the bias light) show through and BRIGHTEN it. Any input
+ * cancels, restores the saved volume, and playback carries on. The fade IS
+ * the prompt — a gentler question than a modal asking whether you are alive.
+ *
+ * Nothing here touches the element or reads a setting; the component passes
+ * the knobs in and applies what comes back.
+ */
+/** The fade itself — twenty seconds, and the fade is the prompt. */
+export declare const WIND_DOWN_FADE_MS = 20000;
+/** The veil's opacity at the end of the fade (the picture keeps 1 − 0.92). */
+export declare const WIND_DOWN_DEPTH = 0.92;
+/** Minutes of absence before the fade begins — the extension's `sleep.after`. */
+export declare const WIND_DOWN_AFTER_DEFAULT = 30;
+export declare const WIND_DOWN_AFTER_MIN = 10;
+export declare const WIND_DOWN_AFTER_MAX = 90;
+/**
+ * How often the component re-asks the question while armed and playing.
+ * Shorter than the extension's 60s because the answer is now local and
+ * free; the decision still only ever acts on a threshold of minutes.
+ */
+export declare const WIND_DOWN_PROBE_MS = 15000;
+/**
+ * Where the evidence of absence came from.
+ * · `desktop` — Idle Detection API: system-wide idle + screen lock. Full fidelity.
+ * · `page`    — no input on this page. Lower fidelity, labelled as such.
+ */
+export type PresenceSource = 'desktop' | 'page';
+/** The desktop's two raw facts (IdleDetector's userState/screenState). */
+export interface DesktopSignal {
+    idle: boolean;
+    locked: boolean;
+}
+export type WindDownPhase = 'off' | 'watching' | 'fading' | 'paused';
+/** Reported to the host on real change only. */
+export interface WindDownState {
+    phase: WindDownPhase;
+    /** Which evidence the player is using right now; null when the feature is off. */
+    source: PresenceSource | null;
+}
+/** Clamp a minutes knob to the declared range; junk falls back to the default. */
+export declare function windDownAfterMs(minutes: unknown): number;
+export interface WindDownInput {
+    /** Feature on, and (if night-only) night armed. */
+    armed: boolean;
+    playing: boolean;
+    /** Already fading or already paused by us — nothing more to begin. */
+    active: boolean;
+    source: PresenceSource;
+    /** Latest desktop facts; null when the desktop source has no reading yet. */
+    desktop: DesktopSignal | null;
+    /** ms since the last input on the page. */
+    quietMs: number;
+    /** The threshold, ms (windDownAfterMs). */
+    afterMs: number;
+    /**
+     * The document is hidden. Page presence holds while it is: silence on a
+     * background tab says nothing about whether you are at the machine —
+     * you may be busy in another one. The desktop source ignores it (a
+     * locked screen hides the document, and that is exactly its case).
+     */
+    hidden?: boolean;
+}
+/**
+ * Should the fade begin now? Never guesses: a desktop source with no reading
+ * yet holds (the extension's "no desktop signal → never wind down"), and
+ * junk numbers hold.
+ *
+ * A locked screen skips the wait entirely — that is not an inference, it is
+ * a statement. Desktop idle already carries the threshold (the detector is
+ * started with it), so `idle` alone is sufficient there.
+ */
+export declare function shouldBeginWindDown(i: WindDownInput): boolean;
+/** A desktop reading that says someone is there — cancels a fade in progress. */
+export declare function desktopPresent(d: DesktopSignal | null | undefined): boolean;
+/** Fade progress 0–1 from elapsed ms. Junk ⇒ 0 (nothing faded). */
+export declare function windDownProgress(elapsedMs: unknown, fadeMs?: number): number;
+/**
+ * The levels at progress p: the volume factor (× the volume saved at the
+ * start of the fade), the veil's opacity, and what that leaves of the
+ * picture. Linear on purpose — the extension's, and a sleeping viewer is not
+ * tracking a curve.
+ */
+export declare function windDownLevels(p: unknown): {
+    volume: number;
+    veil: number;
+    picture: number;
+};
+/** The visible surface. The page source says it is guessing from less. */
+export declare function windDownHint(phase: 'fading' | 'paused', source: PresenceSource): string;

package/dist/video/presence/winddown.js

@@ -0,0 +1,104 @@
+/**
+ * Wind-down — the pure half (mos-5lzns.34). extension-library FEATURES.md
+ * §Wind-down, re-based from `hyprctl cursorpos` + `hyprlock` onto the
+ * browser's two signals (see ./idle.ts for how they are gathered).
+ *
+ * The signal question is the whole design. Page input cannot answer it on
+ * its own: a video legitimately plays for two hours with nobody touching a
+ * key, so "no input here" describes watching exactly as well as it
+ * describes sleeping. The DESKTOP can answer it — Chromium's Idle Detection
+ * API reports system-wide user idle and a locked screen. Everywhere else the
+ * player falls back to page presence, and says so (`source: 'page'`): the
+ * behaviour is the same, the evidence is weaker, and the host must be able
+ * to label it as such.
+ *
+ * It never just stops. `WIND_DOWN_FADE_MS` of frames: volume falls linearly
+ * to zero while a neutral veil over the picture rises to `0.92·p` — a veil,
+ * never the video's own opacity, which would let whatever is behind the
+ * player (the page, the bias light) show through and BRIGHTEN it. Any input
+ * cancels, restores the saved volume, and playback carries on. The fade IS
+ * the prompt — a gentler question than a modal asking whether you are alive.
+ *
+ * Nothing here touches the element or reads a setting; the component passes
+ * the knobs in and applies what comes back.
+ */
+/** The fade itself — twenty seconds, and the fade is the prompt. */
+export const WIND_DOWN_FADE_MS = 20_000;
+/** The veil's opacity at the end of the fade (the picture keeps 1 − 0.92). */
+export const WIND_DOWN_DEPTH = 0.92;
+/** Minutes of absence before the fade begins — the extension's `sleep.after`. */
+export const WIND_DOWN_AFTER_DEFAULT = 30;
+export const WIND_DOWN_AFTER_MIN = 10;
+export const WIND_DOWN_AFTER_MAX = 90;
+/**
+ * How often the component re-asks the question while armed and playing.
+ * Shorter than the extension's 60s because the answer is now local and
+ * free; the decision still only ever acts on a threshold of minutes.
+ */
+export const WIND_DOWN_PROBE_MS = 15_000;
+/** Clamp a minutes knob to the declared range; junk falls back to the default. */
+export function windDownAfterMs(minutes) {
+    const n = typeof minutes === 'number' ? minutes : Number(minutes);
+    const m = Number.isFinite(n)
+        ? Math.min(WIND_DOWN_AFTER_MAX, Math.max(WIND_DOWN_AFTER_MIN, n))
+        : WIND_DOWN_AFTER_DEFAULT;
+    return m * 60_000;
+}
+/**
+ * Should the fade begin now? Never guesses: a desktop source with no reading
+ * yet holds (the extension's "no desktop signal → never wind down"), and
+ * junk numbers hold.
+ *
+ * A locked screen skips the wait entirely — that is not an inference, it is
+ * a statement. Desktop idle already carries the threshold (the detector is
+ * started with it), so `idle` alone is sufficient there.
+ */
+export function shouldBeginWindDown(i) {
+    if (!i || !i.armed || !i.playing || i.active)
+        return false;
+    if (i.source === 'desktop') {
+        const d = i.desktop;
+        if (!d)
+            return false;
+        return d.locked === true || d.idle === true;
+    }
+    if (i.hidden === true)
+        return false;
+    const quiet = Number(i.quietMs);
+    const after = Number(i.afterMs);
+    if (!Number.isFinite(quiet) || !Number.isFinite(after) || after <= 0)
+        return false;
+    return quiet >= after;
+}
+/** A desktop reading that says someone is there — cancels a fade in progress. */
+export function desktopPresent(d) {
+    return !!d && d.idle === false && d.locked === false;
+}
+/** Fade progress 0–1 from elapsed ms. Junk ⇒ 0 (nothing faded). */
+export function windDownProgress(elapsedMs, fadeMs = WIND_DOWN_FADE_MS) {
+    const e = Number(elapsedMs);
+    const f = Number(fadeMs);
+    if (!Number.isFinite(e) || e <= 0 || !Number.isFinite(f) || f <= 0)
+        return 0;
+    return Math.min(1, e / f);
+}
+/**
+ * The levels at progress p: the volume factor (× the volume saved at the
+ * start of the fade), the veil's opacity, and what that leaves of the
+ * picture. Linear on purpose — the extension's, and a sleeping viewer is not
+ * tracking a curve.
+ */
+export function windDownLevels(p) {
+    const n = Number(p);
+    const q = Number.isFinite(n) ? Math.min(1, Math.max(0, n)) : 0;
+    const veil = WIND_DOWN_DEPTH * q;
+    return { volume: 1 - q, veil, picture: 1 - veil };
+}
+/** The visible surface. The page source says it is guessing from less. */
+export function windDownHint(phase, source) {
+    if (phase === 'paused')
+        return 'Paused — you were away';
+    return source === 'desktop'
+        ? 'Winding down — move anything to stay'
+        : 'Winding down (no activity on this page) — move anything to stay';
+}

package/dist/video/presence.d.ts

@@ -1,25 +1,29 @@
 /**
- * Presence module — CONTRACT ONLY (mos-5lzns.28). Implemented by mos-5lzns.34
- * ("wind-down (Idle Detection API), resume-at-sentence, FLIP open").
+ * Presence (mos-5lzns.34) — the barrel. Three behaviours about whether you
+ * are there and where you were, each an OPTIONAL VideoPlayer prop that is
+ * inert when absent (extension-library FEATURES.md §Wind-down, §Resume at a
+ * sentence, §Open like an object):
  *
- * What lands here (extension-library FEATURES.md §Wind-down,
- * §Resume at a sentence, §Open like an object), as ADVISORS + pure helpers:
+ * · `presence/winddown.ts` — pure: the begin decision, fade levels, hint.
+ *   The desktop says nobody is there → picture and sound fade over 20s and
+ *   the video pauses. The fade IS the prompt; any input cancels it.
+ * · `presence/idle.ts` — the desktop signal: Chromium's Idle Detection API,
+ *   feature-detected, never prompting unless the host opted in (and then
+ *   only from a gesture). Elsewhere the player falls back to page presence,
+ *   reported as `source: 'page'` so the host can label it.
+ * · `presence/resume.ts` — resume-at-sentence glue around .27's
+ *   `advisors/resume-point` (the snapping is NOT duplicated here): the
+ *   host-supplied store (localStorage default), the data mapping, and the
+ *   two integration rules — snap when the boundaries land, stand down once
+ *   the user has taken the wheel.
+ * · `presence/flip.ts` — FLIP open/close over WAAPI with the poster painted
+ *   on every path; a no-op under prefers-reduced-motion except the poster.
  *
- * · wind-down — the desktop says nobody is there (Idle Detection API / user
- *   activity), the player fades picture and sound over ~20s and pauses. The
- *   fade IS the prompt — cancelling it is how you come back.
- * · resume-at-sentence — snap a resume point back to the nearest sentence /
- *   speaker turn / chapter within 15s (CLOSEST wins, not most-specific);
- *   quote the line, never paraphrase; stand down if the user has taken the
- *   wheel (>2.5s from the stored point). Runs when the transcript lands, not
- *   at open.
- * · FLIP open — the clicked card's rectangle → the player shell, WAAPI, two
- *   keyframes, transform-origin top-left, poster painted under the video on
- *   EVERY path (a black rectangle is a bug at any motion setting); no-op
- *   under prefers-reduced-motion except the poster.
- *
- * All three are advisors/mechanics: they read no settings, touch no
- * <video> outside the callbacks the component passes, and fail toward doing
- * nothing.
+ * Advisors and mechanics: they read no settings and touch no <video>; the
+ * component passes knobs in and applies what comes back, and every one of
+ * them fails toward doing nothing.
  */
-export declare const PRESENCE_NEUTRAL = 1;
+export { WIND_DOWN_FADE_MS, WIND_DOWN_DEPTH, WIND_DOWN_AFTER_DEFAULT, WIND_DOWN_AFTER_MIN, WIND_DOWN_AFTER_MAX, WIND_DOWN_PROBE_MS, windDownAfterMs, shouldBeginWindDown, desktopPresent, windDownProgress, windDownLevels, windDownHint, type PresenceSource, type DesktopSignal, type WindDownPhase, type WindDownState, type WindDownInput } from './presence/winddown';
+export { IDLE_THRESHOLD_MIN_MS, idleDetectionSupported, idleDetectionPermission, requestIdleDetection, startDesktopWatch, toDesktopSignal, type IdlePermission, type DesktopWatch } from './presence/idle';
+export { RESUME_WHEEL_SEC, RESUME_MAX_BACK, RESUME_SAVE_MS, RESUME_FLOOR_SEC, RESUME_TAIL_SEC, localResumeStore, coerceResumeSec, resumeToSave, toResumeCtx, hasBoundaries, planResumeSnap, type VideoResumeStore, type ResumeSnapPlan } from './presence/resume';
+export { FLIP_EASE, FLIP_OPEN_MS, FLIP_CLOSE_MS, FLIP_FADE_WITH_POSTER, FLIP_FADE_BARE, FLIP_POSTER_CLASS, flipOpen, flipClose, clearPoster, posterBackground, rectOf, onScreen, flipGeometry, awayFrame, homeFrame, type FlipSource, type FlipRect } from './presence/flip';