@hyperframes/studio 0.7.52 → 0.7.54

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.7.52",
+  "version": "0.7.54",
   "description": "",
   "repository": {
     "type": "git",
@@ -46,11 +46,11 @@
     "gsap": "^3.13.0",
     "marked": "^14.1.4",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.7.52",
-    "@hyperframes/parsers": "0.7.52",
-    "@hyperframes/sdk": "0.7.52",
-    "@hyperframes/player": "0.7.52",
-    "@hyperframes/studio-server": "0.7.52"
+    "@hyperframes/player": "0.7.54",
+    "@hyperframes/sdk": "0.7.54",
+    "@hyperframes/parsers": "0.7.54",
+    "@hyperframes/studio-server": "0.7.54",
+    "@hyperframes/core": "0.7.54"
   },
   "devDependencies": {
     "@types/react": "19",
@@ -65,7 +65,7 @@
     "vite": "^6.4.2",
     "vitest": "^3.2.4",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.7.52"
+    "@hyperframes/producer": "0.7.54"
   },
   "peerDependencies": {
     "react": "19",

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

@@ -0,0 +1,86 @@
+// @vitest-environment happy-dom
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it } from "vitest";
+import type { DomEditSelection } from "./domEditing";
+import type { OverlayRect } from "./domEditOverlayGeometry";
+import { DomEditCropHandles } from "./DomEditCropHandles";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+afterEach(() => {
+  document.body.innerHTML = "";
+});
+
+const overlayRect: OverlayRect = {
+  left: 0,
+  top: 0,
+  width: 200,
+  height: 100,
+  editScaleX: 1,
+  editScaleY: 1,
+};
+
+function selectionFor(el: HTMLElement): DomEditSelection {
+  return { element: el, id: el.id, selector: `#${el.id}` } as unknown as DomEditSelection;
+}
+
+function makeEl(id: string, clip: string): HTMLElement {
+  const el = document.createElement("div");
+  el.id = id;
+  if (clip) el.style.setProperty("clip-path", clip);
+  document.body.append(el);
+  return el;
+}
+
+function render(el: HTMLElement): { root: Root; rerender: (next: HTMLElement) => void } {
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  const draw = (target: HTMLElement) =>
+    act(() => {
+      root.render(
+        <DomEditCropHandles
+          selection={selectionFor(target)}
+          overlayRect={overlayRect}
+          onStyleCommit={() => undefined}
+        />,
+      );
+    });
+  draw(el);
+  return { root, rerender: draw };
+}
+
+// Regression: the deselect restore used a ref recomputed from RENDER state — on
+// a direct A→B selection switch, state re-syncs to B before A's effect cleanup
+// runs, so A used to get B's crop string (or lose its crop entirely). The
+// restore value must be owned by A's own lift effect / crop gesture.
+describe("DomEditCropHandles clip lift/restore", () => {
+  it("lifts on select and restores the inline clip verbatim on unmount", () => {
+    const a = makeEl("a", "inset(16px round 12px)");
+    const { root } = render(a);
+    expect(a.style.getPropertyValue("clip-path")).toBe("none");
+    act(() => root.unmount());
+    expect(a.style.getPropertyValue("clip-path")).toBe("inset(16px round 12px)");
+  });
+
+  it("restores A's own clip when switching directly to B", () => {
+    const a = makeEl("a", "inset(16px)");
+    const b = makeEl("b", "inset(40px 8px 4px 2px)");
+    const { root, rerender } = render(a);
+    rerender(b);
+    // A got ITS clip back, not B's (and not removed); B is now lifted.
+    expect(a.style.getPropertyValue("clip-path")).toBe("inset(16px)");
+    expect(b.style.getPropertyValue("clip-path")).toBe("none");
+    act(() => root.unmount());
+    expect(b.style.getPropertyValue("clip-path")).toBe("inset(40px 8px 4px 2px)");
+  });
+
+  it("never lifts an uneditable clip and leaves it untouched across select/deselect", () => {
+    const a = makeEl("a", "circle(50% at 50% 50%)");
+    const { root } = render(a);
+    expect(a.style.getPropertyValue("clip-path")).toBe("circle(50% at 50% 50%)");
+    act(() => root.unmount());
+    expect(a.style.getPropertyValue("clip-path")).toBe("circle(50% at 50% 50%)");
+  });
+});

package/src/components/editor/DomEditCropHandles.tsx

@@ -4,9 +4,11 @@ import type { OverlayRect } from "./domEditOverlayGeometry";
 import {
   type CropEdge,
   cropRectFromInsets,
+  readElementCropFrame,
   readElementCropInsets,
   resolveCropInsetFromEdgeDrag,
   resolveCropInsetFromMoveDrag,
+  rotateDeltaIntoFrame,
 } from "./domEditOverlayCrop";
 import { buildInsetClipPathSides, type ClipPathInsetSides } from "./clipPathHelpers";
 
@@ -17,6 +19,10 @@ interface CropGestureState {
   startY: number;
   startInsets: ClipPathInsetSides;
   didMove: boolean;
+  /** Element frame captured at gesture start: pointer deltas rotate into it. */
+  angleDeg: number;
+  scaleX: number;
+  scaleY: number;
 }
 
 interface DomEditCropHandlesProps {
@@ -77,36 +83,23 @@ export function DomEditCropHandles({
 }: DomEditCropHandlesProps) {
   const gestureRef = useRef<CropGestureState | null>(null);
   const [dragging, setDragging] = useState(false);
-  const [state, setState] = useState(() => {
-    const parsed = readElementCropInsets(selection.element);
-    return {
-      element: selection.element,
-      insets: {
-        top: parsed.top,
-        right: parsed.right,
-        bottom: parsed.bottom,
-        left: parsed.left,
-      } as ClipPathInsetSides,
-      radius: parsed.radius,
-    };
-  });
+  // readElementCropInsets returns null for a clip this tool can't represent
+  // (circle/polygon/non-px inset): the crop UI must fully stand down for that
+  // element — no lift, no handles — or select+deselect replaces the authored
+  // clip with an inset (or deletes it).
+  const cropStateFor = (element: HTMLElement) => {
+    const parsed = readElementCropInsets(element);
+    const { radius, ...insets } = parsed ?? { top: 0, right: 0, bottom: 0, left: 0, radius: 0 };
+    return { element, croppable: parsed !== null, insets, radius };
+  };
+  const [state, setState] = useState(() => cropStateFor(selection.element));
 
   // Re-sync when the selection targets a different element (reselect, or an
   // undo/redo that re-keys the node): read its committed crop before the lift
   // effect runs. Read inside the guard so a drag's per-frame setState doesn't
   // re-run getComputedStyle every frame.
   if (state.element !== selection.element) {
-    const liveInsets = readElementCropInsets(selection.element);
-    setState({
-      element: selection.element,
-      insets: {
-        top: liveInsets.top,
-        right: liveInsets.right,
-        bottom: liveInsets.bottom,
-        left: liveInsets.left,
-      },
-      radius: liveInsets.radius,
-    });
+    setState(cropStateFor(selection.element));
   }
 
   const hasCrop =
@@ -115,31 +108,51 @@ export function DomEditCropHandles({
     state.insets.bottom > 0 ||
     state.insets.left > 0;
 
-  // Latest committed crop — re-applied to the element when the selection drops.
-  const committedRef = useRef<string | null>(null);
-  committedRef.current = hasCrop ? buildInsetClipPathSides(state.insets, state.radius) : null;
-
   // Lift the clip while the element is selected so the full content shows and the
-  // cropped-away area can be dimmed; restore the committed crop on deselect. Keyed
-  // on the element so switching selections restores the previous one. Runs after
-  // render, so the state re-sync above still reads the element's real committed clip.
+  // cropped-away area can be dimmed; restore on deselect. Keyed on the element so
+  // switching selections restores the previous one. Runs after render, so the
+  // state re-sync above still reads the element's real committed clip. Restore
+  // prefers the pre-lift inline value VERBATIM — the rebuilt inset only replaces
+  // it after a crop gesture actually commits, so a mere select+deselect can
+  // never reformat (or drop) what the author wrote. Both refs are written only
+  // by THIS element's lift effect and crop gestures — never derived from render
+  // state, which by cleanup time already describes the NEXT selection (a direct
+  // A→B switch re-syncs state to B before A's cleanup runs).
   const liftedRef = useRef(false);
+  const preLiftInlineClipRef = useRef("");
+  // null = no crop gesture committed this selection; "" = committed a crop
+  // removal; anything else = the exact committed clip-path value.
+  const committedClipRef = useRef<string | null>(null);
   useEffect(() => {
     const el = selection.element;
+    if (readElementCropInsets(el) === null) return;
+    preLiftInlineClipRef.current = el.style.getPropertyValue("clip-path");
+    committedClipRef.current = null;
     el.style.setProperty("clip-path", "none");
     liftedRef.current = true;
     return () => {
       liftedRef.current = false;
-      if (committedRef.current) el.style.setProperty("clip-path", committedRef.current);
+      const committed = committedClipRef.current;
+      const restore = committed !== null ? committed || null : preLiftInlineClipRef.current || null;
+      if (restore) el.style.setProperty("clip-path", restore);
       else el.style.removeProperty("clip-path");
     };
   }, [selection.element]);
 
-  const scaleX = overlayRect.editScaleX > 0 ? overlayRect.editScaleX : 1;
-  const scaleY = overlayRect.editScaleY > 0 ? overlayRect.editScaleY : 1;
-  const width = overlayRect.width / scaleX;
-  const height = overlayRect.height / scaleY;
-  const cropRect = cropRectFromInsets(overlayRect, state.insets, scaleX, scaleY);
+  // The crop applies in the element's LOCAL frame (clip-path precedes the
+  // transform), so all crop UI is drawn inside a container rotated with the
+  // element — on a rotated element an axis-aligned dim visually "straightens"
+  // it by masking the rotated corners.
+  const frame = readElementCropFrame(selection.element, overlayRect);
+  const width = frame.width / frame.scaleX; // element CSS px
+  const height = frame.height / frame.scaleY;
+  // Crop rect in FRAME-LOCAL coordinates (origin = frame top-left).
+  const cropRect = cropRectFromInsets(
+    { left: 0, top: 0, width: frame.width, height: frame.height },
+    state.insets,
+    frame.scaleX,
+    frame.scaleY,
+  );
 
   const startCropGesture = (edge: CropEdge | "move", event: ReactPointerEvent<HTMLElement>) => {
     if (!onStyleCommit) return;
@@ -153,6 +166,9 @@ export function DomEditCropHandles({
       startY: event.clientY,
       startInsets: state.insets,
       didMove: false,
+      angleDeg: frame.angleDeg,
+      scaleX: frame.scaleX,
+      scaleY: frame.scaleY,
     };
     // Clip is already lifted by the selection effect; just flag the drag so the
     // rule-of-thirds grid shows.
@@ -164,12 +180,17 @@ export function DomEditCropHandles({
     if (!gesture || gesture.pointerId !== event.pointerId) return;
     event.preventDefault();
     event.stopPropagation();
+    const local = rotateDeltaIntoFrame(
+      event.clientX - gesture.startX,
+      event.clientY - gesture.startY,
+      gesture.angleDeg,
+    );
     const drag = {
       startInsets: gesture.startInsets,
-      deltaX: event.clientX - gesture.startX,
-      deltaY: event.clientY - gesture.startY,
-      scaleX,
-      scaleY,
+      deltaX: local.deltaX,
+      deltaY: local.deltaY,
+      scaleX: gesture.scaleX,
+      scaleY: gesture.scaleY,
     };
     const nextInsets =
       gesture.edge === "move"
@@ -196,9 +217,19 @@ export function DomEditCropHandles({
     const reLift = () => {
       if (liftedRef.current) el.style.setProperty("clip-path", "none");
     };
-    void Promise.resolve(
-      onStyleCommit?.("clip-path", buildInsetClipPathSides(state.insets, state.radius)),
-    ).then(reLift, reLift);
+    const committedValue = buildInsetClipPathSides(state.insets, state.radius);
+    const cropped =
+      state.insets.top > 0 ||
+      state.insets.right > 0 ||
+      state.insets.bottom > 0 ||
+      state.insets.left > 0;
+    void Promise.resolve(onStyleCommit?.("clip-path", committedValue)).then(() => {
+      // Only a landed commit makes the rebuilt inset the restore value; a
+      // failed one keeps restoring the pre-lift clip. Store the value itself —
+      // by deselect time, render state describes the next selection.
+      committedClipRef.current = cropped ? committedValue : "";
+      reLift();
+    }, reLift);
   };
 
   const cancelCropGesture = (event: ReactPointerEvent<HTMLElement>) => {
@@ -212,25 +243,32 @@ export function DomEditCropHandles({
     setState((prev) => ({ ...prev, insets: gesture.startInsets }));
   };
 
+  // Uneditable clip (circle/polygon/non-px inset): the element renders exactly
+  // as authored and the crop tool shows nothing. All hooks above stay mounted.
+  if (!state.croppable) return null;
+
   return (
-    <>
+    <div
+      data-dom-edit-crop-frame="true"
+      className="pointer-events-none absolute"
+      style={{
+        left: frame.left,
+        top: frame.top,
+        width: frame.width,
+        height: frame.height,
+        transform: frame.angleDeg !== 0 ? `rotate(${frame.angleDeg}deg)` : undefined,
+      }}
+    >
       {/* Dim the cropped-away area whenever the element is cropped and selected,
-          so the hidden content is visible (ghosted) without dragging. */}
+          so the hidden content is visible (ghosted) without dragging. Clipped to
+          the element's own (rotated) box. */}
       {hasCrop && (
-        <div
-          className="pointer-events-none absolute overflow-hidden"
-          style={{
-            left: overlayRect.left,
-            top: overlayRect.top,
-            width: overlayRect.width,
-            height: overlayRect.height,
-          }}
-        >
+        <div className="pointer-events-none absolute inset-0 overflow-hidden">
           <div
             className="absolute"
             style={{
-              left: cropRect.left - overlayRect.left,
-              top: cropRect.top - overlayRect.top,
+              left: cropRect.left,
+              top: cropRect.top,
               width: cropRect.width,
               height: cropRect.height,
               boxShadow: "0 0 0 100000px rgba(8, 8, 12, 0.6)",
@@ -312,6 +350,6 @@ export function DomEditCropHandles({
           />
         );
       })}
-    </>
+    </div>
   );
 }

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

@@ -535,6 +535,47 @@ describe("resolveDomEditResizeGesture", () => {
     });
   });
 
+  it("divides the cursor delta by the element's content scale (rescaled element)", () => {
+    // Element renders at 2x via a GSAP scale: a 30px cursor delta must grow the
+    // CSS box by only 15px so the RENDERED box tracks the pointer 1:1.
+    const next = resolveDomEditResizeGesture({
+      originWidth: 480, // 240 css x 2 content scale (overlay px at editScale 1)
+      originHeight: 240,
+      actualWidth: 240,
+      actualHeight: 120,
+      scaleX: 1,
+      scaleY: 1,
+      contentScaleX: 2,
+      contentScaleY: 2,
+      dx: 30,
+      dy: 12,
+      uniform: false,
+    });
+    expect(next.width).toBe(255);
+    expect(next.height).toBe(126);
+    // The overlay box keeps tracking the raw cursor.
+    expect(next.overlayWidth).toBe(510);
+    expect(next.overlayHeight).toBe(252);
+  });
+
+  it("treats a missing/invalid content scale as 1 (unscaled element)", () => {
+    const next = resolveDomEditResizeGesture({
+      originWidth: 240,
+      originHeight: 120,
+      actualWidth: 240,
+      actualHeight: 120,
+      scaleX: 1,
+      scaleY: 1,
+      contentScaleX: 0,
+      contentScaleY: Number.NaN,
+      dx: 30,
+      dy: 12,
+      uniform: false,
+    });
+    expect(next.width).toBe(270);
+    expect(next.height).toBe(132);
+  });
+
   it("snaps width and height to the same value when Shift is held", () => {
     expect(
       resolveDomEditResizeGesture({

package/src/components/editor/DomEditOverlay.tsx

@@ -1,4 +1,5 @@
 import { memo, useEffect, useMemo, useRef, useState, type RefObject } from "react";
+import { getPreviewTargetFromPointer } from "../../utils/studioPreviewHelpers";
 import { type DomEditSelection } from "./domEditing";
 import type { PreviewMouseDownOptions } from "../../hooks/usePreviewInteraction";
 import { useMarqueeGestures } from "./marqueeCommit";
@@ -305,8 +306,23 @@ export const DomEditOverlay = memo(function DomEditOverlay({
     const target = event.target as HTMLElement | null;
     if (target?.closest('[data-dom-edit-selection-box="true"]')) return;
 
-    // Start marquee if clicking on empty canvas (no element under pointer)
+    // Start marquee if clicking on empty canvas (no element under pointer).
+    // The hover selection is an ASYNC cache: on a fast click (or when the
+    // pointer was already resting over an element) it can still be empty while
+    // an element IS under the pointer — starting a marquee here would swallow
+    // the selection mousedown and the click would silently select nothing.
+    // Confirm emptiness with a fresh SYNCHRONOUS hit-test before committing.
     if (!hoverSelectionRef.current && onMarqueeSelectRef.current && compRect.width > 0) {
+      const iframe = iframeRef.current;
+      const freshTarget = iframe
+        ? getPreviewTargetFromPointer(
+            iframe,
+            event.clientX,
+            event.clientY,
+            activeCompositionPathRef.current,
+          )
+        : null;
+      if (freshTarget) return;
       const overlayEl = overlayRef.current;
       if (overlayEl) {
         const oRect = overlayEl.getBoundingClientRect();

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

@@ -1,8 +1,12 @@
 import { describe, expect, it } from "vitest";
 import {
   cropRectFromInsets,
+  hugRectForElement,
+  readElementCropFrame,
+  readElementCropInsets,
   resolveCropInsetFromEdgeDrag,
   resolveCropInsetFromMoveDrag,
+  rotateDeltaIntoFrame,
 } from "./domEditOverlayCrop";
 
 describe("resolveCropInsetFromEdgeDrag", () => {
@@ -104,3 +108,136 @@ describe("cropRectFromInsets", () => {
     expect(r.height).toBe(0);
   });
 });
+
+describe("readElementCropInsets tri-state", () => {
+  // Regression: a clip-path the crop tool can't represent (circle/polygon/
+  // non-px inset) used to parse to ZEROS — indistinguishable from "no crop" —
+  // so selecting lifted the clip and deselecting removed/replaced it: the
+  // authored circle clip was silently destroyed by a mere select+deselect.
+  const fakeEl = (inlineClip: string) =>
+    ({
+      style: { getPropertyValue: (p: string) => (p === "clip-path" ? inlineClip : "") },
+      ownerDocument: { defaultView: { getComputedStyle: () => ({ clipPath: "none" }) } },
+    }) as unknown as HTMLElement;
+
+  it("zeros for no clip", () => {
+    expect(readElementCropInsets(fakeEl(""))).toEqual({
+      top: 0,
+      right: 0,
+      bottom: 0,
+      left: 0,
+      radius: 0,
+    });
+  });
+
+  it("parses a px inset", () => {
+    expect(readElementCropInsets(fakeEl("inset(16px round 12px)"))).toEqual({
+      top: 16,
+      right: 16,
+      bottom: 16,
+      left: 16,
+      radius: 12,
+    });
+  });
+
+  it("null for a circle clip (uneditable, must not be lifted)", () => {
+    expect(readElementCropInsets(fakeEl("circle(50% at 50% 50%)"))).toBeNull();
+  });
+
+  it("null for a non-px inset (uneditable, must not be lifted)", () => {
+    expect(readElementCropInsets(fakeEl("inset(10%)"))).toBeNull();
+  });
+
+  it("hugRectForElement passes the rect through for uneditable clips", () => {
+    const rect = { left: 1, top: 2, width: 30, height: 40, editScaleX: 1, editScaleY: 1 };
+    expect(hugRectForElement(rect, fakeEl("circle(50%)"))).toEqual(rect);
+  });
+});
+
+// Regression: crop UI drawn on the axis-aligned bounding box visually
+// "straightens" a rotated element — the dim masks the rotated corners. The
+// frame gives the element's own box + rotation so the UI rotates with it.
+describe("readElementCropFrame", () => {
+  const overlayRect = { left: 100, top: 50, width: 220, height: 130, editScaleX: 1, editScaleY: 1 };
+
+  const fakeEl = (transform: string, offsetWidth = 200, offsetHeight = 100) =>
+    ({
+      offsetWidth,
+      offsetHeight,
+      ownerDocument: { defaultView: { getComputedStyle: () => ({ transform }) } },
+    }) as unknown as HTMLElement;
+
+  it("identity transform → the axis-aligned overlay rect", () => {
+    expect(readElementCropFrame(fakeEl("none"), overlayRect)).toEqual({
+      angleDeg: 0,
+      left: 100,
+      top: 50,
+      width: 220,
+      height: 130,
+      scaleX: 1,
+      scaleY: 1,
+    });
+  });
+
+  it("rotated element → its own box, centered on the AABB, with the angle", () => {
+    // rotate(30deg): matrix(cos, sin, -sin, cos, tx, ty)
+    const cos = Math.cos(Math.PI / 6);
+    const sin = Math.sin(Math.PI / 6);
+    const frame = readElementCropFrame(
+      fakeEl(`matrix(${cos}, ${sin}, ${-sin}, ${cos}, 10, 20)`),
+      overlayRect,
+    );
+    expect(frame.angleDeg).toBeCloseTo(30, 3);
+    expect(frame.width).toBeCloseTo(200, 3);
+    expect(frame.height).toBeCloseTo(100, 3);
+    // centered on the AABB center (210, 115)
+    expect(frame.left + frame.width / 2).toBeCloseTo(210, 3);
+    expect(frame.top + frame.height / 2).toBeCloseTo(115, 3);
+    expect(frame.scaleX).toBeCloseTo(1, 3);
+  });
+
+  it("scaled element → scale factored into px-per-element-px", () => {
+    const frame = readElementCropFrame(fakeEl("matrix(1.5, 0, 0, 2, 0, 0)"), overlayRect);
+    expect(frame.angleDeg).toBe(0);
+    expect(frame.scaleX).toBeCloseTo(1.5, 3);
+    expect(frame.scaleY).toBeCloseTo(2, 3);
+    expect(frame.width).toBeCloseTo(300, 3);
+    expect(frame.height).toBeCloseTo(200, 3);
+  });
+
+  it("3D transform falls back to the axis-aligned frame", () => {
+    const frame = readElementCropFrame(
+      fakeEl("matrix3d(1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1)"),
+      overlayRect,
+    );
+    expect(frame).toEqual({
+      angleDeg: 0,
+      left: 100,
+      top: 50,
+      width: 220,
+      height: 130,
+      scaleX: 1,
+      scaleY: 1,
+    });
+  });
+});
+
+describe("rotateDeltaIntoFrame", () => {
+  it("passes deltas through at 0deg", () => {
+    expect(rotateDeltaIntoFrame(10, 5, 0)).toEqual({ deltaX: 10, deltaY: 5 });
+  });
+
+  it("rotates a screen delta into a 90deg-rotated frame", () => {
+    // Element rotated +90°: dragging DOWN on screen moves along the element's +x.
+    const { deltaX, deltaY } = rotateDeltaIntoFrame(0, 10, 90);
+    expect(deltaX).toBeCloseTo(10, 6);
+    expect(deltaY).toBeCloseTo(0, 6);
+  });
+
+  it("round-trips a 30deg rotation", () => {
+    const local = rotateDeltaIntoFrame(7, -3, 30);
+    const back = rotateDeltaIntoFrame(local.deltaX, local.deltaY, -30);
+    expect(back.deltaX).toBeCloseTo(7, 6);
+    expect(back.deltaY).toBeCloseTo(-3, 6);
+  });
+});