@hyperframes/studio 0.7.99 → 0.7.101

package/src/hooks/gsapResizeSweep.test.ts

@@ -0,0 +1,274 @@
+// @vitest-environment happy-dom
+/**
+ * Every shape of animated element a composition can hand the resize, swept.
+ *
+ * Both faults this branch fixes were found one composition at a time, which is
+ * a bad way to find the third. So this drives the real intercept across the
+ * cross-product of what an element's tweens can look like and holds every run
+ * to the two rules that were broken:
+ *
+ *   1. Never address an animation the source does not have. Sending a stale id
+ *      is what "animation not found" is, and it leaves the element unsavable.
+ *   2. Never leave a tween spanning two property groups. The parser classifies
+ *      such a tween as neither, so it loses its group suffix and its id along
+ *      with it, and every later edit has nothing to address.
+ *
+ * The server stand-in answers the way the real one does — an id it cannot find
+ * is a rejection — and applies what it is told, so a run that corrupts the
+ * animation list is caught by the next mutation in the same run rather than by
+ * a person noticing weeks later.
+ */
+import { afterEach, expect, it, vi } from "vitest";
+import { classifyTweenPropertyGroup } from "@hyperframes/core/gsap-parser";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
+import { usePlayerStore } from "../player/store/playerStore";
+import { tryGsapResizeIntercept } from "./gsapResizeIntercept";
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  usePlayerStore.setState({ currentTime: 0, activeKeyframePct: null });
+  document.body.innerHTML = "";
+});
+
+type Props = Record<string, number>;
+
+function tween(id: string, properties: Props, duration: number): GsapAnimation {
+  return {
+    id,
+    targetSelector: "#el",
+    propertyGroup: classifyTweenPropertyGroup(properties),
+    method: "to",
+    properties,
+    position: 0,
+    resolvedStart: 0,
+    duration,
+    ...(duration === 0 ? { extras: { immediateRender: "__raw:true" } } : {}),
+  } as unknown as GsapAnimation;
+}
+
+/** The dimensions an element's animations actually vary across. */
+const SCALE = {
+  none: null,
+  "instant hold": () => tween("#el-scale", { scale: 1.2 }, 0),
+  tween: () => tween("#el-scale", { scale: 1.2 }, 2),
+  longhands: () => tween("#el-scale", { scaleX: 1.2, scaleY: 1.1 }, 2),
+} as const;
+const SIZE = {
+  none: null,
+  "instant hold": () => tween("#el-size", { width: 300, height: 200 }, 0),
+  tween: () => tween("#el-size", { width: 300, height: 200 }, 2),
+} as const;
+const POSITION = {
+  none: null,
+  "static hold": () => tween("#el-position", { x: 40, y: 60 }, 0),
+  tween: () => tween("#el-position", { x: 40, y: 60 }, 2),
+} as const;
+const EXTRA = {
+  none: null,
+  // What a 3D card carries, and the shape that produced two same-group ids.
+  "3d and rotation": () => [
+    tween("#el-other", { rotationY: -540, rotationX: 720, _auto: 0 }, 0),
+    tween("#el-rotation", { rotation: 720 }, 0),
+    tween("#el-other-2", { z: 50 }, 0),
+  ],
+  // A tween that already spans two groups, which the resize has to split.
+  "a mixed tween": () => [tween("#el-mixed", { scale: 1.2, width: 300, height: 200 }, 0)],
+} as const;
+
+interface Recorded {
+  rejected: string[];
+  corrupted: string[];
+}
+
+/**
+ * The source, as the server sees it: a list of animations, a rejection for an
+ * id that is not in it, and the effect of each mutation applied.
+ */
+function fakeSource(initial: GsapAnimation[]) {
+  let current = initial;
+  const recorded: Recorded = { rejected: [], corrupted: [] };
+
+  const mergeInto = (id: string, properties: Props) => {
+    current = current.map((animation) => {
+      if (animation.id !== id) return animation;
+      const before = classifyTweenPropertyGroup(animation.properties ?? {});
+      const merged = { ...(animation.properties ?? {}), ...properties };
+      const after = classifyTweenPropertyGroup(merged);
+      // Mixing is only a fault when the resize CAUSED it. A tween that already
+      // spanned two groups is an input, and splitting it is the point.
+      if (before !== undefined && after === undefined) recorded.corrupted.push(id);
+      return { ...animation, properties: merged, propertyGroup: after } as GsapAnimation;
+    });
+  };
+
+  const split = (id: string) => {
+    const target = current.find((animation) => animation.id === id);
+    if (!target) return;
+    const byGroup = new Map<string, Props>();
+    for (const [key, value] of Object.entries(target.properties ?? {})) {
+      const group = classifyTweenPropertyGroup({ [key]: value as number }) ?? "other";
+      byGroup.set(group, { ...(byGroup.get(group) ?? {}), [key]: value as number });
+    }
+    current = [
+      ...current.filter((animation) => animation.id !== id),
+      ...[...byGroup].map(([group, properties]) =>
+        tween(`#el-split-${group}`, properties, target.duration ?? 0),
+      ),
+    ];
+  };
+
+  const apply = (mutation: Record<string, unknown>, id: string | undefined) => {
+    const properties = (mutation.properties ?? {}) as Props;
+    if (mutation.type === "split-into-property-groups") return id && split(id);
+    if (!id) {
+      if (mutation.type === "add")
+        current = [...current, tween(`#el-added-${current.length}`, properties, 0)];
+      return;
+    }
+    mergeInto(id, properties);
+    const framed = (mutation.keyframes as Array<{ properties: Props }> | undefined) ?? [];
+    for (const frame of framed) mergeInto(id, frame.properties);
+  };
+
+  const commitMutation = vi.fn(async (_selection: unknown, mutation: Record<string, unknown>) => {
+    const id = mutation.animationId as string | undefined;
+    if (id && !current.some((animation) => animation.id === id)) {
+      recorded.rejected.push(`${String(mutation.type)}:${id}`);
+      throw new Error("animation not found");
+    }
+    apply(mutation, id);
+  });
+
+  return { commitMutation, recorded, animations: () => current };
+}
+
+type Dimension = Array<[string, () => GsapAnimation[]]>;
+
+function dimension(
+  entries: Record<string, null | (() => GsapAnimation | GsapAnimation[])>,
+): Dimension {
+  return Object.entries(entries).map(([name, make]) => [
+    name,
+    () => {
+      if (!make) return [];
+      const made = make();
+      return Array.isArray(made) ? made : [made];
+    },
+  ]);
+}
+
+function buildCases() {
+  const dimensions = [dimension(SCALE), dimension(SIZE), dimension(POSITION), dimension(EXTRA)];
+  let combos: Array<Array<[string, () => GsapAnimation[]]>> = [[]];
+  for (const next of dimensions) {
+    combos = combos.flatMap((combo) => next.map((entry) => [...combo, entry]));
+  }
+  const labels = ["scale", "size", "position", "extra"];
+  return combos.map((combo) => ({
+    name: combo.map(([name], index) => `${labels[index]} ${name}`).join(" / "),
+    animations: combo.flatMap(([, make]) => make()),
+  }));
+}
+
+const CASES = buildCases();
+
+it(`sweeps ${CASES.length} animated shapes without a stale id or a mixed tween`, async () => {
+  const failures: string[] = [];
+
+  for (const testCase of CASES) {
+    document.body.innerHTML = "";
+    const el = document.createElement("div");
+    el.id = "el";
+    el.setAttribute("data-hf-studio-original-box-width", "630");
+    el.setAttribute("data-hf-studio-original-box-height", "408");
+    document.body.append(el);
+    usePlayerStore.setState({ currentTime: 0, activeKeyframePct: null });
+
+    const source = fakeSource(testCase.animations);
+    try {
+      await tryGsapResizeIntercept(
+        { id: "el", selector: "#el", element: el } as DomEditSelection,
+        { width: 326, height: 213 },
+        testCase.animations,
+        null,
+        source.commitMutation as never,
+        async () => source.animations(),
+      );
+    } catch (error) {
+      // A rejection is recorded below; anything else is worth reporting as-is.
+      if (!(error instanceof Error) || error.message !== "animation not found") {
+        failures.push(`${testCase.name} — threw ${String(error)}`);
+      }
+    }
+
+    if (source.recorded.rejected.length > 0) {
+      failures.push(`${testCase.name} — stale id: ${source.recorded.rejected.join(", ")}`);
+    }
+    if (source.recorded.corrupted.length > 0) {
+      failures.push(`${testCase.name} — mixed tween: ${source.recorded.corrupted.join(", ")}`);
+    }
+  }
+
+  expect(failures).toEqual([]);
+});
+
+/**
+ * Which tween a resize edits when the element has several in the same group.
+ *
+ * A composition animates the same property more than once — a scale-in early
+ * and a scale-out late — and the one the user means is the one under the
+ * playhead. Editing the wrong one changes a moment they are not looking at and
+ * leaves the moment they ARE looking at unchanged, which reads as "the resize
+ * did nothing".
+ */
+function scaleAt(id: string, position: number): GsapAnimation {
+  return {
+    ...tween(id, { scale: 1 }, 2),
+    position,
+    resolvedStart: position,
+    keyframes: {
+      keyframes: [
+        { percentage: 0, properties: { scale: 1 } },
+        { percentage: 100, properties: { scale: 1.4 } },
+      ],
+    },
+  } as unknown as GsapAnimation;
+}
+
+const PLAYHEADS: Array<[number, string]> = [
+  [0.5, "#el-early"],
+  [1.9, "#el-early"],
+  [3, "#el-early"],
+  [3.1, "#el-late"],
+  [4.5, "#el-late"],
+  [9, "#el-late"],
+];
+
+it.each(PLAYHEADS)("at t=%s edits the tween under the playhead (%s)", async (time, expected) => {
+  document.body.innerHTML = "";
+  const el = document.createElement("div");
+  el.id = "el";
+  el.setAttribute("data-hf-studio-original-box-width", "630");
+  el.setAttribute("data-hf-studio-original-box-height", "408");
+  document.body.append(el);
+  usePlayerStore.setState({ currentTime: time, activeKeyframePct: null });
+
+  const animations = [scaleAt("#el-early", 0), scaleAt("#el-late", 4)];
+  const commitMutation = vi.fn();
+  await tryGsapResizeIntercept(
+    { id: "el", selector: "#el", element: el } as DomEditSelection,
+    { width: 326, height: 213 },
+    animations,
+    null,
+    commitMutation as never,
+    async () => animations,
+  );
+
+  const touched = new Set(
+    commitMutation.mock.calls
+      .map((call) => (call[1] as { animationId?: string }).animationId)
+      .filter((id): id is string => id != null),
+  );
+  expect([...touched]).toEqual([expected]);
+});

package/src/hooks/useGsapAwareEditing.test.tsx

@@ -313,8 +313,8 @@ describe("useGsapAwareEditing anchored resize", () => {
     act(() => h.root.unmount());
   });
 
-  it("does not apply the anchor twice when scale route already settles the drop point", async () => {
-    mocks.resize.mockResolvedValue({ status: "persisted" });
+  it("does not apply the anchor twice when the resize already settled the drop point", async () => {
+    mocks.resize.mockResolvedValue({ status: "persisted", ownsDragOffset: true });
     const scale = { propertyGroup: "scale" } as GsapAnimation;
     const h = mountResizeHandler([scale]);
     await act(() => h.resize(h.selection, { width: 300, height: 200 }, { x: -50, y: -25 }));
@@ -322,4 +322,21 @@ describe("useGsapAwareEditing anchored resize", () => {
     expect(h.fallback).not.toHaveBeenCalled();
     act(() => h.root.unmount());
   });
+
+  /**
+   * The same element, and the resize says it did NOT settle the drop point.
+   *
+   * This is the shape that broke: an element whose scale is an instant hold has
+   * a scale-group tween and still commits width/height. Reading the tweens said
+   * "scale route, it settles its own position", so the offset was withheld,
+   * nobody wrote it, and the element snapped back on every drag.
+   */
+  it("applies the anchor when the resize leaves the drop point to the caller", async () => {
+    mocks.resize.mockResolvedValue({ status: "persisted" });
+    const scale = { propertyGroup: "scale" } as GsapAnimation;
+    const h = mountResizeHandler([scale]);
+    await act(() => h.resize(h.selection, { width: 300, height: 200 }, { x: -50, y: -25 }));
+    expect(mocks.drag).toHaveBeenCalledTimes(1);
+    act(() => h.root.unmount());
+  });
 });

package/src/hooks/useGsapAwareEditing.ts

@@ -258,13 +258,21 @@ export function useGsapAwareEditing({
                 makeFetchFallback(selection),
               );
               assertGsapEditPersisted(outcome);
+              // What the resize actually did, not what its animations suggest
+              // it would do. An element whose scale is an instant hold has a
+              // scale-group tween and still commits width/height, so guessing
+              // from the tweens withheld an offset nobody had written and the
+              // element snapped back to its authored position on every drag.
+              const ownsDragOffset =
+                outcome.status === "persisted" && outcome.ownsDragOffset === true;
               logResize("intercept-handled", {
                 scaleRoute,
-                willForwardOffset: !!(offset && !scaleRoute),
+                ownsDragOffset,
+                willForwardOffset: !!(offset && !ownsDragOffset),
               });
-              // Scale-route resize persists its residual position internally.
-              // Width/height persists the already-settled anchor through drag.
-              if (offset && !scaleRoute) {
+              // A resize that moved the element itself has already written
+              // where it landed. Everything else leaves the anchor to the drag.
+              if (offset && !ownsDragOffset) {
                 const dragOutcome = await tryGsapDragIntercept(
                   selection,
                   offset,
@@ -275,7 +283,7 @@ export function useGsapAwareEditing({
                 );
                 assertGsapEditPersisted(dragOutcome);
               }
-              logResizeSettle(selection.element, scaleRoute ? "gsap-scale" : "gsap-size");
+              logResizeSettle(selection.element, ownsDragOffset ? "gsap-scale" : "gsap-size");
               return;
             } catch (error) {
               trackGsapInteractionFailure(error, selection, "resize", "Resize animated layer");

package/src/hooks/useGsapTweenCache.ts

@@ -4,6 +4,7 @@ import { usePlayerStore } from "../player/store/playerStore";
 import { readRuntimeKeyframes, scanAllRuntimeKeyframes } from "./gsapRuntimeBridge";
 import {
   clearKeyframeCacheForElement,
+  elementCacheKeys,
   pruneKeyframeCacheToFiles,
   publishKeyframeCache,
   writeGsapAnimationsForElement,
@@ -302,8 +303,9 @@ export function useGsapAnimationsForElement(
       // scan already cached. Only clear when no source cached this element —
       // otherwise selecting it would wipe its diamonds.
       const { keyframeCache } = usePlayerStore.getState();
-      const hasCached =
-        keyframeCache.has(`${sourceFile}#${elementId}`) || keyframeCache.has(elementId);
+      const hasCached = elementCacheKeys(sourceFile, elementId).some((key) =>
+        keyframeCache.has(key),
+      );
       if (!hasCached) clearKeyframeCacheForElement(sourceFile, elementId);
       return;
     }
@@ -314,14 +316,16 @@ export function useGsapAnimationsForElement(
       ...(ease ? { ease } : {}),
       ...(easeEach ? { easeEach } : {}),
     };
-    // PropertyPanel reads the cache by bare elementId (without sourceFile
-    // prefix), so the same entry is written under the bare key for
-    // cross-component lookups. Both keys land in one publish: a reader that woke
-    // between two separate writes saw the prefixed key updated and the bare one
-    // still stale.
+    // elementCacheKeys owns the key-variant list every writer sets (prefixed,
+    // index.html fallback, bare id). Building it by hand here is what let this
+    // site drift: it omitted the fallback key, and it wrote the bare id without
+    // the string coercion that keeps prune from throwing on a non-string. All
+    // keys land in one publish: a reader that woke between two separate writes
+    // saw the prefixed key updated and the bare one still stale.
     publishKeyframeCache((draft) => {
-      draft.keyframeCache.set(`${sourceFile}#${elementId}`, merged);
-      draft.keyframeCache.set(elementId, merged);
+      for (const key of elementCacheKeys(sourceFile, elementId)) {
+        draft.keyframeCache.set(key, merged);
+      }
     });
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [elementId, sourceFile, animations, domClipChildrenKey]);
@@ -426,13 +430,8 @@ export function usePopulateKeyframeCacheForFile(
       // in between re-rendered against a cache only partly filled in.
       publishKeyframeCache((draft) => {
         for (const [id, data] of scanned) {
-          const cacheKey = `${sf}#${id}`;
-          const fallbackKey = `index.html#${id}`;
-          const alreadyCached =
-            draft.keyframeCache.has(cacheKey) ||
-            draft.keyframeCache.has(fallbackKey) ||
-            draft.keyframeCache.has(id);
-          if (alreadyCached) continue;
+          const keys = elementCacheKeys(sf, id);
+          if (keys.some((key) => draft.keyframeCache.has(key))) continue;
           // Skip position-only set tweens from runtime too, same filter as AST path
           const isPosOnly =
             data.keyframes.length === 1 &&
@@ -445,9 +444,7 @@ export function usePopulateKeyframeCacheForFile(
             keyframes: data.keyframes,
             ...(data.easeEach ? { easeEach: data.easeEach } : {}),
           };
-          draft.keyframeCache.set(cacheKey, entry);
-          if (sf !== "index.html") draft.keyframeCache.set(fallbackKey, entry);
-          draft.keyframeCache.set(id, entry);
+          for (const key of keys) draft.keyframeCache.set(key, entry);
         }
       });
       runtimeScanDoneRef.current = `kf-cache:${projectId}:${sf}:${version}`;

package/src/hooks/usePanelLayout.test.ts

@@ -60,6 +60,11 @@ function renderPanelLayout() {
   return renderPanelLayoutWith(usePanelLayout);
 }
 
+function resizeWindowTo(width: number) {
+  Object.defineProperty(window, "innerWidth", { configurable: true, value: width });
+  window.dispatchEvent(new Event("resize"));
+}
+
 describe("usePanelLayout — right inspector panes", () => {
   it("opens Design with the intended viewport-scaled panel widths", () => {
     const harness = renderPanelLayout();
@@ -160,6 +165,118 @@ describe("usePanelLayout — right inspector panes", () => {
     harness.unmount();
   });
 
+  it("caps a panel relative to the window instead of at a flat 600px", () => {
+    resizeWindowTo(700);
+    const harness = renderPanelLayout();
+    // The old flat cap let the inspector claim 600 of a 700px window.
+    expect(harness.getState().rightWidth).toBeLessThanOrEqual(280);
+    harness.unmount();
+  });
+
+  it("rails both panels once the window cannot fit them", () => {
+    resizeWindowTo(560);
+    const harness = renderPanelLayout();
+    expect(harness.getState()).toMatchObject({
+      effectiveLeftCollapsed: true,
+      effectiveRightCollapsed: true,
+      leftCollapsed: false,
+      rightCollapsed: false,
+    });
+    harness.unmount();
+  });
+
+  it("auto-collapse never writes the user's persisted or URL-synced intent", () => {
+    const harness = renderPanelLayout();
+    act(() => resizeWindowTo(560));
+
+    expect(harness.getState().effectiveLeftCollapsed).toBe(true);
+    // localStorage carries leftCollapsed; the shareable URL carries rightCollapsed.
+    // A ten-second window drag must rewrite neither.
+    expect(readStudioUiPreferences().leftCollapsed).toBeUndefined();
+    expect(harness.getState().leftCollapsed).toBe(false);
+    expect(harness.getState().rightCollapsed).toBe(false);
+    harness.unmount();
+  });
+
+  it("returns the user's own width when the window grows back", () => {
+    const harness = renderPanelLayout();
+    const wide = harness.getState().leftWidth;
+
+    act(() => resizeWindowTo(560));
+    expect(harness.getState().leftWidth).toBeLessThan(wide);
+
+    act(() => resizeWindowTo(1496));
+    expect(harness.getState().leftWidth).toBe(wide);
+    harness.unmount();
+  });
+
+  it("keeps an explicitly collapsed sidebar collapsed after a narrow trip", () => {
+    const harness = renderPanelLayout();
+    act(() => harness.getState().toggleLeftSidebar());
+    expect(readStudioUiPreferences().leftCollapsed).toBe(true);
+
+    act(() => resizeWindowTo(560));
+    act(() => resizeWindowTo(1496));
+
+    expect(harness.getState().effectiveLeftCollapsed).toBe(true);
+    harness.unmount();
+  });
+
+  it("lets the user reopen a panel the window auto-collapsed", () => {
+    const harness = renderPanelLayout();
+    act(() => resizeWindowTo(560));
+    expect(harness.getState().effectiveRightCollapsed).toBe(true);
+
+    // Without this the header Inspector button would be dead below 700px.
+    act(() => harness.getState().setRightCollapsed(false));
+    expect(harness.getState().effectiveRightCollapsed).toBe(false);
+    harness.unmount();
+  });
+
+  it("opens the sidebar when the rail's own button is clicked", () => {
+    const harness = renderPanelLayout();
+    act(() => resizeWindowTo(560));
+    expect(harness.getState().effectiveLeftCollapsed).toBe(true);
+
+    // Regression: the toggle used to flip stored INTENT, which was already
+    // false here, so the click persisted leftCollapsed=true and the rail stayed
+    // railed — a dead button that silently saved a collapse nobody asked for.
+    act(() => harness.getState().toggleLeftSidebar());
+
+    expect(harness.getState().effectiveLeftCollapsed).toBe(false);
+    expect(harness.getState().leftCollapsed).toBe(false);
+    expect(readStudioUiPreferences().leftCollapsed).toBe(false);
+    // And it gets a real width: rendering an expanded sidebar at the 42px rail
+    // width would squash its own content. Only a real-UI click caught this.
+    expect(harness.getState().leftWidth).toBeGreaterThanOrEqual(200);
+    harness.unmount();
+  });
+
+  it("closes the sidebar again on the next click", () => {
+    const harness = renderPanelLayout();
+    act(() => resizeWindowTo(560));
+    act(() => harness.getState().toggleLeftSidebar());
+    act(() => harness.getState().toggleLeftSidebar());
+
+    expect(harness.getState().effectiveLeftCollapsed).toBe(true);
+    expect(readStudioUiPreferences().leftCollapsed).toBe(true);
+    harness.unmount();
+  });
+
+  it("forgets that reopen once the window is wide again", () => {
+    const harness = renderPanelLayout();
+    act(() => resizeWindowTo(560));
+    act(() => harness.getState().setRightCollapsed(false));
+    expect(harness.getState().effectiveRightCollapsed).toBe(false);
+
+    // Widening past the threshold clears the override, so a later narrow trip
+    // rails again rather than staying open forever off one old click.
+    act(() => resizeWindowTo(1496));
+    act(() => resizeWindowTo(560));
+    expect(harness.getState().effectiveRightCollapsed).toBe(true);
+    harness.unmount();
+  });
+
   it("setRightPanelTab is flat-aware: exclusivity holds for callers other than a direct in-panel tab click", async () => {
     vi.resetModules();
     vi.doMock("../components/editor/manualEditingAvailability", async () => {