@hyperframes/studio 0.7.55 → 0.7.56

package/src/hooks/useTimelineEditing.test.tsx

@@ -159,7 +159,7 @@ type TimelineRecordEdit = NonNullable<
 function renderTimelineEditingHookWithLifecycle(input: {
   timelineElements: TimelineElement[];
   iframe: HTMLIFrameElement;
-  commitPositionPatchToHtml: ReturnType<typeof vi.fn<(...args: unknown[]) => Promise<void>>>;
+  commitDomEditPatchBatches: ReturnType<typeof vi.fn<(...args: unknown[]) => Promise<void>>>;
 }): {
   move: ReturnType<typeof useTimelineEditing>["handleTimelineElementMove"];
   unmount: () => void;
@@ -176,7 +176,7 @@ function renderTimelineEditingHookWithLifecycle(input: {
       projectIdRef: { current: "p1" },
       reloadPreview: vi.fn(),
       clearDomSelection: vi.fn(),
-      commitPositionPatchToHtml: input.commitPositionPatchToHtml,
+      commitDomEditPatchBatches: input.commitDomEditPatchBatches,
     });
     const commitRef = useRef(lifecycle.handleDomZIndexReorderCommit);
     commitRef.current = lifecycle.handleDomZIndexReorderCommit;
@@ -481,11 +481,11 @@ describe("useTimelineEditing timeline z-index reorder", () => {
     ]);
     const front = timelineElement({ id: "front", track: 0, zIndex: 0 });
     const back = timelineElement({ id: "back", track: 1, zIndex: 0 });
-    const commitPositionPatchToHtml = vi.fn<(...args: unknown[]) => Promise<void>>(async () => {});
+    const commitDomEditPatchBatches = vi.fn<(...args: unknown[]) => Promise<void>>(async () => {});
     const { move, unmount } = renderTimelineEditingHookWithLifecycle({
       timelineElements: [front, back],
       iframe,
-      commitPositionPatchToHtml,
+      commitDomEditPatchBatches,
     });
 
     await act(async () => {
@@ -501,8 +501,11 @@ describe("useTimelineEditing timeline z-index reorder", () => {
       await flushAsyncWork();
     });
 
-    expect(commitPositionPatchToHtml).toHaveBeenCalled();
-    expect(commitPositionPatchToHtml.mock.calls[0]![1]).toEqual([
+    expect(commitDomEditPatchBatches).toHaveBeenCalled();
+    const batch = commitDomEditPatchBatches.mock.calls[0]![0] as Array<{
+      patches: Array<{ operations: unknown[] }>;
+    }>;
+    expect(batch[0]?.patches[0]?.operations).toEqual([
       { type: "inline-style", property: "z-index", value: "2" },
       { type: "inline-style", property: "position", value: "relative" },
     ]);
@@ -522,14 +525,13 @@ describe("useTimelineEditing timeline z-index reorder", () => {
       { ...back, hasExplicitZIndex: false },
     ]);
     const saveError = new Error("save failed");
-    const commitPositionPatchToHtml = vi
+    const commitDomEditPatchBatches = vi
       .fn<(...args: unknown[]) => Promise<void>>()
-      .mockResolvedValueOnce(undefined)
       .mockRejectedValueOnce(saveError);
     const { move, unmount } = renderTimelineEditingHookWithLifecycle({
       timelineElements: [front, back],
       iframe,
-      commitPositionPatchToHtml,
+      commitDomEditPatchBatches,
     });
     const doc = iframe.contentDocument;
     if (!doc) throw new Error("Expected iframe document");
@@ -576,29 +578,24 @@ describe("useTimelineEditing timeline z-index reorder", () => {
     unmount();
   });
 
-  it("waits for every lifecycle z-index save before resolving a reorder", async () => {
+  it("waits for the lifecycle z-index batch before resolving a reorder", async () => {
     const iframe = createPreviewIframe([
       { id: "front", track: 0, style: "position: relative; z-index: 1" },
       { id: "back", track: 1, style: "position: relative; z-index: 0" },
     ]);
     const front = timelineElement({ id: "front", track: 0, zIndex: 1 });
     const back = timelineElement({ id: "back", track: 1, zIndex: 0 });
-    let releaseFirst!: () => void;
-    let releaseSecond!: () => void;
-    const firstSave = new Promise<void>((resolve) => {
-      releaseFirst = resolve;
+    let releaseBatch!: () => void;
+    const batchSave = new Promise<void>((resolve) => {
+      releaseBatch = resolve;
     });
-    const secondSave = new Promise<void>((resolve) => {
-      releaseSecond = resolve;
-    });
-    const commitPositionPatchToHtml = vi
+    const commitDomEditPatchBatches = vi
       .fn<(...args: unknown[]) => Promise<void>>()
-      .mockReturnValueOnce(firstSave)
-      .mockReturnValueOnce(secondSave);
+      .mockReturnValueOnce(batchSave);
     const { move, unmount } = renderTimelineEditingHookWithLifecycle({
       timelineElements: [front, back],
       iframe,
-      commitPositionPatchToHtml,
+      commitDomEditPatchBatches,
     });
     let settled = false;
 
@@ -621,17 +618,11 @@ describe("useTimelineEditing timeline z-index reorder", () => {
       await flushAsyncWork();
     });
 
-    expect(commitPositionPatchToHtml).toHaveBeenCalledTimes(2);
-    expect(settled).toBe(false);
-
-    await act(async () => {
-      releaseFirst();
-      await flushAsyncWork();
-    });
+    expect(commitDomEditPatchBatches).toHaveBeenCalledTimes(1);
     expect(settled).toBe(false);
 
     await act(async () => {
-      releaseSecond();
+      releaseBatch();
       await movePromise;
       await flushAsyncWork();
     });

package/src/hooks/useTimelineEditingTypes.ts

@@ -22,6 +22,7 @@ export type TimelineZIndexReorderCommit = (
     sourceFile: string;
     key?: string;
   }>,
+  coalesceKey?: string,
 ) => Promise<void>;
 
 export interface UseTimelineEditingOptions {
@@ -43,3 +44,8 @@ export interface UseTimelineEditingOptions {
   forceReloadSdkSession?: () => void;
   handleDomZIndexReorderCommitRef?: MutableRefObject<TimelineZIndexReorderCommit | null>;
 }
+
+export type TimelineFileDropHandler = (
+  files: File[],
+  placement?: { start: number; track: number },
+) => Promise<void>;

package/src/hooks/useTimelineGroupEditing.ts

@@ -21,6 +21,7 @@ import {
 export interface TimelineGroupMoveChange {
   element: TimelineElement;
   start: number;
+  track?: number;
 }
 
 export interface TimelineGroupResizeChange {
@@ -152,9 +153,13 @@ export function useTimelineGroupEditing({
     (changes: TimelineGroupMoveChange[], options?: TimelineGroupCommitOptions) => {
       if (changes.length === 0) return Promise.resolve();
       for (const change of changes) {
-        patchIframeDomTiming(previewIframeRef.current, change.element, [
+        const attrs: Array<[string, string]> = [
           ["data-start", formatTimelineAttributeNumber(change.start)],
-        ]);
+        ];
+        if (change.track != null) {
+          attrs.push(["data-track-index", formatTimelineAttributeNumber(change.track)]);
+        }
+        patchIframeDomTiming(previewIframeRef.current, change.element, attrs);
       }
 
       const maxEnd = Math.max(...changes.map((change) => change.start + change.element.duration));
@@ -169,7 +174,10 @@ export function useTimelineGroupEditing({
             : null,
         );
         const canUseSdk =
-          !needsExtension && sharedPath !== null && sdkChanges.every((change) => change !== null);
+          !needsExtension &&
+          sharedPath !== null &&
+          changes.every((change) => change.track == null) &&
+          sdkChanges.every((change) => change !== null);
         if (canUseSdk) {
           const handled = await sdkTimingBatchPersist(
             sdkChanges.filter((change): change is NonNullable<typeof change> => change !== null),
@@ -194,7 +202,13 @@ export function useTimelineGroupEditing({
           changes.map((change) => ({
             element: change.element,
             buildPatches: (original, target) =>
-              buildTimelineMoveTimingPatch(original, target, change.start, change.element.duration),
+              buildTimelineMoveTimingPatch(
+                original,
+                target,
+                change.start,
+                change.element.duration,
+                change.track,
+              ),
           })),
           coalesceKey,
         );

package/src/index.ts

@@ -1,5 +1,5 @@
 // NLE Layout
-export { NLELayout } from "./components/nle/NLELayout";
+export { EditorShell } from "./components/EditorShell";
 export { NLEPreview } from "./components/nle/NLEPreview";
 export { CompositionBreadcrumb } from "./components/nle/CompositionBreadcrumb";
 export type { CompositionLevel } from "./components/nle/CompositionBreadcrumb";

package/src/player/components/ImageThumbnail.test.tsx

@@ -0,0 +1,173 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { ImageThumbnail } from "./ImageThumbnail";
+
+Object.defineProperty(globalThis, "IS_REACT_ACT_ENVIRONMENT", {
+  configurable: true,
+  value: true,
+});
+
+// --- Observer stubs: fire "intersecting" immediately on observe ---
+class MockIntersectionObserver {
+  private cb: IntersectionObserverCallback;
+  constructor(cb: IntersectionObserverCallback) {
+    this.cb = cb;
+  }
+  observe() {
+    this.cb(
+      [{ isIntersecting: true } as IntersectionObserverEntry],
+      this as unknown as IntersectionObserver,
+    );
+  }
+  disconnect() {}
+  unobserve() {}
+  takeRecords(): IntersectionObserverEntry[] {
+    return [];
+  }
+}
+
+class MockResizeObserver {
+  observe() {}
+  disconnect() {}
+  unobserve() {}
+}
+
+// --- Image stub: captures instances so tests fire load/error deterministically ---
+class MockImage {
+  static instances: MockImage[] = [];
+  onload: (() => void) | null = null;
+  onerror: (() => void) | null = null;
+  naturalWidth = 0;
+  naturalHeight = 0;
+  src = "";
+  constructor() {
+    MockImage.instances.push(this);
+  }
+}
+
+const originalIO = globalThis.IntersectionObserver;
+const originalRO = globalThis.ResizeObserver;
+const originalImage = globalThis.Image;
+
+let host: HTMLDivElement;
+let root: Root | null = null;
+
+beforeEach(() => {
+  globalThis.IntersectionObserver =
+    MockIntersectionObserver as unknown as typeof IntersectionObserver;
+  globalThis.ResizeObserver = MockResizeObserver as unknown as typeof ResizeObserver;
+  globalThis.Image = MockImage as unknown as typeof Image;
+  MockImage.instances = [];
+  host = document.createElement("div");
+  document.body.append(host);
+});
+
+afterEach(() => {
+  act(() => root?.unmount());
+  root = null;
+  globalThis.IntersectionObserver = originalIO;
+  globalThis.ResizeObserver = originalRO;
+  globalThis.Image = originalImage;
+  document.body.innerHTML = "";
+});
+
+function render(props: { imageSrc: string; label?: string; labelColor?: string }) {
+  root = createRoot(host);
+  act(() => {
+    root!.render(
+      <ImageThumbnail
+        imageSrc={props.imageSrc}
+        label={props.label ?? ""}
+        labelColor={props.labelColor ?? "#fff"}
+      />,
+    );
+  });
+}
+
+function lastProbe(): MockImage {
+  const probe = MockImage.instances.at(-1);
+  expect(probe).toBeDefined();
+  return probe!;
+}
+
+/** Assert at least one tile rendered and the first tile serves `expectedSrc`. */
+function expectFirstTileSrc(expectedSrc: string): void {
+  const imgs = [...host.querySelectorAll("img")];
+  expect(imgs.length).toBeGreaterThanOrEqual(1);
+  expect(imgs[0].getAttribute("src")).toBe(expectedSrc);
+}
+
+describe("ImageThumbnail", () => {
+  it("shows the loading shimmer before the image resolves", () => {
+    render({ imageSrc: "/api/projects/p/preview/assets/pic.png" });
+    expect(host.querySelector(".animate-pulse")).not.toBeNull();
+    expect(host.querySelectorAll("img").length).toBe(0);
+  });
+
+  it("probes the resolved src and renders repeated object-cover tiles on load", () => {
+    render({ imageSrc: "/api/projects/p/preview/assets/pic.png" });
+    const probe = lastProbe();
+    expect(probe.src).toBe("/api/projects/p/preview/assets/pic.png");
+
+    act(() => {
+      probe.naturalWidth = 1920;
+      probe.naturalHeight = 1080;
+      probe.onload?.();
+    });
+
+    const imgs = [...host.querySelectorAll("img")];
+    expect(imgs.length).toBeGreaterThanOrEqual(1);
+    for (const img of imgs) {
+      expect(img.getAttribute("src")).toBe("/api/projects/p/preview/assets/pic.png");
+      expect(img.className).toContain("object-cover");
+    }
+    expect(host.querySelector(".animate-pulse")).toBeNull();
+  });
+
+  it("drops the shimmer and renders no tiles when a raster image fails to load", () => {
+    render({ imageSrc: "/api/projects/p/preview/assets/missing.png" });
+    act(() => lastProbe().onerror?.());
+    expect(host.querySelectorAll("img").length).toBe(0);
+    expect(host.querySelector(".animate-pulse")).toBeNull();
+  });
+
+  it("renders tiles at 16:9 when an SVG has no intrinsic dimensions (naturalWidth=0)", () => {
+    render({ imageSrc: "/api/projects/p/preview/assets/logo.svg" });
+    const probe = lastProbe();
+
+    act(() => {
+      // naturalWidth stays 0 — SVG with no width/height attribute
+      probe.onload?.();
+    });
+
+    expectFirstTileSrc("/api/projects/p/preview/assets/logo.svg");
+    expect(host.querySelector(".animate-pulse")).toBeNull();
+  });
+
+  it("renders SVG tiles at 16:9 fallback even when the probe fires onerror", () => {
+    // Some browser/sandbox environments fire onerror for SVGs even though the
+    // <img> element itself can render the file — we must not blank the strip.
+    render({ imageSrc: "/api/projects/p/preview/assets/icon.svg" });
+
+    act(() => lastProbe().onerror?.());
+
+    expectFirstTileSrc("/api/projects/p/preview/assets/icon.svg");
+    expect(host.querySelector(".animate-pulse")).toBeNull();
+  });
+
+  it("renders the label above the strip when provided", () => {
+    render({ imageSrc: "/x.png", label: "hero", labelColor: "#abc" });
+    act(() => {
+      const probe = lastProbe();
+      probe.naturalWidth = 100;
+      probe.naturalHeight = 100;
+      probe.onload?.();
+    });
+    const label = [...host.querySelectorAll("span")].find((s) => s.textContent === "hero");
+    expect(label).toBeDefined();
+    expect(label!.closest(".z-10")).not.toBeNull();
+  });
+});

package/src/player/components/ImageThumbnail.tsx

@@ -0,0 +1,160 @@
+import { memo, useRef, useState, useCallback, useEffect } from "react";
+import { useMountEffect } from "../../hooks/useMountEffect";
+import { computeThumbnailStrip } from "./thumbnailUtils";
+
+interface ImageThumbnailProps {
+  imageSrc: string;
+  label: string;
+  labelColor: string;
+}
+
+/**
+ * Renders a film-strip of a still image for a timeline clip. The image is a
+ * fixed-width tile (sized by its natural aspect ratio) repeated to fill the
+ * clip width — matching VideoThumbnail's visual pattern. Loading is lazy
+ * (IntersectionObserver) with the same shimmer fallback while decoding.
+ */
+export const ImageThumbnail = memo(function ImageThumbnail({
+  imageSrc,
+  label,
+  labelColor,
+}: ImageThumbnailProps) {
+  const [containerWidth, setContainerWidth] = useState(0);
+  const [visible, setVisible] = useState(false);
+  const [status, setStatus] = useState<"loading" | "loaded" | "error">("loading");
+  const [aspect, setAspect] = useState(16 / 9);
+  const ioRef = useRef<IntersectionObserver | null>(null);
+  const roRef = useRef<ResizeObserver | null>(null);
+
+  const setContainerRef = useCallback((el: HTMLDivElement | null) => {
+    ioRef.current?.disconnect();
+    roRef.current?.disconnect();
+    if (!el) return;
+
+    const measured = el.parentElement?.clientWidth || el.clientWidth;
+    setContainerWidth(measured);
+
+    ioRef.current = new IntersectionObserver(
+      ([entry]) => {
+        if (entry.isIntersecting) {
+          setVisible(true);
+          ioRef.current?.disconnect();
+        }
+      },
+      { rootMargin: "200px" },
+    );
+    // fallow-ignore-next-line code-duplication
+    ioRef.current.observe(el);
+
+    const target = el.parentElement || el;
+    roRef.current = new ResizeObserver(([entry]) => {
+      setContainerWidth(entry.contentRect.width);
+    });
+    roRef.current.observe(target);
+  }, []);
+
+  useMountEffect(() => () => {
+    ioRef.current?.disconnect();
+    roRef.current?.disconnect();
+  });
+
+  // Probe the image once visible — measures the natural aspect ratio so the
+  // tile width matches, and flips to the error state (plain clip background)
+  // if the src can't load. The browser cache makes the tile <img>s free.
+  //
+  // SVG handling: SVGs without intrinsic width/height report naturalWidth=0 on
+  // load (treat as success with the 16:9 default aspect) and may fire onerror
+  // in some environments even though the file is valid and can be displayed —
+  // fall back to loaded-at-16:9 rather than hiding the strip entirely.
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    if (!visible) return;
+    let cancelled = false;
+    setStatus("loading");
+
+    const isSvg = /\.svg($|\?)/i.test(imageSrc);
+
+    const probe = new Image();
+    probe.onload = () => {
+      if (cancelled) return;
+      if (probe.naturalWidth > 0 && probe.naturalHeight > 0) {
+        setAspect(probe.naturalWidth / probe.naturalHeight);
+      }
+      // naturalWidth===0 (e.g. SVG with no intrinsic dimensions) falls through
+      // to "loaded" with the default 16:9 aspect already set in state.
+      setStatus("loaded");
+    };
+    probe.onerror = () => {
+      if (cancelled) return;
+      // SVGs can fail the probe in certain browser/sandbox environments even
+      // though the <img> tiles themselves render fine (different security
+      // context). Show the strip at the 16:9 fallback rather than blanking.
+      if (isSvg) {
+        setStatus("loaded");
+      } else {
+        setStatus("error");
+      }
+    };
+    probe.src = imageSrc;
+
+    return () => {
+      cancelled = true;
+      probe.onload = null;
+      probe.onerror = null;
+      probe.src = "";
+    };
+  }, [visible, imageSrc]);
+
+  const { frameW, frameCount } = computeThumbnailStrip(containerWidth, aspect);
+
+  return (
+    <div ref={setContainerRef} className="absolute inset-0 overflow-hidden">
+      {visible && status === "loaded" && (
+        <div className="absolute inset-0 flex">
+          {Array.from({ length: frameCount }).map((_, i) => (
+            <div
+              key={i}
+              className="flex-shrink-0 h-full relative overflow-hidden bg-neutral-900"
+              style={{ width: frameW }}
+            >
+              <img
+                src={imageSrc}
+                alt=""
+                draggable={false}
+                loading="lazy"
+                className="absolute inset-0 w-full h-full object-cover"
+              />
+            </div>
+          ))}
+        </div>
+      )}
+
+      {visible && status === "loading" && (
+        <div
+          className="absolute inset-0 animate-pulse"
+          style={{
+            background:
+              "linear-gradient(90deg, rgba(255,255,255,0.02) 0%, rgba(255,255,255,0.05) 50%, rgba(255,255,255,0.02) 100%)",
+          }}
+        />
+      )}
+
+      {label && (
+        <div
+          className="absolute bottom-0 left-0 right-0 z-10 px-1.5 pb-0.5 pt-3"
+          style={{
+            background:
+              "linear-gradient(to top, rgba(0,0,0,0.85) 0%, rgba(0,0,0,0.4) 60%, transparent 100%)",
+          }}
+        >
+          <span
+            className="text-[9px] font-semibold truncate block leading-tight"
+            style={{ color: labelColor, textShadow: "0 1px 2px rgba(0,0,0,0.9)" }}
+          >
+            {label}
+          </span>
+        </div>
+      )}
+    </div>
+  );
+});

package/src/player/components/PlayheadIndicator.tsx

@@ -2,20 +2,44 @@
 /**
  * Shared playhead visual used by TimelineCanvas (real playhead) and
  * TimelineEditorNotice (animated illustration).
+ *
+ * The vertical line + glow span the full track height; the grab-handle HEAD is
+ * `position: sticky; top: 0` so it pins to the top of the (vertically) scrolling
+ * track area — the ruler is sticky too, so the head stays visible and grabbable
+ * no matter how far the tracks are scrolled. The head is OUTLINE-only at rest and
+ * FILLED while the playhead is actively held/scrubbed (`scrubbing`).
  */
 interface PlayheadIndicatorProps {
   /** CSS color, defaults to the HF accent variable */
   color?: string;
   /** Glow shadow color, defaults to translucent accent */
   glowColor?: string;
+  /** Whether the playhead is being actively scrubbed — fills the head. */
+  scrubbing?: boolean;
+  /**
+   * When false, the head chip is rendered in normal flow (top:1) instead of the
+   * sticky pin — used by the static illustration where there is no scroll area.
+   */
+  stickyHead?: boolean;
 }
 
 export function PlayheadIndicator({
   color = "var(--hf-accent, #3CE6AC)",
   glowColor = "rgba(60,230,172,0.14)",
+  scrubbing = false,
+  stickyHead = true,
 }: PlayheadIndicatorProps) {
+  // Head chip dimensions — used to compute the centering offset and the
+  // point where the vertical line starts (so it begins at the head's bottom
+  // edge rather than running through the hollow diamond center).
+  const HEAD_W = 9;
+  const HEAD_H = 9;
+  // marginTop(1) + HEAD_H = where the line should start.
+  const HEAD_TOTAL_H = 1 + HEAD_H;
+
   return (
     <>
+      {/* Glow — spans full height, centered on the line. */}
       <div
         aria-hidden="true"
         className="absolute top-0 bottom-0"
@@ -26,23 +50,44 @@ export function PlayheadIndicator({
           background: `radial-gradient(closest-side, ${glowColor}, transparent)`,
         }}
       />
+      {/* Vertical line — starts at the bottom edge of the head chip so nothing
+          shows through the hollow diamond center. */}
       <div
-        className="absolute top-0 bottom-0"
+        className="absolute bottom-0"
         style={{
           left: "50%",
+          top: HEAD_TOTAL_H,
           width: 1,
           marginLeft: -0.5,
           background: color,
           boxShadow: `0 0 6px ${glowColor}`,
         }}
       />
-      <div className="absolute" style={{ left: "50%", top: 1, transform: "translateX(-50%)" }}>
+      {/* Head chip — sticky so it pins to the ruler while tracks scroll.
+          Centering logic: wrapper width = HEAD_W (chip forces it). The line sits
+          at wrapper.left + HEAD_W/2 (left:"50%" of wrapper). The sticky element's
+          natural flow position is wrapper.left; so placing it there with no
+          horizontal translate puts its LEFT edge at wrapper.left and its CENTER
+          at wrapper.left + HEAD_W/2 — exactly on the line. */}
+      <div
+        className={stickyHead ? "sticky" : "absolute"}
+        style={{
+          left: 0,
+          top: stickyHead ? 0 : 1,
+          // Zero height keeps it from covering rows (sticky strip trick).
+          height: stickyHead ? 0 : undefined,
+        }}
+      >
         <div
           style={{
-            width: 9,
-            height: 9,
+            width: HEAD_W,
+            height: HEAD_H,
             borderRadius: 2,
-            background: color,
+            marginTop: 1,
+            // Outline-only at rest, filled while scrubbing.
+            background: scrubbing ? color : "transparent",
+            border: `1.5px solid ${color}`,
+            boxSizing: "border-box",
             boxShadow: `0 1px 3px rgba(0,0,0,0.55), 0 0 5px ${glowColor}`,
             transform: "rotate(45deg)",
           }}