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

package/src/node/tools.ts

@@ -0,0 +1,170 @@
+import { isAbsolute, relative, resolve } from 'node:path'
+import { deckLocale, defineService, DOCUMENT_FILES, SPEECH } from '@lincyaw/kernel'
+import type { AgentTool, AgentToolContext, IRDocument, SourceRange, SpeechService } from '@lincyaw/kernel'
+import { LECTURES_DIR, LECTURE_MESSAGES, LECTURE_TOOL_ERRORS, narrationDraft, narrationSource, SCRIPT_TRACK, trackDuration, translationItems } from '../domain/index.ts'
+import type { LecturePlan, LectureTrack } from '../domain/index.ts'
+import { latestView } from './latest-ir.ts'
+import { deckPlan } from './plan.ts'
+import { deckFiles, readTrack, TRACK_FILE, trackDir } from './store.ts'
+import type { DeckFiles } from './store.ts'
+import { synthesisFailureMessage, synthesizeLecture } from './synthesize.ts'
+import { assertVoiceSource, VoiceSourceRefusal } from './voice-source.ts'
+import { claimVoiceGeneration } from './voice-generation.ts'
+import { transcribeLecture } from './transcribe.ts'
+
+export interface LectureDeck {
+  deckDir: string
+  workspaceRoot: string
+}
+
+export const LECTURE_DECK = defineService<LectureDeck>('presmium.lecture.deck')
+
+function deckOf(ctx: AgentToolContext): { deckDir: string, doc: IRDocument, files: DeckFiles } {
+  const deck = ctx.service(LECTURE_DECK)
+  if (!deck) throw new Error('lecture-plugin-missing')
+  const doc = latestView(deck.deckDir)
+  if (!doc) throw new Error('document-not-ready')
+  return { deckDir: deck.deckDir, doc, files: deckFiles(deck.workspaceRoot, () => ctx.service(DOCUMENT_FILES)) }
+}
+
+function speechOf(ctx: AgentToolContext): SpeechService {
+  const speech = ctx.service(SPEECH)
+  if (!speech) throw new Error('speech-unavailable')
+  return speech
+}
+
+function planView(plan: LecturePlan, section?: string) {
+  return plan.sections.filter(s => !section || s.id === section).map(s => ({
+    section: s.id,
+    title: s.title,
+    from: s.from,
+    steps: s.steps,
+    paragraphs: s.paragraphs.map(p => ({
+      step: p.step,
+      said: p.pieces.map(piece => ({
+        ...piece.id ? { utterance: piece.id } : {},
+        text: piece.text,
+        ...piece.spoken !== piece.text ? { spoken: piece.spoken } : {},
+        cues: piece.cues.map(c => ({ cue: c.name, before: piece.text.slice(c.offset, c.offset + 8) || '(end)', ...c.data })),
+        ...piece.pause ? { pauseMs: piece.pause } : {},
+      })),
+    })),
+  }))
+}
+
+export const lecturePreview: AgentTool = {
+  name: 'lecture_preview',
+  description: 'The lecture plan of the deck: per section and step, the canonical lecture.json narration the synthesized lecture says and the {cue} marks in it with the operation each makes; the voice; and problems (unknown cues, missing blocks). Reads only; nothing is synthesized.',
+  input: { type: 'object', properties: { section: { type: 'string', description: 'Only this section id' } } },
+  kind: 'read',
+  async run(input, ctx) {
+    const { doc } = deckOf(ctx)
+    const deck = deckPlan(doc)
+    return {
+      voice: deck.voice ?? null,
+      gapMs: deck.gap,
+      sections: planView(deck.plan, typeof input.section === 'string' ? input.section : undefined),
+      problems: [...deck.findings.map(f => f.message), ...deck.plan.problems.filter(p => p.reportedAtCompile).map(p => p.message)],
+      play: deck.voice ? `?view=lecture&track=${SCRIPT_TRACK}` : null,
+    }
+  },
+}
+
+export const lectureSynthesize: AgentTool = {
+  name: 'lecture_synthesize',
+  description: 'Explicitly generates voiceover for the canonical narrations and Production voice sources: clips missing from the exact synthesis cache (.presmium/speech/) are synthesized by the speech engine, which costs money; matching clips come from cache. Returns the synthesized lecture\'s length and parts; play it with ?view=lecture&track=script.',
+  input: { type: 'object', properties: {} },
+  kind: 'spend',
+  async run(_input, ctx) {
+    const { deckDir, doc } = deckOf(ctx)
+    const source = await assertVoiceSource(doc, deckDir)
+    const assertCurrent = async () => {
+      if (latestView(deckDir) !== doc) throw new VoiceSourceRefusal('voice-source-changed')
+      await assertVoiceSource(doc, deckDir, source)
+      if (latestView(deckDir) !== doc) throw new VoiceSourceRefusal('voice-source-changed')
+    }
+    const release = claimVoiceGeneration(deckDir)
+    try {
+      await assertCurrent()
+      const { deck, track, failures } = await synthesizeLecture(doc, deckDir, speechOf(ctx), ctx.signal, { assertCurrent })
+      await assertCurrent()
+      ctx.signal.throwIfAborted()
+      if (!deck.voice) throw new Error(LECTURE_MESSAGES[deckLocale(doc.meta.lang)].production.noVoice)
+      if (!track) throw new Error(failures.map(failure => synthesisFailureMessage(failure)).join('\n'))
+      return {
+        track: SCRIPT_TRACK,
+        voice: track.voice,
+        durationMs: trackDuration(track),
+        utterances: track.utterances.length,
+        events: track.events.length,
+        problems: deck.findings.map(f => f.message),
+        source,
+      }
+    } finally { release() }
+  },
+}
+
+export const trackTranscribe: AgentTool = {
+  name: 'track_transcribe',
+  description: 'Transcribes a recorded lecture (lectures/<track>/): its audio goes to the speech engine\'s provider, which costs money; the transcript becomes the lecture\'s utterances, and the actions taken while a sentence was said are bound to its words. Writes lectures/<track>/track.json.',
+  input: { type: 'object', properties: { track: { type: 'string', description: 'The lecture id (a directory of lectures/)' } }, required: ['track'] },
+  kind: 'spend',
+  async run(input, ctx) {
+    const { deckDir, doc, files } = deckOf(ctx)
+    if (typeof input.track !== 'string' || !input.track) throw new Error('track-required')
+    const { track, bound, provider } = await transcribeLecture(files, deckDir, input.track, speechOf(ctx), doc, ctx.signal)
+    return { track: track.id, provider, utterances: track.utterances.map(u => ({ id: u.id, section: u.section, t: u.t, text: u.text })), bound }
+  },
+}
+
+function storedTrack(deckDir: string, input: Record<string, unknown>): LectureTrack {
+  if (typeof input.track !== 'string' || !input.track) throw new Error('track-required')
+  const track = trackDir(deckDir, input.track) ? readTrack(deckDir, input.track)?.track : undefined
+  if (!track) throw new Error(`no lecture ${input.track} (lectures/${input.track}/${TRACK_FILE})`)
+  return track
+}
+
+const TRACK_INPUT = { track: { type: 'string', description: 'The lecture id (a directory of lectures/)' } }
+
+export const trackNarration: AgentTool = {
+  name: 'track_narration',
+  description: 'A recorded lecture\'s transcript as narration, to write it back into the deck: per section and step, the sentences said there joined (draft), with a {cue …}`…` role before the word each action of the lecture (spotlight, pointer, next step, run …) was bound to; and where that step\'s narration is in the source (narration: file and lines of its paragraphs; for a step without narration, the on-screen block it follows: after). Reads only.',
+  input: { type: 'object', properties: { ...TRACK_INPUT, section: { type: 'string', description: 'Only this section id' } }, required: ['track'] },
+  kind: 'read',
+  async run(input, ctx) {
+    const { deckDir, doc } = deckOf(ctx)
+    const track = storedTrack(deckDir, input)
+    const draft = narrationDraft(track, typeof input.section === 'string' ? input.section : undefined)
+    const { plan } = deckPlan(doc)
+    const file = (range: SourceRange): SourceRange => ({ ...range, file: relative(deckDir, isAbsolute(range.file) ? range.file : resolve(deckDir, range.file)) })
+    return {
+      track: track.id,
+      lang: track.lang,
+      sections: draft.sections.map(s => ({
+        section: s.section,
+        title: doc.sections.find(own => own.id === s.section)?.title ?? '(the deck has no such section now)',
+        steps: s.steps.map((step) => {
+          const source = narrationSource(doc, plan, s.section, step.step)
+          return { ...step, narration: source.narration.map(file), ...source.after ? { after: { ...file(source.after), block: source.after.block } } : {} }
+        }),
+      })),
+      ...draft.skipped ? { skipped: `${draft.skipped} actions bound to words have no {cue}` } : {},
+    }
+  },
+}
+
+export const trackTranslations: AgentTool = {
+  name: 'track_translations',
+  description: 'The sentences (utterances) of a recorded lecture to translate: each with its id, text and source, the digest of the text that its translation records; with the translation into lang it has, if any, and whether that is stale. Write a translation into the utterance\'s line of lectures/<track>/track.json as "translations": { "<lang>": { "text": "…", "source": "<source>" } }. Reads only.',
+  input: { type: 'object', properties: { ...TRACK_INPUT, lang: { type: 'string', description: 'The language to translate into (BCP 47), e.g. en' } }, required: ['track', 'lang'] },
+  kind: 'read',
+  async run(input, ctx) {
+    const { deckDir } = deckOf(ctx)
+    const track = storedTrack(deckDir, input)
+    if (typeof input.lang !== 'string' || !input.lang) throw new Error('lang-required')
+    return { track: track.id, file: `${LECTURES_DIR}/${track.id}/${TRACK_FILE}`, lang: track.lang, into: input.lang, utterances: translationItems(track, input.lang) }
+  },
+}
+
+// Generation uses shared host start_voiceover tasks; the existing export CLI is unchanged.
+export const lectureTools: AgentTool[] = [lecturePreview, trackTranscribe, trackNarration, trackTranslations].map(tool => ({ ...tool, errors: LECTURE_TOOL_ERRORS }))

package/src/node/transcribe.ts

@@ -0,0 +1,53 @@
+import type { IRDocument, SpeechService } from '@lincyaw/kernel'
+import { sectionHints, transcribedTrack } from '../domain/index.ts'
+import type { LectureTrack, MediaSegment, SegmentTranscript } from '../domain/index.ts'
+import { whyNoTranscriptionEngine, transcriptionEngine } from './engines.ts'
+import { deckPlan } from './plan.ts'
+import { mediaFile, readInDeck, readTrack, trackDir, writeTrack } from './store.ts'
+import type { DeckFiles } from './store.ts'
+
+const MIME: Record<string, string> = { wav: 'audio/wav', ogg: 'audio/ogg', opus: 'audio/ogg', webm: 'audio/webm', mp4: 'audio/mp4', m4a: 'audio/mp4' }
+
+function audioBlob(file: string, bytes: Uint8Array): Blob {
+  return new Blob([new Uint8Array(bytes)], { type: MIME[file.split('.').at(-1) ?? ''] ?? 'application/octet-stream' })
+}
+
+interface TranscriptionOptions {
+  engine?: string
+  lang: string
+  /** The words likely said in a section (its narration's), which the engine takes as hints. */
+  hints: (section: string) => string[]
+}
+
+async function transcribeSegments(speech: SpeechService, segments: readonly MediaSegment[], audio: (segment: MediaSegment) => Blob | undefined, options: TranscriptionOptions, signal?: AbortSignal): Promise<SegmentTranscript[]> {
+  const transcripts: SegmentTranscript[] = []
+  for (const segment of segments) {
+    const local = audio(segment)
+    if (!local) throw new Error(`the audio of section ${segment.section} (${segment.src}) is not on this machine`)
+    const hints = options.hints(segment.section)
+    const transcript = await speech.transcribe({ ...options.engine ? { engine: options.engine } : {}, audio: local, lang: options.lang, ...hints.length ? { hints } : {} }, signal)
+    transcripts.push({ segment, segments: transcript.segments })
+  }
+  return transcripts
+}
+
+export async function transcribeLecture(files: DeckFiles, deckDir: string, id: string, speech: SpeechService, doc: IRDocument | undefined, signal?: AbortSignal): Promise<{ track: LectureTrack, bound: number, provider: string }> {
+  const stored = trackDir(deckDir, id) ? readTrack(deckDir, id) : undefined
+  if (!stored) throw new Error(`no lecture ${id}`)
+  const engine = await transcriptionEngine(speech, doc)
+  if (!engine) throw new Error(whyNoTranscriptionEngine(doc))
+  const audio = (segment: { src: string }) => {
+    const file = mediaFile(deckDir, id, segment.src)
+    const bytes = file && readInDeck(deckDir, file)
+    return file && bytes ? audioBlob(file, bytes) : undefined
+  }
+  const plan = doc && deckPlan(doc).plan
+  const hints = (section: string) => {
+    const planned = plan?.sections.find(s => s.id === section)
+    return planned ? sectionHints(planned, stored.track.lang) : []
+  }
+  const transcripts = await transcribeSegments(speech, stored.track.audio ?? [], audio, { engine: engine.id, lang: stored.track.lang, hints }, signal)
+  const { track, bound } = transcribedTrack(stored.track, transcripts)
+  await writeTrack(files, deckDir, track)
+  return { track, bound, provider: engine.provider }
+}

package/src/node/voice-generation.ts

@@ -0,0 +1,15 @@
+import { resolve } from 'node:path'
+
+const active = new Map<string, symbol>()
+export class VoiceGenerationBusy extends Error {
+  constructor() { super('voice-job-busy') }
+}
+
+/** One spending operation per document, including preflight awaits and cancellation acknowledgement. */
+export function claimVoiceGeneration(deckDir: string): () => void {
+  const key = resolve(deckDir)
+  if (active.has(key)) throw new VoiceGenerationBusy()
+  const owner = Symbol()
+  active.set(key, owner)
+  return () => { if (active.get(key) === owner) active.delete(key) }
+}

package/src/node/voice-source.ts

@@ -0,0 +1,34 @@
+import { createHash } from 'node:crypto'
+import { readFile } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+import { DOCUMENT_ENTRY, fnv1a64, isRecord } from '@lincyaw/kernel'
+import type { CanonicalSource, IRDocument } from '@lincyaw/kernel'
+
+export class VoiceSourceRefusal extends Error {}
+
+export function canonicalSource(value: unknown): value is CanonicalSource {
+  return isRecord(value) && typeof value.documentId === 'string' && value.documentId.length > 0
+    && typeof value.version === 'string' && /^[\da-f]{20}$/.test(value.version)
+    && typeof value.fingerprint === 'string' && /^[\da-f]{16}$/.test(value.fingerprint)
+}
+
+export function sameCanonicalSource(a: CanonicalSource, b: CanonicalSource): boolean {
+  return a.documentId === b.documentId && a.version === b.version && a.fingerprint === b.fingerprint
+}
+
+/** Generation and audition verify disk provenance; renderers continue consuming IR and exact cache only. */
+export async function assertVoiceSource(doc: IRDocument, deckDir: string, expected?: CanonicalSource): Promise<CanonicalSource> {
+  const source = doc.source
+  if (!canonicalSource(source)) throw new VoiceSourceRefusal('voice-source-unavailable')
+  if (expected && !sameCanonicalSource(expected, source)) throw new VoiceSourceRefusal('voice-source-changed')
+  const file = join(resolve(deckDir), DOCUMENT_ENTRY)
+  if (resolve(doc.meta.entry) !== file || doc.meta.documentId !== source.documentId) throw new VoiceSourceRefusal('voice-source-changed')
+  let raw: string
+  try { raw = await readFile(file, 'utf8') } catch { throw new VoiceSourceRefusal('voice-source-unavailable') }
+  if (createHash('sha256').update(raw).digest('hex').slice(0, 20) !== source.version || fnv1a64(raw) !== source.fingerprint) throw new VoiceSourceRefusal('voice-source-changed')
+  try {
+    const value: unknown = JSON.parse(raw.replace(/^\uFEFF/, ''))
+    if (!isRecord(value) || value.id !== source.documentId) throw new Error('identity')
+  } catch { throw new VoiceSourceRefusal('voice-source-changed') }
+  return { ...source }
+}

package/src/node/voiceover-execution.ts

@@ -0,0 +1,223 @@
+import { createHash } from 'node:crypto'
+import { readFile } from 'node:fs/promises'
+import { setImmediate } from 'node:timers/promises'
+import { deckLocale, errorMessage, isRecord, resolvedVoice, speechEngineId, speechFailureCode, speechVoice, voiceTarget } from '@lincyaw/kernel'
+import { irRevision, VoiceoverOperationError } from '@lincyaw/kernel/node'
+import type { CanonicalSource, IRDocument, NodeServiceContext, SpeechService, SpeechVoice, Synthesis, SynthesisRequest, VoiceoverExecution, VoiceoverProgress, VoiceoverRunResult, VoiceoverSnapshot, VoiceoverStatusQuery, VoicePreviewQuery, VoicePreviewQuote, VoiceScope, VoiceTarget } from '@lincyaw/kernel'
+import { plannedUtterances } from '../domain/index.ts'
+import { latestDoc, lectureView } from './latest-ir.ts'
+import { deckPlan } from './plan.ts'
+import { claimVoiceGeneration, VoiceGenerationBusy } from './voice-generation.ts'
+import { assertVoiceSource, VoiceSourceRefusal } from './voice-source.ts'
+import { createServedDeck, RouteRefusal } from './routes/served-deck.ts'
+
+const PREVIEW_TEXT = {
+  'zh-CN': '你好，这是一段配音试听。你可以用它比较音色，再选择文稿的配音音色。',
+  'en': 'Hello. This is a short voice preview for your presentation.',
+}
+
+type Unit = ReturnType<typeof plannedUtterances>[number]
+interface Context { source: CanonicalSource, doc: IRDocument, revision: string, units: Unit[], lang: string, lexicon?: Record<string, string> }
+const digest = (value: unknown) => createHash('sha256').update(JSON.stringify(value)).digest('hex')
+const validTarget = (value: unknown): value is VoiceTarget => isRecord(value) && typeof value.section === 'string' && Number.isSafeInteger(value.step) && (value.step as number) >= 0 && typeof value.binding === 'string'
+
+function scoped(context: Context, scope: VoiceScope): Unit[] {
+  if (scope.kind === 'document') return context.units
+  if (scope.kind === 'page') {
+    if (!context.doc.sections.some(section => section.id === scope.section)) throw new RouteRefusal(409, 'voice-target-changed')
+    return context.units.filter(unit => unit.section === scope.section)
+  }
+  const targets = scope.kind === 'step' ? [scope.target] : scope.targets
+  for (const at of targets) {
+    const section = context.doc.sections.find(section => section.id === at.section)
+    if (!section || at.step > section.steps || voiceTarget(section, at.step).binding !== at.binding) throw new RouteRefusal(409, 'voice-step-binding-stale')
+    const setting = resolvedVoice(context.doc, section, at.step)
+    if (!setting.editable) throw new RouteRefusal(409, `voice-${setting.reason}`)
+  }
+  return context.units.filter(unit => targets.some(at => unit.voiceTarget?.section === at.section && unit.voiceTarget.step === at.step && unit.voiceTarget.binding === at.binding))
+}
+
+function requestOf(context: Context, unit: Unit): SynthesisRequest {
+  if (unit.voiceIssue || !unit.voice) throw new RouteRefusal(409, unit.voiceIssue ?? 'voice-unset')
+  return { ...unit.voice, text: unit.spoken, lang: context.lang, ...context.lexicon ? { lexicon: context.lexicon } : {} }
+}
+
+
+/** Real lecture execution; the shared host owner retains all jobs and intents. */
+export function voiceoverExecution(ctx: NodeServiceContext): VoiceoverExecution {
+  const served = createServedDeck({ ...ctx, service: token => ctx.service?.(token) })
+  const context = async (expected?: CanonicalSource): Promise<Context> => {
+    const doc = latestDoc(served.deckDir)
+    if (!doc) throw new RouteRefusal(503, 'voice-document-unavailable')
+    const source = await assertVoiceSource(doc, served.deckDir, expected)
+    if (latestDoc(served.deckDir) !== doc) throw new RouteRefusal(409, 'voice-revision-changed')
+    const deck = deckPlan(lectureView(doc))
+    return { source, doc, revision: irRevision(doc), units: plannedUtterances(deck.plan), lang: deck.lang, lexicon: deck.lexicon }
+  }
+  const same = (now: Context) => latestDoc(served.deckDir) === now.doc
+  const assertCurrent = async (now: Context) => {
+    if (!same(now)) throw new RouteRefusal(409, 'voice-revision-changed')
+    await assertVoiceSource(now.doc, served.deckDir, now.source)
+    if (!same(now)) throw new RouteRefusal(409, 'voice-revision-changed')
+  }
+  const stale = (error: unknown) => error instanceof VoiceSourceRefusal || error instanceof RouteRefusal && error.message === 'voice-revision-changed'
+  const assertRevision = async (revision: unknown, expected?: CanonicalSource): Promise<Context> => {
+    const now = await context(expected)
+    if (revision !== now.revision) throw new RouteRefusal(409, 'voice-revision-changed')
+    return now
+  }
+  const engines = async (speech: SpeechService) => (await speech.engines()).filter(engine => engine.tts)
+  /** Naming an engine that does not synthesize, or that is not configured, is a bad request; only having no engine at all is the service's state. */
+  const noEngine = async (speech: SpeechService, preferred: string | undefined) => {
+    if (!preferred) return new RouteRefusal(503, 'voice-not-configured')
+    const id = speechEngineId(preferred), all = await speech.engines()
+    if (all.some(engine => engine.id === id)) return new RouteRefusal(422, 'voice-engine-unsupported')
+    return all.some(engine => engine.tts) ? new RouteRefusal(422, 'voice-engine-unknown') : new RouteRefusal(503, 'voice-not-configured')
+  }
+  const providerFor = async (speech: SpeechService, voice: SpeechVoice, now: Context, signal?: AbortSignal) => {
+    const list = await engines(speech)
+    const preferred = voice.engine ?? await speech.defaultSynthesisEngine?.()
+    const engine = preferred ? list.find(engine => engine.id === speechEngineId(preferred)) : undefined
+    if (!engine) throw await noEngine(speech, preferred)
+    const catalog = await speech.voiceCatalog?.(engine.id, undefined, signal)
+    if (catalog?.status !== 'available') throw new RouteRefusal(409, 'voice-catalog-unavailable')
+    const chosen = catalog.voices.find(candidate => candidate.id === voice.voice)
+    if (!chosen || chosen.lang.length && !chosen.lang.some(lang => lang.toLowerCase().split('-')[0] === now.lang.toLowerCase().split('-')[0])) throw new RouteRefusal(409, 'voice-unavailable')
+    return engine
+  }
+  const snapshot = async (query: VoiceoverStatusQuery, signal: AbortSignal): Promise<Omit<VoiceoverSnapshot, 'jobs'>> => {
+    const now = await context(query.source)
+    if (query.revision !== undefined && query.revision !== now.revision) throw new RouteRefusal(409, 'voice-revision-changed')
+    let speech: SpeechService | undefined
+    try { speech = served.speech() } catch { /* Readability and editing remain available without speech. */ }
+    const providers = speech ? await engines(speech) : []
+    const defaultEngine = await speech?.defaultSynthesisEngine?.()
+    const cached = new Map<string, boolean>()
+    const unavailable = new Map<string, string>()
+    const usable = new Set<string>()
+    await Promise.all(now.units.map(async unit => {
+      if (!speech || !unit.voice || unit.voiceIssue) return
+      try {
+        const hit = Boolean(await speech.lookup?.(requestOf(now, unit), signal))
+        cached.set(unit.id, hit)
+        if (!hit) await providerFor(speech, unit.voice, now, signal)
+        usable.add(unit.id)
+      } catch (error) { unavailable.set(unit.id, errorMessage(error)) }
+    }))
+    await assertCurrent(now)
+    const steps = now.doc.sections.flatMap(section => Array.from({ length: section.steps + 1 }, (_, step) => {
+      const selected = resolvedVoice(now.doc, section, step)
+      const units = now.units.filter(unit => unit.voiceTarget?.section === section.id && unit.voiceTarget.step === step)
+      const count = units.filter(unit => cached.get(unit.id)).length
+      const reason = units.find(unit => unit.voiceIssue)?.voiceIssue ?? units.map(unit => unavailable.get(unit.id)).find(Boolean) ?? (units.length > 0 && !selected.voice ? 'voice-unset' : undefined)
+      return { target: selected.target, ...section.stepIds?.[step] ? { stepId: section.stepIds[step] } : {}, state: reason ? 'blocked' as const : units.length === 0 ? 'empty' as const : count === units.length ? 'ready' as const : 'missing' as const, utterances: units.length, cached: count, ...reason ? { reason } : {} }
+    }))
+    const unboundByPage = now.doc.sections.flatMap(section => {
+      const units = now.units.filter(unit => !unit.voiceTarget && unit.section === section.id)
+      if (!units.length) return []
+      const count = units.filter(unit => cached.get(unit.id)).length
+      const reason = units.find(unit => unit.voiceIssue)?.voiceIssue ?? units.map(unit => unavailable.get(unit.id)).find(Boolean)
+      return [{ section: section.id, state: reason ? 'blocked' as const : count === units.length ? 'ready' as const : 'missing' as const, utterances: units.length, cached: count, ...reason ? { reason } : {} }]
+    })
+    return { source: now.source, revision: now.revision, capability: { available: Boolean(speech && usable.size), providers, ...defaultEngine ? { defaultEngine } : {}, ...!speech ? { reason: 'speech-unavailable' as const } : !usable.size && unavailable.size ? { reason: [...unavailable.values()].some(reason => reason === 'voice-not-configured') ? 'not-configured' as const : [...unavailable.values()].some(reason => reason === 'voice-catalog-unavailable') ? 'catalog-unavailable' as const : 'voice-unavailable' as const } : !usable.size ? { reason: 'voice-unset' as const } : {} }, steps, unboundByPage }
+  }
+
+  const quote = async (query: VoicePreviewQuery, signal: AbortSignal, expected?: CanonicalSource): Promise<{ quote: VoicePreviewQuote, request: SynthesisRequest, hit?: Synthesis, context: Context }> => {
+    const now = await assertRevision(query.revision, expected), voice = speechVoice(query.voice)
+    if (!voice) throw new RouteRefusal(400, 'voice-preview-invalid')
+    let text = PREVIEW_TEXT[deckLocale(now.lang)]
+    if (query.mode === 'step') {
+      if (!validTarget(query.target)) throw new RouteRefusal(400, 'voice-target')
+      text = scoped(now, { kind: 'step', target: query.target }).map(unit => unit.spoken).join('\n\n')
+      if (!text.trim()) throw new RouteRefusal(409, 'voice-script-empty')
+    }
+    if (text.length > 2000) throw new RouteRefusal(413, 'voice-preview-too-long')
+    const speech = served.speech(), available = await engines(speech)
+    const preferred = voice.engine ?? await speech.defaultSynthesisEngine?.()
+    const engine = preferred ? available.find(engine => engine.id === speechEngineId(preferred)) : undefined
+    const request = { ...voice, ...engine ? { engine: engine.id } : {}, text, lang: now.lang, ...now.lexicon ? { lexicon: now.lexicon } : {} }
+    const hit = await speech.lookup?.(request, signal)
+    if (!engine && !hit) throw await noEngine(speech, preferred)
+    if (!hit) await providerFor(speech, voice, now, signal)
+    await assertCurrent(now)
+    const provider = hit?.provider ?? engine!.provider, local = Boolean(hit || engine?.local)
+    const token = digest({ source: now.source, revision: now.revision, request, provider, local, target: query.target, mode: query.mode })
+    return { quote: { ...query, source: now.source, voice, text, provider, local, cached: Boolean(hit), quote: token }, request, hit, context: now }
+  }
+
+
+  const guarded = async <T>(run: () => Promise<T>): Promise<T> => {
+    try { return await run() }
+    catch (error) {
+      if (error instanceof VoiceSourceRefusal || error instanceof VoiceGenerationBusy) throw new VoiceoverOperationError(409, error.message)
+      throw error
+    }
+  }
+  return {
+    status: (query, signal) => guarded(() => snapshot(query, signal)),
+    prepare: (request, signal) => guarded(async () => {
+      signal.throwIfAborted()
+      const now = await assertRevision(request.revision, request.source), units = scoped(now, request.scope)
+      signal.throwIfAborted()
+      if (!units.length) throw new RouteRefusal(409, 'voice-script-empty')
+      const release = claimVoiceGeneration(served.deckDir)
+      try {
+        const speech = served.speech(), issues = new Map<string, string>()
+        for (const unit of units) {
+          signal.throwIfAborted(); await assertCurrent(now); signal.throwIfAborted()
+          try { if (!await speech.lookup?.(requestOf(now, unit), signal)) await providerFor(speech, unit.voice!, now, signal) }
+          catch (error) { signal.throwIfAborted(); if (stale(error)) throw error; issues.set(unit.id, errorMessage(error)) }
+          await assertCurrent(now)
+        }
+        signal.throwIfAborted()
+        if (issues.size === units.length) throw new RouteRefusal(409, issues.values().next().value ?? 'voice-unavailable')
+        return {
+          source: now.source, revision: now.revision, scope: structuredClone(request.scope), total: units.length, dispose: release,
+          async run(signal: AbortSignal, progress: (value: VoiceoverProgress) => void): Promise<VoiceoverRunResult> {
+            let completed = 0, failed = 0, failure: string | undefined, yielded = performance.now()
+            try {
+              for (const unit of units) {
+                signal.throwIfAborted(); await assertCurrent(now)
+                try {
+                  if (issues.has(unit.id)) throw new Error(issues.get(unit.id))
+                  const request = requestOf(now, unit)
+                  if (!await speech.lookup?.(request, signal)) {
+                    await providerFor(speech, unit.voice!, now, signal)
+                    await assertCurrent(now); signal.throwIfAborted()
+                    await speech.synthesize(request, signal)
+                  }
+                  signal.throwIfAborted(); await assertCurrent(now); signal.throwIfAborted(); completed++
+                } catch (error) {
+                  if (signal.aborted || stale(error) || !same(now)) throw error
+                  failed++; failure = speechFailureCode(error) ?? errorMessage(error)
+                }
+                progress({ completed, failed, ...failure ? { error: failure } : {} })
+                if (performance.now() - yielded >= 8) { await setImmediate(); yielded = performance.now() }
+              }
+              await assertCurrent(now); signal.throwIfAborted()
+              return { state: failed ? 'failed' : 'done', completed, failed, ...failure ? { error: failure } : {} }
+            } catch (error) {
+              const state = stale(error) || !same(now) ? 'stale' : signal.aborted ? 'cancelled' : 'failed'
+              return { state, completed, failed, ...state !== 'cancelled' ? { error: errorMessage(error) } : {} }
+            }
+          },
+        }
+      } catch (error) { release(); throw error }
+    }),
+    quote: (query, signal) => guarded(async () => (await quote(query, signal, query.source)).quote),
+    preview: (request, signal) => guarded(async () => {
+      const queried = await quote(request, signal, request.source)
+      if (request.quote !== queried.quote.quote) throw new RouteRefusal(409, 'voice-preview-changed')
+      const release = queried.hit ? undefined : claimVoiceGeneration(served.deckDir)
+      try {
+        signal.throwIfAborted(); await assertCurrent(queried.context); signal.throwIfAborted()
+        const result = queried.hit ?? await served.speech().synthesize(queried.request, signal)
+        await assertCurrent(queried.context)
+        const bytes = typeof result.audio === 'string' ? await readFile(result.audio) : Buffer.from(await result.audio.arrayBuffer())
+        if (bytes.byteLength > 8 << 20) throw new RouteRefusal(413, 'voice-preview-too-large')
+        signal.throwIfAborted(); await assertCurrent(queried.context); signal.throwIfAborted()
+        return { source: queried.context.source, revision: request.revision, voice: queried.quote.voice, text: queried.quote.text, cached: Boolean(queried.hit), key: result.key, bytes: new Uint8Array(bytes), mediaType: result.mime, duration: result.duration, provider: result.provider }
+      } finally { release?.() }
+    }),
+  }
+}