@hyperframes/studio 0.8.20 → 0.8.21

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

@@ -0,0 +1,275 @@
+// @vitest-environment jsdom
+import { describe, expect, it, vi } from "vitest";
+import {
+  studioSetStyle,
+  studioSetText,
+  type ContentToolDeps,
+  type StudioSetStyleResult,
+  type StudioSetTextResult,
+} from "./contentTools";
+import { expectFailure, expectOk, previewElement, selectionFor } from "../webmcpTestUtils";
+
+function contentDeps(overrides: Partial<ContentToolDeps> = {}): ContentToolDeps {
+  const element = previewElement('<h1 id="headline">Ship it</h1>', "headline");
+  return {
+    getCurrentSelection: () => selectionFor(element),
+    getWriteBlockedReason: () => null,
+    setText: async () => ({ ok: true }),
+    setStyle: async () => ({ ok: true }),
+    ...overrides,
+  };
+}
+
+describe("studioSetText", () => {
+  it("writes the text and reports what it now is", async () => {
+    const setText = vi.fn(async () => ({ ok: true }) as const);
+
+    const result = await studioSetText(contentDeps({ setText }), { text: "Ship it faster" });
+
+    const ok = expectOk<StudioSetTextResult>(result);
+    expect(ok.text).toBe("Ship it faster");
+    expect(ok.changed).toBe(true);
+    // The single field is resolved and named, rather than left undefined.
+    expect(setText).toHaveBeenCalledWith("Ship it faster", "self");
+  });
+
+  it("reports changed:false when the text already said that", async () => {
+    const result = await studioSetText(contentDeps(), { text: "Ship it" });
+
+    expect(expectOk<StudioSetTextResult>(result).changed).toBe(false);
+  });
+
+  it("refuses to write while a conflict is waiting for the user", async () => {
+    // The paused-save and conflict states are banners with no lock behind them.
+    // Nothing else stops a programmatic write landing on top of a decision the
+    // user has been asked to make.
+    const setText = vi.fn();
+
+    const result = expectFailure(
+      await studioSetText(
+        contentDeps({
+          getWriteBlockedReason: () => "an external change to this file is waiting to be resolved",
+          setText,
+        }),
+        { text: "Ship it faster" },
+      ),
+    );
+
+    expect(result.kind).toBe("blocked");
+    expect(result.reason).toMatch(/external change/);
+    expect(setText).not.toHaveBeenCalled();
+  });
+
+  it("does not report success when the commit declined", async () => {
+    // The whole reason the handlers now return an outcome: they resolve on
+    // failure, so awaiting them proves nothing.
+    const result = expectFailure(
+      await studioSetText(
+        contentDeps({ setText: async () => ({ ok: false, reason: "persist-failed" }) }),
+        { text: "Ship it faster" },
+      ),
+    );
+
+    expect(result.kind).toBe("failed");
+    expect(result.reason).toMatch(/persist-failed/);
+  });
+
+  it("turns a decline reason into a hint naming what to do instead", async () => {
+    const result = expectFailure(
+      await studioSetText(
+        contentDeps({ setText: async () => ({ ok: false, reason: "not-text-editable" }) }),
+        { text: "x" },
+      ),
+    );
+
+    expect(result.kind).toBe("blocked");
+    expect(result.hint).toMatch(/studio_inspect/);
+  });
+
+  it("rejects a non-string text without dispatching", async () => {
+    const setText = vi.fn();
+
+    const result = expectFailure(await studioSetText(contentDeps({ setText }), { text: 42 }));
+
+    expect(result.kind).toBe("invalid");
+    expect(setText).not.toHaveBeenCalled();
+  });
+
+  it("fails when nothing is selected", async () => {
+    const setText = vi.fn();
+
+    const result = expectFailure(
+      await studioSetText(contentDeps({ getCurrentSelection: () => null, setText }), { text: "x" }),
+    );
+
+    expect(result.kind).toBe("invalid");
+    expect(result.hint).toMatch(/studio_select/);
+    expect(setText).not.toHaveBeenCalled();
+  });
+
+  it("targets the element's ACTUAL text field, not a field called self", async () => {
+    // Found end to end, not by these tests. An element's text usually lives in a
+    // child field keyed like `child:0:h1`. Passing no key planned zero
+    // operations, and the server rejected the empty patch with
+    // "target and operations required" -- a persist failure that looked like a
+    // server problem and was not.
+    const element = previewElement('<h1 id="headline">Ship it</h1>', "headline");
+    const selection = selectionFor(element);
+    selection.textFields = [{ ...selection.textFields[0]!, key: "child:0:h1" }];
+    const setText = vi.fn(async () => ({ ok: true }) as const);
+
+    await studioSetText(contentDeps({ getCurrentSelection: () => selection, setText }), {
+      text: "Shipped it",
+    });
+
+    expect(setText).toHaveBeenCalledWith("Shipped it", "child:0:h1");
+  });
+
+  it("rejects a field the element does not have, rather than writing nowhere", async () => {
+    const element = previewElement('<h1 id="headline">Ship it</h1>', "headline");
+    const selection = selectionFor(element);
+    selection.textFields = [{ ...selection.textFields[0]!, key: "child:0:h1" }];
+    const setText = vi.fn();
+
+    const result = expectFailure(
+      await studioSetText(contentDeps({ getCurrentSelection: () => selection, setText }), {
+        text: "x",
+        field: "self",
+      }),
+    );
+
+    expect(result.kind).toBe("invalid");
+    expect(result.hint).toContain("child:0:h1");
+    expect(setText).not.toHaveBeenCalled();
+  });
+
+  it("asks which field when the element has several", async () => {
+    const element = previewElement('<div id="card">a</div>', "card");
+    const selection = selectionFor(element);
+    const base = selection.textFields[0]!;
+    selection.textFields = [
+      { ...base, key: "child:0:h2" },
+      { ...base, key: "child:1:p" },
+    ];
+    const setText = vi.fn();
+
+    const result = expectFailure(
+      await studioSetText(contentDeps({ getCurrentSelection: () => selection, setText }), {
+        text: "x",
+      }),
+    );
+
+    expect(result.kind).toBe("invalid");
+    expect(result.reason).toMatch(/2 text fields/);
+    expect(setText).not.toHaveBeenCalled();
+  });
+
+  it("reports an element with no text field as blocked", async () => {
+    const element = previewElement('<div id="box"></div>', "box");
+    const selection = selectionFor(element);
+    selection.textFields = [];
+    const setText = vi.fn();
+
+    const result = expectFailure(
+      await studioSetText(contentDeps({ getCurrentSelection: () => selection, setText }), {
+        text: "x",
+      }),
+    );
+
+    expect(result.kind).toBe("blocked");
+    expect(setText).not.toHaveBeenCalled();
+  });
+});
+
+describe("studioSetStyle", () => {
+  it("applies every property and reports them", async () => {
+    const setStyle = vi.fn(async () => ({ ok: true }) as const);
+
+    const result = await studioSetStyle(contentDeps({ setStyle }), {
+      styles: { color: "red", "font-size": "48px" },
+    });
+
+    const ok = expectOk<StudioSetStyleResult>(result);
+    expect(ok.applied).toEqual({ color: "red", "font-size": "48px" });
+    expect(ok.rejected).toEqual({});
+    expect(setStyle).toHaveBeenCalledTimes(2);
+  });
+
+  it("commits sequentially, never concurrently", async () => {
+    // Two commits racing through Studio's client-side read-modify-write can
+    // record undo entries that both claim the same starting content.
+    let inFlight = 0;
+    let maxInFlight = 0;
+    const setStyle = vi.fn(async () => {
+      inFlight += 1;
+      maxInFlight = Math.max(maxInFlight, inFlight);
+      await Promise.resolve();
+      inFlight -= 1;
+      return { ok: true } as const;
+    });
+
+    await studioSetStyle(contentDeps({ setStyle }), {
+      styles: { color: "red", "font-size": "48px", opacity: "0.5" },
+    });
+
+    expect(maxInFlight).toBe(1);
+  });
+
+  it("reports a partial success as partial, not whole", async () => {
+    const setStyle = vi.fn(async (property: string) =>
+      property === "left"
+        ? ({ ok: false, reason: "geometry-property" } as const)
+        : ({ ok: true } as const),
+    );
+
+    const result = await studioSetStyle(contentDeps({ setStyle }), {
+      styles: { color: "red", left: "10px" },
+    });
+
+    const ok = expectOk<StudioSetStyleResult>(result);
+    expect(ok.applied).toEqual({ color: "red" });
+    expect(ok.rejected).toEqual({ left: "geometry-property" });
+  });
+
+  it("fails when every property was refused", async () => {
+    const result = expectFailure(
+      await studioSetStyle(
+        contentDeps({ setStyle: async () => ({ ok: false, reason: "styles-not-editable" }) }),
+        { styles: { color: "red" } },
+      ),
+    );
+
+    expect(result.kind).toBe("blocked");
+    expect(result.reason).toMatch(/styles-not-editable/);
+  });
+
+  it("rejects an empty styles object rather than committing nothing", async () => {
+    const setStyle = vi.fn();
+
+    const result = expectFailure(await studioSetStyle(contentDeps({ setStyle }), { styles: {} }));
+
+    expect(result.kind).toBe("invalid");
+    expect(setStyle).not.toHaveBeenCalled();
+  });
+
+  it("rejects a non-object styles value", async () => {
+    for (const styles of ["color: red", 42, null, ["color"]]) {
+      const result = expectFailure(await studioSetStyle(contentDeps(), { styles }));
+      expect(result.kind).toBe("invalid");
+    }
+  });
+
+  it("refuses to write while a conflict is waiting for the user", async () => {
+    const setStyle = vi.fn();
+
+    const result = expectFailure(
+      await studioSetStyle(
+        contentDeps({ getWriteBlockedReason: () => "Auto-save is paused", setStyle }),
+        { styles: { color: "red" } },
+      ),
+    );
+
+    expect(result.kind).toBe("blocked");
+    expect(setStyle).not.toHaveBeenCalled();
+  });
+});

package/src/webmcp/tools/contentTools.ts

@@ -0,0 +1,217 @@
+/**
+ * `studio_set_text` and `studio_set_style`: the first tools that change the file.
+ *
+ * Both operate on the CURRENT selection and take no handle. That is not an
+ * omission. `handleDomTextCommit(value, fieldKey?)` and
+ * `handleDomStyleCommit(property, value)` read the ambient React selection, and
+ * `applyDomSelection` only schedules a state update, so selecting and
+ * committing inside one call would write to whatever was selected before.
+ * Two tool calls are separated by a render. Select first, then edit.
+ *
+ * Every write here is guarded before dispatch and verified after. Studio has
+ * several paths where a failed commit resolves anyway, so "the function did not
+ * throw" proves nothing; the outcome the handler now returns is what proves it.
+ */
+
+import type { DomEditCommitOutcome } from "../../hooks/domEditCommitRunner";
+import type { DomEditSelection } from "../../components/editor/domEditingTypes";
+import { toolFailure, toolOk, type ToolFailure, type ToolResult } from "../toolResult";
+
+export interface ContentToolDeps {
+  getCurrentSelection: () => DomEditSelection | null;
+  /** Why a write would be refused right now, or null. Checked BEFORE dispatch. */
+  getWriteBlockedReason: () => string | null;
+  setText: (value: string, fieldKey?: string) => Promise<DomEditCommitOutcome>;
+  setStyle: (property: string, value: string) => Promise<DomEditCommitOutcome>;
+}
+
+/**
+ * The reasons a commit declines, translated into something an agent can act on.
+ * `persist-failed` is exogenous; the rest are states it should route around.
+ */
+const DECLINE_HINTS: Record<string, { kind: "blocked" | "invalid" | "failed"; hint?: string }> = {
+  "no-selection": { kind: "invalid", hint: "Call studio_select first." },
+  "no-project": { kind: "blocked" },
+  "geometry-property": {
+    kind: "blocked",
+    hint: "Position and size are not editable as styles. Use the transform tools.",
+  },
+  "styles-not-editable": {
+    kind: "blocked",
+    hint: "studio_inspect reports why, in can.reasonIfDisabled.",
+  },
+  "not-text-editable": {
+    kind: "blocked",
+    hint: "This element has no editable text. studio_inspect lists its textFields.",
+  },
+  "persist-failed": { kind: "failed", hint: "The write did not reach the file. Check Studio." },
+};
+
+function fromOutcome(outcome: DomEditCommitOutcome, what: string): ToolFailure | null {
+  if (outcome.ok) return null;
+  const mapped = DECLINE_HINTS[outcome.reason] ?? { kind: "failed" as const };
+  return toolFailure(mapped.kind, `${what} was not applied: ${outcome.reason}`, mapped.hint);
+}
+
+function guardWrite(deps: ContentToolDeps): ToolFailure | null {
+  // Both blocked states are banners in Studio's UI with no lock behind them, so
+  // nothing else stops a programmatic write from landing on top of a conflict
+  // the user has been asked to adjudicate.
+  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;
+}
+
+export interface StudioSetTextResult {
+  text: string;
+  changed: boolean;
+}
+
+export async function studioSetText(
+  deps: ContentToolDeps,
+  input: { text?: unknown; field?: unknown },
+): Promise<ToolResult<StudioSetTextResult>> {
+  if (typeof input.text !== "string") {
+    return toolFailure("invalid", "text must be a string");
+  }
+
+  const blocked = guardWrite(deps);
+  if (blocked) return blocked;
+
+  const selection = deps.getCurrentSelection();
+  if (!selection) return toolFailure("invalid", "nothing is selected");
+
+  const fields = selection.textFields;
+  const requested = typeof input.field === "string" && input.field ? input.field : undefined;
+  if (requested && !fields.some((candidate) => candidate.key === requested)) {
+    return toolFailure(
+      "invalid",
+      `this element has no text field "${requested}"`,
+      `Its fields are: ${fields.map((candidate) => candidate.key).join(", ") || "none"}.`,
+    );
+  }
+
+  // Resolving the field is NOT optional. An element's text usually lives in a
+  // child field keyed like `child:0:h1`, not in one called `self`, and passing
+  // no key plans zero operations. The server then rejects the empty patch with
+  // "target and operations required", which surfaces as a persist failure that
+  // looks like a server problem and is not.
+  const field = requested ?? (fields.length === 1 ? fields[0]?.key : undefined);
+  if (!field) {
+    if (fields.length === 0) {
+      return toolFailure(
+        "blocked",
+        "this element has no editable text field",
+        "studio_inspect lists an element's textFields.",
+      );
+    }
+    return toolFailure(
+      "invalid",
+      `this element has ${fields.length} text fields, so one must be named`,
+      `Pass field as one of: ${fields.map((candidate) => candidate.key).join(", ")}.`,
+    );
+  }
+
+  const before = selection.textContent ?? null;
+  const outcome = await deps.setText(input.text, field);
+  const failure = fromOutcome(outcome, "the text");
+  if (failure) return failure;
+
+  return toolOk<StudioSetTextResult>({ text: input.text, changed: before !== input.text });
+}
+
+export interface StudioSetStyleResult {
+  applied: Record<string, string>;
+  /** Properties the element refused, with the reason. Empty when all landed. */
+  rejected: Record<string, string>;
+}
+
+export async function studioSetStyle(
+  deps: ContentToolDeps,
+  input: { styles?: unknown },
+): Promise<ToolResult<StudioSetStyleResult>> {
+  const styles = input.styles;
+  if (typeof styles !== "object" || styles === null || Array.isArray(styles)) {
+    return toolFailure("invalid", "styles must be an object of CSS property to value");
+  }
+  const entries = Object.entries(styles).filter(
+    (entry): entry is [string, string] => typeof entry[1] === "string",
+  );
+  if (entries.length === 0) {
+    // An empty commit would report success having done nothing.
+    return toolFailure("invalid", "styles must contain at least one string value");
+  }
+
+  const blocked = guardWrite(deps);
+  if (blocked) return blocked;
+
+  // `handleDomStyleCommit` is one property per call, so N properties are N
+  // commits and N undo entries. Sequential, not concurrent: two commits racing
+  // through Studio's client-side read-modify-write can record undo entries that
+  // both claim the same starting content.
+  const applied: Record<string, string> = {};
+  const rejected: Record<string, string> = {};
+  for (const [property, value] of entries) {
+    const outcome = await deps.setStyle(property, value);
+    if (outcome.ok) applied[property] = value;
+    else rejected[property] = outcome.reason;
+  }
+
+  if (Object.keys(applied).length === 0) {
+    const reasons = Object.entries(rejected)
+      .map(([property, reason]) => `${property}: ${reason}`)
+      .join(", ");
+    return toolFailure("blocked", `no style was applied (${reasons})`);
+  }
+
+  return toolOk<StudioSetStyleResult>({ applied, rejected });
+}
+
+export const STUDIO_SET_TEXT_INPUT_SCHEMA = {
+  type: "object",
+  properties: {
+    text: { type: "string", description: "The new text content." },
+    field: {
+      type: "string",
+      description:
+        "Which text field to write, from studio_inspect. Omit for the element's own text.",
+    },
+  },
+  required: ["text"],
+  additionalProperties: false,
+} as const;
+
+export const STUDIO_SET_TEXT_DESCRIPTION = [
+  "Set the text of the CURRENTLY SELECTED element. Call studio_select first.",
+  "This is the edit a synthetic double-click cannot reach, because Studio's canvas",
+  "takes pointer capture and recognises the double press itself.",
+  "Returns `ok: true` with the resulting text and whether it changed, or `ok: false`",
+  "with `kind`, `reason` and usually a `hint` naming what to do instead.",
+].join(" ");
+
+export const STUDIO_SET_STYLE_INPUT_SCHEMA = {
+  type: "object",
+  properties: {
+    styles: {
+      type: "object",
+      description: 'CSS property to value, for example {"color": "red", "font-size": "48px"}.',
+      additionalProperties: { type: "string" },
+    },
+  },
+  required: ["styles"],
+  additionalProperties: false,
+} as const;
+
+export const STUDIO_SET_STYLE_DESCRIPTION = [
+  "Set inline styles on the CURRENTLY SELECTED element. Call studio_select first.",
+  "Each property is a separate commit, so N properties produce N undo entries.",
+  "Position and size properties (left, top, width, height) are refused here on purpose;",
+  "they belong to the transform tools.",
+  "Returns `ok: true` with `applied` and `rejected` maps, so a partial success is visible",
+  "as a partial success rather than reported as a whole one.",
+].join(" ");

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

@@ -0,0 +1,136 @@
+// @vitest-environment jsdom
+import { describe, expect, it, vi } from "vitest";
+import { studioFrame, type FrameToolDeps, type StudioFrameResult } from "./frameTools";
+import { expectFailure, expectOk } from "../webmcpTestUtils";
+
+function frameDeps(overrides: Partial<FrameToolDeps> = {}): FrameToolDeps {
+  return {
+    getProjectId: () => "demo",
+    getCompositionPath: () => "index.html",
+    readPlayhead: () => ({ currentTime: 2.4, duration: 10, isPlaying: false }),
+    requestSeek: () => undefined,
+    probeFrame: async () => ({ ok: true, status: 200 }),
+    wait: async () => undefined,
+    ...overrides,
+  };
+}
+
+describe("studioFrame", () => {
+  it("returns a URL for the composition at the playhead", async () => {
+    const result = await studioFrame(frameDeps());
+
+    const ok = expectOk<StudioFrameResult>(result);
+    expect(ok.time).toBe(2.4);
+    expect(ok.compositionPath).toBe("index.html");
+    expect(ok.url).toContain("/thumbnail/");
+    expect(ok.url).toContain("t=2.400");
+    expect(ok.url).toContain("format=png");
+  });
+
+  it("seeks first when given a time", async () => {
+    const requestSeek = vi.fn();
+
+    await studioFrame(frameDeps({ requestSeek }), { time: 5 });
+
+    expect(requestSeek).toHaveBeenCalledWith(5);
+  });
+
+  it("captures where the playhead LANDED, not what was asked for", async () => {
+    // The player clamps. Reporting the request would attach the wrong time to
+    // the frame, and an agent judging motion would draw the wrong conclusion.
+    const result = await studioFrame(
+      frameDeps({ readPlayhead: () => ({ currentTime: 10, duration: 10, isPlaying: false }) }),
+      { time: 999 },
+    );
+
+    const ok = expectOk<StudioFrameResult>(result);
+    expect(ok.time).toBe(10);
+    expect(ok.url).toContain("t=10.000");
+  });
+
+  it("waits before capturing, so a just-made edit is in the frame", async () => {
+    // The render cache is cleared by a file watcher with a write-stability
+    // threshold. Capturing faster than that renders the PRE-edit composition.
+    const wait = vi.fn(async () => undefined);
+    const order: string[] = [];
+
+    await studioFrame(
+      frameDeps({
+        wait: async (ms) => {
+          order.push(`wait:${ms}`);
+          await wait();
+        },
+        probeFrame: async () => {
+          order.push("probe");
+          return { ok: true, status: 200 };
+        },
+      }),
+    );
+
+    expect(order).toEqual(["wait:150", "probe"]);
+  });
+
+  it("honours a caller-supplied settle time and reports it", async () => {
+    const result = await studioFrame(frameDeps(), { settleMs: 800 });
+
+    expect(expectOk<StudioFrameResult>(result).settledMs).toBe(800);
+  });
+
+  it("clamps an absurd settle time rather than hanging", async () => {
+    const result = await studioFrame(frameDeps(), { settleMs: 10 * 60 * 1000 });
+
+    expect(expectOk<StudioFrameResult>(result).settledMs).toBe(5000);
+  });
+
+  it("falls back to the default for a nonsense settle time", async () => {
+    for (const settleMs of [-1, Number.NaN]) {
+      const result = await studioFrame(frameDeps(), { settleMs });
+      expect(expectOk<StudioFrameResult>(result).settledMs).toBe(150);
+    }
+  });
+
+  it("skips the wait entirely when asked for zero", async () => {
+    const wait = vi.fn(async () => undefined);
+
+    await studioFrame(frameDeps({ wait }), { settleMs: 0 });
+
+    expect(wait).not.toHaveBeenCalled();
+  });
+
+  it("reports a renderer failure instead of handing back a dead URL", async () => {
+    const result = expectFailure(
+      await studioFrame(frameDeps({ probeFrame: async () => ({ ok: false, status: 500 }) })),
+    );
+
+    expect(result.kind).toBe("failed");
+    expect(result.reason).toContain("500");
+    expect(result.hint).toBeDefined();
+  });
+
+  it("fails when no project is open, before touching the renderer", async () => {
+    const probeFrame = vi.fn();
+
+    const result = expectFailure(
+      await studioFrame(frameDeps({ getProjectId: () => null, probeFrame })),
+    );
+
+    expect(result.kind).toBe("blocked");
+    expect(probeFrame).not.toHaveBeenCalled();
+  });
+
+  it("rejects a negative or non-finite time without seeking", async () => {
+    const requestSeek = vi.fn();
+
+    for (const time of [-1, Number.NaN, Number.POSITIVE_INFINITY]) {
+      const result = expectFailure(await studioFrame(frameDeps({ requestSeek }), { time }));
+      expect(result.kind).toBe("invalid");
+    }
+    expect(requestSeek).not.toHaveBeenCalled();
+  });
+
+  it("captures the master composition when no path is active", async () => {
+    const result = await studioFrame(frameDeps({ getCompositionPath: () => null }));
+
+    expect(expectOk<StudioFrameResult>(result).compositionPath).toBe("index.html");
+  });
+});