@voithos-labs/aragonite 0.10.3 → 0.10.7

package/dist/components/blocks/table/cell-render.d.ts

@@ -1,51 +1,46 @@
 /**
- * DOM-build for TableCellBlock's render $effect. Mirrors text-render.ts without the
- * ambient prefix or block marker — a cell's entire raw is content, so every island
- * offset is a raw offset. The component owns the effect and the pending-cursor
- * restore; this factory owns the imperative build.
+ * DOM-building for TableCellBlock's render effect. The same as text-render.ts without a
+ * marker prefix or block marker, since a cell's whole raw is content, so every decoration
+ * offset is a raw offset. The component owns the effect and the pending-cursor restore;
+ * this factory builds the DOM.
  */
 import type { DocumentView, NodeView } from '../../../core/node-views';
-import type { LinkReferenceResolverRef, ResolveLinkUrl } from '../../../editor-keys';
-import type { PresentationMode } from '../../../presentation-mode';
+import type { ResolveLinkUrl } from '../../../editor-keys';
 import type { IndexedDecoration } from '../../../decorations/buckets';
 import type { ReplaceDecoration, WidgetDecoration } from '../../../decorations/types';
+import type { Reading } from '../../../schema/reading';
 export interface CellRenderDeps {
     get el(): HTMLElement | null;
     get node(): NodeView;
-    get linkRef(): LinkReferenceResolverRef | undefined;
+    /** How the editor reads its bytes. Its mode is read inside the render pass on purpose: that read
+     *  is the reactive dependency that re-renders every mounted cell when the mode changes. */
+    get reading(): Reading;
     resolveLinkUrl: ResolveLinkUrl;
-    /** Effective mode. Read inside the render pass on purpose: the read is the
-     *  reactive dependency that re-renders every mounted cell on a mode flip. */
-    get presentationMode(): PresentationMode;
-    /** The editor's theme name, forwarded to widgets. NOT a render-key term: this DOM is
-     *  themed by CSS, so only a widget whose engine paints its own colors reads it. */
-    getTheme?: () => string;
+    /** The editor's theme name, passed on to widgets. Not part of the render key: this DOM
+     *  is themed by CSS, so only a widget that draws its own colors reads it. */
+    getTheme: () => string;
     /** Live root document for widgets that derive from it. A getter, so a pooled widget
      *  re-reads the current document across edits rather than a mount-time snapshot. */
     getDocument: () => DocumentView | undefined;
-    /** The editor's content version, so a widget can memoize a document-wide derivation
-     *  on it. Absent in a bare harness. */
-    getContentVersion?: () => number;
-    /** The editor's navigation door, forwarded to widgets whose gesture jumps elsewhere. */
-    navigateTo?: (path: number[]) => Promise<boolean>;
-    /** Position-sorted islands. A getter read inside the render pass on purpose: that
-     *  read is the reactive dependency that re-renders the cell on an island change. */
+    /** The editor's content version, so a widget can memoize a document-wide derivation on it. */
+    getContentVersion: () => number;
+    /** The editor's navigation call, passed on to widgets whose gesture jumps elsewhere. */
+    navigateTo: (path: number[]) => Promise<boolean>;
+    /** Decoration widgets, sorted by position. A getter read inside the render pass on
+     *  purpose: that read is the dependency that re-renders the cell when one changes. */
     get islands(): IndexedDecoration<WidgetDecoration | ReplaceDecoration>[];
-    /** A widget's synchronous mount throw goes to the editor's `error` channel. Absent →
-     *  unsurfaced; the widget still falls back to its raw source. */
-    reportRenderError?: (error: unknown) => void;
+    /** A widget that throws while mounting reports to the editor's `error` event, and still falls
+     *  back to its raw source. */
+    reportRenderError: (error: unknown) => void;
 }
 export interface CellRender {
-    /**
-     * Rebuild the cell's children from current node state. Skips work on an unchanged
-     * memo key unless `forceRebuild` — pass it when a pending cursor restore needs the
-     * DOM re-anchored even though the key held.
-     */
+    /** Rebuilds the cell's children, skipping an unchanged key unless `forceRebuild`, which a
+     *  pending cursor restore passes. */
     render(opts?: {
         forceRebuild?: boolean;
         carryCaret?: boolean;
     }): void;
-    /** Destroy every pooled widget instance and mounted island — called on unmount. */
+    /** Destroy every pooled widget and mounted decoration, called when the cell unmounts. */
     dispose(): void;
 }
 export declare function createCellRender(deps: CellRenderDeps): CellRender;

package/dist/components/blocks/table/cell-render.js

@@ -1,14 +1,14 @@
 /**
- * DOM-build for TableCellBlock's render $effect. Mirrors text-render.ts without the
- * ambient prefix or block marker — a cell's entire raw is content, so every island
- * offset is a raw offset. The component owns the effect and the pending-cursor
- * restore; this factory owns the imperative build.
+ * DOM-building for TableCellBlock's render effect. The same as text-render.ts without a
+ * marker prefix or block marker, since a cell's whole raw is content, so every decoration
+ * offset is a raw offset. The component owns the effect and the pending-cursor restore;
+ * this factory builds the DOM.
  */
 import { computeInlineContent, contentLengthOf } from '../../../core/inline';
 import { renderInlineNodes } from '../../../core/inline-render';
 import { trimTrailingLineEnding } from '../../../core/lines';
-import { captureFocusedCaretWalkOffset, restoreCaretAtWalkOffset } from '../../../cursor/focused-caret';
-import { CONTENT_EMPTY_ATTR, holdsOnlyMarkerChrome } from '../../../cursor/widget-offset';
+import { captureFocusedCaret } from '../../../cursor/focused-caret';
+import { CONTENT_EMPTY_ATTR, holdsOnlyMarkerChrome, placeCaretAtRaw } from '../../../cursor/widget-offset';
 import { applyIslandDecorations, islandRenderKeyPart } from '../../../decorations/island-dom';
 import { mountDecorationWidget } from '../../../decorations/widget-dom';
 import { devWarn } from '../../../dev-warn';
@@ -18,11 +18,11 @@ export function createCellRender(deps) {
     let lastRenderedKey = '';
     const widgetPool = createSvelteWidgetPool({
         reportError: deps.reportRenderError,
-        getPresentationMode: () => deps.presentationMode,
         getTheme: deps.getTheme,
         getDocument: deps.getDocument,
         getContentVersion: deps.getContentVersion,
-        navigateTo: deps.navigateTo
+        navigateTo: deps.navigateTo,
+        reading: deps.reading
     });
     let islandDestroys = [];
     function destroyIslands() {
@@ -38,55 +38,53 @@ export function createCellRender(deps) {
         if (!el)
             return;
         const node = deps.node;
-        // Gating both the signature dependency and the resolver read on the bracket keeps
-        // an LRD change from re-rendering every cell. A false positive re-parses identically.
+        // Checking for a bracket before reading the signature or the resolver keeps one edit to
+        // a link-reference definition from re-rendering every cell. A false hit reparses the same.
         const hasRef = node.raw.includes('[');
-        // Key on the compact signature epoch, never the ~MB-scale string (text-render's twin).
-        const sig = hasRef ? String(deps.linkRef?.epoch ?? deps.linkRef?.signature ?? '') : '';
-        // Unconditional, unlike the ref gating: a mode flip re-renders every mounted cell.
-        // '' in source keeps the default key byte-identical but for one NUL (text-render's twin).
-        const mode = deps.presentationMode;
+        // Key on the short signature token, never the string, which can reach megabytes.
+        const sig = hasRef ? String(deps.reading.resolverEpoch) : '';
+        // Always included, unlike the reference part: a mode change re-renders every mounted
+        // cell. '' in source mode keeps the default key byte-identical, as text-render does.
+        const mode = deps.reading.mode();
         const modeKeyPart = mode === 'source' ? '' : mode;
         const islands = deps.islands;
         const renderKey = `${node.raw}\0${sig}\0${modeKeyPart}${islandRenderKeyPart(islands)}`;
         const forceRebuild = opts?.forceRebuild ?? false;
         if (renderKey === lastRenderedKey && !forceRebuild)
             return;
-        const content = computeInlineContent(node, hasRef ? deps.linkRef?.current : undefined);
-        // An island-signature change rebuilds a focused cell with no edit-path pending
-        // offset, so carry the caret in walk space; the edit path opts out because its
-        // own restore runs after and wins (text-render's twin).
-        const caretWalkOffset = (opts?.carryCaret ?? true) ? captureFocusedCaretWalkOffset(el) : null;
+        const content = computeInlineContent(node, hasRef ? deps.reading.resolver : undefined, deps.reading.grammar);
+        // A decoration change rebuilds a focused cell with no restore pending, so the caret is
+        // carried across; an edit opts out because its own restore runs after.
+        const caret = (opts?.carryCaret ?? true) ? captureFocusedCaret(el) : null;
         // Bracketing the rebuild pools portal widgets, so an unchanged `$…$` keeps its
-        // instance across per-keystroke rebuilds. Island widgets are unpooled.
+        // instance across per-keystroke rebuilds. Decoration widgets are not pooled.
         widgetPool.beginPass();
         destroyIslands();
         el.replaceChildren(renderInlineNodes(content, node.raw, {
             renderImagesAsWidgets: getBlockKindDescriptor(node.kind).renderImagesAsWidgets ?? true,
             resolveLinkUrl: deps.resolveLinkUrl,
-            buildPortalWidget
+            buildPortalWidget,
+            grammar: deps.reading.grammar
         }));
-        // Ambient length 0: a cell carries no marker, so island offsets are raw offsets.
         islandDestroys = applyIslandDecorations(el, node.raw, islands, {
             contentLength: contentLengthOf(node),
-            ambientLength: 0,
             mountWidget: (spec, dec) => mountDecorationWidget(spec, dec, deps.reportRenderError),
-            onSkipped: (dec, reason) => devWarn('decorations', `island skipped: ${reason}`, dec)
+            onSkipped: (dec, reason) => devWarn('decorations', `decoration skipped: ${reason}`, dec)
         });
         widgetPool.sweep();
         lastRenderedKey = renderKey;
-        // An empty cell needs a `<br>` caret anchor, but a `<br>` inside an island
-        // belongs to the widget, not the cell — it must not satisfy the anchor.
+        // An empty cell needs a `<br>` for the caret to anchor in, but a `<br>` inside a
+        // decoration widget belongs to that widget, not the cell, so it cannot serve.
         if (trimTrailingLineEnding(node.raw) === '') {
             const hasAnchorBr = [...el.querySelectorAll('br')].some((br) => !br.closest('[data-decoration-island]'));
             if (!hasAnchorBr)
                 el.appendChild(document.createElement('br'));
         }
-        // A cell whose whole content is an empty construct (`[](u)`) would otherwise paint
-        // nothing; the stamp precedes the restore, which lands through the same walk.
+        // A cell whose whole content is an empty construct (`[](u)`) would otherwise draw
+        // nothing; the attribute is set before the restore, which uses the same traversal.
         el.toggleAttribute(CONTENT_EMPTY_ATTR, holdsOnlyMarkerChrome(el));
-        if (caretWalkOffset !== null)
-            restoreCaretAtWalkOffset(el, caretWalkOffset);
+        if (caret !== null)
+            placeCaretAtRaw(el, caret, { clamp: 'exact' });
     }
     return {
         render,

package/dist/components/blocks/table/selected-cells.d.ts

@@ -1,14 +1,14 @@
 /**
- * Which cells of one table a measurement request covers: a live intra-table
- * rectangle, or a plain `[start, end)` run of row-major cell indices. The rectangle
- * wins only when it belongs to THIS table.
+ * Which cells of one table a measurement request covers: a live rectangle of cells, or a plain
+ * `[start, end)` run of row-major cell indices. The rectangle wins only when it belongs to this
+ * table.
  */
-import type { IntraTableRect } from './cell-clipboard';
+import type { GridCoverage } from '../../../selection/range-coverage';
 import type { CellCoord } from './table-navigation';
 export interface SelectedCellsInput {
-    /** The live rectangle from anywhere in the document, or null. */
-    rect: IntraTableRect | null;
-    /** This table's doc path — the owner check against `rect.tablePath`. */
+    /** The live rectangle's coverage from anywhere in the document, or null. */
+    grid: GridCoverage | null;
+    /** This table's document path, checked against `grid.path`. */
     myPath: readonly number[];
     start: number;
     /** `SELECTION_END` means "through the last cell". */

package/dist/components/blocks/table/selected-cells.js

@@ -1,16 +1,15 @@
 /**
- * Which cells of one table a measurement request covers: a live intra-table
- * rectangle, or a plain `[start, end)` run of row-major cell indices. The rectangle
- * wins only when it belongs to THIS table.
+ * Which cells of one table a measurement request covers: a live rectangle of cells, or a plain
+ * `[start, end)` run of row-major cell indices. The rectangle wins only when it belongs to this
+ * table.
  */
 import { SELECTION_END } from '../../../block-component';
 import { cellRowCol } from '../../../cursor/coordinate-spaces';
 import { pathsEqual } from '../../../selection/path-math';
 export function selectedCells(input) {
-    const { rect, myPath, columnCount, rowCount } = input;
-    if (rect && pathsEqual(rect.tablePath, myPath)) {
-        return rectangleCells(rect, columnCount);
-    }
+    const { grid, myPath, columnCount, rowCount } = input;
+    if (grid && pathsEqual(grid.path, myPath))
+        return rectangleCells(grid.rect);
     const cellCount = rowCount * columnCount;
     const end = input.end === SELECTION_END ? cellCount : Math.min(input.end, cellCount);
     const cells = [];
@@ -18,14 +17,11 @@ export function selectedCells(input) {
         cells.push(coordOf(i, columnCount));
     return cells;
 }
-function rectangleCells(rect, columnCount) {
-    const a = coordOf(rect.anchorCellIdx, columnCount);
-    const b = coordOf(rect.focusCellIdx, columnCount);
+function rectangleCells({ top, left, rows, cols }) {
     const cells = [];
-    for (let r = Math.min(a.rowIdx, b.rowIdx); r <= Math.max(a.rowIdx, b.rowIdx); r++) {
-        for (let c = Math.min(a.colIdx, b.colIdx); c <= Math.max(a.colIdx, b.colIdx); c++) {
+    for (let r = top; r < top + rows; r++) {
+        for (let c = left; c < left + cols; c++)
             cells.push({ rowIdx: r, colIdx: c });
-        }
     }
     return cells;
 }

package/dist/components/blocks/table/table-caret-at-point.d.ts

@@ -1,8 +1,8 @@
 /**
- * Table's `caretTargetAtPoint`: the cell a point lands a caret in, as a `[rowIdx, colIdx]` path
- * plus a within-cell offset. NEAREST, not exact — the difference from `tableDragHitTest` beside
- * it. A point clamped into the table's box can sit in a gutter, a padding gap or a windowing
- * spacer and must still land a caret, where an exact `elementFromPoint` hit declines.
+ * Table's `caretTargetAtPoint`: the cell a point puts a caret in, as a `[rowIdx, colIdx]` path
+ * plus an offset inside the cell. Nearest, not exact, which is the difference from
+ * `tableDragHitTest` beside it. A point clamped into the table's box can sit in a gutter, a
+ * padding gap or a windowing spacer and must still land a caret, where an exact hit refuses.
  */
 import type { CaretTarget } from '../../../schema/block-kind-descriptor';
 export declare function tableCaretAtPoint(blockEl: HTMLElement, clientX: number, clientY: number): CaretTarget | null;

package/dist/components/blocks/table/table-caret-at-point.js

@@ -1,8 +1,8 @@
 /**
- * Table's `caretTargetAtPoint`: the cell a point lands a caret in, as a `[rowIdx, colIdx]` path
- * plus a within-cell offset. NEAREST, not exact — the difference from `tableDragHitTest` beside
- * it. A point clamped into the table's box can sit in a gutter, a padding gap or a windowing
- * spacer and must still land a caret, where an exact `elementFromPoint` hit declines.
+ * Table's `caretTargetAtPoint`: the cell a point puts a caret in, as a `[rowIdx, colIdx]` path
+ * plus an offset inside the cell. Nearest, not exact, which is the difference from
+ * `tableDragHitTest` beside it. A point clamped into the table's box can sit in a gutter, a
+ * padding gap or a windowing spacer and must still land a caret, where an exact hit refuses.
  */
 import { CURSOR_END } from '../../../block-component';
 import { mountedRowEls, rowCellEls } from './cell-pointer';
@@ -13,7 +13,7 @@ export function tableCaretAtPoint(blockEl, clientX, clientY) {
     let nearest = null;
     let smallestDistance = Infinity;
     for (const rowEl of mountedRowEls(tableEl)) {
-        // The ABSOLUTE row index: under row windowing the first mounted row is not row 0.
+        // The absolute row index: under row windowing the first mounted row is not row 0.
         const rowIdx = Number(rowEl.getAttribute('data-table-row-idx'));
         if (Number.isNaN(rowIdx))
             continue;

package/dist/components/blocks/table/table-cell-paste.d.ts

@@ -1,16 +1,10 @@
 /**
- * Cell text ingestion for tableCell: the caret mapping that follows the sink's
- * inserted backslashes, plus the paste hooks exposed as a PasteSurface. The bytes
- * are the kind's business — every hook hands back plain spliced text and
- * `normalizeCellRaw` runs at the write sink.
+ * How a table cell takes in pasted text. The bytes are the kind's business: every hook hands back
+ * unescaped text, and the cell's write rule (`schema/table-cell-raw.ts`) runs when it is written.
  */
 import type { CstNode } from '../../../core/nodes';
-import type { InlinePasteResult, PasteRange, PasteSeam, PasteSurface } from '../../../tree-operations/paste-surfaces';
+import type { InlinePasteResult, PasteRange, PasteSurface } from '../../../tree-operations/paste-surfaces';
+import type { StoredAs } from '../../../schema/stored-as';
 export declare function normalizeWhitespace(s: string): string;
-/**
- * Where `offset` lands once the sink's `normalizeCellRaw` has run — defined as 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;
-export declare function tableCellInlinePaste(node: CstNode, offset: number, text: string, preDelete?: PasteRange, seam?: PasteSeam): InlinePasteResult;
+export declare function tableCellInlinePaste(node: CstNode, offset: number, text: string, preDelete: PasteRange | undefined, store: StoredAs): InlinePasteResult;
 export declare const tableCellPasteSurface: PasteSurface;

package/dist/components/blocks/table/table-cell-paste.js

@@ -1,40 +1,23 @@
 /**
- * Cell text ingestion for tableCell: the caret mapping that follows the sink's
- * inserted backslashes, plus the paste hooks exposed as a PasteSurface. The bytes
- * are the kind's business — every hook hands back plain spliced text and
- * `normalizeCellRaw` runs at the write sink.
+ * How a table cell takes in pasted text. The bytes are the kind's business: every hook hands back
+ * unescaped text, and the cell's write rule (`schema/table-cell-raw.ts`) runs when it is written.
  */
 import { CURSOR_END } from '../../../block-component';
-import { normalizeCellRaw } from '../../../schema/table-cell-raw';
 import { blockNodeAt } from '../../../tree-operations/node-primitives';
-import { cutRangeFromDisplay } from '../../../tree-operations/node-ops';
+import { replaceRangeInLeaf } from '../../../tree-operations/leaf-range';
 import { sliceTableAtRow } from '../../../tree-operations/paste/table-slice';
 import { focusIndexBeforeResidue } from '../../../tree-operations/paste/focus-target';
-import { replaceBlockAtParent } from '../../../tree-operations/paste/replace-block-at-parent';
+import { landClipboardBlocks, landedAfter } from '../../../tree-operations/paste/paste-replacement';
+import { documentLineEnding, trimTrailingLineEnding, trimWhitespace } from '../../../core/lines';
 // ── Public API ─────────────────────────────────────────────────────────────
 export function normalizeWhitespace(s) {
-    return s.replace(/\n+/g, ' ').trim();
+    return trimWhitespace(s.replace(/\n+/g, ' '));
 }
-/**
- * Where `offset` lands once the sink's `normalizeCellRaw` has run — defined as 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;
-}
-export function tableCellInlinePaste(node, offset, text, preDelete, seam) {
+export function tableCellInlinePaste(node, offset, text, preDelete, store) {
+    // The kind's pipe escaping runs over whatever the join writes, when the cell is written.
     const cleaned = normalizeWhitespace(text);
-    // The delete half crosses the join seam BEFORE the escaping stage (live-mode.md § 4.5): the
-    // seam reads and writes the cell's own display bytes, and `normalizeCellRaw` still runs at the
-    // sink over whatever they end up being.
-    const { display: raw, offset: effectiveOffset } = cutRangeFromDisplay(node, node.raw, preDelete ?? { start: offset, end: offset }, seam?.presentationMode, seam?.linkRef);
-    const spliced = raw.slice(0, effectiveOffset) + cleaned + raw.slice(effectiveOffset);
-    // Escaped space, because the sink escapes the whole spliced raw and not just the
-    // pasted text: the insertion point can sit between a `\` and the `|` it frees.
-    return {
-        newRaw: spliced,
-        caretOffset: escapedCellOffset(spliced, effectiveOffset + cleaned.length)
-    };
+    const edit = replaceRangeInLeaf(node, preDelete ?? { start: offset, end: offset }, cleaned, store);
+    return { newRaw: trimTrailingLineEnding(edit.raw), caretOffset: edit.caret };
 }
 export const tableCellPasteSurface = {
     kind: 'tableCell',
@@ -44,33 +27,34 @@ export const tableCellPasteSurface = {
 };
 // ── Internal ───────────────────────────────────────────────────────────────
 // The cell's blockEdit is the row-level nested bundle (its `replaceBlock` targets the
-// row's cells), so the splice routes through `replaceBlockAtParent` at the table's parent.
+// row's cells), so the splice goes through the paste coordinator at the table's parent.
 async function tableCellScopedStructuralPaste(input) {
     const tablePath = input.targetPath.slice(0, -2);
     const rowIdx = input.targetPath[input.targetPath.length - 2];
     const table = blockNodeAt(input.doc, tablePath);
-    // Malformed path: swallow the paste.
+    // Malformed path: drop the paste.
     if (!table || table.kind !== 'table')
         return;
     const { firstHalf, secondHalf } = sliceTableAtRow(table, rowIdx, 'first');
+    const lineEnding = documentLineEnding(input.doc);
     const replacement = [];
     if (firstHalf)
         replacement.push(firstHalf);
+    const landed = landClipboardBlocks(firstHalf ?? undefined, input.blocks, lineEnding);
     // Appended, never spread: a paste can outnumber an argument list (G4.60).
-    for (const block of input.blocks)
+    for (const block of landed)
         replacement.push(block);
+    const last = replacement[replacement.length - 1];
+    // The rows below the cell stay a table: with no blank line, the last block would read them.
     if (secondHalf)
-        replacement.push(secondHalf);
-    await replaceBlockAtParent({
-        doc: input.doc,
-        blockPath: tablePath,
-        replacement,
-        controller: input.controller,
-        undoEntry: input.undoEntry,
-        // The last pasted block, before the second table half (the residue).
-        focusReplacementIndex: focusIndexBeforeResidue(replacement.length, secondHalf !== null),
-        focusOffset: CURSOR_END,
-        source: 'paste-dispatch-table-cell',
-        ...(input.grammar ? { grammar: input.grammar } : {})
-    });
+        replacement.push(last ? landedAfter(last, secondHalf, lineEnding) : secondHalf);
+    await input.controller.replaceBlock(tablePath, replacement, 
+    // The last pasted block, before the second half of the table.
+    {
+        replacementIndex: focusIndexBeforeResidue(replacement.length, secondHalf !== null),
+        offset: CURSOR_END
+    }, 
+    // The commit targets the whole table, where no in-cell offset applies; the live read
+    // records the cell's caret.
+    { source: 'paste-dispatch-table-cell', snapshotOffset: 0 });
 }

package/dist/components/blocks/table/table-drag-hit-test.js

@@ -3,6 +3,7 @@
  * Owns the encoding so the selection layer stays free of table-DOM knowledge.
  */
 import { cellAtPoint, mountedRowEls, rowCellEls } from './cell-pointer';
+import { rowMajorCellIndex } from '../../../cursor/coordinate-spaces';
 export function tableDragHitTest(blockEl, clientX, clientY) {
     const tableEl = blockEl.querySelector(':scope > [role="table"]');
     if (!tableEl)
@@ -16,5 +17,5 @@ export function tableDragHitTest(blockEl, clientX, clientY) {
     const columnCount = rowCellEls(firstRow).length;
     if (columnCount === 0)
         return null;
-    return cell.rowIdx * columnCount + cell.colIdx;
+    return rowMajorCellIndex(cell.rowIdx, cell.colIdx, columnCount);
 }

package/dist/components/blocks/table/table-menu-model.d.ts

@@ -7,8 +7,8 @@ import type { TableAxisAction } from '../../../action-contracts';
 import type { TableAlignment } from '../../../core/nodes';
 export type ClipboardAction = 'cut' | 'copy' | 'paste';
 /**
- * Clamp a fixed-position menu's top-left into the viewport (minus `margin`) — menus
- * open at a raw pointer coordinate. Larger than the viewport pins to top/left.
+ * Clamp a fixed-position menu's top-left into the viewport, less `margin`, since menus open
+ * at a raw pointer coordinate. One larger than the viewport is pinned to the top left.
  */
 export declare function clampMenuToViewport(desired: {
     x: number;
@@ -23,12 +23,8 @@ export declare function clampMenuToViewport(desired: {
     x: number;
     y: number;
 };
-/**
- * Where a flyout hung off its parent row ends up on screen: shifted UP just enough to clear the
- * viewport bottom (never above the top margin) and, when its right edge would overflow, flipped
- * to the parent menu's left side. Shifting vertically keeps the hovered row pointing into it;
- * flipping horizontally keeps it off its own parent. Pure, so the two flyouts share one rule.
- */
+/** A flyout rises just enough to clear the viewport bottom, and moves to the parent menu's
+ *  left when its right edge would overflow and the left has room. */
 export declare function flyoutPlacement(flyout: {
     top: number;
     bottom: number;

package/dist/components/blocks/table/table-menu-model.js

@@ -1,8 +1,8 @@
 import { tableRowReorderTarget, tableColumnReorderTarget } from '../../../editor-actions/table-context';
 import { canDeleteRow, canDeleteColumn } from '../../../tree-operations/table-mutations';
 /**
- * Clamp a fixed-position menu's top-left into the viewport (minus `margin`) — menus
- * open at a raw pointer coordinate. Larger than the viewport pins to top/left.
+ * Clamp a fixed-position menu's top-left into the viewport, less `margin`, since menus open
+ * at a raw pointer coordinate. One larger than the viewport is pinned to the top left.
  */
 export function clampMenuToViewport(desired, menu, viewport, margin = 8) {
     const maxX = Math.max(margin, viewport.width - menu.width - margin);
@@ -12,12 +12,8 @@ export function clampMenuToViewport(desired, menu, viewport, margin = 8) {
         y: Math.min(Math.max(margin, desired.y), maxY)
     };
 }
-/**
- * Where a flyout hung off its parent row ends up on screen: shifted UP just enough to clear the
- * viewport bottom (never above the top margin) and, when its right edge would overflow, flipped
- * to the parent menu's left side. Shifting vertically keeps the hovered row pointing into it;
- * flipping horizontally keeps it off its own parent. Pure, so the two flyouts share one rule.
- */
+/** A flyout rises just enough to clear the viewport bottom, and moves to the parent menu's
+ *  left when its right edge would overflow and the left has room. */
 export function flyoutPlacement(flyout, parentMenu, viewport, margin = 8) {
     const overflow = flyout.bottom + margin - viewport.height;
     const dy = overflow > 0 ? -Math.min(overflow, Math.max(0, flyout.top - margin)) : 0;
@@ -31,7 +27,7 @@ clipboard) {
     const rows = rowGroup(cell.rowIdx, dims.rowCount);
     const cols = columnGroup(cell.colIdx, dims.colCount, alignments);
     const isDelete = (i) => i.kind === 'action' && (i.action === 'deleteRow' || i.action === 'deleteColumn');
-    // A cell knows both axes, so each axis's inserts and moves fold behind one flyout and only
+    // A cell knows both axes, so each axis's inserts and moves go behind one flyout and only
     // the two deletes and the alignment stay in the list.
     return [
         ...clipboardGroup(clipboard.hasSelection || clipboard.hasRect === true),
@@ -49,7 +45,7 @@ clipboard) {
         ...cols.filter((i) => i.kind === 'alignment')
     ];
 }
-// Paste always applies: clipboard contents aren't readable synchronously to gate it.
+// Paste always applies: the clipboard cannot be read synchronously to decide otherwise.
 function clipboardGroup(hasContent) {
     return [
         { kind: 'clipboard', action: 'cut', label: 'Cut', enabled: hasContent },

package/dist/components/blocks/table/table-navigation.js

@@ -1,5 +1,5 @@
-// Pure: no DOM, no Svelte. Null means "no cell that way" — what the caller does with
-// the edge (exit, append a row) is the plan's decision, not this module's.
+// Pure: no DOM, no Svelte. Null means there is no cell that way; what the caller does at the
+// edge, leaving the table or appending a row, is its own decision.
 export function nextCell(pos, columnCount, rowCount) {
     if (pos.colIdx < columnCount - 1)
         return { rowIdx: pos.rowIdx, colIdx: pos.colIdx + 1 };