@hyperframes/studio 0.6.0-alpha.2 → 0.6.0-alpha.5

package/src/components/nle/NLELayout.tsx

@@ -55,20 +55,24 @@ interface NLELayoutProps {
   onInspectTimelineElement?: (element: TimelineElement) => void;
   inspectedTimelineElementId?: string | null;
   timelineLayerChildCounts?: ReadonlyMap<string, number>;
-  thumbnailedTimelineElementIds?: ReadonlySet<string>;
-  onToggleTimelineElementThumbnail?: (element: TimelineElement) => void;
   /** Exposes the compIdToSrc map for parent components (e.g., useRenderClipContent) */
   onCompIdToSrcChange?: (map: Map<string, string>) => void;
   /** Whether the timeline panel is visible (default: true) */
   timelineVisible?: boolean;
   /** Callback to toggle timeline visibility */
   onToggleTimeline?: () => void;
+  /** Notifies parent when composition loading state changes */
+  onCompositionLoadingChange?: (loading: boolean) => void;
 }
 
 const MIN_TIMELINE_H = 100;
 const DEFAULT_TIMELINE_H = 220;
 const MIN_PREVIEW_H = 120;
 
+export function shouldDisableTimelineWhileCompositionLoading(compositionLoading: boolean): boolean {
+  return compositionLoading;
+}
+
 export const NLELayout = memo(function NLELayout({
   projectId,
   portrait,
@@ -90,11 +94,10 @@ export const NLELayout = memo(function NLELayout({
   onInspectTimelineElement,
   inspectedTimelineElementId,
   timelineLayerChildCounts,
-  thumbnailedTimelineElementIds,
-  onToggleTimelineElementThumbnail,
   onCompIdToSrcChange,
   timelineVisible,
   onToggleTimeline,
+  onCompositionLoadingChange: onCompositionLoadingChangeParent,
 }: NLELayoutProps) {
   const {
     iframeRef,
@@ -214,6 +217,12 @@ export const NLELayout = memo(function NLELayout({
 
   // Resizable timeline height
   const [timelineH, setTimelineH] = useState(DEFAULT_TIMELINE_H);
+  const [compositionLoading, setCompositionLoading] = useState(true);
+  const timelineDisabled = shouldDisableTimelineWhileCompositionLoading(compositionLoading);
+
+  useEffect(() => {
+    onCompositionLoadingChangeParent?.(compositionLoading);
+  }, [compositionLoading, onCompositionLoadingChangeParent]);
   const isTimelineVisible = timelineVisible ?? true;
   const isDragging = useRef(false);
   const containerRef = useRef<HTMLDivElement>(null);
@@ -327,23 +336,31 @@ export const NLELayout = memo(function NLELayout({
   }, [activeCompositionPath, projectId, updateCompositionStack]);
 
   // Resize divider handlers
-  const handleDividerPointerDown = useCallback((e: React.PointerEvent) => {
-    e.preventDefault();
-    isDragging.current = true;
-    (e.target as HTMLElement).setPointerCapture(e.pointerId);
-  }, []);
+  const handleDividerPointerDown = useCallback(
+    (e: React.PointerEvent) => {
+      if (timelineDisabled) return;
+      e.preventDefault();
+      isDragging.current = true;
+      (e.target as HTMLElement).setPointerCapture(e.pointerId);
+    },
+    [timelineDisabled],
+  );
 
-  const handleDividerPointerMove = useCallback((e: React.PointerEvent) => {
-    if (!isDragging.current || !containerRef.current) return;
-    const rect = containerRef.current.getBoundingClientRect();
-    const mouseY = e.clientY - rect.top;
-    const containerH = rect.height;
-    const newTimelineH = Math.max(
-      MIN_TIMELINE_H,
-      Math.min(containerH - MIN_PREVIEW_H, containerH - mouseY),
-    );
-    setTimelineH(newTimelineH);
-  }, []);
+  const handleDividerPointerMove = useCallback(
+    (e: React.PointerEvent) => {
+      if (timelineDisabled) return;
+      if (!isDragging.current || !containerRef.current) return;
+      const rect = containerRef.current.getBoundingClientRect();
+      const mouseY = e.clientY - rect.top;
+      const containerH = rect.height;
+      const newTimelineH = Math.max(
+        MIN_TIMELINE_H,
+        Math.min(containerH - MIN_PREVIEW_H, containerH - mouseY),
+      );
+      setTimelineH(newTimelineH);
+    },
+    [timelineDisabled],
+  );
 
   const handleDividerPointerUp = useCallback(() => {
     isDragging.current = false;
@@ -374,6 +391,7 @@ export const NLELayout = memo(function NLELayout({
             projectId={projectId}
             iframeRef={iframeRef}
             onIframeLoad={onIframeLoad}
+            onCompositionLoadingChange={setCompositionLoading}
             portrait={portrait}
             directUrl={directUrl}
             refreshKey={refreshKey}
@@ -388,7 +406,7 @@ export const NLELayout = memo(function NLELayout({
               onNavigate={handleNavigateComposition}
             />
           )}
-          <PlayerControls onTogglePlay={togglePlay} onSeek={seek} />
+          <PlayerControls onTogglePlay={togglePlay} onSeek={seek} disabled={timelineDisabled} />
         </div>
       </div>
 
@@ -406,13 +424,18 @@ export const NLELayout = memo(function NLELayout({
           </div>
 
           {/* Timeline section — fixed height, resizable */}
-          <div className="flex flex-col flex-shrink-0" style={{ height: timelineH }}>
+          <div
+            className="relative flex flex-col flex-shrink-0"
+            style={{ height: timelineH }}
+            aria-disabled={timelineDisabled || undefined}
+          >
             {/* Timeline tracks */}
             <div
               // flex-col: toolbar takes natural height, Timeline fills remainder.
               className="flex flex-col flex-1 min-h-0 overflow-hidden bg-neutral-950"
               onDoubleClick={(e) => {
                 if ((e.target as HTMLElement).closest("[data-clip]")) return;
+                if (timelineDisabled) return;
                 if (compositionStack.length > 1) {
                   updateCompositionStack((prev) => prev.slice(0, -1));
                 }
@@ -433,11 +456,20 @@ export const NLELayout = memo(function NLELayout({
                 onInspectElement={onInspectTimelineElement}
                 inspectedElementId={inspectedTimelineElementId}
                 layerChildCounts={timelineLayerChildCounts}
-                thumbnailedElementIds={thumbnailedTimelineElementIds}
-                onToggleElementThumbnail={onToggleTimelineElementThumbnail}
+                disabled={timelineDisabled}
               />
             </div>
             {timelineFooter && <div className="flex-shrink-0">{timelineFooter}</div>}
+            {timelineDisabled && (
+              <div
+                className="absolute inset-0 z-30 cursor-not-allowed bg-black/18"
+                data-testid="timeline-loading-disabled-overlay"
+                aria-hidden="true"
+                onPointerDown={(event) => event.preventDefault()}
+                onDragOver={(event) => event.preventDefault()}
+                onDrop={(event) => event.preventDefault()}
+              />
+            )}
           </div>
         </>
       ) : onToggleTimeline ? (

package/src/components/nle/NLEPreview.tsx

@@ -5,6 +5,7 @@ interface NLEPreviewProps {
   projectId: string;
   iframeRef: Ref<HTMLIFrameElement>;
   onIframeLoad: () => void;
+  onCompositionLoadingChange?: (loading: boolean) => void;
   portrait?: boolean;
   directUrl?: string;
   refreshKey?: number;
@@ -36,6 +37,7 @@ export const NLEPreview = memo(function NLEPreview({
   projectId,
   iframeRef,
   onIframeLoad,
+  onCompositionLoadingChange,
   portrait,
   directUrl,
   refreshKey,
@@ -88,6 +90,7 @@ export const NLEPreview = memo(function NLEPreview({
           projectId={directUrl ? undefined : projectId}
           directUrl={directUrl}
           onLoad={retiringKey ? handleNewPlayerLoad : onIframeLoad}
+          onCompositionLoadingChange={onCompositionLoadingChange}
           portrait={portrait}
           style={retiringKey ? { position: "absolute", inset: 0, zIndex: 1 } : undefined}
         />

package/src/components/renders/RenderQueue.tsx

@@ -1,10 +1,12 @@
 import { memo, useState, useRef, useEffect } from "react";
 import { RenderQueueItem } from "./RenderQueueItem";
-import type { RenderJob } from "./useRenderQueue";
+import type { RenderJob, ResolutionPreset } from "./useRenderQueue";
 
 type StartRenderHandler = (
   format: "mp4" | "webm" | "mov",
   quality: "draft" | "standard" | "high",
+  resolution: ResolutionPreset | "auto",
+  fps: 24 | 30 | 60,
 ) => void | Promise<void>;
 
 interface RenderQueueProps {
@@ -16,6 +18,36 @@ interface RenderQueueProps {
   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: {
@@ -101,6 +133,8 @@ function FormatExportButton({
 }) {
   const [format, setFormat] = useState<"mp4" | "webm" | "mov">("mp4");
   const [quality, setQuality] = useState<"draft" | "standard" | "high">("standard");
+  const [resolution, setResolution] = useState<ResolutionPreset | "auto">("auto");
+  const [fps, setFps] = useState<24 | 30 | 60>(30);
 
   // MOV (ProRes) is a fixed-quality codec — quality selector has no effect.
   const showQuality = format !== "mov";
@@ -108,13 +142,30 @@ 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] rounded-l 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"
         >
           {QUALITY_OPTIONS.map((q) => (
             <option key={q.value} value={q.value} title={q.title}>
@@ -123,11 +174,22 @@ function FormatExportButton({
           ))}
         </select>
       )}
+      <select
+        value={fps}
+        onChange={(e) => setFps(Number(e.target.value) as 24 | 30 | 60)}
+        disabled={isRendering}
+        title="Frames per second"
+        className="h-5 px-1 text-[10px] bg-neutral-800 border border-neutral-700 text-neutral-300 outline-none disabled:opacity-50"
+      >
+        <option value={24}>24fps</option>
+        <option value={30}>30fps</option>
+        <option value={60}>60fps</option>
+      </select>
       <select
         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 ${showQuality ? "" : "rounded-l"}`}
+        className="h-5 px-1 text-[10px] bg-neutral-800 border border-neutral-700 text-neutral-300 outline-none disabled:opacity-50"
       >
         <option value="mp4">MP4</option>
         <option value="mov">MOV</option>
@@ -135,7 +197,7 @@ function FormatExportButton({
       </select>
       <button
         onClick={() => {
-          void onStartRender(format, quality);
+          void onStartRender(format, quality, resolution, fps);
         }}
         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,6 +11,20 @@ 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);
@@ -59,20 +73,30 @@ export function useRenderQueue(projectId: string | null) {
 
   // Start a render and track progress via SSE
   const startRender = useCallback(
-    async (
-      fps = 30,
-      quality: "draft" | "standard" | "high" = "standard",
-      format: "mp4" | "webm" | "mov" = "mp4",
-    ) => {
+    async (opts: StartRenderOptions = {}) => {
       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({ fps, quality, format }),
+          body: JSON.stringify(body),
         });
       } catch {
         const failedJob: RenderJob = {

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

@@ -0,0 +1,58 @@
+// @vitest-environment happy-dom
+
+import { describe, expect, it } from "vitest";
+import { hasUnloadedAssets, shouldShowCompositionLoadingOverlay } from "./Player";
+
+describe("composition loading overlay", () => {
+  it("shows while the composition is loading", () => {
+    expect(shouldShowCompositionLoadingOverlay(true)).toBe(true);
+  });
+
+  it("hides after the composition is ready", () => {
+    expect(shouldShowCompositionLoadingOverlay(false)).toBe(false);
+  });
+
+  it("keeps the asset overlay up while media is still buffering", () => {
+    const iframe = document.createElement("iframe");
+    document.body.appendChild(iframe);
+    const audio = iframe.contentDocument?.createElement("audio");
+    expect(audio).toBeDefined();
+    Object.defineProperty(audio, "readyState", {
+      value: 0,
+      configurable: true,
+    });
+    Object.defineProperty(audio, "networkState", {
+      value: 2,
+      configurable: true,
+    });
+    iframe.contentDocument?.body.appendChild(audio!);
+
+    expect(hasUnloadedAssets(iframe, false)).toBe(true);
+
+    iframe.remove();
+  });
+
+  it("does not keep the asset overlay stuck on failed media sources", () => {
+    const iframe = document.createElement("iframe");
+    document.body.appendChild(iframe);
+    const audio = iframe.contentDocument?.createElement("audio");
+    expect(audio).toBeDefined();
+    Object.defineProperty(audio, "error", {
+      value: { code: 4, message: "format error" },
+      configurable: true,
+    });
+    Object.defineProperty(audio, "readyState", {
+      value: 0,
+      configurable: true,
+    });
+    Object.defineProperty(audio, "networkState", {
+      value: 3,
+      configurable: true,
+    });
+    iframe.contentDocument?.body.appendChild(audio!);
+
+    expect(hasUnloadedAssets(iframe, false)).toBe(false);
+
+    iframe.remove();
+  });
+});

package/src/player/components/Player.tsx

@@ -10,6 +10,7 @@ interface PlayerProps {
   projectId?: string;
   directUrl?: string;
   onLoad: () => void;
+  onCompositionLoadingChange?: (loading: boolean) => void;
   portrait?: boolean;
   style?: React.CSSProperties;
 }
@@ -18,6 +19,9 @@ interface HyperframesPlayerElement extends HTMLElement {
   iframeElement: HTMLIFrameElement;
 }
 
+const MEDIA_HAVE_FUTURE_DATA = 3;
+const MEDIA_NETWORK_NO_SOURCE = 3;
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null;
 }
@@ -31,6 +35,10 @@ function getShaderTransitionLoading(event: Event): boolean | null {
   return state.loading === true && state.ready !== true;
 }
 
+export function shouldShowCompositionLoadingOverlay(compositionLoading: boolean): boolean {
+  return compositionLoading;
+}
+
 function enableInteractiveIframe(player: HyperframesPlayerElement): void {
   const root = player.shadowRoot;
   if (!root) return;
@@ -42,6 +50,11 @@ function enableInteractiveIframe(player: HyperframesPlayerElement): void {
   iframe?.style.setProperty("pointer-events", "auto");
 }
 
+function isPreviewMediaElement(el: Element): el is HTMLMediaElement {
+  const tagName = el.tagName.toLowerCase();
+  return tagName === "video" || tagName === "audio";
+}
+
 // Assets are considered ready when every `<video>`/`<audio>` has enough data
 // to play through without buffering, and every registered Lottie animation has
 // finished loading.
@@ -50,14 +63,19 @@ function enableInteractiveIframe(player: HyperframesPlayerElement): void {
 // races so a brief access failure (e.g. an iframe that just swapped src)
 // doesn't flicker the overlay state — we keep showing whatever was most
 // recently true.
-function hasUnloadedAssets(iframe: HTMLIFrameElement, lastResult: boolean): boolean {
+export function hasUnloadedAssets(iframe: HTMLIFrameElement, lastResult: boolean): boolean {
   try {
     const win = iframe.contentWindow as unknown as (Window & { __hfLottie?: unknown[] }) | null;
     const doc = iframe.contentDocument;
     if (!win || !doc) return lastResult;
 
     for (const el of doc.querySelectorAll("video, audio")) {
-      if (el instanceof HTMLMediaElement && el.readyState < HTMLMediaElement.HAVE_FUTURE_DATA) {
+      if (
+        isPreviewMediaElement(el) &&
+        !el.error &&
+        el.networkState !== MEDIA_NETWORK_NO_SOURCE &&
+        el.readyState < MEDIA_HAVE_FUTURE_DATA
+      ) {
         return true;
       }
     }
@@ -84,7 +102,7 @@ function hasUnloadedAssets(iframe: HTMLIFrameElement, lastResult: boolean): bool
  * timeline probing, and DOM inspection.
  */
 export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
-  ({ projectId, directUrl, onLoad, portrait, style }, ref) => {
+  ({ projectId, directUrl, onLoad, onCompositionLoadingChange, portrait, style }, ref) => {
     const containerRef = useRef<HTMLDivElement>(null);
     const loadCountRef = useRef(0);
     const assetPollRef = useRef<ReturnType<typeof setInterval> | null>(null);
@@ -93,6 +111,7 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
     const [assetOverlayVisible, setAssetOverlayVisible] = useState(false);
     const [assetOverlayFading, setAssetOverlayFading] = useState(false);
     const [shaderTransitionLoading, setShaderTransitionLoading] = useState(false);
+    const [compositionLoading, setCompositionLoading] = useState(true);
 
     useMountEffect(() => {
       const container = containerRef.current;
@@ -138,10 +157,20 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
         };
         player.addEventListener("shadertransitionstate", handleShaderTransitionState);
 
+        const handleReady = () => {
+          setCompositionLoading(false);
+        };
+        const handleError = () => {
+          setCompositionLoading(false);
+        };
+        player.addEventListener("ready", handleReady);
+        player.addEventListener("error", handleError);
+
         // Forward the iframe's native load event to the studio's onIframeLoad.
         const handleLoad = () => {
           loadCountRef.current++;
           setShaderTransitionLoading(false);
+          setCompositionLoading(true);
           // Reveal animation on reload (hot-reload, composition switch)
           if (loadCountRef.current > 1) {
             container.classList.remove("preview-revealing");
@@ -192,6 +221,8 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
           iframe.removeEventListener("load", handleLoad);
           player.removeEventListener("click", preventToggle, { capture: true });
           player.removeEventListener("shadertransitionstate", handleShaderTransitionState);
+          player.removeEventListener("ready", handleReady);
+          player.removeEventListener("error", handleError);
           if (assetPollRef.current) clearInterval(assetPollRef.current);
           assetPollRef.current = null;
           container.removeChild(player);
@@ -237,7 +268,13 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
       };
     }, [assetsLoading]);
 
-    const showAssetOverlay = assetOverlayVisible && !shaderTransitionLoading;
+    const showCompositionOverlay = shouldShowCompositionLoadingOverlay(compositionLoading);
+    const showAssetOverlay =
+      assetOverlayVisible && !shaderTransitionLoading && !showCompositionOverlay;
+
+    useEffect(() => {
+      onCompositionLoadingChange?.(showCompositionOverlay);
+    }, [onCompositionLoadingChange, showCompositionOverlay]);
 
     return (
       <div
@@ -245,6 +282,23 @@ export const Player = forwardRef<HTMLIFrameElement, PlayerProps>(
         style={style}
       >
         <div ref={containerRef} className="w-full h-full" />
+        {showCompositionOverlay && (
+          <div
+            className="absolute inset-0 bg-black flex items-center justify-center z-30 select-none"
+            data-hyperframes-ignore=""
+            data-testid="composition-loading-overlay"
+            draggable={false}
+            onDragStart={(event) => event.preventDefault()}
+            onMouseDown={(event) => event.preventDefault()}
+            onPointerDown={(event) => event.preventDefault()}
+          >
+            <HyperframesLoader
+              title="Loading composition"
+              detail="Preparing the Studio preview."
+              size={56}
+            />
+          </div>
+        )}
         {showAssetOverlay && (
           <div
             className="absolute inset-0 bg-black flex items-center justify-center z-20 select-none"