@voithos-labs/aragonite 0.10.4 → 0.10.7

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

@@ -1,8 +1,8 @@
 /**
- * Structural-sharing epoch primitive — the copy-on-write engine `unshare.ts` reads to
- * decide when a node must be cloned before it is written. The undo lifecycle bumps the
- * epoch, after which any node stamped earlier counts as shared. A missing `ownerEpoch`
- * counts as shared too: an unnecessary copy is correct, a missed one corrupts history.
+ * The generation counter `unshare.ts` reads to decide whether a node must be copied before it
+ * is written. Undo bumps the counter at every snapshot and restore, after which any node marked
+ * earlier counts as shared. A missing `ownerEpoch` counts as shared too: an unnecessary copy is
+ * correct, a missed one corrupts history.
  */
 export interface SharingState {
     /** Bump after every snapshot push and every undo/redo restore. */
@@ -10,7 +10,7 @@ export interface SharingState {
     isShared(node: {
         ownerEpoch?: number;
     }): boolean;
-    /** Stamp a freshly created/copied node as owned by the live tree. */
+    /** Mark a freshly created or copied node as owned by the live tree. */
     stamp(node: {
         ownerEpoch?: number;
     }): void;

package/dist/tree-operations/splice-many.d.ts

@@ -1,9 +1,9 @@
 /**
- * The splice every mutation door owes a document-scaled list. A spread hands the engine one
- * argument per item, and a list past its argument limit raises "Maximum call stack size exceeded"
- * at the call (G4.60), so a list too long for one call goes in chunks. Splices in place, so the
- * array keeps its identity and a `$state` proxy sees the writes a hand-rolled splice would make.
+ * The splice every mutation must use on a document-sized list. A spread hands the JavaScript
+ * runtime one argument per item, and a list past its argument limit raises "Maximum call stack
+ * size exceeded" at the call (G4.60), so a list too long for one call goes in chunks. Splices in
+ * place, so the array keeps its identity and a `$state` proxy sees the writes.
  */
-/** Well under the engine's argument ceiling, which measures around 125,000 on a desktop V8. */
+/** Well under V8's argument limit, which measures around 125,000 on a desktop. */
 export declare const INSERT_CHUNK = 50000;
 export declare function spliceMany<T>(target: T[], at: number, deleteCount: number, items: readonly T[]): void;

package/dist/tree-operations/splice-many.js

@@ -1,10 +1,10 @@
 /**
- * The splice every mutation door owes a document-scaled list. A spread hands the engine one
- * argument per item, and a list past its argument limit raises "Maximum call stack size exceeded"
- * at the call (G4.60), so a list too long for one call goes in chunks. Splices in place, so the
- * array keeps its identity and a `$state` proxy sees the writes a hand-rolled splice would make.
+ * The splice every mutation must use on a document-sized list. A spread hands the JavaScript
+ * runtime one argument per item, and a list past its argument limit raises "Maximum call stack
+ * size exceeded" at the call (G4.60), so a list too long for one call goes in chunks. Splices in
+ * place, so the array keeps its identity and a `$state` proxy sees the writes.
  */
-/** Well under the engine's argument ceiling, which measures around 125,000 on a desktop V8. */
+/** Well under V8's argument limit, which measures around 125,000 on a desktop. */
 export const INSERT_CHUNK = 50_000;
 export function spliceMany(target, at, deleteCount, items) {
     // One call while the list fits in one: splitting the delete off costs a second O(n) shift of

package/dist/tree-operations/stored-as.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The one maker of `StoredAs`: how a leaf position stores and reads back bytes, derived from the
+ * tree. A store reads the tree the first time it is asked and keeps that answer, so make one per
+ * gesture, at the gesture, and drop it after (`docs/design/live-mode.md` § 4.5).
+ */
+import type { DocumentView } from '../core/node-views';
+import type { Reading } from '../schema/reading';
+import type { StoredAs } from '../schema/stored-as';
+import { type WriteTarget } from './content-write';
+/** The leaf at `path` in `doc`: the store its bytes go through, read when first asked. */
+export declare function storedAsAt(doc: DocumentView, path: readonly number[], reading: Reading): StoredAs;
+/** The same for slot `index` of a holder a caller already walked to, such as a join's target. */
+export declare function storedAsIn(holder: WriteTarget, index: number, reading: Reading): StoredAs;

package/dist/tree-operations/stored-as.js

@@ -0,0 +1,48 @@
+/**
+ * The one maker of `StoredAs`: how a leaf position stores and reads back bytes, derived from the
+ * tree. A store reads the tree the first time it is asked and keeps that answer, so make one per
+ * gesture, at the gesture, and drop it after (`docs/design/live-mode.md` § 4.5).
+ */
+import { documentLineEnding } from '../core/lines';
+import { tryGetBlockKindDescriptor } from '../schema/block-kind-descriptor';
+import { legalizeWrite } from './content-write';
+import { childSlotAt, fragmentReaderAt, readThroughItemMarker } from './list/task-paragraph';
+/** The leaf at `path` in `doc`: the store its bytes go through, read when first asked. */
+export function storedAsAt(doc, path, reading) {
+    return storeOver(reading, () => {
+        const { owner, index } = childSlotAt(doc, path);
+        const holder = owner
+            ? { owner, children: owner.children ?? [], lineEnding: documentLineEnding(doc) }
+            : doc;
+        return { holder, index };
+    });
+}
+/** The same for slot `index` of a holder a caller already walked to, such as a join's target. */
+export function storedAsIn(holder, index, reading) {
+    return storeOver(reading, () => ({ holder, index }));
+}
+function storeOver(reading, locate) {
+    let found;
+    const slot = () => (found ??= locate());
+    return {
+        reading,
+        get surface() {
+            const { holder, index } = slot();
+            // A kind with no recognizer of its own stores text the parser never reads as a block.
+            const kind = holder.children[index].kind;
+            return tryGetBlockKindDescriptor(kind)?.contextDependentKind ? 'inline' : 'block';
+        },
+        stored(bytes) {
+            const { holder, index } = slot();
+            return legalizeWrite(holder, index, bytes, 'literal').text;
+        },
+        readSlot(stored) {
+            const { holder, index } = slot();
+            const owner = 'owner' in holder ? holder.owner : undefined;
+            if (index === 0 && owner?.kind === 'listItem') {
+                return readThroughItemMarker(owner, stored, reading.grammar);
+            }
+            return fragmentReaderAt(owner, index, reading.grammar)(stored);
+        }
+    };
+}

package/dist/tree-operations/structural-change.d.ts

@@ -1,8 +1,8 @@
 /**
- * Structural-change descriptor returned by tree ops; the commit primitive consumes it to
- * auto-sync the parallel `blockIds` / `blockRefs` arrays, so callers never hand-splice
- * them. Every variant describes ONE contiguous `at`/`count` window — an op editing two
- * disjoint ranges splits into separate commits or uses the multi-scope commit path.
+ * The change descriptor a tree op returns; the commit consumes it to keep the parallel
+ * `blockIds` / `blockRefs` arrays in step, so callers never splice them by hand. Every variant
+ * describes one contiguous `at`/`count` window: an op editing two disjoint ranges splits into
+ * separate commits or uses the multi-scope commit.
  */
 import type { BlockComponent } from '../block-component';
 import type { CstNode } from '../core/nodes';
@@ -26,16 +26,13 @@ export type StructuralChange = {
     idMap?: Record<number, number>;
 };
 /**
- * Replace [at, at+count) where the FIRST new item inherits the old first item's id + ref,
- * preserving Svelte keyed identity (cursor, IME composition) across the swap.
+ * Replace [at, at+count), the first new item keeping the first replaced item's id and ref so its
+ * component (caret, IME composition) survives the swap.
  */
 export declare function replacePreservingFirst(at: number, count: number, newCount: number): StructuralChange;
 /**
- * Stamp the nodes a change's insert/replace window CREATED as owned by the live tree;
- * pre-existing nodes go through `unshare.ts` instead. Also backfills `childIds` on
- * containers in a created subtree, before the commit publishes: a freshly-parsed node
- * carries none, and under a reused component instance the nested keyed `{#each}` renders
- * before the re-init effect, so undefined keys would reach Svelte.
+ * Mark the nodes the change's window created as owned by the live tree, and give every container
+ * in them `childIds`, since a reused component's keyed `{#each}` renders before its re-init.
  */
 export declare function stampStructuralChange(children: CstNode[], change: StructuralChange, sharing: SharingState): void;
 /**
@@ -43,15 +40,14 @@ export declare function stampStructuralChange(children: CstNode[], change: Struc
  * IDs + undefined refs; `idMap` on replace preserves specified old-index IDs.
  */
 export declare function applyStructuralChangeToIdsRefs(change: StructuralChange, ids: string[], refs: (BlockComponent | undefined)[]): void;
-/** A parent whose parallel id array the splice doors maintain: a container, or the root. */
+/** A parent whose parallel id array the splice functions maintain: a container, or the root. */
 type IdCarrier = {
     children?: CstNode[];
     childIds?: string[];
 };
 /**
- * Borrow `parent.childIds` as the ledger the splice doors write their net splice into, so a
- * caller running several of them reports what they add up to instead of re-deriving it from
- * lengths (a settle's fold moves slots the caller's own window never named).
+ * Borrow `parent.childIds` to record what several splice functions add up to, since a merge in
+ * the fix-up moves positions the caller's own window never named.
  */
 export declare function trackChildIds(parent: IdCarrier): {
     read: () => StructuralChange;

package/dist/tree-operations/structural-change.js

@@ -1,26 +1,23 @@
 /**
- * Structural-change descriptor returned by tree ops; the commit primitive consumes it to
- * auto-sync the parallel `blockIds` / `blockRefs` arrays, so callers never hand-splice
- * them. Every variant describes ONE contiguous `at`/`count` window — an op editing two
- * disjoint ranges splits into separate commits or uses the multi-scope commit path.
+ * The change descriptor a tree op returns; the commit consumes it to keep the parallel
+ * `blockIds` / `blockRefs` arrays in step, so callers never splice them by hand. Every variant
+ * describes one contiguous `at`/`count` window: an op editing two disjoint ranges splits into
+ * separate commits or uses the multi-scope commit.
  */
 import { generateBlockId, assignChildIdsDeep, assignIds } from '../block-id';
 import { spliceMany } from './splice-many';
 import { assertInvariant } from '../assert';
 import { checkStructuralDescriptor } from '../invariants/structural-descriptor';
 /**
- * Replace [at, at+count) where the FIRST new item inherits the old first item's id + ref,
- * preserving Svelte keyed identity (cursor, IME composition) across the swap.
+ * Replace [at, at+count), the first new item keeping the first replaced item's id and ref so its
+ * component (caret, IME composition) survives the swap.
  */
 export function replacePreservingFirst(at, count, newCount) {
     return { op: 'replace', at, count, newCount, idMap: { 0: 0 } };
 }
 /**
- * Stamp the nodes a change's insert/replace window CREATED as owned by the live tree;
- * pre-existing nodes go through `unshare.ts` instead. Also backfills `childIds` on
- * containers in a created subtree, before the commit publishes: a freshly-parsed node
- * carries none, and under a reused component instance the nested keyed `{#each}` renders
- * before the re-init effect, so undefined keys would reach Svelte.
+ * Mark the nodes the change's window created as owned by the live tree, and give every container
+ * in them `childIds`, since a reused component's keyed `{#each}` renders before its re-init.
  */
 export function stampStructuralChange(children, change, sharing) {
     if (change.op !== 'insert' && change.op !== 'replace')
@@ -65,9 +62,8 @@ export function applyStructuralChangeToIdsRefs(change, ids, refs) {
     }
 }
 /**
- * Borrow `parent.childIds` as the ledger the splice doors write their net splice into, so a
- * caller running several of them reports what they add up to instead of re-deriving it from
- * lengths (a settle's fold moves slots the caller's own window never named).
+ * Borrow `parent.childIds` to record what several splice functions add up to, since a merge in
+ * the fix-up moves positions the caller's own window never named.
  */
 export function trackChildIds(parent) {
     const had = parent.childIds;

package/dist/tree-operations/structural-suffix.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Where a cut through a heading leaves its structure: the marker in front of the text and the
+ * bytes past it (a closing `#` run, a setext underline) stay with the text. Every split, paste
+ * and join that divides a block at a caret cuts through here (`docs/design/editor.md` § 8).
+ */
+import type { NodeView } from '../core/node-views';
+/** `node`'s text cut at `offset` for a split or a paste, both halves without a final line ending.
+ *  A cut at or before an ATX heading's text moves the whole heading into `rest`. */
+export declare function cutKeepingStructure(node: NodeView, offset: number): {
+    head: string;
+    rest: string;
+};
+/** A cut into `node` moved out of its structural suffix: a join or a truncation that keeps the
+ *  block's head keeps the suffix whole after it. */
+export declare function cutBeforeSuffix(node: NodeView, cut: number): number;
+/** The bytes of a join: `survivor` cut at `cut`, `absorbed`'s text from `from` through `writeTail`
+ *  (the absorbed kind's write rule), then the survivor's structural suffix. */
+export declare function joinKeepingSuffix(survivor: NodeView, cut: number, absorbed: NodeView, from: number, writeTail: (tail: string) => string): {
+    raw: string;
+    start: number;
+    end: number;
+};

package/dist/tree-operations/structural-suffix.js

@@ -0,0 +1,61 @@
+/**
+ * Where a cut through a heading leaves its structure: the marker in front of the text and the
+ * bytes past it (a closing `#` run, a setext underline) stay with the text. Every split, paste
+ * and join that divides a block at a caret cuts through here (`docs/design/editor.md` § 8).
+ */
+import { headingLevel } from '../core/nodes';
+import { getContentRange, structuralSuffix } from '../core/inline';
+import { displayLength, ownTrailingLineEnding, snapToScalarBoundary, trimTrailingLineEnding } from '../core/lines';
+/** `node`'s text cut at `offset` for a split or a paste, both halves without a final line ending.
+ *  A cut at or before an ATX heading's text moves the whole heading into `rest`. */
+export function cutKeepingStructure(node, offset) {
+    const display = trimTrailingLineEnding(node.raw);
+    // The cut leaves a surrogate pair whole, since its halves would land in different blocks.
+    const cut = headingHeadCut(node, snapToScalarBoundary(display, offset));
+    const suffix = structuralSuffix(node);
+    const textEnd = display.length - suffix.length;
+    if (suffix === '' || cut === 0 || cut > textEnd) {
+        return { head: display.slice(0, cut), rest: display.slice(cut) };
+    }
+    // A remainder opening with a whitespace-only line reloads as blank, so the head takes it.
+    const wsLine = /^[ \t]+\r?\n/.exec(display.slice(cut, textEnd))?.[0] ?? '';
+    return {
+        // The suffix opens with the ending of the line it follows, so one already on the head goes.
+        head: trimTrailingLineEnding(display.slice(0, cut) + trimTrailingLineEnding(wsLine)) + suffix,
+        rest: display.slice(cut + wsLine.length, textEnd)
+    };
+}
+function headingHeadCut(node, cut) {
+    if (headingLevel(node) === null)
+        return cut;
+    const content = getContentRange(node);
+    if (content.start === 0 || content.end === content.start)
+        return cut;
+    return cut <= content.start ? 0 : cut;
+}
+/** A cut into `node` moved out of its structural suffix: a join or a truncation that keeps the
+ *  block's head keeps the suffix whole after it. */
+export function cutBeforeSuffix(node, cut) {
+    const suffix = structuralSuffix(node);
+    return suffix ? Math.min(cut, displayLength(node.raw) - suffix.length) : cut;
+}
+/** The bytes of a join: `survivor` cut at `cut`, `absorbed`'s text from `from` through `writeTail`
+ *  (the absorbed kind's write rule), then the survivor's structural suffix. */
+export function joinKeepingSuffix(survivor, cut, absorbed, from, writeTail) {
+    const kept = structuralSuffix(survivor);
+    const dropped = structuralSuffix(absorbed);
+    const start = cutBeforeSuffix(survivor, cut);
+    const textEnd = displayLength(absorbed.raw) - dropped.length;
+    const end = dropped ? Math.min(from, textEnd) : from;
+    const tail = writeTail(dropped
+        ? absorbed.raw.slice(end, textEnd) + ownTrailingLineEnding(absorbed.raw)
+        : absorbed.raw.slice(end));
+    return {
+        raw: survivor.raw.slice(0, start) +
+            trimTrailingLineEnding(tail) +
+            kept +
+            ownTrailingLineEnding(tail),
+        start,
+        end
+    };
+}

package/dist/tree-operations/sub-table-copy.d.ts

@@ -1,6 +1,13 @@
+/**
+ * A rectangle of a table's cells as clipboard text: a GFM table of its own, written by the table
+ * rebuilder so its rows, padding and line ending are the ones the document's table has.
+ */
 import type { NodeView } from '../core/node-views';
 export interface CellPos {
     rowIdx: number;
     colIdx: number;
 }
+/** The rectangle as a GFM table, its first row the header; one cell is its raw alone. */
 export declare function copyRectangleAsSubTable(table: NodeView, a: CellPos, b: CellPos): string;
+/** The raws of the cells between two corners, row by row; a missing cell reads empty. */
+export declare function rectangleCellRaws(table: NodeView, a: CellPos, b: CellPos): string[][];

package/dist/tree-operations/sub-table-copy.js

@@ -1,43 +1,47 @@
+/**
+ * A rectangle of a table's cells as clipboard text: a GFM table of its own, written by the table
+ * rebuilder so its rows, padding and line ending are the ones the document's table has.
+ */
 import { metadataOf } from '../core/nodes';
+import { rebuildTableRaw, tableLineEnding } from '../schema/container-rebuilders';
+/** The rectangle as a GFM table, its first row the header; one cell is its raw alone. */
 export function copyRectangleAsSubTable(table, a, b) {
-    const minRow = Math.min(a.rowIdx, b.rowIdx);
-    const maxRow = Math.max(a.rowIdx, b.rowIdx);
-    const minCol = Math.min(a.colIdx, b.colIdx);
-    const maxCol = Math.max(a.colIdx, b.colIdx);
+    const cellRaws = rectangleCellRaws(table, a, b);
+    if (cellRaws.length === 1 && cellRaws[0].length === 1)
+        return cellRaws[0][0];
+    const left = Math.min(a.colIdx, b.colIdx);
+    const alignments = metadataOf(table, 'table').alignments.slice(left, left + cellRaws[0].length);
+    return subTable(cellRaws, alignments, tableLineEnding(table)).raw;
+}
+/** The raws of the cells between two corners, row by row; a missing cell reads empty. */
+export function rectangleCellRaws(table, a, b) {
     const rows = table.children ?? [];
-    const cellRaws = [];
-    for (let r = minRow; r <= maxRow; r++) {
-        const rowCells = rows[r]?.children ?? [];
-        const slice = [];
-        for (let c = minCol; c <= maxCol; c++) {
-            slice.push(rowCells[c]?.raw ?? '');
+    const grid = [];
+    for (let r = Math.min(a.rowIdx, b.rowIdx); r <= Math.max(a.rowIdx, b.rowIdx); r++) {
+        const cells = rows[r]?.children ?? [];
+        const line = [];
+        for (let c = Math.min(a.colIdx, b.colIdx); c <= Math.max(a.colIdx, b.colIdx); c++) {
+            line.push(cells[c]?.raw ?? '');
         }
-        cellRaws.push(slice);
-    }
-    if (cellRaws.length === 1 && cellRaws[0].length === 1) {
-        return cellRaws[0][0];
+        grid.push(line);
     }
-    const alignments = metadataOf(table, 'table').alignments.slice(minCol, maxCol + 1);
-    const lines = [];
-    lines.push(formatRow(cellRaws[0]));
-    lines.push(formatRow(alignments.map(formatAlignmentCell)));
-    for (let i = 1; i < cellRaws.length; i++) {
-        lines.push(formatRow(cellRaws[i]));
-    }
-    return lines.join('');
-}
-function formatRow(cells) {
-    return '| ' + cells.join(' | ') + ' |\n';
+    return grid;
 }
-function formatAlignmentCell(alignment) {
-    switch (alignment) {
-        case 'left':
-            return ':---';
-        case 'center':
-            return ':---:';
-        case 'right':
-            return '---:';
-        default:
-            return '---';
-    }
+function subTable(cellRaws, alignments, lineEnding) {
+    const table = {
+        kind: 'table',
+        leadingTrivia: '',
+        // The rebuild reads the line ending off the raw it replaces.
+        raw: lineEnding,
+        metadata: { columnCount: alignments.length, alignments },
+        children: cellRaws.map((cells, i) => ({
+            kind: 'tableRow',
+            leadingTrivia: '',
+            raw: '',
+            metadata: { isHeader: i === 0 },
+            children: cells.map((raw) => ({ kind: 'tableCell', leadingTrivia: '', raw }))
+        }))
+    };
+    rebuildTableRaw(table);
+    return table;
 }

package/dist/tree-operations/table-grid-clipboard.d.ts

@@ -5,16 +5,11 @@
  * inverse, an HTML table for the spreadsheets that read text/html, lives here too.
  */
 import type { NodeView } from '../core/node-views';
+import { type CellPos } from './sub-table-copy';
 /** Rows of cell texts, rectangular: every row padded to the widest. Null for a non-grid payload. */
 export declare function parseClipboardGrid(text: string): string[][] | null;
 /** A rectangle's cell texts, pipes unescaped, as the clipboard's grid. */
-export declare function rectangleGrid(table: NodeView, a: {
-    rowIdx: number;
-    colIdx: number;
-}, b: {
-    rowIdx: number;
-    colIdx: number;
-}): string[][];
+export declare function rectangleGrid(table: NodeView, a: CellPos, b: CellPos): string[][];
 /** The grid repeated to fill a selection whose sides are multiples of it (a spreadsheet's
  *  tiling); any other selection takes the grid once from its top-left corner. */
 export declare function tileGridTo(grid: string[][], rows: number, cols: number): string[][];

package/dist/tree-operations/table-grid-clipboard.js

@@ -4,10 +4,14 @@
  * rectangle copy writes). Anything else is not a grid and takes the ordinary paste route. The
  * inverse, an HTML table for the spreadsheets that read text/html, lives here too.
  */
+import { isBlankText, trimWhitespace } from '../core/lines';
+import { matchTableDelimiterRow, splitRowCells } from '../core/parsers/table';
+import { unescapeCellPipes } from '../schema/table-cell-raw';
+import { rectangleCellRaws } from './sub-table-copy';
 /** Rows of cell texts, rectangular: every row padded to the widest. Null for a non-grid payload. */
 export function parseClipboardGrid(text) {
     const lines = text.replace(/\r\n?/g, '\n').split('\n');
-    while (lines.length && lines[lines.length - 1].trim() === '')
+    while (lines.length && isBlankText(lines[lines.length - 1]))
         lines.pop();
     if (lines.length === 0)
         return null;
@@ -21,35 +25,16 @@ export function parseClipboardGrid(text) {
         return null;
     return rows.map((row) => [...row, ...Array(width - row.length).fill('')]);
 }
-// Every line a pipe row; the delimiter line (second, all dashes and colons) is dropped.
+// Accepts only pipe rows, read by the table parser's own row and delimiter matchers; a cell's
+// pipes are unescaped, as a copied rectangle's are.
 function parseGfmRows(lines) {
-    if (!lines.every((line) => /^\s*\|.*\|\s*$/.test(line)))
+    if (!lines.every((line) => /^\|.*\|$/.test(trimWhitespace(line))))
         return null;
-    const rows = lines.map(splitPipeRow);
-    if (rows.length >= 2 && rows[1].every((cell) => /^:?-+:?$/.test(cell)))
+    const rows = lines.map((line) => splitRowCells(line).map(unescapeCellPipes));
+    if (rows.length >= 2 && matchTableDelimiterRow(lines[1]))
         rows.splice(1, 1);
     return rows;
 }
-function splitPipeRow(line) {
-    const inner = line.trim().slice(1, -1);
-    const cells = [];
-    let cell = '';
-    for (let i = 0; i < inner.length; i++) {
-        const ch = inner[i];
-        if (ch === '\\' && inner[i + 1] === '|') {
-            cell += '|';
-            i++;
-        }
-        else if (ch === '|') {
-            cells.push(cell.trim());
-            cell = '';
-        }
-        else
-            cell += ch;
-    }
-    cells.push(cell.trim());
-    return cells;
-}
 function parseTsvRows(lines) {
     if (!lines.some((line) => line.includes('\t')))
         return null;
@@ -57,17 +42,7 @@ function parseTsvRows(lines) {
 }
 /** A rectangle's cell texts, pipes unescaped, as the clipboard's grid. */
 export function rectangleGrid(table, a, b) {
-    const rows = table.children ?? [];
-    const grid = [];
-    for (let r = Math.min(a.rowIdx, b.rowIdx); r <= Math.max(a.rowIdx, b.rowIdx); r++) {
-        const cells = rows[r]?.children ?? [];
-        const line = [];
-        for (let c = Math.min(a.colIdx, b.colIdx); c <= Math.max(a.colIdx, b.colIdx); c++) {
-            line.push((cells[c]?.raw ?? '').replace(/\\\|/g, '|'));
-        }
-        grid.push(line);
-    }
-    return grid;
+    return rectangleCellRaws(table, a, b).map((row) => row.map(unescapeCellPipes));
 }
 /** The grid repeated to fill a selection whose sides are multiples of it (a spreadsheet's
  *  tiling); any other selection takes the grid once from its top-left corner. */

package/dist/tree-operations/table-mutations.d.ts

@@ -3,14 +3,18 @@ import type { StructuralChange } from './structural-change';
 export declare function insertEmptyRow(table: CstNode, rowIdx: number, side: 'above' | 'below'): void;
 export declare function insertEmptyColumn(table: CstNode, colIdx: number, side: 'left' | 'right'): StructuralChange[];
 export declare function deleteRow(table: CstNode, rowIdx: number): void;
+/**
+ * Make the table's first row its header. A header wider than the delimiter row reads as no table,
+ * so its surplus cells become new columns, each row filling them from its own surplus first.
+ */
+export declare function promoteFirstRowToHeader(table: CstNode): void;
 export declare function deleteColumn(table: CstNode, colIdx: number): StructuralChange[];
 export declare function moveColumn(table: CstNode, fromCol: number, toCol: number): StructuralChange[];
 export declare function setAlignment(table: CstNode, colIdx: number, alignment: TableAlignment): void;
 export declare function cycleAlignment(table: CstNode, colIdx: number): void;
 /**
- * Whether a row delete is allowed. `rowCount` is the FULL count including the header. A
- * header delete promotes the next row so it needs only a second row; a body delete needs
- * a second body row, else it would leave a header-only table.
+ * `rowCount` includes the header. A header delete promotes the next row, so it needs only a
+ * second row; a body delete needs a second body row, or it leaves a header-only table.
  */
 export declare function canDeleteRow(rowIdx: number, rowCount: number): boolean;
 /** Whether a column delete is allowed: a table must keep at least one column. */

package/dist/tree-operations/table-mutations.js

@@ -1,8 +1,9 @@
-// In-place table CST mutations; the caller owns the commit ceremony and the raw rebuild,
-// so these touch neither reactivity, undo, nor raw. Column mutators emit exactly one
+// In-place table CST mutations; the caller owns the commit and the raw rebuild, so these
+// touch neither reactivity, undo, nor raw. Column mutators emit exactly one
 // StructuralChange per row, in row order, for multi-scope callers to pair with row scopes.
 import { metadataOf } from '../core/nodes';
 import { reorderChildren } from './reorder';
+import { generateBlockId } from '../block-id';
 const ALIGN_CYCLE = ['left', 'center', 'right'];
 // ── Public API ─────────────────────────────────────────────────────────────
 export function insertEmptyRow(table, rowIdx, side) {
@@ -38,10 +39,46 @@ export function deleteRow(table, rowIdx) {
     const rows = table.children ?? [];
     const willRemoveHeader = rowIdx === 0;
     rows.splice(rowIdx, 1);
-    if (willRemoveHeader && rows.length > 0) {
-        metadataOf(rows[0], 'tableRow').isHeader = true;
+    if (willRemoveHeader && rows.length > 0)
+        promoteFirstRowToHeader(table);
+}
+/**
+ * Make the table's first row its header. A header wider than the delimiter row reads as no table,
+ * so its surplus cells become new columns, each row filling them from its own surplus first.
+ */
+export function promoteFirstRowToHeader(table) {
+    const rows = table.children ?? [];
+    if (rows.length === 0)
+        return;
+    const meta = metadataOf(table, 'table');
+    const extra = metadataOf(rows[0], 'tableRow').surplusCells?.length ?? 0;
+    if (extra > 0) {
+        meta.columnCount += extra;
+        meta.alignments = [...meta.alignments, ...Array(extra).fill('none')];
+    }
+    // Written as copies: only the table is this edit's own, and a row can still be in an undo entry.
+    for (let i = 0; i < rows.length; i++) {
+        if (i === 0 || extra > 0)
+            rows[i] = widenedRow(rows[i], meta.columnCount, i === 0);
     }
 }
+/** A copy of the row holding `columnCount` cells, the missing ones taken from its surplus first. */
+function widenedRow(row, columnCount, isHeader) {
+    const surplus = metadataOf(row, 'tableRow').surplusCells ?? [];
+    const missing = Math.max(0, columnCount - row.children.length);
+    const added = Array.from({ length: missing }, (_, k) => ({
+        kind: 'tableCell',
+        leadingTrivia: '',
+        raw: surplus[k] ?? ''
+    }));
+    const rest = surplus.slice(missing);
+    const metadata = rest.length > 0 ? { isHeader, surplusCells: rest } : { isHeader };
+    const copy = { ...row, metadata, children: [...row.children, ...added] };
+    if (row.childIds)
+        copy.childIds = [...row.childIds, ...added.map(() => generateBlockId())];
+    delete copy.childSpans;
+    return copy;
+}
 export function deleteColumn(table, colIdx) {
     const meta = metadataOf(table, 'table');
     const changes = [];
@@ -73,8 +110,8 @@ export function setAlignment(table, colIdx, alignment) {
 export function cycleAlignment(table, colIdx) {
     const meta = metadataOf(table, 'table');
     const current = meta.alignments[colIdx];
-    // 'none' renders identically to 'left', so stepping through it would look like a stuck
-    // press; jump to 'center' instead. Once cycling begins the column never re-enters it.
+    // 'none' renders identically to 'left', so stepping through it would look like the click
+    // did nothing; jump to 'center' instead. Once cycling begins the column never re-enters it.
     if (current === 'none') {
         meta.alignments[colIdx] = 'center';
         return;
@@ -86,9 +123,8 @@ export function cycleAlignment(table, colIdx) {
 // Single source of truth for the deletion-refusal rules, here rather than in
 // editor-actions/ so selection/ never has to reach across for them.
 /**
- * Whether a row delete is allowed. `rowCount` is the FULL count including the header. A
- * header delete promotes the next row so it needs only a second row; a body delete needs
- * a second body row, else it would leave a header-only table.
+ * `rowCount` includes the header. A header delete promotes the next row, so it needs only a
+ * second row; a body delete needs a second body row, or it leaves a header-only table.
  */
 export function canDeleteRow(rowIdx, rowCount) {
     if (rowCount <= 1)