@pixerate/editor 0.175.0 → 0.176.0

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

@@ -61,6 +61,7 @@ export { transformSurface, warpSurface, reduceSurface, compositeSurfaceOver, tra
 export { rectToQuad, homographyFromPoints, applyHomography, invertHomography, homographyFromAffine, boxQuad, identityWarpMesh, evalWarpMesh, warpPresetMesh, warpMeshEditPoints, warpMeshGridCurves, dragWarpMeshPoint, pullWarpMesh, warpMeshParamAt, resizeWarpMesh, WARP_STYLE_LABELS, } from '../geom/index.cjs';
 export * from './layers/transform-ui.cjs';
 export * from './effects.cjs';
+export { checkEffectAnimation, checkEffectTime, effectLayerTiming, hasLayersBelow, withBackgroundOpacity, type EffectLayerTiming } from './effect-layers.cjs';
 export * from './provider-effect-tools.cjs';
 export * from './playback.cjs';
 export * from './editorDocument.cjs';

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

@@ -61,6 +61,7 @@ export { transformSurface, warpSurface, reduceSurface, compositeSurfaceOver, tra
 export { rectToQuad, homographyFromPoints, applyHomography, invertHomography, homographyFromAffine, boxQuad, identityWarpMesh, evalWarpMesh, warpPresetMesh, warpMeshEditPoints, warpMeshGridCurves, dragWarpMeshPoint, pullWarpMesh, warpMeshParamAt, resizeWarpMesh, WARP_STYLE_LABELS, } from '../geom/index.js';
 export * from './layers/transform-ui.js';
 export * from './effects.js';
+export { checkEffectAnimation, checkEffectTime, effectLayerTiming, hasLayersBelow, withBackgroundOpacity, type EffectLayerTiming } from './effect-layers.js';
 export * from './provider-effect-tools.js';
 export * from './playback.js';
 export * from './editorDocument.js';

package/dist/image-editor/index.js

@@ -30,6 +30,7 @@ import {
   LUMA_709,
   LayerCompositor,
   LayerOperationError,
+  MAX_EFFECT_ANIMATION_MS,
   MAX_KELVIN,
   MIN_KELVIN,
   MIRED_PER_TEMPERATURE_UNIT,
@@ -369,7 +370,7 @@ import {
   writePsd,
   xyToTempTint,
   xyToUv
-} from "../chunk-BDIM6NVW.js";
+} from "../chunk-Y46OMERN.js";
 import {
   parseCssColor
 } from "../chunk-3CI7FRMK.js";
@@ -3298,6 +3299,35 @@ function refineSelection(pixels, mask, params = {}) {
   return createSelectionMask(mask.width, mask.height, out);
 }
 
+// src/image-editor/effect-layers.ts
+function hasLayersBelow(layers, id) {
+  const all = flattenLayers(layers);
+  const at = all.findIndex((l) => l.id === id);
+  return at > 0 && all.slice(0, at).some((l) => l.type !== "group" && l.type !== "adjustment" && l.type !== "annotation");
+}
+function withBackgroundOpacity(d, values, below) {
+  const out = { ...values };
+  if (below && d.backgroundOpacity && out[d.backgroundOpacity] === void 0) out[d.backgroundOpacity] = 0;
+  return out;
+}
+function checkEffectTime(time) {
+  if (time === void 0) return 0;
+  if (!(typeof time === "number" && Number.isFinite(time) && time >= 0)) throw new LayerOperationError("time must be a number of ms from 0.");
+  return time;
+}
+function checkEffectAnimation(animate) {
+  const duration = animate?.duration;
+  if (!(typeof duration === "number" && Number.isFinite(duration) && duration > 0 && duration <= MAX_EFFECT_ANIMATION_MS)) {
+    throw new LayerOperationError(`animate.duration must be more than 0 and at most ${MAX_EFFECT_ANIMATION_MS} ms.`);
+  }
+  return { duration: Math.round(duration) };
+}
+function effectLayerTiming(g, d) {
+  if (!d?.duration) return null;
+  const time = g.time ?? 0;
+  return { mode: g.animate ? "animate" : "still", time, range: Math.max(d.duration, time), duration: g.animate?.duration ?? d.duration, loops: d.loop };
+}
+
 // src/image-editor/effects.ts
 var IMAGE_EFFECT_PLACES = {
   /** A smart filter: the effect changes the pixels below it. */
@@ -4900,28 +4930,35 @@ var ImageEditorController = class {
   /**
    * Adds an effect layer: a pixel layer drawn by a provider generator, overlay or title effect at
    * the document's size and bit depth (at `time` ms, default 0), placed like `addPixelLayer`. One
-   * undo step. Masks, blend and opacity apply as to any layer. Returns its id.
+   * undo step. Masks, blend and opacity apply as to any layer. An effect with a background of its
+   * own (`backgroundOpacity`) starts with it transparent when there are layers below it, unless
+   * `values` set it. `animate` makes it play when the document is output as an animation. Returns
+   * its id.
    */
   async addEffectLayer(effect, options = {}) {
     const d = await this.describeEffect(effect, "layer");
-    const values = resolveEffectValues(d, options.values);
-    const { width, height } = this.naturalSize;
-    const pixels = await this.effectsEngine.renderLayer(d.id, values, { width, height, depth: this.bitDepth, time: options.time });
     const blend = parseBlend(options.blend);
     if (options.opacity !== void 0 && !(options.opacity >= 0 && options.opacity <= 1)) throw new LayerOperationError("opacity must be from 0 to 1.");
+    const time = checkEffectTime(options.time);
+    const animate = options.animate === void 0 ? void 0 : checkEffectAnimation(options.animate);
     const ids = new Set(flattenLayers(this.state.layers).map((l) => l.id));
+    const id = options.id && !ids.has(options.id) ? options.id : newLayerId();
+    const placed = placeLayer(this.state.layers, { type: "pixel", id, name: "", visible: true, opacity: 1, blend: "normal", surface: emptySurface(4), offset: { x: 0, y: 0 } }, this.newLayerPlacement(options));
+    const values = resolveEffectValues(d, withBackgroundOpacity(d, options.values, hasLayersBelow(placed, id)));
+    const { width, height } = this.naturalSize;
+    const pixels = await this.effectsEngine.renderLayer(d.id, values, { width, height, depth: this.bitDepth, time });
     const layer = {
       type: "pixel",
-      id: options.id && !ids.has(options.id) ? options.id : newLayerId(),
+      id,
       name: options.name?.trim() || d.name,
       visible: true,
       opacity: options.opacity ?? 1,
       blend: blend ?? "normal",
       surface: effectPixelsToSurface(pixels, this.bitDepth),
       offset: { x: 0, y: 0 },
-      generator: { effect: d.id, provider: this.effects.require().id, name: d.name, values, ...options.time ? { time: options.time } : {} }
+      generator: { effect: d.id, provider: this.effects.require().id, name: d.name, values, ...time ? { time } : {}, ...animate ? { animate } : {} }
     };
-    const next = placeLayer(this.state.layers, layer, this.newLayerPlacement(options));
+    const next = mapLayer(placed, id, () => layer);
     this.commitLayers(next, () => {
       this.state.activeLayerId = layer.id;
       this.state.activeTarget = "pixels";
@@ -4929,9 +4966,12 @@ var ImageEditorController = class {
     return layer.id;
   }
   /**
-   * Draws an effect layer again with new `values` (merged over its own; `null` resets a control)
-   * or `time`, at the document's size and depth, replacing its pixels (painting on it is lost).
-   * One undo step (none with `commitToHistory` false). Returns its effect settings.
+   * Draws an effect layer again, replacing its pixels (painting on it is lost): with new `values`
+   * (merged over its own; `null` resets a control), at another `time`, or as another `effect`
+   * (a generator, overlay or title: its defaults plus `values`, with its background transparent
+   * when there are layers below; the layer keeps a name of its own, else takes the new effect's).
+   * `animate` sets how it plays in an animation (null: a still frame). One undo step (none with
+   * `commitToHistory` false). Returns its effect settings.
    */
   async updateEffectLayer(layerId, changes, commitToHistory = true) {
     const found = findLayer(this.state.layers, layerId);
@@ -4939,8 +4979,9 @@ var ImageEditorController = class {
     if (!layer || layer.type !== "pixel" || !layer.generator) throw new LayerOperationError(`"${layerId}" is not an effect layer; add one with add_effect_layer.`);
     requireUnlocked(layer, "pixels", "draw its effect again");
     const g = layer.generator;
-    const d = await this.describeEffect(g.effect);
-    const base = { ...g.values };
+    const swap = changes.effect !== void 0 && changes.effect !== g.effect;
+    const d = swap ? await this.describeEffect(changes.effect, "layer") : await this.describeEffect(g.effect);
+    const base = swap ? { ...d.defaults, ...withBackgroundOpacity(d, {}, hasLayersBelow(this.state.layers, layerId)) } : { ...g.values };
     const given = {};
     for (const [k, v] of Object.entries(changes.values ?? {})) {
       if (v !== null) given[k] = v;
@@ -4948,15 +4989,47 @@ var ImageEditorController = class {
       else throw new LayerOperationError(`"${k}" is not a control of "${d.id}"; its controls are ${Object.keys(d.controls.properties).join(", ")}.`);
     }
     const values = { ...base, ...resolveEffectValues({ ...d, defaults: base }, given) };
-    const time = changes.time ?? g.time ?? 0;
+    const time = changes.time === void 0 ? g.time ?? 0 : checkEffectTime(changes.time);
+    const animate = changes.animate === void 0 ? g.animate : changes.animate === null ? void 0 : checkEffectAnimation(changes.animate);
     const { width, height } = this.naturalSize;
     const pixels = await this.effectsEngine.renderLayer(d.id, values, { width, height, depth: this.bitDepth, time });
-    const generator = { ...g, values, provider: this.effects.require().id, ...time ? { time } : {} };
-    if (!time) delete generator.time;
-    const next = mapLayer(this.state.layers, layerId, (l) => ({ ...l, surface: effectPixelsToSurface(pixels, this.bitDepth), offset: { x: 0, y: 0 }, generator }));
+    const generator = { effect: d.id, provider: this.effects.require().id, name: d.name, values, ...time ? { time } : {}, ...animate ? { animate } : {} };
+    const renamed = swap && (!layer.name || layer.name === (g.name ?? g.effect));
+    const next = mapLayer(this.state.layers, layerId, (l) => ({ ...l, ...renamed ? { name: d.name } : {}, surface: effectPixelsToSurface(pixels, this.bitDepth), offset: { x: 0, y: 0 }, generator }));
     this.commitLayers(next, void 0, commitToHistory);
     return generator;
   }
+  /**
+   * The document as an animation: its visible effect layers that animate (`generator.animate`)
+   * and how long it runs, the longest of theirs (ms). Null when none animates.
+   */
+  getAnimation() {
+    const layers = flattenLayers(this.state.layers).filter((l) => l.type === "pixel" && l.visible && !!l.generator?.animate);
+    if (!layers.length) return null;
+    return { duration: Math.max(...layers.map((l) => l.generator.animate.duration)), layerIds: layers.map((l) => l.id) };
+  }
+  /**
+   * Renders the document `time` ms into its animation (see `getAnimation`), like `renderExport`:
+   * each animating effect layer drawn at its own `time` plus `time` (an effect that loops keeps
+   * looping past its duration), every other layer as it is. Nothing in the document changes.
+   */
+  async renderAnimationFrame(time, options) {
+    if (!(Number.isFinite(time) && time >= 0)) throw new LayerOperationError("time must be a number of ms from 0.");
+    const source = this.drawSource();
+    if (!source) return this.renderer.createCanvas(1, 1);
+    this.syncViews();
+    const { width, height } = this.naturalSize;
+    const surfaces = /* @__PURE__ */ new Map();
+    for (const l of flattenLayers(this.state.layers)) {
+      if (l.type !== "pixel" || !l.visible || !l.generator?.animate) continue;
+      const g = l.generator;
+      const pixels = await this.effectsEngine.renderLayer(g.effect, g.values, { width, height, depth: this.bitDepth, time: (g.time ?? 0) + time });
+      surfaces.set(l.id, effectPixelsToSurface(pixels, this.bitDepth));
+    }
+    let layers = this.state.layers;
+    for (const [id, surface] of surfaces) layers = mapLayer(layers, id, (l) => ({ ...l, surface, offset: { x: 0, y: 0 } }));
+    return this.renderer.renderExport(source, { ...this.state, layers }, options);
+  }
   /** Turns an effect layer into a plain pixel layer keeping its pixels (one undo step). */
   rasterizeEffectLayer(layerId) {
     const found = findLayer(this.state.layers, layerId);
@@ -14631,32 +14704,39 @@ async function addLayerOfKind(controller, id, init) {
   throw new Error(`Unknown layer kind "${id}"`);
 }
 function layerPanels(layer, options = {}) {
-  const effects = options.effects ? [{ id: "provider-effects", title: "Effects" }] : [];
   if (!layer) {
     return [
       { id: "canvas-size", title: "Composition Size" },
-      { id: "selection", title: "Selection" },
-      ...effects
+      { id: "selection", title: "Selection" }
     ];
   }
-  const panels = [
-    { id: "properties", title: "Layer Properties" },
-    ...effects
-  ];
+  const panels = [{ id: "properties", title: "Layer Properties" }];
+  const styles = (id, title) => {
+    if (!options.effects) panels.push({ id, title });
+  };
+  const effects = () => {
+    if (options.effects) panels.push({ id: "provider-effects", title: "Effects" });
+  };
   if (layer.type === "pixel") {
+    effects();
     panels.push({ id: "paint", title: "Brush Options" });
-    panels.push({ id: "effects", title: "Layer Effects" });
+    styles("effects", "Layer Effects");
   } else if (layer.type === "adjustment") {
     panels.push({ id: "adjustment", title: adjustmentKindLabel(layer.kind) });
   } else if (layer.type === "type") {
     panels.push({ id: "type", title: "Typography" });
-    panels.push({ id: "effects", title: "Layer Effects" });
+    effects();
+    styles("effects", "Layer Effects");
   } else if (layer.type === "shape") {
     panels.push({ id: "shape", title: "Shape Options" });
-    panels.push({ id: "effects", title: "Layer Effects" });
+    effects();
+    styles("effects", "Layer Effects");
   } else if (layer.type === "smart") {
-    panels.push({ id: "smart-filters", title: "Smart Filters" });
-    panels.push({ id: "effects", title: "Layer Effects" });
+    effects();
+    styles("smart-filters", "Smart Filters");
+    styles("effects", "Layer Effects");
+  } else if (layer.type === "group") {
+    effects();
   }
   if (layer.mask) {
     panels.push({ id: "mask", title: "Mask Options" });
@@ -15518,10 +15598,17 @@ var FreeTransformTool = class {
 };
 
 // src/image-editor/provider-effect-tools.ts
+var ANIMATE_SCHEMA = {
+  type: "object",
+  properties: { duration: { type: "number", exclusiveMinimum: 0, maximum: MAX_EFFECT_ANIMATION_MS, description: `How long it plays in ms (at most ${MAX_EFFECT_ANIMATION_MS}).` } },
+  required: ["duration"],
+  additionalProperties: false,
+  description: "Play when the document is output as an animation, for duration ms from time (the longest animating layer sets the animation's length)."
+};
 function imageLayerAppliedEffects(layer) {
   const out = [];
   const ref = (r) => ({ effect: r.effect, ...r.name ? { name: r.name } : {}, ...r.provider ? { provider: r.provider } : {} });
-  if (layer.type === "pixel" && layer.generator) out.push({ id: "generator", ...ref(layer.generator), role: "effect layer", enabled: true, values: layer.generator.values, ...layer.generator.time ? { time: layer.generator.time } : {} });
+  if (layer.type === "pixel" && layer.generator) out.push({ id: "generator", ...ref(layer.generator), role: "effect layer", enabled: true, values: layer.generator.values, ...layer.generator.time ? { time: layer.generator.time } : {}, ...layer.generator.animate ? { animate: layer.generator.animate } : {} });
   if (layer.type === "smart")
     (layer.smartFilters?.filters ?? []).forEach((f, index) => {
       if (f.kind === "effect") out.push({ id: f.id, ...ref(f), role: "smart filter", enabled: f.enabled && layer.smartFilters.enabled, opacity: f.opacity, blend: f.blend, values: f.values, index });
@@ -15590,13 +15677,14 @@ function createImageEffectsToolProvider(controller, options = {}) {
       {
         name: "add_effect_layer",
         title: "Add an effect layer",
-        description: `Adds a layer drawn by a provider generator, overlay or title effect (search_effects with use generator, overlay or title) at the document's size and bit depth, above the active layer unless placed. Masks, blend mode, opacity and layer styles apply as to any layer; transparent effects show the layers beneath. update_effect with effect "generator" draws it again with new values; remove_effect "generator" keeps its pixels as a plain layer. One undo step. Returns the new layer id and its effect.`,
+        description: `Adds a layer drawn by a provider generator, overlay or title effect (search_effects with use generator, overlay or title) at the document's size and bit depth, above the active layer unless placed. Masks, blend mode, opacity and layer styles apply as to any layer; transparent effects show the layers beneath, and an effect with its own background (describe_effect backgroundOpacity) starts with it transparent when there are layers below, unless values set it. animate makes it play when the document is output as an animation. set_effect_layer changes its effect, frame or animation; update_effect with effect "generator" draws it again with new values; remove_effect "generator" keeps its pixels as a plain layer. One undo step. Returns the new layer id and its effect.`,
         inputSchema: {
           type: "object",
           properties: {
             effect: ctx.effectIdSchema(["generator", "overlay", "title"]),
             values: ctx.valuesSchema("Control values over the effect's defaults"),
-            time: { type: "number", minimum: 0, description: "Which moment of an animated effect to draw, in ms (default 0)." },
+            time: { type: "number", minimum: 0, description: "Which moment of an animated effect to draw, in ms (default 0); where its animation starts." },
+            animate: ANIMATE_SCHEMA,
             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)." },
             belowId: { type: "string", minLength: 1, description: "Put it directly below this layer." },
@@ -15609,9 +15697,34 @@ function createImageEffectsToolProvider(controller, options = {}) {
         annotations: { title: "Add an effect layer", ...ctx.annotations.write },
         handler: async (args) => {
           ctx.requireProvider();
-          const id = await controller.addEffectLayer(args.effect, { values: plainValues(args.values), time: args.time, name: args.name, aboveId: args.aboveId, belowId: args.belowId, opacity: args.opacity, blend: args.blend });
+          const id = await controller.addEffectLayer(args.effect, { values: plainValues(args.values), time: args.time, animate: args.animate, name: args.name, aboveId: args.aboveId, belowId: args.belowId, opacity: args.opacity, blend: args.blend });
           return { layerId: id, effects: imageLayerAppliedEffects(layerOf(id)) };
         }
+      },
+      {
+        name: "set_effect_layer",
+        title: "Change an effect layer",
+        description: 'Changes an effect layer (list_applied_effects shows its effect as "generator"): effect swaps in another generator, overlay or title effect (its defaults plus values, the background transparent when there are layers below); time picks the still frame of an animated effect; animate { duration } makes it play when the document is output as an animation, null makes it a still frame again. Redraws its pixels (painting on it is lost). One undo step. Returns its effects.',
+        inputSchema: {
+          type: "object",
+          properties: {
+            layerId: { type: "string", minLength: 1, description: "The effect layer's id (list_layers)." },
+            effect: ctx.effectIdSchema(["generator", "overlay", "title"]),
+            values: ctx.valuesSchema("Control values: over the new effect's defaults when effect is given, else over the layer's own (null resets one)"),
+            time: { type: "number", minimum: 0, description: "The moment drawn as the still frame, in ms; where the animation starts." },
+            animate: { anyOf: [ANIMATE_SCHEMA, { type: "null" }], description: "Play for this long in an animation, or null for a still frame." }
+          },
+          required: ["layerId"],
+          additionalProperties: false
+        },
+        annotations: { title: "Change an effect layer", ...ctx.annotations.write },
+        handler: async (args) => {
+          if (args.effect !== void 0) ctx.requireProvider();
+          const layer = layerOf(args.layerId);
+          if (layer.type !== "pixel" || !layer.generator) throw new Error(`"${args.layerId}" is not an effect layer; its effects are in list_applied_effects, and add_effect_layer adds one.`);
+          await controller.updateEffectLayer(args.layerId, { effect: args.effect, values: args.values, time: args.time, animate: args.animate });
+          return { layerId: args.layerId, effects: imageLayerAppliedEffects(layerOf(args.layerId)) };
+        }
       }
     ]
   }), options.playbackSurface);
@@ -15752,6 +15865,7 @@ export {
   MAX_BATCH,
   MAX_BRUSH_SIZE,
   MAX_CANVAS_BACKING_SIDE,
+  MAX_EFFECT_ANIMATION_MS,
   MAX_EFFECT_REACH,
   MAX_KELVIN,
   MAX_TILT_ACCEL,
@@ -15972,6 +16086,8 @@ export {
   canvasToImagePoint,
   caretAt,
   changedTiles,
+  checkEffectAnimation,
+  checkEffectTime,
   checkImageEffectPlace,
   clampControlValue,
   clampCropToImage,
@@ -16099,6 +16215,7 @@ export {
   edgeWidth,
   effectColorHex,
   effectControlChange,
+  effectLayerTiming,
   effectPixelsToSurface,
   effectReach,
   effectiveProof,
@@ -16158,6 +16275,7 @@ export {
   guidedFilterColor,
   handlePaintShortcut,
   hasActiveEffects,
+  hasLayersBelow,
   hasResampledLegacyMask,
   hasSurface,
   hasWarp,
@@ -16606,6 +16724,7 @@ export {
   wetSupport,
   whiteBalanceFromSample,
   whiteBalanceMatrix,
+  withBackgroundOpacity,
   withFilterMaskSurface,
   withImagePlayback,
   withNewIds,

package/dist/image-editor/layers/model.d.cts

@@ -68,8 +68,22 @@ export interface ImageEffectGenerator {
     name?: string;
     /** Control values (over the effect's defaults). */
     values: Record<string, EffectValue>;
-    /** The moment of the effect drawn (ms, default 0). */
+    /**
+     * The moment of the effect drawn (ms, default 0): the still frame, and where an animation
+     * starts.
+     */
     time?: number;
+    /**
+     * The layer plays when the document is output as an animation (`renderAnimationFrame`),
+     * for `duration` ms from `time`. Absent: the layer is the still frame at `time`.
+     */
+    animate?: ImageEffectAnimation;
+}
+/** The longest an effect layer animates (ms): a minute. */
+export declare const MAX_EFFECT_ANIMATION_MS = 60000;
+/** How an animated effect layer plays: for `duration` ms (more than 0, at most `MAX_EFFECT_ANIMATION_MS`). */
+export interface ImageEffectAnimation {
+    duration: number;
 }
 export interface PixelLayer extends LayerBase, Omit<RasterPixelLayer, keyof RasterLayerBase> {
     /**

package/dist/image-editor/layers/model.d.ts

@@ -68,8 +68,22 @@ export interface ImageEffectGenerator {
     name?: string;
     /** Control values (over the effect's defaults). */
     values: Record<string, EffectValue>;
-    /** The moment of the effect drawn (ms, default 0). */
+    /**
+     * The moment of the effect drawn (ms, default 0): the still frame, and where an animation
+     * starts.
+     */
     time?: number;
+    /**
+     * The layer plays when the document is output as an animation (`renderAnimationFrame`),
+     * for `duration` ms from `time`. Absent: the layer is the still frame at `time`.
+     */
+    animate?: ImageEffectAnimation;
+}
+/** The longest an effect layer animates (ms): a minute. */
+export declare const MAX_EFFECT_ANIMATION_MS = 60000;
+/** How an animated effect layer plays: for `duration` ms (more than 0, at most `MAX_EFFECT_ANIMATION_MS`). */
+export interface ImageEffectAnimation {
+    duration: number;
 }
 export interface PixelLayer extends LayerBase, Omit<RasterPixelLayer, keyof RasterLayerBase> {
     /**

package/dist/image-editor/layers/panel.d.cts

@@ -110,8 +110,12 @@ export interface LayerPanelDescriptor {
 }
 export interface LayerPanelsOptions {
     /**
-     * The editor has an effects provider (`controller.effectsProvider`): adds the `provider-effects`
-     * panel, to add effect layers and to apply effects to the layer or change an effect layer's own.
+     * The editor has an effects provider (`controller.effectsProvider`): one `provider-effects`
+     * panel ("Effects") holds everything that changes how a layer looks beyond its own settings:
+     * an effect layer's effect (change it, its frame or animation, its controls), and the layer's
+     * styles (drop shadow, stroke…) and filters. It takes the place of the `effects` (Layer
+     * Effects) and `smart-filters` panels. New effect layers are added from the layers panel
+     * (`newLayerOptions`).
      */
     effects?: boolean;
 }

package/dist/image-editor/layers/panel.d.ts

@@ -110,8 +110,12 @@ export interface LayerPanelDescriptor {
 }
 export interface LayerPanelsOptions {
     /**
-     * The editor has an effects provider (`controller.effectsProvider`): adds the `provider-effects`
-     * panel, to add effect layers and to apply effects to the layer or change an effect layer's own.
+     * The editor has an effects provider (`controller.effectsProvider`): one `provider-effects`
+     * panel ("Effects") holds everything that changes how a layer looks beyond its own settings:
+     * an effect layer's effect (change it, its frame or animation, its controls), and the layer's
+     * styles (drop shadow, stroke…) and filters. It takes the place of the `effects` (Layer
+     * Effects) and `smart-filters` panels. New effect layers are added from the layers panel
+     * (`newLayerOptions`).
      */
     effects?: boolean;
 }

package/dist/image-editor/provider-effect-tools.d.cts

@@ -2,7 +2,8 @@
  * Agent tools for provider effects in the image editor: the shared effect tools
  * (`search_effects`, `describe_effect`, `list_applied_effects`, `apply_effect`, `update_effect`,
  * `remove_effect`) on layers, where filter effects become smart filters, plus `add_effect_layer`
- * for generator, overlay and title effects. (Drop shadows, strokes and the other layer styles are
+ * for generator, overlay and title effects and `set_effect_layer` to change one (its effect, still
+ * frame or animation). (Drop shadows, strokes and the other layer styles are
  * `set_layer_effect`, a different thing.)
  */
 import { type AppliedEffectInfo } from '../effects/tools.cjs';

package/dist/image-editor/provider-effect-tools.d.ts

@@ -2,7 +2,8 @@
  * Agent tools for provider effects in the image editor: the shared effect tools
  * (`search_effects`, `describe_effect`, `list_applied_effects`, `apply_effect`, `update_effect`,
  * `remove_effect`) on layers, where filter effects become smart filters, plus `add_effect_layer`
- * for generator, overlay and title effects. (Drop shadows, strokes and the other layer styles are
+ * for generator, overlay and title effects and `set_effect_layer` to change one (its effect, still
+ * frame or animation). (Drop shadows, strokes and the other layer styles are
  * `set_layer_effect`, a different thing.)
  */
 import { type AppliedEffectInfo } from '../effects/tools.js';

package/dist/paint-editor/index.cjs

@@ -7,7 +7,7 @@ var _chunkZ64NRDEHcjs = require('../chunk-Z64NRDEH.cjs');
 
 
 
-var _chunkOVYQAYGHcjs = require('../chunk-OVYQAYGH.cjs');
+var _chunkUHMSMUHKcjs = require('../chunk-UHMSMUHK.cjs');
 require('../chunk-A2IS7EHE.cjs');
 
 
@@ -1653,11 +1653,11 @@ function header(state, options) {
   return out;
 }
 function serializePaintDocument(state, options = {}) {
-  const { layers, assets } = _chunkOVYQAYGHcjs.serializeLayers.call(void 0, state.layers);
+  const { layers, assets } = _chunkUHMSMUHKcjs.serializeLayers.call(void 0, state.layers);
   return { ...header(state, options), layers, assets };
 }
 async function serializePaintDocumentExternal(state, store, options = {}) {
-  const { layers, assets } = await _chunkOVYQAYGHcjs.serializeLayersExternal.call(void 0, state.layers, store);
+  const { layers, assets } = await _chunkUHMSMUHKcjs.serializeLayersExternal.call(void 0, state.layers, store);
   return { ...header(state, options), layers, assets };
 }
 function paintLayersOnly(layers, problems) {
@@ -1694,7 +1694,7 @@ function deserializePaintDocument(raw) {
   const canvas = normalizeCanvas({ width: r.width, height: r.height, dpi: _nullishCoalesce(r.dpi, () => ( void 0)) });
   const paper = _chunkYQ5C5BVKcjs.normalizePaper.call(void 0, _nullishCoalesce(r.paper, () => ( {})));
   const assets = r.assets && typeof r.assets === "object" ? r.assets : {};
-  const layers = paintLayersOnly(_chunkOVYQAYGHcjs.deserializeLayers.call(void 0, r.layers, { assets, problems }), problems);
+  const layers = paintLayersOnly(_chunkUHMSMUHKcjs.deserializeLayers.call(void 0, r.layers, { assets, problems }), problems);
   const wanted = typeof r.activeLayerId === "string" ? r.activeLayerId : null;
   const activeLayerId = wanted && _chunkHGTDMKNEcjs.findLayer.call(void 0, layers, wanted) ? wanted : _nullishCoalesce(_optionalChain([_chunkHGTDMKNEcjs.flattenLayers.call(void 0, layers), 'access', _70 => _70.filter, 'call', _71 => _71((l) => l.type === "pixel"), 'access', _72 => _72.pop, 'call', _73 => _73(), 'optionalAccess', _74 => _74.id]), () => ( null));
   const wetEvents = Array.isArray(r.wetEvents) ? r.wetEvents.filter((e) => e && typeof e === "object" && Number.isInteger(e.clock) && typeof e.kind === "string") : [];
@@ -1710,7 +1710,7 @@ async function deserializePaintDocumentAsync(raw, store) {
   if (!raw || typeof raw !== "object") throw new Error("Not a paint document: expected a JSON object.");
   const r = raw;
   const problems = [];
-  const assets = await _chunkOVYQAYGHcjs.resolveExternalAssets.call(void 0, _nullishCoalesce(r.assets, () => ( {})), store, problems);
+  const assets = await _chunkUHMSMUHKcjs.resolveExternalAssets.call(void 0, _nullishCoalesce(r.assets, () => ( {})), store, problems);
   const loaded = deserializePaintDocument({ ...r, assets });
   return { ...loaded, problems: [...problems, ...loaded.problems] };
 }
@@ -5409,7 +5409,7 @@ var PaintEditorController = (_class10 = class _PaintEditorController {
       return next.type === "group" ? { ...next, children: toStandard(next.children) } : next;
     });
     const layers = toStandard(dried);
-    const result = _chunkOVYQAYGHcjs.exportPsd.call(void 0, { width, height, layers: [paperLayer, ...layers], merged, resolution: dpi });
+    const result = _chunkUHMSMUHKcjs.exportPsd.call(void 0, { width, height, layers: [paperLayer, ...layers], merged, resolution: dpi });
     for (const [mode, names] of changed) {
       const label = _nullishCoalesce(_optionalChain([_chunkCWM3CUUXcjs.BLEND_MODES, 'access', _271 => _271.find, 'call', _272 => _272((m) => m.id === mode), 'optionalAccess', _273 => _273.label]), () => ( mode));
       const std = _nullishCoalesce(_optionalChain([_chunkCWM3CUUXcjs.BLEND_MODES, 'access', _274 => _274.find, 'call', _275 => _275((m) => m.id === _chunkCWM3CUUXcjs.standardBlendMode.call(void 0, mode)), 'optionalAccess', _276 => _276.label]), () => ( _chunkCWM3CUUXcjs.standardBlendMode.call(void 0, mode)));

package/dist/paint-editor/index.js

@@ -7,7 +7,7 @@ import {
   resolveExternalAssets,
   serializeLayers,
   serializeLayersExternal
-} from "../chunk-BDIM6NVW.js";
+} from "../chunk-Y46OMERN.js";
 import "../chunk-3CI7FRMK.js";
 import {
   EffectRendererPool

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixerate/editor",
-  "version": "0.175.0",
+  "version": "0.176.0",
   "description": "UI-agnostic rich text and media editing core library",
   "author": "Pixerate",
   "license": "MIT",

package/skills/pixerate-image-editor/SKILL.md

@@ -390,7 +390,8 @@ in the source frame at the document's bit depth, colour mode and profile. Read
 | `apply_effect` | Run a provider filter effect on a layer as a smart filter (`target`, `effect`, `values`, `index`, `enabled`, `opacity`); a pixel, shape or type layer becomes a smart object in the same undo step (`converted`). Returns the filter id. |
 | `update_effect` | Change an effect smart filter (`values` merged, `null` resets; `enabled`, `opacity`, `index`) or redraw an effect layer (`effect: "generator"`, values only). |
 | `remove_effect` | Remove an effect smart filter, or (`generator`) keep an effect layer's pixels as a plain layer. |
-| `add_effect_layer` | Add a layer drawn by a generator, overlay or title effect at the document's size and bit depth (`values`, `time`, `name`, `aboveId` / `belowId`, `opacity`, `blend`). Returns the layer id. |
+| `add_effect_layer` | Add a layer drawn by a generator, overlay or title effect at the document's size and bit depth (`values`, `time`, `animate`, `name`, `aboveId` / `belowId`, `opacity`, `blend`). An effect with its own background (`backgroundOpacity` in `describe_effect`) starts with it transparent when there are layers below. Returns the layer id. |
+| `set_effect_layer` | Change an effect layer: swap its `effect` (its defaults plus `values`), pick the still frame (`time`, ms), or make it play in an animation (`animate: { duration }`; `null` for a still frame). The longest animating layer sets the animation's length. |
 | `apply_selection_as_mask` | Mask a layer with the current selection: pass `layerId` to mask an existing layer, or `kind` (plus optional `params`) to create a new masked layer in one step. `density` 0..1 and `feather` px soften the mask non-destructively. Returns `layerId`, kind, mask info and the selection summary. |
 
 ### Save and open