@pixerate/editor 0.22.0 → 0.24.0

package/dist/history/index.d.cts

@@ -1,19 +1,34 @@
-import { H as HistoryManagerOptions, a as HistoryState, C as Command, M as MergedExecutionOptions, S as SnapshotCommandOptions } from '../types-BZgcDsC5.cjs';
+import { b as HistoryManagerOptions, H as HistoryState, C as Command, M as MergedExecutionOptions, c as HistoryMark, a as HistoryEntry, S as SnapshotCommandOptions } from '../types-GT5a5YAX.cjs';
 
 /**
  * UI-agnostic History and Undo/Redo manager supporting command closures,
- * snapshot diffs, transaction batching, and high-frequency event coalescing.
+ * 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;
     /**
@@ -21,18 +36,51 @@ declare class HistoryManager {
      * 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.
+     * Clears the redo stack and ends the current gesture.
      */
     execute(command: Command): void;
     /**
-     * Executes a command, coalescing it with the previous command if they share
-     * the same `tag` and occurred within `windowMs` (default: 300ms).
-     * Useful for high-frequency interactions like slider scrubs or node drags.
+     * 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.
      */
@@ -42,6 +90,9 @@ declare class HistoryManager {
      * 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.
@@ -52,6 +103,30 @@ declare class HistoryManager {
      * 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.
      */
@@ -72,4 +147,133 @@ declare class HistoryManager {
  */
 declare function createHistoryManager(options?: HistoryManagerOptions): HistoryManager;
 
-export { Command, HistoryManager, HistoryManagerOptions, HistoryState, MergedExecutionOptions, SnapshotCommandOptions, createHistoryManager };
+/**
+ * Compares two values for structural equality.
+ * Handles primitives, objects, arrays, and null/undefined.
+ */
+declare function defaultIsEqual<T>(a: T, b: T): boolean;
+interface DirtyTrackerOptions<T> {
+    /**
+     * Equality check. When `normalize` is set it receives the normalized values.
+     */
+    isEqual?: (a: T, b: T) => boolean;
+    /**
+     * Projects a value onto the part that counts as "the document" before
+     * comparing, e.g. `({ selection, viewport, ...doc }) => doc` so that
+     * selecting, scrolling or zooming never marks the document dirty.
+     */
+    normalize?: (value: T) => unknown;
+}
+/**
+ * Tracks a baseline (saved) value and determines whether the current value is
+ * dirty (modified).
+ *
+ * Stateless use: `isDirty(current)`. Stateful use: feed values with
+ * `update(current, revision?)`, read `dirty`, `subscribe` to changes, call
+ * `markClean()` after saving and wrap programmatic loads in `suppress(fn)`.
+ */
+declare class DirtyTracker<T = unknown> {
+    private baseline;
+    private readonly isEqual;
+    private readonly normalize?;
+    private normalizedBaseline;
+    /** `isDirty` result as of a revision (and baseline version). */
+    private cache;
+    private baselineVersion;
+    private suppressDepth;
+    private hasValue;
+    private lastValue;
+    private dirtyState;
+    private listeners;
+    constructor(initialBaseline: T, options?: DirtyTrackerOptions<T> | ((a: T, b: T) => boolean));
+    /**
+     * Returns current baseline value.
+     */
+    getBaseline(): T;
+    private changeBaseline;
+    /**
+     * Sets a new baseline value without triggering any dirty state.
+     * If a value is being tracked (`update`), `dirty` is recomputed against it.
+     */
+    setBaseline(value: T): void;
+    private compare;
+    /**
+     * Checks whether the given value differs from the baseline.
+     * With a `revision` (e.g. `HistoryManager.getRevision()`), the result is
+     * cached and reused for the same revision until the baseline changes.
+     */
+    isDirty(current: T, revision?: number): boolean;
+    /**
+     * Resets the baseline to the provided current value (or clears dirty status).
+     */
+    reset(current: T): void;
+    /**
+     * Records the current value and returns whether it is dirty. While
+     * suppressed (`suppress`), the value becomes the new baseline instead, so
+     * programmatic loads and restores never mark the document dirty.
+     */
+    update(current: T, revision?: number): boolean;
+    /** Whether the last value passed to `update` differs from the baseline. */
+    get dirty(): boolean;
+    /** Whether `suppress` is currently running. */
+    get suppressed(): boolean;
+    /**
+     * Marks the document saved: `current` (default: the last value passed to
+     * `update`) becomes the baseline.
+     */
+    markClean(...args: [] | [current: T]): void;
+    /**
+     * Runs `fn` without marking anything dirty: every `update` during it
+     * rebaselines. Re-entrant (depth counter). If `fn` returns a promise, the
+     * suppression lasts until it settles.
+     */
+    suppress<R>(fn: () => R): R;
+    /**
+     * Subscribes to changes of `dirty`. The listener is called immediately with
+     * the current value. Returns an unsubscribe function.
+     */
+    subscribe(listener: (dirty: boolean) => void): () => void;
+    private setDirtyState;
+}
+/**
+ * Creates a DirtyTracker instance.
+ */
+declare function createDirtyTracker<T>(initialBaseline: T, options?: DirtyTrackerOptions<T> | ((a: T, b: T) => boolean)): DirtyTracker<T>;
+/**
+ * Runs `fn` with dirty tracking suppressed (see `DirtyTracker.suppress`).
+ */
+declare function withoutDirty<R>(tracker: DirtyTracker<any>, fn: () => R): R;
+/** Minimal history surface used by `bindDirtyToHistory` (`HistoryManager` satisfies it). */
+interface DirtyHistorySource {
+    subscribe(listener: (...args: any[]) => void): () => void;
+    getRevision?(): number;
+}
+interface BindDirtyToHistoryOptions<T> extends DirtyTrackerOptions<T> {
+    history: DirtyHistorySource;
+    /** Reads the current document value. */
+    getValue: () => T;
+    /** Existing tracker to drive (default: a new one baselined on `getValue()`). */
+    tracker?: DirtyTracker<T>;
+}
+interface HistoryDirtyBinding<T> {
+    readonly tracker: DirtyTracker<T>;
+    /** Whether the document differs from the saved baseline. */
+    readonly dirty: boolean;
+    /** Marks the current value as saved. */
+    markClean(): void;
+    /** Runs `fn` (e.g. a load or restore) without marking the document dirty. */
+    suppress<R>(fn: () => R): R;
+    /** Re-reads the value after a change made outside the history. */
+    refresh(): boolean;
+    subscribe(listener: (dirty: boolean) => void): () => void;
+    /** Stops listening to the history. */
+    destroy(): void;
+}
+/**
+ * Keeps a `DirtyTracker` in step with a `HistoryManager`: every history change
+ * re-reads the value (cached per history revision), so undoing back to the
+ * saved state makes the document clean again.
+ */
+declare function bindDirtyToHistory<T>(options: BindDirtyToHistoryOptions<T>): HistoryDirtyBinding<T>;
+
+export { type BindDirtyToHistoryOptions, Command, type DirtyHistorySource, DirtyTracker, type DirtyTrackerOptions, type HistoryDirtyBinding, HistoryEntry, HistoryManager, HistoryManagerOptions, HistoryMark, HistoryState, MergedExecutionOptions, SnapshotCommandOptions, bindDirtyToHistory, createDirtyTracker, createHistoryManager, defaultIsEqual, withoutDirty };

package/dist/history/index.d.ts

@@ -1,19 +1,34 @@
-import { H as HistoryManagerOptions, a as HistoryState, C as Command, M as MergedExecutionOptions, S as SnapshotCommandOptions } from '../types-BZgcDsC5.js';
+import { b as HistoryManagerOptions, H as HistoryState, C as Command, M as MergedExecutionOptions, c as HistoryMark, a as HistoryEntry, S as SnapshotCommandOptions } from '../types-GT5a5YAX.js';
 
 /**
  * UI-agnostic History and Undo/Redo manager supporting command closures,
- * snapshot diffs, transaction batching, and high-frequency event coalescing.
+ * 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;
     /**
@@ -21,18 +36,51 @@ declare class HistoryManager {
      * 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.
+     * Clears the redo stack and ends the current gesture.
      */
     execute(command: Command): void;
     /**
-     * Executes a command, coalescing it with the previous command if they share
-     * the same `tag` and occurred within `windowMs` (default: 300ms).
-     * Useful for high-frequency interactions like slider scrubs or node drags.
+     * 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.
      */
@@ -42,6 +90,9 @@ declare class HistoryManager {
      * 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.
@@ -52,6 +103,30 @@ declare class HistoryManager {
      * 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.
      */
@@ -72,4 +147,133 @@ declare class HistoryManager {
  */
 declare function createHistoryManager(options?: HistoryManagerOptions): HistoryManager;
 
-export { Command, HistoryManager, HistoryManagerOptions, HistoryState, MergedExecutionOptions, SnapshotCommandOptions, createHistoryManager };
+/**
+ * Compares two values for structural equality.
+ * Handles primitives, objects, arrays, and null/undefined.
+ */
+declare function defaultIsEqual<T>(a: T, b: T): boolean;
+interface DirtyTrackerOptions<T> {
+    /**
+     * Equality check. When `normalize` is set it receives the normalized values.
+     */
+    isEqual?: (a: T, b: T) => boolean;
+    /**
+     * Projects a value onto the part that counts as "the document" before
+     * comparing, e.g. `({ selection, viewport, ...doc }) => doc` so that
+     * selecting, scrolling or zooming never marks the document dirty.
+     */
+    normalize?: (value: T) => unknown;
+}
+/**
+ * Tracks a baseline (saved) value and determines whether the current value is
+ * dirty (modified).
+ *
+ * Stateless use: `isDirty(current)`. Stateful use: feed values with
+ * `update(current, revision?)`, read `dirty`, `subscribe` to changes, call
+ * `markClean()` after saving and wrap programmatic loads in `suppress(fn)`.
+ */
+declare class DirtyTracker<T = unknown> {
+    private baseline;
+    private readonly isEqual;
+    private readonly normalize?;
+    private normalizedBaseline;
+    /** `isDirty` result as of a revision (and baseline version). */
+    private cache;
+    private baselineVersion;
+    private suppressDepth;
+    private hasValue;
+    private lastValue;
+    private dirtyState;
+    private listeners;
+    constructor(initialBaseline: T, options?: DirtyTrackerOptions<T> | ((a: T, b: T) => boolean));
+    /**
+     * Returns current baseline value.
+     */
+    getBaseline(): T;
+    private changeBaseline;
+    /**
+     * Sets a new baseline value without triggering any dirty state.
+     * If a value is being tracked (`update`), `dirty` is recomputed against it.
+     */
+    setBaseline(value: T): void;
+    private compare;
+    /**
+     * Checks whether the given value differs from the baseline.
+     * With a `revision` (e.g. `HistoryManager.getRevision()`), the result is
+     * cached and reused for the same revision until the baseline changes.
+     */
+    isDirty(current: T, revision?: number): boolean;
+    /**
+     * Resets the baseline to the provided current value (or clears dirty status).
+     */
+    reset(current: T): void;
+    /**
+     * Records the current value and returns whether it is dirty. While
+     * suppressed (`suppress`), the value becomes the new baseline instead, so
+     * programmatic loads and restores never mark the document dirty.
+     */
+    update(current: T, revision?: number): boolean;
+    /** Whether the last value passed to `update` differs from the baseline. */
+    get dirty(): boolean;
+    /** Whether `suppress` is currently running. */
+    get suppressed(): boolean;
+    /**
+     * Marks the document saved: `current` (default: the last value passed to
+     * `update`) becomes the baseline.
+     */
+    markClean(...args: [] | [current: T]): void;
+    /**
+     * Runs `fn` without marking anything dirty: every `update` during it
+     * rebaselines. Re-entrant (depth counter). If `fn` returns a promise, the
+     * suppression lasts until it settles.
+     */
+    suppress<R>(fn: () => R): R;
+    /**
+     * Subscribes to changes of `dirty`. The listener is called immediately with
+     * the current value. Returns an unsubscribe function.
+     */
+    subscribe(listener: (dirty: boolean) => void): () => void;
+    private setDirtyState;
+}
+/**
+ * Creates a DirtyTracker instance.
+ */
+declare function createDirtyTracker<T>(initialBaseline: T, options?: DirtyTrackerOptions<T> | ((a: T, b: T) => boolean)): DirtyTracker<T>;
+/**
+ * Runs `fn` with dirty tracking suppressed (see `DirtyTracker.suppress`).
+ */
+declare function withoutDirty<R>(tracker: DirtyTracker<any>, fn: () => R): R;
+/** Minimal history surface used by `bindDirtyToHistory` (`HistoryManager` satisfies it). */
+interface DirtyHistorySource {
+    subscribe(listener: (...args: any[]) => void): () => void;
+    getRevision?(): number;
+}
+interface BindDirtyToHistoryOptions<T> extends DirtyTrackerOptions<T> {
+    history: DirtyHistorySource;
+    /** Reads the current document value. */
+    getValue: () => T;
+    /** Existing tracker to drive (default: a new one baselined on `getValue()`). */
+    tracker?: DirtyTracker<T>;
+}
+interface HistoryDirtyBinding<T> {
+    readonly tracker: DirtyTracker<T>;
+    /** Whether the document differs from the saved baseline. */
+    readonly dirty: boolean;
+    /** Marks the current value as saved. */
+    markClean(): void;
+    /** Runs `fn` (e.g. a load or restore) without marking the document dirty. */
+    suppress<R>(fn: () => R): R;
+    /** Re-reads the value after a change made outside the history. */
+    refresh(): boolean;
+    subscribe(listener: (dirty: boolean) => void): () => void;
+    /** Stops listening to the history. */
+    destroy(): void;
+}
+/**
+ * Keeps a `DirtyTracker` in step with a `HistoryManager`: every history change
+ * re-reads the value (cached per history revision), so undoing back to the
+ * saved state makes the document clean again.
+ */
+declare function bindDirtyToHistory<T>(options: BindDirtyToHistoryOptions<T>): HistoryDirtyBinding<T>;
+
+export { type BindDirtyToHistoryOptions, Command, type DirtyHistorySource, DirtyTracker, type DirtyTrackerOptions, type HistoryDirtyBinding, HistoryEntry, HistoryManager, HistoryManagerOptions, HistoryMark, HistoryState, MergedExecutionOptions, SnapshotCommandOptions, bindDirtyToHistory, createDirtyTracker, createHistoryManager, defaultIsEqual, withoutDirty };

package/dist/history/index.js

@@ -1,9 +1,19 @@
 import {
+  DirtyTracker,
   HistoryManager,
-  createHistoryManager
-} from "../chunk-KAADNAPF.js";
+  bindDirtyToHistory,
+  createDirtyTracker,
+  createHistoryManager,
+  defaultIsEqual,
+  withoutDirty
+} from "../chunk-2H7ZHPEJ.js";
 export {
+  DirtyTracker,
   HistoryManager,
-  createHistoryManager
+  bindDirtyToHistory,
+  createDirtyTracker,
+  createHistoryManager,
+  defaultIsEqual,
+  withoutDirty
 };
 //# sourceMappingURL=index.js.map