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

package/src/approvals.tsx

@@ -0,0 +1,60 @@
+import { useEffect, useState } from 'react'
+import type { ApprovalRequest } from '@lincyaw/kernel'
+import { PmButton, PmNotice, PmPopover } from './components.tsx'
+import { useMessages, useWorkbench } from './context.tsx'
+import { WorkspaceServerError } from './workspace-client.ts'
+
+interface Pending { id: string, request: ApprovalRequest }
+
+/**
+ * The host's operations waiting for the author, such as an external MCP client's import: shown only while one is
+ * pending, answered here as in the viewer's "Approvals". The host times them out; a late answer is reported, not retried.
+ */
+export function WorkbenchApprovals({ density = 'compact' }: { density?: 'compact' | 'touch' }) {
+  const { client } = useWorkbench()
+  const t = useMessages()
+  const [pending, setPending] = useState<Pending[]>([])
+  const [open, setOpen] = useState(false)
+  const [answering, setAnswering] = useState<string>()
+  const [notice, setNotice] = useState<string>()
+  useEffect(() => client.subscribeApprovals((event) => {
+    if (event.type === 'reset') setPending([])
+    else if (event.type === 'settled') setPending(list => list.filter(item => item.id !== event.id))
+    else setPending(list => list.some(item => item.id === event.id) ? list : [...list, { id: event.id, request: event.request }])
+  }), [client])
+  useEffect(() => { if (!pending.length) setOpen(false) }, [pending.length])
+  if (!pending.length) return null
+  const answer = (id: string, allow: boolean) => {
+    setAnswering(id); setNotice(undefined)
+    void client.answerApproval(id, allow).then(
+      () => setPending(list => list.filter(item => item.id !== id)),
+      (error: unknown) => {
+        if (error instanceof WorkspaceServerError && error.status === 404) {
+          setPending(list => list.filter(item => item.id !== id))
+          setNotice(t.approvalExpired)
+        } else setNotice(t.approvalFailed)
+      },
+    ).finally(() => setAnswering(current => current === id ? undefined : current))
+  }
+  return (
+    <PmPopover open={open} onOpenChange={setOpen} label={t.approvalsTitle} name="pmw-approvals" trigger={
+      <PmButton variant="accent" density={density}>{t.approvals(pending.length)}</PmButton>
+    }>
+      <h2 className="pmw-approvals__heading">{t.approvalsTitle}</h2>
+      <ul className="pmw-approvals__list">
+        {pending.map(({ id, request }) => (
+          <li key={id} className="pmw-approvals__item" data-approval={id}>
+            <p className="pmw-approvals__title">{request.title}</p>
+            <p className="pmw-muted">{t.approvalFrom(t.approvalOrigin[request.from] ?? t.approvalOtherOrigin)}</p>
+            {request.detail && <p className="pmw-approvals__detail">{request.detail}</p>}
+            <div className="pmw-approvals__actions">
+              <PmButton density={density} disabled={answering === id} onClick={() => answer(id, false)}>{t.approvalDeny}</PmButton>
+              <PmButton variant="primary" density={density} loading={answering === id ? true : undefined} disabled={answering === id} onClick={() => answer(id, true)}>{t.approvalAllow}</PmButton>
+            </div>
+          </li>
+        ))}
+      </ul>
+      {notice && <PmNotice tone="warn">{notice}</PmNotice>}
+    </PmPopover>
+  )
+}

package/src/assistant-mascot.ts

@@ -0,0 +1,62 @@
+// What the kitten beside the assistant does, from what the assistant is doing: asking the author to approve
+// something, reading the document it was asked about, writing into it, thinking, just finished, or idle (sitting,
+// then lying down, then asleep the longer nothing happens).
+import { useEffect, useState } from 'react'
+import type { MascotAction } from '@lincyaw/design/mascot'
+import { useWorkbench, useWorkbenchState } from './context.tsx'
+
+const DONE_MS = 2400
+const LOAF_MS = 90_000
+const SLEEP_MS = 300_000
+
+export interface AssistantActivity {
+  /** The assistant's turn is running. */
+  running: boolean
+  /** It holds a review of the open document: still working in it, and how many changes it has made. */
+  review?: { running: boolean, changes: number }
+  /** Operations wait for the author's approval. */
+  approvals: number
+  /** How long ago the assistant last stopped, in milliseconds (Infinity if it has not run). */
+  sinceStopped: number
+}
+
+export function assistantMascotAction(a: AssistantActivity): MascotAction {
+  if (a.approvals > 0) return 'ask'
+  if (a.review?.running) return a.review.changes > 0 ? 'write' : 'read'
+  if (a.running) return 'think'
+  if (a.review && a.review.changes > 0) return 'ask'
+  if (a.sinceStopped < DONE_MS) return 'done'
+  if (a.sinceStopped > SLEEP_MS) return 'sleep'
+  if (a.sinceStopped > LOAF_MS) return 'loaf'
+  return 'sit'
+}
+
+/** The kitten's action for the assistant, given whether its turn is running; follows the workbench's review and the
+ * operations waiting for approval, and moves on by itself as time passes. */
+export function useAssistantMascot(running: boolean): MascotAction {
+  const { client } = useWorkbench()
+  // two plain values rather than one object, so the selection compares equal while nothing changes
+  const reviewRunning = useWorkbenchState(state => state.review?.running)
+  const changes = useWorkbenchState(state => state.review?.changes.length)
+  const review = reviewRunning === undefined ? undefined : { running: reviewRunning, changes: changes ?? 0 }
+  const [approvals, setApprovals] = useState<string[]>([])
+  const [stoppedAt, setStoppedAt] = useState<number>(() => performance.now() - LOAF_MS / 2)
+  const [, setNow] = useState(0)
+  const busy = running || Boolean(review?.running)
+  useEffect(() => client.subscribeApprovals(event => {
+    if (event.type === 'reset') setApprovals([])
+    else if (event.type === 'settled') setApprovals(list => list.filter(id => id !== event.id))
+    else setApprovals(list => list.includes(event.id) ? list : [...list, event.id])
+  }), [client])
+  useEffect(() => { if (!busy) setStoppedAt(performance.now()) }, [busy])
+  // Wake up at the next moment the idle kitten changes what it does.
+  const since = performance.now() - stoppedAt
+  useEffect(() => {
+    if (busy) return
+    const next = [DONE_MS, LOAF_MS, SLEEP_MS].find(ms => ms > since)
+    if (next === undefined) return
+    const timer = setTimeout(() => setNow(performance.now()), next - since + 50)
+    return () => clearTimeout(timer)
+  }, [busy, since])
+  return assistantMascotAction({ running, review, approvals: approvals.length, sinceStopped: busy ? 0 : since })
+}

package/src/audio-recording-messages.ts

@@ -0,0 +1,44 @@
+import type { Locale } from './messages.ts'
+
+const zh = {
+  trim: '录音区间', captionReview: '字幕尚未按裁剪后的录音对齐，请核对。',
+  title: '原音频', source: '本步原音', choose: '选择已保存音频', removedAudio: '原音频已移除', adopt: '采用为本步配音', adopted: '已采用', retryAdoption: '重试采用', cancelAdoption: '取消采用', adoptionSourceChanged: '文稿已更新，请重试。', adoptionFailed: '无法采用这段音频，请重试。', start: '开始录音', stop: '停止录音', cancel: '取消', cancelTake: '放弃本次录音', rerecord: '重新录音',
+  audition: '试听', stopAudition: '停止试听', save: '保存为音频素材', saving: '正在保存原音…', retry: '重试', discard: '放弃候选',
+  ready: '原音候选 · 尚未保存', imported: '已保存为音频素材', requesting: '正在等待麦克风许可', recording: '正在录音', stopping: '正在完成录音…',
+  cancelSave: '取消保存', currentSource: '文稿尚未保存，请先完成当前输入。', saveFailed: '无法保存原音。录音已保留，请重试。',
+  discardTitle: '放弃这份原音？', discardHint: '未保存的录音将被删除，已保存的音频素材不受影响。', keep: '保留原音',
+  failures: {
+    'recording-context': '当前环境无法访问麦克风。请使用安全连接，或继续导入音频。',
+    'recording-unsupported': '此浏览器无法录制受支持的音频格式。仍可导入音频。',
+    'recording-permission': '麦克风未获许可。请检查浏览器权限后重试。',
+    'recording-device': '没有可用的麦克风。', 'recording-device-busy': '麦克风当前无法使用，请检查设备后重试。',
+    'recording-device-unsupported': '当前浏览器或设备不支持此录音请求。仍可导入音频。',
+    'recording-device-ended': '麦克风连接已结束，已保留录到的原音。',
+    'recording-failed': '无法完成本次录音。已有原音仍保留。', 'recording-empty': '本次没有录到音频，请重试。',
+    'recording-size': '录音超过 16 MiB。请缩短录音后重试，已有候选仍保留。',
+    'recording-duration': '已达到十分钟录制上限，录音已停止。',
+    'audition-audio': '原音无法播放。请检查音频或重新录制。', 'audition-request': '无法开始试听，请重试。',
+  } as Record<string, string>,
+}
+type Messages = typeof zh
+const en: Messages = {
+  trim: 'Recording range', captionReview: 'Captions are not aligned to the trimmed recording. Review them.',
+  title: 'Original audio', source: 'Original audio for this step', choose: 'Choose Saved Audio', removedAudio: 'Original audio was removed', adopt: 'Use as Step Voiceover', adopted: 'Applied', retryAdoption: 'Retry', cancelAdoption: 'Cancel', adoptionSourceChanged: 'The document changed. Retry.', adoptionFailed: 'Couldn’t use this audio. Try again.', start: 'Start Recording', stop: 'Stop Recording', cancel: 'Cancel', cancelTake: 'Discard This Recording', rerecord: 'Record Again',
+  audition: 'Play Sample', stopAudition: 'Stop Sample', save: 'Save as Audio Asset', saving: 'Saving original audio…', retry: 'Retry', discard: 'Discard Candidate',
+  ready: 'Original audio candidate · Not saved', imported: 'Saved as an audio asset', requesting: 'Waiting for microphone permission', recording: 'Recording', stopping: 'Finishing recording…',
+  cancelSave: 'Cancel', currentSource: 'Finish and save the current document input first.', saveFailed: 'Couldn’t save the original audio. The recording is kept; try again.',
+  discardTitle: 'Discard this original audio?', discardHint: 'The recording that is not saved will be deleted. Saved audio assets are kept.', keep: 'Keep Original Audio',
+  failures: {
+    'recording-context': 'Microphone access is unavailable here. Use a secure connection or import an audio file.',
+    'recording-unsupported': 'This browser cannot record a supported audio format. Audio file import is still available.',
+    'recording-permission': 'Microphone permission was not granted. Check browser permissions and retry.',
+    'recording-device': 'No microphone is available.', 'recording-device-busy': 'The microphone is unavailable. Check the device and retry.',
+    'recording-device-unsupported': 'This browser or device does not support the recording request. Audio file import is still available.',
+    'recording-device-ended': 'The microphone disconnected. Recorded audio is retained.',
+    'recording-failed': 'Couldn’t finish this recording. Any previous original audio is kept.', 'recording-empty': 'No audio was recorded. Retry.',
+    'recording-size': 'The recording exceeds 16 MiB. Record a shorter take; any previous candidate is retained.',
+    'recording-duration': 'The ten-minute recording limit was reached. Recording stopped.',
+    'audition-audio': 'This audio could not be played. Check it or record again.', 'audition-request': 'Couldn’t start listening. Try again.',
+  },
+}
+export const AUDIO_RECORDING_MESSAGES: Record<Locale, Messages> = { 'zh-CN': zh, en }

package/src/audio-recording.ts

@@ -0,0 +1,192 @@
+/** A microphone take remains an in-memory candidate until the author saves its original bytes. */
+export interface RecordingCandidate { file: File, recordedAt: string, elapsedMs: number, assetId?: string }
+export interface AudioRecordingState {
+  phase: 'idle' | 'requesting' | 'recording' | 'stopping' | 'ready' | 'failed'
+  candidate?: RecordingCandidate
+  elapsedMs: number
+  error?: string
+}
+const MAX_BYTES = 16 << 20
+const MAX_DURATION_MS = 10 * 60_000
+const MIME_TYPES = ['audio/webm;codecs=opus', 'audio/ogg;codecs=opus', 'audio/mp4']
+
+export function recordingUnavailable(): string | undefined {
+  if (!globalThis.isSecureContext || !navigator.mediaDevices?.getUserMedia) return 'recording-context'
+  if (typeof MediaRecorder === 'undefined' || !MIME_TYPES.some(type => MediaRecorder.isTypeSupported(type))) return 'recording-unsupported'
+  return undefined
+}
+
+interface Take {
+  recorder: MediaRecorder
+  stream: MediaStream
+  chunks: Blob[]
+  bytes: number
+  started: number
+  recordedAt: string
+  discard: boolean
+  error?: string
+  interval?: ReturnType<typeof setInterval>
+  release: () => void
+  ended: () => void
+}
+
+export class AudioRecording {
+  #state: AudioRecordingState = { phase: 'idle', elapsedMs: 0 }
+  readonly #listeners = new Set<() => void>()
+  #generation = 0
+  #disposed = false
+  #take?: Take
+  #release?: () => void
+  #warning = false
+  readonly #beforeUnload = (event: BeforeUnloadEvent) => { event.preventDefault(); event.returnValue = '' }
+
+  snapshot = (): AudioRecordingState => this.#state
+  subscribe = (listener: () => void): (() => void) => { if (this.#disposed) return () => {}; this.#listeners.add(listener); return () => { this.#listeners.delete(listener) } }
+  #set(state: AudioRecordingState): void {
+    if (this.#disposed) return
+    this.#state = state
+    const warning = ['requesting', 'recording', 'stopping'].includes(state.phase) || Boolean(state.candidate && !state.candidate.assetId)
+    if (warning !== this.#warning) {
+      this.#warning = warning
+      if (warning) window.addEventListener('beforeunload', this.#beforeUnload)
+      else window.removeEventListener('beforeunload', this.#beforeUnload)
+    }
+    for (const listener of this.#listeners) listener()
+  }
+  #settle(error?: string): void {
+    this.#set({ phase: error ? 'failed' : this.#state.candidate ? 'ready' : 'idle', candidate: this.#state.candidate, elapsedMs: this.#state.candidate?.elapsedMs ?? 0, ...error ? { error } : {} })
+  }
+
+  async start(prepare: () => Promise<() => void>): Promise<void> {
+    if (this.#disposed || this.#take || this.#state.phase === 'requesting') return
+    const unavailable = recordingUnavailable()
+    if (unavailable) { this.#settle(unavailable); return }
+    const generation = ++this.#generation
+    this.#set({ ...this.#state, phase: 'requesting', error: undefined })
+    let stream: MediaStream | undefined
+    let release: (() => void) | undefined
+    try {
+      release = await prepare()
+      if (generation !== this.#generation) { release(); return }
+      this.#release = release
+      stream = await navigator.mediaDevices.getUserMedia({ audio: { channelCount: { ideal: 1 } }, video: false })
+      if (generation !== this.#generation) { stream.getTracks().forEach(track => track.stop()); return }
+      const mimeType = MIME_TYPES.find(type => MediaRecorder.isTypeSupported(type))!
+      const recorder = new MediaRecorder(stream, { mimeType, audioBitsPerSecond: 128_000 })
+      const take: Take = {
+        recorder, stream, chunks: [], bytes: 0, started: performance.now(), recordedAt: new Date().toISOString(), discard: false,
+        release: () => { release?.(); if (this.#release === release) this.#release = undefined },
+        ended: () => { if (this.#take === take) this.stop('recording-device-ended') },
+      }
+      this.#take = take
+      recorder.ondataavailable = event => {
+        if (this.#take !== take || !event.data.size) return
+        take.chunks.push(event.data); take.bytes += event.data.size
+        if (take.bytes > MAX_BYTES) this.stop('recording-size')
+      }
+      recorder.onerror = () => { if (this.#take === take) this.stop('recording-failed') }
+      recorder.onstop = () => this.#finish(take)
+      for (const track of stream.getTracks()) track.addEventListener('ended', take.ended)
+      recorder.start(1000)
+      this.#set({ ...this.#state, phase: 'recording', elapsedMs: 0, error: undefined })
+      take.interval = setInterval(() => {
+        if (this.#take !== take || recorder.state !== 'recording') return
+        const elapsedMs = performance.now() - take.started
+        this.#set({ ...this.#state, elapsedMs })
+        if (elapsedMs >= MAX_DURATION_MS) this.stop('recording-duration')
+      }, 1000)
+    } catch (error) {
+      stream?.getTracks().forEach(track => track.stop())
+      release?.(); if (this.#release === release) this.#release = undefined
+      if (generation !== this.#generation) return
+      this.#take = undefined
+      const name = error instanceof DOMException ? error.name : ''
+      this.#settle(name === 'NotAllowedError' || name === 'SecurityError' ? 'recording-permission' : name === 'NotFoundError' ? 'recording-device' : name === 'NotReadableError' ? 'recording-device-busy' : name === 'NotSupportedError' ? 'recording-device-unsupported' : 'recording-failed')
+    }
+  }
+
+  stop(error?: string): void {
+    const take = this.#take
+    if (!take) {
+      if (this.#state.phase === 'requesting') { this.#generation++; this.#release?.(); this.#release = undefined; this.#settle(error) }
+      return
+    }
+    if (error) take.error ??= error
+    clearInterval(take.interval)
+    if (take.recorder.state !== 'inactive') {
+      this.#set({ ...this.#state, phase: 'stopping' })
+      try { take.recorder.stop() }
+      catch { take.error ??= 'recording-failed'; this.#finish(take) }
+    }
+    take.stream.getTracks().forEach(track => track.stop())
+    take.release()
+  }
+
+  #finish(take: Take): void {
+    if (this.#take !== take) return
+    this.#take = undefined
+    clearInterval(take.interval)
+    for (const track of take.stream.getTracks()) { track.removeEventListener('ended', take.ended); track.stop() }
+    take.recorder.ondataavailable = null; take.recorder.onstop = null; take.recorder.onerror = null
+    take.release()
+    if (take.discard) { this.#settle(); return }
+    if (take.error && this.#state.candidate) { this.#settle(take.error); return }
+    if (!take.bytes || take.bytes > MAX_BYTES) { this.#settle(take.bytes ? 'recording-size' : 'recording-empty'); return }
+    const mime = take.recorder.mimeType || take.chunks[0]!.type
+    const extension = mime.includes('ogg') ? 'ogg' : mime.includes('mp4') ? 'm4a' : 'webm'
+    const file = new File(take.chunks, `recording-${take.recordedAt.replace(/[:.]/g, '-')}.${extension}`, { type: mime })
+    this.#set({ phase: 'ready', candidate: { file, recordedAt: take.recordedAt, elapsedMs: performance.now() - take.started }, elapsedMs: performance.now() - take.started, ...take.error ? { error: take.error } : {} })
+  }
+
+  cancelTake(): void {
+    if (this.#take) this.#take.discard = true
+    this.stop()
+  }
+  imported(file: File, assetId: string): void {
+    if (this.#state.candidate?.file !== file) return
+    this.#set({ ...this.#state, candidate: { ...this.#state.candidate, assetId }, error: undefined })
+  }
+  forgetImport(assetId: string): void {
+    if (this.#state.candidate?.assetId !== assetId) return
+    this.#set({ ...this.#state, candidate: { ...this.#state.candidate, assetId: undefined } })
+  }
+  discard(): void {
+    this.cancelTake()
+    this.#set({ phase: 'idle', elapsedMs: 0 })
+  }
+
+  dispose(): void {
+    if (this.#disposed) return
+    this.#disposed = true
+    this.#generation++
+    const take = this.#take
+    if (take) { take.discard = true; this.stop(); this.#finish(take) }
+    this.#release?.(); this.#release = undefined
+    if (this.#warning) window.removeEventListener('beforeunload', this.#beforeUnload)
+    this.#warning = false
+    this.#state = { phase: 'idle', elapsedMs: 0 }
+    this.#listeners.clear()
+  }
+}
+
+const recordings = new WeakMap<object, Map<string, AudioRecording>>()
+/** Includes preparation and recorder finalization, when a playback lease alone cannot describe the take. */
+export function documentRecordingActive(owner: object): boolean {
+  return [...recordings.get(owner)?.values() ?? []].some(recording => ['requesting', 'recording', 'stopping'].includes(recording.snapshot().phase))
+}
+
+/** Volatile UI material, isolated by the real workspace/document identity; never a persisted source model. */
+export function documentRecording(owner: object, identity: string): AudioRecording {
+  let documents = recordings.get(owner)
+  if (!documents) { documents = new Map(); recordings.set(owner, documents) }
+  let recording = documents.get(identity)
+  if (!recording) { recording = new AudioRecording(); documents.set(identity, recording) }
+  return recording
+}
+
+export function disposeDocumentRecordings(owner: object): void {
+  const documents = recordings.get(owner)
+  recordings.delete(owner)
+  for (const recording of documents?.values() ?? []) recording.dispose()
+  documents?.clear()
+}

package/src/audio-wav.ts

@@ -0,0 +1,25 @@
+/** A recording or an audio file as 16-bit mono WAV, with its length. */
+export interface WavAudio { blob: Blob, seconds: number }
+
+/**
+ * Decodes any audio the browser plays (a microphone take in WebM, Ogg or MP4; an MP3, M4A or WAV file) and writes
+ * it as 16-bit mono WAV at `rate`: the one format every voice-cloning provider takes. Rendering through an offline
+ * context mixes the channels down and resamples, with no realtime audio and no permission.
+ */
+export async function toWav(source: Blob, rate = 24000): Promise<WavAudio> {
+  const decoded = await new OfflineAudioContext(1, 1, rate).decodeAudioData(await source.arrayBuffer())
+  const offline = new OfflineAudioContext(1, Math.max(1, Math.ceil(decoded.duration * rate)), rate)
+  const node = offline.createBufferSource()
+  node.buffer = decoded
+  node.connect(offline.destination)
+  node.start()
+  const samples = (await offline.startRendering()).getChannelData(0)
+  const wav = new DataView(new ArrayBuffer(44 + samples.length * 2))
+  const text = (at: number, value: string) => { for (let i = 0; i < value.length; i++) wav.setUint8(at + i, value.charCodeAt(i)) }
+  text(0, 'RIFF'); wav.setUint32(4, 36 + samples.length * 2, true); text(8, 'WAVE')
+  text(12, 'fmt '); wav.setUint32(16, 16, true); wav.setUint16(20, 1, true); wav.setUint16(22, 1, true)
+  wav.setUint32(24, rate, true); wav.setUint32(28, rate * 2, true); wav.setUint16(32, 2, true); wav.setUint16(34, 16, true)
+  text(36, 'data'); wav.setUint32(40, samples.length * 2, true)
+  for (let i = 0; i < samples.length; i++) wav.setInt16(44 + i * 2, Math.round(Math.max(-1, Math.min(1, samples[i]!)) * 32767), true)
+  return { blob: new Blob([wav.buffer], { type: 'audio/wav' }), seconds: decoded.duration }
+}

package/src/audio-waveform.ts

@@ -0,0 +1,110 @@
+/** Read-only peaks from decoded media, never a replacement for the lecture's timing plan. */
+export interface AudioWaveform {
+  readonly durationMs: number
+  readonly peaks: readonly number[]
+}
+
+const MAX_BYTES = 16 * 1024 * 1024
+const MAX_DURATION_MS = 10 * 60 * 1000
+const MAX_PENDING = 128
+const MAX_CACHED = 24
+const CONCURRENCY = 2
+
+interface Job {
+  key: string
+  durationMs: number
+  bins: number
+  load(signal: AbortSignal): Promise<Blob>
+  signal?: AbortSignal
+  unlisten(): void
+  resolve(value: AudioWaveform): void
+  reject(error: unknown): void
+}
+
+function aborted(): DOMException { return new DOMException('Waveform reading cancelled', 'AbortError') }
+
+async function decode(blob: Blob, durationMs: number, bins: number, signal: AbortSignal): Promise<AudioWaveform> {
+  signal.throwIfAborted()
+  if (!blob.size || blob.size > MAX_BYTES) throw new Error('waveform-size-limit')
+  if (typeof OfflineAudioContext !== 'function') throw new Error('waveform-decoder-unavailable')
+  const bytes = await blob.arrayBuffer()
+  signal.throwIfAborted()
+  // Offline decoding never starts an AudioContext destination or requests permission to play.
+  const context = new OfflineAudioContext(1, 1, 8000)
+  let audio: AudioBuffer
+  try { audio = await context.decodeAudioData(bytes) }
+  catch { signal.throwIfAborted(); throw new Error('waveform-invalid-audio') }
+  signal.throwIfAborted()
+  const decodedMs = audio.duration * 1000
+  if (!Number.isFinite(decodedMs) || decodedMs <= 0 || decodedMs > MAX_DURATION_MS) throw new Error('waveform-duration-limit')
+  // A materially different file must not draw a plausible waveform against the old plan's duration.
+  if (Math.abs(decodedMs - durationMs) > Math.max(100, durationMs * 0.01)) throw new Error('waveform-duration-changed')
+  const peaks = Array.from({ length: bins }, () => 0)
+  for (let channel = 0; channel < audio.numberOfChannels; channel++) {
+    const samples = audio.getChannelData(channel)
+    for (let index = 0; index < samples.length; index++) {
+      const bin = Math.min(bins - 1, Math.floor(index * bins / samples.length))
+      const sample = samples[index]!
+      if (!Number.isFinite(sample)) throw new Error('waveform-invalid-audio')
+      peaks[bin] = Math.max(peaks[bin]!, Math.min(1, Math.abs(sample)))
+    }
+  }
+  signal.throwIfAborted()
+  return Object.freeze({ durationMs: Math.round(decodedMs), peaks: Object.freeze(peaks) })
+}
+
+/** A visible production workspace owns this queue; closing it cancels reads and releases cached peaks. */
+export class AudioWaveforms {
+  readonly #queue: Job[] = []
+  readonly #active = new Set<AbortController>()
+  readonly #cache = new Map<string, AudioWaveform>()
+  #closed = false
+
+  /** key includes the confirmed plan and clip identity; media is fetched only after a queue slot is available. */
+  read(key: string, load: Job['load'], durationMs: number, signal?: AbortSignal, bins = 128): Promise<AudioWaveform> {
+    if (this.#closed || signal?.aborted) return Promise.reject(signal?.reason ?? aborted())
+    if (!Number.isFinite(durationMs) || durationMs <= 0 || durationMs > MAX_DURATION_MS) return Promise.reject(new Error('waveform-duration-limit'))
+    if (!Number.isInteger(bins) || bins < 16 || bins > 2048) return Promise.reject(new Error('waveform-bin-limit'))
+    const identity = JSON.stringify([key, durationMs, bins]), cached = this.#cache.get(identity)
+    if (cached) {
+      this.#cache.delete(identity); this.#cache.set(identity, cached)
+      return Promise.resolve(cached)
+    }
+    if (this.#queue.length >= MAX_PENDING) return Promise.reject(new Error('waveform-queue-limit'))
+    return new Promise((resolve, reject) => {
+      const cancel = () => {
+        const index = this.#queue.indexOf(job)
+        if (index < 0) return
+        this.#queue.splice(index, 1); job.unlisten(); reject(signal?.reason ?? aborted())
+      }
+      const job: Job = { key: identity, load, durationMs, bins, signal, resolve, reject, unlisten: () => signal?.removeEventListener('abort', cancel) }
+      signal?.addEventListener('abort', cancel, { once: true })
+      this.#queue.push(job); this.#pump()
+    })
+  }
+
+  dispose(): void {
+    this.#closed = true
+    for (const job of this.#queue.splice(0)) { job.unlisten(); job.reject(aborted()) }
+    for (const controller of this.#active) controller.abort(aborted())
+    this.#cache.clear()
+  }
+
+  #pump(): void {
+    while (!this.#closed && this.#active.size < CONCURRENCY && this.#queue.length) {
+      const job = this.#queue.shift()!
+      job.unlisten()
+      const controller = new AbortController(), signal = job.signal ? AbortSignal.any([controller.signal, job.signal]) : controller.signal
+      this.#active.add(controller)
+      void (async () => {
+        signal.throwIfAborted()
+        const value = await decode(await job.load(signal), job.durationMs, job.bins, signal)
+        signal.throwIfAborted()
+        if (this.#closed) throw aborted()
+        this.#cache.delete(job.key); this.#cache.set(job.key, value)
+        if (this.#cache.size > MAX_CACHED) this.#cache.delete(this.#cache.keys().next().value!)
+        return value
+      })().then(job.resolve, job.reject).finally(() => { this.#active.delete(controller); this.#pump() })
+    }
+  }
+}

package/src/audition.ts

@@ -0,0 +1,84 @@
+import type { Workbench } from './workbench.ts'
+import { speechFailureCode } from '@lincyaw/kernel'
+
+export interface AuditionState { status: 'idle' | 'loading' | 'playing' | 'failed', error?: string }
+export interface AuditionSource { audio: Blob | string }
+
+/** An explicit audio audition owns its request and media; formal playback owns the lecture clock. */
+export class Audition {
+  readonly #workbench: Workbench
+  readonly #listeners = new Set<() => void>()
+  readonly #unregister: () => void
+  #state: AuditionState = { status: 'idle' }
+  #version = 0
+  #request?: AbortController
+  #audio?: HTMLAudioElement
+  #objectUrl?: string
+  #disposed = false
+
+  constructor(workbench: Workbench) {
+    this.#workbench = workbench
+    this.#unregister = workbench.registerAudition(() => this.stop())
+  }
+
+  snapshot = (): AuditionState => this.#state
+  subscribe = (listener: () => void): (() => void) => { this.#listeners.add(listener); return () => { this.#listeners.delete(listener) } }
+  #set(state: AuditionState): void { this.#state = state; for (const listener of this.#listeners) listener() }
+
+  #release(): void {
+    this.#request?.abort()
+    this.#request = undefined
+    const audio = this.#audio
+    this.#audio = undefined
+    if (audio) { audio.onended = null; audio.onerror = null; audio.pause(); audio.removeAttribute('src'); audio.load() }
+    if (this.#objectUrl) URL.revokeObjectURL(this.#objectUrl)
+    this.#objectUrl = undefined
+  }
+
+  stop(): void {
+    this.#version++
+    this.#release()
+    if (!this.#disposed) this.#set({ status: 'idle' })
+  }
+
+  async play(produce: (signal: AbortSignal) => Promise<AuditionSource>): Promise<void> {
+    this.#workbench.stopAuditions()
+    if (this.#disposed) return
+    const version = this.#version
+    const request = new AbortController()
+    this.#request = request
+    const current = () => !this.#disposed && this.#version === version && !request.signal.aborted
+    this.#set({ status: 'loading' })
+    try {
+      await this.#workbench.pausePlayback(true)
+      if (!current()) return
+      const source = await produce(request.signal)
+      if (!current()) return
+      const audio = new Audio()
+      this.#audio = audio
+      audio.preload = 'auto'
+      audio.src = typeof source.audio === 'string' ? source.audio : this.#objectUrl = URL.createObjectURL(source.audio)
+      audio.onended = () => { if (current()) this.stop() }
+      audio.onerror = () => {
+        if (!current()) return
+        this.#release()
+        this.#set({ status: 'failed', error: 'audition-audio' })
+      }
+      await audio.play()
+      if (!current()) { audio.pause(); return }
+      this.#set({ status: 'playing' })
+    } catch (error) {
+      if (!current()) return
+      this.#release()
+      this.#set({ status: 'failed', error: speechFailureCode(error) ?? (error instanceof Error && error.message.startsWith('preview-playback-') ? error.message : 'audition-request') })
+    }
+  }
+
+  dispose(): void {
+    if (this.#disposed) return
+    this.stop()
+    this.#disposed = true
+    this.#unregister()
+    this.#listeners.clear()
+  }
+}