@hyperframes/studio 0.8.115 → 0.8.117

package/src/hooks/usePersistentEditHistory.ts

@@ -2,17 +2,13 @@ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import type { HistoryListItem, HistoryResult } from "@hyperframes/studio-server";
 import { studioFileContentVersion, studioWriteHeaders } from "../utils/studioFileVersion";
 import type { RestoreFiles } from "../utils/gsapUndoRestore";
-
-interface RecordEditInput {
-  label: string;
-  coalesceKey?: string;
-  coalesceMs?: number;
-  files: Record<string, { before: string; after: string }>;
-}
+import { studioApiFetch } from "../utils/studioApiFetch";
+import type { RecordEditInput } from "../utils/studioFileHistory";
 
 interface ApplyCallbacks {
   readFile: (path: string) => Promise<string>;
   serialize?: <T>(paths: readonly string[], task: () => Promise<T>) => Promise<T>;
+  claimedAfter?: number;
 }
 
 export interface UsePersistentEditHistoryOptions {
@@ -53,6 +49,8 @@ function createOwnHistory() {
   const own = new Map<string, OwnFiles>();
   let next: Record<"undo" | "redo", NextStep | null> | null = null;
   let changes = 0;
+  let claimed = { count: 0, id: "" };
+  const undoneIds = new Set<string>();
   const remember = (id: string, files: OwnFiles) => {
     const known = own.get(id) ?? {};
     for (const [path, { before, after }] of Object.entries(files)) {
@@ -73,7 +71,16 @@ function createOwnHistory() {
       if (seen === changes) next = { undo: view.back, redo: view.forward };
     },
     changes: () => changes,
+    claimCount: () => claimed.count,
+    claimedAfter: (count: number) => (claimed.count > count && claimed.id ? claimed.id : null),
+    targetFor: (id: string | null, pressedAt: number) =>
+      !id || !undoneIds.has(id) ? id : claimed.count > pressedAt ? false : null,
+    noteClaim: (id: string) => {
+      claimed = { count: claimed.count + 1, id };
+    },
     stepped: (entry: { id: string; undoes?: string }) => {
+      if (entry.undoes) undoneIds.add(entry.undoes);
+      if (undoneIds.size > OWN_ENTRIES_KEPT) undoneIds.delete(undoneIds.values().next().value!);
       const undone = entry.undoes ? own.get(entry.undoes) : undefined;
       if (!undone) return;
       const swapped = Object.entries(undone).map(([path, f]) => [
@@ -102,6 +109,7 @@ function createOwnHistory() {
     },
     clear: () => {
       own.clear();
+      undoneIds.clear();
       next = null;
       changes += 1;
     },
@@ -113,12 +121,20 @@ function historyUrl(projectId: string, path = ""): string {
   return `/api/projects/${encodeURIComponent(projectId)}/history${path}`;
 }
 
+async function cantUndo(paths: string[] | undefined): Promise<ApplyResult> {
+  return { ok: false, reason: "content-mismatch", paths: paths ?? [] };
+}
+
+function unionPaths(...lists: Array<readonly string[] | undefined>): string[] {
+  return [...new Set(lists.flatMap((list) => list ?? []))];
+}
+
 async function post(
   url: string,
   body: object,
   headers: Record<string, string> = {},
 ): Promise<{ ok: true; body: unknown } | { ok: false; status: number; error: string }> {
-  const response = await fetch(url, {
+  const response = await studioApiFetch(url, {
     method: "POST",
     headers: { "Content-Type": "application/json", ...headers },
     body: JSON.stringify(body),
@@ -194,9 +210,12 @@ export function usePersistentEditHistory({ projectId }: UsePersistentEditHistory
   const refresh = useCallback(async () => {
     if (!projectId) return;
     const seen = own.changes();
-    const response = await fetch(historyUrl(projectId)).catch(() => null);
-    const next = response?.ok ? ((await response.json()) as HistoryView) : EMPTY;
+    const response = await studioApiFetch(historyUrl(projectId)).catch(() => null);
+    const next = response?.ok
+      ? ((await response.json().catch(() => null)) as HistoryView | null)
+      : EMPTY;
     if (projectIdRef.current !== projectId) return;
+    if (!next) return console.error("The history's reply was unreadable.");
     setView(next);
     own.offered(seen, next);
   }, [projectId, own]);
@@ -210,9 +229,9 @@ export function usePersistentEditHistory({ projectId }: UsePersistentEditHistory
   }, [refresh, own]);
 
   const recordEdit = useCallback(
-    async ({ label, coalesceKey, coalesceMs, files }: RecordEditInput) => {
+    async ({ label, coalesceKey, coalesceMs, files, created = [] }: RecordEditInput) => {
       if (!projectId) return;
-      const paths = Object.keys(files);
+      const paths = [...Object.keys(files), ...created];
       own.overtake();
       const reply = await post(historyUrl(projectId, "/claim"), {
         label,
@@ -221,7 +240,10 @@ export function usePersistentEditHistory({ projectId }: UsePersistentEditHistory
         ...(coalesceKey && { coalesceKey, idleMs: coalesceMs ?? DEFAULT_COALESCE_MS }),
       });
       const claimed = claimHeld(reply, label);
-      if (claimed) own.remember(claimed, files);
+      if (claimed) {
+        own.remember(claimed, files);
+        own.noteClaim(claimed);
+      }
       heldClaimRef.current = claimed && coalesceKey ? { paths, at: Date.now() } : null;
       await refresh();
     },
@@ -231,14 +253,20 @@ export function usePersistentEditHistory({ projectId }: UsePersistentEditHistory
   const step = useCallback(
     async (direction: "undo" | "redo", callbacks: ApplyCallbacks): Promise<ApplyResult> => {
       if (!projectId) return { ok: false, reason: "empty" };
+      const candidate =
+        direction === "undo" && callbacks.claimedAfter !== undefined
+          ? own.claimedAfter(callbacks.claimedAfter)
+          : null;
       const next = direction === "undo" ? view.back : view.forward;
-      const paths = [...new Set([...(next?.paths ?? []), ...(heldClaimRef.current?.paths ?? [])])];
+      const stepPaths = candidate ? Object.keys(own.afterOf(candidate)) : next?.paths;
+      const paths = unionPaths(stepPaths, heldClaimRef.current?.paths);
+      const pressedAt = own.claimCount();
       own.overtake();
-      const run = async (): Promise<ApplyResult> => {
+      const attempt = async (target: string | null): Promise<ApplyResult> => {
         const previous = await readAll(paths, callbacks.readFile);
         const posted = await post(
-          historyUrl(projectId, "/step"),
-          { direction: direction === "undo" ? "back" : "forward" },
+          historyUrl(projectId, target ? "/undo" : "/step"),
+          target ? { entryId: target } : { direction: direction === "undo" ? "back" : "forward" },
           studioWriteHeaders(),
         );
         heldClaimRef.current = null;
@@ -266,6 +294,10 @@ export function usePersistentEditHistory({ projectId }: UsePersistentEditHistory
           ),
         };
       };
+      const run = () => {
+        const target = own.targetFor(candidate, pressedAt);
+        return target === false ? cantUndo(stepPaths) : attempt(target);
+      };
       return callbacks.serialize ? callbacks.serialize(paths, run) : run();
     },
     [projectId, view, refresh, own],
@@ -301,6 +333,7 @@ export function usePersistentEditHistory({ projectId }: UsePersistentEditHistory
     undo,
     redo,
     predict: own.predict,
+    claims: own.claimCount,
     noteOutsideChange,
   };
 }

package/src/hooks/usePreviewPersistence.history.test.tsx

@@ -79,12 +79,13 @@ describe("undo that re-runs the top-level script over an element of a nested com
     };
   }
 
-  async function undo(fileOk: boolean) {
+  async function undo(fileOk: boolean, projectId: string | null = "p1") {
     const { iframe, nwid } = nestedPreview();
     const reloadPreview = vi.fn();
     const fetch = vi.fn(async () => ({ ok: fileOk, json: async () => ({ content: SUB }) }));
     vi.stubGlobal("fetch", fetch);
-    usePlayerStore.getState().beginTimelineSession("p1");
+    if (projectId) usePlayerStore.getState().beginTimelineSession(projectId);
+    else usePlayerStore.setState({ timelineProjectId: null });
     let sync: ReturnType<typeof usePreviewPersistence>["syncHistoryPreviewAfterApply"] | null =
       null;
     function Harness() {
@@ -109,7 +110,9 @@ describe("undo that re-runs the top-level script over an element of a nested com
   it("restores the element from its own composition file", async () => {
     const { nwid, reloadPreview, fetch } = await undo(true);
 
-    expect(fetch).toHaveBeenCalledWith(expect.stringContaining("/files/compositions%2Fsub.html"));
+    expect(fetch).toHaveBeenCalledWith(expect.stringContaining("/files/compositions%2Fsub.html"), {
+      credentials: "omit",
+    });
     expect(reloadPreview).not.toHaveBeenCalled();
     expect(nwid.getAttribute("style")).toBe("left: 40px;");
   });
@@ -120,4 +123,12 @@ describe("undo that re-runs the top-level script over an element of a nested com
     expect(reloadPreview).toHaveBeenCalledTimes(1);
     expect(nwid.getAttribute("style")).toBe("left: 40px; width: 337px");
   });
+
+  it("reloads the preview in full when no project is open to read that file from", async () => {
+    const { nwid, reloadPreview, fetch } = await undo(true, null);
+
+    expect(fetch).not.toHaveBeenCalled();
+    expect(reloadPreview).toHaveBeenCalledTimes(1);
+    expect(nwid.getAttribute("style")).toBe("left: 40px; width: 337px");
+  });
 });

package/src/hooks/usePreviewPersistence.ts

@@ -163,8 +163,9 @@ export function usePreviewPersistence({
   }, [drainPendingDomEditSaves]);
 
   const settlePendingEdits = useCallback(async (): Promise<void> => {
-    await flushStudioPendingEdits();
-    await domEditSaveQueueRef.current?.waitForIdle();
+    const queued = domEditSaveQueueRef.current?.waitForIdle();
+    await flushStudioPendingEdits({ onlyCurrent: true });
+    await queued;
   }, []);
 
   const resetDomEditSaveQueueBreaker = useCallback(() => {
@@ -209,14 +210,15 @@ export function usePreviewPersistence({
       // multi-file, sub-comp, or a permanent soft-reload failure.
       const projectId = usePlayerStore.getState().timelineProjectId;
       const nestedFiles = await settleNestedReads(
-        projectId
-          ? readUndoNestedFiles(
-              previewIframeRef.current,
-              activeCompPathRef.current,
-              restore.files,
-              (path) => readProjectFileContent(projectId, path),
-            )
-          : null,
+        readUndoNestedFiles(
+          previewIframeRef.current,
+          activeCompPathRef.current,
+          restore.files,
+          (path) =>
+            projectId
+              ? readProjectFileContent(projectId, path)
+              : Promise.reject(new Error("No project is open to read nested files from.")),
+        ),
       );
       const strategy = applyUndoRestoreToPreview(
         previewIframeRef.current,
@@ -258,7 +260,7 @@ export function usePreviewPersistence({
 
   // ── Migrate legacy studio-motion.json ──
   // Projects that used the old JSON-file approach may still have a populated
-  // `.hyperframes/studio-motion.json`. The studio no longer reads from it, but
+  // studio-motion.json in the project's .hyperframes folder. The studio no longer reads it, but
   // the legacy render-script injection in `preview.ts` / `vite.studioMotion.ts`
   // could still fire alongside the new seek-reapply runtime. Empty the file so
   // the legacy codepath no-ops.

package/src/hooks/useProjectFileWriter.ts

@@ -6,11 +6,22 @@ import {
   StudioSaveNetworkError,
 } from "../utils/studioSaveDiagnostics";
 import { studioExpectedFileVersion, studioWriteHeaders } from "../utils/studioFileVersion";
+import { studioApiFetch } from "../utils/studioApiFetch";
 
 export interface UseProjectFileWriterOptions {
   projectId: string | null;
 }
 
+async function fetchProjectFile(projectId: string | null, path: string, query: string) {
+  if (!projectId) throw new Error("No active project");
+  const response = await studioApiFetch(
+    `/api/projects/${encodeURIComponent(projectId)}/files/${encodeURIComponent(path)}${query}`,
+  );
+  if (!response.ok) throw new Error(`Failed to read ${path}`);
+  const data = (await response.json()) as { content?: string; version?: string };
+  return { content: data.content, version: data.version ?? response.headers.get("etag") };
+}
+
 // The etag-guarded project-file read/write pair every Studio save path
 // shares. A host mounting hand editing outside Studio needs only this, not
 // the full file manager (file tree, editor tabs, uploads, font assets).
@@ -30,29 +41,19 @@ export function useProjectFileWriter({ projectId }: UseProjectFileWriterOptions)
 
   const readProjectFile = useCallback(
     async (path: string): Promise<string> => {
-      if (!projectId) throw new Error("No active project");
-      const response = await fetch(
-        `/api/projects/${encodeURIComponent(projectId)}/files/${encodeURIComponent(path)}`,
-      );
-      if (!response.ok) throw new Error(`Failed to read ${path}`);
-      const data = (await response.json()) as { content?: string; version?: string };
-      if (typeof data.content !== "string") throw new Error(`Missing file contents for ${path}`);
-      fileVersions.set(path, data.version ?? response.headers.get("etag"));
-      return data.content;
+      const { content, version } = await fetchProjectFile(projectId, path, "");
+      if (typeof content !== "string") throw new Error(`Missing file contents for ${path}`);
+      fileVersions.set(path, version);
+      return content;
     },
     [fileVersions, projectId],
   );
 
   const readOptionalProjectFile = useCallback(
     async (path: string): Promise<string> => {
-      if (!projectId) throw new Error("No active project");
-      const response = await fetch(
-        `/api/projects/${encodeURIComponent(projectId)}/files/${encodeURIComponent(path)}?optional=1`,
-      );
-      if (!response.ok) throw new Error(`Failed to read ${path}`);
-      const data = (await response.json()) as { content?: string; version?: string };
-      fileVersions.set(path, data.version ?? response.headers.get("etag"));
-      return typeof data.content === "string" ? data.content : "";
+      const { content, version } = await fetchProjectFile(projectId, path, "?optional=1");
+      fileVersions.set(path, version);
+      return typeof content === "string" ? content : "";
     },
     [fileVersions, projectId],
   );
@@ -63,7 +64,7 @@ export function useProjectFileWriter({ projectId }: UseProjectFileWriterOptions)
       const writeProjectId = projectId;
       let expectedVersion = await studioExpectedFileVersion(fileVersions, path, expectedContent);
       if (expectedVersion === undefined) {
-        const preflight = await fetch(
+        const preflight = await studioApiFetch(
           `/api/projects/${encodeURIComponent(writeProjectId)}/files/${encodeURIComponent(path)}`,
         );
         if (preflight.ok) {
@@ -86,7 +87,7 @@ export function useProjectFileWriter({ projectId }: UseProjectFileWriterOptions)
         // the retry can produce a second filesystem receipt that must be suppressed independently.
         let response: Response;
         try {
-          response = await fetch(
+          response = await studioApiFetch(
             `/api/projects/${encodeURIComponent(writeProjectId)}/files/${encodeURIComponent(path)}`,
             {
               method: "PUT",

package/src/hooks/useRemoveBackground.ts

@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useRef } from "react";
 import { waitForMediaJob } from "../components/studioMediaJobs";
 import type { BackgroundRemovalProgress } from "../components/editor/propertyPanelTypes";
+import { studioApiFetch } from "../utils/studioApiFetch";
 
 interface RemoveBackgroundOptions {
   createBackgroundPlate?: boolean;
@@ -31,7 +32,7 @@ export function useRemoveBackground(
   return useCallback(
     // fallow-ignore-next-line complexity
     async (inputPath: string, options: RemoveBackgroundOptions) => {
-      const response = await fetch(
+      const response = await studioApiFetch(
         `/api/projects/${encodeURIComponent(projectId)}/media/remove-background`,
         {
           method: "POST",

package/src/hooks/useSdkSession.ts

@@ -6,6 +6,7 @@ import { trackStudioEvent } from "../utils/studioTelemetry";
 import type { PublishSdkSession } from "../utils/sdkCutover";
 import { addExternalFileReloadListener } from "./externalFileReloadBus";
 import { whenPreviewBooted } from "../player/store/playerStore";
+import { studioApiFetch } from "../utils/studioApiFetch";
 
 /**
  * Why an optional project-file read produced no usable content. `stage: "read"`
@@ -194,7 +195,7 @@ async function readProjectFileOptional(
   let res: Response;
   const fetchStarted = performance.now();
   try {
-    res = await fetch(
+    res = await studioApiFetch(
       `/api/projects/${encodeURIComponent(projectId)}/files/${encodeURIComponent(path)}?optional=1`,
     );
   } catch {

package/src/hooks/useServerConnection.ts

@@ -2,6 +2,7 @@ import { useEffect, useState } from "react";
 import { buildProjectHash, parseProjectIdFromHash } from "../utils/projectRouting";
 import { useMountEffect } from "./useMountEffect";
 import { trackStudioEvent } from "../utils/studioTelemetry";
+import { studioApiFetch } from "../utils/studioApiFetch";
 
 interface ServerConnectionState {
   projectId: string | null;
@@ -37,7 +38,7 @@ type ProjectHashVerdict = {
 
 async function resolveHashProject(id: string): Promise<ProjectHashVerdict> {
   try {
-    const res = await fetch(`/api/projects/${encodeURIComponent(id)}`);
+    const res = await studioApiFetch(`/api/projects/${encodeURIComponent(id)}`);
     if (res.ok) return { outcome: "ok", status: res.status };
     return { outcome: res.status === 404 ? "missing" : "unknown", status: res.status };
   } catch {
@@ -72,7 +73,7 @@ function replaceProjectHash(projectId: string): void {
  */
 async function firstProjectId(): Promise<string | null> {
   try {
-    const res = await fetch("/api/projects");
+    const res = await studioApiFetch("/api/projects");
     const data = (await res.json()) as { projects?: Array<{ id?: string }> };
     return data.projects?.[0]?.id ?? null;
   } catch {
@@ -107,7 +108,7 @@ export function useServerConnection(): ServerConnectionState {
     }
 
     function tryConnect() {
-      fetch("/api/projects")
+      studioApiFetch("/api/projects")
         .then((r) => r.json())
         .then(async (data) => {
           if (cancelled) return;

package/src/hooks/useStudioSelectionPublisher.ts

@@ -3,6 +3,7 @@ import type { DomEditSelection } from "../components/editor/domEditing";
 import { usePlayerStore } from "../player";
 import { buildStudioSelectionSnapshot } from "../utils/studioSelectionSnapshot";
 import { trackStudioEvent } from "../utils/studioTelemetry";
+import { studioApiFetch } from "../utils/studioApiFetch";
 
 interface UseStudioSelectionPublisherParams {
   projectId: string | null;
@@ -26,7 +27,7 @@ function reportSelectionPublishError(error: unknown): void {
 }
 
 function putSelection(projectId: string, selection: unknown, signal?: AbortSignal): Promise<void> {
-  return fetch(`/api/projects/${encodeURIComponent(projectId)}/selection`, {
+  return studioApiFetch(`/api/projects/${encodeURIComponent(projectId)}/selection`, {
     method: "PUT",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify({ selection }),

package/src/hooks/useThumbnailStill.test.ts

@@ -0,0 +1,100 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { thumbnailScheduler } from "../player/lib/thumbnailScheduler";
+// By package name, as a host imports it: the test fails if the export goes.
+import { useThumbnailStill, type ThumbnailStill } from "@hyperframes/studio";
+
+Object.defineProperty(globalThis, "IS_REACT_ACT_ENVIRONMENT", { configurable: true, value: true });
+
+class MockImage {
+  onload: (() => void) | null = null;
+  onerror: (() => void) | null = null;
+  naturalWidth = 320;
+  naturalHeight = 180;
+  set src(_value: string) {
+    queueMicrotask(() => this.onload?.());
+  }
+}
+
+const URL_ONE = "http://localhost:3000/api/projects/demo/thumbnail/index.html?t=1.00&revision=1";
+const originalImage = globalThis.Image;
+const originalFetch = globalThis.fetch;
+const originalCreate = URL.createObjectURL;
+const originalRevoke = URL.revokeObjectURL;
+let host: HTMLDivElement;
+let root: Root | null = null;
+let shown: ThumbnailStill | null = null;
+
+function Still({ url }: { url: string | null }) {
+  shown = useThumbnailStill(url, "demo");
+  return null;
+}
+
+const mount = (url: string | null) =>
+  act(async () => {
+    root ??= createRoot(host);
+    root.render(React.createElement(Still, { url }));
+  });
+
+beforeEach(() => {
+  globalThis.Image = MockImage as unknown as typeof Image;
+  globalThis.fetch = vi.fn(async () => new Response(new Blob(["still"]), { status: 200 }));
+  URL.createObjectURL = vi.fn(() => "blob:still");
+  URL.revokeObjectURL = vi.fn();
+  shown = null;
+  host = document.createElement("div");
+  document.body.append(host);
+});
+
+afterEach(() => {
+  act(() => root?.unmount());
+  root = null;
+  thumbnailScheduler.setPreviewReloading(false);
+  thumbnailScheduler.invalidateProject("demo");
+  globalThis.Image = originalImage;
+  globalThis.fetch = originalFetch;
+  URL.createObjectURL = originalCreate;
+  URL.revokeObjectURL = originalRevoke;
+  document.body.replaceChildren();
+});
+
+describe("useThumbnailStill", () => {
+  it("hands back the still's object URL once the scheduler has loaded it", async () => {
+    await mount(URL_ONE);
+    expect(globalThis.fetch).toHaveBeenCalledWith(URL_ONE, expect.anything());
+    await vi.waitFor(() => expect(shown).toEqual({ status: "ready", url: "blob:still" }));
+  });
+
+  it("hands back the same object while nothing changes", async () => {
+    await mount(URL_ONE);
+    await vi.waitFor(() => expect(shown).toEqual({ status: "ready", url: "blob:still" }));
+    const first = shown;
+    await mount(URL_ONE);
+    expect(shown).toBe(first);
+  });
+
+  it("asks for nothing without a url", async () => {
+    await mount(null);
+    expect(globalThis.fetch).not.toHaveBeenCalled();
+    expect(shown).toEqual({ status: "loading" });
+  });
+
+  it("says failed when the still cannot load, so a host can fall back", async () => {
+    globalThis.fetch = vi.fn(async () => new Response("", { status: 500 }));
+    await mount(URL_ONE);
+    await vi.waitFor(() => expect(shown).toEqual({ status: "failed" }));
+  });
+
+  it("holds the fetch while a preview reloads, and runs it once the reload is over", async () => {
+    thumbnailScheduler.setPreviewReloading(true);
+    await mount(URL_ONE);
+    expect(globalThis.fetch).not.toHaveBeenCalled();
+    expect(shown).toEqual({ status: "loading" });
+    await act(async () => thumbnailScheduler.setPreviewReloading(false));
+    expect(globalThis.fetch).toHaveBeenCalledTimes(1);
+    await vi.waitFor(() => expect(shown).toEqual({ status: "ready", url: "blob:still" }));
+  });
+});

package/src/hooks/useThumbnailStill.ts

@@ -0,0 +1,37 @@
+import { useMemo } from "react";
+import { compositionThumbnailRequest } from "../player/components/CompositionThumbnail";
+import type { ThumbnailPriority } from "../player/lib/thumbnailScheduler";
+import { useThumbnailLease } from "./useThumbnailLease";
+
+export interface UseThumbnailStillOptions {
+  sessionEpoch?: number;
+  priority?: ThumbnailPriority;
+}
+
+export type ThumbnailStill =
+  | { status: "loading" }
+  | { status: "ready"; url: string }
+  | { status: "failed" };
+
+const LOADING: ThumbnailStill = Object.freeze({ status: "loading" });
+const FAILED: ThumbnailStill = Object.freeze({ status: "failed" });
+
+/** A host picture's server still through the thumbnail scheduler, so it yields to a preview reload. */
+export function useThumbnailStill(
+  url: string | null,
+  projectId: string,
+  { sessionEpoch = 0, priority = "visible" }: UseThumbnailStillOptions = {},
+): ThumbnailStill {
+  const request = useMemo(
+    () => (url ? compositionThumbnailRequest(url, projectId, { sessionEpoch, priority }) : null),
+    [priority, projectId, sessionEpoch, url],
+  );
+  const snapshot = useThumbnailLease(request);
+  const ready =
+    snapshot.status === "ready" && snapshot.value.kind === "image" ? snapshot.value.url : null;
+  return useMemo(
+    () =>
+      ready ? { status: "ready", url: ready } : snapshot.status === "error" ? FAILED : LOADING,
+    [ready, snapshot.status],
+  );
+}

package/src/hooks/useTimelineDeleteOps.ts

@@ -21,6 +21,7 @@ import type {
   TimelineGroupCommitOptions,
   TimelineGroupMoveChange,
 } from "./useTimelineGroupEditing";
+import { studioApiFetch } from "../utils/studioApiFetch";
 
 /** Apply already-resolved ripple changes to the surviving elements for the
  *  optimistic store update after a delete. Pure — no IO. */
@@ -130,7 +131,7 @@ export function useTimelineDeleteOps({
                 }
                 return patchTarget;
               });
-              const removeResponse = await fetch(
+              const removeResponse = await studioApiFetch(
                 buildProjectApiPath(
                   pid,
                   `/file-mutations/remove-elements/${encodeURIComponent(targetPath)}`,

package/src/index.ts

@@ -76,6 +76,8 @@ export type { AudioWaveformProps } from "./player/components/AudioWaveform";
 export { ImageThumbnail } from "./player/components/ImageThumbnail";
 export type { ImageThumbnailProps } from "./player/components/ImageThumbnail";
 export { useRenderClipContent } from "./hooks/useRenderClipContent";
+export { useThumbnailStill } from "./hooks/useThumbnailStill";
+export type { ThumbnailStill, UseThumbnailStillOptions } from "./hooks/useThumbnailStill";
 export type { UseRenderClipContentOptions } from "./hooks/useRenderClipContent";
 export type { ThumbnailPriority } from "./player/lib/thumbnailScheduler";
 export type {
@@ -208,6 +210,8 @@ export type { DomEditZOrder } from "./components/editor/useDomEditZOrder";
 export type { ZOrderAction } from "./components/editor/canvasContextMenuZOrder";
 export type { DomEditCapabilities, DomEditSelection } from "./components/editor/domEditingTypes";
 export { useDomStyleCommit } from "./hooks/useDomStyleCommit";
+export { ColorField } from "./components/editor/propertyPanelColor";
+export { GradientField } from "./components/editor/propertyPanelFill";
 export type { UseDomStyleCommitOptions } from "./hooks/useDomStyleCommit";
 export type { DomEditCommitDeclineReason, DomEditCommitOutcome } from "./hooks/domEditCommitRunner";
 export { resolveDomEditSelection } from "./components/editor/domEditingLayers";

package/src/player/components/AudioWaveform.tsx

@@ -5,6 +5,7 @@ import { useThumbnailLease } from "../../hooks/useThumbnailLease";
 import { createThumbnailKey, type ThumbnailPriority } from "../lib/thumbnailScheduler";
 import { decimatePeaks, loudnessToOpacity } from "./audioWaveformPeaks";
 import { ClipFadesContext, type ClipFadeShape } from "./TimelineClipFades";
+import { studioApiFetch } from "../../utils/studioApiFetch";
 
 export interface AudioWaveformProps {
   audioUrl: string;
@@ -124,7 +125,7 @@ async function loadWaveform(
 }
 
 async function fetchWaveformPeaks(url: string, signal: AbortSignal): Promise<number[]> {
-  const response = await fetch(url, { signal });
+  const response = await studioApiFetch(url, { signal });
   if (!response.ok) throw new Error(`Waveform request failed (${response.status})`);
   const data: unknown = await response.json();
   if (
@@ -140,7 +141,7 @@ async function fetchWaveformPeaks(url: string, signal: AbortSignal): Promise<num
 }
 
 async function decodeWaveformPeaks(url: string, signal: AbortSignal): Promise<number[]> {
-  const response = await fetch(url, { signal });
+  const response = await studioApiFetch(url, { signal });
   if (!response.ok) throw new Error(`Audio request failed (${response.status})`);
   const buffer = await response.arrayBuffer();
   if (signal.aborted) throw new DOMException("Aborted", "AbortError");

package/src/player/components/CompositionThumbnail.tsx

@@ -8,6 +8,7 @@ import {
 } from "../lib/thumbnailScheduler";
 import { TIMELINE_VIEWPORT_BUDGETS } from "../lib/timelineViewportBudgets";
 import { computeThumbnailStrip, probeImageAspect } from "./thumbnailUtils";
+import { studioApiFetch } from "../../utils/studioApiFetch";
 
 interface CompositionThumbnailProps {
   previewUrl: string;
@@ -106,7 +107,7 @@ export function compositionThumbnailRequest(
 }
 
 async function loadCompositionImage(url: string, signal: AbortSignal) {
-  const response = await fetch(url, { signal });
+  const response = await studioApiFetch(url, { signal });
   if (!response.ok) throw new Error(`Composition thumbnail failed (${response.status})`);
   const blob = await response.blob();
   if (signal.aborted) throw new DOMException("Aborted", "AbortError");

package/src/player/components/clipMenuNormalize.ts

@@ -4,6 +4,7 @@ import { resolveMediaPreviewUrl } from "./thumbnailUtils";
 import type { TimelineElement } from "../store/timelineElement";
 import { parseAutomation, VOLUME_TARGET } from "@hyperframes/core/audio-automation";
 import type { TimelineEditOutcome } from "../../hooks/timelineEditPermission";
+import { studioApiFetch } from "../../utils/studioApiFetch";
 
 export interface NormalizePlan {
   targetLufs: number;
@@ -74,7 +75,7 @@ function isNormalizePlan(value: unknown): value is NormalizePlan {
 export async function requestNormalizePlan(
   projectId: string,
   el: TimelineElement,
-  fetchImpl: typeof fetch = fetch,
+  fetchImpl: typeof studioApiFetch = studioApiFetch,
 ): Promise<NormalizePlan> {
   const origin = window.location.origin;
   const relative = resolvePreviewRelative(

package/src/player/components/clipPeakMap.ts

@@ -1,4 +1,5 @@
 import { buildProjectApiPath } from "../../utils/projectRouting";
+import { studioApiFetch } from "../../utils/studioApiFetch";
 import { resolvePreviewRelative } from "../../utils/previewRelativePath";
 import type { TimelineElement } from "../store/timelineElement";
 import { clipSourcePeak, isPeakMap, type ClipSourceWindow, type PeakMap } from "./clipPeakRuns";
@@ -10,7 +11,7 @@ const peakMapRequests = new Map<string, Promise<PeakMap | null>>();
 export function loadPeakMap(url: string): Promise<PeakMap | null> {
   const pending = peakMapRequests.get(url);
   if (pending) return pending;
-  const request = fetch(url)
+  const request = studioApiFetch(url)
     .then((res) => (res.ok ? res.json() : null))
     .then((body: unknown) => (isPeakMap(body) ? body : null))
     .catch(() => null);