@ephia/dova-sdk 1.0.0

package/src/react/hooks/targets/useEphiaTiptap.ts

@@ -0,0 +1,23 @@
+import type { Editor } from "@tiptap/core";
+import { createTiptapEphiaAdapter } from "../../../rich-editor/adapters/tiptap";
+import { useEphiaRichEditor } from "../../../rich-editor/use-ephia-rich-editor";
+import type { UseEphiaNativeTargetOptions } from "../useEphiaTarget";
+
+/** @deprecated Use `UseEphiaNativeTargetOptions` instead. */
+export type UseEphiaTargetOptions = UseEphiaNativeTargetOptions;
+
+/**
+ * @deprecated Use `useEphiaRichEditor(createTiptapEphiaAdapter(editor), options)`.
+ *
+ * @example
+ * const ref = useEphiaRichEditor(
+ *   createTiptapEphiaAdapter(editor),
+ *   { id: 'compte-rendu', label: 'Compte rendu' },
+ * );
+ */
+export function useEphiaTiptap(
+  editor: Editor | null,
+  options: UseEphiaNativeTargetOptions,
+): React.RefObject<HTMLDivElement | null> {
+  return useEphiaRichEditor(createTiptapEphiaAdapter(editor), options);
+}

package/src/react/hooks/useEphia.lifecycle.test.tsx

@@ -0,0 +1,389 @@
+// @vitest-environment jsdom
+
+import React, { useEffect, useState } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { cleanup, render, screen, waitFor, act } from "@testing-library/react";
+import { PROTOCOL_VERSION, type EphiaAudioEvent } from "ephia-protocol";
+// NOTE: EphiaAudioEvent is kept for MockTransport helpers; onEvent prop is removed in V2.
+import { EphiaProvider } from "../provider/EphiaProvider";
+import { EphiaAudioClient } from "../../core/client/EphiaAudioClient";
+import { useEphia } from "./useEphia";
+import { useEphiaContext } from "../provider/EphiaContext";
+import { EphiaDictationButton } from "../components/EphiaDictationButton";
+import { MockTransport } from "../../core/transport/MockTransport";
+
+class FakeAudioContext {
+  state: AudioContextState = "running";
+
+  createAnalyser(): AnalyserNode {
+    return {
+      fftSize: 0,
+      smoothingTimeConstant: 0,
+      frequencyBinCount: 8,
+      getByteTimeDomainData: (data: Uint8Array) => data.fill(128),
+    } as unknown as AnalyserNode;
+  }
+
+  createMediaStreamSource(): MediaStreamAudioSourceNode {
+    return {
+      connect: vi.fn(),
+      disconnect: vi.fn(),
+    } as unknown as MediaStreamAudioSourceNode;
+  }
+
+  resume(): Promise<void> {
+    return Promise.resolve();
+  }
+
+  close(): Promise<void> {
+    return Promise.resolve();
+  }
+}
+
+class FailingPublishTransport extends MockTransport {
+  async publishAudio(_track: MediaStreamTrack): Promise<void> {
+    throw new Error("publish failed");
+  }
+}
+
+function event<T extends EphiaAudioEvent["type"]>(
+  type: T,
+  payload: Extract<EphiaAudioEvent, { type: T }>["payload"],
+  seq = 1
+): Extract<EphiaAudioEvent, { type: T }> {
+  return {
+    protocolVersion: PROTOCOL_VERSION,
+    eventId: `00000000-0000-4000-8000-${String(seq).padStart(12, "0")}`,
+    sessionId: "test-session",
+    type,
+    seq,
+    timestampMs: Date.now(),
+    payload,
+  } as Extract<EphiaAudioEvent, { type: T }>;
+}
+
+function createMockMediaStream(): MediaStream {
+  const track = {
+    id: "track-1",
+    label: "Test microphone",
+    enabled: true,
+    muted: false,
+    readyState: "live",
+    getSettings: () => ({ deviceId: "device-1" }),
+    stop: vi.fn(),
+  } as unknown as MediaStreamTrack;
+  return {
+    getAudioTracks: () => [track],
+    getTracks: () => [track],
+  } as unknown as MediaStream;
+}
+
+function deferred<T>(): {
+  promise: Promise<T>;
+  resolve: (value: T) => void;
+  reject: (reason?: unknown) => void;
+} {
+  let resolve!: (value: T) => void;
+  let reject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
+class PauseAckBlockingTransport extends MockTransport {
+  private unpublishGate?: Promise<void>;
+  messages: Parameters<MockTransport["sendMessage"]>[0][] = [];
+
+  constructor(options: ConstructorParameters<typeof MockTransport>[0] = {}) {
+    super(options);
+  }
+
+  blockUnpublishUntil(promise: Promise<void>): void {
+    this.unpublishGate = promise;
+  }
+
+  async sendMessage(message: Parameters<MockTransport["sendMessage"]>[0]): Promise<void> {
+    this.messages.push(message);
+    if (message.type === "session.pause") {
+      setTimeout(() => {
+        this.simulateEvent(event("session.paused", {}, 100));
+      }, 0);
+      return;
+    }
+    if (message.type === "session.reset") {
+      setTimeout(() => {
+        this.simulateEvent(event("session.context.reset", { contextOnly: true }, 101));
+      }, 0);
+      return;
+    }
+    await super.sendMessage(message);
+  }
+
+  async unpublishAudio(): Promise<void> {
+    if (this.unpublishGate) {
+      await this.unpublishGate;
+    }
+    await super.unpublishAudio();
+  }
+}
+
+function installBrowserAudioMocks(): void {
+  vi.stubGlobal("navigator", {
+    mediaDevices: {
+      getUserMedia: vi.fn(async () => createMockMediaStream()),
+    },
+  });
+  Object.assign(window, {
+    AudioContext: FakeAudioContext,
+    webkitAudioContext: undefined,
+  });
+}
+
+function installDeferredBrowserAudioMocks(): ReturnType<typeof deferred<MediaStream>> {
+  const mic = deferred<MediaStream>();
+  vi.stubGlobal("navigator", {
+    mediaDevices: {
+      getUserMedia: vi.fn(() => mic.promise),
+    },
+  });
+  Object.assign(window, {
+    AudioContext: FakeAudioContext,
+    webkitAudioContext: undefined,
+  });
+  return mic;
+}
+
+function installCreateSessionMock(): void {
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async () =>
+      new Response(
+        JSON.stringify({
+          session_id: "test-session",
+          room_name: "room-1",
+          token: "token-1",
+          livekit_url: "wss://livekit.test",
+        }),
+        { status: 200 }
+      )
+    )
+  );
+}
+
+function installDomGlobals(): void {
+  vi.stubGlobal("Node", window.Node);
+}
+
+function StartOnMount({ onError }: { onError: (value: unknown) => void }) {
+  const { start, status, error } = useEphia();
+  useEffect(() => {
+    const timer = setTimeout(() => {
+      start().catch(onError);
+    }, 0);
+    return () => clearTimeout(timer);
+  }, [onError, start]);
+  return <output data-testid="status" data-error-code={error?.code ?? ""}>{status}</output>;
+}
+
+function ForceIdleButton() {
+  const { store } = useEphiaContext();
+  useEffect(() => {
+    store.getState()._setStatus("idle");
+  }, [store]);
+  return <EphiaDictationButton />;
+}
+
+function DictationControl() {
+  const { status } = useEphia();
+  return (
+    <>
+      <EphiaDictationButton />
+      <output data-testid="status">{status}</output>
+    </>
+  );
+}
+
+function DictationControlWithTarget() {
+  return (
+    <>
+      <textarea data-ephia-target="report" data-ephia-insertion="preview-inline" />
+      <DictationControl />
+    </>
+  );
+}
+
+
+describe("useEphia lifecycle", () => {
+  afterEach(() => {
+    cleanup();
+    document.body.removeAttribute("data-ephia-session-active");
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+  });
+
+  it("rolls the React store to error when start fails", async () => {
+    installDomGlobals();
+    installBrowserAudioMocks();
+    installCreateSessionMock();
+    const onError = vi.fn();
+
+    render(
+      <EphiaProvider
+        apiUrl="https://api.test"
+        transport={new FailingPublishTransport({ autoEmitReady: false, latencyMs: 0 })}
+      >
+        <StartOnMount onError={onError} />
+      </EphiaProvider>
+    );
+
+    await waitFor(() => expect(onError).toHaveBeenCalled());
+    await waitFor(() => expect(screen.getByTestId("status").textContent).toBe("error"));
+    expect(screen.getByTestId("status").getAttribute("data-error-code")).toBe(
+      "audio.track_publish_failed"
+    );
+    await waitFor(() =>
+      expect(onError.mock.calls[0]?.[0]).toMatchObject({
+        code: "audio.track_publish_failed",
+      })
+    );
+  });
+
+  it("sets processing during start, then recording once the session is connected", async () => {
+    installDomGlobals();
+    const mic = installDeferredBrowserAudioMocks();
+    installCreateSessionMock();
+
+    render(
+      <EphiaProvider
+        apiUrl="https://api.test"
+        transport={new MockTransport({ autoEmitReady: false, latencyMs: 0 })}
+      >
+        <DictationControl />
+      </EphiaProvider>
+    );
+
+    await act(async () => {
+      screen.getByRole("button", { name: "Démarrer la dictée" }).click();
+    });
+
+    expect(screen.getByTestId("status").textContent).toBe("processing");
+    expect(
+      (screen.getByRole("button", { name: "Démarrer la dictée" }) as HTMLButtonElement)
+        .disabled
+    ).toBe(true);
+
+    await act(async () => {
+      mic.resolve(createMockMediaStream());
+    });
+    await waitFor(() => expect(screen.getByTestId("status").textContent).toBe("recording"));
+    expect(
+      (screen.getByRole("button", { name: "Arrêter la dictée" }) as HTMLButtonElement)
+        .disabled
+    ).toBe(false);
+  });
+
+  it("sets processing during stop and returns to idle after the microphone is unpublished", async () => {
+    installDomGlobals();
+    installBrowserAudioMocks();
+    installCreateSessionMock();
+    const unpublish = deferred<void>();
+    const transport = new PauseAckBlockingTransport({
+      autoEmitReady: false,
+      latencyMs: 0,
+    });
+    transport.blockUnpublishUntil(unpublish.promise);
+
+    render(
+      <EphiaProvider apiUrl="https://api.test" transport={transport}>
+        <DictationControl />
+      </EphiaProvider>
+    );
+
+    await act(async () => {
+      screen.getByRole("button", { name: "Démarrer la dictée" }).click();
+    });
+    await waitFor(() => expect(screen.getByTestId("status").textContent).toBe("recording"));
+
+    await act(async () => {
+      screen.getByRole("button", { name: "Arrêter la dictée" }).click();
+    });
+
+    await waitFor(() => expect(screen.getByTestId("status").textContent).toBe("processing"));
+    expect((screen.getByRole("button") as HTMLButtonElement).disabled).toBe(true);
+
+    await act(async () => {
+      unpublish.resolve();
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    });
+    await waitFor(() => expect(screen.getByTestId("status").textContent).toBe("idle"));
+  });
+
+
+
+  it("does not recreate client when sessionOptions reference changes but content is equal", async () => {
+    installDomGlobals();
+    installCreateSessionMock();
+
+    const disposeSpy = vi.spyOn(EphiaAudioClient.prototype, "dispose").mockResolvedValue(undefined);
+    let constructorCalls = 0;
+    const OriginalClient = EphiaAudioClient;
+    vi.spyOn(OriginalClient.prototype, "constructor" as never);
+    // Count instantiations by patching the constructor indirectly via a render counter.
+    // We use disposeSpy: dispose is called once per client teardown.
+
+    const stableTransport = new MockTransport();
+
+    function Wrapper() {
+      const [opts, setOpts] = useState({ mode: "smart_s" as const });
+      return (
+        <>
+          <button
+            data-testid="bump"
+            onClick={() => setOpts({ mode: "smart_s" })} // nouvelle ref, même contenu
+          />
+          <EphiaProvider
+            apiUrl="https://api.test"
+            transport={stableTransport}
+            options={{ sessionOptions: opts }}
+          >
+            <span data-testid="child" />
+          </EphiaProvider>
+        </>
+      );
+    }
+
+    render(<Wrapper />);
+    // Laisser le Provider monter (Strict Mode déclenche un dispose initial — ignoré)
+    await waitFor(() => expect(screen.getByTestId("child")).toBeTruthy());
+    disposeSpy.mockClear();
+
+    // Déclencher un re-render avec nouvelle référence mais même contenu
+    await act(async () => {
+      screen.getByTestId("bump").click();
+    });
+
+    // dispose ne doit pas avoir été appelé (le client n'est pas recréé)
+    expect(disposeSpy).not.toHaveBeenCalled();
+  });
+
+  it("keeps EphiaDictationButton enabled after idle", async () => {
+    installDomGlobals();
+    installCreateSessionMock();
+
+    render(
+      <EphiaProvider apiUrl="https://api.test" transport={new MockTransport()}>
+        <ForceIdleButton />
+      </EphiaProvider>
+    );
+
+    await waitFor(() => {
+      const button = screen.getByRole("button", {
+        name: "Démarrer la dictée",
+      }) as HTMLButtonElement;
+      expect(button.disabled).toBe(false);
+    });
+  });
+
+});