@hyperframes/studio 0.8.24 → 0.8.26

package/src/webmcp/useStudioAgentTools.test.tsx

@@ -3,9 +3,11 @@ import { act } from "react";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { mountReactHarness } from "../hooks/domSelectionTestHarness";
 import { writeStudioUiPreferences } from "../utils/studioUiPreferences";
+import { mintElementHandle } from "./handles";
 import { useStudioAgentTools, type StudioAgentToolsDeps } from "./useStudioAgentTools";
 import type { ModelContext, ModelContextRegisterToolOptions, ModelContextTool } from "./types";
 import type { StudioLookSnapshot } from "./tools/lookTools";
+import { previewDoc, selectionFor } from "./webmcpTestUtils";
 
 const trackEvent = vi.hoisted(() => vi.fn());
 vi.mock("../telemetry/client", () => ({ trackEvent }));
@@ -22,6 +24,7 @@ function snapshot(overrides: Partial<StudioLookSnapshot> = {}): StudioLookSnapsh
     duration: 10,
     isPlaying: false,
     elements: [],
+    scene: { status: "ready", items: [], drillInItem: null },
     selection: null,
     selectionAnimationCount: 0,
     history: { canUndo: false, canRedo: false, undoLabel: null, redoLabel: null },
@@ -50,10 +53,11 @@ function deps(overrides: Partial<StudioAgentToolsDeps> = {}): StudioAgentToolsDe
     moveTo: async () => undefined,
     resizeTo: async () => undefined,
     rotateTo: async () => undefined,
-    addAnimation: () => undefined,
+    addAnimation: async () => true,
     updateAnimation: async () => true,
     addKeyframe: async () => undefined,
-    deleteAnimation: () => undefined,
+    deleteAnimation: async () => true,
+    getAnimationsForSelection: async () => [],
     getGsapDiagnostics: () => ({
       animations: [],
       multipleTimelines: false,
@@ -63,6 +67,40 @@ function deps(overrides: Partial<StudioAgentToolsDeps> = {}): StudioAgentToolsDe
   };
 }
 
+async function executeRegistered<T>(
+  registered: ModelContextTool[],
+  name: string,
+  input: object,
+  signal: AbortSignal = new AbortController().signal,
+): Promise<T> {
+  const tool = registered.find((candidate) => candidate.name === name);
+  if (!tool) throw new Error(`expected ${name} to be registered`);
+  return (await tool.execute(input, { signal })) as T;
+}
+
+function mountedTargetDeps(overrides: Partial<StudioAgentToolsDeps> = {}) {
+  const doc = previewDoc('<h1 id="human">Human</h1><h1 id="agent">Agent</h1>');
+  const human = doc.getElementById("human") as HTMLElement;
+  const agent = doc.getElementById("agent") as HTMLElement;
+  const agentHandle = mintElementHandle({
+    projectId: "demo",
+    domId: "agent",
+    sourceFile: "index.html",
+    activeCompositionPath: "index.html",
+  });
+  if (!agentHandle) throw new Error("expected agent handle");
+  return {
+    agent,
+    agentHandle,
+    currentSelection: selectionFor(human),
+    deps: deps({
+      getPreviewDocument: () => doc,
+      buildSelection: async (element) => selectionFor(element),
+      ...overrides,
+    }),
+  };
+}
+
 /** Install a fake `document.modelContext` and report what got registered. */
 function installModelContext() {
   const registered: ModelContextTool[] = [];
@@ -80,6 +118,12 @@ function installModelContext() {
   return { registered, registerTool };
 }
 
+async function executeFirstRegistered<T>(registered: ModelContextTool[]): Promise<T> {
+  const look = registered[0];
+  if (!look) throw new Error("expected studio_look to be registered");
+  return (await look.execute({}, { signal: new AbortController().signal })) as T;
+}
+
 function removeModelContext() {
   Reflect.deleteProperty(document, "modelContext");
 }
@@ -170,12 +214,10 @@ describe("useStudioAgentTools", () => {
       harness?.rerenderWith(deps({ getSnapshot: () => snapshot({ currentTime: 42 }) }));
     });
 
-    const look = registered[0];
-    if (!look) throw new Error("expected studio_look to be registered");
-    const result = (await look.execute({}, { signal: new AbortController().signal })) as {
+    const result = await executeFirstRegistered<{
       ok: boolean;
       playhead: number;
-    };
+    }>(registered);
 
     expect(result.ok).toBe(true);
     expect(result.playhead).toBe(42);
@@ -257,14 +299,272 @@ describe("useStudioAgentTools", () => {
     });
     vi.spyOn(console, "error").mockImplementation(() => {});
 
-    const look = registered[0];
-    if (!look) throw new Error("expected studio_look to be registered");
-    const result = (await look.execute({}, { signal: new AbortController().signal })) as {
+    const result = await executeFirstRegistered<{
       ok: boolean;
       kind: string;
-    };
+    }>(registered);
 
     expect(result.ok).toBe(false);
     expect(result.kind).toBe("internal");
   });
+
+  it("requires a source-safe handle on every source-writing tool", async () => {
+    const { registered } = installModelContext();
+    await act(async () => mountTools(deps()));
+
+    for (const name of [
+      "studio_set_text",
+      "studio_set_style",
+      "studio_transform",
+      "studio_add_animation",
+      "studio_update_animation",
+      "studio_add_keyframe",
+      "studio_delete_animation",
+    ]) {
+      const schema = registered.find((tool) => tool.name === name)?.inputSchema as {
+        required?: string[];
+      };
+      expect(schema.required, name).toContain("handle");
+    }
+  });
+
+  it("binds a text write to the explicit handle even when human selection points elsewhere", async () => {
+    const { registered } = installModelContext();
+    const targeted = mountedTargetDeps();
+    const setText = vi.fn(
+      async () =>
+        ({
+          ok: true,
+          persistence: {
+            sourceFile: "index.html",
+            version: '"sha256:after"',
+            changed: true,
+          },
+        }) as const,
+    );
+    await act(async () => mountTools({ ...targeted.deps, setText }));
+
+    const result = await executeRegistered<{
+      ok: boolean;
+      stage: string;
+      changed: boolean;
+      target: { handle: string; sourceFile: string };
+    }>(registered, "studio_set_text", {
+      handle: targeted.agentHandle,
+      text: "Edited by agent",
+    });
+
+    expect(setText).toHaveBeenCalledWith(
+      expect.objectContaining({ element: targeted.agent }),
+      "Edited by agent",
+      "self",
+    );
+    expect(result).toMatchObject({
+      ok: true,
+      stage: "saved",
+      changed: true,
+      target: { handle: targeted.agentHandle, sourceFile: "index.html" },
+    });
+  });
+
+  it("refuses a locked target and an early abort before invoking the write actor", async () => {
+    const { registered } = installModelContext();
+    const setText = vi.fn();
+    const targeted = mountedTargetDeps({
+      buildSelection: async (element) => selectionFor(element, { isInsideLockedComposition: true }),
+    });
+    await act(async () => mountTools({ ...targeted.deps, setText }));
+
+    const locked = await executeRegistered<{ ok: boolean; stage: string }>(
+      registered,
+      "studio_set_text",
+      { handle: targeted.agentHandle, text: "No" },
+    );
+    const controller = new AbortController();
+    controller.abort();
+    const aborted = await executeRegistered<{ ok: boolean; stage: string; cancelRequested: true }>(
+      registered,
+      "studio_set_text",
+      { handle: targeted.agentHandle, text: "No" },
+      controller.signal,
+    );
+
+    expect(locked).toMatchObject({ ok: false, stage: "refused" });
+    expect(aborted).toMatchObject({ ok: false, stage: "refused", cancelRequested: true });
+    expect(setText).not.toHaveBeenCalled();
+  });
+
+  it("reports dispatched, saved, and verified only from their corresponding evidence", async () => {
+    const { registered } = installModelContext();
+    const targeted = mountedTargetDeps();
+    const box = { x: 0, y: 0, width: 100, height: 50 };
+    await act(async () =>
+      mountTools({
+        ...targeted.deps,
+        setText: async () => ({
+          ok: true,
+          persistence: {
+            sourceFile: "index.html",
+            version: '"sha256:after"',
+            changed: true,
+          },
+        }),
+        addAnimation: async () => true,
+        readBox: () => ({ ...box }),
+        resizeTo: async (_selection, next) => {
+          Object.assign(box, next);
+          return {
+            ok: true,
+            persistence: {
+              sourceFile: "index.html",
+              version: '"sha256:transform"',
+              changed: true,
+            },
+          } as const;
+        },
+      }),
+    );
+
+    const dispatched = await executeRegistered<{ stage: string }>(
+      registered,
+      "studio_add_animation",
+      { handle: targeted.agentHandle, method: "to" },
+    );
+    const saved = await executeRegistered<{ stage: string }>(registered, "studio_set_text", {
+      handle: targeted.agentHandle,
+      text: "Saved",
+    });
+    const verified = await executeRegistered<{ stage: string }>(registered, "studio_transform", {
+      handle: targeted.agentHandle,
+      width: 200,
+      height: 80,
+    });
+
+    expect(dispatched.stage).toBe("dispatched");
+    expect(saved.stage).toBe("saved");
+    expect(verified.stage).toBe("verified");
+  });
+
+  it("reports a matched no-op with its durable version without fabricating a change", async () => {
+    const { registered } = installModelContext();
+    const targeted = mountedTargetDeps();
+    await act(async () =>
+      mountTools({
+        ...targeted.deps,
+        setText: async () => ({
+          ok: true,
+          persistence: {
+            sourceFile: "index.html",
+            version: '"sha256:current"',
+            changed: false,
+          },
+        }),
+      }),
+    );
+
+    const result = await executeRegistered<{
+      ok: boolean;
+      stage: string;
+      changed: boolean;
+      evidence: { version: string };
+    }>(registered, "studio_set_text", {
+      handle: targeted.agentHandle,
+      text: "Agent",
+    });
+
+    expect(result).toMatchObject({
+      ok: true,
+      stage: "saved",
+      changed: false,
+      evidence: { version: '"sha256:current"' },
+    });
+  });
+
+  it("reports the actual saved outcome and late cancellation without promising rollback", async () => {
+    const { registered } = installModelContext();
+    const targeted = mountedTargetDeps();
+    let finish: (() => void) | undefined;
+    const setText = vi.fn(
+      () =>
+        new Promise<{
+          ok: true;
+          persistence: { sourceFile: string; version: string; changed: true };
+        }>((resolve) => {
+          finish = () =>
+            resolve({
+              ok: true,
+              persistence: {
+                sourceFile: "index.html",
+                version: '"sha256:late"',
+                changed: true,
+              },
+            });
+        }),
+    );
+    await act(async () => mountTools({ ...targeted.deps, setText }));
+    const controller = new AbortController();
+
+    const pending = executeRegistered<{
+      ok: boolean;
+      stage: string;
+      cancelRequested?: boolean;
+    }>(
+      registered,
+      "studio_set_text",
+      { handle: targeted.agentHandle, text: "Late" },
+      controller.signal,
+    );
+    await vi.waitFor(() => expect(setText).toHaveBeenCalledTimes(1));
+    controller.abort();
+    finish?.();
+
+    expect(await pending).toMatchObject({
+      ok: true,
+      stage: "saved",
+      cancelRequested: true,
+    });
+    expect(setText).toHaveBeenCalledTimes(1);
+  });
+
+  it("aggregates partial style evidence and uses the weakest applied assurance", async () => {
+    const { registered } = installModelContext();
+    const targeted = mountedTargetDeps();
+    const setStyle = vi.fn(async (_selection, property: string) => {
+      if (property === "left") return { ok: false, reason: "geometry-property" } as const;
+      if (property === "opacity") return { ok: true } as const;
+      return {
+        ok: true,
+        persistence: {
+          sourceFile: "index.html",
+          version: '"sha256:color"',
+          changed: true,
+        },
+      } as const;
+    });
+    await act(async () => mountTools({ ...targeted.deps, setStyle }));
+
+    const result = await executeRegistered<{
+      ok: boolean;
+      stage: string;
+      partial: boolean;
+      applied: Record<string, string>;
+      rejected: Record<string, string>;
+      propertyReceipts: Record<string, { stage: string }>;
+    }>(registered, "studio_set_style", {
+      handle: targeted.agentHandle,
+      styles: { color: "red", left: "10px", opacity: "0.5" },
+    });
+
+    expect(result).toMatchObject({
+      ok: true,
+      stage: "dispatched",
+      partial: true,
+      applied: { color: "red", opacity: "0.5" },
+      rejected: { left: "geometry-property" },
+      propertyReceipts: {
+        color: { stage: "saved" },
+        opacity: { stage: "dispatched" },
+      },
+    });
+  });
 });

package/src/webmcp/useStudioAgentTools.ts

@@ -177,8 +177,10 @@ function buildStudioTools(depsRef: { readonly current: StudioAgentToolsDeps }):
       description: STUDIO_SET_TEXT_DESCRIPTION,
       inputSchema: STUDIO_SET_TEXT_INPUT_SCHEMA,
       annotations: { readOnlyHint: false, untrustedContentHint: true },
-      execute: (input): Promise<ToolResult<StudioSetTextResult>> =>
-        runToolBody("studio_set_text", () => studioSetText(depsRef.current, input)),
+      execute: (input, { signal }): Promise<ToolResult<StudioSetTextResult>> =>
+        runToolBody<StudioSetTextResult>("studio_set_text", () =>
+          studioSetText(depsRef.current, input, signal),
+        ),
     },
     {
       name: "studio_set_style",
@@ -186,8 +188,10 @@ function buildStudioTools(depsRef: { readonly current: StudioAgentToolsDeps }):
       description: STUDIO_SET_STYLE_DESCRIPTION,
       inputSchema: STUDIO_SET_STYLE_INPUT_SCHEMA,
       annotations: { readOnlyHint: false },
-      execute: (input): Promise<ToolResult<StudioSetStyleResult>> =>
-        runToolBody("studio_set_style", () => studioSetStyle(depsRef.current, input)),
+      execute: (input, { signal }): Promise<ToolResult<StudioSetStyleResult>> =>
+        runToolBody<StudioSetStyleResult>("studio_set_style", () =>
+          studioSetStyle(depsRef.current, input, signal),
+        ),
     },
     {
       name: "studio_transform",
@@ -195,9 +199,9 @@ function buildStudioTools(depsRef: { readonly current: StudioAgentToolsDeps }):
       description: STUDIO_TRANSFORM_DESCRIPTION,
       inputSchema: STUDIO_TRANSFORM_INPUT_SCHEMA,
       annotations: { readOnlyHint: false },
-      execute: (input): Promise<ToolResult<StudioTransformResult>> =>
-        runToolBody("studio_transform", () =>
-          studioTransform(depsRef.current, input as StudioTransformInput),
+      execute: (input, { signal }): Promise<ToolResult<StudioTransformResult>> =>
+        runToolBody<StudioTransformResult>("studio_transform", () =>
+          studioTransform(depsRef.current, input as StudioTransformInput, signal),
         ),
     },
     {
@@ -206,8 +210,10 @@ function buildStudioTools(depsRef: { readonly current: StudioAgentToolsDeps }):
       description: STUDIO_ADD_ANIMATION_DESCRIPTION,
       inputSchema: STUDIO_ADD_ANIMATION_INPUT_SCHEMA,
       annotations: { readOnlyHint: false },
-      execute: (input): Promise<ToolResult<StudioAddAnimationResult>> =>
-        runToolBody("studio_add_animation", () => studioAddAnimation(depsRef.current, input)),
+      execute: (input, { signal }): Promise<ToolResult<StudioAddAnimationResult>> =>
+        runToolBody<StudioAddAnimationResult>("studio_add_animation", () =>
+          studioAddAnimation(depsRef.current, input, signal),
+        ),
     },
     {
       name: "studio_update_animation",
@@ -215,8 +221,10 @@ function buildStudioTools(depsRef: { readonly current: StudioAgentToolsDeps }):
       description: STUDIO_UPDATE_ANIMATION_DESCRIPTION,
       inputSchema: STUDIO_UPDATE_ANIMATION_INPUT_SCHEMA,
       annotations: { readOnlyHint: false },
-      execute: (input): Promise<ToolResult<StudioUpdateAnimationResult>> =>
-        runToolBody("studio_update_animation", () => studioUpdateAnimation(depsRef.current, input)),
+      execute: (input, { signal }): Promise<ToolResult<StudioUpdateAnimationResult>> =>
+        runToolBody<StudioUpdateAnimationResult>("studio_update_animation", () =>
+          studioUpdateAnimation(depsRef.current, input, signal),
+        ),
     },
     {
       name: "studio_add_keyframe",
@@ -224,8 +232,10 @@ function buildStudioTools(depsRef: { readonly current: StudioAgentToolsDeps }):
       description: STUDIO_ADD_KEYFRAME_DESCRIPTION,
       inputSchema: STUDIO_ADD_KEYFRAME_INPUT_SCHEMA,
       annotations: { readOnlyHint: false },
-      execute: (input): Promise<ToolResult<StudioAddKeyframeResult>> =>
-        runToolBody("studio_add_keyframe", () => studioAddKeyframe(depsRef.current, input)),
+      execute: (input, { signal }): Promise<ToolResult<StudioAddKeyframeResult>> =>
+        runToolBody<StudioAddKeyframeResult>("studio_add_keyframe", () =>
+          studioAddKeyframe(depsRef.current, input, signal),
+        ),
     },
     {
       name: "studio_delete_animation",
@@ -233,8 +243,10 @@ function buildStudioTools(depsRef: { readonly current: StudioAgentToolsDeps }):
       description: STUDIO_DELETE_ANIMATION_DESCRIPTION,
       inputSchema: STUDIO_DELETE_ANIMATION_INPUT_SCHEMA,
       annotations: { readOnlyHint: false },
-      execute: (input): Promise<ToolResult<StudioDeleteAnimationResult>> =>
-        runToolBody("studio_delete_animation", () => studioDeleteAnimation(depsRef.current, input)),
+      execute: (input, { signal }): Promise<ToolResult<StudioDeleteAnimationResult>> =>
+        runToolBody<StudioDeleteAnimationResult>("studio_delete_animation", () =>
+          studioDeleteAnimation(depsRef.current, input, signal),
+        ),
     },
   ];
 }

package/src/webmcp/webmcpTestUtils.ts

@@ -8,6 +8,9 @@
 import { expect } from "vitest";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import type { ToolFailure, ToolResult } from "./toolResult";
+import type { SelectionToolDeps } from "./tools/selectionTools";
+import { mintElementHandle } from "./handles";
+import type { TargetedWriteDeps } from "./writeCoordinator";
 
 /**
  * An element inside a real iframe, which is where Studio's chrome expects to
@@ -78,6 +81,40 @@ export function selectionFor(
   };
 }
 
+export function selectionToolDeps(overrides: Partial<SelectionToolDeps> = {}): SelectionToolDeps {
+  return {
+    getPreviewDocument: () => null,
+    getCompositionPath: () => "index.html",
+    getProjectId: () => "project-a",
+    buildSelection: async (element) => selectionFor(element),
+    applySelection: () => undefined,
+    requestSeek: () => undefined,
+    readPlayhead: () => ({ currentTime: 0, duration: 10, isPlaying: false }),
+    ...overrides,
+  };
+}
+
+export function sourceHandle(domId: string, projectId = "project-a"): string {
+  const handle = mintElementHandle({
+    projectId,
+    domId,
+    sourceFile: "index.html",
+    activeCompositionPath: "index.html",
+  });
+  if (!handle) throw new Error(`expected source handle for #${domId}`);
+  return handle;
+}
+
+export function targetedWriteDeps(selection: DomEditSelection): TargetedWriteDeps {
+  return {
+    getPreviewDocument: () => selection.element.ownerDocument,
+    getProjectId: () => "project-a",
+    getWriteBlockedReason: () => null,
+    buildSelection: async () => selection,
+    applySelection: () => undefined,
+  };
+}
+
 export function expectOk<T>(result: ToolResult<T>): { ok: true } & T {
   expect(result.ok, `expected ok, got ${JSON.stringify(result)}`).toBe(true);
   if (!result.ok) throw new Error("unreachable");