@hyperframes/studio 0.7.14 → 0.7.16

package/src/components/editor/manualOffsetDrag.ts

@@ -209,6 +209,22 @@ export function applyManualOffsetDragMatrix(matrix: ManualOffsetDragMatrix, poin
   };
 }
 
+/**
+ * The perspective w-divisor (matrix3d m44) of the element's current transform.
+ * For a plain `translateZ(z)` under `perspective(p)`, m44 = (p - z) / p, so the
+ * element renders 1/m44× larger and a translate of `d` composition px moves
+ * `d / m44` px on screen. Returns 1 for 2D transforms (no foreshortening). Used
+ * to keep the drag offset → screen-movement mapping correct for depth elements,
+ * which the flat-scale fast path below would otherwise get wrong by 1/m44.
+ */
+function readTransformWDivisor(element: HTMLElement): number {
+  const t = element.ownerDocument.defaultView?.getComputedStyle(element).transform;
+  if (!t || !t.startsWith("matrix3d(")) return 1;
+  const parts = t.slice("matrix3d(".length, -1).split(",");
+  const w = Number.parseFloat(parts[15] ?? "");
+  return Number.isFinite(w) && w > 0 ? w : 1;
+}
+
 export function measureManualOffsetDragScreenToOffsetMatrix(
   element: HTMLElement,
   initialOffset: { x: number; y: number },
@@ -221,7 +237,11 @@ export function measureManualOffsetDragScreenToOffsetMatrix(
   ) {
     const sx = options.scaleX || 1;
     const sy = options.scaleY || 1;
-    return { ok: true, matrix: { a: 1 / sx, b: 0, c: 0, d: 1 / sy } };
+    // Fold in the perspective foreshortening: a depth element (z≠0) moves
+    // 1/m44× faster on screen than its flat scale implies, so the screen→offset
+    // matrix must scale by m44 or the element outruns the pointer/overlay.
+    const w = readTransformWDivisor(element);
+    return { ok: true, matrix: { a: w / sx, b: 0, c: 0, d: w / sy } };
   }
 
   const probeSize = options.probeSize ?? DEFAULT_OFFSET_PROBE_PX;
@@ -360,6 +380,7 @@ export function createManualOffsetDragMember(input: {
     // drag is acceptable — the final committed position is always exact.
     const scaleX = input.rect.editScaleX || 1;
     const scaleY = input.rect.editScaleY || 1;
+    const w = readTransformWDivisor(input.element);
     return {
       ok: true,
       member: {
@@ -370,7 +391,7 @@ export function createManualOffsetDragMember(input: {
         baseGsap,
         initialPathOffset,
         gestureToken,
-        screenToOffset: { a: 1 / scaleX, b: 0, c: 0, d: 1 / scaleY },
+        screenToOffset: { a: w / scaleX, b: 0, c: 0, d: w / scaleY },
         originRect: input.rect,
       },
     };

package/src/components/editor/motionPathCommit.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi } from "vitest";
-import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { GsapAnimation } from "@hyperframes/parsers/gsap-parser";
 import { editableAnimationId } from "./motionPathSelection";
 import {
   commitNode,

package/src/components/editor/motionPathSelection.ts

@@ -3,7 +3,7 @@
  * Shared by the overlay and its diagnostics (kept here to avoid a circular
  * import between the two).
  */
-import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { GsapAnimation } from "@hyperframes/parsers/gsap-parser";
 import type { DomEditSelection } from "./domEditing";
 
 export function selectorFor(sel: DomEditSelection | null): string | null {

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

@@ -2,7 +2,7 @@ import { parseCssColor, type ParsedColor } from "./colorValue";
 import { COMMON_LOCAL_FONT_FAMILIES } from "./fontCatalog";
 import type { DomEditSelection } from "./domEditing";
 import type { ImportedFontAsset } from "./fontAssets";
-import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { GsapAnimation } from "@hyperframes/parsers/gsap-parser";
 import { roundToCenti } from "../../utils/rounding";
 
 export interface PropertyPanelProps {
@@ -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>;
@@ -29,7 +31,7 @@ export interface PropertyPanelProps {
   fontAssets?: ImportedFontAsset[];
   onImportFonts?: (files: FileList | File[]) => Promise<ImportedFontAsset[]>;
   previewIframeRef?: React.RefObject<HTMLIFrameElement | null>;
-  gsapAnimations?: import("@hyperframes/core/gsap-parser").GsapAnimation[];
+  gsapAnimations?: import("@hyperframes/parsers/gsap-parser").GsapAnimation[];
   gsapMultipleTimelines?: boolean;
   gsapUnsupportedTimelinePattern?: boolean;
   onUpdateGsapProperty?: (animId: string, prop: string, value: number | string) => void;
@@ -49,13 +51,13 @@ export interface PropertyPanelProps {
     config: {
       enabled: boolean;
       autoRotate?: boolean | number;
-      segments?: import("@hyperframes/core/gsap-parser").ArcPathSegment[];
+      segments?: import("@hyperframes/parsers/gsap-parser").ArcPathSegment[];
     },
   ) => void;
   onUpdateArcSegment?: (
     animId: string,
     segmentIndex: number,
-    update: Partial<import("@hyperframes/core/gsap-parser").ArcPathSegment>,
+    update: Partial<import("@hyperframes/parsers/gsap-parser").ArcPathSegment>,
   ) => void;
   /** Unroll computed (helper/loop) tweens into literal tweens for direct editing. */
   onUnroll?: (animationId: string) => 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 } : {}),
+  };
+}