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

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,67 @@
-# Temporary Holding Version
+# @lincyaw/workbench
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Presmium's workbench panels in React, for teachers who know no code. The panels are:
+
+- 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:
+
+```tsx
+import { DocumentView, HomePanel, Workbench, WorkbenchProvider, workspaceClient } from '@lincyaw/workbench'
+import '@lincyaw/design/design.css'
+import '@lincyaw/workbench/styles.css'
+
+const workbench = new Workbench({ client: workspaceClient('api/presmium/'), locale: 'zh-CN' })
+
+export function Centre({ open }: { open: boolean }) {
+  return <WorkbenchProvider workbench={workbench}>{open ? <DocumentView /> : <HomePanel />}</WorkbenchProvider>
+}
+```
+
+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.
+
+Operations that an outside AI tool asks to perform appear as Approvals in the app bar, where the author allows or denies them.
+
+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/studio.md) (section 7)
+
+## License
+
+Apache-2.0.

package/package.json

@@ -1,6 +1,71 @@
 {
   "name": "@lincyaw/workbench",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "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",
+    "url": "git+https://github.com/Lincyaw/presmium.git",
+    "directory": "packages/workbench"
+  },
+  "homepage": "https://github.com/Lincyaw/presmium/tree/main/packages/workbench#readme",
+  "bugs": "https://github.com/Lincyaw/presmium/issues",
+  "keywords": [
+    "presmium",
+    "workbench",
+    "react"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.19"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./components": "./src/components.tsx",
+    "./styles.css": "./src/styles.css"
+  },
+  "files": [
+    "src"
+  ],
+  "dependencies": {
+    "@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.1.15",
+    "@radix-ui/react-radio-group": "^1.5.1",
+    "@radix-ui/react-tabs": "^1.2.1",
+    "@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",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/react": "18.3.28",
+    "@types/react-dom": "18.3.7",
+    "react": "^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>
+}