@runtypelabs/persona 3.34.1 → 3.36.0

package/src/voice/read-aloud-controller.test.ts

@@ -0,0 +1,143 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { ReadAloudController } from "./read-aloud-controller";
+import type { ReadAloudState, SpeechCallbacks, SpeechEngine, SpeechRequest } from "../types";
+
+class FakeEngine implements SpeechEngine {
+  readonly id = "fake";
+  readonly supportsPause: boolean;
+  speakCalls: SpeechRequest[] = [];
+  lastCallbacks: SpeechCallbacks | null = null;
+  pauseCount = 0;
+  resumeCount = 0;
+  stopCount = 0;
+
+  constructor(supportsPause = true) {
+    this.supportsPause = supportsPause;
+  }
+
+  speak(request: SpeechRequest, callbacks: SpeechCallbacks): void {
+    this.speakCalls.push(request);
+    this.lastCallbacks = callbacks;
+  }
+  pause(): void {
+    this.pauseCount++;
+  }
+  resume(): void {
+    this.resumeCount++;
+  }
+  stop(): void {
+    this.stopCount++;
+  }
+}
+
+const tick = () => new Promise((resolve) => setTimeout(resolve, 0));
+const req = (text: string): SpeechRequest => ({ text });
+
+describe("ReadAloudController", () => {
+  let engine: FakeEngine;
+  let controller: ReadAloudController;
+  let states: Array<[string | null, ReadAloudState]>;
+
+  beforeEach(() => {
+    engine = new FakeEngine(true);
+    controller = new ReadAloudController(() => engine);
+    states = [];
+    controller.onChange((id, state) => states.push([id, state]));
+  });
+
+  it("goes idle → loading → playing on first toggle", async () => {
+    controller.toggle("a", req("hello"));
+    // loading is set synchronously, before the engine resolves
+    expect(controller.stateFor("a")).toBe("loading");
+    await tick();
+    expect(engine.speakCalls).toHaveLength(1);
+    engine.lastCallbacks!.onStart!();
+    expect(controller.stateFor("a")).toBe("playing");
+    expect(states.map((s) => s[1])).toEqual(["loading", "playing"]);
+  });
+
+  it("pauses then resumes a playing message", async () => {
+    controller.toggle("a", req("hello"));
+    await tick();
+    engine.lastCallbacks!.onStart!();
+
+    controller.toggle("a", req("hello")); // playing → pause
+    expect(engine.pauseCount).toBe(1);
+    expect(controller.stateFor("a")).toBe("paused");
+
+    controller.toggle("a", req("hello")); // paused → resume
+    expect(engine.resumeCount).toBe(1);
+    expect(controller.stateFor("a")).toBe("playing");
+  });
+
+  it("stops a playing message (no resume) when the engine can't pause", async () => {
+    engine = new FakeEngine(false);
+    controller = new ReadAloudController(() => engine);
+    controller.toggle("a", req("hello"));
+    await tick();
+    engine.lastCallbacks!.onStart!();
+
+    controller.toggle("a", req("hello")); // playing → stop (no pause support)
+    expect(engine.pauseCount).toBe(0);
+    expect(engine.stopCount).toBeGreaterThanOrEqual(1);
+    expect(controller.stateFor("a")).toBe("idle");
+  });
+
+  it("stops the previous message when a different one starts", async () => {
+    controller.toggle("a", req("first"));
+    await tick();
+    engine.lastCallbacks!.onStart!();
+    expect(controller.stateFor("a")).toBe("playing");
+
+    controller.toggle("b", req("second")); // switch
+    await tick();
+    expect(engine.stopCount).toBeGreaterThanOrEqual(1);
+    engine.lastCallbacks!.onStart!();
+    expect(controller.stateFor("a")).toBe("idle");
+    expect(controller.stateFor("b")).toBe("playing");
+  });
+
+  it("returns to idle on natural end", async () => {
+    controller.toggle("a", req("hello"));
+    await tick();
+    engine.lastCallbacks!.onStart!();
+    engine.lastCallbacks!.onEnd!();
+    expect(controller.stateFor("a")).toBe("idle");
+    expect(controller.activeMessageId()).toBeNull();
+  });
+
+  it("ignores a stale callback from a superseded request", async () => {
+    controller.toggle("a", req("first"));
+    await tick();
+    const staleCallbacks = engine.lastCallbacks!;
+    staleCallbacks.onStart!();
+
+    controller.toggle("b", req("second")); // supersedes "a"
+    await tick();
+    engine.lastCallbacks!.onStart!();
+    expect(controller.stateFor("b")).toBe("playing");
+
+    // Late onEnd from the superseded "a" request must not clobber "b".
+    staleCallbacks.onEnd!();
+    expect(controller.stateFor("b")).toBe("playing");
+  });
+
+  it("stop() resets to idle and stops the engine", async () => {
+    controller.toggle("a", req("hello"));
+    await tick();
+    engine.lastCallbacks!.onStart!();
+    controller.stop();
+    expect(controller.stateFor("a")).toBe("idle");
+    expect(engine.stopCount).toBeGreaterThanOrEqual(1);
+  });
+
+  it("reports a null engine resolution as idle", async () => {
+    const nullController = new ReadAloudController(() => null);
+    const seen: ReadAloudState[] = [];
+    nullController.onChange((_id, state) => seen.push(state));
+    nullController.toggle("a", req("hello"));
+    await tick();
+    expect(nullController.stateFor("a")).toBe("idle");
+    expect(seen).toEqual(["loading", "idle"]);
+  });
+});

package/src/voice/read-aloud-controller.ts

@@ -0,0 +1,136 @@
+// Read-Aloud Controller
+//
+// Engine-agnostic orchestrator for the per-message "Read aloud" action and the
+// auto-speak path. Owns the three things the UI shouldn't: which message is
+// currently active, its playback state, and the single speech engine instance.
+//
+// The button drives a single `toggle(id, request)`; listeners are notified on
+// every state change so the UI can reflect play / pause / resume. The engine is
+// resolved lazily (on first playback, inside the user gesture) via the
+// `resolveEngine` factory, so swapping the browser engine for a hosted one
+// (Runtype or custom) is a config change — this class is unchanged.
+
+import type { ReadAloudState, SpeechEngine, SpeechRequest } from "../types";
+
+export type ReadAloudListener = (
+  activeId: string | null,
+  state: ReadAloudState
+) => void;
+
+export class ReadAloudController {
+  private engine: SpeechEngine | null = null;
+  private activeId: string | null = null;
+  private state: ReadAloudState = "idle";
+  private listeners = new Set<ReadAloudListener>();
+  // Bumped on every play/stop so a late async engine creation or a stale
+  // utterance callback from a superseded request can't mutate current state.
+  private generation = 0;
+
+  constructor(
+    private resolveEngine: () => SpeechEngine | Promise<SpeechEngine> | null
+  ) {}
+
+  /** Whether the active engine supports pause/resume (vs. stop-only). */
+  get supportsPause(): boolean {
+    return this.engine?.supportsPause ?? true;
+  }
+
+  /** Playback state for a message id (`idle` unless it's the active message). */
+  stateFor(id: string): ReadAloudState {
+    return this.activeId === id ? this.state : "idle";
+  }
+
+  /** The message currently being read aloud, if any. */
+  activeMessageId(): string | null {
+    return this.activeId;
+  }
+
+  /** Subscribe to state changes. Returns an unsubscribe function. */
+  onChange(listener: ReadAloudListener): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  /**
+   * Primary entry point for the button: cycle this message through
+   * play → pause → resume (or play → stop when the engine can't pause), and
+   * start fresh when a different message is requested.
+   */
+  toggle(id: string, request: SpeechRequest): void {
+    if (this.activeId === id) {
+      if (this.state === "playing") {
+        if (this.engine?.supportsPause) {
+          this.engine.pause();
+          this.set(id, "paused");
+        } else {
+          this.stop();
+        }
+        return;
+      }
+      if (this.state === "paused") {
+        this.engine?.resume();
+        this.set(id, "playing");
+        return;
+      }
+      if (this.state === "loading") {
+        this.stop();
+        return;
+      }
+    }
+    void this.play(id, request);
+  }
+
+  /** Start (or restart) playback for a message, stopping any current playback. */
+  async play(id: string, request: SpeechRequest): Promise<void> {
+    const generation = ++this.generation;
+    this.engine?.stop();
+    this.set(id, "loading");
+
+    try {
+      if (!this.engine) {
+        const resolved = await this.resolveEngine();
+        if (generation !== this.generation) return; // superseded mid-resolve
+        if (!resolved) {
+          this.set(null, "idle");
+          return;
+        }
+        this.engine = resolved;
+      }
+
+      this.engine.speak(request, {
+        onStart: () => {
+          if (generation === this.generation) this.set(id, "playing");
+        },
+        onEnd: () => {
+          if (generation === this.generation) this.set(null, "idle");
+        },
+        onError: () => {
+          if (generation === this.generation) this.set(null, "idle");
+        },
+      });
+    } catch {
+      if (generation === this.generation) this.set(null, "idle");
+    }
+  }
+
+  /** Stop playback and return to idle. */
+  stop(): void {
+    this.generation++;
+    this.engine?.stop();
+    this.set(null, "idle");
+  }
+
+  /** Drop the controller and its engine (called on widget teardown). */
+  destroy(): void {
+    this.stop();
+    this.engine?.destroy?.();
+    this.engine = null;
+    this.listeners.clear();
+  }
+
+  private set(id: string | null, state: ReadAloudState): void {
+    this.activeId = state === "idle" ? null : id;
+    this.state = state;
+    for (const listener of this.listeners) listener(this.activeId, this.state);
+  }
+}

package/src/voice/runtype-speech-engine.test.ts

@@ -0,0 +1,280 @@
+// Tests for the Runtype hosted TTS engine and the browser-fallback wrapper.
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import type {
+  PcmStreamPlayer,
+  SpeechCallbacks,
+  SpeechEngine,
+  SpeechRequest,
+} from "../types";
+import {
+  RuntypeSpeechEngine,
+  type RuntypeSpeechEngineOptions,
+} from "./runtype-speech-engine";
+import { FallbackSpeechEngine } from "./fallback-speech-engine";
+
+/**
+ * A fake {@link PcmStreamPlayer} whose started/finished callbacks the test can
+ * fire. Injected via `createPlaybackEngine` so the engine never touches a real
+ * AudioContext (and so the test no longer mocks the worklet module — the engine
+ * defaults to the in-bundle AudioPlaybackManager, which we substitute here).
+ */
+function makeFakePlayer() {
+  let startedCbs: Array<() => void> = [];
+  let finishedCbs: Array<() => void> = [];
+  return {
+    enqueue: vi.fn(),
+    markStreamEnd: vi.fn(),
+    flush: vi.fn(() => {
+      startedCbs = [];
+      finishedCbs = [];
+    }),
+    resume: vi.fn(),
+    pause: vi.fn(),
+    destroy: vi.fn(),
+    onStarted: vi.fn((cb: () => void) => startedCbs.push(cb)),
+    onFinished: vi.fn((cb: () => void) => finishedCbs.push(cb)),
+    fireStarted: () => startedCbs.slice().forEach((c) => c()),
+    fireFinished: () => finishedCbs.slice().forEach((c) => c()),
+  };
+}
+
+/** Yield to the macrotask queue so the engine's async read loop fully drains. */
+const settle = () => new Promise((r) => setTimeout(r, 0));
+
+/** A fetch Response stub that streams the given chunks then ends. */
+function streamingResponse(chunks: Uint8Array[]) {
+  let i = 0;
+  return {
+    ok: true,
+    status: 200,
+    body: {
+      getReader: () => ({
+        read: async () =>
+          i < chunks.length
+            ? { done: false, value: chunks[i++] }
+            : { done: true, value: undefined },
+        cancel: async () => {},
+      }),
+    },
+  };
+}
+
+describe("RuntypeSpeechEngine", () => {
+  let fetchMock: ReturnType<typeof vi.fn>;
+  let player: ReturnType<typeof makeFakePlayer>;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    fetchMock = vi.fn();
+    (globalThis as unknown as { fetch: unknown }).fetch = fetchMock;
+    player = makeFakePlayer();
+  });
+
+  /** Build an engine whose playback is the injected fake (no AudioContext). */
+  const makeEngine = (opts: Partial<RuntypeSpeechEngineOptions> = {}) =>
+    new RuntypeSpeechEngine({
+      host: "https://api.runtype.com",
+      agentId: "agent_123",
+      clientToken: "ct_live_abc",
+      createPlaybackEngine: () => player as unknown as PcmStreamPlayer,
+      ...opts,
+    });
+
+  afterEach(() => {
+    delete (globalThis as unknown as { fetch?: unknown }).fetch;
+  });
+
+  it("POSTs to /v1/agents/:id/speak with bearer auth and pcm body", async () => {
+    fetchMock.mockResolvedValue(streamingResponse([new Uint8Array([1, 2, 3, 4])]));
+    const engine = makeEngine({ host: "https://api.runtype.com/" });
+
+    engine.speak({ text: "hello there" }, {});
+    await settle();
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchMock.mock.calls[0];
+    // Trailing slash on host must not double up.
+    expect(url).toBe("https://api.runtype.com/v1/agents/agent_123/speak");
+    expect(init.method).toBe("POST");
+    expect(init.headers.Authorization).toBe("Bearer ct_live_abc");
+    expect(JSON.parse(init.body)).toEqual({
+      text: "hello there",
+      voice: undefined,
+      format: "pcm",
+    });
+  });
+
+  it("streams chunks into the player and marks stream end", async () => {
+    const a = new Uint8Array([1, 2]);
+    const b = new Uint8Array([3, 4]);
+    fetchMock.mockResolvedValue(streamingResponse([a, b]));
+    const engine = makeEngine();
+
+    engine.speak({ text: "hi" }, {});
+    await settle();
+
+    expect(player.enqueue).toHaveBeenCalledTimes(2);
+    expect(player.enqueue).toHaveBeenNthCalledWith(1, a);
+    expect(player.enqueue).toHaveBeenNthCalledWith(2, b);
+    expect(player.markStreamEnd).toHaveBeenCalledTimes(1);
+  });
+
+  it("drives onStart/onEnd from the player, not chunk arrival", async () => {
+    fetchMock.mockResolvedValue(streamingResponse([new Uint8Array([1])]));
+    const onStart = vi.fn();
+    const onEnd = vi.fn();
+    const engine = makeEngine();
+
+    engine.speak({ text: "hi" }, { onStart, onEnd });
+    await settle();
+
+    expect(onStart).not.toHaveBeenCalled();
+    player.fireStarted();
+    expect(onStart).toHaveBeenCalledTimes(1);
+    expect(onEnd).not.toHaveBeenCalled();
+    player.fireFinished();
+    expect(onEnd).toHaveBeenCalledTimes(1);
+  });
+
+  it("sends the request voice when provided, else the engine default", async () => {
+    fetchMock.mockResolvedValue(streamingResponse([]));
+    const engine = makeEngine({ voice: "default-voice" });
+
+    engine.speak({ text: "x", voice: "request-voice" }, {});
+    await settle();
+    expect(JSON.parse(fetchMock.mock.calls[0][1].body).voice).toBe("request-voice");
+
+    engine.speak({ text: "y" }, {});
+    await settle();
+    expect(JSON.parse(fetchMock.mock.calls[1][1].body).voice).toBe("default-voice");
+  });
+
+  it("reports a descriptive error on a non-OK response", async () => {
+    fetchMock.mockResolvedValue({
+      ok: false,
+      status: 401,
+      body: null,
+      json: async () => ({ error: "Invalid or expired client token." }),
+    });
+    const onError = vi.fn();
+    const optsOnError = vi.fn();
+    const engine = makeEngine({ clientToken: "bad", onError: optsOnError });
+
+    engine.speak({ text: "hi" }, { onError });
+    await settle();
+
+    expect(onError).toHaveBeenCalledTimes(1);
+    expect(onError.mock.calls[0][0]).toBeInstanceOf(Error);
+    expect(onError.mock.calls[0][0].message).toContain("Invalid or expired");
+    expect(optsOnError).toHaveBeenCalledTimes(1);
+  });
+
+  it("ignores callbacks from a superseded speak()", async () => {
+    fetchMock.mockResolvedValue(streamingResponse([new Uint8Array([1])]));
+    const firstEnd = vi.fn();
+    const engine = makeEngine();
+
+    engine.speak({ text: "first" }, { onEnd: firstEnd });
+    engine.speak({ text: "second" }, {}); // supersedes the first
+    await settle();
+
+    // The first request's onEnd must not fire even if its (stale) finish lands.
+    player.fireFinished();
+    expect(firstEnd).not.toHaveBeenCalled();
+  });
+});
+
+/** A scriptable SpeechEngine that exposes the callbacks handed to speak(). */
+function fakeEngine(id: string) {
+  let cbs: SpeechCallbacks = {};
+  return {
+    id,
+    supportsPause: true,
+    speak: vi.fn((_req: SpeechRequest, c: SpeechCallbacks) => {
+      cbs = c;
+    }),
+    pause: vi.fn(),
+    resume: vi.fn(),
+    stop: vi.fn(),
+    destroy: vi.fn(),
+    emitStart: () => cbs.onStart?.(),
+    emitEnd: () => cbs.onEnd?.(),
+    emitError: (e: Error) => cbs.onError?.(e),
+  };
+}
+
+describe("FallbackSpeechEngine", () => {
+  it("falls back to the secondary engine when the primary fails before audio", () => {
+    const primary = fakeEngine("primary");
+    const fallback = fakeEngine("fallback");
+    const onFallback = vi.fn();
+    const engine = new FallbackSpeechEngine(
+      primary as unknown as SpeechEngine,
+      fallback as unknown as SpeechEngine,
+      { onFallback },
+    );
+    const onError = vi.fn();
+    const req: SpeechRequest = { text: "hi" };
+
+    engine.speak(req, { onError });
+    primary.emitError(new Error("no endpoint"));
+
+    expect(onFallback).toHaveBeenCalledTimes(1);
+    expect(fallback.speak).toHaveBeenCalledTimes(1);
+    expect(fallback.speak.mock.calls[0][0]).toBe(req);
+    expect(onError).not.toHaveBeenCalled();
+  });
+
+  it("surfaces a failure that happens after playback has started", () => {
+    const primary = fakeEngine("primary");
+    const fallback = fakeEngine("fallback");
+    const engine = new FallbackSpeechEngine(
+      primary as unknown as SpeechEngine,
+      fallback as unknown as SpeechEngine,
+    );
+    const onError = vi.fn();
+
+    engine.speak({ text: "hi" }, { onError });
+    primary.emitStart();
+    primary.emitError(new Error("mid-stream drop"));
+
+    expect(fallback.speak).not.toHaveBeenCalled();
+    expect(onError).toHaveBeenCalledTimes(1);
+    expect(onError.mock.calls[0][0].message).toBe("mid-stream drop");
+  });
+
+  it("routes pause/resume/stop to the active engine", () => {
+    const primary = fakeEngine("primary");
+    const fallback = fakeEngine("fallback");
+    const engine = new FallbackSpeechEngine(
+      primary as unknown as SpeechEngine,
+      fallback as unknown as SpeechEngine,
+    );
+
+    // Before any failure, the primary is active.
+    engine.speak({ text: "hi" }, {});
+    engine.pause();
+    expect(primary.pause).toHaveBeenCalledTimes(1);
+    expect(fallback.pause).not.toHaveBeenCalled();
+
+    // After a pre-start failure the fallback becomes active.
+    primary.emitError(new Error("fail"));
+    engine.resume();
+    engine.stop();
+    expect(fallback.resume).toHaveBeenCalledTimes(1);
+    expect(fallback.stop).toHaveBeenCalledTimes(1);
+    expect(primary.resume).not.toHaveBeenCalled();
+  });
+
+  it("destroys both wrapped engines", () => {
+    const primary = fakeEngine("primary");
+    const fallback = fakeEngine("fallback");
+    const engine = new FallbackSpeechEngine(
+      primary as unknown as SpeechEngine,
+      fallback as unknown as SpeechEngine,
+    );
+    engine.destroy();
+    expect(primary.destroy).toHaveBeenCalledTimes(1);
+    expect(fallback.destroy).toHaveBeenCalledTimes(1);
+  });
+});