@hyperframes/studio 0.7.7 → 0.7.9

package/src/hooks/useAnimatedPropertyCommit.ts

@@ -1,10 +1,11 @@
 /**
  * Unified helper for committing any GSAP property value from the design panel.
  *
- * Handles three cases:
- * 1. Animation with keyframes → add-keyframe at current percentage
- * 2. Flat animation (no keyframes) → convert to keyframes, then add-keyframe
- * 3. No animation → create tl.to(), convert to keyframes, then add-keyframe
+ * Routing depends on whether the element is animated (has keyframes on any tween):
+ * - Animated → write the value into a keyframe at the current playhead (convert a
+ *   flat tween first if needed). An existing static `set` auto-converts to keyframes.
+ * - Static (no keyframes anywhere) → persist as a `tl.set`, NEVER keyframes — same
+ *   as manual drag / resize / rotate. Updates an existing set or creates one.
  */
 import { useCallback } from "react";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
@@ -12,6 +13,7 @@ import { classifyPropertyGroup } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { usePlayerStore } from "../player/store/playerStore";
 import { readAllAnimatedProperties, readGsapProperty } from "./gsapRuntimeBridge";
+import type { SetPatchProps } from "./gsapRuntimePatch";
 import { selectorFromSelection, computeElementPercentage } from "./gsapShared";
 
 interface CommitAnimatedPropertyDeps {
@@ -47,6 +49,7 @@ function pickBestAnimation(
   const currentTime = usePlayerStore.getState().currentTime;
   const targetGroup = property ? classifyPropertyGroup(property) : undefined;
 
+  // fallow-ignore-next-line complexity
   const scored = animations.map((a) => {
     let score = 0;
     if (targetGroup && a.propertyGroup === targetGroup) score += 20;
@@ -62,96 +65,271 @@ function pickBestAnimation(
   return scored[0]?.anim;
 }
 
+/**
+ * Auto-keyframe a just-updated static `set`: if the element is already animated
+ * (its clip carries keyframes on another tween), convert the set to keyframes so
+ * subsequent edits at other playheads interpolate — matching the drag / resize /
+ * rotate UX. Purely static elements (no other keyframes) are left as a set.
+ */
+async function maybeAutoKeyframeSet(
+  selection: DomEditSelection,
+  setAnim: GsapAnimation,
+  animations: GsapAnimation[],
+  commit: NonNullable<CommitAnimatedPropertyDeps["gsapCommitMutation"]>,
+): Promise<void> {
+  const animatedTween = animations.find((a) => a.keyframes && a.id !== setAnim.id);
+  if (!animatedTween) return;
+  await commit(
+    selection,
+    {
+      type: "convert-to-keyframes",
+      animationId: setAnim.id,
+      duration: animatedTween.duration ?? 1,
+    },
+    { label: "Keyframe 3D transform", softReload: true },
+  );
+}
+
+type Commit = NonNullable<CommitAnimatedPropertyDeps["gsapCommitMutation"]>;
+
+/** Merge ALL props into the static `set` in ONE commit (value-only, instant), then
+ *  auto-keyframe. One mutation — a per-property loop would shift the set's
+ *  group-derived id mid-way (e.g. reset adding `scale` to a rotation set), 404-ing
+ *  the next update. */
+async function commitSetProps(
+  selection: DomEditSelection,
+  setAnim: GsapAnimation,
+  propEntries: [string, number | string][],
+  selector: string | null,
+  animations: GsapAnimation[],
+  commit: Commit,
+): Promise<void> {
+  const properties = Object.fromEntries(propEntries);
+  const numericProps: SetPatchProps = {};
+  for (const [k, v] of propEntries) {
+    if (typeof v === "number") numericProps[k as keyof SetPatchProps] = v;
+  }
+  const instantPatch =
+    selector && Object.keys(numericProps).length > 0
+      ? {
+          selector,
+          change: {
+            kind: (setAnim.global ? "global-set" : "set") as "set" | "global-set",
+            props: numericProps,
+          },
+        }
+      : undefined;
+  await commit(
+    selection,
+    { type: "update-properties", animationId: setAnim.id, properties },
+    { label: "Set 3D transform", softReload: true, ...(instantPatch ? { instantPatch } : {}) },
+  );
+  await maybeAutoKeyframeSet(selection, setAnim, animations, commit);
+}
+
+/**
+ * Static element (no keyframes on ANY of its tweens): persist the 3D props as a
+ * `tl.set` — NEVER keyframes. Mirrors manual drag / resize / rotate, which `tl.set`
+ * a static element instead of animating it. Updates an existing `set` in place, or
+ * creates a dedicated `set` at position 0 when the element has none.
+ */
+async function commitStaticSet(
+  selection: DomEditSelection,
+  propEntries: [string, number | string][],
+  selector: string | null,
+  animations: GsapAnimation[],
+  commit: Commit,
+): Promise<void> {
+  if (!selector) return;
+  // Update an existing `set` in ONE batched commit — NEVER a flat `to`/`from`. A
+  // set's id is GROUP-derived, so a per-prop loop shifts it the instant a new-group
+  // prop lands (e.g. `scale` onto a rotation set), 404-ing the next prop; commitSetProps
+  // sends them together. A static element with no set gets a dedicated `set` carrying
+  // ALL props in ONE `add`.
+  const existingSet = animations.find((a) => a.method === "set" && a.targetSelector === selector);
+  if (existingSet) {
+    await commitSetProps(selection, existingSet, propEntries, selector, animations, commit);
+    return;
+  }
+  // Base `gsap.set` (off-timeline) — a static hold with no 0% keyframe marker, so
+  // adjusting a 3D transform on a non-keyframed element doesn't drop a keyframe on
+  // the timeline (matches the manual-drag UX). The global-set instant patch applies
+  // it straight to the element so the first edit shows with no soft-reload flash.
+  const numericProps: SetPatchProps = {};
+  for (const [k, v] of propEntries) {
+    if (typeof v === "number") numericProps[k as keyof SetPatchProps] = v;
+  }
+  await commit(
+    selection,
+    {
+      type: "add",
+      targetSelector: selector,
+      method: "set",
+      position: 0,
+      properties: Object.fromEntries(propEntries),
+      global: true,
+    },
+    {
+      label: "Set 3D transform",
+      softReload: true,
+      ...(Object.keys(numericProps).length > 0
+        ? {
+            instantPatch: {
+              selector,
+              change: { kind: "global-set" as const, props: numericProps },
+            },
+          }
+        : {}),
+    },
+  );
+}
+
+/** Convert-if-flat, then write ALL props into ONE keyframe at the playhead. */
+// fallow-ignore-next-line complexity
+async function commitKeyframeProps(
+  selection: DomEditSelection,
+  anim: GsapAnimation,
+  props: Record<string, number | string>,
+  propEntries: [string, number | string][],
+  primaryProp: string,
+  selector: string | null,
+  iframe: HTMLIFrameElement | null,
+  commit: Commit,
+): Promise<void> {
+  if (!anim.keyframes) {
+    await commit(
+      selection,
+      { type: "convert-to-keyframes", animationId: anim.id },
+      { label: "Convert to keyframes", skipReload: true },
+    );
+  }
+  const pct = computeElementPercentage(usePlayerStore.getState().currentTime, selection, anim);
+  const runtimeProps = selector ? readAllAnimatedProperties(iframe, selector, anim) : {};
+  const properties: Record<string, number | string> = { ...runtimeProps, ...props };
+
+  const backfillDefaults: Record<string, number | string> = { ...runtimeProps };
+  for (const [property, value] of propEntries) {
+    if (!(property in runtimeProps) && selector) {
+      const cssVal = readGsapProperty(iframe, selector, property);
+      if (cssVal != null) backfillDefaults[property] = cssVal;
+    }
+    backfillDefaults[property] = value;
+  }
+
+  const existingKf = anim.keyframes?.keyframes.some((kf) => Math.abs(kf.percentage - pct) < 0.05);
+  // Rebuild the live keyframe tween in place so the edit shows instantly (no flash);
+  // rebuildKeyframeTween declines → soft reload if the tween can't be safely rebuilt.
+  const numericProps: Record<string, number> = {};
+  for (const [k, v] of Object.entries(properties)) {
+    if (typeof v === "number") numericProps[k] = v;
+  }
+  const instantPatch =
+    selector && Object.keys(numericProps).length > 0
+      ? { selector, change: { kind: "keyframe-rebuild" as const, pct, props: numericProps } }
+      : undefined;
+  await commit(
+    selection,
+    existingKf
+      ? { type: "update-keyframe", animationId: anim.id, percentage: pct, properties }
+      : {
+          type: "add-keyframe",
+          animationId: anim.id,
+          percentage: pct,
+          properties,
+          backfillDefaults,
+        },
+    {
+      label: `Edit ${primaryProp} (keyframe ${pct}%)`,
+      softReload: true,
+      ...(instantPatch ? { instantPatch } : {}),
+    },
+  );
+}
+
 export function useAnimatedPropertyCommit(deps: CommitAnimatedPropertyDeps) {
-  const {
-    selectedGsapAnimations,
-    gsapCommitMutation,
-    addGsapAnimation,
-    previewIframeRef,
-    bumpGsapCache,
-  } = deps;
+  const { selectedGsapAnimations, gsapCommitMutation, previewIframeRef, bumpGsapCache } = deps;
 
-  const commitAnimatedProperty = useCallback(
-    async (
-      selection: DomEditSelection,
-      property: string,
-      value: number | string,
-    ): Promise<void> => {
+  const commitAnimatedProperties = useCallback(
+    async (selection: DomEditSelection, props: Record<string, number | string>): Promise<void> => {
       if (!gsapCommitMutation) return;
+      const propEntries = Object.entries(props);
+      if (propEntries.length === 0) return;
+      const primaryProp = propEntries[0]![0];
 
       const iframe = previewIframeRef.current;
       const selector = selectorFromSelection(selection);
 
-      let anim: GsapAnimation | undefined = pickBestAnimation(
+      const anim: GsapAnimation | undefined = pickBestAnimation(
         selectedGsapAnimations,
         selector,
-        property,
+        primaryProp,
       );
+      // Whether the element is animated at all. A 3D edit only creates/edits
+      // keyframes when it IS — a static element (no keyframes on any of its tweens)
+      // gets a `tl.set`, never new keyframes (matches manual drag / resize / rotate).
+      const elementHasKeyframes = selectedGsapAnimations.some((a) => !!a.keyframes);
 
-      // Case 3: No animation — create one first
-      if (!anim) {
-        addGsapAnimation(selection, "to");
-        // The addGsapAnimation triggers a reload. We need to wait for the cache
-        // to update. Use a small delay then bump cache to re-fetch.
-        await new Promise((r) => setTimeout(r, 500));
-        bumpGsapCache();
-        // After creation, we can't proceed in this call — the animation isn't
-        // in our local state yet. The user's next edit will find it.
-        // For immediate feedback, trigger a convert-to-keyframes on the new animation.
-        return;
-      }
+      // The picked anim comes from the (possibly stale) panel cache: if keyframes
+      // were just removed or the script changed underneath us, its id is gone
+      // server-side and the commit 404s. The raw commit already toasts; we catch
+      // so the rejection doesn't escape as an uncaught promise, and bump the cache
+      // so selectedGsapAnimations re-syncs and the user's next edit self-heals.
+      try {
+        // Existing static hold — merge the props into the `set`, then auto-keyframe
+        // ONLY if the element is already animated (maybeAutoKeyframeSet no-ops if not).
+        if (anim?.method === "set") {
+          await commitSetProps(
+            selection,
+            anim,
+            propEntries,
+            selector,
+            selectedGsapAnimations,
+            gsapCommitMutation,
+          );
+          return;
+        }
 
-      // Case 2: Flat animation — convert to keyframes first
-      if (!anim.keyframes) {
-        await gsapCommitMutation(
+        // Static element — persist as a `tl.set`, never keyframes (incl. the
+        // no-animation case, which now creates a set instead of a keyframed tween).
+        if (!elementHasKeyframes) {
+          await commitStaticSet(
+            selection,
+            propEntries,
+            selector,
+            selectedGsapAnimations,
+            gsapCommitMutation,
+          );
+          return;
+        }
+
+        // Animated element — write ALL props into ONE keyframe so a multi-axis cube
+        // edit doesn't race into adjacent duplicates.
+        if (!anim) {
+          bumpGsapCache();
+          return;
+        }
+        await commitKeyframeProps(
           selection,
-          { type: "convert-to-keyframes", animationId: anim.id },
-          { label: "Convert to keyframes", skipReload: true },
+          anim,
+          props,
+          propEntries,
+          primaryProp,
+          selector,
+          iframe,
+          gsapCommitMutation,
         );
+      } catch {
+        bumpGsapCache();
       }
-
-      const pct = computeElementPercentage(usePlayerStore.getState().currentTime, selection, anim);
-
-      // Read all currently animated properties from runtime for backfill
-      const runtimeProps = selector ? readAllAnimatedProperties(iframe, selector, anim) : {};
-
-      // Build the properties object: all runtime props + the new value
-      const properties: Record<string, number | string> = { ...runtimeProps };
-      properties[property] = value;
-
-      // Compute backfill defaults for properties not in existing keyframes
-      const backfillDefaults: Record<string, number | string> = { ...runtimeProps };
-      if (!(property in runtimeProps) && selector) {
-        const cssVal = readGsapProperty(iframe, selector, property);
-        if (cssVal != null) backfillDefaults[property] = cssVal;
-      }
-      backfillDefaults[property] = typeof value === "number" ? value : value;
-
-      const existingKf = anim.keyframes?.keyframes.some(
-        (kf) => Math.abs(kf.percentage - pct) < 0.05,
-      );
-
-      await gsapCommitMutation(
-        selection,
-        existingKf
-          ? {
-              type: "update-keyframe",
-              animationId: anim.id,
-              percentage: pct,
-              properties,
-            }
-          : {
-              type: "add-keyframe",
-              animationId: anim.id,
-              percentage: pct,
-              properties,
-              backfillDefaults,
-            },
-        { label: `Edit ${property} (keyframe ${pct}%)`, softReload: true },
-      );
     },
-    [selectedGsapAnimations, gsapCommitMutation, addGsapAnimation, previewIframeRef, bumpGsapCache],
+    [selectedGsapAnimations, gsapCommitMutation, previewIframeRef, bumpGsapCache],
+  );
+
+  const commitAnimatedProperty = useCallback(
+    (selection: DomEditSelection, property: string, value: number | string) =>
+      commitAnimatedProperties(selection, { [property]: value }),
+    [commitAnimatedProperties],
   );
 
-  return commitAnimatedProperty;
+  return { commitAnimatedProperty, commitAnimatedProperties };
 }

package/src/hooks/useDomEditCommits.ts

@@ -301,7 +301,6 @@ export function useDomEditCommits({
 
   const {
     handleDomPathOffsetCommit,
-    handleDomGroupPathOffsetCommit,
     handleDomBoxSizeCommit,
     handleDomRotationCommit,
     handleDomManualEditsReset,
@@ -340,7 +339,6 @@ export function useDomEditCommits({
     handleDomAddTextField,
     handleDomRemoveTextField,
     handleDomPathOffsetCommit,
-    handleDomGroupPathOffsetCommit,
     handleDomBoxSizeCommit,
     handleDomRotationCommit,
     handleDomManualEditsReset,

package/src/hooks/useDomEditSession.ts

@@ -215,7 +215,6 @@ export function useDomEditSession({
     handleDomTextFieldStyleCommit,
     handleDomAddTextField,
     handleDomRemoveTextField,
-    handleDomGroupPathOffsetCommit,
     handleDomBoxSizeCommit,
     handleDomManualEditsReset,
     handleDomEditElementDelete,
@@ -368,9 +367,11 @@ export function useDomEditSession({
 
   const {
     handleGsapAwarePathOffsetCommit,
+    handleGsapAwareGroupPathOffsetCommit,
     handleGsapAwareBoxSizeCommit,
     handleGsapAwareRotationCommit,
     commitAnimatedProperty,
+    commitAnimatedProperties,
     handleSetArcPath,
     handleUpdateArcSegment,
     handleUnroll,
@@ -452,7 +453,7 @@ export function useDomEditSession({
     handleDomAttributeLiveCommit,
     handleDomHtmlAttributeCommit,
     handleDomPathOffsetCommit: handleGsapAwarePathOffsetCommit,
-    handleDomGroupPathOffsetCommit,
+    handleDomGroupPathOffsetCommit: handleGsapAwareGroupPathOffsetCommit,
     handleDomZIndexReorderCommit,
     handleDomBoxSizeCommit: handleGsapAwareBoxSizeCommit,
     handleDomRotationCommit: handleGsapAwareRotationCommit,
@@ -498,6 +499,7 @@ export function useDomEditSession({
     handleUpdateKeyframeEase,
     handleSetAllKeyframeEases,
     commitAnimatedProperty,
+    commitAnimatedProperties,
     handleSetArcPath,
     handleUpdateArcSegment,
     handleUnroll,

package/src/hooks/useDomGeometryCommits.ts

@@ -16,11 +16,10 @@ import {
   buildClearBoxSizePatches,
   buildClearRotationPatches,
 } from "../components/editor/manualEditsDomPatches";
-import type { DomEditGroupPathOffsetCommit } from "../components/editor/DomEditOverlay";
 import type { PatchOperation } from "../utils/sourcePatcher";
 import { isElementGsapTargeted } from "./gsapTargetCache";
 
-export const GSAP_CSS_FALLBACK_BLOCKED_MESSAGE =
+const GSAP_CSS_FALLBACK_BLOCKED_MESSAGE =
   "This element is GSAP-animated — dragging via CSS would corrupt keyframes";
 
 // ── Hook ──
@@ -46,7 +45,8 @@ export function useDomGeometryCommits({
       // elements fall through to commitPositionPatchToHtml → persistDomEditOperations →
       // onTrySdkPersist and are already SDK-cut-over as setStyle/setAttribute (§3.3 done).
       // Upgrade path for GSAP: add a moveElementGsap SDK op in a separate SDK PR.
-      if (isElementGsapTargeted(previewIframeRef.current, selection.element)) {
+      const gsapTargeted = isElementGsapTargeted(previewIframeRef.current, selection.element);
+      if (gsapTargeted) {
         const error = new Error(GSAP_CSS_FALLBACK_BLOCKED_MESSAGE);
         showToast(error.message, "error");
         return Promise.reject(error);
@@ -60,33 +60,6 @@ export function useDomGeometryCommits({
     [commitPositionPatchToHtml, previewIframeRef, showToast],
   );
 
-  const handleDomGroupPathOffsetCommit = useCallback(
-    (updates: DomEditGroupPathOffsetCommit[]) => {
-      if (updates.length === 0) return Promise.resolve();
-      const blockedUpdate = updates.find(({ selection }) =>
-        isElementGsapTargeted(previewIframeRef.current, selection.element),
-      );
-      if (blockedUpdate) {
-        const error = new Error(GSAP_CSS_FALLBACK_BLOCKED_MESSAGE);
-        showToast(error.message, "error");
-        return Promise.reject(error);
-      }
-      const coalesceKey = updates
-        .map((u) => getDomEditTargetKey(u.selection))
-        .sort()
-        .join(":");
-      const saves = updates.map(({ selection, next }) => {
-        applyStudioPathOffset(selection.element, next);
-        return commitPositionPatchToHtml(selection, buildPathOffsetPatches(selection.element), {
-          label: `Move ${updates.length} layers`,
-          coalesceKey: `group-path-offset:${coalesceKey}`,
-        });
-      });
-      return Promise.all(saves).then(() => undefined);
-    },
-    [commitPositionPatchToHtml, previewIframeRef, showToast],
-  );
-
   const handleDomBoxSizeCommit = useCallback(
     (selection: DomEditSelection, next: { width: number; height: number }) => {
       if (isElementGsapTargeted(previewIframeRef.current, selection.element)) {
@@ -142,7 +115,6 @@ export function useDomGeometryCommits({
 
   return {
     handleDomPathOffsetCommit,
-    handleDomGroupPathOffsetCommit,
     handleDomBoxSizeCommit,
     handleDomRotationCommit,
     handleDomManualEditsReset,

package/src/hooks/useEnableKeyframes.test.ts

@@ -1,10 +1,13 @@
 import { describe, expect, it } from "vitest";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import {
   animatedProps,
   buildExtendedKeyframes,
   isPlayheadWithinTween,
+  promoteSetToKeyframes,
   resolveNewTweenRange,
+  type EnableKeyframesSession,
 } from "./useEnableKeyframes";
 
 function anim(overrides: Partial<GsapAnimation>): GsapAnimation {
@@ -128,3 +131,40 @@ describe("buildExtendedKeyframes", () => {
     expect(out.keyframes[1]!.percentage).toBeCloseTo(22.7, 1);
   });
 });
+
+describe("promoteSetToKeyframes — auto endpoint", () => {
+  it("marks the 0% (held start) as `auto`, leaving the 100% (playhead) fixed", async () => {
+    let committed: Record<string, unknown> | undefined;
+    const session = {
+      commitMutation: async (mutation: Record<string, unknown>) => {
+        committed = mutation;
+      },
+    } as unknown as EnableKeyframesSession;
+    const sel = {
+      id: "card",
+      selector: "#card",
+      sourceFile: "index.html",
+      element: { isConnected: true } as unknown as HTMLElement,
+    } as unknown as DomEditSelection;
+    // readElementPosition reads gsap.getProperty off the iframe window.
+    const iframe = {
+      contentWindow: { gsap: { getProperty: () => -74 } },
+    } as unknown as HTMLIFrameElement;
+    const setAnim = anim({
+      id: "#card-set-0-position",
+      targetSelector: "#card",
+      method: "set",
+      global: true,
+      resolvedStart: 0,
+      properties: { x: -74, y: -469 },
+    });
+
+    await promoteSetToKeyframes(session, sel, setAnim, 1, iframe);
+
+    const kfs = committed?.keyframes as Array<{ percentage: number; auto?: boolean }>;
+    expect(committed?.type).toBe("replace-with-keyframes");
+    expect(kfs[0]).toMatchObject({ percentage: 0, auto: true });
+    expect(kfs[1].percentage).toBe(100);
+    expect(kfs[1].auto).toBeUndefined();
+  });
+});

package/src/hooks/useEnableKeyframes.ts

@@ -107,6 +107,7 @@ export function buildExtendedKeyframes(
   return { position: roundTo3(newStart), duration: newDuration, keyframes };
 }
 
+// fallow-ignore-next-line complexity
 function readElementPosition(
   iframe: HTMLIFrameElement | null,
   sel: DomEditSelection,
@@ -238,8 +239,12 @@ async function applyKeyframeAtPlayhead(
  * two-stop tween from the set's time to the playhead — the held value at 0%, the
  * live value at 100% — giving the user something to animate. No-op if the playhead
  * is at or before the set.
+ *
+ * The 0% endpoint is the held start, which the user didn't choose — mark it `auto`
+ * so it tracks the nearest keyframe until edited directly. The 100% is the real
+ * keyframe being placed at the playhead, so it stays fixed.
  */
-async function promoteSetToKeyframes(
+export async function promoteSetToKeyframes(
   session: EnableKeyframesSession,
   sel: DomEditSelection,
   setAnim: GsapAnimation,
@@ -267,6 +272,7 @@ async function promoteSetToKeyframes(
         {
           percentage: 0,
           properties: Object.keys(startPosition).length > 0 ? startPosition : endPosition,
+          auto: true,
         },
         { percentage: 100, properties: endPosition },
       ],
@@ -283,6 +289,7 @@ async function promoteSetToKeyframes(
  * the path, inserted at the matching segment so the curve is preserved. Outside the
  * range, extend the duration so the motion reaches the playhead.
  */
+// fallow-ignore-next-line complexity
 async function applyArcWaypointAtPlayhead(
   session: EnableKeyframesSession,
   sel: DomEditSelection,
@@ -332,10 +339,10 @@ async function applyArcWaypointAtPlayhead(
   );
 }
 
-// fallow-ignore-next-line complexity
 export function useEnableKeyframes(
   sessionRef: React.RefObject<EnableKeyframesSession | undefined>,
 ) {
+  // fallow-ignore-next-line complexity
   return useCallback(async () => {
     const session = sessionRef.current;
     if (!session) return;

package/src/hooks/useGsapAwareEditing.ts

@@ -21,6 +21,7 @@ import {
   useSafeGsapCommitMutation,
 } from "./useSafeGsapCommitMutation";
 import type { CommitMutation } from "./gsapScriptCommitTypes";
+import type { DomEditGroupPathOffsetCommit } from "../components/editor/DomEditOverlay";
 
 export interface UseGsapAwareEditingParams {
   domEditSelection: DomEditSelection | null;
@@ -122,6 +123,33 @@ export function useGsapAwareEditing({
     ],
   );
 
+  // Multi-select (group) drag: route EACH element through the SAME GSAP intercept as
+  // a single drag, so every position is written as GSAP code (tl.set / keyframes /
+  // gsap.set) — NEVER the deprecated `--hf-studio-offset` CSS var, and GSAP-animated
+  // elements are no longer blocked in a group. No CSS fallback: with no GSAP
+  // composition there's nothing to write (a no-op, exactly like the single-drag path).
+  const handleGsapAwareGroupPathOffsetCommit = useCallback(
+    async (updates: DomEditGroupPathOffsetCommit[]) => {
+      if (!gsapCommitMutation) return;
+      for (const { selection, next } of updates) {
+        try {
+          await tryGsapDragIntercept(
+            selection,
+            next,
+            [],
+            previewIframeRef.current,
+            gsapCommitMutation,
+            makeFetchFallback(selection),
+          );
+        } catch (error) {
+          trackGsapInteractionFailure(error, selection, "drag", "Move animated layer (group)");
+          throw error;
+        }
+      }
+    },
+    [gsapCommitMutation, previewIframeRef, makeFetchFallback, trackGsapInteractionFailure],
+  );
+
   const handleGsapAwareBoxSizeCommit = useCallback(
     async (selection: DomEditSelection, next: { width: number; height: number }) => {
       if (gsapCommitMutation) {
@@ -184,7 +212,7 @@ export function useGsapAwareEditing({
 
   // ── Animated property commit ──
 
-  const commitAnimatedProperty = useAnimatedPropertyCommit({
+  const { commitAnimatedProperty, commitAnimatedProperties } = useAnimatedPropertyCommit({
     selectedGsapAnimations,
     gsapCommitMutation,
     addGsapAnimation: (sel, method, time) => addGsapAnimation(sel, method, time),
@@ -246,9 +274,11 @@ export function useGsapAwareEditing({
 
   return {
     handleGsapAwarePathOffsetCommit,
+    handleGsapAwareGroupPathOffsetCommit,
     handleGsapAwareBoxSizeCommit,
     handleGsapAwareRotationCommit,
     commitAnimatedProperty,
+    commitAnimatedProperties,
     handleSetArcPath,
     handleUpdateArcSegment,
     handleUnroll,

package/src/hooks/useGsapKeyframeOps.ts

@@ -206,6 +206,7 @@ export function useGsapKeyframeOps({
       selection: DomEditSelection,
       animationId: string,
       resolvedFromValues?: Record<string, number | string>,
+      duration?: number,
     ) => {
       if (sdkSession && sdkDeps) {
         const targetPath = selection.sourceFile || activeCompPath || "index.html";
@@ -221,7 +222,9 @@ export function useGsapKeyframeOps({
       }
       return commitMutation(
         selection,
-        { type: "convert-to-keyframes", animationId, resolvedFromValues },
+        // `duration` only applies when the target is a static `set` (which has
+        // none) — it spans the converted keyframes across the element's clip.
+        { type: "convert-to-keyframes", animationId, resolvedFromValues, duration },
         { label: "Convert to keyframes" },
       );
     },