@ephia/dova-sdk 1.0.0

package/src/core/bindings/SegmentBindingBridge.ts

@@ -0,0 +1,377 @@
+import type {
+  TargetBinding,
+  SessionAnchor,
+  BeginSessionOptions,
+  CommitFinalOptions,
+} from "./TargetBinding";
+import type { DocumentOperation } from "ephia-protocol";
+import type { BindingAdapter, SegmentStatus } from "./types";
+
+export interface SegmentBindingBridgeOptions {
+  onSegmentReviewing?(): void;
+  onSegmentReviewDone?(): void;
+  partialDebounceMs?: number;
+}
+
+const DEFAULT_PARTIAL_DEBOUNCE_MS = 120;
+
+/**
+ * Bridge qui adapte l'interface segment-based (BindingAdapter) vers
+ * l'interface event-based legacy (TargetBinding).
+ *
+ * Le reste du SDK (EphiaProvider, useEphia) continue de parler TargetBinding.
+ * Les nouveaux adapters implémentent BindingAdapter.
+ */
+export class SegmentBindingBridge implements TargetBinding {
+  kind = "segment-bridge";
+
+  private adapter: BindingAdapter;
+  private element: HTMLElement;
+  private anchor: SessionAnchor | null = null;
+  private _knownSegmentIds = new Set<string>();
+  private _committedSegmentIds = new Set<string>();
+  private _committedSegmentTexts = new Map<string, string>();
+  private _opts: SegmentBindingBridgeOptions;
+  private _pendingInserts = new Map<string, { timer: ReturnType<typeof setTimeout>; text: string; revision: number }>();
+
+  constructor(adapter: BindingAdapter, element: HTMLElement, opts: SegmentBindingBridgeOptions = {}) {
+    this.adapter = adapter;
+    this.element = element;
+    this._opts = opts;
+  }
+
+  attach(): void {
+    this.adapter.attach();
+  }
+
+  detach(): void {
+    this._clearAllPendingInserts();
+    this.adapter.detach();
+    this.anchor = null;
+    this._knownSegmentIds.clear();
+    this._committedSegmentIds.clear();
+    this._committedSegmentTexts.clear();
+  }
+
+  // ─── Session lifecycle ─────────────────────────────────────────────────────
+
+  beginSession(opts: BeginSessionOptions = {}): SessionAnchor {
+    this.adapter.attach();
+    const replaceSelection = opts.replaceSelection ?? true;
+    const isFocused = document.activeElement === this.element;
+
+    let start = 0;
+    let end = 0;
+    let hadSelection = false;
+
+    if (this.element instanceof HTMLTextAreaElement || this.element instanceof HTMLInputElement) {
+      start = this.element.selectionStart ?? this.element.value.length;
+      end = this.element.selectionEnd ?? start;
+      hadSelection = start !== end;
+    } else if (this.element.getAttribute("contenteditable") === "true") {
+      const sel = window.getSelection();
+      if (sel && sel.rangeCount > 0 && this.element.contains(sel.anchorNode)) {
+        const range = sel.getRangeAt(0);
+        const preCaret = range.cloneRange();
+        preCaret.selectNodeContents(this.element);
+        preCaret.setEnd(range.startContainer, range.startOffset);
+        start = preCaret.toString().length;
+        const postCaret = range.cloneRange();
+        postCaret.selectNodeContents(this.element);
+        postCaret.setEnd(range.endContainer, range.endOffset);
+        end = postCaret.toString().length;
+        hadSelection = start !== end;
+      } else {
+        start = this.element.textContent?.length ?? 0;
+        end = start;
+      }
+    }
+
+    if (!isFocused) {
+      start = this.adapter.getTextContent().length;
+      end = start;
+      hadSelection = false;
+    }
+
+    if (hadSelection && replaceSelection) {
+      // On ne supprime pas ici — l'adapter reçoit l'anchor et gère la plage.
+    }
+
+    this.anchor = {
+      initialStart: start,
+      initialEnd: end,
+      hadSelection,
+      end: hadSelection && replaceSelection ? start : end,
+      selectionPendingDelete: hadSelection && replaceSelection,
+    };
+    this.adapter.beginSession?.(this.anchor);
+
+    return this.anchor;
+  }
+
+  endSession(): void {
+    this._clearAllPendingInserts();
+    this.adapter.endSession?.();
+    this.anchor = null;
+    this.adapter.detach();
+    this._knownSegmentIds.clear();
+    this._committedSegmentIds.clear();
+    this._committedSegmentTexts.clear();
+  }
+
+  getSessionAnchor(): SessionAnchor | null {
+    return this.anchor;
+  }
+
+  // ─── Cursor / Range rects (fallback sur l'élément) ─────────────────────────
+
+  getCursorRect(): DOMRect | null {
+    try {
+      if (this.element instanceof HTMLTextAreaElement || this.element instanceof HTMLInputElement) {
+        const pos = this.anchor?.end ?? this.element.selectionStart ?? this.element.value.length;
+        // Simplification : retourne le rect de l'élément
+        return this.element.getBoundingClientRect();
+      }
+      return this.element.getBoundingClientRect();
+    } catch {
+      return this.element.getBoundingClientRect();
+    }
+  }
+
+  getRangeRect(_start: number, _end: number): DOMRect | null {
+    return this.element.getBoundingClientRect();
+  }
+
+  // ─── Streaming insertion (traduction segment → partial/final) ──────────────
+
+  insertPartial(segmentId: string, text: string, revision: number): void {
+    const pending = this._pendingInserts.get(segmentId);
+    if (pending) {
+      if (revision < pending.revision) return;
+      clearTimeout(pending.timer);
+    }
+
+    const timer = setTimeout(() => {
+      this._pendingInserts.delete(segmentId);
+      this._doInsertPartial(segmentId, text, revision);
+    }, this._opts.partialDebounceMs ?? DEFAULT_PARTIAL_DEBOUNCE_MS);
+
+    this._pendingInserts.set(segmentId, { timer, text, revision });
+  }
+
+  private _doInsertPartial(segmentId: string, text: string, _revision: number): void {
+    const existing = this._knownSegmentIds.has(segmentId);
+    if (existing) {
+      this.adapter.updateSegment(segmentId, text, "streaming");
+    } else {
+      this._knownSegmentIds.add(segmentId);
+      this.adapter.insertSegment({ id: segmentId, text, status: "streaming" });
+    }
+    if (this.anchor) {
+      this.anchor.end = this.adapter.getCursorOffset?.() ?? this.anchor.end;
+    }
+  }
+
+  commitFinal(segmentId: string, text: string, options?: CommitFinalOptions): void {
+    if (
+      this._committedSegmentIds.has(segmentId) &&
+      this._committedSegmentTexts.get(segmentId) === text
+    ) {
+      return;
+    }
+
+    // Flush immédiat si une preview est en attente pour ce segment
+    const pending = this._pendingInserts.get(segmentId);
+    if (pending) {
+      clearTimeout(pending.timer);
+      this._pendingInserts.delete(segmentId);
+    }
+
+    const existing = this._knownSegmentIds.has(segmentId);
+    if (existing) {
+      this.adapter.updateSegment(segmentId, text, "committed");
+    } else {
+      // Fallback : si un final arrive sans partial (rare), insérer directement
+      this._knownSegmentIds.add(segmentId);
+      this.adapter.insertSegment({ id: segmentId, text, status: "committed" });
+    }
+    this.adapter.commitSegment(segmentId);
+    this._committedSegmentIds.add(segmentId);
+    this._committedSegmentTexts.set(segmentId, text);
+    for (const absorbedId of options?.absorbedSegmentIds ?? []) {
+      if (absorbedId === segmentId) continue;
+      const pendingAbsorbed = this._pendingInserts.get(absorbedId);
+      if (pendingAbsorbed) {
+        clearTimeout(pendingAbsorbed.timer);
+        this._pendingInserts.delete(absorbedId);
+      }
+      if (!this._knownSegmentIds.has(absorbedId)) continue;
+      this.adapter.removeSegment(absorbedId);
+      this._knownSegmentIds.delete(absorbedId);
+      this._committedSegmentIds.delete(absorbedId);
+      this._committedSegmentTexts.delete(absorbedId);
+    }
+    if (this.anchor) {
+      this.anchor.end = this.adapter.getCursorOffset?.() ?? this.adapter.getTextContent().length;
+    }
+  }
+
+  notifyReviewing(): void {
+    this._opts.onSegmentReviewing?.();
+  }
+
+  notifyReviewDone(): void {
+    this._opts.onSegmentReviewDone?.();
+  }
+
+  clearPartial(segmentId: string): void {
+    const pending = this._pendingInserts.get(segmentId);
+    if (pending) {
+      clearTimeout(pending.timer);
+      this._pendingInserts.delete(segmentId);
+    }
+    this.adapter.removeSegment(segmentId);
+    this._knownSegmentIds.delete(segmentId);
+    this._committedSegmentIds.delete(segmentId);
+    this._committedSegmentTexts.delete(segmentId);
+  }
+
+  clearAll(): void {
+    this._clearAllPendingInserts();
+    if (this.adapter.clearAll) {
+      this.adapter.clearAll();
+      for (const id of [...this._knownSegmentIds]) {
+        if (!this._committedSegmentIds.has(id)) {
+          this._knownSegmentIds.delete(id);
+        }
+      }
+      return;
+    }
+    for (const id of [...this._knownSegmentIds]) {
+      if (this._committedSegmentIds.has(id)) continue;
+      this.adapter.removeSegment(id);
+      this._knownSegmentIds.delete(id);
+    }
+  }
+
+  private _clearAllPendingInserts(): void {
+    for (const { timer } of this._pendingInserts.values()) {
+      clearTimeout(timer);
+    }
+    this._pendingInserts.clear();
+  }
+
+  getSegmentRange(_segmentId: string): { start: number; end: number } | null {
+    // Les nouveaux adapters ne trackent pas les ranges publics
+    return null;
+  }
+
+  // ─── Lecture ───────────────────────────────────────────────────────────────
+
+  getText(): string {
+    return this.adapter.getTextContent();
+  }
+
+  getSelection() {
+    if (this.element instanceof HTMLTextAreaElement || this.element instanceof HTMLInputElement) {
+      const start = this.element.selectionStart ?? 0;
+      const end = this.element.selectionEnd ?? 0;
+      if (start === end) return null;
+      return {
+        text: this.element.value.slice(start, end),
+        range: { start, end },
+      };
+    }
+    return null;
+  }
+
+  getCursorOffset(): number | null {
+    return this.adapter.getCursorOffset();
+  }
+
+  // ─── Opérations structurées (simplifié) ────────────────────────────────────
+
+  applyOperation(operation: DocumentOperation): void {
+    if (this.adapter.applyOperation) {
+      this.adapter.applyOperation(operation);
+      return;
+    }
+    // Fallback pour les adapters natifs / contenteditable
+    const text = this.adapter.getTextContent();
+
+    switch (operation.type) {
+      case "replace": {
+        let start: number;
+        let end: number;
+        if (operation.range) {
+          start = operation.range.start;
+          end = operation.range.end;
+        } else if (operation.targetText) {
+          const idx = text.indexOf(operation.targetText);
+          if (idx === -1) return;
+          start = idx;
+          end = idx + operation.targetText.length;
+        } else {
+          return;
+        }
+        const before = text.slice(0, start);
+        const after = text.slice(end);
+        const newText = before + operation.replacement + after;
+        this._replaceAll(newText);
+        break;
+      }
+      case "insert": {
+        let pos = this.adapter.getCursorOffset() ?? text.length;
+        if (typeof operation.position === "number") pos = operation.position;
+        else if (operation.position === "end") pos = text.length;
+        else if (operation.position === "start") pos = 0;
+        const before = text.slice(0, pos);
+        const after = text.slice(pos);
+        this._replaceAll(before + operation.text + after);
+        break;
+      }
+      case "delete": {
+        let start: number;
+        let end: number;
+        if (operation.range) {
+          start = operation.range.start;
+          end = operation.range.end;
+        } else if (operation.targetText) {
+          const idx = text.indexOf(operation.targetText);
+          if (idx === -1) return;
+          start = idx;
+          end = idx + operation.targetText.length;
+        } else {
+          return;
+        }
+        const before = text.slice(0, start);
+        const after = text.slice(end);
+        this._replaceAll(before + after);
+        break;
+      }
+      case "replace_all": {
+        this._replaceAll(operation.replacement);
+        break;
+      }
+      default:
+        console.warn("[SegmentBindingBridge] Operation not supported:", operation.type);
+    }
+  }
+
+  // ─── Helpers ───────────────────────────────────────────────────────────────
+
+  private _replaceAll(newText: string): void {
+    if (this.element instanceof HTMLTextAreaElement || this.element instanceof HTMLInputElement) {
+      const setter = Object.getOwnPropertyDescriptor(
+        this.element instanceof HTMLTextAreaElement
+          ? HTMLTextAreaElement.prototype
+          : HTMLInputElement.prototype,
+        "value"
+      )?.set;
+      setter?.call(this.element, newText);
+      this.element.dispatchEvent(new Event("input", { bubbles: true }));
+    } else if (this.element.getAttribute("contenteditable") === "true") {
+      this.element.textContent = newText;
+    }
+  }
+}

package/src/core/bindings/TargetBinding.ts

@@ -0,0 +1,142 @@
+import type { DocumentOperation } from "ephia-protocol";
+
+export interface SessionAnchor {
+  /** Position où la dictée a commencé (immutable pendant la session). */
+  readonly initialStart: number;
+  /** Fin initiale (égale à initialStart si pas de sélection). */
+  readonly initialEnd: number;
+  /** True si la session a démarré avec une sélection non-vide. */
+  readonly hadSelection: boolean;
+  /** Position courante de la fin du texte dicté (mise à jour à chaque insert). */
+  end: number;
+  /**
+   * True tant que la sélection initiale n'a pas encore été supprimée.
+   * Le binding la supprimera atomiquement avec le premier insert de texte dicté.
+   */
+  selectionPendingDelete: boolean;
+}
+
+export interface BeginSessionOptions {
+  /**
+   * Si true, la sélection courante (si non vide) sera supprimée au premier
+   * insert et remplacée par le texte dicté. Défaut : true.
+   */
+  replaceSelection?: boolean;
+}
+
+export interface CommitFinalOptions {
+  absorbedSegmentIds?: string[];
+}
+
+export interface TargetBinding {
+  kind: string;
+
+  attach(): void;
+  detach(): void;
+
+  // ─── Session lifecycle ─────────────────────────────────────────────────────
+  /**
+   * Verrouille un anchor au début d'une session de dictée. Tous les inserts
+   * suivants se feront relativement à cet anchor, indépendamment du curseur
+   * de l'utilisateur. Si l'utilisateur avait une sélection non-vide, elle
+   * sera remplacée (sauf si replaceSelection: false).
+   */
+  beginSession?(opts?: BeginSessionOptions): SessionAnchor;
+
+  /** Termine la session et relâche l'anchor. Les textes restent dans le document. */
+  endSession?(): void;
+
+  /** Retourne l'anchor courant, ou null si pas de session active. */
+  getSessionAnchor?(): SessionAnchor | null;
+
+  /** Position visuelle du point d'insertion (anchor.end pendant la session, curseur sinon). */
+  getCursorRect?(): DOMRect | null;
+
+  /**
+   * Rectangle englobant d'une plage de texte. Utilisé pour le flash visuel
+   * (revised, committed). Retourne null si non supporté ou plage hors vue.
+   */
+  getRangeRect?(start: number, end: number): DOMRect | null;
+
+  // ─── Streaming insertion ───────────────────────────────────────────────────
+  insertPartial?(segmentId: string, text: string, revision: number): void;
+  commitFinal(segmentId: string, text: string, options?: CommitFinalOptions): void;
+  clearPartial(segmentId: string): void;
+  clearAll?(): void;
+
+  /** Retourne la plage [start, end] d'un segment commis dans le document, ou null si inconnu. */
+  getSegmentRange?(segmentId: string): { start: number; end: number } | null;
+
+  /** Récupère le texte complet du document */
+  getText(): string;
+
+  /** Récupère la sélection actuelle */
+  getSelection?(): {
+    text: string;
+    range: {
+      start: number;
+      end: number;
+    };
+  } | null;
+
+  /** Récupère la position du curseur */
+  getCursorOffset?(): number | null;
+
+  /** Applique une opération structurée au document */
+  applyOperation(operation: DocumentOperation): void;
+
+  /**
+   * Applique une séquence d'opérations (ex: insert_text/line_break/paragraph_break
+   * issue de textToDocumentOperations()). applyOperation() seul ne traite
+   * qu'une opération à la fois et n'a pas de notion de curseur implicite entre
+   * deux appels — un binding qui veut positionner correctement chaque
+   * opération relativement aux précédentes (ex: TipTap, cf. P4) doit fournir
+   * sa propre implémentation. Sinon, applyOperationsSequentially() (ci-dessous)
+   * sert de filet par défaut.
+   */
+  applyOperations?(operations: DocumentOperation[]): void;
+
+  /** Appelé quand un segment passe en état "reviewing" (correction SMART en cours) */
+  notifyReviewing?(): void;
+
+  /** Appelé quand la review d'un segment est terminée (corrected ou confirmed) */
+  notifyReviewDone?(): void;
+}
+
+/**
+ * Insère un joiner intelligent entre deux morceaux de texte.
+ * - Pas de joiner si un côté est déjà séparé par un whitespace ou une ponctuation
+ * - Espace par défaut sinon
+ */
+export function pickJoiner(before: string, next: string): string {
+  if (!before || !next) return "";
+  const lastChar = before[before.length - 1];
+  const firstChar = next[0];
+  if (/\s/.test(lastChar)) return "";
+  if (/\s/.test(firstChar)) return "";
+  if (/^[,.;:!?)\]]/.test(firstChar)) return "";
+  if (/[(\[]/.test(lastChar)) return "";
+  return " ";
+}
+
+export function endsWithNewline(text: string): boolean {
+  return text.length > 0 && text[text.length - 1] === "\n";
+}
+
+/**
+ * Filet par défaut pour les bindings qui ne fournissent pas leur propre
+ * applyOperations() : appelle binding.applyOperations() s'il existe, sinon
+ * boucle sur applyOperation() opération par opération (P3).
+ */
+export function applyOperationsSequentially(
+  binding: TargetBinding,
+  operations: DocumentOperation[]
+): void {
+  if (binding.applyOperations) {
+    binding.applyOperations(operations);
+    return;
+  }
+  for (const operation of operations) {
+    binding.applyOperation(operation);
+  }
+}

package/src/core/bindings/adapters/NativeAdapter.test.ts

@@ -0,0 +1,85 @@
+// @vitest-environment jsdom
+
+import { describe, expect, it } from "vitest";
+import { NativeAdapter } from "./NativeAdapter";
+
+describe("NativeAdapter", () => {
+  it("updates a committed native segment when Small final arrives with same segmentId", () => {
+    const textarea = document.createElement("textarea");
+    document.body.appendChild(textarea);
+
+    const adapter = new NativeAdapter(textarea);
+
+    adapter.attach();
+    adapter.insertSegment({
+      id: "efde10b0",
+      text: "\nTechnique :\nacquisition",
+      status: "streaming",
+    });
+    adapter.commitSegment("efde10b0");
+
+    adapter.updateSegment(
+      "efde10b0",
+      "\nTechnique :\nacquisition hélicoïdale sans injection.",
+      "committed"
+    );
+
+    expect(textarea.value).toBe(
+      "\nTechnique :\nacquisition hélicoïdale sans injection."
+    );
+
+    textarea.remove();
+  });
+
+  it("does not duplicate native committed segment on same segmentId update", () => {
+    const textarea = document.createElement("textarea");
+    document.body.appendChild(textarea);
+
+    const adapter = new NativeAdapter(textarea);
+
+    adapter.attach();
+    adapter.insertSegment({
+      id: "efde10b0",
+      text: "\nTechnique :\nacquisition",
+      status: "streaming",
+    });
+    adapter.commitSegment("efde10b0");
+
+    adapter.updateSegment(
+      "efde10b0",
+      "\nTechnique :\nacquisition hélicoïdale.",
+      "committed"
+    );
+
+    expect(textarea.value).toBe("\nTechnique :\nacquisition hélicoïdale.");
+    expect(textarea.value).not.toContain("acquisition\nTechnique");
+
+    textarea.remove();
+  });
+
+  it("keeps leading newlines in native committed segment updates", () => {
+    const textarea = document.createElement("textarea");
+    textarea.value = "Avant";
+    document.body.appendChild(textarea);
+
+    const adapter = new NativeAdapter(textarea);
+
+    adapter.attach();
+    adapter.insertSegment({
+      id: "efde10b0",
+      text: "\nTechnique :\nacquisition",
+      status: "streaming",
+    });
+    adapter.commitSegment("efde10b0");
+
+    adapter.updateSegment(
+      "efde10b0",
+      "\nTechnique :\nacquisition hélicoïdale.",
+      "committed"
+    );
+
+    expect(textarea.value).toBe("Avant\nTechnique :\nacquisition hélicoïdale.");
+
+    textarea.remove();
+  });
+});