@ephia/dova-sdk 1.0.0

package/src/core/operations/textToDocumentOperations.ts

@@ -0,0 +1,92 @@
+/**
+ * P3 (post-P0 dictée) — conversion texte ↔ DocumentOperation[].
+ *
+ * Découpe un texte contenant des \n / \n\n structurels (déjà décidés par le
+ * backend — cf. merge_internal_layout côté ephia_transcribe_agent) en une
+ * séquence d'opérations neutres, consommable aussi bien par un binding riche
+ * (TipTap, cf. P4) qu'un consommateur plain-text/headless (documentOperationsToPlainText).
+ */
+import type {
+  DocumentOperation,
+  InsertTextOperation,
+  LineBreakOperation,
+  ParagraphBreakOperation,
+} from "ephia-protocol";
+
+function localUuid(): string {
+  const c = globalThis.crypto;
+  if (c?.randomUUID) return c.randomUUID();
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+
+export interface TextToDocumentOperationsOptions {
+  position?: number | "cursor" | "start" | "end";
+}
+
+/**
+ * \n  → LineBreakOperation
+ * \n\n (ou plus) → ParagraphBreakOperation
+ * reste → InsertTextOperation
+ */
+export function textToDocumentOperations(
+  text: string,
+  options?: TextToDocumentOperationsOptions
+): DocumentOperation[] {
+  const position = options?.position ?? "cursor";
+  const operations: DocumentOperation[] = [];
+
+  for (const part of text.split(/(\n+)/g)) {
+    if (!part) continue;
+    if (part[0] === "\n") {
+      if (part.length > 1) {
+        operations.push({
+          id: localUuid(),
+          type: "paragraph_break",
+          position,
+        } as ParagraphBreakOperation);
+      } else {
+        operations.push({
+          id: localUuid(),
+          type: "line_break",
+          position,
+        } as LineBreakOperation);
+      }
+    } else {
+      operations.push({
+        id: localUuid(),
+        type: "insert_text",
+        position,
+        text: part,
+      } as InsertTextOperation);
+    }
+  }
+
+  return operations;
+}
+
+/** Fonction inverse — round-trip sans perte avec textToDocumentOperations(),
+ * indispensable pour les consommateurs plain-text/headless qui n'ont pas de
+ * binding riche capable d'interpréter line_break/paragraph_break nativement. */
+export function documentOperationsToPlainText(operations: DocumentOperation[]): string {
+  let out = "";
+  for (const operation of operations) {
+    switch (operation.type) {
+      case "insert_text":
+      case "insert":
+        out += operation.text;
+        break;
+      case "line_break":
+        out += "\n";
+        break;
+      case "paragraph_break":
+        out += "\n\n";
+        break;
+      default:
+        // Les opérations de remplacement/section/highlight n'ont pas de
+        // représentation texte-plat universelle — ignorées ici, gérées par
+        // le store headless qui les interprète (cf. P3, plan post-P0).
+        break;
+    }
+  }
+  return out;
+}

package/src/core/runtime/DictationRuntime.test.ts

@@ -0,0 +1,578 @@
+// @vitest-environment jsdom
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { EphiaAudioEvent } from "ephia-protocol";
+import type { TargetBinding } from "../bindings/TargetBinding";
+import {
+  DictationRuntime,
+  type DictationPartialState,
+  type DictationTarget,
+  type DictationTargetInsertionMode,
+  type DictationTargetRegistry,
+  type DictationRuntimeStatus,
+} from "./DictationRuntime";
+
+type BindingCall =
+  | ["insertPartial", string, string, number]
+  | ["commitFinal", string, string, unknown]
+  | ["clearPartial", string]
+  | ["clearAll"];
+
+function event(type: string, payload: Record<string, unknown> = {}): EphiaAudioEvent {
+  return { type, payload } as unknown as EphiaAudioEvent;
+}
+
+function createBinding(): TargetBinding & { calls: BindingCall[] } {
+  const calls: BindingCall[] = [];
+  return {
+    kind: "test",
+    calls,
+    attach: vi.fn(),
+    detach: vi.fn(),
+    beginSession: vi.fn(),
+    endSession: vi.fn(),
+    insertPartial: vi.fn((segmentId: string, text: string, revision: number) => {
+      calls.push(["insertPartial", segmentId, text, revision]);
+    }),
+    commitFinal: vi.fn((segmentId: string, text: string, options?: unknown) => {
+      calls.push(["commitFinal", segmentId, text, options]);
+    }),
+    clearPartial: vi.fn((segmentId: string) => {
+      calls.push(["clearPartial", segmentId]);
+    }),
+    clearAll: vi.fn(() => {
+      calls.push(["clearAll"]);
+    }),
+    getText: vi.fn(() => ""),
+    getSegmentRange: vi.fn(() => ({ start: 1, end: 5 })),
+    getRangeRect: vi.fn(),
+    applyOperation: vi.fn(),
+  };
+}
+
+class RuntimeHarness {
+  activeTargetId: string | null = "report";
+  status: DictationRuntimeStatus = "recording";
+  partial: DictationPartialState | null = null;
+  error: { code: string; message: string } | null = null;
+  resetCalls: Array<{ waitForAck?: boolean } | undefined> = [];
+  flashCalls: Array<[TargetBinding, number, number, "revised" | "committed" | undefined]> = [];
+  readonly reportBinding = createBinding();
+  readonly otherBinding = createBinding();
+  readonly noneBinding = createBinding();
+  readonly targets = new Map<string, DictationTarget>();
+  readonly runtime: DictationRuntime;
+
+  constructor(voiceFormatting?: { mode: "none" | "dictation" }) {
+    this.targets.set("report", this.createTarget("report", "preview-inline", this.reportBinding));
+    this.targets.set("other", this.createTarget("other", "preview-inline", this.otherBinding));
+    this.targets.set("none", this.createTarget("none", "none", this.noneBinding));
+
+    const registry: DictationTargetRegistry = {
+      get: (id) => this.targets.get(id),
+      getActiveTargetId: () => this.activeTargetId,
+      getActiveTarget: () => (this.activeTargetId ? this.targets.get(this.activeTargetId) : undefined),
+    };
+
+    this.runtime = new DictationRuntime({
+      registry,
+      getStatus: () => this.status,
+      setPartial: (partial) => {
+        this.partial = partial;
+      },
+      setError: (error) => {
+        this.error = error;
+      },
+      setStatus: (status) => {
+        this.status = status;
+      },
+      resetSessionContext: async (options) => {
+        this.resetCalls.push(options);
+      },
+      flashRange: (binding, start, end, variant) => {
+        this.flashCalls.push([binding, start, end, variant]);
+      },
+      voiceFormatting,
+    });
+  }
+
+  private createTarget(
+    id: string,
+    insertion: DictationTargetInsertionMode,
+    binding: TargetBinding
+  ): DictationTarget {
+    const element = document.createElement("div");
+    element.dataset.targetId = id;
+    document.body.appendChild(element);
+    return { id, insertion, binding, element };
+  }
+}
+
+describe("DictationRuntime", () => {
+  beforeEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("routes previews to the active target and keeps the segment mapping", () => {
+    const h = new RuntimeHarness();
+
+    h.runtime.handleEvent(event("transcript.preview", {
+      segmentId: "s1",
+      text: "Bonjour",
+      revision: 1,
+    }));
+
+    expect(h.partial).toEqual({ targetId: "report", text: "Bonjour", segmentId: "s1" });
+    expect(h.reportBinding.calls).toContainEqual(["insertPartial", "s1", "Bonjour", 1]);
+    expect(h.targets.get("report")?.element.getAttribute("data-ephia-target-processing")).toBe("true");
+
+    h.runtime.handleEvent(event("transcript.segment.committed", {
+      segmentId: "s1",
+      text: "Bonjour corrigé",
+      source: "live",
+    }));
+
+    expect(h.reportBinding.calls).toContainEqual(["commitFinal", "s1", "Bonjour corrigé", undefined]);
+    expect(h.otherBinding.calls).toHaveLength(0);
+  });
+
+  it("commits merged segments with absorbed ids and clears absorbed mappings", () => {
+    const h = new RuntimeHarness();
+    h.runtime.handleEvent(event("transcript.preview", { segmentId: "s1", text: "Bonjour", revision: 1 }));
+    h.runtime.handleEvent(event("transcript.preview", { segmentId: "s2", text: "parasite", revision: 1 }));
+
+    h.runtime.handleEvent(event("transcript.segment.committed", {
+      segmentId: "s1",
+      text: "Bonjour.",
+      mergedWith: ["s2"],
+      source: "live",
+    }));
+
+    expect(h.partial).toBeNull();
+    expect(h.reportBinding.calls).toContainEqual([
+      "commitFinal",
+      "s1",
+      "Bonjour.",
+      { absorbedSegmentIds: ["s2"] },
+    ]);
+    expect(h.flashCalls).toHaveLength(1);
+
+  });
+
+  it("clears preview and resets backend context on user interrupt", async () => {
+    const h = new RuntimeHarness();
+    const target = h.targets.get("report")!;
+    target.element.appendChild(document.createElement("span"));
+    const child = target.element.firstChild!;
+
+    h.runtime.handleEvent(event("transcript.preview", {
+      segmentId: "s1",
+      text: "preview",
+      revision: 1,
+    }));
+    h.runtime.handleUserInteraction(new KeyboardEvent("keydown", { key: "a", bubbles: true }));
+    expect(h.resetCalls).toHaveLength(0);
+
+    child.dispatchEvent(new KeyboardEvent("keydown", { key: "a", bubbles: true }));
+    h.runtime.handleUserInteraction(new KeyboardEvent("keydown", { key: "a", bubbles: true }));
+    expect(h.reportBinding.calls).not.toContainEqual(["clearAll"]);
+
+    const domEvent = new KeyboardEvent("keydown", { key: "a", bubbles: true });
+    Object.defineProperty(domEvent, "target", { value: child });
+    h.runtime.handleUserInteraction(domEvent);
+    await Promise.resolve();
+
+    expect(h.partial).toBeNull();
+    expect(h.reportBinding.calls).toContainEqual(["clearAll"]);
+    expect(h.resetCalls).toEqual([{ waitForAck: false }]);
+    expect(target.element.hasAttribute("data-ephia-target-processing")).toBe(false);
+  });
+
+  it("respects final-only and none insertion modes", () => {
+    const h = new RuntimeHarness();
+    h.targets.set("report", {
+      ...h.targets.get("report")!,
+      insertion: "final-only",
+    });
+
+    h.runtime.handleEvent(event("transcript.preview", {
+      segmentId: "s1",
+      text: "preview",
+      revision: 1,
+    }));
+    expect(h.partial?.text).toBe("preview");
+    expect(h.reportBinding.calls).not.toContainEqual(["insertPartial", "s1", "preview", 1]);
+
+    h.runtime.handleEvent(event("transcript.segment.committed", {
+      segmentId: "s1",
+      text: "final",
+    }));
+    expect(h.reportBinding.calls).toContainEqual(["commitFinal", "s1", "final", undefined]);
+
+    h.activeTargetId = "none";
+    h.runtime.handleEvent(event("transcript.preview", {
+      segmentId: "s2",
+      text: "none preview",
+      revision: 1,
+    }));
+    h.runtime.handleEvent(event("transcript.segment.committed", {
+      segmentId: "s2",
+      text: "none final",
+    }));
+    expect(h.noneBinding.calls).toHaveLength(0);
+  });
+
+  it("ignores late transcript events after session closed until a new ready event", () => {
+    const h = new RuntimeHarness();
+
+    h.runtime.handleEvent(event("transcript.preview", { segmentId: "s1", text: "preview", revision: 1 }));
+    h.runtime.handleEvent(event("session.closed"));
+    h.runtime.handleEvent(event("transcript.segment.committed", { segmentId: "s1", text: "late" }));
+
+    expect(h.reportBinding.calls).not.toContainEqual(["commitFinal", "s1", "late", undefined]);
+
+    h.runtime.handleEvent(event("session.ready"));
+    h.runtime.handleEvent(event("transcript.preview", { segmentId: "s2", text: "new", revision: 1 }));
+
+    expect(h.reportBinding.calls).toContainEqual(["insertPartial", "s2", "new", 1]);
+  });
+
+  it("clears only in-flight partial (not committed text) on reset, and clears visual state attributes", () => {
+    const h = new RuntimeHarness();
+    const target = h.targets.get("report")!;
+
+    h.runtime.handleEvent(event("transcript.preview", {
+      segmentId: "s1",
+      text: "preview",
+      revision: 1,
+    }));
+    expect(target.element.getAttribute("data-ephia-target-processing")).toBe("true");
+
+    h.runtime.handleEvent(event("session.context.reset"));
+    expect(h.partial).toBeNull();
+    expect(h.reportBinding.calls).toContainEqual(["clearPartial", "s1"]);
+    expect(h.reportBinding.calls).not.toContainEqual(["clearAll"]);
+    expect(target.element.hasAttribute("data-ephia-target-processing")).toBe(false);
+
+    h.runtime.handleEvent(event("transcript.preview", {
+      segmentId: "s2",
+      text: "preview erreur",
+      revision: 1,
+    }));
+    h.runtime.handleEvent(event("transcript.segment.error", {
+      segmentId: "s2",
+      code: "backend.error",
+      message: "Erreur",
+      recoverable: true,
+    }));
+    expect(h.reportBinding.calls).toContainEqual(["clearPartial", "s2"]);
+    expect(target.element.hasAttribute("data-ephia-target-processing")).toBe(false);
+
+    h.runtime.handleEvent(event("transcript.preview", {
+      segmentId: "s3",
+      text: "preview session error",
+      revision: 1,
+    }));
+    h.runtime.handleEvent(event("session.error", {
+      code: "session.error",
+      message: "Session error",
+    }));
+    expect(h.partial).toBeNull();
+    expect(h.error).toEqual({ code: "session.error", message: "Session error" });
+    expect(h.status).toBe("error");
+    expect(target.element.hasAttribute("data-ephia-target-processing")).toBe(false);
+  });
+
+  it("normalizes committed text in dictation mode", () => {
+    const h = new RuntimeHarness({ mode: "dictation" });
+
+    h.runtime.handleEvent(event("transcript.segment.committed", {
+      segmentId: "s1",
+      text: "rein à la ligne normal",
+    }));
+
+    expect(h.reportBinding.calls).toContainEqual([
+      "commitFinal",
+      "s1",
+      "rein \nNormal",
+      undefined,
+    ]);
+  });
+
+  it("leaves committed text unchanged when voice formatting mode is none", () => {
+    const h = new RuntimeHarness({ mode: "none" });
+
+    h.runtime.handleEvent(event("transcript.segment.committed", {
+      segmentId: "s1",
+      text: "rein virgule normal",
+    }));
+
+    expect(h.reportBinding.calls).toContainEqual([
+      "commitFinal",
+      "s1",
+      "rein virgule normal",
+      undefined,
+    ]);
+  });
+
+  it("does not call clearAll on binding after session.context.reset — committed text must survive", () => {
+    const h = new RuntimeHarness();
+
+    h.runtime.handleEvent(event("transcript.segment.committed", { segmentId: "s1", text: "texte dicté" }));
+    const callsBeforeReset = h.reportBinding.calls.length;
+
+    h.runtime.handleEvent(event("session.context.reset"));
+
+    const newCalls = h.reportBinding.calls.slice(callsBeforeReset);
+    expect(newCalls).not.toContainEqual(["clearAll"]);
+  });
+
+  describe("RealtimeCommitGate", () => {
+    beforeEach(() => {
+      vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    it("does not commit a realtime_final immediately when correctionPending is true", () => {
+      const h = new RuntimeHarness();
+
+      h.runtime.handleEvent(event("transcript.segment.committed", {
+        segmentId: "s1",
+        text: "mauvais début",
+        source: "dova-real-time",
+        correctionPending: true,
+      }));
+
+      expect(h.reportBinding.calls).not.toContainEqual(["commitFinal", "s1", "mauvais début", undefined]);
+    });
+
+    it("commits the Small correction directly when it arrives before the hold expires, discarding the realtime text", () => {
+      const h = new RuntimeHarness();
+
+      h.runtime.handleEvent(event("transcript.segment.committed", {
+        segmentId: "s1",
+        text: "mauvais début",
+        source: "dova-real-time",
+        correctionPending: true,
+      }));
+
+      vi.advanceTimersByTime(100);
+
+      h.runtime.handleEvent(event("transcript.segment.committed", {
+        segmentId: "s1",
+        text: "Bon début corrigé.",
+        source: "dova-medical",
+        corrected: true,
+      }));
+
+      const commitCalls = h.reportBinding.calls.filter((c) => c[0] === "commitFinal");
+      expect(commitCalls).toEqual([["commitFinal", "s1", "Bon début corrigé.", undefined]]);
+
+      // Le timer du realtime ne doit pas committer une seconde fois plus tard.
+      vi.advanceTimersByTime(1000);
+      expect(h.reportBinding.calls.filter((c) => c[0] === "commitFinal")).toHaveLength(1);
+    });
+
+    it("sends Small final as a revision of the same realtime segmentId after realtime hold", () => {
+      const h = new RuntimeHarness();
+
+      h.runtime.handleEvent(event("transcript.segment.committed", {
+        segmentId: "efde10b0",
+        text: "\nTechnique :\nacquisition",
+        source: "dova-real-time",
+        correctionPending: true,
+      }));
+
+      vi.advanceTimersByTime(200);
+
+      h.runtime.handleEvent(event("transcript.segment.committed", {
+        segmentId: "efde10b0",
+        text: "\nTechnique :\nacquisition hélicoïdale.",
+        textForInsertion: "\nTechnique :\nacquisition hélicoïdale.",
+        source: "dova-medical",
+        corrected: true,
+        correctionPending: false,
+      }));
+
+      expect(h.reportBinding.calls.filter((c) => c[0] === "commitFinal")).toEqual([
+        ["commitFinal", "efde10b0", "\nTechnique :\nacquisition", undefined],
+        ["commitFinal", "efde10b0", "\nTechnique :\nacquisition hélicoïdale.", undefined],
+      ]);
+    });
+
+    it("does not insert an absorbed segment when a merge arrives before its realtime hold expires", () => {
+      const h = new RuntimeHarness();
+
+      h.runtime.handleEvent(event("transcript.segment.committed", {
+        segmentId: "s7",
+        text: "amincissement des parois adjacentes.",
+        source: "dova-real-time",
+        correctionPending: true,
+      }));
+
+      h.runtime.handleEvent(event("transcript.segment.committed", {
+        segmentId: "s6",
+        text: "avec aspect inflammatoire et amincissement des parois adjacentes.",
+        source: "dova-medical",
+        corrected: true,
+        mergedWith: ["s7"],
+      }));
+
+      vi.advanceTimersByTime(1000);
+
+      const commitCalls = h.reportBinding.calls.filter((c) => c[0] === "commitFinal");
+      expect(commitCalls).toEqual([[
+        "commitFinal",
+        "s6",
+        "avec aspect inflammatoire et amincissement des parois adjacentes.",
+        { absorbedSegmentIds: ["s7"] },
+      ]]);
+    });
+
+    it("ignores a later commit for a segment already absorbed by a merge", () => {
+      const h = new RuntimeHarness();
+
+      h.runtime.handleEvent(event("transcript.segment.committed", {
+        segmentId: "s6",
+        text: "texte fusionné",
+        source: "dova-medical",
+        mergedWith: ["s7"],
+      }));
+
+      h.runtime.handleEvent(event("transcript.segment.committed", {
+        segmentId: "s7",
+        text: "texte absorbé tardif",
+        source: "dova-medical",
+      }));
+
+      const commitCalls = h.reportBinding.calls.filter((c) => c[0] === "commitFinal");
+      expect(commitCalls).toEqual([[
+        "commitFinal",
+        "s6",
+        "texte fusionné",
+        { absorbedSegmentIds: ["s7"] },
+      ]]);
+    });
+
+    it("falls back to committing the realtime text after the hold timeout if nothing else arrives", () => {
+      const h = new RuntimeHarness();
+
+      h.runtime.handleEvent(event("transcript.segment.committed", {
+        segmentId: "s1",
+        text: "texte realtime",
+        source: "dova-real-time",
+        correctionPending: true,
+      }));
+
+      expect(h.reportBinding.calls).toHaveLength(0);
+
+      vi.advanceTimersByTime(850);
+
+      expect(h.reportBinding.calls).toContainEqual(["commitFinal", "s1", "texte realtime", undefined]);
+    });
+
+    it("cancels the pending hold on clear()", () => {
+      const h = new RuntimeHarness();
+
+      h.runtime.handleEvent(event("transcript.segment.committed", {
+        segmentId: "s1",
+        text: "texte realtime",
+        source: "dova-real-time",
+        correctionPending: true,
+      }));
+
+      h.runtime.clear();
+      vi.advanceTimersByTime(2000);
+
+      expect(h.reportBinding.calls).toHaveLength(0);
+    });
+
+    it("cancels the pending hold on session.closed", () => {
+      const h = new RuntimeHarness();
+
+      h.runtime.handleEvent(event("transcript.segment.committed", {
+        segmentId: "s1",
+        text: "texte realtime",
+        source: "dova-real-time",
+        correctionPending: true,
+      }));
+
+      h.runtime.handleEvent(event("session.closed"));
+      vi.advanceTimersByTime(2000);
+
+      expect(h.reportBinding.calls).not.toContainEqual(["commitFinal", "s1", "texte realtime", undefined]);
+    });
+
+    it("cancels the pending hold when the segment is dropped", () => {
+      const h = new RuntimeHarness();
+
+      h.runtime.handleEvent(event("transcript.segment.committed", {
+        segmentId: "s1",
+        text: "texte realtime",
+        source: "dova-real-time",
+        correctionPending: true,
+      }));
+
+      h.runtime.handleEvent(event("segment.dropped", { segmentId: "s1" }));
+      vi.advanceTimersByTime(2000);
+
+      expect(h.reportBinding.calls).not.toContainEqual(["commitFinal", "s1", "texte realtime", undefined]);
+    });
+  });
+
+  it("uses textForInsertion instead of full committed text", () => {
+    const h = new RuntimeHarness();
+
+    h.runtime.handleEvent(event("transcript.segment.committed", {
+      segmentId: "s-insert",
+      text: "Le foie est homogène.",
+      textForInsertion: "homogène.",
+      source: "dova-medical",
+    }));
+
+    expect(h.reportBinding.calls).toContainEqual([
+      "commitFinal",
+      "s-insert",
+      "homogène.",
+      undefined,
+    ]);
+  });
+
+  it("routes backend-targeted finals to their original target instead of the active target", () => {
+    const h = new RuntimeHarness();
+    h.activeTargetId = "other";
+
+    h.runtime.handleEvent(event("transcript.segment.committed", {
+      segmentId: "s-target",
+      targetId: "report",
+      text: "Texte cible.",
+      source: "dova-medical",
+    }));
+
+    expect(h.reportBinding.calls).toContainEqual([
+      "commitFinal",
+      "s-target",
+      "Texte cible.",
+      undefined,
+    ]);
+    expect(h.otherBinding.calls).toHaveLength(0);
+  });
+
+  it("drops backend-targeted finals for unknown targets instead of using the active target", () => {
+    const h = new RuntimeHarness();
+    h.activeTargetId = "other";
+
+    h.runtime.handleEvent(event("transcript.segment.committed", {
+      segmentId: "s-missing-target",
+      targetId: "missing",
+      text: "Ne pas insérer",
+      source: "dova-medical",
+    }));
+
+    expect(h.reportBinding.calls).toHaveLength(0);
+    expect(h.otherBinding.calls).toHaveLength(0);
+  });
+});