@pixerate/editor 0.254.1 → 0.256.0

package/dist/paint-editor/controller.d.cts

@@ -194,6 +194,29 @@ export interface PaintLayerInfo {
     /** How many live layer effects (glows, shadows, strokes…) it has, when any (`getLayerEffects`). */
     effects?: number;
 }
+/** One change to the paint history, for hosts and change feeds (`onCommit`). */
+export interface PaintCommitEvent {
+    /** `execute`: a new undo step. `merge`: folded into the last one (a slider drag). */
+    kind: 'execute' | 'merge' | 'undo' | 'redo';
+    /** The step's name. */
+    label: string;
+    /** Who made the step: `user`, or `agent:<id>` (see `withOrigin`). */
+    origin: string;
+}
+/** Paint a preview produced (`previewPaint`), in document coordinates, straight RGBA. */
+export interface PaintPreview {
+    /** Where the new paint sits, or `null` when nothing was painted. */
+    bounds: RasterRect | null;
+    /** The new paint alone: `bounds.width × bounds.height` pixels (empty when nothing was painted). */
+    pixels: Uint8ClampedArray;
+    /** The whole picture as it would look with the new paint, inside `bounds` (with the paper; empty when nothing was painted). */
+    composite: Uint8ClampedArray;
+}
+/** Where `previewPaint` puts its layer: above a layer (default the active one), or at the bottom of the stack. */
+export interface PaintPreviewPlacement {
+    aboveId?: string;
+    bottom?: boolean;
+}
 export interface PaintStrokeInit {
     /** Default the active layer. */
     layerId?: string;
@@ -337,6 +360,13 @@ export declare class PaintEditorController {
     private stickerPreview;
     private readonly encodeImage;
     private listeners;
+    private commitListeners;
+    /** Origins set by `withOrigin`, innermost last. */
+    private origins;
+    /** `group` in progress: commits fold into one step, recorded when it ends. */
+    private grouping;
+    /** `previewPaint` in progress: nothing is emitted or recorded. */
+    private previewing;
     private version;
     private cached;
     private session;
@@ -393,6 +423,30 @@ export declare class PaintEditorController {
     private paperEffectNodeCache;
     constructor(options?: PaintEditorOptions);
     subscribe(listener: () => void): () => void;
+    /** Hears each undo step recorded, merged, undone or redone, with who made it. Returns an unsubscribe function. */
+    onCommit(listener: (event: PaintCommitEvent) => void): () => void;
+    private notifyCommit;
+    /** The origin steps are recorded with now: the innermost `withOrigin`, else `user`. */
+    getOrigin(): string;
+    /**
+     * Records the steps `fn` makes as made by `origin` (`agent:<id>` for an agent). When `fn` returns
+     * a promise, the origin holds until it settles. Satisfies `createOriginMiddleware`'s history target,
+     * so agent tool calls are recorded as the calling agent's.
+     */
+    withOrigin<T>(origin: string, fn: () => T): T;
+    /**
+     * Runs `fn` as one undo step named `label`: every change it makes (strokes, fills, new layers) is
+     * undone together. Wet paint can't be grouped. Nested groups join the outer one. If `fn` throws,
+     * its changes are put back and nothing is recorded.
+     */
+    group<T>(label: string, fn: () => T): T;
+    /**
+     * What `fn` would paint, without changing anything: it runs on a new empty layer (above the
+     * active layer, another one, or at the bottom), and the layer's pixels and the picture with them
+     * come back while the document, history and listeners stay as they were. `fn` gets that layer's id and must paint on it with dry brushes (strokes, replays and
+     * fills); wet paint can't be previewed. For ghost paint an agent suggests (`createPaintProposals`).
+     */
+    previewPaint(fn: (layerId: string) => void, placement?: PaintPreviewPlacement): PaintPreview;
     private emit;
     /** A snapshot of the editor (the same object until something changes). */
     getState(): PaintEditorState;

package/dist/paint-editor/controller.d.ts

@@ -194,6 +194,29 @@ export interface PaintLayerInfo {
     /** How many live layer effects (glows, shadows, strokes…) it has, when any (`getLayerEffects`). */
     effects?: number;
 }
+/** One change to the paint history, for hosts and change feeds (`onCommit`). */
+export interface PaintCommitEvent {
+    /** `execute`: a new undo step. `merge`: folded into the last one (a slider drag). */
+    kind: 'execute' | 'merge' | 'undo' | 'redo';
+    /** The step's name. */
+    label: string;
+    /** Who made the step: `user`, or `agent:<id>` (see `withOrigin`). */
+    origin: string;
+}
+/** Paint a preview produced (`previewPaint`), in document coordinates, straight RGBA. */
+export interface PaintPreview {
+    /** Where the new paint sits, or `null` when nothing was painted. */
+    bounds: RasterRect | null;
+    /** The new paint alone: `bounds.width × bounds.height` pixels (empty when nothing was painted). */
+    pixels: Uint8ClampedArray;
+    /** The whole picture as it would look with the new paint, inside `bounds` (with the paper; empty when nothing was painted). */
+    composite: Uint8ClampedArray;
+}
+/** Where `previewPaint` puts its layer: above a layer (default the active one), or at the bottom of the stack. */
+export interface PaintPreviewPlacement {
+    aboveId?: string;
+    bottom?: boolean;
+}
 export interface PaintStrokeInit {
     /** Default the active layer. */
     layerId?: string;
@@ -337,6 +360,13 @@ export declare class PaintEditorController {
     private stickerPreview;
     private readonly encodeImage;
     private listeners;
+    private commitListeners;
+    /** Origins set by `withOrigin`, innermost last. */
+    private origins;
+    /** `group` in progress: commits fold into one step, recorded when it ends. */
+    private grouping;
+    /** `previewPaint` in progress: nothing is emitted or recorded. */
+    private previewing;
     private version;
     private cached;
     private session;
@@ -393,6 +423,30 @@ export declare class PaintEditorController {
     private paperEffectNodeCache;
     constructor(options?: PaintEditorOptions);
     subscribe(listener: () => void): () => void;
+    /** Hears each undo step recorded, merged, undone or redone, with who made it. Returns an unsubscribe function. */
+    onCommit(listener: (event: PaintCommitEvent) => void): () => void;
+    private notifyCommit;
+    /** The origin steps are recorded with now: the innermost `withOrigin`, else `user`. */
+    getOrigin(): string;
+    /**
+     * Records the steps `fn` makes as made by `origin` (`agent:<id>` for an agent). When `fn` returns
+     * a promise, the origin holds until it settles. Satisfies `createOriginMiddleware`'s history target,
+     * so agent tool calls are recorded as the calling agent's.
+     */
+    withOrigin<T>(origin: string, fn: () => T): T;
+    /**
+     * Runs `fn` as one undo step named `label`: every change it makes (strokes, fills, new layers) is
+     * undone together. Wet paint can't be grouped. Nested groups join the outer one. If `fn` throws,
+     * its changes are put back and nothing is recorded.
+     */
+    group<T>(label: string, fn: () => T): T;
+    /**
+     * What `fn` would paint, without changing anything: it runs on a new empty layer (above the
+     * active layer, another one, or at the bottom), and the layer's pixels and the picture with them
+     * come back while the document, history and listeners stay as they were. `fn` gets that layer's id and must paint on it with dry brushes (strokes, replays and
+     * fills); wet paint can't be previewed. For ghost paint an agent suggests (`createPaintProposals`).
+     */
+    previewPaint(fn: (layerId: string) => void, placement?: PaintPreviewPlacement): PaintPreview;
     private emit;
     /** A snapshot of the editor (the same object until something changes). */
     getState(): PaintEditorState;