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

package/src/panels/VoiceCloneDialog.tsx

@@ -0,0 +1,152 @@
+import { useEffect, useRef, useState, useSyncExternalStore } from 'react'
+import type { SpeechEngineInfo, VoiceCloneStatus } from '@lincyaw/kernel'
+import { AudioRecording, recordingUnavailable } from '../audio-recording.ts'
+import { AUDIO_RECORDING_MESSAGES } from '../audio-recording-messages.ts'
+import { toWav } from '../audio-wav.ts'
+import type { WavAudio } from '../audio-wav.ts'
+import { Audition } from '../audition.ts'
+import type { AuditionState } from '../audition.ts'
+import { PmButton, PmDialog, PmField, PmInput, PmNotice } from '../components.tsx'
+import { useWorkbench, useWorkbenchState } from '../context.tsx'
+import { cloneFailure, VOICE_CLONE_MESSAGES } from '../voice-clone-messages.ts'
+
+type Take = WavAudio & { name: string }
+
+/** One recording of the clone form: from the microphone or a file, kept as WAV so every provider takes it. */
+function RecordingSlot({ label, hint, value, disabled, onChange }: { label: string, hint: string, value?: Take, disabled: boolean, onChange(value?: Take): void }) {
+  const workbench = useWorkbench(), locale = useWorkbenchState(state => state.locale)
+  const t = VOICE_CLONE_MESSAGES[locale], r = AUDIO_RECORDING_MESSAGES[locale]
+  const [recording] = useState(() => new AudioRecording())
+  const state = useSyncExternalStore(recording.subscribe, recording.snapshot)
+  const [unavailable] = useState(recordingUnavailable)
+  const [preparing, setPreparing] = useState(false), [failure, setFailure] = useState<string>()
+  const [listening, setListening] = useState<AuditionState>({ status: 'idle' })
+  const audition = useRef<Audition>(), file = useRef<HTMLInputElement>(null), mounted = useRef(true)
+  useEffect(() => () => { mounted.current = false; recording.dispose(); audition.current?.dispose() }, [recording])
+  const accept = async (blob: Blob, name: string) => {
+    setPreparing(true); setFailure(undefined); audition.current?.stop()
+    try {
+      const wav = await toWav(blob)
+      if (mounted.current) onChange({ ...wav, name })
+    } catch { if (mounted.current) setFailure(t.decodeFailed) }
+    finally { if (mounted.current) setPreparing(false) }
+  }
+  // A finished take becomes the slot's WAV; the take itself is not kept.
+  const take = state.candidate?.file
+  useEffect(() => {
+    if (!take) return
+    void accept(take, r.title).finally(() => recording.discard())
+  }, [take])
+  const capturing = ['requesting', 'recording', 'stopping'].includes(state.phase)
+  const start = () => {
+    setFailure(undefined)
+    void recording.start(async () => {
+      workbench.stopAuditions()
+      await workbench.pausePlayback()
+      return workbench.registerAudioCapture(() => recording.stop())
+    })
+  }
+  const listen = () => {
+    if (!value) return
+    if (!audition.current) {
+      const player = audition.current = new Audition(workbench)
+      player.subscribe(() => { if (mounted.current) setListening(player.snapshot()) })
+    }
+    if (listening.status === 'playing' || listening.status === 'loading') audition.current.stop()
+    else void audition.current.play(async () => ({ audio: value.blob }))
+  }
+  const status = state.phase === 'requesting' ? r.requesting : state.phase === 'recording' ? r.recording : preparing ? t.preparing : value ? `${value.name} · ${t.seconds(value.seconds)}` : t.empty
+  return <PmField label={label} hint={hint} group>
+    <span className="pm-ui-hint" role="status">{status}</span>
+    {(state.error || unavailable) && !capturing && <PmNotice tone="warn">{r.failures[state.error ?? unavailable!] ?? r.failures['recording-failed']}</PmNotice>}
+    {failure && <PmNotice tone="danger">{failure}</PmNotice>}
+    <div className="pmw-voice__actions">
+      {state.phase === 'recording' ? <PmButton small variant="primary" onClick={() => recording.stop()}>{t.stop}</PmButton>
+        : <PmButton small disabled={disabled || capturing || preparing || Boolean(unavailable)} onClick={start}>{t.record}</PmButton>}
+      <PmButton small disabled={disabled || capturing || preparing} onClick={() => file.current?.click()}>{t.choose}</PmButton>
+      {value && <PmButton small icon="audio" disabled={capturing || preparing} loading={listening.status === 'loading'} onClick={listen}>{listening.status === 'playing' ? t.stopListening : t.listen}</PmButton>}
+      {value && <PmButton small disabled={disabled || capturing || preparing} onClick={() => { audition.current?.stop(); onChange(undefined) }}>{t.clear}</PmButton>}
+    </div>
+    <input ref={file} hidden type="file" accept="audio/*,.wav,.mp3,.m4a,.ogg,.webm" onChange={(event) => {
+      const chosen = event.currentTarget.files?.[0]
+      event.currentTarget.value = ''
+      if (chosen) void accept(chosen, chosen.name)
+    }} />
+  </PmField>
+}
+
+interface Props { directory: string, engine: SpeechEngineInfo, lang: string, onUse(voice: string): void, onClose(): void }
+
+/**
+ * Trains a cloned voice: who speaks, their consent read aloud, a sample; then a confirmation that names the cost,
+ * since the provider charges for training; then the training, polled until it ends. The server registers the
+ * consent before it sends anything to the provider.
+ */
+export function VoiceCloneDialog({ directory, engine, lang, onUse, onClose }: Props) {
+  const workbench = useWorkbench(), locale = useWorkbenchState(state => state.locale), t = VOICE_CLONE_MESSAGES[locale]
+  const volcengine = engine.id === 'volcengine'
+  const [voice, setVoice] = useState(''), [speaker, setSpeaker] = useState(''), [scope, setScope] = useState(t.defaultScope)
+  const [statement, setStatement] = useState<Take>(), [sample, setSample] = useState<Take>()
+  const [confirming, setConfirming] = useState(false), [busy, setBusy] = useState(false), [failure, setFailure] = useState<string>()
+  const [status, setStatus] = useState<VoiceCloneStatus>(), [waited, setWaited] = useState(0)
+  const request = useRef<AbortController>()
+  useEffect(() => () => request.current?.abort(), [])
+  const name = voice.trim()
+  const nameInvalid = Boolean(name) && !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(name)
+  const trained = status?.state === 'ready'
+  const locked = busy || trained
+  const ready = Boolean(name && !nameInvalid && speaker.trim() && scope.trim() && statement && sample) && !locked
+  const train = async () => {
+    const controller = new AbortController()
+    request.current?.abort(); request.current = controller
+    setConfirming(false); setBusy(true); setFailure(undefined); setStatus(undefined); setWaited(0)
+    const pause = (ms: number) => new Promise<void>((resolve, reject) => {
+      const timer = setTimeout(resolve, ms)
+      controller.signal.addEventListener('abort', () => { clearTimeout(timer); reject(controller.signal.reason) }, { once: true })
+    })
+    try {
+      let answer = await workbench.client.cloneVoice(directory, { engine: engine.id, voice: name, lang, speaker: speaker.trim(), scope: scope.trim(), sample: sample!.blob, statement: statement!.blob }, controller.signal)
+      setStatus(answer)
+      const started = Date.now()
+      // Training takes seconds to minutes; poll every three seconds for at most ten minutes.
+      while (answer.state === 'training' && Date.now() - started < 10 * 60_000) {
+        await pause(3000)
+        answer = await workbench.client.readCloneStatus(directory, name, engine.id, controller.signal)
+        setStatus(answer); setWaited(Date.now() - started)
+      }
+    } catch (error) { if (!controller.signal.aborted) setFailure(cloneFailure(error, locale)) }
+    finally { if (request.current === controller) { request.current = undefined; setBusy(false) } }
+  }
+  const close = () => { request.current?.abort(); onClose() }
+  return <>
+    <PmDialog open label={t.title} closeLabel={t.close} description={t.description} onClose={close} footer={<>
+      <PmButton onClick={close}>{t.close}</PmButton>
+      {trained ? <PmButton variant="primary" onClick={() => onUse(name)}>{t.use}</PmButton>
+        : <PmButton variant="primary" loading={busy} disabled={!ready} onClick={() => setConfirming(true)}>{t.train}</PmButton>}
+    </>}>
+      <div className="pmw-voice__form">
+        {failure && <PmNotice tone="danger">{failure}</PmNotice>}
+        {status && <PmNotice tone={status.state === 'ready' ? 'ok' : status.state === 'failed' ? 'danger' : 'accent'}><span role="status">{t.state(status, waited)}</span></PmNotice>}
+        <PmInput label={t.voice} hint={t.voiceHint(volcengine)} error={nameInvalid ? t.voiceInvalid : undefined} value={voice} maxLength={128} spellCheck={false} autoComplete="off" disabled={locked} onChange={event => setVoice(event.target.value)} />
+        <PmInput label={t.speaker} hint={t.speakerHint} value={speaker} maxLength={80} disabled={locked} onChange={event => setSpeaker(event.target.value)} />
+        <PmInput label={t.scope} hint={t.scopeHint} value={scope} maxLength={200} disabled={locked} onChange={event => setScope(event.target.value)} />
+        <PmField label={t.statementLabel}><p className="pmw-voice__sample">{t.statementText(speaker.trim() || t.someone, scope.trim() || t.defaultScope)}</p></PmField>
+        <RecordingSlot label={t.statement} hint={t.statementHint} value={statement} disabled={locked} onChange={setStatement} />
+        <PmField label={t.passageLabel}><p className="pmw-voice__sample">{t.passage}</p></PmField>
+        <RecordingSlot label={t.sample} hint={t.sampleHint} value={sample} disabled={locked} onChange={setSample} />
+        {sample && (sample.seconds < 10 || sample.seconds > 30) && <PmNotice tone="warn">{t.sampleLength(sample.seconds)}</PmNotice>}
+      </div>
+    </PmDialog>
+    <PmDialog open={confirming} label={t.confirmTitle} closeLabel={t.cancel} description={t.confirmHint} onClose={() => setConfirming(false)} footer={<>
+      <PmButton onClick={() => setConfirming(false)}>{t.cancel}</PmButton>
+      <PmButton variant="primary" onClick={() => void train()}>{t.confirm}</PmButton>
+    </>}>
+      <div className="pmw-voice__form">
+        <PmField label={t.voice}><span>{name}</span></PmField>
+        <PmField label={t.speaker}><span>{speaker.trim()}</span></PmField>
+        <PmField label={t.scope}><span>{scope.trim()}</span></PmField>
+        <PmNotice tone="warn">{t.costs(engine.provider, volcengine)}</PmNotice>
+      </div>
+    </PmDialog>
+  </>
+}

package/src/panels/VoicePreviewDialog.tsx

@@ -0,0 +1,74 @@
+import { useEffect, useRef, useState } from 'react'
+import type { VoicePreviewQuote } from '@lincyaw/kernel'
+import { Audition } from '../audition.ts'
+import type { AuditionState } from '../audition.ts'
+import { PmButton, PmDialog, PmField, PmNotice } from '../components.tsx'
+import { useWorkbench, useWorkbenchState } from '../context.tsx'
+import { VOICE_MESSAGES, voiceFailure } from '../voice-messages.ts'
+import { voiceSnapshotCurrent } from '../voice-snapshot.ts'
+import type { VoiceSnapshot } from '../voice-snapshot.ts'
+
+/** A quote authorizes one explicit audition, never a setting change or automatic synthesis. */
+export function VoicePreviewDialog({ quote, snapshot, onClose, onRecheck }: { quote: VoicePreviewQuote, snapshot: VoiceSnapshot, onClose(): void, onRecheck?(): void }) {
+  const workbench = useWorkbench(), locale = useWorkbenchState(state => state.locale), t = VOICE_MESSAGES[locale]
+  const current = useWorkbenchState(() => voiceSnapshotCurrent(workbench, snapshot))
+  const audition = useRef<Audition>(), owner = useRef(0), closed = useRef(false)
+  const [state, setState] = useState<AuditionState>({ status: 'idle' }), [error, setError] = useState<string>(), [invalid, setInvalid] = useState(false)
+  const matches = quote.revision === snapshot.revision && quote.source.documentId === snapshot.source.documentId && quote.source.version === snapshot.source.version && quote.source.fingerprint === snapshot.source.fingerprint
+
+  useEffect(() => {
+    const version = ++owner.current, player = new Audition(workbench)
+    closed.current = false; audition.current = player
+    setState(player.snapshot()); setError(undefined); setInvalid(false)
+    const stop = player.subscribe(() => { if (owner.current === version && !closed.current) setState(player.snapshot()) })
+    return () => { owner.current++; stop(); player.dispose(); if (audition.current === player) audition.current = undefined }
+  }, [workbench, quote, snapshot])
+
+  useEffect(() => {
+    if (current && matches) return
+    setInvalid(true); audition.current?.stop()
+  }, [current, matches])
+
+  const close = () => { if (closed.current) return; closed.current = true; owner.current++; audition.current?.dispose(); onClose() }
+  const recheck = () => { audition.current?.stop(); onRecheck?.() }
+  const confirm = () => {
+    const player = audition.current, version = owner.current
+    if (!player || closed.current || invalid || !matches || !voiceSnapshotCurrent(workbench, snapshot)) return
+    setError(undefined)
+    void player.play(async signal => {
+      try {
+        if (!voiceSnapshotCurrent(workbench, snapshot)) throw new Error('voice-context-changed')
+        const answer = await workbench.client.previewVoice(snapshot.directory, { revision: quote.revision, source: quote.source, voice: quote.voice, mode: quote.mode, ...quote.target ? { target: quote.target } : {}, quote: quote.quote, confirmed: true }, signal)
+        signal.throwIfAborted()
+        if (owner.current !== version || closed.current || !voiceSnapshotCurrent(workbench, snapshot) || answer.revision !== quote.revision
+          || answer.source.documentId !== quote.source.documentId || answer.source.version !== quote.source.version || answer.source.fingerprint !== quote.source.fingerprint) throw new Error('voice-context-changed')
+        return { audio: answer.audio }
+      } catch (failure) {
+        if (owner.current === version && !closed.current && !signal.aborted) {
+          setError(voiceFailure(failure, locale))
+          if (failure instanceof Error && ['voice-context-changed', 'voice-source-changed', 'voice-source-unavailable', 'voice-revision-changed', 'voice-preview-changed'].includes(failure.message)) setInvalid(true)
+        }
+        throw failure
+      }
+    })
+  }
+  const changed = invalid || !current || !matches, active = state.status === 'loading' || state.status === 'playing'
+  return <PmDialog open label={quote.mode === 'step' ? t.currentScript : t.standard} description={t.previewHint} closeLabel={t.close} onClose={close} footer={<>
+    <PmButton small onClick={close}>{t.close}</PmButton>
+    {changed && onRecheck && <PmButton small onClick={recheck}>{t.recheck}</PmButton>}
+    {active ? <PmButton small onClick={() => audition.current?.stop()}>{t.stop}</PmButton>
+      : <PmButton small variant="accent" disabled={changed || !audition.current} onClick={confirm}>{t.confirmPreview}</PmButton>}
+  </>}>
+    <div className="pmw-operation">
+    <PmField label={t.provider}><span>{quote.provider}</span></PmField>
+    <PmField label={t.currentVoice}><span>{quote.voice.voice}</span></PmField>
+    {quote.target && <PmField label={t.scope}><span>{snapshot.ir.sections.find(page => page.id === quote.target?.section)?.title} · {t.step(snapshot.ir.sections.findIndex(page => page.id === quote.target?.section) + 1, quote.target.step + 1)}</span></PmField>}
+    <PmField label={quote.mode === 'step' ? t.currentScript : t.sampleText}><p className="pmw-voice__sample">{quote.text}</p></PmField>
+    <PmNotice>{quote.cached ? t.cachedPreview : t.disclosure(quote.provider, quote.local)}</PmNotice>
+    {changed && <PmNotice tone="warn">{t.changed}</PmNotice>}
+    {state.status === 'loading' && <PmNotice>{t.auditionLoading}</PmNotice>}
+    {state.status === 'playing' && <PmNotice tone="accent">{t.auditioning}</PmNotice>}
+    {(error || state.status === 'failed') && <PmNotice tone="danger">{error ?? voiceFailure(new Error(state.error), locale)}</PmNotice>}
+    </div>
+  </PmDialog>
+}

package/src/panels/VoiceScopeField.tsx

@@ -0,0 +1,30 @@
+import type { TeachingDocument } from '@lincyaw/kernel'
+import { PmButton, PmField, PmSegmented } from '../components.tsx'
+import { useWorkbenchState } from '../context.tsx'
+import type { DocumentVoiceScope } from '../document-voices.ts'
+import { PRODUCTION_MESSAGES } from '../production-messages.ts'
+import { VOICE_MESSAGES } from '../voice-messages.ts'
+
+/** Scope selection uses authored IDs and stays available before runtime compilation. */
+export function VoiceScopeField({ document, stepId, value, disabled, onChange }: { document: TeachingDocument, stepId: string, value: DocumentVoiceScope, disabled?: boolean, onChange(value: DocumentVoiceScope): void }) {
+  const locale = useWorkbenchState(state => state.locale), t = VOICE_MESSAGES[locale], p = PRODUCTION_MESSAGES[locale]
+  const sectionId = document.steps[stepId]?.sectionId
+  return <>
+    <PmField label={t.scope} group>
+      <PmSegmented label={t.scope} value={value.kind} options={(['step', 'steps', 'page', 'document'] as const).map(kind => ({ value: kind, label: p.scopeShort[kind] }))} disabled={disabled} onChange={kind => {
+        if (kind === 'document') onChange({ kind })
+        else if (kind === 'page' && sectionId) onChange({ kind, sectionId })
+        else if (kind === 'step') onChange({ kind, stepId })
+        else if (kind === 'steps') onChange({ kind, stepIds: [stepId] })
+      }} />
+    </PmField>
+    {value.kind === 'steps' && <PmField label={t.selectedSteps} group hint={t.selected(value.stepIds.length)} error={value.stepIds.length ? undefined : p.selectSteps}>
+      <div className="pmw-voice__steps">
+        {document.sectionOrder.flatMap((id, page) => document.sections[id]!.stepOrder.map((selected, index) => {
+          const checked = value.stepIds.includes(selected)
+          return <PmButton key={selected} small aria-label={`${document.sections[id]!.title} · ${t.step(page + 1, index + 1)}`} aria-pressed={checked} disabled={disabled} onClick={() => onChange({ kind: 'steps', stepIds: checked ? value.stepIds.filter(id => id !== selected) : [...value.stepIds, selected] })}>{page + 1} · {index + 1}</PmButton>
+        }))}
+      </div>
+    </PmField>}
+  </>
+}

package/src/panels/VoiceoverDialog.tsx

@@ -0,0 +1,216 @@
+import { useEffect, useMemo, useRef, useState } from 'react'
+import { speechEngineId } from '@lincyaw/kernel'
+import type { TeachingDocument, VoiceoverJob, VoiceoverSnapshot, VoiceScope } from '@lincyaw/kernel'
+import { PmButton, PmDialog, PmField, PmNotice } from '../components.tsx'
+import { useWorkbench, useWorkbenchState } from '../context.tsx'
+import { documentVoiceStepIds, resolveDocumentStepVoice } from '../document-voices.ts'
+import type { DocumentVoiceScope } from '../document-voices.ts'
+import { VOICE_MESSAGES, voiceFailure } from '../voice-messages.ts'
+import { prepareVoiceSnapshot, runtimeVoiceScope, voiceSnapshotCurrent } from '../voice-snapshot.ts'
+import type { VoiceSnapshot } from '../voice-snapshot.ts'
+import { isAgentChanging } from '../workbench.ts'
+import { VoiceScopeField } from './VoiceScopeField.tsx'
+
+interface CheckedVoice { snapshot: VoiceSnapshot, document: TeachingDocument }
+interface OwnedJob { directory: string }
+const NO_JOBS: VoiceoverJob[] = []
+const active = (job: VoiceoverJob) => ['queued', 'running', 'cancelling'].includes(job.state)
+const sameSource = (a: VoiceoverSnapshot['source'], b: VoiceoverSnapshot['source']) => a.documentId === b.documentId && a.version === b.version && a.fingerprint === b.fingerprint
+const jobStamp = (jobs: VoiceoverJob[]) => jobs.map(job => `${job.id}:${job.sequence}`).join(',')
+function coversScope(job: VoiceScope, selected: VoiceScope): boolean {
+  if (job.kind === 'document') return true
+  if (selected.kind === 'document') return false
+  if (selected.kind === 'page') return job.kind === 'page' && job.section === selected.section
+  const targets = selected.kind === 'step' ? [selected.target] : selected.targets
+  if (job.kind === 'page') return targets.every(target => target.section === job.section)
+  const generated = job.kind === 'step' ? [job.target] : job.targets
+  return targets.every(target => generated.some(value => value.section === target.section && value.step === target.step && value.binding === target.binding))
+}
+
+/** Visible author jobs use acknowledged source versions; polling never starts generation. */
+export function VoiceoverDialog({ stepId, onClose }: { stepId: string, onClose(): void }) {
+  const workbench = useWorkbench(), locale = useWorkbenchState(state => state.locale), t = VOICE_MESSAGES[locale]
+  const source = useWorkbenchState(state => state.authoring)
+  const serviceVersion = useWorkbenchState(state => state.voiceServiceVersion)
+  const jobs = useWorkbenchState(state => state.voiceoverJobs) ?? NO_JOBS
+  const jobsFailure = useWorkbenchState(state => state.voiceoverJobsFailure)
+  const readOnly = useWorkbenchState(state => Boolean(state.authoring?.loading || state.authoring?.composing) || isAgentChanging(state))
+  const [scope, setScope] = useState<DocumentVoiceScope>({ kind: 'step', stepId })
+  const [checked, setChecked] = useState<CheckedVoice>(), [status, setStatus] = useState<VoiceoverSnapshot>()
+  const [loading, setLoading] = useState(true), [submitting, setSubmitting] = useState(false), [cancelling, setCancelling] = useState<string>()
+  const [changed, setChanged] = useState(false), [error, setError] = useState<string>(), [attempt, setAttempt] = useState(0)
+  const life = useRef<AbortController>(), read = useRef<AbortController>(), mutation = useRef<AbortController>(), generation = useRef(0), starting = useRef(false)
+  const checkedRef = useRef<CheckedVoice>(), statusJobs = useRef(''), owned = useRef(new Map<string, OwnedJob>()), closing = useRef(false), directoryRef = useRef(workbench.getState().document)
+
+  const cancelOwned = () => {
+    for (const [id, { directory }] of owned.current) {
+      const job = workbench.getState().voiceoverJobs?.find(value => value.id === id)
+      if (!job || active(job)) void workbench.client.cancelVoiceover(directory, id, AbortSignal.timeout(5000)).catch(() => {})
+    }
+    owned.current.clear()
+  }
+  useEffect(() => {
+    life.current = new AbortController(); closing.current = false
+    directoryRef.current = workbench.getState().document
+    setScope({ kind: 'step', stepId })
+    return () => { closing.current = true; generation.current++; life.current?.abort(); read.current?.abort(); mutation.current?.abort(); cancelOwned() }
+  }, [workbench, stepId, source?.identity])
+  useEffect(() => workbench.observeVoiceoverJobs(), [workbench, source?.identity])
+
+  useEffect(() => {
+    const controller = new AbortController(), version = ++generation.current
+    read.current?.abort(); read.current = controller
+    const signal = AbortSignal.any([controller.signal, life.current!.signal])
+    checkedRef.current = undefined; setChecked(undefined); setStatus(undefined); setLoading(true); setError(undefined)
+    void (async () => {
+      try {
+        workbench.stopAuditions()
+        const snapshot = await prepareVoiceSnapshot(workbench, stepId, signal)
+        const document = workbench.getDocument(snapshot.identity)
+        if (!document) throw new Error('voice-context-changed')
+        const answer = await workbench.client.readVoiceover(snapshot.directory, signal)
+        signal.throwIfAborted()
+        if (generation.current !== version || closing.current) return
+        if (!voiceSnapshotCurrent(workbench, snapshot) || answer.revision !== snapshot.revision || !sameSource(answer.source, snapshot.source)) throw new Error('voice-context-changed')
+        const value = { snapshot, document }
+        checkedRef.current = value; statusJobs.current = jobStamp(answer.jobs)
+        setChecked(value); setStatus(answer); setChanged(false)
+      } catch (failure) {
+        if (generation.current === version && !signal.aborted && !closing.current) setError(voiceFailure(failure, locale))
+      } finally { if (generation.current === version && !signal.aborted && !closing.current) setLoading(false) }
+    })()
+    return () => controller.abort()
+  }, [workbench, stepId, attempt, source?.identity, serviceVersion])
+
+  useEffect(() => workbench.subscribe(() => {
+    const value = checkedRef.current
+    if (!value || voiceSnapshotCurrent(workbench, value.snapshot)) return
+    mutation.current?.abort(); starting.current = false; setSubmitting(false); setChanged(true)
+  }), [workbench])
+
+  const hasActive = jobs.some(active)
+  useEffect(() => {
+    const value = checkedRef.current, stamp = jobStamp(jobs)
+    if (!value || !voiceSnapshotCurrent(workbench, value.snapshot) || stamp === statusJobs.current) return
+    const controller = new AbortController(), signal = AbortSignal.any([controller.signal, life.current!.signal])
+    void (async () => {
+      try {
+        const answer = await workbench.client.readVoiceover(value.snapshot.directory, signal)
+        signal.throwIfAborted()
+        if (closing.current || checkedRef.current !== value) return
+        if (voiceSnapshotCurrent(workbench, value.snapshot) && answer.revision === value.snapshot.revision && sameSource(answer.source, value.snapshot.source)) {
+          statusJobs.current = stamp; setStatus(answer)
+        }
+        else setChanged(true)
+      } catch (failure) { if (!signal.aborted && !closing.current) setError(voiceFailure(failure, locale)) }
+    })()
+    return () => controller.abort()
+  }, [workbench, jobs, checked])
+
+  const selection = useMemo(() => {
+    if (!checked || !status) return undefined
+    try {
+      const ids = documentVoiceStepIds(checked.document, scope), wanted = new Set(ids)
+      const steps = status.steps.filter(value => {
+        const page = checked.snapshot.ir.sections.find(page => page.id === value.target.section)
+        return page?.stepIds?.[value.target.step] !== undefined && wanted.has(page.stepIds[value.target.step]!)
+      })
+      const pages = new Set(ids.map(id => checked.document.steps[id]!.sectionId))
+      const unbound = scope.kind === 'page' || scope.kind === 'document' ? (status.unboundByPage ?? []).filter(value => pages.has(value.section)) : []
+      const units = [...steps, ...unbound]
+      const cached = units.reduce((sum, value) => sum + value.cached, 0)
+      const missing = units.filter(value => value.state === 'missing').reduce((sum, value) => sum + value.utterances - value.cached, 0)
+      const blocked = units.filter(value => value.state === 'blocked').reduce((sum, value) => sum + value.utterances - value.cached, 0)
+      const providers = status.capability.providers.filter(provider => ids.some(id => {
+        const value = resolveDocumentStepVoice(checked.document, id).value
+        return value?.type === 'tts' && provider.id === speechEngineId(value.voice.engine ?? status.capability.defaultEngine ?? '')
+      }))
+      const text = ids.flatMap(id => checked.document.steps[id]!.narrationIds.map(narrationId => checked.document.narrations[narrationId]!.content.map(node => node.type === 'text' ? node.text : node.type === 'pronunciation' ? node.spoken : '').join(''))).join('\n\n')
+      const voices = [...new Map(ids.flatMap(id => { const value = resolveDocumentStepVoice(checked.document, id).value; return value?.type === 'tts' ? [[JSON.stringify(value.voice), value.voice] as const] : [] })).values()]
+      const silent = ids.filter(id => resolveDocumentStepVoice(checked.document, id).value?.type === 'none').length
+      const unset = ids.some(id => resolveDocumentStepVoice(checked.document, id).value === undefined)
+      const reasons = [...new Set(units.filter(value => value.state === 'blocked').flatMap(value => value.reason && !(value.reason === 'voice-unset' && silent && !unset) ? [value.reason] : []))]
+      return { cached, missing, blocked, providers, voices, silent, reasons, text, hasUnbound: !unbound.length && (status.unboundByPage ?? []).some(value => pages.has(value.section) && value.utterances > 0) }
+    } catch { return undefined }
+  }, [checked, status, scope])
+  const hasScopeJob = useMemo(() => {
+    if (!checked) return false
+    try {
+      const selected = runtimeVoiceScope(checked.snapshot, scope)
+      return jobs.some(job => (active(job) || job.state === 'done' && job.completed > 0)
+        && sameSource(job.source, checked.snapshot.source) && job.revision === checked.snapshot.revision && coversScope(job.scope, selected))
+    } catch { return false }
+  }, [checked, jobs, scope])
+  const chooseScope = (value: DocumentVoiceScope) => { mutation.current?.abort(); starting.current = false; setSubmitting(false); setScope(value); setError(undefined) }
+  const close = () => {
+    if (closing.current) return
+    closing.current = true; generation.current++; life.current?.abort(); read.current?.abort(); mutation.current?.abort(); cancelOwned(); onClose()
+  }
+  const start = async () => {
+    const value = checkedRef.current
+    if (!value || !selection?.missing || !selection.providers.length || starting.current || changed || readOnly || closing.current || !voiceSnapshotCurrent(workbench, value.snapshot)) return
+    const controller = new AbortController(), version = generation.current
+    mutation.current?.abort(); mutation.current = controller
+    const signal = AbortSignal.any([controller.signal, life.current!.signal])
+    starting.current = true; setSubmitting(true); setError(undefined)
+    try {
+      workbench.stopAuditions()
+      await workbench.pausePlayback(); signal.throwIfAborted()
+      if (!voiceSnapshotCurrent(workbench, value.snapshot)) throw new Error('voice-context-changed')
+      const runtimeScope = runtimeVoiceScope(value.snapshot, scope)
+      const job = await workbench.client.startVoiceover(value.snapshot.directory, { revision: value.snapshot.revision, source: value.snapshot.source, scope: runtimeScope, confirmed: true }, signal)
+      if (closing.current || signal.aborted || generation.current !== version) { if (active(job)) void workbench.client.cancelVoiceover(value.snapshot.directory, job.id, AbortSignal.timeout(5000)).catch(() => {}); return }
+      if (!sameSource(job.source, value.snapshot.source) || job.revision !== value.snapshot.revision || !voiceSnapshotCurrent(workbench, value.snapshot)) throw new Error('voice-context-changed')
+      owned.current.set(job.id, { directory: value.snapshot.directory })
+      workbench.rememberVoiceoverJob(value.snapshot.directory, job)
+    } catch (failure) { if (!signal.aborted && !closing.current && generation.current === version) setError(voiceFailure(failure, locale)) }
+    finally { if (mutation.current === controller) { starting.current = false; if (!closing.current) setSubmitting(false) } }
+  }
+  const cancel = async (job: VoiceoverJob) => {
+    const directory = owned.current.get(job.id)?.directory ?? checkedRef.current?.snapshot.directory ?? directoryRef.current
+    if (directory === undefined || cancelling || closing.current) return
+    const signal = life.current!.signal
+    setCancelling(job.id); setError(undefined)
+    try {
+      const answer = await workbench.client.cancelVoiceover(directory, job.id, signal)
+      signal.throwIfAborted()
+      if (closing.current) return
+      workbench.rememberVoiceoverJob(directory, answer)
+    } catch (failure) { if (!signal.aborted && !closing.current) setError(voiceFailure(failure, locale)) }
+    finally { if (!signal.aborted && !closing.current) setCancelling(undefined) }
+  }
+  const unavailable = !status?.capability.available && (!selection?.cached || Boolean(selection.missing || selection.blocked))
+  const failure = error ?? (jobsFailure ? voiceFailure(new Error(jobsFailure), locale) : undefined)
+  const capabilityFailure = unavailable && selection?.voices.length && status ? voiceFailure(new Error(status.capability.reason), locale) : undefined
+  const warnings = [...new Set([...(capabilityFailure ? [capabilityFailure] : []), ...(selection?.reasons ?? []).map(reason => voiceFailure(new Error(reason), locale))])].filter(message => message !== failure)
+  const cancelOnClose = submitting || [...owned.current.keys()].some(id => { const job = jobs.find(value => value.id === id); return !job || active(job) })
+  const closeLabel = cancelOnClose ? t.cancelAndClose : t.close
+  return <PmDialog open label={t.generation} closeLabel={closeLabel} onClose={close} footer={<>
+    <PmButton small onClick={close}>{closeLabel}</PmButton>
+    <PmButton small loading={loading} disabled={submitting} onClick={() => setAttempt(value => value + 1)}>{changed ? t.recheck : t.refresh}</PmButton>
+    <PmButton small variant="accent" loading={submitting} disabled={loading || changed || readOnly || hasActive || !selection?.missing || !selection.providers.length || !status?.capability.available} onClick={() => void start()}>{t.confirmGenerate}</PmButton>
+  </>}>
+    <div className="pmw-operation">
+    {(source?.content || checked?.document) && <VoiceScopeField document={checked?.document ?? source!.content!} stepId={stepId} value={scope} disabled={loading || submitting || readOnly} onChange={chooseScope} />}
+    {loading && <PmNotice>{t.refreshing}</PmNotice>}
+    {changed && <PmNotice tone="warn">{t.changed}</PmNotice>}
+    {failure && <PmNotice tone="danger">{failure}</PmNotice>}
+    {status && selection && <>
+      {(selection.missing > 0 || selection.blocked > 0) && <PmNotice>{t.generationSummary(selection.missing, selection.blocked)}</PmNotice>}
+      {!changed && !hasScopeJob && !selection.missing && !selection.blocked && selection.cached > 0 && <PmNotice tone="ok">{t.cacheReady}</PmNotice>}
+      {!selection.missing && !selection.cached && !selection.blocked && <PmNotice>{t.noScript}</PmNotice>}
+      {selection.hasUnbound && <PmNotice tone="warn">{t.unboundScript}</PmNotice>}
+      {selection.silent > 0 && <PmNotice>{t.silentScope(selection.silent)}</PmNotice>}
+      {warnings.map(message => <PmNotice tone="warn" key={message}>{message}</PmNotice>)}
+      {selection.voices.map(voice => <PmField key={JSON.stringify(voice)} label={t.currentVoice}><span>{voice.voice}{voice.engine ? ` · ${voice.engine}` : ''}{voice.rate !== undefined ? ` · ${t.rate}: ${voice.rate}` : ''}{voice.style ? ` · ${t.style}: ${voice.style}` : ''}</span></PmField>)}
+      {selection.missing > 0 && selection.providers.map(provider => <PmNotice key={provider.id}>{t.disclosure(provider.provider, provider.local)}</PmNotice>)}
+      {selection.text && <PmField label={t.generationScript}><p className="pmw-voice__sample">{selection.text}</p></PmField>}
+    </>}
+    {jobs.map(job => <div className="pmw-voice__status" key={job.id}>
+      <span>{t.scopes[job.scope.kind]} · {t.jobs[job.state]} · {t.progress(job.completed, job.total, job.failed)}{source?.version !== job.source.version || source?.fingerprint !== job.source.fingerprint ? ` · ${t.oldVersion}` : ''}</span>
+      {active(job) && <PmButton small loading={cancelling === job.id} disabled={job.state === 'cancelling'} onClick={() => void cancel(job)}>{t.cancelJob}</PmButton>}
+      {job.error && <span>{voiceFailure(new Error(job.error), locale)}</span>}
+    </div>)}
+    </div>
+  </PmDialog>
+}

package/src/places.ts

@@ -0,0 +1,102 @@
+import { irBlocks } from '@lincyaw/kernel'
+import type { IRDocument, PreviewAnchor, ReviewChange, SourcePos, TeachingDocument } from '@lincyaw/kernel'
+
+const CHANGED_PLACES = 100
+
+/** A place in the document (a section, or a block of it) and its source. */
+export interface PlaceWithSource {
+  section: string
+  block?: string
+  source: SourcePos
+}
+
+/** The smallest section or block whose source spans the line of the file; a block wins over a section of the same span. */
+export function findPlaceAtLine(doc: IRDocument, file: string, line: number): PlaceWithSource | undefined {
+  let found: PlaceWithSource | undefined
+  let span = Number.POSITIVE_INFINITY
+  for (const section of doc.sections) {
+    const places: PlaceWithSource[] = [{ section: section.id, source: section.source }, ...[...irBlocks(section.blocks)].map(block => ({ section: section.id, block: block.id, source: block.source }))]
+    for (const place of places) {
+      const { source } = place
+      const end = source.endLine ?? source.line
+      if (source.file !== file || line < source.line || line > end) continue
+      if (end - source.line < span || (end - source.line === span && place.block)) {
+        found = place
+        span = end - source.line
+      }
+    }
+  }
+  return found
+}
+
+/** The source of a section, or of a block in it; a block that is not in the section gives the section's. */
+export function findPlaceSource(doc: IRDocument, section: string, block?: string): PlaceWithSource | undefined {
+  const found = doc.sections.find(s => s.id === section)
+  if (!found) return undefined
+  if (!block) return { section, source: found.source }
+  const inner = [...irBlocks(found.blocks)].find(b => b.id === block)
+  return inner ? { section, block, source: inner.source } : { section, source: found.source }
+}
+
+/** The lines of the new file a unified diff added or changed; a removal marks the line now in its place. */
+function changedLines(diff: string): Set<number> {
+  const lines = new Set<number>()
+  let line = 0
+  for (const text of diff.split('\n')) {
+    const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(text)
+    if (hunk) line = Number(hunk[1])
+    else if (line === 0) continue
+    else if (text.startsWith('+')) lines.add(line++)
+    else if (text.startsWith('-')) lines.add(line)
+    else if (text.startsWith(' ')) line++
+  }
+  return lines
+}
+
+/** The blocks (or sections) of the document whose source the changes touched, in the order of the changes. */
+export function changedPlaces(doc: IRDocument, changes: readonly ReviewChange[]): PreviewAnchor[] {
+  const places = new Map<string, PreviewAnchor>()
+  for (const change of changes) {
+    if (!change.diff || change.kind === 'deleted') continue
+    for (const line of changedLines(change.diff)) {
+      const place = findPlaceAtLine(doc, change.path, line)
+      if (place) places.set(`${place.section}\0${place.block ?? ''}`, { section: place.section, ...place.block ? { block: place.block } : {} })
+    }
+  }
+  return [...places.values()].slice(0, CHANGED_PLACES)
+}
+
+/**
+ * The places that differ between two versions of a document: each block whose content changed or that is new (with
+ * its page), each page whose title changed or that is new, and the block of each step whose narration or settings
+ * changed, at most CHANGED_PLACES.
+ */
+export function changedBlocks(before: TeachingDocument, after: TeachingDocument): PreviewAnchor[] {
+  const places: PreviewAnchor[] = []
+  const visit = (section: string, ids: readonly string[]) => {
+    for (const id of ids) {
+      const block = after.blocks[id]
+      if (!block) continue
+      if (JSON.stringify(block) !== JSON.stringify(before.blocks[id])) places.push({ section, block: id })
+      if ('children' in block && Array.isArray(block.children)) visit(section, block.children as string[])
+    }
+  }
+  for (const id of after.sectionOrder) {
+    const section = after.sections[id]
+    if (!section) continue
+    if (before.sections[id]?.title !== section.title) places.push({ section: id })
+    visit(id, section.children)
+  }
+  // A changed step, or a changed narration of it, shows at the block the step plays (else at its page).
+  const seen = new Set(places.map(place => `${place.section}\0${place.block ?? ''}`))
+  for (const step of Object.values(after.steps)) {
+    const narrated = step.narrationIds.some(id => JSON.stringify(after.narrations[id]) !== JSON.stringify(before.narrations[id]))
+    if (!narrated && JSON.stringify(step) === JSON.stringify(before.steps[step.id])) continue
+    // the component the step plays, where its narration shows, else any block it shows
+    const block = step.visuals.find(visual => after.blocks[visual.blockId]?.type === 'component')?.blockId ?? step.visuals.find(visual => visual.visible)?.blockId ?? step.visuals[0]?.blockId
+    const place = { section: step.sectionId, ...block ? { block } : {} }
+    const key = `${place.section}\0${place.block ?? ''}`
+    if (!seen.has(key)) { seen.add(key); places.push(place) }
+  }
+  return places.slice(0, CHANGED_PLACES)
+}