@pixerate/flair 0.34.0 → 0.35.0

package/dist/index.js

@@ -9,7 +9,7 @@ import {
   standaloneHtml,
   standaloneSceneHtml,
   validateScene
-} from "./chunk-ZULFHADW.js";
+} from "./chunk-OLTY4APV.js";
 import {
   calculateShotTimings,
   createLottieEase,
@@ -870,11 +870,164 @@ function sampleMotionPathAtTime(path, time, duration, ease) {
   return sampleMotionPath(path, distanceFraction);
 }
 
+// src/agent/batch.ts
+function getByPath(obj, path) {
+  if (!obj || typeof obj !== "object") return void 0;
+  const parts = path.replace(/\[(\w+)\]/g, ".$1").split(".");
+  let curr = obj;
+  for (const part of parts) {
+    if (curr === void 0 || curr === null) return void 0;
+    curr = curr[part];
+  }
+  return curr;
+}
+var REFERENCE = /\$(\d+)\.([A-Za-z_][\w.[\]]*)/g;
+function resolve(stepResults, stepStr, path, text) {
+  const stepIdx = parseInt(stepStr, 10);
+  const prevResult = stepResults.get(stepIdx);
+  if (!prevResult) {
+    throw new Error(`"${text}" refers to step ${stepIdx}, which has not run before this step.`);
+  }
+  const resolved = getByPath(prevResult, path);
+  if (resolved === void 0) {
+    throw new Error(`"${text}" does not resolve: step ${stepIdx}'s result has nothing at "${path}".`);
+  }
+  return resolved;
+}
+function substituteVariables(value, stepResults) {
+  if (typeof value === "string") {
+    const match = /^\$(\d+)\.([A-Za-z_][\w.[\]]*)$/.exec(value);
+    if (match) return resolve(stepResults, match[1], match[2], value);
+    return value.replace(
+      REFERENCE,
+      (fullMatch, stepStr, path) => String(resolve(stepResults, stepStr, path, fullMatch))
+    );
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => substituteVariables(item, stepResults));
+  }
+  if (value !== null && typeof value === "object") {
+    const copy = {};
+    for (const [k, v] of Object.entries(value)) {
+      copy[k] = substituteVariables(v, stepResults);
+    }
+    return copy;
+  }
+  return value;
+}
+async function applySceneBatch(scene, commands) {
+  let currentScene = scene;
+  const stepResults = /* @__PURE__ */ new Map();
+  const executedSteps = [];
+  for (let i = 0; i < commands.length; i++) {
+    const stepNumber = i + 1;
+    const cmd = commands[i];
+    if (cmd.tool === "batch_scene") {
+      return {
+        ok: false,
+        scene,
+        // Rollback
+        steps: executedSteps,
+        error: `Step ${stepNumber} is a batch_scene; batches cannot be nested, so list its steps here instead.`,
+        failedStep: stepNumber
+      };
+    }
+    let resolvedParams;
+    try {
+      resolvedParams = substituteVariables(cmd.params || {}, stepResults);
+    } catch (err) {
+      return {
+        ok: false,
+        scene,
+        // Rollback
+        steps: executedSteps,
+        error: `Step ${stepNumber} (${cmd.tool}) failed: ${err.message}`,
+        failedStep: stepNumber
+      };
+    }
+    const stepResult = await applySceneTool(currentScene, cmd.tool, resolvedParams);
+    stepResults.set(stepNumber, stepResult);
+    executedSteps.push({
+      step: stepNumber,
+      tool: cmd.tool,
+      result: stepResult
+    });
+    if (!stepResult.ok) {
+      return {
+        ok: false,
+        scene,
+        // Rollback to initial
+        steps: executedSteps,
+        error: `Step ${stepNumber} (${cmd.tool}) failed: ${stepResult.error}`,
+        failedStep: stepNumber
+      };
+    }
+    currentScene = stepResult.scene;
+  }
+  return {
+    ok: true,
+    scene: currentScene,
+    steps: executedSteps
+  };
+}
+
+// src/agent/schema.ts
+function typeOf(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  if (typeof value === "number") return Number.isInteger(value) ? "integer" : "number";
+  return typeof value;
+}
+function described(type) {
+  if (type === "integer") return "a whole number";
+  if (type === "null") return "null";
+  return `${/^[aeiou]/.test(type) ? "an" : "a"} ${type}`;
+}
+function fits(value, type) {
+  const actual = typeOf(value);
+  return actual === type || type === "number" && actual === "integer";
+}
+function checkSchema(schema, value, at = "arguments") {
+  const problems = [];
+  if (schema.type !== void 0) {
+    const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+    if (!types.some((t) => fits(value, t))) {
+      const actual = typeOf(value) === "integer" ? "number" : typeOf(value);
+      problems.push(`${at} must be ${types.map(described).join(" or ")}, not ${described(actual)}.`);
+      return problems;
+    }
+  }
+  if (schema.enum && !schema.enum.includes(value)) {
+    problems.push(`${at} must be one of ${schema.enum.map((v) => JSON.stringify(v)).join(", ")}.`);
+  }
+  if (typeof value === "number" && typeof schema.minimum === "number" && value < schema.minimum) {
+    problems.push(`${at} must be at least ${schema.minimum}.`);
+  }
+  if (Array.isArray(value) && schema.items) {
+    value.forEach((item, i) => problems.push(...checkSchema(schema.items, item, `${at}[${i}]`)));
+  }
+  if (typeOf(value) === "object") {
+    const obj = value;
+    const props = schema.properties ?? {};
+    for (const name of schema.required ?? []) {
+      if (obj[name] === void 0) problems.push(`${at}.${name} is required.`);
+    }
+    for (const [name, v] of Object.entries(obj)) {
+      if (props[name]) problems.push(...checkSchema(props[name], v, `${at}.${name}`));
+      else if (schema.additionalProperties === false) {
+        const known = Object.keys(props);
+        problems.push(`${at}.${name} is not a parameter${known.length ? `; expected ${known.map((k) => `"${k}"`).join(", ")}` : ""}.`);
+      }
+    }
+  }
+  return problems;
+}
+
 // src/agent/tools.ts
 var FLAIR_AGENT_TOOLS = [
   {
     name: "get_scene",
-    description: "Returns the current scene JSON (or a concise structural outline) and any static validation issues.",
+    description: 'Returns the current scene JSON, or with view "outline" a concise structural outline instead, and any static validation issues. Start here.',
     input_schema: {
       type: "object",
       properties: {
@@ -889,7 +1042,7 @@ var FLAIR_AGENT_TOOLS = [
   },
   {
     name: "write_scene",
-    description: "Overwrites the entire scene with a new specification and validates it.",
+    description: "Overwrites the entire scene with a new specification and validates it. Prefer update_shot, insert_shots and delete_shots for smaller changes.",
     input_schema: {
       type: "object",
       properties: {
@@ -909,7 +1062,10 @@ var FLAIR_AGENT_TOOLS = [
       type: "object",
       properties: {
         shot: { type: "integer", minimum: 1, description: "1-based index of the shot to update." },
-        set: { type: "object", description: "Fields to set or replace on this shot." },
+        set: {
+          type: "object",
+          description: "Fields to set or replace on this shot: caption, title, camera, hold (ms), run, effects, stopEffects, behaviors."
+        },
         remove: {
           type: "array",
           items: { type: "string" },
@@ -934,7 +1090,7 @@ var FLAIR_AGENT_TOOLS = [
         shots: {
           type: "array",
           items: { type: "object" },
-          description: "Array of Shot objects to insert."
+          description: "Shot objects to insert (fields as for update_shot)."
         }
       },
       required: ["after", "shots"],
@@ -966,7 +1122,7 @@ var FLAIR_AGENT_TOOLS = [
         id: { type: "string", description: "Media identifier." },
         media: {
           type: ["object", "null"],
-          description: 'SceneMedia object (e.g. { type: "shader", source: "..." }), or null to remove.'
+          description: 'SceneMedia object, or null to remove. A shader is { type: "shader", source } with a GLSL ES 3.00 Shadertoy-style void mainImage(out vec4 fragColor, in vec2 fragCoord); it is only compiled when the scene is rendered on a GPU.'
         }
       },
       required: ["id", "media"],
@@ -975,7 +1131,7 @@ var FLAIR_AGENT_TOOLS = [
   },
   {
     name: "preview_scene",
-    description: "Simulates the scene fast and off-screen, returning timing, layout checks, and review report.",
+    description: "Simulates the scene fast and off-screen, returning its total length, layout and timing warnings, and notes. Run it after a round of edits.",
     input_schema: {
       type: "object",
       properties: {},
@@ -997,208 +1153,174 @@ var FLAIR_AGENT_TOOLS = [
       required: ["name", "value"],
       additionalProperties: false
     }
+  },
+  {
+    name: "batch_scene",
+    description: `Runs several of these tools in order as one all-or-nothing change: if a step fails, none of the steps apply. A string param "$N.path" is replaced by that path in step N's result (1-based; e.g. "$1.output.outline.shots[0].hold" or "$2.scene.shots[1].title"), and "$N.path" inside a longer string is filled in; a reference that does not resolve fails its step.`,
+    input_schema: {
+      type: "object",
+      properties: {
+        steps: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              tool: { type: "string", description: "A tool name (not batch_scene)." },
+              params: { type: "object", description: "That tool's arguments." }
+            },
+            required: ["tool"],
+            additionalProperties: false
+          },
+          description: "The tool calls to run, in order."
+        }
+      },
+      required: ["steps"],
+      additionalProperties: false
+    }
   }
 ];
+var TOOL_NAMES = FLAIR_AGENT_TOOLS.map((t) => t.name);
+function fail(error, failedStep) {
+  return { ok: false, error, ...failedStep !== void 0 && { failedStep }, output: { ok: false, error } };
+}
+function edited(scene, summary) {
+  const issues = validateScene(scene);
+  return { ok: true, scene, issues, output: { ok: true, summary, shotCount: scene.shots.length, issues } };
+}
+var shotsWord = (n) => `${n} shot${n === 1 ? "" : "s"}`;
+function outlineScene(scene) {
+  return {
+    name: scene.name,
+    title: scene.title,
+    description: scene.description,
+    stage: scene.stage,
+    target: scene.target,
+    mediaIds: Object.keys(scene.media || {}),
+    shots: scene.shots.map((s, i) => ({
+      shot: i + 1,
+      caption: s.caption,
+      title: s.title,
+      hold: s.hold,
+      camera: s.camera,
+      commandCount: Array.isArray(s.run) ? s.run.length : 0,
+      effects: Array.isArray(s.effects) ? s.effects.map((e) => e.type) : void 0
+    }))
+  };
+}
 async function applySceneTool(scene, toolName, input = {}) {
+  const definition = FLAIR_AGENT_TOOLS.find((t) => t.name === toolName);
+  if (!definition) {
+    return fail(`There is no tool "${toolName}"; the tools are ${TOOL_NAMES.join(", ")}.`);
+  }
+  const problems = checkSchema(definition.input_schema, input ?? {});
+  if (problems.length) return fail(`Invalid arguments for ${toolName}: ${problems.join(" ")}`);
+  const shotCount = scene.shots.length;
+  const shotRange = `the scene has ${shotsWord(shotCount)} (1 to ${shotCount})`;
   switch (toolName) {
     case "get_scene": {
       const issues = validateScene(scene);
       if (input.view === "outline") {
-        const outline = {
-          name: scene.name,
-          title: scene.title,
-          description: scene.description,
-          stage: scene.stage,
-          target: scene.target,
-          mediaIds: Object.keys(scene.media || {}),
-          shots: scene.shots.map((s, i) => ({
-            shot: i + 1,
-            caption: s.caption,
-            title: s.title,
-            hold: s.hold,
-            camera: s.camera,
-            commandCount: s.run?.length ?? 0,
-            effects: s.effects?.map((e) => e.type)
-          }))
-        };
-        return { ok: true, scene, outline, issues };
+        const outline = outlineScene(scene);
+        return { ok: true, scene, outline, issues, output: { ok: true, outline, issues } };
       }
-      return { ok: true, scene, issues };
+      return { ok: true, scene, issues, output: { ok: true, scene, issues } };
     }
     case "write_scene": {
-      if (!input.scene || typeof input.scene !== "object") {
-        return { ok: false, error: "Expected scene object in arguments." };
+      const next = input.scene;
+      if (!Array.isArray(next.shots) || next.shots.some((s) => !s || typeof s !== "object" || Array.isArray(s))) {
+        return fail("The scene needs a shots array of shot objects; nothing was written.");
       }
-      const newScene = input.scene;
-      const issues = validateScene(newScene);
-      return { ok: true, scene: newScene, issues };
+      if (next.shots.length === 0) return fail("The scene needs at least one shot; nothing was written.");
+      return edited(next, `Wrote the scene "${next.name}" with ${shotsWord(next.shots.length)}.`);
     }
     case "update_shot": {
       const idx = input.shot - 1;
-      if (idx < 0 || idx >= scene.shots.length) {
-        return { ok: false, error: `Invalid shot number ${input.shot}; scene has ${scene.shots.length} shots.` };
-      }
-      const existing = scene.shots[idx];
-      const updated = { ...existing, ...input.set || {} };
-      if (Array.isArray(input.remove)) {
-        for (const k of input.remove) {
-          delete updated[k];
-        }
+      if (idx >= shotCount) return fail(`There is no shot ${input.shot}; ${shotRange}.`);
+      if (input.set === void 0 && input.remove === void 0) {
+        return fail('Give fields to change in "set", field names to delete in "remove", or both.');
       }
+      const updated = { ...scene.shots[idx], ...input.set || {} };
+      for (const k of input.remove ?? []) delete updated[k];
       const shots = [...scene.shots];
       shots[idx] = updated;
-      const newScene = { ...scene, shots };
-      return { ok: true, scene: newScene, issues: validateScene(newScene) };
+      const changed = [...Object.keys(input.set ?? {}), ...(input.remove ?? []).map((k) => `-${k}`)];
+      return edited({ ...scene, shots }, `Updated shot ${input.shot} (${changed.join(", ")}).`);
     }
     case "insert_shots": {
-      const after = input.after ?? scene.shots.length;
-      if (after < 0 || after > scene.shots.length) {
-        return { ok: false, error: `Invalid after index ${after}.` };
-      }
-      if (!Array.isArray(input.shots) || input.shots.length === 0) {
-        return { ok: false, error: "Expected non-empty shots array to insert." };
-      }
+      const after = input.after;
+      if (after > shotCount) return fail(`Cannot insert after shot ${after}; ${shotRange}, so "after" is 0 to ${shotCount}.`);
+      if (input.shots.length === 0) return fail("Give at least one shot to insert.");
       const shots = [...scene.shots.slice(0, after), ...input.shots, ...scene.shots.slice(after)];
-      const newScene = { ...scene, shots };
-      return { ok: true, scene: newScene, issues: validateScene(newScene) };
+      const first = after + 1;
+      const last = after + input.shots.length;
+      return edited(
+        { ...scene, shots },
+        `Inserted ${shotsWord(input.shots.length)} as ${first === last ? `shot ${first}` : `shots ${first}-${last}`}; later shots moved down.`
+      );
     }
     case "delete_shots": {
-      if (!Array.isArray(input.shots) || input.shots.length === 0) {
-        return { ok: false, error: "Expected non-empty shots array to delete." };
-      }
-      const toDelete = new Set(input.shots.map((n) => n - 1));
+      const numbers = input.shots;
+      if (numbers.length === 0) return fail("Give the shot numbers to delete.");
+      const missing = numbers.filter((n) => n > shotCount);
+      if (missing.length) return fail(`There is no shot ${missing.join(", ")}; ${shotRange}. Nothing was deleted.`);
+      const toDelete = new Set(numbers.map((n) => n - 1));
       const shots = scene.shots.filter((_, i) => !toDelete.has(i));
-      if (shots.length === 0) {
-        return { ok: false, error: "Cannot delete all shots in scene." };
-      }
-      const newScene = { ...scene, shots };
-      return { ok: true, scene: newScene, issues: validateScene(newScene) };
+      if (shots.length === 0) return fail("Cannot delete every shot; a scene needs at least one. Nothing was deleted.");
+      return edited({ ...scene, shots }, `Deleted ${shotsWord(toDelete.size)}; the scene has ${shotsWord(shots.length)} now.`);
     }
     case "set_media": {
-      if (!input.id || typeof input.id !== "string") {
-        return { ok: false, error: "Expected string media id." };
-      }
       const media = { ...scene.media || {} };
       if (input.media === null) {
+        if (!(input.id in media)) {
+          const ids = Object.keys(media);
+          return fail(`There is no media "${input.id}" to remove; ${ids.length ? `the media are ${ids.join(", ")}` : "the scene has no media"}.`);
+        }
         delete media[input.id];
-      } else {
-        media[input.id] = input.media;
+        return edited({ ...scene, media }, `Removed media "${input.id}".`);
       }
-      const newScene = { ...scene, media };
-      return { ok: true, scene: newScene, issues: validateScene(newScene) };
+      if (typeof input.media.type !== "string") return fail('Media needs a string type, e.g. { type: "shader", source: "..." }.');
+      const existed = input.id in media;
+      media[input.id] = input.media;
+      return edited({ ...scene, media }, `${existed ? "Replaced" : "Added"} ${input.media.type} media "${input.id}".`);
     }
     case "preview_scene": {
       const { review } = await simulateScene(scene);
-      return { ok: true, scene, issues: validateScene(scene), review };
+      const issues = validateScene(scene);
+      const { markdown: _markdown, ...summary } = review;
+      return { ok: true, scene, issues, review, output: { ok: true, issues, review: summary } };
     }
     case "set_rig_widget": {
-      if (!scene.rig || !scene.rig.widgets || !scene.rig.widgets[input.name]) {
-        return { ok: false, error: `Scene does not have a rig widget named "${input.name}".` };
+      const widgets = scene.rig?.widgets ?? {};
+      if (!scene.rig || !widgets[input.name]) {
+        const names = Object.keys(widgets);
+        return fail(`Scene does not have a rig widget named "${input.name}"; ${names.length ? `its widgets are ${names.join(", ")}` : "it has no rig widgets"}.`);
       }
       try {
         const updatedRig = setRigWidget(scene.rig, input.name, input.value);
-        const newScene = applyRig(updatedRig, scene);
-        return { ok: true, scene: newScene, issues: validateScene(newScene) };
+        return edited(applyRig(updatedRig, scene), `Set rig widget "${input.name}" to ${JSON.stringify(input.value)}.`);
       } catch (err) {
-        return { ok: false, error: err.message || String(err) };
+        return fail(err.message || String(err));
       }
     }
-    default:
-      return { ok: false, error: `Unknown tool name: ${toolName}` };
-  }
-}
-
-// src/agent/batch.ts
-function getByPath(obj, path) {
-  if (!obj || typeof obj !== "object") return void 0;
-  const parts = path.replace(/\[(\w+)\]/g, ".$1").split(".");
-  let curr = obj;
-  for (const part of parts) {
-    if (curr === void 0 || curr === null) return void 0;
-    curr = curr[part];
-  }
-  return curr;
-}
-function substituteVariables(value, stepResults) {
-  if (typeof value === "string") {
-    const match = /^\$(\d+)\.(.+)$/.exec(value);
-    if (match) {
-      const stepIdx = parseInt(match[1], 10);
-      const path = match[2];
-      const prevResult = stepResults.get(stepIdx);
-      if (prevResult) {
-        const resolved = getByPath(prevResult, path);
-        if (resolved !== void 0) {
-          return resolved;
-        }
-      }
-    }
-    return value.replace(/\$(\d+)\.([a-zA-Z0-9_.[\]]+)/g, (fullMatch, stepStr, path) => {
-      const stepIdx = parseInt(stepStr, 10);
-      const prevResult = stepResults.get(stepIdx);
-      if (prevResult) {
-        const resolved = getByPath(prevResult, path);
-        if (resolved !== void 0) {
-          return String(resolved);
-        }
-      }
-      return fullMatch;
-    });
-  }
-  if (Array.isArray(value)) {
-    return value.map((item) => substituteVariables(item, stepResults));
-  }
-  if (value !== null && typeof value === "object") {
-    const copy = {};
-    for (const [k, v] of Object.entries(value)) {
-      copy[k] = substituteVariables(v, stepResults);
-    }
-    return copy;
-  }
-  return value;
-}
-async function applySceneBatch(scene, commands) {
-  let currentScene = scene;
-  const stepResults = /* @__PURE__ */ new Map();
-  const executedSteps = [];
-  for (let i = 0; i < commands.length; i++) {
-    const stepNumber = i + 1;
-    const cmd = commands[i];
-    const resolvedParams = substituteVariables(cmd.params || {}, stepResults);
-    if (cmd.tool === "batch_scene_tool") {
-      return {
-        ok: false,
-        scene,
-        // Rollback
-        steps: executedSteps,
-        error: `Nested batch_scene_tool is not allowed at step ${stepNumber}.`,
-        failedStep: stepNumber
-      };
-    }
-    const stepResult = await applySceneTool(currentScene, cmd.tool, resolvedParams);
-    stepResults.set(stepNumber, stepResult);
-    executedSteps.push({
-      step: stepNumber,
-      tool: cmd.tool,
-      result: stepResult
-    });
-    if (!stepResult.ok) {
+    case "batch_scene": {
+      const batch = await applySceneBatch(scene, input.steps);
+      if (!batch.ok) return fail(`${batch.error} No steps were applied.`, batch.failedStep);
+      const issues = validateScene(batch.scene);
       return {
-        ok: false,
-        scene,
-        // Rollback to initial
-        steps: executedSteps,
-        error: `Step ${stepNumber} (${cmd.tool}) failed: ${stepResult.error}`,
-        failedStep: stepNumber
+        ok: true,
+        scene: batch.scene,
+        issues,
+        output: {
+          ok: true,
+          summary: `Ran ${batch.steps.length} step${batch.steps.length === 1 ? "" : "s"}.`,
+          steps: batch.steps.map((s) => ({ step: s.step, tool: s.tool, ...s.result.output })),
+          shotCount: batch.scene.shots.length,
+          issues
+        }
       };
     }
-    currentScene = stepResult.scene;
   }
-  return {
-    ok: true,
-    scene: currentScene,
-    steps: executedSteps
-  };
+  return fail(`There is no tool "${toolName}".`);
 }
 export {
   ALL_BLEND_MODES,
@@ -1353,6 +1475,7 @@ export {
   oklabToOklch,
   oklabToSrgb,
   oklchToOklab,
+  outlineScene,
   overlapArea,
   pageHidden,
   parseColor,