@pixerate/editor 0.255.0 → 0.257.0

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

@@ -0,0 +1,180 @@
+/**
+ * Painting alongside an agent: a change feed that says what the user (or an agent) just painted,
+ * and proposals, the paint an agent suggests without painting it. A proposal is a few operations
+ * (strokes, a wash, an echo of strokes already on the canvas) that `previewPaint` renders as a
+ * ghost the user sees over the canvas; accepting paints them as one undo step recorded as the
+ * proposer's, on a layer of their own, and dismissing changes nothing. The canvas equivalents are
+ * `createCanvasChangeFeed` and `createCanvasProposals`.
+ */
+import type { RasterRect } from '../raster/surface.cjs';
+import { type PaintCommitEvent, type PaintEditorController } from './controller.cjs';
+import type { PaintEvent } from './document.cjs';
+import type { RecordedStroke } from './strokes.cjs';
+/** A layer as the feed reports it. */
+export interface PaintChangeLayer {
+    id: string;
+    name: string;
+}
+/** What changed in the painting since the feed's last report. */
+export interface PaintChange {
+    /** Counts up from 1 for each change reported. */
+    seq: number;
+    /** `user`, or `agent:<id>` when an agent's step made it (see `PaintEditorController.withOrigin`). */
+    origin: string;
+    /** The history step behind it, when there was one. */
+    commit?: PaintCommitEvent;
+    addedStrokes: RecordedStroke[];
+    removedStrokes: RecordedStroke[];
+    /** Fills, clears and other recorded operations that aren't strokes. */
+    events: PaintEvent[];
+    addedLayers: PaintChangeLayer[];
+    removedLayers: PaintChangeLayer[];
+    /** Layers whose name, visibility, opacity or blend changed, with the fields. */
+    changedLayers: (PaintChangeLayer & {
+        fields: string[];
+    })[];
+    /** A stroke is being painted: more of the same gesture will follow. */
+    inGesture: boolean;
+    /** A stroke started since the last report (reported even when nothing else changed). */
+    gestureStarted?: true;
+    /** The stroke in progress ended (reported even when it painted nothing). */
+    gestureEnded?: true;
+    /** Milliseconds since the epoch. */
+    at: number;
+}
+export interface PaintChangeFeed {
+    /** Compares the painting with the last snapshot and reports the change, if any. Runs on every controller change. */
+    check(): PaintChange | null;
+    subscribe(listener: (change: PaintChange) => void): () => void;
+    /** Takes a new snapshot without reporting the difference (e.g. after opening a document). */
+    reset(): void;
+    dispose(): void;
+}
+/**
+ * What changed in a painting, after each controller change: strokes added or removed (undo
+ * included), fills and clears, layers added, removed or changed, and the start and end of each
+ * stroke, tagged with who made it. Agents that paint alongside the user read it.
+ */
+export declare function createPaintChangeFeed(controller: PaintEditorController, options?: {
+    now?: () => number;
+}): PaintChangeFeed;
+/** A stroke to paint: pen samples in document pixels. */
+export interface PaintProposalStrokeOp {
+    kind: 'stroke';
+    points: {
+        x: number;
+        y: number;
+        pressure?: number;
+    }[];
+    /** A dry brush from the library (default the editor's brush). */
+    brushId?: string;
+    /** #rrggbb (default the editor colour). */
+    color?: string;
+    /** Brush size in document pixels (default the brush's). */
+    size?: number;
+}
+/** A wash over the suggestion's whole layer, like a ground or a glaze. */
+export interface PaintProposalWashOp {
+    kind: 'wash';
+    color: string;
+    /** 0..1 (default 0.35). */
+    opacity?: number;
+    /** Paper grain response 0..1 (default 0.4). */
+    grain?: number;
+}
+/** Strokes already on the canvas, painted again moved, turned, scaled or mirrored. */
+export interface PaintProposalEchoOp {
+    kind: 'echo';
+    strokeIds: string[];
+    dx?: number;
+    dy?: number;
+    /** Degrees clockwise about the strokes' centre (default 0). */
+    rotate?: number;
+    scale?: number;
+    flipX?: boolean;
+    /** Repeat the move this many times, each on top of the last (default 1). */
+    repeat?: number;
+    /** Recolour (default each stroke's colour). */
+    color?: string;
+}
+export type PaintProposalOp = PaintProposalStrokeOp | PaintProposalWashOp | PaintProposalEchoOp;
+/** Where accepted paint goes: a new layer of its own (above a layer, on top, or at the bottom, behind everything). */
+export interface PaintProposalPlacement {
+    /** Default `top`. `above` needs `layerId`. */
+    place?: 'top' | 'bottom' | 'above';
+    layerId?: string;
+    /** The new layer's name (default the proposal's title). */
+    layerName?: string;
+}
+export interface PaintProposalInput extends PaintProposalPlacement {
+    /** What the suggestion adds, in a few words. Also the undo step's name once accepted. */
+    title: string;
+    /** Why it fits what the user is doing, in a sentence. */
+    rationale?: string;
+    /** Who suggests it (`agent:<id>`); defaults to the store's `origin`. */
+    origin?: string;
+    ops: PaintProposalOp[];
+}
+export interface PaintProposal {
+    id: string;
+    title: string;
+    rationale?: string;
+    origin: string;
+    ops: PaintProposalOp[];
+    placement: PaintProposalPlacement;
+    /** Where the ghost sits (document pixels), or `null` when it painted nothing. */
+    bounds: RasterRect | null;
+    /** The ghost: the picture as it would look, inside `bounds` (straight RGBA). */
+    ghost: Uint8ClampedArray;
+    /** Strokes on the canvas it builds on (echo ops). */
+    anchors: string[];
+    createdAt: number;
+}
+export interface PaintProposalAcceptResult {
+    proposalId: string;
+    layerId: string;
+    /** The strokes it painted. */
+    strokeIds: string[];
+    /** The undo step's name. */
+    label: string;
+}
+export interface PaintProposalsState {
+    proposals: readonly PaintProposal[];
+}
+export interface PaintProposals {
+    getState(): PaintProposalsState;
+    subscribe(listener: (state: PaintProposalsState) => void): () => void;
+    /** Validates and previews a suggestion, and adds it to the pending list. Throws, changing nothing, when it can't be painted. */
+    propose(input: PaintProposalInput): PaintProposal;
+    /** Paints a pending proposal as one undo step recorded as the proposer's. The active layer stays the user's. */
+    accept(id: string): PaintProposalAcceptResult;
+    /** Drops a pending proposal; the painting is unchanged. */
+    reject(id: string): PaintProposal;
+    /** Drops every pending proposal (or those of one origin). Returns the ids dropped. */
+    clear(origin?: string): string[];
+    get(id: string): PaintProposal | undefined;
+    /** Strokes an echo builds on that are no longer on the canvas (it can't be accepted until re-proposed). */
+    missing(id: string): string[];
+}
+export interface PaintProposalsOptions {
+    controller: PaintEditorController;
+    /** Origin of proposals that name none (default `agent:anonymous`). */
+    origin?: string;
+    /** The most points one proposal may paint (default 4000). */
+    maxPoints?: number;
+    now?: () => number;
+    idGenerator?: () => string;
+}
+/** A store of paint an agent suggests (see the module comment). */
+export declare function createPaintProposals(options: PaintProposalsOptions): PaintProposals;
+/**
+ * Where to draw a proposal's ghost and its pixels, for a canvas element placed at `bounds` in
+ * document pixels (`new ImageData(data, width, height)`), or `null` when it paints nothing.
+ */
+export declare function paintProposalGhost(proposal: PaintProposal): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    data: Uint8ClampedArray;
+} | null;

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

@@ -0,0 +1,180 @@
+/**
+ * Painting alongside an agent: a change feed that says what the user (or an agent) just painted,
+ * and proposals, the paint an agent suggests without painting it. A proposal is a few operations
+ * (strokes, a wash, an echo of strokes already on the canvas) that `previewPaint` renders as a
+ * ghost the user sees over the canvas; accepting paints them as one undo step recorded as the
+ * proposer's, on a layer of their own, and dismissing changes nothing. The canvas equivalents are
+ * `createCanvasChangeFeed` and `createCanvasProposals`.
+ */
+import type { RasterRect } from '../raster/surface.js';
+import { type PaintCommitEvent, type PaintEditorController } from './controller.js';
+import type { PaintEvent } from './document.js';
+import type { RecordedStroke } from './strokes.js';
+/** A layer as the feed reports it. */
+export interface PaintChangeLayer {
+    id: string;
+    name: string;
+}
+/** What changed in the painting since the feed's last report. */
+export interface PaintChange {
+    /** Counts up from 1 for each change reported. */
+    seq: number;
+    /** `user`, or `agent:<id>` when an agent's step made it (see `PaintEditorController.withOrigin`). */
+    origin: string;
+    /** The history step behind it, when there was one. */
+    commit?: PaintCommitEvent;
+    addedStrokes: RecordedStroke[];
+    removedStrokes: RecordedStroke[];
+    /** Fills, clears and other recorded operations that aren't strokes. */
+    events: PaintEvent[];
+    addedLayers: PaintChangeLayer[];
+    removedLayers: PaintChangeLayer[];
+    /** Layers whose name, visibility, opacity or blend changed, with the fields. */
+    changedLayers: (PaintChangeLayer & {
+        fields: string[];
+    })[];
+    /** A stroke is being painted: more of the same gesture will follow. */
+    inGesture: boolean;
+    /** A stroke started since the last report (reported even when nothing else changed). */
+    gestureStarted?: true;
+    /** The stroke in progress ended (reported even when it painted nothing). */
+    gestureEnded?: true;
+    /** Milliseconds since the epoch. */
+    at: number;
+}
+export interface PaintChangeFeed {
+    /** Compares the painting with the last snapshot and reports the change, if any. Runs on every controller change. */
+    check(): PaintChange | null;
+    subscribe(listener: (change: PaintChange) => void): () => void;
+    /** Takes a new snapshot without reporting the difference (e.g. after opening a document). */
+    reset(): void;
+    dispose(): void;
+}
+/**
+ * What changed in a painting, after each controller change: strokes added or removed (undo
+ * included), fills and clears, layers added, removed or changed, and the start and end of each
+ * stroke, tagged with who made it. Agents that paint alongside the user read it.
+ */
+export declare function createPaintChangeFeed(controller: PaintEditorController, options?: {
+    now?: () => number;
+}): PaintChangeFeed;
+/** A stroke to paint: pen samples in document pixels. */
+export interface PaintProposalStrokeOp {
+    kind: 'stroke';
+    points: {
+        x: number;
+        y: number;
+        pressure?: number;
+    }[];
+    /** A dry brush from the library (default the editor's brush). */
+    brushId?: string;
+    /** #rrggbb (default the editor colour). */
+    color?: string;
+    /** Brush size in document pixels (default the brush's). */
+    size?: number;
+}
+/** A wash over the suggestion's whole layer, like a ground or a glaze. */
+export interface PaintProposalWashOp {
+    kind: 'wash';
+    color: string;
+    /** 0..1 (default 0.35). */
+    opacity?: number;
+    /** Paper grain response 0..1 (default 0.4). */
+    grain?: number;
+}
+/** Strokes already on the canvas, painted again moved, turned, scaled or mirrored. */
+export interface PaintProposalEchoOp {
+    kind: 'echo';
+    strokeIds: string[];
+    dx?: number;
+    dy?: number;
+    /** Degrees clockwise about the strokes' centre (default 0). */
+    rotate?: number;
+    scale?: number;
+    flipX?: boolean;
+    /** Repeat the move this many times, each on top of the last (default 1). */
+    repeat?: number;
+    /** Recolour (default each stroke's colour). */
+    color?: string;
+}
+export type PaintProposalOp = PaintProposalStrokeOp | PaintProposalWashOp | PaintProposalEchoOp;
+/** Where accepted paint goes: a new layer of its own (above a layer, on top, or at the bottom, behind everything). */
+export interface PaintProposalPlacement {
+    /** Default `top`. `above` needs `layerId`. */
+    place?: 'top' | 'bottom' | 'above';
+    layerId?: string;
+    /** The new layer's name (default the proposal's title). */
+    layerName?: string;
+}
+export interface PaintProposalInput extends PaintProposalPlacement {
+    /** What the suggestion adds, in a few words. Also the undo step's name once accepted. */
+    title: string;
+    /** Why it fits what the user is doing, in a sentence. */
+    rationale?: string;
+    /** Who suggests it (`agent:<id>`); defaults to the store's `origin`. */
+    origin?: string;
+    ops: PaintProposalOp[];
+}
+export interface PaintProposal {
+    id: string;
+    title: string;
+    rationale?: string;
+    origin: string;
+    ops: PaintProposalOp[];
+    placement: PaintProposalPlacement;
+    /** Where the ghost sits (document pixels), or `null` when it painted nothing. */
+    bounds: RasterRect | null;
+    /** The ghost: the picture as it would look, inside `bounds` (straight RGBA). */
+    ghost: Uint8ClampedArray;
+    /** Strokes on the canvas it builds on (echo ops). */
+    anchors: string[];
+    createdAt: number;
+}
+export interface PaintProposalAcceptResult {
+    proposalId: string;
+    layerId: string;
+    /** The strokes it painted. */
+    strokeIds: string[];
+    /** The undo step's name. */
+    label: string;
+}
+export interface PaintProposalsState {
+    proposals: readonly PaintProposal[];
+}
+export interface PaintProposals {
+    getState(): PaintProposalsState;
+    subscribe(listener: (state: PaintProposalsState) => void): () => void;
+    /** Validates and previews a suggestion, and adds it to the pending list. Throws, changing nothing, when it can't be painted. */
+    propose(input: PaintProposalInput): PaintProposal;
+    /** Paints a pending proposal as one undo step recorded as the proposer's. The active layer stays the user's. */
+    accept(id: string): PaintProposalAcceptResult;
+    /** Drops a pending proposal; the painting is unchanged. */
+    reject(id: string): PaintProposal;
+    /** Drops every pending proposal (or those of one origin). Returns the ids dropped. */
+    clear(origin?: string): string[];
+    get(id: string): PaintProposal | undefined;
+    /** Strokes an echo builds on that are no longer on the canvas (it can't be accepted until re-proposed). */
+    missing(id: string): string[];
+}
+export interface PaintProposalsOptions {
+    controller: PaintEditorController;
+    /** Origin of proposals that name none (default `agent:anonymous`). */
+    origin?: string;
+    /** The most points one proposal may paint (default 4000). */
+    maxPoints?: number;
+    now?: () => number;
+    idGenerator?: () => string;
+}
+/** A store of paint an agent suggests (see the module comment). */
+export declare function createPaintProposals(options: PaintProposalsOptions): PaintProposals;
+/**
+ * Where to draw a proposal's ghost and its pixels, for a canvas element placed at `bounds` in
+ * document pixels (`new ImageData(data, width, height)`), or `null` when it paints nothing.
+ */
+export declare function paintProposalGhost(proposal: PaintProposal): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    data: Uint8ClampedArray;
+} | null;

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

@@ -22,6 +22,7 @@ import { type PaintBrushInput, type PaintBrush } from './brushes.cjs';
 import { type BrushLibrary, type BrushLibraryFile } from '../brushes/library.cjs';
 import { type BrushPatch, type UnsettableBrushFacet } from '../brushes/patch.cjs';
 import type { Brush } from '../brushes/types.cjs';
+import type { ColorScheme } from '../color/dual.cjs';
 import { type PaintCanvas, type PaintDocumentState, type PaintLayer } from './document.cjs';
 import { type ImageEncoder, type ImageFormat } from './encode.cjs';
 import type { PenPoint } from './engine.cjs';
@@ -67,6 +68,11 @@ export interface PaintEditorOptions extends Partial<PaintCanvas> {
     brushLibrary?: BrushLibrary;
     /** Saved user brushes to start the default library with (or to add to `brushLibrary`). */
     brushes?: readonly PaintBrush[];
+    /**
+     * The host's colour scheme (default `light`): a brush's light / dark default colour resolves to
+     * its side when the brush is chosen and when a stroke starts. Follow the host with `setColorScheme`.
+     */
+    colorScheme?: ColorScheme;
     /** Paint colour #rrggbb (default #1f2937). */
     color?: string;
     hand?: Hand;
@@ -114,6 +120,10 @@ export interface PaintEditorState {
     brushes: readonly PaintBrush[];
     /** Paint colour #rrggbb. */
     color: string;
+    /** The colour scheme light / dark brush colours resolve for. */
+    colorScheme: ColorScheme;
+    /** Locked: choosing a brush with a default colour keeps the paint colour. */
+    colorLocked: boolean;
     /** The second colour (swap with `swapColors`). */
     secondaryColor: string;
     /**
@@ -194,6 +204,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 +370,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 +433,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;
@@ -771,6 +835,25 @@ export declare class PaintEditorController {
         height?: number;
         color?: string;
     }): BrushThumbnail;
+    private colorScheme;
+    private colorLocked;
+    /** The brush default colour the paint colour came from (resolved again when the scheme changes), or `null`. */
+    private brushColour;
+    /**
+     * The host's colour scheme: a paint colour that came from a brush's light / dark default
+     * resolves to the new side. Editor state, not an undo step.
+     */
+    setColorScheme(scheme: ColorScheme): void;
+    /** Locks the paint colour: choosing a brush with a default colour keeps it. Editor state, not an undo step. */
+    setColorLocked(locked: boolean): void;
+    /**
+     * After the user chooses a brush: its solid or light / dark default colour becomes the paint
+     * colour (resolved for the colour scheme), unless the colour is locked. Gradient defaults are the
+     * brush's own paint already; effect defaults stay a suggestion.
+     */
+    private takeBrushColour;
+    /** A brush that always paints its own colour (`colour.own`): that colour, resolved for the scheme now; else `null`. */
+    private ownColour;
     /** Sets the paint colour (and goes back to one colour from gradient paint). */
     setColor(color: string): string;
     /**

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

@@ -22,6 +22,7 @@ import { type PaintBrushInput, type PaintBrush } from './brushes.js';
 import { type BrushLibrary, type BrushLibraryFile } from '../brushes/library.js';
 import { type BrushPatch, type UnsettableBrushFacet } from '../brushes/patch.js';
 import type { Brush } from '../brushes/types.js';
+import type { ColorScheme } from '../color/dual.js';
 import { type PaintCanvas, type PaintDocumentState, type PaintLayer } from './document.js';
 import { type ImageEncoder, type ImageFormat } from './encode.js';
 import type { PenPoint } from './engine.js';
@@ -67,6 +68,11 @@ export interface PaintEditorOptions extends Partial<PaintCanvas> {
     brushLibrary?: BrushLibrary;
     /** Saved user brushes to start the default library with (or to add to `brushLibrary`). */
     brushes?: readonly PaintBrush[];
+    /**
+     * The host's colour scheme (default `light`): a brush's light / dark default colour resolves to
+     * its side when the brush is chosen and when a stroke starts. Follow the host with `setColorScheme`.
+     */
+    colorScheme?: ColorScheme;
     /** Paint colour #rrggbb (default #1f2937). */
     color?: string;
     hand?: Hand;
@@ -114,6 +120,10 @@ export interface PaintEditorState {
     brushes: readonly PaintBrush[];
     /** Paint colour #rrggbb. */
     color: string;
+    /** The colour scheme light / dark brush colours resolve for. */
+    colorScheme: ColorScheme;
+    /** Locked: choosing a brush with a default colour keeps the paint colour. */
+    colorLocked: boolean;
     /** The second colour (swap with `swapColors`). */
     secondaryColor: string;
     /**
@@ -194,6 +204,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 +370,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 +433,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;
@@ -771,6 +835,25 @@ export declare class PaintEditorController {
         height?: number;
         color?: string;
     }): BrushThumbnail;
+    private colorScheme;
+    private colorLocked;
+    /** The brush default colour the paint colour came from (resolved again when the scheme changes), or `null`. */
+    private brushColour;
+    /**
+     * The host's colour scheme: a paint colour that came from a brush's light / dark default
+     * resolves to the new side. Editor state, not an undo step.
+     */
+    setColorScheme(scheme: ColorScheme): void;
+    /** Locks the paint colour: choosing a brush with a default colour keeps it. Editor state, not an undo step. */
+    setColorLocked(locked: boolean): void;
+    /**
+     * After the user chooses a brush: its solid or light / dark default colour becomes the paint
+     * colour (resolved for the colour scheme), unless the colour is locked. Gradient defaults are the
+     * brush's own paint already; effect defaults stay a suggestion.
+     */
+    private takeBrushColour;
+    /** A brush that always paints its own colour (`colour.own`): that colour, resolved for the scheme now; else `null`. */
+    private ownColour;
     /** Sets the paint colour (and goes back to one colour from gradient paint). */
     setColor(color: string): string;
     /**

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

@@ -18,6 +18,7 @@ import { CoverageMap, type BrushSettings, type Dab, type StrokePoint } from '../
 import type { RasterRect } from '../raster/surface.cjs';
 import type { PaintBrush } from './brushes.cjs';
 import { type EffectPaintPixels } from './effect-paint.cjs';
+import type { StickerArtLookup } from './sticker-art.cjs';
 import { type PaperGrain } from './paper.cjs';
 /** One pen sample in document pixels. Every channel but x and y is optional. */
 export interface PenPoint {
@@ -126,6 +127,8 @@ export interface DryStrokeOptions {
     copies?: readonly StrokeCopy[];
     /** Effect paint: each pixel takes its colour (and alpha) from these canvas-sized pixels. */
     effect?: EffectPaintPixels | null;
+    /** Loaded sticker art, for a stamp tip of a sticker from the sticker library (`brush.stamp`); without it such a tip paints round. */
+    stampArt?: StickerArtLookup;
 }
 /**
  * One dab-engine stroke (dab and eraser brushes): smoothing, the dab walk of every copy, grain and
@@ -144,12 +147,16 @@ export declare class DryStroke {
     private field;
     private lastRaw;
     private lastFed;
+    /** The stamp tip's shape, or `null` for the round computed tip. */
+    private readonly stamp;
     constructor(brush: PaintBrush, options: DryStrokeOptions);
     /** Feeds raw pen samples; returns the document rectangles the new dabs touched. */
     push(points: readonly PenPoint[]): RasterRect[];
     /** Ends the stroke: the smoothed path catches up with the last raw sample; a single tap paints one dab. */
     finish(): RasterRect[];
     private paint;
+    /** Lays one mark (a dab, or a spray droplet of dab `d`): the round tip or the stamp, the paper grain, effect paint. */
+    private mark;
 }
 /** The shared engine's tip for the Mixer Brush engine (it smooths and walks by itself, so smoothing is applied before). */
 export declare function mixerTip(brush: PaintBrush): BrushSettings;