@ephia/dova-sdk 1.0.0

package/src/core/bindings/native/NativeBinding.test.ts

@@ -0,0 +1,277 @@
+// @vitest-environment jsdom
+
+import { describe, expect, it, vi } from "vitest";
+import { NativeBinding } from "./NativeBinding";
+
+function textarea(value = "", selectionStart?: number, selectionEnd?: number) {
+  const el = document.createElement("textarea");
+  el.value = value;
+  document.body.appendChild(el);
+  if (selectionStart !== undefined) {
+    const end = selectionEnd ?? selectionStart;
+    el.setSelectionRange(selectionStart, end);
+  }
+  return el;
+}
+
+describe("NativeBinding — prefix/suffix model", () => {
+  it("inserts segment text at cursor, preserving suffix", () => {
+    const el = textarea("AAA BBB", 4, 4);
+    const b = new NativeBinding(el);
+    b.attach();
+
+    b.upsertSegment({ id: "s1", text: "DICT", stage: "canonical" });
+
+    expect(el.value).toBe("AAA DICTBBB");
+    el.remove();
+  });
+
+  it("inserts segment replacing selection, preserving text after selectionEnd", () => {
+    const el = textarea("hello old world", 6, 9);
+    const b = new NativeBinding(el);
+    b.attach();
+
+    b.upsertSegment({ id: "s1", text: "new", stage: "canonical" });
+
+    expect(el.value).toBe("hello new world");
+    el.remove();
+  });
+
+  it("previews do not remove suffix, suffix stays after preview text", () => {
+    const el = textarea("AAA BBB", 4, 4);
+    const b = new NativeBinding(el);
+    b.attach();
+
+    b.previewSegment({ id: "s1", text: "PREV" });
+
+    expect(el.value).toBe("AAA PREVBBB");
+    el.remove();
+  });
+
+  it("upsert after preview replaces preview text (same segment)", () => {
+    const el = textarea("AAA BBB", 4, 4);
+    const b = new NativeBinding(el);
+    b.attach();
+
+    b.previewSegment({ id: "s1", text: "PREV" });
+    b.upsertSegment({ id: "s1", text: "FINAL", stage: "canonical" });
+
+    expect(el.value).toBe("AAA FINALBBB");
+    el.remove();
+  });
+
+  it("updates same segmentId in place without duplication", () => {
+    const el = textarea("Before.", 7, 7);
+    const b = new NativeBinding(el);
+    b.attach();
+
+    b.upsertSegment({ id: "s1", text: " premier", stage: "provisional" });
+    b.upsertSegment({ id: "s1", text: " premier segment corrigé", stage: "canonical" });
+
+    expect(el.value).toBe("Before. premier segment corrigé");
+    expect(el.value).not.toContain("premier premier");
+    el.remove();
+  });
+
+  it("removes segment and keeps suffix intact", () => {
+    const el = textarea("Avant Après", 6, 6);
+    const b = new NativeBinding(el);
+    b.attach();
+
+    b.upsertSegment({ id: "s1", text: "DICT ", stage: "canonical" });
+    expect(el.value).toBe("Avant DICT Après");
+
+    b.removeSegment("s1");
+    expect(el.value).toBe("Avant Après");
+    el.remove();
+  });
+
+  it("suffix preserved after multiple segments", () => {
+    const el = textarea("fin", 0, 0);
+    const b = new NativeBinding(el);
+    b.attach();
+
+    b.upsertSegment({ id: "s1", text: "un ", stage: "canonical" });
+    b.upsertSegment({ id: "s2", text: "deux ", stage: "canonical" });
+
+    expect(el.value).toBe("un deux fin");
+    el.remove();
+  });
+
+  it("getEditorContext reports middle_of_sentence when suffix non-empty", () => {
+    const el = textarea("Avant Après", 6, 6);
+    const b = new NativeBinding(el);
+    b.attach();
+
+    const ctx = b.getEditorContext("report");
+    expect(ctx.insertionMode).toBe("middle_of_sentence");
+    expect(ctx.rightContext).toBe("Après");
+    el.remove();
+  });
+
+  it("getEditorContext reports append when suffix is empty", () => {
+    const el = textarea("Texte.", 6, 6);
+    const b = new NativeBinding(el);
+    b.attach();
+
+    const ctx = b.getEditorContext("report");
+    expect(ctx.insertionMode).toBe("append");
+    el.remove();
+  });
+
+  it("warns and ignores upsert for a removed segment", () => {
+    const el = textarea("", 0, 0);
+    const warn = vi.fn();
+    const b = new NativeBinding(el, { warn });
+    b.attach();
+
+    b.upsertSegment({ id: "s1", text: "texte", stage: "canonical" });
+    b.removeSegment("s1");
+    b.upsertSegment({ id: "s1", text: "autre", stage: "canonical" });
+
+    expect(warn).toHaveBeenCalledOnce();
+    expect(el.value).toBe("");
+    el.remove();
+  });
+
+  it("identity equals the DOM element", () => {
+    const el = textarea();
+    const b = new NativeBinding(el);
+    expect(b.identity).toBe(el);
+    el.remove();
+  });
+});
+
+describe("NativeBinding — boundary safety", () => {
+  it("adds space when segment collides with existing text", () => {
+    const el = textarea("contraste.", 10, 10);
+    const b = new NativeBinding(el);
+    b.attach();
+
+    b.upsertSegment({ id: "s1", text: "Indication", stage: "provisional" });
+
+    expect(el.value).toBe("contraste. Indication");
+    el.remove();
+  });
+
+  it("clears sdk prefix when canonical provides its own whitespace", () => {
+    const el = textarea("contraste.", 10, 10);
+    const b = new NativeBinding(el);
+    b.attach();
+
+    // Provisional arrives without space — SDK adds " ".
+    b.upsertSegment({ id: "s1", text: "Indication", stage: "provisional" });
+    expect(el.value).toBe("contraste. Indication");
+
+    // Canonical arrives with its own leading space — SDK prefix must be cleared.
+    b.upsertSegment({ id: "s1", text: " Indication corrigée", stage: "canonical" });
+    expect(el.value).toBe("contraste. Indication corrigée");
+    el.remove();
+  });
+
+  it("preview applies boundary and upsert reuses it", () => {
+    const el = textarea("contraste.", 10, 10);
+    const b = new NativeBinding(el);
+    b.attach();
+
+    b.previewSegment({ id: "s1", text: "Ind" });
+    expect(el.value).toBe("contraste. Ind");
+
+    b.previewSegment({ id: "s1", text: "Indication" });
+    expect(el.value).toBe("contraste. Indication");
+
+    // Canonical without own prefix — SDK prefix kept.
+    b.upsertSegment({ id: "s1", text: "Indication corrigée", stage: "canonical" });
+    expect(el.value).toBe("contraste. Indication corrigée");
+    el.remove();
+  });
+
+  it("no double space when text already starts with whitespace on provisional", () => {
+    const el = textarea("contraste.", 10, 10);
+    const b = new NativeBinding(el);
+    b.attach();
+
+    // Backend provisional already has a leading space.
+    b.upsertSegment({ id: "s1", text: " Indication", stage: "provisional" });
+
+    // Should be exactly one space, not two.
+    expect(el.value).toBe("contraste. Indication");
+    el.remove();
+  });
+
+  it("prepareForDictation resyncs after manual edits between sessions", () => {
+    const el = textarea("Avant.", 6, 6);
+    const b = new NativeBinding(el);
+    b.attach();
+
+    b.upsertSegment({ id: "s1", text: " dicté", stage: "canonical" });
+    expect(el.value).toBe("Avant. dicté");
+
+    // User stops, deletes dictated text, moves cursor to end of "Avant."
+    el.value = "Avant.";
+    el.setSelectionRange(6, 6);
+
+    b.prepareForDictation();
+    b.upsertSegment({ id: "s2", text: " suite", stage: "canonical" });
+
+    expect(el.value).toBe("Avant. suite");
+    expect(el.value).not.toContain("dicté");
+    el.remove();
+  });
+
+  it("canonical absorb clears segment boundary prefix when text is self-contained", () => {
+    const el = textarea("Scanner cérébral ", 17, 17);
+    const b = new NativeBinding(el);
+    b.attach();
+
+    b.upsertSegment({
+      id: "seg1",
+      text: "sans injection de produit de contraste.",
+      stage: "provisional",
+    });
+    b.upsertSegment({
+      id: "seg2",
+      text: "Avec injection de produits de contraste.",
+      stage: "provisional",
+    });
+    expect(el.value).toBe(
+      "Scanner cérébral sans injection de produit de contraste. Avec injection de produits de contraste.",
+    );
+
+    b.upsertSegment({
+      id: "seg1",
+      text: "Scanner cérébral avec injection de produit de contraste dans un contexte.",
+      stage: "canonical",
+    });
+    b.removeSegment("seg2");
+
+    expect(el.value).toBe(
+      "Scanner cérébral avec injection de produit de contraste dans un contexte.",
+    );
+    expect(el.value).not.toMatch(/Scanner cérébral Scanner cérébral/);
+    el.remove();
+  });
+
+  it("canonical merge fragment keeps segment boundary prefix", () => {
+    const el = textarea("Scanner cérébral ", 17, 17);
+    const b = new NativeBinding(el);
+    b.attach();
+
+    b.upsertSegment({
+      id: "seg1",
+      text: "sans injection de produit de contraste.",
+      stage: "provisional",
+    });
+
+    b.upsertSegment({
+      id: "seg1",
+      text: "avec injection de produit de contraste.",
+      stage: "canonical",
+    });
+
+    expect(el.value).toBe(
+      "Scanner cérébral avec injection de produit de contraste.",
+    );
+    el.remove();
+  });
+});

package/src/core/bindings/native/NativeBinding.ts

@@ -0,0 +1,239 @@
+import type { EditorContext } from "ephia-protocol";
+import type { EphiaBinding, PreviewSegmentInput, UpsertSegmentInput } from "../EphiaBinding";
+import { ensureMinimalAppendBoundary } from "../insertion-boundary";
+
+// Bypass React controlled components — use native setter to avoid onChange fights.
+function setNativeValue(el: HTMLInputElement | HTMLTextAreaElement, value: string): void {
+  const proto =
+    el instanceof HTMLTextAreaElement
+      ? HTMLTextAreaElement.prototype
+      : HTMLInputElement.prototype;
+  const setter = Object.getOwnPropertyDescriptor(proto, "value")?.set;
+  setter?.call(el, value);
+}
+
+function dispatchInputEvent(el: HTMLInputElement | HTMLTextAreaElement): void {
+  el.dispatchEvent(new Event("input", { bubbles: true }));
+}
+
+/**
+ * Binding V2 pour <textarea> et <input type="text">.
+ *
+ * Modèle : prefix | segments dictés | preview | suffix
+ *
+ * Le prefix et le suffix sont verrouillés à l'attach() depuis la sélection
+ * courante. Tous les segments dictés sont insérés entre les deux.
+ * Même segmentId = mise à jour en place (jamais d'append).
+ */
+export class NativeBinding implements EphiaBinding {
+  readonly kind = "native";
+  readonly identity: HTMLInputElement | HTMLTextAreaElement;
+
+  private readonly el: HTMLInputElement | HTMLTextAreaElement;
+  private readonly warn: (msg: string, details?: Record<string, unknown>) => void;
+
+  // Text before/after the dictation zone, locked at attach().
+  private prefix = "";
+  private suffix = "";
+
+  // Committed segment texts, keyed by id, in insertion order (Map preserves insertion order).
+  private readonly segmentTexts = new Map<string, string>();
+  // Tracks all segment ids ever seen (for idempotent range-lost guard).
+  private readonly knownSegmentIds = new Set<string>();
+  // Boundary prefix computed once per segment at first insertion (preview or upsert).
+  private readonly segmentBoundaryPrefixes = new Map<string, string>();
+
+  // Current streaming preview (displayed but not committed).
+  private previewSegmentId: string | null = null;
+  private previewText = "";
+
+  constructor(
+    el: HTMLInputElement | HTMLTextAreaElement,
+    options?: { warn?: (msg: string, details?: Record<string, unknown>) => void }
+  ) {
+    this.el = el;
+    this.identity = el;
+    this.warn = options?.warn ?? ((msg, d) => console.warn(msg, d));
+  }
+
+  attach(): void {
+    this._syncInsertionAnchor();
+  }
+
+  /**
+   * Resync prefix/suffix and clear segment memory from the current DOM value.
+   * Called before each dictation so manual edits between sessions are preserved.
+   */
+  prepareForDictation(): void {
+    this._syncInsertionAnchor();
+  }
+
+  detach(): void {
+    this.segmentTexts.clear();
+    this.knownSegmentIds.clear();
+    this.segmentBoundaryPrefixes.clear();
+    this.previewSegmentId = null;
+    this.previewText = "";
+  }
+
+  getText(): string {
+    return this.prefix + this._committedText() + this.suffix;
+  }
+
+  getEditorContext(targetId = ""): EditorContext {
+    const committed = this._committedText();
+    const value = this.prefix + committed + this.suffix;
+    const cursorOffset = this.prefix.length + committed.length;
+
+    return {
+      targetId,
+      documentEmpty: value.trim().length === 0,
+      insertionMode: this.suffix.length > 0 ? "middle_of_sentence" : "append",
+      leftContext: value.slice(Math.max(0, cursorOffset - 400), cursorOffset),
+      rightContext: value.slice(cursorOffset, cursorOffset + 200),
+      selectedText: null,
+      cursorOffset,
+    };
+  }
+
+  previewSegment(input: PreviewSegmentInput): void {
+    // Compute boundary prefix once per segment (first preview for this id).
+    if (!this.segmentBoundaryPrefixes.has(input.id)) {
+      const leftText = this.prefix + this._committedText();
+      const withBoundary = ensureMinimalAppendBoundary(leftText, input.text);
+      const prefix = withBoundary.length > input.text.length
+        ? withBoundary.slice(0, withBoundary.length - input.text.length)
+        : "";
+      this.segmentBoundaryPrefixes.set(input.id, prefix);
+    }
+    this.previewSegmentId = input.id;
+    const boundaryPrefix = this.segmentBoundaryPrefixes.get(input.id) ?? "";
+    this.previewText = boundaryPrefix + input.text;
+    this._render();
+  }
+
+  upsertSegment(input: UpsertSegmentInput): void {
+    if (this.previewSegmentId === input.id) {
+      this.previewSegmentId = null;
+      this.previewText = "";
+    }
+
+    if (this.knownSegmentIds.has(input.id) && !this.segmentTexts.has(input.id)) {
+      this.warn("[ephia:native] segment range lost; upsert ignored", { segmentId: input.id });
+      return;
+    }
+
+    if (!this.segmentBoundaryPrefixes.has(input.id)) {
+      // First upsert for this segment with no prior preview — compute boundary from left context.
+      const leftText = this.prefix + this._committedText();
+      const withBoundary = ensureMinimalAppendBoundary(leftText, input.text);
+      const prefix = withBoundary.length > input.text.length
+        ? withBoundary.slice(0, withBoundary.length - input.text.length)
+        : "";
+      this.segmentBoundaryPrefixes.set(input.id, prefix);
+    } else if (input.text.length > 0 && /^\s/.test(input.text)) {
+      // Backend canonical provides its own boundary — clear ours to avoid double spacing.
+      this.segmentBoundaryPrefixes.set(input.id, "");
+    }
+
+    this.segmentTexts.set(input.id, input.text);
+    this.knownSegmentIds.add(input.id);
+
+    if (input.stage === "canonical") {
+      this._reconcileCanonicalSegmentInsertion(input.id, input.text);
+    }
+
+    this._render();
+  }
+
+  removeSegment(id: string): void {
+    if (this.previewSegmentId === id) {
+      this.previewSegmentId = null;
+      this.previewText = "";
+    }
+
+    this.segmentTexts.delete(id);
+    this.segmentBoundaryPrefixes.delete(id);
+    this.knownSegmentIds.add(id);
+    this._render();
+  }
+
+  removeSegments(ids: string[]): void {
+    for (const id of ids) this.removeSegment(id);
+  }
+
+  private _syncInsertionAnchor(): void {
+    const start = this.el.selectionStart ?? this.el.value.length;
+    const end = this.el.selectionEnd ?? start;
+
+    this.prefix = this.el.value.slice(0, start);
+    this.suffix = this.el.value.slice(end);
+
+    this.segmentTexts.clear();
+    this.knownSegmentIds.clear();
+    this.segmentBoundaryPrefixes.clear();
+    this.previewSegmentId = null;
+    this.previewText = "";
+  }
+
+  // ------------------------------------------------------------------
+  // Internals
+  // ------------------------------------------------------------------
+
+  private _committedText(): string {
+    return [...this.segmentTexts.keys()].map((id) => {
+      const prefix = this.segmentBoundaryPrefixes.get(id) ?? "";
+      return prefix + (this.segmentTexts.get(id) ?? "");
+    }).join("");
+  }
+
+  /**
+   * Canonical upserts (incl. absorb/merge) may carry the full corrected phrase.
+   * Drop segment/binding prefixes that would duplicate its opening.
+   */
+  private _reconcileCanonicalSegmentInsertion(segmentId: string, text: string): void {
+    const boundaryPrefix = this.segmentBoundaryPrefixes.get(segmentId);
+    if (boundaryPrefix) {
+      const boundaryCore = boundaryPrefix.trimEnd();
+      if (
+        text.startsWith(boundaryPrefix)
+        || (boundaryCore.length > 0 && text.startsWith(boundaryCore))
+      ) {
+        this.segmentBoundaryPrefixes.set(segmentId, "");
+      }
+    }
+
+    this._trimBindingPrefixOverlap(text);
+  }
+
+  /** Trim binding.prefix when canonical text already opens with its trailing words. */
+  private _trimBindingPrefixOverlap(text: string): void {
+    if (!this.prefix || !text) return;
+
+    for (let overlap = Math.min(this.prefix.length, text.length); overlap > 0; overlap--) {
+      const suffix = this.prefix.slice(this.prefix.length - overlap);
+      if (suffix.trim().length === 0) continue;
+      if (text.startsWith(suffix)) {
+        this.prefix = this.prefix.slice(0, this.prefix.length - overlap);
+        return;
+      }
+    }
+  }
+
+  private _render(): void {
+    const committed = this._committedText();
+    const next = this.prefix + committed + this.previewText + this.suffix;
+
+    if (this.el.value !== next) {
+      setNativeValue(this.el, next);
+      dispatchInputEvent(this.el);
+    }
+
+    const insertionPos = this.prefix.length + committed.length;
+    try {
+      this.el.setSelectionRange(insertionPos, insertionPos);
+    } catch {
+      /* noop */
+    }
+  }
+}

package/src/core/bindings/resolver.ts

@@ -0,0 +1,18 @@
+/**
+ * Résout une cible de binding (string selector ou Element).
+ * SSR-safe : vérifie l'existence de document.
+ */
+
+export function resolveTarget(target: string | Element | null | undefined): Element | null {
+  if (!target) return null;
+  if (typeof target === "string") {
+    if (typeof document === "undefined") return null;
+    try {
+      return document.querySelector(target);
+    } catch {
+      console.warn(`[ephia] invalid target selector: "${target}"`);
+      return null;
+    }
+  }
+  return target;
+}