@lincyaw/workbench 0.1.0 → 0.2.0-rc.0

package/src/telemetry.ts

@@ -0,0 +1,152 @@
+/** A value of an operation's attribute; undefined ones are left out. */
+export type OperationValue = string | number | boolean | undefined
+
+/** A batch of the author's operations, as the workbench sends it to the host. */
+export interface OperationBatch {
+  client: { id: string, browser?: string, locale?: string }
+  records: { name: string, time: number, seq: number, attributes: Record<string, string | number | boolean> }[]
+}
+
+const FLUSH_MS = 2000
+const BATCH = 200
+// Operations kept while the host has not answered, or while it cannot be reached.
+const QUEUE = 5000
+const BROWSER_KEY = 'presmium.telemetry.browser'
+const CONTROLS = 'button, a[href], [role="button"], [role="tab"], [role="menuitem"], [role="menuitemradio"], [role="menuitemcheckbox"], [role="option"], [role="switch"], input[type="checkbox"], input[type="radio"], select, summary'
+
+function newId(): string {
+  return globalThis.crypto?.randomUUID?.() ?? `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`
+}
+
+/** An id of this browser, kept in its storage, so that the loads of the workbench in it can be told apart from another's. */
+function browserId(): string | undefined {
+  try {
+    const known = localStorage.getItem(BROWSER_KEY)
+    if (known) return known
+    const id = newId()
+    localStorage.setItem(BROWSER_KEY, id)
+    return id
+  } catch {
+    return undefined
+  }
+}
+
+/** The name a control shows the author: its label, else its text. */
+function controlName(control: Element): string {
+  const label = control.getAttribute('aria-label') ?? control.getAttribute('title')
+  return (label ?? (control as HTMLElement).innerText ?? control.textContent ?? '').replace(/\s+/g, ' ').trim().slice(0, 120)
+}
+
+/**
+ * The author's operations in the workbench, for the operator's collector: kept in order with their time, and sent in
+ * batches to the host (`/api/presmium/telemetry`), which exports them with each session's events. Nothing leaves the
+ * page unless the host says it collects them; until it answers, operations wait.
+ */
+export class OperationLog {
+  readonly #read: () => Promise<{ enabled: boolean }>
+  readonly #send: (batch: OperationBatch, beacon: boolean) => Promise<void>
+  readonly #client: OperationBatch['client']
+  #enabled: boolean | undefined
+  #queue: OperationBatch['records'] = []
+  #seq = 0
+  #timer: ReturnType<typeof setTimeout> | undefined
+  #sending = false
+  #stop: (() => void) | undefined
+
+  constructor(read: () => Promise<{ enabled: boolean }>, send: (batch: OperationBatch, beacon: boolean) => Promise<void>, locale?: string) {
+    this.#read = read
+    this.#send = send
+    const browser = browserId()
+    this.#client = { id: newId(), ...browser ? { browser } : {}, ...locale ? { locale } : {} }
+  }
+
+  /** The id of this load of the workbench, carried by each of its operations. */
+  get client(): string {
+    return this.#client.id
+  }
+
+  /** Asks the host whether it collects operations; when it does, sends them, and also records clicks on the page's controls. */
+  async start(): Promise<void> {
+    try {
+      this.#enabled = (await this.#read()).enabled === true
+    } catch {
+      this.#enabled = false
+    }
+    if (!this.#enabled) {
+      this.#queue = []
+      return
+    }
+    const hidden = () => {
+      if (document.visibilityState === 'hidden') this.flush(true)
+    }
+    const away = () => this.flush(true)
+    const clicked = (event: MouseEvent) => {
+      const control = event.target instanceof Element ? event.target.closest(CONTROLS) : null
+      if (!control) return
+      const region = control.closest('[aria-label][role="region"], [data-pmw-slot], [role="dialog"]')
+      this.record('ui.click', {
+        'presmium.control': controlName(control),
+        'presmium.control.role': control.getAttribute('role') ?? control.tagName.toLowerCase(),
+        'presmium.control.activity': control.getAttribute('data-activity') ?? undefined,
+        'presmium.region': region ? (region.getAttribute('aria-label') ?? region.getAttribute('data-pmw-slot') ?? undefined) : undefined,
+      })
+    }
+    document.addEventListener('visibilitychange', hidden)
+    window.addEventListener('pagehide', away)
+    document.addEventListener('click', clicked, true)
+    this.#stop = () => {
+      document.removeEventListener('visibilitychange', hidden)
+      window.removeEventListener('pagehide', away)
+      document.removeEventListener('click', clicked, true)
+    }
+    this.#schedule()
+  }
+
+  /** Records one operation now; `attributes` with no value are left out. */
+  record(name: string, attributes: Record<string, OperationValue> = {}): void {
+    if (this.#enabled === false) return
+    const kept: Record<string, string | number | boolean> = {}
+    for (const [key, value] of Object.entries(attributes)) if (value !== undefined) kept[key] = value
+    this.#queue.push({ name, time: Date.now(), seq: ++this.#seq, attributes: kept })
+    if (this.#queue.length > QUEUE) this.#queue.splice(0, this.#queue.length - QUEUE)
+    if (this.#enabled === undefined) return
+    if (this.#queue.length >= BATCH) this.flush()
+    else this.#schedule()
+  }
+
+  /** Sends what is queued; `beacon` when the page goes away, without waiting for an answer. */
+  flush(beacon = false): void {
+    clearTimeout(this.#timer)
+    this.#timer = undefined
+    if (!this.#enabled || this.#queue.length === 0 || (this.#sending && !beacon)) return
+    const records = this.#queue.splice(0, beacon ? this.#queue.length : BATCH)
+    const batch = { client: this.#client, records }
+    if (beacon) {
+      void this.#send(batch, true).catch(() => undefined)
+      return
+    }
+    this.#sending = true
+    this.#send(batch, false).then(() => {
+      this.#sending = false
+      if (this.#queue.length > 0) this.#schedule()
+    }, () => {
+      // Kept for the next try, in their order, before what came since.
+      this.#sending = false
+      this.#queue.unshift(...records)
+      if (this.#queue.length > QUEUE) this.#queue.splice(0, this.#queue.length - QUEUE)
+      this.#schedule()
+    })
+  }
+
+  #schedule(): void {
+    if (this.#timer === undefined && this.#queue.length > 0) this.#timer = setTimeout(() => this.flush(), FLUSH_MS)
+  }
+
+  /** Sends what is left and stops recording clicks. */
+  stop(): void {
+    this.flush(true)
+    this.#stop?.()
+    this.#stop = undefined
+    this.#enabled = false
+  }
+}

package/src/transcription-messages.ts

@@ -0,0 +1,26 @@
+import type { Locale } from '@lincyaw/kernel'
+
+export const TRANSCRIPTION_MESSAGES = {
+  'zh-CN': {
+    import: '导入音频', retry: '重试', records: '转写记录', partial: '部分转写记录无法读取。', other: '另有转写正在进行。', show: '查看', audioUnavailable: '暂时无法检查音频。', loading: '正在加载…',
+    title: '转写', audio: '音频', service: '转写服务', none: '请选择音频', noAudio: '先录音或导入音频。', unavailable: '尚未配置转写服务。', unresolved: '暂时无法确认转写服务。', refresh: '刷新转写状态', start: '转写', cancel: '取消转写', cancelTitle: '取消转写？', cancelKeep: '继续转写', cancelConfirm: '取消', close: '关闭',
+    sending: '等待服务确认', queued: '等待转写', running: '正在转写', cancelling: '正在取消', cancelled: '已取消', done: '转写完成', failed: '转写失败', stale: '来源已更新', requestFailed: '无法确认转写结果，请刷新或取消。', readFailed: '无法读取转写结果，请重试。', storage: '本地恢复不可用，请保留此页面。',
+    text: '转写文本', review: '对照并采用为讲稿', before: '现有讲稿', after: '采用后', apply: '采用讲稿', applying: '正在保存…', adopted: '讲稿已保存', narration: '讲稿', newNarration: '新建讲稿', segments: '采用段落', allSegments: '全部段落', segment: (index: number) => `第 ${index + 1} 段`, empty: '没有可采用的文字。',
+    atoms: '发音与提示', keepAtom: '保留到光标处', removeAtom: '移除', pronunciation: '发音', cue: '提示', resolveAtoms: '请核对发音与提示的位置。', unknownAtom: '发音或提示已变化，请重新核对。', removed: '确认移除', removeTiming: '同时移除对应停顿', shared: '共享讲稿', fork: '仅当前步骤', editShared: '修改所有引用步骤', affected: (count: number) => `将修改 ${count} 个步骤`, conflicts: '还有未核对的修改。', sourceChanged: '文稿已更新，请重新对照。', confirm: '对照修改', edit: '继续校对', previewFailed: '暂时无法对照，请重试。', applyFailed: '无法确认已保存，校对内容已保留。', draftStorage: '校对内容暂时无法恢复，请保留此页面。', stepChanged: '目标步骤已变化，请重新选择。',
+  },
+  en: {
+    import: 'Import Audio', retry: 'Retry', records: 'Transcription history', partial: 'Some transcription records could not be read.', other: 'Another transcription is running.', show: 'View', audioUnavailable: 'Couldn’t check the audio right now.', loading: 'Loading…',
+    title: 'Transcription', audio: 'Audio', service: 'Transcription service', none: 'Select audio', noAudio: 'Record or import audio first.', unavailable: 'No transcription service configured.', unresolved: 'Couldn’t confirm the transcription service.', refresh: 'Refresh Transcription', start: 'Transcribe', cancel: 'Cancel Transcription', cancelTitle: 'Cancel transcription?', cancelKeep: 'Keep Transcribing', cancelConfirm: 'Cancel', close: 'Close',
+    sending: 'Waiting for the service', queued: 'Queued', running: 'Transcribing', cancelling: 'Canceling', cancelled: 'Canceled', done: 'Transcription completed', failed: 'Transcription failed', stale: 'Source changed', requestFailed: 'Couldn’t confirm the result. Refresh or cancel.', readFailed: 'Couldn’t read the transcript. Try again.', storage: 'Local recovery is unavailable. Keep this page open.',
+    text: 'Transcript', review: 'Compare and Use as Script', before: 'Current script', after: 'Proposed script', apply: 'Use Script', applying: 'Saving…', adopted: 'Script saved', narration: 'Script', newNarration: 'New Script', segments: 'Transcript segments', allSegments: 'All segments', segment: (index: number) => `Segment ${index + 1}`, empty: 'No text to adopt.',
+    atoms: 'Pronunciations and cues', keepAtom: 'Keep at Cursor', removeAtom: 'Remove', pronunciation: 'Pronunciation', cue: 'Cue', resolveAtoms: 'Review pronunciation and cue positions.', unknownAtom: 'Pronunciations or cues changed. Review them again.', removed: 'Confirm Removal', removeTiming: 'Also remove its pause', shared: 'Shared script', fork: 'This step only', editShared: 'All referencing steps', affected: (count: number) => `${count} steps will change`, conflicts: 'Some changes still need review.', sourceChanged: 'The document changed. Compare again.', confirm: 'Compare Changes', edit: 'Keep Editing', previewFailed: 'Couldn’t prepare the comparison. Try again.', applyFailed: 'Couldn’t confirm the save. Your edits are kept.', draftStorage: 'Draft recovery is unavailable. Keep this page open.', stepChanged: 'The target step changed. Select it again.',
+  },
+} satisfies Record<Locale, object>
+
+export function transcriptionFailure(error: unknown, locale: Locale): string {
+  const t = TRANSCRIPTION_MESSAGES[locale], code = error instanceof Error ? error.message : ''
+  if (code.includes('version-changed') || code.includes('source-changed') || code.includes('plan-changed') || code.includes('plan-expired')) return t.sourceChanged
+  if (code.includes('engine-unavailable') || code.includes('engine-unsupported') || code.includes('engine-unknown') || code.includes('speech-unavailable')) return t.unavailable
+  if (code.includes('services-unavailable')) return t.unresolved
+  return t.requestFailed
+}

package/src/transcription-session.ts

@@ -0,0 +1,159 @@
+import { isRecord } from '@lincyaw/kernel'
+import type { DocumentTranscriptionRequest, TranscriptionTask } from '@lincyaw/kernel'
+import { WorkspaceServerError } from './workspace-client.ts'
+import type { WorkspaceClient } from './workspace-client.ts'
+
+export interface TranscriptionSessionState {
+  request?: DocumentTranscriptionRequest
+  task?: TranscriptionTask
+  cancelled?: boolean
+  sending: boolean
+  cancelling: boolean
+  checking: boolean
+  verified: boolean
+  failure?: string
+  storageFailure: boolean
+}
+const active = (task?: TranscriptionTask) => Boolean(task && ['queued', 'running', 'cancelling'].includes(task.state))
+const validIntent = (value: unknown): value is string => typeof value === 'string' && /^[A-Za-z\d_-]{16,128}$/.test(value)
+const recoveredRequest = (value: unknown, documentId: string): value is DocumentTranscriptionRequest => isRecord(value) && isRecord(value.source)
+  && value.source.documentId === documentId && typeof value.source.version === 'string' && /^[a-f\d]{20}$/.test(value.source.version)
+  && typeof value.source.fingerprint === 'string' && /^[a-f\d]{16}$/.test(value.source.fingerprint) && validIntent(value.intent)
+  && typeof value.assetId === 'string' && Boolean(value.assetId) && typeof value.engine === 'string' && Boolean(value.engine)
+  && typeof value.audioSha256 === 'string' && /^[a-f\d]{64}$/.test(value.audioSha256) && value.confirmed === true
+const sessions = new WeakMap<WorkspaceClient, Map<string, TranscriptionSession>>()
+
+/** A task outlives its panel. Only explicit cancellation changes its remote lifetime. */
+export class TranscriptionSession {
+  readonly #client: WorkspaceClient
+  readonly #directory: string
+  readonly #documentId: string
+  readonly #key: string
+  readonly #listeners = new Set<() => void>()
+  #state: TranscriptionSessionState = { sending: false, cancelling: false, checking: false, verified: false, storageFailure: false }
+  #intent?: string
+  #taskId?: string
+  #read?: AbortController
+  #timer?: ReturnType<typeof setTimeout>
+  #closed = false
+
+  constructor(client: WorkspaceClient, identity: string, directory: string, documentId: string) {
+    this.#client = client; this.#directory = directory; this.#documentId = documentId
+    this.#key = `presmium.transcription.v1:${JSON.stringify([identity, directory, documentId])}`
+    try {
+      const raw = localStorage.getItem(this.#key)
+      if (raw) {
+        const value: unknown = JSON.parse(raw)
+        if (!isRecord(value) || value.documentId !== documentId || value.directory !== directory
+          || value.request !== undefined && !recoveredRequest(value.request, documentId)
+          || value.task !== undefined && (!isRecord(value.task) || !validIntent(value.task.intent) || typeof value.task.id !== 'string' || !/^[a-f\d]{64}$/.test(value.task.id))) throw new Error('transcription-recovery-invalid')
+        this.#state = { ...this.#state, request: value.request as DocumentTranscriptionRequest | undefined, cancelled: value.cancelled === true }
+        this.#intent = this.#state.request?.intent ?? (value.task as { intent: string } | undefined)?.intent
+        this.#taskId = (value.task as { id: string } | undefined)?.id
+      }
+    } catch { this.#state = { ...this.#state, storageFailure: true }; try { localStorage.removeItem(this.#key) } catch { /* Storage remains unavailable. */ } }
+  }
+
+  getState = (): TranscriptionSessionState => this.#state
+  get intent(): string | undefined { return this.#intent }
+  subscribe = (listener: () => void): (() => void) => {
+    this.#listeners.add(listener)
+    if (this.#listeners.size === 1) void this.refresh()
+    return () => { this.#listeners.delete(listener); if (!this.#listeners.size) this.#stopRead() }
+  }
+  #set(patch: Partial<TranscriptionSessionState>, persist = false): void {
+    if (this.#closed) return
+    this.#state = { ...this.#state, ...patch }
+    if (persist) {
+      try {
+        localStorage.setItem(this.#key, JSON.stringify({ documentId: this.#documentId, directory: this.#directory, request: this.#state.request, ...this.#taskId && this.#intent ? { task: { id: this.#taskId, intent: this.#intent } } : {}, cancelled: this.#state.cancelled }))
+        this.#state.storageFailure = false
+      } catch { this.#state.storageFailure = true }
+    }
+    for (const listener of this.#listeners) listener()
+  }
+  #stopRead(): void { clearTimeout(this.#timer); this.#timer = undefined; this.#read?.abort(); this.#read = undefined; if (this.#state.checking) this.#set({ checking: false }) }
+  #accept(task: TranscriptionTask): void {
+    if (task.intent !== this.#intent || task.document !== this.#directory || task.source.documentId !== this.#documentId || this.#state.cancelled && !this.#state.task) return
+    const previous = this.#state.task
+    if (previous?.id === task.id && task.sequence < previous.sequence) return
+    this.#taskId = task.id
+    this.#set({ task, request: undefined, sending: false, cancelled: false, verified: true, failure: undefined }, true)
+  }
+  select(task: TranscriptionTask): boolean {
+    if (this.#closed || this.#state.sending || this.#state.cancelling || this.#state.request || active(this.#state.task)
+      || task.document !== this.#directory || task.source.documentId !== this.#documentId) return false
+    this.#stopRead(); this.#intent = task.intent; this.#taskId = task.id
+    this.#set({ request: undefined, task, cancelled: false, verified: true, failure: undefined }, true)
+    void this.refresh()
+    return true
+  }
+  async start(request: DocumentTranscriptionRequest, start: () => Promise<TranscriptionTask>): Promise<void> {
+    if (this.#closed || this.#state.sending || this.#state.cancelling || this.#state.request || this.#taskId && !this.#state.verified || active(this.#state.task)) throw new Error('transcription-busy')
+    const sent = structuredClone(request)
+    if (sent.source.documentId !== this.#documentId) throw new Error('document-identity-changed')
+    this.#stopRead(); this.#intent = sent.intent; this.#taskId = undefined
+    this.#set({ request: sent, task: undefined, cancelled: false, sending: true, verified: false, failure: undefined }, true)
+    try { this.#accept(await start()) }
+    catch (error) {
+      if (this.#intent !== sent.intent || this.#state.cancelled) return
+      const known = error instanceof WorkspaceServerError && (error.status < 500 || ['transcription-engine-unavailable', 'transcription-audio-unavailable', 'transcription-services-unavailable'].includes(error.message))
+        || error instanceof Error && ['production-source-changed', 'document-identity-changed'].includes(error.message)
+      if (known) this.#intent = undefined
+      this.#set({ failure: error instanceof Error ? error.message : 'transcription-request-failed', ...known ? { request: undefined, sending: false } : {} }, true)
+    } finally {
+      if (this.#intent === sent.intent) { this.#set({ sending: false }); void this.refresh() }
+    }
+  }
+  async refresh(): Promise<void> {
+    if (this.#closed || !this.#intent || this.#state.cancelled || this.#read) return
+    clearTimeout(this.#timer); this.#timer = undefined
+    const intent = this.#intent, controller = new AbortController(); this.#read = controller
+    this.#set({ checking: true })
+    try {
+      const task = await this.#client.readTranscription(this.#directory, this.#taskId ? { id: this.#taskId } : { intent }, controller.signal)
+      if (!controller.signal.aborted && this.#intent === intent) this.#accept(task)
+    } catch (error) {
+      if (!controller.signal.aborted && this.#intent === intent) {
+        if (error instanceof WorkspaceServerError && error.message === 'transcription-intent-cancelled') this.#set({ request: undefined, cancelled: true, verified: true, failure: undefined }, true)
+        else if (!(error instanceof WorkspaceServerError && error.status === 404 && this.#state.request)) {
+          if (error instanceof WorkspaceServerError && error.status === 404 && this.#taskId) { this.#taskId = undefined; this.#intent = undefined }
+          this.#set({ failure: error instanceof Error ? error.message : 'transcription-request-failed' }, true)
+        }
+      }
+    } finally {
+      if (this.#read === controller) {
+        this.#read = undefined
+        this.#set({ checking: false })
+        if (!this.#closed && this.#listeners.size && this.#intent === intent && (this.#state.request || active(this.#state.task))) this.#timer = setTimeout(() => void this.refresh(), 1000)
+      }
+    }
+  }
+  async cancel(): Promise<void> {
+    if (this.#closed || !this.#intent || this.#state.cancelling || this.#state.cancelled) return
+    const intent = this.#intent
+    this.#set({ cancelling: true, failure: undefined })
+    try {
+      const answer = await this.#client.cancelTranscription(this.#directory, this.#taskId ? { id: this.#taskId } : { intent })
+      if (this.#intent !== intent || answer.intent !== intent) return
+      if (answer.task) this.#accept(answer.task)
+      else if (answer.state === 'cancelled') this.#set({ request: undefined, task: undefined, sending: false, cancelled: true, verified: true, failure: undefined }, true)
+    } catch (error) {
+      if (this.#intent === intent) this.#set({ failure: error instanceof Error ? error.message : 'transcription-cancel-failed' })
+    } finally { if (this.#intent === intent) { this.#set({ cancelling: false }); void this.refresh() } }
+  }
+  dispose(): void { this.#closed = true; this.#stopRead(); this.#listeners.clear() }
+}
+
+export function documentTranscriptionSession(client: WorkspaceClient, identity: string, directory: string, documentId: string): TranscriptionSession {
+  let known = sessions.get(client)
+  if (!known) sessions.set(client, known = new Map())
+  const key = JSON.stringify([identity, directory, documentId])
+  let session = known.get(key)
+  if (!session) { session = new TranscriptionSession(client, identity, directory, documentId); known.set(key, session) }
+  return session
+}
+export function disposeTranscriptionSessions(client: WorkspaceClient): void {
+  for (const session of sessions.get(client)?.values() ?? []) session.dispose()
+  sessions.delete(client)
+}

package/src/use-recording-adoption.ts

@@ -0,0 +1,84 @@
+import { useEffect, useRef, useState } from 'react'
+import type { DocumentRecordingAdoption } from '@lincyaw/kernel'
+import type { DocumentSessionState } from './document-session.ts'
+import { useWorkbench, useWorkbenchState } from './context.tsx'
+
+const requestId = () => `recording_${[...crypto.getRandomValues(new Uint8Array(16))].map(value => value.toString(16).padStart(2, '0')).join('')}`
+function applied(source: DocumentSessionState | undefined, request: DocumentRecordingAdoption): boolean {
+  const document = source?.content, step = document?.steps[request.stepId]
+  const voice = step && (document.production.stepOverrides[step.id]?.voiceSource ?? document.production.sectionOverrides?.[step.sectionId]?.voiceSource ?? document.production.defaults.voiceSource)
+  return Boolean(document?.id === request.source.documentId && voice?.type === 'recording' && voice.assetId === request.assetId && document.assets[request.assetId]?.fingerprint === `sha256:${request.sha256}`)
+}
+
+/** Request ownership and selection only; canonical changes and recovery belong to DocumentSession. */
+export function useRecordingAdoption({ identity, sectionId, stepId, active, disabled, candidateAssetId, onAdopted }: {
+  identity: string, sectionId: string, stepId: string, active: boolean, disabled: boolean, candidateAssetId?: string, onAdopted(): void,
+}) {
+  const workbench = useWorkbench(), source = useWorkbenchState(state => state.authoring)
+  const [selection, setSelection] = useState<string>(), [busy, setBusy] = useState(false), [failure, setFailure] = useState<string>()
+  const owner = useRef({ active: false, revision: 0 }), request = useRef<AbortController>(), retry = useRef<DocumentRecordingAdoption>(), submitted = useRef<DocumentRecordingAdoption>(), reported = useRef<string>()
+  const latest = useRef({ sectionId, stepId, active, onAdopted }); latest.current = { sectionId, stepId, active, onAdopted }
+  const document = source?.identity === identity ? source.content : undefined
+  const effective = document && (document.production.stepOverrides[stepId]?.voiceSource ?? document.production.sectionOverrides?.[sectionId]?.voiceSource ?? document.production.defaults.voiceSource)
+  const selected = selection ?? candidateAssetId ?? (effective?.type === 'recording' ? effective.assetId : '')
+  const assets = Object.values(document?.assets ?? {}).filter(asset => asset.kind === 'audio')
+  const adopted = Boolean(source && !source.loading && !source.dirty && !source.saving && !source.error && effective?.type === 'recording' && effective.assetId === selected && /^sha256:[a-f\d]{64}$/.test(document?.assets[selected]?.fingerprint ?? ''))
+  const current = () => owner.current.active && workbench.getState().authoring?.identity === identity
+  useEffect(() => { owner.current.active = true; return () => { owner.current.active = false; request.current?.abort() } }, [])
+  useEffect(() => {
+    owner.current.revision++; request.current?.abort(); request.current = undefined; setBusy(false); setFailure(undefined)
+  }, [sectionId, stepId, active])
+  useEffect(() => {
+    const sent = submitted.current
+    if (!sent || source?.identity !== identity) return
+    if (applied(source, sent)) {
+      if (retry.current?.id === sent.id) retry.current = undefined
+      if (!source.loading && !source.dirty && !source.saving && !source.composing && !source.error && reported.current !== sent.id) {
+        reported.current = sent.id
+        setFailure(undefined); latest.current.onAdopted()
+      }
+    } else if (source.version !== sent.source.version && request.current) {
+      request.current.abort(); request.current = undefined; setBusy(false); setFailure('production-source-changed')
+    }
+  }, [identity, source?.identity, source?.version, source?.content, source?.loading, source?.dirty, source?.saving, source?.composing, source?.error])
+  const choose = (assetId: string) => {
+    owner.current.revision++; request.current?.abort(); request.current = undefined; retry.current = undefined
+    setSelection(assetId); setBusy(false); setFailure(undefined)
+  }
+  const imported = (assetId: string, revision: number) => { if (current() && owner.current.revision === revision) choose(assetId) }
+  const adopt = async () => {
+    if (!selected || busy || disabled || !active || !current() || adopted) return
+    const target = { sectionId, stepId, assetId: selected }, revision = owner.current.revision, controller = new AbortController()
+    request.current = controller; setBusy(true); setFailure(undefined)
+    const owns = () => current() && request.current === controller && !controller.signal.aborted && owner.current.revision === revision
+      && latest.current.active && latest.current.sectionId === target.sectionId && latest.current.stepId === target.stepId
+    let sent: DocumentRecordingAdoption | undefined
+    try {
+      await workbench.flushPendingEdits(controller.signal)
+      if (!owns()) return
+      const source = workbench.getState().authoring
+      if (!source?.version || !source.fingerprint || !source.content || source.identity !== identity || source.dirty || source.saving || source.composing || source.restored || source.error) throw new Error('production-source-changed')
+      const expected = { identity, version: source.version }, inspection = await workbench.inspectDocumentAudio(target.assetId, expected, controller.signal)
+      if (!owns()) return
+      const canonical = { documentId: source.content.id, version: source.version, fingerprint: source.fingerprint }, previous = retry.current
+      sent = previous && previous.source.documentId === canonical.documentId && previous.source.version === canonical.version && previous.source.fingerprint === canonical.fingerprint && previous.stepId === target.stepId && previous.assetId === target.assetId && previous.sha256 === inspection.inspection.sha256
+        ? previous : { id: requestId(), source: canonical, stepId: target.stepId, assetId: target.assetId, sha256: inspection.inspection.sha256 }
+      retry.current = sent; submitted.current = sent
+      await workbench.adoptDocumentRecording(sent, expected, controller.signal)
+      if (!owns()) return
+      if (retry.current === sent) retry.current = undefined
+      setFailure(undefined)
+      if (reported.current !== sent.id) { reported.current = sent.id; latest.current.onAdopted() }
+    } catch (error) {
+      if (owns()) {
+        const confirmed = sent && applied(workbench.getState().authoring, sent)
+        if (confirmed && retry.current === sent) retry.current = undefined
+        setFailure(confirmed ? undefined : error instanceof Error ? error.message : 'recording-adoption-failed')
+      }
+    } finally {
+      if (request.current === controller) { request.current = undefined; if (current()) setBusy(false) }
+    }
+  }
+  const cancel = () => { owner.current.revision++; request.current?.abort(); request.current = undefined; setBusy(false); setFailure(undefined) }
+  return { assets, selected, choose, imported, revision: () => owner.current.revision, adopt, cancel, busy, failure, adopted }
+}

package/src/voice-clone-messages.ts

@@ -0,0 +1,92 @@
+import type { VoiceCloneStatus } from '@lincyaw/kernel'
+import type { Locale } from './messages.ts'
+import { WorkspaceServerError } from './workspace-client.ts'
+
+// A Latin name or number inside Chinese text takes a space on each side that does not meet full-width punctuation.
+const spaced = (text: string, after = true) => `${/^[A-Za-z0-9]/.test(text) ? ' ' : ''}${text}${after && /[A-Za-z0-9]$/.test(text) ? ' ' : ''}`
+const clock = (ms: number) => `${String(Math.floor(ms / 60000)).padStart(2, '0')}:${String(Math.floor(ms / 1000) % 60).padStart(2, '0')}`
+
+const zh = {
+  open: '复刻音色…', title: '复刻音色', cloned: '复刻音色', close: '关闭', cancel: '取消',
+  description: '用一个人的录音训练出一个合成音色。需要本人授权，并亲口读一遍授权声明。',
+  voice: '音色名称', voiceHint: (volcengine: boolean): string => (volcengine
+    ? '在火山引擎控制台购买的音色槽位（以 S_ 开头），或者给按量付费的音色起一个名字（字母开头，至少 8 个字母或数字）。'
+    : '给这个音色起一个名字，只用字母、数字、“.”、“-”和“_”。'),
+  voiceInvalid: '名称只能包含字母、数字、“.”、“-”和“_”，并以字母或数字开头。',
+  speaker: '说话人', speakerHint: '录音里是谁的声音。', scope: '用途', scopeHint: '这个音色可以用在哪里，会写进授权记录。', defaultScope: '本工作区讲义的配音',
+  statement: '授权声明录音', statementHint: '请说话人本人读出上面的授权声明。', statementText: (speaker: string, scope: string) => `我是${spaced(speaker, false)}。我授权用我的声音训练一个合成音色，只用于${spaced(scope, false)}。`,
+  someone: '（说话人的名字）', statementLabel: '授权声明',
+  passageLabel: '可以朗读的段落', passage: '今天我们从一个简单的问题开始：一张图片是怎样一步一步生成出来的？先看最基本的想法，再看它为什么有效，最后用几个例子把它们连起来。请用平时讲课的语气，自然地读下去。',
+  sample: '声音样本', sampleHint: '10 到 30 秒，只有说话人一个人，环境安静。可以读上面这段。',
+  sampleLength: (seconds: number) => `样本长 ${seconds.toFixed(0)} 秒。10 到 30 秒的录音效果最好。`,
+  record: '录音', stop: '停止录音', choose: '选择音频文件', listen: '试听', stopListening: '停止试听', clear: '清除',
+  empty: '尚未录制或选择', preparing: '正在处理录音…', seconds: (seconds: number) => `${seconds.toFixed(1)} 秒`,
+  decodeFailed: '无法读取这段音频。请换一个文件，或重新录制。',
+  train: '开始训练', use: '使用这个音色',
+  confirmTitle: '确认训练这个音色？', confirmHint: '授权记录会先保存在本机的运营者目录中，然后把样本发送给语音服务训练。',
+  costs: (provider: string, volcengine: boolean) => (volcengine
+    ? `训练和之后的合成都按${spaced(provider)}的价格计费。按量付费的音色在第一次合成（包括试听）时扣费，之后就不能再训练。`
+    : `训练和之后的合成按${spaced(provider)}的价格计费。`),
+  confirm: '确认训练',
+  state: (status: VoiceCloneStatus, waited: number) => status.state === 'ready'
+    ? `训练完成${status.trainingsLeft === undefined ? '' : `，这个音色还可以再训练 ${status.trainingsLeft} 次`}。选择“使用这个音色”回到音色设置。`
+    : status.state === 'failed' ? '训练失败。请换一段更清楚的样本后重试。'
+      : status.state === 'training' ? `正在训练… 已等待 ${clock(waited)}` : '语音服务暂时找不到这次训练，请稍后查看。',
+  failures: {
+    notAllowed: '运营者尚未允许使用复刻音色，请让运营者在工作区设置中开启。',
+    busy: '语音服务正忙，请稍后重试。', tooLarge: '录音太大，请缩短到 30 秒左右。', format: '语音服务不接受这种音频格式，请重新录制。',
+    unsupported: '当前语音服务不支持复刻音色。请在“设置 → 语音服务”中选择支持它的服务。',
+    failed: '无法开始训练。录音已保留，请稍后重试。',
+  },
+}
+
+type VoiceCloneMessages = typeof zh
+
+const en: VoiceCloneMessages = {
+  open: 'Voice Cloning…', title: 'Voice Cloning', cloned: 'cloned voice', close: 'Close', cancel: 'Cancel',
+  description: 'Train a synthetic voice from recordings of one person. They must agree, and read the consent statement aloud themselves.',
+  voice: 'Voice name', voiceHint: (volcengine: boolean) => (volcengine
+    ? 'A voice slot bought in the Volcengine console (it starts with S_), or a name for a pay-as-you-go voice (a letter first, at least 8 letters or digits).'
+    : 'A name for the voice: letters, digits, “.”, “-”, and “_” only.'),
+  voiceInvalid: 'Use letters, digits, “.”, “-”, and “_”, starting with a letter or digit.',
+  speaker: 'Speaker', speakerHint: 'Whose voice this is.', scope: 'Use', scopeHint: 'Where this voice may be used; it goes into the consent record.', defaultScope: 'the voiceover of this workspace’s documents',
+  statement: 'Consent statement recording', statementHint: 'The speaker reads the consent statement above aloud.', statementText: (speaker: string, scope: string) => `I am ${speaker}. I agree that my voice is used to train a synthetic voice, only for ${scope}.`,
+  someone: '(the speaker’s name)', statementLabel: 'Consent statement',
+  passageLabel: 'A passage to read', passage: 'Today we start from a simple question: how is a picture made, one step after another? First the basic idea, then why it works, and finally a few examples that tie it together. Read it the way you would speak in class, at an easy pace.',
+  sample: 'Voice sample', sampleHint: '10 to 30 seconds of the speaker alone, somewhere quiet. Reading the passage above works well.',
+  sampleLength: (seconds: number) => `The sample is ${seconds.toFixed(0)} seconds long. Recordings of 10 to 30 seconds work best.`,
+  record: 'Record', stop: 'Stop Recording', choose: 'Choose Audio File', listen: 'Play Sample', stopListening: 'Stop Sample', clear: 'Clear',
+  empty: 'Nothing recorded or chosen yet', preparing: 'Preparing the recording…', seconds: (seconds: number) => `${seconds.toFixed(1)} s`,
+  decodeFailed: 'Couldn’t read this audio. Choose another file, or record again.',
+  train: 'Start Training', use: 'Use This Voice',
+  confirmTitle: 'Train this voice?', confirmHint: 'The consent record is saved first, in the operator directory on this machine; then the sample is sent to the voice service for training.',
+  costs: (provider: string, volcengine: boolean) => (volcengine
+    ? `Training and every later voiceover are charged at ${provider}’s prices. A pay-as-you-go voice is charged when it first generates voiceover, listening included, and can’t be trained again after that.`
+    : `Training and later voiceover are charged at ${provider}’s prices.`),
+  confirm: 'Train',
+  state: (status: VoiceCloneStatus, waited: number) => status.state === 'ready'
+    ? `Trained${status.trainingsLeft === undefined ? '' : `; it can be trained ${status.trainingsLeft} more times`}. Choose Use This Voice to return to the voice settings.`
+    : status.state === 'failed' ? 'Training failed. Try again with a clearer sample.'
+      : status.state === 'training' ? `Training… ${clock(waited)} so far` : 'The voice service can’t find this training yet. Check again later.',
+  failures: {
+    notAllowed: 'The operator has not allowed cloned voices yet. Ask them to turn cloned voices on in the workspace settings.',
+    busy: 'The voice service is busy. Try again shortly.', tooLarge: 'The recording is too large. Keep it to about 30 seconds.', format: 'The voice service doesn’t accept this audio format. Record again.',
+    unsupported: 'The current voice service doesn’t support Voice Cloning. Choose one that does in Settings → Voice Service.',
+    failed: 'Couldn’t start training. The recordings are kept; try again shortly.',
+  },
+}
+
+export const VOICE_CLONE_MESSAGES: Record<Locale, VoiceCloneMessages> = { 'zh-CN': zh, en }
+
+export function cloneFailure(error: unknown, locale: Locale): string {
+  const t = VOICE_CLONE_MESSAGES[locale].failures
+  const status = error instanceof WorkspaceServerError ? error.status : 0
+  const message = error instanceof Error ? error.message : String(error)
+  if (status === 403 && /cloned voices are off|not allowed/.test(message)) return t.notAllowed
+  if (status === 429) return t.busy
+  if (status === 413) return t.tooLarge
+  if (status === 415) return t.format
+  if (status === 400 && /cannot (?:clone|train cloned) voices/.test(message)) return t.unsupported
+  console.warn(`presmium: voice cloning failed: ${message}`)
+  return t.failed
+}

package/src/voice-drafts.ts

@@ -0,0 +1,89 @@
+import { isRecord } from '@lincyaw/kernel'
+import type { VoiceSource } from '@lincyaw/kernel'
+import type { DocumentVoiceScope } from './document-voices.ts'
+import type { WorkspaceClient } from './workspace-client.ts'
+
+export interface VoiceDraft { version: string, scope: DocumentVoiceScope, source: VoiceSource | null, replaceOverrides: boolean, rateInput?: string }
+export type VoiceDraftStorageStatus = 'available' | 'unavailable' | 'corrupt'
+interface StoredDraft { draft?: VoiceDraft, status: VoiceDraftStorageStatus, unreadable?: string }
+const drafts = new WeakMap<WorkspaceClient, Map<string, StoredDraft>>()
+const keyOf = (identity: string, stepId: string) => JSON.stringify([identity, stepId])
+const storageKey = (key: string) => `presmium.voice-draft.v2:${key}`
+
+/** Only safe shape is checked here; current source IDs, assets and supported values are rechecked on apply. */
+function valid(value: unknown): value is VoiceDraft {
+  if (!isRecord(value) || typeof value.version !== 'string' || typeof value.replaceOverrides !== 'boolean' || !isRecord(value.scope) || value.rateInput !== undefined && typeof value.rateInput !== 'string') return false
+  const scope = value.scope
+  if (!(scope.kind === 'document' || scope.kind === 'page' && typeof scope.sectionId === 'string' || scope.kind === 'step' && typeof scope.stepId === 'string' || scope.kind === 'steps' && Array.isArray(scope.stepIds) && scope.stepIds.every(id => typeof id === 'string'))) return false
+  const source = value.source
+  if (source === null) return true
+  if (!isRecord(source)) return false
+  if (source.type === 'none') return true
+  if (source.type === 'recording') return typeof source.assetId === 'string'
+  if (source.type !== 'tts' || !isRecord(source.voice)) return false
+  const voice = source.voice
+  return typeof voice.voice === 'string' && (voice.engine === undefined || typeof voice.engine === 'string') && (voice.rate === undefined || typeof voice.rate === 'number' && Number.isFinite(voice.rate)) && (voice.style === undefined || typeof voice.style === 'string')
+}
+function store(client: WorkspaceClient): Map<string, StoredDraft> {
+  let known = drafts.get(client)
+  if (!known) drafts.set(client, known = new Map())
+  return known
+}
+function load(client: WorkspaceClient, key: string): StoredDraft {
+  const known = store(client), previous = known.get(key)
+  if (previous) return previous
+  const entry: StoredDraft = { status: 'available' }
+  known.set(key, entry)
+  try {
+    const raw = sessionStorage.getItem(storageKey(key))
+    if (raw !== null) {
+      entry.unreadable = raw
+      const value: unknown = JSON.parse(raw)
+      if (!valid(value)) { entry.status = 'corrupt'; return entry }
+      entry.draft = value
+      delete entry.unreadable
+    }
+  } catch { entry.status = entry.unreadable === undefined ? 'unavailable' : 'corrupt' }
+  return entry
+}
+
+export function readVoiceDraft(client: WorkspaceClient, identity: string, stepId: string): VoiceDraft | undefined {
+  const value = load(client, keyOf(identity, stepId)).draft
+  return value && structuredClone(value)
+}
+
+/** Corrupt storage is left untouched on read; a later write preserves its raw text in one recovery slot. */
+export function voiceDraftStorageStatus(client: WorkspaceClient, identity: string, stepId: string): VoiceDraftStorageStatus {
+  return load(client, keyOf(identity, stepId)).status
+}
+
+/** Returns whether the browser also kept the draft for a reload. */
+export function keepVoiceDraft(client: WorkspaceClient, identity: string, stepId: string, value: VoiceDraft): boolean {
+  if (!valid(value)) throw new Error('voice-draft-invalid')
+  const key = keyOf(identity, stepId), entry = load(client, key)
+  entry.draft = structuredClone(value)
+  try {
+    if (entry.unreadable !== undefined) sessionStorage.setItem(`${storageKey(key)}:unreadable`, entry.unreadable)
+    sessionStorage.setItem(storageKey(key), JSON.stringify(entry.draft))
+    entry.status = 'available'; delete entry.unreadable
+    return true
+  } catch { entry.status = 'unavailable'; return false }
+}
+
+/** A late acknowledgement cannot clear newer memory or persisted input. Failure keeps memory for retry. */
+export function clearVoiceDraft(client: WorkspaceClient, identity: string, stepId: string, expected?: VoiceDraft): boolean {
+  const key = keyOf(identity, stepId), entry = load(client, key)
+  if (expected && JSON.stringify(entry.draft) !== JSON.stringify(expected)) return false
+  try {
+    const raw = sessionStorage.getItem(storageKey(key))
+    if (expected && raw !== null) {
+      let persisted: unknown
+      try { persisted = JSON.parse(raw) } catch { entry.status = 'corrupt'; entry.unreadable = raw; return false }
+      if (!valid(persisted)) { entry.status = 'corrupt'; entry.unreadable = raw; return false }
+      if (JSON.stringify(persisted) !== JSON.stringify(expected)) return false
+    }
+    sessionStorage.removeItem(storageKey(key))
+    delete entry.draft; delete entry.unreadable; entry.status = 'available'
+    return true
+  } catch { entry.status = 'unavailable'; return false }
+}