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

package/src/client/clock.ts

@@ -0,0 +1,169 @@
+import type { Store } from '@lincyaw/host'
+import { createStore } from '@lincyaw/host'
+
+export interface TrackClock {
+  now(): number
+  readonly playing: Readonly<Store<boolean>>
+  readonly rate: Readonly<Store<number>>
+  readonly error: Readonly<Store<Error | undefined>>
+  play(): void
+  pause(): void
+  seek(t: number): void
+  setRate(rate: number): void
+  tick(): void
+  dispose(): void
+}
+
+export class SilentClock implements TrackClock {
+  readonly playing = createStore(false)
+  readonly rate = createStore(1)
+  readonly error = createStore<Error | undefined>(undefined)
+  protected at = 0
+  protected since = performance.now()
+  protected readonly duration: number
+
+  constructor(duration: number) {
+    this.duration = duration
+  }
+
+  now(): number {
+    const t = this.playing.getSnapshot() ? this.at + (performance.now() - this.since) * this.rate.getSnapshot() : this.at
+    return Math.min(t, this.duration)
+  }
+
+  play(): void {
+    if (this.playing.getSnapshot()) return
+    if (this.at >= this.duration) this.at = 0
+    this.since = performance.now()
+    this.playing.set(true)
+  }
+
+  pause(): void {
+    this.at = this.now()
+    this.playing.set(false)
+  }
+
+  seek(t: number): void {
+    this.at = Math.max(0, Math.min(t, this.duration))
+    this.since = performance.now()
+  }
+
+  setRate(rate: number): void {
+    this.at = this.now()
+    this.since = performance.now()
+    this.rate.set(rate)
+  }
+
+  tick(): void {
+    if (this.playing.getSnapshot() && this.now() >= this.duration) this.pause()
+  }
+
+  dispose(): void {
+    this.pause()
+  }
+}
+
+export interface ClockMedia {
+  url: string
+  start: number
+  duration: number
+  sourceStartMs?: number
+  volume?: number
+  muted?: boolean
+}
+
+const DRIFT_MS = 250
+
+export class MediaClock extends SilentClock {
+  private readonly media: { el: HTMLAudioElement, start: number, duration: number, sourceStartMs: number }[]
+
+  constructor(duration: number, media: ClockMedia[]) {
+    super(duration)
+    this.media = media.map(({ url, start, duration: length, sourceStartMs = 0, volume = 1, muted = false }) => {
+      const el = new Audio()
+      el.preload = 'auto'
+      el.onerror = () => this.fail(new Error([url, el.error?.message].filter(Boolean).join(': ')))
+      el.src = url
+      el.volume = volume
+      el.muted = muted
+      return { el, start, duration: length, sourceStartMs }
+    })
+  }
+
+  private fail(error: Error): void {
+    this.pause()
+    this.error.set(error)
+  }
+
+  private mediaAt(t: number) {
+    return this.media.find(m => t >= m.start && t < m.start + m.duration)
+  }
+
+  override now(): number {
+    const current = this.playing.getSnapshot() ? this.mediaAt(super.now()) : undefined
+    if (current && !current.el.paused && current.el.readyState >= 2) {
+      const t = Math.min(current.start + current.duration, current.start + current.el.currentTime * 1000 - current.sourceStartMs)
+      this.at = Math.min(t, this.duration)
+      this.since = performance.now()
+      return this.at
+    }
+    return super.now()
+  }
+
+  override play(): void {
+    super.play()
+    this.tick()
+  }
+
+  override pause(): void {
+    super.pause()
+    for (const { el } of this.media) el.pause()
+  }
+
+  override seek(t: number): void {
+    super.seek(t)
+    for (const m of this.media) {
+      if (t >= m.start && t < m.start + m.duration) m.el.currentTime = (m.sourceStartMs + t - m.start) / 1000
+      else m.el.pause()
+    }
+    this.tick()
+  }
+
+  override setRate(rate: number): void {
+    super.setRate(rate)
+    for (const { el } of this.media) el.playbackRate = rate
+  }
+
+  override tick(): void {
+    super.tick()
+    const t = this.now()
+    for (const m of this.media) {
+      if (!this.playing.getSnapshot() || t < m.start || t >= m.start + m.duration) {
+        if (!m.el.paused) m.el.pause()
+        continue
+      }
+      const offset = (m.sourceStartMs + t - m.start) / 1000
+      if (m.el.paused || Math.abs(m.el.currentTime - offset) * 1000 > DRIFT_MS) m.el.currentTime = offset
+      m.el.playbackRate = this.rate.getSnapshot()
+      if (m.el.paused) void m.el.play().then(() => {
+        const at = super.now()
+        if (!this.playing.getSnapshot() || at < m.start || at >= m.start + m.duration) m.el.pause()
+      }).catch((error: unknown) => {
+        if (error instanceof DOMException && error.name === 'AbortError') return
+        this.fail(error instanceof Error ? error : new Error(String(error)))
+      })
+    }
+  }
+
+  override dispose(): void {
+    super.dispose()
+    for (const { el } of this.media) {
+      el.pause()
+      el.onerror = null
+      const url = el.src
+      el.removeAttribute('src')
+      el.load()
+      if (url.startsWith('blob:')) URL.revokeObjectURL(url)
+    }
+  }
+}

package/src/client/env.d.ts

@@ -0,0 +1,7 @@
+interface ImportMetaEnv {
+  BASE_URL: string
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv
+}

package/src/client/media.ts

@@ -0,0 +1,86 @@
+import { canEncodeAudio, getFirstEncodableVideoCodec, MediaStreamAudioTrackSource, MediaStreamVideoTrackSource, OggOutputFormat, Output, Quality, StreamTarget, WebMOutputFormat } from 'mediabunny'
+
+export interface Chunk {
+  data: Uint8Array<ArrayBuffer>
+  position: number
+}
+
+export type Sink = (chunk: Chunk) => void
+
+export interface Capture {
+  ext: 'ogg' | 'webm' | 'mp4'
+  stop(): Promise<void>
+  failed: Promise<never>
+}
+
+const SPEECH = new Quality({ bitrate: 24_000 })
+
+function target(sink: Sink): StreamTarget {
+  return new StreamTarget(new WritableStream({ write: chunk => sink({ data: chunk.data, position: chunk.position }) }))
+}
+
+async function withOutput(output: Output, clone: MediaStreamTrack, source: MediaStreamAudioTrackSource | MediaStreamVideoTrackSource, ext: Capture['ext']): Promise<Capture> {
+  if (source instanceof MediaStreamAudioTrackSource) output.addAudioTrack(source)
+  else output.addVideoTrack(source)
+  const failed = source.errorPromise.then(() => new Promise<never>(() => {}))
+  await output.start()
+  return {
+    ext,
+    failed,
+    async stop() {
+      await output.finalize()
+      clone.stop()
+    },
+  }
+}
+
+function withRecorder(clone: MediaStreamTrack, sink: Sink): Capture | undefined {
+  if (typeof MediaRecorder === 'undefined') return undefined
+  const type = ['audio/ogg;codecs=opus', 'audio/webm;codecs=opus', 'audio/mp4'].find(t => MediaRecorder.isTypeSupported(t))
+  if (!type) return undefined
+  const recorder = new MediaRecorder(new MediaStream([clone]), { mimeType: type, audioBitsPerSecond: 24_000 })
+  let position = 0
+  let writing = Promise.resolve()
+  recorder.ondataavailable = (event) => {
+    writing = writing.then(async () => {
+      const data = new Uint8Array(await event.data.arrayBuffer())
+      sink({ data, position })
+      position += data.byteLength
+    })
+  }
+  const failed = new Promise<never>((_, fail) => {
+    recorder.onerror = event => fail(new Error(String((event as ErrorEvent).message ?? 'MediaRecorder failed')))
+  })
+  recorder.start(1000)
+  return {
+    ext: type.startsWith('audio/ogg') ? 'ogg' : type.startsWith('audio/webm') ? 'webm' : 'mp4',
+    failed,
+    stop: () => new Promise((done) => {
+      recorder.onstop = () => void writing.then(() => {
+        clone.stop()
+        done()
+      })
+      recorder.stop()
+    }),
+  }
+}
+
+export async function captureAudio(track: MediaStreamTrack, sink: Sink): Promise<Capture | undefined> {
+  const clone = track.clone()
+  if (await canEncodeAudio('opus').catch(() => false)) {
+    const output = new Output({ format: new OggOutputFormat({ maximumPageDuration: 1 }), target: target(sink) })
+    return withOutput(output, clone, new MediaStreamAudioTrackSource(clone as MediaStreamAudioTrack, { codec: 'opus', quality: SPEECH }), 'ogg')
+  }
+  const fallback = withRecorder(clone, sink)
+  if (!fallback) clone.stop()
+  return fallback
+}
+
+export async function captureVideo(track: MediaStreamTrack, sink: Sink): Promise<Capture | undefined> {
+  const { width, height } = track.getSettings()
+  const codec = await getFirstEncodableVideoCodec(['vp9', 'vp8', 'av1'], { width, height }).catch(() => null)
+  if (!codec) return undefined
+  const clone = track.clone()
+  const output = new Output({ format: new WebMOutputFormat({ minimumClusterDuration: 1 }), target: target(sink) })
+  return withOutput(output, clone, new MediaStreamVideoTrackSource(clone as MediaStreamVideoTrack, { codec, quality: new Quality('medium') }), 'webm')
+}

package/src/client/playback.ts

@@ -0,0 +1,140 @@
+import { OPERATIONS, PLAYBACK_CONTROL, PRODUCTION_PLAYBACK, STEP_CLOCK, useMessages, useServer, useService, useStore } from '@lincyaw/host'
+import type { Operations, StepClock } from '@lincyaw/host'
+import { errorMessage, PREVIEW_REVISION, sameProductionBinding } from '@lincyaw/kernel'
+import type { ProductionBinding, ProductionPlan } from '@lincyaw/kernel'
+import { flushSync } from 'react-dom'
+import { useEffect, useRef, useState } from 'react'
+import { audioSegments, LECTURE_ID, LECTURE_MESSAGES, SCRIPT_TRACK, timedEvents, trackDuration } from '../domain/index.ts'
+import type { LectureTrack } from '../domain/index.ts'
+import type { ClockMedia, TrackClock } from './clock.ts'
+import { MediaClock, SilentClock } from './clock.ts'
+import { LecturePlayer } from './player.ts'
+import type { LectureSource } from './source.ts'
+import { lectureSource } from './source.ts'
+import { ProductionPlaybackController, settleProductionPlayback } from './production-playback.ts'
+import { exporting, play, playing, useViewer } from './state.ts'
+
+async function createClock(track: LectureTrack, source: LectureSource, signal?: AbortSignal): Promise<TrackClock> {
+  const length = trackDuration(track)
+  const segments = audioSegments(track)
+  if (!segments.length) return new SilentClock(length)
+  const loaded = await Promise.allSettled(segments.map(async (segment): Promise<ClockMedia> => {
+    if (track.binding && source.productionMedia && !segment.clipId) throw new Error('production-clip-unavailable')
+    const url = track.binding && source.productionMedia && segment.clipId ? await source.productionMedia(track.binding, segment.clipId, signal) : await source.media(track.id, segment.src)
+    return { url, start: segment.start, duration: segment.duration, sourceStartMs: segment.sourceStartMs, volume: segment.volume, muted: segment.muted }
+  }))
+  const media = loaded.flatMap(result => result.status === 'fulfilled' ? [result.value] : [])
+  const failed = loaded.find(result => result.status === 'rejected')
+  if (failed || signal?.aborted) { for (const { url } of media) if (url.startsWith('blob:')) URL.revokeObjectURL(url); if (failed) throw failed.reason; signal?.throwIfAborted() }
+  return new MediaClock(length, media)
+}
+function installExportHook(player: LecturePlayer, clock: StepClock | undefined): void {
+  const frame = () => new Promise<void>(done => requestAnimationFrame(() => done()))
+  Object.assign(window, { presmiumLecture: { duration: player.duration, async advance(at: number) {
+    flushSync(() => player.advanceTo(at)); await clock?.settled(); await frame(); await frame()
+  } } })
+}
+export function useLecturePlayback() {
+  const viewer = useViewer()
+  const doc = useStore(viewer.doc)
+  const server = useServer()
+  const operations = useService(OPERATIONS)
+  const stepClock = useService(STEP_CLOCK)
+  const playback = useService(PLAYBACK_CONTROL)
+  const provided = useService(PRODUCTION_PLAYBACK)
+  const production = provided instanceof ProductionPlaybackController ? provided : undefined
+  const t = useMessages(LECTURE_MESSAGES)
+  const [player, setPlayer] = useState<LecturePlayer>()
+  const [status, setStatus] = useState<'loading' | 'missing' | 'ready' | 'failed' | 'estimated' | 'unavailable'>()
+  const [failure, setFailure] = useState<string>()
+  const [language, setLanguage] = useState<string>()
+  const current = useRef<LecturePlayer>()
+  const generation = useRef(0)
+  const releaseClock = useRef<() => void>(() => {})
+  const releaseProduction = useRef<() => void>(() => {})
+  const clear = () => { releaseProduction.current(); releaseProduction.current = () => {}; current.current?.dispose(); current.current = undefined; releaseClock.current(); releaseClock.current = () => {} }
+  const start = async (track: LectureTrack, source: LectureSource, ops: Operations, load: number, at = 0, plan?: ProductionPlan, signal?: AbortSignal, origin?: { section: string, step: number }) => {
+    const clock = await createClock(track, source, signal)
+    if (load !== generation.current || signal?.aborted) { clock.dispose(); signal?.throwIfAborted(); return }
+    clear()
+    const next = new LecturePlayer(track, doc, ops, clock, playback, Boolean(plan))
+    current.current = next
+    releaseClock.current = stepClock?.drive({ elapsed: next.stepTime, recording: exporting }) ?? (() => {})
+    const seek = () => {
+      if (origin && next.seekStep(origin.section, origin.step)) return
+      if (origin && plan) { clear(); throw new Error('production-binding-stale') }
+      next.seek(at)
+    }
+    if (plan) flushSync(seek)
+    else seek()
+    if (plan && production) {
+      await settleProductionPlayback(stepClock, signal)
+      if (load !== generation.current || signal?.aborted) { signal?.throwIfAborted(); return }
+      releaseProduction.current = production.attach(plan, next, stepClock)
+    }
+    setPlayer(next); setLanguage(old => old ?? track.lang); setStatus('ready')
+    if (exporting) installExportHook(next, stepClock)
+  }
+  useEffect(() => {
+    clear(); setPlayer(undefined); setFailure(undefined)
+    if (!operations) { setStatus(undefined); return }
+    const source = lectureSource(server, doc.config.presmium[LECTURE_ID])
+    const currentBinding = (binding: ProductionBinding) => viewer.doc.getSnapshot() === doc && doc.source?.documentId === binding.source.documentId && doc.source.version === binding.source.version && doc.source.fingerprint === binding.source.fingerprint && doc.meta[PREVIEW_REVISION] === binding.irRevision
+    const loadTrack = async (id: string | undefined, binding?: ProductionBinding, signal?: AbortSignal) => {
+      const load = ++generation.current
+      const check = () => { signal?.throwIfAborted(); if (load !== generation.current || viewer.doc.getSnapshot() !== doc) throw new Error('production-binding-stale') }
+      if (binding && !currentBinding(binding)) throw new Error('production-binding-stale')
+      current.current?.pause(); setFailure(undefined)
+      if (!id) { clear(); setPlayer(undefined); setStatus(undefined); return }
+      setStatus('loading')
+      let plan: ProductionPlan | undefined
+      if (binding) {
+        if (!source.plan || !production) throw new Error('production-playback-unavailable')
+        plan = await source.plan({ source: binding.source, irRevision: binding.irRevision }, signal); check()
+        if (!sameProductionBinding(plan.binding, binding)) throw new Error('production-binding-stale')
+        clear(); setPlayer(undefined); production.loading(binding)
+        if (!plan.canPreview) {
+          releaseProduction.current = production.attach(plan)
+          setStatus(plan.timing === 'estimated' ? 'estimated' : 'unavailable')
+          return
+        }
+      }
+      const track = await source.track(id, plan?.binding.planId, signal); check()
+      if (!track) { clear(); setPlayer(undefined); setStatus('missing'); throw new Error('production-track-unavailable') }
+      if (binding && (!track.binding || !sameProductionBinding(track.binding, binding))) throw new Error('production-binding-stale')
+      // An estimate remains a caption fallback for ordinary readers; explicit production loads inspect its plan.
+      if (!binding && !exporting && track.id === SCRIPT_TRACK && track.utterances.length > 0 && track.utterances.every(utterance => Boolean(utterance.unsaid)) && audioSegments(track).length === 0) { play(undefined); return }
+      const position = viewer.position.getSnapshot()
+      const at = exporting ? 0 : timedEvents(track).find(event => event.type === 'go' && event.data.section === position.section && Number(event.data.step ?? 0) === position.step)?.t ?? 0
+      await start(track, source, operations, load, at, plan, signal, exporting ? undefined : position); check()
+    }
+    let selecting = false
+    const select = () => {
+      if (selecting) return
+      const request = generation.current + 1
+      void loadTrack(playing.getSnapshot()).catch(error => { if (generation.current === request) { setFailure(errorMessage(error)); setStatus('failed') } })
+    }
+    const stopSelect = playing.subscribe(select)
+    const stopLoader = production?.register({ current: currentBinding, async load(binding, signal) {
+      try {
+        await loadTrack(SCRIPT_TRACK, binding, signal)
+        selecting = true; play(SCRIPT_TRACK); selecting = false
+      } catch (error) {
+        if (!signal.aborted && currentBinding(binding)) { setFailure(errorMessage(error)); setStatus('failed') }
+        throw error
+      }
+    } })
+    select()
+    return () => { generation.current++; stopSelect(); stopLoader?.(); clear() }
+  }, [operations, doc, stepClock, playback, server.available, production])
+  // Cancel permission synchronously when IR changes, before a late parent grant can run.
+  useEffect(() => viewer.doc.subscribe(() => current.current?.pause()), [viewer])
+  useEffect(() => () => { play(undefined) }, [])
+  const clockError = useStore<Error | undefined>(player?.clock.error, undefined)
+  function reloadTrack(track: LectureTrack): void {
+    if (!operations || track.id !== playing.getSnapshot()) return
+    void start(track, lectureSource(server, doc.config.presmium[LECTURE_ID]), operations, ++generation.current, current.current?.time.getSnapshot() ?? 0).catch(error => setFailure(errorMessage(error)))
+  }
+  const clockFailure = clockError?.message === 'playback-timeout' ? t.player.playbackTimeout : clockError?.message
+  return { player, status, failure: failure ?? clockFailure, language, setLanguage, reloadTrack }
+}

package/src/client/player.ts

@@ -0,0 +1,202 @@
+import type { Operations, PlaybackControl, PlaybackLease } from '@lincyaw/host'
+import type { IRDocument } from '@lincyaw/kernel'
+import { createStore } from '@lincyaw/host'
+import { eventDrift, lastIndexAt, timedEvents, trackDuration } from '../domain/index.ts'
+import type { LectureTrack, TimedEvent } from '../domain/index.ts'
+import type { TrackClock } from './clock.ts'
+
+export class LecturePlayer {
+  readonly time = createStore(0)
+  /** The time since the lecture reached its current step (ms); undefined while the viewer tries the page out. */
+  readonly stepTime = createStore<number | undefined>(0)
+  readonly trying = createStore(false)
+  readonly waitingFor = createStore<string | undefined>(undefined)
+  readonly cursor = createStore<{ sectionId: string, step: number } | undefined>(undefined)
+  /** Event-identity selection can expose an empty interval while paused; time seeking and playback cannot. */
+  readonly positionMode = createStore<'time' | 'step'>('time')
+  readonly duration: number
+  readonly events: TimedEvent[]
+  readonly dropped: number
+
+  readonly track: LectureTrack
+  readonly clock: TrackClock
+  private readonly operations: Operations
+  // When the lecture reached the position of each event: a `go` that only changes the view (recorded
+  // as the presenter switched views) keeps the step's time, as the page's own clock does.
+  private readonly reached: number[]
+  private applied = -1
+  private frame = 0
+  private readonly unsubscribe: () => void
+  private readonly playback?: PlaybackLease
+  private disposed = false
+  private generation = 0
+  private readonly bufferMissing: boolean
+
+  constructor(track: LectureTrack, doc: IRDocument, operations: Operations, clock: TrackClock, playback?: PlaybackControl, bufferMissing = false) {
+    this.track = track
+    this.clock = clock
+    this.operations = operations
+    this.bufferMissing = bufferMissing
+    const drift = eventDrift(track, doc)
+    const kept = timedEvents(track).filter(event => drift[event.index]?.grade !== 'lost')
+    this.dropped = track.events.length - kept.length
+    this.events = kept.map((event) => {
+      const data = drift[event.index]?.data ?? event.data
+      if (event.type !== 'go') return { ...event, data }
+      const { view: _view, ...position } = data
+      return { ...event, data: position }
+    })
+    let position: string | undefined
+    let since = 0
+    this.reached = this.events.map((event) => {
+      const at = event.type === 'go' ? `${String(event.data.section)}\u0000${String(event.data.step)}` : position
+      if (at !== position) [position, since] = [at, event.t]
+      return since
+    })
+    this.duration = Math.max(trackDuration(track), this.events.at(-1)?.t ?? 0)
+    this.unsubscribe = operations.subscribe(operation => {
+      if (operation.type === 'go' && typeof operation.data.section === 'string') {
+        const step = Number(operation.data.step ?? 0)
+        if (this.seekStep(operation.data.section, step)) return
+      }
+      this.tryIt()
+    })
+    this.playback = playback?.register(() => this.pause())
+  }
+
+  get playing(): boolean {
+    return this.clock.playing.getSnapshot()
+  }
+
+  async play(): Promise<boolean> {
+    if (this.disposed) return false
+    if (this.playing) return true
+    const generation = ++this.generation
+    try {
+      if (this.playback && !await this.playback.requestStart()) return false
+      if (this.disposed || generation !== this.generation) return false
+      const at = this.clock.now()
+      if (this.trying.getSnapshot() || at >= this.duration) {
+        // Restore the timeline without cancelling the permission just granted
+        // for this start. Explicit Back/Seek still pause through their own API.
+        this.trying.set(false)
+        this.clock.seek(at >= this.duration ? 0 : at)
+        this.fold(this.clock.now())
+      }
+      if (this.disposed || generation !== this.generation) return false
+      this.positionMode.set('time')
+      this.clock.error.set(undefined)
+      if (this.bufferAt(this.clock.now(), this.clock.now())) return true
+      this.clock.play()
+      this.loop(generation)
+      return this.clock.playing.getSnapshot()
+    } catch (error) {
+      if (!this.disposed && generation === this.generation) { this.pause(); this.clock.error.set(error instanceof Error ? error : new Error(String(error))) }
+      return false
+    }
+  }
+
+  pause(): void {
+    this.waitingFor.set(undefined)
+    this.generation++
+    this.playback?.cancel()
+    cancelAnimationFrame(this.frame)
+    this.frame = 0
+    this.clock.pause()
+    this.setTime(this.clock.now())
+  }
+
+  seek(t: number): void {
+    this.pause()
+    this.positionMode.set('time')
+    this.trying.set(false)
+    this.clock.seek(t)
+    this.fold(this.clock.now())
+  }
+
+  /** A step is an event boundary, not just a timestamp: zero-length neighbours stay individually selectable. */
+  seekStep(sectionId: string, step: number): boolean {
+    if (this.disposed) return false
+    const target = this.events.findIndex(event => event.type === 'go' && event.data.section === sectionId && Number(event.data.step ?? 0) === step)
+    if (target < 0) return false
+    this.pause()
+    this.trying.set(false)
+    const event = this.events[target]!
+    this.clock.seek(event.t)
+    this.fold(event.t, target)
+    this.positionMode.set('step')
+    return true
+  }
+
+  setRate(rate: number): void {
+    this.clock.setRate(rate)
+  }
+
+  tryIt(): void {
+    this.pause()
+    if (this.trying.getSnapshot()) return
+    this.trying.set(true)
+    this.stepTime.set(undefined)
+  }
+
+  back(): void {
+    this.seek(this.clock.now())
+  }
+
+  dispose(): void {
+    this.disposed = true
+    this.playback?.dispose()
+    cancelAnimationFrame(this.frame)
+    this.unsubscribe()
+    this.clock.dispose()
+    this.operations.clear()
+  }
+
+  private fold(t: number, boundary?: number): void {
+    this.operations.clear()
+    this.cursor.set(undefined)
+    const last = boundary ?? Math.max(lastIndexAt(this.events, t), this.events.findIndex(e => e.type === 'go'))
+    for (let i = 0; i <= last; i++) this.apply(this.events[i]!, i < last)
+    this.applied = last
+    this.setTime(t)
+  }
+
+  private setTime(t: number): void {
+    this.time.set(t)
+    this.stepTime.set(this.trying.getSnapshot() ? undefined : t - (this.reached[this.applied] ?? 0))
+  }
+
+  private apply(event: TimedEvent, seeking: boolean): void {
+    this.operations.replay({ type: event.type, data: event.data }, seeking)
+    if (event.type === 'go' && typeof event.data.section === 'string') this.cursor.set({ sectionId: event.data.section, step: Number(event.data.step ?? 0) })
+  }
+
+  advanceTo(t: number): void {
+    this.positionMode.set('time')
+    while (this.applied + 1 < this.events.length && this.events[this.applied + 1]!.t <= t) this.apply(this.events[++this.applied]!, false)
+    this.setTime(t)
+  }
+
+  private loop(generation: number): void {
+    cancelAnimationFrame(this.frame)
+    const step = () => {
+      if (generation !== this.generation || !this.clock.playing.getSnapshot()) { this.frame = 0; return }
+      const before = this.time.getSnapshot(), now = this.clock.now()
+      if (this.bufferAt(before, now)) { this.frame = 0; return }
+      this.clock.tick()
+      this.advanceTo(this.clock.now())
+      this.frame = generation === this.generation && this.clock.playing.getSnapshot() ? requestAnimationFrame(step) : 0
+    }
+    this.frame = requestAnimationFrame(step)
+  }
+
+  /** Never let an estimated missing interval run silently in the author playback. */
+  private bufferAt(from: number, to: number): boolean {
+    if (!this.bufferMissing) return false
+    const missing = this.track.utterances.find(unit => unit.unsaid && unit.t + unit.d > from && unit.t <= to)
+    if (!missing) return false
+    const at = Math.max(from, missing.t)
+    this.pause(); this.clock.seek(at); this.advanceTo(at); this.waitingFor.set(missing.id)
+    return true
+  }
+}

package/src/client/plugin.ts

@@ -0,0 +1,33 @@
+import { OPERATIONS, PRODUCTION_PLAYBACK } from '@lincyaw/host'
+import type { PluginDefinition, Unsubscribe } from '@lincyaw/kernel'
+import { version } from '../../package.json'
+import { LECTURE_ID } from '../domain/index.ts'
+import { applyInk, applyPoint, clearInks, clearPointer } from './pointer-ink.ts'
+import { readLecturesFlag } from './state.ts'
+import { ProductionPlaybackController } from './production-playback.ts'
+
+let unregister: Unsubscribe[] = []
+
+const plugin: PluginDefinition = {
+  // dispose releases everything setup made; a paused preview starts the same definition again.
+  restartable: true,
+  manifest: { id: LECTURE_ID, name: { 'zh-CN': '讲授', en: 'Lecture' }, version, kernel: '^1.0.0', provides: [PRODUCTION_PLAYBACK], requires: [{ token: OPERATIONS, optional: true }] },
+  setup(ctx) {
+    readLecturesFlag(ctx.config)
+    const operations = ctx.tryGet(OPERATIONS)
+    unregister = operations
+      ? [operations.onReplay('point', { apply: applyPoint, clear: clearPointer }), operations.onReplay('ink', { apply: applyInk, clear: clearInks })]
+      : []
+    const production = new ProductionPlaybackController()
+    ctx.provide(PRODUCTION_PLAYBACK, production)
+    unregister.push(() => production.dispose())
+  },
+  dispose() {
+    unregister.forEach(off => off())
+    unregister = []
+    clearPointer()
+    clearInks()
+  },
+}
+
+export default plugin