@voithos-labs/aragonite 0.10.3 → 0.10.7

package/dist/components/blocks/widget-portal.d.ts

@@ -6,7 +6,7 @@
  */
 import type { AnyInlineKind, InlineNode } from '../../core/nodes';
 import type { DocumentView } from '../../core/node-views';
-import type { PresentationMode } from '../../presentation-mode';
+import type { Reading } from '../../schema/reading';
 export interface WidgetPoolAdapter<H> {
     /** Build one instance, or null when it cannot be built (a caught mount throw). */
     create(kind: AnyInlineKind, inline: InlineNode, source: string): H | null;
@@ -14,41 +14,32 @@ export interface WidgetPoolAdapter<H> {
     element(handle: H): HTMLElement;
 }
 export interface WidgetPool {
-    /**
-     * Adopt the oldest un-adopted live instance for the key, marking it adopted this
-     * pass; else build a new one. Render-pass only — every acquire sits inside a
-     * beginPass/sweep bracket. Key-only lookup cannot distinguish byte-identical
-     * duplicates, so an out-of-pass caller holding a specific element must restore it.
-     */
+    /** Adopts the oldest unadopted instance for the key, else builds one; call only inside a
+     *  beginPass/sweep bracket. Identical sources share a key, so a caller holding one restores it. */
     acquire(kind: AnyInlineKind, inline: InlineNode, source: string): HTMLElement | null;
     /** Open a rebuild pass: un-adopt every instance so this pass re-earns them. */
     beginPass(): void;
     /** Close a rebuild pass: destroy every instance not adopted in it. */
     sweep(): void;
-    /** Destroy everything — the block is unmounting. */
+    /** Destroy everything, because the block is unmounting. */
     dispose(): void;
 }
 export declare function createWidgetPool<H>(adapter: WidgetPoolAdapter<H>): WidgetPool;
-/** The live channels a mounted widget reads beside its frozen `{ inline, source }`
- *  snapshot. Every member is optional so a bare harness can mount without a shell. */
+/** The live channels a mounted widget reads beside its frozen `{ inline, source }` snapshot. All
+ *  required, so no widget falls back to a value the editor does not hold. */
 export interface SvelteWidgetPoolDeps {
-    /** A widget component's synchronous mount throw goes here (the editor's `error`
-     *  channel). Absent leaves the caller falling back to the raw span silently. */
-    reportError?: (error: unknown) => void;
-    getPresentationMode?: () => PresentationMode;
-    /** The editor's theme name — the mode read's sibling, for a widget whose body an
-     *  engine paints (its own colors, unreachable from CSS) rather than CSS styles. */
-    getTheme?: () => string;
-    getDocument?: () => DocumentView | undefined;
-    getContentVersion?: () => number;
-    /** The editor's navigation door, for a widget whose gesture jumps elsewhere in the
-     *  document. Absent in a bare harness. */
-    navigateTo?: (path: number[], offset?: number) => Promise<boolean>;
+    /** A widget component's synchronous mount throw goes here (the editor's `error` channel). */
+    reportError: (error: unknown) => void;
+    /** The editor's theme name, for a widget that draws its own colors where CSS cannot reach. */
+    getTheme: () => string;
+    getDocument: () => DocumentView | undefined;
+    getContentVersion: () => number;
+    /** The editor's navigation call, for a widget whose gesture jumps elsewhere in the document. */
+    navigateTo: (path: number[], offset?: number) => Promise<boolean>;
+    /** How the editor reads its bytes: a widget kind whose plugin it left out mounts nothing, and a
+     *  mounted widget reads the mode and parses inline content through it. */
+    reading: Reading;
 }
-/**
- * The pool wired to Svelte mounting. A synchronous mount throw is caught, reported and surfaced as
- * null so the caller falls back to the raw span. The getters ride ALONGSIDE the frozen
- * `{ inline, source }` snapshot as live props: reuse keys on `${kind} ${source}`, so an instance
- * outlives a mode flip or an edit elsewhere that a frozen value would not.
- */
-export declare function createSvelteWidgetPool(deps?: SvelteWidgetPoolDeps): WidgetPool;
+/** A mount throw is reported and returns null, so the caller falls back to the raw span. The
+ *  getters are live props beside the frozen snapshot, since a pooled instance outlives a mode switch. */
+export declare function createSvelteWidgetPool(deps: SvelteWidgetPoolDeps): WidgetPool;

package/dist/components/blocks/widget-portal.js

@@ -5,6 +5,7 @@
  * `${kind} ${source}`, and `mount`/`unmount` from 'svelte' stay contained here.
  */
 import { mount, unmount } from 'svelte';
+import { inlineReaderFor } from '../../core/inline';
 import { getInlineWidgetComponent } from '../../core/inline/inline-widgets';
 import { tracePoolPass } from '../../debug/interaction-trace';
 import { assertInvariant } from '../../assert';
@@ -14,7 +15,7 @@ export function createWidgetPool(adapter) {
     // two entries in one bucket, each adopted at most once per pass.
     const buckets = new Map();
     // The acquire bracket (see WidgetPool.acquire) held as explicit state so a
-    // violation fires at this seam instead of surfacing as a widget leak (G1.25).
+    // mistake fails here instead of showing up later as a leaked widget (G1.25).
     let passOpen = false;
     // Per-pass adopt/build tallies for the interaction trace, recorded at sweep.
     let passAdopt = 0;
@@ -38,7 +39,7 @@ export function createWidgetPool(adapter) {
             reused.adopted = true;
             passAdopt++;
             // Source and rendered body are identical by key; only the widget's position
-            // may have shifted, so re-stamp the offsets cursor/selection reads.
+            // may have shifted, so write the offsets the cursor and selection read again.
             const el = adapter.element(reused.handle);
             el.dataset.sourceStart = String(inline.start);
             el.dataset.sourceEnd = String(inline.end);
@@ -88,17 +89,14 @@ export function createWidgetPool(adapter) {
     }
     return { acquire, beginPass, sweep, dispose };
 }
-/**
- * The pool wired to Svelte mounting. A synchronous mount throw is caught, reported and surfaced as
- * null so the caller falls back to the raw span. The getters ride ALONGSIDE the frozen
- * `{ inline, source }` snapshot as live props: reuse keys on `${kind} ${source}`, so an instance
- * outlives a mode flip or an edit elsewhere that a frozen value would not.
- */
-export function createSvelteWidgetPool(deps = {}) {
-    const { reportError, getPresentationMode, getTheme, getDocument, getContentVersion, navigateTo } = deps;
+/** A mount throw is reported and returns null, so the caller falls back to the raw span. The
+ *  getters are live props beside the frozen snapshot, since a pooled instance outlives a mode switch. */
+export function createSvelteWidgetPool(deps) {
+    const { reportError, getTheme, getDocument, getContentVersion, navigateTo, reading } = deps;
+    const { grammar } = reading;
     return createWidgetPool({
         create(kind, inline, source) {
-            const component = getInlineWidgetComponent(kind);
+            const component = getInlineWidgetComponent(kind, grammar);
             if (!component)
                 return null;
             const wrapper = document.createElement('span');
@@ -112,17 +110,21 @@ export function createSvelteWidgetPool(deps = {}) {
                     props: {
                         inline,
                         source,
-                        getPresentationMode,
+                        getPresentationMode: reading.mode,
                         getTheme,
                         getDocument,
                         getContentVersion,
-                        navigateTo
+                        navigateTo,
+                        // A getter, so a pooled widget's reader changes with the document's definitions.
+                        get computeInlineContent() {
+                            return inlineReaderFor(reading);
+                        }
                     }
                 });
                 return { wrapper, instance };
             }
             catch (error) {
-                reportError?.(error);
+                reportError(error);
                 return null;
             }
         },

package/dist/components/built-in-blocks.d.ts

@@ -1,7 +1,6 @@
 /**
- * Built-in block component registrations, applied by an explicit `registerBuiltInBlocks()` call:
- * the `sideEffects` allowlist names dist paths and so never covers the src specifiers this
- * library imports from itself, leaving a bare side-effect import here droppable. Lives in
- * `components/` rather than `schema/` so the schema layer keeps no downstream imports.
+ * Built-in block component registrations, run by an explicit `registerBuiltInBlocks()` call: a
+ * side-effect import could be dropped by a bundler, since `sideEffects` names only dist paths.
+ * Lives in `components/` so `schema/` imports nothing downstream.
  */
 export declare function registerBuiltInBlocks(): void;

package/dist/components/built-in-blocks.js

@@ -1,10 +1,10 @@
 /**
- * Built-in block component registrations, applied by an explicit `registerBuiltInBlocks()` call:
- * the `sideEffects` allowlist names dist paths and so never covers the src specifiers this
- * library imports from itself, leaving a bare side-effect import here droppable. Lives in
- * `components/` rather than `schema/` so the schema layer keeps no downstream imports.
+ * Built-in block component registrations, run by an explicit `registerBuiltInBlocks()` call: a
+ * side-effect import could be dropped by a bundler, since `sideEffects` names only dist paths.
+ * Lives in `components/` so `schema/` imports nothing downstream.
  */
 import { metadataOf } from '../core/nodes';
+import { shownKind } from '../core/parsers/heading';
 import { defineBlockComponent, registerBlockComponent } from '../schema/block-component-registry';
 import { augmentBuiltin } from '../schema/block-kind-descriptor';
 import { registerBuiltInDescriptors } from '../schema/built-in-descriptors';
@@ -24,20 +24,22 @@ import { tableCellPasteSurface } from './blocks/table/table-cell-paste';
 import { tableCaretAtPoint } from './blocks/table/table-caret-at-point';
 import { tableDragHitTest } from './blocks/table/table-drag-hit-test';
 function headingExtraProps(node) {
+    if (shownKind(node) === 'paragraph')
+        return { blockClass: 'paragraph-block' };
     const level = metadataOf(node, 'heading')?.level ?? 1;
     return { blockClass: `heading-${level}` };
 }
 const textAsRawBlock = defineBlockComponent(TextEditableBlock, () => ({
     blockClass: 'raw-block'
 }));
-// Idempotence guard, not a registry bypass: a dev-server re-eval resets it so
-// the register-once dev valve still replaces.
+// Stops a second call doing the work twice, without bypassing the registry: a
+// dev-server re-evaluation resets it, so re-registering in dev still replaces.
 let registered = false;
 export function registerBuiltInBlocks() {
     if (registered)
         return;
     registered = true;
-    // Descriptors first — augmentBuiltin('table') below needs `table` registered.
+    // Descriptors first: augmentBuiltin('table') below needs `table` registered.
     registerBuiltInDescriptors();
     registerBlockComponent('paragraph', defineBlockComponent(TextEditableBlock, () => ({ blockClass: 'paragraph-block' })));
     registerBlockComponent('heading', defineBlockComponent(TextEditableBlock, headingExtraProps));
@@ -47,21 +49,19 @@ export function registerBuiltInBlocks() {
     registerBlockComponent('blockquote', defineBlockComponent(BlockquoteBlock));
     registerBlockComponent('list', defineBlockComponent(ListBlock));
     registerBlockComponent('table', defineBlockComponent(TableBlock));
-    // Raw-editable fallback for kinds with no rendered surface. tableRow/tableCell
-    // render inside TableBlock; these catch only orphans that reach BlockHost directly.
+    // Plain editable fallback for kinds with no rendered component. tableRow and tableCell
+    // render inside TableBlock; these catch only strays that reach BlockHost directly.
     registerBlockComponent('indentedCode', textAsRawBlock);
     registerBlockComponent('htmlBlock', textAsRawBlock);
     registerBlockComponent('linkReferenceDefinition', textAsRawBlock);
     registerBlockComponent('tableRow', textAsRawBlock);
     registerBlockComponent('tableCell', textAsRawBlock);
     registerBlockComponent('unrecognized', textAsRawBlock);
-    // tableCell is the one supportsInline kind with bespoke paste semantics, so it
-    // registers here and the default loop in paste/hooks.ts skips it — running both
-    // would let ordering silently revert cell paste to the plain inline default.
+    // The default loop in `paste/hooks.ts` skips `tableCell`, so registration order cannot
+    // revert cell paste to the plain inline default.
     registerPasteSurface(tableCellPasteSurface);
-    // Table owns cell addressing, so it registers both point→cell hooks through the
-    // descriptor registry rather than the selection layer importing the component.
-    // Two hooks: a drag needs the exact hit and its decline, a caret the nearest cell.
+    // Table owns cell addressing: a drag needs the exact hit or a refusal, a caret the nearest
+    // cell, and the selection code reaches both through the descriptor.
     augmentBuiltin('table', {
         foreignDragHitTest: tableDragHitTest,
         caretTargetAtPoint: tableCaretAtPoint
@@ -69,9 +69,8 @@ export function registerBuiltInBlocks() {
     // Image resize is editor-layer behavior, so the core image kind stays data-only
     // and gains its selected-key handler here, where the render layer is reachable.
     augmentInlineWidgetKind('image', { onSelectedKey: imageWidgetOnSelectedKey });
-    // The split rebalancer and the join-seam cleaner need the inline parser and the render path,
-    // neither of which `tree-operations` may import, so the policy table holds the slots and this
-    // layer fills them.
+    // These need the inline parser and render path, which `tree-operations` may not import, so
+    // they are filled in here.
     registerLiveSplitRebalancer(rebalanceLiveSplit);
     registerLiveJoinSeamCleaner(cleanLiveJoinSeam);
 }

package/dist/components/drag-handle.d.ts

@@ -1,35 +1,18 @@
 /**
- * The block drag handle's two policies, kept out of the components that render it: which
- * blocks carry one, and where its grip sits.
- *
- * Presence: prose carries none. A paragraph, a heading, a quote and the note cards read as
- * text on the page, and a grip beside every one of them is noise; the blocks that get one are
- * the objects a reader picks up whole — pictures, code, tables, equations, diagrams, list
- * items, dividers. A gripless block is still a reorder unit: keyboard reorder moves it and a
- * dragged block still drops beside it.
+ * The block drag handle's two rules: which blocks get one (the objects a user picks up whole,
+ * never prose, as `schema/page-role.ts` tells them apart), and where it sits. A block without
+ * one still reorders by keyboard.
  */
 import type { NodeView } from '../core/node-views';
-export declare function isImageOnlyParagraph(node: NodeView): boolean;
-/**
- * A picture's grip does NOT wait for `blockDragHandles`: dragging it is the only pointer road
- * to move a picture, and unlike prose it is a discrete object a reader expects to pick up. The
- * caller still gates reading mode, which shows no affordances at all.
- */
-export declare function showsDragHandle(node: NodeView, handlesEnabled: boolean): boolean;
-/**
- * Vertical centre of the grip. A one-line block centres on its row. A taller one takes the
- * first line-height of its OWN box — not its first line of text, since a card pads above that
- * and a grip level with the first code line hangs below the card's shoulder. A declared anchor
- * SHORTER than a line is a marker to centre on instead (a wrapped task item's checkbox); a
- * taller one is a card, and the band already covers it.
- */
+import type { InlineReading } from '../core/inline/inline-cache';
+/** A picture's handle ignores `blockDragHandles`, since dragging is the only pointer way to
+ *  move one. The caller still checks reading mode. */
+export declare function showsDragHandle(node: NodeView, handlesEnabled: boolean, reading: InlineReading): boolean;
+/** A lone list item has no handle: its drag stays inside the list, with nothing to swap with. */
+export declare function showsListItemDragHandle(itemCount: number, handlesEnabled: boolean): boolean;
+/** Centres on a one-line block's row, else a marker-sized drag anchor, else the box's first
+ *  line-height, since a card pads above its first line of text. */
 export declare function dragHandleAnchorY(host: HTMLElement): number | null;
-/**
- * Svelte attachment for the handle element: places the grip once the block has laid out, and
- * again on every pointerover inside its host, so it follows edits made while hovered.
- *
- * The mount placement is what makes the grip HITTABLE where it appears: it is its own hit
- * target before any hover, so a target parked at the stylesheet's default while the grip would
- * settle elsewhere is a target the pointer misses. One rAF-batched read per handle.
- */
+/** Places the handle once the block has laid out, so it is clickable before any hover, and on
+ *  each pointerover inside its host, so it follows edits made while hovered. */
 export declare function alignDragHandle(handle: HTMLElement): (() => void) | void;

package/dist/components/drag-handle.js

@@ -1,55 +1,26 @@
 /**
- * The block drag handle's two policies, kept out of the components that render it: which
- * blocks carry one, and where its grip sits.
- *
- * Presence: prose carries none. A paragraph, a heading, a quote and the note cards read as
- * text on the page, and a grip beside every one of them is noise; the blocks that get one are
- * the objects a reader picks up whole — pictures, code, tables, equations, diagrams, list
- * items, dividers. A gripless block is still a reorder unit: keyboard reorder moves it and a
- * dragged block still drops beside it.
+ * The block drag handle's two rules: which blocks get one (the objects a user picks up whole,
+ * never prose, as `schema/page-role.ts` tells them apart), and where it sits. A block without
+ * one still reorders by keyboard.
  */
+import { isImageOnlyParagraph } from '../core/inline/picture';
+import { blockPageRole } from '../schema/page-role';
 import { BLOCK_CONTENT_SELECTOR, DRAG_ANCHOR_ATTR } from './block-content-selector';
-/**
- * Prose — the page's background and its asides — plus the list SHELL, whose own grip would
- * land in the gutter on top of its first item's and take the hit test with it. A list moves
- * an item at a time; the shell is a wrapper, not a thing to pick up.
- */
-const GRIPLESS_KINDS = new Set([
-    'paragraph',
-    'heading',
-    'blockquote',
-    'admonition',
-    'githubAlert',
-    'list'
-]);
-/**
- * A paragraph holding nothing but images is a picture in the page, not prose: it reads as a
- * block of its own and is exactly the thing a reader reaches to move. A false negative here
- * (an alt with an escaped bracket, an image beside a word) is the plain no-grip paragraph.
- */
-const IMAGE_ONLY_PARAGRAPH = /^\s*(?:!\[[^\]]*\](?:\([^)]*\)|\[[^\]]*\])\s*)+$/;
-export function isImageOnlyParagraph(node) {
-    return node.kind === 'paragraph' && IMAGE_ONLY_PARAGRAPH.test(node.raw);
-}
-/**
- * A picture's grip does NOT wait for `blockDragHandles`: dragging it is the only pointer road
- * to move a picture, and unlike prose it is a discrete object a reader expects to pick up. The
- * caller still gates reading mode, which shows no affordances at all.
- */
-export function showsDragHandle(node, handlesEnabled) {
-    if (isImageOnlyParagraph(node))
+/** A picture's handle ignores `blockDragHandles`, since dragging is the only pointer way to
+ *  move one. The caller still checks reading mode. */
+export function showsDragHandle(node, handlesEnabled, reading) {
+    if (isImageOnlyParagraph(node, reading))
         return true;
-    return handlesEnabled && !GRIPLESS_KINDS.has(node.kind);
+    return handlesEnabled && blockPageRole(node, reading) === 'object';
+}
+/** A lone list item has no handle: its drag stays inside the list, with nothing to swap with. */
+export function showsListItemDragHandle(itemCount, handlesEnabled) {
+    return handlesEnabled && itemCount > 1;
 }
 /** A box within this many line-heights holds one row of content, margins included. */
 const SINGLE_LINE = 1.5;
-/**
- * Vertical centre of the grip. A one-line block centres on its row. A taller one takes the
- * first line-height of its OWN box — not its first line of text, since a card pads above that
- * and a grip level with the first code line hangs below the card's shoulder. A declared anchor
- * SHORTER than a line is a marker to centre on instead (a wrapped task item's checkbox); a
- * taller one is a card, and the band already covers it.
- */
+/** Centres on a one-line block's row, else a marker-sized drag anchor, else the box's first
+ *  line-height, since a card pads above its first line of text. */
 export function dragHandleAnchorY(host) {
     const content = host.querySelector(BLOCK_CONTENT_SELECTOR);
     if (!content)
@@ -57,13 +28,13 @@ export function dragHandleAnchorY(host) {
     const hostRect = host.getBoundingClientRect();
     const line = lineHeightOf(content);
     const rect = paintedRect(content);
-    // A one-line block IS its own band, and the eye puts the grip level with the row rather
-    // than a hair above its middle — a list item, a task row, a rule.
+    // A one-line block is its own row, and the eye puts the handle level with it rather than
+    // a hair above the middle: a list item, a task row, a rule.
     const box = rect.height <= line * SINGLE_LINE ? rect : (markerRect(content, line) ?? bandRect(rect, line));
     if (!box || box.height === 0)
         return null;
     const y = box.top + box.height / 2 - hostRect.top;
-    // A box painting outside the host (a scrolled or offscreen region) seats nothing.
+    // A box painted outside the host (a scrolled or offscreen region) places nothing.
     return y >= 0 && y <= hostRect.height ? y : null;
 }
 function lineHeightOf(content) {
@@ -80,29 +51,20 @@ function markerRect(content, line) {
         return null;
     return rect.top - content.getBoundingClientRect().top > line ? null : rect;
 }
-/**
- * The box the band measures from: the content's own, unless it leads with an atomic widget
- * (a picture in a paragraph), whose margin would otherwise seat the grip above the picture and
- * flush with its corner.
- */
+/** The content's box, unless it starts with a non-editable inline widget whose margin would
+ *  put the handle above the picture. */
 function paintedRect(content) {
     const rect = content.getBoundingClientRect();
     const widget = content.firstElementChild?.closest('[data-inline-widget]');
     const widgetRect = widget?.getBoundingClientRect();
     return widgetRect && widgetRect.height > 0 && widgetRect.top > rect.top ? widgetRect : rect;
 }
-/** The top line-height of a box; a box shorter than a line is its own band. */
+/** The top line-height of a box; a box shorter than a line is all of it. */
 function bandRect(rect, line) {
     return new DOMRect(rect.x, rect.y, rect.width, Math.min(line, rect.height));
 }
-/**
- * Svelte attachment for the handle element: places the grip once the block has laid out, and
- * again on every pointerover inside its host, so it follows edits made while hovered.
- *
- * The mount placement is what makes the grip HITTABLE where it appears: it is its own hit
- * target before any hover, so a target parked at the stylesheet's default while the grip would
- * settle elsewhere is a target the pointer misses. One rAF-batched read per handle.
- */
+/** Places the handle once the block has laid out, so it is clickable before any hover, and on
+ *  each pointerover inside its host, so it follows edits made while hovered. */
 export function alignDragHandle(handle) {
     const host = handle.parentElement;
     if (!host)
@@ -110,7 +72,7 @@ export function alignDragHandle(handle) {
     const grip = handle.firstElementChild;
     if (!grip)
         return;
-    // Inline `top` on the grip (px from the host's top to its centre; the stylesheet's
+    // Inline `top` on the handle (pixels from the host's top to its centre; the stylesheet's
     // translateY(-50%) does the centring) overrides the stylesheet's half-line default.
     const place = () => {
         const y = dragHandleAnchorY(host);

package/dist/components/editor-built-ins.d.ts

@@ -0,0 +1 @@
+export declare function registerEditorBuiltIns(): void;

package/dist/components/editor-built-ins.js

@@ -0,0 +1,16 @@
+/**
+ * The editor's own registrations (built-in blocks, code languages, context-menu rows), run before
+ * an editor mounts. They run as no plugin, so each belongs to the editor and survives the test
+ * reset even when a plugin's setup is the first thing to reach them.
+ */
+import { registerAsCore } from '../schema/plugin-install';
+import { registerBuiltInBlocks } from './built-in-blocks';
+import { bootstrapCodeLanguages } from './blocks/code/code-bootstrap';
+import { registerDefaultContextActions } from './menu/default-context-actions';
+export function registerEditorBuiltIns() {
+    registerAsCore(() => {
+        registerBuiltInBlocks();
+        bootstrapCodeLanguages();
+        registerDefaultContextActions();
+    });
+}

package/dist/components/editor-root-clipboard.d.ts

@@ -1,8 +1,8 @@
 /**
- * Editor-root clipboard routing: copy/cut/paste for an event that reached no block surface. A
- * selection whose block hosts no text position leaves the native selection empty, so Chromium
- * dispatches at `document.body`, where no per-block binding sees it. Reading-mode gates live at
- * the arms each route calls into, not here.
+ * Editor-root clipboard routing: copy, cut and paste for an event that reached no block. A
+ * selection whose block holds no text position leaves the native selection empty, so Chromium
+ * dispatches at `document.body`, where no per-block listener sees it. The reading-mode checks
+ * live in the handlers each route calls into, not here.
  */
 import type { BlockComponent } from '../block-component';
 import type { DocumentGetter, PasteImageHook } from '../editor-keys';
@@ -13,8 +13,8 @@ export interface EditorRootClipboardDeps {
     selection: SelectionState;
     getDoc: DocumentGetter;
     crossBlock: CrossBlockHandlers;
-    /** Required-nullable so this seam cannot silently skip the arm the block surfaces
-     *  run; `undefined` = no hook. */
+    /** Required but nullable, so this route cannot silently skip the image handling the
+     *  blocks do; `undefined` means no hook. */
     onPasteImage: PasteImageHook | undefined;
     events: EditorEvents;
     /** The block owning the selected inline widget, or null when none is selected. */

package/dist/components/editor-root-clipboard.js

@@ -1,8 +1,8 @@
 /**
- * Editor-root clipboard routing: copy/cut/paste for an event that reached no block surface. A
- * selection whose block hosts no text position leaves the native selection empty, so Chromium
- * dispatches at `document.body`, where no per-block binding sees it. Reading-mode gates live at
- * the arms each route calls into, not here.
+ * Editor-root clipboard routing: copy, cut and paste for an event that reached no block. A
+ * selection whose block holds no text position leaves the native selection empty, so Chromium
+ * dispatches at `document.body`, where no per-block listener sees it. The reading-mode checks
+ * live in the handlers each route calls into, not here.
  */
 import { claimsBodyChord } from '../active-editor';
 import { emitClipboardError } from '../editor-events';
@@ -19,23 +19,15 @@ export function createEditorRootClipboard(deps) {
         events: deps.events,
         crossBlock: deps.crossBlock
     });
-    /**
-     * The event landed nowhere: on this root, or on the body via the retarget above.
-     * Deliberately NOT "inside the root but not a block" — the search input and a
-     * host's header field are both inside and own their own clipboard. The body arm is
-     * claimant-scoped because the listener sees every editor on the page.
-     */
+    /** On this root, or on the body with this instance holding the chord; the search input and a
+     *  header field sit inside the root and keep their own clipboard. */
     function landedNowhere(root, target) {
         if (target === root)
             return true;
         return (target === null || target === root.ownerDocument.body) && claimsBodyChord(root);
     }
-    /**
-     * Who owns an event that reached no block surface. `defaultPrevented` is the block surfaces'
-     * receipt: every arm of their shared clipboard skeleton prevents before it writes, and the one
-     * arm that declines to native is a collapsed cell caret, which is neither state below. Order
-     * decides nothing — widget selection and cross-block selection clear each other.
-     */
+    /** A block marks an event it handled with `defaultPrevented`. The two states cannot coexist,
+     *  so their order does not matter. */
     function targetOf(event, root) {
         if (event.defaultPrevented)
             return null;
@@ -75,28 +67,25 @@ export function createEditorRootClipboard(deps) {
                 void paste(event);
         }
     };
-    /**
-     * The image arm first, exactly as a block surface orders it: the root reaches this
-     * seam for a pure-image paste whenever the focus endpoint hosts no caret, and going
-     * straight to the cross-block arm discarded it for want of any `text/plain`.
-     */
+    /** Images first, as a block does: an image-only paste has no `text/plain` for the
+     *  cross-block branch to use. */
     async function paste(event) {
-        // Read the range synchronously with the event, while the cross-block arm still
-        // guarantees a selection — below the await, a read could only report nothing.
+        // Read the range synchronously with the event, while the cross-block handling still
+        // guarantees a selection: below the await, a read could only report nothing.
         const rangeStartPath = deps.selection.start?.path.slice();
         const images = imageArm.filesOf(event.clipboardData);
         if (images.length === 0) {
             await deps.crossBlock.handlePaste(event);
             return;
         }
-        // Prevent before awaiting the hook, as the surface skeleton does: the browser's
-        // own paste would otherwise fire during the import and inject DOM the CST never sees.
+        // Prevent before awaiting the hook, as a block does: the browser's own paste would
+        // otherwise fire during the import and inject DOM the CST never sees.
         event.preventDefault();
         const markdown = await imageArm.run(event, images);
         if (markdown === null)
             return;
-        // The selection collapsed mid-import, leaving an imported asset and no caret —
-        // the one landing this seam cannot supply, having no block surface to fall back on.
+        // The selection collapsed mid-import, leaving an imported asset and no caret: the one
+        // thing this route cannot supply, having no block to fall back on.
         emitClipboardError(deps.events, {
             error: new Error('imported image had no insertion point at the editor root; nothing inserted'),
             ...(rangeStartPath ? { path: rangeStartPath } : {})

package/dist/components/editor-root-document-swap.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The `source` prop's whole-document replacement. Every piece of per-document state resets here
+ * in one fixed order, so a swap cannot skip a step.
+ */
+import type { Document } from '../core/nodes';
+import type { GrammarView } from '../schema/block-openers';
+import { type LinkReferenceResolver } from '../core/inline/link-reference-resolver';
+import type { CaretMemory } from '../cursor/caret-memory';
+import type { LayoutState } from '../reactivity/layout-state.svelte';
+import type { SelectionState } from '../selection/selection-state.svelte';
+import type { UndoManager } from '../undo/types';
+import type { EditorEvents } from '../editor-events';
+import type { WidgetSelectionState } from './image/widget-selection-state.svelte';
+export interface ParsedDocument {
+    doc: Document;
+    resolver: LinkReferenceResolver;
+    signature: string;
+}
+/** The parse every document goes through, at mount and at each swap, in the editor's grammar. */
+export declare function initDocument(source: string, grammar: GrammarView): ParsedDocument;
+export interface DocumentSwapDeps {
+    grammar: GrammarView;
+    /** A pending typing batch belongs to the outgoing document, so it flushes while its path
+     *  still resolves; left running, the timer would apply note A's path to note B. */
+    flushDebouncedCheckpoint(): void;
+    /** Called before the tree changes, so a caret landing still waiting gives up. */
+    noteTreeSwap(): void;
+    /** Writes the tree into the `$state` root and re-keys its blocks. */
+    adoptDocument(doc: Document): void;
+    bumpContentVersion(): void;
+    clearBlockRefs(): void;
+    layout: Pick<LayoutState, 'forgetMeasuredHeights'>;
+    undoManager: Pick<UndoManager, 'clear'>;
+    caretMemory: Pick<CaretMemory, 'forget'>;
+    /** Every menu Editor owns acts on a block or bytes of the outgoing document; a block's own
+     *  menus unmount with it. Closed before the blocks unmount, which a menu may react to. */
+    closeMenus(): void;
+    widgetSelection: Pick<WidgetSelectionState, 'clear'>;
+    selection: Pick<SelectionState, 'batch' | 'clear' | 'announceSelection'>;
+    /** Unconditional: the outgoing resolver closes over the swapped-out document. */
+    adoptLinkReferences(resolver: LinkReferenceResolver, signature: string): void;
+    events: Pick<EditorEvents, 'emit'>;
+}
+export interface DocumentSwap {
+    swapTo(source: string): void;
+    /** Counts whole-document replacements, which `editEpoch` cannot tell from a keystroke. */
+    generation(): number;
+}
+export declare function createDocumentSwap(deps: DocumentSwapDeps): DocumentSwap;