@pixerate/editor 0.23.0 → 0.25.0

package/dist/commands/index.d.cts

@@ -1,359 +1,11 @@
-import { J as JsonSchema, S as SchemaValidationError, A as AgentToolProvider } from '../registry-D5-R90p0.cjs';
+import { C as CommandRegistry, P as Platform, a as CommandResult, b as CommandEntry, K as KeyboardEventLike, S as ShortcutBinding, c as CommandSpec } from '../registry-D32LpIc4.cjs';
+export { d as Chord, e as CommandErrorCode, f as CommandHistoryTarget, g as CommandListOptions, h as CommandParamsSchema, i as CommandRegistryError, j as CommandRegistryOptions, E as EffectiveChord, k as PLATFORMS, l as ShortcutConflict, m as ShortcutInput, n as ShortcutMap, o as ShortcutMapOptions, p as ShortcutMatch, q as ShortcutResolveOptions, r as chordToString, s as codeFromKey, t as codeToKeyText, u as createCommandRegistry, v as defineCommand, w as detectPlatform, x as effectiveChord, y as effectiveChordKey, z as eventCode, A as formatShortcut, B as isEditableEventTarget, D as keyToCode, F as normalizeChord, G as parseChord, H as shortcutCode, I as toShortcutBindings } from '../registry-D32LpIc4.cjs';
+import { A as AgentToolProvider } from '../registry-DnzpgY27.cjs';
 import { H as HistoryState } from '../types-GT5a5YAX.cjs';
 import { C as CanvasArrangeAction, A as AlignEdge, D as DistributeAxis, a as DistributeMode, Z as ZOrderOperation } from '../arrangeShortcuts-B8O3f8-P.cjs';
+import '../schema-DYDGdYL9.cjs';
 import '../types-DX4Mh4SL.cjs';
 
-/**
- * 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;
@@ -566,6 +218,39 @@ interface ArrangeCommandOptions {
  * named ids, or the selection when none are named.
  */
 declare function createArrangeCommands(controller: ArrangeCommandTarget, options?: ArrangeCommandOptions): CommandSpec[];
+/** Shape operations surface of the arrange controller (`createCanvasArrangeController` satisfies it). */
+interface ShapeCommandTarget {
+    combineShapes(operation: 'unite' | 'intersect' | 'subtract' | 'exclude' | 'divide', ids?: Iterable<string>): unknown;
+    canCombineShapes(ids?: Iterable<string>): boolean;
+    offsetShapes(distance: number, ids?: Iterable<string>, options?: {
+        join?: 'miter' | 'round' | 'bevel';
+        miterLimit?: number;
+    }): unknown;
+    canOffsetShapes(ids?: Iterable<string>): boolean;
+    outlineStroke(ids?: Iterable<string>, options?: {
+        join?: 'miter' | 'round' | 'bevel';
+        cap?: 'butt' | 'round' | 'square';
+        miterLimit?: number;
+    }): unknown;
+    canOutlineStroke(ids?: Iterable<string>): boolean;
+}
+interface ShapeCommandOptions {
+    /** Id prefix (default `canvas.`). */
+    prefix?: string;
+    group?: string;
+    /** Scope (default `canvas`). Pass `null` for global. */
+    scope?: string | null;
+    /** Offset distance used when `canvas.offsetPath` is run without one (default 10). */
+    defaultOffset?: number;
+}
+/**
+ * Palette / context-menu / agent commands for the shape operations: `canvas.unite`,
+ * `canvas.intersect`, `canvas.subtract`, `canvas.exclude`, `canvas.divide`,
+ * `canvas.offsetPath` (`{ distance, join?, miterLimit?, ids? }`) and `canvas.outlineStroke`
+ * (`{ join?, cap?, miterLimit?, ids? }`). Each is one undoable step when the controller has a
+ * history; enablement explains why a command cannot run.
+ */
+declare function createShapeCommands(controller: ShapeCommandTarget, options?: ShapeCommandOptions): CommandSpec[];
 /** Spreadsheet controller surface used by `createSpreadsheetCommands`. */
 interface SpreadsheetCommandTarget {
     selectedRange: unknown;
@@ -589,4 +274,4 @@ interface SpreadsheetCommandOptions {
 /** 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 };
+export { type ArrangeCommandOptions, type ArrangeCommandTarget, CommandEntry, type CommandPaletteController, type CommandPaletteItem, type CommandPaletteOptions, type CommandPaletteState, CommandRegistry, CommandResult, CommandSpec, type CommandToolProviderOptions, DEFAULT_HISTORY_SHORTCUTS, DEFAULT_RECENT_LIMIT, type FuzzyMatch, type HistoryCommandOptions, type HistoryCommandTarget, KeyboardEventLike, Platform, type RankCommandsOptions, type RankableCommand, type RankedCommand, type ShapeCommandOptions, type ShapeCommandTarget, ShortcutBinding, type SpreadsheetCommandOptions, type SpreadsheetCommandTarget, createArrangeCommands, createCommandPaletteController, createCommandToolProvider, createHistoryCommands, createShapeCommands, createSpreadsheetCommands, exactBonus, fuzzyMatch, fuzzyScore, matchHistoryShortcut, matchPaletteHotkey, pushRecent, rankCommands };