@pixerate/editor 0.240.0 → 0.242.0

package/dist/paint-editor/index.js

@@ -1,13 +1,13 @@
 import {
   toVideoFfmpeg
-} from "../chunk-WDDUPWVG.js";
+} from "../chunk-L3JFOTBQ.js";
 import {
   deserializeLayers,
   exportPsd,
   resolveExternalAssets,
   serializeLayers,
   serializeLayersExternal
-} from "../chunk-3E36VDMJ.js";
+} from "../chunk-NE6OOKWJ.js";
 import "../chunk-3CI7FRMK.js";
 import "../chunk-ZNA3IQZF.js";
 import {
@@ -55,7 +55,7 @@ import {
   realPresenceClock,
   tweenPresenceCursor
 } from "../chunk-IVSWRVB4.js";
-import "../chunk-7YGBSFC6.js";
+import "../chunk-ILM6GYAX.js";
 import {
   BRUSH_ID,
   BRUSH_ROTATIONS,
@@ -72,6 +72,8 @@ import {
   DEFAULT_STICKER,
   DEFAULT_WET_BRUSH,
   DryStroke,
+  EFFECT_MAP_REPEATS,
+  EFFECT_STRIP_HEIGHT,
   IDENTITY_COPY,
   IMPASTO_TOOLS,
   MULTI_COLOR_MODES,
@@ -92,7 +94,9 @@ import {
   brushToJSON,
   clonePaper,
   drawSticker,
+  effectDabField,
   effectPaintKey,
+  effectPaintSize,
   hexToRgb8,
   isPaintEffectPaint,
   isWetBrush,
@@ -114,6 +118,7 @@ import {
   paperPreset,
   parseBrushLibrary,
   penOrientation,
+  readEffectStrokeMap,
   readPaintEffectPaint,
   renderPaper,
   renderStickers,
@@ -126,7 +131,7 @@ import {
   tiltToOrientation,
   toStrokePoint,
   usesPaintExchange
-} from "../chunk-PJYG6FCF.js";
+} from "../chunk-XBZK47LV.js";
 import "../chunk-M6DNZNVY.js";
 import "../chunk-WEIK3UYB.js";
 import "../chunk-PWBZH3FK.js";
@@ -138,7 +143,7 @@ import {
   EffectsSlot,
   createEffectToolProvider,
   resolveEffectValues
-} from "../chunk-SIK3LT6M.js";
+} from "../chunk-OFH6Q67U.js";
 import "../chunk-V2ZCJRDM.js";
 import {
   CoverageMap,
@@ -458,7 +463,7 @@ var PaintDabStroke = class {
     let flow = 1;
     if (this.options.effect) {
       const rgb = [0, 0, 0];
-      flow = sampleEffectAt(this.options.effect, d.x, d.y, rgb);
+      flow = sampleEffectAt(this.options.effect, d.x, d.y, rgb, d);
       ex.setReservoirColor(rgb[0], rgb[1], rgb[2]);
     } else if (this.sampler && !this.gradient) {
       const g = this.sampler.dab(d, this.sample);
@@ -711,6 +716,7 @@ var ThickStrokeDriver = class {
   height = /* @__PURE__ */ new Map();
   material = /* @__PURE__ */ new Map();
   paint = [0, 0, 0];
+  centre = [0, 0, 0];
   tip = new Float32Array(0);
   lastRaw = null;
   lastFed = null;
@@ -837,7 +843,11 @@ var ThickStrokeDriver = class {
     }
     const ex = st.exchange;
     let flow = 1;
-    if (this.sampler) {
+    const effect = this.init.effect;
+    if (effect) {
+      sampleEffectAt(effect, d.x, d.y, this.centre, d);
+      ex.setReservoirColor(this.centre[0], this.centre[1], this.centre[2]);
+    } else if (this.sampler) {
       const g = this.sampler.dab(d, this.sample);
       ex.setReservoirColor(g.rgb[0], g.rgb[1], g.rgb[2]);
       flow = g.alpha;
@@ -849,7 +859,12 @@ var ThickStrokeDriver = class {
     if (dep > 0) {
       const cov = new Float32Array(n);
       for (let p = 0; p < n; p++) cov[p] = tip[p] > 0 ? Math.min(1, tip[p] * (im.tool === "roller" || im.tool === "gloop" || im.tool === "tube" ? 1.6 : 1.1)) : 0;
-      this.medium.deposit(rect, cov, dep, this.paint, ex.paintPigment);
+      let field = null;
+      if (effect) {
+        field = new Float32Array(n * 3);
+        effectDabField(effect, rect, cov, this.centre, this.paint, field, 0, d);
+      }
+      this.medium.deposit(rect, cov, dep, this.paint, ex.paintPigment, field);
     }
     const seed = this.init.seed;
     for (let yy = 0, p = 0; yy < rect.height; yy++) {
@@ -996,7 +1011,6 @@ var PaintStrokeSession = class {
     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,
@@ -1009,10 +1023,10 @@ var PaintStrokeSession = class {
     };
     if (this.wetDriver) {
     } else if (init.sticker) {
-      this.stickerSpray = new StickerSpray({ brush, target: this.tileTarget(), color: init.colorHex, seed: init.seed, copies: this.copies, nextId: init.sticker.nextId, paint: init.paint ?? null });
+      this.stickerSpray = new StickerSpray({ brush, target: this.tileTarget(), color: init.colorHex, seed: init.seed, copies: this.copies, nextId: init.sticker.nextId, paint: init.paint ?? null, effect });
     } else if (init.thick) {
       const rgb = (c) => [c[0] / 255, c[1] / 255, c[2] / 255];
-      this.thickDriver = new ThickStrokeDriver({ brush, target: this.tileTarget(), channels: init.thick.channels, color: rgb(init.color), load: init.mixerLoad, seed: init.seed, copies: this.copies, paint: init.paint ?? null });
+      this.thickDriver = new ThickStrokeDriver({ brush, target: this.tileTarget(), channels: init.thick.channels, color: rgb(init.color), load: init.mixerLoad, seed: init.seed, copies: this.copies, paint: init.paint ?? null, effect });
     } else if (brush.engine === "mixer" || brush.engine === "blender" || brush.engine === "smudge" || usesPaintExchange(brush, Boolean(init.paint))) {
       const rgb = (c) => [c[0] / 255, c[1] / 255, c[2] / 255];
       this.wet = new PaintDabStroke(brush, {
@@ -1530,6 +1544,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?.type === "gradient" && s !== 1) out.paint = scalePaintGradient(stroke.paint, s);
+  if (stroke.paint?.type === "effect" && stroke.paint.map && s !== 1) out.paint = { ...stroke.paint, map: { ...stroke.paint.map, length: Math.min(4096, Math.max(16, Math.round(stroke.paint.map.length * s))) } };
   if (stroke.copies?.length) {
     const inv = invertAffine(m);
     out.copies = stroke.copies.map((c) => composeAffine(m, composeAffine(c, inv)));
@@ -1941,6 +1956,7 @@ var WetStrokeDriver = class {
   tip = new Float32Array(0);
   cov = new Float32Array(0);
   paint = [0, 0, 0];
+  centre = [0, 0, 0];
   depth;
   sampler;
   sample = { rgb: [0, 0, 0], alpha: 1 };
@@ -2041,14 +2057,23 @@ var WetStrokeDriver = class {
       case "paint": {
         const ex = st.exchange;
         let flow = 1;
-        if (this.sampler) {
+        const effect = this.init.effect;
+        if (effect) {
+          sampleEffectAt(effect, d.x, d.y, this.centre, d);
+          ex.setReservoirColor(this.centre[0], this.centre[1], this.centre[2]);
+        } else if (this.sampler) {
           const g = this.sampler.dab(d, this.sample);
           ex.setReservoirColor(g.rgb[0], g.rgb[1], g.rgb[2]);
           flow = g.alpha;
         }
         ex.pickUp(this.medium.sample(rect, tip));
         const total = ex.paint(this.paint);
-        if (total > 0 && flow > 0) this.medium.deposit(rect, cov, Math.min(1, total) * k * flow, this.paint, null);
+        if (total > 0 && flow > 0 && effect) {
+          const ec = cov.slice();
+          const field = new Float32Array(ec.length * 3);
+          effectDabField(effect, rect, ec, this.centre, this.paint, field, COVERAGE_STEPS, d);
+          this.medium.deposit(rect, ec, Math.min(1, total) * k, this.paint, null, field);
+        } else if (total > 0 && flow > 0) this.medium.deposit(rect, cov, Math.min(1, total) * k * flow, this.paint, null);
         else world.paint(laneId, rect, cov, this.medium.options.water * k, null);
         ex.drain();
         if (wet.rewet > 0) world.rewet(laneId, rect, cov, wet.rewet * k * 0.15, this.init.paperColor);
@@ -3510,6 +3535,15 @@ var PaintEditorController = class _PaintEditorController {
   dirty = "all";
   seedCounter = 1;
   strokeCounter = 1;
+  /** Live effect paint: playing and the frame rate cap (editor state), and the time the view shows. */
+  effectPlaybackState = { playing: true, fps: 30 };
+  effectTime = 0;
+  /** While a frame is drawn: the time live effect strokes are drawn at (else their own time). */
+  liveEffectAt = null;
+  /** The view's stroke layers at `effectTime`, each with the document surface it was drawn from (stale once that changes). */
+  animatedLayers = /* @__PURE__ */ new Map();
+  /** `renderAnimationFrame` / `withEffectTime`: layer surfaces at another time, for one render. */
+  frameOverride = null;
   /** The area each stroke painted (document pixels; `null`: nothing), learnt as it is painted or drawn, so a stroke layer edit redraws only where it changes (see `drawLiveStrokes`). */
   paintedBounds = /* @__PURE__ */ new WeakMap();
   guides;
@@ -3598,6 +3632,7 @@ var PaintEditorController = class _PaintEditorController {
       mixerLoad: this.mixerLoad,
       view: this.view,
       hand: this.hand,
+      effectPlayback: { ...this.effectPlaybackState, time: this.effectTime },
       selectedStroke: this.selectedStroke,
       selectedSticker: this.selectedSticker,
       canUndo: this.undoStack.length > 0 && !this.session,
@@ -4401,16 +4436,25 @@ var PaintEditorController = class _PaintEditorController {
    * 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.
+   * With `map: { by: 'stroke' }` the effect lies along each stroke instead of the canvas; with
+   * `live`, strokes on a stroke layer keep playing it (see `setEffectPlayback`).
    */
   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);
+    let map;
+    try {
+      map = readEffectStrokeMap(source.map);
+    } catch (e) {
+      throw new PaintEditorError(e.message);
+    }
+    if (source.live !== void 0 && typeof source.live !== "boolean") throw new PaintEditorError("live must be true or false.");
     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 };
+    const paint = { type: "effect", effect: d.id, provider: this.effects.require().id, values, time: source.time ?? 0, ...map ? { map } : {}, ...source.live ? { live: true } : {} };
     this.effectPaintPending = paint;
     this.emit([]);
     try {
@@ -4433,7 +4477,8 @@ var PaintEditorController = class _PaintEditorController {
   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;
+    const size = effectPaintSize(p, this.doc.canvas);
+    if (!img || img.width !== size.width || img.height !== size.height) return null;
     this.effectPaintPixels.delete(key);
     this.effectPaintPixels.set(key, img);
     return img;
@@ -4446,14 +4491,14 @@ var PaintEditorController = class _PaintEditorController {
     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;
+    const { width, height } = effectPaintSize(p, 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) };
+    const img = { width, height, data: new Uint8ClampedArray(pixels.data), ...p.map ? { map: p.map } : {} };
     this.effectPaintPixels.set(effectPaintKey(p), img);
     while (this.effectPaintPixels.size > _PaintEditorController.EFFECT_PAINT_CACHE) this.effectPaintPixels.delete(this.effectPaintPixels.keys().next().value);
     return img;
@@ -4514,11 +4559,6 @@ var PaintEditorController = class _PaintEditorController {
       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 };
@@ -4815,6 +4855,13 @@ var PaintEditorController = class _PaintEditorController {
       const why = liveStrokeRefusal(brush);
       if (why) throw new PaintEditorError(`Layer "${layer.name}" is a stroke layer. ${why}`);
     }
+    if (doc.liveStrokes?.[layer.id] && effect?.source.live) {
+      const key = effectPaintKey(effect.source);
+      const { sources } = this.liveEffects(doc);
+      if (!sources.some((p) => effectPaintKey(p) === key) && sources.length >= MAX_LIVE_EFFECT_SOURCES) {
+        throw new PaintEditorError(`The painting already plays ${MAX_LIVE_EFFECT_SOURCES} live effects, the most it can; paint with one of them, or set_effect_paint with live false to bake this one.`);
+      }
+    }
     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.`);
@@ -4854,7 +4901,8 @@ var PaintEditorController = class _PaintEditorController {
         seed: seedW,
         copies: [IDENTITY_AFFINE, ...copiesW].map(affineCopy),
         mask: init.maskStencils ? this.stencilSelection(init.maskStencils) : init.stencils !== false ? this.stencilSelection() : null,
-        paint: wetGradient
+        paint: effect ? null : wetGradient,
+        effect: effect?.pixels ?? null
       });
       init = { ...init, seed: seedW, load };
       wet = { driver, surface: () => world.display(id).surface };
@@ -5418,8 +5466,10 @@ var PaintEditorController = class _PaintEditorController {
   }
   /** The layers with the live stroke's surface in place. */
   currentLayers() {
+    const override = this.frameOverride;
+    if (override) return Array.from(override).reduce((ls, [id, surface]) => mapLayer(ls, id, (l) => ({ ...l, surface })), this.doc.layers);
     const live = this.live;
-    if (!live) return this.doc.layers;
+    if (!live) return this.animatedView();
     if (this.liveLayers?.key === live.surface) return this.liveLayers.layers;
     const layers = mapLayer(this.doc.layers, live.layerId, (l) => ({ ...l, surface: live.surface }));
     this.liveLayers = { key: live.surface, layers };
@@ -6357,11 +6407,13 @@ var PaintEditorController = class _PaintEditorController {
         if (!cancelled && drawn) out = drawn;
       }
     };
-    const init = { layerId: plain.id, color: st.color, brush: st.brush, seed: st.seed, copies: st.copies ?? [], ...st.load ? { load: st.load } : {}, ...st.paint ? { paint: st.paint } : {}, snapToPerspective: false, stencils: false, maskStencils: st.stencils ?? [] };
+    const paint = st.paint && this.liveEffectAt !== null && isLiveEffect(st) ? framePaint(st.paint, this.liveEffectAt) : st.paint;
+    const init = { layerId: plain.id, color: st.color, brush: st.brush, seed: st.seed, copies: st.copies ?? [], ...st.load ? { load: st.load } : {}, ...paint ? { paint } : {}, snapToPerspective: false, stencils: false, maskStencils: st.stencils ?? [] };
     const session = this.sessionFor({ ...doc, layers: mapLayer(doc.layers, plain.id, () => ({ ...plain, surface })) }, init, host);
     session.push(st.points);
     const result = session.end();
-    this.paintedBounds.set(st, result.bounds);
+    const had = this.paintedBounds.get(st);
+    this.paintedBounds.set(st, had && result.bounds ? unionRect(had, result.bounds) : result.bounds ?? had ?? null);
     return { surface: out, bounds: result.bounds };
   }
   /**
@@ -6398,6 +6450,146 @@ var PaintEditorController = class _PaintEditorController {
     for (const r of rects) surface = writeRegion(surface, r, readRegion(drawn, r));
     return surface;
   }
+  // --- Live effect paint ------------------------------------------------------------
+  /** The view's layers: stroke layers playing live effects at `effectTime`, the rest as they are. */
+  animatedView() {
+    if (!this.animatedLayers.size) return this.doc.layers;
+    let layers = this.doc.layers;
+    for (const [id, a] of this.animatedLayers) {
+      const l = findLayer(layers, id)?.layer;
+      if (isPixelLayer(l) && l.surface === a.base) layers = mapLayer(layers, id, () => ({ ...l, surface: a.surface }));
+    }
+    return layers;
+  }
+  /** Stroke layers with live effect strokes, and the distinct live sources (frame 0). */
+  liveEffects(doc = this.doc) {
+    const layers = [];
+    const sources = /* @__PURE__ */ new Map();
+    for (const [id, strokes] of Object.entries(doc.liveStrokes ?? {})) {
+      const layer = findLayer(doc.layers, id)?.layer;
+      const live = strokes.filter(isLiveEffect);
+      if (!isPixelLayer(layer) || !live.length) continue;
+      layers.push({ layer, strokes });
+      for (const st of live) sources.set(effectPaintKey(st.paint), st.paint);
+    }
+    return { layers, sources: [...sources.values()] };
+  }
+  /** What plays: the live effect strokes and their layers, or `null` when nothing does. */
+  getAnimation() {
+    const { layers, sources } = this.liveEffects();
+    if (!layers.length) return null;
+    return { layerIds: layers.map((x) => x.layer.id), strokes: layers.reduce((n, x) => n + x.strokes.filter(isLiveEffect).length, 0), sources: sources.length };
+  }
+  /** Plays or pauses live effect paint, and caps its frame rate (1..60). Editor state, not an undo step. */
+  setEffectPlayback(update) {
+    if (update.playing !== void 0 && typeof update.playing !== "boolean") throw new PaintEditorError("playing must be true or false.");
+    if (update.fps !== void 0 && !(Number.isInteger(update.fps) && update.fps >= 1 && update.fps <= 60)) throw new PaintEditorError(`fps ${update.fps} is out of range; use a whole number 1..60.`);
+    this.effectPlaybackState = { ...this.effectPlaybackState, ...update };
+    this.emit([]);
+    return { ...this.effectPlaybackState, time: this.effectTime };
+  }
+  /** The surfaces of every stroke layer with live effects at `time` ms, drawn in full (frames rendered first). */
+  async liveSurfacesAt(time) {
+    const { layers, sources } = this.liveEffects();
+    await this.prepareEffectPaints(sources.map((p) => framePaint(p, time)));
+    const out = /* @__PURE__ */ new Map();
+    this.liveEffectAt = time;
+    try {
+      for (const { layer, strokes } of layers) out.set(layer.id, this.drawLiveStrokes({ ...layer, offset: { x: 0, y: 0 } }, strokes));
+    } finally {
+      this.liveEffectAt = null;
+    }
+    return out;
+  }
+  /**
+   * Shows the live effects at `time` ms (each live stroke's effect at its own time plus `time`):
+   * renders their frames, then redraws only where live effect strokes paint. Nothing in the
+   * document changes. Resolves `false` when the document changed while frames rendered (the next
+   * frame catches up).
+   */
+  async showEffectTime(time) {
+    this.checkTime(time);
+    const { layers, sources } = this.liveEffects();
+    const revision = this.docRevision;
+    await this.prepareEffectPaints(sources.map((p) => framePaint(p, time)));
+    if (revision !== this.docRevision || this.session) return false;
+    const next = /* @__PURE__ */ new Map();
+    const dirty = [];
+    this.liveEffectAt = time;
+    try {
+      for (const { layer, strokes } of layers) {
+        const shown = this.animatedLayers.get(layer.id);
+        const from = shown && shown.base === layer.surface ? shown.surface : layer.surface;
+        const areas = strokes.filter(isLiveEffect).flatMap((st) => [liveStrokeBounds(st), ...this.paintedBounds.get(st) ? [this.paintedBounds.get(st)] : []]);
+        const surface = this.drawLiveStrokes({ ...layer, surface: from, offset: { x: 0, y: 0 } }, strokes, layer.offset.x || layer.offset.y ? null : areas);
+        next.set(layer.id, { base: layer.surface, surface });
+        dirty.push(...areas);
+      }
+    } finally {
+      this.liveEffectAt = null;
+    }
+    this.animatedLayers = next;
+    this.effectTime = time;
+    this.emit(dirty);
+    return true;
+  }
+  /**
+   * Plays live effect paint in the view until `stop`: a frame per tick of `clock` (default
+   * animation frames) at most `fps` a second, one render in flight. Idle while paused, while a
+   * stroke is painted, or when nothing is live. The bindings start it while the editor is shown.
+   */
+  playEffects(clock = defaultEffectClock) {
+    let stopped = false;
+    let cancel = () => {
+    };
+    let last = -Infinity;
+    let started = clock.now() - this.effectTime;
+    const tick = () => {
+      if (stopped) return;
+      const now = clock.now();
+      const { playing, fps } = this.effectPlaybackState;
+      if (!playing) started = now - this.effectTime;
+      if (!playing || this.session || now - last < 1e3 / fps - 1 || !this.liveEffects().layers.length) {
+        cancel = clock.frame(tick);
+        return;
+      }
+      last = now;
+      this.showEffectTime(Math.max(0, now - started)).then(
+        () => {
+          if (!stopped) cancel = clock.frame(tick);
+        },
+        () => {
+          if (!stopped) cancel = clock.frame(tick);
+        }
+      );
+    };
+    cancel = clock.frame(tick);
+    return {
+      stop() {
+        stopped = true;
+        cancel();
+      }
+    };
+  }
+  /**
+   * Runs `fn` with the painting as it is `time` ms into its live effects (see `getAnimation`): for
+   * exports at a moment. Nothing in the document changes.
+   */
+  async withEffectTime(time, fn) {
+    this.checkTime(time);
+    const surfaces = await this.liveSurfacesAt(time);
+    const was = this.frameOverride;
+    this.frameOverride = surfaces;
+    try {
+      return await fn();
+    } finally {
+      this.frameOverride = was;
+    }
+  }
+  /** The painting composited `time` ms into its live effects, like `compositePixels`. Nothing in the document changes. */
+  async renderAnimationFrame(time, options = {}) {
+    return this.withEffectTime(time, () => this.compositePixels(options));
+  }
   // --- Stencils --------------------------------------------------------------------
   stencilCache = null;
   nextStencilId = 1;
@@ -6615,6 +6807,24 @@ var PaintEditorController = class _PaintEditorController {
 var MAX_IMAGE_SIDE = 8192;
 var movePoint = (p, dx, dy) => ({ x: p.x + dx, y: p.y + dy });
 var moveRect = (r, dx, dy) => ({ ...r, x: r.x + dx, y: r.y + dy });
+function isLiveEffect(s) {
+  return s.paint?.type === "effect" && s.paint.live === true;
+}
+function framePaint(p, t) {
+  return { ...p, time: p.time + t };
+}
+var MAX_LIVE_EFFECT_SOURCES = 8;
+var defaultEffectClock = {
+  now: () => typeof performance !== "undefined" ? performance.now() : Date.now(),
+  frame: (cb) => {
+    if (typeof requestAnimationFrame === "undefined") {
+      const t = setTimeout(cb, 16);
+      return () => clearTimeout(t);
+    }
+    const id = requestAnimationFrame(cb);
+    return () => cancelAnimationFrame(id);
+  }
+};
 function clipRect(r, width, height) {
   const x0 = Math.max(0, Math.floor(r.x));
   const y0 = Math.max(0, Math.floor(r.y));
@@ -8068,6 +8278,7 @@ var BRUSH_FIELDS = {
   sticker: STICKER_BRUSH,
   paint: BRUSH_PAINT
 };
+var TIME = { type: "number", minimum: 0, description: "Draw live effect paint (strokes on stroke layers painted with live effect paint) this many ms into its animation (default: as painted, its own time)." };
 var POINTS = {
   type: "array",
   minItems: 1,
@@ -8904,20 +9115,22 @@ function createPaintEditorToolProvider(controller, options = {}) {
   add({
     name: "export_image",
     title: "Export the painting",
-    description: "Exports the painting as PNG, JPEG or WebP (base64). JPEG always includes the paper; JPEG and WebP need a browser canvas. Changes nothing. Returns the data, its MIME type and size.",
+    description: "Exports the painting as PNG, JPEG or WebP (base64). JPEG always includes the paper; JPEG and WebP need a browser canvas. With time, live effect paint is drawn at that moment (get_effect_playback / set_effect_playback). Changes nothing. Returns the data, its MIME type and size.",
     inputSchema: {
       type: "object",
       properties: {
         format: { type: "string", enum: ["image/png", "image/jpeg", "image/webp"], description: "File type (default image/png)." },
         quality: { type: "number", minimum: 0, maximum: 1, description: "JPEG / WebP quality 0..1 (default 0.92)." },
         scale: { type: "number", exclusiveMinimum: 0, maximum: 1, description: "Shrink by this factor (default 1)." },
-        paper: { type: "boolean", description: "Include the paper (default true)." }
+        paper: { type: "boolean", description: "Include the paper (default true)." },
+        time: TIME
       },
       additionalProperties: false
     },
     annotations: { title: "Export the painting", ...READ6 },
-    handler: async ({ format, quality, scale, paper }) => {
-      const bytes = await c.exportImage({ format, quality, scale, paper });
+    handler: async ({ format, quality, scale, paper, time }) => {
+      const run = () => c.exportImage({ format, quality, scale, paper });
+      const bytes = time === void 0 ? await run() : await c.withEffectTime(time, run);
       return { mimeType: format ?? "image/png", bytes: bytes.length, data: bytesToBase64(bytes) };
     }
   });
@@ -8925,10 +9138,10 @@ function createPaintEditorToolProvider(controller, options = {}) {
     name: "export_psd",
     title: "Export as PSD",
     description: 'Writes the painting as an 8-bit RGB PSD (PSB above 30000 px) through the shared PSD writer: every layer and group with its opacity, blend, mask and locks, the paper as a locked "Paper" pixel layer at the bottom, and the composite as the merged image. Changes nothing. Returns the file as base64, its size, whether it is a PSB, and warnings (pigment and painterly blend modes have no PSD equivalent: they are written as the nearest standard mode, see list_blend_modes).',
-    inputSchema: EMPTY3,
+    inputSchema: { type: "object", properties: { time: TIME }, additionalProperties: false },
     annotations: { title: "Export as PSD", ...READ6 },
-    handler: () => {
-      const r = c.exportPsd();
+    handler: async ({ time }) => {
+      const r = time === void 0 ? c.exportPsd() : await c.withEffectTime(time, () => c.exportPsd());
       return { data: bytesToBase64(r.bytes), bytes: r.bytes.length, psb: r.psb, warnings: r.warnings };
     }
   });
@@ -9660,7 +9873,7 @@ function createPaintEffectsToolProvider(controller, options = {}) {
   };
   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 } : {} }] : [];
+    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 } : {}, ...p.map ? { map: p.map } : {}, ...p.live ? { live: true } : {} }] : [];
   };
   const layerInfo = (layerId) => {
     const s = controller.getEffectLayer(layerId);
@@ -9729,7 +9942,7 @@ function createPaintEffectsToolProvider(controller, options = {}) {
       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 });
+        await controller.setEffectPaint({ effect: p.effect, values: { ...p.values, ...changes.values ?? {} }, time: p.time, map: p.map, live: p.live });
         const effects2 = paintInfo();
         return { target, effect: effects2[0], effects: effects2 };
       }
@@ -9788,13 +10001,25 @@ function createPaintEffectsToolProvider(controller, options = {}) {
       {
         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).`,
+        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. Watercolour, gouache, oil and impasto brushes take it per pixel too, shifted by paint they pick up (in wet paint the pattern then flows with the water; impasto keeps its relief), and sprayed stickers take the colour at their centre. 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)." }
+            time: { type: "number", minimum: 0, description: "Which moment of an animated effect to paint with, in ms (default 0)." },
+            map: {
+              type: "object",
+              description: "How the effect lies on the paint: by canvas (default: fixed to the canvas, painting reveals a hidden picture) or by stroke (along each stroke: the effect is rendered as a strip length px long, and each pixel takes the colour at its distance along the stroke and its place across the tip).",
+              properties: {
+                by: { type: "string", enum: ["canvas", "stroke"], description: "canvas (default) or stroke." },
+                length: { type: "number", minimum: 16, maximum: 4096, description: "by stroke: px of stroke per repeat of the effect (default 300)." },
+                repeat: { type: "string", enum: ["repeat", "mirror", "clamp"], description: "by stroke: past the strip end start again (default), run back, or hold the last colour." }
+              },
+              required: ["by"],
+              additionalProperties: false
+            },
+            live: { type: "boolean", description: "Live effect paint (default false): strokes on a stroke layer (add_layer type strokes) keep playing the effect, so the paint moves (set_effect_playback); elsewhere strokes bake the frame at time." }
           },
           required: ["effect"],
           additionalProperties: false
@@ -9802,9 +10027,24 @@ function createPaintEffectsToolProvider(controller, options = {}) {
         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 }) };
+          return { effectPaint: await controller.setEffectPaint({ effect: args.effect, values: values(args.values), time: args.time, map: args.map, live: args.live }) };
         }
       },
+      {
+        name: "set_effect_playback",
+        title: "Play or pause live effect paint",
+        description: "Plays or pauses live effect paint (strokes painted on stroke layers with set_effect_paint live true) in the editor view, and caps its frame rate. Exports draw it at a chosen time with export_image / export_psd time. Editor state, not an undo step. Returns playing, fps, the time the view shows (ms) and what plays (animation: layer ids, live strokes, sources; null when nothing does).",
+        inputSchema: {
+          type: "object",
+          properties: {
+            playing: { type: "boolean", description: "Play (true, the default state) or pause at the current frame." },
+            fps: { type: "integer", minimum: 1, maximum: 60, description: "Frame rate cap, frames a second (default 30); lower it on large canvases." }
+          },
+          additionalProperties: false
+        },
+        annotations: { title: "Play or pause live effect paint", ...ctx.annotations.writeIdempotent },
+        handler: async (args) => ({ ...controller.setEffectPlayback({ playing: args.playing, fps: args.fps }), animation: controller.getAnimation() })
+      },
       {
         name: "add_effect_layer",
         title: "Add an effect layer",
@@ -9914,6 +10154,8 @@ export {
   DEFAULT_WET_BRUSH,
   DEFAULT_WET_PARAMS,
   DryStroke,
+  EFFECT_MAP_REPEATS,
+  EFFECT_STRIP_HEIGHT,
   GPU_LEAD,
   GRAIN_PATTERNS,
   GRAIN_TILE,
@@ -9929,6 +10171,7 @@ export {
   MAX_CANVAS_SIDE,
   MAX_COORDINATE,
   MAX_IMAGE_SIDE,
+  MAX_LIVE_EFFECT_SOURCES,
   MAX_ZOOM,
   MIN_CANVAS_SIDE,
   MIN_ZOOM,
@@ -10048,8 +10291,10 @@ export {
   downsampleRgba,
   drawSticker,
   drawWaterOverlay,
+  effectDabField,
   effectLayersToJSON,
   effectPaintKey,
+  effectPaintSize,
   emptiedLayers,
   emptyThickChannels,
   fitZoom,
@@ -10135,6 +10380,7 @@ export {
   quickStencil,
   rand01,
   randSigned,
+  readEffectStrokeMap,
   readPaintEffectPaint,
   readPaintEffectSource,
   readPaintSource,

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

@@ -14,6 +14,7 @@ import { TileMedium, type PaintTileTarget } from '../paint/exchange.cjs';
 import { type PaintGradientSource } from '../paint/gradient-paint.cjs';
 import type { PaintBrush } from './brushes.cjs';
 import { type PenPoint, type StrokeCopy } from './engine.cjs';
+import { type EffectPaintPixels } from './effect-paint.cjs';
 export type StampKind = 'dot' | 'star' | 'heart' | 'leaf' | 'flower' | 'confetti' | 'splat' | 'sparkle' | 'ring';
 export declare const STAMP_KINDS: readonly StampKind[];
 /** One sticker (document pixels). */
@@ -73,6 +74,11 @@ export interface StickerSprayInit {
     nextId: number;
     /** Gradient paint (resolved): each sticker takes its dab's colour (across the tip: by its offset). */
     paint?: PaintGradientSource | null;
+    /**
+     * Effect paint: each sticker takes the effect's colour at its centre (it keeps one colour, so it
+     * stays recolourable); none lands where the effect is transparent.
+     */
+    effect?: EffectPaintPixels | null;
 }
 /** A sticker-spray stroke: drops stickers along the path and draws them as it goes. */
 export declare class StickerSpray {