@voithos-labs/aragonite 0.10.3 → 0.10.7

package/dist/schema/block-kind-descriptor.d.ts

@@ -1,49 +1,37 @@
 import { type AnyBlockKind, type CstNode } from '../core/nodes';
-import type { NodeView } from '../core/node-views';
+import type { DocumentView, NodeView } from '../core/node-views';
+import type { LineEnding } from '../core/lines';
 import type { ContainerBodyWrap } from '../core/parser';
 import type { ChildRawChange } from './child-spans';
 import type { ClosureBlock } from './closure';
-import type { KeyBinding } from './keybindings';
+import { type KeyBinding } from './keybindings';
+import type { HeightEstimateEnv } from './height-estimates';
 /**
- * Backspace-merge role. Full spec: `docs/design/editor.md` — Merge eligibility: roles, not pairs.
- * Lives here, not `merge-rules.ts`, so the descriptor registry can reference it without a cycle.
- * The tuple is the one home: G1.30's runtime vocabulary is derived from it, not re-listed.
+ * The Backspace-merge roles (`docs/design/editor.md` § Merge eligibility: roles, not pairs).
+ * The runtime role check reads its list from this tuple, so the type and the check agree (G1.30).
  */
 export declare const MERGE_ROLES: readonly ["prose", "prose-absorber", "container", "self-merge", "not-mergeable"];
 export type MergeRole = (typeof MERGE_ROLES)[number];
-/** G1.30's runtime half, for the registrations a `MergeRole` parameter cannot bind (plugin casts). */
+/** Catches a role the `MergeRole` type cannot, one that arrived through a cast (G1.30). */
 export declare const isKnownMergeRole: (role: string) => boolean;
 /**
- * The first-child Backspace strategies, each answering whether it carries child 0 out of the
- * container. G1.37's chrome arms read that answer, so a new strategy cannot arrive without one.
+ * How Backspace at the start of a container's child releases it, as a registration declares it;
+ * strategies live in `editor-actions/unwrap-strategies.ts`. Absent, on a container with no title
+ * row: child 0 hands the Backspace to the parent, and later children follow merge-rules.
  */
-declare const FIRST_CHILD_BACKSPACE_LIFTS: {
-    readonly 'lift-first-child-drop-opener': true;
-    readonly 'lift-first-child-keep-container': true;
-    readonly 'keep-reserved-chrome': false;
-    readonly 'list-item-cascade': false;
-};
-export type FirstChildBackspace = keyof typeof FIRST_CHILD_BACKSPACE_LIFTS;
-export declare const liftsFirstChild: (strategy: FirstChildBackspace) => boolean;
-/**
- * Backspace-at-start behavior for a container's children; strategies live in
- * `editor-actions/unwrap-strategies.ts`. Absent = default (first child delegates upward;
- * middle children follow merge-rules).
- */
-export interface UnwrapRole {
-    /**
-     * `'-drop-opener'` is the quote shape, whose opener line goes with the lift so the
-     * remainder reparses as a plain quote; `'-keep-container'` is the shape `rebuildRaw`
-     * re-emits, so the remainder keeps its kind; `'keep-reserved-chrome'` declines, because
-     * child 0 is the container's chrome and a lift would carry it out.
-     */
-    firstChildBackspace: FirstChildBackspace;
+export interface ContainerUnwrapRole {
+    firstChildBackspace: 'lift-first-child-drop-opener' | 'lift-first-child-keep-container' | 'list-item-cascade';
     middleChildBackspace: 'default-merge' | 'list-item-cascade';
 }
+/** The unwrap role the editor reads back: a container with a title row keeps child 0 in place. */
+export interface UnwrapRole {
+    firstChildBackspace: ContainerUnwrapRole['firstChildBackspace'] | 'keep-reserved-chrome';
+    middleChildBackspace: ContainerUnwrapRole['middleChildBackspace'];
+}
 /**
- * A container whose direct children reorder among themselves (Alt+Arrow / drag handle). The
- * reorder walk resolves the unit at the nearest ancestor declaring this; absent = children are
- * NOT independently reorderable, and the container declines the reorder at its boundary.
+ * A container whose direct children reorder among themselves (Alt+Arrow, the drag handle). The
+ * reorder resolves its unit at the nearest ancestor declaring this; absent means the children
+ * are not independently reorderable, and the container declines the reorder at its boundary.
  */
 export interface ReorderChildrenRole {
     /**
@@ -53,229 +41,307 @@ export interface ReorderChildrenRole {
     renumberMarkers?: true;
 }
 /**
- * A caret landing inside a kind's own addressing: the child path a `focusByPath` walks (empty
- * for a leaf, which is its own landing) and the offset within the leaf it names. `CURSOR_END`
- * is a legal offset here, and the one way to say "wherever that leaf ends".
+ * A caret position in a kind's own addressing: the child path `focusByPath` follows (empty for a
+ * leaf, which is its own target) and the offset within the leaf it names. `CURSOR_END` is a legal
+ * offset here, and the one way to say "wherever that leaf ends".
  */
 export interface CaretTarget {
     path: number[];
     offset: number;
 }
+/**
+ * `authored` when the user is typing in the block, so bytes may be the block's own syntax half
+ * written; `literal` for content that arrives whole (a paste, a replace, a range delete).
+ */
+export type WriteMode = 'authored' | 'literal';
+/** What a write rule reads besides the bytes. */
+export interface WriteContext {
+    /** The block whose bytes are written: the kind's own node, or for a body write its container. */
+    node: NodeView;
+    mode: WriteMode;
+    /** The document's line ending, which a line the rule writes takes when the block has none. */
+    lineEnding: LineEnding;
+}
+/**
+ * How a kind makes written bytes legal: `normalize` repairs them, and `mapOffset` says where an
+ * offset into the written bytes lands in the repaired ones. `normalize` must be idempotent.
+ */
+export interface WriteRule {
+    normalize(raw: string, ctx: WriteContext): string;
+    mapOffset(raw: string, offset: number, ctx: WriteContext): number;
+}
+/**
+ * Child 0 is a title row of this kind, its bytes in the container's raw: always present, one
+ * line, cleared rather than deleted, never rekinded. Register it with `registerChromeLeaf`. No
+ * container metadata may come from the row's bytes, so typing in it re-reads none.
+ */
+export interface ReservedChrome {
+    kind: AnyBlockKind;
+    /**
+     * A pure check of the collapsed state (node in, boolean out; no DOM, no component state).
+     * Collapse-aware traversals stop at the title row rather than reach into the hidden body.
+     */
+    isCollapsed?: (node: NodeView) => boolean;
+    /**
+     * The metadata patch that expands a collapsed node, so focusing a hidden body child opens
+     * it. Null or absent: no way to expand, and focus goes to the title row.
+     */
+    expandPatch?: (node: NodeView) => Record<string, unknown> | null;
+}
+/**
+ * How a clipboard whose top block is this kind merges into a same-kind ancestor instead of
+ * nesting as a sub-container. Absent means always nest.
+ */
+export interface ContainerPaste {
+    /** Confirms the merge against the candidate ancestor (e.g. equal list ordered flags). */
+    matchesAncestor: (clipboardTop: CstNode, ancestor: CstNode) => boolean;
+    /**
+     * Pasting into a non-empty single block: splice the clipboard items as siblings into the
+     * enclosing container when it matches, split it when it does not (the list paste shape).
+     */
+    siblingAbsorb: boolean;
+}
 export interface BlockKindDescriptor {
     mergeRole: MergeRole;
     editable: boolean;
     /**
-     * The kind's closure-matrix row: its answer to every cross-cutting editor system. Required,
-     * so a kind cannot ship closed under a subsystem nobody asked about.
+     * The kind's row in the closure matrix: its answer for every cross-cutting editor system.
+     * Required, so a kind cannot ship without answering for a subsystem nobody asked about.
      */
     closure: ClosureBlock;
     /**
-     * Markdown parsing to a tree containing this kind, for the conformance battery; omit for
-     * kinds no document scan yields in isolation. G1.24 checks a declared fixture, not existence.
+     * The block's name, to a screen reader and in the block menu ("Diagram"). Omitted, the kind
+     * name in words stands in. Built-in kinds are named in `a11y-strings.ts`, not here.
+     */
+    label?: string;
+    /**
+     * Markdown that parses to a tree holding this kind, for the conformance suite. Omit it for a
+     * kind no document parse yields alone; only a declared fixture is checked (G1.24).
      */
     conformanceFixture?: string;
     /**
      * `'whole-block'` opts an opaque, childless block into the focus-then-delete model: arrow
-     * traversal stops on it, and Backspace/Delete focuses it before a second press deletes.
+     * traversal stops on it, and Backspace/Delete focuses it before a second keypress deletes.
      */
     blockFocus?: 'whole-block';
     /**
-     * Edges whose sibling-paragraph insertion this kind's own editing surface cannot host, so an
-     * eligible boundary beside it gets a gap caret (`selection/gap-caret.ts`). Required, with
-     * `'none'` the explicit answer: the surface, or an existing affordance, already covers
-     * insertion at both edges. An omission once read as that decision; now it cannot compile.
+     * Edges where this kind's own editing cannot insert a sibling paragraph, so the boundary gets a
+     * gap caret (`selection/gap-caret.ts`). `'none'`: the block or a control covers both edges.
      */
     gapEdges: 'before' | 'after' | 'both' | 'none';
     isContainer: boolean;
     /**
-     * Shape of a container's raw↔children relationship (container kinds only).
-     * `'strip'` — outer syntax wraps a strip-and-recurse body: `strip(raw) === serialize(children)`.
-     * `'grid'` — cells parse straight from `raw`, and that does not hold. A cell index addresses
-     * the OUTER grid as `row * width + column`: rows of equal-width cells, the width read off row 0.
-     * `'opaque'` — `raw` is authoritative, not a strip-decomposition; exempt from the stale-raw
-     * byte-check, and its `rebuildRaw` must be deterministic over children/metadata/inner trivia.
+     * How `raw` relates to the children: `docs/design/syntax-tree.md` § The container contract.
+     * A grid's cell index is `row * width + column`, every row as wide as row 0.
      */
     containerContract?: 'strip' | 'grid' | 'opaque';
     /**
-     * The wrap this container's opener parses its body with, when the body sits between chrome
-     * lines of the container's own: a parse then peels the chrome-adjacent blank line into
-     * `innerPrefix`/`innerSuffix` (`core/parser.parseContainerBody`), which is what makes that
-     * line the wrap's rather than a body block. Absent = the body starts at the container's own
-     * first line (blockquote, list item) and `innerPrefix` is always empty.
+     * For a body between the container's own marker lines (a fence, an HTML tag), whose parse gives
+     * each marker's neighbouring blank line to `innerPrefix`/`innerSuffix`. Absent: body on line one.
      */
     bodyWrap?: ContainerBodyWrap;
     /**
-     * The kind has no standalone line recognizer, so `parse(raw)` would NOT reproduce it: its
-     * container's rebuildRaw owns the syntax, and a content edit writes `raw` without re-deriving.
+     * The kind has no opener of its own, so `parse(raw)` would not reproduce it: its container's
+     * `rebuildRaw` owns the syntax, and a content edit writes `raw` without reparsing the kind.
      */
     contextDependentKind?: boolean;
     /**
-     * Make `raw` legal as this kind's own bytes: escape what the grammar would restructure, and
-     * restore, drop, escalate or sanitize the block's own syntax around a write that broke it
-     * (`schema/fenced-code-raw.ts` is the worked rule). Reads `node` for the block's own shape,
-     * must be idempotent, and owes callers a caret image when it is not prefix-composable. Every
-     * write sink applies it.
-     */
-    normalizeRawWrite?: (raw: string, node: NodeView) => string;
-    /**
-     * Make text legal as a CHILD's raw inside this container's body (container kinds only) —
-     * `normalizeRawWrite`'s ancestor-side counterpart, for a container whose FIXED terminator
-     * (`</details>`) a body write could otherwise reproduce and truncate on. Applied at the write
-     * sinks upstream of the kind-deriving reparse, since the escape changes what the bytes parse
-     * to. `normalize` is idempotent and LINE-LOCAL; `mapOffset` is its exact caret image.
+     * The kind can take the lines right below it as its own (a link definition's title, an HTML
+     * block's body), so a write here or just below asks whether the two blocks now read as one.
      */
-    bodyWrite?: {
-        normalize: (raw: string) => string;
-        mapOffset: (raw: string, offset: number) => number;
-    };
+    readsFollowingLines?: true;
     /**
-     * Child index 0 is a reserved chrome leaf of the given kind — a title whose bytes live in the
-     * container's own raw. Enforced: always present, single-line, cleared-not-deleted by range
-     * ops, kind-stable. Register the chrome kind itself via `registerChromeLeaf`.
+     * Make `raw` legal as this kind's own bytes (`schema/fenced-code-raw.ts` is the worked example).
+     * `ctx.node` is the block as it stood before the write.
      */
-    reservedChrome?: {
-        kind: AnyBlockKind;
-        /**
-         * PURE model probe (node in, bool out; no DOM, no component state) for collapsed state.
-         * Collapse-aware walks stop at the chrome leaf rather than reach into a clamped-out body.
-         */
-        isCollapsed?: (node: NodeView) => boolean;
-        /**
-         * Pure patch that expands a collapsed node, so a reveal aimed at a clamped-out body child
-         * opens the container. Absent or null = no door, and the reveal degrades to the chrome row.
-         */
-        expandPatch?: (node: NodeView) => Record<string, unknown> | null;
-    };
+    rawWrite?: WriteRule;
     /**
-     * How a clipboard whose TOP block is this kind merges into a same-kind ancestor instead of
-     * nesting as a sub-container. Absent = always nest (the default structural path).
+     * Make text legal as a child's raw in this container's body, before the reparse, for a container
+     * whose closing line (`</details>`) a body write could reproduce. `ctx.node` is the container.
      */
-    containerPaste?: {
-        /** Confirms the merge against the candidate ancestor (e.g. equal list ordered flags). */
-        matchesAncestor: (clipboardTop: CstNode, ancestor: CstNode) => boolean;
-        /**
-         * Non-empty single-block targets: splice clipboard items as siblings in the enclosing
-         * container when it matches, split it when it doesn't. The apply path is list-shaped.
-         */
-        siblingAbsorb: boolean;
-    };
-    /** Backspace-at-start unwrap strategies for this container's children. Absent = default dispatch. */
+    bodyWrite?: WriteRule;
+    reservedChrome?: ReservedChrome;
+    containerPaste?: ContainerPaste;
     unwrapRole?: UnwrapRole;
     /**
-     * `'complete-marker'` consumes EVERY space typed at the content start of an empty child, at
-     * any child index, repeated presses included. A `rebuildRaw` that canonicalizes the marker's
-     * trailing space is what makes the first press byte-honest: the space it took reappears the
-     * moment content arrives. Without one, every press is simply eaten.
+     * Takes the first space typed at a child's content start while its marker lacks one. `rebuildRaw`
+     * must restore the marker's trailing space, or the taken space never appears.
      */
     contentStartSpace?: 'complete-marker';
-    /** This container's direct children reorder among themselves. Absent = not reorder-within. */
+    /** This container's direct children reorder among themselves. Absent means they do not. */
     reorderChildren?: ReorderChildrenRole;
-    /** Chord -> command map, consulted before the global table so a kind can shadow a global. */
+    /** Chord -> command map, consulted before the global table so a kind can shadow a global.
+     *  Registration throws on a malformed chord and stores the rest normalized. */
     keymap?: KeyBinding[];
     /** True when the block's raw contains inline syntax the inline parser should process on every edit. */
     supportsInline: boolean;
+    /** The registration's `contentStart.range`. Absent = the default `start=0, end=displayLength`. */
+    getContentRange?: ContentStart['range'];
+    /** The registration's `contentStart.backspace`. */
+    contentStartBackspace?: ContentStart['backspace'];
     /**
-     * Content range (post-marker offsets) in a node's raw, for prose kinds whose markers occupy
-     * a prefix of it. Absent = the default `start=0, end=displayLength`.
-     */
-    getContentRange?: (node: NodeView) => {
-        start: number;
-        end: number;
-    };
-    /**
-     * `'demote-first'` makes Backspace at the CONTENT start give up this kind's own structural
-     * bytes before merging — the first press a user can aim at markers they cannot see
-     * (live-mode.md § 4.4).
-     * Marker-hiding modes only; requires `getContentRange` (G1.32). Absent = the merge cascade.
-     */
-    contentStartBackspace?: 'demote-first';
-    /**
-     * Recompute `raw` from children + metadata; built-ins in `schema/container-rebuilders.ts`.
-     * `changed` names the one child whose own raw just moved, for a rebuilder that can rewrite
-     * that child's region instead of re-reading every child. Ignoring it is always correct.
+     * Recompute `raw` from children and metadata. `changed` names the one child whose raw moved, for
+     * a rebuilder that rewrites only its region; ignoring it is always correct.
      */
     rebuildRaw?: (node: CstNode, changed?: ChildRawChange) => void;
     /** Inline image nodes render as widgets in this kind; opt out (e.g. tableCell) for alt-only fallback. */
     renderImagesAsWidgets?: boolean;
     /**
-     * Translate a foreign drag's viewport point into an internal focus offset, for a kind with
-     * its own coordinate addressing; null when the point is outside an addressable region.
-     * Patched in from `components/built-in-blocks.ts`, so schema keeps no component import.
+     * A foreign drag's viewport point as an offset in the kind's own addressing, or null outside it.
+     * Added from `components/built-in-blocks.ts`, so schema keeps no component import.
      */
     foreignDragHitTest?: (blockEl: HTMLElement, clientX: number, clientY: number) => number | null;
     /**
-     * Translate a point in this block's box into a caret landing in the kind's own addressing.
-     * TOTAL within the box, unlike {@link foreignDragHitTest}: snap to the NEAREST leaf where a
-     * drag declines off-cell.
+     * A point in the block's box as a caret position in the kind's own addressing. Unlike
+     * {@link foreignDragHitTest} it answers every point, snapping to the nearest leaf.
      */
     caretTargetAtPoint?: (blockEl: HTMLElement, clientX: number, clientY: number) => CaretTarget | null;
-    /** O(1) content-height estimate in px for virtual rendering — no subtree walk.
-     *  The oracle adds block chrome; the measured cache still supersedes. */
-    estimateHeight?: (node: NodeView, env: {
-        width: number;
-    }) => number;
+    /**
+     * O(1) content height in px for windowing, frame excluded; a measured height still wins.
+     * `height-estimates.ts` has the common shapes. Absent: the container or prose estimate.
+     */
+    estimateHeight?: (node: NodeView, env: HeightEstimateEnv) => number;
+    /**
+     * `'prose'` is text the user writes in: no drag handle, and a right-click opens clipboard rows.
+     * `'object'`, the default, is picked up whole, with a handle and a block menu.
+     */
+    pageRole?: 'prose' | 'object';
+    /** What the drag ghost calls the block, for one whose text reads badly as a label (a formula's
+     *  source). Absent, the ghost shows the block's first words; blank throws. */
+    dragLabel?: string;
 }
 /**
- * The descriptor's fields as data, for the census that holds the published field reference
- * (`docs/design/plugin-contract.md`) to this type. Complete in both directions below, so the
- * manifest cannot drift from the shape it enumerates.
+ * The descriptor's fields as data, for the check that holds the field table in
+ * `docs/design/plugin-contract.md` to this type; the compile check below keeps the list complete.
  */
-export declare const DESCRIPTOR_FIELDS: readonly ["mergeRole", "editable", "closure", "conformanceFixture", "blockFocus", "gapEdges", "isContainer", "containerContract", "bodyWrap", "contextDependentKind", "normalizeRawWrite", "bodyWrite", "reservedChrome", "containerPaste", "unwrapRole", "contentStartSpace", "reorderChildren", "keymap", "supportsInline", "getContentRange", "contentStartBackspace", "rebuildRaw", "renderImagesAsWidgets", "foreignDragHitTest", "caretTargetAtPoint", "estimateHeight"];
+export declare const DESCRIPTOR_FIELDS: readonly ["mergeRole", "editable", "closure", "label", "conformanceFixture", "blockFocus", "gapEdges", "isContainer", "containerContract", "bodyWrap", "contextDependentKind", "readsFollowingLines", "rawWrite", "bodyWrite", "reservedChrome", "containerPaste", "unwrapRole", "contentStartSpace", "reorderChildren", "keymap", "supportsInline", "getContentRange", "contentStartBackspace", "rebuildRaw", "renderImagesAsWidgets", "foreignDragHitTest", "caretTargetAtPoint", "estimateHeight", "pageRole", "dragLabel"];
 /**
- * Container-only fields as one unit: `contract` and `rebuildRaw` are required together, and a
- * leaf has no way to carry any of them. Field semantics live on `BlockKindDescriptor`, the flat
- * read-side shape the group normalizes into.
+ * Where a prose kind's content starts, for one whose markers take a prefix of its raw. The
+ * Backspace behavior needs the range, so the two travel together.
  */
-export interface ContainerDescriptorGroup {
+export interface ContentStart {
+    /** The content range (post-marker offsets) in a node's raw. */
+    range: (node: NodeView) => {
+        start: number;
+        end: number;
+    };
+    /**
+     * In modes that hide markers, Backspace at the content start strips this kind's markers before
+     * merging (`docs/design/live-mode.md` § 4.4 Cutting a construct open).
+     */
+    backspace?: 'demote-first';
+}
+/** Container-only fields as one unit, so a leaf can't carry any of them. Each is documented on
+ *  `BlockKindDescriptor`, the flat read shape this group normalizes into. */
+interface ContainerBase {
     contract: 'strip' | 'grid' | 'opaque';
     rebuildRaw: (node: CstNode, changed?: ChildRawChange) => void;
     bodyWrap?: ContainerBodyWrap;
-    reservedChrome?: BlockKindDescriptor['reservedChrome'];
-    containerPaste?: BlockKindDescriptor['containerPaste'];
-    unwrapRole?: UnwrapRole;
-    contentStartSpace?: BlockKindDescriptor['contentStartSpace'];
+    containerPaste?: ContainerPaste;
+    contentStartSpace?: 'complete-marker';
     reorderChildren?: ReorderChildrenRole;
-    bodyWrite?: BlockKindDescriptor['bodyWrite'];
+    bodyWrite?: WriteRule;
+}
+interface ContainerWithoutChrome extends ContainerBase {
+    reservedChrome?: never;
+    unwrapRole?: ContainerUnwrapRole;
 }
+/** Backspace at a title row's start never lifts it out, so only the middle strategy is declared. */
+interface ContainerWithChrome extends ContainerBase {
+    reservedChrome: ReservedChrome;
+    unwrapRole?: {
+        /** Implied: Backspace at the start of the title row keeps it. */
+        firstChildBackspace?: never;
+        middleChildBackspace: ContainerUnwrapRole['middleChildBackspace'];
+    };
+}
+export type ContainerDescriptorGroup = ContainerWithChrome | ContainerWithoutChrome;
 export declare const CONTAINER_ONLY_KEYS: readonly ["isContainer", "containerContract", "bodyWrap", "rebuildRaw", "reservedChrome", "containerPaste", "unwrapRole", "contentStartSpace", "reorderChildren", "bodyWrite"];
-type ContainerOnlyKey = (typeof CONTAINER_ONLY_KEYS)[number];
+declare const GROUPED_KEYS: readonly ["isContainer", "containerContract", "bodyWrap", "rebuildRaw", "reservedChrome", "containerPaste", "unwrapRole", "contentStartSpace", "reorderChildren", "bodyWrite", "getContentRange", "contentStartBackspace"];
+type GroupedKey = (typeof GROUPED_KEYS)[number];
 /**
- * The write-side shape `registerBlockKind` accepts. `isContainer` is derived
- * (`container !== undefined`), never declared.
+ * The fields another field constrains, so only a registration sets them. One list drives the
+ * registration and augment types and the augment's runtime refusal; `container.` names a group field.
+ */
+export declare const FIXED_AT_REGISTRATION: readonly ["blockFocus", "supportsInline", "contentStart", "container.reservedChrome", "container.unwrapRole"];
+type FixedField = (typeof FIXED_AT_REGISTRATION)[number];
+type FixedTopKey = Exclude<FixedField, `container.${string}`>;
+type ContainerFieldOf<F> = F extends `container.${infer Key}` ? Key : never;
+type FixedContainerKey = ContainerFieldOf<FixedField>;
+/** The fields no other field constrains, shared by both registration shapes. */
+type RegistrationBase = Omit<BlockKindDescriptor, GroupedKey | FixedTopKey>;
+/**
+ * A block focused as one unit: arrow traversal stops on it, and Backspace/Delete focuses it before
+ * a second press deletes. No caret enters it, so it has no inline content, content start or title row.
  */
-export interface BlockKindRegistration extends Omit<BlockKindDescriptor, ContainerOnlyKey> {
+export interface WholeBlockRegistration extends RegistrationBase {
+    blockFocus: 'whole-block';
+    supportsInline: false;
+    contentStart?: never;
+    container?: ContainerWithoutChrome;
+}
+/** A block the caret enters: a text leaf, or a container whose children take the caret. */
+export interface CaretBlockRegistration extends RegistrationBase {
+    blockFocus?: never;
+    supportsInline: boolean;
+    contentStart?: ContentStart;
     container?: ContainerDescriptorGroup;
 }
+/**
+ * The write-side shape `registerBlockKind` accepts. `isContainer` is derived
+ * (`container !== undefined`), never declared.
+ */
+export type BlockKindRegistration = WholeBlockRegistration | CaretBlockRegistration;
 /**
  * The augment shape: top-level fields replace; a partial `container` group merges into the
- * existing group, and is refused outright for a kind registered as a leaf.
+ * existing group, and is refused outright for a kind registered as a leaf. Fields another field
+ * depends on are fixed at registration, and naming one throws.
  */
-export type BlockKindAugmentation = Partial<Omit<BlockKindRegistration, 'container'>> & {
-    container?: Partial<ContainerDescriptorGroup>;
+export type BlockKindAugmentation = Partial<RegistrationBase> & {
+    [Key in FixedTopKey]?: never;
+} & {
+    container?: Partial<ContainerBase> & {
+        [Key in FixedContainerKey]?: never;
+    };
 };
 export declare function registerBlockKind(kind: AnyBlockKind, registration: BlockKindRegistration): void;
 /**
- * Merge fields into a plugin's own registration — the public authoring entry. Rejects built-in
- * kinds (built-in wire-up uses the internal `augmentBuiltin` seam) and kinds owned by a
- * different plugin, so cross-plugin last-writer-wins is a loud throw rather than a silent
- * override. A kind with no recorded owner (declared outside any plugin install) stays open.
+ * Merge fields into a plugin's own kind. Throws for a built-in or another plugin's kind, so an
+ * overwrite is never silent; a kind whose descriptor no plugin owns stays open.
  */
 export declare function augmentBlockKind(kind: AnyBlockKind, fields: BlockKindAugmentation): void;
 /**
- * Internal seam for augmenting a BUILT-IN descriptor: top-of-DAG wire-up
- * (`components/built-in-blocks.ts`) patches in behavior this file cannot import. Kept off the
- * public `@voithos-labs/aragonite/plugin` surface so a plugin can't rewrite a built-in.
+ * Patch a built-in descriptor with behavior schema cannot import (`components/built-in-blocks.ts`).
+ * Kept off the plugin API so a plugin cannot rewrite a built-in.
  */
 export declare function augmentBuiltin(kind: AnyBlockKind, fields: BlockKindAugmentation): void;
 export declare function getBlockKindDescriptor(kind: AnyBlockKind): BlockKindDescriptor;
 export declare function tryGetBlockKindDescriptor(kind: AnyBlockKind): BlockKindDescriptor | undefined;
+/** Whether a kind declares the grid contract: a table and its rows, or a plugin's equivalent. A
+ *  cell is in a grid when its parent row is one. */
+export declare function isGridKind(kind: AnyBlockKind): boolean;
+/** {@link isGridKind} for a caller already holding the descriptor. */
+export declare function isGridDescriptor(descriptor: BlockKindDescriptor | undefined): boolean;
+/** Whether a block of this kind is broken with no children: every container, except one focused
+ *  as a whole block, which is its own caret target. */
+export declare function mustHoldChild(kind: AnyBlockKind): boolean;
+/** Whether an endpoint on this block's own path counts cells rather than characters. Tables only:
+ *  a plugin grid's endpoints stay character offsets on deep cell paths. */
+export declare function countsCells(node: NodeView | DocumentView): node is Extract<NodeView, {
+    kind: 'table';
+}>;
+/**
+ * How many cells a table's index space holds, the exclusive upper bound on any row-major cell
+ * index. `node` must be a table block; the metadata read is unchecked, so other kinds give NaN.
+ */
+export declare function tableCellCount(node: NodeView): number;
+/** A cell index clamped into a table's grid: the one upper bound every cell-space caller uses. */
+export declare function clampCellIndex(node: NodeView, cellIdx: number): number;
 /**
- * Probe whether a kind descriptor exists — `registerBlockKind` throws on duplicate, so a plugin
- * registering idempotently (HMR / re-import) guards on this. Takes a plain, unbranded name.
+ * Is a kind descriptor registered? `registerBlockKind` throws on a duplicate, so a plugin that
+ * may register twice (hot reload, re-import) checks this first. Takes a plain, unbranded name.
  */
 export declare function isBlockKindRegistered(kind: string): boolean;
 /** Every kind currently registered. Caller must not mutate. */
 export declare function getAllRegisteredKinds(): AnyBlockKind[];
-/** Test-only. Removes every non-built-in descriptor; built-ins survive. */
-export declare function __removePluginBlockKindsForTests(): void;
 export {};