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

package/src/document-editor/authoring.tsx

@@ -0,0 +1,259 @@
+import { createContext, useContext, useMemo } from 'react'
+import type { CSSProperties, KeyboardEvent, ReactNode } from 'react'
+import { insertOrUpdateBlockForSlashMenu, isTableCell, mapTableCell } from '@blocknote/core'
+import type { Block } from '@blocknote/core'
+import { SideMenuExtension, SourceBlockWithPreviewExtension, TableHandlesExtension } from '@blocknote/core/extensions'
+import { DeleteButton, AddButton, DeleteLinkButton, DragHandleMenu, EditLinkButton, LinkToolbar, RemoveBlockItem, SideMenu, SplitButton, TableCellButton, TableCellMenu, TableColumnHeaderItem, TableHandle, TableRowHeaderItem, useBlockNoteEditor, useComponentsContext, useDictionary, useEditorState, useExtension, useExtensionState, usePortalElement, useUIMode } from '@blocknote/react'
+import type { DefaultReactSuggestionItem, LinkToolbarProps, SideMenuProps, TableCellButtonProps, TableHandleMenuProps, TableHandleProps } from '@blocknote/react'
+import { TextSelection } from '@tiptap/pm/state'
+import { DOCUMENT_COLOR_NAMES, documentColorToken, documentColorValue } from '@lincyaw/kernel'
+import type { DocumentColorKind } from '@lincyaw/kernel'
+import { PmIcon } from '../components.tsx'
+import { DOCUMENT_EDITOR_MESSAGES, slashAliases } from './messages.ts'
+import { DOCUMENT_EDITOR_LOCALE } from './math.tsx'
+import type { NativeDocumentEditor } from './schema.tsx'
+
+const useMessages = () => DOCUMENT_EDITOR_MESSAGES[useContext(DOCUMENT_EDITOR_LOCALE)]
+
+interface ColorChoice { color: string, setColor(color: string): void }
+
+function Swatch({ kind, value }: { kind: DocumentColorKind, value: string }) {
+  const style = value === 'default' ? undefined : { '--pm-swatch': documentColorValue(value, kind) } as CSSProperties
+  return <span className="pm-ui-color-swatch" data-kind={kind} style={style} aria-hidden="true">A</span>
+}
+
+/**
+ * Arrow keys move through the swatches as a grid: left and right within a group, up and down to the same colour in
+ * the other group. Mantine's own menu keys run after these and would only step through the items in order, so the
+ * keys handled here stop there; in a submenu the left arrow on a group's first swatch still returns to the parent item.
+ */
+function moveInGrid(event: KeyboardEvent<HTMLDivElement>, sub: boolean) {
+  const item = (event.target as HTMLElement).closest<HTMLElement>('[data-document-color]')
+  const rows = [...event.currentTarget.querySelectorAll('[role=group]')].map(group => [...group.querySelectorAll<HTMLElement>('[data-document-color]')])
+  const row = rows.findIndex(swatches => item && swatches.includes(item))
+  if (row < 0) return
+  const swatches = rows[row]!, column = swatches.indexOf(item!)
+  const at = (index: number) => rows[(index + rows.length) % rows.length]![column]
+  let target: HTMLElement | undefined
+  if (event.key === 'ArrowRight') target = swatches[(column + 1) % swatches.length]
+  else if (event.key === 'ArrowLeft' && !(sub && column === 0)) target = swatches[(column - 1 + swatches.length) % swatches.length]
+  else if (event.key === 'ArrowDown') target = at(row + 1)
+  else if (event.key === 'ArrowUp') target = at(row - 1)
+  if (!target) return
+  event.preventDefault()
+  event.stopPropagation()
+  target.focus()
+}
+
+/** The document's semantic palette as two rows of swatches; choosing one saves its design token. */
+function DocumentColorPicker({ text, background, sub = false }: { text?: ColorChoice, background?: ColorChoice, sub?: boolean }) {
+  const Components = useComponentsContext()!, t = useMessages()
+  const section = (kind: DocumentColorKind, choice: ColorChoice) => {
+    const current = choice.color === 'default' ? 'default' : documentColorValue(choice.color, kind)
+    const heading = kind === 'text' ? t.textColor : t.backgroundColor
+    return <div className="bn-color-picker-group" role="group" aria-label={heading}>
+      <Components.Generic.Menu.Label>{heading}</Components.Generic.Menu.Label>
+      {(['default', ...DOCUMENT_COLOR_NAMES] as const).map(name => {
+        const value = name === 'default' ? 'default' : documentColorToken(name, kind), checked = current === value
+        const label = name === 'default' ? kind === 'text' ? t.colorDefault : t.backgroundDefault : (kind === 'text' ? t.colorNames : t.backgroundNames)[name]
+        // The item's role is fixed to menuitem, so the current colour is announced as aria-current.
+        return <Components.Generic.Menu.Item key={`${kind}-${name}`} data-document-color={`${kind}-${name}`} data-checked={checked || undefined}
+          aria-label={label} aria-current={checked || undefined} {...{ title: label }} onClick={() => choice.setColor(value)}>
+          <Swatch kind={kind} value={value} />{checked && <PmIcon name="check" />}
+        </Components.Generic.Menu.Item>
+      })}
+    </div>
+  }
+  return <div className="bn-color-picker-grid" onKeyDownCapture={event => moveInGrid(event, sub)}>{text && section('text', text)}{background && section('background', background)}</div>
+}
+
+function ColorSubmenu({ children, text, background }: { children: ReactNode, text?: ColorChoice, background?: ColorChoice }) {
+  const Components = useComponentsContext()!, portalElement = usePortalElement()
+  return <Components.Generic.Menu.Root position="right" sub={true} portalElement={portalElement}>
+    <Components.Generic.Menu.Trigger sub={true}><Components.Generic.Menu.Item className="bn-menu-item" subTrigger={true}>{children}</Components.Generic.Menu.Item></Components.Generic.Menu.Trigger>
+    <Components.Generic.Menu.Dropdown sub={true} className="bn-menu-dropdown bn-color-picker-dropdown"><DocumentColorPicker text={text} background={background} sub={true} /></Components.Generic.Menu.Dropdown>
+  </Components.Generic.Menu.Root>
+}
+
+/** Formatting-toolbar colours for the selected text. */
+export function DocumentColorButton() {
+  const Components = useComponentsContext()!, portalElement = usePortalElement(), uiMode = useUIMode(), t = useMessages()
+  const editor = useBlockNoteEditor<any, any, any>()
+  const state = useEditorState({ editor, selector: ({ editor }) => {
+    if (!editor.isEditable || !(editor.getSelection()?.blocks ?? [editor.getTextCursorPosition().block]).some(block => block.content !== undefined)) return undefined
+    const styles = editor.getActiveStyles() as { textColor?: string, backgroundColor?: string }
+    return { text: styles.textColor || 'default', background: styles.backgroundColor || 'default' }
+  } })
+  if (!state) return null
+  const set = (style: 'textColor' | 'backgroundColor') => (color: string) => {
+    if (color === 'default') editor.removeStyles({ [style]: color })
+    else editor.addStyles({ [style]: color })
+    editor.focus()
+  }
+  return <Components.Generic.Menu.Root portalElement={portalElement} preventFocusOnOpen={uiMode === 'mobile'}>
+    <Components.Generic.Menu.Trigger>
+      <Components.FormattingToolbar.Button className="bn-button" data-document-colors="" label={t.colors} mainTooltip={t.colors}
+        icon={<span className="pm-ui-color-swatch pm-ui-color-swatch--pair" style={{ ...state.text !== 'default' ? { '--pm-swatch': documentColorValue(state.text, 'text') } : {}, ...state.background !== 'default' ? { '--pm-swatch-background': documentColorValue(state.background, 'background') } : {} } as CSSProperties} aria-hidden="true">A</span>} />
+    </Components.Generic.Menu.Trigger>
+    <Components.Generic.Menu.Dropdown className="bn-menu-dropdown bn-color-picker-dropdown">
+      <DocumentColorPicker text={{ color: state.text, setColor: set('textColor') }} background={{ color: state.background, setColor: set('backgroundColor') }} />
+    </Components.Generic.Menu.Dropdown>
+  </Components.Generic.Menu.Root>
+}
+
+function BlockColorsItem({ children }: { children: ReactNode }) {
+  const editor = useBlockNoteEditor<any, any, any>()
+  const block = useExtensionState(SideMenuExtension, { editor, selector: state => state?.block }) as Block<any, any, any> | undefined
+  if (!block || !('textColor' in block.props) && !('backgroundColor' in block.props)) return null
+  const choice = (property: 'textColor' | 'backgroundColor'): ColorChoice | undefined => property in block.props
+    ? { color: String(block.props[property] ?? 'default'), setColor: color => editor.updateBlock(block, { props: { [property]: color } }) } : undefined
+  return <ColorSubmenu text={choice('textColor')} background={choice('backgroundColor')}>{children}</ColorSubmenu>
+}
+
+function DocumentDragHandleMenu() {
+  const dict = useDictionary()
+  return <DragHandleMenu>
+    <RemoveBlockItem>{dict.drag_handle.delete_menuitem}</RemoveBlockItem>
+    <BlockColorsItem>{dict.drag_handle.colors_menuitem}</BlockColorsItem>
+    <TableRowHeaderItem>{dict.drag_handle.header_row_menuitem}</TableRowHeaderItem>
+    <TableColumnHeaderItem>{dict.drag_handle.header_column_menuitem}</TableColumnHeaderItem>
+  </DragHandleMenu>
+}
+export function DocumentSideMenu(props: SideMenuProps) { return <SideMenu {...props} dragHandleMenu={DocumentDragHandleMenu} /> }
+
+type TableBlock = Block<any, any, any> & { type: 'table', content: { type: 'tableContent', rows: { cells: any[] }[], headerRows?: number, headerCols?: number } }
+
+function useTableColors(cells: { row: number, col: number }[]) {
+  const editor = useBlockNoteEditor<any, any, any>()
+  const block = useExtensionState(TableHandlesExtension, { selector: state => state?.block }) as TableBlock | undefined
+  if (!block || !cells.length) return undefined
+  const rows = block.content.rows
+  const value = (property: 'textColor' | 'backgroundColor') => {
+    const values = cells.map(({ row, col }) => { const cell = rows[row]?.cells[col]; return cell && isTableCell(cell) ? cell.props[property] : 'default' })
+    return values.every(item => item === values[0]) ? values[0] ?? 'default' : 'default'
+  }
+  const update = (property: 'textColor' | 'backgroundColor') => (color: string) => {
+    const next = rows.map(row => ({ ...row, cells: row.cells.map(cell => mapTableCell(cell)) }))
+    for (const { row, col } of cells) if (next[row]?.cells[col]) next[row]!.cells[col]!.props[property] = color
+    editor.updateBlock(block, { type: 'table', content: { ...block.content, rows: next } })
+    editor.setTextCursorPosition(block)
+  }
+  return { text: { color: value('textColor'), setColor: update('textColor') }, background: { color: value('backgroundColor'), setColor: update('backgroundColor') } }
+}
+
+function CellColors() {
+  const dict = useDictionary()
+  const position = useExtensionState(TableHandlesExtension, { selector: state => state?.rowIndex === undefined || state.colIndex === undefined ? undefined : `${state.rowIndex}:${state.colIndex}` })
+  const cells = useMemo(() => position ? [{ row: Number(position.split(':')[0]), col: Number(position.split(':')[1]) }] : [], [position])
+  const colors = useTableColors(cells)
+  return colors ? <ColorSubmenu {...colors}>{dict.drag_handle.colors_menuitem}</ColorSubmenu> : null
+}
+function DocumentTableCellMenu() { return <TableCellMenu><SplitButton /><CellColors /></TableCellMenu> }
+export function DocumentTableCellButton(props: TableCellButtonProps) { return <TableCellButton {...props} tableCellMenu={DocumentTableCellMenu} /> }
+
+function LineColors({ orientation }: TableHandleMenuProps) {
+  const dict = useDictionary(), tableHandles = useExtension(TableHandlesExtension)
+  const { block, index } = useExtensionState(TableHandlesExtension, { selector: state => ({ block: state?.block, index: orientation === 'column' ? state?.colIndex : state?.rowIndex }) })
+  const cells = useMemo(() => !block || index === undefined ? [] : orientation === 'row' ? tableHandles.getCellsAtRowHandle(block, index) : tableHandles.getCellsAtColumnHandle(block, index), [block, index, orientation, tableHandles])
+  const colors = useTableColors(cells)
+  return colors ? <ColorSubmenu {...colors}>{dict.drag_handle.colors_menuitem}</ColorSubmenu> : null
+}
+// BlockNote's own header buttons are not exported, so the first row and column handles get the same toggle here.
+function LineHeader({ orientation }: TableHandleMenuProps) {
+  const Components = useComponentsContext()!, dict = useDictionary(), editor = useBlockNoteEditor<any, any, any>()
+  const { block, index } = useExtensionState(TableHandlesExtension, { selector: state => ({ block: state?.block as TableBlock | undefined, index: orientation === 'column' ? state?.colIndex : state?.rowIndex }) })
+  if (!block || index !== 0 || !editor.settings.tables.headers) return null
+  const key = orientation === 'row' ? 'headerRows' : 'headerCols', checked = Boolean(block.content[key])
+  return <Components.Generic.Menu.Item className="bn-menu-item" checked={checked} onClick={() => editor.updateBlock(block, { ...block, content: { ...block.content, [key]: checked ? undefined : 1 } })}>
+    {orientation === 'row' ? dict.drag_handle.header_row_menuitem : dict.drag_handle.header_column_menuitem}
+  </Components.Generic.Menu.Item>
+}
+function DocumentTableHandleMenu({ orientation }: TableHandleMenuProps) {
+  const Components = useComponentsContext()!
+  return <Components.Generic.Menu.Dropdown className="bn-table-handle-menu">
+    <DeleteButton orientation={orientation} />
+    <AddButton orientation={orientation} side={orientation === 'row' ? 'above' : 'left' as any} />
+    <AddButton orientation={orientation} side={orientation === 'row' ? 'below' : 'right' as any} />
+    <LineHeader orientation={orientation} />
+    <LineColors orientation={orientation} />
+  </Components.Generic.Menu.Dropdown>
+}
+// BlockNote passes the orientation at runtime, but its public menu type declares no props.
+const RowHandleMenu = () => <DocumentTableHandleMenu orientation="row" />
+const ColumnHandleMenu = () => <DocumentTableHandleMenu orientation="column" />
+export function DocumentTableHandle(props: TableHandleProps) { return <TableHandle {...props} tableHandleMenu={props.orientation === 'row' ? RowHandleMenu : ColumnHandleMenu} /> }
+
+function openBlockFormula(editor: NativeDocumentEditor, id: string): void {
+  editor.setTextCursorPosition(id, 'end')
+  editor.getExtension(SourceBlockWithPreviewExtension)?.store.setState(state => ({ ...state, popupOpen: id }))
+}
+
+/** Inserts a typed inline formula and places the caret in its source, which opens the formula popup. */
+export function insertInlineFormula(editor: NativeDocumentEditor, source = ''): void {
+  const start = editor.prosemirrorState.selection.from
+  editor.insertInlineContent([{ type: 'presmiumMathInline', props: {}, content: source }])
+  editor.transact(transaction => {
+    // The formula replaces the selection at its start; the caret goes to the end of its source.
+    const node = transaction.doc.nodeAt(start)
+    if (node?.type.name === 'presmiumMathInline') transaction.setSelection(TextSelection.create(transaction.doc, start + node.nodeSize - 1))
+  })
+  editor.focus()
+}
+
+export function formulaSlashItems(editor: NativeDocumentEditor, locale: keyof typeof DOCUMENT_EDITOR_MESSAGES, group: string): DefaultReactSuggestionItem[] {
+  const t = DOCUMENT_EDITOR_MESSAGES[locale]
+  return [{
+    title: t.formulaBlock, subtext: t.formulaBlockHint, group, icon: <PmIcon name="formula" />, aliases: slashAliases('formulaBlockAliases'),
+    onItemClick: () => openBlockFormula(editor, insertOrUpdateBlockForSlashMenu(editor, { type: 'presmiumMath', content: '' }).id),
+  }, {
+    title: t.formulaInline, subtext: t.formulaInlineHint, group, icon: <PmIcon name="formula" />, aliases: slashAliases('formulaInlineAliases'),
+    onItemClick: () => insertInlineFormula(editor),
+  }]
+}
+
+/** Turns the selected text into an inline formula, its text becoming the LaTeX source. */
+export function FormulaToolbarButton() {
+  const Components = useComponentsContext()!, t = useMessages()
+  const editor = useBlockNoteEditor<any, any, any>() as unknown as NativeDocumentEditor
+  const show = useEditorState({ editor, selector: ({ editor }) => {
+    const blocks = editor.getSelection()?.blocks ?? [editor.getTextCursorPosition().block]
+    return editor.isEditable && blocks.length === 1 && blocks[0]!.content !== undefined && blocks[0]!.type !== 'codeBlock' && blocks[0]!.type !== 'presmiumMath' && !editor.getActiveStyles().code
+  } })
+  if (!show) return null
+  return <Components.FormattingToolbar.Button className="bn-button" data-document-formula="" label={t.formulaInline} mainTooltip={t.formulaInline} icon={<PmIcon name="formula" />}
+    onClick={() => insertInlineFormula(editor, editor.getSelectedText().replace(/\n/g, ' '))} />
+}
+
+export interface DocumentLinks {
+  /** Shows a page of this document; false when the anchor names none. */
+  openSection?(sectionId: string): boolean
+}
+export const DOCUMENT_LINKS = createContext<DocumentLinks>({})
+
+const EXTERNAL_PROTOCOLS = new Set(['http:', 'https:', 'mailto:', 'tel:'])
+
+/** In-document anchors navigate the workbench; absolute web links open in a new, unrelated tab. */
+export function openDocumentLink(href: string, links: DocumentLinks): void {
+  if (href.startsWith('#')) {
+    let id = href.slice(1)
+    try { id = decodeURIComponent(id) } catch {}
+    links.openSection?.(id)
+    return
+  }
+  let url: URL
+  try { url = new URL(href) } catch { return }
+  if (EXTERNAL_PROTOCOLS.has(url.protocol)) window.open(url.href, '_blank', 'noopener,noreferrer')
+}
+
+function OpenLinkButton({ url }: { url: string }) {
+  const Components = useComponentsContext()!, t = useMessages(), links = useContext(DOCUMENT_LINKS)
+  return <Components.LinkToolbar.Button className="bn-button" mainTooltip={t.openLink} label={t.openLink} isSelected={false}
+    onClick={() => openDocumentLink(url, links)} icon={<PmIcon name={url.startsWith('#') ? 'link' : 'external'} />} />
+}
+export function DocumentLinkToolbar(props: LinkToolbarProps) {
+  return <LinkToolbar {...props}>
+    <EditLinkButton url={props.url} text={props.text} range={props.range} setToolbarOpen={props.setToolbarOpen} setToolbarPositionFrozen={props.setToolbarPositionFrozen} />
+    <OpenLinkButton url={props.url} />
+    <DeleteLinkButton range={props.range} setToolbarOpen={props.setToolbarOpen} />
+  </LinkToolbar>
+}

package/src/document-editor/block-playback.ts

@@ -0,0 +1,90 @@
+import type { BlockPreviewCommand, BlockPreviewPlaybackGranted, BlockPreviewPlaybackRequest } from '@lincyaw/kernel'
+
+interface Member {
+  request: BlockPreviewPlaybackRequest
+  release?: () => void
+  stopped: boolean
+  waiting?: { promise: Promise<void>, finish(error?: Error): void }
+}
+
+interface PlaybackOptions {
+  activate(stop: () => Promise<void>): Promise<() => void>
+  current(request: BlockPreviewPlaybackRequest): boolean
+  adopt(request: BlockPreviewPlaybackRequest): string
+  post(message: BlockPreviewCommand | BlockPreviewPlaybackGranted): void
+  failure: string
+}
+
+/** Wait for the existing child's cancellation acknowledgement before admitting another player. */
+export class DocumentBlockPlayback {
+  readonly #options: PlaybackOptions
+  readonly #members = new Map<number, Member>()
+  #disposed = false
+  constructor(options: PlaybackOptions) { this.#options = options }
+
+  request(request: BlockPreviewPlaybackRequest): void {
+    if (this.#disposed || this.#members.has(request.request)) return
+    if (!this.#options.current(request)) { this.#grant(request, this.#options.failure); return }
+    const member: Member = { request, stopped: false }
+    this.#members.set(request.request, member)
+    void this.#options.activate(() => this.#stop(member)).then(release => {
+      member.release = release
+      if (this.#disposed || member.stopped) { release(); return }
+      if (!this.#options.current(request)) {
+        release(); this.#members.delete(request.request)
+        this.#grant(request, this.#options.failure)
+        return
+      }
+      const navigation = this.#options.adopt(request)
+      this.#grant(request, undefined, navigation)
+    }, error => {
+      this.#members.delete(request.request)
+      if (this.#disposed || member.stopped) return
+      if (error && typeof error === 'object' && 'name' in error && error.name === 'AbortError') this.#pause(request)
+      else this.#grant(request, this.#options.failure)
+    })
+  }
+
+  cancelled(request: number): void {
+    const member = this.#members.get(request)
+    if (!member) return
+    member.stopped = true; member.waiting?.finish(); member.release?.()
+    this.#members.delete(request)
+  }
+
+  #grant(request: BlockPreviewPlaybackRequest, error?: string, navigation = request.navigation): void {
+    if (this.#disposed) return
+    const { document, blockId, revision } = request
+    this.#options.post({ type: 'presmium:block-preview-playback-granted', document, blockId, revision, request: request.request, navigation, ...error ? { error } : {} })
+  }
+
+  #pause(request: BlockPreviewPlaybackRequest): void {
+    const { document, blockId, revision, sectionId, stepId } = request
+    this.#options.post({ type: 'presmium:block-preview-command', document, blockId, revision, sectionId, stepId, action: 'pause' })
+  }
+
+  #stop(member: Member): Promise<void> {
+    if (this.#disposed || member.stopped) return Promise.resolve()
+    if (member.waiting) return member.waiting.promise
+    let finish!: (error?: Error) => void
+    const promise = new Promise<void>((resolve, reject) => {
+      const timer = setTimeout(() => finish(new Error('block-playback-pause-timeout')), 5000)
+      finish = error => {
+        clearTimeout(timer); member.waiting = undefined
+        if (error) reject(error); else resolve()
+      }
+    })
+    member.waiting = { promise, finish }
+    this.#pause(member.request)
+    return promise
+  }
+
+  dispose(): void {
+    if (this.#disposed) return
+    this.#disposed = true
+    for (const member of this.#members.values()) {
+      member.stopped = true; member.waiting?.finish(); member.release?.()
+    }
+    this.#members.clear()
+  }
+}

package/src/document-editor/block-preview-messages.ts

@@ -0,0 +1,13 @@
+/** The words of a block's read-only preview and of its stand-in while the preview is not shown. */
+export const BLOCK_PREVIEW_MESSAGES = {
+  'zh-CN': {
+    preparing: '正在准备预览…', preparingDetail: '首次打开或修改代码后需要稍候，预览准备好后会自动显示。',
+    buildFailure: '这项预览暂时无法准备，请检查最近的修改后重试。', displayFailure: '预览没有显示出来，请重试。',
+    content: '内容', animation: '动画', mindMap: '思维导图', video: '视频', audio: '音频', image: '图片',
+  },
+  en: {
+    preparing: 'Preparing preview…', preparingDetail: 'The first time, or after code changes, this takes a moment. The preview appears when it is ready.',
+    buildFailure: 'This preview could not be prepared. Check recent changes, then retry.', displayFailure: 'The preview did not appear. Retry.',
+    content: 'Content', animation: 'Animation', mindMap: 'Mind map', video: 'Video', audio: 'Audio', image: 'Picture',
+  },
+}

package/src/document-editor/blocknote-messages.ts

@@ -0,0 +1,98 @@
+import type { Dictionary } from '@blocknote/core'
+import { en, zh } from '@blocknote/core/locales'
+import type { Locale } from '../messages.ts'
+
+type Overrides<T> = { [K in keyof T]?: T[K] extends string ? string : T[K] extends (...args: never[]) => unknown ? T[K] : Overrides<T[K]> }
+
+const basic = { 'zh-CN': '基本内容块', en: 'Basic Blocks' }
+const basicGroups = (locale: Locale) => Object.fromEntries(['quote', 'toggle_list', 'numbered_list', 'bullet_list', 'check_list', 'paragraph', 'code_block', 'page_break', 'divider'].map(key => [key, { group: basic[locale] }]))
+const kinds = <T extends string>(image: T, video: T, audio: T, file: T) => ({ image, video, audio, file })
+
+// The block editor's own text, changed where it differs from docs/glossary.md (批注 / New Comment, 内容块 / Block,
+// 插入 / Insert, commands in Title Case, one “…”). Every other entry stays BlockNote's.
+export const BLOCKNOTE_MESSAGES: Record<Locale, Overrides<Dictionary>> = {
+  'zh-CN': {
+    slash_menu: { ...basicGroups('zh-CN'), image: { title: '图片', subtext: '可调整大小、带题注的图片' }, divider: { subtext: '分隔内容块', group: basic['zh-CN'] } },
+    placeholders: { default: '输入文字，或输入“/”使用命令', toggleListItem: '折叠项', new_comment: '输入批注…', edit_comment: '编辑批注…', comment_reply: '回复…' },
+    file_blocks: { add_button_text: kinds('插入图片', '插入视频', '插入音频', '插入文件') },
+    toggle_blocks: { add_block_button: '空的折叠项。单击以插入内容块。', toggle_button: '显示或隐藏' },
+    code_block: { add_source_button_text: '插入代码' },
+    side_menu: { add_block_label: '插入内容块', drag_handle_label: '打开内容块菜单' },
+    drag_handle: { header_row_menuitem: '标题行', header_column_menuitem: '标题列' },
+    table_handle: { delete_column_menuitem: '删除列', delete_row_menuitem: '删除行', split_cell_menuitem: '拆分单元格', merge_cells_menuitem: '合并单元格', background_color_menuitem: '背景色', add_left_menuitem: '在左侧插入列', add_right_menuitem: '在右侧插入列', add_above_menuitem: '在上方插入行', add_below_menuitem: '在下方插入行' },
+    formatting_toolbar: {
+      strike: { tooltip: '删除线' }, code: { tooltip: '代码' }, link: { tooltip: '插入链接' },
+      file_caption: { tooltip: '编辑题注', input_placeholder: '输入题注' },
+      file_replace: { tooltip: kinds('替换图片', '替换视频', '替换音频', '替换文件') },
+      file_rename: { tooltip: kinds('重命名图片', '重命名视频', '重命名音频', '重命名文件'), input_placeholder: kinds('输入名称', '输入名称', '输入名称', '输入名称') },
+      file_download: { tooltip: kinds('下载图片', '下载视频', '下载音频', '下载文件') },
+      file_delete: { tooltip: kinds('删除图片', '删除视频', '删除音频', '删除文件') },
+      file_preview_toggle: { tooltip: '显示或隐藏预览' },
+      nest: { tooltip: '增加缩进' }, unnest: { tooltip: '减少缩进' },
+      align_left: { tooltip: '左对齐' }, align_center: { tooltip: '居中' }, align_right: { tooltip: '右对齐' }, align_justify: { tooltip: '两端对齐' },
+      comment: { tooltip: '新建批注' },
+    },
+    file_panel: { upload: { file_placeholder: kinds('上传图片', '上传视频', '上传音频', '上传文件'), upload_error: '无法上传文件' }, embed: { embed_button: kinds('嵌入图片', '嵌入视频', '嵌入音频', '嵌入文件'), url_placeholder: '输入网址' } },
+    link_toolbar: { delete: { tooltip: '移除链接' }, edit: { text: '编辑链接' }, open: { tooltip: '在新标签页中打开' }, form: { title_placeholder: '链接文字', url_placeholder: '链接地址' } },
+    comments: {
+      discard_pending_comment: '要放弃这条批注吗？',
+      actions: { add_reaction: '添加回应', edit_comment: '编辑批注', delete_comment: '删除批注', more_actions: '更多' },
+    },
+    versioning: {
+      title: '版本历史', start_of_document: '文稿开头', show_named_only: '仅显示已命名的版本', show_all: '显示所有版本', comparison_on: '开启对比', comparison_off: '关闭对比',
+      compare_since_beginning_menuitem: '与最初的版本对比', name_version_menuitem: '命名此版本', compare_with_menuitem: '与此版本对比',
+      before_restore: '还原前', restore_menuitem: '还原', more_actions: '更多', action_failed: '无法完成操作，请重试。', history_load_failed: '无法加载版本历史',
+    },
+    exporter: { open_file: '打开文件', open_video_file: '打开视频', open_audio_file: '打开音频' },
+    generic: { loading: '正在加载…', load_more: '加载更多' },
+  },
+  en: {
+    slash_menu: { ...basicGroups('en'), image: { title: 'Picture', subtext: 'Resizable picture with caption' }, divider: { subtext: 'Visually divide blocks', group: basic.en } },
+    placeholders: { default: 'Enter text, or type “/” for commands', toggleListItem: 'Toggle', new_comment: 'Write a comment…', edit_comment: 'Write a comment…', comment_reply: 'Reply…' },
+    file_blocks: { add_button_text: kinds('Insert Picture', 'Insert Video', 'Insert Audio', 'Insert File') },
+    toggle_blocks: { add_block_button: 'Empty toggle. Click to insert a block.', toggle_button: 'Show or Hide' },
+    code_block: { add_source_button_text: 'Insert Code' },
+    side_menu: { add_block_label: 'Insert Block', drag_handle_label: 'Open Block Menu' },
+    drag_handle: { header_row_menuitem: 'Header Row', header_column_menuitem: 'Header Column' },
+    table_handle: { delete_column_menuitem: 'Delete Column', delete_row_menuitem: 'Delete Row', split_cell_menuitem: 'Split Cell', merge_cells_menuitem: 'Merge Cells', background_color_menuitem: 'Background Color', add_left_menuitem: 'Insert Column Left', add_right_menuitem: 'Insert Column Right', add_above_menuitem: 'Insert Row Above', add_below_menuitem: 'Insert Row Below' },
+    formatting_toolbar: {
+      strike: { tooltip: 'Strikethrough' }, code: { tooltip: 'Code' }, link: { tooltip: 'Insert Link' },
+      file_caption: { tooltip: 'Edit Caption', input_placeholder: 'Enter a caption' },
+      file_replace: { tooltip: kinds('Replace Picture', 'Replace Video', 'Replace Audio', 'Replace File') },
+      file_rename: { tooltip: kinds('Rename Picture', 'Rename Video', 'Rename Audio', 'Rename File'), input_placeholder: kinds('Enter a name', 'Enter a name', 'Enter a name', 'Enter a name') },
+      file_download: { tooltip: kinds('Download Picture', 'Download Video', 'Download Audio', 'Download File') },
+      file_delete: { tooltip: kinds('Delete Picture', 'Delete Video', 'Delete Audio', 'Delete File') },
+      file_preview_toggle: { tooltip: 'Show or Hide Preview' },
+      nest: { tooltip: 'Increase Indent' }, unnest: { tooltip: 'Decrease Indent' },
+      align_left: { tooltip: 'Align Left' }, align_center: { tooltip: 'Center' }, align_right: { tooltip: 'Align Right' }, align_justify: { tooltip: 'Justify' },
+      comment: { tooltip: 'New Comment' },
+    },
+    file_panel: { upload: { file_placeholder: kinds('Upload Picture', 'Upload Video', 'Upload Audio', 'Upload File'), upload_error: 'Couldn’t upload the file' }, embed: { embed_button: kinds('Embed Picture', 'Embed Video', 'Embed Audio', 'Embed File'), url_placeholder: 'Enter an address' } },
+    link_toolbar: { delete: { tooltip: 'Remove Link' }, edit: { text: 'Edit Link' }, open: { tooltip: 'Open in New Tab' }, form: { title_placeholder: 'Link text', url_placeholder: 'Link address' } },
+    comments: {
+      discard_pending_comment: 'Discard this comment?',
+      actions: { add_reaction: 'Add Reaction', edit_comment: 'Edit Comment', delete_comment: 'Delete Comment', more_actions: 'More' },
+    },
+    versioning: {
+      title: 'Version History', start_of_document: 'Beginning of document', show_named_only: 'Show Named Versions Only', show_all: 'Show All Versions', comparison_on: 'Turn On Comparison', comparison_off: 'Turn Off Comparison',
+      compare_since_beginning_menuitem: 'Compare with First Version', name_version_menuitem: 'Name This Version', compare_with_menuitem: 'Compare with This Version',
+      before_restore: 'Before restore', restore_menuitem: 'Restore', more_actions: 'More', action_failed: 'Couldn’t finish the operation. Try again.', history_load_failed: 'Couldn’t load Version History',
+    },
+    exporter: { open_file: 'Open File', open_video_file: 'Open Video', open_audio_file: 'Open Audio' },
+    generic: { loading: 'Loading…', load_more: 'Load More' },
+  },
+}
+
+function merged<T>(base: T, overrides: Overrides<T> | undefined): T {
+  if (!overrides || typeof base !== 'object' || base === null) return (overrides ?? base) as T
+  const out = { ...base } as Record<string, unknown>
+  for (const [key, value] of Object.entries(overrides)) out[key] = merged((base as Record<string, unknown>)[key], value as Overrides<unknown>)
+  return out as T
+}
+
+const DICTIONARIES: Record<Locale, Dictionary> = { 'zh-CN': merged(zh, BLOCKNOTE_MESSAGES['zh-CN']), en: merged(en, BLOCKNOTE_MESSAGES.en) }
+
+/** BlockNote's dictionary for the interface language, through its public `dictionary` option. */
+export function blockNoteDictionary(locale: Locale): Dictionary {
+  return DICTIONARIES[locale]
+}

package/src/document-editor/clipboard.ts

@@ -0,0 +1,40 @@
+import { createExtension } from '@blocknote/core'
+import { Extension } from '@tiptap/core'
+import { Plugin } from '@tiptap/pm/state'
+import type { EditorView } from '@tiptap/pm/view'
+
+function canCopyNativeText(view: EditorView): boolean {
+  const selection = view.dom.ownerDocument.getSelection()
+  if (!selection || selection.isCollapsed || selection.rangeCount !== 1
+    || !selection.anchorNode || !selection.focusNode
+    || !view.dom.contains(selection.anchorNode) || !view.dom.contains(selection.focusNode)) return false
+  const range = selection.getRangeAt(0)
+  let hasTextBlock = false
+  for (const element of view.dom.querySelectorAll('[data-content-type]')) {
+    if (!range.intersectsNode(element)) continue
+    const type = element.getAttribute('data-content-type')
+    if (type !== 'paragraph' && type !== 'bulletListItem') return false
+    hasTextBlock = true
+  }
+  if (!hasTextBlock) return false
+  for (const element of view.dom.querySelectorAll('[data-inline-content-type]:not([data-inline-content-type="text"]):not([data-inline-content-type="link"]), [data-bn-thread-id], [contenteditable="false"]')) {
+    if (range.intersectsNode(element)) return false
+  }
+  return true
+}
+
+/** Plain native text uses the browser's current range; protected nodes keep BlockNote's serializer. */
+export const nativeTextClipboard = createExtension({
+  key: 'presmium-native-text-clipboard',
+  tiptapExtensions: [Extension.create({
+    name: 'presmium-native-text-clipboard',
+    priority: 1000,
+    addProseMirrorPlugins() {
+      return [new Plugin({ props: { handleDOMEvents: {
+        // Consuming the editor handler without preventDefault retains the browser's clipboard action.
+        copy: canCopyNativeText,
+        cut: view => view.editable && canCopyNativeText(view),
+      } } })]
+    },
+  })],
+})

package/src/document-editor/colors.ts

@@ -0,0 +1,57 @@
+import { createExtension, defaultStyleSpecs } from '@blocknote/core'
+import { documentColorValue } from '@lincyaw/kernel'
+import type { DocumentColorKind } from '@lincyaw/kernel'
+import type { StyleSpec } from '@blocknote/core'
+import { Plugin } from '@tiptap/pm/state'
+import type { EditorState } from '@tiptap/pm/state'
+import { Decoration, DecorationSet } from '@tiptap/pm/view'
+import type { Node } from '@tiptap/pm/model'
+
+// Document colours are design tokens; older BlockNote palette names paint as the same semantic token the viewer uses.
+export function documentColor(value: string | undefined, kind: DocumentColorKind): string | undefined {
+  if (!value || value === 'default') return undefined
+  const color = documentColorValue(value, kind)
+  return typeof CSS !== 'undefined' && CSS.supports('color', color) ? color : undefined
+}
+
+function colorStyle<Config extends { type: 'textColor' | 'backgroundColor', propSchema: 'string' }>(spec: StyleSpec<Config>, property: 'color' | 'backgroundColor'): StyleSpec<Config> {
+  const mark = spec.implementation.mark.extend({
+    addMarkView() {
+      // BlockNote's own style marks always define a mark view.
+      const parent = this.parent!()
+      return props => {
+        const view = parent(props)
+        const color = documentColor(props.mark.attrs.stringValue as string | undefined, property === 'color' ? 'text' : 'background')
+        if (color && view.dom instanceof HTMLElement) view.dom.style[property] = color
+        return view
+      }
+    },
+  })
+  return { ...spec, implementation: { ...spec.implementation, mark } }
+}
+
+export const documentColorStyles = {
+  textColor: colorStyle(defaultStyleSpecs.textColor, 'color'),
+  backgroundColor: colorStyle(defaultStyleSpecs.backgroundColor, 'backgroundColor'),
+}
+
+function decorations(doc: Node): DecorationSet {
+  const found: Decoration[] = []
+  doc.descendants((node, position) => {
+    const color = documentColor(node.attrs.textColor as string | undefined, 'text'), background = documentColor(node.attrs.backgroundColor as string | undefined, 'background')
+    if (color || background) found.push(Decoration.node(position, position + node.nodeSize, { style: [color && `color: ${color}`, background && `background-color: ${background}`].filter(Boolean).join('; ') }))
+  })
+  return DecorationSet.create(doc, found)
+}
+
+/** Block and table-cell colours are painted with public node decorations. */
+export const documentBlockColors = createExtension({
+  key: 'presmiumDocumentBlockColors',
+  prosemirrorPlugins: [new Plugin<DecorationSet>({
+    state: {
+      init: (_, state: EditorState) => decorations(state.doc),
+      apply: (transaction, value) => transaction.docChanged ? decorations(transaction.doc) : value,
+    },
+    props: { decorations(state) { return this.getState(state) } },
+  })],
+})

package/src/document-editor/comment-draft-actions.ts

@@ -0,0 +1,58 @@
+import type { AuthoringClientAction, AuthoringClientActionResult, ClientCommentDraftReference } from '@lincyaw/kernel'
+import { draftContentHash } from '../authoring-draft-fragment.ts'
+import { commentDraftReference } from './comment-draft-inspection.ts'
+import { isNewCommentDraft } from './comment-drafts.ts'
+import type { CommentDrafts } from './comment-drafts.ts'
+
+const sameReference = (a: ClientCommentDraftReference | null, b: ClientCommentDraftReference | null): boolean => a === null || b === null ? a === b
+  : a.id === b.id && a.revision === b.revision && a.token === b.token
+
+/** The native composer, rather than its backup, acknowledges actual editor adoption. */
+export async function mutateCommentDrafts(drafts: CommentDrafts, action: Extract<AuthoringClientAction, { type: 'comment-drafts.restore' | 'comment-drafts.discard' }>, signal: AbortSignal, owned: () => void, fits: (result: AuthoringClientActionResult) => boolean): Promise<AuthoringClientActionResult> {
+  const read = await drafts.readForAgent(signal, action.draft), candidate = read.candidates[0]!
+  owned()
+  if (action.type === 'comment-drafts.discard') {
+    const guard = () => { signal.throwIfAborted(); owned(); if (drafts.targetActive(candidate.target) || candidate.composing || candidate.pending) throw new Error('client-comment-draft-needs-human') }
+    const result: AuthoringClientActionResult = { type: action.type, family: 'comment', draft: action.draft, discarded: true }
+    guard()
+    if (!fits(result)) throw new Error('client-comment-result-too-large')
+    if (!await drafts.discard(action.draft, { signal, guard })) throw new Error('client-comment-drafts-changed')
+    guard()
+    return result
+  }
+  if (isNewCommentDraft(candidate.target) || candidate.composing || candidate.pending || candidate.storage !== 'durable') throw new Error('client-comment-draft-needs-human')
+  const composer = drafts.composer(action.composerId), choice = await drafts.restoreChoice(candidate, signal)
+  owned()
+  if (!composer?.restore || choice?.composerId !== action.composerId || !sameReference(choice.expectedCurrent, action.expectedCurrent)) throw new Error('client-comment-composer-unavailable')
+  const previous = composer.snapshot().record
+  if (previous) {
+    if (!action.expectedCurrent) throw new Error('client-comment-drafts-changed')
+    const current = await drafts.readForAgent(signal, action.expectedCurrent)
+    owned()
+    if (current.candidates[0]?.storage !== 'durable') throw new Error('client-comment-draft-needs-human')
+  } else if (action.expectedCurrent !== null) throw new Error('client-comment-drafts-changed')
+  const guard = () => {
+    signal.throwIfAborted(); owned()
+    const state = composer.snapshot()
+    if (!drafts.ownersKnown || drafts.composer(action.composerId) !== composer || state.record !== previous || !state.available || state.composing || composer.targetState() === 'unavailable') throw new Error('client-comment-composer-changed')
+  }
+  guard()
+  const targetState = composer.targetState()
+  if (targetState === 'unavailable') throw new Error('client-comment-composer-unavailable')
+  if (!fits({ type: action.type, family: 'comment', draft: action.draft, composerId: action.composerId,
+    restored: { id: '0'.repeat(36), revision: 1, token: '0'.repeat(64) }, preservedCurrent: action.expectedCurrent, targetState })) throw new Error('client-comment-result-too-large')
+  const record = await composer.restore(candidate, { signal, guard })
+  if (!record) throw new Error('client-comment-native-unverified')
+  const adopted = () => {
+    signal.throwIfAborted(); owned()
+    const state = composer.snapshot()
+    if (!drafts.ownersKnown || drafts.composer(action.composerId) !== composer || state.record !== record || !state.available || state.composing || !drafts.owns(record)) throw new Error('client-comment-composer-changed')
+  }
+  adopted()
+  const token = await draftContentHash(JSON.stringify(record))
+  adopted()
+  const result: AuthoringClientActionResult = { type: action.type, family: 'comment', draft: action.draft, composerId: action.composerId,
+    restored: commentDraftReference({ ...record, token, storage: 'durable' }), preservedCurrent: action.expectedCurrent, targetState }
+  if (!fits(result)) throw new Error('client-comment-result-too-large')
+  return result
+}