@hyperframes/studio 0.8.15 → 0.8.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.15",
+  "version": "0.8.17",
   "description": "",
   "repository": {
     "type": "git",
@@ -40,6 +40,7 @@
     "@codemirror/state": "^6.6.0",
     "@codemirror/theme-one-dark": "^6.1.2",
     "@codemirror/view": "6.40.0",
+    "@mcp-b/global": "^5.0.1",
     "@phosphor-icons/react": "^2.1.10",
     "@tanstack/react-virtual": "^3.14.6",
     "bpm-detective": "^2.0.5",
@@ -47,11 +48,11 @@
     "gsap": "^3.13.0",
     "marked": "^14.1.4",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.8.15",
-    "@hyperframes/player": "0.8.15",
-    "@hyperframes/parsers": "0.8.15",
-    "@hyperframes/studio-server": "0.8.15",
-    "@hyperframes/sdk": "0.8.15"
+    "@hyperframes/player": "0.8.17",
+    "@hyperframes/parsers": "0.8.17",
+    "@hyperframes/studio-server": "0.8.17",
+    "@hyperframes/core": "0.8.17",
+    "@hyperframes/sdk": "0.8.17"
   },
   "devDependencies": {
     "@types/react": "19",
@@ -68,7 +69,7 @@
     "vite": "^6.4.2",
     "vitest": "^3.2.4",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.15"
+    "@hyperframes/producer": "0.8.17"
   },
   "peerDependencies": {
     "react": "19",

package/src/components/EditorShell.tsx

@@ -15,6 +15,7 @@ import { usePlayerStore, type TimelineElement } from "../player";
 import type { BlockPreviewInfo } from "./sidebar/BlocksTab";
 import type { GestureRecordingState } from "./editor/GestureRecordControl";
 import { useTimelineSelectionPreviewSync } from "../hooks/useTimelineSelectionPreviewSync";
+import { StudioAgentTools } from "../webmcp/StudioAgentTools";
 
 type RenderClipContent = (
   element: TimelineElement,
@@ -262,6 +263,9 @@ function EditorShellBody({
       onKeyDown={handleKeyDown}
       tabIndex={-1}
     >
+      {/* Renders nothing; exposes Studio's state to an agentic browser. Mounted
+          here rather than in App because it needs the DomEdit contexts. */}
+      <StudioAgentTools />
       {/* Top row: [left | preview | right] — outer padding + the 8px resize
           seams give the panels CapCut-style separation on the dark canvas. */}
       <div className="flex flex-row flex-1 min-h-0 px-px pt-px">

package/src/components/editor/DomEditCropHandles.test.tsx

@@ -35,7 +35,7 @@ function makeEl(id: string, clip: string): HTMLElement {
 
 function render(
   el: HTMLElement,
-  onStyleCommit: (property: string, value: string) => Promise<void> | void = () => undefined,
+  onStyleCommit: (property: string, value: string) => Promise<unknown> | void = () => undefined,
 ): { root: Root; rerender: (next: HTMLElement) => void } {
   const host = document.createElement("div");
   document.body.append(host);

package/src/components/editor/DomEditCropHandles.tsx

@@ -28,7 +28,7 @@ interface CropGestureState {
 interface DomEditCropHandlesProps {
   selection: DomEditSelection;
   overlayRect: OverlayRect;
-  onStyleCommit?: (property: string, value: string) => Promise<void> | void;
+  onStyleCommit?: (property: string, value: string) => Promise<unknown> | void;
 }
 
 // Hit-strip size (px) for an edge crop handle: THICKNESS extends outward from

package/src/components/editor/DomEditOverlay.tsx

@@ -83,7 +83,7 @@ interface DomEditOverlayProps {
     restore?: () => void,
   ) => Promise<void> | void;
   onRotationCommit: (selection: DomEditSelection, next: { angle: number }) => Promise<void> | void;
-  onStyleCommit?: (property: string, value: string) => Promise<void> | void;
+  onStyleCommit?: (property: string, value: string) => Promise<unknown> | void;
   gridVisible?: boolean;
   gridSpacing?: number;
   recordingState?: GestureRecordingState;

package/src/components/editor/DomEditSelectionChrome.tsx

@@ -123,7 +123,7 @@ interface DomEditSelectionChromeProps {
   groupSelectionCount: number;
   blockedMoveRef: RefObject<BlockedMoveState | null>;
   gestures: GestureHandlers;
-  onStyleCommit?: (property: string, value: string) => Promise<void> | void;
+  onStyleCommit?: (property: string, value: string) => Promise<unknown> | void;
   onBoxMouseDown: (e: React.MouseEvent) => void;
   onBoxClick: (event: React.MouseEvent<HTMLDivElement>) => void;
   /** The canvas' text-editing session: what opens one, and whether one is open. */

package/src/components/editor/anchoredResizeCommitFeedsOffset.test.ts

@@ -1,6 +1,7 @@
 // @vitest-environment happy-dom
 
 import { afterEach, describe, expect, it, vi } from "vitest";
+import { DomEditSaveQueueOpenError } from "../../utils/domEditSaveQueue";
 import type { DomEditSelection } from "./domEditing";
 import type { GestureState, UseDomEditOverlayGesturesOptions } from "./domEditOverlayGestures";
 
@@ -75,7 +76,9 @@ interface CommitCall {
   offset: { x: number; y: number } | undefined;
 }
 
-function buildHarness() {
+function buildHarness(
+  onBoxSizeCommit?: UseDomEditOverlayGesturesOptions["onBoxSizeCommitRef"]["current"],
+) {
   const element = document.createElement("div");
   document.body.append(element);
 
@@ -136,9 +139,12 @@ function buildHarness() {
     onManualDragStartRef: ref(() => {}),
     onPathOffsetCommitRef: ref(() => {}),
     onGroupPathOffsetCommitRef: ref(() => {}),
-    onBoxSizeCommitRef: ref((_s, size, offset) => {
-      commits.push({ size, offset });
-    }),
+    onBoxSizeCommitRef: ref(
+      onBoxSizeCommit ??
+        ((_s, size, offset) => {
+          commits.push({ size, offset });
+        }),
+    ),
     onRotationCommitRef: ref(() => {}),
     onCanvasPointerMoveRef: ref(() => Promise.resolve(null)),
     onCanvasMouseDown: () => {},
@@ -172,6 +178,15 @@ function evt(clientX: number, clientY: number) {
   } as unknown as React.PointerEvent<HTMLDivElement>;
 }
 
+async function finishResize(handlers: ReturnType<typeof createDomEditOverlayGestureHandlers>) {
+  handlers.startGesture("resize", evt(ORIGIN_CENTER.x + 100, ORIGIN_CENTER.y), {
+    resizeHandle: "se",
+  });
+  handlers.onPointerMove(evt(ORIGIN_CENTER.x + 150, ORIGIN_CENTER.y));
+  handlers.onPointerUp(evt(ORIGIN_CENTER.x + 150, ORIGIN_CENTER.y));
+  await Promise.resolve();
+}
+
 afterEach(() => {
   document.body.innerHTML = "";
 });
@@ -211,4 +226,23 @@ describe("anchored corner resize — the release commit feeds the center-pin off
     expect(offset.x).toBeCloseTo(-(size.width - ORIGIN.width) / 2, 0);
     expect(offset.y).toBeCloseTo(-(size.height - ORIGIN.height) / 2, 0);
   });
+
+  it("does not log a paused save queue as an ordinary resize failure", async () => {
+    const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+    const { handlers } = buildHarness(() => Promise.reject(new DomEditSaveQueueOpenError()));
+
+    await finishResize(handlers);
+
+    expect(consoleError).not.toHaveBeenCalled();
+  });
+
+  it("still logs an ordinary resize failure", async () => {
+    const failure = new Error("save failed");
+    const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+    const { handlers } = buildHarness(() => Promise.reject(failure));
+
+    await finishResize(handlers);
+
+    expect(consoleError).toHaveBeenCalledWith("resize commit failed", failure);
+  });
 });

package/src/components/editor/propertyPanelCommitField.tsx

@@ -21,7 +21,7 @@ export function CommitField({
   liveCommit?: boolean;
   align?: "left" | "right";
   onPreview?: (nextValue: string) => void;
-  onCommit: (nextValue: string) => void | Promise<void>;
+  onCommit: (nextValue: string) => void | Promise<unknown>;
 }) {
   const [draft, setDraft] = useState(value);
   const valueRef = useRef(value);

package/src/components/editor/propertyPanelFlatLayoutSection.tsx

@@ -181,7 +181,7 @@ export function LayoutZIndexRow({
   onSetStyle,
 }: {
   styles: Record<string, string>;
-  onSetStyle: (prop: string, value: string) => void | Promise<void>;
+  onSetStyle: (prop: string, value: string) => void | Promise<unknown>;
 }) {
   const zIndex = String(parseInt(styles["z-index"] || "auto", 10) || 0);
   return (
@@ -200,7 +200,7 @@ export function LayoutFlexBlock({
   disabled,
 }: {
   styles: Record<string, string>;
-  onSetStyle: (prop: string, value: string) => void | Promise<void>;
+  onSetStyle: (prop: string, value: string) => void | Promise<unknown>;
   disabled: boolean;
 }) {
   const isFlex = styles.display === "flex" || styles.display === "inline-flex";
@@ -337,7 +337,7 @@ interface FlatLayoutSectionProps
     > {
   element: DomEditSelection;
   styles: Record<string, string>;
-  onSetStyle: (prop: string, value: string) => void | Promise<void>;
+  onSetStyle: (prop: string, value: string) => void | Promise<unknown>;
   disabled: boolean;
 }
 

package/src/components/editor/propertyPanelFlatMaskInsetRows.tsx

@@ -27,7 +27,7 @@ export function FlatMaskInsetRows({
   clipPathValue: string;
   radiusValue: number;
   disabled: boolean;
-  onSetStyle: (prop: string, value: string) => void | Promise<void>;
+  onSetStyle: (prop: string, value: string) => void | Promise<unknown>;
 }) {
   const clipPathPreset = inferClipPathPreset(clipPathValue);
   const parsedClipInsets = parseInsetClipPathSides(clipPathValue);

package/src/components/editor/propertyPanelFlatMediaSection.tsx

@@ -38,7 +38,7 @@ export function FlatMediaSection({
   projectDir: string | null;
   element: DomEditSelection;
   styles: Record<string, string>;
-  onSetStyle: (prop: string, value: string) => void | Promise<void>;
+  onSetStyle: (prop: string, value: string) => void | Promise<unknown>;
   onSetAttribute: (attr: string, value: string) => void | Promise<void>;
   onSetHtmlAttribute: (attr: string, value: string | null) => void | Promise<void>;
   /** A volume lane in the timeline drives the level; the slider cannot. */

package/src/components/editor/propertyPanelFlatPrimitives.tsx

@@ -35,7 +35,7 @@ export function FlatRow({
   /** Renders a trailing 10px caret-down, for select-backed rows. */
   dropdown?: boolean;
   onPreview?: (nextValue: string) => void;
-  onCommit: (nextValue: string) => void | Promise<void>;
+  onCommit: (nextValue: string) => void | Promise<unknown>;
   onReset?: () => void;
 }) {
   const track = useTrackDesignInput();

package/src/components/editor/propertyPanelFlatStyleSections.tsx

@@ -50,7 +50,7 @@ function FlatFillFields({
   element: DomEditSelection;
   styles: Record<string, string>;
   assets: string[];
-  onSetStyle: (prop: string, value: string) => void | Promise<void>;
+  onSetStyle: (prop: string, value: string) => void | Promise<unknown>;
   onPreviewStyle?: (prop: string, value: string) => void;
   onImportAssets?: (files: FileList) => Promise<string[]>;
 }) {
@@ -156,7 +156,7 @@ function FlatStrokeRow({
 }: {
   styles: Record<string, string>;
   disabled: boolean;
-  onSetStyle: (prop: string, value: string) => void | Promise<void>;
+  onSetStyle: (prop: string, value: string) => void | Promise<unknown>;
 }) {
   const borderWidthValue =
     parsePxMetricValue(styles["border-width"] ?? "") ??
@@ -236,7 +236,7 @@ function FlatRadiusRow({
   styles: Record<string, string>;
   gsapBorderRadius?: { tl: number; tr: number; br: number; bl: number } | null;
   disabled: boolean;
-  onSetStyle: (prop: string, value: string) => void | Promise<void>;
+  onSetStyle: (prop: string, value: string) => void | Promise<unknown>;
 }) {
   const radiusValue = parseNumericValue(styles["border-radius"]) ?? 0;
   const radiusTL =
@@ -286,7 +286,7 @@ function FlatShadowBlendRows({
 }: {
   styles: Record<string, string>;
   disabled: boolean;
-  onSetStyle: (prop: string, value: string) => void | Promise<void>;
+  onSetStyle: (prop: string, value: string) => void | Promise<unknown>;
 }) {
   const boxShadowPreset = inferBoxShadowPreset(styles["box-shadow"]);
   const blendValue = styles["mix-blend-mode"] || "normal";
@@ -332,7 +332,7 @@ function FlatBlurSliders({
 }: {
   styles: Record<string, string>;
   disabled: boolean;
-  onSetStyle: (prop: string, value: string) => void | Promise<void>;
+  onSetStyle: (prop: string, value: string) => void | Promise<unknown>;
 }) {
   const filterBlurValue = getCssFilterFunctionPx(styles.filter, "blur");
   const backdropBlurValue = getCssFilterFunctionPx(styles["backdrop-filter"], "blur");
@@ -378,7 +378,7 @@ function FlatOverflowMaskRows({
 }: {
   styles: Record<string, string>;
   disabled: boolean;
-  onSetStyle: (prop: string, value: string) => void | Promise<void>;
+  onSetStyle: (prop: string, value: string) => void | Promise<unknown>;
 }) {
   const radiusValue = parseNumericValue(styles["border-radius"]) ?? 0;
   const clipPathValue = styles["clip-path"] || "none";
@@ -432,7 +432,7 @@ function FlatOpacitySlider({
 }: {
   styles: Record<string, string>;
   disabled: boolean;
-  onSetStyle: (prop: string, value: string) => void | Promise<void>;
+  onSetStyle: (prop: string, value: string) => void | Promise<unknown>;
 }) {
   const opacityValue = Math.round((parseNumericValue(styles.opacity) ?? 1) * 100);
 
@@ -464,7 +464,7 @@ export function FlatStyleSection({
   element: DomEditSelection;
   styles: Record<string, string>;
   assets: string[];
-  onSetStyle: (prop: string, value: string) => void | Promise<void>;
+  onSetStyle: (prop: string, value: string) => void | Promise<unknown>;
   onPreviewStyle?: (prop: string, value: string) => void;
   onImportAssets?: (files: FileList) => Promise<string[]>;
   gsapBorderRadius?: { tl: number; tr: number; br: number; bl: number } | null;

package/src/components/editor/propertyPanelMediaSection.tsx

@@ -35,7 +35,7 @@ export function MediaSection({
   projectDir: string | null;
   element: DomEditSelection;
   styles: Record<string, string>;
-  onSetStyle: (prop: string, value: string) => void | Promise<void>;
+  onSetStyle: (prop: string, value: string) => void | Promise<unknown>;
   onSetAttribute: (attr: string, value: string) => void | Promise<void>;
   onSetHtmlAttribute: (attr: string, value: string | null) => void | Promise<void>;
   onRemoveBackground?: (

package/src/components/editor/propertyPanelPrimitives.tsx

@@ -29,7 +29,7 @@ export function MetricField({
   scrub?: boolean;
   suffix?: string;
   tooltip?: string;
-  onCommit: (nextValue: string) => void | Promise<void>;
+  onCommit: (nextValue: string) => void | Promise<unknown>;
 }) {
   const track = useTrackDesignInput();
   const scrubRef = useRef<{ startX: number; startValue: number; pointerId: number } | null>(null);

package/src/components/editor/propertyPanelStyleSections.tsx

@@ -53,7 +53,7 @@ export function StyleSections({
   element: DomEditSelection;
   styles: Record<string, string>;
   assets: string[];
-  onSetStyle: (prop: string, value: string) => void | Promise<void>;
+  onSetStyle: (prop: string, value: string) => void | Promise<unknown>;
   onImportAssets?: (files: FileList) => Promise<string[]>;
   gsapBorderRadius?: { tl: number; tr: number; br: number; bl: number } | null;
   // When true, the Flex `Section` is suppressed. The flat inspector renders

package/src/components/editor/propertyPanelTypes.ts

@@ -44,7 +44,7 @@ export interface PropertyPanelProps {
   copiedAgentPrompt: boolean;
   onClearSelection: () => void;
   onUngroup?: () => void;
-  onSetStyle: (prop: string, value: string) => void | Promise<void>;
+  onSetStyle: (prop: string, value: string) => void | Promise<unknown>;
   onPreviewStyle?: (prop: string, value: string) => void;
   onSetAttribute: (attr: string, value: string) => void | Promise<void>;
   /** Commits several data-* attributes on the SAME element in ONE atomic

package/src/components/editor/useDomEditOverlayGestures.ts

@@ -58,6 +58,12 @@ import {
 import { logResize, logResizeMove, logResizeSettle } from "../../utils/resizeDebug";
 import { logDrag, logDragSettle, readDragPositions } from "../../utils/dragDebug";
 import { createGroupDragMover } from "./groupDragMove";
+import { DomEditSaveQueueOpenError } from "../../utils/domEditSaveQueue";
+
+function logGestureCommitFailure(message: string, error: unknown): void {
+  if (error instanceof DomEditSaveQueueOpenError) return;
+  console.error(message, error);
+}
 
 export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGesturesOptions) {
   const setDraftOverlayRect = (next: OverlayRect) => {
@@ -409,7 +415,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
       }
       void Promise.resolve(opts.onRotationCommitRef.current(sel, finalRotation))
         .catch((error) => {
-          console.error("rotate commit failed", error);
+          logGestureCommitFailure("rotate commit failed", error);
           if (
             g.manualEditDragToken &&
             isStudioManualEditGestureCurrent(sel.element, g.manualEditDragToken)
@@ -493,7 +499,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
         opts.onBoxSizeCommitRef.current(sel, finalSize, finalOffset ?? undefined, restore),
       )
         .catch((error) => {
-          console.error("resize commit failed", error);
+          logGestureCommitFailure("resize commit failed", error);
         })
         .finally(() => {
           if (member) endManualOffsetDragMembers([member]);

package/src/components/editor/useInspectorGestureTransaction.ts

@@ -1,6 +1,6 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 
-function isPromiseCommit(result: void | Promise<void>): result is Promise<void> {
+function isPromiseCommit(result: void | Promise<unknown>): result is Promise<unknown> {
   return Boolean(result && typeof result.then === "function");
 }
 
@@ -12,7 +12,7 @@ export function useInspectorGestureTransaction<T>({
 }: {
   sourceValue: T;
   onPreview: (value: T) => void;
-  onCommit: (value: T) => void | Promise<void>;
+  onCommit: (value: T) => void | Promise<unknown>;
 }) {
   const sourceRef = useRef(sourceValue);
   const activeRef = useRef<{ before: T; latest: T } | null>(null);
@@ -122,7 +122,7 @@ export function useInspectorGestureDraft<T>({
 }: {
   sourceValue: T;
   onPreview: (value: T) => void;
-  onCommit: (value: T) => void | Promise<void>;
+  onCommit: (value: T) => void | Promise<unknown>;
 }) {
   const [draft, setDraft] = useState(sourceValue);
   const transaction = useInspectorGestureTransaction({

package/src/components/sidebar/AudioRow.tsx

@@ -1,4 +1,5 @@
 import { useState, useRef, useEffect, useCallback } from "react";
+import { classifyWebAudioMediaRoute } from "@hyperframes/core/runtime/web-audio-route";
 import { ContextMenu } from "./AssetContextMenu";
 import { basename, getAudioSubtype, type CopyFeedback } from "./assetHelpers";
 import { TIMELINE_ASSET_MIME } from "../../utils/timelineAssetDrop";
@@ -167,14 +168,24 @@ export function AudioRow({
         setPlaying(false);
         cancelAnimationFrame(animRef.current);
       };
+      // `src` must be set BEFORE classifying: the check reads `currentSrc`/
+      // `src`, and a same-origin `serveUrl` mustn't be judged from a blank
+      // element.
+      el.src = serveUrl;
       audioRef.current = el;
       const analyser = analyserRef.current;
-      if (analyser) {
+      // Same hazard `webAudioRoute.ts` documents for the timeline runtime
+      // (#3458): `createMediaElementSource` on a cross-origin element without
+      // a `crossorigin` opt-in permanently reroutes it to a node that outputs
+      // SILENCE per the Web Audio spec, without throwing. Classify first so
+      // this preview player can't reintroduce that bug — skipping the Web
+      // Audio graph here only costs the frequency-bar visualizer; native
+      // `<audio>` playback below stays audible either way.
+      if (analyser && classifyWebAudioMediaRoute(el).kind === "web-audio") {
         sourceRef.current = actxRef.current.createMediaElementSource(el);
         sourceRef.current.connect(analyser);
         analyser.connect(actxRef.current.destination);
       }
-      el.src = serveUrl;
     }
 
     if (actxRef.current.state === "suspended") await actxRef.current.resume();

package/src/hooks/domEditCommitRunner.ts

@@ -55,3 +55,50 @@ export async function runDomEditCommit(config: DomEditCommitRunnerConfig): Promi
   if (!config.shouldResync()) return;
   await config.resync();
 }
+
+/**
+ * Why a DOM edit commit did not change the file.
+ *
+ * `runDomEditCommit` resolves on persist failure by design (see its contract
+ * above), so a caller cannot learn whether the write landed by awaiting it — a
+ * failed persist and a successful one are indistinguishable. Capture and apply
+ * bugs still reject. The human path does not need to ask about handled persist
+ * failures, because `onError` already put a toast on screen. A programmatic
+ * caller has no screen, so it has to be told.
+ */
+export type DomEditCommitDeclineReason =
+  | "no-project"
+  | "no-selection"
+  | "geometry-property"
+  | "styles-not-editable"
+  | "not-text-editable"
+  | "preview-stale"
+  | "persist-failed";
+
+export type DomEditCommitOutcome = { ok: true } | { ok: false; reason: DomEditCommitDeclineReason };
+
+export function domEditCommitDeclined(reason: DomEditCommitDeclineReason): DomEditCommitOutcome {
+  return { ok: false, reason };
+}
+
+/**
+ * `runDomEditCommit`, reporting whether the write actually landed.
+ *
+ * Owns `onSettled` to do it, and forwards to a caller-supplied one rather than
+ * dropping it. `runDomEditCommit` calls `onSettled` exactly once on both the
+ * success and the failure path, so the flag is always set by the time it
+ * resolves.
+ */
+export async function runReportedDomEditCommit(
+  config: DomEditCommitRunnerConfig,
+): Promise<DomEditCommitOutcome> {
+  let landed = false;
+  await runDomEditCommit({
+    ...config,
+    onSettled: (ok) => {
+      landed = ok;
+      config.onSettled?.(ok);
+    },
+  });
+  return landed ? { ok: true } : domEditCommitDeclined("persist-failed");
+}

package/src/hooks/useDomEditPositionPatchCommit.test.tsx

@@ -0,0 +1,116 @@
+// @vitest-environment jsdom
+import { act } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { DomEditSelection } from "../components/editor/domEditing";
+import { DomEditSaveQueueOpenError } from "../utils/domEditSaveQueue";
+import { mountReactHarness } from "./domSelectionTestHarness";
+import { useDomEditPositionPatchCommit } from "./useDomEditPositionPatchCommit";
+
+Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
+
+let cleanup: (() => void) | null = null;
+
+function selectionStub(): DomEditSelection {
+  const element = document.createElement("div");
+  element.id = "card";
+  return {
+    id: "card",
+    element,
+    label: "Card",
+    tagName: "div",
+    sourceFile: "index.html",
+    compositionPath: "index.html",
+    isCompositionHost: false,
+    isInsideLockedComposition: false,
+    boundingBox: { x: 0, y: 0, width: 100, height: 100 },
+    textContent: null,
+    dataAttributes: {},
+    inlineStyles: {},
+    computedStyles: {},
+    textFields: [],
+    capabilities: {
+      canSelect: true,
+      canEditStyles: true,
+      canCrop: true,
+      canMove: true,
+      canResize: true,
+      canApplyManualOffset: true,
+      canApplyManualSize: true,
+      canApplyManualRotation: true,
+    },
+  };
+}
+
+function renderCommit(params: Parameters<typeof useDomEditPositionPatchCommit>[0]) {
+  const captured: { commit: ReturnType<typeof useDomEditPositionPatchCommit> | null } = {
+    commit: null,
+  };
+  function Probe() {
+    captured.commit = useDomEditPositionPatchCommit(params);
+    return null;
+  }
+  const root = mountReactHarness(<Probe />);
+  cleanup = () => act(() => root.unmount());
+  if (!captured.commit) throw new Error("hook did not initialize");
+  return captured.commit;
+}
+
+function paramsWith(queueDomEditSave: (save: () => Promise<void>) => Promise<void>) {
+  const showToast = vi.fn();
+  return {
+    showToast,
+    params: {
+      activeCompPath: "index.html",
+      persistDomEditOperations: vi.fn().mockResolvedValue(undefined),
+      queueDomEditSave,
+      showToast,
+    },
+  };
+}
+
+const options = { label: "Move layer", coalesceKey: "path-offset:card" };
+
+afterEach(() => {
+  cleanup?.();
+  cleanup = null;
+  vi.restoreAllMocks();
+});
+
+describe("useDomEditPositionPatchCommit", () => {
+  it("rejects when the save queue is paused, so the caller can revert its optimistic change", async () => {
+    const { showToast, params } = paramsWith(() => Promise.reject(new DomEditSaveQueueOpenError()));
+    const commit = renderCommit(params);
+
+    await act(async () => {
+      await expect(commit(selectionStub(), [], options)).rejects.toBeInstanceOf(
+        DomEditSaveQueueOpenError,
+      );
+    });
+
+    // No toast: the paused-save banner already tells the human, and one toast per
+    // blocked edit is what the original swallow existed to prevent.
+    expect(showToast).not.toHaveBeenCalled();
+  });
+
+  it("toasts and rejects on an ordinary save failure", async () => {
+    const { showToast, params } = paramsWith(() => Promise.reject(new Error("server said no")));
+    const commit = renderCommit(params);
+
+    await act(async () => {
+      await expect(commit(selectionStub(), [], options)).rejects.toThrow("server said no");
+    });
+
+    expect(showToast).toHaveBeenCalledWith("server said no");
+  });
+
+  it("resolves when the write lands", async () => {
+    const { showToast, params } = paramsWith((save) => save());
+    const commit = renderCommit(params);
+
+    await act(async () => {
+      await expect(commit(selectionStub(), [], options)).resolves.toBeUndefined();
+    });
+
+    expect(showToast).not.toHaveBeenCalled();
+  });
+});

package/src/hooks/useDomEditPositionPatchCommit.ts

@@ -35,7 +35,12 @@ export function useDomEditPositionPatchCommit({
           skipRefresh: options.skipRefresh ?? true,
         });
       }).catch((error) => {
-        if (error instanceof DomEditSaveQueueOpenError) return;
+        // A paused save queue is not worth a toast: the paused-save banner is
+        // already on screen, and one toast per blocked edit is what this branch
+        // exists to prevent. It still has to REJECT, though. Swallowing it
+        // resolved the commit, which skipped the caller's revert, so the element
+        // stayed where the drag put it while nothing reached the file.
+        if (error instanceof DomEditSaveQueueOpenError) throw error;
         showToast(error instanceof Error ? error.message : "Failed to save position");
         trackStudioSaveFailure({
           source: "dom_edit",