@voithos-labs/aragonite 0.10.4 → 0.10.7

package/dist/plugins/toc/heading-outline.d.ts

@@ -1,21 +1,15 @@
 /**
- * The heading outline as a pure function over the read-only document. The walk
- * recurses through containers, so a heading nested in a blockquote or list is still
- * collected at its own path and remains navigable.
+ * The heading outline as a pure function over the read-only document. It recurses through
+ * containers, so a heading nested in a blockquote or list is still collected at its own path
+ * and stays navigable.
  */
-import { type DocumentView, type InlineNode } from '../../plugin';
+import { type DocumentView, type EditorContext, type InlineNode } from '../../plugin';
 /** Deepest heading level a document can list; `[[toc]]` has no meaning past GFM's six. */
 export declare const MAX_HEADING_DEPTH = 6;
-/**
- * The instance's `{ plugin, options }` depth, else `fallback` (the factory argument's
- * bare-install default). Options arrive as `unknown` from the platform, so anything but a
- * whole number in 1..6 is not a depth and falls back rather than listing nothing.
- */
-export declare function resolveMaxDepth(options: unknown, fallback: number): number;
 export interface TocEntry {
     /** Stable and unique per position: the keyed-loop identity. */
     id: string;
-    /** Doc-absolute block path of the heading, for `rects.scrollTo`. */
+    /** Document-absolute block path of the heading, for `rects.scrollTo`. */
     path: number[];
     level: number;
     label: string;
@@ -25,4 +19,5 @@ export interface TocEntry {
  * render to, and anything unrecognized falls back to its source bytes.
  */
 export declare function projectInlineText(nodes: readonly InlineNode[], raw: string): string;
-export declare function collectHeadings(document: DocumentView | undefined, maxDepth: number): TocEntry[];
+/** Labels read through `read`, the editor's inline parse, so syntax it left out stays text. */
+export declare function collectHeadings(document: DocumentView | undefined, maxDepth: number, read?: EditorContext['computeInlineContent']): TocEntry[];

package/dist/plugins/toc/heading-outline.js

@@ -1,22 +1,11 @@
 /**
- * The heading outline as a pure function over the read-only document. The walk
- * recurses through containers, so a heading nested in a blockquote or list is still
- * collected at its own path and remains navigable.
+ * The heading outline as a pure function over the read-only document. It recurses through
+ * containers, so a heading nested in a blockquote or list is still collected at its own path
+ * and stays navigable.
  */
-import { computeInlineContent, headingLevel } from '../../plugin';
+import { computeInlineContent, headingLevel, trimWhitespace, walkBlocks } from '../../plugin';
 /** Deepest heading level a document can list; `[[toc]]` has no meaning past GFM's six. */
 export const MAX_HEADING_DEPTH = 6;
-/**
- * The instance's `{ plugin, options }` depth, else `fallback` (the factory argument's
- * bare-install default). Options arrive as `unknown` from the platform, so anything but a
- * whole number in 1..6 is not a depth and falls back rather than listing nothing.
- */
-export function resolveMaxDepth(options, fallback) {
-    const declared = options?.maxDepth;
-    if (typeof declared !== 'number' || !Number.isInteger(declared))
-        return fallback;
-    return declared >= 1 && declared <= MAX_HEADING_DEPTH ? declared : fallback;
-}
 /**
  * Plain-text projection: markers drop with their wrapper, value nodes show what they
  * render to, and anything unrecognized falls back to its source bytes.
@@ -39,27 +28,24 @@ export function projectInlineText(nodes, raw) {
     }
     return text;
 }
-export function collectHeadings(document, maxDepth) {
+/** Labels read through `read`, the editor's inline parse, so syntax it left out stays text. */
+export function collectHeadings(document, maxDepth, read = computeInlineContent) {
     const entries = [];
-    const walk = (children, basePath) => {
-        children.forEach((node, index) => {
-            const path = [...basePath, index];
-            const level = headingLevel(node);
-            if (level !== null) {
-                if (level <= maxDepth) {
-                    entries.push({
-                        id: path.join('.'),
-                        path,
-                        level,
-                        label: projectInlineText(computeInlineContent(node), node.raw).trim()
-                    });
-                }
-            }
-            else if (node.children && node.children.length > 0) {
-                walk(node.children, path);
-            }
-        });
-    };
-    walk(document?.children ?? [], []);
+    if (!document)
+        return entries;
+    walkBlocks(document, (node, path) => {
+        const level = headingLevel(node);
+        if (level === null)
+            return;
+        if (level <= maxDepth) {
+            entries.push({
+                id: path.join('.'),
+                path,
+                level,
+                label: trimWhitespace(projectInlineText(read(node), node.raw))
+            });
+        }
+        return 'skip';
+    });
     return entries;
 }

package/dist/plugins/toc/navigation-queue.d.ts

@@ -1,8 +1,6 @@
 /**
- * Per-block serialization for `rects.navigateTo`. The reveal anchor
- * (`cursor/reveal-anchor.ts`) decides which pin survives a race but cannot un-land a
- * caret, and two overlapping navigations from one block land two. A mid-flight call
- * overwrites the pending target, so the newest wins with no extra scroll.
+ * One `rects.navigateTo` at a time per block, since two overlapping navigations would move the
+ * caret twice. A call while one is in progress replaces the pending target, so the newest wins.
  */
 export interface NavigationQueue {
     navigateTo(path: number[]): Promise<void>;

package/dist/plugins/toc/toc-plugin.d.ts

@@ -1,14 +1,14 @@
 /**
- * A `[[toc]]` leaf whose folded view lists the document's headings, read straight off
- * `BlockComponentProps.document` — the reference consumer of that prop. Recognition is
- * gated on registration, so with no plugin loaded `[[toc]]` is a plain paragraph.
+ * A `[[toc]]` block whose rendered view lists the document's headings, read straight off
+ * `BlockComponentProps.document`: the worked example of using that prop. Recognition starts
+ * only once the plugin registers, so without it `[[toc]]` is a plain paragraph.
  */
 import { type EditorPlugin } from '../../plugin';
 export declare const TOC_BLOCK = "toc";
 export declare function registerTocBlock(): void;
 export type MaxHeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
-/** The per-instance `{ plugin, options }` shape, and the factory argument's, which are one
- *  vocabulary on purpose: the instance entry overrides the factory default. */
+/** The factory argument, which sets every editor's default, and an editor's `{ plugin, options }`
+ *  entry, which overrides it. */
 export interface TocOptions {
     /** Deepest heading level listed (default 6 = every level). */
     maxDepth?: MaxHeadingLevel;

package/dist/plugins/toc/toc-plugin.js

@@ -1,7 +1,7 @@
 /**
- * A `[[toc]]` leaf whose folded view lists the document's headings, read straight off
- * `BlockComponentProps.document` — the reference consumer of that prop. Recognition is
- * gated on registration, so with no plugin loaded `[[toc]]` is a plain paragraph.
+ * A `[[toc]]` block whose rendered view lists the document's headings, read straight off
+ * `BlockComponentProps.document`: the worked example of using that prop. Recognition starts
+ * only once the plugin registers, so without it `[[toc]]` is a plain paragraph.
  */
 import { definePlugin, declarePluginKind, declaredPluginKind, registerBlockKind, registerBlockOpener, registerBlockComponent, defineBlockComponent, simpleLeafClosure, OPENER_PRIORITIES } from '../../plugin';
 import TocBlock from './TocBlock.svelte';
@@ -10,14 +10,15 @@ export const TOC_BLOCK = 'toc';
 const TOC_LINE = '[[toc]]';
 export function registerTocBlock() {
     const toc = declarePluginKind(TOC_BLOCK);
-    // A source-holding leaf like `fencedCode`: `serialize` re-emits `leadingTrivia + raw`,
-    // so a raw taken verbatim from the line round-trips.
+    // A block that holds its own source, like `fencedCode`: `serialize` re-emits
+    // `leadingTrivia + raw`, so a raw taken verbatim from the line round-trips.
     registerBlockKind(toc, {
+        label: 'Table of contents',
         mergeRole: 'not-mergeable',
         editable: true,
         supportsInline: false,
-        // Render-primary like the math forms: the folded view leaves a caret no textual landing
-        // at either edge, so both boundaries open against another trapped kind.
+        // Render-primary like the math blocks: the rendered view gives the caret nowhere to sit
+        // at either edge, so both edges take the gap caret.
         gapEdges: 'both',
         conformanceFixture: '[[toc]]\n',
         closure: simpleLeafClosure({
@@ -41,8 +42,8 @@ export function registerTocBlock() {
         })
     });
     registerBlockOpener(toc, {
-        // Gap placement below the only bracket-consuming built-in, so `[[toc]]` resolves here
-        // whatever that matcher claims.
+        // Just below the only built-in that consumes brackets, so `[[toc]]` resolves here
+        // whatever that matcher does.
         priority: OPENER_PRIORITIES.linkReferenceDefinition - 5,
         interruptsParagraph: (text) => text === TOC_LINE,
         tryOpen(ctx) {
@@ -58,14 +59,20 @@ export function registerTocBlock() {
     });
 }
 export function tocPlugin(options) {
-    // Definition-time, so it is the BARE-install default only: the block prefers this editor's
-    // `{ plugin, options }` depth, which is what lets two instances differ.
-    const maxDepth = options?.maxDepth ?? MAX_HEADING_DEPTH;
     return definePlugin({
         name: 'toc',
+        defaults: { maxDepth: options?.maxDepth ?? MAX_HEADING_DEPTH },
+        // Anything but a whole number in 1..6 keeps the default rather than listing nothing.
+        parseOptions(raw) {
+            const maxDepth = raw?.maxDepth;
+            return isMaxHeadingLevel(maxDepth) ? { maxDepth } : {};
+        },
         setup() {
             registerTocBlock();
-            registerBlockComponent(declaredPluginKind(TOC_BLOCK), defineBlockComponent(TocBlock, () => ({ maxDepth })));
+            registerBlockComponent(declaredPluginKind(TOC_BLOCK), defineBlockComponent(TocBlock));
         }
     });
 }
+function isMaxHeadingLevel(value) {
+    return (Number.isInteger(value) && value >= 1 && value <= MAX_HEADING_DEPTH);
+}

package/dist/presentation-mode.d.ts

@@ -1,32 +1,24 @@
 /**
- * The presentation-mode contract. `source` is the editing default (always-visible styled
- * source); `reading` hides markers and makes the surface inert; `preview-block` reveals the
- * caret's block and `preview-inline` narrows that reveal to the caret-touched construct
- * (`components/blocks/text/construct-reveal.ts`); `live` hides markers with no reveal at all,
- * while staying editable. Every door reports the EFFECTIVE mode.
+ * The presentation-mode contract. `source` is the editing default (styled source); `reading`
+ * hides markers and is read-only; the preview modes show markers back in the caret's block or
+ * construct (`components/blocks/text/construct-reveal.ts`); `live` hides markers and shows none
+ * back while staying editable. Every read reports the mode in effect.
  */
 export type PresentationMode = 'source' | 'reading' | 'preview-block' | 'preview-inline' | 'live';
-/**
- * A mode read off the DOM or handed in untyped, narrowed to the contract. The marker-hiding CSS
- * families match known values only, so an unrecognized one must read as the editing default here or
- * the stylesheet and the caret walk disagree about the same block.
- */
+/** Narrows a mode read off the DOM or handed in untyped: an unrecognized value reads as the
+ *  editing default, as the marker-hiding CSS does, or the two would disagree about a block. */
 export declare function asPresentationMode(value: string | null | undefined): PresentationMode;
 /** Membership for the marker-hiding CSS families and the `data-list-marker` hook that
  *  feeds them: styled source is the one mode that paints Markdown syntax. */
 export declare function hidesMarkers(mode: PresentationMode): boolean;
-/** The reveal-on-focus rungs, which alone need the `data-focused` attribute — live hides
- *  markers (see `hidesMarkers`) but never reveals them, so it is deliberately not one. */
+/** The modes that show markers back in a focused block, the only ones needing `data-focused`;
+ *  live hides markers and never shows them back. */
 export declare function isPreviewMode(mode: PresentationMode): boolean;
-/**
- * Whether the mode paints a marker in the block the caret is in: styled source always, and the
- * preview rungs by revealing that block. The question every seam writing at the caret asks, since
- * a rewrite may only drop bytes the reader never saw (live-mode.md § 2).
- */
+/** Whether the mode paints markers in the caret's block: the check everything writing at the caret
+ *  asks, since a rewrite may drop only bytes the user never saw (`docs/design/live-mode.md` § 2). */
 export declare function paintsFocusedMarkers(mode: PresentationMode): boolean;
-/**
- * The read-only gate the dispatch seams key off. Structural parameter type so the
- * schema/selection layers need no editor-keys import; an `undefined` getter (test
- * doubles, unwired surfaces) means not reading.
- */
-export declare function isReadingMode(getMode: (() => PresentationMode) | undefined): boolean;
+/** The converse, the one check a rewrite asks before dropping delimiter bytes at the caret. */
+export declare function hidesDelimitersAtCaret(mode: PresentationMode): boolean;
+/** The read-only check every dispatch path keys off. A plain getter type keeps `schema/` and
+ *  `selection/` off `editor-keys`; the getter is required, since only the editor picks the default. */
+export declare function isReadingMode(getMode: () => PresentationMode): boolean;

package/dist/presentation-mode.js

@@ -1,12 +1,11 @@
 /**
- * The presentation-mode contract. `source` is the editing default (always-visible styled
- * source); `reading` hides markers and makes the surface inert; `preview-block` reveals the
- * caret's block and `preview-inline` narrows that reveal to the caret-touched construct
- * (`components/blocks/text/construct-reveal.ts`); `live` hides markers with no reveal at all,
- * while staying editable. Every door reports the EFFECTIVE mode.
+ * The presentation-mode contract. `source` is the editing default (styled source); `reading`
+ * hides markers and is read-only; the preview modes show markers back in the caret's block or
+ * construct (`components/blocks/text/construct-reveal.ts`); `live` hides markers and shows none
+ * back while staying editable. Every read reports the mode in effect.
  */
-/** Keyed by the union, so a rung added to it fails `npm run check` here rather than falling
- *  silently through {@link asPresentationMode}'s door. */
+/** Keyed by the union, so a mode added to it fails `npm run check` here rather than falling
+ *  silently through {@link asPresentationMode}. */
 const MODES = {
     source: true,
     reading: true,
@@ -14,11 +13,8 @@ const MODES = {
     'preview-inline': true,
     live: true
 };
-/**
- * A mode read off the DOM or handed in untyped, narrowed to the contract. The marker-hiding CSS
- * families match known values only, so an unrecognized one must read as the editing default here or
- * the stylesheet and the caret walk disagree about the same block.
- */
+/** Narrows a mode read off the DOM or handed in untyped: an unrecognized value reads as the
+ *  editing default, as the marker-hiding CSS does, or the two would disagree about a block. */
 export function asPresentationMode(value) {
     return value != null && Object.hasOwn(MODES, value) ? value : 'source';
 }
@@ -27,24 +23,22 @@ export function asPresentationMode(value) {
 export function hidesMarkers(mode) {
     return mode !== 'source';
 }
-/** The reveal-on-focus rungs, which alone need the `data-focused` attribute — live hides
- *  markers (see `hidesMarkers`) but never reveals them, so it is deliberately not one. */
+/** The modes that show markers back in a focused block, the only ones needing `data-focused`;
+ *  live hides markers and never shows them back. */
 export function isPreviewMode(mode) {
     return mode === 'preview-block' || mode === 'preview-inline';
 }
-/**
- * Whether the mode paints a marker in the block the caret is in: styled source always, and the
- * preview rungs by revealing that block. The question every seam writing at the caret asks, since
- * a rewrite may only drop bytes the reader never saw (live-mode.md § 2).
- */
+/** Whether the mode paints markers in the caret's block: the check everything writing at the caret
+ *  asks, since a rewrite may drop only bytes the user never saw (`docs/design/live-mode.md` § 2). */
 export function paintsFocusedMarkers(mode) {
     return !hidesMarkers(mode) || isPreviewMode(mode);
 }
-/**
- * The read-only gate the dispatch seams key off. Structural parameter type so the
- * schema/selection layers need no editor-keys import; an `undefined` getter (test
- * doubles, unwired surfaces) means not reading.
- */
+/** The converse, the one check a rewrite asks before dropping delimiter bytes at the caret. */
+export function hidesDelimitersAtCaret(mode) {
+    return !paintsFocusedMarkers(mode);
+}
+/** The read-only check every dispatch path keys off. A plain getter type keeps `schema/` and
+ *  `selection/` off `editor-keys`; the getter is required, since only the editor picks the default. */
 export function isReadingMode(getMode) {
-    return getMode?.() === 'reading';
+    return getMode() === 'reading';
 }

package/dist/reactivity/block-list-state.svelte.d.ts

@@ -1,22 +1,20 @@
 /**
- * A container's inner BlockList scope: the keyed-each id source and the component-ref slot
- * array. Structural mutations route through the commit primitives on UndoController, which
- * apply `StructuralChange` descriptors to keep ids/refs aligned with children.
+ * A container's inner block list: where its keyed-each ids come from and where its child
+ * component refs are stored. Structural changes go through the commit calls on
+ * `UndoController`, which apply a `StructuralChange` to keep ids and refs lined up with the
+ * children.
  */
 import type { BlockComponent } from '../block-component';
 import type { NodeView } from '../core/node-views';
 import { type RefSlots } from './publish-ref.svelte';
 export interface BlockListState {
-    /** Settable because ids live on the node, where the write reaches the `$state` proxy.
-     *  Refs do not: the array identity IS the scope, so `replaceRefs` publishes contents
-     *  and the property itself never moves. */
+    /** Settable because the ids live on the node, where the write reaches the `$state` proxy.
+     *  The refs array keeps its identity for life; `replaceRefs` rewrites its contents. */
     innerBlockIds: string[];
     readonly innerBlockRefs: (BlockComponent | undefined)[];
-    /** This scope's slot accessors, minted once here so every consumer — the child list,
-     *  the container surface, the mount registry — addresses the scope by one identity. */
+    /** The accessors over `innerBlockRefs` that a child's mount writes through. */
     readonly refSlots: RefSlots<BlockComponent>;
 }
-/** `getNode` must be a live getter — by-value freezes on the initial node and misses
- *  undo's deep-clone reassignment. A view suffices: the only writes target `childIds`,
- *  the bytes-view carve-out. */
+/** `getNode` must be a live getter: a node passed by value goes stale when undo swaps in a deep
+ *  clone. A view is enough, since `childIds` is the only field written. */
 export declare function createBlockListState(getNode: () => NodeView): BlockListState;

package/dist/reactivity/block-list-state.svelte.js

@@ -1,14 +1,14 @@
 /**
- * A container's inner BlockList scope: the keyed-each id source and the component-ref slot
- * array. Structural mutations route through the commit primitives on UndoController, which
- * apply `StructuralChange` descriptors to keep ids/refs aligned with children.
+ * A container's inner block list: where its keyed-each ids come from and where its child
+ * component refs are stored. Structural changes go through the commit calls on
+ * `UndoController`, which apply a `StructuralChange` to keep ids and refs lined up with the
+ * children.
  */
 import { assignIds } from '../block-id';
 import { registerBlockListState } from './state-registry';
 import { refSlotsOver } from './publish-ref.svelte';
-/** `getNode` must be a live getter — by-value freezes on the initial node and misses
- *  undo's deep-clone reassignment. A view suffices: the only writes target `childIds`,
- *  the bytes-view carve-out. */
+/** `getNode` must be a live getter: a node passed by value goes stale when undo swaps in a deep
+ *  clone. A view is enough, since `childIds` is the only field written. */
 export function createBlockListState(getNode) {
     const initialNode = getNode();
     if (!initialNode.childIds) {
@@ -34,9 +34,8 @@ export function createBlockListState(getNode) {
             node.childIds = assignIds(node.children ?? []);
         }
         registerBlockListState(node, state);
-        // A parent-scope replace can reuse this instance with a node prop that has fewer
-        // children than before. Publish cleanup empties departing slots but never shrinks
-        // the array, and refs length must track children exactly, so reconcile it here.
+        // A replacement in the parent list can reuse this instance with fewer children, and ref
+        // cleanup empties entries without shrinking the array; the refs must match the children.
         const childCount = node.children?.length ?? 0;
         if (innerBlockRefs.length > childCount) {
             innerBlockRefs.length = childCount;

package/dist/reactivity/block-window.svelte.d.ts

@@ -1,5 +1,5 @@
 import type { HeightModel } from '../cursor/height-model';
-import type { Scrollport } from '../cursor/scrollport';
+import type { ScrollportReader } from '../cursor/scrollport';
 export interface WindowInputs {
     scrollTop: number;
     viewportHeight: number;
@@ -16,15 +16,22 @@ export interface WindowResult {
     end: number;
     topSpacerPx: number;
     bottomSpacerPx: number;
+    /** The table's height for the whole list, which `useWindowFloor` holds the list's box at while
+     *  the window changes; 0 when not windowing. */
+    floorPx: number;
 }
 export declare function computeWindow(model: HeightModel, input: WindowInputs): WindowResult;
 export interface BlockWindowDeps {
     getModel: () => HeightModel;
-    getPort: () => Scrollport | null;
-    /** Map the port's scrollTop into this list's own coordinate range. Identity for the top level. */
+    getPort: () => ScrollportReader | null;
+    /** Convert the scroll container's `scrollTop` into this list's own range. Unchanged at the
+     *  top level. */
     getLocalScrollTop: () => number;
     getViewportHeight: () => number;
     getPinnedIndex: () => number | null;
+    /** True while a height change's scroll correction is still to come: the range then keeps the
+     *  blocks it has as well, since the scroll doesn't match the table yet. */
+    holdsRange: () => boolean;
     overscan: number;
     pinExtensionCap: number;
     activateAbovePx: number;
@@ -32,9 +39,8 @@ export interface BlockWindowDeps {
 }
 export interface BlockWindow {
     readonly result: WindowResult;
-    /** Push the scroll element's current scrollTop into the window state now. A
-     *  programmatic scrollTop write doesn't fire a `scroll` event, so the passive
-     *  listener wouldn't update the derived in time for a deterministic reveal. */
+    /** A scripted `scrollTop` write fires no `scroll` event, so a scroll into view calls this to
+     *  update the window before reading it. */
     syncScrollTop(): void;
     dispose(): void;
 }

package/dist/reactivity/block-window.svelte.js

@@ -1,28 +1,26 @@
 /**
- * Window math for virtual rendering. `computeWindow` is pure: from a height model and the
- * scroll viewport it returns the slice to mount (extended to keep a pinned caret block
- * contiguous), the spacer heights preserving native scroll geometry, and the next
- * activation state. `createBlockWindow` wires live getters and a scroll listener to it.
+ * Window math for virtual rendering: which blocks to mount, and the spacer heights that keep the
+ * browser's scroll geometry. `computeWindow` is pure; `createBlockWindow` wires live getters and
+ * a scroll listener to it.
  */
 import { untrack } from 'svelte';
 export function computeWindow(model, input) {
     const n = model.size;
     const total = model.total();
-    // The one activation decision in the feature: a scope windows purely on its own modeled
-    // height, so who owns the scroll changes which port is read and nothing else.
+    // The one place windowing turns on or off: a list decides purely on its own estimated
+    // height, so who owns the scroll changes which container is read and nothing else.
     const active = input.active ? total >= input.deactivateBelowPx : total >= input.activateAbovePx;
     if (!active || n === 0) {
-        return { active: false, start: 0, end: n, topSpacerPx: 0, bottomSpacerPx: 0 };
+        return { active: false, start: 0, end: n, topSpacerPx: 0, bottomSpacerPx: 0, floorPx: 0 };
     }
     const firstVisible = model.indexAtOffset(input.scrollTop);
-    // Probe the last on-screen pixel: the viewport is half-open, so a block whose top sits
-    // exactly on the bottom edge isn't visible.
+    // Check the last on-screen pixel: the viewport range is half-open, so a block whose top
+    // sits exactly on the bottom edge isn't visible.
     const lastVisible = model.indexAtOffset(input.scrollTop + input.viewportHeight - 1);
     let start = Math.max(0, firstVisible - input.overscan);
     let end = Math.min(n, lastVisible + 1 + input.overscan);
-    // Extend the CONTIGUOUS range so Svelte preserves the caret block's DOM node and native
-    // focus/IME survive a scroll — bounded, so a caret parked far away before a large scroll
-    // doesn't mount thousands. Beyond the cap it blurs.
+    // Growing the range to the caret block keeps its DOM node, so focus and IME survive a scroll;
+    // capped so a caret left far away doesn't mount thousands of blocks (it loses focus instead).
     const pin = input.pinnedIndex;
     if (pin !== null && pin >= 0 && pin < n) {
         if (pin < start && start - pin <= input.pinExtensionCap)
@@ -35,7 +33,21 @@ export function computeWindow(model, input) {
         start,
         end,
         topSpacerPx: model.offsetOf(start),
-        bottomSpacerPx: total - model.offsetOf(end)
+        bottomSpacerPx: total - model.offsetOf(end),
+        floorPx: total
+    };
+}
+/** `next` widened to keep `shown`'s blocks too, with the spacers the table now gives them. */
+function widened(model, next, shown) {
+    const end = Math.min(Math.max(next.end, shown.end), model.size);
+    const start = Math.min(next.start, shown.start, end);
+    return {
+        active: true,
+        start,
+        end,
+        topSpacerPx: model.offsetOf(start),
+        bottomSpacerPx: model.total() - model.offsetOf(end),
+        floorPx: model.total()
     };
 }
 export function createBlockWindow(deps) {
@@ -56,8 +68,11 @@ export function createBlockWindow(deps) {
             unsubscribe = null;
         };
     });
+    // Plain, not state: the range last shown, and the scroll it was worked out at.
+    let last = null;
     const result = $derived.by(() => {
-        return computeWindow(deps.getModel(), {
+        const model = deps.getModel();
+        const next = computeWindow(model, {
             scrollTop,
             viewportHeight: deps.getViewportHeight(),
             overscan: deps.overscan,
@@ -67,10 +82,22 @@ export function createBlockWindow(deps) {
             activateAbovePx: deps.activateAbovePx,
             deactivateBelowPx: deps.deactivateBelowPx
         });
+        // Unmounting the blocks at the top before the correction lands would remount them fresh; a
+        // range the new one doesn't touch is a jump elsewhere, and goes.
+        const shown = last?.scrollTop === scrollTop ? last.result : null;
+        const kept = shown &&
+            shown.active &&
+            next.active &&
+            next.start <= shown.end &&
+            shown.start <= next.end &&
+            deps.holdsRange()
+            ? widened(model, next, shown)
+            : next;
+        last = { result: kept, scrollTop };
+        return kept;
     });
-    // Hysteresis state. `result` reads `active` and this effect writes it, so the write is
-    // untracked and change-guarded — otherwise the effect depends on its own write. It
-    // converges: once `active` equals `result.active` the guard writes nothing.
+    // Hysteresis: `result` reads `active` and this effect writes it, so the write is untracked
+    // and skipped when unchanged, or the effect would depend on its own write.
     $effect(() => {
         const next = result.active;
         untrack(() => {

package/dist/reactivity/child-list.d.ts

@@ -0,0 +1,34 @@
+/**
+ * One block list's children as a walk down the tree reads them, and the two walks: `descendTo`
+ * scrolls each level's child into the mounted range, `componentAt` reads only what is mounted.
+ * The editor root, every container, the table and each table row publish one.
+ */
+import type { BlockComponent } from '../block-component';
+import { type RefSlots } from './publish-ref.svelte';
+/** One mounted child list, as the descent reads it. Every field is read live. */
+export interface ChildList {
+    count(): number;
+    readonly refs: RefSlots<BlockComponent>;
+    /** Required, so a list that cannot say whether a child is in range cannot exist. */
+    readonly windowing: {
+        /** Scrolls this list so child `index` is inside the mounted range; resolves after a tick. */
+        revealChild(index: number): Promise<void>;
+        /** Whether `index` is inside the mounted range. */
+        isInWindow(index: number): boolean;
+    };
+    /** Scrolls child `index` into this list's own scroller on another axis (a table's columns). */
+    bringChildIntoView?(index: number): void;
+    /** True while only the title row (child 0) is mounted. */
+    isCollapsed?(): boolean;
+    /** Opens a collapsed body as an undoable commit, for a descent asked to open one. */
+    openCollapsed?(): Promise<boolean>;
+}
+/**
+ * Mounts each level of `path` below `root` and returns the component at its end, or null when
+ * a level can't mount. A path into a collapsed body stops there unless `openCollapsed` is set.
+ */
+export declare function descendTo(root: ChildList, path: readonly number[], opts?: {
+    openCollapsed?: boolean;
+}): Promise<BlockComponent | null>;
+/** The mounted component at `path`, or null; never mounts anything. */
+export declare function componentAt(root: ChildList, path: readonly number[]): BlockComponent | null;

package/dist/reactivity/child-list.js

@@ -0,0 +1,48 @@
+import { revealChildOrWait } from './publish-ref.svelte';
+/**
+ * Mounts each level of `path` below `root` and returns the component at its end, or null when
+ * a level can't mount. A path into a collapsed body stops there unless `openCollapsed` is set.
+ */
+export async function descendTo(root, path, opts = {}) {
+    let list = root;
+    for (let depth = 0; depth < path.length; depth++) {
+        const index = path[depth];
+        // Only a body child is hidden; the title row stays mounted while collapsed.
+        if (index >= 1 && list.isCollapsed?.()) {
+            if (!opts.openCollapsed || !list.openCollapsed)
+                return null;
+            await list.openCollapsed();
+        }
+        const { windowing } = list;
+        await revealChildOrWait(index, {
+            slots: list.refs,
+            childCount: list.count(),
+            revealChild: (i) => windowing.revealChild(i),
+            isInWindow: (i) => windowing.isInWindow(i)
+        });
+        const ref = list.refs.get(index);
+        if (!ref)
+            return null;
+        list.bringChildIntoView?.(index);
+        if (depth === path.length - 1)
+            return ref;
+        const next = ref.childList?.();
+        if (!next)
+            return null;
+        list = next;
+    }
+    return null;
+}
+/** The mounted component at `path`, or null; never mounts anything. */
+export function componentAt(root, path) {
+    let list = root;
+    for (let depth = 0; depth < path.length && list; depth++) {
+        const ref = list.refs.get(path[depth]);
+        if (!ref)
+            return null;
+        if (depth === path.length - 1)
+            return ref;
+        list = ref.childList?.();
+    }
+    return null;
+}