@hyperframes/studio 0.8.23 → 0.8.25

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

@@ -7,34 +7,61 @@ import {
   type StudioSetStyleResult,
   type StudioSetTextResult,
 } from "./contentTools";
-import { expectFailure, expectOk, previewElement, selectionFor } from "../webmcpTestUtils";
+import {
+  expectFailure,
+  expectOk,
+  previewElement,
+  selectionFor,
+  sourceHandle,
+  targetedWriteDeps,
+} from "../webmcpTestUtils";
+
+const textInput = (input: Record<string, unknown>) => ({
+  handle: sourceHandle("headline"),
+  ...input,
+});
+
+const styleInput = (styles: unknown) => ({ handle: sourceHandle("headline"), styles });
 
 function contentDeps(overrides: Partial<ContentToolDeps> = {}): ContentToolDeps {
   const element = previewElement('<h1 id="headline">Ship it</h1>', "headline");
+  const selection = selectionFor(element);
   return {
-    getCurrentSelection: () => selectionFor(element),
-    getWriteBlockedReason: () => null,
+    ...targetedWriteDeps(selection),
     setText: async () => ({ ok: true }),
     setStyle: async () => ({ ok: true }),
     ...overrides,
   };
 }
 
+function childTextSelection() {
+  const element = previewElement('<h1 id="headline">Ship it</h1>', "headline");
+  const selection = selectionFor(element);
+  selection.textFields = [{ ...selection.textFields[0]!, key: "child:0:h1" }];
+  return selection;
+}
+
 describe("studioSetText", () => {
   it("writes the text and reports what it now is", async () => {
-    const setText = vi.fn(async () => ({ ok: true }) as const);
+    const setText = vi.fn(async (selection) => {
+      selection.element.textContent = "Ship it faster";
+      return { ok: true } as const;
+    });
 
-    const result = await studioSetText(contentDeps({ setText }), { text: "Ship it faster" });
+    const result = await studioSetText(
+      contentDeps({ setText }),
+      textInput({ 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");
+    expect(setText).toHaveBeenCalledWith(expect.anything(), "Ship it faster", "self");
   });
 
   it("reports changed:false when the text already said that", async () => {
-    const result = await studioSetText(contentDeps(), { text: "Ship it" });
+    const result = await studioSetText(contentDeps(), textInput({ text: "Ship it" }));
 
     expect(expectOk<StudioSetTextResult>(result).changed).toBe(false);
   });
@@ -51,7 +78,7 @@ describe("studioSetText", () => {
           getWriteBlockedReason: () => "an external change to this file is waiting to be resolved",
           setText,
         }),
-        { text: "Ship it faster" },
+        textInput({ text: "Ship it faster" }),
       ),
     );
 
@@ -66,7 +93,7 @@ describe("studioSetText", () => {
     const result = expectFailure(
       await studioSetText(
         contentDeps({ setText: async () => ({ ok: false, reason: "persist-failed" }) }),
-        { text: "Ship it faster" },
+        textInput({ text: "Ship it faster" }),
       ),
     );
 
@@ -78,32 +105,38 @@ describe("studioSetText", () => {
     const result = expectFailure(
       await studioSetText(
         contentDeps({ setText: async () => ({ ok: false, reason: "not-text-editable" }) }),
-        { text: "x" },
+        textInput({ text: "x" }),
       ),
     );
 
-    expect(result.kind).toBe("blocked");
+    expect(result.kind).toBe("failed");
     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 }));
+    const result = expectFailure(
+      await studioSetText(contentDeps({ setText }), textInput({ text: 42 })),
+    );
 
     expect(result.kind).toBe("invalid");
     expect(setText).not.toHaveBeenCalled();
   });
 
-  it("fails when nothing is selected", async () => {
+  it("reports an unsupported target when Studio cannot build its selection", async () => {
     const setText = vi.fn();
 
     const result = expectFailure(
-      await studioSetText(contentDeps({ getCurrentSelection: () => null, setText }), { text: "x" }),
+      await studioSetText(
+        contentDeps({ buildSelection: async () => null, setText }),
+        textInput({ text: "x" }),
+      ),
     );
 
-    expect(result.kind).toBe("invalid");
-    expect(result.hint).toMatch(/studio_select/);
+    expect(result.kind).toBe("blocked");
+    expect(result.reason).toBe("the target resolved to an element Studio cannot edit");
+    expect(result.hint).toMatch(/parent or child/);
     expect(setText).not.toHaveBeenCalled();
   });
 
@@ -113,29 +146,26 @@ describe("studioSetText", () => {
     // 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 selection = childTextSelection();
     const setText = vi.fn(async () => ({ ok: true }) as const);
 
-    await studioSetText(contentDeps({ getCurrentSelection: () => selection, setText }), {
-      text: "Shipped it",
-    });
+    await studioSetText(
+      contentDeps({ ...targetedWriteDeps(selection), setText }),
+      textInput({ text: "Shipped it" }),
+    );
 
-    expect(setText).toHaveBeenCalledWith("Shipped it", "child:0:h1");
+    expect(setText).toHaveBeenCalledWith(selection, "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 selection = childTextSelection();
     const setText = vi.fn();
 
     const result = expectFailure(
-      await studioSetText(contentDeps({ getCurrentSelection: () => selection, setText }), {
-        text: "x",
-        field: "self",
-      }),
+      await studioSetText(
+        contentDeps({ ...targetedWriteDeps(selection), setText }),
+        textInput({ text: "x", field: "self" }),
+      ),
     );
 
     expect(result.kind).toBe("invalid");
@@ -154,7 +184,8 @@ describe("studioSetText", () => {
     const setText = vi.fn();
 
     const result = expectFailure(
-      await studioSetText(contentDeps({ getCurrentSelection: () => selection, setText }), {
+      await studioSetText(contentDeps({ ...targetedWriteDeps(selection), setText }), {
+        handle: sourceHandle("card"),
         text: "x",
       }),
     );
@@ -171,7 +202,8 @@ describe("studioSetText", () => {
     const setText = vi.fn();
 
     const result = expectFailure(
-      await studioSetText(contentDeps({ getCurrentSelection: () => selection, setText }), {
+      await studioSetText(contentDeps({ ...targetedWriteDeps(selection), setText }), {
+        handle: sourceHandle("box"),
         text: "x",
       }),
     );
@@ -186,7 +218,7 @@ describe("studioSetStyle", () => {
     const setStyle = vi.fn(async () => ({ ok: true }) as const);
 
     const result = await studioSetStyle(contentDeps({ setStyle }), {
-      styles: { color: "red", "font-size": "48px" },
+      ...styleInput({ color: "red", "font-size": "48px" }),
     });
 
     const ok = expectOk<StudioSetStyleResult>(result);
@@ -195,6 +227,36 @@ describe("studioSetStyle", () => {
     expect(setStyle).toHaveBeenCalledTimes(2);
   });
 
+  it("keeps an earlier changed property when the latest saved property is a no-op", async () => {
+    const setStyle = vi
+      .fn()
+      .mockResolvedValueOnce({
+        ok: true,
+        persistence: { sourceFile: "index.html", version: "v1", changed: true },
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        persistence: { sourceFile: "index.html", version: "v2", changed: false },
+      });
+
+    const result = expectOk<StudioSetStyleResult>(
+      await studioSetStyle(
+        contentDeps({ setStyle }),
+        styleInput({ color: "red", "font-size": "48px" }),
+      ),
+    );
+
+    expect(result).toMatchObject({
+      stage: "saved",
+      changed: true,
+      evidence: { kind: "content-version", sourceFile: "index.html", version: "v2" },
+      propertyReceipts: {
+        color: { stage: "saved", changed: true },
+        "font-size": { stage: "saved", changed: false },
+      },
+    });
+  });
+
   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.
@@ -209,21 +271,21 @@ describe("studioSetStyle", () => {
     });
 
     await studioSetStyle(contentDeps({ setStyle }), {
-      styles: { color: "red", "font-size": "48px", opacity: "0.5" },
+      ...styleInput({ 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) =>
+    const setStyle = vi.fn(async (_selection, 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" },
+      ...styleInput({ color: "red", left: "10px" }),
     });
 
     const ok = expectOk<StudioSetStyleResult>(result);
@@ -235,18 +297,18 @@ describe("studioSetStyle", () => {
     const result = expectFailure(
       await studioSetStyle(
         contentDeps({ setStyle: async () => ({ ok: false, reason: "styles-not-editable" }) }),
-        { styles: { color: "red" } },
+        styleInput({ color: "red" }),
       ),
     );
 
-    expect(result.kind).toBe("blocked");
+    expect(result.kind).toBe("failed");
     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: {} }));
+    const result = expectFailure(await studioSetStyle(contentDeps({ setStyle }), styleInput({})));
 
     expect(result.kind).toBe("invalid");
     expect(setStyle).not.toHaveBeenCalled();
@@ -254,7 +316,7 @@ describe("studioSetStyle", () => {
 
   it("rejects a non-object styles value", async () => {
     for (const styles of ["color: red", 42, null, ["color"]]) {
-      const result = expectFailure(await studioSetStyle(contentDeps(), { styles }));
+      const result = expectFailure(await studioSetStyle(contentDeps(), styleInput(styles)));
       expect(result.kind).toBe("invalid");
     }
   });
@@ -265,7 +327,7 @@ describe("studioSetStyle", () => {
     const result = expectFailure(
       await studioSetStyle(
         contentDeps({ getWriteBlockedReason: () => "Auto-save is paused", setStyle }),
-        { styles: { color: "red" } },
+        styleInput({ color: "red" }),
       ),
     );
 

package/src/webmcp/tools/contentTools.ts

@@ -1,28 +1,36 @@
 /**
  * `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.
+ * The explicit source-safe handle is resolved to one selection per invocation.
+ * That captured selection is passed into Studio's existing commit actor; visible
+ * selection is presentation only and cannot redirect the write.
  */
 
 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>;
+import { toolFailure, type ToolFailure } from "../toolResult";
+import {
+  dispatched,
+  runTargetedWrite,
+  saved,
+  type StudioWriteAdapterSuccess,
+  type StudioWriteEvidence,
+  type StudioWriteResult,
+  type TargetedWriteDeps,
+  WRITE_RECEIPT_DESCRIPTION,
+} from "../writeCoordinator";
+
+export interface ContentToolDeps extends TargetedWriteDeps {
+  setText: (
+    selection: DomEditSelection,
+    value: string,
+    fieldKey?: string,
+  ) => Promise<DomEditCommitOutcome>;
+  setStyle: (
+    selection: DomEditSelection,
+    property: string,
+    value: string,
+  ) => Promise<DomEditCommitOutcome>;
 }
 
 /**
@@ -53,20 +61,6 @@ function fromOutcome(outcome: DomEditCommitOutcome, what: string): ToolFailure |
   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;
@@ -74,107 +68,147 @@ export interface StudioSetTextResult {
 
 export async function studioSetText(
   deps: ContentToolDeps,
-  input: { text?: unknown; field?: unknown },
-): Promise<ToolResult<StudioSetTextResult>> {
+  input: { handle?: unknown; text?: unknown; field?: unknown },
+  signal: AbortSignal = new AbortController().signal,
+): Promise<StudioWriteResult<StudioSetTextResult>> {
   if (typeof input.text !== "string") {
-    return toolFailure("invalid", "text must be a string");
+    return preDispatchFailure("set-text", toolFailure("invalid", "text must be a string"));
   }
+  const text = input.text;
 
-  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) {
+  let field: string | undefined;
+  return runTargetedWrite(deps, {
+    handle: input.handle,
+    operation: "set-text",
+    signal,
+    preflight: (selection) => {
+      const fields = selection.textFields;
+      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"}.`,
+        );
+      }
+      field = requested ?? (fields.length === 1 ? fields[0]?.key : undefined);
+      if (field) return null;
+      if (fields.length === 0) {
+        return toolFailure(
+          "blocked",
+          "this element has no editable text field",
+          "studio_inspect lists an element's textFields.",
+        );
+      }
       return toolFailure(
-        "blocked",
-        "this element has no editable text field",
-        "studio_inspect lists an element's textFields.",
+        "invalid",
+        `this element has ${fields.length} text fields, so one must be named`,
+        `Pass field as one of: ${fields.map((candidate) => candidate.key).join(", ")}.`,
       );
-    }
-    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 });
+    },
+    write: async (selection) => {
+      const before = selection.element.textContent;
+      const outcome = await deps.setText(selection, text, field);
+      if (!outcome.ok) return fromOutcome(outcome, "the text")!;
+      const value = { text, changed: selection.element.textContent !== before };
+      return outcome.persistence
+        ? saved(value, outcome.persistence)
+        : dispatched(value, value.changed);
+    },
+  });
 }
 
 export interface StudioSetStyleResult {
   applied: Record<string, string>;
   /** Properties the element refused, with the reason. Empty when all landed. */
   rejected: Record<string, string>;
+  partial: boolean;
+  propertyReceipts: Record<
+    string,
+    { stage: "dispatched" | "saved"; changed: boolean; evidence: StudioWriteEvidence }
+  >;
 }
 
 export async function studioSetStyle(
   deps: ContentToolDeps,
-  input: { styles?: unknown },
-): Promise<ToolResult<StudioSetStyleResult>> {
+  input: { handle?: unknown; styles?: unknown },
+  signal: AbortSignal = new AbortController().signal,
+): Promise<StudioWriteResult<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");
+    return preDispatchFailure(
+      "set-style",
+      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;
+    return preDispatchFailure(
+      "set-style",
+      toolFailure("invalid", "styles must contain at least one string value"),
+    );
   }
 
-  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 runTargetedWrite(deps, {
+    handle: input.handle,
+    operation: "set-style",
+    signal,
+    preflight: (selection) =>
+      selection.capabilities.canEditStyles
+        ? null
+        : toolFailure(
+            "blocked",
+            "this element's styles are not editable",
+            "studio_inspect reports why, in can.reasonIfDisabled.",
+          ),
+    write: async (selection) => {
+      const applied: Record<string, string> = {};
+      const rejected: Record<string, string> = {};
+      const propertyReceipts: StudioSetStyleResult["propertyReceipts"] = {};
+      let weakest: StudioWriteAdapterSuccess<object> | null = null;
+      for (const [property, value] of entries) {
+        const outcome = await deps.setStyle(selection, property, value);
+        if (!outcome.ok) {
+          rejected[property] = outcome.reason;
+          continue;
+        }
+        applied[property] = value;
+        const receipt = outcome.persistence ? saved({}, outcome.persistence) : dispatched({}, true);
+        propertyReceipts[property] = {
+          stage: receipt.stage,
+          changed: receipt.changed,
+          evidence: receipt.evidence,
+        };
+        if (!weakest || weakest.stage !== "dispatched") weakest = receipt;
+      }
 
-  return toolOk<StudioSetStyleResult>({ applied, rejected });
+      if (!weakest) {
+        const reasons = Object.entries(rejected)
+          .map(([property, reason]) => `${property}: ${reason}`)
+          .join(", ");
+        return toolFailure("blocked", `no style was applied (${reasons})`);
+      }
+      const value: StudioSetStyleResult = {
+        applied,
+        rejected,
+        partial: Object.keys(rejected).length > 0,
+        propertyReceipts,
+      };
+      const changed = Object.values(propertyReceipts).some((receipt) => receipt.changed);
+      return weakest.stage === "dispatched"
+        ? dispatched(value, changed)
+        : { ...weakest, ...value, changed };
+    },
+  });
 }
 
 export const STUDIO_SET_TEXT_INPUT_SCHEMA = {
   type: "object",
   properties: {
+    handle: { type: "string", description: "A source-safe element handle from studio_look." },
     text: { type: "string", description: "The new text content." },
     field: {
       type: "string",
@@ -182,36 +216,46 @@ export const STUDIO_SET_TEXT_INPUT_SCHEMA = {
         "Which text field to write, from studio_inspect. Omit for the element's own text.",
     },
   },
-  required: ["text"],
+  required: ["handle", "text"],
   additionalProperties: false,
 } as const;
 
 export const STUDIO_SET_TEXT_DESCRIPTION = [
-  "Set the text of the CURRENTLY SELECTED element. Call studio_select first.",
+  "Set one element's text using its source-safe handle from studio_look.",
   "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.",
+  WRITE_RECEIPT_DESCRIPTION,
 ].join(" ");
 
 export const STUDIO_SET_STYLE_INPUT_SCHEMA = {
   type: "object",
   properties: {
+    handle: { type: "string", description: "A source-safe element handle from studio_look." },
     styles: {
       type: "object",
       description: 'CSS property to value, for example {"color": "red", "font-size": "48px"}.',
       additionalProperties: { type: "string" },
     },
   },
-  required: ["styles"],
+  required: ["handle", "styles"],
   additionalProperties: false,
 } as const;
 
 export const STUDIO_SET_STYLE_DESCRIPTION = [
-  "Set inline styles on the CURRENTLY SELECTED element. Call studio_select first.",
+  "Set inline styles on one element using its source-safe handle from studio_look.",
   "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.",
+  WRITE_RECEIPT_DESCRIPTION,
 ].join(" ");
+
+function preDispatchFailure<T extends object>(
+  operation: "set-text" | "set-style",
+  failure: ToolFailure,
+): StudioWriteResult<T> {
+  return { ...failure, stage: "refused", operation };
+}