@ai-matrx/media 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @ai-matrx/media
 
+## 0.15.0 — THE one speech engine (`/speech`) + ReadAloudButton compact size
+
+- New `@ai-matrx/media/speech`: `speak()`, the app-wide playback queue (`enqueuePlayback`,
+  `pausePlayback`, `resumePlayback`, `skipPlayback`, `playPlaybackItem`, `removePlaybackItem`,
+  `clearPlayback`, `subscribePlayback`, …), the playback lock (`claimPlayback` / `releasePlayback`),
+  the Cartesia streaming lane (`connectCartesiaTts`, `cartesiaAdapter`, `ProviderSessionError`),
+  `SinkAwarePlayer` + output-device routing, and the iOS/WebKit unlock (`primeAudioOutput`,
+  `installAudioUnlockListeners`) — moved from matrx-frontend's audio system, which is the reference.
+  A host wires it once: `configureSpeech({ getCartesiaToken, resolveVoiceSettings,
+  reportProviderFailure?, notifyError?, beforeStart?, describeStartRefusal?, onEngage?, adapters?,
+  defaultEngine?, completeRequest?, resolvePronunciations?, invalidateCartesiaToken? })`.
+- `@ai-matrx/media/react`: `useSpeech`, `useReadAloud(text)` (the read-aloud button's whole wiring:
+  `status`, `error`, `onPress`), `usePlaybackSnapshot`, `readAloudStatusOf` — over the same queue
+  instance (`/react` imports `/speech`, never a bundled copy).
+- New dependency `@cartesia/cartesia-js` ^4.2.0.
+- Consumer action: delete the app's own queue / lock / Cartesia connection / player / unlock and
+  import them from `/speech`; call `configureSpeech` once at start-up.
+
+- `ReadAloudButton` `size?: "default" | "compact"` (`ReadAloudButtonSize` exported): "compact" is the
+  message-footer cell (32px box, 28px pill — the tap system's group geometry) instead of the 38px
+  default box. Geometry only; it wins over `variant`.
+- Consumer action: a message footer that drew the old 24px speaker passes `size="compact"`.
+
 ## 0.14.0 — Read-aloud lives here (speech text, languages, button, language picker)
 
 - `@ai-matrx/media/voices`: `parseMarkdownToText` (+ `normalizeSpeechAbbreviations`,

package/dist/react.cjs

@@ -70,7 +70,11 @@ __export(react_exports, {
   VolumeXIcon: () => VolumeXIcon,
   XIcon: () => XIcon,
   cn: () => cn,
-  useMediaDropzone: () => useMediaDropzone
+  readAloudStatusOf: () => readAloudStatusOf,
+  useMediaDropzone: () => useMediaDropzone,
+  usePlaybackSnapshot: () => usePlaybackSnapshot,
+  useReadAloud: () => useReadAloud,
+  useSpeech: () => useSpeech
 });
 module.exports = __toCommonJS(react_exports);
 
@@ -2542,10 +2546,12 @@ function ReadAloudButton({
   onPress,
   error,
   disabled = false,
-  variant,
+  variant: requestedVariant,
+  size = "default",
   className,
   label = "Read aloud"
 }) {
+  const variant = size === "compact" ? "group" : requestedVariant;
   if (status === "playing") {
     return /* @__PURE__ */ (0, import_jsx_runtime9.jsx)(import_buttons.PauseTapButton, { variant, onClick: onPress, disabled, ariaLabel: "Pause", className });
   }
@@ -2574,10 +2580,84 @@ function ReadAloudButton({
   );
 }
 
+// src/react/use-speech.ts
+var import_react17 = require("react");
+var import_speech = require("@ai-matrx/media/speech");
+var cached = (0, import_speech.getPlaybackSnapshot)();
+function subscribe(onChange) {
+  return (0, import_speech.subscribePlayback)((snapshot) => {
+    cached = snapshot;
+    onChange();
+  });
+}
+var read = () => cached;
+function usePlaybackSnapshot() {
+  return (0, import_react17.useSyncExternalStore)(subscribe, read, read);
+}
+function useSpeech({ adoptText, ...request } = {}) {
+  const { items, currentId } = usePlaybackSnapshot();
+  const [itemId, setItemId] = (0, import_react17.useState)(null);
+  const adoptedId = !itemId && adoptText && currentId ? items.find(
+    (i) => i.id === currentId && i.text === adoptText && (i.status === "playing" || i.status === "paused" || i.status === "loading")
+  )?.id ?? null : null;
+  const effectiveId = itemId ?? adoptedId;
+  const { engine, voice, purpose, processMarkdown = true, label, dictionarySurfaceKey, language, speed } = request;
+  const speak = (0, import_react17.useCallback)(
+    (text) => {
+      const { id } = (0, import_speech.speak)({
+        text,
+        engine,
+        voice,
+        purpose,
+        processMarkdown,
+        label,
+        dictionarySurfaceKey,
+        language,
+        speed
+      });
+      setItemId(id);
+      return id;
+    },
+    [engine, voice, purpose, processMarkdown, label, dictionarySurfaceKey, language, speed]
+  );
+  const item = effectiveId ? items.find((i) => i.id === effectiveId) : void 0;
+  const status = item?.status ?? null;
+  return {
+    speak,
+    status,
+    error: item?.error ?? null,
+    itemId,
+    isMine: effectiveId !== null && effectiveId === currentId,
+    pause: import_speech.pausePlayback,
+    resume: import_speech.resumePlayback,
+    skip: import_speech.skipPlayback,
+    remove: import_speech.removePlaybackItem,
+    playItem: import_speech.playPlaybackItem
+  };
+}
+function readAloudStatusOf(status) {
+  if (status === "playing") return "playing";
+  if (status === "paused") return "paused";
+  if (status === "loading" || status === "queued") return "loading";
+  if (status === "error") return "error";
+  return "idle";
+}
+function useReadAloud(text, options = {}) {
+  const { speak, status, error, pause, resume } = useSpeech({ adoptText: text, ...options });
+  const state = readAloudStatusOf(status);
+  const onPress = (0, import_react17.useCallback)(() => {
+    if (state === "loading") return;
+    if (state === "playing") void pause();
+    else if (state === "paused") void resume();
+    else if (text.trim()) speak(text);
+  }, [state, text, speak, pause, resume]);
+  return { status: state, error, onPress, speak };
+}
+
 // src/react/read-aloud-language-picker.tsx
 var import_design_system = require("@ai-matrx/design-system");
 var import_lucide_react = require("lucide-react");
-var import_react17 = require("react");
+var import_react18 = require("react");
 
 // src/voices/read-aloud-languages.ts
 var READ_ALOUD_LANGUAGES = [
@@ -2605,7 +2685,7 @@ function readAloudLanguage(code) {
 // src/react/read-aloud-language-picker.tsx
 var import_jsx_runtime10 = require("react/jsx-runtime");
 function ReadAloudLanguagePicker({ value, onChange, className }) {
-  const [open, setOpen] = (0, import_react17.useState)(false);
+  const [open, setOpen] = (0, import_react18.useState)(false);
   const selected = readAloudLanguage(value);
   return /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)(import_design_system.Popover, { open, onOpenChange: setOpen, children: [
     /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(import_design_system.PopoverTrigger, { asChild: true, children: /* @__PURE__ */ (0, import_jsx_runtime10.jsx)(