@hyperframes/studio 0.8.114 → 0.8.116

package/src/hooks/useGsapKeyframeOps.sdkUsage.test.tsx

@@ -0,0 +1,114 @@
+// @vitest-environment happy-dom
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { useGsapKeyframeOps } from "./useGsapKeyframeOps";
+import type { CutoverResult } from "../utils/sdkCutover";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import { trackStudioEvent } from "../utils/studioTelemetry";
+
+const sdkWrite = vi.hoisted(() => vi.fn<(...args: unknown[]) => Promise<CutoverResult>>());
+vi.mock("../utils/sdkCutover", async (original) => ({
+  ...(await original<typeof import("../utils/sdkCutover")>()),
+  sdkGsapKeyframePersist: sdkWrite,
+  sdkGsapConvertToKeyframesPersist: sdkWrite,
+  sdkGsapRemoveAllKeyframesPersist: sdkWrite,
+}));
+vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
+type Params = Parameters<typeof useGsapKeyframeOps>[0];
+let root: Root;
+function mount() {
+  let api: ReturnType<typeof useGsapKeyframeOps> | undefined;
+  const legacy = vi.fn(async () => undefined);
+  function Probe() {
+    api = useGsapKeyframeOps({
+      activeCompPath: "index.html",
+      commitMutation: legacy,
+      commitMutationSafely: legacy,
+      trackGsapSaveFailure: vi.fn(),
+      sdkSession: {} as NonNullable<Params["sdkSession"]>,
+      sdkDeps: {
+        editHistory: { recordEdit: vi.fn(async () => undefined) },
+        writeProjectFile: vi.fn(async () => undefined),
+        reloadPreview: vi.fn(),
+      },
+    });
+    return null;
+  }
+  root = createRoot(document.createElement("div"));
+  act(() => root.render(<Probe />));
+  if (!api) throw new Error("hook did not mount");
+  return { api, legacy };
+}
+const selection = { id: "private-target", sourceFile: "private.html" } as DomEditSelection;
+beforeEach(() => {
+  vi.clearAllMocks();
+  sdkWrite.mockResolvedValue({
+    status: "committed",
+    version: "v2",
+    before: "before",
+    after: "after",
+  });
+});
+afterEach(() => act(() => root.unmount()));
+describe("SDK keyframe usage", () => {
+  it.each(["add", "convert", "remove_all", "reset"] as const)(
+    "counts a changed committed %s operation once",
+    async (action) => {
+      const { api, legacy } = mount();
+      await act(async () => {
+        if (action === "add")
+          await api.addKeyframeBatch(selection, "private-animation", 50, { x: 12, y: 4 });
+        else if (action === "convert") await api.convertToKeyframes(selection, "private-animation");
+        else await api.removeAllKeyframes(selection, "private-animation", action);
+      });
+      expect(legacy).not.toHaveBeenCalled();
+      expect(trackStudioEvent).toHaveBeenCalledExactlyOnceWith("keyframe", { action });
+    },
+  );
+  it("preserves property metadata on a single-property SDK add", async () => {
+    const { api } = mount();
+    await act(async () => api.addKeyframe(selection, "private-animation", 50, "x", 12));
+    expect(trackStudioEvent).toHaveBeenCalledExactlyOnceWith("keyframe", {
+      action: "add",
+      property: "x",
+    });
+  });
+  it("does not count unchanged SDK source", async () => {
+    sdkWrite.mockResolvedValue({
+      status: "committed",
+      version: "v2",
+      before: "same",
+      after: "same",
+    });
+    const { api } = mount();
+    await api.addKeyframeBatch(selection, "private-animation", 50, { x: 12 });
+    expect(await api.removeAllKeyframes(selection, "private-animation")).toBe(false);
+    expect(trackStudioEvent).not.toHaveBeenCalled();
+  });
+  it("honors intermediate-write suppression in SDK paths", async () => {
+    const { api } = mount();
+    await api.convertToKeyframes(selection, "private-animation", undefined, undefined, {
+      keyframeTelemetry: false,
+    });
+    await api.addKeyframeBatch(
+      selection,
+      "private-animation",
+      50,
+      { x: 12 },
+      { keyframeTelemetry: false },
+    );
+    await api.removeAllKeyframes(selection, "private-animation", "remove_all", false);
+    expect(trackStudioEvent).not.toHaveBeenCalled();
+  });
+  it("does not fall back or count after a failed SDK write", async () => {
+    sdkWrite.mockResolvedValue({ status: "failed", error: new Error("refused") });
+    const { api, legacy } = mount();
+    await expect(
+      api.addKeyframeBatch(selection, "private-animation", 50, { x: 12 }),
+    ).rejects.toThrow("refused");
+    expect(legacy).not.toHaveBeenCalled();
+    expect(trackStudioEvent).not.toHaveBeenCalled();
+  });
+});

package/src/hooks/useGsapKeyframeOps.ts

@@ -1,3 +1,4 @@
+import { trackKeyframeUsage } from "../utils/keyframeUsage";
 // fallow-ignore-file code-duplication
 // Add/remove operation-family transaction shapes stay parallel until SDK graduation.
 import { useCallback } from "react";
@@ -139,10 +140,14 @@ export function useGsapKeyframeOps({
                 coalesceKey: `gsap:${animationId}:kf:${percentage}`,
               },
             );
-            if (cutoverCommittedOrThrow(handled)) return;
+            if (cutoverCommittedOrThrow(handled)) {
+              if (handled.before !== handled.after) trackKeyframeUsage("add", property);
+              return;
+            }
           }
           await commitMutation(selection, mutation, {
             label: `Add keyframe at ${percentage}%`,
+            keyframeProperty: property,
             softReload: true,
           });
         },
@@ -172,7 +177,11 @@ export function useGsapKeyframeOps({
           sdkDeps,
           toSdkPersistOptions(`Add keyframe at ${percentage}%`, commitOverrides),
         );
-        if (cutoverCommittedOrThrow(handled)) return;
+        if (cutoverCommittedOrThrow(handled)) {
+          if (handled.before !== handled.after && commitOverrides?.keyframeTelemetry !== false)
+            trackKeyframeUsage("add");
+          return;
+        }
       }
       return commitMutation(
         selection,
@@ -319,7 +328,11 @@ export function useGsapKeyframeOps({
           sdkDeps,
           toSdkPersistOptions("Convert to keyframes", commitOverrides),
         );
-        if (cutoverCommittedOrThrow(handled)) return;
+        if (cutoverCommittedOrThrow(handled)) {
+          if (handled.before !== handled.after && commitOverrides.keyframeTelemetry !== false)
+            trackKeyframeUsage("convert");
+          return;
+        }
       }
       return commitMutation(
         selection,
@@ -333,11 +346,19 @@ export function useGsapKeyframeOps({
   );
 
   const removeAllKeyframes = useCallback(
-    async (selection: DomEditSelection, animationId: string) => {
+    async (
+      selection: DomEditSelection,
+      animationId: string,
+      action: "remove_all" | "reset" = "remove_all",
+      telemetry = true,
+    ): Promise<boolean> => {
       const targetPath = selection.sourceFile || activeCompPath || "index.html";
       // A class/descendant selector can resolve a live element whose selection
       // deliberately has no id. The cache is still keyed by that DOM id.
-      const cacheElementId = selection.id || selection.element?.id;
+      const clearCache = () => {
+        const cacheElementId = selection.id || selection.element?.id;
+        if (cacheElementId) clearKeyframeCacheForElement(targetPath, cacheElementId);
+      };
       if (sdkSession && sdkDeps) {
         const handled = await sdkGsapRemoveAllKeyframesPersist(
           targetPath,
@@ -347,26 +368,31 @@ export function useGsapKeyframeOps({
           { label: "Remove all keyframes" },
         );
         if (cutoverCommittedOrThrow(handled)) {
-          if (cacheElementId) clearKeyframeCacheForElement(targetPath, cacheElementId);
-          return;
+          clearCache();
+          const changed = handled.before !== handled.after;
+          if (changed && telemetry) trackKeyframeUsage(action);
+          return changed;
         }
       }
+      let changed = false;
       await commitMutationSafely(
         selection,
         { type: "remove-all-keyframes", animationId },
         {
           label: "Remove all keyframes",
+          keyframeAction: action,
+          keyframeTelemetry: telemetry,
           softReload: true,
           // The committed result is the single success boundary: clearing
           // before it makes failed saves lie, while waiting for the reload leaves
           // stale diamonds visible during the source round-trip.
           onResult: (result) => {
-            if (result.changed !== false && cacheElementId) {
-              clearKeyframeCacheForElement(targetPath, cacheElementId);
-            }
+            changed = result.ok && result.changed === true;
+            if (changed) clearCache();
           },
         },
       );
+      return changed;
     },
     [commitMutationSafely, activeCompPath, sdkSession, sdkDeps],
   );

package/src/hooks/useGsapScriptCommits.test.tsx

@@ -590,6 +590,63 @@ describe("runCommit — instantPatch wiring", () => {
     vi.unstubAllGlobals();
   });
 
+  it.each([
+    ["add-keyframe", "add"],
+    ["add-with-keyframes", "add"],
+    ["convert-to-keyframes", "convert"],
+    ["remove-all-keyframes", "remove_all"],
+  ])("counts %s only after a changed durable write", async (type, action) => {
+    mockFetchResult();
+    const deps = renderCommitHook();
+    await deps.api.commitMutation(
+      selection,
+      { type, properties: { text: "private-content" } },
+      { label: "Edit" },
+    );
+    expect(trackStudioEvent.mock.calls.filter(([event]) => event === "keyframe")).toEqual([
+      ["keyframe", { action }],
+    ]);
+  });
+
+  it("counts reset with its explicit action and suppresses intermediate writes", async () => {
+    mockFetchResult();
+    const deps = renderCommitHook();
+    await deps.api.commitMutation(
+      selection,
+      { type: "convert-to-keyframes" },
+      { label: "Convert", keyframeTelemetry: false },
+    );
+    await deps.api.commitMutation(
+      selection,
+      { type: "remove-all-keyframes" },
+      { label: "Reset", keyframeAction: "reset" },
+    );
+    expect(trackStudioEvent.mock.calls.filter(([event]) => event === "keyframe")).toEqual([
+      ["keyframe", { action: "reset" }],
+    ]);
+  });
+
+  it("does not count a successful unchanged keyframe write", async () => {
+    mockFetchResult({ changed: false });
+    const deps = renderCommitHook();
+    await deps.api.commitMutation(selection, { type: "add-keyframe" }, { label: "Add" });
+    expect(trackStudioEvent.mock.calls.filter(([event]) => event === "keyframe")).toEqual([]);
+  });
+
+  it("does not count a failed write that skipReload suppresses", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => ({ ok: false, status: 500 })),
+    );
+    const deps = renderCommitHook();
+    await deps.api.commitMutation(
+      selection,
+      { type: "add-keyframe" },
+      { label: "Add", skipReload: true },
+    );
+    expect(trackStudioEvent.mock.calls.filter(([event]) => event === "keyframe")).toEqual([]);
+  });
+
   const NESTED_SCRIPT = 'window.__timelines["root"] = tl;';
   const SUB = `<template><div data-composition-id="sub"><div id="nwid" style="left: 40px"></div></div></template>`;
 
@@ -641,7 +698,9 @@ describe("runCommit — instantPatch wiring", () => {
       await deps.api.commitMutation(selection, { x: 10 }, { label: "drag", softReload: true });
     });
 
-    expect(fetch).toHaveBeenCalledWith(expect.stringContaining("/files/compositions%2Fsub.html"));
+    expect(fetch).toHaveBeenCalledWith(expect.stringContaining("/files/compositions%2Fsub.html"), {
+      credentials: "omit",
+    });
     expect(applySoftReload).toHaveBeenCalledWith(
       expect.anything(),
       NESTED_SCRIPT,

package/src/hooks/useGsapScriptCommits.ts

@@ -11,6 +11,7 @@ import {
 } from "../utils/gsapSoftReload";
 import type { SoftReloadResult } from "../utils/gsapSoftReload";
 import { trackStudioEvent } from "../utils/studioTelemetry";
+import { trackKeyframeCommit } from "../utils/keyframeUsage";
 import { serializeStudioFileMutation } from "../utils/studioFileMutationCoordinator";
 import { trackedStudioEdit } from "../utils/studioPendingEdits";
 import {
@@ -27,12 +28,13 @@ import {
   formatGsapMutationRejectionToast,
   readJsonResponseBody,
 } from "./gsapScriptCommitHelpers";
-import type {
-  CommitMutation,
-  CommitMutationCall,
-  CommitMutationOptions,
-  GsapScriptCommitsParams,
-  MutationResult,
+import {
+  gsapWriteFile,
+  type CommitMutation,
+  type CommitMutationCall,
+  type CommitMutationOptions,
+  type GsapScriptCommitsParams,
+  type MutationResult,
 } from "./gsapScriptCommitTypes";
 import { useGsapAnimationOps } from "./useGsapAnimationOps";
 import { useGsapArcPathOps } from "./useGsapArcPathOps";
@@ -43,13 +45,14 @@ import {
   useSafeGsapCommitMutation,
 } from "./useSafeGsapCommitMutation";
 import { studioWriteHeaders } from "../utils/studioFileVersion";
+import { studioApiFetch } from "../utils/studioApiFetch";
 
 async function mutateGsapScript(
   projectId: string,
   sourceFile: string,
   mutation: Record<string, unknown>,
 ): Promise<MutationResult> {
-  const res = await fetch(
+  const res = await studioApiFetch(
     `/api/projects/${encodeURIComponent(projectId)}/gsap-mutations/${encodeURIComponent(sourceFile)}`,
     {
       method: "POST",
@@ -68,7 +71,7 @@ async function mutateGsapScriptBatch(
   sourceFile: string,
   mutations: Record<string, unknown>[],
 ): Promise<MutationResult> {
-  const res = await fetch(
+  const res = await studioApiFetch(
     `/api/projects/${encodeURIComponent(projectId)}/gsap-mutations-batch/${encodeURIComponent(sourceFile)}`,
     {
       method: "POST",
@@ -391,6 +394,7 @@ export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIfra
       mutateGsapScript(pid, targetPath, mutation),
     );
     if (!result) return;
+    trackKeyframeCommit([mutation], result, options);
     options.onResult?.(result);
     await finalizeSuccessfulMutation(pid, compositionPath, selection, mutation, targetPath, result, options);
   }, [showToast, finalizeSuccessfulMutation]);
@@ -404,6 +408,7 @@ export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIfra
       mutateGsapScriptBatch(pid, targetPath, mutations),
     );
     if (!result) return;
+    trackKeyframeCommit(mutations, result, options, calls.map((call) => call.options));
     options.onResult?.(result);
     // 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.
@@ -439,14 +444,14 @@ export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIfra
     };
     const commit: CommitMutation = trackedStudioEdit((selection, mutation, options) => {
       if (!activeProjectId) return Promise.resolve();
-      const file = selection.sourceFile || activeCompPath || "index.html";
+      const file = gsapWriteFile(selection, activeCompPath);
       return serializeCommit(file, options.serializeKey, () =>
         runCommit(activeProjectId, activeCompPath, file, selection, mutation, options),
       );
     }) as CommitMutation;
     commit.batch = trackedStudioEdit((calls: CommitMutationCall[], options: CommitMutationOptions) => {
       if (!activeProjectId) return Promise.resolve();
-      const file = calls[0]?.selection.sourceFile || activeCompPath || "index.html";
+      const file = calls[0] ? gsapWriteFile(calls[0].selection, activeCompPath) : "index.html";
       return serializeCommit(file, options.serializeKey, () =>
         runBatchCommit(activeProjectId, activeCompPath, file, calls, options),
       );

package/src/hooks/useGsapSelectionHandlers.test.tsx

@@ -42,7 +42,7 @@ function makeParams(overrides: Partial<Params> = {}): Params {
     moveKeyframe: vi.fn().mockResolvedValue(true),
     resizeKeyframedTween: vi.fn().mockResolvedValue(true),
     convertToKeyframes: resolved(),
-    removeAllKeyframes: resolved(),
+    removeAllKeyframes: vi.fn().mockResolvedValue(true),
     handleDomManualEditsReset: vi.fn(),
     selectedGsapAnimations: [],
     showToast: vi.fn(),

package/src/hooks/useGsapSelectionHandlers.ts

@@ -109,9 +109,16 @@ export function useGsapSelectionHandlers({
     duration?: number,
     commitOverrides?: Partial<CommitMutationOptions>,
   ) => Promise<void>;
-  removeAllKeyframes: (sel: DomEditSelection, animId: string) => Promise<void>;
+  removeAllKeyframes: (
+    sel: DomEditSelection,
+    animId: string,
+    action?: "remove_all" | "reset",
+    telemetry?: boolean,
+  ) => Promise<boolean>;
 
-  handleDomManualEditsReset: (sel: DomEditSelection) => Promise<void>;
+  handleDomManualEditsReset: (
+    sel: DomEditSelection,
+  ) => Promise<void | import("./domEditCommitTypes").DomEditPersistOutcome>;
   selectedGsapAnimations: GsapAnimation[];
   showToast: (message: string, tone?: "error" | "info") => void;
 }) {
@@ -323,7 +330,6 @@ export function useGsapSelectionHandlers({
     ) => {
       const sel = resolveWriteSelection(selectionOverride);
       if (!sel) return;
-      trackStudioEvent("keyframe", { action: "add", property });
       addKeyframe(sel, animId, percentage, property, value);
     },
     [resolveWriteSelection, addKeyframe],
@@ -441,31 +447,31 @@ export function useGsapSelectionHandlers({
   );
 
   const handleGsapRemoveAllKeyframes = useCallback(
-    (animId: string, selectionOverride?: DomEditSelection | null) => {
+    (animId: string, selectionOverride?: DomEditSelection | null, telemetry = true) => {
       const selection = resolveWriteSelection(selectionOverride);
       if (!selection) return Promise.resolve(false);
-      return observeGsapMutation(
-        removeAllKeyframes(selection, animId),
-        selection,
-        "remove-all-keyframes",
-        "Remove all keyframes",
-      );
+      return removeAllKeyframes(selection, animId, "remove_all", telemetry).catch((error) => {
+        trackGsapHandlerFailure(error, selection, "remove-all-keyframes", "Remove all keyframes");
+        return false;
+      });
     },
-    [resolveWriteSelection, observeGsapMutation, removeAllKeyframes],
+    [resolveWriteSelection, trackGsapHandlerFailure, removeAllKeyframes],
   );
 
   const handleResetSelectedElementKeyframes = useCallback((): boolean => {
     if (!domEditSelection) return false;
     const withKeyframes = selectedGsapAnimations.find((a) => a.keyframes);
     if (!withKeyframes) return false;
-    observeGsapMutation(
-      removeAllKeyframes(domEditSelection, withKeyframes.id),
-      domEditSelection,
-      "remove-all-keyframes",
-      "Remove all keyframes",
-    );
+    void removeAllKeyframes(domEditSelection, withKeyframes.id, "reset").catch((error) => {
+      trackGsapHandlerFailure(
+        error,
+        domEditSelection,
+        "remove-all-keyframes",
+        "Remove all keyframes",
+      );
+    });
     return true;
-  }, [domEditSelection, observeGsapMutation, removeAllKeyframes, selectedGsapAnimations]);
+  }, [domEditSelection, trackGsapHandlerFailure, removeAllKeyframes, selectedGsapAnimations]);
 
   return {
     handleGsapUpdateProperty,

package/src/hooks/useGsapTweenCache.ts

@@ -290,17 +290,15 @@ export function usePopulateKeyframeCacheForFile(
   const domClipChildrenKey = usePlayerStore((s) =>
     s.domClipChildren.map((c) => `${c.id}<${c.hostId}`).join("|"),
   );
-  const lastFetchKeyRef = useRef("");
+  const loadedRef = useRef<{ dataKey: string; files: Set<string> }>({
+    dataKey: "",
+    files: new Set(),
+  });
 
   const runtimeScanDoneRef = useRef("");
-  const astFetchDoneRef = useRef("");
 
   useEffect(() => {
-    const fetchKey = `kf-cache:${projectId}:${sourceFile}:${version}:${elementCount}:${domClipChildrenKey}:${compositionSrcKey}`;
-    if (fetchKey === lastFetchKeyRef.current) return;
-    lastFetchKeyRef.current = fetchKey;
-    runtimeScanDoneRef.current = "";
-    astFetchDoneRef.current = "";
+    const dataKey = `kf-cache:${projectId}:${version}:${elementCount}:${domClipChildrenKey}:${compositionSrcKey}`;
     if (!projectId) return;
 
     // The active file first: it owns the selection, and each file clears only
@@ -309,13 +307,21 @@ export function usePopulateKeyframeCacheForFile(
     const files = Array.from(
       new Set([sourceFile, ...(compositionSrcKey ? compositionSrcKey.split("|") : [])]),
     );
-    const doc = iframeRef?.current?.contentDocument;
+    const sameData = loadedRef.current.dataKey === dataKey;
+    const stale = sameData ? files.filter((sf) => !loadedRef.current.files.has(sf)) : files;
+    const covered = sameData ? new Set([...loadedRef.current.files, ...files]) : new Set(files);
+    loadedRef.current = { dataKey, files: covered };
     // Everything the previous scan cached for a file this one no longer covers
     // (the composition just switched away from) has no owner left to clear it.
-    pruneKeyframeCacheToFiles(files);
-    Promise.all(files.map((sf) => populateKeyframeCacheFromAst(projectId, sf, doc))).then(() => {
-      astFetchDoneRef.current = fetchKey;
-    });
+    if (!sameData) pruneKeyframeCacheToFiles(files);
+    if (stale.length === 0) return;
+    runtimeScanDoneRef.current = "";
+    const doc = iframeRef?.current?.contentDocument;
+    for (const sf of stale) {
+      void populateKeyframeCacheFromAst(projectId, sf, doc).then((loaded) => {
+        if (!loaded && loadedRef.current.dataKey === dataKey) loadedRef.current.files.delete(sf);
+      });
+    }
     // elementCount is in the deps because new timeline elements (e.g. after a
     // sub-composition expand) need their keyframe cache populated immediately;
     // without it the effect won't re-run when elements appear/disappear.

package/src/hooks/useLintModal.ts

@@ -3,6 +3,7 @@ import { useState, useCallback, useEffect, useRef, useMemo } from "react";
 import type { LintFinding } from "../components/LintModal";
 import { usePlayerStore } from "../player";
 import { isPreviewBooted, whenPreviewBooted } from "../player/store/playerStore";
+import { studioApiFetch } from "../utils/studioApiFetch";
 
 interface RawFinding {
   severity?: string;
@@ -25,7 +26,7 @@ function parseFinding(f: RawFinding): LintFinding & { elementId?: string; file?:
 }
 
 async function fetchLintFindings(projectId: string) {
-  const res = await fetch(buildProjectApiPath(projectId, `/lint`));
+  const res = await studioApiFetch(buildProjectApiPath(projectId, `/lint`));
   const data = await res.json();
   return ((data.findings ?? []) as RawFinding[]).map(parseFinding);
 }