@pixerate/editor 0.146.0 → 0.148.0

package/dist/effects/index.js

@@ -25,6 +25,14 @@ import {
   srgbToLinear
 } from "../chunk-7KWJEYIK.js";
 import "../chunk-V2ZCJRDM.js";
+import {
+  HistoryManager
+} from "../chunk-RNSANXPT.js";
+import {
+  ANIMATION_EASING_PRESETS,
+  evaluateEasing,
+  isAnimationEasing
+} from "../chunk-5UJHB3BW.js";
 
 // src/effects/conformance.ts
 var codeOf = (e) => isEffectError(e) ? e.code : e instanceof Error ? `untyped ${e.name}: ${e.message}` : String(e);
@@ -107,7 +115,9 @@ async function checkEffectProvider(provider, options = {}) {
   for (const k of ["supportsWorker", "supportsFloat", "supportsMask", "supportsHostImages", "supportsVector"]) {
     if (typeof caps?.[k] !== "boolean") top(`capabilities.${k} is not a boolean`);
   }
+  if (caps?.supportsAuthoring !== void 0 && typeof caps.supportsAuthoring !== "boolean") top("capabilities.supportsAuthoring is not a boolean");
   if (caps?.supportsVector && typeof provider.applyVectorEffect !== "function") top("supportsVector is set but applyVectorEffect is missing");
+  if (caps?.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) {
@@ -149,9 +159,810 @@ async function checkEffectProvider(provider, options = {}) {
       if (bad) issues.push({ effectId: id, message: `applyVectorEffect with an unknown control ${bad}` });
     }
   }
+  if (caps?.supportsAuthoring && options.authoring !== false && typeof provider.openAuthoring === "function") {
+    const targetEffect = (await Promise.all((options.ids ?? [...ids]).map((id) => provider.describe(id)))).find(
+      (d) => d.kind !== "motion" && d.kind !== "vector"
+    );
+    if (targetEffect) {
+      try {
+        const session = await provider.openAuthoring({ effectId: targetEffect.id });
+        const s1 = session.getState();
+        const s2 = session.getState();
+        if (s1 !== s2) {
+          issues.push({ effectId: targetEffect.id, message: "session.getState() returned different objects without changes" });
+        }
+        checkDescription(targetEffect.id, s1.description, issues);
+        const badRes = session.setValue("__no_such_control__", 123);
+        if (badRes.ok) {
+          issues.push({ effectId: targetEffect.id, message: "setValue with unknown control did not fail" });
+        } else if (session.getState() !== s1) {
+          issues.push({ effectId: targetEffect.id, message: "setValue with unknown control changed state" });
+        }
+        const firstKey = Object.keys(targetEffect.defaults)[0];
+        if (firstKey) {
+          const val = targetEffect.defaults[firstKey];
+          session.setValue(firstKey, val);
+          if (!session.getState().canUndo) {
+            issues.push({ effectId: targetEffect.id, message: "setValue did not enable canUndo" });
+          }
+          const undone = session.undo();
+          if (!undone) {
+            issues.push({ effectId: targetEffect.id, message: "undo() returned false" });
+          }
+        }
+        const doc = session.exportDocument();
+        const cloned = JSON.parse(JSON.stringify(doc));
+        const restored = await provider.openAuthoring({ document: cloned });
+        if (JSON.stringify(restored.getState().values) !== JSON.stringify(session.getState().values)) {
+          issues.push({ effectId: targetEffect.id, message: "reopening exported document gave different values" });
+        }
+        restored.dispose();
+        if (s1.sourceLanguage !== null && typeof session.setSource !== "function") {
+          issues.push({ effectId: targetEffect.id, message: "sourceLanguage is not null but setSource is missing" });
+        }
+        try {
+          session.dispose();
+        } catch (e) {
+          issues.push({ effectId: targetEffect.id, message: `session.dispose() threw: ${codeOf(e)}` });
+        }
+      } catch (e) {
+        issues.push({ effectId: targetEffect.id, message: `authoring check failed: ${codeOf(e)}` });
+      }
+    }
+  }
   return issues;
 }
 
+// src/effects/authoring-session.ts
+var HEX_RE = /^#([0-9a-f]{6}|[0-9a-f]{8})$/i;
+function valueErrorMessage(errors) {
+  return errors.map((e) => {
+    const [control, ...rest] = e.path.replace(/^\//, "").split("/");
+    return `control "${control}"${rest.length ? ` (item ${rest.join("/")})` : ""}: ${e.message}`;
+  }).join("; ");
+}
+function documentErrors(doc, description) {
+  const errors = [];
+  const controls = Object.keys(description.controls.properties);
+  const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+  if (doc.values !== void 0) {
+    if (!isRecord(doc.values)) errors.push({ path: "/values", message: "must be an object of control values" });
+    else errors.push(...effectValueErrors(description, doc.values).map((e) => ({ ...e, path: `/values${e.path}` })));
+  }
+  if (doc.tracks !== void 0) {
+    if (!isRecord(doc.tracks)) errors.push({ path: "/tracks", message: "must be an object of keyframe lists" });
+    else
+      for (const [control, kfs] of Object.entries(doc.tracks)) {
+        const at = `/tracks/${control}`;
+        if (!controls.includes(control)) errors.push({ path: at, message: `there is no control "${control}"; the controls are ${controls.join(", ")}` });
+        else if (!Array.isArray(kfs)) errors.push({ path: at, message: "must be a list of keyframes" });
+        else
+          kfs.forEach((kf, i) => {
+            if (!isRecord(kf)) return errors.push({ path: `${at}/${i}`, message: "must be a keyframe object" });
+            if (typeof kf.time !== "number" || !Number.isFinite(kf.time) || kf.time < 0) errors.push({ path: `${at}/${i}/time`, message: "must be a finite number of ms >= 0" });
+            errors.push(...effectValueErrors(description, { [control]: kf.value }).map((e) => ({ ...e, path: `${at}/${i}/value` })));
+            if (kf.easing !== void 0 && !isAnimationEasing(kf.easing)) errors.push({ path: `${at}/${i}/easing`, message: "is not a valid easing" });
+          });
+      }
+  }
+  if (doc.presets !== void 0) {
+    if (!Array.isArray(doc.presets)) errors.push({ path: "/presets", message: "must be a list of presets" });
+    else
+      doc.presets.forEach((p, i) => {
+        if (!isRecord(p) || typeof p.name !== "string" || !p.name) return errors.push({ path: `/presets/${i}`, message: "must have a name" });
+        errors.push(...effectValueErrors(description, p.values).map((e) => ({ ...e, path: `/presets/${i}/values${e.path}` })));
+      });
+  }
+  if (doc.duration !== void 0 && (typeof doc.duration !== "number" || !Number.isFinite(doc.duration) || !(doc.duration > 0))) {
+    errors.push({ path: "/duration", message: "must be a finite number of ms > 0" });
+  }
+  if (doc.loop !== void 0 && typeof doc.loop !== "boolean") errors.push({ path: "/loop", message: "must be a boolean" });
+  return errors;
+}
+function parseHex(hex) {
+  if (!HEX_RE.test(hex)) return null;
+  const body = hex.slice(1);
+  const r = parseInt(body.slice(0, 2), 16);
+  const g = parseInt(body.slice(2, 4), 16);
+  const b = parseInt(body.slice(4, 6), 16);
+  const hasAlpha = body.length === 8;
+  const a = hasAlpha ? parseInt(body.slice(6, 8), 16) : 255;
+  return { r, g, b, a, hasAlpha };
+}
+function toHex2(n) {
+  const clamped = Math.round(Math.max(0, Math.min(255, n)));
+  return clamped.toString(16).padStart(2, "0");
+}
+function lerpHex(c1, c2, t) {
+  const p1 = parseHex(c1);
+  const p2 = parseHex(c2);
+  if (!p1 || !p2) return t >= 1 ? c2 : c1;
+  const r = p1.r + (p2.r - p1.r) * t;
+  const g = p1.g + (p2.g - p1.g) * t;
+  const b = p1.b + (p2.b - p1.b) * t;
+  const a = p1.a + (p2.a - p1.a) * t;
+  const withAlpha = p1.hasAlpha || p2.hasAlpha;
+  return `#${toHex2(r)}${toHex2(g)}${toHex2(b)}${withAlpha ? toHex2(a) : ""}`;
+}
+function interpolateValue(v1, v2, progress) {
+  if (typeof v1 === "number" && typeof v2 === "number") {
+    return v1 + (v2 - v1) * progress;
+  }
+  if (Array.isArray(v1) && Array.isArray(v2) && v1.length === v2.length) {
+    return v1.map((num, i) => {
+      const other = v2[i];
+      return typeof num === "number" && typeof other === "number" ? num + (other - num) * progress : num;
+    });
+  }
+  if (typeof v1 === "string" && typeof v2 === "string" && v1.startsWith("#") && v2.startsWith("#")) {
+    return lerpHex(v1, v2, progress);
+  }
+  return progress >= 1 ? v2 : v1;
+}
+function valuesAtTime(time, baseValues, tracks) {
+  const result = { ...baseValues };
+  for (const [control, kfs] of Object.entries(tracks)) {
+    if (!kfs || kfs.length === 0) continue;
+    if (kfs.length === 1) {
+      result[control] = kfs[0].value;
+      continue;
+    }
+    if (time <= kfs[0].time) {
+      result[control] = kfs[0].value;
+      continue;
+    }
+    const last = kfs[kfs.length - 1];
+    if (time >= last.time) {
+      result[control] = last.value;
+      continue;
+    }
+    let idx = 0;
+    while (idx < kfs.length - 1 && kfs[idx + 1].time <= time) {
+      idx++;
+    }
+    const kf1 = kfs[idx];
+    const kf2 = kfs[idx + 1];
+    const span = kf2.time - kf1.time;
+    const rawProgress = span > 0 ? (time - kf1.time) / span : 0;
+    const easing = kf1.easing ?? "linear";
+    const eased = evaluateEasing(easing, rawProgress);
+    result[control] = interpolateValue(kf1.value, kf2.value, eased);
+  }
+  return result;
+}
+var defaultSchedule = (frame) => {
+  if (typeof requestAnimationFrame === "function") {
+    let handle2;
+    let running2 = true;
+    const tick2 = (now) => {
+      if (!running2) return;
+      frame(now);
+      if (running2) handle2 = requestAnimationFrame(tick2);
+    };
+    handle2 = requestAnimationFrame(tick2);
+    return () => {
+      running2 = false;
+      cancelAnimationFrame(handle2);
+    };
+  }
+  let handle;
+  let running = true;
+  const interval = 16;
+  const tick = () => {
+    if (!running) return;
+    frame(Date.now());
+    if (running) handle = setTimeout(tick, interval);
+  };
+  handle = setTimeout(tick, interval);
+  return () => {
+    running = false;
+    clearTimeout(handle);
+  };
+};
+function isDocumentSource(source) {
+  return "document" in source && typeof source.document === "object" && source.document !== null;
+}
+async function createEffectAuthoringSession(source, options) {
+  const { provider, history = new HistoryManager(), mergeWindowMs = 400 } = options;
+  const scheduleFn = options.schedule ?? defaultSchedule;
+  let effectId;
+  let requestedPreset;
+  let initialDoc = null;
+  if (isDocumentSource(source)) {
+    const doc = source.document;
+    if (doc.version !== 1 || !doc.effectId) {
+      throw new EffectUnsupportedError("Invalid effect authoring document: version 1 required");
+    }
+    effectId = doc.effectId;
+    initialDoc = doc;
+  } else if ("effectId" in source && typeof source.effectId === "string") {
+    effectId = source.effectId;
+    requestedPreset = source.preset;
+  } else {
+    throw new EffectUnsupportedError("Invalid effect authoring source");
+  }
+  const description = await provider.describe(effectId);
+  if (initialDoc) {
+    const problems = documentErrors(initialDoc, description);
+    if (problems.length) throw new EffectControlError(effectId, problems);
+  }
+  if (description.kind === "motion") {
+    throw new EffectUnsupportedError("Motion effects cannot be authored as pixel effects", effectId);
+  }
+  let disposed = false;
+  let playing = false;
+  let cancelSchedule = null;
+  let lastScheduleTime = null;
+  let playheadTime = 0;
+  let duration = initialDoc?.duration ?? description.duration ?? 1e3;
+  if (!(duration > 0)) duration = 1e3;
+  let loop = initialDoc?.loop ?? description.loop ?? false;
+  let compiled = null;
+  let savedPresets = initialDoc ? [...initialDoc.presets ?? []] : [];
+  let baseValues = { ...description.defaults };
+  if (initialDoc?.values) {
+    baseValues = { ...baseValues, ...initialDoc.values };
+  } else if (requestedPreset) {
+    const found = description.presets.find((p) => p.name === requestedPreset);
+    if (!found) {
+      const validNames = description.presets.map((p) => `"${p.name}"`).join(", ");
+      throw new EffectUnsupportedError(
+        `Unknown preset "${requestedPreset}" for effect "${effectId}". Valid presets are: ${validNames || "none"}`,
+        effectId
+      );
+    }
+    baseValues = { ...baseValues, ...found.values };
+  }
+  let tracks = {};
+  if (initialDoc?.tracks) {
+    for (const [k, kfs] of Object.entries(initialDoc.tracks)) {
+      tracks[k] = [...kfs].sort((a, b) => a.time - b.time);
+    }
+  }
+  const livePreviews = /* @__PURE__ */ new Set();
+  const listeners = /* @__PURE__ */ new Set();
+  let cachedState = null;
+  function mergePresets() {
+    const result = [];
+    const seen = /* @__PURE__ */ new Set();
+    for (const p of savedPresets) {
+      result.push(p);
+      seen.add(p.name);
+    }
+    for (const p of description.presets) {
+      if (!seen.has(p.name)) {
+        result.push(p);
+        seen.add(p.name);
+      }
+    }
+    return result;
+  }
+  function currentMergedDescription() {
+    return {
+      ...description,
+      presets: mergePresets()
+    };
+  }
+  function buildState() {
+    const desc = currentMergedDescription();
+    const currentValues = valuesAtTime(playheadTime, baseValues, tracks);
+    const historyState = history.getState();
+    return {
+      providerId: provider.id,
+      effectId,
+      name: initialDoc?.name ?? description.name,
+      kind: description.kind,
+      description: desc,
+      source: null,
+      sourceLanguage: null,
+      values: currentValues,
+      tracks: { ...tracks },
+      issues: [],
+      compiled,
+      time: playheadTime,
+      duration,
+      loop,
+      playing,
+      canUndo: historyState.canUndo,
+      canRedo: historyState.canRedo
+    };
+  }
+  function getState() {
+    if (!cachedState) {
+      cachedState = buildState();
+    }
+    return cachedState;
+  }
+  function invalidateState() {
+    cachedState = null;
+    const next = getState();
+    listeners.forEach((l) => l(next));
+  }
+  function validControlNames() {
+    return Object.keys(description.controls.properties);
+  }
+  function checkDisposed() {
+    if (disposed) {
+      return { ok: false, message: "the session is closed" };
+    }
+    return null;
+  }
+  function pauseInternal() {
+    if (!playing) return;
+    playing = false;
+    if (cancelSchedule) {
+      cancelSchedule();
+      cancelSchedule = null;
+    }
+    lastScheduleTime = null;
+    invalidateState();
+  }
+  function seekInternal(t) {
+    const clamped = Math.max(0, Math.min(duration, t));
+    if (clamped !== playheadTime) {
+      playheadTime = clamped;
+      invalidateState();
+    }
+  }
+  const session = {
+    getState,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    setValue(name, value, opts) {
+      const disp = checkDisposed();
+      if (disp) return disp;
+      const validNames = validControlNames();
+      if (!validNames.includes(name)) {
+        return { ok: false, message: `there is no control "${name}"; the controls are ${validNames.join(", ")}` };
+      }
+      const errors = effectValueErrors(description, { [name]: value });
+      if (errors.length > 0) {
+        return { ok: false, message: valueErrorMessage(errors) };
+      }
+      const isAnimated = (tracks[name]?.length ?? 0) > 0;
+      if (isAnimated) {
+        const oldTracks = { ...tracks };
+        const t = playheadTime;
+        const currentTrack = [...tracks[name] ?? []];
+        const existingIdx = currentTrack.findIndex((kf) => kf.time === t);
+        const prevKf = existingIdx >= 0 ? currentTrack[existingIdx] : void 0;
+        const execute2 = () => {
+          const track = [...tracks[name] ?? []];
+          const idx = track.findIndex((kf) => kf.time === t);
+          if (idx >= 0) {
+            track[idx] = { ...track[idx], value };
+          } else {
+            track.push({ time: t, value });
+            track.sort((a, b) => a.time - b.time);
+          }
+          tracks[name] = track;
+          invalidateState();
+        };
+        const undo2 = () => {
+          tracks = { ...oldTracks };
+          invalidateState();
+        };
+        const cmd2 = {
+          name: `Set ${name}`,
+          tag: name,
+          execute: execute2,
+          undo: undo2
+        };
+        if (opts?.gesture) {
+          history.executeMerged(cmd2, { key: opts.gesture });
+        } else {
+          history.executeMerged(cmd2, { windowMs: mergeWindowMs });
+        }
+        invalidateState();
+        return { ok: true };
+      }
+      const prevVal = baseValues[name];
+      const execute = () => {
+        baseValues[name] = value;
+      };
+      const undo = () => {
+        baseValues[name] = prevVal;
+      };
+      const cmd = {
+        name: `Set ${name}`,
+        tag: name,
+        execute,
+        undo
+      };
+      if (opts?.gesture) {
+        history.executeMerged(cmd, { key: opts.gesture });
+      } else {
+        history.executeMerged(cmd, { windowMs: mergeWindowMs });
+      }
+      invalidateState();
+      return { ok: true };
+    },
+    setValues(values, opts) {
+      const disp = checkDisposed();
+      if (disp) return disp;
+      const validNames = validControlNames();
+      for (const [k, v] of Object.entries(values)) {
+        if (!validNames.includes(k)) {
+          return { ok: false, message: `there is no control "${k}"; the controls are ${validNames.join(", ")}` };
+        }
+        const errors = effectValueErrors(description, { [k]: v });
+        if (errors.length > 0) {
+          return { ok: false, message: valueErrorMessage(errors) };
+        }
+      }
+      const prevBase = { ...baseValues };
+      const prevTracks = { ...tracks };
+      const t = playheadTime;
+      const execute = () => {
+        for (const [k, v] of Object.entries(values)) {
+          const isAnimated = (tracks[k]?.length ?? 0) > 0;
+          if (isAnimated) {
+            const track = [...tracks[k] ?? []];
+            const idx = track.findIndex((kf) => kf.time === t);
+            if (idx >= 0) {
+              track[idx] = { ...track[idx], value: v };
+            } else {
+              track.push({ time: t, value: v });
+              track.sort((a, b) => a.time - b.time);
+            }
+            tracks[k] = track;
+          } else {
+            baseValues[k] = v;
+          }
+        }
+      };
+      const undo = () => {
+        baseValues = { ...prevBase };
+        tracks = { ...prevTracks };
+      };
+      const cmd = {
+        name: "Set values",
+        execute,
+        undo
+      };
+      if (opts?.gesture) {
+        history.executeMerged(cmd, { key: opts.gesture });
+      } else {
+        history.execute(cmd);
+      }
+      invalidateState();
+      return { ok: true };
+    },
+    resetValues(names) {
+      const disp = checkDisposed();
+      if (disp) return disp;
+      const targets = names ? [...names] : validControlNames();
+      const prevBase = { ...baseValues };
+      const prevTracks = { ...tracks };
+      const execute = () => {
+        for (const name of targets) {
+          if (name in description.defaults) {
+            baseValues[name] = description.defaults[name];
+          }
+          delete tracks[name];
+        }
+      };
+      const undo = () => {
+        baseValues = { ...prevBase };
+        tracks = { ...prevTracks };
+      };
+      history.execute({
+        name: "Reset values",
+        execute,
+        undo
+      });
+      invalidateState();
+      return { ok: true };
+    },
+    applyPreset(name) {
+      const disp = checkDisposed();
+      if (disp) return disp;
+      const allPresets = mergePresets();
+      const preset = allPresets.find((p) => p.name === name);
+      if (!preset) {
+        const available = allPresets.map((p) => `"${p.name}"`).join(", ");
+        return { ok: false, message: `unknown preset "${name}"; available presets are: ${available || "none"}` };
+      }
+      const prevBase = { ...baseValues };
+      const prevTracks = { ...tracks };
+      const execute = () => {
+        for (const [k, v] of Object.entries(preset.values)) {
+          baseValues[k] = v;
+          delete tracks[k];
+        }
+      };
+      const undo = () => {
+        baseValues = { ...prevBase };
+        tracks = { ...prevTracks };
+      };
+      history.execute({
+        name: `Apply preset "${name}"`,
+        execute,
+        undo
+      });
+      invalidateState();
+      return { ok: true };
+    },
+    savePreset(name) {
+      const disp = checkDisposed();
+      if (disp) return disp;
+      if (!name || !name.trim()) {
+        return { ok: false, message: "preset name cannot be empty" };
+      }
+      const trimmed = name.trim();
+      const currentValues = valuesAtTime(playheadTime, baseValues, tracks);
+      const prevSaved = [...savedPresets];
+      const execute = () => {
+        const next = savedPresets.filter((p) => p.name !== trimmed);
+        next.push({ name: trimmed, values: { ...currentValues } });
+        savedPresets = next;
+      };
+      const undo = () => {
+        savedPresets = [...prevSaved];
+      };
+      history.execute({
+        name: `Save preset "${trimmed}"`,
+        execute,
+        undo
+      });
+      invalidateState();
+      return { ok: true };
+    },
+    setKeyframe(name, time, value, easing) {
+      const disp = checkDisposed();
+      if (disp) return disp;
+      const validNames = validControlNames();
+      if (!validNames.includes(name)) {
+        return { ok: false, message: `there is no control "${name}"; the controls are ${validNames.join(", ")}` };
+      }
+      if (typeof time !== "number" || !Number.isFinite(time) || time < 0) {
+        return { ok: false, message: "keyframe time must be a finite number >= 0" };
+      }
+      if (easing !== void 0 && !isAnimationEasing(easing)) {
+        return { ok: false, message: `invalid easing: ${String(easing)}` };
+      }
+      const targetValue = value !== void 0 ? value : valuesAtTime(time, baseValues, tracks)[name];
+      const errors = effectValueErrors(description, { [name]: targetValue });
+      if (errors.length > 0) {
+        return { ok: false, message: valueErrorMessage(errors) };
+      }
+      const prevTrack = tracks[name] ? [...tracks[name]] : void 0;
+      const execute = () => {
+        const track = prevTrack ? [...prevTrack] : [];
+        const idx = track.findIndex((kf2) => kf2.time === time);
+        const kf = {
+          time,
+          value: targetValue,
+          ...easing !== void 0 ? { easing } : {}
+        };
+        if (idx >= 0) {
+          track[idx] = kf;
+        } else {
+          track.push(kf);
+          track.sort((a, b) => a.time - b.time);
+        }
+        tracks[name] = track;
+      };
+      const undo = () => {
+        if (prevTrack === void 0) {
+          delete tracks[name];
+        } else {
+          tracks[name] = [...prevTrack];
+        }
+      };
+      history.execute({
+        name: `Set keyframe on ${name}`,
+        execute,
+        undo
+      });
+      invalidateState();
+      return { ok: true };
+    },
+    removeKeyframe(name, time) {
+      const disp = checkDisposed();
+      if (disp) return disp;
+      const validNames = validControlNames();
+      if (!validNames.includes(name)) {
+        return { ok: false, message: `there is no control "${name}"; the controls are ${validNames.join(", ")}` };
+      }
+      const track = tracks[name];
+      if (!track || !track.some((kf) => kf.time === time)) {
+        const times = track?.map((kf) => `${kf.time}`).join(", ");
+        return {
+          ok: false,
+          message: times ? `no keyframe at ${time} ms on control "${name}"; its keyframes are at ${times} ms` : `control "${name}" has no keyframes`
+        };
+      }
+      const prevTrack = [...track];
+      const execute = () => {
+        const next = tracks[name].filter((kf) => kf.time !== time);
+        if (next.length === 0) {
+          delete tracks[name];
+        } else {
+          tracks[name] = next;
+        }
+      };
+      const undo = () => {
+        tracks[name] = [...prevTrack];
+      };
+      history.execute({
+        name: `Remove keyframe on ${name}`,
+        execute,
+        undo
+      });
+      invalidateState();
+      return { ok: true };
+    },
+    clearTrack(name) {
+      const disp = checkDisposed();
+      if (disp) return disp;
+      const validNames = validControlNames();
+      if (!validNames.includes(name)) {
+        return { ok: false, message: `there is no control "${name}"; the controls are ${validNames.join(", ")}` };
+      }
+      const prevTrack = tracks[name] ? [...tracks[name]] : void 0;
+      if (!prevTrack || prevTrack.length === 0) {
+        const animated = Object.keys(tracks).filter((k) => tracks[k]?.length);
+        return {
+          ok: false,
+          message: `control "${name}" is not animated, so there is nothing to clear; ${animated.length ? `the animated controls are ${animated.join(", ")}` : "no control is animated"}`
+        };
+      }
+      const currentValue = valuesAtTime(playheadTime, baseValues, tracks)[name];
+      const prevBase = baseValues[name];
+      const execute = () => {
+        delete tracks[name];
+        baseValues[name] = currentValue;
+      };
+      const undo = () => {
+        tracks[name] = [...prevTrack];
+        baseValues[name] = prevBase;
+      };
+      history.execute({
+        name: `Clear animation on ${name}`,
+        execute,
+        undo
+      });
+      invalidateState();
+      return { ok: true };
+    },
+    setTiming(timing) {
+      const disp = checkDisposed();
+      if (disp) return disp;
+      if (timing.duration !== void 0 && (!(timing.duration > 0) || !Number.isFinite(timing.duration))) {
+        return { ok: false, message: "duration must be a finite number > 0" };
+      }
+      const prevDuration = duration;
+      const prevLoop = loop;
+      const prevTime = playheadTime;
+      const execute = () => {
+        if (timing.duration !== void 0) {
+          duration = timing.duration;
+          if (playheadTime > duration) playheadTime = duration;
+        }
+        if (timing.loop !== void 0) {
+          loop = timing.loop;
+        }
+      };
+      const undo = () => {
+        duration = prevDuration;
+        loop = prevLoop;
+        playheadTime = prevTime;
+      };
+      history.execute({
+        name: "Set timing",
+        execute,
+        undo
+      });
+      invalidateState();
+      return { ok: true };
+    },
+    play() {
+      if (disposed || playing) return;
+      playing = true;
+      lastScheduleTime = null;
+      cancelSchedule = scheduleFn((now) => {
+        if (!playing) return;
+        const delta = lastScheduleTime === null ? 0 : Math.max(0, now - lastScheduleTime);
+        lastScheduleTime = now;
+        let nextTime = playheadTime + delta;
+        if (nextTime >= duration) {
+          if (loop) {
+            nextTime = duration > 0 ? nextTime % duration : 0;
+          } else {
+            nextTime = duration;
+            pauseInternal();
+          }
+        }
+        seekInternal(nextTime);
+      });
+      invalidateState();
+    },
+    pause() {
+      pauseInternal();
+    },
+    seek(time) {
+      if (disposed) return;
+      seekInternal(time);
+    },
+    undo() {
+      if (disposed) return false;
+      const changed = history.undo();
+      if (changed) invalidateState();
+      return changed;
+    },
+    redo() {
+      if (disposed) return false;
+      const changed = history.redo();
+      if (changed) invalidateState();
+      return changed;
+    },
+    async createPreview(opts) {
+      if (disposed) {
+        throw new EffectDisposedError(effectId);
+      }
+      const renderer = await provider.createRenderer(effectId, opts);
+      livePreviews.add(renderer);
+      const preview = {
+        effectId: renderer.effectId,
+        width: renderer.width,
+        height: renderer.height,
+        depth: renderer.depth,
+        render: async (req) => {
+          if (disposed) throw new EffectDisposedError(effectId);
+          const effectiveValues = req.values ?? valuesAtTime(req.time, baseValues, tracks);
+          const pixels = await renderer.render({
+            ...req,
+            values: effectiveValues
+          });
+          if (compiled !== true) {
+            compiled = true;
+            invalidateState();
+          }
+          return pixels;
+        },
+        dispose: () => {
+          livePreviews.delete(renderer);
+          renderer.dispose();
+        }
+      };
+      return preview;
+    },
+    exportDocument() {
+      const currentValues = valuesAtTime(playheadTime, baseValues, tracks);
+      return {
+        version: 1,
+        providerId: provider.id,
+        effectId,
+        name: initialDoc?.name ?? description.name,
+        values: { ...currentValues },
+        tracks: JSON.parse(JSON.stringify(tracks)),
+        presets: JSON.parse(JSON.stringify(savedPresets)),
+        duration,
+        loop
+      };
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      pauseInternal();
+      listeners.clear();
+      for (const p of livePreviews) {
+        try {
+          p.dispose();
+        } catch {
+        }
+      }
+      livePreviews.clear();
+    }
+  };
+  return session;
+}
+
 // src/effects/fake.ts
 var HEX = "^#[0-9a-fA-F]{6}$";
 var colour = (description) => ({ type: "string", pattern: HEX, description });
@@ -426,12 +1237,14 @@ function maskResult(out, mask, source, id) {
   }
 }
 function createFakeEffectProvider(options = {}) {
+  const supportsAuthoring = options.authoring ?? true;
   const capabilities = {
     supportsWorker: false,
     supportsFloat: true,
     supportsMask: true,
     supportsHostImages: false,
     supportsVector: true,
+    supportsAuthoring,
     maxSize: 8192,
     ...options.capabilities
   };
@@ -501,7 +1314,10 @@ function createFakeEffectProvider(options = {}) {
         duration: ms + Math.max(0, ids.length - 1) * stagger,
         loop: false
       };
-    }
+    },
+    ...supportsAuthoring ? {
+      openAuthoring: (from) => createEffectAuthoringSession(from, { provider })
+    } : {}
   };
   return provider;
 }
@@ -559,6 +1375,11 @@ function effectSamplePicture(width, height, variant = 0) {
   }
   return p;
 }
+function effectSampleInputs(description, size) {
+  const inputs = {};
+  for (const input2 of description.inputs) if (input2.kind === "image") inputs[input2.name] = effectSamplePicture(size.width, size.height, input2.name === "to" ? 1 : 0);
+  return inputs;
+}
 function renderEffectThumbnail(provider, effect, size = { width: 96, height: 54 }) {
   let cache = thumbnails.get(provider);
   if (!cache) thumbnails.set(provider, cache = /* @__PURE__ */ new Map());
@@ -579,8 +1400,7 @@ async function renderThumbnail(provider, effect, size) {
   const renderer = await provider.createRenderer(d.id, size);
   try {
     const time = d.duration ? d.duration / 2 : 1e3;
-    const inputs = {};
-    for (const input2 of d.inputs) if (input2.kind === "image") inputs[input2.name] = effectSamplePicture(size.width, size.height, input2.name === "to" ? 1 : 0);
+    const inputs = effectSampleInputs(d, size);
     return await renderer.render({ time, inputs, ...d.uses.includes("transition") ? { progress: 0.5 } : {} });
   } finally {
     renderer.dispose();
@@ -595,6 +1415,390 @@ function groupEffectsByCategory(effects) {
   }
   return [...groups].map(([category, list]) => ({ category, effects: list }));
 }
+
+// src/effects/authoring-tools.ts
+var ANNOTATIONS = {
+  read: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  write: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+  writeIdempotent: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  destructive: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false }
+};
+var object = (properties, required = []) => ({
+  type: "object",
+  properties,
+  ...required.length ? { required } : {},
+  additionalProperties: false
+});
+var EASING_SCHEMA = {
+  description: 'Easing into the next keyframe: a preset name, or a curve { "type": "cubic-bezier", x1, y1, x2, y2 }, { "type": "spring", stiffness, damping, mass, velocity } or { "type": "elastic", amplitude, period, mode }. Default: linear.',
+  anyOf: [
+    { type: "string", enum: [...ANIMATION_EASING_PRESETS] },
+    object(
+      {
+        type: { type: "string", enum: ["cubic-bezier", "spring", "elastic"], description: "Curve kind." },
+        x1: { type: "number", description: "cubic-bezier: out handle x (0\u20131)." },
+        y1: { type: "number", description: "cubic-bezier: out handle y." },
+        x2: { type: "number", description: "cubic-bezier: in handle x (0\u20131)." },
+        y2: { type: "number", description: "cubic-bezier: in handle y." },
+        stiffness: { type: "number", exclusiveMinimum: 0, description: "spring: default 170." },
+        damping: { type: "number", minimum: 0, description: "spring: default 26, lower bounces more." },
+        mass: { type: "number", exclusiveMinimum: 0, description: "spring: default 1." },
+        velocity: { type: "number", description: "spring: starting speed (default 0)." },
+        amplitude: { type: "number", minimum: 0, description: "elastic: overshoot (default 1)." },
+        period: { type: "number", exclusiveMinimum: 0, description: "elastic: fraction of the length (default 0.3)." },
+        mode: { type: "string", enum: ["out", "in", "in-out"], description: "elastic: default out." }
+      },
+      ["type"]
+    )
+  ]
+};
+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 = options?.id ?? "effect-authoring";
+  const namespace = options?.namespace;
+  const title = options?.title ?? "Effect authoring";
+  const description = options?.description ?? "Author shaders and procedural effects, inspect parameters, adjust values, and manage keyframe animations.";
+  const skill = options?.skill ?? "pixerate-effect-authoring";
+  const requireSession = () => {
+    const s = host.session();
+    if (!s) throw new Error(NO_SESSION);
+    return s;
+  };
+  const describeTool = {
+    name: "effect_authoring_describe",
+    title: "Describe open effect",
+    description: "Describes the effect currently open for authoring: name, kind, source language, controls schema and current values, presets, animated tracks with keyframe counts, duration, loop, and compile issues.",
+    inputSchema: object({}),
+    annotations: { title: "Describe open effect", ...ANNOTATIONS.read },
+    handler: () => {
+      const session = requireSession();
+      const state = session.getState();
+      return {
+        name: state.description.name,
+        kind: state.description.kind,
+        sourceLanguage: state.sourceLanguage,
+        controls: effectParameterFields(state.description),
+        values: state.values,
+        presets: state.description.presets?.map((p) => p.name) ?? [],
+        tracks: Object.entries(state.tracks).map(([control, track]) => ({
+          control,
+          keyframes: track.length
+        })),
+        duration: state.duration,
+        loop: state.loop,
+        issues: state.issues
+      };
+    }
+  };
+  const getSourceTool = {
+    name: "effect_authoring_get_source",
+    title: "Get effect source code",
+    description: "Gets the shader or script source code and language of the currently open effect. Refused if the effect does not use source code.",
+    inputSchema: object({}),
+    annotations: { title: "Get effect source code", ...ANNOTATIONS.read },
+    handler: () => {
+      const session = requireSession();
+      const state = session.getState();
+      if (state.sourceLanguage === null || state.source === null) {
+        throw new Error(
+          `The currently open effect (${state.description.name}) does not use shader or script source code.`
+        );
+      }
+      return { language: state.sourceLanguage, source: state.source };
+    }
+  };
+  const setSourceTool = {
+    name: "effect_authoring_set_source",
+    title: "Set effect source code",
+    description: "Replaces the shader or script source code of the currently open effect and recompiles it. Returns any compile issues.",
+    inputSchema: object(
+      {
+        source: { type: "string", description: "The new shader or script source code to compile and apply." }
+      },
+      ["source"]
+    ),
+    annotations: { title: "Set effect source code", ...ANNOTATIONS.write },
+    handler: async (args) => {
+      const session = requireSession();
+      if (!session.setSource) {
+        throw new Error("The currently open session does not support setting source code.");
+      }
+      const res = await session.setSource(args.source);
+      if (!res.ok) throw new Error(res.message);
+      return { issues: res.issues };
+    }
+  };
+  const setValuesTool = {
+    name: "effect_authoring_set_values",
+    title: "Set effect control values",
+    description: "Sets one or more control values on the currently open effect at the current playhead time. All-or-nothing: if any control name or value is invalid, no values are changed. One undo step.",
+    inputSchema: object(
+      {
+        values: {
+          type: "object",
+          description: 'Map of control names to their new values (numbers, booleans, "#rrggbb" colors, vectors).'
+        }
+      },
+      ["values"]
+    ),
+    annotations: { title: "Set effect control values", ...ANNOTATIONS.writeIdempotent },
+    handler: (args) => {
+      const session = requireSession();
+      const res = session.setValues(args.values);
+      if (!res.ok) throw new Error(res.message);
+      return { values: session.getState().values };
+    }
+  };
+  const resetValuesTool = {
+    name: "effect_authoring_reset_values",
+    title: "Reset effect control values",
+    description: "Resets specified controls (or all controls if names is omitted) to their default values. One undo step.",
+    inputSchema: object({
+      names: {
+        type: "array",
+        items: { type: "string" },
+        description: "Names of the controls to reset. If omitted, resets all controls to their defaults."
+      }
+    }),
+    annotations: { title: "Reset effect control values", ...ANNOTATIONS.writeIdempotent },
+    handler: (args) => {
+      const session = requireSession();
+      const res = session.resetValues(args.names);
+      if (!res.ok) throw new Error(res.message);
+      return { values: session.getState().values };
+    }
+  };
+  const applyPresetTool = {
+    name: "effect_authoring_apply_preset",
+    title: "Apply effect preset",
+    description: "Applies a saved or built-in preset by name, setting its values as one undo step.",
+    inputSchema: object(
+      {
+        name: { type: "string", description: "Name of the preset to apply." }
+      },
+      ["name"]
+    ),
+    annotations: { title: "Apply effect preset", ...ANNOTATIONS.write },
+    handler: (args) => {
+      const session = requireSession();
+      const res = session.applyPreset(args.name);
+      if (!res.ok) throw new Error(res.message);
+      return { values: session.getState().values };
+    }
+  };
+  const savePresetTool = {
+    name: "effect_authoring_save_preset",
+    title: "Save effect preset",
+    description: "Saves the current values as a preset under the given name (or updates an existing preset with that name). One undo step.",
+    inputSchema: object(
+      {
+        name: { type: "string", description: "Name for the preset." }
+      },
+      ["name"]
+    ),
+    annotations: { title: "Save effect preset", ...ANNOTATIONS.write },
+    handler: (args) => {
+      const session = requireSession();
+      const res = session.savePreset(args.name);
+      if (!res.ok) throw new Error(res.message);
+      return { name: args.name, values: session.getState().values };
+    }
+  };
+  const setKeyframeTool = {
+    name: "effect_authoring_set_keyframe",
+    title: "Set effect keyframe",
+    description: "Adds or updates a keyframe on a control track at a specific time in milliseconds. If value is omitted, uses the current resolved value of the control at that time. One undo step.",
+    inputSchema: object(
+      {
+        control: { type: "string", description: "Name of the control to animate." },
+        time: { type: "number", minimum: 0, description: "Time in milliseconds from the start of the effect." },
+        value: { description: "Value at this keyframe. If omitted, captures the control value at that time." },
+        easing: EASING_SCHEMA
+      },
+      ["control", "time"]
+    ),
+    annotations: { title: "Set effect keyframe", ...ANNOTATIONS.writeIdempotent },
+    handler: (args) => {
+      const session = requireSession();
+      const res = session.setKeyframe(
+        args.control,
+        args.time,
+        args.value,
+        args.easing
+      );
+      if (!res.ok) throw new Error(res.message);
+      const track = session.getState().tracks[args.control];
+      return { control: args.control, keyframes: track ?? [] };
+    }
+  };
+  const removeKeyframeTool = {
+    name: "effect_authoring_remove_keyframe",
+    title: "Remove effect keyframe",
+    description: "Removes a keyframe at the exact time in milliseconds for the specified control. One undo step.",
+    inputSchema: object(
+      {
+        control: { type: "string", description: "Name of the control." },
+        time: { type: "number", minimum: 0, description: "Time in milliseconds of the keyframe to remove." }
+      },
+      ["control", "time"]
+    ),
+    annotations: { title: "Remove effect keyframe", ...ANNOTATIONS.write },
+    handler: (args) => {
+      const session = requireSession();
+      const res = session.removeKeyframe(args.control, args.time);
+      if (!res.ok) throw new Error(res.message);
+      const track = session.getState().tracks[args.control];
+      return { control: args.control, keyframes: track ?? [] };
+    }
+  };
+  const clearTrackTool = {
+    name: "effect_authoring_clear_track",
+    title: "Clear effect animation track",
+    description: "Removes all keyframes from an animated control. The value it has at the playhead becomes its static value. One undo step.",
+    inputSchema: object(
+      {
+        control: { type: "string", description: "Name of the control whose animation track to remove." }
+      },
+      ["control"]
+    ),
+    annotations: { title: "Clear effect animation track", ...ANNOTATIONS.destructive },
+    handler: (args) => {
+      const session = requireSession();
+      const res = session.clearTrack(args.control);
+      if (!res.ok) throw new Error(res.message);
+      return { control: args.control, value: session.getState().values[args.control] };
+    }
+  };
+  const setTimingTool = {
+    name: "effect_authoring_set_timing",
+    title: "Set effect timing",
+    description: "Sets the total duration in milliseconds and/or whether the effect loops. One undo step.",
+    inputSchema: object({
+      duration: { type: "number", minimum: 1, description: "Total duration of the effect in milliseconds (must be positive)." },
+      loop: { type: "boolean", description: "Whether playback loops back to the start when it reaches duration." }
+    }),
+    annotations: { title: "Set effect timing", ...ANNOTATIONS.writeIdempotent },
+    handler: (args) => {
+      const session = requireSession();
+      if (args.duration === void 0 && args.loop === void 0) {
+        throw new Error("Provide at least one of duration or loop to change.");
+      }
+      const res = session.setTiming({
+        duration: args.duration,
+        loop: args.loop
+      });
+      if (!res.ok) throw new Error(res.message);
+      const state = session.getState();
+      return { duration: state.duration, loop: state.loop };
+    }
+  };
+  const seekTool = {
+    name: "effect_authoring_seek",
+    title: "Seek effect playhead",
+    description: "Moves the preview playhead to a specific time in milliseconds (clamped between 0 and duration). Returns the resolved control values at that time.",
+    inputSchema: object(
+      {
+        time: { type: "number", minimum: 0, description: "Time in milliseconds to move the playhead to." }
+      },
+      ["time"]
+    ),
+    annotations: { title: "Seek effect playhead", ...ANNOTATIONS.writeIdempotent },
+    handler: (args) => {
+      const session = requireSession();
+      if (typeof args.time !== "number" || !Number.isFinite(args.time) || args.time < 0) {
+        throw new Error("time must be a finite non-negative number.");
+      }
+      session.seek(args.time);
+      const state = session.getState();
+      return { time: state.time, values: state.values };
+    }
+  };
+  const undoTool = {
+    name: "effect_authoring_undo",
+    title: "Undo effect authoring edit",
+    description: "Undoes the most recent edit in the authoring session.",
+    inputSchema: object({}),
+    annotations: { title: "Undo effect authoring edit", ...ANNOTATIONS.write },
+    handler: () => {
+      const session = requireSession();
+      const changed = session.undo();
+      const state = session.getState();
+      return { changed, canUndo: state.canUndo, canRedo: state.canRedo };
+    }
+  };
+  const redoTool = {
+    name: "effect_authoring_redo",
+    title: "Redo effect authoring edit",
+    description: "Redoes the most recently undone edit in the authoring session.",
+    inputSchema: object({}),
+    annotations: { title: "Redo effect authoring edit", ...ANNOTATIONS.write },
+    handler: () => {
+      const session = requireSession();
+      const changed = session.redo();
+      const state = session.getState();
+      return { changed, canUndo: state.canUndo, canRedo: state.canRedo };
+    }
+  };
+  const viewTool = {
+    name: "effect_authoring_view",
+    title: "View effect preview image",
+    description: "Captures an image of the effect preview at the current playhead time or at a specified time in milliseconds.",
+    inputSchema: object({
+      time: { type: "number", minimum: 0, description: "Optional time in milliseconds to view the preview at. Moves playhead to this time before capturing." }
+    }),
+    annotations: { title: "View effect preview image", ...ANNOTATIONS.read },
+    handler: async (args) => {
+      const session = requireSession();
+      if (!host.capture) throw new Error("Capturing a preview image is not supported by this host.");
+      if (args.time !== void 0) {
+        if (typeof args.time !== "number" || !Number.isFinite(args.time) || args.time < 0) {
+          throw new Error("time must be a finite non-negative number.");
+        }
+        session.seek(args.time);
+      }
+      const dataUrl = await host.capture();
+      const comma = dataUrl.indexOf(",");
+      const mimeMatch = /^data:(image\/[a-z0-9.+-]+);base64,/i.exec(dataUrl);
+      const mimeType = mimeMatch ? mimeMatch[1] : "image/png";
+      const data = comma !== -1 ? dataUrl.slice(comma + 1) : dataUrl;
+      return {
+        content: [
+          { type: "image", data, mimeType },
+          { type: "text", text: `Captured effect preview at ${session.getState().time}ms.` }
+        ]
+      };
+    }
+  };
+  return {
+    id,
+    ...namespace !== void 0 ? { namespace } : {},
+    title,
+    description,
+    skill,
+    tools: () => {
+      const session = host.session();
+      const tools = [
+        describeTool,
+        getSourceTool,
+        ...session?.setSource ? [setSourceTool] : [],
+        setValuesTool,
+        resetValuesTool,
+        applyPresetTool,
+        savePresetTool,
+        setKeyframeTool,
+        removeKeyframeTool,
+        clearTrackTool,
+        setTimingTool,
+        seekTool,
+        undoTool,
+        redoTool,
+        ...host.capture ? [viewTool] : []
+      ];
+      return tools;
+    },
+    ...host.subscribe ? { subscribe: host.subscribe } : {}
+  };
+}
 export {
   EFFECT_ERROR_CODES,
   EFFECT_KINDS,
@@ -610,12 +1814,15 @@ export {
   UnknownEffectError,
   applyEffectMask,
   checkEffectProvider,
+  createEffectAuthoringSession,
+  createEffectAuthoringToolProvider,
   createEffectPixels,
   createEffectToolProvider,
   createFakeEffectProvider,
   effectControlField,
   effectFieldValue,
   effectParameterFields,
+  effectSampleInputs,
   effectSamplePicture,
   effectValueErrors,
   encodeEffectFloat,