@voithos-labs/aragonite 0.10.1

package/dist/schema/keybindings.js

@@ -0,0 +1,75 @@
+import { devWarn } from '../dev-warn';
+const MOD_ORDER = ['Mod', 'Alt', 'Shift'];
+/**
+ * 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 const BARE_MODIFIER_KEYS = [
+    'Control',
+    'Shift',
+    'Alt',
+    'Meta',
+    'AltGraph',
+    'CapsLock'
+];
+const BARE_MODIFIERS = new Set(BARE_MODIFIER_KEYS);
+/** 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 function isCharacterKey(key) {
+    return [...key].length === 1;
+}
+function normalizeKey(key) {
+    return key.length === 1 ? key.toUpperCase() : key;
+}
+export function eventToChord(e) {
+    if (BARE_MODIFIERS.has(e.key))
+        return null;
+    const mods = [];
+    if (e.ctrlKey || e.metaKey)
+        mods.push('Mod');
+    if (e.altKey)
+        mods.push('Alt');
+    if (e.shiftKey)
+        mods.push('Shift');
+    return [...mods, normalizeKey(e.key)].join('+');
+}
+export function normalizeChord(chord) {
+    const parts = chord.split('+');
+    const key = parts.pop() ?? '';
+    const present = new Set(parts);
+    const mods = MOD_ORDER.filter((m) => present.has(m));
+    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.
+ */
+function chordDefect(chord) {
+    const parts = chord.split('+');
+    const key = parts.pop() ?? '';
+    if (key === '')
+        return 'empty key';
+    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.
+ */
+export function isChordWellFormed(chord) {
+    return chordDefect(chord) === null;
+}
+/**
+ * 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 function normalizeChordStrict(chord) {
+    const defect = chordDefect(chord);
+    if (defect !== null) {
+        devWarn('keybindings', `chord "${chord}": ${defect}; entry dropped`);
+        return null;
+    }
+    return normalizeChord(chord);
+}

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

@@ -0,0 +1,28 @@
+/**
+ * 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.
+ */
+import type { CstNode } from '../core/nodes';
+import { type MergeRole } from './block-kind-descriptor';
+/** Can `currKind` merge into `prevKind` on Backspace? Derived from role pairs, never kinds. */
+export declare function isMergeEligible(prevKind: CstNode['kind'], currKind: CstNode['kind']): boolean;
+export declare function getMergeRole(kind: CstNode['kind']): MergeRole;
+/**
+ * `target` is the leaf whose `raw` receives the merged text; `path` walks from the caller's
+ * `prev` block down to it, and is empty when `target === prev`.
+ */
+export interface MergeTarget {
+    target: CstNode;
+    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.
+ */
+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. */
+export declare function findMergeTarget(prev: CstNode): MergeTarget | null;
+export declare function isBlockEditable(kind: CstNode['kind']): boolean;

package/dist/schema/merge-rules.js

@@ -0,0 +1,57 @@
+/**
+ * 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.
+ */
+import { getBlockKindDescriptor } from './block-kind-descriptor';
+import { isCollapsedContainer } from './reserved-chrome';
+// ── Merge Eligibility ───────────────────────────────────────────────────────
+/** Can `currKind` merge into `prevKind` on Backspace? Derived from role pairs, never kinds. */
+export function isMergeEligible(prevKind, currKind) {
+    const prev = getMergeRole(prevKind);
+    const curr = getMergeRole(currKind);
+    if (prev === 'prose' && curr === 'prose')
+        return true;
+    if (prev === 'prose-absorber' && curr === 'prose')
+        return true;
+    if (prev === 'container' && curr === 'prose')
+        return true;
+    if (prev === 'self-merge' && curr === 'self-merge')
+        return true;
+    return false;
+}
+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.
+ */
+export function walkToDeepestMergeLeaf(node, path) {
+    const role = getMergeRole(node.kind);
+    if (role === 'prose' || role === 'prose-absorber') {
+        return { target: node, path };
+    }
+    if (!node.children || node.children.length === 0) {
+        return null;
+    }
+    const nextIndex = isCollapsedContainer(node) ? 0 : node.children.length - 1;
+    return walkToDeepestMergeLeaf(node.children[nextIndex], [...path, nextIndex]);
+}
+/** The leaf that receives text merged into `prev`; null means the caller moves focus instead. */
+export function findMergeTarget(prev) {
+    const role = getMergeRole(prev.kind);
+    if (role === 'prose' || role === 'prose-absorber' || role === 'self-merge') {
+        return { target: prev, path: [] };
+    }
+    if (role === 'container') {
+        return walkToDeepestMergeLeaf(prev, []);
+    }
+    return null;
+}
+// ── Block Editability ───────────────────────────────────────────────────────
+export function isBlockEditable(kind) {
+    return getBlockKindDescriptor(kind).editable;
+}

package/dist/schema/opener-priorities.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Priority ladder for the built-in block openers, single-sourced here so the published table and
+ * the registry cannot drift. Lower dispatches first, ties broken by kind name. A plugin opener
+ * whose matcher is a superset of a built-in's must price BELOW it (```mermaid under
+ * `fencedCode`); one that only slots between built-ins prices into the gap.
+ */
+export declare const OPENER_PRIORITIES: {
+    readonly fencedCode: 10;
+    readonly heading: 20;
+    readonly thematicBreak: 30;
+    readonly blockquote: 40;
+    readonly list: 50;
+    readonly indentedCode: 60;
+    readonly htmlBlock: 70;
+    readonly linkReferenceDefinition: 80;
+};

package/dist/schema/opener-priorities.js

@@ -0,0 +1,16 @@
+/**
+ * Priority ladder for the built-in block openers, single-sourced here so the published table and
+ * the registry cannot drift. Lower dispatches first, ties broken by kind name. A plugin opener
+ * whose matcher is a superset of a built-in's must price BELOW it (```mermaid under
+ * `fencedCode`); one that only slots between built-ins prices into the gap.
+ */
+export const OPENER_PRIORITIES = {
+    fencedCode: 10,
+    heading: 20,
+    thematicBreak: 30,
+    blockquote: 40,
+    list: 50,
+    indentedCode: 60,
+    htmlBlock: 70,
+    linkReferenceDefinition: 80
+};

package/dist/schema/operations.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Single source of truth for the structural-operation vocabulary: `OperationKind`,
+ * `OpDescriptor`, and `EditEvent` all derive from `OperationDetailMap`, so drift is a compile
+ * error rather than a one-place-missed edit.
+ */
+export interface OperationDetailMap {
+    split: {
+        at: number;
+        itemIndex?: number;
+        innerIndex?: number;
+    };
+    merge: {
+        direction: 'prev' | 'next';
+    };
+    reorder: {
+        from: number;
+        to: number;
+    };
+    delete: {
+        crossBlock?: true;
+        table?: 'whole';
+    } | undefined;
+    input: {
+        byteLength: number;
+    };
+    /** `crossBlock` marks a write that spanned the range's other blocks too: `path` names one
+     *  block, as every op does, and `length` is that block's. The `delete` twin reads the same.
+     *  A toggle endpoint carrying a CELL INDEX names its grid, whose own bytes no write holds, so
+     *  `length` is the grid's PRE-write length; a deep cell path names that cell like any block. */
+    updateContent: {
+        length: number;
+        crossBlock?: true;
+    };
+    replaceBlock: {
+        count: number;
+    } | {
+        action: 'indentItem' | 'promoteNestedItem';
+        itemIndex?: number;
+        parentItemIdx?: number;
+        nestedItemIdx?: number;
+    } | {
+        source: 'paste-dispatch' | 'paste-dispatch-table-cell' | 'cross-block-paste-whole-table';
+    };
+    paste: {
+        count: number;
+    } | {
+        source: 'list-absorb' | 'list-break-out' | 'container-matching' | 'container-matching-merge' | 'container-matching-merge-singleton';
+        listPath?: number[];
+        outerPath?: number[];
+    };
+    appendBlock: {
+        itemIndex?: number;
+    } | undefined;
+    /** Insert at an interior index; `appendBlock`'s sibling for a block minted BETWEEN two. */
+    insertBlock: undefined;
+    metadataUpdate: {
+        fields: string[];
+    };
+    undo: undefined;
+    redo: undefined;
+    tableInsertRow: {
+        rowIdx: number;
+        side: 'above' | 'below';
+    };
+    tableDeleteRow: {
+        rowIdx: number;
+        crossBlock?: true;
+    };
+    tableInsertColumn: {
+        colIdx: number;
+        side: 'left' | 'right';
+    };
+    tableDeleteColumn: {
+        colIdx: number;
+        crossBlock?: true;
+    };
+    tableReorderRow: {
+        from: number;
+        to: number;
+    };
+    tableReorderColumn: {
+        from: number;
+        to: number;
+    };
+    tableCycleAlignment: {
+        colIdx: number;
+    };
+    tableSetAlignment: {
+        colIdx: number;
+    };
+}
+import type { DocPath } from '../selection/path-math';
+export type OperationKind = keyof OperationDetailMap;
+/** Correlated kind↔detail pair; detail is optional only where the map allows undefined. */
+export type OpDescriptor = {
+    [K in OperationKind]: undefined extends OperationDetailMap[K] ? {
+        kind: K;
+        detail?: OperationDetailMap[K];
+    } : {
+        kind: K;
+        detail: OperationDetailMap[K];
+    };
+}[OperationKind];
+/**
+ * OpDescriptor plus the doc-absolute event path container/multi-scope commits carry. `eventPath`
+ * is `DocPath` so the op families composing it can't decay to a raw `number[]`.
+ */
+export type ScopedOpDescriptor = OpDescriptor & {
+    eventPath: DocPath;
+};

package/dist/schema/operations.js

@@ -0,0 +1,6 @@
+/**
+ * Single source of truth for the structural-operation vocabulary: `OperationKind`,
+ * `OpDescriptor`, and `EditEvent` all derive from `OperationDetailMap`, so drift is a compile
+ * error rather than a one-place-missed edit.
+ */
+export {};

package/dist/schema/plugin-activation.d.ts

@@ -0,0 +1,13 @@
+import type { KindEnablement } from './registry-view';
+export interface PluginActivation {
+    isActive(pluginName: string): boolean;
+}
+/** The prop-less default: everything installed in the process is active. */
+export declare const everyInstalledPlugin: PluginActivation;
+export declare function activationFor(pluginNames: readonly string[]): PluginActivation;
+/**
+ * A kind whose owning plugin this instance did not activate resolves no component and drops
+ * its opener. A kind no plugin owns is never gated, which covers the built-ins and any kind
+ * registered outside an install.
+ */
+export declare function kindEnablementFor(activation: PluginActivation): KindEnablement;

package/dist/schema/plugin-activation.js

@@ -0,0 +1,18 @@
+import { pluginKindOwner } from './plugin-install';
+/** The prop-less default: everything installed in the process is active. */
+export const everyInstalledPlugin = { isActive: () => true };
+export function activationFor(pluginNames) {
+    const active = new Set(pluginNames);
+    return { isActive: (name) => active.has(name) };
+}
+/**
+ * A kind whose owning plugin this instance did not activate resolves no component and drops
+ * its opener. A kind no plugin owns is never gated, which covers the built-ins and any kind
+ * registered outside an install.
+ */
+export function kindEnablementFor(activation) {
+    return (kind) => {
+        const owner = pluginKindOwner(kind);
+        return owner === null || activation.isActive(owner);
+    };
+}

package/dist/schema/plugin-editor-context.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Per-(instance, plugin) EditorContext: the one object onEditor callbacks, global-command
+ * handlers, and BlockCommandContext.editor all receive. `document` is a getter so every read is
+ * live (rules.md: getters, not values).
+ */
+import type { DocumentView } from '../core/node-views';
+import type { DecorationRegistry } from '../decorations/types';
+import type { EditorRects } from '../editor-rects';
+import type { PresentationMode } from '../presentation-mode';
+import type { PluginActivation } from './plugin-activation';
+import { type EditorContext, type EditorEventSubscriptions } from './plugin-install';
+export interface EditorPluginContexts {
+    /** The instance's context for a plugin it activated; `undefined` for one it did not. The
+     *  empty name is the instance's own base context (an unowned kind's), never gated. */
+    get(pluginName: string): EditorContext | undefined;
+    attachAll(onError: (report: {
+        plugin: string;
+        error: unknown;
+    }) => void): void;
+    dispose(): void;
+}
+export declare const mintEditorId: () => string;
+export declare function createEditorPluginContexts(deps: {
+    editorId: string;
+    getDoc: () => DocumentView;
+    events: EditorEventSubscriptions;
+    optionsFor: (pluginName: string) => unknown;
+    decorations: DecorationRegistry;
+    rects: EditorRects;
+    getPresentationMode: () => PresentationMode;
+    getTheme: () => string;
+    activation: PluginActivation;
+}): EditorPluginContexts;

package/dist/schema/plugin-editor-context.js

@@ -0,0 +1,65 @@
+import { installedPluginNames, onEditorCallbacks } from './plugin-install';
+// Process-monotonic instance id: `editor-1`, `editor-2`, … Stable per mount, so a
+// plugin can key per-instance state on `editor.editorId`.
+let n = 0;
+export const mintEditorId = () => `editor-${++n}`;
+export function createEditorPluginContexts(deps) {
+    const contexts = new Map();
+    const disposers = [];
+    let onDisposeError = () => { };
+    function get(pluginName) {
+        if (pluginName !== '' && !deps.activation.isActive(pluginName))
+            return undefined;
+        let ctx = contexts.get(pluginName);
+        if (!ctx) {
+            ctx = {
+                editorId: deps.editorId,
+                get document() {
+                    return deps.getDoc();
+                },
+                events: deps.events,
+                options: deps.optionsFor(pluginName),
+                decorations: deps.decorations,
+                rects: deps.rects,
+                get presentationMode() {
+                    return deps.getPresentationMode();
+                },
+                get theme() {
+                    return deps.getTheme();
+                }
+            };
+            contexts.set(pluginName, ctx);
+        }
+        return ctx;
+    }
+    return {
+        get,
+        attachAll(onError) {
+            onDisposeError = onError;
+            for (const plugin of installedPluginNames()) {
+                if (!deps.activation.isActive(plugin))
+                    continue;
+                for (const cb of onEditorCallbacks(plugin)) {
+                    try {
+                        const dispose = cb(get(plugin));
+                        if (typeof dispose === 'function')
+                            disposers.push({ plugin, dispose });
+                    }
+                    catch (error) {
+                        onError({ plugin, error });
+                    }
+                }
+            }
+        },
+        dispose() {
+            for (const d of disposers.splice(0)) {
+                try {
+                    d.dispose();
+                }
+                catch (error) {
+                    onDisposeError({ plugin: d.plugin, error });
+                }
+            }
+        }
+    };
+}

package/dist/schema/plugin-install.d.ts

@@ -0,0 +1,58 @@
+import type { DocumentView } from '../core/node-views';
+import type { EditorEvents } from '../editor-events';
+import type { DecorationRegistry } from '../decorations/types';
+import type { EditorRects } from '../editor-rects';
+import type { PresentationMode } from '../presentation-mode';
+export interface EditorPlugin<Options = unknown> {
+    readonly name: string;
+    readonly version?: string;
+    setup(ctx: PluginSetupContext<Options>): void;
+}
+export interface PluginSetupContext<Options = unknown> {
+    onEditor(cb: OnEditorCallback<Options>): void;
+}
+export type OnEditorCallback<Options = unknown> = (editor: EditorContext<Options>) => void | (() => void);
+/** Subscribe-only view of the events surface. EditorContext must NOT expose the
+ *  full EditorEvents — that would freeze plugin-visible `emit` at 1.0. */
+export type EditorEventSubscriptions = Pick<EditorEvents, 'on'>;
+export interface EditorContext<Options = unknown> {
+    readonly editorId: string;
+    readonly document: DocumentView;
+    readonly events: EditorEventSubscriptions;
+    readonly options: Options;
+    readonly decorations: DecorationRegistry;
+    readonly rects: EditorRects;
+    /** Getter-backed, live; the EFFECTIVE mode. Change signal: the `presentationModeChange` event. */
+    readonly presentationMode: PresentationMode;
+    /** Getter-backed, live; the theme name reflected to `data-editor-theme`. Change signal: the
+     *  `themeChange` event. Needed only by a plugin that PAINTS its own colors. */
+    readonly theme: string;
+}
+export declare function definePlugin<Options = unknown>(plugin: EditorPlugin<Options>): EditorPlugin<Options>;
+export declare function installPlugins(plugins: readonly EditorPlugin[]): void;
+/** A `plugins` prop entry: a bare unit, or a unit with per-instance options. */
+export type EditorPluginEntry = EditorPlugin | {
+    plugin: EditorPlugin;
+    options?: unknown;
+};
+/**
+ * Split a `plugins` prop into the install list and a name→options map. Options are per-instance
+ * even though a unit installs once process-global. A plugin listed twice keeps the first entry,
+ * the same first-wins rule installPlugins applies, so the options map can't disagree with it.
+ */
+export declare function normalizePluginEntries(entries: readonly EditorPluginEntry[]): {
+    plugins: EditorPlugin[];
+    optionsByName: Map<string, unknown>;
+};
+export declare function isPluginInstalled(name: string): boolean;
+export declare function currentInstallingPlugin(): string | null;
+export declare function recordPluginKindOwner(kind: string, plugin: string): void;
+export declare function pluginKindOwner(kind: string): string | null;
+/** The per-instance EditorContext of the plugin owning `kind`. The `''` miss arm hands an
+ *  unowned kind the base per-instance context, so the leaf and container tiers resolve alike. */
+export declare function owningPluginEditor(pluginEditor: ((pluginName: string) => EditorContext | undefined) | undefined, kind: string): EditorContext | undefined;
+/** onEditor callbacks a plugin registered during setup, in registration order. */
+export declare function onEditorCallbacks(pluginName: string): readonly OnEditorCallback[];
+/** Installed plugin names, in install order. */
+export declare function installedPluginNames(): string[];
+export declare function __resetInstalledPluginsForTests(): void;

package/dist/schema/plugin-install.js

@@ -0,0 +1,132 @@
+import { devWarn } from '../dev-warn';
+import { isValidPluginName } from './plugin-name';
+// ── Process-global install state ─────────────────────────────────────────────
+// A plugin is code: its setup writes into register-once registries, so it runs at most once per
+// process. `failed` remembers a name whose setup threw alongside its original error, since a
+// partial setup can't be re-run and a later attempt must advise a reload without losing the cause.
+const installed = new Map();
+const failed = new Map();
+const kindOwners = new Map();
+const onEditorSubs = new Map();
+let installing = null;
+// ── Public API ───────────────────────────────────────────────────────────────
+export function definePlugin(plugin) {
+    if (typeof plugin.setup !== 'function') {
+        throw new Error(`definePlugin: '${plugin.name}' setup must be a function`);
+    }
+    if (!isValidPluginName(plugin.name)) {
+        throw new Error(`definePlugin: invalid plugin name "${plugin.name}" — lowercase first letter, then letters/digits/hyphens`);
+    }
+    return plugin;
+}
+export function installPlugins(plugins) {
+    for (const plugin of plugins) {
+        const alreadyInstalled = installed.get(plugin.name);
+        if (alreadyInstalled) {
+            if (alreadyInstalled !== plugin) {
+                devWarn('plugin-install', `plugin '${pluginLabel(plugin)}' already installed; this definition (including any options) is ignored — definitions are process-global`);
+            }
+            continue;
+        }
+        if (failed.has(plugin.name)) {
+            throw new Error(`plugin '${pluginLabel(plugin)}' failed during a previous install; reload the page (or restart the dev server) — register-once registries cannot re-run a partial setup`, { cause: failed.get(plugin.name) });
+        }
+        installOne(plugin);
+    }
+}
+/**
+ * Split a `plugins` prop into the install list and a name→options map. Options are per-instance
+ * even though a unit installs once process-global. A plugin listed twice keeps the first entry,
+ * the same first-wins rule installPlugins applies, so the options map can't disagree with it.
+ */
+export function normalizePluginEntries(entries) {
+    const plugins = [];
+    const optionsByName = new Map();
+    const seen = new Set();
+    for (const entry of entries) {
+        const plugin = 'plugin' in entry ? entry.plugin : entry;
+        if (seen.has(plugin.name)) {
+            devWarn('plugin-install', `plugin '${plugin.name}' listed twice in one plugins prop; the first entry (and its options) wins`);
+            continue;
+        }
+        seen.add(plugin.name);
+        plugins.push(plugin);
+        if ('plugin' in entry && 'options' in entry)
+            optionsByName.set(plugin.name, entry.options);
+    }
+    return { plugins, optionsByName };
+}
+export function isPluginInstalled(name) {
+    return installed.has(name);
+}
+export function currentInstallingPlugin() {
+    return installing;
+}
+export function recordPluginKindOwner(kind, plugin) {
+    kindOwners.set(kind, plugin);
+}
+export function pluginKindOwner(kind) {
+    return kindOwners.get(kind) ?? null;
+}
+/** The per-instance EditorContext of the plugin owning `kind`. The `''` miss arm hands an
+ *  unowned kind the base per-instance context, so the leaf and container tiers resolve alike. */
+export function owningPluginEditor(pluginEditor, kind) {
+    return pluginEditor?.(pluginKindOwner(kind) ?? '');
+}
+/** onEditor callbacks a plugin registered during setup, in registration order. */
+export function onEditorCallbacks(pluginName) {
+    return onEditorSubs.get(pluginName) ?? [];
+}
+/** Installed plugin names, in install order. */
+export function installedPluginNames() {
+    return [...installed.keys()];
+}
+export function __resetInstalledPluginsForTests() {
+    installed.clear();
+    failed.clear();
+    kindOwners.clear();
+    onEditorSubs.clear();
+}
+// ── Internal ─────────────────────────────────────────────────────────────────
+function installOne(plugin) {
+    installing = plugin.name;
+    const { ctx, close } = makeSetupContext(plugin.name);
+    try {
+        plugin.setup(ctx);
+    }
+    catch (original) {
+        // A setup that threw after calling onEditor must leave no orphaned subscriptions: the
+        // plugin never installs, so its callbacks must never run.
+        onEditorSubs.delete(plugin.name);
+        failed.set(plugin.name, original);
+        const message = original instanceof Error ? original.message : String(original);
+        throw new Error(`plugin '${pluginLabel(plugin)}': ${message}`, { cause: original });
+    }
+    finally {
+        close();
+        installing = null;
+    }
+    installed.set(plugin.name, plugin);
+}
+// onEditor is synchronous-only: the closer fires the moment setup returns, so a context leaked
+// past setup throws instead of silently registering into a wiped install.
+function makeSetupContext(pluginName) {
+    let open = true;
+    const ctx = {
+        onEditor(cb) {
+            if (!open) {
+                throw new Error(`onEditor: '${pluginName}' called onEditor after setup returned — subscriptions are synchronous-only (the same boundary as kind attribution)`);
+            }
+            let list = onEditorSubs.get(pluginName);
+            if (!list)
+                onEditorSubs.set(pluginName, (list = []));
+            list.push(cb);
+        }
+    };
+    return { ctx, close: () => (open = false) };
+}
+// `name@version` when the plugin carries a version, so a two-version collision reads
+// unambiguously in the warn and the two failure throws.
+function pluginLabel(plugin) {
+    return plugin.version ? `${plugin.name}@${plugin.version}` : plugin.name;
+}

package/dist/schema/plugin-kind.d.ts

@@ -0,0 +1,21 @@
+import { type PluginBlockKind, type PluginInlineKind } from '../core/nodes';
+export declare function declarePluginKind(name: string): PluginBlockKind;
+/**
+ * Recover the branded kind for an already-declared name, so a module that didn't mint it reaches
+ * the brand without an unchecked cast. Throws for an undeclared name, so a typo can't silently
+ * register against a kind that doesn't exist.
+ */
+export declare function declaredPluginKind(name: string): PluginBlockKind;
+/**
+ * Non-throwing declaration probe, so an idempotent module (HMR, a re-imported registrar) asks
+ * before declaring instead of catching {@link declarePluginKind}'s or {@link declaredPluginKind}'s
+ * throw.
+ */
+export declare function isBlockKindDeclared(name: string): boolean;
+export declare function __clearDeclaredPluginKindsForTests(): void;
+export declare function declarePluginInlineKind(name: string): PluginInlineKind;
+/** The inline mirror of {@link declaredPluginKind}; throws for an undeclared name. */
+export declare function declaredPluginInlineKind(name: string): PluginInlineKind;
+/** The inline mirror of {@link isBlockKindDeclared}. */
+export declare function isInlineKindDeclared(name: string): boolean;
+export declare function __clearDeclaredPluginInlineKindsForTests(): void;