@hyperframes/studio 0.7.38 → 0.7.39

package/src/components/editor/DomEditOverlay.tsx

@@ -1,5 +1,4 @@
 import { memo, useEffect, useMemo, useRef, useState, type RefObject } from "react";
-import { useMountEffect } from "../../hooks/useMountEffect";
 import { type DomEditSelection } from "./domEditing";
 import type { PreviewMouseDownOptions } from "../../hooks/usePreviewInteraction";
 import { useMarqueeGestures } from "./marqueeCommit";
@@ -21,6 +20,12 @@ import { createDomEditOverlayGestureHandlers } from "./useDomEditOverlayGestures
 import { SnapGuideOverlay, type SnapGuidesState } from "./SnapGuideOverlay";
 import { GridOverlay } from "./GridOverlay";
 import type { GestureRecordingState } from "./GestureRecordControl";
+import { DomEditCropHandles } from "./DomEditCropHandles";
+import { DomEditRotateHandle } from "./DomEditRotateHandle";
+import { hugRectForElement } from "./domEditOverlayCrop";
+import { useCropOverlay } from "../../hooks/useCropMode";
+import { readDomEditSelectionShapeStyles, resolveBoxChromeClass } from "./domEditOverlayShape";
+import { useDomEditCompositionRect } from "./useDomEditCompositionRect";
 
 // Re-exports for external consumers — preserving existing import paths.
 export {
@@ -69,6 +74,9 @@ interface DomEditOverlayProps {
     next: { width: number; height: number },
   ) => Promise<void> | void;
   onRotationCommit: (selection: DomEditSelection, next: { angle: number }) => Promise<void> | void;
+  onStyleCommit?: (property: string, value: string) => Promise<void> | void;
+  cropMode?: boolean;
+  onCropModeChange?: (active: boolean) => void;
   gridVisible?: boolean;
   gridSpacing?: number;
   recordingState?: GestureRecordingState;
@@ -96,6 +104,9 @@ export const DomEditOverlay = memo(function DomEditOverlay({
   onGroupPathOffsetCommit,
   onBoxSizeCommit,
   onRotationCommit,
+  onStyleCommit,
+  cropMode = false,
+  onCropModeChange,
   onMarqueeSelect,
 }: DomEditOverlayProps) {
   const overlayRef = useRef<HTMLDivElement | null>(null);
@@ -103,29 +114,7 @@ export const DomEditOverlay = memo(function DomEditOverlay({
   const onMarqueeSelectRef = useRef(onMarqueeSelect);
   onMarqueeSelectRef.current = onMarqueeSelect;
 
-  // fallow-ignore-next-line complexity
-  const selectionShapeStyles = (() => {
-    const fallback = {
-      borderRadius: 8 as string | number,
-      clipPath: undefined as string | undefined,
-    };
-    if (!selection?.element) return fallback;
-    try {
-      const tag = selection.element.tagName.toLowerCase();
-      if (tag === "svg" || tag === "img" || tag === "video" || tag === "canvas") return fallback;
-      const win = selection.element.ownerDocument.defaultView;
-      if (!win) return fallback;
-      const cs = win.getComputedStyle(selection.element);
-      const br = cs.borderRadius;
-      const cp = cs.clipPath;
-      return {
-        borderRadius: br && br !== "0px" ? br : 4,
-        clipPath: cp && cp !== "none" ? cp : undefined,
-      };
-    } catch {
-      return fallback;
-    }
-  })();
+  const selectionShapeStyles = readDomEditSelectionShapeStyles(selection);
   const gestureRef = useRef<GestureState | null>(null);
   const groupGestureRef = useRef<GroupGestureState | null>(null);
   const blockedMoveRef = useRef<BlockedMoveState | null>(null);
@@ -151,6 +140,8 @@ export const DomEditOverlay = memo(function DomEditOverlay({
   onBoxSizeCommitRef.current = onBoxSizeCommit;
   const onRotationCommitRef = useRef(onRotationCommit);
   onRotationCommitRef.current = onRotationCommit;
+  const onStyleCommitRef = useRef(onStyleCommit);
+  onStyleCommitRef.current = onStyleCommit;
   const onBlockedMoveRef = useRef(onBlockedMove);
   onBlockedMoveRef.current = onBlockedMove;
   const onManualDragStartRef = useRef(onManualDragStart);
@@ -181,49 +172,18 @@ export const DomEditOverlay = memo(function DomEditOverlay({
     rafPausedRef,
   });
 
-  const [compRect, setCompRect] = useState({
-    left: 0,
-    top: 0,
-    width: 0,
-    height: 0,
-    scaleX: 1,
-    scaleY: 1,
-  });
-  useMountEffect(() => {
-    let frame = 0;
-    // fallow-ignore-next-line complexity
-    const update = () => {
-      frame = requestAnimationFrame(update);
-      const iframe = iframeRef.current;
-      const overlayEl = overlayRef.current;
-      if (!iframe || !overlayEl) return;
-      const iRect = iframe.getBoundingClientRect();
-      const oRect = overlayEl.getBoundingClientRect();
-      const left = iRect.left - oRect.left;
-      const top = iRect.top - oRect.top;
-      if (iRect.width <= 0 || iRect.height <= 0) return;
-      const doc = iframe.contentDocument;
-      const root = doc?.querySelector<HTMLElement>("[data-composition-id]") ?? doc?.documentElement;
-      const dw = Number.parseFloat(root?.getAttribute("data-width") ?? "");
-      const dh = Number.parseFloat(root?.getAttribute("data-height") ?? "");
-      const scaleX = dw > 0 ? iRect.width / dw : 1;
-      const scaleY = dh > 0 ? iRect.height / dh : 1;
-      setCompRect((prev) => {
-        if (
-          Math.abs(prev.left - left) < 0.5 &&
-          Math.abs(prev.top - top) < 0.5 &&
-          Math.abs(prev.width - iRect.width) < 0.5 &&
-          Math.abs(prev.height - iRect.height) < 0.5 &&
-          Math.abs(prev.scaleX - scaleX) < 0.001 &&
-          Math.abs(prev.scaleY - scaleY) < 0.001
-        )
-          return prev;
-        return { left, top, width: iRect.width, height: iRect.height, scaleX, scaleY };
-      });
-    };
-    frame = requestAnimationFrame(update);
-    return () => cancelAnimationFrame(frame);
+  const compRect = useDomEditCompositionRect({ iframeRef, overlayRef });
+
+  const { hasCropInsets, cropOutlineInsetPx } = useCropOverlay({
+    selection,
+    groupCount: groupSelections.length,
+    cropMode,
+    onCropModeChange,
+    overlayRect,
   });
+  // Inset crops draw their own outline child; other clip shapes keep the raw mirror.
+  const boxClipPath = hasCropInsets ? undefined : selectionShapeStyles.clipPath;
+  const boxChromeClass = resolveBoxChromeClass(Boolean(cropOutlineInsetPx), boxClipPath);
 
   // Off-canvas element indicators — dashed outlines for elements positioned
   // outside the composition bounds so users can find them.
@@ -251,8 +211,10 @@ export const DomEditOverlay = memo(function DomEditOverlay({
       if (!isElementComputedVisible(item.element)) continue;
       // Groups use their members' union (where they actually render), so a group
       // whose members sit inside the canvas isn't flagged off-canvas by a stale
-      // wrapper box.
-      const r = groupAwareOverlayRect(overlay, iframe, item.element);
+      // wrapper box. Crop-hug the result so an inset crop that keeps the visible
+      // part on-canvas doesn't flag the element either.
+      const base = groupAwareOverlayRect(overlay, iframe, item.element);
+      const r = base ? { ...base, ...hugRectForElement(base, item.element) } : null;
       if (!r) continue;
       // Any edge crossing the composition border → gray-zone indicator (the
       // in-canvas portion is clipped away below, so only the sliver shows).
@@ -325,6 +287,11 @@ export const DomEditOverlay = memo(function DomEditOverlay({
 
   const handleOverlayMouseDown = (event: React.MouseEvent<HTMLDivElement>) => {
     if (!allowCanvasMovement) return;
+    if (cropMode) {
+      event.preventDefault();
+      event.stopPropagation();
+      return;
+    }
     if (suppressNextOverlayMouseDownRef.current) {
       suppressNextOverlayMouseDownRef.current = false;
       suppressNextBoxMouseDownRef.current = false;
@@ -348,6 +315,13 @@ export const DomEditOverlay = memo(function DomEditOverlay({
   // fallow-ignore-next-line complexity
   const handleOverlayPointerDown = (event: React.PointerEvent<HTMLDivElement>) => {
     if (!allowCanvasMovement || event.button !== 0) return;
+    if (cropMode) {
+      // Reaching here = click outside the element (crop UI swallows its own) — exit crop mode.
+      event.preventDefault();
+      event.stopPropagation();
+      onCropModeChange?.(false);
+      return;
+    }
     if (event.shiftKey) {
       // Use the already-updated hover selection rather than re-resolving async
       const candidate = hoverSelectionRef.current;
@@ -395,8 +369,17 @@ export const DomEditOverlay = memo(function DomEditOverlay({
     }
   };
 
+  // Selection re-resolves (and the box re-keys) on every click, so native
+  // dblclick never fires on the box — detect double-click by pointerdown
+  // timestamp (a no-move drag gesture suppresses the click event entirely).
+  const lastBoxPointerDownAtRef = useRef(0);
   const handleBoxClick = (event: React.MouseEvent<HTMLDivElement>) => {
     if (!allowCanvasMovement) return;
+    if (cropMode) {
+      event.preventDefault();
+      event.stopPropagation();
+      return;
+    }
     if (gestureRef.current || groupGestureRef.current) return;
     if (suppressNextBoxClickRef.current) {
       suppressNextBoxClickRef.current = false;
@@ -426,22 +409,17 @@ export const DomEditOverlay = memo(function DomEditOverlay({
       }
       onPointerDown={handleOverlayPointerDown}
       onMouseDown={handleOverlayMouseDown}
-      onPointerMove={marquee.onPointerMove}
+      onPointerMove={cropMode ? undefined : marquee.onPointerMove}
       onPointerLeave={() => onCanvasPointerLeaveRef.current()}
-      onPointerUp={marquee.onPointerUp}
-      onPointerCancel={marquee.onPointerCancel}
+      onPointerUp={cropMode ? undefined : marquee.onPointerUp}
+      onPointerCancel={cropMode ? undefined : marquee.onPointerCancel}
     >
       {hoverSelection && hoverRect && compRect.width > 0 && (
         <div
           aria-hidden="true"
           data-dom-edit-hover-box="true"
-          className="pointer-events-none absolute rounded-md border border-studio-accent/80 bg-studio-accent/5 shadow-[0_0_0_1px_rgba(60,230,172,0.25)]"
-          style={{
-            left: hoverRect.left,
-            top: hoverRect.top,
-            width: hoverRect.width,
-            height: hoverRect.height,
-          }}
+          className="pointer-events-none absolute rounded-md border border-studio-accent/80 shadow-[0_0_0_1px_rgba(60,230,172,0.25)]"
+          style={hugRectForElement(hoverRect, hoverSelection.element)}
         />
       )}
       {hasGroupSelection && groupOverlayItems.length > 1 && groupBounds && compRect.width > 0 && (
@@ -450,7 +428,7 @@ export const DomEditOverlay = memo(function DomEditOverlay({
             <div
               key={item.key}
               aria-hidden="true"
-              className="pointer-events-none absolute rounded-xl border border-studio-accent/70 bg-studio-accent/[0.03]"
+              className="pointer-events-none absolute rounded-xl border border-studio-accent/70"
               style={{
                 left: item.rect.left,
                 top: item.rect.top,
@@ -461,7 +439,7 @@ export const DomEditOverlay = memo(function DomEditOverlay({
           ))}
           <div
             data-dom-edit-selection-box="true"
-            className="pointer-events-auto absolute rounded-xl border border-studio-accent bg-studio-accent/5 shadow-[0_0_0_1px_rgba(60,230,172,0.3)]"
+            className="pointer-events-auto absolute rounded-xl border border-studio-accent shadow-[0_0_0_1px_rgba(60,230,172,0.3)]"
             style={{
               left: groupBounds.left,
               top: groupBounds.top,
@@ -480,49 +458,49 @@ export const DomEditOverlay = memo(function DomEditOverlay({
       )}
       {!hasGroupSelection && selection && overlayRect && compRect.width > 0 && (
         <>
-          {allowCanvasMovement && selection.capabilities.canApplyManualRotation && (
-            <div
-              className="pointer-events-none absolute"
-              style={{
-                left: overlayRect.left + overlayRect.width / 2,
-                top: overlayRect.top - 34,
-                width: 28,
-                height: 34,
-                transform: "translateX(-50%)",
+          {allowCanvasMovement && !cropMode && selection.capabilities.canApplyManualRotation && (
+            <DomEditRotateHandle
+              overlayRect={overlayRect}
+              cropOutlineInsetPx={cropOutlineInsetPx}
+              onStartRotate={(e) => {
+                e.stopPropagation();
+                gestures.startGesture("rotate", e);
               }}
-            >
-              <div className="absolute left-1/2 top-3 bottom-0 w-px -translate-x-1/2 bg-studio-accent/60" />
-              <button
-                type="button"
-                className="pointer-events-auto absolute left-1/2 top-0 h-3 w-3 -translate-x-1/2 rounded-full border border-studio-accent bg-studio-accent p-0 shadow-[0_0_0_2px_rgba(60,230,172,0.18)]"
-                style={{ cursor: "grab", touchAction: "none" }}
-                title="Rotate"
-                aria-label="Rotate selection"
-                onPointerDown={(e) => {
-                  e.stopPropagation();
-                  gestures.startGesture("rotate", e);
-                }}
-              />
-            </div>
+            />
           )}
           <div
             key={selectionKey}
             ref={boxRef}
             data-dom-edit-selection-box="true"
-            className={`pointer-events-auto absolute rounded-md ${selectionShapeStyles.clipPath ? "shadow-[inset_0_0_0_2px_rgba(60,230,172,0.6)]" : "border border-studio-accent/80 shadow-[0_0_0_1px_rgba(60,230,172,0.25)]"} bg-studio-accent/5`}
+            className={`pointer-events-auto absolute rounded-md ${boxChromeClass}`}
             style={{
               left: overlayRect.left,
               top: overlayRect.top,
               width: overlayRect.width,
               height: overlayRect.height,
-              clipPath: selectionShapeStyles.clipPath,
+              clipPath: boxClipPath,
               cursor:
-                allowCanvasMovement && selection.capabilities.canApplyManualOffset
+                allowCanvasMovement && !cropMode && selection.capabilities.canApplyManualOffset
                   ? "move"
                   : "default",
             }}
             onPointerDown={(e) => {
+              if (cropMode) {
+                e.preventDefault();
+                e.stopPropagation();
+                return;
+              }
               if (!allowCanvasMovement || e.shiftKey) return;
+              const now = Date.now();
+              const isDoubleClick = now - lastBoxPointerDownAtRef.current < 400;
+              lastBoxPointerDownAtRef.current = now;
+              if (isDoubleClick && onCropModeChange && selection.capabilities.canCrop) {
+                lastBoxPointerDownAtRef.current = 0;
+                e.preventDefault();
+                e.stopPropagation();
+                onCropModeChange(true);
+                return;
+              }
               if (selection.capabilities.canApplyManualOffset) {
                 gestures.startGesture("drag", e);
                 return;
@@ -540,10 +518,28 @@ export const DomEditOverlay = memo(function DomEditOverlay({
             onMouseDown={suppressBoxMouseDown}
             onClick={handleBoxClick}
           >
-            {allowCanvasMovement && selection.capabilities.canApplyManualSize && (
+            {cropOutlineInsetPx && (
+              <div
+                className="pointer-events-none absolute rounded-md border border-studio-accent/80 shadow-[0_0_0_1px_rgba(60,230,172,0.25)]"
+                style={{
+                  left: cropOutlineInsetPx.left,
+                  top: cropOutlineInsetPx.top,
+                  right: cropOutlineInsetPx.right,
+                  bottom: cropOutlineInsetPx.bottom,
+                }}
+              />
+            )}
+            {allowCanvasMovement && !cropMode && selection.capabilities.canApplyManualSize && (
               <div
                 className="absolute -right-1.5 -bottom-1.5 w-3 h-3 rounded-sm bg-studio-accent border border-studio-accent/60"
-                style={{ cursor: "se-resize", touchAction: "none" }}
+                style={{
+                  cursor: "se-resize",
+                  touchAction: "none",
+                  ...(cropOutlineInsetPx && {
+                    right: cropOutlineInsetPx.right - 6,
+                    bottom: cropOutlineInsetPx.bottom - 6,
+                  }),
+                }}
                 onPointerDown={(e) => {
                   e.stopPropagation();
                   gestures.startGesture("resize", e);
@@ -551,6 +547,13 @@ export const DomEditOverlay = memo(function DomEditOverlay({
               />
             )}
           </div>
+          {cropMode && (
+            <DomEditCropHandles
+              selection={selection}
+              overlayRect={overlayRect}
+              onStyleCommit={onStyleCommitRef.current}
+            />
+          )}
         </>
       )}
       {childRects.length > 0 &&

package/src/components/editor/DomEditRotateHandle.tsx

@@ -0,0 +1,41 @@
+import type { PointerEvent as ReactPointerEvent } from "react";
+import type { OverlayRect } from "./domEditOverlayGeometry";
+
+/** Rotate grab-handle above the selection. Anchors to the crop outline when
+ *  the element is cropped so it stays next to what's visible on screen. */
+export function DomEditRotateHandle({
+  overlayRect,
+  cropOutlineInsetPx,
+  onStartRotate,
+}: {
+  overlayRect: OverlayRect;
+  cropOutlineInsetPx?: { top: number; right: number; bottom: number; left: number };
+  onStartRotate: (e: ReactPointerEvent<HTMLButtonElement>) => void;
+}) {
+  const inset = cropOutlineInsetPx ?? { top: 0, right: 0, bottom: 0, left: 0 };
+  const visibleLeft = overlayRect.left + inset.left;
+  const visibleWidth = Math.max(0, overlayRect.width - inset.left - inset.right);
+  const visibleTop = overlayRect.top + inset.top;
+  return (
+    <div
+      className="pointer-events-none absolute"
+      style={{
+        left: visibleLeft + visibleWidth / 2,
+        top: visibleTop - 34,
+        width: 28,
+        height: 34,
+        transform: "translateX(-50%)",
+      }}
+    >
+      <div className="absolute left-1/2 top-3 bottom-0 w-px -translate-x-1/2 bg-studio-accent/60" />
+      <button
+        type="button"
+        className="pointer-events-auto absolute left-1/2 top-0 h-3 w-3 -translate-x-1/2 rounded-full border border-studio-accent bg-studio-accent p-0 shadow-[0_0_0_2px_rgba(60,230,172,0.18)]"
+        style={{ cursor: "grab", touchAction: "none" }}
+        title="Rotate"
+        aria-label="Rotate selection"
+        onPointerDown={onStartRotate}
+      />
+    </div>
+  );
+}

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

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
 import {
+  buildInsetClipPathSides,
   buildStrokeStyleUpdates,
   buildStrokeWidthStyleUpdates,
   getClipPathInsetPx,
@@ -7,6 +8,7 @@ import {
   inferBoxShadowPreset,
   inferClipPathPreset,
   normalizePanelPxValue,
+  parseInsetClipPathSides,
   setCssFilterFunctionPx,
 } from "./PropertyPanel";
 
@@ -49,6 +51,52 @@ describe("PropertyPanel style helpers", () => {
     expect(getClipPathInsetPx("circle(50% at 50% 50%)")).toBe(0);
   });
 
+  it("builds and parses 4-side inset clip paths without losing radius", () => {
+    expect(buildInsetClipPathSides({ top: 10, right: 20, bottom: 30, left: 40 }, 6)).toBe(
+      "inset(10px 20px 30px 40px round 6px)",
+    );
+    expect(parseInsetClipPathSides("inset(10px 20px 30px 40px round 6px)")).toEqual({
+      top: 10,
+      right: 20,
+      bottom: 30,
+      left: 40,
+      radius: 6,
+    });
+  });
+
+  it("emits the single-value inset form when all sides are equal", () => {
+    expect(buildInsetClipPathSides({ top: 12.5, right: 12.5, bottom: 12.5, left: 12.5 })).toBe(
+      "inset(12.5px)",
+    );
+    expect(parseInsetClipPathSides("inset(12.5px)")).toEqual({
+      top: 12.5,
+      right: 12.5,
+      bottom: 12.5,
+      left: 12.5,
+      radius: 0,
+    });
+    expect(getClipPathInsetPx("inset(12.5px 12.5px 12.5px 12.5px)")).toBe(12.5);
+  });
+
+  it("accepts CSS shorthand inset values and rejects unsupported clip paths", () => {
+    expect(parseInsetClipPathSides("inset(10px 20px)")).toEqual({
+      top: 10,
+      right: 20,
+      bottom: 10,
+      left: 20,
+      radius: 0,
+    });
+    expect(parseInsetClipPathSides("inset(10px 20px 30px)")).toEqual({
+      top: 10,
+      right: 20,
+      bottom: 30,
+      left: 20,
+      radius: 0,
+    });
+    expect(parseInsetClipPathSides("inset(10%)")).toBeNull();
+    expect(parseInsetClipPathSides("circle(50% at 50% 50%)")).toBeNull();
+  });
+
   it("keeps stroke width and style edits visually effective", () => {
     expect(buildStrokeWidthStyleUpdates("3px", "none")).toEqual([
       ["border-width", "3px"],

package/src/components/editor/PropertyPanel.tsx

@@ -1,5 +1,5 @@
 import { memo, useEffect, useMemo, useRef, useState } from "react";
-import { Eye, Layers, Move } from "../../icons/SystemIcons";
+import { Move } from "../../icons/SystemIcons";
 import { InspectorHeaderActions } from "./InspectorHeaderActions";
 import { useStudioShellContext } from "../../contexts/StudioContext";
 import { readStudioBoxSize, readStudioPathOffset, readStudioRotation } from "./manualEdits";
@@ -27,9 +27,11 @@ import { usePlayerStore, liveTime } from "../../player";
 import { TimingSection } from "./propertyPanelTimingSection";
 import { type PropertyPanelProps } from "./propertyPanelHelpers";
 import { GestureRecordPanelButton } from "./GestureRecordControl";
+import { PropertyPanelEmptyState } from "./PropertyPanelEmptyState";
 
 // Re-export helpers that external consumers import from this module
 export {
+  buildInsetClipPathSides,
   buildStrokeStyleUpdates,
   buildStrokeWidthStyleUpdates,
   getCssFilterFunctionPx,
@@ -37,6 +39,7 @@ export {
   inferBoxShadowPreset,
   inferClipPathPreset,
   normalizePanelPxValue,
+  parseInsetClipPathSides,
   setCssFilterFunctionPx,
 } from "./propertyPanelHelpers";
 
@@ -94,6 +97,8 @@ export const PropertyPanel = memo(function PropertyPanel({
   recordingState,
   recordingDuration,
   onToggleRecording,
+  cropMode,
+  onCropModeChange,
 }: PropertyPanelProps) {
   const styles = element?.computedStyles ?? EMPTY_STYLES;
   const { showToast } = useStudioShellContext();
@@ -160,35 +165,7 @@ export const PropertyPanel = memo(function PropertyPanel({
   };
 
   if (!element) {
-    return (
-      <div className="flex h-full flex-col bg-neutral-900">
-        <div className="flex flex-1 flex-col items-center justify-center px-6 text-center">
-          {multiSelectCount > 1 ? (
-            <>
-              <Layers size={18} className="mb-3 text-neutral-600" />
-              <p className="text-sm font-medium text-neutral-200">
-                {multiSelectCount} elements selected
-              </p>
-              <p className="mt-2 max-w-[260px] text-xs leading-5 text-neutral-500">
-                Select a single element to edit its properties. Click an element in the preview or
-                use the timeline layer panel.
-              </p>
-            </>
-          ) : (
-            <>
-              <Eye size={18} className="mb-3 text-neutral-600" />
-              <p className="text-sm font-medium text-neutral-200">
-                Select an element in the preview.
-              </p>
-              <p className="mt-2 max-w-[260px] text-xs leading-5 text-neutral-500">
-                The inspector is tuned for element edits with safer geometry controls, color
-                picking, and cleaner grouped layer controls.
-              </p>
-            </>
-          )}
-        </div>
-      </div>
-    );
+    return <PropertyPanelEmptyState multiSelectCount={multiSelectCount} />;
   }
 
   const manualOffsetEditingDisabled = !element.capabilities.canApplyManualOffset;
@@ -581,6 +558,8 @@ export const PropertyPanel = memo(function PropertyPanel({
             onSetStyle={onSetStyle}
             onImportAssets={onImportAssets}
             gsapBorderRadius={gsapBorderRadius}
+            cropMode={cropMode}
+            onCropModeChange={onCropModeChange}
           />
         )}
       </div>

package/src/components/editor/PropertyPanelEmptyState.tsx

@@ -0,0 +1,33 @@
+import { Eye, Layers } from "../../icons/SystemIcons";
+
+export function PropertyPanelEmptyState({ multiSelectCount }: { multiSelectCount: number }) {
+  return (
+    <div className="flex h-full flex-col bg-neutral-900">
+      <div className="flex flex-1 flex-col items-center justify-center px-6 text-center">
+        {multiSelectCount > 1 ? (
+          <>
+            <Layers size={18} className="mb-3 text-neutral-600" />
+            <p className="text-sm font-medium text-neutral-200">
+              {multiSelectCount} elements selected
+            </p>
+            <p className="mt-2 max-w-[260px] text-xs leading-5 text-neutral-500">
+              Select a single element to edit its properties. Click an element in the preview or use
+              the timeline layer panel.
+            </p>
+          </>
+        ) : (
+          <>
+            <Eye size={18} className="mb-3 text-neutral-600" />
+            <p className="text-sm font-medium text-neutral-200">
+              Select an element in the preview.
+            </p>
+            <p className="mt-2 max-w-[260px] text-xs leading-5 text-neutral-500">
+              The inspector is tuned for element edits with safer geometry controls, color picking,
+              and cleaner grouped layer controls.
+            </p>
+          </>
+        )}
+      </div>
+    </div>
+  );
+}

package/src/components/editor/SnapToolbar.tsx

@@ -1,5 +1,5 @@
 import { memo, useCallback, useEffect, useRef, useState } from "react";
-import { MagnetStraight, GridFour, Path } from "@phosphor-icons/react";
+import { Crop, MagnetStraight, GridFour, Path } from "@phosphor-icons/react";
 import { readStudioUiPreferences, writeStudioUiPreferences } from "../../utils/studioUiPreferences";
 import { usePlayerStore } from "../../player/store/playerStore";
 
@@ -39,6 +39,9 @@ export const SnapToolbar = memo(function SnapToolbar({ onSnapChange }: SnapToolb
   const motionPathCreateAvailable = usePlayerStore((s) => s.motionPathCreateAvailable);
   const motionPathArmed = usePlayerStore((s) => s.motionPathArmed);
   const setMotionPathArmed = usePlayerStore((s) => s.setMotionPathArmed);
+  const cropAvailable = usePlayerStore((s) => s.cropAvailable);
+  const cropMode = usePlayerStore((s) => s.cropMode);
+  const setCropMode = usePlayerStore((s) => s.setCropMode);
   const popoverRef = useRef<HTMLDivElement>(null);
   const gridButtonRef = useRef<HTMLButtonElement>(null);
 
@@ -99,6 +102,22 @@ export const SnapToolbar = memo(function SnapToolbar({ onSnapChange }: SnapToolb
       className="absolute top-2 right-2 z-50 flex items-center gap-1"
       onPointerDown={(e) => e.stopPropagation()}
     >
+      {cropAvailable && (
+        <button
+          type="button"
+          className={`rounded-md p-1.5 transition-colors ${
+            cropMode
+              ? "bg-studio-accent/20 text-studio-accent"
+              : "bg-black/40 text-white/60 hover:bg-black/60 hover:text-white/80"
+          }`}
+          onClick={() => setCropMode(!cropMode)}
+          title={cropMode ? "Exit crop (Esc)" : "Crop selection"}
+          aria-label="Crop selection"
+          aria-pressed={cropMode}
+        >
+          <Crop size={16} weight={cropMode ? "fill" : "regular"} />
+        </button>
+      )}
       {motionPathCreateAvailable && (
         <button
           type="button"