@hyperframes/studio 0.8.127 → 0.8.128

package/src/hooks/gsapRuntimeKeyframes.ts

@@ -8,9 +8,12 @@
  * `toAbsoluteTime` + the element's clip start/duration. `scanAllRuntimeKeyframes`
  * does that conversion itself when given a `clipById` map.
  */
-import { buildArcPath, type ArcPathConfig } from "@hyperframes/core/gsap-parser-acorn";
+import type { ArcPathConfig } from "@hyperframes/core/gsap-parser-acorn";
 import { parsePercentageKeyframes, toAbsoluteTime } from "./gsapShared";
+import { timeAtProgress } from "../utils/gsapKeyframeEases";
+import { readMotionPathTween } from "./gsapRuntimeMotionPath";
 import { roundTo3 } from "../utils/rounding";
+import { matchesElement, tweensTargeting } from "./gsapRuntimeTweenIndex";
 import { withParsedStart } from "./gsapParsedTween";
 import { BOX_SIZE_STYLE_PROPS } from "../components/editor/manualEditsDomPatches";
 import { gsapRendersTransform } from "../components/editor/gsapAnimatesProperty";
@@ -48,6 +51,7 @@ export type ReadTween = {
   keyframes: Pct[];
   easeEach?: string;
   arcPath?: ArcPathConfig;
+  runEase?: string;
   /** GSAP's start values when the first keyframe is after 0%. */
   start?: Record<string, number>;
 };
@@ -92,10 +96,6 @@ function timelinesOf(iframe: HTMLIFrameElement | null): Record<string, RuntimeTi
   }
 }
 
-function isXY(p: unknown): p is { x: number; y: number } {
-  return !!p && typeof (p as any).x === "number" && typeof (p as any).y === "number";
-}
-
 /**
  * A tween we must skip when reading keyframes: a zero-duration `set`/hold (incl.
  * the studio pre-keyframe position hold, tagged `data: STUDIO_HOLD_MARKER`).
@@ -107,31 +107,6 @@ function isZeroDurationSet(duration: number): boolean {
   return !(duration > 0);
 }
 
-/** Coordinates + curviness from a live `vars.motionPath` value (object or array form), or null. */
-function coordsFromMotionPath(mp: unknown): {
-  coords: Array<{ x: number; y: number }>;
-  curviness: number;
-  autoRotate: boolean | number;
-  isCubic: boolean;
-} | null {
-  if (!mp || typeof mp !== "object") return null;
-  const obj = mp as Record<string, unknown>;
-  const pathVal = Array.isArray(mp) ? mp : obj.path;
-  if (!Array.isArray(pathVal)) return null;
-  const coords = pathVal.filter(isXY).map((p) => ({ x: p.x, y: p.y }));
-  if (coords.length < 2) return null;
-  const curviness = typeof obj.curviness === "number" ? obj.curviness : 1;
-  const autoRotate = typeof obj.autoRotate === "number" ? obj.autoRotate : obj.autoRotate === true;
-  return { coords, curviness, autoRotate, isCubic: obj.type === "cubic" };
-}
-
-/** Build an arcPath config from a live `vars.motionPath` value. */
-export function arcPathFromMotionPathValue(mp: unknown): ArcPathConfig | undefined {
-  const parsed = coordsFromMotionPath(mp);
-  if (!parsed) return undefined;
-  return buildArcPath(parsed.coords, parsed.curviness, parsed.autoRotate, parsed.isCubic)?.arcPath;
-}
-
 function flatTweenKeyframes(vars: Record<string, unknown>): Pct[] | null {
   const properties: Record<string, number | string> = {};
   for (const [k, v] of Object.entries(vars)) {
@@ -146,36 +121,22 @@ function flatTweenKeyframes(vars: Record<string, unknown>): Pct[] | null {
   ];
 }
 
+const stringOr = (value: unknown) => (typeof value === "string" ? value : undefined);
+
 /** Tween-relative keyframes + optional arcPath for one live tween, or null. */
 function readTween(vars: Record<string, unknown>): ReadTween | null {
+  const runEase = stringOr(vars.ease);
   if (vars.keyframes && typeof vars.keyframes === "object") {
     const parsed = parsePercentageKeyframes(vars.keyframes as Record<string, unknown>);
-    if (parsed) return parsed;
-  }
-  const mp = coordsFromMotionPath(vars.motionPath);
-  if (mp) {
-    const shape = buildArcPath(mp.coords, mp.curviness, mp.autoRotate, mp.isCubic);
-    if (shape) {
-      const n = shape.waypoints.length;
-      const keyframes = shape.waypoints.map((wp, i) => ({
-        percentage: n > 1 ? Math.round((i / (n - 1)) * 100) : 0,
-        properties: { x: wp.x, y: wp.y },
-      }));
-      return { keyframes, arcPath: shape.arcPath };
-    }
+    const keyframesEase = stringOr((vars.keyframes as { ease?: unknown }).ease);
+    if (parsed) return { ...parsed, runEase: keyframesEase ?? runEase };
   }
+  const path = readMotionPathTween(vars, runEase);
+  if (path) return path;
   const flat = flatTweenKeyframes(vars);
   return flat ? { keyframes: flat } : null;
 }
 
-function matchesElement(tween: RuntimeTween, el: Element): boolean {
-  if (!tween.targets) return false;
-  for (const t of tween.targets()) {
-    if (t === el || (el.id && (t as Element).id === el.id)) return true;
-  }
-  return false;
-}
-
 function tweenTiming(tween: RuntimeTween): { start: number; duration: number } {
   const rawStart = typeof tween.startTime === "function" ? tween.startTime() : 0;
   const rawDur = typeof tween.duration === "function" ? tween.duration() : 0;
@@ -438,10 +399,9 @@ export const GSAP_TRANSFORM_KEYS = new Set(
 export function gsapWritesChannels(el: Element, channels: string[]): boolean {
   const win = el.ownerDocument.defaultView as { __timelines?: Record<string, RuntimeTimeline> };
   return Object.values(win?.__timelines ?? {}).some((tl) =>
-    (tl?.getChildren?.(true) ?? []).some(
+    tweensTargeting(tl, el).some(
       (tween) =>
         !!tween.vars &&
-        matchesElement(tween, el) &&
         (channels.some((ch) => ch in tween.vars!) ||
           keyframeVarsCarryChannel(tween.vars, channels)),
     ),
@@ -515,9 +475,8 @@ function hasNonHoldTween(
 ): boolean {
   if (!timelines) return false;
   for (const tlId of compositionId ? [compositionId] : Object.keys(timelines)) {
-    // fallow-ignore-next-line code-duplication
-    for (const tween of timelines[tlId]?.getChildren?.(true) ?? []) {
-      if (!tween.vars || !matchesElement(tween, targetEl)) continue;
+    for (const tween of tweensTargeting(timelines[tlId], targetEl)) {
+      if (!tween.vars) continue;
       const dur = typeof tween.duration === "function" ? tween.duration() : 0;
       if (isZeroDurationSet(dur)) continue; // skip hold/set tweens (see isZeroDurationSet)
       if (channels && keyframeVarsCarryChannel(tween.vars, channels)) return true;
@@ -530,14 +489,15 @@ function hasNonHoldTween(
 
 /** Convert tween-relative keyframes to clip-relative % using the element's clip dims. */
 function toClipRelative(
-  keyframes: Pct[],
+  read: ReadTween,
   tweenStart: number,
   tweenDuration: number,
   clip: { start: number; duration: number } | undefined,
 ): Pct[] {
+  const { keyframes, runEase } = read;
   if (!clip || clip.duration <= 0) return keyframes;
   return keyframes.map((kf) => {
-    const abs = toAbsoluteTime(tweenStart, tweenDuration, kf.percentage);
+    const abs = toAbsoluteTime(tweenStart, tweenDuration, timeAtProgress(runEase, kf.percentage));
     return { ...kf, percentage: Math.round(((abs - clip.start) / clip.duration) * 100000) / 1000 };
   });
 }
@@ -549,7 +509,7 @@ function buildEntry(
   clip: { start: number; duration: number } | undefined,
 ): RuntimeKeyframeEntry {
   return {
-    keyframes: toClipRelative(read.keyframes, start, duration, clip),
+    keyframes: toClipRelative(read, start, duration, clip),
     tweenStart: start,
     tweenDuration: duration,
     ...(read.easeEach ? { easeEach: read.easeEach } : {}),

package/src/hooks/gsapRuntimeMotionPath.ts

@@ -0,0 +1,47 @@
+import { buildArcPath, type ArcPathConfig } from "@hyperframes/core/gsap-parser-acorn";
+import { MOTION_PATH_RUN_EASE } from "../utils/gsapKeyframeEases";
+import type { ReadTween } from "./gsapRuntimeKeyframes";
+
+function isXY(p: unknown): p is { x: number; y: number } {
+  return !!p && typeof (p as any).x === "number" && typeof (p as any).y === "number";
+}
+
+/** Coordinates + curviness from a live `vars.motionPath` value (object or array form), or null. */
+function coordsFromMotionPath(mp: unknown): {
+  coords: Array<{ x: number; y: number }>;
+  curviness: number;
+  autoRotate: boolean | number;
+  isCubic: boolean;
+} | null {
+  if (!mp || typeof mp !== "object") return null;
+  const obj = mp as Record<string, unknown>;
+  const pathVal = Array.isArray(mp) ? mp : obj.path;
+  if (!Array.isArray(pathVal)) return null;
+  const coords = pathVal.filter(isXY).map((p) => ({ x: p.x, y: p.y }));
+  if (coords.length < 2) return null;
+  const curviness = typeof obj.curviness === "number" ? obj.curviness : 1;
+  const autoRotate = typeof obj.autoRotate === "number" ? obj.autoRotate : obj.autoRotate === true;
+  return { coords, curviness, autoRotate, isCubic: obj.type === "cubic" };
+}
+
+/** Build an arcPath config from a live `vars.motionPath` value. */
+export function arcPathFromMotionPathValue(mp: unknown): ArcPathConfig | undefined {
+  const parsed = coordsFromMotionPath(mp);
+  if (!parsed) return undefined;
+  return buildArcPath(parsed.coords, parsed.curviness, parsed.autoRotate, parsed.isCubic)?.arcPath;
+}
+
+export function readMotionPathTween(
+  vars: Record<string, unknown>,
+  runEase?: string,
+): ReadTween | null {
+  const mp = coordsFromMotionPath(vars.motionPath);
+  const shape = mp && buildArcPath(mp.coords, mp.curviness, mp.autoRotate, mp.isCubic);
+  if (!shape) return null;
+  const n = shape.waypoints.length;
+  const keyframes = shape.waypoints.map((wp, i) => ({
+    percentage: n > 1 ? Math.round((i / (n - 1)) * 100) : 0,
+    properties: { x: wp.x, y: wp.y },
+  }));
+  return { keyframes, arcPath: shape.arcPath, runEase: runEase ?? MOTION_PATH_RUN_EASE };
+}

package/src/hooks/gsapRuntimeTweenIndex.ts

@@ -0,0 +1,53 @@
+import type { RuntimeTimeline, RuntimeTween } from "./gsapRuntimeKeyframes";
+
+export function matchesElement(tween: RuntimeTween, el: Element): boolean {
+  if (!tween.targets) return false;
+  for (const t of tween.targets()) {
+    if (t === el || (el.id && (t as Element).id === el.id)) return true;
+  }
+  return false;
+}
+
+type TweenIndex = { byElement: Map<unknown, RuntimeTween[]>; byId: Map<string, RuntimeTween[]> };
+let tweenIndexes: WeakMap<RuntimeTimeline, TweenIndex> | null = null;
+
+/** Within `run`, finding the tweens on an element reads one index per timeline, not every tween. */
+export function withTweenIndex<T>(run: () => T): T {
+  const outer = tweenIndexes;
+  tweenIndexes ??= new WeakMap();
+  try {
+    return run();
+  } finally {
+    tweenIndexes = outer;
+  }
+}
+
+function indexTweens(children: RuntimeTween[]): TweenIndex {
+  const index: TweenIndex = { byElement: new Map(), byId: new Map() };
+  const add = <K>(map: Map<K, RuntimeTween[]>, key: K, tween: RuntimeTween) => {
+    const list = map.get(key);
+    // A tween's targets are added together, so a repeat of its key is always the last entry.
+    if (!list) map.set(key, [tween]);
+    else if (list.at(-1) !== tween) list.push(tween);
+  };
+  for (const tween of children) {
+    for (const target of tween.targets?.() ?? []) {
+      add(index.byElement, target, tween);
+      const id = (target as Element).id;
+      if (id) add(index.byId, id, tween);
+    }
+  }
+  return index;
+}
+
+export function tweensTargeting(
+  timeline: RuntimeTimeline | undefined,
+  el: Element,
+): RuntimeTween[] {
+  if (!timeline || typeof timeline !== "object" || !tweenIndexes)
+    return (timeline?.getChildren?.(true) ?? []).filter((tween) => matchesElement(tween, el));
+  let index = tweenIndexes.get(timeline);
+  if (!index) tweenIndexes.set(timeline, (index = indexTweens(timeline.getChildren?.(true) ?? [])));
+  // The same rule as matchesElement: an element with an id matches every tween on that id.
+  return (el.id ? index.byId.get(el.id) : index.byElement.get(el)) ?? [];
+}

package/src/hooks/gsapShared.test.ts

@@ -1,33 +1,16 @@
 import { describe, it, expect } from "vitest";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
-import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import {
   idFromSelector,
   idSelector,
   isInstantHold,
   parsePercentageKeyframes,
   resolveClipTimingBasis,
-  resolveEditableTweenDuration,
+  playsNear,
   toClipKeyframes,
   toClipPercentage,
 } from "./gsapShared";
 
-// Fixtures carry only the fields the function under test reads; the double-cast
-// is the documented way to stand in for the full runtime shape (CONTRIBUTING.md).
-const tween = (duration: number | undefined) => ({ duration }) as unknown as GsapAnimation;
-
-describe("resolveEditableTweenDuration", () => {
-  const selection = { dataAttributes: { duration: "16.26" } } as unknown as DomEditSelection;
-
-  it("uses the owning clip duration when the tween omits an outer duration", () => {
-    expect(resolveEditableTweenDuration(tween(undefined), selection)).toBe(16.26);
-  });
-
-  it("keeps an explicitly-authored tween duration", () => {
-    expect(resolveEditableTweenDuration(tween(4), selection)).toBe(4);
-  });
-});
-
 describe("isInstantHold", () => {
   const animation = (method: GsapAnimation["method"], duration?: number) =>
     ({ method, duration }) as unknown as GsapAnimation;
@@ -54,45 +37,49 @@ describe("parsePercentageKeyframes", () => {
     ]);
   });
 
-  it("parses GSAP array-form keyframes as evenly-distributed steps", () => {
-    // Regression: a multi-point shuttle path authored as `keyframes: [...]` used to
-    // read as null (no `N%` keys) → no motion path. Steps map to i/(n-1)*100%.
+  it("parses GSAP array-form keyframes at each step's end, as the parser does", () => {
+    // A multi-point shuttle path authored as `keyframes: [...]` has no `N%` keys;
+    // step i of n ends at (i+1)/n.
     const out = parsePercentageKeyframes([
       { x: 0, y: 0 },
       { x: 520, y: 120 },
       { x: 1040, y: 0 },
       { x: 1480, y: 160 },
     ] as unknown as Record<string, unknown>);
-    expect(out?.keyframes.map((k) => k.percentage)).toEqual([0, 33.3, 66.7, 100]);
+    expect(out?.keyframes.map((k) => k.percentage)).toEqual([25, 50, 75, 100]);
     expect(out?.keyframes.map((k) => k.step)).toEqual([0, 1, 2, 3]);
     expect(out?.keyframes[1]!.properties).toEqual({ x: 520, y: 120 });
+    const timed = parsePercentageKeyframes([
+      { x: 0, duration: 1 },
+      { x: 50, duration: 3 },
+    ] as unknown as Record<string, unknown>);
+    expect(timed?.keyframes.map((k) => k.percentage)).toEqual([25, 100]);
   });
 
-  it("strips a per-entry ease without shifting the even index-spacing of the others", () => {
+  it("strips a per-entry ease without shifting the step spacing of the others", () => {
     // GSAP positions array keyframes by array index, so a `{ ease }` carried on an
     // entry is a segment ease (skipped as a property) — it must not change where
-    // the surrounding keyframes land. 3 entries → 0 / 50 / 100, even though the
+    // the surrounding keyframes land. 3 entries → 33.3 / 66.7 / 100, even though the
     // middle entry also carries an ease.
     const out = parsePercentageKeyframes([
       { x: 0 },
       { x: 100, ease: "power2.in" },
       { x: 200 },
     ] as unknown as Record<string, unknown>);
-    expect(out?.keyframes.map((k) => k.percentage)).toEqual([0, 50, 100]);
+    expect(out?.keyframes.map((k) => k.percentage)).toEqual([33.3, 66.7, 100]);
     expect(out?.keyframes.map((k) => k.properties)).toEqual([{ x: 0 }, { x: 100 }, { x: 200 }]);
   });
 
-  it("keeps even spacing when an interior array slot has no animatable prop", () => {
+  it("keeps the step spacing when an interior array slot has no animatable prop", () => {
     // A degenerate `{ ease }`-only slot contributes no output keyframe, but it is
     // still an array slot GSAP allocates a position to — so the remaining entries
-    // keep their original i/(n-1) percentages (0 and 100 for a 3-slot array), not
-    // 0/100 collapsed onto a 2-entry spacing.
+    // keep their 3-slot percentages (33.3 and 100), not a 2-entry spacing.
     const out = parsePercentageKeyframes([
       { x: 0 },
       { ease: "power2.in" },
       { x: 200 },
     ] as unknown as Record<string, unknown>);
-    expect(out?.keyframes.map((k) => k.percentage)).toEqual([0, 100]);
+    expect(out?.keyframes.map((k) => k.percentage)).toEqual([33.3, 100]);
     expect(out?.keyframes.map((k) => k.properties)).toEqual([{ x: 0 }, { x: 200 }]);
   });
 
@@ -157,12 +144,38 @@ describe("toClipKeyframes", () => {
     resolvedStart: 0,
   } as unknown as GsapAnimation;
 
-  // A tween with no duration spans its clip everywhere else in Studio
-  // (resolveEditableTweenDuration), so the cache rows have to agree: a fixed 1s
-  // basis put the end keyframe at 25% of a 4s clip instead of 100%.
-  it("spans the clip when the tween has no duration", () => {
+  it("places a duration-less tween's keyframes where GSAP plays them, not across the clip", () => {
     const rows = toClipKeyframes([{ percentage: 0 }, { percentage: 100 }], durationless, 0, 4);
-    expect(rows.map((row) => row.percentage)).toEqual([0, 100]);
+    expect(rows.map((row) => row.percentage)).toEqual([0, 12.5]);
+  });
+
+  it("matches a keyframe by the time it plays, not its warped progress", () => {
+    const eased = {
+      ...durationless,
+      duration: 1,
+      ease: "power2.in",
+      keyframes: { format: "percentage", keyframes: [] },
+    } as unknown as GsapAnimation;
+    // At 20% of the time power2.in (cubic) shows 0.8% progress: close in progress, far in time.
+    expect(playsNear(eased, 0, 0.8)).toBe(false);
+    expect(playsNear(eased, 50, 50.5)).toBe(true);
+  });
+
+  it("places a keyframe where an outer ease makes GSAP reach it", () => {
+    const eased = {
+      ...durationless,
+      duration: 1,
+      ease: "power2.in",
+      keyframes: { format: "percentage", keyframes: [] },
+    } as unknown as GsapAnimation;
+    const rows = toClipKeyframes(
+      [{ percentage: 0 }, { percentage: 50 }, { percentage: 100 }],
+      eased,
+      0,
+      1,
+    );
+    // GSAP's power2 is cubic: it reaches 50% at the cube root of 0.5.
+    expect(rows.map((row) => row.percentage)).toEqual([0, 79.37, 100]);
   });
 
   it("keeps the tween percentage and the animation identity on every row", () => {
@@ -276,7 +289,7 @@ describe("sub-composition keyframe percentages", () => {
 
   it("puts a tween on the host's first frame at 0%, never below zero", () => {
     // A clip-relative percentage can never be negative; this one cached -12.
-    expect(percentages(inner(0))).toEqual([0, 100]);
+    expect(percentages(inner(0))).toEqual([0, 4]);
   });
 
   it("puts the last tween's end keyframe at 100%", () => {

package/src/hooks/gsapShared.ts

@@ -5,6 +5,8 @@
  */
 import { isHtmlElement } from "@hyperframes/core/runtime/dom-realm";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import { getObjectArrayKeyframeTiming } from "@hyperframes/parsers/gsap-parser";
+import { progressAtTime, runEaseOf, timeAtProgress } from "../utils/gsapKeyframeEases";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import {
   absoluteToPercentage,
@@ -88,6 +90,13 @@ const SAFE_HASH_ID = /^-?[A-Za-z_][\w-]*$/;
  */
 export const KEYFRAME_PCT_MATCH = 1;
 
+/** Whether the keyframe at `percentage` plays within KEYFRAME_PCT_MATCH of the time where GSAP shows `progress`. */
+export function playsNear(anim: GsapAnimation, percentage: number, progress: number): boolean {
+  const runEase = runEaseOf(anim);
+  const gap = timeAtProgress(runEase, percentage) - timeAtProgress(runEase, progress);
+  return Math.abs(gap) <= KEYFRAME_PCT_MATCH;
+}
+
 export function idSelector(id: string): string {
   // A `#id` selector is only valid for a CSS identifier. IDs that start with a
   // digit (e.g. "01-hook-hero-word") make `document.querySelector("#01-...")` and
@@ -332,22 +341,6 @@ export function tweenTargetsElement(
 
 // ── Percentage computation ────────────────────────────────────────────────────
 
-/**
- * Resolve the timing basis used by editor keyframes. The timeline renders a
- * duration-less tween across its owning clip, so mutations must use that same
- * duration instead of silently falling back to GSAP's 0.5s default.
- */
-export function resolveEditableTweenDuration(
-  animation: GsapAnimation,
-  selection: DomEditSelection,
-): number {
-  const clipDuration = Number.parseFloat(selection.dataAttributes?.duration ?? "");
-  return resolveTweenDuration(
-    animation,
-    Number.isFinite(clipDuration) && clipDuration > 0 ? clipDuration : 0.5,
-  );
-}
-
 /**
  * Compute the current playback percentage within an element's animation range.
  * Uses the animation's resolved timing if available, otherwise falls back to
@@ -360,10 +353,13 @@ export function computeElementPercentage(
 ): number {
   if (animation) {
     const start = resolveTweenStart(animation);
-    const duration = resolveEditableTweenDuration(animation, selection);
+    const duration = resolveTweenDuration(animation);
     if (duration <= 0) return 0;
     if (start !== null) {
-      return absoluteToPercentage(currentTime, start, duration);
+      return progressAtTime(
+        runEaseOf(animation),
+        absoluteToPercentage(currentTime, start, duration),
+      );
     }
   }
   const elStart = Number.parseFloat(selection.dataAttributes?.start ?? "0") || 0;
@@ -428,13 +424,9 @@ export function parsePercentageKeyframes(
   const keyframes: ParsedPercentageKeyframes["keyframes"] = [];
   let easeEach: string | undefined;
 
-  // GSAP array-form keyframes — `keyframes: [{x,y}, {x,y}, ...]` — are spread
-  // evenly across the tween by default: GSAP gives each entry an equal share of
-  // the duration unless an entry carries its own `duration`/`delay`, which the
-  // studio never emits. So entry i of n maps to i/(n-1)*100% (n=4 → 0/33.3/66.7/100).
-  // Index spacing counts EVERY array slot, including a degenerate entry that
-  // contributes no animatable prop (it's still a slot GSAP allocates a position
-  // to), so dropping such an entry from the output below must NOT shift the others.
+  // GSAP array-form keyframes — `keyframes: [{x,y}, {x,y}, ...]` — place each step at
+  // its cumulative end, the parser's rule (getObjectArrayKeyframeTiming). Spacing counts
+  // EVERY array slot, so dropping an entry with no animatable prop must NOT shift the others.
   // A per-entry `ease` is a segment ease, not a keyframe value, so it's skipped as
   // a property; there is no array-form `easeEach` (that's an object-form sibling key).
   // (The object form further down uses explicit "0%" keys instead.) Without this
@@ -442,11 +434,16 @@ export function parsePercentageKeyframes(
   // motion path.
   if (Array.isArray(kfObj)) {
     const steps = kfObj as unknown[];
+    const timing = getObjectArrayKeyframeTiming(
+      steps.map((entry) => (entry as { duration?: unknown } | null)?.duration),
+    );
+    if (!timing) return null;
     steps.forEach((entry, i) => {
       if (!entry || typeof entry !== "object") return;
-      const percentage = steps.length > 1 ? Math.round((i / (steps.length - 1)) * 1000) / 10 : 0;
       const properties = collectAnimatableKeyframeProperties(entry);
-      if (Object.keys(properties).length > 0) keyframes.push({ percentage, properties, step: i });
+      if (Object.keys(properties).length > 0) {
+        keyframes.push({ percentage: timing.percentages[i]!, properties, step: i });
+      }
     });
     return keyframes.length > 0 ? { keyframes } : null;
   }
@@ -575,14 +572,15 @@ export function toClipKeyframes<T extends { percentage: number }>(
   }
 > {
   const tweenStart = anim.resolvedStart ?? (typeof anim.position === "number" ? anim.position : 0);
-  // A duration-less tween spans the clip, the same rule the edit paths use
-  // (resolveEditableTweenDuration). A fixed 1s here put its keyframes at a
-  // percentage no editor agreed with.
-  const tweenDuration = anim.duration ?? clipDuration;
+  const tweenDuration = resolveTweenDuration(anim);
   return source.map((keyframe) => ({
     ...keyframe,
     percentage: toClipPercentage(
-      toAbsoluteTime(tweenStart, tweenDuration, keyframe.percentage),
+      toAbsoluteTime(
+        tweenStart,
+        tweenDuration,
+        timeAtProgress(runEaseOf(anim), keyframe.percentage),
+      ),
       clipStart,
       clipDuration,
       keyframe.percentage,

package/src/hooks/gsapValueAtPlayhead.realGsap.test.ts

@@ -1,14 +1,20 @@
 // @vitest-environment happy-dom
 import { gsap } from "gsap";
 import { parseGsapScriptAcorn } from "@hyperframes/parsers/gsap-parser-acorn";
-import { replaceTweenWithKeyframesInScript } from "@hyperframes/parsers/gsap-writer-acorn";
+import {
+  replaceTweenWithKeyframesInScript,
+  syncPositionHoldsBeforeKeyframes,
+  updateKeyframeInScript,
+} from "@hyperframes/parsers/gsap-writer-acorn";
 import { afterEach, expect, it, vi } from "vitest";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { usePlayerStore } from "../player/store/playerStore";
 import { findParsedTween, parsedImplicitEndValue, parsedTweenEase } from "./gsapParsedTween";
 import { readRuntimeKeyframes } from "./gsapRuntimeKeyframes";
 import { GsapEditBlockedError } from "./gsapEditOutcome";
+import { toClipKeyframes } from "./gsapShared";
 import { commitValueAtPlayhead, planValueEdit } from "./gsapValueAtPlayhead";
+import { applyKeyframeAtPlayhead, type EnableKeyframesSession } from "./useEnableKeyframes";
 
 /** Runs a composition script as the preview does: a paused timeline, bound, then seeked to `at`. */
 function play(script: string, at: number) {
@@ -74,10 +80,10 @@ it("reads plain array nodes where the lane puts them, though GSAP fills in step
 });
 
 // Three default 0.5 s steps stretched over 3 s: GSAP reaches the middle one at 2 s, where the parse
-// places it at 50%.
+// places it at 66.7%.
 it.each([
   ["at the playhead, timing array steps on their own timeline", undefined],
-  ["selected in the lane, in place", 50],
+  ["selected in the lane, in place", 66.7],
 ])("changes the middle array keyframe %s", (_, selectedPct) => {
   const { plan, shown } = dragAndReplay(
     script("keyframes: [{ x: 60 }, { x: 120 }, { x: 180 }], duration: 3"),
@@ -244,6 +250,90 @@ it("writes an edit into a looping tween and keeps its repeat and yoyo, as main d
   expect(written).toMatch(/repeat: 1[\s\S]*yoyo: true/);
 });
 
+it("keeps a delayed step list where GSAP plays it, before and after a keyframe edit", () => {
+  const box = Object.assign(document.body.appendChild(document.createElement("div")), { id: "x" });
+  const stepList = `var tl = gsap.timeline({ paused: true });\ntl.to("#x", { keyframes: [{ x: 60 }, { x: 120 }], ease: "none" }, 1);\nwindow.__timelines["t"] = tl;`;
+  const id = parseGsapScriptAcorn(stepList).animations[0]!.id;
+  const edited = syncPositionHoldsBeforeKeyframes(
+    updateKeyframeInScript(stepList, id, 100, { x: 130 }),
+  );
+  const xAt = (file: string, at: number) => {
+    const { timeline } = play(file, at);
+    const x = gsap.getProperty(box, "x");
+    timeline.kill();
+    gsap.set(box, { clearProps: "all" });
+    return x;
+  };
+  for (const file of [stepList, edited]) {
+    expect([xAt(file, 0.5), xAt(file, 1.25)]).toEqual([0, 30]);
+    const tween = parseGsapScriptAcorn(file).animations.find((a) => a.keyframes)!;
+    for (const { percentage, properties } of tween.keyframes!.keyframes) {
+      expect(xAt(file, 1 + percentage / 100)).toBeCloseTo(Number(properties.x), 3);
+    }
+  }
+});
+
+it.each([
+  [
+    "an outer power2.in",
+    `keyframes: { "0%": { x: 0 }, "50%": { x: 60 }, "100%": { x: 120 } }, duration: 1, ease: "power2.in"`,
+  ],
+  ["no duration", `keyframes: [{ x: 60 }, { x: 120 }], ease: "none"`],
+])("draws each diamond of a keyframed tween with %s where GSAP shows its value", (_, vars) => {
+  const box = Object.assign(document.body.appendChild(document.createElement("div")), { id: "x" });
+  const file = `var tl = gsap.timeline({ paused: true });\ntl.to("#x", { ${vars} }, 1);\nwindow.__timelines["t"] = tl;`;
+  const tween = parseGsapScriptAcornAnimation(file);
+  for (const row of toClipKeyframes(tween.keyframes!.keyframes, tween, 0, 4)) {
+    const { timeline } = play(file, (row.percentage / 100) * 4);
+    expect(gsap.getProperty(box, "x")).toBeCloseTo(Number(row.properties.x), 1);
+    timeline.kill();
+    gsap.set(box, { clearProps: "all" });
+  }
+});
+
+function parseGsapScriptAcornAnimation(file: string) {
+  return parseGsapScriptAcorn(file).animations.find((a) => a.keyframes)!;
+}
+
+it("keeps a step list's steps where GSAP plays them when an outer duration stretches it", () => {
+  const { plan, written } = dragAndReplay(
+    script(`keyframes: [{ x: 100 }, { x: 200 }], duration: 2, ease: "none"`),
+    70,
+    0.5,
+  );
+  expect(plan.ok).toBe(true);
+  const box = document.getElementById("x")!;
+  const xAt = (at: number) => {
+    const { timeline } = play(written!, at);
+    const x = gsap.getProperty(box, "x");
+    timeline.kill();
+    return x;
+  };
+  expect([xAt(0.5), xAt(1), xAt(2)]).toEqual([70, 100, 200]);
+});
+
+it("adds a keyframe where GSAP plays a tween whose duration is an expression, and never rewrites the expression", async () => {
+  const src = `var dur = () => 2;\nvar tl = gsap.timeline({ paused: true });\ntl.to("#x", { keyframes: { "0%": { x: 0 }, "100%": { x: 300 } }, duration: dur() }, 1);\nwindow.__timelines["t"] = tl;`;
+  const box = document.body.appendChild(document.createElement("div"));
+  box.id = "x";
+  const { timeline, iframe } = play(src, 2);
+  const anim = parseGsapScriptAcorn(src).animations[0]!;
+  const writes: Array<[string, unknown]> = [];
+  const session = {
+    commitMutation: async (mutation: unknown) => void writes.push(["replace", mutation]),
+    handleGsapRemoveKeyframe: () => void writes.push(["remove", null]),
+    handleGsapAddKeyframeBatch: async (_id: string, pct: number) => void writes.push(["add", pct]),
+  } as unknown as EnableKeyframesSession;
+  const selection = { id: "x", selector: "#x", element: box } as DomEditSelection;
+
+  await applyKeyframeAtPlayhead(session, selection, anim, 2, iframe);
+  await applyKeyframeAtPlayhead(session, selection, anim, 3.5, iframe);
+  timeline.kill();
+
+  expect(anim.durationUnresolved).toBe(true);
+  expect(writes).toEqual([["add", 50]]);
+});
+
 it("leaves a step list with a runBackwards step to the runtime: a rewrite would play it differently", async () => {
   const flagged = script(
     "keyframes: [{ x: 60, duration: 1, runBackwards: true }, { x: 180, duration: 1 }], ease: 'none'",