@hyperframes/studio 0.8.24 → 0.8.25

package/src/webmcp/tools/animationTools.ts

@@ -1,66 +1,70 @@
 /**
  * `studio_animate`: author motion.
  *
- * These tools are deliberately less confident than the rest, because the
- * handlers underneath them are:
- *
- * - `handleGsapAddAnimation(method)` takes ONLY a method. Its insert position
- *   comes from the live playhead, not from the caller, and the call is
- *   `void ...catch()`, so it returns nothing and cannot be awaited.
- * - `handleGsapAddKeyframeBatch` returns a promise but catches its own failure,
- *   so awaiting it proves the call finished, not that it landed.
- * - `handleGsapDeleteAnimation` discards its promise entirely.
- * - `handleGsapUpdateMeta` is the one honest signal: it returns a boolean.
- *   Its `false` is ambiguous though, meaning either no selection or a failed
- *   write, so the no-selection case is ruled out before dispatch.
- *
- * U8 solved the same problem by reading the result back. That does not work
- * here: the animation list comes from React state that only refreshes on a
- * render, and no render happens inside one tool call. So rather than fake a
- * verification, these report what was dispatched and tell the agent to call
- * `studio_inspect` to see the result. Saying "I asked for this" is honest;
- * saying "this happened" would not be.
+ * Add, update, and delete await the shared GSAP commit pipeline. Its promise is
+ * the single settlement boundary for persistence and live-preview sync, so a
+ * successful tool response never races ahead of the pixels the user sees.
+ * Keyframe writes still report dispatch because their existing actor catches
+ * its own failure instead of returning a landed signal.
  */
 
 import type { DomEditSelection } from "../../components/editor/domEditingTypes";
-import { toolFailure, toolOk, type ToolFailure, type ToolResult } from "../toolResult";
+import { toolFailure, type ToolFailure } from "../toolResult";
+import {
+  dispatched,
+  runTargetedWrite,
+  type StudioWriteResult,
+  type TargetedWriteDeps,
+  WRITE_RECEIPT_DESCRIPTION,
+} from "../writeCoordinator";
 
 export type GsapMethod = "to" | "from" | "set" | "fromTo";
 
 const METHODS: readonly GsapMethod[] = ["to", "from", "set", "fromTo"];
 
-export interface AnimationToolDeps {
-  getCurrentSelection: () => DomEditSelection | null;
-  getWriteBlockedReason: () => string | null;
+export interface AnimationToolDeps extends TargetedWriteDeps {
+  getAnimationsForSelection: (selection: DomEditSelection) => Promise<readonly { id: string }[]>;
   readPlayhead: () => { currentTime: number; duration: number; isPlaying: boolean };
-  addAnimation: (method: GsapMethod) => void;
+  addAnimation: (selection: DomEditSelection, method: GsapMethod) => Promise<boolean>;
   updateAnimation: (
+    selection: DomEditSelection,
     animationId: string,
     updates: { duration?: number; ease?: string; position?: number },
   ) => Promise<boolean>;
   addKeyframe: (
+    selection: DomEditSelection,
     animationId: string,
     percent: number,
     properties: Record<string, number | string>,
   ) => Promise<void>;
-  deleteAnimation: (animationId: string) => void;
+  deleteAnimation: (selection: DomEditSelection, animationId: string) => Promise<boolean>;
 }
 
 const INSPECT_HINT = "Call studio_inspect to see the result.";
 
-function guard(deps: AnimationToolDeps): ToolFailure | null {
-  const blocked = deps.getWriteBlockedReason();
-  if (blocked) return toolFailure("blocked", blocked, "Resolve it in Studio, then retry.");
-  if (!deps.getCurrentSelection()) {
-    return toolFailure("invalid", "nothing is selected", "Call studio_select first.");
-  }
-  return null;
+async function animationBelongsToTarget(
+  deps: AnimationToolDeps,
+  selection: DomEditSelection,
+  animationId: string,
+): Promise<ToolFailure | null> {
+  const animations = await deps.getAnimationsForSelection(selection);
+  return animations.some((animation) => animation.id === animationId)
+    ? null
+    : toolFailure(
+        "invalid",
+        `animation ${animationId} does not belong to the target handle`,
+        "Select the target, then call studio_inspect for its current animation ids.",
+      );
 }
 
 function readAnimationId(value: unknown): string | null {
   return typeof value === "string" && value.trim() ? value : null;
 }
 
+function isRawGsapExpression(value: unknown): value is string {
+  return typeof value === "string" && value.startsWith("__raw:");
+}
+
 export interface StudioAddAnimationResult {
   method: GsapMethod;
   /** Where it was inserted, which is the playhead, not a value you supplied. */
@@ -70,26 +74,32 @@ export interface StudioAddAnimationResult {
 
 export async function studioAddAnimation(
   deps: AnimationToolDeps,
-  input: { method?: unknown },
-): Promise<ToolResult<StudioAddAnimationResult>> {
+  input: { handle?: unknown; method?: unknown },
+  signal: AbortSignal = new AbortController().signal,
+): Promise<StudioWriteResult<StudioAddAnimationResult>> {
   const method = METHODS.find((candidate) => candidate === input.method);
   if (!method) {
-    return toolFailure("invalid", `method must be one of ${METHODS.join(", ")}`);
+    return preDispatchFailure(
+      "add-animation",
+      toolFailure("invalid", `method must be one of ${METHODS.join(", ")}`),
+    );
   }
-
-  const blocked = guard(deps);
-  if (blocked) return blocked;
-
-  // The handler reads the playhead itself. Reporting a position the caller gave
-  // us would be reporting a number that had no effect, so the tool takes no
-  // position and reports where the playhead actually is instead.
-  const { currentTime } = deps.readPlayhead();
-  deps.addAnimation(method);
-
-  return toolOk<StudioAddAnimationResult>({
-    method,
-    insertedAtSeconds: currentTime,
-    dispatched: true,
+  return runTargetedWrite(deps, {
+    handle: input.handle,
+    operation: "add-animation",
+    signal,
+    write: async (selection) => {
+      const { currentTime } = deps.readPlayhead();
+      const landed = await deps.addAnimation(selection, method);
+      if (!landed) {
+        return toolFailure(
+          "failed",
+          "the animation did not land",
+          "The target may be stale. Call studio_look and try again with its current handle.",
+        );
+      }
+      return dispatched({ method, insertedAtSeconds: currentTime, dispatched: true }, false);
+    },
   });
 }
 
@@ -100,42 +110,65 @@ export interface StudioUpdateAnimationResult {
 
 export async function studioUpdateAnimation(
   deps: AnimationToolDeps,
-  input: { animationId?: unknown; duration?: unknown; ease?: unknown; position?: unknown },
-): Promise<ToolResult<StudioUpdateAnimationResult>> {
+  input: {
+    handle?: unknown;
+    animationId?: unknown;
+    duration?: unknown;
+    ease?: unknown;
+    position?: unknown;
+  },
+  signal: AbortSignal = new AbortController().signal,
+): Promise<StudioWriteResult<StudioUpdateAnimationResult>> {
   const animationId = readAnimationId(input.animationId);
   if (!animationId) {
-    return toolFailure("invalid", "animationId must be a non-empty string", INSPECT_HINT);
+    return preDispatchFailure(
+      "update-animation",
+      toolFailure("invalid", "animationId must be a non-empty string", INSPECT_HINT),
+    );
   }
 
   const updates: { duration?: number; ease?: string; position?: number } = {};
   if (typeof input.duration === "number" && Number.isFinite(input.duration)) {
-    if (input.duration < 0) return toolFailure("invalid", "duration must not be negative");
+    if (input.duration < 0)
+      return preDispatchFailure(
+        "update-animation",
+        toolFailure("invalid", "duration must not be negative"),
+      );
     updates.duration = input.duration;
   }
+  if (isRawGsapExpression(input.ease)) {
+    return preDispatchFailure(
+      "update-animation",
+      toolFailure("invalid", "raw JavaScript expressions are not accepted"),
+    );
+  }
   if (typeof input.ease === "string" && input.ease.trim()) updates.ease = input.ease;
   if (typeof input.position === "number" && Number.isFinite(input.position)) {
     updates.position = input.position;
   }
   if (Object.keys(updates).length === 0) {
-    return toolFailure("invalid", "give at least one of duration, ease, position");
-  }
-
-  // Ruled out BEFORE dispatch on purpose: the handler answers `false` for both
-  // "nothing selected" and "the write failed", so a false afterwards would be
-  // ambiguous. Eliminating one of the two makes the other one legible.
-  const blocked = guard(deps);
-  if (blocked) return blocked;
-
-  const landed = await deps.updateAnimation(animationId, updates);
-  if (!landed) {
-    return toolFailure(
-      "failed",
-      `the update to ${animationId} did not land`,
-      "The animation id may be stale. studio_inspect lists the current ones.",
+    return preDispatchFailure(
+      "update-animation",
+      toolFailure("invalid", "give at least one of duration, ease, position"),
     );
   }
-
-  return toolOk<StudioUpdateAnimationResult>({ animationId, updated: updates });
+  return runTargetedWrite(deps, {
+    handle: input.handle,
+    operation: "update-animation",
+    signal,
+    preflight: (selection) => animationBelongsToTarget(deps, selection, animationId),
+    write: async (selection) => {
+      const landed = await deps.updateAnimation(selection, animationId, updates);
+      if (!landed) {
+        return toolFailure(
+          "failed",
+          `the update to ${animationId} did not land`,
+          "The animation id may be stale. studio_inspect lists the current ones.",
+        );
+      }
+      return dispatched({ animationId, updated: updates }, false);
+    },
+  });
 }
 
 export interface StudioAddKeyframeResult {
@@ -147,36 +180,58 @@ export interface StudioAddKeyframeResult {
 
 export async function studioAddKeyframe(
   deps: AnimationToolDeps,
-  input: { animationId?: unknown; percent?: unknown; properties?: unknown },
-): Promise<ToolResult<StudioAddKeyframeResult>> {
+  input: { handle?: unknown; animationId?: unknown; percent?: unknown; properties?: unknown },
+  signal: AbortSignal = new AbortController().signal,
+): Promise<StudioWriteResult<StudioAddKeyframeResult>> {
   const animationId = readAnimationId(input.animationId);
   if (!animationId) {
-    return toolFailure("invalid", "animationId must be a non-empty string", INSPECT_HINT);
+    return preDispatchFailure(
+      "add-keyframe",
+      toolFailure("invalid", "animationId must be a non-empty string", INSPECT_HINT),
+    );
   }
   const percent = input.percent;
   if (typeof percent !== "number" || !Number.isFinite(percent) || percent < 0 || percent > 100) {
     // Validated here because nothing in the platform checks input against the
     // schema; the tool receives whatever the agent sent.
-    return toolFailure("invalid", "percent must be a number between 0 and 100");
+    return preDispatchFailure(
+      "add-keyframe",
+      toolFailure("invalid", "percent must be a number between 0 and 100"),
+    );
   }
   const raw = input.properties;
   if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
-    return toolFailure("invalid", "properties must be an object of GSAP property to value");
+    return preDispatchFailure(
+      "add-keyframe",
+      toolFailure("invalid", "properties must be an object of GSAP property to value"),
+    );
   }
   const properties: Record<string, number | string> = {};
   for (const [key, value] of Object.entries(raw)) {
+    if (isRawGsapExpression(value)) {
+      return preDispatchFailure(
+        "add-keyframe",
+        toolFailure("invalid", "raw JavaScript expressions are not accepted"),
+      );
+    }
     if (typeof value === "number" || typeof value === "string") properties[key] = value;
   }
   if (Object.keys(properties).length === 0) {
-    return toolFailure("invalid", "properties must contain at least one number or string value");
+    return preDispatchFailure(
+      "add-keyframe",
+      toolFailure("invalid", "properties must contain at least one number or string value"),
+    );
   }
-
-  const blocked = guard(deps);
-  if (blocked) return blocked;
-
-  await deps.addKeyframe(animationId, percent, properties);
-
-  return toolOk<StudioAddKeyframeResult>({ animationId, percent, properties, dispatched: true });
+  return runTargetedWrite(deps, {
+    handle: input.handle,
+    operation: "add-keyframe",
+    signal,
+    preflight: (selection) => animationBelongsToTarget(deps, selection, animationId),
+    write: async (selection) => {
+      await deps.addKeyframe(selection, animationId, percent, properties);
+      return dispatched({ animationId, percent, properties, dispatched: true }, false);
+    },
+  });
 }
 
 export interface StudioDeleteAnimationResult {
@@ -186,59 +241,81 @@ export interface StudioDeleteAnimationResult {
 
 export async function studioDeleteAnimation(
   deps: AnimationToolDeps,
-  input: { animationId?: unknown },
-): Promise<ToolResult<StudioDeleteAnimationResult>> {
+  input: { handle?: unknown; animationId?: unknown },
+  signal: AbortSignal = new AbortController().signal,
+): Promise<StudioWriteResult<StudioDeleteAnimationResult>> {
   const animationId = readAnimationId(input.animationId);
   if (!animationId) {
-    return toolFailure("invalid", "animationId must be a non-empty string", INSPECT_HINT);
+    return preDispatchFailure(
+      "delete-animation",
+      toolFailure("invalid", "animationId must be a non-empty string", INSPECT_HINT),
+    );
   }
-
-  const blocked = guard(deps);
-  if (blocked) return blocked;
-
-  deps.deleteAnimation(animationId);
-  return toolOk<StudioDeleteAnimationResult>({ animationId, dispatched: true });
+  return runTargetedWrite(deps, {
+    handle: input.handle,
+    operation: "delete-animation",
+    signal,
+    preflight: (selection) => animationBelongsToTarget(deps, selection, animationId),
+    write: async (selection) => {
+      const landed = await deps.deleteAnimation(selection, animationId);
+      if (!landed) {
+        return toolFailure(
+          "failed",
+          `the delete of ${animationId} did not land`,
+          "The animation id may be stale. studio_inspect lists the current ones.",
+        );
+      }
+      return dispatched({ animationId, dispatched: true }, false);
+    },
+  });
 }
 
-const DISPATCH_CAVEAT = `Reports what was dispatched, not what landed: the handler underneath does not report back. ${INSPECT_HINT}`;
+const SETTLEMENT_NOTE =
+  "Success means persistence and live-preview synchronization have finished. Inspect afterward when exact authored values matter.";
+const KEYFRAME_DISPATCH_CAVEAT = `Reports what was dispatched, not what landed: the keyframe actor does not report back. ${INSPECT_HINT}`;
 
 export const STUDIO_ADD_ANIMATION_INPUT_SCHEMA = {
   type: "object",
   properties: {
+    handle: { type: "string", description: "A source-safe element handle from studio_look." },
     method: { type: "string", enum: METHODS, description: "The GSAP method to add." },
   },
-  required: ["method"],
+  required: ["handle", "method"],
   additionalProperties: false,
 } as const;
 
 export const STUDIO_ADD_ANIMATION_DESCRIPTION = [
-  "Add a GSAP animation to the CURRENTLY SELECTED element. Call studio_select first.",
+  "Add a GSAP animation to one element using its source-safe handle from studio_look.",
   "It is inserted AT THE PLAYHEAD, which this tool does not control: call studio_seek first",
   "to choose when it starts. The result reports where the playhead actually was.",
-  DISPATCH_CAVEAT,
+  SETTLEMENT_NOTE,
+  WRITE_RECEIPT_DESCRIPTION,
 ].join(" ");
 
 export const STUDIO_UPDATE_ANIMATION_INPUT_SCHEMA = {
   type: "object",
   properties: {
+    handle: { type: "string", description: "A source-safe element handle from studio_look." },
     animationId: { type: "string", description: "An animation id from studio_inspect." },
     duration: { type: "number", minimum: 0, description: "Duration in seconds." },
     ease: { type: "string", description: "A GSAP ease, for example power2.out." },
     position: { type: "number", description: "Start position in seconds." },
   },
-  required: ["animationId"],
+  required: ["handle", "animationId"],
   additionalProperties: false,
 } as const;
 
 export const STUDIO_UPDATE_ANIMATION_DESCRIPTION = [
   "Change an existing animation's duration, ease or position.",
-  "This is the one animation tool that CONFIRMS its write, so a failure here is real",
-  "and usually means a stale animationId. Get current ids from studio_inspect.",
+  "It waits for persistence and live-preview synchronization before reporting success.",
+  "Get current ids from studio_inspect.",
+  WRITE_RECEIPT_DESCRIPTION,
 ].join(" ");
 
 export const STUDIO_ADD_KEYFRAME_INPUT_SCHEMA = {
   type: "object",
   properties: {
+    handle: { type: "string", description: "A source-safe element handle from studio_look." },
     animationId: { type: "string", description: "An animation id from studio_inspect." },
     percent: {
       type: "number",
@@ -251,26 +328,36 @@ export const STUDIO_ADD_KEYFRAME_INPUT_SCHEMA = {
       description: 'GSAP property to value, for example {"y": -50, "opacity": 0}.',
     },
   },
-  required: ["animationId", "percent", "properties"],
+  required: ["handle", "animationId", "percent", "properties"],
   additionalProperties: false,
 } as const;
 
 export const STUDIO_ADD_KEYFRAME_DESCRIPTION = [
   "Add a keyframe to an existing animation at a percentage through it.",
   "All the properties land in one commit, so they are one undo entry.",
-  DISPATCH_CAVEAT,
+  KEYFRAME_DISPATCH_CAVEAT,
+  WRITE_RECEIPT_DESCRIPTION,
 ].join(" ");
 
 export const STUDIO_DELETE_ANIMATION_INPUT_SCHEMA = {
   type: "object",
   properties: {
+    handle: { type: "string", description: "A source-safe element handle from studio_look." },
     animationId: { type: "string", description: "An animation id from studio_inspect." },
   },
-  required: ["animationId"],
+  required: ["handle", "animationId"],
   additionalProperties: false,
 } as const;
 
 export const STUDIO_DELETE_ANIMATION_DESCRIPTION = [
-  "Remove an animation from the currently selected element. Undo reverses it.",
-  DISPATCH_CAVEAT,
+  "Remove an animation from the element named by handle. Undo reverses it.",
+  SETTLEMENT_NOTE,
+  WRITE_RECEIPT_DESCRIPTION,
 ].join(" ");
+
+function preDispatchFailure<T extends object>(
+  operation: "add-animation" | "update-animation" | "add-keyframe" | "delete-animation",
+  failure: ToolFailure,
+): StudioWriteResult<T> {
+  return { ...failure, stage: "refused", operation };
+}