@pixerate/flair 0.1.1 → 0.3.0

package/dist/editor/index.js

@@ -3,8 +3,9 @@ import {
   findEffects,
   getEffect,
   renderVectorEffect,
-  vectorControlDef
-} from "../chunk-MWVTQFV5.js";
+  vectorControlIssues,
+  vectorEffectControls
+} from "../chunk-IWKM5FJK.js";
 import {
   svgMotionIssues,
   svgView
@@ -12,7 +13,7 @@ import {
 import {
   BUILTIN_UNIFORMS,
   interpolateOklab
-} from "../chunk-HKXOHRCD.js";
+} from "../chunk-VA74HBPK.js";
 import "../chunk-EHDJ3CPJ.js";
 import {
   realClock
@@ -21,88 +22,22 @@ import {
   checkControlValue,
   controlValue,
   parseControls
-} from "../chunk-J55UBNAT.js";
+} from "../chunk-WC3VADZC.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]
-};
+import {
+  ANIMATION_EASING_PRESETS,
+  cubicBezierAt as editorCubicBezierAt,
+  evaluateEasing as evaluateAnimationEasing,
+  isAnimationEasing
+} from "@pixerate/editor/animation";
+var EASING_PRESETS = ANIMATION_EASING_PRESETS;
+var evaluateEasing = evaluateAnimationEasing;
+var cubicBezierAt = editorCubicBezierAt;
 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);
+  if (!isAnimationEasing(value)) return false;
+  if (typeof value !== "object" || value.type !== "spring") return true;
+  return [value.stiffness, value.damping, value.mass].every((v) => v === void 0 || v > 0);
 }
 function interpolateControlValue(control, a, b, t) {
   if (typeof a === "number" && typeof b === "number") {
@@ -164,7 +99,12 @@ function createEffectDocument(from) {
     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 },
+    effect: effect.kind === "shader" ? { kind: "shader", source: effect.source } : {
+      kind: "vector",
+      motion: structuredClone(effect.motion),
+      ...effect.controls && { controls: effect.controls.map((c) => ({ ...c })) },
+      hold: effect.hold
+    },
     values: {},
     tracks: {},
     duration: effect.kind === "shader" && effect.loop ? Math.round(effect.loop * 1e3) : DEFAULT_DURATION,
@@ -177,7 +117,7 @@ function blankDocument(name, source) {
 }
 function documentControls(doc) {
   if (doc.effect.kind === "shader") return parseControls(doc.effect.source);
-  return doc.effect.controls.map((c, i) => vectorControlDef(c, i + 1));
+  return vectorEffectControls(doc.effect);
 }
 function valuesAt(doc, time, controls = documentControls(doc)) {
   const out = {};
@@ -217,7 +157,7 @@ function documentIssues(doc) {
   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));
+    issues.push(...vectorControlIssues(doc.effect.motion), ...svgMotionIssues(motion));
     if (/\{\{[^}]+\}\}/.test(JSON.stringify(motion))) issues.push("the picture has placeholders no control fills");
   }
   return issues;
@@ -241,7 +181,7 @@ function parseEffectDocument(input) {
   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");
+    if (v.controls !== void 0 && !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");
@@ -282,7 +222,7 @@ 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).'
+  description: 'A control value: a number (float, int), true/false (bool), an array of numbers (vec2\u2013vec4; colours 0\u20131), a "#RRGGBB" colour, an image URL (sampler2D), or a string (text).'
 };
 function describeEditor(editor) {
   const state = editor.getState();
@@ -291,13 +231,13 @@ function describeEditor(editor) {
     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 },
+    ...doc.effect.kind === "shader" ? { source: doc.effect.source } : { motion: doc.effect.motion, ...doc.effect.controls && { 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 },
+      ...c.type !== "bool" && c.type !== "sampler2D" && c.type !== "text" && { min: c.min, max: c.max, step: c.step },
       default: c.default
     })),
     values: state.values,
@@ -456,6 +396,29 @@ function effectCommands() {
       },
       run: (editor, p) => done(editor.setKeyframeEasing(p.name, p.time, p.easing))
     },
+    {
+      id: "keyframe.setTrack",
+      label: "Set keyframes",
+      group: "Keyframes",
+      description: "Replaces all of a control's keyframes at once (an empty list removes them). Times are ms; each easing shapes the segment leaving its keyframe.",
+      params: {
+        type: "object",
+        properties: {
+          name: { type: "string" },
+          keyframes: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: { time: { type: "number", minimum: 0 }, value: valueSchema, easing: easingSchema },
+              required: ["time", "value"]
+            }
+          }
+        },
+        required: ["name", "keyframes"],
+        additionalProperties: false
+      },
+      run: (editor, p) => done(editor.setTrack(p.name, { keyframes: p.keyframes }))
+    },
     {
       id: "keyframe.clear",
       label: "Clear keyframes",
@@ -618,7 +581,7 @@ var EffectEditor = class {
     this.commit("Edit source", { ...this.doc, effect: { kind: "shader", source } }, "source");
     return ok;
   }
-  /** Replaces a vector effect's picture (and optionally its controls). */
+  /** Replaces a vector effect's picture, whose `{{name: type …}}` placeholders declare its controls (and optionally a `controls` list). */
   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 } });
@@ -669,17 +632,17 @@ var EffectEditor = class {
     this.commit("Reset values", { ...this.doc, values });
     return ok;
   }
-  /** Random values in each control's range (colours anywhere), for exploring. */
+  /** Random values in each control's range (colours anywhere), for exploring. Images and text keep theirs. */
   randomize(names, random = Math.random) {
     const values = {};
     for (const control of this.controls) {
-      if (names ? !names.includes(control.name) : control.type === "sampler2D") continue;
+      if (names ? !names.includes(control.name) : control.type === "sampler2D" || control.type === "text") 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.type === "sampler2D" || control.type === "text") 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);
@@ -757,6 +720,33 @@ var EffectEditor = class {
     this.commit("Clear keyframes", { ...this.doc, tracks, values });
     return ok;
   }
+  /**
+   * Replaces a control's whole track (or removes it with `undefined`), one
+   * undo step. Every keyframe is checked like `setKeyframe`; values may be
+   * any form the control accepts (colours as "#RRGGBB" too).
+   */
+  setTrack(name, track) {
+    const control = this.control(name);
+    if (!control) return this.unknownControl(name);
+    const tracks = { ...this.doc.tracks };
+    if (!track || track.keyframes.length === 0) {
+      if (!tracks[name]) return ok;
+      delete tracks[name];
+      this.commit("Clear keyframes", { ...this.doc, tracks });
+      return ok;
+    }
+    const keyframes = [];
+    for (const k of track.keyframes) {
+      if (!(k.time >= 0)) return fail("A keyframe's time is 0 ms or more.");
+      if (k.easing !== void 0 && !isEasing(k.easing)) return fail(`Unknown easing ${JSON.stringify(k.easing)}.`);
+      const check = checkControlValue(control, k.value);
+      if (!check.ok) return fail(`At ${k.time} ms: ${check.message}`);
+      keyframes.push({ time: k.time, value: check.value, ...k.easing !== void 0 && { easing: k.easing } });
+    }
+    tracks[name] = { keyframes: normalizeKeyframes(keyframes), ...track.enabled === false && { enabled: false } };
+    this.commit(`Keyframes ${control.label}`, { ...this.doc, tracks });
+    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 });
@@ -872,6 +862,10 @@ function createEffectEditor(options = {}) {
 
 // src/editor/agent.ts
 import { createCommandToolProvider } from "@pixerate/editor/commands";
+import {
+  createToolRegistry,
+  toToolResult
+} from "@pixerate/editor/tools";
 function createEffectToolProvider(editor, options = {}) {
   const base = createCommandToolProvider(editor.commands, {
     id: options.id ?? "flair-effect",
@@ -898,6 +892,11 @@ function createEffectToolProvider(editor, options = {}) {
   const baseTools = () => typeof base.tools === "function" ? base.tools() : base.tools;
   return { id: base.id, namespace: base.namespace, subscribe: base.subscribe, tools: () => [...baseTools(), ...extra] };
 }
+function createEffectToolRegistry(editor, options = {}) {
+  const registry = createToolRegistry({ validateArguments: true, ...options.registry });
+  registry.register(createEffectToolProvider(editor, options));
+  return registry;
+}
 function toolDefinitions(provider) {
   const tools = typeof provider.tools === "function" ? provider.tools() : provider.tools;
   return tools.map(({ handler: _handler, ...definition }) => definition);
@@ -907,11 +906,7 @@ async function callTool(provider, name, args = {}) {
   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 };
+    return toToolResult(await tool.handler(args, { name, providerId: provider.id }));
   } catch (e) {
     return { content: [{ type: "text", text: e.message }], isError: true };
   }
@@ -932,7 +927,9 @@ Shader effects are GLSL ES 3.00 fragment shaders written Shadertoy-style:
 - 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.
+Vector effects are animated SVG pictures that declare their controls in themselves, like shader uniforms: the first \`{{name: type \u2026}}\` declares a control (types: float, int, bool, color, text; attributes as for \`@control\`, values with spaces in single quotes), and every \`{{name}}\` is replaced by its value, e.g.
+  <!-- {{title: text default='Hello' label='Title'}} {{accent: color default=#6366F1}} --><text fill="{{accent}}">{{title}}</text>
+Change their controls' values freely (a text control takes any words); edit the picture 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.`;
 
@@ -980,16 +977,114 @@ function bindSvgView(editor, container) {
     view?.element.remove();
   };
 }
+
+// src/editor/parameters.ts
+import {
+  ParametersController,
+  rgba01ToHex
+} from "@pixerate/editor/parameters";
+function parameterFieldFor(control, options = {}) {
+  const base = { id: control.name, label: control.label };
+  switch (control.type) {
+    case "bool":
+      return { ...base, type: "boolean", default: control.default === true };
+    case "int":
+      return { ...base, type: "int", min: control.min, max: control.max, step: Math.max(1, Math.round(control.step)), default: Number(control.default) };
+    case "float":
+      return { ...base, type: "number", min: control.min, max: control.max, step: control.step, default: Number(control.default) };
+    case "sampler2D":
+      return { ...base, type: "image", default: String(control.default), ...options.images && { options: options.images } };
+    case "text":
+      return { ...base, type: "text", default: String(control.default) };
+    default: {
+      const value = control.default;
+      if (control.color) {
+        const alpha = control.type === "vec4";
+        return { ...base, type: "color", alpha, default: rgba01ToHex(value, alpha) };
+      }
+      return { ...base, type: "vector", size: value.length, min: control.min, max: control.max, step: control.step, default: [...value] };
+    }
+  }
+}
+function parameterSchemaFor(controls, options = {}) {
+  return { ...options.title && { title: options.title }, fields: controls.map((c) => parameterFieldFor(c, options)) };
+}
+function toParameterValue(control, value) {
+  if (control.color && Array.isArray(value)) return rgba01ToHex(value, control.type === "vec4");
+  return Array.isArray(value) ? [...value] : value;
+}
+function toParameterValues(controls, values) {
+  const out = {};
+  for (const control of controls) if (values[control.name] !== void 0) out[control.name] = toParameterValue(control, values[control.name]);
+  return out;
+}
+function toParameterTrack(control, track) {
+  if (!track) return void 0;
+  return {
+    ...track.enabled === false && { enabled: false },
+    keyframes: track.keyframes.map((k) => ({ ...k, value: control ? toParameterValue(control, k.value) : k.value }))
+  };
+}
+function bindEffectParameters(editor, options = {}) {
+  let state = editor.getState();
+  let controls = state.controls;
+  let signature = JSON.stringify(controls);
+  let syncing = false;
+  const byName = () => new Map(controls.map((c) => [c.name, c]));
+  const keyframes = {
+    getTrack: (id) => toParameterTrack(byName().get(id), editor.getState().document.tracks[id]),
+    setTrack: (id, track) => {
+      editor.setTrack(id, track);
+    },
+    subscribe: (listener) => editor.subscribe(() => listener())
+  };
+  const controller = new ParametersController({
+    schema: parameterSchemaFor(controls, options),
+    values: toParameterValues(controls, state.values),
+    time: state.time,
+    keyframes,
+    onChange: (values, changed) => {
+      if (syncing) return;
+      const result = changed.length === 1 ? editor.setValue(changed[0], values[changed[0]]) : editor.setValues(Object.fromEntries(changed.map((id) => [id, values[id]])));
+      if (!result.ok) sync(editor.getState());
+    }
+  });
+  const sync = (next) => {
+    state = next;
+    const nextSignature = JSON.stringify(next.controls);
+    syncing = true;
+    try {
+      if (nextSignature !== signature) {
+        signature = nextSignature;
+        controls = next.controls;
+        controller.setSchema(parameterSchemaFor(controls, options));
+      }
+      controller.setTime(next.time, toParameterValues(controls, next.values));
+    } finally {
+      syncing = false;
+    }
+  };
+  const unsubscribe = editor.subscribe(sync);
+  return {
+    controller,
+    dispose: () => {
+      unsubscribe();
+      controller.destroy();
+    }
+  };
+}
 export {
   EASING_PRESETS,
   EFFECT_AGENT_INSTRUCTIONS,
   EffectEditor,
+  bindEffectParameters,
   bindShaderRenderer,
   bindSvgView,
   callTool,
   createEffectDocument,
   createEffectEditor,
   createEffectToolProvider,
+  createEffectToolRegistry,
   cubicBezierAt,
   describeEditor,
   documentControls,
@@ -1002,7 +1097,11 @@ export {
   keyframeTimes,
   motionAt,
   normalizeKeyframes,
+  parameterFieldFor,
+  parameterSchemaFor,
   parseEffectDocument,
+  toParameterValue,
+  toParameterValues,
   toolDefinitions,
   valuesAt
 };