@voithos-labs/aragonite 0.10.4 → 0.10.7

package/dist/tree-operations/chain-rebuild.js

@@ -1,18 +1,24 @@
 /**
- * The ancestry rebuild: raws re-derived along an owned spine chain innermost-first, each
- * container's kind re-derived and the seam at its own slot asked on the way out (editor.md § 9).
+ * The ancestor rebuild: raws re-derived up an owned chain of ancestors innermost first, each
+ * container's kind re-derived and the joins at its own position checked on the way out
+ * (`docs/design/editor.md` § The container `raw` contract).
  */
+import { firstLineEnding } from '../core/lines';
+import { assignChildIdsDeep, idsAcrossReread } from '../block-id';
+import { ensureEditableContainers } from './node-primitives';
+import { replacePreservingFirst } from './structural-change';
+import { spliceMany } from './splice-many';
 import { dropChildSpans } from '../schema/child-spans';
-import { trimTrailingLineEnding } from '../core/lines';
+import { firstLine, followBytes, lastLine } from '../schema/container-raw';
+import { reservedChromeKindOf } from '../schema/reserved-chrome';
 import { perfEnabled, recordRebuildDepth } from '../perf/instruments';
 import { rebuildOwnedContainer, walkUnsharing } from './unshare';
 import { absorbWindowSeams } from './settle';
-import { lineOpensAs, reclassifyContainer } from './content-write';
+import { installReading } from './content-write';
 import { settleSublistSeparator } from './list/sublist-separator';
 /**
- * Longest prefix of `chain` still attached under `root`, identity-checked level by level. A
- * commit mutation can splice a node out mid-ceremony, and rebuilding the detached node's raw
- * against its emptied children writes `raw: ''`; ancestors above the detachment still rebuild.
+ * Longest prefix of `chain` still attached under `root`: a node spliced out mid-commit would
+ * rebuild against its emptied children to `raw: ''`, while the ancestors above it still rebuild.
  */
 export function attachedChainPrefix(root, chain) {
     let parentChildren = root.children;
@@ -24,59 +30,124 @@ export function attachedChainPrefix(root, chain) {
     return chain;
 }
 /**
- * Rebuild raws along an owned spine chain innermost-first, re-deriving each container's kind and
- * settling the seams at its own slot; chain- rather than path-based so it survives index shifts.
- * Both passes gate on a boundary line of the rebuilt raw moving. `folds` is required-nullable: a
- * fold splices the PARENT's array, so only a caller that reconciles that scope's ids/refs passes
- * a sink.
+ * The levels each chain rebuilds when the chains are rebuilt in this order, one per chain: a node
+ * several chains hold is left to the last of them, so it's rebuilt once, after everything below it.
  */
-export function rebuildUnsharedChain(root, chain, sharing, folds, grammar, hint) {
+export function sharedChainLevels(chains) {
+    const lastHolder = new Map();
+    chains.forEach((chain, j) => {
+        for (const node of chain)
+            lastHolder.set(node, j);
+    });
+    const readsWhole = new Set();
+    return chains.map((chain, j) => {
+        let floor = chain.length;
+        while (floor > 0 && lastHolder.get(chain[floor - 1]) === j)
+            floor--;
+        return { floor, readsWhole };
+    });
+}
+/**
+ * Rebuild raws up an owned chain innermost first, re-deriving kinds and joins where a first or
+ * last line moved. Only a caller that reconciles a merged array's ids and refs passes `folds`.
+ */
+export function rebuildUnsharedChain(root, chain, sharing, folds, grammar, hint, shared) {
     const reclassified = [];
-    // The bytes chain[i + 1] held before this pass. It rides up only from a door that named the
-    // leaf's own: a caller passing no hint re-derives at every level (editor.md § 9).
+    const floor = shared?.floor ?? 0;
+    // The bytes chain[i + 1] held before this pass, known only when the caller named the leaf's
+    // own; with no hint, every level re-derives its whole raw.
     let childPreviousRaw;
-    for (let i = chain.length - 1; i >= 0; i--) {
+    // The level below read as blocks its own position cannot hold, so this level reads whole.
+    let spilled = null;
+    for (let i = chain.length - 1; i >= floor; i--) {
         const node = chain[i];
         const rawBefore = node.raw;
         const child = chain[i + 1];
-        rebuildOwnedContainer(node, sharing, child && childPreviousRaw !== undefined
+        const changed = child && childPreviousRaw !== undefined
             ? childRawChange(node, child, childPreviousRaw, hint?.path[i + 1])
-            : undefined);
+            : undefined;
+        rebuildOwnedContainer(node, sharing, changed);
         if (hint)
             childPreviousRaw = i === chain.length - 1 ? hint.leafPreviousRaw : rawBefore;
         const openerMoved = firstLine(rawBefore) !== firstLine(node.raw);
         const closerMoved = lastLine(rawBefore) !== lastLine(node.raw);
-        if (!openerMoved && !closerMoved)
+        const whole = spilled !== null || (shared?.readsWhole.has(node) ?? false);
+        spilled = null;
+        if (!openerMoved && !closerMoved && !whole)
             continue;
         const owner = i === 0 ? null : chain[i - 1];
         const siblings = (owner ?? root).children;
         const index = siblings ? childIndexOf(siblings, node, hint?.path[i]) : -1;
         if (!siblings || index < 0)
             continue;
-        if (openerMoved && lineOpensAs(firstLine(node.raw), grammar) !== node.kind) {
-            const replacement = reclassifyContainer({ children: siblings }, index, grammar);
-            if (replacement) {
-                sharing.stamp(replacement);
-                reclassified.push({ siblings, index, previous: node, replacement });
-            }
+        const reading = followBytes(node, rawBefore, grammar, {
+            titleRowOnly: changed !== undefined && isChromeSlot(node, changed.index),
+            whole
+        });
+        const replacement = installReading({ children: siblings }, index, reading, grammar);
+        if (replacement) {
+            sharing.stamp(replacement);
+            reclassified.push({ siblings, index, previous: node, replacement });
         }
-        // Ahead of the seam ask, which then reads the settled bytes: a list rebuilt down to an
-        // empty marker owes the paragraph above it a separating line.
+        else if (reading.outcome === 'diverged' && reading.blocks.length > 0) {
+            spilled = { siblings, index, node, blocks: reading.blocks };
+        }
+        if (!openerMoved && !closerMoved)
+            continue;
+        // Before the join check, which then reads the fixed-up bytes: a list rebuilt down to an
+        // empty marker must give the paragraph above it a separating line.
         if (openerMoved)
             settleSublistSeparator(siblings, index);
-        // After the re-derive: the seam reads whatever occupies the slot now.
+        // After the kind re-derive: the join check reads whatever occupies the position now.
         if (folds) {
             const before = folds.length;
-            settleSlotSeams({ siblings, owner, depth: i, index, openerMoved, closerMoved }, sharing, folds);
-            // A fold re-tiled the owner's children, so its spans describe a shape that is gone.
+            settleSlotSeams({ siblings, owner, depth: i, index, openerMoved, closerMoved }, sharing, folds, grammar);
+            // A merge re-divided the owner's children, so its child spans describe a shape that
+            // is gone.
             if (folds.length > before && owner)
                 dropChildSpans(owner);
         }
     }
-    if (perfEnabled())
-        recordRebuildDepth(chain.length);
+    if (spilled && floor > 0)
+        shared.readsWhole.add(chain[floor - 1]);
+    else if (spilled && folds)
+        spliceSpill(spilled, sharing, folds);
+    if (perfEnabled() && chain.length > floor)
+        recordRebuildDepth(chain.length - floor);
     return reclassified;
 }
+/**
+ * The root's children take the blocks a top-level node's bytes read as, one fold the caller
+ * publishes: the first block keeps the node's id, the rest are new.
+ */
+function spliceSpill(spill, sharing, folds) {
+    const { siblings, index, node, blocks } = spill;
+    // A blank tail the parse set aside has no block to hold it, so such bytes stay as they stand.
+    if (blocks.map((block) => block.leadingTrivia + block.raw).join('') !== node.raw)
+        return;
+    const lineEnding = firstLineEnding(node.raw) ?? '\n';
+    // The first block keeps the node's id, so its children the re-read left alone keep theirs.
+    if (blocks[0].kind === node.kind && blocks[0].children) {
+        blocks[0].childIds = idsAcrossReread(node.children ?? [], node.childIds, blocks[0].children);
+    }
+    for (const block of blocks) {
+        ensureEditableContainers(block, lineEnding);
+        assignChildIdsDeep(block);
+    }
+    blocks[0].leadingTrivia = node.leadingTrivia;
+    const before = siblings.slice();
+    spliceMany(siblings, index, 1, blocks);
+    for (let k = 0; k < blocks.length; k++)
+        sharing.stamp(siblings[index + k]);
+    folds.push({
+        depth: 0,
+        siblings,
+        owner: null,
+        change: replacePreservingFirst(index, 1, blocks.length),
+        before,
+        landing: { index, offset: 0 }
+    });
+}
 /**
  * The changed-child hint for `node`, or undefined when `child` cannot be placed in it. The path
  * index is a guess; an identity match is what makes it an answer.
@@ -88,6 +159,11 @@ function childRawChange(node, child, previousRaw, guess) {
     const index = childIndexOf(siblings, child, guess);
     return index < 0 ? undefined : { index, previousRaw };
 }
+/** Whether child `index` is the container's title row, which no metadata comes from. */
+function isChromeSlot(node, index) {
+    const chromeKind = reservedChromeKindOf(node.kind);
+    return index === 0 && chromeKind !== undefined && node.children?.[0]?.kind === chromeKind;
+}
 /** `indexOf` with a guess first: the scan is O(children) through the `$state` proxy. */
 function childIndexOf(siblings, child, guess) {
     if (guess !== undefined && siblings[guess] === child)
@@ -95,17 +171,16 @@ function childIndexOf(siblings, child, guess) {
     return siblings.indexOf(child);
 }
 /**
- * Ask the joins at a rebuilt container's slot, since its new bytes can stop interrupting a
- * neighbour. `absorbWindowSeams` walks `at - 1 … at + added - 1`, so the two arguments below
- * name exactly the sides whose line moved.
+ * Check the joins at a rebuilt container's position, since its new bytes can stop interrupting
+ * a neighbour; the window passed below covers exactly the sides whose line moved.
  */
-function settleSlotSeams(slot, sharing, folds) {
+function settleSlotSeams(slot, sharing, folds, grammar) {
     const { siblings, index, openerMoved, closerMoved } = slot;
-    // The rollback snapshot is captured only once a fold is certain: an eager copy here cost
+    // The rollback snapshot is captured only once a merge is certain, since a copy costs
     // O(children) reactive reads on every keystroke inside a large container.
     let before = null;
     const landing = { index, offset: 0 };
-    const settled = absorbWindowSeams({ children: siblings }, openerMoved ? index : index + 1, openerMoved && closerMoved ? 1 : 0, index, { op: 'noop' }, sharing, landing, index, () => {
+    const settled = absorbWindowSeams({ children: siblings }, openerMoved ? index : index + 1, openerMoved && closerMoved ? 1 : 0, index, { op: 'noop' }, grammar, sharing, landing, index, () => {
         before ??= siblings.slice();
     });
     if (settled.change.op === 'noop')
@@ -120,21 +195,9 @@ function settleSlotSeams(slot, sharing, folds) {
         landing
     });
 }
-/** The container's opener line. */
-function firstLine(raw) {
-    const nl = raw.indexOf('\n');
-    return nl < 0 ? raw : raw.slice(0, nl);
-}
-/** The container's closing line: its last line carrying bytes, without the ending. */
-function lastLine(raw) {
-    const body = trimTrailingLineEnding(raw);
-    const nl = body.lastIndexOf('\n');
-    return nl < 0 ? body : body.slice(nl + 1);
-}
 /**
- * Unshare the spine to `path` and rebuild it innermost-first, tolerating paths that ran out of
- * range mid-walk (post-delete rebuild passes). Prefer `rebuildUnsharedChain` when indices may
- * have shifted since the unshare.
+ * Copy the ancestors down `path` and rebuild them, tolerating a path cut short by a delete.
+ * Prefer `rebuildUnsharedChain` when indices may have shifted since the copy.
  */
 export function rebuildUnsharedAncestry(root, path, sharing, folds, grammar) {
     const chain = walkUnsharing(root, path, sharing, false);

package/dist/tree-operations/children.d.ts

@@ -1,17 +1,13 @@
 /**
- * Container children mutations that keep `childIds` in lockstep, for out-of-commit-scope
- * writes (discovered descendants/ancestors — see the `node-primitives.ts` header). Inside a
- * commit scope the StructuralChange descriptor owns id/ref sync; here a hand-rolled
- * splice would let the parallel id array drift and break Svelte's keyed-each rendering.
- * The same shape change invalidates `childSpans`, so both parallel arrays settle here.
+ * Children mutations that keep `childIds` and `childSpans` in step, for writes outside a commit
+ * scope (descendants and ancestors found by walking the tree, `node-primitives.ts` header). A
+ * hand-rolled splice there would let the id array drift and break Svelte's keyed each.
  */
 import type { CstNode } from '../core/nodes';
 export declare function pushChild(container: CstNode, child: CstNode): void;
 /**
- * Bring `childIds` back to `children`'s length after an in-place children swap. The
- * surviving prefix keeps its ids — a blanket re-mint would remount every child under
- * Svelte's keyed each, the identity the swapping branches exist to preserve. No-op when
- * the array is absent; the mounting BlockList backfills it.
+ * Bring `childIds` back to `children`'s length after an in-place swap. The surviving prefix keeps
+ * its ids, since fresh ones would remount every child under Svelte's keyed each.
  */
 export declare function resyncChildIds(container: CstNode): void;
 export declare function spliceChildren(container: CstNode, at: number, removeCount: number, items: readonly CstNode[]): void;

package/dist/tree-operations/children.js

@@ -1,9 +1,7 @@
 /**
- * Container children mutations that keep `childIds` in lockstep, for out-of-commit-scope
- * writes (discovered descendants/ancestors — see the `node-primitives.ts` header). Inside a
- * commit scope the StructuralChange descriptor owns id/ref sync; here a hand-rolled
- * splice would let the parallel id array drift and break Svelte's keyed-each rendering.
- * The same shape change invalidates `childSpans`, so both parallel arrays settle here.
+ * Children mutations that keep `childIds` and `childSpans` in step, for writes outside a commit
+ * scope (descendants and ancestors found by walking the tree, `node-primitives.ts` header). A
+ * hand-rolled splice there would let the id array drift and break Svelte's keyed each.
  */
 import { assignIds, generateBlockId } from '../block-id';
 import { dropChildSpans } from '../schema/child-spans';
@@ -20,10 +18,8 @@ export function pushChild(container, child) {
     dropChildSpans(container);
 }
 /**
- * Bring `childIds` back to `children`'s length after an in-place children swap. The
- * surviving prefix keeps its ids — a blanket re-mint would remount every child under
- * Svelte's keyed each, the identity the swapping branches exist to preserve. No-op when
- * the array is absent; the mounting BlockList backfills it.
+ * Bring `childIds` back to `children`'s length after an in-place swap. The surviving prefix keeps
+ * its ids, since fresh ones would remount every child under Svelte's keyed each.
  */
 export function resyncChildIds(container) {
     dropChildSpans(container);
@@ -45,8 +41,8 @@ export function spliceChildren(container, at, removeCount, items) {
         container.children = [];
     // No lazy-init here: containers without childIds get them from the mounting BlockList anyway.
     if (container.childIds) {
-        // A replacement's head continues the slot it lands in, so it keeps that slot's id —
-        // `replacePreservingFirst`'s rule, which the in-commit-scope splice already carries.
+        // A replacement's head continues the position it lands in, so it keeps that position's
+        // id: `replacePreservingFirst`'s rule, which the in-commit splice already applies.
         const continues = removeCount > 0 && items.length > 0;
         const ids = items.map((_, i) => i === 0 && continues ? container.childIds[at] : generateBlockId());
         spliceMany(container.childIds, at, removeCount, ids);

package/dist/tree-operations/cleanup.d.ts

@@ -1,10 +1,9 @@
-import type { Document } from '../core/nodes';
+import type { CstNode, Document } from '../core/nodes';
+import type { GrammarView } from '../schema/block-openers';
 import type { SharingState } from './sharing';
 /**
- * Walk up from `deletedPath`'s parent, removing containers emptied by the cleanup. Stops
- * at `lcaPath` (the range operation's lowest common ancestor, `[]` for the document root)
- * because containers at or above it still hold the start block and cannot legitimately be
- * empty. Owns its spine — each level is unshared before its child is removed, or the
- * splice lands on a node an undo entry still references (`unshare.ts` header).
+ * Remove the containers a delete emptied, walking up from `deletedPath`'s parent (a path below
+ * `root`) to the first that still holds a child; `root` itself is never spliced. Walking from the
+ * document it can splice the document's own children, so the commit must hold that scope.
  */
-export declare function cascadeCleanupEmptyAncestors(doc: Document, deletedPath: number[], lcaPath: number[], sharing: SharingState): void;
+export declare function cascadeCleanupEmptyAncestors(root: CstNode | Document, deletedPath: number[], sharing: SharingState, grammar: GrammarView): void;

package/dist/tree-operations/cleanup.js

@@ -1,25 +1,28 @@
+import { mustHoldChild } from '../schema/block-kind-descriptor';
 import { spliceChildrenSettled } from './settle';
 import { ensureUnsharedPath } from './unshare';
 /**
- * Walk up from `deletedPath`'s parent, removing containers emptied by the cleanup. Stops
- * at `lcaPath` (the range operation's lowest common ancestor, `[]` for the document root)
- * because containers at or above it still hold the start block and cannot legitimately be
- * empty. Owns its spine — each level is unshared before its child is removed, or the
- * splice lands on a node an undo entry still references (`unshare.ts` header).
+ * Remove the containers a delete emptied, walking up from `deletedPath`'s parent (a path below
+ * `root`) to the first that still holds a child; `root` itself is never spliced. Walking from the
+ * document it can splice the document's own children, so the commit must hold that scope.
  */
-export function cascadeCleanupEmptyAncestors(doc, deletedPath, lcaPath, sharing) {
+export function cascadeCleanupEmptyAncestors(root, deletedPath, sharing, grammar) {
+    if (!root.children)
+        return;
+    // The same array as the root's, so the walk's copies land in the root.
+    const top = { children: root.children };
     let currentPath = deletedPath.slice(0, -1);
-    while (currentPath.length > lcaPath.length) {
+    while (currentPath.length > 0) {
         const parentPath = currentPath.slice(0, -1);
-        const chain = ensureUnsharedPath(doc, parentPath, sharing);
-        const parent = chain[chain.length - 1] ?? doc;
+        const chain = ensureUnsharedPath(top, parentPath, sharing);
+        const parent = chain[chain.length - 1] ?? root;
         if (!parent.children)
             break;
         const idx = currentPath[currentPath.length - 1];
         const node = parent.children[idx];
-        if (!node || !node.children || node.children.length > 0)
+        if (!node || !mustHoldChild(node.kind) || (node.children?.length ?? 0) > 0)
             break;
-        spliceChildrenSettled(parent, idx, 1, [], sharing);
+        spliceChildrenSettled(parent, idx, 1, [], grammar, sharing);
         currentPath = parentPath;
     }
 }

package/dist/tree-operations/clone.js

@@ -1,7 +1,8 @@
 import { assertInvariant } from '../assert';
 import { checkCloneSafeMetadata } from '../invariants/node-shape';
 // ── Document ────────────────────────────────────────────────────────────────
-// A deep clone of a view is a fully owned mutable tree — the clone door (core/node-views.ts).
+// A deep clone of a view is a fully owned mutable tree, the one clone path `core/node-views.ts`
+// allows.
 export function cloneDocument(doc) {
     return {
         kind: 'document',
@@ -12,8 +13,8 @@ export function cloneDocument(doc) {
 }
 // ── Node ────────────────────────────────────────────────────────────────────
 export function cloneNode(node) {
-    // `kind` is a runtime value spanning every arm, so no literal arm matches —
-    // the cast is the generic-clone door, mirroring copyNode's spread (unshare.ts).
+    // `kind` is a runtime value spanning every union member, so no literal member matches; the
+    // cast is the generic clone, mirroring `copyNode`'s spread (`unshare.ts`).
     const cloned = {
         kind: node.kind,
         leadingTrivia: node.leadingTrivia,
@@ -33,7 +34,7 @@ export function cloneNode(node) {
     return cloned;
 }
 // Snapshots must share no mutable reference with the live tree, or an in-place splice on
-// live metadata reaches the snapshot. One level deep suffices — G1.6 forbids deeper.
+// live metadata reaches the snapshot. One level deep suffices; metadata nests no deeper (G1.6).
 export function cloneMetadata(meta) {
     const out = {};
     for (const [k, v] of Object.entries(meta)) {

package/dist/tree-operations/container-lift.d.ts

@@ -1,9 +1,14 @@
 /**
- * Lift a container's first child out while the container itself survives (Rule U2's other
- * shape): the remainder keeps its kind and its `rebuildRaw` re-emits the syntax, so a marker
- * held in metadata rides through. `blockquote.ts`'s `unwrapFirstChildFromQuote` is the shape
- * where the opener lives on the first line and the lift drops it.
+ * Lift a container's first child out, input untouched: the blank line that stood between that
+ * child and the next one now stands between the lifted block and what is left of the container.
+ * The caller says how the rest is written back: as the same container, or as a plain quote.
  */
 import type { CstNode } from '../core/nodes';
 import type { NodeView } from '../core/node-views';
-export declare function liftFirstChildKeepingContainer(container: NodeView): CstNode[];
+import type { GrammarView } from '../schema/block-openers';
+/** The container's remaining children written back as one block; its own raw included. */
+export type RemainderBuilder = (container: NodeView, children: CstNode[]) => CstNode;
+export declare function liftFirstChild(container: NodeView, rebuildRemainder: RemainderBuilder): CstNode[];
+/** The remainder keeps the container's kind, and its `rebuildRaw` re-emits the syntax, so a
+ *  marker held in metadata survives. */
+export declare function sameContainer(grammar: GrammarView): RemainderBuilder;

package/dist/tree-operations/container-lift.js

@@ -1,29 +1,35 @@
 /**
- * Lift a container's first child out while the container itself survives (Rule U2's other
- * shape): the remainder keeps its kind and its `rebuildRaw` re-emits the syntax, so a marker
- * held in metadata rides through. `blockquote.ts`'s `unwrapFirstChildFromQuote` is the shape
- * where the opener lives on the first line and the lift drops it.
+ * Lift a container's first child out, input untouched: the blank line that stood between that
+ * child and the next one now stands between the lifted block and what is left of the container.
+ * The caller says how the rest is written back: as the same container, or as a plain quote.
  */
 import { cloneNode } from './clone';
 import { rebuildContainerRaw } from '../schema/container-raw';
 import { assignIds } from '../block-id';
-export function liftFirstChildKeepingContainer(container) {
+export function liftFirstChild(container, rebuildRemainder) {
     const children = container.children;
     if (!children || children.length === 0)
         return [];
     const lifted = cloneNode(children[0]);
-    // The container's leading trivia is applied at the caller's splice point.
+    // The container's leading blank lines are applied at the caller's splice point.
     lifted.leadingTrivia = '';
     if (children.length === 1)
         return [lifted];
-    const remaining = cloneNode(container);
-    const remainingChildren = remaining.children.slice(1);
-    // The blank line that stood between the two children inside the container is the one that
-    // now stands between the lifted block and the container: conserved, never minted.
-    remaining.leadingTrivia = remainingChildren[0].leadingTrivia;
+    const remainingChildren = children.slice(1).map(cloneNode);
+    const separator = remainingChildren[0].leadingTrivia;
     remainingChildren[0].leadingTrivia = '';
-    remaining.children = remainingChildren;
-    remaining.childIds = assignIds(remainingChildren);
-    rebuildContainerRaw(remaining);
+    const remaining = rebuildRemainder(container, remainingChildren);
+    remaining.leadingTrivia = separator;
     return [lifted, remaining];
 }
+/** The remainder keeps the container's kind, and its `rebuildRaw` re-emits the syntax, so a
+ *  marker held in metadata survives. */
+export function sameContainer(grammar) {
+    return (container, children) => {
+        const remaining = cloneNode(container);
+        remaining.children = children;
+        remaining.childIds = assignIds(children);
+        rebuildContainerRaw(remaining, grammar);
+        return remaining;
+    };
+}

package/dist/tree-operations/container-offsets.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Maps between a byte offset in a block's `raw` and a caret position in one of its leaves, for a
+ * fix-up that tracks the caret through a merge. A container's raw re-prefixes its children's lines
+ * (`> `, an item's indent), so the map goes line by line; only a `'strip'` container's is known.
+ */
+import type { NodeView } from '../core/node-views';
+export interface LeafPosition {
+    /** Child indices from the node down to the leaf; empty when the node is the leaf. */
+    path: number[];
+    /** Offset into the leaf's raw, within its displayed text. */
+    offset: number;
+}
+/**
+ * The leaf and offset `rawOffset` addresses inside `node`; null when a container on the way is
+ * not a strip container, whose bytes this module can't map to its children.
+ */
+export declare function leafAtRawOffset(node: NodeView, rawOffset: number): LeafPosition | null;
+/**
+ * The offset into `node`'s raw that the position `offset` in the leaf at `path` sits at: the
+ * inverse of {@link leafAtRawOffset}, with the same refusal.
+ */
+export declare function rawOffsetOfLeaf(node: NodeView, path: readonly number[], offset: number): number | null;

package/dist/tree-operations/container-offsets.js

@@ -0,0 +1,89 @@
+/**
+ * Maps between a byte offset in a block's `raw` and a caret position in one of its leaves, for a
+ * fix-up that tracks the caret through a merge. A container's raw re-prefixes its children's lines
+ * (`> `, an item's indent), so the map goes line by line; only a `'strip'` container's is known.
+ */
+import { displayLength, splitLines } from '../core/lines';
+import { tryGetBlockKindDescriptor } from '../schema/block-kind-descriptor';
+// ── Public API ───────────────────────────────────────────────────────────────
+/**
+ * The leaf and offset `rawOffset` addresses inside `node`; null when a container on the way is
+ * not a strip container, whose bytes this module can't map to its children.
+ */
+export function leafAtRawOffset(node, rawOffset) {
+    const descriptor = tryGetBlockKindDescriptor(node.kind);
+    if (!descriptor?.isContainer || !node.children?.length) {
+        return { path: [], offset: Math.min(Math.max(rawOffset, 0), displayLength(node.raw)) };
+    }
+    if (descriptor.containerContract !== 'strip')
+        return null;
+    const inner = bodyOffsetOf(node, rawOffset) - (node.innerPrefix ?? '').length;
+    const children = node.children;
+    let at = 0;
+    for (let i = 0; i < children.length; i++) {
+        const start = at + children[i].leadingTrivia.length;
+        const end = start + displayLength(children[i].raw);
+        if (inner <= end || i === children.length - 1) {
+            const leaf = leafAtRawOffset(children[i], Math.max(inner - start, 0));
+            return leaf && { path: [i, ...leaf.path], offset: leaf.offset };
+        }
+        at = start + children[i].raw.length;
+    }
+    return null;
+}
+/**
+ * The offset into `node`'s raw that the position `offset` in the leaf at `path` sits at: the
+ * inverse of {@link leafAtRawOffset}, with the same refusal.
+ */
+export function rawOffsetOfLeaf(node, path, offset) {
+    if (path.length === 0)
+        return offset;
+    const descriptor = tryGetBlockKindDescriptor(node.kind);
+    const children = node.children;
+    if (descriptor?.containerContract !== 'strip' || !children?.[path[0]])
+        return null;
+    const inChild = rawOffsetOfLeaf(children[path[0]], path.slice(1), offset);
+    if (inChild === null)
+        return null;
+    let inner = (node.innerPrefix ?? '').length;
+    for (let i = 0; i < path[0]; i++)
+        inner += children[i].leadingTrivia.length + children[i].raw.length;
+    inner += children[path[0]].leadingTrivia.length + inChild;
+    return rawOffsetOfBody(node, inner);
+}
+function lineTable(node) {
+    const body = (node.innerPrefix ?? '') +
+        (node.children ?? []).map((child) => child.leadingTrivia + child.raw).join('') +
+        (node.innerSuffix ?? '');
+    const raw = splitLines(node.raw);
+    const bodyLines = splitLines(body);
+    return { raw, body: bodyLines, shift: Math.max(raw.length - bodyLines.length, 0) };
+}
+/** How many bytes the container writes in front of a body line: the raw line's extra length. */
+const prefixLength = (raw, body) => Math.max(raw.text.length - body.text.length, 0);
+function bodyOffsetOf(node, rawOffset) {
+    const { raw, body, shift } = lineTable(node);
+    const r = lineHolding(raw, rawOffset);
+    const b = r - shift;
+    if (b < 0 || !body[b])
+        return b < 0 ? 0 : (body.at(-1)?.end ?? 0);
+    const column = Math.min(rawOffset - raw[r].start, raw[r].text.length);
+    const inBody = Math.min(Math.max(column - prefixLength(raw[r], body[b]), 0), body[b].text.length);
+    return body[b].start + inBody;
+}
+function rawOffsetOfBody(node, bodyOffset) {
+    const { raw, body, shift } = lineTable(node);
+    const b = lineHolding(body, bodyOffset);
+    const r = b + shift;
+    if (!raw[r] || !body[b])
+        return raw.at(-1)?.end ?? 0;
+    const column = Math.min(bodyOffset - body[b].start, body[b].text.length);
+    return raw[r].start + Math.min(prefixLength(raw[r], body[b]) + column, raw[r].text.length);
+}
+/** The index of the line `offset` falls on; an offset on a line's ending counts as that line. */
+function lineHolding(lines, offset) {
+    for (let i = 0; i < lines.length; i++)
+        if (offset < lines[i].end)
+            return i;
+    return Math.max(lines.length - 1, 0);
+}