@lincyaw/workbench 0.1.0 → 0.2.0-rc.0

package/README.md

@@ -1,15 +1,21 @@
 # @lincyaw/workbench
 
-Presmium's workbench panels in React: the launcher of a workspace (its documents, made from a template, renamed, copied and deleted), a document's file tree, the source editor (CodeMirror 6, with a three-way merge when a file changed on disk), the problems of its compilation, its live preview (the web form or the slides, driven over Presmium's preview protocol) and its changes (an agent's change waiting for review, the changes not committed, the history and its undo). Under them, bound to no framework: the client of the workspace service (`presmium serve`), the workbench's state, the preview protocol's workbench side, and the shared components of Presmium's design (`PmButton`, `PmDialog`, `PmMenu` and the others) in React. Experimental (0.x).
+Presmium's workbench panels in React, for teachers who know no code. The panels are:
 
-Part of [Presmium](https://github.com/Lincyaw/presmium), which turns lectures written in MyST Markdown into web pages, slides, Jupyter notebooks and narrated lectures.
+- the documents of a workspace, listed by title (made from a template, renamed, copied and deleted by title);
+- a document shown as its readers see it (the web form or the slides, driven over Presmium's preview protocol), edited right on the page;
+- the document's comments and its version history.
+
+Under them, bound to no framework, are the client of the workspace service (`presmium serve`), the workbench's state, the mapping of an edit on the page back to the source, the preview protocol's workbench side, and the shared components of Presmium's design (`PmButton`, `PmDialog`, `PmMenu` and the others) in React. Experimental (0.x).
+
+Part of [Presmium](https://github.com/Lincyaw/presmium), which compiles canonical lecture.json teaching documents into web pages, slides, Jupyter notebooks and narrated playback.
 
 ## Usage
 
-`presmium studio` shows these panels in DeepSeek Harness's web client: `@lincyaw/dsh` bundles them into its client part and places them. They know nothing of the host they are drawn in; a layout gives them one `Workbench` and places them:
+`presmium studio` shows these panels in DeepSeek Harness's web client: `@lincyaw/dsh` bundles them into its client part and places them. They know nothing of the host they are drawn in. A layout gives them one `Workbench` and places them:
 
 ```tsx
-import { HomePanel, DocumentView, Workbench, WorkbenchProvider, workspaceClient } from '@lincyaw/workbench'
+import { DocumentView, HomePanel, Workbench, WorkbenchProvider, workspaceClient } from '@lincyaw/workbench'
 import '@lincyaw/design/design.css'
 import '@lincyaw/workbench/styles.css'
 
@@ -20,15 +26,41 @@ export function Centre({ open }: { open: boolean }) {
 }
 ```
 
-The workspace service's routes are reached under the page's `api/presmium/` (the host passes them on to the service); React 18 is a peer dependency. Interactive controls wrap Radix Primitives; cmdk owns command search, React Arborist owns the file tree, and react-resizable-panels owns pane resizing. Presmium maintains the visual tokens and the document, save, review and preview behavior, rather than duplicating these libraries' focus, keyboard, positioning and drag logic.
+The page reaches the workspace service's routes under its own `api/presmium/` path; the host passes them on to the service. React 18 is a peer dependency. Dialogs and menus wrap Radix Primitives. Presmium maintains the visual tokens, the editing, the versions and the preview.
+
+A host exposing a subset of the workspace service can set `client.capabilities` before constructing `Workbench`: `{ diagnostics: 'none', production: false, narration: false, export: false, readOnly: true }`. This disables diagnostic subscriptions and reports, hides the corresponding document controls, and makes the source session and canonical write requests read-only. Omitted fields preserve the local workspace's complete behavior. Hosts explain unavailable services in their own interface and enforce authorization on every server request. The optional third `workspaceClient` argument, `{ fetch }`, provides an instance-specific transport for authentication headers.
+
+`client.capabilities.readOnly: true` also disables canonical document writes, including source transactions, asset imports, comments, page operations and history changes. The source actor and editor controls share this restriction; the service still checks the authenticated member on every request.
+
+`DocumentView` keeps the document title, toolbar, editor and preview in one shared view. Its optional `onBack()` callback replaces the default return to the workspace's document list. `actions` places host controls, such as sharing, beside the document's own commands; hosts provide localized accessible names and use the public workbench controls.
+
+`historyRevisionAction` adds an explicit host operation to the existing Version History rows. It uses the exported `HistoryRevisionAction` configuration: `label`, optional `icon`, `onSelect(revision)`, optional `disabled` (a boolean or a predicate of the revision), and optional `pendingRevision` (the opaque revision ID being processed). The standalone `HistoryPanel` accepts the same configuration as `revisionAction`. The host owns confirmation, source flushing, authorization, conflict checks and request recovery; it controls pending state while the shared panel disables its other history operations and pagination. Read-only clients cannot activate the action.
+
+An absolute snapshot restore is separate from selective undo. A host that stores full snapshots can return `revertible: false` in its history rows and supply a clearly named restore action. Treat revision IDs as opaque references and resolve them on the server; do not reinterpret them in the browser or fetch another history list. Reuse the ordinary compilation and presentation flow, which checks the exact saved source, fingerprint and revision before showing a presentation.
+
+## On the page
+
+The document toolbar holds the navigation pane, Undo and Redo, whether the document is saved, Video production, Captions, Comments, Version History, Presentation preview and Export. Below 768 px, Video production, Captions and Version History move into a More menu. When the view owns its title (`framed` is false), Back and the title use their own row; Undo, Redo and Comments join the same More menu so the main commands fit within the available width. A framed view retains its existing single command row.
+
+The names follow Microsoft Word's, in Chinese and English.
+
+The document is one continuous editor: the author types in place and the change is saved after a short pause. Selecting text opens the formatting toolbar, which includes Add comment. Generated content (components and diagrams) shows its preview, not its source; authors change it through its properties or the AI assistant.
+
+Every save is a version. Undo and Redo (Ctrl+Z, Ctrl+Y or Ctrl+Shift+Z) walk the versions, and Version History undoes any one of them.
+
+The AI's turns become versions too. When the workspace asks to review them (`review: required`), the author accepts or rejects them first.
+
+Comments are saved in the document with the text they point at. The Comments panel lists them; each can be replied to, reacted to, resolved and reopened.
+
+Presentation preview shows the slides with the arrow keys and `Esc` working at once; `Esc` first closes an open menu or dialog, then leaves the presentation.
 
-Documents open in preview, with source and side by side modes. Text selections and picked preview blocks become conversation context. `WorkbenchProvider` protects unsaved changes when closing files, leaving a document or unloading the page. Set `protectChanges={false}` on auxiliary providers when several panels share one workbench, keeping the protection mounted once in its primary provider.
+Operations that an outside AI tool asks to perform appear as Approvals in the app bar, where the author allows or denies them.
 
-Hosts route text file references through `workbench.openSource(document, path, { line })`. The file tree and source reads and saves use the opened workspace's scope (`''`), including code outside the current lecture directory. Opening shared code or root notes keeps the selected lecture preview and existing drafts; switching lectures still protects unsaved changes. Without a selected lecture, root files open in source mode. Keep `DocumentView` mounted when hiding it so editor drafts and undo history survive navigation.
+The workbench hands requests to the conversation through `workbench.onAgentRequest`; the host binds that to its agent session. Hosts route links to a document's source through `workbench.revealSource(path, line)`, which opens that document and outlines the block at the line.
 
 ## Documentation
 
-- [Design of the workbench on DeepSeek Harness](https://github.com/Lincyaw/presmium/blob/main/docs/design-dsh.md) (section 7)
+- [Design of the workbench on DeepSeek Harness](https://github.com/Lincyaw/presmium/blob/main/docs/studio.md) (section 7)
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lincyaw/workbench",
-  "version": "0.1.0",
-  "description": "Presmium's workbench panels in React (home, file tree, source editor, problems, preview, changes) with the workspace service's client and the preview protocol's workbench side; @lincyaw/dsh places them in presmium studio (experimental)",
+  "version": "0.2.0-rc.0",
+  "description": "Presmium's workbench panels in React (the documents, a document edited on its rendered page with comments and version history) with the workspace service's client and the preview protocol's workbench side; @lincyaw/dsh places them in presmium studio (experimental)",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -24,34 +24,38 @@
   },
   "exports": {
     ".": "./src/index.ts",
+    "./components": "./src/components.tsx",
     "./styles.css": "./src/styles.css"
   },
   "files": [
     "src"
   ],
   "dependencies": {
-    "@codemirror/commands": "6.11.1",
-    "@codemirror/lang-markdown": "6.5.2",
-    "@codemirror/lang-yaml": "6.1.3",
-    "@codemirror/language": "6.13.1",
-    "@codemirror/lint": "6.9.7",
-    "@codemirror/search": "6.7.2",
-    "@codemirror/state": "6.7.6",
-    "@codemirror/view": "6.43.14",
-    "@lezer/highlight": "1.2.5",
+    "@blocknote/core": "0.56.0",
+    "@blocknote/mantine": "0.56.0",
+    "@blocknote/react": "0.56.0",
+    "@dnd-kit/dom": "0.5.1",
+    "@dnd-kit/react": "0.5.1",
+    "@floating-ui/react": "0.27.20",
+    "@mantine/core": "8.3.11",
+    "@mantine/hooks": "8.3.11",
     "@radix-ui/react-dialog": "^1.3.1",
     "@radix-ui/react-dropdown-menu": "^2.2.1",
-    "@radix-ui/react-popover": "^1.3.1",
+    "@radix-ui/react-popover": "^1.1.15",
+    "@radix-ui/react-radio-group": "^1.5.1",
     "@radix-ui/react-tabs": "^1.2.1",
-    "@radix-ui/react-toggle-group": "^1.2.1",
-    "cmdk": "^1.1.1",
-    "node-diff3": "3.2.1",
-    "react-arborist": "^4.0.1",
-    "react-dnd": "^16.0.1",
-    "react-dnd-html5-backend": "^16.0.1",
-    "react-resizable-panels": "^4.14.5",
-    "@lincyaw/design": "1.0.0-rc.0",
-    "@lincyaw/kernel": "1.0.0-rc.0"
+    "@radix-ui/react-toolbar": "^1.2.1",
+    "@radix-ui/react-tooltip": "^1.4.1",
+    "@rjsf/core": "6.11.0",
+    "@rjsf/utils": "6.11.0",
+    "@rjsf/validator-ajv8": "6.11.0",
+    "@tiptap/core": "3.32.0",
+    "@tiptap/extension-file-handler": "3.32.0",
+    "@tiptap/pm": "3.32.0",
+    "katex": "0.18.10",
+    "react-resizable-panels": "4.14.5",
+    "@lincyaw/design": "1.0.0-rc.1",
+    "@lincyaw/kernel": "1.0.0-rc.1"
   },
   "peerDependencies": {
     "react": "^18.3.1",
@@ -61,6 +65,7 @@
     "@types/react": "18.3.28",
     "@types/react-dom": "18.3.7",
     "react": "^18.3.1",
-    "react-dom": "^18.3.1"
+    "react-dom": "^18.3.1",
+    "@lincyaw/compiler": "1.0.0-rc.1"
   }
 }

package/src/MediaClipEditor.tsx

@@ -0,0 +1,122 @@
+import { useId, useRef, useState } from 'react'
+import type { MediaClip, ProductionAssetInspection } from '@lincyaw/kernel'
+import { PmButton, PmField, PmInput, PmNotice, PmRange, PmSelect } from './components.tsx'
+import type { ControlDensity } from './components.tsx'
+import type { Locale } from './messages.ts'
+import { MEDIA_MESSAGES } from './media-messages.ts'
+import { mediaTime, mediaTimeValue as timeValue } from './media-time.ts'
+export { mediaTime } from './media-time.ts'
+
+/** Unaccepted input. Untouched fields keep their original numeric precision. */
+export interface MediaClipDraft {
+  version: string
+  clip: MediaClip
+  baseClip?: MediaClip
+  startText?: string
+  endText?: string
+  offsetText?: string
+}
+export interface MediaClipAssetChoice { id: string, label: string }
+export interface MediaClipEditorProps {
+  locale: Locale
+  density?: ControlDensity
+  assets: readonly MediaClipAssetChoice[]
+  clips: readonly MediaClip[]
+  selectedClipId?: string
+  draft: MediaClipDraft
+  inspection?: ProductionAssetInspection
+  stepDurationMs?: number
+  disabled?: boolean
+  canApply?: boolean
+  loading?: boolean
+  busy?: 'import' | 'apply' | 'remove'
+  pending?: boolean
+  review?: boolean
+  storageFailed?: boolean
+  failure?: string
+  status?: string
+  retryImport?: boolean
+  onSelectClip(id: string | undefined): void
+  onSelectAsset(id: string): void
+  onChange(draft: MediaClipDraft): void
+  onImport(file: File): void
+  onRetryImport(): void
+  onRead(): void
+  onReview(): void
+  onApply(clip: MediaClip): void
+  onRemove(): void
+  onEditStart(): void
+}
+
+function offsetValue(raw: string | undefined, original: number): number | undefined {
+  if (raw === undefined || raw === (original / 1000).toFixed(3)) return original
+  const text = raw.normalize('NFKC').trim(), value = Number(text) * 1000
+  return /^\d+(?:\.\d+)?$/.test(text) && Number.isFinite(value) ? value : undefined
+}
+
+/** Compose native public fields; only the caller can adopt a clip into the source. */
+export function MediaClipEditor(props: MediaClipEditorProps) {
+  const { locale, density = 'compact', assets, clips, selectedClipId, draft, inspection, stepDurationMs, disabled, busy, loading, review } = props
+  const t = MEDIA_MESSAGES[locale], file = useRef<HTMLInputElement>(null), composing = useRef(new Set<string>()), [volumePreview, setVolumePreview] = useState<number>()
+  const formatId = useId(), rangeErrorId = useId(), clip = draft.clip
+  const startMs = timeValue(draft.startText, clip.sourceRange.startMs), endMs = timeValue(draft.endText, clip.sourceRange.endMs), offsetMs = offsetValue(draft.offsetText, clip.attachment.offsetMs)
+  const inspected = inspection?.assetId === clip.assetId ? inspection : undefined
+  const rangeInvalid = startMs !== undefined && endMs !== undefined && (startMs < 0 || endMs <= startMs || inspected !== undefined && endMs > inspected.durationMs)
+  const exceedsStep = stepDurationMs !== undefined && startMs !== undefined && endMs !== undefined && offsetMs !== undefined && offsetMs + endMs - startMs > stepDurationMs
+  const rangeError = rangeInvalid ? t.invalidRange : exceedsStep ? t.exceedsStep : undefined
+  const rangeDescription = `${formatId}${rangeError ? ` ${rangeErrorId}` : ''}`
+  const originalRemoved = Boolean(selectedClipId && !clips.some(clip => clip.id === selectedClipId))
+  const valid = Boolean(inspected && startMs !== undefined && endMs !== undefined && offsetMs !== undefined && !rangeInvalid && !exceedsStep && !originalRemoved)
+  const submit = () => {
+    if (disabled || busy || !props.canApply || review || !valid || composing.current.size) return
+    props.onApply({ ...clip, sourceRange: { startMs: startMs!, endMs: endMs! }, attachment: { ...clip.attachment, offsetMs: offsetMs! } })
+  }
+  const change = (patch: Partial<MediaClipDraft>) => props.onChange({ ...draft, ...patch })
+  const composition = (field: string) => ({ onCompositionStart: () => composing.current.add(field), onCompositionEnd: () => { composing.current.delete(field) } })
+  return <section className="pm-ui-media-clip-editor" aria-label={t.title} data-density={density} onFocusCapture={props.onEditStart} onPointerDownCapture={props.onEditStart}
+    onKeyDown={event => {
+      event.stopPropagation()
+      if (event.key === 'Enter' && event.target instanceof HTMLInputElement && event.target.type !== 'range' && !event.nativeEvent.isComposing && !composing.current.size) { event.preventDefault(); submit() }
+    }}>
+    <div className="pm-ui-media-clip-editor__heading"><h2>{t.title}</h2><PmButton density={density} loading={busy === 'import'} disabled={disabled || Boolean(busy)} onClick={() => file.current?.click()}>{t.import}</PmButton>
+      <input ref={file} type="file" hidden accept="audio/*,.wav,.ogg,.mp3,.m4a,.webm" onChange={event => { const selected = event.currentTarget.files?.[0]; event.currentTarget.value = ''; if (selected && !disabled && !busy) props.onImport(selected) }} />
+    </div>
+    <PmSelect label={t.asset} density={density} value={clip.assetId} disabled={disabled || Boolean(busy)} onChange={event => props.onSelectAsset(event.target.value)}>
+      <option value="">{t.chooseAsset}</option>{assets.map(asset => <option key={asset.id} value={asset.id}>{asset.label}</option>)}
+      {clip.assetId && !assets.some(asset => asset.id === clip.assetId) && <option value={clip.assetId}>{clip.assetId}</option>}
+    </PmSelect>
+    {clips.length > 0 || selectedClipId ? <PmSelect label={t.clip} density={density} value={selectedClipId ?? ''} disabled={disabled || Boolean(busy)} onChange={event => props.onSelectClip(event.target.value || undefined)}>
+      <option value="">{t.newClip}</option>{clips.map((clip, index) => <option key={clip.id} value={clip.id}>{t.clipLabel(index, assets.find(asset => asset.id === clip.assetId)?.label ?? clip.assetId)}</option>)}
+      {originalRemoved && <option value={selectedClipId}>{t.removed}</option>}
+    </PmSelect> : null}
+    {clip.assetId && <>
+      {loading ? <span className="pm-ui-field__hint" role="status">{t.loading}</span> : inspected && <output className="pm-ui-field__hint">{t.original(mediaTime(inspected.durationMs), valid ? mediaTime(endMs! - startMs!) : undefined)}</output>}
+      <div className="pm-ui-media-clip-editor__times">
+        <PmInput label={t.in} density={density} width="time" maxLength={32} value={draft.startText ?? mediaTime(clip.sourceRange.startMs)} aria-describedby={rangeDescription} aria-invalid={rangeInvalid || undefined}
+          readOnly={disabled || !inspected} error={startMs === undefined ? t.invalidTime : undefined} onChange={event => change({ startText: event.target.value })} {...composition('in')} />
+        <PmInput label={t.out} density={density} width="time" maxLength={32} value={draft.endText ?? mediaTime(clip.sourceRange.endMs)} aria-describedby={rangeDescription} aria-invalid={Boolean(rangeError) || undefined}
+          readOnly={disabled || !inspected} error={endMs === undefined ? t.invalidTime : undefined} onChange={event => change({ endText: event.target.value })} {...composition('out')} />
+      </div>
+      <span className="pm-ui-field__hint" id={formatId}>{t.timeFormat}</span>
+      {rangeError && <span id={rangeErrorId} className="pm-ui-field__error" role="alert">{rangeError}</span>}
+      <PmInput label={t.offset} density={density} width="number" inputMode="decimal" maxLength={32} value={draft.offsetText ?? (clip.attachment.offsetMs / 1000).toFixed(3)}
+        readOnly={disabled || !inspected} error={offsetMs === undefined ? t.invalidOffset : undefined} onChange={event => change({ offsetText: event.target.value })} {...composition('offset')} />
+      <PmField label={t.volume} density={density} group><div className="pm-ui-media-clip-editor__volume">
+        <PmRange label={t.volume} density={density} value={clip.volume * 100} max={100} disabled={disabled || !inspected} valueText={value => `${Math.round(value)}%`} onPreviewChange={setVolumePreview}
+          onValueCommit={value => change({ clip: { ...clip, volume: value / 100 } })} />
+        <output>{Math.round(volumePreview ?? clip.volume * 100)}%</output><PmButton density={density} aria-pressed={Boolean(clip.muted)} disabled={disabled || !inspected} onClick={() => change({ clip: { ...clip, muted: !clip.muted } })}>{clip.muted ? t.unmute : t.mute}</PmButton>
+      </div></PmField>
+      <div className="pm-ui-media-clip-editor__actions">
+        <PmButton density={density} variant="primary" loading={busy === 'apply'} disabled={disabled || Boolean(busy) || !props.canApply || review || !valid} onClick={submit}>{selectedClipId ? t.apply : t.add}</PmButton>
+        <PmButton density={density} disabled={disabled || !inspected} onClick={() => change({ clip: { ...clip, sourceRange: { startMs: 0, endMs: inspected!.durationMs } }, startText: undefined, endText: undefined })}>{t.restore}</PmButton>
+        {selectedClipId && <PmButton density={density} variant="danger" loading={busy === 'remove'} disabled={disabled || Boolean(busy) || originalRemoved} onClick={props.onRemove}>{t.remove}</PmButton>}
+      </div>
+    </>}
+    {originalRemoved ? <PmNotice tone="warn">{t.removed}</PmNotice> : review ? <PmNotice tone="warn"><span>{t.review}</span><PmButton density={density} disabled={disabled || Boolean(busy) || !props.canApply || !inspected} onClick={props.onReview}>{t.check}</PmButton></PmNotice>
+      : clip.assetId && !props.canApply && !busy && <span className="pm-ui-field__hint">{t.unavailable}</span>}
+    {props.failure && <PmNotice tone="danger"><span>{props.failure}</span><PmButton density={density} disabled={disabled || Boolean(busy)} onClick={props.retryImport ? props.onRetryImport : props.onRead}>{props.retryImport ? t.retryImport : t.retry}</PmButton></PmNotice>}
+    {props.storageFailed && <PmNotice tone="warn">{t.storageFailed}</PmNotice>}
+    {props.pending && !props.failure && <span className="pm-ui-field__hint" role="status">{t.pending}</span>}
+    {props.status && <span className="pm-ui-field__hint" role="status">{props.status}</span>}
+  </section>
+}

package/src/StepProductionEditor.tsx

@@ -0,0 +1,130 @@
+import { useEffect, useRef, useState } from 'react'
+import type { TeachingDocument } from '@lincyaw/kernel'
+import { PmButton, PmField, PmInput, PmSegmented } from './components.tsx'
+import type { Locale } from './messages.ts'
+import { stepNarrationStarts, stepTimingValue } from './step-production.ts'
+import type { ProductionSource, StepDurationDraft, StepDurationKey, StepTimingPatch } from './step-production.ts'
+
+const MESSAGES = {
+  'zh-CN': {
+    timing: '播放时机', start: '配音开始', during: '同步动画', after: '动画后', minimum: '最短停留', trailing: '结束停顿', automatic: '自动', unit: '毫秒',
+    source: { step: '本步设置', section: '继承本页', document: '继承文稿默认', unset: '未设置，使用讲授默认' },
+    restore: '使用继承的时机', restoreHint: '只把本步的开始时机、最短停留与结束停顿改回继承值；为单个讲稿设置的时机保留。',
+    legacy: '继承讲稿设置', mixed: '本步讲稿的开始时机不同。',
+    unify: '统一本步时机', unifyHint: '只覆盖本步；改回继承后继续使用讲稿原有的时机。',
+    invalid: '未采用：请输入不小于 0 的毫秒数。',
+    review: '草稿尚未采用。请核对当前来源设置，再修改或使用继承值。', pending: '输入尚未采用。', storageFailure: '无法在本机保留草稿，请保持页面打开。',
+    count: (index: number, value: string) => `讲稿 ${index}：${value}`,
+    advancedDraft: '有未完成的视频设置，请在视频制作中处理。',
+  },
+  en: {
+    timing: 'Playback timing', start: 'Voiceover starts', during: 'With animation', after: 'After animation', minimum: 'Minimum hold', trailing: 'Trailing pause', automatic: 'Auto', unit: 'ms',
+    source: { step: 'This step', section: 'Inherited from page', document: 'Inherited from document', unset: 'Not set; the lecture default applies' },
+    restore: 'Use Inherited Timing', restoreHint: 'Returns only this step’s start, minimum hold, and trailing pause to the inherited values. Timing set on individual scripts stays.',
+    legacy: 'Inherited from the script', mixed: 'Scripts in this step start at different times.',
+    unify: 'Unify Step Timing', unifyHint: 'Applies only to this step. Using inherited timing again returns to each script’s original timing.',
+    invalid: 'Not applied: enter a duration of 0 ms or more.',
+    review: 'This draft has not been applied. Check the current source setting, then edit it or use the inherited value.', pending: 'Input has not been applied.', storageFailure: 'Couldn’t keep the draft on this device. Keep this page open.',
+    count: (index: number, value: string) => `Script ${index}: ${value}`,
+    advancedDraft: 'Review the pending settings in Video Production.',
+  },
+}
+
+interface DurationFieldProps {
+  label: string
+  value?: number
+  source: ProductionSource
+  locale: Locale
+  readOnly?: boolean
+  draft?: StepDurationDraft
+  onDraft?(draft: StepDurationDraft | undefined): void
+  onChange(value: number | null): void
+  onComposition?(composing: boolean): void
+}
+
+/** Short author intent, never an estimated timestamp or a second playback clock. */
+function DurationField({ label, value, source, locale, readOnly, draft, onDraft, onChange, onComposition }: DurationFieldProps) {
+  const t = MESSAGES[locale], current = useRef({ onComposition, onChange, onDraft, value })
+  current.current = { onComposition, onChange, onDraft, value }
+  const [text, setText] = useState(draft?.text ?? (value === undefined ? '' : String(value))), [error, setError] = useState(draft?.error ?? false)
+  const focused = useRef(false), composing = useRef(false)
+  useEffect(() => { if (!focused.current) { setText(draft?.text ?? (value === undefined ? '' : String(value))); setError(draft?.error ?? false) } }, [value, source, draft?.text, draft?.error, draft?.review])
+  useEffect(() => () => { if (composing.current) current.current.onComposition?.(false) }, [])
+  const commit = (input: string): boolean => {
+    const normalized = input.normalize('NFKC').trim()
+    if (!normalized) { setError(false); current.current.onDraft?.(undefined); current.current.onChange(null); return true }
+    const number = Number(normalized)
+    if (!/^\d+(?:\.\d+)?$/.test(normalized) || !Number.isFinite(number)) { setError(true); current.current.onDraft?.({ text: input, error: true }); return false }
+    setError(false); current.current.onDraft?.(undefined); current.current.onChange(number); return true
+  }
+  return <PmInput label={locale === 'zh-CN' ? `${label}（${t.unit}）` : `${label} (${t.unit})`} width="number" inputMode="decimal" maxLength={256} value={text} placeholder={t.automatic}
+    hint={draft && !error && !draft.review ? `${t.source[source]} · ${t.pending}` : t.source[source]} error={draft?.review ? t.review : error ? t.invalid : undefined} readOnly={readOnly}
+    onFocus={() => { focused.current = true }}
+    onChange={event => {
+      setText(event.target.value)
+      if (readOnly) return
+      if (composing.current) { setError(false); current.current.onDraft?.({ text: event.target.value, error: false }) }
+      else commit(event.target.value)
+    }}
+    onBlur={() => {
+      focused.current = false
+      if (readOnly || composing.current || error || draft) return
+      setText(current.current.value === undefined ? '' : String(current.current.value))
+    }}
+    onCompositionStart={() => { composing.current = true; onComposition?.(true) }}
+    onCompositionEnd={event => {
+      composing.current = false
+      if (!readOnly) commit(event.currentTarget.value)
+      queueMicrotask(() => current.current.onComposition?.(false))
+    }} />
+}
+
+export interface StepProductionEditorProps {
+  document: TeachingDocument
+  stepId: string
+  locale: Locale
+  readOnly?: boolean
+  advanced?: boolean
+  onPause(): void
+  onInteraction?(): void
+  onChange(patch: StepTimingPatch): void
+  drafts?: Partial<Record<StepDurationKey, StepDurationDraft>>
+  draftStorageFailure?: boolean
+  onDraft?(key: StepDurationKey, draft: StepDurationDraft | undefined): void
+  onComposition?(key: StepDurationKey, composing: boolean): void
+}
+
+/** A reusable view of the canonical step production, including inherited and migrated settings. */
+export function StepProductionEditor({ document, stepId, locale, readOnly, advanced = true, onPause, onInteraction, onChange, drafts, onDraft, draftStorageFailure, onComposition }: StepProductionEditorProps) {
+  const t = MESSAGES[locale], [unifying, setUnifying] = useState(false)
+  const start = stepTimingValue(document, stepId, 'narrationStart'), minimum = stepTimingValue(document, stepId, 'minimumHoldMs'), trailing = stepTimingValue(document, stepId, 'trailingPauseMs')
+  const narrations = stepNarrationStarts(document, stepId), hasOverrides = narrations.some(value => value.overridden)
+  const mixed = new Set(narrations.map(value => value.value ?? 'with-animation')).size > 1
+  const hasStepTiming = [start, minimum, trailing].some(value => value.source === 'step')
+  const apply = (patch: StepTimingPatch) => { if (!readOnly) { onPause(); onChange(patch) } }
+  const options = [{ value: 'with-animation', label: t.during, icon: 'timing-during' as const }, { value: 'after-animation', label: t.after, icon: 'timing-after' as const }]
+  return <section className="pm-ui-step-production" contentEditable={false} data-step-production={stepId} aria-label={t.timing}
+    onFocus={() => { onInteraction?.(); onPause() }} onKeyDown={event => event.stopPropagation()} onPointerDown={event => event.stopPropagation()}>
+    {advanced && <div className="pm-ui-step-production__heading"><span className="pm-ui-field__label">{t.timing}</span>
+      <PmButton small variant="ghost" disabled={readOnly || !hasStepTiming && !drafts?.minimumHoldMs && !drafts?.trailingPauseMs} title={t.restoreHint} onClick={() => { onDraft?.('minimumHoldMs', undefined); onDraft?.('trailingPauseMs', undefined); apply({ narrationStart: null, minimumHoldMs: null, trailingPauseMs: null }) }}>{t.restore}</PmButton>
+    </div>}
+    {!advanced ? <PmField group label={t.start} density="compact" hint={mixed ? t.mixed : undefined}>
+      <div className="pm-ui-step-production__actions"><PmSegmented label={t.start} value={mixed ? '' : narrations[0]?.value ?? start.value ?? 'with-animation'} options={options} disabled={readOnly} onChange={value => apply({ narrationStart: value as 'with-animation' | 'after-animation' })} /></div>
+    </PmField> : <><PmField group label={t.start} density="compact" hint={hasOverrides ? (mixed ? t.mixed : t.legacy) : t.source[start.source]}>
+      {!hasOverrides && <div className="pm-ui-step-production__actions"><PmSegmented label={t.start} value={start.value ?? ''} options={options} disabled={readOnly} onChange={value => apply({ narrationStart: value as 'with-animation' | 'after-animation' })} /></div>}
+      {hasOverrides && <>
+        <div className="pm-ui-step-production__narration-settings">{narrations.map((entry, index) => <span key={entry.id} className="pm-ui-field__hint">{t.count(index + 1, entry.value === 'after-animation' ? t.after : t.during)}{entry.overridden ? ` · ${t.legacy}` : ` · ${t.source[start.source]}`}</span>)}</div>
+        <div className="pm-ui-step-production__actions"><PmButton small disabled={readOnly} onClick={() => setUnifying(value => !value)} aria-expanded={unifying}>{t.unify}</PmButton></div>
+        {unifying && <><span className="pm-ui-field__hint">{t.unifyHint}</span><div className="pm-ui-step-production__actions"><PmSegmented label={t.unify} value="" options={options} disabled={readOnly} onChange={value => { apply({ narrationStart: value as 'with-animation' | 'after-animation' }); setUnifying(false) }} /></div></>}
+      </>}
+    </PmField>
+    <div className="pm-ui-step-production__durations">
+      <DurationField label={t.minimum} value={minimum.value} source={minimum.source} locale={locale} readOnly={readOnly} draft={drafts?.minimumHoldMs} onDraft={draft => onDraft?.('minimumHoldMs', draft)}
+        onChange={value => apply({ minimumHoldMs: value })} onComposition={composing => onComposition?.('minimumHoldMs', composing)} />
+      <DurationField label={t.trailing} value={trailing.value} source={trailing.source} locale={locale} readOnly={readOnly} draft={drafts?.trailingPauseMs} onDraft={draft => onDraft?.('trailingPauseMs', draft)}
+        onChange={value => apply({ trailingPauseMs: value })} onComposition={composing => onComposition?.('trailingPauseMs', composing)} />
+    </div></>}
+    {!advanced && (drafts?.minimumHoldMs || drafts?.trailingPauseMs || draftStorageFailure) ? <span className="pm-ui-field__error" role="alert">{t.advancedDraft}</span>
+      : draftStorageFailure && <span className="pm-ui-field__error" role="alert">{t.storageFailure}</span>}
+  </section>
+}

package/src/approvals.tsx

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

package/src/assistant-mascot.ts

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

package/src/audio-recording-messages.ts

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