@hyperframes/studio 0.8.16 → 0.8.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.16",
+  "version": "0.8.18",
   "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.16",
-    "@hyperframes/parsers": "0.8.16",
-    "@hyperframes/player": "0.8.16",
-    "@hyperframes/studio-server": "0.8.16",
-    "@hyperframes/sdk": "0.8.16"
+    "@hyperframes/core": "0.8.18",
+    "@hyperframes/parsers": "0.8.18",
+    "@hyperframes/player": "0.8.18",
+    "@hyperframes/sdk": "0.8.18",
+    "@hyperframes/studio-server": "0.8.18"
   },
   "devDependencies": {
     "@types/react": "19",
@@ -68,7 +69,7 @@
     "vite": "^6.4.2",
     "vitest": "^3.2.4",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.16"
+    "@hyperframes/producer": "0.8.18"
   },
   "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/nle/useCompositionStack.test.tsx

@@ -42,3 +42,72 @@ describe("useCompositionStack — project scoping", () => {
     });
   }
 });
+
+describe("useCompositionStack — activating a composition by path", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  function mountStack(activeCompositionPath: string | null) {
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    const seen: { stack: ReturnType<typeof useCompositionStack>["compositionStack"] } = {
+      stack: [],
+    };
+
+    function Harness(props: { activeCompositionPath: string | null }) {
+      seen.stack = useCompositionStack({ projectId: "p", ...props }).compositionStack;
+      return null;
+    }
+
+    return { root, seen, Harness, activeCompositionPath };
+  }
+
+  // The root stays on the master level; everything else pushes a second level.
+  for (const path of [
+    "compositions/scene-a.html",
+    "parts/part-1.html",
+    "chapter-2.html",
+    "a/b/c/deep.html",
+  ]) {
+    it(`pushes a level for ${path}`, async () => {
+      const { root, seen, Harness } = mountStack(path);
+
+      await act(async () => {
+        root.render(<Harness activeCompositionPath={path} />);
+      });
+
+      expect(seen.stack).toHaveLength(2);
+      expect(seen.stack[1]?.id).toBe(path);
+      expect(seen.stack[1]?.previewUrl).toBe(`/api/projects/p/preview/comp/${path}`);
+
+      act(() => root.unmount());
+    });
+  }
+
+  it("labels a non-compositions/ path without mangling it", async () => {
+    const { root, seen, Harness } = mountStack("parts/part-1.html");
+
+    await act(async () => {
+      root.render(<Harness activeCompositionPath="parts/part-1.html" />);
+    });
+
+    expect(seen.stack[1]?.label).toBe("parts/part-1");
+
+    act(() => root.unmount());
+  });
+
+  it("keeps the master alone for the root composition", async () => {
+    const { root, seen, Harness } = mountStack("index.html");
+
+    await act(async () => {
+      root.render(<Harness activeCompositionPath="index.html" />);
+    });
+
+    expect(seen.stack).toHaveLength(1);
+    expect(seen.stack[0]?.id).toBe("master");
+
+    act(() => root.unmount());
+  });
+});

package/src/components/nle/useCompositionStack.ts

@@ -108,7 +108,13 @@ export function useCompositionStack({
     if (activeCompositionPath === "index.html") {
       usePlayerStore.getState().setElements([]);
       updateCompositionStack([master]);
-    } else if (activeCompositionPath && activeCompositionPath.startsWith("compositions/")) {
+    } else if (activeCompositionPath) {
+      // Any composition file that isn't the root, wherever it lives. Gating
+      // this on a `compositions/` prefix meant a project laying its comps out
+      // anywhere else (`parts/part-1.html`, generated multi-part builds) hit
+      // no branch at all: the stack kept the master mounted while the Comps
+      // panel highlighted the row, so the canvas and timeline stayed on
+      // index.html and edits landed in the root file.
       const label = activeCompositionPath.replace(/^compositions\//, "").replace(/\.html$/, "");
       const previewUrl = `/api/projects/${projectId}/preview/comp/${encodePreviewPath(activeCompositionPath)}`;
       usePlayerStore.getState().setElements([]);
@@ -116,7 +122,7 @@ export function useCompositionStack({
         if (prev[prev.length - 1]?.id === activeCompositionPath) return prev;
         return [master, { id: activeCompositionPath, label, previewUrl }];
       });
-    } else if (!activeCompositionPath) {
+    } else {
       usePlayerStore.getState().setElements([]);
       updateCompositionStack([master]);
     }

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