@pixerate/editor 0.27.0 → 0.29.0

package/README.md

@@ -208,6 +208,23 @@ await registry.callTool("insert_text", { text: "Hello" }); // { content: [...],
 
 `createEditorMcpToolProvider` exposes the static tools (`get_editor_state`, `edit_canvas`, `edit_prompt`, `view_editor`) through the registry, and `planToolCall` turns any tool call into planner steps (`step:tool_call` for registry tools).
 
+### Without TipTap: `@pixerate/editor/tools`
+
+`@pixerate/editor/agent` loads TipTap, ProseMirror and (through the canvas planner) dagre, because the rich-text, spreadsheet and canvas providers live there. Hosts that only need the registry, such as a canvas-only app or an effect editor exposing commands, can import it from `@pixerate/editor/tools`, which has no third-party imports:
+
+```ts
+import { createToolRegistry } from "@pixerate/editor/tools";
+import { createCommandToolProvider } from "@pixerate/editor/commands";
+
+const registry = createToolRegistry();
+registry.register(createCommandToolProvider(commands, { id: "effects" }));
+
+const list = registry.listTools(); // MCP tools/list result
+const result = await registry.callTool(name, args); // MCP tools/call result
+```
+
+It exports `ToolRegistry`, `createToolRegistry`, `ToolRegistryError`, the tool types (`AgentTool`, `AgentToolProvider`, `AgentToolHandler`, `ToolCallContext`, `McpToolDefinition`, `McpToolResult`, `McpListToolsResult`, `ToolCallError`), `validateJsonSchema` / `SchemaValidationError`, and the static `EDITOR_MCP_TOOLS` definitions. `/agent` re-exports all of it, so existing imports keep working. `createEditorMcpToolProvider` stays in `/agent` because its `layout` operation runs dagre.
+
 ## Commands, shortcuts and the command palette
 
 `@pixerate/editor/commands` gives every action one id that menus, keyboard shortcuts, the command palette and agents all run, so they share enablement and parameter validation. It has no third-party imports.
@@ -399,16 +416,41 @@ Each module is also available as a subpath import:
 | `@pixerate/editor/history` | `HistoryManager`: a command-pattern undo/redo stack with gesture merge keys, undo marks, a byte budget and a History-panel listing; `DirtyTracker` / `bindDirtyToHistory` |
 | `@pixerate/editor/spreadsheet` | `SpreadsheetController`, formula parser/evaluator and dependency graph, formula function registry (`registerFormulaFunction`, `listFormulaFunctions`, `searchFormulaFunctions`, `getFormulaSignature`) and autocomplete helpers (`getFormulaHints`, `applyFormulaSuggestion`) |
 | `@pixerate/editor/image-editor` | `ImageEditorController` and Canvas 2D renderer: crop, adjustments, annotations, depth masks, selections and layer masks, and AI hooks. Needs a DOM/canvas environment (the selection algorithms themselves are pure). |
-| `@pixerate/editor/canvas` | Node-graph layout (needs the optional `@dagrejs/dagre` peer), placement, trajectories, displacement, clipboard and streaming layout helpers |
+| `@pixerate/editor/animation` | The keyframe model without canvas nodes: `AnimationTrack` / `AnimationKeyframe`, easing (`resolveEasing`, `evaluateEasing`, `cubicBezierAt`, `springAt`, presets, `parseCssEasing`, `easingToCss`), `evaluateTrack`, `interpolateAnimationValue`, `normalizeKeyframes`, OKLab colour mixing, `AnimationPlayer` and the `Clock` / `ManualClock` / `realClock` time sources (no third-party imports) |
+| `@pixerate/editor/canvas` | Node-graph layout (needs the optional `@dagrejs/dagre` peer), placement, trajectories, displacement, clipboard and streaming layout helpers, and node keyframe animation (re-exports everything in `/animation`) |
 | `@pixerate/editor/agent` | MCP tool schemas, a planner for agent-driven canvas edits, and the dynamic `ToolRegistry` with editor/spreadsheet tool providers |
+| `@pixerate/editor/tools` | `ToolRegistry`, tool types, `validateJsonSchema` and the static MCP tool definitions, without TipTap or dagre (no third-party imports) |
 | `@pixerate/editor/commands` | `CommandRegistry`, `ShortcutMap`, palette ranking, `createCommandToolProvider` and built-in history / arrange / spreadsheet commands (no third-party imports) |
 | `@pixerate/editor/persistence` | Autosave and crash recovery (`createAutosaveController`, `createRecoveryPolicy`, `createRevisionTracker`), storage adapters (memory, localStorage, IndexedDB, OPFS) and document migration (`migrateDocument`, `loadSections`, `LoadReport`) (no third-party imports) |
 | `@pixerate/editor/generation` | Model capability descriptors, `planGenerationRequest`, `capabilitiesToJsonSchema`, `createGenerationToolProvider`, provenance, `createBatchResolver` and job-progress estimates (no third-party imports) |
 | `@pixerate/editor/compare` | `diffSequences` (Myers + patience), `compareDocuments` and `compareHtml`: two versions of a document as tracked changes (also re-exported from the root entry) |
 | `@pixerate/editor/export` | Word export: `exportDocx`, `exportDocxBlob`, `createDocxParts`, `DocxExportController`, plus the zip writer and XML escapers it uses (no third-party imports; also re-exported from the root entry) |
 | `@pixerate/editor/tokens` | Design tokens: collections, modes, aliases, `TokenStore`, `resolveToken`, W3C Design Tokens JSON and CSS custom-property export (no third-party imports) |
+| `@pixerate/editor/parameters` | Schema-driven parameters editor for effects, shaders, generators and component props: `ParameterSchema` (number, int, boolean, choice, color, vector, image and text fields; groups; `showIf`), `ParametersController` (validation, undo with merged slider gestures, reset, randomize, presets, keyframe hooks), `createParameterCommands` for agents and `parameterSchemaFromShaderControls` (no third-party imports) |
+
+The root entry (`@pixerate/editor`) re-exports everything except animation, canvas, agent, commands, persistence, generation, tokens, parameters and image editor, including TipTap. Import from the narrowest subpath you need: `grammar`, `history`, `animation`, `spreadsheet`, `commands`, `persistence` and `image-editor` have no third-party imports, so a spreadsheet-only app bundles no TipTap, markdown or dagre code. The package is marked `sideEffects: false`, so unused root exports are also tree-shaken.
+
+## Keyframe animation without the canvas
+
+`@pixerate/editor/animation` is the keyframe model on its own: no dagre, TipTap or canvas nodes. Use it to animate anything you can describe as a track of numbers or CSS colours.
+
+```ts
+import { evaluateTrack, createAnimationPlayer, ManualClock, type AnimationTrack } from "@pixerate/editor/animation";
+
+const opacity: AnimationTrack = {
+  keyframes: [
+    { time: 0, value: 0, easing: "ease-out" },
+    { time: 600, value: 1, easing: { type: "spring", stiffness: 170, damping: 26 } },
+    { time: 1200, value: 0.5 },
+  ],
+};
+evaluateTrack(opacity, 300); // eased value at 300 ms
+evaluateTrack({ keyframes: [{ time: 0, value: "#ff0000" }, { time: 1000, value: "transparent" }] }, 500, "color"); // OKLab mix
+
+const player = createAnimationPlayer({ clock: new ManualClock(), duration: 1200, loop: "ping-pong", onTime: (t) => console.log(evaluateTrack(opacity, t)) });
+```
 
-The root entry (`@pixerate/editor`) re-exports everything except canvas, agent, commands, persistence, generation, tokens and image editor, including TipTap. Import from the narrowest subpath you need: `grammar`, `history`, `spreadsheet`, `commands`, `persistence` and `image-editor` have no third-party imports, so a spreadsheet-only app bundles no TipTap, markdown or dagre code. The package is marked `sideEffects: false`, so unused root exports are also tree-shaken.
+`@pixerate/editor/canvas` re-exports all of it, and adds node tracks (`evaluateAnimation`, `applyAnimation`), editing, timeline and export helpers on top.
 
 ## Autosave, crash recovery and document migration
 

package/dist/HistoryManager-DWSLd6Tf.d.ts

@@ -0,0 +1,150 @@
+import { a as HistoryManagerOptions, H as HistoryState, C as Command, M as MergedExecutionOptions, b as HistoryMark, c as HistoryEntry, S as SnapshotCommandOptions } from './types-DsiXGmjo.js';
+
+/**
+ * UI-agnostic History and Undo/Redo manager supporting command closures,
+ * snapshot diffs, transaction batching, high-frequency event coalescing,
+ * keyed gestures, undo marks, a memory budget and a History-panel listing.
+ */
+declare class HistoryManager {
+    private undoStack;
+    private redoStack;
+    private readonly maxDepth;
+    private readonly maxBytes;
+    private readonly sizeOf?;
+    private isApplying;
+    private batchDepth;
+    private currentBatch;
+    private listeners;
+    private onStateChange?;
+    private cachedState;
+    private cachedEntries;
+    private nextId;
+    private revision;
+    /** Bumped by `clear()`; marks from an earlier epoch are stale. */
+    private epoch;
+    /** Number of steps dropped from the bottom (depth / byte budget) so far. */
+    private dropped;
+    /** Key of the gesture that the top step belongs to (see `executeMerged`). */
+    private gestureKey;
+    private gestureEntryId;
+    /** Key every merged execute takes while a gesture is held (`beginGesture`). */
+    private heldKey;
+    constructor(options?: HistoryManagerOptions);
+    private computeState;
+    /**
+     * Returns a snapshot of the current history state.
+     * Cached to maintain referential equality across renders for useSyncExternalStore.
+     */
+    getState(): HistoryState;
+    /**
+     * Monotonic counter bumped on every history change (execute, merge, undo,
+     * redo, revert, clear). Useful as a cache key, e.g. for `DirtyTracker`.
+     */
+    getRevision(): number;
+    private notify;
+    private measure;
+    private makeEntry;
+    /** Pushes a step, clears redo and applies the depth and byte limits. */
+    private record;
+    /**
+     * Keeps the stacks within `maxBytes`: the oldest undo steps that do not fit
+     * are dropped, but the most recent undo step is always kept.
+     */
+    private trim;
+    /** Approximate bytes held by the undo and redo stacks (see `maxBytes`). */
+    getByteSize(): number;
+    private resetGesture;
+    /**
+     * Executes a command and pushes it onto the undo stack.
+     * Clears the redo stack and ends the current gesture.
+     */
+    execute(command: Command): void;
+    /**
+     * Executes a command as part of a continuous interaction (slider scrub, node drag).
+     *
+     * - With `options.key` (or while a gesture is held with `beginGesture`):
+     *   consecutive merged executes with the same key fold into one undo step,
+     *   however long the gesture lasts. Recording any other command, undo, redo,
+     *   `revertTo`, `goTo`, `clear` or `endGesture()` ends the gesture.
+     * - Without a key: coalesces with the previous command if they share the same
+     *   `tag` and occurred within `windowMs` (default: 300ms).
+     */
+    executeMerged(command: Command, options?: MergedExecutionOptions): void;
+    /**
+     * Holds a gesture: until `endGesture()`, every `executeMerged` call (whatever
+     * its own key or tag) joins one undo step, e.g. an automation pass and
+     * whatever is dragged during it. Commands recorded with `execute` still end
+     * the current step; the next merged execute then starts a new one.
+     */
+    beginGesture(key: string): void;
+    /** Ends the current (keyed or held) gesture; the next merged execute starts a new step. */
+    endGesture(): void;
+    /** The key of the gesture currently merging into the top step, if any. */
+    getGestureKey(): string | null;
+    /**
+     * Batches multiple commands executed within `fn` into a single atomic undo entry.
+     */
+    batch(name: string, fn: () => void): void;
+    /**
+     * Reverts already-executed commands of an aborted batch, newest first.
+     * Commands executed by the undo closures themselves are not recorded.
+     */
+    private rollback;
+    /** Undoes the top step (caller holds `isApplying`). Throws leave it on the stack. */
+    private undoOne;
+    private redoOne;
+    /**
+     * Reverts the most recent command on the undo stack.
+     * Returns true if a command was undone, false otherwise.
+     */
+    undo(): boolean;
+    /**
+     * Re-applies the most recent undone command on the redo stack.
+     * Returns true if a command was redone, false otherwise.
+     */
+    redo(): boolean;
+    /**
+     * Captures the current point in the history (its top step), for `revertTo`.
+     */
+    mark(): HistoryMark;
+    /** Whether `mark` still points into the undo history. */
+    isMarkValid(mark: HistoryMark): boolean;
+    /**
+     * Takes back every step made since `mark` (merged or not), e.g. to cancel a
+     * drag with Escape: the state returns to how it was at `mark`, and neither
+     * undo nor redo keeps the reverted steps. Does nothing when `mark` has left
+     * the history (undone past, dropped by the limits, or cleared).
+     * Returns how many steps were taken back.
+     */
+    revertTo(mark: HistoryMark): number;
+    /**
+     * Lists the steps for a History panel: undo steps oldest first, then redo
+     * steps (the next redo first). Cached until the history changes.
+     */
+    getEntries(): HistoryEntry[];
+    /**
+     * Undoes or redoes until the step at `index` (from `getEntries`) is the
+     * current one; `-1` undoes everything. Returns how many steps were applied.
+     */
+    goTo(index: number): number;
+    /**
+     * Clears both undo and redo stacks.
+     */
+    clear(): void;
+    /**
+     * Subscribes to history state changes.
+     * The listener is immediately invoked with the current state.
+     * Returns an unsubscribe function.
+     */
+    subscribe(listener: (state: HistoryState) => void): () => void;
+    /**
+     * Utility helper to create a Command from before/after state snapshots.
+     */
+    static createSnapshotCommand<T>(options: SnapshotCommandOptions<T>): Command;
+}
+/**
+ * Creates and initializes a new HistoryManager instance.
+ */
+declare function createHistoryManager(options?: HistoryManagerOptions): HistoryManager;
+
+export { HistoryManager as H, createHistoryManager as c };

package/dist/HistoryManager-DeQQMBCj.d.cts

@@ -0,0 +1,150 @@
+import { a as HistoryManagerOptions, H as HistoryState, C as Command, M as MergedExecutionOptions, b as HistoryMark, c as HistoryEntry, S as SnapshotCommandOptions } from './types-DsiXGmjo.cjs';
+
+/**
+ * UI-agnostic History and Undo/Redo manager supporting command closures,
+ * snapshot diffs, transaction batching, high-frequency event coalescing,
+ * keyed gestures, undo marks, a memory budget and a History-panel listing.
+ */
+declare class HistoryManager {
+    private undoStack;
+    private redoStack;
+    private readonly maxDepth;
+    private readonly maxBytes;
+    private readonly sizeOf?;
+    private isApplying;
+    private batchDepth;
+    private currentBatch;
+    private listeners;
+    private onStateChange?;
+    private cachedState;
+    private cachedEntries;
+    private nextId;
+    private revision;
+    /** Bumped by `clear()`; marks from an earlier epoch are stale. */
+    private epoch;
+    /** Number of steps dropped from the bottom (depth / byte budget) so far. */
+    private dropped;
+    /** Key of the gesture that the top step belongs to (see `executeMerged`). */
+    private gestureKey;
+    private gestureEntryId;
+    /** Key every merged execute takes while a gesture is held (`beginGesture`). */
+    private heldKey;
+    constructor(options?: HistoryManagerOptions);
+    private computeState;
+    /**
+     * Returns a snapshot of the current history state.
+     * Cached to maintain referential equality across renders for useSyncExternalStore.
+     */
+    getState(): HistoryState;
+    /**
+     * Monotonic counter bumped on every history change (execute, merge, undo,
+     * redo, revert, clear). Useful as a cache key, e.g. for `DirtyTracker`.
+     */
+    getRevision(): number;
+    private notify;
+    private measure;
+    private makeEntry;
+    /** Pushes a step, clears redo and applies the depth and byte limits. */
+    private record;
+    /**
+     * Keeps the stacks within `maxBytes`: the oldest undo steps that do not fit
+     * are dropped, but the most recent undo step is always kept.
+     */
+    private trim;
+    /** Approximate bytes held by the undo and redo stacks (see `maxBytes`). */
+    getByteSize(): number;
+    private resetGesture;
+    /**
+     * Executes a command and pushes it onto the undo stack.
+     * Clears the redo stack and ends the current gesture.
+     */
+    execute(command: Command): void;
+    /**
+     * Executes a command as part of a continuous interaction (slider scrub, node drag).
+     *
+     * - With `options.key` (or while a gesture is held with `beginGesture`):
+     *   consecutive merged executes with the same key fold into one undo step,
+     *   however long the gesture lasts. Recording any other command, undo, redo,
+     *   `revertTo`, `goTo`, `clear` or `endGesture()` ends the gesture.
+     * - Without a key: coalesces with the previous command if they share the same
+     *   `tag` and occurred within `windowMs` (default: 300ms).
+     */
+    executeMerged(command: Command, options?: MergedExecutionOptions): void;
+    /**
+     * Holds a gesture: until `endGesture()`, every `executeMerged` call (whatever
+     * its own key or tag) joins one undo step, e.g. an automation pass and
+     * whatever is dragged during it. Commands recorded with `execute` still end
+     * the current step; the next merged execute then starts a new one.
+     */
+    beginGesture(key: string): void;
+    /** Ends the current (keyed or held) gesture; the next merged execute starts a new step. */
+    endGesture(): void;
+    /** The key of the gesture currently merging into the top step, if any. */
+    getGestureKey(): string | null;
+    /**
+     * Batches multiple commands executed within `fn` into a single atomic undo entry.
+     */
+    batch(name: string, fn: () => void): void;
+    /**
+     * Reverts already-executed commands of an aborted batch, newest first.
+     * Commands executed by the undo closures themselves are not recorded.
+     */
+    private rollback;
+    /** Undoes the top step (caller holds `isApplying`). Throws leave it on the stack. */
+    private undoOne;
+    private redoOne;
+    /**
+     * Reverts the most recent command on the undo stack.
+     * Returns true if a command was undone, false otherwise.
+     */
+    undo(): boolean;
+    /**
+     * Re-applies the most recent undone command on the redo stack.
+     * Returns true if a command was redone, false otherwise.
+     */
+    redo(): boolean;
+    /**
+     * Captures the current point in the history (its top step), for `revertTo`.
+     */
+    mark(): HistoryMark;
+    /** Whether `mark` still points into the undo history. */
+    isMarkValid(mark: HistoryMark): boolean;
+    /**
+     * Takes back every step made since `mark` (merged or not), e.g. to cancel a
+     * drag with Escape: the state returns to how it was at `mark`, and neither
+     * undo nor redo keeps the reverted steps. Does nothing when `mark` has left
+     * the history (undone past, dropped by the limits, or cleared).
+     * Returns how many steps were taken back.
+     */
+    revertTo(mark: HistoryMark): number;
+    /**
+     * Lists the steps for a History panel: undo steps oldest first, then redo
+     * steps (the next redo first). Cached until the history changes.
+     */
+    getEntries(): HistoryEntry[];
+    /**
+     * Undoes or redoes until the step at `index` (from `getEntries`) is the
+     * current one; `-1` undoes everything. Returns how many steps were applied.
+     */
+    goTo(index: number): number;
+    /**
+     * Clears both undo and redo stacks.
+     */
+    clear(): void;
+    /**
+     * Subscribes to history state changes.
+     * The listener is immediately invoked with the current state.
+     * Returns an unsubscribe function.
+     */
+    subscribe(listener: (state: HistoryState) => void): () => void;
+    /**
+     * Utility helper to create a Command from before/after state snapshots.
+     */
+    static createSnapshotCommand<T>(options: SnapshotCommandOptions<T>): Command;
+}
+/**
+ * Creates and initializes a new HistoryManager instance.
+ */
+declare function createHistoryManager(options?: HistoryManagerOptions): HistoryManager;
+
+export { HistoryManager as H, createHistoryManager as c };