@hyperframes/studio 0.8.51 → 0.8.53-desktop.0

package/src/components/editor/usePreviewCompositionRect.test.tsx

@@ -0,0 +1,95 @@
+// @vitest-environment happy-dom
+
+import { act, useRef } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it } from "vitest";
+import { usePreviewIframeStore } from "../../player/store/previewIframeStore";
+import {
+  usePreviewCompositionRect,
+  type PreviewCompositionRect,
+} from "./usePreviewCompositionRect";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+afterEach(() => {
+  usePreviewIframeStore.getState().setIframe(null);
+  document.body.innerHTML = "";
+});
+
+function boxed<T extends HTMLElement>(el: T, box: [number, number, number, number]): T {
+  const [left, top, width, height] = box;
+  el.getBoundingClientRect = () => new DOMRect(left, top, width, height);
+  return el;
+}
+
+function mountProbe() {
+  let rect: PreviewCompositionRect | undefined;
+  function Probe() {
+    const ref = useRef<HTMLDivElement>(null);
+    rect = usePreviewCompositionRect(ref);
+    return (
+      <div
+        ref={(el) => {
+          ref.current = el;
+          if (el) boxed(el, [10, 20, 1000, 600]);
+        }}
+      />
+    );
+  }
+  const host = document.createElement("div");
+  document.body.append(host);
+  act(() => createRoot(host).render(<Probe />));
+  return () => rect;
+}
+
+function compositionFrame(box: [number, number, number, number], width: number, height: number) {
+  const iframe = boxed(document.createElement("iframe"), box);
+  document.body.append(iframe);
+  const root = iframe.contentDocument?.createElement("div");
+  root?.setAttribute("data-composition-id", "main");
+  root?.setAttribute("data-width", String(width));
+  root?.setAttribute("data-height", String(height));
+  if (root) iframe.contentDocument?.body.append(root);
+  return iframe;
+}
+
+const settle = () => new Promise((r) => setTimeout(r, 400));
+
+describe("usePreviewCompositionRect", () => {
+  it("reports the live preview iframe's box relative to the overlay, scaled to the composition", async () => {
+    const read = mountProbe();
+    const iframe = compositionFrame([110, 70, 960, 540], 1920, 1080);
+    await act(async () => {
+      usePreviewIframeStore.getState().setIframe(iframe);
+      await settle();
+    });
+    expect(read()).toEqual({
+      left: 100,
+      top: 50,
+      width: 960,
+      height: 540,
+      scaleX: 0.5,
+      scaleY: 0.5,
+    });
+  });
+
+  it("follows the iframe when a reload replaces it", async () => {
+    const read = mountProbe();
+    await act(async () => {
+      usePreviewIframeStore.getState().setIframe(compositionFrame([110, 70, 960, 540], 1920, 1080));
+      await settle();
+    });
+    await act(async () => {
+      usePreviewIframeStore.getState().setIframe(compositionFrame([60, 40, 500, 500], 1000, 1000));
+      await settle();
+    });
+    expect(read()).toEqual({
+      left: 50,
+      top: 20,
+      width: 500,
+      height: 500,
+      scaleX: 0.5,
+      scaleY: 0.5,
+    });
+  });
+});

package/src/components/editor/usePreviewCompositionRect.ts

@@ -0,0 +1,21 @@
+import { useMemo, type RefObject } from "react";
+import { usePreviewIframeStore } from "../../player/store/previewIframeStore";
+import { useDomEditCompositionRect } from "./useDomEditCompositionRect";
+
+export type { DomEditCompositionRect as PreviewCompositionRect } from "./useDomEditCompositionRect";
+
+/**
+ * Where the composition sits inside `overlayRef`, in overlay pixels, plus the scale from
+ * composition units to pixels. Follows the live preview iframe across reloads.
+ */
+export function usePreviewCompositionRect(overlayRef: RefObject<HTMLDivElement | null>) {
+  const iframeRef = useMemo<RefObject<HTMLIFrameElement | null>>(
+    () => ({
+      get current() {
+        return usePreviewIframeStore.getState().iframe;
+      },
+    }),
+    [],
+  );
+  return useDomEditCompositionRect({ iframeRef, overlayRef });
+}

package/src/components/nle/NLEContext.tsx

@@ -4,17 +4,11 @@ import { useTimelinePlayer, usePlayerStore } from "../../player";
 import type { TimelineElement } from "../../player";
 import type { CompositionLevel } from "./CompositionBreadcrumb";
 import { useCompositionStack } from "./useCompositionStack";
-import { MIN_TIMELINE_H, fitTimelineHeight } from "../../utils/fitPanels";
 import { setCompositionSourceMap } from "../editor/domEditingDom";
 import { ensureMotionPathPluginLoaded } from "../../utils/gsapSoftReload";
-import { readStudioUiPreferences, writeStudioUiPreferences } from "../../utils/studioUiPreferences";
 import { useAssetPreviewStore } from "../../utils/assetPreviewStore";
 import { createStableContext } from "../../utils/hmrStableContext";
 
-// Timeline gets a generous default height so the preview isn't oversized and the
-// tracks have room to breathe (CapCut-style). Users can still drag the divider.
-const DEFAULT_TIMELINE_H = 360;
-
 export function shouldDisableTimelineWhileCompositionLoading(compositionLoading: boolean): boolean {
   return compositionLoading;
 }
@@ -34,10 +28,6 @@ export interface NLEContextValue {
   handleDrillDown: (element: TimelineElement) => void;
   compIdToSrc: Map<string, string>;
   // layout state
-  timelineH: number;
-  setTimelineH: React.Dispatch<React.SetStateAction<number>>;
-  persistTimelineH: (height: number) => void;
-  containerRef: React.RefObject<HTMLDivElement | null>;
   // composition loading
   compositionLoading: boolean;
   setCompositionLoading: (loading: boolean) => void;
@@ -256,35 +246,6 @@ export function NLEProvider({
     });
   }, [compIdToSrc]);
 
-  // Resizable timeline height — persisted alongside zoom/pan so the user's
-  // workspace layout survives reloads.
-  const [timelineH, setTimelineH] = useState(() => {
-    const stored = readStudioUiPreferences().timelineHeight;
-    return stored !== undefined && stored >= MIN_TIMELINE_H ? stored : DEFAULT_TIMELINE_H;
-  });
-  const persistTimelineH = useCallback((height: number) => {
-    writeStudioUiPreferences({ timelineHeight: Math.round(height) });
-  }, []);
-  const containerRef = useRef<HTMLDivElement>(null);
-  // A height persisted on a tall window can exceed this window's container and
-  // collapse the flex-1 preview to 0px. Observing the container rather than
-  // clamping once at mount is what makes a window RESIZED after load behave the
-  // same as one loaded at that size: dragging 760 -> 520 tall used to leave the
-  // timeline at its stored 429px and the preview at 47px.
-  useEffect(() => {
-    const element = containerRef.current;
-    if (!element || typeof ResizeObserver === "undefined") return;
-    const reconcile = () => {
-      const containerH = element.getBoundingClientRect().height;
-      if (!containerH) return;
-      setTimelineH((prev) => fitTimelineHeight(containerH, prev));
-    };
-    reconcile();
-    const observer = new ResizeObserver(reconcile);
-    observer.observe(element);
-    return () => observer.disconnect();
-  }, []);
-
   const hasLoadedOnceRef = useRef(false);
   const [compositionLoading, setCompositionLoadingRaw] = useState(true);
   const setCompositionLoading = useCallback((loading: boolean) => {
@@ -317,10 +278,6 @@ export function NLEProvider({
     handleNavigateComposition,
     handleDrillDown,
     compIdToSrc,
-    timelineH,
-    setTimelineH,
-    persistTimelineH,
-    containerRef,
     compositionLoading,
     setCompositionLoading,
     timelineDisabled,

package/src/components/nle/NLEPreview.tsx

@@ -442,7 +442,7 @@ export const NLEPreview = memo(function NLEPreview({
     <div className="flex flex-col h-full min-h-0">
       <div
         ref={viewportRef}
-        className="relative flex-1 flex items-center justify-center p-2 overflow-hidden min-h-0 outline-hidden focus:ring-1 focus:ring-studio-accent/40 bg-neutral-950"
+        className="relative flex-1 flex items-center justify-center p-2 overflow-hidden min-h-0 outline-hidden focus:ring-1 focus:ring-studio-accent/40 bg-[var(--studio-preview-bg,var(--color-neutral-950))]"
         tabIndex={0}
         aria-label="Composition preview"
       >

package/src/components/nle/PreviewPane.tsx

@@ -110,7 +110,7 @@ export function PreviewPane({
       ref={containerRef}
       // Panel chrome (rounded border) is dropped in fullscreen so the preview
       // fills the screen edge-to-edge.
-      className={`flex-1 min-h-0 flex flex-col overflow-hidden bg-neutral-950 ${
+      className={`flex-1 min-h-0 flex flex-col overflow-hidden bg-[var(--studio-preview-bg,var(--color-neutral-950))] ${
         isFullscreen ? "" : "rounded-lg border border-neutral-800/50"
       }`}
       data-studio-fullscreen-target=""

package/src/components/nle/TimelinePane.tsx

@@ -2,7 +2,6 @@ import { useCallback, type ReactNode } from "react";
 import { Timeline } from "../../player";
 import type { TimelineElement } from "../../player";
 import type { BlockedTimelineEditIntent } from "../../player/components/timelineEditing";
-import { TimelineResizeDivider } from "./TimelineResizeDivider";
 import { useTimelineEditContext } from "../../contexts/TimelineEditContext";
 import { trackStudioExpandedClipEdit } from "../../telemetry/events";
 import { useNLEContext } from "./NLEContext";
@@ -78,6 +77,9 @@ export interface TimelinePaneProps {
   timelineToolbar?: ReactNode;
   /** Slot rendered below the timeline tracks */
   timelineFooter?: ReactNode;
+  /** Slot for a host's own overlay spanning the whole timeline area (e.g. a draft/ghost
+   *  clip), positioned absolutely the same way PreviewPane's previewOverlay is. */
+  timelineOverlay?: ReactNode;
   /** Custom clip content renderer for timeline (thumbnails, waveforms, etc.) */
   renderClipContent?: (
     element: TimelineElement,
@@ -114,6 +116,7 @@ export interface TimelinePaneProps {
 export function TimelinePane({
   timelineToolbar,
   timelineFooter,
+  timelineOverlay,
   renderClipContent,
   onFileDrop,
   onDeleteElement,
@@ -132,10 +135,6 @@ export function TimelinePane({
     handleDrillDown,
     compositionStack,
     updateCompositionStack,
-    timelineH,
-    setTimelineH,
-    persistTimelineH,
-    containerRef,
     timelineDisabled,
     timelineSessionEpoch,
   } = useNLEContext();
@@ -254,72 +253,59 @@ export function TimelinePane({
   );
 
   return (
-    <>
-      <TimelineResizeDivider
-        timelineH={timelineH}
-        setTimelineH={setTimelineH}
-        persistTimelineH={persistTimelineH}
-        containerRef={containerRef}
-        disabled={timelineDisabled}
-      />
-
-      {/* Timeline section — inner padding (not margin) keeps the divider's
-          height math exact while giving the panel a gap from the shell edges. */}
+    <div className="relative flex h-full flex-col" aria-disabled={timelineDisabled || undefined}>
       <div
-        className="relative flex flex-col shrink-0 px-px pb-px"
-        style={{ height: timelineH }}
-        aria-disabled={timelineDisabled || undefined}
+        className="flex flex-col flex-1 min-h-0 overflow-hidden rounded-lg border border-neutral-800/50 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));
+          }
+        }}
       >
+        <div className="shrink-0">{timelineToolbar}</div>
+        <Timeline
+          sessionEpoch={timelineSessionEpoch}
+          onSeek={seek}
+          onDrillDown={handleDrillDown}
+          renderClipContent={renderClipContent}
+          onFileDrop={onFileDrop}
+          onDeleteElement={handleDeleteElement}
+          onAssetDrop={onAssetDrop}
+          onBlockDrop={onBlockDrop}
+          onCompositionDrop={onCompositionDrop}
+          onMoveElement={handleMoveElement}
+          onMoveElements={handleMoveElements}
+          onResizeElement={handleResizeElement}
+          onResizeElements={handleResizeElements}
+          onBlockedEditAttempt={onBlockedEditAttempt}
+          onSplitElement={handleSplitElement}
+          onSelectElement={onSelectTimelineElement}
+          onCopyClip={onCopyClip}
+          onPasteClip={onPasteClip}
+          onDuplicateClip={onDuplicateClip}
+          canPasteClip={canPasteClip}
+        />
+      </div>
+      {timelineFooter && <div className="shrink-0">{timelineFooter}</div>}
+      {timelineOverlay && (
+        <div className="pointer-events-none absolute inset-0 z-20">{timelineOverlay}</div>
+      )}
+      {timelineDisabled && (
         <div
-          className="flex flex-col flex-1 min-h-0 overflow-hidden rounded-lg border border-neutral-800/50 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));
-            }
-          }}
+          className="absolute inset-0 z-30 cursor-not-allowed bg-black/18 flex items-center justify-center"
+          data-testid="timeline-loading-disabled-overlay"
+          role="status"
+          onPointerDown={(event) => event.preventDefault()}
+          onDragOver={(event) => event.preventDefault()}
+          onDrop={(event) => event.preventDefault()}
         >
-          <div className="shrink-0">{timelineToolbar}</div>
-          <Timeline
-            sessionEpoch={timelineSessionEpoch}
-            onSeek={seek}
-            onDrillDown={handleDrillDown}
-            renderClipContent={renderClipContent}
-            onFileDrop={onFileDrop}
-            onDeleteElement={handleDeleteElement}
-            onAssetDrop={onAssetDrop}
-            onBlockDrop={onBlockDrop}
-            onCompositionDrop={onCompositionDrop}
-            onMoveElement={handleMoveElement}
-            onMoveElements={handleMoveElements}
-            onResizeElement={handleResizeElement}
-            onResizeElements={handleResizeElements}
-            onBlockedEditAttempt={onBlockedEditAttempt}
-            onSplitElement={handleSplitElement}
-            onSelectElement={onSelectTimelineElement}
-            onCopyClip={onCopyClip}
-            onPasteClip={onPasteClip}
-            onDuplicateClip={onDuplicateClip}
-            canPasteClip={canPasteClip}
-          />
+          <span className="rounded-md bg-neutral-900/90 px-2.5 py-1 text-[11px] text-neutral-400">
+            Loading composition…
+          </span>
         </div>
-        {timelineFooter && <div className="shrink-0">{timelineFooter}</div>}
-        {timelineDisabled && (
-          <div
-            className="absolute inset-0 z-30 cursor-not-allowed bg-black/18 flex items-center justify-center"
-            data-testid="timeline-loading-disabled-overlay"
-            role="status"
-            onPointerDown={(event) => event.preventDefault()}
-            onDragOver={(event) => event.preventDefault()}
-            onDrop={(event) => event.preventDefault()}
-          >
-            <span className="rounded-md bg-neutral-900/90 px-2.5 py-1 text-[11px] text-neutral-400">
-              Loading composition…
-            </span>
-          </div>
-        )}
-      </div>
-    </>
+      )}
+    </div>
   );
 }

package/src/components/panels/SlideshowPanel.tsx

@@ -156,7 +156,7 @@ export function makeSlideshowNotesController(): NotesController {
 // ── Component ─────────────────────────────────────────────────────────────
 
 export interface SlideshowPanelProps {
-  /** Scenes from the live clip manifest (passed from StudioRightPanel). */
+  /** Scenes from the live clip manifest (passed from StudioRightPanels). */
   scenes: import("./slideshowPanelHelpers").SceneInfo[];
   /**
    * Called with the updated manifest after every discrete edit (toggle, add,

package/src/components/panels/VariablesPanel.tsx

@@ -246,7 +246,7 @@ const EMPTY_STATE = (
   </p>
 );
 
-// Panel orchestrator — JSX conditionals per section, same shape as StudioRightPanel.
+// Panel orchestrator — JSX conditionals per section, same shape as StudioRightPanels.
 // fallow-ignore-next-line complexity
 export const VariablesPanel = memo(function VariablesPanel({
   sdkSession,

package/src/components/pointerTargetSize.test.tsx

@@ -6,6 +6,14 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import { CompositionsTab } from "./sidebar/CompositionsTab";
 import { TimelineToolbar } from "./TimelineToolbar";
 
+vi.mock("../contexts/StudioContext", () => ({
+  useStudioShellContext: () => ({
+    editHistory: { canUndo: false, canRedo: false },
+    handleUndo: vi.fn(),
+    handleRedo: vi.fn(),
+  }),
+}));
+
 // WCAG 2.2 (2.5.8) requires a 24x24 CSS pixel pointer target. happy-dom has no
 // CSS engine, so getBoundingClientRect() is 0x0 for everything here and the size
 // itself cannot be measured — these assert the utility classes that PRODUCE the

package/src/components/renders/RenderQueue.tsx

@@ -22,7 +22,7 @@ type StartRenderHandler = (
   fps: 24 | 30 | 60,
 ) => void | Promise<void>;
 
-interface RenderQueueProps {
+export interface RenderQueueProps {
   jobs: RenderJob[];
   projectId: string;
   onDelete: (jobId: string) => void;

package/src/components/renders/RenderQueuePanel.tsx

@@ -7,7 +7,7 @@ import { usePreviewVariablesStore } from "../../hooks/previewVariablesStore";
 /**
  * The Renders tab, wired to the shell context.
  *
- * Split out of StudioRightPanel because every field it needs already lives in
+ * Split out of StudioRightPanels because every field it needs already lives in
  * that context, so routing them through the panel only made the panel longer
  * without giving anything a second reader.
  */

package/src/components/sidebar/{LeftSidebar.masterComposition.test.tsx → CompositionsPanel.masterComposition.test.tsx}

@@ -4,7 +4,7 @@ import { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { usePlayerStore } from "../../player/store/playerStore";
-import { LeftSidebar } from "./LeftSidebar";
+import { CompositionsPanel } from "./CompositionsPanel";
 
 Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
 (
@@ -20,23 +20,20 @@ afterEach(() => {
   usePlayerStore.setState({ thumbnailContentRevision: 0 });
 });
 
-describe("LeftSidebar root badge source", () => {
+describe("CompositionsPanel root badge source", () => {
   it("derives the root badge from the filtered compositions list, not the raw file tree", () => {
-    // `fileTree` includes a non-composition index.html (a vendored preset) that the
-    // server's filtered `compositions` list excludes — the badge must source from
-    // `compositions`, not the raw file tree.
+    // The project's raw file tree can hold a non-composition index.html (a vendored
+    // preset); the badge must source from the server's filtered `compositions` list.
     const host = document.createElement("div");
     document.body.append(host);
     root = createRoot(host);
     act(() => {
       root?.render(
-        <LeftSidebar
+        <CompositionsPanel
           projectId="demo"
           compositions={["hero.html"]}
-          assets={[]}
-          fileTree={["index.html", "hero.html"]}
           activeComposition={null}
-          onSelectComposition={vi.fn()}
+          onSelect={vi.fn()}
         />,
       );
     });

package/src/components/sidebar/CompositionsPanel.tsx

@@ -0,0 +1,15 @@
+import type { ComponentProps } from "react";
+import { resolveMasterCompositionPath } from "../../utils/studioUrlState";
+import { CompositionsTab } from "./CompositionsTab";
+
+type Props = Omit<ComponentProps<typeof CompositionsTab>, "masterCompositionPath">;
+
+/** The Compositions dock panel body; the root badge comes from the filtered composition list. */
+export function CompositionsPanel(props: Props) {
+  return (
+    <CompositionsTab
+      {...props}
+      masterCompositionPath={resolveMasterCompositionPath(props.compositions)}
+    />
+  );
+}

package/src/components/sidebar/{LeftSidebar.lintBadge.test.tsx → SidebarLintButton.test.tsx}

@@ -3,7 +3,7 @@
 import { act } from "react";
 import { createRoot, type Root } from "react-dom/client";
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { LeftSidebar } from "./LeftSidebar";
+import { SidebarLintButton } from "./SidebarLintButton";
 
 Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
 (
@@ -24,23 +24,18 @@ function renderBadge(lintHasError: boolean): HTMLElement | null {
   root = createRoot(host);
   act(() => {
     root?.render(
-      <LeftSidebar
-        projectId="demo"
-        compositions={["index.html"]}
-        assets={[]}
-        fileTree={["index.html"]}
-        activeComposition={null}
-        onSelectComposition={vi.fn()}
+      <SidebarLintButton
         onLint={vi.fn()}
-        lintFindingCount={2}
-        lintHasError={lintHasError}
+        linting={false}
+        findingCount={2}
+        hasError={lintHasError}
       />,
     );
   });
   return host.querySelector<HTMLElement>("[data-lint-badge]");
 }
 
-describe("LeftSidebar lint badge", () => {
+describe("SidebarLintButton badge", () => {
   it("pulses, and stops for reduced motion, while an error finding exists", () => {
     const badge = renderBadge(true);
     expect(badge?.dataset.lintBadge).toBe("error");

package/src/components/sidebar/SidebarLintButton.tsx

@@ -0,0 +1,50 @@
+export function SidebarLintButton({
+  onLint,
+  linting,
+  findingCount,
+  hasError,
+}: {
+  onLint: () => void;
+  linting: boolean;
+  findingCount?: number;
+  hasError?: boolean;
+}) {
+  return (
+    <div className="border-t border-neutral-800 p-2 shrink-0">
+      <button
+        type="button"
+        onClick={onLint}
+        disabled={linting}
+        className="w-full flex items-center justify-center gap-1.5 px-2 py-1.5 rounded-md text-[11px] font-medium text-neutral-500 enabled:hover:text-amber-300 enabled:hover:bg-neutral-800 enabled:active:scale-[0.98] transition-colors disabled:opacity-40"
+      >
+        <svg
+          width="12"
+          height="12"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="2"
+        >
+          <path d="M9 11l3 3L22 4" />
+          <path d="M21 12v7a2 2 0 01-2 2H5a2 2 0 01-2-2V5a2 2 0 012-2h11" />
+        </svg>
+        {linting ? "Linting…" : "Lint"}
+        {!linting && findingCount != null && findingCount > 0 && (
+          <span
+            data-lint-badge={hasError ? "error" : "warning"}
+            className={
+              hasError
+                ? "ml-1 min-w-[16px] rounded-full bg-panel-danger/25 px-1 text-[9px] font-bold text-panel-danger animate-pulse motion-reduce:animate-none"
+                : "ml-1 min-w-[16px] rounded-full bg-amber-500/20 px-1 text-[9px] font-bold text-amber-400"
+            }
+          >
+            {findingCount}
+            <span className="sr-only">
+              {hasError ? " lint findings, including errors" : " lint findings, warnings only"}
+            </span>
+          </span>
+        )}
+      </button>
+    </div>
+  );
+}

package/src/components/timelineToolbarStyles.ts

@@ -0,0 +1,5 @@
+// CapCut-flat icon buttons: a transparent 28px hit area with a subtle hover wash.
+export const flatBtn = "flex h-7 w-7 items-center justify-center rounded-md transition-colors";
+export const flatIdle = `${flatBtn} text-neutral-400 hover:bg-white/6 hover:text-neutral-200 active:scale-[0.98]`;
+export const flatActive = `${flatBtn} bg-white/8 text-neutral-100 active:scale-[0.98]`;
+export const flatDisabled = `${flatBtn} text-neutral-700 cursor-not-allowed`;