@ephia/dova-sdk 1.0.0

package/src/core/bindings/targets/tiptap.binding.ts

@@ -0,0 +1,1192 @@
+/**
+ * Binding TipTap historique mais encore actif.
+ * Ne pas supprimer tant que createTiptapBinding est utilisé par les intégrations.
+ * Les corrections d'insertion realtime TipTap doivent être faites ici, pas dans ProseMirrorAdapter.
+ */
+
+import type { Editor } from "@tiptap/core";
+import { Mark } from "@tiptap/core";
+import type { Mark as ProseMirrorMark } from "@tiptap/pm/model";
+import { Plugin, PluginKey, TextSelection } from "@tiptap/pm/state";
+import type { Transaction } from "@tiptap/pm/state";
+import type {
+  BeginSessionOptions,
+  CommitFinalOptions,
+  SessionAnchor,
+  TargetBinding,
+} from "../TargetBinding";
+import { pickJoiner } from "../TargetBinding";
+import type { DocumentOperation } from "ephia-protocol";
+import { documentStore } from "../../../shared/store/document-store";
+import { textToDocumentOperations } from "../../operations/textToDocumentOperations";
+import { stripLeadingOverlapFromTextWithInfo } from "../../text-processing/overlap";
+
+// ---------------------------------------------------------------------------
+// ProseMirror Plugin — stocke les positions des segments audio + l'anchor de
+// session, et les mappe automatiquement à chaque transaction (typing, undo).
+// ---------------------------------------------------------------------------
+
+interface EphiaTiptapPluginState {
+  segments: Record<string, { from: number; to: number; revision: number; joinerLength?: number }>;
+  anchor: {
+    initialStart: number;
+    initialEnd: number;
+    hadSelection: boolean;
+    end: number;
+    selectionPendingDelete: boolean;
+  } | null;
+}
+
+const ephiaTiptapKey = new PluginKey<EphiaTiptapPluginState>("ephiaTiptap");
+
+type SegmentUpdate = Record<string, { from: number; to: number; revision: number; joinerLength?: number } | null>;
+type AnchorUpdate =
+  | { kind: "set"; value: EphiaTiptapPluginState["anchor"] }
+  | { kind: "patch"; end?: number }
+  | { kind: "clear" };
+
+interface EphiaMeta {
+  segments?: SegmentUpdate;
+  anchor?: AnchorUpdate;
+}
+
+function createEphiaTiptapPlugin(): Plugin {
+  return new Plugin({
+    key: ephiaTiptapKey,
+    state: {
+      init(): EphiaTiptapPluginState {
+        return { segments: {}, anchor: null };
+      },
+      apply(tr, value): EphiaTiptapPluginState {
+        const docSize = tr.doc.content.size;
+
+        // 1. Mapper les segments existants — clamp + drop hors bornes
+        const mappedSegments: EphiaTiptapPluginState["segments"] = {};
+        for (const [id, pos] of Object.entries(value.segments)) {
+          const mappedFrom = Math.min(Math.max(tr.mapping.map(pos.from), 0), docSize);
+          const mappedTo = Math.min(Math.max(tr.mapping.map(pos.to), 0), docSize);
+          if (mappedFrom < 0 || mappedTo < 0 || mappedFrom > docSize || mappedTo > docSize || mappedFrom > mappedTo) {
+            continue; // segment supprimé / corrompu par undo profond
+          }
+          mappedSegments[id] = {
+            from: mappedFrom,
+            to: mappedTo,
+            revision: pos.revision,
+            joinerLength: pos.joinerLength,
+          };
+        }
+
+        // 2. Mapper l'anchor existant — clamp + drop hors bornes
+        let mappedAnchor = value.anchor
+          ? {
+              initialStart: Math.min(Math.max(tr.mapping.map(value.anchor.initialStart), 0), docSize),
+              initialEnd: Math.min(Math.max(tr.mapping.map(value.anchor.initialEnd), 0), docSize),
+              hadSelection: value.anchor.hadSelection,
+              end: Math.min(Math.max(tr.mapping.map(value.anchor.end), 0), docSize),
+              selectionPendingDelete: value.anchor.selectionPendingDelete,
+            }
+          : null;
+        if (mappedAnchor && (mappedAnchor.initialStart > docSize || mappedAnchor.initialEnd > docSize || mappedAnchor.end > docSize)) {
+          mappedAnchor = null;
+        }
+
+        // 3. Appliquer les mises à jour explicites
+        const meta = tr.getMeta(ephiaTiptapKey) as EphiaMeta | undefined;
+        if (meta) {
+          if (meta.segments) {
+            for (const [id, pos] of Object.entries(meta.segments)) {
+              if (pos === null) delete mappedSegments[id];
+              else mappedSegments[id] = pos;
+            }
+          }
+          if (meta.anchor) {
+            if (meta.anchor.kind === "clear") {
+              mappedAnchor = null;
+            } else if (meta.anchor.kind === "set") {
+              mappedAnchor = meta.anchor.value;
+            } else if (meta.anchor.kind === "patch" && mappedAnchor) {
+              mappedAnchor = {
+                ...mappedAnchor,
+                end: meta.anchor.end ?? mappedAnchor.end,
+              };
+            }
+          }
+        }
+
+        return { segments: mappedSegments, anchor: mappedAnchor };
+      },
+    },
+  });
+}
+
+function getPluginState(editor: Editor): EphiaTiptapPluginState {
+  return (
+    ephiaTiptapKey.getState(editor.state) ?? { segments: {}, anchor: null }
+  );
+}
+
+function setSegmentMeta(
+  tr: Transaction,
+  segmentId: string,
+  pos: { from: number; to: number; revision: number; joinerLength?: number } | null
+): void {
+  const current = (tr.getMeta(ephiaTiptapKey) as EphiaMeta | undefined) ?? {};
+  current.segments = { ...(current.segments ?? {}), [segmentId]: pos };
+  tr.setMeta(ephiaTiptapKey, current);
+}
+
+function setAnchorMeta(tr: Transaction, update: AnchorUpdate): void {
+  const current = (tr.getMeta(ephiaTiptapKey) as EphiaMeta | undefined) ?? {};
+  current.anchor = update;
+  tr.setMeta(ephiaTiptapKey, current);
+}
+
+// ---------------------------------------------------------------------------
+// Helpers — diff intelligent pour éviter delete+insert inutiles
+// ---------------------------------------------------------------------------
+
+function getCommonPrefix(a: string, b: string): number {
+  let i = 0;
+  while (i < a.length && i < b.length && a[i] === b[i]) i++;
+  return i;
+}
+
+function getCommonSuffix(a: string, b: string, prefixLen: number): number {
+  let i = 0;
+  while (
+    i < a.length - prefixLen &&
+    i < b.length - prefixLen &&
+    a[a.length - 1 - i] === b[b.length - 1 - i]
+  ) {
+    i++;
+  }
+  return i;
+}
+
+// ---------------------------------------------------------------------------
+// Scroll helper — throttle + viewport check + user-scroll detection
+// ---------------------------------------------------------------------------
+
+const SCROLL_THROTTLE_MS = 300;
+const USER_SCROLL_QUIET_MS = 500;
+const PARTIAL_DEBOUNCE_MS = 60;
+const SKIP_STORE_SYNC_META = "ephiaSkipStoreSync";
+
+function isPosVisible(editor: Editor, pos: number): boolean {
+  try {
+    const coords = editor.view.coordsAtPos(pos);
+    const rect = editor.view.dom.getBoundingClientRect();
+    return coords.top >= rect.top && coords.bottom <= rect.bottom;
+  } catch {
+    return true; // par défaut, ne pas scroller
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Binding TipTap — session anchor + UX fluide
+// ---------------------------------------------------------------------------
+
+interface ParsedSection {
+  id: string;
+  title: string;
+  text: string;
+  level: number;
+  start: number;
+  end: number;
+}
+
+type ProseMirrorDoc = Editor["state"]["doc"];
+
+function textBetweenWithHardBreaks(
+  doc: ProseMirrorDoc,
+  from: number,
+  to: number,
+  blockSeparator?: string
+): string {
+  return doc.textBetween(from, to, blockSeparator, "\n");
+}
+
+function getTextFromDoc(doc: ProseMirrorDoc): string {
+  return textBetweenWithHardBreaks(doc, 0, doc.content.size, "\n\n");
+}
+
+function resolveInsertPosition(
+  editor: Editor,
+  position?: number | "cursor" | "start" | "end"
+): number {
+  if (typeof position === "number") {
+    return Math.min(Math.max(position, 0), editor.state.doc.content.size);
+  }
+  if (position === "start") return 1;
+  if (position === "end") return Math.max(1, editor.state.doc.content.size - 1);
+  return editor.state.selection.from;
+}
+
+function insertOperationsAt(
+  editor: Editor,
+  tr: Transaction,
+  pos: number,
+  operations: DocumentOperation[],
+  mark?: ProseMirrorMark
+): { from: number; to: number; fallbackSteps: string[] } {
+  let cursor = pos;
+  const fallbackSteps: string[] = [];
+  const hardBreak = editor.schema.nodes.hardBreak;
+  const marks = mark ? [mark] : [];
+
+  const insertText = (text: string) => {
+    if (!text) return;
+    const node = editor.schema.text(text, marks);
+    tr.insert(cursor, node);
+    cursor += node.nodeSize;
+  };
+
+  const insertHardBreakOrFallback = () => {
+    if (hardBreak) {
+      const node = hardBreak.create();
+      tr.insert(cursor, node);
+      cursor += node.nodeSize;
+      return;
+    }
+    const node = editor.schema.text("\n", marks);
+    tr.insert(cursor, node);
+    cursor += node.nodeSize;
+    fallbackSteps.push("fallback_plain_newline_no_hardbreak_node");
+  };
+
+  for (const operation of operations) {
+    if (operation.type === "insert_text" || operation.type === "insert") {
+      insertText(operation.text);
+    } else if (operation.type === "line_break") {
+      insertHardBreakOrFallback();
+    } else if (operation.type === "paragraph_break") {
+      insertHardBreakOrFallback();
+      insertHardBreakOrFallback();
+    }
+  }
+
+  return { from: pos, to: cursor, fallbackSteps };
+}
+
+function measureOperationsSize(editor: Editor, operations: DocumentOperation[]): number {
+  const hardBreak = editor.schema.nodes.hardBreak;
+  let size = 0;
+  for (const operation of operations) {
+    if (operation.type === "insert_text" || operation.type === "insert") {
+      if (operation.text) {
+        size += editor.schema.text(operation.text).nodeSize;
+      }
+    } else if (operation.type === "line_break") {
+      size += hardBreak ? hardBreak.create().nodeSize : editor.schema.text("\n").nodeSize;
+    } else if (operation.type === "paragraph_break") {
+      const breakSize = hardBreak ? hardBreak.create().nodeSize : editor.schema.text("\n").nodeSize;
+      size += breakSize * 2;
+    }
+  }
+  return size;
+}
+
+function measureTextAsOperationsSize(editor: Editor, text: string): number {
+  return measureOperationsSize(editor, textToDocumentOperations(text));
+}
+
+function parseSegmentsFromDoc(doc: ProseMirrorDoc): ParsedSection[] {
+  const segments: ParsedSection[] = [];
+  let currentSection: ParsedSection | null = null;
+  let offset = 0;
+
+  doc.descendants((node, _pos) => {
+    if (node.type.name === "heading") {
+      if (currentSection) currentSection.end = offset;
+      currentSection = {
+        id: `sec_${segments.length}`,
+        title: node.textContent,
+        text: "",
+        level: node.attrs.level || 1,
+        start: offset,
+        end: offset,
+      };
+      segments.push(currentSection);
+    } else if (currentSection && node.isTextblock) {
+      currentSection.text +=
+        (currentSection.text ? "\n" : "") + node.textContent;
+    }
+    offset += node.nodeSize;
+    return true;
+  });
+
+  if (currentSection) {
+    (currentSection as ParsedSection).end = offset;
+  }
+  return segments;
+}
+
+function parseSegmentsFromEditor(editor: Editor): ParsedSection[] {
+  return parseSegmentsFromDoc(editor.state.doc);
+}
+
+/** Convertit l'anchor du plugin (positions PM) vers l'interface publique. */
+function toPublicAnchor(
+  anchor: NonNullable<EphiaTiptapPluginState["anchor"]>
+): SessionAnchor {
+  return {
+    initialStart: anchor.initialStart,
+    initialEnd: anchor.initialEnd,
+    hadSelection: anchor.hadSelection,
+    end: anchor.end,
+    selectionPendingDelete: anchor.selectionPendingDelete,
+  };
+}
+
+/* ── TipTap Marks ─────────────────────────────────────────────────────────── */
+
+/** Mark affiché sur le texte en cours de streaming (preview temps réel). */
+export const EphiaPreviewMark = Mark.create({
+  name: "ephiaPreview",
+  parseHTML() {
+    return [{ tag: "span[data-ephia-streaming]" }];
+  },
+  renderHTML() {
+    return [
+      "span",
+      {
+        "data-ephia-streaming": "true",
+        class: "ephia-text--streaming",
+      },
+      0,
+    ];
+  },
+});
+
+/** Mark temporaire affiché pendant la transition committed (streaming → normal). */
+export const EphiaCommittedMark = Mark.create({
+  name: "ephiaCommitted",
+  parseHTML() {
+    return [{ tag: "span[data-ephia-committed]" }];
+  },
+  renderHTML() {
+    return [
+      "span",
+      {
+        "data-ephia-committed": "true",
+        class: "ephia-text--committed",
+      },
+      0,
+    ];
+  },
+});
+
+/** Mark affiché sur le texte corrigé par le review pipeline. */
+export const EphiaRevisedMark = Mark.create({
+  name: "ephiaRevised",
+  parseHTML() {
+    return [{ tag: "span[data-ephia-revised]" }];
+  },
+  renderHTML() {
+    return [
+      "span",
+      {
+        "data-ephia-revised": "true",
+        class: "ephia-text--revised",
+      },
+      0,
+    ];
+  },
+});
+
+/** Mark affiché sur le placeholder de démarrage (interim avant le premier partial). */
+export const EphiaPlaceholderMark = Mark.create({
+  name: "ephiaPlaceholder",
+  parseHTML() {
+    return [{ tag: "span[data-ephia-placeholder]" }];
+  },
+  renderHTML() {
+    return [
+      "span",
+      {
+        "data-ephia-placeholder": "true",
+        class: "ephia-text--placeholder",
+      },
+      0,
+    ];
+  },
+});
+
+export function createTiptapBinding(editor: Editor, wrapperEl?: HTMLElement): TargetBinding {
+  const plugin = createEphiaTiptapPlugin();
+  editor.registerPlugin(plugin);
+  let lastScrollTime = 0;
+  let lastUserScrollTime = 0;
+  let lastDictationEnd: number | null = null;
+  let cachedSectionsDoc = editor.state.doc;
+  let cachedSections = parseSegmentsFromEditor(editor);
+
+  const markUserScroll = () => {
+    lastUserScrollTime = Date.now();
+  };
+
+  const maybeScrollIntoView = (tr: Transaction, ed: Editor, pos: number): void => {
+    const now = Date.now();
+    if (now - lastUserScrollTime < USER_SCROLL_QUIET_MS) return;
+    if (now - lastScrollTime < SCROLL_THROTTLE_MS) return;
+    if (isPosVisible(ed, pos)) return;
+    tr.scrollIntoView();
+    lastScrollTime = now;
+  };
+
+  editor.view.dom.addEventListener("scroll", markUserScroll, { passive: true });
+
+  // Timeouts de transition committed à nettoyer au detach.
+  const committedTimeouts = new Map<string, number>();
+  const knownSegmentIds = new Set<string>();
+
+  const clearCommittedTimeout = (segmentId: string): void => {
+    const timeoutId = committedTimeouts.get(segmentId);
+    if (timeoutId !== undefined) {
+      window.clearTimeout(timeoutId);
+      committedTimeouts.delete(segmentId);
+    }
+  };
+
+  // Sync to Zustand store — debouncé via rAF pour éviter de re-parser tout le
+  // doc (getText + parseSegments) à chaque transaction pendant le streaming.
+  // Sur une dictée fluide, on reçoit plusieurs partials/sec : sans debounce
+  // ça multiplie par N le coût des subscribers du store.
+  let syncRaf: number | null = null;
+  let pendingSyncDoc: ProseMirrorDoc | null = null;
+  const getCachedSections = (): ParsedSection[] => cachedSections;
+
+  const syncToStore = (event?: { transaction?: Transaction }) => {
+    if (event?.transaction?.getMeta(SKIP_STORE_SYNC_META)) return;
+    pendingSyncDoc = event?.transaction?.doc ?? editor.state.doc;
+    if (syncRaf !== null) return;
+    syncRaf = (typeof requestAnimationFrame !== "undefined"
+      ? requestAnimationFrame
+      : (cb: FrameRequestCallback) => setTimeout(cb, 16) as unknown as number)(
+      () => {
+        syncRaf = null;
+        const doc = pendingSyncDoc ?? editor.state.doc;
+        pendingSyncDoc = null;
+        const text = getTextFromDoc(doc);
+        cachedSectionsDoc = doc;
+        cachedSections = parseSegmentsFromDoc(doc);
+        const segments = cachedSections;
+        documentStore.getState().syncFromEditor(text, segments);
+      }
+    );
+  };
+
+  const syncSelection = () => {
+    const { from, to } = editor.state.selection;
+    const selectedText =
+      from !== to ? textBetweenWithHardBreaks(editor.state.doc, from, to) : null;
+    if (cachedSectionsDoc !== editor.state.doc && cachedSections.length === 0) {
+      cachedSectionsDoc = editor.state.doc;
+      cachedSections = parseSegmentsFromEditor(editor);
+    }
+    const cursor = editor.state.selection.from;
+    const section =
+      getCachedSections().find((seg) => cursor >= seg.start && cursor <= seg.end)
+        ?.title ?? null;
+    documentStore.getState().setSelection(selectedText, section);
+  };
+
+  editor.on("update", syncToStore);
+  editor.on("selectionUpdate", syncSelection);
+
+  syncToStore();
+  syncSelection();
+
+  const _applyPartial = (segmentId: string, text: string, revision: number): void => {
+      const state = getPluginState(editor);
+      const existing = state.segments[segmentId];
+      const isPlaceholder = segmentId === "ephia-startup-placeholder";
+      const mark = isPlaceholder
+        ? editor.schema.marks.ephiaPlaceholder?.create()
+        : editor.schema.marks.ephiaPreview?.create();
+
+      if (existing) {
+        // Réordering réseau : rejeter une révision périmée
+        if (revision <= existing.revision) return;
+
+        const oldText = textBetweenWithHardBreaks(editor.state.doc, existing.from, existing.to);
+        if (oldText === text) return;
+
+        const tr = editor.state.tr;
+        tr.setMeta("addToHistory", false);
+        tr.setMeta(SKIP_STORE_SYNC_META, true);
+
+        const prefixLen = getCommonPrefix(oldText, text);
+        const suffixLen = getCommonSuffix(oldText, text, prefixLen);
+
+        if (prefixLen > 0 || suffixLen > 0) {
+          const deleteFrom = existing.from + prefixLen;
+          const deleteTo = existing.to - suffixLen;
+          const insertText = text.slice(prefixLen, text.length - suffixLen);
+
+          if (deleteFrom < deleteTo) tr.delete(deleteFrom, deleteTo);
+          if (insertText) {
+            insertOperationsAt(
+              editor,
+              tr,
+              deleteFrom,
+              textToDocumentOperations(insertText),
+              mark
+            );
+          }
+          const newEnd = existing.from + measureTextAsOperationsSize(editor, text);
+          setSegmentMeta(tr, segmentId, {
+            from: existing.from,
+            to: newEnd,
+            revision,
+            joinerLength: existing.joinerLength,
+          });
+        } else {
+          tr.delete(existing.from, existing.to);
+          const inserted = insertOperationsAt(
+            editor,
+            tr,
+            existing.from,
+            textToDocumentOperations(text),
+            mark
+          );
+          setSegmentMeta(tr, segmentId, {
+            from: existing.from,
+            to: inserted.to,
+            revision,
+            joinerLength: existing.joinerLength,
+          });
+        }
+
+        // L'anchor.end est mappé automatiquement via tr.mapping
+        maybeScrollIntoView(tr, editor, existing.to);
+        editor.view.dispatch(tr);
+        knownSegmentIds.add(segmentId);
+      } else {
+        // Nouveau segment → insérer à l'anchor (ou au curseur si pas de session)
+        if (!state.anchor) {
+          return; // session terminée → rejeter le partial fantôme
+        }
+
+        const tr = editor.state.tr;
+        tr.setMeta("addToHistory", false);
+        tr.setMeta(SKIP_STORE_SYNC_META, true);
+
+        // Suppression lazy de la sélection : si une sélection était en attente,
+        // la supprimer atomiquement avec le premier insert dicté.
+        let pos = state.anchor.end;
+        if (
+          state.anchor.selectionPendingDelete &&
+          state.anchor.initialEnd > state.anchor.initialStart
+        ) {
+          tr.delete(state.anchor.initialStart, state.anchor.initialEnd);
+          pos = state.anchor.initialStart;
+          setAnchorMeta(tr, {
+            kind: "set",
+            value: {
+              ...state.anchor,
+              selectionPendingDelete: false,
+              initialEnd: state.anchor.initialStart,
+              end: state.anchor.initialStart,
+            },
+          });
+        }
+
+        const before = textBetweenWithHardBreaks(editor.state.doc, Math.max(0, pos - 500), pos);
+        const overlap = stripLeadingOverlapFromTextWithInfo(before, text);
+        text = overlap.text;
+        if (!text) return;
+        const joiner = overlap.partialWord ? "" : pickJoiner(before, text);
+
+        const fullText = joiner + text;
+        const inserted = insertOperationsAt(
+          editor,
+          tr,
+          pos,
+          textToDocumentOperations(fullText),
+          mark
+        );
+
+        const segFrom = pos + measureTextAsOperationsSize(editor, joiner);
+        const segTo = inserted.to;
+        setSegmentMeta(tr, segmentId, { from: segFrom, to: segTo, revision, joinerLength: joiner.length });
+        setAnchorMeta(tr, { kind: "patch", end: segTo });
+
+        maybeScrollIntoView(tr, editor, segTo);
+        editor.view.dispatch(tr);
+        knownSegmentIds.add(segmentId);
+      }
+  };
+
+  // ── Debounce réel des partials, par segment, pour réduire les transactions PM. ──
+  const pendingPartials = new Map<
+    string,
+    { text: string; revision: number; timer: ReturnType<typeof setTimeout> }
+  >();
+
+  const flushPendingPartial = (segmentId: string) => {
+    const pending = pendingPartials.get(segmentId);
+    if (!pending) return;
+    clearTimeout(pending.timer);
+    pendingPartials.delete(segmentId);
+    _applyPartial(segmentId, pending.text, pending.revision);
+  };
+
+  const cancelPendingPartial = (segmentId: string) => {
+    const pending = pendingPartials.get(segmentId);
+    if (!pending) return;
+    clearTimeout(pending.timer);
+    pendingPartials.delete(segmentId);
+  };
+
+  const cancelAllPendingPartials = () => {
+    for (const { timer } of pendingPartials.values()) {
+      clearTimeout(timer);
+    }
+    pendingPartials.clear();
+  };
+
+  const schedulePartial = (segmentId: string, text: string, revision: number) => {
+    const existing = pendingPartials.get(segmentId);
+    if (existing) {
+      if (revision < existing.revision) return;
+      clearTimeout(existing.timer);
+    }
+    const timer = setTimeout(() => flushPendingPartial(segmentId), PARTIAL_DEBOUNCE_MS);
+    pendingPartials.set(segmentId, { text, revision, timer });
+  };
+
+  const trimOverlappingPreviewSegments = (
+    tr: Transaction,
+    state: EphiaTiptapPluginState,
+    committedSegmentId: string,
+    committedText: string
+  ): void => {
+    const previewMark = editor.schema.marks.ephiaPreview?.create();
+    for (const [otherId, other] of Object.entries(state.segments)) {
+      if (otherId === committedSegmentId || other.revision === Number.MAX_SAFE_INTEGER) {
+        continue;
+      }
+      const previewText = textBetweenWithHardBreaks(editor.state.doc, other.from, other.to);
+      const overlap = stripLeadingOverlapFromTextWithInfo(committedText, previewText);
+      const trimmed = overlap.text;
+      if (trimmed === previewText) continue;
+
+      let from = tr.mapping.map(other.from);
+      let to = tr.mapping.map(other.to);
+      if (overlap.partialWord && from > 0 && /\s/.test(textBetweenWithHardBreaks(tr.doc, from - 1, from))) {
+        tr.delete(from - 1, from);
+        from -= 1;
+        to -= 1;
+      }
+      if (trimmed) {
+        tr.delete(from, to);
+        const inserted = insertOperationsAt(
+          editor,
+          tr,
+          from,
+          textToDocumentOperations(trimmed),
+          previewMark
+        );
+        setSegmentMeta(tr, otherId, {
+          from,
+          to: inserted.to,
+          revision: other.revision + 1,
+        });
+      } else {
+        tr.delete(from, to);
+        setSegmentMeta(tr, otherId, null);
+      }
+    }
+  };
+
+  return {
+    kind: "tiptap",
+
+    attach(): void {
+      /* Plugin déjà enregistré */
+    },
+
+    detach(): void {
+      editor.view.dom.removeEventListener("scroll", markUserScroll);
+      editor.unregisterPlugin(ephiaTiptapKey);
+      editor.off("update", syncToStore);
+      editor.off("selectionUpdate", syncSelection);
+      cancelAllPendingPartials();
+      if (syncRaf !== null && typeof cancelAnimationFrame !== "undefined") {
+        cancelAnimationFrame(syncRaf);
+        syncRaf = null;
+      }
+      // Annuler les timeouts committed en attente
+      for (const timeoutId of committedTimeouts.values()) {
+        clearTimeout(timeoutId);
+      }
+      committedTimeouts.clear();
+      knownSegmentIds.clear();
+    },
+
+    // ─── Session lifecycle ──────────────────────────────────────────────────
+    beginSession(opts: BeginSessionOptions = {}): SessionAnchor {
+      const replaceSelection = opts.replaceSelection ?? true;
+      const isFocused = editor.isFocused;
+
+      // Si l'éditeur n'a jamais reçu le focus, la sélection est par défaut au
+      // début du doc (pos 1) — on retombe alors sur la fin du document pour
+      // un comportement type Dragon Medical (insertion à la suite).
+      let from = editor.state.selection.from;
+      let to = editor.state.selection.to;
+      if (!isFocused && from === to) {
+        const docSize = editor.state.doc.content.size;
+        const resumePos = lastDictationEnd !== null
+          ? Math.min(lastDictationEnd, Math.max(1, docSize - 1))
+          : Math.max(1, docSize - 1);
+        from = resumePos;
+        to = resumePos;
+      }
+      const hadSelection = from !== to;
+      const selectionPendingDelete = hadSelection && replaceSelection;
+
+      const tr = editor.state.tr;
+      tr.setMeta("addToHistory", false);
+      tr.setMeta(SKIP_STORE_SYNC_META, true);
+
+      // Ne pas supprimer la sélection ici — la suppression est différée
+      // au premier insert (insertPartial / commitFinal) pour que l'user
+      // voie encore le texte sélectionné pendant la connexion au serveur.
+
+      const anchorValue = {
+        initialStart: from,
+        initialEnd: to,        // conserver la vraie fin de sélection
+        hadSelection,
+        end: from,             // point d'insertion = début de sélection
+        selectionPendingDelete,
+      };
+
+      // Place le curseur PM au début de la sélection (sans la supprimer).
+      try {
+        const resolved = tr.doc.resolve(from);
+        tr.setSelection(TextSelection.near(resolved));
+      } catch {
+        // Position hors bornes : on laisse PM gérer
+      }
+
+      setAnchorMeta(tr, { kind: "set", value: anchorValue });
+      editor.view.dispatch(tr);
+
+      // Re-focus l'éditeur pour que la barre clignotante soit visible
+      if (!isFocused) {
+        try {
+          editor.view.focus();
+        } catch {
+          /* noop */
+        }
+      }
+
+      return toPublicAnchor(anchorValue);
+    },
+
+    endSession(): void {
+      cancelAllPendingPartials();
+      const anchor = getPluginState(editor).anchor;
+      if (anchor) lastDictationEnd = anchor.end;
+      const tr = editor.state.tr;
+      tr.setMeta("addToHistory", false);
+      tr.setMeta(SKIP_STORE_SYNC_META, true);
+      setAnchorMeta(tr, { kind: "clear" });
+      // Nettoyer aussi les marks committed en cours d'animation
+      const committedMark = editor.schema.marks.ephiaCommitted;
+      if (committedMark) {
+        tr.removeMark(0, editor.state.doc.content.size, committedMark);
+      }
+      editor.view.dispatch(tr);
+      syncToStore();
+    },
+
+    getSessionAnchor(): SessionAnchor | null {
+      const anchor = getPluginState(editor).anchor;
+      return anchor ? toPublicAnchor(anchor) : null;
+    },
+
+    getCursorRect(): DOMRect | null {
+      const anchor = getPluginState(editor).anchor;
+      const pos = anchor ? anchor.end : editor.state.selection.from;
+      try {
+        const coords = editor.view.coordsAtPos(pos);
+        // coords = { top, bottom, left, right }
+        return new DOMRect(
+          coords.left,
+          coords.top,
+          coords.right - coords.left,
+          coords.bottom - coords.top
+        );
+      } catch {
+        const dom = editor.view.dom as HTMLElement;
+        return dom.getBoundingClientRect();
+      }
+    },
+
+    getRangeRect(start: number, end: number): DOMRect | null {
+      if (end <= start) return null;
+      try {
+        const a = editor.view.coordsAtPos(start);
+        const b = editor.view.coordsAtPos(end);
+        const top = Math.min(a.top, b.top);
+        const bottom = Math.max(a.bottom, b.bottom);
+        const left = Math.min(a.left, b.left);
+        const right = Math.max(a.right, b.right);
+        return new DOMRect(left, top, Math.max(2, right - left), bottom - top);
+      } catch {
+        return null;
+      }
+    },
+
+    // ─── Streaming insertion ────────────────────────────────────────────────
+    insertPartial(segmentId: string, text: string, revision: number): void {
+      schedulePartial(segmentId, text, revision);
+    },
+
+    commitFinal(segmentId: string, text: string, options?: CommitFinalOptions): void {
+      clearCommittedTimeout(segmentId);
+      flushPendingPartial(segmentId);
+      const state = getPluginState(editor);
+      const existing = state.segments[segmentId];
+      if (!existing && knownSegmentIds.has(segmentId)) {
+        console.warn("[ephia:tiptap] known segmentId lost range; refusing append", {
+          segmentId,
+          text,
+        });
+        return;
+      }
+
+      if (existing) {
+        // Commit final = entrée undo : ⌘Z doit pouvoir revenir avant le commit
+        const tr = editor.state.tr;
+
+        const oldText = textBetweenWithHardBreaks(editor.state.doc, existing.from, existing.to);
+        let newEnd = existing.from + measureTextAsOperationsSize(editor, text);
+
+        if (oldText !== text) {
+          const prefixLen = getCommonPrefix(oldText, text);
+          const suffixLen = getCommonSuffix(oldText, text, prefixLen);
+
+          if (prefixLen > 0 || suffixLen > 0) {
+            const deleteFrom = existing.from + prefixLen;
+            const deleteTo = existing.to - suffixLen;
+            const insertText = text.slice(prefixLen, text.length - suffixLen);
+            if (deleteFrom < deleteTo) tr.delete(deleteFrom, deleteTo);
+            if (insertText) {
+              insertOperationsAt(
+                editor,
+                tr,
+                deleteFrom,
+                textToDocumentOperations(insertText)
+              );
+            }
+            newEnd = existing.from + measureTextAsOperationsSize(editor, text);
+          } else {
+            tr.delete(existing.from, existing.to);
+            const inserted = insertOperationsAt(
+              editor,
+              tr,
+              existing.from,
+              textToDocumentOperations(text)
+            );
+            newEnd = inserted.to;
+          }
+        }
+
+        tr.removeMark(existing.from, newEnd, editor.schema.marks.ephiaPreview);
+
+        // Transition visuelle : mark committed pour le fade-out lavande → vert
+        const committedMark = editor.schema.marks.ephiaCommitted?.create();
+        if (committedMark) {
+          tr.addMark(existing.from, newEnd, committedMark);
+        }
+
+        setSegmentMeta(tr, segmentId, {
+          from: existing.from,
+          to: newEnd,
+          revision: Number.MAX_SAFE_INTEGER,
+          joinerLength: existing.joinerLength,
+        });
+        if (state.anchor) {
+          setAnchorMeta(tr, { kind: "patch", end: newEnd });
+        }
+        lastDictationEnd = newEnd;
+        trimOverlappingPreviewSegments(tr, state, segmentId, text);
+
+        for (const absorbedId of options?.absorbedSegmentIds ?? []) {
+          if (absorbedId === segmentId) continue;
+          cancelPendingPartial(absorbedId);
+          const absorbedSeg = state.segments[absorbedId];
+          if (!absorbedSeg) continue;
+          const aFrom = tr.mapping.map(absorbedSeg.from - (absorbedSeg.joinerLength ?? 0));
+          const aTo = tr.mapping.map(absorbedSeg.to);
+          if (aFrom < aTo) tr.delete(aFrom, aTo);
+          setSegmentMeta(tr, absorbedId, null);
+        }
+
+        maybeScrollIntoView(tr, editor, newEnd);
+        editor.view.dispatch(tr);
+        knownSegmentIds.add(segmentId);
+
+        // Retirer la mark committed après l'animation (1.2s + marge)
+        if (committedMark) {
+          const timeoutId = window.setTimeout(() => {
+            committedTimeouts.delete(segmentId);
+            const freshState = getPluginState(editor);
+            const seg = freshState.segments[segmentId];
+            if (seg && editor.schema.marks.ephiaCommitted) {
+              const tr2 = editor.state.tr;
+              tr2.setMeta("addToHistory", false);
+              tr2.setMeta(SKIP_STORE_SYNC_META, true);
+              tr2.removeMark(seg.from, seg.to, editor.schema.marks.ephiaCommitted);
+              editor.view.dispatch(tr2);
+            }
+          }, 1300);
+          committedTimeouts.set(segmentId, timeoutId);
+        }
+      } else {
+        // Pas de partial préalable → insérer à l'anchor (avec joiner) ou au curseur
+        const tr = editor.state.tr;
+
+        // Suppression lazy de la sélection (même logique que dans _applyPartial)
+        let pos = state.anchor ? state.anchor.end : editor.state.selection.from;
+        if (
+          state.anchor?.selectionPendingDelete &&
+          state.anchor.initialEnd > state.anchor.initialStart
+        ) {
+          tr.delete(state.anchor.initialStart, state.anchor.initialEnd);
+          pos = state.anchor.initialStart;
+          setAnchorMeta(tr, {
+            kind: "set",
+            value: {
+              ...state.anchor,
+              selectionPendingDelete: false,
+              initialEnd: state.anchor.initialStart,
+              end: state.anchor.initialStart,
+            },
+          });
+        }
+
+        let joiner = "";
+        if (state.anchor) {
+          const before = textBetweenWithHardBreaks(editor.state.doc, Math.max(0, pos - 500), pos);
+          const overlap = stripLeadingOverlapFromTextWithInfo(before, text);
+          text = overlap.text;
+          if (!text) return;
+          joiner = overlap.partialWord ? "" : pickJoiner(before, text);
+        }
+
+        const fullText = joiner + text;
+        const inserted = insertOperationsAt(
+          editor,
+          tr,
+          pos,
+          textToDocumentOperations(fullText)
+        );
+
+        const segFrom = pos + measureTextAsOperationsSize(editor, joiner);
+        const segTo = inserted.to;
+        setSegmentMeta(tr, segmentId, {
+          from: segFrom,
+          to: segTo,
+          revision: Number.MAX_SAFE_INTEGER,
+          joinerLength: joiner.length,
+        });
+
+        if (state.anchor) {
+          setAnchorMeta(tr, { kind: "patch", end: segTo });
+        }
+        lastDictationEnd = segTo;
+
+        trimOverlappingPreviewSegments(tr, state, segmentId, text);
+
+        for (const absorbedId of options?.absorbedSegmentIds ?? []) {
+          if (absorbedId === segmentId) continue;
+          cancelPendingPartial(absorbedId);
+          const absorbedSeg = state.segments[absorbedId];
+          if (!absorbedSeg) continue;
+          const aFrom = tr.mapping.map(absorbedSeg.from - (absorbedSeg.joinerLength ?? 0));
+          const aTo = tr.mapping.map(absorbedSeg.to);
+          if (aFrom < aTo) tr.delete(aFrom, aTo);
+          setSegmentMeta(tr, absorbedId, null);
+        }
+
+        maybeScrollIntoView(tr, editor, segTo);
+        editor.view.dispatch(tr);
+        knownSegmentIds.add(segmentId);
+      }
+    },
+
+    clearPartial(segmentId: string): void {
+      cancelPendingPartial(segmentId);
+      const state = getPluginState(editor);
+      const existing = state.segments[segmentId];
+
+      if (existing) {
+        if (existing.revision === Number.MAX_SAFE_INTEGER) {
+          return;
+        }
+        const tr = editor.state.tr;
+        tr.setMeta("addToHistory", false);
+        tr.setMeta(SKIP_STORE_SYNC_META, true);
+        tr.delete(existing.from - (existing.joinerLength ?? 0), existing.to);
+        setSegmentMeta(tr, segmentId, null);
+        editor.view.dispatch(tr);
+      }
+    },
+
+    clearAll(): void {
+      cancelAllPendingPartials();
+      const state = getPluginState(editor);
+      const previewEntries = Object.entries(state.segments).filter(
+        ([, seg]) => seg.revision !== Number.MAX_SAFE_INTEGER
+      );
+      if (previewEntries.length === 0) return;
+
+      const tr = editor.state.tr;
+      tr.setMeta("addToHistory", false);
+      tr.setMeta(SKIP_STORE_SYNC_META, true);
+      for (const [segmentId, seg] of previewEntries.sort(
+        (a, b) => b[1].from - a[1].from
+      )) {
+        const from = tr.mapping.map(seg.from - (seg.joinerLength ?? 0));
+        const to = tr.mapping.map(seg.to);
+        if (from < to) tr.delete(from, to);
+        setSegmentMeta(tr, segmentId, null);
+      }
+      editor.view.dispatch(tr);
+    },
+
+    getText(): string {
+      return getTextFromDoc(editor.state.doc);
+    },
+
+    getSelection() {
+      const { from, to } = editor.state.selection;
+      if (from === to) return null;
+      return {
+        text: textBetweenWithHardBreaks(editor.state.doc, from, to),
+        range: { start: from, end: to },
+      };
+    },
+
+    getCursorOffset(): number | null {
+      return editor.state.selection.from;
+    },
+
+    applyOperation(operation: DocumentOperation): void {
+      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 text = editor.getText();
+            const idx = text.indexOf(operation.targetText);
+            if (idx === -1) {
+              console.warn(
+                "[tiptapBinding] replace ignored: targetText not found"
+              );
+              return;
+            }
+            start = idx;
+            end = idx + operation.targetText.length;
+          } else {
+            console.warn(
+              "[tiptapBinding] replace ignored: missing range or targetText"
+            );
+            return;
+          }
+
+          editor
+            .chain()
+            .deleteRange({ from: start, to: end })
+            .insertContentAt(start, [{ type: "text", text: operation.replacement }])
+            .run();
+          break;
+        }
+
+        case "insert":
+        case "insert_text":
+        case "line_break":
+        case "paragraph_break": {
+          const pos = resolveInsertPosition(editor, operation.position);
+          const tr = editor.state.tr;
+          insertOperationsAt(editor, tr, pos, [operation]);
+          editor.view.dispatch(tr);
+          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 text = editor.getText();
+            const idx = text.indexOf(operation.targetText);
+            if (idx === -1) {
+              console.warn(
+                "[tiptapBinding] delete ignored: targetText not found"
+              );
+              return;
+            }
+            start = idx;
+            end = idx + operation.targetText.length;
+          } else {
+            console.warn(
+              "[tiptapBinding] delete ignored: missing range or targetText"
+            );
+            return;
+          }
+
+          editor.chain().deleteRange({ from: start, to: end }).run();
+          break;
+        }
+
+        case "replace_all": {
+          editor.chain().setContent([{ type: "paragraph", content: [{ type: "text", text: operation.replacement }] }]).run();
+          break;
+        }
+
+        default:
+          console.warn(
+            "[tiptapBinding] Operation not supported:",
+            operation.type
+          );
+      }
+    },
+
+    applyOperations(operations: DocumentOperation[]): void {
+      if (operations.length === 0) return;
+      const firstInsertOperation = operations.find(
+        (operation) =>
+          operation.type === "insert" ||
+          operation.type === "insert_text" ||
+          operation.type === "line_break" ||
+          operation.type === "paragraph_break"
+      );
+      if (!firstInsertOperation) {
+        for (const operation of operations) {
+          console.warn(
+            "[tiptapBinding] Operation not supported in applyOperations:",
+            operation.type
+          );
+        }
+        return;
+      }
+
+      const tr = editor.state.tr;
+      const pos = resolveInsertPosition(editor, firstInsertOperation.position);
+      insertOperationsAt(editor, tr, pos, operations);
+      editor.view.dispatch(tr);
+    },
+  };
+}