@voithos-labs/aragonite 0.10.3 → 0.10.7

package/dist/editor-actions/unwrap-strategies.js

@@ -1,104 +1,99 @@
 /**
- * Unwrap strategy implementations, selected by a container's declared
- * `unwrapRole` (schema/block-kind-descriptor.ts) from the nested blockEdit
- * dispatcher.
+ * The Backspace unwrap strategies a container's declared `unwrapRole` selects, run from the
+ * container's blockEdit (`docs/design/editor.md` § Container unwrap).
  */
 import { CURSOR_END, CURSOR_START } from '../block-component';
-import { deleteNode as performDelete, unwrapFirstItemFromList, unwrapFirstChildFromQuote, liftFirstChildKeepingContainer, mergeListItemIntoPrevious, renumberOrderedList, isItemUserEmpty } from '../tree-operations';
-import { mergedElseFocusPrevious } from './merge-fallback';
-import { scopeParentOf } from './block-edit-scope';
-import { extendDocPath } from '../cursor/coordinate-spaces';
-/** Drop a user-empty item and renumber from its slot; `land` seats the caret the strategy chose. */
-async function deleteEmptyItem({ deps, state }, itemIndex, land) {
-    await deps.parent.containerEdit.commitContainer({
+import { deleteNode as performDelete, unwrapFirstItemFromList, liftFirstChild, plainQuote, sameContainer, mergeListItemIntoPrevious, renumberOrderedList, isItemUserEmpty } from '../tree-operations';
+import { removeEmptiedContainer } from './nested/emptied-container';
+import { mergedElsePrevious } from './merge-fallback';
+import { docPathFrom, extendDocPath } from '../cursor/coordinate-spaces';
+/** Drop an empty item and renumber from its index; the caret lands at `landAt`, an item of this
+ *  list after the delete, at `offset`. */
+async function deleteEmptyItem({ deps, state }, itemIndex, landAt) {
+    return deps.parent.containerEdit.commitContainer({
         containerNode: deps.node,
         path: deps.path,
         state,
         snapshot: { path: extendDocPath(deps.path, itemIndex), offset: 0 },
         mutate: (scope) => {
-            const change = performDelete(scopeParentOf(scope), itemIndex, scope.sharing);
+            const change = performDelete(scope.body, itemIndex, deps.reading.grammar, scope.sharing);
             renumberOrderedList(scope.node, itemIndex, scope.sharing);
             return change;
         },
         op: { kind: 'delete', eventPath: extendDocPath(deps.path, itemIndex) },
-        afterTick: land
+        landing: () => ({ path: extendDocPath(deps.path, landAt.item), offset: landAt.offset })
     });
 }
 // ── First-child strategies ──────────────────────────────────────────────────
-/** Rule U2 for the quote shape: the opener lives on the first line, so the lift drops it. */
+/** Lift the first child out of a quote-shaped container, whose opener goes with it (U2). */
 async function liftFirstChildDroppingOpener({ deps }) {
-    await spliceLift(deps, unwrapFirstChildFromQuote(deps.node));
+    return spliceLift(deps, liftFirstChild(deps.node, plainQuote(deps.reading.grammar)));
 }
-/** Rule U2 for a container whose syntax survives the lift: the remainder keeps its kind. */
+/** Lift the first child out of a container whose syntax survives, so the rest keeps its kind (U2). */
 async function liftFirstChildAndKeepContainer({ deps }) {
-    await spliceLift(deps, liftFirstChildKeepingContainer(deps.node));
+    return spliceLift(deps, liftFirstChild(deps.node, sameContainer(deps.reading.grammar)));
+}
+/** Leaves the tree alone: child 0 is the container's title row, and a lift would carry it out. */
+async function keepReservedChrome() {
+    return false;
 }
-/** Rule U2's declared decline: child 0 is the container's chrome, and a lift would carry it out. */
-async function keepReservedChrome() { }
 async function spliceLift(deps, replacement) {
     if (replacement.length === 0)
-        return;
-    await deps.parent.blockEdit.replaceBlock(deps.index, replacement, {
-        replacementIndex: 0,
-        offset: 0
-    });
+        return false;
+    return deps.parent.blockEdit.replaceBlock(deps.index, replacement, { replacementIndex: 0, offset: 0 }, 
+    // The caret sat in a child leaf, which an offset into the container can't name; the live
+    // read records it.
+    { snapshotOffset: 0 });
 }
-/** List first-item cascade: nested promote / empty delete / empty-sole delete-list / Rule U1. */
+/** The first list item: promote if nested, delete if empty, delete the list if it is the only
+ *  item, else unwrap its first paragraph before the list (U1). */
 async function listItemCascadeFirst(strategy) {
-    const { deps, state } = strategy;
+    const { deps } = strategy;
     const node = deps.node;
     const index = deps.index;
     if (!node.children)
-        return;
+        return false;
     if (deps.parentListContext) {
-        await deps.parentListContext.promoteNestedItem(deps.parentListContext.getContainingItemIndex(), node, 0);
-        return;
+        return deps.parentListContext.promoteNestedItem(deps.parentListContext.getContainingItemIndex(), node, 0);
     }
     const item = node.children[0];
     const firstChildEmpty = isItemUserEmpty(item);
     if (firstChildEmpty && node.children.length > 1) {
-        await deleteEmptyItem(strategy, 0, () => {
-            state.innerBlockRefs[0]?.focus(CURSOR_START);
-        });
-    }
-    else if (firstChildEmpty && node.children.length === 1) {
-        await deps.parent.blockEdit.deleteBlock(index);
-        await deps.parent.focus.moveFocus(index - 1, 'end');
-    }
-    else {
-        const replacement = unwrapFirstItemFromList(node);
-        if (replacement.length === 0)
-            return;
-        await deps.parent.blockEdit.replaceBlock(index, replacement, {
-            replacementIndex: 0,
-            offset: 0
-        });
+        return deleteEmptyItem(strategy, 0, { item: 0, offset: CURSOR_START });
     }
+    if (firstChildEmpty)
+        return removeEmptiedContainer(deps, 'Backspace');
+    const replacement = unwrapFirstItemFromList(node);
+    if (replacement.length === 0)
+        return false;
+    // The caret sat in the first item, which an offset into the list can't name; the live read
+    // records it.
+    return deps.parent.blockEdit.replaceBlock(index, replacement, { replacementIndex: 0, offset: 0 }, { snapshotOffset: 0 });
 }
 // ── Middle-child strategies ─────────────────────────────────────────────────
-/** List middle-item: empty delete+renumber, else Rule M1 merge into deepest text above. */
+/** A middle list item: delete and renumber if empty, else merge into the deepest text above (M1). */
 async function listItemCascadeMiddle(strategy, itemIndex) {
     const { deps, state } = strategy;
     const node = deps.node;
     if (!node.children)
-        return;
+        return false;
     const item = node.children[itemIndex];
     if (isItemUserEmpty(item)) {
-        await deleteEmptyItem(strategy, itemIndex, () => {
-            state.innerBlockRefs[itemIndex - 1]?.focus(CURSOR_END);
-        });
-        return;
+        return deleteEmptyItem(strategy, itemIndex, { item: itemIndex - 1, offset: CURSOR_END });
     }
-    // Rule M1: merge into the deepest visible text above. An opaque prev leaf gives
-    // the merge no target, so the tree stays put and the caret falls back.
+    // A previous leaf with no editable text gives the merge no target, so only the caret moves.
     let mergePoint = null;
-    await deps.parent.containerEdit.commitContainer({
+    const joinedAt = () => mergePoint && {
+        path: docPathFrom([...deps.path, ...mergePoint.targetPath]),
+        offset: mergePoint.offset
+    };
+    return deps.parent.containerEdit.commitContainer({
         containerNode: node,
         path: deps.path,
         state,
         snapshot: { path: extendDocPath(deps.path, itemIndex), offset: 0 },
         mutate: (scope) => {
-            const result = mergeListItemIntoPrevious(scope.node, scope.children, itemIndex, scope.sharing, deps.getPresentationMode?.(), deps.linkRef);
+            const result = mergeListItemIntoPrevious(scope.node, scope.children, itemIndex, scope.sharing, deps.reading);
             mergePoint = result?.mergePoint ?? null;
             return mergePoint ? { op: 'delete', at: itemIndex, count: 1 } : { op: 'noop' };
         },
@@ -107,15 +102,9 @@ async function listItemCascadeMiddle(strategy, itemIndex) {
             detail: { direction: 'prev' },
             eventPath: extendDocPath(deps.path, itemIndex)
         },
-        afterTick: () => {
-            const merged = mergedElseFocusPrevious(mergePoint, state.innerBlockRefs[itemIndex - 1]);
-            if (!merged)
-                return;
-            const [firstPathIdx, ...restPath] = merged.targetPath;
-            state.innerBlockRefs[firstPathIdx]?.focusByPath?.(restPath, merged.offset);
-        },
-        // A no-target merge changes nothing; discard the entry but keep afterTick,
-        // which still lands the caret.
+        landing: () => mergedElsePrevious(joinedAt(), extendDocPath(deps.path, itemIndex - 1)),
+        // A merge with no target changes nothing; discard the undo entry, and the landing still
+        // moves the caret.
         discardIfNoop: true
     });
 }

package/dist/editor-actions/whole-block-focus-surface.d.ts

@@ -1,50 +1,41 @@
 /**
- * The focus surface of a block that IS its own focus target, and the hidden editing host beside
- * it. Such a block has no editing surface of its own, so `beforeinput` and `compositionend` —
- * the only doors AltGr productions and IME composition arrive through — fire nowhere. The proxy
- * is that host. It mounts in the block's BOX, never in the declared focus element, which a
- * render swap replaces.
+ * The focus element of a block that is focused as a whole, and the hidden editing host beside
+ * it. Such a block has no editable element of its own, so `beforeinput` and `compositionend`,
+ * the only events AltGr characters and IME composition arrive through, fire nowhere. The
+ * proxy is that host. It mounts in the block's box, never in the declared focus element,
+ * which a render swap replaces.
  */
 /** The hidden host looks exactly like a plugin's own editable; this is what tells them apart. */
 export declare const WHOLE_BLOCK_INPUT_ATTR = "data-whole-block-input";
 export declare function isWholeBlockInputProxy(target: EventTarget | null): boolean;
-/**
- * A key originating in a plugin's own text-editing surface belongs to that surface, never the
- * whole-block affordances: Backspace inside an edit textarea edits text. The hidden host is
- * excluded here rather than at each gate, so a later reader cannot forget it.
- */
+/** A key pressed in a plugin's own text editor belongs to that editor (Backspace in a textarea
+ *  edits text). The hidden host is excluded here, so no caller can forget it. */
 export declare function isEditableEventTarget(target: EventTarget | null): boolean;
-/**
- * The hidden host is the block's ONE tab stop, so a declared surface that is not itself an
- * editing host leaves the tab order (editor.md § 8). Applied on every read rather than once at
- * mount: a kind's declared element is whatever its current render state supplies, and the state
- * that appears after mount would otherwise keep its stop. Inverse of `focusWholeBlockEl`, which
- * only ever MINTS focusability on a box that has none.
- */
+/** The hidden host is the block's one tab stop, so a declared element that is not an editor
+ *  leaves the tab order. Applied on every read, since a later render state supplies a new one. */
 export declare function demoteDeclaredFromTabOrder(declared: HTMLElement | null): HTMLElement | null;
-/**
- * The class guard behind `getFocusEl`: an absent declared element degrades to the
- * focusable box, never a silent no-op that strands the caret. The one legitimate null
- * survives — a plugin-owned editable inside the box holding focus.
- */
+/** A missing declared element falls back to the focusable box, so the caret is never stranded;
+ *  null only while a plugin-owned editable inside the box holds focus. */
 export declare function composeWholeBlockFocusSurface(getFocusEl: () => HTMLElement | null | undefined, getBoxEl: () => HTMLElement | null | undefined, getKind: () => string): () => HTMLElement | null;
 export declare function focusWholeBlockEl(el: HTMLElement): void;
-/** Whole-block focus sits on the declared surface OR on the hidden host beside it. */
+/** Whole-block focus sits on the declared element or on the hidden host beside it. */
 export declare function holdsWholeBlockFocus(declared: HTMLElement | null | undefined, proxy: HTMLElement | null | undefined): boolean;
 export interface WholeBlockInputProxyDeps {
-    /** The chrome box: stable across the render swaps that replace a declared focus element. */
+    /** The block's box: stable across the render swaps that replace a declared focus element. */
     getBoxEl: () => HTMLElement | null | undefined;
-    /** The kind's declared surface. An editable one is the plugin's own caret host and keeps
-     *  focus for itself. */
+    /** The kind's declared focus element. An editable one is the plugin's own caret host and
+     *  keeps focus for itself. */
     getFocusEl: () => HTMLElement | null | undefined;
     isReading: () => boolean;
-    /** Commit the bytes the host produced — the keydown tail's mint, through another door. */
+    /** The block's accessible name: the host is the block's tab stop, so it names the block. */
+    getLabel: () => string;
+    /** Commit the bytes the host produced: the same paragraph the keydown path creates. */
     mint: (text: string) => void;
 }
 export interface WholeBlockInputProxy {
     /** The mounted host, or null while the block has no box. */
     el(): HTMLElement | null;
-    /** Land DOM focus for a whole-block entry, degrading to `declared` when the plugin owns
+    /** Put DOM focus for a whole-block entry, falling back to `declared` when the plugin owns
      *  the caret or the host has not mounted. */
     focus(declared: HTMLElement): void;
 }

package/dist/editor-actions/whole-block-focus-surface.js

@@ -1,12 +1,11 @@
 /**
- * The focus surface of a block that IS its own focus target, and the hidden editing host beside
- * it. Such a block has no editing surface of its own, so `beforeinput` and `compositionend` —
- * the only doors AltGr productions and IME composition arrive through — fire nowhere. The proxy
- * is that host. It mounts in the block's BOX, never in the declared focus element, which a
- * render swap replaces.
+ * The focus element of a block that is focused as a whole, and the hidden editing host beside
+ * it. Such a block has no editable element of its own, so `beforeinput` and `compositionend`,
+ * the only events AltGr characters and IME composition arrive through, fire nowhere. The
+ * proxy is that host. It mounts in the block's box, never in the declared focus element,
+ * which a render swap replaces.
  */
 import { onMount } from 'svelte';
-import { WHOLE_BLOCK_INPUT_LABEL } from '../a11y-strings';
 import { devWarn } from '../dev-warn';
 // ── Editable-target guards ───────────────────────────────────────────────────
 /** The hidden host looks exactly like a plugin's own editable; this is what tells them apart. */
@@ -14,11 +13,8 @@ export const WHOLE_BLOCK_INPUT_ATTR = 'data-whole-block-input';
 export function isWholeBlockInputProxy(target) {
     return target instanceof Element && target.hasAttribute(WHOLE_BLOCK_INPUT_ATTR);
 }
-/**
- * A key originating in a plugin's own text-editing surface belongs to that surface, never the
- * whole-block affordances: Backspace inside an edit textarea edits text. The hidden host is
- * excluded here rather than at each gate, so a later reader cannot forget it.
- */
+/** A key pressed in a plugin's own text editor belongs to that editor (Backspace in a textarea
+ *  edits text). The hidden host is excluded here, so no caller can forget it. */
 export function isEditableEventTarget(target) {
     if (!(target instanceof HTMLElement))
         return false;
@@ -28,24 +24,16 @@ export function isEditableEventTarget(target) {
     return tag === 'TEXTAREA' || tag === 'INPUT' || target.isContentEditable;
 }
 // ── Tab order ────────────────────────────────────────────────────────────────
-/**
- * The hidden host is the block's ONE tab stop, so a declared surface that is not itself an
- * editing host leaves the tab order (editor.md § 8). Applied on every read rather than once at
- * mount: a kind's declared element is whatever its current render state supplies, and the state
- * that appears after mount would otherwise keep its stop. Inverse of `focusWholeBlockEl`, which
- * only ever MINTS focusability on a box that has none.
- */
+/** The hidden host is the block's one tab stop, so a declared element that is not an editor
+ *  leaves the tab order. Applied on every read, since a later render state supplies a new one. */
 export function demoteDeclaredFromTabOrder(declared) {
     if (declared && declared.tabIndex >= 0 && !isEditableEventTarget(declared)) {
         declared.tabIndex = -1;
     }
     return declared;
 }
-/**
- * The class guard behind `getFocusEl`: an absent declared element degrades to the
- * focusable box, never a silent no-op that strands the caret. The one legitimate null
- * survives — a plugin-owned editable inside the box holding focus.
- */
+/** A missing declared element falls back to the focusable box, so the caret is never stranded;
+ *  null only while a plugin-owned editable inside the box holds focus. */
 export function composeWholeBlockFocusSurface(getFocusEl, getBoxEl, getKind) {
     let warned = false;
     return () => {
@@ -65,15 +53,14 @@ export function composeWholeBlockFocusSurface(getFocusEl, getBoxEl, getKind) {
         return box;
     };
 }
-// The degraded path's own policy, and the inverse of the demotion above: the fallback box is a
-// plain div, focusable only once a tabindex is minted. A surface already focusable keeps whatever
-// it has — this door only ever adds reachability, never removes it.
+// The fallback box is a plain div, focusable only with a tabindex; an element already focusable
+// keeps what it has, so this only ever adds reachability. The caller that moved the caret scrolls.
 export function focusWholeBlockEl(el) {
     if (el.tabIndex < 0 && !el.hasAttribute('tabindex'))
         el.tabIndex = -1;
-    el.focus();
+    el.focus({ preventScroll: true });
 }
-/** Whole-block focus sits on the declared surface OR on the hidden host beside it. */
+/** Whole-block focus sits on the declared element or on the hidden host beside it. */
 export function holdsWholeBlockFocus(declared, proxy) {
     const active = document.activeElement;
     return !!(declared?.contains(active) || (proxy && proxy === active));
@@ -81,45 +68,42 @@ export function holdsWholeBlockFocus(declared, proxy) {
 export function createWholeBlockInputProxy(deps) {
     let proxy = null;
     let composing = false;
-    /** Every read of the declared surface inside the proxy goes through the demotion, so a kind
-     *  supplying its own `getFocusEl` (no composed surface) is held to the rule too. */
+    /** Every read of the declared element inside the proxy goes through the demotion, so a kind
+     *  supplying its own `getFocusEl` (without the composed fallback) is held to the rule too. */
     const declaredSurface = () => demoteDeclaredFromTabOrder(deps.getFocusEl() ?? null);
-    function mint(text) {
-        if (!deps.isReading())
-            deps.mint(text);
-    }
     function onBeforeInput(event) {
         // The browser owns the host between compositionstart and compositionend (the editor's
-        // standing IME stance) — refusing here swallows the composition.
+        // standing IME rule); refusing here swallows the composition.
         if (composing)
             return;
         event.preventDefault();
         if (event.inputType === 'insertText' && event.data)
-            mint(event.data);
+            deps.mint(event.data);
     }
     function onCompositionEnd() {
         composing = false;
         const composed = proxy?.textContent ?? '';
-        // A caret host, never a surface a serializer reads: whatever the IME left belongs to the
-        // minted paragraph, and the host goes back to empty either way.
+        // A caret host, never something a serializer reads: whatever the IME left belongs to the
+        // new paragraph, and the host goes back to empty either way.
         if (proxy)
             proxy.textContent = '';
         if (composed)
-            mint(composed);
+            deps.mint(composed);
     }
-    // A pointer or a Tab lands natively on the kind's own surface, where no beforeinput fires;
-    // without this hand-off the first character after a click is keydown-minted again.
+    // A click or a Tab lands natively on the kind's own element, where no beforeinput fires;
+    // without this hand-off the first character after a click goes through keydown again.
     function onFocusIn(event) {
-        // Read before the identity test, so an arrival ANYWHERE in the box (the host's own included)
-        // re-applies the demotion to whatever surface the current render state supplies — which is
-        // what puts it out of the tab order before the next press, not after it.
+        // A Tab lands on the host without passing `focusProxy`, so the name is refreshed here too.
+        if (proxy && event.target === proxy)
+            syncProxyState();
+        // Before the identity test, so focus arriving anywhere in the box takes the current render
+        // state's declared element out of the tab order before the next keypress.
         if (!proxy || event.target !== declaredSurface())
             return;
         if (isEditableEventTarget(event.target))
             return;
-        // The host's own Shift+Tab lands here on its way out; bouncing it back would trap focus
-        // in the block. Every other arrival is passed on — a toolbar button included, or the
-        // click after one leaves the declared surface holding focus and drops IME again.
+        // The host's own Shift+Tab passes here on its way out, and bouncing it would trap focus. Any
+        // other arrival (a toolbar button too) moves on, or the declared element keeps focus without IME.
         if (event.relatedTarget === proxy)
             return;
         focusProxy();
@@ -127,9 +111,16 @@ export function createWholeBlockInputProxy(deps) {
     function focusProxy() {
         if (!proxy)
             return;
-        // Read per focus, not per mount: reading mode writes no bytes, so its host is inert.
+        syncProxyState();
+        proxy.focus({ preventScroll: true });
+    }
+    // Read per focus, not per mount: reading mode makes the host inert, and a kind's name can
+    // change while the block stays mounted.
+    function syncProxyState() {
+        if (!proxy)
+            return;
         proxy.setAttribute('contenteditable', deps.isReading() ? 'false' : 'true');
-        proxy.focus();
+        proxy.setAttribute('aria-label', deps.getLabel());
     }
     onMount(() => {
         const box = deps.getBoxEl();
@@ -138,12 +129,11 @@ export function createWholeBlockInputProxy(deps) {
         proxy = document.createElement('div');
         proxy.setAttribute(WHOLE_BLOCK_INPUT_ATTR, '');
         proxy.className = 'whole-block-input';
-        proxy.setAttribute('contenteditable', deps.isReading() ? 'false' : 'true');
         proxy.setAttribute('role', 'textbox');
-        proxy.setAttribute('aria-label', WHOLE_BLOCK_INPUT_LABEL);
+        syncProxyState();
         proxy.spellcheck = false;
-        // The block's tab stop, because focus belongs here: a declared surface left in the tab
-        // order is a second stop the backward tab parks on, where no input door exists.
+        // The block's tab stop, because focus belongs here: a declared element left in the tab
+        // order is a second stop Shift+Tab lands on, where no input can arrive.
         proxy.tabIndex = 0;
         declaredSurface();
         proxy.addEventListener('beforeinput', onBeforeInput);

package/dist/editor-events.d.ts

@@ -1,13 +1,13 @@
 /**
- * Observer-pattern event surface reached via `getEvents()`. Events fire synchronously
- * and handlers must NOT mutate the document; an `edit` event fires after its mutation
- * is published, so its handler sees the updated document.
+ * The event subscription object reached through `getEvents()`. Events fire synchronously
+ * and a handler must not mutate the document; an `edit` event fires after its change is
+ * written to state, so its handler sees the updated document.
  */
 import type { AnyBlockKind } from './core/nodes';
 import type { PresentationMode } from './presentation-mode';
 import type { EditorSelection } from './selection/primitives';
 import type { OpDescriptor, OperationDetailMap, OperationKind } from './schema/operations';
-/** Derived per-arm from OperationDetailMap — see schema/operations.ts. */
+/** Derived per operation from `OperationDetailMap`; see `schema/operations.ts`. */
 export type EditEvent = {
     [K in OperationKind]: undefined extends OperationDetailMap[K] ? {
         op: K;
@@ -21,20 +21,19 @@ export type EditEvent = {
         timestamp: number;
     };
 }[OperationKind];
-/** The cast is sound by construction: both types derive from OperationDetailMap, which
- *  TS cannot narrow as a correlated union. */
+/** The cast is sound by construction: both types come from `OperationDetailMap`, which
+ *  TypeScript cannot narrow as a correlated union. */
 export declare function toEditEvent(op: OpDescriptor, path: number[], timestamp: number): EditEvent;
 export type SelectionChangeEvent = EditorSelection | null;
 export interface EditorError {
     /**
-     * `clipboard` is a failure on the paste route — the channel a host needs to release
+     * `clipboard` is a failure while pasting: the channel a host needs in order to release
      * an asset `onPasteImage` already imported for it.
      */
     origin: 'subscriber' | 'render' | 'commit' | 'command' | 'decoration' | 'clipboard' | 'link';
     error: unknown;
-    /** Origin-specific: `path` for render, `op`+`path` for commit, `kind`+`command`
-     *  (+`plugin`) for a command throw, `source` for decoration, `url` for link, and the
-     *  paste's start path for clipboard when it was aimed at a range. */
+    /** Origin-specific: `path` for render, `op`+`path` for commit, `kind`+`command` (+`plugin`) for a
+     *  command, `source` for decoration, `url` for link, the aimed-at start path for clipboard. */
     context?: {
         path?: number[];
         op?: OperationKind;
@@ -49,43 +48,40 @@ export interface EditorEventMap {
     edit: EditEvent;
     selectionChange: SelectionChangeEvent;
     error: EditorError;
-    /** The EFFECTIVE mode after a `presentationMode` prop change (never fired at mount). */
+    /** The mode in effect after a `presentationMode` prop change (never fired at mount). */
     presentationModeChange: PresentationMode;
     /** The theme name after a `theme` prop change (never fired at mount), for a plugin
      *  that paints its own colors and so cannot pick the change up from CSS. */
     themeChange: string;
-    /** `true` when an editor-owned menu (right-click, insert `+`) opens, `false` when it closes,
-     *  so host chrome over the selection can step aside rather than stack on it. */
+    /** `true` when an editor-owned menu or popover opens while none was, `false` when the last one
+     *  closes, so a host's own controls over the selection can step aside rather than stack. */
     menuChange: boolean;
+    /** A `source` prop write replaced the whole document. Fires once the new tree, its selection
+     *  and its link references are in place; an `edit` never fires for it. */
+    sourceSwap: SourceSwapEvent;
+}
+/** `generation` counts whole-document replacements since mount, starting at 1. */
+export interface SourceSwapEvent {
+    generation: number;
 }
 export interface EditorEvents {
     on<K extends keyof EditorEventMap>(event: K, handler: (payload: EditorEventMap[K]) => void): () => void;
-    /** Internal emit — not exported from index.ts. */
+    /** Internal emit; not exported from `index.ts`. */
     emit<K extends keyof EditorEventMap>(event: K, payload: EditorEventMap[K]): void;
 }
 export declare function createEditorEvents(): EditorEvents;
-/**
- * Route a contained command throw to the `error` channel, attributing the command and
- * its owning plugin; no-ops when no events surface is present. A direct `plugin` wins
- * over the kind lookup, so a global command's own owner is never clobbered by one.
- */
+/** Report a thrown command to the `error` channel with the plugin that registered it. */
 export declare function emitCommandError(events: EditorEvents | undefined, report: {
     kind?: AnyBlockKind;
     command: string;
     plugin?: string;
     error: unknown;
 }): void;
-/**
- * Route a blocked link activation to the `error` channel: the scheme allowlist refused the URL,
- * which a host may want to log or surface. Fires for the DEFAULT activation only — a consumer
- * supplying `onLinkActivate` owns its own policy.
- */
+/** Report a link the scheme allowlist refused to the `error` channel. Default activation only: a
+ *  consumer supplying `onLinkActivate` owns its own policy. */
 export declare function emitBlockedLinkError(events: EditorEvents | undefined, url: string): void;
-/**
- * Route a contained clipboard-route failure to the `error` channel. `path` addresses the
- * range the paste was aimed at and is OMITTED where there is none to name — `[]` would
- * report the document root, which holds no caret.
- */
+/** Report a clipboard failure to the `error` channel. `path` is left out when the paste aimed at
+ *  no range, since `[]` would name the document root, which holds no caret. */
 export declare function emitClipboardError(events: EditorEvents, report: {
     error: unknown;
     path?: number[];

package/dist/editor-events.js

@@ -1,13 +1,12 @@
 /**
- * Observer-pattern event surface reached via `getEvents()`. Events fire synchronously
- * and handlers must NOT mutate the document; an `edit` event fires after its mutation
- * is published, so its handler sees the updated document.
+ * The event subscription object reached through `getEvents()`. Events fire synchronously
+ * and a handler must not mutate the document; an `edit` event fires after its change is
+ * written to state, so its handler sees the updated document.
  */
 import { devWarn } from './dev-warn';
 import { editorEnv } from './env';
-import { pluginKindOwner } from './schema/plugin-install';
-/** The cast is sound by construction: both types derive from OperationDetailMap, which
- *  TS cannot narrow as a correlated union. */
+/** The cast is sound by construction: both types come from `OperationDetailMap`, which
+ *  TypeScript cannot narrow as a correlated union. */
 export function toEditEvent(op, path, timestamp) {
     return { op: op.kind, path, detail: op.detail, timestamp };
 }
@@ -33,8 +32,8 @@ export function createEditorEvents() {
                 handler(payload);
             }
             catch (err) {
-                // Recursion guard: an error-channel subscriber's own throw reports rather than
-                // re-emitting, which would loop. Everything the channel cannot carry reds a gate.
+                // An error-channel subscriber that throws is reported rather than re-emitted,
+                // which would loop. Anything the channel cannot report fails a gate instead.
                 if (event !== 'error' && handlers.error?.size) {
                     emit('error', { origin: 'subscriber', error: err });
                 }
@@ -42,8 +41,8 @@ export function createEditorEvents() {
                     devWarn('events', `${event} subscriber threw`, err);
                 }
                 else {
-                    // devWarn is silent in production, and the swallow is what hides an exception the
-                    // consumer's own handler threw, which an unguarded call would have surfaced.
+                    // `devWarn` is silent in production, and swallowing here would hide an exception
+                    // the consumer's own handler threw, which an unguarded call would have shown.
                     console.error(`[aragonite] ${event} subscriber threw`, err);
                 }
             }
@@ -52,13 +51,9 @@ export function createEditorEvents() {
     return { on, emit };
 }
 // ── Contained-failure routing ──────────────────────────────────────────────
-// One envelope minter per origin with more than one emission site, living here so the
-// shell that owns the channel owns the payload shape too.
-/**
- * Route a contained command throw to the `error` channel, attributing the command and
- * its owning plugin; no-ops when no events surface is present. A direct `plugin` wins
- * over the kind lookup, so a global command's own owner is never clobbered by one.
- */
+// One builder per origin that has more than one emission site, kept here so the code that
+// owns the channel owns the payload shape too.
+/** Report a thrown command to the `error` channel with the plugin that registered it. */
 export function emitCommandError(events, report) {
     events?.emit('error', {
         origin: 'command',
@@ -66,15 +61,12 @@ export function emitCommandError(events, report) {
         context: {
             kind: report.kind,
             command: report.command,
-            plugin: report.plugin ?? (report.kind ? (pluginKindOwner(report.kind) ?? undefined) : undefined)
+            plugin: report.plugin
         }
     });
 }
-/**
- * Route a blocked link activation to the `error` channel: the scheme allowlist refused the URL,
- * which a host may want to log or surface. Fires for the DEFAULT activation only — a consumer
- * supplying `onLinkActivate` owns its own policy.
- */
+/** Report a link the scheme allowlist refused to the `error` channel. Default activation only: a
+ *  consumer supplying `onLinkActivate` owns its own policy. */
 export function emitBlockedLinkError(events, url) {
     events?.emit('error', {
         origin: 'link',
@@ -82,11 +74,8 @@ export function emitBlockedLinkError(events, url) {
         context: { url }
     });
 }
-/**
- * Route a contained clipboard-route failure to the `error` channel. `path` addresses the
- * range the paste was aimed at and is OMITTED where there is none to name — `[]` would
- * report the document root, which holds no caret.
- */
+/** Report a clipboard failure to the `error` channel. `path` is left out when the paste aimed at
+ *  no range, since `[]` would name the document root, which holds no caret. */
 export function emitClipboardError(events, report) {
     events.emit('error', {
         origin: 'clipboard',