@hyperframes/studio 0.6.121 → 0.7.0

package/src/hooks/gsapShared.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect } from "vitest";
+import { parsePercentageKeyframes } from "./gsapShared";
+
+describe("parsePercentageKeyframes", () => {
+  it("parses the object/percentage form", () => {
+    const out = parsePercentageKeyframes({ "0%": { x: 0, y: 0 }, "100%": { x: 9, y: 4 } });
+    expect(out?.keyframes).toEqual([
+      { percentage: 0, properties: { x: 0, y: 0 } },
+      { percentage: 100, properties: { x: 9, y: 4 } },
+    ]);
+  });
+
+  it("parses GSAP array-form keyframes as evenly-distributed steps", () => {
+    // Regression: a multi-point shuttle path authored as `keyframes: [...]` used to
+    // read as null (no `N%` keys) → no motion path. Steps map to i/(n-1)*100%.
+    const out = parsePercentageKeyframes([
+      { x: 0, y: 0 },
+      { x: 520, y: 120 },
+      { x: 1040, y: 0 },
+      { x: 1480, y: 160 },
+    ] as unknown as Record<string, unknown>);
+    expect(out?.keyframes.map((k) => k.percentage)).toEqual([0, 33.3, 66.7, 100]);
+    expect(out?.keyframes[1]!.properties).toEqual({ x: 520, y: 120 });
+  });
+
+  it("strips a per-entry ease without shifting the even index-spacing of the others", () => {
+    // GSAP positions array keyframes by array index, so a `{ ease }` carried on an
+    // entry is a segment ease (skipped as a property) — it must not change where
+    // the surrounding keyframes land. 3 entries → 0 / 50 / 100, even though the
+    // middle entry also carries an ease.
+    const out = parsePercentageKeyframes([
+      { x: 0 },
+      { x: 100, ease: "power2.in" },
+      { x: 200 },
+    ] as unknown as Record<string, unknown>);
+    expect(out?.keyframes.map((k) => k.percentage)).toEqual([0, 50, 100]);
+    expect(out?.keyframes.map((k) => k.properties)).toEqual([{ x: 0 }, { x: 100 }, { x: 200 }]);
+  });
+
+  it("keeps even spacing when an interior array slot has no animatable prop", () => {
+    // A degenerate `{ ease }`-only slot contributes no output keyframe, but it is
+    // still an array slot GSAP allocates a position to — so the remaining entries
+    // keep their original i/(n-1) percentages (0 and 100 for a 3-slot array), not
+    // 0/100 collapsed onto a 2-entry spacing.
+    const out = parsePercentageKeyframes([
+      { x: 0 },
+      { ease: "power2.in" },
+      { x: 200 },
+    ] as unknown as Record<string, unknown>);
+    expect(out?.keyframes.map((k) => k.percentage)).toEqual([0, 100]);
+    expect(out?.keyframes.map((k) => k.properties)).toEqual([{ x: 0 }, { x: 200 }]);
+  });
+
+  it("returns null for keyframes with no positional/animatable props", () => {
+    expect(parsePercentageKeyframes([] as unknown as Record<string, unknown>)).toBeNull();
+    expect(parsePercentageKeyframes({})).toBeNull();
+  });
+});

package/src/hooks/gsapShared.ts

@@ -97,16 +97,6 @@ export function queryIframeElement(
   }
 }
 
-/** Safely access an iframe's contentDocument, returning null on cross-origin errors. */
-export function getIframeDocument(iframe: HTMLIFrameElement | null): Document | null {
-  if (!iframe) return null;
-  try {
-    return iframe.contentDocument;
-  } catch {
-    return null;
-  }
-}
-
 // ── Keyframe parsing ──────────────────────────────────────────────────────────
 
 export interface ParsedPercentageKeyframes {
@@ -125,6 +115,34 @@ export function parsePercentageKeyframes(
   const keyframes: ParsedPercentageKeyframes["keyframes"] = [];
   let easeEach: string | undefined;
 
+  // GSAP array-form keyframes — `keyframes: [{x,y}, {x,y}, ...]` — are spread
+  // evenly across the tween by default: GSAP gives each entry an equal share of
+  // the duration unless an entry carries its own `duration`/`delay`, which the
+  // studio never emits. So entry i of n maps to i/(n-1)*100% (n=4 → 0/33.3/66.7/100).
+  // Index spacing counts EVERY array slot, including a degenerate entry that
+  // contributes no animatable prop (it's still a slot GSAP allocates a position
+  // to), so dropping such an entry from the output below must NOT shift the others.
+  // A per-entry `ease` is a segment ease, not a keyframe value, so it's skipped as
+  // a property; there is no array-form `easeEach` (that's an object-form sibling key).
+  // (The object form further down uses explicit "0%" keys instead.) Without this
+  // branch, array-keyframed tweens (e.g. a multi-point shuttle) read as null → no
+  // motion path.
+  if (Array.isArray(kfObj)) {
+    const steps = kfObj as unknown[];
+    steps.forEach((entry, i) => {
+      if (!entry || typeof entry !== "object") return;
+      const percentage = steps.length > 1 ? Math.round((i / (steps.length - 1)) * 1000) / 10 : 0;
+      const properties: Record<string, number | string> = {};
+      for (const [pk, pv] of Object.entries(entry as Record<string, unknown>)) {
+        if (pk === "ease") continue;
+        if (typeof pv === "number") properties[pk] = Math.round(pv * 1000) / 1000;
+        else if (typeof pv === "string") properties[pk] = pv;
+      }
+      if (Object.keys(properties).length > 0) keyframes.push({ percentage, properties });
+    });
+    return keyframes.length > 0 ? { keyframes } : null;
+  }
+
   for (const [key, val] of Object.entries(kfObj)) {
     if (key === "easeEach") {
       if (typeof val === "string") easeEach = val;

package/src/hooks/gsapTargetCache.ts

@@ -1,5 +1,3 @@
-import { STUDIO_GSAP_DRAG_INTERCEPT_ENABLED } from "../components/editor/manualEditingAvailability";
-
 type TimelineLike = { getChildren?: (nested: boolean) => Array<{ targets?: () => Element[] }> };
 
 let _gsapCachedTimelines: Record<string, TimelineLike> | undefined;
@@ -50,7 +48,6 @@ export function isElementGsapTargeted(
   iframe: HTMLIFrameElement | null,
   element: HTMLElement,
 ): boolean {
-  if (!STUDIO_GSAP_DRAG_INTERCEPT_ENABLED) return false;
   const timelines = readTimelines(iframe);
   if (!timelines) return false;
 

package/src/hooks/useDomEditSession.ts

@@ -213,10 +213,8 @@ export function useDomEditSession({
     handleDomTextFieldStyleCommit,
     handleDomAddTextField,
     handleDomRemoveTextField,
-    handleDomPathOffsetCommit,
     handleDomGroupPathOffsetCommit,
     handleDomBoxSizeCommit,
-    handleDomRotationCommit,
     handleDomManualEditsReset,
     handleDomEditElementDelete,
     handleDomZIndexReorderCommit,
@@ -384,9 +382,7 @@ export function useDomEditSession({
     bumpGsapCache,
     makeFetchFallback,
     trackGsapInteractionFailure,
-    handleDomPathOffsetCommit,
     handleDomBoxSizeCommit,
-    handleDomRotationCommit,
     addGsapAnimation,
     convertToKeyframes,
     setArcPath,

package/src/hooks/useDomSelection.ts

@@ -4,7 +4,11 @@ import {
   getAllPreviewTargetsFromPointer,
   getPreviewTargetFromPointer,
 } from "../utils/studioPreviewHelpers";
-import { findMatchingTimelineElementId, type RightPanelTab } from "../utils/studioHelpers";
+import {
+  findMatchingTimelineElementId,
+  findTimelineIdByAncestor,
+  type RightPanelTab,
+} from "../utils/studioHelpers";
 import {
   domEditSelectionsTargetSame,
   domEditSelectionInGroup,
@@ -178,10 +182,13 @@ export function useDomSelection({
           setRightCollapsed(false);
           setRightPanelTab("design");
         }
-        const nextSelectedTimelineId = findMatchingTimelineElementId(
-          nextSelection,
-          timelineElements,
-        );
+        const nextSelectedTimelineId =
+          findMatchingTimelineElementId(nextSelection, timelineElements) ??
+          findTimelineIdByAncestor(
+            nextSelection.element,
+            timelineElements,
+            nextSelection.sourceFile || "index.html",
+          );
         setSelectedTimelineElementId(nextSelectedTimelineId);
         return;
       }

package/src/hooks/useEnableKeyframes.test.ts

@@ -0,0 +1,130 @@
+import { describe, expect, it } from "vitest";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import {
+  animatedProps,
+  buildExtendedKeyframes,
+  isPlayheadWithinTween,
+  resolveNewTweenRange,
+} from "./useEnableKeyframes";
+
+function anim(overrides: Partial<GsapAnimation>): GsapAnimation {
+  return {
+    id: "#el-to-0-position",
+    targetSelector: "#el",
+    method: "to",
+    position: 0,
+    properties: {},
+    ...overrides,
+  };
+}
+
+describe("resolveNewTweenRange", () => {
+  // Regression: "add a keyframe" must land at the PLAYHEAD. The runtime auto-stamps
+  // data-start="0" + data-duration=<rootDuration> on every GSAP element, so honoring
+  // data-start as authored timing put the keyframe at 0. Clamping the playhead into
+  // the element's range fixes it (auto-stamp's full range passes the playhead through).
+  it("anchors at the playhead through the auto-stamped full-composition range", () => {
+    // data-start="0", data-duration="14" (the auto-stamp), playhead 4.9 → 4.9
+    expect(resolveNewTweenRange("0", "14", 4.9)).toEqual({ start: 4.9, duration: 9.1 });
+  });
+
+  it("anchors at the playhead when the element has no authored range", () => {
+    expect(resolveNewTweenRange(undefined, undefined, 4)).toEqual({ start: 4, duration: 1 });
+    expect(resolveNewTweenRange(undefined, undefined, 6.123456).start).toBe(6.123);
+  });
+
+  it("never returns a negative start", () => {
+    expect(resolveNewTweenRange(undefined, undefined, -2).start).toBe(0);
+  });
+
+  it("clamps the playhead into a genuinely narrow authored clip", () => {
+    // clip [2.5, 8]: inside → playhead; before → start; after → end
+    expect(resolveNewTweenRange("2.5", "5.5", 4)).toEqual({ start: 4, duration: 4 });
+    expect(resolveNewTweenRange("2.5", "5.5", 1).start).toBe(2.5);
+    expect(resolveNewTweenRange("2.5", "5.5", 99).start).toBe(8);
+  });
+});
+
+describe("animatedProps", () => {
+  it("uses top-level properties when present (flat tween)", () => {
+    expect(animatedProps(anim({ properties: { x: -260 } }))).toEqual(["x"]);
+  });
+
+  it("derives props from keyframe stops when top-level properties is empty (array form)", () => {
+    // Regression: array-form `keyframes: [{x,y},…]` leaves `properties` empty, so
+    // add-keyframe read an empty prop list → empty position → silent no-op.
+    const a = anim({
+      properties: {},
+      keyframes: {
+        format: "object-array",
+        keyframes: [
+          { percentage: 0, properties: { x: 0, y: 0 } },
+          { percentage: 100, properties: { x: -460, y: -20 } },
+        ],
+      },
+    });
+    expect(animatedProps(a).sort()).toEqual(["x", "y"]);
+  });
+
+  it("falls back to x/y for a null anim or one with no resolvable props", () => {
+    expect(animatedProps(null)).toEqual(["x", "y"]);
+    expect(animatedProps(anim({ properties: {} }))).toEqual(["x", "y"]);
+  });
+});
+
+describe("isPlayheadWithinTween", () => {
+  const tween = anim({ position: 1.0, duration: 3.4 }); // range [1.0, 4.4]
+
+  it("is true inside the range (incl. boundaries)", () => {
+    expect(isPlayheadWithinTween(tween, 3.0)).toBe(true);
+    expect(isPlayheadWithinTween(tween, 1.0)).toBe(true);
+    expect(isPlayheadWithinTween(tween, 4.4)).toBe(true);
+  });
+
+  it("is false outside the tween range", () => {
+    expect(isPlayheadWithinTween(tween, 5.767)).toBe(false);
+    expect(isPlayheadWithinTween(tween, 0.5)).toBe(false);
+  });
+
+  it("does not block when the start can't be resolved", () => {
+    expect(isPlayheadWithinTween(anim({ position: "+=1" }), 99)).toBe(true);
+  });
+});
+
+describe("buildExtendedKeyframes", () => {
+  // puck-b: tween [1.0, 4.4], four evenly-distributed stops.
+  const kfAnim = anim({
+    position: 1.0,
+    duration: 3.4,
+    keyframes: {
+      format: "object-array",
+      keyframes: [
+        { percentage: 0, properties: { x: 0, y: 0 } },
+        { percentage: 33.3, properties: { x: -180, y: -60 } },
+        { percentage: 66.7, properties: { x: -320, y: 40 } },
+        { percentage: 100, properties: { x: -460, y: -20 } },
+      ],
+    },
+  });
+
+  it("extends the end and rescales existing stops to keep their absolute timing", () => {
+    const out = buildExtendedKeyframes(kfAnim, 5.767, { x: -460, y: -20 });
+    expect(out.position).toBe(1.0); // start unchanged
+    expect(out.duration).toBe(4.767); // grown to reach the playhead
+    // old end (abs 4.4) is no longer 100% — it slid back inside the longer range
+    const last = out.keyframes[out.keyframes.length - 1]!;
+    expect(last.percentage).toBe(100); // the new keyframe sits at the new end
+    expect(last.properties).toEqual({ x: -460, y: -20 });
+    expect(out.keyframes[0]!.percentage).toBe(0); // old start still anchors 0%
+    expect(out.keyframes.some((k) => k.percentage > 0 && k.percentage < 100)).toBe(true);
+  });
+
+  it("extends the start when the playhead precedes the tween", () => {
+    const out = buildExtendedKeyframes(kfAnim, 0, { x: 0, y: 0 });
+    expect(out.position).toBe(0); // start moved back to the playhead
+    expect(out.duration).toBe(4.4); // end (abs 4.4) unchanged
+    expect(out.keyframes[0]).toEqual({ percentage: 0, properties: { x: 0, y: 0 } });
+    // the old first stop (abs 1.0) is now partway in: 1.0 / 4.4 ≈ 22.7%
+    expect(out.keyframes[1]!.percentage).toBeCloseTo(22.7, 1);
+  });
+});