@byline/richtext-lexical 5.2.0 → 6.0.0

package/src/field/plugins/toolbar-plugin/index.tsx

@@ -32,7 +32,7 @@ import {
   INSERT_CHECK_LIST_COMMAND,
   INSERT_ORDERED_LIST_COMMAND,
   INSERT_UNORDERED_LIST_COMMAND,
-  ListExtension,
+  ListItemNode,
   ListNode,
   REMOVE_LIST_COMMAND,
 } from '@lexical/list'
@@ -47,7 +47,9 @@ import {
   $createQuoteNode,
   $isHeadingNode,
   $isQuoteNode,
+  HeadingNode,
   type HeadingTagType,
+  QuoteNode,
 } from '@lexical/rich-text'
 import { $setBlocksType } from '@lexical/selection'
 import { $isTableNode } from '@lexical/table'
@@ -92,8 +94,8 @@ import {
   OPEN_LINK_MODAL_COMMAND,
   TOGGLE_LINK_COMMAND,
 } from '../../extensions/link'
-import { useMarkdownToggle } from '../../hooks/use-markdown-toggle'
-import { IS_APPLE } from '../../shared/environment'
+import { canUseMarkdownSourceMode, useMarkdownToggle } from '../../hooks/use-markdown-toggle'
+import { useIsApplePlatform } from '../../hooks/use-platform-modifier'
 import { DropDown, DropDownItem } from '../../ui/dropdown'
 import { getSelectedNode } from '../../utils/getSelectedNode'
 import { sanitizeUrl } from '../../utils/url'
@@ -136,6 +138,53 @@ function dropDownActiveClass(active: boolean): string {
   return ''
 }
 
+export type BlockFormat =
+  | 'paragraph'
+  | 'h1'
+  | 'h2'
+  | 'h3'
+  | 'h4'
+  | 'bullet'
+  | 'number'
+  | 'check'
+  | 'quote'
+  | 'code'
+
+/**
+ * Block formats this editor can actually produce. Paragraph is always
+ * available.
+ *
+ * Structural availability comes from REGISTERED NODES, not from whether
+ * an extension appears in the configuration list: table and list nodes
+ * arrive through `@lexical/table` and `@lexical/list` dependencies, so a
+ * membership test would be wrong for exactly those cases.
+ *
+ * Registered nodes are necessary but not always sufficient.
+ * `hasCheckListBehaviour` is passed in because check lists need
+ * `CheckListExtension` registered as well as the list nodes — removing
+ * that extension alone leaves `ListNode` and `ListItemNode` in place, so
+ * a node-only rule would keep offering a control that no longer works.
+ *
+ * This is a correctness concern rather than a cosmetic one: creating an
+ * unregistered node throws "Attempted to create node X that was not
+ * configured to be used on the editor", so an offered-but-unsupported
+ * format is a crash.
+ */
+export function availableBlockFormats(
+  editor: LexicalEditor,
+  hasCheckListBehaviour: boolean
+): BlockFormat[] {
+  const formats: BlockFormat[] = ['paragraph']
+  if (editor.hasNodes([HeadingNode])) formats.push('h1', 'h2', 'h3', 'h4')
+  if (editor.hasNodes([ListNode, ListItemNode])) {
+    formats.push('bullet', 'number')
+    if (hasCheckListBehaviour) formats.push('check')
+  }
+  if (editor.hasNodes([QuoteNode])) formats.push('quote')
+  if (editor.hasNodes([CodeNode])) formats.push('code')
+  return formats
+}
+
 function BlockFormatDropDown({
   editor,
   blockType,
@@ -146,15 +195,13 @@ function BlockFormatDropDown({
   rootType: keyof typeof rootTypeToRootName
   editor: LexicalEditor
   disabled?: boolean
-}): React.JSX.Element {
-  // Block-format dropdown entries are gated on whether the underlying
-  // extensions are present in the editor's extension graph. Removing
-  // ListExtension via lexicalEditor((c) => c.extensions.remove(ListExtension))
-  // hides the list options here without any flag in EditorSettings.
-  const hasList = useOptionalExtensionDependency(ListExtension) !== undefined
-  const hasCheckList = useOptionalExtensionDependency(CheckListExtension) !== undefined
+}): React.JSX.Element | null {
+  // Entries follow what the resolved editor can actually produce, so
+  // removing an extension removes its control along with its node
+  // registration — no flag in EditorSettings is involved.
   const [composerEditor] = useLexicalComposerContext()
-  const hasCodeHighlight = composerEditor.hasNodes([CodeNode])
+  const hasCheckListBehaviour = useOptionalExtensionDependency(CheckListExtension) !== undefined
+  const formats = availableBlockFormats(composerEditor, hasCheckListBehaviour)
 
   const formatParagraph = (): void => {
     editor.update(() => {
@@ -233,6 +280,10 @@ function BlockFormatDropDown({
     }
   }
 
+  // Paragraph alone is not a choice — with every structural format
+  // removed the control would offer a single no-op entry.
+  if (formats.length === 1) return null
+
   return (
     <DropDown
       disabled={disabled}
@@ -248,43 +299,47 @@ function BlockFormatDropDown({
         <i className="icon paragraph" />
         <span className="text">Normal</span>
       </DropDownItem>
-      <DropDownItem
-        className={`item ${dropDownActiveClass(blockType === 'h1')}`}
-        onClick={() => {
-          formatHeading('h1')
-        }}
-      >
-        <i className="icon h1" />
-        <span className="text">Heading 1</span>
-      </DropDownItem>
-      <DropDownItem
-        className={`item ${dropDownActiveClass(blockType === 'h2')}`}
-        onClick={() => {
-          formatHeading('h2')
-        }}
-      >
-        <i className="icon h2" />
-        <span className="text">Heading 2</span>
-      </DropDownItem>
-      <DropDownItem
-        className={`item ${dropDownActiveClass(blockType === 'h3')}`}
-        onClick={() => {
-          formatHeading('h3')
-        }}
-      >
-        <i className="icon h3" />
-        <span className="text">Heading 3</span>
-      </DropDownItem>
-      <DropDownItem
-        className={`item ${dropDownActiveClass(blockType === 'h4')}`}
-        onClick={() => {
-          formatHeading('h4')
-        }}
-      >
-        <i className="icon h4" />
-        <span className="text">Heading 4</span>
-      </DropDownItem>
-      {hasList && (
+      {formats.includes('h1') && (
+        <>
+          <DropDownItem
+            className={`item ${dropDownActiveClass(blockType === 'h1')}`}
+            onClick={() => {
+              formatHeading('h1')
+            }}
+          >
+            <i className="icon h1" />
+            <span className="text">Heading 1</span>
+          </DropDownItem>
+          <DropDownItem
+            className={`item ${dropDownActiveClass(blockType === 'h2')}`}
+            onClick={() => {
+              formatHeading('h2')
+            }}
+          >
+            <i className="icon h2" />
+            <span className="text">Heading 2</span>
+          </DropDownItem>
+          <DropDownItem
+            className={`item ${dropDownActiveClass(blockType === 'h3')}`}
+            onClick={() => {
+              formatHeading('h3')
+            }}
+          >
+            <i className="icon h3" />
+            <span className="text">Heading 3</span>
+          </DropDownItem>
+          <DropDownItem
+            className={`item ${dropDownActiveClass(blockType === 'h4')}`}
+            onClick={() => {
+              formatHeading('h4')
+            }}
+          >
+            <i className="icon h4" />
+            <span className="text">Heading 4</span>
+          </DropDownItem>
+        </>
+      )}
+      {formats.includes('bullet') && (
         <>
           <DropDownItem
             className={`item ${dropDownActiveClass(blockType === 'bullet')}`}
@@ -303,7 +358,7 @@ function BlockFormatDropDown({
         </>
       )}
 
-      {hasCheckList && (
+      {formats.includes('check') && (
         <DropDownItem
           className={`item ${dropDownActiveClass(blockType === 'check')}`}
           onClick={formatCheckList}
@@ -313,14 +368,16 @@ function BlockFormatDropDown({
         </DropDownItem>
       )}
 
-      <DropDownItem
-        className={`item ${dropDownActiveClass(blockType === 'quote')}`}
-        onClick={formatQuote}
-      >
-        <i className="icon quote" />
-        <span className="text">Quote</span>
-      </DropDownItem>
-      {hasCodeHighlight && (
+      {formats.includes('quote') && (
+        <DropDownItem
+          className={`item ${dropDownActiveClass(blockType === 'quote')}`}
+          onClick={formatQuote}
+        >
+          <i className="icon quote" />
+          <span className="text">Quote</span>
+        </DropDownItem>
+      )}
+      {formats.includes('code') && (
         <DropDownItem
           className={`item ${dropDownActiveClass(blockType === 'code')}`}
           onClick={formatCode}
@@ -373,10 +430,16 @@ export function ToolbarPlugin(): React.JSX.Element {
   const {
     uuid,
     config: {
-      options: { textAlignment, undoRedo, textStyle, inlineCode, markdownToggle },
+      controls: { textAlignment, undoRedo, blockFormat, inlineCode, markdownToggle },
     },
   } = useEditorConfig()
   const { isMarkdown, toggleMarkdown } = useMarkdownToggle()
+  // Resolved after mount so the first client render matches the server;
+  // reading the platform during render mismatches on hydration.
+  const isApple = useIsApplePlatform()
+  // Source mode needs a CodeNode to hold the Markdown text, so the
+  // control follows that capability as well as the preference.
+  const canToggleMarkdown = canUseMarkdownSourceMode(editor)
   // const { openModal } = usePayloadModal()
   // const editDepth = useEditDepth()
 
@@ -600,7 +663,7 @@ export function ToolbarPlugin(): React.JSX.Element {
             onClick={() => {
               activeEditor.dispatchCommand(UNDO_COMMAND, undefined)
             }}
-            title={IS_APPLE ? 'Undo (⌘Z)' : 'Undo (Ctrl+Z)'}
+            title={isApple ? 'Undo (⌘Z)' : 'Undo (Ctrl+Z)'}
             type="button"
             className="toolbar-item spaced"
             aria-label="Undo"
@@ -612,7 +675,7 @@ export function ToolbarPlugin(): React.JSX.Element {
             onClick={() => {
               activeEditor.dispatchCommand(REDO_COMMAND, undefined)
             }}
-            title={IS_APPLE ? 'Redo (⌘Y)' : 'Redo (Ctrl+Y)'}
+            title={isApple ? 'Redo (⌘Y)' : 'Redo (Ctrl+Y)'}
             type="button"
             className="toolbar-item"
             aria-label="Redo"
@@ -625,7 +688,7 @@ export function ToolbarPlugin(): React.JSX.Element {
 
       {blockType in blockTypeToBlockName && activeEditor === editor && (
         <>
-          {textStyle && (
+          {blockFormat && (
             <>
               <BlockFormatDropDown
                 disabled={!isEditable}
@@ -736,9 +799,9 @@ export function ToolbarPlugin(): React.JSX.Element {
               activeEditor.dispatchCommand(FORMAT_TEXT_COMMAND, 'bold')
             }}
             className={`toolbar-item spaced ${isBold ? 'active' : ''}`}
-            title={IS_APPLE ? 'Bold (⌘B)' : 'Bold (Ctrl+B)'}
+            title={isApple ? 'Bold (⌘B)' : 'Bold (Ctrl+B)'}
             type="button"
-            aria-label={`Format text as bold. Shortcut: ${IS_APPLE ? '⌘B' : 'Ctrl+B'}`}
+            aria-label={`Format text as bold. Shortcut: ${isApple ? '⌘B' : 'Ctrl+B'}`}
           >
             <i className="format bold" />
           </button>
@@ -748,9 +811,9 @@ export function ToolbarPlugin(): React.JSX.Element {
               activeEditor.dispatchCommand(FORMAT_TEXT_COMMAND, 'italic')
             }}
             className={`toolbar-item spaced ${isItalic ? 'active' : ''}`}
-            title={IS_APPLE ? 'Italic (⌘I)' : 'Italic (Ctrl+I)'}
+            title={isApple ? 'Italic (⌘I)' : 'Italic (Ctrl+I)'}
             type="button"
-            aria-label={`Format text as italics. Shortcut: ${IS_APPLE ? '⌘I' : 'Ctrl+I'}`}
+            aria-label={`Format text as italics. Shortcut: ${isApple ? '⌘I' : 'Ctrl+I'}`}
           >
             <i className="format italic" />
           </button>
@@ -760,9 +823,9 @@ export function ToolbarPlugin(): React.JSX.Element {
               activeEditor.dispatchCommand(FORMAT_TEXT_COMMAND, 'underline')
             }}
             className={`toolbar-item spaced ${isUnderline ? 'active' : ''}`}
-            title={IS_APPLE ? 'Underline (⌘U)' : 'Underline (Ctrl+U)'}
+            title={isApple ? 'Underline (⌘U)' : 'Underline (Ctrl+U)'}
             type="button"
-            aria-label={`Format text to underlined. Shortcut: ${IS_APPLE ? '⌘U' : 'Ctrl+U'}`}
+            aria-label={`Format text to underlined. Shortcut: ${isApple ? '⌘U' : 'Ctrl+U'}`}
           >
             <i className="format underline" />
           </button>
@@ -872,7 +935,7 @@ export function ToolbarPlugin(): React.JSX.Element {
         ))}
       </ToolbarActiveEditorProvider>
 
-      {markdownToggle && (
+      {markdownToggle && canToggleMarkdown && (
         <>
           <Divider />
           <button

package/src/field/test-support/build-test-editor.test.tsx

@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest'
+
+import { buildFullEditor, buildRestrictedEditor, parseHtmlToTypes } from './build-test-editor'
+
+describe('test harness', () => {
+  it('builds the full default extension set', () => {
+    const editor = buildFullEditor()
+    expect(parseHtmlToTypes(editor, '<p>hello</p>').types).toEqual(['paragraph'])
+    editor.dispose()
+  })
+
+  it('builds a restricted editor', () => {
+    const editor = buildRestrictedEditor()
+    expect(parseHtmlToTypes(editor, '<p>hello</p>').types).toEqual(['paragraph'])
+    editor.dispose()
+  })
+})

package/src/field/test-support/build-test-editor.ts

@@ -0,0 +1,99 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * Shared editor builders for jsdom tests.
+ *
+ * These compose a root extension directly rather than rendering
+ * `EditorContext`, which keeps capability tests fast and free of React.
+ * That also means they do NOT exercise the shipped component: the
+ * production root extension lives in `editor-context.tsx`, and a
+ * regression there is caught by `editor-context.regression.test.tsx`,
+ * not here.
+ */
+
+import { buildEditorFromExtensions } from '@lexical/extension'
+import { $generateNodesFromDOM } from '@lexical/html'
+import { ReactPluginHostExtension } from '@lexical/react/ReactPluginHostExtension'
+import { defineExtension, type LexicalEditor } from 'lexical'
+
+import { builtInExtensions } from '../config/built-in-extension-names'
+import { defaultExtensionsList } from '../config/default-extensions'
+import { rootDependencies } from '../config/root-dependencies'
+import type { ExtensionsList } from '../config/extensions-list'
+
+const NAMESPACE = 'LexicalRichText'
+
+/**
+ * `ReactPluginHostExtension` is required, not optional: several default
+ * extensions host React decorators and `buildEditorFromExtensions`
+ * throws "No ReactProviderExtension detected" without it.
+ */
+function build(extensions: ExtensionsList) {
+  return buildEditorFromExtensions(
+    defineExtension({
+      name: '[test-root]',
+      namespace: NAMESPACE,
+      // Through the same seam the live editor uses, so these builders
+      // mirror production rather than flattering it.
+      // biome-ignore lint/suspicious/noExplicitAny: extension arguments are heterogeneous by design
+      dependencies: [ReactPluginHostExtension, ...rootDependencies(extensions)] as any,
+    })
+  )
+}
+
+/** Every default extension, as a production editor would have them. */
+export function buildFullEditor() {
+  return build(defaultExtensionsList())
+}
+
+/**
+ * The defaults minus the named extensions. Defaults to removing every
+ * Byline built-in plus the upstream list extensions — the "minimal
+ * editor" a downstream site builds when it strips a field back.
+ */
+export function buildRestrictedEditor(removals?: string[]) {
+  const names = removals ?? [
+    ...Object.values(builtInExtensions),
+    '@lexical/list/List',
+    '@lexical/list/CheckList',
+  ]
+  const list = defaultExtensionsList()
+  for (const name of names) list.remove(name)
+  return build(list)
+}
+
+/**
+ * Parse `html` through the legacy `$generateNodesFromDOM` path — the one
+ * a clipboard paste actually uses — and report what the editor made of
+ * it. Assertions are on node types and text, never on markup.
+ *
+ * Scope: this inspects the imported nodes BEFORE insertion, so it
+ * evidences HTML conversion only. Real clipboard insertion — the
+ * `application/x-lexical-editor` branch, its fallthrough, and what
+ * survives `$insertGeneratedNodes` — is covered separately by the
+ * clipboard-equivalence tests.
+ */
+export function parseHtmlToTypes(
+  editor: LexicalEditor,
+  html: string
+): { types: string[]; text: string } {
+  const dom = new DOMParser().parseFromString(html, 'text/html')
+  let result = { types: [] as string[], text: '' }
+  editor.update(
+    () => {
+      const nodes = $generateNodesFromDOM(editor, dom)
+      result = {
+        types: nodes.map((node) => node.getType()),
+        text: nodes.map((node) => node.getTextContent()).join('|'),
+      }
+    },
+    { discrete: true }
+  )
+  return result
+}

package/src/field/test-support/capture-editor.tsx

@@ -0,0 +1,20 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext'
+import type { LexicalEditor } from 'lexical'
+
+/**
+ * Hands the composer's editor to a test. Must be rendered as a child of
+ * `EditorContext` so it sits inside the composer's React tree.
+ */
+export function CaptureEditor({ onEditor }: { onEditor: (editor: LexicalEditor) => void }): null {
+  const [editor] = useLexicalComposerContext()
+  onEditor(editor)
+  return null
+}

package/src/field/test-support/frame-control.ts

@@ -0,0 +1,91 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * Deterministic control over the frames and idle callbacks the editor
+ * defers work through.
+ *
+ * Two pieces of editor behaviour are scheduled rather than immediate,
+ * and a test that waits a fixed number of milliseconds for either is
+ * guessing:
+ *
+ *  - `ApplyValuePlugin` captures its normalization baseline after a
+ *    microtask and **two** animation frames.
+ *  - `editor-component` defers change emission through
+ *    `requestIdleCallback`, which jsdom does not implement at all — so
+ *    without a shim it takes a synchronous branch and an entire class of
+ *    ordering bug becomes invisible.
+ *
+ * Installing controllable versions of both makes the ordering explicit:
+ * a test says when a frame happens, rather than sleeping and hoping.
+ */
+
+interface FrameControl {
+  /** Run pending animation-frame callbacks, `generations` deep. */
+  flushFrames: (generations?: number) => Promise<void>
+  /** Run every pending idle callback. */
+  flushIdle: () => void
+  /** How many idle callbacks are scheduled but not yet run. */
+  pendingIdle: () => number
+  /** Settle the normalization baseline: a microtask, then two frames. */
+  settleBaseline: () => Promise<void>
+  /** Restore the original globals. */
+  restore: () => void
+}
+
+export function installFrameControl(): FrameControl {
+  const frameCallbacks: FrameRequestCallback[] = []
+  const idleCallbacks: Array<() => void> = []
+
+  const originalRaf = globalThis.requestAnimationFrame
+  const originalCaf = globalThis.cancelAnimationFrame
+  // biome-ignore lint/suspicious/noExplicitAny: jsdom does not implement these
+  const originalRic = (globalThis as any).requestIdleCallback
+  // biome-ignore lint/suspicious/noExplicitAny: jsdom does not implement these
+  const originalCic = (globalThis as any).cancelIdleCallback
+
+  globalThis.requestAnimationFrame = ((callback: FrameRequestCallback) => {
+    frameCallbacks.push(callback)
+    return frameCallbacks.length
+  }) as typeof requestAnimationFrame
+  globalThis.cancelAnimationFrame = (() => {}) as typeof cancelAnimationFrame
+  // biome-ignore lint/suspicious/noExplicitAny: shimming a missing jsdom API
+  ;(globalThis as any).requestIdleCallback = (callback: () => void) => {
+    idleCallbacks.push(callback)
+    return idleCallbacks.length
+  }
+  // biome-ignore lint/suspicious/noExplicitAny: shimming a missing jsdom API
+  ;(globalThis as any).cancelIdleCallback = () => {}
+
+  const flushFrames = async (generations = 1): Promise<void> => {
+    for (let generation = 0; generation < generations; generation++) {
+      // Drain microtasks first: the plugin schedules its first frame
+      // from inside `queueMicrotask`.
+      await Promise.resolve()
+      for (const callback of frameCallbacks.splice(0)) callback(performance.now())
+    }
+    await Promise.resolve()
+  }
+
+  return {
+    flushFrames,
+    flushIdle: () => {
+      for (const callback of idleCallbacks.splice(0)) callback()
+    },
+    pendingIdle: () => idleCallbacks.length,
+    settleBaseline: () => flushFrames(2),
+    restore: () => {
+      globalThis.requestAnimationFrame = originalRaf
+      globalThis.cancelAnimationFrame = originalCaf
+      // biome-ignore lint/suspicious/noExplicitAny: restoring a shimmed API
+      ;(globalThis as any).requestIdleCallback = originalRic
+      // biome-ignore lint/suspicious/noExplicitAny: restoring a shimmed API
+      ;(globalThis as any).cancelIdleCallback = originalCic
+    },
+  }
+}

package/src/field/test-support/jsdom-setup.ts

@@ -0,0 +1,41 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * jsdom gaps that the editor's React tree depends on.
+ *
+ * Mounting the real `EditorContext` pulls in components that query
+ * media features and observe element size; jsdom implements neither, so
+ * they are stubbed here rather than mocked per-test.
+ */
+
+if (typeof window !== 'undefined') {
+  if (typeof window.matchMedia !== 'function') {
+    Object.defineProperty(window, 'matchMedia', {
+      writable: true,
+      value: (query: string) => ({
+        matches: false,
+        media: query,
+        onchange: null,
+        addListener: () => {},
+        removeListener: () => {},
+        addEventListener: () => {},
+        removeEventListener: () => {},
+        dispatchEvent: () => false,
+      }),
+    })
+  }
+
+  if (typeof globalThis.ResizeObserver === 'undefined') {
+    globalThis.ResizeObserver = class {
+      observe(): void {}
+      unobserve(): void {}
+      disconnect(): void {}
+    } as unknown as typeof ResizeObserver
+  }
+}

package/src/index.ts

@@ -42,7 +42,9 @@ export {
   selectToolbarItems,
 } from './field/extensions/byline-toolbar'
 export { CodeHighlightExtension } from './field/extensions/code-highlight/code-highlight-extension'
+export { CoreNodesExtension } from './field/extensions/core-nodes/core-nodes-extension'
 export { FloatingTextFormatExtension } from './field/extensions/floating-text-format/floating-text-format-extension'
+export { HeadingExtension } from './field/extensions/heading/heading-extension'
 export { HorizontalRuleExtension } from './field/extensions/horizontal-rule/horizontal-rule-extension'
 export {
   type InlineImageConfig,
@@ -50,10 +52,13 @@ export {
 } from './field/extensions/inline-image/inline-image-extension'
 export { LayoutExtension } from './field/extensions/layout/layout-extension'
 export { AutoLinkExtension, LinkExtension } from './field/extensions/link'
+export { QuoteExtension } from './field/extensions/quote/quote-extension'
 export { TableExtension } from './field/extensions/table/table-extension'
 export { VimeoExtension } from './field/extensions/vimeo/vimeo-extension'
 export { YouTubeExtension } from './field/extensions/youtube/youtube-extension'
-export { Nodes } from './field/nodes'
+// Not a registration list: the vocabulary of node classes Byline can
+// read, used by normalization and the capability manifest.
+export { READABLE_NODES } from './field/nodes'
 // Hook for extensions that contribute toolbar items via
 // BylineToolbarExtension and need the active editor for command dispatch.
 export {
@@ -62,6 +67,11 @@ export {
 } from './field/plugins/toolbar-plugin/toolbar-active-editor'
 export { lexicalEditor } from './lexical-editor'
 export { RichTextField } from './richtext-field'
+// Pre-upgrade capability scan. `capabilitiesFor` / `capabilitiesFromEditor`
+// need a DOM and run in a browser or jsdom; `scanDocument` is pure and runs
+// anywhere, which is why the manifest travels between them as a file.
+export { buildManifest, capabilitiesFor, capabilitiesFromEditor } from './scan/capability-manifest'
+export { scanDocument, summarise } from './scan/scan-documents'
 export { createEmptyEditorState } from './validate/createEmptyEditorState'
 export { hasText } from './validate/hasText'
 export type { EditorConfig, EditorSettings, EditorSettingsOverride } from './field/config/types'
@@ -71,3 +81,4 @@ export type {
   SerializedInlineImageNode,
 } from './field/extensions/inline-image/node-types'
 export type { DocumentRelation } from './field/nodes/document-relation'
+export type { CapabilityManifest, FieldCapabilities, ScanFinding } from './scan/types'