@hyperframes/studio 0.7.102 → 0.7.104

package/src/hooks/useGsapScriptCommits.test.tsx

@@ -73,14 +73,159 @@ describe("applyPreviewSync", () => {
 
     syncDragPreview(result(), reloadPreview);
 
-    expect(patchRuntimeTweenInPlace).toHaveBeenCalledWith(FAKE_IFRAME, "#a", {
-      kind: "set",
-      props: { x: 10 },
-    });
+    expect(patchRuntimeTweenInPlace).toHaveBeenCalledWith(
+      FAKE_IFRAME,
+      "#a",
+      {
+        kind: "set",
+        props: { x: 10 },
+      },
+      undefined,
+      false,
+    );
     expect(applySoftReload).not.toHaveBeenCalled();
     expect(reloadPreview).not.toHaveBeenCalled();
   });
 
+  it("instantPatches: patches every element the batch wrote, rendering once at the end", () => {
+    patchRuntimeTweenInPlace.mockReturnValue(true);
+    const reloadPreview = vi.fn();
+
+    applyPreviewSync(
+      FAKE_IFRAME,
+      result(),
+      {
+        label: "Move animated layer (group)",
+        softReload: true,
+        instantPatches: [
+          { selector: "#a", change: { kind: "set" as const, props: { x: 1 } } },
+          { selector: "#b", change: { kind: "set" as const, props: { x: 2 } } },
+          { selector: "#c", change: { kind: "set" as const, props: { x: 3 } } },
+        ],
+      },
+      reloadPreview,
+    );
+
+    // Only the last patch re-renders — the earlier two defer their seek, so the
+    // group repaints once instead of once per member.
+    expect(patchRuntimeTweenInPlace.mock.calls.map((call) => [call[1], call[4]])).toEqual([
+      ["#a", true],
+      ["#b", true],
+      ["#c", false],
+    ]);
+    expect(applySoftReload).not.toHaveBeenCalled();
+    expect(reloadPreview).not.toHaveBeenCalled();
+  });
+
+  it("applies both plural and singular patches when a caller supplies both", () => {
+    patchRuntimeTweenInPlace.mockReturnValue(true);
+
+    applyPreviewSync(
+      FAKE_IFRAME,
+      result(),
+      {
+        label: "mixed patch contract",
+        instantPatches: [
+          { selector: "#group-a", change: { kind: "set" as const, props: { x: 1 } } },
+        ],
+        instantPatch: {
+          selector: "#single-b",
+          change: { kind: "set" as const, props: { x: 2 } },
+        },
+      },
+      vi.fn(),
+    );
+
+    expect(patchRuntimeTweenInPlace.mock.calls.map((call) => [call[1], call[4]])).toEqual([
+      ["#group-a", true],
+      ["#single-b", false],
+    ]);
+  });
+
+  it("instantPatches: one patch that misses falls the whole batch back to the reload", () => {
+    patchRuntimeTweenInPlace.mockImplementation((_iframe, selector) => selector !== "#b");
+    applySoftReload.mockReturnValue("applied");
+    const reloadPreview = vi.fn();
+
+    applyPreviewSync(
+      FAKE_IFRAME,
+      result({ scriptText: "SCRIPT" }),
+      {
+        label: "Move animated layer (group)",
+        softReload: true,
+        instantPatches: [
+          { selector: "#a", change: { kind: "set" as const, props: { x: 1 } } },
+          { selector: "#b", change: { kind: "set" as const, props: { x: 2 } } },
+        ],
+      },
+      reloadPreview,
+    );
+
+    // A half-patched preview is worse than a reloaded one: "#a" landed, "#b" did
+    // not, so the reload repaints both from the written source.
+    expect(applySoftReload).toHaveBeenCalled();
+    expect(trackStudioEvent).toHaveBeenCalledWith("gsap_instant_patch_fallback", {
+      selector: "#b",
+    });
+  });
+
+  it("carries a deferred patch miss into the final batch render", () => {
+    const previewFallbackLatch = { pending: false };
+    applySoftReload.mockReturnValue("applied");
+    const reloadPreview = vi.fn();
+    patchRuntimeTweenInPlace.mockReturnValueOnce(false).mockReturnValueOnce(true);
+
+    applyPreviewSync(
+      FAKE_IFRAME,
+      result({ scriptText: "SCRIPT" }),
+      {
+        label: "Move animated layer (group)",
+        softReload: true,
+        deferPreviewSync: true,
+        previewFallbackLatch,
+        instantPatch: { selector: "#missed", change: { kind: "set", props: { x: 1 } } },
+      },
+      reloadPreview,
+    );
+
+    expect(previewFallbackLatch.pending).toBe(true);
+    expect(applySoftReload).not.toHaveBeenCalled();
+
+    applyPreviewSync(
+      FAKE_IFRAME,
+      result({ scriptText: "SCRIPT" }),
+      {
+        label: "Move animated layer (group)",
+        softReload: true,
+        previewFallbackLatch,
+        instantPatch: { selector: "#final", change: { kind: "set", props: { x: 2 } } },
+      },
+      reloadPreview,
+    );
+
+    expect(previewFallbackLatch.pending).toBe(false);
+    expect(applySoftReload).toHaveBeenCalledTimes(1);
+  });
+
+  it("falls back immediately when a deferred patch miss has no final-render latch", () => {
+    patchRuntimeTweenInPlace.mockReturnValue(false);
+    applySoftReload.mockReturnValue("applied");
+
+    applyPreviewSync(
+      FAKE_IFRAME,
+      result({ scriptText: "SCRIPT" }),
+      {
+        label: "Deferred standalone write",
+        softReload: true,
+        deferPreviewSync: true,
+        instantPatch: { selector: "#missed", change: { kind: "set", props: { x: 1 } } },
+      },
+      vi.fn(),
+    );
+
+    expect(applySoftReload).toHaveBeenCalledTimes(1);
+  });
+
   it("instantPatch + patch fails: falls back to the soft reload, passing onAsyncFailure", () => {
     patchRuntimeTweenInPlace.mockReturnValue(false);
     applySoftReload.mockReturnValue("applied");
@@ -338,10 +483,51 @@ describe("runCommit — instantPatch wiring", () => {
 
     // The file already matched (changed:false) but the runtime patch deferred
     // from the paired first commit must still land.
-    expect(patchRuntimeTweenInPlace).toHaveBeenCalledWith(FAKE_IFRAME, "#a", {
-      kind: "set",
-      props: { x: 485, y: 311 },
+    expect(patchRuntimeTweenInPlace).toHaveBeenCalledWith(
+      FAKE_IFRAME,
+      "#a",
+      {
+        kind: "set",
+        props: { x: 485, y: 311 },
+      },
+      undefined,
+      false,
+    );
+    expect(deps.reloadPreview).not.toHaveBeenCalled();
+  });
+
+  it("no-op batch still applies every plural instant patch", async () => {
+    patchRuntimeTweenInPlace.mockReturnValue(true);
+    mockFetchResult({ changed: false });
+    const deps = renderCommitHook();
+    const batch = deps.api.commitMutation.batch;
+    if (!batch) throw new Error("batch capability missing");
+
+    await act(async () => {
+      await batch(
+        [
+          {
+            selection,
+            mutation: { type: "update-property", property: "x", value: 10 },
+            options: {
+              label: "Move layer",
+              instantPatch: { selector: "#a", change: { kind: "set", props: { x: 10 } } },
+            },
+          },
+          {
+            selection: { ...selection, id: "b", selector: "#b" },
+            mutation: { type: "update-property", property: "x", value: 20 },
+            options: {
+              label: "Move layer",
+              instantPatch: { selector: "#b", change: { kind: "set", props: { x: 20 } } },
+            },
+          },
+        ],
+        { label: "Move animated layer (group)" },
+      );
     });
+
+    expect(patchRuntimeTweenInPlace.mock.calls.map((call) => call[1])).toEqual(["#a", "#b"]);
     expect(deps.reloadPreview).not.toHaveBeenCalled();
   });
 

package/src/hooks/useGsapScriptCommits.ts

@@ -36,6 +36,7 @@ import {
   useGsapSaveFailureTelemetry,
   useSafeGsapCommitMutation,
 } from "./useSafeGsapCommitMutation";
+import { studioWriteHeaders } from "../utils/studioFileVersion";
 
 async function mutateGsapScript(
   projectId: string,
@@ -46,7 +47,7 @@ async function mutateGsapScript(
     `/api/projects/${encodeURIComponent(projectId)}/gsap-mutations/${encodeURIComponent(sourceFile)}`,
     {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers: { "Content-Type": "application/json", ...studioWriteHeaders() },
       body: JSON.stringify(mutation),
     },
   );
@@ -65,7 +66,7 @@ async function mutateGsapScriptBatch(
     `/api/projects/${encodeURIComponent(projectId)}/gsap-mutations-batch/${encodeURIComponent(sourceFile)}`,
     {
       method: "POST",
-      headers: { "Content-Type": "application/json" },
+      headers: { "Content-Type": "application/json", ...studioWriteHeaders() },
       body: JSON.stringify({ mutations }),
     },
   );
@@ -125,7 +126,10 @@ function finishUnchangedMutation(
   reloadPreview: () => void,
 ): boolean {
   if (result.changed !== false) return false;
-  if (!options.skipReload && options.instantPatch) {
+  if (
+    !options.skipReload &&
+    (instantPatchesFor(options).length > 0 || options.previewFallbackLatch?.pending)
+  ) {
     applyPreviewSync(iframe, result, options, reloadPreview);
   }
   return true;
@@ -248,19 +252,37 @@ export function applyPreviewSync(
   options: CommitMutationOptions,
   reloadPreview: () => void,
 ): void {
-  if (options.instantPatch) {
-    const patched = patchRuntimeTweenInPlace(
-      iframe,
-      options.instantPatch.selector,
-      options.instantPatch.change,
+  const patches = instantPatchesFor(options);
+  let needsFallback = options.previewFallbackLatch?.pending === true;
+  if (patches.length > 0) {
+    const deferSeek = options.deferPreviewSync === true;
+    const missed = patches.find(
+      (patch, index) =>
+        !patchRuntimeTweenInPlace(
+          iframe,
+          patch.selector,
+          patch.change,
+          undefined,
+          deferSeek || index < patches.length - 1,
+        ),
     );
-    // Patched in place — element is already correct on screen; no reload needed.
-    if (patched) return;
-    // The instant path couldn't patch in place — record the fallback so we can
-    // track how often the fast path misses before the soft/full reload below.
-    trackStudioEvent("gsap_instant_patch_fallback", { selector: options.instantPatch.selector });
-    // Fall through to the soft/full reload path below.
+    if (missed) {
+      // The instant path couldn't patch in place — record the fallback so we can
+      // track how often the fast path misses before the soft/full reload below.
+      trackStudioEvent("gsap_instant_patch_fallback", { selector: missed.selector });
+      needsFallback = true;
+    }
+    // Patched in place — elements are already correct on screen; no reload needed
+    // unless an earlier deferred batch left one member unpatched.
+    if (!needsFallback) return;
+  }
+  // Written, but the caller has more writes to make and will render after the last.
+  if (options.deferPreviewSync && options.previewFallbackLatch) {
+    options.previewFallbackLatch.pending = needsFallback;
+    return;
   }
+  if (options.deferPreviewSync && !needsFallback) return;
+  if (options.previewFallbackLatch) options.previewFallbackLatch.pending = false;
   if (options.softReload && result.scriptText) {
     // A soft-reloadable edit escalates to a full iframe remount ONLY on the
     // PERMANENT "cannot-soft-reload" result (the preview is genuinely stale/
@@ -280,6 +302,15 @@ export function applyPreviewSync(
   }
 }
 
+function instantPatchesFor(
+  options: CommitMutationOptions,
+): NonNullable<CommitMutationOptions["instantPatches"]> {
+  return [
+    ...(options.instantPatches ?? []),
+    ...(options.instantPatch ? [options.instantPatch] : []),
+  ];
+}
+
 // oxfmt-ignore
 // fallow-ignore-next-line complexity
 export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIframeRef, editHistory, domEditSaveTimestampRef, reloadPreview, onCacheInvalidate, onFileContentChanged, showToast, sdkSession, publishSdkSession, writeProjectFile, forceReloadSdkSession }: GsapScriptCommitsParams) {
@@ -355,7 +386,13 @@ export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIfra
     );
     if (!result) return;
     options.onResult?.(result);
-    await finalizeSuccessfulMutation(pid, compositionPath, last.selection, last.mutation, targetPath, result, options);
+    // Each call brings its own fast-path patch; the batch wrote them all, so the
+    // preview sync applies them all rather than just the last call's.
+    const instantPatches = calls
+      .map(({ options: callOptions }) => callOptions.instantPatch)
+      .filter((patch) => patch !== undefined);
+    const { instantPatch: _instantPatch, ...batchOptions } = options;
+    await finalizeSuccessfulMutation(pid, compositionPath, last.selection, last.mutation, targetPath, result, instantPatches.length > 0 ? { ...batchOptions, instantPatches } : batchOptions);
   }, [showToast, finalizeSuccessfulMutation]);
 
   // Every GSAP-script commit is a read-modify-write of one file. Overlapping

package/src/hooks/useStudioUrlState.ts

@@ -7,6 +7,7 @@ import {
   buildStudioHash,
   parseStudioUrlStateFromHash,
   type StudioUrlSelectionState,
+  type StudioUrlSelectionTarget,
   type StudioUrlState,
 } from "../utils/studioUrlState";
 
@@ -22,6 +23,8 @@ interface UseStudioUrlStateParams {
   rightCollapsed: boolean;
   activeCompPathHydrated: boolean;
   domEditSelection: DomEditSelection | null;
+  domEditGroupSelections: DomEditSelection[];
+  applyMarqueeSelection: (selections: DomEditSelection[], additive: boolean) => void;
   buildDomSelectionFromTarget: (
     target: HTMLElement,
     options?: { preferClipAncestor?: boolean },
@@ -38,8 +41,7 @@ interface UseStudioUrlStateParams {
   initialState: StudioUrlState;
 }
 
-function toPersistedSelection(selection: DomEditSelection | null): StudioUrlSelectionState | null {
-  if (!selection) return null;
+function toPersistedTarget(selection: DomEditSelection): StudioUrlSelectionTarget | null {
   if (!selection.id && !selection.selector) return null;
   return {
     sourceFile: selection.sourceFile || undefined,
@@ -49,12 +51,109 @@ function toPersistedSelection(selection: DomEditSelection | null): StudioUrlSele
   };
 }
 
+function selectionTargetKey(selection: StudioUrlSelectionTarget): string {
+  return [
+    selection.sourceFile ?? "",
+    selection.id ?? "",
+    selection.selector ?? "",
+    selection.selectorIndex ?? "",
+  ].join("|");
+}
+
+function toPersistedSelection(
+  selection: DomEditSelection | null,
+  // Optional: a caller that only ever has one selection has nothing to add, and
+  // the URL must still carry that one rather than throwing on the way out.
+  group: DomEditSelection[] = [],
+): StudioUrlSelectionState | null {
+  if (!selection) return null;
+  const primary = toPersistedTarget(selection);
+  if (!primary) return null;
+  // The primary is already carried by the top-level fields; the rest ride along so the link
+  // reopens the same multi-selection instead of a single element.
+  const primaryKey = selectionTargetKey(primary);
+  const members = new Map<string, StudioUrlSelectionTarget>();
+  for (const member of group) {
+    const target = toPersistedTarget(member);
+    if (!target) continue;
+    const key = selectionTargetKey(target);
+    if (key !== primaryKey) members.set(key, target);
+  }
+  return {
+    ...primary,
+    group: members.size > 0 ? [...members.values()] : undefined,
+  };
+}
+
 function replaceHash(nextHash: string) {
   if (typeof window === "undefined") return;
   if (window.location.hash === nextHash) return;
   window.history.replaceState(null, "", nextHash);
 }
 
+interface ResolveUrlSelectionsParams {
+  doc: Document;
+  primaryElement: HTMLElement;
+  selection: StudioUrlSelectionState;
+  group: StudioUrlSelectionTarget[];
+  activeCompPath: string | null;
+  isCurrent: () => boolean;
+  buildDomSelection: UseStudioUrlStateParams["buildDomSelectionFromTarget"];
+}
+
+function findUrlSelectionElement(
+  doc: Document,
+  target: StudioUrlSelectionTarget,
+  fallbackSourceFile: string,
+  activeCompPath: string | null,
+): HTMLElement | null {
+  return findElementForSelection(
+    doc,
+    {
+      sourceFile: target.sourceFile ?? fallbackSourceFile,
+      id: target.id,
+      selector: target.selector,
+      selectorIndex: target.selectorIndex,
+    },
+    activeCompPath,
+  );
+}
+
+async function buildOptionalDomSelection(
+  element: HTMLElement | null,
+  buildDomSelection: UseStudioUrlStateParams["buildDomSelectionFromTarget"],
+): Promise<DomEditSelection | null> {
+  if (!element) return null;
+  return buildDomSelection(element, { preferClipAncestor: false });
+}
+
+async function resolveUrlSelections({
+  doc,
+  primaryElement,
+  selection,
+  group,
+  activeCompPath,
+  isCurrent,
+  buildDomSelection,
+}: ResolveUrlSelectionsParams): Promise<DomEditSelection[] | null> {
+  const primary = await buildDomSelection(primaryElement, { preferClipAncestor: false });
+  if (!isCurrent()) return null;
+  if (!primary) return [];
+  const members = [primary];
+  for (const member of group) {
+    const element = findUrlSelectionElement(
+      doc,
+      member,
+      selection.sourceFile ?? "",
+      activeCompPath,
+    );
+    const resolved = await buildOptionalDomSelection(element, buildDomSelection);
+    if (!isCurrent()) return null;
+    if (resolved) members.push(resolved);
+  }
+  return members;
+}
+
 export function useStudioUrlState({
   projectId,
   activeCompPath,
@@ -67,6 +166,8 @@ export function useStudioUrlState({
   rightCollapsed,
   activeCompPathHydrated,
   domEditSelection,
+  domEditGroupSelections,
+  applyMarqueeSelection,
   buildDomSelectionFromTarget,
   applyDomSelection,
   setRightPanelTab,
@@ -82,6 +183,7 @@ export function useStudioUrlState({
   const [selectionHydrated, setSelectionHydrated] = useState(initialState.selection == null);
   const pendingSelectionRef = useRef(initialState.selection);
   const stableTimeRef = useRef<number | null>(initialState.currentTime);
+  const selectionApplySeqRef = useRef(0);
 
   const buildUrlState = useCallback(
     (): StudioUrlState => ({
@@ -91,10 +193,10 @@ export function useStudioUrlState({
       rightCollapsed,
       timelineVisible: null,
       selection: hydratedSelectionRef.current
-        ? toPersistedSelection(domEditSelection)
+        ? toPersistedSelection(domEditSelection, domEditGroupSelections)
         : pendingSelectionRef.current,
     }),
-    [activeCompPath, domEditSelection, rightCollapsed, rightPanelTab],
+    [activeCompPath, domEditGroupSelections, domEditSelection, rightCollapsed, rightPanelTab],
   );
 
   // Resolve a URL selection to a live element and apply it. Shared by the initial
@@ -103,6 +205,7 @@ export function useStudioUrlState({
   // a missing element or null selection clears the selection and returns true.
   const applyUrlSelection = useCallback(
     (selection: StudioUrlSelectionState | null): boolean => {
+      const applySeq = ++selectionApplySeqRef.current;
       if (!selection) {
         applyDomSelection(null, { revealPanel: false });
         return true;
@@ -128,12 +231,32 @@ export function useStudioUrlState({
         applyDomSelection(null, { revealPanel: false });
         return true;
       }
-      void buildDomSelectionFromTarget(element, { preferClipAncestor: false }).then((resolved) => {
-        applyDomSelection(resolved, { revealPanel: false });
+      const group = selection.group ?? [];
+      void resolveUrlSelections({
+        doc,
+        primaryElement: element,
+        selection,
+        group,
+        activeCompPath,
+        isCurrent: () => applySeq === selectionApplySeqRef.current,
+        buildDomSelection: buildDomSelectionFromTarget,
+      }).then((members) => {
+        if (!members) return;
+        const primary = members[0];
+        if (!primary) return applyDomSelection(null, { revealPanel: false });
+        if (group.length === 0) return applyDomSelection(primary, { revealPanel: false });
+        // Missing group members are dropped without failing the rest.
+        applyMarqueeSelection(members, false);
       });
       return true;
     },
-    [activeCompPath, applyDomSelection, buildDomSelectionFromTarget, previewIframeRef],
+    [
+      activeCompPath,
+      applyDomSelection,
+      applyMarqueeSelection,
+      buildDomSelectionFromTarget,
+      previewIframeRef,
+    ],
   );
 
   useEffect(() => {

package/src/hooks/useTimelineEditing.ts

@@ -36,6 +36,7 @@ import { serializeZLaneGesture } from "../components/nle/zLaneGesture";
 import { cutoverCommittedOrThrow, sdkTimingPersist } from "../utils/sdkCutover";
 import type { UseTimelineEditingOptions } from "./useTimelineEditingTypes";
 import { getStudioSaveErrorMessage } from "../utils/studioSaveDiagnostics";
+import { studioWriteHeaders } from "../utils/studioFileVersion";
 
 type TimelineMoveUpdates = Pick<TimelineElement, "start" | "track"> & {
   stackingReorder?: TimelineStackingReorderIntent | null;
@@ -412,7 +413,7 @@ export function useTimelineEditing({
           `/api/projects/${pid}/file-mutations/remove-element/${encodeURIComponent(targetPath)}`,
           {
             method: "POST",
-            headers: { "Content-Type": "application/json" },
+            headers: { "Content-Type": "application/json", ...studioWriteHeaders() },
             body: JSON.stringify({ target: patchTarget }),
           },
         );

package/src/hooks/useTimelineSelectionPreviewSync.ts

@@ -2,6 +2,7 @@ import { useEffect, useMemo, useRef } from "react";
 import type { TimelineElement } from "../player";
 import type { DomEditSelection } from "../components/editor/domEditing";
 import { resolveTimelineIdForSelection } from "../utils/studioHelpers";
+import { logSelect } from "../utils/selectDebug";
 
 interface UseTimelineSelectionPreviewSyncParams {
   selectedElementId: string | null;
@@ -93,6 +94,13 @@ export function useTimelineSelectionPreviewSync({
 
     if (selectedIds.length === 0) {
       missingSelectionKeyRef.current = "";
+      // The timeline holds nothing, so the canvas is about to hold nothing either.
+      // This is the path that silently drops a selection the user can still see.
+      logSelect("timeline-empty", {
+        had: currentIds.length,
+        previousKey: previousSelectedKey.length > 0,
+        clearing: previousSelectedKey.length > 0 && currentIds.length > 0,
+      });
       if (previousSelectedKey.length > 0 && currentIds.length > 0) {
         applyDomSelection(null, { revealPanel: false });
       }
@@ -127,6 +135,11 @@ export function useTimelineSelectionPreviewSync({
         return;
       }
       missingSelectionKeyRef.current = "";
+      logSelect("timeline-sync", {
+        wanted: selectedIds.length,
+        had: currentIds.length,
+        resolved: selections.length,
+      });
       if (selections.length === 0) {
         applyDomSelection(null, { revealPanel: false });
       } else if (selections.length === 1) {

package/src/player/hooks/useTimelinePlayer.ts

@@ -4,6 +4,7 @@ import { useMountEffect } from "../../hooks/useMountEffect";
 import { usePlaybackKeyboard } from "./usePlaybackKeyboard";
 import { useTimelineSyncCallbacks } from "./useTimelineSyncCallbacks";
 import { useTimelinePlayerLoop } from "./useTimelinePlayerLoop";
+import { logReload } from "../../utils/reloadDebug";
 
 export type { ClipManifestClip } from "../lib/playbackTypes";
 export { createStaticSeekPlaybackAdapter } from "../lib/playbackAdapter";
@@ -445,6 +446,7 @@ export function useTimelinePlayer() {
   const refreshPlayer = useCallback(() => {
     const iframe = iframeRef.current;
     if (!iframe) return;
+    logReload("refreshPlayer", () => ({ stack: new Error("refreshPlayer").stack }));
     saveSeekPosition();
     // Hide the iframe across the full reload so the user never sees the reloading
     // document's RAW DOM (every clip stacked and visible) in the window between the