@hyperframes/studio 0.7.15 → 0.7.17

package/src/components/editor/propertyPanel3dTransform.tsx

@@ -6,6 +6,20 @@ import { KeyframeNavigation } from "./KeyframeNavigation";
 import { formatPxMetricValue, parsePxMetricValue, RESPONSIVE_GRID } from "./propertyPanelHelpers";
 import { Transform3DCube, type CubePose } from "./Transform3DCube";
 
+// translateZ only foreshortens under a perspective lens. Rather than hardcode one
+// (an arbitrary px value reads wrong at different canvas sizes), derive it from the
+// element's composition: perspective = composition height puts the virtual camera
+// one comp-height back, a natural ~53° vertical FOV that looks the same whether the
+// canvas is 720p or 4K. Falls back to the element's own height only if the comp size
+// can't be read (detached/unmeasured), never to a fixed magic number.
+function naturalDepthPerspective(el: HTMLElement | null | undefined): number {
+  if (!el) return 0;
+  const root = el.closest("[data-hf-inner-root],[data-composition-id]") as HTMLElement | null;
+  const compHeight = root?.offsetHeight || el.ownerDocument?.documentElement?.clientHeight || 0;
+  if (compHeight > 0) return Math.round(compHeight);
+  return Math.round((el.offsetHeight || 0) * 4) || 0;
+}
+
 type KeyframeEntry = Array<{
   percentage: number;
   properties: Record<string, number | string>;
@@ -38,17 +52,10 @@ interface PropertyPanel3dTransformProps {
   onLivePreviewProps?: (element: DomEditSelection, props: Record<string, number>) => void;
 }
 
-type CommitAnimatedProperty = (
-  element: DomEditSelection,
-  property: string,
-  value: number,
-) => Promise<void>;
-
 /** The draggable cube + its commit/recenter/live-preview wiring. */
 function Cube3dControl({
   element,
   gsapRuntimeValues,
-  onCommitAnimatedProperty,
   onCommitAnimatedProperties,
   onLivePreviewProps,
   onKeyframe,
@@ -56,8 +63,7 @@ function Cube3dControl({
 }: {
   element: DomEditSelection;
   gsapRuntimeValues: Record<string, number>;
-  onCommitAnimatedProperty: CommitAnimatedProperty;
-  onCommitAnimatedProperties?: (
+  onCommitAnimatedProperties: (
     element: DomEditSelection,
     props: Record<string, number | string>,
   ) => Promise<void>;
@@ -70,6 +76,15 @@ function Cube3dControl({
     rotationY: gsapRuntimeValues.rotationY ?? 0,
     rotationZ: gsapRuntimeValues.rotationZ ?? 0,
   };
+  // Comp-derived lens (see naturalDepthPerspective) applied the first time depth is
+  // set, so the scene's foreshortening scales with the canvas instead of a magic 800.
+  const depthPerspective = naturalDepthPerspective(element.element);
+  // A gentle, fixed "depth pose" tilt (degrees) dropped on a flat element the first
+  // time it gets depth, so translateZ reads as 3D foreshortening instead of a plain
+  // resize — small enough to look like a premium card, not a flip.
+  const DEPTH_POSE_X = 10;
+  const DEPTH_POSE_Y = -15;
+  const isFlat = Math.round(pose.rotationX) === 0 && Math.round(pose.rotationY) === 0;
   // Commit only the rotation axes the drag actually changed (each rounded to a
   // whole degree). Reuses the keyframe-aware animated-property commit, so a drag
   // at the playhead writes/updates a keyframe just like the numeric fields.
@@ -82,13 +97,8 @@ function Cube3dControl({
     const axes = Object.keys(changedProps);
     if (axes.length === 0) return;
     // ONE keyframe for the whole pose change — avoids per-axis commits racing into
-    // adjacent duplicate keyframes. Fall back to per-axis if no batched commit.
-    if (onCommitAnimatedProperties) {
-      void onCommitAnimatedProperties(element, changedProps);
-    } else {
-      for (const [axis, v] of Object.entries(changedProps))
-        onCommitAnimatedProperty(element, axis, v);
-    }
+    // adjacent duplicate keyframes.
+    void onCommitAnimatedProperties(element, changedProps);
   };
   const recenter = () => {
     // ONE commit for the whole reset — six per-axis commits meant six soft-reloads
@@ -101,15 +111,10 @@ function Cube3dControl({
       scale: 1,
       transformPerspective: 0,
     };
-    if (onCommitAnimatedProperties) {
-      void onCommitAnimatedProperties(element, identity);
-    } else {
-      for (const [prop, v] of Object.entries(identity))
-        void onCommitAnimatedProperty(element, prop, v);
-    }
+    void onCommitAnimatedProperties(element, identity);
   };
   // Immediate element feedback while dragging — set the live transform without a
-  // source write; the release commits via onCommitAnimatedProperty.
+  // source write; the release commits via commitPose.
   const livePreview = (next: CubePose) =>
     onLivePreviewProps?.(element, {
       rotationX: next.rotationX,
@@ -123,18 +128,54 @@ function Cube3dControl({
         <Transform3DCube
           pose={pose}
           perspective={gsapRuntimeValues.transformPerspective ?? 0}
+          defaultPerspective={depthPerspective}
+          z={gsapRuntimeValues.z ?? 0}
           onPoseDraft={livePreview}
           onPoseCommit={commitPose}
-          onPerspectiveDraft={(px) => onLivePreviewProps?.(element, { transformPerspective: px })}
-          onPerspectiveCommit={(px) =>
-            void onCommitAnimatedProperty(element, "transformPerspective", px)
-          }
+          onDepthDraft={(z) => {
+            // Preview WITH a lens so depth is visible while scrolling — the same
+            // default the commit applies, so the element doesn't snap on release.
+            const preview: Record<string, number> = gsapRuntimeValues.transformPerspective
+              ? { z }
+              : { z, transformPerspective: depthPerspective };
+            // Depth-pose preview: a flat element only scales under Z, so mirror the
+            // commit and preview the gentle tilt that makes the depth read as 3D.
+            if (isFlat) {
+              preview.rotationX = DEPTH_POSE_X;
+              preview.rotationY = DEPTH_POSE_Y;
+            }
+            onLivePreviewProps?.(element, preview);
+          }}
+          onDepthCommit={(z) => {
+            // Best-UX depth: scroll moves Z, and a 3D transform always has a lens —
+            // like an After Effects camera. translateZ is invisible without a
+            // perspective, so the FIRST time depth is added (Perspective still 0) we
+            // set a sensible comp-derived lens ONCE. Every later scroll touches Z
+            // only, and Perspective stays an independent, editable field. The cube's
+            // scroll is clamped in front of the lens, so Z can't run away past it.
+            const props: Record<string, number> = { z };
+            if (!gsapRuntimeValues.transformPerspective && depthPerspective > 0) {
+              props.transformPerspective = depthPerspective;
+            }
+            // Depth-pose: a flat element (no tilt) only scales under Z — it can't read
+            // as depth. So the first time depth lands on a flat element, also drop a
+            // gentle fixed tilt; the foreshortening makes depth read as 3D IN PLACE
+            // (no screen travel, per-element lens unchanged). Once the element has any
+            // tilt, depth scrolls touch Z only. Reset tilt to 0 to go flat again.
+            if (isFlat) {
+              props.rotationX = DEPTH_POSE_X;
+              props.rotationY = DEPTH_POSE_Y;
+            }
+            // One commit for all props so the writes can't race read-modify-write on
+            // the same script (which dropped a prop and reverted after a seek).
+            void onCommitAnimatedProperties(element, props);
+          }}
           onRecenter={recenter}
           onKeyframe={onKeyframe}
           keyframed={keyframed}
         />
         <p className="mt-1 text-center text-[9px] leading-snug text-neutral-600">
-          Drag to tilt · Shift-drag to roll
+          Drag to tilt · Shift-drag to roll · Scroll for depth
         </p>
       </div>
     </div>
@@ -286,11 +327,10 @@ export function PropertyPanel3dTransform({
       </button>
       {collapsed ? null : (
         <>
-          {onCommitAnimatedProperty && (
+          {onCommitAnimatedProperties && (
             <Cube3dControl
               element={element}
               gsapRuntimeValues={gsapRuntimeValues}
-              onCommitAnimatedProperty={onCommitAnimatedProperty}
               onCommitAnimatedProperties={onCommitAnimatedProperties}
               onLivePreviewProps={onLivePreviewProps}
               keyframed={(gsapKeyframes ?? []).some(

package/src/components/editor/propertyPanelHelpers.ts

@@ -13,6 +13,8 @@ export interface PropertyPanelProps {
   multiSelectCount?: number;
   copiedAgentPrompt: boolean;
   onClearSelection: () => void;
+  /** Dissolve the selected data-hf-group wrapper (shown only for group selections). */
+  onUngroup?: () => void;
   onSetStyle: (prop: string, value: string) => void | Promise<void>;
   onSetAttribute: (attr: string, value: string) => void | Promise<void>;
   onSetAttributeLive: (attr: string, value: string | null) => void | Promise<void>;

package/src/components/editor/useDomEditOverlayRects.ts

@@ -11,6 +11,7 @@ import {
   type ResolvedElementRef,
   groupOverlayItemsEqual,
   isElementVisibleForOverlay,
+  groupAwareOverlayRect,
   rectsEqual,
   resolveElementForOverlay,
   selectionCacheKey,
@@ -155,7 +156,7 @@ export function useDomEditOverlayRects({
         // backgroundless full-bleed scene above a subcomposition), which would wrongly
         // hide the selection box. Occlusion stays for hover, where a false hide is cheap.
         if (el && isElementVisibleForOverlay(el)) {
-          const nextRect = toOverlayRect(overlayEl, iframe, el);
+          const nextRect = groupAwareOverlayRect(overlayEl, iframe, el);
           setOverlayRect(nextRect);
           const descendants = el.querySelectorAll("*");
           if (descendants.length > 0 && descendants.length <= 60) {
@@ -196,9 +197,13 @@ export function useDomEditOverlayRects({
         const liveGroupKeys = new Set<string>();
         for (const groupSelection of group) {
           const key = selectionCacheKey(groupSelection);
+          // Members of the same group collapse to one selection under select-as-unit,
+          // so a multi-select can hold the same group twice — dedupe by key to avoid
+          // duplicate React keys (and a doubled overlay box).
+          if (liveGroupKeys.has(key)) continue;
           liveGroupKeys.add(key);
           const el = resolveGroupElement(doc, groupSelection);
-          const rect = el ? toOverlayRect(overlayEl, iframe, el) : null;
+          const rect = el ? groupAwareOverlayRect(overlayEl, iframe, el) : null;
           if (el && rect)
             nextGroupItems.push({ key, selection: groupSelection, element: el, rect });
         }
@@ -235,7 +240,7 @@ export function useDomEditOverlayRects({
         return;
       }
 
-      setHoverRect(toOverlayRect(overlayEl, iframe, hoverEl));
+      setHoverRect(groupAwareOverlayRect(overlayEl, iframe, hoverEl));
     };
 
     frame = requestAnimationFrame(update);

package/src/components/editor/useMotionPathData.ts

@@ -5,6 +5,38 @@ import { buildMotionPathGeometry, type MotionPathGeometry } from "./motionPathGe
 
 type Rect = { left: number; top: number; width: number; height: number };
 
+// The translate (e/f) components of an element's computed transform, in comp px.
+// A group wrapper dragged via GSAP carries its offset here, not in offsetLeft/Top.
+function transformTranslate(el: HTMLElement): { x: number; y: number } {
+  const t = el.ownerDocument?.defaultView?.getComputedStyle(el).transform;
+  if (!t || t === "none") return { x: 0, y: 0 };
+  const m3 = t.match(/matrix3d\(([^)]+)\)/);
+  if (m3) {
+    const v = m3[1].split(",").map(Number);
+    return { x: v[12] || 0, y: v[13] || 0 };
+  }
+  const m = t.match(/matrix\(([^)]+)\)/);
+  if (m) {
+    const v = m[1].split(",").map(Number);
+    return { x: v[4] || 0, y: v[5] || 0 };
+  }
+  return { x: 0, y: 0 };
+}
+
+// Perspective foreshortening of the element's OWN transform (matrix3d m44). A
+// depth element (translateZ toward the viewer) renders 1/m44× larger, so its
+// animated x/y offsets travel 1/m44× further on screen than the flat preview
+// scale implies. Returns 1 for 2D transforms. The motion path magnifies its
+// offset points by 1/m44 (and de-magnifies pointer→offset) so the drawn path and
+// its draggable nodes track the projected element instead of drifting off it.
+export function transformWDivisor(el: HTMLElement): number {
+  const t = el.ownerDocument?.defaultView?.getComputedStyle(el).transform;
+  if (!t || !t.startsWith("matrix3d(")) return 1;
+  const v = t.slice("matrix3d(".length, -1).split(",");
+  const w = Number.parseFloat(v[15] ?? "");
+  return Number.isFinite(w) && w > 0 ? w : 1;
+}
+
 export function elementHome(el: HTMLElement): { x: number; y: number } {
   let left = 0;
   let top = 0;
@@ -12,6 +44,14 @@ export function elementHome(el: HTMLElement): { x: number; y: number } {
   while (node) {
     left += node.offsetLeft;
     top += node.offsetTop;
+    // Ancestor transforms (e.g. a group wrapper moved via GSAP) shift where the
+    // element actually renders, so the path must anchor on top of them. The element's
+    // OWN transform is excluded — that's the animated offset the path itself draws.
+    if (node !== el) {
+      const t = transformTranslate(node);
+      left += t.x;
+      top += t.y;
+    }
     const parent = node.offsetParent as HTMLElement | null;
     if (!parent || parent.hasAttribute("data-composition-id")) break;
     node = parent;
@@ -62,6 +102,7 @@ export function useMotionPathData(
   geometryResolved: boolean;
   visibleInPreview: boolean;
   home: { x: number; y: number } | null;
+  pScale: number;
 } {
   const [rect, setRect] = useState<Rect | null>(null);
   const [geometry, setGeometry] = useState<MotionPathGeometry | null>(null);
@@ -69,6 +110,9 @@ export function useMotionPathData(
   const geometryResolved = resolvedForRef.current === selector;
   const [visibleInPreview, setVisibleInPreview] = useState(true);
   const [home, setHome] = useState<{ x: number; y: number } | null>(null);
+  // Perspective magnification (1/m44) of the selected element — applied to the
+  // path's offset points so depth (translateZ) elements' paths track on screen.
+  const [pScale, setPScale] = useState(1);
 
   useEffect(() => {
     if (!selector) {
@@ -105,6 +149,8 @@ export function useMotionPathData(
           setHome((prev) =>
             prev && Math.abs(prev.x - h.x) < 0.5 && Math.abs(prev.y - h.y) < 0.5 ? prev : h,
           );
+          const ps = 1 / transformWDivisor(live);
+          setPScale((p) => (Math.abs(p - ps) < 0.001 ? p : ps));
         }
       }
       raf = requestAnimationFrame(tick);
@@ -132,5 +178,5 @@ export function useMotionPathData(
     return () => window.clearInterval(id);
   }, [selector, iframeRef]);
 
-  return { rect, geometry, geometryResolved, visibleInPreview, home };
+  return { rect, geometry, geometryResolved, visibleInPreview, home, pScale };
 }

package/src/contexts/DomEditContext.tsx

@@ -31,6 +31,9 @@ export interface DomEditActionsValue extends Pick<
   | "handleBlockedDomMove"
   | "handleDomManualDragStart"
   | "handleDomEditElementDelete"
+  | "handleGroupSelection"
+  | "handleUngroupSelection"
+  | "setActiveGroupElement"
   | "buildDomSelectionFromTarget"
   | "buildDomSelectionForTimelineElement"
   | "updateDomEditHoverSelection"
@@ -72,6 +75,7 @@ export interface DomEditSelectionValue extends Pick<
   | "domEditSelection"
   | "domEditGroupSelections"
   | "domEditHoverSelection"
+  | "activeGroupElement"
   | "domEditSelectionRef"
   | "selectedGsapAnimations"
   | "gsapMultipleTimelines"
@@ -138,6 +142,10 @@ export function DomEditProvider({
     handleBlockedDomMove,
     handleDomManualDragStart,
     handleDomEditElementDelete,
+    handleGroupSelection,
+    handleUngroupSelection,
+    setActiveGroupElement,
+    activeGroupElement,
     buildDomSelectionFromTarget,
     buildDomSelectionForTimelineElement,
     updateDomEditHoverSelection,
@@ -216,6 +224,9 @@ export function DomEditProvider({
       handleBlockedDomMove,
       handleDomManualDragStart,
       handleDomEditElementDelete,
+      handleGroupSelection,
+      handleUngroupSelection,
+      setActiveGroupElement,
       buildDomSelectionFromTarget,
       buildDomSelectionForTimelineElement,
       updateDomEditHoverSelection,
@@ -277,6 +288,9 @@ export function DomEditProvider({
       handleBlockedDomMove,
       handleDomManualDragStart,
       handleDomEditElementDelete,
+      handleGroupSelection,
+      handleUngroupSelection,
+      setActiveGroupElement,
       buildDomSelectionFromTarget,
       buildDomSelectionForTimelineElement,
       updateDomEditHoverSelection,
@@ -319,6 +333,7 @@ export function DomEditProvider({
       domEditSelection,
       domEditGroupSelections,
       domEditHoverSelection,
+      activeGroupElement,
       domEditSelectionRef,
       selectedGsapAnimations,
       gsapMultipleTimelines,
@@ -332,6 +347,7 @@ export function DomEditProvider({
       domEditSelection,
       domEditGroupSelections,
       domEditHoverSelection,
+      activeGroupElement,
       domEditSelectionRef,
       selectedGsapAnimations,
       gsapMultipleTimelines,

package/src/contexts/TimelineEditContext.tsx

@@ -39,7 +39,6 @@ export function TimelineEditProvider({
       value.onDeleteKeyframe,
       value.onDeleteAllKeyframes,
       value.onChangeKeyframeEase,
-      value.onMoveKeyframe,
       value.onToggleKeyframeAtPlayhead,
     ],
   );

package/src/hooks/gsapRuntimeBridge.ts

@@ -241,8 +241,15 @@ export async function tryGsapDragIntercept(
   // place (idempotent), else add a new one. This also covers the stale-cache
   // phantom — committing a set is correct because the element genuinely has no live motion.
   const hasNonHold = hasNonHoldTweenForElement(iframe, selector);
-
-  if (!hasNonHold) {
+  // A KEYFRAMED position tween — even one that's currently a flat constant ("hold",
+  // e.g. 0% and 100% identical) — is still an animation the user is building, so a
+  // drag must add/update a keyframe, NOT fall back to a static `set`. Without this,
+  // dragging an element whose position tween is constant writes a `gsap.set` that
+  // fights the tween (the "drag didn't create a keyframe / didn't persist" bug). The
+  // static path is only for elements with NO keyframed position tween (truly static,
+  // or just a leftover position-hold `set`).
+  const hasKeyframedPosTween = !!posAnim?.keyframes;
+  if (!hasNonHold && !hasKeyframedPosTween) {
     const existingSet =
       posAnim && posAnim.method === "set" && posAnim.targetSelector === selector
         ? posAnim

package/src/hooks/gsapTweenSynth.ts

@@ -0,0 +1,64 @@
+import type {
+  GsapAnimation,
+  GsapKeyframesData,
+  GsapPercentageKeyframe,
+} from "@hyperframes/core/gsap-parser";
+import { PROPERTY_DEFAULTS } from "./gsapShared";
+
+export 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
+export 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 } : {}),
+  };
+}

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();
       }