@ephia/dova-sdk 1.0.0

package/src/core/bindings/tiptap/TiptapBinding.test.ts

@@ -0,0 +1,63 @@
+// @vitest-environment jsdom
+
+import { describe, expect, it } from 'vitest'
+import { Editor, Node } from '@tiptap/core'
+import { TiptapBinding, EphiaV2PreviewMark, EphiaV2CommittedMark } from './TiptapBinding'
+
+const DocumentNode = Node.create({ name: 'doc', topNode: true, content: 'block+' })
+const ParagraphNode = Node.create({
+  name: 'paragraph',
+  group: 'block',
+  content: 'inline*',
+  parseHTML: () => [{ tag: 'p' }],
+  renderHTML: () => ['p', 0],
+})
+const TextNode = Node.create({ name: 'text', group: 'inline' })
+
+function createEditor(content = '<p></p>'): Editor {
+  return new Editor({
+    element: document.createElement('div'),
+    extensions: [DocumentNode, ParagraphNode, TextNode, EphiaV2PreviewMark, EphiaV2CommittedMark],
+    content,
+  })
+}
+
+describe('TiptapBinding upsertSegment', () => {
+  it('replaces the active selection when inserting a new segment', () => {
+    const editor = createEditor('<p>Texte avant sélection texte après</p>')
+    try {
+      const binding = new TiptapBinding(editor)
+      binding.attach()
+
+      // Sélectionner "sélection"
+      editor.commands.setTextSelection({ from: 13, to: 22 })
+      expect(editor.state.doc.textContent).toContain('sélection')
+
+      binding.upsertSegment({ id: 'seg-1', text: 'remplacement', stage: 'committed', isFinal: true })
+
+      const text = editor.state.doc.textContent
+      expect(text).toContain('remplacement')
+      expect(text).toContain('texte après')
+      expect(text).not.toContain('sélection')
+    } finally {
+      editor.destroy()
+    }
+  })
+
+  it('inserts at cursor when there is no selection', () => {
+    const editor = createEditor('<p>Texte avant </p>')
+    try {
+      const binding = new TiptapBinding(editor)
+      binding.attach()
+
+      // Positionner le curseur à la fin
+      editor.commands.setTextSelection(14)
+
+      binding.upsertSegment({ id: 'seg-1', text: 'ajout', stage: 'committed', isFinal: true })
+
+      expect(editor.state.doc.textContent).toBe('Texte avant ajout')
+    } finally {
+      editor.destroy()
+    }
+  })
+})

package/src/core/bindings/tiptap/TiptapBinding.ts

@@ -0,0 +1,464 @@
+import type { Editor } from "@tiptap/core";
+import { Mark } from "@tiptap/core";
+import { Plugin, PluginKey } from "@tiptap/pm/state";
+import type { Transaction } from "@tiptap/pm/state";
+import type { Mark as ProseMirrorMark } from "@tiptap/pm/model";
+import type { EditorContext } from "ephia-protocol";
+import type { EphiaBinding, PreviewSegmentInput, UpsertSegmentInput } from "../EphiaBinding";
+import { textToDocumentOperations } from "../../operations/textToDocumentOperations";
+import { ensureMinimalAppendBoundary } from "../insertion-boundary";
+
+// ---------------------------------------------------------------------------
+// ProseMirror Plugin V2 — tracks segment positions through transactions.
+// ---------------------------------------------------------------------------
+
+interface SegmentPos {
+  from: number;
+  to: number;
+}
+
+interface EphiaV2PluginState {
+  segments: Record<string, SegmentPos>;
+}
+
+const ephiaV2Key = new PluginKey<EphiaV2PluginState>("ephiaV2");
+
+interface SegmentMeta {
+  segments?: Record<string, SegmentPos | null>;
+}
+
+function createEphiaV2Plugin(): Plugin {
+  return new Plugin({
+    key: ephiaV2Key,
+    state: {
+      init(): EphiaV2PluginState {
+        return { segments: {} };
+      },
+      apply(tr, value): EphiaV2PluginState {
+        const docSize = tr.doc.content.size;
+        const mapped: EphiaV2PluginState["segments"] = {};
+        for (const [id, pos] of Object.entries(value.segments)) {
+          const from = Math.min(Math.max(tr.mapping.map(pos.from), 0), docSize);
+          const to = Math.min(Math.max(tr.mapping.map(pos.to), 0), docSize);
+          if (from <= to && to <= docSize) mapped[id] = { from, to };
+        }
+        const meta = tr.getMeta(ephiaV2Key) as SegmentMeta | undefined;
+        if (meta?.segments) {
+          for (const [id, pos] of Object.entries(meta.segments)) {
+            if (pos === null) delete mapped[id];
+            else mapped[id] = pos;
+          }
+        }
+        return { segments: mapped };
+      },
+    },
+  });
+}
+
+function getV2State(editor: Editor): EphiaV2PluginState {
+  return ephiaV2Key.getState(editor.state) ?? { segments: {} };
+}
+
+function applySegmentMeta(tr: Transaction, updates: Record<string, SegmentPos | null>): void {
+  const current = (tr.getMeta(ephiaV2Key) as SegmentMeta | undefined) ?? {};
+  current.segments = { ...(current.segments ?? {}), ...updates };
+  tr.setMeta(ephiaV2Key, current);
+}
+
+// ---------------------------------------------------------------------------
+// Marks
+// ---------------------------------------------------------------------------
+
+export const EphiaV2PreviewMark = Mark.create({
+  name: "ephiaV2Preview",
+  parseHTML: () => [{ tag: "span[data-ephia-preview]" }],
+  renderHTML: () => ["span", { "data-ephia-preview": "true", class: "ephia-text--preview" }, 0],
+});
+
+export const EphiaV2CommittedMark = Mark.create({
+  name: "ephiaV2Committed",
+  parseHTML: () => [{ tag: "span[data-ephia-v2-committed]" }],
+  renderHTML: () => ["span", { "data-ephia-v2-committed": "true", class: "ephia-text--v2-committed" }, 0],
+});
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function getDocText(editor: Editor): string {
+  return editor.state.doc.textBetween(0, editor.state.doc.content.size, "\n\n", "\n");
+}
+
+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;
+}
+
+/**
+ * Replace text in range [from, to] with newText using a smart diff to avoid
+ * unnecessary delete+insert when only part of the text changed.
+ */
+function insertOpsIntoTr(
+  editor: Editor,
+  tr: Transaction,
+  startCursor: number,
+  text: string,
+  mark?: ProseMirrorMark,
+): number {
+  const ops = textToDocumentOperations(text);
+  let cursor = startCursor;
+  for (const op of ops) {
+    if (op.type === "insert_text") {
+      if (op.text) {
+        const node = mark
+          ? editor.schema.text(op.text, [mark])
+          : editor.schema.text(op.text);
+        tr.insert(cursor, node);
+        cursor += op.text.length;
+      }
+    } else if (op.type === "line_break") {
+      const hardBreak = editor.schema.nodes.hardBreak;
+      if (hardBreak) {
+        tr.insert(cursor, hardBreak.create());
+        cursor += 1;
+      }
+    } else if (op.type === "paragraph_break") {
+      const hardBreak = editor.schema.nodes.hardBreak;
+      if (hardBreak) {
+        // Two hard breaks for paragraph separation in flat TipTap documents.
+        tr.insert(cursor, hardBreak.create());
+        cursor += 1;
+        tr.insert(cursor, hardBreak.create());
+        cursor += 1;
+      }
+    }
+  }
+  return cursor;
+}
+
+function smartReplaceRange(
+  editor: Editor,
+  tr: Transaction,
+  from: number,
+  to: number,
+  newText: string
+): SegmentPos {
+  const oldText = editor.state.doc.textBetween(from, to, "\n", "\n");
+  const prefixLen = getCommonPrefix(oldText, newText);
+  const suffixLen = getCommonSuffix(oldText, newText, prefixLen);
+
+  const deleteFrom = from + prefixLen;
+  const deleteTo = to - suffixLen;
+  const insertText = newText.slice(prefixLen, newText.length - suffixLen);
+
+  if (deleteFrom < deleteTo || insertText.length > 0) {
+    if (deleteFrom < deleteTo) tr.delete(deleteFrom, deleteTo);
+    insertOpsIntoTr(editor, tr, deleteFrom, insertText);
+  }
+
+  return { from, to: from + newText.length };
+}
+
+function insertTextAt(editor: Editor, tr: Transaction, pos: number, text: string, mark?: ProseMirrorMark): SegmentPos {
+  const end = insertOpsIntoTr(editor, tr, pos, text, mark);
+  return { from: pos, to: end };
+}
+
+function stripPreviewMark(
+  editor: Editor,
+  tr: Transaction,
+  from: number,
+  to: number,
+): void {
+  const previewMarkType = editor.schema.marks.ephiaV2Preview;
+  if (previewMarkType) tr.removeMark(from, to, previewMarkType);
+}
+
+function applyPreviewMark(
+  editor: Editor,
+  tr: Transaction,
+  from: number,
+  to: number,
+): void {
+  const previewMark = editor.schema.marks.ephiaV2Preview?.create();
+  if (previewMark && from < to) tr.addMark(from, to, previewMark);
+}
+
+// ---------------------------------------------------------------------------
+// TiptapBinding V2
+// ---------------------------------------------------------------------------
+
+export type TiptapBindingOptions = {
+  warn?: (msg: string, details?: Record<string, unknown>) => void;
+};
+
+/**
+ * Binding V2 pour TipTap.
+ *
+ * Règles :
+ *  - même segmentId + upsertSegment = update in place (never append)
+ *  - segmentId connu mais range perdu = warning + no append
+ *  - removeSegments idempotent
+ *  - cleanup visuel ne supprime jamais l'identité segment
+ *  - le préfixe de boundary SDK est stable sur preview -> provisional -> canonical
+ */
+export class TiptapBinding implements EphiaBinding {
+  readonly kind = "tiptap";
+  readonly identity: Editor;
+
+  private readonly editor: Editor;
+  private readonly warn: NonNullable<TiptapBindingOptions["warn"]>;
+  private readonly knownSegmentIds = new Set<string>();
+  private readonly insertionPrefixes = new Map<string, string>();
+  private readonly visualTimeouts = new Map<string, ReturnType<typeof setTimeout>>();
+  private previewSegmentId: string | null = null;
+
+  constructor(editor: Editor, options?: TiptapBindingOptions) {
+    this.editor = editor;
+    this.identity = editor;
+    this.warn = options?.warn ?? ((msg, d) => console.warn(msg, d));
+  }
+
+  attach(): void {
+    const plugin = createEphiaV2Plugin();
+    this.editor.registerPlugin(plugin);
+  }
+
+  detach(): void {
+    this.editor.unregisterPlugin(ephiaV2Key);
+    for (const t of this.visualTimeouts.values()) clearTimeout(t);
+    this.visualTimeouts.clear();
+    this.knownSegmentIds.clear();
+    this.insertionPrefixes.clear();
+    this.previewSegmentId = null;
+  }
+
+  getText(): string {
+    return getDocText(this.editor);
+  }
+
+  getEditorContext(targetId = ""): EditorContext {
+    const { state } = this.editor;
+    const docSize = state.doc.content.size;
+    const text = getDocText(this.editor);
+    const { from, to } = state.selection;
+    const hasSelection = from !== to;
+
+    return {
+      targetId,
+      documentEmpty: text.trim().length === 0,
+      insertionMode: hasSelection
+        ? "replace_selection"
+        : from >= docSize - 1
+          ? "append"
+          : "middle_of_sentence",
+      leftContext: text.slice(Math.max(0, from - 400), from),
+      rightContext: text.slice(to, to + 200),
+      selectedText: hasSelection ? text.slice(from, to) : null,
+      cursorOffset: from,
+    };
+  }
+
+  previewSegment(input: PreviewSegmentInput): void {
+    // Remove previous preview if different segment.
+    if (this.previewSegmentId && this.previewSegmentId !== input.id) {
+      this._clearPreview(this.previewSegmentId);
+    }
+    this.previewSegmentId = input.id;
+    const state = getV2State(this.editor);
+    const existing = state.segments[input.id];
+    const insertPos = existing?.to ?? this.editor.state.selection.from;
+
+    if (existing) {
+      // Update existing preview range while preserving the first-insert boundary prefix.
+      const tr = this.editor.state.tr;
+      const safeText = this._textWithStableBoundary(input.id, input.text, existing.from);
+      const { from, to } = smartReplaceRange(this.editor, tr, existing.from, existing.to, safeText);
+      applyPreviewMark(this.editor, tr, from, to);
+      applySegmentMeta(tr, { [input.id]: { from, to } });
+      this.editor.view.dispatch(tr);
+    } else {
+      // Insert preview at cursor via textToDocumentOperations for consistent \n handling.
+      // Apply boundary safety for the first appearance of this segment.
+      const tr = this.editor.state.tr;
+      const pos = insertPos;
+      const previewMark = this.editor.schema.marks.ephiaV2Preview?.create();
+      const safeText = this._textWithStableBoundary(input.id, input.text, pos);
+      const { from, to } = insertTextAt(this.editor, tr, pos, safeText, previewMark);
+      applySegmentMeta(tr, { [input.id]: { from, to } });
+      this.editor.view.dispatch(tr);
+    }
+  }
+
+  upsertSegment(input: UpsertSegmentInput): void {
+    this._clearVisualTimeout(input.id);
+
+    if (this.previewSegmentId === input.id) {
+      this.previewSegmentId = null;
+    }
+
+    const state = getV2State(this.editor);
+    const existing = state.segments[input.id];
+
+    if (existing) {
+      // Update existing range while preserving the first-insert boundary prefix.
+      const tr = this.editor.state.tr;
+      const safeText = this._textWithStableBoundary(input.id, input.text, existing.from);
+      const { from, to } = smartReplaceRange(this.editor, tr, existing.from, existing.to, safeText);
+      stripPreviewMark(this.editor, tr, from, to);
+      applySegmentMeta(tr, { [input.id]: { from, to } });
+      this.editor.view.dispatch(tr);
+      this.knownSegmentIds.add(input.id);
+      this._scheduleVisualCleanup(input.id);
+      return;
+    }
+
+    if (this.knownSegmentIds.has(input.id)) {
+      this.warn("[ephia:tiptap] segment range lost; upsert ignored", {
+        segmentId: input.id,
+        stage: input.stage,
+      });
+      return;
+    }
+
+    // New segment — apply minimal boundary safety before inserting at cursor.
+    // Si une sélection est active, on la remplace par le texte dicté.
+    const { from: selFrom, to: selTo } = this.editor.state.selection;
+    const hasSelection = selFrom !== selTo;
+    const insertPos = selFrom;
+    const safeText = this._textWithStableBoundary(input.id, input.text, insertPos);
+    const tr = this.editor.state.tr;
+    if (hasSelection) {
+      tr.delete(selFrom, selTo);
+    }
+    const { from, to } = insertTextAt(this.editor, tr, insertPos, safeText);
+    applySegmentMeta(tr, { [input.id]: { from, to } });
+    this.editor.view.dispatch(tr);
+    this.knownSegmentIds.add(input.id);
+    this._scheduleVisualCleanup(input.id);
+  }
+
+  removeSegment(id: string): void {
+    const state = getV2State(this.editor);
+    const existing = state.segments[id];
+    if (!existing) {
+      this.knownSegmentIds.add(id);
+      this.insertionPrefixes.delete(id);
+      return;
+    }
+    if (this.previewSegmentId === id) this.previewSegmentId = null;
+    this._clearVisualTimeout(id);
+    const tr = this.editor.state.tr;
+    tr.delete(existing.from, existing.to);
+    applySegmentMeta(tr, { [id]: null });
+    this.editor.view.dispatch(tr);
+    this.knownSegmentIds.add(id);
+    this.insertionPrefixes.delete(id);
+  }
+
+  removeSegments(ids: string[]): void {
+    if (ids.length === 0) return;
+    const state = getV2State(this.editor);
+    const tr = this.editor.state.tr;
+    const updates: Record<string, SegmentPos | null> = {};
+
+    // Process removals in reverse document order to keep positions valid.
+    const toRemove = ids
+      .map((id) => ({ id, pos: state.segments[id] }))
+      .filter((x): x is { id: string; pos: SegmentPos } => x.pos !== undefined)
+      .sort((a, b) => b.pos.from - a.pos.from);
+
+    for (const { id, pos } of toRemove) {
+      tr.delete(pos.from, pos.to);
+      updates[id] = null;
+      this.knownSegmentIds.add(id);
+      this.insertionPrefixes.delete(id);
+      if (this.previewSegmentId === id) this.previewSegmentId = null;
+      this._clearVisualTimeout(id);
+    }
+
+    for (const id of ids) {
+      this.knownSegmentIds.add(id);
+      this.insertionPrefixes.delete(id);
+    }
+
+    if (toRemove.length > 0) {
+      applySegmentMeta(tr, updates);
+      this.editor.view.dispatch(tr);
+    }
+  }
+
+  // ------------------------------------------------------------------
+  // Internals
+  // ------------------------------------------------------------------
+
+  private _clearPreview(id: string): void {
+    const state = getV2State(this.editor);
+    const pos = state.segments[id];
+    if (!pos) return;
+    const tr = this.editor.state.tr;
+    tr.delete(pos.from, pos.to);
+    applySegmentMeta(tr, { [id]: null });
+    this.editor.view.dispatch(tr);
+  }
+
+  private _textWithStableBoundary(id: string, text: string, insertPos: number): string {
+    if (!text) return text;
+
+    // Backend-provided leading whitespace/newlines are authoritative.
+    // Do not prepend the SDK fallback prefix on top of them.
+    const firstChar = text.at(0);
+    if (!firstChar || /\s/.test(firstChar) || /^[,.;:!?)\]}>]/.test(firstChar)) {
+      this.insertionPrefixes.set(id, "");
+      return text;
+    }
+
+    let prefix = this.insertionPrefixes.get(id);
+    if (prefix === undefined) {
+      const leftText = getDocText(this.editor).slice(0, insertPos);
+      const safeText = ensureMinimalAppendBoundary(leftText, text);
+      prefix = safeText.endsWith(text) ? safeText.slice(0, safeText.length - text.length) : "";
+      this.insertionPrefixes.set(id, prefix);
+    }
+
+    return `${prefix}${text}`;
+  }
+
+  private _scheduleVisualCleanup(id: string): void {
+    this._clearVisualTimeout(id);
+    const timer = setTimeout(() => {
+      this.visualTimeouts.delete(id);
+      this._removeVisualMarkForSegment(id);
+    }, 1200);
+    this.visualTimeouts.set(id, timer);
+  }
+
+  private _clearVisualTimeout(id: string): void {
+    const t = this.visualTimeouts.get(id);
+    if (t) { clearTimeout(t); this.visualTimeouts.delete(id); }
+  }
+
+  private _removeVisualMarkForSegment(id: string): void {
+    const pos = getV2State(this.editor).segments[id];
+    if (!pos) return;
+    const { state } = this.editor;
+    const previewMarkType = state.schema.marks.ephiaV2Preview;
+    const committedMarkType = state.schema.marks.ephiaV2Committed;
+    if (!previewMarkType && !committedMarkType) return;
+    const tr = state.tr;
+    if (previewMarkType) tr.removeMark(pos.from, pos.to, previewMarkType);
+    if (committedMarkType) tr.removeMark(pos.from, pos.to, committedMarkType);
+    this.editor.view.dispatch(tr);
+  }
+}

package/src/core/bindings/types.ts

@@ -0,0 +1,41 @@
+export type SegmentStatus =
+  | "streaming"
+  | "committed"
+  | "error";
+
+export interface TextSegment {
+  id: string;
+  text: string;
+  status: SegmentStatus;
+}
+
+import type { DocumentOperation } from "ephia-protocol";
+import type { SessionAnchor } from "./TargetBinding";
+
+export interface BindingAdapter {
+  // Écriture des segments
+  insertSegment(seg: TextSegment): void;
+  updateSegment(id: string, text: string, status: SegmentStatus): void;
+  commitSegment(id: string): void;
+  removeSegment(id: string): void;
+
+  // Lecture
+  /**
+   * Retourne le texte du segment tel que l'adapter le connaît en interne
+   * (dernière valeur passée à insertSegment/updateSegment).
+   * Ne reflète pas les éditions DOM manuelles concurrentes.
+   */
+  getSegmentText?(id: string): string | null;
+  getTextContent(): string;
+  getCursorOffset(): number;
+
+  // Lifecycle
+  attach(): void;
+  beginSession?(anchor: SessionAnchor): void;
+  endSession?(): void;
+  detach(): void;
+
+  // Opération structurée (document.patch)
+  applyOperation?(operation: DocumentOperation): void;
+  clearAll?(): void;
+}