@lincyaw/workbench 0.1.0 → 0.2.0-rc.1

package/src/workbench.ts

@@ -0,0 +1,2328 @@
+import { applyDocumentCaptionTiming } from '@lincyaw/kernel'
+import type { DocumentCaptionTimingAction } from '@lincyaw/kernel'
+import { reconcileCaptionTiming } from './caption-timing.ts'
+import type { ProjectOperation, ProjectPlan } from '@lincyaw/kernel'
+import { undoDepth, redoDepth } from '@tiptap/pm/history'
+import { TextSelection } from '@tiptap/pm/state'
+import { CommentDraftBank } from './document-editor/comment-drafts.ts'
+import { ComponentPropertyDrafts } from './component-property-drafts.ts'
+import type { ComponentPropertyDraft } from './component-property-drafts.ts'
+import { componentSource, reconcileComponentAction, sameComponentSource } from './component-properties.ts'
+import { applyDocumentComponentAction, documentComponentSection, effectiveComponentParameters } from '@lincyaw/kernel'
+import type { DocumentAuthoringActionPlan, DocumentComponentAction, AppliedDocumentAuthoringAction } from '@lincyaw/kernel'
+import { inspectCommentDrafts } from './document-editor/comment-draft-inspection.ts'
+import { mutateCommentDrafts } from './document-editor/comment-draft-actions.ts'
+import { inspectComponentDrafts } from './component-draft-inspection.ts'
+import { mutateComponentDrafts } from './component-draft-actions.ts'
+import { DocumentSession } from './document-session.ts'
+import { reconcileRecordingAdoption } from './recording-adoption.ts'
+import { disposeTranscriptionSessions } from './transcription-session.ts'
+import { documentRecordingActive, disposeDocumentRecordings } from './audio-recording.ts'
+import { DOCUMENT_AUDIO_MAX_BYTES } from '@lincyaw/kernel'
+import type { DocumentSessionState } from './document-session.ts'
+import type { DocumentDraftReference } from './document-drafts.ts'
+import { DocumentReturnPoints, documentReturnStep, documentViewportOffset, restoreDocumentViewport } from './document-return-point.ts'
+import type { DocumentReturnPoint } from './document-return-point.ts'
+import type { DocumentRecordingAdoption, VerifiedDocumentRecordingAdoption, DocumentAudioImportAnswer, DocumentAudioInspectionAnswer, DocumentChangeAnswer, MediaClip, NarrationNode, TeachingDocument, DocumentTranscriptionRequest, TranscriptionTask, TranscriptionAdoptionDraft, TranscriptionAdoptionApply, TranscriptionAdoptionPlan, TranscriptionAdoptionAnswer } from '@lincyaw/kernel'
+import type { NativeDocumentEditor } from './document-editor/schema.tsx'
+import type { DocumentEditorCommands } from './document-editor/DocumentEditor.tsx'
+import { nativeTextPoint, nativeTextPosition } from './document-editor/selection.ts'
+import type { NativeTextPoint } from './document-editor/selection.ts'
+import type { DocumentFieldBookmark, DocumentFieldRegistration, DocumentHistoryEditor } from './document-editor/focus.ts'
+import { duplicateDocumentPage, moveDocumentPage, pageDeletion, removeDocumentPage, renameDocumentPage } from '@lincyaw/kernel'
+import { changeStepTiming } from './step-production.ts'
+import { changeDocumentVoice } from './document-voices.ts'
+import type { DocumentVoiceOptions, DocumentVoiceScope } from './document-voices.ts'
+import type { CanonicalSource, VoiceoverJob, VoiceSource } from '@lincyaw/kernel'
+import type { StepDurationDraft, StepDurationKey, StepTimingPatch } from './step-production.ts'
+import { DocumentTimingDrafts } from './document-timing-drafts.ts'
+import { CaptionTimingDrafts } from './caption-timing-drafts.ts'
+import type { CaptionTimingDraft } from './caption-timing-drafts.ts'
+import { compileDocumentPreview, readPreviewWhenReady, waitForPreviewRequest } from './document-preview.ts'
+import { readDocumentSnapshot } from './document-preview.ts'
+import { errorMessage, sameProductionBinding, slideShape, stepKeys, stepTrail, trailStep } from '@lincyaw/kernel'
+import type { Diagnostic, DiagnosticSnapshot, DocumentOperation, DocumentsAnswer, Focus, FocusReport, IrAnswer, IrEvent, IRDocument, JobsAnswer, OperationAnswer, PreviewAnchor, PreviewAnswer, PreviewCommand, PreviewDiagnostics, PreviewPoint, PreviewPosition, PreviewRect, PreviewRenderer, PreviewReport, ReviewChange, ReviewSnapshot, RevisionsAnswer, UncommittedFile } from '@lincyaw/kernel'
+import { DocumentDiagnostics } from './diagnostics.ts'
+import { DocumentHistory } from './history.ts'
+import { DocumentJobs } from './jobs.ts'
+import { VoiceoverJobs } from './voiceover-jobs.ts'
+import { contentText, localeOf, MESSAGES } from './messages.ts'
+import type { AgentPlace, Locale } from './messages.ts'
+import { changedBlocks, changedPlaces, findPlaceAtLine, findPlaceSource } from './places.ts'
+import { OperationLog } from './telemetry.ts'
+import type { OperationValue } from './telemetry.ts'
+import { PreviewPlayback } from './preview-playback.ts'
+import { ProductionPlayback } from './production-playback.ts'
+import type { ProductionBinding, ProductionPlan, ProductionPlaybackCommand, ProductionPlaybackState } from '@lincyaw/kernel'
+import { workspaceClient, WorkspaceServerError } from './workspace-client.ts'
+import type { WorkspaceClient } from './workspace-client.ts'
+import type { PageDeletePlan } from '@lincyaw/kernel'
+import type { AuthoringClientAction, AuthoringClientActionResult, AuthoringClientSnapshot } from '@lincyaw/kernel'
+import { PRODUCTION_PLAYBACK_RATES } from '@lincyaw/kernel'
+
+/** `editing`: the canonical document is edited in the parent; `viewing`: a derived snapshot is presented. */
+export type WorkbenchMode = 'editing' | 'viewing'
+
+/**
+ * How the web form is shown: as a page or as its presentation, whose controls can play a configured lecture.
+ * Both share one preview page and switch in place with `go.view`.
+ */
+export type WebView = 'document' | 'present'
+
+/** A playback key pressed in a preview that the workbench plays: Space, and the left and right arrows. */
+export type PlaybackKey = 'play-pause' | 'previous' | 'next'
+
+/** What the author points at in the document: a block (or a section), or a passage selected in it. */
+export interface Pointer {
+  target: PreviewAnchor
+  step?: number
+  /** The selected passage. */
+  quote?: string
+  /** Its box in the preview's viewport; none while it is out of sight. */
+  rect?: PreviewRect
+  obstacles?: PreviewRect[]
+  point?: PreviewPoint
+  /** Its text can be edited in place. */
+  isEditable: boolean
+}
+
+export type SaveState =
+  | { kind: 'idle' }
+  | { kind: 'saving' }
+  | { kind: 'saved', at: string }
+  | { kind: 'locked' }
+  | { kind: 'failed', message: string }
+
+/** A request for the agent of the conversation: its text and what it is about. */
+export interface AgentRequest {
+  text: string
+  focus: FocusReport[]
+}
+
+/** Where the host put a request: the conversation's session and the request's id, which its user message carries. */
+export interface AgentAnswer {
+  session: string
+  request: string
+}
+
+export interface WorkbenchState {
+  locale: Locale
+  authoring?: DocumentSessionState
+  /** Unaccepted numeric form input is retained separately from saved canonical timing. */
+  hasDocumentTimingDrafts?: boolean
+  documentTimingDraftStorageFailure?: boolean
+  captionTimingDraftSteps?: string[]
+  captionTimingDraftStorageFailure?: boolean
+  isDark: boolean
+  documents?: DocumentsAnswer
+  documentsFailure?: string
+  /** The workspace's routes answer 404: `@lincyaw/dsh` is turned off on the plugins page. */
+  isBundleDisabled?: boolean
+  document?: string
+  ir?: IrAnswer
+  mode: WorkbenchMode
+  previewRenderer: PreviewRenderer
+  /** In the web form: the page or the presentation, both in the same page, switched without loading it again. */
+  webView: WebView
+  previewReload: number
+  preview?: PreviewAnswer
+  previewFailure?: string
+  /** The IR revision the preview shows. */
+  previewIrRevision?: string
+  isPreparingPresentation?: boolean
+  presentationFailure?: string
+  presentationSnapshot?: { version: string, fingerprint: string, revision: string, project: number }
+  productionPlan?: ProductionPlan
+  productionPlayback?: ProductionPlaybackState
+  productionFailure?: string
+  voiceoverJobs?: VoiceoverJob[]
+  voiceoverJobsFailure?: string
+  /** A cache refresh that actually changed the current production binding; it never starts playback. */
+  voiceoverCacheRefresh?: { source: CanonicalSource, revision: string, sequence: number }
+  /** Changes when an acknowledged preview connection is attached or detached, including same-revision reloads. */
+  previewConnection: number
+  /** Where the preview is: the section the author reads, or the slide and its step. */
+  position?: PreviewPosition
+  /** Changes on every position intent, including A → B → A, without changing the source. */
+  documentPositionToken: string
+  /** Explicit author navigation, distinct from the player's passive cursor and frame reload reports. */
+  productionNavigationVersion: number
+  documentPositionIntent: 'seek' | 'pause'
+  /** An explicit source navigation request; scrolling updates position without issuing another request. */
+  documentNavigation?: { section: string, block?: string, request: string }
+  documentPositionFailure?: 'removed'
+  isCreatingPage?: boolean
+  isEditingPage?: boolean
+  editorHistory?: EditorHistoryState
+  isHistoryPreparing?: boolean
+  pageEditFailure?: string
+  diagnostics?: DiagnosticSnapshot
+  isDiagnosticsUnavailable: boolean
+  canRepairDiagnostics: boolean
+  isRepairingDiagnostics: boolean
+  diagnosticsRepairFailure?: string
+  pointer?: Pointer
+  /** Where the blocks the AI just changed are in the preview, for the kitten to walk to; `id` is new for each change. */
+  changeTrail?: { id: number, rects: PreviewRect[] }
+  /** The places the AI just changed, for the kitten in the editor to walk to; `id` is new for each change. */
+  changedPlaces?: { id: number, targets: PreviewAnchor[] }
+  save: SaveState
+  /** What the conversation's agent is told the author points at. */
+  focus: FocusReport[]
+  isFocusPending: boolean
+  focusFailure?: string
+  review?: ReviewSnapshot
+  history?: RevisionsAnswer
+  /** Files changed elsewhere and not yet in the history. */
+  outside?: UncommittedFile[]
+  historyFailure?: string
+  isHistoryBusy: boolean
+  isAsking: boolean
+  askFailure?: string
+  /** What the document can be made into, and its builds and exports (the author's and the AI's). */
+  jobs?: JobsAnswer
+  jobsFailure?: string
+  voiceServiceVersion?: number
+  jobPreparing?: { target: string, canCancel: boolean }
+}
+
+export interface PreviewSink {
+  readonly generation?: number
+  readonly capabilities?: readonly PreviewCommand['type'][]
+  send(command: PreviewCommand): void
+}
+
+export interface EditorHistoryState { section: string, undo: boolean, redo: boolean, field?: boolean }
+
+type Listener = () => void
+const sameSource = (a: CanonicalSource, b: CanonicalSource) => a.documentId === b.documentId && a.version === b.version && a.fingerprint === b.fingerprint
+
+/** The workbench's state as its parts read and change it. */
+export interface WorkbenchStore {
+  readonly state: WorkbenchState
+  set(patch: Partial<WorkbenchState>): void
+}
+
+// The export of the lecture as a video (`@lincyaw/addon-lecture`).
+export const VIDEO_TARGET = 'video'
+
+/** The document the conversation works on: none when no document is open. */
+export function selectedDocument(state: WorkbenchState): string | null {
+  return state.document ?? null
+}
+
+/** Whether the AI is changing the workspace now, or its change waits for the author. */
+export function isAgentChanging(state: WorkbenchState): boolean {
+  return Boolean(state.review && (state.review.running || state.review.changes.length > 0))
+}
+
+/** Whether the document has a slides form (no renderers listed: every form). */
+export function hasSlides(ir: IrAnswer | undefined): boolean {
+  const renderers = ir?.doc.config.renderers
+  return !renderers || Object.keys(renderers).length === 0 || 'slides' in renderers
+}
+
+/** The width of the document's slides over their height (`renderers.slides.aspectRatio`), 16:9 by default. */
+export function slideAspect(ir: IrAnswer | undefined): number {
+  if (!ir) return 16 / 9
+  const { width, height } = slideShape(ir.doc)
+  return width / height
+}
+
+/** What opening or closing a document clears. */
+const DOCUMENT_RESET = {
+  mode: 'editing',
+  authoring: undefined,
+  isCreatingPage: false,
+  isEditingPage: false,
+  editorHistory: undefined,
+  isHistoryPreparing: false,
+  pageEditFailure: undefined,
+  ir: undefined, preview: undefined, previewFailure: undefined, previewIrRevision: undefined, position: undefined, documentNavigation: undefined, documentPositionFailure: undefined,
+  diagnostics: undefined, isDiagnosticsUnavailable: false, isRepairingDiagnostics: false, diagnosticsRepairFailure: undefined,
+  pointer: undefined, save: { kind: 'idle' },
+  focus: [], isFocusPending: false, focusFailure: undefined,
+  review: undefined, history: undefined, outside: undefined, historyFailure: undefined, isHistoryBusy: false, askFailure: undefined,
+  jobs: undefined, jobsFailure: undefined, jobPreparing: undefined,
+  voiceoverJobs: undefined, voiceoverJobsFailure: undefined, voiceoverCacheRefresh: undefined,
+} satisfies Partial<WorkbenchState>
+
+/** A free directory for a new document called `title`, beside most of the existing ones. */
+export function documentDirFor(title: string, taken: readonly string[]): string {
+  const parents = new Map<string, number>()
+  for (const dir of taken) {
+    const parent = dir.includes('/') ? dir.slice(0, dir.lastIndexOf('/')) : ''
+    parents.set(parent, (parents.get(parent) ?? 0) + 1)
+  }
+  const parent = [...parents].sort((a, b) => b[1] - a[1])[0]?.[0] ?? ''
+  const slug = title.normalize('NFKD').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40) || 'document'
+  const base = parent ? `${parent}/${slug}` : slug
+  let dir = base
+  for (let n = 2; taken.includes(dir); n++) dir = `${base}-${n}`
+  return dir
+}
+
+/**
+ * The state of the workbench and its actions: the documents, the open document's preview, what the author points at
+ * in it; canonical source editing, diagnostics and history are parts of their own
+ * (`diagnostics.ts`, `history.ts`).
+ */
+export class Workbench {
+  readonly client: WorkspaceClient
+  readonly #documentSession: DocumentSession
+  readonly #audioImports = new WeakMap<File, { identity: string, version: string, id: string }>()
+  readonly #audioFingerprints = new WeakMap<File, Promise<string>>()
+  readonly #documentTimingDrafts = new DocumentTimingDrafts()
+  readonly #captionTimingDrafts = new CaptionTimingDrafts()
+  readonly #removedCueTimings = new Map<string, { pauseMs: number }>()
+  #cueTimingScope?: string
+  #documentEditor?: NativeDocumentEditor
+  #documentEditorCommands?: DocumentEditorCommands
+  #documentEditorBinding?: { identity: string, reset: number }
+  readonly #documentReturnPoints = new DocumentReturnPoints()
+  #documentViewport?: { element: HTMLElement, identity: string, returnScrollTop?: number, stop(): void }
+  #stopDocumentReturnScroll?: () => void
+  #openingDocument?: { directory: string, scope: number, generation: number, focus?: 'body', initial?: boolean, stop(): void,
+    basis?: { identity: string, reset: number, version?: string, content: TeachingDocument }, point?: DocumentReturnPoint, fallback?: DocumentReturnPoint }
+  #stopDocumentLayoutScroll?: () => void
+  #activeDocumentHistory?: DocumentHistoryEditor
+  #unsubscribeDocumentHistory?: () => void
+  #unsubscribeDocumentSelection?: () => void
+  #documentSelectionGeneration = 0
+  #removedDocumentPosition?: { identity: string, documentId: string, sectionId: string, stepId?: string, version: string, fingerprint: string, scope: number, generation: number, token: string }
+  #pendingDocumentFocus?: { documentId: string, nodeId: string, generation: number, afterSave?: true }
+  #pendingDocumentSelection?: { documentId: string, anchor: NativeTextPoint, head: NativeTextPoint, focused: boolean }
+  readonly #documentFields = new Map<string, DocumentFieldRegistration>()
+  #pendingDocumentField?: { field: Omit<DocumentFieldRegistration, 'focus' | 'editor'>, bookmark: DocumentFieldBookmark, reset: number, generation: number }
+  #state: WorkbenchState
+  readonly #listeners = new Set<Listener>()
+  readonly #commentDrafts = new CommentDraftBank()
+  readonly #componentPropertyDrafts = new ComponentPropertyDrafts()
+  readonly #positionSeed = Array.from(crypto.getRandomValues(new Uint32Array(2)), value => value.toString(36)).join('-')
+  #positionSequence = 0
+  readonly #selectedSteps = new Map<string, number>()
+  #pendingGo?: { document: string | undefined, command: Extract<PreviewCommand, { type: 'go' }> }
+  readonly #diagnostics: DocumentDiagnostics
+  readonly #history: DocumentHistory
+  readonly #jobs: DocumentJobs
+  readonly #voiceover: VoiceoverJobs
+  readonly #askers = new Set<(request: AgentRequest) => Promise<AgentAnswer | void>>()
+  readonly #previewSinks = new Set<PreviewSink>()
+  readonly #playbackKeys = new Set<(command: PlaybackKey) => void>()
+  #unsubscribeIr?: () => void
+  #runtimeDocument?: string
+  #jobsDocument?: string
+  readonly #jobObservers = new Set<symbol>()
+  readonly #previewObservers = new Set<symbol>()
+  #previewReads = 0
+  #presentationPreparation = 0
+  #presentationController?: AbortController
+  #irReads = 0
+  #focusVersion = 0
+  #focusWriting: Promise<void> = Promise.resolve()
+  #documentScope = 0
+  #jobPreparation?: AbortController
+  readonly #playback = new PreviewPlayback(() => ({ document: this.#state.document, scope: this.#documentScope, sinks: this.#previewSinks }))
+  readonly #production = new ProductionPlayback(() => ({ document: this.#state.document, scope: this.#documentScope, sinks: this.#previewSinks,
+    binding: this.#state.productionPlan?.binding, ready: this.#productionReady() }), state => this.#set({ productionPlayback: state }))
+  /** A place to show that no preview could take yet (none was attached, e.g. the chat covered the document). */
+  #pendingReveal?: PreviewAnchor
+  /** The AI's changes to show on the document once the preview has them. */
+  #pendingFlash?: ReviewChange[]
+  #trail = 0
+  #lastPosition?: string
+  #awaitingView?: WebView
+  /** The forms asked for ahead of the author (`web:<dir>`, `slides:<dir>`), and the wait before asking for the slides. */
+  /** What the author does, for the operator's collector when the host has one. */
+  readonly telemetry: OperationLog
+  readonly #preparationTimeoutMs: number
+
+  constructor(options: { client?: WorkspaceClient, locale?: Locale, isDark?: boolean, preparationTimeoutMs?: number } = {}) {
+    this.client = options.client ?? workspaceClient()
+    this.#preparationTimeoutMs = Number.isFinite(options.preparationTimeoutMs) ? Math.max(1000, Math.min(300_000, options.preparationTimeoutMs!)) : 45_000
+    this.#state = {
+      locale: options.locale ?? localeOf(globalThis.navigator?.language) ?? 'en',
+      isDark: options.isDark ?? false,
+      mode: 'editing',
+      previewRenderer: 'web',
+      webView: 'document',
+      previewReload: 0,
+      previewConnection: 0,
+      documentPositionToken: this.#nextDocumentPosition(),
+      productionNavigationVersion: 0,
+      documentPositionIntent: 'seek',
+      isDiagnosticsUnavailable: false,
+      canRepairDiagnostics: false,
+      isRepairingDiagnostics: false,
+      save: { kind: 'idle' },
+      focus: [],
+      isFocusPending: false,
+      isHistoryBusy: false,
+      isAsking: false,
+    }
+    const workbench = this
+    const store: WorkbenchStore = {
+      get state() {
+        return workbench.#state
+      },
+      set: patch => workbench.#set(patch),
+    }
+    this.#documentSession = new DocumentSession(this.client, authoring => {
+      if (this.#state.document !== authoring.directory) return
+      const pendingField = this.#pendingDocumentField
+      if (pendingField && (pendingField.field.identity !== authoring.identity || authoring.reset > pendingField.reset
+        || pendingField.field.blockId !== undefined && !authoring.content?.blocks[pendingField.field.blockId]
+        || !authoring.content?.steps[pendingField.field.stepId])) this.#pendingDocumentField = undefined
+      const cueTimingScope = JSON.stringify([authoring.identity, authoring.reset])
+      if (this.#cueTimingScope !== cueTimingScope) { this.#removedCueTimings.clear(); this.#cueTimingScope = cueTimingScope }
+      const previous = this.#state.authoring
+      // A saved timestamp belongs to this client's acknowledged source version.
+      // Remote adoption has no server modification time to display in its place.
+      const adoptedCleanVersion = Boolean(previous?.identity && previous.identity === authoring.identity
+        && previous.version && authoring.version && previous.version !== authoring.version
+        && !previous.loading && !authoring.loading && !previous.dirty && !authoring.dirty && !previous.saving && !authoring.saving)
+      const position = this.#state.position
+      const selected = position && previous && previous.identity === authoring.identity ? previous.content?.sections[position.section]?.stepOrder[position.step] : undefined
+      const selectedStep = selected ? authoring.content?.steps[selected] : undefined, selectedPage = selectedStep ? authoring.content?.sections[selectedStep.sectionId] : undefined
+      const selectedIndex = selectedPage?.stepOrder.indexOf(selected!) ?? -1
+      const moved = position && selectedStep && selectedIndex >= 0 && (position.section !== selectedStep.sectionId || position.step !== selectedIndex)
+      const removed = this.#state.webView === 'document' && position?.view !== 'present' && position && previous?.identity === authoring.identity
+        && (selected ? !selectedStep || selectedIndex < 0 : !authoring.content?.sectionOrder.includes(position.section))
+      const restoredPosition = !removed && this.#restoredDocumentPosition(authoring)
+      const scope = this.#documentScope, generation = this.#documentSelectionGeneration
+      if (removed && authoring.identity) this.#documentReturnPoints.forget(authoring.identity)
+      this.#set({ authoring,
+        ...removed ? { position: undefined, documentNavigation: undefined, documentPositionFailure: 'removed' as const } : {},
+        ...restoredPosition ? { documentPositionFailure: undefined } : {},
+        ...moved ? { position: { ...position, section: selectedStep.sectionId, step: selectedIndex, trail: [] } } : {},
+        hasDocumentTimingDrafts: Boolean(authoring.identity && authoring.content && this.#documentTimingDrafts.has(authoring.identity, authoring.content)),
+        documentTimingDraftStorageFailure: this.#documentTimingDrafts.failed,
+        captionTimingDraftSteps: authoring.identity && authoring.member?.id && authoring.content ? this.#captionTimingDrafts.steps({ identity: authoring.identity, memberId: authoring.member.id }, authoring.content) : [],
+        captionTimingDraftStorageFailure: Boolean(authoring.identity && authoring.member?.id && this.#captionTimingDrafts.failed({ identity: authoring.identity, memberId: authoring.member.id })),
+        save: authoring.error ? { kind: 'failed', message: authoring.error } : authoring.saving ? { kind: 'saving' } : !authoring.dirty && (previous?.dirty || previous?.saving) ? { kind: 'saved', at: new Date().toISOString() } : adoptedCleanVersion || this.#state.save.kind === 'failed' ? { kind: 'idle' } : this.#state.save })
+      // The deletion owns the token produced above; source restoration only retires its notice.
+      if (removed && previous?.identity && previous.content && previous.version && previous.fingerprint
+        && !previous.loading && !previous.dirty && !previous.saving && !previous.restored && !previous.composing && !previous.recovering && !previous.error
+        && scope === this.#documentScope && generation === this.#documentSelectionGeneration && !this.#state.position && this.#state.documentPositionFailure === 'removed') {
+        this.#removedDocumentPosition = { identity: previous.identity, documentId: previous.content.id, sectionId: position.section,
+          ...selected ? { stepId: selected } : {}, version: previous.version, fingerprint: previous.fingerprint, scope, generation, token: this.#state.documentPositionToken }
+      }
+      this.#finishOpeningDocument()
+      // Native insertion can select a page before the source actor receives that new entity.
+      if (position && previous && previous.identity === authoring.identity && !previous.content?.sections[position.section]
+        && authoring.content?.sections[position.section]) this.#saveDocumentReturnPoint()
+      if (this.#production.changed()) void this.pausePlayback().catch(() => {})
+      const acknowledgedSourceChanged = !authoring.dirty && !authoring.loading && !authoring.error && !previous?.loading
+        && previous?.identity === authoring.identity && Boolean(previous?.version && authoring.version)
+        && (previous?.version !== authoring.version || previous?.fingerprint !== authoring.fingerprint)
+      if (!authoring.dirty && previous?.dirty || acknowledgedSourceChanged) { void this.#history.read(authoring.directory); void this.loadDocuments() }
+      // The source changed under an author with nothing unsaved while the AI holds a review: the AI changed it. The
+      // editor's kitten walks to the blocks whose content differs.
+      if (acknowledgedSourceChanged && !previous?.dirty && !previous?.saving && this.#state.review && previous?.content && authoring.content) {
+        const targets = changedBlocks(previous.content, authoring.content)
+        if (targets.length) this.#set({ changedPlaces: { id: ++this.#trail, targets } })
+      }
+    })
+    this.#diagnostics = new DocumentDiagnostics(this.client, store)
+    this.#jobs = new DocumentJobs(this.client, store)
+    this.#voiceover = new VoiceoverJobs(this.client, store, (job, signal) => this.#refreshVoiceover(job, signal))
+    this.#history = new DocumentHistory(this.client, store, (changes) => {
+      this.#record('ai.change', { 'presmium.files': changes.map(change => change.path).join('\n'), 'presmium.added': changes.reduce((n, c) => n + c.added, 0), 'presmium.removed': changes.reduce((n, c) => n + c.removed, 0) })
+      this.#pendingFlash = changes
+      this.#flashChanges()
+    })
+    this.telemetry = new OperationLog(() => this.client.readTelemetry(), (batch, beacon) => this.client.sendTelemetry(batch, beacon), this.#state.locale)
+    void this.telemetry.start()
+  }
+
+  /** Records an operation of the author, with the document, the view and the mode it was done in. */
+  #record(name: string, attributes: Record<string, OperationValue> = {}): void {
+    this.telemetry.record(name, { 'presmium.document': this.#state.document, 'presmium.view': this.#state.previewRenderer, 'presmium.mode': this.#state.mode, ...attributes })
+  }
+
+  /** Does an operation that takes time and records it once done, with its outcome and how long it took. */
+  async #timed<T>(name: string, attributes: Record<string, OperationValue>, work: () => Promise<T>, outcome: (value: T) => string = () => 'done'): Promise<T> {
+    const started = Date.now()
+    try {
+      const value = await work()
+      this.#record(name, { ...attributes, 'presmium.outcome': outcome(value), 'presmium.ms': Date.now() - started })
+      return value
+    } catch (error) {
+      this.#record(name, { ...attributes, 'presmium.outcome': 'failed', 'presmium.error': errorMessage(error), 'presmium.ms': Date.now() - started })
+      throw error
+    }
+  }
+
+  get state(): WorkbenchState {
+    return this.#state
+  }
+
+  /** Page-lifetime document navigation only; not a canonical source or playback revision. */
+  get documentNavigationVersion(): number { return this.#documentScope }
+
+  documentCommentDrafts(identity: string) {
+    const source = this.#state.authoring
+    return source?.identity === identity && source.member?.id ? this.#commentDrafts.get(identity, source.member.id) : undefined
+  }
+  /** A status counter only: passive client reports never enumerate or serialize drafts. */
+  authoringCommentDraftRevision(): number {
+    const source = this.#state.authoring
+    return source?.identity && source.member?.id ? this.#commentDrafts.peek(source.identity, source.member.id)?.revision ?? 0 : 0
+  }
+  documentPropertyDrafts(identity: string): ComponentPropertyDrafts | undefined { return this.#state.authoring?.identity === identity ? this.#componentPropertyDrafts : undefined }
+  /** Only counters enter passive client state; no new form payload is exposed to MCP. */
+  authoringDraftRevision(): string {
+    const source = this.#state.authoring
+    return JSON.stringify([this.authoringCommentDraftRevision(), source?.identity && source.member?.id ? this.#componentPropertyDrafts.revision(source.identity, source.member.id) : 0])
+  }
+  subscribeAuthoringDraftChanges(listener: () => void): () => void {
+    const comments = this.#commentDrafts.subscribe(listener), properties = this.#componentPropertyDrafts.subscribe(listener)
+    return () => { comments(); properties() }
+  }
+
+  getState = (): WorkbenchState => this.#state
+
+  subscribe = (listener: Listener): (() => void) => {
+    this.#listeners.add(listener)
+    return () => this.#listeners.delete(listener)
+  }
+
+  onRepairDiagnostics = (repairer: (diagnostics: readonly Diagnostic[]) => void | Promise<void>): (() => void) => this.#diagnostics.onRepair(repairer)
+
+  requestRepairDiagnostics(): Promise<void> {
+    this.#record('diagnostics.repair')
+    return this.#diagnostics.requestRepair()
+  }
+
+  /** Settings changed without changing document content; open voice surfaces read fresh capabilities. */
+  refreshVoiceServices(): void {
+    this.stopAuditions()
+    this.#set({ voiceServiceVersion: (this.#state.voiceServiceVersion ?? 0) + 1 })
+  }
+
+  /** The host's way to hand a request to the conversation's agent. */
+  onAgentRequest = (asker: (request: AgentRequest) => Promise<AgentAnswer | void>): (() => void) => {
+    this.#askers.add(asker)
+    return () => this.#askers.delete(asker)
+  }
+
+  #nextDocumentPosition(): string { return `${this.#positionSeed}:${++this.#positionSequence}` }
+
+  #restoredDocumentPosition(source: DocumentSessionState): boolean {
+    const removed = this.#removedDocumentPosition
+    if (!removed) return false
+    if (removed.scope !== this.#documentScope || removed.generation !== this.#documentSelectionGeneration || removed.token !== this.#state.documentPositionToken
+      || removed.identity !== source.identity || this.#state.documentPositionFailure !== 'removed' || source.error) {
+      this.#removedDocumentPosition = undefined
+      return false
+    }
+    const section = source.content?.sections[removed.sectionId]
+    return !source.loading && !source.dirty && !source.saving && !source.restored && !source.composing && !source.recovering
+      && source.version === removed.version && source.fingerprint === removed.fingerprint && source.content?.id === removed.documentId
+      && Boolean(section && source.content?.sectionOrder.includes(removed.sectionId)
+        && (!removed.stepId || section.stepOrder.includes(removed.stepId) && source.content.steps[removed.stepId]?.sectionId === removed.sectionId))
+  }
+
+  #set(patch: Partial<WorkbenchState>): void {
+    if (Object.hasOwn(patch, 'position') || Object.hasOwn(patch, 'documentPositionFailure')) this.#removedDocumentPosition = undefined
+    if (Object.hasOwn(patch, 'position')) { this.#cancelOpeningDocument(); this.#stopDocumentReturnScroll?.() }
+    this.#state = { ...this.#state, ...patch, ...Object.hasOwn(patch, 'position') ? { documentPositionToken: this.#nextDocumentPosition(), documentPositionIntent: patch.documentPositionIntent ?? 'seek' } : {} }
+    if (Object.hasOwn(patch, 'position')) this.#saveDocumentReturnPoint()
+    for (const listener of this.#listeners) listener()
+  }
+
+  get #messages() {
+    return MESSAGES[this.#state.locale]
+  }
+
+  setLocale(locale: Locale): void {
+    if (locale === this.#state.locale) return
+    this.#set({ locale })
+    this.#record('locale.set', { 'presmium.locale': locale })
+  }
+
+  setDark(isDark: boolean): void {
+    if (isDark === this.#state.isDark) return
+    this.#set({ isDark })
+    this.#broadcast({ type: 'appearance', dark: isDark })
+    this.#record('appearance.set', { 'presmium.dark': isDark })
+  }
+
+  async loadDocuments(): Promise<void> {
+    try {
+      this.#set({ documents: await this.client.readDocuments(), documentsFailure: undefined, isBundleDisabled: false })
+    } catch (error) {
+      this.#set({ documentsFailure: errorMessage(error), isBundleDisabled: error instanceof WorkspaceServerError && error.status === 404 })
+    }
+  }
+
+  planDocumentOperation(operation: ProjectOperation): Promise<ProjectPlan> {
+    return this.client.planProjectChange({ id: crypto.randomUUID(), operation })
+  }
+
+  operateDocument(operation: ProjectOperation, planned?: ProjectPlan): Promise<OperationAnswer> {
+    const attributes = Object.fromEntries(Object.entries(operation).filter(([, value]) => typeof value === 'string').map(([key, value]) => [`presmium.op.${key}`, value as string]))
+    return this.#timed(`document.${operation.op}`, attributes, async () => {
+      const scope = this.#documentScope
+      if (this.#state.document === operation.dir) await this.flushPendingEdits()
+      const answer = await this.client.operateDocument(operation, planned)
+      if ((operation.op === 'rename' || operation.op === 'delete') && scope === this.#documentScope && this.#state.document === operation.dir) this.closeDocument()
+      await this.loadDocuments()
+      return answer
+    })
+  }
+
+  /** Makes a document called `title` from the template, in a directory of its own; answers the directory. */
+  async createDocument(title: string, template?: string): Promise<string> {
+    const taken = this.#state.documents?.documents.map(doc => doc.dir) ?? []
+    const answer = await this.operateDocument({ op: 'create', dir: documentDirFor(title, taken), title, ...template ? { template } : {} })
+    return answer.dir!
+  }
+
+  /** Copies a document; the copy is called `title`. */
+  async copyDocument(dir: string, title: string): Promise<string> {
+    const taken = this.#state.documents?.documents.map(doc => doc.dir) ?? []
+    let to = `${dir}-copy`
+    for (let n = 2; taken.includes(to); n++) to = `${dir}-copy-${n}`
+    const answer = await this.operateDocument({ op: 'copy', dir, to, title })
+    return answer.dir ?? to
+  }
+
+  /** Title changes use the same fixed project plan as directory management. */
+  async retitleDocument(dir: string, title: string): Promise<void> {
+    await this.operateDocument({ op: 'retitle', dir, title })
+  }
+
+  #watchOpeningInteraction(cancel: () => void): () => void {
+    if (typeof document === 'undefined') return () => {}
+    const focused = document.activeElement, dialog = focused?.closest('[role="dialog"]')
+    const interact = (event: Event) => {
+      if (!event.isTrusted) return
+      if (event.type === 'focusin' && (!(event.target instanceof Element) || event.target === focused || dialog?.contains(event.target))) return
+      cancel()
+    }
+    const events = ['pointerdown', 'keydown', 'beforeinput', 'wheel', 'touchmove', 'focusin']
+    for (const event of events) document.addEventListener(event, interact, true)
+    return () => { for (const event of events) document.removeEventListener(event, interact, true) }
+  }
+
+  #cancelOpeningDocument(): void {
+    const pending = this.#openingDocument
+    this.#openingDocument = undefined
+    pending?.stop()
+  }
+
+  #beginOpeningDocument(directory: string, focus?: 'body', fallback?: DocumentReturnPoint): void {
+    this.#cancelOpeningDocument()
+    this.#openingDocument = { directory, focus, fallback: fallback && { ...fallback }, scope: this.#documentScope, generation: this.#documentSelectionGeneration,
+      stop: this.#watchOpeningInteraction(() => this.#cancelOpeningDocument()) }
+  }
+
+  #saveDocumentReturnPoint(): void {
+    const source = this.#state.authoring, position = this.#state.position
+    if (!source?.identity || !source.content || source.loading || !position || !source.content.sectionOrder.includes(position.section)) return
+    const section = source.content.sections[position.section]
+    let stepId = section?.stepOrder[position.step]
+    if (this.#state.webView === 'present' || position.view === 'present') {
+      const snapshot = this.#state.presentationSnapshot, ir = this.#state.ir
+      if (!snapshot || !ir || source.dirty || source.saving || source.error || snapshot.version !== source.version || snapshot.fingerprint !== source.fingerprint
+        || snapshot.project !== (source.projectRevision ?? 0) || snapshot.revision !== ir.revision || snapshot.revision !== this.#state.previewIrRevision) return
+      const ids = ir.doc.sections.find(page => page.id === position.section)?.stepIds
+      if (!ids || ids.length && !ids[position.step]) return
+      stepId = ids[position.step]
+      if (stepId && (!section?.stepOrder.includes(stepId) || source.content.steps[stepId]?.sectionId !== position.section)) return
+    }
+    if (!section || !stepId && section.stepOrder.length) return
+    const viewport = this.#documentViewport, previous = this.#documentReturnPoints.read(source.identity)
+    const measured = this.#state.webView === 'document' && viewport?.identity === source.identity ? documentViewportOffset(viewport.element, section.id) : undefined
+    const offset = measured ?? (previous?.sectionId === section.id ? previous.offset : undefined)
+    this.#documentReturnPoints.write(source.identity, { sectionId: section.id, ...stepId ? { stepId } : {}, ...offset !== undefined ? { offset } : {} })
+  }
+
+  #finishOpeningDocument(): void {
+    const pending = this.#openingDocument, source = this.#state.authoring
+    if (!pending || source?.loading || !source?.identity || !source.content) return
+    if (source.error === 'document-identity-changed') { this.#cancelOpeningDocument(); return }
+    if (pending.scope !== this.#documentScope || pending.directory !== this.#state.document || pending.generation !== this.#documentSelectionGeneration) { this.#cancelOpeningDocument(); return }
+    if (!pending.basis) {
+      pending.basis = { identity: source.identity, reset: source.reset, version: source.version, content: source.content }
+      if (!pending.focus) {
+        pending.point = this.#documentReturnPoints.read(source.identity) ?? pending.fallback
+        if (!pending.point) {
+          const section = source.content.sections[source.content.sectionOrder[0]!]
+          if (!section) { this.#cancelOpeningDocument(); return }
+          pending.point = { sectionId: section.id, ...section.stepOrder[0] ? { stepId: section.stepOrder[0] } : {} }
+          pending.initial = true
+        }
+        if (documentReturnStep(source.content, pending.point) === undefined) {
+          this.#documentReturnPoints.forget(source.identity); this.#cancelOpeningDocument()
+          this.#set({ documentPositionFailure: 'removed' }); return
+        }
+      }
+    }
+    const basis = pending.basis
+    if (source.identity !== basis.identity || source.reset !== basis.reset || source.version !== basis.version || source.content !== basis.content) { this.#cancelOpeningDocument(); return }
+    const editor = this.#documentEditor, binding = this.#documentEditorBinding, viewport = this.#documentViewport
+    if (!editor || editor.prosemirrorView.isDestroyed || binding?.identity !== source.identity || binding.reset !== source.reset || viewport?.identity !== source.identity) return
+    // The editor can mount read-only while the source is still loading; a read-only body cannot take the caret yet.
+    if (pending.focus && !editor.isEditable) return
+    this.#cancelOpeningDocument()
+    if (pending.focus) {
+      const body = (blocks: typeof editor.document, sectionId?: string): { nodeId: string, sectionId: string } | undefined => {
+        for (const block of blocks) {
+          if (block.type === 'presmiumPage') sectionId = block.props.sectionId
+          else if (sectionId && editor.schema.blockSchema[block.type].content === 'inline') return { nodeId: block.id, sectionId }
+          const nested = body(block.children, sectionId)
+          if (nested) return nested
+        }
+      }
+      const target = body(editor.document)
+      if (target && source.content.sections[target.sectionId]) {
+        this.#set({ position: { section: target.sectionId, step: 0, trail: [], view: 'document' }, documentPositionFailure: undefined, documentNavigation: undefined })
+        this.#focusDocumentNode(editor, target.nodeId)
+      }
+      return
+    }
+    const point = pending.point!, step = documentReturnStep(source.content, point)
+    if (step === undefined) return
+    this.#selectedSteps.set(`${pending.directory}\0${point.sectionId}`, step)
+    this.#set({ position: { section: point.sectionId, step, trail: [], view: 'document' }, documentPositionFailure: undefined, documentNavigation: undefined })
+    if (pending.initial) return
+    const current = () => this.#state.document === pending.directory && this.#state.authoring?.identity === basis.identity
+      && this.#state.authoring.reset === basis.reset && this.#state.authoring.version === basis.version && this.#state.authoring.content === basis.content
+      && this.#documentViewport === viewport && this.#state.position?.section === point.sectionId && this.#state.position.step === step
+    const restore = () => {
+      if (!current()) { stop(); return }
+      const top = viewport.element.scrollTop
+      restoreDocumentViewport(viewport.element, point)
+      if (viewport.element.scrollTop !== top) viewport.returnScrollTop = viewport.element.scrollTop
+    }
+    const observer = typeof ResizeObserver === 'undefined' ? undefined : new ResizeObserver(restore)
+    let stopInteraction: () => void = () => {}
+    const stop = () => { observer?.disconnect(); stopInteraction(); viewport.returnScrollTop = undefined; if (this.#stopDocumentReturnScroll === stop) this.#stopDocumentReturnScroll = undefined }
+    this.#stopDocumentReturnScroll?.(); this.#stopDocumentReturnScroll = stop
+    stopInteraction = this.#watchOpeningInteraction(stop)
+    observer?.observe(viewport.element)
+    observer?.observe(editor.prosemirrorView.dom)
+    restore()
+  }
+
+  /** Consume only this viewport owner's actual programmatic destination; user gestures retire it. */
+  consumeDocumentReturnScroll(element: HTMLElement): boolean {
+    const viewport = this.#documentViewport, top = viewport?.returnScrollTop
+    if (viewport?.element !== element || top === undefined) return false
+    viewport.returnScrollTop = undefined
+    return element.scrollTop === top
+  }
+
+  attachDocumentViewport(element: HTMLElement, identity: string): () => void {
+    this.#documentViewport?.stop()
+    const scroll = () => { if (!this.#openingDocument) this.#saveDocumentReturnPoint() }
+    const viewport = { element, identity, stop: () => element.removeEventListener('scroll', scroll) }
+    this.#documentViewport = viewport
+    element.addEventListener('scroll', scroll, { passive: true })
+    this.#finishOpeningDocument()
+    return () => { if (this.#documentViewport === viewport) { this.#saveDocumentReturnPoint(); this.#stopDocumentReturnScroll?.(); this.#documentViewport = undefined }; viewport.stop() }
+  }
+
+  /** The body editor became editable: an opening that waits to put the caret in it can finish now. */
+  documentEditorEditable(): void { this.#finishOpeningDocument() }
+
+  async openDocument(dir: string, options: { focus?: 'body', expectedIdentity?: string, fallbackReturnPoint?: DocumentReturnPoint } = {}): Promise<void> {
+    if (this.#state.document === dir) {
+      if (options.focus) { this.#beginOpeningDocument(dir, options.focus); this.#finishOpeningDocument() }
+      return
+    }
+    this.#saveDocumentReturnPoint()
+    this.#documentScope++
+    const scope = this.#documentScope
+    this.#stopSubscriptions()
+    this.#history.subscribeReview(dir)
+    this.#set({ ...DOCUMENT_RESET, document: dir, previewRenderer: 'web', webView: 'document' })
+    this.#beginOpeningDocument(dir, options.focus, options.fallbackReturnPoint)
+    this.#record('document.open')
+    this.#diagnostics.subscribe(dir)
+    // Authoring is ready from source JSON; compilation and preview are independent.
+    const [opened] = await Promise.all([this.#documentSession.open(dir, options.expectedIdentity), this.#readFocus(dir), this.#history.read(dir)])
+    if (opened === 'identity-changed' && scope === this.#documentScope && this.#state.document === dir) { this.closeDocument(); return }
+    this.#finishOpeningDocument()
+  }
+
+  closeDocument(): void {
+    this.#saveDocumentReturnPoint()
+    this.#documentScope++
+    if (this.#state.document !== undefined) this.#record('document.close')
+    this.#stopSubscriptions()
+    this.#documentSession.close()
+    this.#set({ ...DOCUMENT_RESET, document: undefined })
+    void this.loadDocuments()
+  }
+
+  async #readFocus(dir: string): Promise<void> {
+    const version = this.#focusVersion
+    try {
+      const answer = await this.client.readFocus(dir)
+      if (this.#state.document === dir && version === this.#focusVersion) this.#set({ focus: answer.focus ?? [] })
+    } catch {
+    }
+  }
+
+  async #readIr(dir: string): Promise<void> {
+    const read = ++this.#irReads
+    try {
+      const ir = await this.client.readIr(dir)
+      if (this.#state.document === dir && read === this.#irReads) {
+        this.#set({ ir })
+        this.#flashChanges()
+      }
+    } catch {
+    }
+  }
+
+  /**
+   * Makes the blocks the AI changed blink on the document, once the preview shows the revision the workbench has: the
+   * author sees what changed where they read it, not as files.
+   */
+  #flashChanges(): void {
+    const changes = this.#pendingFlash
+    const ir = this.#state.ir
+    if (!changes || !ir || this.#state.previewIrRevision !== ir.revision || this.#previewSinks.size === 0) return
+    this.#pendingFlash = undefined
+    const targets = changedPlaces(ir.doc, changes)
+    if (targets.length === 0) return
+    this.#trail++
+    this.#broadcast({ type: 'flash', targets })
+    this.#record('ai.change.shown', { 'presmium.places': targets.map(target => [target.section, target.block].filter(Boolean).join(':')).join('\n') })
+  }
+
+  retryDiagnostics(): void {
+    this.#record('diagnostics.retry')
+    this.#diagnostics.retry()
+  }
+
+  reportPreviewDiagnostics(report: PreviewDiagnostics): Promise<void> {
+    return this.#diagnostics.reportPreview(report)
+  }
+
+  async #readPreview(dir: string): Promise<void> {
+    const read = ++this.#previewReads
+    const renderer = this.#state.previewRenderer
+    const current = () => this.#state.document === dir && this.#state.previewRenderer === renderer && read === this.#previewReads
+    try {
+      const preview = await readPreviewWhenReady(this.client, dir, renderer, { waiting: current })
+      if (current()) this.#set({ preview, previewFailure: undefined })
+    } catch (error) {
+      if (current()) this.#set({ previewFailure: error instanceof Error && error.name === 'TimeoutError' ? 'preview-timeout' : errorMessage(error) })
+    }
+  }
+
+  async #handleIrEvent(dir: string, event: IrEvent): Promise<void> {
+    if (this.#state.document !== dir) return
+    const renderers = this.#state.ir?.doc.config.renderers
+    if (event.revision !== this.#state.ir?.revision) {
+      await this.#readIr(dir)
+      // Opening the document and its initial SSE snapshot share one request.
+      // A save can arrive while that request still describes the previous revision.
+      if (this.#state.document === dir && event.revision !== this.#state.ir?.revision) await this.#readIr(dir)
+    }
+    if (this.#state.document !== dir) return
+    // The view switch goes with the slides: a document that lost them shows its web form.
+    if (this.#state.previewRenderer === 'slides' && !hasSlides(this.#state.ir)) this.setPreviewRenderer('web')
+    else if (renderers && JSON.stringify(renderers) !== JSON.stringify(this.#state.ir?.doc.config.renderers)) void this.#readPreview(dir)
+    if (event.files.length > 0) void this.#history.read(dir)
+  }
+
+  setMode(mode: WorkbenchMode): void {
+    if (mode === this.#state.mode) return
+    this.#set({ mode })
+    this.#record('mode.set')
+    this.point(undefined)
+    this.#broadcast({ type: 'pick', on: false })
+  }
+
+  setPreviewRenderer(renderer: PreviewRenderer): void {
+    if (renderer === this.#state.previewRenderer) return
+    this.#set({ previewRenderer: renderer, preview: undefined, previewFailure: undefined, previewIrRevision: undefined, pointer: undefined })
+    this.#record('view.set')
+    this.#syncRuntimeStreams()
+    const document = this.#state.document
+    if (document !== undefined) void this.#readPreview(document)
+  }
+
+  /** Only public modal semantics are inspected; no field values or editor selection are read. */
+  #previewModalOpen(): boolean {
+    return typeof document !== 'undefined' && [...document.querySelectorAll<HTMLElement>('[role="dialog"][aria-modal="true"]')]
+      .some(element => !element.closest('[hidden], [inert]') && element.getClientRects().length > 0 && getComputedStyle(element).visibility !== 'hidden')
+  }
+
+  #canPreparePresentation(owned = false): boolean {
+    const state = this.#state, source = state.authoring
+    return Boolean(state.document !== undefined && source?.identity && source.version && source.fingerprint && source.content
+      && !source.loading && !source.dirty && !source.saving && !source.restored && !source.error && !source.composing && !source.recovering
+      && !state.hasDocumentTimingDrafts && !state.documentTimingDraftStorageFailure && !state.isCreatingPage && !state.isEditingPage
+      && !state.isHistoryBusy && !state.isHistoryPreparing && !state.jobPreparing && !state.isBundleDisabled && !isAgentChanging(state)
+      && (owned || !state.isPreparingPresentation) && !this.#previewModalOpen())
+  }
+
+  /** One explicit preparation owner; caller cancellation stops adoption without changing the current mode. */
+  async preparePresentation(signal?: AbortSignal, deadline?: number): Promise<boolean> {
+    const directory = this.#state.document, source = this.#state.authoring
+    if (!this.#canPreparePresentation() || directory === undefined || !source?.identity || !source.version || !source.fingerprint || !source.content) {
+      this.#set({ presentationFailure: this.#state.hasDocumentTimingDrafts ? this.#messages.timingDraftPending : this.#messages.presentationPending })
+      return false
+    }
+    signal?.throwIfAborted()
+    this.#presentationController?.abort(new Error('presentation-superseded'))
+    const request = ++this.#presentationPreparation, scope = this.#documentScope
+    const controller = this.#presentationController = new AbortController()
+    const cancel = () => controller.abort(signal?.reason)
+    signal?.addEventListener('abort', cancel, { once: true })
+    const { identity, version, fingerprint } = source, project = source.projectRevision ?? 0
+    const current = () => request === this.#presentationPreparation && scope === this.#documentScope && this.#state.document === directory && this.#state.authoring?.identity === identity
+    const unchanged = () => {
+      const latest = this.#state.authoring
+      return current() && !controller.signal.aborted && (deadline === undefined || Date.now() < deadline) && this.#canPreparePresentation(true)
+        && latest?.version === version && latest.fingerprint === fingerprint && (latest.projectRevision ?? 0) === project
+    }
+    this.#set({ isPreparingPresentation: true, presentationFailure: undefined })
+    const timeout = setTimeout(() => controller.abort(deadline === undefined ? new DOMException('Presentation preparation timed out', 'TimeoutError') : new Error('client-request-expired')), Math.max(0, Math.min(this.#preparationTimeoutMs, deadline === undefined ? this.#preparationTimeoutMs : deadline - Date.now())))
+    const stop = this.subscribe(() => { if (!unchanged()) controller.abort(new Error('presentation-source-changed')) })
+    const input = () => controller.abort(new Error('client-preview-input'))
+    const escape = (event: KeyboardEvent) => { if (event.key === 'Escape') controller.abort(new Error('client-preview-cancelled')) }
+    const observer = typeof MutationObserver === 'undefined' ? undefined : new MutationObserver(() => { if (this.#previewModalOpen()) controller.abort(new Error('client-preview-modal-open')) })
+    if (typeof document !== 'undefined') {
+      document.addEventListener('beforeinput', input, true); document.addEventListener('compositionstart', input, true); document.addEventListener('keydown', escape, true)
+      observer?.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['aria-modal', 'hidden', 'inert'] })
+    }
+    try {
+      await waitForPreviewRequest(this.pausePlayback(), controller.signal)
+      if (!unchanged()) return false
+      controller.signal.throwIfAborted()
+      const snapshot = await compileDocumentPreview(this.client, { directory, version, fingerprint, project }, controller.signal)
+      controller.signal.throwIfAborted()
+      const ir = snapshot.ir
+      if (!current()) return false
+      const entry = directory ? `${directory}/lecture.json` : 'lecture.json'
+      if (!unchanged() || ir.revision !== snapshot.revision || ir.sourceFingerprints?.[entry] !== fingerprint
+        || ir.doc.source?.version !== version || ir.doc.source.fingerprint !== fingerprint) throw new Error('presentation-source-changed')
+      if (ir.diagnostics.some(finding => finding.severity === 'error')) throw new Error('document-preview-compile-failed')
+      this.#set({ ir, preview: snapshot.preview, previewRenderer: 'web', previewFailure: undefined, presentationSnapshot: { version, fingerprint, revision: ir.revision, project } })
+      return true
+    } catch (error) {
+      // Editing supersedes this snapshot; the existing stale status owns its recovery action.
+      const cancelled = controller.signal.aborted && !(controller.signal.reason instanceof Error && controller.signal.reason.name === 'TimeoutError')
+      if (current()) this.#set({ presentationFailure: cancelled || error instanceof Error && error.message === 'presentation-source-changed' ? undefined : this.#messages.presentationCompileFailed })
+      return false
+    } finally {
+      clearTimeout(timeout); stop(); signal?.removeEventListener('abort', cancel); observer?.disconnect()
+      if (typeof document !== 'undefined') { document.removeEventListener('beforeinput', input, true); document.removeEventListener('compositionstart', input, true); document.removeEventListener('keydown', escape, true) }
+      if (this.#presentationController === controller) this.#presentationController = undefined
+      if (current()) this.#set({ isPreparingPresentation: false })
+    }
+  }
+
+  /** Closing an explicit preview cancels its pending adoption, while source saves retain their owner. */
+  cancelPreviewPreparation(): void {
+    if (!this.#state.isPreparingPresentation) return
+    this.#presentationController?.abort(new Error('client-preview-cancelled'))
+    this.#presentationPreparation++
+    this.#set({ isPreparingPresentation: false, presentationFailure: undefined })
+  }
+
+  /**
+   * Shows the web form as a page or as its presentation. The page is the same (and stays loaded): the view changes there,
+   * at the place the author is; from the slides, the web form is shown first.
+   */
+  setWebView(view: WebView): void {
+    if (view === this.#state.webView && this.#state.previewRenderer === 'web') return
+    this.#awaitingView = view
+    this.#set({ webView: view })
+    this.#syncRuntimeStreams()
+    this.#record('view.set', { 'presmium.preview.view': view })
+    if (this.#state.previewRenderer !== 'web') {
+      this.setPreviewRenderer('web')
+    } else { if (view === 'present' && this.#state.document !== undefined) void this.#readPreview(this.#state.document); this.#showWebView() }
+  }
+
+  /** Source editing never owns IR or job streams. Export and presentation share one optional runtime stream. */
+  #syncRuntimeStreams(): void {
+    const document = this.#state.document
+    const jobs = document !== undefined && this.#jobObservers.size > 0
+    const runtime = document !== undefined && !jobs && (this.#previewObservers.size > 0 || this.#state.webView === 'present' || this.#state.previewRenderer === 'slides')
+    if (!runtime || this.#runtimeDocument !== document) {
+      this.#unsubscribeIr?.(); this.#unsubscribeIr = undefined; this.#runtimeDocument = undefined
+    }
+    if (!jobs || this.#jobsDocument !== document) { this.#jobs.stop(); this.#jobsDocument = undefined }
+    if (jobs && this.#jobsDocument !== document) { this.#jobsDocument = document; this.#jobs.subscribe(document!) }
+    if (runtime && !this.#unsubscribeIr) {
+      this.#runtimeDocument = document
+      this.#unsubscribeIr = this.client.subscribeIr(document!, event => void this.#handleIrEvent(document!, event), () => void this.#readIr(document!))
+      void this.#readIr(document!)
+    }
+  }
+
+  /** A visible reader or presentation shares the existing optional IR stream. */
+  observePreviewRuntime(): () => void {
+    const token = Symbol('preview')
+    this.#previewObservers.add(token)
+    this.#syncRuntimeStreams()
+    return () => { if (this.#previewObservers.delete(token)) this.#syncRuntimeStreams() }
+  }
+
+  /** Follows export status only while a consumer is visible; it displaces the optional IR stream. */
+  observeJobs(): () => void {
+    const token = Symbol('exports')
+    this.#jobObservers.add(token)
+    this.#syncRuntimeStreams()
+    if (this.#state.document !== undefined) void this.#readIr(this.#state.document)
+    return () => { if (this.#jobObservers.delete(token)) this.#syncRuntimeStreams() }
+  }
+
+  /** Space and the left and right arrows pressed in a preview that the workbench plays (Video Production's). */
+  observePlaybackKeys(listener: (command: PlaybackKey) => void): () => void {
+    this.#playbackKeys.add(listener)
+    return () => { this.#playbackKeys.delete(listener) }
+  }
+
+  /** Video and its dialogs borrow one owner; its idle reads never prepare a snapshot or stop media. */
+  observeVoiceoverJobs(): () => void {
+    return this.#state.document === undefined ? () => {} : this.#voiceover.observe(this.#state.document)
+  }
+
+  rememberVoiceoverJob(document: string, job: VoiceoverJob): void { this.#voiceover.remember(document, job) }
+
+  #voiceoverPlaybackCurrent(job: VoiceoverJob): boolean {
+    const state = this.#state, snapshot = state.presentationSnapshot, binding = state.productionPlan?.binding
+    return Boolean(binding && this.#productionSourceCurrent(binding) && sameSource(binding.source, job.source) && binding.irRevision === job.revision
+      && snapshot?.version === job.source.version && snapshot.fingerprint === job.source.fingerprint && snapshot.revision === job.revision
+      && snapshot.project === (state.authoring?.projectRevision ?? 0) && state.previewIrRevision === job.revision
+      && state.webView === 'present' && state.previewRenderer === 'web' && state.preview?.web && !state.isPreparingPresentation
+      && !state.hasDocumentTimingDrafts && !state.documentTimingDraftStorageFailure && !documentRecordingActive(this))
+  }
+
+  async #refreshVoiceover(job: VoiceoverJob, signal: AbortSignal): Promise<boolean> {
+    if (!this.#voiceoverPlaybackCurrent(job)) return false
+    const document = this.#state.document!, scope = this.#documentScope, identity = this.#state.authoring?.identity, initialBinding = this.#state.productionPlan!.binding
+    // This is the existing cache-only plan read: no compile, discovery, generation or draft flush.
+    const plan = await this.client.readProductionPlan(document, { source: job.source, irRevision: job.revision }, signal)
+    signal.throwIfAborted()
+    const current = () => scope === this.#documentScope && identity === this.#state.authoring?.identity && this.#voiceoverPlaybackCurrent(job)
+      && Boolean(this.#state.productionPlan && sameProductionBinding(initialBinding, this.#state.productionPlan.binding))
+    if (!current()) return false
+    if (!sameSource(plan.binding.source, job.source) || plan.binding.irRevision !== job.revision) throw new Error('voice-context-changed')
+    if (sameProductionBinding(plan.binding, this.#state.productionPlan!.binding)) return true
+    this.#playback.stopPreviewOutputs()
+    await this.pausePlayback()
+    signal.throwIfAborted()
+    if (!current()) return false
+    this.#production.reset()
+    this.#set({ productionPlan: plan, voiceoverCacheRefresh: { source: job.source, revision: job.revision, sequence: (this.#state.voiceoverCacheRefresh?.sequence ?? 0) + 1 } })
+    // The mounted production loader fetches this new binding in the existing frame.
+    // Replacing the iframe for every clip would interrupt progressive playback and its connection.
+    return true
+  }
+
+  #showWebView(sinks: Iterable<PreviewSink> = this.#previewSinks): void {
+    const selected = this.#state.position
+    const section = selected?.section ?? this.#state.ir?.doc.sections[0]?.id ?? this.#state.authoring?.content?.sectionOrder[0]
+    if (section === undefined) return
+    // A fresh or reloaded frame reports its initial document view before applying this command.
+    this.#awaitingView = this.#state.webView
+    for (const sink of sinks) sink.send({ type: 'go', section, step: selected?.step ?? 0, view: this.#state.webView })
+  }
+
+  reloadPreview(): void {
+    this.#record('preview.reload')
+    this.#reloadPreview()
+  }
+
+  /** New exact audio caches can refresh an existing current preview, without compiling or starting playback. */
+  refreshVoicePlayback(source: CanonicalSource, revision: string): boolean {
+    const state = this.#state, authoring = state.authoring, snapshot = state.presentationSnapshot
+    if (!authoring || authoring.content?.id !== source.documentId || authoring.version !== source.version || authoring.fingerprint !== source.fingerprint
+      || authoring.loading || authoring.dirty || authoring.saving || authoring.composing || authoring.restored || authoring.error
+      || !snapshot || snapshot.version !== source.version || snapshot.fingerprint !== source.fingerprint || snapshot.revision !== revision
+      || snapshot.project !== (authoring.projectRevision ?? 0) || state.webView !== 'present' || state.previewRenderer !== 'web' || !state.preview?.web) return false
+    this.#reloadPreview()
+    return true
+  }
+
+  #productionSourceCurrent(binding: ProductionBinding): boolean {
+    const source = this.#state.authoring
+    return Boolean(source?.content?.id === binding.source.documentId && source.version === binding.source.version && source.fingerprint === binding.source.fingerprint
+      && !source.loading && !source.dirty && !source.saving && !source.composing && !source.restored && !source.error && !isAgentChanging(this.#state))
+  }
+
+  #productionReady(): boolean {
+    const state = this.#state, binding = state.productionPlan?.binding, snapshot = state.presentationSnapshot
+    return Boolean(binding && this.#productionSourceCurrent(binding) && snapshot?.revision === binding.irRevision
+      && snapshot.version === binding.source.version && snapshot.fingerprint === binding.source.fingerprint && snapshot.project === (state.authoring?.projectRevision ?? 0)
+      && state.previewIrRevision === binding.irRevision && state.webView === 'present' && state.previewRenderer === 'web'
+      && !state.hasDocumentTimingDrafts && !state.documentTimingDraftStorageFailure)
+  }
+
+  /** Bounded observations, without reading or publishing any unsubmitted editor content. */
+  authoringClientSnapshot(revision: number): AuthoringClientSnapshot | undefined {
+    const state = this.#state, source = state.authoring, content = source?.content
+    if (state.document === undefined || !content || !source?.identity || !source.version || !source.fingerprint) return undefined
+    const locked = isAgentChanging(state), conflicted = Boolean(source.error || source.restored || source.recovering)
+    const editing = { dirty: source.dirty, saving: source.saving, composing: source.composing, conflicted, locked, loading: source.loading }
+    const safe = !source.loading && !source.composing && !conflicted && !locked && !state.isCreatingPage && !state.isEditingPage
+    const clean = safe && !source.dirty && !source.saving && !state.hasDocumentTimingDrafts
+    const plan = state.productionPlan, playback = state.productionPlayback
+    const ready = clean && plan?.canPreview && this.#productionReady() && playback?.status === 'ready' && sameProductionBinding(plan.binding, playback.binding)
+    const position = state.position, page = position && content.sections[position.section]
+    const commentDrafts = source.member?.id ? this.#commentDrafts.peek(source.identity, source.member.id) : undefined
+    const prepared = state.presentationSnapshot, actual = { documentId: content.id, version: source.version, fingerprint: source.fingerprint }
+    const preparedCurrent = clean && prepared && prepared.version === source.version && prepared.fingerprint === source.fingerprint && prepared.project === (source.projectRevision ?? 0)
+      && state.ir?.revision === prepared.revision && state.ir.doc.source?.version === source.version && state.ir.doc.source.fingerprint === source.fingerprint
+    return { revision, source: { documentId: content.id, version: source.version, fingerprint: source.fingerprint }, view: state.webView, editing,
+      interaction: state.documentPositionToken,
+      ...page && position ? { position: { sectionId: page.id, ...page.stepOrder[position.step] ? { stepId: page.stepOrder[position.step] } : {} } } : {},
+      ...plan ? { binding: plan.binding } : {}, ...playback ? { playback } : {},
+      preview: preparedCurrent ? { status: 'prepared', source: actual, irRevision: prepared.revision, projectRevision: prepared.project }
+        : { status: state.isPreparingPresentation ? 'preparing' : state.presentationFailure ? 'unavailable' : 'unprepared' },
+      actions: ['state.read', 'playback.pause', ...safe ? ['source.flush' as const] : [],
+        ...commentDrafts?.readable ? ['comment-drafts.inspect' as const, 'comment-drafts.read' as const] : [],
+        ...clean && !state.isHistoryBusy && !state.isHistoryPreparing && commentDrafts?.readable && commentDrafts.ownersKnown ? ['comment-drafts.discard' as const, ...state.webView === 'document' && commentDrafts.hasRestoreComposer() ? ['comment-drafts.restore' as const] : []] : [],
+        ...source.member?.id && this.#componentPropertyDrafts.readable(source.identity, source.member.id) ? ['component-drafts.inspect' as const, 'component-drafts.read' as const] : [],
+        ...clean && !state.isHistoryBusy && !state.isHistoryPreparing && source.member?.id && this.#componentPropertyDrafts.readable(source.identity, source.member.id) ? ['component-drafts.restore' as const, 'component-drafts.discard' as const] : [],
+        ...this.#canPreparePresentation() ? ['preview.prepare' as const] : [],
+        ...clean && (state.webView === 'document' || ready) ? ['position.step' as const] : [],
+        ...ready ? ['playback.play' as const, 'playback.rate' as const, ...plan?.timing === 'confirmed' ? ['playback.seek' as const] : []] : []], unsubmittedContent: 'not-inspected' }
+  }
+
+  /** Reuses the same source actor, mutual-audio gate and frame acknowledgements as the human controls. */
+  async executeAuthoringClientAction(action: AuthoringClientAction, expected: CanonicalSource, signal: AbortSignal, deadline?: number, fits?: (result: AuthoringClientActionResult) => boolean): Promise<void | AuthoringClientActionResult> {
+    const scope = this.#documentScope, identity = this.#state.authoring?.identity, document = this.#state.document, interaction = this.#state.documentPositionToken
+    const owned = () => { signal.throwIfAborted(); if (scope !== this.#documentScope || identity !== this.#state.authoring?.identity || document !== this.#state.document) throw new Error('client-document-changed') }
+    const current = () => { owned(); const state = this.authoringClientSnapshot(0); if (!state || !sameSource(state.source, expected) || !state.actions.includes(action.type)) throw new Error('client-action-unavailable'); return state }
+    current()
+    if (action.type === 'state.read') return
+    if (action.type === 'comment-drafts.inspect' || action.type === 'comment-drafts.read') {
+      const drafts = identity ? this.documentCommentDrafts(identity) : undefined
+      if (!drafts?.readable || !fits) throw new Error('client-comment-drafts-unavailable')
+      const result = await inspectCommentDrafts(drafts, action, signal, fits)
+      current()
+      return result
+    }
+    if (action.type === 'comment-drafts.restore' || action.type === 'comment-drafts.discard') {
+      const memberId = this.#state.authoring?.member?.id, drafts = identity ? this.documentCommentDrafts(identity) : undefined
+      if (!identity || !memberId || !drafts || !fits) throw new Error('client-comment-drafts-unavailable')
+      const guard = () => {
+        owned()
+        const state = this.#state, source = state.authoring
+        if (!source?.content || source.member?.id !== memberId || !source.version || !source.fingerprint
+          || !sameSource({ documentId: source.content.id, version: source.version, fingerprint: source.fingerprint }, expected)
+          || source.loading || source.dirty || source.saving || source.composing || source.restored || source.recovering || source.error || isAgentChanging(state)
+          || state.isCreatingPage || state.isEditingPage || state.isHistoryBusy || state.isHistoryPreparing || state.hasDocumentTimingDrafts
+          || action.type === 'comment-drafts.restore' && state.webView !== 'document') throw new Error('client-source-changed')
+      }
+      return mutateCommentDrafts(drafts, action, signal, guard, fits)
+    }
+    if (action.type === 'component-drafts.inspect' || action.type === 'component-drafts.read') {
+      const memberId = this.#state.authoring?.member?.id
+      if (!identity || !memberId || !fits || !this.#componentPropertyDrafts.readable(identity, memberId)) throw new Error('client-component-drafts-unavailable')
+      const result = await inspectComponentDrafts(this.#componentPropertyDrafts, { identity, memberId, source: expected }, action, signal, fits)
+      current()
+      return result
+    }
+    if (action.type === 'component-drafts.restore' || action.type === 'component-drafts.discard') {
+      const memberId = this.#state.authoring?.member?.id
+      if (!identity || !memberId || !fits) throw new Error('client-component-drafts-unavailable')
+      const guard = (draft?: ComponentPropertyDraft) => {
+        owned()
+        const state = this.#state, source = state.authoring
+        if (!source?.content || source.identity !== identity || source.member?.id !== memberId || !source.version || !source.fingerprint
+          || !sameSource({ documentId: source.content.id, version: source.version, fingerprint: source.fingerprint }, expected)
+          || source.loading || source.dirty || source.saving || source.composing || source.restored || source.recovering || source.error || isAgentChanging(state)
+          || state.isCreatingPage || state.isEditingPage || state.isHistoryBusy || state.isHistoryPreparing || state.hasDocumentTimingDrafts) throw new Error('client-source-changed')
+        if (action.type === 'component-drafts.restore') {
+          const block = source.content.blocks[action.draft.blockId]
+          if (block?.type !== 'component' || draft && block.definitionId !== draft.definitionId) throw new Error('client-component-target-unavailable')
+          // The source-bound bank checks the saved Definition again before adopting its strict fork.
+          try { effectiveComponentParameters(source.content, block.id, action.draft.stepId) } catch { throw new Error('client-component-target-unavailable') }
+        }
+      }
+      return mutateComponentDrafts(this.#componentPropertyDrafts, { identity, memberId, source: expected }, action, signal, guard, fits)
+    }
+    if (action.type === 'preview.prepare') {
+      const view = this.#state.webView
+      const stop = this.subscribe(() => { if (interaction !== this.#state.documentPositionToken || view !== this.#state.webView) this.cancelPreviewPreparation() })
+      try {
+        const prepared = await this.preparePresentation(signal, deadline)
+        owned(); signal.throwIfAborted()
+        const result = this.authoringClientSnapshot(0)
+        if (!prepared || result?.preview?.status !== 'prepared' || !result.preview.source || !sameSource(result.preview.source, expected)
+          || result.view !== view || result.interaction !== interaction) throw new Error('client-preview-unavailable')
+      } finally { stop() }
+      return
+    }
+    if (action.type === 'source.flush') {
+      await this.flushPendingEdits(signal); owned()
+      const source = this.#state.authoring
+      if (!source || source.dirty || source.saving || source.composing || source.error || source.restored) throw new Error('client-source-not-saved')
+      return
+    }
+    if (action.type === 'playback.pause') { this.#interruptProductionNavigation(); await this.pausePlayback(); owned(); return }
+    if (action.type === 'position.step') {
+      const content = this.#state.authoring?.content, section = content?.sections[action.sectionId]
+      if (!section?.stepOrder.includes(action.stepId) || content?.steps[action.stepId]?.sectionId !== action.sectionId) throw new Error('client-step-not-found')
+      await this.pausePlayback(); current()
+      if (interaction !== this.#state.documentPositionToken) throw new Error('client-position-changed')
+      const present = this.#state.webView === 'present'
+      const result = await this.selectDocumentStep(action.sectionId, action.stepId)
+      owned()
+      const state = this.authoringClientSnapshot(0)
+      if (!state || !sameSource(state.source, expected) || state.position?.sectionId !== action.sectionId || state.position.stepId !== action.stepId
+        || present && (!result || result.status !== 'ready' || result.position?.sectionId !== action.sectionId || result.position.stepId !== action.stepId || result.position.playing)) throw new Error('client-step-unverified')
+      return
+    }
+    const plan = this.#state.productionPlan
+    if (!plan || !sameProductionBinding(plan.binding, action.binding)) throw new Error('client-playback-binding-changed')
+    if (action.type === 'playback.seek' && (plan.timing !== 'confirmed' || plan.durationMs === undefined || action.timeMs > plan.durationMs)) throw new Error('client-seek-out-of-range')
+    if (action.type === 'playback.rate' && !(PRODUCTION_PLAYBACK_RATES as readonly number[]).includes(action.rate)) throw new Error('client-rate-unavailable')
+    const control: ProductionPlaybackCommand = action.type === 'playback.play' ? { action: 'play', binding: action.binding }
+      : action.type === 'playback.seek' ? { action: 'seek', binding: action.binding, timeMs: action.timeMs } : { action: 'rate', binding: action.binding, rate: action.rate }
+    const result = await this.controlProduction(control, signal); owned()
+    if (result.status !== 'ready' || !result.position || action.type === 'playback.play' && !result.position.playing
+      || action.type === 'playback.rate' && result.position.rate !== action.rate) throw new Error('client-playback-unverified')
+  }
+
+  /** Reads the actual derived plan without building the visuals or synthesizing speech. */
+  async prepareProductionPlan(signal: AbortSignal): Promise<ProductionPlan> {
+    const initial = this.#state, source = initial.authoring, identity = source?.identity, directory = initial.document, scope = this.#documentScope
+    if (!identity || directory === undefined || !source?.version || !source.fingerprint || source.loading || source.dirty || source.saving || source.composing || source.restored || source.error) throw new Error('production-source-changed')
+    const snapshot = await readDocumentSnapshot(this.client, { directory, version: source.version, fingerprint: source.fingerprint }, signal)
+    signal.throwIfAborted()
+    if (!snapshot.doc.source || scope !== this.#documentScope || this.#state.authoring?.identity !== identity) throw new Error('production-source-changed')
+    const plan = await this.client.readProductionPlan(directory, { source: snapshot.doc.source, irRevision: snapshot.revision }, signal)
+    signal.throwIfAborted()
+    if (scope !== this.#documentScope || this.#state.authoring?.identity !== identity || !this.#productionSourceCurrent(plan.binding)) throw new Error('production-source-changed')
+    this.#set({ productionPlan: plan })
+    if (this.#production.changed()) void this.pausePlayback().catch(() => {})
+    return plan
+  }
+
+  #interruptProductionNavigation(): void {
+    this.#set({ productionNavigationVersion: this.#state.productionNavigationVersion + 1 })
+  }
+
+  /** The child confirms seeks and playback; the parent never estimates a playhead using a timer. */
+  async controlProduction(control: ProductionPlaybackCommand, signal?: AbortSignal): Promise<ProductionPlaybackState> {
+    if (control.action === 'pause' || control.action === 'seek' || control.action === 'step' && !control.utteranceId) this.#interruptProductionNavigation()
+    if (control.action === 'seek' && this.#state.productionPlan?.timing !== 'confirmed') throw new Error('production-plan-unavailable')
+    const scope = this.#documentScope
+    this.#set({ productionFailure: undefined })
+    try {
+      if (control.action === 'play' || control.action === 'load' || control.action === 'seek' || control.action === 'step') {
+        if (control.action === 'load') this.#playback.stopPreviewOutputs()
+        else this.stopAuditions()
+        await this.pausePlayback()
+        signal?.throwIfAborted()
+      }
+      return await this.#production.control(control, signal)
+    } catch (error) {
+      const code = errorMessage(error), current = this.#state.productionPlan?.binding
+      if (scope === this.#documentScope && !signal?.aborted && current && sameProductionBinding(current, control.binding) && this.#productionReady()
+        && !(control.action === 'load' && code === 'production-playback-cancelled')
+        && !['production-source-changed', 'production-request-superseded', 'production-request-cancelled'].includes(code)) this.#set({ productionFailure: code })
+      throw error
+    }
+  }
+
+  closeProduction(): void {
+    this.#interruptProductionNavigation()
+    this.#production.reset()
+    this.#set({ productionPlan: undefined, productionFailure: undefined })
+  }
+
+  /** Explicitly enables the standard production capability in this document's one authoritative source. */
+  async enableDocumentProduction(): Promise<void> {
+    const scope = this.#documentScope, identity = this.#state.authoring?.identity
+    if (!identity) throw new Error('production-source-changed')
+    await this.pausePlayback()
+    await this.flushPendingEdits()
+    const source = this.#state.authoring, document = this.getDocument(identity)
+    if (scope !== this.#documentScope || !document || !source?.version || !source.fingerprint || source.dirty || source.saving || source.composing || source.restored || source.error || isAgentChanging(this.#state)) throw new Error('production-source-changed')
+    const plugins = [...new Set([...(document.metadata.plugins ?? []), '@lincyaw/addon-lecture', '@lincyaw/addon-speech'])]
+    const next = { ...document, metadata: { ...document.metadata, plugins, renderers: { ...document.metadata.renderers, lecture: document.metadata.renderers?.lecture ?? {} } } }
+    this.#documentSession.record(next)
+    await this.flushPendingEdits()
+    if (scope !== this.#documentScope || this.#state.authoring?.identity !== identity || this.#state.authoring.dirty || this.#state.authoring.saving || this.#state.authoring.error) throw new Error('production-source-changed')
+  }
+
+  #reloadPreview(): void {
+    this.#set({ previewReload: this.#state.previewReload + 1 })
+    const address = this.#state.previewRenderer === 'slides' ? this.#state.preview?.slides : this.#state.preview?.web
+    if (!address) this.retryPreview()
+  }
+
+  retryPreview(): void {
+    this.#record('preview.retry')
+    if (this.#state.document !== undefined) void this.#readPreview(this.#state.document)
+  }
+
+  #pageEditMessage(reason: string): string {
+    const t = this.#messages
+    if (reason === 'native-unavailable') return t.nativeEditUnavailable
+    if (reason.startsWith('native-')) return t.nativeEditDraft
+    switch (reason) {
+      case 'page-multiple-files': return t.pageEditFiles
+      case 'page-boundary': return t.pageEditBoundary
+      case 'page-hierarchy': return t.pageEditHierarchy
+      case 'page-implicit-title': return t.pageEditImplicitTitle
+      case 'page-formatted-title': return t.pageEditFormattedTitle
+      case 'page-title': return t.pageEditInvalidTitle
+      case 'page-compiler': return t.pageEditCompiler
+      case 'page-referenced': return t.pageDeleteReferenced
+      case 'page-external-bindings': return t.pageDeleteExternalBindings
+      case 'page-references-unavailable': return t.pageDeleteReferencesUnavailable
+      case 'page-busy': return t.pageEditBusy
+      case 'preview-flush-unavailable': return t.pageEditPreview
+      case 'page-context-changed': return t.pageEditChanged
+      case 'save-timeout': return t.pageEditFlushTimeout
+      case 'source-draft': return t.pageEditSourceDraft
+      case 'source-refresh': return t.pageEditRefresh
+      case 'page-draft':
+      case 'source-conflict':
+      case 'narration-conflict':
+      case 'revision-conflict': return t.pageEditDraft
+      case 'save-locked': return t.saveLocked
+      default: return t.pageEditRequestFailed
+    }
+  }
+
+  pageEditCapability(section: string): { rename: boolean, move: boolean, reason?: string } {
+    const exists = Boolean(this.#state.authoring?.content?.sections[section])
+    const capability = { rename: exists, move: exists }
+    if (isAgentChanging(this.#state)) return { rename: false, move: false, reason: this.#messages.saveLocked }
+    if (this.#state.isCreatingPage || this.#state.isEditingPage || this.#state.isHistoryBusy) return { rename: false, move: false, reason: this.#messages.pageEditBusy }
+    return capability
+  }
+
+  clearPageEditFailure(): void { this.#set({ pageEditFailure: undefined }) }
+
+  /** The preview acknowledges that all registered lecture playback has paused before audition audio starts. */
+  pausePlayback(interactive = false): Promise<void> { if (interactive) this.#interruptProductionNavigation(); return this.#playback.pause() }
+
+  /** The owner must invalidate pending audio responses as well as stop its current audio element. */
+  registerAudition(stop: () => void): () => void { return this.#playback.registerAudition(stop) }
+  registerAudioCapture(stop: () => void): () => void { this.#interruptProductionNavigation(); return this.#playback.registerAudioCapture(stop) }
+
+  /** Inline runtimes join the same exclusive playback group as author auditions. */
+  startDocumentPlayback(stop: () => Promise<void>): Promise<() => void> { this.#interruptProductionNavigation(); return this.#playback.startDocumentPlayback(stop) }
+
+  stopAuditions(): void { this.#playback.stopAuditions() }
+
+  /** The latest source actor value, scoped to the field/editor that captured its identity. */
+  getDocument(identity?: string): TeachingDocument | undefined {
+    const source = this.#state.authoring
+    if (!source || source.loading || source.directory !== this.#state.document || identity !== undefined && identity !== source.identity) return undefined
+    return source.content
+  }
+  /** Native image uploads commit the original file without interrupting later text input. */
+  async importDocumentImage(file: File, identity: string, signal?: AbortSignal): Promise<string> {
+    if (!this.getDocument(identity) || isAgentChanging(this.#state)) throw new Error('document-identity-changed')
+    this.stopAuditions()
+    await this.pausePlayback()
+    await this.flushPendingEdits(signal)
+    if (!this.getDocument(identity) || isAgentChanging(this.#state)) throw new Error('document-identity-changed')
+    const answer = await this.#documentSession.importImage(file, identity, signal)
+    signal?.throwIfAborted()
+    const asset = this.getDocument(identity)?.assets[answer.assetId]
+    if (!asset || asset.kind !== 'image' || asset.location !== answer.content.assets[answer.assetId]?.location) throw new Error('document-identity-changed')
+    return asset.location
+  }
+  #mediaSource(expected: { identity: string, version: string }): DocumentSessionState {
+    const source = this.#state.authoring
+    if (!source || !this.getDocument(expected.identity) || source.version !== expected.version || !source.fingerprint
+      || source.dirty || source.saving || source.composing || source.restored || source.error || isAgentChanging(this.#state)) throw new Error('production-source-changed')
+    return source
+  }
+  /** Inspects the saved declaration, including a local asset not yet attached to a step. */
+  async inspectDocumentAudio(assetId: string, expected: { identity: string, version: string }, signal?: AbortSignal): Promise<DocumentAudioInspectionAnswer> {
+    const source = this.#mediaSource(expected), scope = this.#documentScope
+    const answer = await this.client.readDocumentAudio(source.directory, assetId, expected.version, signal)
+    signal?.throwIfAborted()
+    if (scope !== this.#documentScope || answer.document !== source.directory || answer.version !== expected.version || answer.fingerprint !== source.fingerprint || answer.inspection.assetId !== assetId) throw new Error('production-source-changed')
+    this.#mediaSource(expected)
+    return answer
+  }
+  /** Recognition keeps its captured source even if subsequent author input moves to a newer version. */
+  async startDocumentTranscription(request: Omit<DocumentTranscriptionRequest, 'source'>, expected: { identity: string, version: string }, signal?: AbortSignal): Promise<TranscriptionTask> {
+    const source = this.#mediaSource(expected)
+    if (!source.content || !source.fingerprint) throw new Error('production-source-changed')
+    const sent: DocumentTranscriptionRequest = { ...structuredClone(request), source: { documentId: source.content.id, version: expected.version, fingerprint: source.fingerprint } }
+    const answer = await this.client.startTranscription(source.directory, sent, signal)
+    signal?.throwIfAborted()
+    if (answer.document !== source.directory || answer.intent !== sent.intent || answer.source.documentId !== sent.source.documentId
+      || answer.source.version !== sent.source.version || answer.source.fingerprint !== sent.source.fingerprint || answer.audio.assetId !== sent.assetId || answer.audio.sha256 !== sent.audioSha256) throw new Error('transcription-response-changed')
+    return answer
+  }
+  async planDocumentTranscription(draft: TranscriptionAdoptionDraft, expected: { identity: string, version: string }, signal?: AbortSignal): Promise<TranscriptionAdoptionPlan> {
+    const source = this.#mediaSource(expected), sent = structuredClone(draft)
+    if (sent.source.documentId !== source.content?.id || sent.source.version !== expected.version || sent.source.fingerprint !== source.fingerprint) throw new Error('production-source-changed')
+    const answer = await this.client.planTranscriptionAdoption(source.directory, sent, signal)
+    signal?.throwIfAborted()
+    this.#mediaSource(expected)
+    if (answer.document !== source.directory || answer.changeId !== sent.id || answer.source.documentId !== sent.source.documentId
+      || answer.source.version !== sent.source.version || answer.source.fingerprint !== sent.source.fingerprint || answer.candidate.id !== sent.candidate.id
+      || answer.candidate.revision !== sent.candidate.revision || answer.draftRevision !== sent.draftRevision) throw new Error('transcription-response-changed')
+    return answer
+  }
+  async adoptDocumentTranscription(request: TranscriptionAdoptionApply, expected: { identity: string, version: string }, signal?: AbortSignal): Promise<TranscriptionAdoptionAnswer> {
+    const source = this.#mediaSource(expected), sent = structuredClone(request)
+    if (sent.source.documentId !== source.content?.id || sent.source.version !== expected.version || sent.source.fingerprint !== source.fingerprint) throw new Error('production-source-changed')
+    const answer = await this.#writeDocumentMedia(expected, directory => this.client.applyTranscriptionAdoption(directory, sent, signal), signal)
+    if (answer.adoption.planId !== sent.planId || answer.adoption.candidate.id !== sent.candidate.id || answer.adoption.candidate.revision !== sent.candidate.revision
+      || answer.adoption.draftRevision !== sent.draftRevision) throw new Error('transcription-response-changed')
+    return answer
+  }
+  async #writeDocumentMedia<T extends DocumentChangeAnswer>(expected: { identity: string, version: string }, write: (directory: string) => Promise<T>, signal?: AbortSignal): Promise<T> {
+    const scope = this.#documentScope, source = this.#mediaSource(expected)
+    this.stopAuditions()
+    await this.pausePlayback()
+    await this.flushPendingEdits(signal)
+    signal?.throwIfAborted()
+    if (scope !== this.#documentScope) throw new Error('production-source-changed')
+    this.#mediaSource(expected)
+    let answer: T
+    try { answer = await write(source.directory) }
+    finally { await this.#documentSession.refresh(source.directory) }
+    signal?.throwIfAborted()
+    if (scope !== this.#documentScope || answer.document !== source.directory || answer.content.id !== source.content?.id) throw new Error('production-source-changed')
+    this.#mediaSource({ identity: expected.identity, version: answer.version })
+    return answer
+  }
+  /** Import commits the original file and its declaration together, without creating a clip or narration. */
+  async importDocumentAudio(file: File, expected: { identity: string, version: string }, signal?: AbortSignal): Promise<DocumentAudioImportAnswer> {
+    let request: { identity: string, version: string, id: string } | undefined
+    const answer = await this.#writeDocumentMedia(expected, async directory => {
+      const existing = this.#audioImports.get(file), first = !existing || existing.identity !== expected.identity
+      request = first ? { identity: expected.identity, version: expected.version, id: crypto.randomUUID() } : existing!
+      this.#audioImports.set(file, request)
+      try { return await this.client.importDocumentAudio(directory, file, { id: request.id, baseDocumentVersion: request.version }, signal) }
+      catch (error) {
+        if (first && error instanceof WorkspaceServerError && error.status >= 400 && error.status < 500 && this.#audioImports.get(file) === request) this.#audioImports.delete(file)
+        throw error
+      }
+    }, signal)
+    if (answer.changeId !== request?.id || answer.inspection.assetId !== answer.assetId || !answer.content.assets[answer.assetId]) throw new Error('production-source-changed')
+    if (this.#audioImports.get(file) === request) this.#audioImports.delete(file)
+    return answer
+  }
+  /** Reconcile an ambiguous save against real asset bytes before admitting a new source-bound import. */
+  async ensureDocumentAudio(file: File, expected: { identity: string, version: string }, signal?: AbortSignal): Promise<DocumentAudioInspectionAnswer> {
+    const source = this.#mediaSource(expected)
+    if (!file.size || file.size > DOCUMENT_AUDIO_MAX_BYTES) throw new Error('production.asset-size')
+    let pending = this.#audioFingerprints.get(file)
+    if (!pending) {
+      pending = file.arrayBuffer().then(bytes => crypto.subtle.digest('SHA-256', bytes)).then(bytes => [...new Uint8Array(bytes)].map(value => value.toString(16).padStart(2, '0')).join(''))
+      this.#audioFingerprints.set(file, pending)
+    }
+    const hash = await pending
+    signal?.throwIfAborted(); this.#mediaSource(expected)
+    for (const asset of Object.values(source.content?.assets ?? {})) {
+      if (asset.kind !== 'audio' || asset.fingerprint !== `sha256:${hash}`) continue
+      try {
+        const answer = await this.inspectDocumentAudio(asset.id, expected, signal)
+        if (answer.inspection.sha256 === hash) return answer
+      } catch (error) {
+        if (!(error instanceof WorkspaceServerError) || ![404, 413, 422].includes(error.status)) throw error
+      }
+    }
+    signal?.throwIfAborted(); this.#mediaSource(expected)
+    const previous = this.#audioImports.get(file)
+    if (previous?.identity === expected.identity && previous.version !== expected.version) this.#audioImports.delete(file)
+    let imported: DocumentAudioImportAnswer
+    try { imported = await this.importDocumentAudio(file, expected, signal) }
+    catch (error) {
+      if (!previous || this.#audioImports.get(file) !== previous || !(error instanceof WorkspaceServerError)
+        || error.status !== 409 || error.message !== 'document-version-changed') throw error
+      signal?.throwIfAborted(); this.#mediaSource(expected)
+      this.#audioImports.delete(file)
+      imported = await this.importDocumentAudio(file, expected, signal)
+    }
+    return { document: imported.document, version: imported.version, fingerprint: imported.fingerprint, inspection: imported.inspection }
+  }
+  /** The source actor owns this external transaction; capture is independent from preview output. */
+  async adoptDocumentRecording(request: DocumentRecordingAdoption, expected: { identity: string, version: string }, signal?: AbortSignal): Promise<VerifiedDocumentRecordingAdoption> {
+    const scope = this.#documentScope, source = this.#mediaSource(expected), sent = structuredClone(request)
+    if (sent.source.documentId !== source.content?.id || sent.source.version !== source.version || sent.source.fingerprint !== source.fingerprint
+      || !source.content.steps[sent.stepId] || !source.content.assets[sent.assetId]) throw new Error('production-source-changed')
+    this.#playback.stopPreviewOutputs()
+    await this.pausePlayback()
+    await this.flushPendingEdits(signal)
+    signal?.throwIfAborted()
+    if (scope !== this.#documentScope) throw new Error('production-source-changed')
+    this.#mediaSource(expected)
+    const answer = await this.#documentSession.commitExternal(expected, async (_before, ownedSignal) => {
+      const saved = await this.client.adoptRecording(source.directory, sent, ownedSignal)
+      if (saved.changeId !== sent.id || saved.verification.stepId !== sent.stepId || saved.verification.assetId !== sent.assetId || saved.verification.sha256 !== sent.sha256) throw new Error('document-confirmation')
+      return saved
+    }, (before, remote, current) => reconcileRecordingAdoption(sent, before, remote, current), signal)
+    signal?.throwIfAborted()
+    if (scope !== this.#documentScope || this.#state.authoring?.identity !== expected.identity) throw new Error('production-source-changed')
+    return answer
+  }
+  async applyDocumentMediaClip(clip: MediaClip, expected: { identity: string, version: string, binding: ProductionBinding }, signal?: AbortSignal): Promise<DocumentChangeAnswer> {
+    this.#mediaSource(expected)
+    if (!this.#state.productionPlan || !sameProductionBinding(this.#state.productionPlan.binding, expected.binding) || !this.#productionSourceCurrent(expected.binding)) throw new Error('production-source-changed')
+    const id = crypto.randomUUID(), value = structuredClone(clip)
+    const answer = await this.#writeDocumentMedia(expected, directory => this.client.changeDocumentMediaClip(directory, { id, baseDocumentVersion: expected.version, binding: expected.binding, clip: value }, signal), signal)
+    if (answer.changeId !== id) throw new Error('production-source-changed')
+    return answer
+  }
+  async removeDocumentMediaClip(clipId: string, expected: { identity: string, version: string }, signal?: AbortSignal): Promise<DocumentChangeAnswer> {
+    const id = crypto.randomUUID()
+    const answer = await this.#writeDocumentMedia(expected, directory => this.client.changeDocumentMediaClip(directory, { id, baseDocumentVersion: expected.version, removeClipId: clipId }, signal), signal)
+    if (answer.changeId !== id) throw new Error('production-source-changed')
+    return answer
+  }
+  /** Applies a reviewed voice scope to the current source actor, without replacing body or narration. */
+  async applyDocumentVoice(scope: DocumentVoiceScope, value: VoiceSource | null, options: DocumentVoiceOptions, expected: { identity: string, version: string, fingerprint: string }): Promise<boolean> {
+    const source = this.#state.authoring, document = this.getDocument(expected.identity), context = this.#documentScope
+    if (!source || !document || source.version !== expected.version || source.fingerprint !== expected.fingerprint
+      || source.dirty || source.saving || source.composing || source.restored || source.error || isAgentChanging(this.#state)) throw new Error('voice-context-changed')
+    const next = changeDocumentVoice(document, scope, value, options)
+    if (next === document) return true
+    this.stopAuditions()
+    this.#documentSession.record(next)
+    await this.flushPendingEdits()
+    if (context !== this.#documentScope || this.#state.authoring?.identity !== expected.identity) return false
+    const saved = this.#state.authoring
+    if (!saved || saved.dirty || saved.saving || saved.composing || saved.restored || saved.error) throw new Error('voice-save-unconfirmed')
+    return true
+  }
+  /** Parameter planning is an authoring read; it does not compile, change modes or write the document. */
+  async planDocumentComponentAction(action: DocumentComponentAction, id: string, expected: { identity: string, version: string, fingerprint: string }, signal?: AbortSignal): Promise<DocumentAuthoringActionPlan> {
+    const source = this.#mediaSource(expected), scope = this.#documentScope
+    if (!source.content || !source.fingerprint || source.fingerprint !== expected.fingerprint) throw new Error('component-source-changed')
+    const request = { id, source: componentSource({ content: source.content, version: source.version!, fingerprint: source.fingerprint }), action: structuredClone(action) }
+    const answer = await this.client.planDocumentAction(source.directory, request, signal)
+    signal?.throwIfAborted()
+    const current = this.#mediaSource(expected)
+    if (scope !== this.#documentScope || !current.content || !current.fingerprint || answer.document !== source.directory || answer.changeId !== id || answer.effect.kind !== 'component'
+      || !sameComponentSource(answer.source, request.source) || JSON.stringify(answer.action) !== JSON.stringify(request.action)) throw new Error('component-source-changed')
+    return answer
+  }
+  /** The existing source actor owns adoption and ambiguous-response recovery, including later native input. */
+  async applyDocumentComponentPlan(plan: DocumentAuthoringActionPlan, expected: { identity: string, version: string }, signal?: AbortSignal): Promise<{ answer: DocumentChangeAnswer, commitId?: string }> {
+    if (plan.effect.kind !== 'component' || !plan.action.type.startsWith('component.')) throw new Error('component-plan-invalid')
+    const source = this.#mediaSource(expected), action = plan.action as DocumentComponentAction, scope = this.#documentScope
+    if (!source.content || !source.fingerprint || !sameComponentSource(plan.source, componentSource({ content: source.content, version: source.version!, fingerprint: source.fingerprint }))) throw new Error('component-source-changed')
+    this.#playback.stopPreviewOutputs()
+    await this.pausePlayback()
+    let receipt: AppliedDocumentAuthoringAction | undefined
+    const remember = (answer: DocumentChangeAnswer) => {
+      if (this.#documentEditorBinding?.identity === expected.identity) this.#documentEditorCommands?.rememberComponentConfiguration(answer.content)
+      return { answer, ...receipt?.commit ? { commitId: receipt.commit.id } : {} }
+    }
+    try {
+      const answer = await this.#documentSession.commitExternal(expected, async (_before, ownedSignal) => {
+        receipt = await this.client.applyDocumentAction(source.directory, { planId: plan.planId, digest: plan.digest, source: plan.source }, ownedSignal)
+        const current = await this.client.readDocument(source.directory)
+        if (receipt.planId !== plan.planId || receipt.digest !== plan.digest || receipt.changeId !== plan.changeId || receipt.action !== plan.action.type
+          || !receipt.verification.saved || !receipt.verification.actionStateVerified || !sameComponentSource(receipt.verification.source, componentSource(current))) throw new Error('document-confirmation')
+        return { ...current, changeId: receipt.changeId, files: receipt.files }
+      }, (before, answer, current) => reconcileComponentAction(action, before, answer, current), signal)
+      if (scope !== this.#documentScope || this.#state.authoring?.identity !== expected.identity) throw new Error('component-source-changed')
+      return remember(answer)
+    } catch (error) {
+      const current = this.#state.authoring, file = plan.files.find(value => value.path === (source.directory ? `${source.directory}/lecture.json` : 'lecture.json'))
+      // commitExternal has independently read and reconciled this exact predicted canonical version.
+      if (scope === this.#documentScope && current?.identity === expected.identity && current.content && current.version && current.fingerprint && !current.error
+        && file?.version === current.version && current.version !== plan.source.version) {
+        // Canonical acceptance is already known even when later native input has
+        // deleted the target. Undoing that deletion must restore its accepted configuration.
+        if (this.#documentEditorBinding?.identity === expected.identity) this.#documentEditorCommands?.rememberComponentConfiguration(plan.content)
+        try {
+          if (!applyDocumentComponentAction(current.content, action).effect.changed) return remember({ document: source.directory, content: plan.content,
+            version: current.version, fingerprint: current.fingerprint, issues: plan.issues, changeId: plan.changeId, files: plan.files.map(value => ({ path: value.path, version: value.version })) })
+        } catch { /* A later conflicting input keeps the original request failure and form draft. */ }
+      }
+      throw error
+    }
+  }
+  /** Manual caption times reuse the canonical action plan, media preflight and original source actor. */
+  async applyDocumentCaptionTiming(action: DocumentCaptionTimingAction, id: string, expected: { identity: string, version: string, fingerprint: string }, signal?: AbortSignal): Promise<DocumentChangeAnswer> {
+    const source = this.#mediaSource(expected), scope = this.#documentScope
+    if (!source.content || source.fingerprint !== expected.fingerprint) throw new Error('caption-source-changed')
+    const request = { id, source: componentSource({ content: source.content, version: source.version!, fingerprint: source.fingerprint! }), action }
+    const plan = await this.client.planDocumentAction(source.directory, request, signal)
+    signal?.throwIfAborted()
+    if (scope !== this.#documentScope || this.#state.authoring?.identity !== expected.identity || plan.effect.kind !== 'caption'
+      || plan.changeId !== id || JSON.stringify(plan.action) !== JSON.stringify(action) || !sameComponentSource(plan.source, request.source)) throw new Error('caption-source-changed')
+    this.#playback.stopPreviewOutputs()
+    await this.pausePlayback()
+    try {
+      return await this.#documentSession.commitExternal(expected, async (_before, ownedSignal) => {
+        const receipt = await this.client.applyDocumentAction(source.directory, { planId: plan.planId, digest: plan.digest, source: plan.source }, ownedSignal)
+        const actual = await this.client.readDocument(source.directory)
+        if (receipt.planId !== plan.planId || receipt.digest !== plan.digest || receipt.changeId !== id || !receipt.verification.saved || !receipt.verification.actionStateVerified
+          || !sameComponentSource(receipt.verification.source, componentSource(actual))) throw new Error('document-confirmation')
+        return { ...actual, changeId: id, files: receipt.files }
+      }, (before, answer, current) => reconcileCaptionTiming(action, before, answer, current), signal)
+    } catch (error) {
+      const current = this.#state.authoring, file = plan.files.find(file => file.path === (source.directory ? `${source.directory}/lecture.json` : 'lecture.json'))
+      // Lost ACK was independently read by commitExternal; only the exact predicted saved version can settle it.
+      if (scope === this.#documentScope && current?.identity === expected.identity && current.content && current.version === file?.version && current.fingerprint && !current.error) {
+        try {
+          if (!applyDocumentCaptionTiming(current.content, action).effect.changed) return { document: source.directory, content: plan.content, version: current.version!, fingerprint: current.fingerprint, changeId: id, issues: plan.issues, files: plan.files.map(({ path, version }) => ({ path, version })) }
+        } catch { /* A newer target stays pending with the actual request error. */ }
+      }
+      throw error
+    }
+  }
+  /** Uses the current actor revision so timing edits cannot replace later body or narration input. */
+  setDocumentStepProduction(stepId: string, patch: StepTimingPatch, identity?: string): void {
+    const document = this.getDocument(identity)
+    if (!document || isAgentChanging(this.#state)) return
+    const next = changeStepTiming(document, stepId, patch)
+    if (next === document) return
+    this.stopAuditions()
+    this.#documentSession.record(next)
+  }
+  documentTimingDraft(stepId: string, key: StepDurationKey, identity: string, reset: number): StepDurationDraft | undefined {
+    const document = this.getDocument(identity)
+    return document && this.#state.authoring?.reset === reset ? this.#documentTimingDrafts.get(identity, document, stepId, key) : undefined
+  }
+  /** Retains unaccepted numeric input by stable target; it is not authoring content or a second timing source. */
+  setDocumentTimingDraft(stepId: string, key: StepDurationKey, draft: StepDurationDraft | undefined, identity: string, reset: number): void {
+    const source = this.#state.authoring, document = this.getDocument(identity)
+    if (!document?.steps[stepId] || source?.reset !== reset || isAgentChanging(this.#state)) return
+    if (!this.#documentTimingDrafts.set(identity, document, stepId, key, draft)) return
+    this.#set({ authoring: { ...source }, hasDocumentTimingDrafts: this.#documentTimingDrafts.has(identity, document), documentTimingDraftStorageFailure: this.#documentTimingDrafts.failed })
+  }
+  captionTimingDraft(stepId: string, identity: string): CaptionTimingDraft | undefined {
+    const source = this.#state.authoring
+    return source?.identity === identity && source.member?.id ? this.#captionTimingDrafts.get({ identity, memberId: source.member.id }, stepId) : undefined
+  }
+  setCaptionTimingDraft(stepId: string, draft: CaptionTimingDraft | undefined, identity: string): void {
+    const source = this.#state.authoring, document = this.getDocument(identity)
+    if (!document?.steps[stepId] || source?.identity !== identity || !source.member?.id) return
+    const scope = { identity, memberId: source.member.id }
+    this.#captionTimingDrafts.set(scope, stepId, draft)
+    this.#set({ captionTimingDraftSteps: this.#captionTimingDrafts.steps(scope, document), captionTimingDraftStorageFailure: this.#captionTimingDrafts.failed(scope) })
+  }
+  /** Changes one stable narration target without replacing the body editor or derived captions. */
+  setDocumentNarration(stepId: string, narrationId: string | undefined, content: NarrationNode[], identity?: string): string | undefined {
+    const document = this.getDocument(identity)
+    if (!document || isAgentChanging(this.#state) || !Object.hasOwn(document.steps, stepId)) return undefined
+    const step = document.steps[stepId]!
+    if (!document.sections[step.sectionId]?.stepOrder.includes(stepId)) return undefined
+    if (!Array.isArray(content)) throw new Error('document-narration-content')
+    let meaningful = false
+    for (const node of content) {
+      if (!node || typeof node !== 'object') throw new Error('document-narration-content')
+      if (node.type === 'text' && typeof node.text === 'string') meaningful ||= Boolean(node.text.trim())
+      else if (node.type === 'pronunciation' && typeof node.display === 'string' && typeof node.spoken === 'string') meaningful ||= Boolean(node.display.trim() || node.spoken.trim())
+      else if (node.type === 'cue' && typeof node.id === 'string' && node.id && typeof node.action === 'string' && node.action) meaningful = true
+      else throw new Error('document-narration-content')
+    }
+    const target = narrationId ?? step.narrationIds[0]
+    const existing = target !== undefined && Object.hasOwn(document.narrations, target) ? document.narrations[target] : undefined
+    if (existing && !step.narrationIds.includes(existing.id)) throw new Error('document-narration-target')
+    if (!existing && !meaningful) return undefined
+    const id = target ?? crypto.randomUUID()
+    if (!id || id.length > 200 || /[\u0000-\u001f]/.test(id) || ['__proto__', 'constructor', 'prototype'].includes(id)) throw new Error('document-narration-target')
+    if (!existing && (document.id === id || [document.sections, document.blocks, document.steps, document.assets, document.definitions].some(map => Object.hasOwn(map, id)))) throw new Error('document-narration-target')
+    if (existing && JSON.stringify(existing.content) === JSON.stringify(content)) return id
+    const next: TeachingDocument = { ...document,
+      narrations: { ...document.narrations, [id]: { ...existing, id, content: structuredClone(content) } },
+      ...step.narrationIds.includes(id) ? {} : { steps: { ...document.steps, [stepId]: { ...step, narrationIds: [...step.narrationIds, id] } } },
+    }
+    const cueIds = new Set(content.flatMap(node => node.type === 'cue' ? [node.id] : []))
+    const previousCues = new Set(existing?.content.flatMap(node => node.type === 'cue' ? [node.id] : []) ?? [])
+    if (document.production.cueTimings) {
+      const removed = [...previousCues].filter(cue => !cueIds.has(cue) && Object.hasOwn(document.production.cueTimings!, cue)
+        && !Object.values(next.narrations).some(narration => narration.content.some(node => node.type === 'cue' && node.id === cue)))
+      if (removed.length) {
+        const cueTimings = { ...document.production.cueTimings }
+        for (const cue of removed) {
+          this.#removedCueTimings.delete(cue)
+          this.#removedCueTimings.set(cue, { ...cueTimings[cue]! })
+          delete cueTimings[cue]
+        }
+        while (this.#removedCueTimings.size > 512) this.#removedCueTimings.delete(this.#removedCueTimings.keys().next().value!)
+        next.production = { ...document.production, cueTimings }
+      }
+    }
+    for (const cue of cueIds) {
+      const timing = this.#removedCueTimings.get(cue)
+      if (!previousCues.has(cue) && timing && !Object.hasOwn(next.production.cueTimings ?? {}, cue)) {
+        next.production = { ...next.production, cueTimings: { ...next.production.cueTimings, [cue]: { ...timing } } }
+        this.#removedCueTimings.delete(cue)
+      }
+    }
+    this.stopAuditions()
+    this.#documentSession.record(next)
+    return id
+  }
+  recordDocument(content: TeachingDocument): void { if (!isAgentChanging(this.#state)) this.#documentSession.record(content) }
+  documentComposition(composing: boolean, owner = 'body', identity?: string): void { this.#documentSession.composition(composing, owner, identity) }
+  retryDocument(): Promise<void> { return this.#documentSession.retry() }
+  discardDocument(): Promise<void> { return this.#documentSession.discard() }
+  recoverDocumentDraft(value: DocumentDraftReference, identity: string): Promise<void> {
+    return this.#state.authoring?.identity === identity && !isAgentChanging(this.#state) ? this.#documentSession.recoverDraft(value) : Promise.resolve()
+  }
+  forgetDocumentDraft(value: DocumentDraftReference, identity: string): void {
+    if (this.#state.authoring?.identity === identity && !isAgentChanging(this.#state)) void this.#documentSession.forgetDraft(value)
+  }
+  documentError(error: Error): void { this.#set({ save: { kind: 'failed', message: error.message } }) }
+  documentInteraction(): void {
+    this.#documentSelectionGeneration++; this.#cancelOpeningDocument(); this.#stopDocumentReturnScroll?.()
+    if (this.#state.documentPositionFailure) this.#set({ documentPositionFailure: undefined })
+  }
+  pendingDocumentField(blockId: string | undefined, identity?: string): Pick<DocumentFieldRegistration, 'stepId' | 'narrationId' | 'slot'> | undefined {
+    const pending = this.#pendingDocumentField, source = this.#state.authoring
+    return pending && pending.generation === this.#documentSelectionGeneration && pending.field.blockId === blockId
+      && pending.field.identity === (identity ?? source?.identity) && pending.reset === source?.reset ? pending.field : undefined
+  }
+  /** A live native field owns its target only while it still has focus in this source. */
+  focusedDocumentField(): Readonly<Pick<DocumentFieldRegistration, 'identity' | 'reset' | 'blockId' | 'stepId' | 'narrationId' | 'slot'>> & { readonly editor: DocumentHistoryEditor } | undefined {
+    const source = this.#state.authoring, editor = this.#activeDocumentHistory
+    if (!source?.identity || !source.content || !editor || editor === this.#documentEditor || editor.prosemirrorView.isDestroyed || !editor.prosemirrorView.hasFocus()) return
+    for (const field of this.#documentFields.values()) {
+      if (field.editor !== editor || field.identity !== source.identity || field.reset !== source.reset) continue
+      const step = source.content.steps[field.stepId], section = step && source.content.sections[step.sectionId]
+      if (!step || !section?.stepOrder.includes(field.stepId) || field.slot < 0 || field.slot >= Math.max(1, step.narrationIds.length)
+        || step.narrationIds[field.slot] !== undefined && step.narrationIds[field.slot] !== field.narrationId) return
+      const { identity, reset, blockId, stepId, narrationId, slot } = field
+      return { identity, reset, blockId, stepId, narrationId, slot, editor }
+    }
+    return undefined
+  }
+  registerDocumentField(field: DocumentFieldRegistration): () => void {
+    if (field.identity !== this.#state.authoring?.identity || field.reset !== this.#state.authoring.reset) return () => {}
+    const key = JSON.stringify([field.identity, field.blockId, field.stepId, field.slot, field.narrationId])
+    this.#documentFields.set(key, field)
+    const pending = this.#pendingDocumentField
+    if (pending && pending.reset === field.reset && JSON.stringify([pending.field.identity, pending.field.blockId, pending.field.stepId, pending.field.slot, pending.field.narrationId]) === key) {
+      this.#pendingDocumentField = undefined
+      if (pending.generation === this.#documentSelectionGeneration && field.identity === this.#state.authoring?.identity && field.reset === this.#state.authoring.reset) field.focus.restore(pending.bookmark)
+    }
+    return () => {
+      if (this.#documentFields.get(key) !== field) return
+      this.#documentFields.delete(key)
+      if (field.editor && this.#activeDocumentHistory === field.editor) this.activateDocumentHistory(this.#documentEditor)
+    }
+  }
+  /** Toolbar commands use the focused native editor's own history, without replacing the body editor. */
+  activateDocumentHistory(editor: DocumentHistoryEditor | undefined): void {
+    if (editor && editor !== this.#documentEditor && ![...this.#documentFields.values()].some(field => field.editor === editor && field.identity === this.#state.authoring?.identity)) return
+    if (editor === this.#activeDocumentHistory) return
+    this.#unsubscribeDocumentHistory?.()
+    this.#activeDocumentHistory = editor
+    const update = () => this.#set({ editorHistory: editor ? { section: this.#state.position?.section ?? '', undo: undoDepth(editor.prosemirrorState) > 0, redo: redoDepth(editor.prosemirrorState) > 0, field: editor !== this.#documentEditor } : undefined })
+    this.#unsubscribeDocumentHistory = editor?.onChange(update)
+    update()
+  }
+  attachDocumentEditor(editor: NativeDocumentEditor | undefined, commands?: DocumentEditorCommands, binding?: { identity: string, reset: number }): void {
+    if (binding && (binding.identity !== this.#state.authoring?.identity || binding.reset !== this.#state.authoring.reset)) return
+    const wasBody = !this.#activeDocumentHistory || this.#activeDocumentHistory === this.#documentEditor
+    if (editor !== this.#documentEditor) this.#documentSession.composition(false, 'body')
+    this.#unsubscribeDocumentSelection?.(); this.#stopDocumentLayoutScroll?.(); this.#stopDocumentLayoutScroll = undefined
+    this.#documentEditor = editor; this.#documentEditorCommands = commands; this.#documentEditorBinding = editor ? binding : undefined
+    if (editor) {
+      const focus = this.#pendingDocumentFocus, selection = this.#pendingDocumentSelection
+      this.#pendingDocumentFocus = undefined; this.#pendingDocumentSelection = undefined
+      if (focus && focus.documentId === this.#state.authoring?.content?.id && focus.generation === this.#documentSelectionGeneration && editor.getBlock(focus.nodeId)) {
+        // A deferred page operation adopts its selection only after the source write is acknowledged.
+        if (!focus.afterSave) {
+          this.#focusDocumentNode(editor, focus.nodeId)
+        }
+      } else if (!this.#pendingDocumentField && selection && selection.documentId === this.#state.authoring?.content?.id) {
+        const anchor = nativeTextPosition(editor, selection.anchor), head = nativeTextPosition(editor, selection.head)
+        if (anchor !== undefined && head !== undefined) {
+          editor.transact(transaction => transaction.setSelection(TextSelection.create(transaction.doc, anchor, head)))
+          if (selection.focused) editor.focus()
+        }
+      }
+    }
+    if (wasBody) this.activateDocumentHistory(editor)
+    if (editor) {
+      const focus = () => this.activateDocumentHistory(editor)
+      const element = editor.prosemirrorView.dom
+      element.addEventListener('focusin', focus)
+      if (editor.prosemirrorView.hasFocus()) focus()
+      const stopSelection = editor.onSelectionChange(() => { this.#documentSelectionGeneration++ })
+      this.#unsubscribeDocumentSelection = () => { this.#stopDocumentLayoutScroll?.(); stopSelection(); element.removeEventListener('focusin', focus) }
+    } else this.#unsubscribeDocumentSelection = undefined
+    this.#finishOpeningDocument()
+  }
+  #focusDocumentNode(editor: NativeDocumentEditor, nodeId: string): void {
+    this.#stopDocumentLayoutScroll?.(); this.#stopDocumentLayoutScroll = undefined
+    editor.setTextCursorPosition(nodeId, 'start')
+    editor.focus()
+    editor.prosemirrorView.dispatch(editor.prosemirrorState.tr.scrollIntoView())
+    // React node views can finish sizing after the native editor mounts.
+    // Keep only this untouched focus visible through those layout changes.
+    if (typeof ResizeObserver !== 'undefined') {
+      const view = editor.prosemirrorView, document = view.dom.ownerDocument
+      const source = this.#state.authoring!, identity = source.identity, reset = source.reset, documentId = source.content!.id
+      const request = this.#state.documentNavigation?.request, selected = editor.prosemirrorState.selection
+      let size = view.dom.getBoundingClientRect(), active = true
+      const events = ['pointerdown', 'wheel', 'touchmove', 'keydown', 'beforeinput']
+      const cancel = () => {
+        if (!active) return
+        active = false; observer.disconnect(); stopFocus(); stopSelection()
+        for (const event of events) document.removeEventListener(event, interact, true)
+      }
+      const interact = (event: Event) => { if (event.isTrusted) cancel() }
+      const stopFocus = editor.onFocusChange((_, { focused }) => { if (!focused) cancel() })
+      const stopSelection = editor.onSelectionChange(cancel)
+      const observer = new ResizeObserver(() => {
+        if (!active) return
+        const current = this.#state.authoring
+        if (this.#documentEditor !== editor || view.isDestroyed || !current || current.identity !== identity || current.reset !== reset
+          || current?.content?.id !== documentId || this.#state.documentNavigation?.request !== request
+          || !editor.isFocused() || !editor.prosemirrorState.selection.eq(selected) || editor.getTextCursorPosition().block.id !== nodeId) { cancel(); return }
+        const next = view.dom.getBoundingClientRect()
+        if (next.width === size.width && next.height === size.height) return
+        size = next
+        view.dispatch(editor.prosemirrorState.tr.scrollIntoView())
+      })
+      for (const event of events) document.addEventListener(event, interact, true)
+      observer.observe(view.dom)
+      this.#stopDocumentLayoutScroll = cancel
+    }
+  }
+  async flushPendingEdits(signal?: AbortSignal): Promise<void> {
+    if (isAgentChanging(this.#state)) throw new Error('save-locked')
+    await this.#documentSession.flush(signal)
+  }
+  async #changeDocumentPage(change: (document: TeachingDocument) => void): Promise<boolean> {
+    const source = this.#state.authoring, directory = this.#state.document
+    if (!source?.content || directory === undefined || isAgentChanging(this.#state)) return false
+    const scope = this.#documentScope, identity = source.identity, documentId = source.content.id
+    const current = () => scope === this.#documentScope && directory === this.#state.document && identity === this.#state.authoring?.identity && documentId === this.#state.authoring?.content?.id
+    this.#set({ isEditingPage: true, pageEditFailure: undefined })
+    try {
+      await this.flushPendingEdits()
+      if (!current()) throw new Error('page-context-changed')
+      const document = structuredClone(this.#state.authoring!.content!)
+      change(document)
+      const editor = this.#documentEditor
+      this.#pendingDocumentField = undefined
+      const plannedFocus = this.#pendingDocumentFocus
+      if (!plannedFocus || plannedFocus.generation !== this.#documentSelectionGeneration) for (const field of this.#documentFields.values()) {
+        if (field.identity !== source.identity || field.reset !== this.#state.authoring!.reset || field.blockId !== undefined && !document.blocks[field.blockId] || !document.steps[field.stepId]) continue
+        const bookmark = field.focus.capture()
+        if (bookmark) {
+          const { focus: _focus, editor: _editor, ...target } = field
+          this.#pendingDocumentField = { field: target, bookmark, reset: this.#state.authoring!.reset + 1, generation: this.#documentSelectionGeneration }
+          this.#pendingDocumentSelection = undefined
+          break
+        }
+      }
+      if (editor && !this.#pendingDocumentField) {
+        const state = editor.prosemirrorState, anchor = nativeTextPoint(editor, state.selection.anchor), head = nativeTextPoint(editor, state.selection.head)
+        if (anchor && head) this.#pendingDocumentSelection = { documentId: document.id, anchor, head, focused: editor.prosemirrorView.hasFocus() }
+      }
+      this.#documentSession.replace(document)
+      await this.#documentSession.flush()
+      return current()
+    } catch (error) { if (current()) this.#set({ pageEditFailure: this.#pageEditMessage(errorMessage(error)) }); return false }
+    finally { if (current()) this.#set({ isEditingPage: false }) }
+  }
+  renamePage(section: string, title: string): Promise<boolean> {
+    return this.#changeDocumentPage(document => { Object.assign(document, renameDocumentPage(document, section, title)) })
+  }
+  async duplicatePage(section: string): Promise<boolean> {
+    if (this.#state.isEditingPage || this.#state.isCreatingPage || this.#state.isHistoryBusy) return false
+    const scope = this.#documentScope, identity = this.#state.authoring?.identity, generation = this.#documentSelectionGeneration, navigation = this.#state.documentNavigation?.request
+    let copied: string | undefined
+    const saved = await this.#changeDocumentPage(document => {
+      if (scope !== this.#documentScope || identity !== this.#state.authoring?.identity) throw new Error('page-context-changed')
+      const page = document.sections[section]
+      if (!page) throw new Error('page-boundary')
+      const copy = duplicateDocumentPage(document, section, contentText(document.metadata.lang).copyTitle(page.title), () => crypto.randomUUID())
+      copied = copy.section
+      Object.assign(document, copy.document)
+      if (generation === this.#documentSelectionGeneration) this.#pendingDocumentFocus = { documentId: document.id, nodeId: `page:${copied}`, generation, afterSave: true }
+    })
+    // Source confirmation owns editing. A later author selection takes precedence over this response.
+    if (!saved || !copied || scope !== this.#documentScope || generation !== this.#documentSelectionGeneration || navigation !== this.#state.documentNavigation?.request || !this.#state.authoring?.content?.sections[copied]) return saved
+    this.goToSection(copied)
+    const editor = this.#documentEditor
+    if (editor) {
+      const blocks = editor.document, start = blocks.findIndex(block => block.id === `page:${copied}`)
+      const first = (nodes: typeof blocks): string | undefined => {
+        for (const node of nodes) { if (node.type === 'presmiumPage') break; if (node.content !== undefined) return node.id; const child = first(node.children); if (child) return child }
+        return undefined
+      }
+      const target = start < 0 ? undefined : first(blocks.slice(start + 1)) ?? blocks[start]!.id
+      if (target) { editor.setTextCursorPosition(target, 'start'); editor.focus() }
+    }
+    return true
+  }
+  movePage(section: string, before: string | null): Promise<boolean> {
+    return this.#changeDocumentPage(document => { Object.assign(document, moveDocumentPage(document, section, before)) })
+  }
+  pageDeleteMessage(reason: string): string { return this.#pageEditMessage(reason) }
+  async preparePageDeletion(section: string): Promise<PageDeletePlan> {
+    await this.flushPendingEdits()
+    const source = this.#state.authoring
+    if (!source?.content || !source.version || this.#state.document === undefined) throw new Error('document-unavailable')
+    return pageDeletion(source.content, this.#state.document, source.version, section)
+  }
+  async deletePage(plan: PageDeletePlan): Promise<boolean> {
+    if (!plan.allowed || plan.document !== this.#state.document) return false
+    return this.#changeDocumentPage(document => {
+      if (this.#state.authoring?.version !== plan.source.version) throw new Error('revision-conflict')
+      const current = pageDeletion(document, plan.document, plan.source.version, plan.section)
+      if (!current.allowed) throw new Error(current.reason)
+      Object.assign(document, removeDocumentPage(document, plan.section, () => crypto.randomUUID()))
+      this.#set({ position: { section: document.sectionOrder[0]!, step: 0, trail: [], view: 'document' }, documentNavigation: { section: document.sectionOrder[0]!, request: crypto.randomUUID() } })
+    })
+  }
+  createPage(after = this.#state.position?.section): boolean {
+    const source = this.#state.authoring, editor = this.#documentEditor, commands = this.#documentEditorCommands
+    if (!source?.content || source.loading || source.composing || source.restored || source.error || !editor || !commands
+      || editor.prosemirrorView.isDestroyed || isAgentChanging(this.#state) || this.#state.isEditingPage || this.#state.isCreatingPage
+      || this.#state.isHistoryBusy || this.#state.isHistoryPreparing) return false
+    try {
+      this.#set({ pageEditFailure: undefined })
+      const created = commands.insertPage(after, contentText(source.content.metadata.lang).newPage)
+      this.#pendingDocumentField = undefined; this.#pendingDocumentSelection = undefined; this.#pendingDocumentFocus = undefined
+      this.#set({ position: { section: created.sectionId, step: 0, trail: [], view: 'document' }, documentNavigation: { section: created.sectionId, request: crypto.randomUUID() } })
+      this.#focusDocumentNode(editor, created.nodeId)
+      return true
+    } catch (error) { this.#set({ pageEditFailure: this.#pageEditMessage(errorMessage(error)) }); return false }
+  }
+
+  /** Points at a block or a passage (none: stops pointing): the preview outlines it and the conversation is told. */
+  point(pointer: Pointer | undefined): void {
+    const pointed = this.#state.pointer !== undefined || this.#state.focus.length > 0
+    if (pointer) this.#record('point', { 'presmium.section': pointer.target.section, 'presmium.block': pointer.target.block, 'presmium.step': pointer.step, 'presmium.quote': pointer.quote, 'presmium.editable': pointer.isEditable })
+    this.#set({ pointer, askFailure: undefined })
+    this.#broadcast({ type: 'highlight', target: pointer?.target ?? null })
+    if (pointer) this.setFocus([this.#focusReportOf(pointer)])
+    else if (pointed) this.setFocus([])
+  }
+
+  #focusReportOf(pointer: Pointer): FocusReport {
+    const { target, step, quote } = pointer
+    return { id: 'selection', from: this.#state.previewRenderer, section: target.section, ...target.block ? { block: target.block } : {}, ...step === undefined ? {} : { step }, ...quote ? { quote: quote.slice(0, 2000) } : {} }
+  }
+
+  setFocus(focus: FocusReport[]): void {
+    const document = this.#state.document
+    if (document === undefined) return
+    const version = ++this.#focusVersion
+    this.#set({ focus, isFocusPending: true, focusFailure: undefined })
+    this.#focusWriting = this.#focusWriting.then(async () => {
+      if (version !== this.#focusVersion) return
+      try {
+        const answer = await this.client.writeFocus(document, focus)
+        if (version === this.#focusVersion && document === this.#state.document) this.#set({ focus: answer.focus ?? [], isFocusPending: false })
+      } catch (error) {
+        if (version === this.#focusVersion && document === this.#state.document) this.#set({ isFocusPending: false, focusFailure: errorMessage(error) })
+      }
+    })
+  }
+
+  /** Hands `instruction` about what the author points at (or `focus`) to the conversation's agent. */
+  askAgent(instruction: string, focus: FocusReport[] = this.#state.pointer ? [this.#focusReportOf(this.#state.pointer)] : []): Promise<boolean> {
+    return this.#ask('request', focus, places => this.#messages.agentRequest(instruction, [...places.values()]))
+  }
+
+  /**
+   * Sets `focus` as the document's focus, then sends the agent the message `compose` writes from the places, by focus id.
+   * The message names places as the author sees them; the agent's document context has their source ranges.
+   */
+  async #ask(kind: 'request' | 'comments', focus: FocusReport[], compose: (places: Map<string, AgentPlace>) => string): Promise<boolean> {
+    const document = this.#state.document
+    const asker = [...this.#askers][0]
+    if (document === undefined) return false
+    // The request's id joins the operation to the conversation: the session's user message carries it, and its turn follows.
+    const asked = (attributes: Record<string, OperationValue>) => this.#record('agent.ask', { 'presmium.ask.kind': kind, 'presmium.focus': focus.map(item => [item.id, item.section, item.block].filter(Boolean).join(':')).join('\n'), ...attributes })
+    if (!asker) {
+      asked({ 'presmium.outcome': 'no-conversation' })
+      this.#set({ askFailure: 'no-conversation' })
+      return false
+    }
+    this.#set({ isAsking: true, askFailure: undefined })
+    let text: string | undefined
+    try {
+      if (focus.length > 0) {
+        this.setFocus(focus)
+        await this.#focusWriting
+      }
+      const located = this.#state.focus as (FocusReport & Partial<Focus>)[]
+      const places = new Map(located.map(item => [item.id, this.#describe(item)]))
+      text = compose(places)
+      const answer = await asker({ text, focus })
+      asked({ 'presmium.ask.text': text, 'presmium.outcome': 'sent', 'dsh.session.id': answer?.session, 'dsh.request.id': answer?.request })
+      if (this.#state.document === document) this.#set({ isAsking: false, pointer: undefined })
+      this.#broadcast({ type: 'highlight', target: null })
+      return true
+    } catch (error) {
+      asked({ 'presmium.ask.text': text, 'presmium.outcome': 'failed', 'presmium.error': errorMessage(error) })
+      if (this.#state.document === document) this.#set({ isAsking: false, askFailure: errorMessage(error) })
+      return false
+    }
+  }
+
+  /** A place as the author sees it: the section's title and the passage. */
+  #describe(item: FocusReport & Partial<Focus>): AgentPlace {
+    const doc = this.#state.ir?.doc
+    const section = item.section ? doc?.sections.find(s => s.id === item.section)?.title ?? item.section : undefined
+    const quote = item.quote ?? item.excerpt
+    return { ...section ? { section } : {}, ...quote ? { quote: quote.slice(0, 1500) } : {} }
+  }
+
+  /** Shows a section, or a block of it, in the preview (the next one attached, when none is). */
+  revealPlace(section: string, block?: string): void {
+    this.#record('reveal.place', { 'presmium.section': section, 'presmium.block': block })
+    const target: PreviewAnchor = { section, ...block ? { block } : {} }
+    if (this.#previewSinks.size === 0) {
+      this.#pendingReveal = target
+      return
+    }
+    this.#broadcast({ type: 'go', section })
+    this.#broadcast({ type: 'highlight', target })
+  }
+
+  /** Shows a section in the preview: from the navigation pane, the section to read or the slide to show. */
+  goToSection(section: string): void {
+    if (this.#state.webView === 'document' && this.#state.authoring?.content?.sections[section]) {
+      this.#set({ position: { section, step: 0, trail: [], view: 'document' }, documentPositionFailure: undefined, documentNavigation: { section, request: crypto.randomUUID() } }); return
+    }
+    this.goToStep(section, this.#selectedSteps.get(`${this.#state.document}\0${section}`) ?? 0)
+  }
+
+  /** Material references locate a canonical block in Doc without entering a runtime view or rewriting selection. */
+  revealDocumentComponent(blockId: string, identity: string): void {
+    const source = this.#state.authoring, document = this.getDocument(identity)
+    if (!document || source?.identity !== identity || this.#state.webView !== 'document' || document.blocks[blockId]?.type !== 'component') return
+    const sectionId = documentComponentSection(document, blockId), section = document.sections[sectionId]!
+    const current = this.#state.position?.section === sectionId ? this.#state.position.step : this.#selectedSteps.get(`${this.#state.document}\0${sectionId}`) ?? 0
+    const visible = (index: number) => Boolean(section.stepOrder[index] && effectiveComponentParameters(document, blockId, section.stepOrder[index]).visual?.visible)
+    const step = visible(current) ? current : Math.max(0, section.stepOrder.findIndex((_, index) => visible(index)))
+    this.#set({ position: { section: sectionId, step, trail: [], view: 'document' }, documentPositionFailure: undefined,
+      documentNavigation: { section: sectionId, block: blockId, request: crypto.randomUUID() } })
+  }
+
+  observeDocumentSection(section: string): void {
+    if (this.#state.webView !== 'document' || !this.#state.authoring?.content?.sections[section]) return
+    if (this.#state.documentPositionFailure) this.#set({ documentPositionFailure: undefined })
+    if (this.#state.position?.section === section) return
+    this.#set({ position: { section, step: this.#selectedSteps.get(`${this.#state.document}\0${section}`) ?? 0, trail: [], view: 'document' } })
+  }
+
+  /** A read-only inline runtime chooses a source step without navigating or editing the document. */
+  observeDocumentStep(sectionId: string, stepId: string): void {
+    this.#documentStep(sectionId, stepId, false)
+  }
+
+  /** An author freezes this target even when its step has not changed. */
+  pauseDocumentStep(sectionId: string, stepId: string): void {
+    this.#interruptProductionNavigation()
+    this.#documentStep(sectionId, stepId, true)
+  }
+
+  /** A canonical step remains selectable while its next runtime snapshot is still compiling. */
+  selectDocumentStep(sectionId: string, stepId: string): Promise<ProductionPlaybackState | undefined> | void {
+    this.#interruptProductionNavigation()
+    const source = this.#state.authoring, section = source?.content?.sections[sectionId]
+    const step = section?.stepOrder.indexOf(stepId) ?? -1
+    if (!section || step < 0) return
+    this.#pendingGo = undefined
+    if (this.#state.webView === 'document') { this.pauseDocumentStep(sectionId, stepId); return }
+    const plan = this.#state.productionPlan, range = plan?.pages.find(page => page.sectionId === sectionId)?.steps.find(step => step.stepId === stepId)
+    if (plan?.canPreview && this.#productionReady() && range?.startMs !== undefined) {
+      this.stopAuditions()
+      if (this.#production.selecting(sectionId, stepId)) return
+      this.#selectedSteps.set(`${this.#state.document}\0${sectionId}`, step)
+      this.#set({ position: { section: sectionId, step, trail: [], view: 'present' } })
+      return this.controlProduction({ binding: plan.binding, action: 'step', sectionId, stepId }).catch(() => undefined)
+    }
+    const snapshot = this.#state.presentationSnapshot
+    const compiled = this.#state.ir?.doc.sections.find(page => page.id === sectionId)?.stepIds?.indexOf(stepId) ?? -1
+    if (snapshot && snapshot.version === source?.version && snapshot.fingerprint === source.fingerprint && compiled >= 0) this.goToStep(sectionId, compiled)
+    else this.#set({ position: { section: sectionId, step, trail: [], view: this.#state.webView } })
+  }
+
+  #documentStep(sectionId: string, stepId: string, pause: boolean): void {
+    const content = this.#state.authoring?.content, section = content?.sections[sectionId]
+    if (this.#state.webView !== 'document' || !content?.sectionOrder.includes(sectionId) || !section) return
+    const step = section.stepOrder.indexOf(stepId)
+    if (step < 0 || content.steps[stepId]?.sectionId !== sectionId) return
+    if (this.#state.documentPositionFailure) this.#set({ documentPositionFailure: undefined })
+    this.#selectedSteps.set(`${this.#state.document}\0${sectionId}`, step)
+    const same = this.#state.position?.section === sectionId && this.#state.position.step === step
+    if (same && !pause) return
+    this.#set({ position: { section: sectionId, step, trail: section.stepOrder.slice(1, step + 1).map(id => `step:${id}`), view: 'document' }, documentPositionIntent: same && pause ? 'pause' : 'seek' })
+  }
+
+  /** Complete-IR position; trail maps the same step into a filtered preview without reusing its ordinal. */
+  goToStep(section: string, step: number): void {
+    this.#interruptProductionNavigation()
+    const target = this.#state.ir?.doc.sections.find(item => item.id === section)
+    if (!target || !Number.isInteger(step) || step < 0 || step > target.steps) return
+    const trail = stepTrail(stepKeys(target), step)
+    this.#set({ position: { section, step, trail, view: this.#state.webView } })
+    this.#record('navigate', { 'presmium.section': section, 'presmium.step': step })
+    this.#selectedSteps.set(`${this.#state.document}\0${section}`, step)
+    this.#lastPosition = undefined
+    const command = { type: 'go', section, step, trail, view: this.#state.webView } as const
+    if (this.#previewSinks.size === 0) {
+      this.#pendingGo = { document: this.#state.document, command }
+      return
+    }
+    this.#broadcast(command)
+  }
+
+  /** Shows the place of a line of a source file: in the document holding the file, opened when it is another. */
+  async revealSource(path: string, line = 1): Promise<boolean> {
+    this.#record('reveal.source', { 'presmium.path': path, 'presmium.line': line })
+    const documents = this.#state.documents?.documents ?? []
+    const holder = [...documents].sort((a, b) => b.dir.length - a.dir.length).find(doc => !doc.dir || path.startsWith(`${doc.dir}/`))
+    if (!holder) return false
+    if (holder.dir !== this.#state.document) await this.openDocument(holder.dir)
+    const doc = this.#state.ir?.doc
+    const place = doc && findPlaceAtLine(doc, path, line)
+    if (!place) return false
+    this.revealPlace(place.section, place.block)
+    return true
+  }
+
+  undo(): Promise<boolean> { if (this.#state.mode !== 'editing') return Promise.resolve(false); if (this.#activeDocumentHistory && (this.#state.editorHistory?.undo || this.#state.editorHistory?.field)) { this.#activeDocumentHistory.focus(); return Promise.resolve(this.#activeDocumentHistory.undo()) } return this.#changeHistory('undo') }
+  redo(): Promise<boolean> { if (this.#state.mode !== 'editing') return Promise.resolve(false); if (this.#activeDocumentHistory && (this.#state.editorHistory?.redo || this.#state.editorHistory?.field)) { this.#activeDocumentHistory.focus(); return Promise.resolve(this.#activeDocumentHistory.redo()) } return this.#changeHistory('redo') }
+
+  async #changeHistory(action: 'undo' | 'redo' | 'revert', revision?: string): Promise<boolean> {
+    if (this.#state.mode !== 'editing' || this.#state.isCreatingPage || this.#state.isEditingPage || this.#state.isHistoryBusy || this.#state.isHistoryPreparing) return false
+    const document = this.#state.document, scope = this.#documentScope
+    if (document === undefined) return false
+    const current = () => this.#state.document === document && this.#documentScope === scope
+    this.#set({ isHistoryPreparing: true, historyFailure: undefined })
+    try {
+      if (!current()) return false
+      await this.flushPendingEdits()
+      if (!current()) return false
+      await this.#history.read(document)
+      if (!current()) return false
+      const done = await this.#timed(`history.${action}`, revision ? { 'presmium.revision': revision } : {}, () => action === 'revert' ? this.#history.revert(revision!) : this.#history[action](), done => done ? 'done' : 'refused')
+      if (done && current()) await this.#documentSession.refresh(document)
+      return done
+    } catch {
+      if (current()) this.#set({ historyFailure: this.#messages.historyPendingSave })
+      return false
+    } finally { if (current()) this.#set({ isHistoryPreparing: false }) }
+  }
+
+  readHistoryPage(offset: number): Promise<void> { return this.#history.page(offset) }
+
+  revertRevision(id: string): Promise<boolean> {
+    return this.#changeHistory('revert', id)
+  }
+
+  acceptReview(): Promise<boolean> {
+    return this.#timed('review.accept', {}, () => this.#history.acceptReview(), done => (done ? 'done' : 'refused'))
+  }
+
+  rejectReview(): Promise<boolean> {
+    return this.#timed('review.reject', {}, () => this.#history.rejectReview(), done => (done ? 'done' : 'refused'))
+  }
+
+  /** Makes the document into `target` (a renderer, or an export of its plugins) as a job of the workspace server. */
+  startJob(target: string): Promise<void> {
+    const document = this.#state.document, scope = this.#documentScope, identity = this.#state.authoring?.identity
+    if (document === undefined || !identity || this.#state.jobPreparing) return Promise.resolve()
+    const controller = this.#jobPreparation = new AbortController()
+    const current = () => document === this.#state.document && scope === this.#documentScope && identity === this.#state.authoring?.identity && !controller.signal.aborted
+    this.#set({ jobPreparing: { target, canCancel: true }, jobsFailure: undefined })
+    return this.#timed('job.start', { 'presmium.job.target': target }, async () => {
+      const stop = this.observeJobs()
+      try {
+        if (this.#state.hasDocumentTimingDrafts || this.#state.documentTimingDraftStorageFailure) throw new Error('job-timing-draft')
+        if (this.#state.captionTimingDraftSteps?.length || this.#state.captionTimingDraftStorageFailure) throw new Error('job-caption-draft')
+        await this.flushPendingEdits(controller.signal)
+        if (!current()) return
+        const source = this.#state.authoring
+        if (!source?.version || !source.fingerprint || source.dirty || source.saving || source.composing || source.restored || source.error) throw new Error('job-save-required')
+        if (this.#state.hasDocumentTimingDrafts || this.#state.documentTimingDraftStorageFailure) throw new Error('job-timing-draft')
+        if (this.#state.captionTimingDraftSteps?.length || this.#state.captionTimingDraftStorageFailure) throw new Error('job-caption-draft')
+        this.#set({ jobPreparing: { target, canCancel: false } })
+        await this.#jobs.start(document, target, { version: source.version, fingerprint: source.fingerprint })
+      } catch (error) {
+        if (current()) this.#set({ jobsFailure: errorMessage(error) })
+      } finally {
+        stop()
+        if (this.#jobPreparation === controller) {
+          this.#jobPreparation = undefined
+          if (current()) this.#set({ jobPreparing: undefined })
+        }
+      }
+    })
+  }
+
+  /** Cancels the pending export intent; a document save already sent retains its own acknowledgement. */
+  cancelJobPreparation(): void {
+    if (!this.#state.jobPreparing?.canCancel) return
+    this.#jobPreparation?.abort()
+    this.#jobPreparation = undefined
+    this.#set({ jobPreparing: undefined })
+  }
+
+  cancelJob(id: string): Promise<void> {
+    return this.#timed('job.cancel', { 'presmium.job.id': id }, async () => { const stop = this.observeJobs(); try { await this.#jobs.cancel(id) } finally { stop() } })
+  }
+
+  recordOutsideChanges(): Promise<boolean> {
+    return this.#timed('changes.record', {}, () => this.#history.recordOutside(this.#messages.outsideChange), done => (done ? 'done' : 'refused'))
+  }
+
+  /** Attaches the shown preview and selects the requested view in its existing runtime. */
+  attachPreview(sink: PreviewSink): () => void {
+    this.#previewSinks.add(sink)
+    this.#set({ previewConnection: this.#state.previewConnection + 1 })
+    if (this.#state.previewRenderer === 'web') this.#showWebView([sink])
+    const pending = this.#pendingGo
+    if (pending && pending.document === this.#state.document) sink.send(pending.command)
+    this.#pendingGo = undefined
+    sink.send({ type: 'appearance', dark: this.#state.isDark })
+    sink.send({ type: 'pick', on: false })
+    const reveal = this.#pendingReveal
+    this.#pendingReveal = undefined
+    if (reveal) sink.send({ type: 'go', section: reveal.section })
+    sink.send({ type: 'highlight', target: reveal ?? this.#state.pointer?.target ?? null })
+    return () => {
+      this.#previewSinks.delete(sink)
+      this.#production.detach(sink)
+      this.#set({ previewConnection: this.#state.previewConnection + 1 })
+      this.#playback.detach(sink)
+    }
+  }
+
+  /** A report of the shown preview. */
+  handlePreviewReport(document: string, renderer: PreviewRenderer, report: PreviewReport, origin?: PreviewSink): void {
+    const unsupported = 'document-authoring-required'
+    if (report.type === 'edited' && report.request !== undefined) { origin?.send({ type: 'edit-result', request: report.request, target: report.target, error: unsupported }); return }
+    if (report.type === 'blocks-edited') { origin?.send({ type: 'blocks-result', section: report.section, request: report.request, error: unsupported }); return }
+    if (report.type === 'source-read') { origin?.send({ type: 'source-result', section: report.section, block: report.block, request: report.request, error: unsupported }); return }
+    if (report.type === 'source-save') { origin?.send({ type: 'source-saved', section: report.section, block: report.block, request: report.request, error: unsupported }); return }
+    if (report.type === 'source-create') { origin?.send({ type: 'source-created', section: report.section, request: report.request, error: unsupported }); return }
+    if (report.type === 'page-create') { origin?.send({ type: 'page-created', section: report.section, request: report.request, error: unsupported }); return }
+    if (document !== this.#state.document || renderer !== this.#state.previewRenderer) return
+    this.#playback.report(document, report, origin)
+    this.#production.report(document, report, origin)
+    switch (report.type) {
+      case 'ready':
+      case 'updated':
+        if (report.revision !== this.#state.previewIrRevision) this.#playback.stopPreviewOutputs()
+        this.#set({ previewIrRevision: report.revision })
+        this.#flashChanges()
+        if (report.type === 'ready' && renderer === 'web' && this.#state.webView !== 'document') this.#showWebView()
+        break
+      case 'picked': {
+        if (this.#state.mode !== 'editing') break
+        const target: PreviewAnchor = { section: report.section, ...report.block ? { block: report.block } : {} }
+        const isEditable = false
+        const section = this.#state.ir?.doc.sections.find(s => s.id === report.section)
+        const step = section && report.trail ? trailStep(stepKeys(section), report.trail) : report.step
+        this.point({ target, ...step === undefined ? {} : { step }, ...report.rect ? { rect: report.rect } : {}, ...report.point ? { point: report.point } : {}, isEditable })
+        break
+      }
+      case 'selection': {
+        if (this.#state.mode !== 'editing') break
+        const selected = report.selection
+        if (selected?.text.trim()) {
+          const target: PreviewAnchor = { section: selected.section, ...selected.block ? { block: selected.block } : {} }
+          this.point({ target, quote: selected.text.trim(), ...selected.rect ? { rect: selected.rect } : {}, ...selected.obstacles ? { obstacles: selected.obstacles } : {}, isEditable: false })
+        } else if (this.#state.pointer?.quote) this.point(undefined)
+        break
+      }
+      case 'flashed':
+        if (this.#trail) this.#set({ changeTrail: { id: this.#trail, rects: report.rects } })
+        break
+      case 'rect':
+        if (this.#state.pointer) this.#set({ pointer: { ...this.#state.pointer, rect: report.rect ?? undefined, obstacles: report.obstacles } })
+        break
+      case 'position': {
+        const snapshot = this.#state.presentationSnapshot, source = this.#state.authoring
+        if (snapshot && source && (source.dirty || source.loading || source.version !== snapshot.version || source.fingerprint !== snapshot.fingerprint)) break
+        // An initial loader can report its old cursor while a newer stable selection is preparing.
+        // Explicit native exits still reach the outer document workspace.
+        if (report.view !== 'document' && this.#production.selecting()) break
+        // A fresh frame announces its document view before applying the queued
+        // presentation command. Only the requested view completes that switch.
+        if (renderer === 'web' && this.#awaitingView) {
+          if (report.view !== this.#awaitingView) break
+          this.#awaitingView = undefined
+        }
+        // Where the author reads or presents: recorded when it moves to another section, step or view.
+        const at = `${report.section}\0${report.step}\0${report.view ?? ''}`
+        if (at === this.#lastPosition) break
+        this.#lastPosition = at
+        const section = this.#state.ir?.doc.sections.find(section => section.id === report.section)
+        const completeStep = section && report.trail.length ? trailStep(stepKeys(section), report.trail) : report.step
+        this.#selectedSteps.set(`${this.#state.document}\0${report.section}`, completeStep)
+        this.#set({ position: { section: report.section, step: completeStep, trail: report.trail, ...report.view ? { view: report.view } : {} } })
+        if (renderer === 'web' && report.view && (report.view === 'present') !== (this.#state.webView === 'present')) this.setWebView(report.view === 'present' ? 'present' : 'document')
+        this.#record('preview.position', { 'presmium.section': report.section, 'presmium.step': report.step, 'presmium.preview.view': report.view })
+        break
+      }
+      case 'shortcut':
+        this.#record('shortcut', { 'presmium.command': report.command })
+        if (report.command === 'dismiss') {
+          if (this.#state.pointer) this.point(undefined)
+        } else if (report.command === 'undo') void this.undo()
+        else if (report.command === 'redo') void this.redo()
+        else if (report.command === 'save') void this.flushPendingEdits().catch(() => {})
+        else for (const listener of this.#playbackKeys) listener(report.command)
+        break
+      default:
+        break
+    }
+  }
+
+  #broadcast(command: PreviewCommand): void {
+    for (const sink of this.#previewSinks) sink.send(command)
+  }
+
+  #stopSubscriptions(): void {
+    this.#componentPropertyDrafts.stopAgentRead()
+    this.#saveDocumentReturnPoint(); this.#cancelOpeningDocument(); this.#stopDocumentReturnScroll?.()
+    this.#documentViewport?.stop(); this.#documentViewport = undefined; this.#documentEditorBinding = undefined
+    this.#presentationPreparation++
+    this.#presentationController?.abort(new Error('client-document-changed'))
+    this.#voiceover.stop()
+    this.#production.reset()
+    this.#set({ isPreparingPresentation: false, presentationFailure: undefined, presentationSnapshot: undefined, productionPlan: undefined, productionFailure: undefined })
+    this.#removedCueTimings.clear(); this.#cueTimingScope = undefined
+    this.#documentSession.close()
+    this.#unsubscribeDocumentHistory?.(); this.#unsubscribeDocumentHistory = undefined; this.#activeDocumentHistory = undefined; this.#documentEditor = undefined
+    this.#unsubscribeDocumentSelection?.(); this.#unsubscribeDocumentSelection = undefined
+    this.#pendingDocumentFocus = undefined; this.#pendingDocumentSelection = undefined; this.#documentSelectionGeneration++
+    this.#documentFields.clear(); this.#pendingDocumentField = undefined
+    this.#playback.reset()
+    this.#focusVersion++
+    this.#pendingReveal = undefined
+    this.#awaitingView = undefined
+    this.#pendingFlash = undefined
+    this.#unsubscribeIr?.()
+    this.#unsubscribeIr = undefined
+    this.#runtimeDocument = undefined
+    this.#jobObservers.clear()
+    this.#jobsDocument = undefined
+    this.#history.stop()
+    this.#diagnostics.stop()
+    this.#jobs.stop()
+  }
+
+  dispose(): void {
+    this.telemetry.stop()
+    this.#stopSubscriptions()
+    this.#diagnostics.dispose()
+    this.#documentSession.dispose()
+    this.#commentDrafts.close()
+    this.#componentPropertyDrafts.close()
+    this.#captionTimingDrafts.close()
+    disposeTranscriptionSessions(this.client)
+    disposeDocumentRecordings(this)
+  }
+}