@pixerate/flair 0.0.0-stage → 0.1.1

package/dist/editor/index.js

@@ -0,0 +1,1009 @@
+import {
+  EFFECT_CATEGORIES,
+  findEffects,
+  getEffect,
+  renderVectorEffect,
+  vectorControlDef
+} from "../chunk-MWVTQFV5.js";
+import {
+  svgMotionIssues,
+  svgView
+} from "../chunk-G5FNZDTA.js";
+import {
+  BUILTIN_UNIFORMS,
+  interpolateOklab
+} from "../chunk-HKXOHRCD.js";
+import "../chunk-EHDJ3CPJ.js";
+import {
+  realClock
+} from "../chunk-WMZQCUFJ.js";
+import {
+  checkControlValue,
+  controlValue,
+  parseControls
+} from "../chunk-J55UBNAT.js";
+
+// src/editor/timeline.ts
+var EASING_PRESETS = [
+  "linear",
+  "ease",
+  "ease-in",
+  "ease-out",
+  "ease-in-out",
+  "ease-in-back",
+  "ease-out-back",
+  "spring",
+  "hold"
+];
+var BEZIERS = {
+  ease: [0.25, 0.1, 0.25, 1],
+  "ease-in": [0.42, 0, 1, 1],
+  "ease-out": [0, 0, 0.58, 1],
+  "ease-in-out": [0.42, 0, 0.58, 1],
+  "ease-in-back": [0.36, 0, 0.66, -0.56],
+  "ease-out-back": [0.34, 1.56, 0.64, 1]
+};
+function isEasing(value) {
+  if (typeof value === "string") return EASING_PRESETS.includes(value);
+  if (!value || typeof value !== "object") return false;
+  const e = value;
+  if (e.type === "cubic-bezier") return ["x1", "y1", "x2", "y2"].every((k) => Number.isFinite(e[k]));
+  if (e.type === "spring")
+    return ["stiffness", "damping", "mass"].every((k) => e[k] === void 0 || typeof e[k] === "number" && e[k] > 0);
+  return false;
+}
+function cubicBezierAt(x1, y1, x2, y2, x) {
+  if (x <= 0) return 0;
+  if (x >= 1) return 1;
+  x1 = Math.min(1, Math.max(0, x1));
+  x2 = Math.min(1, Math.max(0, x2));
+  const bx = (t2) => 3 * x1 * t2 * (1 - t2) ** 2 + 3 * x2 * t2 * t2 * (1 - t2) + t2 ** 3;
+  const by = (t2) => 3 * y1 * t2 * (1 - t2) ** 2 + 3 * y2 * t2 * t2 * (1 - t2) + t2 ** 3;
+  const dx = (t2) => 3 * x1 * (1 - t2) ** 2 + 6 * (x2 - x1) * t2 * (1 - t2) + 3 * (1 - x2) * t2 * t2;
+  let t = x;
+  for (let i = 0; i < 8; i++) {
+    const err = bx(t) - x;
+    if (Math.abs(err) < 1e-6) return by(t);
+    const d = dx(t);
+    if (Math.abs(d) < 1e-6) break;
+    t -= err / d;
+  }
+  let lo = 0;
+  let hi = 1;
+  t = x;
+  for (let i = 0; i < 40; i++) {
+    if (bx(t) < x) lo = t;
+    else hi = t;
+    t = (lo + hi) / 2;
+  }
+  return by(t);
+}
+function springAt(easing, u, durationMs) {
+  const k = easing.stiffness ?? 170;
+  const c = easing.damping ?? 26;
+  const m = easing.mass ?? 1;
+  const w0 = Math.sqrt(k / m);
+  const zeta = c / (2 * Math.sqrt(k * m));
+  const t = u * Math.max(durationMs / 1e3, 0.6);
+  if (zeta < 1) {
+    const wd = w0 * Math.sqrt(1 - zeta * zeta);
+    return 1 - Math.exp(-zeta * w0 * t) * (Math.cos(wd * t) + zeta * w0 / wd * Math.sin(wd * t));
+  }
+  return 1 - Math.exp(-w0 * t) * (1 + w0 * t);
+}
+function evaluateEasing(easing, u, durationMs = 1e3) {
+  if (u <= 0) return 0;
+  if (u >= 1) return 1;
+  if (!easing || easing === "linear") return u;
+  if (easing === "hold") return 0;
+  if (easing === "spring") return springAt({ type: "spring" }, u, durationMs);
+  if (typeof easing === "string") {
+    const b = BEZIERS[easing];
+    return b ? cubicBezierAt(b[0], b[1], b[2], b[3], u) : u;
+  }
+  if (easing.type === "spring") return springAt(easing, u, durationMs);
+  return cubicBezierAt(easing.x1, easing.y1, easing.x2, easing.y2, u);
+}
+function interpolateControlValue(control, a, b, t) {
+  if (typeof a === "number" && typeof b === "number") {
+    const v = a + (b - a) * t;
+    return control?.type === "int" ? Math.round(v) : v;
+  }
+  if (Array.isArray(a) && Array.isArray(b) && a.length === b.length) {
+    if (control?.color && a.length >= 3) {
+      const rgb = interpolateOklab(a.slice(0, 3), b.slice(0, 3), t);
+      const out = rgb.map((c) => Math.min(1, Math.max(0, c)));
+      return a.length === 4 ? [...out, a[3] + (b[3] - a[3]) * t] : out;
+    }
+    return a.map((v, i) => v + (b[i] - v) * t);
+  }
+  return t < 0.5 ? a : b;
+}
+function evaluateTrack(track, time, control) {
+  if (!track || track.enabled === false || track.keyframes.length === 0) return void 0;
+  const keys = track.keyframes;
+  if (time <= keys[0].time) return keys[0].value;
+  const last = keys[keys.length - 1];
+  if (time >= last.time) return last.value;
+  let i = 0;
+  while (i < keys.length - 2 && keys[i + 1].time <= time) i++;
+  const from = keys[i];
+  const to = keys[i + 1];
+  const span = to.time - from.time;
+  const u = span > 0 ? (time - from.time) / span : 1;
+  return interpolateControlValue(control, from.value, to.value, evaluateEasing(from.easing, u, span));
+}
+function normalizeKeyframes(keyframes) {
+  const byTime = /* @__PURE__ */ new Map();
+  for (const k of keyframes) byTime.set(Math.round(k.time * 1e3) / 1e3, { ...k, time: Math.round(k.time * 1e3) / 1e3 });
+  return [...byTime.values()].sort((a, b) => a.time - b.time);
+}
+function keyframeTimes(tracks) {
+  return [...new Set(Object.values(tracks).flatMap((t) => t.keyframes.map((k) => k.time)))].sort((a, b) => a - b);
+}
+
+// src/editor/document.ts
+var DEFAULT_SHADER = `// A new effect: edit me.
+uniform vec3 uColorA;  // @control color default=#6366F1 label="Colour A"
+uniform vec3 uColorB;  // @control color default=#EC4899 label="Colour B"
+uniform float uSpeed;  // @control min=0 max=4 default=1 label="Speed"
+
+void mainImage(out vec4 fragColor, in vec2 fragCoord) {
+  vec2 uv = fragCoord / iResolution.xy;
+  float t = 0.5 + 0.5 * sin(uv.x * 3.0 + iTime * uSpeed);
+  fragColor = vec4(mix(uColorA, uColorB, t), 1.0);
+}
+`;
+var DEFAULT_DURATION = 5e3;
+function createEffectDocument(from) {
+  if (from === void 0) return blankDocument("Untitled effect", DEFAULT_SHADER);
+  if (typeof from === "object" && !("kind" in from)) return blankDocument(from.name ?? "Untitled effect", from.source);
+  const effect = typeof from === "string" ? getEffect(from) : from;
+  if (!effect) throw new Error(`There is no effect "${String(from)}" in the catalog.`);
+  return {
+    version: 1,
+    name: effect.name,
+    basedOn: effect.id,
+    effect: effect.kind === "shader" ? { kind: "shader", source: effect.source } : { kind: "vector", motion: structuredClone(effect.motion), controls: effect.controls.map((c) => ({ ...c })), hold: effect.hold },
+    values: {},
+    tracks: {},
+    duration: effect.kind === "shader" && effect.loop ? Math.round(effect.loop * 1e3) : DEFAULT_DURATION,
+    loop: true,
+    presets: (effect.presets ?? []).map((p) => ({ name: p.name, values: { ...p.values } }))
+  };
+}
+function blankDocument(name, source) {
+  return { version: 1, name, effect: { kind: "shader", source }, values: {}, tracks: {}, duration: DEFAULT_DURATION, loop: true, presets: [] };
+}
+function documentControls(doc) {
+  if (doc.effect.kind === "shader") return parseControls(doc.effect.source);
+  return doc.effect.controls.map((c, i) => vectorControlDef(c, i + 1));
+}
+function valuesAt(doc, time, controls = documentControls(doc)) {
+  const out = {};
+  for (const control of controls) {
+    const tracked = evaluateTrack(doc.tracks[control.name], time, control);
+    out[control.name] = tracked ?? controlValue(control, doc.values);
+  }
+  return out;
+}
+function motionAt(doc, time) {
+  if (doc.effect.kind !== "vector") return void 0;
+  const base = doc.basedOn ? getEffect(doc.basedOn) : void 0;
+  const derived = base?.kind === "vector" ? base.derived : void 0;
+  return renderVectorEffect({ motion: doc.effect.motion, controls: doc.effect.controls, derived }, valuesAt(doc, time));
+}
+function documentIssues(doc) {
+  const issues = [];
+  if (!(doc.duration > 0)) issues.push("`duration` must be above 0 ms");
+  if (doc.effect.kind === "shader" && !/void\s+mainImage\s*\(/.test(doc.effect.source))
+    issues.push("the shader needs `void mainImage(out vec4 fragColor, in vec2 fragCoord)`");
+  const controls = new Map(documentControls(doc).map((c) => [c.name, c]));
+  const check = (where, name, value) => {
+    const control = controls.get(name);
+    if (!control) return void issues.push(`${where}: there is no control "${name}"`);
+    const result = checkControlValue(control, value);
+    if (!result.ok) issues.push(`${where}: ${result.message}`);
+  };
+  for (const [name, value] of Object.entries(doc.values)) check("values", name, value);
+  for (const [name, track] of Object.entries(doc.tracks)) {
+    track.keyframes.forEach((k, i) => {
+      const where = `tracks.${name}[${i}]`;
+      if (!(k.time >= 0)) issues.push(`${where}: \`time\` must be 0 or more`);
+      if (k.easing !== void 0 && !isEasing(k.easing)) issues.push(`${where}: unknown easing`);
+      check(where, name, k.value);
+    });
+  }
+  for (const preset of doc.presets) for (const [name, value] of Object.entries(preset.values)) check(`preset "${preset.name}"`, name, value);
+  if (doc.effect.kind === "vector") {
+    const motion = motionAt(doc, 0);
+    issues.push(...svgMotionIssues(motion));
+    if (/\{\{[^}]+\}\}/.test(JSON.stringify(motion))) issues.push("the picture has placeholders no control fills");
+  }
+  return issues;
+}
+function parseEffectDocument(input) {
+  let raw = input;
+  if (typeof input === "string") {
+    try {
+      raw = JSON.parse(input);
+    } catch (e) {
+      return { ok: false, errors: [`not JSON: ${e.message}`] };
+    }
+  }
+  const errors = [];
+  const o = raw ?? {};
+  if (o.version !== 1) errors.push("`version` must be 1");
+  if (typeof o.name !== "string") errors.push("`name` must be a string");
+  const effect = o.effect;
+  if (!effect || effect.kind !== "shader" && effect.kind !== "vector") errors.push('`effect.kind` must be "shader" or "vector"');
+  else if (effect.kind === "shader" && typeof effect.source !== "string") errors.push("`effect.source` must be a string");
+  else if (effect.kind === "vector") {
+    const v = effect;
+    if (!v.motion || typeof v.motion.svg !== "string") errors.push("`effect.motion.svg` must be a string");
+    if (!Array.isArray(v.controls)) errors.push("`effect.controls` must be a list");
+  }
+  const isRecord = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+  if (o.values !== void 0 && !isRecord(o.values)) errors.push("`values` must be an object");
+  if (o.tracks !== void 0 && !isRecord(o.tracks)) errors.push("`tracks` must be an object");
+  for (const [name, track] of Object.entries(isRecord(o.tracks) ? o.tracks : {}))
+    if (!track || !Array.isArray(track.keyframes)) errors.push(`\`tracks.${name}.keyframes\` must be a list`);
+  if (o.presets !== void 0 && !Array.isArray(o.presets)) errors.push("`presets` must be a list");
+  if (errors.length) return { ok: false, errors };
+  const tracks = Object.fromEntries(
+    Object.entries(o.tracks ?? {}).map(([k, t]) => [k, { ...t, keyframes: normalizeKeyframes(t.keyframes) }])
+  );
+  return {
+    ok: true,
+    document: {
+      version: 1,
+      name: o.name,
+      basedOn: typeof o.basedOn === "string" ? o.basedOn : void 0,
+      effect: o.effect,
+      values: o.values ?? {},
+      tracks,
+      duration: typeof o.duration === "number" && o.duration > 0 ? o.duration : DEFAULT_DURATION,
+      loop: o.loop !== false,
+      presets: o.presets ?? []
+    }
+  };
+}
+
+// src/editor/editor.ts
+import { createCommandRegistry, createHistoryCommands } from "@pixerate/editor/commands";
+import { createHistoryManager, HistoryManager } from "@pixerate/editor/history";
+
+// src/editor/commands.ts
+function done(result) {
+  if (!result.ok) throw new Error(result.message);
+  return result;
+}
+var easingSchema = {
+  description: `An easing preset (${EASING_PRESETS.join(", ")}) or {"type":"cubic-bezier","x1","y1","x2","y2"} or {"type":"spring","stiffness","damping","mass"}.`
+};
+var valueSchema = {
+  description: 'A control value: a number (float, int), true/false (bool), an array of numbers (vec2\u2013vec4; colours 0\u20131), a "#RRGGBB" colour, or an image URL (sampler2D).'
+};
+function describeEditor(editor) {
+  const state = editor.getState();
+  const doc = state.document;
+  return {
+    name: doc.name,
+    basedOn: doc.basedOn,
+    kind: doc.effect.kind,
+    ...doc.effect.kind === "shader" ? { source: doc.effect.source } : { motion: doc.effect.motion, vectorControls: doc.effect.controls },
+    controls: state.controls.map((c) => ({
+      name: c.name,
+      type: c.type,
+      label: c.label,
+      ...c.color && { color: true },
+      ...c.type !== "bool" && c.type !== "sampler2D" && { min: c.min, max: c.max, step: c.step },
+      default: c.default
+    })),
+    values: state.values,
+    tracks: doc.tracks,
+    presets: doc.presets.map((p) => p.name),
+    timeline: { duration: doc.duration, loop: doc.loop, time: state.time, playing: state.playing, recording: state.recording },
+    issues: state.issues,
+    compile: state.compile,
+    history: { canUndo: state.history.canUndo, canRedo: state.history.canRedo }
+  };
+}
+function effectCommands() {
+  return [
+    {
+      id: "effect.describe",
+      label: "Describe effect",
+      group: "Effect",
+      description: "The effect being edited: its source (or picture), controls, values at the playhead, keyframes, presets, timeline, issues and compile errors.",
+      readOnly: true,
+      run: (editor) => describeEditor(editor)
+    },
+    {
+      id: "catalog.search",
+      label: "Search effects",
+      group: "Catalog",
+      description: "Searches the built-in effect catalog. Load one with effect.load to start from it.",
+      readOnly: true,
+      params: {
+        type: "object",
+        properties: {
+          text: { type: "string", description: "Words to look for (all must match)." },
+          category: { type: "string", enum: EFFECT_CATEGORIES },
+          kind: { type: "string", enum: ["shader", "vector"] }
+        },
+        additionalProperties: false
+      },
+      run: (_, params) => findEffects(params ?? {}).map((e) => ({ id: e.id, name: e.name, kind: e.kind, category: e.category, description: e.description, presets: e.presets?.map((p) => p.name) ?? [] }))
+    },
+    {
+      id: "effect.load",
+      label: "Load effect",
+      group: "Effect",
+      description: "Starts over from a catalog effect (by id, optionally with one of its presets), or from a shader's source.",
+      params: {
+        type: "object",
+        properties: {
+          id: { type: "string", description: "A catalog effect id (see catalog.search)." },
+          preset: { type: "string" },
+          source: { type: "string", description: "A shader source to start from instead of a catalog effect." },
+          name: { type: "string" }
+        },
+        additionalProperties: false
+      },
+      run: (editor, p) => done(p?.source !== void 0 ? editor.load({ source: p.source, name: p.name }) : editor.load(p?.id, p?.preset))
+    },
+    {
+      id: "effect.setSource",
+      label: "Set shader source",
+      group: "Effect",
+      description: "Replaces the shader's GLSL ES 3.00 source (Shadertoy-style mainImage; controls are uniforms annotated `// @control`). Compile errors show up in effect.describe once the preview has compiled it.",
+      params: { type: "object", properties: { source: { type: "string" } }, required: ["source"], additionalProperties: false },
+      run: (editor, p) => done(editor.setSource(p.source))
+    },
+    {
+      id: "effect.rename",
+      label: "Rename effect",
+      group: "Effect",
+      params: { type: "object", properties: { name: { type: "string" } }, required: ["name"], additionalProperties: false },
+      run: (editor, p) => done(editor.rename(p.name))
+    },
+    {
+      id: "values.set",
+      label: "Set values",
+      group: "Values",
+      description: "Sets control values by name, all or nothing. A keyframed control (or any, while recording) gets a keyframe at the playhead instead.",
+      params: {
+        type: "object",
+        properties: { values: { type: "object", additionalProperties: valueSchema, description: "Control name \u2192 value." } },
+        required: ["values"],
+        additionalProperties: false
+      },
+      run: (editor, p) => done(editor.setValues(p.values))
+    },
+    {
+      id: "values.reset",
+      label: "Reset values",
+      group: "Values",
+      description: "Puts controls back to their defaults: the named ones, or all.",
+      params: { type: "object", properties: { names: { type: "array", items: { type: "string" } } }, additionalProperties: false },
+      run: (editor, p) => done(editor.resetValues(p?.names))
+    },
+    {
+      id: "values.randomize",
+      label: "Randomize values",
+      group: "Values",
+      keywords: ["shuffle", "surprise", "explore"],
+      params: { type: "object", properties: { names: { type: "array", items: { type: "string" } } }, additionalProperties: false },
+      run: (editor, p) => done(editor.randomize(p?.names))
+    },
+    {
+      id: "preset.apply",
+      label: "Apply preset",
+      group: "Presets",
+      params: { type: "object", properties: { name: { type: "string" } }, required: ["name"], additionalProperties: false },
+      run: (editor, p) => done(editor.applyPreset(p.name))
+    },
+    {
+      id: "preset.save",
+      label: "Save preset",
+      group: "Presets",
+      description: "Saves the values at the playhead (all, or the named controls) as a preset.",
+      params: {
+        type: "object",
+        properties: { name: { type: "string" }, names: { type: "array", items: { type: "string" } } },
+        required: ["name"],
+        additionalProperties: false
+      },
+      run: (editor, p) => done(editor.savePreset(p.name, p.names))
+    },
+    {
+      id: "preset.delete",
+      label: "Delete preset",
+      group: "Presets",
+      params: { type: "object", properties: { name: { type: "string" } }, required: ["name"], additionalProperties: false },
+      run: (editor, p) => done(editor.deletePreset(p.name))
+    },
+    {
+      id: "keyframe.set",
+      label: "Set keyframe",
+      group: "Keyframes",
+      description: "Keyframes a control at a time (ms). Without a value, keyframes its current value there. The easing shapes the segment leaving this keyframe.",
+      params: {
+        type: "object",
+        properties: { name: { type: "string" }, time: { type: "number", minimum: 0 }, value: valueSchema, easing: easingSchema },
+        required: ["name", "time"],
+        additionalProperties: false
+      },
+      run: (editor, p) => done(editor.setKeyframe(p.name, p.time, p.value, p.easing))
+    },
+    {
+      id: "keyframe.remove",
+      label: "Delete keyframe",
+      group: "Keyframes",
+      params: { type: "object", properties: { name: { type: "string" }, time: { type: "number" } }, required: ["name", "time"], additionalProperties: false },
+      run: (editor, p) => done(editor.removeKeyframe(p.name, p.time))
+    },
+    {
+      id: "keyframe.setEasing",
+      label: "Set keyframe easing",
+      group: "Keyframes",
+      params: {
+        type: "object",
+        properties: { name: { type: "string" }, time: { type: "number" }, easing: easingSchema },
+        required: ["name", "time", "easing"],
+        additionalProperties: false
+      },
+      run: (editor, p) => done(editor.setKeyframeEasing(p.name, p.time, p.easing))
+    },
+    {
+      id: "keyframe.clear",
+      label: "Clear keyframes",
+      group: "Keyframes",
+      description: "Removes a control's keyframes; it keeps the value it has at the playhead.",
+      params: { type: "object", properties: { name: { type: "string" } }, required: ["name"], additionalProperties: false },
+      run: (editor, p) => done(editor.clearTrack(p.name))
+    },
+    {
+      id: "timeline.setTiming",
+      label: "Set timing",
+      group: "Timeline",
+      params: {
+        type: "object",
+        properties: { duration: { type: "number", exclusiveMinimum: 0, description: "Ms." }, loop: { type: "boolean" } },
+        additionalProperties: false
+      },
+      run: (editor, p) => done(editor.setTiming(p ?? {}))
+    },
+    {
+      id: "timeline.play",
+      label: "Play",
+      group: "Timeline",
+      run: (editor) => editor.play()
+    },
+    {
+      id: "timeline.pause",
+      label: "Pause",
+      group: "Timeline",
+      run: (editor) => editor.pause()
+    },
+    {
+      id: "timeline.toggle",
+      label: "Play / pause",
+      group: "Timeline",
+      shortcut: "Space",
+      run: (editor) => editor.toggle()
+    },
+    {
+      id: "timeline.seek",
+      label: "Go to time",
+      group: "Timeline",
+      params: { type: "object", properties: { time: { type: "number", minimum: 0, description: "Ms." } }, required: ["time"], additionalProperties: false },
+      run: (editor, p) => editor.seek(p.time)
+    },
+    {
+      id: "timeline.stop",
+      label: "Stop",
+      group: "Timeline",
+      run: (editor) => editor.stop()
+    },
+    {
+      id: "timeline.toggleRecording",
+      label: "Record keyframes",
+      group: "Timeline",
+      description: "While recording, changing a value keyframes it at the playhead.",
+      run: (editor) => editor.setRecording(!editor.getState().recording)
+    }
+  ];
+}
+
+// src/editor/editor.ts
+var ok = { ok: true };
+var fail = (message) => ({ ok: false, message });
+var EffectEditor = class {
+  history;
+  /** Every editing action, by id: for menus, shortcuts, a command palette and agents. */
+  commands;
+  doc;
+  controlsCache = null;
+  compileReport = null;
+  time = 0;
+  playing = false;
+  recording = false;
+  clock;
+  mergeWindowMs;
+  listeners = /* @__PURE__ */ new Set();
+  state = null;
+  unsubscribeHistory;
+  disposed = false;
+  constructor(options = {}) {
+    this.doc = options.document ?? createEffectDocument(options.from);
+    this.history = options.history ?? createHistoryManager({ maxDepth: 100 });
+    this.clock = options.clock ?? realClock;
+    this.mergeWindowMs = options.mergeWindowMs ?? 400;
+    this.commands = createCommandRegistry({ context: this });
+    this.commands.register([...createHistoryCommands(this.history), ...effectCommands()]);
+    this.unsubscribeHistory = this.history.subscribe(() => this.changed());
+  }
+  // ── Reading ────────────────────────────────────────────────────────
+  get document() {
+    return this.doc;
+  }
+  /** The current state; the same object until something changes (safe for `useSyncExternalStore`). */
+  getState() {
+    if (!this.state) {
+      const { controls, issues } = this.analysis();
+      this.state = {
+        document: this.doc,
+        controls,
+        values: valuesAt(this.doc, this.time, controls),
+        issues,
+        compile: this.doc.effect.kind === "shader" ? this.compileReport : null,
+        time: this.time,
+        playing: this.playing,
+        recording: this.recording,
+        history: this.history.getState()
+      };
+    }
+    return this.state;
+  }
+  /** Calls `listener` with the new state after every change; returns an unsubscribe function. */
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  /** The document's controls. */
+  get controls() {
+    return this.analysis().controls;
+  }
+  /** The document as JSON. */
+  toJSON() {
+    return this.doc;
+  }
+  // ── Whole documents ─────────────────────────────────────────────────
+  /** Replaces the document (one undo step). */
+  replaceDocument(next, label = "Replace effect") {
+    const parsed = parseEffectDocument(next);
+    if (!parsed.ok) return fail(parsed.errors.join("; "));
+    this.commit(label, parsed.document);
+    return ok;
+  }
+  /** Starts over from a catalog effect, a shader source, or blank (one undo step). */
+  load(from, preset) {
+    let next;
+    try {
+      next = createEffectDocument(from);
+    } catch (e) {
+      return fail(e.message);
+    }
+    if (preset) {
+      const values = next.presets.find((p) => p.name === preset)?.values;
+      if (!values) return fail(`"${next.name}" has no preset "${preset}"; it has ${next.presets.map((p) => `"${p.name}"`).join(", ") || "none"}.`);
+      next = { ...next, values: { ...values } };
+    }
+    this.compileReport = null;
+    this.commit(`Load ${next.name}`, next);
+    return ok;
+  }
+  rename(name) {
+    if (!name.trim()) return fail("A name cannot be empty.");
+    this.commit("Rename", { ...this.doc, name: name.trim() });
+    return ok;
+  }
+  // ── The effect itself ───────────────────────────────────────────────
+  /** Replaces a shader's source. Compile errors arrive later, from the renderer (see `reportCompile`). */
+  setSource(source) {
+    if (this.doc.effect.kind !== "shader") return fail("This is a vector effect; use setMotion.");
+    if (source === this.doc.effect.source) return ok;
+    this.commit("Edit source", { ...this.doc, effect: { kind: "shader", source } }, "source");
+    return ok;
+  }
+  /** Replaces a vector effect's picture (and optionally its controls). */
+  setMotion(motion, controls) {
+    if (this.doc.effect.kind !== "vector") return fail("This is a shader effect; use setSource.");
+    this.commit("Edit picture", { ...this.doc, effect: { ...this.doc.effect, motion, controls: controls ?? this.doc.effect.controls } });
+    return ok;
+  }
+  /** Called by a renderer binding with the result of compiling the current source. */
+  reportCompile(report) {
+    this.compileReport = { ok: report.ok, errors: [...report.errors] };
+    this.changed();
+  }
+  // ── Values ──────────────────────────────────────────────────────────
+  /**
+   * Sets a control's value. With a track on that control (or while
+   * recording) it sets a keyframe at the playhead instead. Quick successive
+   * changes to one control merge into one undo step.
+   */
+  setValue(name, value) {
+    const control = this.control(name);
+    if (!control) return this.unknownControl(name);
+    const check = checkControlValue(control, value);
+    if (!check.ok) return fail(check.message);
+    if (this.recording || this.doc.tracks[name]) return this.setKeyframe(name, this.time, check.value, void 0, `value:${name}`);
+    this.commit(`Set ${control.label}`, { ...this.doc, values: { ...this.doc.values, [name]: check.value } }, `value:${name}`);
+    return ok;
+  }
+  /** Sets several values in one undo step; refuses them all if any is wrong. */
+  setValues(values) {
+    const next = { ...this.doc.values };
+    const tracks = { ...this.doc.tracks };
+    for (const [name, value] of Object.entries(values)) {
+      const control = this.control(name);
+      if (!control) return this.unknownControl(name);
+      const check = checkControlValue(control, value);
+      if (!check.ok) return fail(check.message);
+      if (this.recording || tracks[name]) {
+        const keyframes = [...tracks[name]?.keyframes ?? [], { time: this.time, value: check.value }];
+        tracks[name] = { ...tracks[name], keyframes: normalizeKeyframes(keyframes) };
+      } else next[name] = check.value;
+    }
+    this.commit("Set values", { ...this.doc, values: next, tracks });
+    return ok;
+  }
+  /** Back to defaults: the named controls, or all of them (values only; tracks stay). */
+  resetValues(names) {
+    const unknown = names?.find((n) => !this.control(n));
+    if (unknown) return this.unknownControl(unknown);
+    const values = names ? Object.fromEntries(Object.entries(this.doc.values).filter(([k]) => !names.includes(k))) : {};
+    this.commit("Reset values", { ...this.doc, values });
+    return ok;
+  }
+  /** Random values in each control's range (colours anywhere), for exploring. */
+  randomize(names, random = Math.random) {
+    const values = {};
+    for (const control of this.controls) {
+      if (names ? !names.includes(control.name) : control.type === "sampler2D") continue;
+      const pick = () => {
+        const v = control.min + random() * (control.max - control.min);
+        return control.type === "int" ? Math.round(v) : +v.toFixed(3);
+      };
+      if (control.type === "bool") values[control.name] = random() < 0.5;
+      else if (control.type === "sampler2D") continue;
+      else if (control.color) values[control.name] = Array.from({ length: control.type === "vec4" ? 4 : 3 }, () => +random().toFixed(3));
+      else if (control.type === "float" || control.type === "int") values[control.name] = pick();
+      else values[control.name] = Array.from({ length: Number(control.type.slice(3)) }, pick);
+    }
+    return this.setValues(values);
+  }
+  // ── Presets ─────────────────────────────────────────────────────────
+  applyPreset(name) {
+    const preset = this.doc.presets.find((p) => p.name === name);
+    if (!preset) return fail(`There is no preset "${name}"; there are ${this.doc.presets.map((p) => `"${p.name}"`).join(", ") || "none"}.`);
+    this.commit(`Apply ${name}`, { ...this.doc, values: { ...this.doc.values, ...preset.values } });
+    return ok;
+  }
+  /** Saves the current values (all, or the named ones) as a preset, replacing one of the same name. */
+  savePreset(name, names) {
+    if (!name.trim()) return fail("A preset needs a name.");
+    const all = valuesAt(this.doc, this.time, this.controls);
+    const values = Object.fromEntries(Object.entries(all).filter(([k]) => names ? names.includes(k) : true));
+    const presets = [...this.doc.presets.filter((p) => p.name !== name), { name: name.trim(), values }];
+    this.commit(`Save preset ${name}`, { ...this.doc, presets });
+    return ok;
+  }
+  deletePreset(name) {
+    if (!this.doc.presets.some((p) => p.name === name)) return fail(`There is no preset "${name}".`);
+    this.commit(`Delete preset ${name}`, { ...this.doc, presets: this.doc.presets.filter((p) => p.name !== name) });
+    return ok;
+  }
+  // ── Keyframes ───────────────────────────────────────────────────────
+  /** Sets (or replaces) a keyframe; `value` defaults to the control's value at that time. */
+  setKeyframe(name, time, value, easing, mergeKey) {
+    const control = this.control(name);
+    if (!control) return this.unknownControl(name);
+    if (!(time >= 0)) return fail("A keyframe's time is 0 ms or more.");
+    if (easing !== void 0 && !isEasing(easing)) return fail(`Unknown easing ${JSON.stringify(easing)}.`);
+    let v;
+    if (value === void 0) v = valuesAt(this.doc, time, [control])[name];
+    else {
+      const check = checkControlValue(control, value);
+      if (!check.ok) return fail(check.message);
+      v = check.value;
+    }
+    const track = this.doc.tracks[name];
+    const existing = track?.keyframes.find((k) => Math.abs(k.time - time) < 1e-3);
+    const keyframe = { time, value: v, ...(easing ?? existing?.easing) !== void 0 && { easing: easing ?? existing?.easing } };
+    const keyframes = normalizeKeyframes([...track?.keyframes ?? [], keyframe]);
+    this.commit(`Keyframe ${control.label}`, { ...this.doc, tracks: { ...this.doc.tracks, [name]: { ...track, keyframes } } }, mergeKey);
+    return ok;
+  }
+  removeKeyframe(name, time) {
+    const track = this.doc.tracks[name];
+    const keyframes = track?.keyframes.filter((k) => Math.abs(k.time - time) >= 1e-3);
+    if (!track || keyframes.length === track.keyframes.length) return fail(`"${name}" has no keyframe at ${time} ms.`);
+    const tracks = { ...this.doc.tracks };
+    if (keyframes.length) tracks[name] = { ...track, keyframes };
+    else delete tracks[name];
+    this.commit("Delete keyframe", { ...this.doc, tracks });
+    return ok;
+  }
+  setKeyframeEasing(name, time, easing) {
+    if (!isEasing(easing)) return fail(`Unknown easing ${JSON.stringify(easing)}.`);
+    const track = this.doc.tracks[name];
+    if (!track?.keyframes.some((k) => Math.abs(k.time - time) < 1e-3)) return fail(`"${name}" has no keyframe at ${time} ms.`);
+    const keyframes = track.keyframes.map((k) => Math.abs(k.time - time) < 1e-3 ? { ...k, easing } : k);
+    this.commit("Set easing", { ...this.doc, tracks: { ...this.doc.tracks, [name]: { ...track, keyframes } } });
+    return ok;
+  }
+  /** Removes a control's track; it keeps the value it had at the playhead. */
+  clearTrack(name) {
+    if (!this.doc.tracks[name]) return fail(`"${name}" has no keyframes.`);
+    const control = this.control(name);
+    const value = control ? evaluateTrack(this.doc.tracks[name], this.time, control) : void 0;
+    const tracks = { ...this.doc.tracks };
+    delete tracks[name];
+    const values = value === void 0 ? this.doc.values : { ...this.doc.values, [name]: value };
+    this.commit("Clear keyframes", { ...this.doc, tracks, values });
+    return ok;
+  }
+  setTiming(timing) {
+    if (timing.duration !== void 0 && !(timing.duration > 0)) return fail("The duration must be above 0 ms.");
+    this.commit("Set timing", { ...this.doc, duration: timing.duration ?? this.doc.duration, loop: timing.loop ?? this.doc.loop });
+    return ok;
+  }
+  // ── Playhead ────────────────────────────────────────────────────────
+  play() {
+    if (this.playing || this.disposed) return;
+    if (!this.doc.loop && this.time >= this.doc.duration) this.time = 0;
+    this.playing = true;
+    this.changed();
+    void this.run();
+  }
+  pause() {
+    if (!this.playing) return;
+    this.playing = false;
+    this.changed();
+  }
+  toggle() {
+    if (this.playing) this.pause();
+    else this.play();
+  }
+  /** Moves the playhead (clamped to the timeline). */
+  seek(time) {
+    const t = Math.min(Math.max(0, time), this.doc.duration);
+    if (t === this.time) return;
+    this.time = t;
+    this.changed();
+  }
+  stop() {
+    this.playing = false;
+    this.time = 0;
+    this.changed();
+  }
+  /** While recording, changing a value keyframes it at the playhead. */
+  setRecording(recording) {
+    if (recording === this.recording) return;
+    this.recording = recording;
+    this.changed();
+  }
+  undo() {
+    return this.history.undo();
+  }
+  redo() {
+    return this.history.redo();
+  }
+  dispose() {
+    this.disposed = true;
+    this.playing = false;
+    this.unsubscribeHistory();
+    this.listeners.clear();
+  }
+  // ── Internals ───────────────────────────────────────────────────────
+  async run() {
+    let last = this.clock.now();
+    while (this.playing && !this.disposed) {
+      await this.clock.frame();
+      if (!this.playing || this.disposed) return;
+      const now = this.clock.now();
+      let next = this.time + (now - last);
+      last = now;
+      if (next >= this.doc.duration) {
+        if (this.doc.loop) next %= this.doc.duration;
+        else {
+          this.time = this.doc.duration;
+          this.playing = false;
+          this.changed();
+          return;
+        }
+      }
+      this.time = next;
+      this.changed();
+    }
+  }
+  analysis() {
+    if (this.controlsCache?.doc !== this.doc) {
+      this.controlsCache = { doc: this.doc, controls: documentControls(this.doc), issues: documentIssues(this.doc) };
+    }
+    return this.controlsCache;
+  }
+  control(name) {
+    return this.controls.find((c) => c.name === name);
+  }
+  unknownControl(name) {
+    return fail(`There is no control "${name}"; the controls are ${this.controls.map((c) => c.name).join(", ") || "none"}.`);
+  }
+  commit(label, next, mergeKey) {
+    const before = this.doc;
+    const command = HistoryManager.createSnapshotCommand({
+      name: label,
+      before,
+      after: next,
+      apply: (doc) => {
+        this.doc = doc;
+        if (this.time > doc.duration) this.time = doc.duration;
+        this.changed();
+      },
+      tag: mergeKey
+    });
+    if (mergeKey) this.history.executeMerged(command, { key: mergeKey, windowMs: this.mergeWindowMs });
+    else this.history.execute(command);
+  }
+  changed() {
+    this.state = null;
+    if (this.listeners.size === 0) return;
+    const state = this.getState();
+    for (const listener of [...this.listeners]) listener(state);
+  }
+};
+function createEffectEditor(options = {}) {
+  return new EffectEditor(options);
+}
+
+// src/editor/agent.ts
+import { createCommandToolProvider } from "@pixerate/editor/commands";
+function createEffectToolProvider(editor, options = {}) {
+  const base = createCommandToolProvider(editor.commands, {
+    id: options.id ?? "flair-effect",
+    namespace: options.namespace,
+    exclude: options.exclude
+  });
+  const extra = [];
+  if (options.capture) {
+    const capture = options.capture;
+    extra.push({
+      name: options.namespace ? `${options.namespace}__view_effect` : "view_effect",
+      title: "View effect",
+      description: "An image of the effect's preview as it is drawn now, to check what your changes look like.",
+      inputSchema: { type: "object", properties: {}, additionalProperties: false },
+      annotations: { readOnlyHint: true },
+      handler: async () => {
+        const url = await capture();
+        const match = url ? /^data:([^;,]+);base64,(.*)$/.exec(url) : null;
+        if (!match) return { content: [{ type: "text", text: "Nothing to show yet: the preview has not drawn a frame." }], isError: true };
+        return { content: [{ type: "image", data: match[2], mimeType: match[1] }] };
+      }
+    });
+  }
+  const baseTools = () => typeof base.tools === "function" ? base.tools() : base.tools;
+  return { id: base.id, namespace: base.namespace, subscribe: base.subscribe, tools: () => [...baseTools(), ...extra] };
+}
+function toolDefinitions(provider) {
+  const tools = typeof provider.tools === "function" ? provider.tools() : provider.tools;
+  return tools.map(({ handler: _handler, ...definition }) => definition);
+}
+async function callTool(provider, name, args = {}) {
+  const tools = typeof provider.tools === "function" ? provider.tools() : provider.tools;
+  const tool = tools.find((t) => t.name === name);
+  if (!tool) return { content: [{ type: "text", text: `There is no tool "${name}".` }], isError: true };
+  try {
+    const result = await tool.handler(args, { name, providerId: provider.id });
+    if (result && typeof result === "object" && Array.isArray(result.content)) return result;
+    if (result === void 0) return { content: [] };
+    if (typeof result === "string") return { content: [{ type: "text", text: result }] };
+    return { content: [{ type: "text", text: JSON.stringify(result) }], structuredContent: result };
+  } catch (e) {
+    return { content: [{ type: "text", text: e.message }], isError: true };
+  }
+}
+var EFFECT_AGENT_INSTRUCTIONS = `You design web visual effects in an effect editor. Work through its tools: \`list_commands\` shows every command with its parameters; \`run_command\` runs one; \`run_commands\` runs several in order.
+
+Start with \`effect.describe\` to see what is being edited. To start from something close, use \`catalog.search\` then \`effect.load\` (with a preset if one fits). Every change is one undo step; \`history.undo\` reverts a step.
+
+Shader effects are GLSL ES 3.00 fragment shaders written Shadertoy-style:
+- Define \`void mainImage(out vec4 fragColor, in vec2 fragCoord)\`; the output is opaque (alpha is ignored).
+- Built-in uniforms (do not declare them): ${BUILTIN_UNIFORMS.map((u) => `\`${u.type} ${u.name}\` (${u.doc})`).join("; ")}.
+- Declare controls as uniforms with an annotation on the same line, e.g.
+  uniform float uSpeed;  // @control min=0 max=4 default=1 label="Speed"
+  uniform vec3 uTint;    // @control color default=#77C16A label="Tint"
+  uniform bool uGrain;   // @control default=true label="Film grain"
+  uniform sampler2D uPhoto; // @control filter=linear wrap=clamp label="Photo"
+  Types: float, int, bool, vec2, vec3, vec4, sampler2D. Every uniform you declare should be a control.
+- Write float literals with a decimal point (1.0, not 1); GLSL does not convert int to float implicitly. Use \`texture()\`, not \`texture2D()\`.
+- After \`effect.setSource\`, call \`effect.describe\` and read \`compile\`: fix any errors (their line numbers match your source) before going on.
+
+Vector effects are animated SVG pictures: change their controls' values; their picture is edited with care, keeping element ids that animations refer to.
+
+Make effects that loop smoothly and read well behind content: keep motion calm unless asked otherwise, keep contrast where text may sit, and expose the few controls a designer would actually want (colours, speed, scale, intensity) with sensible ranges. Use keyframes (\`keyframe.set\`, in ms) for changes over the timeline. When you can, look at the result with \`view_effect\` and refine it.`;
+
+// src/editor/bind.ts
+function bindShaderRenderer(editor, renderer) {
+  let source;
+  renderer.pause();
+  const sync = (state) => {
+    const effect = state.document.effect;
+    if (effect.kind !== "shader") return;
+    if (effect.source !== source) {
+      source = effect.source;
+      editor.reportCompile(renderer.setSource(source));
+    }
+    renderer.setValues(state.values);
+    renderer.seek(state.time / 1e3);
+  };
+  sync(editor.getState());
+  return editor.subscribe(sync);
+}
+function bindSvgView(editor, container) {
+  let view;
+  let key;
+  const sync = (state) => {
+    const motion = motionAt(state.document, state.time);
+    if (!motion) {
+      view?.element.remove();
+      view = void 0;
+      key = void 0;
+      return;
+    }
+    const next = JSON.stringify(motion);
+    if (next !== key) {
+      key = next;
+      view?.element.remove();
+      view = svgView(motion);
+      container.appendChild(view.element);
+    }
+    view.draw(state.time);
+  };
+  sync(editor.getState());
+  const unsubscribe = editor.subscribe(sync);
+  return () => {
+    unsubscribe();
+    view?.element.remove();
+  };
+}
+export {
+  EASING_PRESETS,
+  EFFECT_AGENT_INSTRUCTIONS,
+  EffectEditor,
+  bindShaderRenderer,
+  bindSvgView,
+  callTool,
+  createEffectDocument,
+  createEffectEditor,
+  createEffectToolProvider,
+  cubicBezierAt,
+  describeEditor,
+  documentControls,
+  documentIssues,
+  effectCommands,
+  evaluateEasing,
+  evaluateTrack,
+  interpolateControlValue,
+  isEasing,
+  keyframeTimes,
+  motionAt,
+  normalizeKeyframes,
+  parseEffectDocument,
+  toolDefinitions,
+  valuesAt
+};
+//# sourceMappingURL=index.js.map