@hyperframes/studio 0.8.127 → 0.8.129

package/src/hooks/gsapDragPositionCommit.ts

@@ -1,8 +1,13 @@
-import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { GsapAnimation, GsapPercentageKeyframe } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { usePlayerStore } from "../player/store/playerStore";
-import { resolveTweenStart } from "../utils/globalTimeCompiler";
-import { KEYFRAME_PCT_MATCH, resolveEditableTweenDuration } from "./gsapShared";
+import {
+  isTimeWithinTween,
+  resolveTweenDuration,
+  resolveTweenStart,
+} from "../utils/globalTimeCompiler";
+import { KEYFRAME_PCT_MATCH, playsNear } from "./gsapShared";
+import { progressAtTime, runEaseOf, timeAtProgress } from "../utils/gsapKeyframeEases";
 import { roundTo3 } from "../utils/rounding";
 import { computeDraggedGsapPosition } from "./draggedGsapPosition";
 import {
@@ -19,7 +24,8 @@ import { commitValueAtPlayhead, planValueEdit } from "./gsapValueAtPlayhead";
  * server takes a replace-with-keyframes list verbatim, so an append-only build
  * could hand it two keyframes a fraction of a percent apart. The invariant lives
  * here rather than in each caller's own pre-check, which is how the two callers
- * ended up with different tolerances in the first place.
+ * ended up with different tolerances in the first place. Arc writes are linear, so each
+ * keyframe moves to the time GSAP reached it and `percentage` is a time percentage.
  */
 export function buildTemporalArcKeyframes(
   anim: GsapAnimation,
@@ -27,7 +33,7 @@ export function buildTemporalArcKeyframes(
   properties: Record<string, number>,
 ) {
   return [
-    ...(anim.keyframes?.keyframes ?? [])
+    ...linearArcKeyframes(anim)
       .filter((keyframe) => Math.abs(keyframe.percentage - percentage) > KEYFRAME_PCT_MATCH)
       .map((keyframe) => ({
         percentage: keyframe.percentage,
@@ -38,6 +44,46 @@ export function buildTemporalArcKeyframes(
   ].sort((a, b) => a.percentage - b.percentage);
 }
 
+/** An arc's keyframes at the time percentages GSAP plays them, for a write with `ease: "none"`. */
+export function linearArcKeyframes(anim: GsapAnimation): GsapPercentageKeyframe[] {
+  const runEase = runEaseOf(anim);
+  return (anim.keyframes?.keyframes ?? []).map((keyframe) => ({
+    ...keyframe,
+    percentage: roundTo3(timeAtProgress(runEase, keyframe.percentage)),
+  }));
+}
+
+/** Grow a keyframe tween's range to a playhead outside it and add a keyframe there; every
+ *  existing keyframe keeps its absolute time under `writeEase`, the run ease the write keeps. */
+export function buildExtendedKeyframes(
+  anim: GsapAnimation,
+  currentTime: number,
+  position: Record<string, number>,
+  sourceDuration = resolveTweenDuration(anim),
+  writeEase = runEaseOf(anim),
+): { position: number; duration: number; keyframes: GsapPercentageKeyframe[] } {
+  const oldStart = resolveTweenStart(anim) ?? 0;
+  const oldDuration = sourceDuration;
+  const newStart = Math.min(oldStart, currentTime);
+  const newEnd = Math.max(oldStart + oldDuration, currentTime);
+  const newDuration = roundTo3(newEnd - newStart);
+  const oldRunEase = runEaseOf(anim);
+  const toPct = (absoluteTime: number) => {
+    if (newDuration <= 0) return 0;
+    const progress = progressAtTime(writeEase, ((absoluteTime - newStart) / newDuration) * 100);
+    return Math.max(0, Math.min(100, Math.round(progress * 10) / 10));
+  };
+  const stops = anim.keyframes?.keyframes ?? [];
+  const rescaled: GsapPercentageKeyframe[] = stops.map((stop) => ({
+    percentage: toPct(oldStart + (timeAtProgress(oldRunEase, stop.percentage) / 100) * oldDuration),
+    properties: stop.properties,
+    ...(stop.ease ? { ease: stop.ease } : {}),
+  }));
+  const added: GsapPercentageKeyframe = { percentage: toPct(currentTime), properties: position };
+  const keyframes = [...rescaled, added].sort((a, b) => a.percentage - b.percentage);
+  return { position: roundTo3(newStart), duration: newDuration, keyframes };
+}
+
 /** commitGsapPositionFromDrag's refusal, decided without writing. */
 export function gsapPositionFromDragOutcome(
   selection: DomEditSelection,
@@ -87,15 +133,45 @@ export async function commitGsapPositionFromDrag(
   };
 
   if (anim.arcPath?.enabled) {
-    const { activeKeyframePct, setActiveKeyframePct } = usePlayerStore.getState();
+    const { activeKeyframePct, currentTime, setActiveKeyframePct } = usePlayerStore.getState();
+    const tweenStart = resolveTweenStart(anim);
+    const tweenDuration = resolveTweenDuration(anim);
+    if (
+      activeKeyframePct === null &&
+      tweenStart !== null &&
+      !isTimeWithinTween(currentTime, tweenStart, tweenDuration)
+    ) {
+      const extended = buildExtendedKeyframes(
+        anim,
+        currentTime,
+        { x: newX, y: newY },
+        tweenDuration,
+        "none",
+      );
+      await callbacks.commitMutation(
+        selection,
+        {
+          type: "replace-with-keyframes",
+          animationId: anim.id,
+          targetSelector: anim.targetSelector,
+          ...extended,
+          ease: "none",
+        },
+        {
+          label: "Move layer (new keyframe)",
+          keyframeAction: "add",
+          softReload: true,
+          beforeReload: restoreOffset,
+        },
+      );
+      return { status: "persisted" };
+    }
     const pct = activeKeyframePct ?? computeCurrentPercentage(selection, anim);
     const keyframes = anim.keyframes?.keyframes ?? [];
-    // Same tolerance as applyArcKeyframeAtPlayhead and isMotionPathEndpoint. A
-    // tighter one here meant a drag that landed a fraction of a percent off an
-    // authored waypoint skipped the update-point branch and appended instead.
-    const pointIndex = keyframes.findIndex(
-      (kf) => Math.abs(kf.percentage - pct) <= KEYFRAME_PCT_MATCH,
-    );
+    // A drag counts as on a waypoint when it plays within KEYFRAME_PCT_MATCH of it,
+    // so landing a fraction of a percent off an authored waypoint updates that point
+    // instead of appending a new one.
+    const pointIndex = keyframes.findIndex((kf) => playsNear(anim, kf.percentage, pct));
     if (pointIndex >= 0) {
       await callbacks.commitMutation(
         selection,
@@ -113,13 +189,10 @@ export async function commitGsapPositionFromDrag(
       return { status: "persisted" };
     }
 
-    const tweenStart = resolveTweenStart(anim);
-    // Clip-wide, same as applyArcKeyframeAtPlayhead: authoring GSAP's 0.5s
-    // default here would collapse a duration-less arc's window on drag.
-    const tweenDuration = resolveEditableTweenDuration(anim, selection);
     if (tweenStart === null || tweenDuration <= 0 || keyframes.length < 2)
       return { status: "persisted" };
-    const temporalKeyframes = buildTemporalArcKeyframes(anim, pct, { x: newX, y: newY });
+    const timePct = roundTo3(timeAtProgress(runEaseOf(anim), pct));
+    const temporalKeyframes = buildTemporalArcKeyframes(anim, timePct, { x: newX, y: newY });
     await callbacks.commitMutation(
       selection,
       {

package/src/hooks/gsapKeyframeCacheHelpers.test.ts

@@ -78,6 +78,56 @@ describe("non-string cache keys", () => {
   });
 });
 
+describe("replaceKeyframeCacheForFile re-reads", () => {
+  it("publishes nothing when a file re-reads to the same entries, and the change when one differs", () => {
+    const write = (x: number) =>
+      replaceKeyframeCacheForFile(
+        "comp.html",
+        new Map([
+          ["box", { format: "percentage", keyframes: [{ percentage: 0, properties: { x } }] }],
+        ]),
+        new Map([["box", [animWithKeyframes("box")]]]),
+      );
+    write(0);
+    let notified = 0;
+    const stop = usePlayerStore.subscribe(() => notified++);
+    write(0);
+    expect(notified).toBe(0);
+    write(5);
+    stop();
+    expect(notified).toBe(1);
+    expect(cache().get("comp.html#box")?.keyframes[0]?.properties).toEqual({ x: 5 });
+  });
+
+  it("leaves a sub-composition's entries alone when index.html re-reads", () => {
+    const one = (id: string) => new Map([[id, entry()]]);
+    const anims = (id: string) => new Map([[id, [animWithKeyframes(id)]]]);
+    replaceKeyframeCacheForFile("comp.html", one("box"), anims("box"));
+    replaceKeyframeCacheForFile("index.html", one("hero"), anims("hero"));
+    let notified = 0;
+    const stop = usePlayerStore.subscribe(() => notified++);
+    replaceKeyframeCacheForFile("index.html", one("hero"), anims("hero"));
+    stop();
+
+    expect(notified).toBe(0);
+    for (const key of ["comp.html#box", "index.html#box", "box", "index.html#hero", "hero"]) {
+      expect(cache().has(key)).toBe(true);
+    }
+  });
+
+  it("still drops index.html's own element that shares an id with a sub-composition", () => {
+    const one = (id: string) => new Map([[id, entry()]]);
+    const anims = (id: string) => new Map([[id, [animWithKeyframes(id)]]]);
+    const own = { format: "percentage", keyframes: [{ percentage: 0, properties: { x: 9 } }] };
+    replaceKeyframeCacheForFile("comp.html", one("title"), anims("title"));
+    replaceKeyframeCacheForFile("index.html", new Map([["title", own]]), anims("title"));
+    replaceKeyframeCacheForFile("index.html", new Map(), new Map());
+
+    expect(cache().has("index.html#title")).toBe(false);
+    expect(cache().has("comp.html#title")).toBe(true);
+  });
+});
+
 describe("clearKeyframeCacheForElement", () => {
   it("drops the prefixed, index.html fallback, and bare key for a non-index source", () => {
     seed("comp.html#box");

package/src/hooks/gsapKeyframeCacheHelpers.ts

@@ -5,6 +5,7 @@
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import { usePlayerStore, type KeyframeCacheEntry } from "../player/store/playerStore";
 import { trackStudioEvent } from "../utils/studioTelemetry";
+import { sameData } from "../utils/sameData";
 import { resolveClipTimingBasis, resolveSelectorElementIds, toClipKeyframes } from "./gsapShared";
 import {
   deduplicateKeyframes,
@@ -18,6 +19,14 @@ export interface KeyframeCacheDraft {
   gsapAnimations: Map<string, GsapAnimation[]>;
 }
 
+// A rebuilt entry equal to the one shown keeps its object, so re-reading an unchanged file publishes nothing.
+function keepEqualEntries<V>(before: ReadonlyMap<string, V>, draft: Map<string, V>): void {
+  for (const [key, value] of draft) {
+    const shown = before.get(key);
+    if (shown !== undefined && shown !== value && sameData(shown, value)) draft.set(key, shown);
+  }
+}
+
 function sameEntries<V>(before: ReadonlyMap<string, V>, after: ReadonlyMap<string, V>): boolean {
   if (before.size !== after.size) return false;
   for (const [key, value] of before) {
@@ -42,6 +51,8 @@ export function publishKeyframeCache(edit: (draft: KeyframeCacheDraft) => void):
     gsapAnimations: new Map(gsapAnimations),
   };
   edit(draft);
+  keepEqualEntries(keyframeCache, draft.keyframeCache);
+  keepEqualEntries(gsapAnimations, draft.gsapAnimations);
   if (
     sameEntries(keyframeCache, draft.keyframeCache) &&
     sameEntries(gsapAnimations, draft.gsapAnimations)
@@ -175,8 +186,16 @@ function cachedElementIdsForFile(
   const sfPrefix = `${sourceFile}#`;
   const ids = new Set<string>();
   for (const key of [...keyframeCache.keys(), ...gsapAnimations.keys()]) {
-    if (!key.startsWith(sfPrefix)) continue;
-    ids.add(key.slice(sfPrefix.length));
+    if (key.startsWith(sfPrefix)) ids.add(key.slice(sfPrefix.length));
+  }
+  if (sourceFile !== "index.html") return ids;
+  // Another file's element also writes the `index.html#id` fallback, as the very same entry object.
+  for (const [key, entry] of keyframeCache) {
+    const hash = key.indexOf("#");
+    const id = key.slice(hash + 1);
+    if (hash > 0 && !key.startsWith(sfPrefix) && keyframeCache.get(sfPrefix + id) === entry) {
+      ids.delete(id);
+    }
   }
   return ids;
 }

package/src/hooks/gsapMutationClient.ts

@@ -88,9 +88,11 @@ function readMutationError(value: unknown, fallback: string): string {
   return fallback;
 }
 
+type GsapMutationRoute = "gsap-mutations" | "gsap-mutations-batch";
+
 export function requestGsapMutation(
   projectId: string,
-  route: "gsap-mutations" | "gsap-mutations-batch",
+  route: GsapMutationRoute,
   filePath: string,
   body: unknown,
 ): Promise<Response> {
@@ -104,23 +106,49 @@ export function requestGsapMutation(
   );
 }
 
-export async function postGsapMutation(
+async function postOwnedGsapMutation(
+  route: GsapMutationRoute,
   projectId: string,
   filePath: string,
-  mutation: Record<string, unknown>,
+  body: Record<string, unknown>,
   fallback: string,
 ): Promise<GsapMutationStatus> {
   let response: Response;
   try {
-    response = await requestGsapMutation(projectId, "gsap-mutations", filePath, mutation);
+    response = await requestGsapMutation(projectId, route, filePath, body);
   } catch (error) {
     throw new GsapPreviewConvergenceError(`${fallback}: mutation outcome unknown`, {
       cause: error,
     });
   }
-  const body: unknown = await response.json().catch(() => null);
+  const payload: unknown = await response.json().catch(() => null);
   if (!response.ok) {
-    throw new GsapPreviewConvergenceError(readMutationError(body, fallback));
+    throw new GsapPreviewConvergenceError(readMutationError(payload, fallback));
   }
-  return readMutationStatus(body);
+  return readMutationStatus(payload);
+}
+
+export function postGsapMutation(
+  projectId: string,
+  filePath: string,
+  mutation: Record<string, unknown>,
+  fallback: string,
+): Promise<GsapMutationStatus> {
+  return postOwnedGsapMutation("gsap-mutations", projectId, filePath, mutation, fallback);
+}
+
+/** Every mutation in one request: the file is parsed and written once, with one ownership pair. */
+export function postGsapMutations(
+  projectId: string,
+  filePath: string,
+  mutations: readonly Record<string, unknown>[],
+  fallback: string,
+): Promise<GsapMutationStatus> {
+  return postOwnedGsapMutation(
+    "gsap-mutations-batch",
+    projectId,
+    filePath,
+    { mutations },
+    fallback,
+  );
 }

package/src/hooks/gsapOvershootEase.test.ts

@@ -0,0 +1,67 @@
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import { parseGsapScriptAcorn } from "@hyperframes/parsers/gsap-parser-acorn";
+import { replaceTweenWithKeyframesInScript } from "@hyperframes/parsers/gsap-writer-acorn";
+import { describe, expect, it } from "vitest";
+import { resolveKeyframeRetime } from "../components/editor/keyframeRetime";
+import { absoluteToPercentageForAnimation } from "../utils/globalTimeCompiler";
+import { runEaseOf, timeAtProgress } from "../utils/gsapKeyframeEases";
+import { buildExtendedKeyframes } from "./gsapDragPositionCommit";
+import { keyframeEases } from "./gsapShared";
+
+const script = (ease: string) =>
+  `const tl = gsap.timeline({ paused: true });\ntl.to("#x", { keyframes: { "0%": { x: 0 }, "50%": { x: 600 }, "100%": { x: 1200 } }, duration: 2, ease: "${ease}" }, 1);`;
+
+const percentages = (anim: GsapAnimation) => anim.keyframes!.keyframes.map((k) => k.percentage);
+const distinctInRange = (pcts: number[]) =>
+  pcts.every((p, i) => p >= 0 && p <= 100 && (i === 0 || p > pcts[i - 1]!));
+
+describe.each(["back.out(1.7)", "back.in(1.7)", "elastic.out(1, 0.3)", "steps(4)"])(
+  "an outer %s, which does not map time to progress one to one",
+  (ease) => {
+    const src = script(ease);
+    const anim = parseGsapScriptAcorn(src).animations[0]!;
+
+    it("adding a keyframe past the end keeps every keyframe, distinct and in range, after a reparse", () => {
+      const out = buildExtendedKeyframes(anim, 5, { x: 1500 });
+      const written = replaceTweenWithKeyframesInScript(src, anim.id, {
+        targetSelector: "#x",
+        ...keyframeEases(anim),
+        ...out,
+      })!;
+      const back = parseGsapScriptAcorn(written).animations[0]!;
+      expect(distinctInRange(percentages(back))).toBe(true);
+      expect(back.keyframes!.keyframes.map((k) => k.properties.x)).toEqual([0, 600, 1200, 1500]);
+    });
+
+    it("a keyframe added inside the tween lands within 0-100%", () => {
+      const pct = absoluteToPercentageForAnimation(1 + 0.7 * 2, anim)!;
+      expect(pct).toBeGreaterThanOrEqual(0);
+      expect(pct).toBeLessThanOrEqual(100);
+    });
+
+    it("dragging the last keyframe later keeps every keyframe distinct and in range", () => {
+      const retime = resolveKeyframeRetime({
+        keyframes: anim.keyframes!.keyframes,
+        draggedTweenPct: 100,
+        tweenStart: 1,
+        tweenDuration: 2,
+        dropAbsTime: 4,
+        runEase: runEaseOf(anim),
+      });
+      expect(retime.kind).toBe("resize");
+      expect(distinctInRange(retime.pctRemap!.map((r) => r.to))).toBe(true);
+    });
+  },
+);
+
+it("extending a tween under steps(4) loses no keyframe", () => {
+  const src = `const tl = gsap.timeline({ paused: true });\ntl.to("#x", { keyframes: { "0%": { x: 0 }, "25%": { x: 60 }, "60%": { x: 120 }, "100%": { x: 30 } }, duration: 2, ease: "steps(4)" }, 1);`;
+  const anim = parseGsapScriptAcorn(src).animations[0]!;
+  const out = buildExtendedKeyframes(anim, 4, { x: 999 });
+  expect(distinctInRange(out.keyframes.map((k) => k.percentage))).toBe(true);
+  expect(out.keyframes.map((k) => k.properties.x)).toEqual([0, 60, 120, 30, 999]);
+});
+
+it("still times keyframes through an outer ease that rises one to one", () => {
+  expect(timeAtProgress("power2.in", 50)).toBeCloseTo(79.37, 1);
+});

package/src/hooks/gsapParsedTween.ts

@@ -247,14 +247,13 @@ const BUILT_IN_EASES = [
 export function withExactStepTimes(anim: GsapAnimation, tween: ParsedTween | null): GsapAnimation {
   const data = anim.keyframes;
   const parts = tween?.timeline?.getChildren?.() ?? [];
-  const total = tween?.timeline?.duration?.() ?? 0;
-  if (data?.format !== "object-array" || parts.length !== data.keyframes.length || !(total > 0))
-    return anim;
-  const ends = parts.map((part) => ((part.startTime?.() ?? 0) + (part.duration?.() ?? 0)) / total);
-  if (ends.some((end) => !Number.isFinite(end))) return anim;
+  if (data?.format !== "object-array" || parts.length !== data.keyframes.length) return anim;
+  const ends = parts.map((part) => (part.startTime?.() ?? 0) + (part.duration?.() ?? 0));
+  const total = Math.max(...ends);
+  if (!(total > 0) || ends.some((end) => !Number.isFinite(end))) return anim;
   const keyframes = data.keyframes.map((kf, i) => ({
     ...kf,
-    percentage: Math.round(ends[i]! * 100000) / 1000,
+    percentage: Math.round((ends[i]! / total) * 100000) / 1000,
   }));
   return { ...anim, keyframes: { ...data, keyframes } };
 }

package/src/hooks/gsapPositionDetection.ts

@@ -8,6 +8,7 @@
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import { usePlayerStore } from "../player/store/playerStore";
 import { getIframeGsap, KEYFRAME_PCT_MATCH, queryIframeElement } from "./gsapShared";
+import { runEaseOf, timeAtProgress } from "../utils/gsapKeyframeEases";
 import { resolveTweenStart, resolveTweenDuration } from "../utils/globalTimeCompiler";
 
 // fallow-ignore-next-line complexity
@@ -60,7 +61,7 @@ export function findGsapPositionAnimation(
 
 function playheadProximity(a: GsapAnimation, currentTime: number): number {
   const pos = a.resolvedStart ?? (typeof a.position === "number" ? a.position : 0);
-  const dur = a.duration ?? 0;
+  const dur = resolveTweenDuration(a);
   if (currentTime >= pos - 0.05 && currentTime <= pos + dur + 0.05) return 50;
   return -Math.round(Math.min(Math.abs(currentTime - pos), Math.abs(currentTime - pos - dur)) * 5);
 }
@@ -71,7 +72,9 @@ function statesValueAt(anim: GsapAnimation, time: number): boolean {
   if (!(duration > 0)) return false;
   const pct = ((time - (resolveTweenStart(anim) ?? 0)) / duration) * 100;
   const near = (keyframe: number) => Math.abs(keyframe - pct) <= KEYFRAME_PCT_MATCH;
-  if (anim.keyframes) return anim.keyframes.keyframes.some((kf) => near(kf.percentage));
+  const runEase = runEaseOf(anim);
+  if (anim.keyframes)
+    return anim.keyframes.keyframes.some((kf) => near(timeAtProgress(runEase, kf.percentage)));
   if (anim.method === "from") return near(0);
   return near(100) || (anim.method === "fromTo" && near(0));
 }

package/src/hooks/gsapRuntimeBridge.test.ts

@@ -582,6 +582,41 @@ describe("tryGsapDragIntercept — motion paths", () => {
     );
   });
 
+  it("adds a node at a playhead past a duration-less arc, keeping the other nodes' times", async () => {
+    usePlayerStore.setState({
+      autoKeyframeEnabled: true,
+      activeKeyframePct: null,
+      currentTime: 15.9,
+    });
+    const durationless = { ...motionPathAnim, duration: undefined } as GsapAnimation;
+    const commitMutation = vi.fn();
+    await tryGsapDragIntercept(
+      selection,
+      { x: -50, y: 30 },
+      [durationless],
+      fakeIframe("puck-b", [
+        { ...liveTween, vars: { motionPath: { path: [] } }, duration: () => 0.5 },
+      ]),
+      commitMutation,
+    );
+    // GSAP plays it 12.17-12.67 s; the nodes stay at 12.17, 12.42 and 12.67 s.
+    expect(commitMutation).toHaveBeenCalledWith(
+      selection,
+      expect.objectContaining({
+        type: "replace-with-keyframes",
+        position: 12.17,
+        duration: 3.73,
+        keyframes: [
+          { percentage: 0, properties: { x: -184, y: 326 } },
+          { percentage: 6.7, properties: { x: 416, y: 804 } },
+          { percentage: 13.4, properties: { x: 796, y: 237 } },
+          { percentage: 100, properties: { x: -50, y: 30 } },
+        ],
+      }),
+      expect.objectContaining({ label: "Move layer (new keyframe)", keyframeAction: "add" }),
+    );
+  });
+
   it("keeps an explicitly selected path waypoint as a spatial edit", async () => {
     const { commitMutation, handled } = await dragMotionPath(50);
 

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]);
+  });
+});