@hyperframes/studio 0.8.115 → 0.8.117

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.115",
+  "version": "0.8.117",
   "description": "",
   "repository": {
     "type": "git",
@@ -60,12 +60,12 @@
     "dockview-react": "8.3.1",
     "gsap": "^3.13.0",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.8.115",
-    "@hyperframes/player": "0.8.115",
-    "@hyperframes/studio-server": "0.8.115",
-    "@hyperframes/sdk": "0.8.115",
-    "@hyperframes/shader-transitions": "0.8.115",
-    "@hyperframes/parsers": "0.8.115"
+    "@hyperframes/core": "0.8.117",
+    "@hyperframes/parsers": "0.8.117",
+    "@hyperframes/sdk": "0.8.117",
+    "@hyperframes/shader-transitions": "0.8.117",
+    "@hyperframes/studio-server": "0.8.117",
+    "@hyperframes/player": "0.8.117"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",
@@ -81,7 +81,7 @@
     "vite": "^6.4.2",
     "vitest": "^4.1.11",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.115"
+    "@hyperframes/producer": "0.8.117"
   },
   "peerDependencies": {
     "react": "19",

package/src/captions/hooks/useCaptionSync.ts

@@ -5,6 +5,7 @@ import { useMountEffect } from "../../hooks/useMountEffect";
 import { trackEvent } from "../../telemetry/client";
 import type { CaptionStyle } from "../types";
 import { studioWriteHeaders } from "../../utils/studioFileVersion";
+import { studioApiFetch } from "../../utils/studioApiFetch";
 
 interface CaptionOverrideEntry {
   wordId?: string;
@@ -93,11 +94,14 @@ export function useCaptionSync(projectId: string | null) {
     const seqAtSave = editSeqRef.current;
     const overrides = buildOverrides(state.model);
 
-    fetch(buildProjectApiPath(pid, `/files/${encodeURIComponent("caption-overrides.json")}`), {
-      method: "PUT",
-      headers: { "Content-Type": "text/plain", ...studioWriteHeaders() },
-      body: JSON.stringify(overrides, null, 2),
-    })
+    studioApiFetch(
+      buildProjectApiPath(pid, `/files/${encodeURIComponent("caption-overrides.json")}`),
+      {
+        method: "PUT",
+        headers: { "Content-Type": "text/plain", ...studioWriteHeaders() },
+        body: JSON.stringify(overrides, null, 2),
+      },
+    )
       .then((res) => {
         if (!res.ok) throw new Error(`HTTP ${res.status}`);
         // A newer edit may have re-armed the debounce while this PUT was in
@@ -171,7 +175,7 @@ export function useCaptionSync(projectId: string | null) {
 
     let data: { content?: string };
     try {
-      const res = await fetch(
+      const res = await studioApiFetch(
         buildProjectApiPath(pid, `/files/${encodeURIComponent("caption-overrides.json")}`),
       );
       if (!res.ok) return; // no overrides file yet — normal

package/src/components/ProjectUnreachableBanner.tsx

@@ -1,4 +1,5 @@
 import { useEffect, useState } from "react";
+import { studioApiFetch } from "../utils/studioApiFetch";
 
 interface ServedProject {
   id: string;
@@ -24,8 +25,7 @@ interface ProjectUnreachableBannerProps {
  *
  * The wording is deliberately narrower than "this project is gone". We can see
  * which project this server serves; we cannot see why it does not serve this
- * one, and nothing here is lost. See
- * `docs/hyperframes/plans/sdk/2026-09-20-stale-project-id-remaining-doors-plan.md` §C.
+ * one, and nothing here is lost.
  */
 export function ProjectUnreachableBanner({ projectId }: ProjectUnreachableBannerProps) {
   const [served, setServed] = useState<ServedProject[] | null>(null);
@@ -35,7 +35,7 @@ export function ProjectUnreachableBanner({ projectId }: ProjectUnreachableBanner
     // A list we could not read is not evidence of anything, so a failed fetch
     // leaves `served` empty and the banner falls back to the vague wording
     // rather than claiming this Studio serves nothing.
-    fetch("/api/projects")
+    studioApiFetch("/api/projects")
       .then((res) => (res.ok ? res.json() : { projects: [] }))
       .then((data: { projects?: ServedProject[] }) => {
         if (!cancelled) setServed(data.projects ?? []);

package/src/components/editor/DomEditOverlay.tsx

@@ -94,6 +94,7 @@ export interface DomEditOverlayProps {
     next: { width: number; height: number },
     offset?: { x: number; y: number },
     restore?: () => void,
+    route?: { plainTranslate: boolean },
   ) => Promise<unknown> | void;
   onRotationCommit: (selection: DomEditSelection, next: RotationCommit) => Promise<unknown> | void;
   onStyleCommit?: (property: string, value: string) => Promise<unknown> | void;

package/src/components/editor/domEditOverlayGestures.ts

@@ -275,6 +275,7 @@ export type UseDomEditOverlayGesturesOptions = {
       n: { width: number; height: number },
       offset?: { x: number; y: number },
       restore?: () => void,
+      route?: { plainTranslate: boolean },
     ) => Promise<unknown> | void
   >;
   onRotationCommitRef: RefObject<

package/src/components/editor/domEditOverlayStartGesture.ts

@@ -32,7 +32,7 @@ import {
   type UseDomEditOverlayGesturesOptions,
 } from "./domEditOverlayGestures";
 import { collectSnapContext, buildExcludeElements } from "./snapTargetCollection";
-import { gsapWritesRotation } from "../../hooks/gsapRuntimeKeyframes";
+import { editsPlainCss } from "../../hooks/gsapRuntimeKeyframes";
 import { logResize, resetResizeMoveLog } from "../../utils/resizeDebug";
 import { logDrag, readDragPositions, resetDragMoveLog } from "../../utils/dragDebug";
 
@@ -234,7 +234,7 @@ export function startGesture(
   try {
     // Rotation base: the angle the element shows. An element GSAP does not turn, or a plain-translate
     // move, never asks GSAP: reading a property makes it bake the CSS into its transform.
-    const plain = !!pathOffsetMember?.plainTranslate || !gsapWritesRotation(sel.element);
+    const plain = !!pathOffsetMember?.plainTranslate || editsPlainCss(sel.element, "rotate");
     const plainRotation = plain && kind === "rotate" ? readCssRotationTarget(sel.element) : null;
     const rotation = { angle: readRotationBase(sel.element, plain) };
     const overlayBounds = overlayEl?.getBoundingClientRect();

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();
 });

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

@@ -289,6 +289,39 @@ describe("a drag moves only with its own pointer pressed", () => {
   );
 });
 
+describe("an outside change during a drag, on a preview that can swap scenes in place", () => {
+  it("leaves the dragged node in place and shows the change after the drop, loaded fresh", async () => {
+    const { live, overlay, box } = mountEditor(false);
+    const swapScenes = vi.fn((html: string) => {
+      live.contentDocument!.body.innerHTML = html.replace(/^[\s\S]*<body>|<\/body>[\s\S]*$/g, "");
+    });
+    Object.assign(live.contentWindow!, { __hfSwapScenes: swapScenes });
+    vi.stubGlobal(
+      "fetch",
+      async () => new Response(served("").contentDocument!.documentElement.outerHTML),
+    );
+    const dragged = byId(live, "title");
+    pointer(box, "pointerdown", 150, 150);
+    pointer(overlay, "pointermove", 190, 170);
+
+    act(() => api().refreshPlayer());
+    await settle();
+    expect(swapScenes, "swapped under the pointer").not.toHaveBeenCalled();
+    expect(byId(live, "title")).toBe(dragged);
+    const beforeDrop = await paintShadow(api, served("?_t=1"));
+    expect(api().iframeRef.current, "promoted under the pointer").toBe(live);
+
+    pointer(overlay, "pointerup", 190, 170);
+    await settle();
+    expect(file.title).toBe("translate: 40px 20px");
+    const fresh = served("?_t=2");
+    expect(await paintShadow(api, fresh)).toBeGreaterThan(beforeDrop);
+    expect(api().iframeRef.current).toBe(fresh);
+    expect(byId(fresh, "title").style.getPropertyValue("translate")).toBe("40px 20px");
+    vi.unstubAllGlobals();
+  });
+});
+
 type Editor = ReturnType<typeof mountEditor>;
 
 describe("every way a drag ends without a drop clears its mark and promotes the held reload", () => {

package/src/components/editor/manualEditingAvailability.ts

@@ -78,4 +78,12 @@ export const STUDIO_FLAT_INSPECTOR_ENABLED = resolveStudioBooleanEnvFlag(
   true,
 );
 
+// A host whose mounted API authenticates with same-origin cookies sets this; studioApiFetch then sends them, and its
+// requests share the preview media's sockets again.
+export const STUDIO_API_SAME_ORIGIN_CREDENTIALS = resolveStudioBooleanEnvFlag(
+  env,
+  ["VITE_STUDIO_API_SAME_ORIGIN_CREDENTIALS"],
+  false,
+);
+
 import { resolveEnabledSdkFamilies } from "../../utils/sdkCutoverPolicy";

package/src/components/editor/manualOffsetDrag.ts

@@ -11,7 +11,7 @@ import {
   type StudioPathOffsetSnapshot,
 } from "./manualEdits";
 import { computeDraggedGsapPosition } from "../../hooks/draggedGsapPosition";
-import { gsapWritesBox, gsapWritesPosition } from "../../hooks/gsapRuntimeKeyframes";
+import { editsPlainCss } from "../../hooks/gsapRuntimeKeyframes";
 import { readTranslatePx, UNREADABLE_TRANSLATE, writeTranslatePx } from "./plainTranslate";
 import type { StudioEditRevert } from "../../utils/studioPendingEdits";
 
@@ -146,12 +146,12 @@ function getRectCenter(element: HTMLElement): Point | null {
     return null;
   }
 
-  let point = {
-    x: rect.left + rect.width / 2,
-    y: rect.top + rect.height / 2,
-  };
+  const point = { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 };
+  return toTopScreenPoint(element.ownerDocument, point);
+}
 
-  let win: Window | null = element.ownerDocument.defaultView;
+export function toTopScreenPoint(doc: Document, point: Point): Point | null {
+  let win: Window | null = doc.defaultView;
   while (win) {
     const frameElement = getFrameElement(win);
     if (!frameElement) break;
@@ -166,7 +166,6 @@ function getRectCenter(element: HTMLElement): Point | null {
     };
     win = frameElement.ownerDocument.defaultView;
   }
-
   return point;
 }
 
@@ -319,8 +318,8 @@ export function createManualOffsetDragMember(input: {
   rect: ManualOffsetDragRect;
   gesture?: "drag" | "nudge" | "resize"; // resize: the anchor that keeps its centre planted
 }): ManualOffsetDragMemberResult {
-  const gsapOwns = input.gesture === "resize" ? gsapWritesBox : gsapWritesPosition;
-  const plainTranslate = !!input.gesture && !gsapOwns(input.element);
+  const plainTranslate =
+    !!input.gesture && editsPlainCss(input.element, input.gesture === "resize" ? "resize" : "move");
   // The APPLIED offset, never a dormant var, so a stale one can't fling the element off-screen.
   const initialOffset = plainTranslate
     ? readTranslatePx(input.element)