@lincyaw/workbench 0.0.0-stage → 0.2.0-rc.0

package/src/production-messages.ts

@@ -0,0 +1,151 @@
+import type { Locale } from './messages.ts'
+
+const zh = {
+  serviceSettings: '语音服务设置',
+  playOnDemand: '播放时按需生成配音并缓存；缺失讲稿会发送到所选语音服务。',
+  generatingPlayback: '正在生成当前配音，完成后自动播放。可暂停取消。',
+  generatingProgress: (done: number, total: number) => `正在生成配音 ${done} / ${total}，完成后自动播放。`,
+  library: '页面与素材', pages: '页面', media: '音频素材', properties: '步骤属性', narration: '讲稿', voiceTab: '配音', captionsTab: '字幕',
+  searchPages: '搜索页面', pageResults: (count: number) => `${count} 页`, pageSteps: (count: number) => `${count} 个步骤`, noPages: '没有匹配的页面',
+  resizeLibrary: '调整页面列表与画面宽度', issueCount: (count: number) => `${count} 项问题`,
+  resizeProperties: '调整画面与讲稿宽度', resizeTimeline: '调整画面与时间线高度',
+  title: '视频制作', back: '返回文稿', preview: '画面', script: '讲稿与配音', outputs: '导出',
+  step: '当前步骤', page: '页面', prepare: '准备画面', preparing: '正在准备画面…',
+  current: '当前保存版本', outdated: '需要更新', unavailable: '画面尚未准备',
+  previewHint: '用当前保存版本准备画面后即可查看。讲稿和音色可单独编辑。',
+  voice: '音色与配音', choose: '选择音色', generate: '生成配音', none: '静音', unset: '未设置音色',
+  recording: '录音来源',
+  inherited: { step: '本步设置', page: '继承本页', document: '继承文稿默认', unset: '未设置' },
+  scopeShort: { step: '本步', steps: '多步', page: '本页', document: '文稿' },
+  counts: (updated: number, preserved: number, unchanged: number) => `更新 ${updated} 个步骤，${preserved} 个步骤保留覆盖，${unchanged} 个步骤不变。`,
+  overridden: (none: number, recording: number) => `范围内有 ${none} 项静音、${recording} 项录音独立设置。`,
+  replaceCount: (count: number) => `确认替换 ${count} 处覆盖`, keepAssets: '录音和其他素材仍保留，不会改写讲稿或生成配音。',
+  mute: '设置为静音', restore: '使用继承设置', selectSteps: '请至少选择一个步骤。',
+  draftChanged: '文稿已更新。设置草稿已保留，请重新检查范围后应用。',
+  applyTitle: '确认音色应用范围', restoreTitle: '确认使用继承设置',
+  applyHint: '只修改所选范围的音色来源，正文、讲稿和播放时机保留。',
+  restoreHint: '所选层级改用上一级的设置，保留的下级覆盖不变。清除文稿默认后将没有默认音色。',
+  catalogFailed: '无法加载音色列表，请重试。', cached: '当前讲稿可使用已有配音缓存。',
+  sourceReady: '只有确认保存版本与步骤后才能试听或生成。',
+  currentScript: '试听本步讲稿', selectedVoice: '所选音色', unknownSource: '未连接的服务',
+  playbackHint: '当前按步骤编辑；播放时长与字幕时间由实际讲授的时间线得出。',
+  timeline: '时间线', play: '播放', pause: '暂停', rate: '播放速度', planLoading: '正在加载时间线…',
+  enable: '启用视频制作', enableHint: '此文稿尚未启用视频制作。启用后可使用时间线并导出讲授，正文和讲稿保留；选择音色后，播放时会按需生成配音。',
+  planOutdated: '文稿已更新，正在准备对应的时间线。', planRetry: '重新加载时间线', playbackWaiting: '准备当前画面后可播放或定位到时间。',
+  playbackLoading: '正在准备播放…', playbackFailed: '无法完成播放或定位，请重试。', planFailed: '当前编排无法准备，请检查步骤、配音和动画时长。',
+  estimatedPlan: '未生成部分显示估计时长。播放时自动生成并缓存，生成后更新精确时间。',
+  unknownPlan: '当前编排仍有未确认的时序。请查看原因，修正后再按时间播放或导出。',
+  issues: (count: number) => `查看 ${count} 项编排问题`,
+  diagnosticFallback: '当前编排包含未支持或无效的绑定，请检查关联内容。',
+  diagnostics: {
+    'production.animation-duration-unknown': '动画未声明有效时长，暂不能按时间播放或导出。',
+    'production.recording-cue-unsupported': '原音频没有提示的确认时码，请移除跨步或内部暂停，并将提示放到本步起点。',
+    'production.recording-start-conflict': '同一步讲稿的播放起点不一致，请先统一后采用原音频。',
+    'production.recording-captions-unverified': '录音已裁剪，字幕仍为本步完整讲稿，尚未按原音对齐，请核对。',
+    'production.recording-fingerprint-required': '请重新采用原音频以确认实际文件。',
+    'production.recording-unsupported': '录音来源已保留，但暂时不能用于这份讲稿的播放。',
+    'production.media-unsupported': '媒体片段已保留，暂不支持裁剪和混音。',
+    'production.silent-cue-unknown': '静音讲稿中的文字提示没有确认时码；请放到步骤起点或提供音频。',
+    'production.next-pause-unsupported': '跨步骤的同一段配音尚不能插入步骤停顿，请先拆成按步骤绑定的讲稿。',
+    'production.cache-missing': '当前配音尚未缓存，点击播放后自动生成。',
+    'production.voice-unset': '此讲稿尚未选择发声方式，请选择静音或实际音色。',
+    'production.cue-invalid': '讲稿提示的目标或动作无效，请检查对应的讲稿和内容。',
+  },
+  timingDraft: '请先确认或修正尚未保存的播放时机。', captionDraft: '未应用字幕时间', captionStorageFailed: '无法备份字幕时间，请保持此页面打开。',
+  tracks: { visual: '画面', voice: '配音', caption: '字幕' },
+  captionSegment: '字幕片段', chooseCaptionSegment: '选择字幕片段',
+  alignmentStatus: { manual: '手动时间', words: '词时码', proportional: '比例估时', none: '未对齐' },
+  segmentStatus: { recorded: '原音频', cached: '已有配音', silent: '静音', missing: '配音待生成', blocked: '暂不可用' },
+  waveformLoading: '正在加载波形…', waveformUnavailable: '波形不可用', stepNumber: (index: number) => `步骤 ${index + 1}`,
+  timelineLabels: { position: '位置', seconds: '秒', seek: '播放头位置', zoomIn: '放大时间线', zoomOut: '缩小时间线', fit: '适配本页', estimated: '估计时长', unknown: '时长未知', loading: '正在加载时间线…', empty: '当前页暂无时间线片段', seekHint: '选择步骤，或用时间尺、方向键和精确时间定位；定位会先暂停播放。', invalidPosition: '请输入本页时长范围内的秒数。' },
+  failures: {
+    'production-source-changed': '文稿已更新，旧播放请求已停止。请重新准备当前版本。',
+    'production-binding-stale': '时间线已更新，请重新加载后再播放。',
+    'production-plan-changed': '音频或时间线已更新，请重新加载后再播放。',
+    'production-plan-unavailable': '当前时间线尚不能播放，请检查缺失的配音、动画时长或不支持的媒体设置。',
+    'production-playback-unavailable': '画面尚未连接播放控制，请更新画面后重试。',
+    'production-playback-timeout': '无法确认播放或定位，请重试。',
+    'production-playback-time': '所选时间超出当前时间线，请重新定位。',
+    'production-playback-rate': '当前播放速度不可用，请重新选择。',
+    'production-playback-failed': '无法播放当前媒体，请检查音频能否读取。',
+    'production-playback-cancelled': '播放请求已取消。',
+  },
+}
+export const PRODUCTION_MESSAGES: Record<Locale, typeof zh> = {
+  'zh-CN': zh,
+  en: {
+    serviceSettings: 'Voice Service Settings',
+    playOnDemand: 'Play generates and caches missing voiceover using the selected speech service.',
+    generatingPlayback: 'Generating the current voiceover. Playback continues when ready; pause to cancel.',
+    generatingProgress: (done, total) => `Generating voiceover ${done} / ${total}. Playback continues when ready.`,
+    library: 'Pages and Assets', pages: 'Pages', media: 'Audio Assets', properties: 'Step Properties', narration: 'Script', voiceTab: 'Voiceover', captionsTab: 'Captions',
+    searchPages: 'Search Pages', pageResults: count => `${count} ${count === 1 ? 'page' : 'pages'}`, pageSteps: count => `${count} ${count === 1 ? 'step' : 'steps'}`, noPages: 'No matching pages',
+    resizeLibrary: 'Resize page list and visuals', issueCount: count => `${count} ${count === 1 ? 'Issue' : 'Issues'}`,
+    resizeProperties: 'Resize visuals and script', resizeTimeline: 'Resize visuals and timeline',
+    title: 'Video Production', back: 'Back to Document', preview: 'Visuals', script: 'Script and Voiceover', outputs: 'Export',
+    step: 'Current step', page: 'Page', prepare: 'Prepare Visuals', preparing: 'Preparing visuals…',
+    current: 'Current saved version', outdated: 'Update needed', unavailable: 'Visuals are not prepared',
+    previewHint: 'Prepare the saved version to see the visuals. Scripts and voices can be edited separately.',
+    voice: 'Voice and Voiceover', choose: 'Choose Voice', generate: 'Generate Voiceover', none: 'Silent', unset: 'No voice set',
+    recording: 'Recording source',
+    inherited: { step: 'This step', page: 'Inherited from page', document: 'Inherited from document', unset: 'Not set' },
+    scopeShort: { step: 'Step', steps: 'Selected', page: 'Page', document: 'Document' },
+    counts: (updated, preserved, unchanged) => `${updated} steps update, ${preserved} keep overrides, ${unchanged} stay unchanged.`,
+    overridden: (none, recording) => `This scope contains ${none} silent and ${recording} recording overrides.`,
+    replaceCount: count => `Replace ${count} ${count === 1 ? 'Override' : 'Overrides'}`, keepAssets: 'Recordings and other assets are kept. Scripts stay unchanged; no voiceover is generated.',
+    mute: 'Set to Silent', restore: 'Use Inherited Setting', selectSteps: 'Select at least one step.',
+    draftChanged: 'The document changed. Your settings draft is kept; check the scope again before applying.',
+    applyTitle: 'Confirm Voice Scope', restoreTitle: 'Use Inherited Setting',
+    applyHint: 'Only the voice source changes. Content, scripts, and timing are kept.',
+    restoreHint: 'The selected level uses its parent’s setting; overrides kept below it stay. Clearing the document default leaves no default voice.',
+    catalogFailed: 'Couldn’t load the list of voices. Try again.', cached: 'The current script can use existing cached voiceover.',
+    sourceReady: 'Confirm the saved version and step before listening or generating voiceover.',
+    currentScript: 'Play This Step’s Script', selectedVoice: 'Selected voice', unknownSource: 'Disconnected service',
+    playbackHint: 'Editing is organized by steps. Durations and caption times come from the lecture’s actual timeline.',
+    timeline: 'Timeline', play: 'Play', pause: 'Pause', rate: 'Playback speed', planLoading: 'Loading the timeline…',
+    enable: 'Turn On Video Production', enableHint: 'Video production is not turned on for this document. Turn it on to use the timeline and export the lecture; content and scripts are kept. Choose a voice, then Play generates missing voiceover.',
+    planOutdated: 'The document changed. Preparing its timeline.', planRetry: 'Reload Timeline', playbackWaiting: 'Prepare the current visuals to play or go to a time.',
+    playbackLoading: 'Preparing playback…', playbackFailed: 'Couldn’t finish playing or seeking. Try again.', planFailed: 'Couldn’t prepare the sequence. Check the steps, voiceover, and animation durations.',
+    estimatedPlan: 'Missing clips show estimated durations. Play generates and caches voiceover, then updates exact times.',
+    unknownPlan: 'Some timing is unconfirmed. Review the issues before timed playback or export.',
+    issues: count => `Review ${count} Sequence ${count === 1 ? 'Issue' : 'Issues'}`, diagnosticFallback: 'The sequence contains an unsupported or invalid link to content. Check the related content.',
+    diagnostics: {
+      'production.animation-duration-unknown': 'The animation has no valid declared duration. Timed playback and export are unavailable.',
+      'production.recording-cue-unsupported': 'The recording has no confirmed cue timing. Remove next-step cues and internal pauses, and place cues at the step start.',
+      'production.recording-start-conflict': 'Scripts in this step have different starts. Use one common start before using the recording.',
+      'production.recording-captions-unverified': 'The recording is trimmed. Captions still show the complete step script and are not aligned to the audio; review them.',
+      'production.recording-fingerprint-required': 'Use the recording again to confirm the actual file.',
+      'production.recording-unsupported': 'The recording source is kept but can’t be used to play this script yet.',
+      'production.media-unsupported': 'Media clips are kept. Trimming and mixing are not available yet.',
+      'production.silent-cue-unknown': 'Text-anchored cues in silent scripts have no confirmed timing. Move them to the step start or provide audio.',
+      'production.next-pause-unsupported': 'One voiceover clip that spans steps can’t take step pauses yet. Split it into one script per step.',
+      'production.cache-missing': 'This voiceover is not cached. Play generates it automatically.',
+      'production.voice-unset': 'This script has no voice source. Choose silence or an actual voice.',
+      'production.cue-invalid': 'A script cue has an invalid target or action. Check the script and its content.',
+    },
+    timingDraft: 'Confirm or correct the playback timing that is not saved first.', captionDraft: 'Caption times not applied', captionStorageFailed: 'Couldn’t back up caption times. Keep this page open.',
+    tracks: { visual: 'Visuals', voice: 'Voiceover', caption: 'Captions' },
+    captionSegment: 'Caption segment', chooseCaptionSegment: 'Choose Caption Segment',
+    alignmentStatus: { manual: 'Manual timing', words: 'Word timing', proportional: 'Proportional timing', none: 'Unaligned' },
+    segmentStatus: { recorded: 'Original audio', cached: 'Voiceover cached', silent: 'Silent', missing: 'Voiceover needed', blocked: 'Unavailable' },
+    waveformLoading: 'Loading waveform…', waveformUnavailable: 'Waveform unavailable', stepNumber: index => `Step ${index + 1}`,
+    timelineLabels: { position: 'Position', seconds: 'seconds', seek: 'Playhead position', zoomIn: 'Zoom In Timeline', zoomOut: 'Zoom Out Timeline', fit: 'Fit Page', estimated: 'Estimated duration', unknown: 'Unknown duration', loading: 'Loading the timeline…', empty: 'This page has no timeline segments', seekHint: 'Select a step, or use the ruler, arrow keys, or an exact time to seek. Seeking pauses playback first.', invalidPosition: 'Enter a time in seconds within this page’s duration.' },
+    failures: {
+      'production-source-changed': 'The document changed and the old playback request stopped. Prepare the current version.',
+      'production-binding-stale': 'The timeline changed. Reload it before playing.',
+      'production-plan-changed': 'The audio or timeline changed. Reload it before playing.',
+      'production-plan-unavailable': 'This timeline can’t be played yet. Check for missing voiceover, animation durations, or unsupported media settings.',
+      'production-playback-unavailable': 'The visuals are not connected to playback controls. Update the visuals and try again.',
+      'production-playback-timeout': 'Couldn’t confirm playing or seeking. Try again.',
+      'production-playback-time': 'The selected time is outside the current timeline. Choose another position.',
+      'production-playback-rate': 'This playback speed is unavailable. Choose another speed.',
+      'production-playback-failed': 'Couldn’t play the current media. Check that its audio can be read.',
+      'production-playback-cancelled': 'The playback request was canceled.',
+    },
+  },
+}
+
+export function productionFailure(error: unknown, locale: Locale): string {
+  const message = error instanceof Error ? error.message : String(error), t = PRODUCTION_MESSAGES[locale]
+  return (t.failures as Record<string, string>)[message] ?? t.playbackFailed
+}

package/src/production-playback.ts

@@ -0,0 +1,109 @@
+import type { PreviewReport, ProductionBinding, ProductionPlaybackCommand, ProductionPlaybackState } from '@lincyaw/kernel'
+import { sameProductionBinding } from '@lincyaw/kernel'
+import type { PreviewSink } from './workbench.ts'
+
+interface Context {
+  document?: string
+  scope: number
+  binding?: ProductionBinding
+  ready: boolean
+  sinks: ReadonlySet<PreviewSink>
+}
+interface Pending {
+  request: number
+  document: string
+  scope: number
+  sink: PreviewSink
+  generation?: number
+  binding: ProductionBinding
+  selection?: { sectionId: string, stepId: string }
+  finish(state?: ProductionPlaybackState, error?: string): void
+}
+
+/** Owns command acknowledgements from one live frame; reported positions always come from its lecture clock. */
+export class ProductionPlayback {
+  readonly #context: () => Context
+  readonly #publish: (state: ProductionPlaybackState | undefined) => void
+  #pending?: Pending
+  #owner?: { sink: PreviewSink, generation?: number, binding: ProductionBinding }
+  #sequence = 0
+
+  constructor(context: () => Context, publish: (state: ProductionPlaybackState | undefined) => void) {
+    this.#context = context; this.#publish = publish
+  }
+
+  /** A stable selection owns its target until the current frame has acknowledged it. */
+  selecting(sectionId?: string, stepId?: string): boolean {
+    const pending = this.#pending, context = this.#context()
+    return Boolean(pending?.selection && context.ready && pending.scope === context.scope && pending.document === context.document
+      && context.binding && sameProductionBinding(pending.binding, context.binding)
+      && (sectionId === undefined || pending.selection.sectionId === sectionId && pending.selection.stepId === stepId))
+  }
+
+  control(control: ProductionPlaybackCommand, signal?: AbortSignal): Promise<ProductionPlaybackState> {
+    if (signal?.aborted) return Promise.reject(signal.reason)
+    const context = this.#context(), sink = [...context.sinks].find(value => value.capabilities?.includes('production-playback'))
+    if (context.document === undefined || !context.ready || !context.binding || !sameProductionBinding(context.binding, control.binding)) return Promise.reject(new Error('production-source-changed'))
+    if (!sink) return Promise.reject(new Error('production-playback-unavailable'))
+    this.#pending?.finish(undefined, 'production-request-superseded')
+    const request = ++this.#sequence
+    this.#owner = { sink, generation: sink.generation, binding: control.binding }
+    return new Promise((resolve, reject) => {
+      const cancel = () => finish(undefined, 'production-request-cancelled')
+      const timer = setTimeout(() => finish(undefined, 'production-playback-timeout'), 15000)
+      const finish = (state?: ProductionPlaybackState, error?: string) => {
+        if (this.#pending?.request !== request) return
+        this.#pending = undefined
+        clearTimeout(timer); signal?.removeEventListener('abort', cancel)
+        if (error || !state) { this.#release(); reject(new Error(error ?? 'production-playback-unavailable')) }
+        else { this.#publish(state); resolve(state) }
+      }
+      this.#pending = { request, document: context.document!, scope: context.scope, sink, generation: sink.generation, binding: control.binding,
+        ...control.action === 'step' ? { selection: { sectionId: control.sectionId, stepId: control.stepId } } : {}, finish }
+      signal?.addEventListener('abort', cancel, { once: true })
+      try { sink.send({ type: 'production-playback', request, control }) }
+      catch { finish(undefined, 'production-playback-unavailable') }
+    })
+  }
+
+  report(document: string, report: PreviewReport, sink?: PreviewSink): void {
+    if (report.type !== 'production-playback-state' && report.type !== 'production-playback-result') return
+    const context = this.#context(), owner = this.#owner
+    if (!sink || !owner || document !== context.document || !context.ready || !context.binding || !context.sinks.has(sink)
+      || owner.sink !== sink || owner.generation !== sink.generation || !sameProductionBinding(owner.binding, context.binding)) return
+    if (report.type === 'production-playback-state') {
+      // An older state event cannot move a newer pending seek's playhead before its acknowledgement.
+      if (!this.#pending && sameProductionBinding(report.state.binding, owner.binding)) this.#publish(report.state)
+      return
+    }
+    const pending = this.#pending
+    if (!pending || pending.request !== report.request || pending.scope !== context.scope || pending.document !== document || pending.sink !== sink
+      || pending.generation !== sink.generation || !sameProductionBinding(pending.binding, report.binding)) return
+    if (report.state && !sameProductionBinding(report.state.binding, pending.binding)) pending.finish(undefined, 'production-source-changed')
+    else pending.finish(report.state, report.error)
+  }
+
+  /** Source edits or a replaced plan invalidate pending work before any old callback can be published. */
+  changed(): boolean {
+    const context = this.#context()
+    if (!this.#owner || context.ready && context.binding && sameProductionBinding(context.binding, this.#owner.binding)) return false
+    this.reset(); return true
+  }
+
+  detach(sink: PreviewSink): void { if (this.#owner?.sink === sink) this.reset() }
+
+  reset(): void {
+    if (this.#pending) { this.#pending.finish(undefined, 'production-source-changed'); return }
+    this.#release()
+  }
+
+  #release(): void {
+    const owner = this.#owner
+    this.#owner = undefined
+    // Cancelling a parent request also supersedes its asynchronous work in the child.
+    if (owner) {
+      try { owner.sink.send({ type: 'production-playback', request: ++this.#sequence, control: { binding: owner.binding, action: 'pause' } }) } catch {}
+    }
+    this.#publish(undefined)
+  }
+}

package/src/production-voice-playback.ts

@@ -0,0 +1,114 @@
+import { useEffect, useRef, useState } from 'react'
+import { sameProductionBinding } from '@lincyaw/kernel'
+import type { ProductionPlan, ProductionPlaybackPosition, VoiceoverJob } from '@lincyaw/kernel'
+import { useWorkbench, useWorkbenchState } from './context.tsx'
+import { prepareVoiceSnapshot, voiceSnapshotCurrent } from './voice-snapshot.ts'
+import { voiceFailure } from './voice-messages.ts'
+import type { Workbench, WorkbenchState } from './workbench.ts'
+import { isAgentChanging } from './workbench.ts'
+
+const running = (job: VoiceoverJob) => ['queued', 'running', 'cancelling'].includes(job.state)
+
+/** Observes the existing owners; it has no media timer, task ledger, or source writer. */
+function observeUntil<T>(workbench: Workbench, signal: AbortSignal, read: (state: WorkbenchState) => T | undefined): Promise<T> {
+  return new Promise((resolve, reject) => {
+    let stop = () => {}
+    const finish = (error?: unknown, value?: T) => { stop(); signal.removeEventListener('abort', abort); error ? reject(error) : resolve(value!) }
+    const abort = () => finish(signal.reason ?? new DOMException('Cancelled', 'AbortError'))
+    const check = () => { try { signal.throwIfAborted(); const value = read(workbench.getState()); if (value !== undefined) finish(undefined, value) } catch (error) { finish(error) } }
+    stop = workbench.subscribe(check); signal.addEventListener('abort', abort, { once: true }); check()
+  })
+}
+
+/** A click grants one cancellable playback intent; missing clips use the shared voiceover job and cache. */
+export function useProductionVoicePlayback() {
+  const workbench = useWorkbench(), locale = useWorkbenchState(state => state.locale)
+  const plan = useWorkbenchState(state => state.productionPlan), playback = useWorkbenchState(state => state.productionPlayback)
+  const source = useWorkbenchState(state => state.authoring), serviceVersion = useWorkbenchState(state => state.voiceServiceVersion)
+  const navigation = useWorkbenchState(state => state.productionNavigationVersion)
+  const blocked = useWorkbenchState(state => Boolean(state.hasDocumentTimingDrafts || state.documentTimingDraftStorageFailure || isAgentChanging(state)))
+  const [busy, setBusy] = useState(false), [starting, setStarting] = useState(false), [failure, setFailure] = useState<string>(), [progress, setProgress] = useState<{ completed: number, total: number }>()
+  const request = useRef<AbortController>(), startRequest = useRef<AbortController>(), intent = useRef(false), mounted = useRef(true), epoch = useRef(0)
+  const stop = () => { epoch.current++; intent.current = false; startRequest.current?.abort(); startRequest.current = undefined; request.current?.abort(); request.current = undefined; if (mounted.current) { setBusy(false); setStarting(false); setProgress(undefined) } }
+  useEffect(() => { mounted.current = true; return () => { mounted.current = false; stop() } }, [workbench])
+  useEffect(() => { stop() }, [source?.identity, source?.version, source?.fingerprint, source?.projectRevision, serviceVersion, navigation])
+  useEffect(() => { if (blocked || source?.dirty || source?.saving || source?.composing || source?.restored || source?.error) stop() }, [blocked, source?.dirty, source?.saving, source?.composing, source?.restored, source?.error])
+
+  const generate = async (oldPlan: ProductionPlan, position: ProductionPlaybackPosition) => {
+    if (request.current || !intent.current || !position.waitingFor) return
+    const controller = new AbortController(); request.current = controller
+    const signal = AbortSignal.any([controller.signal, AbortSignal.timeout(180000)])
+    const initial = workbench.getState(), directory = initial.document, navigation = initial.productionNavigationVersion, project = initial.authoring?.projectRevision
+    let job: VoiceoverJob | undefined, settled = false, stopProgress = () => {}
+    setBusy(true); setFailure(undefined); setProgress(undefined)
+    try {
+      const segment = oldPlan.tracks.find(track => track.kind === 'voice')?.segments.find(segment => segment.utteranceId === position.waitingFor)
+      if (!segment || !position.stepId || !position.sectionId) throw new Error('voice-context-changed')
+      const stepId = segment.sourceStepId ?? segment.stepId
+      const snapshot = await prepareVoiceSnapshot(workbench, stepId, signal)
+      if (directory === undefined || snapshot.directory !== directory || snapshot.source.version !== oldPlan.binding.source.version || snapshot.source.fingerprint !== oldPlan.binding.source.fingerprint) throw new Error('voice-context-changed')
+      const status = await workbench.client.readVoiceover(directory, signal)
+      if (!voiceSnapshotCurrent(workbench, snapshot) || status.revision !== snapshot.revision) throw new Error('voice-context-changed')
+      const selected = status.steps.find(step => step.stepId === stepId)
+      const unbound = status.unboundByPage?.find(page => page.section === segment.sectionId)
+      const pageScope = (segment.stepIds?.length ?? 0) > 1 || Boolean(unbound?.utterances)
+      const target = pageScope ? unbound : selected
+      if (target?.state === 'blocked') throw new Error(target.reason ?? 'voice-unavailable')
+      if (segment.status === 'blocked' && !target?.cached) throw new Error(target?.reason ?? 'voice-unset')
+      const current = () => {
+        signal.throwIfAborted(); const state = workbench.getState()
+        if (!intent.current || !voiceSnapshotCurrent(workbench, snapshot) || state.productionNavigationVersion !== navigation || state.authoring?.projectRevision !== project || state.productionPlan?.binding.irRevision !== snapshot.revision) {
+          controller.abort(); throw new Error('voice-context-changed')
+        }
+      }
+      current()
+      if (target?.state !== 'ready' && target?.state !== 'empty') {
+        job = await workbench.client.startVoiceover(directory, { source: snapshot.source, revision: snapshot.revision, scope: pageScope ? { kind: 'page', section: segment.sectionId } : { kind: 'step', target: snapshot.target }, confirmed: true }, signal)
+        current(); workbench.rememberVoiceoverJob(directory, job)
+        stopProgress = workbench.subscribe(() => { const latest = workbench.getState().voiceoverJobs?.find(value => value.id === job?.id); if (latest && mounted.current) setProgress({ completed: latest.completed, total: latest.total }) })
+        const finished = running(job) ? await observeUntil(workbench, signal, state => { current(); const latest = state.voiceoverJobs?.find(value => value.id === job!.id); return latest && !running(latest) ? latest : undefined }) : job
+        settled = true
+        if (finished.state !== 'done') throw new Error(finished.error ?? (finished.state === 'stale' ? 'voice-context-changed' : 'voice-generation-failed'))
+      }
+      current()
+      // The ordinary job observer refreshes the plan in the mounted frame. A concurrent hit has no local job.
+      if (!job) { await workbench.prepareProductionPlan(signal); current() }
+      const refreshed = await observeUntil(workbench, signal, state => {
+        current()
+        const next = state.productionPlan, live = state.productionPlayback
+        return next && next.binding.irRevision === snapshot.revision && next.binding.planId !== oldPlan.binding.planId && live?.status === 'ready' && sameProductionBinding(next.binding, live.binding) ? next : undefined
+      })
+      current()
+      await workbench.controlProduction({ binding: refreshed.binding, action: 'step', sectionId: position.sectionId, stepId: position.stepId, utteranceId: position.waitingFor }, signal)
+      current()
+      if (position.rate !== 1) await workbench.controlProduction({ binding: refreshed.binding, action: 'rate', rate: position.rate }, signal)
+      current()
+      await workbench.controlProduction({ binding: refreshed.binding, action: 'play' }, signal)
+    } catch (error) {
+      if (!controller.signal.aborted && mounted.current) { intent.current = false; setFailure(voiceFailure(error, locale)) }
+    } finally {
+      stopProgress()
+      if (job && !settled) void workbench.client.cancelVoiceover(directory!, job.id, AbortSignal.timeout(5000)).catch(() => {})
+      if (request.current === controller) { request.current = undefined; if (mounted.current) { setBusy(false); setProgress(undefined) } }
+    }
+  }
+  useEffect(() => {
+    if (intent.current && !busy && !starting && plan && playback?.position?.waitingFor && sameProductionBinding(plan.binding, playback.binding)) void generate(plan, playback.position)
+  }, [plan, playback, busy, starting])
+
+  const toggle = async () => {
+    const state = workbench.getState(), current = state.productionPlan
+    if (!current) return
+    if (request.current || startRequest.current || state.productionPlayback?.position?.playing) {
+      stop()
+      try { await workbench.controlProduction({ binding: current.binding, action: 'pause' }) } catch { /* The cancelled binding may already have been replaced. */ }
+      return
+    }
+    const controller = new AbortController(), owner = ++epoch.current
+    startRequest.current = controller; intent.current = true; setStarting(true); setFailure(undefined)
+    try { await workbench.controlProduction({ binding: current.binding, action: 'play' }, controller.signal) }
+    catch (error) { if (owner === epoch.current && !controller.signal.aborted) { intent.current = false; if (mounted.current) setFailure(voiceFailure(error, locale)) } }
+    finally { if (startRequest.current === controller) { startRequest.current = undefined; if (mounted.current) setStarting(false) } }
+  }
+  return { busy: busy || starting, failure, progress, stop, toggle }
+}

package/src/recording-adoption.ts

@@ -0,0 +1,33 @@
+import type { DocumentAnswer, DocumentRecordingAdoption, TeachingDocument, VoiceSource } from '@lincyaw/kernel'
+
+const same = (a: unknown, b: unknown): boolean => {
+  if (a === b) return true
+  if (!a || !b || typeof a !== 'object' || typeof b !== 'object') return false
+  if (Array.isArray(a) || Array.isArray(b)) return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((value, index) => same(value, b[index]))
+  const left = a as Record<string, unknown>, right = b as Record<string, unknown>, keys = Object.keys(left)
+  return keys.length === Object.keys(right).length && keys.every(key => Object.hasOwn(right, key) && same(left[key], right[key]))
+}
+function source(document: TeachingDocument, stepId: string): VoiceSource | undefined {
+  const step = document.steps[stepId]
+  return step && (document.production.stepOverrides[stepId]?.voiceSource ?? document.production.sectionOverrides?.[step.sectionId]?.voiceSource ?? document.production.defaults.voiceSource)
+}
+
+/** Accept only the submitted recording delta; later author input remains the sole local draft. */
+export function reconcileRecordingAdoption(request: DocumentRecordingAdoption, before: TeachingDocument, answer: DocumentAnswer, current: TeachingDocument): TeachingDocument | undefined {
+  if (before.id !== request.source.documentId || current.id !== before.id || answer.content.id !== before.id) return
+  const step = before.steps[request.stepId], asset = before.assets[request.assetId]
+  if (!step || asset?.kind !== 'audio') return
+  const expected = structuredClone(before)
+  const voice: VoiceSource = { type: 'recording', assetId: asset.id, ...request.sourceRange ? { sourceRange: { ...request.sourceRange } } : {} }
+  expected.assets[asset.id]!.fingerprint = `sha256:${request.sha256}`
+  expected.production.stepOverrides[step.id] = { ...expected.production.stepOverrides[step.id], voiceSource: voice }
+  if (!same(expected, answer.content)) return
+  const content = structuredClone(current), localAsset = content.assets[asset.id]
+  const assetUnchanged = same(localAsset, asset) || same(localAsset, expected.assets[asset.id])
+  if (assetUnchanged) content.assets[asset.id]!.fingerprint = `sha256:${request.sha256}`
+  const own = (document: TeachingDocument) => document.production.stepOverrides[step.id]?.voiceSource
+  if (assetUnchanged && content.steps[step.id] && same(own(current), own(before)) && same(source(current, step.id), source(before, step.id))) {
+    content.production.stepOverrides[step.id] = { ...content.production.stepOverrides[step.id], voiceSource: voice }
+  }
+  return content
+}

package/src/schema-form/PmSchemaForm.tsx

@@ -0,0 +1,187 @@
+import { useEffect, useId, useMemo, useRef, useState } from 'react'
+import type { ReactNode } from 'react'
+import Form from '@rjsf/core'
+import { createSchemaUtils } from '@rjsf/utils'
+import type { RJSFSchema } from '@rjsf/utils'
+import { validateDocumentParameters, documentParameterAccess, documentParameterSchemaForAccess } from '@lincyaw/kernel'
+import type { DocumentParameterValidation, JsonSchema, JsonValue } from '@lincyaw/kernel'
+import { PmNotice } from '../components.tsx'
+import type { ControlDensity } from '../components.tsx'
+import { SCHEMA_FORM_MESSAGES } from './context.ts'
+import type { FieldPathList, SchemaFormContext } from './context.ts'
+import { declaredSchemaProperties, schemaFormFields } from './fields.tsx'
+import { schemaFormTemplates } from './templates.tsx'
+import { schemaFormWidgets } from './widgets.tsx'
+import { schemaFormValidator } from './validator.ts'
+
+export interface PmSchemaFormProps {
+  schema: JsonSchema
+  value: JsonValue
+  onChange(value: JsonValue, validation: DocumentParameterValidation): void
+  onValidationChange?(validation: DocumentParameterValidation): void
+  onComposition?(composing: boolean): void
+  disabled?: boolean
+  readOnly?: boolean
+  density?: ControlDensity
+  locale?: 'zh-CN' | 'en'
+  label?: string
+  error?: ReactNode
+  extraValidation?(value: JsonValue): DocumentParameterValidation
+  /** Independent roots used for field access only; validity still belongs to extraValidation. */
+  accessorSchemas?: readonly JsonSchema[]
+  hideProperties?: readonly string[]
+  empty?: ReactNode
+  idPrefix?: string
+}
+const object = (value: unknown): value is Record<string, any> => Boolean(value && typeof value === 'object' && !Array.isArray(value))
+const own = (value: unknown, key: string | number) => value !== null && typeof value === 'object' && Object.hasOwn(value, key)
+const at = (value: unknown, path: FieldPathList): unknown => path.reduce((current: unknown, key) => own(current, key) ? (current as Record<string, unknown>)[key] : undefined, value)
+// RJSF represents unanswered fields with undefined; the authoring value contains JSON only.
+function jsonValue(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(item => item === undefined ? null : jsonValue(item))
+  if (object(value)) return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined).map(([key, item]) => [key, jsonValue(item)]))
+  return value
+}
+function replace(value: JsonValue, path: FieldPathList, next: unknown): JsonValue {
+  if (!path.length) return (next ?? null) as JsonValue
+  const result = structuredClone(value), last = path.at(-1)!
+  let parent: any = result
+  for (let index = 0; index < path.length - 1; index++) {
+    const key = path[index]!
+    if (!own(parent, key) || parent[key] === null || typeof parent[key] !== 'object') Object.defineProperty(parent, key, { value: typeof path[index + 1] === 'number' ? [] : {}, enumerable: true, configurable: true, writable: true })
+    parent = parent[key]
+  }
+  if (next === undefined && !Array.isArray(parent)) delete parent[last]
+  else Object.defineProperty(parent, last, { value: next === undefined ? null : structuredClone(next), enumerable: true, configurable: true, writable: true })
+  return result
+}
+
+/** Remove data-producing annotations only from schema positions, never from authored data. */
+function withoutDefaults(schema: JsonSchema): RJSFSchema {
+  if (typeof schema === 'boolean') return { allOf: [schema] } as RJSFSchema
+  const result = structuredClone(schema) as RJSFSchema
+  delete result.default
+  for (const key of ['$defs', 'definitions', 'properties', 'patternProperties', 'dependentSchemas'] as const) {
+    const entries = result[key]
+    if (object(entries)) result[key] = Object.fromEntries(Object.entries(entries).map(([name, child]) => [name, withoutDefaults(child)]))
+  }
+  for (const key of ['items', 'additionalProperties', 'additionalItems', 'contains', 'not', 'if', 'then', 'else', 'unevaluatedProperties', 'unevaluatedItems'] as const) {
+    const child = result[key]
+    if (typeof child === 'boolean' || object(child)) result[key] = withoutDefaults(child) as any
+    else if (Array.isArray(child)) result[key] = child.map(withoutDefaults) as any
+  }
+  for (const key of ['allOf', 'anyOf', 'oneOf', 'prefixItems'] as const) if (Array.isArray(result[key])) result[key] = result[key]!.map(withoutDefaults)
+  return result
+}
+
+/** Top-level fields resolved through the same public schema utilities used by the form. */
+export function schemaFormPropertyNames(schema: JsonSchema, value: JsonValue): { available: boolean, names: string[] } {
+  try {
+    const rendered = withoutDefaults(documentParameterSchemaForAccess(schema)), validator = schemaFormValidator(rendered)
+    const resolved = createSchemaUtils(validator, rendered).retrieveSchema(rendered, value)
+    // A selector's uncommitted branch is UI state, so it cannot be inferred from the saved value.
+    if (resolved.oneOf || resolved.anyOf) return { available: false, names: [] }
+    return { available: true, names: declaredSchemaProperties(resolved) }
+  } catch { return { available: false, names: [] } }
+}
+
+/** Controlled parameter fields. The caller owns drafts, scope, persistence and adoption. */
+export function PmSchemaForm({ schema, value, onChange, onValidationChange, onComposition, extraValidation, accessorSchemas = [], hideProperties = [], empty, idPrefix, disabled = false, readOnly = false, density = 'compact', locale = 'zh-CN', label, error }: PmSchemaFormProps) {
+  const id = useId(), current = useRef({ schema, value, onChange, onValidationChange, onComposition, extraValidation, accessorSchemas, disabled, readOnly })
+  current.current = { schema, value, onChange, onValidationChange, onComposition, extraValidation, accessorSchemas, disabled, readOnly }
+  const [inputErrors, setInputErrors] = useState<Record<string, string>>({}), [composing, setComposing] = useState(false)
+  const composition = useRef(false)
+  const reportedValidation = useRef<string>()
+  const view = useMemo(() => { try { return { available: true, schema: withoutDefaults(documentParameterSchemaForAccess(schema)) } } catch { return { available: false, schema: {} as RJSFSchema } } }, [schema])
+  const rendered = view.schema, validator = useMemo(() => schemaFormValidator(rendered), [rendered])
+  const utilities = useMemo(() => createSchemaUtils(validator, rendered), [validator, rendered])
+  const validate = (next: JsonValue) => {
+    const base = validateDocumentParameters(current.current.schema, next), extra = current.current.extraValidation?.(next)
+    return extra ? { available: base.available && extra.available, valid: base.valid && extra.valid, issues: [...base.issues, ...extra.issues] } : base
+  }
+  const validation = useMemo(() => validate(value), [schema, value, extraValidation])
+  const context = useMemo<SchemaFormContext>(() => ({ density, messages: SCHEMA_FORM_MESSAGES[locale], paths: new Map(), schemas: new Map(), readOnly: new Map(),
+    mark(control) {
+      const branch = control.replace(/__(?:oneof|anyof)_select$/, '')
+      this.intent = this.paths.get(control) ?? this.paths.get(branch)
+      this.intentReadOnly = this.readOnly.get(control) ?? this.readOnly.get(branch)
+      this.branch = branch !== control ? branch : undefined
+    },
+    inputError(control, message) { setInputErrors(errors => errors[control] === message || !message && !Object.hasOwn(errors, control) ? errors : message ? { ...errors, [control]: message } : Object.fromEntries(Object.entries(errors).filter(([key]) => key !== control))) },
+    access(path) {
+      const latest = current.current, primary = documentParameterAccess(latest.schema, latest.value, path)
+      // RJSF's public SchemaField carries the explicitly selected UI branch while a draft is incomplete.
+      // Schema/reference failures never use this path; the canonical validator must still be available.
+      const draft = primary.reason === 'value-unresolved' || primary.available && !primary.public ? validateDocumentParameters(latest.schema, latest.value) : undefined
+      const pointer = path.length ? `/${path.map(key => String(key).replace(/~/g, '~0').replace(/\//g, '~1')).join('/')}` : ''
+      // Unlike oneOf, the accessor may silently omit an anyOf branch with unanswered required fields.
+      const unanswered = draft?.issues.some(issue => issue.keyword === 'anyOf' && (issue.path === '' || pointer === issue.path || pointer.startsWith(`${issue.path}/`)))
+      const selected = Boolean(draft?.available && (primary.reason === 'value-unresolved' || unanswered))
+      const additional = latest.accessorSchemas.map(root => documentParameterAccess(root, latest.value, path))
+      return { available: (primary.available || selected) && additional.every(result => result.available), public: primary.public || selected || additional.some(result => result.public), readOnly: primary.readOnly || additional.some(result => result.readOnly) }
+    },
+    hideProperties: new Set(hideProperties), empty,
+  }), [density, locale, JSON.stringify(hideProperties), empty])
+  const result = useMemo<DocumentParameterValidation>(() => {
+    const issues = [...validation.issues, ...Object.values(inputErrors).map(message => ({ path: '', keyword: 'input', message })), ...composing ? [{ path: '', keyword: 'composing', message: context.messages.composing }] : []]
+    return { ...validation, valid: validation.valid && !issues.length, issues }
+  }, [validation, inputErrors, composing, context.messages.composing])
+  useEffect(() => {
+    const serialized = JSON.stringify(result)
+    if (!current.current.onValidationChange || serialized === reportedValidation.current) return
+    reportedValidation.current = serialized
+    current.current.onValidationChange(result)
+  }, [result, onValidationChange])
+  useEffect(() => () => { if (composition.current) current.current.onComposition?.(false) }, [])
+
+  const preserve = (before: unknown, after: unknown, scope: RJSFSchema, depth = 0): unknown => {
+    if (depth > 32) throw new Error('schema-form-depth')
+    if (scope.readOnly) return structuredClone(before)
+    if (!object(before) || !object(after)) return after
+    const fields: Record<string, RJSFSchema> = {}
+    const collect = (candidate: RJSFSchema, level: number) => {
+      if (level > 32) throw new Error('schema-form-depth')
+      const resolved = utilities.retrieveSchema(candidate, after)
+      for (const key of declaredSchemaProperties(resolved)) fields[key] = resolved.properties![key] as RJSFSchema
+      for (const key of ['allOf', 'oneOf', 'anyOf'] as const) for (const branch of resolved[key] ?? []) if (typeof branch !== 'boolean') collect(branch, level + 1)
+    }
+    collect(scope, depth)
+    const merged = structuredClone(before)
+    for (const [key, child] of Object.entries(fields)) {
+      if (typeof child === 'boolean' || child.readOnly) continue
+      if (!Object.hasOwn(after, key)) delete merged[key]
+      else Object.defineProperty(merged, key, { value: preserve(before[key], after[key], child, depth + 1), enumerable: true, configurable: true, writable: true })
+    }
+    return merged
+  }
+  if (!validation.available || !view.available) return <PmNotice tone="warn">{context.messages.unsupported}</PmNotice>
+  return <div className="pm-ui-schema-form" data-density={density} role="group" aria-label={label}
+    onCompositionStart={() => { composition.current = true; setComposing(true); current.current.onComposition?.(true) }}
+    onCompositionEnd={() => { composition.current = false; setComposing(false); current.current.onComposition?.(false) }}>
+    {error && <PmNotice tone="danger">{error}</PmNotice>}
+    <Form schema={rendered} formData={value} validator={validator} widgets={schemaFormWidgets} templates={schemaFormTemplates} fields={schemaFormFields} formContext={context}
+      idPrefix={idPrefix ?? `parameters-${id}`} tagName="div" noHtml5Validate showErrorList={false} liveValidate disabled={disabled} readonly={readOnly}
+      experimental_defaultFormStateBehavior={{ emptyObjectFields: 'skipDefaults', arrayMinItems: { populate: 'never' }, constAsDefaults: 'never', requiredBooleanDefault: 'skip' }}
+      uiSchema={{ 'ui:options': { expandable: false } }} onChange={event => {
+        const latest = current.current, path = context.intent, branch = context.branch, intentReadOnly = context.intentReadOnly
+        context.intent = undefined; context.branch = undefined; context.intentReadOnly = undefined
+        if (!path || latest.disabled || latest.readOnly || intentReadOnly) return
+        const access = context.access(path)
+        if (!access.available || !access.public || access.readOnly) return
+        let next = jsonValue(at(event.formData, path))
+        if (branch) {
+          let scope = rendered, data: unknown = latest.value
+          for (const key of path) {
+            const resolved = utilities.retrieveSchema(scope, data)
+            const child = Array.isArray(data) ? resolved.items : resolved.properties?.[key]
+            if (!child || typeof child === 'boolean' || Array.isArray(child)) throw new Error('schema-form-target-unavailable')
+            scope = child; data = own(data, key) ? (data as Record<string, unknown>)[key] : undefined
+          }
+          next = preserve(at(latest.value, path), next, scope)
+        }
+        const updated = replace(latest.value, path, next)
+        const checked = validate(updated)
+        latest.onChange(updated, composition.current ? { ...checked, valid: false, issues: [...checked.issues, { path: '', keyword: 'composing', message: context.messages.composing }] } : checked)
+      }}><span /></Form>
+  </div>
+}