@ephia/dova-sdk 1.0.0

package/src/core/transcript/transcript.assembler.ts

@@ -0,0 +1,152 @@
+import type { LiveTranscriptChunk } from "./transcript.state";
+
+function trimBoundarySpaces(text: string): string {
+  return text
+    .replace(/\r\n/g, "\n")
+    .replace(/\r/g, "\n")
+    .replace(/^[ \t]+|[ \t]+$/g, "");
+}
+
+/**
+ * Joint deux morceaux de texte avec gestion intelligente des espaces et de la ponctuation.
+ * Exported pour être réutilisé dans les autres reducers.
+ */
+export function joinWithSpacing(prev: string, next: string): string {
+  if (!prev) return next;
+  if (!next) return prev;
+  const lastChar = prev.slice(-1);
+  const firstChar = next.charAt(0);
+  if (lastChar === " " && firstChar === " ") return prev + next.trimStart();
+  if (/\s/.test(lastChar) || /\s/.test(firstChar)) return prev + next;
+  if (/[,.;:!?)\]]/.test(firstChar)) return prev + next;
+  return prev + " " + next;
+}
+
+/**
+ * Assemble les chunks en texte cohérent.
+ *
+ * Règles :
+ * - tri par segmentSeq
+ * - pas de double espace
+ * - espace après ponctuation si manquant
+ * - ignorer les chunks error sans texte
+ */
+export function assembleTranscript(chunks: LiveTranscriptChunk[]): string {
+  const sorted = [...chunks]
+    .filter((c) => (c.status === "done" || c.finalizedText) && (c.text || c.finalizedText))
+    .sort((a, b) => a.segmentSeq - b.segmentSeq);
+
+  if (sorted.length === 0) return "";
+
+  let result = "";
+  for (let i = 0; i < sorted.length; i++) {
+    const chunk = sorted[i];
+    let text = trimBoundarySpaces(chunk.text || chunk.finalizedText || "");
+
+    if (i === 0) {
+      result = text;
+      continue;
+    }
+
+    const prev = result;
+    const lastChar = prev.slice(-1);
+    const firstChar = text.charAt(0);
+
+    // Règles d'espacement
+    if (lastChar.match(/[.!?;,:\)]/) && firstChar.match(/[a-zA-ZÀ-ÿ0-9]/)) {
+      result = prev + " " + text;
+    } else if (/\s/.test(lastChar) && /\s/.test(firstChar)) {
+      result = prev + text.trimStart();
+    } else if (
+      !/\s/.test(lastChar) &&
+      !/\s/.test(firstChar) &&
+      firstChar.match(/[a-zA-ZÀ-ÿ0-9]/)
+    ) {
+      result = prev + " " + text;
+    } else {
+      result = prev + text;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Assemble les chunks commités en document texte.
+ *
+ * Règles :
+ * - tri par segmentSeq
+ * - utilise committedText ou text si disponible
+ * - ignore les chunks fusionnés (mergedWith présent)
+ */
+export function assembleCommittedDocument(
+  chunks: Record<string, LiveTranscriptChunk>,
+  orderedSegmentIds: string[]
+): string {
+  const sorted = [...orderedSegmentIds]
+    .map((id) => chunks[id])
+    .filter((c): c is LiveTranscriptChunk => !!c && c.status === "done")
+    .filter((c) => !c.mergedWith || Array.isArray(c.mergedWith))
+    .sort((a, b) => a.segmentSeq - b.segmentSeq);
+
+  if (sorted.length === 0) return "";
+
+  let result = "";
+  for (let i = 0; i < sorted.length; i++) {
+    const chunk = sorted[i];
+    const text = trimBoundarySpaces(chunk.committedText ?? chunk.text ?? "");
+    if (!text) continue;
+
+    if (i === 0) {
+      result = text;
+      continue;
+    }
+
+    const prev = result;
+    const lastChar = prev.slice(-1);
+    const firstChar = text.charAt(0);
+
+    if (lastChar.match(/[.!?;,:\)]/) && firstChar.match(/[a-zA-ZÀ-ÿ0-9]/)) {
+      result = prev + " " + text;
+    } else if (/\s/.test(lastChar) && /\s/.test(firstChar)) {
+      result = prev + text.trimStart();
+    } else if (
+      !/\s/.test(lastChar) &&
+      !/\s/.test(firstChar) &&
+      firstChar.match(/[a-zA-ZÀ-ÿ0-9]/)
+    ) {
+      result = prev + " " + text;
+    } else {
+      result = prev + text;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Construit le texte d'affichage complet :
+ * finalText + previewText du chunk courant.
+ */
+const PUNCTUATION_NO_SPACE = new Set([",", ".", ";", ":", "!", "?", ")", "]", "}"]);
+
+export function buildDisplayText(
+  finalText: string,
+  previewText: string,
+  previewContinuesPreviousWord = false
+): string {
+  if (!finalText && !previewText) return "";
+  if (!finalText) return previewText;
+  if (!previewText) return finalText;
+  // trimEnd() supprimerait les \n intentionnels (commandes "à la ligne")
+  const prev = finalText.replace(/[ \t]+$/, "");
+  const next = previewText.trimStart();
+  if (!next) return prev;
+  if (previewContinuesPreviousWord) return prev + next;
+  const firstChar = next[0];
+  if (firstChar && PUNCTUATION_NO_SPACE.has(firstChar)) {
+    return prev + next;
+  }
+  if (prev.endsWith("\n")) return prev + next;
+  return prev + " " + next;
+}

package/src/core/transcript/transcript.reducer.test.ts

@@ -0,0 +1,199 @@
+import { describe, expect, it } from "vitest";
+import { liveTranscriptReducer } from "./transcript.reducer";
+import { initialLiveTranscriptState } from "./transcript.state";
+import type { LiveTranscriptAction } from "./transcript.reducer";
+import { PROTOCOL_VERSION, type EphiaAudioEvent } from "ephia-protocol";
+
+function makeEnvelope<T extends string>(
+  type: T,
+  payload: Record<string, unknown>,
+  seq = 1
+): EphiaAudioEvent {
+  return {
+    protocolVersion: PROTOCOL_VERSION,
+    eventId: `00000000-0000-4000-8000-${String(seq).padStart(12, "0")}`,
+    sessionId: "test-session",
+    type,
+    seq,
+    timestampMs: Date.now(),
+    payload,
+  } as unknown as EphiaAudioEvent;
+}
+
+function event(type: string, payload: Record<string, unknown>, seq = 1): LiveTranscriptAction {
+  return { type: "event", event: makeEnvelope(type, payload, seq) };
+}
+
+// ------------------------------------------------------------------
+// segment.audio.closed — conserver le preview jusqu'au committed
+// ------------------------------------------------------------------
+
+describe("segment.audio.closed", () => {
+  it("keeps preview text visible while waiting for committed", () => {
+    let state = initialLiveTranscriptState;
+
+    state = liveTranscriptReducer(
+      state,
+      event("segment.opened", { segmentId: "seg1", segmentSeq: 1, startMs: 0 }, 1)
+    );
+    state = liveTranscriptReducer(
+      state,
+      event(
+        "transcript.preview",
+        { segmentId: "seg1", segmentSeq: 1, text: "Bonjour docteur", revision: 1 },
+        2
+      )
+    );
+
+    state = liveTranscriptReducer(
+      state,
+      event(
+        "segment.audio.closed",
+        { segmentId: "seg1", segmentSeq: 1, endMs: 1000, reason: "vad_end" },
+        3
+      )
+    );
+
+    expect(state.chunks["seg1"]?.previewText).toBe("Bonjour docteur");
+    expect(state.chunks["seg1"]?.status).toBe("processing");
+    expect(state.displayText).toContain("Bonjour docteur");
+  });
+
+  it("enriches preview after audio closed when a later partial arrives", () => {
+    let state = initialLiveTranscriptState;
+
+    state = liveTranscriptReducer(
+      state,
+      event("segment.opened", { segmentId: "seg1", segmentSeq: 1, startMs: 0 }, 1)
+    );
+    state = liveTranscriptReducer(
+      state,
+      event(
+        "transcript.preview",
+        { segmentId: "seg1", segmentSeq: 1, text: "Bonjour", revision: 1 },
+        2
+      )
+    );
+    state = liveTranscriptReducer(
+      state,
+      event(
+        "segment.audio.closed",
+        { segmentId: "seg1", segmentSeq: 1, endMs: 1000, reason: "vad_end" },
+        3
+      )
+    );
+    state = liveTranscriptReducer(
+      state,
+      event(
+        "transcript.preview",
+        { segmentId: "seg1", segmentSeq: 1, text: "Bonjour docteur", revision: 6 },
+        4
+      )
+    );
+
+    expect(state.chunks["seg1"]?.status).toBe("preview");
+    expect(state.chunks["seg1"]?.previewText).toBe("Bonjour docteur");
+    expect(state.chunks["seg1"]?.revision).toBe(6);
+    expect(state.displayText).toContain("Bonjour docteur");
+    expect(state.orderedSegmentIds).toEqual(["seg1"]);
+  });
+});
+
+// ------------------------------------------------------------------
+// Replace Model: partial ignoré après committed
+// ------------------------------------------------------------------
+
+describe("Replace Model — partial after committed", () => {
+  it("does not overwrite committed text when a late partial arrives", () => {
+    let state = initialLiveTranscriptState;
+
+    // Segment opened
+    state = liveTranscriptReducer(state, event("segment.opened", { segmentId: "seg1", segmentSeq: 1, startMs: 0 }, 1));
+    // Committed
+    state = liveTranscriptReducer(state, event("transcript.segment.committed", {
+      segmentId: "seg1",
+      segmentSeq: 1,
+      text: "Texte final commité.",
+      source: "live",
+    }, 2));
+
+    expect(state.chunks["seg1"]?.status).toBe("done");
+    expect(state.chunks["seg1"]?.text).toBe("Texte final commité.");
+
+    // Late partial — status is already "done", partial should be ignored
+    state = liveTranscriptReducer(state, event("transcript.preview", {
+      segmentId: "seg1",
+      segmentSeq: 1,
+      text: "texte partiel tardif",
+      revision: 99,
+    }, 3));
+
+    expect(state.chunks["seg1"]?.text).toBe("Texte final commité.");
+    expect(state.chunks["seg1"]?.previewText).toBeUndefined();
+  });
+});
+
+// ------------------------------------------------------------------
+// session.context.reset — conservation des chunks finalisés
+// ------------------------------------------------------------------
+
+describe("session.context.reset", () => {
+  it("keeps finalized chunks without committedText on contextOnly reset", () => {
+    let state = initialLiveTranscriptState;
+
+    // Simulate a finalized segment arriving via transcript.final
+    // (no committedText set, only status="done" + text)
+    state = liveTranscriptReducer(
+      state,
+      event("transcript.final", {
+        segmentId: "seg-final",
+        segmentSeq: 1,
+        text: "Texte finalisé sans committedText.",
+        provider: "voxtral-small",
+      }, 1)
+    );
+
+    expect(state.chunks["seg-final"]?.status).toBe("done");
+    expect(state.chunks["seg-final"]?.committedText).toBeUndefined();
+
+    // Context-only reset (emitted by the backend when the client stops)
+    state = liveTranscriptReducer(
+      state,
+      event("session.context.reset", { contextOnly: true }, 2)
+    );
+
+    // The finalized chunk must survive the reset
+    expect(state.chunks["seg-final"]).toBeDefined();
+    expect(state.chunks["seg-final"]?.status).toBe("done");
+    expect(state.chunks["seg-final"]?.text).toBe("Texte finalisé sans committedText.");
+    expect(state.orderedSegmentIds).toContain("seg-final");
+    expect(state.documentText).toContain("Texte finalisé sans committedText.");
+  });
+});
+
+// ------------------------------------------------------------------
+// Sequence gap detection
+// ------------------------------------------------------------------
+
+describe("sequence gap detection", () => {
+  it("marks seqValid false when events arrive out of order", () => {
+    let state = initialLiveTranscriptState;
+
+    state = liveTranscriptReducer(state, event("session.ready", { roomName: "room1" }, 1));
+    expect(state.diagnostics.seqValid).toBe(true);
+
+    // Skip seq 2, jump to 3
+    state = liveTranscriptReducer(state, event("audio.vad.start", { timestampMs: 0 }, 3));
+    expect(state.diagnostics.seqValid).toBe(false);
+  });
+
+  it("keeps seqValid true for monotone consecutive events", () => {
+    let state = initialLiveTranscriptState;
+
+    state = liveTranscriptReducer(state, event("session.ready", { roomName: "room1" }, 1));
+    state = liveTranscriptReducer(state, event("audio.vad.start", { timestampMs: 0 }, 2));
+    state = liveTranscriptReducer(state, event("audio.vad.end", { timestampMs: 100, durationMs: 100 }, 3));
+
+    expect(state.diagnostics.seqValid).toBe(true);
+  });
+});