@hyperframes/studio 0.7.14 → 0.7.16

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],

package/src/hooks/useGsapTweenCache.ts

@@ -1,6 +1,5 @@
 import { useEffect, useMemo, useRef, useState, useCallback } from "react";
 import type { GsapAnimation, GsapKeyframesData, ParsedGsap } from "@hyperframes/core/gsap-parser";
-import type { GsapPercentageKeyframe } from "@hyperframes/core/gsap-parser";
 import { isStudioHoldSet } from "@hyperframes/core/gsap-parser";
 import { usePlayerStore } from "../player/store/playerStore";
 import { readRuntimeKeyframes, scanAllRuntimeKeyframes } from "./gsapRuntimeBridge";
@@ -8,63 +7,8 @@ import {
   clearKeyframeCacheForElement,
   clearKeyframeCacheForFile,
 } from "./gsapKeyframeCacheHelpers";
-import { PROPERTY_DEFAULTS, toAbsoluteTime } from "./gsapShared";
-
-function deduplicateKeyframes(keyframes: GsapPercentageKeyframe[]): GsapPercentageKeyframe[] {
-  const byPct = new Map<number, GsapPercentageKeyframe>();
-  for (const kf of keyframes) {
-    const existing = byPct.get(kf.percentage);
-    if (existing) {
-      existing.properties = { ...existing.properties, ...kf.properties };
-      if (kf.ease) existing.ease = kf.ease;
-    } else {
-      byPct.set(kf.percentage, { ...kf, properties: { ...kf.properties } });
-    }
-  }
-  return Array.from(byPct.values()).sort((a, b) => a.percentage - b.percentage);
-}
-
-// fallow-ignore-next-line complexity
-function synthesizeFlatTweenKeyframes(anim: GsapAnimation): GsapKeyframesData | null {
-  if (anim.method === "set") {
-    // A `set` is a STATIC HOLD — a value applied at one point, not an animated
-    // keyframe. It must NOT synthesize a keyframe, or the timeline + panel show a
-    // phantom diamond for a value that doesn't animate. This holds for a base
-    // `gsap.set` (off-timeline) AND an on-timeline `tl.set`, and aligns the AST
-    // path with the runtime scan, which already skips every zero-duration set.
-    return null;
-  }
-  const toProps = anim.properties;
-  const fromProps = anim.fromProperties;
-  if (!toProps || Object.keys(toProps).length === 0) return null;
-
-  const startProps: Record<string, number | string> = {};
-  const endProps: Record<string, number | string> = {};
-
-  if (anim.method === "from") {
-    for (const [k, v] of Object.entries(toProps)) {
-      startProps[k] = v;
-      endProps[k] = PROPERTY_DEFAULTS[k] ?? 0;
-    }
-  } else if (anim.method === "fromTo" && fromProps) {
-    Object.assign(startProps, fromProps);
-    Object.assign(endProps, toProps);
-  } else {
-    for (const [k, v] of Object.entries(toProps)) {
-      startProps[k] = PROPERTY_DEFAULTS[k] ?? 0;
-      endProps[k] = v;
-    }
-  }
-
-  return {
-    format: "percentage",
-    keyframes: [
-      { percentage: 0, properties: startProps },
-      { percentage: 100, properties: endProps },
-    ],
-    ...(anim.ease ? { ease: anim.ease } : {}),
-  };
-}
+import { toAbsoluteTime } from "./gsapShared";
+import { deduplicateKeyframes, synthesizeFlatTweenKeyframes } from "./gsapTweenSynth";
 
 function extractIdFromSelector(selector: string): string | null {
   const match = selector.match(/^#([\w-]+)/);
@@ -176,6 +120,37 @@ export async function fetchParsedAnimations(
   }
 }
 
+/**
+ * Clip-relative timing basis for an element. Sub-composition internals (e.g. pills
+ * inside a scene) aren't timeline clips themselves — they're derived at expand time
+ * — so they're absent from `elements`. Without a basis, elDuration defaulted to 1
+ * and clip-relative keyframe percentages blew past 100% (rendering off the clip).
+ * Fall back to the sub-comp HOST's bounds, resolved via domClipChildren (the host's
+ * data-composition-src is stripped in the rendered DOM, so we can't query it).
+ */
+function resolveClipTimingBasis(
+  elementId: string,
+  sourceFile: string,
+  elements: ReadonlyArray<{
+    domId?: string;
+    key?: string;
+    id: string;
+    start: number;
+    duration: number;
+  }>,
+  domClipChildren: ReadonlyArray<{ id: string; hostId: string }>,
+): { elStart: number; elDuration: number } {
+  const direct = elements.find(
+    (el) => el.domId === elementId || (el.key ?? el.id) === `${sourceFile}#${elementId}`,
+  );
+  if (direct) return { elStart: direct.start, elDuration: direct.duration };
+  const hostId = domClipChildren.find((c) => c.id === elementId)?.hostId;
+  const host = hostId
+    ? elements.find((el) => el.domId === hostId || (el.key ?? el.id) === `index.html#${hostId}`)
+    : undefined;
+  return { elStart: host?.start ?? 0, elDuration: host?.duration ?? 1 };
+}
+
 export function useGsapAnimationsForElement(
   projectId: string | null,
   sourceFile: string,
@@ -192,6 +167,11 @@ export function useGsapAnimationsForElement(
   const [unsupportedTimelinePattern, setUnsupportedTimelinePattern] = useState(false);
   const lastFetchKeyRef = useRef("");
   const retryTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  // Re-run the per-element cache populate when sub-comp DOM children appear, so a
+  // sub-comp element gets its host-relative keyframe percentages (not elDuration=1).
+  const domClipChildrenKey = usePlayerStore((s) =>
+    s.domClipChildren.map((c) => `${c.id}<${c.hostId}`).join("|"),
+  );
 
   useEffect(() => {
     const targetKey = target?.id ?? target?.selector ?? "";
@@ -351,12 +331,13 @@ export function useGsapAnimationsForElement(
 
     // Resolve the element's time range from the player store so we can
     // convert tween-relative keyframe percentages to clip-relative ones.
-    const { elements } = usePlayerStore.getState();
-    const timelineEl = elements.find(
-      (el) => el.domId === elementId || (el.key ?? el.id) === `${sourceFile}#${elementId}`,
+    const { elements, domClipChildren } = usePlayerStore.getState();
+    const { elStart, elDuration } = resolveClipTimingBasis(
+      elementId,
+      sourceFile,
+      elements,
+      domClipChildren,
     );
-    const elStart = timelineEl?.start ?? 0;
-    const elDuration = timelineEl?.duration ?? 1;
 
     const allKeyframes: Array<
       GsapKeyframesData["keyframes"][0] & { tweenPercentage?: number; propertyGroup?: string }
@@ -419,7 +400,8 @@ export function useGsapAnimationsForElement(
     // PropertyPanel reads the cache by bare elementId (without sourceFile prefix),
     // so write a duplicate entry under the bare key for cross-component lookups.
     setKeyframeCache(elementId, merged);
-  }, [elementId, sourceFile, animations]);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [elementId, sourceFile, animations, domClipChildrenKey]);
 
   return { animations, multipleTimelines, unsupportedTimelinePattern };
 }
@@ -442,13 +424,19 @@ export function usePopulateKeyframeCacheForFile(
   iframeRef?: React.RefObject<HTMLIFrameElement | null>,
 ): void {
   const elementCount = usePlayerStore((s) => s.elements.length);
+  // Re-run when sub-comp DOM children appear (they supply the host bounds the
+  // clip-relative keyframe percentages are computed against; without this the
+  // cache is computed once before they exist and the percentages stay wrong).
+  const domClipChildrenKey = usePlayerStore((s) =>
+    s.domClipChildren.map((c) => `${c.id}<${c.hostId}`).join("|"),
+  );
   const lastFetchKeyRef = useRef("");
 
   const runtimeScanDoneRef = useRef("");
   const astFetchDoneRef = useRef("");
 
   useEffect(() => {
-    const fetchKey = `kf-cache:${projectId}:${sourceFile}:${version}:${elementCount}`;
+    const fetchKey = `kf-cache:${projectId}:${sourceFile}:${version}:${elementCount}:${domClipChildrenKey}`;
     if (fetchKey === lastFetchKeyRef.current) return;
     lastFetchKeyRef.current = fetchKey;
     runtimeScanDoneRef.current = "";
@@ -461,7 +449,7 @@ export function usePopulateKeyframeCacheForFile(
       if (!parsed) return;
       const { setKeyframeCache } = usePlayerStore.getState();
       clearKeyframeCacheForFile(sf);
-      const { elements } = usePlayerStore.getState();
+      const { elements, domClipChildren } = usePlayerStore.getState();
       const doc = iframeRef?.current?.contentDocument;
       const mergedByElement = new Map<string, GsapKeyframesData>();
       for (const anim of parsed.animations) {
@@ -482,11 +470,7 @@ export function usePopulateKeyframeCacheForFile(
         // Attribute the tween to every element it animates (handles class /
         // group / descendant selectors, not just `#id`).
         for (const id of resolveSelectorElementIds(anim.targetSelector, doc)) {
-          const timelineEl = elements.find(
-            (el) => el.domId === id || (el.key ?? el.id) === `${sf}#${id}`,
-          );
-          const elStart = timelineEl?.start ?? 0;
-          const elDuration = timelineEl?.duration ?? 1;
+          const { elStart, elDuration } = resolveClipTimingBasis(id, sf, elements, domClipChildren);
           const clipKeyframes = kfData.keyframes.map((kf) => {
             const absTime = toAbsoluteTime(tweenPos, tweenDur, kf.percentage);
             // 0.001% precision (matching useGsapAnimationsForElement above) so a
@@ -524,7 +508,7 @@ export function usePopulateKeyframeCacheForFile(
     // iframeRef is read for DOM selector resolution but intentionally not a dep
     // (it's a stable ref; the separate runtime-scan effect owns iframe timing).
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [projectId, sourceFile, version, elementCount]);
+  }, [projectId, sourceFile, version, elementCount, domClipChildrenKey]);
 
   // Separate effect for runtime keyframe discovery — polls until the iframe
   // has loaded GSAP timelines, independent of the AST fetch lifecycle.

package/src/hooks/usePreviewInteraction.ts

@@ -3,6 +3,7 @@ import { liveTime, usePlayerStore } from "../player";
 import { pauseStudioPreviewPlayback } from "../utils/studioPreviewHelpers";
 import { STUDIO_PREVIEW_SELECTION_ENABLED } from "../components/editor/manualEditingAvailability";
 import { type DomEditSelection } from "../components/editor/domEditing";
+import { trackStudioEvent } from "../utils/studioTelemetry";
 
 // ── Types ──
 
@@ -20,13 +21,19 @@ export interface UsePreviewInteractionParams {
   resolveDomSelectionFromPreviewPoint: (
     clientX: number,
     clientY: number,
-    options?: { preferClipAncestor?: boolean; skipSourceProbe?: boolean },
+    options?: {
+      preferClipAncestor?: boolean;
+      skipSourceProbe?: boolean;
+      activeGroupElement?: HTMLElement | null;
+    },
   ) => Promise<DomEditSelection | null>;
   resolveAllDomSelectionsFromPreviewPoint: (
     clientX: number,
     clientY: number,
   ) => Promise<DomEditSelection[]>;
   updateDomEditHoverSelection: (selection: DomEditSelection | null) => void;
+  /** Drill into a group (double-click on the canvas) so its children become selectable. */
+  setActiveGroupElement: (el: HTMLElement | null) => void;
 
   onClickToSource?: (selection: DomEditSelection) => void;
 }
@@ -41,6 +48,12 @@ interface ClickCycleState {
 
 const CYCLE_RADIUS_PX = 6;
 const CYCLE_WINDOW_MS = 600;
+// Manual double-click window. `e.detail` can't be trusted here: the first click
+// selects the group and re-renders the overlay, so the second click lands on a
+// fresh element and the browser's native click-counter resets to 1 — drill-in
+// (which keyed off `e.detail >= 2`) never fired. We track time+position instead.
+const DOUBLE_CLICK_MS = 400;
+const DOUBLE_CLICK_RADIUS_PX = 6;
 
 // ── Hook ──
 
@@ -53,15 +66,47 @@ export function usePreviewInteraction({
   resolveDomSelectionFromPreviewPoint,
   resolveAllDomSelectionsFromPreviewPoint,
   updateDomEditHoverSelection,
+  setActiveGroupElement,
   onClickToSource,
 }: UsePreviewInteractionParams) {
   const cycleRef = useRef<ClickCycleState | null>(null);
+  const lastDownRef = useRef<{ t: number; x: number; y: number } | null>(null);
 
   const handlePreviewCanvasMouseDown = useCallback(
     // fallow-ignore-next-line complexity
     async (e: React.MouseEvent<HTMLDivElement>, options?: { preferClipAncestor?: boolean }) => {
       if (!STUDIO_PREVIEW_SELECTION_ENABLED || captionEditMode || compositionLoading) return;
 
+      // Manual double-click detection (see DOUBLE_CLICK_MS): the first click
+      // re-renders the overlay so `e.detail` never reaches 2 on the canvas.
+      const downTs = Date.now();
+      const lastDown = lastDownRef.current;
+      const isDoubleClick =
+        e.detail >= 2 ||
+        (lastDown != null &&
+          downTs - lastDown.t < DOUBLE_CLICK_MS &&
+          Math.hypot(e.clientX - lastDown.x, e.clientY - lastDown.y) < DOUBLE_CLICK_RADIUS_PX);
+      lastDownRef.current = { t: downTs, x: e.clientX, y: e.clientY };
+
+      // Double-click a group → drill into it and select the child under the
+      // pointer (resolve with the group as the explicit drill-in scope, since the
+      // activeGroupElement state hasn't re-rendered yet within this handler).
+      if (isDoubleClick && !e.shiftKey) {
+        const hit = await resolveDomSelectionFromPreviewPoint(e.clientX, e.clientY);
+        if (hit?.element.hasAttribute("data-hf-group")) {
+          e.preventDefault();
+          e.stopPropagation();
+          cycleRef.current = null;
+          trackStudioEvent("group", { action: "drill_in" });
+          setActiveGroupElement(hit.element);
+          const child = await resolveDomSelectionFromPreviewPoint(e.clientX, e.clientY, {
+            activeGroupElement: hit.element,
+          });
+          applyDomSelection(child ?? hit);
+          return;
+        }
+      }
+
       const now = Date.now();
       const prev = cycleRef.current;
       const dx = prev ? e.clientX - prev.x : Infinity;
@@ -96,9 +141,21 @@ export function usePreviewInteraction({
       }
 
       // Fresh click — resolve topmost element
-      const nextSelection = await resolveDomSelectionFromPreviewPoint(e.clientX, e.clientY, {
+      let nextSelection = await resolveDomSelectionFromPreviewPoint(e.clientX, e.clientY, {
         preferClipAncestor: options?.preferClipAncestor ?? false,
       });
+      // A null result while drilled into a group means the click landed OUTSIDE that
+      // group (resolveGroupCapture → out-of-scope). Drill-in isn't sticky: exit it and
+      // re-resolve at the top level so this click selects whatever's there (or the
+      // group as a unit). Without this, a stale drill-in keeps selecting children and
+      // the "first click selects the group" expectation breaks.
+      if (!nextSelection) {
+        setActiveGroupElement(null);
+        nextSelection = await resolveDomSelectionFromPreviewPoint(e.clientX, e.clientY, {
+          preferClipAncestor: options?.preferClipAncestor ?? false,
+          activeGroupElement: null,
+        });
+      }
       if (!nextSelection) {
         cycleRef.current = null;
         applyDomSelection(null, { revealPanel: false });
@@ -125,6 +182,7 @@ export function usePreviewInteraction({
       onClickToSource,
       resolveAllDomSelectionsFromPreviewPoint,
       resolveDomSelectionFromPreviewPoint,
+      setActiveGroupElement,
     ],
   );
 

package/src/player/components/ShortcutsPanel.tsx

@@ -36,6 +36,8 @@ const SHORTCUT_SECTIONS = [
       { key: "⌘V", label: "Paste element" },
       { key: "⌘X", label: "Cut element" },
       { key: "S", label: "Split clip at playhead" },
+      { key: "⌘G", label: "Group elements" },
+      { key: "⌘⇧G", label: "Ungroup" },
       { key: "Del", label: "Delete selected element" },
     ],
   },

package/src/player/components/Timeline.tsx

@@ -20,7 +20,6 @@ import {
   type KeyframeDiamondContextMenuState,
 } from "./KeyframeDiamondContextMenu";
 import { useTimelineClipDrag } from "./useTimelineClipDrag";
-import { snapKeyframePctToBeat } from "./timelineEditing";
 import { ClipContextMenu } from "./ClipContextMenu";
 import {
   GUTTER,
@@ -87,7 +86,6 @@ export const Timeline = memo(function Timeline({
     onDeleteKeyframe,
     onDeleteAllKeyframes,
     onChangeKeyframeEase,
-    onMoveKeyframe,
   } = useResolvedTimelineEditCallbacks({
     onMoveElement: onMoveElementOverride,
     onResizeElement: onResizeElementOverride,
@@ -481,19 +479,6 @@ export const Timeline = memo(function Timeline({
           onShiftClickKeyframe={(elId, pct) => {
             toggleSelectedKeyframe(`${elId}:${pct}`);
           }}
-          onDragKeyframe={(el, oldPct, newPct) => {
-            onMoveKeyframe?.(el, oldPct, newPct);
-          }}
-          onSnapKeyframePct={(el, pct) =>
-            snapKeyframePctToBeat(el, pct, adjustedBeatAnalysis?.beatTimes, pps)
-          }
-          onPickKeyframeElement={(el) => {
-            const elKey = el.key ?? el.id;
-            if (selectedElementId !== elKey) {
-              setSelectedElementId(elKey);
-              onSelectElement?.(el);
-            }
-          }}
           onContextMenuKeyframe={(e, elId, pct) => {
             const el = expandedElements.find((x) => (x.key ?? x.id) === elId);
             if (el) {

package/src/player/components/TimelineCanvas.tsx

@@ -91,11 +91,6 @@ interface TimelineCanvasProps {
   currentTime: number;
   onClickKeyframe?: (element: TimelineElement, percentage: number) => void;
   onShiftClickKeyframe?: (elementId: string, percentage: number) => void;
-  onDragKeyframe?: (element: TimelineElement, oldPct: number, newPct: number) => void;
-  /** Snap a keyframe's clip-relative % to the nearest beat (returns unchanged when none in range). */
-  onSnapKeyframePct?: (element: TimelineElement, pct: number) => number;
-  /** Select the element when a keyframe drag starts (loads its GSAP session). */
-  onPickKeyframeElement?: (element: TimelineElement) => void;
   onContextMenuKeyframe?: (e: React.MouseEvent, elementId: string, percentage: number) => void;
   onContextMenuClip?: (e: React.MouseEvent, element: TimelineElement) => void;
   beatAnalysis?: MusicBeatAnalysis | null;
@@ -143,9 +138,6 @@ export const TimelineCanvas = memo(function TimelineCanvas({
   currentTime,
   onClickKeyframe,
   onShiftClickKeyframe,
-  onDragKeyframe,
-  onSnapKeyframePct,
-  onPickKeyframeElement,
   onContextMenuKeyframe,
   onContextMenuClip,
   beatAnalysis,
@@ -446,11 +438,6 @@ export const TimelineCanvas = memo(function TimelineCanvas({
                         selectedKeyframes={selectedKeyframes}
                         onClickKeyframe={(pct) => onClickKeyframe?.(previewElement, pct)}
                         onShiftClickKeyframe={onShiftClickKeyframe}
-                        onDragKeyframe={(oldPct, newPct) =>
-                          onDragKeyframe?.(previewElement, oldPct, newPct)
-                        }
-                        snapPct={(pct) => onSnapKeyframePct?.(previewElement, pct) ?? pct}
-                        onPickForDrag={() => onPickKeyframeElement?.(previewElement)}
                         onContextMenuKeyframe={onContextMenuKeyframe}
                       />
                     )}