@voithos-labs/aragonite 0.10.4 → 0.10.7

package/dist/schema/reserved-chords.js

@@ -1,43 +1,44 @@
 /**
- * Which modifier chords a mounted editor consumes. The keymap tiers enumerate from the
- * registries; chords claimed by hand-written keydown branches do not, so they ride the
- * manifest below — G4.29's source scan fails until a new claiming site joins it. Bare keys
- * stay out of contract: a focused document owns them whatever the manifest says. A manifested
- * file must keep its literal key comparisons and modifier reads, which are the scan's evidence.
+ * Which modifier chords a mounted editor consumes. Keymap chords come from the registries; chords
+ * taken by hand-written keydown branches are listed in `HARDCODED_CHORD_SITES`, and a source scan
+ * fails until a new such file is added there (G4.29). A listed file keeps its literal key
+ * comparisons and modifier reads, the scan's evidence. Bare keys are out of scope: the document
+ * owns them.
  */
-import { getAllRegisteredKinds, tryGetBlockKindDescriptor } from './block-kind-descriptor';
-import { GLOBAL_KEYMAP, pluginGlobalChords, reservedUiChords } from './commands';
-import { eventToChord, normalizeChord } from './keybindings';
+import { getAllRegisteredKinds } from './block-kind-descriptor';
+import { GLOBAL_KEYMAP, kindKeymap, pluginGlobalChords, reservedUiChords } from './commands';
+import { kindEnablementFor } from './registry-view';
+import { eventToChord } from './keybindings';
 export const HARDCODED_CHORD_SITES = [
     {
-        file: 'components/Editor.svelte',
+        file: 'components/editor-root-gestures.ts',
         chords: [],
         keys: [],
-        note: 'Mod-click link activation — no keystroke is consumed.'
+        note: 'Mod-click link activation: no keystroke is consumed.'
     },
     {
         file: 'components/editor-root-keydown.ts',
         chords: [],
-        keys: ['Escape'],
-        note: 'Escape closes the find bar (a reserved UI chord, enumerated). The modifier read is a REFUSAL: an unchorded character over a live range goes to the range’s text door, a chorded one to the arms below it.'
+        keys: ['Escape', 'H'],
+        note: 'Escape closes the find bar, and Mod+H picks the replace row as the bar opens (reserved UI chords, enumerated). The modifier read is a refusal: an unchorded character over a live range is written as text, a chorded one goes to the handlers below it.'
     },
     {
         file: 'components/editor-root-listeners.ts',
         chords: [],
         keys: [],
-        note: 'The Mod-held `data-mod-active` affordance tracks flag state only — no keystroke is consumed.'
+        note: 'The Mod-held `data-mod-active` affordance tracks flag state only: no keystroke is consumed.'
     },
     {
         file: 'selection/selection-drop.ts',
         chords: [],
         keys: [],
-        note: 'Ctrl/Alt at the DROP is the platform copy modifier, read off a DragEvent — no keystroke is consumed.'
+        note: 'Ctrl/Alt at the drop is the platform copy modifier, read off a DragEvent: no keystroke is consumed.'
     },
     {
         file: 'selection/multi-click.ts',
         chords: [],
         keys: [],
-        note: 'A modified multi-click is left to the browser (Shift extends, Mod activates) — no keystroke is consumed.'
+        note: 'A modified multi-click is left to the browser (Shift extends, Mod activates): no keystroke is consumed.'
     },
     {
         file: 'components/GapCaret.svelte',
@@ -52,7 +53,7 @@ export const HARDCODED_CHORD_SITES = [
             'Enter',
             'Escape'
         ],
-        note: 'The gap caret proxy claims the exits plus the Enter that mints; Ctrl/Meta/Alt yields to the global table, and Shift takes the plain arrow arm.'
+        note: 'The gap caret proxy claims the exits plus the Enter that creates a block; Ctrl/Meta/Alt yields to the global table, and Shift takes the plain arrow branch.'
     },
     {
         file: 'components/SearchBar.svelte',
@@ -64,13 +65,13 @@ export const HARDCODED_CHORD_SITES = [
         file: 'components/blocks/editable-leaf.ts',
         chords: [],
         keys: ['Backspace', 'Enter'],
-        note: "Shift-click gate on the rendered surface — a pointer read; plain Backspace (no modifier) at the top of an empty painted source deletes the block, as the code block does. The reveal's own undo resolves its chord through the keymap, so it claims none here."
+        note: "Shift-click gate on the rendered surface, a pointer read; plain Backspace (no modifier) at the top of an empty painted source deletes the block, as the code block does. The reveal's own undo resolves its chord through the keymap, so it claims none here."
     },
     {
         file: 'components/link-card/LinkCard.svelte',
-        chords: ['Shift+Tab', 'Mod+K'],
-        keys: ['Enter', 'K', 'Tab', 'k'],
-        note: "Backwards step of the open card's focus trap, plus the entry chord swallowed as a no-op where the focus already is — the kind keymaps claim it everywhere else. Escape lives on the host, which must also close a card the document still holds the caret for."
+        chords: ['Shift+Tab'],
+        keys: ['Enter', 'Tab'],
+        note: "Backwards step of the open card's focus trap. The chord that opens the card is swallowed there too, resolved through the keymap like everywhere else. Escape lives on the host, which must also close a card the document still holds the caret for."
     },
     {
         file: 'components/menu/BlockMenu.svelte',
@@ -98,19 +99,8 @@ export const HARDCODED_CHORD_SITES = [
     },
     {
         file: 'components/blocks/table/cell-keydown-plan.ts',
-        chords: ['Mod+A', 'Shift+Tab'],
-        keys: [
-            'A',
-            'ArrowDown',
-            'ArrowLeft',
-            'ArrowRight',
-            'ArrowUp',
-            'Backspace',
-            'Delete',
-            'Enter',
-            'Tab',
-            'a'
-        ]
+        chords: ['Shift+Tab'],
+        keys: ['ArrowDown', 'ArrowLeft', 'ArrowRight', 'ArrowUp', 'Backspace', 'Delete', 'Enter', 'Tab']
     },
     {
         file: 'components/blocks/text/TextEditableBlock.svelte',
@@ -147,9 +137,13 @@ export const HARDCODED_CHORD_SITES = [
             'ArrowUp',
             'Backspace',
             'Delete',
-            'Escape'
+            'End',
+            'Escape',
+            'Home',
+            'PageDown',
+            'PageUp'
         ],
-        note: 'Extends a selection into a widget. A modified arrow is also swallowed while a widget is selected, but that is a caret-coherence guard in a transient state, not a binding; a plain vertical arrow seats a caret and declines.'
+        note: 'Extends a selection into a widget. A modified arrow is also swallowed while a widget is selected, but that is a caret-coherence guard in a transient state, not a binding; a plain vertical arrow, Home, End or page key places a caret and declines.'
     },
     {
         file: 'components/image/ImageResizeHandles.svelte',
@@ -170,16 +164,16 @@ export const HARDCODED_CHORD_SITES = [
         note: 'Shift-click declines, so the block keeps cross-block extension.'
     },
     {
-        file: 'cursor/edge-affinity.ts',
+        file: 'components/image/widget-selection-state.svelte.ts',
         chords: [],
-        keys: ['ArrowDown', 'ArrowLeft', 'ArrowRight', 'ArrowUp', 'End', 'Home', 'PageDown', 'PageUp'],
-        note: 'Classifies an arrival for the caret-side memory; consumes nothing.'
+        keys: [],
+        note: 'A Shift-press on a block is left to that block, which grows a range from the image.'
     },
     {
-        file: 'cursor/sticky-column.ts',
+        file: 'cursor/caret-memory.ts',
         chords: [],
-        keys: ['ArrowDown', 'ArrowUp'],
-        note: 'Classifies a keystroke for the column memory; consumes nothing.'
+        keys: [],
+        note: 'Hands the meta flag to the arrival classifier: Cmd+Arrow is a line end. Consumes nothing.'
     },
     {
         file: 'editor-actions/container-block-component.ts',
@@ -195,42 +189,41 @@ export const HARDCODED_CHORD_SITES = [
             'c',
             'x'
         ],
-        note: 'Whole-block copy/cut: a keydown carries no ClipboardEvent, so the chord is read here. The unchorded printable mints a paragraph below, so the same modifier reads gate that branch too.'
+        note: 'Whole-block copy/cut: a keydown carries no ClipboardEvent, so the chord is read here. The unchorded printable creates a paragraph below, so the same modifier reads gate that branch too.'
     },
     {
         file: 'editor-actions/plugin/container.ts',
-        chords: ['Alt+ArrowUp', 'Alt+ArrowDown'],
-        keys: ['ArrowDown', 'ArrowUp'],
-        note: 'Reorder for plugin containers, whose command dispatch is inert.'
+        chords: [],
+        keys: [],
+        note: 'The arrow exit for a plugin editor declines every modified key rather than claiming one.'
     },
     {
         file: 'plugins/footnotes/FootnoteDefinition.svelte',
         chords: [],
         keys: [],
-        note: 'Mod-click on the `[^label]` marker jumps back to the reference — no keystroke is consumed.'
+        note: 'Mod-click on the `[^label]` marker jumps back to the reference: no keystroke is consumed.'
     },
     {
         file: 'plugins/footnotes/FootnoteReference.svelte',
         chords: [],
-        keys: [],
-        note: 'Mod-click jump to the definition, the link click’s gesture — no keystroke is consumed.'
+        keys: [' ', 'Enter'],
+        note: 'Mod-click jump to the definition, the link click’s gesture; Enter and Space on the reference, a tab stop in reading mode only, are bare keys.'
     },
     {
         file: 'plugins/mermaid/MermaidBlock.svelte',
         chords: ['Mod+Enter'],
         keys: ['ArrowDown', 'ArrowLeft', 'ArrowRight', 'ArrowUp', 'Enter', 'Escape', 'Tab'],
-        note: 'Commits the diagram edit; the arrows are the edit box’s boundary exits, and a modified one is declined rather than claimed. Bundled-plugin chord, listed unconditionally — it coincides with the table keymap, so gating it on the install would change no answer.'
+        note: 'Commits the diagram edit; the arrows are the edit box’s boundary exits, and a modified one is declined rather than claimed. Bundled-plugin chord, listed unconditionally: it coincides with the table keymap, so gating it on the install would change no answer.'
     },
     {
         file: 'schema/keybindings.ts',
-        chords: [],
-        keys: [],
-        note: 'The normalizer every other site reads.'
+        chords: ['Mod+A'],
+        keys: ['A'],
+        note: 'The normalizer every other site reads, and the select-all predicate every block asks.'
     },
     {
         file: 'selection/cross-block/keydown.ts',
         chords: [
-            'Mod+A',
             'Mod+Shift+Home',
             'Mod+Shift+End',
             'Shift+ArrowUp',
@@ -255,14 +248,13 @@ export const HARDCODED_CHORD_SITES = [
             'K',
             'Tab',
             'X',
-            'a',
             'b',
             'e',
             'i',
             'k',
             'x'
         ],
-        note: 'Mod+0-6 routes to the merged command registry, where that binding lives. The rewrite chords are CLAIMED over a cross-block range and handed to the dispatch seam — the four format toggles route to the cross-block arm, the link card declines, since no single block can host its mint — because falling through read the chord as text (or ran Ctrl+K as kill-line). Mod+Shift+X takes an arm of its own: unshifted Mod+X is the whole-block cut.'
+        note: 'Mod+0-6 routes to the merged command registry, where that binding lives. The rewrite chords are claimed over a cross-block range and handed to the cross-block dispatch: the four format toggles route to the cross-block handler, and the link card declines, since no single block can hold the link it would create. Falling through read the chord as text (or ran Ctrl+K as kill-line). Mod+Shift+X takes a branch of its own: unshifted Mod+X is the whole-block cut.'
     },
     {
         file: 'selection/cross-block/pointer.ts',
@@ -279,40 +271,26 @@ export const HARDCODED_CHORD_SITES = [
     {
         file: 'selection/shared-keydown.ts',
         chords: ['Shift+ArrowUp', 'Shift+ArrowDown', 'Shift+ArrowLeft', 'Shift+ArrowRight'],
-        keys: [
-            'Alt',
-            'AltGraph',
-            'ArrowDown',
-            'ArrowLeft',
-            'ArrowRight',
-            'ArrowUp',
-            'CapsLock',
-            'Control',
-            'Meta',
-            'Shift',
-            'a'
-        ],
+        keys: ['ArrowDown', 'ArrowLeft', 'ArrowRight', 'ArrowUp'],
         note: 'Extends across a block boundary once the native extend runs out of room.'
     }
 ];
-const HARDCODED_CHORDS = new Set(HARDCODED_CHORD_SITES.flatMap((site) => site.chords).map(normalizeChord));
+const HARDCODED_CHORDS = new Set(HARDCODED_CHORD_SITES.flatMap((site) => site.chords));
 /**
  * Every modifier chord this editor consumes, normalized. Composed on each call: kind keymaps,
- * the plugin tiers and the override map all change under a live editor.
+ * plugin chords and the override map all change under a live editor.
  */
 export function collectReservedChords(options) {
     const claimed = new Set([
-        ...registeredKeymapChords(),
+        ...registeredKeymapChords(options.activation),
         ...GLOBAL_KEYMAP.map((binding) => binding.chord),
         ...pluginGlobalChords(options.activation),
         ...HARDCODED_CHORDS,
         ...(options.searchBar ? reservedUiChords() : []),
         ...overrideBoundChords(options.keybindings)
-    ]
-        .map(normalizeChord)
-        .filter(carriesModifier));
-    // A global disable unbinds the chord at every command tier. A hardcoded branch never
-    // consults the override map, so it keeps its claim.
+    ].filter(carriesModifier));
+    // A global disable unbinds the chord at every command level. A hardcoded branch never
+    // consults the override map, so it keeps the chord.
     for (const chord of globallyDisabledChords(options.keybindings)) {
         if (!HARDCODED_CHORDS.has(chord))
             claimed.delete(chord);
@@ -320,8 +298,8 @@ export function collectReservedChords(options) {
     return claimed;
 }
 /**
- * True when `chords` claims this keystroke, under the editor's own normalization — Ctrl and
- * Cmd both fold to `Mod`, so a consumer never re-derives the platform rule.
+ * True when `chords` holds this keystroke, under the editor's own normalization: Ctrl and Cmd
+ * both become `Mod`, so a consumer never re-derives the platform rule.
  */
 export function chordIsClaimed(event, chords) {
     const chord = eventToChord(event);
@@ -331,8 +309,13 @@ export function chordIsClaimed(event, chords) {
 function carriesModifier(chord) {
     return chord.includes('+');
 }
-function registeredKeymapChords() {
-    return getAllRegisteredKinds().flatMap((kind) => tryGetBlockKindDescriptor(kind)?.keymap?.map((binding) => binding.chord) ?? []);
+/** Only the kinds this editor resolves: an unlisted plugin's kind renders nowhere here, so its
+ *  keymap takes no chord. */
+function registeredKeymapChords(activation) {
+    const isEnabled = kindEnablementFor(activation);
+    return getAllRegisteredKinds()
+        .filter(isEnabled)
+        .flatMap((kind) => kindKeymap(kind).map((binding) => binding.chord));
 }
 function overrideBoundChords(overrides) {
     if (!overrides)

package/dist/schema/reserved-chrome.d.ts

@@ -2,22 +2,23 @@ import type { AnyBlockKind } from '../core/nodes';
 import type { NodeView } from '../core/node-views';
 import { type BlockKindDescriptor } from './block-kind-descriptor';
 /**
- * Reserved-chrome predicates: the declaration-driven surface the model layer dispatches on
- * instead of a plugin kind name. These read a container's `reservedChrome` declaration, never
- * a hard-coded kind.
+ * Checks for a container's reserved title row (its fixed first child), read off the container's
+ * `reservedChrome` declaration so the rest of the editor never names a plugin kind.
  */
-/** The reserved chrome kind a container declares, or undefined if it declares none. */
+/** The title row kind a container declares, or undefined if it declares none. */
 export declare function reservedChromeKindOf(containerKind: AnyBlockKind): AnyBlockKind | undefined;
-/** True when `childIndex` is the reserved chrome slot (index 0) of a chrome-declaring container. */
+/** True when `childIndex` is the title row position (index 0) of a container declaring one. */
 export declare function isReservedChromeChild(container: NodeView, childIndex: number): boolean;
-/** True only when the kind declares an `isCollapsed` probe and it reports this node collapsed. */
+/** True only when the kind declares an `isCollapsed` check and that check reports it collapsed. */
 export declare function isCollapsedContainer(node: NodeView): boolean;
-/** The same reading for a caller already holding the descriptor — the height oracle's per-node
- *  path, where a second registry lookup is one per block of the document. */
+/** How many of `node`'s children a caret can reach: all of them, or only the title row while the
+ *  container is collapsed, so its last reachable child is this count minus one. */
+export declare function caretChildCount(node: NodeView): number;
+/** The same answer for a caller that already holds the descriptor: the height estimator runs per
+ *  node, where a second registry lookup would cost one per block of the document. */
 export declare function isCollapsedByDescriptor(descriptor: BlockKindDescriptor | undefined, node: NodeView): boolean;
 /**
- * The metadata patch that expands `node`, or null when its kind declares no door. Sibling of
- * `isCollapsedContainer` over the same declaration, so the clamp that hides a body and the
- * reveal that opens it cannot disagree about which containers collapse.
+ * The metadata change that expands `node`, or null when its kind declares none. It reads the same
+ * declaration as `isCollapsedContainer`, so hiding a body and opening it cannot disagree.
  */
 export declare function expandContainerPatch(node: NodeView): Record<string, unknown> | null;

package/dist/schema/reserved-chrome.js

@@ -1,31 +1,35 @@
 import { tryGetBlockKindDescriptor } from './block-kind-descriptor';
 /**
- * Reserved-chrome predicates: the declaration-driven surface the model layer dispatches on
- * instead of a plugin kind name. These read a container's `reservedChrome` declaration, never
- * a hard-coded kind.
+ * Checks for a container's reserved title row (its fixed first child), read off the container's
+ * `reservedChrome` declaration so the rest of the editor never names a plugin kind.
  */
-/** The reserved chrome kind a container declares, or undefined if it declares none. */
+/** The title row kind a container declares, or undefined if it declares none. */
 export function reservedChromeKindOf(containerKind) {
     return tryGetBlockKindDescriptor(containerKind)?.reservedChrome?.kind;
 }
-/** True when `childIndex` is the reserved chrome slot (index 0) of a chrome-declaring container. */
+/** True when `childIndex` is the title row position (index 0) of a container declaring one. */
 export function isReservedChromeChild(container, childIndex) {
     return childIndex === 0 && reservedChromeKindOf(container.kind) !== undefined;
 }
-/** True only when the kind declares an `isCollapsed` probe and it reports this node collapsed. */
+/** True only when the kind declares an `isCollapsed` check and that check reports it collapsed. */
 export function isCollapsedContainer(node) {
     return isCollapsedByDescriptor(tryGetBlockKindDescriptor(node.kind), node);
 }
-/** The same reading for a caller already holding the descriptor — the height oracle's per-node
- *  path, where a second registry lookup is one per block of the document. */
+/** How many of `node`'s children a caret can reach: all of them, or only the title row while the
+ *  container is collapsed, so its last reachable child is this count minus one. */
+export function caretChildCount(node) {
+    const count = node.children?.length ?? 0;
+    return count > 0 && isCollapsedContainer(node) ? 1 : count;
+}
+/** The same answer for a caller that already holds the descriptor: the height estimator runs per
+ *  node, where a second registry lookup would cost one per block of the document. */
 export function isCollapsedByDescriptor(descriptor, node) {
     const probe = descriptor?.reservedChrome?.isCollapsed;
     return probe !== undefined && probe(node);
 }
 /**
- * The metadata patch that expands `node`, or null when its kind declares no door. Sibling of
- * `isCollapsedContainer` over the same declaration, so the clamp that hides a body and the
- * reveal that opens it cannot disagree about which containers collapse.
+ * The metadata change that expands `node`, or null when its kind declares none. It reads the same
+ * declaration as `isCollapsedContainer`, so hiding a body and opening it cannot disagree.
  */
 export function expandContainerPatch(node) {
     const door = tryGetBlockKindDescriptor(node.kind)?.reservedChrome?.expandPatch;

package/dist/schema/setext-raw.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The setext heading's two byte facts: where its title ends, and its write rule, declared on the
+ * kind as `rawWrite`. The underline line after the title is structure, kept under a title and
+ * dropped under a blank line, where it would read as a block of its own.
+ */
+import type { NodeView } from '../core/node-views';
+import type { WriteRule } from './block-kind-descriptor';
+/** The title's range in the heading's raw: everything before the break above the underline. */
+export declare function setextHeadingContentRange(node: NodeView): {
+    start: number;
+    end: number;
+};
+export declare const setextHeadingWrite: WriteRule;

package/dist/schema/setext-raw.js

@@ -0,0 +1,33 @@
+/**
+ * The setext heading's two byte facts: where its title ends, and its write rule, declared on the
+ * kind as `rawWrite`. The underline line after the title is structure, kept under a title and
+ * dropped under a blank line, where it would read as a block of its own.
+ */
+import { displayLines, isBlankLine, trimTrailingLineEnding } from '../core/lines';
+/** The title's range in the heading's raw: everything before the break above the underline. */
+export function setextHeadingContentRange(node) {
+    const display = trimTrailingLineEnding(node.raw);
+    const lines = displayLines(display);
+    if (lines.length < 2)
+        return { start: 0, end: display.length };
+    const underline = lines[lines.length - 1];
+    const breakAbove = lines[lines.length - 2].ending;
+    return { start: 0, end: display.length - underline.text.length - breakAbove.length };
+}
+/** `raw` less the heading's underline when the line above it is blank, as an emptied ATX heading
+ *  gives up its `#`. */
+function dropUnderlineUnderBlankLine(node, raw) {
+    const underline = trimTrailingLineEnding(node.raw).slice(setextHeadingContentRange(node).end);
+    const display = trimTrailingLineEnding(raw);
+    if (!underline || !display.endsWith(underline))
+        return raw;
+    const title = display.slice(0, display.length - underline.length);
+    const lastLine = title.slice(title.lastIndexOf('\n') + 1);
+    return isBlankLine(lastLine) ? title + raw.slice(display.length) : raw;
+}
+export const setextHeadingWrite = {
+    normalize: (raw, ctx) => dropUnderlineUnderBlankLine(ctx.node, raw),
+    // The dropped underline sits after the blank line every caret stands on, so a caret past it
+    // lands at the end of what is left.
+    mapOffset: (raw, offset, ctx) => Math.min(offset, dropUnderlineUnderBlankLine(ctx.node, raw).length)
+};

package/dist/schema/stored-as.d.ts

@@ -0,0 +1,20 @@
+/**
+ * How bytes written at one leaf position are stored and read back, so a live rewrite that removes
+ * bytes checks its candidate the way a reload will read it there. Only
+ * `tree-operations/stored-as.ts` makes one, so a rewrite can't describe its own position.
+ */
+import type { Document } from '../core/nodes';
+import type { Reading } from './reading';
+declare const storedAsBrand: unique symbol;
+export interface StoredAs {
+    readonly reading: Reading;
+    /** `inline`: the position stores text, never a block (a table cell, a title row). */
+    readonly surface: 'block' | 'inline';
+    /** The bytes the position keeps: the kind's write rule, then its container's body rule. */
+    stored(bytes: string): string;
+    /** Stored bytes read as a reload reads them at the position, or null where the reload would
+     *  read the container around them differently. */
+    readSlot(stored: string): Document | null;
+    readonly [storedAsBrand]: true;
+}
+export {};

package/dist/schema/stored-as.js

@@ -0,0 +1,6 @@
+/**
+ * How bytes written at one leaf position are stored and read back, so a live rewrite that removes
+ * bytes checks its candidate the way a reload will read it there. Only
+ * `tree-operations/stored-as.ts` makes one, so a rewrite can't describe its own position.
+ */
+export {};

package/dist/schema/table-cell-raw.d.ts

@@ -1,14 +1,25 @@
 /**
- * The tableCell raw-write rule, declared on the kind as `normalizeRawWrite` and applied at the
- * write sink (`tree-operations/content-write.updateNodeContent`). A cell's bytes are joined verbatim
- * into its row, and the parser truncates a row reparsing wider than the delimiter's column
- * count, so a bare `|` or line break reaching a cell raw deletes the last column's content.
- * Both passes are prefix-composable, which is what makes `escapedCellOffset` an exact caret image.
+ * The rule for writing a table cell's bytes, declared on the kind as `rawWrite`. A cell's bytes
+ * go into its row unchanged, so a bare `|` or line break reaching them would split the row and
+ * delete the last column's content. Both passes work prefix by prefix, which is what lets
+ * {@link escapedCellOffset} map a caret exactly.
  */
+import type { WriteRule } from './block-kind-descriptor';
 /**
- * Escape every `|` not already freed by an odd run of backslashes. Idempotent: the freeing
- * backslash usually comes from text the writer never touched, so a re-run must be a no-op.
+ * Escape every `|` an odd run of backslashes has not already escaped. Running it twice changes
+ * nothing: the escaping backslash usually comes from text the writer never touched.
  */
 export declare function escapeUnescapedPipes(s: string): string;
+/** A cell's text with the escape taken off each pipe, the text a spreadsheet reads; the cell
+ *  writer puts it back. */
+export declare function unescapeCellPipes(raw: string): string;
 /** Text made legal as a cell's `raw`: no line break, no unescaped delimiter. */
 export declare function normalizeCellRaw(raw: string): string;
+/**
+ * Where `offset` lands once {@link normalizeCellRaw} has run, worked out by that same pass over
+ * the prefix, so the caret cannot drift out of step with the bytes.
+ */
+export declare function escapedCellOffset(text: string, offset: number): number;
+/** The cell's write rule; it reads nothing but the bytes. A cell has no line ending of its own,
+ *  so the one a block write carries is dropped rather than turned into a space. */
+export declare const tableCellWrite: WriteRule;

package/dist/schema/table-cell-raw.js

@@ -1,13 +1,13 @@
 /**
- * The tableCell raw-write rule, declared on the kind as `normalizeRawWrite` and applied at the
- * write sink (`tree-operations/content-write.updateNodeContent`). A cell's bytes are joined verbatim
- * into its row, and the parser truncates a row reparsing wider than the delimiter's column
- * count, so a bare `|` or line break reaching a cell raw deletes the last column's content.
- * Both passes are prefix-composable, which is what makes `escapedCellOffset` an exact caret image.
+ * The rule for writing a table cell's bytes, declared on the kind as `rawWrite`. A cell's bytes
+ * go into its row unchanged, so a bare `|` or line break reaching them would split the row and
+ * delete the last column's content. Both passes work prefix by prefix, which is what lets
+ * {@link escapedCellOffset} map a caret exactly.
  */
+import { trimTrailingLineEnding } from '../core/lines';
 /**
- * Escape every `|` not already freed by an odd run of backslashes. Idempotent: the freeing
- * backslash usually comes from text the writer never touched, so a re-run must be a no-op.
+ * Escape every `|` an odd run of backslashes has not already escaped. Running it twice changes
+ * nothing: the escaping backslash usually comes from text the writer never touched.
  */
 export function escapeUnescapedPipes(s) {
     let out = '';
@@ -24,7 +24,28 @@ export function escapeUnescapedPipes(s) {
     }
     return out;
 }
+/** A cell's text with the escape taken off each pipe, the text a spreadsheet reads; the cell
+ *  writer puts it back. */
+export function unescapeCellPipes(raw) {
+    return raw.replace(/\\\|/g, '|');
+}
 /** Text made legal as a cell's `raw`: no line break, no unescaped delimiter. */
 export function normalizeCellRaw(raw) {
     return escapeUnescapedPipes(raw.replace(/\r?\n/g, ' '));
 }
+/**
+ * Where `offset` lands once {@link normalizeCellRaw} has run, worked out by that same pass over
+ * the prefix, so the caret cannot drift out of step with the bytes.
+ */
+export function escapedCellOffset(text, offset) {
+    return normalizeCellRaw(text.slice(0, offset)).length;
+}
+/** The cell's write rule; it reads nothing but the bytes. A cell has no line ending of its own,
+ *  so the one a block write carries is dropped rather than turned into a space. */
+export const tableCellWrite = {
+    normalize: (raw) => normalizeCellRaw(trimTrailingLineEnding(raw)),
+    mapOffset: (raw, offset) => {
+        const text = trimTrailingLineEnding(raw);
+        return escapedCellOffset(text, Math.min(offset, text.length));
+    }
+};

package/dist/schema/whole-block-unit.d.ts

@@ -1,8 +1,9 @@
 /**
- * The kind class with no character positions: `blockFocus: 'whole-block'` declares the opaque
- * focus-then-delete model, and no children means no inner surface either, so the rendered body
- * (an SVG, a toolbar) is chrome rather than the block's bytes. Its only addressable offsets are
- * 0 and `displayLength(raw)`; `selection/char-endpoint-snap.ts` is what holds selection to them.
+ * The class of block with no character positions inside it: `blockFocus: 'whole-block'` means the
+ * block is focused and deleted as one unit, and having no children means there is no editable area
+ * inside it either, so what it draws (an SVG, a toolbar) is frame rather than the block's bytes.
+ * Its only offsets are 0 and `displayLength(raw)`; `selection/char-endpoint-snap.ts` holds
+ * selection to them.
  */
 import type { NodeView } from '../core/node-views';
 export declare function isWholeBlockUnit(node: NodeView): boolean;

package/dist/schema/whole-block-unit.js

@@ -1,8 +1,9 @@
 /**
- * The kind class with no character positions: `blockFocus: 'whole-block'` declares the opaque
- * focus-then-delete model, and no children means no inner surface either, so the rendered body
- * (an SVG, a toolbar) is chrome rather than the block's bytes. Its only addressable offsets are
- * 0 and `displayLength(raw)`; `selection/char-endpoint-snap.ts` is what holds selection to them.
+ * The class of block with no character positions inside it: `blockFocus: 'whole-block'` means the
+ * block is focused and deleted as one unit, and having no children means there is no editable area
+ * inside it either, so what it draws (an SVG, a toolbar) is frame rather than the block's bytes.
+ * Its only offsets are 0 and `displayLength(raw)`; `selection/char-endpoint-snap.ts` holds
+ * selection to them.
  */
 import { tryGetBlockKindDescriptor } from './block-kind-descriptor';
 export function isWholeBlockUnit(node) {

package/dist/search/document-scan.d.ts

@@ -1,7 +1,7 @@
 import type { DocumentView } from '../core/node-views';
 import type { CompiledMatcher, RawRange } from './matcher';
-/** `start`/`end` are raw offsets into the matched block's own raw (public
- *  surface, so they stay `number`; DOM entry points mint). */
+/** `start`/`end` are raw offsets into the matched block's own raw; public API, so they
+ *  stay `number`, and the DOM entry points brand them. */
 export interface Match {
     path: number[];
     start: number;
@@ -16,7 +16,7 @@ export interface ScanTarget {
 /** The searchable leaves in document order. Split out from matching so one target list can
  *  be matched here or shipped to the off-thread executor and re-joined against its ranges. */
 export declare function collectScanTargets(doc: DocumentView): ScanTarget[];
-/** Joins per-target ranges back onto their paths, positionally — the ranges must
+/** Joins per-target ranges back onto their paths by position: the ranges must
  *  come from the same target list, in the same order. */
 export declare function matchesFromRanges(targets: readonly ScanTarget[], perTarget: readonly RawRange[][]): Match[];
 export declare function scanDocument(doc: DocumentView, matcher: CompiledMatcher): Match[];

package/dist/search/document-scan.js

@@ -15,14 +15,14 @@ export function collectScanTargets(doc) {
                 return; // container raw duplicates child content; only leaves carry text
             }
             if (!desc.editable)
-                return; // thematicBreak and other non-editable kinds have no searchable text
+                return; // non-editable kinds have no searchable text
             out.push({ path, raw: node.raw });
         });
     };
     walk(doc.children, []);
     return out;
 }
-/** Joins per-target ranges back onto their paths, positionally — the ranges must
+/** Joins per-target ranges back onto their paths by position: the ranges must
  *  come from the same target list, in the same order. */
 export function matchesFromRanges(targets, perTarget) {
     const out = [];

package/dist/search/matcher.d.ts

@@ -19,7 +19,7 @@ export type CompileResult = {
     error: string;
 };
 /** What a regex-mode query compiles to. The off-thread executor searches the same
- *  language as the synchronous matcher because both mint the spec here. */
+ *  language as the synchronous matcher because both build the spec here. */
 export interface RegexSpec {
     pattern: string;
     flags: string;