@pixerate/editor 0.266.2 → 0.268.0

package/dist/stickers/index.js

@@ -3,7 +3,7 @@ import {
   editorStickers,
   stampOutline,
   stampPixels
-} from "../chunk-DOZ6F2K2.js";
+} from "../chunk-NSETJI74.js";
 import {
   createInsertStickerTool,
   createStickerToolProvider,
@@ -11,7 +11,7 @@ import {
   describeStickerRef,
   insertSticker,
   stickerForAgent
-} from "../chunk-6JL2D5SG.js";
+} from "../chunk-VE6UKYQ2.js";
 import {
   DEFAULT_STICKER_PAGE,
   EDITOR_STICKERS_ID,
@@ -25,6 +25,7 @@ import {
   editorStampOf,
   normalizeStickerRef,
   parseStickerRef,
+  providerCollections,
   stampCoverage,
   stickerCollections,
   stickerIdFor,
@@ -32,7 +33,7 @@ import {
   stickerRefOf,
   stickerVariantFor,
   stickerVariantsOf
-} from "../chunk-ACFSFUQH.js";
+} from "../chunk-JL6YH5WD.js";
 import {
   StickerError
 } from "../chunk-SZTI6EER.js";
@@ -121,7 +122,9 @@ function createFakeStickerProvider(options = {}) {
       if (!s) return void 0;
       return { ...summaryOf(s), silhouette: s.shape === "badge" ? "M60 6A54 54 0 1 1 59.9 6Z" : "M10 10H110V110H10Z", colours: s.shape === "badge" ? [s.colours[0]] : [...s.colours] };
     },
+    collections: () => stickerCollections(summaries, COLLECTIONS),
     listCollections: () => stickerCollections(summaries, COLLECTIONS),
+    // the older name, kept for callers that use it
     categories: () => [...new Set(CATALOGUE.map((s) => s.category))].map((c) => ({ id: c, name: c, count: CATALOGUE.filter((s) => s.category === c).length })),
     async load(id, o = {}) {
       if (options.loadDelayMs) await new Promise((r) => setTimeout(r, options.loadDelayMs));
@@ -157,7 +160,7 @@ function combineStickerProviders(providers, options = {}) {
   const collectionOwner = (c) => {
     const i = c.indexOf(":");
     const p = i > 0 ? byId.get(c.slice(0, i)) : void 0;
-    if (!p) throw new StickerError("invalid_argument", `No collection "${c}"; collections here are "provider:collection" (listCollections lists them).`);
+    if (!p) throw new StickerError("invalid_argument", `No collection "${c}"; collections here are "provider:collection" (collections() lists them).`);
     return { p, collection: p.namespaced ? c : c.slice(i + 1) };
   };
   const page = async (query, o = {}) => {
@@ -196,6 +199,11 @@ function combineStickerProviders(providers, options = {}) {
     if (!next && items.length >= limit && i < providers.length) next = `${i}|`;
     return { items, total, ...next ? { next } : {} };
   };
+  const collections = async () => {
+    const out = [];
+    for (const p of providers) for (const c of await providerCollections(p) ?? []) out.push({ ...c, id: collectionOf(p, c.id) });
+    return out;
+  };
   return {
     id: options.id ?? "stickers",
     name: options.name ?? providers.map((p) => p.name).join(" + "),
@@ -232,11 +240,8 @@ function combineStickerProviders(providers, options = {}) {
       }
       return [...counts.values()];
     },
-    async listCollections() {
-      const out = [];
-      for (const p of providers) for (const c of await p.listCollections?.() ?? []) out.push({ ...c, id: collectionOf(p, c.id) });
-      return out;
-    }
+    collections,
+    listCollections: collections
   };
 }
 
@@ -263,7 +268,7 @@ function checkSummary(s, provider, issues) {
     else if (!v.includes("light")) at("variants must include light (every sticker has its light art)");
   }
   if (s.collection !== void 0 && (typeof s.collection !== "string" || !s.collection)) at("collection must be a non-empty string when present");
-  if (s.collection !== void 0 && !provider.listCollections) at(`is in collection "${s.collection}" but the provider has no listCollections()`);
+  if (s.collection !== void 0 && !provider.collections && !provider.listCollections) at(`is in collection "${s.collection}" but the provider has no collections()`);
 }
 async function checkStickerProvider(provider, options = {}) {
   const issues = [];
@@ -322,24 +327,24 @@ async function checkStickerProvider(provider, options = {}) {
     if (d?.colours?.some((c) => !HEX.test(c))) top(`describe("${first.id}").colours must be #rrggbb`);
   }
   if (await provider.describe("__no_such_sticker__") !== void 0) top("describe of an unknown id returned a sticker");
-  if (provider.listCollections) {
+  if (provider.collections || provider.listCollections) {
     try {
-      const collections = await provider.listCollections();
+      const collections = await providerCollections(provider) ?? [];
       const known = /* @__PURE__ */ new Set();
       for (const c of collections) {
         if (typeof c?.id !== "string" || !c.id || typeof c.name !== "string" || !c.name || !(Number.isInteger(c.count) && c.count >= 0)) {
-          top(`listCollections() returned ${JSON.stringify(c)}; each needs id, name and a count`);
+          top(`collections() returned ${JSON.stringify(c)}; each needs id, name and a count`);
           continue;
         }
-        if (known.has(c.id)) top(`listCollections() lists "${c.id}" twice`);
+        if (known.has(c.id)) top(`collections() lists "${c.id}" twice`);
         known.add(c.id);
         const page = await provider.list({ collection: c.id, limit: 100 });
         if (page.total !== c.count) top(`collection "${c.id}" says count ${c.count} but list({ collection }) has ${page.total}`);
         if (page.items.some((x) => x.collection !== c.id)) top(`list({ collection: "${c.id}" }) returned stickers of other collections`);
       }
-      for (const x of all) if (x.collection !== void 0 && !known.has(x.collection)) issues.push({ stickerId: x.id, message: `collection "${x.collection}" is not in listCollections()` });
+      for (const x of all) if (x.collection !== void 0 && !known.has(x.collection)) issues.push({ stickerId: x.id, message: `collection "${x.collection}" is not in collections()` });
     } catch (e) {
-      top(`listCollections() rejected: ${e.message}`);
+      top(`collections() rejected: ${e.message}`);
     }
   }
   let rejected = false;
@@ -413,6 +418,7 @@ export {
   insertSticker,
   normalizeStickerRef,
   parseStickerRef,
+  providerCollections,
   stampCoverage,
   stampOutline,
   stampPixels,

package/dist/stickers/types.d.cts

@@ -61,7 +61,7 @@ export interface StickerSummary {
      * picker or brush can pick the dark one for a dark background without calling `describe` first.
      */
     variants?: StickerVariant[];
-    /** The collection it belongs to (`listCollections`), when the provider groups its stickers. */
+    /** The collection it belongs to (`collections()`), when the provider groups its stickers. */
     collection?: string;
 }
 /** Everything about one sticker. */
@@ -93,7 +93,7 @@ export interface StickerPage {
 }
 export interface StickerSearchOptions {
     category?: string;
-    /** Only stickers of this collection (`listCollections`). */
+    /** Only stickers of this collection (`collections()`). */
     collection?: string;
     /** Every tag must match. */
     tags?: string[];
@@ -144,6 +144,8 @@ export interface StickerProvider {
         count: number;
     }>>;
     /** Its collections with counts, when it groups its stickers. Ids stay unique across collections, so `load(id)` needs none. */
+    collections?(): MaybePromise<StickerCollection[]>;
+    /** The older name for `collections()`, still read when a provider has no `collections()`. */
     listCollections?(): MaybePromise<StickerCollection[]>;
 }
 /** `provider:id`, the name of a sticker across providers. A bare editor stamp (`"star"`) means `editor:star`. */

package/dist/stickers/types.d.ts

@@ -61,7 +61,7 @@ export interface StickerSummary {
      * picker or brush can pick the dark one for a dark background without calling `describe` first.
      */
     variants?: StickerVariant[];
-    /** The collection it belongs to (`listCollections`), when the provider groups its stickers. */
+    /** The collection it belongs to (`collections()`), when the provider groups its stickers. */
     collection?: string;
 }
 /** Everything about one sticker. */
@@ -93,7 +93,7 @@ export interface StickerPage {
 }
 export interface StickerSearchOptions {
     category?: string;
-    /** Only stickers of this collection (`listCollections`). */
+    /** Only stickers of this collection (`collections()`). */
     collection?: string;
     /** Every tag must match. */
     tags?: string[];
@@ -144,6 +144,8 @@ export interface StickerProvider {
         count: number;
     }>>;
     /** Its collections with counts, when it groups its stickers. Ids stay unique across collections, so `load(id)` needs none. */
+    collections?(): MaybePromise<StickerCollection[]>;
+    /** The older name for `collections()`, still read when a provider has no `collections()`. */
     listCollections?(): MaybePromise<StickerCollection[]>;
 }
 /** `provider:id`, the name of a sticker across providers. A bare editor stamp (`"star"`) means `editor:star`. */

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[];