@ephia/dova-sdk 1.0.0

package/src/core/targets/EditorContextCollector.ts

@@ -0,0 +1,71 @@
+import type { EditorContext } from "ephia-protocol";
+import type { TargetBinding } from "../bindings/TargetBinding";
+
+export type EditorContextCollectorOptions = {
+  maxContextChars?: number;
+};
+
+export type EditorContextTarget = {
+  id: string;
+  binding: Pick<TargetBinding, "getText" | "getSelection" | "getCursorOffset"> | null;
+};
+
+type SelectionSnapshot = {
+  text: string;
+  range: {
+    start: number;
+    end: number;
+  };
+} | null;
+
+export class EditorContextCollector {
+  private readonly maxContextChars: number;
+
+  constructor(options: EditorContextCollectorOptions = {}) {
+    this.maxContextChars = options.maxContextChars ?? 600;
+  }
+
+  collect(target: EditorContextTarget): EditorContext {
+    const text = target.binding?.getText?.() ?? "";
+    const selection = target.binding?.getSelection?.() ?? null;
+    const cursorOffset = this.resolveCursorOffset(target.binding, text, selection);
+    const leftRaw = text.slice(0, cursorOffset);
+    const rightRaw = text.slice(cursorOffset);
+
+    return {
+      targetId: target.id,
+      documentEmpty: text.trim().length === 0,
+      insertionMode: this.resolveInsertionMode(text, cursorOffset, selection),
+      leftContext: leftRaw.slice(-this.maxContextChars),
+      rightContext: rightRaw.slice(0, this.maxContextChars),
+      selectedText: selection?.text || null,
+      cursorOffset,
+    };
+  }
+
+  private resolveCursorOffset(
+    binding: EditorContextTarget["binding"],
+    text: string,
+    selection: SelectionSnapshot
+  ): number {
+    if (selection?.range) return clamp(selection.range.start, 0, text.length);
+    const cursor = binding?.getCursorOffset?.();
+    if (typeof cursor === "number") return clamp(cursor, 0, text.length);
+    return text.length;
+  }
+
+  private resolveInsertionMode(
+    text: string,
+    cursorOffset: number,
+    selection: SelectionSnapshot
+  ): EditorContext["insertionMode"] {
+    if (selection?.text) return "replace_selection";
+    if (text.trim().length === 0) return "document_start";
+    if (cursorOffset >= text.length) return "append";
+    return "middle_of_sentence";
+  }
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}

package/src/core/targets/TargetManager.test.ts

@@ -0,0 +1,194 @@
+import { describe, expect, it, vi } from "vitest";
+import type { TargetBinding } from "../bindings/TargetBinding";
+import type { EphiaBinding } from "../bindings/EphiaBinding";
+import { EditorContextCollector } from "./EditorContextCollector";
+import { TargetManager } from "./TargetManager";
+
+// ── EditorContextCollector tests (standalone utility, kept as-is) ──────────
+
+function legacyBinding(overrides: Partial<TargetBinding> = {}): TargetBinding {
+  return {
+    kind: "test",
+    attach: vi.fn(),
+    detach: vi.fn(),
+    insertPartial: vi.fn(),
+    commitFinal: vi.fn(),
+    clearPartial: vi.fn(),
+    getText: () => "Le patient presente une douleur.",
+    getSelection: () => null,
+    getCursorOffset: () => 10,
+    applyOperation: vi.fn(),
+    ...overrides,
+  };
+}
+
+describe("EditorContextCollector", () => {
+  it("collects bounded camelCase editor context", () => {
+    const collector = new EditorContextCollector({ maxContextChars: 8 });
+    const context = collector.collect({
+      id: "report",
+      binding: legacyBinding({
+        getText: () => "abcdef gauche|droite zzz",
+        getCursorOffset: () => 13,
+      }),
+    });
+
+    expect(context).toMatchObject({
+      targetId: "report",
+      documentEmpty: false,
+      insertionMode: "middle_of_sentence",
+      leftContext: "f gauche",
+      rightContext: "|droite ",
+      cursorOffset: 13,
+    });
+  });
+
+  it("uses replace_selection when text is selected", () => {
+    const collector = new EditorContextCollector();
+    const context = collector.collect({
+      id: "report",
+      binding: legacyBinding({
+        getSelection: () => ({ text: "douleur", range: { start: 3, end: 10 } }),
+      }),
+    });
+
+    expect(context.insertionMode).toBe("replace_selection");
+    expect(context.selectedText).toBe("douleur");
+    expect(context.cursorOffset).toBe(3);
+  });
+});
+
+// ── TargetManager tests (uses EphiaBinding) ────────────────────────────────
+
+function binding(overrides: Partial<EphiaBinding> = {}): EphiaBinding {
+  return {
+    kind: "test",
+    attach: vi.fn(),
+    detach: vi.fn(),
+    getText: () => "Le patient presente une douleur.",
+    getEditorContext: (targetId = "") => ({
+      targetId,
+      documentEmpty: false,
+      insertionMode: "middle_of_sentence" as const,
+      leftContext: "Le patient",
+      rightContext: " presente",
+      selectedText: null,
+      cursorOffset: 10,
+    }),
+    previewSegment: vi.fn(),
+    upsertSegment: vi.fn(),
+    removeSegment: vi.fn(),
+    removeSegments: vi.fn(),
+    ...overrides,
+  };
+}
+
+describe("TargetManager", () => {
+  it("sends target change and editor context updates", () => {
+    vi.useFakeTimers();
+    const sendMessage = vi.fn(async () => undefined);
+    const manager = new TargetManager({ sendMessage, flushDelayMs: 10 });
+
+    manager.register({ id: "report", binding: binding(), mode: "write" });
+    vi.runAllTimers();
+
+    expect(sendMessage).toHaveBeenCalledWith({
+      type: "session.target.changed",
+      payload: { targetId: "report" },
+    });
+    expect(sendMessage).toHaveBeenCalledWith({
+      type: "session.editor_context.update",
+      payload: expect.objectContaining({
+        targetId: "report",
+        insertionMode: "middle_of_sentence",
+      }),
+    });
+    vi.useRealTimers();
+  });
+
+  it("syncs the latest active target on demand", () => {
+    const sendMessage = vi.fn(async () => undefined);
+    const manager = new TargetManager({ sendMessage, flushDelayMs: 10 });
+    manager.register({ id: "report", binding: binding(), mode: "write" });
+    sendMessage.mockClear();
+
+    manager.syncActiveTarget();
+
+    expect(sendMessage).toHaveBeenCalledWith({
+      type: "session.target.changed",
+      payload: { targetId: "report" },
+    });
+    expect(sendMessage).toHaveBeenCalledWith({
+      type: "session.editor_context.update",
+      payload: expect.objectContaining({ targetId: "report" }),
+    });
+  });
+
+  it("register returns a token and unregister with wrong token is a no-op", () => {
+    const sendMessage = vi.fn(async () => undefined);
+    const manager = new TargetManager({ sendMessage, flushDelayMs: 10 });
+
+    manager.register({ id: "report", binding: binding(), mode: "write" });
+    const staleToken = Symbol("stale");
+
+    // Unregister with wrong token — should be ignored.
+    const removed = manager.unregister("report", staleToken);
+    expect(removed).toBe(false);
+    expect(manager.get("report")).toBeDefined();
+  });
+
+  it("unregister with correct token removes the target", () => {
+    const sendMessage = vi.fn(async () => undefined);
+    const manager = new TargetManager({ sendMessage, flushDelayMs: 10 });
+
+    const token = manager.register({ id: "report", binding: binding(), mode: "write" });
+    const removed = manager.unregister("report", token);
+
+    expect(removed).toBe(true);
+    expect(manager.get("report")).toBeUndefined();
+  });
+
+  it("newer registration is not removed by stale token from older registration", () => {
+    const sendMessage = vi.fn(async () => undefined);
+    const manager = new TargetManager({ sendMessage, flushDelayMs: 10 });
+
+    const oldToken = manager.register({ id: "report", binding: binding(), mode: "write" });
+    // Simulate remount: same id is re-registered with a new binding.
+    manager.register({ id: "report", binding: binding(), mode: "write" });
+
+    // Stale cleanup from old mount — should not remove the new registration.
+    const removed = manager.unregister("report", oldToken);
+    expect(removed).toBe(false);
+    expect(manager.get("report")).toBeDefined();
+  });
+
+  it("unregister without token removes unconditionally (legacy behavior)", () => {
+    const sendMessage = vi.fn(async () => undefined);
+    const manager = new TargetManager({ sendMessage, flushDelayMs: 10 });
+
+    manager.register({ id: "report", binding: binding(), mode: "write" });
+    const removed = manager.unregister("report");
+
+    expect(removed).toBe(true);
+    expect(manager.get("report")).toBeUndefined();
+  });
+
+  it("preserves reset reason and scope", () => {
+    const sendMessage = vi.fn(async () => undefined);
+    const manager = new TargetManager({ sendMessage, flushDelayMs: 10 });
+    manager.register({ id: "report", binding: binding(), mode: "write" });
+    sendMessage.mockClear();
+
+    manager.reset("target", "report", "manual_edit");
+    manager.reset("global", undefined, "editor_empty");
+
+    expect(sendMessage).toHaveBeenCalledWith({
+      type: "session.reset",
+      payload: { scope: "target", targetId: "report", reason: "manual_edit" },
+    });
+    expect(sendMessage).toHaveBeenCalledWith({
+      type: "session.reset",
+      payload: { scope: "global", reason: "editor_empty" },
+    });
+  });
+});

package/src/core/targets/TargetManager.ts

@@ -0,0 +1,194 @@
+import type { EphiaClientMessage, ResetReason } from "ephia-protocol";
+import type { EphiaBinding } from "../bindings/EphiaBinding";
+
+type WireClientMessage = EphiaClientMessage | {
+  type: string;
+  payload?: Record<string, unknown>;
+};
+
+export type ManagedTarget = {
+  id: string;
+  binding: EphiaBinding | null;
+  element?: HTMLElement;
+  mode?: string;
+};
+
+/** Internal stored target — extends ManagedTarget with a registration token. */
+type StoredTarget = ManagedTarget & { token: symbol };
+
+export type TargetManagerOptions = {
+  sendMessage: (message: WireClientMessage) => Promise<void>;
+  flushDelayMs?: number;
+  onActiveTargetChange?: (targetId: string | null) => void;
+  onTargetRegistered?: (targetId: string) => void;
+};
+
+export class TargetManager {
+  private readonly targets = new Map<string, StoredTarget>();
+  private readonly sendMessage: TargetManagerOptions["sendMessage"];
+  private readonly flushDelayMs: number;
+  private readonly onActiveTargetChange?: (targetId: string | null) => void;
+  private readonly onTargetRegistered?: (targetId: string) => void;
+  private activeTargetId: string | null = null;
+  private flushTimers = new Map<string, ReturnType<typeof setTimeout>>();
+
+  constructor(options: TargetManagerOptions) {
+    this.sendMessage = options.sendMessage;
+    this.flushDelayMs = options.flushDelayMs ?? 80;
+    this.onActiveTargetChange = options.onActiveTargetChange;
+    this.onTargetRegistered = options.onTargetRegistered;
+  }
+
+  /**
+   * Register a target and return its registration token.
+   * Pass the token to unregister() to prevent stale cleanups from accidentally
+   * removing a newer registration with the same id (React StrictMode / remounts).
+   */
+  register(target: ManagedTarget): symbol {
+    const token = Symbol(target.id);
+    this.targets.set(target.id, { ...target, token });
+    if (this.activeTargetId === null && target.mode !== "read") {
+      this.setActive(target.id);
+    }
+    this.onTargetRegistered?.(target.id);
+    return token;
+  }
+
+  /**
+   * Unregister a target.
+   * When `token` is provided, only unregisters if the stored token matches
+   * (prevents a stale cleanup from removing a newer registration).
+   * Returns true if the target was removed, false if skipped.
+   */
+  unregister(targetId: string, token?: symbol): boolean {
+    const current = this.targets.get(targetId);
+    if (!current) return false;
+
+    if (token !== undefined && current.token !== token) {
+      // Token mismatch — a newer registration owns this id, skip.
+      return false;
+    }
+
+    this.targets.delete(targetId);
+    this.clearFlush(targetId);
+    if (this.activeTargetId === targetId) {
+      const next = this.firstWritableTargetId();
+      this.activeTargetId = null;
+      if (next) {
+        this.setActive(next);
+      } else {
+        this.onActiveTargetChange?.(null);
+      }
+    }
+    return true;
+  }
+
+  get(targetId: string): ManagedTarget | undefined {
+    return this.targets.get(targetId);
+  }
+
+  getActiveTargetId(): string | null {
+    return this.activeTargetId;
+  }
+
+  getActiveTarget(): ManagedTarget | undefined {
+    return this.activeTargetId ? this.targets.get(this.activeTargetId) : undefined;
+  }
+
+  setActive(targetId: string): void {
+    if (!this.targets.has(targetId)) return;
+    if (this.activeTargetId === targetId) {
+      this.scheduleEditorContextFlush(targetId);
+      return;
+    }
+    this.activeTargetId = targetId;
+    this.onActiveTargetChange?.(targetId);
+    this.send({
+      type: "session.target.changed",
+      payload: { targetId },
+    });
+    this.scheduleEditorContextFlush(targetId);
+  }
+
+  syncActiveTarget(): void {
+    if (!this.activeTargetId) return;
+    this.send({
+      type: "session.target.changed",
+      payload: { targetId: this.activeTargetId },
+    });
+    this.flushEditorContext(this.activeTargetId);
+  }
+
+  /** Resync native bindings from current DOM before dictation (manual edits between sessions). */
+  prepareForDictation(targetId = this.activeTargetId): void {
+    if (!targetId) return;
+    const binding = this.targets.get(targetId)?.binding;
+    if (binding?.kind === "native" && "prepareForDictation" in binding) {
+      (binding as { prepareForDictation: () => void }).prepareForDictation();
+    }
+  }
+
+  flushEditorContext(targetId = this.activeTargetId): void {
+    if (!targetId) return;
+    this.clearFlush(targetId);
+    const target = this.targets.get(targetId);
+    if (!target?.binding) return;
+    const context = target.binding.getEditorContext(target.id);
+    this.send({
+      type: "session.editor_context.update",
+      payload: context,
+    });
+  }
+
+  scheduleEditorContextFlush(targetId = this.activeTargetId): void {
+    if (!targetId) return;
+    this.clearFlush(targetId);
+    const timer = setTimeout(() => {
+      this.flushTimers.delete(targetId);
+      this.flushEditorContext(targetId);
+    }, this.flushDelayMs);
+    this.flushTimers.set(targetId, timer);
+  }
+
+  reset(
+    scope: "global" | "target",
+    targetId = this.activeTargetId,
+    reason: ResetReason = "user_explicit"
+  ): void {
+    this.send({
+      type: "session.reset",
+      payload:
+        scope === "target" && targetId
+          ? { scope: "target", targetId, reason }
+          : { scope: "global", reason },
+    });
+  }
+
+  dispose(): void {
+    for (const targetId of this.flushTimers.keys()) {
+      this.clearFlush(targetId);
+    }
+    this.targets.clear();
+    this.activeTargetId = null;
+  }
+
+  private firstWritableTargetId(): string | null {
+    for (const target of this.targets.values()) {
+      if (target.mode !== "read") return target.id;
+    }
+    return null;
+  }
+
+  private clearFlush(targetId: string): void {
+    const timer = this.flushTimers.get(targetId);
+    if (timer) clearTimeout(timer);
+    this.flushTimers.delete(targetId);
+  }
+
+  private send(message: WireClientMessage): void {
+    this.sendMessage(message).catch(() => {
+      // The manager can be mounted before the LiveKit room is connected.
+      // A session-active resync flushes the latest active target/context.
+    });
+  }
+}

package/src/core/targets/index.ts

@@ -0,0 +1,10 @@
+export {
+  EditorContextCollector,
+  type EditorContextCollectorOptions,
+  type EditorContextTarget,
+} from "./EditorContextCollector";
+export {
+  TargetManager,
+  type ManagedTarget,
+  type TargetManagerOptions,
+} from "./TargetManager";

package/src/core/text-processing/index.ts

@@ -0,0 +1,11 @@
+export {
+  stripLeadingOverlapFromText,
+  stripLeadingOverlapFromTextWithInfo,
+} from "./overlap";
+export {
+  normalizePreviewText,
+  normalizeCommittedText,
+  resolveVoiceFormattingConfig,
+  applyVoiceFormattingToEvent,
+} from "./voice-formatting.normalizer";
+export type { VoiceFormattingConfig, VoiceFormattingMode } from "./voice-formatting.normalizer";

package/src/core/text-processing/overlap.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import {
+  stripLeadingOverlapFromText,
+  stripLeadingOverlapFromTextWithInfo,
+} from "./overlap";
+
+describe("realtime overlap", () => {
+  it("strips a repeated prefix already present before the cursor", () => {
+    const before = "... On retrouve cependant une formation méningi";
+    const incoming =
+      "On retrouve cependant une formation méningiomateuse mesurant 25 mm";
+
+    expect(stripLeadingOverlapFromText(before, incoming)).toBe(
+      "omateuse mesurant 25 mm"
+    );
+  });
+
+  it("reports partial-word overlap", () => {
+    const overlap = stripLeadingOverlapFromTextWithInfo(
+      "formation méningi",
+      "formation méningiomateuse"
+    );
+    expect(overlap).toEqual({
+      text: "omateuse",
+      partialWord: true,
+      overlapTokens: 2,
+    });
+  });
+
+  it("normalizes case, punctuation, and accents", () => {
+    expect(stripLeadingOverlapFromText("Bonne aération sinusienne.", "AERATION sinusienne et mastoïdienne")).toBe(
+      "et mastoïdienne"
+    );
+  });
+});

package/src/core/text-processing/overlap.ts

@@ -0,0 +1,101 @@
+const TOKEN_RE = /\S+/g;
+const PUNCT_EDGE_RE = /^[.,;:!?"'«»“”‘’()[\]{}]+|[.,;:!?"'«»“”‘’()[\]{}]+$/g;
+const ELISION_RE = /^(?:qu['’]|[dlsnmtcj]['’])/i;
+
+interface Token {
+  raw: string;
+  norm: string;
+  start: number;
+  end: number;
+}
+
+function normalizeToken(token: string): string {
+  return token
+    .normalize("NFD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toLowerCase()
+    .replace(PUNCT_EDGE_RE, "")
+    .replace(ELISION_RE, "");
+}
+
+function tokenize(text: string): Token[] {
+  const out: Token[] = [];
+  for (const match of text.matchAll(TOKEN_RE)) {
+    const raw = match[0];
+    const start = match.index ?? 0;
+    const norm = normalizeToken(raw);
+    if (!norm) continue;
+    out.push({ raw, norm, start, end: start + raw.length });
+  }
+  return out;
+}
+
+function prefixCharsForNormalizedPrefix(raw: string, normalizedPrefix: string): number {
+  if (!normalizedPrefix) return 0;
+  for (let i = 1; i <= raw.length; i++) {
+    const norm = normalizeToken(raw.slice(0, i));
+    if (norm.length >= normalizedPrefix.length && norm.startsWith(normalizedPrefix)) {
+      return i;
+    }
+  }
+  return 0;
+}
+
+/**
+ * Removes the prefix of `incoming` already covered by the suffix of `before`.
+ * Handles case/punctuation/diacritics and the common streaming case where the
+ * previous text ends with a partial word.
+ */
+export function stripLeadingOverlapFromText(
+  before: string,
+  incoming: string,
+  maxTokens = 24
+): string {
+  return stripLeadingOverlapFromTextWithInfo(before, incoming, maxTokens).text;
+}
+
+export function stripLeadingOverlapFromTextWithInfo(
+  before: string,
+  incoming: string,
+  maxTokens = 24
+): { text: string; partialWord: boolean; overlapTokens: number } {
+  const left = tokenize(before);
+  const right = tokenize(incoming);
+  if (!left.length || !right.length) {
+    return { text: incoming, partialWord: false, overlapTokens: 0 };
+  }
+
+  const limit = Math.min(left.length, right.length, maxTokens);
+  for (let size = limit; size > 0; size--) {
+    const leftSlice = left.slice(left.length - size);
+    const rightSlice = right.slice(0, size);
+    let partialLast = false;
+    let matches = true;
+
+    for (let i = 0; i < size; i++) {
+      const l = leftSlice[i].norm;
+      const r = rightSlice[i].norm;
+      if (l === r) continue;
+      if (i === size - 1 && l.length >= 3 && r.startsWith(l)) {
+        partialLast = true;
+        continue;
+      }
+      matches = false;
+      break;
+    }
+    if (!matches) continue;
+
+    const lastRight = rightSlice[rightSlice.length - 1];
+    let cut = lastRight.end;
+    if (partialLast) {
+      cut = lastRight.start + prefixCharsForNormalizedPrefix(lastRight.raw, leftSlice[size - 1].norm);
+    }
+    return {
+      text: incoming.slice(cut).replace(/^[ \t]+/, ""),
+      partialWord: partialLast,
+      overlapTokens: size,
+    };
+  }
+
+  return { text: incoming, partialWord: false, overlapTokens: 0 };
+}