@pixerate/editor 0.254.1 → 0.256.0

package/dist/image-editor/index.d.cts

@@ -73,3 +73,4 @@ export * from './paths.cjs';
 export * from './path-edit.cjs';
 export * from './content-aware-fill-session.cjs';
 export * from './stickers.cjs';
+export * from './brush-presets.cjs';

package/dist/image-editor/index.d.ts

@@ -73,3 +73,4 @@ export * from './paths.js';
 export * from './path-edit.js';
 export * from './content-aware-fill-session.js';
 export * from './stickers.js';
+export * from './brush-presets.js';

package/dist/image-editor/index.js

@@ -8,7 +8,7 @@ import {
   parseOpenTypeFont,
   removeAnchorsKeepingShape,
   traceField
-} from "../chunk-2ZJ4DT3M.js";
+} from "../chunk-VUKUTT2W.js";
 import {
   ColorGmm,
   GAMMA,
@@ -413,7 +413,7 @@ import {
   writePsd,
   xyToTempTint,
   xyToUv
-} from "../chunk-QC3OXRE4.js";
+} from "../chunk-DMTEQ6SH.js";
 import {
   parseCssColor
 } from "../chunk-3CI7FRMK.js";
@@ -743,8 +743,14 @@ import {
   warpMeshParamAt,
   warpMeshRows,
   warpPresetMesh
-} from "../chunk-GYMMNCFT.js";
-import "../chunk-MTKY6K3Q.js";
+} from "../chunk-AF23QK5F.js";
+import {
+  IMAGE_PROFILE,
+  checkBrush,
+  closest,
+  createBrushLibrary,
+  resolveBrush
+} from "../chunk-JVRLGV3C.js";
 import "../chunk-APX63ILU.js";
 import "../chunk-M6DNZNVY.js";
 import {
@@ -5742,6 +5748,32 @@ function convertSurfaceColors(surface, t) {
   return new TiledSurface(4, tiles, surface.defaultValue);
 }
 
+// src/image-editor/brush-presets.ts
+var ImageBrushPresetError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ImageBrushPresetError";
+  }
+};
+function imageBrushPreset(brush, ids = []) {
+  const check = checkBrush(brush, IMAGE_PROFILE);
+  if (!check.ok) {
+    const why = check.issues.filter((i) => i.severity === "error").map((i) => `${i.reason} ${i.fix}`).join(" ");
+    throw new ImageBrushPresetError(`Brush "${brush.id}" (${brush.name}) can't paint in the image editor: ${why}${ids.length ? ` ${closest(brush.id, ids)}list_brush_presets lists the ones it can.` : ""}`);
+  }
+  const resolved2 = resolveBrush(brush);
+  const tool = resolved2.engine === "eraser" ? "eraser" : resolved2.engine === "mixer" ? "mixer" : "brush";
+  return {
+    id: brush.id,
+    name: brush.name,
+    tool,
+    brush: { ...resolved2.tip },
+    ...tool === "mixer" ? { mixer: { ...resolved2.mixer } } : {},
+    ...resolved2.paint && tool === "brush" ? { paint: resolved2.paint } : {},
+    warnings: check.issues.filter((i) => i.severity === "warning").map((i) => i.reason)
+  };
+}
+
 // src/image-editor/controller.ts
 var IMAGE_EDITOR_SCHEMA_VERSION = LAYERED_SCHEMA_VERSION;
 var RETOUCH_TOOLS = ["clone", "heal", "spot-heal", "smudge", "dodge", "burn", "sponge", "blur", "sharpen", "history"];
@@ -6230,6 +6262,7 @@ var ImageEditorController = class {
   effectsEngine = new ImageEffectsEngine({ slot: this.effects });
   effectRefresh = "none";
   constructor(options = {}) {
+    this.brushLibrary = options.brushLibrary ?? createBrushLibrary();
     this.effects.subscribe(() => this.queueEffectRefresh("all"));
     this.effectsEngine.subscribe(() => this.queueEffectRefresh("incomplete"));
     if (options.effects) this.effects.set(options.effects);
@@ -9008,6 +9041,34 @@ var ImageEditorController = class {
     return pngDataUrl(thumb.width, thumb.height, thumb.data, 4);
   }
   // --- Painting ---
+  /** The brush library the brush presets come from (shared with other editors when the host passes one). */
+  brushLibrary;
+  /** The brushes this editor can paint with (`IMAGE_PROFILE`): built-in presets, then saved brushes. */
+  async listBrushPresets() {
+    return this.brushLibrary.list({ profile: IMAGE_PROFILE });
+  }
+  /**
+   * Paints with a brush from the brush library: sets the paint tool it needs (brush, Mixer Brush
+   * or eraser), its brush and mixer settings and, for a brush with its own gradient, the paint.
+   * View state, no undo. Throws for an unknown id (with the closest ones) or a brush the image
+   * editor can't paint (wet, thick, particles, stickers, light), saying why.
+   */
+  async setBrushPreset(id) {
+    const entry = await this.brushLibrary.get(id);
+    const ids = (await this.listBrushPresets()).map((e) => e.brush.id);
+    if (!entry) throw new LayerOperationError(`Unknown brush "${id}". ${closest(id, ids)}list_brush_presets lists the brushes the image editor can paint with.`);
+    let preset;
+    try {
+      preset = imageBrushPreset(entry.brush, ids);
+    } catch (e) {
+      throw new LayerOperationError(e.message);
+    }
+    this.setPaintOptions({ brush: preset.brush, ...preset.mixer ? { mixer: preset.mixer } : {}, ...preset.paint ? { paint: preset.paint } : {} });
+    this.state.paint = { ...this.state.paint, brushPreset: preset.id };
+    if (this.state.activeTool !== preset.tool) this.setTool(preset.tool);
+    else this.notify();
+    return preset;
+  }
   /** Brush settings, colours and tool options of the paint tools (view state, no undo). */
   setPaintOptions(options) {
     const cur = this.state.paint;
@@ -9022,6 +9083,8 @@ var ImageEditorController = class {
     }
     if (source.type === "color" || options.foreground !== void 0) source = { type: "color", color: foreground };
     const next = {
+      // Brush settings changed by hand are no longer the preset's.
+      brushPreset: options.brush || options.mixer ? null : cur.brushPreset ?? null,
       brush: options.brush ? normalizeBrush({ ...cur.brush, ...options.brush }) : cur.brush,
       foreground,
       background: options.background !== void 0 ? toHex(parseColor(options.background)) : cur.background,
@@ -13625,7 +13688,7 @@ var DEPTH_MASK_CONTROLS = [
 
 // src/image-editor/playback.ts
 var IMAGE_PLAYBACK_KIND = "layer";
-var PAINT = /^(paint_stroke|clone_stamp|heal_brush|spot_heal|dodge|burn|sponge|smudge|blur_stroke|sharpen_stroke|history_brush|set_clone_source|set_clone_transform|fill_pixels|clear_pixels|set_paint|sample_color|set_retouch_options|load_mixer_brush|clean_mixer_brush)$/;
+var PAINT = /^(paint_stroke|clone_stamp|heal_brush|spot_heal|dodge|burn|sponge|smudge|blur_stroke|sharpen_stroke|history_brush|set_clone_source|set_clone_transform|fill_pixels|clear_pixels|set_paint|sample_color|set_retouch_options|load_mixer_brush|clean_mixer_brush|set_brush_preset)$/;
 var SELECT = /^(make_work_path|add_path|set_path_geometry|rename_path|duplicate_path|delete_path|fill_path|stroke_path|select_region|select_subject|select_by_color|select_all|deselect|invert_selection|select_rect|select_ellipse|select_polygon|quick_select|select_object|select_focus_area|select_sky|select_line|magic_wand|grow_selection|select_similar|reselect|select_layer_transparency|select_color_range|load_selection_from_image|load_selection_from_mask|set_selection_display|modify_selection|refine_selection|transform_selection|apply_selection_as_mask|layer_via_copy|stroke_selection|content_aware_fill|copy_pixels|cut_pixels|paste_pixels|save_selection|load_selection_from_channel|set_channel_properties|duplicate_channel|delete_channel|load_channel_from_image|set_quick_mask|path_to_selection|select_text_shape|compare_selections|edit_selection_step|insert_selection_step|remove_selection_step|freeze_selection|separate_subject)$/;
 var ANNOTATE = /^(add_shape_layer|update_shape|add_shape_component|set_shape_component|remove_shape_component|merge_shape_components|add_text_layer|set_text|set_text_style|set_paragraph_style|set_text_frame|set_text_orientation|convert_text_to_shape)$/;
 var CROP = /^(set_crop|crop_to_selection|reset_crop|set_rotation|flip_image|transform_layer|warp_layer|flip_layer|offset_layer)$/;
@@ -17191,7 +17254,7 @@ function createImagePaintTools(controller) {
   };
   const paintView = () => {
     const p = controller.getState().paint;
-    return { paint: p.paint, foreground: p.foreground, background: p.background, brush: p.brush };
+    return { paint: p.paint, foreground: p.foreground, background: p.background, brush: p.brush, brushPreset: p.brushPreset ?? null };
   };
   const setPaint = {
     name: "set_paint",
@@ -17207,7 +17270,7 @@ function createImagePaintTools(controller) {
   const getPaint = {
     name: "get_paint",
     title: "Get the paint",
-    description: "Reads what the brush paints (paint: the foreground colour or gradient paint), the foreground and background colours and the brush settings (size, hardness, spacing, opacity, flow \u2026). Changes nothing.",
+    description: "Reads what the brush paints (paint: the foreground colour or gradient paint), the foreground and background colours, the brush settings (size, hardness, spacing, opacity, flow \u2026) and brushPreset (the set_brush_preset id they came from, null once changed by hand). Changes nothing.",
     inputSchema: { type: "object", properties: {}, additionalProperties: false },
     annotations: { title: "Get the paint", ...READ3 },
     handler: () => paintView()
@@ -17277,7 +17340,15 @@ function createImagePaintTools(controller) {
       return { gradient, css: gradientToCss(gradient), pointsRead: read };
     }
   };
-  return [paintStroke, fill, clear, getMixer, loadMixerTool, cleanMixerTool, setPaint, getPaint, sampleColor2, sampleGradient];
+  const setBrushPreset = {
+    name: "set_brush_preset",
+    title: "Paint with a brush preset",
+    description: "Chooses a brush from the brush library (a built-in preset or a saved brush; list_brush_presets lists the ones the image editor can paint, describe_brush reads one) for the brush tools: it sets the paint tool the brush needs (brush, mixer for a Mixer Brush, eraser), its brush settings (size, hardness, spacing, angle, roundness, opacity, flow, smoothing, pressure, blend), its Mixer Brush settings and, for a brush with its own gradient, the paint. paint_stroke with that tool then paints with it. Brushes the image editor cannot paint (wet or thick paint, particles, stickers, light, the wet tools) are refused with the reason. View state, not an undo step. Returns the id, name, tool, brush, mixer, paint and warnings (settings it paints without, such as paper grain).",
+    inputSchema: { type: "object", properties: { id: { type: "string", minLength: 1, maxLength: 64, description: 'Brush id from list_brush_presets (e.g. "pencil-hb", "marker", "mixer-brush", "eraser-soft").' } }, required: ["id"], additionalProperties: false },
+    annotations: { title: "Paint with a brush preset", ...SET },
+    handler: async ({ id }) => controller.setBrushPreset(id)
+  };
+  return [paintStroke, fill, clear, getMixer, loadMixerTool, cleanMixerTool, setPaint, getPaint, sampleColor2, sampleGradient, setBrushPreset];
 }
 
 // src/image-editor/color-tools.ts
@@ -22616,6 +22687,7 @@ export {
   INTENTS,
   INTENT_OPTIONS,
   INTERPOLATIONS,
+  ImageBrushPresetError,
   ImageEditorController,
   ImageEditorRenderer,
   ImageEffectsEngine,
@@ -23127,6 +23199,7 @@ export {
   identityLevels,
   identityTransform,
   identityWarpMesh,
+  imageBrushPreset,
   imageEditorStateMigrations,
   imageLayerAppliedEffects,
   imagePanelTool,

package/dist/image-editor/types.d.cts

@@ -9,6 +9,7 @@ import type { ImageLayer, LayerTarget } from './layers/model.cjs';
 import type { SerializedLayeredImageEditorState } from './layers/serialize.cjs';
 import type { PaintOptions } from './controller.cjs';
 import type { TextShaper } from './layers/text.cjs';
+import type { BrushLibrary } from '../brushes/library.cjs';
 export interface ImageDimensions {
     width: number;
     height: number;
@@ -452,6 +453,12 @@ export interface ExportOptions {
 import type { EffectProvider } from '../effects/types.cjs';
 import type { SegmentationProvider } from './selection/segmentation.cjs';
 export interface ImageEditorOptions {
+    /**
+     * The brush library the brush presets come from (`setBrushPreset`): built-in presets and saved
+     * brushes, filtered by `IMAGE_PROFILE`. Share one with the paint editor so a brush saved there
+     * paints here (default: a library in memory).
+     */
+    brushLibrary?: BrushLibrary;
     /**
      * What lays out and draws type layers. Default: the browser's fonts through Canvas 2D
      * (`createCanvasTextShaper`) where there is a 2D canvas; `null` (or no canvas) keeps type layers'

package/dist/image-editor/types.d.ts

@@ -9,6 +9,7 @@ import type { ImageLayer, LayerTarget } from './layers/model.js';
 import type { SerializedLayeredImageEditorState } from './layers/serialize.js';
 import type { PaintOptions } from './controller.js';
 import type { TextShaper } from './layers/text.js';
+import type { BrushLibrary } from '../brushes/library.js';
 export interface ImageDimensions {
     width: number;
     height: number;
@@ -452,6 +453,12 @@ export interface ExportOptions {
 import type { EffectProvider } from '../effects/types.js';
 import type { SegmentationProvider } from './selection/segmentation.js';
 export interface ImageEditorOptions {
+    /**
+     * The brush library the brush presets come from (`setBrushPreset`): built-in presets and saved
+     * brushes, filtered by `IMAGE_PROFILE`. Share one with the paint editor so a brush saved there
+     * paints here (default: a library in memory).
+     */
+    brushLibrary?: BrushLibrary;
     /**
      * What lays out and draws type layers. Default: the browser's fonts through Canvas 2D
      * (`createCanvasTextShaper`) where there is a 2D canvas; `null` (or no canvas) keeps type layers'

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

@@ -0,0 +1,19 @@
+/**
+ * Agent tools for paint proposals: `propose_paint`, `list_paint_proposals`,
+ * `accept_paint_proposal` and `reject_paint_proposal`. An agent suggests paint as a ghost the user
+ * can take or leave, instead of painting it outright. They drive a {@link PaintProposals} store.
+ */
+import type { AgentToolProvider } from '../tools/registry.cjs';
+import type { PaintProposals } from './collaboration.cjs';
+export interface PaintProposalToolProviderOptions {
+    /** Provider id (unique per registry). Default `paint-proposals`. */
+    id?: string;
+    /** Tool-name prefix (`<namespace>__<name>`); defaults to the provider id, `''` for bare names. */
+    namespace?: string;
+    /** Accepting is not allowed: `accept_paint_proposal` refuses with this reason (a sentence). */
+    readOnly?: boolean | string | (() => boolean | string);
+    /** Origin of proposals from calls that name no actor (default the store's). */
+    fallbackOrigin?: string;
+}
+/** The proposal tools for a paint editor (see the module comment). */
+export declare function createPaintProposalToolProvider(proposals: PaintProposals, options?: PaintProposalToolProviderOptions): AgentToolProvider;

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

@@ -0,0 +1,19 @@
+/**
+ * Agent tools for paint proposals: `propose_paint`, `list_paint_proposals`,
+ * `accept_paint_proposal` and `reject_paint_proposal`. An agent suggests paint as a ghost the user
+ * can take or leave, instead of painting it outright. They drive a {@link PaintProposals} store.
+ */
+import type { AgentToolProvider } from '../tools/registry.js';
+import type { PaintProposals } from './collaboration.js';
+export interface PaintProposalToolProviderOptions {
+    /** Provider id (unique per registry). Default `paint-proposals`. */
+    id?: string;
+    /** Tool-name prefix (`<namespace>__<name>`); defaults to the provider id, `''` for bare names. */
+    namespace?: string;
+    /** Accepting is not allowed: `accept_paint_proposal` refuses with this reason (a sentence). */
+    readOnly?: boolean | string | (() => boolean | string);
+    /** Origin of proposals from calls that name no actor (default the store's). */
+    fallbackOrigin?: string;
+}
+/** The proposal tools for a paint editor (see the module comment). */
+export declare function createPaintProposalToolProvider(proposals: PaintProposals, options?: PaintProposalToolProviderOptions): AgentToolProvider;

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;