@hyperframes/studio 0.8.103 → 0.8.104

package/src/components/editor/rotationDraft.ts

@@ -0,0 +1,145 @@
+import { readCssRotation } from "../../hooks/draggedGsapPosition";
+import { roundTo3 } from "../../utils/rounding";
+import type { PatchOperation } from "../../utils/sourcePatcher";
+import {
+  readStudioRotation,
+  restoreStudioRotation,
+  type StudioRotationSnapshot,
+} from "./manualEdits";
+import { getOffsetDragGsap } from "./manualOffsetDrag";
+import { splitTopLevelWhitespace } from "./manualEditsStyleHelpers";
+
+function lastRuleTransform(element: HTMLElement): string {
+  let value = "";
+  for (const sheet of Array.from(element.ownerDocument.styleSheets)) {
+    let rules: CSSStyleRule[] = [];
+    try {
+      rules = Array.from(sheet.cssRules) as CSSStyleRule[];
+    } catch {
+      // a cross-origin sheet
+    }
+    for (const rule of rules) {
+      const declared = rule.style?.getPropertyValue("transform");
+      if (declared && element.matches(rule.selectorText)) value = declared;
+    }
+  }
+  return value;
+}
+
+// ponytail: the authored transform if it moves the box, from the last matching rule in sheet order;
+// specificity, !important and @media are not weighed. Weigh them when a film's rule is missed.
+function translatingTransform(element: HTMLElement): string {
+  const view = element.ownerDocument.defaultView;
+  const computed = view?.getComputedStyle(element).transform ?? "none";
+  const m = computed === "none" ? null : new view!.DOMMatrix(computed);
+  if (!m || (m.m41 === 0 && m.m42 === 0)) return "";
+  const value = element.style.getPropertyValue("transform") || lastRuleTransform(element);
+  return value === "none" ? "" : value;
+}
+
+/** Where a plain rotate draws its turn, read once at press: the element's own `rotate`, or, when its
+ *  transform translates it (often the translate(-50%, -50%) centring), a rotate() right after that
+ *  translate, so the box turns in place in screen space. `share` is what the rest already turns. */
+export interface CssRotationTarget {
+  property: "rotate" | "transform";
+  before: string;
+  after: string;
+  share: number;
+  /** -1 when a mirroring `scale` property flips a turn made inside the transform. */
+  sign: number;
+  /** An inline box does not transform, so the turn makes it inline-block. */
+  inline: boolean;
+}
+
+export type RotationCommit = { angle: number; plain?: CssRotationTarget };
+
+const TRANSLATE = /^translate(?:3d|X|Y|Z)?\(/i;
+const OWN_TURN = /^rotate\(\s*-?[\d.]+(?:e[+-]?\d+)?deg\s*\)$/i;
+
+export function readCssRotationTarget(element: HTMLElement): CssRotationTarget {
+  const style = element.ownerDocument.defaultView?.getComputedStyle(element);
+  const inline = style?.display === "inline";
+  const transform = translatingTransform(element);
+  if (!transform) {
+    const share = readCssRotation(element, false);
+    return { property: "rotate", before: "", after: "", share, sign: 1, inline };
+  }
+  const parts = splitTopLevelWhitespace(transform);
+  const lead = parts.findIndex((part) => !TRANSLATE.test(part));
+  const split = lead < 0 ? parts.length : lead;
+  const rest = parts.slice(split);
+  if (OWN_TURN.test(rest[0] ?? "")) rest.shift();
+  const [before, after] = [parts.slice(0, split).join(" "), rest.join(" ")];
+  const [sx = 1, sy = sx] = splitTopLevelWhitespace(style?.getPropertyValue("scale") ?? "").map(
+    Number.parseFloat,
+  );
+  const inlineStyle = element.style;
+  const saved = [
+    inlineStyle.getPropertyValue("transform"),
+    inlineStyle.getPropertyPriority("transform"),
+  ];
+  inlineStyle.setProperty("transform", `${before} ${after}`.trim() || "none");
+  const share = readCssRotation(element);
+  inlineStyle.setProperty("transform", saved[0] ?? "", saved[1] ?? "");
+  return { property: "transform", before, after, share, sign: sx * sy < 0 ? -1 : 1, inline };
+}
+
+/** Draws `angle` where `target` says, and returns the source patches that save it as drawn. */
+export function applyCssRotation(
+  element: HTMLElement,
+  angle: number,
+  target = readCssRotationTarget(element),
+): Array<PatchOperation & { value: string }> {
+  const turn = `${roundTo3(target.sign * (angle - target.share))}deg`;
+  const value =
+    target.property === "rotate"
+      ? turn
+      : [target.before, `rotate(${turn})`, target.after].filter(Boolean).join(" ");
+  const patches: Array<PatchOperation & { value: string }> = [
+    { type: "inline-style", property: target.property, value },
+  ];
+  if (target.inline) {
+    patches.unshift({ type: "inline-style", property: "display", value: "inline-block" });
+  }
+  for (const patch of patches) element.style.setProperty(patch.property, patch.value);
+  return patches;
+}
+
+/** Back to the press: the rotation snapshot and, for a plain rotate, the inline transform it drew in. */
+export function restorePlainRotation(element: HTMLElement, snapshot: StudioRotationSnapshot): void {
+  restoreStudioRotation(element, snapshot);
+  element.style.setProperty("transform", snapshot.transform);
+  element.style.setProperty("display", snapshot.display);
+}
+
+// `plain`, read at press: where a turn GSAP does not own draws; null for GSAP's rotation.
+export function applyRotationDraft(
+  element: HTMLElement,
+  angle: number,
+  plain: CssRotationTarget | null,
+): void {
+  if (plain) return void applyCssRotation(element, angle, plain);
+  element.style.setProperty("rotate", "none");
+  getOffsetDragGsap(element)?.set(element, { rotation: angle });
+}
+
+/** Back to the gesture start: the CSS snapshot, and GSAP's rotation without the legacy var. */
+export function restoreRotationDraft(
+  element: HTMLElement,
+  angle: number,
+  snapshot: StudioRotationSnapshot,
+  plain: boolean,
+): void {
+  if (plain) return restorePlainRotation(element, snapshot);
+  getOffsetDragGsap(element)?.set(element, {
+    rotation: angle - (Number.parseFloat(snapshot.studioRotation) || 0),
+  });
+  restoreStudioRotation(element, snapshot);
+}
+
+/** The angle a rotate gesture starts from, as the element shows it. */
+export function readRotationBase(element: HTMLElement, plain: boolean): number {
+  if (plain) return readCssRotation(element);
+  const gsapRotation = Number(getOffsetDragGsap(element)?.getProperty(element, "rotation") ?? 0);
+  return gsapRotation + readStudioRotation(element).angle;
+}

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

@@ -227,3 +227,36 @@ describe("useDomEditNudge — selection cleanup keyed on stable identity", () =>
     elementB.remove();
   });
 });
+
+describe("useDomEditNudge carries the route its press chose", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    __resetForTests();
+  });
+  afterEach(() => vi.useRealTimers());
+
+  it("commits an element without GSAP on the CSS route", () => {
+    const host = document.createElement("div");
+    const root = createRoot(host);
+    const element = document.createElement("div");
+    document.body.append(element);
+    const commit = vi.fn();
+    act(() => {
+      root.render(
+        React.createElement(Harness, {
+          selection: makeSelection("Dot", element),
+          onPathOffsetCommit: commit,
+        }),
+      );
+    });
+    act(() => dispatchArrowRight());
+    act(() => vi.advanceTimersByTime(CANVAS_NUDGE_COMMIT_DEBOUNCE_MS + 10));
+    expect(commit).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.anything(),
+      expect.objectContaining({ plainTranslate: true }),
+    );
+    act(() => root.unmount());
+    element.remove();
+  });
+});

package/src/components/editor/useDomEditNudge.ts

@@ -18,6 +18,7 @@ import {
 import type {
   BlockedMoveState,
   DomEditGroupPathOffsetCommit,
+  MoveCommitOptions,
   GestureState,
   GroupGestureState,
 } from "./domEditOverlayGestures";
@@ -60,7 +61,7 @@ export interface UseDomEditNudgeParams {
     (
       s: DomEditSelection,
       n: { x: number; y: number },
-      m?: { altKey?: boolean },
+      m?: MoveCommitOptions,
     ) => Promise<unknown> | void
   >;
   onGroupPathOffsetCommitRef: RefObject<
@@ -150,11 +151,14 @@ export function useDomEditNudge(params: UseDomEditNudgeParams): { flushNudge: ()
     const updates: DomEditGroupPathOffsetCommit[] = session.members.map((member) => ({
       selection: member.selection,
       next: applyManualOffsetNudgeCommit(member, session.accum),
+      plainTranslate: member.plainTranslate,
     }));
     const p = paramsRef.current;
     const commit = session.isGroup
       ? p.onGroupPathOffsetCommitRef.current(updates)
-      : p.onPathOffsetCommitRef.current(updates[0].selection, updates[0].next);
+      : p.onPathOffsetCommitRef.current(updates[0].selection, updates[0].next, {
+          plainTranslate: updates[0].plainTranslate,
+        });
     void Promise.resolve(commit)
       .catch(() => {
         for (const member of session.members) {

package/src/components/editor/useDomEditOverlayGestures.ts

@@ -9,21 +9,18 @@ import { type DomEditSelection } from "./domEditing";
 import {
   applyManualOffsetDragCommit,
   applyManualOffsetDragDraft,
-  applyRotationDraftViaGsap,
   endManualOffsetDragMembers,
   restoreManualOffsetDragMembers,
 } from "./manualOffsetDrag";
+import { applyRotationDraft, restoreRotationDraft } from "./rotationDraft";
 import {
   applyStudioBoxSize,
   applyStudioBoxSizeDraft,
-  applyStudioRotation,
-  applyStudioRotationDraft,
   endStudioManualEditGesture,
   isStudioManualEditGestureCurrent,
   readStudioBoxSize,
   restoreStudioBoxSize,
   restoreStudioPathOffset,
-  restoreStudioRotation,
 } from "./manualEdits";
 import {
   type GroupOverlayItem,
@@ -166,9 +163,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
         actualAngle: g.actualRotation,
         snap: e.shiftKey,
       });
-      if (!applyRotationDraftViaGsap(sel.element, rotated.angle)) {
-        applyStudioRotationDraft(sel.element, rotated);
-      }
+      applyRotationDraft(sel.element, rotated.angle, g.plainRotation);
       return;
     }
 
@@ -336,6 +331,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
       const updates = groupG.members.map((member) => ({
         selection: member.selection,
         next: applyManualOffsetDragCommit(member, dx, dy),
+        plainTranslate: member.plainTranslate,
       }));
       logDrag("drop", {
         pointer: `${Math.round(rawDx)},${Math.round(rawDy)}`,
@@ -421,24 +417,22 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
         actualAngle: g.actualRotation,
         snap: e.shiftKey,
       });
-      const restoreRotation = () => {
-        // Single source of truth: snap the GSAP rotation back to the gesture's base
-        // angle; fall back to the legacy CSS-var restore when gsap is unavailable.
-        if (!applyRotationDraftViaGsap(sel.element, g.actualRotation)) {
-          restoreStudioRotation(sel.element, g.initialRotation);
-        }
-      };
+      const restoreRotation = () =>
+        restoreRotationDraft(
+          sel.element,
+          g.actualRotation,
+          g.initialRotation,
+          g.plainRotation !== null,
+        );
       if (!hasDomEditRotationChanged(g.actualRotation, finalRotation.angle)) {
         restoreRotation();
         endStudioManualEditGesture(sel.element, g.manualEditDragToken);
         return;
       }
-      // Keep the preview at the final angle through the GSAP channel (NOT the CSS var)
-      // while the commit lands a `tl.set`/keyframe rotation on the timeline.
-      if (!applyRotationDraftViaGsap(sel.element, finalRotation.angle)) {
-        applyStudioRotation(sel.element, finalRotation);
-      }
-      void Promise.resolve(opts.onRotationCommitRef.current(sel, finalRotation))
+      // Hold the final angle while the commit lands.
+      applyRotationDraft(sel.element, finalRotation.angle, g.plainRotation);
+      const commit = g.plainRotation ? { ...finalRotation, plain: g.plainRotation } : finalRotation;
+      void Promise.resolve(opts.onRotationCommitRef.current(sel, commit))
         .catch((error) => {
           logGestureCommitFailure("rotate commit failed", error);
           if (
@@ -476,7 +470,10 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
         box.style.top = `${nextBoxTop}px`;
       }
       void Promise.resolve(
-        opts.onPathOffsetCommitRef.current(sel, finalOffset, { altKey: e.altKey }),
+        opts.onPathOffsetCommitRef.current(sel, finalOffset, {
+          altKey: e.altKey,
+          plainTranslate: g.pathOffsetMember.plainTranslate,
+        }),
       )
         .catch(() => {
           if (
@@ -555,11 +552,12 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
       restoreGestureOverlayRect(g);
     }
     if (g?.mode === "rotation" && sel) {
-      applyRotationDraftViaGsap(
+      restoreRotationDraft(
         sel.element,
-        g.actualRotation - (Number.parseFloat(g.initialRotation.studioRotation) || 0),
+        g.actualRotation,
+        g.initialRotation,
+        g.plainRotation !== null,
       );
-      restoreStudioRotation(sel.element, g.initialRotation);
       endStudioManualEditGesture(sel.element, g.manualEditDragToken);
     }
     opts.blockedMoveRef.current = null;

package/src/hooks/draggedGsapPosition.ts

@@ -8,6 +8,34 @@ import { roundTo3 } from "../utils/rounding";
  * it without pulling the GSAP commit graph into its module scope.
  */
 
+const cssValue = (style: CSSStyleDeclaration, prop: string) => {
+  const value = style.getPropertyValue(prop).trim();
+  return value === "none" ? "" : value;
+};
+
+// Without GSAP, the rotation GSAP will parse from the CSS `rotate`, `scale` and `transform`; with
+// `withRotate` false, only the part `scale` and `transform` draw. GSAP folds them into one transform,
+// and a list the browser rejects (e.g. `rotate: x 30deg`) leaves it only the plain transform.
+export function readCssRotation(element: HTMLElement, withRotate = true): number {
+  const view = element.ownerDocument.defaultView;
+  if (!view) return 0;
+  const style = view.getComputedStyle(element);
+  const rotate = withRotate ? cssValue(style, "rotate") : "";
+  const scale = cssValue(style, "scale");
+  const transform = cssValue(style, "transform");
+  const angle = (list: string) => {
+    if (!list) return 0;
+    const m = new view.DOMMatrix(list);
+    return (Math.atan2(m.b, m.a) * 180) / Math.PI;
+  };
+  const folded = [rotate && `rotate(${rotate})`, scale && `scale(${scale.split(/\s+/).join(",")})`];
+  try {
+    return angle([...folded, transform].join(" ").trim());
+  } catch {
+    return angle(transform);
+  }
+}
+
 /**
  * Translate a studio drag offset into absolute GSAP x/y, accounting for the
  * element's rotation and its drag-start base pose. Reads the drag-start

package/src/hooks/elementOffsetStager.ts

@@ -6,7 +6,11 @@ import {
 import { LAYER_REVEAL_PRIOR_POSITION_ATTR } from "../player/lib/timelineElementHelpers";
 import type { PatchOperation } from "../utils/sourcePatcher";
 import { translatePatch } from "../components/editor/plainTranslate";
-import { gsapWritesPosition } from "./gsapRuntimeKeyframes";
+import { gsapHoldsTranslate } from "./gsapRuntimeKeyframes";
+import { markStudioSaveErrorAlreadyToasted } from "../utils/studioSaveDiagnostics";
+
+const GSAP_TOOK_OVER =
+  "The animation took over this layer's position during the move, so it was not saved.";
 
 const ELEMENT_OFFSET_REFUSED: Record<ElementOffsetRefusal, string> = {
   anchored: "This layer is anchored from its right or bottom edge. Move it in the Code tab.",
@@ -23,15 +27,29 @@ export interface ElementOffsetStagerDeps {
   readOnlyPreview?: boolean;
 }
 
+function gsapOf(el: HTMLElement): { set: (t: Element, v: object) => void } | undefined {
+  return (el.ownerDocument.defaultView as { gsap?: { set: (t: Element, v: object) => void } })
+    ?.gsap;
+}
+
 /** The drag draft moved GSAP's x/y; left/top carries the move now, so put them back. */
 function settleGsapDraftAtGestureStart(el: HTMLElement): void {
-  const gsap = (el.ownerDocument.defaultView as { gsap?: { set: (t: Element, v: object) => void } })
-    ?.gsap;
+  const gsap = gsapOf(el);
   const x = Number.parseFloat(el.getAttribute("data-hf-drag-gsap-base-x") ?? "");
   const y = Number.parseFloat(el.getAttribute("data-hf-drag-gsap-base-y") ?? "");
   if (gsap && Number.isFinite(x) && Number.isFinite(y)) gsap.set(el, { x, y });
 }
 
+export function refuseGsapTakeover(
+  el: HTMLElement,
+  showToast: ElementOffsetStagerDeps["showToast"],
+) {
+  if (!gsapHoldsTranslate(el)) return;
+  gsapOf(el)?.set(el, { x: 0, y: 0, xPercent: 0, yPercent: 0 });
+  showToast(GSAP_TOOK_OVER, "error");
+  throw markStudioSaveErrorAlreadyToasted(new Error(GSAP_TOOK_OVER));
+}
+
 let plainMoveCounter = 0;
 
 /** GSAP does not position the element: `next` is its whole translate, live now and saved as drawn. */
@@ -58,17 +76,19 @@ function stagePlainTranslate(
   return { save, rollback };
 }
 
-/** Applies a move on the element itself live now: its translate when GSAP does not position it,
- *  else left/top for a shared-tween element. Throws, after a toast, when it cannot. */
+/** Applies a move on the element itself live now: its translate on the plain route, else
+ *  left/top for a shared-tween element. Throws, after a toast, when it cannot. */
 export function stageElementOffset(
   { commitPositionPatchToHtml, showToast, readOnlyPreview }: ElementOffsetStagerDeps,
   selection: DomEditSelection,
   next: { x: number; y: number },
+  plainTranslate: boolean,
   coalesceKey?: string,
 ): { save: () => Promise<void>; rollback: () => void } {
   const el = selection.element;
   if (readOnlyPreview) return { save: () => Promise.resolve(), rollback: () => undefined };
-  if (!gsapWritesPosition(el)) {
+  if (plainTranslate) {
+    refuseGsapTakeover(el, showToast);
     return stagePlainTranslate(commitPositionPatchToHtml, selection, next, coalesceKey);
   }
   const previous = { position: el.style.position, left: el.style.left, top: el.style.top };

package/src/hooks/gsapRuntimeBridge.ts

@@ -35,7 +35,11 @@ import {
   pickClosestToPlayhead,
   readGsapPositionFromIframe,
 } from "./gsapPositionDetection";
-import { hasNonHoldTweenForElement, POSITION_CHANNELS } from "./gsapRuntimeKeyframes";
+import {
+  hasNonHoldTweenForElement,
+  POSITION_CHANNELS,
+  ROTATION_CHANNELS,
+} from "./gsapRuntimeKeyframes";
 import { getAnimationsForElement } from "./gsapElementMatch";
 import {
   animationWritesAnyProperty,
@@ -44,8 +48,6 @@ import {
 } from "./gsapEditOutcome";
 
 const POSITION_CHANNEL_SET = new Set<string>(POSITION_CHANNELS);
-
-const ROTATION_CHANNELS: string[] = ["rotation", "rotationX", "rotationY", "rotationZ"];
 const ROTATION_CHANNEL_SET = new Set<string>(ROTATION_CHANNELS);
 
 // ── Property-group tween resolution ───────────────────────────────────────

package/src/hooks/gsapRuntimeKeyframes.ts

@@ -11,6 +11,7 @@
 import { buildArcPath, type ArcPathConfig } from "@hyperframes/core/gsap-parser-acorn";
 import { parsePercentageKeyframes, toAbsoluteTime } from "./gsapShared";
 import { roundTo3 } from "../utils/rounding";
+import { BOX_SIZE_STYLE_PROPS } from "../components/editor/manualEditsDomPatches";
 
 /**
  * A GSAP tween's `vars` object — intentionally open: it mixes channel values
@@ -439,11 +440,44 @@ function gsapWritesChannels(el: Element, channels: string[]): boolean {
   );
 }
 
+// GSAP's CSSPlugin also takes rotate, rotateX/Y/Z for rotation.
+export const ROTATION_CHANNELS: string[] = [
+  ...["rotation", "rotationX", "rotationY", "rotationZ"],
+  ...["rotate", "rotateX", "rotateY", "rotateZ"],
+];
+
+const gsapRendersTransform = (el: Element) =>
+  !!(el as { _gsap?: { renderTransform?: unknown } })._gsap?.renderTransform;
+
 /** GSAP owns this element's position: a tween or hold writes it, or GSAP already renders its
  *  transform (a CSS translate would then apply twice). Everything else moves by plain CSS. */
 export function gsapWritesPosition(el: Element): boolean {
-  const cache = (el as { _gsap?: { renderTransform?: unknown } })._gsap;
-  return !!cache?.renderTransform || gsapWritesChannels(el, MOVE_CHANNELS);
+  return gsapRendersTransform(el) || gsapWritesChannels(el, MOVE_CHANNELS);
+}
+
+/** `gsapWritesPosition` for a rotate: everything else turns by its own CSS `rotate`. */
+export function gsapWritesRotation(el: Element): boolean {
+  return gsapRendersTransform(el) || gsapWritesChannels(el, ROTATION_CHANNELS);
+}
+
+export function gsapHoldsTranslate(el: Element): boolean {
+  const cache = (el as { _gsap?: Record<string, unknown> })._gsap;
+  return ["x", "y", "xPercent", "yPercent"].some(
+    (key) => !!Number.parseFloat(String(cache?.[key])),
+  );
+}
+
+const BOX_CHANNELS = [
+  ...BOX_SIZE_STYLE_PROPS.map((prop) =>
+    prop.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase()),
+  ),
+  "scaleX",
+  "scaleY",
+];
+
+/** GSAP owns this element's box: its position, or any property the CSS box writer sets. Else a resize writes CSS. */
+export function gsapWritesBox(el: Element): boolean {
+  return gsapWritesPosition(el) || gsapWritesChannels(el, BOX_CHANNELS);
 }
 
 /** `hasNonHoldTweenForElement` for an element in hand, read from its own window's timelines. */

package/src/hooks/plainRotation.test.ts

@@ -0,0 +1,122 @@
+// @vitest-environment happy-dom
+
+import { describe, expect, it, vi } from "vitest";
+import type { DomEditSelection } from "../components/editor/domEditing";
+import {
+  applyStudioRotation,
+  reapplyPositionEditsAfterSeek,
+} from "../components/editor/manualEdits";
+import { STUDIO_ROTATION_ATTR } from "../components/editor/manualEditsTypes";
+import type { ElementOffsetStagerDeps } from "./elementOffsetStager";
+import { savePlainRotation } from "./plainRotation";
+import { readShownRotation } from "../components/editor/plainTranslate";
+
+function rotate(
+  element: HTMLElement,
+  angle: number,
+  options: { save?: () => Promise<void>; readOnlyPreview?: boolean } = {},
+) {
+  element.id = "box";
+  document.body.append(element);
+  const commitPositionPatchToHtml = vi.fn<ElementOffsetStagerDeps["commitPositionPatchToHtml"]>(
+    options.save ?? (() => Promise.resolve()),
+  );
+  const selection = { element, id: "box", selector: "#box" } as unknown as DomEditSelection;
+  const saved = savePlainRotation(
+    { commitPositionPatchToHtml, readOnlyPreview: options.readOnlyPreview },
+    selection,
+    { angle },
+  );
+  return { saved, commitPositionPatchToHtml, selection };
+}
+
+describe("savePlainRotation", () => {
+  it("saves the element's own rotate, less what its transform turns, with no Studio marks", async () => {
+    const element = document.createElement("div");
+    element.style.transform = "rotate(10deg)";
+    const { saved, commitPositionPatchToHtml, selection } = rotate(element, 55);
+    await saved;
+    expect(element.style.getPropertyValue("rotate")).toBe("45deg");
+    expect(commitPositionPatchToHtml).toHaveBeenCalledWith(
+      selection,
+      [{ type: "inline-style", property: "rotate", value: "45deg" }],
+      expect.objectContaining({ label: "Rotate layer" }),
+    );
+    expect(element.hasAttribute(STUDIO_ROTATION_ATTR)).toBe(false);
+  });
+
+  it("drops a legacy Studio rotation in the same write, so a seek does not put its angle back", async () => {
+    const element = document.createElement("div");
+    applyStudioRotation(element, { angle: 15 });
+    const { saved, commitPositionPatchToHtml } = rotate(element, 40);
+    await saved;
+    const patches = commitPositionPatchToHtml.mock.calls[0]![1];
+    expect(patches).toContainEqual({
+      type: "attribute",
+      property: STUDIO_ROTATION_ATTR,
+      value: null,
+    });
+    expect(patches.at(-1)).toEqual({ type: "inline-style", property: "rotate", value: "40deg" });
+    reapplyPositionEditsAfterSeek(document);
+    expect(element.style.getPropertyValue("rotate")).toBe("40deg");
+  });
+
+  it("puts the live rotate back when the save fails", async () => {
+    const element = document.createElement("div");
+    element.style.setProperty("rotate", "12deg");
+    const { saved } = rotate(element, 30, { save: () => Promise.reject(new Error("offline")) });
+    await expect(saved).rejects.toThrow("offline");
+    expect(element.style.getPropertyValue("rotate")).toBe("12deg");
+  });
+
+  it("writes nothing in a read-only preview", async () => {
+    const element = document.createElement("div");
+    const { saved, commitPositionPatchToHtml } = rotate(element, 30, { readOnlyPreview: true });
+    await saved;
+    expect(element.style.getPropertyValue("rotate")).toBe("");
+    expect(commitPositionPatchToHtml).not.toHaveBeenCalled();
+  });
+
+  it("saves a transform-centred element's turn in its transform and puts it back on a failed save", async () => {
+    const element = document.createElement("div");
+    element.style.transform = "translate(-120px, -80px)";
+    const { saved, commitPositionPatchToHtml } = rotate(element, 25, {
+      save: () => Promise.reject(new Error("offline")),
+    });
+    expect(commitPositionPatchToHtml.mock.calls[0]![1]).toEqual([
+      {
+        type: "inline-style",
+        property: "transform",
+        value: "translate(-120px, -80px) rotate(25deg)",
+      },
+    ]);
+    await expect(saved).rejects.toThrow("offline");
+    expect(element.style.getPropertyValue("transform")).toBe("translate(-120px, -80px)");
+  });
+
+  it("makes an inline element inline-block, as a turn needs, and puts it back on a failed save", async () => {
+    const element = document.createElement("span");
+    element.style.setProperty("display", "inline");
+    const { saved, commitPositionPatchToHtml } = rotate(element, 20, {
+      save: () => Promise.reject(new Error("offline")),
+    });
+    expect(commitPositionPatchToHtml.mock.calls[0]![1]).toEqual([
+      { type: "inline-style", property: "display", value: "inline-block" },
+      { type: "inline-style", property: "rotate", value: "20deg" },
+    ]);
+    await expect(saved).rejects.toThrow("offline");
+    expect(element.style.getPropertyValue("display")).toBe("inline");
+  });
+});
+
+describe("readShownRotation", () => {
+  it("shows an element's own CSS turn, and GSAP's legacy reading once GSAP turns it", () => {
+    const element = document.createElement("div");
+    document.body.append(element);
+    element.style.setProperty("rotate", "25deg");
+    expect(readShownRotation(element)).toEqual({ angle: 25 });
+    Object.assign(element, { _gsap: { renderTransform: () => {} } });
+    applyStudioRotation(element, { angle: 15 });
+    expect(readShownRotation(element)).toEqual({ angle: 15 });
+  });
+});

package/src/hooks/plainRotation.ts

@@ -0,0 +1,42 @@
+import type { DomEditSelection } from "../components/editor/domEditing";
+import { captureStudioRotation, clearStudioRotation } from "../components/editor/manualEdits";
+import { buildClearRotationPatches } from "../components/editor/manualEditsDomPatches";
+import { STUDIO_ROTATION_ATTR } from "../components/editor/manualEditsTypes";
+import {
+  applyCssRotation,
+  restorePlainRotation,
+  type RotationCommit,
+} from "../components/editor/rotationDraft";
+import type { PatchOperation } from "../utils/sourcePatcher";
+import type { ElementOffsetStagerDeps } from "./elementOffsetStager";
+
+let plainRotateCounter = 0;
+
+/** GSAP does not turn the element: `next` is its whole angle, drawn and saved as its CSS turn. */
+export function savePlainRotation(
+  { commitPositionPatchToHtml, readOnlyPreview }: Omit<ElementOffsetStagerDeps, "showToast">,
+  selection: DomEditSelection,
+  next: RotationCommit,
+): Promise<void> {
+  if (readOnlyPreview) return Promise.resolve();
+  const { element } = selection;
+  const before = captureStudioRotation(element);
+  // Legacy marks go in the same write, or a seek puts their angle back; clearing them voids the press read.
+  const patches: PatchOperation[] = element.hasAttribute(STUDIO_ROTATION_ATTR)
+    ? buildClearRotationPatches(element)
+    : [];
+  if (patches.length) clearStudioRotation(element);
+  const drawn = applyCssRotation(element, next.angle, patches.length ? undefined : next.plain);
+  patches.push(...drawn);
+  const turn = drawn.at(-1)!;
+  return commitPositionPatchToHtml(selection, patches, {
+    label: "Rotate layer",
+    coalesceKey: `rotate:${++plainRotateCounter}`,
+    coalesceMs: Number.POSITIVE_INFINITY,
+  }).catch((error) => {
+    if (element.style.getPropertyValue(turn.property) === turn.value) {
+      restorePlainRotation(element, before);
+    }
+    throw error;
+  });
+}