@tinytars/frame 0.1.29 → 0.1.30

package/PersonaBubble.svelte

@@ -3,6 +3,7 @@
   import LeafActionMenu from "@tinytars/frame/LeafActionMenu.svelte";
   import type { LeafMenuItem } from "@tinytars/frame/menu-items";
   import { speechRegistry, isSpeechSupported } from "./speech-registry.svelte";
+  import { currentRetell } from "./retell-registry.svelte";
 
   // The one persona treatment: a tinted bubble with a head row (uppercase persona tag on the
   // left; an optional meta/date and an optional action icon, e.g. download, on the right). Colors
@@ -24,58 +25,100 @@
     onTogglePin?: () => void;
     pinDisplay?: "auto" | "hidden";
     actions?: BubbleAction[];
+    // Opaque to this package: handed to the app's configured SpeechEngine.
+    voice?: string;
+    // False where the body is already a chosen telling (e.g. a chat reply in the picked persona).
+    retellable?: boolean;
     children?: Snippet;
   }
-  let { persona, label, meta, id, pinned = false, onTogglePin, pinDisplay = "auto", actions, children }: Props = $props();
+  let { persona, label, meta, id, pinned = false, onTogglePin, pinDisplay = "auto", actions, voice, retellable = true, children }: Props = $props();
 
-  // Every assistant-generated bubble gets Speak for free: reads bodyEl's own rendered text at click
-  // time rather than a prop threaded through every one of this component's call sites, so no
-  // existing caller needs to change. speechRegistry is the shared "only one thing speaks at a time"
-  // singleton (mirrors menu-registry.svelte.ts); clicking the currently-speaking bubble's own button
-  // again toggles it off (speechRegistry.speak handles that toggle internally).
+  // Every assistant-generated bubble gets read-aloud for free. It reads bodyEl's rendered text at
+  // click time instead of taking a prop, so no caller has to change. speechRegistry is the shared
+  // player, and SpeechControls keeps playback controllable after this bubble unmounts.
   const uid = $props.id();
   const bubbleId = `${persona}-${uid}`;
   const speakable = $derived(persona === "assistant" && isSpeechSupported());
-  const speaking = $derived(speechRegistry.isSpeaking(bubbleId));
+  const speech = $derived(speechRegistry.statusOf(bubbleId));
+  const speakTitle = $derived(speech === "playing" ? "Pause reading" : speech === "paused" ? "Resume reading" : "Read aloud");
   let bodyEl: HTMLDivElement | undefined;
+
+  // A retelling replaces the body in place, so read-aloud and the label follow what is on screen.
+  // It lasts only while the app still offers that retelling.
+  const retell = $derived(persona === "assistant" && retellable && children ? currentRetell() : null);
+  let retold = $state<{ by: string; text: string } | null>(null);
+  let retelling = $state(false);
+  const shownRetold = $derived(retold && retell && retold.by === retell.label ? retold : null);
+  const shownLabel = $derived(shownRetold ? shownRetold.by : label);
+  async function toggleRetell() {
+    if (shownRetold) { retold = null; return; }
+    const r = retell!;
+    retelling = true;
+    const text = await r.retell(bodyEl?.textContent ?? "").catch(() => null);
+    retelling = false;
+    retold = text ? { by: r.label, text } : null;
+  }
+  const menuItems = $derived<BubbleAction[]>([
+    ...(actions ?? []),
+    ...(retell ? [{
+      key: "retell",
+      label: retelling ? `${retell.label}…` : shownRetold ? "Show original" : retell.label,
+      disabled: retelling,
+      onClick: toggleRetell,
+    }] : []),
+  ]);
+
   function toggleSpeak() {
-    speechRegistry.speak(bubbleId, bodyEl?.textContent ?? "");
+    speechRegistry.toggle(bubbleId, bodyEl?.textContent ?? "", meta ? `${shownLabel} · ${meta}` : shownLabel, shownRetold ? retell?.voice : voice);
   }
 </script>
 
-<div class="persona-bubble p-{persona}" {id}>
+<div class="persona-bubble p-{persona}" {id} data-speech-id={speakable ? bubbleId : undefined}>
   <div class="persona-head">
     <span class="persona-head-left">
-      <span class="persona-tag">{label}</span>
+      <span class="persona-tag">{shownLabel}</span>
     </span>
-    {#if meta || actions?.length || onTogglePin || speakable}
+    {#if meta || menuItems.length || onTogglePin || speakable}
       <span class="persona-head-right">
         {#if meta}<span class="persona-meta">{meta}</span>{/if}
         {#if speakable}
           <button
             type="button"
             class="persona-speak"
-            class:speaking
-            title={speaking ? "Stop reading" : "Read aloud"}
-            aria-label={speaking ? "Stop reading" : "Read aloud"}
-            aria-pressed={speaking}
+            class:active={speech !== "idle"}
+            title={speakTitle}
+            aria-label={speakTitle}
             onclick={toggleSpeak}
-          >{speaking ? "⏸" : "🔊"}</button>
+          >{speech === "playing" ? "⏸\uFE0E" : "▶\uFE0E"}</button>
+          {#if speech !== "idle"}
+            <button
+              type="button"
+              class="persona-speak"
+              title="Stop reading"
+              aria-label="Stop reading"
+              onclick={() => speechRegistry.stop()}
+            >⏹&#xFE0E;</button>
+          {/if}
         {/if}
-        {#if actions?.length || onTogglePin}
-          <LeafActionMenu items={actions ?? []} {pinned} {onTogglePin} {pinDisplay} />
+        {#if menuItems.length || onTogglePin}
+          <LeafActionMenu items={menuItems} {pinned} {onTogglePin} {pinDisplay} />
         {/if}
       </span>
     {/if}
   </div>
-  {#if children}<div class="persona-body" bind:this={bodyEl}>{@render children()}</div>{/if}
+  {#if children}
+    <div class="persona-body" bind:this={bodyEl}>
+      {#if shownRetold}<p class="persona-retold">{shownRetold.text}</p>{:else}{@render children()}{/if}
+    </div>
+  {/if}
 </div>
 
 <style>
+  .persona-retold { margin: 0; white-space: pre-wrap; }
   .persona-speak {
     flex-shrink: 0; border: none; background: none; cursor: pointer;
     font-size: 0.95rem; line-height: 1; padding: 0.3rem; border-radius: 6px; color: var(--muted);
   }
   .persona-speak:hover { background: color-mix(in srgb, var(--accent) 10%, transparent); color: var(--fg); }
-  .persona-speak.speaking { color: var(--accent); }
+  .persona-speak.active { color: var(--accent); }
 </style>

package/SpeechControls.svelte

@@ -0,0 +1,47 @@
+<script lang="ts">
+  import { speechRegistry } from "./speech-registry.svelte";
+
+  // The global now-playing pill. Reading keeps going after its bubble unmounts (tab or leaf switch),
+  // so this is the control that is always reachable. It renders nothing while idle.
+  const now = $derived(speechRegistry.current());
+  const playing = $derived(now.status === "playing");
+
+  function reveal() {
+    document.querySelector(`[data-speech-id="${now.id}"]`)?.scrollIntoView({ behavior: "smooth", block: "center" });
+  }
+</script>
+
+{#if now.status !== "idle"}
+  <div class="speech-controls" role="region" aria-label="Read aloud">
+    <button type="button" class="sc-label" title="Show what is being read" onclick={reveal}>{now.label}</button>
+    <span class="sc-progress" aria-label="Sentence {now.index + 1} of {now.total}">{now.index + 1} / {now.total}</span>
+    <button
+      type="button"
+      class="sc-btn"
+      title={playing ? "Pause reading" : "Resume reading"}
+      aria-label={playing ? "Pause reading" : "Resume reading"}
+      onclick={() => (playing ? speechRegistry.pause() : speechRegistry.resume())}
+    >{playing ? "⏸︎" : "▶︎"}</button>
+    <button type="button" class="sc-btn" title="Stop reading" aria-label="Stop reading" onclick={() => speechRegistry.stop()}>⏹&#xFE0E;</button>
+  </div>
+{/if}
+
+<style>
+  .speech-controls {
+    position: fixed; bottom: 1rem; right: 1rem; z-index: 40;
+    display: flex; align-items: center; gap: 0.35rem; max-width: calc(100vw - 2rem);
+    padding: 0.3rem 0.4rem 0.3rem 0.8rem; border-radius: 999px;
+    background: var(--panel); color: var(--fg); border: 1px solid var(--border);
+    box-shadow: 0 4px 16px rgba(0, 0, 0, 0.18); font-size: 0.85rem;
+  }
+  .sc-label {
+    border: none; background: none; color: inherit; cursor: pointer; padding: 0;
+    font: inherit; font-weight: 600; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+  }
+  .sc-progress { color: var(--muted); font-variant-numeric: tabular-nums; white-space: nowrap; }
+  .sc-btn {
+    border: none; background: none; cursor: pointer; color: var(--accent);
+    font-size: 0.95rem; line-height: 1; padding: 0.35rem; border-radius: 999px;
+  }
+  .sc-btn:hover { background: color-mix(in srgb, var(--accent) 12%, transparent); }
+</style>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tinytars/frame",
-  "version": "0.1.29",
+  "version": "0.1.30",
   "description": "Domain-neutral Svelte app-shell: session/auth controllers, account chrome, and menu/card/modal primitives built on @tinytars/vault.",
   "license": "MIT",
   "type": "module",
@@ -70,6 +70,8 @@
     "./SidebarGroupList.svelte": "./SidebarGroupList.svelte",
     "./SidebarLeafList.svelte": "./SidebarLeafList.svelte",
     "./speech-registry.svelte": "./speech-registry.svelte.ts",
+    "./retell-registry.svelte": "./retell-registry.svelte.ts",
+    "./SpeechControls.svelte": "./SpeechControls.svelte",
     "./support-access.svelte": "./support-access.svelte.ts",
     "./theme.css": "./theme.css",
     "./time-ago": "./time-ago.ts",

package/retell-registry.svelte.ts

@@ -0,0 +1,18 @@
+// An app may offer a second telling of any assistant bubble (e.g. the same content in another voice).
+// PersonaBubble adds a menu item for it while one is configured; this package knows nothing of what
+// the retelling says, only its label and the voice it is read aloud in.
+export interface Retell {
+  label: string;
+  voice?: string;
+  retell(text: string): Promise<string | null>;
+}
+
+const state = $state<{ current: Retell | null }>({ current: null });
+
+export function configureRetell(r: Retell | null): void {
+  state.current = r;
+}
+
+export function currentRetell(): Retell | null {
+  return state.current;
+}

package/speech-registry.svelte.ts

@@ -1,50 +1,189 @@
-// The one shared "who's currently speaking" registry, mirroring menu-registry.svelte.ts's
-// singleton shape: starting a new utterance stops whatever else was speaking, and clicking the
-// currently-speaking bubble's own button again stops it (toggle) — the same "only one thing
-// active" convention a popover-heavy UI wants for this too.
+// The one shared read-aloud player. It mirrors menu-registry.svelte.ts's singleton shape: playing one
+// thing stops whatever else was playing.
 //
-// speechSynthesis is a real, global, OS-level engine — it can finish an utterance (or fail) entirely
-// on its own, not just via a manual stop() call. `onend`/`onerror` on the utterance are what keep
-// `speakingId` in sync with reality in that case; a plain isSpeaking() flag flipped only at the two
-// call sites (speak/stop) would go stale the instant a normal utterance finishes.
-const state = $state<{ speakingId: string | null }>({ speakingId: null });
+// Text is spoken one chunk (roughly one sentence) at a time, and each chunk's `end` starts the next.
+// Chromium silently cuts off a single long utterance after ~15s, and chunking is also what makes
+// progress and resume possible. Pause is cancel() plus a remembered index, not
+// speechSynthesis.pause(), which is a no-op or broken on Android Chrome and some Linux voices. Resume
+// restarts the current chunk.
+//
+// The engine finishes or fails utterances on its own. cancel()'s `end` also arrives as a separate
+// task, after the call that caused it. So every utterance captures the `generation` it was spoken
+// under. Each pause, stop, or new play bumps that counter, which makes a late event from a
+// superseded chunk a no-op.
+//
+// An app may configure a SpeechEngine: each chunk is then synthesized to audio (a neural voice) and
+// played through an HTMLAudioElement, the next chunk prefetched while the current one plays. If the
+// engine or playback fails, the rest of that playback falls back to the browser voice.
+export type SpeechStatus = "idle" | "playing" | "paused";
+
+export interface SpeechEngine {
+  synthesize(text: string, voice?: string): Promise<Blob>;
+  normalize?(text: string): string;
+}
+
+const MAX_CHUNK = 200;
+
+const state = $state({
+  id: null as string | null,
+  label: "",
+  status: "idle" as SpeechStatus,
+  chunks: [] as string[],
+  index: 0,
+});
+let generation = 0;
+let engine: SpeechEngine | null = null;
+let voice: string | undefined;
+let neural = false;
+let audio: HTMLAudioElement | null = null;
+let clips = new Map<number, Promise<string>>();
+
+export function configureSpeech(e: SpeechEngine | null): void {
+  engine = e;
+}
 
 function synth(): SpeechSynthesis | undefined {
   return typeof window !== "undefined" ? window.speechSynthesis : undefined;
 }
 
 export function isSpeechSupported(): boolean {
-  return !!synth();
+  return !!engine || !!synth();
+}
+
+function pack(parts: string[]): string[] {
+  const out: string[] = [];
+  let buf = "";
+  for (const p of parts) {
+    const next = buf ? `${buf} ${p}` : p;
+    if (buf && next.length > MAX_CHUNK) {
+      out.push(buf);
+      buf = p;
+    } else {
+      buf = next;
+    }
+  }
+  if (buf) out.push(buf);
+  return out;
+}
+
+export function speechChunks(text: string): string[] {
+  const sentences = Array.from(new Intl.Segmenter(undefined, { granularity: "sentence" }).segment(text), (s) => s.segment.trim())
+    .filter(Boolean);
+  return pack(sentences.flatMap((s) => (s.length > MAX_CHUNK ? pack(s.split(/\s+/)) : [s])));
+}
+
+function halt() {
+  generation++;
+  synth()?.cancel();
+  audio?.pause();
+  audio = null;
+}
+
+function releaseClips() {
+  for (const p of clips.values()) p.then((url) => URL.revokeObjectURL(url), () => {});
+  clips = new Map();
+}
+
+function reset() {
+  releaseClips();
+  neural = false;
+  state.id = null;
+  state.label = "";
+  state.status = "idle";
+  state.chunks = [];
+  state.index = 0;
+}
+
+function advance(gen: number) {
+  if (gen !== generation) return;
+  if (state.index + 1 < state.chunks.length) {
+    state.index++;
+    speakCurrent();
+  } else {
+    reset();
+  }
+}
+
+function speakCurrent() {
+  const gen = ++generation;
+  if (neural) speakNeural(gen);
+  else speakBrowser(gen);
+}
+
+function speakBrowser(gen: number) {
+  const utterance = new SpeechSynthesisUtterance(state.chunks[state.index]);
+  utterance.onend = () => advance(gen);
+  utterance.onerror = () => { if (gen === generation) reset(); };
+  synth()!.speak(utterance);
+}
+
+function clip(i: number): Promise<string> {
+  let p = clips.get(i);
+  if (!p) {
+    p = engine!.synthesize(state.chunks[i], voice).then((blob) => URL.createObjectURL(blob));
+    clips.set(i, p);
+  }
+  return p;
+}
+
+function speakNeural(gen: number) {
+  const i = state.index;
+  clip(i).then((url) => {
+    if (gen !== generation) return;
+    const a = new Audio(url);
+    audio = a;
+    a.onended = () => advance(gen);
+    a.onerror = () => fallBack(gen);
+    a.play().catch(() => fallBack(gen));
+    if (i + 1 < state.chunks.length) clip(i + 1).catch(() => {});
+  }, () => fallBack(gen));
+}
+
+function fallBack(gen: number) {
+  if (gen !== generation) return;
+  neural = false;
+  audio = null;
+  if (synth()) speakBrowser(gen);
+  else reset();
 }
 
 export const speechRegistry = {
-  isSpeaking(id: string): boolean {
-    return state.speakingId === id;
+  statusOf(id: string): SpeechStatus {
+    return state.id === id ? state.status : "idle";
   },
-  speak(id: string, text: string): void {
-    const s = synth();
-    if (!s || !text.trim()) return;
-    // cancel()'s `end` event is dispatched as its own task, never inside this call — which is what
-    // makes the toggle below reachable, since it compares against a speakingId this cancel has not
-    // had the chance to clear. The old speakingId is cleared by the assignment further down (or by
-    // the toggle); each handler guards on its own id so a late `end` cannot clear a newer utterance.
-    // (An earlier version of this comment claimed the opposite, that cancel() fires onend
-    // SYNCHRONOUSLY and that this is what clears the old id. Were that true the toggle would be
-    // dead code and a second click would re-speak.)
-    s.cancel();
-    if (state.speakingId === id) {
-      // Toggle: clicking the already-speaking bubble's own button again just stops it.
-      state.speakingId = null;
-      return;
-    }
-    const utterance = new SpeechSynthesisUtterance(text);
-    utterance.onend = () => { if (state.speakingId === id) state.speakingId = null; };
-    utterance.onerror = () => { if (state.speakingId === id) state.speakingId = null; };
-    state.speakingId = id;
-    s.speak(utterance);
+  current() {
+    return { id: state.id, label: state.label, status: state.status, index: state.index, total: state.chunks.length };
+  },
+  play(id: string, text: string, label: string, withVoice?: string): void {
+    const chunks = speechChunks(engine?.normalize ? engine.normalize(text) : text);
+    if (!isSpeechSupported() || !chunks.length) return;
+    halt();
+    releaseClips();
+    voice = withVoice;
+    neural = !!engine;
+    Object.assign(state, { id, label, status: "playing", chunks, index: 0 });
+    speakCurrent();
+  },
+  pause(): void {
+    if (state.status !== "playing") return;
+    halt();
+    state.status = "paused";
+  },
+  resume(): void {
+    if (state.status !== "paused" || !isSpeechSupported()) return;
+    state.status = "playing";
+    speakCurrent();
+  },
+  toggle(id: string, text: string, label: string, withVoice?: string): void {
+    if (state.id !== id) this.play(id, text, label, withVoice);
+    else if (state.status === "playing") this.pause();
+    else this.resume();
   },
   stop(): void {
-    synth()?.cancel();
-    state.speakingId = null;
+    halt();
+    reset();
   },
 };
+
+// Nothing keeps speaking into a page that is being navigated away from or put in the bfcache.
+if (typeof window !== "undefined") window.addEventListener("pagehide", () => speechRegistry.stop());