@hyperframes/studio 0.4.12 → 0.4.13-alpha.1

package/src/player/components/CompositionThumbnail.tsx

@@ -1,52 +1,129 @@
-/**
- * CompositionThumbnail — Single server-rendered JPEG stretched across the clip.
- *
- * Takes one screenshot at the midpoint of the clip and covers the full width —
- * same approach as After Effects for precomps. This avoids the 1-2s per-frame
- * Puppeteer cost of rendering multiple filmstrip frames.
- */
-
-import { memo } from "react";
+import { memo, useCallback, useState, useRef } from "react";
+import { useMountEffect } from "../../hooks/useMountEffect";
 
 interface CompositionThumbnailProps {
   previewUrl: string;
   label: string;
   labelColor: string;
+  accentColor?: string;
+  selector?: string;
   seekTime?: number;
   duration?: number;
   width?: number;
   height?: number;
 }
 
+const CLIP_HEIGHT = 66;
+const THUMBNAIL_URL_VERSION = "v2";
+
 export const CompositionThumbnail = memo(function CompositionThumbnail({
   previewUrl,
   label,
   labelColor,
+  accentColor = "#6B7280",
+  selector,
   seekTime = 2,
   duration = 5,
 }: CompositionThumbnailProps) {
-  // Single screenshot at the midpoint of the clip
+  const [containerWidth, setContainerWidth] = useState(0);
+  const [loaded, setLoaded] = useState(false);
+  const [aspect, setAspect] = useState(16 / 9);
+  const roRef = useRef<ResizeObserver | null>(null);
+
+  const setContainerRef = useCallback((el: HTMLDivElement | null) => {
+    roRef.current?.disconnect();
+    if (!el) return;
+
+    const measured = el.parentElement?.clientWidth || el.clientWidth;
+    setContainerWidth(measured);
+
+    const target = el.parentElement || el;
+    roRef.current = new ResizeObserver(([entry]) => {
+      setContainerWidth(entry.contentRect.width);
+    });
+    roRef.current.observe(target);
+  }, []);
+
+  useMountEffect(() => () => {
+    roRef.current?.disconnect();
+  });
+
   const thumbnailBase = previewUrl
     .replace("/preview/comp/", "/thumbnail/")
     .replace(/\/preview$/, "/thumbnail/index.html");
   const midTime = seekTime + duration / 2;
-  const url = `${thumbnailBase}?t=${midTime.toFixed(2)}`;
+  const thumbnailUrl = new URL(thumbnailBase, window.location.origin);
+  thumbnailUrl.searchParams.set("t", midTime.toFixed(2));
+  thumbnailUrl.searchParams.set("v", THUMBNAIL_URL_VERSION);
+  if (selector) thumbnailUrl.searchParams.set("selector", selector);
+  const url = thumbnailUrl.toString();
+  const frameW = Math.max(48, Math.round(CLIP_HEIGHT * aspect));
+  const frameCount = containerWidth > 0 ? Math.max(1, Math.ceil(containerWidth / frameW)) : 1;
 
   return (
-    <div className="absolute inset-0 overflow-hidden bg-neutral-950">
+    <div ref={setContainerRef} className="absolute inset-0 overflow-hidden">
       <img
         src={url}
         alt=""
         draggable={false}
         loading="lazy"
         onLoad={(e) => {
-          (e.target as HTMLImageElement).style.opacity = "1";
+          const img = e.currentTarget;
+          if (img.naturalWidth > 0 && img.naturalHeight > 0) {
+            setAspect(img.naturalWidth / img.naturalHeight);
+          }
+          setLoaded(true);
         }}
-        className="absolute inset-0 w-full h-full object-cover"
-        style={{ opacity: 0, transition: "opacity 200ms ease-out" }}
+        className="hidden"
       />
 
-      {/* Label */}
+      {loaded ? (
+        <div className="absolute inset-0 flex">
+          {Array.from({ length: frameCount }).map((_, i) => (
+            <div
+              key={i}
+              className="relative h-full flex-shrink-0 overflow-hidden"
+              style={{ width: frameW }}
+            >
+              <img
+                src={url}
+                alt=""
+                draggable={false}
+                className="absolute inset-0 h-full w-full object-cover opacity-60"
+              />
+            </div>
+          ))}
+        </div>
+      ) : (
+        <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%)",
+          }}
+        />
+      )}
+
+      <div
+        className="absolute inset-0"
+        style={{
+          background: `linear-gradient(120deg, ${accentColor}2e, transparent 34%), linear-gradient(180deg, rgba(255,255,255,0.02), rgba(0,0,0,0.08))`,
+        }}
+      />
+
+      <div className="absolute left-2 top-2 z-10">
+        <span
+          className="block max-w-full truncate rounded-md px-1.5 py-0.5 text-[9px] font-semibold uppercase leading-none"
+          style={{
+            color: labelColor,
+            background: `${accentColor}2e`,
+            boxShadow: `inset 0 0 0 1px ${accentColor}40`,
+          }}
+        >
+          {label}
+        </span>
+      </div>
+
       <div
         className="absolute bottom-0 left-0 right-0 z-10 px-1.5 pb-0.5 pt-3"
         style={{
@@ -55,7 +132,7 @@ export const CompositionThumbnail = memo(function CompositionThumbnail({
         }}
       >
         <span
-          className="text-[9px] font-semibold truncate block leading-tight"
+          className="block truncate text-[9px] font-semibold leading-tight"
           style={{ color: labelColor, textShadow: "0 1px 2px rgba(0,0,0,0.9)" }}
         >
           {label}

package/src/player/components/EditModal.tsx

@@ -2,6 +2,7 @@ import { useState, useCallback, useMemo, useRef } from "react";
 import { useMountEffect } from "../../hooks/useMountEffect";
 import { usePlayerStore } from "../store/playerStore";
 import { formatTime } from "../lib/time";
+import { buildPromptCopyText, buildTimelineAgentPrompt } from "./timelineEditing";
 
 interface EditPopoverProps {
   rangeStart: number;
@@ -14,7 +15,8 @@ interface EditPopoverProps {
 export function EditPopover({ rangeStart, rangeEnd, anchorX, anchorY, onClose }: EditPopoverProps) {
   const elements = usePlayerStore((s) => s.elements);
   const [prompt, setPrompt] = useState("");
-  const [copied, setCopied] = useState(false);
+  const [copiedAgentPrompt, setCopiedAgentPrompt] = useState(false);
+  const [copiedPromptOnly, setCopiedPromptOnly] = useState(false);
   const popoverRef = useRef<HTMLDivElement>(null);
   const textareaRef = useRef<HTMLTextAreaElement>(null);
 
@@ -51,27 +53,12 @@ export function EditPopover({ rangeStart, rangeEnd, anchorX, anchorY, onClose }:
   });
 
   const buildClipboardText = useCallback(() => {
-    const elementLines = elementsInRange
-      .map(
-        (el) =>
-          `- #${el.id} (${el.tag}) — ${formatTime(el.start)} to ${formatTime(el.start + el.duration)}, track ${el.track}`,
-      )
-      .join("\n");
-
-    return `Edit the following HyperFrames composition:
-
-Time range: ${formatTime(start)} — ${formatTime(end)}
-
-Elements in range:
-${elementLines || "(none)"}
-
-User request:
-${prompt.trim() || "(no prompt provided)"}
-
-Instructions:
-Modify only the elements listed above within the specified time range.
-The composition uses HyperFrames data attributes (data-start, data-duration, data-track-index) and GSAP for animations.
-Preserve all other elements and timing outside this range.`;
+    return buildTimelineAgentPrompt({
+      rangeStart: start,
+      rangeEnd: end,
+      elements: elementsInRange,
+      prompt,
+    });
   }, [start, end, elementsInRange, prompt]);
 
   const handleCopy = useCallback(async () => {
@@ -85,13 +72,32 @@ Preserve all other elements and timing outside this range.`;
       document.execCommand("copy");
       document.body.removeChild(ta);
     }
-    setCopied(true);
+    setCopiedAgentPrompt(true);
     setTimeout(() => {
-      setCopied(false);
+      setCopiedAgentPrompt(false);
       onClose();
     }, 800);
   }, [buildClipboardText, onClose]);
 
+  const handleCopyPrompt = useCallback(async () => {
+    const promptText = buildPromptCopyText(prompt);
+    if (!promptText) return;
+    try {
+      await navigator.clipboard.writeText(promptText);
+    } catch {
+      const ta = document.createElement("textarea");
+      ta.value = promptText;
+      document.body.appendChild(ta);
+      ta.select();
+      document.execCommand("copy");
+      document.body.removeChild(ta);
+    }
+    setCopiedPromptOnly(true);
+    setTimeout(() => {
+      setCopiedPromptOnly(false);
+    }, 800);
+  }, [prompt]);
+
   const style: React.CSSProperties = {
     position: "fixed",
     left: Math.max(8, Math.min(anchorX - 160, window.innerWidth - 336)),
@@ -146,17 +152,30 @@ Preserve all other elements and timing outside this range.`;
         </div>
 
         {/* Action */}
-        <div className="px-3 pb-3">
+        <div className="grid grid-cols-2 gap-2 px-3 pb-3">
+          <button
+            onClick={handleCopyPrompt}
+            disabled={!buildPromptCopyText(prompt)}
+            className={`py-1.5 text-[11px] font-medium rounded-lg transition-all border ${
+              copiedPromptOnly
+                ? "bg-green-500/20 text-green-400 border-green-500/30"
+                : "bg-neutral-800/70 text-neutral-200 border-neutral-700/50 hover:bg-neutral-800"
+            } disabled:opacity-50 disabled:cursor-not-allowed`}
+          >
+            {copiedPromptOnly ? "Prompt Copied!" : "Copy Prompt"}
+          </button>
           <button
             onClick={handleCopy}
-            className={`w-full py-1.5 text-[11px] font-medium rounded-lg transition-all ${
-              copied
+            className={`py-1.5 text-[11px] font-medium rounded-lg transition-all ${
+              copiedAgentPrompt
                 ? "bg-green-500/20 text-green-400 border border-green-500/30"
                 : "bg-studio-accent/15 text-studio-accent border border-studio-accent/25 hover:bg-studio-accent/25"
             }`}
           >
-            {copied ? "Copied!" : "Copy to Agent"}
-            {!copied && <span className="text-[9px] text-studio-accent/50 ml-1.5">Cmd+Enter</span>}
+            {copiedAgentPrompt ? "Copied!" : "Copy to Agent"}
+            {!copiedAgentPrompt && (
+              <span className="text-[9px] text-studio-accent/50 ml-1.5">Cmd+Enter</span>
+            )}
           </button>
         </div>
       </div>

package/src/player/components/Player.tsx

@@ -1,6 +1,5 @@
 import { forwardRef, useRef, useState } from "react";
 import { useMountEffect } from "../../hooks/useMountEffect";
-import type { HyperframesPlayer } from "@hyperframes/player";
 // NOTE: importing "@hyperframes/player" registers a class extending HTMLElement
 // at module load, which throws under SSR. Defer the import to the mount effect
 // so it only runs in the browser.
@@ -12,6 +11,10 @@ interface PlayerProps {
   portrait?: boolean;
 }
 
+interface HyperframesPlayerElement extends HTMLElement {
+  iframeElement: HTMLIFrameElement;
+}
+
 /**
  * Readiness check for a Lottie animation instance. Duck-types both supported
  * player shapes:
@@ -96,7 +99,7 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
         if (canceled) return;
 
         // Create the web component imperatively to avoid JSX custom-element typing.
-        const player = document.createElement("hyperframes-player") as HyperframesPlayer;
+        const player = document.createElement("hyperframes-player") as HyperframesPlayerElement;
         const src = directUrl || `/api/projects/${projectId}/preview`;
         player.setAttribute("src", src);
         player.setAttribute("width", String(portrait ? 1080 : 1920));

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

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { resolveSeekPercent } from "./PlayerControls";
+
+describe("resolveSeekPercent", () => {
+  it("returns 0 when the track width is invalid", () => {
+    expect(resolveSeekPercent(100, 0, 0)).toBe(0);
+  });
+
+  it("snaps to the start within the edge threshold", () => {
+    expect(resolveSeekPercent(105, 100, 200)).toBe(0);
+  });
+
+  it("snaps to the end within the edge threshold", () => {
+    expect(resolveSeekPercent(298, 100, 200)).toBe(1);
+  });
+
+  it("preserves the true percent away from the edges", () => {
+    expect(resolveSeekPercent(150, 100, 200)).toBe(0.25);
+  });
+});

package/src/player/components/PlayerControls.tsx

@@ -4,6 +4,17 @@ import { formatTime } from "../lib/time";
 import { usePlayerStore, liveTime } from "../store/playerStore";
 
 const SPEED_OPTIONS = [0.25, 0.5, 1, 1.5, 2] as const;
+const SEEK_EDGE_SNAP_PX = 8;
+
+export function resolveSeekPercent(clientX: number, rectLeft: number, rectWidth: number): number {
+  if (!Number.isFinite(rectWidth) || rectWidth <= 0) return 0;
+  const rawPercent = (clientX - rectLeft) / rectWidth;
+  const clamped = Math.max(0, Math.min(1, rawPercent));
+  const snapThreshold = Math.min(0.5, SEEK_EDGE_SNAP_PX / rectWidth);
+  if (clamped <= snapThreshold) return 0;
+  if (clamped >= 1 - snapThreshold) return 1;
+  return clamped;
+}
 
 interface PlayerControlsProps {
   onTogglePlay: () => void;
@@ -88,7 +99,7 @@ export const PlayerControls = memo(function PlayerControls({
       const bar = seekBarRef.current;
       if (!bar || duration <= 0) return;
       const rect = bar.getBoundingClientRect();
-      const percent = Math.max(0, Math.min(1, (clientX - rect.left) / rect.width));
+      const percent = resolveSeekPercent(clientX, rect.left, rect.width);
       // Immediately update progress bar visuals (don't wait for liveTime round-trip)
       const pct = percent * 100;
       if (progressFillRef.current) progressFillRef.current.style.width = `${pct}%`;

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

@@ -1,5 +1,10 @@
 import { describe, it, expect } from "vitest";
-import { generateTicks } from "./Timeline";
+import {
+  generateTicks,
+  getTimelinePlayheadLeft,
+  getTimelineScrollLeftForZoomTransition,
+  shouldAutoScrollTimeline,
+} from "./Timeline";
 import { formatTime } from "../lib/time";
 
 describe("generateTicks", () => {
@@ -108,3 +113,41 @@ describe("formatTime", () => {
     expect(formatTime(61)).toBe("1:01");
   });
 });
+
+describe("shouldAutoScrollTimeline", () => {
+  it("never auto-scrolls in fit mode", () => {
+    expect(shouldAutoScrollTimeline("fit", 1200, 800)).toBe(false);
+  });
+
+  it("does not auto-scroll when there is no horizontal overflow", () => {
+    expect(shouldAutoScrollTimeline("manual", 800, 800)).toBe(false);
+    expect(shouldAutoScrollTimeline("manual", 800.5, 800)).toBe(false);
+  });
+
+  it("auto-scrolls in manual mode when horizontal overflow exists", () => {
+    expect(shouldAutoScrollTimeline("manual", 1200, 800)).toBe(true);
+  });
+});
+
+describe("getTimelineScrollLeftForZoomTransition", () => {
+  it("resets horizontal scroll when switching from manual zoom back to fit", () => {
+    expect(getTimelineScrollLeftForZoomTransition("manual", "fit", 480)).toBe(0);
+  });
+
+  it("preserves the current scroll offset for other zoom transitions", () => {
+    expect(getTimelineScrollLeftForZoomTransition("fit", "fit", 480)).toBe(480);
+    expect(getTimelineScrollLeftForZoomTransition("fit", "manual", 480)).toBe(480);
+    expect(getTimelineScrollLeftForZoomTransition("manual", "manual", 480)).toBe(480);
+  });
+});
+
+describe("getTimelinePlayheadLeft", () => {
+  it("converts time to a pixel offset from the gutter", () => {
+    expect(getTimelinePlayheadLeft(4, 20)).toBe(112);
+  });
+
+  it("guards invalid input", () => {
+    expect(getTimelinePlayheadLeft(Number.NaN, 20)).toBe(32);
+    expect(getTimelinePlayheadLeft(4, Number.NaN)).toBe(32);
+  });
+});