@hyperframes/studio 0.8.19 → 0.8.21

package/src/webmcp/useStudioAgentTools.test.tsx

@@ -29,6 +29,40 @@ function snapshot(overrides: Partial<StudioLookSnapshot> = {}): StudioLookSnapsh
   };
 }
 
+/** Full deps with inert defaults; override only what the test is about. */
+function deps(overrides: Partial<StudioAgentToolsDeps> = {}): StudioAgentToolsDeps {
+  return {
+    getSnapshot: () => snapshot(),
+    getPreviewDocument: () => null,
+    buildSelection: async () => null,
+    applySelection: () => undefined,
+    requestSeek: () => undefined,
+    readPlayhead: () => ({ currentTime: 0, duration: 10, isPlaying: false }),
+    getProjectId: () => "demo",
+    getCompositionPath: () => "index.html",
+    probeFrame: async () => ({ ok: true, status: 200 }),
+    wait: async () => undefined,
+    getCurrentSelection: () => null,
+    getWriteBlockedReason: () => null,
+    setText: async () => ({ ok: true }),
+    setStyle: async () => ({ ok: true }),
+    readBox: () => ({ x: 0, y: 0, width: 100, height: 50 }),
+    moveTo: async () => undefined,
+    resizeTo: async () => undefined,
+    rotateTo: async () => undefined,
+    addAnimation: () => undefined,
+    updateAnimation: async () => true,
+    addKeyframe: async () => undefined,
+    deleteAnimation: () => undefined,
+    getGsapDiagnostics: () => ({
+      animations: [],
+      multipleTimelines: false,
+      unsupportedTimelinePattern: false,
+    }),
+    ...overrides,
+  };
+}
+
 /** Install a fake `document.modelContext` and report what got registered. */
 function installModelContext() {
   const registered: ModelContextTool[] = [];
@@ -50,12 +84,12 @@ function removeModelContext() {
   Reflect.deleteProperty(document, "modelContext");
 }
 
-function mountTools(deps: StudioAgentToolsDeps) {
+function mountTools(initial: StudioAgentToolsDeps) {
   function Probe({ current }: { current: StudioAgentToolsDeps }) {
     useStudioAgentTools(current);
     return null;
   }
-  const root = mountReactHarness(<Probe current={deps} />);
+  const root = mountReactHarness(<Probe current={initial} />);
   cleanup = () => act(() => root.unmount());
   return {
     rerenderWith(next: StudioAgentToolsDeps) {
@@ -82,10 +116,23 @@ describe("useStudioAgentTools", () => {
     const { registered } = installModelContext();
 
     await act(async () => {
-      mountTools({ getSnapshot: () => snapshot() });
+      mountTools(deps({ getSnapshot: () => snapshot() }));
     });
 
-    expect(registered.map((tool) => tool.name)).toEqual(["studio_look"]);
+    expect(registered.map((tool) => tool.name)).toEqual([
+      "studio_look",
+      "studio_select",
+      "studio_seek",
+      "studio_frame",
+      "studio_inspect",
+      "studio_set_text",
+      "studio_set_style",
+      "studio_transform",
+      "studio_add_animation",
+      "studio_update_animation",
+      "studio_add_keyframe",
+      "studio_delete_animation",
+    ]);
     expect(trackEvent).toHaveBeenCalledWith("webmcp.native_present");
   });
 
@@ -97,16 +144,16 @@ describe("useStudioAgentTools", () => {
 
     let harness: ReturnType<typeof mountTools> | null = null;
     await act(async () => {
-      harness = mountTools({ getSnapshot: () => snapshot() });
+      harness = mountTools(deps({ getSnapshot: () => snapshot() }));
     });
-    expect(registerTool).toHaveBeenCalledTimes(1);
+    expect(registerTool).toHaveBeenCalledTimes(12);
 
     await act(async () => {
-      harness?.rerenderWith({ getSnapshot: () => snapshot({ currentTime: 5 }) });
-      harness?.rerenderWith({ getSnapshot: () => snapshot({ currentTime: 6 }) });
+      harness?.rerenderWith(deps({ getSnapshot: () => snapshot({ currentTime: 5 }) }));
+      harness?.rerenderWith(deps({ getSnapshot: () => snapshot({ currentTime: 6 }) }));
     });
 
-    expect(registerTool).toHaveBeenCalledTimes(1);
+    expect(registerTool).toHaveBeenCalledTimes(12);
   });
 
   it("executes against the LATEST deps, not the ones present at registration", async () => {
@@ -116,11 +163,11 @@ describe("useStudioAgentTools", () => {
 
     let harness: ReturnType<typeof mountTools> | null = null;
     await act(async () => {
-      harness = mountTools({ getSnapshot: () => snapshot({ currentTime: 1 }) });
+      harness = mountTools(deps({ getSnapshot: () => snapshot({ currentTime: 1 }) }));
     });
 
     await act(async () => {
-      harness?.rerenderWith({ getSnapshot: () => snapshot({ currentTime: 42 }) });
+      harness?.rerenderWith(deps({ getSnapshot: () => snapshot({ currentTime: 42 }) }));
     });
 
     const look = registered[0];
@@ -138,7 +185,7 @@ describe("useStudioAgentTools", () => {
     const { registerTool } = installModelContext();
 
     await act(async () => {
-      mountTools({ getSnapshot: () => snapshot() });
+      mountTools(deps({ getSnapshot: () => snapshot() }));
     });
     const signal = registerTool.mock.calls[0]?.[1]?.signal;
     expect(signal?.aborted).toBe(false);
@@ -153,7 +200,7 @@ describe("useStudioAgentTools", () => {
     removeModelContext();
 
     await act(async () => {
-      mountTools({ getSnapshot: () => snapshot() });
+      mountTools(deps({ getSnapshot: () => snapshot() }));
     });
 
     // The assertion is that mounting did not throw; a browser without the
@@ -166,7 +213,7 @@ describe("useStudioAgentTools", () => {
     const { registerTool } = installModelContext();
 
     await act(async () => {
-      mountTools({ getSnapshot: () => snapshot() });
+      mountTools(deps({ getSnapshot: () => snapshot() }));
     });
 
     expect(registerTool).not.toHaveBeenCalled();
@@ -176,10 +223,10 @@ describe("useStudioAgentTools", () => {
     const { registerTool } = installModelContext();
 
     await act(async () => {
-      mountTools({ getSnapshot: () => snapshot() });
+      mountTools(deps({ getSnapshot: () => snapshot() }));
     });
 
-    expect(registerTool).toHaveBeenCalledTimes(1);
+    expect(registerTool).toHaveBeenCalledTimes(12);
   });
 
   it("reports a non-abort registration failure through production telemetry", async () => {
@@ -187,7 +234,7 @@ describe("useStudioAgentTools", () => {
     registerTool.mockRejectedValue(new DOMException("blocked", "NotAllowedError"));
 
     await act(async () => {
-      mountTools({ getSnapshot: () => snapshot() });
+      mountTools(deps({ getSnapshot: () => snapshot() }));
     });
 
     expect(trackEvent).toHaveBeenCalledWith("webmcp_registration_failed", {
@@ -200,11 +247,13 @@ describe("useStudioAgentTools", () => {
     const { registered } = installModelContext();
 
     await act(async () => {
-      mountTools({
-        getSnapshot: () => {
-          throw new TypeError("handler signature moved");
-        },
-      });
+      mountTools(
+        deps({
+          getSnapshot: () => {
+            throw new TypeError("handler signature moved");
+          },
+        }),
+      );
     });
     vi.spyOn(console, "error").mockImplementation(() => {});
 

package/src/webmcp/useStudioAgentTools.ts

@@ -14,6 +14,71 @@ import {
   type StudioLookInput,
   type StudioLookSnapshot,
 } from "./tools/lookTools";
+import {
+  studioSeek,
+  studioSelect,
+  STUDIO_SEEK_DESCRIPTION,
+  STUDIO_SEEK_INPUT_SCHEMA,
+  STUDIO_SELECT_DESCRIPTION,
+  STUDIO_SELECT_INPUT_SCHEMA,
+  type SelectionToolDeps,
+  type StudioSeekResult,
+  type StudioSelectResult,
+} from "./tools/selectionTools";
+import {
+  studioFrame,
+  STUDIO_FRAME_DESCRIPTION,
+  STUDIO_FRAME_INPUT_SCHEMA,
+  type FrameToolDeps,
+  type StudioFrameInput,
+  type StudioFrameResult,
+} from "./tools/frameTools";
+import {
+  studioInspect,
+  STUDIO_INSPECT_DESCRIPTION,
+  STUDIO_INSPECT_INPUT_SCHEMA,
+  type InspectToolDeps,
+  type StudioInspectInput,
+  type StudioInspectResult,
+} from "./tools/inspectTools";
+import {
+  studioSetStyle,
+  studioSetText,
+  STUDIO_SET_STYLE_DESCRIPTION,
+  STUDIO_SET_STYLE_INPUT_SCHEMA,
+  STUDIO_SET_TEXT_DESCRIPTION,
+  STUDIO_SET_TEXT_INPUT_SCHEMA,
+  type ContentToolDeps,
+  type StudioSetStyleResult,
+  type StudioSetTextResult,
+} from "./tools/contentTools";
+import {
+  studioTransform,
+  STUDIO_TRANSFORM_DESCRIPTION,
+  STUDIO_TRANSFORM_INPUT_SCHEMA,
+  type StudioTransformInput,
+  type StudioTransformResult,
+  type TransformToolDeps,
+} from "./tools/transformTools";
+import {
+  studioAddAnimation,
+  studioAddKeyframe,
+  studioDeleteAnimation,
+  studioUpdateAnimation,
+  STUDIO_ADD_ANIMATION_DESCRIPTION,
+  STUDIO_ADD_ANIMATION_INPUT_SCHEMA,
+  STUDIO_ADD_KEYFRAME_DESCRIPTION,
+  STUDIO_ADD_KEYFRAME_INPUT_SCHEMA,
+  STUDIO_DELETE_ANIMATION_DESCRIPTION,
+  STUDIO_DELETE_ANIMATION_INPUT_SCHEMA,
+  STUDIO_UPDATE_ANIMATION_DESCRIPTION,
+  STUDIO_UPDATE_ANIMATION_INPUT_SCHEMA,
+  type AnimationToolDeps,
+  type StudioAddAnimationResult,
+  type StudioAddKeyframeResult,
+  type StudioDeleteAnimationResult,
+  type StudioUpdateAnimationResult,
+} from "./tools/animationTools";
 
 const log = makeStudioDebugLogger("webmcp");
 
@@ -27,7 +92,14 @@ function reportRegistration(report: ToolRegistrationReport, native: boolean): vo
   }
 }
 
-export interface StudioAgentToolsDeps {
+export interface StudioAgentToolsDeps
+  extends
+    SelectionToolDeps,
+    FrameToolDeps,
+    InspectToolDeps,
+    ContentToolDeps,
+    TransformToolDeps,
+    AnimationToolDeps {
   /** Read Studio's current state. Called per tool invocation, never cached. */
   getSnapshot: () => StudioLookSnapshot;
 }
@@ -57,9 +129,131 @@ function buildStudioTools(depsRef: { readonly current: StudioAgentToolsDeps }):
           buildStudioLook(depsRef.current.getSnapshot(), input as StudioLookInput),
         ),
     },
+    {
+      name: "studio_select",
+      title: "Select an element",
+      description: STUDIO_SELECT_DESCRIPTION,
+      inputSchema: STUDIO_SELECT_INPUT_SCHEMA,
+      annotations: { readOnlyHint: false, untrustedContentHint: true },
+      execute: (input): Promise<ToolResult<StudioSelectResult>> =>
+        runToolBody("studio_select", () =>
+          studioSelect(depsRef.current, readStringInput(input, "handle")),
+        ),
+    },
+    {
+      name: "studio_seek",
+      title: "Move the playhead",
+      description: STUDIO_SEEK_DESCRIPTION,
+      inputSchema: STUDIO_SEEK_INPUT_SCHEMA,
+      annotations: { readOnlyHint: false },
+      execute: (input): Promise<ToolResult<StudioSeekResult>> =>
+        runToolBody("studio_seek", async () =>
+          studioSeek(depsRef.current, readNumberInput(input, "time")),
+        ),
+    },
+    {
+      name: "studio_frame",
+      title: "See the composition",
+      description: STUDIO_FRAME_DESCRIPTION,
+      inputSchema: STUDIO_FRAME_INPUT_SCHEMA,
+      annotations: { readOnlyHint: true, untrustedContentHint: true },
+      execute: (input): Promise<ToolResult<StudioFrameResult>> =>
+        runToolBody("studio_frame", () => studioFrame(depsRef.current, input as StudioFrameInput)),
+    },
+    {
+      name: "studio_inspect",
+      title: "Inspect one element",
+      description: STUDIO_INSPECT_DESCRIPTION,
+      inputSchema: STUDIO_INSPECT_INPUT_SCHEMA,
+      annotations: { readOnlyHint: true, untrustedContentHint: true },
+      execute: (input): Promise<ToolResult<StudioInspectResult>> =>
+        runToolBody("studio_inspect", () =>
+          studioInspect(depsRef.current, input as StudioInspectInput),
+        ),
+    },
+    {
+      name: "studio_set_text",
+      title: "Set an element's text",
+      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)),
+    },
+    {
+      name: "studio_set_style",
+      title: "Set an element's styles",
+      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)),
+    },
+    {
+      name: "studio_transform",
+      title: "Move, resize or rotate",
+      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),
+        ),
+    },
+    {
+      name: "studio_add_animation",
+      title: "Add an animation",
+      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)),
+    },
+    {
+      name: "studio_update_animation",
+      title: "Change an animation",
+      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)),
+    },
+    {
+      name: "studio_add_keyframe",
+      title: "Add a keyframe",
+      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)),
+    },
+    {
+      name: "studio_delete_animation",
+      title: "Remove an animation",
+      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)),
+    },
   ];
 }
 
+/**
+ * Nothing in the platform validates the input object against `inputSchema`, so
+ * a tool receives whatever the agent sent. These read a field without asserting
+ * its type; the tools themselves reject what they cannot use.
+ */
+function readStringInput(input: object, key: string): string {
+  const value = Reflect.get(input, key);
+  return typeof value === "string" ? value : "";
+}
+
+function readNumberInput(input: object, key: string): number {
+  const value = Reflect.get(input, key);
+  return typeof value === "number" ? value : Number.NaN;
+}
+
 /**
  * Register Studio's tools with the browser, exactly once per mount.
  *

package/src/webmcp/webmcpTestUtils.ts

@@ -0,0 +1,91 @@
+/**
+ * Shared fixtures for the WebMCP tool tests.
+ *
+ * Not a `.test` file so vitest does not collect it as a suite. Mirrors the
+ * existing `hooks/domSelectionTestHarness.ts` convention.
+ */
+
+import { expect } from "vitest";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import type { ToolFailure, ToolResult } from "./toolResult";
+
+/**
+ * An element inside a real iframe, which is where Studio's chrome expects to
+ * find preview elements. The separate realm matters: a preview element is not
+ * an instance of Studio's own `HTMLElement`.
+ */
+export function previewDoc(html: string): Document {
+  const iframe = document.createElement("iframe");
+  document.body.append(iframe);
+  const doc = iframe.contentDocument;
+  if (!doc) throw new Error("expected iframe document");
+  doc.body.innerHTML = html;
+  return doc;
+}
+
+export function previewElement(html: string, id: string): HTMLElement {
+  const doc = previewDoc(html);
+  const element = doc.getElementById(id);
+  const HTMLElementCtor = doc.defaultView?.HTMLElement;
+  if (!HTMLElementCtor || !(element instanceof HTMLElementCtor)) {
+    throw new Error(`expected preview element #${id}`);
+  }
+  return element;
+}
+
+export function selectionFor(
+  element: HTMLElement,
+  overrides: Partial<DomEditSelection> = {},
+): DomEditSelection {
+  return {
+    id: element.id || undefined,
+    hfId: element.getAttribute("data-hf-id") ?? undefined,
+    element,
+    label: "Headline",
+    tagName: element.tagName.toLowerCase(),
+    sourceFile: "index.html",
+    compositionPath: "index.html",
+    isCompositionHost: false,
+    isInsideLockedComposition: false,
+    boundingBox: { x: 40, y: 12, width: 880, height: 96 },
+    textContent: element.textContent,
+    dataAttributes: { "data-role": "title" },
+    inlineStyles: { color: "red" },
+    computedStyles: { "font-size": "42.7px", color: "rgb(255, 0, 0)" },
+    textFields: [
+      {
+        key: "self",
+        label: "Text",
+        value: element.textContent ?? "",
+        tagName: element.tagName.toLowerCase(),
+        attributes: [],
+        inlineStyles: {},
+        computedStyles: {},
+        source: "self",
+      },
+    ],
+    capabilities: {
+      canSelect: true,
+      canEditStyles: true,
+      canCrop: true,
+      canMove: true,
+      canResize: true,
+      canApplyManualOffset: true,
+      canApplyManualSize: true,
+      canApplyManualRotation: true,
+    },
+    ...overrides,
+  };
+}
+
+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");
+  return result;
+}
+
+export function expectFailure(result: ToolResult<unknown>): ToolFailure {
+  expect(result.ok, `expected failure, got ${JSON.stringify(result)}`).toBe(false);
+  if (result.ok) throw new Error("unreachable");
+  return result;
+}