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

package/src/schema-form/context.ts

@@ -0,0 +1,26 @@
+import type { ControlDensity } from '../components.tsx'
+import type { RJSFSchema } from '@rjsf/utils'
+import type { ReactNode } from 'react'
+import type { DocumentParameterAccess } from '@lincyaw/kernel'
+export type FieldPathList = (string | number)[]
+
+export interface SchemaFormMessages { empty: string, unsupported: string, yes: string, no: string, choose: string, add: string, remove: string, up: string, down: string, number: string, composing: string, access: string, union: string }
+export const SCHEMA_FORM_MESSAGES: Record<'zh-CN' | 'en', SchemaFormMessages> = {
+  'zh-CN': { empty: '无公开参数', unsupported: '此参数暂不支持表单编辑', yes: '是', no: '否', choose: '请选择', add: '添加', remove: '移除', up: '上移', down: '下移', number: '请输入有效数字', composing: '请完成输入', access: '此参数暂不可编辑', union: '此分支暂不可编辑' },
+  en: { empty: 'No public parameters', unsupported: 'This parameter cannot be edited in this form', yes: 'Yes', no: 'No', choose: 'Choose', add: 'Add', remove: 'Remove', up: 'Move Up', down: 'Move Down', number: 'Enter a valid number', composing: 'Finish composing', access: 'This parameter is currently read-only', union: 'This branch is currently read-only' },
+}
+export interface SchemaFormContext {
+  density: ControlDensity
+  messages: SchemaFormMessages
+  paths: Map<string, FieldPathList>
+  schemas: Map<string, RJSFSchema>
+  readOnly: Map<string, boolean>
+  intent?: FieldPathList
+  intentReadOnly?: boolean
+  branch?: string
+  mark(id: string): void
+  inputError(id: string, error: string | undefined): void
+  access(path: FieldPathList): DocumentParameterAccess
+  hideProperties: ReadonlySet<string>
+  empty?: ReactNode
+}

package/src/schema-form/fields.tsx

@@ -0,0 +1,59 @@
+import { createContext, useContext, useLayoutEffect } from 'react'
+import { getDefaultRegistry } from '@rjsf/core'
+import { ADDITIONAL_PROPERTY_FLAG, getDiscriminatorFieldFromSchema, getOptionMatchingSimpleDiscriminator } from '@rjsf/utils'
+import type { FieldProps, RJSFMarkedSchema, RJSFSchema } from '@rjsf/utils'
+import type { FieldPathList, SchemaFormContext } from './context.ts'
+import { PmNotice } from '../components.tsx'
+
+export const SchemaFormPath = createContext<{ path: FieldPathList, id?: string }>({ path: [] })
+export const SchemaFormUnionFields = createContext<readonly { id: string, names: ReadonlySet<string> }[]>([])
+const native = getDefaultRegistry().fields, NativeSchemaField = native.SchemaField!
+
+/** The public marker distinguishes authored fields from properties inferred from additional data. */
+export function declaredSchemaProperties(schema: RJSFSchema): string[] {
+  return Object.entries(schema.properties ?? {}).filter(([, child]) => typeof child === 'boolean' || !(child as RJSFMarkedSchema)[ADDITIONAL_PROPERTY_FLAG]).map(([name]) => name)
+}
+
+/** Public SchemaField props retain exact property names, including punctuation, without parsing DOM IDs. */
+function SchemaField(props: FieldProps<unknown, any, SchemaFormContext>) {
+  const id = props.fieldPathId.$id, path = props.fieldPathId.path
+  const context = props.registry.formContext
+  const access = context.access(path), blocked = !access.available || !access.public
+  const hidden = Boolean((props.schema as RJSFMarkedSchema)[ADDITIONAL_PROPERTY_FLAG] || access.available && !access.public)
+  const readonly = Boolean(props.readonly || props.schema.readOnly || access.readOnly || blocked)
+  useLayoutEffect(() => {
+    if (hidden) return
+    context.paths.set(id, path); context.schemas.set(id, props.schema); context.readOnly.set(id, readonly)
+    return () => { if (context.schemas.get(id) === props.schema) { context.paths.delete(id); context.schemas.delete(id); context.readOnly.delete(id) } }
+  }, [context, id, props.schema, readonly, hidden, JSON.stringify(path)])
+  if (hidden) return null
+  return <SchemaFormPath.Provider value={{ path, id }}>{blocked && !props.readonly && <PmNotice>{context.messages.access}</PmNotice>}<NativeSchemaField {...props} readonly={readonly} /></SchemaFormPath.Provider>
+}
+
+/** Keep native branch state; omit only fields already rendered outside this exact union scope. */
+function unionField(Native: typeof NativeSchemaField) {
+  return function UnionField(props: FieldProps<unknown, any, SchemaFormContext>) {
+    const inherited = useContext(SchemaFormUnionFields)
+    let names: string[], supported = false
+    try {
+      const { schemaUtils, formContext } = props.registry, resolved = schemaUtils.retrieveSchema(props.schema, props.formData)
+      names = declaredSchemaProperties(resolved)
+      const selector = getDiscriminatorFieldFromSchema(props.schema)
+      const options = (props.options as RJSFSchema[]).map(option => schemaUtils.retrieveSchema(option, props.formData))
+      if (selector && options.length) {
+        const values = options.map(option => {
+          const property = option.properties?.[selector]
+          if (!property || typeof property === 'boolean' || !option.required?.includes(selector)) return undefined
+          const marker = schemaUtils.retrieveSchema(property, (props.formData as Record<string, unknown> | undefined)?.[selector])
+          if (!Object.hasOwn(marker, 'const') || marker.readOnly || marker.const !== null && !['string', 'number', 'boolean'].includes(typeof marker.const) || typeof marker.const === 'number' && !Number.isFinite(marker.const)) return undefined
+          return JSON.stringify(marker.const)
+        })
+        const access = formContext.access([...props.fieldPathId.path, selector])
+        supported = values.every(value => value !== undefined) && new Set(values).size === options.length && getOptionMatchingSimpleDiscriminator(props.formData, options, selector) !== undefined && access.available && access.public && !access.readOnly
+      }
+    }
+    catch { return <PmNotice>{props.registry.formContext.messages.unsupported}</PmNotice> }
+    return <SchemaFormUnionFields.Provider value={[...inherited, { id: props.fieldPathId.$id, names: new Set(names) }]}>{!supported && !props.readonly && <PmNotice>{props.registry.formContext.messages.union}</PmNotice>}<Native {...props} readonly={props.readonly || !supported} /></SchemaFormUnionFields.Provider>
+  }
+}
+export const schemaFormFields = { SchemaField, AnyOfField: unionField(native.AnyOfField!), OneOfField: unionField(native.OneOfField!) }

package/src/schema-form/templates.tsx

@@ -0,0 +1,50 @@
+import { useContext } from 'react'
+import type { FormProps } from '@rjsf/core'
+import type { ArrayFieldItemButtonsTemplateProps, ArrayFieldItemTemplateProps, ArrayFieldTemplateProps, FieldTemplateProps, ObjectFieldTemplateProps } from '@rjsf/utils'
+import { PmButton, PmField, PmIconButton, PmNotice } from '../components.tsx'
+import type { SchemaFormContext } from './context.ts'
+import { declaredSchemaProperties, SchemaFormPath, SchemaFormUnionFields } from './fields.tsx'
+
+function Field(props: FieldTemplateProps<unknown, any, SchemaFormContext>) {
+  if (props.hidden) return null
+  return <div className="pm-ui-schema-form__field">{props.children}{(props.schema.type === 'object' || props.schema.type === 'array') && props.rawErrors?.length ? <PmNotice tone="danger">{props.rawErrors.join(' · ')}</PmNotice> : null}</div>
+}
+function ObjectFields(props: ObjectFieldTemplateProps<unknown, any, SchemaFormContext>) {
+  const declared = new Set(declaredSchemaProperties(props.schema))
+  const fields = props.properties.filter(property => declared.has(property.name))
+  const scope = useContext(SchemaFormPath), context = props.registry.formContext
+  const unions = useContext(SchemaFormUnionFields)
+  const duplicate = (name: string) => unions.some(union => union.id === props.fieldPathId.$id && union.names.has(name))
+  const shown = fields.filter(property => !duplicate(property.name) && (scope.path.length || !context.hideProperties.has(property.name)))
+  if (scope.path.length && !fields.length && !props.schema.oneOf && !props.schema.anyOf) return null
+  if (fields.length && fields.every(property => duplicate(property.name))) return null
+  const children = shown.length ? <div className="pm-ui-schema-form__fields">{shown.map(property => <div key={property.name}>{property.content}</div>)}</div>
+    : props.schema.oneOf || props.schema.anyOf ? null : context.empty === undefined ? <span>{context.messages.empty}</span> : context.empty
+  return props.title ? <PmField label={props.title} group density={props.registry.formContext.density}>{children}</PmField> : children
+}
+function ArrayFields(props: ArrayFieldTemplateProps<unknown, any, SchemaFormContext>) {
+  const context = props.registry.formContext
+  return <PmField label={props.title} group density={context.density}><div className="pm-ui-schema-form__fields">{props.items}</div>
+    {props.canAdd && <PmButton small icon="plus" disabled={props.disabled || props.readonly} onClick={event => { context.intent = props.fieldPathId.path; context.intentReadOnly = Boolean(props.disabled || props.readonly); props.onAddClick(event) }}>{context.messages.add}</PmButton>}
+  </PmField>
+}
+function ArrayButtons(props: ArrayFieldItemButtonsTemplateProps<unknown, any, SchemaFormContext>) {
+  const context = props.registry.formContext
+  const invoke = (action: (event: unknown) => void, event: unknown) => { context.intent = props.fieldPathId.path.slice(0, -1); context.intentReadOnly = Boolean(props.disabled || props.readonly); action(event) }
+  return <div className="pm-ui-schema-form__actions">
+    {props.hasMoveUp && <PmButton small disabled={props.disabled || props.readonly} onClick={event => invoke(props.onMoveUpItem, event)}>{context.messages.up}</PmButton>}
+    {props.hasMoveDown && <PmButton small disabled={props.disabled || props.readonly} onClick={event => invoke(props.onMoveDownItem, event)}>{context.messages.down}</PmButton>}
+    {props.hasRemove && <PmIconButton small icon="trash" label={context.messages.remove} disabled={props.disabled || props.readonly} onClick={event => invoke(props.onRemoveItem, event)} />}
+  </div>
+}
+function ArrayItem(props: ArrayFieldItemTemplateProps<unknown, any, SchemaFormContext>) {
+  return <div className="pm-ui-schema-form__item"><div className="pm-ui-schema-form__field">{props.children}</div>{props.hasToolbar && <ArrayButtons {...props.buttonsProps} />}</div>
+}
+
+export const schemaFormTemplates: NonNullable<FormProps['templates']> = {
+  FieldTemplate: Field, ObjectFieldTemplate: ObjectFields, ArrayFieldTemplate: ArrayFields,
+  ArrayFieldItemTemplate: ArrayItem, ArrayFieldItemButtonsTemplate: ArrayButtons,
+  WrapIfAdditionalTemplate: () => null, ErrorListTemplate: () => null,
+  UnsupportedFieldTemplate: props => <PmNotice>{props.registry.formContext.messages.unsupported}</PmNotice>,
+  ButtonTemplates: { SubmitButton: () => null },
+}

package/src/schema-form/validator.ts

@@ -0,0 +1,36 @@
+import { validateDocumentParameters } from '@lincyaw/kernel'
+import type { DocumentParameterValidation, JsonSchema } from '@lincyaw/kernel'
+import { createErrorHandler, ErrorSchemaBuilder, ROOT_SCHEMA_PREFIX, unwrapErrorHandler, validationDataMerge, withIdRefPrefix } from '@rjsf/utils'
+import type { RJSFSchema, RJSFValidationError, ValidatorType } from '@rjsf/utils'
+
+const pathOf = (pointer: string) => pointer ? pointer.slice(1).split('/').map(value => value.replaceAll('~1', '/').replaceAll('~0', '~')) : []
+
+/** RJSF owns field discovery; CFworker remains the canonical validation implementation. */
+export function schemaFormValidator(root: RJSFSchema): ValidatorType {
+  const validate = (schema: RJSFSchema, data: unknown, rootSchema = root): DocumentParameterValidation => {
+    if (schema === rootSchema) return validateDocumentParameters(schema as JsonSchema, data)
+    const fragment = withIdRefPrefix(schema) as RJSFSchema
+    // RJSF's fragment refs point at the registered root, not the fragment's original resource ID.
+    delete fragment.$id
+    return validateDocumentParameters(fragment as JsonSchema, data, [{ id: ROOT_SCHEMA_PREFIX, schema: rootSchema as JsonSchema }])
+  }
+  return {
+    rawValidation<Result>(schema: RJSFSchema, data?: unknown) {
+      const result = validate(schema, data)
+      return result.available ? { errors: result.issues as Result[] } : { validationError: new Error(result.issues[0]?.message) }
+    },
+    isValid: (schema, data, rootSchema) => validate(schema, data, rootSchema).valid,
+    validateFormData(data, schema, customValidate, transformErrors, uiSchema) {
+      const result = validate(schema, data)
+      const issues = result.issues.filter(issue => !['properties', 'items', '$ref', 'allOf'].includes(issue.keyword)
+        || !result.issues.some(child => child !== issue && child.path.startsWith(issue.path) && child.keyword !== issue.keyword))
+      let errors: RJSFValidationError[] = issues.map(issue => ({ name: issue.keyword, message: issue.message, params: { instancePath: issue.path },
+        property: pathOf(issue.path).map(part => `[${JSON.stringify(part)}]`).join(''), schemaPath: issue.schemaPath, stack: `${issue.path} ${issue.message}` }))
+      if (transformErrors) errors = transformErrors(errors, uiSchema)
+      const builder = new ErrorSchemaBuilder()
+      errors.forEach(error => builder.addErrors(error.message ?? error.stack, typeof error.params?.instancePath === 'string' ? pathOf(error.params.instancePath) : []))
+      const validated = { errors, errorSchema: builder.ErrorSchema }
+      return customValidate ? validationDataMerge(validated, unwrapErrorHandler(customValidate(data, createErrorHandler(data), uiSchema))) : validated
+    },
+  }
+}

package/src/schema-form/widgets.tsx

@@ -0,0 +1,60 @@
+import { useEffect, useState } from 'react'
+import { enumOptionsValueForIndex } from '@rjsf/utils'
+import type { WidgetProps } from '@rjsf/utils'
+import { PmField, PmInput, PmNotice, PmSegmented, PmSelect, PmTextarea } from '../components.tsx'
+import type { SchemaFormContext } from './context.ts'
+
+type Props = WidgetProps<unknown, any, SchemaFormContext>
+const feedback = (props: Props) => props.rawErrors?.join(' · ')
+const change = (props: Props, value: unknown) => { if (!props.disabled && !props.readonly) { props.registry.formContext.mark(props.id); props.onChange(value) } }
+
+function Input(props: Props) {
+  const { id, value, schema, disabled, readonly, label, placeholder, registry, onBlur, onFocus } = props
+  const numeric = schema.type === 'number' || schema.type === 'integer'
+  const [draft, setDraft] = useState<string>(), [invalid, setInvalid] = useState(false)
+  useEffect(() => { setDraft(undefined); setInvalid(false); registry.formContext.inputError(id, undefined) }, [value])
+  useEffect(() => () => registry.formContext.inputError(id, undefined), [id])
+  return <PmInput id={id} label={label} value={draft ?? (value === undefined || value === null ? '' : String(value))} placeholder={placeholder}
+    disabled={disabled} readOnly={readonly} density={registry.formContext.density} inputMode={numeric ? 'decimal' : undefined} width={numeric ? 'number' : undefined}
+    error={invalid ? registry.formContext.messages.number : feedback(props)} hint={schema.description}
+    onFocus={() => onFocus(id, value)} onBlur={() => onBlur(id, value)} onChange={event => {
+      if (disabled || readonly) return
+      const text = event.currentTarget.value
+      if (!numeric) { change(props, text); return }
+      setDraft(text)
+      const number = Number(text), valid = text === '' || /^[-+]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[-+]?\d+)?$/i.test(text) && Number.isFinite(number)
+      setInvalid(!valid); registry.formContext.inputError(id, valid ? undefined : registry.formContext.messages.number)
+      change(props, !valid ? text : text === '' ? undefined : number)
+    }} />
+}
+
+function Select(props: Props) {
+  const { id, label, value, options, disabled, readonly, registry } = props
+  const choices = options.enumOptions ?? []
+  const selected = choices.findIndex(option => JSON.stringify(option.value) === JSON.stringify(value))
+  if (props.multiple) return <PmNotice>{registry.formContext.messages.unsupported}</PmNotice>
+  return <PmSelect id={id} label={label} value={selected < 0 ? '' : String(selected)} disabled={disabled || readonly} density={registry.formContext.density}
+    error={feedback(props)} onBlur={() => props.onBlur(id, value)} onFocus={() => props.onFocus(id, value)} onChange={event => {
+      change(props, enumOptionsValueForIndex(event.currentTarget.value, choices, options.emptyValue))
+    }}><option value="">{registry.formContext.messages.choose}</option>{choices.map((option, index) => <option key={index} value={index}>{option.label}</option>)}</PmSelect>
+}
+
+function Boolean(props: Props) {
+  const context = props.registry.formContext
+  return <PmField label={props.label} group error={feedback(props)} density={context.density}>
+    <PmSegmented label={props.label} value={typeof props.value === 'boolean' ? String(props.value) : ''} options={[{ value: 'true', label: context.messages.yes }, { value: 'false', label: context.messages.no }]}
+      disabled={props.disabled || props.readonly} density={context.density} onChange={value => change(props, value === 'true')} />
+  </PmField>
+}
+function Textarea(props: Props) {
+  return <PmTextarea id={props.id} label={props.label} value={props.value ?? ''} disabled={props.disabled} readOnly={props.readonly} density={props.registry.formContext.density}
+    error={feedback(props)} onChange={event => change(props, event.currentTarget.value)} />
+}
+function Unsupported(props: Props) { return <PmNotice>{props.registry.formContext.messages.unsupported}</PmNotice> }
+
+export const schemaFormWidgets = {
+  TextWidget: Input, UpDownWidget: Input, EmailWidget: Input, URLWidget: Input, PasswordWidget: Input,
+  DateWidget: Input, DateTimeWidget: Input, TimeWidget: Input, ColorWidget: Input, RangeWidget: Input,
+  TextareaWidget: Textarea, SelectWidget: Select, RadioWidget: Select, CheckboxWidget: Boolean,
+  CheckboxesWidget: Unsupported, FileWidget: Unsupported, HiddenWidget: Unsupported,
+}

package/src/shortcuts.ts

@@ -0,0 +1,8 @@
+const apple = typeof navigator !== 'undefined' && /Mac|iPhone|iPad|iPod/.test(navigator.platform || navigator.userAgent)
+
+/**
+ * The keys shown for the workbench's commands, one form per platform (docs/glossary.md, Undo and Redo): ⌘Z and ⌘⇧Z on
+ * Apple devices, Ctrl+Z and Ctrl+Y elsewhere. Both Ctrl+Y and Ctrl+Shift+Z (⌘⇧Z) redo, in the page and in the editor.
+ * Key names stay in English in both languages, as on the keys.
+ */
+export const SHORTCUTS = { ...apple ? { undo: '⌘Z', redo: '⌘⇧Z', save: '⌘S' } : { undo: 'Ctrl+Z', redo: 'Ctrl+Y', save: 'Ctrl+S' }, playPause: 'Space' }

package/src/sortable-list.tsx

@@ -0,0 +1,201 @@
+import { DragDropProvider, useDragDropManager } from '@dnd-kit/react'
+import type { DragEndEvent, DragOverEvent, DragStartEvent } from '@dnd-kit/react'
+import { isSortable, useSortable } from '@dnd-kit/react/sortable'
+import { Accessibility, Feedback } from '@dnd-kit/dom'
+import { useCallback, useId, useLayoutEffect, useMemo, useRef, useState } from 'react'
+import type { MutableRefObject, ReactNode } from 'react'
+import { PmIconButton } from './base-controls.tsx'
+import type { ControlDensity } from './base-controls.tsx'
+
+export interface SortableListItem {
+  id: string
+  label: string
+  prefix?: ReactNode
+  actions?: ReactNode
+  disabled?: boolean
+  /** Reordering can be unavailable while selection and the item's actions remain usable. */
+  reorderDisabled?: boolean
+}
+export interface SortableListLabels {
+  handle(label: string): string
+  instructions: string
+  pickedUp(label: string, index: number, count: number): string
+  position(label: string, index: number, count: number): string
+  dropped(label: string): string
+  cancelled(label: string): string
+  saving(label: string): string
+  saved(label: string, index: number, count: number): string
+  failed(label: string): string
+}
+export interface SortableListProps {
+  label: string
+  scopeKey: string
+  /** An external source replacement cancels a gesture without replacing the navigation control. */
+  resetKey?: string | number
+  items: readonly SortableListItem[]
+  value?: string
+  onSelect(id: string): void
+  onMove?(id: string, before: string | null): void | Promise<void>
+  /** These states block reordering, without blocking selection or caller-owned actions. */
+  reorderDisabled?: boolean
+  loading?: boolean
+  density?: ControlDensity
+  /** The workbench's interface language (its state's `locale`); the list does not choose one itself. */
+  locale: 'zh-CN' | 'en'
+  labels?: Partial<SortableListLabels>
+  className?: string
+}
+
+const MESSAGES: Record<'zh-CN' | 'en', SortableListLabels> = {
+  'zh-CN': {
+    handle: label => `移动：${label}`,
+    instructions: '按空格或回车开始移动，用方向键调整位置，再按空格或回车放下，按 Escape 取消。',
+    pickedUp: (label, index, count) => `已拾起“${label}”，第 ${index} 项，共 ${count} 项。`,
+    position: (label, index, count) => `${label}，位置 ${index}，共 ${count} 项。`,
+    dropped: label => `已放下“${label}”。`, cancelled: label => `已取消移动“${label}”。`,
+    saving: label => `正在移动“${label}”…`, saved: (label, index, count) => `已移动“${label}”，第 ${index} 项，共 ${count} 项。`,
+    failed: label => `无法移动“${label}”。`,
+  },
+  en: {
+    handle: label => `Move: ${label}`,
+    instructions: 'Press Space or Enter to pick up an item, use the arrow keys to move, then press Space or Enter to drop, or Escape to cancel.',
+    pickedUp: (label, index, count) => `Picked up ${label}, item ${index} of ${count}.`,
+    position: (label, index, count) => `${label}, position ${index} of ${count}.`,
+    dropped: label => `Dropped ${label}.`, cancelled: label => `Canceled moving ${label}.`,
+    saving: label => `Moving ${label}…`, saved: (label, index, count) => `Moved ${label}, item ${index} of ${count}.`,
+    failed: label => `Couldn’t move ${label}.`,
+  },
+}
+
+/** A changed list identity owns a fresh gesture and cannot receive an earlier move's completion. */
+export function PmSortableList(props: SortableListProps) {
+  const gesture = useRef(false), movePending = useRef(false), focus = useRef<string>()
+  const order = JSON.stringify(props.items.map(item => item.id)), members = JSON.stringify(props.items.map(item => item.id).sort())
+  const availability = JSON.stringify([props.reorderDisabled, props.loading, Boolean(props.onMove), props.items.map(item => [item.id, item.disabled, item.reorderDisabled])])
+  const previous = useRef({ scope: props.scopeKey, order, members, reset: props.resetKey, availability, generation: 0 })
+  if (previous.current.scope !== props.scopeKey) focus.current = undefined
+  if (gesture.current && (previous.current.scope !== props.scopeKey || previous.current.order !== order || previous.current.reset !== props.resetKey || previous.current.availability !== availability)
+    || movePending.current && previous.current.members !== members) {
+    previous.current.generation++; gesture.current = false; movePending.current = false
+  }
+  previous.current = { scope: props.scopeKey, order, members, reset: props.resetKey, availability, generation: previous.current.generation }
+  const signature = JSON.stringify([props.scopeKey, previous.current.generation, props.locale, props.labels?.instructions])
+  return <SortableSession key={signature} {...props} gesture={gesture} movePending={movePending} focus={focus} />
+}
+
+type AccessibilityOptions = NonNullable<ConstructorParameters<typeof Accessibility>[1]>
+
+function SortableGuard({ signature, revision, active, onReplace }: { signature: string, revision: string, active: MutableRefObject<boolean>, onReplace(): void }) {
+  const manager = useDragDropManager(), previous = useRef({ signature, revision })
+  useLayoutEffect(() => {
+    if (previous.current.signature !== signature || previous.current.revision !== revision) {
+      if (active.current) manager?.actions.stop({ canceled: true })
+      if (previous.current.revision !== revision) onReplace()
+    }
+    previous.current = { signature, revision }
+  }, [manager, signature, revision, onReplace])
+  return null
+}
+
+function SortableSession(props: SortableListProps & { gesture: MutableRefObject<boolean>, movePending: MutableRefObject<boolean>, focus: MutableRefObject<string | undefined> }) {
+  const { items, onMove, density = 'compact', locale } = props
+  const labels = useMemo(() => ({ ...MESSAGES[locale], ...props.labels }), [locale, props.labels])
+  const [pending, setPending] = useState<{ id: string, order: string[] }>(), [announcement, setAnnouncement] = useState('')
+  const alive = useRef(true), active = props.gesture, movePending = props.movePending, focus = props.focus, request = useRef<object>(), current = useRef({ props, labels })
+  const list = useRef<HTMLOListElement>(null), handles = useRef(new Map<string, HTMLButtonElement>())
+  const focusFrame = useRef<number>()
+  const pendingOrder = useRef<string[]>()
+  current.current = { props, labels }
+  useLayoutEffect(() => { alive.current = true; return () => { alive.current = false; request.current = undefined; active.current = false; movePending.current = false; if (focusFrame.current !== undefined) cancelAnimationFrame(focusFrame.current) } }, [])
+  const group = useId(), disabled = Boolean(props.reorderDisabled || props.loading || pending || !onMove)
+  const signature = JSON.stringify([props.reorderDisabled, props.loading, Boolean(onMove), items.map(item => [item.id, item.disabled, item.reorderDisabled])])
+  const orderKey = JSON.stringify(items.map(item => item.id)), revision = JSON.stringify([orderKey, props.resetKey])
+  const restoreFocus = () => {
+    const handle = focus.current && handles.current.get(focus.current), element = list.current?.ownerDocument.activeElement
+    if (handle && (element === document.body || [...handles.current.values()].includes(element as HTMLButtonElement))) handle.focus({ preventScroll: true })
+  }
+  useLayoutEffect(() => {
+    const select = (event: FocusEvent) => { if (event.target !== document.body) { const entry = [...handles.current].find(([, handle]) => handle === event.target); focus.current = entry?.[0] } }
+    const point = (event: PointerEvent) => { if (![...handles.current.values()].some(handle => handle.contains(event.target as Node))) focus.current = undefined }
+    const tab = (event: KeyboardEvent) => { if (event.key === 'Tab') focus.current = undefined }
+    const blur = () => { focus.current = undefined }
+    document.addEventListener('focusin', select); document.addEventListener('pointerdown', point); document.addEventListener('keydown', tab); window.addEventListener('blur', blur)
+    return () => { document.removeEventListener('focusin', select); document.removeEventListener('pointerdown', point); document.removeEventListener('keydown', tab); window.removeEventListener('blur', blur) }
+  }, [])
+  useLayoutEffect(restoreFocus, [orderKey, props.resetKey, Boolean(pending), signature])
+  const ordered = pending ? pending.order.flatMap(id => { const item = items.find(item => item.id === id); return item ? [item] : [] }) : items
+  const named = (id?: string | number) => current.current.props.items.find(item => item.id === id)?.label ?? ''
+  const accessibility = useMemo<AccessibilityOptions>(() => ({
+    screenReaderInstructions: { draggable: labels.instructions },
+    announcements: {
+      dragstart: ({ operation: { source } }: DragStartEvent) => source ? current.current.labels.pickedUp(named(source.id), isSortable(source) ? source.initialIndex + 1 : 1, current.current.props.items.length) : undefined,
+      dragover: ({ operation: { source } }: DragOverEvent) => source && isSortable(source) ? current.current.labels.position(named(source.id), source.index + 1, current.current.props.items.length) : undefined,
+      dragend: ({ operation: { source }, canceled }: DragEndEvent) => source ? canceled ? current.current.labels.cancelled(named(source.id)) : current.current.labels.dropped(named(source.id)) : undefined,
+    },
+  }), [labels])
+  return <DragDropProvider plugins={defaults => [...defaults, Feedback.configure({ dropAnimation: null, keyboardTransition: null }), Accessibility.configure(accessibility)]}
+    onBeforeDragStart={event => {
+      const source = event.operation.source, item = items.find(item => item.id === source?.id)
+      if (event.defaultPrevented || disabled || !item || item.disabled || item.reorderDisabled) event.preventDefault()
+      else active.current = true
+    }}
+    onDragStart={() => { active.current = true; setAnnouncement('') }}
+    onDragEnd={event => {
+      active.current = false
+      const source = event.operation.source
+      const element = document.activeElement
+      if (alive.current && source && event.nativeEvent instanceof KeyboardEvent && (element === document.body || [...handles.current.values()].includes(element as HTMLButtonElement))) {
+        focus.current = String(source.id)
+        if (focusFrame.current !== undefined) cancelAnimationFrame(focusFrame.current)
+        focusFrame.current = requestAnimationFrame(() => { focusFrame.current = undefined; if (alive.current) restoreFocus() })
+      }
+      if (!alive.current || disabled || event.canceled || !onMove || !isSortable(source) || !event.operation.target || source.initialIndex === source.index) return
+      const item = items[source.initialIndex]
+      if (!item || item.id !== source.id || item.disabled || item.reorderDisabled || source.index < 0 || source.index >= items.length) return
+      const order = items.map(item => item.id)
+      order.splice(source.initialIndex, 1); order.splice(source.index, 0, item.id)
+      const before = order[source.index + 1] ?? null, owner = {}
+      request.current = owner; movePending.current = true; pendingOrder.current = order; setPending({ id: item.id, order }); setAnnouncement(labels.saving(item.label))
+      void (async () => {
+        try {
+          await onMove(item.id, before)
+          if (alive.current && request.current === owner) setAnnouncement(current.current.labels.saved(item.label, order.indexOf(item.id) + 1, order.length))
+        } catch {
+          if (alive.current && request.current === owner) setAnnouncement(current.current.labels.failed(item.label))
+        } finally {
+          if (alive.current && request.current === owner) { request.current = undefined; movePending.current = false; pendingOrder.current = undefined; setPending(undefined) }
+        }
+      })()
+    }}>
+    <ol ref={list} className={['pm-ui-sortable-list', 'pm-ui', props.className].filter(Boolean).join(' ')} aria-label={props.label} aria-busy={Boolean(props.loading || pending) || undefined} data-density={density}>
+      {ordered.map((item, index) => <SortableRow key={item.id} item={item} index={index} group={group} density={density} selected={item.id === props.value} disabled={disabled} loading={Boolean(props.loading || pending?.id === item.id)} label={labels.handle(item.label)} onSelect={props.onSelect} onHandle={element => { if (element) handles.current.set(item.id, element); else handles.current.delete(item.id) }} onSettled={restoreFocus} />)}
+    </ol>
+    <p role="status" className="pm-ui-sr-only">{announcement}</p>
+    <SortableGuard signature={signature} revision={revision} active={active} onReplace={() => {
+      if (pendingOrder.current && JSON.stringify(pendingOrder.current) === orderKey) return
+      request.current = undefined; movePending.current = false; pendingOrder.current = undefined; setPending(undefined); setAnnouncement('')
+    }} />
+  </DragDropProvider>
+}
+
+function SortableRow({ item, index, group, density, selected, disabled, loading, label, onSelect, onHandle, onSettled }: {
+  item: SortableListItem, index: number, group: string, density: ControlDensity, selected: boolean, disabled: boolean, loading: boolean, label: string, onSelect(id: string): void, onHandle(element: HTMLButtonElement | null): void, onSettled(): void,
+}) {
+  const { ref, handleRef, isDragSource } = useSortable({ id: item.id, index, group, type: group, accept: group, disabled: disabled || item.disabled || item.reorderDisabled, transition: null })
+  const callbacks = useRef({ handleRef, onHandle })
+  callbacks.current = { handleRef, onHandle }
+  const attachHandle = useCallback((element: HTMLButtonElement | null) => {
+    callbacks.current.handleRef(element); callbacks.current.onHandle(element)
+  }, [])
+  const wasDragging = useRef(false)
+  useLayoutEffect(() => { if (wasDragging.current && !isDragSource) onSettled(); wasDragging.current = isDragSource }, [isDragSource, onSettled])
+  return <li ref={ref} className="pm-ui-sortable-list__row" data-sortable-id={item.id} data-density={density} data-selected={selected || undefined} data-dragging={isDragSource || undefined}>
+    <PmIconButton ref={attachHandle} icon="grip" label={label} density={density} className="pm-ui-sortable-list__handle" disabled={disabled || item.disabled || item.reorderDisabled} loading={loading} tooltip={false} onPointerDownCapture={event => {
+      if (event.isPrimary && event.button === 0 && !event.currentTarget.disabled) event.currentTarget.focus({ preventScroll: true })
+    }} />
+    <button type="button" className="pm-ui-sortable-list__select" disabled={item.disabled} aria-current={selected ? 'location' : undefined} onClick={() => onSelect(item.id)}>
+      {item.prefix !== undefined && <span className="pm-ui-sortable-list__prefix">{item.prefix}</span>}<span className="pm-ui-sortable-list__label">{item.label}</span>
+    </button>
+    {item.actions && <span className="pm-ui-sortable-list__actions">{item.actions}</span>}
+  </li>
+}

package/src/speech-settings-messages.ts

@@ -0,0 +1,40 @@
+import type { Locale } from './messages.ts'
+
+const zh = {
+  title: '语音服务', provider: '火山引擎', service: '默认服务', model: '语音合成 2.0',
+  description: '配置此工作区的配音服务，保存后立即生效。',
+  key: '语音密钥', keyPlaceholder: '输入 API Key 或 Access Token', keySaved: '已配置，留空保留',
+  keyHint: '使用语音 API Key，或与 App ID 配套的 Access Token。',
+  appId: 'App ID（可选）', appIdPlaceholder: '使用 API Key 时留空', appIdHint: '使用 Access Token 时填写对应 App ID；不需要 Secret Key。输入新的密钥且留空此项时，使用 API Key。',
+  console: '打开语音控制台',
+  source: { saved: '使用本机保存的密钥', environment: '使用启动环境中的密钥', none: '尚未配置密钥' },
+  configured: '已配置，尚未验证服务权限', unconfigured: '未配置',
+  verification: '检查配置仅检查已保存的本机设置，服务权限在播放或试听时验证。请先开通语音合成服务；播放会按需生成并缓存配音，可能产生服务费用。',
+  privacy: '密钥仅保存在本机此工作区的服务配置中，不写入讲义。',
+  check: '检查配置', save: '保存', saved: '语音服务已保存，无需重启。', checked: '本机配置可用。请通过试听验证服务权限。',
+  remove: '清除已保存密钥', removeTitle: '清除语音服务密钥', removeHint: '清除本机保存的密钥后恢复启动环境中的配置；讲稿、音色选择和已有配音保留。', cancel: '取消',
+  cleared: '已清除本机保存的密钥。', retry: '重新加载', loading: '正在加载语音服务设置…',
+  unavailable: '无法读取语音服务设置，请重试。', invalid: '请输入有效的语音密钥和对应 App ID。',
+  conflict: '设置已在别处更新。当前输入已保留，请重新加载后再保存。', busy: '设置正在被更新，请稍后重试。',
+  failed: '无法保存语音服务设置。当前输入已保留，请重试。',
+}
+export const SPEECH_SETTINGS_MESSAGES: Record<Locale, typeof zh> = {
+  'zh-CN': zh,
+  en: {
+    title: 'Voice Service', provider: 'Volcengine', service: 'Default service', model: 'Speech synthesis 2.0',
+    description: 'Configure voiceover for this workspace. Saved settings apply immediately.',
+    key: 'Speech Key', keyPlaceholder: 'Enter an API key or access token', keySaved: 'Configured; leave blank to keep',
+    keyHint: 'Use a speech API key, or an access token paired with an App ID.',
+    appId: 'App ID (optional)', appIdPlaceholder: 'Leave blank for an API key', appIdHint: 'Enter the matching App ID for an access token; no secret key is needed. A new key with this field blank uses API key authentication.',
+    console: 'Open Speech Console',
+    source: { saved: 'Using a key saved on this machine', environment: 'Using the launch environment key', none: 'No key configured' },
+    configured: 'Configured; service permissions not verified', unconfigured: 'Not configured',
+    verification: 'Checking configuration checks saved local settings. Playback or a sample verifies service permissions. Enable speech synthesis first; playback generates and caches missing voiceover and may incur service charges.',
+    privacy: 'The key stays in this workspace’s service settings on this machine, outside the document.',
+    check: 'Check Configuration', save: 'Save', saved: 'Voice service saved. No restart is needed.', checked: 'Local settings are available. Play a sample to verify service permissions.',
+    remove: 'Clear Saved Key', removeTitle: 'Clear Voice Service Key', removeHint: 'Clearing the saved key restores the launch environment configuration. Scripts, voice choices, and generated audio are kept.', cancel: 'Cancel',
+    cleared: 'The saved key was cleared.', retry: 'Reload', loading: 'Reading voice service settings…',
+    unavailable: 'Couldn’t read voice service settings. Try again.', invalid: 'Enter a valid speech key and matching App ID.',
+    conflict: 'Settings changed elsewhere. Your input is kept; reload before saving.', busy: 'Settings are being updated. Try again shortly.', failed: 'Couldn’t save voice service settings. Your input is kept; try again.',
+  },
+}

package/src/step-production.css

@@ -0,0 +1,5 @@
+.pm-ui-step-production { display: grid; gap: var(--pm-space-3); min-width: 0; }
+.pm-ui-step-production__heading { display: flex; flex-wrap: wrap; align-items: center; justify-content: space-between; gap: var(--pm-space-2); }
+.pm-ui-step-production__durations { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); max-width: calc(var(--pm-control-time-width) * 2 + var(--pm-space-3)); align-items: start; gap: var(--pm-space-3); }
+.pm-ui-step-production__actions { display: flex; flex-wrap: wrap; align-items: flex-start; gap: var(--pm-space-3); }
+.pm-ui-step-production__narration-settings { display: grid; gap: var(--pm-space-1); }

package/src/step-production.ts

@@ -0,0 +1,51 @@
+import type { StepProduction, TeachingDocument } from '@lincyaw/kernel'
+
+export const STEP_TIMING_KEYS = ['narrationStart', 'minimumHoldMs', 'trailingPauseMs'] as const
+export type StepTimingKey = typeof STEP_TIMING_KEYS[number]
+export type StepTimingPatch = { [K in StepTimingKey]?: StepProduction[K] | null }
+export type ProductionSource = 'step' | 'section' | 'document' | 'unset'
+export type StepDurationKey = 'minimumHoldMs' | 'trailingPauseMs'
+/** An unaccepted form value; never serialized into Production. */
+export interface StepDurationDraft { text: string, error: boolean, review?: boolean }
+
+/** The source is author intent; an absent value is not a fabricated playback default. */
+export function stepTimingValue<K extends StepTimingKey>(document: TeachingDocument, stepId: string, key: K): { value: StepProduction[K], source: ProductionSource } {
+  const production = document.production, step = document.steps[stepId]
+  const layers = [[production.stepOverrides[stepId], 'step'], [step && production.sectionOverrides?.[step.sectionId], 'section'], [production.defaults, 'document']] as const
+  for (const [settings, source] of layers) if (settings?.[key] !== undefined) return { value: settings[key], source }
+  return { value: undefined, source: 'unset' }
+}
+
+/** Migrated narration defaults are inherited until this step explicitly overrides its start. */
+export function stepNarrationStarts(document: TeachingDocument, stepId: string) {
+  const inherited = stepTimingValue(document, stepId, 'narrationStart')
+  return (document.steps[stepId]?.narrationIds ?? []).map(id => ({ id,
+    value: inherited.source === 'step' ? inherited.value : document.production.narrationOverrides?.[id]?.narrationStart ?? inherited.value,
+    overridden: inherited.source !== 'step' && document.production.narrationOverrides?.[id]?.narrationStart !== undefined,
+  }))
+}
+
+/** Patches only author-owned timing; voice, cues, media and other steps retain their source values. */
+export function changeStepTiming(document: TeachingDocument, stepId: string, patch: StepTimingPatch): TeachingDocument {
+  const step = document.steps[stepId]
+  if (!step || !document.sections[step.sectionId]?.stepOrder.includes(stepId)) return document
+  for (const key of Object.keys(patch)) if (!STEP_TIMING_KEYS.includes(key as StepTimingKey)) throw new Error('document-production-key')
+  const previous = document.production.stepOverrides[stepId], next = { ...previous }
+  for (const key of STEP_TIMING_KEYS) {
+    if (!Object.hasOwn(patch, key)) continue
+    const value = patch[key]
+    if (value === null || value === undefined) delete next[key]
+    else if (key === 'narrationStart') {
+      if (value !== 'with-animation' && value !== 'after-animation') throw new Error('document-production-start')
+      next.narrationStart = value
+    } else {
+      if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) throw new Error('document-production-duration')
+      next[key] = value
+    }
+  }
+  const stepOverrides = { ...document.production.stepOverrides }
+  if (Object.keys(next).length) stepOverrides[stepId] = next
+  else delete stepOverrides[stepId]
+  const production = { ...document.production, stepOverrides }
+  return JSON.stringify(document.production) === JSON.stringify(production) ? document : { ...document, production }
+}