@hyperframes/studio 0.7.38 → 0.7.40

package/src/components/editor/PropertyPanel.tsx

@@ -1,5 +1,6 @@
 import { memo, useEffect, useMemo, useRef, useState } from "react";
-import { Eye, Layers, Move } from "../../icons/SystemIcons";
+import { Move } from "../../icons/SystemIcons";
+import { Eye, EyeSlash } from "@phosphor-icons/react";
 import { InspectorHeaderActions } from "./InspectorHeaderActions";
 import { useStudioShellContext } from "../../contexts/StudioContext";
 import { readStudioBoxSize, readStudioPathOffset, readStudioRotation } from "./manualEdits";
@@ -10,6 +11,7 @@ import {
   RESPONSIVE_GRID,
   readGsapRuntimeValuesForPanel,
   readGsapBorderRadiusForPanel,
+  isSelectedElementHidden,
 } from "./propertyPanelHelpers";
 import { MetricField, Section } from "./propertyPanelPrimitives";
 import { createTransformCommitHandlers } from "./propertyPanelTransformCommit";
@@ -27,9 +29,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 +41,7 @@ export {
   inferBoxShadowPreset,
   inferClipPathPreset,
   normalizePanelPxValue,
+  parseInsetClipPathSides,
   setCssFilterFunctionPx,
 } from "./propertyPanelHelpers";
 
@@ -64,6 +69,7 @@ export const PropertyPanel = memo(function PropertyPanel({
   onAddTextField,
   onRemoveTextField,
   onAskAgent: _onAskAgent,
+  onToggleElementHidden,
   onImportAssets,
   fontAssets = [],
   onImportFonts,
@@ -94,6 +100,8 @@ export const PropertyPanel = memo(function PropertyPanel({
   recordingState,
   recordingDuration,
   onToggleRecording,
+  cropMode,
+  onCropModeChange,
 }: PropertyPanelProps) {
   const styles = element?.computedStyles ?? EMPTY_STYLES;
   const { showToast } = useStudioShellContext();
@@ -101,6 +109,10 @@ export const PropertyPanel = memo(function PropertyPanel({
   const clipboardTimerRef = useRef<ReturnType<typeof setTimeout>>(undefined);
   const storeTime = usePlayerStore((s) => s.currentTime);
   const isPlaying = usePlayerStore((s) => s.isPlaying);
+  const timelineElements = usePlayerStore((s) => s.elements);
+  const selectedElementId = usePlayerStore((s) => s.selectedElementId);
+  const selectedElementHidden = isSelectedElementHidden(timelineElements, selectedElementId);
+  const visibilityToggleLabel = selectedElementHidden ? "Show element" : "Hide element";
   const liveTimeRef = useRef(storeTime);
   const [, forceRender] = useState(0);
   useEffect(() => {
@@ -160,35 +172,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;
@@ -311,13 +295,32 @@ export const PropertyPanel = memo(function PropertyPanel({
             </div>
             <div className="mt-0.5 truncate text-[11px] text-neutral-500">{sourceLabel}</div>
           </div>
-          <InspectorHeaderActions
-            element={element}
-            copied={clipboardCopied}
-            onCopy={handleCopyElementInfo}
-            onClear={onClearSelection}
-            onUngroup={onUngroup}
-          />
+          <div className="flex items-center gap-1">
+            {selectedElementId && onToggleElementHidden && (
+              <button
+                type="button"
+                aria-label={visibilityToggleLabel}
+                title={visibilityToggleLabel}
+                onClick={() => {
+                  void onToggleElementHidden(selectedElementId, !selectedElementHidden);
+                }}
+                className="flex h-6 w-6 items-center justify-center rounded text-neutral-500 transition-colors hover:bg-neutral-800 hover:text-neutral-300"
+              >
+                {selectedElementHidden ? (
+                  <EyeSlash size={13} weight="bold" aria-hidden="true" />
+                ) : (
+                  <Eye size={13} weight="bold" aria-hidden="true" />
+                )}
+              </button>
+            )}
+            <InspectorHeaderActions
+              element={element}
+              copied={clipboardCopied}
+              onCopy={handleCopyElementInfo}
+              onClear={onClearSelection}
+              onUngroup={onUngroup}
+            />
+          </div>
         </div>
       </div>
       <div className="flex-1 overflow-y-auto">
@@ -581,6 +584,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"

package/src/components/editor/clipPathHelpers.ts

@@ -0,0 +1,113 @@
+import { roundToCenti } from "../../utils/rounding";
+
+export interface ClipPathInsetSides {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+
+export type ParsedInsetClipPathSides = ClipPathInsetSides & { radius: number };
+
+function formatClipNumber(value: number): string {
+  const rounded = roundToCenti(value);
+  return Number.isInteger(rounded)
+    ? `${rounded}`
+    : rounded.toFixed(2).replace(/0+$/, "").replace(/\.$/, "");
+}
+
+function formatClipPx(value: number): string {
+  return `${formatClipNumber(Math.max(0, value))}px`;
+}
+
+function parseInsetLengthPx(value: string): number | null {
+  const normalized = value.trim();
+  if (normalized === "0") return 0;
+  const match = /^(-?\d+(?:\.\d+)?)px$/i.exec(normalized);
+  if (!match) return null;
+  const parsed = Number.parseFloat(match[1]);
+  return Number.isFinite(parsed) ? Math.max(0, parsed) : null;
+}
+
+function sidesFromInsetTokens(tokens: number[]): ClipPathInsetSides | null {
+  if (tokens.length < 1 || tokens.length > 4) return null;
+  // CSS shorthand expansion: T | T R | T R B | T R B L
+  const [top, right = top, bottom = top, left = right] = tokens;
+  if (top === undefined || right === undefined || bottom === undefined || left === undefined) {
+    return null;
+  }
+  return { top, right, bottom, left };
+}
+
+export function inferClipPathPreset(
+  value: string | undefined,
+): "none" | "inset" | "circle" | "custom" {
+  const normalized = value?.trim();
+  if (!normalized || normalized === "none") return "none";
+  if (/^inset\(/i.test(normalized)) return "inset";
+  if (/^circle\(/i.test(normalized)) return "circle";
+  return "custom";
+}
+
+export function parseInsetClipPathSides(
+  value: string | undefined,
+): ParsedInsetClipPathSides | null {
+  // Unambiguous pattern (no nested optional whitespace) to avoid polynomial
+  // backtracking on adversarial input; trim the payload instead.
+  const match = /^inset\(([^()]*)\)$/i.exec(value?.trim() ?? "");
+  if (!match) return null;
+  const parts = match[1]
+    .trim()
+    .replace(/\s+/g, " ")
+    .split(/ round /i);
+  const insetPart = parts[0]?.trim();
+  if (!insetPart || parts.length > 2) return null;
+
+  const tokens = insetPart.split(/\s+/).map(parseInsetLengthPx);
+  if (tokens.some((token) => token == null)) return null;
+  const numericTokens: number[] = [];
+  for (const token of tokens) {
+    if (token == null) return null;
+    numericTokens.push(token);
+  }
+  const sides = sidesFromInsetTokens(numericTokens);
+  if (!sides) return null;
+
+  const radiusPart = parts[1]?.trim();
+  const radius = radiusPart ? parseInsetLengthPx(radiusPart) : 0;
+  if (radius == null) return null;
+  return { ...sides, radius };
+}
+
+export function getClipPathInsetPx(value: string | undefined): number {
+  const parsed = parseInsetClipPathSides(value);
+  if (!parsed) return 0;
+  const { top, right, bottom, left } = parsed;
+  return top === right && top === bottom && top === left ? top : 0;
+}
+
+export function buildClipPathValue(
+  preset: "none" | "inset" | "circle" | "custom",
+  radiusValue: number,
+  fallback: string | undefined,
+) {
+  if (preset === "custom") return fallback?.trim() || "none";
+  if (preset === "circle") return "circle(50% at 50% 50%)";
+  if (preset === "inset") {
+    return `inset(0 round ${formatClipNumber(Math.max(0, radiusValue))}px)`;
+  }
+  return "none";
+}
+
+export function buildInsetClipPathSides(sides: ClipPathInsetSides, radiusPx: number = 0): string {
+  const values = [sides.top, sides.right, sides.bottom, sides.left].map(formatClipPx);
+  const [top, right, bottom, left] = values;
+  const inset =
+    top === right && top === bottom && top === left ? top : `${top} ${right} ${bottom} ${left}`;
+  const radius = Math.max(0, radiusPx);
+  return radius > 0 ? `inset(${inset} round ${formatClipNumber(radius)}px)` : `inset(${inset})`;
+}
+
+export function buildInsetClipPathValue(insetPx: number, radiusValue: number): string {
+  return `inset(${formatClipPx(insetPx)} round ${formatClipNumber(Math.max(0, radiusValue))}px)`;
+}

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

@@ -0,0 +1,106 @@
+import { describe, expect, it } from "vitest";
+import {
+  cropRectFromInsets,
+  resolveCropInsetFromEdgeDrag,
+  resolveCropInsetFromMoveDrag,
+} from "./domEditOverlayCrop";
+
+describe("resolveCropInsetFromEdgeDrag", () => {
+  const startInsets = { top: 10, right: 20, bottom: 30, left: 40 };
+
+  it("converts overlay-space edge movement into element-space inset changes", () => {
+    expect(
+      resolveCropInsetFromEdgeDrag({
+        edge: "left",
+        startInsets,
+        deltaX: 20,
+        deltaY: 0,
+        scaleX: 2,
+        scaleY: 1,
+        width: 200,
+        height: 120,
+      }),
+    ).toEqual({ top: 10, right: 20, bottom: 30, left: 50 });
+
+    expect(
+      resolveCropInsetFromEdgeDrag({
+        edge: "right",
+        startInsets,
+        deltaX: 20,
+        deltaY: 0,
+        scaleX: 2,
+        scaleY: 1,
+        width: 200,
+        height: 120,
+      }),
+    ).toEqual({ top: 10, right: 10, bottom: 30, left: 40 });
+  });
+
+  it("clamps edited insets so opposing sides never overlap", () => {
+    expect(
+      resolveCropInsetFromEdgeDrag({
+        edge: "left",
+        startInsets,
+        deltaX: 400,
+        deltaY: 0,
+        scaleX: 1,
+        scaleY: 1,
+        width: 100,
+        height: 120,
+      }),
+    ).toEqual({ top: 10, right: 20, bottom: 30, left: 80 });
+
+    expect(
+      resolveCropInsetFromEdgeDrag({
+        edge: "top",
+        startInsets,
+        deltaX: 0,
+        deltaY: -40,
+        scaleX: 1,
+        scaleY: 2,
+        width: 200,
+        height: 120,
+      }),
+    ).toEqual({ top: 0, right: 20, bottom: 30, left: 40 });
+  });
+});
+
+describe("cropRectFromInsets", () => {
+  it("shrinks the overlay rect by scaled insets", () => {
+    expect(
+      cropRectFromInsets(
+        { left: 100, top: 50, width: 200, height: 100 },
+        { top: 10, right: 40, bottom: 20, left: 30 },
+        2,
+        1,
+      ),
+    ).toEqual({ left: 160, top: 60, width: 60, height: 70 });
+  });
+
+  it("clamps to zero size when insets exceed the rect", () => {
+    const r = cropRectFromInsets(
+      { left: 0, top: 0, width: 100, height: 100 },
+      { top: 300, right: 300, bottom: 300, left: 300 },
+      1,
+      1,
+    );
+    expect(r.width).toBe(0);
+    expect(r.height).toBe(0);
+  });
+});
+
+describe("resolveCropInsetFromMoveDrag", () => {
+  const startInsets = { top: 10, right: 20, bottom: 30, left: 40 };
+
+  it("shifts opposing insets together so the crop size stays constant", () => {
+    expect(
+      resolveCropInsetFromMoveDrag({ startInsets, deltaX: 20, deltaY: -10, scaleX: 2, scaleY: 1 }),
+    ).toEqual({ top: 0, right: 10, bottom: 40, left: 50 });
+  });
+
+  it("clamps the window inside the element bounds", () => {
+    expect(
+      resolveCropInsetFromMoveDrag({ startInsets, deltaX: 999, deltaY: 999, scaleX: 1, scaleY: 1 }),
+    ).toEqual({ top: 40, right: 0, bottom: 0, left: 60 });
+  });
+});

package/src/components/editor/domEditOverlayCrop.ts

@@ -0,0 +1,115 @@
+import { parseInsetClipPathSides, type ClipPathInsetSides } from "./clipPathHelpers";
+
+export type CropEdge = "top" | "right" | "bottom" | "left";
+
+export interface CropScreenRect {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+/** Element-space insets → the cropped region in overlay (screen) space. */
+export function cropRectFromInsets(
+  rect: CropScreenRect,
+  insets: ClipPathInsetSides,
+  scaleX: number,
+  scaleY: number,
+): CropScreenRect {
+  const sx = scaleX > 0 ? scaleX : 1;
+  const sy = scaleY > 0 ? scaleY : 1;
+  const left = rect.left + insets.left * sx;
+  const top = rect.top + insets.top * sy;
+  return {
+    left,
+    top,
+    width: Math.max(0, rect.width - (insets.left + insets.right) * sx),
+    height: Math.max(0, rect.height - (insets.top + insets.bottom) * sy),
+  };
+}
+
+/** Current inset crop of an element (inline first, computed fallback), or zeros. */
+export function readElementCropInsets(element: HTMLElement): ClipPathInsetSides & {
+  radius: number;
+} {
+  const inline = element.style.getPropertyValue("clip-path").trim();
+  const value =
+    inline || element.ownerDocument.defaultView?.getComputedStyle(element).clipPath.trim() || "";
+  const parsed = parseInsetClipPathSides(value === "none" ? "" : value);
+  return parsed ?? { top: 0, right: 0, bottom: 0, left: 0, radius: 0 };
+}
+
+export interface CropInsetDragInput {
+  edge: CropEdge;
+  startInsets: ClipPathInsetSides;
+  deltaX: number;
+  deltaY: number;
+  scaleX: number;
+  scaleY: number;
+  width: number;
+  height: number;
+}
+
+function clampInset(value: number, max: number): number {
+  if (!Number.isFinite(value)) return 0;
+  return Math.min(Math.max(0, value), Math.max(0, max));
+}
+
+export function resolveCropInsetFromEdgeDrag(input: CropInsetDragInput): ClipPathInsetSides {
+  const scaleX = input.scaleX > 0 ? input.scaleX : 1;
+  const scaleY = input.scaleY > 0 ? input.scaleY : 1;
+  const next = { ...input.startInsets };
+
+  if (input.edge === "left") {
+    next.left = clampInset(
+      input.startInsets.left + input.deltaX / scaleX,
+      input.width - next.right,
+    );
+  } else if (input.edge === "right") {
+    next.right = clampInset(
+      input.startInsets.right - input.deltaX / scaleX,
+      input.width - next.left,
+    );
+  } else if (input.edge === "top") {
+    next.top = clampInset(
+      input.startInsets.top + input.deltaY / scaleY,
+      input.height - next.bottom,
+    );
+  } else {
+    next.bottom = clampInset(
+      input.startInsets.bottom - input.deltaY / scaleY,
+      input.height - next.top,
+    );
+  }
+
+  return next;
+}
+
+/** Drag the whole crop window: both opposing insets shift together, the crop
+ *  size stays constant, clamped inside the element bounds. */
+export function resolveCropInsetFromMoveDrag(input: {
+  startInsets: ClipPathInsetSides;
+  deltaX: number;
+  deltaY: number;
+  scaleX: number;
+  scaleY: number;
+}): ClipPathInsetSides {
+  const sx = input.scaleX > 0 ? input.scaleX : 1;
+  const sy = input.scaleY > 0 ? input.scaleY : 1;
+  const totalX = input.startInsets.left + input.startInsets.right;
+  const totalY = input.startInsets.top + input.startInsets.bottom;
+  const left = Math.min(Math.max(0, input.startInsets.left + input.deltaX / sx), totalX);
+  const top = Math.min(Math.max(0, input.startInsets.top + input.deltaY / sy), totalY);
+  return { left, right: totalX - left, top, bottom: totalY - top };
+}
+
+/** Display-only hug: shrink a projected rect by the element's inset crop.
+ *  For rects nothing writes back to (e.g. the hover ring). */
+export function hugRectForElement(
+  rect: CropScreenRect & { editScaleX: number; editScaleY: number },
+  element: HTMLElement,
+): CropScreenRect {
+  const insets = readElementCropInsets(element);
+  if (insets.top <= 0 && insets.right <= 0 && insets.bottom <= 0 && insets.left <= 0) return rect;
+  return cropRectFromInsets(rect, insets, rect.editScaleX, rect.editScaleY);
+}

package/src/components/editor/domEditOverlayGeometry.ts

@@ -1,5 +1,6 @@
 import { type DomEditSelection, findElementForSelection } from "./domEditing";
 import { isElementVisibleThroughAncestors } from "./domEditingDom";
+import { hugRectForElement } from "./domEditOverlayCrop";
 
 export interface OverlayRect {
   left: number;
@@ -84,6 +85,19 @@ export function resolveDomEditCoordinateScale(input: {
   };
 }
 
+/** toOverlayRect, then shrunk to the element's visible (inset-cropped) region.
+ *  For consumers that reason about what's ON SCREEN — snap targets, marquee
+ *  hit-tests, display outlines. The selection box must keep the full rect
+ *  (it is the gesture coordinate basis). */
+export function toVisibleOverlayRect(
+  overlayEl: HTMLDivElement,
+  iframe: HTMLIFrameElement,
+  element: HTMLElement,
+): OverlayRect | null {
+  const rect = toOverlayRect(overlayEl, iframe, element);
+  return rect ? { ...rect, ...hugRectForElement(rect, element) } : null;
+}
+
 export function toOverlayRect(
   overlayEl: HTMLDivElement,
   iframe: HTMLIFrameElement,

package/src/components/editor/domEditOverlayShape.ts

@@ -0,0 +1,39 @@
+import type { DomEditSelection } from "./domEditing";
+
+export interface DomEditSelectionShapeStyles {
+  borderRadius: string | number;
+  clipPath?: string;
+}
+
+export function readDomEditSelectionShapeStyles(
+  selection: DomEditSelection | null,
+): DomEditSelectionShapeStyles {
+  const fallback = {
+    borderRadius: 8,
+    clipPath: 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 borderRadius = cs.borderRadius;
+    const clipPath = cs.clipPath;
+    return {
+      borderRadius: borderRadius && borderRadius !== "0px" ? borderRadius : 4,
+      clipPath: clipPath && clipPath !== "none" ? clipPath : undefined,
+    };
+  } catch {
+    return fallback;
+  }
+}
+
+/** Selection-box chrome: none when the crop-outline child draws it, inset
+ *  shadow for clip-mirrored shapes, plain border otherwise. */
+export function resolveBoxChromeClass(hasCropOutline: boolean, boxClipPath?: string): string {
+  if (hasCropOutline) return "";
+  if (boxClipPath) return "shadow-[inset_0_0_0_2px_rgba(60,230,172,0.6)]";
+  return "border border-studio-accent/80 shadow-[0_0_0_1px_rgba(60,230,172,0.25)]";
+}

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

@@ -76,6 +76,7 @@ describe("resolveDomEditCapabilities", () => {
       canEditStyles: true,
       canMove: true,
       canResize: true,
+      canCrop: true,
       canApplyManualOffset: true,
       canApplyManualSize: true,
       canApplyManualRotation: true,
@@ -424,6 +425,7 @@ describe("resolveDomEditSelection", () => {
       canEditStyles: false,
       canMove: true,
       canResize: true,
+      canCrop: true,
       canApplyManualOffset: false,
       canApplyManualSize: false,
       canApplyManualRotation: false,

package/src/components/editor/domEditingElement.ts

@@ -28,6 +28,7 @@ export function isElementComputedVisible(el: HTMLElement): boolean {
 
 const VISUAL_LEAF_TAGS = new Set(["img", "video", "canvas", "svg", "audio"]);
 
+// fallow-ignore-next-line complexity
 function hasVisualPresence(el: HTMLElement): boolean {
   const win = el.ownerDocument.defaultView;
   if (!win) return false;
@@ -236,9 +237,13 @@ export function isLargeRasterDomEditSelection(
 
 // ─── Element finders ──────────────────────────────────────────────────────────
 
+type FindElementSelection = Pick<DomEditSelection, "id" | "hfId" | "selector" | "selectorIndex"> & {
+  sourceFile?: string;
+};
+
 export function findElementForSelection(
   doc: Document,
-  selection: Pick<DomEditSelection, "id" | "hfId" | "selector" | "selectorIndex" | "sourceFile">,
+  selection: FindElementSelection,
   activeCompositionPath: string | null = null,
 ): HTMLElement | null {
   if (selection.hfId) {
@@ -259,6 +264,7 @@ export function findElementForSelection(
 
   if (!selection.selector) return null;
 
+  // fallow-ignore-next-line code-duplication
   if (selection.selector.startsWith(".") && selection.selectorIndex != null) {
     const matches = querySelectorAllSafely(doc, selection.selector).filter(
       (candidate): candidate is HTMLElement =>
@@ -270,6 +276,7 @@ export function findElementForSelection(
     return matches[selection.selectorIndex] ?? null;
   }
 
+  // fallow-ignore-next-line code-duplication
   const matches = querySelectorAllSafely(doc, selection.selector).filter(
     (candidate): candidate is HTMLElement =>
       isHtmlElement(candidate) &&