feat(web): API client, IndexedDB store, Recorder state machine

web/src/lib/api.ts

@@ -0,0 +1,86 @@
+export type Lang = { code: string; label: string };
+
+export type ParamSpec = {
+  name: string;
+  label: string;
+  type: "float" | "int" | "bool" | "enum";
+  default: number | string | boolean;
+  min?: number;
+  max?: number;
+  step?: number;
+  choices?: string[];
+  help?: string;
+};
+
+export type ModelInfo = {
+  id: string;
+  label: string;
+  description: string;
+  languages: Lang[];
+  paralinguistic_tags: string[];
+  supports_voice_clone: boolean;
+  params: ParamSpec[];
+};
+
+export type ActiveStatus = {
+  id: string | null;
+  status: "idle" | "loading" | "loaded" | "error";
+  last_error: string | null;
+};
+
+export async function listModels(): Promise<ModelInfo[]> {
+  const r = await fetch("/api/models");
+  if (!r.ok) throw new Error(`listModels: ${r.status}`);
+  return r.json();
+}
+
+export async function getActiveModel(): Promise<ActiveStatus> {
+  const r = await fetch("/api/models/active");
+  if (!r.ok) throw new Error(`getActiveModel: ${r.status}`);
+  return r.json();
+}
+
+export async function activateModel(id: string): Promise<void> {
+  const r = await fetch(`/api/models/${encodeURIComponent(id)}/activate`, { method: "POST" });
+  if (!r.ok) {
+    const err = await r.json().catch(() => ({}));
+    throw new Error(err?.error?.code ?? `activateModel: ${r.status}`);
+  }
+}
+
+export type GenerateInput = {
+  modelId: string;
+  text: string;
+  language?: string;
+  params: Record<string, unknown>;
+  reference?: Blob;
+};
+
+export async function generate(input: GenerateInput): Promise<Blob> {
+  const fd = new FormData();
+  fd.set("text", input.text);
+  fd.set("model_id", input.modelId);
+  fd.set("params", JSON.stringify(input.params ?? {}));
+  if (input.language) fd.set("language", input.language);
+  if (input.reference) fd.set("reference_wav", input.reference, "ref.wav");
+  const r = await fetch("/api/generate", { method: "POST", body: fd });
+  if (!r.ok) {
+    const err = await r.json().catch(() => ({}));
+    throw new Error(err?.error?.code ?? `generate: ${r.status}`);
+  }
+  return r.blob();
+}
+
+export function streamActiveEvents(
+  onEvent: (e: { id: string | null; status: string; error?: string }) => void,
+) {
+  const es = new EventSource("/api/models/active/events");
+  es.onmessage = (m) => {
+    try {
+      onEvent(JSON.parse(m.data));
+    } catch {
+      /* ignore malformed */
+    }
+  };
+  return () => es.close();
+}

web/src/lib/audio.ts

@@ -0,0 +1,63 @@
+export type RecorderState = "idle" | "requesting" | "recording" | "stopping" | "error";
+
+type Deps = {
+  getUserMedia?: (constraints: MediaStreamConstraints) => Promise<MediaStream>;
+};
+
+export class Recorder {
+  state: RecorderState = "idle";
+  lastError: Error | null = null;
+  private chunks: BlobPart[] = [];
+  private rec: MediaRecorder | null = null;
+  private stream: MediaStream | null = null;
+  private getUserMedia: NonNullable<Deps["getUserMedia"]>;
+
+  constructor(deps: Deps = {}) {
+    this.getUserMedia =
+      deps.getUserMedia ?? ((c) => navigator.mediaDevices.getUserMedia(c));
+  }
+
+  requestStart() {
+    this.state = "requesting";
+  }
+
+  async start(): Promise<void> {
+    this.requestStart();
+    try {
+      this.stream = await this.getUserMedia({ audio: true });
+    } catch (e) {
+      this.lastError = e as Error;
+      this.state = "error";
+      throw e;
+    }
+    this.chunks = [];
+    this.rec = new MediaRecorder(this.stream);
+    this.rec.ondataavailable = (ev) => {
+      if (ev.data && ev.data.size > 0) this.chunks.push(ev.data);
+    };
+    this.rec.start();
+    this.state = "recording";
+  }
+
+  stop(): Promise<Blob | null> {
+    if (this.state === "idle") return Promise.resolve(null);
+    return new Promise((resolve) => {
+      if (!this.rec) {
+        this.state = "idle";
+        resolve(null);
+        return;
+      }
+      this.state = "stopping";
+      this.rec.onstop = () => {
+        const blob = new Blob(this.chunks, { type: this.rec?.mimeType ?? "audio/webm" });
+        this.chunks = [];
+        this.rec = null;
+        this.stream?.getTracks().forEach((t) => t.stop());
+        this.stream = null;
+        this.state = "idle";
+        resolve(blob);
+      };
+      this.rec.stop();
+    });
+  }
+}

web/src/lib/idb.ts

@@ -0,0 +1,82 @@
+import Dexie, { type Table } from "dexie";
+
+export const HISTORY_CAP = 50;
+
+export type VoiceRecord = {
+  id?: number;
+  name: string;
+  blob: Blob;
+  sampleRate: number;
+  durationMs: number;
+  createdAt: number;
+  isFavorite: boolean;
+};
+
+export type HistoryRecord = {
+  id?: number;
+  text: string;
+  modelId: string;
+  voiceId?: number;
+  language?: string;
+  params: Record<string, unknown>;
+  audioBlob: Blob;
+  createdAt: number;
+};
+
+class DB extends Dexie {
+  voices!: Table<VoiceRecord, number>;
+  history!: Table<HistoryRecord, number>;
+
+  constructor() {
+    super("chatterbox-voice-studio");
+    this.version(1).stores({
+      voices: "++id, name, createdAt, isFavorite",
+      history: "++id, createdAt",
+    });
+  }
+}
+
+export const db = new DB();
+
+export async function addVoice(
+  v: Omit<VoiceRecord, "id" | "createdAt" | "isFavorite"> & Partial<Pick<VoiceRecord, "isFavorite">>,
+): Promise<number> {
+  return db.voices.add({
+    ...v,
+    isFavorite: v.isFavorite ?? false,
+    createdAt: Date.now(),
+  });
+}
+
+export async function listVoices(): Promise<VoiceRecord[]> {
+  return db.voices.orderBy("createdAt").reverse().toArray();
+}
+
+export async function deleteVoice(id: number): Promise<void> {
+  await db.voices.delete(id);
+}
+
+export async function setFavorite(id: number, fav: boolean): Promise<void> {
+  await db.voices.update(id, { isFavorite: fav });
+}
+
+export async function addHistory(
+  h: Omit<HistoryRecord, "id" | "createdAt">,
+): Promise<number> {
+  const id = await db.history.add({ ...h, createdAt: Date.now() });
+  const count = await db.history.count();
+  if (count > HISTORY_CAP) {
+    const overflow = count - HISTORY_CAP;
+    const oldest = await db.history.orderBy("createdAt").limit(overflow).primaryKeys();
+    await db.history.bulkDelete(oldest);
+  }
+  return id;
+}
+
+export async function listHistory(): Promise<HistoryRecord[]> {
+  return db.history.orderBy("createdAt").reverse().toArray();
+}
+
+export async function clearHistory(): Promise<void> {
+  await db.history.clear();
+}

web/src/test/api.test.ts

@@ -0,0 +1,69 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { activateModel, generate, getActiveModel, listModels } from "@/lib/api";
+
+const fetchMock = vi.fn();
+
+beforeEach(() => {
+  vi.stubGlobal("fetch", fetchMock);
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  fetchMock.mockReset();
+});
+
+describe("api", () => {
+  it("listModels GETs /api/models", async () => {
+    fetchMock.mockResolvedValue(new Response(JSON.stringify([{ id: "x" }])));
+    const out = await listModels();
+    expect(fetchMock).toHaveBeenCalledWith("/api/models");
+    expect(out[0].id).toBe("x");
+  });
+
+  it("getActiveModel returns status object", async () => {
+    fetchMock.mockResolvedValue(
+      new Response(JSON.stringify({ id: "x", status: "loaded" })),
+    );
+    const out = await getActiveModel();
+    expect(out.status).toBe("loaded");
+  });
+
+  it("activateModel posts to /api/models/{id}/activate", async () => {
+    fetchMock.mockResolvedValue(new Response("{}", { status: 202 }));
+    await activateModel("foo");
+    expect(fetchMock).toHaveBeenCalledWith(
+      "/api/models/foo/activate",
+      expect.objectContaining({ method: "POST" }),
+    );
+  });
+
+  it("generate posts multipart and returns response blob", async () => {
+    fetchMock.mockResolvedValue(new Response("RIFFFAKE", { status: 200 }));
+    const out = await generate({
+      modelId: "x",
+      text: "hi",
+      params: {},
+    });
+    expect(typeof out.size).toBe("number");
+    expect(fetchMock).toHaveBeenCalledWith(
+      "/api/generate",
+      expect.objectContaining({ method: "POST" }),
+    );
+    const call = fetchMock.mock.calls[0];
+    const body = call[1].body as FormData;
+    expect(body.get("text")).toBe("hi");
+    expect(body.get("model_id")).toBe("x");
+  });
+
+  it("generate surfaces error JSON on 4xx", async () => {
+    fetchMock.mockResolvedValue(
+      new Response(
+        JSON.stringify({ error: { code: "model_not_found", message: "x" } }),
+        { status: 404, headers: { "content-type": "application/json" } },
+      ),
+    );
+    await expect(
+      generate({ modelId: "x", text: "hi", params: {} }),
+    ).rejects.toThrow(/model_not_found/);
+  });
+});

web/src/test/audio.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vitest";
+import { Recorder } from "@/lib/audio";
+
+describe("Recorder state machine", () => {
+  it("starts in idle", () => {
+    const r = new Recorder();
+    expect(r.state).toBe("idle");
+  });
+
+  it("transitions idle -> requesting on start()", () => {
+    const r = new Recorder();
+    r.requestStart();
+    expect(r.state).toBe("requesting");
+  });
+
+  it("transitions to error on permission denial", async () => {
+    const r = new Recorder({
+      getUserMedia: () => Promise.reject(new Error("denied")),
+    });
+    await r.start().catch(() => {});
+    expect(r.state).toBe("error");
+    expect(r.lastError?.message).toBe("denied");
+  });
+
+  it("ignores stop() in idle", async () => {
+    const r = new Recorder();
+    const result = await r.stop();
+    expect(r.state).toBe("idle");
+    expect(result).toBeNull();
+  });
+});

web/src/test/idb.test.ts

@@ -0,0 +1,57 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import {
+  addHistory,
+  addVoice,
+  db,
+  deleteVoice,
+  listHistory,
+  listVoices,
+  setFavorite,
+  HISTORY_CAP,
+} from "@/lib/idb";
+
+beforeEach(async () => {
+  await db.voices.clear();
+  await db.history.clear();
+});
+
+describe("voices", () => {
+  it("adds and lists voices ordered by createdAt desc", async () => {
+    await addVoice({ name: "A", blob: new Blob(["a"]), sampleRate: 24000, durationMs: 1000 });
+    await new Promise((r) => setTimeout(r, 5));
+    await addVoice({ name: "B", blob: new Blob(["b"]), sampleRate: 24000, durationMs: 1500 });
+    const out = await listVoices();
+    expect(out.map((v) => v.name)).toEqual(["B", "A"]);
+  });
+
+  it("setFavorite toggles", async () => {
+    const id = await addVoice({ name: "A", blob: new Blob(["a"]), sampleRate: 24000, durationMs: 1000 });
+    await setFavorite(id, true);
+    const v = (await listVoices()).find((x) => x.id === id)!;
+    expect(v.isFavorite).toBe(true);
+  });
+
+  it("deleteVoice removes", async () => {
+    const id = await addVoice({ name: "A", blob: new Blob(["a"]), sampleRate: 24000, durationMs: 1000 });
+    await deleteVoice(id);
+    expect(await listVoices()).toEqual([]);
+  });
+});
+
+describe("history", () => {
+  it("caps at HISTORY_CAP entries (oldest evicted)", async () => {
+    for (let i = 0; i < HISTORY_CAP + 5; i++) {
+      await addHistory({
+        text: `t${i}`,
+        modelId: "x",
+        voiceId: undefined,
+        language: undefined,
+        params: {},
+        audioBlob: new Blob([`${i}`]),
+      });
+    }
+    const items = await listHistory();
+    expect(items.length).toBe(HISTORY_CAP);
+    expect(items[0].text).toBe(`t${HISTORY_CAP + 4}`);
+  });
+});