@pixerate/editor 0.225.0 → 0.227.0

package/dist/image-editor/index.js

@@ -4,7 +4,7 @@ import {
   parseOpenTypeFont,
   removeAnchorsKeepingShape,
   traceField
-} from "../chunk-DJBYJOHM.js";
+} from "../chunk-XSVUNSDJ.js";
 import {
   ColorGmm,
   GAMMA,
@@ -405,7 +405,7 @@ import {
   writePsd,
   xyToTempTint,
   xyToUv
-} from "../chunk-S6KKLFZO.js";
+} from "../chunk-KN3Y3FRY.js";
 import {
   parseCssColor
 } from "../chunk-3CI7FRMK.js";
@@ -727,8 +727,8 @@ import {
   warpMeshParamAt,
   warpMeshRows,
   warpPresetMesh
-} from "../chunk-NDMXB4PR.js";
-import "../chunk-F7YA3MMC.js";
+} from "../chunk-CU6ANS5L.js";
+import "../chunk-TQOL6CF7.js";
 import "../chunk-M6DNZNVY.js";
 import {
   bezierPathToSvg,
@@ -743,7 +743,7 @@ import {
   createEffectToolProvider,
   linearToSrgb,
   resolveEffectValues
-} from "../chunk-HKPLKISO.js";
+} from "../chunk-7DZ55AIE.js";
 import "../chunk-V2ZCJRDM.js";
 import {
   BrushstrokeCache,
@@ -6545,7 +6545,7 @@ var ImageEditorController = class {
       id = res2.layer.id;
       converted = true;
     }
-    const filter = normalizeSmartFilter({ kind: "effect", effect: d.id, provider: this.effects.require().id, name: d.name, values, enabled: options.enabled !== false, blend: options.blend, opacity: options.opacity });
+    const filter = normalizeSmartFilter({ kind: "effect", effect: d.id, provider: this.effects.require().id, name: d.name, values, enabled: options.enabled !== false, blend: options.blend, opacity: options.opacity, preserveTransparency: options.preserveTransparency });
     const res = addSmartFilter(layers, id, filter, this.canvasSize, options.index);
     const masked = this.asOneStep(() => {
       this.commitLayers(res.layers);
@@ -6555,7 +6555,8 @@ var ImageEditorController = class {
   }
   /**
    * Changes an effect smart filter: `values` merged over its own (`null` resets a control to the
-   * effect's default), `enabled`, `blend`, `opacity` or its place in the stack (`index`). Values
+   * effect's default), `enabled`, `blend`, `opacity`, `preserveTransparency` or its place in the
+   * stack (`index`). Values
    * are checked against the provider's controls. One undo step (none with `commitToHistory`
    * false, during a drag).
    */
@@ -6575,7 +6576,7 @@ var ImageEditorController = class {
       }
       update.values = { ...base, ...resolveEffectValues({ ...d, defaults: base }, given) };
     }
-    for (const k of ["enabled", "blend", "opacity"]) if (changes[k] !== void 0) update[k] = changes[k];
+    for (const k of ["enabled", "blend", "opacity", "preserveTransparency"]) if (changes[k] !== void 0) update[k] = changes[k];
     let res = updateSmartFilter(this.state.layers, layerId, filterId, update, this.canvasSize);
     if (changes.index !== void 0) res = { ...res, layers: moveSmartFilter(res.layers, layerId, filterId, changes.index, this.canvasSize).layers };
     this.commitLayers(res.layers, void 0, commitToHistory);
@@ -6586,8 +6587,9 @@ var ImageEditorController = class {
    * the document's size and bit depth (at `time` ms, default 0), placed like `addPixelLayer`. One
    * undo step. Masks, blend and opacity apply as to any layer. An effect with a background of its
    * own (`backgroundOpacity`) starts with it transparent when there are layers below it, unless
-   * `values` set it. `animate` makes it play when the document is output as an animation. Returns
-   * its id.
+   * `values` set it. `animate` makes it play when the document is output as an animation.
+   * `clipped` clips it to the layer below (a clipping mask) in the same step, so it only shows
+   * over that layer's pixels. Returns its id.
    */
   async addEffectLayer(effect, options = {}) {
     const d = await this.describeEffect(effect, "layer");
@@ -6598,6 +6600,7 @@ var ImageEditorController = class {
     const ids = new Set(flattenLayers(this.state.layers).map((l) => l.id));
     const id = options.id && !ids.has(options.id) ? options.id : newLayerId();
     const placed = placeLayer(this.state.layers, { type: "pixel", id, name: "", visible: true, opacity: 1, blend: "normal", surface: emptySurface(4), offset: { x: 0, y: 0 } }, this.newLayerPlacement(options));
+    if (options.clipped) requireClipBase(placed, id);
     const values = resolveEffectValues(d, withBackgroundOpacity(d, options.values, hasLayersBelow(placed, id)));
     const { width, height } = this.naturalSize;
     const pixels = await this.effectsEngine.renderLayer(d.id, values, { width, height, depth: this.bitDepth, time });
@@ -6610,7 +6613,8 @@ var ImageEditorController = class {
       blend: blend ?? "normal",
       surface: effectPixelsToSurface(pixels, this.bitDepth),
       offset: { x: 0, y: 0 },
-      generator: { effect: d.id, provider: this.effects.require().id, name: d.name, values, ...time ? { time } : {}, ...animate ? { animate } : {} }
+      generator: { effect: d.id, provider: this.effects.require().id, name: d.name, values, ...time ? { time } : {}, ...animate ? { animate } : {} },
+      ...options.clipped ? { clipped: true } : {}
     };
     const next = mapLayer(placed, id, () => layer);
     this.commitLayers(next, () => {
@@ -9763,6 +9767,7 @@ var ImageEditorController = class {
    * above the other adjustment layers (or, without any, above the topmost non-annotation layer,
    * so annotations stay on top); `index` counts adjustment layers (0 = below the others);
    * `aboveId` / `parentId` place it anywhere in the stack. `kind` alone gives neutral parameters.
+   * `clipped` clips it to the layer below in the same step, so it only adjusts that layer.
    */
   addAdjustmentLayer(init, index) {
     const spec = typeof init === "string" ? { kind: init } : init;
@@ -9778,14 +9783,17 @@ var ImageEditorController = class {
     });
     while (ids.has(layer.id)) layer.id = newLayerId("adj");
     const { width, height } = this.naturalSize;
-    this.recordHistory();
     const node = adjustmentNodeFromLegacy(layer, width, height);
+    if (spec.clipped) node.clipped = true;
     const positioned = Boolean(spec.aboveId || spec.parentId);
-    this.state.layers = this.placeLayer(this.state.layers, node, {
+    const placed = this.placeLayer(this.state.layers, node, {
       aboveId: spec.aboveId,
       parentId: spec.parentId,
       adjustmentIndex: index !== void 0 ? index : positioned ? void 0 : Infinity
     });
+    if (spec.clipped) requireClipBase(placed, node.id);
+    this.recordHistory();
+    this.state.layers = placed;
     this.notify();
     return layer.id;
   }
@@ -12652,6 +12660,9 @@ function serializeAdjustments(adjustments) {
   }
   return out;
 }
+function requireClipBase(layers, id) {
+  if (findLayer(layers, id)?.index === 0) throw new LayerOperationError("There is no layer below the new layer to clip it to: it would be the bottom layer of its group or the stack. Put it directly above the layer to clip to (aboveId), or leave clipped false.");
+}
 function withDevelop(layer, partial) {
   const filters = [...layer.filters ?? []];
   let i = filters.findIndex((f) => f.kind === "develop");
@@ -19713,7 +19724,7 @@ function createImageEditorToolProvider(controller, options = {}) {
   const addLayer = {
     name: "add_adjustment_layer",
     title: "Add an adjustment layer",
-    description: "Adds a non-destructive adjustment layer on top of the stack (one undoable step) and returns it; with a selection it is masked by it (useSelection, default true; masked in the result says so). Kinds: " + ADJUSTMENT_KINDS.map((k) => k.kind).join(", ") + ". Omitted params are neutral.",
+    description: "Adds a non-destructive adjustment layer on top of the stack (one undoable step) and returns it; with a selection it is masked by it (useSelection, default true; masked in the result says so). clipped clips it to the layer directly below in the same step, so it adjusts only that layer (clipped in the result). Kinds: " + ADJUSTMENT_KINDS.map((k) => k.kind).join(", ") + ". Omitted params are neutral.",
     inputSchema: {
       type: "object",
       properties: {
@@ -19724,7 +19735,8 @@ function createImageEditorToolProvider(controller, options = {}) {
         name: { type: "string", description: "Layer name shown in the layers panel." },
         aboveId: { type: "string", description: "Put the layer directly above this layer (from list_layers). Default: above the other adjustment layers, below annotations." },
         parentId: { type: "string", description: "Put the layer at the top of this group (from list_layers)." },
-        useSelection: { type: "boolean", description: "With a selection, mask the new layer with it so the adjustment only affects the selected area (default true; false for a global layer)." }
+        useSelection: { type: "boolean", description: "With a selection, mask the new layer with it so the adjustment only affects the selected area (default true; false for a global layer)." },
+        clipped: { type: "boolean", description: "Clip it to the layer directly below (a clipping mask) so it adjusts only that layer (default false). Use with aboveId; refused when nothing is below it in its group or the stack." }
       },
       required: ["kind"],
       additionalProperties: false
@@ -19736,7 +19748,7 @@ function createImageEditorToolProvider(controller, options = {}) {
       idempotentHint: false,
       openWorldHint: false
     },
-    handler: ({ kind, params, opacity, blend, name, aboveId, parentId, useSelection }) => {
+    handler: ({ kind, params, opacity, blend, name, aboveId, parentId, useSelection, clipped }) => {
       if (!isAdjustmentKind(kind)) throw new Error(`Unknown adjustment kind "${kind}".`);
       if (blend !== void 0 && !isBlendMode(blend)) throw new Error(`Unknown blend mode "${blend}".`);
       if (aboveId !== void 0 && parentId !== void 0) throw new Error("Give aboveId or parentId, not both.");
@@ -19744,9 +19756,9 @@ function createImageEditorToolProvider(controller, options = {}) {
         if (ref !== void 0 && !controller.getLayer(ref)) throw new Error(`Unknown layer "${ref}". Call list_layers for ids.`);
       }
       if (parentId !== void 0 && controller.getLayer(parentId)?.type !== "group") throw new Error(`Layer "${parentId}" is not a group.`);
-      const id = controller.addAdjustmentLayer({ kind, params, opacity, blend, name, aboveId, parentId, useSelection: useSelection !== false });
+      const id = controller.addAdjustmentLayer({ kind, params, opacity, blend, name, aboveId, parentId, useSelection: useSelection !== false, clipped: clipped === true });
       const layer = controller.getAdjustmentLayer(id);
-      return { layer: JSON.parse(JSON.stringify(layer)), index: controller.getAdjustmentLayers().findIndex((l) => l.id === id), masked: Boolean(layer.mask) };
+      return { layer: JSON.parse(JSON.stringify(layer)), index: controller.getAdjustmentLayers().findIndex((l) => l.id === id), masked: Boolean(layer.mask), clipped: Boolean(controller.getLayer(id)?.clipped) };
     }
   };
   const renderPreview = {
@@ -21776,6 +21788,7 @@ var FreeTransformTool = class {
 };
 
 // src/image-editor/provider-effect-tools.ts
+var FILTER_BLEND_SCHEMA = { type: "string", enum: BLEND_MODES.map((m) => m.id).filter((b) => b !== "pigment"), description: "How the effect's result blends with the layer below it in the stack (default normal)." };
 var ANIMATE_SCHEMA = {
   type: "object",
   properties: { duration: { type: "number", exclusiveMinimum: 0, maximum: MAX_EFFECT_ANIMATION_MS, description: `How long it plays in ms (at most ${MAX_EFFECT_ANIMATION_MS}).` } },
@@ -21789,7 +21802,7 @@ function imageLayerAppliedEffects(layer) {
   if (layer.type === "pixel" && layer.generator) out.push({ id: "generator", ...ref(layer.generator), role: "effect layer", enabled: true, values: layer.generator.values, ...layer.generator.time ? { time: layer.generator.time } : {}, ...layer.generator.animate ? { animate: layer.generator.animate } : {} });
   if (layer.type === "smart")
     (layer.smartFilters?.filters ?? []).forEach((f, index) => {
-      if (f.kind === "effect") out.push({ id: f.id, ...ref(f), role: "smart filter", enabled: f.enabled && layer.smartFilters.enabled, opacity: f.opacity, blend: f.blend, values: f.values, index });
+      if (f.kind === "effect") out.push({ id: f.id, ...ref(f), role: "smart filter", enabled: f.enabled && layer.smartFilters.enabled, opacity: f.opacity, blend: f.blend, preserveTransparency: Boolean(f.preserveTransparency), values: f.values, index });
     });
   return out;
 }
@@ -21819,27 +21832,35 @@ function createImageEffectsToolProvider(controller, options = {}) {
     skill: "pixerate-image-editor",
     target: { noun: "layer", id: "A layer id from list_layers." },
     applyUses: ["filter"],
-    applyDetails: "The effect becomes a smart filter: it runs on the layer's pixels after the smart filters below it, with its own blend and opacity, under the smart filter mask, and can be changed or removed later. A pixel, shape or type layer (or a group) is converted to a smart object first, in the same undo step (one layer keeps its id; the result says converted). With a selection, the filter mask is set from it in the same step, so the filter only changes the selected area (the result says masked); deselect first to filter the whole layer. Generators and overlays go on their own layer through add_effect_layer.",
+    applyDetails: "The effect becomes a smart filter: it runs on the layer's pixels after the smart filters below it, with its own blend and opacity, under the smart filter mask, and can be changed or removed later. It keeps the layer's transparency by default (preserveTransparency: the result only changes the layer's own pixels, never fills transparent ones); preserveTransparency false lets it draw over the whole canvas. A pixel, shape or type layer (or a group) is converted to a smart object first, in the same undo step (one layer keeps its id; the result says converted). With a selection, the filter mask is set from it in the same step, so the filter only changes the selected area (the result says masked); deselect first to filter the whole layer. Generators and overlays go on their own layer through add_effect_layer.",
     provider: () => controller.effectsProvider,
     readOnlyReason,
+    applyOptions: {
+      preserveTransparency: { type: "boolean", description: "Keep the layer's transparency: the result is drawn over the layer and takes its alpha, so transparent pixels stay transparent and only the layer's content changes (default true). false lets the effect's own alpha replace the layer's, so a shader can fill the empty area." },
+      blend: FILTER_BLEND_SCHEMA
+    },
+    updateOptions: {
+      preserveTransparency: { type: "boolean", description: "Keep the layer's transparency (true) or let the effect fill transparent pixels (false). Smart filters only." },
+      blend: FILTER_BLEND_SCHEMA
+    },
     list: (target) => {
       const layers = target ? [layerOf(target)] : flattenLayers(controller.getState().layers);
       return layers.map((l) => ({ target: l.id, ...l.name ? { name: l.name } : {}, effects: imageLayerAppliedEffects(l) })).filter((t) => target || t.effects.length);
     },
     apply: async (target, effect, args) => {
-      const r = await controller.applyEffectFilter(target, effect, { values: plainValues(args.values), index: args.index, enabled: args.enabled, opacity: args.opacity, useSelection: true });
+      const r = await controller.applyEffectFilter(target, effect, { values: plainValues(args.values), index: args.index, enabled: args.enabled, opacity: args.opacity, blend: args.blend, preserveTransparency: args.preserveTransparency !== false, useSelection: true });
       return result(r.layerId, r.filter.id, { converted: r.converted, masked: r.masked });
     },
     update: async (target, instance, changes) => {
       const layer = layerOf(target);
       if (instance === "generator") {
-        const extra = ["enabled", "opacity", "index"].filter((k) => changes[k] !== void 0);
+        const extra = ["enabled", "opacity", "index", "blend", "preserveTransparency"].filter((k) => changes[k] !== void 0);
         if (extra.length) throw new Error(`An effect layer's own effect only takes values; change the layer's ${extra.join(", ")} with update_layer.`);
         if (layer.type !== "pixel" || !layer.generator) throw new Error(`"${target}" is not an effect layer.`);
         await controller.updateEffectLayer(target, { values: changes.values });
         return result(target, "generator");
       }
-      await controller.updateEffectFilter(target, instance, { values: changes.values, enabled: changes.enabled, opacity: changes.opacity, index: changes.index });
+      await controller.updateEffectFilter(target, instance, { values: changes.values, enabled: changes.enabled, opacity: changes.opacity, index: changes.index, blend: changes.blend, preserveTransparency: changes.preserveTransparency });
       return result(target, instance);
     },
     remove: async (target, instance) => {
@@ -21855,7 +21876,7 @@ function createImageEffectsToolProvider(controller, options = {}) {
       {
         name: "add_effect_layer",
         title: "Add an effect layer",
-        description: `Adds a layer drawn by a provider generator, overlay or title effect (search_effects with use generator, overlay or title) at the document's size and bit depth, above the active layer unless placed. Masks, blend mode, opacity and layer styles apply as to any layer; transparent effects show the layers beneath, and an effect with its own background (describe_effect backgroundOpacity) starts with it transparent when there are layers below, unless values set it. animate makes it play when the document is output as an animation. set_effect_layer changes its effect, frame or animation; update_effect with effect "generator" draws it again with new values; remove_effect "generator" keeps its pixels as a plain layer. One undo step. Returns the new layer id and its effect.`,
+        description: `Adds a layer drawn by a provider generator, overlay or title effect (search_effects with use generator, overlay or title) at the document's size and bit depth, above the active layer unless placed. Masks, blend mode, opacity and layer styles apply as to any layer; transparent effects show the layers beneath, and an effect with its own background (describe_effect backgroundOpacity) starts with it transparent when there are layers below, unless values set it. animate makes it play when the document is output as an animation. clipped clips it to the layer directly below (a clipping mask) in the same step, so it only shows over that layer's pixels. set_effect_layer changes its effect, frame or animation; update_effect with effect "generator" draws it again with new values; remove_effect "generator" keeps its pixels as a plain layer. One undo step. Returns the new layer id, whether it is clipped, and its effect.`,
         inputSchema: {
           type: "object",
           properties: {
@@ -21867,7 +21888,8 @@ function createImageEffectsToolProvider(controller, options = {}) {
             aboveId: { type: "string", minLength: 1, description: "Put it directly above this layer (default: above the active layer, else on top)." },
             belowId: { type: "string", minLength: 1, description: "Put it directly below this layer." },
             opacity: { type: "number", minimum: 0, maximum: 1, description: "Layer opacity 0\u20131 (default 1)." },
-            blend: { type: "string", enum: BLEND_MODES.map((m) => m.id).filter((b) => b !== "pigment"), description: "Layer blend mode (default normal); screen or add for light effects, multiply for textures." }
+            blend: { type: "string", enum: BLEND_MODES.map((m) => m.id).filter((b) => b !== "pigment"), description: "Layer blend mode (default normal); screen or add for light effects, multiply for textures." },
+            clipped: { type: "boolean", description: "Clip it to the layer directly below (a clipping mask), so it only shows over that layer's pixels (default false). Refused when nothing is below it in its group or the stack." }
           },
           required: ["effect"],
           additionalProperties: false
@@ -21875,8 +21897,8 @@ function createImageEffectsToolProvider(controller, options = {}) {
         annotations: { title: "Add an effect layer", ...ctx.annotations.write },
         handler: async (args) => {
           ctx.requireProvider();
-          const id = await controller.addEffectLayer(args.effect, { values: plainValues(args.values), time: args.time, animate: args.animate, name: args.name, aboveId: args.aboveId, belowId: args.belowId, opacity: args.opacity, blend: args.blend });
-          return { layerId: id, effects: imageLayerAppliedEffects(layerOf(id)) };
+          const id = await controller.addEffectLayer(args.effect, { values: plainValues(args.values), time: args.time, animate: args.animate, name: args.name, aboveId: args.aboveId, belowId: args.belowId, opacity: args.opacity, blend: args.blend, clipped: args.clipped });
+          return { layerId: id, clipped: Boolean(layerOf(id).clipped), effects: imageLayerAppliedEffects(layerOf(id)) };
         }
       },
       {

package/dist/image-editor/layers/model.d.cts

@@ -465,6 +465,12 @@ export interface EffectSmartFilter {
     name?: string;
     /** Control values (over the effect's defaults). */
     values: Record<string, EffectValue>;
+    /**
+     * Keep the layer's transparency: the effect's result is drawn over its input and takes the
+     * input's alpha, so it never fills transparent pixels (before the filter's blend and opacity).
+     * Missing means false: the result's alpha replaces the input's.
+     */
+    preserveTransparency?: boolean;
 }
 /** One smart filter: a layer filter, a provider effect or a kept PSD filter, with its own blending over the result below it. */
 export type SmartFilter = (LayerFilter | PsdSmartFilter | EffectSmartFilter) & {

package/dist/image-editor/layers/model.d.ts

@@ -465,6 +465,12 @@ export interface EffectSmartFilter {
     name?: string;
     /** Control values (over the effect's defaults). */
     values: Record<string, EffectValue>;
+    /**
+     * Keep the layer's transparency: the effect's result is drawn over its input and takes the
+     * input's alpha, so it never fills transparent pixels (before the filter's blend and opacity).
+     * Missing means false: the result's alpha replaces the input's.
+     */
+    preserveTransparency?: boolean;
 }
 /** One smart filter: a layer filter, a provider effect or a kept PSD filter, with its own blending over the result below it. */
 export type SmartFilter = (LayerFilter | PsdSmartFilter | EffectSmartFilter) & {

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

@@ -40,6 +40,7 @@ import { type WetBackendInfo } from '../paint/wet/world.cjs';
 import { type TimeLapse, type TimeLapseOptions } from './replay.cjs';
 import { EffectsSlot } from '../effects/helpers.cjs';
 import type { EffectDescription, EffectProvider, EffectValue } from '../effects/types.cjs';
+import { type PaintEffectPaint } from './effect-paint.cjs';
 import { type PaintEffectPlace, type PaintEffectSource, type PaintPaperEffect, type PaperEffectBlend } from './effects.cjs';
 import { type PaintLighting } from './thick.cjs';
 /** A refusal with a message that says what is wrong and how to fix it. */
@@ -100,6 +101,13 @@ export interface PaintEditorState {
      * own gradient (`brush.paint`) paints that instead.
      */
     paint: PaintSource;
+    /**
+     * Effect paint (`setEffectPaint`): a provider effect strokes take each pixel's colour from,
+     * instead of `paint`; `null` when they paint `paint`. `setColor` and `setPaint` clear it.
+     */
+    effectPaint: PaintEffectPaint | null;
+    /** The effect paint is still rendering: strokes that would paint with it wait (they throw). */
+    effectPaintRendering: boolean;
     /** What the Mixer Brush carries between strokes. */
     mixerLoad: MixerLoad;
     view: PaintView;
@@ -145,10 +153,11 @@ export interface PaintStrokeInit {
     /** Default the editor colour. */
     color?: string;
     /**
-     * What this stroke paints with, instead of the editor's paint: a colour, or gradient paint
-     * (`@pixerate/editor/paint` `PaintSource`). A colour here is the same as `color`.
+     * What this stroke paints with, instead of the editor's paint: a colour, gradient paint
+     * (`@pixerate/editor/paint` `PaintSource`), or effect paint (render it first with
+     * `prepareEffectPaints`). A colour here is the same as `color`.
      */
-    paint?: PaintSource | string;
+    paint?: PaintSource | PaintEffectPaint | string;
     /** Default the active brush. */
     brushId?: string;
     /** Changes to the brush for this stroke only. */
@@ -256,6 +265,13 @@ export declare class PaintEditorController {
     private secondaryColor;
     /** Gradient paint chosen with `setPaint` (`null`: the paint colour). */
     private gradient;
+    /** Effect paint chosen with `setEffectPaint` (rendered), and one still rendering. */
+    private effectPaint;
+    private effectPaintPending;
+    /** Changes whenever the paint is chosen, so an effect paint that finishes rendering late does not take over. */
+    private paintEpoch;
+    /** Rendered effect paints by `effectPaintKey` (most recently used last). */
+    private readonly effectPaintPixels;
     private mixerLoad;
     private view;
     private hand;
@@ -508,6 +524,41 @@ export declare class PaintEditorController {
         layerId: string;
         source: PaintEffectSource;
     }>;
+    /** At most this many rendered effect paints are kept (each is canvas-sized). */
+    private static readonly EFFECT_PAINT_CACHE;
+    /** The effect paint strokes use (or the one rendering), or `null`. */
+    getEffectPaint(): PaintEffectPaint | null;
+    /**
+     * Paints with a provider generator, overlay or title effect: it is rendered once at the canvas
+     * size, and brushes then take each pixel's colour (and alpha) from it, fixed to the canvas, as if
+     * painting a hidden picture into view. `setColor` and `setPaint` go back to colour. Editor state,
+     * not an undo step. Strokes that would paint with it throw while it renders. Returns the paint.
+     */
+    setEffectPaint(source: {
+        effect: string;
+        values?: Record<string, EffectValue | null>;
+        time?: number;
+    }): Promise<PaintEffectPaint>;
+    /** The rendered pixels of an effect paint at the current canvas size, or `null` when it has not been rendered. */
+    private effectPaintImage;
+    /** Renders an effect paint at the canvas size into the cache (nothing when it is there already). */
+    private renderEffectPaint;
+    /**
+     * Renders effect paints that are not rendered yet (strokes and replays need them rendered
+     * first, since strokes are synchronous). Throws naming the effect and provider when one cannot be.
+     */
+    prepareEffectPaints(paints: Iterable<PaintEffectPaint>): Promise<void>;
+    /** Renders the effect paints of recorded strokes (default all of them) before a replay. */
+    prepareStrokeEffects(strokeIds?: readonly string[]): Promise<void>;
+    /** A small preview of the effect paint (a PNG data URL `size` px wide), or `null` without a rendered one. */
+    effectPaintThumbnail(size?: number): string | null;
+    /**
+     * The effect paint a stroke paints with and its pixels, or `null`: the stroke's own effect
+     * `paint`, else (without its own `paint` or `color`, and with no brush gradient) the editor's.
+     * Throws while the editor's is still rendering, for an engine that cannot paint with it, or when
+     * its pixels are not rendered.
+     */
+    private strokeEffect;
     /**
      * Runs a filter effect (light, glow, colour grade …) on a layer's dried paint and bakes it in, at
      * `amount` strength (0..1, default 1). Transparent areas stay transparent; thick paint keeps its

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

@@ -40,6 +40,7 @@ import { type WetBackendInfo } from '../paint/wet/world.js';
 import { type TimeLapse, type TimeLapseOptions } from './replay.js';
 import { EffectsSlot } from '../effects/helpers.js';
 import type { EffectDescription, EffectProvider, EffectValue } from '../effects/types.js';
+import { type PaintEffectPaint } from './effect-paint.js';
 import { type PaintEffectPlace, type PaintEffectSource, type PaintPaperEffect, type PaperEffectBlend } from './effects.js';
 import { type PaintLighting } from './thick.js';
 /** A refusal with a message that says what is wrong and how to fix it. */
@@ -100,6 +101,13 @@ export interface PaintEditorState {
      * own gradient (`brush.paint`) paints that instead.
      */
     paint: PaintSource;
+    /**
+     * Effect paint (`setEffectPaint`): a provider effect strokes take each pixel's colour from,
+     * instead of `paint`; `null` when they paint `paint`. `setColor` and `setPaint` clear it.
+     */
+    effectPaint: PaintEffectPaint | null;
+    /** The effect paint is still rendering: strokes that would paint with it wait (they throw). */
+    effectPaintRendering: boolean;
     /** What the Mixer Brush carries between strokes. */
     mixerLoad: MixerLoad;
     view: PaintView;
@@ -145,10 +153,11 @@ export interface PaintStrokeInit {
     /** Default the editor colour. */
     color?: string;
     /**
-     * What this stroke paints with, instead of the editor's paint: a colour, or gradient paint
-     * (`@pixerate/editor/paint` `PaintSource`). A colour here is the same as `color`.
+     * What this stroke paints with, instead of the editor's paint: a colour, gradient paint
+     * (`@pixerate/editor/paint` `PaintSource`), or effect paint (render it first with
+     * `prepareEffectPaints`). A colour here is the same as `color`.
      */
-    paint?: PaintSource | string;
+    paint?: PaintSource | PaintEffectPaint | string;
     /** Default the active brush. */
     brushId?: string;
     /** Changes to the brush for this stroke only. */
@@ -256,6 +265,13 @@ export declare class PaintEditorController {
     private secondaryColor;
     /** Gradient paint chosen with `setPaint` (`null`: the paint colour). */
     private gradient;
+    /** Effect paint chosen with `setEffectPaint` (rendered), and one still rendering. */
+    private effectPaint;
+    private effectPaintPending;
+    /** Changes whenever the paint is chosen, so an effect paint that finishes rendering late does not take over. */
+    private paintEpoch;
+    /** Rendered effect paints by `effectPaintKey` (most recently used last). */
+    private readonly effectPaintPixels;
     private mixerLoad;
     private view;
     private hand;
@@ -508,6 +524,41 @@ export declare class PaintEditorController {
         layerId: string;
         source: PaintEffectSource;
     }>;
+    /** At most this many rendered effect paints are kept (each is canvas-sized). */
+    private static readonly EFFECT_PAINT_CACHE;
+    /** The effect paint strokes use (or the one rendering), or `null`. */
+    getEffectPaint(): PaintEffectPaint | null;
+    /**
+     * Paints with a provider generator, overlay or title effect: it is rendered once at the canvas
+     * size, and brushes then take each pixel's colour (and alpha) from it, fixed to the canvas, as if
+     * painting a hidden picture into view. `setColor` and `setPaint` go back to colour. Editor state,
+     * not an undo step. Strokes that would paint with it throw while it renders. Returns the paint.
+     */
+    setEffectPaint(source: {
+        effect: string;
+        values?: Record<string, EffectValue | null>;
+        time?: number;
+    }): Promise<PaintEffectPaint>;
+    /** The rendered pixels of an effect paint at the current canvas size, or `null` when it has not been rendered. */
+    private effectPaintImage;
+    /** Renders an effect paint at the canvas size into the cache (nothing when it is there already). */
+    private renderEffectPaint;
+    /**
+     * Renders effect paints that are not rendered yet (strokes and replays need them rendered
+     * first, since strokes are synchronous). Throws naming the effect and provider when one cannot be.
+     */
+    prepareEffectPaints(paints: Iterable<PaintEffectPaint>): Promise<void>;
+    /** Renders the effect paints of recorded strokes (default all of them) before a replay. */
+    prepareStrokeEffects(strokeIds?: readonly string[]): Promise<void>;
+    /** A small preview of the effect paint (a PNG data URL `size` px wide), or `null` without a rendered one. */
+    effectPaintThumbnail(size?: number): string | null;
+    /**
+     * The effect paint a stroke paints with and its pixels, or `null`: the stroke's own effect
+     * `paint`, else (without its own `paint` or `color`, and with no brush gradient) the editor's.
+     * Throws while the editor's is still rendering, for an engine that cannot paint with it, or when
+     * its pixels are not rendered.
+     */
+    private strokeEffect;
     /**
      * Runs a filter effect (light, glow, colour grade …) on a layer's dried paint and bakes it in, at
      * `amount` strength (0..1, default 1). Transparent areas stay transparent; thick paint keeps its

package/dist/paint-editor/dab-stroke.d.cts

@@ -19,6 +19,7 @@ import { type MixerLoad, type MixingModel, type PaintTileTarget, type RgbTriple
 import type { RasterRect } from '../raster/surface.cjs';
 import { type PaintGradientSource } from '../paint/gradient-paint.cjs';
 import type { MultiColorSettings, PaintBrush } from './brushes.cjs';
+import { type EffectPaintPixels } from './effect-paint.cjs';
 import { type PenPoint, type StrokeCopy } from './engine.cjs';
 import { type PaperGrain } from './paper.cjs';
 export interface PaintDabStrokeOptions {
@@ -36,6 +37,8 @@ export interface PaintDabStrokeOptions {
     copies?: readonly StrokeCopy[];
     /** Gradient paint (resolved: no `paint` / `secondary` stops): each dab's colour comes from it. */
     paint?: PaintGradientSource | null;
+    /** Effect paint: each dab's colour (and flow, by alpha) is the effect's at the dab's centre. */
+    effect?: EffectPaintPixels | null;
 }
 /** Colours of a multi-colour brush, resolved against the paint and secondary colours. */
 export declare function multiColorPalette(mc: MultiColorSettings, color: RgbTriple, secondary: RgbTriple): RgbTriple[];

package/dist/paint-editor/dab-stroke.d.ts

@@ -19,6 +19,7 @@ import { type MixerLoad, type MixingModel, type PaintTileTarget, type RgbTriple
 import type { RasterRect } from '../raster/surface.js';
 import { type PaintGradientSource } from '../paint/gradient-paint.js';
 import type { MultiColorSettings, PaintBrush } from './brushes.js';
+import { type EffectPaintPixels } from './effect-paint.js';
 import { type PenPoint, type StrokeCopy } from './engine.js';
 import { type PaperGrain } from './paper.js';
 export interface PaintDabStrokeOptions {
@@ -36,6 +37,8 @@ export interface PaintDabStrokeOptions {
     copies?: readonly StrokeCopy[];
     /** Gradient paint (resolved: no `paint` / `secondary` stops): each dab's colour comes from it. */
     paint?: PaintGradientSource | null;
+    /** Effect paint: each dab's colour (and flow, by alpha) is the effect's at the dab's centre. */
+    effect?: EffectPaintPixels | null;
 }
 /** Colours of a multi-colour brush, resolved against the paint and secondary colours. */
 export declare function multiColorPalette(mc: MultiColorSettings, color: RgbTriple, secondary: RgbTriple): RgbTriple[];

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

@@ -0,0 +1,47 @@
+/**
+ * Effect paint: a provider generator, overlay or title effect that brushes paint with. The effect
+ * is rendered once at the canvas size when it is chosen; strokes then take each pixel's colour
+ * from that image, fixed to the canvas, as if painting a hidden picture into view. The effect's
+ * alpha multiplies the brush coverage, so a transparent part of an overlay paints nothing.
+ *
+ * Strokes are synchronous and effect renders are not, so the pixels are rendered (and cached by
+ * source) before a stroke can use them; a stroke records the source, and replays render any
+ * missing source before they paint.
+ *
+ * Kept out of the shared `PaintSource` union (`@pixerate/editor/paint`), which the image editor
+ * shares: only the paint editor paints with effects.
+ */
+import type { EffectValue } from '../effects/types.cjs';
+import type { RasterRect } from '../raster/surface.cjs';
+/** What strokes paint with when they paint with a provider effect. */
+export interface PaintEffectPaint {
+    type: 'effect';
+    /** The effect id (search_effects). */
+    effect: string;
+    /** The provider's id when it was chosen. */
+    provider: string;
+    /** Every control value. */
+    values: Record<string, EffectValue>;
+    /** Which moment of an animated effect, in ms. */
+    time: number;
+}
+/** Canvas-sized straight-alpha RGBA an effect paint was rendered to. */
+export interface EffectPaintPixels {
+    width: number;
+    height: number;
+    data: ArrayLike<number>;
+}
+/** The cache key of an effect paint (the same source renders the same pixels). */
+export declare function effectPaintKey(p: PaintEffectPaint): string;
+/** Whether a value is an effect paint (`{ type: 'effect', effect, … }`). */
+export declare function isPaintEffectPaint(raw: unknown): raw is PaintEffectPaint;
+/** A saved effect paint, or `null` when it is not one. */
+export declare function readPaintEffectPaint(raw: unknown): PaintEffectPaint | null;
+/**
+ * Takes a dab's colours from the effect: fills `field` (sRGB 0..1, 3 per pixel of `rect`, a
+ * document rectangle) with the effect's colour at each pixel and multiplies `vals` by its alpha.
+ * Pixels off the canvas paint nothing.
+ */
+export declare function sampleEffectField(img: EffectPaintPixels, rect: RasterRect, vals: Float32Array, field: Float32Array): void;
+/** The effect's colour (sRGB 0..1 into `out`) at a document point; returns its alpha 0..1 (0 off the canvas). */
+export declare function sampleEffectAt(img: EffectPaintPixels, x: number, y: number, out: [number, number, number]): number;

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

@@ -0,0 +1,47 @@
+/**
+ * Effect paint: a provider generator, overlay or title effect that brushes paint with. The effect
+ * is rendered once at the canvas size when it is chosen; strokes then take each pixel's colour
+ * from that image, fixed to the canvas, as if painting a hidden picture into view. The effect's
+ * alpha multiplies the brush coverage, so a transparent part of an overlay paints nothing.
+ *
+ * Strokes are synchronous and effect renders are not, so the pixels are rendered (and cached by
+ * source) before a stroke can use them; a stroke records the source, and replays render any
+ * missing source before they paint.
+ *
+ * Kept out of the shared `PaintSource` union (`@pixerate/editor/paint`), which the image editor
+ * shares: only the paint editor paints with effects.
+ */
+import type { EffectValue } from '../effects/types.js';
+import type { RasterRect } from '../raster/surface.js';
+/** What strokes paint with when they paint with a provider effect. */
+export interface PaintEffectPaint {
+    type: 'effect';
+    /** The effect id (search_effects). */
+    effect: string;
+    /** The provider's id when it was chosen. */
+    provider: string;
+    /** Every control value. */
+    values: Record<string, EffectValue>;
+    /** Which moment of an animated effect, in ms. */
+    time: number;
+}
+/** Canvas-sized straight-alpha RGBA an effect paint was rendered to. */
+export interface EffectPaintPixels {
+    width: number;
+    height: number;
+    data: ArrayLike<number>;
+}
+/** The cache key of an effect paint (the same source renders the same pixels). */
+export declare function effectPaintKey(p: PaintEffectPaint): string;
+/** Whether a value is an effect paint (`{ type: 'effect', effect, … }`). */
+export declare function isPaintEffectPaint(raw: unknown): raw is PaintEffectPaint;
+/** A saved effect paint, or `null` when it is not one. */
+export declare function readPaintEffectPaint(raw: unknown): PaintEffectPaint | null;
+/**
+ * Takes a dab's colours from the effect: fills `field` (sRGB 0..1, 3 per pixel of `rect`, a
+ * document rectangle) with the effect's colour at each pixel and multiplies `vals` by its alpha.
+ * Pixels off the canvas paint nothing.
+ */
+export declare function sampleEffectField(img: EffectPaintPixels, rect: RasterRect, vals: Float32Array, field: Float32Array): void;
+/** The effect's colour (sRGB 0..1 into `out`) at a document point; returns its alpha 0..1 (0 off the canvas). */
+export declare function sampleEffectAt(img: EffectPaintPixels, x: number, y: number, out: [number, number, number]): number;

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

@@ -1,8 +1,8 @@
 /**
  * Agent tools for provider effects in the paint editor: the shared effect tools, where
  * `apply_effect` runs a filter (light, glow, grade) on a layer's dried paint and bakes it in, and
- * the target `paper` is the effect paper; plus `set_paper_effect`, `add_effect_layer` and
- * `fill_layer_with_effect`.
+ * the target `paper` is the effect paper and the target `paint` the effect paint; plus
+ * `set_paper_effect`, `add_effect_layer`, `fill_layer_with_effect` and `set_effect_paint`.
  */
 import type { AgentToolProvider } from '../tools/registry.cjs';
 import type { PaintEditorController } from './controller.cjs';
@@ -21,5 +21,7 @@ export interface PaintEffectsToolProviderOptions {
 }
 /** The target id of the effect paper. */
 export declare const PAPER_TARGET = "paper";
+/** The target id of the effect paint (what brushes paint with). */
+export declare const PAINT_TARGET = "paint";
 /** The effect tools for a paint editor (see the module comment). */
 export declare function createPaintEffectsToolProvider(controller: PaintEditorController, options?: PaintEffectsToolProviderOptions): AgentToolProvider;