@hyperframes/studio 0.8.16 → 0.8.17

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");
+  });
+});

package/src/webmcp/tools/lookTools.ts

@@ -0,0 +1,201 @@
+/**
+ * `studio_look`: the one call that orients an agent.
+ *
+ * Deliberately fat. Every field here is one the agent would otherwise have to
+ * spend a round trip discovering.
+ *
+ * The building is a pure function over a snapshot so it can be tested with
+ * values. Gathering the snapshot is the React layer's job.
+ */
+
+import type { DomEditSelection } from "../../components/editor/domEditingTypes";
+import type { TimelineElement } from "../../player/store/timelineElement";
+import { mintElementHandle, patchTargetAddress, timelineElementAddress } from "../handles";
+import { toolOk, type ToolResult } from "../toolResult";
+
+export interface StudioLookSnapshot {
+  projectId: string | null;
+  compositionPath: string | null;
+  currentTime: number;
+  duration: number;
+  isPlaying: boolean;
+  elements: readonly TimelineElement[];
+  selection: DomEditSelection | null;
+  /** Live animations for the current selection arrive outside DomEditSelection. */
+  selectionAnimationCount: number;
+  /**
+   * The undo stack as Studio's shell actually exposes it.
+   *
+   * This is a weaker signal than a revision counter, and deliberately not
+   * dressed up as one: the depth lives in component-local state and is not
+   * reachable here without plumbing it through the shell context. What an agent
+   * CAN do is checkpoint `undoLabel` before a batch and notice it change to
+   * something it did not do, which means a human pressed undo and its earlier
+   * edits are gone.
+   */
+  history: {
+    canUndo: boolean;
+    canRedo: boolean;
+    undoLabel: string | null;
+    redoLabel: string | null;
+  };
+}
+
+interface LookElement {
+  /** Pass back to any tool that takes a handle. Null means unaddressable. */
+  handle: string | null;
+  label: string | null;
+  tag: string;
+  kind: string | null;
+  start: number;
+  duration: number;
+  track: number;
+  zIndex: number | null;
+}
+
+interface LookSelection {
+  handle: string | null;
+  label: string;
+  tagName: string;
+  sourceFile: string;
+  box: { x: number; y: number; width: number; height: number };
+  text: string | null;
+  /** What this element will and will not accept, straight from Studio. */
+  can: {
+    editStyles: boolean;
+    move: boolean;
+    resize: boolean;
+    editText: boolean;
+    reasonIfDisabled: string | null;
+  };
+  animationCount: number;
+}
+
+/**
+ * Session-scoped response shape. There is intentionally no schema version:
+ * WebMCP consumers discover the current tool and schema when they connect
+ * rather than pinning a cached REST response contract.
+ */
+export interface StudioLook {
+  projectId: string | null;
+  compositionPath: string | null;
+  playhead: number;
+  duration: number;
+  isPlaying: boolean;
+  history: StudioLookSnapshot["history"];
+  selection: LookSelection | null;
+  elementCount: number;
+  elements: LookElement[];
+}
+
+export interface StudioLookInput {
+  /** Case-insensitive substring match against label, tag, and handle. */
+  filter?: string;
+  /** Cap the returned list. The full count is always reported separately. */
+  limit?: number;
+}
+
+const DEFAULT_LIMIT = 200;
+const MAX_FILTER_LENGTH = 128;
+
+function describeElement(element: TimelineElement): LookElement {
+  return {
+    handle: mintElementHandle(timelineElementAddress(element)),
+    label: element.label ?? null,
+    tag: element.tag,
+    kind: element.kind ?? null,
+    start: element.start,
+    duration: element.duration,
+    track: element.track,
+    zIndex: element.zIndex ?? null,
+  };
+}
+
+function describeSelection(selection: DomEditSelection, animationCount: number): LookSelection {
+  const { capabilities } = selection;
+  return {
+    handle: mintElementHandle(patchTargetAddress(selection)),
+    label: selection.label,
+    tagName: selection.tagName,
+    sourceFile: selection.sourceFile,
+    box: selection.boundingBox,
+    text: selection.textContent,
+    can: {
+      editStyles: capabilities.canEditStyles,
+      move: capabilities.canMove || capabilities.canApplyManualOffset,
+      resize: capabilities.canResize || capabilities.canApplyManualSize,
+      editText: selection.textFields.length > 0,
+      reasonIfDisabled: capabilities.reasonIfDisabled ?? null,
+    },
+    animationCount,
+  };
+}
+
+function matchesFilter(element: LookElement, needle: string): boolean {
+  return (
+    (element.label?.toLowerCase().includes(needle) ?? false) ||
+    element.tag.toLowerCase().includes(needle) ||
+    (element.handle?.toLowerCase().includes(needle) ?? false)
+  );
+}
+
+export function buildStudioLook(
+  snapshot: StudioLookSnapshot,
+  input: StudioLookInput = {},
+): ToolResult<StudioLook> {
+  const described = snapshot.elements.map(describeElement);
+  const needle = input.filter?.slice(0, MAX_FILTER_LENGTH).trim().toLowerCase();
+  const matched = needle
+    ? described.filter((element) => matchesFilter(element, needle))
+    : described;
+
+  // Clamp rather than reject: a bad limit should not cost the agent a round trip
+  // when the answer it wants is right here.
+  const requested =
+    Number.isInteger(input.limit) && input.limit! > 0 ? input.limit! : DEFAULT_LIMIT;
+  const limit = Math.min(requested, DEFAULT_LIMIT);
+
+  return toolOk<StudioLook>({
+    projectId: snapshot.projectId,
+    compositionPath: snapshot.compositionPath,
+    playhead: snapshot.currentTime,
+    duration: snapshot.duration,
+    isPlaying: snapshot.isPlaying,
+    history: snapshot.history,
+    selection: snapshot.selection
+      ? describeSelection(snapshot.selection, snapshot.selectionAnimationCount)
+      : null,
+    // The count is of everything that MATCHED, so a truncated list is visible
+    // as a truncated list rather than reading as "that is all there is".
+    elementCount: matched.length,
+    elements: matched.slice(0, limit),
+  });
+}
+
+export const STUDIO_LOOK_INPUT_SCHEMA = {
+  type: "object",
+  properties: {
+    filter: {
+      type: "string",
+      maxLength: MAX_FILTER_LENGTH,
+      description: "Case-insensitive substring matched against element label, tag, and handle.",
+    },
+    limit: {
+      type: "integer",
+      minimum: 1,
+      maximum: DEFAULT_LIMIT,
+      description: `Cap the returned elements (default and max ${DEFAULT_LIMIT}). elementCount always reports the full match count.`,
+    },
+  },
+  additionalProperties: false,
+} as const;
+
+export const STUDIO_LOOK_DESCRIPTION = [
+  "Read HyperFrames Studio's live state in one call: the open project and composition,",
+  "the playhead and duration, what the human currently has selected (including what that",
+  "element will and will not accept), and the timeline's elements with a handle for each.",
+  "Pass a handle back to any tool that edits an element.",
+  "Returns an object with `ok: true`, or `ok: false` with `kind`, `reason` and often a `hint`.",
+  "`history.undoLabel` is worth checkpointing before a batch: if it later names something",
+  "you did not do, a human pressed undo and your earlier edits are gone.",
+].join(" ");

package/src/webmcp/types.ts

@@ -0,0 +1,90 @@
+/**
+ * The slice of the WebMCP browser API that Studio uses.
+ *
+ * Mirrors the WebIDL in the W3C spec (`webmachinelearning/webmcp`, `index.bs`)
+ * as of 2026-08-26. Two things worth knowing before editing this file:
+ *
+ * - The API hangs off `document`, NOT `navigator`. `navigator.modelContext` is
+ *   a polyfill compatibility shim, not a spec member, so feature-detecting it
+ *   is wrong even where an article's sample "works".
+ * - The spec is pre-stable (Origin Trial). This file and `registrar.ts` are the
+ *   only places that touch the API, so a spec change is a two-file edit. Re-read
+ *   `index.bs` rather than trusting this transcription.
+ *
+ * Only the surface Studio registers against is declared. `getTools` and
+ * `executeTool` are the consumer side; Studio registers, it does not call.
+ *
+ * These stay hand-written rather than imported from `@mcp-b/webmcp-types`,
+ * which the polyfill pulls in. That package's `registerTool` is overloaded to
+ * infer argument types from a literal `inputSchema`, which is useful when you
+ * register one tool inline and actively hostile when you register a uniform
+ * list of them, as `registerStudioTools` does. Narrower is the safe operation
+ * here. It does mean this file can drift from the spec, hence the note above.
+ */
+
+export interface ModelContextToolAnnotations {
+  /** The tool does not change state. Lets an agent decide when calling is free. */
+  readOnlyHint?: boolean;
+  /** The tool's output contains data the page's author does not vouch for. */
+  untrustedContentHint?: boolean;
+}
+
+export interface ToolExecuteCallbackOptions {
+  /**
+   * Aborted when the caller cancels. Studio's commit path is not cancellable
+   * once dispatched, so tools check this BEFORE dispatching and document that a
+   * late abort does not unwind a write.
+   */
+  signal: AbortSignal;
+}
+
+export interface ModelContextTool {
+  /**
+   * Max 128 characters, ASCII alphanumeric plus `_`, `-`, `.`. Registering a
+   * name that already exists REJECTS with InvalidStateError; it does not
+   * replace.
+   */
+  name: string;
+  title?: string;
+  /** Required and non-empty; an empty string rejects with InvalidStateError. */
+  description: string;
+  /** JSON Schema. Nothing in the platform validates input against it. */
+  inputSchema?: object;
+  /**
+   * The user agent JSON-serializes whatever this resolves with, so it must
+   * return an object. Returning `undefined` fails the serialization.
+   *
+   * A rejection is NOT a usable error channel: the spec discards the reason and
+   * rejects the caller with a bare UnknownError. Resolve with a tagged failure
+   * instead. See `toolResult.ts`.
+   */
+  execute: (input: object, options: ToolExecuteCallbackOptions) => Promise<unknown>;
+  annotations?: ModelContextToolAnnotations;
+}
+
+export interface ModelContextRegisterToolOptions {
+  exposedTo?: string[];
+  /** Aborting unregisters the tool. It does not cancel a running `execute`. */
+  signal?: AbortSignal;
+}
+
+export interface ModelContext {
+  registerTool(tool: ModelContextTool, options?: ModelContextRegisterToolOptions): Promise<void>;
+}
+
+function isModelContext(value: unknown): value is ModelContext {
+  if (typeof value !== "object" || value === null) return false;
+  return typeof Reflect.get(value, "registerTool") === "function";
+}
+
+/**
+ * The live WebMCP entry point, or null when this browser has not shipped it.
+ *
+ * Reads through a guard rather than augmenting the `Document` interface. The
+ * polyfill's typings already declare `Document.modelContext` globally, and a
+ * second, narrower declaration of the same property is a type error.
+ */
+export function getModelContext(doc: Document = document): ModelContext | null {
+  const candidate = Reflect.get(doc, "modelContext");
+  return isModelContext(candidate) ? candidate : null;
+}