@voithos-labs/aragonite 0.10.3 → 0.10.7

package/dist/schema/inline-construct-policy.d.ts

@@ -1,33 +1,32 @@
 /**
  * Per-inline-kind editing policy: how a construct behaves at its edges, whether emptying it
- * unwraps it, how a split treats its markers, whether preview-inline's reveal addresses them, and
- * what a format chord writes for it. Lives in `schema/` because it is the only directory
- * `tree-operations`, `selection`, `components` and `core/inline` can all reach. Rows are data; the
- * split rebalancer is a function value patched in from the component layer, so this module keeps
- * no import of it.
+ * unwraps it, how a split treats its markers, whether preview-inline may show its markers, and
+ * what a format chord writes for it. The rows are data; the live split and join rewrites are
+ * functions the component layer registers here.
  */
 import { type AnyInlineKind } from '../core/nodes';
 import type { NodeView } from '../core/node-views';
-import type { LinkReferenceResolver } from '../core/inline/link-reference-resolver';
+import type { Reading } from './reading';
+import type { StoredAs } from './stored-as';
 import type { AnyCommandId } from './command-id';
 /** The constructs a format chord addresses: whichever rows below declare a mark. An alias rather
- *  than a union, so a plugin's markable kind needs no edit here — the membership test is the row
- *  lookup, at runtime. */
+ *  than a union, so a plugin's markable kind needs no edit here; membership is the row lookup,
+ *  done at runtime. */
 export type InlineMarkKind = AnyInlineKind;
 /**
- * The vocabulary a format chord needs to write a construct's own delimiters. Whole or absent, so a
- * kind cannot declare itself markable without saying what a mark on it writes.
+ * What a format chord needs in order to write a construct's own delimiters. Present in full or
+ * absent, so a kind cannot call itself markable without saying what a mark on it writes.
  */
 export interface InlineMarkPolicy {
     /** Where the kind sits when one insertion carries several marks: ascending is outermost first,
-     *  and the order is the table's, never the order the chords arrived in. */
+     *  and the order is this table's, never the order the chords arrived in. */
     nestingRank: number;
     /** The bare run that opens and closes the construct. */
     markerBytes: string;
-    /** Wrap `content` for a kind whose delimiters depend on what they enclose — a code span sizes
-     *  its fence past the longest run inside it. Absent means marker, content, marker. */
+    /** Wrap `content` for a kind whose delimiters depend on what they enclose: a code span makes
+     *  its fence longer than the longest run inside it. Absent means marker, content, marker. */
     wrapBytes?: (content: string) => string;
-    /** The command whose press toggles this mark. */
+    /** The command that toggles this mark. */
     command: AnyCommandId;
 }
 export interface InlineConstructPolicy {
@@ -35,57 +34,53 @@ export interface InlineConstructPolicy {
     autoUnwrapOnEmpty: boolean;
     splitBehavior: 'close-and-reopen' | 'plain';
     revealable: boolean;
-    /** Whether the link card is the door to this construct's destination — the only one a mode
-     *  that paints no URL leaves the reader (live-mode.md § 4.6). Absent reads as no: an image's
-     *  destination has its own editor, and an autolink's IS the text on screen. */
+    /** Whether the link card edits this construct's destination, the only way in a mode that hides
+     *  the URL (`docs/design/live-mode.md` § 4.6 The link card). Absent reads as no. */
     cardEditable?: boolean;
     /** Absent for a construct no format chord addresses. */
     mark?: InlineMarkPolicy;
+    /**
+     * How much of the construct is prose, where a trigger such as `#` may open the inline menu.
+     * Absent reads as `'all'`, or `'none'` for an inline widget kind.
+     */
+    prose?: InlineProseExtent;
 }
+export type InlineProseExtent = 'none' | 'content' | 'all';
 export declare function registerInlineConstructPolicy(kind: AnyInlineKind, policy: InlineConstructPolicy): void;
 /** Undefined for a kind with no row: absent means "no live-mode construct behavior at all". */
 export declare function getInlineConstructPolicy(kind: AnyInlineKind): InlineConstructPolicy | undefined;
-/** Whether preview-inline's construct reveal may flip this kind's marker spans. */
+/** Whether the preview-inline mode may show this kind's markers. */
 export declare function isRevealableInlineKind(kind: AnyInlineKind): boolean;
 /** Whether the link card may address this kind's destination. */
 export declare function isCardEditableInlineKind(kind: AnyInlineKind): boolean;
 export declare function listInlineConstructPolicies(): readonly (InlineConstructPolicy & {
     kind: AnyInlineKind;
 })[];
-/** A kind's mark vocabulary, or undefined for one no chord addresses — the membership test the
- *  toggle seams run before writing any delimiter. */
+/** A kind's mark policy, or undefined for a kind no chord addresses. The toggle paths check this
+ *  before writing any delimiter. */
 export declare function getInlineMarkPolicy(kind: AnyInlineKind): InlineMarkPolicy | undefined;
 export interface InlineMark {
     kind: AnyInlineKind;
     mark: InlineMarkPolicy;
 }
-/** Every markable kind, outermost first. Carrying the row rather than the bare kind is what keeps
- *  a caller from mapping a lookup that can miss over a list it built itself. */
+/** Every markable kind, outermost first. Returning the row with the kind saves each caller a
+ *  second lookup that could miss. */
 export declare function listInlineMarks(): readonly InlineMark[];
-/** The mark a command toggles, or null for a command no row claims. */
+/** The mark a command toggles, or null when no row names that command. */
 export declare function inlineMarkForCommand(command: string): InlineMark | null;
-/**
- * The link-reference resolver a rewrite parses with, structurally rather than by naming
- * `editor-keys`' type — that would cycle the editor's context module onto every layer this table
- * serves, the reason `inline-cache` states for the same shape. Registration is process-global and
- * the resolver is per-instance, so it rides the CALL, never the registration.
- */
-export type InlineResolverRef = {
-    current?: LinkReferenceResolver;
-    signature?: string;
-};
 /**
  * The one live-mode split rewrite, consulting each construct's own `splitBehavior`, so
  * `splitNode` needs neither `parseInline` nor a per-kind dispatch. Null declines the rewrite.
+ * Registration is process-wide, so the editor's reading is passed on each call.
  */
-export type LiveSplitRebalancer = (node: NodeView, offset: number, firstRaw: string, secondRaw: string, linkRef: InlineResolverRef | undefined) => {
+export type LiveSplitRebalancer = (node: NodeView, offset: number, firstRaw: string, secondRaw: string, reading: Reading) => {
     firstRaw: string;
     secondRaw: string;
 } | null;
 export declare function registerLiveSplitRebalancer(rebalancer: LiveSplitRebalancer): void;
 export declare function getLiveSplitRebalancer(): LiveSplitRebalancer | undefined;
-/** One side of a join: the block bytes it contributed and the offset they were cut at — a whole
- *  block's content end for a merge, the selection endpoint for a range delete. */
+/** One side of a join: the block it contributed bytes from and the offset they were cut at. A
+ *  merge cuts at the end of the block's content, a range delete at the selection endpoint. */
 export interface JoinEndpoint {
     node: NodeView;
     offset: number;
@@ -96,20 +91,15 @@ export interface JoinSeam {
     seam: number;
     start: JoinEndpoint;
     end: JoinEndpoint;
-    /** Per-instance, so it rides the call: a reference form parsed without it reads as brackets,
-     *  and the seam would step around a construct the reader saw as a link. */
-    linkRef: InlineResolverRef | undefined;
-    /** Text the caller will splice at the seam once the cleanup returns. Absent for a pure delete;
-     *  present, it is part of the bytes the cleanup has to verify, since a typed run changes the
-     *  flanking a kept delimiter pairs against. */
-    typed?: string;
-    /** The container prefix the surviving side is installed under (`- `, `> `). Absent where the
-     *  surface paints none. A candidate is read back through it: an item's body starting with a
-     *  space reloads as a WIDER marker than the live tree holds. */
-    ambientPrefix?: string;
+    /** Text the caller will insert at the join after the cleanup, `''` for a plain delete. The
+     *  cleanup checks it too, since typed text changes what a surviving delimiter pairs against. */
+    typed: string;
+    /** Where the joined bytes will be stored, with the editor's reading: the cleanup reads each
+     *  candidate back there, a list item's marker line or a cell's text included. */
+    store: StoredAs;
 }
-/** The bytes a cleanup wrote and where the two sides now meet in them: dropping a run on the
- *  first side's half moves the seam the caret lands on. */
+/** The bytes a cleanup wrote and where the two sides now meet in them: dropping characters from
+ *  the first side moves the point the caret lands on. */
 export interface CleanedJoin {
     raw: string;
     seam: number;
@@ -121,11 +111,8 @@ export interface CleanedJoin {
 export type LiveJoinSeamCleaner = (join: JoinSeam) => CleanedJoin | null;
 export declare function registerLiveJoinSeamCleaner(cleaner: LiveJoinSeamCleaner): void;
 export declare function getLiveJoinSeamCleaner(): LiveJoinSeamCleaner | undefined;
-/** Test-only. Drops every plugin-registered row; built-in rows and the rebalancer survive,
- *  being built-in registrations. */
-export declare function __resetInlineConstructPoliciesForTests(): void;
-/** Test-only, and separate on purpose: only a suite testing the SLOT wants it emptied, and the
- *  registry's own reset must not do it as a side effect. */
+/** Test-only, and separate on purpose: only a suite testing this one function wants it cleared,
+ *  and the registry's own reset must not clear it as a side effect. */
 export declare function __resetLiveSplitRebalancerForTests(): void;
-/** Test-only, {@link __resetLiveSplitRebalancerForTests}'s twin for the join slot. */
+/** Test-only, the join cleaner's counterpart to {@link __resetLiveSplitRebalancerForTests}. */
 export declare function __resetLiveJoinSeamCleanerForTests(): void;

package/dist/schema/inline-construct-policy.js

@@ -1,66 +1,72 @@
 /**
  * Per-inline-kind editing policy: how a construct behaves at its edges, whether emptying it
- * unwraps it, how a split treats its markers, whether preview-inline's reveal addresses them, and
- * what a format chord writes for it. Lives in `schema/` because it is the only directory
- * `tree-operations`, `selection`, `components` and `core/inline` can all reach. Rows are data; the
- * split rebalancer is a function value patched in from the component layer, so this module keeps
- * no import of it.
+ * unwraps it, how a split treats its markers, whether preview-inline may show its markers, and
+ * what a format chord writes for it. The rows are data; the live split and join rewrites are
+ * functions the component layer registers here.
  */
 import { isBuiltinInlineKind } from '../core/nodes';
 import { isBuiltinCommandId } from './commands';
-import { deletePluginEntries, registerOnce } from './register-once';
-const policies = new Map();
+import { registerOnce } from './register-once';
+import { everyInstalledPlugin } from './plugin-activation';
+import { createInlineKindRegistry } from './plugin-registry';
+// Read with no editor at hand: a row matters only for a node of its kind, and only an editor
+// that activated the kind's plugin parses one, so the rows answer for every installed plugin.
+const policies = createInlineKindRegistry({
+    label: 'registerInlineConstructPolicy',
+    isBuiltin: isBuiltinInlineKind
+});
+const policyOf = (kind) => policies.get(kind, everyInstalledPlugin);
 export function registerInlineConstructPolicy(kind, policy) {
     assertMarkCommandMintable(kind, policy.mark);
     assertCardImpliesRevealable(kind, policy);
-    registerOnce(policies.has(kind), () => policies.set(kind, policy), `registerInlineConstructPolicy: "${kind}" is already registered. Policies are register-once.`);
+    policies.register(kind, policy, `registerInlineConstructPolicy: "${kind}" is already registered. Policies are register-once.`);
 }
-/** Ahead of the register-once valve, so it rejects in every env: the valve forgives a duplicate
- *  row, never an invalid one. The rule and why it matters are G1.31's, which stays the belt. */
+/** Runs before the register-once check, so it throws in every environment: that check forgives a
+ *  duplicate row, never an invalid one. */
 function assertMarkCommandMintable(kind, mark) {
     if (!mark || isBuiltinInlineKind(kind) || !isBuiltinCommandId(mark.command))
         return;
-    throw new Error(`registerInlineConstructPolicy: "${kind}" claims built-in command "${mark.command}" for its mark — that id already has a built-in meaning; mint a plugin command id for the mark`);
+    throw new Error(`registerInlineConstructPolicy: "${kind}" claims built-in command "${mark.command}" for its mark; that id already has a built-in meaning; create a plugin command id for the mark`);
 }
-/** The card's open chain admits only revealable kinds (`link-at-point.ts`), so a row claiming the
- *  card without the reveal declares a door nothing can walk through. Stated here rather than left
- *  to a silent no-op at the click. */
+/** The card opens only on revealable kinds (`link-at-point.ts`), so a row asking for it without
+ *  `revealable` throws here rather than failing silently at the click. */
 function assertCardImpliesRevealable(kind, policy) {
     if (!policy.cardEditable || policy.revealable)
         return;
-    throw new Error(`registerInlineConstructPolicy: "${kind}" declares cardEditable without revealable — the card's open chain reaches only revealable kinds, so the door would never open`);
+    throw new Error(`registerInlineConstructPolicy: "${kind}" declares cardEditable without revealable; the card's open chain reaches only revealable kinds, so the entry point would never open`);
 }
 /** Undefined for a kind with no row: absent means "no live-mode construct behavior at all". */
 export function getInlineConstructPolicy(kind) {
-    return policies.get(kind);
+    return policyOf(kind);
 }
-/** Whether preview-inline's construct reveal may flip this kind's marker spans. */
+/** Whether the preview-inline mode may show this kind's markers. */
 export function isRevealableInlineKind(kind) {
-    return policies.get(kind)?.revealable === true;
+    return policyOf(kind)?.revealable === true;
 }
 /** Whether the link card may address this kind's destination. */
 export function isCardEditableInlineKind(kind) {
-    return policies.get(kind)?.cardEditable === true;
+    return policyOf(kind)?.cardEditable === true;
 }
 export function listInlineConstructPolicies() {
-    return [...policies].map(([kind, policy]) => ({ kind, ...policy }));
+    return policies.entries(everyInstalledPlugin).map(([kind, policy]) => ({ kind, ...policy }));
 }
 // ── The mark vocabulary ─────────────────────────────────────────────────────
-/** A kind's mark vocabulary, or undefined for one no chord addresses — the membership test the
- *  toggle seams run before writing any delimiter. */
+/** A kind's mark policy, or undefined for a kind no chord addresses. The toggle paths check this
+ *  before writing any delimiter. */
 export function getInlineMarkPolicy(kind) {
-    return policies.get(kind)?.mark;
+    return policyOf(kind)?.mark;
 }
-/** Every markable kind, outermost first. Carrying the row rather than the bare kind is what keeps
- *  a caller from mapping a lookup that can miss over a list it built itself. */
+/** Every markable kind, outermost first. Returning the row with the kind saves each caller a
+ *  second lookup that could miss. */
 export function listInlineMarks() {
     const marks = [];
-    for (const [kind, policy] of policies)
+    for (const [kind, policy] of policies.entries(everyInstalledPlugin)) {
         if (policy.mark)
             marks.push({ kind, mark: policy.mark });
+    }
     return marks.sort((a, b) => a.mark.nestingRank - b.mark.nestingRank);
 }
-/** The mark a command toggles, or null for a command no row claims. */
+/** The mark a command toggles, or null when no row names that command. */
 export function inlineMarkForCommand(command) {
     return listInlineMarks().find((entry) => entry.mark.command === command) ?? null;
 }
@@ -80,17 +86,12 @@ export function registerLiveJoinSeamCleaner(cleaner) {
 export function getLiveJoinSeamCleaner() {
     return joinSeamCleaner;
 }
-/** Test-only. Drops every plugin-registered row; built-in rows and the rebalancer survive,
- *  being built-in registrations. */
-export function __resetInlineConstructPoliciesForTests() {
-    deletePluginEntries(policies, isBuiltinInlineKind);
-}
-/** Test-only, and separate on purpose: only a suite testing the SLOT wants it emptied, and the
- *  registry's own reset must not do it as a side effect. */
+/** Test-only, and separate on purpose: only a suite testing this one function wants it cleared,
+ *  and the registry's own reset must not clear it as a side effect. */
 export function __resetLiveSplitRebalancerForTests() {
     splitRebalancer = undefined;
 }
-/** Test-only, {@link __resetLiveSplitRebalancerForTests}'s twin for the join slot. */
+/** Test-only, the join cleaner's counterpart to {@link __resetLiveSplitRebalancerForTests}. */
 export function __resetLiveJoinSeamCleanerForTests() {
     joinSeamCleaner = undefined;
 }

package/dist/schema/insert-catalogue.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The blocks a menu can insert: the built-ins, then the entries plugins register, each with the
+ * Markdown it inserts. The right-click flyout, `EditorInstance.getInsertCatalogue()` and a plugin's
+ * `editor.insertCatalogue` all read this one list, so no two of them can disagree.
+ */
+import { type MenuIconName } from '../menu-icons';
+import type { PluginActivation } from './plugin-activation';
+export interface InsertEntry {
+    readonly id: string;
+    readonly label: string;
+    readonly icon: MenuIconName;
+    /** Other words a filter should find the entry by: `todo` for "To-do list". */
+    readonly keywords: readonly string[];
+    /** Handed to the paste path as is, the way `insertMarkdown` takes it. */
+    readonly markdown: string;
+    /** The Markdown for the word typed after the entry (`/table 3x4`; the word is never empty),
+     *  and the dim text saying how it was read. Absent: the entry takes no argument. */
+    readonly withArgument?: (argument: string) => {
+        markdown: string;
+        detail?: string;
+    };
+}
+/**
+ * Call from a plugin's `setup`: the entry is listed after the built-ins, and only in editors that
+ * activated that plugin. Throws on a taken id or an icon name the menu cannot draw.
+ */
+export declare function registerInsertEntry(entry: InsertEntry): void;
+/** Every entry one editor lists: the built-ins, then each plugin entry `activation` resolves. A
+ *  fresh frozen list per call. */
+export declare function insertCatalogue(activation: PluginActivation): readonly InsertEntry[];

package/dist/schema/insert-catalogue.js

@@ -0,0 +1,95 @@
+/**
+ * The blocks a menu can insert: the built-ins, then the entries plugins register, each with the
+ * Markdown it inserts. The right-click flyout, `EditorInstance.getInsertCatalogue()` and a plugin's
+ * `editor.insertCatalogue` all read this one list, so no two of them can disagree.
+ */
+import { isMenuIconName } from '../menu-icons';
+import { legalFenceInfo } from './fenced-code-raw';
+import { createPluginRegistry } from './plugin-registry';
+const DEFAULT_TABLE = { columns: 2, rows: 2 };
+const MAX_COLUMNS = 20;
+const MAX_ROWS = 100;
+const TABLE_HINT = 'columns×rows, like 3x4';
+// A heading is not here: it is text turned into a heading, which the selection toolbar offers.
+const BUILT_IN = [
+    entry('bullet', 'Bulleted list', 'list', ['bullet', 'unordered', 'ul', 'list'], '- '),
+    entry('numbered', 'Numbered list', 'list-ordered', ['number', 'ordered', 'ol', 'list'], '1. '),
+    entry('todo', 'To-do list', 'square-check', ['todo', 'td', 'task', 'checkbox', 'list'], '- [ ] '),
+    entry('quote', 'Quote', 'text-quote', ['blockquote', 'citation'], '> '),
+    entry('divider', 'Divider', 'minus', ['rule', 'separator', 'line'], '---\n'),
+    entry('code', 'Code block', 'code', ['fence', 'pre', 'snippet'], codeFence(''), codeArgument),
+    entry('table', 'Table', 'table', ['grid'], tableMarkdown(DEFAULT_TABLE), tableArgument)
+];
+const BUILT_IN_IDS = new Set(BUILT_IN.map((e) => e.id));
+// Listed in registration order.
+const fromPlugins = createPluginRegistry({
+    label: 'registerInsertEntry',
+    isBuiltin: () => false
+});
+/**
+ * Call from a plugin's `setup`: the entry is listed after the built-ins, and only in editors that
+ * activated that plugin. Throws on a taken id or an icon name the menu cannot draw.
+ */
+export function registerInsertEntry(entry) {
+    if (!isMenuIconName(entry.icon)) {
+        throw new Error(`registerInsertEntry: '${entry.id}' names icon '${entry.icon}', which the menu cannot draw`);
+    }
+    if (BUILT_IN_IDS.has(entry.id)) {
+        throw new Error(`registerInsertEntry: '${entry.id}' is a built-in insert entry`);
+    }
+    fromPlugins.register(entry.id, freezeEntry(entry), `registerInsertEntry: an insert entry '${entry.id}' is already registered`);
+}
+/** Every entry one editor lists: the built-ins, then each plugin entry `activation` resolves. A
+ *  fresh frozen list per call. */
+export function insertCatalogue(activation) {
+    const listed = fromPlugins.entries(activation).map(([, entry]) => entry);
+    return Object.freeze([...BUILT_IN, ...listed]);
+}
+// ── Internal ─────────────────────────────────────────────────────────────────
+function entry(id, label, icon, keywords, markdown, withArgument) {
+    return freezeEntry({
+        id,
+        label,
+        icon,
+        keywords,
+        markdown,
+        ...(withArgument && { withArgument })
+    });
+}
+function freezeEntry(entry) {
+    return Object.freeze({ ...entry, keywords: Object.freeze([...entry.keywords]) });
+}
+// ── Arguments ────────────────────────────────────────────────────────────────
+function codeFence(info) {
+    return `\`\`\`${info}\n\n\`\`\`\n`;
+}
+// The code block's own info-string rule, so the fence reads as if the language were typed on it.
+function codeArgument(language) {
+    const info = legalFenceInfo(language, '`');
+    return { markdown: codeFence(info), detail: info || 'no language' };
+}
+/** A malformed size inserts the default table and says how to write one, so Enter always inserts. */
+function tableArgument(argument) {
+    const size = parseTableSize(argument);
+    if (!size) {
+        const hint = `${sizeLabel(DEFAULT_TABLE)} · ${TABLE_HINT}`;
+        return { markdown: tableMarkdown(DEFAULT_TABLE), detail: hint };
+    }
+    return { markdown: tableMarkdown(size), detail: sizeLabel(size) };
+}
+/** `3x4` (or `3X4`, `3×4`) is three columns and four rows; null for anything else. */
+function parseTableSize(argument) {
+    const match = /^(\d+)[xX×](\d+)$/.exec(argument);
+    if (!match)
+        return null;
+    const size = { columns: Number(match[1]), rows: Number(match[2]) };
+    const fits = size.columns >= 1 && size.columns <= MAX_COLUMNS && size.rows >= 2 && size.rows <= MAX_ROWS;
+    return fits ? size : null;
+}
+function tableMarkdown({ columns, rows }) {
+    const line = (cell) => `|${` ${cell} |`.repeat(columns)}\n`;
+    return line('Column') + line('---') + line('').repeat(rows - 1);
+}
+function sizeLabel({ columns, rows }) {
+    return `${columns}×${rows}`;
+}

package/dist/schema/keybinding-overrides.d.ts

@@ -1,7 +1,7 @@
 /**
  * Per-instance keybinding overrides: the public override-entry type, the normalized lookup it
- * compiles into, and the primitives the command resolver composes with the built-in tables.
- * Schema leaf — the map reaches the resolver as an argument, never through a context read.
+ * compiles into, and the primitives the command resolver composes with the built-in tables. The
+ * map reaches the resolver as an argument, never through a context read.
  */
 import type { AnyBlockKind } from '../core/nodes';
 import { type KeyBinding } from './keybindings';
@@ -10,17 +10,15 @@ import type { AnyCommandId } from './command-id';
 export interface KeybindingOverride {
     /** Chord string in the public format (Mod/Alt/Shift + key). See keybindings.ts. */
     chord: string;
-    /** A command to bind (built-in or minted plugin id), or `null` to disable the chord. A disable
-     *  removes the binding and drops the chord from `reservedChords()`, but the press is still
-     *  consumed inside the editor rather than falling through to the browser's own default. */
+    /** A command to bind (built-in or plugin id), or `null` to disable the chord. A disabled chord
+     *  leaves `reservedChords()` but is still consumed, so the browser's own default never runs. */
     command: AnyCommandId | null;
-    /** Target one block kind's keymap — built-in, or a plugin kind via its exported
-     *  kind constant (branded; a raw string literal won't typecheck). Omit for the
-     *  editor-global scope. */
+    /** One block kind's keymap, a plugin kind named by its exported (branded) constant. Omit for
+     *  the editor-global scope. */
     kind?: AnyBlockKind;
     /**
-     * Static argument baked into the binding. `unknown` for coherence with `KeyBinding.arg`: a
-     * minted command's non-number arg survives normalization, and the handler type-guards it.
+     * Static argument baked into the binding. `unknown` to match `KeyBinding.arg`: a plugin
+     * command's non-number arg survives normalization, and the handler type-guards it.
      */
     arg?: unknown;
 }
@@ -35,5 +33,5 @@ export interface KeybindingOverrideMap {
 export declare function normalizeKeybindingOverrides(overrides: KeybindingOverride[] | undefined): KeybindingOverrideMap;
 /** Look up a single override for a (scope, chord). undefined when no entry exists. */
 export declare function lookupOverride(overrides: KeybindingOverrideMap | undefined, scope: 'global' | AnyBlockKind, chord: string): OverrideValue | undefined;
-/** Resolve one tier: a binding (use it), null (decided unbound — disabled), undefined (no decision). */
+/** Resolve one override scope: a binding (use it), null (disabled), undefined (no entry). */
 export declare function overrideDecision(value: OverrideValue | undefined): KeyBinding | null | undefined;

package/dist/schema/keybinding-overrides.js

@@ -35,7 +35,7 @@ export function lookupOverride(overrides, scope, chord) {
         return overrides.global.get(chord);
     return overrides.byKind.get(scope)?.get(chord);
 }
-/** Resolve one tier: a binding (use it), null (decided unbound — disabled), undefined (no decision). */
+/** Resolve one override scope: a binding (use it), null (disabled), undefined (no entry). */
 export function overrideDecision(value) {
     if (value === undefined)
         return undefined;

package/dist/schema/keybindings.d.ts

@@ -8,8 +8,8 @@ export interface KeyBinding {
     chord: string;
     command: AnyCommandId;
     /**
-     * Static argument baked into the binding, widened so a minted command travels the same
-     * channel. It reaches the handler as `unknown`, which must type-guard before use.
+     * Static argument baked into the binding, widened so a plugin command's argument travels the
+     * same channel. It reaches the handler as `unknown`, which must type-guard before use.
      */
     arg?: unknown;
 }
@@ -21,14 +21,22 @@ export declare const BARE_MODIFIER_KEYS: readonly string[];
 /** A `key` value that is one typed character: one code point, so an astral glyph's two
  *  UTF-16 units still count as a single keystroke. */
 export declare function isCharacterKey(key: string): boolean;
-export declare function eventToChord(e: KeyboardEvent): string | null;
+/** The fields of a keydown a chord is read from; a `KeyboardEvent` is one. */
+export type ChordKeys = Pick<KeyboardEvent, 'key' | 'ctrlKey' | 'metaKey' | 'altKey' | 'shiftKey'>;
+export declare function eventToChord(e: ChordKeys): string | null;
+/** Mod+A, CapsLock or not (CapsLock uppercases the key without a Shift). Select-all is a browser
+ *  chord rather than a keymap command, so every block asks this one predicate. */
+export declare function isSelectAllChord(e: ChordKeys): boolean;
+/** Whether a key ends a run of select-all keypresses: any chord but Mod+A, not a held modifier. */
+export declare function endsSelectAllRun(e: ChordKeys): boolean;
 export declare function normalizeChord(chord: string): string;
+/** Whether a chord is well-formed: Mod/Alt/Shift modifiers and a non-empty key. */
+export declare function isChordWellFormed(chord: string): boolean;
 /**
- * The well-formedness the strict ingestion paths gate on, so a mis-typed `'Ctrl+B'` can't
- * collapse to a bare `'B'` that fires on every keypress. Pure: the caller decides whether to
- * warn, throw, or report.
+ * Validate then normalize a chord a registration declares, throwing on a malformed one, so a
+ * mis-typed `'Ctrl+B'` never collapses to a bare `'B'` that fires on every keypress.
  */
-export declare function isChordWellFormed(chord: string): boolean;
+export declare function registeredChord(chord: string, entry: string): string;
 /**
  * Validate then normalize a consumer-supplied chord; null (dev-warned) when malformed, guarding
  * the trap where `'Ctrl+B'` drops the unrecognized `Ctrl` and collapses to bare `'B'`.

package/dist/schema/keybindings.js

@@ -33,6 +33,15 @@ export function eventToChord(e) {
         mods.push('Shift');
     return [...mods, normalizeKey(e.key)].join('+');
 }
+/** Mod+A, CapsLock or not (CapsLock uppercases the key without a Shift). Select-all is a browser
+ *  chord rather than a keymap command, so every block asks this one predicate. */
+export function isSelectAllChord(e) {
+    return eventToChord(e) === 'Mod+A';
+}
+/** Whether a key ends a run of select-all keypresses: any chord but Mod+A, not a held modifier. */
+export function endsSelectAllRun(e) {
+    return eventToChord(e) !== null && !isSelectAllChord(e);
+}
 export function normalizeChord(chord) {
     const parts = chord.split('+');
     const key = parts.pop() ?? '';
@@ -41,10 +50,7 @@ export function normalizeChord(chord) {
     return [...mods, normalizeKey(key)].join('+');
 }
 const VALID_MODIFIERS = new Set(MOD_ORDER);
-/**
- * Why a chord is malformed, or null when it is well-formed. Shared core of the strict paths;
- * keeping the reason lets `normalizeChordStrict` name it in the warn.
- */
+/** Why a chord is malformed, or null when it's well-formed; a registration's error names it. */
 function chordDefect(chord) {
     const parts = chord.split('+');
     const key = parts.pop() ?? '';
@@ -53,14 +59,20 @@ function chordDefect(chord) {
     const bad = parts.find((mod) => !VALID_MODIFIERS.has(mod));
     return bad === undefined ? null : `unrecognized modifier "${bad}" (use Mod/Alt/Shift)`;
 }
-/**
- * The well-formedness the strict ingestion paths gate on, so a mis-typed `'Ctrl+B'` can't
- * collapse to a bare `'B'` that fires on every keypress. Pure: the caller decides whether to
- * warn, throw, or report.
- */
+/** Whether a chord is well-formed: Mod/Alt/Shift modifiers and a non-empty key. */
 export function isChordWellFormed(chord) {
     return chordDefect(chord) === null;
 }
+/**
+ * Validate then normalize a chord a registration declares, throwing on a malformed one, so a
+ * mis-typed `'Ctrl+B'` never collapses to a bare `'B'` that fires on every keypress.
+ */
+export function registeredChord(chord, entry) {
+    const defect = chordDefect(chord);
+    if (defect !== null)
+        throw new Error(`${entry}: chord "${chord}" is malformed: ${defect}`);
+    return normalizeChord(chord);
+}
 /**
  * Validate then normalize a consumer-supplied chord; null (dev-warned) when malformed, guarding
  * the trap where `'Ctrl+B'` drops the unrecognized `Ctrl` and collapses to bare `'B'`.

package/dist/schema/merge-rules.d.ts

@@ -1,7 +1,7 @@
 /**
- * Merge eligibility and target resolution for Backspace-at-start — the role-pair rules and the
- * target-finding walker; per-kind `MergeRole` assignment lives on `BlockKindDescriptor`.
- * See docs/design/editor.md — Merge eligibility: roles, not pairs.
+ * Merge eligibility and target resolution for Backspace at the start of a block: the role-pair
+ * rules and the walk that finds the target. Each kind's `MergeRole` is declared on
+ * `BlockKindDescriptor` (`docs/design/editor.md` § Merge eligibility: roles, not pairs).
  */
 import type { CstNode } from '../core/nodes';
 import { type MergeRole } from './block-kind-descriptor';
@@ -17,10 +17,8 @@ export interface MergeTarget {
     path: number[];
 }
 /**
- * Descend into the last child until landing on a prose / prose-absorber leaf; null on a
- * not-mergeable leaf or an empty container. A collapsed container clamps its body out of view,
- * so the walk descends to the chrome leaf (child 0) instead — its not-mergeable role turns the
- * merge into the caller's focus-move fallback rather than a hidden-body write.
+ * Descend through last children to a prose or prose-absorber leaf; null on a not-mergeable leaf or
+ * an empty container. A collapsed container stops at its title row, which refuses the merge.
  */
 export declare function walkToDeepestMergeLeaf(node: CstNode, path: number[]): MergeTarget | null;
 /** The leaf that receives text merged into `prev`; null means the caller moves focus instead. */

package/dist/schema/merge-rules.js

@@ -1,10 +1,10 @@
 /**
- * Merge eligibility and target resolution for Backspace-at-start — the role-pair rules and the
- * target-finding walker; per-kind `MergeRole` assignment lives on `BlockKindDescriptor`.
- * See docs/design/editor.md — Merge eligibility: roles, not pairs.
+ * Merge eligibility and target resolution for Backspace at the start of a block: the role-pair
+ * rules and the walk that finds the target. Each kind's `MergeRole` is declared on
+ * `BlockKindDescriptor` (`docs/design/editor.md` § Merge eligibility: roles, not pairs).
  */
 import { getBlockKindDescriptor } from './block-kind-descriptor';
-import { isCollapsedContainer } from './reserved-chrome';
+import { caretChildCount } from './reserved-chrome';
 // ── Merge Eligibility ───────────────────────────────────────────────────────
 /** Can `currKind` merge into `prevKind` on Backspace? Derived from role pairs, never kinds. */
 export function isMergeEligible(prevKind, currKind) {
@@ -24,10 +24,8 @@ export function getMergeRole(kind) {
     return getBlockKindDescriptor(kind).mergeRole;
 }
 /**
- * Descend into the last child until landing on a prose / prose-absorber leaf; null on a
- * not-mergeable leaf or an empty container. A collapsed container clamps its body out of view,
- * so the walk descends to the chrome leaf (child 0) instead — its not-mergeable role turns the
- * merge into the caller's focus-move fallback rather than a hidden-body write.
+ * Descend through last children to a prose or prose-absorber leaf; null on a not-mergeable leaf or
+ * an empty container. A collapsed container stops at its title row, which refuses the merge.
  */
 export function walkToDeepestMergeLeaf(node, path) {
     const role = getMergeRole(node.kind);
@@ -37,7 +35,7 @@ export function walkToDeepestMergeLeaf(node, path) {
     if (!node.children || node.children.length === 0) {
         return null;
     }
-    const nextIndex = isCollapsedContainer(node) ? 0 : node.children.length - 1;
+    const nextIndex = caretChildCount(node) - 1;
     return walkToDeepestMergeLeaf(node.children[nextIndex], [...path, nextIndex]);
 }
 /** The leaf that receives text merged into `prev`; null means the caller moves focus instead. */