@pixerate/editor 0.270.0 → 0.272.0

package/dist/paint-editor/index.js

@@ -6,12 +6,13 @@ import {
   BRUSH_PATCH_PROPERTIES,
   BRUSH_SLIDERS,
   BRUSH_UNSET_PROPERTY,
+  GHOST_SLIDERS,
   brushEngineControls,
   createBrushLibraryToolProvider,
   mergeBrushPatch,
   multiColorSliders,
   patchBrushValue
-} from "../chunk-ININNHLM.js";
+} from "../chunk-NAHJV3O6.js";
 import {
   createStickerTools,
   describeStickerRef
@@ -19,10 +20,10 @@ import {
 import {
   BRUSH_PREVIEW_DARK_PAPER,
   brushPreviewsOnDark
-} from "../chunk-LETF75CA.js";
+} from "../chunk-CLB2I2FU.js";
 import {
   toVideoFfmpeg
-} from "../chunk-MWUZCEFT.js";
+} from "../chunk-S2XPXA47.js";
 import {
   ToolRegistry
 } from "../chunk-K4BGRCSH.js";
@@ -34,7 +35,7 @@ import {
   resolveExternalAssets,
   serializeLayers,
   serializeLayersExternal
-} from "../chunk-4YSPQGZW.js";
+} from "../chunk-5HP2VSAS.js";
 import "../chunk-ADMRNWR7.js";
 import "../chunk-WJ4WQJCC.js";
 import {
@@ -79,6 +80,7 @@ import {
   EFFECT_STRIP_HEIGHT,
   GPU_LEAD,
   IDENTITY_COPY,
+  MAX_EFFECT_PATH_POINTS,
   PAPER_FAMILIES,
   PAPER_LIBRARY,
   PaintDabStroke,
@@ -95,6 +97,7 @@ import {
   effectPaintKey,
   effectPaintSize,
   hexToRgb8,
+  inferEffectPathControl,
   isPaintEffectPaint,
   mixerTip,
   multiColorForDab,
@@ -109,11 +112,13 @@ import {
   sampleEffectAt,
   sampleEffectField,
   stampSampler,
+  strokePathPoints,
   tiltToOrientation,
   toStrokePoint,
   wetPaperInput,
-  wetPigmentOf
-} from "../chunk-FUDP5QBB.js";
+  wetPigmentOf,
+  withStrokePath
+} from "../chunk-ZEI7ZEA4.js";
 import {
   BRUSH_ID,
   BRUSH_PRESETS,
@@ -125,6 +130,7 @@ import {
   DEFAULT_BRISTLE,
   DEFAULT_BRUSH_ID,
   DEFAULT_DYNAMICS,
+  DEFAULT_GHOST,
   DEFAULT_IMPASTO,
   DEFAULT_LIGHT,
   DEFAULT_MULTI_COLOR,
@@ -164,6 +170,7 @@ import {
   normalizeBristle,
   normalizeBrushSpec,
   normalizeDynamics,
+  normalizeGhost,
   normalizeImpasto,
   normalizeLight,
   normalizeMultiColor,
@@ -176,7 +183,7 @@ import {
   readBrushSource,
   resolveBrush,
   usesPaintExchange
-} from "../chunk-KZI3YWKW.js";
+} from "../chunk-UXYCY3HP.js";
 import {
   STAMP_KINDS,
   StickersSlot,
@@ -201,11 +208,12 @@ import {
 } from "../chunk-SZTI6EER.js";
 import {
   EffectRendererPool
-} from "../chunk-EHLOCVWB.js";
+} from "../chunk-T2URHAJX.js";
 import {
   EffectUnsupportedError,
   EffectsSlot,
   createEffectToolProvider,
+  pathControlsOf,
   resolveEffectValues
 } from "../chunk-MV7CYFMJ.js";
 import "../chunk-V2ZCJRDM.js";
@@ -223,7 +231,7 @@ import {
   normalizeWetParams,
   pigmentOf,
   wetSupport
-} from "../chunk-GSTSZPSR.js";
+} from "../chunk-N3SKPQEH.js";
 import "../chunk-W6JDUXP3.js";
 import {
   CoverageMap,
@@ -2103,7 +2111,6 @@ var PaintStrokeSession = class _PaintStrokeSession {
     const brush = init.brush;
     if (init.wet) this.wetDriver = init.wet.driver;
     if (init.light && !init.wet && !init.sticker) this.lightTwin = this.makeLightTwin(init.light.surface);
-    const effect = init.effect?.pixels ?? null;
     this.apply = {
       mode: brush.engine === "eraser" ? "erase" : "paint",
       color: init.color,
@@ -2114,31 +2121,7 @@ var PaintStrokeSession = class _PaintStrokeSession {
       selection: init.selection ?? null,
       offset: init.offset
     };
-    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, effect, art: init.sticker.art, variant: init.sticker.variant });
-    } 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, 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, {
-        target: this.tileTarget(),
-        color: rgb(init.color),
-        secondary: rgb(init.secondary ?? init.background),
-        load: init.mixerLoad,
-        grain: init.grain,
-        paperDepth: init.paperDepth,
-        seed: init.seed,
-        copies: this.copies,
-        paint: init.paint ?? null,
-        effect,
-        stampArt: init.stampArt
-      });
-    } else {
-      const opts = { grain: init.grain, paperDepth: init.paperDepth, seed: init.seed, copies: this.copies, paint: init.paint ?? null, effect, stampArt: init.stampArt };
-      this.dry = brush.engine === "particle" ? new ParticleStroke(brush, opts) : brush.engine === "bristle" ? new BristleStroke(brush, opts) : new DryStroke(brush, opts);
-    }
+    if (!this.wetDriver) this.build(init.effect?.pixels ?? null);
   }
   host;
   init;
@@ -2167,6 +2150,52 @@ var PaintStrokeSession = class _PaintStrokeSession {
   result = null;
   /** The mask stencils this stroke was painted with when they are not the editor's (replays). */
   maskStencils = null;
+  /** Sets up the marks' engine (every kind but wet, which the wet layer paints), sampling `effect` for effect paint. */
+  build(effect) {
+    const init = this.init;
+    const brush = init.brush;
+    this.dry = this.wet = this.thickDriver = this.stickerSpray = null;
+    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, effect, art: init.sticker.art, variant: init.sticker.variant });
+    } 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, 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, {
+        target: this.tileTarget(),
+        color: rgb(init.color),
+        secondary: rgb(init.secondary ?? init.background),
+        load: init.mixerLoad,
+        grain: init.grain,
+        paperDepth: init.paperDepth,
+        seed: init.seed,
+        copies: this.copies,
+        paint: init.paint ?? null,
+        effect,
+        stampArt: init.stampArt
+      });
+    } else {
+      const opts = { grain: init.grain, paperDepth: init.paperDepth, seed: init.seed, copies: this.copies, paint: init.paint ?? null, effect, stampArt: init.stampArt };
+      this.dry = brush.engine === "particle" ? new ParticleStroke(brush, opts) : brush.engine === "bristle" ? new BristleStroke(brush, opts) : new DryStroke(brush, opts);
+    }
+  }
+  /**
+   * Paints the stroke so far again, sampling new effect pixels: a path-mapped effect rendered
+   * along the path drawn so far (`map: { by: 'path' }`). Only the live preview changes; the stroke
+   * keeps recording its own paint. Nothing for wet strokes or once the stroke has ended.
+   */
+  repaintEffect(pixels) {
+    if (this.closed || this.wetDriver || !this.init.effect) return;
+    const was = this.bounds;
+    this.live = new Map(this.base.tiles);
+    this.touched.clear();
+    this.fresh.clear();
+    this.bounds = null;
+    this.build(pixels);
+    const rects = this.points.length ? this.dry ? this.dry.push(this.points) : this.thickDriver ? this.thickDriver.push(this.points) : this.stickerSpray ? this.stickerSpray.push(this.points) : this.wet.push(this.points) : [];
+    this.update(was ? [...rects, was] : rects);
+  }
   /** The stroke's twin over the light channel: the same marks in grey at the brush's light amount (see `light.ts`). */
   makeLightTwin(light) {
     const init = this.init;
@@ -2703,7 +2732,8 @@ 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.paint?.type === "effect" && stroke.paint.map?.by === "stroke" && 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.paint?.type === "effect" && stroke.paint.map?.by === "path") out.paint = withStrokePath(stroke.paint, points);
   if (stroke.copies?.length) {
     const inv = invertAffine(m);
     out.copies = stroke.copies.map((c) => composeAffine(m, composeAffine(c, inv)));
@@ -4067,7 +4097,7 @@ async function replayPainting(source, target, options = {}) {
   const chunk = Math.max(1, options.wetChunk ?? 0) || Infinity;
   let strokes = 0;
   const scaled = source.strokes.slice(0, maxStrokes).map((st) => s === 1 ? st : varyStroke(st, scaleM, { scale: s }));
-  await target.prepareEffectPaints(scaled.flatMap((st) => st.paint?.type === "effect" ? [st.paint] : []));
+  await target.prepareEffectPaints(scaled.flatMap((st) => st.paint?.type === "effect" && st.paint.map?.by !== "path" ? [st.paint] : []));
   const advanceTo = async (clock) => {
     const now = target.getState().wet.clock;
     let left = clock - now;
@@ -4139,6 +4169,7 @@ async function replayPainting(source, target, options = {}) {
     const st = s === 1 ? item.stroke : varyStroke(item.stroke, scaleM, { scale: s });
     strokes++;
     if (!target.getLayer(st.layerId)) continue;
+    if (st.paint?.type === "effect" && st.paint.map?.by === "path") await target.prepareEffectPaints([st.paint]);
     const init = { layerId: st.layerId, 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 ?? []).map((x) => s === 1 ? x : scaleStencil(x, s)) };
     if (st.brush.engine === "wet" && st.steps?.length === st.points.length) {
       await target.wetIdle();
@@ -4321,6 +4352,12 @@ var PaintEffectsRenderer = class {
     }
     return out;
   }
+  renderSync(provider, id, size, request) {
+    this.follow(provider);
+    const out = this.pool.renderSync(provider, id, { ...size, depth: 8 }, request);
+    if (!out || out.width !== size.width || out.height !== size.height || out.data.length !== size.width * size.height * 4) return null;
+    return out;
+  }
   dispose() {
     this.pool.clear();
     this.descriptions.clear();
@@ -4439,6 +4476,17 @@ var PaintEditorController = class _PaintEditorController {
   paintEpoch = 0;
   /** Rendered effect paints by `effectPaintKey` (most recently used last). */
   effectPaintPixels = /* @__PURE__ */ new Map();
+  /** Primary path control name (`format: 'svg-path'`) per effect id, learned from `describeEffect`. */
+  effectPathControls = /* @__PURE__ */ new Map();
+  /** How many renders the running batch needs together (`prepareEffectPaints`; a synchronous replay reads them all). */
+  effectPaintBatch = 0;
+  /** The hand-painted stroke waiting for its path render (`finishPathStroke`), or `null`. */
+  pathStroke = null;
+  /**
+   * The hand-painted path stroke's live preview: the effect rendered along the path drawn so far
+   * (one render at a time; the newest path when it lands), repainted into the stroke as it lands.
+   */
+  pathPreview = null;
   mixerLoad = EMPTY_MIXER_LOAD;
   view = { ...DEFAULT_VIEW, pan: { ...DEFAULT_VIEW.pan } };
   hand;
@@ -4775,7 +4823,7 @@ var PaintEditorController = class _PaintEditorController {
       secondaryColor: this.secondaryColor,
       paint: this.gradient ?? { type: "color", color: this.color },
       effectPaint: this.effectPaintPending ?? this.effectPaint,
-      effectPaintRendering: Boolean(this.effectPaintPending),
+      effectPaintRendering: Boolean(this.effectPaintPending || this.pathStroke),
       mixerLoad: this.mixerLoad,
       view: this.view,
       hand: this.hand,
@@ -4837,6 +4885,7 @@ var PaintEditorController = class _PaintEditorController {
   }
   requireIdle(what) {
     if (this.session) throw new PaintEditorError(`A stroke is in progress; end or cancel it before ${what}.`);
+    if (this.pathStroke) throw new PaintEditorError(`The last stroke is still rendering the effect "${this.pathStroke.effect}" along its path; wait for it (strokeRendering) before ${what}.`);
     if (this.grouping?.pending && !this.grouping.inside) throw new PaintEditorError(`"${this.grouping.label}" is still being painted (one undo step); wait for it to finish before ${what}.`);
   }
   commit(label, next, before = this.doc) {
@@ -5481,6 +5530,8 @@ var PaintEditorController = class _PaintEditorController {
   /** The provider's description of an effect, checked for `place` (rejects without a provider or for an unknown id). */
   async describeEffect(effect, place) {
     const d = await this.effectsRenderer.describe(this.effects.require(), effect);
+    const pcs = pathControlsOf(d);
+    if (pcs.length) this.effectPathControls.set(d.id, pcs[0]);
     if (place) checkPaintEffectPlace(d, place);
     return d;
   }
@@ -5681,7 +5732,11 @@ var PaintEditorController = class _PaintEditorController {
     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). */
+  /**
+   * At most this many rendered effect paints are kept (each is canvas-sized), more only while
+   * something needs them all: a replay's batch, and the path-mapped strokes on stroke layers,
+   * which each have a render of their own and are redrawn synchronously.
+   */
   static EFFECT_PAINT_CACHE = 6;
   /** The effect paint strokes use (or the one rendering), or `null`. */
   getEffectPaint() {
@@ -5693,8 +5748,10 @@ 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`).
+   * With `map: { by: 'stroke' }` the effect lies along each stroke as a strip; with
+   * `map: { by: 'path' }` an effect with a path control (`format: 'svg-path'`) draws itself along
+   * each stroke's centreline in canvas pixels; 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).");
@@ -5709,6 +5766,9 @@ var PaintEditorController = class _PaintEditorController {
     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");
+    if (map?.by === "path" && !pathControlsOf(d).length) {
+      throw new PaintEditorError(`Effect "${d.id}" has no path control (format "svg-path"); use by: "stroke" (bent along each stroke) or by: "canvas" (fixed to the canvas).`);
+    }
     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, ...map ? { map } : {}, ...source.live ? { live: true } : {} };
@@ -5740,10 +5800,38 @@ var PaintEditorController = class _PaintEditorController {
     this.effectPaintPixels.set(key, img);
     return img;
   }
+  cacheEffectPaintPixels(p, pixels) {
+    return this.cacheEffectPaintImage(p, toEffectPaintPixels(p, pixels));
+  }
+  cacheEffectPaintImage(p, img) {
+    this.effectPaintPixels.set(effectPaintKey(p), img);
+    this.trimEffectPaints();
+    return img;
+  }
+  trimEffectPaints() {
+    let live = 0;
+    for (const list of Object.values(this.doc.liveStrokes ?? {})) for (const s of list) if (s.paint?.type === "effect" && s.paint.map?.by === "path") live++;
+    const limit = Math.max(_PaintEditorController.EFFECT_PAINT_CACHE, this.effectPaintBatch, live + 1);
+    while (this.effectPaintPixels.size > limit) this.effectPaintPixels.delete(this.effectPaintPixels.keys().next().value);
+  }
+  /** Renders an effect paint on the caller's stack when its renderer is warm and has `renderSync`; otherwise `null`. */
+  renderEffectPaintSync(p) {
+    const have = this.effectPaintImage(p);
+    if (have) return have;
+    const provider = this.effects.provider;
+    if (!provider || p.provider && provider.id !== p.provider) return null;
+    const size = effectPaintSize(p, this.doc.canvas);
+    const pixels = this.effectsRenderer.renderSync(provider, p.effect, size, { time: p.time, values: p.values });
+    return pixels ? this.cacheEffectPaintPixels(p, pixels) : null;
+  }
   /** 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;
+    return this.cacheEffectPaintImage(p, await this.renderEffectPaintPixels(p));
+  }
+  /** Renders an effect paint at the canvas size without keeping it. */
+  async renderEffectPaintPixels(p) {
     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.`);
@@ -5755,28 +5843,107 @@ var PaintEditorController = class _PaintEditorController {
     } 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), ...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;
+    return toEffectPaintPixels(p, pixels);
   }
   /**
    * 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(paints2) {
+    const list = [...paints2];
+    this.effectPaintBatch = new Set(list.map(effectPaintKey)).size;
     const seen = /* @__PURE__ */ new Set();
-    for (const p of paints2) {
+    for (const p of list) {
       const key = effectPaintKey(p);
       if (seen.has(key)) continue;
       seen.add(key);
       await this.renderEffectPaint(p);
     }
   }
+  /**
+   * Renders the path-mapped effect paint for one or more strokes' points before a synchronous
+   * stroke call runs (`paint_stroke` and `stroke_path` do; `paintStroke` throws without it on a
+   * provider that can't render synchronously). For a stroke layer edit, see `prepareStrokeEdit`.
+   */
+  async prepareStrokePathEffect(init, pointsList) {
+    const brush = this.strokeBrush(init);
+    if (!brushTakesPaint(brush)) return;
+    let source = null;
+    if (init.paint !== void 0) {
+      if (!isPaintEffectPaint(init.paint)) return;
+      source = readPaintEffectPaint(init.paint);
+    } else if (init.color === void 0 && !brush.paint && !this.effectPaintPending) {
+      source = this.effectPaint;
+    }
+    if (!source || source.map?.by !== "path") return;
+    if (!this.effectPathControls.has(source.effect)) await this.describeEffect(source.effect);
+    const control = this.effectPathControls.get(source.effect);
+    const paints2 = pointsList.filter((pts) => pts.length > 0).map((pts) => withStrokePath(source, pts, control));
+    if (paints2.length) await this.prepareEffectPaints(paints2);
+  }
+  /**
+   * Renders what an edit of a stroke layer's stroke paints with (`updateStroke`, `editStrokePoints`):
+   * a new effect paint, or a path-mapped stroke's new path. Those calls are synchronous, and throw
+   * without it on a provider that can't render synchronously. Bad edits are left for them to refuse.
+   */
+  async prepareStrokeEdit(id, edit) {
+    const p = this.strokeEditPaint(id, edit);
+    if (!p) return;
+    if (p.map?.by === "path" && !this.effectPathControls.has(p.effect)) await this.describeEffect(p.effect);
+    await this.prepareEffectPaints([this.strokeEditPaint(id, edit) ?? p]);
+  }
+  /** Whether `prepareStrokeEdit` has to be awaited before this edit can run. */
+  strokeEditNeedsRender(id, edit) {
+    const p = this.strokeEditPaint(id, edit);
+    return Boolean(p && !this.effectPaintImage(p) && !this.renderEffectPaintSync(p));
+  }
+  strokeEditPaint(id, edit) {
+    const was = Object.values(this.doc.liveStrokes ?? {}).flat().find((s) => s.id === id);
+    if (!was) return null;
+    try {
+      if (edit.paint !== void 0) {
+        if (!isPaintEffectPaint(edit.paint)) return null;
+        const p = readPaintEffectPaint(edit.paint);
+        return p && withStrokePath(p, was.points, this.effectPathControls.get(p.effect));
+      }
+      if (was.paint?.type !== "effect" || was.paint.map?.by !== "path") return null;
+      if (edit.points !== void 0) return withStrokePath(was.paint, this.checkPoints(edit.points), this.effectPathControls.get(was.paint.effect));
+      if (!edit.transform) return null;
+      const varied = varyStroke(was, this.strokeTransform(was, edit.transform), {}).paint;
+      return varied?.type === "effect" ? varied : null;
+    } catch {
+      return null;
+    }
+  }
+  /** A stroke edit's transform as an affine map, checked. */
+  strokeTransform(stroke, t) {
+    if (t.scale !== void 0 && !(t.scale > 0 && t.scale <= 20)) throw new PaintEditorError(`scale ${t.scale} is out of range; use above 0 up to 20.`);
+    for (const k of ["dx", "dy", "rotate"]) if (t[k] !== void 0 && !Number.isFinite(t[k])) throw new PaintEditorError(`${k} must be a number.`);
+    const b = strokeBounds(stroke.points);
+    return variationAffine(t, t.origin ?? { x: b.x + b.width / 2, y: b.y + b.height / 2 });
+  }
   /** Renders the effect paints of recorded strokes (default all of them) before a replay. */
-  async prepareStrokeEffects(strokeIds) {
+  async prepareStrokeEffects(strokeIds, variation) {
     const ids = strokeIds ? new Set(strokeIds) : null;
-    const paints2 = this.doc.strokes.filter((s) => (!ids || ids.has(s.id)) && s.paint?.type === "effect").map((s) => s.paint);
+    const strokes = this.doc.strokes.filter((s) => (!ids || ids.has(s.id)) && s.paint?.type === "effect");
+    const paints2 = strokes.map((s) => s.paint);
+    if (variation && strokes.length) {
+      const repeat = Math.max(1, Math.min(100, variation.repeat ?? 1));
+      let origin = variation.origin;
+      if (!origin) {
+        const b = strokeBounds(strokes.flatMap((s) => s.points));
+        origin = { x: b.x + b.width / 2, y: b.y + b.height / 2 };
+      }
+      const step = variationAffine(variation, origin);
+      let m = IDENTITY_AFFINE;
+      for (let k = 0; k < repeat; k++) {
+        m = [step[0] * m[0] + step[1] * m[2], step[0] * m[1] + step[1] * m[3], step[2] * m[0] + step[3] * m[2], step[2] * m[1] + step[3] * m[3], step[0] * m[4] + step[1] * m[5] + step[4], step[2] * m[4] + step[3] * m[5] + step[5]];
+        for (const s of strokes) {
+          const v = varyStroke(s, m, variation);
+          if (v.paint?.type === "effect") paints2.push(v.paint);
+        }
+      }
+    }
     await this.prepareEffectPaints(paints2);
   }
   /** A small preview of the effect paint (a PNG data URL `size` px wide), or `null` without a rendered one. */
@@ -5804,7 +5971,7 @@ var PaintEditorController = class _PaintEditorController {
    * 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) {
+  strokeEffect(init, brush, points) {
     if (!brushTakesPaint(brush)) return null;
     let source = null;
     if (init.paint !== void 0) {
@@ -5816,8 +5983,10 @@ var PaintEditorController = class _PaintEditorController {
       source = this.effectPaint;
     }
     if (!source) return null;
-    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.`);
+    const path = source.map?.by === "path";
+    if (path && points?.length) source = withStrokePath(source, points, this.effectPathControls.get(source.effect));
+    const pixels = this.effectPaintImage(source) ?? (path ? this.renderEffectPaintSync(source) : null);
+    if (!pixels) throw new PaintEditorError(`The effect paint "${source.effect}"${source.provider ? ` from provider "${source.provider}"` : ""} is not rendered at this canvas size; call ${path ? "prepareStrokePathEffect (the paint_stroke tool does this) or prepareStrokeEdit" : "set_effect_paint (or prepareEffectPaints)"} first.`);
     return { source, pixels };
   }
   /**
@@ -6205,7 +6374,7 @@ var PaintEditorController = class _PaintEditorController {
   strokeCopies() {
     return symmetryCopies(this.guides.symmetry);
   }
-  sessionFor(doc, init, host) {
+  sessionFor(doc, init, host, points) {
     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 };
@@ -6224,9 +6393,27 @@ var PaintEditorController = class _PaintEditorController {
     })();
     const brush = this.strokeBrush(init);
     if (this.previewing && isWetBrush(brush)) throw new PaintEditorError(`Wet paint can't be previewed; the ${brush.name} brush paints wet media. Suggest it with a dry brush.`);
-    const effect = this.strokeEffect(init, brush);
+    if (brush.ghost) {
+      if (brush.light.amount > 0) throw new PaintEditorError(`Ghost paint (${brush.name}) shares the wet light channel and can't emit light; set light.amount to 0 or ghost to null (set_brush).`);
+      if (isPaintEffectPaint(init.paint) || init.paint === void 0 && init.color === void 0 && Boolean(this.effectPaint)) {
+        throw new PaintEditorError(`Ghost paint (${brush.name}) needs a single colour to subtract as it fades, so it can't paint with an effect; set a solid colour (set_color) or pass color to paint_stroke.`);
+      }
+      if (brush.behavior.multicolor.mode !== "off") throw new PaintEditorError(`Ghost paint (${brush.name}) needs a single colour to subtract as it fades, so it can't use multi-colour paint; set behavior.multicolor.mode to "off" (set_brush).`);
+      const gCol = init.color === void 0 ? this.ownColour(init.brushId) ?? this.color : parseColor(init.color);
+      if (this.strokeGradient(init, brush, gCol)) throw new PaintEditorError(`Ghost paint (${brush.name}) needs a single colour to subtract as it fades, so it can't paint a gradient; set a solid colour (set_color) or pass color to paint_stroke.`);
+      if (Boolean(doc.light?.[layer.id]?.tiles.size) || Boolean(this.wet.world?.hasLane(layer.id) && this.wet.world.isLit(layer.id))) {
+        throw new PaintEditorError(`Layer "${layer.name}" holds light paint, and ghost paint shares the wet light channel; paint on another layer (add_layer) or clear the light first (clear_light).`);
+      }
+    }
+    const effect = this.strokeEffect(init, brush, points);
+    if (!points && init.paint === void 0 && effect?.source.map?.by === "path" && isWetBrush(brush)) {
+      throw new PaintEditorError(`The ${brush.name} brush paints wet media, which can't follow a path that isn't known until the stroke ends; paint with a dry brush, set_effect_paint with by: "stroke", or give the points to paint_stroke.`);
+    }
     if (brush.light.amount > 0) {
       if (brush.engine === "sticker") throw new PaintEditorError(`The ${brush.name} brush sprays stickers, which don't take light yet; paint light with a dab or particle light brush (glow-gel, neon-marker; list_brush_presets lists them), or set light.amount to 0 (set_brush).`);
+      if (Boolean(this.wet.world?.hasLane(layer.id) && this.wet.world.getGhost(layer.id)) || Boolean(this.wet.settings.get(layer.id)?.ghost)) {
+        throw new PaintEditorError(`Layer "${layer.name}" has ghost paint fading on it, which uses the wet light channel; paint light on another layer (add_layer), or finish the ghost first (dry_paint).`);
+      }
     }
     if (doc.liveStrokes?.[layer.id]) {
       const why = liveStrokeRefusal(brush);
@@ -6279,7 +6466,8 @@ var PaintEditorController = class _PaintEditorController {
         copies: [IDENTITY_AFFINE, ...copiesW].map(affineCopy),
         mask: init.maskStencils ? this.stencilSelection(init.maskStencils) : init.stencils !== false ? this.stencilSelection() : null,
         paint: effect ? null : wetGradient,
-        effect: effect?.pixels ?? null
+        effect: effect?.pixels ?? null,
+        speed: this.wet.speed
       });
       init = { ...init, seed: seedW, load };
       wet = { driver, surface: () => world.display(id).surface };
@@ -6374,9 +6562,19 @@ var PaintEditorController = class _PaintEditorController {
         this.liveThick = ch ? { layerId, channels: ch } : null;
         this.emit(rects);
       },
-      sampled: (s, points) => this.notifySample("points", s, points),
+      sampled: (s, points) => {
+        this.notifySample("points", s, points);
+        this.previewPathStroke(s);
+      },
       commit: (s, surface, cancelled) => {
         this.session = null;
+        const preview = this.pathPreview?.session === s ? this.pathPreview : null;
+        this.pathPreview = null;
+        const pathPaint = cancelled ? null : this.pathStrokePaint(s);
+        if (pathPaint) {
+          this.finishPathStroke(s, pathPaint, preview);
+          return;
+        }
         this.live = null;
         this.liveLayers = null;
         this.liveThick = null;
@@ -6425,14 +6623,99 @@ var PaintEditorController = class _PaintEditorController {
       throw e;
     }
     this.session = session;
+    if (session.init.effect?.source.map?.by === "path" && !session.init.wet) this.pathPreview = { session, key: "", pending: null, landed: null };
     this.emit([]);
     this.notifySample("begin", session);
     return session;
   }
+  /**
+   * Renders a hand-painted path stroke's effect along the path drawn so far and paints the stroke
+   * again with it when it lands, so the effect follows the pen while it draws. One render at a
+   * time: when one lands, the next takes the newest path. A failed render leaves the preview as it
+   * was; the render on release reports it.
+   */
+  previewPathStroke(s) {
+    const pv = this.pathPreview;
+    if (!pv || pv.session !== s || pv.pending || !s.open) return;
+    const paint = this.pathStrokePaint(s);
+    if (!paint) return;
+    const key = effectPaintKey(paint);
+    if (key === pv.key) return;
+    pv.key = key;
+    const cached = this.effectPaintImage(paint);
+    const pending = cached ? Promise.resolve(cached) : this.renderEffectPaintPixels(paint);
+    pv.pending = pending;
+    pending.then(
+      (pixels) => {
+        pv.pending = null;
+        pv.landed = { key, pixels };
+        if (this.pathPreview !== pv || !s.open) return;
+        s.repaintEffect(pixels);
+        this.previewPathStroke(s);
+      },
+      () => {
+        pv.pending = null;
+      }
+    );
+  }
   /** The current live stroke, if any. */
   get activeStroke() {
     return this.session;
   }
+  /**
+   * While a hand-painted stroke waits for its path render (`map: { by: 'path' }`), settles when it
+   * has landed and rejects if it could not (the stroke is dropped); `null` otherwise. Until then
+   * the editor is busy, as during a stroke, and shows the stroke as it was painted.
+   */
+  get strokeRendering() {
+    return this.pathStroke?.done ?? null;
+  }
+  /** The paint a finished hand-painted stroke must be painted again with, or `null` when it already painted with it. */
+  pathStrokePaint(s) {
+    const source = s.init.effect?.source;
+    if (source?.map?.by !== "path" || !s.points.length) return null;
+    const paint = withStrokePath(source, s.points, this.effectPathControls.get(source.effect));
+    return effectPaintKey(paint) === effectPaintKey(source) ? null : paint;
+  }
+  /**
+   * Ends a hand-painted stroke with a path-mapped effect. Its whole path isn't known until now, so
+   * the live stroke was only a preview from renders along the path so far (`previewPathStroke`):
+   * nothing of it was committed. Paints it again with the path's own render, as one stroke and one undo step, at
+   * once if that can render synchronously and when the render lands if not.
+   */
+  finishPathStroke(s, paint, preview) {
+    const finish = () => {
+      this.pathStroke = null;
+      this.live = null;
+      this.liveLayers = null;
+      this.liveThick = null;
+      const masks = s.init.selection ? (s.maskStencils ?? this.guides.stencils).filter((x) => x.enabled && x.mode === "mask") : [];
+      const load = s.init.mixerLoad;
+      const result = this.paintStroke({ layerId: s.layerId, points: s.points, color: s.init.colorHex, brush: brushToJSON(s.init.brush), seed: s.init.seed, copies: s.init.affineCopies, ...load.reservoir || load.pickup ? { load } : {}, paint, snapToPerspective: false, stencils: false, maskStencils: masks });
+      Object.assign(s.result, result);
+      this.notifySample("end", s, [], result.strokeId);
+    };
+    const key = effectPaintKey(paint);
+    if (preview?.landed?.key === key) this.cacheEffectPaintImage(paint, preview.landed.pixels);
+    if (this.effectPaintImage(paint) || this.renderEffectPaintSync(paint)) {
+      finish();
+      return;
+    }
+    const render = preview?.pending && preview.key === key ? preview.pending.then((img) => this.cacheEffectPaintImage(paint, img)) : this.renderEffectPaint(paint);
+    const done = render.then(finish, (e) => {
+      this.pathStroke = null;
+      this.live = null;
+      this.liveLayers = null;
+      this.liveThick = null;
+      this.emit();
+      this.notifySample("cancel", s, []);
+      throw e;
+    });
+    done.catch(() => {
+    });
+    this.pathStroke = { effect: paint.effect, done };
+    this.emit([]);
+  }
   /** Runs a whole stroke against `doc` without touching the editor; returns the new document. */
   runStroke(doc, init, points) {
     let out = doc;
@@ -6459,7 +6742,7 @@ var PaintEditorController = class _PaintEditorController {
         }, stroke);
       }
     };
-    const session = this.sessionFor(doc, init, host);
+    const session = this.sessionFor(doc, init, host, points);
     session.push(points);
     const result = session.end();
     if (session.init.wet) {
@@ -6609,6 +6892,8 @@ var PaintEditorController = class _PaintEditorController {
       }
     }
     if (doc !== this.doc) this.commit(strokes.length === 1 && repeat === 1 ? "Replay stroke" : "Replay strokes", doc);
+    this.effectPaintBatch = 0;
+    this.trimEffectPaints();
     return { strokeIds: ids, bounds, layerIds: [...layerIds] };
   }
   // --- Light paint --------------------------------------------------------------------
@@ -7104,7 +7389,11 @@ var PaintEditorController = class _PaintEditorController {
   /** Wet settings saved with the document (`null` when they are all defaults). */
   wetJSON() {
     const layers = {};
-    for (const [id, set] of this.wet.settings) if (findLayer(this.doc.layers, id)) layers[id] = { params: { ...set.params }, flow: { ...set.flow } };
+    for (const [id, set] of this.wet.settings) {
+      if (!findLayer(this.doc.layers, id)) continue;
+      const ghost = this.wet.world?.hasLane(id) ? this.wet.world.getGhost(id) : set.ghost ?? null;
+      layers[id] = { params: { ...set.params }, flow: { ...set.flow }, ...ghost ? { ghost } : {} };
+    }
     const flat = this.wet.tilt.angle === 0;
     if (!Object.keys(layers).length && flat) return void 0;
     return { tilt: { ...this.wet.tilt }, layers };
@@ -7121,7 +7410,8 @@ var PaintEditorController = class _PaintEditorController {
           continue;
         }
         const x = v;
-        this.wet.settings.set(id, { params: normalizeWetParams(x.params ?? {}), flow: normalizeFlow(x.flow ?? {}) });
+        const ghost = readWetGhost(x.ghost);
+        this.wet.settings.set(id, { params: normalizeWetParams(x.params ?? {}), flow: normalizeFlow(x.flow ?? {}), ...ghost ? { ghost } : {} });
       }
     }
   }
@@ -7912,8 +8202,9 @@ var PaintEditorController = class _PaintEditorController {
     if (update.paint !== void 0) {
       if (update.paint === null) delete next.paint;
       else if (isPaintEffectPaint(update.paint)) {
-        if (!this.effectPaintImage(update.paint)) throw new PaintEditorError(`The effect "${update.paint.effect}" is not rendered yet; render it first (prepareEffectPaints; the update_stroke tool does this).`);
-        next.paint = JSON.parse(JSON.stringify(update.paint));
+        const ep = update.paint.map?.by === "path" ? withStrokePath(update.paint, next.points, this.effectPathControls.get(update.paint.effect)) : update.paint;
+        if (!this.effectPaintImage(ep) && !this.renderEffectPaintSync(ep)) throw new PaintEditorError(`The effect "${update.paint.effect}" is not rendered yet; render it first (prepareEffectPaints; the update_stroke tool does this).`);
+        next.paint = JSON.parse(JSON.stringify(ep));
       } else {
         const p = this.readStrokePaint(update.paint);
         if (p.type === "color") {
@@ -7944,13 +8235,11 @@ var PaintEditorController = class _PaintEditorController {
     if (edit.points !== void 0) {
       const points = this.checkPoints(edit.points);
       next = { ...was, points: points.map((p) => ({ ...p })) };
+      if (next.paint?.type === "effect" && next.paint.map?.by === "path") {
+        next.paint = withStrokePath(next.paint, next.points, this.effectPathControls.get(next.paint.effect));
+      }
     } else {
-      const t = edit.transform;
-      if (t.scale !== void 0 && !(t.scale > 0 && t.scale <= 20)) throw new PaintEditorError(`scale ${t.scale} is out of range; use above 0 up to 20.`);
-      for (const k of ["dx", "dy", "rotate"]) if (t[k] !== void 0 && !Number.isFinite(t[k])) throw new PaintEditorError(`${k} must be a number.`);
-      const b = strokeBounds(was.points);
-      const m = variationAffine(t, t.origin ?? { x: b.x + b.width / 2, y: b.y + b.height / 2 });
-      next = varyStroke(was, m, {});
+      next = varyStroke(was, this.strokeTransform(was, edit.transform), {});
       if (was.stencils) next.stencils = was.stencils;
     }
     const list = strokes.map((x, i) => i === index ? next : x);
@@ -8606,6 +8895,19 @@ function clipToCanvas(rect, canvas) {
   const y1 = Math.min(canvas.height, rect.y + rect.height);
   return x1 > x0 && y1 > y0 ? { x: x0, y: y0, width: x1 - x0, height: y1 - y0 } : null;
 }
+function toEffectPaintPixels(p, pixels) {
+  return { width: pixels.width, height: pixels.height, data: new Uint8ClampedArray(pixels.data), ...p.map?.by === "stroke" ? { map: p.map } : {} };
+}
+function readWetGhost(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const g = raw;
+  if (!Array.isArray(g.pigment) || g.pigment.length !== 4 || !g.pigment.every((x) => typeof x === "number" && Number.isFinite(x))) return null;
+  const remaining = typeof g.remaining === "number" && Number.isFinite(g.remaining) ? Math.max(0, Math.round(g.remaining)) : 0;
+  if (remaining <= 0) return null;
+  const total = typeof g.total === "number" && Number.isFinite(g.total) ? Math.max(1, Math.round(g.total)) : remaining;
+  const linger = typeof g.linger === "number" && Number.isFinite(g.linger) ? Math.max(0.5, Math.min(60, g.linger)) : 4;
+  return { pigment: [g.pigment[0], g.pigment[1], g.pigment[2], g.pigment[3]], remaining, total, linger };
+}
 
 // src/paint-editor/presence.ts
 var PaintPresence = class extends PresenceStore {
@@ -9528,7 +9830,7 @@ function createPaintWetTools(c) {
     {
       name: "get_wet_paint",
       title: "Get the wet paint",
-      description: "Reads the wet media: whether any paint is still wet, the simulation clock (steps), whether time is paused, its speed (steps per second), the canvas tilt, the kernel running it (typescript, wasm, wasm-threads with the thread count, and a message when it runs slower than it could, e.g. without cross-origin isolation), and each wet layer: wet cells, where the water is (wetBounds), live tiles, its settings and flow map. Also engine: Engine B, the GPU accelerator: WebGPU in browsers, Metal in the Swift editors (mode auto/off, state, reason, adapter, minTiles, activeTiles). Call it after wet strokes to see what is still wet.",
+      description: "Reads the wet media: whether any paint is still wet, the simulation clock (steps), whether time is paused, its speed (steps per second), the canvas tilt, the kernel running it (typescript, wasm, wasm-threads with the thread count, and a message when it runs slower than it could, e.g. without cross-origin isolation), and each wet layer: wet cells, where the water is (wetBounds), live tiles, its settings, flow map, and ghost: { remaining } (seconds of simulated time left when ghost paint is fading on the layer). Also engine: Engine B, the GPU accelerator: WebGPU in browsers, Metal in the Swift editors (mode auto/off, state, reason, adapter, minTiles, activeTiles). Call it after wet strokes to see what is still wet.",
       inputSchema: EMPTY2,
       annotations: { title: "Get the wet paint", ...READ3 },
       coordinates: { out: ["layers[].wetBounds", "layers[].flow.center"] },
@@ -10320,6 +10622,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
         if (refs.length) await c.prepareStickers(refs);
       }
       const stroke = { points: a.points, layerId: a.layerId, brushId: a.brushId, brush, color: a.color, paint: a.paint, seed: a.seed, snapToPerspective: a.snapToPerspective };
+      await c.prepareStrokePathEffect(stroke, [stroke.points]);
       const r = await act({ kind: "stroke", stroke }, () => c.paintStroke(stroke));
       return r.mixerLoad ? { ...r, mixerLoad: loadResult(r.mixerLoad) } : r;
     }
@@ -10357,6 +10660,13 @@ function createPaintEditorToolProvider(controller, options = {}) {
       }
       const path = options.origin && typeof a.path === "string" && a.path.trim() ? bezierPathToSvg(a.path, { offset: { x: -options.origin.x, y: -options.origin.y } }) : a.path;
       const init = { path, spacing: a.spacing, pressure: a.pressure, speed: a.speed, layerId: a.layerId, brushId: a.brushId, brush, color: a.color, paint: a.paint, seed: a.seed };
+      if (typeof path === "string" && path.trim()) {
+        try {
+          const sampled = samplePath(path, init);
+          await c.prepareStrokePathEffect(init, sampled);
+        } catch {
+        }
+      }
       const r = await act(
         () => {
           if (typeof path !== "string" || !path.trim()) throw new PaintEditorError('path is empty; give SVG path data in document pixels, e.g. "M 10 10 C 40 0 80 60 120 30".');
@@ -10508,7 +10818,8 @@ function createPaintEditorToolProvider(controller, options = {}) {
     },
     annotations: { title: "Move or reshape a stroke", ...WRITE5 },
     coordinates: { in: ["points[]", "transform.origin"], out: ["bounds", "stroke.bounds", "stroke.points[]"] },
-    handler: ({ id, points, transform }) => {
+    handler: async ({ id, points, transform }) => {
+      await c.prepareStrokeEdit(id, { points, transform });
       const r = c.editStrokePoints(id, { points, transform });
       return { stroke: strokeSummary(r.stroke, true, true), bounds: r.bounds };
     }
@@ -10591,7 +10902,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
     coordinates: { in: ["origin"], out: ["bounds"] },
     handler: async (a) => {
       const replay = a;
-      if (replay.color === void 0) await c.prepareStrokeEffects(replay.strokeIds);
+      if (replay.color === void 0) await c.prepareStrokeEffects(replay.strokeIds, replay);
       return act({ kind: "replay", replay }, () => c.replayStrokes(replay));
     }
   });
@@ -10967,15 +11278,28 @@ var PaintGesture = class {
     if (!m || m.pointerId !== e.pointerId) return;
     this.mode = null;
     this.predicted = [];
-    if (m.kind === "stroke") this.controller.activeStroke?.end();
+    if (m.kind === "stroke") {
+      this.controller.activeStroke?.end();
+      this.controller.strokeRendering?.catch((err) => {
+        this.error = err instanceof Error ? err.message : String(err);
+      });
+    }
     if (m.kind === "move-stroke") {
       const dx = Math.round((this.doc(e).x - m.from.x) * 100) / 100;
       const dy = Math.round((this.doc(e).y - m.from.y) * 100) / 100;
       if (dx || dy) {
-        try {
-          this.controller.editStrokePoints(m.id, { transform: { dx, dy } });
-        } catch (err) {
+        const edit = { transform: { dx, dy } };
+        const failed = (err) => {
           this.error = err instanceof Error ? err.message : String(err);
+        };
+        if (this.controller.strokeEditNeedsRender(m.id, edit)) {
+          this.controller.prepareStrokeEdit(m.id, edit).then(() => this.controller.editStrokePoints(m.id, edit)).catch(failed);
+        } else {
+          try {
+            this.controller.editStrokePoints(m.id, edit);
+          } catch (err) {
+            failed(err);
+          }
         }
       }
     }
@@ -11482,9 +11806,9 @@ function createPaintEffectsToolProvider(controller, options = {}) {
             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).",
+              description: `How the effect lies on the paint: by canvas (default: fixed to the canvas, painting reveals a hidden picture), 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), or by path (for effects with a path control format svg-path, e.g. search_effects accepts ["path"]: passes each stroke's centreline [x0, y0, x1, y1, \u2026] in canvas pixels to that control so the effect draws itself along the stroke; strokes longer than 256 points are simplified rather than refused).`,
               properties: {
-                by: { type: "string", enum: ["canvas", "stroke"], description: "canvas (default) or stroke." },
+                by: { type: "string", enum: ["canvas", "stroke", "path"], description: "canvas (default), stroke (bent strip along each stroke) or path (native path control for effects with format svg-path)." },
                 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." }
               },
@@ -12095,7 +12419,7 @@ function uiTables() {
     brushOptions: BRUSH_OPTION_CONTROLS,
     blendMenu: BLEND_MENU_GROUPS,
     layerEffects: LAYER_EFFECT_MENU.map(({ kind, label }) => ({ kind, label, controls: layerEffectControls(defaultLayerEffect(kind, kind)) })),
-    sliders: { paper: PAPER_SLIDERS, wet: WET_PARAM_SLIDERS, wetTilt: WET_TILT_SLIDERS, wetSpeed: WET_SPEED_SLIDER, light: LIGHT_SLIDERS, stroke: STROKE_SLIDERS, sticker: STICKER_SLIDERS },
+    sliders: { paper: PAPER_SLIDERS, wet: WET_PARAM_SLIDERS, wetTilt: WET_TILT_SLIDERS, wetSpeed: WET_SPEED_SLIDER, light: LIGHT_SLIDERS, ghost: GHOST_SLIDERS, stroke: STROKE_SLIDERS, sticker: STICKER_SLIDERS },
     pathStrokeTapers: PATH_STROKE_TAPERS,
     padSampleSizes: PAD_SAMPLE_SIZES,
     wetGpu: WET_GPU_OPTIONS,
@@ -12172,6 +12496,7 @@ export {
   DEFAULT_DPI,
   DEFAULT_DYNAMICS,
   DEFAULT_FLOW,
+  DEFAULT_GHOST,
   DEFAULT_IMPASTO,
   DEFAULT_LIGHT,
   DEFAULT_LIGHTING,
@@ -12194,6 +12519,7 @@ export {
   DryStroke,
   EFFECT_MAP_REPEATS,
   EFFECT_STRIP_HEIGHT,
+  GHOST_SLIDERS,
   GPU_LEAD,
   GRAIN_PATTERNS,
   GRAIN_TILE,
@@ -12209,6 +12535,7 @@ export {
   MAX_CANVAS_SIDE,
   MAX_COORDINATE,
   MAX_DOT_TEXTURES,
+  MAX_EFFECT_PATH_POINTS,
   MAX_IMAGE_SIDE,
   MAX_LIVE_EFFECT_SOURCES,
   MAX_PATH_SAMPLES,
@@ -12370,6 +12697,7 @@ export {
   hslToRgb,
   hsvToRgb,
   hueToWheel,
+  inferEffectPathControl,
   invertAffine,
   isBlendMode,
   isGradientPaint,
@@ -12400,6 +12728,7 @@ export {
   normalizeCanvas,
   normalizeDynamics,
   normalizeFlow,
+  normalizeGhost,
   normalizeHexColor,
   normalizeImpasto,
   normalizeLight,
@@ -12492,6 +12821,7 @@ export {
   stickerSurface,
   strokeBounds,
   strokeDuration,
+  strokePathPoints,
   strokeSchedule,
   strokeToJSON,
   sweepPath,
@@ -12524,5 +12854,6 @@ export {
   wheelPick,
   wheelPoint,
   wheelToHue,
-  withPaintPlayback
+  withPaintPlayback,
+  withStrokePath
 };