@voithos-labs/aragonite 0.10.1

package/dist/schema/fenced-code-raw.js

@@ -0,0 +1,220 @@
+/**
+ * The fencedCode raw-write rule, declared on the kind as `normalizeRawWrite` and applied at every
+ * write sink. RESTORE re-appends a closer a truncating write dropped and DROP removes one it
+ * stranded, ESCALATE grows both runs past a body line that would read as the closer, SANITIZE
+ * drops backticks from a backtick fence's info string (CommonMark §4.5) — all off the block's OWN
+ * fence shape, which is why the pass takes a node. An authored open fence is exempt.
+ */
+import { metadataOf } from '../core/nodes';
+import { trailingLineEnding, trimTrailingLineEnding } from '../core/lines';
+import { escalatedFenceLength, matchFenceClose, matchFenceOpen } from '../core/parsers/fence-syntax';
+// ── Public API ──────────────────────────────────────────────────────────────
+export function fenceShapeOf(node) {
+    const meta = metadataOf(node, 'fencedCode');
+    return { marker: meta.fenceMarker, length: meta.fenceLength, closed: meta.closed };
+}
+export function reconcileFenceWrite(input) {
+    const { fence, mode } = input;
+    if (!fence.closed && mode === 'authored')
+        return { display: input.display, caret: input.caret };
+    return escalateFenceRuns({ ...input, ...sanitizeInfoString(input) });
+}
+/**
+ * A whole fencedCode `raw` made legal — the kind's `normalizeRawWrite`. Literal by
+ * construction: a sink reaching a node's bytes without its surface is never the author
+ * typing the block's own syntax. The fence lines reconcile first, so ESCALATE measures a
+ * body that ends where the closer does.
+ */
+export function normalizeFencedRaw(raw, node) {
+    const fence = fenceShapeOf(node);
+    const written = reconcileFenceWrite({
+        display: reconcileFenceLines(trimTrailingLineEnding(raw), fence, trailingLineEnding(node.raw)),
+        caret: 0,
+        fence,
+        mode: 'literal'
+    });
+    return written.display + trailingLineEnding(raw);
+}
+/**
+ * The bytes with `info` written onto the opening fence line. Only that span moves, so the
+ * indent, both marker runs, the body and the closer come through byte-identical. Null when
+ * line 0 does not read as this block's opener at all.
+ */
+export function writeFenceInfo(display, info, fence) {
+    const lineEnd = firstLineEnd(display);
+    const line = display.slice(0, lineEnd);
+    const opener = splitOpener(line, fence);
+    if (!opener)
+        return null;
+    // A CRLF separator's `\r` sits inside the line; the info span ends before it.
+    const infoEnd = lineEnd - (line.endsWith('\r') ? 1 : 0);
+    return display.slice(0, opener.runEnd) + legalInfo(info, fence) + display.slice(infoEnd);
+}
+// ── Internal ────────────────────────────────────────────────────────────────
+/**
+ * What the info span may hold: one line, no backtick under a backtick fence (CommonMark §4.5),
+ * and no leading run of the fence's own marker, which lengthens the fence instead — `~~~` + `~x`
+ * reparses as a four-tilde run its own closer no longer closes. Dropped rather than declined,
+ * the rule the typed and pasted routes already share.
+ */
+function legalInfo(info, fence) {
+    const oneLine = info.replace(/[\r\n]/g, '');
+    const kept = fence.marker === '`' ? oneLine.replaceAll('`', '') : oneLine;
+    let start = 0;
+    while (kept[start] === fence.marker)
+        start++;
+    return kept.slice(start);
+}
+/**
+ * Split by the block's OWN run length, not by re-scanning the written line: a backtick
+ * typed at the head of the info string must read as info, not as a longer run.
+ */
+function splitOpener(line, fence) {
+    const indent = /^ {0,3}/.exec(line)[0];
+    const runEnd = indent.length + fence.length;
+    if (line.slice(indent.length, runEnd) !== fence.marker.repeat(fence.length))
+        return null;
+    return { indent, info: line.slice(runEnd), runEnd };
+}
+/**
+ * The block's fence lines against a write that took one of them — an unclosed fence absorbs every
+ * block below it at the next parse, from either half. With the block's own opener still at line 0
+ * a missing closer comes back; without it a surviving closer is machinery the write stranded and
+ * goes. The arms split on {@link ownOpener}, so exactly one can fire.
+ */
+function reconcileFenceLines(display, fence, blockEnding) {
+    if (!fence.closed)
+        return display;
+    const lines = display.split('\n');
+    const opener = ownOpener(lines, fence);
+    const reconciled = opener
+        ? restoredCloser(lines, fence, opener, blockEnding)
+        : droppedStrandedCloser(lines, fence);
+    return reconciled ?? display;
+}
+/**
+ * Line 0 read as the block's OWN opener: its exact run, and info that is not a longer run. A
+ * write's only line reading as this fence's CLOSER is not it — an opener never doubles as one,
+ * and no metadata claims a block to size a fence to.
+ */
+function ownOpener(lines, fence) {
+    const opener = splitOpener(lines[0], fence);
+    if (!opener || opener.info.startsWith(fence.marker))
+        return null;
+    if (lines.length === 1 && matchFenceClose(lines[0], fence.marker, fence.length))
+        return null;
+    return opener;
+}
+/**
+ * The closer a truncating write dropped, re-appended, or null when one is still there. The ending
+ * is the BLOCK's, not the written slice's, which may be unterminated (G4.20).
+ */
+function restoredCloser(lines, fence, opener, blockEnding) {
+    if (lastCloserIndex(lines, fence) !== -1)
+        return null;
+    return lines.join('\n') + blockEnding + opener.indent + fence.marker.repeat(fence.length);
+}
+/**
+ * The closer a write left behind after taking the block's own opener — machinery no metadata
+ * claims, removed rather than kept, since as text it re-opens a fence over the live siblings
+ * below. Null when there is none, or when an opener above could CLOSE on the run:
+ * same marker, run no longer than the closer's — a foreign-marker or longer-run open line is
+ * body text the run never terminated.
+ */
+function droppedStrandedCloser(lines, fence) {
+    const closer = lastCloserIndex(lines, fence, 0);
+    if (closer === -1)
+        return null;
+    const run = /^ {0,3}([`~]+)/.exec(lines[closer])[1].length;
+    const claimed = (line) => {
+        const open = matchFenceOpen(line);
+        return open !== null && open.marker === fence.marker && open.length <= run;
+    };
+    if (lines.slice(0, closer).some(claimed))
+        return null;
+    return withoutLine(lines, closer);
+}
+/** Splitting on `\n` leaves a CRLF separator's `\r` above; dropping the last line orphans it. */
+function withoutLine(lines, index) {
+    const kept = lines.slice(0, index).concat(lines.slice(index + 1));
+    if (index === lines.length - 1 && kept.length > 0) {
+        kept[kept.length - 1] = kept[kept.length - 1].replace(/\r$/, '');
+    }
+    return kept.join('\n');
+}
+function sanitizeInfoString(input) {
+    const { display, caret, fence } = input;
+    if (fence.marker !== '`')
+        return { display, caret };
+    const lineEnd = firstLineEnd(display);
+    const opener = splitOpener(display.slice(0, lineEnd), fence);
+    if (!opener || !opener.info.includes('`'))
+        return { display, caret };
+    const kept = opener.info.replaceAll('`', '');
+    const dropped = countDroppedBefore(opener.info, opener.runEnd, caret);
+    return {
+        display: opener.indent + fence.marker.repeat(fence.length) + kept + display.slice(lineEnd),
+        caret: caret - dropped
+    };
+}
+/** Backticks removed from the info string that sat before the caret. */
+function countDroppedBefore(info, infoStart, caret) {
+    let dropped = 0;
+    for (let i = 0; i < info.length && infoStart + i < caret; i++) {
+        if (info[i] === '`')
+            dropped++;
+    }
+    return dropped;
+}
+function escalateFenceRuns(input) {
+    const { display, caret, fence } = input;
+    const lines = display.split('\n');
+    const opener = splitOpener(lines[0], fence);
+    if (!opener || lines.length < 2)
+        return { display, caret };
+    // An open fence has no closer line, so a literal write measures everything below
+    // the opener; a closed one measures only what sits above its own closer.
+    const closerIndex = fence.closed ? lastCloserIndex(lines, fence) : -1;
+    if (fence.closed && closerIndex < 1)
+        return { display, caret };
+    const bodyEnd = closerIndex === -1 ? lines.length : closerIndex;
+    const body = lines.slice(1, bodyEnd).join('\n');
+    const grown = escalatedFenceLength(body, fence.marker, fence.length);
+    const delta = grown - fence.length;
+    if (delta === 0)
+        return { display, caret };
+    const run = fence.marker.repeat(grown);
+    lines[0] = opener.indent + run + opener.info;
+    let closerRunStart = -1;
+    if (closerIndex !== -1) {
+        const closerIndent = /^ {0,3}/.exec(lines[closerIndex])[0];
+        const tail = lines[closerIndex].slice(closerIndent.length).replace(/^[`~]+/, '');
+        closerRunStart = lineStartOffset(display, closerIndex) + closerIndent.length;
+        lines[closerIndex] = closerIndent + run + tail;
+    }
+    // The run grows in place, so a caret past an insertion point moves with it.
+    let moved = caret;
+    if (caret > opener.runEnd)
+        moved += delta;
+    if (closerRunStart !== -1 && caret > closerRunStart)
+        moved += delta;
+    return { display: lines.join('\n'), caret: moved };
+}
+/** Last line reading as this fence's closer at or after `from`; line 0 is the opener's slot. */
+function lastCloserIndex(lines, fence, from = 1) {
+    for (let i = lines.length - 1; i >= from; i--) {
+        if (matchFenceClose(lines[i], fence.marker, fence.length))
+            return i;
+    }
+    return -1;
+}
+function firstLineEnd(display) {
+    const index = display.indexOf('\n');
+    return index === -1 ? display.length : index;
+}
+function lineStartOffset(display, lineIndex) {
+    let offset = 0;
+    for (let i = 0; i < lineIndex; i++)
+        offset = display.indexOf('\n', offset) + 1;
+    return offset;
+}

package/dist/schema/global-commands.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Plugin-facing global commands: mint a process-wide command id, register a handler receiving
+ * the dispatching instance's EditorContext, optionally bind a chord in the plugin-global tier
+ * (last in precedence). Beside block-commands, not in commands.ts, for the same cycle reason —
+ * commands ← command-id must stay one-directional.
+ */
+import { type PluginCommandId } from './command-id';
+import type { EditorContext } from './plugin-install';
+export declare function registerGlobalCommand(name: string, handler: (editor: EditorContext) => boolean, opts?: {
+    chord?: string;
+}): PluginCommandId;

package/dist/schema/global-commands.js

@@ -0,0 +1,40 @@
+/**
+ * Plugin-facing global commands: mint a process-wide command id, register a handler receiving
+ * the dispatching instance's EditorContext, optionally bind a chord in the plugin-global tier
+ * (last in precedence). Beside block-commands, not in commands.ts, for the same cycle reason —
+ * commands ← command-id must stay one-directional.
+ */
+import { mintCommandId } from './command-id';
+import { registerCommand, registerPluginGlobalBinding, assertPluginGlobalChordAvailable, warnDeadKeyCommand } from './commands';
+import { currentInstallingPlugin } from './plugin-install';
+export function registerGlobalCommand(name, handler, opts) {
+    // Validate the chord BEFORE the mint: a collision must not leave a minted name and a
+    // registered handler behind a failed registration.
+    if (opts?.chord)
+        assertPluginGlobalChordAvailable(opts.chord, name);
+    const owner = currentInstallingPlugin();
+    // Owner-attributed: it is what lets a plugin re-mint its own name, and what names the prior
+    // owner in a cross-plugin collision.
+    const id = mintCommandId(name, owner);
+    registerCommand(id, (ctx) => {
+        if (!ctx.pluginEditor) {
+            warnDeadKeyCommand(id, 'plugin-global');
+            return false;
+        }
+        // Installed process-wide but absent from this editor's `plugins` prop: inert here, not
+        // dead, so it must not spend the dead-key diagnostic a truly unreachable id owes.
+        const editor = ctx.pluginEditor(owner ?? '');
+        if (!editor)
+            return false;
+        try {
+            return handler(editor);
+        }
+        catch (error) {
+            ctx.onCommandError?.({ command: id, plugin: owner ?? undefined, error });
+            return true;
+        }
+    });
+    if (opts?.chord)
+        registerPluginGlobalBinding({ chord: opts.chord, command: id }, owner);
+    return id;
+}

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

@@ -0,0 +1,131 @@
+/**
+ * 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.
+ */
+import { type AnyInlineKind } from '../core/nodes';
+import type { NodeView } from '../core/node-views';
+import type { LinkReferenceResolver } from '../core/inline/link-reference-resolver';
+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. */
+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.
+ */
+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. */
+    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. */
+    wrapBytes?: (content: string) => string;
+    /** The command whose press toggles this mark. */
+    command: AnyCommandId;
+}
+export interface InlineConstructPolicy {
+    edgeAffinity: 'symmetric-pair' | 'never-extend';
+    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. */
+    cardEditable?: boolean;
+    /** Absent for a construct no format chord addresses. */
+    mark?: InlineMarkPolicy;
+}
+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. */
+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. */
+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. */
+export declare function listInlineMarks(): readonly InlineMark[];
+/** The mark a command toggles, or null for a command no row claims. */
+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.
+ */
+export type LiveSplitRebalancer = (node: NodeView, offset: number, firstRaw: string, secondRaw: string, linkRef: InlineResolverRef | undefined) => {
+    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. */
+export interface JoinEndpoint {
+    node: NodeView;
+    offset: number;
+}
+/** The bytes a join produced, plus where the second side's contribution starts in them. */
+export interface JoinSeam {
+    mergedRaw: string;
+    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;
+}
+/** 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. */
+export interface CleanedJoin {
+    raw: string;
+    seam: number;
+}
+/**
+ * The one live-mode join rewrite, consulting each construct's own policy row, so the merge
+ * primitives need neither `parseInline` nor a per-kind dispatch. Null declines the rewrite.
+ */
+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. */
+export declare function __resetLiveSplitRebalancerForTests(): void;
+/** Test-only, {@link __resetLiveSplitRebalancerForTests}'s twin for the join slot. */
+export declare function __resetLiveJoinSeamCleanerForTests(): void;

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

@@ -0,0 +1,96 @@
+/**
+ * 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.
+ */
+import { isBuiltinInlineKind } from '../core/nodes';
+import { isBuiltinCommandId } from './commands';
+import { deletePluginEntries, registerOnce } from './register-once';
+const policies = new Map();
+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.`);
+}
+/** 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. */
+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`);
+}
+/** 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. */
+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`);
+}
+/** Undefined for a kind with no row: absent means "no live-mode construct behavior at all". */
+export function getInlineConstructPolicy(kind) {
+    return policies.get(kind);
+}
+/** Whether preview-inline's construct reveal may flip this kind's marker spans. */
+export function isRevealableInlineKind(kind) {
+    return policies.get(kind)?.revealable === true;
+}
+/** Whether the link card may address this kind's destination. */
+export function isCardEditableInlineKind(kind) {
+    return policies.get(kind)?.cardEditable === true;
+}
+export function listInlineConstructPolicies() {
+    return [...policies].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. */
+export function getInlineMarkPolicy(kind) {
+    return policies.get(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. */
+export function listInlineMarks() {
+    const marks = [];
+    for (const [kind, policy] of policies)
+        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. */
+export function inlineMarkForCommand(command) {
+    return listInlineMarks().find((entry) => entry.mark.command === command) ?? null;
+}
+let splitRebalancer;
+export function registerLiveSplitRebalancer(rebalancer) {
+    registerOnce(splitRebalancer !== undefined, () => (splitRebalancer = rebalancer), `registerLiveSplitRebalancer: a rebalancer is already registered. The slot holds one ` +
+        `function for every construct — extend that one rather than registering a second.`);
+}
+export function getLiveSplitRebalancer() {
+    return splitRebalancer;
+}
+let joinSeamCleaner;
+export function registerLiveJoinSeamCleaner(cleaner) {
+    registerOnce(joinSeamCleaner !== undefined, () => (joinSeamCleaner = cleaner), `registerLiveJoinSeamCleaner: a cleaner is already registered. The slot holds one ` +
+        `function for every construct — extend that one rather than registering a second.`);
+}
+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. */
+export function __resetLiveSplitRebalancerForTests() {
+    splitRebalancer = undefined;
+}
+/** Test-only, {@link __resetLiveSplitRebalancerForTests}'s twin for the join slot. */
+export function __resetLiveJoinSeamCleanerForTests() {
+    joinSeamCleaner = undefined;
+}

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

@@ -0,0 +1,39 @@
+/**
+ * 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.
+ */
+import type { AnyBlockKind } from '../core/nodes';
+import { type KeyBinding } from './keybindings';
+import type { AnyCommandId } from './command-id';
+/** A consumer override of the default keymap for one mounted editor (the `keybindings` prop). */
+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. */
+    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. */
+    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.
+     */
+    arg?: unknown;
+}
+/** A normalized override entry: a concrete binding, or `'disabled'` (the chord is unbound). */
+export type OverrideValue = KeyBinding | 'disabled';
+/** Compiled per-instance override lookup, split by scope. */
+export interface KeybindingOverrideMap {
+    global: Map<string, OverrideValue>;
+    byKind: Map<AnyBlockKind, Map<string, OverrideValue>>;
+}
+/** Compile the `keybindings` prop into the scoped lookup. Malformed chords are dev-warned and dropped. */
+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). */
+export declare function overrideDecision(value: OverrideValue | undefined): KeyBinding | null | undefined;

package/dist/schema/keybinding-overrides.js

@@ -0,0 +1,43 @@
+import { normalizeChordStrict } from './keybindings';
+const EMPTY = { global: new Map(), byKind: new Map() };
+/** Compile the `keybindings` prop into the scoped lookup. Malformed chords are dev-warned and dropped. */
+export function normalizeKeybindingOverrides(overrides) {
+    if (!overrides || overrides.length === 0)
+        return EMPTY;
+    const global = new Map();
+    const byKind = new Map();
+    for (const o of overrides) {
+        const chord = normalizeChordStrict(o.chord);
+        if (chord === null)
+            continue;
+        const value = o.command === null
+            ? 'disabled'
+            : { chord, command: o.command, ...(o.arg !== undefined ? { arg: o.arg } : {}) };
+        if (o.kind === undefined) {
+            global.set(chord, value);
+        }
+        else {
+            let kindMap = byKind.get(o.kind);
+            if (!kindMap) {
+                kindMap = new Map();
+                byKind.set(o.kind, kindMap);
+            }
+            kindMap.set(chord, value);
+        }
+    }
+    return { global, byKind };
+}
+/** Look up a single override for a (scope, chord). undefined when no entry exists. */
+export function lookupOverride(overrides, scope, chord) {
+    if (!overrides)
+        return undefined;
+    if (scope === 'global')
+        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). */
+export function overrideDecision(value) {
+    if (value === undefined)
+        return undefined;
+    return value === 'disabled' ? null : value;
+}

package/dist/schema/keybindings.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Keyboard chord parsing and the per-kind binding shape. `Mod` is the cross-platform
+ * Ctrl-or-Cmd modifier; a chord is modifiers in fixed order (Mod, Alt, Shift) then the key,
+ * single letters uppercased. Shifted-symbol keys (Shift+1 -> '!') are not modeled.
+ */
+import type { AnyCommandId } from './command-id';
+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.
+     */
+    arg?: unknown;
+}
+/**
+ * Keys that are a modifier being held, never a keystroke of their own. Every keydown consumer
+ * that must ignore "not a chord yet" reads this set rather than re-listing it.
+ */
+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;
+export declare function normalizeChord(chord: string): string;
+/**
+ * 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.
+ */
+export declare function isChordWellFormed(chord: string): boolean;
+/**
+ * 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'`.
+ */
+export declare function normalizeChordStrict(chord: string): string | null;