@ephia/dova-sdk 1.0.0

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

@@ -0,0 +1,216 @@
+import { BindingAdapter, SegmentStatus, TextSegment } from "../types";
+import { pickJoiner } from "../TargetBinding";
+import type { SessionAnchor } from "../TargetBinding";
+
+type SegmentEntry = {
+  text: string;
+  joiner: string;
+  status: SegmentStatus;
+};
+
+// Bypass React controlled component
+function setNativeValue(
+  el: HTMLInputElement | HTMLTextAreaElement,
+  value: string
+) {
+  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) {
+  el.dispatchEvent(new Event("input", { bubbles: true }));
+}
+
+function dispatchCustomEvent<T>(
+  el: HTMLInputElement | HTMLTextAreaElement,
+  type: string,
+  detail: T
+) {
+  el.dispatchEvent(new CustomEvent(type, { bubbles: false, detail }));
+}
+
+/**
+ * Adapter natif pour <textarea> et <input>.
+ *
+ * Stratégie :
+ * - Les partials sont écrits directement dans le champ sans notifier React.
+ * - React n'est notifié (via dispatchEvent) qu'au commit final.
+ * - Cela évite le "fight" entre le binding et les onChange React qui transforment
+ *   la valeur (validation, masque, uppercase, etc.).
+ */
+export class NativeAdapter implements BindingAdapter {
+  private element: HTMLInputElement | HTMLTextAreaElement;
+  // Texte avant/après la plage de dictée verrouillée au début de session.
+  private prefixText = "";
+  private suffixText = "";
+  // Segments déjà commités pendant cette session, adressables par id pour les
+  // révisions tardives (Voxtral Small).
+  private committedSegments = new Map<string, SegmentEntry>();
+  // Segments en cours de streaming (preview).
+  private segments = new Map<string, SegmentEntry>();
+
+  constructor(el: HTMLInputElement | HTMLTextAreaElement) {
+    this.element = el;
+  }
+
+  attach() {
+    this.prefixText = this.element.value;
+    this.suffixText = "";
+    this.committedSegments.clear();
+    this.segments.clear();
+  }
+
+  beginSession(anchor: SessionAnchor) {
+    const value = this.element.value;
+    const start = Math.max(0, Math.min(anchor.initialStart, value.length));
+    const end = Math.max(start, Math.min(anchor.initialEnd, value.length));
+    this.prefixText = value.slice(0, start);
+    this.suffixText = value.slice(end);
+    this.committedSegments.clear();
+    this.segments.clear();
+    this._setSelectionToInsertionEnd();
+    this._dispatchCursorPosition();
+    this._dispatchPartialCleared();
+    anchor.selectionPendingDelete = false;
+  }
+
+  detach() {
+    this.segments.clear();
+    this.committedSegments.clear();
+    this.suffixText = "";
+    this._dispatchPartialCleared();
+  }
+
+  insertSegment(seg: TextSegment) {
+    const before = this._buildInsertionText();
+    // Si le segment commence par \n (commande résolue côté backend), pas d'espace
+    const joiner = seg.text.startsWith("\n") ? "" : pickJoiner(before, seg.text);
+    this.segments.set(seg.id, { text: seg.text, joiner, status: seg.status });
+    this._render();
+  }
+
+  updateSegment(id: string, text: string, status: SegmentStatus) {
+    const seg = this.segments.get(id) ?? this.committedSegments.get(id);
+    if (!seg) return;
+    // Le joiner calculé à l'insertion est conservé — seul le texte change.
+    seg.text = text;
+    seg.status = status;
+    this._render();
+  }
+
+  commitSegment(id: string) {
+    const streamingSeg = this.segments.get(id);
+    if (streamingSeg) {
+      // Déplacer le segment streaming vers les segments commités ; il reste
+      // adressable par id pour une révision Voxtral Small ultérieure.
+      this.committedSegments.set(id, streamingSeg);
+      this.segments.delete(id);
+    } else if (!this.committedSegments.has(id)) {
+      // Segment inconnu : rien à committer.
+      return;
+    }
+
+    const expectedValue = this._buildText();
+    if (this.element.value !== expectedValue) {
+      setNativeValue(this.element, expectedValue);
+    }
+
+    this._setSelectionToInsertionEnd();
+    this._dispatchCursorPosition();
+    this._dispatchPartialUpdate();
+    dispatchInputEvent(this.element);
+  }
+
+  removeSegment(id: string) {
+    this.segments.delete(id);
+    this.committedSegments.delete(id);
+    this._render();
+    this._dispatchPartialUpdate();
+  }
+
+  clearAll() {
+    this.segments.clear();
+    this._render();
+    this._dispatchPartialCleared();
+  }
+
+  getTextContent() {
+    return this.element.value;
+  }
+
+  getSegmentText(id: string): string | null {
+    return this.segments.get(id)?.text ?? this.committedSegments.get(id)?.text ?? null;
+  }
+
+  getCursorOffset() {
+    return this.element.selectionEnd ?? this.element.value.length;
+  }
+
+  private _buildStreamingText() {
+    return [...this.segments.values()]
+      .map((s) => s.joiner + s.text)
+      .join("");
+  }
+
+  private _buildCommittedText() {
+    return [...this.committedSegments.values()]
+      .map((s) => s.joiner + s.text)
+      .join("");
+  }
+
+  // Texte avant le suffixe : sert à calculer les joiners et le caret.
+  private _buildInsertionText() {
+    return this.prefixText + this._buildCommittedText() + this._buildStreamingText();
+  }
+
+  // Reconstruit la valeur affichée : prefix + dictée en cours + suffixe intact.
+  private _buildText() {
+    return this._buildInsertionText() + this.suffixText;
+  }
+
+  private _insertionEnd() {
+    return this._buildInsertionText().length;
+  }
+
+  private _setSelectionToInsertionEnd() {
+    const pos = this._insertionEnd();
+    try {
+      this.element.setSelectionRange(pos, pos);
+    } catch {
+      /* noop */
+    }
+  }
+
+  private _render() {
+    setNativeValue(this.element, this._buildText());
+    this._setSelectionToInsertionEnd();
+    this._dispatchCursorPosition();
+    this._dispatchPartialUpdate();
+  }
+
+  private _dispatchCursorPosition() {
+    dispatchCustomEvent(this.element, "ephia:cursor-position", {
+      position: this._insertionEnd(),
+    });
+  }
+
+  private _dispatchPartialUpdate() {
+    const text = this._buildStreamingText();
+    if (!text) {
+      this._dispatchPartialCleared();
+      return;
+    }
+    dispatchCustomEvent(this.element, "ephia:partial", {
+      text,
+      insertAt: this.prefixText.length + this._buildCommittedText().length,
+    });
+  }
+
+  private _dispatchPartialCleared() {
+    dispatchCustomEvent(this.element, "ephia:partial-cleared", {});
+  }
+}

package/src/core/bindings/adapters/ProseMirrorAdapter.ts

@@ -0,0 +1,231 @@
+import { Plugin, PluginKey } from "@tiptap/pm/state";
+import { Decoration, DecorationSet } from "@tiptap/pm/view";
+import type { EditorView } from "@tiptap/pm/view";
+import type { Transaction } from "@tiptap/pm/state";
+import { BindingAdapter, SegmentStatus, TextSegment } from "../types";
+import type { DocumentOperation } from "ephia-protocol";
+import { pickJoiner } from "../TargetBinding";
+
+// --- Plugin PM auto-injecté ---
+
+interface EphiaSegmentState {
+  segments: Map<string, { from: number; to: number; text: string; status: SegmentStatus }>;
+}
+
+const ephiaKey = new PluginKey<EphiaSegmentState>("ephia-segments");
+
+const setSegmentsEffect = (
+  tr: Transaction,
+  segments: EphiaSegmentState["segments"]
+) => {
+  tr.setMeta(ephiaKey, { segments: new Map(segments) } as EphiaSegmentState);
+};
+
+const ephiaPlugin = new Plugin<EphiaSegmentState>({
+  key: ephiaKey,
+  state: {
+    init(): EphiaSegmentState {
+      return { segments: new Map() };
+    },
+    apply(tr, prev): EphiaSegmentState {
+      // Remap les positions à chaque transaction (undo, typing, etc.)
+      const remapped = new Map(
+        [...prev.segments.entries()].map(([id, seg]) => [
+          id,
+          {
+            ...seg,
+            from: tr.mapping.map(seg.from),
+            to: tr.mapping.map(seg.to, 1),
+          },
+        ])
+      );
+
+      // Appliquer les effets Ephia
+      const meta = tr.getMeta(ephiaKey) as EphiaSegmentState | undefined;
+      if (meta?.segments) {
+        return { segments: meta.segments };
+      }
+      return { segments: remapped };
+    },
+  },
+  props: {
+    decorations(state) {
+      const pluginState = ephiaKey.getState(state);
+      if (!pluginState) return DecorationSet.empty;
+
+      const decos: Decoration[] = [];
+      for (const seg of pluginState.segments.values()) {
+        if (seg.from >= seg.to) continue;
+        decos.push(
+          Decoration.inline(seg.from, seg.to, {
+            class: `ephia-${seg.status}`,
+          })
+        );
+      }
+      return DecorationSet.create(state.doc, decos);
+    },
+  },
+});
+
+// --- Adapter ---
+
+export class ProseMirrorAdapter implements BindingAdapter {
+  private view: EditorView;
+  private segments = new Map<
+    string,
+    { from: number; to: number; text: string; joinerLength: number; status: SegmentStatus }
+  >();
+
+  constructor(view: EditorView) {
+    this.view = view;
+  }
+
+  attach() {
+    // Injecter le plugin PM si pas déjà présent
+    const alreadyPresent = this.view.state.plugins.some(
+      (p) => p.spec.key === ephiaKey
+    );
+    if (!alreadyPresent) {
+      this.view.updateState(
+        this.view.state.reconfigure({
+          plugins: [...this.view.state.plugins, ephiaPlugin],
+        })
+      );
+    }
+  }
+
+  detach() {
+    this.segments.clear();
+    this._dispatch();
+  }
+
+  insertSegment(seg: TextSegment) {
+    const { from } = this.view.state.selection;
+    const before = this.view.state.doc.textContent;
+    const joiner = pickJoiner(before, seg.text);
+    const fullText = joiner + seg.text;
+    const tr = this.view.state.tr.insertText(fullText, from);
+    const to = from + fullText.length;
+    this.view.dispatch(tr);
+    this.segments.set(seg.id, { from, to, text: seg.text, joinerLength: joiner.length, status: seg.status });
+    this._dispatch();
+  }
+
+  updateSegment(id: string, text: string, status: SegmentStatus) {
+    const seg = this.segments.get(id);
+    if (!seg) return;
+    // Remplacer uniquement la partie texte — le joiner en tête du segment est conservé
+    const textFrom = seg.from + seg.joinerLength;
+    const tr = this.view.state.tr.replaceWith(
+      textFrom,
+      seg.to,
+      this.view.state.schema.text(text)
+    );
+    const newTo = textFrom + text.length;
+    this.view.dispatch(tr);
+    this.segments.set(id, { ...seg, to: newTo, text, status });
+    this._dispatch();
+  }
+
+  commitSegment(id: string) {
+    const seg = this.segments.get(id);
+    if (!seg) return;
+    this.segments.set(id, { ...seg, status: "committed" });
+    this._dispatch();
+    // Retirer la décoration après l'animation CSS (1.2s)
+    setTimeout(() => {
+      this.segments.delete(id);
+      this._dispatch();
+    }, 1400);
+  }
+
+  removeSegment(id: string) {
+    const seg = this.segments.get(id);
+    if (!seg) return;
+    const tr = this.view.state.tr.delete(seg.from, seg.to);
+    this.view.dispatch(tr);
+    this.segments.delete(id);
+    this._dispatch();
+  }
+
+  getTextContent() {
+    return this.view.state.doc.textContent;
+  }
+
+  getSegmentText(id: string): string | null {
+    const seg = this.segments.get(id);
+    if (!seg || seg.status === "committed") return null;
+    return seg.text;
+  }
+
+  getCursorOffset() {
+    return this.view.state.selection.from;
+  }
+
+  applyOperation(operation: DocumentOperation): void {
+    switch (operation.type) {
+      case "replace": {
+        let start: number, end: number;
+        if (operation.range) {
+          start = operation.range.start;
+          end = operation.range.end;
+        } else if (operation.targetText) {
+          const text = this.view.state.doc.textContent;
+          const idx = text.indexOf(operation.targetText);
+          if (idx === -1) return;
+          start = idx;
+          end = idx + operation.targetText.length;
+        } else return;
+        const tr = this.view.state.tr.replaceWith(
+          start,
+          end,
+          this.view.state.schema.text(operation.replacement)
+        );
+        this.view.dispatch(tr);
+        break;
+      }
+      case "insert": {
+        let pos = this.view.state.selection.from;
+        if (typeof operation.position === "number") pos = operation.position;
+        else if (operation.position === "end") pos = this.view.state.doc.content.size - 2;
+        else if (operation.position === "start") pos = 1;
+        const tr = this.view.state.tr.insertText(operation.text, pos);
+        this.view.dispatch(tr);
+        break;
+      }
+      case "delete": {
+        let start: number, end: number;
+        if (operation.range) {
+          start = operation.range.start;
+          end = operation.range.end;
+        } else if (operation.targetText) {
+          const text = this.view.state.doc.textContent;
+          const idx = text.indexOf(operation.targetText);
+          if (idx === -1) return;
+          start = idx;
+          end = idx + operation.targetText.length;
+        } else return;
+        const tr = this.view.state.tr.delete(start, end);
+        this.view.dispatch(tr);
+        break;
+      }
+      case "replace_all": {
+        const tr = this.view.state.tr.replaceWith(
+          0,
+          this.view.state.doc.content.size,
+          this.view.state.schema.text(operation.replacement)
+        );
+        this.view.dispatch(tr);
+        break;
+      }
+      default:
+        console.warn("[ProseMirrorAdapter] Operation not supported:", operation.type);
+    }
+  }
+
+  private _dispatch() {
+    const tr = this.view.state.tr.setMeta("addToHistory", false);
+    setSegmentsEffect(tr, this.segments);
+    this.view.dispatch(tr);
+  }
+}

package/src/core/bindings/adapters/index.ts

@@ -0,0 +1,2 @@
+export { NativeAdapter } from "./NativeAdapter";
+export { ProseMirrorAdapter } from "./ProseMirrorAdapter";

package/src/core/bindings/binding-factory.ts

@@ -0,0 +1,78 @@
+import type { TargetBinding } from "./TargetBinding";
+import { createContentEditableBinding } from "./targets/contenteditable.binding";
+import { SegmentBindingBridge } from "./SegmentBindingBridge";
+import { createTiptapBinding } from "./targets/tiptap.binding";
+import { createCodeMirrorBinding } from "./targets/codemirror.binding";
+import { createMonacoBinding } from "./targets/monaco.binding";
+import { NativeAdapter } from "./adapters/NativeAdapter";
+import { TiptapInstanceRegistry } from "../../react/registry/registries/TiptapInstanceRegistry";
+import { CodeMirrorInstanceRegistry } from "../../react/registry/registries/CodeMirrorInstanceRegistry";
+import { MonacoInstanceRegistry } from "../../react/registry/registries/MonacoInstanceRegistry";
+import type { EditorType } from "./detect-editor-type";
+
+export interface TargetOptions {
+  mode: TargetMode;
+  context?: string;
+  insertion?: TargetInsertionMode;
+  editor?: EditorType;
+}
+
+export type TargetMode = "write" | "read" | "write+read" | "write+agent";
+export type TargetInsertionMode = "preview-inline" | "final-only" | "preview-floating" | "none";
+
+export interface TargetDescriptor {
+  id: string;
+  element: HTMLElement;
+  editorType: EditorType;
+  mode: TargetMode;
+  insertion: TargetInsertionMode;
+  binding: TargetBinding | null;
+  _focusinListener?: (() => void);
+}
+
+export function createBindingForElement(
+  el: HTMLElement,
+  editorType: EditorType,
+  opts?: TargetOptions
+): TargetBinding | null {
+  switch (editorType) {
+    case "tiptap": {
+      const editor = TiptapInstanceRegistry.get(el);
+      if (!editor) return null;
+      return createTiptapBinding(editor, el);
+    }
+    case "codemirror": {
+      const view = CodeMirrorInstanceRegistry.get(el);
+      if (!view) return null;
+      return createCodeMirrorBinding(view);
+    }
+    case "monaco": {
+      const editor = MonacoInstanceRegistry.get(el);
+      if (!editor) return null;
+      return createMonacoBinding(editor);
+    }
+    case "lexical":
+    case "slate": {
+      console.error(
+        `[ephia] Adapter "${editorType}" n'est pas encore supporté. Dictée désactivée pour cet éditeur.`
+      );
+      return null;
+    }
+    case "contenteditable": {
+      const target =
+        el.getAttribute("contenteditable") === "true"
+          ? el
+          : el.querySelector<HTMLElement>('[contenteditable="true"]') ?? el;
+      return createContentEditableBinding(target);
+    }
+    case "native": {
+      const target =
+        el.tagName === "INPUT" || el.tagName === "TEXTAREA"
+          ? (el as HTMLTextAreaElement | HTMLInputElement)
+          : el.querySelector<HTMLTextAreaElement | HTMLInputElement>("input, textarea");
+      if (!target) return null;
+      const nativeAdapter = new NativeAdapter(target);
+      return new SegmentBindingBridge(nativeAdapter, target);
+    }
+  }
+}

package/src/core/bindings/detect-editor-type.ts

@@ -0,0 +1,87 @@
+export type EditorType =
+  | "tiptap"
+  | "contenteditable"
+  | "native"
+  | "codemirror"
+  | "monaco"
+  | "lexical"
+  | "slate";
+
+/**
+ * Détecte le type d'éditeur d'un élément.
+ *
+ * Ordre de priorité :
+ * 1. data-ephia-editor explicite (source of truth)
+ * 2. Heuristiques structurelles fiables
+ * 3. Récursion sur l'enfant direct si wrapper
+ */
+export function detectEditorType(el: HTMLElement): EditorType {
+  const explicit = el.getAttribute("data-ephia-editor");
+  if (explicit === "tiptap") return "tiptap";
+  if (explicit === "contenteditable") return "contenteditable";
+  if (explicit === "native") return "native";
+  if (explicit === "codemirror") return "codemirror";
+  if (explicit === "monaco") return "monaco";
+  if (explicit === "lexical") return "lexical";
+  if (explicit === "slate") return "slate";
+
+  if (
+    el.classList.contains("cm-editor") ||
+    el.querySelector(".cm-editor") !== null ||
+    el.classList.contains("cm-content")
+  ) {
+    return "codemirror";
+  }
+
+  if (
+    el.classList.contains("monaco-editor") ||
+    el.querySelector(".monaco-editor") !== null
+  ) {
+    return "monaco";
+  }
+
+  if (
+    el.classList.contains("ProseMirror") ||
+    el.querySelector(".ProseMirror") !== null ||
+    el.hasAttribute("data-tiptap")
+  ) {
+    return "tiptap";
+  }
+
+  if (
+    el.hasAttribute("data-lexical-editor") ||
+    el.querySelector("[data-lexical-editor]") !== null
+  ) {
+    console.warn(
+      "[ephia-audio] Lexical détecté. L'injection DOM directe sera neutralisée par la réconciliation Lexical.\n" +
+        "Utilisez useEphiaTarget avec data-ephia-editor=\"contenteditable\" pour forcer le fallback CE, ou attendez un adapter Lexical dédié."
+    );
+    return "lexical";
+  }
+
+  if (
+    el.hasAttribute("data-slate-editor") ||
+    el.querySelector("[data-slate-editor]") !== null
+  ) {
+    console.warn(
+      "[ephia-audio] Slate détecté. L'injection DOM directe sera neutralisée par Slate.\n" +
+        "Utilisez data-ephia-editor=\"contenteditable\" pour forcer le fallback CE, ou attendez un adapter Slate dédié."
+    );
+    return "slate";
+  }
+
+  if (el.getAttribute("contenteditable") === "true") {
+    return "contenteditable";
+  }
+
+  if (el.tagName === "INPUT" || el.tagName === "TEXTAREA") {
+    return "native";
+  }
+
+  const inner = el.querySelector<HTMLElement>(
+    '.cm-editor, .monaco-editor, .ProseMirror, input, textarea, [contenteditable="true"]'
+  );
+  if (inner) return detectEditorType(inner);
+
+  return "native";
+}

package/src/core/bindings/index.ts

@@ -0,0 +1,13 @@
+// ── V2 bindings (EphiaBinding interface + implementations) ──
+export type { EphiaBinding, UpsertSegmentInput, PreviewSegmentInput } from "./EphiaBinding";
+export { NativeBinding } from "./native/NativeBinding";
+export { TiptapBinding, EphiaV2PreviewMark, EphiaV2CommittedMark } from "./tiptap/TiptapBinding";
+
+// ── Legacy TipTap marks (V1 targets) ──
+export {
+  createTiptapBinding as createLegacyTiptapBinding,
+  EphiaCommittedMark,
+  EphiaPlaceholderMark,
+  EphiaPreviewMark,
+  EphiaRevisedMark,
+} from "./targets";

package/src/core/bindings/insertion-boundary.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+import { ensureMinimalAppendBoundary } from "./insertion-boundary";
+
+describe("ensureMinimalAppendBoundary", () => {
+  it("returns incoming unchanged when left is empty", () => {
+    expect(ensureMinimalAppendBoundary("", "Bonjour")).toBe("Bonjour");
+  });
+
+  it("returns incoming unchanged when incoming is empty", () => {
+    expect(ensureMinimalAppendBoundary("texte.", "")).toBe("");
+  });
+
+  it("returns incoming unchanged when left ends with whitespace", () => {
+    expect(ensureMinimalAppendBoundary("texte. ", "Suite")).toBe("Suite");
+  });
+
+  it("returns incoming unchanged when incoming starts with whitespace", () => {
+    expect(ensureMinimalAppendBoundary("texte.", " Suite")).toBe(" Suite");
+  });
+
+  it("returns incoming unchanged when incoming starts with punctuation", () => {
+    expect(ensureMinimalAppendBoundary("texte", ",")).toBe(",");
+    expect(ensureMinimalAppendBoundary("texte", ".")).toBe(".");
+    expect(ensureMinimalAppendBoundary("texte", ":")).toBe(":");
+  });
+
+  it("prepends a space when two words would collide", () => {
+    expect(ensureMinimalAppendBoundary("contraste.", "Indication")).toBe(
+      " Indication",
+    );
+  });
+
+  it("does not add a newline — only a space", () => {
+    const result = ensureMinimalAppendBoundary("fin de phrase.", "Nouvelle phrase.");
+    expect(result).toBe(" Nouvelle phrase.");
+    expect(result).not.toContain("\n");
+  });
+});

package/src/core/bindings/insertion-boundary.ts

@@ -0,0 +1,26 @@
+/**
+ * Safety net: ensures a minimal space is inserted between two words when the
+ * backend sends a segment without any leading whitespace.
+ *
+ * Rules:
+ * - SDK only adds a single space. Never a newline.
+ * - Only applied on the *first* insertion of a segment, not on updates.
+ * - Not applied if the left context already ends with whitespace.
+ * - Not applied if the incoming text starts with whitespace or punctuation.
+ */
+export function ensureMinimalAppendBoundary(
+  leftText: string,
+  incomingText: string,
+): string {
+  if (!leftText || !incomingText) return incomingText;
+
+  const left = leftText.at(-1);
+  const right = incomingText.at(0);
+
+  if (!left || !right) return incomingText;
+  if (/\s/.test(left)) return incomingText;
+  if (/\s/.test(right)) return incomingText;
+  if (/^[,.;:!?)\]}>]/.test(right)) return incomingText;
+
+  return ` ${incomingText}`;
+}