@hyperframes/studio 0.8.99 → 0.8.100

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.99",
+  "version": "0.8.100",
   "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.99",
-    "@hyperframes/parsers": "0.8.99",
-    "@hyperframes/player": "0.8.99",
-    "@hyperframes/sdk": "0.8.99",
-    "@hyperframes/studio-server": "0.8.99",
-    "@hyperframes/shader-transitions": "0.8.99"
+    "@hyperframes/core": "0.8.100",
+    "@hyperframes/sdk": "0.8.100",
+    "@hyperframes/parsers": "0.8.100",
+    "@hyperframes/player": "0.8.100",
+    "@hyperframes/shader-transitions": "0.8.100",
+    "@hyperframes/studio-server": "0.8.100"
   },
   "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.99"
+    "@hyperframes/producer": "0.8.100"
   },
   "peerDependencies": {
     "react": "19",

package/src/components/editor/PropertyPanel.tsx

@@ -3,7 +3,8 @@ import { memo, useMemo, useRef, useState } from "react";
 import { Move } from "../../icons/SystemIcons";
 import { InspectorHeaderActions } from "./InspectorHeaderActions";
 import { useStudioShellContext } from "../../contexts/StudioContext";
-import { readStudioBoxSize, readStudioPathOffset, readStudioRotation } from "./manualEdits";
+import { readStudioBoxSize, readStudioRotation } from "./manualEdits";
+import { readMoveOffset } from "./plainTranslate";
 import {
   buildElementInfoText,
   EMPTY_STYLES,
@@ -199,7 +200,7 @@ export const PropertyPanel = memo(function PropertyPanel(props: PropertyPanelPro
   // selection) so the Timing section shows for pure-GSAP elements with no data-start.
   const sections = resolveEditingSections(domEditSelectionToFacts(element, gsapAnimations.length));
   const showEditableSections = element.capabilities.canEditStyles && sections.style;
-  const manualOffset = readStudioPathOffset(element.element);
+  const manualOffset = readMoveOffset(element.element);
   const manualSize = readStudioBoxSize(element.element);
   const resolvedWidth =
     manualSize.width > 0
@@ -209,7 +210,6 @@ export const PropertyPanel = memo(function PropertyPanel(props: PropertyPanelPro
     manualSize.height > 0
       ? manualSize.height
       : (parsePxMetricValue(styles.height ?? "") ?? element.boundingBox.height);
-
   const manualRotation = readStudioRotation(element.element);
 
   const elStart = Number.parseFloat(element?.dataAttributes?.start ?? "0") || 0;

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

@@ -0,0 +1,83 @@
+// @vitest-environment happy-dom
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { DomEditSelection } from "./domEditing";
+import type { GestureState } from "./domEditOverlayGestures";
+import { createDomEditOverlayGestureHandlers } from "./useDomEditOverlayGestures";
+
+afterEach(() => {
+  delete (window as { gsap?: unknown }).gsap;
+  delete (window as { __timelines?: unknown }).__timelines;
+  document.body.innerHTML = "";
+});
+
+const PRESS = {
+  clientX: 10,
+  clientY: 10,
+  pointerId: 1,
+  button: 0,
+  preventDefault() {},
+  stopPropagation() {},
+  currentTarget: { setPointerCapture() {} },
+};
+
+/** Presses a drag on the element and returns the gesture it started. */
+function pressDrag(element: HTMLElement): GestureState | null {
+  const opts = pressOptions(element);
+  expect(
+    createDomEditOverlayGestureHandlers(opts as never).startGesture("drag", PRESS as never),
+  ).toBe(true);
+  return opts.gestureRef.current;
+}
+
+function pressOptions(element: HTMLElement) {
+  const ref = <T>(current: T) => ({ current });
+  const selection = { element, capabilities: { canApplyManualOffset: true } };
+  return {
+    selectionRef: ref(selection as unknown as DomEditSelection),
+    overlayRectRef: ref({ left: 0, top: 0, width: 240, height: 160, editScaleX: 1, editScaleY: 1 }),
+    boxRef: ref(null),
+    overlayRef: ref(null),
+    iframeRef: ref(null),
+    gestureRef: ref<GestureState | null>(null),
+    rafPausedRef: ref(false),
+    onManualDragStartRef: ref(vi.fn()),
+    onBlockedMoveRef: ref(vi.fn()),
+  };
+}
+
+describe("a drag press on a page that loads GSAP", () => {
+  it.each([
+    ["GSAP animates nothing", false],
+    ["GSAP animates only its parent", true],
+  ])(
+    "%s: the press never asks GSAP about the element, so its translate stays CSS",
+    (_, parentTween) => {
+      const getProperty = vi.fn(() => 0);
+      const set = vi.fn();
+      const parent = document.createElement("div");
+      const element = document.createElement("div");
+      element.style.setProperty("translate", "40px 30px");
+      parent.append(element);
+      document.body.append(parent);
+      const tween = { targets: () => [parent], vars: { x: 100 }, duration: () => 2 };
+      const timelines = { main: { getChildren: () => (parentTween ? [tween] : []) } };
+      Object.assign(window, { gsap: { getProperty, set }, __timelines: timelines });
+      expect(pressDrag(element)?.pathOffsetMember?.plainTranslate).toBe(true);
+      expect(getProperty).not.toHaveBeenCalled();
+      expect(set).not.toHaveBeenCalled();
+      expect(element.style.getPropertyValue("translate")).toBe("40px 30px");
+    },
+  );
+});
+
+describe("a drag press on a centred element without GSAP", () => {
+  it("starts from its -50% translate in px and leaves its style as it was", () => {
+    const element = document.createElement("div");
+    element.style.cssText =
+      "position: absolute; left: 50%; top: 50%; width: 240px; height: 160px; translate: -50% -50%";
+    document.body.append(element);
+    const style = element.getAttribute("style");
+    expect(pressDrag(element)?.pathOffsetMember?.initialOffset).toEqual({ x: -120, y: -80 });
+    expect(element.getAttribute("style")).toBe(style);
+  });
+});

package/src/components/editor/domEditOverlayStartGesture.ts

@@ -70,6 +70,7 @@ export function startGroupDrag(
       selection: item.selection,
       element: item.element,
       rect: item.rect,
+      gesture: "drag",
     });
     if (!result.ok) {
       restoreManualOffsetDragMembers(members);
@@ -151,10 +152,6 @@ export function startGesture(
     return false;
 
   const size = readStudioBoxSize(sel.element);
-  // Single-source rotation base = the live GSAP transform rotation plus any legacy
-  // `--hf-studio-rotation` CSS var (old projects), so a rotate gesture starts from the
-  // element's actual visual angle and commits an absolute angle to the timeline.
-  const rotation = { angle: readGsapRotation(sel.element) + readStudioRotation(sel.element).angle };
   // The draft writes CSS width/height, so the resize base must be the CSS
   // layout size. offsetWidth/Height are transform-free; the overlay-rect
   // fallback (rect / editScale) includes the element's own GSAP scale and
@@ -198,6 +195,7 @@ export function startGesture(
       selection: sel,
       element: sel.element,
       rect,
+      gesture: "drag",
     });
     if (!result.ok) {
       opts.onBlockedMoveRef.current(result.selection);
@@ -232,6 +230,10 @@ export function startGesture(
     }
   }
 
+  // Rotation base = GSAP's rotation plus the legacy `--hf-studio-rotation` var. A plain-translate
+  // move never asks GSAP: reading a property makes it bake the CSS translate into its transform.
+  const gsapRotation = pathOffsetMember?.plainTranslate ? 0 : readGsapRotation(sel.element);
+  const rotation = { angle: gsapRotation + readStudioRotation(sel.element).angle };
   const overlayBounds = overlayEl?.getBoundingClientRect();
   const centerX = (overlayBounds?.left ?? 0) + rect.left + rect.width / 2;
   const centerY = (overlayBounds?.top ?? 0) + rect.top + rect.height / 2;

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

@@ -5,6 +5,7 @@ import {
   resumeGsapTimelines,
   applyManualOffsetDragDraft,
   applyManualOffsetDragMatrix,
+  applyManualOffsetNudgeDraft,
   createManualOffsetDragMember,
   endManualOffsetDragMembers,
   invertManualOffsetDragMatrix,
@@ -566,3 +567,72 @@ describe("resumeGsapTimelines", () => {
     expect(() => resumeGsapTimelines(element)).not.toThrow();
   });
 });
+
+describe("a move of an element GSAP does not position", () => {
+  function plainBox(options: { gsapLoaded?: boolean } = {}) {
+    const window = new Window();
+    const element = window.document.createElement("div");
+    window.document.body.append(element);
+    element.style.setProperty("translate", "40px 30px");
+    // A rect that never moves: the probe falls back to the 1:1 preview-scale mapping.
+    element.getBoundingClientRect = () => new window.DOMRect(10, 20, 100, 50);
+    const gsapCalls: string[] = [];
+    if (options.gsapLoaded) {
+      Object.assign(window, {
+        gsap: { set: () => gsapCalls.push("set"), getProperty: () => gsapCalls.push("read") },
+      });
+    }
+    const member = (gesture: "drag" | "nudge" = "drag") => {
+      const result = createManualOffsetDragMember({
+        key: "box",
+        selection: { element } as never,
+        element,
+        rect: { left: 10, top: 20, width: 100, height: 50, editScaleX: 1, editScaleY: 1 },
+        gesture,
+      });
+      if (!result.ok) throw new Error(result.reason);
+      return result.member;
+    };
+    return { window, element, gsapCalls, member };
+  }
+
+  it("drafts and drops the element's own translate in plain px, never touching GSAP", () => {
+    const { element, gsapCalls, member } = plainBox({ gsapLoaded: true });
+    const m = member();
+    expect(m.plainTranslate).toBe(true);
+    applyManualOffsetDragDraft(m, 90.25, 60);
+    expect(element.style.getPropertyValue("translate")).toBe("130.25px 90px");
+    expect(applyManualOffsetDragCommit(m, 90.25, 60)).toEqual({ x: 130.25, y: 90 });
+    endManualOffsetDragMembers([m]);
+    expect(element.style.getPropertyValue("translate")).toBe("130.25px 90px");
+    expect(gsapCalls).toEqual([]);
+    expect(element.hasAttribute("data-hf-drag-gsap-base-x")).toBe(false);
+  });
+
+  it("starts a second move where the first dropped, while the first save is still in flight", () => {
+    const { member } = plainBox();
+    const first = member();
+    applyManualOffsetDragCommit(first, 90, 60);
+    const second = member();
+    expect(second.initialOffset).toEqual({ x: 130, y: 90 });
+    expect(applyManualOffsetDragCommit(second, 40, 0)).toEqual({ x: 170, y: 90 });
+  });
+
+  it("nudges from the element's translate", () => {
+    const { member } = plainBox();
+    expect(applyManualOffsetNudgeDraft(member("nudge"), { x: 5, y: -1 })).toEqual({ x: 45, y: 29 });
+  });
+
+  it("keeps the GSAP writer once GSAP renders the element's transform", () => {
+    const { element, member } = plainBox({ gsapLoaded: true });
+    Object.assign(element, { _gsap: { renderTransform: () => {} } });
+    expect(member().plainTranslate).toBe(false);
+  });
+
+  it("keeps the GSAP writer for an element a timeline hold positions", () => {
+    const { window, element, member } = plainBox();
+    const hold = { targets: () => [element], vars: { x: 40 }, duration: () => 0 };
+    Object.assign(window, { __timelines: { main: { getChildren: () => [hold] } } });
+    expect(member().plainTranslate).toBe(false);
+  });
+});

package/src/components/editor/manualOffsetDrag.ts

@@ -11,6 +11,8 @@ import {
   type StudioPathOffsetSnapshot,
 } from "./manualEdits";
 import { computeDraggedGsapPosition } from "../../hooks/draggedGsapPosition";
+import { gsapWritesPosition } from "../../hooks/gsapRuntimeKeyframes";
+import { readTranslatePx, writeTranslatePx } from "./plainTranslate";
 
 interface OffsetDragGsap {
   set: (el: Element, vars: Record<string, number | string>) => void;
@@ -97,6 +99,8 @@ export interface ManualOffsetDragMember {
   selection: DomEditSelection;
   element: HTMLElement;
   initialOffset: { x: number; y: number };
+  /** The move writes the element's own inline `translate`; offsets are then absolute translate px. */
+  plainTranslate: boolean;
   /**
    * The element's GSAP x/y at gesture start, captured in JS so a mid-drag
    * re-render (which reverts inline style + wipes the `data-hf-drag-gsap-base-*`
@@ -242,22 +246,23 @@ function readTransformWDivisor(element: HTMLElement): number {
 export function measureManualOffsetDragScreenToOffsetMatrix(
   element: HTMLElement,
   initialOffset: { x: number; y: number },
-  options: { probeSize?: number; scaleX?: number; scaleY?: number } = {},
+  options: { probeSize?: number; scaleX?: number; scaleY?: number; plainTranslate?: boolean } = {},
 ): { ok: true; matrix: ManualOffsetDragMatrix } | { ok: false; reason: string } {
   const probeSize = options.probeSize ?? DEFAULT_OFFSET_PROBE_PX;
   if (!Number.isFinite(probeSize) || probeSize <= 0) {
     return { ok: false, reason: "Invalid movement probe size." };
   }
 
+  const draw = options.plainTranslate ? writeTranslatePx : applyStudioPathOffsetDraft;
   const snapshot = captureStudioPathOffset(element);
   try {
-    applyStudioPathOffsetDraft(element, initialOffset);
+    draw(element, initialOffset);
     const origin = getRectCenter(element);
     if (!origin) {
       return { ok: false, reason: "Element has no measurable box." };
     }
 
-    applyStudioPathOffsetDraft(element, {
+    draw(element, {
       x: initialOffset.x + probeSize,
       y: initialOffset.y,
     });
@@ -266,7 +271,7 @@ export function measureManualOffsetDragScreenToOffsetMatrix(
       return { ok: false, reason: "Element X movement could not be measured." };
     }
 
-    applyStudioPathOffsetDraft(element, {
+    draw(element, {
       x: initialOffset.x,
       y: initialOffset.y + probeSize,
     });
@@ -332,24 +337,25 @@ export function createManualOffsetDragMember(input: {
   selection: DomEditSelection;
   element: HTMLElement;
   rect: ManualOffsetDragRect;
+  gesture?: "drag" | "nudge"; // a resize's anchor member keeps the legacy offset channel
 }): ManualOffsetDragMemberResult {
-  // Base the drag on the offset ACTUALLY applied, never the raw (possibly dormant)
-  // var — see readAppliedStudioPathOffset. This keeps the commit purely relative
-  // (applied + delta) so a stale offset can't fling the element off-screen.
-  const initialOffset = readAppliedStudioPathOffset(input.element);
-  input.element.setAttribute("data-hf-drag-initial-offset-x", String(initialOffset.x));
-  input.element.setAttribute("data-hf-drag-initial-offset-y", String(initialOffset.y));
-
+  const plainTranslate = !!input.gesture && !gsapWritesPosition(input.element);
+  // Base the drag on the offset ACTUALLY applied, never a dormant var (readAppliedStudioPathOffset),
+  // so a stale offset can't fling the element off-screen.
+  const initialOffset = plainTranslate
+    ? readTranslatePx(input.element)
+    : readAppliedStudioPathOffset(input.element);
   const win = input.element.ownerDocument.defaultView as
     | (Window & {
         gsap?: { getProperty?: (el: Element, prop: string) => number };
         __timelines?: Record<string, { pause?: () => void; paused?: () => boolean }>;
       })
     | null;
-  const gsapX = win?.gsap?.getProperty?.(input.element, "x") || 0;
-  const gsapY = win?.gsap?.getProperty?.(input.element, "y") || 0;
-  input.element.setAttribute("data-hf-drag-gsap-base-x", String(gsapX));
-  input.element.setAttribute("data-hf-drag-gsap-base-y", String(gsapY));
+  // getProperty makes GSAP bake the CSS translate into its transform, so a plain move never reads it.
+  const gsapX = (!plainTranslate && win?.gsap?.getProperty?.(input.element, "x")) || 0;
+  const gsapY = (!plainTranslate && win?.gsap?.getProperty?.(input.element, "y")) || 0;
+  const baseGsap = { x: gsapX, y: gsapY };
+  if (!plainTranslate) stampGestureBase(input.element, initialOffset, baseGsap);
 
   if (win?.__timelines) {
     const paused: string[] = [];
@@ -373,8 +379,8 @@ export function createManualOffsetDragMember(input: {
   const measured = measureManualOffsetDragScreenToOffsetMatrix(input.element, initialOffset, {
     scaleX: input.rect.editScaleX,
     scaleY: input.rect.editScaleY,
+    plainTranslate,
   });
-  const baseGsap = { x: gsapX, y: gsapY };
   if (!measured.ok) {
     // Fallback: when GSAP transforms interfere with probe measurement, use
     // the preview scale as an approximation. The commit path reads the actual
@@ -390,6 +396,7 @@ export function createManualOffsetDragMember(input: {
         selection: input.selection,
         element: input.element,
         initialOffset,
+        plainTranslate,
         baseGsap,
         initialPathOffset,
         gestureToken,
@@ -406,6 +413,7 @@ export function createManualOffsetDragMember(input: {
       selection: input.selection,
       element: input.element,
       initialOffset,
+      plainTranslate,
       baseGsap,
       initialPathOffset,
       gestureToken,
@@ -428,18 +436,25 @@ function resolveManualOffsetDragMemberOffset(
   });
 }
 
+/** Draws the offset where the commit writes it: the inline translate, else GSAP, else the legacy var. */
+function drawMemberOffset(
+  member: ManualOffsetDragMember,
+  offset: { x: number; y: number },
+  commit: boolean,
+): void {
+  if (member.plainTranslate) writeTranslatePx(member.element, offset);
+  else if (applyOffsetDragDraftViaGsap(member.element, offset, member.baseGsap)) return;
+  else if (commit) applyStudioPathOffset(member.element, offset);
+  else applyStudioPathOffsetDraft(member.element, offset);
+}
+
 export function applyManualOffsetDragDraft(
   member: ManualOffsetDragMember,
   dx: number,
   dy: number,
 ): { x: number; y: number } {
   const offset = resolveManualOffsetDragMemberOffset(member, dx, dy);
-  // Position is single-sourced on the GSAP timeline; preview through gsap.set so
-  // the live draft matches the committed `tl.set`/keyframe. CSS draft only when
-  // gsap is unavailable (no preview iframe runtime).
-  if (!applyOffsetDragDraftViaGsap(member.element, offset, member.baseGsap)) {
-    applyStudioPathOffsetDraft(member.element, offset);
-  }
+  drawMemberOffset(member, offset, false);
   return offset;
 }
 
@@ -451,25 +466,20 @@ export function applyManualOffsetDragDraft(
  * the element flies off-screen the instant you drop it. The member holds the
  * true gesture-start values in JS, immune to the re-render.
  */
-function restampManualOffsetDragGestureBase(member: ManualOffsetDragMember): void {
-  member.element.setAttribute("data-hf-drag-gsap-base-x", String(member.baseGsap.x));
-  member.element.setAttribute("data-hf-drag-gsap-base-y", String(member.baseGsap.y));
-  member.element.setAttribute("data-hf-drag-initial-offset-x", String(member.initialOffset.x));
-  member.element.setAttribute("data-hf-drag-initial-offset-y", String(member.initialOffset.y));
+function stampGestureBase(el: HTMLElement, initialOffset: Point, baseGsap: Point): void {
+  el.setAttribute("data-hf-drag-gsap-base-x", String(baseGsap.x));
+  el.setAttribute("data-hf-drag-gsap-base-y", String(baseGsap.y));
+  el.setAttribute("data-hf-drag-initial-offset-x", String(initialOffset.x));
+  el.setAttribute("data-hf-drag-initial-offset-y", String(initialOffset.y));
 }
 
 function applyManualOffsetCommitValue(
   member: ManualOffsetDragMember,
   offset: { x: number; y: number },
 ): { x: number; y: number } {
-  restampManualOffsetDragGestureBase(member);
-  // Optimistic visual through the GSAP channel (same as the live draft and the
-  // committed `tl.set`), so the element holds its dropped position until the
-  // source mutation soft-reloads — no transient CSS `--hf-studio-offset` write.
-  // CSS apply only when gsap is unavailable.
-  if (!applyOffsetDragDraftViaGsap(member.element, offset, member.baseGsap)) {
-    applyStudioPathOffset(member.element, offset);
-  }
+  if (!member.plainTranslate)
+    stampGestureBase(member.element, member.initialOffset, member.baseGsap);
+  drawMemberOffset(member, offset, true);
   return offset;
 }
 
@@ -496,9 +506,7 @@ export function applyManualOffsetNudgeDraft(
     x: member.initialOffset.x + delta.x,
     y: member.initialOffset.y + delta.y,
   };
-  if (!applyOffsetDragDraftViaGsap(member.element, offset, member.baseGsap)) {
-    applyStudioPathOffsetDraft(member.element, offset);
-  }
+  drawMemberOffset(member, offset, false);
   return offset;
 }
 
@@ -514,7 +522,9 @@ export function applyManualOffsetNudgeCommit(
 
 function restoreManualOffsetDragMember(member: ManualOffsetDragMember): void {
   restoreStudioPathOffset(member.element, member.initialPathOffset);
-  getOffsetDragGsap(member.element)?.set(member.element, { ...member.baseGsap });
+  if (!member.plainTranslate) {
+    getOffsetDragGsap(member.element)?.set(member.element, { ...member.baseGsap });
+  }
   endStudioManualEditGesture(member.element, member.gestureToken);
 }
 
@@ -548,7 +558,7 @@ export function endManualOffsetDragMembers(members: ManualOffsetDragMember[]): v
     member.element.removeAttribute("data-hf-drag-gsap-base-y");
     // Do NOT clearProps:"transform" — that nukes the committed GSAP position
     // and causes a visual snap-back before the soft reload re-applies it.
-    const gsapOwnsPosition = Boolean(getOffsetDragGsap(member.element));
+    const gsapOwnsPosition = !member.plainTranslate && Boolean(getOffsetDragGsap(member.element));
     // Migration: when GSAP owns the position (the committed value lives in the
     // GSAP transform), the legacy `--hf-studio-offset` CSS channel is obsolete.
     // Clear it on the LIVE element — otherwise the leftover `translate:

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

@@ -0,0 +1,62 @@
+// @vitest-environment happy-dom
+import { describe, expect, it } from "vitest";
+import { readTranslatePx } from "./plainTranslate";
+
+function box(style: string): HTMLElement {
+  const element = document.createElement("div");
+  element.style.cssText = `position: absolute; width: 240px; height: 160px; ${style}`;
+  document.body.append(element);
+  return element;
+}
+
+describe("readTranslatePx", () => {
+  it.each([
+    ["40px 30px", { x: 40, y: 30 }],
+    ["-50% -50%", { x: -120, y: -80 }],
+    ["25% 25%", { x: 60, y: 40 }],
+    ["calc(-50% + 12px) calc(10% - 6px)", { x: -108, y: 10 }],
+    ["30px", { x: 30, y: 0 }],
+  ])("reads %s against the border box, in px", (translate, want) => {
+    expect(readTranslatePx(box(`translate: ${translate}`))).toEqual(want);
+  });
+
+  it.each([
+    ["calc(50% - 20px) 0px", { x: 100, y: 0 }],
+    ["calc(50% + 20px) calc(50% - 20px)", { x: 140, y: 60 }],
+  ])("adds and subtracts the terms of %s", (translate, want) => {
+    expect(readTranslatePx(box(`translate: ${translate}`))).toEqual(want);
+  });
+
+  it.each([
+    "min(10px, 5%) 0px",
+    "calc(2 * 10px) 0px",
+    "calc(10px +) 0px",
+    "clamp(0px, 10%, 30px) 5px",
+  ])("hands %s to Chrome's own resolution and puts the element's style back", (translate) => {
+    const element = box(`translate: ${translate}; transform: rotate(5deg)`);
+    const before = element.getAttribute("style");
+    const read = readTranslatePx(element);
+    expect(Number.isFinite(read.x) && Number.isFinite(read.y)).toBe(true);
+    expect(element.getAttribute("style")).toBe(before);
+  });
+
+  it("counts padding and border in the box a percent resolves against", () => {
+    const element = box(
+      "translate: 50% 50%; padding: 10px; border: 5px solid; box-sizing: content-box",
+    );
+    expect(readTranslatePx(element)).toEqual({ x: 135, y: 95 });
+  });
+
+  it("writes nothing to the element it reads", () => {
+    const element = box("translate: -50% -50%");
+    const before = element.getAttribute("style");
+    const writes: MutationRecord[] = [];
+    const observer = new MutationObserver((records) => writes.push(...records));
+    observer.observe(element, { attributes: true });
+    readTranslatePx(element);
+    writes.push(...observer.takeRecords());
+    observer.disconnect();
+    expect(writes).toEqual([]);
+    expect(element.getAttribute("style")).toBe(before);
+  });
+});

package/src/components/editor/plainTranslate.ts

@@ -0,0 +1,85 @@
+import { roundTo3 } from "../../utils/rounding";
+import { gsapWritesPosition } from "../../hooks/gsapRuntimeKeyframes";
+import { readStudioPathOffset } from "./manualEditsDom";
+import { splitTopLevelWhitespace } from "./manualEditsStyleHelpers";
+import type { PatchOperation } from "../../utils/sourcePatcher";
+
+type Point = { x: number; y: number };
+
+const TERM = /^(-?\d*\.?\d+(?:e[-+]?\d+)?)(px|%)$/i;
+
+const SIGN: Record<string, number> = { "+": 1, "-": -1 };
+
+function termPx(term: string | undefined, side: number): number | null {
+  const match = TERM.exec(term ?? "");
+  return match ? Number(match[1]) * (match[2] === "%" ? side / 100 : 1) : null;
+}
+
+/** px, %, or Chrome's computed `calc(P% + Lpx)`, against the border-box side; null for min()/max()/clamp(). */
+function resolveLength(value: string, side: number): number | null {
+  const parts = (/^calc\((.*)\)$/.exec(value)?.[1] ?? value).split(" ");
+  if (parts.length % 2 === 0) return null;
+  let total = termPx(parts[0], side);
+  for (let i = 1; i < parts.length && total !== null; i += 2) {
+    const term = termPx(parts[i + 1], side);
+    const sign = SIGN[parts[i] ?? ""];
+    total = term === null || !sign ? null : total + sign * term;
+  }
+  return total;
+}
+
+function borderBox(
+  cs: CSSStyleDeclaration,
+  size: "width" | "height",
+  a: string,
+  b: string,
+): number {
+  const n = (prop: string) => Number.parseFloat(cs.getPropertyValue(prop)) || 0;
+  const pad =
+    n(`padding-${a}`) + n(`padding-${b}`) + n(`border-${a}-width`) + n(`border-${b}-width`);
+  return n(size) + (cs.boxSizing === "border-box" ? 0 : pad);
+}
+
+// Chrome resolves min()/max()/clamp() inside a transform function to a matrix; an unrendered box has none.
+function resolveInTransform(el: HTMLElement, x: string, y: string): Point {
+  const style = el.style;
+  const saved = [style.getPropertyValue("transform"), style.getPropertyPriority("transform")];
+  style.setProperty("transform", `translate(${x}, ${y})`, "important");
+  try {
+    const resolved = el.ownerDocument.defaultView?.getComputedStyle(el).transform ?? "";
+    const matrix = new DOMMatrixReadOnly(resolved.startsWith("matrix") ? resolved : undefined);
+    return { x: matrix.m41, y: matrix.m42 };
+  } finally {
+    style.setProperty("transform", saved[0] ?? "", saved[1] ?? "");
+  }
+}
+
+/** The element's CSS `translate` in px, as it renders now. */
+// ponytail: a 3-value translate loses its z on the next move; keep z when a fixture needs it.
+export function readTranslatePx(el: HTMLElement): Point {
+  const cs = el.ownerDocument.defaultView?.getComputedStyle(el);
+  const value = el.style.getPropertyValue("translate") || cs?.translate || "none";
+  if (value === "none") return { x: 0, y: 0 };
+  const [x = "0px", y = "0px"] = splitTopLevelWhitespace(value);
+  const px = cs && resolveLength(x, borderBox(cs, "width", "left", "right"));
+  const py = cs && resolveLength(y, borderBox(cs, "height", "top", "bottom"));
+  return px != null && py != null ? { x: px, y: py } : resolveInTransform(el, x, y);
+}
+
+/** Plain px only: GSAP's CSSPlugin splits `translate` on spaces and drops a calc(). */
+function formatTranslatePx(p: Point): string {
+  return `${roundTo3(p.x)}px ${roundTo3(p.y)}px`;
+}
+
+export function translatePatch(p: Point): PatchOperation & { value: string } {
+  return { type: "inline-style", property: "translate", value: formatTranslatePx(p) };
+}
+
+export function writeTranslatePx(el: HTMLElement, p: Point): void {
+  el.style.setProperty("translate", formatTranslatePx(p));
+}
+
+/** The position the panel shows and edits: the translate a move writes, unless GSAP positions it. */
+export function readMoveOffset(el: HTMLElement): Point {
+  return gsapWritesPosition(el) ? readStudioPathOffset(el) : readTranslatePx(el);
+}

package/src/components/editor/propertyPanelTransformCommit.ts

@@ -1,5 +1,6 @@
 import type { DomEditSelection } from "./domEditingTypes";
-import { readStudioBoxSize, readStudioPathOffset } from "./manualEdits";
+import { readStudioBoxSize } from "./manualEdits";
+import { readMoveOffset } from "./plainTranslate";
 import { parsePxMetricValue, type PropertyPanelProps } from "./propertyPanelHelpers";
 
 interface TransformCommitDeps {
@@ -73,7 +74,7 @@ export function createTransformCommitHandlers({
       )
     )
       return;
-    const current = readStudioPathOffset(element.element);
+    const current = readMoveOffset(element.element);
     await Promise.resolve(
       onSetManualOffset(element, {
         x: axis === "x" ? parsed : current.x,

package/src/components/editor/useDomEditNudge.ts

@@ -189,7 +189,7 @@ export function useDomEditNudge(params: UseDomEditNudgeParams): { flushNudge: ()
     if (!targets) return null;
     const members: ManualOffsetDragMember[] = [];
     for (const target of targets) {
-      const result = createManualOffsetDragMember(target);
+      const result = createManualOffsetDragMember({ ...target, gesture: "nudge" });
       if (!result.ok) {
         restoreManualOffsetDragMembers(members);
         return null;