@joewinke/jatui 0.34.2 → 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/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 */
+    }
+}

package/dist/listen/prefs.d.ts

@@ -0,0 +1,49 @@
+/**
+ * ListenControl preferences — speed and voice persistence (jatui-eev2n).
+ *
+ * The same contract as `video/settings/store.ts` and `columnStorage`: jatui
+ * persists to THIS browser's localStorage by default, a host keeping per-user
+ * state passes its own store. Every access is guarded — private mode, a full
+ * quota, or SSR degrade to "nothing stored", never to a thrown error.
+ */
+/** The listening speeds people actually pick — click cycles, [ / ] step. */
+export declare const LISTEN_SPEEDS: number[];
+/** The task's range: 0.75–2×. */
+export declare const SPEED_FLOOR = 0.75;
+export declare const SPEED_CEIL = 2;
+/**
+ * Clamp to the 0.75–2× range. Garbage (NaN, Infinity, hostile types) degrades
+ * to 1× — never a thrown error.
+ */
+export declare function clampSpeed(rate: unknown): number;
+/**
+ * One step along the speed staircase in `direction`. A rate OFF the staircase
+ * (1.1 from a host's own menu, say) steps to its nearest staircase neighbour
+ * in the pressed direction — never snapping back to 1×. Past either end the
+ * rate holds.
+ */
+/**
+ * Plain multiplier label for listening speeds — `0.75×`, `1×`, `1.25×`,
+ * `1.5×`, `1.75×`, `2×`. (VideoPlayer's `formatSpeedLabel` writes sub-1×
+ * speeds as a delta — mpv style — which reads wrong on a reading player.)
+ */
+export declare function formatListenSpeed(rate: number): string;
+export declare function stepSpeed(current: number, direction: 1 | -1): number;
+export interface ListenPrefs {
+    speed: number;
+    voiceId: string | null;
+}
+/** What persistence needs. Null/undefined ⇒ no storage (SSR, private mode). */
+export type ListenPrefStore = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'> | null | undefined;
+/**
+ * Read prefs. Missing/corrupt storage or hostile JSON → null (use the
+ * defaults); a hostile `speed` degrades to 1× rather than poisoning the
+ * player, and `voiceId` must be a non-empty string to survive.
+ */
+export declare function loadListenPrefs(store: ListenPrefStore, key: string): ListenPrefs | null;
+/** Write prefs. Best-effort: a throwing/full store is swallowed. */
+export declare function saveListenPrefs(store: ListenPrefStore, key: string, prefs: ListenPrefs): void;
+/** The default store: this browser's localStorage, or null on SSR/private mode. */
+export declare function localListenStore(): ListenPrefStore;
+/** Default key prefix — hosts pass `storageKey` to namespace per-page/feature. */
+export declare const LISTEN_PREFS_KEY = "jatui.listen:prefs";

package/dist/listen/prefs.js

@@ -0,0 +1,97 @@
+/**
+ * ListenControl preferences — speed and voice persistence (jatui-eev2n).
+ *
+ * The same contract as `video/settings/store.ts` and `columnStorage`: jatui
+ * persists to THIS browser's localStorage by default, a host keeping per-user
+ * state passes its own store. Every access is guarded — private mode, a full
+ * quota, or SSR degrade to "nothing stored", never to a thrown error.
+ */
+/** The listening speeds people actually pick — click cycles, [ / ] step. */
+export const LISTEN_SPEEDS = [0.75, 1, 1.25, 1.5, 1.75, 2];
+/** The task's range: 0.75–2×. */
+export const SPEED_FLOOR = 0.75;
+export const SPEED_CEIL = 2;
+/**
+ * Clamp to the 0.75–2× range. Garbage (NaN, Infinity, hostile types) degrades
+ * to 1× — never a thrown error.
+ */
+export function clampSpeed(rate) {
+    const n = typeof rate === 'number' ? rate : Number(rate);
+    if (!Number.isFinite(n) || n <= 0)
+        return 1;
+    return Math.min(SPEED_CEIL, Math.max(SPEED_FLOOR, n));
+}
+/**
+ * One step along the speed staircase in `direction`. A rate OFF the staircase
+ * (1.1 from a host's own menu, say) steps to its nearest staircase neighbour
+ * in the pressed direction — never snapping back to 1×. Past either end the
+ * rate holds.
+ */
+/**
+ * Plain multiplier label for listening speeds — `0.75×`, `1×`, `1.25×`,
+ * `1.5×`, `1.75×`, `2×`. (VideoPlayer's `formatSpeedLabel` writes sub-1×
+ * speeds as a delta — mpv style — which reads wrong on a reading player.)
+ */
+export function formatListenSpeed(rate) {
+    return `${clampSpeed(rate)}×`;
+}
+export function stepSpeed(current, direction) {
+    const cur = clampSpeed(current);
+    const i = LISTEN_SPEEDS.indexOf(cur);
+    if (i !== -1)
+        return LISTEN_SPEEDS[Math.min(LISTEN_SPEEDS.length - 1, Math.max(0, i + direction))];
+    if (direction > 0)
+        return LISTEN_SPEEDS.find((s) => s > cur) ?? cur;
+    for (let j = LISTEN_SPEEDS.length - 1; j >= 0; j--)
+        if (LISTEN_SPEEDS[j] < cur)
+            return LISTEN_SPEEDS[j];
+    return cur;
+}
+/**
+ * Read prefs. Missing/corrupt storage or hostile JSON → null (use the
+ * defaults); a hostile `speed` degrades to 1× rather than poisoning the
+ * player, and `voiceId` must be a non-empty string to survive.
+ */
+export function loadListenPrefs(store, key) {
+    if (!store || typeof key !== 'string' || key === '')
+        return null;
+    try {
+        const raw = store.getItem(key);
+        if (raw == null || raw === '')
+            return null;
+        const parsed = JSON.parse(raw);
+        if (parsed == null || typeof parsed !== 'object')
+            return null;
+        const obj = parsed;
+        const speed = typeof obj.speed === 'number' && Number.isFinite(obj.speed) ? clampSpeed(obj.speed) : NaN;
+        const voiceId = typeof obj.voiceId === 'string' && obj.voiceId !== '' ? obj.voiceId : null;
+        if (!Number.isFinite(speed) && voiceId === null)
+            return null;
+        return { speed: Number.isFinite(speed) ? speed : 1, voiceId };
+    }
+    catch {
+        return null;
+    }
+}
+/** Write prefs. Best-effort: a throwing/full store is swallowed. */
+export function saveListenPrefs(store, key, prefs) {
+    if (!store || typeof key !== 'string' || key === '')
+        return;
+    try {
+        store.setItem(key, JSON.stringify({ speed: clampSpeed(prefs.speed), voiceId: prefs.voiceId ?? null }));
+    }
+    catch {
+        /* private mode, quota — the session keeps its in-memory values */
+    }
+}
+/** The default store: this browser's localStorage, or null on SSR/private mode. */
+export function localListenStore() {
+    try {
+        return typeof localStorage === 'undefined' ? null : localStorage;
+    }
+    catch {
+        return null;
+    }
+}
+/** Default key prefix — hosts pass `storageKey` to namespace per-page/feature. */
+export const LISTEN_PREFS_KEY = 'jatui.listen:prefs';