@hyperframes/studio 0.7.14 → 0.7.16

package/src/hooks/useAnimatedPropertyCommit.ts

@@ -15,6 +15,8 @@ import { usePlayerStore } from "../player/store/playerStore";
 import { readAllAnimatedProperties, readGsapProperty } from "./gsapRuntimeBridge";
 import type { SetPatchProps } from "./gsapRuntimePatch";
 import { selectorFromSelection, computeElementPercentage } from "./gsapShared";
+import { resolveTweenStart, resolveTweenDuration } from "../utils/globalTimeCompiler";
+import { roundTo3 } from "../utils/rounding";
 
 interface CommitAnimatedPropertyDeps {
   selectedGsapAnimations: GsapAnimation[];
@@ -45,14 +47,22 @@ function pickBestAnimation(
   selector: string | null,
   property?: string,
 ): GsapAnimation | undefined {
-  if (animations.length <= 1) return animations[0];
-  const currentTime = usePlayerStore.getState().currentTime;
   const targetGroup = property ? classifyPropertyGroup(property) : undefined;
-
-  // fallow-ignore-next-line complexity
-  const scored = animations.map((a) => {
+  // Group-aware: never hand back a tween from a DIFFERENT property group. The old
+  // `animations.length <= 1` early return merged a rotation/3D edit into the element's
+  // only tween even when that was a `position` tween — contaminating it and leaving the
+  // new property with no clean keyframe baseline. When a target group is known, only
+  // same-group tweens are candidates; if none exist we return undefined and the caller
+  // creates a fresh same-group tween.
+  const candidates =
+    targetGroup !== undefined
+      ? animations.filter((a) => a.propertyGroup === targetGroup)
+      : animations;
+  if (candidates.length === 0) return undefined;
+  if (candidates.length === 1) return candidates[0];
+  const currentTime = usePlayerStore.getState().currentTime;
+  const scored = candidates.map((a) => {
     let score = 0;
-    if (targetGroup && a.propertyGroup === targetGroup) score += 20;
     if (a.keyframes) score += 10;
     if (selector && a.targetSelector === selector) score += 5;
     else if (a.targetSelector.includes(",")) score -= 3;
@@ -196,14 +206,15 @@ async function commitKeyframeProps(
   iframe: HTMLIFrameElement | null,
   commit: Commit,
 ): Promise<void> {
-  if (!anim.keyframes) {
+  const wasKeyframed = !!anim.keyframes;
+  if (!wasKeyframed) {
     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 ct = usePlayerStore.getState().currentTime;
   const runtimeProps = selector ? readAllAnimatedProperties(iframe, selector, anim) : {};
   const properties: Record<string, number | string> = { ...runtimeProps, ...props };
 
@@ -216,6 +227,52 @@ async function commitKeyframeProps(
     backfillDefaults[property] = value;
   }
 
+  // Playhead OUTSIDE the keyframe tween's time range → EXTEND the tween to reach it
+  // and add a keyframe there, exactly like manual drag's extendTweenAndAddKeyframe.
+  // The add-keyframe below only writes WITHIN the existing range, so without this a
+  // depth edit past the tween end just overwrites the last keyframe (the bug: no new
+  // diamond appears at a playhead beyond the tween). Only for an already-keyframed
+  // tween — a freshly-converted set has no prior range worth remapping.
+  const kfs = anim.keyframes?.keyframes;
+  const ts = resolveTweenStart(anim);
+  const td = resolveTweenDuration(anim);
+  const hasSelectedKeyframe = usePlayerStore.getState().activeKeyframePct != null;
+  const playheadOutside = ts !== null && td > 0 && (ct < ts - 0.01 || ct > ts + td + 0.01);
+  const willExtend = wasKeyframed && !!kfs && playheadOutside && !hasSelectedKeyframe;
+  if (willExtend && kfs && ts !== null) {
+    const newStart = Math.min(ct, ts);
+    const newEnd = Math.max(ct, ts + td);
+    const newDuration = Math.max(0.01, newEnd - newStart);
+    const remapped = kfs.map((kf) => {
+      const absTime = ts + (kf.percentage / 100) * td;
+      const newPct = Math.round(((absTime - newStart) / newDuration) * 1000) / 10;
+      const p: Record<string, number | string> = { ...kf.properties };
+      for (const k of Object.keys(properties)) {
+        if (!(k in p) && backfillDefaults[k] != null) p[k] = backfillDefaults[k];
+      }
+      return { percentage: newPct, properties: p };
+    });
+    remapped.push({
+      percentage: Math.round(((ct - newStart) / newDuration) * 1000) / 10,
+      properties,
+    });
+    remapped.sort((a, b) => a.percentage - b.percentage);
+    await commit(
+      selection,
+      {
+        type: "replace-with-keyframes",
+        animationId: anim.id,
+        targetSelector: anim.targetSelector,
+        position: roundTo3(newStart),
+        duration: roundTo3(newDuration),
+        keyframes: remapped,
+      },
+      { label: `Edit ${primaryProp} (extended keyframe)`, softReload: true },
+    );
+    return;
+  }
+
+  const pct = computeElementPercentage(ct, selection, anim);
   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.
@@ -275,8 +332,30 @@ export function useAnimatedPropertyCommit(deps: CommitAnimatedPropertyDeps) {
       // 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).
+        // Animated element → keyframe at the playhead, EXACTLY like manual drag /
+        // resize / rotate: if the picked anim is still a static `set`,
+        // commitKeyframeProps converts it to keyframes first, then writes the new
+        // value as a keyframe at the current time — so the 3D animates instead of
+        // holding a flat constant. This MUST come before the `set`-update path below,
+        // or a 3D `set` would short-circuit to an in-place update and the playhead
+        // keyframe would never land (the bug: scrolling depth on a keyframed element
+        // just changed the constant instead of dropping a keyframe).
+        if (elementHasKeyframes && anim) {
+          await commitKeyframeProps(
+            selection,
+            anim,
+            props,
+            propEntries,
+            primaryProp,
+            selector,
+            iframe,
+            gsapCommitMutation,
+          );
+          return;
+        }
+
+        // Existing static hold on a NON-animated element — merge the props into the
+        // `set` in place (maybeAutoKeyframeSet no-ops when nothing else is keyframed).
         if (anim?.method === "set") {
           await commitSetProps(
             selection,
@@ -289,8 +368,8 @@ export function useAnimatedPropertyCommit(deps: CommitAnimatedPropertyDeps) {
           return;
         }
 
-        // Static element — persist as a `tl.set`, never keyframes (incl. the
-        // no-animation case, which now creates a set instead of a keyframed tween).
+        // Static element (no keyframes anywhere) — persist as a `tl.set`, never
+        // keyframes (incl. the no-animation case, which creates a fresh set).
         if (!elementHasKeyframes) {
           await commitStaticSet(
             selection,
@@ -302,22 +381,43 @@ export function useAnimatedPropertyCommit(deps: CommitAnimatedPropertyDeps) {
           return;
         }
 
-        // Animated element — write ALL props into ONE keyframe so a multi-axis cube
-        // edit doesn't race into adjacent duplicates.
-        if (!anim) {
-          bumpGsapCache();
+        // Animated element but NO same-group tween exists (e.g. the FIRST rotation/3D
+        // keyframe on an element that only has a position tween). Create a fresh
+        // same-group keyframed tween WITH a 0% baseline at the playhead, instead of
+        // contaminating a foreign-group tween. Mirror an existing keyframed tween's
+        // time range so the new group animates over the same span. The 0% baseline is
+        // an `_auto` endpoint so it tracks the nearest keyframe as you add more.
+        if (selector) {
+          const template = selectedGsapAnimations.find((a) => !!a.keyframes);
+          const tStart = template ? (resolveTweenStart(template) ?? 0) : 0;
+          const tDur = template ? resolveTweenDuration(template) || 1 : 1;
+          const ct = usePlayerStore.getState().currentTime;
+          const pct =
+            tDur > 0
+              ? Math.max(0, Math.min(100, Math.round(((ct - tStart) / tDur) * 1000) / 10))
+              : 0;
+          const newProps = Object.fromEntries(propEntries);
+          const keyframes =
+            pct <= 0.05
+              ? [{ percentage: 0, properties: newProps }]
+              : [
+                  { percentage: 0, properties: { ...newProps, _auto: 1 } },
+                  { percentage: pct, properties: newProps },
+                ];
+          await gsapCommitMutation(
+            selection,
+            {
+              type: "add-with-keyframes",
+              targetSelector: selector,
+              position: roundTo3(tStart),
+              duration: roundTo3(tDur),
+              keyframes,
+            },
+            { label: `Add ${primaryProp} keyframe`, softReload: true },
+          );
           return;
         }
-        await commitKeyframeProps(
-          selection,
-          anim,
-          props,
-          propEntries,
-          primaryProp,
-          selector,
-          iframe,
-          gsapCommitMutation,
-        );
+        bumpGsapCache();
       } catch {
         bumpGsapCache();
       }

package/src/hooks/useAppHotkeys.ts

@@ -8,6 +8,7 @@ import { shouldHandleTimelineToggleHotkey, isEditableTarget } from "../utils/tim
 import { shouldIgnoreHistoryShortcut } from "../utils/studioHelpers";
 import { canSplitElement } from "../utils/timelineElementSplit";
 import { STUDIO_RAZOR_TOOL_ENABLED } from "../components/editor/manualEditingAvailability";
+import { trackStudioEvent } from "../utils/studioTelemetry";
 
 function iframeContentWindow(iframe: HTMLIFrameElement | null): Window | null {
   try {
@@ -117,6 +118,10 @@ interface UseAppHotkeysParams {
   onDeleteSelectedKeyframes: () => void;
   onAfterUndoRedo?: () => void;
   onToggleRecording?: () => void;
+  /** Group the current multi-selection into a data-hf-group wrapper (⌘G). */
+  onGroupSelection?: () => void;
+  /** Ungroup the selected group wrapper (⌘⇧G). */
+  onUngroupSelection?: () => void;
   /** Active composition path — used to decide whether undo/redo must resync the SDK session. */
   activeCompPath?: string | null;
   /**
@@ -142,6 +147,8 @@ interface HotkeyCallbacks {
   onResetKeyframes: () => boolean;
   onDeleteSelectedKeyframes: () => void;
   onToggleRecording?: () => void;
+  onGroupSelection?: () => void;
+  onUngroupSelection?: () => void;
   leftSidebarRef: React.RefObject<LeftSidebarHandle | null>;
   domEditSelectionRef: React.MutableRefObject<DomEditSelection | null>;
   showToast: (message: string, tone?: "error" | "info") => void;
@@ -152,36 +159,56 @@ function dispatchModifierKey(event: KeyboardEvent, key: string, cb: HotkeyCallba
     !shouldIgnoreHistoryShortcut(event.target) &&
     handleUndoRedoKey(
       event,
-      () => void cb.handleUndo(),
-      () => void cb.handleRedo(),
+      () => {
+        trackStudioEvent("keyboard_shortcut", { action: "undo" });
+        void cb.handleUndo();
+      },
+      () => {
+        trackStudioEvent("keyboard_shortcut", { action: "redo" });
+        void cb.handleRedo();
+      },
     )
   )
     return true;
 
   if (event.key === "1") {
     event.preventDefault();
+    trackStudioEvent("keyboard_shortcut", { action: "tab_compositions" });
     cb.leftSidebarRef.current?.selectTab("compositions");
     return true;
   }
   if (event.key === "2") {
     event.preventDefault();
+    trackStudioEvent("keyboard_shortcut", { action: "tab_assets" });
     cb.leftSidebarRef.current?.selectTab("assets");
     return true;
   }
 
+  if (key === "g" && !event.altKey && !isEditableTarget(event.target)) {
+    event.preventDefault();
+    if (event.shiftKey) cb.onUngroupSelection?.();
+    else cb.onGroupSelection?.();
+    return true;
+  }
+
   if (!event.shiftKey && !event.altKey && !isEditableTarget(event.target)) {
     if (key === "c") {
-      if (cb.handleCopy()) event.preventDefault();
+      if (cb.handleCopy()) {
+        event.preventDefault();
+        trackStudioEvent("keyboard_shortcut", { action: "copy" });
+      }
       return true;
     }
     if (key === "v") {
       event.preventDefault();
+      trackStudioEvent("keyboard_shortcut", { action: "paste" });
       void cb.handlePaste();
       return true;
     }
     if (key === "x") {
       if (usePlayerStore.getState().selectedElementId || cb.domEditSelectionRef.current) {
         event.preventDefault();
+        trackStudioEvent("keyboard_shortcut", { action: "cut" });
         void cb.handleCut();
       }
       return true;
@@ -310,6 +337,8 @@ export function useAppHotkeys({
   onDeleteSelectedKeyframes,
   onAfterUndoRedo,
   onToggleRecording,
+  onGroupSelection,
+  onUngroupSelection,
   activeCompPath,
   forceReloadSdkSession,
 }: UseAppHotkeysParams) {
@@ -403,6 +432,8 @@ export function useAppHotkeys({
     onResetKeyframes,
     onDeleteSelectedKeyframes,
     onToggleRecording,
+    onGroupSelection,
+    onUngroupSelection,
     leftSidebarRef,
     domEditSelectionRef,
     showToast,

package/src/hooks/useDomEditSession.ts

@@ -1,4 +1,5 @@
 import { useCallback } from "react";
+import { trackStudioEvent } from "../utils/studioTelemetry";
 import type { TimelineElement } from "../player";
 import type { ImportedFontAsset } from "../components/editor/fontAssets";
 import type { EditHistoryKind } from "../utils/editHistory";
@@ -12,6 +13,7 @@ import { useAskAgentModal } from "./useAskAgentModal";
 import { useDomSelection } from "./useDomSelection";
 import { usePreviewInteraction } from "./usePreviewInteraction";
 import { useDomEditCommits } from "./useDomEditCommits";
+import { useGroupCommits } from "./useGroupCommits";
 import { useGsapScriptCommits } from "./useGsapScriptCommits";
 import { useGsapCacheVersion } from "./useGsapTweenCache";
 import { useDomEditWiring } from "./useDomEditWiring";
@@ -114,7 +116,10 @@ export function useDomEditSession({
     domEditSelection,
     domEditGroupSelections,
     domEditHoverSelection,
+    activeGroupElement,
     domEditSelectionRef,
+    domEditGroupSelectionsRef,
+    setActiveGroupElement,
     applyDomSelection,
     clearDomSelection,
     buildDomSelectionFromTarget,
@@ -279,6 +284,44 @@ export function useDomEditSession({
       : undefined,
   });
 
+  // ── Element groups (wrap selected elements in a data-hf-group div) ──
+
+  const { groupSelection, ungroupSelection } = useGroupCommits({
+    activeCompPath,
+    showToast,
+    writeProjectFile,
+    domEditSaveTimestampRef,
+    editHistory,
+    projectIdRef,
+    reloadPreview,
+    clearDomSelection,
+    forceReloadSdkSession,
+  });
+
+  const handleGroupSelection = useCallback(() => {
+    const group = domEditGroupSelectionsRef.current;
+    const single = domEditSelectionRef.current;
+    const members = group.length > 0 ? group : single ? [single] : [];
+    if (members.length < 2) {
+      showToast("Select at least 2 elements to group", "info");
+      return;
+    }
+    trackStudioEvent("group", { action: "create", count: members.length });
+    void groupSelection(members);
+  }, [domEditGroupSelectionsRef, domEditSelectionRef, groupSelection, showToast]);
+
+  const handleUngroupSelection = useCallback(() => {
+    const sel = domEditSelectionRef.current;
+    if (!sel?.element.hasAttribute("data-hf-group")) {
+      showToast("Select a group to ungroup", "info");
+      return;
+    }
+    // Dissolving the group exits any drill-in (the wrapper is about to vanish).
+    trackStudioEvent("group", { action: "ungroup" });
+    setActiveGroupElement(null);
+    void ungroupSelection(sel);
+  }, [domEditSelectionRef, ungroupSelection, setActiveGroupElement, showToast]);
+
   // ── Wiring: selection sync, GSAP cache, preview sync, selection handlers ──
 
   const {
@@ -360,6 +403,7 @@ export function useDomEditSession({
     resolveDomSelectionFromPreviewPoint,
     resolveAllDomSelectionsFromPreviewPoint,
     updateDomEditHoverSelection,
+    setActiveGroupElement,
     onClickToSource,
   });
 
@@ -435,6 +479,7 @@ export function useDomEditSession({
     domEditSelection,
     domEditGroupSelections,
     domEditHoverSelection,
+    activeGroupElement,
     agentModalOpen,
     agentModalAnchorPoint,
     copiedAgentPrompt,
@@ -467,6 +512,9 @@ export function useDomEditSession({
     handleBlockedDomMove,
     handleDomManualDragStart,
     handleDomEditElementDelete,
+    handleGroupSelection,
+    handleUngroupSelection,
+    setActiveGroupElement,
     buildDomSelectionFromTarget,
     buildDomSelectionForTimelineElement,
     updateDomEditHoverSelection,

package/src/hooks/useDomSelection.ts

@@ -48,13 +48,16 @@ export interface UseDomSelectionReturn {
   domEditSelection: DomEditSelection | null;
   domEditGroupSelections: DomEditSelection[];
   domEditHoverSelection: DomEditSelection | null;
+  activeGroupElement: HTMLElement | null;
   // Refs
   domEditSelectionRef: React.MutableRefObject<DomEditSelection | null>;
   domEditGroupSelectionsRef: React.MutableRefObject<DomEditSelection[]>;
   domEditHoverSelectionRef: React.MutableRefObject<DomEditSelection | null>;
+  activeGroupElementRef: React.MutableRefObject<HTMLElement | null>;
   // State setters (needed by useDomEditSession for agent-prompt reset flows)
   setDomEditSelection: React.Dispatch<React.SetStateAction<DomEditSelection | null>>;
   setDomEditGroupSelections: React.Dispatch<React.SetStateAction<DomEditSelection[]>>;
+  setActiveGroupElement: (el: HTMLElement | null) => void;
   // Callbacks
   applyDomSelection: (
     selection: DomEditSelection | null,
@@ -67,12 +70,20 @@ export interface UseDomSelectionReturn {
   clearDomSelection: () => void;
   buildDomSelectionFromTarget: (
     target: HTMLElement,
-    options?: { preferClipAncestor?: boolean },
+    options?: {
+      preferClipAncestor?: boolean;
+      skipSourceProbe?: boolean;
+      activeGroupElement?: HTMLElement | null;
+    },
   ) => Promise<DomEditSelection | null>;
   resolveDomSelectionFromPreviewPoint: (
     clientX: number,
     clientY: number,
-    options?: { preferClipAncestor?: boolean },
+    options?: {
+      preferClipAncestor?: boolean;
+      skipSourceProbe?: boolean;
+      activeGroupElement?: HTMLElement | null;
+    },
   ) => Promise<DomEditSelection | null>;
   resolveAllDomSelectionsFromPreviewPoint: (
     clientX: number,
@@ -110,17 +121,21 @@ export function useDomSelection({
   const [domEditSelection, setDomEditSelection] = useState<DomEditSelection | null>(null);
   const [domEditGroupSelections, setDomEditGroupSelections] = useState<DomEditSelection[]>([]);
   const [domEditHoverSelection, setDomEditHoverSelection] = useState<DomEditSelection | null>(null);
+  // The data-hf-group wrapper the user has drilled into (null = top level).
+  const [activeGroupElement, setActiveGroupElementState] = useState<HTMLElement | null>(null);
 
   // ── Refs ──
 
   const domEditSelectionRef = useRef<DomEditSelection | null>(domEditSelection);
   const domEditGroupSelectionsRef = useRef<DomEditSelection[]>(domEditGroupSelections);
   const domEditHoverSelectionRef = useRef<DomEditSelection | null>(domEditHoverSelection);
+  const activeGroupElementRef = useRef<HTMLElement | null>(activeGroupElement);
 
   // Keep refs in sync with state
   domEditSelectionRef.current = domEditSelection;
   domEditGroupSelectionsRef.current = domEditGroupSelections;
   domEditHoverSelectionRef.current = domEditHoverSelection;
+  activeGroupElementRef.current = activeGroupElement;
 
   // ── Callbacks ──
 
@@ -178,6 +193,14 @@ export function useDomSelection({
       setDomEditSelection(nextSelection);
       setDomEditGroupSelections(nextGroup);
 
+      // Selecting something outside the drilled-into group exits the drill-in, so
+      // a later click on the group selects it as a unit again (non-sticky drill-in).
+      const activeGroup = activeGroupElementRef.current;
+      if (activeGroup && nextSelection && !activeGroup.contains(nextSelection.element)) {
+        activeGroupElementRef.current = null;
+        setActiveGroupElementState(null);
+      }
+
       if (nextSelection) {
         if (options?.revealPanel !== false) {
           setRightCollapsed(false);
@@ -203,16 +226,36 @@ export function useDomSelection({
     applyDomSelection(null, { revealPanel: false });
   }, [applyDomSelection]);
 
+  // Drill into / out of a group. Changing scope clears the current selection so
+  // the user isn't left with an out-of-scope element selected.
+  const setActiveGroupElement = useCallback(
+    (el: HTMLElement | null) => {
+      setActiveGroupElementState(el);
+      applyDomSelection(null, { revealPanel: false });
+    },
+    [applyDomSelection],
+  );
+
   const buildDomSelectionFromTarget = useCallback(
     (
       target: HTMLElement,
-      options?: { preferClipAncestor?: boolean; skipSourceProbe?: boolean },
+      options?: {
+        preferClipAncestor?: boolean;
+        skipSourceProbe?: boolean;
+        // Override the drill-in scope (used by canvas double-click to resolve the
+        // child inside a group before the activeGroupElement state has re-rendered).
+        activeGroupElement?: HTMLElement | null;
+      },
     ) => {
       return resolveDomEditSelection(target, {
         activeCompositionPath: activeCompPath,
         isMasterView,
         preferClipAncestor: options?.preferClipAncestor,
         skipSourceProbe: options?.skipSourceProbe,
+        activeGroupElement:
+          options && "activeGroupElement" in options
+            ? options.activeGroupElement
+            : activeGroupElementRef.current,
         projectId,
       });
     },
@@ -224,7 +267,11 @@ export function useDomSelection({
     async (
       clientX: number,
       clientY: number,
-      options?: { preferClipAncestor?: boolean; skipSourceProbe?: boolean },
+      options?: {
+        preferClipAncestor?: boolean;
+        skipSourceProbe?: boolean;
+        activeGroupElement?: HTMLElement | null;
+      },
     ) => {
       const iframe = previewIframeRef.current;
       if (!iframe || captionEditMode) return null;
@@ -235,10 +282,19 @@ export function useDomSelection({
       }
       const target = getPreviewTargetFromPointer(iframe, clientX, clientY, activeCompPath);
       if (!target) return null;
-      return buildDomSelectionFromTarget(target, {
-        preferClipAncestor: options?.preferClipAncestor,
-        skipSourceProbe: options?.skipSourceProbe,
-      });
+      return buildDomSelectionFromTarget(
+        target,
+        options && "activeGroupElement" in options
+          ? {
+              preferClipAncestor: options.preferClipAncestor,
+              skipSourceProbe: options.skipSourceProbe,
+              activeGroupElement: options.activeGroupElement,
+            }
+          : {
+              preferClipAncestor: options?.preferClipAncestor,
+              skipSourceProbe: options?.skipSourceProbe,
+            },
+      );
     },
     [activeCompPath, buildDomSelectionFromTarget, captionEditMode, previewIframeRef],
   );
@@ -445,7 +501,12 @@ export function useDomSelection({
           if (!domEditSelectionInGroup(nextGroup, s)) nextGroup = [...nextGroup, s];
         }
       } else {
-        nextGroup = selections;
+        // Dedupe by target: under select-as-unit several marquee'd members collapse
+        // to the same group, which must count as one selection, not many duplicates.
+        nextGroup = [];
+        for (const s of selections) {
+          if (!domEditSelectionInGroup(nextGroup, s)) nextGroup.push(s);
+        }
       }
       const nextSelection = additive && current ? current : selections[0];
       domEditSelectionRef.current = nextSelection;
@@ -478,13 +539,16 @@ export function useDomSelection({
     domEditSelection,
     domEditGroupSelections,
     domEditHoverSelection,
+    activeGroupElement,
     // Refs
     domEditSelectionRef,
     domEditGroupSelectionsRef,
     domEditHoverSelectionRef,
+    activeGroupElementRef,
     // State setters
     setDomEditSelection,
     setDomEditGroupSelections,
+    setActiveGroupElement,
     // Callbacks
     applyDomSelection,
     clearDomSelection,

package/src/hooks/useEnableKeyframes.test.ts

@@ -167,4 +167,39 @@ describe("promoteSetToKeyframes — auto endpoint", () => {
     expect(kfs[1].percentage).toBe(100);
     expect(kfs[1].auto).toBeUndefined();
   });
+
+  it("playhead AT the set (t <= setStart) drops a single 0% keyframe, not a no-op", async () => {
+    // Regression: enabling keyframes on a `gsap.set` element at t=0 (set start 0)
+    // returned early (`t <= setStart`) → nothing created. Must give a 0% keyframe.
+    let committed: Record<string, unknown> | undefined;
+    const session = {
+      commitMutation: async (mutation: Record<string, unknown>) => {
+        committed = mutation;
+      },
+    } as unknown as EnableKeyframesSession;
+    const sel = {
+      id: "box",
+      selector: "#box",
+      sourceFile: "index.html",
+      element: { isConnected: true } as unknown as HTMLElement,
+    } as unknown as DomEditSelection;
+    const iframe = {
+      contentWindow: { gsap: { getProperty: () => -1091 } },
+    } as unknown as HTMLIFrameElement;
+    const setAnim = anim({
+      id: "#box-set-0-position",
+      targetSelector: "#box",
+      method: "set",
+      global: true,
+      resolvedStart: 0,
+      properties: { x: -1091, y: 280 },
+    });
+
+    await promoteSetToKeyframes(session, sel, setAnim, 0, iframe);
+
+    const kfs = committed?.keyframes as Array<{ percentage: number }>;
+    expect(committed?.type).toBe("replace-with-keyframes");
+    expect(kfs).toHaveLength(1);
+    expect(kfs[0].percentage).toBe(0);
+  });
 });

package/src/hooks/useEnableKeyframes.ts

@@ -253,7 +253,35 @@ export async function promoteSetToKeyframes(
 ): Promise<void> {
   const selector = selectorFromSelection(sel);
   const setStart = resolveTweenStart(setAnim) ?? 0;
-  if (!selector || !session.commitMutation || t <= setStart) return;
+  if (!selector || !session.commitMutation) return;
+  // Playhead at or before the set → there's no forward range to promote into.
+  // Instead of doing nothing (which read as "can't add a keyframe at 0"), replace
+  // the set with a single keyframe at the playhead holding its value, matching the
+  // no-animation branch: one diamond the user can build motion from.
+  if (t <= setStart) {
+    const position = readElementPosition(iframe, sel, setAnim);
+    if (Object.keys(position).length === 0) {
+      for (const key of Object.keys(setAnim.properties ?? {})) {
+        const held = setAnim.properties?.[key];
+        if (typeof held === "number") position[key] = held;
+      }
+    }
+    if (Object.keys(position).length === 0) return;
+    const range = resolveNewTweenRange(sel.dataAttributes?.start, sel.dataAttributes?.duration, t);
+    await session.commitMutation(
+      {
+        type: "replace-with-keyframes",
+        animationId: setAnim.id,
+        targetSelector: selector,
+        position: roundTo3(range.start),
+        duration: roundTo3(range.duration),
+        keyframes: [{ percentage: 0, properties: position }],
+        ease: setAnim.ease,
+      },
+      { label: "Enable keyframes", softReload: true },
+    );
+    return;
+  }
   const endPosition = readElementPosition(iframe, sel, setAnim);
   if (Object.keys(endPosition).length === 0) return;
   const startPosition: Record<string, number> = {};