@pixerate/editor 0.93.0 → 0.94.0

package/dist/image-editor/index.js

@@ -5,17 +5,25 @@ import {
   createCaptureTool
 } from "../chunk-REOJJIY3.js";
 import {
+  DEFAULT_GLOBAL_LIGHT,
   DIRECT_GAUSSIAN_MAX_SIGMA,
+  LAYER_EFFECT_KINDS,
+  LayerEffectError,
   RasterCompositor,
   ZlibError,
   adler32,
   base64ToBytes,
   blendTile,
+  builtinPattern,
+  builtinPatternIds,
   bytesToBase64,
   changedTiles,
+  curveLut,
   decodePng,
+  defaultLayerEffect,
   deflate,
   deflateRaw,
+  effectsMargin,
   encodePng,
   findLayer,
   flattenLayers,
@@ -23,12 +31,18 @@ import {
   inflate,
   inflateRaw,
   insertLayer,
+  isLayerEffectKind,
   isLayerLocked,
   isPng,
+  layerEffectLabel,
   mapLayer,
+  mergeLayerEffect,
+  newEffectId,
+  normalizeLayerEffects,
   parseDataUrl,
-  pngDataUrl
-} from "../chunk-P5TPUNBZ.js";
+  pngDataUrl,
+  validateLayerEffects
+} from "../chunk-747CGOT2.js";
 import {
   CoverageMap,
   DEFAULT_BRUSH,
@@ -1496,59 +1510,6 @@ function normalizeAdjustmentLayers(raw) {
   }
   return out;
 }
-function curveLut(points, size = ADJUSTMENT_LUT_SIZE) {
-  const pts = points.filter((p) => Number.isFinite(p.input) && Number.isFinite(p.output)).map((p) => [p.input, p.output]).sort((a, b) => a[0] - b[0]);
-  const dedup = [];
-  for (const p of pts) {
-    if (dedup.length && Math.abs(dedup[dedup.length - 1][0] - p[0]) < 1e-6) continue;
-    dedup.push(p);
-  }
-  const out = new Float32Array(size);
-  const n = dedup.length;
-  if (n < 2) {
-    for (let k = 0; k < size; k++) out[k] = k / (size - 1);
-    return out;
-  }
-  const x = dedup.map((p) => p[0]);
-  const y = dedup.map((p) => p[1]);
-  const m2 = new Float64Array(n);
-  if (n > 2) {
-    const c = new Float64Array(n);
-    const d = new Float64Array(n);
-    for (let i = 1; i < n - 1; i++) {
-      const h0 = x[i] - x[i - 1];
-      const h1 = x[i + 1] - x[i];
-      const a = h0 / 6;
-      const b = (h0 + h1) / 3;
-      const cc = h1 / 6;
-      const r = (y[i + 1] - y[i]) / h1 - (y[i] - y[i - 1]) / h0;
-      const denom = b - a * c[i - 1];
-      c[i] = cc / denom;
-      d[i] = (r - a * d[i - 1]) / denom;
-    }
-    for (let i = n - 2; i >= 1; i--) m2[i] = d[i] - c[i] * m2[i + 1];
-  }
-  let seg = 0;
-  for (let k = 0; k < size; k++) {
-    const xv = k / (size - 1);
-    if (xv <= x[0]) {
-      out[k] = clamp01(y[0]);
-      continue;
-    }
-    if (xv >= x[n - 1]) {
-      out[k] = clamp01(y[n - 1]);
-      continue;
-    }
-    while (seg < n - 2 && xv > x[seg + 1]) seg++;
-    const x0 = x[seg], x1 = x[seg + 1];
-    const h = x1 - x0;
-    const a = (x1 - xv) / h;
-    const b = (xv - x0) / h;
-    const v = a * y[seg] + b * y[seg + 1] + ((a * a * a - a) * m2[seg] + (b * b * b - b) * m2[seg + 1]) * (h * h) / 6;
-    out[k] = clamp01(v);
-  }
-  return out;
-}
 function curveLutFromLevels(points) {
   return curveLut(points.map((p) => ({ input: p.input / 255, output: p.output / 255 })));
 }
@@ -2700,7 +2661,7 @@ function developTarget(layers, activeLayerId) {
   }
   return pixels.find((l) => l.source === "document") ?? pixels.find((l) => l.id === BACKGROUND_LAYER_ID) ?? pixels[0] ?? null;
 }
-var isPlain = (l) => l.visible && l.opacity === 1 && l.blend === "normal" && !l.clipped && !l.mask && !l.locks;
+var isPlain = (l) => l.visible && l.opacity === 1 && l.blend === "normal" && !l.clipped && !l.mask && !l.locks && !l.effects;
 function legacyView(stack, width, height, activeLayerId = null) {
   const { layers } = stack;
   const target = developTarget(layers, activeLayerId);
@@ -2740,7 +2701,7 @@ function isLegacyShape(stack) {
   const bg = layers[0];
   if (!bg || bg.type !== "pixel" || bg.source !== "document") return false;
   if (bg.id !== BACKGROUND_LAYER_ID || bg.name !== BACKGROUND_LAYER_NAME) return false;
-  if (!bg.visible || bg.opacity !== 1 || bg.blend !== "normal" || bg.clipped || bg.locks) return false;
+  if (!bg.visible || bg.opacity !== 1 || bg.blend !== "normal" || bg.clipped || bg.locks || bg.effects) return false;
   if ((bg.fillOpacity ?? 1) !== 1 || bg.offset.x !== 0 || bg.offset.y !== 0) return false;
   const filters = bg.filters ?? [];
   if (filters.length < 1 || filters.length > 2) return false;
@@ -2756,7 +2717,7 @@ function isLegacyShape(stack) {
   let adjustments = 0;
   for (; i < layers.length && layers[i].type === "adjustment"; i++) {
     const l = layers[i];
-    if (l.clipped || l.locks || l.mask?.source) return false;
+    if (l.clipped || l.locks || l.mask?.source || l.effects) return false;
     adjustments++;
   }
   for (; i < layers.length; i++) {
@@ -3262,7 +3223,9 @@ var ImageEditorRenderer = class {
         return this.depthMaps.get(`${source.maskSource}|${width}x${height}`) ?? null;
       },
       rasterizeAnnotation: (annotation, rect) => this.rasterizeAnnotation(annotation, rect),
-      version: `${host?.version() ?? ""}:${this.assetVersion}`
+      version: `${host?.version() ?? ""}:${this.assetVersion}`,
+      globalLight: host?.globalLight?.(),
+      pattern: host?.pattern ? (id) => host.pattern(id) : void 0
     };
   }
   /** Loads what the compositor reads synchronously: depth maps (at canvas size) and annotation images. */
@@ -4535,8 +4498,29 @@ function baseFields(layer, ctx) {
   if (layer.clipped) out.clipped = true;
   if (layer.mask) out.mask = serializeMask(layer.mask, `${layer.id}-mask`, ctx);
   if (layer.locks && Object.values(layer.locks).some(Boolean)) out.locks = { ...layer.locks };
+  if (layer.effects) out.effects = serializeEffects(layer.effects);
+  return out;
+}
+function serializeEffects(effects) {
+  const out = { enabled: effects.enabled, items: JSON.parse(JSON.stringify(effects.items)) };
+  if (effects.scale !== void 0 && effects.scale !== 1) out.scale = effects.scale;
+  if (effects.psd) out.psd = { key: effects.psd.key, data: bytesToBase64(effects.psd.data) };
   return out;
 }
+function deserializeEffects(raw) {
+  if (!raw || typeof raw !== "object") return void 0;
+  const r = raw;
+  let psd;
+  const p = r.psd;
+  if (p && typeof p.key === "string" && typeof p.data === "string") {
+    try {
+      psd = { key: p.key, data: base64ToBytes(p.data) };
+    } catch {
+      psd = void 0;
+    }
+  }
+  return normalizeLayerEffects({ ...r, psd });
+}
 function serializeMask(mask, hint, ctx) {
   const out = { defaultValue: mask.defaultValue };
   if (!mask.source) {
@@ -4739,6 +4723,8 @@ function deserializeLayer(raw, ctx) {
     for (const k of ["pixels", "transparency", "position", "all"]) if (r.locks[k] === true) locks[k] = true;
     if (Object.keys(locks).length) base.locks = locks;
   }
+  const effects = deserializeEffects(r.effects);
+  if (effects && r.type !== "adjustment") base.effects = effects;
   switch (r.type) {
     case "pixel": {
       const layer = {
@@ -5021,6 +5007,77 @@ function removeLayerFilter(layers, id, filterId) {
   else delete next.filters;
   return mapLayer(layers, id, () => next);
 }
+function requireEffectLayer(layers, id, action) {
+  const layer = requireLayer(layers, id).layer;
+  if (layer.type === "adjustment") fail(`Layer "${layer.name || id}" is an adjustment layer; effects go on pixel, annotation and group layers.`);
+  requireUnlocked(layer, "all", action);
+  return layer;
+}
+function layerEffectsOf(layer) {
+  return layer.effects ?? { enabled: true, items: [] };
+}
+function guard(fn) {
+  try {
+    return fn();
+  } catch (e) {
+    if (e instanceof LayerEffectError) fail(e.message);
+    throw e;
+  }
+}
+function setLayerEffects(layers, id, effects) {
+  const layer = requireEffectLayer(layers, id, "change its effects");
+  const next = { ...layer };
+  if (effects && (effects.items.length || effects.psd || effects.scale !== void 0 || !effects.enabled)) {
+    guard(() => validateLayerEffects(effects));
+    next.effects = effects;
+  } else delete next.effects;
+  return mapLayer(layers, id, () => next);
+}
+function addLayerEffect(layers, id, kind, params = {}, index) {
+  if (!isLayerEffectKind(kind)) fail(`Unknown effect kind "${String(kind)}". Kinds: ${LAYER_EFFECT_KINDS.join(", ")}.`);
+  const layer = requireEffectLayer(layers, id, "add effects");
+  const current = layerEffectsOf(layer);
+  const ids = new Set(current.items.map((e) => e.id));
+  let effectId = newEffectId();
+  while (ids.has(effectId)) effectId = newEffectId();
+  const { id: _ignored, kind: _kind, ...rest } = params;
+  const effect = guard(() => mergeLayerEffect(defaultLayerEffect(kind, effectId), rest));
+  const items = [...current.items];
+  const at = index === void 0 ? items.length : Math.max(0, Math.min(items.length, Math.floor(index)));
+  items.splice(at, 0, effect);
+  return { layers: setLayerEffects(layers, id, { ...current, items }), effect };
+}
+function requireEffect(layer, effectId) {
+  const items = layer.effects?.items ?? [];
+  const i = items.findIndex((e) => e.id === effectId);
+  if (i === -1) fail(`Layer "${layer.name || layer.id}" has no effect "${effectId}". Effects: ${items.map((e) => `${e.id} (${e.kind})`).join(", ") || "none"}; call list_layer_effects.`);
+  return i;
+}
+function updateLayerEffect(layers, id, effectId, changes) {
+  const layer = requireEffectLayer(layers, id, "change its effects");
+  const i = requireEffect(layer, effectId);
+  const current = layer.effects;
+  const items = [...current.items];
+  items[i] = guard(() => mergeLayerEffect(items[i], changes));
+  return setLayerEffects(layers, id, { ...current, items });
+}
+function removeLayerEffect(layers, id, effectId) {
+  const layer = requireEffectLayer(layers, id, "change its effects");
+  requireEffect(layer, effectId);
+  const current = layer.effects;
+  return setLayerEffects(layers, id, { ...current, items: current.items.filter((e) => e.id !== effectId) });
+}
+function setLayerEffectsEnabled(layers, id, enabled, scale) {
+  const layer = requireEffectLayer(layers, id, "change its effects");
+  if (scale !== void 0 && !(Number.isFinite(scale) && scale >= 0.01 && scale <= 10)) fail(`scale must be from 0.01 to 10 (1 = 100 %), got ${scale}.`);
+  const current = layerEffectsOf(layer);
+  const next = { ...current, enabled };
+  if (scale !== void 0) {
+    if (scale === 1) delete next.scale;
+    else next.scale = scale;
+  }
+  return setLayerEffects(layers, id, next);
+}
 function parseBlend(value, allowPassThrough = false) {
   if (value === void 0) return void 0;
   if (value === "pass-through" && allowPassThrough) return value;
@@ -7305,7 +7362,8 @@ var ImageEditorController = class {
     this.renderer.layerSources = {
       surfaceOf: (layer) => this.surfaceOf(layer),
       sourceIsOpaque: () => this.sourceIsOpaque(),
-      version: () => this.sourceVersion()
+      version: () => this.sourceVersion(),
+      globalLight: () => this.state.globalLight
     };
     this.state = {
       sourceUrl: typeof options.image === "string" ? options.image : null,
@@ -7459,6 +7517,7 @@ var ImageEditorController = class {
       }
     };
     if (s.legacyOutputBlur !== void 0) entry.legacyOutputBlur = s.legacyOutputBlur;
+    if (s.globalLight) entry.globalLight = { ...s.globalLight };
     return entry;
   }
   restoreHistoryEntry(entry) {
@@ -7471,6 +7530,8 @@ var ImageEditorController = class {
     s.outputOpacity = entry.outputOpacity;
     if (entry.legacyOutputBlur !== void 0) s.legacyOutputBlur = entry.legacyOutputBlur;
     else delete s.legacyOutputBlur;
+    if (entry.globalLight) s.globalLight = { ...entry.globalLight };
+    else delete s.globalLight;
     s.selection = entry.selection;
     if (this.imageElement !== entry.source.element && !this.samplePixelsOverride) this.samplePixels = null;
     this.imageElement = entry.source.element;
@@ -7692,7 +7753,7 @@ var ImageEditorController = class {
   }
   compositorSources() {
     const { width, height } = this.naturalSize;
-    return { width, height, surfaceOf: (l) => this.surfaceOf(l), version: this.sourceVersion() };
+    return { width, height, surfaceOf: (l) => this.surfaceOf(l), version: this.sourceVersion(), globalLight: this.state.globalLight };
   }
   sourceIds = /* @__PURE__ */ new WeakMap();
   nextSourceId = 1;
@@ -8104,6 +8165,55 @@ var ImageEditorController = class {
     this.commitLayers(next);
     return findLayer(next, id).layer.filters ?? [];
   }
+  // --- Layer effects ---
+  /** A layer's effects (an empty, enabled list when it has none). */
+  getLayerEffects(id) {
+    return layerEffectsOf(requireLayer(this.state.layers, id).layer);
+  }
+  /**
+   * Adds an effect of `kind` with Photoshop's defaults and `params` applied (one undo step), at
+   * `index` in the layer's effect list (default the end). Returns the new effect and the effects.
+   */
+  addLayerEffect(id, kind, params = {}, index) {
+    const res = addLayerEffect(this.state.layers, id, kind, params, index);
+    this.commitLayers(res.layers);
+    return { effect: res.effect, effects: this.getLayerEffects(id) };
+  }
+  /** Changes one effect (one undo step, or none with `commitToHistory = false` during a drag). Returns the effects. */
+  updateLayerEffect(id, effectId, changes, commitToHistory = true) {
+    this.commitLayers(updateLayerEffect(this.state.layers, id, effectId, changes), void 0, commitToHistory);
+    return this.getLayerEffects(id);
+  }
+  /** Removes one effect (one undo step). Returns the remaining effects. */
+  removeLayerEffect(id, effectId) {
+    this.commitLayers(removeLayerEffect(this.state.layers, id, effectId));
+    return this.getLayerEffects(id);
+  }
+  /** Turns a layer's effects on or off as a whole and, when given, sets Scale Effects (one undo step). */
+  setLayerEffectsEnabled(id, enabled, scale, commitToHistory = true) {
+    this.commitLayers(setLayerEffectsEnabled(this.state.layers, id, enabled, scale), void 0, commitToHistory);
+    return this.getLayerEffects(id);
+  }
+  /** Replaces a layer's effects (one undo step; `null` removes them). Returns the effects. */
+  setLayerEffects(id, effects, commitToHistory = true) {
+    this.commitLayers(setLayerEffects(this.state.layers, id, effects), void 0, commitToHistory);
+    return this.getLayerEffects(id);
+  }
+  /** The light effects with "use global light" follow. */
+  getGlobalLight() {
+    return { ...this.state.globalLight ?? DEFAULT_GLOBAL_LIGHT };
+  }
+  /** Sets the global light (one undo step). `angle` -360..360°, `altitude` 0..90°. Returns it. */
+  setGlobalLight(light, commitToHistory = true) {
+    const next = { ...this.getGlobalLight(), ...light };
+    if (!(Number.isFinite(next.angle) && next.angle >= -360 && next.angle <= 360)) throw new LayerOperationError(`angle must be from -360 to 360 degrees, got ${next.angle}.`);
+    if (!(Number.isFinite(next.altitude) && next.altitude >= 0 && next.altitude <= 90)) throw new LayerOperationError(`altitude must be from 0 to 90 degrees, got ${next.altitude}.`);
+    if (commitToHistory) this.recordHistory();
+    if (next.angle === DEFAULT_GLOBAL_LIGHT.angle && next.altitude === DEFAULT_GLOBAL_LIGHT.altitude) delete this.state.globalLight;
+    else this.state.globalLight = next;
+    this.notify();
+    return this.getGlobalLight();
+  }
   /** Composites `layers` (in isolation) over `rect` into a surface, loading depth maps first. */
   async compositeToSurface(layers, rect) {
     const { width, height } = this.naturalSize;
@@ -8133,7 +8243,8 @@ var ImageEditorController = class {
   }
   /**
    * Merge Down: composites a layer onto the pixel layer directly below it (which keeps its name,
-   * opacity and blend; masks, fill and filters are baked), as one undo step. Returns the merged id.
+   * opacity and blend; masks, fill, filters and both layers' effects are baked), as one undo step.
+   * Returns the merged id.
    */
   async mergeDown(id) {
     const loc = requireLayer(this.state.layers, id);
@@ -8145,7 +8256,9 @@ var ImageEditorController = class {
     if (!upper.visible) throw new LayerOperationError(`Layer "${upper.name || id}" is hidden; show it or delete it instead of merging.`);
     requireUnlocked(upper, "all", "merge it");
     requireUnlocked(lower, "pixels", "merge into it");
-    const rect = unionRect(this.paintBounds(lower), upper.type === "adjustment" ? null : this.paintBounds(upper)) ?? { x: 0, y: 0, width: 1, height: 1 };
+    let rect = unionRect(this.paintBounds(lower), upper.type === "adjustment" ? null : this.paintBounds(upper)) ?? { x: 0, y: 0, width: 1, height: 1 };
+    const reach = Math.max(effectsMargin(lower.effects), upper.type === "adjustment" ? 0 : effectsMargin(upper.effects));
+    if (reach) rect = { x: rect.x - reach, y: rect.y - reach, width: rect.width + 2 * reach, height: rect.height + 2 * reach };
     const base = { ...lower, blend: "normal", opacity: 1 };
     delete base.clipped;
     const surface = await this.compositeToSurface([base, upper], rect);
@@ -8154,6 +8267,7 @@ var ImageEditorController = class {
     delete merged.fillOpacity;
     delete merged.filters;
     delete merged.source;
+    delete merged.effects;
     let next = mapLayer(this.state.layers, id, () => null);
     next = mapLayer(next, lower.id, () => merged);
     this.commitLayers(next, () => {
@@ -9534,6 +9648,9 @@ var ImageEditorController = class {
       if (typeof data.legacyOutputBlur === "number" && data.legacyOutputBlur >= 0) s.legacyOutputBlur = data.legacyOutputBlur;
       else delete s.legacyOutputBlur;
       s.activeLayerId = data.activeLayerId && findLayer(s.layers, data.activeLayerId) ? data.activeLayerId : null;
+      const light = data.globalLight;
+      if (light && Number.isFinite(light.angle) && Number.isFinite(light.altitude)) s.globalLight = { angle: light.angle, altitude: Math.min(90, Math.max(0, light.altitude)) };
+      else delete s.globalLight;
       if (!this.imageElement && typeof data.width === "number" && typeof data.height === "number" && data.width > 0 && data.height > 0) {
         s.imageDimensions = { width: data.width, height: data.height };
       }
@@ -9547,6 +9664,7 @@ var ImageEditorController = class {
       s.crop = data.crop ? { ...data.crop } : null;
       s.transform = { ...data.transform };
       s.activeLayerId = null;
+      delete s.globalLight;
     }
     s.activeTarget = "pixels";
     this.viewKey = [];
@@ -9556,7 +9674,7 @@ var ImageEditorController = class {
   serializeState() {
     const { width, height } = this.naturalSize;
     const view = legacyView(this.stack(), width, height, null);
-    if (view.exact) {
+    if (view.exact && !this.state.globalLight) {
       return {
         // States without adjustment layers keep schema 1, so they round-trip unchanged.
         version: view.adjustments.layers?.length ? 2 : 1,
@@ -9583,6 +9701,7 @@ var ImageEditorController = class {
       opacity: this.state.outputOpacity
     };
     if (this.state.legacyOutputBlur !== void 0) out.legacyOutputBlur = this.state.legacyOutputBlur;
+    if (this.state.globalLight) out.globalLight = { ...this.state.globalLight };
     return out;
   }
 };
@@ -10820,6 +10939,7 @@ function describeLayer(layer, activeId, boundsOf) {
     clipped: Boolean(layer.clipped),
     locks: layer.locks ? { ...layer.locks } : {},
     mask: maskSummary(layer.mask),
+    effects: layer.effects ? { enabled: layer.effects.enabled, scale: layer.effects.scale ?? 1, items: layer.effects.items.map((e) => ({ id: e.id, kind: e.kind, enabled: e.enabled })) } : null,
     active: layer.id === activeId
   };
   switch (layer.type) {
@@ -10879,7 +10999,7 @@ function createImageLayerTools(controller) {
   const listLayers = {
     name: "list_layers",
     title: "List image layers",
-    description: "Returns the layer stack bottom to top as a tree: id, type (pixel, adjustment, group, annotation), name, document bounds (pixel layers), visible, opacity, fillOpacity, blend, clipped, locks, a mask summary, filters (pixel layers), kind and params (adjustment layers), children (groups) and which layer is active. Also returns the active layer id and target (pixels or mask) and the canvas size.",
+    description: "Returns the layer stack bottom to top as a tree: id, type (pixel, adjustment, group, annotation), name, document bounds (pixel layers), visible, opacity, fillOpacity, blend, clipped, locks, a mask summary, an effects summary (master switch, scale, effect ids and kinds; details from list_layer_effects), filters (pixel layers), kind and params (adjustment layers), children (groups) and which layer is active. Also returns the active layer id and target (pixels or mask) and the canvas size.",
     inputSchema: { type: "object", properties: {}, additionalProperties: false },
     annotations: { title: "List image layers", ...READ2 },
     handler: () => {
@@ -11315,9 +11435,338 @@ function createImageLayerTools(controller) {
   ];
 }
 
-// src/image-editor/paint-tools.ts
+// src/image-editor/effect-tools.ts
+var READ3 = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
 var WRITE3 = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
+var WRITE_IDEMPOTENT3 = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false };
 var DESTRUCTIVE2 = { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false };
+var LAYER_ID3 = { type: "string", description: "Layer id from list_layers (a pixel, annotation or group layer)." };
+var EFFECT_ID = { type: "string", description: "Effect id from list_layer_effects or add_layer_effect." };
+var BLEND_IDS = BLEND_MODES.map((m) => m.id);
+var DEFS = {
+  color: { type: "string", pattern: "^#?([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$", description: "Colour as #rrggbb." },
+  contour: {
+    type: "object",
+    description: "A transfer curve over the effect coverage: points { input, output } from 0 to 1 (at least 2), sorted by input. Linear is [{0,0},{1,1}].",
+    properties: {
+      name: { type: "string", description: 'Display name (e.g. "Cone", "Gaussian").' },
+      points: {
+        type: "array",
+        minItems: 2,
+        description: "Curve points.",
+        items: {
+          type: "object",
+          properties: {
+            input: { type: "number", minimum: 0, maximum: 1, description: "Coverage in (0..1)." },
+            output: { type: "number", minimum: 0, maximum: 1, description: "Coverage out (0..1)." },
+            corner: { type: "boolean", description: "Sharp corner instead of a smooth point (default false)." }
+          },
+          required: ["input", "output"],
+          additionalProperties: false
+        }
+      }
+    },
+    required: ["name", "points"],
+    additionalProperties: false
+  },
+  gradient: {
+    type: "object",
+    description: "A gradient: colour stops, optional opacity stops and its layout.",
+    properties: {
+      stops: {
+        type: "array",
+        minItems: 1,
+        description: "Colour stops { position 0..1, color #rrggbb }.",
+        items: {
+          type: "object",
+          properties: { position: { type: "number", minimum: 0, maximum: 1, description: "0..1 along the gradient." }, color: { $ref: "#/$defs/color" } },
+          required: ["position", "color"],
+          additionalProperties: false
+        }
+      },
+      opacityStops: {
+        type: "array",
+        description: "Opacity stops { position 0..1, opacity 0..1 } (default opaque).",
+        items: {
+          type: "object",
+          properties: {
+            position: { type: "number", minimum: 0, maximum: 1, description: "0..1 along the gradient." },
+            opacity: { type: "number", minimum: 0, maximum: 1, description: "0..1." }
+          },
+          required: ["position", "opacity"],
+          additionalProperties: false
+        }
+      },
+      style: { type: "string", enum: ["linear", "radial", "angle", "reflected", "diamond"], description: "Geometry." },
+      angle: { type: "number", minimum: -360, maximum: 360, description: "Degrees, 90 = bottom to top." },
+      scale: { type: "number", minimum: 0.1, maximum: 1.5, description: "1 = 100 %." },
+      reverse: { type: "boolean", description: "Swap the ends." },
+      align: { type: "boolean", description: "Lay out over the layer bounds (true) or the canvas." },
+      offset: {
+        type: "object",
+        description: "Centre offset as fractions of the bounds.",
+        properties: { x: { type: "number", minimum: -1, maximum: 1, description: "Fraction of the width." }, y: { type: "number", minimum: -1, maximum: 1, description: "Fraction of the height." } },
+        required: ["x", "y"],
+        additionalProperties: false
+      }
+    },
+    required: ["stops", "style", "angle", "scale", "reverse", "align", "offset"],
+    additionalProperties: false
+  },
+  phase: {
+    type: "object",
+    description: "Pattern origin offset in px.",
+    properties: { x: { type: "number", description: "px." }, y: { type: "number", description: "px." } },
+    required: ["x", "y"],
+    additionalProperties: false
+  },
+  fill: {
+    description: "What a stroke or glow paints with. Glows take color or gradient only.",
+    anyOf: [
+      {
+        type: "object",
+        properties: { type: { const: "color", description: "Solid colour." }, color: { $ref: "#/$defs/color" } },
+        required: ["type", "color"],
+        additionalProperties: false
+      },
+      {
+        type: "object",
+        properties: { type: { const: "gradient", description: "Gradient." }, gradient: { $ref: "#/$defs/gradient" } },
+        required: ["type", "gradient"],
+        additionalProperties: false
+      },
+      {
+        type: "object",
+        properties: {
+          type: { const: "pattern", description: "Pattern (strokes only)." },
+          patternId: { type: "string", description: "Pattern id from list_layer_effects.patterns." },
+          name: { type: "string", description: "Display name." },
+          scale: { type: "number", minimum: 0.01, maximum: 10, description: "1 = 100 %." },
+          angle: { type: "number", minimum: -360, maximum: 360, description: "Rotation in degrees (default 0)." },
+          link: { type: "boolean", description: "Tile from the layer (default true) or the canvas origin." },
+          phase: { $ref: "#/$defs/phase" }
+        },
+        required: ["type", "patternId", "scale"],
+        additionalProperties: false
+      }
+    ]
+  }
+};
+var nullable = (schema, description) => ({ anyOf: [schema, { type: "null" }], description });
+function settingsSchema(forUpdate) {
+  const opt = (schema, description) => forUpdate ? nullable(schema, `${description} null removes it.`) : { ...schema, description };
+  return {
+    type: "object",
+    description: forUpdate ? "Settings to change (only these; nested objects are replaced whole). Which settings a kind takes: see add_layer_effect." : "Settings to change from Photoshop's defaults (all optional). Unknown settings for the kind are refused with the list of its settings.",
+    properties: {
+      enabled: { type: "boolean", description: "All kinds: false keeps the effect but hides it (default true)." },
+      blend: { type: "string", enum: BLEND_IDS, description: "All but bevel-emboss: blend mode (shadows multiply, glows screen, others normal)." },
+      opacity: { type: "number", minimum: 0, maximum: 1, description: "All but bevel-emboss: 0..1 (shadows / glows 0.75, satin 0.5, others 1)." },
+      color: { $ref: "#/$defs/color", description: "drop-shadow, inner-shadow, satin, color-overlay: #rrggbb." },
+      angle: { type: "number", minimum: -360, maximum: 360, description: "Shadows, satin, bevel-emboss: light direction in degrees, counter-clockwise from 3 o'clock (default 120; satin 19)." },
+      useGlobalLight: { type: "boolean", description: "Shadows, bevel-emboss: follow the document global light instead of angle (default true)." },
+      distance: { type: "number", minimum: 0, maximum: 3e4, description: "Shadows, satin: offset in px (default 5; satin 11)." },
+      spread: { type: "number", minimum: 0, maximum: 1, description: "drop-shadow, outer-glow: 0..1 of the size made solid (default 0)." },
+      choke: { type: "number", minimum: 0, maximum: 1, description: "inner-shadow, inner-glow: 0..1 of the size made solid (default 0)." },
+      size: { type: "number", minimum: 0, maximum: 250, description: "Shadows, glows, satin, bevel-emboss: blur / size in px (default 5; satin 14); stroke: width in px (default 3)." },
+      contour: opt({ $ref: "#/$defs/contour" }, "Shadows, glows, satin: coverage contour (default linear)."),
+      antiAlias: { type: "boolean", description: "Shadows, glows, satin: smooth the contour (default false; satin true)." },
+      noise: { type: "number", minimum: 0, maximum: 1, description: "Shadows, glows: speckle 0..1 (default 0)." },
+      knocksOut: { type: "boolean", description: "drop-shadow: the layer hides the shadow beneath its see-through fill (default true)." },
+      fill: { $ref: "#/$defs/fill", description: "outer-glow, inner-glow (color or gradient), stroke (color, gradient or pattern)." },
+      technique: { type: "string", enum: ["softer", "precise", "smooth", "chisel-hard", "chisel-soft"], description: "Glows: softer | precise (default softer); bevel-emboss: smooth | chisel-hard | chisel-soft (default smooth)." },
+      range: { type: "number", minimum: 0.01, maximum: 1, description: "Glows: the part of the glow the contour spans (default 0.5)." },
+      jitter: { type: "number", minimum: 0, maximum: 1, description: "Glows: gradient jitter 0..1 (stored, not rendered; default 0)." },
+      source: { type: "string", enum: ["edge", "center"], description: "inner-glow: glow from the edge (default) or the centre." },
+      style: { type: "string", enum: ["inner-bevel", "outer-bevel", "emboss", "pillow-emboss", "stroke-emboss"], description: "bevel-emboss: style (default inner-bevel)." },
+      depth: { type: "number", minimum: 0, maximum: 10, description: "bevel-emboss: depth, 1 = 100 % (default 1)." },
+      direction: { type: "string", enum: ["up", "down"], description: "bevel-emboss: raised (up, default) or sunk (down)." },
+      soften: { type: "number", minimum: 0, maximum: 16, description: "bevel-emboss: blur of the height in px (default 0)." },
+      altitude: { type: "number", minimum: 0, maximum: 90, description: "bevel-emboss: light altitude in degrees (default 30)." },
+      glossContour: opt({ $ref: "#/$defs/contour" }, "bevel-emboss: gloss contour over the shading (default linear)."),
+      highlightColor: { $ref: "#/$defs/color", description: "bevel-emboss: highlight colour (default #ffffff)." },
+      highlightBlend: { type: "string", enum: BLEND_IDS, description: "bevel-emboss: highlight mode (default screen)." },
+      highlightOpacity: { type: "number", minimum: 0, maximum: 1, description: "bevel-emboss: highlight opacity (default 0.75)." },
+      shadowColor: { $ref: "#/$defs/color", description: "bevel-emboss: shadow colour (default #000000)." },
+      shadowBlend: { type: "string", enum: BLEND_IDS, description: "bevel-emboss: shadow mode (default multiply)." },
+      shadowOpacity: { type: "number", minimum: 0, maximum: 1, description: "bevel-emboss: shadow opacity (default 0.75)." },
+      contourElement: opt(
+        {
+          type: "object",
+          properties: {
+            contour: { $ref: "#/$defs/contour" },
+            range: { type: "number", minimum: 0, maximum: 1, description: "Stored range (default 0.5)." },
+            antiAlias: { type: "boolean", description: "Smooth the contour." }
+          },
+          required: ["contour", "range", "antiAlias"],
+          additionalProperties: false
+        },
+        "bevel-emboss: the Contour element, shaping the bevel's height profile (default off)."
+      ),
+      texture: opt(
+        {
+          type: "object",
+          properties: {
+            patternId: { type: "string", description: "Pattern id from list_layer_effects.patterns." },
+            name: { type: "string", description: "Display name." },
+            scale: { type: "number", minimum: 0.01, maximum: 10, description: "1 = 100 %." },
+            depth: { type: "number", minimum: -10, maximum: 10, description: "1 = +100 %; negative carves the pattern in." },
+            invert: { type: "boolean", description: "Invert the pattern." },
+            link: { type: "boolean", description: "Tile from the layer (default true)." },
+            phase: { $ref: "#/$defs/phase" }
+          },
+          required: ["patternId", "scale", "depth", "invert"],
+          additionalProperties: false
+        },
+        "bevel-emboss: the Texture element, a pattern's luminance as extra height (default off)."
+      ),
+      invert: { type: "boolean", description: "satin: invert (default true)." },
+      gradient: { $ref: "#/$defs/gradient", description: "gradient-overlay: the gradient (default black to white, 90\xB0)." },
+      dither: { type: "boolean", description: "gradient-overlay: dither (stored; default false)." },
+      patternId: { type: "string", description: "pattern-overlay: pattern id from list_layer_effects.patterns (default checker)." },
+      name: { type: "string", description: "pattern-overlay: pattern display name." },
+      scale: { type: "number", minimum: 0.01, maximum: 10, description: "pattern-overlay: 1 = 100 % (default 1)." },
+      link: { type: "boolean", description: "pattern-overlay: tile from the layer (default true) or the canvas origin." },
+      phase: { $ref: "#/$defs/phase", description: "pattern-overlay: origin offset in px (default 0, 0)." },
+      position: { type: "string", enum: ["outside", "inside", "center"], description: "stroke: where the stroke sits on the edge (default outside)." }
+    },
+    additionalProperties: false
+  };
+}
+function patternList() {
+  return builtinPatternIds().map((id) => {
+    const p = builtinPattern(id);
+    return { id, name: p.name, width: p.width, height: p.height, builtin: true };
+  });
+}
+function describeLayerEffects(effects) {
+  return {
+    enabled: effects.enabled,
+    scale: effects.scale ?? 1,
+    margin: effectsMargin(effects),
+    fromPsd: Boolean(effects.psd),
+    effects: effects.items.map((e) => ({ ...JSON.parse(JSON.stringify(e)), label: layerEffectLabel(e.kind) }))
+  };
+}
+function createImageEffectTools(controller) {
+  const layerArg = (id) => {
+    if (typeof id !== "string" || !id) throw new LayerOperationError("layerId is required (a layer id from list_layers).");
+    requireLayer(controller.getLayers(), id);
+    return id;
+  };
+  const result = (layerId, extra = {}) => ({ layerId, ...extra, ...describeLayerEffects(controller.getLayerEffects(layerId)) });
+  const list = {
+    name: "list_layer_effects",
+    title: "List layer effects",
+    description: "Returns a layer's effects: the master switch (enabled), Scale Effects (scale, 1 = 100 %), margin (px the effects reach beyond the shape), whether they came from a PSD, and every effect with its id, kind, label and all settings. Also returns the document global light and the pattern ids pattern effects can use.",
+    inputSchema: { type: "object", properties: { layerId: LAYER_ID3 }, required: ["layerId"], additionalProperties: false },
+    annotations: { title: "List layer effects", ...READ3 },
+    handler: ({ layerId }) => result(layerArg(layerId), { globalLight: controller.getGlobalLight(), patterns: patternList(), kinds: [...LAYER_EFFECT_KINDS] })
+  };
+  const add = {
+    name: "add_layer_effect",
+    title: "Add a layer effect",
+    description: "Adds a live effect to a pixel, annotation or group layer with Photoshop's defaults, changed by settings: drop-shadow, inner-shadow, outer-glow, inner-glow, bevel-emboss, satin, color-overlay, gradient-overlay, pattern-overlay or stroke. Several of one kind are allowed (the first listed is on top). One undo step. Returns the new effect's id and the layer's effects.",
+    inputSchema: {
+      type: "object",
+      $defs: DEFS,
+      properties: {
+        layerId: LAYER_ID3,
+        kind: { type: "string", enum: [...LAYER_EFFECT_KINDS], description: "Effect kind." },
+        settings: settingsSchema(false),
+        index: { type: "integer", minimum: 0, description: "Position in the layer's effect list (default the end)." }
+      },
+      required: ["layerId", "kind"],
+      additionalProperties: false
+    },
+    annotations: { title: "Add a layer effect", ...WRITE3 },
+    handler: ({ layerId, kind, settings, index }) => {
+      const id = layerArg(layerId);
+      if (!isLayerEffectKind(kind)) throw new LayerOperationError(`kind must be one of ${LAYER_EFFECT_KINDS.join(", ")}.`);
+      const { effect } = controller.addLayerEffect(id, kind, settings ?? {}, index);
+      return result(id, { effectId: effect.id });
+    }
+  };
+  const update = {
+    name: "update_layer_effect",
+    title: "Change a layer effect",
+    description: "Changes settings of one effect (only the given ones; fill, gradient, contour and texture objects are replaced whole, null removes an optional contour or texture). The kind cannot change. Validates everything before changing anything. One undo step. Returns the layer's effects.",
+    inputSchema: {
+      type: "object",
+      $defs: DEFS,
+      properties: { layerId: LAYER_ID3, effectId: EFFECT_ID, settings: settingsSchema(true) },
+      required: ["layerId", "effectId", "settings"],
+      additionalProperties: false
+    },
+    annotations: { title: "Change a layer effect", ...WRITE_IDEMPOTENT3 },
+    handler: ({ layerId, effectId, settings }) => {
+      const id = layerArg(layerId);
+      const changes = settings ?? {};
+      if (!Object.keys(changes).length) throw new LayerOperationError("Give at least one setting to change.");
+      controller.updateLayerEffect(id, effectId, changes);
+      return result(id);
+    }
+  };
+  const remove = {
+    name: "remove_layer_effect",
+    title: "Remove a layer effect",
+    description: "Removes one effect from a layer (to hide it but keep its settings, set enabled false with update_layer_effect instead). One undo step. Returns the layer's remaining effects.",
+    inputSchema: { type: "object", properties: { layerId: LAYER_ID3, effectId: EFFECT_ID }, required: ["layerId", "effectId"], additionalProperties: false },
+    annotations: { title: "Remove a layer effect", ...DESTRUCTIVE2 },
+    handler: ({ layerId, effectId }) => {
+      const id = layerArg(layerId);
+      controller.removeLayerEffect(id, effectId);
+      return result(id);
+    }
+  };
+  const setEnabled = {
+    name: "set_layer_effects_enabled",
+    title: "Switch layer effects on or off",
+    description: "Turns all of a layer's effects on or off at once (the master switch; each effect keeps its own enabled flag) and optionally sets Scale Effects, which multiplies every size, distance and pattern scale. One undo step. Returns the layer's effects.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        layerId: LAYER_ID3,
+        enabled: { type: "boolean", description: "true renders the enabled effects; false hides them all." },
+        scale: { type: "number", minimum: 0.01, maximum: 10, description: "Scale Effects, 1 = 100 % (unchanged when left out)." }
+      },
+      required: ["layerId", "enabled"],
+      additionalProperties: false
+    },
+    annotations: { title: "Switch layer effects on or off", ...WRITE_IDEMPOTENT3 },
+    handler: ({ layerId, enabled, scale }) => {
+      const id = layerArg(layerId);
+      controller.setLayerEffectsEnabled(id, enabled, scale);
+      return result(id);
+    }
+  };
+  const light = {
+    name: "set_global_light",
+    title: "Set the global light",
+    description: "Sets the document global light that shadows and bevels with useGlobalLight follow (Photoshop default: angle 120\xB0, altitude 30\xB0). One undo step. Returns the light.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        angle: { type: "number", minimum: -360, maximum: 360, description: "Degrees, counter-clockwise from 3 o'clock: where the light comes from (unchanged when left out)." },
+        altitude: { type: "number", minimum: 0, maximum: 90, description: "Degrees above the canvas, for bevels (unchanged when left out)." }
+      },
+      additionalProperties: false
+    },
+    annotations: { title: "Set the global light", ...WRITE_IDEMPOTENT3 },
+    handler: ({ angle, altitude }) => {
+      if (angle === void 0 && altitude === void 0) throw new LayerOperationError("Give angle, altitude or both.");
+      const next = {};
+      if (angle !== void 0) next.angle = angle;
+      if (altitude !== void 0) next.altitude = altitude;
+      return { globalLight: controller.setGlobalLight(next) };
+    }
+  };
+  return [list, add, update, remove, setEnabled, light];
+}
+
+// src/image-editor/paint-tools.ts
+var WRITE4 = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
+var DESTRUCTIVE3 = { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false };
 var TARGET = {
   layerId: { type: "string", description: "Layer to paint (default the active layer; see list_layers)." },
   channel: { type: "string", enum: ["pixels", "mask"], description: "pixels (default for a pixel layer) or the layer's mask: black hides, white reveals." }
@@ -11375,7 +11824,7 @@ function createImagePaintTools(controller) {
       required: ["points"],
       additionalProperties: false
     },
-    annotations: { title: "Paint a brush stroke", ...WRITE3 },
+    annotations: { title: "Paint a brush stroke", ...WRITE4 },
     handler: (args) => controller.paintStroke({
       tool: args.tool,
       points: args.points,
@@ -11399,7 +11848,7 @@ function createImagePaintTools(controller) {
       },
       additionalProperties: false
     },
-    annotations: { title: "Fill pixels", ...WRITE3 },
+    annotations: { title: "Fill pixels", ...WRITE4 },
     handler: (args) => controller.fillPixels({
       color: args.color,
       opacity: args.opacity,
@@ -11421,15 +11870,15 @@ function createImagePaintTools(controller) {
       },
       additionalProperties: false
     },
-    annotations: { title: "Clear pixels", ...DESTRUCTIVE2 },
+    annotations: { title: "Clear pixels", ...DESTRUCTIVE3 },
     handler: (args) => controller.clearPixels({ opacity: args.opacity, useSelection: args.useSelection, ...readTarget(args) })
   };
   return [paintStroke, fill, clear];
 }
 
 // src/image-editor/psd-tools.ts
-var READ3 = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
-var DESTRUCTIVE3 = { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false };
+var READ4 = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+var DESTRUCTIVE4 = { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false };
 var DATA = {
   type: "string",
   minLength: 1,
@@ -11449,7 +11898,7 @@ function createImagePsdTools(controller) {
     title: "Inspect a PSD",
     description: "Reads a PSD / PSB without opening it: size, bit depth, colour mode, resolution, and every layer (bottom first, a group before its children) with its PSD kind, the layer type it would become and its status (mapped, approximated or dropped, with notes), plus the import warnings. Changes nothing. Call before import_psd to see what would be lost.",
     inputSchema: { type: "object", properties: { data: DATA }, required: ["data"], additionalProperties: false },
-    annotations: { title: "Inspect a PSD", ...READ3 },
+    annotations: { title: "Inspect a PSD", ...READ4 },
     handler: ({ data }) => {
       const res = importPsd(psdBytesFromBase64(data), { skipPixels: true });
       return {
@@ -11467,7 +11916,7 @@ function createImagePsdTools(controller) {
     title: "Open a PSD as the document",
     description: "Opens a PSD / PSB as the document, replacing the current layers, crop and rotation (one undo step; undo brings the previous document back). Pixel, group and adjustment layers, masks, blend modes, opacity, fill, clipping, visibility and locks map directly; type, smart-object, fill and shape layers come in as their pixels; unsupported adjustments are left out. Returns the new layer tree with ids, the size and the warnings (each names the affected layers).",
     inputSchema: { type: "object", properties: { data: DATA }, required: ["data"], additionalProperties: false },
-    annotations: { title: "Open a PSD as the document", ...DESTRUCTIVE3 },
+    annotations: { title: "Open a PSD as the document", ...DESTRUCTIVE4 },
     handler: ({ data }) => {
       const res = controller.loadPsd(psdBytesFromBase64(data));
       const s = controller.getState();
@@ -11486,7 +11935,7 @@ function createImagePsdTools(controller) {
     title: "Export the document as a PSD",
     description: "Writes the document as an 8-bit RGB PSD (a PSB above 30000 px) with real layers, groups, adjustment layers and masks, in the source frame (crop and rotation are not applied). Layer filters and depth masks are baked, annotation layers are rasterized (in a browser; elsewhere left out), and the merged image is the editor's composite. Changes nothing. Returns the file as base64, its size in bytes, whether it is a PSB, and warnings for everything that was changed or left out.",
     inputSchema: { type: "object", properties: {}, additionalProperties: false },
-    annotations: { title: "Export the document as a PSD", ...READ3 },
+    annotations: { title: "Export the document as a PSD", ...READ4 },
     handler: async () => {
       const res = await controller.toPsd();
       return {
@@ -11740,6 +12189,7 @@ function createImageEditorToolProvider(controller, options = {}) {
       ...createImageSelectionTools(controller),
       ...createImageEditTools(controller),
       ...createImageLayerTools(controller),
+      ...createImageEffectTools(controller),
       ...createImagePaintTools(controller),
       ...createPigmentTools(),
       ...createImagePsdTools(controller)
@@ -12427,6 +12877,7 @@ export {
   XYZ_D50_TO_SRGB,
   ZlibError,
   activeAdjustmentLayers,
+  addLayerEffect,
   addLayerFilter,
   addToHistogram,
   adjustmentKindLabel,
@@ -12490,6 +12941,7 @@ export {
   createImageCaptureSurface,
   createImageEditTools,
   createImageEditorToolProvider,
+  createImageEffectTools,
   createImageLayerTools,
   createImagePaintTools,
   createImagePsdTools,
@@ -12516,7 +12968,9 @@ export {
   depthMaskAlpha,
   depthRasterMask,
   describeLayer,
+  describeLayerEffects,
   describeSelection,
+  deserializeEffects,
   deserializeLayer,
   deserializeLayers,
   deserializeSelection,
@@ -12601,6 +13055,7 @@ export {
   isSpatialFilter,
   kelvinToTemperature,
   layerBadge,
+  layerEffectsOf,
   layerLabel,
   layerMaskCoverage,
   layerMaskFromSelection,
@@ -12686,6 +13141,7 @@ export {
   removeAlpha,
   removeCurvePoint,
   removeLayer,
+  removeLayerEffect,
   removeLayerFilter,
   renderLayeredBase,
   requireLayer,
@@ -12708,11 +13164,14 @@ export {
   selectionToCoverage,
   selectionToPixels,
   selectionValueAt,
+  serializeEffects,
   serializeLayer,
   serializeLayers,
   serializeLayersExternal,
   serializeSelection,
   setControlPath,
+  setLayerEffects,
+  setLayerEffectsEnabled,
   setLayerMask,
   setLayerProperties,
   setLum,
@@ -12746,6 +13205,7 @@ export {
   uniformTile,
   unionRect,
   unprojectCanvasPoint,
+  updateLayerEffect,
   updateLayerFilter,
   updateLayerMaskProps,
   uvToXy,