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

package/src/document-editor/DocumentEditor.tsx

@@ -0,0 +1,192 @@
+import { useEffect, useMemo, useRef } from 'react'
+import type { Transaction } from '@tiptap/pm/state'
+import { closeHistory } from '@tiptap/pm/history'
+import { allocateDocumentPage } from '@lincyaw/kernel'
+import type { Member, TeachingDocument } from '@lincyaw/kernel'
+import type { Locale } from '../messages.ts'
+import { BlockNoteSurface } from './BlockNoteSurface.tsx'
+import type { CommentDrafts } from './comment-drafts.ts'
+import { DocumentThreadStore } from './comments.ts'
+import { createDocumentProjection, nativeDocumentToProduct, nativePage, pageId, rememberComponentConfiguration, rememberDocumentStructure } from './projection.ts'
+import type { NativePageCreation } from './projection.ts'
+import { captureRichBaseline } from './rich-text.ts'
+import { captureTableIdentities, seedTableIdentities } from './table-identities.ts'
+import type { DocumentNodeViews, NativeDocumentEditor } from './schema.tsx'
+import { nativeEditingCursor } from './selection.ts'
+import type { NativeDocumentSelection } from './selection.ts'
+
+export interface DocumentEditingPosition {
+  nativeBlockId: string
+  sectionId: string
+  position: number
+}
+export interface DocumentEditorCommands {
+  insertPage(after: string | undefined, title: string): NativePageCreation
+  rememberComponentConfiguration(document: TeachingDocument): void
+}
+
+export interface DocumentEditorProps {
+  identity: string
+  document: TeachingDocument
+  version?: string
+  member?: Member
+  commentDrafts?: CommentDrafts
+  /** The latest actor version, including before the next React render. */
+  getDocumentVersion?(): string | undefined
+  /** Only a clean source snapshot confirms a submitted comment backup. */
+  acknowledged?: boolean
+  getDocumentAcknowledged?(): boolean
+  /** Read sibling field edits before their React render has committed. */
+  getDocument?(): TeachingDocument | undefined
+  /** Ownership of a deferred native focus notification. */
+  getPositionToken?(): string
+  /** Display-only URL resolution; native block URLs keep their canonical source locations. */
+  resolveAssetURL?(location: string): Promise<string>
+  uploadImage?(file: File, signal: AbortSignal): Promise<string>
+  reset?: number
+  locale: Locale
+  readOnly?: boolean
+  nodeViews?: DocumentNodeViews
+  onChange(document: TeachingDocument): void
+  onSelection?(selection: NativeDocumentSelection | undefined): void
+  onEditingPosition?(position: DocumentEditingPosition, editor: NativeDocumentEditor): void
+  onReady?(editor: NativeDocumentEditor | undefined, commands?: DocumentEditorCommands): void
+  onComposition?(composing: boolean): void
+  onSectionLink?(sectionId: string): boolean
+  onError?(error: Error): void
+  commentsPortal?: HTMLElement | null
+  onCommentDraftRestore?(): void
+}
+
+/** A source version reset replaces the editor; its own save receipts never replace it. */
+export function DocumentEditor(props: DocumentEditorProps) {
+  const projection = useMemo(() => createDocumentProjection(props.document), [props.identity, props.reset])
+  useEffect(() => rememberComponentConfiguration(projection, props.document), [projection, props.version])
+  const comments = useMemo(() => new DocumentThreadStore(props.document, props.member, props.version, props.identity, props.commentDrafts), [props.identity, props.reset])
+  useEffect(() => {
+    const latest = current.current, document = latest.getDocument ? latest.getDocument() : latest.document
+    const version = latest.getDocumentVersion ? latest.getDocumentVersion() : latest.version
+    if (document && version !== undefined) {
+      comments.drafts?.synchronize(document, version, latest.getDocumentAcknowledged ? latest.getDocumentAcknowledged() : latest.acknowledged ?? false)
+      comments.drafts?.start()
+    }
+    return () => comments.close()
+  }, [comments])
+  const current = useRef(props), editor = useRef<NativeDocumentEditor>(), unsubscribe = useRef<() => void>()
+  const projectedDocument = useRef<NativeDocumentEditor['prosemirrorState']['doc']>()
+  const pendingTransaction = useRef<Transaction>()
+  const focusFrame = useRef<number>()
+  const binding = useRef(projection)
+  const active = useRef(projection)
+  active.current = projection
+  current.current = props
+  const cancelFocus = () => { if (focusFrame.current !== undefined) cancelAnimationFrame(focusFrame.current); focusFrame.current = undefined }
+  const reportPosition = () => {
+    const value = editor.current
+    if (!value || current.current.readOnly || !current.current.onEditingPosition || binding.current !== projection || active.current !== projection || value.prosemirrorView.isDestroyed || value.prosemirrorState.doc !== projectedDocument.current) return
+    try {
+      const cursor = nativeEditingCursor(value)
+      if (!cursor) return
+      const owner = projection.owners.get(cursor.nativeBlockId)
+      const sectionId = projection.pages.get(cursor.nativeBlockId) ?? (owner ? projection.blockSections.get(owner) : undefined)
+      const latest = current.current.getDocument ? current.current.getDocument() : current.current.document
+      if (sectionId && latest?.sections[sectionId]) current.current.onEditingPosition({ ...cursor, sectionId }, value)
+    } catch (error) { current.current.onError?.(error instanceof Error ? error : new Error(String(error))) }
+  }
+  const syncComments = () => {
+    const value = editor.current, latest = current.current.getDocument ? current.current.getDocument() : current.current.document
+    const version = current.current.getDocumentVersion ? current.current.getDocumentVersion() : current.current.version
+    if (!value || !latest || binding.current !== projection || active.current !== projection || value.prosemirrorView.isDestroyed) return
+    const transaction = pendingTransaction.current
+    comments.synchronize(latest, version, value, transaction?.doc === value.prosemirrorState.doc && transaction.before === projectedDocument.current ? transaction : undefined, current.current.getDocumentAcknowledged ? current.current.getDocumentAcknowledged() : current.current.acknowledged ?? false)
+    if (version !== undefined) comments.drafts?.start()
+    projectedDocument.current = value.prosemirrorState.doc
+  }
+  comments.beforeAction = () => { if (current.current.getDocumentVersion && current.current.getDocumentVersion() === undefined) throw new Error('document-context-changed'); syncComments() }
+  useEffect(syncComments, [props.version, props.document.comments, props.acknowledged, comments])
+  const emit = () => {
+    if (!editor.current || binding.current !== projection || comments.synchronizing) return
+    try {
+      captureTableIdentities(editor.current, projection)
+      if (projection !== active.current) return
+      const latest = current.current.getDocument ? current.current.getDocument() : current.current.document
+      if (!latest || current.current.getDocumentVersion && current.current.getDocumentVersion() === undefined) return
+      syncComments()
+      const document = nativeDocumentToProduct(editor.current.document, projection, latest)
+      const threads = comments.snapshot(editor.current)
+      if (Object.keys(threads).length) document.comments = threads
+      else delete document.comments
+      current.current.onChange(document)
+      projectedDocument.current = editor.current.prosemirrorState.doc
+      pendingTransaction.current = undefined
+      cancelFocus()
+      reportPosition()
+    } catch (error) { current.current.onError?.(error instanceof Error ? error : new Error(String(error))) }
+  }
+  return <BlockNoteSurface identity={props.identity} reset={props.reset} initialContent={projection.content} locale={props.locale} contentLang={props.document.metadata.lang || 'zh-CN'} readOnly={props.readOnly}
+    resolveAssetURL={props.resolveAssetURL} uploadImage={props.uploadImage}
+    comments={comments} commentsPortal={props.commentsPortal} onCommentDraftRestore={() => current.current.onCommentDraftRestore?.()} nodeViews={props.nodeViews} onComposition={props.onComposition} onSelection={props.onSelection} onSectionLink={sectionId => {
+      if (!current.current.onSectionLink?.(sectionId)) return false
+      // The click placed the caret in the link; it follows the reader to the page they asked for.
+      const value = editor.current
+      if (value && !value.prosemirrorView.isDestroyed && value.getBlock(pageId(sectionId))) value.setTextCursorPosition(pageId(sectionId), 'start')
+      return true
+    }}
+    onChange={emit} onReady={value => {
+      if (projection !== active.current) return
+      unsubscribe.current?.(); unsubscribe.current = undefined
+      cancelFocus()
+      editor.current = undefined
+      projectedDocument.current = undefined
+      pendingTransaction.current = undefined
+      if (value) {
+        seedTableIdentities(value, projection)
+        captureTableIdentities(value, projection)
+        captureRichBaseline(value.document, projection)
+        rememberDocumentStructure(value.document, projection)
+        comments.restoreAnchors(value)
+        binding.current = projection
+        editor.current = value
+        projectedDocument.current = value.prosemirrorState.doc
+        const stopBefore = value.onBeforeChange(({ tr }) => { if (!comments.synchronizing && tr.docChanged) pendingTransaction.current = tr })
+        const stopComments = comments.subscribe(emit)
+        const stopSelection = value.onSelectionChange(() => { cancelFocus(); reportPosition() })
+        const stopFocus = value.onFocusChange((_, { focused }) => {
+          cancelFocus()
+          if (!focused) return
+          const token = current.current.getPositionToken?.()
+          focusFrame.current = requestAnimationFrame(() => {
+            focusFrame.current = undefined
+            if (token === current.current.getPositionToken?.()) reportPosition()
+          })
+        })
+        unsubscribe.current = () => { stopBefore(); stopComments(); stopSelection(); stopFocus(); cancelFocus() }
+      }
+      const commands: DocumentEditorCommands | undefined = value ? { rememberComponentConfiguration: document => {
+        if (editor.current === value && active.current === projection && binding.current === projection && !value.prosemirrorView.isDestroyed) rememberComponentConfiguration(projection, document)
+      }, insertPage: (after, title) => {
+        if (current.current.readOnly || editor.current !== value || active.current !== projection || binding.current !== projection || value.prosemirrorView.isDestroyed) throw new Error('page-context-changed')
+        const blocks = value.document, index = after ? blocks.findIndex(block => block.type === 'presmiumPage' && block.props.sectionId === after) : blocks.length - 1
+        if (index < 0) throw new Error('page-boundary')
+        const next = after ? blocks.slice(index + 1).find(block => block.type === 'presmiumPage') : undefined
+        const latest = current.current.getDocument ? current.current.getDocument() : current.current.document
+        if (!latest) throw new Error('page-context-changed')
+        const creation = allocateDocumentPage(latest, () => crypto.randomUUID())
+        projection.createdPages.set(creation.sectionId, creation)
+        try {
+          value.transact(transaction => {
+            closeHistory(transaction)
+            value.insertBlocks([nativePage(creation.sectionId, title), { id: creation.nodeId, type: 'paragraph', content: [] }], next ?? blocks.at(-1)!, next ? 'before' : 'after')
+          })
+          // The first keystroke belongs to its own native history event.
+          value.transact(transaction => closeHistory(transaction))
+          return creation
+        } catch (error) {
+          if (!value.getBlock(`page:${creation.sectionId}`)) projection.createdPages.delete(creation.sectionId)
+          throw error
+        }
+      } } : undefined
+      current.current.onReady?.(value, commands)
+      if (value) reportPosition()
+    }} getPositionToken={() => current.current.getPositionToken?.()} />
+}

package/src/document-editor/DocumentStepNarration.tsx

@@ -0,0 +1,93 @@
+import { useRef, useState } from 'react'
+import type { NarrationNode, TeachingDocument } from '@lincyaw/kernel'
+import { PmIconButton } from '../components.tsx'
+import { useWorkbench, useWorkbenchState } from '../context.tsx'
+import { isAgentChanging } from '../workbench.ts'
+import { NarrationEditor } from './NarrationEditor.tsx'
+import { DOCUMENT_EDITOR_MESSAGES } from './messages.ts'
+import { narrationFieldFocus } from './narration.ts'
+import type { NativeNarrationEditor } from './narration-schema.tsx'
+import { StepProductionEditor } from '../StepProductionEditor.tsx'
+
+/** Content ownership determines the page, even when the author is reading another page. */
+export function documentBlockSection(document: TeachingDocument, blockId: string): string | undefined {
+  const contains = (id: string): boolean => {
+    if (id === blockId) return true
+    const block = document.blocks[id]
+    return (block?.type === 'container' || block?.type === 'component') && (block.children ?? []).some(contains)
+  }
+  return document.sectionOrder.find(id => document.sections[id]?.children.some(contains))
+}
+
+export function narrationDisplay(content: readonly NarrationNode[]): string {
+  return content.map(node => node.type === 'text' ? node.text : node.type === 'pronunciation' ? node.display : '').join('')
+}
+
+function NarrationField({ identity, reset, blockId, stepId, slot, narrationId, content, readOnly, advanced, onPause }: {
+  identity: string, reset: number, blockId?: string, stepId: string, slot: number, narrationId?: string, content: NarrationNode[], readOnly: boolean, advanced: boolean, onPause(): void,
+}) {
+  const workbench = useWorkbench(), locale = useWorkbenchState(state => state.locale)
+  // Reserving an identity does not create an entity. The first actual input commits it.
+  const [reservedId] = useState(() => {
+    const pending = workbench.pendingDocumentField(blockId, identity)
+    return narrationId ?? (pending?.stepId === stepId ? pending.narrationId : undefined) ?? crypto.randomUUID()
+  })
+  const id = narrationId ?? reservedId
+  const target = () => narrationId ?? workbench.getDocument(identity)?.steps[stepId]?.narrationIds[slot] ?? id
+  const registration = useRef<() => void>()
+  const fieldEditor = useRef<NativeNarrationEditor>()
+  const owner = `narration:${identity}:${reset}:${JSON.stringify(blockId ?? null)}:${stepId}:${slot}:${id}`
+  return <NarrationEditor identity={identity} reset={reset} narrationId={id} content={content} locale={locale} readOnly={readOnly} advanced={advanced}
+    getContent={() => { const document = workbench.getDocument(identity); return document ? document.narrations[target()]?.content ?? [] : undefined }}
+    onReady={editor => {
+      registration.current?.()
+      fieldEditor.current = editor
+      registration.current = editor ? workbench.registerDocumentField({ identity, reset, blockId, stepId, narrationId: id, slot, focus: narrationFieldFocus(editor), editor }) : undefined
+    }}
+    onFocus={() => { workbench.documentInteraction(); if (fieldEditor.current) workbench.activateDocumentHistory(fieldEditor.current); onPause() }} onChange={value => workbench.setDocumentNarration(stepId, target(), value, identity)}
+    onComposition={composing => workbench.documentComposition(composing, owner, identity)}
+    onError={error => workbench.documentError(error)} />
+}
+
+/** Captions are a view of the current step's canonical narration, including unsaved input. */
+export function DocumentStepNarration({ blockId, sectionId, stepId, expanded, advanced = false, showLabel = true, panelId, onPause }: {
+  blockId?: string, sectionId: string, stepId: string, expanded: boolean, advanced?: boolean, showLabel?: boolean, panelId: string, onPause(): void,
+}) {
+  const workbench = useWorkbench(), source = useWorkbenchState(state => state.authoring)
+  const locale = useWorkbenchState(state => state.locale), t = DOCUMENT_EDITOR_MESSAGES[locale]
+  const readOnly = useWorkbenchState(state => workbench.client.capabilities?.readOnly === true || Boolean(state.authoring?.loading) || isAgentChanging(state))
+  const timingStorageFailure = useWorkbenchState(state => state.documentTimingDraftStorageFailure)
+  if (workbench.client.capabilities?.narration === false) return null
+  const document = source?.content, section = document?.sections[sectionId], step = document?.steps[stepId]
+  if (!source?.identity || !document || !section || !step) return null
+  const index = section.stepOrder.indexOf(stepId), ids = step.narrationIds
+  const label = t.narrationStep(index + 1, section.stepOrder.length, step.title ?? ''), fieldLabel = advanced ? t.stepNarration : t.stepCaptions
+  const text = ids.map(id => narrationDisplay(document.narrations[id]?.content ?? [])).filter(Boolean).join('\n')
+  const navigate = (offset: number) => {
+    const id = section.stepOrder[index + offset]
+    if (id) { onPause(); workbench.selectDocumentStep(sectionId, id) }
+  }
+  return <section className="pm-ui-block-preview__narration" aria-label={fieldLabel} data-step-narration={stepId}>
+    <header className="pm-ui-block-preview__narration-header">
+      <span className="pm-ui-block-preview__step-label">{label}</span>
+      <span className="pm-ui-block-preview__actions">
+        <PmIconButton small icon="chevron-left" label={t.previousStep} disabled={index <= 0} onClick={() => navigate(-1)} />
+        <PmIconButton small icon="chevron-right" label={t.nextStep} disabled={index >= section.stepOrder.length - 1} onClick={() => navigate(1)} />
+      </span>
+    </header>
+    {!expanded && text && <p className="pm-ui-block-preview__caption" data-step-caption={stepId}>{text}</p>}
+    {expanded && <div id={panelId} className="pm-ui-block-preview__narration-fields">
+      {showLabel && <span className="pm-ui-block-preview__step-label">{fieldLabel}</span>}
+      {(ids.length ? ids : [undefined]).map((id, slot) => <NarrationField key={`${source.identity}:${source.reset}:${stepId}:${slot}`}
+        identity={source.identity!} reset={source.reset} blockId={blockId} stepId={stepId} slot={slot} narrationId={id}
+        content={id ? document.narrations[id]?.content ?? [] : []} readOnly={readOnly} advanced={advanced} onPause={onPause} />)}
+      <StepProductionEditor key={`${source.identity}:${source.reset}:${stepId}`} document={document} stepId={stepId} locale={locale} readOnly={readOnly} advanced={advanced}
+        onPause={onPause} onInteraction={() => workbench.documentInteraction()}
+        onChange={patch => workbench.setDocumentStepProduction(stepId, patch, source.identity)}
+        drafts={{ minimumHoldMs: workbench.documentTimingDraft(stepId, 'minimumHoldMs', source.identity, source.reset), trailingPauseMs: workbench.documentTimingDraft(stepId, 'trailingPauseMs', source.identity, source.reset) }}
+        draftStorageFailure={timingStorageFailure}
+        onDraft={(key, draft) => workbench.setDocumentTimingDraft(stepId, key, draft, source.identity!, source.reset)}
+        onComposition={(key, composing) => workbench.documentComposition(composing, `production:${source.identity}:${source.reset}:${blockId}:${stepId}:${key}`, source.identity)} />
+    </div>}
+  </section>
+}

package/src/document-editor/NarrationEditor.tsx

@@ -0,0 +1,110 @@
+import { useEffect, useMemo, useRef, useState } from 'react'
+import { createRoot } from 'react-dom/client'
+import type { NarrationNode } from '@lincyaw/kernel'
+import { blockNoteDictionary } from './blocknote-messages.ts'
+import { BlockNoteView } from '@blocknote/mantine'
+import { useCreateBlockNote } from '@blocknote/react'
+import { PmButton, PmDialog, PmInput } from '../components.tsx'
+import type { Locale } from '../messages.ts'
+import { DOCUMENT_EDITOR_THEME } from './BlockNoteSurface.tsx'
+import { narrationToNative, nativeToNarration } from './narration.ts'
+import { NARRATION_CONTEXT, NARRATION_MESSAGES, narrationExtensions, narrationSchema } from './narration-schema.tsx'
+import type { NativeNarrationEditor } from './narration-schema.tsx'
+
+export interface NarrationEditorProps {
+  identity: string
+  narrationId: string
+  content: NarrationNode[]
+  getContent?(): NarrationNode[] | undefined
+  locale: Locale
+  reset?: number
+  readOnly?: boolean
+  advanced?: boolean
+  onChange(content: NarrationNode[]): void
+  onComposition?(composing: boolean): void
+  onFocus?(): void
+  onError?(error: Error): void
+  onReady?(editor: NativeNarrationEditor | undefined): void
+}
+
+/** A native field can live inside an opaque body node without sharing its DOM event root. */
+export function NarrationEditor(props: NarrationEditorProps) {
+  const mount = useRef<HTMLDivElement>(null), root = useRef<ReturnType<typeof createRoot>>(), current = useRef(props)
+  current.current = props
+  useEffect(() => {
+    const host = mount.current!, shadow = host.shadowRoot ?? host.attachShadow({ mode: 'open' })
+    // Public stylesheet entries are shared; typography and tokens keep their single source.
+    const styles = [...document.head.querySelectorAll('link[rel="stylesheet"], style')].map(node => node.cloneNode(true))
+    const element = document.createElement('div')
+    shadow.append(...styles, element)
+    const field = createRoot(element)
+    root.current = field
+    const stop = (event: Event) => event.stopPropagation()
+    const events = ['keydown', 'keyup', 'keypress', 'beforeinput', 'input', 'compositionstart', 'compositionupdate', 'compositionend', 'mousedown', 'mouseup', 'pointerdown', 'pointerup', 'click', 'dblclick', 'contextmenu', 'focusin', 'focusout', 'copy', 'cut', 'paste', 'dragstart', 'dragover', 'drop']
+    for (const event of events) element.addEventListener(event, stop)
+    field.render(<NarrationSurface {...current.current} />)
+    return () => {
+      root.current = undefined
+      for (const event of events) element.removeEventListener(event, stop)
+      queueMicrotask(() => { field.unmount(); element.remove(); styles.forEach(node => node.parentNode?.removeChild(node)) })
+    }
+  }, [])
+  useEffect(() => { root.current?.render(<NarrationSurface {...props} />) })
+  return <div ref={mount} contentEditable={false} data-narration-editor={props.narrationId} />
+}
+
+function NarrationSurface(props: NarrationEditorProps) {
+  const current = useRef(props), pending = useRef<string[]>([])
+  current.current = props
+  const canonical = props.getContent?.() ?? props.content
+  const incoming = JSON.stringify(canonical), sourceKey = JSON.stringify([props.identity, props.narrationId, props.reset])
+  const version = useRef({ key: sourceKey, incoming, epoch: 0 })
+  if (version.current.key !== sourceKey) {
+    version.current.epoch++; version.current.key = sourceKey; pending.current = []
+  } else if (version.current.incoming !== incoming) {
+    const receipt = pending.current.lastIndexOf(incoming)
+    if (receipt >= 0) pending.current.splice(0, receipt + 1)
+    else { version.current.epoch++; pending.current = [] }
+  }
+  version.current.incoming = incoming
+  const instance = useMemo(() => ({ content: structuredClone(canonical), emitted: incoming }), [sourceKey, version.current.epoch])
+  const active = useRef(instance); active.current = instance
+  const t = NARRATION_MESSAGES[props.locale]
+  const editor = useCreateBlockNote({ schema: narrationSchema, initialContent: narrationToNative(props.narrationId, instance.content),
+    trailingBlock: false,
+    dictionary: { ...blockNoteDictionary(props.locale), placeholders: { ...blockNoteDictionary(props.locale).placeholders, default: props.advanced === false ? t.emptyCaptions : t.empty } },
+    extensions: narrationExtensions, domAttributes: { editor: { 'aria-label': props.advanced === false ? t.captions : t.field } },
+  }, [instance, props.advanced])
+  const baseline = useMemo(() => JSON.stringify(editor.document), [editor])
+  const [open, setOpen] = useState(false), [display, setDisplay] = useState(''), [spoken, setSpoken] = useState('')
+  useEffect(() => {
+    current.current.onReady?.(editor)
+    return () => { props.onComposition?.(false); props.onReady?.(undefined) }
+  }, [editor])
+  const change = () => {
+    if (active.current !== instance) return
+    if (current.current.getContent && current.current.getContent() === undefined) return
+    try {
+      const content = JSON.stringify(editor.document) === baseline ? structuredClone(instance.content) : nativeToNarration(editor.document)
+      const serialized = JSON.stringify(content)
+      if (serialized === instance.emitted) return
+      instance.emitted = serialized; pending.current.push(serialized)
+      current.current.onChange(content)
+    } catch (error) { current.current.onError?.(error instanceof Error ? error : new Error(String(error))) }
+  }
+  return <NARRATION_CONTEXT.Provider value={{ locale: props.locale, readOnly: props.readOnly, advanced: props.advanced }}>
+    <div className="pm-ui-narration-editor pm-ui-block-editor pm-ui" onFocus={() => current.current.onFocus?.()}
+      onCompositionStart={() => current.current.onComposition?.(true)}
+      onCompositionEnd={() => queueMicrotask(() => { if (active.current === instance) current.current.onComposition?.(false) })}>
+      <BlockNoteView editor={editor} editable={!props.readOnly} theme={DOCUMENT_EDITOR_THEME} formattingToolbar={false} sideMenu={false} slashMenu={false} linkToolbar={false} comments={false} onChange={change} />
+      {props.advanced !== false && <div className="pm-ui-narration-editor__actions"><PmButton small variant="ghost" disabled={props.readOnly} onClick={() => { setDisplay(editor.getSelectedText()); setSpoken(''); setOpen(true) }}>{t.pronunciation}</PmButton></div>}
+      <PmDialog open={open} label={t.pronunciation} closeLabel={t.cancel} onClose={() => setOpen(false)} actions={<>
+        <PmButton small onClick={() => setOpen(false)}>{t.cancel}</PmButton>
+        <PmButton small variant="primary" disabled={!display} onClick={() => { editor.insertInlineContent([{ type: 'narrationAtom', props: { kind: 'pronunciation', display, spoken, cueId: '', payload: '' } }], { updateSelection: true }); setOpen(false); editor.focus() }}>{t.done}</PmButton>
+      </>}>
+        <PmInput label={t.display} value={display} onChange={event => setDisplay(event.target.value)} />
+        <PmInput label={t.spoken} value={spoken} onChange={event => setSpoken(event.target.value)} />
+      </PmDialog>
+    </div>
+  </NARRATION_CONTEXT.Provider>
+}

package/src/document-editor/NewCommentDrafts.tsx

@@ -0,0 +1,224 @@
+import { createContext, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react'
+import type { ReactNode } from 'react'
+import { CommentEditorSubmitExtension, CommentsExtension } from '@blocknote/core/comments'
+import { components } from '@blocknote/mantine'
+import { ComponentsContext, FloatingComposer, PositionPopover, useBlockNoteEditor, useComponentsContext, useCreateBlockNote, useDictionary, useEditorState, useExtension, useExtensionState } from '@blocknote/react'
+import type { ComponentProps } from '@blocknote/react'
+import type { BlockNoteEditor } from '@blocknote/core'
+import { TextSelection } from '@tiptap/pm/state'
+import { COMMENT_EDITOR_CONTEXT, DraftChoices } from './DocumentComments.tsx'
+import { isNewCommentDraft, sameCommentDraftTarget } from './comment-drafts.ts'
+import { enterSubmits } from './comments.ts'
+import type { CommentDraftCandidate, CommentDraftRecord, CommentDraftReference, NewCommentDraftTarget } from './comment-drafts.ts'
+import { createRichProjection, nativeRichTextToProduct, productRichTextToNative } from './rich-text.ts'
+import type { DocumentEditorBlock, NativeDocumentEditor } from './schema.tsx'
+import { PmNotice } from '../components.tsx'
+import { DOCUMENT_EDITOR_MESSAGES } from './messages.ts'
+import { commentFloating } from './popover.tsx'
+
+type CommentEditor = BlockNoteEditor<any, any, any>
+interface ComposerBinding {
+  target: NewCommentDraftTarget
+  editor: CommentEditor
+  record?: CommentDraftRecord
+  origin?: CommentDraftReference
+  input: number
+  composing: boolean
+  active: boolean
+}
+interface PreparedDraft { record: CommentDraftRecord, origin: CommentDraftReference, doc: NativeDocumentEditor['prosemirrorState']['doc'], selection: NativeDocumentEditor['prosemirrorState']['selection'], version: string }
+interface NewDraftOwner {
+  editor: NativeDocumentEditor
+  latest: { current: ComposerBinding | undefined }
+  prepared: { current: PreparedDraft | undefined }
+  restore(candidate: CommentDraftCandidate, current?: () => boolean): Promise<void>
+  failure?: boolean
+}
+const NEW_DRAFT_OWNER = createContext<NewDraftOwner | undefined>(undefined)
+const emptySubscribe = () => () => {}
+const emptyState = { candidates: [], pending: false, failed: false, reading: false } as const
+
+/** One owner connects the public composer instance to a source-bound creation intent. */
+export function NewCommentDraftProvider({ children }: { children?: ReactNode }) {
+  const context = useContext(COMMENT_EDITOR_CONTEXT), editor = useBlockNoteEditor() as NativeDocumentEditor, comments = useExtension(CommentsExtension)
+  const latest = useRef<ComposerBinding>(), prepared = useRef<PreparedDraft>(), active = useRef(true), operation = useRef(0)
+  const [failure, setFailure] = useState(false)
+  useEffect(() => { active.current = true; return () => { active.current = false; ++operation.current; prepared.current = undefined; latest.current = undefined } }, [editor])
+  const restore = async (candidate: CommentDraftCandidate, current = () => true) => {
+    const store = context?.store, drafts = store?.drafts, target = candidate.target
+    if (!store || !drafts || !isNewCommentDraft(target) || candidate.storage !== 'durable' || editor.prosemirrorView.isDestroyed || editor.prosemirrorView.composing) return
+    const binding = latest.current
+    if (binding?.record && !drafts.owns(binding.record)) binding.record = undefined
+    const request = ++operation.current, input = binding?.input, record = binding?.record
+    try {
+      store.beforeAction?.()
+      if (!store.auth.canCreateThread() || store.draftTargetState(target) !== 'current' || !store.newDraftPositions(target, editor)) { setFailure(true); return }
+      const version = store.version, native = editor.prosemirrorState, extensionState = comments.store.state, position = context.getPositionToken?.()
+      if (!version || binding?.composing || binding?.editor.prosemirrorView.composing) return
+      const owns = () => active.current && current() && request === operation.current && !editor.prosemirrorView.isDestroyed && !editor.prosemirrorView.composing && store.version === version
+        && context.getPositionToken?.() === position
+        && editor.prosemirrorState.doc === native.doc && editor.prosemirrorState.selection === native.selection && comments.store.state === extensionState
+        && (!binding || latest.current === binding && binding.input === input && binding.record === record && !binding.composing)
+      if (record && !await drafts.confirm(record) || !owns()) return
+      const nextTarget = { ...target, intentId: crypto.randomUUID() }, next = await drafts.recover(candidate, nextTarget, version)
+      store.beforeAction?.()
+      if (!next || !owns()) return
+      const positions = store.newDraftPositions(nextTarget, editor)
+      if (!positions) { setFailure(true); return }
+      comments.stopPendingComment()
+      // ProseMirror scrolls to a selection only while the DOM selection is in the editor, and the pressed button is gone.
+      editor.focus()
+      editor.transact(transaction => transaction.setSelection(TextSelection.create(transaction.doc, positions.from, positions.to)).scrollIntoView())
+      // The public controller creates the actual editor; this is only its strictly committed handoff.
+      prepared.current = { record: next, origin: candidate, doc: editor.prosemirrorState.doc, selection: editor.prosemirrorState.selection, version }
+      comments.startPendingComment()
+      prepared.current.selection = editor.prosemirrorState.selection
+      setFailure(false)
+      context.onDraftRestore?.()
+    } catch { if (active.current && request === operation.current) setFailure(true) }
+  }
+  return <NEW_DRAFT_OWNER.Provider value={{ editor, latest, prepared, restore, failure }}>{children}</NEW_DRAFT_OWNER.Provider>
+}
+
+/**
+ * BlockNote's FloatingComposerController, assembled from the same public parts but without its modal focus manager.
+ * That manager marks everything outside the form with `aria-hidden`, and when the document holds a live region (a
+ * block's notice) it walks into the document and marks the blocks themselves: ProseMirror reads those attributes as
+ * an edit and redraws every block, which collapses the canvas (it scrolls away) and takes the focus from the form.
+ * The comment editor focuses itself (`autoFocus`, without scrolling), as in a thread's reply form.
+ * Closing hides the native form; permanent discard is an exact backup action.
+ */
+export function DocumentNewCommentController() {
+  const owner = useContext(NEW_DRAFT_OWNER), context = useContext(COMMENT_EDITOR_CONTEXT), comments = useExtension(CommentsExtension)
+  const editor = useBlockNoteEditor(), dict = useDictionary()
+  const pendingComment = useExtensionState(CommentsExtension, { editor, selector: state => state.pendingComment })
+  const newCommentEditor = useCreateBlockNote({
+    trailingBlock: false,
+    dictionary: { ...dict, placeholders: { ...dict.placeholders, emptyDocument: dict.placeholders.new_comment } },
+    schema: comments.commentEditorSchema,
+    extensions: [CommentEditorSubmitExtension({ submitOnEnter: comments.submitOnEnter, onSubmit: async commentEditor => {
+      await comments.createThread({ initialComment: { body: commentEditor.document } })
+      comments.stopPendingComment()
+      editor.transact(transaction => { transaction.setSelection(TextSelection.create(transaction.doc, transaction.selection.to)) })
+      editor.focus()
+    } })],
+  }, [pendingComment])
+  const position = useEditorState({ editor, selector: ({ editor }) => pendingComment ? { from: editor.prosemirrorState.selection.from, to: editor.prosemirrorState.selection.to } : undefined })
+  const floating = useMemo(() => commentFloating(), [])
+  return <PositionPopover position={position} focusManagerProps={{ disabled: true }} elementProps={{ style: { zIndex: COMPOSER_LAYER } }}
+    useFloatingOptions={{ placement: 'bottom', ...floating, open: pendingComment, onOpenChange(open) {
+      if (open || !owner || owner.latest.current?.composing || owner.latest.current?.editor.prosemirrorView.composing) return
+      try { context?.store.beforeAction?.() } catch { return }
+      comments.stopPendingComment()
+      if (!owner.editor.prosemirrorView.isDestroyed) owner.editor.focus()
+    } }}>
+    <DocumentNewCommentComposer newCommentEditor={newCommentEditor} />
+  </PositionPopover>
+}
+// BlockNote's layer for the new-comment form, above its toolbars and thread cards.
+const COMPOSER_LAYER = 60
+
+function DocumentNewCommentComposer({ newCommentEditor }: { newCommentEditor: CommentEditor }) {
+  const owner = useContext(NEW_DRAFT_OWNER), context = useContext(COMMENT_EDITOR_CONTEXT), nativeComponents = useComponentsContext()!
+  const [binding, setBinding] = useState<ComposerBinding>(), [, render] = useState(0)
+  useLayoutEffect(() => {
+    if (!owner || !context) return
+    try {
+      context.store.beforeAction?.()
+      const restored = owner.prepared.current, prepared = restored && restored.version === context.store.version
+        && restored.doc === owner.editor.prosemirrorState.doc && restored.selection === owner.editor.prosemirrorState.selection && newCommentEditor.isEmpty
+        && isNewCommentDraft(restored.record.target) && context.store.newDraftPositions(restored.record.target, owner.editor) ? restored : undefined
+      const target = prepared && isNewCommentDraft(prepared.record.target) ? prepared.record.target : context.store.newDraftTarget(owner.editor)
+      const value: ComposerBinding = { target, editor: newCommentEditor, record: prepared?.record, origin: prepared?.origin, input: 0, composing: false, active: true }
+      if (prepared) owner.prepared.current = undefined
+      owner.latest.current = value; setBinding(value)
+      return () => { value.active = false }
+    } catch { /* The unchanged native form remains available when no authoritative target can be confirmed. */ }
+  }, [newCommentEditor, context?.store, owner?.editor])
+  const value = useMemo(() => ({ ...nativeComponents, Comments: { ...nativeComponents.Comments, Editor: NewCommentEditor } }), [nativeComponents])
+  return <NEW_COMPOSER_BINDING.Provider value={{ binding, ready: () => render(value => value + 1) }}><ComponentsContext.Provider value={value}>
+    <FloatingComposer newCommentEditor={newCommentEditor} />
+  </ComponentsContext.Provider></NEW_COMPOSER_BINDING.Provider>
+}
+const NEW_COMPOSER_BINDING = createContext<{ binding?: ComposerBinding, ready(): void } | undefined>(undefined)
+
+function NewCommentEditor(props: ComponentProps['Comments']['Editor']) {
+  const context = useContext(COMMENT_EDITOR_CONTEXT), owner = useContext(NEW_DRAFT_OWNER), composer = useContext(NEW_COMPOSER_BINDING), binding = composer?.binding
+  const rich = useMemo(() => createRichProjection(), [props.editor]), suppress = useRef(false), submitting = useRef(false)
+  const [failure, setFailure] = useState(false)
+  const drafts = context?.store.drafts, state = useSyncExternalStore(drafts?.subscribe ?? emptySubscribe, drafts?.snapshot ?? (() => emptyState))
+  useLayoutEffect(() => {
+    if (!binding || !drafts || !context || !owner) return
+    if (binding.record && props.editor.isEmpty) {
+      props.editor.replaceBlocks(props.editor.document, productRichTextToNative(binding.record.content, rich))
+      if (binding.origin) { void drafts.discard(binding.origin); binding.origin = undefined }
+    }
+    const original = props.editor.getExtension(CommentEditorSubmitExtension)
+    let guarded: typeof original, stopEnter = () => {}
+    if (original) {
+      props.editor.replaceExtension(original, CommentEditorSubmitExtension({ onSubmit: async () => {
+        if (!binding.active || binding.composing || props.editor.prosemirrorView.composing) return
+        try {
+          context.store.beforeAction?.()
+          const positions = context.store.newDraftPositions(binding.target, owner.editor), selection = owner.editor.prosemirrorState.selection
+          if (!context.store.auth.canCreateThread() || !positions || selection.from !== positions.from || selection.to !== positions.to) { setFailure(true); return }
+          const before = new Set(context.store.getThreads().keys()), record = binding.record
+          submitting.current = true
+          try {
+            const result = original.submit(), thread = [...context.store.getThreads().values()].find(thread => !before.has(thread.id))
+            const actual = thread && context.store.threadSnapshot(thread.id)
+            if (actual) { drafts.submitted(record, actual.comments[0], actual); binding.record = undefined }
+            await result
+          } finally { submitting.current = false }
+        } catch { setFailure(true) }
+      } }))
+      guarded = props.editor.getExtension(CommentEditorSubmitExtension); composer.ready()
+      const extension = guarded
+      stopEnter = enterSubmits(props.editor, () => extension?.submit())
+    }
+    const stop = props.editor.onChange(() => {
+      if (!binding.active || suppress.current || submitting.current || !context.store.version) return
+      ++binding.input
+      if (props.editor.isEmpty) { if (binding.record) { void drafts.clearOwn(binding.record); binding.record = undefined }; return }
+      binding.record = drafts.write(binding.record?.target ?? binding.target, binding.record?.version ?? context.store.version,
+        nativeRichTextToProduct(props.editor.document as DocumentEditorBlock[], rich), binding.composing, binding.record) ?? binding.record
+    })
+    return () => { stop(); stopEnter(); if (original && guarded && !props.editor.prosemirrorView.isDestroyed && props.editor.getExtension(CommentEditorSubmitExtension) === guarded) props.editor.replaceExtension(guarded, original) }
+  }, [binding, drafts, props.editor])
+  const composerId = useRef(crypto.randomUUID())
+  useLayoutEffect(() => {
+    if (!binding || !drafts || !context) return
+    return drafts.registerComposer({ id: composerId.current, target: binding.target,
+      snapshot: () => { const available = binding.active && !submitting.current && !props.editor.prosemirrorView.isDestroyed; return { record: binding.record, composing: binding.composing || available && props.editor.prosemirrorView.composing, available } },
+      targetState: () => context.store.draftTargetState(binding.target) })
+  }, [binding, drafts, props.editor])
+  const t = DOCUMENT_EDITOR_MESSAGES[context?.locale ?? 'en']
+  const composition = (value: boolean) => {
+    if (!binding) return
+    binding.composing = value
+    if (binding.record && drafts) binding.record = drafts.write(binding.record.target, binding.record.version,
+      nativeRichTextToProduct(props.editor.document as DocumentEditorBlock[], rich), value, binding.record) ?? binding.record
+  }
+  return <div onCompositionStart={() => composition(true)} onCompositionEnd={() => composition(false)}>
+    <components.Comments.Editor {...props} />
+    {failure && <PmNotice tone="warn">{t.commentTargetUnavailable}</PmNotice>}
+    {state.failed && <PmNotice tone="warn">{t.commentBackupFailed}</PmNotice>}
+  </div>
+}
+
+export function DocumentNewCommentRecovery() {
+  const context = useContext(COMMENT_EDITOR_CONTEXT), owner = useContext(NEW_DRAFT_OWNER), drafts = context?.store.drafts
+  const active = useRef(true)
+  useLayoutEffect(() => { active.current = true; return () => { active.current = false } }, [owner?.editor])
+  const state = useSyncExternalStore(drafts?.subscribe ?? emptySubscribe, drafts?.snapshot ?? (() => emptyState)), t = DOCUMENT_EDITOR_MESSAGES[context?.locale ?? 'en']
+  const candidates = state.candidates.filter(value => isNewCommentDraft(value.target))
+  if (!drafts || !owner) return null
+  return <>{owner.failure && <PmNotice tone="warn">{t.commentTargetUnavailable}</PmNotice>}<DraftChoices candidates={candidates} preview
+    canRecover={candidate => isNewCommentDraft(candidate.target) && Boolean(context?.store.newDraftPositions(candidate.target, owner.editor))}
+    unavailableMessage={t.commentTargetUnavailable} onRecover={candidate => owner.restore(candidate, () => active.current)} onDiscard={async candidate => {
+      const binding = owner.latest.current, record = binding?.record, input = binding?.input
+      const { token, storage, ...value } = candidate
+      if (await drafts.discard(candidate) && binding && owner.latest.current === binding && binding.input === input && binding.record === record
+        && record && JSON.stringify(record) === JSON.stringify(value)) binding.record = undefined
+    }} /></>
+}