@ephia/dova-sdk 1.0.0

package/src/core/transport/Transport.ts

@@ -0,0 +1,82 @@
+/**
+ * Interface abstraite du transport Ephia Audio.
+ *
+ * LiveKit est une implémentation. MockTransport en est une autre.
+ */
+
+import type { EphiaAudioEvent, EphiaClientMessage, EphiaServerEvent } from "ephia-protocol";
+import type { EphiaSdkError } from "../../shared/errors/EphiaSdkError";
+
+export type TransportConnectParams = {
+  livekitUrl: string;
+  token: string;
+  roomName: string;
+};
+
+export type TransportConnectionStatus =
+  | "idle"
+  | "connecting"
+  | "connected"
+  | "reconnecting"
+  | "reconnected"
+  | "disconnected"
+  | "error";
+
+export type TransportState = {
+  status: TransportConnectionStatus;
+  roomName?: string;
+  participantIdentity?: string;
+  connectionQuality?: "unknown" | "poor" | "good" | "excellent";
+  krispActive?: boolean;
+  localAudioPublished: boolean;
+  localAudioMuted: boolean;
+  reconnectCount: number;
+  lastError?: EphiaSdkError;
+};
+
+export interface Transport {
+  /** Connecte le transport. */
+  connect(params: TransportConnectParams): Promise<void>;
+
+  /** Déconnecte proprement. */
+  disconnect(reason?: string): Promise<void>;
+
+  /** Publie une piste audio. */
+  publishAudio(track: MediaStreamTrack, options?: { enableNoiseFilter?: boolean }): Promise<void>;
+
+  /** Dé-publie l'audio local. */
+  unpublishAudio(): Promise<void>;
+
+  /** Envoie un message client vers le serveur. */
+  sendMessage(message: EphiaClientMessage): Promise<void>;
+
+  /** Écoute les events Ephia. Retourne un unsubscriber. */
+  onEvent(callback: (event: EphiaAudioEvent) => void): () => void;
+
+  /** Écoute les events serveur V2 bruts (sans inférence). Retourne un unsubscriber. */
+  onServerEvent(callback: (event: EphiaServerEvent) => void): () => void;
+
+  /** Écoute les changements d'état transport. Retourne un unsubscriber. */
+  onTransportState(callback: (state: TransportState) => void): () => void;
+
+  /** Écoute les erreurs transport. Retourne un unsubscriber. */
+  onError(callback: (error: EphiaSdkError) => void): () => void;
+
+  /** Retourne l'état courant. */
+  getState(): TransportState;
+
+  /** Publication audio locale (pour VAD gate mute/unmute). */
+  getLocalAudioPublication?(): {
+    mute(): Promise<unknown>;
+    unmute(): Promise<unknown>;
+  } | null;
+
+  /** Pré-chauffe la connexion WebRTC (DNS + TLS). Non bloquant. Optionnel. */
+  prepareConnection?(url: string, token?: string): Promise<void>;
+
+  /** Appel RPC vers le serveur. */
+  performRpc?(method: string, payload: unknown, timeout?: number): Promise<string>;
+
+  /** Change le périphérique actif. */
+  switchActiveDevice?(kind: MediaDeviceKind, deviceId: string): Promise<boolean>;
+}

package/src/debug/sdk-debug-collector.ts

@@ -0,0 +1,79 @@
+/**
+ * Collecteur de debug interne pour l'Ephia SDK.
+ * Active uniquement en environnement de développement (Next.js dev).
+ * Expose window.__ephia_sdk_debug__ pour inspection externe.
+ */
+
+export interface SdkDebugEntry {
+  ts: number;
+  source: string;
+  type: string;
+  payload: unknown;
+}
+
+export interface SdkDebugStateSnapshot {
+  ts: number;
+  source: string;
+  state: unknown;
+}
+
+export interface SdkDebugCollector {
+  events: SdkDebugEntry[];
+  rawEvents: SdkDebugEntry[];
+  states: Record<string, SdkDebugStateSnapshot>;
+  pushEvent(source: string, type: string, payload: unknown): void;
+  pushRawEvent(source: string, type: string, payload: unknown): void;
+  setState(source: string, state: unknown): void;
+}
+
+function isDev(): boolean {
+  if (typeof window === "undefined") return false;
+  try {
+    return process.env.NODE_ENV === "development";
+  } catch {
+    return false;
+  }
+}
+
+let collector: SdkDebugCollector | null = null;
+
+export function getSdkDebugCollector(): SdkDebugCollector | null {
+  if (!isDev()) return null;
+  if (!collector) {
+    collector = {
+      events: [],
+      rawEvents: [],
+      states: {},
+      pushEvent(source, type, payload) {
+        const entry: SdkDebugEntry = { ts: performance.now(), source, type, payload };
+        this.events.push(entry);
+        if (this.events.length > 3000) this.events.shift();
+      },
+      pushRawEvent(source, type, payload) {
+        const entry: SdkDebugEntry = { ts: performance.now(), source, type, payload };
+        this.rawEvents.push(entry);
+        if (this.rawEvents.length > 3000) this.rawEvents.shift();
+      },
+      setState(source, state) {
+        this.states[source] = { ts: performance.now(), source, state };
+      },
+    };
+    (window as unknown as Record<string, unknown>).__ephia_sdk_debug__ = collector;
+  }
+  return collector;
+}
+
+/** Helper: pousse un event brut sans importer le collector explicitement. */
+export function dbgRawEvent(source: string, type: string, payload: unknown): void {
+  getSdkDebugCollector()?.pushRawEvent(source, type, payload);
+}
+
+/** Helper: pousse un event parsé. */
+export function dbgEvent(source: string, type: string, payload: unknown): void {
+  getSdkDebugCollector()?.pushEvent(source, type, payload);
+}
+
+/** Helper: met à jour un snapshot state. */
+export function dbgState(source: string, state: unknown): void {
+  getSdkDebugCollector()?.setState(source, state);
+}

package/src/devices/index.ts

@@ -0,0 +1,2 @@
+export * from "./speechmike";
+

package/src/devices/speechmike/__tests__/EphiaSpeechMikeProvider.test.tsx

@@ -0,0 +1,99 @@
+// @vitest-environment jsdom
+
+import React from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { cleanup, render, screen, waitFor } from "@testing-library/react";
+import { EphiaSpeechMikeProvider } from "../react/EphiaSpeechMikeProvider";
+import { useEphiaSpeechMike } from "../react/useEphiaSpeechMike";
+import { EphiaInternalContext } from "../../../react/provider/EphiaInternalContext";
+import { createEphiaStore } from "../../../react/store/create-ephia-store";
+import type { EphiaInternalContextValue } from "../../../react/provider/EphiaInternalContext";
+
+function mediaDevice(label: string, deviceId: string): MediaDeviceInfo {
+  return {
+    deviceId,
+    groupId: `${deviceId}-group`,
+    kind: "audioinput",
+    label,
+    toJSON: () => ({}),
+  } as MediaDeviceInfo;
+}
+
+function installMediaDeviceEventTarget(devices: MediaDeviceInfo[]): void {
+  const target = new EventTarget();
+  vi.stubGlobal("navigator", {
+    mediaDevices: {
+      enumerateDevices: vi.fn(async () => devices),
+      addEventListener: target.addEventListener.bind(target),
+      removeEventListener: target.removeEventListener.bind(target),
+      dispatchEvent: target.dispatchEvent.bind(target),
+    },
+  });
+}
+
+function HookProbe(): React.ReactElement {
+  const speechMike = useEphiaSpeechMike();
+  return (
+    <output
+      data-testid="speechmike"
+      data-hid={speechMike.status.hid}
+      data-audio={speechMike.status.audio}
+      data-device-id={speechMike.audioInputDeviceId ?? ""}
+    >
+      {speechMike.isReady ? "ready" : "not-ready"}
+    </output>
+  );
+}
+
+function createInternalContext(setPreferred: (deviceId: string | undefined) => void): EphiaInternalContextValue {
+  return {
+    store: createEphiaStore(),
+    clientRef: {
+      current: {
+        setPreferredAudioInputDeviceId: setPreferred,
+      },
+    } as EphiaInternalContextValue["clientRef"],
+    targetManagerRef: { current: null } as EphiaInternalContextValue["targetManagerRef"],
+    clientEpoch: 0,
+  };
+}
+
+describe("EphiaSpeechMikeProvider", () => {
+  afterEach(() => {
+    cleanup();
+    vi.unstubAllGlobals();
+  });
+
+  it("returns a safe hook fallback outside the provider", () => {
+    render(<HookProbe />);
+
+    const output = screen.getByTestId("speechmike");
+    expect(output.getAttribute("data-hid")).toBe("unsupported");
+    expect(output.getAttribute("data-audio")).toBe("idle");
+  });
+
+  it("resolves a SpeechMike audio device and applies it to the internal client", async () => {
+    const setPreferred = vi.fn();
+    installMediaDeviceEventTarget([
+      mediaDevice("Built-in Microphone", "builtin"),
+      mediaDevice("Philips SpeechMike Premium", "speechmike"),
+    ]);
+    const internal = createInternalContext(setPreferred);
+
+    render(
+      <EphiaInternalContext.Provider value={internal}>
+        <EphiaSpeechMikeProvider autoConnect={false}>
+          <HookProbe />
+        </EphiaSpeechMikeProvider>
+      </EphiaInternalContext.Provider>,
+    );
+
+    (navigator.mediaDevices as unknown as EventTarget).dispatchEvent(new Event("devicechange"));
+
+    await waitFor(() => {
+      expect(setPreferred).toHaveBeenCalledWith("speechmike");
+      expect(screen.getByTestId("speechmike").getAttribute("data-audio")).toBe("ready");
+      expect(screen.getByTestId("speechmike").getAttribute("data-device-id")).toBe("speechmike");
+    });
+  });
+});

package/src/devices/speechmike/__tests__/speechmike-audio-resolver.test.ts

@@ -0,0 +1,96 @@
+// @vitest-environment jsdom
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  listAudioInputDevices,
+  resolveSpeechMikeAudioInput,
+  scoreSpeechMikeAudioDevice,
+} from "../speechmike-audio-resolver";
+
+function mediaDevice(
+  label: string,
+  deviceId = label.toLowerCase().replace(/\s+/g, "-"),
+  kind: MediaDeviceKind = "audioinput",
+): MediaDeviceInfo {
+  return {
+    deviceId,
+    groupId: `${deviceId}-group`,
+    kind,
+    label,
+    toJSON: () => ({}),
+  } as MediaDeviceInfo;
+}
+
+function stubMediaDevices(devices: MediaDeviceInfo[], stream?: MediaStream): void {
+  vi.stubGlobal("navigator", {
+    mediaDevices: {
+      enumerateDevices: vi.fn(async () => devices),
+      getUserMedia: vi.fn(async () => stream ?? createStream()),
+    },
+  });
+}
+
+function createStream(): MediaStream {
+  const track = { stop: vi.fn() } as unknown as MediaStreamTrack;
+  return {
+    getTracks: () => [track],
+  } as unknown as MediaStream;
+}
+
+describe("SpeechMikeAudioResolver", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("scores SpeechMike, Philips, dictation, and microphone labels", () => {
+    expect(scoreSpeechMikeAudioDevice(mediaDevice("SpeechMike Premium"))).toBe(100);
+    expect(scoreSpeechMikeAudioDevice(mediaDevice("Philips USB"))).toBe(60);
+    expect(scoreSpeechMikeAudioDevice(mediaDevice("Dictation source"))).toBe(40);
+    expect(scoreSpeechMikeAudioDevice(mediaDevice("Built-in Microphone"))).toBe(10);
+    expect(scoreSpeechMikeAudioDevice(mediaDevice("Speaker", "speaker", "audiooutput"))).toBe(0);
+  });
+
+  it("selects the highest scoring audio input", async () => {
+    stubMediaDevices([
+      mediaDevice("Built-in Microphone", "builtin"),
+      mediaDevice("Philips SpeechMike Premium", "speechmike"),
+      mediaDevice("Dictation microphone", "dictation"),
+    ]);
+
+    await expect(resolveSpeechMikeAudioInput()).resolves.toMatchObject({
+      deviceId: "speechmike",
+      label: "Philips SpeechMike Premium",
+      score: 160,
+    });
+  });
+
+  it("returns null when no audio input matches", async () => {
+    stubMediaDevices([mediaDevice("USB Headset", "headset")]);
+
+    await expect(resolveSpeechMikeAudioInput()).resolves.toBeNull();
+  });
+
+  it("lists only audio input devices", async () => {
+    stubMediaDevices([
+      mediaDevice("SpeechMike", "mic"),
+      mediaDevice("Speaker", "speaker", "audiooutput"),
+    ]);
+
+    await expect(listAudioInputDevices()).resolves.toHaveLength(1);
+  });
+
+  it("requests permission only when requested and closes the probe stream", async () => {
+    const stop = vi.fn();
+    const stream = {
+      getTracks: () => [{ stop }],
+    } as unknown as MediaStream;
+    stubMediaDevices([mediaDevice("SpeechMike", "speechmike")], stream);
+
+    await resolveSpeechMikeAudioInput();
+    expect(navigator.mediaDevices.getUserMedia).not.toHaveBeenCalled();
+
+    await resolveSpeechMikeAudioInput({ requestPermission: true });
+    expect(navigator.mediaDevices.getUserMedia).toHaveBeenCalledWith({ audio: true });
+    expect(stop).toHaveBeenCalledTimes(1);
+  });
+});

package/src/devices/speechmike/__tests__/speechmike-button-router.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it, vi, afterEach } from "vitest";
+import { SpeechMikeButtonRouter } from "../speechmike-button-router";
+import type { DictationSupportEnum } from "../dictation-support-loader";
+
+const BUTTONS = {
+  1: "RECORD",
+  2: "PLAY",
+  4: "F3",
+  8: "F1",
+  16: "UNKNOWN",
+  RECORD: 1,
+  PLAY: 2,
+  F3: 4,
+  F1: 8,
+  UNKNOWN: 16,
+} as unknown as DictationSupportEnum;
+
+describe("SpeechMikeButtonRouter", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("maps known button bitmasks to default actions", () => {
+    expect(new SpeechMikeButtonRouter(BUTTONS).parse(1)?.actions).toEqual([
+      "record.toggle",
+    ]);
+    expect(new SpeechMikeButtonRouter(BUTTONS).parse(2)?.actions).toEqual([
+      "play.toggle",
+    ]);
+    expect(new SpeechMikeButtonRouter(BUTTONS).parse(4)?.actions).toEqual([
+      "audio.submit",
+    ]);
+    expect(new SpeechMikeButtonRouter(BUTTONS).parse(8)?.actions).toEqual([
+      "audio.discard",
+    ]);
+  });
+
+  it("debounces repeated button events", () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(1_000);
+    const router = new SpeechMikeButtonRouter(BUTTONS, {}, 150);
+
+    expect(router.parse(1)?.actions).toEqual(["record.toggle"]);
+    vi.setSystemTime(1_100);
+    expect(router.parse(1)).toBeNull();
+    vi.setSystemTime(1_200);
+    expect(router.parse(1)?.actions).toEqual(["record.toggle"]);
+  });
+
+  it("applies custom mapping over defaults", () => {
+    const router = new SpeechMikeButtonRouter(BUTTONS, {
+      RECORD: "record.start",
+      F3: "none",
+    });
+
+    expect(router.parse(1)?.actions).toEqual(["record.start"]);
+    expect(new SpeechMikeButtonRouter(BUTTONS, { F3: "none" }).parse(4)?.actions).toEqual([]);
+  });
+
+  it("returns no actions for unknown buttons and empty masks", () => {
+    const router = new SpeechMikeButtonRouter(BUTTONS);
+
+    expect(router.parse(16)).toMatchObject({ actions: [], rawBitMask: 16 });
+    expect(router.parse(0)).toMatchObject({ actions: [], rawBitMask: 0 });
+  });
+});

package/src/devices/speechmike/__tests__/speechmike-device-manager.test.ts

@@ -0,0 +1,201 @@
+// @vitest-environment jsdom
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { SpeechMikeDeviceManager } from "../speechmike-device-manager";
+import type {
+  DictationButtonCallback,
+  DictationDeviceCallback,
+  DictationDeviceManagerLike,
+  DictationSupportRuntime,
+} from "../dictation-support-loader";
+
+const BUTTONS = {
+  1: "RECORD",
+  RECORD: 1,
+} as unknown as DictationSupportRuntime["ButtonEvent"];
+
+class FakeDictationDeviceManager implements DictationDeviceManagerLike {
+  devices: unknown[] = [];
+  init = vi.fn(async () => {});
+  requestDevice = vi.fn(async () => {
+    this.devices = [{ productName: "SpeechMike Premium" }];
+    return this.devices;
+  });
+  getDevices = vi.fn(() => this.devices);
+  disconnect = vi.fn();
+  buttonListeners = new Set<DictationButtonCallback>();
+  connectedListeners = new Set<DictationDeviceCallback>();
+  disconnectedListeners = new Set<DictationDeviceCallback>();
+
+  addButtonEventListener = vi.fn((cb: DictationButtonCallback) => {
+    this.buttonListeners.add(cb);
+  });
+  removeButtonEventListener = vi.fn((cb: DictationButtonCallback) => {
+    this.buttonListeners.delete(cb);
+  });
+  addDeviceConnectedEventListener = vi.fn((cb: DictationDeviceCallback) => {
+    this.connectedListeners.add(cb);
+  });
+  removeDeviceConnectedEventListener = vi.fn((cb: DictationDeviceCallback) => {
+    this.connectedListeners.delete(cb);
+  });
+  addDeviceDisconnectedEventListener = vi.fn((cb: DictationDeviceCallback) => {
+    this.disconnectedListeners.add(cb);
+  });
+  removeDeviceDisconnectedEventListener = vi.fn((cb: DictationDeviceCallback) => {
+    this.disconnectedListeners.delete(cb);
+  });
+}
+
+function runtimeFor(instance: FakeDictationDeviceManager): DictationSupportRuntime {
+  return {
+    ButtonEvent: BUTTONS,
+    DictationDeviceManager: class {
+      constructor() {
+        return instance;
+      }
+    } as unknown as new () => DictationDeviceManagerLike,
+  };
+}
+
+function stubNavigator(options: {
+  hidDevices?: unknown[];
+  mediaDevices?: MediaDeviceInfo[];
+  connect?: Set<(event: Event) => void>;
+  disconnect?: Set<(event: Event) => void>;
+} = {}): void {
+  const connect = options.connect ?? new Set<(event: Event) => void>();
+  const disconnect = options.disconnect ?? new Set<(event: Event) => void>();
+
+  vi.stubGlobal("navigator", {
+    hid: {
+      getDevices: vi.fn(async () => options.hidDevices ?? []),
+      addEventListener: vi.fn((type: "connect" | "disconnect", cb: (event: Event) => void) => {
+        (type === "connect" ? connect : disconnect).add(cb);
+      }),
+      removeEventListener: vi.fn((type: "connect" | "disconnect", cb: (event: Event) => void) => {
+        (type === "connect" ? connect : disconnect).delete(cb);
+      }),
+    },
+    mediaDevices: {
+      enumerateDevices: vi.fn(async () => options.mediaDevices ?? []),
+    },
+  });
+}
+
+function mediaDevice(label: string): MediaDeviceInfo {
+  return {
+    deviceId: label,
+    groupId: label,
+    kind: "audioinput",
+    label,
+    toJSON: () => ({}),
+  } as MediaDeviceInfo;
+}
+
+describe("SpeechMikeDeviceManager", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.useRealTimers();
+  });
+
+  it("reports unsupported when WebHID is absent", async () => {
+    vi.stubGlobal("navigator", { mediaDevices: {} });
+    const statuses: string[] = [];
+    const manager = new SpeechMikeDeviceManager({
+      loadRuntime: async () => runtimeFor(new FakeDictationDeviceManager()),
+    });
+    manager.on("status", (status) => statuses.push(status));
+
+    await manager.initialize();
+
+    expect(statuses).toContain("unsupported");
+  });
+
+  it("reports driver_missing when dictation_support cannot load", async () => {
+    stubNavigator();
+    const errors: string[] = [];
+    const statuses: string[] = [];
+    const manager = new SpeechMikeDeviceManager({
+      loadRuntime: async () => {
+        throw Object.assign(new Error("missing"), { code: "speechmike.driver_missing" });
+      },
+    });
+    manager.on("status", (status) => statuses.push(status));
+    manager.on("error", (error) => errors.push(error.code));
+
+    await manager.initialize();
+
+    expect(errors).toEqual(["speechmike.driver_missing"]);
+    expect(statuses).toContain("driver_missing");
+  });
+
+  it("silently restores an already authorized device", async () => {
+    const instance = new FakeDictationDeviceManager();
+    instance.devices = [{ productName: "SpeechMike Premium" }];
+    stubNavigator({ hidDevices: [{ productName: "SpeechMike Premium" }] });
+    const devices: unknown[] = [];
+    const statuses: string[] = [];
+    const manager = new SpeechMikeDeviceManager({
+      loadRuntime: async () => runtimeFor(instance),
+    });
+    manager.on("device", (device) => devices.push(device));
+    manager.on("status", (status) => statuses.push(status));
+
+    await manager.initialize();
+
+    expect(instance.init).toHaveBeenCalled();
+    expect(devices[0]).toBe(instance.devices[0]);
+    expect(statuses).toContain("connected");
+    manager.dispose();
+  });
+
+  it("reports present_unauthorized when only physical/audio presence is visible", async () => {
+    const instance = new FakeDictationDeviceManager();
+    stubNavigator({ mediaDevices: [mediaDevice("Philips SpeechMike")] });
+    const statuses: string[] = [];
+    const manager = new SpeechMikeDeviceManager({
+      loadRuntime: async () => runtimeFor(instance),
+    });
+    manager.on("status", (status) => statuses.push(status));
+
+    await manager.initialize();
+
+    expect(statuses).toContain("present_unauthorized");
+    manager.dispose();
+  });
+
+  it("requests explicit authorization and attaches the granted device", async () => {
+    const instance = new FakeDictationDeviceManager();
+    stubNavigator({ hidDevices: [{ productName: "SpeechMike Premium" }] });
+    const statuses: string[] = [];
+    const manager = new SpeechMikeDeviceManager({
+      loadRuntime: async () => runtimeFor(instance),
+    });
+    manager.on("status", (status) => statuses.push(status));
+
+    await manager.requestAuthorization();
+
+    expect(instance.requestDevice).toHaveBeenCalled();
+    expect(manager.getCurrentDevice()).toBe(instance.devices[0]);
+    expect(statuses).toContain("authorization_required");
+    expect(statuses).toContain("connected");
+    manager.dispose();
+  });
+
+  it("cleans up listeners and disconnects on dispose", async () => {
+    const instance = new FakeDictationDeviceManager();
+    stubNavigator({ hidDevices: [{ productName: "SpeechMike Premium" }] });
+    const manager = new SpeechMikeDeviceManager({
+      loadRuntime: async () => runtimeFor(instance),
+    });
+
+    await manager.initialize();
+    manager.dispose();
+
+    expect(instance.removeButtonEventListener).toHaveBeenCalled();
+    expect(instance.removeDeviceConnectedEventListener).toHaveBeenCalled();
+    expect(instance.removeDeviceDisconnectedEventListener).toHaveBeenCalled();
+    expect(instance.disconnect).toHaveBeenCalled();
+  });
+});

package/src/devices/speechmike/__tests__/speechmike-led-controller.test.ts

@@ -0,0 +1,68 @@
+// @vitest-environment jsdom
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { SpeechMikeLedController } from "../speechmike-led-controller";
+
+describe("SpeechMikeLedController", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("uses batch setLeds when available", async () => {
+    const setLeds = vi.fn(async () => {});
+    const controller = new SpeechMikeLedController(() => ({ setLeds }));
+
+    await controller.setBatch({ 1: 3, 2: 0 });
+
+    expect(setLeds).toHaveBeenCalledWith({ 1: 3, 2: 0 });
+  });
+
+  it("falls back to individual setLed calls when batch fails", async () => {
+    const setLeds = vi.fn(async () => {
+      throw new Error("batch failed");
+    });
+    const setLed = vi.fn(async () => {});
+    const controller = new SpeechMikeLedController(() => ({ setLeds, setLed }));
+
+    await controller.setBatch({ 1: 3, 2: 0 });
+
+    expect(setLed).toHaveBeenCalledWith(1, 3);
+    expect(setLed).toHaveBeenCalledWith(2, 0);
+  });
+
+  it("no-ops without a connected device", async () => {
+    const controller = new SpeechMikeLedController(() => null);
+
+    await expect(controller.setBatch({ 1: 3 })).resolves.toBeUndefined();
+    await expect(controller.setLed(1, 3)).resolves.toBe(false);
+  });
+
+  it("returns false when an individual LED operation times out", async () => {
+    vi.useFakeTimers();
+    const controller = new SpeechMikeLedController(() => ({
+      setLed: vi.fn(() => new Promise<void>(() => {})),
+    }));
+
+    const result = controller.setLed(1, 3);
+    vi.advanceTimersByTime(501);
+
+    await expect(result).resolves.toBe(false);
+  });
+
+  it("clear queues the off intent", async () => {
+    const setLeds = vi.fn(async () => {});
+    const controller = new SpeechMikeLedController(() => ({ setLeds }));
+
+    controller.clear();
+    await vi.waitFor(() => expect(setLeds).toHaveBeenCalled());
+
+    const firstCall = setLeds.mock.calls[0] as unknown as
+      | [Record<number, number>]
+      | undefined;
+    expect(firstCall?.[0]).toMatchObject({
+      0: 0,
+      1: 0,
+      9: 0,
+    });
+  });
+});