@hyperframes/studio 0.7.54 → 0.7.55

package/src/player/components/timelineZoom.test.ts

@@ -1,12 +1,15 @@
 import { describe, expect, it } from "vitest";
 import {
   clampTimelineZoomPercent,
+  computePinnedZoomPercent,
   getNextTimelineZoomPercent,
   getPinchTimelineZoomPercent,
   getTimelinePixelsPerSecond,
   getTimelineZoomPercent,
   MAX_TIMELINE_ZOOM_PERCENT,
   MIN_TIMELINE_ZOOM_PERCENT,
+  timelineZoomPercentToSlider,
+  timelineSliderToZoomPercent,
 } from "./timelineZoom";
 
 describe("clampTimelineZoomPercent", () => {
@@ -81,3 +84,67 @@ describe("getPinchTimelineZoomPercent", () => {
     expect(getPinchTimelineZoomPercent(-10000, "manual", 100)).toBe(MAX_TIMELINE_ZOOM_PERCENT);
   });
 });
+
+describe("timelineZoomPercentToSlider", () => {
+  it("maps min zoom to slider position 0", () => {
+    expect(timelineZoomPercentToSlider(MIN_TIMELINE_ZOOM_PERCENT)).toBeCloseTo(0, 5);
+  });
+
+  it("maps max zoom to slider position 100", () => {
+    expect(timelineZoomPercentToSlider(MAX_TIMELINE_ZOOM_PERCENT)).toBeCloseTo(100, 5);
+  });
+
+  it("maps 100% to the log midpoint between 10 and 2000", () => {
+    const expected = ((Math.log(100) - Math.log(10)) / (Math.log(2000) - Math.log(10))) * 100;
+    expect(timelineZoomPercentToSlider(100)).toBeCloseTo(expected, 3);
+  });
+});
+
+describe("timelineSliderToZoomPercent", () => {
+  it("maps slider 0 to min zoom", () => {
+    expect(timelineSliderToZoomPercent(0)).toBe(MIN_TIMELINE_ZOOM_PERCENT);
+  });
+
+  it("maps slider 100 to max zoom", () => {
+    expect(timelineSliderToZoomPercent(100)).toBe(MAX_TIMELINE_ZOOM_PERCENT);
+  });
+});
+
+describe("computePinnedZoomPercent", () => {
+  it("returns 100 when current pps equals the fit pps (a no-op pin at the current fit)", () => {
+    expect(computePinnedZoomPercent(42, 42)).toBe(100);
+  });
+
+  it("reproduces the current pps: percent × fitPps / 100 === currentPps", () => {
+    const fitPps = 20;
+    const currentPps = 50; // user zoomed in 2.5×
+    const percent = computePinnedZoomPercent(currentPps, fitPps);
+    expect(percent).toBe(250);
+    // Round-trips through getTimelinePixelsPerSecond back to the on-screen pps.
+    expect(getTimelinePixelsPerSecond(fitPps, "manual", percent)).toBeCloseTo(currentPps, 5);
+  });
+
+  it("clamps a pin that would exceed the manual-zoom bounds", () => {
+    // currentPps 10000 / fitPps 1 = 1_000_000% → clamped to MAX.
+    expect(computePinnedZoomPercent(10000, 1)).toBe(MAX_TIMELINE_ZOOM_PERCENT);
+    // Tiny ratio → clamped up to MIN.
+    expect(computePinnedZoomPercent(0.001, 1000)).toBe(MIN_TIMELINE_ZOOM_PERCENT);
+  });
+
+  it("falls back to 100 for unusable inputs (a safe no-op pin)", () => {
+    expect(computePinnedZoomPercent(Number.NaN, 20)).toBe(100);
+    expect(computePinnedZoomPercent(50, 0)).toBe(100);
+    expect(computePinnedZoomPercent(-5, 20)).toBe(100);
+    expect(computePinnedZoomPercent(50, Number.POSITIVE_INFINITY)).toBe(100);
+  });
+});
+
+describe("timelineZoomPercentToSlider / timelineSliderToZoomPercent round-trip", () => {
+  for (const percent of [10, 100, 500, 2000]) {
+    it(`round-trips ${percent}% within ±1%`, () => {
+      const slider = timelineZoomPercentToSlider(percent);
+      const back = timelineSliderToZoomPercent(slider);
+      expect(Math.abs(back - percent) / percent).toBeLessThan(0.01);
+    });
+  }
+});

package/src/player/components/timelineZoom.ts

@@ -18,6 +18,34 @@ export function getTimelineZoomPercent(zoomMode: ZoomMode, manualZoomPercent: nu
   return zoomMode === "fit" ? 100 : clampTimelineZoomPercent(manualZoomPercent);
 }
 
+/**
+ * The manual-zoom percent that, applied to `fitPixelsPerSecond`, reproduces the
+ * CURRENT on-screen pixels-per-second exactly. Used to PIN the timeline zoom on
+ * the first edit so a duration change (which recomputes fit-pps) no longer
+ * rescales every clip: we switch `zoomMode` to "manual" with this percent, so
+ * `getTimelinePixelsPerSecond` keeps returning today's pps regardless of the new
+ * fit basis.
+ *
+ * Since `pps = fitPps * (percent / 100)` in manual mode, and while fitting
+ * `pps === fitPps`, the pinned percent is `currentPps / fitPps * 100`. Clamped to
+ * the manual-zoom range so the pin can't land outside the slider's bounds; falls
+ * back to 100 (a no-op pin at the current fit) when either input is unusable.
+ */
+export function computePinnedZoomPercent(
+  currentPixelsPerSecond: number,
+  fitPixelsPerSecond: number,
+): number {
+  if (
+    !Number.isFinite(currentPixelsPerSecond) ||
+    currentPixelsPerSecond <= 0 ||
+    !Number.isFinite(fitPixelsPerSecond) ||
+    fitPixelsPerSecond <= 0
+  ) {
+    return 100;
+  }
+  return clampTimelineZoomPercent((currentPixelsPerSecond / fitPixelsPerSecond) * 100);
+}
+
 export function getTimelinePixelsPerSecond(
   fitPixelsPerSecond: number,
   zoomMode: ZoomMode,
@@ -47,3 +75,26 @@ export function getPinchTimelineZoomPercent(
   if (!Number.isFinite(deltaY) || deltaY === 0) return current;
   return clampTimelineZoomPercent(current * Math.exp(-deltaY * PINCH_ZOOM_SENSITIVITY));
 }
+
+const LOG_MIN = Math.log(MIN_TIMELINE_ZOOM_PERCENT);
+const LOG_MAX = Math.log(MAX_TIMELINE_ZOOM_PERCENT);
+
+/**
+ * Maps a zoom percent (10–2000) to a slider position (0–100) using a log scale.
+ * Log scale is used because the range spans 200×; linear would compress the
+ * low end (10–100%) into a tiny sliver of the slider.
+ */
+export function timelineZoomPercentToSlider(percent: number): number {
+  const clamped = clampTimelineZoomPercent(percent);
+  return ((Math.log(clamped) - LOG_MIN) / (LOG_MAX - LOG_MIN)) * 100;
+}
+
+/**
+ * Maps a slider position (0–100) to a zoom percent (10–2000) using a log scale.
+ * Inverse of `timelineZoomPercentToSlider`.
+ */
+export function timelineSliderToZoomPercent(slider: number): number {
+  const clampedSlider = Math.max(0, Math.min(100, slider));
+  const logValue = LOG_MIN + (clampedSlider / 100) * (LOG_MAX - LOG_MIN);
+  return clampTimelineZoomPercent(Math.exp(logValue));
+}

package/src/player/hooks/useTimelineSyncCallbacks.test.ts

@@ -0,0 +1,219 @@
+// @vitest-environment happy-dom
+import { describe, expect, it } from "vitest";
+import {
+  resolveReloadSeekTime,
+  resolveTimelineTotalDuration,
+  revealIframe,
+} from "./useTimelineSyncCallbacks";
+import { readTimelineDurationFromDocument } from "../lib/timelineDOM";
+
+// Minimal stand-in — revealIframe only touches `style.visibility`. Avoids
+// depending on a DOM environment (this test file runs under node).
+function fakeIframe(visibility: string): HTMLIFrameElement {
+  return { style: { visibility } } as unknown as HTMLIFrameElement;
+}
+
+describe("revealIframe", () => {
+  it("clears a hidden iframe's visibility (undoes refreshPlayer's hide)", () => {
+    const iframe = fakeIframe("hidden");
+    revealIframe(iframe);
+    expect(iframe.style.visibility).toBe("");
+  });
+
+  it("leaves an already-visible iframe untouched (idempotent)", () => {
+    const iframe = fakeIframe("");
+    revealIframe(iframe);
+    expect(iframe.style.visibility).toBe("");
+  });
+
+  it("no-ops on a null iframe", () => {
+    expect(() => revealIframe(null)).not.toThrow();
+  });
+});
+
+describe("resolveReloadSeekTime", () => {
+  it("restores the pending seek saved by refreshPlayer (the primary reload path)", () => {
+    expect(
+      resolveReloadSeekTime({
+        pendingSeek: 7.2,
+        requestedSeek: null,
+        storeCurrentTime: 7.2,
+        duration: 20,
+      }),
+    ).toBe(7.2);
+  });
+
+  it("honors a deep-link seek request when no pending seek exists", () => {
+    expect(
+      resolveReloadSeekTime({
+        pendingSeek: null,
+        requestedSeek: 12.5,
+        storeCurrentTime: 0,
+        duration: 20,
+      }),
+    ).toBe(12.5);
+  });
+
+  it("THE BUG: a second overlapping reload (pending seek already consumed) restores the store playhead, not 0", () => {
+    // Drop → reload #1 consumes pendingSeek and seeks/syncs to 7.2. A staggered
+    // second reload (refreshPreviewDocumentVersion 80/300ms bumps) then finds the
+    // slot empty — the old code reset the playhead to 0 here.
+    expect(
+      resolveReloadSeekTime({
+        pendingSeek: null,
+        requestedSeek: null,
+        storeCurrentTime: 7.2,
+        duration: 20,
+      }),
+    ).toBe(7.2);
+  });
+
+  it("fresh project load starts at 0 (store resets currentTime on project switch)", () => {
+    expect(
+      resolveReloadSeekTime({
+        pendingSeek: null,
+        requestedSeek: null,
+        storeCurrentTime: 0,
+        duration: 20,
+      }),
+    ).toBe(0);
+  });
+
+  it("clamps to duration when content shrank past the playhead (the one sanctioned move)", () => {
+    expect(
+      resolveReloadSeekTime({
+        pendingSeek: 18,
+        requestedSeek: null,
+        storeCurrentTime: 18,
+        duration: 9,
+      }),
+    ).toBe(9);
+  });
+
+  it("a pending seek of 0 is an explicit position, not a missing value", () => {
+    expect(
+      resolveReloadSeekTime({
+        pendingSeek: 0,
+        requestedSeek: 12,
+        storeCurrentTime: 5,
+        duration: 20,
+      }),
+    ).toBe(0);
+  });
+
+  it("returns the guarded target unclamped when the duration is non-finite (no seek(NaN))", () => {
+    // Mid-reload the adapter can report a NaN duration; Math.min(target, NaN) would
+    // be NaN and seek(NaN). The guarded target must pass through unclamped instead.
+    expect(
+      resolveReloadSeekTime({
+        pendingSeek: 7.2,
+        requestedSeek: null,
+        storeCurrentTime: 7.2,
+        duration: Number.NaN,
+      }),
+    ).toBe(7.2);
+    // A zero/negative duration is equally unusable — pass the target through.
+    expect(
+      resolveReloadSeekTime({
+        pendingSeek: 7.2,
+        requestedSeek: null,
+        storeCurrentTime: 7.2,
+        duration: 0,
+      }),
+    ).toBe(7.2);
+  });
+
+  it("guards against non-finite and negative targets", () => {
+    expect(
+      resolveReloadSeekTime({
+        pendingSeek: Number.NaN,
+        requestedSeek: null,
+        storeCurrentTime: 5,
+        duration: 20,
+      }),
+    ).toBe(0);
+    expect(
+      resolveReloadSeekTime({
+        pendingSeek: -3,
+        requestedSeek: null,
+        storeCurrentTime: 5,
+        duration: 20,
+      }),
+    ).toBe(0);
+  });
+});
+
+describe("resolveTimelineTotalDuration", () => {
+  it("THE BUG: a clip-manifest total shorter than the authored root duration never wins (stale '0:44/0:40')", () => {
+    // Fixture shape: root data-duration=44.5, furthest clip ends at 40. A runtime
+    // that measures the manifest from the furthest clip end reports 40s; playback
+    // still runs the full 44.5s, so the transport total must stay 44.5, not 40.
+    expect(
+      resolveTimelineTotalDuration({
+        manifestDurationSeconds: 40,
+        authoredRootDurationSeconds: 44.5,
+      }),
+    ).toBe(44.5);
+  });
+
+  it("lets clips extend the total PAST the authored root (content can grow the timeline)", () => {
+    expect(
+      resolveTimelineTotalDuration({
+        manifestDurationSeconds: 50,
+        authoredRootDurationSeconds: 44.5,
+      }),
+    ).toBe(50);
+  });
+
+  it("falls back to the manifest total when the root authors no duration", () => {
+    expect(
+      resolveTimelineTotalDuration({
+        manifestDurationSeconds: 40,
+        authoredRootDurationSeconds: 0,
+      }),
+    ).toBe(40);
+  });
+
+  it("uses the authored root when the manifest is loop-inflated / non-finite", () => {
+    expect(
+      resolveTimelineTotalDuration({
+        manifestDurationSeconds: Number.POSITIVE_INFINITY,
+        authoredRootDurationSeconds: 44.5,
+      }),
+    ).toBe(44.5);
+    expect(
+      resolveTimelineTotalDuration({
+        manifestDurationSeconds: 9000, // beyond the 7200s sanity cap
+        authoredRootDurationSeconds: 44.5,
+      }),
+    ).toBe(44.5);
+  });
+
+  it("returns 0 when neither source yields a usable duration", () => {
+    expect(
+      resolveTimelineTotalDuration({
+        manifestDurationSeconds: Number.NaN,
+        authoredRootDurationSeconds: -1,
+      }),
+    ).toBe(0);
+  });
+
+  it("floors the manifest at the authored root read from the fixture's DOM shape", () => {
+    // Reconstruct the fixture: root authored at 44.5s, last clip (v-letters)
+    // ends at 34 + 6 = 40s. readTimelineDurationFromDocument must report the
+    // authored 44.5, and flooring the 40s manifest total against it yields 44.5.
+    const doc = document.implementation.createHTMLDocument("fixture");
+    doc.body.innerHTML =
+      '<div id="main" data-composition-id="main" data-duration="44.5">' +
+      '<video class="clip" data-start="34" data-duration="6"></video>' +
+      "</div>";
+    const authoredRootDurationSeconds = readTimelineDurationFromDocument(doc);
+    expect(authoredRootDurationSeconds).toBe(44.5);
+    expect(
+      resolveTimelineTotalDuration({
+        manifestDurationSeconds: 1200 / 30, // durationInFrames measured from clip end
+        authoredRootDurationSeconds,
+      }),
+    ).toBe(44.5);
+  });
+});

package/src/player/hooks/useTimelineSyncCallbacks.ts

@@ -19,6 +19,7 @@ import {
   createImplicitTimelineLayersFromDOM,
   buildStandaloneRootTimelineElement,
   getTimelineElementSelector,
+  readTimelineDurationFromDocument,
 } from "../lib/timelineDOM";
 import {
   normalizePreviewViewport,
@@ -41,6 +42,76 @@ interface UseTimelineSyncCallbacksParams {
   applyPreviewAudioState: () => void;
 }
 
+/**
+ * Where should the player seek when the preview (re)loads?
+ * Priority: explicit pending seek (saved by refreshPlayer right before a
+ * reload) → store-level seek request (deep-link `?t=` hydration) → the store's
+ * last known playhead. The last fallback makes the playhead RELOAD-INVARIANT:
+ * edits persist + reload the preview, sometimes more than once (App's
+ * refreshPreviewDocumentVersion staggers extra bumps at 80/300ms), and the
+ * consume-once pendingSeekRef meant any reload after the first found the slot
+ * empty and reset the playhead to 0 — the "dropped a file and the playhead
+ * jumped to 0" bug. Falling back to the store's playhead means every reload
+ * restores position; a fresh project load still starts at 0 because the store
+ * resets currentTime on project switch. Invariant: an edit NEVER moves the
+ * playhead (the clamp below is the one sanctioned move — content shrank past it).
+ */
+/**
+ * Undo the `visibility: hidden` that refreshPlayer sets across a full reload.
+ * Safe to call when the iframe was never hidden (idempotent no-op). Every reload
+ * completion + failure path funnels through here so the preview can never get
+ * stuck invisible.
+ */
+export function revealIframe(iframe: HTMLIFrameElement | null): void {
+  if (iframe && iframe.style.visibility === "hidden") {
+    iframe.style.visibility = "";
+  }
+}
+
+export function resolveReloadSeekTime(input: {
+  pendingSeek: number | null;
+  requestedSeek: number | null;
+  storeCurrentTime: number;
+  duration: number;
+}): number {
+  const target = input.pendingSeek ?? input.requestedSeek ?? input.storeCurrentTime;
+  if (!Number.isFinite(target) || target <= 0) return 0;
+  // Only clamp to duration when it's a usable positive number. A non-finite or
+  // non-positive duration (e.g. the adapter reports NaN mid-reload) would turn
+  // Math.min(target, NaN) into NaN and seek(NaN); return the guarded target
+  // unclamped instead so the playhead lands at the intended position.
+  if (!Number.isFinite(input.duration) || input.duration <= 0) return target;
+  return Math.min(target, input.duration);
+}
+
+/** Reject non-finite, non-positive, and absurdly large (loop-inflated) values. */
+function sanitizeDurationSeconds(value: number): number {
+  return Number.isFinite(value) && value > 0 && value < 7200 ? value : 0;
+}
+
+/**
+ * The transport TOTAL a clip-manifest message should write to the store.
+ *
+ * The manifest's `durationInFrames` measures the runtime timeline; some runtimes
+ * report only the furthest clip end and ignore the root composition's authored
+ * `data-duration`. When that manifest total is SHORTER than the authored root
+ * duration, writing it makes the readout stale (playback still runs the full
+ * authored window — the user saw "0:44/0:40" on a root authored at 44.5s whose
+ * last clip ends at 40s). The authored root duration is the floor for the total,
+ * so the readout can never sit below what the file declares. A manifest total
+ * that is LONGER (clips extend past the root) still wins — content can only grow
+ * the timeline, never shrink it below the authored window.
+ */
+export function resolveTimelineTotalDuration(input: {
+  manifestDurationSeconds: number;
+  authoredRootDurationSeconds: number;
+}): number {
+  return Math.max(
+    sanitizeDurationSeconds(input.manifestDurationSeconds),
+    sanitizeDurationSeconds(input.authoredRootDurationSeconds),
+  );
+}
+
 export function useTimelineSyncCallbacks({
   iframeRef,
   probeIntervalRef,
@@ -154,8 +225,14 @@ export function useTimelineSyncCallbacks({
       const rawDuration = data.durationInFrames / 30;
       // Clamp non-finite or absurdly large durations — the runtime can emit
       // Infinity when it detects a loop-inflated GSAP timeline without an
-      // explicit data-duration on the root composition.
-      const newDuration = Number.isFinite(rawDuration) && rawDuration < 7200 ? rawDuration : 0;
+      // explicit data-duration on the root composition. Floor the manifest total
+      // at the authored root `data-duration` so a runtime that measures only the
+      // furthest clip end (shorter than the authored window) can't leave a stale,
+      // too-short total in the transport (the "0:44/0:40" bug).
+      const newDuration = resolveTimelineTotalDuration({
+        manifestDurationSeconds: rawDuration,
+        authoredRootDurationSeconds: readTimelineDurationFromDocument(iframeDoc),
+      });
       const effectiveDuration = newDuration > 0 ? newDuration : usePlayerStore.getState().duration;
       const clampedEls =
         effectiveDuration > 0
@@ -218,12 +295,32 @@ export function useTimelineSyncCallbacks({
     // never reaches pendingSeekRef). Reconciling with the store here is what makes a
     // deep-linked `?t=` land instead of starting at 0.
     const storeSeek = usePlayerStore.getState().requestedSeekTime;
-    const seekTo = pendingSeekRef.current ?? storeSeek;
+    const startTime = resolveReloadSeekTime({
+      pendingSeek: pendingSeekRef.current,
+      requestedSeek: storeSeek,
+      storeCurrentTime: usePlayerStore.getState().currentTime,
+      duration: adapter.getDuration(),
+    });
     pendingSeekRef.current = null;
     if (storeSeek != null) usePlayerStore.getState().clearSeekRequest();
-    const startTime = seekTo != null ? Math.min(seekTo, adapter.getDuration()) : 0;
 
+    // Force a REAL render at startTime, not a no-op. After a post-edit reload the
+    // freshly rebuilt GSAP timeline can already report being at `startTime`
+    // internally (the reload restores the same playhead), so a single
+    // `adapter.seek(startTime)` is a GSAP no-op — `tl.seek(t)` at the current time
+    // doesn't re-evaluate. That's why a just-dropped clip stayed invisible until
+    // the user nudged the playhead: its element's state was never applied at the
+    // restore position. Seeking to a DIFFERENT guard value first (a hair off, or 0
+    // when startTime is already ~0) guarantees the follow-up seek to `startTime`
+    // crosses a time boundary and re-renders every clip — including the new one.
+    const guardTime = startTime > 0.001 ? Math.max(0, startTime - 0.001) : 0.001;
+    adapter.seek(guardTime);
     adapter.seek(startTime);
+    // The correct frame is now rendered — reveal the iframe that refreshPlayer hid
+    // for the reload, so the user sees the restored frame directly (never the raw
+    // all-clips DOM). Cleared unconditionally: any later failure path must not leave
+    // the preview stuck invisible.
+    revealIframe(iframeRef.current);
     // Keep non-React listeners such as the capture link and time display in sync
     // with the initial adapter seek on iframe load.
     liveTime.notify(startTime);
@@ -332,6 +429,9 @@ export function useTimelineSyncCallbacks({
         trySettle();
       }
       window.removeEventListener("message", onMessage);
+      // Never leave the preview stuck invisible if the runtime never settled
+      // (initializeAdapter reveals on success; this covers the give-up case).
+      revealIframe(iframeRef.current);
     }, 5000) as unknown as ReturnType<typeof setInterval>;
   }, [initializeAdapter, iframeRef, probeIntervalRef, applyPreviewAudioState]);
 

package/src/utils/assetClickBehavior.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it } from "vitest";
+import { findClipForAsset, isPointerClick, DRAG_THRESHOLD_PX } from "./assetClickBehavior";
+import type { TimelineElement } from "../player/store/playerStore";
+
+// Minimal TimelineElement factory — only the fields the function inspects.
+function makeEl(overrides: Partial<TimelineElement> & { id: string }): TimelineElement {
+  return {
+    tag: "div",
+    start: 0,
+    duration: 5,
+    track: 0,
+    ...overrides,
+  };
+}
+
+describe("findClipForAsset", () => {
+  it("returns null when elements array is empty", () => {
+    expect(findClipForAsset([], "assets/foo.mp4")).toBeNull();
+  });
+
+  it("returns null when no element matches", () => {
+    const el = makeEl({ id: "el1", src: "assets/other.mp4" });
+    expect(findClipForAsset([el], "assets/foo.mp4")).toBeNull();
+  });
+
+  it("matches a bare relative src against the project-relative asset path", () => {
+    const el = makeEl({ id: "el1", src: "assets/clip.mp4", start: 2 });
+    expect(findClipForAsset([el], "assets/clip.mp4")).toBe(el);
+  });
+
+  it("matches a src with a ./ prefix", () => {
+    const el = makeEl({ id: "el1", src: "./assets/logo.png" });
+    expect(findClipForAsset([el], "assets/logo.png")).toBe(el);
+  });
+
+  it("matches a server-relative /api/projects/…/preview/ src", () => {
+    const el = makeEl({ id: "el1", src: "/api/projects/demo/preview/assets/bgm.mp3" });
+    expect(findClipForAsset([el], "assets/bgm.mp3")).toBe(el);
+  });
+
+  it("matches a fully-absolute URL (as produced by the core runtime)", () => {
+    const el = makeEl({
+      id: "el1",
+      src: "http://localhost:3012/api/projects/demo/preview/assets/clip.mp4",
+    });
+    expect(findClipForAsset([el], "assets/clip.mp4")).toBe(el);
+  });
+
+  it("decodes percent-encoded filenames when matching", () => {
+    const el = makeEl({
+      id: "el1",
+      src: "http://localhost:3012/api/projects/p/preview/assets/my%20file%20(1).mp4",
+    });
+    expect(findClipForAsset([el], "assets/my file (1).mp4")).toBe(el);
+  });
+
+  it("strips query strings from src before matching", () => {
+    const el = makeEl({ id: "el1", src: "assets/clip.mp4?v=2" });
+    expect(findClipForAsset([el], "assets/clip.mp4")).toBe(el);
+  });
+
+  it("returns the element with the earliest start when multiple clips match", () => {
+    const later = makeEl({ id: "late", src: "assets/clip.mp4", start: 10 });
+    const earlier = makeEl({ id: "early", src: "assets/clip.mp4", start: 2 });
+    const first = makeEl({ id: "first", src: "assets/clip.mp4", start: 0 });
+    expect(findClipForAsset([later, earlier, first], "assets/clip.mp4")).toBe(first);
+  });
+
+  it("prefers the key over id when the element has both", () => {
+    // findClipForAsset returns the element object itself; callers do `clip.key ?? clip.id`
+    const el = makeEl({ id: "el1", key: "clip-key", src: "assets/img.png" });
+    const found = findClipForAsset([el], "assets/img.png");
+    expect(found?.key).toBe("clip-key");
+  });
+
+  it("skips elements with no src", () => {
+    const noSrc = makeEl({ id: "nosrc" });
+    const withSrc = makeEl({ id: "withsrc", src: "assets/img.png" });
+    expect(findClipForAsset([noSrc, withSrc], "assets/img.png")).toBe(withSrc);
+  });
+});
+
+describe("isPointerClick", () => {
+  it("returns true for zero movement", () => {
+    expect(isPointerClick(0, 0)).toBe(true);
+  });
+
+  it("returns true for movement within the threshold", () => {
+    expect(isPointerClick(DRAG_THRESHOLD_PX - 1, 0)).toBe(true);
+    expect(isPointerClick(0, DRAG_THRESHOLD_PX - 1)).toBe(true);
+    expect(isPointerClick(DRAG_THRESHOLD_PX - 1, DRAG_THRESHOLD_PX - 1)).toBe(true);
+  });
+
+  it("returns false at or beyond the threshold", () => {
+    expect(isPointerClick(DRAG_THRESHOLD_PX, 0)).toBe(false);
+    expect(isPointerClick(0, DRAG_THRESHOLD_PX)).toBe(false);
+    expect(isPointerClick(DRAG_THRESHOLD_PX + 10, 0)).toBe(false);
+  });
+
+  it("handles negative movement (pointer moved left/up)", () => {
+    expect(isPointerClick(-(DRAG_THRESHOLD_PX - 1), 0)).toBe(true);
+    expect(isPointerClick(-DRAG_THRESHOLD_PX, 0)).toBe(false);
+  });
+});

package/src/utils/assetClickBehavior.ts

@@ -0,0 +1,75 @@
+/**
+ * Pure helpers for CapCut-style asset card click behavior.
+ *
+ * Clicking an asset card that is ALREADY ADDED to the timeline selects the
+ * corresponding clip. Clicking one NOT yet in the timeline opens a lightweight
+ * preview overlay. Both behaviors are gated on "this was a click, not a drag".
+ *
+ * Pure — unit-tested.
+ */
+import type { TimelineElement } from "../player/store/playerStore";
+
+/**
+ * Find the TimelineElement that references `assetPath`, returning the one with
+ * the earliest start time when multiple clips share the same source.
+ *
+ * Matching mirrors `deriveUsedPaths` in AssetsTab: an element's `src` may be a
+ * fully-absolute URL, a server-relative `/api/projects/…/preview/…` path, a
+ * `./`-prefixed relative path, or a bare relative path — all normalised to the
+ * project-relative form that `assetPath` carries.
+ *
+ * Returns `null` when no element matches.
+ */
+export function findClipForAsset(
+  elements: TimelineElement[],
+  assetPath: string,
+): TimelineElement | null {
+  let best: TimelineElement | null = null;
+  for (const el of elements) {
+    if (!el.src) continue;
+    if (normalizeSrc(el.src) !== assetPath) continue;
+    if (best === null || el.start < best.start) best = el;
+  }
+  return best;
+}
+
+/**
+ * Normalise a raw element `src` to the bare project-relative path so it can be
+ * compared against the asset-list strings (which have no leading slash, no
+ * origin, no query string).
+ *
+ * Mirrors the logic in `deriveUsedPaths` (AssetsTab.tsx) — keep in sync.
+ */
+function normalizeSrc(src: string): string {
+  let s = src;
+  try {
+    const u = new URL(s);
+    s = u.pathname;
+  } catch {
+    // Not an absolute URL — leave as-is
+  }
+  s = s
+    .replace(/^\/api\/projects\/[^/]+\/preview\//, "")
+    .replace(/^\.?\//, "")
+    .split(/[?#]/)[0];
+  try {
+    s = decodeURIComponent(s);
+  } catch {
+    // Malformed encoding — use as-is
+  }
+  return s;
+}
+
+/** Drag-detection threshold in pixels — movements within this are treated as clicks. */
+export const DRAG_THRESHOLD_PX = 4;
+
+/**
+ * Determine whether a pointer-up event should be treated as a click given the
+ * total pointer displacement since pointer-down.
+ *
+ * @param dx  Horizontal distance moved in pixels.
+ * @param dy  Vertical distance moved in pixels.
+ */
+export function isPointerClick(dx: number, dy: number): boolean {
+  return Math.abs(dx) < DRAG_THRESHOLD_PX && Math.abs(dy) < DRAG_THRESHOLD_PX;
+}