@hyperframes/studio 0.7.15 → 0.7.17

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> = {};

package/src/hooks/useGroupCommits.ts

@@ -0,0 +1,188 @@
+import { useCallback } from "react";
+import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";
+import { createStudioSaveHttpError } from "../utils/studioSaveDiagnostics";
+import { buildDomEditPatchTarget, type DomEditSelection } from "../components/editor/domEditing";
+import type { EditHistoryKind } from "../utils/editHistory";
+
+interface RecordEditInput {
+  label: string;
+  kind: EditHistoryKind;
+  coalesceKey?: string;
+  files: Record<string, { before: string; after: string }>;
+}
+
+interface UseGroupCommitsParams {
+  activeCompPath: string | null;
+  showToast: (message: string, tone?: "error" | "info") => void;
+  writeProjectFile: (path: string, content: string) => Promise<void>;
+  domEditSaveTimestampRef: React.MutableRefObject<number>;
+  editHistory: { recordEdit: (entry: RecordEditInput) => Promise<void> };
+  projectIdRef: React.MutableRefObject<string | null>;
+  reloadPreview: () => void;
+  clearDomSelection: () => void;
+  /** Resync the SDK session after a server-side write (the wrapper/unwrap changes
+   * structure the in-memory doc doesn't know about). */
+  forceReloadSdkSession?: () => void;
+}
+
+interface PatchTarget {
+  id?: string | null;
+  hfId?: string;
+  selector?: string;
+  selectorIndex?: number;
+}
+
+interface GroupGeometry {
+  bbox: { left: number; top: number; width: number; height: number };
+  targets: PatchTarget[];
+  rebases: Array<{ target: PatchTarget; left: number; top: number }>;
+}
+
+// Wrapper sits at the members' bounding box top-left; each member is rebased so
+// its absolute position is unchanged. offsetLeft/Top are layout coordinates in
+// composition space (transforms excluded), exactly the space the rebase formula
+// `left_new = left_old - W.left` operates in — GSAP x/y and offset vars are
+// transform deltas and stay correct without adjustment.
+function computeGroupGeometry(members: DomEditSelection[]): GroupGeometry {
+  const boxes = members.map((m) => ({
+    target: buildDomEditPatchTarget(m),
+    left: m.element.offsetLeft,
+    top: m.element.offsetTop,
+    right: m.element.offsetLeft + m.element.offsetWidth,
+    bottom: m.element.offsetTop + m.element.offsetHeight,
+  }));
+  const left = Math.min(...boxes.map((b) => b.left));
+  const top = Math.min(...boxes.map((b) => b.top));
+  const width = Math.max(...boxes.map((b) => b.right)) - left;
+  const height = Math.max(...boxes.map((b) => b.bottom)) - top;
+  return {
+    bbox: { left, top, width, height },
+    targets: boxes.map((b) => b.target),
+    rebases: boxes.map((b) => ({ target: b.target, left: b.left - left, top: b.top - top })),
+  };
+}
+
+// Shared read → mutate-route → save-with-history → reload pipeline for both
+// wrap (group) and unwrap (ungroup). Mirrors the structural-mutation pattern in
+// useElementLifecycleOps (delete). Returns the route's JSON, or throws.
+async function commitStructuralMutation(
+  pid: string,
+  targetPath: string,
+  route: "wrap-elements" | "unwrap-elements",
+  body: unknown,
+  label: string,
+  deps: Pick<
+    UseGroupCommitsParams,
+    | "writeProjectFile"
+    | "editHistory"
+    | "domEditSaveTimestampRef"
+    | "clearDomSelection"
+    | "forceReloadSdkSession"
+    | "reloadPreview"
+  >,
+): Promise<{ content?: string; groupId?: string }> {
+  const response = await fetch(`/api/projects/${pid}/files/${encodeURIComponent(targetPath)}`);
+  if (!response.ok) {
+    throw await createStudioSaveHttpError(response, `Failed to read ${targetPath}`);
+  }
+  const data = (await response.json()) as { content?: string };
+  const originalContent = data.content;
+  if (typeof originalContent !== "string") {
+    throw new Error(`Missing file contents for ${targetPath}`);
+  }
+
+  deps.domEditSaveTimestampRef.current = Date.now();
+  const mutateResponse = await fetch(
+    `/api/projects/${pid}/file-mutations/${route}/${encodeURIComponent(targetPath)}`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    },
+  );
+  if (!mutateResponse.ok) {
+    const errBody = (await mutateResponse.json().catch(() => null)) as { error?: string } | null;
+    throw new Error(errBody?.error ?? `Failed to ${label.toLowerCase()} in ${targetPath}`);
+  }
+  const mutateData = (await mutateResponse.json()) as { content?: string; groupId?: string };
+  const patchedContent =
+    typeof mutateData.content === "string" ? mutateData.content : originalContent;
+
+  await saveProjectFilesWithHistory({
+    projectId: pid,
+    label,
+    kind: "manual",
+    files: { [targetPath]: patchedContent },
+    readFile: async () => originalContent,
+    writeFile: deps.writeProjectFile,
+    recordEdit: deps.editHistory.recordEdit,
+  });
+  deps.clearDomSelection();
+  deps.forceReloadSdkSession?.();
+  deps.reloadPreview();
+  return mutateData;
+}
+
+export function useGroupCommits(params: UseGroupCommitsParams) {
+  const { activeCompPath, showToast, projectIdRef } = params;
+
+  const groupSelection = useCallback(
+    async (members: DomEditSelection[]): Promise<string | null> => {
+      const pid = projectIdRef.current;
+      if (!pid || members.length === 0) return null;
+
+      // All members must live in the same source file — the wrapper is one node
+      // in one document. (Cross-file grouping is out of scope.)
+      const targetPath = members[0].sourceFile || activeCompPath || "index.html";
+      if (members.some((m) => (m.sourceFile || activeCompPath || "index.html") !== targetPath)) {
+        showToast("Can't group elements from different files", "error");
+        return null;
+      }
+
+      // Auto-name "Group N" by the count of existing groups in the document.
+      const doc = members[0].element.ownerDocument;
+      const groupId = `Group ${doc.querySelectorAll("[data-hf-group]").length + 1}`;
+      const { bbox, targets, rebases } = computeGroupGeometry(members);
+
+      try {
+        const data = await commitStructuralMutation(
+          pid,
+          targetPath,
+          "wrap-elements",
+          { targets, groupId, bbox, rebases },
+          "Group elements",
+          params,
+        );
+        return data.groupId ?? groupId;
+      } catch (error) {
+        showToast(error instanceof Error ? error.message : "Failed to group elements", "error");
+        return null;
+      }
+    },
+    [activeCompPath, projectIdRef, showToast, params],
+  );
+
+  const ungroupSelection = useCallback(
+    async (group: DomEditSelection): Promise<void> => {
+      const pid = projectIdRef.current;
+      if (!pid) return;
+      const targetPath = group.sourceFile || activeCompPath || "index.html";
+
+      try {
+        await commitStructuralMutation(
+          pid,
+          targetPath,
+          "unwrap-elements",
+          { target: buildDomEditPatchTarget(group) },
+          "Ungroup elements",
+          params,
+        );
+      } catch (error) {
+        showToast(error instanceof Error ? error.message : "Failed to ungroup elements", "error");
+      }
+    },
+    [activeCompPath, projectIdRef, showToast, params],
+  );
+
+  return { groupSelection, ungroupSelection };
+}

package/src/hooks/useGsapSelectionHandlers.ts

@@ -2,6 +2,7 @@ import { useCallback, useRef } from "react";
 import type { DomEditSelection } from "../components/editor/domEditing";
 import { usePlayerStore } from "../player";
 import { trackStudioSaveFailure } from "../utils/studioSaveDiagnostics";
+import { trackStudioEvent } from "../utils/studioTelemetry";
 
 /**
  * Thin useCallback wrappers that guard on `domEditSelection` before
@@ -136,6 +137,7 @@ export function useGsapSelectionHandlers({
     (targetSelector: string) => {
       const sel = domEditSelection ?? lastSelectionRef.current;
       if (!sel) return;
+      trackStudioEvent("keyframe", { action: "delete_all" });
       deleteAllForSelector(sel, targetSelector);
     },
     [domEditSelection, deleteAllForSelector],
@@ -206,6 +208,7 @@ export function useGsapSelectionHandlers({
     ) => {
       const sel = selectionOverride ?? domEditSelection ?? lastSelectionRef.current;
       if (!sel) return;
+      trackStudioEvent("keyframe", { action: "add", property });
       addKeyframe(sel, animId, percentage, property, value);
     },
     [domEditSelection, addKeyframe],
@@ -224,6 +227,7 @@ export function useGsapSelectionHandlers({
     (animId: string, percentage: number, selectionOverride?: DomEditSelection | null) => {
       const sel = selectionOverride ?? domEditSelection ?? lastSelectionRef.current;
       if (!sel) return;
+      trackStudioEvent("keyframe", { action: "remove" });
       removeKeyframe(sel, animId, percentage);
     },
     [domEditSelection, removeKeyframe],