@hyperframes/studio 0.8.127 → 0.8.128

package/src/player/components/timelineLinkSelection.ts

@@ -1,13 +1,5 @@
 import { usePlayerStore, type TimelineElement } from "../store/playerStore";
-import {
-  dropMisalignedTrimPartners,
-  expandToLinkedMembers,
-  linkedGestureKeys,
-  linkedMembersOf,
-} from "./audioClipLink";
-import { buildTimelineGroupResizeMembers } from "./timelineGroupEditing";
-import { resolveGroupMovers } from "./timelineMultiDragPreview";
-import { MAX_HAND_EDIT_CLIPS } from "./timelineEditing";
+import { expandToLinkedMembers, linkedMembersOf } from "./audioClipLink";
 import { isLinkedSelectionOn } from "../../utils/linkedClipPreferences";
 
 /**
@@ -47,29 +39,3 @@ export function toggleClipWithLinks(key: string, altKey: boolean): TimelineEleme
   const primary = usePlayerStore.getState().selectedElementId;
   return state.elements.find((el) => (el.key ?? el.id) === primary) ?? null;
 }
-
-/** Whether a hand drag on `grabbed` (trimming `edge`, or null to move) would change more clips than allowed. */
-export function exceedsHandEditLimit(
-  grabbed: TimelineElement,
-  altKey: boolean,
-  edge: "start" | "end" | null,
-): boolean {
-  const { selectedElementIds, elements } = usePlayerStore.getState();
-  const grabbedKey = grabbed.key ?? grabbed.id;
-  const keys = linkedGestureKeys(
-    selectedElementIds,
-    grabbed,
-    elements,
-    altKey,
-    isLinkedSelectionOn(),
-  );
-  const changed = edge
-    ? buildTimelineGroupResizeMembers(
-        elements,
-        dropMisalignedTrimPartners(keys, grabbed, elements, edge),
-        grabbedKey,
-        edge,
-      )
-    : resolveGroupMovers(elements, keys, grabbedKey);
-  return (changed?.length ?? 1) > MAX_HAND_EDIT_CLIPS;
-}

package/src/player/components/timelineOptimisticRevision.ts

@@ -1,4 +1,5 @@
 import type { TimelineElement } from "../store/playerStore";
+import { batchElementUpdates } from "../store/batchElementUpdates";
 
 type UpdateElement = (key: string, updates: Partial<TimelineElement>) => void;
 type RevisionScope = "timing" | "membership";
@@ -45,9 +46,11 @@ export function rollbackLatestTimelineOptimisticGesture(
   gesture: ReadonlyMap<string, number>,
   rollbacks: ReadonlyArray<{ key: string; updates: Partial<TimelineElement> }>,
 ): void {
-  for (const rollback of rollbacks) {
-    if (isLatestTimelineOptimisticGesture(updateElement, gesture, rollback.key)) {
-      updateElement(rollback.key, rollback.updates);
+  batchElementUpdates(() => {
+    for (const rollback of rollbacks) {
+      if (isLatestTimelineOptimisticGesture(updateElement, gesture, rollback.key)) {
+        updateElement(rollback.key, rollback.updates);
+      }
     }
-  }
+  });
 }

package/src/player/components/trackHeaderLaneState.ts

@@ -17,7 +17,7 @@ import {
 } from "../../utils/globalTimeCompiler";
 import type { TimelinePropertyGroupKeyframeToggle } from "./timelineCallbacks";
 import { getTimelinePropertyLanes } from "./TimelinePropertyLanes";
-import { groupLabel, valuesAt, type LaneValues } from "./trackHeaderLaneValues";
+import { groupLabel, valuesAt, valuesBefore, type LaneValues } from "./trackHeaderLaneValues";
 
 export type TimelinePropertyLane = ReturnType<typeof getTimelinePropertyLanes>[number];
 export type KeyframeNavigationState = ReturnType<
@@ -110,7 +110,14 @@ export function resolveLaneHeaderState(
     currentTime,
     clipPercentage,
   );
-  const values = animation ? valuesAt(animation, lane.group, tweenPercentage) : {};
+  const values = animation
+    ? valuesAt(
+        animation,
+        lane.group,
+        tweenPercentage,
+        valuesBefore(animation, lane.elementAnimations),
+      )
+    : {};
 
   return {
     navigation,

package/src/player/components/trackHeaderLaneValues.test.ts

@@ -0,0 +1,89 @@
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import { describe, expect, it } from "vitest";
+import { progressAtTime, runEaseOf } from "../../utils/gsapKeyframeEases";
+import { valuesAt, valuesBefore } from "./trackHeaderLaneValues";
+
+const tween = (format: string, vars: { ease?: string; easeEach?: string }) =>
+  ({
+    id: "#x-to-0-position",
+    targetSelector: "#x",
+    method: "to",
+    position: 0,
+    duration: 1,
+    properties: {},
+    ...(vars.ease ? { ease: vars.ease } : {}),
+    keyframes: {
+      format,
+      keyframes: [
+        { percentage: 50, properties: { x: 60 } },
+        { percentage: 100, properties: { x: 120 } },
+      ],
+      ...(vars.easeEach ? { easeEach: vars.easeEach } : {}),
+    },
+  }) as unknown as GsapAnimation;
+
+const xAt = (animation: GsapAnimation, timePercentage: number) =>
+  Number(
+    valuesAt(animation, "position", progressAtTime(runEaseOf(animation), timePercentage)).x.toFixed(
+      2,
+    ),
+  );
+
+// Each row is what GSAP 3.15 draws for x at 12.5, 37.5, 62.5 and 87.5% of the tween.
+describe("valuesAt at the playhead", () => {
+  it.each([
+    ["a step list", tween("object-array", {}), [15, 45, 75, 105]],
+    [
+      "a step list with an outer ease",
+      tween("object-array", { ease: "power1.out" }),
+      [28.13, 73.13, 103.13, 118.13],
+    ],
+    ["percentage keyframes", tween("percentage", {}), [7.5, 52.5, 67.5, 112.5]],
+    [
+      "percentage keyframes with an outer ease",
+      tween("percentage", { ease: "power1.out", easeEach: "power1.out" }),
+      [43.07, 83.38, 115.25, 119.94],
+    ],
+  ])("reads %s as GSAP plays it", (_, animation, expected) => {
+    expect([12.5, 37.5, 62.5, 87.5].map((at) => xAt(animation, at))).toEqual(expected);
+  });
+});
+
+describe("valuesBefore", () => {
+  it("starts a step list from the value an earlier set left, not a default", () => {
+    const set = { id: "s", method: "set", position: 0, resolvedStart: 0, properties: { x: 300 } };
+    const stepList = { ...tween("object-array", { ease: "none" }), position: 1, resolvedStart: 1 };
+    stepList.keyframes!.keyframes = [
+      { percentage: 50, properties: { x: 300 } },
+      { percentage: 100, properties: { x: 500 } },
+    ];
+    const start = valuesBefore(stepList, [set as unknown as GsapAnimation, stepList]);
+    expect(start).toEqual({ x: 300 });
+    expect(valuesAt(stepList, "position", 25, start)).toEqual({ x: 300 });
+  });
+
+  it("takes a set placed at the tween's own start, and never a relative string", () => {
+    const at = (id: string, resolvedStart: number, x: number | string) =>
+      ({ id, method: "set", resolvedStart, properties: { x } }) as unknown as GsapAnimation;
+    const stepList = { ...tween("object-array", { ease: "none" }), resolvedStart: 1 };
+    const relative = at("r", 0.5, "+=50");
+    expect(valuesBefore(stepList, [at("s", 1, 300), stepList])).toEqual({ x: 300 });
+    expect(valuesBefore(stepList, [stepList, at("s", 1, 300)])).toEqual({});
+    expect(valuesBefore(stepList, [at("s", 0, 300), relative, stepList])).toEqual({});
+  });
+
+  it("skips a tween still running when this one starts", () => {
+    const set = { id: "s", method: "set", resolvedStart: 0, properties: { x: 300 } };
+    const running = {
+      id: "r",
+      method: "to",
+      resolvedStart: 0.5,
+      duration: 1,
+      properties: { x: 900 },
+    };
+    const stepList = { ...tween("object-array", { ease: "none" }), resolvedStart: 1 };
+    const others = [set, running] as unknown as GsapAnimation[];
+    expect(valuesBefore(stepList, [...others, stepList])).toEqual({ x: 300 });
+    expect(valuesBefore({ ...stepList, resolvedStart: undefined }, others)).toEqual({});
+  });
+});

package/src/player/components/trackHeaderLaneValues.ts

@@ -4,12 +4,14 @@
  * reads to a human. Kept apart from the header's JSX so a formatting change and
  * a layout change never touch the same file.
  */
-import gsap from "gsap";
 import {
   classifyPropertyGroup,
   type GsapAnimation,
   type PropertyGroupName,
 } from "@hyperframes/core/gsap-parser";
+import { PROPERTY_DEFAULTS } from "../../hooks/gsapShared";
+import { resolveTweenDuration, resolveTweenStart } from "../../utils/globalTimeCompiler";
+import { easeFunction, keyframedTweenEases } from "../../utils/gsapKeyframeEases";
 
 export type LaneValues = Record<string, number | string>;
 
@@ -17,15 +19,8 @@ function roundValue(value: number): string {
   return String(Math.round(value * 100) / 100);
 }
 
-/** GSAP applies a keyframe's `ease` to the segment ARRIVING at it, so the curve
- *  between two keyframes is named by the later one (with the tween-level
- *  `easeEach`/`ease` as the fallback). Sampling linearly would report a value the
- *  element never has at that time, and stamp that wrong value onto a keyframe
- *  added from the track header. Unknown ease names parse to undefined -> linear. */
 function easedProgress(progress: number, animation: GsapAnimation, ease?: string): number {
-  const resolved = ease ?? animation.keyframes?.easeEach ?? animation.ease;
-  if (!resolved || resolved === "none") return progress;
-  return gsap.parseEase(resolved)?.(progress) ?? progress;
+  return easeFunction(keyframedTweenEases(animation).segment({ ease }))?.(progress) ?? progress;
 }
 
 interface PropertyStop {
@@ -34,14 +29,23 @@ interface PropertyStop {
   ease?: string;
 }
 
-function propertyStops(animation: GsapAnimation, property: string): PropertyStop[] {
-  return (animation.keyframes?.keyframes ?? [])
+/** Before its first keyframe a tween animates from the value it starts at (`start`), or the
+ *  property's base value as for a flat tween (synthesizeFlatTweenKeyframes). */
+function propertyStops(
+  animation: GsapAnimation,
+  property: string,
+  start?: number | string,
+): PropertyStop[] {
+  const stops = (animation.keyframes?.keyframes ?? [])
     .filter((keyframe) => property in keyframe.properties)
     .map((keyframe) => ({
       percentage: keyframe.percentage,
       value: keyframe.properties[property],
       ease: keyframe.ease,
     }));
+  const first = stops[0];
+  if (!first || first.percentage <= 0 || typeof first.value !== "number") return stops;
+  return [{ percentage: 0, value: start ?? PROPERTY_DEFAULTS[property] ?? 0 }, ...stops];
 }
 
 /** A pair only interpolates when both ends are numeric and actually span time;
@@ -60,8 +64,9 @@ function propertyValueAt(
   animation: GsapAnimation,
   property: string,
   tweenPercentage: number,
+  start?: number | string,
 ): number | string | undefined {
-  const stops = propertyStops(animation, property);
+  const stops = propertyStops(animation, property, start);
   const before = stops.filter((stop) => stop.percentage <= tweenPercentage).at(-1);
   const after = stops.find((stop) => stop.percentage >= tweenPercentage);
   if (!before) return after?.value;
@@ -77,6 +82,7 @@ export function valuesAt(
   animation: GsapAnimation,
   group: PropertyGroupName,
   tweenPercentage: number,
+  startValues: LaneValues = {},
 ): LaneValues {
   const propertyNames = new Set<string>();
   for (const keyframe of animation.keyframes?.keyframes ?? []) {
@@ -86,12 +92,47 @@ export function valuesAt(
   }
   const values: LaneValues = {};
   for (const property of propertyNames) {
-    const value = propertyValueAt(animation, property, tweenPercentage);
+    const value = propertyValueAt(animation, property, tweenPercentage, startValues[property]);
     if (value !== undefined) values[property] = value;
   }
   return values;
 }
 
+const endValue = (animation: GsapAnimation, property: string) =>
+  animation.keyframes?.keyframes.findLast((keyframe) => property in keyframe.properties)
+    ?.properties[property] ?? animation.properties[property];
+
+/** Each property's value as `animation` starts: the end of the last tween done writing it by then. */
+export function valuesBefore(
+  animation: GsapAnimation,
+  animations: readonly GsapAnimation[],
+): LaneValues {
+  const start = resolveTweenStart(animation);
+  if (start == null) return {};
+  const endOf = (other: GsapAnimation) =>
+    (resolveTweenStart(other) ?? Infinity) +
+    (other.method === "set" ? 0 : resolveTweenDuration(other));
+  const index = animations.indexOf(animation);
+  const finished = animations
+    .filter((other, i) => {
+      if (other.method === "from" || i === index) return false;
+      return endOf(other) < start || (endOf(other) === start && i < index);
+    })
+    .sort((a, b) => endOf(a) - endOf(b));
+  const values: LaneValues = {};
+  for (const other of finished) {
+    const keyframes = other.keyframes?.keyframes ?? [{ properties: other.properties }];
+    for (const property of new Set(
+      keyframes.flatMap((keyframe) => Object.keys(keyframe.properties)),
+    )) {
+      const value = endValue(other, property);
+      if (typeof value === "number") values[property] = value;
+      else delete values[property];
+    }
+  }
+  return values;
+}
+
 export function groupLabel(group: PropertyGroupName, properties: LaneValues): string {
   if (group === "visual" && ("opacity" in properties || "autoAlpha" in properties)) {
     return "Opacity";

package/src/player/components/useTimelineClipDrag.keyboard.test.tsx

@@ -165,13 +165,11 @@ it("leaves Space on a nested fade slider to the slider", () => {
   act(() => view.root.unmount());
 });
 
-it("does not pick up a clip held in a selection above the hand-move limit", () => {
+it("picks up a clip held in a selection of any size", () => {
   const view = mount();
   usePlayerStore.getState().setSelection(["top", "hero", "tail", "bottom"], "hero");
   view.key(" ");
-  expect(view.drag).toBeNull();
-  expect(view.onBlockedEditAttempt).toHaveBeenCalledWith(
-    expect.objectContaining({ id: "hero" }),
-    "edit-many",
-  );
+  expect(view.drag).not.toBeNull();
+  expect(view.onBlockedEditAttempt).not.toHaveBeenCalled();
+  act(() => view.root.unmount());
 });

package/src/player/components/useTimelineClipDrag.resize.test.tsx

@@ -380,13 +380,10 @@ describe("useTimelineClipDrag — multi-select group resize (restored)", () => {
 
     expect(h.onResizeElement).not.toHaveBeenCalled();
     expect(h.onResizeElements).toHaveBeenCalledTimes(1);
-    expect(h.onResizeElements).toHaveBeenCalledWith(
-      [
-        expect.objectContaining({ element: a, duration: 2.5 }),
-        expect.objectContaining({ element: b, duration: 3.5 }),
-      ],
-      { coalesceKey: expect.stringMatching(/^clip-group-resize:/) },
-    );
+    expect(h.onResizeElements).toHaveBeenCalledWith([
+      expect.objectContaining({ element: a, duration: 2.5 }),
+      expect.objectContaining({ element: b, duration: 3.5 }),
+    ]);
     expect(h.storeById("a").duration).toBe(2.5);
     expect(h.getResizeProjection()).toHaveLength(0);
     expect(h.storeById("b").duration).toBe(3.5);

package/src/player/components/useTimelineClipDrag.ts

@@ -31,7 +31,6 @@ import type {
 } from "./timelineClipDragTypes";
 import { getTimelineElementIndexes } from "../lib/timelineElementIndexes";
 import { dropMisalignedTrimPartners, linkedGestureKeys } from "./audioClipLink";
-import { exceedsHandEditLimit } from "./timelineLinkSelection";
 import { isLinkedSelectionOn } from "../../utils/linkedClipPreferences";
 import { useTimelineClipCapabilities } from "./timelineReadOnly";
 import { timelineClipFocusId } from "./timelineNavigationIdentity";
@@ -526,8 +525,6 @@ export function useTimelineClipDrag({
       if (!element || !getClipCapabilities(element).canMove) return;
       event.preventDefault();
       event.stopImmediatePropagation();
-      if (exceedsHandEditLimit(element, false, null))
-        return void onBlockedEditAttemptRef.current?.(element, "edit-many");
       setShowPopover(false);
       setRangeSelectionRef.current?.(null);
       const row = keyboardPickupInsertRow(

package/src/player/components/useTimelineKeyframeHandlers.ts

@@ -4,6 +4,7 @@ import {
   type PointerEvent as ReactPointerEvent,
 } from "react";
 import { clipToTweenPercentage } from "../../components/editor/KeyframeNavigation";
+import { progressAtTime, runEaseOf, timeAtProgress } from "../../utils/gsapKeyframeEases";
 import {
   KEYFRAME_DRAG_THRESHOLD_PX,
   previewClipPct,
@@ -162,6 +163,15 @@ export function subscribeTimelineKeyframeRetimePreview(
   return () => coordinator.previewListeners.delete(listener);
 }
 
+function retimedRunEase(actor: TimelineKeyframeRetimeActor): string | undefined {
+  const id = actor.target.animationId;
+  if (id === undefined) return undefined;
+  const { gsapAnimations } = usePlayerStore.getState();
+  const animations = gsapAnimations.get(actor.elementId) ?? [...gsapAnimations.values()].flat();
+  const animation = animations.find((candidate) => candidate.id === id);
+  return animation ? runEaseOf(animation) : undefined;
+}
+
 function resolveRetimeTweenPercentage(
   actor: TimelineKeyframeRetimeActor,
   toClipPercentage: number,
@@ -173,7 +183,13 @@ function resolveRetimeTweenPercentage(
   const tweenPercentages = animationKeyframes
     .map((keyframe) => keyframe.tweenPercentage)
     .filter((value): value is number => typeof value === "number");
-  const mapped = clipToTweenPercentage(animationKeyframes, toClipPercentage);
+  const runEase = retimedRunEase(actor);
+  const timed = animationKeyframes.map((keyframe) =>
+    keyframe.tweenPercentage === undefined
+      ? keyframe
+      : { ...keyframe, tweenPercentage: timeAtProgress(runEase, keyframe.tweenPercentage) },
+  );
+  const mapped = progressAtTime(runEase, clipToTweenPercentage(timed, toClipPercentage));
   if (tweenPercentages.length === 0) return mapped;
   return Math.max(Math.min(...tweenPercentages), Math.min(Math.max(...tweenPercentages), mapped));
 }

package/src/player/store/batchElementUpdates.test.ts

@@ -0,0 +1,43 @@
+// @vitest-environment happy-dom
+import { beforeEach, describe, expect, it } from "vitest";
+import { batchElementUpdates } from "./batchElementUpdates";
+import { usePlayerStore, type TimelineElement } from "./playerStore";
+
+const clips = (n: number): TimelineElement[] =>
+  Array.from({ length: n }, (_, i) => ({
+    id: `c${i}`,
+    tag: "div",
+    start: i,
+    duration: 1,
+    track: 0,
+  }));
+
+describe("batchElementUpdates", () => {
+  beforeEach(() => {
+    usePlayerStore.getState().reset();
+    usePlayerStore.getState().setElements(clips(4));
+  });
+
+  it("lands every update of a batch as one store change, as the same calls one by one would", () => {
+    const { updateElement } = usePlayerStore.getState();
+    let notified = 0;
+    const stop = usePlayerStore.subscribe(() => notified++);
+    batchElementUpdates(() => {
+      updateElement("c0", { start: 10 });
+      batchElementUpdates(() => updateElement("c2", { start: 12 }));
+      updateElement("c0", { track: 3 });
+    });
+    stop();
+
+    expect(notified).toBe(1);
+    const byId = new Map(usePlayerStore.getState().elements.map((el) => [el.id, el]));
+    expect(byId.get("c0")).toMatchObject({ start: 10, track: 3 });
+    expect(byId.get("c1")?.start).toBe(1);
+    expect(byId.get("c2")?.start).toBe(12);
+  });
+
+  it("applies updates outside a batch at once", () => {
+    usePlayerStore.getState().updateElement("c1", { start: 7 });
+    expect(usePlayerStore.getState().elements[1]?.start).toBe(7);
+  });
+});

package/src/player/store/batchElementUpdates.ts

@@ -0,0 +1,9 @@
+import { collectElementPatches, patchElements } from "./elementPatchQueue";
+import { usePlayerStore } from "./playerStore";
+
+/** `updateElement` calls inside `run` land as one store update: one pass over the list, one notification. */
+export function batchElementUpdates(run: () => void): void {
+  const patches = collectElementPatches(run);
+  if (!patches || patches.size === 0) return;
+  usePlayerStore.setState((state) => ({ elements: patchElements(state.elements, patches) }));
+}

package/src/player/store/elementPatchQueue.ts

@@ -0,0 +1,35 @@
+import type { TimelineElement, TimelineElementPatch } from "./timelineElement";
+
+let queued: Map<string, TimelineElementPatch> | null = null;
+
+/** Queues `updates` while a batch is collecting; false means the caller applies it now. */
+export function queueElementPatch(key: string, updates: TimelineElementPatch): boolean {
+  if (!queued) return false;
+  queued.set(key, { ...queued.get(key), ...updates });
+  return true;
+}
+
+/** Runs `run`, returning the patches it queued; null when an outer batch already collects them. */
+export function collectElementPatches(run: () => void): Map<string, TimelineElementPatch> | null {
+  if (queued) {
+    run();
+    return null;
+  }
+  const patches = (queued = new Map());
+  try {
+    run();
+  } finally {
+    queued = null;
+  }
+  return patches;
+}
+
+export function patchElements(
+  elements: TimelineElement[],
+  patches: ReadonlyMap<string, TimelineElementPatch>,
+): TimelineElement[] {
+  return elements.map((el) => {
+    const patch = patches.get(el.key ?? el.id);
+    return patch ? { ...el, ...patch } : el;
+  });
+}

package/src/player/store/playerStore.ts

@@ -21,6 +21,7 @@ import { createThumbnailSlice, type ThumbnailSlice } from "./thumbnailSlice";
 import { createPlaybackReadinessSlice } from "./readinessSlice";
 import { createRangeSelectionSlice, type RangeSelectionSlice } from "./rangeSelectionSlice";
 import { createTimelineResetState } from "./timelineResetState";
+import { patchElements, queueElementPatch } from "./elementPatchQueue";
 export type { KeyframeCacheEntry } from "./keyframeSlice";
 export { liveTime } from "./liveTime";
 import { liveTime } from "./liveTime";
@@ -547,12 +548,10 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
         focusedEaseSegment: id === s.selectedElementId ? s.focusedEaseSegment : null,
       };
     }),
-  updateElement: (elementId, updates) =>
-    set((state) => ({
-      elements: state.elements.map((el) =>
-        (el.key ?? el.id) === elementId ? { ...el, ...updates } : el,
-      ),
-    })),
+  updateElement: (elementId, updates) => {
+    if (queueElementPatch(elementId, updates)) return;
+    set((state) => ({ elements: patchElements(state.elements, new Map([[elementId, updates]])) }));
+  },
   // UI preferences intentionally survive reset. So do timelineSessionEpoch and
   // focusedEaseRequestNonce: the epoch advances only when project identity
   // changes, while a monotonic nonce prevents collisions with stale consumers.

package/src/utils/domEditHelpers.ts

@@ -1,5 +1,6 @@
 import type { DomEditSelection } from "../components/editor/domEditing";
 import { getDomEditTargetKey } from "../components/editor/domEditing";
+import { sameData } from "./sameData";
 
 export function domEditSelectionsTargetSame(
   a: DomEditSelection | null,
@@ -10,6 +11,10 @@ export function domEditSelectionsTargetSame(
   return getDomEditTargetKey(a) === getDomEditTargetKey(b);
 }
 
+export function domEditSelectionsEqual(a: DomEditSelection, b: DomEditSelection): boolean {
+  return sameData(a, b);
+}
+
 export function domEditSelectionInGroup(
   group: DomEditSelection[],
   selection: DomEditSelection | null,

package/src/utils/globalTimeCompiler.test.ts

@@ -112,10 +112,6 @@ describe("resolveTweenDuration", () => {
   test("missing duration defaults to GSAP default (0.5)", () => {
     expect(resolveTweenDuration(makeAnim({ duration: undefined }))).toBe(0.5);
   });
-
-  test("missing duration can use its editor timing basis", () => {
-    expect(resolveTweenDuration(makeAnim({ duration: undefined }), 16.26)).toBe(16.26);
-  });
 });
 
 describe("findTweenAtTime", () => {

package/src/utils/globalTimeCompiler.ts

@@ -1,4 +1,6 @@
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import { GSAP_DEFAULT_DURATION } from "@hyperframes/parsers/gsap-parser";
+import { progressAtTime, runEaseOf, timeAtProgress } from "./gsapKeyframeEases";
 
 export function absoluteToPercentage(
   time: number,
@@ -34,8 +36,8 @@ export function resolveTweenStart(animation: GsapAnimation): number | null {
   return null;
 }
 
-export function resolveTweenDuration(animation: GsapAnimation, fallback = 0.5): number {
-  return animation.duration ?? fallback;
+export function resolveTweenDuration(animation: GsapAnimation): number {
+  return animation.duration ?? GSAP_DEFAULT_DURATION;
 }
 
 export function findTweenAtTime(
@@ -60,7 +62,7 @@ export function absoluteToPercentageForAnimation(
   const start = resolveTweenStart(animation);
   if (start === null) return null;
   const duration = resolveTweenDuration(animation);
-  return absoluteToPercentage(time, start, duration);
+  return progressAtTime(runEaseOf(animation), absoluteToPercentage(time, start, duration));
 }
 
 export function percentageToAbsoluteForAnimation(
@@ -70,7 +72,7 @@ export function percentageToAbsoluteForAnimation(
   const start = resolveTweenStart(animation);
   if (start === null) return null;
   const duration = resolveTweenDuration(animation);
-  return percentageToAbsolute(pct, start, duration);
+  return percentageToAbsolute(timeAtProgress(runEaseOf(animation), pct), start, duration);
 }
 
 function matchesSelector(tweenSelector: string, querySelector: string): boolean {

package/src/utils/gsapKeyframeEases.ts

@@ -0,0 +1,79 @@
+import gsap from "gsap";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+
+// GSAP 3.15 defaults: a percentage keyframe eases its segment power1.inOut; an array step is linear.
+export const PERCENTAGE_SEGMENT_EASE = "power1.inOut";
+export const ARRAY_STEP_EASE = "none";
+// A motionPath tween is a plain tween to GSAP, so it runs GSAP's default tween ease.
+export const MOTION_PATH_RUN_EASE = "power1.out";
+
+/** `run` warps a keyframed tween's whole progress; a segment eases with the keyframe it arrives
+ *  at, else easeEach, else GSAP's default for the form. A flat tween has no run ease. */
+export function keyframedTweenEases(anim: GsapAnimation): {
+  run?: string;
+  segment: (arriving: { ease?: string }) => string;
+} {
+  const data = anim.keyframes;
+  const fallback =
+    data?.format === "object-array" ? ARRAY_STEP_EASE : (data?.easeEach ?? PERCENTAGE_SEGMENT_EASE);
+  return {
+    run: data
+      ? (data.ease ?? anim.ease ?? (data.fromMotionPath ? MOTION_PATH_RUN_EASE : undefined))
+      : undefined,
+    segment: (arriving) => arriving.ease ?? fallback,
+  };
+}
+
+export function easeFunction(name: string | undefined): ((progress: number) => number) | null {
+  if (!name || name === "none" || name === "linear") return null;
+  return gsap.parseEase(name) ?? null;
+}
+
+export const runEaseOf = (anim: GsapAnimation) => keyframedTweenEases(anim).run;
+
+const SCAN_STEPS = 200;
+const BISECT_STEPS = 40;
+const timingEases = new Map<string, ((progress: number) => number) | null>();
+
+/** The run ease as a one-to-one time/progress map; an ease that overshoots 0-1 or stalls times keys linearly. */
+function timingEase(runEase: string | undefined): ((progress: number) => number) | null {
+  if (!runEase) return null;
+  if (!timingEases.has(runEase)) {
+    const run = easeFunction(runEase);
+    const samples = Array.from(
+      { length: SCAN_STEPS + 1 },
+      (_, step) => run?.(step / SCAN_STEPS) ?? 0,
+    );
+    const oneToOne = samples.every((v, i) => v >= 0 && v <= 1 && (i === 0 || v > samples[i - 1]!));
+    timingEases.set(runEase, run && oneToOne ? run : null);
+  }
+  return timingEases.get(runEase) ?? null;
+}
+
+/** The keyframe progress (0-100) GSAP shows at `timePercentage` of a tween with this run ease. */
+export function progressAtTime(runEase: string | undefined, timePercentage: number): number {
+  const run = timingEase(runEase);
+  return run ? run(timePercentage / 100) * 100 : timePercentage;
+}
+
+/** The time (0-100 of the tween) at which GSAP first reaches keyframe progress `percentage`. */
+export function timeAtProgress(runEase: string | undefined, percentage: number): number {
+  const run = timingEase(runEase);
+  if (!run || percentage <= 0 || percentage >= 100) return percentage;
+  const target = percentage / 100;
+  let low = 0;
+  let high = 1;
+  for (let step = 1; step <= SCAN_STEPS; step++) {
+    if (run(step / SCAN_STEPS) >= target) {
+      low = (step - 1) / SCAN_STEPS;
+      high = step / SCAN_STEPS;
+      break;
+    }
+  }
+  for (let step = 0; step < BISECT_STEPS; step++) {
+    const mid = (low + high) / 2;
+    if (run(mid) >= target) high = mid;
+    else low = mid;
+  }
+  return high * 100;
+}