@voithos-labs/aragonite 0.10.4 → 0.10.7

package/dist/ambient/ambient-dom.js

@@ -1,10 +1,8 @@
 /**
- * DOM construction and lookup for the ambient marker span — the read-only
- * prefix container blocks contribute to their first prose child's textContent.
+ * Builds the marker prefix span (the "ambient" prefix): the read-only prefix a container block
+ * draws in front of its first prose child's text. Reading it back is `cursor/widget-offset.ts`.
  */
 import { DRAG_ANCHOR_ATTR } from '../components/block-content-selector';
-import { domDescendants } from '../cursor/dom-walk';
-import { isAtomicInlineWidget, isHiddenMarkerText } from '../cursor/widget-offset';
 import { devWarn } from '../dev-warn';
 export function buildAmbientSpan(prefix) {
     const normalized = typeof prefix === 'string' ? { text: prefix } : prefix;
@@ -32,10 +30,17 @@ export function buildAmbientSpan(prefix) {
         if (range.ariaChecked !== undefined) {
             inner.setAttribute('aria-checked', String(range.ariaChecked));
         }
+        if (range.label !== undefined)
+            inner.setAttribute('aria-label', range.label);
+        if (range.focusable)
+            inner.tabIndex = 0;
         if (range.dragAnchor)
             inner.setAttribute(DRAG_ANCHOR_ATTR, '');
         inner.textContent = normalized.text.slice(range.start, range.end);
         inner.addEventListener('click', range.onClick);
+        const onActivate = range.onActivate;
+        if (onActivate)
+            inner.addEventListener('keydown', (e) => activateOnKey(e, onActivate));
         outer.appendChild(inner);
         cursor = range.end;
     }
@@ -44,63 +49,12 @@ export function buildAmbientSpan(prefix) {
     }
     return outer;
 }
-export function ambientSpanOf(blockEl) {
-    const first = blockEl.firstChild;
-    if (!first || first.nodeType !== Node.ELEMENT_NODE)
-        return null;
-    const span = first;
-    if (!span.classList.contains('md-marker'))
-        return null;
-    if (span.getAttribute('contenteditable') !== 'false')
-        return null;
-    return span;
-}
-export function ambientLengthOf(blockEl) {
-    return ambientSpanOf(blockEl)?.textContent?.length ?? 0;
-}
-export function placeCaretAfterAmbientSpan(blockEl) {
-    const span = ambientSpanOf(blockEl);
-    if (!span)
-        return false;
-    const range = document.createRange();
-    // Prefer the first text node after the span so visual-line geometry returns real rects;
-    // setStartAfter yields a collapsed range with no textbox in empty-item state. A hidden
-    // marker run next to the span is not that text node — it paints nothing, and descending
-    // into it would seat raw 0 inside unpainted bytes.
-    const textAfter = firstTextNodeAfter(span);
-    if (textAfter && !isHiddenMarkerText(textAfter, blockEl)) {
-        range.setStart(textAfter, 0);
-    }
-    else {
-        range.setStartAfter(span);
-    }
-    range.collapse(true);
-    const sel = window.getSelection();
-    sel?.removeAllRanges();
-    sel?.addRange(range);
-    return true;
-}
 // ── Internal ────────────────────────────────────────────────────────────────
-function firstTextNodeAfter(node) {
-    let sibling = node.nextSibling;
-    while (sibling) {
-        // An atomic widget stands for raw bytes, so text past it is not raw 0.
-        if (isAtomicInlineWidget(sibling))
-            return null;
-        const text = firstTextDescendant(sibling);
-        if (text)
-            return text;
-        sibling = sibling.nextSibling;
-    }
-    return null;
-}
-// Unfiltered on the way down, unlike the measurable-text search it resembles
-// (`cursor/visual-lines.ts`): the caller judges hidden marker text once, at the top.
-function firstTextDescendant(node) {
-    for (const current of domDescendants(node)) {
-        if (current.nodeType === Node.TEXT_NODE && (current.textContent?.length ?? 0) > 0) {
-            return current;
-        }
-    }
-    return null;
+// Enter and Space, the keys a link or button answers; the block below must not see them too.
+function activateOnKey(e, onActivate) {
+    if (e.key !== 'Enter' && e.key !== ' ')
+        return;
+    e.preventDefault();
+    e.stopPropagation();
+    onActivate();
 }

package/dist/assert.js

@@ -1,12 +1,13 @@
 /**
- * Dev-runtime invariant channel: routes a violation to devWarn and never throws, since a
- * false positive must not crash a real editor. In production the predicate is not even
- * invoked. Tests call predicates directly rather than going through here.
+ * Where a dev-mode invariant check reports: it sends a violation to `devWarn` and never
+ * throws, since a false positive must not crash a real editor. Outside a dev build, unless
+ * `configureEditorEnv` turned dev on, the check is not even run. Tests call the predicates
+ * directly rather than going through here.
  */
-import { DEV } from 'esm-env';
+import { isDevChecks } from './env';
 import { devWarn } from './dev-warn';
 export function assertInvariant(tag, check) {
-    if (!DEV)
+    if (!isDevChecks())
         return;
     const violation = check();
     if (violation) {

package/dist/block-component.d.ts

@@ -1,12 +1,12 @@
 /**
- * The view-layer contract every rendered block satisfies, plus the cursor sentinels and
- * ambient-prefix shape blocks produce. Orchestration reaches a block only through this flat
- * interface, so a capability a block lacks is an omitted optional member rather than a kind
- * check upstream; `ContainerBlockComponent` is the one promoted tier. Authoritative for
- * external authors: each member's docstring states its own contract.
+ * The contract every rendered block satisfies, plus the special caret values and the marker-prefix
+ * shape blocks produce. The editor reaches a block only through this flat interface, so something
+ * a block cannot do is a missing optional member, not a kind check upstream;
+ * `ContainerBlockComponent` is the stricter version. Each member's docstring states its contract.
  */
 import type { DocumentView, NodeView } from './core/node-views';
 import type { EditorRects } from './editor-rects';
+import type { ChildList } from './reactivity/child-list';
 declare const cursorEndBrand: unique symbol;
 /** Branded `number`: a focus offset meaning "end of content", not a position. */
 export type CursorEnd = number & {
@@ -28,29 +28,41 @@ export type SelectionEnd = number & {
     readonly [selectionEndBrand]: true;
 };
 /**
- * "Place cursor at end of content." Focus walkers fall through to their end-of-content
- * fallback when the offset exceeds the block's length, so MAX_SAFE_INTEGER always lands
- * there — a finite sentinel lands mid-block once content outgrows it.
+ * "Place cursor at end of content." Focus handlers fall back to the end of the content when
+ * the offset exceeds the block's length, so `MAX_SAFE_INTEGER` always lands there; a smaller
+ * fixed number would land mid-block once the content outgrew it.
  */
 export declare const CURSOR_END: CursorEnd;
 /**
- * "Place cursor at start of content" — {@link CURSOR_END}'s twin, and NOT a synonym for 0. A
- * mode that paints no marker puts raw 0 out of the caret's reach behind a leading construct, so
- * an ARRIVAL says this and the door seats it on the first landable offset.
+ * "Place cursor at start of content": the counterpart of {@link CURSOR_END}, and not a synonym
+ * for 0. A mode that paints no marker puts raw byte 0 out of the caret's reach behind a leading
+ * construct, so a caret arriving here says this and lands on the first offset it can sit at.
  */
 export declare const CURSOR_START: CursorStart;
 /**
- * "Raw byte 0 exactly" — the ONE seat the park door does not clamp. A live split's continuation
- * reopens a construct at byte 0 and typing must continue inside it (live-mode.md § 4.4), which
- * the landable clamp would move outside; every other caller wants the clamp (G2.12).
+ * "Raw byte 0 exactly": the one position `parkCaret` does not clamp. A live split's continuation
+ * reopens a construct at byte 0 and typing has to continue inside it (live-mode.md § 4.4), which
+ * the clamp would move outside; every other caller wants the clamp (G2.12).
  */
 export declare const CURSOR_EXACT_START: CursorExactStart;
-/** Cascade focus to the last descendant and place the cursor at its start. */
-export declare const FOCUS_LAST_START = -1;
+/** Which child a caret entering a container takes, and the offset handed on to it. */
+export interface EntryEdge {
+    readonly child: 'first' | 'last';
+    readonly offset: number;
+    /** The offset was a byte inside the container, not an edge: a container that can map its
+     *  bytes to a child places it there, and any other takes the last child's end. */
+    readonly inside: boolean;
+}
+/**
+ * How every container reads a caret offset it is entered with, so a list, a table and a table
+ * row agree: 0 and the two start values enter the first child unchanged, and `CURSOR_END` or a
+ * byte offset the last child at its end.
+ */
+export declare function entryEdge(offset: number): EntryEdge;
 /**
- * "End of this block's measurable range" for measurePartialRects' endOffset. Each
- * surface interprets it in its own coordinate system: text falls through to native
- * range clamping, TableBlock matches it explicitly to reach the last cell.
+ * "End of this block's measurable range" for `measurePartialRects`' `endOffset`. Each
+ * block reads it in its own coordinate system: text falls through to the browser's range
+ * clamping, `TableBlock` matches it explicitly to reach the last cell.
  */
 export declare const SELECTION_END: SelectionEnd;
 /**
@@ -65,13 +77,26 @@ export type StickyColumnDirection = 'above' | 'below';
 export type FocusPosition = 'start' | 'end' | number | {
     stickyColumnFrom: StickyColumnDirection;
 };
-export interface AmbientInteractiveRange {
+/** A focusable range must say what Enter and Space do, so a tab stop is never a dead key. */
+export type AmbientInteractiveRange = AmbientRangeBase & ({
+    /** Gives the span a tab stop. Decide by mode: a stop inside an editable block
+     *  interrupts the caret's Tab, so the footnote marker takes one in reading mode only. */
+    focusable: true;
+    /** Enter or Space on the focused span. */
+    onActivate: () => void;
+} | {
+    focusable?: false;
+    onActivate?: () => void;
+});
+interface AmbientRangeBase {
     start: number;
     end: number;
     className: string;
-    role?: 'checkbox';
+    role?: 'checkbox' | 'link' | 'button';
     ariaChecked?: boolean;
-    /** The block's drag grip centres on this span's box rather than on its text line. */
+    /** The span's accessible name, rendered as `aria-label`. */
+    label?: string;
+    /** The block's drag handle centres on this span's box rather than on its text line. */
     dragAnchor?: boolean;
     /** The click lands on the range's own span, before the leaf's caret handling; a handler
      *  reading the chord (`isWidgetActivationClick`) stops propagation to keep the gesture. */
@@ -88,91 +113,85 @@ export type AmbientPrefix = string | {
 };
 /**
  * The props BlockHost passes every block component; a registry `extraProps` may add
- * kind-specific ones. A component may declare a subset — Svelte ignores props it omits,
- * but a leaf that drops `ambientPrefix` visually deletes its markers.
+ * kind-specific ones. A component may declare a subset, since Svelte ignores props it
+ * omits, but a leaf that drops `ambientPrefix` visually deletes its markers.
  */
 export interface BlockComponentProps {
-    /** Bytes-readonly view (G1.9): components render the CST; mutation routes through actions. */
+    /** Bytes-readonly view: components render the CST, and mutation goes through actions (G1.9). */
     node: NodeView;
     index: number;
     myPath: number[];
     /** Container-contributed read-only prefix rendered before the block's own raw (a list item's `- `). */
     ambientPrefix: AmbientPrefix;
-    /** The root document, readonly by type — mutation stays a commit-ceremony concern. */
+    /** The root document, readonly by type; changing it is the commit path's business. */
     document?: DocumentView;
-    /** The owning instance's rect surface: measure/reveal/scroll by path. The live
-     *  instance object, so a block navigating to another shares the editor's one seam. */
+    /** The owning instance's `EditorRects`: measure, scroll into view, or scroll to a path.
+     *  The live object, so a block navigating to another shares the editor's one copy. */
     rects?: EditorRects;
 }
 export interface BlockComponent {
     /**
-     * Place the caret at `offset`, focusing the surface, and end any live cross-block range — the
-     * safe default door over {@link parkCaret}, since the range-ending batches with the landing.
-     * Also takes the four caret sentinels above, which stay internal (none is on
+     * Place the caret at `offset`, focus the element, and end whatever the editor had selected (a
+     * cross-block range, a gap caret, an image selected whole): the safe default over
+     * {@link parkCaret}, since ending it batches with placing the caret. Also
+     * takes the four special caret values above, which stay internal (none is on
      * `@voithos-labs/aragonite/plugin`). Clamping is required; never throw.
      */
     focus(offset: number): void;
     /**
-     * `focus` WITHOUT the range-ending: seat the caret and touch nothing else. For
-     * selection-extend paths only (G2.12 guards the callers), where a `focus` would
-     * cancel the range still being grown; any other caller wants `focus`.
+     * `focus` without the range-ending: place the caret and touch nothing else. For paths that only
+     * extend a selection, where a `focus` would cancel the range still being grown (G2.12).
      */
     parkCaret?(offset: number): void;
     /**
-     * Caret position as a raw offset into this block's own bytes: ambient markers
-     * excluded, a widget counted as the source bytes it stands for. `null` (never 0)
-     * means not in this block — dispatch walks refs to find the focused one.
+     * Caret position as a raw offset into this block's own bytes: the container's marker
+     * prefix excluded, a widget counted as the source bytes it stands for. `null`, never 0,
+     * means the caret is not in this block; dispatch checks each ref to find the focused one.
      */
     getCursorOffset(): number | null;
     /**
-     * The current selection's rendered text, or `''` when unmounted or nothing is
-     * selected. NOT clipped to this block: a cross-block selection returns the whole
-     * range. Rendered, not raw — a caller needing this block's bytes slices `raw`.
+     * The current selection's rendered text, or `''` when unmounted or nothing is selected.
+     * Not clipped to this block: a cross-block selection returns the whole range. Rendered
+     * text, not raw bytes; a caller that needs this block's bytes slices `raw`.
      */
     getSelectedText?(): string;
     /**
-     * Select `[start, end)` in the same raw-offset space `getCursorOffset` returns.
-     * A no-op when the block is unmounted or the range doesn't resolve.
+     * Select `[start, end)` in the same raw-offset space `getCursorOffset` returns, ending whatever
+     * the editor had selected first, as `focus` does. A no-op when the block is unmounted or the
+     * range doesn't resolve.
      */
     setSelection?(start: number, end: number): void;
     /**
      * Position the cursor at the offset nearest editor-relative pixel X on the first
-     * (`'above'`) or last (`'below'`) visual line; callers fall back to focus(0) /
-     * CURSOR_END when a block omits it. Inherits {@link parkCaret}'s semantics — it does
-     * NOT end a live cross-block range, which vertical traversal can never reach.
+     * (`'above'`) or last (`'below'`) visual line that can show a caret; callers fall back to `focus(0)` or
+     * `CURSOR_END` when a block omits it. Behaves like {@link parkCaret}: it does not end a
+     * live cross-block range, which vertical movement can never reach.
      */
     focusAtColumn?(x: number, from: StickyColumnDirection): void;
     /** Cascade focus down a path of child indices to reach a leaf at the given offset. */
     focusByPath?(path: number[], offset: number): void;
     /**
-     * Apply this surface's own click-intent caret snap for a viewport point inside its box,
-     * after a landing has been placed. A caret that fell at an atomic widget's edge has no
-     * visual representation there, so the prose surface moves it onto the edge and paints the
-     * indicator Chromium omits; one that landed in real text is left alone. Omitted by
-     * surfaces with no such snap.
+     * Apply this block's own snap for a viewport point inside its box, once the caret has been
+     * placed. A caret that fell at the edge of an inline widget has nothing to draw there, so
+     * the prose block moves it onto the edge and paints the indicator Chromium leaves out; one
+     * that landed in real text is left alone. Omitted by blocks with no such snap.
      */
     snapCaretToPoint?(clientX: number, clientY: number): void;
     /**
-     * A press beside the block (the editor's margin, the host's own padding) that may become a
-     * drag: start the block's OWN drag anchored at the leaf nearest the point — a table's cell
-     * rectangle — exactly as a press on that leaf would. True when it did; false leaves the press
-     * to the editor's generic drag.
+     * A click beside the block (the editor's margin, the host's own padding) that may become a
+     * drag: start the block's own drag from the leaf nearest the point, a table's cell rectangle
+     * for instance, exactly as a click on that leaf would. True when it did; false leaves the
+     * click to the editor's generic drag.
      */
     startDragAtPoint?(clientX: number, clientY: number, event: PointerEvent): boolean;
     /**
-     * Descend child indices to the BlockComponent at the leaf, or null if the path
-     * doesn't resolve. Empty `path` returns this component. Containers implement it.
+     * This block's children as the editor walks down to one: their refs, the render window that
+     * mounts them, and the collapse a navigation may open. Containers, tables and rows have one.
      */
-    getBlockComponentByPath?(path: number[]): BlockComponent | null;
+    childList?(): ChildList;
     /**
-     * Async sibling of getBlockComponentByPath: at each nested level, scroll the child
-     * into its window and await its mount before recursing, so an off-window target
-     * resolves instead of returning null.
-     */
-    revealByPath?(path: number[]): Promise<BlockComponent | null>;
-    /**
-     * Deep cursor position for nested-block surfaces (table cells): the path from this
-     * block to the leaf holding the cursor, plus the within-leaf offset. Preferred over
+     * Deep cursor position for blocks with nested blocks inside (table cells): the path from
+     * this block to the leaf holding the cursor, plus the offset in it. Preferred over
      * getCursorOffset by getSelection() when implemented.
      */
     getCursorPosition?(): {
@@ -181,49 +200,54 @@ export interface BlockComponent {
     } | null;
     /**
      * Viewport-space rects covering [startOffset, endOffset) in this block's visible
-     * text, for cross-block selection painting. Accepts SELECTION_END as endOffset,
-     * which surfaces interpret per their own coordinate system.
+     * text, for cross-block selection painting. Accepts `SELECTION_END` as `endOffset`,
+     * which each block reads in its own coordinate system.
      */
     measurePartialRects?(startOffset: number, endOffset: number): DOMRect[];
     /**
-     * Viewport-space rect of a single cell by 2D coordinate — whole-cell highlighting on
-     * grid surfaces, bypassing measurePartialRects' selection-aware range logic. Null
-     * when the cell isn't mounted or the coordinate is out of range.
+     * Viewport-space rect of a single cell by row and column: whole-cell highlighting in a
+     * grid, skipping `measurePartialRects`' selection-aware range logic. Null when the cell
+     * isn't mounted or the coordinate is out of range.
      */
     cellRect?(rowIdx: number, colIdx: number): DOMRect | null;
     /**
-     * Current mounted row-window `[start, end)` of a row-windowed grid surface. Overlays
-     * read it reactively so a repaint fires once the re-sliced rows are committed —
-     * off-window rows can't paint until mounted.
+     * The mounted row range `[start, end)` of a grid that windows its rows. Overlays read it
+     * reactively so a repaint fires once the new rows are committed; rows outside the range
+     * cannot paint until they mount.
      */
     mountedRowWindow?(): {
         start: number;
         end: number;
     };
     /**
-     * True when vertical traversal should pass straight through: no caret-able text
-     * positions of its own, only widgets carrying no column meaning. Decided from the
-     * CST, not mounted refs, so a container answers the same for an off-window child.
+     * True when vertical movement should pass straight through: no text positions the caret
+     * can sit at, only widgets with no column meaning. Decided from the CST, not from mounted
+     * refs, so a container answers the same for a child that is not mounted.
      */
     isVerticallyTransparent?(): boolean;
     /**
-     * Enter an edge widget instead of placing a caret at its boundary. What "enter" means
-     * belongs to the kind's registered `InlineWidgetEditingPolicy` — an open vocabulary,
-     * not a two-way choice. False lets the caller fall through to focus(0) / CURSOR_END.
+     * Enter a widget at the block's edge instead of placing a caret beside it. What "enter"
+     * means belongs to the kind's registered `InlineWidgetEditingPolicy`, an open set of
+     * behaviours rather than a yes-or-no choice. False falls through to `focus(0)`/`CURSOR_END`.
      */
     enterEdgeWidget?(side: 'start' | 'end'): boolean;
     /**
-     * Run a named block-local command resolved from a keybinding. `arg` carries the
-     * binding's static argument as `unknown` — the handler must type-guard it and ignore
-     * an out-of-shape value. False lets the caller fall through to later keydown branches.
+     * Run a named block-local command resolved from a keybinding. `arg` passes the binding's
+     * fixed argument as `unknown`, so the handler must check its shape and ignore anything
+     * unexpected. False lets the caller fall through to later keydown branches.
      */
     runCommand?(id: import('./schema/command-id').AnyCommandId, arg?: unknown): boolean;
     /**
-     * Whether the command's toggle-state reads ON at the surface's own caret or selection —
-     * the read a toolbar paints a pressed state from. Absent, or an id with no toggle-state,
-     * reads inactive.
+     * Whether the command's toggle reads on at this block's own caret or selection: the read
+     * a toolbar paints a pressed state from. Absent, or an id with no toggle state, reads
+     * inactive.
      */
     isCommandActive?(id: import('./schema/command-id').AnyCommandId): boolean;
+    /**
+     * Run `run` once this block's shown widget source, which lives in the DOM only, is written
+     * back. A block that never shows one omits it; a command from outside the block waits on it.
+     */
+    afterSourceCommit?(run: () => void): void;
     /**
      * Current raw-offset selection in an editable leaf, a collapsed caret as
      * `{start: n, end: n}`. Captured before a right-click menu steals focus.
@@ -233,19 +257,21 @@ export interface BlockComponent {
         end: number;
     } | null;
     /**
-     * Claim a copy/cut/paste the editor root received because a selection state this block
-     * owns seats no native caret: a selected inline widget in a block with no text position
-     * leaves the native selection empty, so the browser dispatches at `<body>`. The claim is
-     * unconditional once the root has targeted this block, so there is nothing to report back:
-     * the seam offers the event to one arm only, and never re-offers it elsewhere.
+     * Take a copy, cut or paste the editor root received because a selection this block owns
+     * puts no caret in the DOM: a selected inline widget in a block with no text position
+     * leaves the browser's selection empty, so the event fires at `<body>`. Taking it always
+     * succeeds once the root has picked this block, so there is nothing to report back: the
+     * root offers the event to one block only, and never offers it elsewhere.
      */
     claimRootClipboard?(event: ClipboardEvent): void;
     /**
-     * Insert markdown at this surface's caret exactly as pasting it would, minus the
-     * clipboard — the block half of `EditorInstance.insertMarkdown`. True means the paste
-     * pipeline took the text, not that its commit has flushed. Omitted by non-editable blocks.
+     * Insert markdown at this block's caret exactly as pasting it would, minus the clipboard:
+     * the block half of `EditorInstance.insertMarkdown`. Return a promise that resolves once
+     * the insert has landed, so the editor can keep it in the undo entry of the gesture that
+     * asked for it; a plain true means only that the text was taken.
+     * Omitted by non-editable blocks.
      */
-    insertMarkdown?(md: string): boolean;
+    insertMarkdown?(md: string): boolean | Promise<boolean>;
     /**
      * Run a clipboard action from the table cell's right-click menu against the offsets
      * captured at menu-open (focus/selection may have moved since).
@@ -255,34 +281,34 @@ export interface BlockComponent {
         end: number;
     }): Promise<void>;
     /**
-     * Whether this component's own surface takes text input — a REPORT, never a gate. The
-     * kind's descriptor `editable` is the declaration and the only flag the editor gates on
-     * (merge eligibility, search scanning); this mirrors it for the mounted surface.
+     * Whether this component's own element takes text input: a report, never something the
+     * editor acts on. The kind descriptor's `editable` is the declaration and the only flag
+     * the editor tests (merge eligibility, search scanning); this mirrors it once mounted.
      */
     readonly editable: boolean;
     /** Whether focus may land on this block at all. This is the flag focus dispatch reads. */
     readonly focusable: boolean;
 }
 /**
- * Every member a container owes, promoted to required: a caret entering a container has
- * to descend, so the descent verbs are not "implement if you can" the way a leaf's
- * optionals are. `createContainerBlockComponent` returns this.
+ * Every member a container must provide, promoted to required: a caret entering a container
+ * has to descend into it, so the descent methods are not "implement if you can" the way a
+ * leaf's optional ones are. `createContainerBlockComponent` returns this.
  */
-export type ContainerBlockComponent = BlockComponent & Required<Pick<BlockComponent, 'getCursorPosition' | 'focusByPath' | 'getBlockComponentByPath' | 'revealByPath' | 'focusAtColumn' | 'isVerticallyTransparent' | 'enterEdgeWidget' | 'parkCaret'>>;
+export type ContainerBlockComponent = BlockComponent & Required<Pick<BlockComponent, 'getCursorPosition' | 'focusByPath' | 'childList' | 'focusAtColumn' | 'isVerticallyTransparent' | 'enterEdgeWidget' | 'parkCaret'>>;
 /**
- * What a mounted block component publishes through `bind:this`: a leaf publishes the
- * surface itself, a container publishes it under the one `containerApi` export (Svelte 5
- * instance exports are individual declarations with no spread, so re-exporting a dozen
- * members by hand drops one). The union is the enforcement — a container publishing a
- * leaf-grade surface is a type error at its `defineBlockComponent` registration site.
+ * What a mounted block component publishes through `bind:this`: a leaf publishes the object
+ * itself, a container publishes it under the one `containerApi` export (Svelte 5 instance
+ * exports are separate declarations with no spread, so re-exporting a dozen members by hand
+ * drops one). The union is what enforces it: a container publishing only a leaf's members is
+ * a type error where `defineBlockComponent` registers it.
  */
 export type BlockComponentExports = BlockComponent | {
     readonly containerApi: ContainerBlockComponent;
 };
 /**
- * The `BlockComponent` behind a published instance — the one point that knows a
- * container's surface hides under `containerApi`. Returns the object it was handed,
- * never a wrapper: `publishRefSlot` compares identity, so a fresh one stomps a slot.
+ * The `BlockComponent` behind a published instance: the one place that knows a container's
+ * object hides under `containerApi`. Returns the object it was handed, never a wrapper,
+ * because `publishRefSlot` compares identity and a new object would overwrite the stored one.
  */
 export declare function resolveBlockSurface(exports: BlockComponentExports | undefined): BlockComponent | undefined;
 export {};

package/dist/block-component.js

@@ -1,40 +1,48 @@
 /**
- * The view-layer contract every rendered block satisfies, plus the cursor sentinels and
- * ambient-prefix shape blocks produce. Orchestration reaches a block only through this flat
- * interface, so a capability a block lacks is an omitted optional member rather than a kind
- * check upstream; `ContainerBlockComponent` is the one promoted tier. Authoritative for
- * external authors: each member's docstring states its own contract.
+ * The contract every rendered block satisfies, plus the special caret values and the marker-prefix
+ * shape blocks produce. The editor reaches a block only through this flat interface, so something
+ * a block cannot do is a missing optional member, not a kind check upstream;
+ * `ContainerBlockComponent` is the stricter version. Each member's docstring states its contract.
  */
 /**
- * "Place cursor at end of content." Focus walkers fall through to their end-of-content
- * fallback when the offset exceeds the block's length, so MAX_SAFE_INTEGER always lands
- * there — a finite sentinel lands mid-block once content outgrows it.
+ * "Place cursor at end of content." Focus handlers fall back to the end of the content when
+ * the offset exceeds the block's length, so `MAX_SAFE_INTEGER` always lands there; a smaller
+ * fixed number would land mid-block once the content outgrew it.
  */
 export const CURSOR_END = Number.MAX_SAFE_INTEGER;
 /**
- * "Place cursor at start of content" — {@link CURSOR_END}'s twin, and NOT a synonym for 0. A
- * mode that paints no marker puts raw 0 out of the caret's reach behind a leading construct, so
- * an ARRIVAL says this and the door seats it on the first landable offset.
+ * "Place cursor at start of content": the counterpart of {@link CURSOR_END}, and not a synonym
+ * for 0. A mode that paints no marker puts raw byte 0 out of the caret's reach behind a leading
+ * construct, so a caret arriving here says this and lands on the first offset it can sit at.
  */
 export const CURSOR_START = -2;
 /**
- * "Raw byte 0 exactly" — the ONE seat the park door does not clamp. A live split's continuation
- * reopens a construct at byte 0 and typing must continue inside it (live-mode.md § 4.4), which
- * the landable clamp would move outside; every other caller wants the clamp (G2.12).
+ * "Raw byte 0 exactly": the one position `parkCaret` does not clamp. A live split's continuation
+ * reopens a construct at byte 0 and typing has to continue inside it (live-mode.md § 4.4), which
+ * the clamp would move outside; every other caller wants the clamp (G2.12).
  */
 export const CURSOR_EXACT_START = -3;
-/** Cascade focus to the last descendant and place the cursor at its start. */
-export const FOCUS_LAST_START = -1;
 /**
- * "End of this block's measurable range" for measurePartialRects' endOffset. Each
- * surface interprets it in its own coordinate system: text falls through to native
- * range clamping, TableBlock matches it explicitly to reach the last cell.
+ * How every container reads a caret offset it is entered with, so a list, a table and a table
+ * row agree: 0 and the two start values enter the first child unchanged, and `CURSOR_END` or a
+ * byte offset the last child at its end.
+ */
+export function entryEdge(offset) {
+    if (offset === 0 || offset === CURSOR_START || offset === CURSOR_EXACT_START) {
+        return { child: 'first', offset, inside: false };
+    }
+    return { child: 'last', offset: CURSOR_END, inside: offset !== CURSOR_END };
+}
+/**
+ * "End of this block's measurable range" for `measurePartialRects`' `endOffset`. Each
+ * block reads it in its own coordinate system: text falls through to the browser's range
+ * clamping, `TableBlock` matches it explicitly to reach the last cell.
  */
 export const SELECTION_END = Number.MAX_SAFE_INTEGER;
 /**
- * The `BlockComponent` behind a published instance — the one point that knows a
- * container's surface hides under `containerApi`. Returns the object it was handed,
- * never a wrapper: `publishRefSlot` compares identity, so a fresh one stomps a slot.
+ * The `BlockComponent` behind a published instance: the one place that knows a container's
+ * object hides under `containerApi`. Returns the object it was handed, never a wrapper,
+ * because `publishRefSlot` compares identity and a new object would overwrite the stored one.
  */
 export function resolveBlockSurface(exports) {
     if (!exports)

package/dist/block-id.d.ts

@@ -1,14 +1,10 @@
 import type { NodeView } from './core/node-views';
-/**
- * These ids key Svelte's `{#each}`: process uniqueness, not unguessability. `crypto.randomUUID`
- * answers a question nobody asked here, at a per-block cost a large load pays in full
- * (`performance.md`), and is secure-context-only besides.
- */
+/** Keys for Svelte's `{#each}`: unique within the process and cheap per block, not unguessable. */
 export declare function generateBlockId(): string;
 export declare function assignIds(children: readonly NodeView[]): string[];
-/**
- * Initialize `childIds` before a freshly-parsed subtree is spliced into the live tree: a
- * reused container reads it in its keyed-each synchronously, so a missing array surfaces
- * as `undefined` keys.
- */
+/** Ids for `next`, a re-read of `previous`: an unchanged run at either end keeps its ids, the first
+ *  changed block keeps its own (the edit was in it), and each block the re-read made is new. */
+export declare function idsAcrossReread(previous: readonly NodeView[], ids: readonly string[] | undefined, next: readonly NodeView[]): string[] | undefined;
+/** Call before a freshly parsed subtree is spliced in: a reused container reads `childIds` in its
+ *  keyed each synchronously, so a missing array shows up as `undefined` keys. */
 export declare function assignChildIdsDeep(node: NodeView): void;