@ephia/dova-sdk 1.0.0

package/src/core/runtime/DictationRuntime.ts

@@ -0,0 +1,434 @@
+import type { EphiaAudioEvent } from "ephia-protocol";
+import type { TargetBinding } from "../bindings/TargetBinding";
+import { pickEffectiveText } from "../../shared/effective-text";
+import {
+  normalizeCommittedText,
+  normalizePreviewText,
+  type VoiceFormattingConfig,
+} from "../text-processing/voice-formatting.normalizer";
+
+export type DictationTargetInsertionMode =
+  | "preview-inline"
+  | "final-only"
+  | "preview-floating"
+  | "none";
+
+export type DictationRuntimeStatus =
+  | "idle"
+  | "recording"
+  | "processing"
+  | "error";
+
+export interface DictationTarget {
+  id: string;
+  insertion: DictationTargetInsertionMode;
+  element: HTMLElement;
+  binding: TargetBinding | null;
+}
+
+export interface DictationTargetRegistry {
+  get(id: string): DictationTarget | undefined;
+  getActiveTargetId(): string | null;
+  getActiveTarget(): DictationTarget | undefined;
+}
+
+export interface DictationPartialState {
+  targetId: string | null;
+  text: string;
+  segmentId: string;
+}
+
+export interface DictationRuntimeOptions {
+  registry: DictationTargetRegistry;
+  getStatus(): DictationRuntimeStatus;
+  setPartial(partial: DictationPartialState | null): void;
+  setError?(error: { code: string; message: string } | null): void;
+  setStatus?(status: DictationRuntimeStatus): void;
+  resetSessionContext(options?: { waitForAck?: boolean }): Promise<void>;
+  flashRange?(
+    binding: TargetBinding,
+    start: number,
+    end: number,
+    variant?: "revised" | "committed"
+  ): void;
+  voiceFormatting?: VoiceFormattingConfig;
+  getVoiceFormatting?: () => VoiceFormattingConfig | undefined;
+}
+
+function isEphiaControlEventTarget(target: EventTarget | null): boolean {
+  if (!(target instanceof Element)) return false;
+  return Boolean(
+    target.closest(
+      '[data-ephia-control="true"], [data-ephia-status], .ephia-transcribe-root, .ephia-transcribe-floating-root'
+    )
+  );
+}
+
+function isModifierOnlyKey(event: Event): boolean {
+  if (!(event instanceof KeyboardEvent)) return false;
+  return ["Alt", "Control", "Meta", "Shift", "CapsLock"].includes(event.key);
+}
+
+function asArray(value: string | string[] | undefined): string[] {
+  if (!value) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
+// Délai minimal entre realtime_final et son commit définitif — laisse le temps
+// à la correction Small d'arriver avant que le realtime ne soit visible.
+// Réduit à 150 ms : Small reçoit l'audio seul, sa latence est plus prévisible.
+const REALTIME_COMMIT_HOLD_MS = 150;
+
+export class DictationRuntime {
+  private readonly registry: DictationTargetRegistry;
+  private readonly opts: DictationRuntimeOptions;
+  private readonly segmentTargetMap = new Map<string, string>();
+  private readonly pendingRealtimeCommits = new Map<string, ReturnType<typeof setTimeout>>();
+  private readonly absorbedSegmentIds = new Set<string>();
+  private activePartial: DictationPartialState | null = null;
+  private interruptResetInFlight = false;
+  private sessionClosed = false;
+
+  constructor(opts: DictationRuntimeOptions) {
+    this.opts = opts;
+    this.registry = opts.registry;
+  }
+
+  handleEvent(event: EphiaAudioEvent): void {
+    if (
+      this.sessionClosed &&
+      (event.type.startsWith("transcript.") || event.type.startsWith("segment."))
+    ) {
+      return;
+    }
+
+    switch (event.type) {
+      case "session.ready":
+        this.sessionClosed = false;
+        break;
+
+      case "transcript.preview":
+      case "transcript.preview.stable":
+        this.handlePreview(event);
+        break;
+
+      case "transcript.segment.ready":
+        this.handleSegmentReady(event);
+        break;
+
+      case "transcript.final":
+      case "transcript.segment.committed":
+        this.handleCommitted(event);
+        break;
+
+      case "segment.absorbed":
+        this.segmentTargetMap.delete(event.payload.segmentId);
+        break;
+
+      case "segment.dropped":
+        this.handleDropped(event.payload.segmentId);
+        break;
+
+      case "transcript.segment.error":
+        this.clearSegmentState(event.payload.segmentId, { clearPartial: true });
+        break;
+
+      case "session.closed":
+        this.sessionClosed = true;
+        this.setPartial(null);
+        this.clearMappedTargetStates({ clearBindings: true });
+        this.segmentTargetMap.clear();
+        this.absorbedSegmentIds.clear();
+        this.clearPendingRealtimeCommits();
+        break;
+
+      case "session.context.reset": {
+        if (this.activePartial) {
+          const t = this.getSegmentTarget(this.activePartial.segmentId);
+          t?.binding?.clearPartial(this.activePartial.segmentId);
+        }
+        this.setPartial(null);
+        this.clearMappedTargetStates({ clearBindings: false });
+        this.segmentTargetMap.clear();
+        this.absorbedSegmentIds.clear();
+        this.clearPendingRealtimeCommits();
+        break;
+      }
+
+      case "session.error":
+        this.sessionClosed = true;
+        this.setPartial(null);
+        this.clearMappedTargetStates({ clearBindings: true });
+        this.opts.setError?.(event.payload);
+        this.opts.setStatus?.("error");
+        this.segmentTargetMap.clear();
+        this.absorbedSegmentIds.clear();
+        this.clearPendingRealtimeCommits();
+        break;
+    }
+  }
+
+  private clearPendingRealtimeCommits(): void {
+    for (const timer of this.pendingRealtimeCommits.values()) clearTimeout(timer);
+    this.pendingRealtimeCommits.clear();
+  }
+
+  handleFallbackFinal(text: string, segmentId: string): boolean {
+    const targetId = this.segmentTargetMap.get(segmentId) ?? this.registry.getActiveTargetId();
+    if (!targetId) return false;
+
+    const target = this.registry.get(targetId);
+    if (target?.insertion !== "none" && target?.binding) {
+      target.binding.commitFinal(segmentId, this.formatCommittedText(text));
+    }
+    return true;
+  }
+
+  handleUserInteraction(event: Event): void {
+    const status = this.opts.getStatus();
+    const partial = this.activePartial;
+    if (!partial) return;
+    if (status === "idle" || status === "error") return;
+    if (isModifierOnlyKey(event) || isEphiaControlEventTarget(event.target)) return;
+
+    const activeTargetId = this.registry.getActiveTargetId();
+    if (!activeTargetId || (partial.targetId && partial.targetId !== activeTargetId)) return;
+
+    const target = this.registry.get(activeTargetId);
+    const eventTarget = event.target;
+    if (!target?.binding || !(eventTarget instanceof Node)) return;
+    if (!target.element.contains(eventTarget)) return;
+
+    this.setPartial(null);
+    target.binding.clearAll?.();
+    this.clearTargetState(target);
+
+    if (!this.interruptResetInFlight) {
+      this.interruptResetInFlight = true;
+      this.opts.resetSessionContext({ waitForAck: false }).finally(() => {
+        this.interruptResetInFlight = false;
+      });
+    }
+  }
+
+  clear(): void {
+    this.segmentTargetMap.clear();
+    this.absorbedSegmentIds.clear();
+    this.clearPendingRealtimeCommits();
+    this.interruptResetInFlight = false;
+    this.sessionClosed = false;
+    this.setPartial(null);
+  }
+
+  private getVoiceFormatting(): VoiceFormattingConfig | undefined {
+    return this.opts.getVoiceFormatting?.() ?? this.opts.voiceFormatting;
+  }
+
+  private formatPreviewText(text: string): string {
+    return normalizePreviewText(text, this.getVoiceFormatting());
+  }
+
+  private formatCommittedText(text: string): string {
+    return normalizeCommittedText(text, this.getVoiceFormatting());
+  }
+
+  private handlePreview(
+    event: Extract<EphiaAudioEvent, { type: "transcript.preview" | "transcript.preview.stable" }>
+  ): void {
+    const { segmentId, revision } = event.payload;
+    const text = this.formatPreviewText(event.payload.text);
+    const targetId = this.resolveSegmentTargetId(segmentId);
+
+    this.setPartial({ targetId, text, segmentId });
+
+    const target = targetId ? this.registry.get(targetId) : undefined;
+    const insertion = target?.insertion ?? "preview-inline";
+    if (insertion === "preview-inline" || insertion === "preview-floating") {
+      target?.binding?.insertPartial?.(segmentId, text, revision ?? 0);
+    }
+    target?.element?.setAttribute("data-ephia-target-processing", "true");
+  }
+
+  private handleSegmentReady(
+    event: Extract<EphiaAudioEvent, { type: "transcript.segment.ready" }>
+  ): void {
+    const { segmentId, text, delta } = event.payload;
+    const effectiveText = this.formatCommittedText(pickEffectiveText({ text, delta }));
+    const targetId = this.resolveSegmentTargetId(segmentId);
+    const target = targetId ? this.registry.get(targetId) : undefined;
+    const insertion = target?.insertion ?? "preview-inline";
+
+    if (target?.binding?.insertPartial && insertion !== "none") {
+      target.binding.insertPartial(segmentId, effectiveText, Number.MAX_SAFE_INTEGER);
+    }
+  }
+
+  private handleCommitted(
+    event: Extract<EphiaAudioEvent, { type: "transcript.final" | "transcript.segment.committed" }>
+  ): void {
+    const { segmentId } = event.payload as { segmentId: string };
+    const absorbed = asArray(
+      event.type === "transcript.segment.committed"
+        ? (event.payload as { mergedWith?: string | string[] }).mergedWith
+        : undefined
+    );
+
+    for (const absorbedId of absorbed) {
+      this.absorbedSegmentIds.add(absorbedId);
+      const pending = this.pendingRealtimeCommits.get(absorbedId);
+      if (pending) {
+        clearTimeout(pending);
+        this.pendingRealtimeCommits.delete(absorbedId);
+      }
+      if (this.activePartial?.segmentId === absorbedId) {
+        this.setPartial(null);
+      }
+    }
+
+    if (this.absorbedSegmentIds.has(segmentId)) {
+      const pending = this.pendingRealtimeCommits.get(segmentId);
+      if (pending) {
+        clearTimeout(pending);
+        this.pendingRealtimeCommits.delete(segmentId);
+      }
+      return;
+    }
+
+    // Un realtime_final (correctionPending=true) n'est pas encore sûr : Small
+    // peut le corriger ~500-800ms plus tard. On retarde son commit pour éviter
+    // qu'un mauvais début de segment ne s'affiche brièvement comme définitif.
+    const keepProcessing =
+      event.type === "transcript.segment.committed" &&
+      (event.payload as { correctionPending?: boolean }).correctionPending === true;
+
+    if (keepProcessing) {
+      const existing = this.pendingRealtimeCommits.get(segmentId);
+      if (existing) clearTimeout(existing);
+      const timer = setTimeout(() => {
+        this.pendingRealtimeCommits.delete(segmentId);
+        this.commitEventNow(event);
+      }, REALTIME_COMMIT_HOLD_MS);
+      this.pendingRealtimeCommits.set(segmentId, timer);
+      return;
+    }
+
+    const pending = this.pendingRealtimeCommits.get(segmentId);
+    if (pending) {
+      clearTimeout(pending);
+      this.pendingRealtimeCommits.delete(segmentId);
+    }
+    this.commitEventNow(event);
+  }
+
+  private commitEventNow(
+    event: Extract<EphiaAudioEvent, { type: "transcript.final" | "transcript.segment.committed" }>
+  ): void {
+    const { segmentId, text, delta, textForInsertion, targetId: payloadTargetId } = event.payload as {
+      segmentId: string;
+      text: string;
+      delta?: string;
+      textForInsertion?: string;
+      targetId?: string;
+    };
+    if (this.absorbedSegmentIds.has(segmentId)) {
+      return;
+    }
+    const absorbed = asArray(
+      event.type === "transcript.segment.committed"
+        ? (event.payload as { mergedWith?: string | string[] }).mergedWith
+        : undefined
+    );
+    const rawEffectiveText =
+      event.type === "transcript.segment.committed"
+        ? textForInsertion ?? pickEffectiveText({ text, delta })
+        : text;
+    const effectiveText = this.formatCommittedText(rawEffectiveText);
+    const targetId = this.resolveSegmentTargetId(segmentId, payloadTargetId);
+    const target = targetId ? this.registry.get(targetId) : undefined;
+    this.setPartial(null);
+    this.clearTargetState(target);
+
+    if (target?.insertion !== "none" && target?.binding) {
+      target.binding.commitFinal(
+        segmentId,
+        effectiveText,
+        absorbed.length ? { absorbedSegmentIds: absorbed } : undefined
+      );
+      for (const absorbedId of absorbed) this.segmentTargetMap.delete(absorbedId);
+      const range = target.binding.getSegmentRange?.(segmentId);
+      if (range) this.opts.flashRange?.(target.binding, range.start, range.end, "committed");
+    }
+  }
+
+  private handleDropped(segmentId: string): void {
+    const pending = this.pendingRealtimeCommits.get(segmentId);
+    if (pending) {
+      clearTimeout(pending);
+      this.pendingRealtimeCommits.delete(segmentId);
+    }
+    this.setPartial(null);
+    const target = this.getSegmentTarget(segmentId);
+    target?.binding?.clearPartial(segmentId);
+    this.clearTargetState(target);
+    this.segmentTargetMap.delete(segmentId);
+  }
+
+  private clearSegmentState(
+    segmentId: string,
+    opts: { clearPartial: boolean }
+  ): void {
+    if (opts.clearPartial) this.setPartial(null);
+    const target = this.getSegmentTarget(segmentId);
+    if (opts.clearPartial) target?.binding?.clearPartial(segmentId);
+    this.clearTargetState(target);
+    this.segmentTargetMap.delete(segmentId);
+  }
+
+  private clearTargetState(target: DictationTarget | undefined): void {
+    target?.element?.removeAttribute("data-ephia-target-processing");
+  }
+
+  private clearMappedTargetStates(opts: { clearBindings: boolean }): void {
+    const targetIds = new Set(this.segmentTargetMap.values());
+    const activeTargetId = this.registry.getActiveTargetId();
+    if (activeTargetId) targetIds.add(activeTargetId);
+
+    for (const targetId of targetIds) {
+      const target = this.registry.get(targetId);
+      if (opts.clearBindings) target?.binding?.clearAll?.();
+      this.clearTargetState(target);
+    }
+  }
+
+  private setPartial(partial: DictationPartialState | null): void {
+    this.activePartial = partial;
+    this.opts.setPartial(partial);
+  }
+
+  private resolveSegmentTargetId(
+    segmentId: string | undefined,
+    payloadTargetId?: string
+  ): string | null {
+    const activeTargetId = this.registry.getActiveTargetId();
+    if (!segmentId) {
+      if (payloadTargetId && this.registry.get(payloadTargetId)) return payloadTargetId;
+      return payloadTargetId ? null : activeTargetId;
+    }
+    const mappedTargetId = this.segmentTargetMap.get(segmentId);
+    if (mappedTargetId) return mappedTargetId;
+    if (payloadTargetId) {
+      if (!this.registry.get(payloadTargetId)) return null;
+      this.segmentTargetMap.set(segmentId, payloadTargetId);
+      return payloadTargetId;
+    }
+    if (!this.segmentTargetMap.has(segmentId) && activeTargetId) {
+      this.segmentTargetMap.set(segmentId, activeTargetId);
+    }
+    return this.segmentTargetMap.get(segmentId) ?? activeTargetId;
+  }
+
+  private getSegmentTarget(segmentId: string): DictationTarget | undefined {
+    const targetId = this.resolveSegmentTargetId(segmentId);
+    return targetId ? this.registry.get(targetId) : undefined;
+  }
+}