@voithos-labs/aragonite 0.10.1

package/dist/schema/block-component-registry.js

@@ -0,0 +1,33 @@
+/**
+ * Runtime `BlockKind → component` map. BlockHost looks up by kind; plugin
+ * kinds register a descriptor plus a component entry.
+ */
+import { isBuiltinBlockKind } from '../core/nodes';
+import { deletePluginEntries, registerOnce } from './register-once';
+/**
+ * Typed constructor for a registry entry: the component publishes one of the two sanctioned
+ * surface shapes, and its props are a subset of what BlockHost passes. A container that forgot
+ * its `containerApi` fails here rather than mounting as a block nothing can focus. The internal
+ * cast widens contravariant props to the registry's `Record<string, unknown>`.
+ */
+export function defineBlockComponent(component, extraProps) {
+    return { component: component, extraProps };
+}
+const registry = new Map();
+export function registerBlockComponent(kind, entry) {
+    registerOnce(registry.has(kind), () => registry.set(kind, entry), `registerBlockComponent: "${kind}" is already registered. Components are register-once.`);
+}
+export function getBlockComponent(kind) {
+    return registry.get(kind);
+}
+/**
+ * Probe whether a component is registered — `registerBlockComponent` throws on duplicate, so a
+ * plugin registering idempotently (HMR / re-import) guards on this. Takes a plain name.
+ */
+export function isBlockComponentRegistered(kind) {
+    return registry.has(kind);
+}
+/** Test-only. Removes every non-built-in component entry; built-ins survive. */
+export function __removePluginComponentsForTests() {
+    deletePluginEntries(registry, isBuiltinBlockKind);
+}

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

@@ -0,0 +1,281 @@
+import { type AnyBlockKind, type CstNode } from '../core/nodes';
+import type { NodeView } from '../core/node-views';
+import type { ContainerBodyWrap } from '../core/parser';
+import type { ChildRawChange } from './child-spans';
+import type { ClosureBlock } from './closure';
+import type { KeyBinding } from './keybindings';
+/**
+ * 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.
+ */
+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). */
+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.
+ */
+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;
+    middleChildBackspace: 'default-merge' | 'list-item-cascade';
+}
+/**
+ * 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.
+ */
+export interface ReorderChildrenRole {
+    /**
+     * Direct children carry position-dependent markers needing a renumber after a permutation
+     * (ordered-list numbering). Absent = position-independent, so `rebuildRaw` alone re-emits.
+     */
+    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".
+ */
+export interface CaretTarget {
+    path: number[];
+    offset: number;
+}
+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.
+     */
+    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.
+     */
+    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.
+     */
+    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.
+     */
+    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.
+     */
+    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.
+     */
+    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.
+     */
+    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.
+     */
+    bodyWrite?: {
+        normalize: (raw: string) => string;
+        mapOffset: (raw: string, offset: number) => number;
+    };
+    /**
+     * 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`.
+     */
+    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;
+    };
+    /**
+     * 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).
+     */
+    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. */
+    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.
+     */
+    contentStartSpace?: 'complete-marker';
+    /** This container's direct children reorder among themselves. Absent = not reorder-within. */
+    reorderChildren?: ReorderChildrenRole;
+    /** Chord -> command map, consulted before the global table so a kind can shadow a global. */
+    keymap?: KeyBinding[];
+    /** True when the block's raw contains inline syntax the inline parser should process on every edit. */
+    supportsInline: boolean;
+    /**
+     * 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.
+     */
+    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.
+     */
+    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.
+     */
+    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;
+}
+/**
+ * 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.
+ */
+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"];
+/**
+ * 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.
+ */
+export interface ContainerDescriptorGroup {
+    contract: 'strip' | 'grid' | 'opaque';
+    rebuildRaw: (node: CstNode, changed?: ChildRawChange) => void;
+    bodyWrap?: ContainerBodyWrap;
+    reservedChrome?: BlockKindDescriptor['reservedChrome'];
+    containerPaste?: BlockKindDescriptor['containerPaste'];
+    unwrapRole?: UnwrapRole;
+    contentStartSpace?: BlockKindDescriptor['contentStartSpace'];
+    reorderChildren?: ReorderChildrenRole;
+    bodyWrite?: BlockKindDescriptor['bodyWrite'];
+}
+export declare const CONTAINER_ONLY_KEYS: readonly ["isContainer", "containerContract", "bodyWrap", "rebuildRaw", "reservedChrome", "containerPaste", "unwrapRole", "contentStartSpace", "reorderChildren", "bodyWrite"];
+type ContainerOnlyKey = (typeof CONTAINER_ONLY_KEYS)[number];
+/**
+ * The write-side shape `registerBlockKind` accepts. `isContainer` is derived
+ * (`container !== undefined`), never declared.
+ */
+export interface BlockKindRegistration extends Omit<BlockKindDescriptor, ContainerOnlyKey> {
+    container?: ContainerDescriptorGroup;
+}
+/**
+ * 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.
+ */
+export type BlockKindAugmentation = Partial<Omit<BlockKindRegistration, 'container'>> & {
+    container?: Partial<ContainerDescriptorGroup>;
+};
+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.
+ */
+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.
+ */
+export declare function augmentBuiltin(kind: AnyBlockKind, fields: BlockKindAugmentation): void;
+export declare function getBlockKindDescriptor(kind: AnyBlockKind): BlockKindDescriptor;
+export declare function tryGetBlockKindDescriptor(kind: AnyBlockKind): BlockKindDescriptor | undefined;
+/**
+ * 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.
+ */
+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 {};

package/dist/schema/block-kind-descriptor.js

@@ -0,0 +1,187 @@
+import { isBuiltinBlockKind } from '../core/nodes';
+import { enqueueRegistrationCheck } from './registration-pending';
+import { currentInstallingPlugin, pluginKindOwner } from './plugin-install';
+import { deletePluginEntries, registerOnce } from './register-once';
+/**
+ * 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.
+ */
+export const MERGE_ROLES = [
+    'prose',
+    'prose-absorber',
+    'container',
+    'self-merge',
+    'not-mergeable'
+];
+/** G1.30's runtime half, for the registrations a `MergeRole` parameter cannot bind (plugin casts). */
+export const isKnownMergeRole = (role) => MERGE_ROLES.includes(role);
+/**
+ * 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.
+ */
+const FIRST_CHILD_BACKSPACE_LIFTS = {
+    'lift-first-child-drop-opener': true,
+    'lift-first-child-keep-container': true,
+    'keep-reserved-chrome': false,
+    'list-item-cascade': false
+};
+export const liftsFirstChild = (strategy) => FIRST_CHILD_BACKSPACE_LIFTS[strategy];
+/**
+ * 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.
+ */
+export const DESCRIPTOR_FIELDS = [
+    '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'
+];
+const _descriptorFieldsAreComplete = true;
+void _descriptorFieldsAreComplete;
+// One source for both the type-level Omit and the runtime strip: excess-property checks bite
+// only fresh literals, so a widened value can structurally smuggle these keys past the types.
+export const CONTAINER_ONLY_KEYS = [
+    'isContainer',
+    'containerContract',
+    'bodyWrap',
+    'rebuildRaw',
+    'reservedChrome',
+    'containerPaste',
+    'unwrapRole',
+    'contentStartSpace',
+    'reorderChildren',
+    'bodyWrite'
+];
+const _containerOnlyKeysAreComplete = true;
+void _containerOnlyKeysAreComplete;
+function stripContainerOnlyKeys(fields) {
+    const stripped = { ...fields };
+    for (const key of CONTAINER_ONLY_KEYS)
+        delete stripped[key];
+    return stripped;
+}
+// ── Registry ────────────────────────────────────────────────────────────────
+const registry = new Map();
+// ── Public API ──────────────────────────────────────────────────────────────
+export function registerBlockKind(kind, registration) {
+    const isDuplicate = registry.has(kind);
+    const owner = isDuplicate ? pluginKindOwner(kind) : null;
+    registerOnce(isDuplicate, () => {
+        registry.set(kind, normalizeRegistration(registration));
+        enqueueRegistrationCheck(kind);
+    }, `registerBlockKind: "${kind}" is already registered. Kinds are register-once — ` +
+        `use augmentBlockKind to merge fields into an existing registration.` +
+        (owner ? ` — first declared by plugin '${owner}'` : ''));
+}
+// The flat part is stripped and isContainer derived, so the `container` group is the only
+// source of container fields — a widened or stale-keyed registration object cannot leak.
+function normalizeRegistration(registration) {
+    const { container, ...rest } = registration;
+    const flat = stripContainerOnlyKeys(rest);
+    if (!container)
+        return { ...flat, isContainer: false };
+    const { contract, ...containerFields } = container;
+    return { ...flat, ...containerFields, isContainer: true, containerContract: contract };
+}
+// Throws if the kind was never registered (no accidental creation via partial data). The
+// built-in-vs-plugin gate lives in the two public entries below; the leaf/container gate lives
+// here so both entries inherit it.
+function mergeBlockKindFields(entry, kind, fields) {
+    const existing = registry.get(kind);
+    if (!existing) {
+        throw new Error(`${entry}: cannot augment "${kind}" — no base descriptor. Call registerBlockKind first.`);
+    }
+    const { container, ...rest } = fields;
+    const next = { ...existing, ...stripContainerOnlyKeys(rest) };
+    if (container) {
+        if (!existing.isContainer) {
+            throw new Error(`${entry}: cannot augment "${kind}" with container fields — it was registered as a leaf`);
+        }
+        // Merge, never unset: skipping undefined keeps an explicitly-undefined group field from
+        // breaking the contract/rebuild pairing. Keyed off the group, not a hand-kept field list.
+        const { contract, ...group } = container;
+        next.containerContract = contract ?? existing.containerContract;
+        Object.assign(next, Object.fromEntries(Object.entries(group).filter(([, value]) => value !== undefined)));
+    }
+    registry.set(kind, next);
+    enqueueRegistrationCheck(kind);
+}
+/**
+ * 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.
+ */
+export function augmentBlockKind(kind, fields) {
+    if (isBuiltinBlockKind(kind)) {
+        throw new Error(`augmentBlockKind: "${kind}" is a built-in kind — the plugin surface may only augment ` +
+            `plugin-declared kinds.`);
+    }
+    const owner = pluginKindOwner(kind);
+    const installer = currentInstallingPlugin();
+    if (owner !== null && owner !== installer) {
+        throw new Error(`augmentBlockKind: "${kind}" is owned by plugin '${owner}' — ` +
+            (installer
+                ? `plugin '${installer}' may not augment another plugin's kind.`
+                : `only plugin '${owner}' may augment its own kind, from its setup.`));
+    }
+    mergeBlockKindFields('augmentBlockKind', kind, fields);
+}
+/**
+ * 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.
+ */
+export function augmentBuiltin(kind, fields) {
+    mergeBlockKindFields('augmentBuiltin', kind, fields);
+}
+export function getBlockKindDescriptor(kind) {
+    const d = registry.get(kind);
+    if (!d) {
+        throw new Error(`getBlockKindDescriptor: no descriptor registered for kind "${kind}". ` +
+            `Register at module load (see built-in-descriptors.ts).`);
+    }
+    return d;
+}
+export function tryGetBlockKindDescriptor(kind) {
+    return registry.get(kind);
+}
+/**
+ * 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.
+ */
+export function isBlockKindRegistered(kind) {
+    return registry.has(kind);
+}
+/** Every kind currently registered. Caller must not mutate. */
+export function getAllRegisteredKinds() {
+    return Array.from(registry.keys());
+}
+/** Test-only. Removes every non-built-in descriptor; built-ins survive. */
+export function __removePluginBlockKindsForTests() {
+    deletePluginEntries(registry, isBuiltinBlockKind);
+}

package/dist/schema/block-openers.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Per-kind block-opener registry: the parser's dispatch order and the paragraph-interrupt scan
+ * both derive from these declarations, so a registered opener is automatically in both.
+ * Paragraph is the unregistered total fallback; setext headings and tables emerge from its
+ * continuation scan, not from openers.
+ */
+import { type AnyBlockKind, type CstNode } from '../core/nodes';
+import type { ParsedLine } from '../core/lines';
+/** Minted fresh per block and read synchronously; never a handle to keep past the return. */
+export interface OpenContext {
+    lines: ParsedLine[];
+    index: number;
+    end: number;
+    /** The line at `index`, precomputed once per dispatch. */
+    line: ParsedLine;
+    /** Blank-line bytes folded above this block: non-empty is the "preceded by blank" interrupt context (GFM §4.4). */
+    leadingTrivia: string;
+    /** True when this parse entry was given a whole document (`parse` scope `'document'`), false for one block's bytes read standalone. Constant through nested container recursion, so a document-position gate composes it with `index`/`depth`/`leadingTrivia`. */
+    isDocumentParse: boolean;
+    /** Container-nesting depth of this parse level (0 at the document root). A container opener that reparses its body recurses at `depth + 1`; the cap (`MAX_NESTING_DEPTH`) folds deeper input into paragraph content. */
+    depth: number;
+    /**
+     * The instance seam over the global openers. Nested container reparses create their own
+     * context and default to the global grammar (the enablement boundary — see `parse`).
+     */
+    grammar: GrammarView;
+}
+/**
+ * A claim on the lines starting at `ctx.index`. `consumed` is a count, not a resume position,
+ * and must be >= 1 — claiming nothing would spin the parse loop, so the dispatch declines it.
+ */
+export interface BlockOpenerResult {
+    node: CstNode;
+    consumed: number;
+}
+export interface BlockOpener {
+    priority: number;
+    /** Attempt to open this kind at ctx.index; null declines. */
+    tryOpen(ctx: OpenContext): BlockOpenerResult | null;
+    /** Whether a line of this kind interrupts an open paragraph (GFM continuation rules); `false` = never. */
+    interruptsParagraph: ((lineText: string) => boolean) | false;
+}
+export declare function registerBlockOpener(kind: AnyBlockKind, opener: BlockOpener): void;
+/**
+ * Probe whether an opener is registered — `registerBlockOpener` throws on duplicate, so a
+ * plugin registering idempotently (HMR / re-import) guards on this. Takes a plain name.
+ */
+export declare function isBlockOpenerRegistered(kind: string): boolean;
+/** A per-instance enablement predicate: `true` keeps the kind's opener in the grammar. */
+export type OpenerEnablement = (kind: AnyBlockKind) => boolean;
+/**
+ * The parser's dispatch order (G1.10 warns on a priority tie). The grammar-consumption seam:
+ * pending registrations are validated before this read, and flush-before-mark keeps a registrant
+ * racing the first read out of the late-opener warn (G1.17). `isEnabled` filters plugin kinds
+ * per instance; absent = all definitions, cached. Built-ins are never filtered.
+ */
+export declare function getOrderedOpeners(isEnabled?: OpenerEnablement): readonly BlockOpener[];
+/**
+ * Registry-derived paragraph-interrupt check, carrying the same seam duties as
+ * `getOrderedOpeners`. NOT enablement-filtered: the parsers call it directly rather than
+ * through a GrammarView, so the interrupt scan is the global-grammar boundary.
+ */
+export declare function lineInterruptsParagraph(lineText: string): boolean;
+/**
+ * The grammar as a per-instance resolution object over the global openers, threaded by
+ * `parse(source, { grammar })`. Only the opener dispatch is instance-resolved; the
+ * paragraph-interrupt scan stays on the global-grammar boundary.
+ */
+export interface GrammarView {
+    orderedOpeners(): readonly BlockOpener[];
+}
+export declare const defaultGrammarView: GrammarView;
+export declare function createGrammarView(isEnabled: OpenerEnablement): GrammarView;
+/** What a line means at the outer level, which turns on whether a paragraph is open above it. */
+export interface OuterBlockScan {
+    /** A lazy continuation: an open paragraph absorbs the starts §4.4 forbids from interrupting. */
+    paragraphOpen: boolean;
+    /** Defaults to the global openers, the boundary `lineInterruptsParagraph` also reads. */
+    grammar?: GrammarView;
+}
+/**
+ * Does `line` start a block at the outer level? cmark-gfm ends both a lazy continuation and a
+ * table's row scan there, and the paragraph-interrupt exceptions do not apply. Two claims are
+ * transparent: a link reference definition is carved out of a paragraph at finalize rather than
+ * opened as a block, and indented code cannot open while a paragraph is open to absorb the line.
+ */
+export declare function lineStartsOuterBlock(line: ParsedLine, scan: OuterBlockScan): boolean;
+/** Registry introspection for the invariant guard (G1.10). */
+export declare function listRegisteredOpeners(): {
+    kind: AnyBlockKind;
+    priority: number;
+}[];
+export declare function __resetBlockOpenersForTests(): void;
+export declare function __removePluginOpenersForTests(): void;