@hyperframes/studio 0.7.38 → 0.7.40

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/contexts/TimelineEditContext.tsx

@@ -32,6 +32,7 @@ export function TimelineEditProvider({
     [
       value.onMoveElement,
       value.onResizeElement,
+      value.onToggleTrackHidden,
       value.onBlockedEditAttempt,
       value.onSplitElement,
       value.onRazorSplit,

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/gsapDragCommit.test.ts

@@ -5,6 +5,7 @@ import { commitGsapPositionFromDrag } from "./gsapDragPositionCommit";
 import {
   commitStaticGsapPosition,
   commitStaticGsapRotation,
+  findExistingPositionWrite,
   parkPlayheadOnKeyframe,
   type GsapDragCommitCallbacks,
 } from "./gsapDragCommit";
@@ -75,6 +76,7 @@ describe("commitGsapPositionFromDrag — flat tween", () => {
   });
 
   it("extends the existing tween (never spawns a parallel one) when dragged OUTSIDE its range", async () => {
+    // fallow-ignore-next-line code-duplication
     usePlayerStore.setState({ currentTime: 6 }); // outside [1.2, 3.4]
     const { types, callbacks } = recordingCallbacks();
 
@@ -94,7 +96,9 @@ describe("commitGsapPositionFromDrag — flat tween", () => {
   });
 
   it("adds a keyframe at the playhead when dragged INSIDE its range", async () => {
+    // fallow-ignore-next-line code-duplication
     usePlayerStore.setState({ currentTime: 2 }); // inside [1.2, 3.4]
+    // fallow-ignore-next-line code-duplication
     const { types, callbacks } = recordingCallbacks();
 
     await commitGsapPositionFromDrag(
@@ -115,6 +119,7 @@ describe("commitGsapPositionFromDrag — flat tween", () => {
     // User clicked the 100% diamond (activeKeyframePct=100), playhead drifted past
     // the end. Expect: convert + add-keyframe AT 100% — not replace-with-keyframes.
     usePlayerStore.setState({ currentTime: 6, activeKeyframePct: 100 }); // outside [1.2, 3.4]
+    // fallow-ignore-next-line code-duplication
     const { types, mutations, callbacks } = recordingCallbacks();
 
     await commitGsapPositionFromDrag(
@@ -338,6 +343,7 @@ describe("commitStaticGsapPosition — instantPatch (value-only set)", () => {
     await commitStaticGsapPosition(
       selection(),
       { x: -50, y: 30 },
+      // fallow-ignore-next-line code-duplication
       { x: 0, y: 0 },
       "#puck-a",
       null, // no existing set → `add` a new base gsap.set
@@ -352,6 +358,55 @@ describe("commitStaticGsapPosition — instantPatch (value-only set)", () => {
   });
 });
 
+// A degenerate `tl.to("#el",{keyframes:{...},duration:0})` — what a pre-fix drag
+// left behind when it routed a STATIC position hold (sitting beside a keyframed
+// rotation) into the keyframe branch. A duration-0 keyframed tween renders its
+// final keyframe at every playhead, so the element froze and "couldn't move".
+const keyframedZeroDurationHold = (): GsapAnimation =>
+  ({
+    id: "#puck-a-frozen",
+    targetSelector: "#puck-a",
+    method: "to",
+    propertyGroup: "position",
+    duration: 0,
+    keyframes: {
+      keyframes: [
+        { percentage: 0, properties: { x: 100, y: 50 } },
+        { percentage: 100, properties: { x: -260, y: -70 } },
+      ],
+    },
+    properties: {},
+  }) as unknown as GsapAnimation;
+
+describe("static position hold recognition + heal (frozen duration-0 keyframed tween)", () => {
+  beforeEach(() => usePlayerStore.setState({ currentTime: 0, activeKeyframePct: null }));
+
+  it("findExistingPositionWrite recognizes a keyframed zero-duration position hold", () => {
+    const found = findExistingPositionWrite([keyframedZeroDurationHold()], "#puck-a");
+    expect(found?.id).toBe("#puck-a-frozen");
+  });
+
+  it("commitStaticGsapPosition heals a keyframed hold by delete + clean add-set (never update-property)", async () => {
+    const { commits, callbacks } = optionRecordingCallbacks();
+
+    await commitStaticGsapPosition(
+      selection(),
+      { x: -50, y: 30 },
+      { x: 0, y: 0 },
+      "#puck-a",
+      keyframedZeroDurationHold(),
+      callbacks,
+    );
+
+    const types = commits.map((c) => c.mutation.type);
+    // Can't update-property into keyframes — must delete the frozen tween and
+    // write a clean static set, so the element becomes freely movable.
+    expect(types).toEqual(["delete", "add"]);
+    expect(types).not.toContain("update-property");
+    expect((commits[1].mutation as { method?: string }).method).toBe("set");
+  });
+});
+
 describe("commitStaticGsapRotation — instantPatch (value-only set)", () => {
   beforeEach(() => usePlayerStore.setState({ currentTime: 0, activeKeyframePct: null }));
 
@@ -377,6 +432,7 @@ describe("commitStaticGsapRotation — instantPatch (value-only set)", () => {
   it("ADDS a global gsap.set with a global-set instantPatch (off-timeline, no flash)", async () => {
     const { commits, callbacks } = optionRecordingCallbacks();
 
+    // fallow-ignore-next-line code-duplication
     await commitStaticGsapRotation(selection(), 42, "#puck-a", null, callbacks);
 
     expect(commits).toHaveLength(1);