@hyperframes/studio 0.6.0-alpha.1 → 0.6.0-alpha.11

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,18 @@ export const NLELayout = memo(function NLELayout({
 
   // Resizable timeline height
   const [timelineH, setTimelineH] = useState(DEFAULT_TIMELINE_H);
+  const hasLoadedOnceRef = useRef(false);
+  const [compositionLoading, setCompositionLoadingRaw] = useState(true);
+  const setCompositionLoading = useCallback((loading: boolean) => {
+    if (!loading) hasLoadedOnceRef.current = true;
+    if (loading && hasLoadedOnceRef.current) return;
+    setCompositionLoadingRaw(loading);
+  }, []);
+  const timelineDisabled = shouldDisableTimelineWhileCompositionLoading(compositionLoading);
+
+  useEffect(() => {
+    onCompositionLoadingChangeParent?.(compositionLoading);
+  }, [compositionLoading, onCompositionLoadingChangeParent]);
   const isTimelineVisible = timelineVisible ?? true;
   const isDragging = useRef(false);
   const containerRef = useRef<HTMLDivElement>(null);
@@ -327,23 +342,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,9 +397,11 @@ export const NLELayout = memo(function NLELayout({
             projectId={projectId}
             iframeRef={iframeRef}
             onIframeLoad={onIframeLoad}
+            onCompositionLoadingChange={setCompositionLoading}
             portrait={portrait}
             directUrl={directUrl}
             refreshKey={refreshKey}
+            suppressLoadingOverlay={hasLoadedOnceRef.current}
           />
           {previewOverlay}
         </div>
@@ -388,7 +413,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 +431,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 +463,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,9 +5,11 @@ interface NLEPreviewProps {
   projectId: string;
   iframeRef: Ref<HTMLIFrameElement>;
   onIframeLoad: () => void;
+  onCompositionLoadingChange?: (loading: boolean) => void;
   portrait?: boolean;
   directUrl?: string;
   refreshKey?: number;
+  suppressLoadingOverlay?: boolean;
 }
 
 export function getPreviewPlayerKey({
@@ -36,9 +38,11 @@ export const NLEPreview = memo(function NLEPreview({
   projectId,
   iframeRef,
   onIframeLoad,
+  onCompositionLoadingChange,
   portrait,
   directUrl,
   refreshKey,
+  suppressLoadingOverlay,
 }: NLEPreviewProps) {
   const baseKey = getPreviewPlayerKey({ projectId, directUrl, refreshKey });
   const prevRefreshKeyRef = useRef(refreshKey);
@@ -88,8 +92,10 @@ 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}
+          suppressLoadingOverlay={suppressLoadingOverlay}
         />
       </div>
     </div>

package/src/components/renders/RenderQueue.tsx

@@ -1,10 +1,27 @@
 import { memo, useState, useRef, useEffect } from "react";
 import { RenderQueueItem } from "./RenderQueueItem";
-import type { RenderJob } from "./useRenderQueue";
+import type { RenderJob, ResolutionPreset } from "./useRenderQueue";
+
+export interface CompositionDimensions {
+  width: number;
+  height: number;
+}
+
+const RESOLUTION_OPTIONS: { value: ResolutionPreset | "auto"; label: string }[] = [
+  { value: "auto", label: "Auto" },
+  { value: "landscape", label: "1080p" },
+  { value: "landscape-4k", label: "4K" },
+  { value: "portrait", label: "1080p ↕" },
+  { value: "portrait-4k", label: "4K ↕" },
+  { value: "square", label: "Square" },
+  { value: "square-4k", label: "Square 4K" },
+];
 
 type StartRenderHandler = (
   format: "mp4" | "webm" | "mov",
   quality: "draft" | "standard" | "high",
+  resolution: ResolutionPreset | "auto",
+  fps: 24 | 30 | 60,
 ) => void | Promise<void>;
 
 interface RenderQueueProps {
@@ -14,6 +31,12 @@ interface RenderQueueProps {
   onClearCompleted: () => void;
   onStartRender: StartRenderHandler;
   isRendering: boolean;
+  /**
+   * Authored dimensions of the active composition. Used to pick the
+   * matching preset (landscape / portrait / square) when the user selects
+   * a 1080p or 4K scale. `null` falls back to landscape (legacy default).
+   */
+  compositionDimensions?: CompositionDimensions | null;
 }
 
 const FORMAT_INFO: Record<"mp4" | "webm" | "mov", { label: string; desc: string }> = {
@@ -101,6 +124,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 +133,29 @@ 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}
+        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((opt) => (
+          <option key={opt.value} value={opt.value}>
+            {opt.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 +164,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 +187,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 = {