@hyperframes/studio 0.5.5 → 0.6.0-alpha.1

package/src/components/nle/NLEPreview.tsx

@@ -1,4 +1,4 @@
-import { memo, type Ref } from "react";
+import { memo, useRef, useState, type Ref } from "react";
 import { Player } from "../../player";
 
 interface NLEPreviewProps {
@@ -21,6 +21,17 @@ export function getPreviewPlayerKey({
   return directUrl ?? projectId;
 }
 
+/**
+ * Manages the composition preview with crossfade on reload.
+ *
+ * When refreshKey changes, a new Player is mounted alongside the old one.
+ * The old Player stays visible (opacity 1) until the new one fires onLoad,
+ * at which point the old is removed. This avoids the flash that a simple
+ * key-swap remount would cause.
+ *
+ * Uses the render-time state adjustment pattern (React-sanctioned) to detect
+ * refreshKey changes — no useEffect needed.
+ */
 export const NLEPreview = memo(function NLEPreview({
   projectId,
   iframeRef,
@@ -29,22 +40,56 @@ export const NLEPreview = memo(function NLEPreview({
   directUrl,
   refreshKey,
 }: NLEPreviewProps) {
-  const playerKey = getPreviewPlayerKey({ projectId, directUrl, refreshKey });
+  const baseKey = getPreviewPlayerKey({ projectId, directUrl, refreshKey });
+  const prevRefreshKeyRef = useRef(refreshKey);
+  const [retiringKey, setRetiringKey] = useState<string | null>(null);
+  const retiringTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // Detect refreshKey change during render (React-sanctioned derived state pattern).
+  // When the key changes, the current active player becomes the retiring player
+  // and a new active player is mounted alongside it.
+  if (refreshKey !== prevRefreshKeyRef.current) {
+    const oldKey = `${baseKey}:${prevRefreshKeyRef.current ?? 0}`;
+    prevRefreshKeyRef.current = refreshKey;
+    setRetiringKey(oldKey);
+  }
+
+  const activeKey = `${baseKey}:${refreshKey ?? 0}`;
+
+  const handleNewPlayerLoad = () => {
+    onIframeLoad();
+    if (retiringTimerRef.current) clearTimeout(retiringTimerRef.current);
+    retiringTimerRef.current = setTimeout(() => {
+      setRetiringKey(null);
+      retiringTimerRef.current = null;
+    }, 160);
+  };
 
   return (
     <div className="flex flex-col h-full min-h-0">
       <div
-        className="flex-1 flex items-center justify-center p-2 overflow-hidden min-h-0 outline-none focus:ring-1 focus:ring-studio-accent/40"
+        className="relative flex-1 flex items-center justify-center p-2 overflow-hidden min-h-0 outline-none focus:ring-1 focus:ring-studio-accent/40"
         tabIndex={0}
         aria-label="Composition preview"
       >
+        {retiringKey && (
+          <Player
+            key={retiringKey}
+            projectId={directUrl ? undefined : projectId}
+            directUrl={directUrl}
+            onLoad={() => {}}
+            portrait={portrait}
+            style={{ position: "absolute", inset: 0, zIndex: 0, opacity: 1 }}
+          />
+        )}
         <Player
-          key={playerKey}
+          key={activeKey}
           ref={iframeRef}
           projectId={directUrl ? undefined : projectId}
           directUrl={directUrl}
-          onLoad={onIframeLoad}
+          onLoad={retiringKey ? handleNewPlayerLoad : onIframeLoad}
           portrait={portrait}
+          style={retiringKey ? { position: "absolute", inset: 0, zIndex: 1 } : undefined}
         />
       </div>
     </div>

package/src/components/renders/RenderQueue.tsx

@@ -1,50 +1,21 @@
 import { memo, useState, useRef, useEffect } from "react";
 import { RenderQueueItem } from "./RenderQueueItem";
-import type { RenderJob, ResolutionPreset } from "./useRenderQueue";
+import type { RenderJob } from "./useRenderQueue";
+
+type StartRenderHandler = (
+  format: "mp4" | "webm" | "mov",
+  quality: "draft" | "standard" | "high",
+) => void | Promise<void>;
 
 interface RenderQueueProps {
   jobs: RenderJob[];
   projectId: string;
   onDelete: (jobId: string) => void;
   onClearCompleted: () => void;
-  onStartRender: (
-    format: "mp4" | "webm" | "mov",
-    quality: "draft" | "standard" | "high",
-    resolution: ResolutionPreset | "auto",
-  ) => void;
+  onStartRender: StartRenderHandler;
   isRendering: boolean;
 }
 
-// Indexing the table by `ResolutionPreset | "auto"` makes adding a new preset
-// to `core.types` (e.g. an 8K row) a TypeScript error here instead of a
-// silently missing dropdown entry. Order is fixed by the array below.
-const RESOLUTION_LABELS: Record<ResolutionPreset | "auto", { label: string; title: string }> = {
-  auto: { label: "Auto", title: "Render at the composition's authored resolution" },
-  landscape: { label: "1080p ↔", title: "1920×1080 landscape" },
-  portrait: { label: "1080p ↕", title: "1080×1920 portrait" },
-  "landscape-4k": {
-    label: "4K ↔",
-    title: "3840×2160 — supersamples a 1080p composition via Chrome DPR. Slower, larger files.",
-  },
-  "portrait-4k": {
-    label: "4K ↕",
-    title: "2160×3840 — supersamples a 1080p portrait composition via Chrome DPR.",
-  },
-};
-
-const RESOLUTION_OPTION_ORDER: (ResolutionPreset | "auto")[] = [
-  "auto",
-  "landscape",
-  "portrait",
-  "landscape-4k",
-  "portrait-4k",
-];
-
-const RESOLUTION_OPTIONS = RESOLUTION_OPTION_ORDER.map((value) => ({
-  value,
-  ...RESOLUTION_LABELS[value],
-}));
-
 const FORMAT_INFO: Record<"mp4" | "webm" | "mov", { label: string; desc: string }> = {
   mp4: { label: "MP4", desc: "Best for general use. Smallest file, universal playback." },
   mov: {
@@ -125,16 +96,11 @@ function FormatExportButton({
   onStartRender,
   isRendering,
 }: {
-  onStartRender: (
-    format: "mp4" | "webm" | "mov",
-    quality: "draft" | "standard" | "high",
-    resolution: ResolutionPreset | "auto",
-  ) => void;
+  onStartRender: StartRenderHandler;
   isRendering: boolean;
 }) {
   const [format, setFormat] = useState<"mp4" | "webm" | "mov">("mp4");
   const [quality, setQuality] = useState<"draft" | "standard" | "high">("standard");
-  const [resolution, setResolution] = useState<ResolutionPreset | "auto">("auto");
 
   // MOV (ProRes) is a fixed-quality codec — quality selector has no effect.
   const showQuality = format !== "mov";
@@ -142,30 +108,13 @@ function FormatExportButton({
   return (
     <div className="flex items-center gap-1">
       <FormatInfoTooltip format={format} />
-      {/* Resolution must remain the leftmost <select> in this row — it
-          carries `rounded-l` for the joined-button look. If you ever hide it
-          (feature-flag, etc.), move `rounded-l` to whichever element ends up
-          leftmost. */}
-      <select
-        value={resolution}
-        onChange={(e) => setResolution(e.target.value as ResolutionPreset | "auto")}
-        disabled={isRendering}
-        title={RESOLUTION_OPTIONS.find((r) => r.value === resolution)?.title}
-        className="h-5 px-1 text-[10px] rounded-l bg-neutral-800 border border-neutral-700 text-neutral-300 outline-none disabled:opacity-50"
-      >
-        {RESOLUTION_OPTIONS.map((r) => (
-          <option key={r.value} value={r.value} title={r.title}>
-            {r.label}
-          </option>
-        ))}
-      </select>
       {showQuality && (
         <select
           value={quality}
           onChange={(e) => setQuality(e.target.value as "draft" | "standard" | "high")}
           disabled={isRendering}
           title={QUALITY_OPTIONS.find((q) => q.value === quality)?.title}
-          className="h-5 px-1 text-[10px] bg-neutral-800 border border-neutral-700 text-neutral-300 outline-none disabled:opacity-50"
+          className="h-5 px-1 text-[10px] rounded-l bg-neutral-800 border border-neutral-700 text-neutral-300 outline-none disabled:opacity-50"
         >
           {QUALITY_OPTIONS.map((q) => (
             <option key={q.value} value={q.value} title={q.title}>
@@ -178,14 +127,16 @@ function FormatExportButton({
         value={format}
         onChange={(e) => setFormat(e.target.value as "mp4" | "webm" | "mov")}
         disabled={isRendering}
-        className="h-5 px-1 text-[10px] bg-neutral-800 border border-neutral-700 text-neutral-300 outline-none disabled:opacity-50"
+        className={`h-5 px-1 text-[10px] bg-neutral-800 border border-neutral-700 text-neutral-300 outline-none disabled:opacity-50 ${showQuality ? "" : "rounded-l"}`}
       >
         <option value="mp4">MP4</option>
         <option value="mov">MOV</option>
         <option value="webm">WebM</option>
       </select>
       <button
-        onClick={() => onStartRender(format, quality, resolution)}
+        onClick={() => {
+          void onStartRender(format, quality);
+        }}
         disabled={isRendering}
         className="flex items-center gap-1 px-2 py-0.5 text-[10px] font-semibold rounded-r bg-studio-accent text-[#09090B] hover:brightness-110 transition-colors disabled:opacity-50"
       >

package/src/components/renders/useRenderQueue.ts

@@ -11,20 +11,6 @@ export interface RenderJob {
   durationMs?: number;
 }
 
-// Mirrors `CanvasResolution` from @hyperframes/core. Kept local because
-// studio's tsconfig doesn't include node types, and the core barrel
-// transitively pulls in modules with `node:fs` imports. Drift risk is
-// low (4 string literals tied to a stable enum).
-export type ResolutionPreset = "landscape" | "portrait" | "landscape-4k" | "portrait-4k";
-
-export interface StartRenderOptions {
-  fps?: number;
-  quality?: "draft" | "standard" | "high";
-  format?: "mp4" | "webm" | "mov";
-  /** `"auto"` (default) renders at the composition's authored dimensions. */
-  resolution?: ResolutionPreset | "auto";
-}
-
 export function useRenderQueue(projectId: string | null) {
   const [jobs, setJobs] = useState<RenderJob[]>([]);
   const eventSourceRef = useRef<EventSource | null>(null);
@@ -73,30 +59,20 @@ export function useRenderQueue(projectId: string | null) {
 
   // Start a render and track progress via SSE
   const startRender = useCallback(
-    async (opts: StartRenderOptions = {}) => {
+    async (
+      fps = 30,
+      quality: "draft" | "standard" | "high" = "standard",
+      format: "mp4" | "webm" | "mov" = "mp4",
+    ) => {
       if (!projectId) return;
 
-      const fps = opts.fps ?? 30;
-      const quality = opts.quality ?? "standard";
-      const format = opts.format ?? "mp4";
-      const resolution = opts.resolution;
-
       const startTime = Date.now();
-      // "auto" / undefined means "render at the composition's authored size".
-      // Omit the field entirely — sending "auto" would trip the route's
-      // enum validation set.
-      const body: { fps: number; quality: string; format: string; resolution?: string } = {
-        fps,
-        quality,
-        format,
-      };
-      if (resolution && resolution !== "auto") body.resolution = resolution;
       let res: Response;
       try {
         res = await fetch(`/api/projects/${projectId}/render`, {
           method: "POST",
           headers: { "Content-Type": "application/json" },
-          body: JSON.stringify(body),
+          body: JSON.stringify({ fps, quality, format }),
         });
       } catch {
         const failedJob: RenderJob = {

package/src/components/sidebar/AssetsTab.tsx

@@ -2,6 +2,7 @@ import { memo, useState, useCallback, useRef } from "react";
 import { VideoFrameThumbnail } from "../ui/VideoFrameThumbnail";
 import { MEDIA_EXT, IMAGE_EXT, VIDEO_EXT, AUDIO_EXT } from "../../utils/mediaTypes";
 import { TIMELINE_ASSET_MIME } from "../../utils/timelineAssetDrop";
+import { copyTextToClipboard } from "../../utils/clipboard";
 
 interface AssetsTabProps {
   projectId: string;
@@ -298,12 +299,10 @@ export const AssetsTab = memo(function AssetsTab({
   );
 
   const handleCopyPath = useCallback(async (path: string) => {
-    try {
-      await navigator.clipboard.writeText(path);
+    const copied = await copyTextToClipboard(path);
+    if (copied) {
       setCopiedPath(path);
       setTimeout(() => setCopiedPath(null), 1500);
-    } catch {
-      // ignore
     }
   }, []);
 

package/src/components/sidebar/CompositionsTab.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { resolveCompositionPreviewScale } from "./CompositionsTab";
+import { resolveCompositionPreviewScale, resolveThumbnailSeekTime } from "./CompositionsTab";
 
 describe("resolveCompositionPreviewScale", () => {
   it("scales a 16:9 stage to fit the composition card", () => {
@@ -35,3 +35,18 @@ describe("resolveCompositionPreviewScale", () => {
     ).toBeCloseTo(80 / 1920);
   });
 });
+
+describe("resolveThumbnailSeekTime", () => {
+  it("uses the default 3s frame for compositions longer than 3s", () => {
+    expect(resolveThumbnailSeekTime(6)).toBe(3);
+  });
+
+  it("uses the midpoint for compositions shorter than 3s", () => {
+    expect(resolveThumbnailSeekTime(2)).toBe(1);
+  });
+
+  it("falls back to the default 3s frame when duration is unknown", () => {
+    expect(resolveThumbnailSeekTime(null)).toBe(3);
+    expect(resolveThumbnailSeekTime(Number.NaN)).toBe(3);
+  });
+});

package/src/components/sidebar/CompositionsTab.tsx

@@ -1,4 +1,4 @@
-import { memo, useRef, useState } from "react";
+import { memo, useCallback, useEffect, useRef, useState } from "react";
 
 interface CompositionsTabProps {
   projectId: string;
@@ -8,6 +8,17 @@ interface CompositionsTabProps {
 }
 
 const DEFAULT_PREVIEW_STAGE = { width: 1920, height: 1080 };
+const THUMBNAIL_SEEK_TIME_SECONDS = 3;
+const THUMBNAIL_PLAYBACK_SYNC_ATTEMPTS = 10;
+
+type PreviewWindow = Window & {
+  __player?: {
+    play?: () => void;
+    pause?: () => void;
+    seek?: (time: number) => void;
+    getDuration?: () => number;
+  };
+};
 
 export function resolveCompositionPreviewScale(input: {
   cardWidth: number;
@@ -28,6 +39,54 @@ export function resolveCompositionPreviewScale(input: {
   return Math.min(scaleX, scaleY);
 }
 
+export function resolveThumbnailSeekTime(durationSeconds: number | null | undefined): number {
+  if (
+    Number.isFinite(durationSeconds) &&
+    durationSeconds != null &&
+    durationSeconds > 0 &&
+    durationSeconds < THUMBNAIL_SEEK_TIME_SECONDS
+  ) {
+    return durationSeconds / 2;
+  }
+
+  return THUMBNAIL_SEEK_TIME_SECONDS;
+}
+
+function parsePositiveNumber(value: string | null): number | null {
+  if (value == null) return null;
+  const parsed = Number.parseFloat(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+}
+
+function resolveIframeDuration(iframe: HTMLIFrameElement | null): number | null {
+  const win = iframe?.contentWindow as PreviewWindow | null;
+  const playerDuration = win?.__player?.getDuration?.();
+  if (Number.isFinite(playerDuration) && playerDuration != null && playerDuration > 0) {
+    return playerDuration;
+  }
+
+  const doc = iframe?.contentDocument;
+  const root = doc?.querySelector("[data-composition-id]") ?? doc?.documentElement ?? null;
+  return (
+    parsePositiveNumber(root?.getAttribute("data-composition-duration") ?? null) ??
+    parsePositiveNumber(root?.getAttribute("data-duration") ?? null)
+  );
+}
+
+function syncIframePlayback(iframe: HTMLIFrameElement | null, shouldPlay: boolean): boolean {
+  const player = (iframe?.contentWindow as PreviewWindow | null)?.__player;
+  if (!player) return false;
+
+  if (shouldPlay) {
+    player.play?.();
+    return true;
+  }
+
+  player.pause?.();
+  player.seek?.(resolveThumbnailSeekTime(resolveIframeDuration(iframe)));
+  return true;
+}
+
 function CompCard({
   projectId,
   comp,
@@ -41,7 +100,25 @@ function CompCard({
 }) {
   const [hovered, setHovered] = useState(false);
   const [stageSize, setStageSize] = useState(DEFAULT_PREVIEW_STAGE);
+  const iframeRef = useRef<HTMLIFrameElement | null>(null);
   const hoverTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const syncTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const requestIframePlaybackSync = useCallback((shouldPlay: boolean) => {
+    if (syncTimer.current) {
+      clearTimeout(syncTimer.current);
+      syncTimer.current = null;
+    }
+
+    const sync = (remainingAttempts: number) => {
+      if (syncIframePlayback(iframeRef.current, shouldPlay) || remainingAttempts <= 0) return;
+
+      syncTimer.current = setTimeout(() => sync(remainingAttempts - 1), 100);
+    };
+
+    sync(THUMBNAIL_PLAYBACK_SYNC_ATTEMPTS);
+  }, []);
+
   const handleEnter = () => {
     hoverTimer.current = setTimeout(() => setHovered(true), 300);
   };
@@ -53,7 +130,6 @@ function CompCard({
     setHovered(false);
   };
   const name = comp.replace(/^compositions\//, "").replace(/\.html$/, "");
-  const thumbnailUrl = `/api/projects/${projectId}/thumbnail/${comp}?t=2`;
   const previewUrl = `/api/projects/${projectId}/preview/comp/${comp}`;
   const previewScale = resolveCompositionPreviewScale({
     cardWidth: 80,
@@ -62,6 +138,17 @@ function CompCard({
     stageHeight: stageSize.height,
   });
 
+  useEffect(() => {
+    requestIframePlaybackSync(hovered);
+  }, [hovered, requestIframePlaybackSync]);
+
+  useEffect(() => {
+    return () => {
+      if (hoverTimer.current) clearTimeout(hoverTimer.current);
+      if (syncTimer.current) clearTimeout(syncTimer.current);
+    };
+  }, []);
+
   return (
     <div
       onClick={onSelect}
@@ -74,49 +161,34 @@ function CompCard({
       }`}
     >
       <div className="w-20 h-[45px] rounded overflow-hidden bg-neutral-900 flex-shrink-0 relative">
-        {/* Live iframe preview on hover */}
-        {hovered && (
-          <iframe
-            src={previewUrl}
-            sandbox="allow-scripts allow-same-origin"
-            className="absolute left-0 top-0 border-none pointer-events-none"
-            style={{
-              transformOrigin: "0 0",
-              width: stageSize.width,
-              height: stageSize.height,
-              transform: `scale(${previewScale})`,
-            }}
-            onLoad={(e) => {
-              try {
-                const iframe = e.currentTarget;
-                const root = iframe.contentDocument?.querySelector("[data-composition-id]");
-                const width =
-                  Number(root?.getAttribute("data-width")) || DEFAULT_PREVIEW_STAGE.width;
-                const height =
-                  Number(root?.getAttribute("data-height")) || DEFAULT_PREVIEW_STAGE.height;
-                setStageSize({ width, height });
-              } catch {
-                setStageSize(DEFAULT_PREVIEW_STAGE);
-              }
-            }}
-            tabIndex={-1}
-          />
-        )}
-        {/* Static thumbnail — hidden while hovering */}
-        <div
-          className="absolute inset-0 transition-opacity duration-150"
-          style={{ opacity: hovered ? 0 : 1 }}
-        >
-          <img
-            src={thumbnailUrl}
-            alt={name}
-            loading="lazy"
-            className="w-full h-full object-contain"
-            onError={(e) => {
-              (e.target as HTMLImageElement).style.display = "none";
-            }}
-          />
-        </div>
+        <iframe
+          ref={iframeRef}
+          src={previewUrl}
+          sandbox="allow-scripts allow-same-origin"
+          loading="lazy"
+          className="absolute left-0 top-0 border-none pointer-events-none"
+          style={{
+            transformOrigin: "0 0",
+            width: stageSize.width,
+            height: stageSize.height,
+            transform: `scale(${previewScale})`,
+          }}
+          onLoad={(e) => {
+            try {
+              const iframe = e.currentTarget;
+              const root = iframe.contentDocument?.querySelector("[data-composition-id]");
+              const width = Number(root?.getAttribute("data-width")) || DEFAULT_PREVIEW_STAGE.width;
+              const height =
+                Number(root?.getAttribute("data-height")) || DEFAULT_PREVIEW_STAGE.height;
+              setStageSize({ width, height });
+              requestIframePlaybackSync(hovered);
+            } catch {
+              setStageSize(DEFAULT_PREVIEW_STAGE);
+            }
+          }}
+          title={`${name} preview`}
+          tabIndex={-1}
+        />
       </div>
       <div className="min-w-0 flex-1">
         <span className="text-[11px] font-medium text-neutral-300 truncate block">{name}</span>