@hyperframes/studio 0.7.54 → 0.7.56

package/src/styles/studio.css

@@ -141,6 +141,22 @@ body {
   opacity: 1;
 }
 
+/* Audio clips read as a distinct kind — a persistent violet tint vs the teal-
+   accented visual clips — so the audio zone at the bottom is visually separate
+   at a glance (the timeline's kinds: visual on top, audio below). */
+.timeline-clip.is-audio {
+  background-color: rgba(167, 139, 250, 0.16);
+  border-color: rgba(167, 139, 250, 0.4);
+}
+
+.timeline-clip.is-audio.is-hovered {
+  background-color: rgba(167, 139, 250, 0.24);
+}
+
+.timeline-clip.is-audio.is-dragging {
+  background-color: rgba(60, 52, 84, 0.96);
+}
+
 .timeline-clip.is-hovered {
   background-color: rgba(255, 255, 255, 0.09);
 }
@@ -158,9 +174,20 @@ body {
 }
 
 .timeline-clip.is-dragging {
+  /* Solid background so the picked-up clip reads clearly while dragging — audio
+     clips (waveform drawn on a separate layer) would otherwise look transparent. */
+  background-color: rgba(38, 42, 52, 0.96);
   box-shadow: 0 8px 24px rgba(0, 0, 0, 0.4);
 }
 
+/* Keep the white selection outline while dragging (a plain box-shadow alone gets
+   overridden by .is-dragging's drop shadow, so re-state both together). */
+.timeline-clip.is-selected.is-dragging {
+  box-shadow:
+    0 0 0 1.5px rgba(255, 255, 255, 0.85),
+    0 8px 24px rgba(0, 0, 0, 0.4);
+}
+
 .timeline-clip[data-active].is-selected.is-dragging {
   box-shadow:
     0 0 0 1.5px rgba(255, 255, 255, 0.85),

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;
+}

package/src/utils/assetPreviewStore.ts

@@ -0,0 +1,33 @@
+/**
+ * Tiny Zustand slice that carries the "asset preview overlay" state.
+ *
+ * When a user clicks an asset card that has NOT yet been added to the
+ * timeline the overlay fires up: a dark scrim + centered media element
+ * (img / video / audio) + filename label rendered inside PreviewPane.
+ *
+ * State lives here so AssetsTab (sidebar) and PreviewPane (preview column)
+ * can communicate without prop-drilling through the multi-layer EditorShell
+ * tree. The store is project-scoped: NLEProvider (NLEContext.tsx) clears it
+ * whenever `projectId` changes, so a preview opened in one project can't
+ * bleed into another (the overlay itself stays mounted across project
+ * switches — EditorShell isn't keyed by projectId).
+ */
+import { create } from "zustand";
+
+interface AssetPreviewState {
+  /** Project-relative asset path currently being previewed, or null. */
+  previewAsset: string | null;
+  /** projectId for which the preview was opened (used to build the serve URL). */
+  previewProjectId: string | null;
+  /** Open a media preview for the given asset. */
+  setPreviewAsset: (asset: string, projectId: string) => void;
+  /** Close the preview overlay. */
+  clearPreviewAsset: () => void;
+}
+
+export const useAssetPreviewStore = create<AssetPreviewState>((set) => ({
+  previewAsset: null,
+  previewProjectId: null,
+  setPreviewAsset: (asset, projectId) => set({ previewAsset: asset, previewProjectId: projectId }),
+  clearPreviewAsset: () => set({ previewAsset: null, previewProjectId: null }),
+}));

package/src/utils/blockInstaller.ts

@@ -2,9 +2,10 @@ import type { RegistryItem } from "@hyperframes/core/registry";
 import type { TimelineElement } from "../player";
 import {
   insertTimelineAssetIntoSource,
-  resolveTimelineAssetInitialGeometry,
+  resolveTimelineAssetCompositionSize,
 } from "./timelineAssetDrop";
 import { collectHtmlIds } from "./studioHelpers";
+import { generateId } from "./generateId";
 import { formatTimelineAttributeNumber } from "../player/components/timelineEditing";
 import { saveProjectFilesWithHistory } from "./studioFileHistory";
 import type { EditHistoryKind } from "./editHistory";
@@ -120,7 +121,9 @@ export async function addBlockToProject(
       );
 
       const isBlock = block.type === "hyperframes:block";
-      const hostDims = resolveTimelineAssetInitialGeometry(originalContent);
+      const { width: hostWidth, height: hostHeight } =
+        resolveTimelineAssetCompositionSize(originalContent);
+      const hostDims = { left: 0, top: 0, width: hostWidth, height: hostHeight };
 
       const currentTime = opts.currentTime ?? 0;
       const start = placement
@@ -152,6 +155,11 @@ export async function addBlockToProject(
 
       const subCompHtml = [
         `<div`,
+        // A stable id (+ hf-id) is what authored sub-comps carry; without it the
+        // timeline can't dedup the host and renders duplicate clips that multiply
+        // on every interaction. Matches the authored-comp shape.
+        `  id="${compId}"`,
+        `  data-hf-id="hf-${generateId()}"`,
         `  data-composition-id="${compId}"`,
         `  data-composition-src="${compositionFile}"`,
         `  data-start="${formatTimelineAttributeNumber(start)}"`,

package/src/utils/canvasNudgeGate.test.ts

@@ -0,0 +1,31 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { __resetForTests, acquireCanvasNudgeKeys, canvasNudgeKeysClaimed } from "./canvasNudgeGate";
+
+describe("canvasNudgeGate", () => {
+  // The claim counter is module-level state; reset it so an unbalanced claim in one
+  // test can't leak into the next.
+  beforeEach(() => {
+    __resetForTests();
+  });
+
+  it("reports claimed while at least one claim is held", () => {
+    expect(canvasNudgeKeysClaimed()).toBe(false);
+    const releaseA = acquireCanvasNudgeKeys();
+    const releaseB = acquireCanvasNudgeKeys();
+    expect(canvasNudgeKeysClaimed()).toBe(true);
+    releaseA();
+    expect(canvasNudgeKeysClaimed()).toBe(true);
+    releaseB();
+    expect(canvasNudgeKeysClaimed()).toBe(false);
+  });
+
+  it("makes release idempotent so an effect re-run cannot underflow", () => {
+    const release = acquireCanvasNudgeKeys();
+    release();
+    release();
+    expect(canvasNudgeKeysClaimed()).toBe(false);
+    const releaseNext = acquireCanvasNudgeKeys();
+    expect(canvasNudgeKeysClaimed()).toBe(true);
+    releaseNext();
+  });
+});

package/src/utils/canvasNudgeGate.ts

@@ -0,0 +1,32 @@
+/**
+ * Arrow-key ownership gate between the canvas nudge (DomEditOverlay) and the
+ * playback frame-step shortcuts (usePlaybackKeyboard). Both listen for arrow
+ * keys with window capture listeners, and their relative order depends on
+ * mount order (DomEditOverlay remounts when caption edit mode toggles), so
+ * `event.defaultPrevented` alone can't arbitrate. While a nudgeable canvas
+ * selection holds a claim, the playback handler skips ArrowLeft/ArrowRight.
+ */
+
+let claims = 0;
+
+/** Claim the arrow keys for canvas nudging. Returns an idempotent release. */
+export function acquireCanvasNudgeKeys(): () => void {
+  claims += 1;
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    claims -= 1;
+  };
+}
+
+/** True while a nudgeable canvas selection owns the arrow keys. */
+export function canvasNudgeKeysClaimed(): boolean {
+  return claims > 0;
+}
+
+/** Test-only: reset the module-level claim counter so leaked claims from one test
+ *  can't bleed into the next (call in a `beforeEach`). */
+export function __resetForTests(): void {
+  claims = 0;
+}

package/src/utils/editHistory.test.ts

@@ -209,6 +209,41 @@ describe("edit history", () => {
     expect(state.undo[0].files["index.html"].after).toBe("c");
   });
 
+  it("merges a lane-change move with its z-reorder past the default window via entry coalesceMs", () => {
+    // The z entry records only after the move persist's round-trip — often >300ms.
+    // Both sides pass coalesceMs: 5000 with the shared gesture key so the pair
+    // still folds into ONE undo step.
+    const move = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Move timeline clips",
+      kind: "timeline",
+      coalesceKey: "clip-lane-move:1",
+      coalesceMs: 5000,
+      files: { "index.html": { before: "a", after: "b" } },
+      now: 100,
+      id: "move-entry",
+    });
+    const zReorder = buildEditHistoryEntry({
+      projectId: "project-1",
+      label: "Reorder layers",
+      kind: "manual",
+      coalesceKey: "clip-lane-move:1",
+      coalesceMs: 5000,
+      files: { "index.html": { before: "b", after: "c" } },
+      now: 500,
+      id: "z-entry",
+    });
+
+    const state = pushEditHistoryEntry(
+      pushEditHistoryEntry(createEmptyEditHistory(), move),
+      zReorder,
+    );
+
+    expect(state.undo).toHaveLength(1);
+    expect(state.undo[0].files["index.html"].before).toBe("a");
+    expect(state.undo[0].files["index.html"].after).toBe("c");
+  });
+
   it("folds a slow GSAP follow-up into the timing edit via a per-entry coalesceMs override", () => {
     const timing = buildEditHistoryEntry({
       projectId: "project-1",

package/src/utils/gsapSoftReload.test.ts

@@ -1,7 +1,12 @@
 // @vitest-environment happy-dom
 
 import { describe, it, expect, vi } from "vitest";
-import { applySoftReload, ensureMotionPathPluginLoaded } from "./gsapSoftReload";
+import {
+  applySoftReload,
+  ensureMotionPathPluginLoaded,
+  diffSoftReloadableRestore,
+  applyUndoRestoreToPreview,
+} from "./gsapSoftReload";
 
 const SCRIPT_TEXT = `
 window.__timelines = window.__timelines || {};
@@ -447,3 +452,116 @@ describe("applySoftReload authored-opacity restore", () => {
     expect(restoreOpacity(el)).toBe("");
   });
 });
+
+// ── Bug 2: undo/redo restore soft-apply ──────────────────────────────────────
+
+const wrap = (body: string) => `<html><body>${body}</body></html>`;
+
+describe("diffSoftReloadableRestore", () => {
+  it("reports the changed id for an attribute/inline-style-only diff", () => {
+    const prev = wrap(`<div id="a" style="translate: 10px 10px">t</div>`);
+    const next = wrap(`<div id="a" style="translate: 0px 0px">t</div>`);
+    expect(diffSoftReloadableRestore(prev, next)).toEqual({ changedElementIds: ["a"] });
+  });
+
+  it("treats a structural change (added element) as NOT soft-reloadable", () => {
+    const prev = wrap(`<div id="a">t</div>`);
+    const next = wrap(`<div id="a">t</div><div id="a-split">t</div>`);
+    expect(diffSoftReloadableRestore(prev, next)).toBeNull();
+  });
+
+  it("treats an element text/child change as NOT soft-reloadable", () => {
+    const prev = wrap(`<div id="a">one</div>`);
+    const next = wrap(`<div id="a">two</div>`);
+    expect(diffSoftReloadableRestore(prev, next)).toBeNull();
+  });
+
+  it("allows a GSAP-script-only change (no id'd-attribute diff)", () => {
+    const prev = wrap(
+      `<div id="a">t</div><script>window.__timelines["root"]=gsap.timeline().to("#a",{x:1});</script>`,
+    );
+    const next = wrap(
+      `<div id="a">t</div><script>window.__timelines["root"]=gsap.timeline().to("#a",{x:9});</script>`,
+    );
+    expect(diffSoftReloadableRestore(prev, next)).toEqual({ changedElementIds: [] });
+  });
+});
+
+function buildLiveIframe(bodyHtml: string) {
+  const doc = document.implementation.createHTMLDocument("");
+  doc.body.innerHTML = bodyHtml;
+  const contentWindow = {
+    gsap: { timeline: () => {} },
+    __hfForceTimelineRebind: () => {},
+    __timelines: {} as Record<string, unknown>,
+    __player: { getTime: () => 3, seek: vi.fn() },
+    __hfStudioManualEditsApply: vi.fn(),
+  };
+  return {
+    iframe: { contentWindow, contentDocument: doc } as unknown as HTMLIFrameElement,
+    contentWindow,
+    doc,
+  };
+}
+
+describe("applyUndoRestoreToPreview", () => {
+  const ROOT = "index.html";
+
+  it("soft-applies an attribute/style-only restore: syncs the live element, no full reload", () => {
+    const { iframe, contentWindow, doc } = buildLiveIframe(
+      `<div id="a" style="translate: 10px 10px" data-hf-path-offset="true">t</div>`,
+    );
+    const reloadPreview = vi.fn();
+    const files = {
+      [ROOT]: {
+        previous: wrap(
+          `<div id="a" style="translate: 10px 10px" data-hf-path-offset="true">t</div>`,
+        ),
+        restored: wrap(`<div id="a" style="translate: 0px 0px" data-hf-path-offset="true">t</div>`),
+      },
+    };
+    const outcome = applyUndoRestoreToPreview(iframe, ROOT, files, 3, reloadPreview);
+    expect(outcome).toBe("soft");
+    expect(reloadPreview).not.toHaveBeenCalled();
+    // Live element reverted to the restored inline style.
+    expect(doc.getElementById("a")!.getAttribute("style")).toBe("translate: 0px 0px");
+    // No GSAP script in the restore → the manual-edit reapply runs, playhead held.
+    expect(contentWindow.__player.seek).toHaveBeenCalledWith(3);
+    expect(contentWindow.__hfStudioManualEditsApply).toHaveBeenCalled();
+  });
+
+  it("full-reloads a multi-file restore", () => {
+    const { iframe } = buildLiveIframe(`<div id="a">t</div>`);
+    const reloadPreview = vi.fn();
+    const files = {
+      [ROOT]: {
+        previous: wrap(`<div id="a" style="x">t</div>`),
+        restored: wrap(`<div id="a">t</div>`),
+      },
+      "scenes/intro.html": { previous: "a", restored: "b" },
+    };
+    expect(applyUndoRestoreToPreview(iframe, ROOT, files, 3, reloadPreview)).toBe("full");
+    expect(reloadPreview).toHaveBeenCalledTimes(1);
+  });
+
+  it("full-reloads a structural restore (split/delete undo)", () => {
+    const { iframe } = buildLiveIframe(`<div id="a">t</div><div id="a-split">t</div>`);
+    const reloadPreview = vi.fn();
+    const files = {
+      [ROOT]: {
+        previous: wrap(`<div id="a">t</div><div id="a-split">t</div>`),
+        restored: wrap(`<div id="a">t</div>`),
+      },
+    };
+    expect(applyUndoRestoreToPreview(iframe, ROOT, files, 3, reloadPreview)).toBe("full");
+    expect(reloadPreview).toHaveBeenCalledTimes(1);
+  });
+
+  it("full-reloads when the restore touches a sub-comp, not the active comp", () => {
+    const { iframe } = buildLiveIframe(`<div id="a">t</div>`);
+    const reloadPreview = vi.fn();
+    const files = { "scenes/intro.html": { previous: "a", restored: "b" } };
+    expect(applyUndoRestoreToPreview(iframe, ROOT, files, 3, reloadPreview)).toBe("full");
+    expect(reloadPreview).toHaveBeenCalledTimes(1);
+  });
+});