@lincyaw/workbench 0.1.0 → 0.2.0-rc.0

package/src/document-editor/BlockNoteSurface.tsx

@@ -0,0 +1,209 @@
+import { forwardRef, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react'
+import type { ForwardRefExoticComponent, ReactNode, RefAttributes } from 'react'
+import { filterSuggestionItems } from '@blocknote/core'
+import { BlockNoteView, components } from '@blocknote/mantine'
+import { AddCommentButton, BasicTextStyleButton, BlockNoteViewEditor, BlockTypeSelect, ComponentsContext, CreateLinkButton, FormattingToolbar, FormattingToolbarController, getDefaultReactSlashMenuItems, LinkToolbarController, NestBlockButton, RenderInPortalElement, SideMenuController, SuggestionMenuController, TableCellMergeButton, TableHandlesController, TextAlignButton, UnnestBlockButton, useBlockNoteEditor, useCreateBlockNote, useEditorState } from '@blocknote/react'
+import type { ComponentProps, FormattingToolbarProps } from '@blocknote/react'
+import { useMediaQuery } from '@mantine/hooks'
+import type { Locale } from '../messages.ts'
+import { PmIconButton, PmNotice, PmTooltip } from '../components.tsx'
+import { DOCUMENT_NODE_VIEWS, documentEditorSchema } from './schema.tsx'
+import type { DocumentEditorBlock, DocumentEditorInput, DocumentNodeViews, NativeDocumentEditor } from './schema.tsx'
+import { documentSelection } from './selection.ts'
+import type { NativeDocumentSelection } from './selection.ts'
+import { DOCUMENT_EDITOR_MESSAGES, IMAGE_IMPORT_MESSAGES, slashAliases } from './messages.ts'
+import { blockNoteDictionary } from './blocknote-messages.ts'
+import { imageFileInput } from './file-input.ts'
+import type { ImageImportFailure } from './file-input.ts'
+import { nativeTextClipboard } from './clipboard.ts'
+import { documentBlockColors } from './colors.ts'
+import { DOCUMENT_EDITOR_LOCALE } from './math.tsx'
+import { DOCUMENT_LINKS, DocumentColorButton, DocumentLinkToolbar, DocumentSideMenu, DocumentTableCellButton, DocumentTableHandle, FormulaToolbarButton, formulaSlashItems, openDocumentLink } from './authoring.tsx'
+import type { DocumentLinks } from './authoring.tsx'
+import { excludeCommentMarkHistory, nativeComments, nativeCommentSelection } from './comments.ts'
+import type { DocumentThreadStore } from './comments.ts'
+import { DocumentMenuRoot, linkToolbarFloating } from './popover.tsx'
+import { COMMENT_EDITOR_CONTEXT, DocumentCommentEditor, DocumentFloatingThreadController, DocumentThreadsSidebar } from './DocumentComments.tsx'
+import { DocumentNewCommentController, DocumentNewCommentRecovery, NewCommentDraftProvider } from './NewCommentDrafts.tsx'
+
+export const DOCUMENT_EDITOR_THEME = {
+  colors: {
+    editor: { background: 'var(--pm-color-surface)', text: 'var(--pm-color-ink)' },
+    menu: { background: 'var(--pm-color-surface)', text: 'var(--pm-color-ink)' },
+    tooltip: { background: 'var(--pm-color-surface)', text: 'var(--pm-color-ink)' },
+    hovered: { background: 'var(--pm-color-sunk)', text: 'var(--pm-color-ink)' },
+    selected: { background: 'var(--pm-color-accent-soft)', text: 'var(--pm-color-accent)' },
+    disabled: { background: 'var(--pm-color-sunk)', text: 'var(--pm-color-muted)' },
+    border: 'var(--pm-color-line)', shadow: 'var(--pm-color-backdrop)', sideMenu: 'var(--pm-color-muted)',
+  },
+  fontFamily: 'var(--pm-font-sans)',
+}
+
+const MantineComment = components.Comments.Comment as ForwardRefExoticComponent<ComponentProps['Comments']['Comment'] & RefAttributes<HTMLDivElement>>
+const DocumentComment = forwardRef<HTMLDivElement, ComponentProps['Comments']['Comment']>(function DocumentComment(props, ref) {
+  const coarse = useMediaQuery('(pointer: coarse)', false, { getInitialValueInEffect: false })
+  const className = [props.className, props.actions ? 'pm-ui-comment-actions-row' : undefined].filter(Boolean).join(' ')
+  return <MantineComment {...props} ref={ref} className={className} showActions={coarse && props.showActions === 'hover' ? true : props.showActions} />
+})
+const MantineBadge = components.Generic.Badge.Root as ForwardRefExoticComponent<ComponentProps['Generic']['Badge']['Root'] & RefAttributes<HTMLInputElement>>
+const DocumentReactionBadge = forwardRef<HTMLInputElement, ComponentProps['Generic']['Badge']['Root']>(function DocumentReactionBadge(props, ref) {
+  if (!props.className?.split(/\s+/).includes('bn-comment-reaction')) return <MantineBadge {...props} ref={ref} />
+  const label = [props.mainTooltip, props.secondaryTooltip?.replace(/\s+/g, ' ')].filter(Boolean).join(' · ')
+  // Keep the input mounted while tooltip visibility changes; let its label own activation and focus.
+  return <PmTooltip label={label}><span><MantineBadge {...props} mainTooltip={undefined} secondaryTooltip={undefined} ref={ref}
+    onClick={event => { if (event.target instanceof HTMLInputElement) props.onClick?.(event) }} /></span></PmTooltip>
+})
+
+const MantineToolbarButton = components.Generic.Toolbar.Button as ForwardRefExoticComponent<ComponentProps['Generic']['Toolbar']['Button'] & RefAttributes<HTMLButtonElement>>
+const DocumentToolbarButton = forwardRef<HTMLButtonElement, ComponentProps['Generic']['Toolbar']['Button']>(function DocumentToolbarButton(props, ref) {
+  const label = props.label ?? props.mainTooltip
+  return label === undefined ? <MantineToolbarButton {...props} ref={ref} /> : <MantineToolbarButton {...props} ref={ref} label={label} />
+})
+
+const DOCUMENT_EDITOR_COMPONENTS = { ...components, Generic: { ...components.Generic, Menu: { ...components.Generic.Menu, Root: DocumentMenuRoot }, Badge: { ...components.Generic.Badge, Root: DocumentReactionBadge }, Toolbar: { ...components.Generic.Toolbar, Button: DocumentToolbarButton } }, Comments: { ...components.Comments, Comment: DocumentComment, Editor: DocumentCommentEditor } }
+
+export interface BlockNoteSurfaceProps {
+  identity: string
+  /** Explicit replacement of an external source; an own save acknowledgement must not change it. */
+  reset?: number
+  initialContent: DocumentEditorInput[]
+  locale: Locale
+  /** The language the document is written in (its `lang`), so the browser shapes its text and punctuation for it. */
+  contentLang?: string
+  readOnly?: boolean
+  resolveAssetURL?(location: string): Promise<string>
+  uploadImage?(file: File, signal: AbortSignal): Promise<string>
+  nodeViews?: DocumentNodeViews
+  onChange(blocks: DocumentEditorBlock[], editor: NativeDocumentEditor): void
+  onSelection?(selection: NativeDocumentSelection | undefined): void
+  comments?: DocumentThreadStore
+  commentsPortal?: HTMLElement | null
+  getPositionToken?(): string | undefined
+  onCommentDraftRestore?(): void
+  onReady?(editor: NativeDocumentEditor | undefined): void
+  onComposition?(composing: boolean): void
+  /** Shows a page of this document from an in-document link; false when none matches. */
+  onSectionLink?(sectionId: string): boolean
+  children?: ReactNode
+}
+
+function EditorToolbar(props: FormattingToolbarProps) {
+  const editor = useBlockNoteEditor(documentEditorSchema)
+  const title = useEditorState({ editor, selector: ({ editor }) => editor.getSelection()?.blocks.some(block => block.type === 'presmiumPage') ?? false })
+  if (title) return <FormattingToolbar {...props}><AddCommentButton /></FormattingToolbar>
+  return <FormattingToolbar {...props}>
+    <BlockTypeSelect items={props.blockTypeSelectItems} />
+    <BasicTextStyleButton basicTextStyle="bold" /><BasicTextStyleButton basicTextStyle="italic" />
+    <BasicTextStyleButton basicTextStyle="underline" /><BasicTextStyleButton basicTextStyle="strike" /><BasicTextStyleButton basicTextStyle="code" />
+    <TextAlignButton textAlignment="left" /><TextAlignButton textAlignment="center" /><TextAlignButton textAlignment="right" />
+    <DocumentColorButton /><NestBlockButton /><UnnestBlockButton /><CreateLinkButton /><FormulaToolbarButton />
+    <TableCellMergeButton />
+    <AddCommentButton />
+  </FormattingToolbar>
+}
+
+function PlainContentComments({ editor }: { editor: NativeDocumentEditor }) {
+  const show = useEditorState({ editor, selector: ({ editor }) => {
+    if (editor.prosemirrorState.selection.empty) return false
+    let plain = false
+    editor.prosemirrorState.selection.content().content.descendants(node => { if (node.type.spec.content === 'text*') plain = true; return !plain })
+    return plain
+  } })
+  // BlockNote hides formatting controls over code; its own comment action still applies.
+  return show && editor.getExtension('comments') ? <div className="pm-document-editor__comment-tools"><FormattingToolbar><AddCommentButton /></FormattingToolbar></div> : null
+}
+
+// Formulas join the group that holds tables so the menu keeps one heading per group.
+function withFormulas<Item extends { group?: string }>(items: Item[], formulas: Item[]): Item[] {
+  const index = items.findLastIndex(item => item.group === formulas[0]?.group)
+  return index < 0 ? [...items, ...formulas] : [...items.slice(0, index + 1), ...formulas, ...items.slice(index + 1)]
+}
+
+/** One native editor owns selection, transactions and history across the complete document. */
+export function BlockNoteSurface(props: BlockNoteSurfaceProps) {
+  const current = useRef(props)
+  const uploads = useMemo(() => ({ controllers: new Set<AbortController>(), pending: Promise.resolve() }), [props.identity, props.reset ?? 0])
+  const [fileErrors, setFileErrors] = useState<{ identity: string, failures: ImageImportFailure[] }>()
+  current.current = props
+  const dictionary = blockNoteDictionary(props.locale)
+  const t = DOCUMENT_EDITOR_MESSAGES[props.locale]
+  const linkToolbarOptions = useMemo(linkToolbarFloating, [])
+  const links = useMemo<DocumentLinks>(() => ({ openSection: sectionId => current.current.onSectionLink?.(sectionId) ?? false }), [])
+  const fileMessages = IMAGE_IMPORT_MESSAGES[props.locale]
+  const editor = useCreateBlockNote({ schema: documentEditorSchema, initialContent: props.initialContent,
+    resolveFileUrl: location => current.current.resolveAssetURL?.(location) ?? Promise.resolve(location),
+    uploadFile: props.uploadImage ? file => {
+      const controller = new AbortController()
+      const uploadImage = current.current.uploadImage!
+      uploads.controllers.add(controller)
+      const request = uploads.pending.then(async () => {
+        controller.signal.throwIfAborted()
+        if (current.current.identity !== props.identity) throw new DOMException('Document changed', 'AbortError')
+        return uploadImage(file, controller.signal)
+      })
+      uploads.pending = request.then(() => {}, () => {})
+      return request.finally(() => { uploads.controllers.delete(controller) })
+    } : undefined,
+    disableExtensions: ['dropFile'],
+    pasteHandler: ({ event, editor, defaultPasteHandler }) => {
+      const files = [...event.clipboardData?.files ?? []]
+      if (files.length && !event.clipboardData?.getData('text/html')) {
+        editor.getExtension(imageFileInput)?.insert(files)
+        return true
+      }
+      return defaultPasteHandler({ prioritizeMarkdownOverHTML: false })
+    },
+    dictionary, tables: { splitCells: true, cellBackgroundColor: true, cellTextColor: true, headers: true },
+    // The surface's own click handler opens links in editable and read-only states alike.
+    links: { onClick: () => true },
+    extensions: [nativeTextClipboard, documentBlockColors, imageFileInput({
+      onStart: () => { if (current.current.identity === props.identity) setFileErrors(undefined) },
+      onFailure: failure => { if (current.current.identity === props.identity) setFileErrors(value => ({ identity: props.identity, failures: [...(value?.identity === props.identity ? value.failures : []), failure] })) },
+    }), ...props.comments ? [nativeCommentSelection(), nativeComments(props.comments, t.author)] : []],
+    domAttributes: { block: { 'data-document-editor-block': '' }, editor: { lang: props.contentLang ?? props.locale } },
+  }, [props.identity, props.reset ?? 0])
+  useEffect(() => {
+    const stopCommentHistory = current.current.comments ? excludeCommentMarkHistory(editor) : undefined
+    current.current.onReady?.(editor)
+    return () => {
+      for (const controller of uploads.controllers) controller.abort()
+      uploads.controllers.clear()
+      stopCommentHistory?.(); current.current.onReady?.(undefined)
+    }
+  }, [editor])
+  return <DOCUMENT_EDITOR_LOCALE.Provider value={props.locale}><DOCUMENT_LINKS.Provider value={links}><DOCUMENT_NODE_VIEWS.Provider value={props.nodeViews ?? {}}><COMMENT_EDITOR_CONTEXT.Provider value={props.comments ? { store: props.comments, locale: props.locale, sidebar: Boolean(props.commentsPortal), getPositionToken: () => current.current.getPositionToken?.(), onDraftRestore: () => current.current.onCommentDraftRestore?.() } : undefined}>
+    <div className="pm-document-editor pm-ui-block-editor pm-ui" data-document-editor={props.identity}
+      onDragEnter={event => { if (event.dataTransfer.types.includes('Files')) event.stopPropagation() }}
+      onDragOver={event => { if (event.dataTransfer.types.includes('Files')) event.stopPropagation() }}
+      onClick={event => {
+        const link = event.target instanceof Element ? event.target.closest('a[data-inline-content-type="link"]') : null
+        const href = link?.getAttribute('href')
+        if (!href || event.button !== 0) return
+        event.preventDefault()
+        openDocumentLink(href, links)
+      }}
+      onCompositionStart={() => current.current.onComposition?.(true)}
+      onCompositionEnd={() => queueMicrotask(() => current.current.onComposition?.(false))}>
+      {fileErrors?.identity === props.identity && <PmNotice tone="danger"><div className="pm-document-editor__file-errors"><ul>{fileErrors.failures.map((failure, index) => <li key={index}>{failure.name} · {fileMessages[failure.kind]}</li>)}</ul><PmIconButton small icon="close" label={fileMessages.dismiss} onClick={() => setFileErrors(undefined)} /></div></PmNotice>}
+      <BlockNoteView editor={editor} editable={!props.readOnly} theme={DOCUMENT_EDITOR_THEME} formattingToolbar={false} slashMenu={false} linkToolbar={false} sideMenu={false} tableHandles={false} renderEditor={false} comments={false}
+        onChange={() => current.current.onChange(editor.document, editor)}
+        onSelectionChange={() => current.current.onSelection?.(documentSelection(editor))}>
+        <ComponentsContext.Provider value={DOCUMENT_EDITOR_COMPONENTS}>
+        <PlainContentComments editor={editor} />
+        <BlockNoteViewEditor><NewCommentDraftProvider>
+        <DocumentNewCommentController />{!props.commentsPortal && <DocumentFloatingThreadController />}{props.commentsPortal && <><RenderInPortalElement target={props.commentsPortal}><DocumentThreadsSidebar><DocumentNewCommentRecovery /></DocumentThreadsSidebar></RenderInPortalElement></>}
+        <FormattingToolbarController formattingToolbar={EditorToolbar} />
+        <LinkToolbarController linkToolbar={DocumentLinkToolbar} floatingUIOptions={linkToolbarOptions} />
+        <SideMenuController sideMenu={DocumentSideMenu} />
+        <TableHandlesController tableHandle={DocumentTableHandle} tableCellHandle={DocumentTableCellButton} />
+        <SuggestionMenuController triggerCharacter="/" getItems={async query => editor.getTextCursorPosition().block.type === 'presmiumPage' ? [] : filterSuggestionItems([...withFormulas(getDefaultReactSlashMenuItems(editor), formulaSlashItems(editor, props.locale, dictionary.slash_menu.table.group)), {
+          title: t.page, aliases: slashAliases('pageAliases'), group: t.document,
+          onItemClick: () => { const current = editor.getTextCursorPosition().block; editor.insertBlocks([{ type: 'presmiumPage', props: { sectionId: crypto.randomUUID() }, content: t.untitledPage }], current, 'after') },
+        }], query)} />
+        {props.children}
+        </NewCommentDraftProvider></BlockNoteViewEditor>
+        </ComponentsContext.Provider>
+      </BlockNoteView>
+    </div>
+  </COMMENT_EDITOR_CONTEXT.Provider></DOCUMENT_NODE_VIEWS.Provider></DOCUMENT_LINKS.Provider></DOCUMENT_EDITOR_LOCALE.Provider>
+}

package/src/document-editor/ComponentMaterials.tsx

@@ -0,0 +1,62 @@
+import { useMemo } from 'react'
+import { applyDocumentComponentAction } from '@lincyaw/kernel'
+import type { Definition, TeachingDocument } from '@lincyaw/kernel'
+import { PmButton, PmMenu, PmSearchList } from '../components.tsx'
+import type { ComponentPropertyMessages } from '../component-property-messages.ts'
+
+export function componentDefinitionLabel(definition: Definition): string {
+  const title = typeof definition.parameterSchema === 'object' && typeof definition.parameterSchema.title === 'string' ? definition.parameterSchema.title.trim() : ''
+  if (title) return Array.from(title).slice(0, 80).join('')
+  const implementation = definition.implementation
+  const name = implementation.type === 'file' ? implementation.path.split('/').at(-1)?.replace(/\.(tsx?|jsx?|mjs|cjs)$/, '')
+    : implementation.type === 'plugin' ? implementation.name : implementation.specifier.split('/').at(-1)
+  return Array.from(name || definition.kind).slice(0, 80).join('')
+}
+
+/** Selection is a proposal; only the caller's source-bound Apply changes a binding. */
+export function ComponentMaterials({ document, blockId, selected, onSelect, onLocate, disabled, messages: t }: {
+  document: TeachingDocument, blockId: string, selected: string, onSelect(id: string): void,
+  onLocate(blockId: string): void, disabled: boolean, messages: ComponentPropertyMessages,
+}) {
+  const current = document.blocks[blockId]
+  const choices = useMemo(() => {
+    const definitions = Object.values(document.definitions), names = definitions.map(componentDefinitionLabel)
+    const counts = new Map<string, number>()
+    for (const name of names) counts.set(name, (counts.get(name) ?? 0) + 1)
+    return definitions.map((definition, index) => {
+    let reason: string | undefined
+    if (definition.implementation.type === 'module') reason = t.module
+    else {
+      try { applyDocumentComponentAction(document, { type: 'component.definition.use', blockId, definitionId: definition.id }) }
+      catch { reason = t.incompatible }
+    }
+    const name = names[index]!, duplicate = counts.get(name)! > 1
+    return { value: definition.id, label: duplicate ? `${name} · ${index + 1}` : name, keywords: [definition.kind, definition.id, name], disabled: Boolean(reason),
+      description: reason ?? (current?.type === 'component' && current.definitionId === definition.id ? t.current : undefined) }
+    })
+  }, [document, blockId, current, t])
+  const references = useMemo(() => {
+    const pages = new Map<string, string>()
+    const visit = (id: string, page: string) => {
+      if (pages.has(id)) return
+      pages.set(id, page)
+      const block = document.blocks[id]
+      if (block?.type === 'component' || block?.type === 'container') for (const child of block.children ?? []) visit(child, page)
+    }
+    for (const id of document.sectionOrder) for (const child of document.sections[id]!.children) visit(child, document.sections[id]!.title)
+    return Object.values(document.blocks).filter(block => block.type === 'component' && block.definitionId === selected)
+      .map(block => ({ id: block.id, page: pages.get(block.id) ?? '' }))
+  }, [document, selected])
+  return <div className="component-properties__content">
+    <PmSearchList label={t.definitions} searchLabel={t.search} items={choices} value={selected} onValueChange={onSelect}
+      resultsLabel={t.results} emptyLabel={t.noDefinitions} loadingLabel={t.loading} disabled={disabled} />
+    <div className="component-properties__actions"><PmMenu label={t.actions} description={references.length ? `${t.copyUnavailable} ${t.inUse}` : t.unavailable}
+      items={[{ id: 'copy', label: t.copy, disabled: true }, { id: 'delete', label: t.remove, disabled: true, danger: true }]} onSelect={() => {}} /></div>
+    <div className="component-properties__references" role="group" aria-label={t.references}>
+      <span>{t.references}</span>
+      {references.map((reference, index) => <div className="component-properties__reference" key={reference.id}>
+        <span>{reference.page} · {index + 1}</span><PmButton small disabled={disabled} onClick={() => onLocate(reference.id)}>{t.locate}</PmButton>
+      </div>)}
+    </div>
+  </div>
+}

package/src/document-editor/ComponentPropertiesDialog.tsx

@@ -0,0 +1,282 @@
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react'
+import { applyDocumentComponentAction, effectiveComponentParameters, isRecord, validateDocumentParameters } from '@lincyaw/kernel'
+import type { CanonicalSource, DocumentComponentAction, DocumentParameterValidation, JsonObject, TeachingDocument } from '@lincyaw/kernel'
+import { PmButton, PmDialog, PmNotice, PmSelect } from '../components.tsx'
+import { useWorkbench, useWorkbenchState } from '../context.tsx'
+import { isAgentChanging } from '../workbench.ts'
+import { COMPONENT_PROPERTY_MESSAGES } from '../component-property-messages.ts'
+import type { ComponentPropertyMessages } from '../component-property-messages.ts'
+import { componentPropertyAction, componentSource, rebaseComponentPropertyDraft, sameComponentSource } from '../component-properties.ts'
+import type { ComponentPropertyBackup, ComponentPropertyBackupRead, ComponentPropertyDraft, ComponentPropertyTarget } from '../component-property-drafts.ts'
+import { PmSchemaForm, schemaFormPropertyNames } from '../schema-form/PmSchemaForm.tsx'
+import { ComponentMaterials, componentDefinitionLabel } from './ComponentMaterials.tsx'
+
+const subscribeEmpty = () => () => {}, snapshotEmpty = () => 0
+const targetKey = (target: ComponentPropertyTarget) => JSON.stringify([target.identity, target.memberId, target.blockId, target.stepId ?? null])
+function fresh(document: TeachingDocument, source: CanonicalSource, target: ComponentPropertyTarget): ComponentPropertyDraft {
+  const block = document.blocks[target.blockId]
+  if (block?.type !== 'component') throw new Error('component-block-missing')
+  const value = effectiveComponentParameters(document, block.id, target.stepId).parameters
+  return { format: 1, id: crypto.randomUUID(), revision: 0, target, source, definitionId: block.definitionId, baseline: value, value,
+    composing: false, reset: false, updatedAt: new Date().toISOString() }
+}
+function message(error: unknown, t: ComponentPropertyMessages): string {
+  const code = error instanceof Error ? error.message : ''
+  if (code.includes('definition-changed')) return t.definitionChanged
+  if (/source|context|version|identity/.test(code)) return t.changed
+  if (/permission|forbidden|review-required/.test(code)) return t.denied
+  if (/draft-limit/.test(code)) return t.limit
+  if (/missing|owner/.test(code)) return t.missing
+  if (/parameter.*invalid|schema|readonly/.test(code)) return t.invalid
+  return t.failed
+}
+interface Applied { commitId?: string, source: CanonicalSource }
+interface Intent { draft?: ComponentPropertyDraft, signature: string, id: string }
+
+/** One source-bound form; the existing draft bank and canonical actor own every retained value. */
+export function ComponentPropertiesDialog({ identity, blockId, stepId, onClose }: {
+  identity: string, blockId: string, stepId?: string, onClose(): void,
+}) {
+  const workbench = useWorkbench(), state = useWorkbenchState(value => value), locale = state.locale, t = COMPONENT_PROPERTY_MESSAGES[locale]
+  const source = state.authoring?.identity === identity ? state.authoring : undefined
+  const document = source?.content, block = document?.blocks[blockId], definition = block?.type === 'component' ? document?.definitions[block.definitionId] : undefined
+  const bank = useMemo(() => workbench.documentPropertyDrafts(identity), [workbench, identity])
+  const revision = useSyncExternalStore(bank?.subscribe ?? subscribeEmpty, bank?.snapshot ?? snapshotEmpty)
+  const [scope, setScope] = useState<'base' | 'step'>('base'), [page, setPage] = useState<'parameters' | 'materials'>('parameters')
+  const target = useMemo<ComponentPropertyTarget>(() => ({ identity, memberId: source?.member?.id ?? '', blockId, ...scope === 'step' && stepId ? { stepId } : {} }), [identity, source?.member?.id, blockId, scope, stepId])
+  const key = targetKey(target)
+  const [ready, setReady] = useState(false), [openAttempt, setOpenAttempt] = useState(0), [initial, setInitial] = useState<{ key: string, draft: ComponentPropertyDraft }>()
+  const [error, setError] = useState<string>(), [busy, setBusy] = useState(false), [validation, setValidation] = useState<DocumentParameterValidation>()
+  const [applied, setApplied] = useState<Applied>(), [backups, setBackups] = useState<ComponentPropertyBackupRead>(), [backupError, setBackupError] = useState(false)
+  const [backupIndex, setBackupIndex] = useState(0), [backupRead, setBackupRead] = useState(0), [backupBusy, setBackupBusy] = useState(false)
+  const [material, setMaterial] = useState<{ definitionId: string, source: CanonicalSource }>()
+  const flight = useRef<AbortController>(), backupFlight = useRef<AbortController>(), intent = useRef<Intent>(), mounted = useRef(true), locateOnClose = useRef(false)
+  const ownedInput = useRef(new Map<string, ComponentPropertyDraft>())
+  const current = useRef({ key, source, target, scope, page, busy })
+  current.current = { key, source, target, scope, page, busy }
+  const close = () => { flight.current?.abort(); backupFlight.current?.abort(); onClose() }
+  useEffect(() => () => backupFlight.current?.abort(), [key])
+  useEffect(() => {
+    mounted.current = true
+    let active = true
+    if (workbench.getState().authoring?.identity !== identity) { setError(t.changed); return () => { active = false; mounted.current = false; flight.current?.abort() } }
+    void workbench.flushPendingEdits().then(() => {
+      if (!active) return
+      const source = workbench.getState().authoring
+      if (source?.identity !== identity || !source.content || !source.version || !source.fingerprint || source.dirty || source.saving || source.composing || source.error || source.restored) { setError(t.changed); return }
+      setReady(true)
+    }, () => { if (active) setError(t.failed) })
+    return () => { active = false; mounted.current = false; flight.current?.abort() }
+  }, [workbench, identity, openAttempt])
+  useEffect(() => {
+    if (!ready || !bank || !document || !source?.version || !source.fingerprint || block?.type !== 'component' || !target.memberId || busy) return
+    if (scope === 'step' && !stepId) return
+    if (initial?.key === key && (bank.get(target) || sameComponentSource(initial.draft.source, componentSource({ content: document, version: source.version, fingerprint: source.fingerprint })))) return
+    try { setInitial({ key, draft: fresh(document, componentSource({ content: document, version: source.version, fingerprint: source.fingerprint }), target) }) }
+    catch (error) { setError(message(error, t)) }
+  }, [ready, bank, key, revision, source?.version, source?.fingerprint, busy, initial])
+  const draft = bank?.get(target) ?? (initial?.key === key ? initial.draft : undefined)
+  const stored = bank?.get(target)
+  const editable = workbench.client.capabilities?.readOnly !== true && Boolean(source?.member?.roles.some(role => role === 'editor' || role === 'owner'))
+  const clean = Boolean(source?.version && source.fingerprint && !source.loading && !source.dirty && !source.saving && !source.composing && !source.restored && !source.recovering && !source.error
+    && editable && !state.isHistoryBusy && !state.isHistoryPreparing && !isAgentChanging(state))
+  const canonical = document && source?.version && source.fingerprint ? componentSource({ content: document, version: source.version, fingerprint: source.fingerprint }) : undefined
+  const stale = Boolean(draft && (!canonical || !sameComponentSource(draft.source, canonical) || block?.type !== 'component' || block.definitionId !== draft.definitionId))
+  const preview = useMemo(() => {
+    if (!document || !draft || stale) return {}
+    try { const action = componentPropertyAction(draft); return action ? { action, effect: applyDocumentComponentAction(document, action).effect } : {} }
+    catch (error) { return { error: message(error, t) } }
+  }, [document, draft, stale, t])
+  const keep = useCallback((value: JsonObject, composing?: boolean, reset = false) => {
+    const latest = current.current
+    if (!bank || !draft || latest.key !== key) return
+    const record = bank.get(target) ?? draft
+    try {
+      const activeComposition = composing ?? record.composing
+      const saved = bank.keep(target, { source: record.source, definitionId: record.definitionId, baseline: record.baseline, value, composing: activeComposition, reset })
+      ownedInput.current.set(key, saved)
+      const source = latest.source, block = source?.content?.blocks[target.blockId]
+      // An unchanged idle field has no pending intent. During a write, even a return
+      // to the old baseline remains later input and must survive its acknowledgement.
+      if (!flight.current && !latest.busy && !activeComposition && !reset && source?.content && source.version && source.fingerprint && block?.type === 'component'
+        && block.definitionId === saved.definitionId && sameComponentSource(saved.source, componentSource({ content: source.content, version: source.version, fingerprint: source.fingerprint }))
+        && !componentPropertyAction(saved)) void bank.clear(saved)
+      setError(undefined)
+    }
+    catch (error) { setError(message(error, t)) }
+  }, [bank, draft, key, target, t])
+  const composition = (composing: boolean) => {
+    const record = bank?.get(target) ?? draft
+    if (!bank || !record) return
+    if (current.current.key === key) { keep(record.value, composing, record.reset); return }
+    // A field leaving its scope may end only the preedit revision it still owns.
+    if (!composing && record.composing && ownedInput.current.get(key) === record && bank.canKeep(target)) {
+      const saved = bank.keep(target, { source: record.source, definitionId: record.definitionId, baseline: record.baseline, value: record.value, reset: record.reset, composing: false })
+      ownedInput.current.set(key, saved)
+    }
+  }
+  useEffect(() => {
+    if (!ready || !bank || !target.memberId) return
+    const controller = new AbortController(), expected = key
+    setBackups(undefined); setBackupError(false); setBackupIndex(0)
+    void bank.read(target, controller.signal).then(value => { if (mounted.current && current.current.key === expected) setBackups(value) }, () => {
+      if (!controller.signal.aborted && mounted.current && current.current.key === expected) setBackupError(true)
+    })
+    return () => controller.abort()
+  }, [ready, bank, key, backupRead])
+  const recheck = () => {
+    if (!draft || !document || !canonical || !bank || !clean) return
+    try {
+      const value = rebaseComponentPropertyDraft(document, draft), baseline = effectiveComponentParameters(document, blockId, target.stepId).parameters
+      bank.keep(target, { source: canonical, definitionId: draft.definitionId, baseline, value, reset: draft.reset, composing: false })
+      setError(undefined); intent.current = undefined
+    } catch (error) { setError(message(error, t)) }
+  }
+  const restore = async (backup: ComponentPropertyBackup) => {
+    if (!bank || !draft || backupBusy || bank.status(target) !== 'available' || draft.composing) return
+    const expected = key, previous = bank.get(target), controller = new AbortController()
+    backupFlight.current = controller
+    setBackupBusy(true)
+    try {
+      const answer = await bank.read(target, controller.signal)
+      if (!mounted.current || current.current.key !== expected) return
+      if (bank.get(target) !== previous || !answer.candidates.some(value => value.key === backup.key && value.token === backup.token)) { setError(t.backupChanged); setBackupRead(value => value + 1); return }
+      const recovered = await bank.recover(backup, previous, controller.signal)
+      if (!mounted.current || current.current.key !== expected) return
+      if (!recovered) setError(t.backupChanged)
+      else setError(undefined)
+      setBackupRead(value => value + 1)
+    } catch { if (!controller.signal.aborted && mounted.current && current.current.key === expected) setBackupError(true) }
+    finally { if (backupFlight.current === controller) backupFlight.current = undefined; if (mounted.current) setBackupBusy(false) }
+  }
+  const discardBackup = async (backup: ComponentPropertyBackup) => {
+    if (!bank || backupBusy) return
+    const expected = key, controller = new AbortController(); backupFlight.current = controller; setBackupBusy(true)
+    try { const done = await bank.discard(backup, controller.signal); if (mounted.current && current.current.key === expected) { if (!done) setError(t.backupChanged); setBackupRead(value => value + 1) } }
+    catch { if (!controller.signal.aborted && mounted.current && current.current.key === expected) setBackupError(true) }
+    finally { if (backupFlight.current === controller) backupFlight.current = undefined; if (mounted.current) setBackupBusy(false) }
+  }
+  const discardLocal = async () => {
+    if (!bank || !stored || busy) return
+    const expected = key
+    if (await bank.clear(stored) && mounted.current && current.current.key === expected) { setInitial(undefined); setError(undefined) }
+  }
+  const submit = async (action: DocumentComponentAction, submitted?: ComponentPropertyDraft) => {
+    if (!canonical || !source?.version || !clean || current.current.busy) return
+    const expected = { identity, version: source.version, fingerprint: source.fingerprint! }, signature = JSON.stringify([canonical, action])
+    if (!intent.current || intent.current.signature !== signature || intent.current.draft !== submitted) intent.current = { signature, draft: submitted, id: crypto.randomUUID() }
+    const captured = intent.current, controller = new AbortController(), submittedKey = key
+    flight.current = controller; current.current.busy = true; setBusy(true); setError(undefined)
+    try {
+      const plan = await workbench.planDocumentComponentAction(action, captured.id, expected, controller.signal)
+      if (submitted && bank?.get(submitted.target) !== submitted) return
+      const result = await workbench.applyDocumentComponentPlan(plan, expected, controller.signal)
+      if (submitted) await bank?.clear(submitted)
+      if (!mounted.current || current.current.key !== submittedKey) return
+      setApplied({ commitId: result.commitId, source: componentSource(result.answer) })
+      if (current.current.page === 'materials' && action.type === 'component.definition.use') setMaterial({ definitionId: action.definitionId, source: componentSource(result.answer) })
+      intent.current = undefined
+    } catch (error) {
+      if (mounted.current && current.current.key === submittedKey) setError(message(error, t))
+    } finally { if (flight.current === controller) flight.current = undefined; current.current.busy = false; if (mounted.current) setBusy(false) }
+  }
+  const undo = async () => {
+    if (!applied?.commitId || !canonical || !sameComponentSource(applied.source, canonical) || !clean || current.current.busy || bank?.has(identity, target.memberId)) return
+    const expected = key; current.current.busy = true; setBusy(true); setError(undefined)
+    try { if (!await workbench.revertRevision(applied.commitId)) { if (mounted.current && current.current.key === expected) setError(t.failed); return }; if (mounted.current && current.current.key === expected) { setApplied(undefined); setInitial(undefined) } }
+    catch (error) { if (mounted.current && current.current.key === expected) setError(message(error, t)) }
+    finally { current.current.busy = false; if (mounted.current) setBusy(false) }
+  }
+  const retrySource = async () => {
+    if (current.current.busy || workbench.getState().authoring?.identity !== identity) return
+    const expected = key; current.current.busy = true; setBusy(true); setError(undefined)
+    try { await workbench.retryDocument(); if (mounted.current && current.current.key === expected && !ready) setOpenAttempt(value => value + 1) }
+    catch (error) { if (mounted.current && current.current.key === expected) setError(message(error, t)) }
+    finally { current.current.busy = false; if (mounted.current) setBusy(false) }
+  }
+  const enterMaterials = () => {
+    if (!canonical || block?.type !== 'component') return
+    setMaterial(before => before ?? { definitionId: block.definitionId, source: canonical }); setPage('materials'); setError(undefined)
+  }
+  const materialAction: DocumentComponentAction | undefined = material && block?.type === 'component' && material.definitionId !== block.definitionId
+    ? { type: 'component.definition.use', blockId, definitionId: material.definitionId } : undefined
+  let materialValid = false
+  if (document && materialAction && document.definitions[materialAction.definitionId]?.implementation.type !== 'module') {
+    try { materialValid = applyDocumentComponentAction(document, materialAction).effect.changed } catch { /* Disabled choice carries the compatibility reason. */ }
+  }
+  const materialStale = Boolean(material && (!canonical || !sameComponentSource(material.source, canonical)))
+  const canUndo = Boolean(applied?.commitId && canonical && sameComponentSource(applied.source, canonical) && clean && !busy && !materialAction && !bank?.has(identity, target.memberId))
+  const canApply = Boolean(!busy && clean && ready && (page === 'materials' ? materialAction && materialValid && !materialStale : preview.action && preview.effect?.changed && !stale && !draft?.composing && validation?.valid))
+  const selectedBackup = backups?.candidates[backupIndex]
+  let inherited: ReturnType<typeof effectiveComponentParameters> | undefined
+  try { if (document && stepId) inherited = effectiveComponentParameters(document, blockId, stepId) } catch { /* The missing source is reported below. */ }
+  const stateSchema = scope === 'step' ? definition?.states.find(item => item.id === inherited?.visual?.state)?.parameterSchema : undefined
+  const baseNames = useMemo(() => definition && draft ? schemaFormPropertyNames(definition.parameterSchema, draft.value) : undefined, [definition, draft?.value])
+  const extraValidation = useCallback((value: Parameters<typeof validateDocumentParameters>[1]) => {
+    return stateSchema !== undefined ? validateDocumentParameters(stateSchema, value) : { available: true, valid: true, issues: [] }
+  }, [stateSchema])
+  const name = definition ? componentDefinitionLabel(definition) : t.properties
+  return <PmDialog open label={page === 'materials' ? t.materials : name} closeLabel={applied ? t.done : t.cancel} onClose={close}
+    onCloseAutoFocus={event => { if (locateOnClose.current) event.preventDefault() }}
+    footer={<>{page === 'materials' && <PmButton onClick={() => setPage('parameters')}>{t.back}</PmButton>}
+      {applied?.commitId && <PmButton disabled={!canUndo} onClick={() => void undo()}>{t.undo}</PmButton>}
+      <PmButton onClick={close}>{applied ? t.done : t.cancel}</PmButton>
+      <PmButton variant="primary" loading={busy} disabled={!canApply} onClick={() => {
+        const action = page === 'materials' ? materialAction : preview.action
+        if (action) void submit(action, page === 'parameters' ? stored : undefined)
+      }}>{page === 'materials' ? t.adopt : t.apply}</PmButton></>}>
+    <div className="component-properties__content">
+      {error && !((stale || materialStale || source?.error) && error === t.changed) && <PmNotice tone="danger">{error}</PmNotice>}
+      {!ready && error && <PmButton disabled={busy || !source} onClick={() => void retrySource()}>{t.retry}</PmButton>}
+      {!ready && !error && <PmNotice>{t.loading}</PmNotice>}
+      {ready && source?.error && <PmNotice tone="warn">{t.changed}<PmButton small disabled={busy} onClick={() => void retrySource()}>{t.retry}</PmButton></PmNotice>}
+      {ready && (!document || block?.type !== 'component' || !definition) && <PmNotice tone="warn">{t.missing}</PmNotice>}
+      {ready && document && definition && block?.type === 'component' && page === 'materials' && <>
+        {materialStale && <PmNotice tone="warn">{t.changed}<PmButton small disabled={!clean || busy} onClick={() => { if (canonical) { setMaterial(value => value && { ...value, source: canonical }); setError(undefined) } }}>{t.recheck}</PmButton></PmNotice>}
+        <ComponentMaterials document={document} blockId={blockId} selected={material?.definitionId ?? block.definitionId} disabled={busy}
+          messages={t} onSelect={definitionId => setMaterial(value => ({ definitionId, source: value?.source ?? canonical! }))}
+          onLocate={id => { locateOnClose.current = true; close(); workbench.revealDocumentComponent(id, identity) }} />
+      </>}
+      {ready && document && definition && draft && page === 'parameters' && <>
+        <PmSelect label={t.scope} value={scope} onChange={event => { setScope(event.currentTarget.value as 'base' | 'step'); setError(undefined); setValidation(undefined) }}>
+          <option value="base">{t.base}</option><option value="step" disabled={!stepId}>{t.step}</option>
+        </PmSelect>
+        {stale && <PmNotice tone="warn">{t.changed}<PmButton small disabled={!clean || busy} onClick={recheck}>{t.recheck}</PmButton></PmNotice>}
+        {stored && (stale || error) && <PmButton small variant="ghost" disabled={busy} onClick={() => void discardLocal()}>{t.discardChanges}</PmButton>}
+        {preview.effect && <span>{t.impact(preview.effect.affected.steps.length)}{scope === 'base' ? ` · ${t.preserved}` : ''}</span>}
+        {preview.error && <PmNotice tone="danger">{preview.error}</PmNotice>}
+        {bank?.status(target) === 'session-only' && <PmNotice tone="warn">{t.storage}</PmNotice>}
+        {!bank?.canKeep(target) && <PmNotice tone="warn">{t.limit}</PmNotice>}
+        {draft.reset && <PmNotice>{t.resetPending}</PmNotice>}
+        <PmSchemaForm key={key} schema={definition.parameterSchema} value={draft.value} locale={locale} label={t.properties} empty={stateSchema !== undefined ? null : t.empty}
+          accessorSchemas={stateSchema !== undefined ? [stateSchema] : undefined}
+          readOnly={!editable || draft.reset} disabled={!bank?.canKeep(target)} extraValidation={scope === 'step' ? extraValidation : undefined}
+          onValidationChange={setValidation} onComposition={composition}
+          onChange={value => { if (isRecord(value)) keep(value as JsonObject) }} />
+        {stateSchema !== undefined && <PmSchemaForm key={`${key}:state`} schema={stateSchema} value={draft.value} locale={locale} label={t.properties} empty={null}
+          accessorSchemas={[definition.parameterSchema]}
+          hideProperties={baseNames?.available ? baseNames.names : undefined} readOnly={!editable || draft.reset} disabled={!bank?.canKeep(target)}
+          onComposition={composition}
+          onChange={value => { if (isRecord(value)) keep(value as JsonObject) }} />}
+        <div className="component-properties__actions">
+          {scope === 'step' && inherited?.ownParameters !== undefined && <PmButton small disabled={busy} onClick={() => {
+            try {
+              if (draft.reset) keep(draft.baseline)
+              else { const reset = applyDocumentComponentAction(document, { type: 'component.step-parameters.reset', blockId, stepId: target.stepId! }).content; keep(effectiveComponentParameters(reset, blockId, target.stepId).parameters, false, true) }
+            } catch (error) { setError(message(error, t)) }
+          }}>{draft.reset ? t.edit : t.reset}</PmButton>}
+          <PmButton variant="ghost" onClick={enterMaterials}>{t.materials}</PmButton>
+        </div>
+        {backupError && <PmNotice tone="warn">{t.storageRead}<PmButton small onClick={() => setBackupRead(value => value + 1)}>{t.retry}</PmButton></PmNotice>}
+        {Boolean(backups?.unreadable) && <PmNotice tone="warn">{t.unreadable}</PmNotice>}
+        {Boolean(backups?.candidates.length) && <div className="component-properties__backups">
+          <PmSelect label={t.backup} value={backupIndex} disabled={backupBusy} onChange={event => setBackupIndex(Number(event.currentTarget.value))}>
+            {backups!.candidates.map((backup, index) => <option value={index} key={backup.key + backup.token}>{new Date(backup.record.updatedAt).toLocaleString(locale)} · {index + 1}</option>)}
+          </PmSelect>
+          <div className="component-properties__actions"><PmButton small disabled={!selectedBackup || backupBusy || busy || draft.composing || !bank?.canKeep(target) || bank?.status(target) !== 'available'} onClick={() => selectedBackup && void restore(selectedBackup)}>{t.recover}</PmButton>
+            <PmButton small disabled={!selectedBackup || backupBusy} onClick={() => selectedBackup && void discardBackup(selectedBackup)}>{t.discard}</PmButton></div>
+        </div>}
+      </>}
+    </div>
+  </PmDialog>
+}

package/src/document-editor/DocumentBlockFallback.tsx

@@ -0,0 +1,31 @@
+import type { DocumentBlock, TeachingDocument } from '@lincyaw/kernel'
+import type { Locale } from '../messages.ts'
+import { DOCUMENT_EDITOR_MESSAGES } from './messages.ts'
+import { BLOCK_PREVIEW_MESSAGES } from './block-preview-messages.ts'
+import { PmNotice } from '../components.tsx'
+import { isDiagram } from './projection.ts'
+import { fallbackText } from './rich-text.ts'
+
+
+const MEDIA_KINDS = ['video', 'audio', 'animation', 'image'] as const
+const authorText = (value: unknown) => typeof value === 'string' && value.trim() ? value.trim() : undefined
+
+/**
+ * A readable source fallback while the independent component snapshot is unavailable. It names the content only by what
+ * the author wrote (a title) or by its kind, never by its code (the component, file or definition names).
+ */
+export function DocumentBlockFallback({ block, document, locale }: { block: DocumentBlock, document: TeachingDocument, locale: Locale }) {
+  const t = DOCUMENT_EDITOR_MESSAGES[locale], p = BLOCK_PREVIEW_MESSAGES[locale]
+  if (isDiagram(block, document)) return <PmNotice>{t.diagram(block.type === 'code' && block.title || '')}</PmNotice>
+  if (block.type === 'code') return <PmNotice>{t.codeReference(block.title ?? block.origin?.anchor ?? block.language)}</PmNotice>
+  if (block.type !== 'component') return null
+  const definition = document.definitions[block.definitionId]
+  const schema = definition?.parameterSchema as { title?: unknown } | undefined
+  const name = authorText(block.parameters.title) ?? authorText(definition?.data?.title) ?? authorText(schema?.title)
+  const media = MEDIA_KINDS.find(kind => kind === block.parameters.kind)
+  const kind = definition?.kind === 'scene' ? p.animation : media ? p[media]
+    : definition?.implementation.type === 'plugin' && definition.implementation.name === 'PmMarkmap' ? p.mindMap : p.content
+  const label = name ? definition?.kind === 'scene' ? t.animation(name) : t.component(name) : kind
+  const description = typeof block.parameters.alt === 'string' ? block.parameters.alt : fallbackText(definition?.data?.fallback)
+  return <PmNotice><div className="pm-document-editor__fallback"><strong>{label}</strong>{description ? <p>{description}</p> : null}</div></PmNotice>
+}