@joewinke/jatui 0.14.0 → 0.16.0

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

@@ -5,6 +5,9 @@ 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';
+export type { VideoSettingsStore, SettingValue, SettingSpec } from '../video/settings';
 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';
@@ -12,6 +15,9 @@ 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';
+import { type SettingValue, type VideoSettingsStore } from '../video/settings';
 type $$ComponentProps = {
     src: string;
     poster?: string | null;
@@ -214,6 +220,103 @@ type $$ComponentProps = {
     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;
+    /**
+     * Settings (mos-5lzns.35): where the viewer's standing choices live —
+     * `{ get(id), set(id, value) }`, either may be async, keyed by the ids
+     * in `VIDEO_SETTINGS`. jatui never persists on its own (no
+     * localStorage, no API): a host with per-user state passes its own
+     * adapter. Every stored value is coerced; junk reads as nothing.
+     *
+     * A stored choice overrides the matching prop — the prop is the
+     * host's DEFAULT, the stored value is the viewer's decision. It never
+     * creates a feature the host left out: a stored `audio.level` does
+     * nothing on a player with no `loudness` prop. `night.mode` /
+     * `night.depth` are written into the bindable `night` / `nightDepth`,
+     * and `N` / the moon wheel are saved back through the store.
+     */
+    settingsStore?: VideoSettingsStore;
+    /**
+     * Show the settings panel (default off — inert): a gear in the control
+     * strip and the `,` key open it. The panel is generated from the
+     * registry and shows only rows for features THIS player has (host
+     * opted in and the data exists). Without a `settingsStore`, choices
+     * last while the player is mounted.
+     */
+    settingsPanel?: boolean;
+    /** A host page explaining the settings — linked from the panel's footer. */
+    settingsHelpHref?: string | null;
+    /** The viewer changed a setting (panel, `N`, the moon wheel). Coerced value. */
+    onSettingChange?: (id: string, value: SettingValue) => void;
     class?: string;
 };
 declare const VideoPlayer: import("svelte").Component<$$ComponentProps, {

package/dist/index.d.ts

@@ -12,8 +12,10 @@ 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, VideoAdSpan, RateReport, } 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 { VIDEO_SETTINGS, SETTING_GROUPS, settingSpec, settingValue, coerce as coerceVideoSetting, memorySettingsStore, panelGroups as videoSettingsGroups, formatSettingValue, type VideoSettingsStore, type SettingSpec as VideoSettingSpec, type SettingValue as VideoSettingValue, type SettingOption as VideoSettingOption, type SettingWhen as VideoSettingWhen, type SettingAvailability as VideoSettingAvailability } from './video/settings';
 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

@@ -17,6 +17,16 @@ export { default as VideoPlayer } from './components/VideoPlayer.svelte';
 // 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';
+// Settings (mos-5lzns.35): the registry is the single source for the
+// player's panel AND a host's help page (labels + hints), the store adapter
+// type a host implements for per-user persistence, and `coerce` for a host
+// that reads the same values elsewhere. jatui never persists settings itself.
+export { VIDEO_SETTINGS, SETTING_GROUPS, settingSpec, settingValue, coerce as coerceVideoSetting, memorySettingsStore, panelGroups as videoSettingsGroups, formatSettingValue } from './video/settings';
 // 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

@@ -19,10 +19,10 @@ props + callback surfaces.
 | `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` + `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. |
+| `settings.ts` + `settings/` | **.35** (done) — knobs added by .30–.34 | `settings.ts` is the barrel. `registry.ts` — `VIDEO_SETTINGS`: id, group, label, **mandatory hint**, the prop it drives, the availability gate (`when`); `coerce` never throws (hostile values, throwing `valueOf`, Symbols → undefined). Labels/hints are the single source for the panel AND a host help page. `store.ts` — the host-supplied `VideoSettingsStore` (`get`/`set`, either async; jatui never persists on its own) and `createSettingsSession`: coerced reads, a choice made on screen beats a late read, per-id debounced writes flushed on close. `panel.ts` — `panelGroups` (rows only for features this player has — omitted, never disabled), value formatting, radio stepping. `SettingsPanel.svelte` — the generated dialog (switch / radio group / range, focus trap, Esc/`,` close, focus handed back). In the component a stored choice overlays its prop but never creates a presence-gated feature; `night`/`nightDepth` are written through their bindings and `N`/the moon wheel are saved back. The one permission ask is `sleep.desktopIdle` turned on, from that click. 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

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), `,` (settings —
- * jatui is prop-driven; a settings module arrives with the features that need
- * 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.
+ * library-app verbs, not player verbs), `/` (transcript search — the pane
+ * has none yet). N (night cycle) landed with the night module (mos-5lzns.33)
+ * and `,` (settings) with the settings panel (mos-5lzns.35), each 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' | 'night';
+    when?: 'chapters' | 'bookmarks' | 'transcript' | 'comments' | 'night' | 'settings';
 }
 /** 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), `,` (settings —
- * jatui is prop-driven; a settings module arrives with the features that need
- * 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.
+ * library-app verbs, not player verbs), `/` (transcript search — the pane
+ * has none yet). N (night cycle) landed with the night module (mos-5lzns.33)
+ * and `,` (settings) with the settings panel (mos-5lzns.35), each gated on
+ * the host opting in.
  */
 /** Order follows the help overlay: transport, seek, volume, speed, structure. */
 export const PLAYER_KEYS = [
@@ -30,6 +30,7 @@ export const PLAYER_KEYS = [
     { 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: 'Settings', when: 'settings' },
     { keys: '?', description: 'Toggle this help' }
 ];
 /** Band-local keys (band focused): advertised by the band's aria, not the overlay. */

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