@hyperframes/studio 0.7.71 → 0.7.73

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

@@ -0,0 +1,143 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { ColorGradingCapturedFrame } from "./useColorGradingPreviews";
+import { useColorGradingScopes } from "./useColorGradingScopes";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  vi.useRealTimers();
+  vi.restoreAllMocks();
+});
+
+function Harness({
+  open,
+  refreshKey,
+  captureFrame,
+}: {
+  open: boolean;
+  refreshKey: string;
+  captureFrame: () => Promise<ColorGradingCapturedFrame | null>;
+}) {
+  const scopes = useColorGradingScopes({ open, refreshKey, captureFrame });
+  return (
+    <>
+      <span data-status>{scopes.status}</span>
+      <span data-analysis>{scopes.analysis ? "ready" : "empty"}</span>
+      <button type="button" onClick={scopes.refresh}>
+        Refresh
+      </button>
+    </>
+  );
+}
+
+function installPixelDecode() {
+  vi.spyOn(HTMLImageElement.prototype, "decode").mockResolvedValue();
+  vi.spyOn(HTMLCanvasElement.prototype, "getContext").mockReturnValue({
+    drawImage: vi.fn(),
+    getImageData: vi.fn().mockReturnValue({
+      data: new Uint8ClampedArray([255, 255, 255, 255]),
+    }),
+  } as unknown as CanvasRenderingContext2D);
+}
+
+function renderScopeHarness({ open, refreshKey = "a" }: { open: boolean; refreshKey?: string }) {
+  vi.useFakeTimers();
+  installPixelDecode();
+  const captureFrame = vi.fn().mockResolvedValue({
+    dataUrl: "data:image/png;base64,scope",
+    width: 1,
+    height: 1,
+  });
+  const host = document.body.appendChild(document.createElement("div"));
+  const root = createRoot(host);
+  act(() =>
+    root.render(<Harness open={open} refreshKey={refreshKey} captureFrame={captureFrame} />),
+  );
+  return { captureFrame, host, root };
+}
+
+describe("useColorGradingScopes", () => {
+  it("captures once on open rather than polling during playback", async () => {
+    const { captureFrame, host, root } = renderScopeHarness({ open: false });
+    await act(async () => vi.advanceTimersByTimeAsync(1000));
+    expect(captureFrame).not.toHaveBeenCalled();
+
+    act(() => root.render(<Harness open refreshKey="a" captureFrame={captureFrame} />));
+    await act(async () => vi.advanceTimersByTimeAsync(180));
+    expect(captureFrame).toHaveBeenCalledOnce();
+    expect(host.querySelector("[data-status]")?.textContent).toBe("ready");
+
+    await act(async () => vi.advanceTimersByTimeAsync(5000));
+    expect(captureFrame).toHaveBeenCalledOnce();
+    act(() => root.unmount());
+  });
+
+  it("refreshes only after a committed grading key or explicit request", async () => {
+    const { captureFrame, host, root } = renderScopeHarness({ open: true });
+    await act(async () => vi.advanceTimersByTimeAsync(180));
+
+    act(() => root.render(<Harness open refreshKey="b" captureFrame={captureFrame} />));
+    await act(async () => vi.advanceTimersByTimeAsync(180));
+    expect(captureFrame).toHaveBeenCalledTimes(2);
+
+    act(() => {
+      host.querySelector("button")?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    });
+    await act(async () => vi.advanceTimersByTimeAsync(180));
+    expect(captureFrame).toHaveBeenCalledTimes(3);
+    act(() => root.unmount());
+  });
+
+  it("reports unavailable when capture returns no frame", async () => {
+    vi.useFakeTimers();
+    const host = document.body.appendChild(document.createElement("div"));
+    const root = createRoot(host);
+    act(() =>
+      root.render(<Harness open refreshKey="a" captureFrame={vi.fn().mockResolvedValue(null)} />),
+    );
+
+    await act(async () => vi.advanceTimersByTimeAsync(180));
+    expect(host.querySelector("[data-status]")?.textContent).toBe("unavailable");
+    act(() => root.unmount());
+  });
+
+  it("clears stale analysis while a refresh is pending and when it is unavailable", async () => {
+    vi.useFakeTimers();
+    installPixelDecode();
+    let resolveRefresh: (frame: ColorGradingCapturedFrame | null) => void = () => {};
+    const pendingRefresh = new Promise<ColorGradingCapturedFrame | null>((resolve) => {
+      resolveRefresh = resolve;
+    });
+    const captureFrame = vi
+      .fn()
+      .mockResolvedValueOnce({
+        dataUrl: "data:image/png;base64,scope",
+        width: 1,
+        height: 1,
+      })
+      .mockReturnValueOnce(pendingRefresh);
+    const host = document.body.appendChild(document.createElement("div"));
+    const root = createRoot(host);
+    act(() => root.render(<Harness open refreshKey="a" captureFrame={captureFrame} />));
+
+    await act(async () => vi.advanceTimersByTimeAsync(180));
+    expect(host.querySelector("[data-analysis]")?.textContent).toBe("ready");
+
+    act(() => {
+      host.querySelector("button")?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    });
+    act(() => vi.advanceTimersByTime(180));
+    expect(host.querySelector("[data-status]")?.textContent).toBe("loading");
+    expect(host.querySelector("[data-analysis]")?.textContent).toBe("empty");
+
+    await act(async () => resolveRefresh(null));
+    expect(host.querySelector("[data-status]")?.textContent).toBe("unavailable");
+    expect(host.querySelector("[data-analysis]")?.textContent).toBe("empty");
+    act(() => root.unmount());
+  });
+});

package/src/components/editor/useColorGradingScopes.ts

@@ -0,0 +1,62 @@
+import { useEffect, useRef, useState } from "react";
+import type { ColorGradingCapturedFrame } from "./useColorGradingPreviews";
+import {
+  analyzeColorGradingFrame,
+  readColorGradingFramePixels,
+  type ColorGradingScopeAnalysis,
+} from "./colorGradingFrameAnalysis";
+
+type ColorGradingScopeStatus = "idle" | "loading" | "ready" | "unavailable";
+const CAPTURE_DEBOUNCE_MS = 180;
+
+export function useColorGradingScopes({
+  open,
+  captureFrame,
+  refreshKey,
+}: {
+  open: boolean;
+  captureFrame: () => Promise<ColorGradingCapturedFrame | null>;
+  refreshKey: string;
+}) {
+  const [analysis, setAnalysis] = useState<ColorGradingScopeAnalysis | null>(null);
+  const [status, setStatus] = useState<ColorGradingScopeStatus>("idle");
+  const [refreshVersion, setRefreshVersion] = useState(0);
+  const captureRef = useRef(captureFrame);
+  captureRef.current = captureFrame;
+
+  useEffect(() => {
+    if (!open) {
+      setAnalysis(null);
+      setStatus("idle");
+      return;
+    }
+    let cancelled = false;
+    const timer = window.setTimeout(async () => {
+      setAnalysis(null);
+      setStatus("loading");
+      try {
+        const frame = await captureRef.current();
+        if (cancelled) return;
+        if (!frame) {
+          setStatus("unavailable");
+          return;
+        }
+        const pixels = await readColorGradingFramePixels(frame);
+        if (!pixels) throw new Error("Canvas 2D unavailable");
+        const next = analyzeColorGradingFrame(pixels, frame.width, frame.height);
+        if (!cancelled) {
+          setAnalysis(next);
+          setStatus("ready");
+        }
+      } catch {
+        if (!cancelled) setStatus("unavailable");
+      }
+    }, CAPTURE_DEBOUNCE_MS);
+    return () => {
+      cancelled = true;
+      window.clearTimeout(timer);
+    };
+  }, [open, refreshKey, refreshVersion]);
+
+  return { analysis, status, refresh: () => setRefreshVersion((version) => version + 1) };
+}

package/src/components/editor/useInspectorGestureTransaction.ts

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useRef } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 
 /** One owner for continuous inspector edits: preview freely, persist once. */
 export function useInspectorGestureTransaction<T>({
@@ -58,3 +58,32 @@ export function useInspectorGestureTransaction<T>({
 
   return { begin, preview, settle, cancel, activeRef };
 }
+
+export function useInspectorGestureDraft<T>({
+  sourceValue,
+  onPreview,
+  onCommit,
+}: {
+  sourceValue: T;
+  onPreview: (value: T) => void;
+  onCommit: (value: T) => void;
+}) {
+  const [draft, setDraft] = useState(sourceValue);
+  const transaction = useInspectorGestureTransaction({
+    sourceValue,
+    onPreview: (next) => {
+      setDraft(next);
+      onPreview(next);
+    },
+    onCommit: (next) => {
+      setDraft(next);
+      onCommit(next);
+    },
+  });
+
+  useEffect(() => {
+    if (!transaction.activeRef.current) setDraft(sourceValue);
+  }, [sourceValue, transaction.activeRef]);
+
+  return { draft, setDraft, transaction };
+}

package/src/components/nle/NLEContext.tsx

@@ -19,7 +19,7 @@ import { useAssetPreviewStore } from "../../utils/assetPreviewStore";
 
 // 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 = 340;
+const DEFAULT_TIMELINE_H = 360;
 
 export function shouldDisableTimelineWhileCompositionLoading(compositionLoading: boolean): boolean {
   return compositionLoading;

package/src/contexts/PanelLayoutContext.tsx

@@ -14,9 +14,8 @@ export function usePanelLayoutContext(): PanelLayoutValue {
 export function PanelLayoutProvider({
   value: {
     leftWidth,
-    setLeftWidth,
     rightWidth,
-    setRightWidth,
+    adjustPanelWidth,
     leftCollapsed,
     setLeftCollapsed,
     rightCollapsed,
@@ -39,9 +38,8 @@ export function PanelLayoutProvider({
   const stable = useMemo<PanelLayoutValue>(
     () => ({
       leftWidth,
-      setLeftWidth,
       rightWidth,
-      setRightWidth,
+      adjustPanelWidth,
       leftCollapsed,
       setLeftCollapsed,
       rightCollapsed,
@@ -58,9 +56,8 @@ export function PanelLayoutProvider({
     }),
     [
       leftWidth,
-      setLeftWidth,
       rightWidth,
-      setRightWidth,
+      adjustPanelWidth,
       leftCollapsed,
       setLeftCollapsed,
       rightCollapsed,

package/src/hooks/useBlockCatalog.ts

@@ -6,33 +6,51 @@ import {
   resolveBlockCategory,
 } from "../utils/blockCategories";
 
-export type CatalogItem = RegistryItem & {
+type CatalogItem = RegistryItem & {
   category: BlockCategory;
 };
 
+let catalogCache: CatalogItem[] | null = null;
+let catalogRequest: Promise<CatalogItem[]> | null = null;
+
+function loadCatalog(): Promise<CatalogItem[]> {
+  catalogRequest ??= fetch("/api/registry/blocks")
+    .then((response) => {
+      if (!response.ok) throw new Error("Failed to load catalog");
+      return response.json() as Promise<RegistryItem[]>;
+    })
+    .then((items) => {
+      catalogCache = items
+        .map((item) => ({ ...item, category: resolveBlockCategory(item.tags) }))
+        .sort((a, b) => {
+          const aIndex = BLOCK_CATEGORIES.findIndex((category) => category.id === a.category);
+          const bIndex = BLOCK_CATEGORIES.findIndex((category) => category.id === b.category);
+          return (aIndex === -1 ? 99 : aIndex) - (bIndex === -1 ? 99 : bIndex);
+        });
+      return catalogCache;
+    })
+    .catch((error: unknown) => {
+      catalogRequest = null;
+      throw error;
+    });
+  return catalogRequest;
+}
+
 export function useBlockCatalog() {
-  const [blocks, setBlocks] = useState<CatalogItem[]>([]);
-  const [loading, setLoading] = useState(true);
+  const [blocks, setBlocks] = useState<CatalogItem[]>(() => catalogCache ?? []);
+  const [loading, setLoading] = useState(catalogCache === null);
   const [error, setError] = useState<string | null>(null);
   const [search, setSearch] = useState("");
   const [category, setCategory] = useState<BlockCategory | null>(null);
 
   // fallow-ignore-next-line complexity
   useEffect(() => {
+    if (catalogCache) return;
     let cancelled = false;
     (async () => {
       try {
-        const res = await fetch("/api/registry/blocks");
-        if (!res.ok) throw new Error("Failed to load catalog");
-        const data = (await res.json()) as RegistryItem[];
+        const items = await loadCatalog();
         if (cancelled) return;
-        const items = data
-          .map((b) => ({ ...b, category: resolveBlockCategory(b.tags) }))
-          .sort((a, b) => {
-            const ia = BLOCK_CATEGORIES.findIndex((c) => c.id === a.category);
-            const ib = BLOCK_CATEGORIES.findIndex((c) => c.id === b.category);
-            return (ia === -1 ? 99 : ia) - (ib === -1 ? 99 : ib);
-          });
         setBlocks(items);
       } catch (err) {
         if (cancelled) return;

package/src/hooks/useBlockHandlers.ts

@@ -9,6 +9,7 @@ import { addBlockToProject } from "../utils/blockInstaller";
 import type { BlockParam } from "@hyperframes/core/registry";
 import type { EditHistoryKind } from "../utils/editHistory";
 import type { RightPanelTab } from "../utils/studioHelpers";
+import type { MediaOverlayPlacement } from "../components/editor/propertyPanelTypes";
 
 interface BlockCtxDeps {
   activeCompPath: string | null;
@@ -46,6 +47,7 @@ export interface UseBlockHandlersResult {
   >;
   handleAddBlock: (blockName: string) => void;
   handleTimelineBlockDrop: (blockName: string, placement: { start: number; track: number }) => void;
+  handleAddMediaOverlay: (blockName: string, placement: MediaOverlayPlacement) => Promise<void>;
   handlePreviewBlockDrop: (blockName: string, position: { left: number; top: number }) => void;
 }
 
@@ -151,6 +153,25 @@ export function useBlockHandlers({
     [projectId, blockCtx, previewIframeRef, runBlockInstall],
   );
 
+  const handleAddMediaOverlay = useCallback(
+    async (blockName: string, placement: MediaOverlayPlacement) => {
+      if (!projectId) return;
+      const { compositionPath, ...timelinePlacement } = placement;
+      await runBlockInstall(blockName, () =>
+        addBlockToProject({
+          projectId,
+          blockName,
+          ...blockCtx,
+          activeCompPath: compositionPath ?? blockCtx.activeCompPath,
+          placement: timelinePlacement,
+          previewIframe: previewIframeRef.current,
+          currentTime: usePlayerStore.getState().currentTime,
+        }),
+      );
+    },
+    [projectId, blockCtx, previewIframeRef, runBlockInstall],
+  );
+
   const handlePreviewBlockDrop = useCallback(
     (blockName: string, position: { left: number; top: number }) => {
       if (!projectId) return;
@@ -173,6 +194,7 @@ export function useBlockHandlers({
     setActiveBlockParams,
     handleAddBlock,
     handleTimelineBlockDrop,
+    handleAddMediaOverlay,
     handlePreviewBlockDrop,
   };
 }

package/src/hooks/useGsapScriptCommits.test.tsx

@@ -283,6 +283,21 @@ function mockFetchResult(over: Partial<MutationResult> = {}): void {
 }
 
 describe("runCommit — instantPatch wiring", () => {
+  it("explains a deliberate mutation that the server safely rejected as unchanged", async () => {
+    mockFetchResult({ changed: false });
+    const deps = renderCommitHook();
+
+    await act(async () => {
+      await deps.api.commitMutation(
+        selection,
+        { type: "move-keyframe", fromPercentage: 50, toPercentage: 100 },
+        { label: "Move keyframe" },
+      );
+    });
+
+    expect(deps.showToast).toHaveBeenCalledWith("A keyframe already exists at that time", "info");
+  });
+
   it("no-op commit with an instantPatch still patches the runtime (paired x/y commits)", async () => {
     patchRuntimeTweenInPlace.mockReturnValue(true);
     mockFetchResult({ changed: false });

package/src/hooks/useGsapScriptCommits.ts

@@ -77,6 +77,17 @@ async function mutateGsapScriptBatch(
 
 type ShowToast = (message: string, tone?: "error" | "info") => void;
 
+function showUnchangedMutationFeedback(
+  mutations: Record<string, unknown>[],
+  result: MutationResult,
+  showToast: ShowToast | undefined,
+): void {
+  if (result.changed !== false || mutations.length !== 1) return;
+  if (mutations[0]?.type === "move-keyframe") {
+    showToast?.("A keyframe already exists at that time", "info");
+  }
+}
+
 async function runMutationRequest(
   mutations: Record<string, unknown>[],
   options: CommitMutationOptions,
@@ -94,7 +105,9 @@ async function runMutationRequest(
     );
   }
   try {
-    return await request();
+    const result = await request();
+    showUnchangedMutationFeedback(mutations, result, showToast);
+    return result;
   } catch (error) {
     if (error instanceof GsapMutationHttpError) {
       showToast?.(formatGsapMutationRejectionToast(error), "error");

package/src/hooks/usePanelLayout.test.ts

@@ -2,11 +2,30 @@
 
 import React, { act } from "react";
 import { createRoot } from "react-dom/client";
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { readStudioUiPreferences } from "../utils/studioUiPreferences";
 import { usePanelLayout } from "./usePanelLayout";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
 
+beforeEach(() => {
+  const entries = new Map<string, string>();
+  Object.defineProperty(window, "localStorage", {
+    configurable: true,
+    value: {
+      get length() {
+        return entries.size;
+      },
+      clear: () => entries.clear(),
+      getItem: (key: string) => entries.get(key) ?? null,
+      key: (index: number) => Array.from(entries.keys())[index] ?? null,
+      removeItem: (key: string) => entries.delete(key),
+      setItem: (key: string, value: string) => entries.set(key, value),
+    } satisfies Storage,
+  });
+  Object.defineProperty(window, "innerWidth", { configurable: true, value: 1496 });
+});
+
 afterEach(() => {
   document.body.innerHTML = "";
   vi.doUnmock("../components/editor/manualEditingAvailability");
@@ -42,6 +61,54 @@ function renderPanelLayout() {
 }
 
 describe("usePanelLayout — right inspector panes", () => {
+  it("opens Design with the intended viewport-scaled panel widths", () => {
+    const harness = renderPanelLayout();
+
+    expect(harness.getState()).toMatchObject({
+      leftWidth: 384,
+      rightWidth: 424,
+      rightCollapsed: false,
+      rightPanelTab: "design",
+    });
+
+    harness.unmount();
+  });
+
+  it("persists the latest pointer width even before React rerenders", () => {
+    const harness = renderPanelLayout();
+    const state = harness.getState();
+    const target = { setPointerCapture: vi.fn() };
+
+    act(() => {
+      state.handlePanelResizeStart("left", {
+        preventDefault: vi.fn(),
+        target,
+        pointerId: 1,
+        clientX: 100,
+      } as unknown as React.PointerEvent);
+      state.handlePanelResizeMove({ clientX: 140 } as React.PointerEvent);
+      state.handlePanelResizeEnd();
+    });
+
+    expect(harness.getState().leftWidth).toBe(424);
+    expect(readStudioUiPreferences().leftWidth).toBe(424);
+    harness.unmount();
+  });
+
+  it("accumulates and persists rapid keyboard resize steps", () => {
+    const harness = renderPanelLayout();
+    const state = harness.getState();
+
+    act(() => {
+      state.adjustPanelWidth("right", 16);
+      state.adjustPanelWidth("right", 16);
+    });
+
+    expect(harness.getState().rightWidth).toBe(456);
+    expect(readStudioUiPreferences().rightWidth).toBe(456);
+    harness.unmount();
+  });
+
   it("toggleRightInspectorPane independently flips one pane, allowing both open at once", () => {
     const harness = renderPanelLayout();
     expect(harness.getState().rightInspectorPanes).toEqual({ layers: false, design: true });