@joewinke/jatui 0.13.0 → 0.15.0

package/dist/components/VideoPlayer.svelte.d.ts

@@ -4,12 +4,18 @@ export type { VideoLumaTrack } from '../video/band/luma';
 export type { VideoMarker } from '../video/band/markers';
 export type { NightMode, NightWindow } from '../video/night/clock';
 export type { AudioState, AudioStatus, AudioBrokenReason } from '../video/audio/graph';
+export type { VideoAdSpan, RateReport } from '../video/rate';
+export type { WindDownState, WindDownPhase, PresenceSource, VideoResumeStore, FlipSource } from '../video/presence';
+export type { ResumePoint } from '../video/advisors/resume-point';
 import type { VideoBookmark, VideoChapter, VideoSpeakerTalkTime, VideoSpeakerTurn, VideoTranscriptSegment, VideoWaveform } from '../video/types';
 import { type BandState } from '../video/band/axis';
 import { type VideoLumaTrack } from '../video/band/luma';
 import { type VideoMarker } from '../video/band/markers';
+import { type RateReport, type VideoAdSpan } from '../video/rate';
 import { type NightMode, type NightWindow } from '../video/night/clock';
 import { type AudioBrokenReason, type AudioState } from '../video/audio';
+import { type FlipSource, type VideoResumeStore, type WindDownState } from '../video/presence';
+import type { ResumePoint } from '../video/advisors/resume-point';
 type $$ComponentProps = {
     src: string;
     poster?: string | null;
@@ -180,6 +186,108 @@ type $$ComponentProps = {
     onAudioState?: (state: AudioState) => void;
     /** Entered `broken`: 'build-failed' | 'unsafe-src' | 'silent' (see above). */
     onAudioBroken?: (reason: AudioBrokenReason) => void;
+    /**
+     * Rate composer (mos-5lzns.32): `rate = base × speaker × silence`. The
+     * speed readout only ever reports `base` — the rate a human chose — so it
+     * keeps saying `1×` while a gap is taken at 2.2×. Every advisor is off by
+     * default and collapses to 1 until its data arrives: off, the element
+     * plays at exactly `base`.
+     *
+     * Smart speed: run the silences between sentences at 2.2×, found off the
+     * `waveform` envelope. Speech stays at `base`.
+     */
+    smartSpeed?: boolean;
+    /**
+     * Per-speaker pace: level everyone to the median words-per-minute,
+     * measured from the diarised `transcript` + `speakers`. Ad reads and
+     * gaps between turns play at `base`.
+     */
+    speakerPace?: boolean;
+    /**
+     * Hand-set speaker rates keyed by speaker NAME (the legend's display
+     * name). They always beat measured ones, and like them apply only while
+     * `speakerPace` is on — off means off. Range 0.0625–16.
+     */
+    speakerRates?: Record<string, number> | null;
+    /** Host-detected ad reads. Merged with any `ad: true` speaker turns. */
+    adSpans?: VideoAdSpan[] | null;
+    /**
+     * Skip ad reads: when playback runs into an ad span it jumps to its end
+     * (the OSD says so). A seek that lands inside an ad is honoured.
+     */
+    skipAds?: boolean;
+    /** The composed rate changed (real change only). `base` is what the UI shows. */
+    onRateChange?: (report: RateReport) => void;
+    /**
+     * Wind-down (mos-5lzns.34): when nobody is there, the picture and sound
+     * fade over 20s and the video pauses, keeping your place. The fade IS
+     * the prompt — any input anywhere on the page (or the desktop coming
+     * back) cancels it and brings everything straight back. Omitted/false ⇒
+     * the feature does not exist on this player: no listeners, no timers,
+     * no variables.
+     *
+     * The evidence of absence is the DESKTOP when `idleDetection` is on and
+     * granted (Chromium's Idle Detection API: system-wide idle, and a locked
+     * screen skips the wait entirely); otherwise it is PAGE presence — no
+     * input on this page for `windDownAfter` minutes — which is weaker
+     * evidence (a video legitimately plays for an hour untouched), and is
+     * reported as `source: 'page'` so the host can label it.
+     */
+    windDown?: boolean;
+    /** Minutes of absence before the fade begins, 10–90 (default 30). */
+    windDownAfter?: number;
+    /**
+     * Only wind down while night is armed (default true — falling asleep
+     * mid-video is a night problem). Uses the `night` mode when present,
+     * else the local-clock auto window.
+     */
+    windDownNightOnly?: boolean;
+    /**
+     * Opt in to the Idle Detection API (Chromium only; permission-gated).
+     * The player NEVER prompts without this. Already granted ⇒ it starts at
+     * once; still `prompt` ⇒ the permission is requested on the next click
+     * or key inside the player (the API needs a user gesture). Better: call
+     * `requestIdleDetection()` from the click that enables the setting.
+     * Unsupported or denied ⇒ the page-presence fallback, reported.
+     */
+    idleDetection?: boolean;
+    /** Phase/source changes: `off` | `watching` | `fading` | `paused`, and `desktop` | `page`. */
+    onWindDown?: (state: WindDownState) => void;
+    /**
+     * Resume (mos-5lzns.34): present ⇒ the player remembers where this video
+     * was left under this key and returns there when it opens again. An
+     * explicit `startAt` or a `?t=` deep link always wins over a stored point.
+     */
+    resumeKey?: string | null;
+    /**
+     * Where resume points live — `{ load(key), save(key, sec | null) }`,
+     * either may be async. Default: this browser's localStorage. jatui never
+     * calls an API; a host with per-user server state passes its own.
+     */
+    resumeStore?: VideoResumeStore;
+    /**
+     * Snap the resume point back to the nearest sentence / speaker turn /
+     * chapter within 15s once that data lands, and say the line you're
+     * walking back into (quoted, never paraphrased). Stands down if you've
+     * moved the playhead yourself. Default on; off ⇒ the raw second.
+     */
+    resumeSnap?: boolean;
+    /** The player moved the playhead for a resume: `from` the stored second, to `point`. */
+    onResume?: (from: number, point: ResumePoint) => void;
+    /**
+     * Open like an object (mos-5lzns.34): the clicked card (an element or a
+     * rect snapshot). Present ⇒ on mount the stage grows out of that
+     * rectangle (FLIP over WAAPI, 260ms) with `openPoster` painted over the
+     * video until its first frame decodes. `null` ⇒ the poster only. The
+     * poster paints on EVERY path — under prefers-reduced-motion, with
+     * `openMotion` off, or with the card scrolled away — because a black
+     * rectangle is a bug at any motion setting. Omitted ⇒ nothing changes.
+     */
+    openFrom?: FlipSource | null;
+    /** The card's (already-loaded) thumbnail. Defaults to `poster`. */
+    openPoster?: string | null;
+    /** Run the motion half of the open (default true). Off ⇒ poster only. */
+    openMotion?: boolean;
     class?: string;
 };
 declare const VideoPlayer: import("svelte").Component<$$ComponentProps, {

package/dist/index.d.ts

@@ -12,7 +12,9 @@ export type { ChapterBlock } from './components/replay/ChapterTimeline.svelte';
 export { default as TranscriptPlayer } from './components/TranscriptPlayer.svelte';
 export type { TranscriptSegment, TranscriptBookmark, TranscriptChapter, TranscriptSpeakerTalkTime, } from './components/TranscriptPlayer.svelte';
 export { default as VideoPlayer } from './components/VideoPlayer.svelte';
-export type { VideoChapter, VideoSpeakerTurn, VideoTranscriptSegment, VideoBookmark, VideoWaveform, VideoSpeakerTalkTime, VideoLumaTrack, VideoMarker, BandState, BandAxis, NightMode, NightWindow, AudioState, AudioStatus, AudioBrokenReason, } from './components/VideoPlayer.svelte';
+export type { VideoChapter, VideoSpeakerTurn, VideoTranscriptSegment, VideoBookmark, VideoWaveform, VideoSpeakerTalkTime, VideoLumaTrack, VideoMarker, BandState, BandAxis, NightMode, NightWindow, AudioState, AudioStatus, AudioBrokenReason, VideoAdSpan, RateReport, WindDownState, WindDownPhase, PresenceSource, VideoResumeStore, FlipSource, } from './components/VideoPlayer.svelte';
+export { speakerRateMap, toRateTurns, toRateSegments } from './video/rate';
+export { idleDetectionSupported, idleDetectionPermission, requestIdleDetection, localResumeStore, flipOpen, flipClose, clearPoster, type IdlePermission } from './video/presence';
 export { buildSilenceMap, boostAt, estimateSaving, type SilenceMap, type SilenceWave, type SilenceOpts, type BoostOpts } from './video/advisors/smart-speed';
 export { speakerPace, suggestRates, rateAt, describeRates, type SpeakerPace, type SpeakerPaceRow, type RateMap, type RateTurn, type RateSegment, type SuggestOpts } from './video/advisors/speaker-rate';
 export { snapResume, resumeLabel, type ResumePoint, type ResumeReason, type ResumeCtx, type ResumeOpts } from './video/advisors/resume-point';

package/dist/index.js

@@ -13,6 +13,15 @@ export { default as TranscriptPlayer } from './components/TranscriptPlayer.svelt
 // optional so a bare mp4 still gets the full playback UX. TranscriptPlayer
 // stays exported unchanged — meetings already depends on it.
 export { default as VideoPlayer } from './components/VideoPlayer.svelte';
+// Rate composer (mos-5lzns.32): the same name → rate table the player applies
+// under `speakerPace` (manual beats measured), for a host drawing its own
+// per-speaker speed UI.
+export { speakerRateMap, toRateTurns, toRateSegments } from './video/rate';
+// Presence (mos-5lzns.34): the permission call a host makes from the click
+// that enables wind-down's desktop signal (the API needs a user gesture),
+// the default resume store, and the FLIP pair for a host animating its own
+// theater shell (e.g. flipClose back onto the card).
+export { idleDetectionSupported, idleDetectionPermission, requestIdleDetection, localResumeStore, flipOpen, flipClose, clearPoster } from './video/presence';
 // Pure advisors (mos-5lzns.27): the extension-library self-test modules,
 // ported verbatim. They measure and advise; the player's feature tasks
 // (.31 audio / .32 rate / .34 presence) consume them. qrCanvas is the one

package/dist/video/README.md

@@ -17,17 +17,17 @@ props + callback surfaces.
 | `band.ts` | .28 (done) — extended by **.30** | The timeline band: zoom window (`BandWindow`, `zoomAt`, `followPlayhead`), hit tests (`segmentAt`, `chapterAt`, `biasToSegmentStart`, `nearestBookmark`), and `paintBand` (canvas). .30 adds one-axis arbitration + the light ribbon; its state lives HERE. |
 | `band/` | **.30** (done) | `window.ts` — the zoom-window math (moved out of band.ts, re-exported there; shared by every band layer without an import cycle). `axis.ts` — one-axis four-state arbitration (`resolveAxis`, `BandState`, the churn-guarded microtask `createBandReporter`), `playheadX` (the one "where you are" mapping — ≤0.2px agreement) and `overviewBracket`. `luma.ts` — the light track (`VideoLumaTrack`, the sidecar verbatim) → ribbon (`v² × 0.55`, max-per-interval). `markers.ts` — `VideoMarker` comments (clustered dots) + like heat. |
 | `keys.ts` | .28 (done) | The keyboard map — `PLAYER_KEYS` (the `?` overlay renders it), `chapterJump`, `FRAME_STEP_SEC`. Every key that exists is in the map; a key not in the map doesn't exist. |
-| `rate.ts` | .28 (done) — filled by **.32** | The rate composer contract (`composeRate`, deadband, clamp), the `SPEED_STEPS` staircase, `formatSpeedLabel`. .32 adds the speaker-pace and silence-map advisors — they never write `playbackRate`; they advise. |
+| `rate.ts` + `rate/` | .28 contract — **.32** (done) | `rate.ts` is the barrel. `compose.ts` — the contract (`composeRate`, clamp [0.0625, 16], `shouldWriteRate`'s 0.001 deadband with an exact return to base), the `SPEED_STEPS` staircase, `formatSpeedLabel`. `speaker.ts` — props → `advisors/speaker-rate`; manual rates keyed by NAME always beat measured. `silence.ts` — waveform → `advisors/smart-speed` map + boost + the OSD saving claim. `ads.ts` — `adSpans` ∪ `ad: true` turns; skip only when PLAYBACK runs into an ad, never when a seek lands in one. `tick.ts` — the component's own 120ms loop's one-tick decision. None of them write `playbackRate`; they advise. |
 | `deepLink.ts` | .28 (done) | `?t=` parse/format/read/write (replaceState, throttled, other params preserved). |
 | `settings.ts` | shared — knobs added by .30–.34 | `coerce` (never throws, never junk) + `VIDEO_SETTINGS` registry. A knob lands WITH its reader. |
 | `audio.ts` + `audio/` | **.31** (done) | `audio.ts` is the barrel. `rider.ts` — pure: RMS dBFS (silence → null), the 12 dB relative-gated loud estimate (rise 0.08 / forget 0.01), want-gain clamped 0.3–1.35, the asymmetric ride (down 0.15 / up 0.02), limiter constants + `compressorMakeupDb`/`limiterTrim` (DynamicsCompressor's automatic makeup, cancelled by a trim node), `routeSafety` (only blob:/data: or a `crossorigin` load — a same-origin URL may redirect cross-origin and route to SILENCE). `graph.ts` — `createAudioSession`: source → gain → quiet chain → limiter → trim → destination, analyser on the source. Context first, route last: the element is taken only when a feature is on, the source is route-safe and `ctx.state === 'running'` (gestures resume + retry; never navigator.userActivation). After routing it watches: an unsafe src or bit-exact zeros while audibly playing ⇒ `broken` (`unsafe-src` / `silent`) via `onBroken`. A construction throw is a permanent `build-failed` (context closed if the element wasn't taken; kept with source → destination if it was). Level off cancels before it sets; limiter moves are ramped. The element never enters the module — the component passes a `route` closure. |
 | `night.ts` + `night/` | **.33** (done) | `night.ts` is the barrel. `meter.ts` — 32×18 frame bytes → Rec.709 luma + blown share, asymmetric smoothing, bias-light cells from the same bytes. `levels.ts` — luma → brightness/saturation/warmth/vignette off `NIGHT_FLOOR` 0.34, blind fixed level, the light-theme surround. `clock.ts` — local-clock `auto` window + the `N` auto/on/off cycle (no hyprsunset). `track.ts` — prediction (only ever adds dimming), flash intervals, `composeNight` (darker at once, brighter released per tick — never a jump). |
-| `presence.ts` | **.34** | Wind-down (Idle Detection), resume-at-sentence, FLIP open. |
+| `presence.ts` + `presence/` | **.34** (done) | `presence.ts` is the barrel. `winddown.ts` — pure: `shouldBeginWindDown` (a locked screen skips the wait; a desktop source with no reading holds — never guess), the 20s linear fade levels (volume `1−p`, picture `1−0.92p`), the hint (the page source says it is guessing from less). `idle.ts` — Chromium's Idle Detection API, feature-detected (`IdleDetector` + secure context); `startDesktopWatch` never prompts (start() rejects unless already granted ⇒ page fallback), `requestIdleDetection` is the ONE prompting call and the player makes it only with `idleDetection` on, from a gesture inside it. `resume.ts` — the host-supplied `VideoResumeStore` (localStorage default; jatui never calls an API), the data → advisor mapping, and `planResumeSnap` (wait for boundaries, drop once the user moved > 2.5s, skip `exact`/`start`); the snapping itself is `advisors/resume-point`, not re-derived. `flip.ts` — `open-transition.js` ported: FLIP over WAAPI, two keyframes, origin restated in both, poster on every path, a no-op under prefers-reduced-motion except the poster, `flipClose` holds and the next open releases on every path. |
 | `advisors/` | **.27 (done)** | The five extension-library pure advisors, ported verbatim: `smart-speed` (silence map + boost), `speaker-rate` (measured wpm + suggested rates), `resume-point` (sentence-snapping + the label), `quiet-listening` (tone-only chain + `amountFor`), `qr` (ISO 18004 encoder v1–10). Each has its own README row in `advisors/README.md`; the `--self-test` suites live on as vitest in `tests/unit/advisors/` (`npm run test:advisors`). |
 
 Sub-task map: **.30** scrubbing/one-axis/ribbon/markers → `band.ts` (+ its own
 paint layers); **.31** audio graph → `audio.ts`; **.32** rate composer →
-`rate.ts` advisors; **.33** night → `night.ts`; **.34** presence/wind-down →
+`rate.ts` + `rate/`; **.33** night → `night.ts`; **.34** presence/wind-down →
 `presence.ts`. **.27** (landed) ports the advisors themselves — .31's chain
 builder and `amountFor` live in `advisors/quiet-listening`, .32's two advisor
 modules in `advisors/smart-speed` + `advisors/speaker-rate`, .34's snapping in

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

@@ -0,0 +1,145 @@
+/**
+ * Open like an object (mos-5lzns.34) — extension-library
+ * `lib/open-transition.js`, ported. The card you pointed at becomes the
+ * thing you're watching.
+ *
+ * Opening a video read as a cut, for two different reasons:
+ * · the rectangle is BLACK because <video> paints its own opaque letterbox
+ *   before it has a frame — fix: paint the card's (already-loaded) thumbnail
+ *   over that box on the same frame the player appears, so there is no
+ *   instant at which the player is empty;
+ * · it is a CUT because nothing carries the eye — fix: move the shell from
+ *   the card's rectangle to its own.
+ *
+ *   flipOpen({ from, shell, poster?, hasPoster?, duration? })  -> Promise<void>
+ *   flipClose({ to, shell, duration? })                        -> Promise<void>
+ *   clearPoster(shell)                  — call on the video's `loadeddata`
+ *
+ * FLIP (read both rects, invert with a transform, play), never an animated
+ * box: width/height/top/left is a layout property per frame. WAAPI, never
+ * CSS classes: it works with no stylesheet cooperation and never writes the
+ * `style` attribute, so "no inline styles left behind" is structural — the
+ * `will-change` hint is reclaimed by name on finish AND cancel.
+ *
+ * `transformOrigin: 0 0` is restated in BOTH keyframes (a property named in
+ * only one keyframe interpolates toward the default and silently breaks the
+ * translate/scale pair). Two keyframes, never three: `easing` is the
+ * effect's timing function, so a hand-placed offset lands somewhere other
+ * than where it reads. The scale is non-uniform on purpose — matching the
+ * card's outline exactly is what hides the seam.
+ *
+ * Every entry point is a no-op returning a resolved Promise when it has
+ * nothing honest to animate — no source, a source scrolled off screen, an
+ * unmeasurable shell, `prefers-reduced-motion`, or geometry already
+ * congruent within 1px / 1%. THE POSTER IS THE EXCEPTION: it is painted on
+ * every one of those paths, because a black rectangle is a bug at any
+ * motion setting, not a flourish someone opted out of.
+ *
+ * `flipClose` holds its end state (`fill: forwards`) — snapping back to full
+ * size on the last frame would flash the whole player right before the host
+ * hides it. The hold is released by the next `flipOpen` on EVERY path,
+ * including the no-op ones, so a shell reopened under reduced motion can
+ * never sit shrunk at the last card's position.
+ *
+ * The one DOM-touching module in presence/ besides idle.ts; its globals are
+ * injectable (`g`) so node:test drives it with fakes.
+ */
+/** The app's one state-change curve. */
+export declare const FLIP_EASE = "cubic-bezier(.25, 1, .5, 1)";
+export declare const FLIP_OPEN_MS = 260;
+export declare const FLIP_CLOSE_MS = 200;
+/** Opacity the shell starts at: shallow with a picture on screen, deeper without. */
+export declare const FLIP_FADE_WITH_POSTER = 0.7;
+export declare const FLIP_FADE_BARE = 0.25;
+export declare const FLIP_POSTER_CLASS = "jatui-flip-poster";
+/** Anything with a rectangle: an Element, a DOMRect, or a snapshot of one. */
+export type FlipSource = {
+    getBoundingClientRect(): {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+} | {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+};
+export interface FlipRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+type Globals = {
+    matchMedia?: (q: string) => {
+        matches: boolean;
+    };
+    innerWidth?: number;
+    innerHeight?: number;
+    document?: {
+        createElement(tag: string): unknown;
+    };
+    getComputedStyle?: (el: unknown) => {
+        position?: string;
+        borderRadius?: string;
+    };
+};
+/**
+ * Duck-types an Element or a rect snapshot (a virtualised grid may hand over
+ * a rect it measured before the card went away). Zero-sized or non-finite ⇒
+ * null — never divide a scale factor by nothing.
+ */
+export declare function rectOf(x: unknown): FlipRect | null;
+/** Any part of the rect inside the viewport. Unknown viewport ⇒ assume visible. */
+export declare function onScreen(r: FlipRect, vw: unknown, vh: unknown): boolean;
+/**
+ * The inversion — "put my corner on the card's corner, shrink to its size".
+ * Null when the boxes already coincide (within 1px / 1%) or can't be scaled.
+ */
+export declare function flipGeometry(visual: FlipRect, layout: FlipRect): {
+    dx: number;
+    dy: number;
+    sx: number;
+    sy: number;
+} | null;
+export declare function awayFrame(g: {
+    dx: number;
+    dy: number;
+    sx: number;
+    sy: number;
+}): Keyframe;
+export declare function homeFrame(): Keyframe;
+/**
+ * A poster string → a safe `background-image` value, or "" for none. A bare
+ * URL containing a quote, paren or backslash emits nothing rather than a
+ * broken declaration that would take the whole rule with it.
+ */
+export declare function posterBackground(poster: unknown): string;
+/** Remove a poster painted by flipOpen (and the position it may have needed). */
+export declare function clearPoster(shell: unknown): void;
+/**
+ * Grow `shell` out of `from`'s rectangle. `poster` (a URL or CSS image) is
+ * painted into the shell on EVERY path; a host that paints its own poster
+ * passes `hasPoster: true` instead so the fade depth matches.
+ */
+export declare function flipOpen(opts?: {
+    from?: FlipSource | null;
+    shell?: unknown;
+    poster?: string | null;
+    hasPoster?: boolean;
+    duration?: number;
+    g?: Globals;
+}): Promise<void>;
+/**
+ * Shrink `shell` back onto `to` and HOLD there (the host hides it after).
+ * No opacity: the last frame before the host hides the shell IS the card.
+ */
+export declare function flipClose(opts?: {
+    to?: FlipSource | null;
+    shell?: unknown;
+    duration?: number;
+    g?: Globals;
+}): Promise<void>;
+export {};

package/dist/video/presence/flip.js

@@ -0,0 +1,253 @@
+/**
+ * Open like an object (mos-5lzns.34) — extension-library
+ * `lib/open-transition.js`, ported. The card you pointed at becomes the
+ * thing you're watching.
+ *
+ * Opening a video read as a cut, for two different reasons:
+ * · the rectangle is BLACK because <video> paints its own opaque letterbox
+ *   before it has a frame — fix: paint the card's (already-loaded) thumbnail
+ *   over that box on the same frame the player appears, so there is no
+ *   instant at which the player is empty;
+ * · it is a CUT because nothing carries the eye — fix: move the shell from
+ *   the card's rectangle to its own.
+ *
+ *   flipOpen({ from, shell, poster?, hasPoster?, duration? })  -> Promise<void>
+ *   flipClose({ to, shell, duration? })                        -> Promise<void>
+ *   clearPoster(shell)                  — call on the video's `loadeddata`
+ *
+ * FLIP (read both rects, invert with a transform, play), never an animated
+ * box: width/height/top/left is a layout property per frame. WAAPI, never
+ * CSS classes: it works with no stylesheet cooperation and never writes the
+ * `style` attribute, so "no inline styles left behind" is structural — the
+ * `will-change` hint is reclaimed by name on finish AND cancel.
+ *
+ * `transformOrigin: 0 0` is restated in BOTH keyframes (a property named in
+ * only one keyframe interpolates toward the default and silently breaks the
+ * translate/scale pair). Two keyframes, never three: `easing` is the
+ * effect's timing function, so a hand-placed offset lands somewhere other
+ * than where it reads. The scale is non-uniform on purpose — matching the
+ * card's outline exactly is what hides the seam.
+ *
+ * Every entry point is a no-op returning a resolved Promise when it has
+ * nothing honest to animate — no source, a source scrolled off screen, an
+ * unmeasurable shell, `prefers-reduced-motion`, or geometry already
+ * congruent within 1px / 1%. THE POSTER IS THE EXCEPTION: it is painted on
+ * every one of those paths, because a black rectangle is a bug at any
+ * motion setting, not a flourish someone opted out of.
+ *
+ * `flipClose` holds its end state (`fill: forwards`) — snapping back to full
+ * size on the last frame would flash the whole player right before the host
+ * hides it. The hold is released by the next `flipOpen` on EVERY path,
+ * including the no-op ones, so a shell reopened under reduced motion can
+ * never sit shrunk at the last card's position.
+ *
+ * The one DOM-touching module in presence/ besides idle.ts; its globals are
+ * injectable (`g`) so node:test drives it with fakes.
+ */
+/** The app's one state-change curve. */
+export const FLIP_EASE = 'cubic-bezier(.25, 1, .5, 1)';
+export const FLIP_OPEN_MS = 260;
+export const FLIP_CLOSE_MS = 200;
+/** Opacity the shell starts at: shallow with a picture on screen, deeper without. */
+export const FLIP_FADE_WITH_POSTER = 0.7;
+export const FLIP_FADE_BARE = 0.25;
+export const FLIP_POSTER_CLASS = 'jatui-flip-poster';
+const G = () => (typeof globalThis === 'undefined' ? {} : globalThis);
+// Keyed on the shell, not a field on an element the host owns.
+const running = new WeakMap();
+function reducedMotion(g) {
+    try {
+        return typeof g.matchMedia === 'function' && g.matchMedia('(prefers-reduced-motion: reduce)').matches;
+    }
+    catch {
+        return false;
+    }
+}
+function animatable(el) {
+    return !!el && typeof el.animate === 'function' && typeof el.getBoundingClientRect === 'function';
+}
+/**
+ * Duck-types an Element or a rect snapshot (a virtualised grid may hand over
+ * a rect it measured before the card went away). Zero-sized or non-finite ⇒
+ * null — never divide a scale factor by nothing.
+ */
+export function rectOf(x) {
+    if (!x || typeof x !== 'object')
+        return null;
+    const src = x;
+    let r;
+    try {
+        r =
+            typeof src.getBoundingClientRect === 'function'
+                ? src.getBoundingClientRect()
+                : src;
+    }
+    catch {
+        return null;
+    }
+    if (!r)
+        return null;
+    const width = Number(r.width);
+    const height = Number(r.height);
+    const left = Number(r.left);
+    const top = Number(r.top);
+    if (!(width > 0) || !(height > 0) || !Number.isFinite(left) || !Number.isFinite(top))
+        return null;
+    return { left, top, width, height };
+}
+/** Any part of the rect inside the viewport. Unknown viewport ⇒ assume visible. */
+export function onScreen(r, vw, vh) {
+    const w = Number(vw);
+    const h = Number(vh);
+    if (!Number.isFinite(w) || !Number.isFinite(h))
+        return true;
+    return r.left < w && r.top < h && r.left + r.width > 0 && r.top + r.height > 0;
+}
+/**
+ * The inversion — "put my corner on the card's corner, shrink to its size".
+ * Null when the boxes already coincide (within 1px / 1%) or can't be scaled.
+ */
+export function flipGeometry(visual, layout) {
+    const sx = visual.width / layout.width;
+    const sy = visual.height / layout.height;
+    const dx = visual.left - layout.left;
+    const dy = visual.top - layout.top;
+    if (![sx, sy, dx, dy].every(Number.isFinite) || !(sx > 0) || !(sy > 0))
+        return null;
+    if (Math.abs(dx) < 1 && Math.abs(dy) < 1 && Math.abs(sx - 1) < 0.01 && Math.abs(sy - 1) < 0.01)
+        return null;
+    return { dx, dy, sx, sy };
+}
+export function awayFrame(g) {
+    return { transformOrigin: '0 0', transform: `translate(${g.dx}px, ${g.dy}px) scale(${g.sx}, ${g.sy})` };
+}
+export function homeFrame() {
+    return { transformOrigin: '0 0', transform: 'none' };
+}
+/**
+ * A poster string → a safe `background-image` value, or "" for none. A bare
+ * URL containing a quote, paren or backslash emits nothing rather than a
+ * broken declaration that would take the whole rule with it.
+ */
+export function posterBackground(poster) {
+    if (typeof poster !== 'string')
+        return '';
+    const v = poster.trim();
+    if (!v)
+        return '';
+    if (/^(url\(|none$|(-webkit-)?(linear|radial|conic)-gradient\(|(-webkit-)?image-set\()/i.test(v)) {
+        return v.toLowerCase() === 'none' ? '' : v;
+    }
+    if (/["'()\\]/.test(v))
+        return '';
+    return `url("${v}")`;
+}
+/** Remove a poster painted by flipOpen (and the position it may have needed). */
+export function clearPoster(shell) {
+    const s = shell;
+    if (!s || typeof s.querySelector !== 'function')
+        return;
+    const el = s.querySelector('.' + FLIP_POSTER_CLASS);
+    if (!el)
+        return;
+    if (el.dataset?.restorePosition === '1')
+        s.style.position = '';
+    el.remove?.();
+}
+function paintPoster(shell, poster, g) {
+    if (!shell || typeof shell.appendChild !== 'function' || !g.document)
+        return false;
+    clearPoster(shell); // a posterless reopen must not keep the last video's picture
+    const image = posterBackground(poster);
+    if (!image)
+        return false;
+    const el = g.document.createElement('div');
+    el.className = FLIP_POSTER_CLASS;
+    el.setAttribute('aria-hidden', 'true');
+    el.style.cssText =
+        'position:absolute;inset:0;z-index:0;pointer-events:none;' +
+            'background-repeat:no-repeat;background-position:center;background-size:contain;';
+    el.style.backgroundImage = image;
+    const cs = g.getComputedStyle;
+    if (typeof cs === 'function' && cs(shell).position === 'static') {
+        shell.style.position = 'relative';
+        el.dataset.restorePosition = '1';
+    }
+    shell.appendChild(el);
+    return true;
+}
+function release(shell) {
+    const prev = running.get(shell);
+    if (!prev)
+        return;
+    running.delete(shell);
+    try {
+        prev.cancel();
+    }
+    catch {
+        /* already gone */
+    }
+    shell.style.willChange = '';
+}
+function play(shell, frames, duration, hold) {
+    const anim = shell.animate(frames, { duration, easing: FLIP_EASE, fill: hold ? 'forwards' : 'none' });
+    running.set(shell, anim);
+    shell.style.willChange = 'transform'; // promoted for the quarter second it earns it, never longer
+    const settle = () => {
+        if (running.get(shell) !== anim)
+            return; // a later open already owns the shell
+        if (!hold)
+            running.delete(shell);
+        shell.style.willChange = '';
+    };
+    return anim.finished.then(settle, settle);
+}
+const durationOf = (v, fallback) => {
+    const n = Number(v);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+};
+/**
+ * Grow `shell` out of `from`'s rectangle. `poster` (a URL or CSS image) is
+ * painted into the shell on EVERY path; a host that paints its own poster
+ * passes `hasPoster: true` instead so the fade depth matches.
+ */
+export function flipOpen(opts = {}) {
+    const g = opts.g ?? G();
+    const shell = opts.shell;
+    const painted = paintPoster(shell, opts.poster, g) || opts.hasPoster === true;
+    if (!animatable(shell))
+        return Promise.resolve();
+    release(shell); // on every path — a held close must never survive a reopen
+    if (reducedMotion(g))
+        return Promise.resolve();
+    const fromRect = rectOf(opts.from);
+    const shellRect = rectOf(shell);
+    if (!fromRect || !shellRect || !onScreen(fromRect, g.innerWidth, g.innerHeight))
+        return Promise.resolve();
+    const geo = flipGeometry(fromRect, shellRect);
+    if (!geo)
+        return Promise.resolve();
+    const fade = painted ? FLIP_FADE_WITH_POSTER : FLIP_FADE_BARE;
+    return play(shell, [{ ...awayFrame(geo), opacity: fade }, { ...homeFrame(), opacity: 1 }], durationOf(opts.duration, FLIP_OPEN_MS), false);
+}
+/**
+ * Shrink `shell` back onto `to` and HOLD there (the host hides it after).
+ * No opacity: the last frame before the host hides the shell IS the card.
+ */
+export function flipClose(opts = {}) {
+    const g = opts.g ?? G();
+    const shell = opts.shell;
+    if (!animatable(shell))
+        return Promise.resolve();
+    release(shell);
+    if (reducedMotion(g))
+        return Promise.resolve();
+    const toRect = rectOf(opts.to);
+    const shellRect = rectOf(shell);
+    if (!toRect || !shellRect || !onScreen(toRect, g.innerWidth, g.innerHeight))
+        return Promise.resolve();
+    const geo = flipGeometry(toRect, shellRect);
+    if (!geo)
+        return Promise.resolve();
+    return play(shell, [homeFrame(), awayFrame(geo)], durationOf(opts.duration, FLIP_CLOSE_MS), true);
+}

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

@@ -0,0 +1,82 @@
+/**
+ * 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.
+ */
+import type { DesktopSignal } from './winddown';
+/** The API's floor: `threshold` below 60s is rejected by the browser. */
+export declare const IDLE_THRESHOLD_MIN_MS = 60000;
+export type IdlePermission = 'granted' | 'denied' | 'prompt' | 'unsupported';
+type Globals = {
+    IdleDetector?: unknown;
+    isSecureContext?: boolean;
+    navigator?: {
+        permissions?: {
+            query?: (d: {
+                name: string;
+            }) => Promise<{
+                state: string;
+            }>;
+        };
+    };
+    AbortController?: typeof AbortController;
+};
+/** Does this browser have the Idle Detection API at all? (Chromium, secure context.) */
+export declare function idleDetectionSupported(g?: Globals | undefined): boolean;
+/**
+ * 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 declare function idleDetectionPermission(g?: Globals | undefined): Promise<IdlePermission>;
+/**
+ * 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 declare function requestIdleDetection(g?: Globals | undefined): Promise<Exclude<IdlePermission, 'prompt'>>;
+export interface DesktopWatch {
+    /** Resolves true once the detector is running; false if it could not start. */
+    ready: Promise<boolean>;
+    /** Latest reading, or null before the first one. */
+    read(): DesktopSignal | null;
+    stop(): void;
+}
+/** Map the API's two strings onto the two facts. Unknown ⇒ null (no reading). */
+export declare function toDesktopSignal(userState: unknown, screenState: unknown): DesktopSignal | null;
+/**
+ * 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 declare function startDesktopWatch(opts: {
+    thresholdMs: number;
+    onChange: (signal: DesktopSignal | null) => void;
+    g?: Globals;
+}): DesktopWatch;
+export {};