@voithos-labs/aragonite 0.10.4 → 0.10.7

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

@@ -1,11 +1,12 @@
-import { isBuiltinBlockKind } from '../core/nodes';
+import { isBuiltinBlockKind, metadataOf } from '../core/nodes';
 import { enqueueRegistrationCheck } from './registration-pending';
-import { currentInstallingPlugin, pluginKindOwner } from './plugin-install';
-import { deletePluginEntries, registerOnce } from './register-once';
+import { currentInstallingPlugin } from './plugin-install';
+import { createBlockKindRegistry } from './plugin-registry';
+import { registeredChord } from './keybindings';
+import { rejectIncoherentPairs } from './registration-pairs';
 /**
- * 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 const MERGE_ROLES = [
     'prose',
@@ -14,28 +15,17 @@ export const MERGE_ROLES = [
     'self-merge',
     'not-mergeable'
 ];
-/** 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 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.
+ * 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 const DESCRIPTOR_FIELDS = [
     'mergeRole',
     'editable',
     'closure',
+    'label',
     'conformanceFixture',
     'blockFocus',
     'gapEdges',
@@ -43,7 +33,8 @@ export const DESCRIPTOR_FIELDS = [
     'containerContract',
     'bodyWrap',
     'contextDependentKind',
-    'normalizeRawWrite',
+    'readsFollowingLines',
+    'rawWrite',
     'bodyWrite',
     'reservedChrome',
     'containerPaste',
@@ -58,7 +49,9 @@ export const DESCRIPTOR_FIELDS = [
     'renderImagesAsWidgets',
     'foreignDragHitTest',
     'caretTargetAtPoint',
-    'estimateHeight'
+    'estimateHeight',
+    'pageRole',
+    'dragLabel'
 ];
 const _descriptorFieldsAreComplete = true;
 void _descriptorFieldsAreComplete;
@@ -78,70 +71,136 @@ export const CONTAINER_ONLY_KEYS = [
 ];
 const _containerOnlyKeysAreComplete = true;
 void _containerOnlyKeysAreComplete;
-function stripContainerOnlyKeys(fields) {
+// Read-shape fields a registration declares only through a group, stripped for the same reason.
+const GROUPED_KEYS = [...CONTAINER_ONLY_KEYS, 'getContentRange', 'contentStartBackspace'];
+function stripGroupedKeys(fields) {
     const stripped = { ...fields };
-    for (const key of CONTAINER_ONLY_KEYS)
+    for (const key of GROUPED_KEYS)
         delete stripped[key];
     return stripped;
 }
+/**
+ * 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 const FIXED_AT_REGISTRATION = [
+    'blockFocus',
+    'supportsInline',
+    'contentStart',
+    'container.reservedChrome',
+    'container.unwrapRole'
+];
 // ── Registry ────────────────────────────────────────────────────────────────
-const registry = new Map();
+// Never filtered by activation: a kind an editor left out still needs its descriptor to degrade.
+const registry = createBlockKindRegistry({
+    label: 'registerBlockKind',
+    isBuiltin: isBuiltinBlockKind
+});
 // ── 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 — ` +
+    rejectBlankLabel('registerBlockKind', kind, 'label', registration.label);
+    rejectBlankLabel('registerBlockKind', kind, 'dragLabel', registration.dragLabel);
+    rejectIncoherentPairs(kind, registration);
+    const descriptor = normalizeRegistration(registration);
+    if (descriptor.keymap)
+        descriptor.keymap = registeredKeymap('registerBlockKind', kind, descriptor.keymap);
+    const owner = registry.ownerOf(kind);
+    registry.register(kind, descriptor, `registerBlockKind: "${kind}" is already registered. Kinds are register-once — ` +
         `use augmentBlockKind to merge fields into an existing registration.` +
         (owner ? ` — first declared by plugin '${owner}'` : ''));
+    enqueueRegistrationCheck(kind);
+}
+// A blank label would render as an empty `aria-label`, leaving the block's textbox unnamed.
+function rejectBlankLabel(entry, kind, field, label) {
+    if (label === undefined || label.trim() !== '')
+        return;
+    throw new Error(`${entry}: "${kind}" has a blank ${field}; give it a name or omit ${field} for the default.`);
 }
-// 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.
+// Every chord is checked and normalized once here, so the resolvers compare stored chords as is.
+function registeredKeymap(entry, kind, keymap) {
+    return keymap.map((binding) => ({
+        ...binding,
+        chord: registeredChord(binding.chord, `${entry}: "${kind}" keymap`)
+    }));
+}
+// The flat part is stripped and isContainer derived, so each group is the only source of its
+// fields: a widened or stale-keyed registration object cannot leak through.
 function normalizeRegistration(registration) {
-    const { container, ...rest } = registration;
-    const flat = stripContainerOnlyKeys(rest);
+    const { container, contentStart, ...rest } = registration;
+    const flat = { ...stripGroupedKeys(rest), isContainer: false };
+    if (contentStart) {
+        flat.getContentRange = contentStart.range;
+        if (contentStart.backspace)
+            flat.contentStartBackspace = contentStart.backspace;
+    }
     if (!container)
-        return { ...flat, isContainer: false };
-    const { contract, ...containerFields } = container;
-    return { ...flat, ...containerFields, isContainer: true, containerContract: contract };
+        return flat;
+    const { contract, unwrapRole, ...containerFields } = container;
+    const descriptor = {
+        ...flat,
+        ...containerFields,
+        isContainer: true,
+        containerContract: contract
+    };
+    // A title row implies its first-child strategy; the read shape spells it out for the dispatch.
+    if (container.reservedChrome) {
+        descriptor.unwrapRole = {
+            firstChildBackspace: 'keep-reserved-chrome',
+            middleChildBackspace: unwrapRole?.middleChildBackspace ?? 'default-merge'
+        };
+    }
+    else if (container.unwrapRole)
+        descriptor.unwrapRole = container.unwrapRole;
+    return descriptor;
 }
-// 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.
+// A JavaScript caller or a cast gets past the augment types. Presence alone refuses, since an
+// explicit undefined would spread over the registered value.
+function rejectFixedFields(entry, kind, fields) {
+    for (const field of FIXED_AT_REGISTRATION) {
+        const [group, key] = field.startsWith('container.')
+            ? [fields.container, field.slice('container.'.length)]
+            : [fields, field];
+        if (!group || !(key in group))
+            continue;
+        throw new Error(`${entry}: cannot augment "${kind}" with ${field}; it is fixed at registration`);
+    }
+}
+// Throws if the kind was never registered, so partial data cannot create one.
 function mergeBlockKindFields(entry, kind, fields) {
-    const existing = registry.get(kind);
+    const existing = registry.getIgnoringActivation(kind);
     if (!existing) {
-        throw new Error(`${entry}: cannot augment "${kind}" — no base descriptor. Call registerBlockKind first.`);
+        throw new Error(`${entry}: cannot augment "${kind}"; no base descriptor. Call registerBlockKind first.`);
     }
+    rejectFixedFields(entry, kind, fields);
+    rejectBlankLabel(entry, kind, 'label', fields.label);
+    rejectBlankLabel(entry, kind, 'dragLabel', fields.dragLabel);
     const { container, ...rest } = fields;
-    const next = { ...existing, ...stripContainerOnlyKeys(rest) };
+    const next = { ...existing, ...stripGroupedKeys(rest) };
+    if (rest.keymap)
+        next.keymap = registeredKeymap(entry, kind, rest.keymap);
     if (container) {
         if (!existing.isContainer) {
-            throw new Error(`${entry}: cannot augment "${kind}" with container fields — it was registered as a leaf`);
+            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.
+        // breaking the contract/rebuild pairing.
         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);
+    registry.update(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.
+ * 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 function augmentBlockKind(kind, fields) {
     if (isBuiltinBlockKind(kind)) {
-        throw new Error(`augmentBlockKind: "${kind}" is a built-in kind — the plugin surface may only augment ` +
+        throw new Error(`augmentBlockKind: "${kind}" is a built-in kind; the plugin surface may only augment ` +
             `plugin-declared kinds.`);
     }
-    const owner = pluginKindOwner(kind);
+    const owner = registry.ownerOf(kind);
     const installer = currentInstallingPlugin();
     if (owner !== null && owner !== installer) {
         throw new Error(`augmentBlockKind: "${kind}" is owned by plugin '${owner}' — ` +
@@ -152,15 +211,14 @@ export function augmentBlockKind(kind, fields) {
     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.
+ * 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 function augmentBuiltin(kind, fields) {
     mergeBlockKindFields('augmentBuiltin', kind, fields);
 }
 export function getBlockKindDescriptor(kind) {
-    const d = registry.get(kind);
+    const d = registry.getIgnoringActivation(kind);
     if (!d) {
         throw new Error(`getBlockKindDescriptor: no descriptor registered for kind "${kind}". ` +
             `Register at module load (see built-in-descriptors.ts).`);
@@ -168,20 +226,47 @@ export function getBlockKindDescriptor(kind) {
     return d;
 }
 export function tryGetBlockKindDescriptor(kind) {
-    return registry.get(kind);
+    return registry.getIgnoringActivation(kind);
+}
+/** 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 function isGridKind(kind) {
+    return isGridDescriptor(tryGetBlockKindDescriptor(kind));
+}
+/** {@link isGridKind} for a caller already holding the descriptor. */
+export function isGridDescriptor(descriptor) {
+    return descriptor?.containerContract === 'grid';
+}
+/** 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 function mustHoldChild(kind) {
+    const descriptor = tryGetBlockKindDescriptor(kind);
+    return !!descriptor?.isContainer && descriptor.blockFocus !== 'whole-block';
+}
+/** 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 function countsCells(node) {
+    return 'raw' in node && node.kind === 'table';
 }
 /**
- * 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.
+ * 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 function tableCellCount(node) {
+    return (node.children?.length ?? 0) * metadataOf(node, 'table').columnCount;
+}
+/** A cell index clamped into a table's grid: the one upper bound every cell-space caller uses. */
+export function clampCellIndex(node, cellIdx) {
+    return Math.min(Math.max(cellIdx, 0), Math.max(tableCellCount(node) - 1, 0));
+}
+/**
+ * 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 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);
+    return registry.records().map((r) => r.key);
 }

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

@@ -1,33 +1,35 @@
 /**
  * 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.
+ * both come from these declarations, so registering an opener puts it in both. Paragraph is the
+ * fallback and has no opener; setext headings and tables come out of its continuation scan.
  */
 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. */
+import { type PluginActivation } from './plugin-activation';
+/** Created fresh for each block and read synchronously; never keep it past the call. */
 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). */
+    /** The blank lines above this block, which the paragraph-interrupt rules read (GFM §4.4);
+     *  non-empty means a blank line precedes it. */
     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`. */
+    /** True when the parse was given a whole document, false for one block's bytes alone. It holds
+     *  through nested parses, so a position check also reads `index` and `depth`. */
     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. */
+    /** Container nesting depth, 0 at the root. A container opener parses its body at `depth + 1`;
+     *  past `MAX_NESTING_DEPTH` deeper input becomes 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`).
-     */
+    /** The editor's grammar. A container opener hands it to its body parse, so a kind this
+     *  editor switched off stays off inside a list item or a quote too. */
     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.
+ * What an opener returns for the lines starting at `ctx.index`. `consumed` is a line count, not
+ * a resume position, and must be at least 1: taking no line would spin the parse loop, so the
+ * parser rejects that result.
  */
 export interface BlockOpenerResult {
     node: CstNode;
@@ -42,53 +44,60 @@ export interface BlockOpener {
 }
 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.
+ * Is an opener registered? `registerBlockOpener` throws on a duplicate, so a plugin that may
+ * register twice (hot reload, re-import) checks this first. 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;
+/** Every registered opener in dispatch order, whoever registered it. An editor's own order is its
+ *  `GrammarView.orderedOpeners`. */
+export declare function getOrderedOpeners(): readonly BlockOpener[];
 /**
- * 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.
+ * Global, not per editor, so an unlisted plugin's line still ends a paragraph; a plugin whose
+ * setup threw interrupts nothing. The paragraph parser stops at `---` itself.
  */
 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.
+ * A per-editor view of the global syntax, passed in as `parse(source, { grammar })` and to the
+ * inline scan. The opener dispatch, the setext underline check and every plugin's inline syntax,
+ * widgets, directive names and completers are resolved per editor; the paragraph-interrupt scan
+ * uses the global grammar.
  */
 export interface GrammarView {
     orderedOpeners(): readonly BlockOpener[];
+    /** Whether a `===` or `---` line under paragraph text makes it a heading. */
+    readonly setextHeading: boolean;
+    /** The plugins this editor activated; every plugin-registered entry resolves through it. */
+    readonly activation: PluginActivation;
 }
+export declare function createGrammarView(isEnabled: OpenerEnablement, options?: {
+    setextHeading?: boolean;
+    activation?: PluginActivation;
+}): GrammarView;
+/** The grammar a `parse()` with no editor reads: every opener but a failed plugin's. */
 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. */
+    /** A lazy continuation: an open paragraph absorbs the block starts §4.4 forbids from interrupting. */
     paragraphOpen: boolean;
-    /** Defaults to the global openers, the boundary `lineInterruptsParagraph` also reads. */
-    grammar?: GrammarView;
+    /** The editor's grammar: an opener it left out starts no block here. */
+    grammar: GrammarView;
+    /** The lines `line` sits in (`lines[index]` is `line`), so an opener that needs a later line to
+     *  open, a `$$` block and its closing line, sees it. Without them `line` is read alone. */
+    window?: {
+        lines: ParsedLine[];
+        index: number;
+        end: number;
+    };
 }
 /**
- * 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.
+ * Whether `line` starts a block at the outer level, where cmark-gfm ends a lazy continuation or a
+ * table. A link reference definition never counts, nor indented code under an open paragraph.
  */
 export declare function lineStartsOuterBlock(line: ParsedLine, scan: OuterBlockScan): boolean;
-/** Registry introspection for the invariant guard (G1.10). */
+/** Read by the dev-mode check that warns when two kinds share a priority (G1.10). */
 export declare function listRegisteredOpeners(): {
     kind: AnyBlockKind;
     priority: number;
 }[];
-export declare function __resetBlockOpenersForTests(): void;
-export declare function __removePluginOpenersForTests(): void;