@joewinke/jatui 0.34.1 → 0.35.0

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

@@ -0,0 +1,87 @@
+export type { ListenSegment, ListenChapter, ListenVoice, ListenSegmentPage, ListenSegmentSource, ListenStatus, ListenApi } from '../listen/types';
+/**
+     * ListenControl — "listen to this page" as one compact control.
+     *
+     * A small pill that expands into a playback bar: play/pause, −15s/+15s and
+     * previous/next sentence, speed (0.75–2×), a voice picker, a document-wide
+     * progress bar with chapter/section ticks, time, close. Built for hosts
+     * that synthesize audio per sentence (TTS): the host supplies an async
+     * SEGMENT SOURCE — sentences/paragraphs with ids → audio URLs — and the
+     * player starts on the first chunk while the rest synthesizes, hatching
+     * the not-yet-real tail of the progress bar. Every segment boundary fires
+     * `onSegmentChange(id)` so the host can highlight + scroll-follow.
+     *
+     * ── One timeline across per-sentence files ──────────────────────────────
+     * A "listen" player is a playlist, not one media element. Each segment has
+     * its own URL, so the engine walks segments sequentially through ONE
+     * hidden `<audio>` element and reports ONE document-wide time: the
+     * elapsed clock, the progress fill, the ticks, a ±15s skip that crosses a
+     * boundary and a seek from the slider all map through `buildTimeline`'s
+     * offsets (listen/segments.ts) — the same one-axis discipline as the
+     * VideoPlayer band. Durations the host knows (`durationSec`, TTS usually
+     * reports them) lay the timeline out immediately; unknown ones are
+     * measured on load and ESTIMATED until then, self-correcting as they land.
+     *
+     * The transport row borrows VideoPlayer's `kind="audio"` / `transport=
+     * "band"` shape (round primary play, ghost transport buttons, tabular
+     * clock) and reuses its pure time formatting (`video/time.ts`); the
+     * per-segment playlist engine is what doesn't fit inside VideoPlayer and
+     * lives here instead.
+     *
+     * ── Media Session ───────────────────────────────────────────────────────
+     * Lock-screen/headset/OS controls are wired while open: metadata (the
+     * `title` prop + current voice), play/pause, previous/next track (the
+     * sentence skip), seekbackward/seekforward/seekto, and ONE document-wide
+     * position state. Feature-detected end to end — nothing runs where the
+     * API is missing (listen/mediaSession.ts).
+     *
+     * ── Scope honesty ───────────────────────────────────────────────────────
+     * The keyboard map (Space/K, ←/→ sentences, Shift+←/→ ±15s, [ / ] speed,
+     * Escape) fires only while focus is inside the player — a library
+     * component must not hijack the host page's keys. Hosts wanting global
+     * keys bind `api` and wire their own handler with the same actions.
+     *
+     * Theming is token-only (DaisyUI semantic vars); motion is reduced-motion
+     * aware; everything is labelled; on narrow screens the expanded bar
+     * becomes a fixed sticky mini-bar at the bottom.
+     */
+import { type Snippet } from 'svelte';
+import type { ListenApi, ListenChapter, ListenSegment, ListenSegmentSource, ListenVoice } from '../listen/types';
+interface Props {
+    /**
+     * Host-supplied async segment source (sentences/paragraphs with ids →
+     * audio). Called per voice; pages arrive as chunks synthesize and are
+     * merged by id, so a later page can fill a segment's `url` in late.
+     * Pass a STABLE reference — a fresh inline arrow re-runs the source.
+     */
+    source: ListenSegmentSource;
+    /** The voices the host offers. Empty ⇒ no picker (one implicit voice, ''). */
+    voices?: ListenVoice[];
+    /** The picked voice (bindable). Default: the first voice, persisted to storage. */
+    voiceId?: string;
+    /** Sections for the progress ticks + the caption's chapter label. */
+    chapters?: ListenChapter[];
+    /** Document title — lock-screen metadata + the bar's aria-label. */
+    title?: string;
+    /** The pill's label. Default `Listen`. */
+    triggerLabel?: string;
+    /** Expanded state (bindable). */
+    open?: boolean;
+    /** Load the source on mount instead of waiting for the first open (TTS cost is the host's call). */
+    preload?: boolean;
+    /** Estimate for a segment whose duration isn't known yet. Default 3s. */
+    estimateSec?: number;
+    /** localStorage key prefix for speed/voice. Default `jatui.listen` (→ `jatui.listen:prefs`). */
+    storageKey?: string;
+    /** Segment-boundary hook — host-side highlight + scroll-follow. */
+    onSegmentChange?: (id: string | null, segment: ListenSegment | null) => void;
+    onOpenChange?: (open: boolean) => void;
+    /** Instance API for hosts wiring their own global keys / external controls. */
+    api?: ListenApi;
+    class?: string;
+    /** Custom trigger content (replaces the headphones+label default). */
+    children?: Snippet;
+}
+declare const ListenControl: import("svelte").Component<Props, {}, "open" | "voiceId" | "api">;
+type ListenControl = ReturnType<typeof ListenControl>;
+export default ListenControl;

package/dist/components/review/MediaZoomLightbox.svelte

@@ -613,7 +613,14 @@
 			>
 		</div>
 		{#if showHint}
-			<p class="w-full text-2xs text-base-content/60" data-media-zoom-hint>{hint}</p>
+			<!-- Keys are useless on a touch screen: hidden on coarse pointers
+		     (the checklist block's footer hint hides the same way,
+		     mos-lsmve.16 F7 — the 4-line wrap pushed the note below the
+		     fold). -->
+			<p
+				class="w-full text-2xs text-base-content/60 [@media(pointer:coarse)]:hidden"
+				data-media-zoom-hint>{hint}</p
+			>
 		{/if}
 	</div>
 

package/dist/components/review/ReviewNote.svelte

@@ -6,7 +6,9 @@
     marked `opensNote` (Reject / Needs work / Fail…). It does NOT open on
     mount, on a repeat of the same verdict, or when the round changes.
   - The note is optional: under an EMPTY note on a note-worthy verdict sits
-    the soft NOTE_HINT — never a validation block.
+    the soft NOTE_HINT — never a validation block. The hint never claims the
+    verdict was saved when it was not: a `saveFailed` host (its own save
+    state) or this note's own failed save silences it (mos-lsmve.16 F6).
   - Auto-grows with its content.
   - Per-note save state from `onSave`: "Saving…" → "Saved ✓", or
     "Not saved" + Retry when it throws/rejects. Saves are debounced while
@@ -16,7 +18,12 @@
     discard.
   - `round` keys the note to the current round: a new round resets the save
     state, drops any pending save for the old round, and collapses the note
-    if the host gives it an empty value.
+    if the host gives it an empty value. The round effect is DECLARED BEFORE
+    the verdict effect on purpose (mos-lsmve.16 F9): when a round change and
+    a note-worthy verdict change land in the same flush, Svelte runs
+    instance effects in declaration order, so the verdict's open runs LAST
+    and survives the round's collapse — the reviewer is looking at a note
+    for the verdict they just cast, and it must not blink away.
 -->
 <script module lang="ts">
 	/** The soft inline hint under an EMPTY note field on a note-worthy verdict. */
@@ -42,6 +49,10 @@
 		options?: readonly VerdictOption[];
 		/** Current round key (version, retestSince…). */
 		round?: string | number | null;
+		/** The host's own save failed (e.g. the verdict's save): the hint must
+		 * not claim the verdict is saved while the block shows "Not saved"
+		 * (mos-lsmve.16 F6). */
+		saveFailed?: boolean;
 		/** Persist the note. Throw / reject to show "Not saved". */
 		onSave?: (text: string, ctx: { round: string | number | null }) => void | Promise<void>;
 		/** Every keystroke, before the debounce. */
@@ -66,6 +77,7 @@
 		verdict = null,
 		options = [],
 		round = null,
+		saveFailed = false,
 		onSave,
 		onInput,
 		debounceMs = 600,
@@ -88,20 +100,12 @@
 
 	const noteWorthy = $derived(!!verdict && options.some((o) => o.id === verdict && o.opensNote));
 
-	// Open + focus when the verdict CHANGES to a note-worthy one. The first run
-	// only records the starting verdict, so a saved state never pops open.
-	let lastVerdict: string | null | undefined = undefined;
-	$effect(() => {
-		const v = verdict;
-		const prev = lastVerdict;
-		lastVerdict = v;
-		if (prev === undefined || v === prev || !v) return;
-		if (!untrack(() => options.some((o) => o.id === v && o.opensNote))) return;
-		open = true;
-		tick().then(() => textarea?.focus());
-	});
-
 	// A new round: forget the old round's save state and pending save.
+	// DECLARED BEFORE the verdict effect below (mos-lsmve.16 F9): instance
+	// effects run in declaration order, so when a round change and a
+	// note-worthy verdict change land in the same flush, the round's
+	// collapse happens FIRST and the verdict's open survives — the note
+	// never blinks away under the verdict the reviewer just cast.
 	let lastRound: string | number | null | undefined = undefined;
 	$effect(() => {
 		const r = round;
@@ -115,6 +119,19 @@
 		if (!untrack(() => value)) open = false;
 	});
 
+	// Open + focus when the verdict CHANGES to a note-worthy one. The first run
+	// only records the starting verdict, so a saved state never pops open.
+	let lastVerdict: string | null | undefined = undefined;
+	$effect(() => {
+		const v = verdict;
+		const prev = lastVerdict;
+		lastVerdict = v;
+		if (prev === undefined || v === prev || !v) return;
+		if (!untrack(() => options.some((o) => o.id === v && o.opensNote))) return;
+		open = true;
+		tick().then(() => textarea?.focus());
+	});
+
 	// Auto-grow: reset, then fit the content.
 	$effect(() => {
 		void value;
@@ -206,7 +223,11 @@
 			onblur={flush}
 			onkeydown={onKeydown}
 		></textarea>
-		{#if noteWorthy && !value.trim()}
+		<!-- The hint asserts the verdict was saved — it must not say that
+		     while a save has failed (the host's own, or this note's own
+		     retryable one): the alert above is saying the opposite
+		     (mos-lsmve.16 F6). -->
+		{#if noteWorthy && !value.trim() && saveState !== 'error' && !saveFailed}
 			<p class="text-xs text-base-content/60">{NOTE_HINT}</p>
 		{/if}
 	</div>

package/dist/components/review/ReviewNote.svelte.d.ts

@@ -13,6 +13,10 @@ interface Props {
     options?: readonly VerdictOption[];
     /** Current round key (version, retestSince…). */
     round?: string | number | null;
+    /** The host's own save failed (e.g. the verdict's save): the hint must
+     * not claim the verdict is saved while the block shows "Not saved"
+     * (mos-lsmve.16 F6). */
+    saveFailed?: boolean;
     /** Persist the note. Throw / reject to show "Not saved". */
     onSave?: (text: string, ctx: {
         round: string | number | null;

package/dist/components/review/VerdictControl.svelte

@@ -13,12 +13,17 @@
   - One-key hotkeys from `options[].key` (and `u` = Undo) while focus is in
     the control. Handled keys are preventDefault-ed so a page-level
     reviewKeys() handler skips them.
+  - `trailing` renders the row's trailing actions (a Note toggle…) in ONE
+    non-breaking group with Undo, so a narrow card wraps the whole group —
+    the note button never strands alone on its own row (mos-lsmve.16 F7:
+    it used to wrap alone, below Undo).
   - Sizes: `sm` (cards, default) and `xs` (inline strips).
 
   The `options` array is the same one ReviewNote (`opensNote`) and
   reviewKeys (`key`) take.
 -->
 <script lang="ts">
+	import type { Snippet } from 'svelte';
 	import type { VerdictOption, VerdictTone } from '../../actions/reviewKeys';
 
 	interface Props {
@@ -35,6 +40,9 @@
 		undoLabel?: string;
 		/** Show each option's hotkey as a keycap inside its button. */
 		showKeys?: boolean;
+		/** Trailing actions (Note toggle…), kept in one non-breaking group
+		 * with Undo so the wrap boundary falls before the pair. */
+		trailing?: Snippet;
 		/** Local hotkeys while focus is inside the control. Default true. */
 		hotkeys?: boolean;
 		disabled?: boolean;
@@ -50,6 +58,7 @@
 		label = 'Verdict',
 		undoLabel = 'Undo',
 		showKeys = false,
+		trailing = undefined,
 		hotkeys = true,
 		disabled = false,
 		class: className = ''
@@ -145,19 +154,27 @@
 			</button>
 		{/each}
 	</div>
-	{#if value && onUndo}
-		<button
-			type="button"
-			class="btn btn-ghost {sizeClass} gap-1 px-2 text-base-content/75 hover:text-base-content"
-			aria-label="{undoLabel} — {label}"
-			aria-keyshortcuts="u"
-			{disabled}
-			onclick={() => onUndo?.()}
-		>
-			<svg viewBox="0 0 24 24" class="size-3.5" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
-				<path d="M9 14 4 9l5-5" /><path d="M4 9h10.5a5.5 5.5 0 0 1 0 11H11" />
-			</svg>
-			{undoLabel}
-		</button>
+	<!-- Undo + trailing actions in one ATOMIC span: the row's wrap boundary
+	     falls before the pair, so Undo and whatever trails it (the Note
+	     toggle) always sit on the same line (mos-lsmve.16 F7). -->
+	{#if value && onUndo || trailing}
+		<span class="flex items-center gap-2">
+			{#if value && onUndo}
+				<button
+					type="button"
+					class="btn btn-ghost {sizeClass} gap-1 px-2 text-base-content/75 hover:text-base-content"
+					aria-label="{undoLabel} — {label}"
+					aria-keyshortcuts="u"
+					{disabled}
+					onclick={() => onUndo?.()}
+				>
+					<svg viewBox="0 0 24 24" class="size-3.5" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+						<path d="M9 14 4 9l5-5" /><path d="M4 9h10.5a5.5 5.5 0 0 1 0 11H11" />
+					</svg>
+					{undoLabel}
+				</button>
+			{/if}
+			{#if trailing}{@render trailing()}{/if}
+		</span>
 	{/if}
 </div>

package/dist/components/review/VerdictControl.svelte.d.ts

@@ -1,3 +1,4 @@
+import type { Snippet } from 'svelte';
 import type { VerdictOption } from '../../actions/reviewKeys';
 interface Props {
     options: readonly VerdictOption[];
@@ -13,6 +14,9 @@ interface Props {
     undoLabel?: string;
     /** Show each option's hotkey as a keycap inside its button. */
     showKeys?: boolean;
+    /** Trailing actions (Note toggle…), kept in one non-breaking group
+     * with Undo so the wrap boundary falls before the pair. */
+    trailing?: Snippet;
     /** Local hotkeys while focus is inside the control. Default true. */
     hotkeys?: boolean;
     disabled?: boolean;

package/dist/components/table/DataTable.svelte.d.ts

@@ -2,7 +2,7 @@ import type { DataTableProps } from './types.js';
 declare function $$render<TData>(): {
     props: DataTableProps<TData>;
     exports: {};
-    bindings: "collapsed" | "sorting" | "api";
+    bindings: "api" | "collapsed" | "sorting";
     slots: {};
     events: {};
 };
@@ -10,7 +10,7 @@ declare class __sveltets_Render<TData> {
     props(): ReturnType<typeof $$render<TData>>['props'];
     events(): ReturnType<typeof $$render<TData>>['events'];
     slots(): ReturnType<typeof $$render<TData>>['slots'];
-    bindings(): "collapsed" | "sorting" | "api";
+    bindings(): "api" | "collapsed" | "sorting";
     exports(): {};
 }
 interface $$IsomorphicComponent {

package/dist/index.d.ts

@@ -18,6 +18,10 @@ export type { ChapterBlock, ChapterStateVisual } from './components/replay/Chapt
 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 { default as ListenControl } from './components/ListenControl.svelte';
+export type { ListenSegment, ListenChapter, ListenVoice, ListenSegmentPage, ListenSegmentSource, ListenStatus, ListenApi } from './listen/types';
+export { LISTEN_KEYS } from './listen/keys';
+export { LISTEN_SPEEDS, SPEED_FLOOR, SPEED_CEIL, clampSpeed, stepSpeed, formatListenSpeed } from './listen/prefs';
 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';

package/dist/index.js

@@ -33,6 +33,12 @@ 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';
+// ListenControl (jatui-eev2n) — "listen to this page" playback over the host's
+// per-sentence audio source. The component re-exports its types too; these
+// are the same names, so either import site works.
+export { default as ListenControl } from './components/ListenControl.svelte';
+export { LISTEN_KEYS } from './listen/keys';
+export { LISTEN_SPEEDS, SPEED_FLOOR, SPEED_CEIL, clampSpeed, stepSpeed, formatListenSpeed } from './listen/prefs';
 // 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.

package/dist/listen/keys.d.ts

@@ -0,0 +1,36 @@
+/**
+ * ListenControl keyboard map (jatui-eev2n) — the same single-source discipline
+ * as `video/keys.ts`: a key that exists is in the map, a key in the map
+ * exists. The component's keydown handler and any host help surface both read
+ * LISTEN_KEYS.
+ *
+ * Map parity: Space/K play-pause, ←/→ prev/next SENTENCE (a reading player's
+ * primary navigation — the segments ARE the sentences), Shift+←/→ the ±15s
+ * skip, [ / ] speed down/up, Escape close. Deliberately NOT bound globally:
+ * the map fires only while focus is inside the player (a library component
+ * must not hijack the host page's keys — hosts wanting global keys wire the
+ * exported `ListenApi` themselves).
+ */
+export interface ListenKeyRow {
+    /** Keycap label — `/`-separated alternates, as shown in a help table. */
+    keys: string;
+    description: string;
+}
+export declare const LISTEN_KEYS: ListenKeyRow[];
+export type ListenKeyAction = 'toggle' | 'prev' | 'next' | 'back' | 'forward' | 'slower' | 'faster' | 'close';
+/**
+ * One keydown → one action (or null). Pure: takes the two KeyboardEvent
+ * fields the map needs, so a synthetic event in node tests resolves the same
+ * way a real one does.
+ */
+export declare function resolveListenKey(event: {
+    key: string;
+    shiftKey?: boolean;
+}): ListenKeyAction | null;
+/**
+ * Targets whose keys already mean something native — a focused button gets
+ * Space as its activation key, the progress `<input type=range>` owns the
+ * arrows, a `<select>` owns typeahead. The component skips the map for these
+ * (Escape excepted — closing the player outranks every widget).
+ */
+export declare function isNativeControlTarget(target: EventTarget | null): boolean;

package/dist/listen/keys.js

@@ -0,0 +1,68 @@
+/**
+ * ListenControl keyboard map (jatui-eev2n) — the same single-source discipline
+ * as `video/keys.ts`: a key that exists is in the map, a key in the map
+ * exists. The component's keydown handler and any host help surface both read
+ * LISTEN_KEYS.
+ *
+ * Map parity: Space/K play-pause, ←/→ prev/next SENTENCE (a reading player's
+ * primary navigation — the segments ARE the sentences), Shift+←/→ the ±15s
+ * skip, [ / ] speed down/up, Escape close. Deliberately NOT bound globally:
+ * the map fires only while focus is inside the player (a library component
+ * must not hijack the host page's keys — hosts wanting global keys wire the
+ * exported `ListenApi` themselves).
+ */
+import { isTypingTarget } from '../utils/keyboardShortcutRegistry';
+export const LISTEN_KEYS = [
+    { keys: 'Space / K', description: 'Play / pause' },
+    { keys: '← / →', description: 'Previous / next sentence' },
+    { keys: 'Shift + ← / →', description: 'Skip ∓15s' },
+    { keys: '[ / ]', description: 'Speed down / up (0.75–2×)' },
+    { keys: 'Escape', description: 'Close the player' }
+];
+/**
+ * One keydown → one action (or null). Pure: takes the two KeyboardEvent
+ * fields the map needs, so a synthetic event in node tests resolves the same
+ * way a real one does.
+ */
+export function resolveListenKey(event) {
+    const key = typeof event?.key === 'string' ? event.key : '';
+    const shift = event?.shiftKey === true;
+    switch (key) {
+        case ' ':
+        case 'Spacebar': // legacy IE/Edge spelling
+            return shift ? null : 'toggle';
+        case 'k':
+        case 'K':
+            return 'toggle';
+        case 'ArrowLeft':
+            return shift ? 'back' : 'prev';
+        case 'ArrowRight':
+            return shift ? 'forward' : 'next';
+        case '[':
+            return 'slower';
+        case ']':
+            return 'faster';
+        case 'Escape':
+            return 'close';
+        default:
+            return null;
+    }
+}
+/**
+ * Targets whose keys already mean something native — a focused button gets
+ * Space as its activation key, the progress `<input type=range>` owns the
+ * arrows, a `<select>` owns typeahead. The component skips the map for these
+ * (Escape excepted — closing the player outranks every widget).
+ */
+export function isNativeControlTarget(target) {
+    if (isTypingTarget(target))
+        return true;
+    // Duck-typed (not `instanceof`) so node tests without DOM globals work.
+    // `<input type=range>` (the progress bar) is not a typing target but still
+    // owns its own arrow keys natively — as does any other input.
+    const el = target;
+    if (typeof el?.tagName !== 'string')
+        return false;
+    const tag = el.tagName.toUpperCase();
+    return tag === 'BUTTON' || tag === 'INPUT';
+}

package/dist/listen/mediaSession.d.ts

@@ -0,0 +1,90 @@
+/**
+ * ListenControl Media Session glue (jatui-eev2n) — lock-screen / headset /
+ * OS-media controls for a page whose audio is a SEQUENCE of per-sentence
+ * files. The browser only ever sees one session; this module keeps it fed:
+ *
+ * · metadata — the document title + the current voice (artist);
+ * · action handlers — play/pause, previous/next track (sentence),
+ *   seekbackward/seekforward (the ±15s skip), seekto;
+ * · position state — ONE document-wide position, throttled by the component
+ *   (`navigator.mediaSession.setPositionState` throws on an invalid
+ *   duration/rate combination, so every write is guarded).
+ *
+ * Feature-detected end to end: everywhere the API is missing (every non-secure
+ * context, older Safari, jsdom, node) these are silent no-ops. Pure enough to
+ * drive from a fake session in node tests — the DOM `MediaSession` type is
+ * deliberately mirrored structurally, not imported.
+ */
+/** The slice of `navigator.mediaSession` ListenControl uses. */
+export interface MediaSessionLike {
+    metadata: {
+        title?: string;
+        artist?: string;
+        album?: string;
+        artwork?: {
+            src: string;
+            sizes?: string;
+            type?: string;
+        }[];
+    } | null;
+    setActionHandler(action: string, handler: ((details: {
+        seekOffset?: number;
+        seekTime?: number;
+        fastSeek?: boolean;
+    }) => void) | null): void;
+    setPositionState(state: {
+        duration: number;
+        playbackRate?: number;
+        position?: number;
+    }): void;
+}
+/** Navigator-like lookup — injectable so node tests can pass a fake. */
+export type NavigatorLike = {
+    mediaSession?: MediaSessionLike;
+} | null | undefined;
+/** The session, or null where the Media Session API doesn't exist. */
+export declare function getMediaSession(nav?: NavigatorLike): MediaSessionLike | null;
+export interface ListenMediaMeta {
+    title: string;
+    artist?: string;
+    album?: string;
+    /** Optional cover art URL(s) — host-supplied. */
+    artwork?: string[];
+}
+/** Best-effort metadata write. No-op without a session; never throws. */
+export declare function setListenMetadata(session: MediaSessionLike | null, meta: ListenMediaMeta): void;
+/**
+ * Wire the transport actions. Each handler is registered on its own try/catch:
+ * browsers reject actions they don't implement individually, and one refusal
+ * must not cost the rest. A null handler value clears that action.
+ */
+export declare function setListenActions(session: MediaSessionLike | null, handlers: {
+    play?: (() => void) | null;
+    pause?: (() => void) | null;
+    previoustrack?: (() => void) | null;
+    nexttrack?: (() => void) | null;
+    seekbackward?: ((details: {
+        seekOffset?: number;
+    }) => void) | null;
+    seekforward?: ((details: {
+        seekOffset?: number;
+    }) => void) | null;
+    seekto?: ((details: {
+        seekTime?: number;
+        fastSeek?: boolean;
+    }) => void) | null;
+    stop?: (() => void) | null;
+}): void;
+/** Hand the lock-screen back: null metadata, null handlers. */
+export declare function clearListenSession(session: MediaSessionLike | null): void;
+/**
+ * One document-wide position write. Guards the two ways this throws: no
+ * session, and an invalid state (negative/NaN duration, position outside it,
+ * a non-positive rate) — `setPositionState` rejects those with an exception,
+ * which must never surface from a timeupdate.
+ */
+export declare function updateListenPosition(session: MediaSessionLike | null, state: {
+    duration: number;
+    position: number;
+    playbackRate: number;
+}): void;

package/dist/listen/mediaSession.js

@@ -0,0 +1,108 @@
+/**
+ * ListenControl Media Session glue (jatui-eev2n) — lock-screen / headset /
+ * OS-media controls for a page whose audio is a SEQUENCE of per-sentence
+ * files. The browser only ever sees one session; this module keeps it fed:
+ *
+ * · metadata — the document title + the current voice (artist);
+ * · action handlers — play/pause, previous/next track (sentence),
+ *   seekbackward/seekforward (the ±15s skip), seekto;
+ * · position state — ONE document-wide position, throttled by the component
+ *   (`navigator.mediaSession.setPositionState` throws on an invalid
+ *   duration/rate combination, so every write is guarded).
+ *
+ * Feature-detected end to end: everywhere the API is missing (every non-secure
+ * context, older Safari, jsdom, node) these are silent no-ops. Pure enough to
+ * drive from a fake session in node tests — the DOM `MediaSession` type is
+ * deliberately mirrored structurally, not imported.
+ */
+/** The session, or null where the Media Session API doesn't exist. */
+export function getMediaSession(nav = typeof navigator === 'undefined' ? null : navigator) {
+    const session = nav?.mediaSession;
+    if (!session || typeof session.setActionHandler !== 'function')
+        return null;
+    return session;
+}
+/** Best-effort metadata write. No-op without a session; never throws. */
+export function setListenMetadata(session, meta) {
+    if (!session)
+        return;
+    try {
+        const plain = {
+            title: meta.title,
+            artist: meta.artist ?? '',
+            album: meta.album ?? '',
+            ...(meta.artwork && meta.artwork.length
+                ? { artwork: meta.artwork.map((src) => ({ src, sizes: '512x512' })) }
+                : {})
+        };
+        // `MediaMetadata` is browser-global; node/fake sessions get the plain shape.
+        const Ctor = typeof MediaMetadata === 'undefined' ? null : MediaMetadata;
+        session.metadata = Ctor ? new Ctor(plain) : plain;
+    }
+    catch {
+        /* hostile metadata — keep playing without lock-screen info */
+    }
+}
+/**
+ * Wire the transport actions. Each handler is registered on its own try/catch:
+ * browsers reject actions they don't implement individually, and one refusal
+ * must not cost the rest. A null handler value clears that action.
+ */
+export function setListenActions(session, handlers) {
+    if (!session)
+        return;
+    for (const [action, handler] of Object.entries(handlers)) {
+        if (handler === undefined)
+            continue;
+        try {
+            session.setActionHandler(action, handler);
+        }
+        catch {
+            /* this browser doesn't implement that action */
+        }
+    }
+}
+/** Hand the lock-screen back: null metadata, null handlers. */
+export function clearListenSession(session) {
+    if (!session)
+        return;
+    try {
+        session.metadata = null;
+    }
+    catch {
+        /* ignore */
+    }
+    setListenActions(session, {
+        play: null,
+        pause: null,
+        previoustrack: null,
+        nexttrack: null,
+        seekbackward: null,
+        seekforward: null,
+        seekto: null,
+        stop: null
+    });
+}
+/**
+ * One document-wide position write. Guards the two ways this throws: no
+ * session, and an invalid state (negative/NaN duration, position outside it,
+ * a non-positive rate) — `setPositionState` rejects those with an exception,
+ * which must never surface from a timeupdate.
+ */
+export function updateListenPosition(session, state) {
+    if (!session)
+        return;
+    const { duration, position, playbackRate } = state;
+    if (!Number.isFinite(duration) || duration <= 0)
+        return;
+    if (!Number.isFinite(position) || position < 0 || position > duration)
+        return;
+    if (!Number.isFinite(playbackRate) || playbackRate <= 0)
+        return;
+    try {
+        session.setPositionState({ duration, position, playbackRate });
+    }
+    catch {
+        /* raced with a source change — the next timeupdate rewrites it */
+    }
+}