@voithos-labs/aragonite 0.10.3 → 0.10.7

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

@@ -1,8 +1,8 @@
 /**
- * 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.
+ * Priority order for the built-in block openers, kept only here so the published table and the
+ * registry cannot drift. Lower runs first, ties broken by kind name. A plugin opener that matches
+ * everything a built-in matches and more needs a lower number than it (```mermaid below
+ * `fencedCode`); one that belongs between two built-ins takes a number in the gap.
  */
 export declare const OPENER_PRIORITIES: {
     readonly fencedCode: 10;

package/dist/schema/opener-priorities.js

@@ -1,8 +1,8 @@
 /**
- * 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.
+ * Priority order for the built-in block openers, kept only here so the published table and the
+ * registry cannot drift. Lower runs first, ties broken by kind name. A plugin opener that matches
+ * everything a built-in matches and more needs a lower number than it (```mermaid below
+ * `fencedCode`); one that belongs between two built-ins takes a number in the gap.
  */
 export const OPENER_PRIORITIES = {
     fencedCode: 10,

package/dist/schema/operations.d.ts

@@ -1,7 +1,7 @@
 /**
- * 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.
+ * The one list of structural operations: `OperationKind`, `OpDescriptor` and `EditEvent` all come
+ * from `OperationDetailMap`, so a mismatch is a compile error rather than an edit someone missed
+ * in one place.
  */
 export interface OperationDetailMap {
     split: {
@@ -23,10 +23,8 @@ export interface OperationDetailMap {
     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. */
+    /** `crossBlock` marks a write that also covered the range's other blocks. `length` is the named
+     *  block's, or for an endpoint carrying a cell index, its table's length before the write. */
     updateContent: {
         length: number;
         crossBlock?: true;
@@ -39,7 +37,7 @@ export interface OperationDetailMap {
         parentItemIdx?: number;
         nestedItemIdx?: number;
     } | {
-        source: 'paste-dispatch' | 'paste-dispatch-table-cell' | 'cross-block-covered-block';
+        source: 'paste-dispatch' | 'paste-dispatch-table-cell' | 'cross-block-covered-block' | 'selection-drop';
     };
     paste: {
         count: number;
@@ -51,7 +49,7 @@ export interface OperationDetailMap {
     appendBlock: {
         itemIndex?: number;
     } | undefined;
-    /** Insert at an interior index; `appendBlock`'s sibling for a block minted BETWEEN two. */
+    /** Insert at an index inside the list; `appendBlock`'s sibling for a block created between two. */
     insertBlock: undefined;
     metadataUpdate: {
         fields: string[];
@@ -109,8 +107,8 @@ export type OpDescriptor = {
     };
 }[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[]`.
+ * `OpDescriptor` plus the document-absolute path that container and multi-list commits carry.
+ * `eventPath` is a `DocPath` so the code that builds it cannot fall back to a plain `number[]`.
  */
 export type ScopedOpDescriptor = OpDescriptor & {
     eventPath: DocPath;

package/dist/schema/operations.js

@@ -1,6 +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.
+ * The one list of structural operations: `OperationKind`, `OpDescriptor` and `EditEvent` all come
+ * from `OperationDetailMap`, so a mismatch is a compile error rather than an edit someone missed
+ * in one place.
  */
 export {};

package/dist/schema/page-role.d.ts

@@ -0,0 +1,14 @@
+/**
+ * How a block reads on the page, the one answer the drag handle, the context menu and the drag
+ * ghost ask: the kind's declared `pageRole`, except that a paragraph holding only pictures is an
+ * object whatever its kind declares.
+ */
+import type { NodeView } from '../core/node-views';
+import type { InlineReading } from '../core/inline/inline-cache';
+export type PageRole = 'prose' | 'object';
+export declare function blockPageRole(node: NodeView, reading: InlineReading): PageRole;
+/**
+ * Prose the caret writes in: a prose block holding no children. A right-click there acts on the
+ * text; a prose container's own frame (a quote's bar) is aimed at the container instead.
+ */
+export declare function isProseLeaf(node: NodeView, reading: InlineReading): boolean;

package/dist/schema/page-role.js

@@ -0,0 +1,19 @@
+/**
+ * How a block reads on the page, the one answer the drag handle, the context menu and the drag
+ * ghost ask: the kind's declared `pageRole`, except that a paragraph holding only pictures is an
+ * object whatever its kind declares.
+ */
+import { isImageOnlyParagraph } from '../core/inline/picture';
+import { tryGetBlockKindDescriptor } from './block-kind-descriptor';
+export function blockPageRole(node, reading) {
+    if (isImageOnlyParagraph(node, reading))
+        return 'object';
+    return tryGetBlockKindDescriptor(node.kind)?.pageRole ?? 'object';
+}
+/**
+ * Prose the caret writes in: a prose block holding no children. A right-click there acts on the
+ * text; a prose container's own frame (a quote's bar) is aimed at the container instead.
+ */
+export function isProseLeaf(node, reading) {
+    return (blockPageRole(node, reading) === 'prose' && !tryGetBlockKindDescriptor(node.kind)?.isContainer);
+}

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

@@ -1,13 +1,11 @@
-import type { KindEnablement } from './registry-view';
 export interface PluginActivation {
     isActive(pluginName: string): boolean;
 }
-/** The prop-less default: everything installed in the process is active. */
+/** The default when no `plugins` prop is given; `resolvesIn` still drops a plugin whose setup threw. */
 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.
+ * An entry no plugin owns always resolves; a plugin's only once its setup finished without
+ * throwing and the editor activated it, so a half-installed plugin resolves nowhere.
  */
-export declare function kindEnablementFor(activation: PluginActivation): KindEnablement;
+export declare function resolvesIn(activation: PluginActivation, owner: string | null): boolean;

package/dist/schema/plugin-activation.js

@@ -1,18 +1,20 @@
-import { pluginKindOwner } from './plugin-install';
-/** The prop-less default: everything installed in the process is active. */
+/**
+ * Which plugins one editor activates, and the one check every plugin registration is read
+ * through. Definitions are process-wide; an editor activates exactly the plugins its `plugins`
+ * prop lists, and one mounted without that prop activates everything installed in the process
+ * (`docs/design/plugin-contract.md` § Per-instance enablement).
+ */
+import { isPluginInstalled } from './plugin-install';
+/** The default when no `plugins` prop is given; `resolvesIn` still drops a plugin whose setup threw. */
 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.
+ * An entry no plugin owns always resolves; a plugin's only once its setup finished without
+ * throwing and the editor activated it, so a half-installed plugin resolves nowhere.
  */
-export function kindEnablementFor(activation) {
-    return (kind) => {
-        const owner = pluginKindOwner(kind);
-        return owner === null || activation.isActive(owner);
-    };
+export function resolvesIn(activation, owner) {
+    return owner === null || (isPluginInstalled(owner) && activation.isActive(owner));
 }

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

@@ -1,22 +1,28 @@
 /**
- * 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).
+ * One `EditorContext` per editor and plugin: the object `onEditor` callbacks, global-command
+ * handlers and `BlockCommandContext.editor` all receive. `document` is a getter so every read is
+ * live (`docs/contributing/rules.md` § The five rules), and `options` is the plugin's defaults
+ * merged with this editor's entry.
  */
 import type { DocumentView } from '../core/node-views';
 import type { DecorationRegistry } from '../decorations/types';
 import type { EditorRects } from '../editor-rects';
+import type { InsertMarkdownOptions } from '../editor-props';
+import type { InlineMenuRegistry } from '../inline-menu/types';
 import type { PresentationMode } from '../presentation-mode';
-import type { PluginActivation } from './plugin-activation';
+import type { Reading } from './reading';
+import { type PluginActivation } from './plugin-activation';
 import { type EditorContext, type EditorEventSubscriptions } from './plugin-install';
+type ErrorReport = {
+    plugin: string;
+    error: unknown;
+};
 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. */
+    /** This editor's context for a plugin it activated; `undefined` for one it did not. The empty
+     *  name returns the editor's base context, the one kinds no plugin owns use, never filtered. */
     get(pluginName: string): EditorContext | undefined;
-    attachAll(onError: (report: {
-        plugin: string;
-        error: unknown;
-    }) => void): void;
+    /** Also receives any options error reported before it was called. */
+    attachAll(onError: (report: ErrorReport) => void): void;
     dispose(): void;
 }
 export declare const mintEditorId: () => string;
@@ -24,10 +30,19 @@ export declare function createEditorPluginContexts(deps: {
     editorId: string;
     getDoc: () => DocumentView;
     events: EditorEventSubscriptions;
+    /** The entry's options as the host wrote them, before the merge. */
     optionsFor: (pluginName: string) => unknown;
     decorations: DecorationRegistry;
     rects: EditorRects;
+    inlineMenus: InlineMenuRegistry;
+    getDocumentGeneration: () => number;
     getPresentationMode: () => PresentationMode;
     getTheme: () => string;
     activation: PluginActivation;
+    /** The instance's own entry points; the context only delegates. */
+    insertMarkdown: (md: string, options?: InsertMarkdownOptions) => Promise<boolean>;
+    runCommand: (commandId: string, arg?: unknown) => boolean;
+    /** How the editor reads its bytes, which every plugin inline read follows. */
+    reading: Reading;
 }): EditorPluginContexts;
+export {};

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

@@ -1,14 +1,31 @@
-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`.
+import { inlineReaderFor } from '../core/inline';
+import { insertCatalogue } from './insert-catalogue';
+import { resolvesIn } from './plugin-activation';
+import { installedPlugin, installedPluginNames, onEditorCallbacks, resolvePluginOptions } from './plugin-install';
+// Editor ids counted up across the process: `editor-1`, `editor-2`, … Stable for the life of a
+// mount, so a plugin can key its per-editor state on `editor.editorId`.
 let n = 0;
 export const mintEditorId = () => `editor-${++n}`;
 export function createEditorPluginContexts(deps) {
     const contexts = new Map();
     const disposers = [];
-    let onDisposeError = () => { };
+    // A block reads its options while it renders, which is before `attachAll` sets a handler.
+    const early = [];
+    let report = (r) => void early.push(r);
+    function optionsFor(pluginName) {
+        const plugin = installedPlugin(pluginName) ?? {};
+        try {
+            return resolvePluginOptions(plugin, deps.optionsFor(pluginName));
+        }
+        catch (cause) {
+            const message = cause instanceof Error ? cause.message : String(cause);
+            const error = new Error(`plugin '${pluginName}': options rejected, running on its defaults: ${message}`, { cause });
+            report({ plugin: pluginName, error });
+            return resolvePluginOptions(plugin, undefined);
+        }
+    }
     function get(pluginName) {
-        if (pluginName !== '' && !deps.activation.isActive(pluginName))
+        if (pluginName !== '' && !resolvesIn(deps.activation, pluginName))
             return undefined;
         let ctx = contexts.get(pluginName);
         if (!ctx) {
@@ -17,10 +34,22 @@ export function createEditorPluginContexts(deps) {
                 get document() {
                     return deps.getDoc();
                 },
+                get documentGeneration() {
+                    return deps.getDocumentGeneration();
+                },
                 events: deps.events,
-                options: deps.optionsFor(pluginName),
+                options: optionsFor(pluginName),
                 decorations: deps.decorations,
                 rects: deps.rects,
+                inlineMenus: deps.inlineMenus,
+                get insertCatalogue() {
+                    return insertCatalogue(deps.activation);
+                },
+                insertMarkdown: (md, options) => deps.insertMarkdown(md, options),
+                runCommand: (commandId, arg) => deps.runCommand(commandId, arg),
+                get computeInlineContent() {
+                    return inlineReaderFor(deps.reading);
+                },
                 get presentationMode() {
                     return deps.getPresentationMode();
                 },
@@ -35,9 +64,11 @@ export function createEditorPluginContexts(deps) {
     return {
         get,
         attachAll(onError) {
-            onDisposeError = onError;
+            report = onError;
+            for (const r of early.splice(0))
+                onError(r);
             for (const plugin of installedPluginNames()) {
-                if (!deps.activation.isActive(plugin))
+                if (!resolvesIn(deps.activation, plugin))
                     continue;
                 for (const cb of onEditorCallbacks(plugin)) {
                     try {
@@ -57,7 +88,7 @@ export function createEditorPluginContexts(deps) {
                     d.dispose();
                 }
                 catch (error) {
-                    onDisposeError({ plugin: d.plugin, error });
+                    report({ plugin: d.plugin, error });
                 }
             }
         }

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

@@ -1,58 +1,90 @@
-import type { DocumentView } from '../core/node-views';
+import type { DocumentView, NodeView } from '../core/node-views';
+import type { InlineNode } from '../core/nodes';
 import type { EditorEvents } from '../editor-events';
+import type { InsertMarkdownOptions } from '../editor-props';
 import type { DecorationRegistry } from '../decorations/types';
 import type { EditorRects } from '../editor-rects';
+import type { InlineMenuRegistry } from '../inline-menu/types';
 import type { PresentationMode } from '../presentation-mode';
+import type { InsertEntry } from './insert-catalogue';
 export interface EditorPlugin<Options = unknown> {
     readonly name: string;
     readonly version?: string;
+    /** Where every editor's `options` start; an editor's `{ plugin, options }` entry replaces them
+     *  field by field, an array included. */
+    readonly defaults?: Options;
+    /** Checks one editor's raw options and returns the fields to apply (leave a bad one out to keep
+     *  its default); a throw is reported on the `error` event and the editor runs on the defaults. */
+    parseOptions?(raw: unknown): Partial<Options>;
     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. */
+/** Subscribe-only view of the editor's events. `EditorContext` must not expose the full
+ *  `EditorEvents`: that would freeze a plugin-visible `emit` into the 1.0 API. */
 export type EditorEventSubscriptions = Pick<EditorEvents, 'on'>;
 export interface EditorContext<Options = unknown> {
     readonly editorId: string;
     readonly document: DocumentView;
+    /** A getter, so always live, but not reactive: how many times a `source` write has replaced
+     *  the document, 0 at mount. Subscribe to the `sourceSwap` event to hear a change. */
+    readonly documentGeneration: number;
     readonly events: EditorEventSubscriptions;
+    /** The plugin's `defaults` with this editor's `{ plugin, options }` entry merged over them. */
     readonly options: Options;
     readonly decorations: DecorationRegistry;
     readonly rects: EditorRects;
-    /** Getter-backed, live; the EFFECTIVE mode. Change signal: the `presentationModeChange` event. */
+    /** Menus opened under the caret by a typed trigger: tag autocomplete, a document picker. */
+    readonly inlineMenus: InlineMenuRegistry;
+    /** A getter, so always live: the blocks the insert menus offer in this editor, plugin blocks
+     *  included; the same list as `EditorInstance.getInsertCatalogue()`. */
+    readonly insertCatalogue: readonly InsertEntry[];
+    /** `EditorInstance.insertMarkdown` for this editor: false, nothing written, with no caret, in
+     *  reading mode or at a gap caret. Await it in `onCommit` to keep one undo entry for the pick. */
+    readonly insertMarkdown: (md: string, options?: InsertMarkdownOptions) => Promise<boolean>;
+    /** `EditorInstance.runCommand` for this editor: false, and nothing written, on an unknown id,
+     *  in reading mode, or with nothing focused for a block command. */
+    readonly runCommand: (commandId: string, arg?: unknown) => boolean;
+    /** Inline-parse a prose leaf as this editor draws it, reference links included. Uncached, and a
+     *  new function whenever the document's definitions change, so a cache keyed on it refreshes. */
+    readonly computeInlineContent: (node: NodeView) => InlineNode[];
+    /** A getter, so always live: the mode in effect. The `presentationModeChange` event signals a change. */
     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. */
+    /** A getter, so always live: the theme name written to `data-editor-theme`. The `themeChange`
+     *  event signals a change. Only a plugin that draws its own colors needs it. */
     readonly theme: string;
 }
-export declare function definePlugin<Options = unknown>(plugin: EditorPlugin<Options>): EditorPlugin<Options>;
+export declare function definePlugin<Options extends object = Record<never, never>>(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. */
+/** A `plugins` prop entry: a plugin on its own, or a plugin with options for this editor. */
 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.
+ * The options belong to one editor even though a plugin installs once per process. A plugin listed
+ * twice keeps its first entry, the rule `installPlugins` uses, so the two cannot disagree.
  */
 export declare function normalizePluginEntries(entries: readonly EditorPluginEntry[]): {
     plugins: EditorPlugin[];
     optionsByName: Map<string, unknown>;
 };
+/** One editor's options for a plugin: its defaults, then each defined field of the entry that
+ *  `parseOptions` kept. A `parseOptions` throw propagates, so the caller decides who hears it. */
+export declare function resolvePluginOptions<Options extends object>(plugin: Pick<EditorPlugin<Options>, 'defaults' | 'parseOptions'>, raw: unknown): Options;
+export declare function installedPlugin(name: string): EditorPlugin | undefined;
 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;
+/** An editor's `EditorContext` for the plugin an entry answers to; an entry no plugin owns gets
+ *  the editor's base context (`''`). Undefined when no editor is wired. */
+export declare function pluginEditorFor(lookup: ((pluginName: string) => EditorContext | undefined) | undefined, owner: string | null): EditorContext | undefined;
+/** Runs shared registrations a plugin's setup triggers as core ones, owned by no plugin, so every
+ *  editor resolves them whichever plugin reached them first. */
+export declare function registerAsCore(register: () => void): void;
+export declare function pluginInstallGeneration(): number;
 /** 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

@@ -1,21 +1,22 @@
 import { devWarn } from '../dev-warn';
 import { isValidPluginName } from './plugin-name';
+import { enrollTestReset } from './registry-reset';
 // ── 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.
+// A plugin's setup writes into register-once registries, so it runs at most once per process.
+// `failed` keeps a thrown setup's error, so a later attempt can say to reload and keep the cause.
 const installed = new Map();
 const failed = new Map();
-const kindOwners = new Map();
 const onEditorSubs = new Map();
 let installing = null;
+// Bumped whenever the installed set changes, so a cache filtered by installation can tell it is stale.
+let generation = 0;
 // ── 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`);
+        throw new Error(`definePlugin: invalid plugin name "${plugin.name}"; lowercase first letter, then letters/digits/hyphens`);
     }
     return plugin;
 }
@@ -24,20 +25,19 @@ export function installPlugins(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`);
+                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) });
+            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.
+ * The options belong to one editor even though a plugin installs once per process. A plugin listed
+ * twice keeps its first entry, the rule `installPlugins` uses, so the two cannot disagree.
  */
 export function normalizePluginEntries(entries) {
     const plugins = [];
@@ -56,22 +56,40 @@ export function normalizePluginEntries(entries) {
     }
     return { plugins, optionsByName };
 }
+/** One editor's options for a plugin: its defaults, then each defined field of the entry that
+ *  `parseOptions` kept. A `parseOptions` throw propagates, so the caller decides who hears it. */
+export function resolvePluginOptions(plugin, raw) {
+    const entry = raw === undefined ? {} : plugin.parseOptions ? plugin.parseOptions(raw) : raw;
+    return { ...plugin.defaults, ...definedFields(entry) };
+}
+export function installedPlugin(name) {
+    return installed.get(name);
+}
 export function isPluginInstalled(name) {
     return installed.has(name);
 }
 export function currentInstallingPlugin() {
     return installing;
 }
-export function recordPluginKindOwner(kind, plugin) {
-    kindOwners.set(kind, plugin);
+/** An editor's `EditorContext` for the plugin an entry answers to; an entry no plugin owns gets
+ *  the editor's base context (`''`). Undefined when no editor is wired. */
+export function pluginEditorFor(lookup, owner) {
+    return lookup?.(owner ?? '');
 }
-export function pluginKindOwner(kind) {
-    return kindOwners.get(kind) ?? null;
+/** Runs shared registrations a plugin's setup triggers as core ones, owned by no plugin, so every
+ *  editor resolves them whichever plugin reached them first. */
+export function registerAsCore(register) {
+    const outer = installing;
+    installing = null;
+    try {
+        register();
+    }
+    finally {
+        installing = outer;
+    }
 }
-/** 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) ?? '');
+export function pluginInstallGeneration() {
+    return generation;
 }
 /** onEditor callbacks a plugin registered during setup, in registration order. */
 export function onEditorCallbacks(pluginName) {
@@ -81,12 +99,13 @@ export function onEditorCallbacks(pluginName) {
 export function installedPluginNames() {
     return [...installed.keys()];
 }
-export function __resetInstalledPluginsForTests() {
+function __resetInstalledPluginsForTests() {
     installed.clear();
     failed.clear();
-    kindOwners.clear();
     onEditorSubs.clear();
+    generation++;
 }
+enrollTestReset(__resetInstalledPluginsForTests);
 // ── Internal ─────────────────────────────────────────────────────────────────
 function installOne(plugin) {
     installing = plugin.name;
@@ -105,17 +124,18 @@ function installOne(plugin) {
     finally {
         close();
         installing = null;
+        generation++;
     }
     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.
+// `onEditor` works during setup only: the context closes the moment setup returns, so a context
+// kept past that throws instead of quietly registering into an install that is already over.
 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)`);
+                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)
@@ -125,8 +145,14 @@ function makeSetupContext(pluginName) {
     };
     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.
+// An entry's field set to `undefined` keeps its default, the same as leaving it out.
+function definedFields(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return {};
+    return Object.fromEntries(Object.entries(value).filter(([, field]) => field !== undefined));
+}
+// `name@version` when the plugin carries a version, so a clash between two versions is
+// unambiguous in the warning and in the two failure messages.
 function pluginLabel(plugin) {
     return plugin.version ? `${plugin.name}@${plugin.version}` : plugin.name;
 }

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

@@ -1,21 +1,25 @@
+/**
+ * Declaring the names plugin kinds take, block and inline, and which plugin declared each: a
+ * kind's owner is the plugin whose setup declared it, and it decides where the kind resolves.
+ */
 import { type PluginBlockKind, type PluginInlineKind } from '../core/nodes';
 export declare function declarePluginKind(name: string): PluginBlockKind;
+/** The plugin whose setup declared `kind`; null for a built-in or a kind declared outside one. */
+export declare function pluginKindOwner(kind: string): string | null;
 /**
- * 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.
+ * The branded kind for a declared name, without an unchecked cast. Throws for an undeclared name,
+ * so a typo cannot quietly register against a kind that does not 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.
+ * A module that may run twice (hot reload, a re-imported registration) asks this first 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 pluginKindOwner}. */
+export declare function pluginInlineKindOwner(kind: string): string | null;
 /** The inline mirror of {@link isBlockKindDeclared}. */
 export declare function isInlineKindDeclared(name: string): boolean;
-export declare function __clearDeclaredPluginInlineKindsForTests(): void;