@hyperframes/studio 0.8.24 → 0.8.26

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

@@ -6,7 +6,19 @@ import {
   type StudioTransformResult,
   type TransformToolDeps,
 } from "./transformTools";
-import { expectFailure, expectOk, previewElement, selectionFor } from "../webmcpTestUtils";
+import {
+  expectFailure,
+  expectOk,
+  previewElement,
+  selectionFor,
+  sourceHandle,
+  targetedWriteDeps,
+} from "../webmcpTestUtils";
+
+const transformInput = (input: Record<string, unknown>) => ({
+  handle: sourceHandle("headline"),
+  ...input,
+});
 
 /**
  * A stand-in for the rendered box. happy-dom and jsdom report all-zero rects,
@@ -23,9 +35,9 @@ function boxStore(initial: ElementBox) {
 
 function transformDeps(overrides: Partial<TransformToolDeps> = {}): TransformToolDeps {
   const element = previewElement('<h1 id="headline">Ship it</h1>', "headline");
+  const selection = selectionFor(element);
   return {
-    getCurrentSelection: () => selectionFor(element),
-    getWriteBlockedReason: () => null,
+    ...targetedWriteDeps(selection),
     readBox: () => ({ x: 0, y: 0, width: 100, height: 50 }),
     moveTo: async () => undefined,
     resizeTo: async () => undefined,
@@ -34,16 +46,31 @@ function transformDeps(overrides: Partial<TransformToolDeps> = {}): TransformToo
   };
 }
 
+async function resizeAndMove(moveLands: boolean): Promise<StudioTransformResult> {
+  const store = boxStore({ x: 0, y: 0, width: 100, height: 50 });
+  const resizeTo = vi.fn(async () => {
+    store.set({ width: 200, height: 80 });
+  });
+  const moveTo = vi.fn(async () => {
+    if (moveLands) store.set({ x: 40, y: 40 });
+  });
+  const result = await studioTransform(transformDeps({ readBox: store.read, resizeTo, moveTo }), {
+    ...transformInput({ x: 40, y: 40, width: 200, height: 80 }),
+  });
+  return expectOk<StudioTransformResult>(result);
+}
+
 describe("studioTransform", () => {
   it("reports the box read back, not the box requested", async () => {
     const store = boxStore({ x: 0, y: 0, width: 100, height: 50 });
     // The handler lands somewhere other than asked, which is what a clamp or a
     // layout constraint does.
-    const resizeTo = vi.fn(async () => store.set({ width: 300, height: 120 }));
+    const resizeTo = vi.fn(async () => {
+      store.set({ width: 300, height: 120 });
+    });
 
     const result = await studioTransform(transformDeps({ readBox: store.read, resizeTo }), {
-      width: 999,
-      height: 999,
+      ...transformInput({ width: 999, height: 999 }),
     });
 
     const ok = expectOk<StudioTransformResult>(result);
@@ -52,69 +79,122 @@ describe("studioTransform", () => {
     expect(ok.applied).toContain("resize");
   });
 
-  it("reports a silent no-op as unchanged instead of success", async () => {
+  it("reports a void actor's silent no-op as dispatched and unchanged", async () => {
     // handleGsapAwarePathOffsetCommit is `if (gsapCommitMutation) {...}` with no
     // else branch. Without GSAP it resolves having written nothing, and echoing
     // the request back would be a lie the agent builds on.
     const store = boxStore({ x: 10, y: 10, width: 100, height: 50 });
     const moveTo = vi.fn(async () => undefined);
 
-    const result = expectFailure(
-      await studioTransform(transformDeps({ readBox: store.read, moveTo }), { x: 500, y: 400 }),
+    const result = expectOk<StudioTransformResult>(
+      await studioTransform(
+        transformDeps({ readBox: store.read, moveTo }),
+        transformInput({ x: 500, y: 400 }),
+      ),
     );
 
     expect(moveTo).toHaveBeenCalled();
-    expect(result.kind).toBe("blocked");
-    expect(result.reason).toMatch(/did not move/);
-    expect(result.hint).toMatch(/GSAP/);
+    expect(result.stage).toBe("dispatched");
+    expect(result.unchanged.move).toMatch(/did not move/);
   });
 
   it("separates what landed from what did not, in one call", async () => {
-    const store = boxStore({ x: 0, y: 0, width: 100, height: 50 });
-    const resizeTo = vi.fn(async () => store.set({ width: 200, height: 80 }));
-    const moveTo = vi.fn(async () => undefined);
-
-    const result = await studioTransform(transformDeps({ readBox: store.read, resizeTo, moveTo }), {
-      x: 40,
-      y: 40,
-      width: 200,
-      height: 80,
-    });
+    const result = await resizeAndMove(false);
 
-    const ok = expectOk<StudioTransformResult>(result);
-    expect(ok.applied).toEqual(["resize"]);
-    expect(ok.unchanged.move).toMatch(/did not move/);
+    expect(result.applied).toEqual(["resize"]);
+    expect(result.unchanged.move).toMatch(/did not move/);
   });
 
   it("re-reads between operations so a later one sees the earlier result", async () => {
-    const store = boxStore({ x: 0, y: 0, width: 100, height: 50 });
-    const resizeTo = vi.fn(async () => store.set({ width: 200, height: 80 }));
-    const moveTo = vi.fn(async () => store.set({ x: 40, y: 40 }));
-
-    const result = await studioTransform(transformDeps({ readBox: store.read, resizeTo, moveTo }), {
-      x: 40,
-      y: 40,
-      width: 200,
-      height: 80,
-    });
+    const result = await resizeAndMove(true);
 
     // Move is judged against the box AFTER the resize. Comparing against the
     // original would credit the resize's change to the move.
-    const ok = expectOk<StudioTransformResult>(result);
-    expect(ok.applied).toEqual(["resize", "move"]);
-    expect(ok.unchanged).toEqual({});
+    expect(result.applied).toEqual(["resize", "move"]);
+    expect(result.unchanged).toEqual({});
   });
 
-  it("reports rotation as dispatched rather than verified", async () => {
+  it("reports durable partial success when a later operation fails", async () => {
+    const store = boxStore({ x: 0, y: 0, width: 100, height: 50 });
+    const result = expectOk<StudioTransformResult>(
+      await studioTransform(
+        transformDeps({
+          readBox: store.read,
+          resizeTo: async () => {
+            store.set({ width: 200, height: 80 });
+            return {
+              ok: true,
+              persistence: {
+                sourceFile: "index.html",
+                version: '"sha256:resize"',
+                changed: true,
+              },
+            };
+          },
+          moveTo: async () => ({ ok: false, reason: "the move actor failed" }),
+        }),
+        transformInput({ width: 200, height: 80, x: 40, y: 40 }),
+      ),
+    );
+
+    expect(result).toMatchObject({
+      stage: "saved",
+      changed: true,
+      partial: true,
+      applied: ["resize"],
+      failed: { move: expect.stringContaining("move actor failed") },
+    });
+  });
+
+  it("aggregates changed across durable operations instead of trusting the last no-op", async () => {
+    const store = boxStore({ x: 0, y: 0, width: 100, height: 50 });
+    const result = expectOk<StudioTransformResult>(
+      await studioTransform(
+        transformDeps({
+          readBox: store.read,
+          resizeTo: async () => {
+            store.set({ width: 200, height: 80 });
+            return {
+              ok: true,
+              persistence: {
+                sourceFile: "index.html",
+                version: '"sha256:resize"',
+                changed: true,
+              },
+            };
+          },
+          moveTo: async () => ({
+            ok: true,
+            persistence: {
+              sourceFile: "index.html",
+              version: '"sha256:noop"',
+              changed: false,
+            },
+          }),
+        }),
+        transformInput({ width: 200, height: 80, x: 0, y: 0 }),
+      ),
+    );
+
+    expect(result.changed).toBe(true);
+    expect(result.applied).toEqual(["resize"]);
+  });
+
+  it("reports unobserved rotation as dispatched without claiming it applied", async () => {
     // `rotate` is an individual transform property and does not appear in the
     // computed transform, so there is no honest box-derived signal for it.
     const rotateTo = vi.fn(async () => undefined);
 
-    const result = await studioTransform(transformDeps({ rotateTo }), { rotate: 15 });
+    const result = await studioTransform(
+      transformDeps({ rotateTo }),
+      transformInput({ rotate: 15 }),
+    );
 
     const ok = expectOk<StudioTransformResult>(result);
     expect(rotateTo).toHaveBeenCalledWith(expect.anything(), { angle: 15 });
-    expect(ok.applied).toEqual(["rotate"]);
+    expect(ok.applied).toEqual([]);
+    expect(ok.unchanged.rotation).toMatch(/dispatched but not independently observed/);
+    expect(ok.changed).toBe(false);
   });
 
   it("refuses to write while a conflict is waiting for the user", async () => {
@@ -123,7 +203,7 @@ describe("studioTransform", () => {
     const result = expectFailure(
       await studioTransform(
         transformDeps({ getWriteBlockedReason: () => "Auto-save is paused", moveTo }),
-        { x: 10, y: 10 },
+        transformInput({ x: 10, y: 10 }),
       ),
     );
 
@@ -136,8 +216,12 @@ describe("studioTransform", () => {
     const resizeTo = vi.fn();
     const deps = transformDeps({ moveTo, resizeTo });
 
-    expect(expectFailure(await studioTransform(deps, { x: 10 })).reason).toMatch(/together/);
-    expect(expectFailure(await studioTransform(deps, { width: 10 })).reason).toMatch(/together/);
+    expect(expectFailure(await studioTransform(deps, transformInput({ x: 10 }))).reason).toMatch(
+      /together/,
+    );
+    expect(
+      expectFailure(await studioTransform(deps, transformInput({ width: 10 }))).reason,
+    ).toMatch(/together/);
     expect(moveTo).not.toHaveBeenCalled();
     expect(resizeTo).not.toHaveBeenCalled();
   });
@@ -145,17 +229,19 @@ describe("studioTransform", () => {
   it("rejects a negative size and an empty request", async () => {
     const deps = transformDeps();
 
-    expect(expectFailure(await studioTransform(deps, { width: -1, height: 10 })).kind).toBe(
-      "invalid",
+    expect(
+      expectFailure(await studioTransform(deps, transformInput({ width: -1, height: 10 }))).kind,
+    ).toBe("invalid");
+    expect(expectFailure(await studioTransform(deps, transformInput({}))).reason).toMatch(
+      /at least one/,
     );
-    expect(expectFailure(await studioTransform(deps, {})).reason).toMatch(/at least one/);
   });
 
   it("rejects non-finite numbers rather than passing them to a handler", async () => {
     const moveTo = vi.fn();
 
     const result = expectFailure(
-      await studioTransform(transformDeps({ moveTo }), { x: Number.NaN, y: 10 }),
+      await studioTransform(transformDeps({ moveTo }), transformInput({ x: Number.NaN, y: 10 })),
     );
 
     expect(result.kind).toBe("invalid");
@@ -166,14 +252,14 @@ describe("studioTransform", () => {
     const moveTo = vi.fn();
 
     const result = expectFailure(
-      await studioTransform(transformDeps({ getCurrentSelection: () => null, moveTo }), {
-        x: 1,
-        y: 1,
-      }),
+      await studioTransform(
+        transformDeps({ buildSelection: async () => null, moveTo }),
+        transformInput({ x: 1, y: 1 }),
+      ),
     );
 
-    expect(result.kind).toBe("invalid");
-    expect(result.hint).toMatch(/studio_select/);
+    expect(result.kind).toBe("blocked");
+    expect(result.hint).toMatch(/parent or child/);
     expect(moveTo).not.toHaveBeenCalled();
   });
 });

package/src/webmcp/tools/transformTools.ts

@@ -21,7 +21,19 @@
  */
 
 import type { DomEditSelection } from "../../components/editor/domEditingTypes";
-import { toolFailure, toolOk, type ToolFailure, type ToolResult } from "../toolResult";
+import type { DomEditCommitOutcome } from "../../hooks/domEditCommitRunner";
+import type { DomEditPersistOutcome } from "../../hooks/domEditCommitTypes";
+import { toolFailure, type ToolFailure } from "../toolResult";
+import {
+  dispatched,
+  runTargetedWrite,
+  saved,
+  verified,
+  type StudioWriteAdapterSuccess,
+  type StudioWriteResult,
+  type TargetedWriteDeps,
+  WRITE_RECEIPT_DESCRIPTION,
+} from "../writeCoordinator";
 
 export interface ElementBox {
   x: number;
@@ -30,17 +42,25 @@ export interface ElementBox {
   height: number;
 }
 
-export interface TransformToolDeps {
-  getCurrentSelection: () => DomEditSelection | null;
-  getWriteBlockedReason: () => string | null;
+export interface TransformToolDeps extends TargetedWriteDeps {
   /** The element's box as it renders right now. */
   readBox: (selection: DomEditSelection) => ElementBox;
-  moveTo: (selection: DomEditSelection, next: { x: number; y: number }) => Promise<void>;
-  resizeTo: (selection: DomEditSelection, next: { width: number; height: number }) => Promise<void>;
-  rotateTo: (selection: DomEditSelection, next: { angle: number }) => Promise<void>;
+  moveTo: (
+    selection: DomEditSelection,
+    next: { x: number; y: number },
+  ) => Promise<DomEditCommitOutcome | void>;
+  resizeTo: (
+    selection: DomEditSelection,
+    next: { width: number; height: number },
+  ) => Promise<DomEditCommitOutcome | void>;
+  rotateTo: (
+    selection: DomEditSelection,
+    next: { angle: number },
+  ) => Promise<DomEditCommitOutcome | void>;
 }
 
 export interface StudioTransformInput {
+  handle?: unknown;
   x?: unknown;
   y?: unknown;
   width?: unknown;
@@ -54,6 +74,9 @@ export interface StudioTransformResult {
   applied: string[];
   /** Requested operations whose effect could not be observed, with why. */
   unchanged: Record<string, string>;
+  /** Present when earlier operations landed before a later operation failed. */
+  partial?: true;
+  failed?: Partial<Record<TransformOperation, string>>;
 }
 
 const NO_OP_HINT =
@@ -63,15 +86,6 @@ function readNumber(value: unknown): number | null {
   return typeof value === "number" && Number.isFinite(value) ? value : null;
 }
 
-function guard(deps: TransformToolDeps): ToolFailure | null {
-  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;
-}
-
 interface TransformRequest {
   move: { x: number; y: number } | null;
   size: { width: number; height: number } | null;
@@ -126,75 +140,219 @@ function parseRequest(input: StudioTransformInput): TransformRequest | ToolFailu
   };
 }
 
-export async function studioTransform(
+type TransformOperation = "resize" | "move" | "rotate";
+
+interface TransformObservation {
+  operation: TransformOperation;
+  changed: boolean;
+  unchangedReason?: string;
+  persistence?: DomEditPersistOutcome;
+}
+
+function transformPreflight(
+  request: TransformRequest,
+  selection: DomEditSelection,
+): ToolFailure | null {
+  if (
+    request.size &&
+    !selection.capabilities.canResize &&
+    !selection.capabilities.canApplyManualSize
+  ) {
+    return toolFailure("blocked", "this target cannot be resized");
+  }
+  if (
+    request.move &&
+    !selection.capabilities.canMove &&
+    !selection.capabilities.canApplyManualOffset
+  ) {
+    return toolFailure("blocked", "this target cannot be moved");
+  }
+  if (request.rotate !== null && !selection.capabilities.canApplyManualRotation) {
+    return toolFailure("blocked", "this target cannot be rotated");
+  }
+  return null;
+}
+
+async function observeResize(
   deps: TransformToolDeps,
-  input: StudioTransformInput,
-): Promise<ToolResult<StudioTransformResult>> {
-  const request = parseRequest(input);
-  if (isFailure(request)) return request;
+  selection: DomEditSelection,
+  size: NonNullable<TransformRequest["size"]>,
+): Promise<TransformObservation | ToolFailure> {
+  const before = deps.readBox(selection);
+  const outcome = await deps.resizeTo(selection, size);
+  if (outcome && !outcome.ok) return outcomeFailure(outcome.reason);
+  const after = deps.readBox(selection);
+  const changed = after.width !== before.width || after.height !== before.height;
+  return {
+    operation: "resize",
+    changed,
+    ...(!changed ? { unchangedReason: "the element's size did not change" } : {}),
+    ...(outcome?.ok && outcome.persistence ? { persistence: outcome.persistence } : {}),
+  };
+}
+
+async function observeMove(
+  deps: TransformToolDeps,
+  selection: DomEditSelection,
+  move: NonNullable<TransformRequest["move"]>,
+): Promise<TransformObservation | ToolFailure> {
+  const before = deps.readBox(selection);
+  const outcome = await deps.moveTo(selection, move);
+  if (outcome && !outcome.ok) return outcomeFailure(outcome.reason);
+  const after = deps.readBox(selection);
+  const changed = after.x !== before.x || after.y !== before.y;
+  return {
+    operation: "move",
+    changed,
+    ...(!changed ? { unchangedReason: `the element did not move. ${NO_OP_HINT}` } : {}),
+    ...(outcome?.ok && outcome.persistence ? { persistence: outcome.persistence } : {}),
+  };
+}
 
-  const blocked = guard(deps);
-  if (blocked) return blocked;
+async function observeRotation(
+  deps: TransformToolDeps,
+  selection: DomEditSelection,
+  rotate: number,
+): Promise<TransformObservation | ToolFailure> {
+  const outcome = await deps.rotateTo(selection, { angle: rotate });
+  if (outcome && !outcome.ok) return outcomeFailure(outcome.reason);
+  if (!outcome || !outcome.persistence) {
+    return {
+      operation: "rotate",
+      changed: false,
+      unchangedReason: "rotation was dispatched but not independently observed",
+    };
+  }
+  if (!outcome.persistence.changed) {
+    return {
+      operation: "rotate",
+      changed: false,
+      unchangedReason: "the durable write reported no rotation change",
+      persistence: outcome.persistence,
+    };
+  }
+  return { operation: "rotate", changed: true, persistence: outcome.persistence };
+}
 
-  const selection = deps.getCurrentSelection();
-  if (!selection) return toolFailure("invalid", "nothing is selected");
+function requestMatchesBox(request: TransformRequest, box: ElementBox): boolean {
+  const sizeMatches =
+    !request.size || (box.width === request.size.width && box.height === request.size.height);
+  const moveMatches = !request.move || (box.x === request.move.x && box.y === request.move.y);
+  return sizeMatches && moveMatches;
+}
 
-  const applied: string[] = [];
-  const unchanged: Record<string, string> = {};
+function transformReceipt(
+  request: TransformRequest,
+  initial: ElementBox,
+  box: ElementBox,
+  observations: TransformObservation[],
+  failure?: { operation: TransformOperation; reason: string },
+): StudioWriteAdapterSuccess<StudioTransformResult> {
+  const applied = observations.filter((item) => item.changed).map((item) => item.operation);
+  const unchanged = Object.fromEntries(
+    observations.flatMap((item) => {
+      if (!item.unchangedReason) return [];
+      const key = item.operation === "rotate" ? "rotation" : item.operation;
+      return [[key, item.unchangedReason]];
+    }),
+  );
+  const value: StudioTransformResult = {
+    box,
+    applied,
+    unchanged,
+    ...(failure ? { partial: true, failed: { [failure.operation]: failure.reason } } : {}),
+  };
+  const changed = observations.some((item) => item.changed) || !boxesEqual(initial, box);
+  const allDurable = observations.every((item) => item.persistence !== undefined);
+  const persistence = observations.at(-1)?.persistence;
+  if (!allDurable || !persistence) return dispatched(value, changed);
+  if (!failure && requestMatchesBox(request, box) && request.rotate === null) {
+    return { ...verified(value, persistence, { before: initial, after: box }), changed };
+  }
+  return { ...saved(value, persistence), changed };
+}
 
-  // Sequential, and each one re-reads first, so a move is judged against the box
-  // AFTER a resize in the same call rather than against the original.
+async function writeTransform(
+  deps: TransformToolDeps,
+  selection: DomEditSelection,
+  request: TransformRequest,
+): Promise<StudioWriteAdapterSuccess<StudioTransformResult> | ToolFailure> {
+  const initial = deps.readBox(selection);
+  const observations: TransformObservation[] = [];
   if (request.size) {
-    const before = deps.readBox(selection);
-    await deps.resizeTo(selection, request.size);
-    const after = deps.readBox(selection);
-    if (after.width !== before.width || after.height !== before.height) applied.push("resize");
-    else unchanged.resize = "the element's size did not change";
+    const observation = await observeResize(deps, selection, request.size);
+    if (isFailure(observation)) return observation;
+    observations.push(observation);
   }
-
   if (request.move) {
-    const before = deps.readBox(selection);
-    await deps.moveTo(selection, request.move);
-    const after = deps.readBox(selection);
-    if (after.x !== before.x || after.y !== before.y) applied.push("move");
-    else unchanged.move = `the element did not move. ${NO_OP_HINT}`;
+    const observation = await observeMove(deps, selection, request.move);
+    if (isFailure(observation)) {
+      if (observations.length === 0) return observation;
+      return transformReceipt(request, initial, deps.readBox(selection), observations, {
+        operation: "move",
+        reason: observation.reason,
+      });
+    }
+    observations.push(observation);
   }
-
   if (request.rotate !== null) {
-    // Rotation is written as the CSS `rotate` property, an individual transform
-    // property that does NOT appear in getComputedStyle().transform. There is no
-    // reliable box-derived signal, so this is reported as dispatched rather than
-    // verified, and the description says so.
-    await deps.rotateTo(selection, { angle: request.rotate });
-    applied.push("rotate");
+    const observation = await observeRotation(deps, selection, request.rotate);
+    if (isFailure(observation)) {
+      if (observations.length === 0) return observation;
+      return transformReceipt(request, initial, deps.readBox(selection), observations, {
+        operation: "rotate",
+        reason: observation.reason,
+      });
+    }
+    observations.push(observation);
   }
+  return transformReceipt(request, initial, deps.readBox(selection), observations);
+}
 
-  if (applied.length === 0) {
-    return toolFailure(
-      "blocked",
-      `nothing changed: ${Object.values(unchanged).join("; ")}`,
-      NO_OP_HINT,
-    );
+export async function studioTransform(
+  deps: TransformToolDeps,
+  input: StudioTransformInput,
+  signal: AbortSignal = new AbortController().signal,
+): Promise<StudioWriteResult<StudioTransformResult>> {
+  const request = parseRequest(input);
+  if (isFailure(request)) {
+    return { ...request, stage: "refused", operation: "transform" };
   }
 
-  return toolOk<StudioTransformResult>({ box: deps.readBox(selection), applied, unchanged });
+  return runTargetedWrite(deps, {
+    handle: input.handle,
+    operation: "transform",
+    signal,
+    preflight: (selection) => transformPreflight(request, selection),
+    write: (selection) => writeTransform(deps, selection, request),
+  });
+}
+
+function boxesEqual(a: ElementBox, b: ElementBox): boolean {
+  return a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height;
+}
+
+function outcomeFailure(reason: string): ToolFailure {
+  return toolFailure("failed", `the transform was not applied: ${reason}`);
 }
 
 export const STUDIO_TRANSFORM_INPUT_SCHEMA = {
   type: "object",
   properties: {
+    handle: { type: "string", description: "A source-safe element handle from studio_look." },
     x: { type: "number", description: "New x offset in pixels. Must be paired with y." },
     y: { type: "number", description: "New y offset in pixels. Must be paired with x." },
     width: { type: "number", minimum: 0, description: "New width. Must be paired with height." },
     height: { type: "number", minimum: 0, description: "New height. Must be paired with width." },
     rotate: { type: "number", description: "Rotation in degrees." },
   },
+  required: ["handle"],
   additionalProperties: false,
 } as const;
 
 export const STUDIO_TRANSFORM_DESCRIPTION = [
-  "Move, resize or rotate the CURRENTLY SELECTED element, the way a drag would.",
-  "Call studio_select first. Give x with y, and width with height.",
+  "Move, resize or rotate one element using its source-safe handle from studio_look.",
+  "Give x with y, and width with height.",
   "The result's `box` is READ BACK after the write, not echoed from your request, and",
   "`applied` lists what actually took effect. Check it.",
   "Move and rotate are written as GSAP code, so in a composition with no GSAP timeline they",
@@ -202,4 +360,5 @@ export const STUDIO_TRANSFORM_DESCRIPTION = [
   "Rotation is reported as dispatched rather than verified, because the CSS `rotate` property",
   "does not appear in the element's computed transform.",
   "Returns `ok: true`, or `ok: false` with `kind`, `reason` and a `hint`.",
+  WRITE_RECEIPT_DESCRIPTION,
 ].join(" ");