@hyperframes/studio 0.7.54 → 0.7.56

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)",
           }}

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

@@ -18,7 +18,14 @@ import {
   shouldHandleTimelineDeleteKey,
   shouldAutoScrollTimeline,
 } from "./Timeline";
-import { RULER_H, TRACK_H } from "./timelineLayout";
+import {
+  GUTTER,
+  MIN_TIMELINE_EXTENT_S,
+  RULER_H,
+  TRACK_H,
+  getTimelineDisplayContentWidth,
+  getTimelineFitPps,
+} from "./timelineLayout";
 import { formatTime } from "../lib/time";
 import { usePlayerStore } from "../store/playerStore";
 import { TimelineEditProvider } from "../../contexts/TimelineEditContext";
@@ -323,30 +330,30 @@ describe("generateTicks", () => {
 });
 
 describe("formatTime", () => {
-  it("formats 0 seconds as 0:00", () => {
-    expect(formatTime(0)).toBe("0:00");
+  it("formats 0 seconds as 00:00", () => {
+    expect(formatTime(0)).toBe("00:00");
   });
 
   // fallow-ignore-next-line code-duplication
   it("formats seconds below a minute", () => {
-    expect(formatTime(5)).toBe("0:05");
-    expect(formatTime(30)).toBe("0:30");
-    expect(formatTime(59)).toBe("0:59");
+    expect(formatTime(5)).toBe("00:05");
+    expect(formatTime(30)).toBe("00:30");
+    expect(formatTime(59)).toBe("00:59");
   });
 
   it("formats exactly one minute", () => {
-    expect(formatTime(60)).toBe("1:00");
+    expect(formatTime(60)).toBe("01:00");
   });
 
   it("formats minutes and seconds", () => {
-    expect(formatTime(90)).toBe("1:30");
-    expect(formatTime(125)).toBe("2:05");
+    expect(formatTime(90)).toBe("01:30");
+    expect(formatTime(125)).toBe("02:05");
   });
 
   it("floors fractional seconds", () => {
-    expect(formatTime(5.7)).toBe("0:05");
-    expect(formatTime(59.9)).toBe("0:59");
-    expect(formatTime(90.5)).toBe("1:30");
+    expect(formatTime(5.7)).toBe("00:05");
+    expect(formatTime(59.9)).toBe("00:59");
+    expect(formatTime(90.5)).toBe("01:30");
   });
 
   it("handles large values", () => {
@@ -354,16 +361,16 @@ describe("formatTime", () => {
     expect(formatTime(3661)).toBe("61:01");
   });
 
-  it("zero-pads seconds to two digits", () => {
-    expect(formatTime(1)).toBe("0:01");
-    expect(formatTime(9)).toBe("0:09");
-    expect(formatTime(61)).toBe("1:01");
+  it("zero-pads minutes and seconds to two digits", () => {
+    expect(formatTime(1)).toBe("00:01");
+    expect(formatTime(9)).toBe("00:09");
+    expect(formatTime(61)).toBe("01:01");
   });
 });
 
 describe("formatTimelineTickLabel", () => {
   it("uses minute-second labels for normal timeline intervals", () => {
-    expect(formatTimelineTickLabel(90, 180, 5)).toBe("1:30");
+    expect(formatTimelineTickLabel(90, 180, 5)).toBe("01:30");
   });
 
   it("uses hour labels for long timelines", () => {
@@ -371,7 +378,7 @@ describe("formatTimelineTickLabel", () => {
   });
 
   it("shows subsecond labels when the major ruler interval is below one second", () => {
-    expect(formatTimelineTickLabel(1.5, 3, 0.5)).toBe("0:01.5");
+    expect(formatTimelineTickLabel(1.5, 3, 0.5)).toBe("00:01.5");
   });
 });
 
@@ -390,6 +397,80 @@ describe("shouldAutoScrollTimeline", () => {
   });
 });
 
+describe("getTimelineFitPps (min 60s extent)", () => {
+  const viewport = 632; // usable width = 632 - GUTTER - 2 = 598
+
+  it("computes fit pps against the 60s floor for short compositions", () => {
+    // A 10s comp maps 60s onto the viewport → the comp takes ~1/6 of the width.
+    const pps = getTimelineFitPps(viewport, 10);
+    expect(pps).toBeCloseTo((viewport - GUTTER - 2) / MIN_TIMELINE_EXTENT_S);
+    expect(10 * pps).toBeCloseTo((viewport - GUTTER - 2) / 6);
+  });
+
+  it("keeps filling the viewport with the composition when it is 60s or longer", () => {
+    expect(getTimelineFitPps(viewport, 60)).toBeCloseTo((viewport - GUTTER - 2) / 60);
+    expect(getTimelineFitPps(viewport, 120)).toBeCloseTo((viewport - GUTTER - 2) / 120);
+  });
+
+  it("falls back to 100 pps before the viewport is measured", () => {
+    expect(getTimelineFitPps(0, 10)).toBe(100);
+    expect(getTimelineFitPps(GUTTER, 10)).toBe(100);
+    expect(getTimelineFitPps(Number.NaN, 10)).toBe(100);
+  });
+
+  it("uses the floor for zero/invalid durations", () => {
+    expect(getTimelineFitPps(viewport, 0)).toBeCloseTo(
+      (viewport - GUTTER - 2) / MIN_TIMELINE_EXTENT_S,
+    );
+    expect(getTimelineFitPps(viewport, Number.NaN)).toBeCloseTo(
+      (viewport - GUTTER - 2) / MIN_TIMELINE_EXTENT_S,
+    );
+  });
+});
+
+describe("getTimelineDisplayContentWidth", () => {
+  it("always spans at least MIN_TIMELINE_EXTENT_S seconds of content", () => {
+    // 10s of content at 20 pps = 200px; the floor keeps 60s (1200px) rendered.
+    expect(
+      getTimelineDisplayContentWidth({ trackContentWidth: 200, viewportWidth: 400, pps: 20 }),
+    ).toBe(MIN_TIMELINE_EXTENT_S * 20);
+  });
+
+  it("still fills the viewport when that is larger than the 60s floor", () => {
+    expect(
+      getTimelineDisplayContentWidth({ trackContentWidth: 200, viewportWidth: 2000, pps: 5 }),
+    ).toBe(2000 - GUTTER - 2);
+  });
+
+  it("tracks a drag ghost past every other bound (drag-to-extend)", () => {
+    expect(
+      getTimelineDisplayContentWidth({
+        trackContentWidth: 500,
+        viewportWidth: 400,
+        pps: 5,
+        dragGhostEndPx: 5000,
+      }),
+    ).toBe(5000);
+  });
+
+  it("tracks a resize (trim) ghost past every other bound (trim-to-extend)", () => {
+    expect(
+      getTimelineDisplayContentWidth({
+        trackContentWidth: 500,
+        viewportWidth: 400,
+        pps: 5,
+        resizeGhostEndPx: 4200,
+      }),
+    ).toBe(4200);
+  });
+
+  it("keeps long content authoritative", () => {
+    expect(
+      getTimelineDisplayContentWidth({ trackContentWidth: 9000, viewportWidth: 400, pps: 50 }),
+    ).toBe(9000);
+  });
+});
+
 describe("getTimelineScrollLeftForZoomTransition", () => {
   it("resets horizontal scroll when switching from manual zoom back to fit", () => {
     expect(getTimelineScrollLeftForZoomTransition("manual", "fit", 480)).toBe(0);
@@ -524,7 +605,9 @@ describe("resolveTimelineAssetDrop", () => {
           trackOrder: [0, 3, 7],
         },
         432,
-        310,
+        // clientY updated for TRACKS_TOP_PAD=72: rectTop(200) + RULER_H(24) +
+        // TRACKS_TOP_PAD(72) + TRACK_H(48) + TRACK_H/2(24) = 368 → row 1 → track 3.
+        368,
       ),
     ).toEqual({ start: 3, track: 3 });
   });