@pixerate/flair 0.34.0 → 0.35.0

package/dist/editor/index.js

@@ -234,6 +234,12 @@ var easingSchema = {
 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, an image URL (sampler2D), or a string (text).'
 };
+var CATALOG_SEARCH_LIMIT = 20;
+function compileStatus(editor) {
+  const state = editor.getState();
+  if (state.document.effect.kind !== "shader") return void 0;
+  return state.compile ?? "not compiled yet: no renderer has compiled this source, so compile errors are unknown";
+}
 function describeEditor(editor) {
   const state = editor.getState();
   const doc = state.document;
@@ -255,7 +261,7 @@ function describeEditor(editor) {
     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,
+    ...doc.effect.kind === "shader" && { compile: compileStatus(editor) },
     history: { canUndo: state.history.canUndo, canRedo: state.history.canRedo }
   };
 }
@@ -273,7 +279,7 @@ function effectCommands() {
       id: "catalog.search",
       label: "Search effects",
       group: "Catalog",
-      description: "Searches the built-in effect catalog. Load one with effect.load to start from it.",
+      description: `Searches the built-in effect catalog: {total, effects}, at most \`limit\` effects (default ${CATALOG_SEARCH_LIMIT}). Narrow with words and filters rather than raising the limit. Load one with effect.load to start from it.`,
       readOnly: true,
       params: {
         type: "object",
@@ -301,25 +307,37 @@ function effectCommands() {
             items: { type: "string", enum: EFFECT_INTERACTIONS },
             description: "Only effects that answer the pointer in one of these ways: hover, press, click, trail (follows where it has been), pointer (follows where it is). An empty list finds effects that don't answer it."
           },
-          transparent: { type: "boolean", description: "Only overlays (true), drawn over other content, or only effects that fill their frame (false)." }
+          transparent: { type: "boolean", description: "Only overlays (true), drawn over other content, or only effects that fill their frame (false)." },
+          limit: { type: "integer", minimum: 1, description: `Most effects to return (default ${CATALOG_SEARCH_LIMIT}).` },
+          offset: { type: "integer", minimum: 0, description: "Effects to skip first, to page through more (default 0)." }
         },
         additionalProperties: false
       },
-      run: (_, params) => findEffects(params ?? {}).map((e) => {
-        const inputs = effectInputs(e);
+      run: (_, params) => {
+        const { limit = CATALOG_SEARCH_LIMIT, offset = 0, ...filters } = params ?? {};
+        const found = findEffects(filters);
+        const effects = found.slice(offset, offset + limit).map((e) => {
+          const inputs = effectInputs(e);
+          return {
+            id: e.id,
+            name: e.name,
+            kind: e.kind,
+            category: e.category,
+            description: e.description,
+            ...e.kind === "shader" && e.video ? { video: e.video } : {},
+            accepts: inputs.accepts,
+            ...inputs.interactions.length ? { interactions: inputs.interactions } : {},
+            ...inputs.transparent ? { transparent: true } : {},
+            presets: e.presets?.map((p) => p.name) ?? []
+          };
+        });
+        const more = found.length - offset - effects.length;
         return {
-          id: e.id,
-          name: e.name,
-          kind: e.kind,
-          category: e.category,
-          description: e.description,
-          ...e.kind === "shader" && e.video ? { video: e.video } : {},
-          accepts: inputs.accepts,
-          ...inputs.interactions.length ? { interactions: inputs.interactions } : {},
-          ...inputs.transparent ? { transparent: true } : {},
-          presets: e.presets?.map((p) => p.name) ?? []
+          total: found.length,
+          effects,
+          ...more > 0 && { more: `${more} more match; narrow the search, or pass offset ${offset + effects.length} for the next ones.` }
         };
-      })
+      }
     },
     {
       id: "effect.load",
@@ -342,9 +360,40 @@ function effectCommands() {
       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.",
+      description: "Replaces a shader effect's GLSL ES 3.00 source (Shadertoy-style mainImage; controls are uniforms annotated `// @control`). Returns the compile report when a preview compiled it (errors carry your source's line numbers), and the document's issues.",
       params: { type: "object", properties: { source: { type: "string" } }, required: ["source"], additionalProperties: false },
-      run: (editor, p) => done(editor.setSource(p.source))
+      run: (editor, p) => {
+        done(editor.setSource(p.source));
+        return { ok: true, compile: compileStatus(editor), issues: editor.getState().issues };
+      }
+    },
+    {
+      id: "effect.setMotion",
+      label: "Set vector picture",
+      group: "Effect",
+      description: "Replaces a vector effect's picture: {svg, animate?}. `svg` is one self-contained <svg> with a viewBox (no scripts); `{{name: type \u2026}}` placeholders in it declare controls and `{{name}}` fills them. `animate` lists changes to elements by id: {id, step?, delay?, ms?, ease?, attrs?: {name: [from, to]}, draw?, view?, along?, count?, write?}. Returns the document's issues.",
+      params: {
+        type: "object",
+        properties: {
+          motion: {
+            type: "object",
+            properties: { svg: { type: "string" }, animate: { type: "array", items: { type: "object" } } },
+            required: ["svg"],
+            description: "The picture and its animation."
+          },
+          controls: {
+            type: "array",
+            items: { type: "object" },
+            description: "Controls declared outside the picture, for older pictures: {name, type, default, label?, color?, min?, max?, step?}. Leave out to keep the current list."
+          }
+        },
+        required: ["motion"],
+        additionalProperties: false
+      },
+      run: (editor, p) => {
+        done(editor.setMotion(p.motion, p.controls));
+        return { ok: true, issues: editor.getState().issues };
+      }
     },
     {
       id: "effect.rename",
@@ -621,14 +670,16 @@ var EffectEditor = class {
   // ── 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 (this.doc.effect.kind !== "shader") return fail("This is a vector effect; change its picture with setMotion (the effect.setMotion command).");
     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, 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.");
+    if (this.doc.effect.kind !== "vector") return fail("This is a shader effect; change its source with setSource (the effect.setSource command).");
+    if (!motion || typeof motion.svg !== "string" || !motion.svg.trim()) return fail("The picture needs `svg`: one <svg>\u2026</svg> element with a viewBox.");
+    if (motion.animate !== void 0 && !Array.isArray(motion.animate)) return fail("`animate` must be a list of changes to the picture's elements.");
     this.commit("Edit picture", { ...this.doc, effect: { ...this.doc.effect, motion, controls: controls ?? this.doc.effect.controls } });
     return ok;
   }
@@ -958,7 +1009,7 @@ async function callTool(provider, name, args = {}) {
 }
 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.
+Start with \`effect.describe\` to see what is being edited. To start from something close, use \`catalog.search\` (it returns the first matches and a \`total\`; narrow it with words and filters) 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 unless the host renders with \`alpha: true\` (overlays), when \`fragColor.a\` is coverage.
@@ -970,11 +1021,11 @@ Shader effects are GLSL ES 3.00 fragment shaders written Shadertoy-style:
   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.
+- \`effect.setSource\` returns \`compile\`: fix any errors (their line numbers match your source) before going on. When it says the source is not compiled yet, no preview is attached; check again with \`effect.describe\` or \`view_effect\` later.
 
 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.
+Change their controls' values freely (a text control takes any words). Replace the picture with \`effect.setMotion\` ({svg, animate}), with care: keep the viewBox and the element ids that animations refer to, and read the issues it returns.
 
 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.`;
 
@@ -1119,6 +1170,7 @@ function bindEffectParameters(editor, options = {}) {
   };
 }
 export {
+  CATALOG_SEARCH_LIMIT,
   EASING_PRESETS,
   EFFECT_AGENT_INSTRUCTIONS,
   EffectEditor,