@pixerate/editor 0.21.0 → 0.23.0

package/dist/commands/index.d.ts

@@ -0,0 +1,592 @@
+import { J as JsonSchema, S as SchemaValidationError, A as AgentToolProvider } from '../registry-D5-R90p0.js';
+import { H as HistoryState } from '../types-GT5a5YAX.js';
+import { C as CanvasArrangeAction, A as AlignEdge, D as DistributeAxis, a as DistributeMode, Z as ZOrderOperation } from '../arrangeShortcuts-sLlD2rSX.js';
+import '../types-DX4Mh4SL.js';
+
+/**
+ * Keyboard chords in a platform-neutral notation.
+ *
+ * | token | macOS | Windows / Linux |
+ * |---|---|---|
+ * | `Mod` | ⌘ Command | Ctrl |
+ * | `Ctrl` | ⌃ Control | Ctrl (same key as `Mod`: conflicts are reported) |
+ * | `Meta` / `Cmd` | ⌘ Command | Win / Super |
+ * | `Alt` / `Option` | ⌥ Option | Alt |
+ * | `Shift` | ⇧ Shift | Shift |
+ *
+ * Keys are stored as `KeyboardEvent.code` values (`KeyZ`, `Digit1`, `BracketRight`,
+ * `PageDown`), so Option/Alt chords work on macOS (where Option changes `event.key`).
+ */
+type Platform = 'mac' | 'windows' | 'linux';
+declare const PLATFORMS: readonly Platform[];
+/** A parsed chord. `mod` is the platform's primary modifier. */
+interface Chord {
+    /** `KeyboardEvent.code` of the key, e.g. `KeyZ`. */
+    key: string;
+    mod?: boolean;
+    ctrl?: boolean;
+    meta?: boolean;
+    alt?: boolean;
+    shift?: boolean;
+}
+/** The modifiers a chord needs on one platform (`mod` resolved to `meta` or `ctrl`). */
+interface EffectiveChord {
+    key: string;
+    ctrl: boolean;
+    meta: boolean;
+    alt: boolean;
+    shift: boolean;
+}
+/** The current platform from `navigator` (`linux` when unknown, e.g. in Node). */
+declare function detectPlatform(): Platform;
+/** `KeyboardEvent.code` for a key token (`Z`, `1`, `]`, `PageDown`, `F5`, `KeyZ`), or `null`. */
+declare function keyToCode(token: string): string | null;
+/** Neutral text for a code: `KeyZ` → `Z`, `BracketRight` → `]`, `ArrowUp` → `Up`. */
+declare function codeToKeyText(code: string): string;
+/**
+ * Parses chord text (`Mod+Shift+Z`, `Alt+]`, `⌥⇧⌘K`, `CmdOrCtrl+K`). Throws on unknown
+ * modifiers or keys. The last `+`-separated token is the key (`+` itself is `Plus`).
+ */
+declare function parseChord(text: string): Chord;
+/** Canonical platform-neutral text: `Mod+Ctrl+Meta+Alt+Shift+<key>`. */
+declare function chordToString(chord: Chord): string;
+/** Canonical spelling of chord text (`shift+cmdorctrl+z` → `Mod+Shift+Z`). Throws when invalid. */
+declare function normalizeChord(text: string): string;
+/** The modifiers a chord needs on `platform`: `Mod` is ⌘ (meta) on macOS and Ctrl elsewhere. */
+declare function effectiveChord(chord: string | Chord, platform: Platform): EffectiveChord;
+/** Identity of an effective chord, for conflict detection (`Ctrl+Shift+KeyZ`). */
+declare function effectiveChordKey(chord: string | Chord, platform: Platform): string;
+/**
+ * Display text: `⌥⇧⌘K` on macOS, `Ctrl+Alt+Shift+K` on Windows / Linux (`Meta` shows as
+ * `Win` / `Super`). Invalid text is returned unchanged.
+ */
+declare function formatShortcut(chord: string | Chord, platform?: Platform): string;
+/** Minimal keyboard event surface (DOM `KeyboardEvent` satisfies it). */
+interface KeyboardEventLike {
+    key?: string;
+    code?: string;
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+    altKey?: boolean;
+    shiftKey?: boolean;
+    target?: EventTarget | null | unknown;
+    defaultPrevented?: boolean;
+    preventDefault?: () => void;
+}
+/** `event.code`, or one derived from `event.key` for synthetic events without a code. */
+declare function eventCode(event: KeyboardEventLike): string;
+/**
+ * The key code a shortcut event is matched by: `event.code` (layout-independent, so
+ * Option/Alt chords work on macOS and punctuation chords follow the physical key),
+ * except that a letter key producing a different Latin letter without Alt (AZERTY,
+ * QWERTZ, Dvorak) uses the produced letter, as browsers and operating systems do.
+ */
+declare function shortcutCode(event: KeyboardEventLike): string;
+/** The code a printable `event.key` names on a US layout (`z` → `KeyZ`, `]` → `BracketRight`). */
+declare function codeFromKey(key: string): string | null;
+/**
+ * Whether a keyboard event comes from a text-entry element: `<input>`, `<textarea>`,
+ * `<select>`, a `contenteditable` element (or a descendant) or a ProseMirror editor.
+ * Falls back to `document.activeElement` when the event has no element target.
+ */
+declare function isEditableEventTarget(event: {
+    target?: unknown;
+}): boolean;
+
+/** One key binding: a chord that runs `command`, optionally only in one scope / on some platforms. */
+interface ShortcutBinding {
+    command: string;
+    /** Chord text (`Mod+Shift+Z`) or a parsed chord. */
+    chord: string | Chord;
+    /** Scope (e.g. `canvas`, `spreadsheet`); scoped bindings win over global ones. Omit for global. */
+    scope?: string;
+    /** Platforms the binding exists on (default: all). E.g. `Mod+Y` redo only off macOS. */
+    platforms?: readonly Platform[];
+    /** Also fire while focus is in an input, textarea or contenteditable (default `false`). */
+    allowInEditable?: boolean;
+}
+/** Shortcut declaration on a command: chord text, or an object for platform / scope specifics. */
+type ShortcutInput = string | Omit<ShortcutBinding, 'command'> | ReadonlyArray<string | Omit<ShortcutBinding, 'command'>>;
+/** Expands a command's `shortcut` declaration into bindings. */
+declare function toShortcutBindings(command: string, input: ShortcutInput | undefined, scope?: string): ShortcutBinding[];
+interface ShortcutConflict {
+    /** Scope shared by the bindings (`undefined` = global). */
+    scope?: string;
+    /** Effective chord, e.g. `Ctrl+KeyZ`. */
+    chord: string;
+    /** Commands bound to it (two or more). */
+    commands: string[];
+}
+interface ShortcutMatch {
+    command: string;
+    binding: ShortcutBinding;
+}
+interface ShortcutResolveOptions {
+    /** Active scopes, most specific first. Bindings in these scopes win over global ones. */
+    scopes?: string | readonly string[];
+    /** Resolve even when the event comes from a text input (default: per binding). */
+    allowInEditable?: boolean;
+    /** Override the map's platform. */
+    platform?: Platform;
+}
+interface ShortcutMapOptions {
+    /** Platform used to resolve `Mod` (default: detected from `navigator` on every resolve). */
+    platform?: Platform;
+    /**
+     * `platform` (default): `Mod` means ⌘ on macOS and Ctrl elsewhere, exactly.
+     * `either`: `Mod` (and `Ctrl` / `Meta`) match ⌘ or Ctrl on every platform.
+     */
+    modifierMode?: 'platform' | 'either';
+}
+/**
+ * Keyboard shortcuts as data: default bindings plus user overrides, resolved from
+ * `KeyboardEvent`s by `event.code` (so Option/Alt chords work on macOS), with scopes
+ * (scoped bindings win), conflict detection per platform and display formatting.
+ */
+declare class ShortcutMap {
+    private defaults;
+    private overrides;
+    private readonly listeners;
+    private readonly options;
+    constructor(bindings?: readonly ShortcutBinding[], options?: ShortcutMapOptions);
+    get platform(): Platform;
+    private entry;
+    private changed;
+    /** Subscribes to binding changes. Returns an unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+    /** Adds default bindings (throws on invalid chord text). Returns a function removing them. */
+    bind(bindings: ShortcutBinding | readonly ShortcutBinding[]): () => void;
+    /**
+     * User override for a command: replaces all of its default bindings with `chords`
+     * (an empty list unbinds it). Throws on invalid chord text.
+     */
+    setOverride(command: string, chords: string | Chord | ReadonlyArray<string | Chord | Omit<ShortcutBinding, 'command'>>): void;
+    /** Removes a user override (the defaults apply again). */
+    clearOverride(command: string): void;
+    /** User overrides as plain data (`{ command: ['Mod+K'] }`), e.g. to persist them. */
+    getOverrides(): Record<string, string[]>;
+    /** Restores overrides saved with `getOverrides` (replacing the current ones). */
+    setOverrides(overrides: Record<string, readonly string[]>): void;
+    private active;
+    /** Effective bindings on `platform` (defaults without overridden commands, plus overrides). */
+    bindings(platform?: Platform): ShortcutBinding[];
+    /** Canonical chord text bound to `command` on `platform` (first = primary). */
+    forCommand(command: string, platform?: Platform): string[];
+    /**
+     * The command a keydown event runs, or `null`. Events from text inputs are ignored
+     * unless the binding (or `options`) allows them. Bindings in the active scopes
+     * (in order) win over global bindings; bindings in other scopes never match.
+     * Keys are matched by `event.code`, except that a letter key producing another Latin
+     * letter (AZERTY, QWERTZ, Dvorak) matches that letter when Alt is not held, so
+     * `Mod+Z` follows the Z label (see `shortcutCode`).
+     */
+    resolve(event: KeyboardEventLike, options?: ShortcutResolveOptions): ShortcutMatch | null;
+    private matches;
+    /**
+     * Groups of bindings that share an effective chord in one scope on `platform`
+     * (e.g. `Mod+Y` and `Ctrl+Y` collide off macOS). A scoped binding shadowing a
+     * global one is not a conflict.
+     */
+    findConflicts(platform?: Platform): ShortcutConflict[];
+    /** Conflicts on every platform, keyed by platform (only platforms with conflicts). */
+    findAllConflicts(): Partial<Record<Platform, ShortcutConflict[]>>;
+}
+
+/** Object JSON Schema describing a command's parameters. */
+type CommandParamsSchema = JsonSchema & {
+    type: 'object';
+};
+/**
+ * Metadata and implementation of one command. Menus, shortcuts, the palette and agent
+ * tools all run commands by id, so every entry point shares enablement and validation.
+ */
+interface CommandSpec<TContext = any, TParams = any, TResult = unknown> {
+    /** Unique id, e.g. `history.undo` or `canvas.alignLeft`. */
+    id: string;
+    label: string;
+    /** Group / menu name shown next to the label, e.g. `Edit` or `Arrange`. */
+    group?: string;
+    /** Extra search terms for the palette. */
+    keywords?: readonly string[];
+    description?: string;
+    /** Object JSON Schema for `params`. Unknown keys are rejected unless `additionalProperties` allows them. */
+    params?: CommandParamsSchema;
+    /** Default shortcut(s): platform-neutral chord text such as `Mod+Shift+Z`. */
+    shortcut?: ShortcutInput;
+    /** Scope the command (and its shortcuts) belong to, e.g. `canvas`. Omit for global commands. */
+    scope?: string;
+    /**
+     * Whether the command can run: `true` (or `undefined`), `false`, or a reason string
+     * ("Nothing to undo"). Receives the params a caller named, so a command acting on the
+     * selection can still run on targets passed explicitly (`params` is `undefined` for menus).
+     */
+    enabled?: (context: TContext, params: TParams | undefined) => boolean | string | undefined;
+    run: (context: TContext, params: TParams) => TResult;
+    /**
+     * Runs inside the registry's `history.batch(label, …)`, so all history entries the
+     * command records become one undo step and a throw rolls back its partial changes.
+     */
+    undoable?: boolean;
+    /** The command only reads state (agent tools mark it read-only). */
+    readOnly?: boolean;
+    /** Hide from the palette and `list()` unless `includeHidden` (still runnable by id). */
+    hidden?: boolean;
+}
+type CommandErrorCode = 'unknown_command' | 'disabled' | 'invalid_params' | 'failed';
+type CommandResult<T = unknown> = {
+    ok: true;
+    id: string;
+    result: T;
+} | {
+    ok: false;
+    id: string;
+    code: CommandErrorCode;
+    message: string;
+    details?: SchemaValidationError[];
+};
+/** A command as listed for menus, palettes and agents. */
+interface CommandEntry {
+    id: string;
+    label: string;
+    group?: string;
+    keywords?: readonly string[];
+    description?: string;
+    params?: CommandParamsSchema;
+    scope?: string;
+    /** Canonical chord text bound on the registry's platform (first = primary). */
+    shortcuts: string[];
+    enabled: boolean;
+    /** Why the command is disabled (only when `enabled` is false). */
+    disabledReason?: string;
+    undoable: boolean;
+    readOnly: boolean;
+}
+interface CommandListOptions<TContext = any> {
+    /** Only global commands plus commands of these scopes. */
+    scope?: string | readonly string[];
+    enabledOnly?: boolean;
+    includeHidden?: boolean;
+    /** Context for the enablement check (default: the registry's context). */
+    context?: TContext;
+}
+/** Minimal history surface (`HistoryManager` satisfies it). */
+interface CommandHistoryTarget {
+    batch(name: string, fn: () => void): void;
+}
+interface CommandRegistryOptions<TContext = any> {
+    /** Default context passed to `enabled` / `run` (a value or a getter). */
+    context?: TContext | (() => TContext);
+    /** Wraps `undoable` commands in one history step (see `CommandSpec.undoable`). */
+    history?: CommandHistoryTarget;
+    /** Options for the registry's `ShortcutMap`. */
+    shortcuts?: ShortcutMapOptions;
+}
+declare class CommandRegistryError extends Error {
+    readonly code: 'duplicate_command' | 'invalid_command';
+    constructor(code: CommandRegistryError['code'], message: string);
+}
+/**
+ * Registry of commands: one id per action, shared by shortcuts (`shortcuts`), the
+ * command palette (`list` + `rankCommands`) and agent tools (`createCommandToolProvider`).
+ */
+declare class CommandRegistry<TContext = any> {
+    /** Shortcut bindings of the registered commands (plus any user overrides). */
+    readonly shortcuts: ShortcutMap;
+    private readonly commands;
+    private readonly listeners;
+    private readonly options;
+    private version;
+    private muted;
+    constructor(options?: CommandRegistryOptions<TContext>);
+    /** Monotonic counter bumped on every change (useful as a snapshot key). */
+    getVersion(): number;
+    /** The default context. */
+    get context(): TContext;
+    /**
+     * Registers a command (or several) and returns a function that unregisters it.
+     * Throws a `CommandRegistryError` for a duplicate or invalid id, or invalid chord text.
+     */
+    register(spec: CommandSpec<TContext> | readonly CommandSpec<TContext>[]): () => void;
+    /** Removes a command by id. Returns whether it was registered. */
+    unregister(id: string): boolean;
+    private unbindQuietly;
+    has(id: string): boolean;
+    get(id: string): CommandSpec<TContext> | undefined;
+    /** Registered ids in registration order. */
+    ids(): string[];
+    /** Whether `id` can run now (`{ enabled, reason }`); `params` are the targets a caller named. */
+    isEnabled(id: string, params?: unknown, context?: TContext): {
+        enabled: boolean;
+        reason?: string;
+    };
+    /** Commands for menus, palettes and agents, with their current enablement. */
+    list(options?: CommandListOptions<TContext>): CommandEntry[];
+    private check;
+    private invoke;
+    /**
+     * Runs a command synchronously and returns a structured result; never throws.
+     * A command whose `run` returns a promise yields `{ ok: true, result: promise }`
+     * (use `executeAsync` to await it and catch its rejection).
+     */
+    execute<T = unknown>(id: string, params?: unknown, context?: TContext): CommandResult<T>;
+    /** Like `execute`, but awaits async commands (rejections become `failed` results). */
+    executeAsync<T = unknown>(id: string, params?: unknown, context?: TContext): Promise<CommandResult<T>>;
+    /**
+     * Resolves a keydown event to a command (see `ShortcutMap.resolve`) and runs it when
+     * enabled, calling `preventDefault()`. Disabled commands leave the event alone, so the
+     * browser or a focused editor can still handle it. Returns the result, or `null`.
+     */
+    handleKeyDown(event: KeyboardEventLike, options?: ShortcutResolveOptions & {
+        context?: TContext;
+    }): CommandResult | null;
+    /** Display-ready primary shortcut of a command (`⇧⌘Z` / `Ctrl+Shift+Z`), or `undefined`. */
+    shortcutFor(id: string, platform?: Platform): string | undefined;
+    /**
+     * Subscribes to changes: commands registered or removed, shortcut overrides, executed
+     * commands and `invalidate()` calls (e.g. when enablement inputs change).
+     */
+    subscribe(listener: () => void): () => void;
+    /** Tells subscribers that enablement may have changed (e.g. the selection changed). */
+    invalidate(): void;
+    private notify;
+}
+declare function createCommandRegistry<TContext = any>(options?: CommandRegistryOptions<TContext>): CommandRegistry<TContext>;
+/** Identity helper that types a command spec. */
+declare function defineCommand<TContext = any, TParams = any, TResult = unknown>(spec: CommandSpec<TContext, TParams, TResult>): CommandSpec<TContext, TParams, TResult>;
+
+/** The fields `rankCommands` searches (a `CommandEntry` satisfies it). */
+interface RankableCommand {
+    id: string;
+    label: string;
+    group?: string;
+    keywords?: readonly string[];
+    enabled?: boolean;
+}
+interface FuzzyMatch {
+    score: number;
+    /** Indices of the matched characters in the text (for highlighting). */
+    indices: number[];
+}
+/**
+ * Subsequence fuzzy match: every query character must appear in order. Consecutive
+ * matches score 8, others 1; a match at a word start adds 5; longer texts lose
+ * `length / 8`. Case-insensitive. Returns `null` when the query does not match.
+ */
+declare function fuzzyMatch(query: string, text: string): FuzzyMatch | null;
+/** `fuzzyMatch(query, text)?.score ?? null`. */
+declare function fuzzyScore(query: string, text: string): number | null;
+/**
+ * Bonus that puts a command whose name is exactly the query ahead of every fuzzy match
+ * ("undo" finds Undo before "Undo Selection Change"). Trailing ellipses are ignored.
+ */
+declare function exactBonus(query: string, names: readonly string[]): number;
+/** Default number of recently run commands a palette remembers. */
+declare const DEFAULT_RECENT_LIMIT = 8;
+/** Moves `id` to the front of `list` (deduplicated, newest first, at most `cap`). Returns a new array. */
+declare function pushRecent(list: readonly string[], id: string, cap?: number): string[];
+interface RankedCommand<T extends RankableCommand = RankableCommand> {
+    entry: T;
+    score: number;
+    /** Matched character indices in `entry.label` (empty when another field matched). */
+    labelIndices: number[];
+    /** The entry was shown because it was run recently (empty query). */
+    recent: boolean;
+}
+interface RankCommandsOptions {
+    /** Recently run ids, newest first. Shown first for an empty query and boosted slightly otherwise. */
+    recents?: readonly string[];
+    /** Maximum number of recents shown for an empty query (default 8). */
+    recentLimit?: number;
+    /** Maximum number of results. */
+    limit?: number;
+    /** Sort disabled commands after enabled ones (default `true`). */
+    disabledLast?: boolean;
+    /** With an empty query: `all` (default) lists recents then every other command; `recents` lists only recents. */
+    emptyQuery?: 'all' | 'recents';
+}
+/**
+ * Ranks commands for a palette query. Searches the label, `group label`, keywords and id;
+ * an exact label or keyword match always wins. An empty query lists recent commands
+ * first (deduplicated and capped), then the rest in their original order.
+ */
+declare function rankCommands<T extends RankableCommand>(query: string, entries: readonly T[], options?: RankCommandsOptions): RankedCommand<T>[];
+
+/** One palette row. */
+interface CommandPaletteItem extends RankedCommand<CommandEntry> {
+    id: string;
+    label: string;
+    group?: string;
+    /** Display-ready primary shortcut (`⇧⌘Z` / `Ctrl+Shift+Z`). */
+    shortcut?: string;
+    enabled: boolean;
+    disabledReason?: string;
+}
+interface CommandPaletteState {
+    open: boolean;
+    query: string;
+    activeIndex: number;
+    items: CommandPaletteItem[];
+    recents: string[];
+    /** Result of the last command the palette ran. */
+    lastResult: CommandResult | null;
+}
+interface CommandPaletteOptions<TContext = any> {
+    /** Context for enablement and runs (default: the registry's). */
+    context?: TContext | (() => TContext);
+    /** Only global commands plus these scopes. */
+    scope?: string | readonly string[] | (() => string | readonly string[] | undefined);
+    /** Initial recently run ids (newest first), e.g. restored from storage. */
+    recents?: readonly string[];
+    /** Called whenever the recents change, e.g. to persist them. */
+    onRecentsChange?: (recents: string[]) => void;
+    recentLimit?: number;
+    /** Maximum rows (default 50). */
+    limit?: number;
+    /** Platform for shortcut display (default: detected). */
+    platform?: Platform;
+    /** Called after a command ran from the palette. */
+    onRun?: (result: CommandResult) => void;
+}
+/**
+ * Framework-agnostic command palette state (open, query, ranked rows, active row and
+ * recents) over a `CommandRegistry`. The React hook and Svelte rune wrap it.
+ */
+declare function createCommandPaletteController<TContext = any>(registry: CommandRegistry<TContext>, options?: CommandPaletteOptions<TContext>): {
+    getState: () => CommandPaletteState;
+    subscribe(listener: (state: CommandPaletteState) => void): () => void;
+    setOpen(next: boolean): void;
+    toggle(): void;
+    setQuery(next: string): void;
+    setActiveIndex(index: number): void;
+    /** Moves the active row by `delta`, wrapping around. */
+    move(delta: number): void;
+    /** Runs a command by id, closes the palette and records it as recent. Disabled commands do nothing. */
+    run(id: string): CommandResult | null;
+    runActive(): CommandResult | null;
+    /**
+     * Keyboard handling for the palette input: ArrowUp/ArrowDown (wrap), Home/End,
+     * Enter (run the active row) and Escape (close). Returns whether it handled the key.
+     */
+    handleKeyDown(event: KeyboardEventLike): boolean;
+    /** Re-reads commands and enablement. */
+    refresh(): void;
+    destroy(): void;
+};
+type CommandPaletteController = ReturnType<typeof createCommandPaletteController>;
+/**
+ * Matches a global "open palette" hotkey (e.g. `Mod+K`), also while typing in inputs.
+ * Returns `true` when `event` is the hotkey.
+ */
+declare function matchPaletteHotkey(event: KeyboardEventLike, hotkey: string, platform?: Platform): boolean;
+
+interface CommandToolProviderOptions<TContext = any> {
+    /** Provider id (default `commands`). */
+    id?: string;
+    /** Always prefix the tool names with `<namespace>__`. */
+    namespace?: string;
+    /** Context for enablement and runs (default: the registry's). */
+    context?: TContext | (() => TContext);
+    /** Only expose global commands plus these scopes. */
+    scope?: string | readonly string[];
+    /** Commands agents may not see or run (e.g. ones that open dialogs). */
+    exclude?: (id: string) => boolean;
+}
+/**
+ * Exposes a `CommandRegistry` to agents through a `ToolRegistry`:
+ *
+ * - `list_commands {query?, enabledOnly?}`: ids, labels, params schemas, shortcuts and
+ *   enablement (with the reason a command is disabled).
+ * - `run_command {id, params?}`: runs one command; disabled commands, unknown params and
+ *   failures come back as `isError` results with a `{code, message}` error.
+ * - `run_commands {steps: [{id, params?}], stopOnError?}`: runs steps **in order**, each as
+ *   its own command (and undo step). It is not atomic: steps that succeeded before a failure
+ *   stay applied. For all-or-nothing behaviour, register a command that runs the steps
+ *   inside `HistoryManager.batch` (or mark it `undoable` on a registry with `history`).
+ *
+ * The id enum in `run_command`'s schema follows the registered commands, so the
+ * `ToolRegistry` announces `listChanged` when commands are added or removed.
+ */
+declare function createCommandToolProvider<TContext = any>(registry: CommandRegistry<TContext>, options?: CommandToolProviderOptions<TContext>): AgentToolProvider;
+
+/** Minimal history surface (`HistoryManager` satisfies it). */
+interface HistoryCommandTarget {
+    undo(): boolean | void;
+    redo(): boolean | void;
+    getState(): Pick<HistoryState, 'canUndo' | 'canRedo'> & Partial<Pick<HistoryState, 'undoName' | 'redoName'>>;
+}
+/** Default history bindings: `Mod+Z` undo; `Mod+Shift+Z` redo, plus `Mod+Y` off macOS. */
+declare const DEFAULT_HISTORY_SHORTCUTS: readonly ShortcutBinding[];
+interface HistoryCommandOptions {
+    /** Id prefix (default `history.`). */
+    prefix?: string;
+    group?: string;
+    scope?: string;
+}
+/** `history.undo` / `history.redo` commands for a `HistoryManager` (disabled with a reason when empty). */
+declare function createHistoryCommands(history: HistoryCommandTarget, options?: HistoryCommandOptions): CommandSpec[];
+/**
+ * Resolves a keydown event to `undo` / `redo` with the default history bindings
+ * (`Mod` is ⌘ on macOS and Ctrl elsewhere). Events from text inputs and
+ * contenteditable elements are ignored unless `allowInEditable`.
+ */
+declare function matchHistoryShortcut(event: KeyboardEventLike, options?: {
+    platform?: Platform;
+    allowInEditable?: boolean;
+}): 'undo' | 'redo' | null;
+/** Minimal arrange controller surface (`createCanvasArrangeController` satisfies it). */
+interface ArrangeCommandTarget {
+    align(edge: AlignEdge, ids?: Iterable<string>): unknown;
+    distribute(axis: DistributeAxis, mode?: DistributeMode, ids?: Iterable<string>): unknown;
+    reorder(operation: ZOrderOperation, ids?: Iterable<string>): unknown;
+    lock(ids?: Iterable<string>): unknown;
+    unlock(ids?: Iterable<string>): unknown;
+}
+interface ArrangeCommandOptions {
+    /** Id prefix (default `canvas.`). */
+    prefix?: string;
+    group?: string;
+    /** Scope of the commands and their shortcuts (default `canvas`). Pass `null` for global. */
+    scope?: string | null;
+    /** Current selection, used for enablement ("Select at least two nodes"). */
+    getSelectedIds?: () => string[];
+    /** Scene navigation (`nextScene` / `previousScene`); those commands are only added when given. */
+    scenes?: {
+        next(): unknown;
+        previous(): unknown;
+    };
+    /** Use these bindings instead of `DEFAULT_ARRANGE_SHORTCUTS`. */
+    bindings?: readonly {
+        action: CanvasArrangeAction;
+        label: string;
+    }[];
+}
+/**
+ * Commands for the canvas arrange actions (`canvas.alignLeft`, `canvas.bringToFront`, …)
+ * with the default arrange shortcuts. Each accepts `{ ids? }`; enablement checks the
+ * named ids, or the selection when none are named.
+ */
+declare function createArrangeCommands(controller: ArrangeCommandTarget, options?: ArrangeCommandOptions): CommandSpec[];
+/** Spreadsheet controller surface used by `createSpreadsheetCommands`. */
+interface SpreadsheetCommandTarget {
+    selectedRange: unknown;
+    getFilterState(): {
+        enabled: boolean;
+        rules: readonly unknown[];
+    };
+    toggleFilters(): void;
+    clearFilters(): void;
+    unhideAll(): void;
+    mergeCells(): boolean;
+    unmergeCells(): boolean;
+    transposeRange(): boolean;
+}
+interface SpreadsheetCommandOptions {
+    /** Id prefix (default `spreadsheet.`). */
+    prefix?: string;
+    /** Scope (default `spreadsheet`). Pass `null` for global. */
+    scope?: string | null;
+}
+/** Palette / agent commands for common spreadsheet table actions (no default shortcuts). */
+declare function createSpreadsheetCommands(controller: SpreadsheetCommandTarget, options?: SpreadsheetCommandOptions): CommandSpec[];
+
+export { type ArrangeCommandOptions, type ArrangeCommandTarget, type Chord, type CommandEntry, type CommandErrorCode, type CommandHistoryTarget, type CommandListOptions, type CommandPaletteController, type CommandPaletteItem, type CommandPaletteOptions, type CommandPaletteState, type CommandParamsSchema, CommandRegistry, CommandRegistryError, type CommandRegistryOptions, type CommandResult, type CommandSpec, type CommandToolProviderOptions, DEFAULT_HISTORY_SHORTCUTS, DEFAULT_RECENT_LIMIT, type EffectiveChord, type FuzzyMatch, type HistoryCommandOptions, type HistoryCommandTarget, type KeyboardEventLike, PLATFORMS, type Platform, type RankCommandsOptions, type RankableCommand, type RankedCommand, type ShortcutBinding, type ShortcutConflict, type ShortcutInput, ShortcutMap, type ShortcutMapOptions, type ShortcutMatch, type ShortcutResolveOptions, type SpreadsheetCommandOptions, type SpreadsheetCommandTarget, chordToString, codeFromKey, codeToKeyText, createArrangeCommands, createCommandPaletteController, createCommandRegistry, createCommandToolProvider, createHistoryCommands, createSpreadsheetCommands, defineCommand, detectPlatform, effectiveChord, effectiveChordKey, eventCode, exactBonus, formatShortcut, fuzzyMatch, fuzzyScore, isEditableEventTarget, keyToCode, matchHistoryShortcut, matchPaletteHotkey, normalizeChord, parseChord, pushRecent, rankCommands, shortcutCode, toShortcutBindings };