@linto-ai/transcript-ui-core 0.9.23 → 0.9.24-unstable.202610151359

package/src/core/test/capabilities.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "bun:test"
+import {
+  DEFAULT_SUMMARY_CAPABILITIES,
+  computeCanChat,
+  computeSummaryCapabilities,
+} from "../capabilities"
+
+const TEXT_ONLY = { text: "edit", speakers: "edit" } as const
+
+describe("computeSummaryCapabilities", () => {
+  it("falls back on the defaults when the host sets none", () => {
+    expect(computeSummaryCapabilities(TEXT_ONLY)).toBe(
+      DEFAULT_SUMMARY_CAPABILITIES,
+    )
+  })
+
+  it("returns the host's permissions", () => {
+    const summary = { generate: true, edit: false, forceGenerate: true }
+    expect(computeSummaryCapabilities({ ...TEXT_ONLY, summary })).toBe(summary)
+  })
+})
+
+describe("computeCanChat", () => {
+  it("keeps the chat when the host sets nothing", () => {
+    expect(computeCanChat(TEXT_ONLY)).toBe(true)
+  })
+
+  it("follows the host's capability", () => {
+    expect(computeCanChat({ ...TEXT_ONLY, chat: "disabled" })).toBe(false)
+    expect(computeCanChat({ ...TEXT_ONLY, chat: "enabled" })).toBe(true)
+  })
+})

package/src/core/test/createCore.test.ts

@@ -0,0 +1,248 @@
+import { afterEach, describe, expect, it } from "bun:test"
+import { nextTick } from "vue"
+import { createCore } from "../createCore"
+
+/** Stands in for the browser's media query so the core can be built at a
+ *  chosen width and resized — there is no DOM under `bun test`. */
+function installViewport(isMobile: boolean) {
+  const listeners = new Set<(event: MediaQueryListEvent) => void>()
+  const query = {
+    matches: isMobile,
+    addEventListener(_: string, listener: (event: MediaQueryListEvent) => void) {
+      listeners.add(listener)
+    },
+    removeEventListener(
+      _: string,
+      listener: (event: MediaQueryListEvent) => void,
+    ) {
+      listeners.delete(listener)
+    },
+  }
+  Object.defineProperty(globalThis, "window", {
+    value: { matchMedia: () => query },
+    configurable: true,
+    writable: true,
+  })
+  return {
+    resizeTo(matches: boolean) {
+      query.matches = matches
+      for (const listener of [...listeners]) {
+        listener({ matches } as MediaQueryListEvent)
+      }
+    },
+    listenerCount: () => listeners.size,
+  }
+}
+
+function uninstallViewport(): void {
+  Reflect.deleteProperty(globalThis, "window")
+}
+
+afterEach(uninstallViewport)
+
+describe("createCore — sidebar drawer", () => {
+  it("opens and closes on mobile, reporting every move to the host", () => {
+    installViewport(true)
+    const core = createCore()
+    const seen: boolean[] = []
+    core.on("sidebar:open", ({ open }) => seen.push(open))
+
+    expect(core.sidebarOpen.value).toBe(false)
+
+    core.setSidebarOpen(true)
+    expect(core.sidebarOpen.value).toBe(true)
+
+    core.setSidebarOpen(false)
+    expect(core.sidebarOpen.value).toBe(false)
+
+    expect(seen).toEqual([true, false])
+  })
+
+  it("stays silent when the state does not actually change", () => {
+    installViewport(true)
+    const core = createCore()
+    let events = 0
+    core.on("sidebar:open", () => events++)
+
+    core.setSidebarOpen(false)
+    core.setSidebarOpen(true)
+    core.setSidebarOpen(true)
+
+    expect(events).toBe(1)
+  })
+
+  it("refuses to open above the breakpoint, and keeps no armed state", () => {
+    const viewport = installViewport(false)
+    const core = createCore()
+    let events = 0
+    core.on("sidebar:open", () => events++)
+
+    core.setSidebarOpen(true)
+    expect(core.sidebarOpen.value).toBe(false)
+    expect(events).toBe(0)
+
+    // The drawer appears at phone width — closed, not sprung open by the
+    // call made while it did not exist.
+    viewport.resizeTo(true)
+    expect(core.sidebarOpen.value).toBe(false)
+    expect(events).toBe(0)
+  })
+
+  it("closes itself when the viewport leaves phone width", () => {
+    const viewport = installViewport(true)
+    const core = createCore()
+    const seen: boolean[] = []
+    core.on("sidebar:open", ({ open }) => seen.push(open))
+
+    core.setSidebarOpen(true)
+    viewport.resizeTo(false)
+
+    expect(core.sidebarOpen.value).toBe(false)
+    expect(seen).toEqual([true, false])
+  })
+})
+
+describe("createCore — viewport", () => {
+  it("reports every crossing of the breakpoint to the host", () => {
+    const viewport = installViewport(false)
+    const core = createCore()
+    const seen: boolean[] = []
+    core.on("viewport:change", ({ isMobile }) => seen.push(isMobile))
+
+    expect(core.isMobile.value).toBe(false)
+
+    viewport.resizeTo(true)
+    expect(core.isMobile.value).toBe(true)
+
+    viewport.resizeTo(false)
+    expect(core.isMobile.value).toBe(false)
+
+    expect(seen).toEqual([true, false])
+  })
+
+  it("releases its listener on destroy", () => {
+    const viewport = installViewport(true)
+    const core = createCore()
+    expect(viewport.listenerCount()).toBe(1)
+
+    core.destroy()
+    expect(viewport.listenerCount()).toBe(0)
+  })
+
+  it("builds and tears down without a DOM to watch", () => {
+    uninstallViewport()
+    const core = createCore()
+
+    expect(core.isMobile.value).toBe(false)
+    expect(() => core.destroy()).not.toThrow()
+  })
+})
+
+describe("createCore — transcript font size", () => {
+  it("starts at the default and announces every change", async () => {
+    const core = createCore()
+    const seen: number[] = []
+    core.on("transcript:fontSize", ({ fontSize }) => seen.push(fontSize))
+
+    expect(core.transcriptFontSize.value).toBe(18)
+
+    core.transcriptFontSize.value = 24
+    await nextTick()
+    core.transcriptFontSize.value = 14
+    await nextTick()
+
+    expect(seen).toEqual([24, 14])
+  })
+
+  it("stops announcing once destroyed", async () => {
+    const core = createCore()
+    let events = 0
+    core.on("transcript:fontSize", () => events++)
+
+    core.destroy()
+    core.transcriptFontSize.value = 24
+    await nextTick()
+
+    expect(events).toBe(0)
+  })
+})
+
+describe("createCore — theme", () => {
+  it("starts light and announces every switch", async () => {
+    const core = createCore()
+    const seen: string[] = []
+    core.on("theme:change", ({ theme }) => seen.push(theme))
+
+    expect(core.theme.value).toBe("light")
+
+    core.theme.value = "dark"
+    await nextTick()
+    core.theme.value = "light"
+    await nextTick()
+
+    expect(seen).toEqual(["dark", "light"])
+  })
+
+  it("stops announcing once destroyed", async () => {
+    const core = createCore()
+    let events = 0
+    core.on("theme:change", () => events++)
+
+    core.destroy()
+    core.theme.value = "dark"
+    await nextTick()
+
+    expect(events).toBe(0)
+  })
+})
+
+describe("createCore — active track", () => {
+  function track(id: string, isSource: boolean) {
+    return { id, languages: ["fr"], isSource, turns: [] }
+  }
+
+  function createDocumentCore() {
+    installViewport(false)
+    const core = createCore()
+    core.setDocument({
+      title: "",
+      speakers: new Map(),
+      channels: [
+        {
+          id: "ch-1",
+          name: "",
+          duration: 0,
+          translations: [track("src-1", true), track("en-1", false)],
+        },
+        {
+          id: "ch-2",
+          name: "",
+          duration: 0,
+          translations: [track("src-2", true), track("en-2", false)],
+        },
+      ],
+    })
+    const seen: Array<{ channelId: string; translationId: string }> = []
+    core.on("activeTrack:change", (payload) => seen.push(payload))
+    return { core, seen }
+  }
+
+  it("announces a track change of the active channel", () => {
+    const { core, seen } = createDocumentCore()
+    core.channels.get("ch-1")!.setActiveTranslation("en-1")
+    expect(seen).toEqual([{ channelId: "ch-1", translationId: "en-1" }])
+  })
+
+  it("announces a channel change with the track that channel was on", () => {
+    const { core, seen } = createDocumentCore()
+    core.channels.get("ch-2")!.setActiveTranslation("en-2")
+    core.setActiveChannel("ch-2")
+    expect(seen).toEqual([{ channelId: "ch-2", translationId: "en-2" }])
+  })
+
+  it("stays silent for a track change of another channel", () => {
+    const { core, seen } = createDocumentCore()
+    core.channels.get("ch-2")!.setActiveTranslation("en-2")
+    expect(seen).toEqual([])
+  })
+})

package/src/core/types.ts

@@ -11,18 +11,44 @@ import type {
 
 // ── Capabilities ────────────────────────────────────────────────────────
 
+/** What the reader may do with the reports (llm-services plugin). Separate
+ *  permissions rather than levels: a host can offer forcing a generation
+ *  without editing (e.g. a phone app). */
+export interface SummaryCapabilities {
+  /** Generate a report that is missing or out of date. */
+  generate: boolean
+  /** Edit and save a report by hand. */
+  edit: boolean
+  /** Generate again a report that is already up to date. */
+  forceGenerate: boolean
+}
+
 export interface CoreCapabilities {
   text: "edit" | "view"
   speakers: "edit" | "view"
+  /** Left unset: DEFAULT_SUMMARY_CAPABILITIES. */
+  summary?: SummaryCapabilities
+  /** Whether the reader may chat, once a chat plugin is installed. Left
+   *  unset: "enabled". */
+  chat?: "enabled" | "disabled"
 }
 
 // ── Event Map ──────────────────────────────────────────────────────────
 
+/** Light is the default; dark redefines the colour tokens on the editor's
+ *  root, under the same data-theme convention the host app uses. */
+export type EditorTheme = "light" | "dark"
+
 export interface CoreEventMap {
   /** A new document was loaded via setDocument (channels rebuilt). */
   "document:change": void
   "channel:change": { channelId: string }
-  "translation:change": { translationId: string | null }
+  "translation:change": { channelId: string; translationId: string | null }
+  /** The displayed track changed: another channel, or another track of the
+   *  active channel. Follows channel:change / translation:change, so a
+   *  consumer of "what is on screen" listens to this one alone. Not emitted
+   *  by setDocument: read core.activeChannel once the document is set. */
+  "activeTrack:change": { channelId: string; translationId: string }
   "turn:add": { turn: Turn; translationId: string }
   "turn:update": { turn: Turn; translationId: string }
   "turn:remove": { turnId: string; translationId: string }
@@ -30,9 +56,9 @@ export interface CoreEventMap {
   "speaker:add": { speaker: Speaker }
   "speaker:remove": { speakerId: string }
   "scroll:top": { translationId: string }
-  /** A seek was requested through core.audio.seekTo (widget scrub or
-   *  click-to-read) — the explicit "take me to this instant" gesture that
-   *  should resume follow-playback scrolling. */
+  /** An explicit "take me to this instant" gesture that should resume
+   *  follow-playback scrolling: core.audio.seekTo (click-to-read) or a
+   *  click/drag on the player's waveform. */
   "audio:seek": { time: number }
   "translation:sync": { translationId: string }
   "channel:sync": { channelId: string }
@@ -40,6 +66,25 @@ export interface CoreEventMap {
   "watermark:display": { display: boolean }
   "watermark:pin": { pinned: boolean }
   "subtitle:visible": { visible: boolean; height: number }
+  /** The reading size of the transcript changed. The editor does not
+   *  remember it — a host that wants the preference to survive a reload
+   *  listens here and restores it into core.transcriptFontSize. */
+  "transcript:fontSize": { fontSize: number }
+  /** The editor switched theme. The editor applies it to itself; a host
+   *  that wants its own chrome to follow listens here (studio-frontend
+   *  sets html[data-theme] from it). */
+  "theme:change": { theme: EditorTheme }
+  /** The sidebar drawer was opened or closed — by the built-in header,
+   *  by the drawer's own close button, by a channel change, or by the
+   *  host calling setSidebarOpen. A host rendering its own header (see
+   *  TranscriptUI's no-header) listens to this to keep its button in
+   *  sync, since it is not the only thing that moves the drawer. */
+  "sidebar:open": { open: boolean }
+  /** The viewport crossed the phone-width breakpoint. Same information as
+   *  core.isMobile, pushed: a host that can't subscribe to a Vue 3 ref (a
+   *  Vue 2 app, or plain JS around the web component) follows this to show
+   *  or hide its own sidebar button. */
+  "viewport:change": { isMobile: boolean }
   "llmService:regenerate": { id: string }
   "llmService:export": { id: string }
   "llmService:active": { id: string | null }
@@ -53,6 +98,8 @@ export interface CoreEventMap {
   "chat:deleteSession": { sessionId: string }
   "chat:renameSession": { sessionId: string; title: string }
   "chat:send": { content: string }
+  /** The action button of an error message (see ChatMessageError) was clicked. */
+  "chat:errorAction": { messageId: string; actionId: string }
   destroy: void
 }
 
@@ -81,9 +128,13 @@ export interface ReadableTranslation extends TranslationInfo {
 export interface TurnStore {
   readonly id: string
   readonly turns: Readonly<Ref<Turn[]>>
-  /** Epoch ms — last time the transcription was modified (host-pushed). */
+  /** Epoch ms of the last server-side modification of this track (host- or
+   *  broadcast-pushed). */
   readonly lastModifiedAt: Ref<number | null>
-  setLastModifiedAt(ts: number | null): void
+  /** Move lastModifiedAt forward only: null, non-finite, or older-or-equal
+   *  timestamps are ignored (server reads and broadcasts can arrive out of
+   *  order; a modification never makes the transcription older). */
+  advanceLastModifiedAt(ts: number | null): void
   addTurn(turn: Turn): void
   prependTurns(turns: Turn[]): void
   updateTurn(turnId: string, patch: Partial<Turn>): void
@@ -217,6 +268,8 @@ export interface TurnUpdate {
   etime?: number
   /** Per-translation edit version — carried, not consumed yet (resync lot). */
   version?: number
+  /** Server last_update of the track after this mutation. */
+  lastUpdate?: string
 }
 
 /** A full turn as carried by structural broadcasts (turn_split, turns_merged). */
@@ -237,6 +290,8 @@ export interface TurnSplit {
   /** The two halves, in order — the left one keeps the original turn id. */
   turns: WireTurn[]
   version?: number
+  /** Server last_update of the track after this mutation. */
+  lastUpdate?: string
 }
 
 /** Two adjacent turns merged, as broadcast by the server (editor:turns_merged). */
@@ -247,6 +302,8 @@ export interface TurnsMerged {
   removedTurnId: string
   turn: WireTurn
   version?: number
+  /** Server last_update of the track after this mutation. */
+  lastUpdate?: string
 }
 
 /** A turn removed (the client committed an emptied text), as broadcast by
@@ -256,6 +313,8 @@ export interface TurnDeleted {
   turnId: string
   removedSpeakerId?: string
   version?: number
+  /** Server last_update of the track after this mutation. */
+  lastUpdate?: string
 }
 
 /** A turn pointed at a (possibly freshly created) speaker, as broadcast by
@@ -267,6 +326,8 @@ export interface TurnSpeakerUpdated {
   speaker: { id: string; name: string }
   removedSpeakerId?: string
   version?: number
+  /** Server last_update of the track after this mutation. */
+  lastUpdate?: string
   /** @see SpeakerRenamed.revisionId */
   revisionId?: string | null
   /** @see SpeakerRenamed.redoRevisionId */
@@ -278,6 +339,8 @@ export interface SpeakerRenamed {
   speakerId: string
   name: string
   version?: number
+  /** Server last_update of the track after this mutation. */
+  lastUpdate?: string
   /** The undo cursor AFTER this broadcast (see onUndo/onRedo server-side) —
    *  a plain rename and an undo/redo replaying one are indistinguishable on
    *  the wire, and don't need to be: both just mean "the cursor is here
@@ -299,6 +362,8 @@ export interface SpeakerReplaced {
   fromSpeakerId: string
   toSpeakerId: string
   version?: number
+  /** Server last_update of the track after this mutation. */
+  lastUpdate?: string
   /** @see SpeakerRenamed.revisionId */
   revisionId?: string | null
   /** @see SpeakerRenamed.redoRevisionId */
@@ -316,6 +381,8 @@ export interface SpeakerRestored {
   toSpeakerId: string
   turnIds: string[]
   version?: number
+  /** Server last_update of the track after this mutation. */
+  lastUpdate?: string
   /** @see SpeakerRenamed.revisionId */
   revisionId?: string | null
   /** @see SpeakerRenamed.redoRevisionId */
@@ -422,7 +489,11 @@ export interface SubtitlePluginApi {
 
 // ── LLM Services Plugin API ─────────────────────────────────────────────
 
+/** "loading": the host is fetching the state of the report (opening, or the
+ *  followed track changed). Nothing to show yet, and no action either: the
+ *  report may well exist. */
 export type LLMServiceStatus =
+  | "loading"
   | "idle"
   | "queued"
   | "processing"
@@ -552,6 +623,20 @@ export interface LiveTranslationEventData {
 
 export interface LivePluginApi {
   partial: ShallowRef<string | null>
+  /** Whether the provisional text of the turn being spoken reaches the
+   *  screen at all — it feeds both the transcription panel and the live
+   *  subtitles, so turning it off silences the two of them. */
+  partialsVisible: Ref<boolean>
+  showPartials(): void
+  hidePartials(): void
+  /** True while partials keep arriving — the only sign anyone is talking,
+   *  and the one the UI falls back on once the text itself is hidden. Stays
+   *  on for silenceDelay after the last partial. */
+  isSpeechActive: Ref<boolean>
+  /** Milliseconds without a partial before speech counts as over. ASRs
+   *  differ in how often they emit — one per word, or one every few
+   *  seconds — so a host tunes this to its backend. */
+  silenceDelay: Ref<number>
   hasLiveUpdate: Ref<boolean>
   ttsAvailable: boolean
   ttsEnabled: Ref<boolean>
@@ -577,6 +662,17 @@ export interface ChatMessage {
   tokenCount?: number
   /** True only for the virtual in-flight assistant message during streaming. */
   streaming?: boolean
+  /** Set on an assistant message that reports a failure instead of a reply:
+   *  rendered as an error card, its content is ignored. */
+  error?: ChatMessageError
+}
+
+/** A failure reported in the thread. The host writes the texts (already
+ *  translated) and owns the action: clicking it emits "chat:errorAction". */
+export interface ChatMessageError {
+  title: string
+  description?: string
+  action?: { id: string; label: string; icon?: string }
 }
 
 export interface ChatSession {
@@ -639,6 +735,35 @@ export interface Core {
   readonly channels: Map<string, ChannelStore>
   readonly activeChannel: ComputedRef<ChannelStore | undefined>
 
+  /** Reading size of the transcript text, in pixels. Chrome (buttons,
+   *  headers, the sidebar) keeps its own scale. Writable: there is nothing to
+   *  guard, and a change is announced by "transcript:fontSize". */
+  readonly transcriptFontSize: Ref<number>
+  /** Colour theme of the editor. Writable: a host can restore a stored
+   *  preference, and a change is announced by "theme:change". */
+  readonly theme: Ref<EditorTheme>
+  /** Brand colour, pushed by the host so the editor's accents match the app
+   *  around it. Null keeps the editor's own. Applied as an inline style on
+   *  the editor's root, which is the only thing that outranks the token
+   *  declarations inside the shadow tree. */
+  readonly primaryColor: Ref<string | null>
+
+  // ── Layout chrome ────────────────────────────────────────────────────
+  /** True while the viewport is at phone width — below the breakpoint where
+   *  Layout swaps the permanent sidebar for the drawer. Read it instead of
+   *  duplicating the media query: a host rendering its own header needs the
+   *  exact same threshold to know when its sidebar button is worth showing. */
+  readonly isMobile: Readonly<Ref<boolean>>
+  /** Whether the sidebar drawer is open. Only the mobile, single-panel
+   *  layout mounts that drawer — on desktop the sidebar is permanent and in
+   *  split view there is none. */
+  readonly sidebarOpen: Readonly<Ref<boolean>>
+  /** Opens or closes that drawer. Opening is refused, silently and without
+   *  an event, while the viewport is wider than the breakpoint: there is no
+   *  drawer to open, and a stored "open" would spring it on the next resize.
+   *  Closing always applies. */
+  setSidebarOpen(open: boolean): void
+
   // ── Navigation ───────────────────────────────────────────────────────
   setDocument(doc: EditorDocument): void
   setActiveChannel(channelId: string): void

package/src/index.ts

@@ -4,6 +4,9 @@ export {
   provideCore,
   useCore,
   CROSS_TRANSLATION_ID,
+  DEFAULT_SUMMARY_CAPABILITIES,
+  computeSummaryCapabilities,
+  computeCanChat,
 } from './core'
 export type {
   Core,
@@ -11,6 +14,7 @@ export type {
   CoreEventMap,
   CoreOptions,
   CoreCapabilities,
+  SummaryCapabilities,
   UISlot,
   TurnEventKey,
   ReadableTranslation,
@@ -47,6 +51,7 @@ export type {
   LLMServicesPluginApi,
   ChatRole,
   ChatMessage,
+  ChatMessageError,
   ChatSession,
   ChatPluginApi,
 } from './core'
@@ -67,7 +72,10 @@ export { default as SpeakerPopover } from './components/molecules/SpeakerPopover
 export { useEditorReady } from './composables/useEditorReady'
 
 // Phone breakpoint shared with plugins, so their panels switch layout at the
-// same width as the core Layout.
+// same width as the core Layout. Reads core.isMobile, so it only works under
+// a provideCore() — inside <TranscriptUI>, in other words. A host rendering
+// its own chrome around the editor reads core.isMobile (or follows the
+// "viewport:change" event) instead of calling this.
 export { useIsMobile } from './composables/useIsMobile'
 
 // Adapter API LinTO