@linto-ai/transcript-ui-core 0.9.0

package/src/utils/turnWords/parseWordId.ts

@@ -0,0 +1,13 @@
+/** Inverse of wordId: split a `turnId#index` key back into its parts. */
+export function parseWordId(
+  id: string,
+): { turnId: string; index: number } | null {
+  const sep = id.lastIndexOf("#")
+  if (sep <= 0) return null
+  const raw = id.slice(sep + 1)
+  // Number("") is 0 — an empty index must not parse as word 0.
+  if (raw === "") return null
+  const index = Number(raw)
+  if (!Number.isInteger(index) || index < 0) return null
+  return { turnId: id.slice(0, sep), index }
+}

package/src/utils/turnWords/test/carryWordTimes.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "bun:test"
+import { carryWordTimes } from "../carryWordTimes"
+import { wordsFromText } from "../wordsFromText"
+import { layoutWords } from "../layoutWords"
+
+const prev = layoutWords("turn-1", [
+  { text: "Bonjour", startTime: 0, endTime: 0.8 },
+  { text: "tout", startTime: 0.9, endTime: 1.1 },
+  { text: "le", startTime: 1.2, endTime: 1.3 },
+  { text: "monde", startTime: 1.4, endTime: 1.8 },
+])
+
+describe("carryWordTimes", () => {
+  it("keeps every timing when the text is unchanged", () => {
+    const next = carryWordTimes(
+      wordsFromText("turn-1", "Bonjour tout le monde"),
+      prev,
+    )
+    expect(next.map((w) => w.startTime)).toEqual([0, 0.9, 1.2, 1.4])
+  })
+
+  it("keeps prefix/suffix timings and leaves the edited middle untimed", () => {
+    const next = carryWordTimes(
+      wordsFromText("turn-1", "Bonjour tous le monde"),
+      prev,
+    )
+    expect(next[0]?.startTime).toBe(0)
+    expect(next[1]?.startTime).toBeUndefined()
+    expect(next[2]?.startTime).toBe(1.2)
+    expect(next[3]?.startTime).toBe(1.4)
+  })
+
+  it("anchors the suffix by position from the end on insertion", () => {
+    const next = carryWordTimes(
+      wordsFromText("turn-1", "Bonjour vraiment tout le monde"),
+      prev,
+    )
+    expect(next.map((w) => w.startTime)).toEqual([0, undefined, 0.9, 1.2, 1.4])
+  })
+
+  it("carries what survives a deletion", () => {
+    const next = carryWordTimes(wordsFromText("turn-1", "Bonjour le monde"), prev)
+    expect(next[0]?.startTime).toBe(0)
+    expect(next[1]?.startTime).toBe(1.2)
+    expect(next[2]?.startTime).toBe(1.4)
+  })
+})

package/src/utils/turnWords/test/layoutWords.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "bun:test"
+import { layoutWords } from "../layoutWords"
+
+describe("layoutWords", () => {
+  it("lays timed words out with single-space offsets", () => {
+    const words = layoutWords("turn-1", [
+      { text: "Bonjour", startTime: 0, endTime: 0.8 },
+      { text: "tout", startTime: 0.9, endTime: 1.1 },
+    ])
+    expect(words).toEqual([
+      {
+        id: "turn-1#0",
+        text: "Bonjour",
+        charStart: 0,
+        charEnd: 7,
+        startTime: 0,
+        endTime: 0.8,
+      },
+      {
+        id: "turn-1#1",
+        text: "tout",
+        charStart: 8,
+        charEnd: 12,
+        startTime: 0.9,
+        endTime: 1.1,
+      },
+    ])
+  })
+
+  it("splits a source word with internal whitespace, each part keeping its timing", () => {
+    const words = layoutWords("turn-1", [
+      { text: "l'enfant ?", startTime: 2, endTime: 3 },
+    ])
+    expect(words.map((w) => w.text)).toEqual(["l'enfant", "?"])
+    expect(words[0]).toMatchObject({ charStart: 0, charEnd: 8, startTime: 2 })
+    expect(words[1]).toMatchObject({ charStart: 9, charEnd: 10, endTime: 3 })
+  })
+
+  it("skips silence placeholders (empty/whitespace-only words)", () => {
+    const words = layoutWords("turn-1", [
+      { text: "", startTime: 0, endTime: 1 },
+      { text: "  " },
+      { text: "mot", startTime: 1, endTime: 2 },
+    ])
+    expect(words.map((w) => w.text)).toEqual(["mot"])
+    expect(words[0]?.charStart).toBe(0)
+  })
+
+  it("omits absent timing fields instead of writing undefined", () => {
+    const [word] = layoutWords("turn-1", [{ text: "mot" }])
+    expect(word && "startTime" in word).toBe(false)
+    expect(word && "endTime" in word).toBe(false)
+  })
+})

package/src/utils/turnWords/test/parseWordId.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from "bun:test"
+import { parseWordId } from "../parseWordId"
+import { wordId } from "../wordId"
+
+describe("parseWordId", () => {
+  it("round-trips wordId", () => {
+    expect(parseWordId(wordId("turn-1", 4))).toEqual({
+      turnId: "turn-1",
+      index: 4,
+    })
+  })
+
+  it("splits on the LAST separator (turn ids may contain '#')", () => {
+    expect(parseWordId("a#b#7")).toEqual({ turnId: "a#b", index: 7 })
+  })
+
+  it("rejects malformed ids", () => {
+    expect(parseWordId("no-separator")).toBeNull()
+    expect(parseWordId("#3")).toBeNull()
+    expect(parseWordId("turn-1#")).toBeNull()
+    expect(parseWordId("turn-1#-2")).toBeNull()
+    expect(parseWordId("turn-1#1.5")).toBeNull()
+  })
+})

package/src/utils/turnWords/test/wordId.test.ts

@@ -0,0 +1,9 @@
+import { describe, expect, it } from "bun:test"
+import { wordId } from "../wordId"
+
+describe("wordId", () => {
+  it("derives the positional key", () => {
+    expect(wordId("turn-1", 0)).toBe("turn-1#0")
+    expect(wordId("turn-1", 12)).toBe("turn-1#12")
+  })
+})

package/src/utils/turnWords/test/wordsFromApi.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "bun:test"
+import { wordsFromApi } from "../wordsFromApi"
+
+describe("wordsFromApi", () => {
+  it("maps API fields (word/stime/etime/confidence) onto store words", () => {
+    const words = wordsFromApi("turn-1", [
+      { wid: "w1", word: "Bonjour", stime: 0, etime: 0.8, confidence: 0.9 },
+      { wid: "w2", word: "tout" },
+    ])
+    expect(words[0]).toMatchObject({
+      id: "turn-1#0",
+      text: "Bonjour",
+      startTime: 0,
+      endTime: 0.8,
+      confidence: 0.9,
+    })
+    expect(words[1]).toMatchObject({ id: "turn-1#1", text: "tout" })
+    expect(words[1] && "startTime" in words[1]).toBe(false)
+  })
+})

package/src/utils/turnWords/test/wordsFromText.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from "bun:test"
+import { wordsFromText } from "../wordsFromText"
+
+describe("wordsFromText", () => {
+  it("derives positional words with offsets from plain text", () => {
+    expect(wordsFromText("turn-1", "Bonjour tout le")).toEqual([
+      { id: "turn-1#0", text: "Bonjour", charStart: 0, charEnd: 7 },
+      { id: "turn-1#1", text: "tout", charStart: 8, charEnd: 12 },
+      { id: "turn-1#2", text: "le", charStart: 13, charEnd: 15 },
+    ])
+  })
+
+  it("returns no words for empty or whitespace-only text", () => {
+    expect(wordsFromText("turn-1", "")).toEqual([])
+    expect(wordsFromText("turn-1", "   ")).toEqual([])
+  })
+})

package/src/utils/turnWords/wordId.ts

@@ -0,0 +1,9 @@
+/**
+ * Word identity is positional now that the document is plain text: a word IS
+ * the i-th whitespace-delimited token of its turn. Word.id is derived
+ * (`turnId#index`) — an opaque, recomputable key for consumers (karaoke,
+ * follow-playback), never persisted and never on the wire.
+ */
+export function wordId(turnId: string, index: number): string {
+  return `${turnId}#${index}`
+}

package/src/utils/turnWords/wordsFromApi.ts

@@ -0,0 +1,16 @@
+import { layoutWords } from "./layoutWords"
+import type { Word } from "../../types/editor"
+import type { ApiWord } from "../../types/api"
+
+/** Build the word list from an API turn payload (see layoutWords). */
+export function wordsFromApi(turnId: string, apiWords: ApiWord[]): Word[] {
+  return layoutWords(
+    turnId,
+    apiWords.map((w) => ({
+      text: w.word ?? "",
+      ...(w.stime !== undefined && { startTime: w.stime }),
+      ...(w.etime !== undefined && { endTime: w.etime }),
+      ...(w.confidence !== undefined && { confidence: w.confidence }),
+    })),
+  )
+}

package/src/utils/turnWords/wordsFromText.ts

@@ -0,0 +1,14 @@
+import { tokenize } from "../tokenize"
+import { wordId } from "./wordId"
+import type { Word } from "../../types/editor"
+
+/** Derive the word list from a turn's plain text (no timestamps — those are
+ *  carried over or broadcast by the server). */
+export function wordsFromText(turnId: string, text: string): Word[] {
+  return tokenize(text).map((t, i) => ({
+    id: wordId(turnId, i),
+    text: t.text,
+    charStart: t.charStart,
+    charEnd: t.charEnd,
+  }))
+}

package/src/utils/validateDocument.ts

@@ -0,0 +1,80 @@
+import type { EditorDocument } from "../types/editor"
+
+export class DocumentValidationError extends Error {
+  path: string
+  constructor(path: string, message: string) {
+    super(`${path}: ${message}`)
+    this.name = "DocumentValidationError"
+    this.path = path
+  }
+}
+
+export function validateEditorDocument(doc: unknown): asserts doc is EditorDocument {
+  if (doc == null || typeof doc !== "object") {
+    throw new DocumentValidationError("document", "must be a non-null object")
+  }
+
+  const d = doc as Record<string, unknown>
+
+  if (typeof d.title !== "string") {
+    throw new DocumentValidationError("document.title", "must be a string")
+  }
+
+  if (!(d.speakers instanceof Map)) {
+    throw new DocumentValidationError("document.speakers", "must be a Map")
+  }
+
+  if (!Array.isArray(d.channels)) {
+    throw new DocumentValidationError("document.channels", "must be an array")
+  }
+
+  for (let ci = 0; ci < d.channels.length; ci++) {
+    const ch = d.channels[ci] as Record<string, unknown>
+    const cp = `channels[${ci}]`
+
+    if (ch == null || typeof ch !== "object") {
+      throw new DocumentValidationError(cp, "must be a non-null object")
+    }
+
+    if (typeof ch.id !== "string") {
+      throw new DocumentValidationError(`${cp}.id`, "must be a string")
+    }
+
+    if (typeof ch.name !== "string") {
+      throw new DocumentValidationError(`${cp}.name`, "must be a string")
+    }
+
+    if (typeof ch.duration !== "number") {
+      throw new DocumentValidationError(`${cp}.duration`, "must be a number")
+    }
+
+    if (!Array.isArray(ch.translations)) {
+      throw new DocumentValidationError(`${cp}.translations`, "must be an array")
+    }
+
+    for (let ti = 0; ti < ch.translations.length; ti++) {
+      const tr = ch.translations[ti] as Record<string, unknown>
+      const tp = `${cp}.translations[${ti}]`
+
+      if (tr == null || typeof tr !== "object") {
+        throw new DocumentValidationError(tp, "must be a non-null object")
+      }
+
+      if (typeof tr.id !== "string") {
+        throw new DocumentValidationError(`${tp}.id`, "must be a string")
+      }
+
+      if (!Array.isArray(tr.languages)) {
+        throw new DocumentValidationError(`${tp}.languages`, "must be an array")
+      }
+
+      if (typeof tr.isSource !== "boolean") {
+        throw new DocumentValidationError(`${tp}.isSource`, "must be a boolean")
+      }
+
+      if (!Array.isArray(tr.turns)) {
+        throw new DocumentValidationError(`${tp}.turns`, "must be an array")
+      }
+    }
+  }
+}

package/src/utils/waveform.ts

@@ -0,0 +1,64 @@
+/**
+ * Normalizes raw waveform values (any scale, e.g. 16-bit ints from the
+ * audiowaveform format) to [-1, 1] floats as expected by WaveSurfer.
+ * Scales against the 98th percentile (values above it clip at 1) so a few
+ * isolated loud peaks don't flatten the rest of the waveform.
+ */
+export function normalizePeaks(data: number[]): Float32Array {
+  const peaks = new Float32Array(data.length)
+  if (data.length === 0) return peaks
+
+  const sorted = data.map(Math.abs).sort((a, b) => a - b)
+  const reference = sorted[Math.floor((sorted.length - 1) * 0.98)] ?? 0
+  if (reference === 0) return peaks
+
+  // Gamma > 1 expands the contrast: average speech stays mid-height while
+  // near-silence drops to a flat line instead of a thin permanent bar.
+  const gamma = 1.5
+  for (let i = 0; i < data.length; i++) {
+    const value = (data[i] ?? 0) / reference
+    const clipped = Math.max(-1, Math.min(1, value))
+    peaks[i] = Math.sign(clipped) * Math.abs(clipped) ** gamma
+  }
+  return peaks
+}
+
+export function renderWaveform(
+  channels: (number[] | Float32Array)[],
+  ctx: CanvasRenderingContext2D,
+): void {
+  const { width, height } = ctx.canvas
+  const channel = channels[0]!
+  const scale = channel.length / width
+  const step = 0.5
+
+  ctx.translate(0, height / 2)
+  ctx.strokeStyle = ctx.fillStyle
+  ctx.beginPath()
+
+  for (let i = 0; i < width; i += step * 2) {
+    // Average all values that fall into this pixel bucket: on long audios
+    // (several data points per pixel) point-sampling picks loud windows too
+    // often and the waveform turns into a solid mass.
+    const start = Math.floor(i * scale)
+    const end = Math.max(start + 1, Math.floor((i + step * 2) * scale))
+    let sum = 0
+    for (let j = start; j < end; j++) sum += Math.abs(channel[j] ?? 0)
+    const value = sum / (end - start)
+    let x = i
+    let y = value * (height / 2)
+
+    ctx.moveTo(x, 0)
+    ctx.lineTo(x, y)
+    ctx.lineTo(x + step, 0)
+
+    x = x + step
+    y = -y
+    ctx.moveTo(x, 0)
+    ctx.lineTo(x, y)
+    ctx.lineTo(x + step, 0)
+  }
+
+  ctx.stroke()
+  ctx.closePath()
+}

package/src/utils/wordRange.ts

@@ -0,0 +1,67 @@
+import type { Core } from "../core/types"
+import type { Turn } from "../types/editor"
+import { parseWordId } from "./turnWords"
+
+/**
+ * Locate a word in the rendered DOM as a character Range — the shared anchor
+ * for the karaoke highlight (CSS Custom Highlight API) and follow-playback
+ * scrolling. Nothing is ever inserted into the content: a Range is a
+ * read-only view over the existing text nodes.
+ */
+
+/** Resolve the active word id (`turnId#index`) into a DOM Range under `root`
+ *  (the editor DOM or any container holding the rendered turns). */
+export function activeWordRange(
+  root: ParentNode,
+  core: Core,
+  wordId: string,
+): Range | null {
+  const parsed = parseWordId(wordId)
+  if (!parsed) return null
+  const translation = core.activeChannel.value?.activeTranslation.value
+  const turn = translation?.turns.value.find((t) => t.id === parsed.turnId)
+  if (!turn) return null
+  return findWordRange(root, turn, parsed.index)
+}
+
+export function findWordRange(
+  root: ParentNode,
+  turn: Turn,
+  index: number,
+): Range | null {
+  const word = turn.words[index]
+  if (!word || word.charStart == null || word.charEnd == null) return null
+
+  const container = root.querySelector(
+    `[data-turn-id="${cssEscape(turn.id)}"] .turn-text`,
+  )
+  if (!container) return null
+
+  // Map the char offsets onto the container's text nodes. The store offsets
+  // come from tokenizing the same text PM renders, so a full walk always
+  // lands — unless an edit is mid-flight, in which case bail (null).
+  const range = document.createRange()
+  let offset = 0
+  let startSet = false
+  const walker = document.createTreeWalker(container, NodeFilter.SHOW_TEXT)
+  for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+    const len = node.nodeValue?.length ?? 0
+    if (!startSet && word.charStart < offset + len) {
+      range.setStart(node, word.charStart - offset)
+      startSet = true
+    }
+    if (word.charEnd <= offset + len) {
+      if (!startSet) return null
+      range.setEnd(node, word.charEnd - offset)
+      return range
+    }
+    offset += len
+  }
+  return null
+}
+
+function cssEscape(value: string): string {
+  return typeof CSS !== "undefined" && CSS.escape
+    ? CSS.escape(value)
+    : value.replace(/["\\]/g, "\\$&")
+}

package/src/utils/words.ts

@@ -0,0 +1,45 @@
+import type { Word } from "../types/editor"
+
+/** True if at least one word carries a timestamp. Robust to sparse timing:
+ *  freshly typed words (and split/merge products) may have no timestamp yet,
+ *  and they can sit anywhere in the list — not just at index 0. */
+export function hasWordTimestamps(words: Word[]): boolean {
+  return words.some((w) => w.startTime != null)
+}
+
+/** First defined word start in the list (skips untimed leading words). */
+export function firstWordStart(words: Word[]): number | undefined {
+  for (const w of words) if (w.startTime != null) return w.startTime
+  return undefined
+}
+
+/** Last defined word end in the list (skips untimed trailing words). */
+export function lastWordEnd(words: Word[]): number | undefined {
+  for (let i = words.length - 1; i >= 0; i--) {
+    const e = words[i]!.endTime
+    if (e != null) return e
+  }
+  return undefined
+}
+
+/**
+ * Margin in seconds around a word's [startTime, endTime] interval.
+ * Avoids highlight "holes" during inter-word micro-gaps (silences,
+ * punctuation). Beyond this margin no word is active.
+ */
+const ACTIVE_WORD_MARGIN = 1
+
+/**
+ * Returns the first word whose [startTime - margin, endTime] interval contains
+ * `time`, or null when none does. Words without timestamps are skipped (a typed
+ * word with no timing yet is never "active").
+ */
+export function findActiveWord(words: Word[], time: number): string | null {
+  for (const word of words) {
+    if (word.startTime == null || word.endTime == null) continue
+    if (word.startTime - ACTIVE_WORD_MARGIN <= time && time <= word.endTime) {
+      return word.id
+    }
+  }
+  return null
+}