@pixerate/editor 0.226.0 → 0.227.0

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

@@ -40,6 +40,7 @@ export * from './stickers.cjs';
 export * from './procedural.cjs';
 export * from './sticker-tools.cjs';
 export * from './effects.cjs';
+export * from './effect-paint.cjs';
 export * from './effect-tools.cjs';
 export { WET_FLOW_KINDS, DEFAULT_FLOW, normalizeFlow, type WetFlowKind, type WetFlowSpec } from '../paint/wet/flow.cjs';
 export { DEFAULT_WET_PARAMS, WET_PARAM_KEYS, normalizeWetParams, type WetParams, type WetTilt } from '../paint/wet/model.cjs';

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

@@ -40,6 +40,7 @@ export * from './stickers.js';
 export * from './procedural.js';
 export * from './sticker-tools.js';
 export * from './effects.js';
+export * from './effect-paint.js';
 export * from './effect-tools.js';
 export { WET_FLOW_KINDS, DEFAULT_FLOW, normalizeFlow, type WetFlowKind, type WetFlowSpec } from '../paint/wet/flow.js';
 export { DEFAULT_WET_PARAMS, WET_PARAM_KEYS, normalizeWetParams, type WetParams, type WetTilt } from '../paint/wet/model.js';

package/dist/paint-editor/index.js

@@ -7,7 +7,7 @@ import {
   resolveExternalAssets,
   serializeLayers,
   serializeLayersExternal
-} from "../chunk-5YLOU7VF.js";
+} from "../chunk-KN3Y3FRY.js";
 import "../chunk-3CI7FRMK.js";
 import "../chunk-ZNA3IQZF.js";
 import {
@@ -58,7 +58,7 @@ import {
   realPresenceClock,
   tweenPresenceCursor
 } from "../chunk-IVSWRVB4.js";
-import "../chunk-NDMXB4PR.js";
+import "../chunk-CU6ANS5L.js";
 import {
   BRUSH_ID,
   BRUSH_ROTATIONS,
@@ -95,7 +95,9 @@ import {
   brushToJSON,
   clonePaper,
   drawSticker,
+  effectPaintKey,
   hexToRgb8,
+  isPaintEffectPaint,
   isWetBrush,
   isWetCapable,
   mixerTip,
@@ -115,15 +117,18 @@ import {
   paperPreset,
   parseBrushLibrary,
   penOrientation,
+  readPaintEffectPaint,
   renderPaper,
   renderStickers,
+  sampleEffectAt,
+  sampleEffectField,
   stampCoverage,
   stickerRect,
   stickerSurface,
   tiltToOrientation,
   toStrokePoint,
   usesPaintExchange
-} from "../chunk-F7YA3MMC.js";
+} from "../chunk-TQOL6CF7.js";
 import "../chunk-M6DNZNVY.js";
 import "../chunk-WEIK3UYB.js";
 import "../chunk-PWBZH3FK.js";
@@ -449,7 +454,11 @@ var PaintDabStroke = class {
     const ex = st.exchange;
     ex.pickUp(this.medium.sample(rect, tip));
     let flow = 1;
-    if (this.sampler && !this.gradient) {
+    if (this.options.effect) {
+      const rgb = [0, 0, 0];
+      flow = sampleEffectAt(this.options.effect, d.x, d.y, rgb);
+      ex.setReservoirColor(rgb[0], rgb[1], rgb[2]);
+    } else if (this.sampler && !this.gradient) {
       const g = this.sampler.dab(d, this.sample);
       ex.setReservoirColor(g.rgb[0], g.rgb[1], g.rgb[2]);
       flow = g.alpha;
@@ -984,6 +993,8 @@ var PaintStrokeSession = class {
     this.copies = init.copies.length ? init.copies : [IDENTITY_COPY];
     const brush = init.brush;
     if (init.wet) this.wetDriver = init.wet.driver;
+    const effect = init.effect?.pixels ?? null;
+    if (effect && (init.wet || init.thick || init.sticker)) throw new Error(`The ${brush.name} brush (${brush.engine} engine) cannot paint with effect paint.`);
     this.apply = {
       mode: brush.engine === "eraser" ? "erase" : "paint",
       color: init.color,
@@ -1011,10 +1022,11 @@ var PaintStrokeSession = class {
         paperDepth: init.paperDepth,
         seed: init.seed,
         copies: this.copies,
-        paint: init.paint ?? null
+        paint: init.paint ?? null,
+        effect
       });
     } else {
-      const opts = { grain: init.grain, paperDepth: init.paperDepth, seed: init.seed, copies: this.copies, paint: init.paint ?? null };
+      const opts = { grain: init.grain, paperDepth: init.paperDepth, seed: init.seed, copies: this.copies, paint: init.paint ?? null, effect };
       this.dry = brush.engine === "particle" ? new ParticleStroke(brush, opts) : brush.engine === "bristle" ? new BristleStroke(brush, opts) : new DryStroke(brush, opts);
     }
   }
@@ -1473,8 +1485,10 @@ function normalizeBrushStroke(raw) {
     }
     if (st.length) out.stencils = st;
   }
-  const paint = readPaintSource(r.paint);
-  if (paint && paint.type === "gradient") out.paint = paint;
+  const effect = readPaintEffectPaint(r.paint);
+  const paint = effect ? null : readPaintSource(r.paint);
+  if (effect) out.paint = effect;
+  else if (paint && paint.type === "gradient") out.paint = paint;
   if (Array.isArray(r.steps) && r.steps.length === points.length && r.steps.every((v) => Number.isInteger(v) && v >= 0)) out.steps = [...r.steps];
   return out;
 }
@@ -1512,7 +1526,7 @@ function varyStroke(stroke, m, v) {
   });
   const brush = s !== 1 ? normalizePaintBrush({ ...stroke.brush, tip: { ...stroke.brush.tip, size: stroke.brush.tip.size * s } }) : stroke.brush;
   const out = { ...stroke, brush, points };
-  if (stroke.paint && s !== 1) out.paint = scalePaintGradient(stroke.paint, s);
+  if (stroke.paint?.type === "gradient" && s !== 1) out.paint = scalePaintGradient(stroke.paint, s);
   if (stroke.copies?.length) {
     const inv = invertAffine(m);
     out.copies = stroke.copies.map((c) => composeAffine(m, composeAffine(c, inv)));
@@ -3091,6 +3105,7 @@ async function replayPainting(source, target, options = {}) {
   const maxStrokes = options.strokes ?? source.strokes.length;
   const chunk = Math.max(1, options.wetChunk ?? 0) || Infinity;
   let strokes = 0;
+  await target.prepareEffectPaints(source.strokes.slice(0, maxStrokes).flatMap((st) => st.paint?.type === "effect" ? [st.paint] : []));
   const advanceTo = async (clock) => {
     const now = target.getState().wet.clock;
     let left = clock - now;
@@ -3262,19 +3277,23 @@ var PAINT_EFFECT_PLACES = {
   /** An effect fill: composited onto a layer's pixels. */
   fill: ["generator", "overlay", "title"],
   /** Light (or any filter) on a layer's dried paint. */
-  light: ["filter"]
+  light: ["filter"],
+  /** Effect paint: brushes take each pixel's colour from it. */
+  paint: ["generator", "overlay", "title"]
 };
 var PLACE_WORDS = {
   paper: "effect paper takes generator effects",
   layer: "an effect layer takes generator, overlay or title effects",
   fill: "an effect fill takes generator, overlay or title effects",
-  light: "light on dried paint takes filter effects"
+  light: "light on dried paint takes filter effects",
+  paint: "effect paint takes generator, overlay or title effects"
 };
 function checkPaintEffectPlace(d, place) {
   const allowed = PAINT_EFFECT_PLACES[place];
   if (d.kind !== "motion" && d.kind !== "vector" && d.uses.some((u) => allowed.includes(u))) return;
   let instead = "";
-  if (d.uses.includes("filter") && place !== "light") instead = "; run it on a layer's dried paint with apply_effect instead";
+  if (d.uses.includes("filter") && place === "paint") instead = "; paint with a generator, overlay or title effect, or run the filter on the painted layer with apply_effect";
+  else if (d.uses.includes("filter") && place !== "light") instead = "; run it on a layer's dried paint with apply_effect instead";
   else if (place === "light" && d.uses.some((u) => PAINT_EFFECT_PLACES.layer.includes(u))) instead = "; add it as an effect layer (add_effect_layer) or fill a layer with it (fill_layer_with_effect) instead";
   else if (place === "paper" && d.uses.some((u) => u === "overlay" || u === "title")) instead = "; add it as an effect layer with add_effect_layer instead";
   throw new EffectUnsupportedError(`"${d.id}" (${d.name}) is a ${d.uses.join(" / ") || d.kind} effect, and ${PLACE_WORDS[place]}${instead}.`, d.id);
@@ -3418,6 +3437,13 @@ var PaintEditorController = class _PaintEditorController {
   secondaryColor = "#ffffff";
   /** Gradient paint chosen with `setPaint` (`null`: the paint colour). */
   gradient = null;
+  /** Effect paint chosen with `setEffectPaint` (rendered), and one still rendering. */
+  effectPaint = null;
+  effectPaintPending = null;
+  /** Changes whenever the paint is chosen, so an effect paint that finishes rendering late does not take over. */
+  paintEpoch = 0;
+  /** Rendered effect paints by `effectPaintKey` (most recently used last). */
+  effectPaintPixels = /* @__PURE__ */ new Map();
   mixerLoad = EMPTY_MIXER_LOAD;
   view = { ...DEFAULT_VIEW, pan: { ...DEFAULT_VIEW.pan } };
   hand;
@@ -3512,6 +3538,8 @@ var PaintEditorController = class _PaintEditorController {
       color: this.color,
       secondaryColor: this.secondaryColor,
       paint: this.gradient ?? { type: "color", color: this.color },
+      effectPaint: this.effectPaintPending ?? this.effectPaint,
+      effectPaintRendering: Boolean(this.effectPaintPending),
       mixerLoad: this.mixerLoad,
       view: this.view,
       hand: this.hand,
@@ -4296,6 +4324,141 @@ var PaintEditorController = class _PaintEditorController {
     this.commit("Effect fill", { ...this.doc, layers: mapLayer(this.doc.layers, now.id, () => ({ ...now, surface })) });
     return { layerId: now.id, source: this.sourceOf(d, values, options.time) };
   }
+  // --- Effect paint ----------------------------------------------------------------
+  /** At most this many rendered effect paints are kept (each is canvas-sized). */
+  static EFFECT_PAINT_CACHE = 6;
+  /** The effect paint strokes use (or the one rendering), or `null`. */
+  getEffectPaint() {
+    const p = this.effectPaintPending ?? this.effectPaint;
+    return p ? { ...p, values: JSON.parse(JSON.stringify(p.values)) } : 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.
+   */
+  async setEffectPaint(source) {
+    if (!source || typeof source.effect !== "string" || !source.effect) throw new PaintEditorError("effect is missing; pass an effect id from search_effects (use generator, overlay or title).");
+    this.checkTime(source.time);
+    const epoch = ++this.paintEpoch;
+    const changed = (name) => new PaintEditorError(`The paint changed while "${name}" rendered (set_color, set_paint or another set_effect_paint); call set_effect_paint again to paint with it.`);
+    const d = await this.describeEffect(source.effect, "paint");
+    const values = this.effectValues(d, { ...d.defaults }, source.values);
+    if (epoch !== this.paintEpoch) throw changed(d.name);
+    const paint = { type: "effect", effect: d.id, provider: this.effects.require().id, values, time: source.time ?? 0 };
+    this.effectPaintPending = paint;
+    this.emit([]);
+    try {
+      await this.renderEffectPaint(paint);
+    } catch (e) {
+      if (this.effectPaintPending === paint) {
+        this.effectPaintPending = null;
+        this.emit([]);
+      }
+      throw e;
+    }
+    if (this.effectPaintPending !== paint || epoch !== this.paintEpoch) throw changed(d.name);
+    this.effectPaintPending = null;
+    this.effectPaint = paint;
+    this.gradient = null;
+    this.emit([]);
+    return this.getEffectPaint();
+  }
+  /** The rendered pixels of an effect paint at the current canvas size, or `null` when it has not been rendered. */
+  effectPaintImage(p) {
+    const key = effectPaintKey(p);
+    const img = this.effectPaintPixels.get(key);
+    if (!img || img.width !== this.doc.canvas.width || img.height !== this.doc.canvas.height) return null;
+    this.effectPaintPixels.delete(key);
+    this.effectPaintPixels.set(key, img);
+    return img;
+  }
+  /** Renders an effect paint at the canvas size into the cache (nothing when it is there already). */
+  async renderEffectPaint(p) {
+    const have = this.effectPaintImage(p);
+    if (have) return have;
+    const provider = this.effects.provider;
+    const what = `the effect "${p.effect}"${p.provider ? ` from provider "${p.provider}"` : ""}`;
+    if (!provider) throw new PaintEditorError(`Effect paint needs ${what}, but no effects provider is registered; register it (setEffectsProvider) and try again.`);
+    if (p.provider && provider.id !== p.provider) throw new PaintEditorError(`Effect paint needs ${what}, but the registered provider is "${provider.id}"; register "${p.provider}" (setEffectsProvider) and try again.`);
+    const { width, height } = this.doc.canvas;
+    let pixels;
+    try {
+      pixels = await this.effectsRenderer.render(provider, p.effect, { width, height }, { time: p.time, values: p.values });
+    } catch (e) {
+      throw new PaintEditorError(`Effect paint could not render ${what}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const img = { width, height, data: new Uint8ClampedArray(pixels.data) };
+    this.effectPaintPixels.set(effectPaintKey(p), img);
+    while (this.effectPaintPixels.size > _PaintEditorController.EFFECT_PAINT_CACHE) this.effectPaintPixels.delete(this.effectPaintPixels.keys().next().value);
+    return img;
+  }
+  /**
+   * 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.
+   */
+  async prepareEffectPaints(paints) {
+    const seen = /* @__PURE__ */ new Set();
+    for (const p of paints) {
+      const key = effectPaintKey(p);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      await this.renderEffectPaint(p);
+    }
+  }
+  /** Renders the effect paints of recorded strokes (default all of them) before a replay. */
+  async prepareStrokeEffects(strokeIds) {
+    const ids = strokeIds ? new Set(strokeIds) : null;
+    const paints = this.doc.strokes.filter((s) => (!ids || ids.has(s.id)) && s.paint?.type === "effect").map((s) => s.paint);
+    await this.prepareEffectPaints(paints);
+  }
+  /** A small preview of the effect paint (a PNG data URL `size` px wide), or `null` without a rendered one. */
+  effectPaintThumbnail(size = 48) {
+    const p = this.effectPaint;
+    const img = p ? this.effectPaintImage(p) : null;
+    if (!img) return null;
+    const w = Math.max(1, Math.min(img.width, Math.round(size)));
+    const h = Math.max(1, Math.round(img.height / img.width * w));
+    const out = new Uint8ClampedArray(w * h * 4);
+    for (let y = 0; y < h; y++) {
+      const sy = Math.min(img.height - 1, Math.floor((y + 0.5) * img.height / h));
+      for (let x = 0; x < w; x++) {
+        const sx = Math.min(img.width - 1, Math.floor((x + 0.5) * img.width / w));
+        const i = (sy * img.width + sx) * 4;
+        const o = (y * w + x) * 4;
+        for (let c = 0; c < 4; c++) out[o + c] = img.data[i + c];
+      }
+    }
+    return pngDataUrl(w, h, out);
+  }
+  /**
+   * 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.
+   */
+  strokeEffect(init, brush) {
+    if (!brushTakesPaint(brush)) return null;
+    let source = null;
+    if (init.paint !== void 0) {
+      if (!isPaintEffectPaint(init.paint)) return null;
+      source = readPaintEffectPaint(init.paint);
+      if (!source) throw new PaintEditorError("The stroke's effect paint needs an effect id and values (getEffectPaint returns one).");
+    } else if (init.color === void 0 && !brush.paint) {
+      if (this.effectPaintPending) throw new PaintEditorError(`The effect paint "${this.effectPaintPending.effect}" is still rendering; wait for set_effect_paint to finish, then paint.`);
+      source = this.effectPaint;
+    }
+    if (!source) return null;
+    if (brush.engine === "wet" || brush.engine === "impasto" || brush.engine === "sticker") {
+      throw new PaintEditorError(
+        `The ${brush.name} brush (${brush.engine} engine) cannot paint with effect paint: it carries one colour as ${brush.engine === "sticker" ? "stickers" : brush.engine === "wet" ? "wet pigment" : "thick paint"}. Paint with a dry brush (a dab, particle, bristle or mixer brush), or paint the shape first and fill it with fill_layer_with_effect {lockTransparency: true}.`
+      );
+    }
+    const pixels = this.effectPaintImage(source);
+    if (!pixels) throw new PaintEditorError(`The effect paint "${source.effect}"${source.provider ? ` from provider "${source.provider}"` : ""} is not rendered at this canvas size; call set_effect_paint (or prepareEffectPaints) first.`);
+    return { source, pixels };
+  }
   /**
    * 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
@@ -4438,6 +4601,8 @@ var PaintEditorController = class _PaintEditorController {
   setColor(color) {
     this.color = parseColor(color);
     this.gradient = null;
+    this.effectPaint = this.effectPaintPending = null;
+    this.paintEpoch++;
     this.emit([]);
     return this.color;
   }
@@ -4460,6 +4625,8 @@ var PaintEditorController = class _PaintEditorController {
       return p;
     }
     this.gradient = p;
+    this.effectPaint = this.effectPaintPending = null;
+    this.paintEpoch++;
     this.emit([]);
     return p;
   }
@@ -4472,6 +4639,7 @@ var PaintEditorController = class _PaintEditorController {
     if (!brushTakesPaint(brush)) return null;
     let g = null;
     if (init.paint !== void 0) {
+      if (isPaintEffectPaint(init.paint)) return null;
       const p = this.readStrokePaint(init.paint);
       g = p.type === "gradient" ? p : null;
     } else g = brush.paint ?? (init.color === void 0 ? this.gradient : null);
@@ -4561,7 +4729,7 @@ var PaintEditorController = class _PaintEditorController {
     return symmetryCopies(this.guides.symmetry);
   }
   sessionFor(doc, init, host) {
-    if (init.paint !== void 0) {
+    if (init.paint !== void 0 && !isPaintEffectPaint(init.paint)) {
       const p = this.readStrokePaint(init.paint);
       if (p.type === "color") init = { ...init, color: p.color, paint: void 0 };
       else init = { ...init, paint: p };
@@ -4578,6 +4746,7 @@ var PaintEditorController = class _PaintEditorController {
       return l;
     })();
     const brush = this.strokeBrush(init);
+    const effect = this.strokeEffect(init, brush);
     const stickerLayer = Boolean(doc.stickers?.[layer.id]?.length);
     if (brush.engine === "sticker") {
       if (!stickerLayer && contentBounds(layer.surface)) throw new PaintEditorError(`Layer "${layer.name}" already has paint; spray stickers onto an empty layer (add_layer) so they stay editable.`);
@@ -4659,7 +4828,8 @@ var PaintEditorController = class _PaintEditorController {
       wet,
       thick: brush.engine === "impasto" ? { channels: doc.thick?.[layer.id] ?? emptyThickChannels() } : void 0,
       sticker: brush.engine === "sticker" ? { nextId: this.nextStickerNumber(doc) } : void 0,
-      paint: this.strokeGradient(init, brush, color)
+      paint: effect ? null : this.strokeGradient(init, brush, color),
+      effect
     });
     if (wet) this.wet.driver = wet.driver;
     if (init.maskStencils) session.maskStencils = init.maskStencils;
@@ -4676,7 +4846,8 @@ var PaintEditorController = class _PaintEditorController {
       seed: init.seed
     };
     if (init.affineCopies.length) stroke.copies = init.affineCopies.map((m) => [...m]);
-    if (init.paint) stroke.paint = JSON.parse(JSON.stringify(init.paint));
+    if (init.effect) stroke.paint = JSON.parse(JSON.stringify(init.effect.source));
+    else if (init.paint) stroke.paint = JSON.parse(JSON.stringify(init.paint));
     if (init.mixerLoad.reservoir || init.mixerLoad.pickup) stroke.load = JSON.parse(JSON.stringify(init.mixerLoad));
     if (init.wet) stroke.steps = [...init.wet.driver.steps];
     if (init.selection) {
@@ -4844,6 +5015,13 @@ var PaintEditorController = class _PaintEditorController {
     if (options.color !== void 0) parseColor(options.color);
     if (options.brushId !== void 0) this.requireBrush(options.brushId);
     if (options.layerId !== void 0) this.paintTarget(options.layerId, "replay onto");
+    if (options.color === void 0) {
+      for (const s of strokes) {
+        if (s.paint?.type === "effect" && !this.effectPaintImage(s.paint)) {
+          throw new PaintEditorError(`Stroke "${s.id}" paints with the effect "${s.paint.effect}"${s.paint.provider ? ` from provider "${s.paint.provider}"` : ""}, which is not rendered in this editor; render it first (prepareStrokeEffects; the replay_strokes tool does this) or recolour the replay with color.`);
+        }
+      }
+    }
     let origin = options.origin;
     if (!origin) {
       const b = strokeBounds(strokes.flatMap((s) => s.points));
@@ -4938,6 +5116,8 @@ var PaintEditorController = class _PaintEditorController {
     const paper = { ...this.doc.paper, scale: Math.min(8, this.doc.paper.scale * scale) };
     target.adopt({ state: { canvas: target.doc.canvas, paper, layers: emptiedLayers(this.doc.layers), activeLayerId: this.doc.activeLayerId, strokes: [] }, extensions: {}, problems: [] });
     target.lighting = { ...this.lighting };
+    target.effects.set(this.effects.provider);
+    if (w === width && h === height) for (const [key, img] of this.effectPaintPixels) target.effectPaintPixels.set(key, img);
     return target;
   }
   /**
@@ -4989,6 +5169,7 @@ var PaintEditorController = class _PaintEditorController {
   dispose() {
     this.wet.destroy();
     this.effectsRenderer.dispose();
+    this.effectPaintPixels.clear();
   }
   /** Resolves when wet paint is between steps (edits, undo and exports can run). */
   wetIdle() {
@@ -7833,7 +8014,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
   add({
     name: "set_color",
     title: "Set the paint colour",
-    description: "Sets the paint colour (and optionally the second colour) that strokes and fills use by default. Editor state, not an undo step. Returns both colours.",
+    description: "Sets the paint colour (and optionally the second colour) that strokes and fills use by default. Setting color goes back to one colour from gradient paint (set_paint) or effect paint (set_effect_paint). Editor state, not an undo step. Returns both colours.",
     inputSchema: {
       type: "object",
       properties: { color: { ...COLOR3, description: "Paint colour #rrggbb." }, secondaryColor: { ...COLOR3, description: "Second colour #rrggbb." } },
@@ -7850,7 +8031,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
   add({
     name: "set_paint",
     title: "Set the paint (colour or gradient)",
-    description: 'Sets what strokes paint with: one colour, or gradient paint that changes colour as the stroke goes. Gradient paint: 2..16 stops sorted by offset (#rrggbb, or "paint" / "secondary" for the two editor colours), space pigment (default: mixes like paint) / oklab / srgb, and map: distance (default: the colour changes as the stroke is dragged out, 300 px then mirrored back), pressure, tilt, velocity, direction, time, across-tip or random. Every stroking brush samples it per dab (dab, mixer, watercolour and gouache, oil and impasto, particle, bristle, sticker); erasers, blenders and smudges ignore it, and a brush with its own gradient (get_brush paint) paints that instead. set_color goes back to one colour. Editor state, not an undo step. Returns paint, color and secondaryColor.',
+    description: 'Sets what strokes paint with: one colour, or gradient paint that changes colour as the stroke goes. Gradient paint: 2..16 stops sorted by offset (#rrggbb, or "paint" / "secondary" for the two editor colours), space pigment (default: mixes like paint) / oklab / srgb, and map: distance (default: the colour changes as the stroke is dragged out, 300 px then mirrored back), pressure, tilt, velocity, direction, time, across-tip or random. Every stroking brush samples it per dab (dab, mixer, watercolour and gouache, oil and impasto, particle, bristle, sticker); erasers, blenders and smudges ignore it, and a brush with its own gradient (get_brush paint) paints that instead. It also ends effect paint (set_effect_paint); set_color goes back to one colour. Editor state, not an undo step. Returns paint, color and secondaryColor.',
     inputSchema: { type: "object", properties: { paint: PAINT_SOURCE_JSON_SCHEMA }, required: ["paint"], additionalProperties: false },
     annotations: { title: "Set the paint (colour or gradient)", ...SET4 },
     handler: ({ paint }) => {
@@ -8001,8 +8182,9 @@ function createPaintEditorToolProvider(controller, options = {}) {
     },
     annotations: { title: "Replay strokes, varied", ...WRITE5 },
     coordinates: { in: ["origin"], out: ["bounds"] },
-    handler: (a) => {
+    handler: async (a) => {
       const replay = a;
+      if (replay.color === void 0) await c.prepareStrokeEffects(replay.strokeIds);
       return act({ kind: "replay", replay }, () => c.replayStrokes(replay));
     }
   });
@@ -8692,6 +8874,7 @@ function quickStencil(kind, canvas) {
 
 // src/paint-editor/effect-tools.ts
 var PAPER_TARGET = "paper";
+var PAINT_TARGET = "paint";
 var ref = (s) => ({ effect: s.effect, ...s.name ? { name: s.name } : {}, ...s.provider ? { provider: s.provider } : {} });
 function createPaintEffectsToolProvider(controller, options = {}) {
   const readOnlyReason = () => {
@@ -8702,6 +8885,10 @@ function createPaintEffectsToolProvider(controller, options = {}) {
     const p = controller.getPaperEffect();
     return p ? [{ id: PAPER_TARGET, ...ref(p), role: "effect paper", enabled: true, opacity: p.opacity, blend: p.blend, values: p.values, ...p.time ? { time: p.time } : {} }] : [];
   };
+  const paintInfo = () => {
+    const p = controller.getEffectPaint();
+    return p ? [{ id: PAINT_TARGET, effect: p.effect, provider: p.provider, role: controller.getState().effectPaintRendering ? "effect paint (rendering)" : "effect paint", enabled: true, values: p.values, ...p.time ? { time: p.time } : {} }] : [];
+  };
   const layerInfo = (layerId) => {
     const s = controller.getEffectLayer(layerId);
     return s ? [{ id: "effect", ...ref(s), role: "effect layer", enabled: true, values: s.values, ...s.time ? { time: s.time } : {} }] : [];
@@ -8714,14 +8901,14 @@ function createPaintEffectsToolProvider(controller, options = {}) {
     }
     return l;
   };
-  const effectsOf = (target) => target === PAPER_TARGET ? paperInfo() : layerInfo(target);
+  const effectsOf = (target) => target === PAPER_TARGET ? paperInfo() : target === PAINT_TARGET ? paintInfo() : layerInfo(target);
   const instanceCheck = (target, instance) => {
-    const want = target === PAPER_TARGET ? PAPER_TARGET : "effect";
-    if (target !== PAPER_TARGET) requireLayer(target);
+    const want = target === PAPER_TARGET || target === PAINT_TARGET ? target : "effect";
+    if (target !== PAPER_TARGET && target !== PAINT_TARGET) requireLayer(target);
     if (instance !== want || !effectsOf(target).length) {
       const have = effectsOf(target).map((e) => `"${e.id}"`);
       throw new Error(
-        `${target === PAPER_TARGET ? "The paper" : `Layer "${target}"`} has no provider effect "${instance}"; its effects are ${have.join(", ") || "none"} (list_applied_effects). Light baked into paint is part of the pixels: undo takes it back.`
+        `${target === PAPER_TARGET ? "The paper" : target === PAINT_TARGET ? "The paint" : `Layer "${target}"`} has no provider effect "${instance}"; its effects are ${have.join(", ") || "none"} (list_applied_effects). Light baked into paint is part of the pixels: undo takes it back.`
       );
     }
   };
@@ -8736,24 +8923,27 @@ function createPaintEffectsToolProvider(controller, options = {}) {
     title: "Paint effects",
     description: "Provider effects on paint layers and on the effect paper.",
     skill: "pixerate-paint-editor",
-    target: { noun: "layer", id: `A pixel layer id from list_layers ("${PAPER_TARGET}" is the effect paper, for list, update and remove).` },
+    target: { noun: "layer", id: `A pixel layer id from list_layers ("${PAPER_TARGET}" is the effect paper and "${PAINT_TARGET}" the effect paint, for list, update and remove).` },
     applyUses: ["filter"],
     applyDetails: "Light on dried paint: the filter (search_effects with use filter, e.g. a light, glow or grade) runs on the layer's paint at the canvas size and is baked into its pixels; transparent areas stay transparent, and thick paint keeps its relief (an effect with a height input gets it). opacity is the strength (default 1). Wet paint is refused: dry it first (dry_paint). It is one undo step and is not listed afterwards (it is part of the pixels). Generators go on the paper (set_paper_effect), on their own layer (add_effect_layer) or into a layer (fill_layer_with_effect).",
     provider: () => controller.effectsProvider,
     readOnlyReason,
     list: (target) => {
       if (target === PAPER_TARGET) return [{ target: PAPER_TARGET, name: "Paper", effects: paperInfo() }];
+      if (target === PAINT_TARGET) return [{ target: PAINT_TARGET, name: "Paint", effects: paintInfo() }];
       if (target) {
         const l = requireLayer(target);
         return [{ target, name: l.name, effects: layerInfo(target) }];
       }
       const out = [];
+      if (paintInfo().length) out.push({ target: PAINT_TARGET, name: "Paint", effects: paintInfo() });
       if (paperInfo().length) out.push({ target: PAPER_TARGET, name: "Paper", effects: paperInfo() });
       for (const e of controller.listEffectLayers()) out.push({ target: e.layerId, name: e.name, effects: layerInfo(e.layerId) });
       return out;
     },
     apply: async (target, effect, args) => {
       if (target === PAPER_TARGET) throw new Error("The paper takes generator effects through set_paper_effect; apply_effect runs a filter on a layer's paint.");
+      if (target === PAINT_TARGET) throw new Error("Brushes paint with an effect through set_effect_paint; apply_effect runs a filter on a layer's paint.");
       noStackArgs(args);
       requireLayer(target);
       const r = await controller.applyLightEffect(target, effect, { values: values(args.values), amount: args.opacity });
@@ -8763,6 +8953,13 @@ function createPaintEffectsToolProvider(controller, options = {}) {
     update: async (target, instance, changes) => {
       instanceCheck(target, instance);
       noStackArgs(changes);
+      if (target === PAINT_TARGET) {
+        if (changes.opacity !== void 0) throw new Error("opacity does not apply to the effect paint: change the brush opacity (set_brush tip.opacity).");
+        const p = controller.getEffectPaint();
+        await controller.setEffectPaint({ effect: p.effect, values: { ...p.values, ...changes.values ?? {} }, time: p.time });
+        const effects2 = paintInfo();
+        return { target, effect: effects2[0], effects: effects2 };
+      }
       if (target === PAPER_TARGET) {
         await controller.updatePaperEffect({ values: changes.values, opacity: changes.opacity });
         const effects2 = paperInfo();
@@ -8776,6 +8973,10 @@ function createPaintEffectsToolProvider(controller, options = {}) {
     remove: async (target, instance) => {
       instanceCheck(target, instance);
       const was = effectsOf(target)[0];
+      if (target === PAINT_TARGET) {
+        controller.setColor(controller.getState().color);
+        return { target, effect: was, effects: [] };
+      }
       if (target === PAPER_TARGET) await controller.setPaperEffect(null);
       else controller.rasterizeEffectLayer(target);
       return { target, effect: was, effects: [], ...target === PAPER_TARGET ? {} : { keptPixels: true } };
@@ -8811,6 +9012,26 @@ function createPaintEffectsToolProvider(controller, options = {}) {
           return { paperEffect: await controller.setPaperEffect(args.effect, { values: values(args.values), opacity: args.opacity, blend: args.blend, time: args.time }) };
         }
       },
+      {
+        name: "set_effect_paint",
+        title: "Paint with an effect",
+        description: `Makes brushes paint with a provider generator, overlay or title effect (search_effects with use generator, overlay or title): it is rendered once at the canvas size, and each stroke then takes every pixel's colour from it, fixed to the canvas, as if painting a hidden picture into view (the effect's transparency paints nothing). Dab, particle and bristle brushes take the colour per pixel; mixer brushes and dab brushes that pick up paint take it per dab, at its centre. Wet, impasto and sticker brushes refuse it (paint the shape and use fill_layer_with_effect with lockTransparency instead); erasers, blenders and smudges ignore it. It replaces the paint colour or gradient until set_color or set_paint; a brush with its own gradient paints that instead. Strokes record it and replay exactly. Editor state, not an undo step. Returns the effect paint: { effect, provider, values (every control), time } (list_applied_effects target "paint" shows it; update_effect / remove_effect with target and effect "paint" change or clear it).`,
+        inputSchema: {
+          type: "object",
+          properties: {
+            effect: ctx.effectIdSchema(["generator", "overlay", "title"]),
+            values: ctx.valuesSchema("Control values over the effect's defaults"),
+            time: { type: "number", minimum: 0, description: "Which moment of an animated effect to paint with, in ms (default 0)." }
+          },
+          required: ["effect"],
+          additionalProperties: false
+        },
+        annotations: { title: "Paint with an effect", ...ctx.annotations.writeIdempotent },
+        handler: async (args) => {
+          ctx.requireProvider();
+          return { effectPaint: await controller.setEffectPaint({ effect: args.effect, values: values(args.values), time: args.time }) };
+        }
+      },
       {
         name: "add_effect_layer",
         title: "Add an effect layer",
@@ -8960,6 +9181,7 @@ export {
   PAINT_GRADIENT_SPACE_LABELS,
   PAINT_SCHEMA_VERSION,
   PAINT_SOURCE_JSON_SCHEMA,
+  PAINT_TARGET,
   PAINT_TOOLS,
   PAPER_EFFECT_BLENDS,
   PAPER_EFFECT_NODE_ID,
@@ -9052,6 +9274,7 @@ export {
   drawSticker,
   drawWaterOverlay,
   effectLayersToJSON,
+  effectPaintKey,
   emptiedLayers,
   emptyThickChannels,
   fitZoom,
@@ -9068,6 +9291,7 @@ export {
   invertAffine,
   isBlendMode,
   isGradientPaint,
+  isPaintEffectPaint,
   isPainterlyBlendMode,
   isPalmTouch,
   isWetBrush,
@@ -9134,6 +9358,7 @@ export {
   quickStencil,
   rand01,
   randSigned,
+  readPaintEffectPaint,
   readPaintEffectSource,
   readPaintSource,
   readPath,
@@ -9152,6 +9377,8 @@ export {
   rgbToHexColor,
   rgbToHsl,
   rgbToHsv,
+  sampleEffectAt,
+  sampleEffectField,
   samplePressure,
   scalePaintGradient,
   scaleStencil,

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

@@ -21,6 +21,7 @@ import { CoverageMap } from '../paint/brush.cjs';
 import { type PaintGradientSource } from '../paint/gradient-paint.cjs';
 import type { RasterRect } from '../raster/surface.cjs';
 import type { PaintBrush } from './brushes.cjs';
+import { type EffectPaintPixels } from './effect-paint.cjs';
 import { PenDabWalker, PenSmoother, type PenDab, type PenPoint, type StrokeCopy } from './engine.cjs';
 import { type PaperGrain } from './paper.cjs';
 export interface ProceduralStrokeOptions {
@@ -30,6 +31,8 @@ export interface ProceduralStrokeOptions {
     copies?: readonly StrokeCopy[];
     /** Gradient paint (resolved): each mark takes the colour of the pen dab that made it. */
     paint?: PaintGradientSource | null;
+    /** Effect paint: each pixel of a mark takes its colour (and alpha) from these canvas-sized pixels. */
+    effect?: EffectPaintPixels | null;
 }
 /** What a coverage-building stroke engine provides to the stroke session. */
 export interface CoverageStroke {
@@ -49,6 +52,7 @@ declare abstract class MarkStroke implements CoverageStroke {
     protected readonly walkers: PenDabWalker[];
     protected readonly depth: number;
     private buf;
+    private field;
     private lastRaw;
     private lastFed;
     protected readonly seed: number;

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

@@ -21,6 +21,7 @@ import { CoverageMap } from '../paint/brush.js';
 import { type PaintGradientSource } from '../paint/gradient-paint.js';
 import type { RasterRect } from '../raster/surface.js';
 import type { PaintBrush } from './brushes.js';
+import { type EffectPaintPixels } from './effect-paint.js';
 import { PenDabWalker, PenSmoother, type PenDab, type PenPoint, type StrokeCopy } from './engine.js';
 import { type PaperGrain } from './paper.js';
 export interface ProceduralStrokeOptions {
@@ -30,6 +31,8 @@ export interface ProceduralStrokeOptions {
     copies?: readonly StrokeCopy[];
     /** Gradient paint (resolved): each mark takes the colour of the pen dab that made it. */
     paint?: PaintGradientSource | null;
+    /** Effect paint: each pixel of a mark takes its colour (and alpha) from these canvas-sized pixels. */
+    effect?: EffectPaintPixels | null;
 }
 /** What a coverage-building stroke engine provides to the stroke session. */
 export interface CoverageStroke {
@@ -49,6 +52,7 @@ declare abstract class MarkStroke implements CoverageStroke {
     protected readonly walkers: PenDabWalker[];
     protected readonly depth: number;
     private buf;
+    private field;
     private lastRaw;
     private lastFed;
     protected readonly seed: number;