@lincyaw/addon-lecture 0.0.0-stage → 1.0.0-rc.2

package/src/client/source.ts

@@ -0,0 +1,109 @@
+import { siteBase } from '@lincyaw/host'
+import type { ServerClient } from '@lincyaw/host'
+import { ABSOLUTE_URL, isRecord } from '@lincyaw/kernel'
+import type { ProductionBinding, ProductionPlan, ProductionPlanQuery } from '@lincyaw/kernel'
+import { LECTURE_ID, parseTrack } from '../domain/index.ts'
+import type { LectureTrack, Voice } from '../domain/index.ts'
+
+export interface LectureSummary {
+  id: string
+  lang?: string
+  voice?: Voice
+  duration?: number
+}
+
+export interface LectureSource {
+  list(): Promise<LectureSummary[]>
+  track(id: string, planId?: string, signal?: AbortSignal): Promise<LectureTrack | undefined>
+  media(id: string, src: string): Promise<string>
+  plan?(query: ProductionPlanQuery, signal?: AbortSignal): Promise<ProductionPlan>
+  productionMedia?(binding: ProductionBinding, clipId: string, signal?: AbortSignal): Promise<string>
+}
+
+function summaries(value: unknown): LectureSummary[] {
+  return Array.isArray(value) ? value.filter((v): v is LectureSummary => isRecord(v) && typeof v.id === 'string') : []
+}
+
+/** Why the server refused: its `{ error }`, or the text it answered (a proxy's), else the status. */
+async function refusal(response: Response): Promise<string> {
+  const text = (await response.text().catch(() => '')).trim()
+  let body: unknown
+  try {
+    body = JSON.parse(text)
+  } catch {}
+  if (isRecord(body) && typeof body.error === 'string') return body.error
+  return text && !text.startsWith('<') ? `HTTP ${response.status}: ${text.slice(0, 300)}` : `HTTP ${response.status}`
+}
+
+async function readTrackAnswer(response: Response): Promise<LectureTrack | undefined> {
+  if (response.status === 404) return undefined
+  if (!response.ok) throw new Error(await refusal(response))
+  const { track, problems } = parseTrack(await response.json())
+  if (!track) throw new Error(problems.join('; '))
+  return track
+}
+
+export function serverSource(server: ServerClient): LectureSource {
+  return {
+    list: async () => summaries(await (await server.fetch(LECTURE_ID, 'tracks')).json()),
+    track: async (id, planId, signal) => readTrackAnswer(await server.fetch(LECTURE_ID, `tracks/${encodeURIComponent(id)}${planId ? `?planId=${encodeURIComponent(planId)}` : ''}`, { signal })),
+    plan: (query, signal) => readAnswer<ProductionPlan>(server.fetch(LECTURE_ID, `production-plan?source=${encodeURIComponent(JSON.stringify(query.source))}&irRevision=${encodeURIComponent(query.irRevision)}`, { signal })),
+    async productionMedia(binding, clipId, signal) {
+      const query = `source=${encodeURIComponent(JSON.stringify(binding.source))}&irRevision=${encodeURIComponent(binding.irRevision)}&planId=${encodeURIComponent(binding.planId)}&clipId=${encodeURIComponent(clipId)}`
+      const response = await server.fetch(LECTURE_ID, `production-media?${query}`, { signal })
+      if (!response.ok) throw new Error(await refusal(response))
+      return URL.createObjectURL(await response.blob())
+    },
+    async media(id, src) {
+      if (ABSOLUTE_URL.test(src)) return src
+      const response = await server.fetch(LECTURE_ID, `tracks/${encodeURIComponent(id)}/${src.split('/').map(encodeURIComponent).join('/')}`)
+      if (!response.ok) throw new Error(`${src}: HTTP ${response.status}`)
+      return URL.createObjectURL(await response.blob())
+    },
+  }
+}
+
+export async function readAnswer<T = unknown>(response: Promise<Response>): Promise<T> {
+  const r = await response
+  const body: unknown = await r.json().catch(() => ({}))
+  if (!r.ok) throw new Error(isRecord(body) && typeof body.error === 'string' ? body.error : `HTTP ${r.status}`)
+  return body as T
+}
+
+/** The lectures published at the first of `bases` that has an index (the last when none answers). */
+export function staticSource(bases: readonly string[]): LectureSource {
+  let located: Promise<string> | undefined
+  const base = () => located ??= (async () => {
+    for (const candidate of bases.slice(0, -1)) {
+      const response = await fetch(new URL('index.json', candidate), { method: 'HEAD' }).catch(() => undefined)
+      if (response?.ok) return candidate
+    }
+    return bases.at(-1)!
+  })()
+  return {
+    list: async () => {
+      const response = await fetch(new URL('index.json', await base()))
+      return response.ok ? summaries(await response.json()) : []
+    },
+    track: async (id, _planId, signal) => readTrackAnswer(await fetch(new URL(`${encodeURIComponent(id)}/track.json`, await base()), { cache: 'no-cache', signal })),
+    media: async (id, src) => (ABSOLUTE_URL.test(src) ? src : new URL(`${encodeURIComponent(id)}/${src.split('/').map(encodeURIComponent).join('/')}`, await base()).href),
+  }
+}
+
+/**
+ * Where a static page looks for its lectures: `presmium.lecture.url` when the document names it; otherwise `lecture/` under
+ * the page, where a site of several documents puts each one's lectures in its own directory, then `../lecture/` beside
+ * the web form, where a document's own build puts them.
+ */
+export function staticBases(config: Record<string, unknown> | undefined): string[] {
+  const site = new URL(siteBase(), location.href)
+  const configured = typeof config?.url === 'string' && config.url ? config.url : undefined
+  return (configured ? [configured] : ['lecture/', '../lecture/']).map((base) => {
+    const url = new URL(base, site).href
+    return url.endsWith('/') ? url : `${url}/`
+  })
+}
+
+export function lectureSource(server: ServerClient, config: unknown): LectureSource {
+  return server.available ? serverSource(server) : staticSource(staticBases(isRecord(config) ? config : undefined))
+}

package/src/client/state.ts

@@ -0,0 +1,45 @@
+import { createStore, serverClient, useServer, useStore } from '@lincyaw/host'
+import type { Viewer, ViewerPluginContext } from '@lincyaw/viewer'
+import { useEffect } from 'react'
+import type { LecturePlayer } from './player.ts'
+import { serverSource } from './source.ts'
+
+let context: Pick<ViewerPluginContext, 'useViewer'> | undefined
+export function setViewerContext(ctx: Pick<ViewerPluginContext, 'useViewer'>): void { context = ctx }
+export function useViewer(): Viewer {
+  if (!context) throw new Error('[presmium] the lecture viewer plugin is not installed')
+  return context.useViewer()
+}
+const compiled = createStore(false)
+export const lecturesAvailable = createStore(false)
+export function readLecturesFlag(config: Record<string, unknown>): void {
+  compiled.set(config.lectures === true)
+  if (!serverClient().available) lecturesAvailable.set(compiled.getSnapshot())
+}
+export async function refreshLectures(): Promise<void> {
+  const server = serverClient()
+  if (!server.available) { lecturesAvailable.set(compiled.getSnapshot()); return }
+  lecturesAvailable.set((await serverSource(server).list().catch(() => [])).length > 0)
+}
+export function watchLectureList(): void { void refreshLectures() }
+export function useLecturesAvailable(): boolean {
+  const server = useServer()
+  useEffect(() => { void refreshLectures() }, [server.available])
+  return useStore(lecturesAvailable)
+}
+const PARAM = 'track'
+function fromUrl(): string | undefined { return typeof location === 'undefined' ? undefined : new URLSearchParams(location.search).get(PARAM) ?? undefined }
+export const playing = createStore<string | undefined>(fromUrl())
+export const exporting = typeof location !== 'undefined' && new URLSearchParams(location.search).has('export')
+/** `&autoplay`: a page that embeds the presentation asks for the lecture to start as soon as it is ready. */
+export const autoplay = typeof location !== 'undefined' && new URLSearchParams(location.search).has('autoplay')
+export const burnedCaptions = exporting ? new URLSearchParams(location.search).get('captions') ?? undefined : undefined
+export function play(id: string | undefined): void {
+  playing.set(id)
+  const url = new URL(location.href)
+  if (id) url.searchParams.set(PARAM, id)
+  else url.searchParams.delete(PARAM)
+  history.replaceState(history.state, '', url.pathname + url.search + url.hash)
+}
+/** The player a presentation shows, which Space plays and pauses; none while Video Production drives the player. */
+export const keyboardPlayer = createStore<LecturePlayer | undefined>(undefined)

package/src/client/viewer.ts

@@ -0,0 +1,37 @@
+import type { ViewerPlugin } from '@lincyaw/viewer'
+import { currentLocale } from '@lincyaw/host'
+import { LECTURE_MESSAGES } from '../domain/index.ts'
+import LectureView from './LectureView.tsx'
+import PlayerPanel from './PlayerPanel.tsx'
+import PlayLectureButton from './PlayLectureButton.tsx'
+import RecorderPanel from './RecorderPanel.tsx'
+import { exporting, keyboardPlayer, setViewerContext, watchLectureList } from './state.ts'
+
+const plugin: ViewerPlugin = (ctx) => {
+  setViewerContext(ctx)
+  watchLectureList()
+  if (exporting) document.documentElement.classList.add('pm-lecture-exporting')
+  ctx.registerView({
+    id: 'lecture',
+    get label() {
+      return LECTURE_MESSAGES[currentLocale()].view
+    },
+    kind: 'overlay',
+    component: LectureView,
+    // Kept for lecture links and choosing a recorded track; playback is part of the presentation's controls.
+    hidden: true,
+  })
+  ctx.registerLayer({ id: 'presmium.lecture.player', component: PlayerPanel, views: ['present'], scope: exporting ? 'view' : 'bar' })
+  // Space plays and pauses the lecture; without a player it is left to the next step.
+  ctx.registerAction({ id: 'presmium.lecture.play', keys: [' '], views: ['present'], run: (_viewer, event) => {
+    const player = keyboardPlayer.getSnapshot()
+    if (!player) return false
+    if (event?.repeat) return true
+    if (player.playing) player.pause()
+    else void player.play()
+  } })
+  ctx.registerLayer({ id: 'presmium.lecture.play', component: PlayLectureButton, views: ['present'], scope: 'bar' })
+  ctx.registerLayer({ id: 'presmium.lecture.recorder', component: RecorderPanel, views: ['present'], scope: 'view' })
+}
+
+export default plugin

package/src/domain/audience.ts

@@ -0,0 +1,108 @@
+import type { IRDocument, TrackEvent } from '@lincyaw/kernel'
+import { blockDrift, blockOf, irHash, sectionHashes } from './drift.ts'
+import { anchorOf, timedEvents } from './timing.ts'
+import type { LectureTrack, MediaSegment, Utterance } from './track.ts'
+
+function positionsOf(track: LectureTrack): { sectionAt(t: number): string | undefined, stepAt(t: number): number } {
+  const moves = timedEvents(track).filter(event => event.type === 'go' && typeof event.data.section === 'string')
+  const at = (t: number) => moves.filter(move => move.t <= t).at(-1)?.data
+  return {
+    sectionAt(t) {
+      const section = at(t)?.section
+      return typeof section === 'string' ? section : undefined
+    },
+    stepAt: t => Number(at(t)?.step ?? 0),
+  }
+}
+
+export function trimToDeck(track: LectureTrack, doc: IRDocument): LectureTrack | undefined {
+  const sections = new Set(doc.sections.map(section => section.id))
+  const drift = blockDrift(track, doc)
+  const keptStep = (section: string | undefined, step: number) => (section === undefined || sections.has(section) ? step : undefined)
+  const keepsBlock = (key: string) => sections.has(key.slice(0, key.lastIndexOf('/'))) || Boolean(drift.get(key)?.to)
+  const { sectionAt, stepAt } = positionsOf(track)
+
+  let changed = false
+  const tainted = new Set<string>()
+  const dropped = new Set<string>()
+  const utterances: Utterance[] = []
+  for (const u of track.utterances) {
+    const section = u.section ?? sectionAt(u.t)
+    const step = keptStep(section, u.step ?? stepAt(u.t))
+    if (step === undefined) {
+      dropped.add(u.id)
+      if (section) tainted.add(section)
+      continue
+    }
+    if (u.step !== undefined && step !== u.step) changed = true
+    utterances.push(u.step === undefined || step === u.step ? u : { ...u, step })
+  }
+  const events: TrackEvent[] = []
+  for (const [t, type, data] of track.events) {
+    const where = sectionAt(t)
+    if (type === 'go') {
+      const section = typeof data.section === 'string' ? data.section : undefined
+      const step = keptStep(section, Number(data.step ?? 0))
+      if (step !== undefined) {
+        if (data.step !== undefined && step !== data.step) changed = true
+        events.push([t, type, data.step === undefined || step === data.step ? data : { ...data, step }])
+        continue
+      }
+      for (const name of [section, where]) if (name) tainted.add(name)
+      continue
+    }
+    const block = blockOf(data)
+    const anchor = anchorOf(data)
+    const placed = keptStep(where, stepAt(t)) !== undefined
+    const kept = block ? keepsBlock(block) : placed
+    if (kept && !(anchor && dropped.has(anchor[0]))) {
+      events.push([t, type, data])
+      continue
+    }
+    for (const name of [block?.slice(0, block.lastIndexOf('/')), where]) if (name) tainted.add(name)
+  }
+  if (utterances.length === 0 && events.length === 0) return undefined
+  const media = <T extends MediaSegment>(segments: T[] | undefined) => segments?.filter(segment => sections.has(segment.section) && !tainted.has(segment.section))
+  const audio = media(track.audio)
+  const video = media(track.video)
+  const captionOverrides = track.captionOverrides?.filter(own => sections.has(own.section) && !tainted.has(own.section))
+  const irSections = track.ir.sections && Object.fromEntries(Object.entries(track.ir.sections).filter(([id]) => sections.has(id)))
+  const blocks = Object.fromEntries(Object.entries(track.blocks).filter(([key]) => keepsBlock(key)))
+  const same = !changed && utterances.length === track.utterances.length && events.length === track.events.length
+    && audio?.length === track.audio?.length && video?.length === track.video?.length
+    && captionOverrides?.length === track.captionOverrides?.length
+    && Object.keys(irSections ?? {}).length === Object.keys(track.ir.sections ?? {}).length && Object.keys(blocks).length === Object.keys(track.blocks).length
+  if (same) return track
+  return {
+    ...track,
+    ir: { ...track.ir, ...irSections ? { sections: irSections } : {} },
+    ...audio ? { audio } : {},
+    ...video ? { video } : {},
+    blocks,
+    ...captionOverrides ? { captionOverrides } : {},
+    utterances,
+    events,
+  }
+}
+
+export function dropChangedSections(track: LectureTrack, view: IRDocument): LectureTrack | undefined {
+  const now = sectionHashes(view)
+  const recorded = track.ir.sections
+  const whole = recorded === undefined && track.ir.hash === irHash(view)
+  const same = (section: string | undefined) => section !== undefined && (whole || (recorded?.[section] !== undefined && recorded[section] === now[section]))
+  const { sectionAt } = positionsOf(track)
+  const utterances = track.utterances.filter(u => same(u.section ?? sectionAt(u.t)))
+  const said = new Set(utterances.map(u => u.id))
+  const events = track.events.filter(([t, type, data]) => {
+    if (type === 'go') return true
+    const anchor = anchorOf(data)
+    return same(sectionAt(t)) && !(anchor && !said.has(anchor[0]))
+  })
+  const media = <T extends MediaSegment>(segments: T[] | undefined) => segments?.filter(segment => same(segment.section))
+  const audio = media(track.audio)
+  const video = media(track.video)
+  const captionOverrides = track.captionOverrides?.filter(own => same(own.section))
+  if (utterances.length === track.utterances.length && events.length === track.events.length && audio?.length === track.audio?.length && video?.length === track.video?.length && captionOverrides?.length === track.captionOverrides?.length) return track
+  if (utterances.length === 0 && !audio?.length && !video?.length) return undefined
+  return { ...track, ...audio ? { audio } : {}, ...video ? { video } : {}, ...captionOverrides ? { captionOverrides } : {}, utterances, events }
+}

package/src/domain/caption-timing.ts

@@ -0,0 +1,59 @@
+import { captionTimingProblem, deckLocale, fnv1a64 } from '@lincyaw/kernel'
+import type { CaptionTimingSource, IRDocument, ProductionDiagnostic, ProductionPage } from '@lincyaw/kernel'
+import type { LectureTrack } from './track.ts'
+
+const STALE = {
+  'zh-CN': '手动字幕时间与当前讲稿、音频或步骤时间不符。请重新核对。',
+  'en': 'Manual caption times no longer match this script, audio, or step timing. Review them before using them again.',
+}
+
+/** Actual per-step playback evidence. All positions are relative; no source version or mutable plan ID enters this basis. */
+export function captionTimingSources(doc: IRDocument, track: LectureTrack, pages: readonly ProductionPage[]): Map<string, CaptionTimingSource> {
+  const sources = new Map<string, CaptionTimingSource>()
+  for (const page of pages) for (const step of page.steps) {
+    const section = doc.sections.find(section => section.id === page.sectionId), narrationIds = section?.stepNarrations?.[step.stepId]?.map(item => item.id) ?? []
+    const sourceFingerprint = section?.captionSources?.[step.stepId] ?? ''
+    const fail = (reason: string) => { sources.set(step.stepId, { available: false, reason, sourceFingerprint, narrationIds }) }
+    if (!sourceFingerprint || !narrationIds.length) { fail('caption-script-unavailable'); continue }
+    if (step.timing !== 'confirmed' || step.startMs === undefined || step.endMs === undefined || step.endMs <= step.startMs) { fail('caption-duration-unconfirmed'); continue }
+    const start = step.startMs, durationMs = Math.round(step.endMs - start), until = step.endMs
+    const utterances = track.utterances.filter(u => u.section === section?.id && u.step === step.index)
+    if (!utterances.length || utterances.some(u => u.unsaid || u.t < start || u.t + u.d > until)
+      || track.utterances.some(u => u.t < start && u.t + u.d > start || u.t < until && u.t + u.d > until)) { fail('caption-cross-step-unsupported'); continue }
+    const recordings = (track.audio ?? []).filter(a => a.role === 'recording' && a.stepId === step.stepId)
+    if (utterances.some(u => !u.recording && (!u.audioSha256 || !u.clip)) || recordings.some(a => !a.sha256) || !recordings.length && !utterances.some(u => u.audioSha256)) { fail('caption-audio-unavailable'); continue }
+    const idMap = new Map(utterances.map((u, index) => [u.id, index]))
+    const events = track.events.filter(([at, type]) => at >= start && at < until && type !== 'go').map(([at, type, data]) => {
+      const { at: anchor, ...rest } = data
+      return [Math.round(at - start), type, rest, Array.isArray(anchor) ? [idMap.get(String(anchor[0])) ?? 'foreign', anchor[1]] : null]
+    })
+    const playbackFingerprint = fnv1a64(JSON.stringify({ durationMs, events,
+      utterances: utterances.map(u => ({ t: Math.round(u.t - start), d: u.d, sha256: u.audioSha256, voice: u.voice, narrationIds: u.narrationIds, recording: u.recording })),
+      recordings: recordings.map(a => ({ t: Math.round(a.start * 1000 - start), d: Math.round(a.duration * 1000), assetId: a.assetId, sha256: a.sha256, sourceStartMs: a.sourceStartMs ?? 0 })),
+    }))
+    sources.set(step.stepId, { available: true, sourceFingerprint, playbackFingerprint, durationMs, narrationIds })
+  }
+  return sources
+}
+
+/** Typed canonical text is projected only after both content and real media/time evidence still match. */
+export function applyCaptionTimings(doc: IRDocument, track: LectureTrack, pages: readonly ProductionPage[]): ProductionDiagnostic[] {
+  const sources = captionTimingSources(doc, track, pages), diagnostics: ProductionDiagnostic[] = []
+  const overrides: NonNullable<LectureTrack['captionOverrides']> = []
+  for (const [stepId, value] of Object.entries(doc.production?.captionTimings ?? {})) {
+    const page = pages.find(page => page.steps.some(step => step.stepId === stepId)), step = page?.steps.find(step => step.stepId === stepId)
+    const section = doc.sections.find(section => section.id === page?.sectionId), source = sources.get(stepId)
+    const text = (section?.stepNarrations?.[stepId] ?? []).map(narration => narration.text).join('\n')
+    const stale = !source?.available || value.sourceFingerprint !== source.sourceFingerprint || value.playbackFingerprint !== source.playbackFingerprint
+      || value.durationMs !== source.durationMs || JSON.stringify(value.narrationIds) !== JSON.stringify(source.narrationIds) || captionTimingProblem(value, text)
+    if (stale || !step || step.startMs === undefined || step.endMs === undefined || !section) {
+      diagnostics.push({ code: 'production.caption-timing-stale', severity: 'warning', stepId, ...page ? { sectionId: page.sectionId } : {},
+        message: STALE[deckLocale(doc.meta.lang)] })
+      continue
+    }
+    overrides.push({ section: section.id, step: step.index, stepId, startMs: step.startMs, endMs: step.endMs,
+      groups: value.segments.map(segment => ({ id: `manual:${stepId}:${segment.id}`, text: text.slice(segment.from, segment.to), t: step.startMs! + segment.startMs, d: segment.endMs - segment.startMs, alignment: 'manual' })) })
+  }
+  track.captionOverrides = overrides
+  return diagnostics
+}

package/src/domain/captions.ts

@@ -0,0 +1,59 @@
+import type { LectureTrack, Utterance } from './track.ts'
+import { locate } from './words.ts'
+
+export interface CaptionGroup { id: string, text: string, t: number, d: number, alignment: 'words' | 'proportional' | 'none' | 'manual' }
+
+const MAX_CHARACTERS = 42
+const sentenceEnd = /[。！？!?；;]\s*[”’"'）)\]]*\s*$/u
+const hasText = /[\p{L}\p{N}]/u
+
+/** Readable display groups; every internal time boundary belongs to an actual word. */
+export function captionGroups(utterance: Utterance): CaptionGroup[] {
+  const full: CaptionGroup = { id: utterance.id, text: utterance.text, t: utterance.t, d: utterance.d,
+    alignment: utterance.alignment === 'proportional' ? 'proportional' : 'none' }
+  const words = utterance.words
+  if (utterance.silent || utterance.recording || utterance.unsaid || utterance.alignment !== 'words' || !words?.length || utterance.d <= 0) return [full]
+  const places = locate(words.map(word => word[2]), utterance.text)
+  let previous = utterance.t, end = 0
+  for (const [index, word] of words.entries()) {
+    const place = places[index]
+    if (!place || !Number.isFinite(word[0]) || !Number.isFinite(word[1]) || word[1] <= 0
+      || word[0] < previous || word[0] + word[1] > utterance.t + utterance.d
+      || hasText.test(utterance.text.slice(end, place.start))) return [full]
+    previous = word[0] + word[1]; end = place.end
+  }
+  if (hasText.test(utterance.text.slice(end))) return [full]
+  const asciiTokens = [...utterance.text.matchAll(/[\x21-\x7e]+/g)].map(match => ({ start: match.index, end: match.index + match[0].length }))
+  let token = 0
+  const groups: CaptionGroup[] = []
+  let from = 0, first = 0
+  const append = (last: number, to: number) => {
+    const start = first === 0 ? utterance.t : words[first]![0]
+    const until = last + 1 < words.length ? words[last + 1]![0] : utterance.t + utterance.d
+    if (until <= start) return false
+    groups.push({ id: `${utterance.id}:${from}`, text: utterance.text.slice(from, to), t: start, d: until - start, alignment: 'words' })
+    from = to; first = last + 1
+    return true
+  }
+  for (let index = 0; index < words.length; index++) {
+    const to = places[index + 1]?.start ?? utterance.text.length
+    const text = utterance.text.slice(from, to)
+    while (asciiTokens[token] && asciiTokens[token]!.end <= to) token++
+    const insideToken = asciiTokens[token] && asciiTokens[token]!.start < to && to < asciiTokens[token]!.end
+    const next = places[index + 2]?.start ?? utterance.text.length
+    if (!insideToken && (index + 1 === words.length || sentenceEnd.test(text) || [...utterance.text.slice(from, next)].length > MAX_CHARACTERS)) {
+      if (!append(index, to)) return [full]
+    }
+  }
+  return groups
+}
+
+export function captionGroupAt(groups: readonly CaptionGroup[], timeMs: number): CaptionGroup | undefined {
+  return groups.find(group => group.t <= timeMs && timeMs < group.t + group.d)
+}
+
+/** Shared projection used by publication and playback; an explicit manual gap stays empty. */
+export function trackCaptionGroups(track: LectureTrack): CaptionGroup[] {
+  return [...track.utterances.filter(u => !track.captionOverrides?.some(own => own.section === u.section && own.step === u.step)).flatMap(captionGroups),
+    ...track.captionOverrides?.flatMap(own => own.groups) ?? []].sort((a, b) => a.t - b.t)
+}

package/src/domain/config.ts

@@ -0,0 +1,67 @@
+import { documentVoice, irBlocks, isRecord, parseDuration, resolvedVoice, speechVoice, voiceOverrides } from '@lincyaw/kernel'
+import type { IRDocument, IRSection, SpeechVoice, VoiceTarget } from '@lincyaw/kernel'
+
+export interface LectureVoice {
+  engine?: string
+  voice: string
+  rate?: number
+  style?: string
+}
+
+export interface NarrationVoice { voice?: SpeechVoice, issue?: string, target?: VoiceTarget }
+
+export function configuredLectureVoice(doc: IRDocument): LectureVoice | undefined {
+  const overrides = voiceOverrides(doc)
+  return documentVoice(doc) ?? Object.values(overrides.pages)[0] ?? overrides.steps[0]?.voice
+}
+
+/** Resolve against the complete IR before renderer filtering compacts its steps. */
+export function prepareNarrationVoices(doc: IRDocument): void {
+  // JSON lowering resolves each authored narration against its stable step and
+  // Production scope. Do not replace those bindings with legacy source hints.
+  if (doc.production) return
+  const overrides = voiceOverrides(doc)
+  for (const section of doc.sections) {
+    const bindings = Object.fromEntries([...irBlocks(section.blocks)].filter(block => block.role === 'narration').map(block => {
+      const resolved = resolvedVoice(doc, section, block.at)
+      const unsafe = resolved.reason && overrides.steps.some(entry => entry.section === section.id)
+      return [block.id, { ...resolved.editable ? { target: resolved.target } : {}, ...unsafe ? { issue: resolved.reason } : resolved.voice ? { voice: resolved.voice } : { issue: 'voice-unset' } }]
+    }))
+    section.config = { ...section.config, 'presmium.lecture': { ...section.config?.['presmium.lecture'], resolvedNarrationVoices: bindings } }
+  }
+}
+
+export function narrationVoice(doc: IRDocument, section: IRSection, block?: string, step = 0): NarrationVoice {
+  const configured = section.config?.['presmium.lecture']?.resolvedNarrationVoices
+  const mapped = block && isRecord(configured) ? configured[block] : undefined
+  if (isRecord(mapped)) return { ...speechVoice(mapped.voice) ? { voice: speechVoice(mapped.voice) } : {}, ...typeof mapped.issue === 'string' ? { issue: mapped.issue } : {}, ...isRecord(mapped.target) ? { target: mapped.target as unknown as VoiceTarget } : {} }
+  const overrides = voiceOverrides(doc)
+  if (section.stepMap && overrides.steps.some(entry => entry.section === section.id)) return { issue: 'voice-step-binding-unavailable' }
+  const resolved = resolvedVoice(doc, section, step)
+  if (resolved.reason && overrides.steps.some(entry => entry.section === section.id)) return { issue: resolved.reason }
+  return { ...resolved.editable ? { target: resolved.target } : {}, ...resolved.voice ? { voice: resolved.voice } : { issue: 'voice-unset' } }
+}
+
+export function lectureVoice(config: Record<string, unknown> | undefined): LectureVoice | undefined {
+  const voice = isRecord(config?.voice) ? config.voice : undefined
+  if (typeof voice?.voice !== 'string' || !voice.voice) return undefined
+  return {
+    voice: voice.voice,
+    ...typeof voice.engine === 'string' && voice.engine ? { engine: voice.engine } : {},
+    ...typeof voice.rate === 'number' ? { rate: voice.rate } : {},
+    ...typeof voice.style === 'string' && voice.style ? { style: voice.style } : {},
+  }
+}
+
+export function lectureGap(config: Record<string, unknown> | undefined): number {
+  const gap = config?.gap
+  if (typeof gap === 'number' && gap >= 0) return gap
+  return (typeof gap === 'string' ? parseDuration(gap) : undefined) ?? 500
+}
+
+export function lexiconOf(config: Record<string, unknown> | undefined): Record<string, string> | undefined {
+  const lexicon = isRecord(config?.lexicon) ? config.lexicon : undefined
+  if (!lexicon) return undefined
+  const entries = Object.entries(lexicon).filter((entry): entry is [string, string] => typeof entry[1] === 'string')
+  return entries.length ? Object.fromEntries(entries) : undefined
+}

package/src/domain/drift.ts

@@ -0,0 +1,159 @@
+import { fingerprint, fnv1a64, irBlocks } from '@lincyaw/kernel'
+import type { IRBlock, IRDocument, MdastNode, TrackEvent } from '@lincyaw/kernel'
+import { anchorOf } from './timing.ts'
+import type { LectureTrack, TrackBlock } from './track.ts'
+import { PLAYER_RENDERER } from './track.ts'
+
+export type Grade = 'exact' | 'moved' | 'fuzzy' | 'lost'
+
+export function blockKey(section: string, block: string): string {
+  return `${section}/${block}`
+}
+
+export function blockOf(data: Record<string, unknown>): string | undefined {
+  if (typeof data.block !== 'string' || !data.block) return undefined
+  if (typeof data.section === 'string' && !data.block.includes('/')) return blockKey(data.section, data.block)
+  return data.block.includes('/') ? data.block : undefined
+}
+
+function text(node: MdastNode | undefined): string {
+  if (!node) return ''
+  const own = [node.value, node.alt].filter((v): v is string => typeof v === 'string')
+  return [...own, ...(node.children ?? []).map(text)].join(' ')
+}
+
+function content(block: IRBlock): string {
+  const { node } = block
+  if (node.type === 'code') return node.value
+  if (node.type === 'markdown') return text(node.mdast)
+  const files = new Set(Object.keys(node.assets ?? {}).map(path => path.split('.')[0]))
+  const props = Object.fromEntries(Object.entries(node.props).filter(([key]) => !files.has(key)))
+  return [node.name, JSON.stringify(props), ...(node.children ?? []).map(content)].join('\n')
+}
+
+export function codeLineCount(block: IRBlock): number | undefined {
+  return block.node.type === 'code' ? block.node.value.replace(/\n$/, '').split('\n').length : undefined
+}
+
+export function lastNamedLine(lines: unknown): number | undefined {
+  if (typeof lines !== 'string' && typeof lines !== 'number') return undefined
+  const numbers = String(lines).match(/\d+/g)?.map(Number) ?? []
+  return numbers.length ? Math.max(...numbers) : undefined
+}
+
+export function trackBlock(block: IRBlock): TrackBlock {
+  const fp = fingerprint(content(block))
+  const lines = codeLineCount(block)
+  return lines === undefined ? { fp } : { fp, lines }
+}
+
+export function playedBlocks(doc: IRDocument): Map<string, TrackBlock> {
+  const blocks = new Map<string, TrackBlock>()
+  for (const section of doc.sections) {
+    for (const block of irBlocks(section.blocks)) {
+      if (block.only && !block.only.includes(PLAYER_RENDERER)) continue
+      blocks.set(blockKey(section.id, block.id), trackBlock(block))
+    }
+  }
+  return blocks
+}
+
+export function irHash(doc: IRDocument): string {
+  return fnv1a64([...playedBlocks(doc)].map(([key, block]) => `${key}\t${block.fp}`).join('\n'))
+}
+
+export function sectionHashes(doc: IRDocument): Record<string, string> {
+  return Object.fromEntries(doc.sections.map(section => [section.id, irHash({ ...doc, sections: [section] })]))
+}
+
+export function unchanged(track: LectureTrack, doc: IRDocument): boolean {
+  const recorded = track.ir.sections
+  if (!recorded) return track.ir.hash === irHash(doc)
+  const now = sectionHashes(doc)
+  return Object.entries(recorded).every(([section, hash]) => now[section] === hash)
+}
+
+export function referencedBlocks(doc: IRDocument, events: readonly TrackEvent[]): Record<string, TrackBlock> {
+  const blocks = playedBlocks(doc)
+  const referenced: Record<string, TrackBlock> = {}
+  for (const [, , data] of events) {
+    const key = blockOf(data)
+    const block = key && blocks.get(key)
+    if (block) referenced[key] = block
+  }
+  return referenced
+}
+
+export interface BlockDrift {
+  grade: Grade
+  to?: string
+}
+
+export function blockDrift(track: LectureTrack, doc: IRDocument): Map<string, BlockDrift> {
+  const current = playedBlocks(doc)
+  const byFingerprint = new Map<string, string[]>()
+  for (const [key, block] of current) byFingerprint.set(block.fp, [...byFingerprint.get(block.fp) ?? [], key])
+  const keys = new Set([...Object.keys(track.blocks), ...track.events.flatMap(([, , data]) => blockOf(data) ?? [])])
+  const drift = new Map<string, BlockDrift>()
+  for (const key of keys) {
+    const recorded = track.blocks[key]
+    const now = current.get(key)
+    if (!recorded) {
+      drift.set(key, { grade: now ? 'exact' : 'lost' })
+      continue
+    }
+    if (now?.fp === recorded.fp) {
+      drift.set(key, { grade: 'exact' })
+      continue
+    }
+    const elsewhere = byFingerprint.get(recorded.fp) ?? []
+    if (elsewhere.length === 1) drift.set(key, { grade: 'moved', to: elsewhere[0] })
+    else drift.set(key, { grade: now ? 'fuzzy' : 'lost' })
+  }
+  return drift
+}
+
+export interface EventDrift {
+  index: number
+  grade: Grade
+  reason?: 'block' | 'section' | 'steps' | 'lines' | 'at'
+  block?: string
+  data: Record<string, unknown>
+}
+
+export function eventDrift(track: LectureTrack, doc: IRDocument): EventDrift[] {
+  const blocks = blockDrift(track, doc)
+  const current = playedBlocks(doc)
+  const sections = new Map(doc.sections.map(s => [s.id, s]))
+  const utterances = new Set(track.utterances.map(u => u.id))
+  return track.events.map(([, type, data], index): EventDrift => {
+    if (type === 'go') {
+      const section = typeof data.section === 'string' ? sections.get(data.section) : undefined
+      if (!section) return { index, grade: 'lost', reason: 'section', data }
+      const step = Number(data.step)
+      if (Number.isFinite(step) && step > section.steps) return { index, grade: 'fuzzy', reason: 'steps', data }
+      return { index, grade: 'exact', data }
+    }
+    const key = blockOf(data)
+    const at = anchorOf(data)
+    if (!key) return at && !utterances.has(at[0]) ? { index, grade: 'fuzzy', reason: 'at', data } : { index, grade: 'exact', data }
+    const drift = blocks.get(key) ?? { grade: 'lost' }
+    if (drift.grade === 'lost') return { index, grade: 'lost', reason: 'block', block: key, data }
+    const now = drift.to ?? key
+    const moved = drift.to ? moveTo(data, drift.to) : data
+    const last = lastNamedLine(data.lines ?? data.line)
+    const lines = current.get(now)?.lines
+    if (last !== undefined && lines !== undefined && last > lines) return { index, grade: 'lost', reason: 'lines', block: key, data: moved }
+    if (drift.grade !== 'exact') return { index, grade: drift.grade, reason: 'block', block: key, data: moved }
+    if (at && !utterances.has(at[0])) return { index, grade: 'fuzzy', reason: 'at', data }
+    return { index, grade: 'exact', data }
+  })
+}
+
+function moveTo(data: Record<string, unknown>, key: string): Record<string, unknown> {
+  const cut = key.lastIndexOf('/')
+  if (typeof data.section === 'string' && typeof data.block === 'string' && !data.block.includes('/')) {
+    return { ...data, section: key.slice(0, cut), block: key.slice(cut + 1) }
+  }
+  return { ...data, block: key }
+}