@hyperframes/studio 0.8.114 → 0.8.116

package/src/components/editor/SnapToolbar.tsx

@@ -1,3 +1,4 @@
+import { trackPreviewFeatureUsed } from "../../utils/previewFeatureUsage";
 import { memo, useCallback, useEffect, useRef, useState } from "react";
 import { MagnetStraight, GridFour, Path, Ruler, FrameCorners } from "@phosphor-icons/react";
 import { usePlayerStore } from "../../player/store/playerStore";
@@ -16,6 +17,16 @@ export const SnapToolbar = memo(function SnapToolbar() {
   const setMotionPathArmed = usePlayerStore((s) => s.setMotionPathArmed);
   const popoverRef = useRef<HTMLDivElement>(null);
   const gridButtonRef = useRef<HTMLButtonElement>(null);
+  const gridSpacingAtFocus = useRef<number | null>(null);
+  const currentGridSpacing = useRef(prefs.gridSpacing);
+  currentGridSpacing.current = prefs.gridSpacing;
+  const settleGridSpacing = useCallback(() => {
+    const previous = gridSpacingAtFocus.current;
+    gridSpacingAtFocus.current = null;
+    if (previous !== null && previous !== currentGridSpacing.current)
+      trackPreviewFeatureUsed("grid_spacing", "field");
+  }, []);
+  useEffect(() => settleGridSpacing, [settleGridSpacing]);
 
   const updatePrefs = useCallback(
     (patch: Partial<typeof prefs>) => {
@@ -26,10 +37,12 @@ export const SnapToolbar = memo(function SnapToolbar() {
 
   const toggleSnap = useCallback(() => {
     updatePrefs({ snapEnabled: !prefs.snapEnabled });
+    trackPreviewFeatureUsed("snapping", "button");
   }, [prefs.snapEnabled, updatePrefs]);
 
   const toggleGrid = useCallback(() => {
     updatePrefs({ gridVisible: !prefs.gridVisible });
+    trackPreviewFeatureUsed("grid", "button");
   }, [prefs.gridVisible, updatePrefs]);
 
   useEffect(() => {
@@ -41,10 +54,12 @@ export const SnapToolbar = memo(function SnapToolbar() {
       if (e.key === "s" && !e.metaKey && !e.ctrlKey && !e.altKey) {
         e.preventDefault();
         updatePrefs({ snapEnabled: !prefs.snapEnabled });
+        if (!e.repeat) trackPreviewFeatureUsed("snapping", "keyboard");
       }
       if (e.key === "g" && !e.metaKey && !e.ctrlKey && !e.altKey) {
         e.preventDefault();
         updatePrefs({ gridVisible: !prefs.gridVisible });
+        if (!e.repeat) trackPreviewFeatureUsed("grid", "keyboard");
       }
     };
     document.addEventListener("keydown", handleKeyDown);
@@ -56,11 +71,12 @@ export const SnapToolbar = memo(function SnapToolbar() {
     const handleClickOutside = (e: MouseEvent) => {
       const target = e.target as Node;
       if (popoverRef.current?.contains(target) || gridButtonRef.current?.contains(target)) return;
+      settleGridSpacing();
       setGridPopoverOpen(false);
     };
     document.addEventListener("mousedown", handleClickOutside);
     return () => document.removeEventListener("mousedown", handleClickOutside);
-  }, [gridPopoverOpen]);
+  }, [gridPopoverOpen, settleGridSpacing]);
 
   return (
     <div
@@ -101,7 +117,10 @@ export const SnapToolbar = memo(function SnapToolbar() {
                 ? "bg-studio-accent/20 text-accent-ink"
                 : "bg-black/40 text-white/60 hover:bg-black/60 hover:text-white/80"
             }`}
-            onClick={toggle}
+            onClick={() => {
+              toggle();
+              trackPreviewFeatureUsed(key === "rulerVisible" ? "ruler" : "safe_margins", "button");
+            }}
             title={`${label} ${visible ? "on" : "off"}`}
             aria-label={`Toggle ${label.toLowerCase()}`}
             aria-pressed={visible}
@@ -136,6 +155,7 @@ export const SnapToolbar = memo(function SnapToolbar() {
           onClick={toggleGrid}
           onContextMenu={(e) => {
             e.preventDefault();
+            if (gridPopoverOpen) settleGridSpacing();
             setGridPopoverOpen((v) => !v);
           }}
           title={
@@ -150,7 +170,10 @@ export const SnapToolbar = memo(function SnapToolbar() {
         <button
           type="button"
           className="absolute -right-0.5 -bottom-0.5 rounded-sm p-0.5 text-white/50 hover:text-white/90 bg-black/50"
-          onClick={() => setGridPopoverOpen((v) => !v)}
+          onClick={() => {
+            if (gridPopoverOpen) settleGridSpacing();
+            setGridPopoverOpen((v) => !v);
+          }}
           title="Grid options"
           aria-label="Grid options"
           aria-expanded={gridPopoverOpen}
@@ -173,9 +196,21 @@ export const SnapToolbar = memo(function SnapToolbar() {
                 max={500}
                 step={10}
                 value={prefs.gridSpacing}
+                onFocus={() => {
+                  gridSpacingAtFocus.current = prefs.gridSpacing;
+                }}
+                onBlur={settleGridSpacing}
+                onKeyDown={(e) => {
+                  if (e.key === "Enter") e.currentTarget.blur();
+                }}
                 onChange={(e) => {
                   const val = Number.parseInt(e.target.value, 10);
-                  if (Number.isFinite(val) && val >= 10 && val <= 500) {
+                  if (
+                    Number.isFinite(val) &&
+                    val >= 10 &&
+                    val <= 500 &&
+                    val !== prefs.gridSpacing
+                  ) {
                     updatePrefs({ gridSpacing: val });
                   }
                 }}
@@ -186,7 +221,10 @@ export const SnapToolbar = memo(function SnapToolbar() {
               <input
                 type="checkbox"
                 checked={prefs.snapToGrid}
-                onChange={() => updatePrefs({ snapToGrid: !prefs.snapToGrid })}
+                onChange={() => {
+                  updatePrefs({ snapToGrid: !prefs.snapToGrid });
+                  trackPreviewFeatureUsed("snap_to_grid", "button");
+                }}
                 className="accent-studio-accent"
               />
               <span>Snap to grid</span>

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

@@ -1,6 +1,8 @@
 // @vitest-environment happy-dom
 
 import { afterEach, describe, expect, it, vi } from "vitest";
+import { trackStudioEvent } from "../../utils/studioTelemetry";
+vi.mock("../../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
 import { DomEditSaveQueueOpenError } from "../../utils/domEditSaveQueue";
 import type { DomEditSelection } from "./domEditing";
 import type { GestureState, UseDomEditOverlayGesturesOptions } from "./domEditOverlayGestures";
@@ -178,7 +180,7 @@ function buildHarness(
   };
 
   const handlers = createDomEditOverlayGestureHandlers(opts);
-  return { handlers, commits, selection };
+  return { handlers, commits, selection, opts };
 }
 
 type OverlayRectLike = {
@@ -287,3 +289,48 @@ describe("anchored corner resize — the release commit feeds the center-pin off
     expect(consoleError).toHaveBeenCalledWith("resize commit failed", failure);
   });
 });
+
+describe("resize usage at pointer release", () => {
+  it("counts one completed resize despite multiple pointer moves", async () => {
+    vi.mocked(trackStudioEvent).mockClear();
+    const h = buildHarness(async () => ({ ok: true, changed: true }));
+    await finishResize(h.handlers);
+    expect(trackStudioEvent).toHaveBeenCalledExactlyOnceWith("feature_used", {
+      feature: "resize",
+      surface: "preview",
+      method: "drag",
+    });
+  });
+  it.each([undefined, { ok: true as const, changed: false }])(
+    "does not count an unchanged or unconfirmed resize",
+    async (result) => {
+      vi.mocked(trackStudioEvent).mockClear();
+      const h = buildHarness(async () => result);
+      await finishResize(h.handlers);
+      expect(trackStudioEvent).not.toHaveBeenCalled();
+    },
+  );
+});
+
+describe("move and rotation usage", () => {
+  it.each(["drag", "rotate"] as const)("counts %s once after pointer release", async (kind) => {
+    vi.mocked(trackStudioEvent).mockClear();
+    const h = buildHarness();
+    h.selection.capabilities.canApplyManualRotation = true;
+    const saved = vi.fn(async () => ({ ok: true as const, changed: true }));
+    h.opts.onPathOffsetCommitRef.current = saved;
+    h.opts.onRotationCommitRef.current = saved;
+    h.handlers.startGesture(kind, evt(200, 50));
+    h.handlers.onPointerMove(evt(150, 120));
+    h.handlers.onPointerMove(evt(100, 150));
+    expect(trackStudioEvent).not.toHaveBeenCalled();
+    h.handlers.onPointerUp(evt(100, 150));
+    await Promise.resolve();
+    expect(saved).toHaveBeenCalledTimes(1);
+    expect(trackStudioEvent).toHaveBeenCalledExactlyOnceWith("feature_used", {
+      feature: kind === "drag" ? "move" : "rotate",
+      surface: "preview",
+      method: "drag",
+    });
+  });
+});

package/src/components/editor/audioFxTelemetry.ts

@@ -10,9 +10,8 @@
  * filenames, not composition paths, not chain JSON. Every property below is
  * either a fixed identifier from our own catalogue (a preset id, an effect
  * type, a parameter key), a number, or a boolean. `studioTelemetry.ts` already
- * strips the query string off `url_hash` for exactly this reason — the ids in
- * it are the author's own. The rack sees the same class of data and must hold
- * the same line.
+ * sends only a route kind in `url_hash` for the same reason. The rack sees
+ * the same class of data and must hold the same line.
  *
  * The second rule is about volume: **commit, not preview.** Every control in
  * the rack has a preview path that fires continuously while a slider moves and

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

@@ -287,7 +287,7 @@ describe("handles follow what Studio would commit", () => {
       { x: 0, y: 0 },
       commitList,
       preview,
-      vi.fn(),
+      vi.fn(async () => undefined),
       undefined,
       preflightOnly,
     );
@@ -401,7 +401,7 @@ describe("handles follow what Studio would commit", () => {
       { x: 0, y: 0 },
       [stagger],
       preview,
-      vi.fn(),
+      vi.fn(async () => undefined),
       undefined,
       groupPreflight,
     );

package/src/components/editor/cropResize.ts

@@ -1,3 +1,4 @@
+import type { DomEditPersistOutcome } from "../../hooks/domEditCommitTypes";
 import type { PatchOperation } from "../../utils/sourcePatcher";
 import type { CommitMutation } from "../../hooks/gsapScriptCommitTypes";
 import type { DomEditSelection } from "./domEditingTypes";
@@ -94,7 +95,7 @@ type PatchCommit = (
   selection: DomEditSelection,
   patches: PatchOperation[],
   options: { label: string; coalesceKey: string; coalesceMs?: number },
-) => Promise<void>;
+) => Promise<DomEditPersistOutcome | undefined>;
 
 /** Stage the crop and save it under the resize's undo key, taking it back off the element if that fails. */
 export async function saveCropResize(
@@ -102,11 +103,11 @@ export async function saveCropResize(
   selection: DomEditSelection,
   commit: PatchCommit,
   coalesceKey: string,
-): Promise<void> {
+): Promise<DomEditPersistOutcome | undefined> {
   const crop = stage();
   if (!crop) return;
   try {
-    await commit(selection, [crop.patch], {
+    return await commit(selection, [crop.patch], {
       label: "Resize layer",
       coalesceKey,
       coalesceMs: Number.POSITIVE_INFINITY,

package/src/components/editor/domEditingDom.ts

@@ -30,6 +30,10 @@ export function isTextBearingTag(tagName: string): boolean {
   return ["div", "span", "p", "strong", "h1", "h2", "h3", "h4", "h5", "h6"].includes(tagName);
 }
 
+export function isEditableTextLeaf(el: HTMLElement): boolean {
+  return isTextBearingTag(el.tagName.toLowerCase()) && el.children.length === 0;
+}
+
 /** Does this node render AT ALL, ignoring what it inherits? Sole owner of the
  *  rule; the walk below only decides which nodes to ask it about. */
 function elementRendersItself(win: Window, el: HTMLElement): boolean {

package/src/components/editor/domEditingLayers.ts

@@ -23,8 +23,8 @@ import {
   getInlineStyles,
   getSelectorIndex,
   getSourceFileForElement,
+  isEditableTextLeaf,
   isHtmlElement,
-  isTextBearingTag,
 } from "./domEditingDom";
 import {
   findElementForSelection,
@@ -35,10 +35,6 @@ import { isCompositionRootLayer } from "./domEditingRootLayer";
 import { withSelectorIndexPass } from "../../utils/sourceScopedSelectorIndex";
 import { type DomEditLayerWalkCache, readDomEditLayerWalkEntry } from "./domEditLayerWalkCache";
 
-export function isEditableTextLeaf(el: HTMLElement): boolean {
-  return isTextBearingTag(el.tagName.toLowerCase()) && el.children.length === 0;
-}
-
 function sameTagChildIndex(el: HTMLElement): number {
   let index = 0;
   let sibling = el.previousElementSibling;

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

@@ -0,0 +1,252 @@
+// @vitest-environment happy-dom
+import { act } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { DomEditSelection } from "./domEditingTypes";
+import type { DomEditGroupPathOffsetCommit } from "./domEditOverlayGestures";
+import { STUDIO_OFFSET_X_PROP, STUDIO_OFFSET_Y_PROP } from "./manualEdits";
+import { isStudioManualEditGestureLiveIn } from "./manualEditsDom";
+import { readTranslatePx } from "./plainTranslate";
+import { moveDomGroupBy } from "./domGroupMoveBy";
+import { GsapEditBlockedError } from "../../hooks/gsapEditOutcome";
+
+Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
+
+const mocks = vi.hoisted(() => ({ drag: vi.fn() }));
+vi.mock("../../hooks/gsapRuntimeBridge", () => ({
+  tryGsapDragIntercept: mocks.drag,
+  tryGsapRotationIntercept: vi.fn(),
+}));
+vi.mock("../../hooks/useAnimatedPropertyCommit", () => ({
+  useAnimatedPropertyCommit: () => ({
+    commitAnimatedProperty: vi.fn(),
+    commitAnimatedProperties: vi.fn(),
+  }),
+}));
+vi.mock("../../hooks/useSafeGsapCommitMutation", () => ({
+  useGsapSaveFailureTelemetry: () => vi.fn(),
+  useSafeGsapCommitMutation: (commit: unknown) => commit,
+}));
+vi.mock("../../utils/studioSaveDiagnostics", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../../utils/studioSaveDiagnostics")>()),
+  trackStudioEditBlocked: vi.fn(),
+  trackStudioSaveFailure: vi.fn(),
+}));
+
+import { mountGsapAwareEditing } from "../../hooks/useGsapAwareEditing.testHelpers";
+
+afterEach(() => {
+  vi.clearAllMocks();
+  document.body.innerHTML = "";
+});
+
+/** A preview iframe drawn at half size: 200x100 composition px in a 100x50 box. */
+function preview(): Document {
+  const iframe = document.createElement("iframe");
+  document.body.append(iframe);
+  const win = iframe.contentWindow!;
+  Object.defineProperty(win, "frameElement", { configurable: true, value: iframe });
+  Object.defineProperty(win, "innerWidth", { configurable: true, value: 200 });
+  Object.defineProperty(win, "innerHeight", { configurable: true, value: 100 });
+  iframe.getBoundingClientRect = () => new DOMRect(50, 40, 100, 50);
+  return iframe.contentDocument!;
+}
+
+const turned = (deg: number, scale: number) => {
+  const r = (deg * Math.PI) / 180;
+  return [scale * Math.cos(r), scale * Math.sin(r), -scale * Math.sin(r), scale * Math.cos(r)];
+};
+
+/** An element whose box centre is `at` plus its own move carried through its ancestors' linear map. */
+function layer(doc: Document, id: string, parent = [1, 0, 0, 1], gsap?: object) {
+  const element = Object.assign(doc.createElement("div"), gsap ? { _gsap: gsap } : {});
+  doc.body.append(element);
+  const own = () => {
+    if (!gsap) return readTranslatePx(element);
+    const read = (prop: string) => Number.parseFloat(element.style.getPropertyValue(prop)) || 0;
+    return { x: read(STUDIO_OFFSET_X_PROP), y: read(STUDIO_OFFSET_Y_PROP) };
+  };
+  element.getBoundingClientRect = () => {
+    const { x, y } = own();
+    const [a, b, c, d] = parent as [number, number, number, number];
+    return new DOMRect(60 + a * x + c * y - 20, 40 + b * x + d * y - 10, 40, 20);
+  };
+  const selection = {
+    element,
+    id,
+    selector: `#${id}`,
+    label: id,
+    capabilities: { canApplyManualOffset: true },
+  } as unknown as DomEditSelection;
+  const centre = () => {
+    const r = element.getBoundingClientRect();
+    return { x: r.left + r.width / 2, y: r.top + r.height / 2 };
+  };
+  return { element, selection, centre };
+}
+
+function mountGroupCommit() {
+  const showToast = vi.fn();
+  const save = vi.fn().mockResolvedValue(undefined);
+  const stageElementPositionOffset = vi.fn(() => ({ save, rollback: vi.fn() }));
+  const { editing, root } = mountGsapAwareEditing({ showToast, stageElementPositionOffset });
+  const commit = (u: DomEditGroupPathOffsetCommit[], o?: { refusalToast?: boolean }) =>
+    editing().handleGsapAwareGroupPathOffsetCommit(u, o);
+  const moveBy = (moves: Parameters<typeof moveDomGroupBy>[0]) =>
+    act(() => moveDomGroupBy(moves, (u) => commit(u, { refusalToast: false })));
+  return {
+    commit: (u: DomEditGroupPathOffsetCommit[]) => commit(u),
+    moveBy,
+    showToast,
+    stageElementPositionOffset,
+    root,
+  };
+}
+
+const moved = (from: { x: number; y: number }, to: { x: number; y: number }) => ({
+  x: to.x - from.x,
+  y: to.y - from.y,
+});
+
+describe("handleDomGroupMoveBy", () => {
+  it("moves each box by its delta in composition px, saved under one undo entry", async () => {
+    const doc = preview();
+    const offset = layer(doc, "offset");
+    offset.element.style.setProperty("translate", "30px 0px");
+    const halved = layer(doc, "halved", [0.5, 0, 0, 0.5]);
+    const before = [offset.centre(), halved.centre()];
+    const { moveBy, stageElementPositionOffset, showToast, root } = mountGroupCommit();
+
+    await moveBy([
+      { selection: offset.selection, delta: { x: 10, y: 0 } },
+      { selection: halved.selection, delta: { x: 0, y: -5 } },
+    ]);
+
+    expect(moved(before[0]!, offset.centre())).toEqual({ x: 10, y: 0 });
+    expect(moved(before[1]!, halved.centre())).toEqual({ x: 0, y: -5 });
+    const calls = stageElementPositionOffset.mock.calls as unknown as unknown[][];
+    expect(calls.map((call) => call[1])).toEqual([
+      { x: 40, y: 0 },
+      { x: 0, y: -10 },
+    ]);
+    expect(calls[0]![3]).toMatch(/^group-drag:\d+$/);
+    expect(calls[1]![3]).toBe(calls[0]![3]);
+    expect(showToast).not.toHaveBeenCalled();
+    expect(isStudioManualEditGestureLiveIn(doc)).toBe(false);
+    act(() => root.unmount());
+  });
+
+  it("lands exactly under a half-scale parent with a rotated ancestor", async () => {
+    const doc = preview();
+    const tilted = layer(doc, "tilted", turned(30, 0.5));
+    const before = tilted.centre();
+    const { moveBy, root } = mountGroupCommit();
+
+    await moveBy([{ selection: tilted.selection, delta: { x: 10, y: 0 } }]);
+
+    const delta = moved(before, tilted.centre());
+    // Exact to the 0.001 px a translate is written with.
+    expect(delta.x).toBeCloseTo(10, 3);
+    expect(delta.y).toBeCloseTo(0, 3);
+    act(() => root.unmount());
+  });
+
+  it("moves a member GSAP positions through the GSAP write, planned and written at one delta", async () => {
+    mocks.drag.mockResolvedValue({ status: "persisted" });
+    const doc = preview();
+    const animated = layer(doc, "animated", [1, 0, 0, 1], { renderTransform: () => {} });
+    const before = animated.centre();
+    const { moveBy, stageElementPositionOffset, root } = mountGroupCommit();
+
+    await moveBy([{ selection: animated.selection, delta: { x: 10, y: 0 } }]);
+
+    const write = mocks.drag.mock.calls.find((call) => !call[6]?.preflightOnly);
+    expect(write?.[0]).toBe(animated.selection);
+    expect(write?.[1]).toEqual({ x: 10, y: 0 });
+    const plan = mocks.drag.mock.calls.find((call) => call[6]?.preflightOnly);
+    expect(plan?.[1]).toEqual(write?.[1]);
+    expect(moved(before, animated.centre())).toEqual({ x: 10, y: 0 });
+    expect(stageElementPositionOffset).not.toHaveBeenCalled();
+    act(() => root.unmount());
+  });
+
+  it("skips a zero delta, and writes nothing when every delta is zero", async () => {
+    const doc = preview();
+    const still = layer(doc, "still");
+    const { moveBy, stageElementPositionOffset, root } = mountGroupCommit();
+
+    await moveBy([{ selection: still.selection, delta: { x: 0, y: 0 } }]);
+
+    expect(stageElementPositionOffset).not.toHaveBeenCalled();
+    act(() => root.unmount());
+  });
+
+  it.each([
+    [
+      "a member that can't take a manual move",
+      (doc: Document) => {
+        const locked = layer(doc, "locked");
+        Object.assign(locked.selection.capabilities, {
+          canApplyManualOffset: false,
+          reasonIfDisabled: "Locked by a helper loop.",
+        });
+        return locked;
+      },
+      /helper loop/,
+    ],
+    [
+      "a member an animation took over",
+      (doc: Document) => layer(doc, "folded", [1, 0, 0, 1], { x: "94px" }),
+      /animation took over/,
+    ],
+    [
+      "a member the GSAP write refuses",
+      (doc: Document) => {
+        mocks.drag.mockResolvedValue({ status: "blocked", reason: "no-selector" });
+        return layer(doc, "blocked", [1, 0, 0, 1], { renderTransform: () => {} });
+      },
+      new GsapEditBlockedError("no-selector").message,
+    ],
+  ])("refuses %s before any write, without a Studio toast", async (_, make, reason) => {
+    const doc = preview();
+    const fine = layer(doc, "fine");
+    const refused = make(doc);
+    const before = [fine.centre(), refused.centre()];
+    const { moveBy, stageElementPositionOffset, showToast, root } = mountGroupCommit();
+
+    await expect(
+      moveBy([
+        { selection: fine.selection, delta: { x: 10, y: 0 } },
+        { selection: refused.selection, delta: { x: 10, y: 0 } },
+      ]),
+    ).rejects.toThrow(reason);
+
+    expect(stageElementPositionOffset).not.toHaveBeenCalled();
+    expect(mocks.drag.mock.calls.some((call) => !call[6]?.preflightOnly)).toBe(false);
+    expect(showToast).not.toHaveBeenCalled();
+    expect([fine.centre(), refused.centre()]).toEqual(before);
+    expect(isStudioManualEditGestureLiveIn(doc)).toBe(false);
+    act(() => root.unmount());
+  });
+
+  it.each([
+    ["an animation took over", () => layer(preview(), "folded", [1, 0, 0, 1], { x: "94px" }), true],
+    [
+      "the GSAP write refuses",
+      () => {
+        mocks.drag.mockResolvedValue({ status: "blocked", reason: "no-selector" });
+        return layer(preview(), "blocked", [1, 0, 0, 1], { renderTransform: () => {} });
+      },
+      false,
+    ],
+  ])("still toasts on a canvas group drag when %s", async (_, make, plainTranslate) => {
+    const { selection } = make();
+    const { commit, showToast, root } = mountGroupCommit();
+
+    await expect(
+      act(() => commit([{ selection, next: { x: 1, y: 2 }, plainTranslate }])),
+    ).rejects.toThrow();
+
+    expect(showToast).toHaveBeenCalledWith(expect.any(String), "error");
+    act(() => root.unmount());
+  });
+});

package/src/components/editor/domGroupMoveBy.ts

@@ -0,0 +1,95 @@
+import type { DomEditSelection } from "./domEditing";
+import type { DomEditGroupPathOffsetCommit } from "./domEditOverlayGestures";
+import { canCanvasNudgeTargets } from "./domEditNudge";
+import { isStudioManualEditGestureCurrent, restoreStudioPathOffset } from "./manualEdits";
+import { countStudioManualEditSave } from "./manualEditsDom";
+import {
+  applyManualOffsetDragCommit,
+  createManualOffsetDragMember,
+  endManualOffsetDragMembers,
+  restoreManualOffsetDragMembers,
+  toTopScreenPoint,
+  type ManualOffsetDragMember,
+} from "./manualOffsetDrag";
+
+export interface DomGroupMove {
+  selection: DomEditSelection;
+  /** Composition px: the element's box moves by exactly this in the film. */
+  delta: { x: number; y: number };
+}
+
+/** Composition px to the top page's px; the preview frames only scale and shift. */
+function toScreen(doc: Document, delta: { x: number; y: number }) {
+  const origin = toTopScreenPoint(doc, { x: 0, y: 0 });
+  const moved = toTopScreenPoint(doc, delta);
+  if (!origin || !moved) throw new Error("The preview has no measurable size.");
+  return { x: moved.x - origin.x, y: moved.y - origin.y };
+}
+
+function memberFor(
+  selection: DomEditSelection,
+  scale: { x: number; y: number },
+): ManualOffsetDragMember {
+  const { element } = selection;
+  const box = element.getBoundingClientRect();
+  const result = createManualOffsetDragMember({
+    key: selection.id ?? selection.selector ?? selection.label,
+    selection,
+    element,
+    rect: {
+      left: box.left,
+      top: box.top,
+      width: box.width,
+      height: box.height,
+      editScaleX: scale.x,
+      editScaleY: scale.y,
+    },
+    gesture: "drag",
+  });
+  if (!result.ok) throw new Error(result.reason);
+  return result.member;
+}
+
+/**
+ * Moves each element by its delta as one group drag would drop it: one save, one undo entry.
+ * Any member that can't move refuses the whole call before anything is drawn or written.
+ */
+export async function moveDomGroupBy(
+  moves: DomGroupMove[],
+  commitGroup: (updates: DomEditGroupPathOffsetCommit[]) => Promise<unknown>,
+): Promise<void> {
+  const moving = moves.filter(({ delta }) => delta.x !== 0 || delta.y !== 0);
+  if (moving.length === 0) return;
+  const selections = moving.map(({ selection }) => selection);
+  if (!canCanvasNudgeTargets(selections)) {
+    const blocked = selections.find((s) => !s.capabilities.canApplyManualOffset);
+    throw new Error(blocked?.capabilities.reasonIfDisabled ?? `${blocked?.label} can't be moved.`);
+  }
+  const screens = moving.map(({ selection, delta }) =>
+    toScreen(selection.element.ownerDocument, delta),
+  );
+  const members: ManualOffsetDragMember[] = [];
+  try {
+    for (const selection of selections)
+      members.push(memberFor(selection, toScreen(selection.element.ownerDocument, { x: 1, y: 1 })));
+  } catch (error) {
+    restoreManualOffsetDragMembers(members);
+    throw error;
+  }
+  const updates = members.map((member, index) => ({
+    selection: member.selection,
+    next: applyManualOffsetDragCommit(member, screens[index]!.x, screens[index]!.y),
+    plainTranslate: member.plainTranslate,
+  }));
+  try {
+    await countStudioManualEditSave(members[0]!.element, () => commitGroup(updates));
+  } catch (error) {
+    for (const member of members) {
+      if (isStudioManualEditGestureCurrent(member.element, member.gestureToken))
+        restoreStudioPathOffset(member.element, member.initialPathOffset);
+    }
+    throw error;
+  } finally {
+    endManualOffsetDragMembers(members);
+  }
+}

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

@@ -5,7 +5,7 @@ import type { GestureState } from "./domEditOverlayGestures";
 import { createDomEditOverlayGestureHandlers } from "./useDomEditOverlayGestures";
 import {
   hasStudioPendingEdits,
-  revertNewestStudioPendingEdit,
+  paintBackNewestStudioPendingEdit,
 } from "../../utils/studioPendingEdits";
 
 afterEach(() => {
@@ -59,13 +59,13 @@ it("a drag whose save is still running can be painted back at once, and shown ag
   const moved = element.style.getPropertyValue("translate");
   expect(moved).not.toBe("40px 30px");
 
-  const showAgain = revertNewestStudioPendingEdit();
+  const shown = paintBackNewestStudioPendingEdit();
   expect(element.style.getPropertyValue("translate")).toBe("40px 30px");
-  expect(revertNewestStudioPendingEdit()).toBeNull();
-  showAgain!();
+  expect(paintBackNewestStudioPendingEdit()).toBeNull();
+  shown!.showAgain();
   expect(element.style.getPropertyValue("translate")).toBe(moved);
 
   saved();
   await vi.waitFor(() => expect(hasStudioPendingEdits()).toBe(false));
-  expect(revertNewestStudioPendingEdit()).toBeNull();
+  expect(paintBackNewestStudioPendingEdit()).toBeNull();
 });