@pixerate/editor 0.125.0 → 0.127.0

package/dist/paint-editor/index.js

@@ -73,16 +73,18 @@ import {
 } from "../chunk-UYQUPUR6.js";
 import {
   toVideoFfmpeg
-} from "../chunk-G6WXWS4Y.js";
+} from "../chunk-FICSDDDF.js";
 import {
   deserializeLayers,
   exportPsd,
   resolveExternalAssets,
   serializeLayers,
   serializeLayersExternal
-} from "../chunk-WUDPFWAN.js";
+} from "../chunk-F7Q2NE2Y.js";
 import "../chunk-CTTF4KYV.js";
-import "../chunk-FJ3324TZ.js";
+import {
+  EffectRendererPool
+} from "../chunk-FJ3324TZ.js";
 import {
   RasterCompositor,
   findLayer,
@@ -209,10 +211,15 @@ import {
   realPresenceClock,
   tweenPresenceCursor
 } from "../chunk-B6DSIEXA.js";
-import "../chunk-FPRIUR4T.js";
-import "../chunk-TGKT5QAB.js";
-import "../chunk-FG274FYT.js";
-import "../chunk-GLWZXQ4Q.js";
+import "../chunk-ROZFX4QI.js";
+import "../chunk-YGJIER2R.js";
+import "../chunk-KHNZ6MOU.js";
+import {
+  EffectUnsupportedError,
+  EffectsSlot,
+  createEffectToolProvider,
+  resolveEffectValues
+} from "../chunk-QFSTQHZY.js";
 import "../chunk-4FX5ACVG.js";
 import "../chunk-33AHNSEB.js";
 import "../chunk-ZRJMJIQU.js";
@@ -1483,6 +1490,7 @@ function varyStroke(stroke, m, v) {
 // src/paint-editor/render.ts
 var PAPER_NODE_ID = "__paper";
 var TRACING_NODE_ID = "__tracing";
+var PAPER_EFFECT_NODE_ID = "__paper_effect";
 function paperKey(p, light) {
   const metal = p.metallic ?? 0;
   return JSON.stringify([p.pattern, p.seed, p.color, p.scale, p.tiling, p.shading, p.dry, metal, metal > 0 && light ? [light.azimuth, light.elevation] : null]);
@@ -3216,6 +3224,130 @@ ${tl.ffmpeg.command}
   return writeZip(entries, { compression: "store" });
 }
 
+// src/paint-editor/effects.ts
+var PAINT_EFFECT_PLACES = {
+  /** Effect paper: drawn over the whole sheet. */
+  paper: ["generator"],
+  /** An effect layer: drawn at the canvas size. */
+  layer: ["generator", "overlay", "title"],
+  /** 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"]
+};
+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"
+};
+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";
+  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);
+}
+var PAPER_EFFECT_BLENDS = ["multiply", "normal", "overlay", "soft-light", "screen", "color"];
+var paperVersion = 1;
+function nextPaperEffectVersion() {
+  return paperVersion++;
+}
+function overPixels(base, top, opacity = 1) {
+  const out = new Uint8ClampedArray(base.length);
+  for (let i = 0; i < out.length; i += 4) {
+    const ta = top[i + 3] / 255 * opacity;
+    const ba = base[i + 3] / 255;
+    const a = ta + ba * (1 - ta);
+    out[i + 3] = Math.round(a * 255);
+    if (a > 0) for (let c = 0; c < 3; c++) out[i + c] = (top[i + c] * ta + base[i + c] * ba * (1 - ta)) / a;
+  }
+  return out;
+}
+function mixPixels(before, after, amount) {
+  const out = new Uint8ClampedArray(before.length);
+  for (let i = 0; i < out.length; i += 4) {
+    for (let c = 0; c < 3; c++) out[i + c] = before[i + c] + (after[i + c] - before[i + c]) * amount;
+    out[i + 3] = before[i + 3];
+  }
+  return out;
+}
+var PaintEffectsRenderer = class {
+  pool = new EffectRendererPool({ maxRenderers: 3 });
+  descriptions = /* @__PURE__ */ new Map();
+  provider = null;
+  /** Forgets cached descriptions and renderers when the provider changes. */
+  follow(provider) {
+    if (provider === this.provider) return;
+    this.provider = provider;
+    this.descriptions.clear();
+    this.pool.clear();
+  }
+  describe(provider, id) {
+    this.follow(provider);
+    let d = this.descriptions.get(id);
+    if (!d) {
+      d = Promise.resolve().then(() => provider.describe(id));
+      d.catch(() => this.descriptions.delete(id));
+      this.descriptions.set(id, d);
+    }
+    return d;
+  }
+  async render(provider, id, size, request) {
+    this.follow(provider);
+    const out = await this.pool.render(provider, id, { ...size, depth: 8 }, request);
+    if (out.width !== size.width || out.height !== size.height || out.data.length !== size.width * size.height * 4) {
+      throw new Error(`The effect "${id}" returned ${out.width}\xD7${out.height} pixels for a ${size.width}\xD7${size.height} canvas.`);
+    }
+    return out;
+  }
+  dispose() {
+    this.pool.clear();
+    this.descriptions.clear();
+  }
+};
+var sourceOut = (s) => ({
+  effect: s.effect,
+  ...s.provider ? { provider: s.provider } : {},
+  ...s.name ? { name: s.name } : {},
+  values: JSON.parse(JSON.stringify(s.values)),
+  ...s.time ? { time: s.time } : {}
+});
+function readPaintEffectSource(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const r = raw;
+  if (typeof r.effect !== "string" || !r.effect || !r.values || typeof r.values !== "object" || Array.isArray(r.values)) return null;
+  return {
+    effect: r.effect,
+    ...typeof r.provider === "string" ? { provider: r.provider } : {},
+    ...typeof r.name === "string" ? { name: r.name } : {},
+    values: r.values,
+    ...typeof r.time === "number" && r.time > 0 ? { time: r.time } : {}
+  };
+}
+function paperEffectToJSON(p) {
+  return { ...sourceOut(p), opacity: p.opacity, blend: p.blend, png: pngDataUrl(p.image.width, p.image.height, p.image.data) };
+}
+function paperEffectFromJSON(raw, width, height) {
+  const source = readPaintEffectSource(raw);
+  if (!source) throw new Error("it is not an effect (effect id and values)");
+  const r = raw;
+  const parsed = typeof r.png === "string" ? parseDataUrl(r.png) : null;
+  if (!parsed) throw new Error("its pixels are missing");
+  const image = decodePng(parsed.bytes);
+  if (image.width !== width || image.height !== height) throw new Error(`its pixels are ${image.width}\xD7${image.height}, not the canvas size ${width}\xD7${height}`);
+  const opacity = typeof r.opacity === "number" && r.opacity >= 0 && r.opacity <= 1 ? r.opacity : 1;
+  const blend = PAPER_EFFECT_BLENDS.includes(r.blend) ? r.blend : "multiply";
+  return { ...source, opacity, blend, image: { width, height, data: new Uint8ClampedArray(image.data) }, version: nextPaperEffectVersion() };
+}
+function effectLayersToJSON(map, keep) {
+  const out = {};
+  for (const [id, s] of Object.entries(map)) if (keep(id)) out[id] = sourceOut(s);
+  return Object.keys(out).length ? out : void 0;
+}
+
 // src/paint-editor/controller.ts
 var PaintEditorError = class extends Error {
   constructor(message) {
@@ -3291,6 +3423,10 @@ var PaintEditorController = class _PaintEditorController {
   liveThick = null;
   /** Set while an operation that changes wet paint runs: the simulation before it (for undo). */
   wetOp = null;
+  /** The effects provider slot (see `setEffectsProvider`). */
+  effects = new EffectsSlot();
+  effectsRenderer = new PaintEffectsRenderer();
+  paperEffectNodeCache = null;
   constructor(options = {}) {
     this.historyLimit = Math.max(1, options.historyLimit ?? 200);
     this.doc = createPaintDocument({ width: options.width, height: options.height, dpi: options.dpi, paper: this.resolvePaper(options.paper) });
@@ -3404,6 +3540,21 @@ var PaintEditorController = class _PaintEditorController {
     this.trimWetHistory();
     this.emit();
   }
+  /**
+   * Commits `next` as a new undo step, or with `commitToHistory` false folds it into the last step
+   * when that step has the same label (the later values of one slider drag).
+   */
+  commitOrAmend(label, next, commitToHistory) {
+    const last = this.undoStack[this.undoStack.length - 1];
+    if (commitToHistory || !last || last.label !== label || last.wet || this.wetOp) {
+      this.commit(label, next);
+      return;
+    }
+    last.after = next;
+    this.redoStack = [];
+    this.doc = next;
+    this.emit();
+  }
   /** Keeps the wet snapshots in history within the wet undo memory, dropping the oldest. */
   trimWetHistory() {
     const seen = /* @__PURE__ */ new Set();
@@ -3812,6 +3963,257 @@ var PaintEditorController = class _PaintEditorController {
     }
     return new TiledSurface(4, tiles, 0);
   }
+  // --- Provider effects ------------------------------------------------------------
+  /** The registered effects provider, or `null`. */
+  get effectsProvider() {
+    return this.effects.provider;
+  }
+  /** Registers (or with `null` removes) the effects provider. Not an edit: no undo step. */
+  setEffectsProvider(provider) {
+    this.effects.set(provider);
+  }
+  /** Registers `provider` and returns a function that removes it again (if it is still the one set). */
+  useEffects(provider) {
+    return this.effects.use(provider);
+  }
+  /** 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);
+    if (place) checkPaintEffectPlace(d, place);
+    return d;
+  }
+  /** Every effect layer (top first) with its effect. */
+  listEffectLayers() {
+    const map = this.doc.effectLayers ?? {};
+    return this.listLayers().filter((l) => map[l.id]).map((l) => ({ layerId: l.id, name: l.name, source: map[l.id] }));
+  }
+  /** The effect a layer is drawn from, or `undefined` for other layers. */
+  getEffectLayer(layerId) {
+    return findLayer(this.doc.layers, layerId) ? this.doc.effectLayers?.[layerId] : void 0;
+  }
+  /** The effect paper (without its pixels), or `null`. */
+  getPaperEffect() {
+    const p = this.doc.paperEffect;
+    if (!p) return null;
+    const { image: _i, version: _v, ...rest } = p;
+    return { ...rest, values: { ...rest.values } };
+  }
+  /** Values over `base` (`null` resets a control to its default), checked against the effect's controls. */
+  effectValues(d, base, changes) {
+    const merged = { ...base };
+    const given = {};
+    for (const [k, v] of Object.entries(changes ?? {})) {
+      if (!(k in d.controls.properties)) throw new PaintEditorError(`"${k}" is not a control of "${d.id}"; its controls are ${Object.keys(d.controls.properties).join(", ") || "none"} (describe_effect).`);
+      if (v === null) merged[k] = d.defaults[k];
+      else given[k] = v;
+    }
+    return { ...merged, ...resolveEffectValues({ ...d, defaults: merged }, given) };
+  }
+  /** Renders a generator, overlay or title effect at the canvas size. */
+  renderEffectCanvas(d, values, time = 0) {
+    const { width, height } = this.doc.canvas;
+    return this.effectsRenderer.render(this.effects.require(), d.id, { width, height }, { time, values });
+  }
+  sourceOf(d, values, time) {
+    return { effect: d.id, provider: this.effects.require().id, name: d.name, values, ...time ? { time } : {} };
+  }
+  checkTime(time) {
+    if (time !== void 0 && !(Number.isFinite(time) && time >= 0)) throw new PaintEditorError(`time ${time} is not a moment of the effect; use 0 or more milliseconds.`);
+  }
+  checkOpacity(opacity) {
+    if (opacity !== void 0 && !(opacity >= 0 && opacity <= 1)) throw new PaintEditorError(`opacity ${opacity} is out of range; use 0..1.`);
+  }
+  /** A pixel layer that takes effect pixels: unlocked, visible, no sticker layer, no wet paint. */
+  effectTarget(layerId, what) {
+    const l = this.paintTarget(layerId, what);
+    if (this.doc.stickers?.[l.id]?.length) throw new PaintEditorError(`Layer "${l.name}" is a sticker layer; ${what} another layer (add_layer).`);
+    if (this.wet.wetLayerIds().includes(l.id)) throw new PaintEditorError(`Layer "${l.name}" holds wet paint; effects go on dried paint, so dry it first (dry_paint) and try again.`);
+    return l;
+  }
+  /** After an effect rendered: the layer must be as it was when the render started. */
+  sameLayerAfterRender(before) {
+    this.requireIdle("applying an effect");
+    const now = this.getLayer(before.id);
+    if (!isPixelLayer(now)) throw new PaintEditorError(`Layer "${before.name}" was removed while the effect rendered.`);
+    if (now.surface !== before.surface || now.offset.x !== before.offset.x || now.offset.y !== before.offset.y) throw new PaintEditorError(`Layer "${before.name}" changed while the effect rendered; apply the effect again.`);
+    return now;
+  }
+  /** The canvas rectangle in a layer's own coordinates. */
+  canvasRectOf(l) {
+    return { x: -l.offset.x, y: -l.offset.y, width: this.doc.canvas.width, height: this.doc.canvas.height };
+  }
+  /**
+   * Sets the effect paper: a provider generator drawn over the paper and under the paint, at the
+   * canvas size (`multiply` by default, so the paper's colour and grain still show). `null` removes
+   * it. One undo step. Returns the effect paper (without pixels), or `null`.
+   */
+  async setPaperEffect(effect, options = {}) {
+    this.requireIdle("changing the paper");
+    if (effect === null) {
+      if (!this.doc.paperEffect) return null;
+      const { paperEffect: _p, ...rest } = this.doc;
+      this.commit("Remove effect paper", rest);
+      return null;
+    }
+    this.checkOpacity(options.opacity);
+    this.checkTime(options.time);
+    if (options.blend !== void 0 && !PAPER_EFFECT_BLENDS.includes(options.blend)) throw new PaintEditorError(`Unknown effect paper blend "${options.blend}"; use ${PAPER_EFFECT_BLENDS.join(", ")}.`);
+    const d = await this.describeEffect(effect, "paper");
+    const values = this.effectValues(d, { ...d.defaults }, options.values);
+    const pixels = await this.renderEffectCanvas(d, values, options.time);
+    this.requireIdle("changing the paper");
+    const was = this.doc.paperEffect;
+    const paperEffect = {
+      ...this.sourceOf(d, values, options.time),
+      opacity: options.opacity ?? was?.opacity ?? 1,
+      blend: options.blend ?? was?.blend ?? "multiply",
+      image: { width: pixels.width, height: pixels.height, data: new Uint8ClampedArray(pixels.data) },
+      version: nextPaperEffectVersion()
+    };
+    this.commit("Effect paper", { ...this.doc, paperEffect });
+    return this.getPaperEffect();
+  }
+  /**
+   * Changes the effect paper: new control `values` (merged over its own; `null` resets one) or
+   * `time` draw it again at the canvas size; `opacity` and `blend` only change how it is drawn.
+   * One undo step; with `commitToHistory` false it joins the previous effect paper step (a slider
+   * drag). Returns the effect paper (without pixels).
+   */
+  async updatePaperEffect(changes, commitToHistory = true) {
+    this.requireIdle("changing the paper");
+    const was = this.doc.paperEffect;
+    if (!was) throw new PaintEditorError("There is no effect paper; set one with set_paper_effect.");
+    this.checkOpacity(changes.opacity);
+    this.checkTime(changes.time);
+    if (changes.blend !== void 0 && !PAPER_EFFECT_BLENDS.includes(changes.blend)) throw new PaintEditorError(`Unknown effect paper blend "${changes.blend}"; use ${PAPER_EFFECT_BLENDS.join(", ")}.`);
+    let next = { ...was, ...changes.opacity !== void 0 ? { opacity: changes.opacity } : {}, ...changes.blend !== void 0 ? { blend: changes.blend } : {} };
+    const { width, height } = this.doc.canvas;
+    if (changes.values !== void 0 || changes.time !== void 0 || was.image.width !== width || was.image.height !== height) {
+      const d = await this.describeEffect(was.effect, "paper");
+      const values = this.effectValues(d, was.values, changes.values);
+      const time = changes.time ?? was.time ?? 0;
+      const pixels = await this.renderEffectCanvas(d, values, time);
+      this.requireIdle("changing the paper");
+      if (this.doc.paperEffect !== was) throw new PaintEditorError("The effect paper changed while it rendered; change it again.");
+      next = { ...next, ...this.sourceOf(d, values, time), image: { width: pixels.width, height: pixels.height, data: new Uint8ClampedArray(pixels.data) }, version: nextPaperEffectVersion() };
+      if (!time) delete next.time;
+    }
+    this.commitOrAmend("Effect paper", { ...this.doc, paperEffect: next }, commitToHistory);
+    return this.getPaperEffect();
+  }
+  /**
+   * Adds an effect layer above the active layer (or `aboveId`): a pixel layer drawn by a provider
+   * generator, overlay or title effect at the canvas size. It keeps its effect, so
+   * `updateEffectLayer` draws it again. One undo step. Returns the layer and its effect.
+   */
+  async addEffectLayer(effect, options = {}) {
+    this.requireIdle("adding a layer");
+    this.checkOpacity(options.opacity);
+    this.checkTime(options.time);
+    if (options.blend !== void 0 && !isBlendMode(options.blend)) throw new PaintEditorError(`Unknown blend mode "${options.blend}". Call get_canvas_info for the blend modes.`);
+    if (options.aboveId !== void 0) this.requireLayer(options.aboveId);
+    const d = await this.describeEffect(effect, "layer");
+    const values = this.effectValues(d, { ...d.defaults }, options.values);
+    const pixels = await this.renderEffectCanvas(d, values, options.time);
+    this.requireIdle("adding a layer");
+    const above = options.aboveId ?? this.doc.activeLayerId;
+    const loc = above ? findLayer(this.doc.layers, above) : null;
+    if (options.aboveId !== void 0 && !loc) throw new PaintEditorError(`Layer "${options.aboveId}" was removed while the effect rendered.`);
+    const layer = { ...createPaintLayer(options.name?.trim() || d.name), surface: surfaceFromPixels(pixels, 4), opacity: options.opacity ?? 1, blend: options.blend ?? "normal" };
+    const layers = insertLayer(this.doc.layers, layer, loc?.parent?.id ?? null, loc ? loc.index + 1 : void 0);
+    const source = this.sourceOf(d, values, options.time);
+    this.commit("Add effect layer", { ...this.doc, layers, activeLayerId: layer.id, effectLayers: { ...this.doc.effectLayers ?? {}, [layer.id]: source } });
+    return { layer: this.describeLayer(layer), source };
+  }
+  /**
+   * Draws an effect layer again with new `values` (merged over its own; `null` resets one) or
+   * `time`, at the canvas size, replacing its pixels (paint on it is lost). One undo step; with
+   * `commitToHistory` false it joins the previous effect layer step (a slider drag).
+   */
+  async updateEffectLayer(layerId, changes, commitToHistory = true) {
+    this.requireIdle("changing an effect layer");
+    const was = this.getEffectLayer(layerId);
+    if (!was) throw new PaintEditorError(`"${layerId}" is not an effect layer; add one with add_effect_layer.`);
+    this.checkTime(changes.time);
+    const l = this.effectTarget(layerId, "draw the effect on");
+    const d = await this.describeEffect(was.effect, "layer");
+    const values = this.effectValues(d, was.values, changes.values);
+    const time = changes.time ?? was.time ?? 0;
+    const pixels = await this.renderEffectCanvas(d, values, time);
+    const now = this.getLayer(l.id);
+    this.requireIdle("changing an effect layer");
+    if (!isPixelLayer(now)) throw new PaintEditorError(`Layer "${l.name}" was removed while the effect rendered.`);
+    const source = this.sourceOf(d, values, time);
+    this.commitOrAmend("Effect layer", { ...this.doc, layers: mapLayer(this.doc.layers, l.id, () => ({ ...now, surface: surfaceFromPixels(pixels, 4), offset: { x: 0, y: 0 } })), effectLayers: { ...this.doc.effectLayers ?? {}, [l.id]: source } }, commitToHistory);
+    return source;
+  }
+  /** Turns an effect layer into a plain pixel layer, keeping its pixels (one undo step). */
+  rasterizeEffectLayer(layerId) {
+    this.requireIdle("changing an effect layer");
+    if (!this.getEffectLayer(layerId)) throw new PaintEditorError(`"${layerId}" is not an effect layer; list_applied_effects lists them.`);
+    const { [layerId]: _gone, ...rest } = this.doc.effectLayers ?? {};
+    this.commit("Rasterize effect layer", { ...this.doc, effectLayers: rest });
+    return this.describeLayer(this.requireLayer(layerId));
+  }
+  /**
+   * Fills a layer with a provider generator, overlay or title effect: its pixels, rendered at the
+   * canvas size, are composited onto the layer's paint at `opacity` (only where it is already
+   * painted with `lockTransparency`, or when the layer's transparency is locked). One undo step.
+   */
+  async fillLayerWithEffect(effect, options = {}) {
+    this.requireIdle("filling");
+    this.checkOpacity(options.opacity);
+    this.checkTime(options.time);
+    const l = this.effectTarget(options.layerId, "fill");
+    const d = await this.describeEffect(effect, "fill");
+    const values = this.effectValues(d, { ...d.defaults }, options.values);
+    const pixels = await this.renderEffectCanvas(d, values, options.time);
+    const now = this.sameLayerAfterRender(l);
+    const rect = this.canvasRectOf(now);
+    const before = readRegion(now.surface, rect);
+    let after = overPixels(before, pixels.data, options.opacity ?? 1);
+    if (options.lockTransparency || isLayerLocked(now, "transparency")) after = mixPixels(before, after, 1);
+    const surface = writeRegion(now.surface, rect, after);
+    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) };
+  }
+  /**
+   * 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
+   * relief, and an effect with a `height` input gets the relief as a height map. Wet paint is
+   * refused (dry it first). One undo step.
+   */
+  async applyLightEffect(layerId, effect, options = {}) {
+    this.requireIdle("applying an effect");
+    const amount = options.amount ?? 1;
+    if (!(amount >= 0 && amount <= 1)) throw new PaintEditorError(`amount ${options.amount} is out of range; use 0..1.`);
+    this.checkTime(options.time);
+    const l = this.effectTarget(layerId, "light");
+    if (!contentBounds(l.surface)) throw new PaintEditorError(`Layer "${l.name}" has no paint to light; paint on it first, or add an effect layer (add_effect_layer).`);
+    const d = await this.describeEffect(effect, "light");
+    const values = this.effectValues(d, { ...d.defaults }, options.values);
+    const rect = this.canvasRectOf(l);
+    const before = readRegion(l.surface, rect);
+    const inputs = { source: { width: rect.width, height: rect.height, data: before } };
+    const heightInput = d.inputs.find((i) => i.kind === "image" && /^(height|depth|relief)$/i.test(i.name));
+    const relief = this.doc.thick?.[l.id];
+    if (heightInput && relief) {
+      const h = readRegion(relief.height, rect);
+      const rgba = new Uint8ClampedArray(rect.width * rect.height * 4);
+      for (let i = 0; i < h.length; i++) rgba.set([h[i], h[i], h[i], 255], i * 4);
+      inputs[heightInput.name] = { width: rect.width, height: rect.height, data: rgba };
+    }
+    const sourceInput = d.inputs.find((i) => i.kind === "image" && i.name !== heightInput?.name)?.name ?? "source";
+    if (sourceInput !== "source") {
+      inputs[sourceInput] = inputs.source;
+      delete inputs.source;
+    }
+    const out = await this.effectsRenderer.render(this.effects.require(), d.id, { width: rect.width, height: rect.height }, { time: options.time ?? 0, values, inputs });
+    const now = this.sameLayerAfterRender(l);
+    const surface = writeRegion(now.surface, rect, mixPixels(before, out.data, amount));
+    this.commit("Light effect", { ...this.doc, layers: mapLayer(this.doc.layers, now.id, () => ({ ...now, surface })) });
+    return { layerId: now.id, source: this.sourceOf(d, values, options.time), amount };
+  }
   // --- Brushes -------------------------------------------------------------------
   findBrush(id) {
     return BUILTIN_BRUSHES.find((b) => b.id === id) ?? this.userBrushes.find((b) => b.id === id);
@@ -4464,6 +4866,7 @@ var PaintEditorController = class _PaintEditorController {
   /** Stops the wet simulation's worker threads (call when the editor goes away). */
   dispose() {
     this.wet.destroy();
+    this.effectsRenderer.dispose();
   }
   /** Resolves when wet paint is between steps (edits, undo and exports can run). */
   wetIdle() {
@@ -4651,6 +5054,14 @@ var PaintEditorController = class _PaintEditorController {
     if (!t || !t.visible) return [];
     return [this.tracingNode(t)];
   }
+  /** The effect paper as a compositor layer (one object per effect paper, so caches hold). */
+  paperEffectNode(p) {
+    const c = this.paperEffectNodeCache;
+    if (c && c.image === p.image && c.opacity === p.opacity && c.blend === p.blend) return c;
+    const node = { type: "image", id: PAPER_EFFECT_NODE_ID, name: "Effect paper", visible: true, opacity: p.opacity, blend: p.blend, image: p.image, version: p.version };
+    this.paperEffectNodeCache = node;
+    return node;
+  }
   /** The tracing image resampled onto the canvas (cached until it or the canvas changes). */
   tracingNode(t) {
     const { width, height } = this.doc.canvas;
@@ -4700,6 +5111,7 @@ var PaintEditorController = class _PaintEditorController {
       layers = picked.map((l) => ({ ...l, visible: true }));
     }
     const under = options.paper === false ? [] : [paperNode(this.doc.paper, this.lighting)];
+    if (options.paper !== false && this.doc.paperEffect) under.push(this.paperEffectNode(this.doc.paperEffect));
     if (view) under.push(...this.underlayLayers());
     return [...under, ...layers];
   }
@@ -4774,6 +5186,11 @@ var PaintEditorController = class _PaintEditorController {
     for (const [id, list] of Object.entries(this.doc.stickers ?? {})) if (list.length && findLayer(this.doc.layers, id)) stickers[id] = list.map((x) => ({ ...x }));
     if (Object.keys(stickers).length) ext.stickers = stickers;
     else delete ext.stickers;
+    const effectLayers = effectLayersToJSON(this.doc.effectLayers ?? {}, (id) => isPixelLayer(findLayer(this.doc.layers, id)?.layer));
+    if (effectLayers) ext.effectLayers = effectLayers;
+    else delete ext.effectLayers;
+    if (this.doc.paperEffect) ext.paperEffect = paperEffectToJSON(this.doc.paperEffect);
+    else delete ext.paperEffect;
     if (this.lighting.azimuth !== DEFAULT_LIGHTING.azimuth || this.lighting.elevation !== DEFAULT_LIGHTING.elevation || this.lighting.relief !== DEFAULT_LIGHTING.relief) ext.lighting = { ...this.lighting };
     else delete ext.lighting;
     return ext;
@@ -4792,6 +5209,23 @@ var PaintEditorController = class _PaintEditorController {
       }
       if (Object.keys(stickers).length) state = { ...state, stickers };
     }
+    if (ext.effectLayers && typeof ext.effectLayers === "object") {
+      const effectLayers = {};
+      for (const [id, v] of Object.entries(ext.effectLayers)) {
+        if (!isPixelLayer(findLayer(state.layers, id)?.layer)) continue;
+        const source = readPaintEffectSource(v);
+        if (source) effectLayers[id] = source;
+        else problems.push(`The effect of layer "${id}" could not be read; it loads as a plain layer.`);
+      }
+      if (Object.keys(effectLayers).length) state = { ...state, effectLayers };
+    }
+    if (ext.paperEffect !== void 0) {
+      try {
+        state = { ...state, paperEffect: paperEffectFromJSON(ext.paperEffect, state.canvas.width, state.canvas.height) };
+      } catch (e) {
+        problems.push(`The effect paper could not be read (${e.message}); the plain paper shows.`);
+      }
+    }
     const raw = ext.layerChannels;
     if (!raw || typeof raw !== "object") return state;
     const thick = {};
@@ -4828,6 +5262,8 @@ var PaintEditorController = class _PaintEditorController {
     delete this.extensions.layerChannels;
     delete this.extensions.lighting;
     delete this.extensions.stickers;
+    delete this.extensions.effectLayers;
+    delete this.extensions.paperEffect;
     this.viewCompositor.clear();
     this.emit();
     return loaded.problems;
@@ -5025,7 +5461,7 @@ var PaintEditorController = class _PaintEditorController {
   /** Adds a floating reference image to look at and pick colours from. */
   addReferenceImage(options) {
     const { src, pixels } = this.importImage(options, "The reference image");
-    const ref = {
+    const ref2 = {
       id: `ref${this.nextReferenceId++}`,
       name: options.name?.trim() || `Reference ${this.guides.references.length + 1}`,
       src,
@@ -5036,8 +5472,8 @@ var PaintEditorController = class _PaintEditorController {
       displayWidth: options.displayWidth ?? Math.min(240, pixels.width),
       visible: true
     };
-    this.setGuides({ ...this.guides, references: [...this.guides.references, ref] });
-    return ref;
+    this.setGuides({ ...this.guides, references: [...this.guides.references, ref2] });
+    return ref2;
   }
   requireReference(id) {
     const r = this.guides.references.find((x) => x.id === id);
@@ -5101,12 +5537,12 @@ var PaintEditorController = class _PaintEditorController {
       }
     }
     if (Array.isArray(r.references)) {
-      for (const ref of r.references) {
-        if (!ref || typeof ref.src !== "string" || typeof ref.id !== "string") continue;
+      for (const ref2 of r.references) {
+        if (!ref2 || typeof ref2.src !== "string" || typeof ref2.id !== "string") continue;
         try {
-          const px = this.decodeImage(ref.src, `Reference "${ref.name}"`);
-          guides.references.push({ id: ref.id, name: String(ref.name ?? ref.id), src: ref.src, width: px.width, height: px.height, x: Number(ref.x) || 0, y: Number(ref.y) || 0, displayWidth: Number(ref.displayWidth) || 240, visible: ref.visible !== false });
-          const n = Number(/^ref(\d+)$/.exec(ref.id)?.[1] ?? 0);
+          const px = this.decodeImage(ref2.src, `Reference "${ref2.name}"`);
+          guides.references.push({ id: ref2.id, name: String(ref2.name ?? ref2.id), src: ref2.src, width: px.width, height: px.height, x: Number(ref2.x) || 0, y: Number(ref2.y) || 0, displayWidth: Number(ref2.displayWidth) || 240, visible: ref2.visible !== false });
+          const n = Number(/^ref(\d+)$/.exec(ref2.id)?.[1] ?? 0);
           if (n >= this.nextReferenceId) this.nextReferenceId = n + 1;
         } catch (e) {
           problems.push(e.message);
@@ -7938,6 +8374,176 @@ function quickStencil(kind, canvas) {
       return { kind: "line", from: { x: w / 2, y: 0 }, to: { x: w / 2, y: h } };
   }
 }
+
+// src/paint-editor/effect-tools.ts
+var PAPER_TARGET = "paper";
+var ref = (s) => ({ effect: s.effect, ...s.name ? { name: s.name } : {}, ...s.provider ? { provider: s.provider } : {} });
+function createPaintEffectsToolProvider(controller, options = {}) {
+  const readOnlyReason = () => {
+    const ro = typeof options.readOnly === "function" ? options.readOnly() : options.readOnly;
+    return ro ? typeof ro === "string" ? ro : "The painting is read-only." : null;
+  };
+  const paperInfo = () => {
+    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 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 } : {} }] : [];
+  };
+  const requireLayer = (id) => {
+    const l = controller.getLayer(id);
+    if (!l) {
+      const ids = controller.listLayers().map((x) => `"${x.id}"`);
+      throw new Error(`There is no layer "${id}"; the targets are "${PAPER_TARGET}" and the layers ${ids.join(", ") || "(none)"} (list_layers lists them).`);
+    }
+    return l;
+  };
+  const effectsOf = (target) => target === PAPER_TARGET ? paperInfo() : layerInfo(target);
+  const instanceCheck = (target, instance) => {
+    const want = target === PAPER_TARGET ? PAPER_TARGET : "effect";
+    if (target !== PAPER_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.`
+      );
+    }
+  };
+  const noStackArgs = (changes) => {
+    if (changes.index !== void 0) throw new Error("index does not apply: the paper and each effect layer have one effect.");
+    if (changes.enabled !== void 0) throw new Error("enabled does not apply here: hide an effect layer with update_layer visible false, or remove the effect paper.");
+  };
+  const values = (v) => v;
+  return createEffectToolProvider({
+    id: options.id ?? "paint-effects",
+    namespace: options.namespace,
+    target: { noun: "layer", id: `A pixel layer id from list_layers ("${PAPER_TARGET}" is the effect paper, 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) {
+        const l = requireLayer(target);
+        return [{ target, name: l.name, effects: layerInfo(target) }];
+      }
+      const out = [];
+      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.");
+      noStackArgs(args);
+      requireLayer(target);
+      const r = await controller.applyLightEffect(target, effect, { values: values(args.values), amount: args.opacity });
+      const applied = { id: "light", ...ref(r.source), role: "baked light", enabled: true, opacity: r.amount, values: r.source.values };
+      return { target, effect: applied, effects: layerInfo(target), baked: true };
+    },
+    update: async (target, instance, changes) => {
+      instanceCheck(target, instance);
+      noStackArgs(changes);
+      if (target === PAPER_TARGET) {
+        await controller.updatePaperEffect({ values: changes.values, opacity: changes.opacity });
+        const effects2 = paperInfo();
+        return { target, effect: effects2[0], effects: effects2 };
+      }
+      if (changes.opacity !== void 0) throw new Error("An effect layer's opacity is the layer's: change it with update_layer.");
+      await controller.updateEffectLayer(target, { values: changes.values });
+      const effects = layerInfo(target);
+      return { target, effect: effects[0], effects };
+    },
+    remove: async (target, instance) => {
+      instanceCheck(target, instance);
+      const was = effectsOf(target)[0];
+      if (target === PAPER_TARGET) await controller.setPaperEffect(null);
+      else controller.rasterizeEffectLayer(target);
+      return { target, effect: was, effects: [], ...target === PAPER_TARGET ? {} : { keptPixels: true } };
+    },
+    subscribe: (notify) => {
+      const a = controller.subscribe(() => notify());
+      const b = controller.effects.subscribe(() => notify());
+      return () => {
+        a();
+        b();
+      };
+    },
+    extraTools: (ctx) => [
+      {
+        name: "set_paper_effect",
+        title: "Set the effect paper",
+        description: `Draws a provider generator (search_effects with use generator) over the paper and under the paint, at the canvas size: multiplied by default, so the paper's colour and grain still show. Replaces any effect paper; it is saved and exported with the painting. effect null removes it. One undo step. Returns the effect paper (update_effect / remove_effect with target and effect "paper" change it later).`,
+        inputSchema: {
+          type: "object",
+          properties: {
+            effect: { anyOf: [ctx.effectIdSchema(["generator"]), { type: "null" }], description: "A generator effect id from search_effects, or null to remove the effect paper." },
+            values: ctx.valuesSchema("Control values over the effect's defaults"),
+            opacity: { type: "number", minimum: 0, maximum: 1, description: "Strength 0\u20131 (default 1, or the current effect paper's)." },
+            blend: { type: "string", enum: [...PAPER_EFFECT_BLENDS], description: "How it draws over the paper (default multiply, which keeps the paper's grain; normal covers it)." },
+            time: { type: "number", minimum: 0, description: "Which moment of an animated effect to draw, in ms (default 0)." }
+          },
+          required: ["effect"],
+          additionalProperties: false
+        },
+        annotations: { title: "Set the effect paper", ...ctx.annotations.writeIdempotent },
+        handler: async (args) => {
+          if (args.effect !== null) ctx.requireProvider();
+          return { paperEffect: await controller.setPaperEffect(args.effect, { values: values(args.values), opacity: args.opacity, blend: args.blend, time: args.time }) };
+        }
+      },
+      {
+        name: "add_effect_layer",
+        title: "Add an effect layer",
+        description: 'Adds a pixel layer drawn by a provider generator, overlay or title effect (search_effects with use generator, overlay or title) at the canvas size, above the active layer unless aboveId is given, and makes it active. Paint on it like any layer; update_effect (effect "effect") draws it again with new values, replacing its pixels; remove_effect keeps its pixels as a plain layer. One undo step. Returns the new layer and its effect.',
+        inputSchema: {
+          type: "object",
+          properties: {
+            effect: ctx.effectIdSchema(["generator", "overlay", "title"]),
+            values: ctx.valuesSchema("Control values over the effect's defaults"),
+            name: { type: "string", minLength: 1, description: "The layer name (default: the effect's name)." },
+            aboveId: { type: "string", minLength: 1, description: "Put it directly above this layer (default: above the active layer, else on top)." },
+            opacity: { type: "number", minimum: 0, maximum: 1, description: "Layer opacity 0\u20131 (default 1)." },
+            blend: { type: "string", enum: BLEND_MODES.map((m) => m.id), description: "Layer blend mode (default normal); screen or linear-dodge for light, multiply for textures." },
+            time: { type: "number", minimum: 0, description: "Which moment of an animated effect to draw, in ms (default 0)." }
+          },
+          required: ["effect"],
+          additionalProperties: false
+        },
+        annotations: { title: "Add an effect layer", ...ctx.annotations.write },
+        handler: async (args) => {
+          ctx.requireProvider();
+          const r = await controller.addEffectLayer(args.effect, { values: values(args.values), name: args.name, aboveId: args.aboveId, opacity: args.opacity, blend: args.blend, time: args.time });
+          return { layer: r.layer, effects: layerInfo(r.layer.id) };
+        }
+      },
+      {
+        name: "fill_layer_with_effect",
+        title: "Fill a layer with an effect",
+        description: "Composites a provider generator, overlay or title effect (rendered at the canvas size) onto a layer's pixels at opacity, as a fill: the layer keeps no link to the effect. lockTransparency (or a transparency-locked layer) only colours what is already painted. Wet paint is refused: dry it first (dry_paint). One undo step. Returns the layer id and the effect used.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            effect: ctx.effectIdSchema(["generator", "overlay", "title"]),
+            layerId: { type: "string", minLength: 1, description: "The pixel layer to fill (default: the active layer)." },
+            values: ctx.valuesSchema("Control values over the effect's defaults"),
+            opacity: { type: "number", minimum: 0, maximum: 1, description: "Fill strength 0\u20131 (default 1)." },
+            lockTransparency: { type: "boolean", description: "Only colour pixels that are already painted (default false)." },
+            time: { type: "number", minimum: 0, description: "Which moment of an animated effect to draw, in ms (default 0)." }
+          },
+          required: ["effect"],
+          additionalProperties: false
+        },
+        annotations: { title: "Fill a layer with an effect", ...ctx.annotations.write },
+        handler: async (args) => {
+          ctx.requireProvider();
+          return controller.fillLayerWithEffect(args.effect, { layerId: args.layerId, values: values(args.values), opacity: args.opacity, lockTransparency: args.lockTransparency, time: args.time });
+        }
+      }
+    ]
+  });
+}
 export {
   BLEND_MENU_GROUPS,
   BLEND_MODES,
@@ -7991,6 +8597,7 @@ export {
   PAINT_BRUSH_CATEGORIES,
   PAINT_BRUSH_ENGINES,
   PAINT_COLOR_JSON_SCHEMA,
+  PAINT_EFFECT_PLACES,
   PAINT_FORMAT,
   PAINT_GRADIENT_FULL_SPEED,
   PAINT_GRADIENT_JSON_SCHEMA,
@@ -8005,10 +8612,13 @@ export {
   PAINT_SCHEMA_VERSION,
   PAINT_SOURCE_JSON_SCHEMA,
   PAINT_TOOLS,
+  PAPER_EFFECT_BLENDS,
+  PAPER_EFFECT_NODE_ID,
   PAPER_FAMILIES,
   PAPER_LIBRARY,
   PAPER_NODE_ID,
   PAPER_SLIDERS,
+  PAPER_TARGET,
   PARTICLE_KINDS,
   PARTICLE_KIND_LABELS,
   PARTICLE_RENDERS,
@@ -8019,6 +8629,7 @@ export {
   PaintDocumentError,
   PaintEditorController,
   PaintEditorError,
+  PaintEffectsRenderer,
   PaintGesture,
   PaintGradientSampler,
   PaintPresence,
@@ -8065,6 +8676,7 @@ export {
   brushTakesPaint,
   brushToJSON,
   buildTimeLapse,
+  checkPaintEffectPlace,
   clonePaper,
   colorHarmony,
   composeAffine,
@@ -8072,6 +8684,7 @@ export {
   createPaintCompositor,
   createPaintDocument,
   createPaintEditorToolProvider,
+  createPaintEffectsToolProvider,
   createPaintLayer,
   createPaintReplayTools,
   createPaintStickerTools,
@@ -8088,6 +8701,7 @@ export {
   downsampleRgba,
   drawSticker,
   drawWaterOverlay,
+  effectLayersToJSON,
   emptiedLayers,
   emptyThickChannels,
   fitZoom,
@@ -8112,6 +8726,7 @@ export {
   lightingKey,
   mapPenPoint,
   mix32,
+  mixPixels,
   mixerLoadForStroke,
   mixerTip,
   multiColorForDab,
@@ -8120,6 +8735,7 @@ export {
   multiColorSliders,
   multiColorToPaint,
   newPaintLayerId,
+  nextPaperEffectVersion,
   normalizeBehavior,
   normalizeBristle,
   normalizeBrushStroke,
@@ -8142,11 +8758,14 @@ export {
   normalizeView,
   normalizeWetBrush,
   normalizeWetParams,
+  overPixels,
   padSampleRadius,
   paintGradientMappingFor,
   paintSourceColor,
   paintSourceCss,
   paintToMultiColor,
+  paperEffectFromJSON,
+  paperEffectToJSON,
   paperGrain,
   paperKey,
   paperNode,
@@ -8163,6 +8782,7 @@ export {
   quickStencil,
   rand01,
   randSigned,
+  readPaintEffectSource,
   readPaintSource,
   readPath,
   readSwatch,