@joewinke/jatui 0.34.2 → 0.36.1

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/ThumbnailGrid.svelte

@@ -21,12 +21,28 @@
 		max?: number;
 		/** Tile size. Default 'md'. */
 		size?: 'xs' | 'sm' | 'md' | 'lg';
-		/** Show remove (×) buttons on hover; requires `onRemove`. */
+		/** Show remove (×) buttons; requires `onRemove`. Visibility follows `removeMode`. */
 		removable?: boolean;
+		/**
+		 * When the remove × is visible. 'hover' (default) reveals it on
+		 * hover/focus and keeps it visible on coarse (touch) pointers — a
+		 * hover-only control is unusable on touch (the ContextMenuTrigger
+		 * pattern). 'always' pins it visible for touch-first flows.
+		 */
+		removeMode?: 'hover' | 'always';
 		/** Show the dashed add tile at the end; requires `onAdd`. */
 		addable?: boolean;
 		/** Tooltip / aria-label for the add tile. Default 'Add items'. */
 		addLabel?: string;
+		/**
+		 * Tailwind grid-cols classes for a responsive tile grid, e.g.
+		 * 'grid-cols-2 sm:grid-cols-4'. When set, the root renders as a CSS grid
+		 * (`grid {gridCols} gap-2`) instead of the fixed flex-wrap strip, and
+		 * tiles stretch to fill their column (height still follows `size`).
+		 */
+		gridCols?: string;
+		/** Extra classes for the root container, composed after the layout classes. */
+		class?: string;
 		/** Fired when a thumbnail is clicked. */
 		onSelect?: (item: ThumbnailItem) => void;
 		/** Fired when a remove (×) button is clicked. */
@@ -46,12 +62,15 @@
 		max = 8,
 		size = 'md',
 		removable = false,
+		removeMode = 'hover',
 		addable = false,
 		addLabel = 'Add items',
+		gridCols,
 		onSelect,
 		onRemove,
 		onAdd,
-		cell
+		cell,
+		class: className = ''
 	}: Props = $props();
 
 	const sizeClasses: Record<NonNullable<Props['size']>, string> = {
@@ -63,18 +82,26 @@
 
 	const visible = $derived(items.slice(0, max));
 	const overflow = $derived(Math.max(0, items.length - max));
+	/** Grid mode when the caller supplies grid-cols classes; tiles fill their column. */
+	const isGrid = $derived(Boolean(gridCols));
+	const fillClass = $derived(isGrid ? ' w-full' : '');
+	const removeVisibility = $derived(
+		removeMode === 'always'
+			? 'opacity-100'
+			: 'opacity-0 transition-opacity group-hover:opacity-100 focus-visible:opacity-100 pointer-coarse:opacity-100'
+	);
 
 	function shortLabel(alt: string): string {
 		return alt.length > 14 ? `${alt.slice(0, 14)}…` : alt;
 	}
 </script>
 
-<div class="flex flex-wrap items-center gap-2">
+<div class="{isGrid ? 'grid gap-2' : 'flex flex-wrap items-center gap-2'} {gridCols ?? ''} {className}">
 	{#each visible as item (item.id)}
 		<div class="group relative">
 			<button
 				type="button"
-				class="{sizeClasses[size]} cursor-pointer overflow-hidden rounded border transition-all duration-200
+				class="{sizeClasses[size]}{fillClass} cursor-pointer overflow-hidden rounded border transition-all duration-200
 					{removable ? 'border-2 border-accent' : 'border-base-300 hover:border-primary'}"
 				onclick={() => onSelect?.(item)}
 				title={item.alt}
@@ -96,7 +123,7 @@
 			{#if removable && onRemove}
 				<button
 					type="button"
-					class="absolute -top-1 -right-1 z-10 flex h-4 w-4 items-center justify-center rounded-full bg-error text-error-content opacity-0 transition-opacity group-hover:opacity-100"
+					class="absolute -top-1 -right-1 z-10 flex h-4 w-4 items-center justify-center rounded-full bg-error text-error-content {removeVisibility}"
 					onclick={(e) => {
 						e.stopPropagation();
 						onRemove(item);
@@ -114,7 +141,7 @@
 
 	{#if overflow > 0}
 		<div
-			class="{sizeClasses[size]} flex items-center justify-center rounded border border-base-300 bg-base-200"
+			class="{sizeClasses[size]}{fillClass} flex items-center justify-center rounded border border-base-300 bg-base-200"
 			title="{overflow} more item{overflow === 1 ? '' : 's'}"
 		>
 			<span class="text-xs opacity-70">+{overflow}</span>
@@ -124,7 +151,7 @@
 	{#if addable && onAdd}
 		<button
 			type="button"
-			class="{sizeClasses[size]} flex scale-90 cursor-pointer items-center justify-center rounded border-2 border-dashed border-primary/30 bg-primary/5 transition-all duration-200 hover:border-primary/50 hover:bg-primary/10"
+			class="{sizeClasses[size]}{fillClass} flex scale-90 cursor-pointer items-center justify-center rounded border-2 border-dashed border-primary/30 bg-primary/5 transition-all duration-200 hover:border-primary/50 hover:bg-primary/10"
 			onclick={onAdd}
 			title={addLabel}
 			aria-label={addLabel}

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

@@ -18,12 +18,28 @@ interface Props {
     max?: number;
     /** Tile size. Default 'md'. */
     size?: 'xs' | 'sm' | 'md' | 'lg';
-    /** Show remove (×) buttons on hover; requires `onRemove`. */
+    /** Show remove (×) buttons; requires `onRemove`. Visibility follows `removeMode`. */
     removable?: boolean;
+    /**
+     * When the remove × is visible. 'hover' (default) reveals it on
+     * hover/focus and keeps it visible on coarse (touch) pointers — a
+     * hover-only control is unusable on touch (the ContextMenuTrigger
+     * pattern). 'always' pins it visible for touch-first flows.
+     */
+    removeMode?: 'hover' | 'always';
     /** Show the dashed add tile at the end; requires `onAdd`. */
     addable?: boolean;
     /** Tooltip / aria-label for the add tile. Default 'Add items'. */
     addLabel?: string;
+    /**
+     * Tailwind grid-cols classes for a responsive tile grid, e.g.
+     * 'grid-cols-2 sm:grid-cols-4'. When set, the root renders as a CSS grid
+     * (`grid {gridCols} gap-2`) instead of the fixed flex-wrap strip, and
+     * tiles stretch to fill their column (height still follows `size`).
+     */
+    gridCols?: string;
+    /** Extra classes for the root container, composed after the layout classes. */
+    class?: string;
     /** Fired when a thumbnail is clicked. */
     onSelect?: (item: ThumbnailItem) => void;
     /** Fired when a remove (×) button is clicked. */

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';
@@ -89,7 +93,7 @@ export { default as ResizablePanel } from './components/ResizablePanel.svelte';
 export { default as VoicePlayer } from './components/VoicePlayer.svelte';
 export { default as SpeechForm } from './components/SpeechForm.svelte';
 export { default as AudioRecorder } from './components/AudioRecorder.svelte';
-export type { AudioRecordingResult } from './utils/audioRecorderCore';
+export type { AudioRecordingResult, AudioRecorderChunk } from './utils/audioRecorderCore';
 export { createAudioRecorder } from './utils/audioRecorder';
 export type { AudioRecorder, AudioRecorderCore, AudioRecorderError, AudioRecorderErrorKind, AudioRecorderFrame, AudioRecorderMode, AudioRecorderOptions, AudioRecorderPhase, AudioRecorderSnapshot } from './utils/audioRecorderCore';
 export { default as ThemeSelector } from './components/ThemeSelector.svelte';
@@ -168,7 +172,8 @@ export { default as PipelineColumn } from './components/pipeline/PipelineColumn.
 export { default as PipelineCard } from './components/pipeline/PipelineCard.svelte';
 export type { PipelineStage, StageColors, PipelineItem, PipelineMetric, StageMetrics, PipelineViewMode, PipelineTableColumn, PipelineDragConfig, PipelineConfig, PipelineStageChangeEvent, PipelineItemClickEvent } from './types/pipeline';
 export { DEFAULT_DRAG_CONFIG, DEFAULT_PIPELINE_CONFIG } from './types/pipeline';
-export { parseMentions, renderMentionsAsHTML, createMentionString, extractPlainText, findMentionAtCursor, findPartialMention, replaceMentionInContent, escapeHTML, countMentions, setMentionUrlGenerator } from './utils/mentionParser';
+export { parseMentions, renderMentionsAsHTML, createMentionString, extractPlainText, findMentionAtCursor, findPartialMention, replaceMentionInContent, escapeHTML, countMentions, hasMentions, setMentionUrlGenerator, registerMentionType, extractAgentMentions, getUniqueMentionsByType, getMentionedUserIds, AGENT_MENTION_TYPE } from './utils/mentionParser';
+export type { MentionMatch, MentionUrlGenerator, MentionTypeConfig } from './utils/mentionParser';
 export { default as CommentThread } from './components/CommentThread.svelte';
 export type { Comment, CommentEntityType, CommentVisibility, CommentCreateInput, CommentCallbacks } from './types/comments';
 export { COMMENT_ENTITY_TYPES, COMMENT_VISIBILITIES } from './types/comments';
@@ -183,6 +188,7 @@ export type { MarkupTool, Point, MarkupShape, ArrowShape, RectangleShape, Ellips
 export type { Annotation, AnnotationProfile, AnnotationThread, AnnotationCallbacks, } from './types/annotation';
 export { default as KeyboardShortcutsOverlay } from './components/KeyboardShortcutsOverlay.svelte';
 export type { KeyboardShortcut, SectionEntry as KeyboardShortcutSectionEntry, ShortcutSection as KeyboardShortcutSection, } from './components/KeyboardShortcutsOverlay.svelte';
+export { keyboardShortcutHub, KEYBOARD_SHORTCUT_HUB_ID, type KeyboardShortcutHost, type ShortcutContribution, type ShortcutSectionLike, } from './utils/keyboardShortcutHub';
 export { createShortcutRegistry, getShortcutRegistry, formatShortcut, parseCombo as parseShortcutCombo, isTypingTarget, detectPlatform as detectShortcutPlatform, SIDEBAR_TOGGLE_KEY, normalizeCombo, comboFromEvent, validateCombo, localStorageBindingStore, BROWSER_RESERVED_COMBOS, } from './utils/keyboardShortcutRegistry';
 export type { ShortcutRegistry, ShortcutDefinition, ShortcutModifier, ShortcutPlatform, PushContextOptions as ShortcutContextOptions, RegistrySection as ShortcutRegistrySection, ToSectionsOptions as ShortcutSectionsOptions, ShortcutRegistryOptions, ShortcutEventTarget, ShortcutDeclaration, BindingOverrides, BindingStore, BindingInfo, ShortcutConflict, ShortcutConflictSeverity, FindConflictsTarget, AllConflictsOptions as ShortcutAllConflictsOptions, ReservedCombo, RebindResult, RebindOptions as ShortcutRebindOptions, RejectedBinding, RawShortcutHandler, ModifierState as ShortcutModifierState, } from './utils/keyboardShortcutRegistry';
 export { default as MapView } from './components/MapView.svelte';
@@ -196,7 +202,7 @@ export { staggerEntrance } from './actions/staggerEntrance';
 export type { StaggerEntranceOptions } from './actions/staggerEntrance';
 export { attention } from './actions/attention';
 export type { AttentionEffect, AttentionOptions } from './actions/attention';
-export { reveal, REVEAL_HIDDEN_CLASS, REVEAL_BASE_CLASS } from './actions/reveal';
+export { reveal, REVEAL_HIDDEN_CLASS, REVEAL_BASE_CLASS, REVEAL_OFF_SELECTOR, REVEAL_MAX_DELAY_SECONDS } from './actions/reveal';
 export type { RevealOptions, RevealVariant } from './actions/reveal';
 export { default as ThumbnailGrid } from './components/ThumbnailGrid.svelte';
 export type { ThumbnailItem } from './components/ThumbnailGrid.svelte';

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.
@@ -198,7 +204,7 @@ export { default as PipelineColumn } from './components/pipeline/PipelineColumn.
 export { default as PipelineCard } from './components/pipeline/PipelineCard.svelte';
 export { DEFAULT_DRAG_CONFIG, DEFAULT_PIPELINE_CONFIG } from './types/pipeline';
 // Utilities — mention parsing
-export { parseMentions, renderMentionsAsHTML, createMentionString, extractPlainText, findMentionAtCursor, findPartialMention, replaceMentionInContent, escapeHTML, countMentions, setMentionUrlGenerator } from './utils/mentionParser';
+export { parseMentions, renderMentionsAsHTML, createMentionString, extractPlainText, findMentionAtCursor, findPartialMention, replaceMentionInContent, escapeHTML, countMentions, hasMentions, setMentionUrlGenerator, registerMentionType, extractAgentMentions, getUniqueMentionsByType, getMentionedUserIds, AGENT_MENTION_TYPE } from './utils/mentionParser';
 // Components — Comments (universal threaded comments)
 export { default as CommentThread } from './components/CommentThread.svelte';
 export { COMMENT_ENTITY_TYPES, COMMENT_VISIBILITIES } from './types/comments';
@@ -214,6 +220,7 @@ export { default as AnnotationPanel } from './components/AnnotationPanel.svelte'
 export { MARKUP_COLORS, DEFAULT_STROKE_WIDTH, renderShape, renderAllShapes, nextShapeId, } from './components/markup';
 // Components — Keyboard Navigation
 export { default as KeyboardShortcutsOverlay } from './components/KeyboardShortcutsOverlay.svelte';
+export { keyboardShortcutHub, KEYBOARD_SHORTCUT_HUB_ID, } from './utils/keyboardShortcutHub';
 export { createShortcutRegistry, getShortcutRegistry, formatShortcut, parseCombo as parseShortcutCombo, isTypingTarget, detectPlatform as detectShortcutPlatform, SIDEBAR_TOGGLE_KEY, normalizeCombo, comboFromEvent, validateCombo, localStorageBindingStore, BROWSER_RESERVED_COMBOS, } from './utils/keyboardShortcutRegistry';
 // Components — Google Maps (DispatchMap fork + location primitives)
 export { default as MapView } from './components/MapView.svelte';
@@ -237,7 +244,7 @@ export { attention } from './actions/attention';
 // Scroll-reveal (jatui-m4uz3.3, chimaro port): IntersectionObserver
 // scroll-reveal whose variants live in styles/motion.css as jatui-reveal-*
 // classes on the --motion-* tokens — no shipped animista.css.
-export { reveal, REVEAL_HIDDEN_CLASS, REVEAL_BASE_CLASS } from './actions/reveal';
+export { reveal, REVEAL_HIDDEN_CLASS, REVEAL_BASE_CLASS, REVEAL_OFF_SELECTOR, REVEAL_MAX_DELAY_SECONDS } from './actions/reveal';
 // Thumbnail grid (jatui-m4uz3.3, chimaro port): generic {id,url,alt} strip
 // with overflow counter, remove/add affordances and a cell snippet override.
 export { default as ThumbnailGrid } from './components/ThumbnailGrid.svelte';

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 */
+    }
+}