@hyperframes/studio 0.8.114 → 0.8.115

package/src/hooks/useEnableKeyframes.test.ts

@@ -314,7 +314,7 @@ describe("applyArcKeyframeAtPlayhead", () => {
         ],
         ease: "none",
       },
-      { label: "Add keyframe", softReload: true },
+      { label: "Add keyframe", softReload: true, keyframeAction: "add" },
     );
   });
 
@@ -336,7 +336,7 @@ describe("applyArcKeyframeAtPlayhead", () => {
         duration: 10,
         keyframes: expect.arrayContaining([{ percentage: 25, properties: { x: 25, y: 25 } }]),
       }),
-      { label: "Add keyframe", softReload: true },
+      { label: "Add keyframe", softReload: true, keyframeAction: "add" },
     );
   });
 });

package/src/hooks/useEnableKeyframes.ts

@@ -159,7 +159,7 @@ async function replaceSetWithSingleKeyframe(
       keyframes: [{ percentage: 0, properties: position }],
       ease: setAnim.ease,
     },
-    { label: "Enable keyframes", softReload: true },
+    { label: "Enable keyframes", keyframeAction: "add", softReload: true },
   );
 }
 
@@ -270,6 +270,7 @@ async function extendKeyframedTweenToPlayhead(
     },
     {
       label: "Add keyframe",
+      keyframeAction: "add",
       softReload: true,
       ...commitOverrides,
     },
@@ -377,7 +378,7 @@ export async function promoteSetToKeyframes(
       ],
       ease: setAnim.ease,
     },
-    { label: "Add keyframe", softReload: true },
+    { label: "Add keyframe", keyframeAction: "add", softReload: true },
   );
 }
 
@@ -454,7 +455,7 @@ export async function applyArcKeyframeAtPlayhead(
       }),
       ease: "none",
     },
-    { label: "Add keyframe", softReload: true },
+    { label: "Add keyframe", keyframeAction: "add", softReload: true },
   );
 }
 
@@ -503,6 +504,7 @@ export function useEnableKeyframes(
       enableKeyframesTransactionCounter += 1;
       const coalesceKey = `enable-keyframes:${flatAnim.id}:${enableKeyframesTransactionCounter}`;
       const convertCommitOverrides: Partial<CommitMutationOptions> = {
+        keyframeTelemetry: false,
         skipReload: true,
         coalesceKey,
         coalesceMs: Number.POSITIVE_INFINITY,

package/src/hooks/useExternalFileChangeCoordinator.test.tsx

@@ -143,6 +143,85 @@ describe("external file change coordinator", () => {
     expect(onAcceptedPersistedFileChange).toHaveBeenLastCalledWith("scene.html", ["scene.html"]);
   });
 
+  it("keeps a waiting head edit's thumbnail refresh when a later write replaces it", async () => {
+    let release = () => {};
+    const inFlight = new Promise<void>((resolve) => (release = resolve));
+    const onAcceptedPersistedFileChange = vi.fn();
+    let drains = 0;
+    await mountCoordinator({
+      onAcceptedPersistedFileChange,
+      drainPendingChanges: async () => {
+        if (drains++ === 0) await inFlight;
+        return { status: "clean" as const };
+      },
+    });
+    await act(async () => handler?.({ path: "other.html", content: "a", version: "v1" }));
+    await act(async () => handler?.({ path: "index.html", content: "b", version: "v2" }));
+    await act(async () =>
+      handler?.({
+        path: "index.html",
+        content: "c",
+        version: "v3",
+        affectedCompositions: ["index.html"],
+      }),
+    );
+    await act(async () => release());
+    expect(onAcceptedPersistedFileChange).toHaveBeenLastCalledWith("index.html", null);
+  });
+
+  it("keeps a head edit's thumbnail refresh through a conflict that a later write replaces", async () => {
+    const onAcceptedPersistedFileChange = vi.fn();
+    const conflict = new StudioFileConflictError({
+      filePath: "index.html",
+      currentVersion: "v1",
+      currentContent: "theirs",
+      attemptedContent: "mine",
+    });
+    const { captured } = await mountCoordinator({
+      onAcceptedPersistedFileChange,
+      drainPendingChanges: async () => ({ status: "conflict" as const, error: conflict }),
+    });
+    await act(async () => handler?.({ path: "index.html", content: "head", version: "v1" }));
+    await act(async () =>
+      handler?.({
+        path: "index.html",
+        content: "body",
+        version: "v2",
+        affectedCompositions: ["index.html"],
+      }),
+    );
+    await act(async () => captured.handle?.useExternalFile());
+    expect(onAcceptedPersistedFileChange).toHaveBeenLastCalledWith("index.html", null);
+  });
+
+  it("keeps a held head edit's thumbnail refresh when a later write saves cleanly", async () => {
+    const onAcceptedPersistedFileChange = vi.fn();
+    const conflict = new StudioFileConflictError({
+      filePath: "index.html",
+      currentVersion: "v1",
+      currentContent: "theirs",
+      attemptedContent: "mine",
+    });
+    let drains = 0;
+    await mountCoordinator({
+      onAcceptedPersistedFileChange,
+      drainPendingChanges: async () =>
+        drains++ === 0
+          ? { status: "conflict" as const, error: conflict }
+          : { status: "clean" as const },
+    });
+    await act(async () => handler?.({ path: "index.html", content: "head", version: "v1" }));
+    await act(async () =>
+      handler?.({
+        path: "index.html",
+        content: "body",
+        version: "v2",
+        affectedCompositions: ["index.html"],
+      }),
+    );
+    expect(onAcceptedPersistedFileChange).toHaveBeenLastCalledWith("index.html", null);
+  });
+
   it("does not refresh the tree for a suppressed self-write echo", async () => {
     const refreshFileTree = vi.fn();
     await mountCoordinator({ refreshFileTree });
@@ -333,6 +412,29 @@ describe("external file change coordinator", () => {
     expect(onAcceptedPersistedFileChange).toHaveBeenCalledOnce();
   });
 
+  it("keeps the failed file's payload when a snapshot delete fails for another file", async () => {
+    const { captured } = await mountCoordinator({
+      drainPendingChanges: vi
+        .fn()
+        .mockResolvedValueOnce({ status: "failed" as const, error: new Error("offline") })
+        .mockResolvedValueOnce({ status: "clean" as const }),
+      getPendingCandidate: () => ({ path: "scene.html", content: "studio" }),
+      deleteConflictSnapshot: vi.fn(async () => {
+        throw new Error("delete failed");
+      }),
+    });
+    await act(async () =>
+      handler?.({ path: "scene.html", content: "scene-external", version: "s1" }),
+    );
+    await act(async () =>
+      handler?.({ path: "index.html", content: "index-external", version: "i1" }),
+    );
+    expect(captured.handle?.blocked).toMatchObject({
+      status: "failed",
+      payload: { path: "scene.html", content: "scene-external", version: "s1" },
+    });
+  });
+
   it("restores and overwrites from a durable failed draft", async () => {
     const overwriteConflict = vi.fn(async () => undefined);
     const onAcceptedPersistedFileChange = vi.fn();

package/src/hooks/useExternalFileChangeCoordinator.ts

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useRef, useState, type MutableRefObject } from "react";
 import {
+  mergeFileChangeAffectedCompositions,
   readFileChangeAffectedCompositions,
   readFileChangeAffectsPreview,
   readFileChangeField,
@@ -163,7 +164,7 @@ export function useExternalFileChangeCoordinator({
   onAcceptedPersistedFileChange,
   refreshFileTree,
 }: ExternalFileChangeCoordinatorOptions): ExternalFileChangeCoordinatorHandle {
-  const [blocked, setBlocked] = useState<ExternalFileChangeBlockedState | null>(null);
+  const [blocked, setBlockedState] = useState<ExternalFileChangeBlockedState | null>(null);
   const generationRef = useRef(0);
   const mountedRef = useRef(true);
   const lastEventIdentityRef = useRef<string | null>(null);
@@ -172,6 +173,14 @@ export function useExternalFileChangeCoordinator({
   const drainingRef = useRef(false);
   const pendingPayloadRef = useRef<{ payload: unknown } | null>(null);
   blockedRef.current = blocked;
+  // A newer blocked change replaces the held one, so it inherits the thumbnails the held one owed.
+  const setBlocked = useCallback((next: ExternalFileChangeBlockedState | null) => {
+    setBlockedState((held) =>
+      next && held
+        ? { ...next, payload: mergeFileChangeAffectedCompositions(held.payload, next.payload) }
+        : next,
+    );
+  }, []);
 
   useEffect(() => {
     mountedRef.current = true;
@@ -185,7 +194,7 @@ export function useExternalFileChangeCoordinator({
     generationRef.current += 1;
     setBlocked(null);
     lastEventIdentityRef.current = null;
-  }, [projectId, activeCompPath]);
+  }, [projectId, activeCompPath, setBlocked]);
 
   useEffect(() => {
     if (!projectId || !recoveryFilePath || !loadConflictSnapshot) return;
@@ -229,7 +238,7 @@ export function useExternalFileChangeCoordinator({
     return () => {
       cancelled = true;
     };
-  }, [loadConflictSnapshot, projectId, recoveryFilePath]);
+  }, [loadConflictSnapshot, projectId, recoveryFilePath, setBlocked]);
 
   const reloadAcceptedGeneration = useCallback(
     (path: string, affectsPreview = true) => {
@@ -275,14 +284,22 @@ export function useExternalFileChangeCoordinator({
             await deleteConflictSnapshot(projectId!, path);
           } catch (error) {
             if (mountedRef.current && generation === generationRef.current) {
-              setBlocked({ ...previousBlocked, generation, error });
+              setBlocked({
+                ...previousBlocked,
+                generation,
+                error,
+                payload: mergeFileChangeAffectedCompositions(payload, previousBlocked.payload),
+              });
             }
             return;
           }
         }
         if (!mountedRef.current || generation !== generationRef.current) return;
         setBlocked(null);
-        onAcceptedPersistedFileChange(path, readFileChangeAffectedCompositions(payload));
+        const owed = previousBlocked
+          ? mergeFileChangeAffectedCompositions(previousBlocked.payload, payload)
+          : payload;
+        onAcceptedPersistedFileChange(path, readFileChangeAffectedCompositions(owed));
         reloadAcceptedGeneration(path, readFileChangeAffectsPreview(payload));
         return;
       }
@@ -344,6 +361,7 @@ export function useExternalFileChangeCoordinator({
     },
     [
       drainPendingChanges,
+      setBlocked,
       projectId,
       deleteConflictSnapshot,
       getPendingCandidate,
@@ -419,7 +437,12 @@ export function useExternalFileChangeCoordinator({
         waiting != null &&
         readFileChangeAffectsPreview(waiting) &&
         !readFileChangeAffectsPreview(payload);
-      if (!waitingChangeOutranksThis) pendingPayloadRef.current = { payload };
+      if (!waitingChangeOutranksThis) {
+        pendingPayloadRef.current = {
+          payload:
+            waiting == null ? payload : mergeFileChangeAffectedCompositions(waiting, payload),
+        };
+      }
       void startDrainLoop();
     },
     [projectId, pendingTimelineEditPathRef, startDrainLoop, onAcceptedPersistedFileChange],
@@ -469,6 +492,7 @@ export function useExternalFileChangeCoordinator({
     },
     [
       deleteConflictSnapshot,
+      setBlocked,
       discardPendingChanges,
       onUseExternalFile,
       onAcceptedPersistedFileChange,
@@ -527,6 +551,7 @@ export function useExternalFileChangeCoordinator({
     reloadAcceptedGeneration(conflict.filePath);
   }, [
     deleteConflictSnapshot,
+    setBlocked,
     discardPendingChanges,
     overwriteConflict,
     projectId,

package/src/hooks/useGestureCommit.test.tsx

@@ -1,12 +1,18 @@
 // @vitest-environment jsdom
-import { act } from "react";
+import { act, useLayoutEffect } from "react";
 import { afterEach, describe, expect, it, vi } from "vitest";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import { trackStudioEvent } from "../utils/studioTelemetry";
+import { trackKeyframeCommit } from "../utils/keyframeUsage";
 import type { DomEditSelection } from "../components/editor/domEditing";
 import { usePlayerStore } from "../player";
 import { mountReactHarness } from "./domSelectionTestHarness";
 import type { CommitMutationOptions } from "./gsapScriptCommitTypes";
+import { useGsapAwareEditing } from "./useGsapAwareEditing";
 import { useGestureCommit } from "./useGestureCommit";
 
+vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+
 const gestureRecording = vi.hoisted(() => ({
   startRecording: vi.fn(),
   stopRecording: vi.fn(() => [
@@ -84,44 +90,88 @@ function makeSelection(element: HTMLElement): DomEditSelection {
   };
 }
 
+function mountRecording(
+  writer: (
+    mutation: Record<string, unknown>,
+    options: CommitMutationOptions,
+    selection?: DomEditSelection,
+  ) => Promise<void>,
+  animations: GsapAnimation[] = [],
+  readOnlyPreview = false,
+) {
+  const iframe = document.createElement("iframe");
+  document.body.append(iframe);
+  const element = document.createElement("div");
+  element.id = "card";
+  const session = {
+    current: {
+      domEditSelection: makeSelection(element),
+      selectedGsapAnimations: animations,
+      commitMutation: writer,
+    },
+  };
+  let hook: ReturnType<typeof useGestureCommit> | null = null;
+  function Probe() {
+    const editing = useGsapAwareEditing({
+      domEditSelection: session.current.domEditSelection,
+      selectedGsapAnimations: session.current.selectedGsapAnimations,
+      gsapCommitMutation: (selection, mutation, options) => writer(mutation, options, selection),
+      previewIframeRef: { current: iframe },
+      showToast: vi.fn(),
+      bumpGsapCache: vi.fn(),
+      makeFetchFallback: () => vi.fn(),
+      trackGsapInteractionFailure: vi.fn(),
+      stageElementPositionOffset: vi.fn(),
+      handleDomBoxSizeCommit: vi.fn(),
+      handleDomRotationCommit: vi.fn(),
+      commitPositionPatchToHtml: vi.fn(),
+      addGsapAnimation: vi.fn(),
+      convertToKeyframes: vi.fn(),
+      setArcPath: vi.fn(),
+      updateArcSegment: vi.fn(),
+    });
+    const currentHook = useGestureCommit({
+      domEditSessionRef: session,
+      previewIframeRef: { current: iframe },
+      showToast: vi.fn(),
+      isGestureRecordingRef: { current: false },
+      readOnlyPreview,
+    });
+    useLayoutEffect(() => {
+      session.current.commitMutation = editing.commitMutation;
+      hook = currentHook;
+    });
+    return null;
+  }
+  const root = mountReactHarness(<Probe />);
+  cleanup = () => act(() => root.unmount());
+  return Object.assign(
+    () => {
+      if (!hook) throw new Error("hook did not initialize");
+      return hook;
+    },
+    {
+      select: (selection: DomEditSelection, nextAnimations: GsapAnimation[]) => {
+        session.current.domEditSelection = selection;
+        session.current.selectedGsapAnimations = nextAnimations;
+        act(() => root.render(<Probe />));
+      },
+    },
+  );
+}
+
 describe("useGestureCommit", () => {
   it("coalesces property-group commits and reloads only the terminal group", async () => {
-    const iframe = document.createElement("iframe");
-    document.body.append(iframe);
-    const element = document.createElement("div");
-    element.id = "card";
-    const commitMutation = vi.fn<
+    const writer = vi.fn<
       (mutation: Record<string, unknown>, options: CommitMutationOptions) => Promise<void>
     >(async () => {});
-    const sessionRef = {
-      current: {
-        domEditSelection: makeSelection(element),
-        selectedGsapAnimations: [],
-        commitMutation,
-      },
-    };
-    const captured: { hook: ReturnType<typeof useGestureCommit> | null } = { hook: null };
-    function Probe() {
-      captured.hook = useGestureCommit({
-        domEditSessionRef: sessionRef,
-        previewIframeRef: { current: iframe },
-        showToast: vi.fn(),
-        isGestureRecordingRef: { current: false },
-        readOnlyPreview: false,
-      });
-      return null;
-    }
-    const root = mountReactHarness(<Probe />);
-    cleanup = () => act(() => root.unmount());
-    if (!captured.hook) throw new Error("hook did not initialize");
-
-    act(() => captured.hook?.handleToggleRecording());
-    act(() => captured.hook?.handleToggleRecording());
+    const hook = mountRecording(writer);
+    act(() => hook().handleToggleRecording());
+    act(() => hook().handleToggleRecording());
     await act(async () => {
-      await vi.waitFor(() => expect(commitMutation).toHaveBeenCalledTimes(2));
+      await vi.waitFor(() => expect(writer).toHaveBeenCalledTimes(2));
     });
-
-    const options = commitMutation.mock.calls.map((call) => call[1]);
+    const options = writer.mock.calls.map((call) => call[1]);
     expect(new Set(options.map((entry) => entry.coalesceKey)).size).toBe(1);
     expect(options[0]).toEqual(expect.objectContaining({ coalesceMs: Infinity, skipReload: true }));
     expect(options[0]).not.toHaveProperty("softReload");
@@ -130,30 +180,150 @@ describe("useGestureCommit", () => {
   });
 
   it("does not start a recording while the preview is read-only", () => {
-    const element = document.createElement("div");
-    const commitMutation = vi.fn(async () => {});
-    const captured: { hook: ReturnType<typeof useGestureCommit> | null } = { hook: null };
-    function Probe() {
-      captured.hook = useGestureCommit({
-        domEditSessionRef: {
-          current: {
-            domEditSelection: makeSelection(element),
-            selectedGsapAnimations: [],
-            commitMutation,
-          },
-        },
-        previewIframeRef: { current: document.createElement("iframe") },
-        showToast: vi.fn(),
-        isGestureRecordingRef: { current: false },
-        readOnlyPreview: true,
+    const writer = vi.fn(async () => {});
+    const hook = mountRecording(writer, [], true);
+    act(() => hook().handleToggleRecording());
+    expect(gestureRecording.startRecording).not.toHaveBeenCalled();
+    expect(writer).not.toHaveBeenCalled();
+  });
+});
+
+it.each([
+  ["new mixed-property recording", undefined, true, true, 1, "button"],
+  ["keyboard recording", undefined, true, true, 1, "keyboard"],
+  ["static hold replacement", "set", true, true, 1, "button"],
+  ["overlapping tween replacement", "to", true, true, 1, "button"],
+  ["unchanged recording", undefined, true, false, 0, "button"],
+  ["refused recording", undefined, false, true, 0, "button"],
+] as const)(
+  "counts writer receipts once for %s",
+  async (_name, method, ok, changed, count, inputMethod) => {
+    const animations = method
+      ? [
+          {
+            id: "card-position",
+            targetSelector: "#card",
+            propertyGroup: "position",
+            method,
+            properties: { x: 0, y: 0 },
+            resolvedStart: 0,
+            position: 0,
+            duration: method === "set" ? 0 : 2,
+            keyframes: {
+              keyframes: [
+                { percentage: 0, properties: { x: 0 } },
+                { percentage: 100, properties: { x: 100 } },
+              ],
+            },
+          } as unknown as GsapAnimation,
+        ]
+      : [];
+    const writer = vi.fn(
+      async (mutation: Record<string, unknown>, options: CommitMutationOptions) => {
+        const result = { ok, changed };
+        trackKeyframeCommit([mutation], result, options);
+        options.onResult?.(result);
+      },
+    );
+    const hook = mountRecording(writer, animations);
+    act(() => hook().handleToggleRecording(inputMethod));
+    await act(async () => {
+      hook().handleToggleRecording();
+      await vi.waitFor(() => expect(writer).toHaveBeenCalled());
+    });
+    expect(trackStudioEvent).toHaveBeenCalledTimes(count * 2);
+    if (count) {
+      expect(trackStudioEvent).toHaveBeenCalledWith("keyframe", { action: "add" });
+      expect(trackStudioEvent).toHaveBeenCalledWith("feature_used", {
+        feature: "gesture_recording",
+        surface: "preview",
+        method: inputMethod,
       });
-      return null;
     }
-    const root = mountReactHarness(<Probe />);
-    cleanup = () => act(() => root.unmount());
+  },
+);
 
-    act(() => captured.hook?.handleToggleRecording());
-    expect(gestureRecording.startRecording).not.toHaveBeenCalled();
-    expect(commitMutation).not.toHaveBeenCalled();
+it("keeps a pending recording isolated until its writer settles", async () => {
+  let release!: () => void;
+  const pending = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  const writer = vi.fn(
+    async (_mutation: Record<string, unknown>, options: CommitMutationOptions) => {
+      await pending;
+      options.onResult?.({ ok: true, changed: true });
+    },
+  );
+  const hook = mountRecording(writer);
+  act(() => hook().handleToggleRecording("keyboard"));
+  act(() => hook().handleToggleRecording());
+  await vi.waitFor(() => expect(writer).toHaveBeenCalledTimes(1));
+  act(() => hook().handleToggleRecording("button"));
+  expect(gestureRecording.startRecording).toHaveBeenCalledTimes(1);
+  await act(async () => {
+    release();
+    await vi.waitFor(() =>
+      expect(trackStudioEvent).toHaveBeenCalledWith("feature_used", {
+        feature: "gesture_recording",
+        surface: "preview",
+        method: "keyboard",
+      }),
+    );
+  });
+  expect(gestureRecording.clearSamples).toHaveBeenCalledTimes(1);
+  act(() => hook().handleToggleRecording("button"));
+  expect(gestureRecording.startRecording).toHaveBeenCalledTimes(2);
+});
+
+it("writes one recording to its original selection after selecting another source", async () => {
+  const original = {
+    id: "original-position",
+    targetSelector: "#card",
+    propertyGroup: "position",
+    method: "set",
+    properties: { x: 0, y: 0 },
+    resolvedStart: 0,
+    position: 0,
+    duration: 0,
+  } as GsapAnimation;
+  const writer = vi.fn(
+    async (
+      _mutation: Record<string, unknown>,
+      options: CommitMutationOptions,
+      _selection?: DomEditSelection,
+    ) => {
+      options.onResult?.({ ok: true, changed: true });
+    },
+  );
+  const hook = mountRecording(writer, [original]);
+  act(() => hook().handleToggleRecording("keyboard"));
+  const other = document.createElement("div");
+  other.id = "other";
+  hook.select(
+    { ...makeSelection(other), sourceFile: "other.html", compositionPath: "other.html" },
+    [],
+  );
+  await act(async () => {
+    hook().handleToggleRecording();
+    await vi.waitFor(() => expect(trackStudioEvent).toHaveBeenCalledTimes(2));
+  });
+  expect(writer).toHaveBeenCalledExactlyOnceWith(
+    expect.objectContaining({
+      type: "replace-with-keyframes",
+      animationId: "original-position",
+      targetSelector: "#card",
+    }),
+    expect.objectContaining({ keyframeAction: "add" }),
+    expect.objectContaining({
+      id: "card",
+      sourceFile: "index.html",
+      compositionPath: "index.html",
+    }),
+  );
+  expect(trackStudioEvent).toHaveBeenCalledWith("keyframe", { action: "add" });
+  expect(trackStudioEvent).toHaveBeenCalledWith("feature_used", {
+    feature: "gesture_recording",
+    surface: "preview",
+    method: "keyboard",
   });
 });