@hyperframes/studio 0.8.86 → 0.8.88

package/src/hooks/useDomEditPersist.ts

@@ -0,0 +1,225 @@
+import { useCallback, useRef } from "react";
+import { findUnsafeDomPatchValues } from "@hyperframes/core/studio-api/finite-mutation";
+import { trackStudioEvent } from "../utils/studioTelemetry";
+import { buildDomEditPatchTarget, type DomEditSelection } from "../components/editor/domEditing";
+import type { PersistDomEditOperations } from "./domEditCommitTypes";
+import type { PatchOperation } from "../utils/sourcePatcher";
+import {
+  DomEditPersistUnsafeValueError,
+  DomEditPersistUnresolvableError,
+  warnDomEditPersistNoOp,
+} from "./domEditPersistFailure";
+import {
+  formatUnsafeFieldList,
+  postPatchElement,
+  writePreparedContent,
+} from "./useDomEditCommitsHelpers";
+import type { CutoverResult } from "../utils/sdkCutover";
+import { reseekPreviewRuntime } from "./timelineTrackVisibility";
+import { serializeStudioFileMutations } from "../utils/studioFileMutationCoordinator";
+import { readProjectFileContent } from "../utils/studioFileHistory";
+
+export interface RecordEditInput {
+  label: string;
+  coalesceKey?: string;
+  coalesceMs?: number;
+  files: Record<string, { before: string; after: string }>;
+}
+
+export interface UseDomEditPersistParams {
+  activeCompPath: string | null;
+  previewIframeRef: React.MutableRefObject<HTMLIFrameElement | null>;
+  showToast: (message: string, tone?: "error" | "info") => void;
+  queueDomEditSave: <T>(save: () => Promise<T>) => Promise<T>;
+  writeProjectFile: (path: string, content: string, expectedContent?: string) => Promise<void>;
+  editHistory: { recordEdit: (entry: RecordEditInput) => Promise<void> };
+  projectIdRef: React.MutableRefObject<string | null>;
+  reloadPreview: () => void;
+  forceReloadSdkSession?: () => void;
+  onTrySdkPersist?: (
+    selection: DomEditSelection,
+    operations: PatchOperation[],
+    originalContent: string,
+    targetPath: string,
+    options?: { label?: string; coalesceKey?: string; skipRefresh?: boolean },
+  ) => Promise<CutoverResult>;
+}
+
+/** Studio's one DOM-edit writer: patches the source file, records history, then reloads or reseeks the preview. */
+export function useDomEditPersist({
+  activeCompPath,
+  previewIframeRef,
+  showToast,
+  queueDomEditSave,
+  writeProjectFile,
+  editHistory,
+  projectIdRef,
+  reloadPreview,
+  forceReloadSdkSession,
+  onTrySdkPersist,
+}: UseDomEditPersistParams): PersistDomEditOperations {
+  const reportedUnresolvableRef = useRef(new Set<string>());
+
+  // fallow-ignore-next-line complexity
+  const performPersistDomEditOperations = useCallback(
+    // fallow-ignore-next-line complexity
+    async (
+      selection: DomEditSelection,
+      operations: PatchOperation[],
+      options: Parameters<PersistDomEditOperations>[2],
+      expectedProjectId: string,
+    ) => {
+      if (projectIdRef.current !== expectedProjectId) {
+        throw new Error("Active project changed before the edit could be saved");
+      }
+      const pid = expectedProjectId;
+      if (options?.shouldSave && !options.shouldSave()) return;
+
+      const targetPath = selection.sourceFile || activeCompPath || "index.html";
+      const completePersistence = <T>(result: T, changed: boolean): T => {
+        if (options?.skipRefresh && changed) reseekPreviewRuntime(previewIframeRef.current);
+        return result;
+      };
+
+      const readTarget = async (): Promise<string | null> => {
+        const content = await readProjectFileContent(pid, targetPath);
+        if (projectIdRef.current !== expectedProjectId) {
+          throw new Error("Active project changed before the edit could be saved");
+        }
+        return options?.shouldSave && !options.shouldSave() ? null : content;
+      };
+
+      // Validate layout values BEFORE any persist path runs. The SDK cutover
+      // path (onTrySdkPersist) returns early on success, so leaving this check
+      // after it let invalid numeric values bypass the guard whenever the
+      // cutover flag was on.
+      const patchTarget = buildDomEditPatchTarget(selection);
+      const patchBody = { target: patchTarget, operations };
+      const unsafeFields = findUnsafeDomPatchValues(patchBody);
+      if (unsafeFields.length > 0) {
+        const fields = formatUnsafeFieldList(unsafeFields);
+        showToast("Couldn't save edit because it contains invalid layout values", "error");
+        throw new DomEditPersistUnsafeValueError(`DOM patch contains unsafe values: ${fields}`, {
+          alreadyToasted: true,
+        });
+      }
+
+      // Skip the SDK path when prepareContent is set (e.g. @font-face injection
+      // for a custom font): sdkCutoverPersist serializes only the patched DOM
+      // and would drop the injected content. Let the server path run prepareContent.
+      // The SDK joins the file queue itself and re-reads there; this read is only its fallback.
+      if (onTrySdkPersist && !options?.prepareContent) {
+        const originalContent = await readTarget();
+        if (originalContent === null) return;
+        const cutover = await onTrySdkPersist(selection, operations, originalContent, targetPath, {
+          label: options?.label,
+          coalesceKey: options?.coalesceKey,
+          skipRefresh: options?.skipRefresh,
+        });
+        if (cutover.status === "failed") throw cutover.error;
+        if (cutover.status === "committed") {
+          // SDK handled it — its in-memory doc is already current, so do NOT
+          // forceReload (that would echo-reload the session we just wrote).
+          return completePersistence(
+            { sourceFile: targetPath, version: cutover.version, changed: true },
+            true,
+          );
+        }
+      }
+
+      const history = {
+        label: options?.label ?? "Edit layer",
+        coalesceKey: options?.coalesceKey,
+        coalesceMs: options?.coalesceMs,
+      };
+      const prepare = options?.prepareContent;
+      // Read, server patch, follow-up write and history hold the file's queue, so no save lands between them.
+      const saved = await serializeStudioFileMutations(writeProjectFile, [targetPath], async () => {
+        const originalContent = await readTarget();
+        if (originalContent === null) return null;
+        const patchData = await postPatchElement(pid, targetPath, patchBody, showToast);
+        if (!patchData.changed) return { patchData, patchedContent: null, finalContent: null };
+
+        const patchedContent =
+          typeof patchData.content === "string" ? patchData.content : originalContent;
+        const finalContent = prepare
+          ? await writePreparedContent(
+              targetPath,
+              patchedContent,
+              prepare,
+              writeProjectFile,
+              showToast,
+            )
+          : patchedContent;
+
+        await editHistory.recordEdit({
+          ...history,
+          files: { [targetPath]: { before: originalContent, after: finalContent } },
+        });
+        return { patchData, patchedContent, finalContent };
+      });
+      if (saved === null) return;
+      const { patchData, patchedContent, finalContent } = saved;
+
+      if (finalContent === null) {
+        if (patchData.matched === false) {
+          const targetKey = selection.selector ?? selection.id ?? "selection";
+          if (!reportedUnresolvableRef.current.has(targetKey)) {
+            reportedUnresolvableRef.current.add(targetKey);
+            trackStudioEvent("save_skipped_unresolvable", {
+              target_id: selection.id ?? undefined,
+              target_selector: selection.selector ?? undefined,
+              target_source_file: selection.sourceFile ?? undefined,
+              composition: activeCompPath ?? undefined,
+            });
+          }
+          throw new DomEditPersistUnresolvableError(targetPath);
+        }
+        warnDomEditPersistNoOp(selection, operations);
+        return completePersistence(
+          typeof patchData.path === "string" && typeof patchData.version === "string"
+            ? { sourceFile: patchData.path, version: patchData.version, changed: false }
+            : undefined,
+          false,
+        );
+      }
+      forceReloadSdkSession?.();
+
+      if (!options?.skipRefresh) {
+        reloadPreview();
+      }
+      return completePersistence(
+        finalContent === patchedContent &&
+          typeof patchData.path === "string" &&
+          typeof patchData.version === "string"
+          ? { sourceFile: patchData.path, version: patchData.version, changed: true }
+          : undefined,
+        true,
+      );
+    },
+    [
+      activeCompPath,
+      editHistory,
+      writeProjectFile,
+      projectIdRef,
+      reloadPreview,
+      showToast,
+      forceReloadSdkSession,
+      onTrySdkPersist,
+      previewIframeRef,
+    ],
+  );
+
+  const persistDomEditOperations: PersistDomEditOperations = useCallback(
+    (selection, operations, options) => {
+      const expectedProjectId = projectIdRef.current;
+      if (!expectedProjectId) return Promise.reject(new Error("No active project"));
+      return queueDomEditSave(() =>
+        performPersistDomEditOperations(selection, operations, options, expectedProjectId),
+      );
+    },
+    [performPersistDomEditOperations, projectIdRef, queueDomEditSave],
+  );
+
+  return persistDomEditOperations;
+}

package/src/hooks/useDomEditPreviewSync.test.ts

@@ -0,0 +1,58 @@
+// @vitest-environment happy-dom
+
+import { createElement, act } from "react";
+import { createRoot } from "react-dom/client";
+import { describe, expect, it, vi } from "vitest";
+import { useDomEditPreviewSync } from "./useDomEditPreviewSync";
+import { sceneSwapFor } from "../player/sceneSwap";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+describe("useDomEditPreviewSync", () => {
+  it("re-syncs the preview when edited scenes are swapped in, and not when the swap is refused", async () => {
+    const iframe = document.createElement("iframe");
+    let refuse = false;
+    Object.defineProperty(iframe, "contentWindow", {
+      value: {
+        __hfSwapScenes: async () => {
+          if (refuse) throw new Error("the film changed outside its scenes");
+        },
+      },
+    });
+    const fetchSpy = vi.spyOn(globalThis, "fetch").mockImplementation(async () => new Response(""));
+    const applyManualEdits = vi.fn(async () => {});
+    const refreshVersion = vi.fn();
+    function Harness() {
+      useDomEditPreviewSync({
+        previewIframe: iframe,
+        activeCompPath: null,
+        captionEditMode: false,
+        domEditSelectionRef: { current: null },
+        domEditGroupSelectionsRef: { current: [] },
+        domEditSelection: null,
+        refreshDomEditGroupSelectionsFromPreview: async () => {},
+        applyDomSelection: () => {},
+        buildDomSelectionFromTarget: async () => null,
+        refreshPreviewDocumentVersion: refreshVersion,
+        syncPreviewHotkeys: () => {},
+        applyStudioManualEditsToPreviewRef: { current: applyManualEdits },
+      });
+      return null;
+    }
+    const root = createRoot(document.createElement("div"));
+    act(() => root.render(createElement(Harness)));
+    applyManualEdits.mockClear();
+    refreshVersion.mockClear();
+
+    refuse = true;
+    await act(() => sceneSwapFor(iframe)!("/preview", () => true).catch(() => {}));
+    expect(refreshVersion).not.toHaveBeenCalled();
+
+    refuse = false;
+    await act(() => sceneSwapFor(iframe)!("/preview", () => true));
+    expect(applyManualEdits).toHaveBeenCalledWith(iframe);
+    expect(refreshVersion).toHaveBeenCalledTimes(1);
+    act(() => root.unmount());
+    fetchSpy.mockRestore();
+  });
+});

package/src/hooks/useDomEditPreviewSync.ts

@@ -9,6 +9,7 @@ import { reapplyPositionEditsAfterSeek } from "../components/editor/manualEdits"
 import { useDockLayoutStore } from "../components/dock/dockLayoutStore";
 import type { PatchTarget } from "../utils/sourcePatcher";
 import { logSelect } from "../utils/selectDebug";
+import { onPreviewContentReplaced } from "../player/sceneSwap";
 
 interface UseDomEditPreviewSyncParams {
   previewIframe: HTMLIFrameElement | null;
@@ -113,10 +114,7 @@ export function useDomEditPreviewSync({
       refreshPreviewDocumentVersion();
     };
 
-    previewIframe.addEventListener("load", handleLoad);
-    return () => {
-      previewIframe.removeEventListener("load", handleLoad);
-    };
+    return onPreviewContentReplaced(previewIframe, handleLoad);
   }, [
     activeCompPath,
     applyDomSelection,

package/src/hooks/useDomEditSession.test.tsx

@@ -5,6 +5,7 @@ import { describe, expect, it, vi } from "vitest";
 import { shouldUseSdkCutover } from "../utils/sdkCutover";
 import type { PatchOperation } from "../utils/sourcePatcher";
 import type { Composition } from "@hyperframes/sdk";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import type { TimelineElement } from "../player";
 import type { UseDomEditSessionParams } from "./useDomEditSession";
@@ -62,6 +63,8 @@ const domEditSelectionRef: { current: DomEditSelection | null } = { current: nul
 const domEditGroupSelectionsRef: { current: DomEditSelection[] } = { current: [] };
 const groupSelectionSpy = vi.fn();
 const gsapCommitMutation = Object.assign(vi.fn(), { batch: vi.fn() });
+const neverParsed = new Promise<{ animations: GsapAnimation[] }>(() => undefined);
+const parsedFile = { current: neverParsed };
 
 function createSessionParams(
   overrides: Partial<UseDomEditSessionParams> = {},
@@ -166,7 +169,12 @@ vi.mock("./useAskAgentModal", () => ({
 vi.mock("./useStudioSelectionPublisher", () => ({
   useStudioSelectionPublisher: () => {},
 }));
-vi.mock("./useGsapTweenCache", () => ({
+vi.mock("./keyframeCacheAstLoad", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("./keyframeCacheAstLoad")>()),
+  fetchParsedAnimations: () => parsedFile.current,
+}));
+vi.mock("./useGsapTweenCache", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("./useGsapTweenCache")>()),
   useGsapCacheVersion: () => ({ version: 0, bump: vi.fn() }),
 }));
 vi.mock("./useGsapScriptCommits", () => ({
@@ -413,6 +421,48 @@ describe("bulk segment ease commits", () => {
   });
 });
 
+describe("the session hands out selections narrowed to what the GSAP commit accepts", () => {
+  it("closes the move of a helper-loop element once its preflight lands", async () => {
+    const { useDomEditSession } = await import("./useDomEditSession");
+    domEditSelectionRef.current = {
+      id: "hero",
+      selector: "#hero",
+      element: document.createElement("div"),
+      sourceFile: "index.html",
+      capabilities: {
+        canApplyManualOffset: true,
+        canApplyManualSize: true,
+        canApplyManualRotation: true,
+      },
+    } as unknown as DomEditSelection;
+    const loop = { targetSelector: "#hero", properties: { x: 100 }, provenance: { kind: "loop" } };
+    parsedFile.current = Promise.resolve({ animations: [loop as unknown as GsapAnimation] });
+    const seen: { selection?: DomEditSelection | null } = {};
+    function Probe() {
+      seen.selection = useDomEditSession(createSessionParams()).domEditSelection;
+      return null;
+    }
+    const root = createRoot(document.createElement("div"));
+    try {
+      act(() => root.render(<Probe />));
+      expect(seen.selection?.capabilities.canApplyManualOffset).toBe(false);
+      await act(async () => {
+        for (let tick = 0; tick < 10; tick++) await Promise.resolve();
+      });
+      expect(seen.selection?.capabilities).toMatchObject({
+        canApplyManualOffset: false,
+        canApplyManualSize: true,
+        canApplyManualRotation: true,
+        reasonIfDisabled: expect.stringContaining("helper or loop"),
+      });
+    } finally {
+      domEditSelectionRef.current = null;
+      parsedFile.current = neverParsed;
+      act(() => root.unmount());
+    }
+  });
+});
+
 // ── Grouping refuses audio ───────────────────────────────────────────────────
 //
 // A layout group is a positioned wrapper: it takes the members' bounding box,

package/src/hooks/useDomEditSession.ts

@@ -19,6 +19,7 @@ import { useDomEditWiring } from "./useDomEditWiring";
 import { useGsapAwareEditing } from "./useGsapAwareEditing";
 import { useStudioSelectionPublisher } from "./useStudioSelectionPublisher";
 import { useKeyframeEaseCommits } from "./useKeyframeEaseCommits";
+import { useCommitPreflightCapabilities } from "./useCommitPreflightCapabilities";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { membersForDelete, timelineElementsForDelete } from "./domEditDeleteMembers";
 import type { RecordEditInput } from "./domEditDeleteMembers";
@@ -494,9 +495,17 @@ export function useDomEditSession({
   });
   const { handleUpdateSegmentEase, handleUpdateKeyframeEase, handleSetAllKeyframeEases } =
     useKeyframeEaseCommits({ gsapCommitMutation, domEditSelectionRef });
+  const committable = useCommitPreflightCapabilities({
+    projectId,
+    enabled: gsapCommitMutation !== null,
+    selection: domEditSelection,
+    groupSelections: domEditGroupSelections,
+    previewIframeRef,
+    version: gsapCacheVersion,
+  });
   return {
-    domEditSelection,
-    domEditGroupSelections,
+    domEditSelection: committable.selection,
+    domEditGroupSelections: committable.groupSelections,
     domEditHoverSelection,
     activeGroupElement,
     agentModalOpen,

package/src/hooks/useDomEditTextCommits.ts

@@ -1,10 +1,5 @@
 import { useCallback, useRef } from "react";
-import type { PatchOperation } from "../utils/sourcePatcher";
-import {
-  isImageBackgroundValue,
-  isManualGeometryStyleProperty,
-  normalizeDomEditStyleValue,
-} from "../utils/studioHelpers";
+import { normalizeDomEditStyleValue } from "../utils/studioHelpers";
 import {
   injectPreviewGoogleFont,
   injectPreviewImportedFont,
@@ -12,7 +7,6 @@ import {
 } from "../utils/studioFontHelpers";
 import {
   buildDomEditRichTextPatchOperation,
-  buildDomEditStylePatchOperation,
   findElementForSelection,
   getDomEditTargetKey,
   isTextEditableSelection,
@@ -32,6 +26,7 @@ import {
   runReportedDomEditCommit,
   type DomEditCommitOutcome,
 } from "./domEditCommitRunner";
+import { commitDomStyles } from "./domStyleCommit";
 import { useDomEditAttributeCommits } from "./useDomEditAttributeCommits";
 import type { InlineTextEditCommit } from "./useInlineTextEdit";
 
@@ -70,24 +65,6 @@ function ownsCurrentPreviewElement(
   return element === selection.element && element.ownerDocument === document;
 }
 
-function buildDomStyleCommitOperations(
-  property: string,
-  value: string,
-  isImageBackgroundCommit: boolean,
-): PatchOperation[] {
-  const operations: PatchOperation[] = [
-    buildDomEditStylePatchOperation(property, normalizeDomEditStyleValue(property, value)),
-  ];
-  if (isImageBackgroundCommit) {
-    operations.push(
-      buildDomEditStylePatchOperation("background-position", "center"),
-      buildDomEditStylePatchOperation("background-repeat", "no-repeat"),
-      buildDomEditStylePatchOperation("background-size", "contain"),
-    );
-  }
-  return operations;
-}
-
 async function resyncDomTextSelectionFromPreview(
   doc: Document | null | undefined,
   selection: DomEditSelection,
@@ -138,81 +115,20 @@ export function useDomEditTextCommits({
   });
 
   const handleDomStyleCommitForSelection = useCallback(
-    async (
-      selection: DomEditSelection,
-      property: string,
-      value: string,
-    ): Promise<DomEditCommitOutcome> => {
-      if (isManualGeometryStyleProperty(property))
-        return domEditCommitDeclined("geometry-property");
-      if (!selection.capabilities.canEditStyles) {
-        return domEditCommitDeclined("styles-not-editable");
-      }
-      const styleCommitKey = `${getDomEditTargetKey(selection)}:${property}`;
-      const isLatestStyleCommit = bumpDomEditCommitMapVersion(
-        domStyleCommitVersionRef.current,
-        styleCommitKey,
-      );
-      const importedFont = property === "font-family" ? resolveImportedFontAsset(value) : null;
-      const iframe = previewIframeRef.current;
-      const doc = iframe?.contentDocument;
-      const normalizedValue = normalizeDomEditStyleValue(property, value);
-      const isImageBackgroundCommit =
-        property === "background-image" && isImageBackgroundValue(value);
-      let editedElement: HTMLElement | null = null;
-      let previousInlineValue: string | null = null;
-      const operations = buildDomStyleCommitOperations(property, value, isImageBackgroundCommit);
-      // Inline-style commits never full-reload the preview (that blanks the iframe
-      // until it re-renders): the live element was already mutated optimistically in
-      // apply(). z-index is no exception — setting `element.style.zIndex` restacks the
-      // element in-browser immediately, so a reload would only cost a black blink.
-      const skipRefresh = true;
-
-      return runReportedDomEditCommit({
-        capture: () => {
-          if (!doc) return;
-          const el = findElementForSelection(doc, selection, activeCompPath);
-          if (!el) return;
-          editedElement = el;
-          previousInlineValue = el.style.getPropertyValue(property);
-        },
-        apply: () => {
-          if (!editedElement) return;
-          editedElement.style.setProperty(property, normalizedValue);
-          if (property === "font-family" && doc) {
-            injectPreviewGoogleFont(doc, value);
-            if (importedFont) injectPreviewImportedFont(doc, importedFont);
-          }
-          if (isImageBackgroundCommit) {
-            editedElement.style.setProperty("background-position", "center");
-            editedElement.style.setProperty("background-repeat", "no-repeat");
-            editedElement.style.setProperty("background-size", "contain");
-          }
-        },
-        persist: () =>
-          persistDomEditOperations(selection, operations, {
-            label: "Edit layer style",
-            skipRefresh,
-            prepareContent: importedFont
-              ? (html, sourceFile) => ensureImportedFontFace(html, importedFont, sourceFile)
-              : undefined,
-          }),
-        shouldRevert: () => isLatestStyleCommit(),
-        revert: () => {
-          if (!editedElement || previousInlineValue === null) return;
-          // ponytail: background-image side-effect styles are not reverted here.
-          if (previousInlineValue === "") {
-            editedElement.style.removeProperty(property);
-          } else {
-            editedElement.style.setProperty(property, previousInlineValue);
-          }
+    (selection: DomEditSelection, property: string, value: string): Promise<DomEditCommitOutcome> =>
+      commitDomStyles(
+        {
+          activeCompPath,
+          previewIframeRef,
+          persistDomEditOperations,
+          showToast,
+          versions: domStyleCommitVersionRef.current,
+          resolveImportedFontAsset,
+          resync: refreshDomEditSelectionFromPreview,
         },
-        onError: (error) => reportDomEditPersistFailure(selection, operations, error, showToast),
-        shouldResync: isLatestStyleCommit,
-        resync: () => refreshDomEditSelectionFromPreview(selection),
-        onFinally: isLatestStyleCommit.release,
-      });
-    },
+        selection,
+        { [property]: value },
+      ),
     [
       activeCompPath,
       persistDomEditOperations,