@hyperframes/studio 0.8.126 → 0.8.128

package/src/hooks/gsapRuntimeKeyframes.test.ts

@@ -1,9 +1,7 @@
-import { describe, expect, it } from "vitest";
-import {
-  arcPathFromMotionPathValue,
-  hasNonHoldTweenForElement,
-  readRuntimeKeyframes,
-} from "./gsapRuntimeKeyframes";
+import { describe, expect, it, vi } from "vitest";
+import { hasNonHoldTweenForElement, readRuntimeKeyframes } from "./gsapRuntimeKeyframes";
+import { arcPathFromMotionPathValue } from "./gsapRuntimeMotionPath";
+import { tweensTargeting, withTweenIndex } from "./gsapRuntimeTweenIndex";
 
 // Build a fake preview iframe whose runtime timeline holds the given child tweens
 // and resolves `selector` to `el`.
@@ -261,3 +259,79 @@ describe("arcPathFromMotionPathValue", () => {
     expect(arcPathFromMotionPathValue(null)).toBeUndefined();
   });
 });
+
+describe("readRuntimeKeyframes — a motion path runs GSAP's default tween ease", () => {
+  const el = { id: "arc" };
+  const arcTween = (ease?: string) => ({
+    targets: () => [el],
+    vars: {
+      motionPath: {
+        path: [
+          { x: 0, y: 0 },
+          { x: 100, y: -50 },
+          { x: 200, y: 0 },
+        ],
+      },
+      ease,
+    },
+    duration: () => 2,
+    startTime: () => 0,
+  });
+
+  it("reads power1.out when the tween sets no ease, and the authored ease otherwise", () => {
+    const read = (ease?: string) =>
+      readRuntimeKeyframes(fakeIframe(el, [arcTween(ease)]), "#arc")?.runEase;
+    expect(read()).toBe("power1.out");
+    expect(read("none")).toBe("none");
+  });
+});
+
+describe("withTweenIndex — many elements, one scan of the tweens", () => {
+  const ids = Array.from({ length: 20 }, (_, i) => `clip-${i}`);
+  const tweens = ids.map((id) => ({
+    targets: vi.fn(() => [{ id }]),
+    vars: { x: 10, duration: 1 },
+    duration: () => 1,
+    startTime: () => 0,
+  }));
+  const timeline = { getChildren: () => tweens };
+  const preview = {
+    contentWindow: { __timelines: { "index.html": timeline } },
+    contentDocument: { querySelector: (sel: string) => ({ id: sel.slice(1) }) },
+  } as unknown as HTMLIFrameElement;
+  const askAll = () => ids.map((id) => hasNonHoldTweenForElement(preview, `#${id}`));
+
+  it("answers the same as the plain scan", () => {
+    const plain = askAll();
+    expect(withTweenIndex(askAll)).toEqual(plain);
+    expect(plain.every(Boolean)).toBe(true);
+  });
+
+  it("reads each tween's targets once per pass instead of once per element", () => {
+    for (const tween of tweens) tween.targets.mockClear();
+    withTweenIndex(askAll);
+    expect(tweens.every((tween) => tween.targets.mock.calls.length === 1)).toBe(true);
+  });
+
+  it("skips a timelines entry that is not an object", () => {
+    const odd = {
+      contentWindow: {
+        __timelines: { stray: null, label: "x", main: { getChildren: () => tweens } },
+      },
+      contentDocument: { querySelector: (sel: string) => ({ id: sel.slice(1) }) },
+    } as unknown as HTMLIFrameElement;
+    expect(withTweenIndex(() => hasNonHoldTweenForElement(odd, "#clip-3"))).toBe(true);
+    expect(withTweenIndex(() => hasNonHoldTweenForElement(odd, "#nobody"))).toBe(false);
+  });
+
+  it("returns the plain scan's tweens, once each and in timeline order", () => {
+    const el = { id: "clip-2" } as unknown as Element;
+    const byElement = { targets: () => [el], vars: {}, duration: () => 1 };
+    const byId = { targets: () => [{ id: "clip-2" }], vars: {}, duration: () => 1 };
+    const both = { targets: () => [el, { id: "clip-2" }], vars: {}, duration: () => 1 };
+    const tl = { getChildren: () => [byId, byElement, both] };
+    const plain = tweensTargeting(tl, el);
+    expect(withTweenIndex(() => tweensTargeting(tl, el))).toEqual(plain);
+    expect(plain).toEqual([byId, byElement, both]);
+  });
+});

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";
@@ -43,11 +46,12 @@ export interface RuntimeTimeline {
   to?: (targets: Element[], vars: GsapVars, position?: number) => RuntimeTween;
 }
 
-type Pct = { percentage: number; properties: Record<string, number | string> };
+type Pct = { percentage: number; properties: Record<string, number | string>; step?: number };
 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,44 +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 }]);
   });
 
@@ -156,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", () => {
@@ -275,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;
@@ -399,7 +395,11 @@ export function queryIframeElement(
 // ── Keyframe parsing ──────────────────────────────────────────────────────────
 
 export interface ParsedPercentageKeyframes {
-  keyframes: Array<{ percentage: number; properties: Record<string, number | string> }>;
+  keyframes: Array<{
+    percentage: number;
+    properties: Record<string, number | string>;
+    step?: number;
+  }>;
   easeEach?: string;
 }
 
@@ -424,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
@@ -438,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 });
+      if (Object.keys(properties).length > 0) {
+        keyframes.push({ percentage: timing.percentages[i]!, properties, step: i });
+      }
     });
     return keyframes.length > 0 ? { keyframes } : null;
   }
@@ -571,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,