beads-map 0.3.4 → 0.3.6

package/components/SettingsModal.tsx

@@ -0,0 +1,237 @@
+"use client";
+
+import { useState, useEffect, useCallback } from "react";
+import { createPortal } from "react-dom";
+import {
+  getSettings,
+  saveSettings,
+  type BeadsMapSettings,
+} from "@/lib/settings";
+
+interface SettingsModalProps {
+  isOpen: boolean;
+  onClose: () => void;
+}
+
+export function SettingsModal({ isOpen, onClose }: SettingsModalProps) {
+  const [apiKey, setApiKey] = useState("");
+  const [voiceId, setVoiceId] = useState("");
+  const [model, setModel] = useState("");
+  const [showKey, setShowKey] = useState(false);
+  const [mounted, setMounted] = useState(false);
+
+  // SSR guard for createPortal
+  useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  // Load current settings when modal opens
+  useEffect(() => {
+    if (isOpen) {
+      const s = getSettings();
+      setApiKey(s.elevenLabsApiKey || "");
+      setVoiceId(s.elevenLabsVoiceId);
+      setModel(s.elevenLabsModel);
+      setShowKey(false);
+    }
+  }, [isOpen]);
+
+  // Escape key
+  useEffect(() => {
+    if (!isOpen) return;
+    const handler = (e: KeyboardEvent) => {
+      if (e.key === "Escape") onClose();
+    };
+    window.addEventListener("keydown", handler);
+    return () => window.removeEventListener("keydown", handler);
+  }, [isOpen, onClose]);
+
+  const handleSave = useCallback(() => {
+    const updates: Partial<BeadsMapSettings> = {
+      elevenLabsApiKey: apiKey.trim() || undefined,
+      elevenLabsVoiceId: voiceId.trim() || "UgBBYS2sOqTuMpoF3BR0",
+      elevenLabsModel: model || "eleven_turbo_v2_5",
+    };
+    saveSettings(updates);
+    onClose();
+  }, [apiKey, voiceId, model, onClose]);
+
+  if (!isOpen || !mounted) return null;
+
+  return createPortal(
+    <div
+      className="fixed inset-0 z-[100] flex items-center justify-center"
+      style={{ backgroundColor: "rgba(0,0,0,0.4)", backdropFilter: "blur(4px)" }}
+      onClick={onClose}
+    >
+      <div
+        className="bg-white rounded-xl shadow-2xl w-[90vw] max-w-md flex flex-col"
+        onClick={(e) => e.stopPropagation()}
+      >
+        {/* Header */}
+        <div className="flex items-center justify-between px-5 py-3.5 border-b border-zinc-100">
+          <h2 className="text-sm font-semibold text-zinc-900">Settings</h2>
+          <button
+            onClick={onClose}
+            className="p-1 text-zinc-400 hover:text-zinc-600 transition-colors"
+          >
+            <svg
+              className="w-4 h-4"
+              fill="none"
+              stroke="currentColor"
+              viewBox="0 0 24 24"
+              strokeWidth={2}
+            >
+              <path
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                d="M6 18L18 6M6 6l12 12"
+              />
+            </svg>
+          </button>
+        </div>
+
+        {/* Body */}
+        <div className="px-5 py-4 space-y-4 overflow-y-auto max-h-[60vh]">
+          {/* Section header */}
+          <h3 className="text-[11px] font-semibold uppercase tracking-widest text-teal-600">
+            Text-to-Speech
+          </h3>
+
+          {/* API Key */}
+          <div>
+            <label className="block text-xs font-medium text-zinc-700 mb-1">
+              ElevenLabs API Key
+            </label>
+            <div className="relative">
+              <input
+                type={showKey ? "text" : "password"}
+                value={apiKey}
+                onChange={(e) => setApiKey(e.target.value)}
+                placeholder="sk_..."
+                className="w-full rounded-lg border border-zinc-200 bg-zinc-50 px-3 py-2 text-sm text-zinc-900 placeholder:text-zinc-400 focus:outline-none focus:ring-2 focus:ring-emerald-500/30 focus:border-emerald-500 pr-10"
+              />
+              <button
+                type="button"
+                onClick={() => setShowKey((v) => !v)}
+                className="absolute right-2 top-1/2 -translate-y-1/2 p-1 text-zinc-400 hover:text-zinc-600 transition-colors"
+                title={showKey ? "Hide key" : "Show key"}
+              >
+                {showKey ? (
+                  <svg
+                    className="w-4 h-4"
+                    fill="none"
+                    viewBox="0 0 24 24"
+                    strokeWidth={1.5}
+                    stroke="currentColor"
+                  >
+                    <path
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      d="M3.98 8.223A10.477 10.477 0 001.934 12C3.226 16.338 7.244 19.5 12 19.5c.993 0 1.953-.138 2.863-.395M6.228 6.228A10.45 10.45 0 0112 4.5c4.756 0 8.773 3.162 10.065 7.498a10.523 10.523 0 01-4.293 5.774M6.228 6.228L3 3m3.228 3.228l3.65 3.65m7.894 7.894L21 21m-3.228-3.228l-3.65-3.65m0 0a3 3 0 10-4.243-4.243m4.242 4.242L9.88 9.88"
+                    />
+                  </svg>
+                ) : (
+                  <svg
+                    className="w-4 h-4"
+                    fill="none"
+                    viewBox="0 0 24 24"
+                    strokeWidth={1.5}
+                    stroke="currentColor"
+                  >
+                    <path
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      d="M2.036 12.322a1.012 1.012 0 010-.639C3.423 7.51 7.36 4.5 12 4.5c4.638 0 8.573 3.007 9.963 7.178.07.207.07.431 0 .639C20.577 16.49 16.64 19.5 12 19.5c-4.638 0-8.573-3.007-9.963-7.178z"
+                    />
+                    <path
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      d="M15 12a3 3 0 11-6 0 3 3 0 016 0z"
+                    />
+                  </svg>
+                )}
+              </button>
+            </div>
+            <p className="mt-1 text-[11px] text-zinc-400">
+              Get your key at{" "}
+              <a
+                href="https://elevenlabs.io/app/settings/api-keys"
+                target="_blank"
+                rel="noopener noreferrer"
+                className="underline underline-offset-2 text-teal-500 hover:text-teal-600"
+              >
+                elevenlabs.io/app/settings
+              </a>
+            </p>
+          </div>
+
+          {/* Voice ID */}
+          <div>
+            <label className="block text-xs font-medium text-zinc-700 mb-1">
+              Voice ID
+            </label>
+            <input
+              type="text"
+              value={voiceId}
+              onChange={(e) => setVoiceId(e.target.value)}
+              placeholder="UgBBYS2sOqTuMpoF3BR0"
+              className="w-full rounded-lg border border-zinc-200 bg-zinc-50 px-3 py-2 text-sm text-zinc-900 placeholder:text-zinc-400 focus:outline-none focus:ring-2 focus:ring-emerald-500/30 focus:border-emerald-500"
+            />
+            <p className="mt-1 text-[11px] text-zinc-400">
+              Default: Mark - Natural Conversations. Find voice IDs in the{" "}
+              <a
+                href="https://elevenlabs.io/app/voice-library"
+                target="_blank"
+                rel="noopener noreferrer"
+                className="underline underline-offset-2 text-teal-500 hover:text-teal-600"
+              >
+                ElevenLabs Voice Library
+              </a>
+              .
+            </p>
+          </div>
+
+          {/* Model */}
+          <div>
+            <label className="block text-xs font-medium text-zinc-700 mb-1">
+              Model
+            </label>
+            <select
+              value={model}
+              onChange={(e) => setModel(e.target.value)}
+              className="w-full rounded-lg border border-zinc-200 bg-zinc-50 px-3 py-2 text-sm text-zinc-900 focus:outline-none focus:ring-2 focus:ring-emerald-500/30 focus:border-emerald-500"
+            >
+              <option value="eleven_turbo_v2_5">
+                Turbo v2.5 (default, fast &amp; cheap)
+              </option>
+              <option value="eleven_flash_v2_5">
+                Flash v2.5 (fastest, cheapest)
+              </option>
+              <option value="eleven_multilingual_v2">
+                Multilingual v2 (highest quality)
+              </option>
+            </select>
+          </div>
+        </div>
+
+        {/* Footer */}
+        <div className="flex items-center justify-end gap-2 px-5 py-3.5 border-t border-zinc-100">
+          <button
+            onClick={onClose}
+            className="px-4 py-2 text-sm font-medium text-zinc-500 hover:text-zinc-700 rounded-lg hover:bg-zinc-50 transition-colors"
+          >
+            Cancel
+          </button>
+          <button
+            onClick={handleSave}
+            className="px-4 py-2 text-sm font-medium text-white rounded-lg bg-emerald-500 hover:bg-emerald-600 transition-colors"
+          >
+            Save
+          </button>
+        </div>
+      </div>
+    </div>,
+    document.body
+  );
+}

package/components/TutorialOverlay.tsx

@@ -27,7 +27,7 @@ export const TUTORIAL_STEPS: TutorialStep[] = [
     target: "view-controls",
     title: "View Controls",
     description:
-      "Collapse or expand epic groups, toggle cluster label overlays, and control auto-fit. When auto-fit is on (green), the camera re-centers after every update. Turn it off to stay focused on a specific area while data streams in.",
+      "Collapse or expand epic groups, toggle cluster label overlays, control auto-fit, and toggle the pulse animation. When auto-fit is on (green), the camera re-centers after every update. Pulse highlights the most recently active node with emerald ripples.",
   },
   {
     target: "legend",
@@ -51,14 +51,14 @@ export const TUTORIAL_STEPS: TutorialStep[] = [
     target: "graph",
     title: "Interacting with Nodes",
     description:
-      "Click a node to see details. Hover for a quick tooltip. Right-click for actions like viewing descriptions, commenting, claiming tasks, or collapsing epics.",
+      "Click a node to see details. Hover for a quick tooltip. Right-click for actions like viewing descriptions, commenting, claiming tasks, collapsing epics, or focusing on an epic to isolate its subgraph.",
     padding: 0,
   },
   {
     target: "nav-pills",
     title: "Navigation Bar",
     description:
-      "Replay steps through your project\u2019s history. Comments shows conversations. Activity is a real-time feed. And Learn brings you right back here.",
+      "Replay steps through your project\u2019s history. Comments shows conversations across your beads. Activity is a real-time feed filtered to only your local issues. And Learn brings you right back here.",
   },
 ];
 

package/lib/settings.ts

@@ -0,0 +1,42 @@
+// ============================================================================
+// User settings — persisted in localStorage
+// ============================================================================
+
+export interface BeadsMapSettings {
+  elevenLabsApiKey?: string;
+  elevenLabsVoiceId: string;
+  elevenLabsModel: string;
+}
+
+const STORAGE_KEY = "beads-map-settings";
+
+const DEFAULTS: BeadsMapSettings = {
+  elevenLabsVoiceId: "UgBBYS2sOqTuMpoF3BR0", // Mark - Natural Conversations
+  elevenLabsModel: "eleven_turbo_v2_5",
+};
+
+/** Read settings from localStorage, merged with defaults */
+export function getSettings(): BeadsMapSettings {
+  if (typeof window === "undefined") return { ...DEFAULTS };
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    if (!raw) return { ...DEFAULTS };
+    return { ...DEFAULTS, ...JSON.parse(raw) };
+  } catch {
+    return { ...DEFAULTS };
+  }
+}
+
+/** Write settings to localStorage */
+export function saveSettings(settings: Partial<BeadsMapSettings>): void {
+  if (typeof window === "undefined") return;
+  const current = getSettings();
+  const merged = { ...current, ...settings };
+  localStorage.setItem(STORAGE_KEY, JSON.stringify(merged));
+}
+
+/** Check if ElevenLabs API key is configured */
+export function hasApiKey(): boolean {
+  const s = getSettings();
+  return !!s.elevenLabsApiKey && s.elevenLabsApiKey.trim().length > 0;
+}

package/lib/tts.ts

@@ -0,0 +1,397 @@
+// ============================================================================
+// ElevenLabs Text-to-Speech helper
+//
+// Uses the /with-timestamps API endpoint to get character-level alignment data
+// alongside audio. This enables zero-API-call text-selection playback by
+// seeking within cached full-text audio.
+// ============================================================================
+
+import { getSettings } from "./settings";
+
+// --- Markdown stripping ---------------------------------------------------
+
+/** Strip Markdown syntax to produce clean plain text for TTS */
+export function stripMarkdown(md: string): string {
+  return (
+    md
+      // Remove code blocks (triple backtick)
+      .replace(/```[\s\S]*?```/g, "")
+      // Remove inline code
+      .replace(/`([^`]+)`/g, "$1")
+      // Remove images ![alt](url)
+      .replace(/!\[([^\]]*)\]\([^)]+\)/g, "$1")
+      // Convert links [text](url) to just text
+      .replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+      // Remove headers (# ## ### etc)
+      .replace(/^#{1,6}\s+/gm, "")
+      // Remove bold/italic markers
+      .replace(/(\*{1,3}|_{1,3})(.*?)\1/g, "$2")
+      // Remove strikethrough
+      .replace(/~~(.*?)~~/g, "$1")
+      // Remove horizontal rules
+      .replace(/^[-*_]{3,}\s*$/gm, "")
+      // Remove blockquotes
+      .replace(/^>\s+/gm, "")
+      // Remove list markers
+      .replace(/^[\s]*[-*+]\s+/gm, "")
+      .replace(/^[\s]*\d+\.\s+/gm, "")
+      // Remove HTML tags
+      .replace(/<[^>]+>/g, "")
+      // Collapse multiple newlines
+      .replace(/\n{3,}/g, "\n\n")
+      .trim()
+  );
+}
+
+// --- Types ----------------------------------------------------------------
+
+/** Character-level alignment from ElevenLabs with-timestamps API */
+export interface CharacterAlignment {
+  characters: string[];
+  characterStartTimesSeconds: number[];
+  characterEndTimesSeconds: number[];
+}
+
+/** Cached audio entry with alignment data for seek-based selection playback */
+export interface CachedAudio {
+  blob: Blob;
+  alignment: CharacterAlignment;
+  strippedText: string; // exact text sent to ElevenLabs
+}
+
+export type TtsState = "idle" | "loading" | "playing" | "paused" | "error";
+
+// --- Audio cache (session-scoped, LRU, max 10 entries) --------------------
+
+const audioCache = new Map<string, CachedAudio>();
+const CACHE_MAX = 10;
+
+function cacheKey(voiceId: string, model: string, text: string): string {
+  return `${voiceId}:${model}:${text}`;
+}
+
+function cacheGet(key: string): CachedAudio | undefined {
+  const entry = audioCache.get(key);
+  if (entry) {
+    // LRU: move to end by delete + re-insert
+    audioCache.delete(key);
+    audioCache.set(key, entry);
+  }
+  return entry;
+}
+
+function cachePut(key: string, entry: CachedAudio): void {
+  if (audioCache.size >= CACHE_MAX) {
+    // Evict oldest (first key in Map iteration order)
+    const oldest = audioCache.keys().next().value;
+    if (oldest) audioCache.delete(oldest);
+  }
+  audioCache.set(key, entry);
+}
+
+// --- Substring alignment lookup -------------------------------------------
+
+/** Normalize whitespace for fuzzy substring matching */
+function normalizeWhitespace(s: string): string {
+  return s.replace(/\s+/g, " ").trim().toLowerCase();
+}
+
+/**
+ * Check if any cached audio contains the given text as a substring.
+ * If found, returns the blob and start/end times for seeking.
+ * This enables zero-API-call playback for text selections.
+ */
+export function findCachedAlignmentForText(selectedText: string): {
+  blob: Blob;
+  startTime: number;
+  endTime: number;
+} | null {
+  const normalizedSelection = normalizeWhitespace(selectedText);
+  if (!normalizedSelection) return null;
+
+  for (const entry of audioCache.values()) {
+    const normalizedFull = normalizeWhitespace(entry.strippedText);
+    const idx = normalizedFull.indexOf(normalizedSelection);
+    if (idx === -1) continue;
+
+    // Build a mapping from each char in strippedText to its position in the
+    // normalized (lowercased, collapsed-whitespace) version.
+    const { strippedText, alignment } = entry;
+    const charToNormPos: number[] = [];
+    let np = 0;
+    let prevWasSpace = false;
+
+    for (let i = 0; i < strippedText.length; i++) {
+      const isSpace = /\s/.test(strippedText[i]);
+      if (isSpace) {
+        if (!prevWasSpace && np > 0) {
+          charToNormPos.push(np);
+          np++;
+        } else {
+          charToNormPos.push(-1); // collapsed away
+        }
+        prevWasSpace = true;
+      } else {
+        charToNormPos.push(np);
+        np++;
+        prevWasSpace = false;
+      }
+    }
+
+    // Find the strippedText char indices that map to the normalized range
+    const selEnd = idx + normalizedSelection.length - 1;
+    let startCharIdx = -1;
+    let endCharIdx = -1;
+
+    for (let i = 0; i < charToNormPos.length; i++) {
+      if (charToNormPos[i] === idx && startCharIdx === -1) {
+        startCharIdx = i;
+      }
+      if (charToNormPos[i] === selEnd) {
+        endCharIdx = i;
+      }
+    }
+
+    if (startCharIdx === -1 || endCharIdx === -1) continue;
+
+    // Clamp to alignment array bounds
+    const alignLen = alignment.characterStartTimesSeconds.length;
+    if (alignLen === 0) continue;
+
+    const clampedStart = Math.min(startCharIdx, alignLen - 1);
+    const clampedEnd = Math.min(endCharIdx, alignment.characterEndTimesSeconds.length - 1);
+
+    if (clampedStart < 0 || clampedEnd < 0) continue;
+
+    return {
+      blob: entry.blob,
+      startTime: alignment.characterStartTimesSeconds[clampedStart],
+      endTime: alignment.characterEndTimesSeconds[clampedEnd],
+    };
+  }
+
+  return null;
+}
+
+// --- Audio playback state -------------------------------------------------
+
+/** Current audio element for stop control */
+let currentAudio: HTMLAudioElement | null = null;
+let currentBlobUrl: string | null = null;
+
+/** When playing a selection from cached audio, auto-stop at this time */
+let selectionEndTime: number | null = null;
+
+// --- Playback controls ----------------------------------------------------
+
+/** Set playback speed on the current audio element */
+export function setTtsPlaybackRate(rate: number): void {
+  if (currentAudio) {
+    currentAudio.playbackRate = rate;
+  }
+}
+
+/** Pause TTS audio without destroying — preserves position for resume */
+export function pauseTts(): void {
+  if (currentAudio && !currentAudio.paused) {
+    currentAudio.pause();
+  }
+}
+
+/** Resume paused TTS audio from where it left off */
+export function resumeTts(): void {
+  if (currentAudio && currentAudio.paused && currentAudio.currentTime > 0) {
+    currentAudio.play();
+  }
+}
+
+/** Stop any currently playing TTS audio */
+export function stopTts(): void {
+  if (currentAudio) {
+    currentAudio.pause();
+    currentAudio.currentTime = 0;
+    currentAudio.onended = null;
+    currentAudio.onerror = null;
+    currentAudio.ontimeupdate = null;
+    currentAudio = null;
+  }
+  if (currentBlobUrl) {
+    URL.revokeObjectURL(currentBlobUrl);
+    currentBlobUrl = null;
+  }
+  selectionEndTime = null;
+}
+
+// --- Internal: create Audio from blob and play ----------------------------
+
+/** Internal: create Audio from blob and play it */
+function playBlobAsAudio(
+  blob: Blob,
+  onStateChange: (state: TtsState, error?: string) => void,
+): void {
+  // Full-text playback: no auto-stop
+  selectionEndTime = null;
+
+  const blobUrl = URL.createObjectURL(blob);
+  currentBlobUrl = blobUrl;
+
+  const audio = new Audio(blobUrl);
+  currentAudio = audio;
+
+  onStateChange("playing");
+
+  audio.onended = () => {
+    stopTts();
+    onStateChange("idle");
+  };
+
+  audio.onerror = () => {
+    stopTts();
+    onStateChange("error", "Audio playback failed");
+  };
+
+  audio.play();
+}
+
+// --- Main TTS functions ---------------------------------------------------
+
+/**
+ * Call ElevenLabs TTS API (with-timestamps) and play the result.
+ * Uses cache to avoid redundant API calls.
+ *
+ * @param text - Plain text to speak (already stripped of Markdown)
+ * @param onStateChange - Callback for state transitions
+ */
+export async function speakWithElevenLabs(
+  text: string,
+  onStateChange: (state: TtsState, error?: string) => void,
+): Promise<void> {
+  // Stop any existing playback
+  stopTts();
+
+  const settings = getSettings();
+  if (!settings.elevenLabsApiKey) {
+    onStateChange("error", "No API key configured");
+    return;
+  }
+
+  const voiceId = settings.elevenLabsVoiceId;
+  const key = cacheKey(voiceId, settings.elevenLabsModel, text);
+
+  // Check cache first — zero API call on hit
+  const cached = cacheGet(key);
+  if (cached) {
+    playBlobAsAudio(cached.blob, onStateChange);
+    return;
+  }
+
+  onStateChange("loading");
+
+  try {
+    const res = await fetch(
+      `https://api.elevenlabs.io/v1/text-to-speech/${voiceId}/with-timestamps?output_format=mp3_44100_128`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "xi-api-key": settings.elevenLabsApiKey,
+        },
+        body: JSON.stringify({
+          text,
+          model_id: settings.elevenLabsModel,
+        }),
+      },
+    );
+
+    if (!res.ok) {
+      const errorText = await res.text().catch(() => res.statusText);
+      throw new Error(`ElevenLabs API error (${res.status}): ${errorText}`);
+    }
+
+    const json = await res.json();
+    const { audio_base64, alignment } = json;
+
+    // Decode base64 to Blob
+    const binary = atob(audio_base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+    const blob = new Blob([bytes], { type: "audio/mpeg" });
+
+    // Store in cache with alignment data
+    const cachedEntry: CachedAudio = {
+      blob,
+      alignment: {
+        characters: alignment.characters,
+        characterStartTimesSeconds: alignment.character_start_times_seconds,
+        characterEndTimesSeconds: alignment.character_end_times_seconds,
+      },
+      strippedText: text,
+    };
+    cachePut(key, cachedEntry);
+
+    playBlobAsAudio(blob, onStateChange);
+  } catch (err) {
+    stopTts();
+    const message = err instanceof Error ? err.message : "TTS failed";
+    onStateChange("error", message);
+  }
+}
+
+/**
+ * Play a text selection, leveraging cached audio when possible.
+ *
+ * Credit-saving flow:
+ * 1. Check if any cached full-text audio contains this selection as a substring
+ * 2. If yes: create Audio from cached blob, seek to start time, auto-stop at end time
+ * 3. If no: fall back to speakWithElevenLabs() (makes API call, result gets cached)
+ *
+ * @param selectedText - The raw text the user selected (from window.getSelection().toString())
+ * @param onStateChange - State change callback (same as speakWithElevenLabs)
+ */
+export async function speakSelection(
+  selectedText: string,
+  onStateChange: (state: TtsState, error?: string) => void,
+): Promise<void> {
+  // Stop any existing playback first
+  stopTts();
+
+  // Try zero-API-call path: seek within cached full-text audio
+  const cached = findCachedAlignmentForText(selectedText);
+  if (cached) {
+    const { blob, startTime, endTime } = cached;
+    const blobUrl = URL.createObjectURL(blob);
+    currentBlobUrl = blobUrl;
+
+    const audio = new Audio(blobUrl);
+    currentAudio = audio;
+    selectionEndTime = endTime;
+
+    audio.onended = () => {
+      stopTts();
+      onStateChange("idle");
+    };
+
+    audio.onerror = () => {
+      stopTts();
+      onStateChange("error", "Audio playback failed");
+    };
+
+    // Auto-stop at selection end time
+    audio.ontimeupdate = () => {
+      if (selectionEndTime !== null && audio.currentTime >= selectionEndTime) {
+        stopTts();
+        onStateChange("idle");
+      }
+    };
+
+    // Seek to selection start, then play
+    audio.currentTime = startTime;
+    onStateChange("playing");
+    await audio.play();
+    return;
+  }
+
+  // Cache miss: fall back to full API call for just the selected text
+  // This result also gets cached (with its own alignment data) for future replays
+  await speakWithElevenLabs(selectedText, onStateChange);
+}