@hyperframes/studio 0.7.56 → 0.7.58

package/src/hooks/useElementLifecycleOps.ts

@@ -11,6 +11,14 @@ import {
   readHfId,
   type DomEditSelection,
 } from "../components/editor/domEditing";
+import { LAYER_REVEAL_PRIOR_POSITION_ATTR } from "../player/lib/timelineElementHelpers";
+import {
+  beginLayerRevealCommit,
+  beginLayerZPersist,
+  completeLayerRevealCommit,
+  rollbackLayerRevealCommit,
+  type LayerRevealCommitOwnership,
+} from "../components/editor/useLayerRevealOverride";
 import type { CommitDomEditPatchBatches, DomEditPatchBatch } from "./domEditCommitTypes";
 
 interface UseElementLifecycleOpsParams extends DomEditCommitBaseParams {
@@ -25,6 +33,36 @@ interface UseElementLifecycleOpsParams extends DomEditCommitBaseParams {
   onElementDeleted?: (selection: DomEditSelection) => void;
 }
 
+// One coalesce key per z-reorder gesture. A monotonic counter — NOT Date.now()
+// / Math.random(), which the determinism rules forbid — matches the
+// laneChangeGestureSeq precedent in timelineClipDragCommit.ts: the key only has
+// to be unique per gesture and identical across the gesture's records.
+let zReorderGestureSeq = 0;
+
+/**
+ * Undo coalesce key for ONE z-reorder gesture — unique per call. The key
+ * carries the action kind + element ids for debuggability, plus a gesture
+ * sequence so two SEPARATE user actions (even the same action on the same
+ * selection) never share a key. That uniqueness is what makes the unbounded
+ * per-gesture coalesce window (see handleDomZIndexReorderCommit) safe: the
+ * fold can only ever merge records of the SAME gesture.
+ *
+ * Exported as THE single implementation of the key: the canvas z-order wiring
+ * (PreviewOverlays) mints it once per gesture and passes the same instance to
+ * both the z persist and the timeline lane mirror (useCanvasZOrderTimelineMirror)
+ * so editHistory folds the z write and the track write into one undo entry —
+ * recomputing the key per record would silently split the undo.
+ */
+export function zReorderCoalesceKey(
+  entries: ReadonlyArray<{ element: HTMLElement; id?: string; selector?: string }>,
+  actionKind?: string,
+): string {
+  const ids = entries
+    .map((e) => e.id ?? e.selector ?? e.element.getAttribute("data-hf-id") ?? "el")
+    .join(":");
+  return `z-reorder:${actionKind ?? "reorder"}:${ids}:g${zReorderGestureSeq++}`;
+}
+
 export function useElementLifecycleOps({
   activeCompPath,
   showToast,
@@ -130,11 +168,11 @@ export function useElementLifecycleOps({
     ],
   );
 
-  // ponytail: z-index reorder folds every element patch for a source file in memory and sends
-  // one patch-elements-batch request, so each file is persisted with one atomic disk write.
+  // Z-index reorder folds patches by source file, then sends one aggregate cross-file
+  // patch-element-batches request. The server refuses the whole gesture on any unmatched
+  // target and rolls back earlier file writes if a later write fails.
   // No SDK reorder/reparent op exists; DOM sibling order stays server-authoritative if ever needed.
   const handleDomZIndexReorderCommit = useCallback(
-    // fallow-ignore-next-line complexity
     (
       entries: Array<{
         element: HTMLElement;
@@ -146,78 +184,146 @@ export function useElementLifecycleOps({
         key?: string;
       }>,
       gestureCoalesceKey?: string,
+      actionKind?: string,
     ) => {
       if (entries.length === 0) return Promise.resolve();
-      // Resolver shadow (telemetry-only, decoupled from cutover): record whether
-      // the SDK resolves each reordered element — the reorderElements op's targets.
-      onReorderShadow?.(
-        entries.map((e) => readHfId(e.element)).filter((id): id is string => id != null),
-      );
-      const coalesceKey =
-        gestureCoalesceKey ??
-        `z-reorder:${entries.map((e) => e.id ?? e.selector ?? e.element.getAttribute("data-hf-id") ?? "el").join(":")}`;
-      const patchesBySourceFile = new Map<string, DomEditPatchBatch["patches"]>();
-      const rollbacks: Array<() => void> = [];
-      for (const entry of entries) {
-        const priorZIndex = entry.element.style.zIndex;
-        const priorPosition = entry.element.style.position;
-        const priorStoreEntry = entry.key
-          ? usePlayerStore.getState().elements.find((el) => (el.key ?? el.id) === entry.key)
-          : undefined;
-        let positionChanged = false;
-        entry.element.style.zIndex = String(entry.zIndex);
-        const patches: Array<{ type: "inline-style"; property: string; value: string }> = [
-          { type: "inline-style", property: "z-index", value: String(entry.zIndex) },
-        ];
+      // One async owner must bracket reveal tokens, optimistic DOM/store state,
+      // atomic persistence, rollback, and the final persistence-count release.
+      // Splitting those phases would make transaction ownership less explicit.
+      // fallow-ignore-next-line complexity
+      return (async () => {
+        const releaseZPersists = entries.map((entry) => beginLayerZPersist(entry.element));
         try {
-          const win = entry.element.ownerDocument?.defaultView;
-          if (win && win.getComputedStyle(entry.element).position === "static") {
-            entry.element.style.position = "relative";
-            positionChanged = true;
-            patches.push({ type: "inline-style", property: "position", value: "relative" });
+          // Resolver shadow (telemetry-only, decoupled from cutover): record whether
+          // the SDK resolves each reordered element — the reorderElements op's targets.
+          onReorderShadow?.(
+            entries.map((e) => readHfId(e.element)).filter((id): id is string => id != null),
+          );
+          // The default key carries the action kind so two DIFFERENT actions on the
+          // same element set (e.g. "bring-forward" then "send-backward" within the
+          // coalesce window) never merge into one undo step. Callers that share a
+          // gesture (lane moves) pass an explicit gestureCoalesceKey instead.
+          const coalesceKey = gestureCoalesceKey ?? zReorderCoalesceKey(entries, actionKind);
+          const patchesBySourceFile = new Map<string, DomEditPatchBatch["patches"]>();
+          const rollbacks: Array<() => void> = [];
+          const revealCommits: Array<{
+            element: HTMLElement;
+            ownership: LayerRevealCommitOwnership;
+          }> = [];
+          for (const entry of entries) {
+            const priorZIndex = entry.element.style.zIndex;
+            const priorPosition = entry.element.style.position;
+            const priorStoreEntry = entry.key
+              ? usePlayerStore.getState().elements.find((el) => (el.key ?? el.id) === entry.key)
+              : undefined;
+            let positionChanged = false;
+            // An active Layers-panel reveal lift on this element is consumed by
+            // this commit: the new z is the truth. Read the parked TRUE position
+            // for the static check below (the lift set a temporary
+            // position:relative that would otherwise mask the need to persist
+            // one), then drop the lift attributes so z readers stop reporting the
+            // stale prior (see useLayerRevealOverride / readLayerRevealPriorZ).
+            const liftPriorPosition = entry.element.getAttribute(LAYER_REVEAL_PRIOR_POSITION_ATTR);
+            const revealOwnership = beginLayerRevealCommit(entry.element);
+            if (revealOwnership) {
+              revealCommits.push({ element: entry.element, ownership: revealOwnership });
+            }
+            entry.element.style.zIndex = String(entry.zIndex);
+            const patches: Array<{ type: "inline-style"; property: string; value: string }> = [
+              { type: "inline-style", property: "z-index", value: String(entry.zIndex) },
+            ];
+            try {
+              const win = entry.element.ownerDocument?.defaultView;
+              const effectivePosition =
+                liftPriorPosition ??
+                (win ? win.getComputedStyle(entry.element).position : undefined);
+              if (effectivePosition === "static") {
+                entry.element.style.position = "relative";
+                positionChanged = true;
+                patches.push({ type: "inline-style", property: "position", value: "relative" });
+              }
+            } catch {
+              /* cross-origin or detached — skip */
+            }
+            if (entry.key) {
+              usePlayerStore
+                .getState()
+                .updateElement(entry.key, { zIndex: entry.zIndex, hasExplicitZIndex: true });
+            }
+            rollbacks.push(() => {
+              if (revealOwnership) {
+                rollbackLayerRevealCommit(entry.element, revealOwnership);
+              } else {
+                entry.element.style.zIndex = priorZIndex;
+                if (positionChanged) entry.element.style.position = priorPosition;
+              }
+              if (entry.key && priorStoreEntry) {
+                usePlayerStore.getState().updateElement(entry.key, {
+                  zIndex: priorStoreEntry.zIndex,
+                  hasExplicitZIndex: priorStoreEntry.hasExplicitZIndex,
+                });
+              }
+            });
+            const filePatches = patchesBySourceFile.get(entry.sourceFile) ?? [];
+            filePatches.push({
+              target: buildDomEditPatchTarget({
+                id: entry.id,
+                hfId: readHfId(entry.element),
+                selector: entry.selector,
+                selectorIndex: entry.selectorIndex,
+              }),
+              operations: patches,
+            });
+            patchesBySourceFile.set(entry.sourceFile, filePatches);
           }
-        } catch {
-          /* cross-origin or detached — skip */
-        }
-        if (entry.key) {
-          usePlayerStore
-            .getState()
-            .updateElement(entry.key, { zIndex: entry.zIndex, hasExplicitZIndex: true });
-        }
-        rollbacks.push(() => {
-          entry.element.style.zIndex = priorZIndex;
-          if (positionChanged) entry.element.style.position = priorPosition;
-          if (entry.key && priorStoreEntry) {
-            usePlayerStore.getState().updateElement(entry.key, {
-              zIndex: priorStoreEntry.zIndex,
-              hasExplicitZIndex: priorStoreEntry.hasExplicitZIndex,
+          const batches = [...patchesBySourceFile].map(([sourceFile, patches]) => ({
+            sourceFile,
+            patches,
+          }));
+          // Live z state changed with NO reload coming (skipReload below) — nudge
+          // DOM-derived views (Layers panel z-sort) to re-read the iframe.
+          usePlayerStore.getState().bumpZEditVersion();
+          const rollbackOptimisticState = () => {
+            for (const rollback of rollbacks) rollback();
+            usePlayerStore.getState().bumpZEditVersion();
+          };
+          // Resolves once every source-file batch is persisted so a same-file timing write
+          // can be ordered after it (see applyTimelineStackingReorder callers).
+          //
+          // skipReload: the live iframe DOM and the player store already hold the
+          // final z state (applied synchronously above), and the persisted patch is
+          // inline-style-only — a full iframe remount would only blink the preview.
+          // commitDomEditPatchBatches still falls back to reloading whenever the
+          // server reports an unmatched patch target (live DOM ≠ disk).
+          try {
+            const result = await commitDomEditPatchBatches(batches, {
+              label: "Reorder layers",
+              coalesceKey,
+              // Unbounded window: every key this commit records under is unique per
+              // gesture (zReorderCoalesceKey's gesture seq, or the lane drag's
+              // clip-lane-move:<seq>), so the fold can only merge records of the SAME
+              // gesture — and those records are separated by a server round-trip
+              // (move→z on a lane drag, z→lane-mirror on a canvas action), which
+              // under real network latency exceeds the 300ms default window.
+              coalesceMs: Number.POSITIVE_INFINITY,
+              skipReload: true,
             });
+            if (!result.durable) {
+              rollbackOptimisticState();
+              return result;
+            }
+            for (const { element, ownership } of revealCommits) {
+              completeLayerRevealCommit(element, ownership);
+            }
+            return result;
+          } catch (error) {
+            rollbackOptimisticState();
+            throw error;
           }
-        });
-        const filePatches = patchesBySourceFile.get(entry.sourceFile) ?? [];
-        filePatches.push({
-          target: buildDomEditPatchTarget({
-            id: entry.id,
-            hfId: readHfId(entry.element),
-            selector: entry.selector,
-            selectorIndex: entry.selectorIndex,
-          }),
-          operations: patches,
-        });
-        patchesBySourceFile.set(entry.sourceFile, filePatches);
-      }
-      const batches = [...patchesBySourceFile].map(([sourceFile, patches]) => ({
-        sourceFile,
-        patches,
-      }));
-      // Resolves once every source-file batch is persisted so a same-file timing write
-      // can be ordered after it (see applyTimelineStackingReorder callers).
-      return commitDomEditPatchBatches(batches, { label: "Reorder layers", coalesceKey }).catch(
-        (error) => {
-          for (const rollback of rollbacks) rollback();
-          throw error;
-        },
-      );
+        } finally {
+          for (const release of releaseZPersists) release();
+        }
+      })();
     },
     [commitDomEditPatchBatches, onReorderShadow],
   );

package/src/hooks/useElementPicker.ts

@@ -1,6 +1,10 @@
 import { useState, useCallback, useRef } from "react";
 import { useMountEffect } from "./useMountEffect";
 import { resolveSourceFile, applyPatch } from "../utils/sourcePatcher";
+import {
+  acceptStudioRuntimeMessage,
+  postRuntimeControlMessage,
+} from "../player/lib/runtimeProtocol";
 
 export interface PickedElement {
   id: string | null;
@@ -65,10 +69,7 @@ export function useElementPicker(
 
   const enablePick = useCallback(() => {
     try {
-      getActiveIframe()?.contentWindow?.postMessage(
-        { source: "hf-parent", type: "control", action: "enable-pick-mode" },
-        "*",
-      );
+      postRuntimeControlMessage(getActiveIframe()?.contentWindow, "enable-pick-mode");
       setIsPickMode(true);
     } catch {
       /* cross-origin */
@@ -77,10 +78,7 @@ export function useElementPicker(
 
   const disablePick = useCallback(() => {
     try {
-      getActiveIframe()?.contentWindow?.postMessage(
-        { source: "hf-parent", type: "control", action: "disable-pick-mode" },
-        "*",
-      );
+      postRuntimeControlMessage(getActiveIframe()?.contentWindow, "disable-pick-mode");
     } catch {
       /* cross-origin */
     }
@@ -96,6 +94,7 @@ export function useElementPicker(
     const handleMessage = (e: MessageEvent) => {
       const data = e.data;
       if (data?.source !== "hf-preview") return;
+      if (!acceptStudioRuntimeMessage(data)) return;
       // Accept events from either the primary iframe or the active override
       const activeIframe = getActiveIframe();
       if (!activeIframe) return;

package/src/hooks/usePreviewPersistence.ts

@@ -10,7 +10,7 @@ import type { EditHistoryKind } from "../utils/editHistory";
 import { createDomEditSaveQueue } from "../utils/domEditSaveQueue";
 import { flushStudioPendingEdits } from "../utils/studioPendingEdits";
 import { trackStudioEvent } from "../utils/studioTelemetry";
-import { applyUndoRestoreToPreview, type UndoRestoreFile } from "../utils/gsapSoftReload";
+import { applyUndoRestoreToPreview, type UndoRestoreFile } from "../utils/gsapUndoRestore";
 import { usePlayerStore } from "../player";
 
 /** The restore payload the undo/redo preview-sync consumes (from the history store). */
@@ -156,7 +156,7 @@ export function usePreviewPersistence({
 
   // ── Queue / drain helpers ──
 
-  const queueDomEditSave = useCallback((save: () => Promise<void>) => {
+  const queueDomEditSave = useCallback(<T>(save: () => Promise<T>): Promise<T> => {
     return domEditSaveQueueRef.current?.enqueue(save) ?? save();
   }, []);
 

package/src/hooks/useTimelineAssetDropOps.ts

@@ -0,0 +1,175 @@
+// Asset-drop handlers for the timeline: drop an existing project asset at a
+// placement, or upload dragged-in OS files and place them sequentially.
+// Extracted verbatim from useTimelineEditing.ts to keep it under the studio
+// 600-line cap.
+import { useCallback, type MutableRefObject, type RefObject } from "react";
+import type { TimelineElement } from "../player";
+import {
+  buildTimelineAssetId,
+  buildTimelineAssetInsertHtml,
+  buildTimelineFileDropPlacements,
+  fitTimelineAssetGeometry,
+  getTimelineAssetKind,
+  insertTimelineAssetIntoSource,
+  resolveTimelineAssetCompositionSize,
+  resolveTimelineAssetSrc,
+} from "../utils/timelineAssetDrop";
+import { generateId } from "../utils/generateId";
+import { saveProjectFilesWithHistory, type RecordEditInput } from "../utils/studioFileHistory";
+import { collectHtmlIds, resolveDroppedAssetDuration } from "../utils/studioHelpers";
+import { formatTimelineAttributeNumber } from "./timelineEditingHelpers";
+import { readFileContent } from "./timelineTimingSync";
+
+interface UseTimelineAssetDropOpsOptions {
+  projectIdRef: MutableRefObject<string | null>;
+  activeCompPath: string | null;
+  timelineElements: TimelineElement[];
+  showToast: (message: string, tone?: "error" | "info") => void;
+  writeProjectFile: (path: string, content: string) => Promise<void>;
+  recordEdit: (input: RecordEditInput) => Promise<void>;
+  domEditSaveTimestampRef: MutableRefObject<number>;
+  reloadPreview: () => void;
+  uploadProjectFiles: (files: Iterable<File>, dir?: string) => Promise<string[]>;
+  isRecordingRef?: RefObject<boolean>;
+  forceReloadSdkSession?: () => void;
+}
+
+export function useTimelineAssetDropOps({
+  projectIdRef,
+  activeCompPath,
+  timelineElements,
+  showToast,
+  writeProjectFile,
+  recordEdit,
+  domEditSaveTimestampRef,
+  reloadPreview,
+  uploadProjectFiles,
+  isRecordingRef,
+  forceReloadSdkSession,
+}: UseTimelineAssetDropOpsOptions) {
+  // fallow-ignore-next-line complexity
+  const handleTimelineAssetDrop = useCallback(
+    // fallow-ignore-next-line complexity
+    async (
+      assetPath: string,
+      placement: Pick<TimelineElement, "start" | "track">,
+      durationOverride?: number,
+    ) => {
+      if (isRecordingRef?.current) {
+        showToast("Cannot edit timeline while recording", "error");
+        return;
+      }
+      const pid = projectIdRef.current;
+      if (!pid) throw new Error("No active project");
+
+      const kind = getTimelineAssetKind(assetPath);
+      if (!kind) {
+        showToast("Only image, video, and audio assets can be dropped onto the timeline.");
+        return;
+      }
+
+      const targetPath = activeCompPath || "index.html";
+      try {
+        const originalContent = await readFileContent(pid, targetPath);
+
+        const normalizedStart = Number(formatTimelineAttributeNumber(placement.start));
+        const duration =
+          Number.isFinite(durationOverride) && durationOverride != null && durationOverride > 0
+            ? durationOverride
+            : await resolveDroppedAssetDuration(pid, assetPath, kind);
+        const normalizedDuration = Number(formatTimelineAttributeNumber(duration));
+        const newId = buildTimelineAssetId(assetPath, collectHtmlIds(originalContent));
+        const resolvedAssetSrc = resolveTimelineAssetSrc(targetPath, assetPath);
+
+        const resolvedTargetPath = targetPath || "index.html";
+        const relevantElements = timelineElements.filter(
+          (te) => (te.sourceFile || activeCompPath || "index.html") === resolvedTargetPath,
+        );
+        const newElementZIndex = Math.max(1, relevantElements.length + 1);
+
+        const patchedContent = insertTimelineAssetIntoSource(
+          originalContent,
+          buildTimelineAssetInsertHtml({
+            id: newId,
+            hfId: `hf-${generateId()}`,
+            assetPath: resolvedAssetSrc,
+            kind,
+            start: normalizedStart,
+            duration: normalizedDuration,
+            track: placement.track,
+            zIndex: newElementZIndex,
+            geometry: fitTimelineAssetGeometry(
+              null,
+              resolveTimelineAssetCompositionSize(originalContent),
+            ),
+          }),
+        );
+
+        domEditSaveTimestampRef.current = Date.now();
+        await saveProjectFilesWithHistory({
+          projectId: pid,
+          label: "Add timeline asset",
+          kind: "timeline",
+          files: { [targetPath]: patchedContent },
+          readFile: async () => originalContent,
+          writeFile: writeProjectFile,
+          recordEdit,
+        });
+
+        forceReloadSdkSession?.();
+        reloadPreview();
+      } catch (error) {
+        const message =
+          error instanceof Error ? error.message : "Failed to drop asset onto timeline";
+        showToast(message);
+      }
+    },
+    [
+      projectIdRef,
+      activeCompPath,
+      recordEdit,
+      showToast,
+      timelineElements,
+      writeProjectFile,
+      domEditSaveTimestampRef,
+      reloadPreview,
+      isRecordingRef,
+      forceReloadSdkSession,
+    ],
+  );
+
+  // fallow-ignore-next-line complexity
+  const handleTimelineFileDrop = useCallback(
+    // fallow-ignore-next-line complexity
+    async (files: File[], placement?: Pick<TimelineElement, "start" | "track">) => {
+      if (isRecordingRef?.current) {
+        showToast("Cannot edit timeline while recording", "error");
+        return;
+      }
+      const pid = projectIdRef.current;
+      if (!pid) return;
+      const uploaded = await uploadProjectFiles(files);
+      if (uploaded.length === 0) return;
+      const durations: number[] = [];
+      for (const assetPath of uploaded) {
+        const kind = getTimelineAssetKind(assetPath);
+        const duration = kind ? await resolveDroppedAssetDuration(pid, assetPath, kind) : 0;
+        durations.push(Number(formatTimelineAttributeNumber(duration)));
+      }
+      const placements = buildTimelineFileDropPlacements(
+        placement ?? { start: 0, track: 0 },
+        durations,
+      );
+      for (const [index, assetPath] of uploaded.entries()) {
+        await handleTimelineAssetDrop(
+          assetPath,
+          placements[index] ?? placements[0],
+          durations[index],
+        );
+      }
+    },
+    [handleTimelineAssetDrop, projectIdRef, uploadProjectFiles, isRecordingRef, showToast],
+  );
+
+  return { handleTimelineAssetDrop, handleTimelineFileDrop };
+}