@hyperframes/studio 0.8.16 → 0.8.18

package/src/webmcp/registrar.test.ts

@@ -0,0 +1,150 @@
+// @vitest-environment jsdom
+import { describe, expect, it, vi } from "vitest";
+import { findToolDefinitionError, registerStudioTools } from "./registrar";
+import type { ModelContext, ModelContextTool } from "./types";
+
+function tool(overrides: Partial<ModelContextTool> = {}): ModelContextTool {
+  return {
+    name: "studio_look",
+    description: "Read Studio's live state.",
+    execute: async () => ({ ok: true }),
+    ...overrides,
+  };
+}
+
+function fakeModelContext(
+  registerTool: ModelContext["registerTool"] = vi.fn().mockResolvedValue(undefined),
+): ModelContext {
+  return { registerTool };
+}
+
+function domException(name: string, message = name): DOMException {
+  return new DOMException(message, name);
+}
+
+describe("findToolDefinitionError", () => {
+  it("accepts the names Studio actually uses", () => {
+    expect(findToolDefinitionError(tool({ name: "studio_look" }))).toBeNull();
+    expect(findToolDefinitionError(tool({ name: "studio.look-2" }))).toBeNull();
+  });
+
+  it("rejects a name the browser would reject, naming the tool", () => {
+    expect(findToolDefinitionError(tool({ name: "studio look" }))).toMatch(/name must be/);
+    expect(findToolDefinitionError(tool({ name: "a".repeat(129) }))).toMatch(/name must be/);
+    expect(findToolDefinitionError(tool({ name: "" }))).toMatch(/name must be/);
+  });
+
+  it("rejects an empty description", () => {
+    expect(findToolDefinitionError(tool({ description: "   " }))).toBe(
+      "description must not be empty",
+    );
+  });
+});
+
+describe("registerStudioTools", () => {
+  it("registers every tool with the shared abort signal", async () => {
+    const registerTool = vi.fn().mockResolvedValue(undefined);
+    const controller = new AbortController();
+
+    const report = await registerStudioTools(
+      fakeModelContext(registerTool),
+      [tool({ name: "studio_look" }), tool({ name: "studio_frame" })],
+      controller.signal,
+    );
+
+    expect(report.registered).toEqual(["studio_look", "studio_frame"]);
+    expect(report.failed).toEqual([]);
+    expect(registerTool).toHaveBeenCalledTimes(2);
+    expect(registerTool.mock.calls[0]?.[1]).toEqual({ signal: controller.signal });
+  });
+
+  it("stops silently when the signal aborts mid-registration", async () => {
+    // A StrictMode mount-cleanup-mount rejects the in-flight registrations with
+    // AbortError. That is teardown working; it must not surface as a failure or
+    // escape as an unhandled rejection.
+    const registerTool = vi
+      .fn()
+      .mockResolvedValueOnce(undefined)
+      .mockRejectedValueOnce(domException("AbortError"));
+
+    const report = await registerStudioTools(
+      fakeModelContext(registerTool),
+      [tool({ name: "studio_look" }), tool({ name: "studio_frame" })],
+      new AbortController().signal,
+    );
+
+    expect(report.registered).toEqual(["studio_look"]);
+    expect(report.failed).toEqual([]);
+  });
+
+  it("keeps the DOMException name, which is the only thing that tells the gates apart", async () => {
+    const registerTool = vi
+      .fn()
+      .mockRejectedValue(domException("SecurityError", "not origin-keyed"));
+
+    const report = await registerStudioTools(
+      fakeModelContext(registerTool),
+      [tool()],
+      new AbortController().signal,
+    );
+
+    expect(report.failed).toHaveLength(1);
+    expect(report.failed[0]?.tool).toBe("studio_look");
+    expect(report.failed[0]?.name).toBe("SecurityError");
+    // Substring, not equality: jsdom prefixes DOMException.message with the
+    // name and real browsers do not.
+    expect(report.failed[0]?.message).toContain("not origin-keyed");
+    expect(report.registered).toEqual([]);
+  });
+
+  it("keeps going after one tool fails", async () => {
+    const registerTool = vi
+      .fn()
+      .mockRejectedValueOnce(domException("NotAllowedError", "tools policy"))
+      .mockResolvedValueOnce(undefined);
+
+    const report = await registerStudioTools(
+      fakeModelContext(registerTool),
+      [tool({ name: "studio_look" }), tool({ name: "studio_frame" })],
+      new AbortController().signal,
+    );
+
+    expect(report.registered).toEqual(["studio_frame"]);
+    expect(report.failed.map((f) => f.tool)).toEqual(["studio_look"]);
+  });
+
+  it("catches a duplicate name before the browser does, so the report names it", async () => {
+    const registerTool = vi.fn().mockResolvedValue(undefined);
+
+    const report = await registerStudioTools(
+      fakeModelContext(registerTool),
+      [tool({ name: "studio_look" }), tool({ name: "studio_look" })],
+      new AbortController().signal,
+    );
+
+    expect(report.registered).toEqual(["studio_look"]);
+    expect(report.failed).toEqual([
+      {
+        tool: "studio_look",
+        name: "InvalidStateError",
+        message: "duplicate tool name in this registration set",
+      },
+    ]);
+    // Registering the same name twice REJECTS rather than replacing, so the
+    // second one must never reach the browser.
+    expect(registerTool).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not send a tool the browser would reject", async () => {
+    const registerTool = vi.fn().mockResolvedValue(undefined);
+
+    const report = await registerStudioTools(
+      fakeModelContext(registerTool),
+      [tool({ name: "studio look" })],
+      new AbortController().signal,
+    );
+
+    expect(registerTool).not.toHaveBeenCalled();
+    expect(report.failed[0]?.name).toBe("InvalidStateError");
+  });
+});

package/src/webmcp/registrar.ts

@@ -0,0 +1,115 @@
+/**
+ * Registers Studio's tools with the browser, once.
+ *
+ * The only file besides `types.ts` that touches the WebMCP API, so a spec
+ * change lands here. Tool names are document-scoped, so Studio relies on its
+ * single live `EditorShell` mounting one `StudioAgentTools`. A second live
+ * shell would register the same names and receive `InvalidStateError`; the
+ * duplicate check below only owns duplicates within one registration set.
+ */
+
+import type { ModelContext, ModelContextTool } from "./types";
+
+export interface ToolRegistrationFailure {
+  tool: string;
+  /** The DOMException name where there is one. It is the only thing that tells
+   *  a duplicate name (InvalidStateError) apart from a document that is not
+   *  origin-keyed (SecurityError) or not permitted to use `tools`
+   *  (NotAllowedError), and all three look identical without it. */
+  name: string;
+  message: string;
+}
+
+export interface ToolRegistrationReport {
+  registered: string[];
+  failed: ToolRegistrationFailure[];
+}
+
+/** Max 128 chars, ASCII alphanumeric plus `_`, `-`, `.` (`index.bs`). */
+const VALID_TOOL_NAME = /^[A-Za-z0-9_.-]{1,128}$/;
+
+/**
+ * A tool whose name or description the browser would reject anyway. Caught here
+ * so the failure names the offending tool instead of arriving as one of N
+ * identical InvalidStateErrors.
+ */
+export function findToolDefinitionError(tool: ModelContextTool): string | null {
+  if (!VALID_TOOL_NAME.test(tool.name)) {
+    return `name must be 1-128 chars of A-Z a-z 0-9 _ - . (got ${JSON.stringify(tool.name)})`;
+  }
+  if (!tool.description.trim()) return "description must not be empty";
+  return null;
+}
+
+function isAbortError(error: unknown): boolean {
+  return error instanceof DOMException && error.name === "AbortError";
+}
+
+function invalidState(tool: string, message: string): ToolRegistrationFailure {
+  return { tool, name: "InvalidStateError", message };
+}
+
+/**
+ * `"aborted"` is a third outcome, not a failure: teardown got there first and
+ * the caller should stop rather than record anything.
+ */
+type RegisterOneOutcome =
+  | { status: "registered" }
+  | { status: "failed"; failure: ToolRegistrationFailure }
+  | { status: "aborted" };
+
+async function registerOne(
+  modelContext: ModelContext,
+  tool: ModelContextTool,
+  signal: AbortSignal,
+): Promise<RegisterOneOutcome> {
+  const definitionError = findToolDefinitionError(tool);
+  if (definitionError) {
+    return { status: "failed", failure: invalidState(tool.name, definitionError) };
+  }
+
+  try {
+    await modelContext.registerTool(tool, { signal });
+    return { status: "registered" };
+  } catch (error) {
+    // A mount-cleanup-mount cycle (React StrictMode in dev) aborts the signal in
+    // the same task the registration promise is queued in, which rejects every
+    // registerTool with AbortError. That is teardown working, not a failure, and
+    // letting it escape fills the dev console with unhandled rejections.
+    if (isAbortError(error)) return { status: "aborted" };
+    return {
+      status: "failed",
+      failure: {
+        tool: tool.name,
+        name: error instanceof DOMException ? error.name : "Error",
+        message: error instanceof Error ? error.message : String(error),
+      },
+    };
+  }
+}
+
+export async function registerStudioTools(
+  modelContext: ModelContext,
+  tools: readonly ModelContextTool[],
+  signal: AbortSignal,
+): Promise<ToolRegistrationReport> {
+  const report: ToolRegistrationReport = { registered: [], failed: [] };
+  const seen = new Set<string>();
+
+  for (const tool of tools) {
+    // Registering a name twice REJECTS rather than replacing, so a duplicate
+    // must never reach the browser.
+    if (seen.has(tool.name)) {
+      report.failed.push(invalidState(tool.name, "duplicate tool name in this registration set"));
+      continue;
+    }
+    seen.add(tool.name);
+
+    const outcome = await registerOne(modelContext, tool, signal);
+    if (outcome.status === "aborted") return report;
+    if (outcome.status === "failed") report.failed.push(outcome.failure);
+    else report.registered.push(tool.name);
+  }
+
+  return report;
+}

package/src/webmcp/toolResult.ts

@@ -0,0 +1,67 @@
+/**
+ * The shape every Studio tool resolves with.
+ *
+ * Tools resolve, they never reject. That is forced by the spec, not a style
+ * choice: a rejected `execute` has its reason DISCARDED and the caller is
+ * rejected with a bare `UnknownError` (`index.bs`, the execute-tool completion
+ * steps). Rejecting would therefore guarantee the agent cannot see why the edit
+ * failed, which is the one thing it needs most.
+ *
+ * There is no `outputSchema` in the platform yet, so this discriminant is
+ * invisible to the agent's schema layer. Every tool's `description` has to say
+ * that it returns `ok`.
+ */
+
+export type ToolFailureKind =
+  /** A real state the agent can route around: save queue paused, capability off. */
+  | "blocked"
+  /** The agent's fault: unknown handle, bad enum, out of range. */
+  | "invalid"
+  /** Exogenous: the server said no, the patch target could not be resolved. */
+  | "failed"
+  /** Our bug. Reported AND re-thrown, so it is findable instead of plausible. */
+  | "internal";
+
+export interface ToolFailure {
+  ok: false;
+  kind: ToolFailureKind;
+  reason: string;
+  /** What to try instead. This is what turns a failure into a next action. */
+  hint?: string;
+}
+
+export type ToolResult<T> = ({ ok: true } & T) | ToolFailure;
+
+export function toolOk<T extends object>(value: T): { ok: true } & T {
+  return { ok: true, ...value };
+}
+
+function toolFailure(kind: ToolFailureKind, reason: string, hint?: string): ToolFailure {
+  return hint ? { ok: false, kind, reason, hint } : { ok: false, kind, reason };
+}
+
+/**
+ * Wrap a tool body so a thrown bug becomes a legible result instead of a
+ * rejection the agent cannot read.
+ *
+ * The split matters. A `TypeError` means a handler signature moved under us and
+ * the tool is permanently broken; reporting that as an ordinary failure would
+ * let it ship looking like a bad request forever. So it is tagged `internal`
+ * AND re-thrown to the console, where it is findable. Everything else is a
+ * failure the agent should route around.
+ */
+export async function runToolBody<T>(
+  toolName: string,
+  body: () => Promise<ToolResult<T>>,
+): Promise<ToolResult<T>> {
+  try {
+    return await body();
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    if (error instanceof TypeError || error instanceof ReferenceError) {
+      console.error(`[hf-webmcp] ${toolName} threw`, error);
+      return toolFailure("internal", reason);
+    }
+    return toolFailure("failed", reason);
+  }
+}

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

@@ -0,0 +1,225 @@
+// @vitest-environment jsdom
+import { describe, expect, it } from "vitest";
+import type { DomEditSelection } from "../../components/editor/domEditingTypes";
+import type { TimelineElement } from "../../player/store/timelineElement";
+import { buildStudioLook, STUDIO_LOOK_INPUT_SCHEMA, type StudioLookSnapshot } from "./lookTools";
+
+function element(overrides: Partial<TimelineElement>): TimelineElement {
+  return { id: "synthetic", tag: "div", start: 0, duration: 1, track: 0, ...overrides };
+}
+
+function snapshot(overrides: Partial<StudioLookSnapshot> = {}): StudioLookSnapshot {
+  return {
+    projectId: "demo",
+    compositionPath: "index.html",
+    currentTime: 1.5,
+    duration: 10,
+    isPlaying: false,
+    elements: [],
+    selection: null,
+    selectionAnimationCount: 0,
+    history: { canUndo: true, canRedo: false, undoLabel: "Move layer", redoLabel: null },
+    ...overrides,
+  };
+}
+
+function selection(overrides: Partial<DomEditSelection> = {}): DomEditSelection {
+  return {
+    id: "headline",
+    hfId: "abc123",
+    element: document.createElement("div"),
+    label: "Headline",
+    tagName: "h1",
+    sourceFile: "index.html",
+    compositionPath: "index.html",
+    isCompositionHost: false,
+    isInsideLockedComposition: false,
+    boundingBox: { x: 40, y: 12, width: 880, height: 96 },
+    textContent: "Ship it",
+    dataAttributes: {},
+    inlineStyles: {},
+    computedStyles: {},
+    textFields: [],
+    capabilities: {
+      canSelect: true,
+      canEditStyles: true,
+      canCrop: true,
+      canMove: true,
+      canResize: true,
+      canApplyManualOffset: true,
+      canApplyManualSize: true,
+      canApplyManualRotation: true,
+    },
+    ...overrides,
+  };
+}
+
+function expectOk<T>(result: { ok: boolean } & Record<string, unknown>): T {
+  if (!result.ok) throw new Error(`expected ok, got ${JSON.stringify(result)}`);
+  return result as unknown as T;
+}
+
+describe("buildStudioLook", () => {
+  it("reports the playhead, duration and undo label an agent needs to checkpoint", () => {
+    const look = expectOk<{
+      playhead: number;
+      duration: number;
+      history: { undoLabel: string | null };
+    }>(
+      buildStudioLook(
+        snapshot({
+          currentTime: 2.4,
+          duration: 30,
+          history: { canUndo: true, canRedo: false, undoLabel: "Edit text", redoLabel: null },
+        }),
+      ),
+    );
+
+    expect(look.playhead).toBe(2.4);
+    expect(look.duration).toBe(30);
+    expect(look.history.undoLabel).toBe("Edit text");
+  });
+
+  it("gives every addressable element a handle a write tool can consume", () => {
+    const look = expectOk<{ elements: { handle: string | null; label: string | null }[] }>(
+      buildStudioLook(
+        snapshot({
+          elements: [
+            element({ hfId: "abc", label: "Headline" }),
+            element({ domId: "cta", label: "Button" }),
+            element({ selector: ".card", selectorIndex: 2, label: "Card" }),
+          ],
+        }),
+      ),
+    );
+
+    expect(look.elements.map((e) => e.handle)).toEqual(["hf:abc", "dom:cta", "sel:.card#2"]);
+  });
+
+  it("reports an unaddressable element with a null handle rather than hiding it", () => {
+    const look = expectOk<{ elements: { handle: string | null }[]; elementCount: number }>(
+      buildStudioLook(snapshot({ elements: [element({ label: "Anonymous" })] })),
+    );
+
+    expect(look.elementCount).toBe(1);
+    expect(look.elements[0]?.handle).toBeNull();
+  });
+
+  it("returns an empty list for an empty timeline, not a failure", () => {
+    const look = expectOk<{ elements: unknown[]; elementCount: number }>(
+      buildStudioLook(snapshot()),
+    );
+
+    expect(look.elements).toEqual([]);
+    expect(look.elementCount).toBe(0);
+  });
+
+  it("filters on label, tag and handle, case-insensitively", () => {
+    const elements = [
+      element({ hfId: "abc", label: "Headline", tag: "h1" }),
+      element({ domId: "cta", label: "Button", tag: "button" }),
+    ];
+
+    const byLabel = expectOk<{ elements: { handle: string | null }[] }>(
+      buildStudioLook(snapshot({ elements }), { filter: "HEADLINE" }),
+    );
+    const byTag = expectOk<{ elements: { handle: string | null }[] }>(
+      buildStudioLook(snapshot({ elements }), { filter: "button" }),
+    );
+    const byHandle = expectOk<{ elements: { handle: string | null }[] }>(
+      buildStudioLook(snapshot({ elements }), { filter: "hf:abc" }),
+    );
+
+    expect(byLabel.elements.map((e) => e.handle)).toEqual(["hf:abc"]);
+    expect(byTag.elements.map((e) => e.handle)).toEqual(["dom:cta"]);
+    expect(byHandle.elements.map((e) => e.handle)).toEqual(["hf:abc"]);
+  });
+
+  it("bounds a filter before normalizing it", () => {
+    const boundedFilter = "x".repeat(128);
+    const look = expectOk<{ elements: { handle: string | null }[] }>(
+      buildStudioLook(
+        snapshot({ elements: [element({ domId: "bounded", label: boundedFilter })] }),
+        { filter: `${boundedFilter}${"y".repeat(10_000)}` },
+      ),
+    );
+
+    expect(look.elements.map((entry) => entry.handle)).toEqual(["dom:bounded"]);
+    expect(STUDIO_LOOK_INPUT_SCHEMA.properties.filter.maxLength).toBe(128);
+  });
+
+  it("keeps the true match count when the list is truncated", () => {
+    const elements = Array.from({ length: 5 }, (_, index) =>
+      element({ domId: `el-${index}`, label: "Card" }),
+    );
+
+    const look = expectOk<{ elements: unknown[]; elementCount: number }>(
+      buildStudioLook(snapshot({ elements }), { limit: 2 }),
+    );
+
+    // A truncated list must not read as "that is all there is".
+    expect(look.elements).toHaveLength(2);
+    expect(look.elementCount).toBe(5);
+  });
+
+  it("clamps a nonsense limit instead of failing the call", () => {
+    const elements = [element({ domId: "a" }), element({ domId: "b" })];
+
+    for (const limit of [0, -3, 1.5, Number.NaN]) {
+      const look = expectOk<{ elements: unknown[] }>(
+        buildStudioLook(snapshot({ elements }), { limit }),
+      );
+      expect(look.elements).toHaveLength(2);
+    }
+  });
+
+  it("surfaces the selection with its capabilities and a usable handle", () => {
+    const look = expectOk<{
+      selection: { handle: string | null; box: { width: number }; can: { editStyles: boolean } };
+    }>(buildStudioLook(snapshot({ selection: selection() })));
+
+    expect(look.selection?.handle).toBe("hf:abc123");
+    expect(look.selection?.box.width).toBe(880);
+    expect(look.selection?.can.editStyles).toBe(true);
+  });
+
+  it("reports the live animation count supplied outside the DOM selection", () => {
+    const look = expectOk<{ selection: { animationCount: number } | null }>(
+      buildStudioLook(snapshot({ selection: selection(), selectionAnimationCount: 3 })),
+    );
+
+    expect(look.selection?.animationCount).toBe(3);
+  });
+
+  it("passes the disabled reason through so the agent learns it from a read", () => {
+    const locked = selection({
+      capabilities: {
+        ...selection().capabilities,
+        canEditStyles: false,
+        canMove: false,
+        canApplyManualOffset: false,
+        reasonIfDisabled: "Element is inside a locked composition",
+      },
+    });
+
+    const look = expectOk<{
+      selection: { can: { editStyles: boolean; move: boolean; reasonIfDisabled: string | null } };
+    }>(buildStudioLook(snapshot({ selection: locked })));
+
+    expect(look.selection?.can.editStyles).toBe(false);
+    expect(look.selection?.can.move).toBe(false);
+    expect(look.selection?.can.reasonIfDisabled).toBe("Element is inside a locked composition");
+  });
+
+  it("reports null selection rather than an empty one when nothing is selected", () => {
+    const look = expectOk<{ selection: unknown }>(buildStudioLook(snapshot({ selection: null })));
+    expect(look.selection).toBeNull();
+  });
+
+  it("does not advertise write readiness before the real write gate exists", () => {
+    const look = expectOk<Record<string, unknown>>(buildStudioLook(snapshot()));
+
+    expect(look).not.toHaveProperty("canWrite");
+    expect(look).not.toHaveProperty("writeBlockedReason");
+  });
+});