@lincyaw/workbench 0.1.0 → 0.2.0-rc.1

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()
+  }
+}

package/src/authoring-client.ts

@@ -0,0 +1,136 @@
+import { authoringClientResultFits } from '@lincyaw/kernel'
+import type { AuthoringClientActionResult, AuthoringClientEvent, AuthoringClientSnapshot, CanonicalSource } from '@lincyaw/kernel'
+import type { Workbench } from './workbench.ts'
+import type { AuthoringClientChannel } from './workspace-client.ts'
+
+const sameSource = (a: CanonicalSource, b: CanonicalSource) => a.documentId === b.documentId && a.version === b.version && a.fingerprint === b.fingerprint
+// Clock samples are observations, not user input revisions. Never push at animation-frame frequency.
+const signature = (value: AuthoringClientSnapshot) => JSON.stringify({ ...value, revision: 0, playback: value.playback && { ...value.playback,
+  position: value.playback.position && { ...value.playback.position, timeMs: 0, stepTimeMs: 0 } } })
+type Attachment = { directory: string, identity: string, epoch: string, channel: AuthoringClientChannel, connectionId?: string }
+
+/** One logical reader on Studio's shared authenticated socket; no extra browser SSE or polling timer. */
+export function connectAuthoringClient(workbench: Workbench): () => void {
+  const open = workbench.client.openAuthoringClient
+  if (!open) return () => {}
+  const clientId = crypto.randomUUID()
+  let closed = false, revision = 0, sequence = 0
+  let attached: Attachment | undefined
+  let lastSignature: string | undefined, lastContent: object | undefined
+  let lastDraftRevision: string | undefined
+  let active: { requestId: string, controller: AbortController } | undefined
+  let reports: Promise<void> = Promise.resolve()
+  let pendingState: { owner: Attachment, connectionId: string, value: AuthoringClientSnapshot } | undefined
+  let stateSending = false
+  const seen = new Set<string>()
+  const snapshot = (): AuthoringClientSnapshot | undefined => {
+    const value = workbench.authoringClientSnapshot(revision)
+    if (!value) return
+    const next = signature(value), content = workbench.state.authoring?.content, drafts = workbench.authoringDraftRevision()
+    if (next !== lastSignature || content !== lastContent || drafts !== lastDraftRevision) { revision++; lastSignature = next; lastContent = content; lastDraftRevision = drafts }
+    return { ...value, revision }
+  }
+  const detach = () => {
+    active?.controller.abort(); active = undefined
+    attached?.channel.close(); attached = undefined
+    pendingState = undefined
+    lastSignature = undefined; lastContent = undefined; lastDraftRevision = undefined; seen.clear()
+  }
+  const send = (owner: Attachment, connectionId: string, value: AuthoringClientSnapshot, acknowledgement?: { requestId: string, state: 'executing' | 'done' | 'refused' | 'failed', error?: { code: string }, result?: AuthoringClientActionResult }, preflight?: () => void) => {
+    const report = { sequence: ++sequence, snapshot: value, ...acknowledgement }
+    const next = reports.then(() => {
+      if (closed || attached !== owner || owner.connectionId !== connectionId) throw new Error('client-connection-changed')
+      preflight?.()
+      return acknowledgement ? owner.channel.acknowledge(connectionId, report as import('@lincyaw/kernel').AuthoringClientAcknowledgement) : owner.channel.publish(connectionId, report)
+    })
+    reports = next.catch(() => {})
+    return next
+  }
+  const publishState = (owner: Attachment, connectionId: string, value: AuthoringClientSnapshot) => {
+    pendingState = { owner, connectionId, value }
+    if (stateSending) return
+    stateSending = true
+    void (async () => {
+      try {
+        while (pendingState) {
+          const pending = pendingState; pendingState = undefined
+          if (attached !== pending.owner || attached.connectionId !== pending.connectionId) continue
+          // Coalesce rapid input while a publication is in flight; never retain an unbounded keystroke queue.
+          const latest = snapshot() ?? pending.value
+          await send(pending.owner, pending.connectionId, latest).catch(() => {})
+        }
+      } finally { stateSending = false }
+    })()
+  }
+  const received = async (owner: Attachment, event: AuthoringClientEvent) => {
+    if (closed || attached !== owner) return
+    if (event.type === 'connected') {
+      active?.controller.abort(); active = undefined
+      owner.connectionId = event.connectionId
+      const value = snapshot()
+      if (value) publishState(owner, event.connectionId, value)
+      return
+    }
+    if (event.type === 'cancel') { if (event.connectionId === owner.connectionId && event.requestId === active?.requestId) active.controller.abort(); return }
+    const request = event.request, connectionId = owner.connectionId
+    if (!connectionId || request.clientId !== clientId || request.epoch !== owner.epoch || request.expectedClientState.connectionId !== connectionId || seen.has(request.requestId)) return
+    seen.add(request.requestId)
+    if (seen.size > 64) seen.delete(seen.values().next().value!)
+    const value = snapshot()
+    if (!value) return
+    const controller = new AbortController(), task = { requestId: request.requestId, controller }
+    const owned = () => {
+      controller.signal.throwIfAborted()
+      if (closed || attached !== owner || owner.connectionId !== connectionId || active !== task || Date.now() >= Date.parse(event.expiresAt)) throw new Error('client-request-expired')
+    }
+    if (active || value.revision !== request.expectedClientState.revision || !sameSource(value.source, request.source) || !value.actions.includes(request.action.type) || Date.now() >= Date.parse(event.expiresAt)) {
+      await send(owner, connectionId, value, { requestId: request.requestId, state: 'refused', error: { code: 'client-state-changed' } }).catch(() => {})
+      return
+    }
+    active = task
+    const expiresAt = Date.parse(event.expiresAt)
+    const timeout = setTimeout(() => controller.abort(new Error('client-request-expired')), Math.max(0, expiresAt - Date.now()))
+    try {
+      // Only a confirmed executing acknowledgement grants this epoch permission to invoke a control.
+      await send(owner, connectionId, value, { requestId: request.requestId, state: 'executing' })
+      owned()
+      const latest = snapshot()
+      if (!latest || latest.revision !== request.expectedClientState.revision || !sameSource(latest.source, request.source)) throw new Error('client-state-changed')
+      const fits = (result: AuthoringClientActionResult) => authoringClientResultFits({ request, connection: { clientId, epoch: owner.epoch, connectionId }, document: owner.directory, snapshot: snapshot() ?? value }, result)
+      const actionResult = await workbench.executeAuthoringClientAction(request.action, request.source, controller.signal, expiresAt, fits)
+      owned()
+      const result = snapshot()
+      if (!result) throw new Error('client-document-changed')
+      await send(owner, connectionId, result, { requestId: request.requestId, state: 'done', ...actionResult ? { result: actionResult } : {} }, actionResult ? () => {
+        owned()
+        const latest = snapshot()
+        if (!latest || latest.revision !== result.revision || !['component-drafts.restore', 'component-drafts.discard', 'comment-drafts.restore', 'comment-drafts.discard'].includes(actionResult.type) && latest.revision !== request.expectedClientState.revision) throw new Error(actionResult.family === 'component' ? 'client-component-drafts-changed' : 'client-comment-drafts-changed')
+        if (!fits(actionResult)) throw new Error(actionResult.family === 'component' ? 'client-component-result-too-large' : 'client-comment-result-too-large')
+      } : undefined)
+    } catch (error) {
+      const result = snapshot()
+      const code = error instanceof Error && /^(client|production)-[a-z-]{1,100}$/.test(error.message) ? error.message : 'client-action-not-verified'
+      if (!controller.signal.aborted && attached === owner && owner.connectionId === connectionId && result) await send(owner, connectionId, result, { requestId: request.requestId, state: 'failed', error: { code } }).catch(() => {})
+    } finally { clearTimeout(timeout); if (active === task) active = undefined }
+  }
+  const changed = () => {
+    const state = workbench.state, source = state.authoring
+    if (closed || state.document === undefined || !source?.identity || source.loading) { detach(); return }
+    const before = revision, value = snapshot()
+    if (!value) { detach(); return }
+    if (attached && (attached.directory !== state.document || attached.identity !== source.identity)) detach()
+    if (!attached) {
+      const epoch = crypto.randomUUID()
+      // Callbacks run after the channel has been installed; the socket implementation is asynchronous.
+      const owner = { directory: state.document, identity: source.identity, epoch } as Attachment
+      owner.channel = open(state.document, { clientId, epoch, snapshot: value }, event => { void received(owner, event) }, () => {
+        if (attached === owner) { owner.connectionId = undefined; active?.controller.abort(); active = undefined }
+      })
+      attached = owner
+    } else if (before !== revision && attached.connectionId) publishState(attached, attached.connectionId, value)
+  }
+  const stop = workbench.subscribe(changed)
+  const stopDrafts = workbench.subscribeAuthoringDraftChanges(changed)
+  changed()
+  return () => { closed = true; stop(); stopDrafts(); detach() }
+}

package/src/authoring-draft-fragment.ts

@@ -0,0 +1,28 @@
+import type { AuthoringClientActionResult } from '@lincyaw/kernel'
+
+type Fragment = Extract<AuthoringClientActionResult, { jsonText: string }>
+type Fields = 'offset' | 'endOffset' | 'totalUtf16' | 'totalUtf8' | 'sha256' | 'jsonText'
+type FragmentBase = Fragment extends infer Value ? Value extends Fragment ? Omit<Value, Fields> : never : never
+export const draftContentHash = async (text: string): Promise<string> => [...new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text)))].map(value => value.toString(16).padStart(2, '0')).join('')
+const boundary = (text: string, offset: number) => !(offset > 0 && offset < text.length && /[\uD800-\uDBFF]/.test(text[offset - 1]!) && /[\uDC00-\uDFFF]/.test(text[offset]!))
+
+/** Budget the complete client receipt and WS frame, preserving exact JSON text and Unicode progress. */
+export async function authoringDraftFragment(options: { text: string, base: FragmentBase, offset: number, maxChars?: number }, current: () => void, fits: (value: AuthoringClientActionResult) => boolean): Promise<Fragment> {
+  const { text, base, offset } = options, maxChars = options.maxChars ?? 2048
+  const sha256 = await draftContentHash(text)
+  current()
+  if (!Number.isSafeInteger(offset) || offset < 0 || offset > text.length || !boundary(text, offset)) throw new Error(`client-${base.family}-offset-invalid`)
+  if (!Number.isSafeInteger(maxChars) || maxChars < 2 || maxChars > 2048) throw new Error(`client-${base.family}-fragment-limit`)
+  const lengths = { offset, totalUtf16: text.length, totalUtf8: new TextEncoder().encode(text).byteLength, sha256 }
+  let low = offset, high = Math.min(text.length, offset + maxChars), best: Fragment | undefined
+  while (low <= high) {
+    const middle = Math.floor((low + high) / 2)
+    const end = boundary(text, middle) ? middle : middle - 1
+    const result: Fragment = { ...base, ...lengths, endOffset: end, jsonText: text.slice(offset, end) }
+    if (fits(result)) { if (end > offset || end === text.length) best = result; low = middle + 1 }
+    else high = middle - 1
+  }
+  if (!best) throw new Error(`client-${base.family}-fragment-too-large`)
+  current()
+  return best
+}

package/src/base-controls.tsx

@@ -0,0 +1,47 @@
+import { ICONS } from '@lincyaw/design'
+import type { IconName } from '@lincyaw/design'
+import * as Tooltip from '@radix-ui/react-tooltip'
+import { createElement, forwardRef } from 'react'
+import type { ButtonHTMLAttributes, ReactNode } from 'react'
+
+const cls = (...names: (string | false | undefined | null)[]) => names.filter(Boolean).join(' ')
+
+export function PmIcon({ name, size: _size, strokeWidth = 1.7 }: { name: IconName, size?: number | string, strokeWidth?: number }) {
+  return (
+    <svg className="pm-ui-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={strokeWidth} strokeLinecap="round" strokeLinejoin="round" aria-hidden="true" focusable="false">
+      {ICONS[name].map(([tag, attrs], i) => createElement(tag, { key: i, ...attrs }))}
+    </svg>
+  )
+}
+
+export type ButtonVariant = 'default' | 'primary' | 'accent' | 'ghost' | 'danger'
+
+export type ButtonProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'type'> & { type?: 'button' | 'submit' | 'reset' }
+export type ControlDensity = 'compact' | 'regular' | 'touch'
+export type ControlProps = { density?: ControlDensity, loading?: boolean }
+
+export const PmButton = forwardRef<HTMLButtonElement, ButtonProps & ControlProps & { variant?: ButtonVariant, small?: boolean, icon?: IconName }>(function PmButton({ variant = 'default', small, density = small ? 'compact' : 'regular', loading, icon, type = 'button', className, children, disabled, ...rest }, ref) {
+  return (
+    <button {...rest} ref={ref} type={type} data-density={density} aria-busy={loading || undefined} disabled={disabled || loading || rest['aria-disabled'] === true || rest['aria-disabled'] === 'true'} className={cls('pm-ui-button', variant !== 'default' && `pm-ui-button--${variant}`, className)}>
+      <span className={cls('pm-ui-button__content', !icon && loading !== undefined && 'pm-ui-button__content--loading-text')}>{(icon || loading !== undefined) && <span aria-hidden="true" className={cls('pm-ui-button__icon', loading && 'pm-ui-loading')}>{loading ? <PmIcon name="loading" /> : icon && <PmIcon name={icon} />}</span>}{children}</span>
+    </button>
+  )
+})
+
+/** Radix opens on keyboard focus immediately; pointer hover uses the I11 delay. */
+export function PmTooltip({ label, shortcut, children }: { label: string, shortcut?: string, children: ReactNode }) {
+  return (
+    <Tooltip.Provider delayDuration={300} skipDelayDuration={0}>
+      <Tooltip.Root><Tooltip.Trigger asChild>{children}</Tooltip.Trigger><Tooltip.Portal><div className="pm-ui-tooltip-layer"><Tooltip.Content className="pm-ui-tooltip pm-ui" side="bottom" sideOffset={6} collisionPadding={8}>
+        {label}{shortcut && <kbd className="pm-ui-shortcut">{shortcut}</kbd>}
+      </Tooltip.Content></div></Tooltip.Portal></Tooltip.Root>
+    </Tooltip.Provider>
+  )
+}
+
+export const PmIconButton = forwardRef<HTMLButtonElement, ButtonProps & ControlProps & { icon: IconName, label: string, hint?: string, shortcut?: string, small?: boolean, tooltip?: boolean }>(function PmIconButton({ icon, label, hint, shortcut, small, tooltip = true, density = small ? 'compact' : 'regular', loading, className, disabled, ...rest }, ref) {
+  const button = <button {...rest} ref={ref} type="button" data-density={density} aria-label={label} aria-busy={loading || undefined} disabled={disabled || loading || rest['aria-disabled'] === true || rest['aria-disabled'] === 'true'} className={cls('pm-ui-icon-button', className)}>
+      <span className={cls('pm-ui-button__content', loading && 'pm-ui-loading')}><PmIcon name={loading ? 'loading' : icon} /></span>
+    </button>
+  return tooltip ? <PmTooltip label={hint ?? label} shortcut={shortcut}>{button}</PmTooltip> : button
+})