@hyperframes/studio 0.8.20 → 0.8.21

package/src/webmcp/StudioAgentTools.tsx

@@ -1,8 +1,8 @@
-import { useCallback } from "react";
-import { useDomEditSelectionContext } from "../contexts/DomEditContext";
+import { useCallback, useMemo } from "react";
+import { useDomEditActionsContext, useDomEditSelectionContext } from "../contexts/DomEditContext";
 import { useStudioShellContext } from "../contexts/StudioContext";
 import { usePlayerStore } from "../player";
-import { useStudioAgentTools } from "./useStudioAgentTools";
+import { useStudioAgentTools, type StudioAgentToolsDeps } from "./useStudioAgentTools";
 import type { StudioLookSnapshot } from "./tools/lookTools";
 
 /**
@@ -12,14 +12,32 @@ import type { StudioLookSnapshot } from "./tools/lookTools";
  * contexts are only readable below `DomEditProvider`, which `App` renders, and
  * `App.tsx` sits three lines under the 600-line cap.
  *
- * The player store is read IMPERATIVELY through `getState()` inside the
- * snapshot callback rather than subscribed to. Subscribing to `currentTime`
- * would re-render this component on every animation frame during playback for
- * a value nothing here displays.
+ * The player store is read IMPERATIVELY through `getState()` rather than
+ * subscribed to. Subscribing to `currentTime` would re-render this component on
+ * every animation frame during playback for a value nothing here displays.
  */
 export function StudioAgentTools() {
-  const { projectId, activeCompPath, editHistory } = useStudioShellContext();
-  const { domEditSelection, selectedGsapAnimations } = useDomEditSelectionContext();
+  const { projectId, activeCompPath, editHistory, writeBlockedReason } = useStudioShellContext();
+  const {
+    domEditSelection,
+    selectedGsapAnimations,
+    gsapMultipleTimelines,
+    gsapUnsupportedTimelinePattern,
+  } = useDomEditSelectionContext();
+  const {
+    previewIframeRef,
+    buildDomSelectionFromTarget,
+    applyDomSelection,
+    handleDomTextCommit,
+    handleDomStyleCommit,
+    handleDomPathOffsetCommit,
+    handleDomBoxSizeCommit,
+    handleDomRotationCommit,
+    handleGsapAddAnimation,
+    handleGsapUpdateMeta,
+    handleGsapAddKeyframeBatch,
+    handleGsapDeleteAnimation,
+  } = useDomEditActionsContext();
 
   const getSnapshot = useCallback((): StudioLookSnapshot => {
     const player = usePlayerStore.getState();
@@ -41,6 +59,83 @@ export function StudioAgentTools() {
     };
   }, [projectId, activeCompPath, domEditSelection, selectedGsapAnimations, editHistory]);
 
-  useStudioAgentTools({ getSnapshot });
+  const deps = useMemo<StudioAgentToolsDeps>(
+    () => ({
+      getSnapshot,
+      getPreviewDocument: () => previewIframeRef.current?.contentDocument ?? null,
+      buildSelection: (element) => buildDomSelectionFromTarget(element),
+      applySelection: (selection) => applyDomSelection(selection, { revealPanel: true }),
+      requestSeek: (time) => usePlayerStore.getState().requestSeek(time),
+      readPlayhead: () => {
+        const player = usePlayerStore.getState();
+        return {
+          currentTime: player.currentTime,
+          duration: player.duration,
+          isPlaying: player.isPlaying,
+        };
+      },
+      getProjectId: () => projectId,
+      getCompositionPath: () => activeCompPath,
+      // HEAD, not GET: the tool only needs to know the frame renders. Pulling
+      // the PNG here would download it once for nothing, since the agent
+      // fetches the URL itself.
+      probeFrame: async (url) => {
+        try {
+          const response = await fetch(url, { method: "HEAD" });
+          return { ok: response.ok, status: response.status };
+        } catch {
+          return { ok: false, status: 0 };
+        }
+      },
+      wait: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+      getCurrentSelection: () => domEditSelection,
+      getWriteBlockedReason: () => writeBlockedReason,
+      setText: (value, fieldKey) => handleDomTextCommit(value, fieldKey),
+      setStyle: (property, value) => handleDomStyleCommit(property, value),
+      // Measured, not authored: the tool compares this before and after to
+      // tell a real change from a handler that did nothing and resolved.
+      readBox: (selection) => {
+        const rect = selection.element.getBoundingClientRect();
+        return { x: rect.x, y: rect.y, width: rect.width, height: rect.height };
+      },
+      moveTo: (selection, next) => handleDomPathOffsetCommit(selection, next),
+      resizeTo: (selection, next) => handleDomBoxSizeCommit(selection, next),
+      rotateTo: (selection, next) => handleDomRotationCommit(selection, next),
+      addAnimation: (method) => handleGsapAddAnimation(method),
+      updateAnimation: (animationId, updates) => handleGsapUpdateMeta(animationId, updates),
+      addKeyframe: (animationId, percent, properties) =>
+        handleGsapAddKeyframeBatch(animationId, percent, properties),
+      deleteAnimation: (animationId) => handleGsapDeleteAnimation(animationId),
+      getGsapDiagnostics: () => ({
+        animations: selectedGsapAnimations,
+        multipleTimelines: gsapMultipleTimelines,
+        unsupportedTimelinePattern: gsapUnsupportedTimelinePattern,
+      }),
+    }),
+    [
+      getSnapshot,
+      previewIframeRef,
+      buildDomSelectionFromTarget,
+      applyDomSelection,
+      projectId,
+      activeCompPath,
+      writeBlockedReason,
+      handleDomTextCommit,
+      handleDomStyleCommit,
+      handleDomPathOffsetCommit,
+      handleDomBoxSizeCommit,
+      handleDomRotationCommit,
+      handleGsapAddAnimation,
+      handleGsapUpdateMeta,
+      handleGsapAddKeyframeBatch,
+      handleGsapDeleteAnimation,
+      domEditSelection,
+      selectedGsapAnimations,
+      gsapMultipleTimelines,
+      gsapUnsupportedTimelinePattern,
+    ],
+  );
+
+  useStudioAgentTools(deps);
   return null;
 }

package/src/webmcp/toolResult.ts

@@ -36,7 +36,7 @@ export function toolOk<T extends object>(value: T): { ok: true } & T {
   return { ok: true, ...value };
 }
 
-function toolFailure(kind: ToolFailureKind, reason: string, hint?: string): ToolFailure {
+export function toolFailure(kind: ToolFailureKind, reason: string, hint?: string): ToolFailure {
   return hint ? { ok: false, kind, reason, hint } : { ok: false, kind, reason };
 }
 

package/src/webmcp/tools/animationTools.test.ts

@@ -0,0 +1,244 @@
+// @vitest-environment jsdom
+import { describe, expect, it, vi } from "vitest";
+import {
+  studioAddAnimation,
+  studioAddKeyframe,
+  studioDeleteAnimation,
+  studioUpdateAnimation,
+  type AnimationToolDeps,
+  type StudioAddAnimationResult,
+  type StudioAddKeyframeResult,
+  type StudioUpdateAnimationResult,
+} from "./animationTools";
+import { expectFailure, expectOk, previewElement, selectionFor } from "../webmcpTestUtils";
+
+function animationDeps(overrides: Partial<AnimationToolDeps> = {}): AnimationToolDeps {
+  const element = previewElement('<h1 id="headline">Ship it</h1>', "headline");
+  return {
+    getCurrentSelection: () => selectionFor(element),
+    getWriteBlockedReason: () => null,
+    readPlayhead: () => ({ currentTime: 2.4, duration: 10, isPlaying: false }),
+    addAnimation: () => undefined,
+    updateAnimation: async () => true,
+    addKeyframe: async () => undefined,
+    deleteAnimation: () => undefined,
+    ...overrides,
+  };
+}
+
+describe("studioAddAnimation", () => {
+  it("reports where the playhead actually was, not a position the caller chose", async () => {
+    // The handler reads the playhead itself and ignores any position argument,
+    // so echoing one back would report a number that had no effect.
+    const addAnimation = vi.fn();
+
+    const result = await studioAddAnimation(
+      animationDeps({
+        addAnimation,
+        readPlayhead: () => ({ currentTime: 7.25, duration: 10, isPlaying: false }),
+      }),
+      { method: "from" },
+    );
+
+    const ok = expectOk<StudioAddAnimationResult>(result);
+    expect(ok.insertedAtSeconds).toBe(7.25);
+    expect(ok.method).toBe("from");
+    expect(addAnimation).toHaveBeenCalledWith("from");
+  });
+
+  it("marks the result as dispatched rather than claiming it landed", async () => {
+    // `handleGsapAddAnimation` is fire-and-forget and returns nothing, so there
+    // is no honest success signal to report.
+    const result = await studioAddAnimation(animationDeps(), { method: "to" });
+
+    expect(expectOk<StudioAddAnimationResult>(result).dispatched).toBe(true);
+  });
+
+  it("rejects an unknown method without dispatching", async () => {
+    const addAnimation = vi.fn();
+
+    const result = expectFailure(
+      await studioAddAnimation(animationDeps({ addAnimation }), { method: "wiggle" }),
+    );
+
+    expect(result.kind).toBe("invalid");
+    expect(addAnimation).not.toHaveBeenCalled();
+  });
+
+  it("refuses while a write is blocked, and when nothing is selected", async () => {
+    const addAnimation = vi.fn();
+
+    const paused = expectFailure(
+      await studioAddAnimation(
+        animationDeps({ getWriteBlockedReason: () => "Auto-save is paused", addAnimation }),
+        { method: "to" },
+      ),
+    );
+    const unselected = expectFailure(
+      await studioAddAnimation(animationDeps({ getCurrentSelection: () => null, addAnimation }), {
+        method: "to",
+      }),
+    );
+
+    expect(paused.kind).toBe("blocked");
+    expect(unselected.kind).toBe("invalid");
+    expect(addAnimation).not.toHaveBeenCalled();
+  });
+});
+
+describe("studioUpdateAnimation", () => {
+  it("confirms the write, because this handler actually reports back", async () => {
+    const updateAnimation = vi.fn(async () => true);
+
+    const result = await studioUpdateAnimation(animationDeps({ updateAnimation }), {
+      animationId: "anim-1",
+      ease: "power2.out",
+      duration: 1.5,
+    });
+
+    const ok = expectOk<StudioUpdateAnimationResult>(result);
+    expect(ok.updated).toEqual({ duration: 1.5, ease: "power2.out" });
+    expect(updateAnimation).toHaveBeenCalledWith("anim-1", {
+      duration: 1.5,
+      ease: "power2.out",
+    });
+  });
+
+  it("reports a false return as a real failure", async () => {
+    const result = expectFailure(
+      await studioUpdateAnimation(animationDeps({ updateAnimation: async () => false }), {
+        animationId: "anim-gone",
+        ease: "none",
+      }),
+    );
+
+    expect(result.kind).toBe("failed");
+    expect(result.hint).toMatch(/stale/);
+  });
+
+  it("rules out the no-selection case BEFORE dispatch, so a false is unambiguous", async () => {
+    // The handler answers `false` for both "nothing selected" and "the write
+    // failed". Eliminating one beforehand is what makes the other legible.
+    const updateAnimation = vi.fn(async () => false);
+
+    const result = expectFailure(
+      await studioUpdateAnimation(
+        animationDeps({ getCurrentSelection: () => null, updateAnimation }),
+        { animationId: "anim-1", ease: "none" },
+      ),
+    );
+
+    expect(result.kind).toBe("invalid");
+    expect(result.reason).toMatch(/nothing is selected/);
+    expect(updateAnimation).not.toHaveBeenCalled();
+  });
+
+  it("requires at least one field, and rejects a negative duration", async () => {
+    const deps = animationDeps();
+
+    expect(expectFailure(await studioUpdateAnimation(deps, { animationId: "a" })).reason).toMatch(
+      /at least one/,
+    );
+    expect(
+      expectFailure(await studioUpdateAnimation(deps, { animationId: "a", duration: -1 })).reason,
+    ).toMatch(/negative/);
+  });
+
+  it("rejects a blank animation id", async () => {
+    const updateAnimation = vi.fn();
+
+    const result = expectFailure(
+      await studioUpdateAnimation(animationDeps({ updateAnimation }), {
+        animationId: "   ",
+        ease: "none",
+      }),
+    );
+
+    expect(result.kind).toBe("invalid");
+    expect(updateAnimation).not.toHaveBeenCalled();
+  });
+});
+
+describe("studioAddKeyframe", () => {
+  it("passes every property through in one commit", async () => {
+    const addKeyframe = vi.fn(async () => undefined);
+
+    const result = await studioAddKeyframe(animationDeps({ addKeyframe }), {
+      animationId: "anim-1",
+      percent: 50,
+      properties: { y: -50, opacity: 0 },
+    });
+
+    const ok = expectOk<StudioAddKeyframeResult>(result);
+    expect(ok.properties).toEqual({ y: -50, opacity: 0 });
+    // One call, so one undo entry, rather than one per property.
+    expect(addKeyframe).toHaveBeenCalledTimes(1);
+    expect(addKeyframe).toHaveBeenCalledWith("anim-1", 50, { y: -50, opacity: 0 });
+  });
+
+  it("validates percent itself, because the platform does not", async () => {
+    // Nothing checks the input object against inputSchema, so the tool receives
+    // whatever the agent sent.
+    const addKeyframe = vi.fn();
+    const deps = animationDeps({ addKeyframe });
+
+    for (const percent of [-1, 101, Number.NaN, "50"]) {
+      const result = expectFailure(
+        await studioAddKeyframe(deps, { animationId: "a", percent, properties: { y: 1 } }),
+      );
+      expect(result.kind).toBe("invalid");
+    }
+    expect(addKeyframe).not.toHaveBeenCalled();
+  });
+
+  it("rejects properties that carry no usable value", async () => {
+    const addKeyframe = vi.fn();
+    const deps = animationDeps({ addKeyframe });
+
+    for (const properties of [{}, { y: null }, [], "y:1"]) {
+      const result = expectFailure(
+        await studioAddKeyframe(deps, { animationId: "a", percent: 50, properties }),
+      );
+      expect(result.kind).toBe("invalid");
+    }
+    expect(addKeyframe).not.toHaveBeenCalled();
+  });
+
+  it("accepts 0 and 100 as the ends of the tween", async () => {
+    for (const percent of [0, 100]) {
+      const result = await studioAddKeyframe(animationDeps(), {
+        animationId: "a",
+        percent,
+        properties: { y: 1 },
+      });
+      expect(expectOk<StudioAddKeyframeResult>(result).percent).toBe(percent);
+    }
+  });
+});
+
+describe("studioDeleteAnimation", () => {
+  it("dispatches the delete and says so", async () => {
+    const deleteAnimation = vi.fn();
+
+    const result = await studioDeleteAnimation(animationDeps({ deleteAnimation }), {
+      animationId: "anim-1",
+    });
+
+    expect(result.ok).toBe(true);
+    expect(deleteAnimation).toHaveBeenCalledWith("anim-1");
+  });
+
+  it("refuses while a write is blocked", async () => {
+    const deleteAnimation = vi.fn();
+
+    const result = expectFailure(
+      await studioDeleteAnimation(
+        animationDeps({ getWriteBlockedReason: () => "Auto-save is paused", deleteAnimation }),
+        { animationId: "anim-1" },
+      ),
+    );
+
+    expect(result.kind).toBe("blocked");
+    expect(deleteAnimation).not.toHaveBeenCalled();
+  });
+});

package/src/webmcp/tools/animationTools.ts

@@ -0,0 +1,276 @@
+/**
+ * `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.
+ */
+
+import type { DomEditSelection } from "../../components/editor/domEditingTypes";
+import { toolFailure, toolOk, type ToolFailure, type ToolResult } from "../toolResult";
+
+export type GsapMethod = "to" | "from" | "set" | "fromTo";
+
+const METHODS: readonly GsapMethod[] = ["to", "from", "set", "fromTo"];
+
+export interface AnimationToolDeps {
+  getCurrentSelection: () => DomEditSelection | null;
+  getWriteBlockedReason: () => string | null;
+  readPlayhead: () => { currentTime: number; duration: number; isPlaying: boolean };
+  addAnimation: (method: GsapMethod) => void;
+  updateAnimation: (
+    animationId: string,
+    updates: { duration?: number; ease?: string; position?: number },
+  ) => Promise<boolean>;
+  addKeyframe: (
+    animationId: string,
+    percent: number,
+    properties: Record<string, number | string>,
+  ) => Promise<void>;
+  deleteAnimation: (animationId: string) => void;
+}
+
+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;
+}
+
+function readAnimationId(value: unknown): string | null {
+  return typeof value === "string" && value.trim() ? value : null;
+}
+
+export interface StudioAddAnimationResult {
+  method: GsapMethod;
+  /** Where it was inserted, which is the playhead, not a value you supplied. */
+  insertedAtSeconds: number;
+  dispatched: true;
+}
+
+export async function studioAddAnimation(
+  deps: AnimationToolDeps,
+  input: { method?: unknown },
+): Promise<ToolResult<StudioAddAnimationResult>> {
+  const method = METHODS.find((candidate) => candidate === input.method);
+  if (!method) {
+    return 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,
+  });
+}
+
+export interface StudioUpdateAnimationResult {
+  animationId: string;
+  updated: { duration?: number; ease?: string; position?: number };
+}
+
+export async function studioUpdateAnimation(
+  deps: AnimationToolDeps,
+  input: { animationId?: unknown; duration?: unknown; ease?: unknown; position?: unknown },
+): Promise<ToolResult<StudioUpdateAnimationResult>> {
+  const animationId = readAnimationId(input.animationId);
+  if (!animationId) {
+    return 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");
+    updates.duration = input.duration;
+  }
+  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 toolOk<StudioUpdateAnimationResult>({ animationId, updated: updates });
+}
+
+export interface StudioAddKeyframeResult {
+  animationId: string;
+  percent: number;
+  properties: Record<string, number | string>;
+  dispatched: true;
+}
+
+export async function studioAddKeyframe(
+  deps: AnimationToolDeps,
+  input: { animationId?: unknown; percent?: unknown; properties?: unknown },
+): Promise<ToolResult<StudioAddKeyframeResult>> {
+  const animationId = readAnimationId(input.animationId);
+  if (!animationId) {
+    return 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");
+  }
+  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");
+  }
+  const properties: Record<string, number | string> = {};
+  for (const [key, value] of Object.entries(raw)) {
+    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");
+  }
+
+  const blocked = guard(deps);
+  if (blocked) return blocked;
+
+  await deps.addKeyframe(animationId, percent, properties);
+
+  return toolOk<StudioAddKeyframeResult>({ animationId, percent, properties, dispatched: true });
+}
+
+export interface StudioDeleteAnimationResult {
+  animationId: string;
+  dispatched: true;
+}
+
+export async function studioDeleteAnimation(
+  deps: AnimationToolDeps,
+  input: { animationId?: unknown },
+): Promise<ToolResult<StudioDeleteAnimationResult>> {
+  const animationId = readAnimationId(input.animationId);
+  if (!animationId) {
+    return 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 });
+}
+
+const DISPATCH_CAVEAT = `Reports what was dispatched, not what landed: the handler underneath does not report back. ${INSPECT_HINT}`;
+
+export const STUDIO_ADD_ANIMATION_INPUT_SCHEMA = {
+  type: "object",
+  properties: {
+    method: { type: "string", enum: METHODS, description: "The GSAP method to add." },
+  },
+  required: ["method"],
+  additionalProperties: false,
+} as const;
+
+export const STUDIO_ADD_ANIMATION_DESCRIPTION = [
+  "Add a GSAP animation to the CURRENTLY SELECTED element. Call studio_select first.",
+  "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,
+].join(" ");
+
+export const STUDIO_UPDATE_ANIMATION_INPUT_SCHEMA = {
+  type: "object",
+  properties: {
+    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"],
+  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.",
+].join(" ");
+
+export const STUDIO_ADD_KEYFRAME_INPUT_SCHEMA = {
+  type: "object",
+  properties: {
+    animationId: { type: "string", description: "An animation id from studio_inspect." },
+    percent: {
+      type: "number",
+      minimum: 0,
+      maximum: 100,
+      description: "Where in the tween, 0 to 100.",
+    },
+    properties: {
+      type: "object",
+      description: 'GSAP property to value, for example {"y": -50, "opacity": 0}.',
+    },
+  },
+  required: ["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,
+].join(" ");
+
+export const STUDIO_DELETE_ANIMATION_INPUT_SCHEMA = {
+  type: "object",
+  properties: {
+    animationId: { type: "string", description: "An animation id from studio_inspect." },
+  },
+  required: ["animationId"],
+  additionalProperties: false,
+} as const;
+
+export const STUDIO_DELETE_ANIMATION_DESCRIPTION = [
+  "Remove an animation from the currently selected element. Undo reverses it.",
+  DISPATCH_CAVEAT,
+].join(" ");