@pixerate/editor 0.266.1 → 0.267.0

package/dist/tools/index.js

@@ -1,8 +1,10 @@
 import {
   CONFORMANCE_BINARY_MIN_LENGTH,
+  CONFORMANCE_NUMBER_TOLERANCE,
   ConformanceIds,
   callEvalTool,
   conformanceResult,
+  conformanceValuesMatch,
   createOriginMiddleware,
   createStyleResolver,
   createStyleToolProvider,
@@ -21,7 +23,7 @@ import {
   runToolScript,
   toolResultError,
   toolResultValue
-} from "../chunk-ZQI3WUPP.js";
+} from "../chunk-QCLY5SFS.js";
 import {
   JSON_RPC_ERRORS,
   MCP_PROTOCOL_VERSIONS,
@@ -121,6 +123,7 @@ export {
   CAPTURE_EXCLUDE_SELECTOR,
   CAPTURE_OVERLAY_SELECTORS,
   CONFORMANCE_BINARY_MIN_LENGTH,
+  CONFORMANCE_NUMBER_TOLERANCE,
   ConformanceIds,
   EDITOR_CANVAS_TOOLS,
   EDITOR_MCP_TOOLS,
@@ -161,6 +164,7 @@ export {
   captureOutputSize,
   cloneElementWithStyles,
   conformanceResult,
+  conformanceValuesMatch,
   connectToolBridge,
   createAgentPlayback,
   createCaptureTool,

package/dist/vector/backdrop.d.cts

@@ -0,0 +1,13 @@
+import type { RasterRect } from '../raster/surface.cjs';
+import { type VectorPaintDef } from './gradient.cjs';
+import type { VectorRenderNode } from './render.cjs';
+import type { VectorMatrix } from './types.cjs';
+type M = VectorMatrix;
+/** An SVG `transform` attribute (`matrix`, `translate`, `scale`, `rotate`, in order) as a matrix. */
+export declare function parseVectorTransform(value: string | undefined): M;
+/**
+ * The render data's `nodes` (document space) drawn over `rect` (pixels) through `toPixels`, the
+ * map from document space to those pixels: straight-alpha RGBA, `rect.width × rect.height`.
+ */
+export declare function rasterizeVectorBackdrop(nodes: readonly VectorRenderNode[], defs: readonly VectorPaintDef[], toPixels: VectorMatrix, rect: RasterRect): Uint8ClampedArray;
+export {};

package/dist/vector/backdrop.d.ts

@@ -0,0 +1,13 @@
+import type { RasterRect } from '../raster/surface.js';
+import { type VectorPaintDef } from './gradient.js';
+import type { VectorRenderNode } from './render.js';
+import type { VectorMatrix } from './types.js';
+type M = VectorMatrix;
+/** An SVG `transform` attribute (`matrix`, `translate`, `scale`, `rotate`, in order) as a matrix. */
+export declare function parseVectorTransform(value: string | undefined): M;
+/**
+ * The render data's `nodes` (document space) drawn over `rect` (pixels) through `toPixels`, the
+ * map from document space to those pixels: straight-alpha RGBA, `rect.width × rect.height`.
+ */
+export declare function rasterizeVectorBackdrop(nodes: readonly VectorRenderNode[], defs: readonly VectorPaintDef[], toPixels: VectorMatrix, rect: RasterRect): Uint8ClampedArray;
+export {};

package/dist/vector/brushstroke.d.cts

@@ -1,11 +1,14 @@
 import { type PaintBrush } from '../paint-editor/brushes.cjs';
 import type { Brush } from '../brushes/types.cjs';
-import type { VectorBrushstroke, VectorBrushstrokePaper, VectorPathNode, VectorStrokeLayer } from './types.cjs';
+import { type VectorBrushstrokeBackdrop } from './brushstrokeMedia.cjs';
+import type { VectorBrushstroke, VectorBrushstrokePaint, VectorBrushstrokePaper, VectorDocument, VectorPathNode, VectorStrokeLayer } from './types.cjs';
 /** Image pixels per document unit brushstrokes are rendered at. */
 export declare const VECTOR_BRUSHSTROKE_SCALE = 2;
+/** Whether a brush's engine paints vector brushstrokes: dry dab brushes, wet paint, the Mixer Brush, smudge and blender. */
+export declare function isVectorBrushstrokeEngine(brush: PaintBrush): boolean;
 /**
  * The brushes a brushstroke can use, as the engine paints them: the presets `VECTOR_PROFILE`
- * admits (dry dab-engine brushes), then the saved brushes given (facet brushes, e.g. a brush
+ * admits (dry, wet paint, mixer, smudge and blender brushes), then the saved brushes given (facet brushes, e.g. a brush
  * library's) it admits.
  */
 export declare function vectorBrushstrokeBrushes(user?: readonly Brush[]): PaintBrush[];
@@ -30,6 +33,15 @@ export declare function vectorBrushstrokeDefaultColour(id: string, user?: readon
  * kept in `spec`.
  */
 export declare function sanitizeVectorBrushstroke(value: unknown, user?: readonly Brush[]): VectorBrushstroke | null;
+/**
+ * What is wrong with a brushstroke's gradient `paint` (from an agent or a caller), or null when it
+ * is valid. Paint is `{ type: 'color', color }` or `{ type: 'gradient', stops, space, map, softness }`
+ * (the paint engine's `PaintSource`, lengths in document units). `velocity` and `time` mappings
+ * are refused: a vector path has no timing.
+ */
+export declare function vectorBrushstrokePaintError(paint: unknown): string | null;
+/** Reads brushstroke paint from untrusted data (a stored layer); null when it is not valid paint. */
+export declare function readVectorBrushstrokePaint(value: unknown): VectorBrushstrokePaint | null;
 /** The largest brushstroke seed. */
 export declare const VECTOR_BRUSHSTROKE_MAX_SEED = 2147483647;
 /** Reads paper settings from untrusted data; null when there are none (the default paper). */
@@ -59,10 +71,45 @@ export interface VectorBrushstrokeImage {
     width: number;
     height: number;
 }
+/** Where and how a brushstroke renders. */
+export interface VectorBrushstrokeContext {
+    /**
+     * The document the path is in. A Mixer Brush, smudge or blender acts on what lies beneath the
+     * stroke there; without it, only on the path's own fills and lower strokes.
+     */
+    document?: VectorDocument | null;
+    /**
+     * `async` (default): a wet brushstroke shows the paint as laid until its simulation has settled
+     * (`onVectorBrushstrokesSettled` says when). `now`: settle it first (exports, agents).
+     */
+    settle?: 'async' | 'now';
+}
+/**
+ * What lies beneath stroke layer `index` of `node`: the objects it depends on (compared by
+ * identity: any change beneath gives a new one), and the backdrop renderer. The scene renderer
+ * registers it (`setVectorBackdropSource`), as it is the one that can draw the scene.
+ */
+export type VectorBackdropSource = (document: VectorDocument | null, node: VectorPathNode, index: number, settle: 'async' | 'now') => {
+    deps: readonly unknown[];
+    backdrop: VectorBrushstrokeBackdrop;
+};
+/** Registers what draws the backdrop of mixer, smudge and blender brushstrokes (done by `render.ts`). */
+export declare function setVectorBackdropSource(source: VectorBackdropSource | null): void;
+/**
+ * Calls `listener` whenever a wet brushstroke has settled, so its final image replaces the one
+ * shown while it settled. Re-render the scene then (the controller does: it notifies its
+ * subscribers). Returns the unsubscribe function.
+ */
+export declare function onVectorBrushstrokesSettled(listener: () => void): () => void;
+/** How many wet brushstrokes are still settling. */
+export declare function vectorBrushstrokesSettling(): number;
+/** Settles every wet brushstroke still settling, now (slow for many long strokes). Returns how many there were. */
+export declare function settleVectorBrushstrokes(): number;
 /**
- * The images of a brushstroke layer on a path, one per subpath, in the path's own space (cached
- * per path and layer object, and by the shared renderer's cache, whose key includes the seed and
- * paper). A layer with a seed renders with the brush's character, the grain laid in the path's
- * own space (paper point = path point).
+ * The images of a brushstroke layer on a path, one per subpath, in the path's own space. Cached
+ * per path and layer object, by the shared renderer's cache (whose key includes the seed and
+ * paper), and for mixer, smudge and blender strokes by what lies beneath them. A layer with a
+ * seed renders with the brush's character, the grain laid in the path's own space (paper point =
+ * path point). See `VectorBrushstrokeContext` for wet strokes and backdrops.
  */
-export declare function vectorBrushstrokeImages(node: VectorPathNode, layer: VectorStrokeLayer): VectorBrushstrokeImage[];
+export declare function vectorBrushstrokeImages(node: VectorPathNode, layer: VectorStrokeLayer, context?: VectorBrushstrokeContext): VectorBrushstrokeImage[];

package/dist/vector/brushstroke.d.ts

@@ -1,11 +1,14 @@
 import { type PaintBrush } from '../paint-editor/brushes.js';
 import type { Brush } from '../brushes/types.js';
-import type { VectorBrushstroke, VectorBrushstrokePaper, VectorPathNode, VectorStrokeLayer } from './types.js';
+import { type VectorBrushstrokeBackdrop } from './brushstrokeMedia.js';
+import type { VectorBrushstroke, VectorBrushstrokePaint, VectorBrushstrokePaper, VectorDocument, VectorPathNode, VectorStrokeLayer } from './types.js';
 /** Image pixels per document unit brushstrokes are rendered at. */
 export declare const VECTOR_BRUSHSTROKE_SCALE = 2;
+/** Whether a brush's engine paints vector brushstrokes: dry dab brushes, wet paint, the Mixer Brush, smudge and blender. */
+export declare function isVectorBrushstrokeEngine(brush: PaintBrush): boolean;
 /**
  * The brushes a brushstroke can use, as the engine paints them: the presets `VECTOR_PROFILE`
- * admits (dry dab-engine brushes), then the saved brushes given (facet brushes, e.g. a brush
+ * admits (dry, wet paint, mixer, smudge and blender brushes), then the saved brushes given (facet brushes, e.g. a brush
  * library's) it admits.
  */
 export declare function vectorBrushstrokeBrushes(user?: readonly Brush[]): PaintBrush[];
@@ -30,6 +33,15 @@ export declare function vectorBrushstrokeDefaultColour(id: string, user?: readon
  * kept in `spec`.
  */
 export declare function sanitizeVectorBrushstroke(value: unknown, user?: readonly Brush[]): VectorBrushstroke | null;
+/**
+ * What is wrong with a brushstroke's gradient `paint` (from an agent or a caller), or null when it
+ * is valid. Paint is `{ type: 'color', color }` or `{ type: 'gradient', stops, space, map, softness }`
+ * (the paint engine's `PaintSource`, lengths in document units). `velocity` and `time` mappings
+ * are refused: a vector path has no timing.
+ */
+export declare function vectorBrushstrokePaintError(paint: unknown): string | null;
+/** Reads brushstroke paint from untrusted data (a stored layer); null when it is not valid paint. */
+export declare function readVectorBrushstrokePaint(value: unknown): VectorBrushstrokePaint | null;
 /** The largest brushstroke seed. */
 export declare const VECTOR_BRUSHSTROKE_MAX_SEED = 2147483647;
 /** Reads paper settings from untrusted data; null when there are none (the default paper). */
@@ -59,10 +71,45 @@ export interface VectorBrushstrokeImage {
     width: number;
     height: number;
 }
+/** Where and how a brushstroke renders. */
+export interface VectorBrushstrokeContext {
+    /**
+     * The document the path is in. A Mixer Brush, smudge or blender acts on what lies beneath the
+     * stroke there; without it, only on the path's own fills and lower strokes.
+     */
+    document?: VectorDocument | null;
+    /**
+     * `async` (default): a wet brushstroke shows the paint as laid until its simulation has settled
+     * (`onVectorBrushstrokesSettled` says when). `now`: settle it first (exports, agents).
+     */
+    settle?: 'async' | 'now';
+}
+/**
+ * What lies beneath stroke layer `index` of `node`: the objects it depends on (compared by
+ * identity: any change beneath gives a new one), and the backdrop renderer. The scene renderer
+ * registers it (`setVectorBackdropSource`), as it is the one that can draw the scene.
+ */
+export type VectorBackdropSource = (document: VectorDocument | null, node: VectorPathNode, index: number, settle: 'async' | 'now') => {
+    deps: readonly unknown[];
+    backdrop: VectorBrushstrokeBackdrop;
+};
+/** Registers what draws the backdrop of mixer, smudge and blender brushstrokes (done by `render.ts`). */
+export declare function setVectorBackdropSource(source: VectorBackdropSource | null): void;
+/**
+ * Calls `listener` whenever a wet brushstroke has settled, so its final image replaces the one
+ * shown while it settled. Re-render the scene then (the controller does: it notifies its
+ * subscribers). Returns the unsubscribe function.
+ */
+export declare function onVectorBrushstrokesSettled(listener: () => void): () => void;
+/** How many wet brushstrokes are still settling. */
+export declare function vectorBrushstrokesSettling(): number;
+/** Settles every wet brushstroke still settling, now (slow for many long strokes). Returns how many there were. */
+export declare function settleVectorBrushstrokes(): number;
 /**
- * The images of a brushstroke layer on a path, one per subpath, in the path's own space (cached
- * per path and layer object, and by the shared renderer's cache, whose key includes the seed and
- * paper). A layer with a seed renders with the brush's character, the grain laid in the path's
- * own space (paper point = path point).
+ * The images of a brushstroke layer on a path, one per subpath, in the path's own space. Cached
+ * per path and layer object, by the shared renderer's cache (whose key includes the seed and
+ * paper), and for mixer, smudge and blender strokes by what lies beneath them. A layer with a
+ * seed renders with the brush's character, the grain laid in the path's own space (paper point =
+ * path point). See `VectorBrushstrokeContext` for wet strokes and backdrops.
  */
-export declare function vectorBrushstrokeImages(node: VectorPathNode, layer: VectorStrokeLayer): VectorBrushstrokeImage[];
+export declare function vectorBrushstrokeImages(node: VectorPathNode, layer: VectorStrokeLayer, context?: VectorBrushstrokeContext): VectorBrushstrokeImage[];

package/dist/vector/brushstrokeMedia.d.cts

@@ -0,0 +1,96 @@
+/**
+ * Brushstrokes on vector paths with media that need more than an empty image (#519): wet paint, and
+ * the Mixer Brush, smudge and blender, which act on the paint under them. The path stays the data
+ * and the pixels a cache, as for dry brushstrokes (`renderBrushstroke`).
+ *
+ * - **Wet** (`engine: 'wet'`, wet paint brushes: watercolour, gouache, wet oils): the stroke gets its
+ *   own small `WetWorld` over its bounds, the paint editor's `WetStrokeDriver` lays it, the
+ *   simulation runs `VECTOR_WET_STEPS` steps (time is counted in steps, never wall time) and the
+ *   paint is dried where it is. The bytes depend only on the path, brush, colour and seed. The
+ *   simulation costs about 9 ms per 256 px tile per step on the TypeScript kernel, so
+ *   `WetBrushstrokeJob` can run it in slices: hosts show the bake of the paint as laid (step 0) at
+ *   once, and swap in the settled image when it is done.
+ * - **Backdrop media** (`mixer`, `smudge`, `blender`): the stroke runs the paint editor's dab-by-dab
+ *   engine (`PaintDabStroke`) over a local copy of what lies beneath it (the backdrop, rendered by
+ *   the caller), and keeps only the pixels it changed. Drawn over the content it was made from,
+ *   that is the stroke's result. A smudge can drag paint over bare paper, but it can't take paint
+ *   away from the content underneath (the image is drawn over it).
+ *
+ * Coordinates: like `renderBrushstroke`, inputs are in path units, rendered at `scale` image pixels
+ * per unit, and the result's `bounds` place the image back in path units.
+ */
+import { type BrushstrokeImage, type BrushstrokeInput } from '../paint/brushstroke.cjs';
+import { type PaintSource } from '../paint/gradient-paint.cjs';
+import type { PaintBrush } from '../paint-editor/brushes.cjs';
+import { type RasterRect } from '../raster/surface.cjs';
+/** Simulation steps a wet brushstroke runs before it is dried (enough to bleed, bloom and granulate). */
+export declare const VECTOR_WET_STEPS = 120;
+/** Engines a vector brushstroke paints through this module. */
+export type VectorMediaEngine = 'wet' | 'mixer' | 'smudge' | 'blender';
+/** Whether a brush paints through this module (and which way), or null for a dry dab brush. */
+export declare function vectorMediaEngine(brush: Pick<PaintBrush, 'engine' | 'wet'>): VectorMediaEngine | null;
+/** Whether a media engine acts on the paint beneath the stroke (and needs a backdrop). */
+export declare const usesVectorBackdrop: (engine: VectorMediaEngine | null) => boolean;
+export interface VectorMediaOptions {
+    /** Image pixels per path unit (default 1). */
+    scale?: number;
+    /** RGBA 0..255 of the paint (the alpha scales the result). */
+    color: readonly [number, number, number, number];
+    /** Gradient paint sampled dab by dab (lengths in path units), or null for `color`. */
+    paint?: PaintSource | null;
+    /** Jitter seed (default 0). */
+    seed?: number;
+    closed?: boolean;
+    /** The largest image to render, in pixels (default 4096²); a bigger stroke renders at a lower scale. */
+    maxPixels?: number;
+}
+/**
+ * One wet brushstroke's simulation: the paint is laid when the job is made; `run` advances it
+ * (within a time budget, for hosts that slice the work), `image` bakes it as it is now and
+ * `settled` once all `VECTOR_WET_STEPS` steps have run. Call `destroy` when done with it.
+ */
+export declare class WetBrushstrokeJob {
+    readonly steps: number;
+    private readonly world;
+    private readonly placed;
+    private readonly dabs;
+    private done;
+    private final;
+    constructor(input: BrushstrokeInput, brush: PaintBrush, options: VectorMediaOptions, steps?: number);
+    /** Steps run so far. */
+    get progress(): number;
+    get finished(): boolean;
+    /** Runs steps until `budgetMs` has passed (at least one) or all have run. Returns whether it is finished. */
+    run(budgetMs?: number): boolean;
+    /** The paint dried where it is now (step 0: as laid). */
+    image(): BrushstrokeImage;
+    /** The settled image: runs the remaining steps now. */
+    settled(): BrushstrokeImage;
+    destroy(): void;
+    private bake;
+}
+/** A wet brushstroke rendered and settled at once (`VECTOR_WET_STEPS` steps; slow for long strokes). */
+export declare function renderWetBrushstroke(input: BrushstrokeInput, brush: PaintBrush, options: VectorMediaOptions): BrushstrokeImage;
+/**
+ * What lies beneath a stroke: straight-alpha RGBA of `rect` (image pixels at the stroke's scale,
+ * path units × scale), row by row. Called once per render.
+ */
+export type VectorBrushstrokeBackdrop = (rect: RasterRect, scale: number) => Uint8ClampedArray;
+/** The image pixels a backdrop brushstroke reads, in path units × the scale it renders at (for callers that render backdrops). */
+export declare function vectorBackdropRect(input: BrushstrokeInput, brush: PaintBrush, options: VectorMediaOptions): {
+    rect: RasterRect;
+    scale: number;
+} | null;
+/**
+ * A Mixer Brush, smudge or blender stroke over `backdrop`: the pixels it changed (the rest are
+ * transparent). Without a backdrop it acts on bare paper: a Mixer Brush still paints from its
+ * reservoir; a smudge or blender changes nothing.
+ */
+export declare function renderBackdropBrushstroke(input: BrushstrokeInput, brush: PaintBrush, options: VectorMediaOptions & {
+    backdrop?: VectorBrushstrokeBackdrop | null;
+    /** A cache for the result, given the backdrop's bytes (the result depends only on them and the stroke). */
+    cache?: (backdrop: Uint8ClampedArray) => {
+        get(): BrushstrokeImage | undefined;
+        set(image: BrushstrokeImage): void;
+    };
+}): BrushstrokeImage;

package/dist/vector/brushstrokeMedia.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Brushstrokes on vector paths with media that need more than an empty image (#519): wet paint, and
+ * the Mixer Brush, smudge and blender, which act on the paint under them. The path stays the data
+ * and the pixels a cache, as for dry brushstrokes (`renderBrushstroke`).
+ *
+ * - **Wet** (`engine: 'wet'`, wet paint brushes: watercolour, gouache, wet oils): the stroke gets its
+ *   own small `WetWorld` over its bounds, the paint editor's `WetStrokeDriver` lays it, the
+ *   simulation runs `VECTOR_WET_STEPS` steps (time is counted in steps, never wall time) and the
+ *   paint is dried where it is. The bytes depend only on the path, brush, colour and seed. The
+ *   simulation costs about 9 ms per 256 px tile per step on the TypeScript kernel, so
+ *   `WetBrushstrokeJob` can run it in slices: hosts show the bake of the paint as laid (step 0) at
+ *   once, and swap in the settled image when it is done.
+ * - **Backdrop media** (`mixer`, `smudge`, `blender`): the stroke runs the paint editor's dab-by-dab
+ *   engine (`PaintDabStroke`) over a local copy of what lies beneath it (the backdrop, rendered by
+ *   the caller), and keeps only the pixels it changed. Drawn over the content it was made from,
+ *   that is the stroke's result. A smudge can drag paint over bare paper, but it can't take paint
+ *   away from the content underneath (the image is drawn over it).
+ *
+ * Coordinates: like `renderBrushstroke`, inputs are in path units, rendered at `scale` image pixels
+ * per unit, and the result's `bounds` place the image back in path units.
+ */
+import { type BrushstrokeImage, type BrushstrokeInput } from '../paint/brushstroke.js';
+import { type PaintSource } from '../paint/gradient-paint.js';
+import type { PaintBrush } from '../paint-editor/brushes.js';
+import { type RasterRect } from '../raster/surface.js';
+/** Simulation steps a wet brushstroke runs before it is dried (enough to bleed, bloom and granulate). */
+export declare const VECTOR_WET_STEPS = 120;
+/** Engines a vector brushstroke paints through this module. */
+export type VectorMediaEngine = 'wet' | 'mixer' | 'smudge' | 'blender';
+/** Whether a brush paints through this module (and which way), or null for a dry dab brush. */
+export declare function vectorMediaEngine(brush: Pick<PaintBrush, 'engine' | 'wet'>): VectorMediaEngine | null;
+/** Whether a media engine acts on the paint beneath the stroke (and needs a backdrop). */
+export declare const usesVectorBackdrop: (engine: VectorMediaEngine | null) => boolean;
+export interface VectorMediaOptions {
+    /** Image pixels per path unit (default 1). */
+    scale?: number;
+    /** RGBA 0..255 of the paint (the alpha scales the result). */
+    color: readonly [number, number, number, number];
+    /** Gradient paint sampled dab by dab (lengths in path units), or null for `color`. */
+    paint?: PaintSource | null;
+    /** Jitter seed (default 0). */
+    seed?: number;
+    closed?: boolean;
+    /** The largest image to render, in pixels (default 4096²); a bigger stroke renders at a lower scale. */
+    maxPixels?: number;
+}
+/**
+ * One wet brushstroke's simulation: the paint is laid when the job is made; `run` advances it
+ * (within a time budget, for hosts that slice the work), `image` bakes it as it is now and
+ * `settled` once all `VECTOR_WET_STEPS` steps have run. Call `destroy` when done with it.
+ */
+export declare class WetBrushstrokeJob {
+    readonly steps: number;
+    private readonly world;
+    private readonly placed;
+    private readonly dabs;
+    private done;
+    private final;
+    constructor(input: BrushstrokeInput, brush: PaintBrush, options: VectorMediaOptions, steps?: number);
+    /** Steps run so far. */
+    get progress(): number;
+    get finished(): boolean;
+    /** Runs steps until `budgetMs` has passed (at least one) or all have run. Returns whether it is finished. */
+    run(budgetMs?: number): boolean;
+    /** The paint dried where it is now (step 0: as laid). */
+    image(): BrushstrokeImage;
+    /** The settled image: runs the remaining steps now. */
+    settled(): BrushstrokeImage;
+    destroy(): void;
+    private bake;
+}
+/** A wet brushstroke rendered and settled at once (`VECTOR_WET_STEPS` steps; slow for long strokes). */
+export declare function renderWetBrushstroke(input: BrushstrokeInput, brush: PaintBrush, options: VectorMediaOptions): BrushstrokeImage;
+/**
+ * What lies beneath a stroke: straight-alpha RGBA of `rect` (image pixels at the stroke's scale,
+ * path units × scale), row by row. Called once per render.
+ */
+export type VectorBrushstrokeBackdrop = (rect: RasterRect, scale: number) => Uint8ClampedArray;
+/** The image pixels a backdrop brushstroke reads, in path units × the scale it renders at (for callers that render backdrops). */
+export declare function vectorBackdropRect(input: BrushstrokeInput, brush: PaintBrush, options: VectorMediaOptions): {
+    rect: RasterRect;
+    scale: number;
+} | null;
+/**
+ * A Mixer Brush, smudge or blender stroke over `backdrop`: the pixels it changed (the rest are
+ * transparent). Without a backdrop it acts on bare paper: a Mixer Brush still paints from its
+ * reservoir; a smudge or blender changes nothing.
+ */
+export declare function renderBackdropBrushstroke(input: BrushstrokeInput, brush: PaintBrush, options: VectorMediaOptions & {
+    backdrop?: VectorBrushstrokeBackdrop | null;
+    /** A cache for the result, given the backdrop's bytes (the result depends only on them and the stroke). */
+    cache?: (backdrop: Uint8ClampedArray) => {
+        get(): BrushstrokeImage | undefined;
+        set(image: BrushstrokeImage): void;
+    };
+}): BrushstrokeImage;

package/dist/vector/controller.d.cts

@@ -29,7 +29,7 @@ import { type VectorSnapGuides, type VectorTrackingPoint } from './snap.cjs';
 import { type VectorBlendMode, type VectorFilterType, type VectorWarpMesh } from './types.cjs';
 import { EffectsSlot } from '../effects/helpers.cjs';
 import type { EffectProvider, EffectValue } from '../effects/types.cjs';
-import type { Vec2, VectorEffectType, VectorAlign, VectorAnchor, VectorAnchorRef, VectorAnchorType, VectorArrange, VectorAverageAxis, VectorBlendOptions, VectorBooleanOperation, VectorBounds, VectorCornerKind, VectorDefaults, VectorDistribute, VectorDocument, VectorGroupNode, VectorProviderEffect, VectorHandleRef, VectorMask, VectorMaskType, VectorModifiers, VectorNode, VectorPathfinderOperation, VectorPathNode, VectorSegmentRef, VectorStyle, VectorSubpath, VectorTool, VectorTransformHandle, VectorViewport, VectorWidthPoint, VectorCharacterStyle, VectorParagraphStyle, VectorTextAlign, VectorTextFrame, VectorTextNode, VectorMatrix, VectorSymbol, VectorPaint, VectorConstraint, VectorConstraintKind, VectorParameter, VectorBrushstroke, VectorBrushstrokePaper } from './types.cjs';
+import type { Vec2, VectorEffectType, VectorAlign, VectorAnchor, VectorAnchorRef, VectorAnchorType, VectorArrange, VectorAverageAxis, VectorBlendOptions, VectorBooleanOperation, VectorBounds, VectorCornerKind, VectorDefaults, VectorDistribute, VectorDocument, VectorGroupNode, VectorProviderEffect, VectorHandleRef, VectorMask, VectorMaskType, VectorModifiers, VectorNode, VectorPathfinderOperation, VectorPathNode, VectorSegmentRef, VectorStyle, VectorSubpath, VectorTool, VectorTransformHandle, VectorViewport, VectorWidthPoint, VectorCharacterStyle, VectorParagraphStyle, VectorTextAlign, VectorTextFrame, VectorTextNode, VectorMatrix, VectorSymbol, VectorPaint, VectorConstraint, VectorConstraintKind, VectorParameter, VectorBrushstroke, VectorBrushstrokePaint, VectorBrushstrokePaper } from './types.cjs';
 export interface VectorSnapOptions {
     /** Grid size in document units (0 = off, default 0). Points and boxes that snap to no object snap to it. */
     grid: number;
@@ -113,6 +113,8 @@ export interface VectorEditorOptions {
     brushPreview?: BrushPreviewRenderer;
     /** The app's colour scheme, which picks the side of a brush's light / dark default colour (default light). */
     colorScheme?: 'light' | 'dark';
+    /** Start with the colour locked: new and rebrushed brushstrokes keep their colour (see `setColorLocked`). */
+    colorLocked?: boolean;
     /** History to record into, e.g. one shared with the rest of the app (default: a new one). */
     history?: HistoryManager;
     /** Starting tool (default `select`). */
@@ -408,6 +410,10 @@ export interface VectorEditorState {
      * a side skews along it (Alt: about the centre).
      */
     freeDistort: boolean;
+    /** The colour scheme that picks the side of a brush's light / dark default colour. */
+    colorScheme: 'light' | 'dark';
+    /** "Keep my colour": brushstrokes don't take a brush's default colour (`setColorLocked`). */
+    colorLocked: boolean;
     /** The text being edited on the canvas, or null. Typing goes to `textInput`, keys to `keyDown`. */
     textEdit: VectorTextEditState | null;
     /** Font and alignment new text gets. */
@@ -799,6 +805,7 @@ export declare class VectorEditorController {
     private revision;
     private state;
     private colorScheme;
+    private colorLocked;
     constructor(options?: VectorEditorOptions);
     /** Listens to the history (once; again after `destroy`). */
     private connect;
@@ -1133,7 +1140,7 @@ export declare class VectorEditorController {
      * Adds a brushstroke to the selected (or given) paths: a stroke layer that paints the path with
      * brush `brushId` (a preset, or a saved brush of the brush library: `listBrushstrokeBrushes`), `size` document
      * units across (default the brush's own), an optional `pressure` profile along the length, in
-     * `color` (default the brush's own default colour, unless `keepColour`; else the top stroke's
+     * `color` (default the brush's own default colour, unless `keepColour` or the colour is locked; else the top stroke's
      * paint, else black) at `opacity`. At the top of the stroke
      * stack or at `index`. A `seed` gives it the brush's character (jitter and the grain of `paper`,
      * `null` for none); without one it renders plain. One undo step.
@@ -1150,7 +1157,7 @@ export declare class VectorEditorController {
      * given) paths: another brush, size, pressure profile (null removes it), colour or opacity, the
      * character `seed` (null removes it: plain dabs) or the `paper` (replaced whole: `null` for no
      * grain, `{}` for the default paper). Another brush without a `color` takes that brush's default
-     * colour, if it has one, unless `keepColour`. Fails, changing nothing, when that layer is not a
+     * colour, if it has one, unless `keepColour` or the colour is locked. Fails, changing nothing, when that layer is not a
      * brushstroke. With `merge`, consecutive edits fold into one undo step.
      */
     setBrushstroke(index: number, patch: {
@@ -1162,12 +1169,19 @@ export declare class VectorEditorController {
         opacity?: number;
         seed?: number | null;
         paper?: VectorBrushstrokePaper | null;
+        paint?: VectorBrushstrokePaint | null;
     }, options?: {
         ids?: readonly string[];
         merge?: boolean | string;
     }): VectorActionResult;
     /** Sets the colour scheme that picks the side of a brush's light / dark default colour. Existing strokes keep their colour. */
     setColorScheme(scheme: 'light' | 'dark'): void;
+    /**
+     * Locks the brushstroke colour ("Keep my colour"): `addBrushstroke` and `setBrushstroke` with
+     * another brush keep the colour instead of taking the brush's default; an explicit `color` still
+     * applies. Existing strokes are unchanged. Editor state, not an undo step.
+     */
+    setColorLocked(locked: boolean): void;
     /** Removes layer `index` of the fill or stroke stack of the selected (or given) paths. */
     removePaintLayer(kind: 'fill' | 'stroke', index: number, options?: {
         ids?: readonly string[];

package/dist/vector/controller.d.ts

@@ -29,7 +29,7 @@ import { type VectorSnapGuides, type VectorTrackingPoint } from './snap.js';
 import { type VectorBlendMode, type VectorFilterType, type VectorWarpMesh } from './types.js';
 import { EffectsSlot } from '../effects/helpers.js';
 import type { EffectProvider, EffectValue } from '../effects/types.js';
-import type { Vec2, VectorEffectType, VectorAlign, VectorAnchor, VectorAnchorRef, VectorAnchorType, VectorArrange, VectorAverageAxis, VectorBlendOptions, VectorBooleanOperation, VectorBounds, VectorCornerKind, VectorDefaults, VectorDistribute, VectorDocument, VectorGroupNode, VectorProviderEffect, VectorHandleRef, VectorMask, VectorMaskType, VectorModifiers, VectorNode, VectorPathfinderOperation, VectorPathNode, VectorSegmentRef, VectorStyle, VectorSubpath, VectorTool, VectorTransformHandle, VectorViewport, VectorWidthPoint, VectorCharacterStyle, VectorParagraphStyle, VectorTextAlign, VectorTextFrame, VectorTextNode, VectorMatrix, VectorSymbol, VectorPaint, VectorConstraint, VectorConstraintKind, VectorParameter, VectorBrushstroke, VectorBrushstrokePaper } from './types.js';
+import type { Vec2, VectorEffectType, VectorAlign, VectorAnchor, VectorAnchorRef, VectorAnchorType, VectorArrange, VectorAverageAxis, VectorBlendOptions, VectorBooleanOperation, VectorBounds, VectorCornerKind, VectorDefaults, VectorDistribute, VectorDocument, VectorGroupNode, VectorProviderEffect, VectorHandleRef, VectorMask, VectorMaskType, VectorModifiers, VectorNode, VectorPathfinderOperation, VectorPathNode, VectorSegmentRef, VectorStyle, VectorSubpath, VectorTool, VectorTransformHandle, VectorViewport, VectorWidthPoint, VectorCharacterStyle, VectorParagraphStyle, VectorTextAlign, VectorTextFrame, VectorTextNode, VectorMatrix, VectorSymbol, VectorPaint, VectorConstraint, VectorConstraintKind, VectorParameter, VectorBrushstroke, VectorBrushstrokePaint, VectorBrushstrokePaper } from './types.js';
 export interface VectorSnapOptions {
     /** Grid size in document units (0 = off, default 0). Points and boxes that snap to no object snap to it. */
     grid: number;
@@ -113,6 +113,8 @@ export interface VectorEditorOptions {
     brushPreview?: BrushPreviewRenderer;
     /** The app's colour scheme, which picks the side of a brush's light / dark default colour (default light). */
     colorScheme?: 'light' | 'dark';
+    /** Start with the colour locked: new and rebrushed brushstrokes keep their colour (see `setColorLocked`). */
+    colorLocked?: boolean;
     /** History to record into, e.g. one shared with the rest of the app (default: a new one). */
     history?: HistoryManager;
     /** Starting tool (default `select`). */
@@ -408,6 +410,10 @@ export interface VectorEditorState {
      * a side skews along it (Alt: about the centre).
      */
     freeDistort: boolean;
+    /** The colour scheme that picks the side of a brush's light / dark default colour. */
+    colorScheme: 'light' | 'dark';
+    /** "Keep my colour": brushstrokes don't take a brush's default colour (`setColorLocked`). */
+    colorLocked: boolean;
     /** The text being edited on the canvas, or null. Typing goes to `textInput`, keys to `keyDown`. */
     textEdit: VectorTextEditState | null;
     /** Font and alignment new text gets. */
@@ -799,6 +805,7 @@ export declare class VectorEditorController {
     private revision;
     private state;
     private colorScheme;
+    private colorLocked;
     constructor(options?: VectorEditorOptions);
     /** Listens to the history (once; again after `destroy`). */
     private connect;
@@ -1133,7 +1140,7 @@ export declare class VectorEditorController {
      * Adds a brushstroke to the selected (or given) paths: a stroke layer that paints the path with
      * brush `brushId` (a preset, or a saved brush of the brush library: `listBrushstrokeBrushes`), `size` document
      * units across (default the brush's own), an optional `pressure` profile along the length, in
-     * `color` (default the brush's own default colour, unless `keepColour`; else the top stroke's
+     * `color` (default the brush's own default colour, unless `keepColour` or the colour is locked; else the top stroke's
      * paint, else black) at `opacity`. At the top of the stroke
      * stack or at `index`. A `seed` gives it the brush's character (jitter and the grain of `paper`,
      * `null` for none); without one it renders plain. One undo step.
@@ -1150,7 +1157,7 @@ export declare class VectorEditorController {
      * given) paths: another brush, size, pressure profile (null removes it), colour or opacity, the
      * character `seed` (null removes it: plain dabs) or the `paper` (replaced whole: `null` for no
      * grain, `{}` for the default paper). Another brush without a `color` takes that brush's default
-     * colour, if it has one, unless `keepColour`. Fails, changing nothing, when that layer is not a
+     * colour, if it has one, unless `keepColour` or the colour is locked. Fails, changing nothing, when that layer is not a
      * brushstroke. With `merge`, consecutive edits fold into one undo step.
      */
     setBrushstroke(index: number, patch: {
@@ -1162,12 +1169,19 @@ export declare class VectorEditorController {
         opacity?: number;
         seed?: number | null;
         paper?: VectorBrushstrokePaper | null;
+        paint?: VectorBrushstrokePaint | null;
     }, options?: {
         ids?: readonly string[];
         merge?: boolean | string;
     }): VectorActionResult;
     /** Sets the colour scheme that picks the side of a brush's light / dark default colour. Existing strokes keep their colour. */
     setColorScheme(scheme: 'light' | 'dark'): void;
+    /**
+     * Locks the brushstroke colour ("Keep my colour"): `addBrushstroke` and `setBrushstroke` with
+     * another brush keep the colour instead of taking the brush's default; an explicit `color` still
+     * applies. Existing strokes are unchanged. Editor state, not an undo step.
+     */
+    setColorLocked(locked: boolean): void;
     /** Removes layer `index` of the fill or stroke stack of the selected (or given) paths. */
     removePaintLayer(kind: 'fill' | 'stroke', index: number, options?: {
         ids?: readonly string[];