@linto-ai/transcript-ui-core 0.9.0

package/src/types/api.ts

@@ -0,0 +1,52 @@
+/** Types mirroring the backend API JSON format */
+
+export interface ApiWord {
+  /** Legacy identity — still present in Mongo/REST payloads for other
+   *  consumers, ignored by the editor (words align by token index). */
+  wid?: string
+  stime?: number
+  etime?: number
+  word: string
+  confidence?: number
+}
+
+export interface ApiTurn {
+  speaker_id: string
+  turn_id: string
+  segment: string
+  raw_segment: string
+  words: ApiWord[]
+  stime?: number
+  etime?: number
+  language: string
+}
+
+export interface ApiSpeaker {
+  speaker_id: string
+  speaker_name: string
+  stime: number
+  etime: number
+}
+
+export interface ApiAudioMetadata {
+  filename: string
+  duration: number
+  mimetype: string
+  filepath: string
+}
+
+export interface ApiMetadata {
+  transcription: {
+    lang: string
+    confidence: number
+  }
+  audio: ApiAudioMetadata
+}
+
+export interface ApiDocument {
+  name: string
+  description: string
+  speakers: ApiSpeaker[]
+  text: ApiTurn[]
+  metadata: ApiMetadata
+}

package/src/types/editor.ts

@@ -0,0 +1,65 @@
+/** Internal editor types — backend-agnostic */
+
+export interface Word {
+  /** Derived, positional: `${turnId}#${index}`. Recomputed on every text
+   *  change — an opaque key for consumers, never persisted. */
+  id: string
+  text: string
+  /** Offsets into the turn's plain text (UTF-16 code units), derived locally
+   *  by tokenization — the karaoke/click/follow anchor. */
+  charStart?: number
+  charEnd?: number
+  startTime?: number
+  endTime?: number
+  confidence?: number
+}
+
+export interface Turn {
+  id: string
+  speakerId: string | null
+  text: string | null // non-null when words is empty (live text-only), null otherwise
+  words: Word[] // non-empty for word-level detail (ASR), empty when text is the source
+  startTime?: number
+  endTime?: number
+  startDate?: number // Unix timestamp in seconds — wall-clock fallback when startTime is absent
+  endDate?: number
+  language: string
+  /** Original language of the turn (the side being translated from); live-only. */
+  sourceLanguage?: string
+}
+
+export interface Speaker {
+  id: string
+  name: string
+  color: string
+}
+
+export interface AudioSource {
+  src: string
+  filename?: string
+}
+
+export interface Translation {
+  id: string
+  languages: string[] // ["fr", "en"] for source, ["es"] for auto-translation
+  isSource: boolean
+  audio?: AudioSource
+  turns: Turn[]
+}
+
+export interface Channel {
+  id: string
+  name: string
+  description?: string
+  duration: number
+  translations: Translation[] // at least 1 (the source)
+}
+
+export interface EditorDocument {
+  title: string
+  description?: string
+  /** ISO date string or Unix timestamp (seconds) — date the recording took place */
+  date?: string | number
+  speakers: Map<string, Speaker>
+  channels: Channel[]
+}

package/src/types/whisperx.ts

@@ -0,0 +1,22 @@
+/** Types mirroring the WhisperX JSON output format */
+
+export interface WhisperXWord {
+  word: string
+  start: number
+  end: number
+  score: number
+  speaker?: string
+}
+
+export interface WhisperXSegment {
+  start: number
+  end: number
+  text: string
+  speaker?: string
+  words: WhisperXWord[]
+}
+
+export interface WhisperXDocument {
+  segments: WhisperXSegment[]
+  language?: string
+}

package/src/utils/color.ts

@@ -0,0 +1,7 @@
+export function hexToRgba(hex: string, alpha: number): string {
+  const cleaned = hex.replace('#', '')
+  const r = parseInt(cleaned.substring(0, 2), 16)
+  const g = parseInt(cleaned.substring(2, 4), 16)
+  const b = parseInt(cleaned.substring(4, 6), 16)
+  return `rgba(${r}, ${g}, ${b}, ${alpha})`
+}

package/src/utils/computeCaretOffsetFromPoint.ts

@@ -0,0 +1,56 @@
+import { computeTextOffsetInContainer } from "@linto-ai/transcript-ui-ui"
+
+interface CaretPoint {
+  node: Node
+  offset: number
+}
+
+// Shadow roots enclosing `node`, innermost first. caretPositionFromPoint
+// only resolves inside a shadow root when that root is listed in its
+// shadowRoots option — Chrome clamps to the host otherwise (Firefox pierces
+// the boundary even without it).
+function collectShadowRoots(node: Node): ShadowRoot[] {
+  const roots: ShadowRoot[] = []
+  let root = node.getRootNode()
+  while (root instanceof ShadowRoot) {
+    roots.push(root)
+    root = root.host.getRootNode()
+  }
+  return roots
+}
+
+// Firefox/Chrome expose caretPositionFromPoint; Safari only the older
+// caretRangeFromPoint (which clamps to the shadow host — callers get null
+// and fall back). Both resolve a viewport point to a DOM position.
+function resolveCaretPoint(
+  container: HTMLElement,
+  x: number,
+  y: number,
+): CaretPoint | null {
+  const doc = container.ownerDocument
+  if (typeof doc.caretPositionFromPoint === "function") {
+    const position = doc.caretPositionFromPoint(x, y, {
+      shadowRoots: collectShadowRoots(container),
+    })
+    if (!position) return null
+    return { node: position.offsetNode, offset: position.offset }
+  }
+  const range = doc.caretRangeFromPoint?.(x, y)
+  if (!range) return null
+  return { node: range.startContainer, offset: range.startOffset }
+}
+
+/**
+ * Character offset in `container`'s plain text for a clicked viewport point,
+ * or null when the point doesn't resolve inside the container (caller picks
+ * its fallback — usually end of text).
+ */
+export function computeCaretOffsetFromPoint(
+  container: HTMLElement,
+  x: number,
+  y: number,
+): number | null {
+  const point = resolveCaretPoint(container, x, y)
+  if (!point || !container.contains(point.node)) return null
+  return computeTextOffsetInContainer(container, point.node, point.offset)
+}

package/src/utils/computeTurnPlainText.ts

@@ -0,0 +1,9 @@
+import type { Turn } from "../types/editor"
+
+/** A turn's editable plain text: the words joined by single spaces (the
+ *  normalized whitespace contract shared with the server), or the raw text
+ *  for words-less turns. */
+export function computeTurnPlainText(turn: Turn): string {
+  if (turn.words.length > 0) return turn.words.map((w) => w.text).join(" ")
+  return turn.text ?? ""
+}

package/src/utils/extractLangCode.ts

@@ -0,0 +1,7 @@
+/**
+ * Normalize a language tag to its base code, dropping any region/subtag.
+ * e.g. "fr-FR" → "fr", "en" → "en".
+ */
+export function extractLangCode(language: string): string {
+  return language.split("-")[0]!
+}

package/src/utils/findWordAtOffset.ts

@@ -0,0 +1,16 @@
+import type { Word } from "../types/editor"
+
+/** The word whose [charStart, charEnd) range contains the offset, if any —
+ *  words without offsets (defensive) never match. */
+export function findWordAtOffset(
+  words: Word[],
+  offset: number,
+): Word | undefined {
+  return words.find(
+    (w) =>
+      w.charStart != null &&
+      w.charEnd != null &&
+      w.charStart <= offset &&
+      offset < w.charEnd,
+  )
+}

package/src/utils/index.ts

@@ -0,0 +1,19 @@
+export { hexToRgba } from "./color"
+export { extractLangCode } from "./extractLangCode"
+export { isSameLanguage } from "./isSameLanguage"
+export { getLanguageDisplayName, buildTranslationItems } from "./intl"
+export { throttle } from "./throttle"
+export {
+  formatTime,
+  formatShortDateTime,
+  formatLongDate,
+  formatDurationMinutes,
+  formatRelativeFromNow,
+} from "./time"
+export { validateEditorDocument, DocumentValidationError } from "./validateDocument"
+export { renderWaveform, normalizePeaks } from "./waveform"
+export { findActiveWord, hasWordTimestamps, firstWordStart, lastWordEnd } from "./words"
+export { speakText, stopTTS, unlockTTS, isTTSSupported, hasVoices } from "./tts"
+export { computeTurnPlainText } from "./computeTurnPlainText"
+export { wordsFromText, wordsFromApi, carryWordTimes, layoutWords, parseWordId, wordId } from "./turnWords"
+export type { TimedText } from "./turnWords"

package/src/utils/intl.ts

@@ -0,0 +1,47 @@
+import type { TranslationInfo } from "../core/types"
+
+export function getLanguageDisplayName(
+  code: string,
+  locale: string,
+  wildcardLabel = "*",
+  stripRegion = true,
+): string {
+  // Some backend turns carry no language at all — an empty name hides the chip.
+  if (!code) return ""
+  if (code === "*") return wildcardLabel
+  const lookup = stripRegion ? (code.split("-")[0] ?? code) : code
+  try {
+    const display = new Intl.DisplayNames([locale], { type: "language" })
+    return display.of(lookup) ?? display.of(code.split("-")[0] ?? code) ?? code
+  } catch {
+    return code
+  }
+}
+
+export function buildTranslationItems(
+  translations: TranslationInfo[],
+  locale: string,
+  originalLabel: string,
+  wildcardLabel = "*",
+  bilingualLabel = "",
+): { value: string; label: string }[] {
+  const sorted = [...translations].sort(
+    (a, b) => Number(b.isSource) - Number(a.isSource),
+  )
+  return sorted.map((tr) => {
+    // The virtual cross translation is the only non-source track with >1 language.
+    const isBilingual = !tr.isSource && tr.languages.length > 1
+    return {
+      value: tr.id,
+      label: tr.isSource
+        ? originalLabel
+        : isBilingual && bilingualLabel
+          ? bilingualLabel
+          : tr.languages
+              .map((code) =>
+                getLanguageDisplayName(code, locale, wildcardLabel, false),
+              )
+              .join(", "),
+    }
+  })
+}

package/src/utils/isSameLanguage.ts

@@ -0,0 +1,13 @@
+import { extractLangCode } from "./extractLangCode"
+
+/**
+ * Compare two language tags ignoring region/subtag — "fr-FR" matches "fr".
+ * Returns false when either tag is missing.
+ */
+export function isSameLanguage(
+  a: string | undefined,
+  b: string | undefined,
+): boolean {
+  if (a == null || b == null) return false
+  return extractLangCode(a) === extractLangCode(b)
+}

package/src/utils/test/computeTurnPlainText.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "bun:test"
+import { computeTurnPlainText } from "../computeTurnPlainText"
+import type { Turn } from "../../types/editor"
+
+function makeTurn(partial: Partial<Turn>): Turn {
+  return {
+    id: "turn-1",
+    speakerId: null,
+    text: null,
+    words: [],
+    language: "fr",
+    ...partial,
+  }
+}
+
+describe("computeTurnPlainText", () => {
+  it("joins words with single spaces", () => {
+    const turn = makeTurn({
+      words: [
+        { id: "turn-1#0", text: "Bonjour" },
+        { id: "turn-1#1", text: "tout" },
+        { id: "turn-1#2", text: "le" },
+      ],
+    })
+    expect(computeTurnPlainText(turn)).toBe("Bonjour tout le")
+  })
+
+  it("falls back to the raw text for words-less turns", () => {
+    expect(computeTurnPlainText(makeTurn({ text: "texte brut" }))).toBe(
+      "texte brut",
+    )
+    expect(computeTurnPlainText(makeTurn({}))).toBe("")
+  })
+})

package/src/utils/test/findWordAtOffset.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "bun:test"
+import { findWordAtOffset } from "../findWordAtOffset"
+import { wordsFromText } from "../turnWords"
+
+// "Bonjour tout" — Bonjour[0,7[ tout[8,12[
+const WORDS = wordsFromText("turn-1", "Bonjour tout")
+
+describe("findWordAtOffset", () => {
+  it("resolves the word containing the offset", () => {
+    expect(findWordAtOffset(WORDS, 0)?.text).toBe("Bonjour")
+    expect(findWordAtOffset(WORDS, 6)?.text).toBe("Bonjour")
+    expect(findWordAtOffset(WORDS, 8)?.text).toBe("tout")
+  })
+
+  it("returns nothing in a gap or past the end", () => {
+    expect(findWordAtOffset(WORDS, 7)).toBeUndefined()
+    expect(findWordAtOffset(WORDS, 12)).toBeUndefined()
+  })
+
+  it("skips words without offsets", () => {
+    expect(
+      findWordAtOffset([{ id: "t#0", text: "x" }], 0),
+    ).toBeUndefined()
+  })
+})

package/src/utils/throttle.ts

@@ -0,0 +1,23 @@
+function throttle(fn: (...args: unknown[]) => void, delay = 250) {
+  let isThrottled = false
+  let pendingArgs: unknown[] | null = null
+
+  return (...args: unknown[]) => {
+    if (isThrottled) {
+      pendingArgs = args
+      return
+    }
+    isThrottled = true
+    fn(...args)
+    setTimeout(() => {
+      isThrottled = false
+      if (pendingArgs !== null) {
+        const saved = pendingArgs
+        pendingArgs = null
+        fn(...saved)
+      }
+    }, delay)
+  }
+}
+
+export { throttle }

package/src/utils/time.ts

@@ -0,0 +1,95 @@
+export function formatTime(seconds: number): string {
+  const totalSeconds = Math.floor(seconds)
+  const hours = Math.floor(totalSeconds / 3600)
+  const minutes = Math.floor((totalSeconds % 3600) / 60)
+  const secs = totalSeconds % 60
+  const mm = String(minutes).padStart(2, "0")
+  const ss = String(secs).padStart(2, "0")
+  if (hours > 0) {
+    return `${hours}:${mm}:${ss}`
+  }
+  return `${mm}:${ss}`
+}
+
+export function formatShortDateTime(
+  unixSeconds: number,
+  locale: string,
+): string {
+  return new Intl.DateTimeFormat(locale, {
+    //day: "numeric",
+    //month: "numeric",
+    hour: "2-digit",
+    minute: "2-digit",
+  }).format(new Date(unixSeconds * 1000))
+}
+
+function toDate(value: string | number): Date | null {
+  if (typeof value === "number") {
+    const ms = value < 1e12 ? value * 1000 : value
+    const d = new Date(ms)
+    return Number.isNaN(d.getTime()) ? null : d
+  }
+  const d = new Date(value)
+  return Number.isNaN(d.getTime()) ? null : d
+}
+
+export function formatLongDate(
+  value: string | number,
+  locale: string,
+): string {
+  const d = toDate(value)
+  if (!d) return ""
+  return new Intl.DateTimeFormat(locale, {
+    day: "numeric",
+    month: "long",
+    year: "numeric",
+  }).format(d)
+}
+
+export function formatDurationMinutes(
+  seconds: number,
+  locale: string,
+): string {
+  const minutes = Math.max(0, Math.round(seconds / 60))
+  if (minutes < 60) {
+    return new Intl.NumberFormat(locale, {
+      style: "unit",
+      unit: "minute",
+      unitDisplay: "narrow",
+    }).format(minutes)
+  }
+  const hours = Math.floor(minutes / 60)
+  const remaining = minutes % 60
+  const h = new Intl.NumberFormat(locale, {
+    style: "unit",
+    unit: "hour",
+    unitDisplay: "narrow",
+  }).format(hours)
+  if (remaining === 0) return h
+  const m = new Intl.NumberFormat(locale, {
+    style: "unit",
+    unit: "minute",
+    unitDisplay: "narrow",
+  }).format(remaining)
+  return `${h} ${m}`
+}
+
+export function formatRelativeFromNow(
+  value: string | number,
+  locale: string,
+): string {
+  const d = toDate(value)
+  if (!d) return ""
+  const diffSec = Math.round((Date.now() - d.getTime()) / 1000)
+  const rtf = new Intl.RelativeTimeFormat(locale, { numeric: "auto" })
+  if (Math.abs(diffSec) < 60) {
+    return rtf.format(0, "minute")
+  }
+  if (Math.abs(diffSec) < 3600) {
+    return rtf.format(-Math.round(diffSec / 60), "minute")
+  }
+  if (Math.abs(diffSec) < 86400) {
+    return rtf.format(-Math.round(diffSec / 3600), "hour")
+  }
+  return rtf.format(-Math.round(diffSec / 86400), "day")
+}

package/src/utils/tokenize.ts

@@ -0,0 +1,34 @@
+/**
+ * THE tokenization contract, shared by contract with the backend
+ * (studio-api/components/EditorHandler/words/tokenize.js): a word token is a
+ * maximal run of non-whitespace characters. Client and server MUST tokenize
+ * identically — word/timestamp payloads are aligned by token index, with no
+ * wid and no character offsets on the wire.
+ *
+ * Offsets are expressed in UTF-16 code units (plain JS string indices),
+ * relative to the turn's own text. They never leave the process: each side
+ * derives its own from its own copy of the text.
+ */
+
+export interface Token {
+  text: string
+  charStart: number
+  charEnd: number
+}
+
+const TOKEN_RE = /\S+/g
+
+export function tokenize(text: string): Token[] {
+  const tokens: Token[] = []
+  if (!text) return tokens
+  TOKEN_RE.lastIndex = 0
+  let m: RegExpExecArray | null
+  while ((m = TOKEN_RE.exec(text)) !== null) {
+    tokens.push({
+      text: m[0],
+      charStart: m.index,
+      charEnd: m.index + m[0].length,
+    })
+  }
+  return tokens
+}

package/src/utils/tts.ts

@@ -0,0 +1,49 @@
+// Browser speech synthesis (Web Speech API) helpers for reading turns aloud.
+
+const TTS_SUPPORTED =
+  typeof window !== "undefined" && "speechSynthesis" in window
+
+export function isTTSSupported(): boolean {
+  return TTS_SUPPORTED
+}
+
+// At least one voice installed (the list loads async — also watch "voiceschanged").
+export function hasVoices(): boolean {
+  return TTS_SUPPORTED && window.speechSynthesis.getVoices().length > 0
+}
+
+// Voice for the language (exact tag, else base code); null → use the default.
+function findVoice(lang: string): SpeechSynthesisVoice | null {
+  if (!TTS_SUPPORTED || !lang || lang === "*") return null
+  const norm = lang.toLowerCase()
+  const base = norm.split("-")[0]
+  const voices = window.speechSynthesis.getVoices()
+  const exact = voices.find((v) => v.lang.toLowerCase() === norm)
+  if (exact) return exact
+  return voices.find((v) => v.lang.toLowerCase().split("-")[0] === base) ?? null
+}
+
+// Speaks text in its language; calls queue and play in order. Falls back to the
+// browser's default voice when no voice matches the language.
+export function speakText(text: string, lang?: string | null): void {
+  if (!isTTSSupported()) return
+  const clean = text.trim()
+  if (!clean) return
+  const utterance = new SpeechSynthesisUtterance(clean)
+  const voice = lang ? findVoice(lang) : null
+  if (voice) {
+    utterance.voice = voice
+    utterance.lang = voice.lang
+  }
+  window.speechSynthesis.speak(utterance)
+}
+
+// Silent utterance within a user gesture, to unlock later event-driven playback.
+export function unlockTTS(): void {
+  if (!isTTSSupported()) return
+  window.speechSynthesis.speak(new SpeechSynthesisUtterance(" "))
+}
+
+export function stopTTS(): void {
+  if (isTTSSupported()) window.speechSynthesis.cancel()
+}

package/src/utils/turnWords/carryWordTimes.ts

@@ -0,0 +1,37 @@
+import type { Word } from "../../types/editor"
+
+/**
+ * Carry timestamps from the previous word list onto freshly derived tokens by
+ * anchoring on the common prefix and suffix (token text equality). The edited
+ * middle stays untimed until the server broadcasts recomputed timings (it
+ * re-flushes after every edit, so the gap lasts about a debounce). Cheap,
+ * deterministic, and wrong only transiently — by design.
+ */
+export function carryWordTimes(next: Word[], prev: Word[]): Word[] {
+  const max = Math.min(next.length, prev.length)
+  let prefix = 0
+  while (prefix < max && next[prefix]!.text === prev[prefix]!.text) prefix++
+  let suffix = 0
+  while (
+    suffix < max - prefix &&
+    next[next.length - 1 - suffix]!.text === prev[prev.length - 1 - suffix]!.text
+  ) {
+    suffix++
+  }
+
+  return next.map((w, i) => {
+    const from =
+      i < prefix
+        ? prev[i]
+        : i >= next.length - suffix
+          ? prev[prev.length - (next.length - i)]
+          : undefined
+    if (!from) return w
+    return {
+      ...w,
+      ...(from.startTime !== undefined && { startTime: from.startTime }),
+      ...(from.endTime !== undefined && { endTime: from.endTime }),
+      ...(from.confidence !== undefined && { confidence: from.confidence }),
+    }
+  })
+}

package/src/utils/turnWords/index.ts

@@ -0,0 +1,6 @@
+export { wordId } from "./wordId"
+export { parseWordId } from "./parseWordId"
+export { wordsFromText } from "./wordsFromText"
+export { layoutWords, type TimedText } from "./layoutWords"
+export { wordsFromApi } from "./wordsFromApi"
+export { carryWordTimes } from "./carryWordTimes"

package/src/utils/turnWords/layoutWords.ts

@@ -0,0 +1,41 @@
+import { wordId } from "./wordId"
+import type { Word } from "../../types/editor"
+
+export interface TimedText {
+  text: string
+  startTime?: number
+  endTime?: number
+  confidence?: number
+}
+
+/**
+ * Lay timed source words out as store Words matching the doc text EXACTLY.
+ * The seed (client and server turnsToDoc alike) joins tokens with single
+ * spaces and collapses all whitespace — so a stored word carrying irregular
+ * whitespace (NBSP, internal space: "l'enfant ?") is SPLIT into its tokens
+ * here, each keeping the source word's timing. Without this, every offset
+ * after such a word would be shifted from the rendered text at load.
+ * Empty/whitespace-only source words (silence placeholders) yield nothing.
+ */
+export function layoutWords(turnId: string, source: TimedText[]): Word[] {
+  const out: Word[] = []
+  let cursor = 0
+  for (const src of source) {
+    for (const part of (src.text ?? "").split(/\s+/)) {
+      if (!part) continue
+      const charStart = cursor
+      const charEnd = charStart + part.length
+      cursor = charEnd + 1
+      out.push({
+        id: wordId(turnId, out.length),
+        text: part,
+        charStart,
+        charEnd,
+        ...(src.startTime !== undefined && { startTime: src.startTime }),
+        ...(src.endTime !== undefined && { endTime: src.endTime }),
+        ...(src.confidence !== undefined && { confidence: src.confidence }),
+      })
+    }
+  }
+  return out
+}