@voithos-labs/aragonite 0.10.3 → 0.10.7

package/dist/schema/commands.d.ts

@@ -1,9 +1,8 @@
 /**
- * The command vocabulary, the global command registry, and chord→binding resolution. GLOBAL
- * commands (undo/redo) are free functions over a minimal context; BLOCK-LOCAL ones run on the
- * focused block or a registered block-command handler. The chord dispatchers live in
- * `./block-commands`, not here, so this file carries no runtime edge to it. Schema leaf: it may
- * not import action-contracts, so `GlobalCommandContext` is what `HistoryActions` satisfies.
+ * The command ids, the global command registry, and chord-to-binding resolution. Global commands
+ * (undo/redo) are plain functions over a small context; block commands run on the focused block.
+ * The chord dispatchers live in `./block-commands`, and the editor's actions satisfy
+ * `GlobalCommandContext` by shape, so this file imports neither at runtime.
  */
 import type { AnyBlockKind } from '../core/nodes';
 import type { AnyCommandId } from './command-id';
@@ -11,30 +10,28 @@ import { type KeyBinding } from './keybindings';
 import { type KeybindingOverrideMap } from './keybinding-overrides';
 import type { EditorContext } from './plugin-install';
 import type { PluginActivation } from './plugin-activation';
-import type { CommandErrorSink } from './block-commands';
-import type { PresentationMode } from '../presentation-mode';
+import type { CommandDispatchContext, CommandErrorSink } from './block-commands';
+import { type PresentationMode } from '../presentation-mode';
 export declare const GLOBAL_COMMAND_IDS: readonly ["history.undo", "history.redo"];
-export declare const BLOCK_COMMAND_IDS: readonly ["block.split", "block.hardBreak", "block.insertTab", "block.mergePrev", "block.mergeNext", "block.moveUp", "block.moveDown", "format.toggleStrong", "format.toggleEmphasis", "format.toggleStrikethrough", "format.toggleCode", "link.openCard", "heading.cycle", "code.newline", "code.indent", "code.dedent", "code.backspace", "code.delete", "list.indent", "list.unindent", "cell.enter", "cell.tab", "cell.shiftTab", "table.insertRowBelow", "table.insertRowAbove", "table.insertColumnRight", "table.insertColumnLeft", "table.deleteRow", "table.deleteColumn", "table.moveRowUp", "table.moveRowDown", "table.moveColumnLeft", "table.moveColumnRight", "table.cycleAlignment", "chrome.descendToBody"];
+export declare const BLOCK_COMMAND_IDS: readonly ["block.split", "block.hardBreak", "block.insertTab", "block.mergePrev", "block.mergeNext", "block.moveUp", "block.moveDown", "format.toggleStrong", "format.toggleEmphasis", "format.toggleStrikethrough", "format.toggleCode", "link.openCard", "heading.cycle", "code.newline", "code.indent", "code.dedent", "code.backspace", "code.delete", "list.indent", "list.unindent", "list.toggleTask", "cell.enter", "cell.tab", "cell.shiftTab", "table.insertRowBelow", "table.insertRowAbove", "table.insertColumnRight", "table.insertColumnLeft", "table.deleteRow", "table.deleteColumn", "table.moveRowUp", "table.moveRowDown", "table.moveColumnLeft", "table.moveColumnRight", "table.cycleAlignment", "chrome.descendToBody"];
 export type GlobalCommandId = (typeof GLOBAL_COMMAND_IDS)[number];
 export type BlockCommandId = (typeof BLOCK_COMMAND_IDS)[number];
 export type CommandId = GlobalCommandId | BlockCommandId;
 /**
- * Commands whose arms rewrite one block's bytes around that block's own selection and have no
- * cross-block reading: the dispatch seam declines them outright while a range is painted.
- * Membership is the arm's shape, not the id's prefix — the link card mints its link over one
- * block's offsets, and a range gives it no one block to mint into.
+ * Commands that rewrite one block and have no cross-block form, declined while a selection spans
+ * blocks. Membership follows what the handler does (the link card, a heading level), not the id.
  */
 export declare const RANGE_DECLINED_COMMAND_IDS: ReadonlySet<string>;
+/** Built-in commands that move the block or row holding the caret rather than the caret. */
+export declare const BLOCK_MOVE_COMMAND_IDS: ReadonlySet<string>;
 /**
- * The same one-block arms, but with a cross-block one behind them
- * (`selection/cross-block/format-toggle.ts`), which the seam routes to through an injected
- * router. Declined wherever no router is threaded, so a dispatch site that skips it cannot
- * fall through to the focused block's own offsets.
+ * Single-block commands with a cross-block form (`selection/cross-block/format-toggle.ts`),
+ * declined wherever no router was injected so they never fall through to the focused block.
  */
 export declare const CROSS_BLOCK_RANGE_COMMAND_IDS: ReadonlySet<string>;
 /**
- * The command ids a host's selection toolbar invokes through `EditorInstance.runCommand`. The
- * rest of the vocabulary stays internal until the command registry unifies it.
+ * The ids a host's selection toolbar invokes through `EditorInstance.runCommand`. Each is in one of
+ * the two sets above, so `canRunCommand` can tell a toolbar which buttons a range leaves idle.
  */
 export declare const TOOLBAR_COMMANDS: {
     readonly toggleStrong: "format.toggleStrong";
@@ -43,6 +40,8 @@ export declare const TOOLBAR_COMMANDS: {
     readonly toggleCode: "format.toggleCode";
     /** The link editor Mod+K opens: over a selection it creates, inside a link it edits. */
     readonly editLink: "link.openCard";
+    /** The heading picker's command, taking the level as its argument; 0 is normal text. */
+    readonly setHeading: "heading.cycle";
 };
 /** Minimal context a global command needs; HistoryActions is structurally compatible. */
 export interface GlobalCommandContext {
@@ -53,95 +52,94 @@ export interface GlobalCommandContext {
     /** Per-instance context lookup, threaded from the dispatching editor; it resolves nothing
      *  for a plugin installed in the process that this editor did not activate. */
     pluginEditor?: (pluginName: string) => EditorContext | undefined;
-    /** The plugins the dispatching editor activated, so the process-global plugin-global tier
-     *  claims a chord only where its plugin is live. Required-nullable: a new dispatch context
-     *  must answer, and `undefined` is the answer of a caller holding no instance. */
-    activation: PluginActivation | undefined;
-    /** The effective presentation mode, read live — the reading-mode gate keys off this,
-     *  not the plugin lookup. Absent (a history-only context) means source. */
-    getPresentationMode?: () => PresentationMode;
-    /** Injected by dispatchKeyCommand — routes a contained handler throw. */
-    onCommandError?: CommandErrorSink;
+    /** The plugins the dispatching editor activated, so a plugin's global chord (registered
+     *  process-wide) fires only where its plugin is active; `everyInstalledPlugin` with no editor. */
+    activation: PluginActivation;
+    /** The effective presentation mode, read live; the reading-mode check reads this, not the
+     *  plugin lookup. */
+    getPresentationMode: () => PresentationMode;
+    /** Receives a caught handler throw. */
+    onCommandError: CommandErrorSink;
+    /** The argument `runCommand(id, arg)` or the chord's binding carried, injected per dispatch. */
+    arg?: unknown;
 }
 export type GlobalCommandRun = (ctx: GlobalCommandContext) => boolean;
-export declare function registerCommand(id: AnyCommandId, run: GlobalCommandRun): void;
-export declare function getCommand(id: AnyCommandId): GlobalCommandRun | undefined;
 /** True when the id is in the closed built-in vocabulary. Takes a plain, unbranded name. */
 export declare function isBuiltinCommandId(id: string): boolean;
-/**
- * Test-only. Removes every command outside the closed built-in vocabulary; the plugin-global
- * chord keymap resets separately (`__resetPluginGlobalKeymapForTests`).
- */
-export declare function __removePluginCommandsForTests(): void;
-/** Which seam found the command dead. Half the memo key below: a no-op at one seam must not
- *  spend the one-time diagnostic another seam still owes. */
+export declare function registerCommand(id: AnyCommandId, run: GlobalCommandRun): void;
+/** The command's handler where `activation` resolves the plugin that registered it. */
+export declare function getCommand(id: AnyCommandId, activation: PluginActivation): GlobalCommandRun | undefined;
+/** Whether any plugin or built-in registered the id, whatever the activation. */
+export declare function isCommandRegistered(id: AnyCommandId): boolean;
+/** The plugin whose setup registered a global command, read at dispatch like a block command's. */
+export declare function globalCommandOwner(id: AnyCommandId): string | null;
+/** Runs a plugin's command handler, global or block, and reports a throw as the plugin's that
+ *  registered it; a contained throw still counts as handled, so the key goes no further. */
+export declare function runPluginCommand(owner: string | null, failure: {
+    command: AnyCommandId;
+    kind?: AnyBlockKind;
+}, onCommandError: CommandErrorSink, run: () => boolean): boolean;
+/** Which dispatch path found the command dead. Half the memo key below: a no-op on one path must
+ *  not use up the one-time warning another path still has to give. */
 export type CommandDispatchPath = 'chord' | 'door' | 'plugin-global' | 'global-chord';
 /**
- * Dev-warn once per (id, path) that a command reached no runnable handler at `path` — a dead
- * key. Unreachable, not unregistered: a minted command resolves only where the dispatch target
- * supplies a command context.
+ * Dev-warn once per (id, path) that a command reached no runnable handler: a key that does nothing.
+ * Unreachable rather than unregistered: a plugin command needs the target's command context.
  */
 export declare function warnDeadKeyCommand(id: AnyCommandId, path: CommandDispatchPath): void;
-/** Test-only. Clears the dead-key warn memo so each test sees a first-time warn. */
-export declare function __resetCommandWarningsForTests(): void;
 export declare const GLOBAL_KEYMAP: KeyBinding[];
 /**
- * True when the editor UI intercepts a chord outside the command resolvers. The single source
- * both the plugin-global registration guard and the editor-root keydown handler read.
+ * True when the editor UI intercepts a normalized chord outside the command resolvers. The single
+ * source both the plugin-global registration guard and the editor-root keydown handler read.
  */
 export declare function isReservedUiChord(chord: string): boolean;
 /** The same pair, for the callers that must enumerate it rather than test one chord. */
 export declare function reservedUiChords(): readonly string[];
+/** The chord's normal form, or a throw when it can't be bound. A dev-server re-evaluation binding
+ *  `candidateCommand` to its own chord again replaces the binding rather than colliding. */
+export declare function assertPluginGlobalChordAvailable(rawChord: string, candidateCommand?: string): string;
+export declare function registerPluginGlobalBinding(binding: KeyBinding): void;
+export declare function pluginGlobalBinding(chord: string, activation: PluginActivation): KeyBinding | null;
+/** Every plugin-global binding `activation` resolves, each with the plugin that installed it. */
+export declare function pluginGlobalBindings(activation: PluginActivation): readonly (KeyBinding & {
+    plugin: string | null;
+})[];
+/** The chords of {@link pluginGlobalBindings}, normalized. */
+export declare function pluginGlobalChords(activation: PluginActivation): readonly string[];
+/** The bindings a kind resolves: its declared keymap, plus the whole-block defaults above. */
+export declare function kindKeymap(kind: AnyBlockKind): readonly KeyBinding[];
 /**
- * `candidateCommand` is the id the incoming registration will bind (the mint is deterministic:
- * name IS the id). A dev-server re-eval re-binding its OWN command to its OWN chord is an
- * idempotent replace, not a collision; reserved chords and cross-command collisions still throw.
- */
-export declare function assertPluginGlobalChordAvailable(rawChord: string, candidateCommand?: string): void;
-export declare function registerPluginGlobalBinding(binding: KeyBinding, plugin: string | null): void;
-export declare function pluginGlobalBinding(chord: string, activation: PluginActivation | undefined): KeyBinding | null;
-/** Every chord the plugin-global tier binds for `activation`. Registration is process-global,
- *  so an absent activation reflects plugins any mounted editor installed. */
-export declare function pluginGlobalChords(activation: PluginActivation | undefined): readonly string[];
-export declare function __resetPluginGlobalKeymapForTests(): void;
-/**
- * Container-bubble resolution: override(kind) → override(global) → built-in kind keymap. No
- * built-in GLOBAL fallthrough — undo/redo belong to the focused leaf, and a bubble re-firing
- * them would double-fire. Consumer overrides ARE honored at both scopes, so a global disable
- * unbinds a chord a kind defines, and a global bind shadows the built-in kind binding.
+ * A chord bubbled to a container: override(kind), override(global), then the built-in kind keymap.
+ * No built-in global fallthrough, since undo/redo belong to the focused leaf and would double-fire.
  */
 export declare function resolveKindBinding(chord: string, kind: AnyBlockKind, overrides?: KeybindingOverrideMap): KeyBinding | null;
 /**
  * Leaf precedence: override(kind) → override(global) → built-in kind → built-in global. Override
  * source dominates specificity, so a global disable suppresses a chord a kind defines.
  */
-export declare function resolveBinding(chord: string, kind: AnyBlockKind, overrides: KeybindingOverrideMap | undefined, activation: PluginActivation | undefined): KeyBinding | null;
+export declare function resolveBinding(chord: string, kind: AnyBlockKind, overrides: KeybindingOverrideMap | undefined, activation: PluginActivation): KeyBinding | null;
 /**
- * True when the built-in keymap, or a plugin-global chord `activation` claims, binds this exact
- * chord BEFORE any consumer override — never a modified variant like `Mod+Alt+Y`. Override-BLIND
- * by design: it answers which chords carry a native browser default to suppress, not which
- * command runs. A dispatch question reads `runGlobalChord`/`runGlobalChordOnKind`, which consult
- * the override tier.
+ * The command a keypress names at `kind`, overrides included, without running it; a keypress
+ * with no block under it (a null kind) resolves at global scope.
  */
-export declare function isDefaultGlobalChord(chord: string, activation: PluginActivation | undefined): boolean;
+export declare function commandForKey(e: KeyboardEvent, kind: AnyBlockKind | null, ctx: Pick<CommandDispatchContext, 'keybindingOverrides' | 'activation'>): AnyCommandId | null;
 /**
- * Resolve a chord at GLOBAL scope only, for input-layer sites with no focused block for a kind
- * tier to apply to: a consumer global override, else the editor-global keymap.
+ * Whether the built-in keymap or an active plugin-global chord binds this exact chord, ignoring
+ * overrides: the question is which chords have a browser default to suppress, not what runs.
  */
-export declare function resolveGlobalBinding(chord: string, overrides: KeybindingOverrideMap | undefined, activation: PluginActivation | undefined): KeyBinding | null;
-/** Reading mode consumes a claimed chord and runs nothing: falling through would hand a
- *  read-only document the browser's own history. */
-export interface GlobalChordContext extends GlobalCommandContext {
-    isReading: boolean;
-}
+export declare function isDefaultGlobalChord(chord: string, activation: PluginActivation): boolean;
+/**
+ * Resolve a chord at global scope only, for the input sites with no focused block whose kind
+ * keymap could apply: a consumer global override, else the editor-global keymap.
+ */
+export declare function resolveGlobalBinding(chord: string, overrides: KeybindingOverrideMap | undefined, activation: PluginActivation): KeyBinding | null;
 /**
- * Run whatever `chord` claims at global scope, for the surfaces with no focused block for a kind
- * tier to apply to — the editor root's windowed-out caret, the gap caret's proxy. True means the
- * press was CONSUMED, which a disabled chord is without running anything.
+ * Run what `chord` binds at global scope where no focused block's keymap applies (a caret in an
+ * unmounted block, the gap caret). True means consumed, which a disabled chord is too.
  */
-export declare function runGlobalChord(chord: string, overrides: KeybindingOverrideMap | undefined, context: GlobalChordContext): boolean;
+export declare function runGlobalChord(chord: string, context: CommandDispatchContext): boolean;
 /**
- * The same, for a block that IS its own focus target: no inner leaf carries the global tier for
- * it, so resolution takes the leaf precedence and a consumer's KIND-scoped rebind reaches here.
+ * The same for a block that is its own focus target: no inner leaf resolves global chords for it,
+ * so resolution takes the leaf precedence and a consumer's kind-scoped rebind reaches here.
  */
-export declare function runGlobalChordOnKind(chord: string, kind: AnyBlockKind, overrides: KeybindingOverrideMap | undefined, context: GlobalChordContext): boolean;
+export declare function runGlobalChordOnKind(chord: string, kind: AnyBlockKind, context: CommandDispatchContext): boolean;