@pixerate/editor 0.175.0 → 0.176.0

package/dist/effects/fake.d.cts

@@ -4,7 +4,7 @@
  *
  * Effects (ids prefixed `fake.`):
  * - `invert` (filter), `tint` (filter)
- * - `gradient` (generator, loops)
+ * - `gradient` (generator, loops; its background opacity is `opacity`)
  * - `bar` (title / overlay: a lower-third bar that slides in, transparent)
  * - `crossfade` (transition)
  * - `fade-in` (motion, vector only)

package/dist/effects/fake.d.ts

@@ -4,7 +4,7 @@
  *
  * Effects (ids prefixed `fake.`):
  * - `invert` (filter), `tint` (filter)
- * - `gradient` (generator, loops)
+ * - `gradient` (generator, loops; its background opacity is `opacity`)
  * - `bar` (title / overlay: a lower-third bar that slides in, transparent)
  * - `crossfade` (transition)
  * - `fade-in` (motion, vector only)

package/dist/effects/index.cjs

@@ -61,6 +61,7 @@ function checkSummary(e, issues) {
   if (typeof e.transparent !== "boolean") at("transparent is not a boolean");
   if (typeof e.loop !== "boolean") at("loop is not a boolean");
   if (e.duration !== void 0 && !(e.duration > 0)) at("duration must be a positive number of ms when present");
+  if (e.backgroundOpacity !== void 0 && (typeof e.backgroundOpacity !== "string" || !e.backgroundOpacity)) at("backgroundOpacity must name a control when present");
 }
 function checkDescription(id, d, issues) {
   const at = (message) => issues.push({ effectId: id, message });
@@ -73,6 +74,11 @@ function checkDescription(id, d, issues) {
     if (!(name in (_nullishCoalesce(d.defaults, () => ( {}))))) at(`control "${name}" has no default`);
   }
   for (const name of Object.keys(_nullishCoalesce(d.defaults, () => ( {})))) if (!(name in (_nullishCoalesce(_optionalChain([c, 'optionalAccess', _3 => _3.properties]), () => ( {}))))) at(`default "${name}" is not a control`);
+  if (d.backgroundOpacity !== void 0) {
+    const control = _optionalChain([c, 'optionalAccess', _4 => _4.properties, 'optionalAccess', _5 => _5[d.backgroundOpacity]]);
+    if (!control) at(`backgroundOpacity "${d.backgroundOpacity}" is not a control`);
+    else if (control.type !== "number" || control.minimum !== 0 || control.maximum !== 1) at(`backgroundOpacity "${d.backgroundOpacity}" must be a number control from 0 to 1`);
+  }
   for (const e of _chunkA3A5TI6Rcjs.effectValueErrors.call(void 0, d, d.defaults)) at(`default ${e.path}: ${e.message}`);
   for (const p of _nullishCoalesce(d.presets, () => ( []))) for (const e of _chunkA3A5TI6Rcjs.effectValueErrors.call(void 0, d, p.values)) at(`preset "${p.name}" ${e.path}: ${e.message}`);
   for (const input2 of _nullishCoalesce(d.inputs, () => ( []))) {
@@ -118,11 +124,11 @@ async function checkEffectProvider(provider, options = {}) {
   if (!provider.id) top("provider has no id");
   const caps = provider.capabilities;
   for (const k of ["supportsWorker", "supportsFloat", "supportsMask", "supportsHostImages", "supportsVector"]) {
-    if (typeof _optionalChain([caps, 'optionalAccess', _4 => _4[k]]) !== "boolean") top(`capabilities.${k} is not a boolean`);
+    if (typeof _optionalChain([caps, 'optionalAccess', _6 => _6[k]]) !== "boolean") top(`capabilities.${k} is not a boolean`);
   }
-  if (_optionalChain([caps, 'optionalAccess', _5 => _5.supportsAuthoring]) !== void 0 && typeof caps.supportsAuthoring !== "boolean") top("capabilities.supportsAuthoring is not a boolean");
-  if (_optionalChain([caps, 'optionalAccess', _6 => _6.supportsVector]) && typeof provider.applyVectorEffect !== "function") top("supportsVector is set but applyVectorEffect is missing");
-  if (_optionalChain([caps, 'optionalAccess', _7 => _7.supportsAuthoring]) && typeof provider.openAuthoring !== "function") top("supportsAuthoring is set but openAuthoring is missing");
+  if (_optionalChain([caps, 'optionalAccess', _7 => _7.supportsAuthoring]) !== void 0 && typeof caps.supportsAuthoring !== "boolean") top("capabilities.supportsAuthoring is not a boolean");
+  if (_optionalChain([caps, 'optionalAccess', _8 => _8.supportsVector]) && typeof provider.applyVectorEffect !== "function") top("supportsVector is set but applyVectorEffect is missing");
+  if (_optionalChain([caps, 'optionalAccess', _9 => _9.supportsAuthoring]) && typeof provider.openAuthoring !== "function") top("supportsAuthoring is set but openAuthoring is missing");
   const list = await provider.list();
   const ids = /* @__PURE__ */ new Set();
   for (const e of list) {
@@ -132,7 +138,7 @@ async function checkEffectProvider(provider, options = {}) {
   }
   const all = await provider.search("");
   if (all.length !== list.length) top(`search("") returned ${all.length} effects, list() ${list.length}`);
-  const firstUse = _optionalChain([list, 'access', _8 => _8[0], 'optionalAccess', _9 => _9.uses, 'access', _10 => _10[0]]);
+  const firstUse = _optionalChain([list, 'access', _10 => _10[0], 'optionalAccess', _11 => _11.uses, 'access', _12 => _12[0]]);
   if (firstUse) {
     const filtered = await provider.search("", { use: firstUse });
     if (filtered.some((e) => !e.uses.includes(firstUse))) top(`search("", { use: "${firstUse}" }) returned effects without that use`);
@@ -164,7 +170,7 @@ async function checkEffectProvider(provider, options = {}) {
       if (bad) issues.push({ effectId: id, message: `applyVectorEffect with an unknown control ${bad}` });
     }
   }
-  if (_optionalChain([caps, 'optionalAccess', _11 => _11.supportsAuthoring]) && options.authoring !== false && typeof provider.openAuthoring === "function") {
+  if (_optionalChain([caps, 'optionalAccess', _13 => _13.supportsAuthoring]) && options.authoring !== false && typeof provider.openAuthoring === "function") {
     const targetEffect = (await Promise.all((_nullishCoalesce(options.ids, () => ( [...ids]))).map((id) => provider.describe(id)))).find(
       (d) => d.kind !== "motion" && d.kind !== "vector"
     );
@@ -278,6 +284,7 @@ var DESCRIPTIONS = [
     transparent: false,
     loop: true,
     duration: 4e3,
+    backgroundOpacity: "opacity",
     controls: {
       type: "object",
       additionalProperties: false,
@@ -285,10 +292,11 @@ var DESCRIPTIONS = [
         from: colour("Start colour as #rrggbb. Default #1e3a8a."),
         to: colour("End colour as #rrggbb. Default #f472b6."),
         angle: { type: "number", minimum: 0, maximum: 360, description: "Direction in degrees, 0 = left to right, 90 = top to bottom. Default 90." },
-        spin: { type: "number", minimum: -360, maximum: 360, description: "Turn per loop (4 s) in degrees. Default 0." }
+        spin: { type: "number", minimum: -360, maximum: 360, description: "Turn per loop (4 s) in degrees. Default 0." },
+        opacity: { type: "number", minimum: 0, maximum: 1, description: "Background opacity 0\u20131: 0 is fully transparent. Default 1." }
       }
     },
-    defaults: { from: "#1e3a8a", to: "#f472b6", angle: 90, spin: 0 },
+    defaults: { from: "#1e3a8a", to: "#f472b6", angle: 90, spin: 0, opacity: 1 },
     presets: [{ name: "Sunset", values: { from: "#f97316", to: "#7c3aed" } }],
     inputs: []
   },
@@ -391,7 +399,7 @@ var hexToRgb = (hex) => [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16));
 var smooth = (t) => t * t * (3 - 2 * t);
 var clamp01 = (v) => v < 0 ? 0 : v > 1 ? 1 : v;
 function input(request, name, id, width, height) {
-  const src = _optionalChain([request, 'access', _12 => _12.inputs, 'optionalAccess', _13 => _13[name]]);
+  const src = _optionalChain([request, 'access', _14 => _14.inputs, 'optionalAccess', _15 => _15[name]]);
   if (!src) throw new (0, _chunkA3A5TI6Rcjs.EffectUnsupportedError)(`Effect "${id}" needs an input named "${name}".`, id);
   if (!_chunkA3A5TI6Rcjs.isEffectPixels.call(void 0, src)) throw new (0, _chunkA3A5TI6Rcjs.EffectUnsupportedError)(`The fake provider only takes EffectPixels inputs ("${name}").`, id);
   if (src.width !== width || src.height !== height) {
@@ -434,7 +442,7 @@ function renderPixels(d, v, request, width, height) {
         for (let x = 0; x < width; x++, i += 4) {
           const t = clamp01(((x + 0.5 - width / 2) * dx + (y + 0.5 - height / 2) * dy) / (2 * half) + 0.5);
           for (let c = 0; c < 3; c++) o[i + c] = a[c] + (b[c] - a[c]) * t;
-          o[i + 3] = 255;
+          o[i + 3] = 255 * clamp01(v.opacity);
         }
       }
       break;
@@ -538,11 +546,11 @@ function createFakeEffectProvider(options = {}) {
             throw new (0, _chunkA3A5TI6Rcjs.EffectUnsupportedError)(`time must be a finite number of ms \u2265 0, got ${request.time}.`, id);
           }
           const values = _chunkA3A5TI6Rcjs.resolveEffectValues.call(void 0, d, request.values);
-          _optionalChain([options, 'access', _14 => _14.onRender, 'optionalCall', _15 => _15(id, request)]);
+          _optionalChain([options, 'access', _16 => _16.onRender, 'optionalCall', _17 => _17(id, request)]);
           const out = renderPixels(d, values, request, width, height);
           if (request.mask) {
             if (!capabilities.supportsMask) throw new (0, _chunkA3A5TI6Rcjs.EffectUnsupportedError)("This provider does not take masks.", id);
-            const source = d.uses.includes("filter") ? _optionalChain([request, 'access', _16 => _16.inputs, 'optionalAccess', _17 => _17.source]) : void 0;
+            const source = d.uses.includes("filter") ? _optionalChain([request, 'access', _18 => _18.inputs, 'optionalAccess', _19 => _19.source]) : void 0;
             maskResult(out, request.mask, source, id);
           }
           return depth > 8 && capabilities.supportsFloat ? toFloat(out) : out;
@@ -592,10 +600,16 @@ var typeOf = (s) => Array.isArray(s.type) ? s.type.find((t) => t !== "null") : s
 function isEffectFontControl(schema) {
   return typeOf(schema) === "string" && (schema.format === "font" || schema["x-pixerate-control"] === "font");
 }
+function jsonTypeOf(value) {
+  if (Array.isArray(value)) return "array";
+  if (typeof value === "string" || typeof value === "boolean") return typeof value;
+  if (typeof value === "number") return "number";
+  return void 0;
+}
 function effectControlField(name, schema, fallback, options = {}) {
   const base = { id: name, ...schema.title ? { label: schema.title } : {}, ...schema.description ? { description: schema.description } : {} };
   const def = _nullishCoalesce(schema.default, () => ( fallback));
-  const type = typeOf(schema);
+  const type = _nullishCoalesce(typeOf(schema), () => ( typeOf(_nullishCoalesce(_optionalChain([schema, 'access', _20 => _20.anyOf, 'optionalAccess', _21 => _21.find, 'call', _22 => _22((s) => typeOf(s) === jsonTypeOf(def))]), () => ( {})))));
   if (Array.isArray(schema.enum) && schema.enum.length) {
     const options2 = schema.enum.filter((v) => typeof v === "string" || typeof v === "number");
     return { ...base, type: "choice", options: options2, default: typeof def === "string" || typeof def === "number" ? def : options2[0], control: options2.length <= 4 ? "segmented" : "select" };
@@ -609,7 +623,7 @@ function effectControlField(name, schema, fallback, options = {}) {
   if (isEffectFontControl(schema)) {
     const fonts = _nullishCoalesce(options.fonts, () => ( _chunkFKUKJ3XAcjs.SYSTEM_FONT_CATALOG));
     const opts = fonts.map((f) => ({ value: f.family, label: f.family, description: f.category }));
-    const current = typeof def === "string" && def ? def : _nullishCoalesce(_optionalChain([opts, 'access', _18 => _18[0], 'optionalAccess', _19 => _19.value]), () => ( "sans-serif"));
+    const current = typeof def === "string" && def ? def : _nullishCoalesce(_optionalChain([opts, 'access', _23 => _23[0], 'optionalAccess', _24 => _24.value]), () => ( "sans-serif"));
     if (!opts.some((o) => o.value.toLowerCase() === current.toLowerCase())) opts.unshift({ value: current, label: current, description: "current" });
     return { ...base, type: "choice", options: opts, default: opts.find((o) => o.value.toLowerCase() === current.toLowerCase()).value, control: "select" };
   }
@@ -618,7 +632,7 @@ function effectControlField(name, schema, fallback, options = {}) {
     return { ...base, type: "text", default: typeof def === "string" ? def : "", ...schema.maxLength ? { maxLength: schema.maxLength } : {} };
   }
   if (type === "array" && Array.isArray(def) && def.length >= 2 && def.length <= 4 && def.every((n) => typeof n === "number")) {
-    const items = _nullishCoalesce(schema.items, () => ( {}));
+    const items = _nullishCoalesce(_nullishCoalesce(schema.items, () => ( _optionalChain([schema, 'access', _25 => _25.anyOf, 'optionalAccess', _26 => _26.find, 'call', _27 => _27((s) => typeOf(s) === "array"), 'optionalAccess', _28 => _28.items]))), () => ( {}));
     return { ...base, type: "vector", size: def.length, default: [...def], ...items.minimum !== void 0 ? { min: items.minimum } : {}, ...items.maximum !== void 0 ? { max: items.maximum } : {} };
   }
   return null;
@@ -728,11 +742,11 @@ var EASING_SCHEMA = {
 };
 var NO_SESSION = "No effect authoring session is currently open. Open an effect using EffectProvider.openAuthoring() or in an authoring editor before calling effect authoring tools.";
 function createEffectAuthoringToolProvider(host, options) {
-  const id = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _20 => _20.id]), () => ( "effect-authoring"));
-  const namespace = _optionalChain([options, 'optionalAccess', _21 => _21.namespace]);
-  const title = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _22 => _22.title]), () => ( "Effect authoring"));
-  const description = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _23 => _23.description]), () => ( "Author shaders and procedural effects, inspect parameters, adjust values, and manage keyframe animations."));
-  const skill = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _24 => _24.skill]), () => ( "pixerate-effect-authoring"));
+  const id = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _29 => _29.id]), () => ( "effect-authoring"));
+  const namespace = _optionalChain([options, 'optionalAccess', _30 => _30.namespace]);
+  const title = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _31 => _31.title]), () => ( "Effect authoring"));
+  const description = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _32 => _32.description]), () => ( "Author shaders and procedural effects, inspect parameters, adjust values, and manage keyframe animations."));
+  const skill = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _33 => _33.skill]), () => ( "pixerate-effect-authoring"));
   const requireSession = () => {
     const s = host.session();
     if (!s) throw new Error(NO_SESSION);
@@ -753,7 +767,7 @@ function createEffectAuthoringToolProvider(host, options) {
         sourceLanguage: state.sourceLanguage,
         controls: effectParameterFields(state.description),
         values: state.values,
-        presets: _nullishCoalesce(_optionalChain([state, 'access', _25 => _25.description, 'access', _26 => _26.presets, 'optionalAccess', _27 => _27.map, 'call', _28 => _28((p) => p.name)]), () => ( [])),
+        presets: _nullishCoalesce(_optionalChain([state, 'access', _34 => _34.description, 'access', _35 => _35.presets, 'optionalAccess', _36 => _36.map, 'call', _37 => _37((p) => p.name)]), () => ( [])),
         tracks: Object.entries(state.tracks).map(([control, track]) => ({
           control,
           keyframes: track.length
@@ -1060,7 +1074,7 @@ function createEffectAuthoringToolProvider(host, options) {
       const tools = [
         describeTool,
         getSourceTool,
-        ..._optionalChain([session, 'optionalAccess', _29 => _29.setSource]) ? [setSourceTool] : [],
+        ..._optionalChain([session, 'optionalAccess', _38 => _38.setSource]) ? [setSourceTool] : [],
         setValuesTool,
         resetValuesTool,
         applyPresetTool,

package/dist/effects/index.js

@@ -61,6 +61,7 @@ function checkSummary(e, issues) {
   if (typeof e.transparent !== "boolean") at("transparent is not a boolean");
   if (typeof e.loop !== "boolean") at("loop is not a boolean");
   if (e.duration !== void 0 && !(e.duration > 0)) at("duration must be a positive number of ms when present");
+  if (e.backgroundOpacity !== void 0 && (typeof e.backgroundOpacity !== "string" || !e.backgroundOpacity)) at("backgroundOpacity must name a control when present");
 }
 function checkDescription(id, d, issues) {
   const at = (message) => issues.push({ effectId: id, message });
@@ -73,6 +74,11 @@ function checkDescription(id, d, issues) {
     if (!(name in (d.defaults ?? {}))) at(`control "${name}" has no default`);
   }
   for (const name of Object.keys(d.defaults ?? {})) if (!(name in (c?.properties ?? {}))) at(`default "${name}" is not a control`);
+  if (d.backgroundOpacity !== void 0) {
+    const control = c?.properties?.[d.backgroundOpacity];
+    if (!control) at(`backgroundOpacity "${d.backgroundOpacity}" is not a control`);
+    else if (control.type !== "number" || control.minimum !== 0 || control.maximum !== 1) at(`backgroundOpacity "${d.backgroundOpacity}" must be a number control from 0 to 1`);
+  }
   for (const e of effectValueErrors(d, d.defaults)) at(`default ${e.path}: ${e.message}`);
   for (const p of d.presets ?? []) for (const e of effectValueErrors(d, p.values)) at(`preset "${p.name}" ${e.path}: ${e.message}`);
   for (const input2 of d.inputs ?? []) {
@@ -278,6 +284,7 @@ var DESCRIPTIONS = [
     transparent: false,
     loop: true,
     duration: 4e3,
+    backgroundOpacity: "opacity",
     controls: {
       type: "object",
       additionalProperties: false,
@@ -285,10 +292,11 @@ var DESCRIPTIONS = [
         from: colour("Start colour as #rrggbb. Default #1e3a8a."),
         to: colour("End colour as #rrggbb. Default #f472b6."),
         angle: { type: "number", minimum: 0, maximum: 360, description: "Direction in degrees, 0 = left to right, 90 = top to bottom. Default 90." },
-        spin: { type: "number", minimum: -360, maximum: 360, description: "Turn per loop (4 s) in degrees. Default 0." }
+        spin: { type: "number", minimum: -360, maximum: 360, description: "Turn per loop (4 s) in degrees. Default 0." },
+        opacity: { type: "number", minimum: 0, maximum: 1, description: "Background opacity 0\u20131: 0 is fully transparent. Default 1." }
       }
     },
-    defaults: { from: "#1e3a8a", to: "#f472b6", angle: 90, spin: 0 },
+    defaults: { from: "#1e3a8a", to: "#f472b6", angle: 90, spin: 0, opacity: 1 },
     presets: [{ name: "Sunset", values: { from: "#f97316", to: "#7c3aed" } }],
     inputs: []
   },
@@ -434,7 +442,7 @@ function renderPixels(d, v, request, width, height) {
         for (let x = 0; x < width; x++, i += 4) {
           const t = clamp01(((x + 0.5 - width / 2) * dx + (y + 0.5 - height / 2) * dy) / (2 * half) + 0.5);
           for (let c = 0; c < 3; c++) o[i + c] = a[c] + (b[c] - a[c]) * t;
-          o[i + 3] = 255;
+          o[i + 3] = 255 * clamp01(v.opacity);
         }
       }
       break;
@@ -592,10 +600,16 @@ var typeOf = (s) => Array.isArray(s.type) ? s.type.find((t) => t !== "null") : s
 function isEffectFontControl(schema) {
   return typeOf(schema) === "string" && (schema.format === "font" || schema["x-pixerate-control"] === "font");
 }
+function jsonTypeOf(value) {
+  if (Array.isArray(value)) return "array";
+  if (typeof value === "string" || typeof value === "boolean") return typeof value;
+  if (typeof value === "number") return "number";
+  return void 0;
+}
 function effectControlField(name, schema, fallback, options = {}) {
   const base = { id: name, ...schema.title ? { label: schema.title } : {}, ...schema.description ? { description: schema.description } : {} };
   const def = schema.default ?? fallback;
-  const type = typeOf(schema);
+  const type = typeOf(schema) ?? typeOf(schema.anyOf?.find((s) => typeOf(s) === jsonTypeOf(def)) ?? {});
   if (Array.isArray(schema.enum) && schema.enum.length) {
     const options2 = schema.enum.filter((v) => typeof v === "string" || typeof v === "number");
     return { ...base, type: "choice", options: options2, default: typeof def === "string" || typeof def === "number" ? def : options2[0], control: options2.length <= 4 ? "segmented" : "select" };
@@ -618,7 +632,7 @@ function effectControlField(name, schema, fallback, options = {}) {
     return { ...base, type: "text", default: typeof def === "string" ? def : "", ...schema.maxLength ? { maxLength: schema.maxLength } : {} };
   }
   if (type === "array" && Array.isArray(def) && def.length >= 2 && def.length <= 4 && def.every((n) => typeof n === "number")) {
-    const items = schema.items ?? {};
+    const items = schema.items ?? schema.anyOf?.find((s) => typeOf(s) === "array")?.items ?? {};
     return { ...base, type: "vector", size: def.length, default: [...def], ...items.minimum !== void 0 ? { min: items.minimum } : {}, ...items.maximum !== void 0 ? { max: items.maximum } : {} };
   }
   return null;

package/dist/effects/types.d.cts

@@ -42,6 +42,12 @@ export interface EffectSummary {
     loop: boolean;
     /** Length of one play (ms). Absent for effects that do not change over time. */
     duration?: number;
+    /**
+     * The control (a number from 0 to 1) setting how opaque the effect's own background is: at 0
+     * only what it draws is left, so it can sit over other content. Absent when the effect has no
+     * background of its own to fade (an overlay is already transparent).
+     */
+    backgroundOpacity?: string;
 }
 export interface EffectSearchOptions {
     kind?: EffectKind;

package/dist/effects/types.d.ts

@@ -42,6 +42,12 @@ export interface EffectSummary {
     loop: boolean;
     /** Length of one play (ms). Absent for effects that do not change over time. */
     duration?: number;
+    /**
+     * The control (a number from 0 to 1) setting how opaque the effect's own background is: at 0
+     * only what it draws is left, so it can sit over other content. Absent when the effect has no
+     * background of its own to fade (an overlay is already transparent).
+     */
+    backgroundOpacity?: string;
 }
 export interface EffectSearchOptions {
     kind?: EffectKind;

package/dist/effects/ui.d.cts

@@ -19,12 +19,6 @@ export interface EffectFieldOptions {
  * `"x-pixerate-control": "font"`.
  */
 export declare function isEffectFontControl(schema: JsonSchema): boolean;
-/**
- * One control as a parameter field: numbers and integers (sliders when bounded), switches,
- * choices (`enum`), font families (`format: "font"`, a choice of `options.fonts`), colours
- * (strings whose default is `#rrggbb`), vectors (2–4 numbers) and text.
- * `null` for a control no field can edit (objects, long lists).
- */
 export declare function effectControlField(name: string, schema: JsonSchema, fallback: EffectValue | undefined, options?: EffectFieldOptions): ParameterField | null;
 /** An effect's controls as parameter fields, in schema order (controls no field can edit are left out). */
 export declare function effectParameterFields(description: Pick<EffectDescription, 'controls' | 'defaults'>, options?: EffectFieldOptions): ParameterField[];

package/dist/effects/ui.d.ts

@@ -19,12 +19,6 @@ export interface EffectFieldOptions {
  * `"x-pixerate-control": "font"`.
  */
 export declare function isEffectFontControl(schema: JsonSchema): boolean;
-/**
- * One control as a parameter field: numbers and integers (sliders when bounded), switches,
- * choices (`enum`), font families (`format: "font"`, a choice of `options.fonts`), colours
- * (strings whose default is `#rrggbb`), vectors (2–4 numbers) and text.
- * `null` for a control no field can edit (objects, long lists).
- */
 export declare function effectControlField(name: string, schema: JsonSchema, fallback: EffectValue | undefined, options?: EffectFieldOptions): ParameterField | null;
 /** An effect's controls as parameter fields, in schema order (controls no field can edit are left out). */
 export declare function effectParameterFields(description: Pick<EffectDescription, 'controls' | 'defaults'>, options?: EffectFieldOptions): ParameterField[];

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

@@ -9,7 +9,7 @@ import { type SelectionModifyOp } from './selection/modify.cjs';
 import { type RefineEdgeParams } from './selection/refine.cjs';
 import type { LayerMaskProps } from './selection/layer-mask.cjs';
 import type { AdjustmentLayerMask } from './types.cjs';
-import { type LayerBlendMode, type ImageLayer, type LayerFilter, type LayerTarget, type PixelLayer, type RasterMask, type SmartContents, type SmartFilter, type SmartPlacement, type LiveShape, type ShapeFillRule, type ShapeOperation, type ShapePaint, type ShapeStroke, type ParagraphStyle, type TextStyle, type TypeLayer } from './layers/model.cjs';
+import { type LayerBlendMode, type ImageLayer, type LayerFilter, type LayerTarget, type PixelLayer, type RasterMask, type SmartContents, type SmartFilter, type SmartPlacement, type LiveShape, type ShapeFillRule, type ShapeOperation, type ShapePaint, type ShapeStroke, type ParagraphStyle, type TextStyle, type TypeLayer, type ImageEffectAnimation } from './layers/model.cjs';
 import { type TextLayout, type TextShaper } from './layers/text.cjs';
 import type { VectorSubpath } from '../vector/types.cjs';
 import { EffectsSlot } from '../effects/helpers.cjs';
@@ -609,25 +609,48 @@ export declare class ImageEditorController {
     /**
      * 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.
      */
     addEffectLayer(effect: string, options?: LayerPlacement & {
         values?: Record<string, EffectValue>;
         name?: string;
         time?: number;
+        animate?: ImageEffectAnimation;
         opacity?: number;
         blend?: string;
         id?: string;
     }): Promise<string>;
     /**
-     * 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.
      */
     updateEffectLayer(layerId: string, changes: {
+        effect?: string;
         values?: Record<string, EffectValue | null>;
         time?: number;
+        animate?: ImageEffectAnimation | null;
     }, commitToHistory?: boolean): Promise<NonNullable<PixelLayer['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(): {
+        duration: number;
+        layerIds: string[];
+    } | null;
+    /**
+     * 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.
+     */
+    renderAnimationFrame(time: number, options?: ExportOptions): Promise<HTMLCanvasElement>;
     /** Turns an effect layer into a plain pixel layer keeping its pixels (one undo step). */
     rasterizeEffectLayer(layerId: string): void;
     private displayFor;

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

@@ -9,7 +9,7 @@ import { type SelectionModifyOp } from './selection/modify.js';
 import { type RefineEdgeParams } from './selection/refine.js';
 import type { LayerMaskProps } from './selection/layer-mask.js';
 import type { AdjustmentLayerMask } from './types.js';
-import { type LayerBlendMode, type ImageLayer, type LayerFilter, type LayerTarget, type PixelLayer, type RasterMask, type SmartContents, type SmartFilter, type SmartPlacement, type LiveShape, type ShapeFillRule, type ShapeOperation, type ShapePaint, type ShapeStroke, type ParagraphStyle, type TextStyle, type TypeLayer } from './layers/model.js';
+import { type LayerBlendMode, type ImageLayer, type LayerFilter, type LayerTarget, type PixelLayer, type RasterMask, type SmartContents, type SmartFilter, type SmartPlacement, type LiveShape, type ShapeFillRule, type ShapeOperation, type ShapePaint, type ShapeStroke, type ParagraphStyle, type TextStyle, type TypeLayer, type ImageEffectAnimation } from './layers/model.js';
 import { type TextLayout, type TextShaper } from './layers/text.js';
 import type { VectorSubpath } from '../vector/types.js';
 import { EffectsSlot } from '../effects/helpers.js';
@@ -609,25 +609,48 @@ export declare class ImageEditorController {
     /**
      * 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.
      */
     addEffectLayer(effect: string, options?: LayerPlacement & {
         values?: Record<string, EffectValue>;
         name?: string;
         time?: number;
+        animate?: ImageEffectAnimation;
         opacity?: number;
         blend?: string;
         id?: string;
     }): Promise<string>;
     /**
-     * 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.
      */
     updateEffectLayer(layerId: string, changes: {
+        effect?: string;
         values?: Record<string, EffectValue | null>;
         time?: number;
+        animate?: ImageEffectAnimation | null;
     }, commitToHistory?: boolean): Promise<NonNullable<PixelLayer['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(): {
+        duration: number;
+        layerIds: string[];
+    } | null;
+    /**
+     * 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.
+     */
+    renderAnimationFrame(time: number, options?: ExportOptions): Promise<HTMLCanvasElement>;
     /** Turns an effect layer into a plain pixel layer keeping its pixels (one undo step). */
     rasterizeEffectLayer(layerId: string): void;
     private displayFor;

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

@@ -0,0 +1,40 @@
+/**
+ * Effect layer rules shared by the controller and the panels: which layers sit below one (so its
+ * background starts transparent), the checks on a still frame's time and an animation, and the
+ * timing the panels show.
+ */
+import type { EffectDescription, EffectSummary, EffectValue } from '../effects/types.cjs';
+import { type ImageEffectAnimation, type ImageEffectGenerator, type ImageLayer } from './layers/model.cjs';
+/**
+ * Whether anything is drawn below layer `id` in the stack: a pixel, shape, type or smart object
+ * layer under it (groups and adjustment layers draw nothing of their own). False for the bottom
+ * layer, or an id not in the stack.
+ */
+export declare function hasLayersBelow(layers: readonly ImageLayer[], id: string): boolean;
+/**
+ * `values` with the effect's background opacity control (`backgroundOpacity`) set to 0 when the
+ * layer has others below it and `values` leave it unset; otherwise `values` unchanged.
+ */
+export declare function withBackgroundOpacity(d: Pick<EffectDescription, 'backgroundOpacity'>, values: Record<string, EffectValue> | undefined, below: boolean): Record<string, EffectValue>;
+/** A still frame's time: a number of ms from 0 (undefined is 0). */
+export declare function checkEffectTime(time: number | undefined): number;
+/** An effect layer's animation: a duration in ms, more than 0 and at most `MAX_EFFECT_ANIMATION_MS`. */
+export declare function checkEffectAnimation(animate: ImageEffectAnimation): ImageEffectAnimation;
+/** What the panels show of an effect layer's timing (see `effectLayerTiming`). */
+export interface EffectLayerTiming {
+    /** A still frame at `time`, or playing from `time` in an animation. */
+    mode: 'still' | 'animate';
+    /** The frame drawn (ms): the still frame, and where the animation starts. */
+    time: number;
+    /** How far the frame can be moved (ms): one loop of a looping effect, else one play. */
+    range: number;
+    /** How long it plays in an animation (ms): its own, else the effect's play. */
+    duration: number;
+    /** The effect repeats every `range` ms. */
+    loops: boolean;
+}
+/**
+ * An effect layer's timing for the panels, or null when its effect does not change over time
+ * (the provider gives it no `duration`).
+ */
+export declare function effectLayerTiming(g: ImageEffectGenerator, d: Pick<EffectSummary, 'duration' | 'loop'> | null | undefined): EffectLayerTiming | null;

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

@@ -0,0 +1,40 @@
+/**
+ * Effect layer rules shared by the controller and the panels: which layers sit below one (so its
+ * background starts transparent), the checks on a still frame's time and an animation, and the
+ * timing the panels show.
+ */
+import type { EffectDescription, EffectSummary, EffectValue } from '../effects/types.js';
+import { type ImageEffectAnimation, type ImageEffectGenerator, type ImageLayer } from './layers/model.js';
+/**
+ * Whether anything is drawn below layer `id` in the stack: a pixel, shape, type or smart object
+ * layer under it (groups and adjustment layers draw nothing of their own). False for the bottom
+ * layer, or an id not in the stack.
+ */
+export declare function hasLayersBelow(layers: readonly ImageLayer[], id: string): boolean;
+/**
+ * `values` with the effect's background opacity control (`backgroundOpacity`) set to 0 when the
+ * layer has others below it and `values` leave it unset; otherwise `values` unchanged.
+ */
+export declare function withBackgroundOpacity(d: Pick<EffectDescription, 'backgroundOpacity'>, values: Record<string, EffectValue> | undefined, below: boolean): Record<string, EffectValue>;
+/** A still frame's time: a number of ms from 0 (undefined is 0). */
+export declare function checkEffectTime(time: number | undefined): number;
+/** An effect layer's animation: a duration in ms, more than 0 and at most `MAX_EFFECT_ANIMATION_MS`. */
+export declare function checkEffectAnimation(animate: ImageEffectAnimation): ImageEffectAnimation;
+/** What the panels show of an effect layer's timing (see `effectLayerTiming`). */
+export interface EffectLayerTiming {
+    /** A still frame at `time`, or playing from `time` in an animation. */
+    mode: 'still' | 'animate';
+    /** The frame drawn (ms): the still frame, and where the animation starts. */
+    time: number;
+    /** How far the frame can be moved (ms): one loop of a looping effect, else one play. */
+    range: number;
+    /** How long it plays in an animation (ms): its own, else the effect's play. */
+    duration: number;
+    /** The effect repeats every `range` ms. */
+    loops: boolean;
+}
+/**
+ * An effect layer's timing for the panels, or null when its effect does not change over time
+ * (the provider gives it no `duration`).
+ */
+export declare function effectLayerTiming(g: ImageEffectGenerator, d: Pick<EffectSummary, 'duration' | 'loop'> | null | undefined): EffectLayerTiming | null;