@hyperframes/studio 0.8.80 → 0.8.82

package/src/hooks/timelineQuickSaves.test.ts

@@ -0,0 +1,195 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  buildTimelineMoveTimingPatch,
+  buildTimelineResizeTimingPatch,
+  persistElementAttribute,
+  persistTimelineBatchEdit,
+  persistTimelineEdit,
+} from "./timelineEditingHelpers";
+import type { TimelineElement } from "../player/store/playerStore";
+import { finishClipTimingFallback } from "./timelineTimingSync";
+import { applyColorGradingScopeUpdate } from "../components/studioColorGradingScope";
+
+const SOURCE =
+  '<div id="root"><video id="a" class="clip" data-start="1" data-duration="5" data-track-index="0"></video>' +
+  '<video id="b" class="clip" data-start="2" data-duration="5" data-track-index="1"></video>' +
+  '<script>gsap.to("#a", { x: 1 }, 1)</script></div>';
+
+// Refuses a write whose base is stale, like the server's If-Match; one write can be held mid-flight.
+// A GSAP shift lands 10 ms after it is posted and releases the held write.
+function fakeProject() {
+  let file = SOURCE;
+  const refused: string[] = [];
+  let writes = 0;
+  let release = () => {};
+  const firstWrite = new Promise<void>((resolve) => (release = resolve));
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (input: string) => {
+      if (input.includes("/gsap-mutation-capabilities")) {
+        return Response.json({ atomicOwnershipPairs: true });
+      }
+      if (input.includes("/gsap-mutations/")) {
+        await new Promise((resolve) => setTimeout(resolve, 10));
+        const before = file;
+        file = file.replace("{ x: 1 }, 1)", "{ x: 1 }, 3)");
+        release();
+        return Response.json({ mutated: true, before, after: file, scriptText: null });
+      }
+      return Response.json({ content: file });
+    }),
+  );
+  const writeProjectFile = async (path: string, content: string, expected?: string) => {
+    if (++writes === 1) await firstWrite;
+    if (expected !== undefined && expected !== file && content !== file) {
+      refused.push(path);
+      throw new Error(`409 conflict on ${path}`);
+    }
+    file = content;
+  };
+  return { writeProjectFile, refused, release: () => release(), read: () => file };
+}
+
+type Project = ReturnType<typeof fakeProject>;
+
+function clip(id: string): TimelineElement {
+  return { id, key: id, domId: id, tag: "video", label: id, start: 0, duration: 5, track: 0 };
+}
+
+const shared = (project: Project) => ({
+  projectId: "p1",
+  activeCompPath: "index.html",
+  writeProjectFile: project.writeProjectFile,
+  recordEdit: async () => {},
+  pendingTimelineEditPathRef: { current: new Set<string>() },
+});
+
+const move = (project: Project, id: string, start: number) =>
+  persistTimelineEdit({
+    ...shared(project),
+    element: clip(id),
+    label: "Move clip",
+    buildPatches: (original, target) => buildTimelineMoveTimingPatch(original, target, start, 5),
+  });
+
+const trim = (project: Project, id: string, duration: number) =>
+  persistTimelineBatchEdit({
+    ...shared(project),
+    label: "Trim clip",
+    changes: [
+      {
+        element: clip(id),
+        buildPatches: (original, target) =>
+          buildTimelineResizeTimingPatch(original, target, clip(id), { start: 0, duration }),
+      },
+    ],
+  });
+
+// Starts the second save while the first one's write is in flight; both must land unrefused.
+async function expectBothLand(
+  project: Project,
+  first: () => Promise<unknown>,
+  second: () => Promise<unknown>,
+) {
+  const saves = [first()];
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  saves.push(second());
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  project.release();
+  const results = await Promise.allSettled(saves);
+  expect(project.refused).toEqual([]);
+  expect(results.map((r) => r.status)).toEqual(["fulfilled", "fulfilled"]);
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe("two quick timeline saves on one file", () => {
+  it("lands both moves", async () => {
+    const project = fakeProject();
+    await expectBothLand(
+      project,
+      () => move(project, "a", 3),
+      () => move(project, "b", 4),
+    );
+
+    expect(project.read()).toContain('id="a" class="clip" data-start="3"');
+    expect(project.read()).toContain('id="b" class="clip" data-start="4"');
+  });
+
+  it("lands both trims", async () => {
+    const project = fakeProject();
+    await expectBothLand(
+      project,
+      () => trim(project, "a", 3),
+      () => trim(project, "b", 2),
+    );
+
+    expect(project.read()).toMatch(/id="a"[^>]*data-duration="3"/);
+    expect(project.read()).toMatch(/id="b"[^>]*data-duration="2"/);
+  });
+
+  it("lands a move started while a volume save is writing", async () => {
+    const project = fakeProject();
+    const volume = () =>
+      persistElementAttribute({
+        ...shared(project),
+        targetPath: "index.html",
+        patchTarget: { id: "a" },
+        attr: "data-volume",
+        value: "0.5",
+        label: "Set volume",
+        patchLive: () => {},
+        onFileRead: () => {},
+      });
+    await expectBothLand(project, volume, () => move(project, "b", 4));
+
+    expect(project.read()).toContain('data-volume="0.5"');
+    expect(project.read()).toContain('id="b" class="clip" data-start="4"');
+  });
+
+  it("keeps a move when a color grade starts while it is writing", async () => {
+    const project = fakeProject();
+    const grade = () =>
+      applyColorGradingScopeUpdate({
+        scope: "source-file",
+        value: "warm",
+        selectedSourceFile: "index.html",
+        fileTree: ["index.html"],
+        projectId: "p1",
+        waitForPendingDomEditSaves: async () => {},
+        readProjectFile: async () => project.read(),
+        writeProjectFile: project.writeProjectFile,
+        recordEdit: async () => {},
+        reloadPreview: () => {},
+        showToast: () => {},
+      });
+    await expectBothLand(project, () => move(project, "a", 3), grade);
+
+    expect(project.read()).toContain('id="a" class="clip" data-start="3"');
+    expect(project.read()).toContain('data-color-grading="warm"');
+  });
+
+  it("lands a move started while the previous move's GSAP rewrite is in flight", async () => {
+    const project = fakeProject();
+    const shiftA = finishClipTimingFallback({
+      iframe: null,
+      reloadPreview: () => {},
+      projectId: "p1",
+      targetPath: "index.html",
+      domId: "a",
+      label: "Move clip",
+      recordEdit: async () => {},
+      writeProjectFile: project.writeProjectFile,
+      edit: { kind: "shift", delta: 2 },
+    });
+    const results = await Promise.allSettled([shiftA, move(project, "b", 4)]);
+
+    expect(project.refused).toEqual([]);
+    expect(results.map((r) => r.status)).toEqual(["fulfilled", "fulfilled"]);
+    expect(project.read()).toContain('gsap.to("#a", { x: 1 }, 3)');
+    expect(project.read()).toContain('id="b" class="clip" data-start="4"');
+  });
+});

package/src/hooks/timelineTimingSync.test.ts

@@ -11,6 +11,8 @@ import {
   shiftGsapPositions,
 } from "./timelineTimingSync";
 
+const writeProjectFile = async () => {};
+
 afterEach(() => {
   usePlayerStore.getState().reset();
   vi.restoreAllMocks();
@@ -68,6 +70,7 @@ function clipFallbackInput(overrides: {
     domId: "clip",
     label: "Move timeline clip",
     recordEdit: overrides.recordEdit as never,
+    writeProjectFile,
     edit: { kind: "shift", delta: 1 } as const,
   };
 }
@@ -495,6 +498,7 @@ describe("nothing-to-rewrite timing edits rebind in place (no script re-executio
     const element = { sourceFile: "index.html" } as TimelineElement;
 
     await finishGroupTimingGsapFallback({
+      writeProjectFile,
       projectId: "p1",
       iframe,
       reloadPreview,
@@ -522,6 +526,7 @@ describe("nothing-to-rewrite timing edits rebind in place (no script re-executio
     const reloadPreview = vi.fn();
 
     await finishGroupTimingGsapFallback({
+      writeProjectFile,
       projectId: "p1",
       iframe,
       reloadPreview,
@@ -602,6 +607,7 @@ describe("foldGsapMutationIntoHistory — owned GSAP transaction", () => {
     let clipIndex = 0;
 
     await finishGroupTimingGsapFallback({
+      writeProjectFile,
       projectId: "p1",
       iframe: buildLivePreviewIframe().iframe,
       reloadPreview: vi.fn(),
@@ -632,6 +638,7 @@ describe("foldGsapMutationIntoHistory — owned GSAP transaction", () => {
     let clipIndex = 0;
 
     await finishGroupTimingGsapFallback({
+      writeProjectFile,
       projectId: "p1",
       iframe: buildLivePreviewIframe().iframe,
       reloadPreview: vi.fn(),
@@ -669,6 +676,7 @@ describe("foldGsapMutationIntoHistory — owned GSAP transaction", () => {
 
     const reloadPreview = vi.fn();
     await finishGroupTimingGsapFallback({
+      writeProjectFile,
       projectId: "p1",
       iframe: buildLivePreviewIframe().iframe,
       reloadPreview,
@@ -698,6 +706,7 @@ describe("foldGsapMutationIntoHistory — owned GSAP transaction", () => {
     let clipIndex = 0;
 
     await finishGroupTimingGsapFallback({
+      writeProjectFile,
       projectId: "p1",
       iframe: buildLivePreviewIframe().iframe,
       reloadPreview,
@@ -728,6 +737,7 @@ describe("foldGsapMutationIntoHistory — owned GSAP transaction", () => {
     const recordEdit = vi.fn(async () => {});
 
     await finishGroupTimingGsapFallback({
+      writeProjectFile,
       projectId: "p1",
       iframe: buildLivePreviewIframe().iframe,
       reloadPreview: vi.fn(),
@@ -762,6 +772,7 @@ describe("foldGsapMutationIntoHistory — owned GSAP transaction", () => {
 
     const reloadPreview = vi.fn();
     await finishGroupTimingGsapFallback({
+      writeProjectFile,
       projectId: "p1",
       iframe: buildLivePreviewIframe().iframe,
       reloadPreview,
@@ -797,6 +808,7 @@ describe("foldGsapMutationIntoHistory — owned GSAP transaction", () => {
     const server = installOwnedFileServer(contents, { failReadAt: 1 });
 
     await finishGroupTimingGsapFallback({
+      writeProjectFile,
       projectId: "p1",
       iframe: buildLivePreviewIframe().iframe,
       reloadPreview: vi.fn(),

package/src/hooks/timelineTimingSync.ts

@@ -7,10 +7,18 @@ import { applySoftReload, applySoftReloadFinalization } from "../utils/gsapSoftR
 import { furthestClipEndFromDocument } from "../player/lib/timelineElementHelpers";
 import type { RecordEditInput } from "../utils/studioFileHistory";
 import { patchDocumentRootDuration } from "./timelineEditingGsap";
-import { studioWriteHeaders } from "../utils/studioFileVersion";
-
-class GsapPreviewConvergenceError extends Error {}
-class GsapOwnershipProtocolError extends GsapPreviewConvergenceError {}
+import {
+  GsapOwnershipProtocolError,
+  GsapPreviewConvergenceError,
+  postGsapMutation,
+  requireGsapOwnershipProtocol,
+  rollbackOwnedMutation,
+  type GsapMutationStatus,
+} from "./gsapMutationClient";
+import {
+  serializeStudioFileMutations,
+  type StudioProjectFileWriter,
+} from "../utils/studioFileMutationCoordinator";
 
 export async function readFileContent(projectId: string, targetPath: string): Promise<string> {
   if (targetPath.includes("\0") || targetPath.includes("..")) {
@@ -29,51 +37,6 @@ export async function readFileContent(projectId: string, targetPath: string): Pr
   return data.content;
 }
 
-/** Verify rollback ownership support before any GSAP mutation can land. */
-async function requireGsapOwnershipProtocol(projectId: string): Promise<void> {
-  const response = await fetch(
-    `/api/projects/${encodeURIComponent(projectId)}/gsap-mutation-capabilities`,
-  );
-  if (!response.ok) {
-    throw new GsapOwnershipProtocolError("Server does not support owned GSAP mutations");
-  }
-  const body = await response.json().catch(() => null);
-  if (!isRecord(body) || body.atomicOwnershipPairs !== true) {
-    throw new GsapOwnershipProtocolError("Invalid GSAP mutation capability response");
-  }
-}
-
-/** Atomically restore one GSAP mutation only while its exact output still owns
- * the file. The server performs compare + write synchronously, eliminating the
- * client GET→PUT window that could overwrite a successor edit. */
-async function rollbackOwnedMutation(
-  projectId: string,
-  targetPath: string,
-  expected: string,
-  restore: string,
-): Promise<"restored" | "conflict"> {
-  if (targetPath.includes("\0") || targetPath.includes("..")) {
-    throw new Error(`Unsafe path: ${targetPath}`);
-  }
-  const response = await fetch(
-    `/api/projects/${encodeURIComponent(projectId)}/gsap-mutation-rollback/${encodeURIComponent(targetPath)}`,
-    {
-      method: "POST",
-      // Deliberately unclaimed: a rollback runs because a mutation did not
-      // converge, so let the restored file reload the preview.
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ expected, restore }),
-    },
-  );
-  if (!response.ok) {
-    throw new Error(`Failed to restore ${targetPath}`);
-  }
-  const result = (await response.json()) as { restored?: unknown; conflict?: unknown };
-  if (result.restored === true && result.conflict === false) return "restored";
-  if (result.restored === false && result.conflict === true) return "conflict";
-  throw new Error(`Invalid restore response for ${targetPath}`);
-}
-
 /** Best-effort live-iframe wrapper for patchDocumentRootDuration (see timelineEditingGsap). */
 function patchIframeRootDuration(iframe: HTMLIFrameElement | null, contentEnd: number): void {
   try {
@@ -102,79 +65,6 @@ export function captureDurationRollback(iframe: HTMLIFrameElement | null): () =>
   };
 }
 
-/**
- * The bits of the server GSAP-mutation response the timeline edit path needs.
- * `scriptText` is the rewritten root GSAP script — feeding it to `applySoftReload`
- * swaps the runtime timeline in place (no iframe reload = no all-clips flash). Null
- * when the endpoint didn't return one (older server, or a multi-script comp the
- * soft path can't scope) — the caller then full-reloads when `mutated`, or
- * rebinds the runtime timing in place when nothing was rewritten (see
- * syncTimingEditPreview).
- */
-export type GsapMutationStatus = {
-  mutated: boolean;
-  scriptText: string | null;
-  /** Atomic whole-file ownership pair returned by the mutation endpoint. */
-  before?: string;
-  after?: string;
-};
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null;
-}
-
-function readMutationStatus(value: unknown): GsapMutationStatus {
-  if (
-    !isRecord(value) ||
-    typeof value.mutated !== "boolean" ||
-    typeof value.before !== "string" ||
-    typeof value.after !== "string" ||
-    value.mutated !== (value.before !== value.after) ||
-    ("changed" in value && value.changed !== value.mutated)
-  ) {
-    throw new GsapOwnershipProtocolError("Invalid owned GSAP mutation response");
-  }
-  return {
-    mutated: value.mutated,
-    scriptText: typeof value.scriptText === "string" ? value.scriptText : null,
-    before: value.before,
-    after: value.after,
-  };
-}
-
-function readMutationError(value: unknown, fallback: string): string {
-  if (isRecord(value) && typeof value.error === "string") return value.error;
-  return fallback;
-}
-
-async function postGsapMutation(
-  projectId: string,
-  filePath: string,
-  mutation: Record<string, unknown>,
-  fallback: string,
-): Promise<GsapMutationStatus> {
-  let response: Response;
-  try {
-    response = await fetch(
-      `/api/projects/${encodeURIComponent(projectId)}/gsap-mutations/${encodeURIComponent(filePath)}`,
-      {
-        method: "POST",
-        headers: { "Content-Type": "application/json", ...studioWriteHeaders() },
-        body: JSON.stringify(mutation),
-      },
-    );
-  } catch (error) {
-    throw new GsapPreviewConvergenceError(`${fallback}: mutation outcome unknown`, {
-      cause: error,
-    });
-  }
-  const body: unknown = await response.json().catch(() => null);
-  if (!response.ok) {
-    throw new GsapPreviewConvergenceError(readMutationError(body, fallback));
-  }
-  return readMutationStatus(body);
-}
-
 /** Re-derive live timing windows without re-executing composition scripts.
  * Works for zero-GSAP compositions; false asks the caller to full-reload. */
 function rebindPreviewTiming(iframe: HTMLIFrameElement | null, currentTime: number): boolean {
@@ -341,7 +231,7 @@ async function rollbackAfterFailure(
 // The ledger, reverse rollback, final ownership check, and history fold are one
 // transaction; extracting phases would obscure which function owns convergence.
 // fallow-ignore-next-line complexity
-async function foldGsapMutationIntoHistory(input: {
+async function foldGsapMutationInQueue(input: {
   projectId: string;
   label: string;
   coalesceKey?: string;
@@ -411,6 +301,18 @@ async function foldGsapMutationIntoHistory(input: {
   return status;
 }
 
+// The mutations, the ownership read and any rollback hold every touched file's queue.
+function foldGsapMutationIntoHistory(
+  input: Parameters<typeof foldGsapMutationInQueue>[0] & {
+    writeFile: StudioProjectFileWriter;
+    paths: readonly string[];
+  },
+): Promise<GsapMutationStatus> {
+  return serializeStudioFileMutations(input.writeFile, input.paths, () =>
+    foldGsapMutationInQueue(input),
+  );
+}
+
 /**
  * Shift all GSAP animation positions targeting a given element by a time delta.
  * Calls the server-side GSAP mutation endpoint which uses the AST-based parser.
@@ -491,6 +393,7 @@ export function finishClipTimingFallback(input: {
   label: string;
   coalesceKey?: string;
   recordEdit: (edit: RecordEditInput) => Promise<void>;
+  writeProjectFile: StudioProjectFileWriter;
   edit: SingleClipGsapEdit;
 }): Promise<void> {
   const { projectId, targetPath, domId, edit } = input;
@@ -519,6 +422,8 @@ export function finishClipTimingFallback(input: {
       timingChanged && domId && projectId
         ? () =>
             foldGsapMutationIntoHistory({
+              writeFile: input.writeProjectFile,
+              paths: [targetPath],
               projectId,
               label: input.label,
               coalesceKey: input.coalesceKey,
@@ -552,6 +457,7 @@ export async function finishGroupTimingGsapFallback<C extends { element: Timelin
   errorLabel: string;
   coalesceKey?: string;
   recordEdit: (edit: RecordEditInput) => Promise<void>;
+  writeProjectFile: StudioProjectFileWriter;
   activeCompPath: string | null;
   changes: readonly C[];
   resolveChangePath: (element: TimelineElement) => string;
@@ -568,6 +474,8 @@ export async function finishGroupTimingGsapFallback<C extends { element: Timelin
     reloadPreview: input.reloadPreview,
     gsapMutation: () =>
       foldGsapMutationIntoHistory({
+        writeFile: input.writeProjectFile,
+        paths: input.changes.map((change) => input.resolveChangePath(change.element)),
         projectId: input.projectId,
         label: input.label,
         coalesceKey: input.coalesceKey,

package/src/hooks/timelineTrackVisibility.ts

@@ -9,11 +9,11 @@ import {
 } from "../player/components/timelineTrackDisplay";
 import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";
 import { isAudioTimelineElement } from "../utils/timelineInspector";
-import { readTagSnippetByTarget, type PatchOperation } from "../utils/sourcePatcher";
+import type { PatchOperation } from "../utils/sourcePatcher";
 import {
-  applyPatchByTarget,
-  buildPatchTarget,
   findTimelineElementInIframe,
+  operationChanges,
+  patchTimelineChangesInSource,
   readFileContent,
   type RecordEditInput,
 } from "./timelineEditingHelpers";
@@ -149,38 +149,24 @@ async function setElementsHidden({
     property: "hidden",
     value: hidden ? "" : null,
   };
-  const originalByPath = new Map<string, string>();
-  const files: Record<string, string> = {};
-
-  try {
-    for (const [targetPath, fileElements] of groupElementsByTargetPath(elements, activeCompPath)) {
-      let patchedContent = await readFileContent(projectId, targetPath);
-      originalByPath.set(targetPath, patchedContent);
-
-      for (const element of fileElements) {
-        const patchTarget = buildPatchTarget(element);
-        if (!patchTarget) {
-          throw new Error(`Timeline element ${element.id} is missing a patchable target`);
-        }
-        if (readTagSnippetByTarget(patchedContent, patchTarget) === undefined) {
-          throw new Error(`Unable to patch timeline element ${element.id} in ${targetPath}`);
-        }
-        patchedContent = applyPatchByTarget(patchedContent, patchTarget, hiddenOperation);
-      }
-
-      files[targetPath] = patchedContent;
+  const files: Record<string, (current: string) => string> = {};
+  for (const [targetPath, fileElements] of groupElementsByTargetPath(elements, activeCompPath)) {
+    files[targetPath] = (current) => {
       pendingTimelineEditPathRef.current.add(targetPath);
-    }
+      return patchTimelineChangesInSource(
+        current,
+        targetPath,
+        operationChanges(fileElements, hiddenOperation),
+      );
+    };
+  }
 
+  try {
     const changedPaths = await saveProjectFilesWithHistory({
       projectId,
       label,
       files,
-      readFile: async (path) => {
-        const original = originalByPath.get(path);
-        if (original !== undefined) return original;
-        return readFileContent(projectId, path);
-      },
+      readFile: (path) => readFileContent(projectId, path),
       writeFile: writeProjectFile,
       recordEdit,
     });

package/src/hooks/useApplyColorGradingScope.test.tsx

@@ -0,0 +1,53 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { expect, it, vi } from "vitest";
+import { useApplyColorGradingScope } from "./useApplyColorGradingScope";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const readProjectFile = vi.fn(async (_path: string) => "<html><body></body></html>");
+
+vi.mock("../contexts/StudioContext", () => ({
+  useStudioShellContext: () => ({
+    projectId: "demo",
+    activeCompPath: "index.html",
+    showToast: vi.fn(),
+    waitForPendingDomEditSaves: async () => {},
+  }),
+}));
+vi.mock("../contexts/DomEditContext", () => ({
+  useDomEditContext: () => ({ domEditSelection: null }),
+}));
+vi.mock("../contexts/FileManagerContext", () => ({
+  useFileManagerContext: () => ({
+    readProjectFile,
+    writeProjectFile: vi.fn(),
+    fileTree: ["index.html", "scene.html", ".hyperframes/preview/4884df6e.html"],
+    compositions: ["index.html", "scene.html"],
+  }),
+}));
+
+it("grades the project's compositions, not Studio's generated preview documents", async () => {
+  let apply: ReturnType<typeof useApplyColorGradingScope> | null = null;
+  function Probe() {
+    apply = useApplyColorGradingScope(
+      vi.fn(async () => {}),
+      vi.fn(),
+    );
+    return null;
+  }
+  const root = createRoot(document.createElement("div"));
+  act(() => root.render(<Probe />));
+
+  await act(async () => {
+    await apply!("project", null);
+  });
+
+  expect(readProjectFile.mock.calls.map(([path]) => path).sort()).toEqual([
+    "index.html",
+    "scene.html",
+  ]);
+  act(() => root.unmount());
+});

package/src/hooks/useApplyColorGradingScope.ts

@@ -0,0 +1,54 @@
+import { useCallback } from "react";
+import { useStudioShellContext } from "../contexts/StudioContext";
+import { useDomEditContext } from "../contexts/DomEditContext";
+import { useFileManagerContext } from "../contexts/FileManagerContext";
+import {
+  applyColorGradingScopeUpdate,
+  EMPTY_COLOR_GRADING_SCOPE_RESULT,
+  type ColorGradingScope,
+} from "../components/studioColorGradingScope";
+import type { StudioRightPanelsProps } from "../components/StudioRightPanels.types";
+
+export function useApplyColorGradingScope(
+  recordEdit: StudioRightPanelsProps["recordEdit"],
+  reloadPreview: StudioRightPanelsProps["reloadPreview"],
+) {
+  const { projectId, activeCompPath, showToast, waitForPendingDomEditSaves } =
+    useStudioShellContext();
+  const { domEditSelection } = useDomEditContext();
+  const { readProjectFile, writeProjectFile, compositions } = useFileManagerContext();
+  return useCallback(
+    async (scope: ColorGradingScope, value: string | null) =>
+      applyColorGradingScopeUpdate({
+        scope,
+        value,
+        selectedSourceFile: domEditSelection?.sourceFile || activeCompPath || "index.html",
+        compositionPaths: compositions,
+        projectId,
+        waitForPendingDomEditSaves,
+        readProjectFile,
+        writeProjectFile,
+        recordEdit,
+        reloadPreview,
+        showToast,
+      }).catch((error) => {
+        showToast(
+          `Couldn't apply color grading: ${error instanceof Error ? error.message : String(error)}`,
+          "error",
+        );
+        return EMPTY_COLOR_GRADING_SCOPE_RESULT;
+      }),
+    [
+      activeCompPath,
+      compositions,
+      domEditSelection?.sourceFile,
+      projectId,
+      readProjectFile,
+      recordEdit,
+      reloadPreview,
+      showToast,
+      waitForPendingDomEditSaves,
+      writeProjectFile,
+    ],
+  );
+}