@hyperframes/studio 0.7.38 → 0.7.39

package/src/components/editor/useDomEditCompositionRect.ts

@@ -0,0 +1,68 @@
+import { useState, type RefObject } from "react";
+import { useMountEffect } from "../../hooks/useMountEffect";
+
+export interface DomEditCompositionRect {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+  scaleX: number;
+  scaleY: number;
+}
+
+function sameRect(a: DomEditCompositionRect, b: DomEditCompositionRect): boolean {
+  const d = (k: keyof DomEditCompositionRect) => Math.abs(a[k] - b[k]);
+  return (
+    d("left") < 0.5 &&
+    d("top") < 0.5 &&
+    d("width") < 0.5 &&
+    d("height") < 0.5 &&
+    d("scaleX") < 0.001 &&
+    d("scaleY") < 0.001
+  );
+}
+
+export function useDomEditCompositionRect({
+  iframeRef,
+  overlayRef,
+}: {
+  iframeRef: RefObject<HTMLIFrameElement | null>;
+  overlayRef: RefObject<HTMLDivElement | null>;
+}): DomEditCompositionRect {
+  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;
+      const next = { left, top, width: iRect.width, height: iRect.height, scaleX, scaleY };
+      setCompRect((prev) => (sameRect(prev, next) ? prev : next));
+    };
+    frame = requestAnimationFrame(update);
+    return () => cancelAnimationFrame(frame);
+  });
+
+  return compRect;
+}

package/src/components/editor/useDomEditOverlayGestures.ts

@@ -46,6 +46,7 @@ import {
   startGesture as _startGesture,
   startGroupDrag as _startGroupDrag,
 } from "./domEditOverlayStartGesture";
+import { hugRectForElement } from "./domEditOverlayCrop";
 import {
   resolveSnapAdjustment,
   resolveResizeSnapAdjustment,
@@ -183,12 +184,18 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
     if (g.kind === "drag") {
       const sc = g.snapContext;
       if (sc?.snapEnabled && sc.targets.length > 0) {
-        const movingRect = {
-          left: g.originLeft,
-          top: g.originTop,
-          width: g.originWidth,
-          height: g.originHeight,
-        };
+        // Snap the element's VISIBLE (crop-hugged) edges, not the full bounds.
+        const movingRect = hugRectForElement(
+          {
+            left: g.originLeft,
+            top: g.originTop,
+            width: g.originWidth,
+            height: g.originHeight,
+            editScaleX: g.editScaleX,
+            editScaleY: g.editScaleY,
+          },
+          g.selection.element,
+        );
         const allTargets = sc.compositionTarget
           ? [...sc.targets, sc.compositionTarget]
           : sc.targets;

package/src/components/editor/useDomEditOverlayRects.ts

@@ -4,6 +4,7 @@
  */
 import { useRef, useState, type RefObject } from "react";
 import { useMountEffect } from "../../hooks/useMountEffect";
+import { hugRectForElement } from "./domEditOverlayCrop";
 import { type DomEditSelection, findElementForSelection } from "./domEditing";
 import {
   type GroupOverlayItem,
@@ -15,7 +16,7 @@ import {
   rectsEqual,
   resolveElementForOverlay,
   selectionCacheKey,
-  toOverlayRect,
+  toVisibleOverlayRect,
 } from "./domEditOverlayGeometry";
 
 function childRectsEqual(a: OverlayRect[], b: OverlayRect[]): boolean {
@@ -164,7 +165,7 @@ export function useDomEditOverlayRects({
             for (let i = 0; i < descendants.length; i++) {
               const child = descendants[i] as HTMLElement;
               if (!child.getBoundingClientRect) continue;
-              const r = toOverlayRect(overlayEl, iframe, child);
+              const r = toVisibleOverlayRect(overlayEl, iframe, child);
               if (r && r.width > 2 && r.height > 2) nextChildRects.push(r);
             }
             if (!childRectsEqual(childRectsRef.current, nextChildRects)) {
@@ -203,7 +204,8 @@ export function useDomEditOverlayRects({
           if (liveGroupKeys.has(key)) continue;
           liveGroupKeys.add(key);
           const el = resolveGroupElement(doc, groupSelection);
-          const rect = el ? groupAwareOverlayRect(overlayEl, iframe, el) : null;
+          const base = el ? groupAwareOverlayRect(overlayEl, iframe, el) : null;
+          const rect = base && el ? { ...base, ...hugRectForElement(base, el) } : base;
           if (el && rect)
             nextGroupItems.push({ key, selection: groupSelection, element: el, rect });
         }

package/src/components/sidebar/AssetsTab.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest";
+import { filterByUsage, countUsage, deriveUsedPaths } from "./AssetsTab";
+import { globalAssetRows } from "./GlobalAssetsView";
+
+const assets = ["bgm.mp3", "logo.png", "orphan.wav"];
+const used = new Set(["bgm.mp3", "logo.png"]);
+
+describe("filterByUsage", () => {
+  it("returns everything for 'all'", () => {
+    expect(filterByUsage(assets, used, "all")).toEqual(assets);
+  });
+
+  it("keeps only referenced assets for 'used'", () => {
+    expect(filterByUsage(assets, used, "used")).toEqual(["bgm.mp3", "logo.png"]);
+  });
+
+  it("keeps only unreferenced assets for 'unused'", () => {
+    expect(filterByUsage(assets, used, "unused")).toEqual(["orphan.wav"]);
+  });
+
+  it("treats everything as unused when nothing is referenced", () => {
+    expect(filterByUsage(assets, new Set(), "used")).toEqual([]);
+    expect(filterByUsage(assets, new Set(), "unused")).toEqual(assets);
+  });
+});
+
+describe("deriveUsedPaths", () => {
+  it("matches the asset-list format across every src shape", () => {
+    const used = deriveUsedPaths([
+      { src: "assets/logo.png" }, // raw authored relative path
+      { src: "/api/projects/demo/preview/assets/bgm.mp3" }, // served form
+      { src: "./assets/icon.svg" }, // ./-prefixed
+      { src: "assets/clip.mp4?v=2" }, // cache-busted
+      {}, // no src — skipped
+    ]);
+    expect(used.has("assets/logo.png")).toBe(true);
+    expect(used.has("assets/bgm.mp3")).toBe(true);
+    expect(used.has("assets/icon.svg")).toBe(true);
+    expect(used.has("assets/clip.mp4")).toBe(true);
+    expect(used.size).toBe(4);
+  });
+
+  it("an authored relative src lines up with the asset entry (the live bug class)", () => {
+    const used = deriveUsedPaths([{ src: "assets/logo.png" }]);
+    // asset-list entries are project-relative (see serveUrl = preview/${asset})
+    expect(filterByUsage(["assets/logo.png", "assets/orphan.wav"], used, "used")).toEqual([
+      "assets/logo.png",
+    ]);
+  });
+});
+
+describe("countUsage", () => {
+  it("counts used vs unused", () => {
+    expect(countUsage(assets, used)).toEqual({ used: 2, unused: 1 });
+  });
+
+  it("is all-unused with an empty used set", () => {
+    expect(countUsage(assets, new Set())).toEqual({ used: 0, unused: 3 });
+  });
+});
+
+describe("globalAssetRows", () => {
+  const recs = [
+    { id: "bgm_001", type: "bgm", description: "calm ambient" },
+    { id: "img_001", type: "image", entity: "Acme" },
+    { sha: "abc", type: "sfx" },
+  ];
+
+  it("maps records to display rows with a sensible label", () => {
+    const rows = globalAssetRows(recs);
+    expect(rows).toEqual([
+      { id: "bgm_001", type: "bgm", label: "calm ambient" },
+      { id: "img_001", type: "image", label: "Acme" },
+      { id: "abc", type: "sfx", label: "abc" },
+    ]);
+  });
+
+  it("filters by id / type / description / entity, case-insensitively", () => {
+    expect(globalAssetRows(recs, "ACME").map((r) => r.id)).toEqual(["img_001"]);
+    expect(globalAssetRows(recs, "bgm").map((r) => r.id)).toEqual(["bgm_001"]);
+    expect(globalAssetRows(recs, "ambient").map((r) => r.id)).toEqual(["bgm_001"]);
+  });
+
+  it("empty query returns all", () => {
+    expect(globalAssetRows(recs, "  ").length).toBe(3);
+  });
+});

package/src/components/sidebar/AssetsTab.tsx

@@ -1,3 +1,4 @@
+// fallow-ignore-file code-duplication
 import { memo, useState, useCallback, useRef, useMemo, useEffect } from "react";
 import { VideoFrameThumbnail } from "../ui/VideoFrameThumbnail";
 import { MEDIA_EXT, IMAGE_EXT, VIDEO_EXT, FONT_EXT } from "../../utils/mediaTypes";
@@ -14,6 +15,7 @@ import {
   FILTER_ORDER,
 } from "./assetHelpers";
 import { AudioRow } from "./AudioRow";
+import { GlobalAssetsView } from "./GlobalAssetsView";
 
 interface AssetsTabProps {
   projectId: string;
@@ -172,6 +174,51 @@ function ImageCard({
   );
 }
 
+export type UsageFilter = "all" | "used" | "unused";
+
+/** Filter assets by whether the composition references them. Pure — unit-tested. */
+export function filterByUsage(
+  assets: string[],
+  usedPaths: Set<string>,
+  usageFilter: UsageFilter,
+): string[] {
+  if (usageFilter === "used") return assets.filter((a) => usedPaths.has(a));
+  if (usageFilter === "unused") return assets.filter((a) => !usedPaths.has(a));
+  return assets;
+}
+
+/** Count used vs unused over a media set. Pure — unit-tested. */
+export function countUsage(
+  assets: string[],
+  usedPaths: Set<string>,
+): { used: number; unused: number } {
+  let used = 0;
+  for (const a of assets) if (usedPaths.has(a)) used++;
+  return { used, unused: assets.length - used };
+}
+
+/**
+ * Project-relative asset paths referenced by composition elements — the set the
+ * "in use" badge, used-first sort, and usage filter all key on. Element src is
+ * the raw authored value (timelineElementHelpers sets entry.src =
+ * getAttribute("src")), so it can be a relative path ("assets/x.png"), a
+ * "./"-prefixed path, the served "/api/projects/<id>/preview/assets/x.png" form,
+ * or carry a ?query — normalize all of them to the bare project path so they
+ * match the asset-list entries. Pure — unit-tested.
+ */
+export function deriveUsedPaths(elements: Array<{ src?: string }>): Set<string> {
+  const paths = new Set<string>();
+  for (const el of elements) {
+    if (!el.src) continue;
+    const s = el.src
+      .replace(/^\/api\/projects\/[^/]+\/preview\//, "") // strip the dev serve prefix
+      .replace(/^\.?\//, "") // strip leading ./ or /
+      .split(/[?#]/)[0]; // drop query / hash
+    if (s) paths.add(s);
+  }
+  return paths;
+}
+
 export const AssetsTab = memo(function AssetsTab({
   projectId,
   assets,
@@ -183,7 +230,11 @@ export const AssetsTab = memo(function AssetsTab({
   const [dragOver, setDragOver] = useState(false);
   const [copiedPath, setCopiedPath] = useState<string | null>(null);
   const [activeFilter, setActiveFilter] = useState<MediaCategory | "all">("all");
+  const [usageFilter, setUsageFilter] = useState<"all" | "used" | "unused">("all");
   const [searchQuery, setSearchQuery] = useState("");
+  // Cross-project view: the global media-use cache (~/.media). The view itself
+  // (GlobalAssetsView) owns its fetch — AssetsTab only tracks which scope is active.
+  const [viewMode, setViewMode] = useState<"local" | "global">("local");
   const [manifest, setManifest] = useState<
     Map<string, { description?: string; duration?: number; width?: number; height?: number }>
   >(new Map());
@@ -246,19 +297,11 @@ export const AssetsTab = memo(function AssetsTab({
   }, []);
 
   const elements = usePlayerStore((s) => s.elements);
-  const usedPaths = useMemo(() => {
-    const paths = new Set<string>();
-    for (const el of elements) {
-      if (el.src) {
-        const src = el.src.replace(/^\/api\/projects\/[^/]+\/preview\//, "");
-        paths.add(src);
-      }
-    }
-    return paths;
-  }, [elements]);
+  const usedPaths = useMemo(() => deriveUsedPaths(elements), [elements]);
 
   const mediaAssets = useMemo(() => {
-    const all = assets.filter((a) => MEDIA_EXT.test(a) || FONT_EXT.test(a));
+    const media = assets.filter((a) => MEDIA_EXT.test(a) || FONT_EXT.test(a));
+    const all = filterByUsage(media, usedPaths, usageFilter);
     if (!searchQuery) return all;
     const q = searchQuery.toLowerCase();
     return all.filter((a) => {
@@ -266,7 +309,7 @@ export const AssetsTab = memo(function AssetsTab({
       const rec = manifest.get(a);
       return rec?.description?.toLowerCase().includes(q);
     });
-  }, [assets, searchQuery, manifest]);
+  }, [assets, searchQuery, manifest, usageFilter, usedPaths]);
 
   const categorized = useMemo(() => {
     const groups: Record<MediaCategory, string[]> = { audio: [], images: [], video: [], fonts: [] };
@@ -291,6 +334,17 @@ export const AssetsTab = memo(function AssetsTab({
     return c;
   }, [mediaAssets, categorized]);
 
+  // Usage counts over the full media set (independent of the active usage filter,
+  // so the chips don't show their own filtered totals).
+  const usageCounts = useMemo(
+    () =>
+      countUsage(
+        assets.filter((a) => MEDIA_EXT.test(a) || FONT_EXT.test(a)),
+        usedPaths,
+      ),
+    [assets, usedPaths],
+  );
+
   const visibleCategories =
     activeFilter === "all"
       ? FILTER_ORDER.filter((c) => categorized[c].length > 0)
@@ -308,6 +362,22 @@ export const AssetsTab = memo(function AssetsTab({
     >
       {/* Header — matches design panel Section pattern */}
       <div className="px-4 pt-2.5 pb-1.5 flex-shrink-0">
+        {/* Scope toggle — this project's assets vs the global media-use cache */}
+        <div className="flex gap-1 mb-2.5 p-0.5 rounded-md bg-panel-input">
+          {(["local", "global"] as const).map((m) => (
+            <button
+              key={m}
+              onClick={() => setViewMode(m)}
+              className={`flex-1 px-2 py-1 text-[11px] font-medium rounded transition-colors ${
+                viewMode === m
+                  ? "bg-panel-accent/15 text-panel-accent"
+                  : "text-panel-text-3 hover:text-panel-text-1"
+              }`}
+            >
+              {m === "local" ? "This project" : "All projects"}
+            </button>
+          ))}
+        </div>
         {/* Import */}
         {onImport && (
           <>
@@ -377,8 +447,8 @@ export const AssetsTab = memo(function AssetsTab({
           </div>
         )}
 
-        {/* Filter chips — panel-input style */}
-        {mediaAssets.length > 0 && (
+        {/* Filter chips — panel-input style (local view only) */}
+        {viewMode === "local" && mediaAssets.length > 0 && (
           <div className="flex gap-1.5 flex-wrap">
             <button
               onClick={() => setActiveFilter("all")}
@@ -405,13 +475,41 @@ export const AssetsTab = memo(function AssetsTab({
                 </button>
               ) : null,
             )}
+            {/* Usage filter — show only assets the composition references, or only the unused ones */}
+            {usageCounts.used > 0 && usageCounts.unused > 0 && (
+              <>
+                <span className="w-px self-stretch bg-panel-input mx-0.5" aria-hidden="true" />
+                <button
+                  onClick={() => setUsageFilter(usageFilter === "used" ? "all" : "used")}
+                  className={`px-2.5 py-1 text-[11px] font-medium rounded-md transition-colors ${
+                    usageFilter === "used"
+                      ? "bg-panel-accent/15 text-panel-accent"
+                      : "bg-panel-input text-panel-text-3 hover:text-panel-text-1"
+                  }`}
+                >
+                  In use {usageCounts.used}
+                </button>
+                <button
+                  onClick={() => setUsageFilter(usageFilter === "unused" ? "all" : "unused")}
+                  className={`px-2.5 py-1 text-[11px] font-medium rounded-md transition-colors ${
+                    usageFilter === "unused"
+                      ? "bg-panel-accent/15 text-panel-accent"
+                      : "bg-panel-input text-panel-text-3 hover:text-panel-text-1"
+                  }`}
+                >
+                  Unused {usageCounts.unused}
+                </button>
+              </>
+            )}
           </div>
         )}
       </div>
 
       {/* Asset list */}
       <div className="flex-1 overflow-y-auto mt-1">
-        {mediaAssets.length === 0 ? (
+        {viewMode === "global" ? (
+          <GlobalAssetsView searchQuery={searchQuery} />
+        ) : mediaAssets.length === 0 ? (
           <div className="flex flex-col items-center justify-center h-full px-4 gap-2">
             <svg
               width="24"

package/src/components/sidebar/BlocksTab.tsx

@@ -1,3 +1,4 @@
+// fallow-ignore-file code-duplication
 import { memo, useState, useCallback, useRef, useEffect } from "react";
 import { createPortal } from "react-dom";
 import { useBlockCatalog } from "../../hooks/useBlockCatalog";
@@ -234,7 +235,7 @@ function buildAgentPrompt(
     captions: [
       `Using /hyperframes, add the "${title}" caption style (registry: ${name}) to my composition.`,
       `${description}`,
-      `Transcribe the audio with /hyperframes-media, then wire the transcript into this caption component. Match the font colors and animation timing to my composition's design tokens. Place it as an overlay above the main content with the highest z-index.`,
+      `Transcribe the audio with /media-use, then wire the transcript into this caption component. Match the font colors and animation timing to my composition's design tokens. Place it as an overlay above the main content with the highest z-index.`,
     ].join("\n\n"),
     vfx: [
       `Using /hyperframes, add the "${title}" VFX (registry: ${name}) as a full-screen overlay on my composition.`,

package/src/components/sidebar/GlobalAssetsView.tsx

@@ -0,0 +1,91 @@
+import { useEffect, useMemo, useState } from "react";
+
+// Cross-project asset view — the global media-use cache (~/.media), fetched from
+// /api/assets/global. Self-contained (owns its fetch + state) so AssetsTab stays
+// focused on the local view.
+
+export interface GlobalAssetRecord {
+  id?: string;
+  type?: string;
+  description?: string;
+  entity?: string;
+  sha?: string;
+}
+
+export interface GlobalAssetRow {
+  id: string;
+  type: string;
+  label: string;
+}
+
+/**
+ * Normalize global records into display rows, filtered by an optional query
+ * (id / type / description / entity). Pure — unit-tested.
+ */
+export function globalAssetRows(records: GlobalAssetRecord[], query = ""): GlobalAssetRow[] {
+  const q = query.trim().toLowerCase();
+  return records
+    .filter((r) =>
+      !q
+        ? true
+        : [r.id, r.type, r.description, r.entity].some(
+            (f) => f && String(f).toLowerCase().includes(q),
+          ),
+    )
+    .map((r) => ({
+      id: r.id ?? r.sha ?? "asset",
+      type: r.type ?? "asset",
+      label: r.description || r.entity || r.id || r.sha || "asset",
+    }));
+}
+
+export function GlobalAssetsView({ searchQuery }: { searchQuery: string }) {
+  const [records, setRecords] = useState<GlobalAssetRecord[] | null>(null);
+  useEffect(() => {
+    let cancelled = false;
+    fetch("/api/assets/global")
+      .then((r) => (r.ok ? r.json() : { assets: [] }))
+      .then((d) => {
+        if (!cancelled) setRecords(Array.isArray(d.assets) ? d.assets : []);
+      })
+      .catch(() => {
+        if (!cancelled) setRecords([]);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  const rows = useMemo(() => globalAssetRows(records ?? [], searchQuery), [records, searchQuery]);
+
+  if (records === null) {
+    return <p className="px-4 py-3 text-[11px] text-panel-text-5">Loading global assets…</p>;
+  }
+  if (rows.length === 0) {
+    return (
+      <p className="px-4 py-3 text-[11px] text-panel-text-5">
+        No assets in the global cache yet. Resolved media is promoted to <code>~/.media</code> and
+        becomes reusable across projects.
+      </p>
+    );
+  }
+  return (
+    <div>
+      <div className="px-4 py-2 border-t border-panel-border text-[11px] text-panel-text-5">
+        {rows.length} reusable across all projects
+      </div>
+      {rows.map((row) => (
+        <div
+          key={row.id}
+          className="px-4 py-1.5 flex items-center gap-2.5 border-l-2 border-transparent hover:bg-neutral-800/50"
+          title={`${row.id} · ${row.type}`}
+        >
+          <span className="text-[9px] font-medium text-neutral-600 uppercase w-10 flex-shrink-0">
+            {row.type}
+          </span>
+          <span className="text-xs text-panel-text-1 truncate">{row.label}</span>
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/hooks/domSelectionTestHarness.ts

@@ -30,6 +30,7 @@ export function makeSelection(label: string, element: HTMLElement): DomEditSelec
     capabilities: {
       canSelect: true,
       canEditStyles: true,
+      canCrop: true,
       canMove: true,
       canResize: true,
       canApplyManualOffset: true,

package/src/hooks/useCropMode.ts

@@ -0,0 +1,91 @@
+import { useEffect, useMemo, useReducer } from "react";
+import { usePlayerStore } from "../player";
+
+export interface CropModeProps {
+  cropMode: boolean;
+  onCropModeChange: (active: boolean) => void;
+}
+
+/** Crop mode lives in the player store so the canvas toolbar, the Clip panel,
+ *  and the overlay all share one switch without prop threading. */
+export function useCropModeProps(): CropModeProps {
+  const cropMode = usePlayerStore((s) => s.cropMode);
+  const setCropMode = usePlayerStore((s) => s.setCropMode);
+  return useMemo(
+    () => ({
+      cropMode,
+      onCropModeChange: setCropMode,
+    }),
+    [cropMode, setCropMode],
+  );
+}
+
+import type { OverlayRect } from "../components/editor/domEditOverlayGeometry";
+import type { DomEditSelection } from "../components/editor/domEditing";
+import { readElementCropInsets } from "../components/editor/domEditOverlayCrop";
+
+/** Overlay-side crop state: Escape-to-exit, toolbar availability publishing,
+ *  and the box clip that makes the selection outline hug the cropped region.
+ *  The box div itself always sits at the FULL element bounds — gestures write
+ *  its position directly during drags, so moving/resizing it in React would
+ *  fight them. The hug is purely visual: the element's inset clip-path scaled
+ *  into overlay space and applied to the box. */
+export function useCropOverlay(params: {
+  selection: DomEditSelection | null;
+  groupCount: number;
+  cropMode: boolean;
+  onCropModeChange?: (active: boolean) => void;
+  overlayRect: OverlayRect | null;
+}) {
+  const { selection, groupCount, cropMode, onCropModeChange, overlayRect } = params;
+
+  useEffect(() => {
+    if (!cropMode || !onCropModeChange) return;
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Escape") onCropModeChange(false);
+    };
+    window.addEventListener("keydown", handleKeyDown);
+    return () => window.removeEventListener("keydown", handleKeyDown);
+  }, [cropMode, onCropModeChange]);
+
+  // Publish availability so the canvas toolbar shows the Crop button only
+  // when the selection can take a clip-path crop.
+  const setCropAvailable = usePlayerStore((s) => s.setCropAvailable);
+  const cropAvailable = Boolean(selection && groupCount <= 1 && selection.capabilities.canCrop);
+  useEffect(() => {
+    setCropAvailable(cropAvailable);
+    return () => setCropAvailable(false);
+  }, [cropAvailable, setCropAvailable]);
+
+  // Crop-mode exit restores the element's clip in an effect cleanup — after
+  // this hook already read it. One forced re-render picks up the fresh insets
+  // so the selection box hugs the crop immediately.
+  const [, bumpAfterExit] = useReducer((x: number) => x + 1, 0);
+  useEffect(() => {
+    if (!cropMode) bumpAfterExit();
+  }, [cropMode]);
+
+  const cropInsets = selection ? readElementCropInsets(selection.element) : null;
+  const hasCropInsets = Boolean(
+    cropInsets &&
+    (cropInsets.top > 0 || cropInsets.right > 0 || cropInsets.bottom > 0 || cropInsets.left > 0),
+  );
+
+  // Scaled insets for the crop outline child + the resize-handle shift. The
+  // box div itself stays border-less at full bounds; a child draws the
+  // outline ON the crop boundary (a clip on the box would swallow the
+  // border everywhere the crop edge doesn't touch the element edge).
+  const sx = overlayRect && overlayRect.editScaleX > 0 ? overlayRect.editScaleX : 1;
+  const sy = overlayRect && overlayRect.editScaleY > 0 ? overlayRect.editScaleY : 1;
+  const cropOutlineInsetPx =
+    cropInsets && hasCropInsets && !cropMode
+      ? {
+          top: cropInsets.top * sy,
+          right: cropInsets.right * sx,
+          bottom: cropInsets.bottom * sy,
+          left: cropInsets.left * sx,
+        }
+      : undefined;
+
+  return { hasCropInsets, cropOutlineInsetPx };
+}

package/src/hooks/useDomEditCommits.test.tsx

@@ -1,3 +1,4 @@
+// fallow-ignore-file code-duplication
 // @vitest-environment happy-dom
 import { act, createElement } from "react";
 import { createRoot, type Root } from "react-dom/client";
@@ -183,6 +184,7 @@ function createSelection(
     capabilities: {
       canSelect: true,
       canEditStyles: true,
+      canCrop: true,
       canMove: true,
       canResize: true,
       canApplyManualOffset: true,

package/src/player/components/ShortcutsPanel.tsx

@@ -60,6 +60,15 @@ const SHORTCUT_SECTIONS = [
       { key: "⇧ Drag", label: "Uniform resize" },
     ],
   },
+  {
+    title: "Crop",
+    hints: [
+      { key: "DblClick", label: "Crop selected element" },
+      { key: "Drag edge", label: "Adjust crop side" },
+      { key: "Drag frame", label: "Move crop window" },
+      { key: "Esc", label: "Exit crop (or click outside)" },
+    ],
+  },
   {
     title: "Panels",
     hints: [