@joewinke/jatui 0.34.2 → 0.35.0

package/dist/listen/segments.d.ts

@@ -0,0 +1,101 @@
+/**
+ * ListenControl sequencing — the ONE timeline across per-sentence audio
+ * files (jatui-eev2n).
+ *
+ * A "listen to this page" player is a playlist, not one media element: the
+ * host synthesizes each sentence/paragraph separately, so the player walks
+ * segments sequentially and reports ONE document-wide time. Every position —
+ * the elapsed clock, the progress fill, the chapter ticks, a ±15s skip that
+ * crosses a segment boundary, a seek from the slider — maps through
+ * `buildTimeline`'s offsets, the same one-axis discipline the VideoPlayer
+ * band uses (`video/band/axis.ts`).
+ *
+ * Pure and DOM-free: safe on garbage input, node-testable.
+ */
+import type { ListenChapter, ListenSegment, ListenSegmentPage, ListenSegmentSource } from './types';
+/** Placeholder width of a segment whose duration is not known yet (pending synth). */
+export declare const DEFAULT_ESTIMATE_SEC = 3;
+/**
+ * A "previous sentence" press RESTARTS the current segment when it is already
+ * this deep in — past that it means "the one before". Podcast |</<< convention.
+ */
+export declare const SENTENCE_RESTART_SEC = 3;
+/** The document-wide timeline: each segment's start, effective duration and total. */
+export interface ListenTimeline {
+    /** Start time of each segment on the one timeline. */
+    offsets: number[];
+    /** Measured > host-supplied > estimated duration per segment. */
+    durations: number[];
+    /** `offsets[n] + durations[n]` — the end of the last segment. */
+    total: number;
+    /** True where the duration is the estimate, not a real one. */
+    estimated: boolean[];
+}
+/**
+ * Is this segment playable right now? A segment exists before its audio does
+ * (`url: null` while synthesizing).
+ */
+export declare function isPlayable(segment: ListenSegment | null | undefined): boolean;
+/** First index ≥ `from` with playable audio; -1 when none. */
+export declare function firstPlayableFrom(segments: ListenSegment[], from?: number): number;
+/**
+ * The one timeline. An unknown duration borrows `estimateSec` so later
+ * segments still get stable offsets (self-correcting as real durations land);
+ * `estimated[i]` says which, so the UI can hatch the not-yet-real tail.
+ */
+export declare function buildTimeline(segments: ListenSegment[], estimateSec?: number): ListenTimeline;
+/** Where does document time `t` live? Binary search; `t` past the end clamps to the last segment's end. */
+export declare function locate(t: number, timeline: ListenTimeline): {
+    index: number;
+    into: number;
+} | null;
+/**
+ * Document-time seek: ±delta from `t`, clamped to [0, total]. Returns the
+ * segment to load and the offset into it — a skip that lands mid-segment
+ * resumes inside it; one that lands past an estimate still resolves (the
+ * offset self-corrects when the real duration arrives).
+ */
+export declare function seekTo(t: number, timeline: ListenTimeline): {
+    index: number;
+    into: number;
+} | null;
+/**
+ * Previous / next SENTENCE (the skip-sentence controls and ←/→ keys). Each
+ * segment is one sentence, so the move is index±1 — with one exception: deep
+ * inside the current segment (past `SENTENCE_RESTART_SEC`) "previous" means
+ * "restart this one". Returns the target index, or null at the edge.
+ */
+export declare function jumpSentence(index: number, into: number, count: number, direction: 1 | -1, restartAfterSec?: number): number | null;
+/** A chapter tick for every chapter that owns at least one segment; `frac` is its 0–100 % position. */
+export declare function chapterTicks(chapters: ListenChapter[], segments: ListenSegment[], timeline: ListenTimeline): {
+    id: string;
+    label: string;
+    frac: number;
+}[];
+/** The chapter active at document time `t` — for the bar's section caption. */
+export declare function activeChapter(chapters: ListenChapter[], segments: ListenSegment[], timeline: ListenTimeline, t: number): {
+    id: string;
+    label: string;
+} | null;
+/**
+ * Merge one page into the running list. New ids append in page order; a
+ * REPEATED id is an update — the host streaming a later page that fills
+ * `url`/`durationSec` in for a segment it announced before. Only defined
+ * fields overwrite (a page that re-announces `{id}` alone changes nothing),
+ * so late-arriving audio can never blank a known field.
+ */
+export declare function mergePages(existing: ListenSegment[], page: ListenSegmentPage): ListenSegment[];
+/**
+ * Normalize the four source shapes (async iterable, sync iterable, Promise of
+ * a page, bare page) into one async iteration, so the component consumes a
+ * single `for await`. A rejected/throwing source ends the iteration — the
+ * component keeps whatever pages landed and flags `done`.
+ */
+export declare function iterateSource(source: ListenSegmentSource, voiceId: string): AsyncGenerator<ListenSegmentPage, void, undefined>;
+/**
+ * The contiguous run of NOT-yet-synthesized segments at the end of the list —
+ * the common TTS shape (synthesized in order). The progress bar hatches this
+ * region to say "more is coming". Returns the start index, or -1 when every
+ * trailing segment already has audio.
+ */
+export declare function pendingTailStart(segments: ListenSegment[]): number;

package/dist/listen/segments.js

@@ -0,0 +1,224 @@
+/**
+ * ListenControl sequencing — the ONE timeline across per-sentence audio
+ * files (jatui-eev2n).
+ *
+ * A "listen to this page" player is a playlist, not one media element: the
+ * host synthesizes each sentence/paragraph separately, so the player walks
+ * segments sequentially and reports ONE document-wide time. Every position —
+ * the elapsed clock, the progress fill, the chapter ticks, a ±15s skip that
+ * crosses a segment boundary, a seek from the slider — maps through
+ * `buildTimeline`'s offsets, the same one-axis discipline the VideoPlayer
+ * band uses (`video/band/axis.ts`).
+ *
+ * Pure and DOM-free: safe on garbage input, node-testable.
+ */
+/** Placeholder width of a segment whose duration is not known yet (pending synth). */
+export const DEFAULT_ESTIMATE_SEC = 3;
+/**
+ * A "previous sentence" press RESTARTS the current segment when it is already
+ * this deep in — past that it means "the one before". Podcast |</<< convention.
+ */
+export const SENTENCE_RESTART_SEC = 3;
+/**
+ * Is this segment playable right now? A segment exists before its audio does
+ * (`url: null` while synthesizing).
+ */
+export function isPlayable(segment) {
+    return typeof segment?.url === 'string' && segment.url.length > 0;
+}
+/** First index ≥ `from` with playable audio; -1 when none. */
+export function firstPlayableFrom(segments, from = 0) {
+    for (let i = Math.max(0, from); i < segments.length; i++)
+        if (isPlayable(segments[i]))
+            return i;
+    return -1;
+}
+/**
+ * The one timeline. An unknown duration borrows `estimateSec` so later
+ * segments still get stable offsets (self-correcting as real durations land);
+ * `estimated[i]` says which, so the UI can hatch the not-yet-real tail.
+ */
+export function buildTimeline(segments, estimateSec = DEFAULT_ESTIMATE_SEC) {
+    const est = Number.isFinite(estimateSec) && estimateSec > 0 ? estimateSec : DEFAULT_ESTIMATE_SEC;
+    const offsets = [];
+    const durations = [];
+    const estimated = [];
+    let at = 0;
+    for (const s of segments) {
+        offsets.push(at);
+        const d = s.durationSec;
+        const known = Number.isFinite(d) && d > 0 ? d : est;
+        estimated.push(!(Number.isFinite(d) && d > 0));
+        durations.push(known);
+        at += known;
+    }
+    return { offsets, durations, estimated, total: at };
+}
+/** Where does document time `t` live? Binary search; `t` past the end clamps to the last segment's end. */
+export function locate(t, timeline) {
+    const n = timeline.offsets.length;
+    if (n === 0)
+        return null;
+    if (!Number.isFinite(t) || t <= 0)
+        return { index: 0, into: 0 };
+    // Binary search the highest segment whose offset <= t.
+    let lo = 0;
+    let hi = n - 1;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (timeline.offsets[mid] <= t)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return { index: lo, into: Math.min(t - timeline.offsets[lo], timeline.durations[lo]) };
+}
+/**
+ * Document-time seek: ±delta from `t`, clamped to [0, total]. Returns the
+ * segment to load and the offset into it — a skip that lands mid-segment
+ * resumes inside it; one that lands past an estimate still resolves (the
+ * offset self-corrects when the real duration arrives).
+ */
+export function seekTo(t, timeline) {
+    const n = timeline.offsets.length;
+    if (n === 0)
+        return null;
+    const clamped = Math.min(Math.max(0, Number.isFinite(t) ? t : 0), timeline.total);
+    const at = locate(clamped, timeline);
+    return at ? { index: at.index, into: Math.min(at.into, timeline.durations[at.index]) } : null;
+}
+/**
+ * Previous / next SENTENCE (the skip-sentence controls and ←/→ keys). Each
+ * segment is one sentence, so the move is index±1 — with one exception: deep
+ * inside the current segment (past `SENTENCE_RESTART_SEC`) "previous" means
+ * "restart this one". Returns the target index, or null at the edge.
+ */
+export function jumpSentence(index, into, count, direction, restartAfterSec = SENTENCE_RESTART_SEC) {
+    if (count === 0 || !Number.isFinite(index))
+        return null;
+    const i = Math.min(Math.max(0, Math.floor(index)), count - 1);
+    if (direction === 1)
+        return i < count - 1 ? i + 1 : null;
+    // Backwards: restart the current sentence first when we are already deep in it.
+    if (Number.isFinite(into) && into > restartAfterSec)
+        return i;
+    return i > 0 ? i - 1 : null;
+}
+/** A chapter tick for every chapter that owns at least one segment; `frac` is its 0–100 % position. */
+export function chapterTicks(chapters, segments, timeline) {
+    if (timeline.total <= 0 || chapters.length === 0)
+        return [];
+    const firstOf = new Map();
+    for (let i = 0; i < segments.length; i++) {
+        const cid = segments[i].chapterId;
+        if (cid && !firstOf.has(cid))
+            firstOf.set(cid, i);
+    }
+    const ticks = [];
+    for (const c of chapters) {
+        const i = firstOf.get(c.id);
+        if (i === undefined)
+            continue;
+        ticks.push({ id: c.id, label: c.label, frac: Math.min(100, (timeline.offsets[i] / timeline.total) * 100) });
+    }
+    return ticks;
+}
+/** The chapter active at document time `t` — for the bar's section caption. */
+export function activeChapter(chapters, segments, timeline, t) {
+    if (chapters.length === 0 || segments.length === 0)
+        return null;
+    const at = locate(t, timeline);
+    if (!at)
+        return null;
+    // Walk back from the current segment to the nearest one that names a chapter.
+    for (let i = at.index; i >= 0; i--) {
+        const cid = segments[i].chapterId;
+        if (!cid)
+            continue;
+        const c = chapters.find((x) => x.id === cid);
+        if (c)
+            return { id: c.id, label: c.label };
+    }
+    return null;
+}
+/**
+ * Merge one page into the running list. New ids append in page order; a
+ * REPEATED id is an update — the host streaming a later page that fills
+ * `url`/`durationSec` in for a segment it announced before. Only defined
+ * fields overwrite (a page that re-announces `{id}` alone changes nothing),
+ * so late-arriving audio can never blank a known field.
+ */
+export function mergePages(existing, page) {
+    const incoming = Array.isArray(page?.segments) ? page.segments : [];
+    if (incoming.length === 0)
+        return existing;
+    const out = existing.slice();
+    const byId = new Map();
+    out.forEach((s, i) => byId.set(s.id, i));
+    for (const raw of incoming) {
+        if (!raw || typeof raw.id !== 'string' || raw.id === '')
+            continue;
+        const i = byId.get(raw.id);
+        if (i === undefined) {
+            byId.set(raw.id, out.length);
+            out.push({ ...raw });
+        }
+        else {
+            const prev = out[i];
+            out[i] = {
+                ...prev,
+                ...(raw.text !== undefined ? { text: raw.text } : {}),
+                ...(raw.url !== undefined ? { url: raw.url } : {}),
+                ...(raw.durationSec !== undefined ? { durationSec: raw.durationSec } : {}),
+                ...(raw.chapterId !== undefined ? { chapterId: raw.chapterId } : {})
+            };
+        }
+    }
+    return out;
+}
+/**
+ * Normalize the four source shapes (async iterable, sync iterable, Promise of
+ * a page, bare page) into one async iteration, so the component consumes a
+ * single `for await`. A rejected/throwing source ends the iteration — the
+ * component keeps whatever pages landed and flags `done`.
+ */
+export async function* iterateSource(source, voiceId) {
+    const result = source(voiceId);
+    if (result == null)
+        return;
+    const asPromise = result;
+    if (typeof asPromise.then === 'function') {
+        yield await asPromise;
+        return;
+    }
+    const asAsync = result;
+    if (typeof asAsync[Symbol.asyncIterator] === 'function') {
+        for await (const page of asAsync) {
+            if (page != null)
+                yield page;
+        }
+        return;
+    }
+    const asSync = result;
+    if (typeof asSync[Symbol.iterator] === 'function') {
+        for (const page of asSync) {
+            if (page != null)
+                yield page;
+        }
+        return;
+    }
+    // Bare page.
+    yield result;
+}
+/**
+ * The contiguous run of NOT-yet-synthesized segments at the end of the list —
+ * the common TTS shape (synthesized in order). The progress bar hatches this
+ * region to say "more is coming". Returns the start index, or -1 when every
+ * trailing segment already has audio.
+ */
+export function pendingTailStart(segments) {
+    let i = segments.length;
+    while (i > 0 && !isPlayable(segments[i - 1]))
+        i--;
+    return i < segments.length ? i : -1;
+}

package/dist/listen/types.d.ts

@@ -0,0 +1,81 @@
+/**
+ * ListenControl data contracts (jatui-eev2n) — the "listen to this page"
+ * playback component. Pure types, DOM-free, node-testable like
+ * `video/types.ts`; the component re-exports them so
+ * `import type … from 'jatui'` keeps working.
+ */
+/** One listenable unit — a sentence or paragraph, whichever the host splits at. */
+export interface ListenSegment {
+    /**
+     * Stable id. `onSegmentChange` fires with it as playback crosses segment
+     * boundaries; the host keys its highlight + scroll-follow off it.
+     */
+    id: string;
+    /** The text being read — feeds the bar's caption and aria-live line. */
+    text?: string;
+    /**
+     * Audio for this segment. `null`/`undefined` while the host is still
+     * synthesizing it — the player starts on the first chunk that HAS a url
+     * and lights the rest in as pages arrive.
+     */
+    url?: string | null;
+    /**
+     * Duration in seconds when the host knows it (TTS usually reports it).
+     * Missing durations are measured when the audio loads and ESTIMATED
+     * (`estimateSec`) until then, so the progress bar can lay out before
+     * every chunk exists.
+     */
+    durationSec?: number;
+    /** Section (`ListenChapter.id`) this segment belongs to — drives the progress ticks. */
+    chapterId?: string;
+}
+/** A chapter/section heading — renders as a tick on the progress bar. */
+export interface ListenChapter {
+    id: string;
+    label: string;
+}
+/** A synthetic voice the host offers. The list is host-supplied; the player persists the pick. */
+export interface ListenVoice {
+    id: string;
+    label: string;
+}
+/**
+ * One page from the async segment source. Pages arrive as chunks finish
+ * synthesizing; a page may REPEAT an earlier id to fill its `url` in late
+ * (merge-by-id — `mergePages` in `listen/segments.ts`).
+ */
+export interface ListenSegmentPage {
+    segments: ListenSegment[];
+    /** True on the final page — no more are coming for this voice. */
+    done?: boolean;
+}
+/**
+ * Host-supplied async segment source: ids → audio. Called once per voice
+ * (again when the voice changes) and consumed page by page, so playback can
+ * start on the first chunk while the rest synthesizes. A plain page, a
+ * Promise of one, a sync or async iterable of them all work.
+ */
+export type ListenSegmentSource = (voiceId: string) => AsyncIterable<ListenSegmentPage> | Iterable<ListenSegmentPage> | Promise<ListenSegmentPage> | ListenSegmentPage;
+/** Playback status. `buffering` = the user pressed play but the current segment has no audio yet. */
+export type ListenStatus = 'idle' | 'playing' | 'paused' | 'buffering' | 'ended';
+/**
+ * Instance API (bind:this on ListenControl) — the same actions the bar's
+ * buttons and keyboard map drive, for hosts wiring their own global keys or
+ * external controls.
+ */
+export interface ListenApi {
+    play(): void;
+    pause(): void;
+    toggle(): void;
+    next(): void;
+    prev(): void;
+    /** ±delta seconds on the document-wide timeline. */
+    skip(deltaSec: number): void;
+    /** Seek to a document-wide time (seconds). */
+    seekTo(sec: number): void;
+    open(): void;
+    close(): void;
+    readonly status: ListenStatus;
+    /** The segment under the playhead — null once the document finished. */
+    readonly currentId: string | null;
+}

package/dist/listen/types.js

@@ -0,0 +1,7 @@
+/**
+ * ListenControl data contracts (jatui-eev2n) — the "listen to this page"
+ * playback component. Pure types, DOM-free, node-testable like
+ * `video/types.ts`; the component re-exports them so
+ * `import type … from 'jatui'` keeps working.
+ */
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joewinke/jatui",
-  "version": "0.34.2",
+  "version": "0.35.0",
   "private": false,
   "description": "Shared Svelte 5 component library for JAT projects",
   "type": "module",