@ephia/dova-sdk 1.0.0

package/src/react/registry/registries/TargetRegistry.ts

@@ -0,0 +1,327 @@
+import type { EphiaStore } from "../../store/create-ephia-store";
+import { detectEditorType } from "../detect-editor-type";
+import {
+  createBindingForElement,
+  type TargetDescriptor,
+  type TargetInsertionMode,
+  type TargetOptions,
+} from "../binding-factory";
+import {
+  EPHIA_TARGET_FOCUSED,
+  EPHIA_TIPTAP_MOUNTED,
+  EPHIA_TIPTAP_DESTROYED,
+  EPHIA_CODEMIRROR_MOUNTED,
+  EPHIA_CODEMIRROR_DESTROYED,
+  EPHIA_MONACO_MOUNTED,
+  EPHIA_MONACO_DESTROYED,
+  dispatchTargetFocused,
+} from "../events";
+
+const DATA_TARGET = "data-ephia-target";
+const DATA_MODE = "data-ephia-mode";
+// const DATA_CONTEXT = "data-ephia-context";  // TODO: réactiver
+const DATA_EDITOR = "data-ephia-editor";
+const DATA_INSERTION = "data-ephia-insertion";
+
+export interface TargetRegistryOptions {
+  store: EphiaStore;
+}
+
+export class TargetRegistry {
+  private descriptors = new Map<string, TargetDescriptor>();
+  private observer: MutationObserver | null = null;
+  private store: EphiaStore;
+  private abortController: AbortController | null = null;
+
+  constructor(opts: TargetRegistryOptions) {
+    this.store = opts.store;
+  }
+
+  // ─── Lifecycle ──────────────────────────────────────────────────────────────
+
+  mount(scope?: Element): void {
+    this.scanDocument(scope);
+    this.startObserver(scope);
+    this.attachGlobalListeners();
+  }
+
+  unmount(): void {
+    this.observer?.disconnect();
+    this.observer = null;
+    this.abortController?.abort();
+    this.abortController = null;
+    for (const desc of this.descriptors.values()) {
+      desc.binding?.detach();
+      if (desc._focusinListener && desc.element) {
+        desc.element.removeEventListener("focusin", desc._focusinListener);
+      }
+    }
+    this.descriptors.clear();
+  }
+
+  // ─── API publique ────────────────────────────────────────────────────────────
+
+  register(id: string, el: HTMLElement, opts: TargetOptions): void {
+    el.setAttribute(DATA_TARGET, id);
+    if (opts.mode) el.setAttribute(DATA_MODE, opts.mode);
+    // if (opts.context) el.setAttribute(DATA_CONTEXT, opts.context);  // TODO: réactiver
+    if (opts.insertion) el.setAttribute(DATA_INSERTION, opts.insertion);
+    if (opts.editor) el.setAttribute(DATA_EDITOR, opts.editor);
+    this.attachElement(el);
+  }
+
+  unregister(id: string): void {
+    const desc = this.descriptors.get(id);
+    if (!desc) return;
+    desc.binding?.detach();
+    if (desc._focusinListener && desc.element) {
+      desc.element.removeEventListener("focusin", desc._focusinListener);
+    }
+    this.descriptors.delete(id);
+
+    if (this.store.getState().activeTargetId === id) {
+      // Ne pas changer le target actif en pleine session — le binding
+      // détaché a déjà le texte en cours et changer de target actif
+      // ferait pointer les events suivants vers null ou un autre élément.
+      const status = this.store.getState().status;
+      if (status === "idle" || status === "error") {
+        const first = this.getFirstWritable();
+        this.store.getState()._setActiveTarget(first?.id ?? null);
+      }
+    }
+  }
+
+  get(id: string): TargetDescriptor | undefined {
+    return this.descriptors.get(id);
+  }
+
+  getActiveBinding() {
+    const id = this.store.getState().activeTargetId;
+    if (!id) return null;
+    return this.descriptors.get(id)?.binding ?? null;
+  }
+
+  getFirstWritable(): TargetDescriptor | undefined {
+    for (const desc of this.descriptors.values()) {
+      if (desc.mode.includes("write")) return desc;
+    }
+    return undefined;
+  }
+
+  values(): TargetDescriptor[] {
+    return Array.from(this.descriptors.values());
+  }
+
+  setActive(id: string): void {
+    if (!this.descriptors.has(id)) return;
+    // Lock the active target during an active session to prevent focus changes
+    // from redirecting transcript insertion to a different element.
+    const status = this.store.getState().status;
+    if (status !== "idle" && status !== "error") return;
+    this.store.getState()._setActiveTarget(id);
+  }
+
+  readContent(id: string): string {
+    return this.descriptors.get(id)?.binding?.getText() ?? "";
+  }
+
+  get size(): number {
+    return this.descriptors.size;
+  }
+
+  // ─── Scan + Observer ─────────────────────────────────────────────────────────
+
+  private scanDocument(scope?: Element): void {
+    if (typeof document === "undefined") return;
+    const root = scope ?? document;
+    root.querySelectorAll<HTMLElement>(`[${DATA_TARGET}]`).forEach((el) => {
+      this.attachElement(el);
+    });
+  }
+
+  private startObserver(scope?: Element): void {
+    if (typeof MutationObserver === "undefined") return;
+
+    this.observer = new MutationObserver((mutations) => {
+      for (const mutation of mutations) {
+        if (mutation.type === "childList") {
+          mutation.addedNodes.forEach((node) => {
+            if (node.nodeType !== Node.ELEMENT_NODE) return;
+            const el = node as HTMLElement;
+            if (el.hasAttribute(DATA_TARGET)) this.attachElement(el);
+            el.querySelectorAll<HTMLElement>(`[${DATA_TARGET}]`).forEach((child) => {
+              this.attachElement(child);
+            });
+          });
+          mutation.removedNodes.forEach((node) => {
+            if (node.nodeType !== Node.ELEMENT_NODE) return;
+            const el = node as HTMLElement;
+            const id = el.getAttribute(DATA_TARGET);
+            if (id) this.unregister(id);
+            el.querySelectorAll<HTMLElement>(`[${DATA_TARGET}]`).forEach((child) => {
+              const childId = child.getAttribute(DATA_TARGET);
+              if (childId) this.unregister(childId);
+            });
+          });
+        }
+      }
+    });
+
+    const target = scope ?? document.body;
+    this.observer.observe(target, { childList: true, subtree: true });
+  }
+
+  // ─── Global DOM event listeners ──────────────────────────────────────────────
+
+  private attachGlobalListeners(): void {
+    this.abortController = new AbortController();
+    const { signal } = this.abortController;
+
+    document.addEventListener(
+      EPHIA_TARGET_FOCUSED,
+      (e) => {
+        this.setActive((e as CustomEvent<{ id: string }>).detail.id);
+      },
+      { signal }
+    );
+    document.addEventListener(
+      EPHIA_TIPTAP_MOUNTED,
+      (e) => { this.onEditorReady((e as CustomEvent<{ el: HTMLElement }>).detail.el, "tiptap"); },
+      { signal }
+    );
+    document.addEventListener(
+      EPHIA_TIPTAP_DESTROYED,
+      (e) => { this.onEditorGone((e as CustomEvent<{ el: HTMLElement }>).detail.el); },
+      { signal }
+    );
+    document.addEventListener(
+      EPHIA_CODEMIRROR_MOUNTED,
+      (e) => { this.onEditorReady((e as CustomEvent<{ el: HTMLElement }>).detail.el, "codemirror"); },
+      { signal }
+    );
+    document.addEventListener(
+      EPHIA_CODEMIRROR_DESTROYED,
+      (e) => { this.onEditorGone((e as CustomEvent<{ el: HTMLElement }>).detail.el); },
+      { signal }
+    );
+    document.addEventListener(
+      EPHIA_MONACO_MOUNTED,
+      (e) => { this.onEditorReady((e as CustomEvent<{ el: HTMLElement }>).detail.el, "monaco"); },
+      { signal }
+    );
+    document.addEventListener(
+      EPHIA_MONACO_DESTROYED,
+      (e) => { this.onEditorGone((e as CustomEvent<{ el: HTMLElement }>).detail.el); },
+      { signal }
+    );
+  }
+
+  // ─── Élément attachment ───────────────────────────────────────────────────────
+
+  private attachElement(el: HTMLElement): void {
+    const id = el.getAttribute(DATA_TARGET);
+    if (!id) return;
+
+    const existing = this.descriptors.get(id);
+    if (existing) {
+      // Si le nœud DOM a été remplacé (même id, nouvel élément), mettre à jour.
+      if (existing.element !== el) {
+        existing.binding?.detach();
+        if (existing._focusinListener) {
+          existing.element.removeEventListener("focusin", existing._focusinListener);
+        }
+        // Recréer le binding sur le nouveau nœud
+        const mode = (el.getAttribute(DATA_MODE) ?? "write") as TargetDescriptor["mode"];
+        // const context = el.getAttribute(DATA_CONTEXT) ?? undefined;  // TODO: réactiver
+        const insertion = (el.getAttribute(DATA_INSERTION) ?? "preview-inline") as TargetInsertionMode;
+        const editorType = detectEditorType(el);
+        const binding = createBindingForElement(el, editorType, { mode, insertion });
+        const focusinListener = this.createFocusinListener(id, mode);
+        if (focusinListener) el.addEventListener("focusin", focusinListener);
+        const updated: TargetDescriptor = {
+          ...existing,
+          element: el,
+          editorType,
+          mode,
+          // context,
+          insertion,
+          binding,
+          _focusinListener: focusinListener ?? undefined,
+        };
+        this.descriptors.set(id, updated);
+      }
+      return;
+    }
+
+    const mode = (el.getAttribute(DATA_MODE) ?? "write") as TargetDescriptor["mode"];
+    // const context = el.getAttribute(DATA_CONTEXT) ?? undefined;  // TODO: réactiver
+    const insertion = (el.getAttribute(DATA_INSERTION) ?? "preview-inline") as TargetInsertionMode;
+    const editorType = detectEditorType(el);
+
+    const binding = createBindingForElement(el, editorType, { mode, insertion });
+
+    const focusinListener = this.createFocusinListener(id, mode);
+    if (focusinListener) el.addEventListener("focusin", focusinListener);
+
+    const desc: TargetDescriptor = {
+      id,
+      element: el,
+      editorType,
+      mode,
+      // context,
+      insertion,
+      binding,
+      _focusinListener: focusinListener ?? undefined,
+    };
+    this.descriptors.set(id, desc);
+
+    // Auto-activer le premier target writable
+    if (this.store.getState().activeTargetId === null && mode.includes("write")) {
+      this.store.getState()._setActiveTarget(id);
+    }
+  }
+
+  private createFocusinListener(
+    id: string,
+    mode: TargetDescriptor["mode"]
+  ): (() => void) | null {
+    if (!mode.includes("write")) return null;
+    return () => dispatchTargetFocused(id);
+  }
+
+  // ─── Async editor resolution (TipTap, CodeMirror, Monaco) ───────────────────
+
+  private onEditorReady(el: HTMLElement, editorType: "tiptap" | "codemirror" | "monaco"): void {
+    for (const [id, desc] of this.descriptors) {
+      if (
+        desc.element === el ||
+        desc.element.contains(el) ||
+        el.contains(desc.element)
+      ) {
+        // Détacher l'ancien binding (ex: contenteditable fallback) avant de
+        // remplacer par le binding natif de l'éditeur.
+        if (desc.binding !== null) {
+          desc.binding.detach();
+        }
+        const binding = createBindingForElement(desc.element, editorType);
+        if (binding) {
+          desc.binding = binding;
+          desc.editorType = editorType;
+          this.descriptors.set(id, desc);
+        }
+        return;
+      }
+    }
+  }
+
+  private onEditorGone(el: HTMLElement): void {
+    for (const [id, desc] of this.descriptors) {
+      if (desc.element === el || desc.element.contains(el)) {
+        desc.binding?.detach();
+        desc.binding = null;
+        this.descriptors.set(id, desc);
+        return;
+      }
+    }
+  }
+}

package/src/react/registry/registries/TiptapInstanceRegistry.ts

@@ -0,0 +1,43 @@
+import type { Editor } from "@tiptap/core";
+import { dispatchTiptapMounted, dispatchTiptapDestroyed } from "../events";
+
+/**
+ * Registre global des instances TipTap, indexé par l'élément conteneur.
+ *
+ * Utilise une WeakMap pour éviter les fuites mémoire — si l'élément est
+ * retiré du DOM et n'a plus de référence, l'entrée est collectée automatiquement.
+ *
+ * Usage :
+ *   // Dans le composant TipTap
+ *   const ref = useRef<HTMLDivElement>(null)
+ *   useEffect(() => {
+ *     if (!editor || !ref.current) return
+ *     TiptapInstanceRegistry.set(ref.current, editor)
+ *     return () => TiptapInstanceRegistry.delete(ref.current!)
+ *   }, [editor])
+ *
+ *   // Ou via le hook useEphiaTiptap (recommandé)
+ */
+const registry = new WeakMap<HTMLElement, Editor>();
+
+export const TiptapInstanceRegistry = {
+  set(el: HTMLElement, editor: Editor): void {
+    registry.set(el, editor);
+    dispatchTiptapMounted(el);
+  },
+
+  get(el: HTMLElement): Editor | undefined {
+    if (registry.has(el)) return registry.get(el);
+    // Chercher dans les ancêtres directs (cas wrapper)
+    const proseMirror = el.querySelector<HTMLElement>(".ProseMirror");
+    if (proseMirror?.parentElement) {
+      return registry.get(proseMirror.parentElement);
+    }
+    return undefined;
+  },
+
+  delete(el: HTMLElement): void {
+    registry.delete(el);
+    dispatchTiptapDestroyed(el);
+  },
+};

package/src/react/registry/registries/index.ts

@@ -0,0 +1,5 @@
+export { CodeMirrorInstanceRegistry } from "./CodeMirrorInstanceRegistry";
+export { MonacoInstanceRegistry } from "./MonacoInstanceRegistry";
+export { TargetRegistry } from "./TargetRegistry";
+export type { TargetRegistryOptions } from "./TargetRegistry";
+export { TiptapInstanceRegistry } from "./TiptapInstanceRegistry";

package/src/react/store/create-ephia-store.ts

@@ -0,0 +1,36 @@
+import { createStore } from "zustand/vanilla";
+import type { StoreApi } from "zustand/vanilla";
+import { initialConnectionState } from "../../core/connection/connection-state";
+import { initialAudioState } from "../../shared/state/audio-state";
+import type { EphiaStoreState } from "./types";
+
+export type EphiaStore = StoreApi<EphiaStoreState>;
+
+const baseState = {
+  status: "idle" as const,
+  sessionId: null,
+  error: null,
+  activeTargetId: null,
+  partial: null,
+  connection: initialConnectionState,
+  audio: initialAudioState,
+};
+
+export function createEphiaStore(): EphiaStore {
+  return createStore<EphiaStoreState>((set) => ({
+    ...baseState,
+
+    _setStatus: (status) => set({ status }),
+    _setSessionId: (sessionId) => set({ sessionId }),
+    _setError: (error) => set({ error }),
+    _setActiveTarget: (activeTargetId) => set({ activeTargetId }),
+    _setPartial: (partial) => set({ partial }),
+    _setConnection: (connection) => set({ connection }),
+    _setAudio: (audio) => set({ audio }),
+    _reset: () => set({
+      ...baseState,
+      connection: { ...initialConnectionState },
+      audio: { ...initialAudioState },
+    }),
+  }));
+}

package/src/react/store/types.ts

@@ -0,0 +1,41 @@
+'use client'
+
+import type { EphiaConnectionState } from "../../core/connection/connection-state";
+import type { EphiaAudioState } from "../../shared/state/audio-state";
+
+export type EphiaStatus =
+  | "idle"
+  | "recording"
+  | "processing"
+  | "error";
+
+export interface EphiaPartial {
+  targetId: string | null;
+  text: string;
+  segmentId: string;
+}
+
+export interface EphiaError {
+  code: string;
+  message: string;
+}
+
+export interface EphiaStoreState {
+  status: EphiaStatus;
+  sessionId: string | null;
+  error: EphiaError | null;
+  activeTargetId: string | null;
+  partial: EphiaPartial | null;
+  connection: EphiaConnectionState;
+  audio: EphiaAudioState;
+
+  // Internal mutators — prefixed with _ to signal "don't call from user code"
+  _setStatus: (status: EphiaStatus) => void;
+  _setSessionId: (sessionId: string | null) => void;
+  _setError: (error: EphiaError | null) => void;
+  _setActiveTarget: (id: string | null) => void;
+  _setPartial: (partial: EphiaPartial | null) => void;
+  _setConnection: (connection: EphiaConnectionState) => void;
+  _setAudio: (audio: EphiaAudioState) => void;
+  _reset: () => void;
+}

package/src/react/utils/flash-range.ts

@@ -0,0 +1,24 @@
+import type { TargetBinding } from "../../core/bindings/TargetBinding";
+
+const FLASH_DURATION_MS = 700;
+
+export function flashRange(
+  binding: TargetBinding,
+  start: number,
+  end: number,
+  variant: "revised" | "committed" = "committed"
+): void {
+  if (typeof document === "undefined") return;
+  const rect = binding.getRangeRect?.(start, end);
+  if (!rect || rect.width < 1 || rect.height < 1) return;
+
+  const flash = document.createElement("div");
+  if (variant === "committed") {
+    flash.className = "ephia-committed-flash";
+  } else if (variant === "revised") {
+    flash.className = "ephia-reformat-flash ephia-reformat-flash--revised";
+  }
+  flash.style.cssText = `left:${rect.left}px;top:${rect.top}px;width:${rect.width}px;height:${rect.height}px;`;
+  document.body.appendChild(flash);
+  setTimeout(() => flash.remove(), FLASH_DURATION_MS + 100);
+}

package/src/react/utils/index.ts

@@ -0,0 +1 @@
+export { flashRange } from "./flash-range";

package/src/rich-editor/adapters/tiptap.test.ts

@@ -0,0 +1,86 @@
+// @vitest-environment jsdom
+
+import { describe, expect, it } from "vitest";
+import { Editor, Node } from "@tiptap/core";
+import { createTiptapEphiaAdapter } from "./tiptap";
+import { EphiaV2PreviewMark, EphiaV2CommittedMark } from "../../core/bindings/tiptap/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(): Editor {
+  return new Editor({
+    element: document.createElement("div"),
+    extensions: [DocumentNode, ParagraphNode, TextNode, EphiaV2PreviewMark, EphiaV2CommittedMark],
+    content: "<p></p>",
+  });
+}
+
+describe("createTiptapEphiaAdapter", () => {
+  it("returns null for null editor", () => {
+    expect(createTiptapEphiaAdapter(null)).toBeNull();
+  });
+
+  it("returns the same adapter object for the same editor instance", () => {
+    const editor = createEditor();
+    try {
+      const adapter1 = createTiptapEphiaAdapter(editor);
+      const adapter2 = createTiptapEphiaAdapter(editor);
+      expect(adapter1).toBe(adapter2);
+    } finally {
+      editor.destroy();
+    }
+  });
+
+  it("returns different adapters for different editor instances", () => {
+    const editorA = createEditor();
+    const editorB = createEditor();
+    try {
+      expect(createTiptapEphiaAdapter(editorA)).not.toBe(
+        createTiptapEphiaAdapter(editorB),
+      );
+    } finally {
+      editorA.destroy();
+      editorB.destroy();
+    }
+  });
+
+  it("adapter has kind tiptap", () => {
+    const editor = createEditor();
+    try {
+      expect(createTiptapEphiaAdapter(editor)?.kind).toBe("tiptap");
+    } finally {
+      editor.destroy();
+    }
+  });
+
+  it("adapter identity is the editor instance", () => {
+    const editor = createEditor();
+    try {
+      expect(createTiptapEphiaAdapter(editor)?.identity).toBe(editor);
+    } finally {
+      editor.destroy();
+    }
+  });
+
+  it("adapter creates a binding that can attach and detach", () => {
+    const editor = createEditor();
+    try {
+      const adapter = createTiptapEphiaAdapter(editor)!;
+      const binding = adapter.createBinding({ targetId: "test" });
+      expect(() => {
+        binding.attach();
+        binding.detach();
+      }).not.toThrow();
+    } finally {
+      editor.destroy();
+    }
+  });
+});

package/src/rich-editor/adapters/tiptap.ts

@@ -0,0 +1,23 @@
+import type { Editor } from "@tiptap/core";
+import { TiptapBinding } from "../../core/bindings/tiptap/TiptapBinding";
+import type { EphiaRichEditorAdapter } from "../types";
+
+const tiptapAdapterCache = new WeakMap<Editor, EphiaRichEditorAdapter>();
+
+export function createTiptapEphiaAdapter(
+  editor: Editor | null,
+): EphiaRichEditorAdapter | null {
+  if (!editor) return null;
+
+  const cached = tiptapAdapterCache.get(editor);
+  if (cached) return cached;
+
+  const adapter: EphiaRichEditorAdapter = {
+    kind: "tiptap",
+    identity: editor,
+    createBinding: () => new TiptapBinding(editor),
+  };
+
+  tiptapAdapterCache.set(editor, adapter);
+  return adapter;
+}

package/src/rich-editor/index.ts

@@ -0,0 +1,3 @@
+export { useEphiaRichEditor } from "./use-ephia-rich-editor";
+export { createTiptapEphiaAdapter } from "./adapters/tiptap";
+export type { EphiaRichEditorAdapter, UseEphiaRichEditorOptions } from "./types";

package/src/rich-editor/types.ts

@@ -0,0 +1,24 @@
+import type { EphiaBinding } from "../core/bindings/EphiaBinding";
+
+export interface EphiaRichEditorAdapter {
+  kind: string;
+  /**
+   * Stable identity for this editor instance across React renders.
+   * Official adapters always provide this. Custom adapters should too.
+   * When present, useEphiaRichEditor depends on this instead of the adapter object,
+   * making the hook safe against inline adapter creation (e.g. without useMemo).
+   */
+  identity?: object;
+  createBinding(options: {
+    targetId: string;
+    label?: string;
+  }): EphiaBinding;
+  getElement?(): HTMLElement | null;
+}
+
+export interface UseEphiaRichEditorOptions {
+  id: string;
+  mode?: string;
+  label?: string;
+  enabled?: boolean;
+}