@hyperframes/studio 0.8.134 → 0.8.136

package/src/hooks/gsapPlaybackTestHarness.ts

@@ -0,0 +1,28 @@
+import { gsap } from "gsap";
+
+type KeyframeMutation = {
+  duration: number;
+  ease?: string;
+  easeEach?: string;
+  keyframes: Array<{
+    percentage: number;
+    properties: Record<string, number | string>;
+    ease?: string;
+  }>;
+};
+
+/** Plays a replace-with-keyframes mutation in real GSAP and reads `x` at `time` seconds. */
+export function xAtTime(mutation: KeyframeMutation, time: number): number {
+  const target = { x: 0, y: 0, opacity: 1 };
+  const frames: Record<string, unknown> = mutation.easeEach ? { easeEach: mutation.easeEach } : {};
+  for (const kf of mutation.keyframes) {
+    frames[`${kf.percentage}%`] = { ...kf.properties, ...(kf.ease ? { ease: kf.ease } : {}) };
+  }
+  const vars = {
+    duration: mutation.duration,
+    keyframes: frames,
+    ...(mutation.ease ? { ease: mutation.ease } : {}),
+  };
+  gsap.timeline({ paused: true }).to(target, vars, 0).seek(time);
+  return target.x;
+}

package/src/hooks/gsapRuntimePatch.ts

@@ -19,6 +19,7 @@ import {
   type RuntimeTween,
   type RuntimeTimeline,
 } from "./gsapRuntimeKeyframes";
+import { recordLiveSet } from "../utils/softReloadTargets";
 
 /** Value-only channels a `tl.set(...)` patch may touch. */
 export interface SetPatchProps {
@@ -34,6 +35,8 @@ export interface SetPatchProps {
   scaleY?: number;
   scale?: number;
   opacity?: number;
+  width?: number;
+  height?: number;
 }
 
 /** A single keyframe step's numeric channels (the GSAP array-keyframe form). */
@@ -101,6 +104,7 @@ function applyGlobalSet(
     const numeric = finiteNumericProps(props);
     if (!gsapLib?.set || !el || !numeric) return false;
     gsapLib.set(el, numeric);
+    recordLiveSet(el, numeric);
     return true;
   } catch {
     return false;

package/src/hooks/gsapShared.test.ts

@@ -4,6 +4,7 @@ import {
   idFromSelector,
   idSelector,
   isInstantHold,
+  keyframeEases,
   parsePercentageKeyframes,
   resolveClipTimingBasis,
   playsNear,
@@ -11,6 +12,16 @@ import {
   toClipPercentage,
 } from "./gsapShared";
 
+describe("keyframeEases", () => {
+  it("carries the keyframes' own ease into the tween ease, which GSAP plays the same", () => {
+    const anim = {
+      ease: "back.out",
+      keyframes: { keyframes: [], ease: "sine.inOut", easeEach: "power2.out" },
+    } as unknown as GsapAnimation;
+    expect(keyframeEases(anim)).toEqual({ ease: "sine.inOut", easeEach: "power2.out" });
+  });
+});
+
 describe("isInstantHold", () => {
   const animation = (method: GsapAnimation["method"], duration?: number) =>
     ({ method, duration }) as unknown as GsapAnimation;

package/src/hooks/gsapShared.ts

@@ -41,7 +41,7 @@ export const PROPERTY_DEFAULTS: Record<string, number> = {
  *  since GSAP eases each percentage segment power1.inOut whatever the tween-level ease says. */
 export function keyframeEases(anim: GsapAnimation): { ease?: string; easeEach?: string } {
   if (!anim.keyframes) return { easeEach: anim.ease };
-  return { ease: anim.ease, easeEach: anim.keyframes.easeEach };
+  return { ease: runEaseOf(anim), easeEach: anim.keyframes.easeEach };
 }
 
 /**

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

@@ -0,0 +1,37 @@
+// Real gsap: the ease the parser reports for keyframes must be the one GSAP plays.
+import { parseGsapScriptAcorn } from "@hyperframes/core/gsap-parser-acorn";
+import { gsap } from "gsap";
+import { describe, expect, it } from "vitest";
+
+const STEPS = { "0%": { x: 0 }, "100%": { x: 10 } };
+
+function xAt(vars: gsap.TweenVars, time = 0.3): number {
+  const target = { x: 0 };
+  gsap
+    .timeline({ paused: true })
+    .to(target, { duration: 1, ...vars }, 0)
+    .seek(time);
+  return target.x;
+}
+
+const parsedEaseEach = (vars: string) =>
+  parseGsapScriptAcorn(`const tl = gsap.timeline({ paused: true });
+tl.to("#a", { duration: 1, ${vars} }, 0);`).animations[0]!.keyframes?.easeEach;
+
+describe("the keyframes ease the parser reports", () => {
+  it("is not a tween-level easeEach, which GSAP ignores", () => {
+    expect(xAt({ keyframes: STEPS, easeEach: "power4.in" })).toBe(xAt({ keyframes: STEPS }));
+    expect(
+      parsedEaseEach('keyframes: { "0%": { x: 0 }, "100%": { x: 10 } }, easeEach: "power4.in"'),
+    ).toBeUndefined();
+  });
+
+  it("is an easeEach inside the keyframes, which GSAP plays", () => {
+    expect(xAt({ keyframes: { ...STEPS, easeEach: "power4.in" } })).not.toBe(
+      xAt({ keyframes: STEPS }),
+    );
+    expect(
+      parsedEaseEach('keyframes: { "0%": { x: 0 }, "100%": { x: 10 }, easeEach: "power4.in" }'),
+    ).toBe("power4.in");
+  });
+});

package/src/hooks/useAnimatedPropertyCommit.test.tsx

@@ -10,6 +10,7 @@ import { mountReactHarness, withInlineLayoutBox } from "./domSelectionTestHarnes
 import { writeSizeWithCrop } from "../components/editor/cropResize";
 import { trackStudioEvent } from "../utils/studioTelemetry";
 import { trackKeyframeCommit } from "../utils/keyframeUsage";
+import { xAtTime } from "./gsapPlaybackTestHarness";
 import type { CommitMutationOptions, CommitMutation } from "./gsapScriptCommitTypes";
 
 vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
@@ -205,6 +206,38 @@ function renderCommitHook(
 // canvas nudge exercises (not the raw drag intercept) — with auto-keyframe
 // off, it must shift the whole tween instead of adding/updating a keyframe
 // at the playhead.
+describe("useAnimatedPropertyCommit — extending a keyframed tween to the playhead", () => {
+  it("keeps the tween's eases and each keyframe's own ease", async () => {
+    usePlayerStore.setState({ autoKeyframeEnabled: true, currentTime: 3, activeKeyframePct: null });
+    const eased = {
+      ...keyframedAnim,
+      ease: "power2.inOut",
+      keyframes: {
+        easeEach: "power2.out",
+        keyframes: [
+          { percentage: 0, properties: { x: 0, y: 0 }, ease: "expo.in" },
+          { percentage: 100, properties: { x: 100, y: 0 } },
+        ],
+      },
+    } as unknown as GsapAnimation;
+    const mutations: Array<Record<string, unknown>> = [];
+    let commit!: Commit;
+    const root = renderHookWith(
+      [eased],
+      (mutation) => mutations.push(mutation),
+      (ready) => (commit = ready),
+    );
+    await act(async () => commit(selection, { x: 50 }));
+    act(() => root.unmount());
+
+    const replace = mutations.find((m) => m.type === "replace-with-keyframes")!;
+    expect(replace).toMatchObject({ ease: "power2.inOut", easeEach: "power2.out" });
+    expect((replace.keyframes as Array<{ ease?: string }>)[0]!.ease).toBe("expo.in");
+    // The old end keyframe still plays at 2 s once the tween runs to the playhead at 3 s.
+    expect(xAtTime(replace as unknown as Parameters<typeof xAtTime>[0], 2)).toBeCloseTo(100, 0);
+  });
+});
+
 describe("useAnimatedPropertyCommit — autoKeyframeEnabled toggle (#1808)", () => {
   async function runCommitWithAutoKeyframe(enabled: boolean) {
     usePlayerStore.setState({ autoKeyframeEnabled: enabled, currentTime: 0 });

package/src/hooks/useAnimatedPropertyCommit.ts

@@ -18,6 +18,7 @@ import {
   selectorFromSelection,
   computeElementPercentage,
   isInstantHold,
+  keyframeEases,
   writeTargetSelector,
   tweenTargetsElement,
 } from "./gsapShared";
@@ -375,7 +376,7 @@ async function commitKeyframeProps(
       for (const k of Object.keys(properties)) {
         if (!(k in p) && backfillDefaults[k] != null) p[k] = backfillDefaults[k];
       }
-      return { percentage: newPct, properties: p };
+      return { percentage: newPct, properties: p, ...(kf.ease ? { ease: kf.ease } : {}) };
     });
     remapped.push({ percentage: toNewPct(ct), properties });
     remapped.sort((a, b) => a.percentage - b.percentage);
@@ -388,6 +389,7 @@ async function commitKeyframeProps(
         position: roundTo3(newStart),
         duration: roundTo3(newDuration),
         keyframes: remapped,
+        ...keyframeEases(anim),
       },
       { label: `Edit ${primaryProp} (extended keyframe)`, keyframeAction: "add", softReload: true },
     );

package/src/hooks/useDomGeometryCommits.test.tsx

@@ -376,6 +376,27 @@ describe("Reset after a plain move puts the author's translate back", () => {
   });
 });
 
+describe("useDomGeometryCommits undo steps", () => {
+  it("never merges a resize with the next size edit of the same element", async () => {
+    const element = document.createElement("div");
+    element.id = "box";
+    document.body.append(element);
+    const selection = { id: "box", selector: "#box", element } as unknown as DomEditSelection;
+    const commitPositionPatchToHtml = vi
+      .fn<UseDomGeometryCommitsParams["commitPositionPatchToHtml"]>()
+      .mockResolvedValue(undefined);
+    const { commits, unmount } = mountCommits(commitPositionPatchToHtml);
+
+    await commits().handleDomBoxSizeCommit(selection, { width: 418, height: 200 });
+    await commits().handleDomBoxSizeCommit(selection, { width: 280, height: 200 });
+
+    const [resize, field] = commitPositionPatchToHtml.mock.calls.map(([, , options]) => options);
+    expect(resize!.coalesceKey).not.toBe(field!.coalesceKey);
+    unmount();
+    element.remove();
+  });
+});
+
 describe("useDomGeometryCommits resize of a cropped element", () => {
   it("saves the crop scaled per axis with the box in the resize's own commit", async () => {
     const element = withInlineLayoutBox(document.createElement("div"));

package/src/hooks/useDomGeometryCommits.ts

@@ -26,6 +26,8 @@ import {
 } from "../components/editor/manualEditsDomPatches";
 import type { PatchOperation } from "../utils/sourcePatcher";
 
+let boxSizeCommitCounter = 0;
+
 // ── Hook ──
 
 export interface UseDomGeometryCommitsParams {
@@ -90,7 +92,10 @@ export function useDomGeometryCommits({
         label: "Resize layer box",
         ...(undoKey
           ? { coalesceKey: undoKey, coalesceMs: Number.POSITIVE_INFINITY, deferRender: true }
-          : { coalesceKey: `box-size:${getDomEditTargetKey(selection)}` }),
+          : {
+              coalesceKey: `box-size:${++boxSizeCommitCounter}`,
+              coalesceMs: Number.POSITIVE_INFINITY,
+            }),
       }).catch((error) => {
         restoreStudioBoxSize(element, beforeSize);
         if (offset) restoreStudioPathOffset(element, beforeOffset);

package/src/hooks/useGestureCommit.test.tsx

@@ -10,6 +10,7 @@ import { mountReactHarness } from "./domSelectionTestHarness";
 import type { CommitMutationOptions } from "./gsapScriptCommitTypes";
 import { useGsapAwareEditing } from "./useGsapAwareEditing";
 import { useGestureCommit } from "./useGestureCommit";
+import { xAtTime } from "./gsapPlaybackTestHarness";
 
 vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
 
@@ -243,6 +244,94 @@ it.each([
   },
 );
 
+const FROM_0_TO_100 = [
+  { percentage: 0, properties: { x: 0 } },
+  { percentage: 100, properties: { x: 100 } },
+];
+
+function positionTween(
+  duration: number,
+  eases: { ease?: string; easeEach?: string } = {},
+  keyframes = FROM_0_TO_100,
+) {
+  return {
+    id: "card-position",
+    targetSelector: "#card",
+    propertyGroup: "position",
+    method: "to",
+    properties: { x: 0, y: 0 },
+    resolvedStart: 0,
+    position: 0,
+    duration,
+    ...(eases.ease ? { ease: eases.ease } : {}),
+    keyframes: {
+      ...(eases.easeEach ? { easeEach: eases.easeEach } : {}),
+      keyframes,
+    },
+  } as unknown as GsapAnimation;
+}
+
+/** Records the mocked 1 s gesture (x 0, 50, 100) from 0 s over `tween`; resolves to the merge mutation. */
+async function recordMergeInto(tween: GsapAnimation) {
+  const writer = vi.fn(
+    async (_mutation: Record<string, unknown>, options: CommitMutationOptions) => {
+      options.onResult?.({ ok: true, changed: true });
+    },
+  );
+  const hook = mountRecording(writer, [tween]);
+  act(() => hook().handleToggleRecording("button"));
+  await act(async () => {
+    hook().handleToggleRecording();
+    await vi.waitFor(() => expect(writer).toHaveBeenCalled());
+  });
+  expect(writer.mock.calls[0]![1]).toMatchObject({ label: "Gesture recording (merge)" });
+  return writer.mock.calls[0]![0] as unknown as Parameters<typeof xAtTime>[0] & {
+    type: string;
+    ease?: string;
+    easeEach?: string;
+  };
+}
+
+it("keeps the tween's eases when a recording merges into it", async () => {
+  const merge = await recordMergeInto(
+    positionTween(2, { ease: "back.out", easeEach: "power2.out" }),
+  );
+  expect(merge).toMatchObject({
+    type: "replace-with-keyframes",
+    ease: "back.out",
+    easeEach: "power2.out",
+  });
+  // Recorded segments the fitter left unset stay constant speed instead of taking easeEach.
+  expect(merge.keyframes.map((kf) => kf.ease)).toEqual([undefined, "none", "none", undefined]);
+});
+
+it("plays a recording merged into an eased tween at the times it was recorded", async () => {
+  const merge = await recordMergeInto(positionTween(3, { ease: "power2.out" }));
+  expect(xAtTime(merge, 0.5)).toBeCloseTo(50, 0);
+  expect(xAtTime(merge, 1)).toBeCloseTo(100, 0);
+});
+
+it("keeps recorded keyframes apart over the tail of a power4.out tween", async () => {
+  usePlayerStore.setState({ currentTime: 9 });
+  const merge = await recordMergeInto(positionTween(10, { ease: "power4.out" }));
+  expect(xAtTime(merge, 9.5)).toBeCloseTo(50, 0);
+});
+
+it("keeps a keyframe playing at 8.5 s when a recording covers 9-10 s of a power2.out tween", async () => {
+  usePlayerStore.setState({ currentTime: 9 });
+  const at8_5s = { percentage: 99.6625, properties: { x: 80 } };
+  const merge = await recordMergeInto(
+    positionTween(10, { ease: "power2.out" }, [FROM_0_TO_100[0]!, at8_5s, FROM_0_TO_100[1]!]),
+  );
+  expect(merge.keyframes).toContainEqual(at8_5s);
+  expect(xAtTime(merge, 8.5)).toBeCloseTo(80, 0);
+});
+
+it("writes merged keyframe percentages rounded, not as float noise", async () => {
+  const merge = await recordMergeInto(positionTween(3));
+  expect(merge.keyframes.map((kf) => kf.percentage)).toEqual([0, 16.667, 33.333, 100]);
+});
+
 it("keeps a pending recording isolated until its writer settles", async () => {
   let release!: () => void;
   const pending = new Promise<void>((resolve) => {

package/src/hooks/useGestureCommit.ts

@@ -16,8 +16,15 @@ import { trackPreviewEditResult } from "../utils/previewFeatureUsage";
 import { observeGsapGesture } from "./gsapGestureOutcome";
 import { roundTo3 } from "../utils/rounding";
 import { classifyPropertyGroup } from "@hyperframes/core/gsap-parser";
-import { isInstantHold, idSelector, writeTargetSelector, tweenTargetsElement } from "./gsapShared";
+import {
+  isInstantHold,
+  idSelector,
+  keyframeEases,
+  writeTargetSelector,
+  tweenTargetsElement,
+} from "./gsapShared";
 import { useStableHandlers } from "./useStableHandlers";
+import { progressAtTime, runEaseOf, timeAtProgress, warpsTime } from "../utils/gsapKeyframeEases";
 
 type RecordedKeyframe = {
   percentage: number;
@@ -269,25 +276,34 @@ export function useGestureCommit({
 
             if (overlaps) {
               const existingKfs = existingPositionTween.keyframes?.keyframes ?? [];
-              const rangeStartPct =
+              const startTimePct =
                 tweenDur > 0 ? Math.max(0, ((recStart - tweenStart) / tweenDur) * 100) : 0;
-              const rangeEndPct =
+              const endTimePct =
                 tweenDur > 0 ? Math.min(100, ((recEnd - tweenStart) / tweenDur) * 100) : 100;
+              const runEase = runEaseOf(existingPositionTween);
+              const roundPct = warpsTime(runEase) ? (pct: number) => pct : roundTo3;
 
               const preserved = existingKfs
-                .filter(
-                  (kf) => kf.percentage < rangeStartPct - 0.5 || kf.percentage > rangeEndPct + 0.5,
-                )
+                .filter((kf) => {
+                  const playsAt = timeAtProgress(runEase, kf.percentage);
+                  return playsAt < startTimePct - 0.5 || playsAt > endTimePct + 0.5;
+                })
                 .map((kf) => ({
                   percentage: kf.percentage,
                   properties: kf.properties,
                   ...(kf.ease ? { ease: kf.ease } : {}),
                 }));
 
-              const mapped = keyframes.map((kf) => ({
-                percentage: rangeStartPct + (kf.percentage / 100) * (rangeEndPct - rangeStartPct),
+              const constantSpeed = { ease: "none" };
+              const mapped = keyframes.map((kf, index) => ({
+                percentage: roundPct(
+                  progressAtTime(
+                    runEase,
+                    startTimePct + (kf.percentage / 100) * (endTimePct - startTimePct),
+                  ),
+                ),
                 properties: kf.properties,
-                ...(kf.ease ? { ease: kf.ease } : {}),
+                ...(kf.ease ? { ease: kf.ease } : index > 0 ? constantSpeed : {}),
               }));
 
               const merged = [...preserved, ...mapped].sort((a, b) => a.percentage - b.percentage);
@@ -303,6 +319,7 @@ export function useGestureCommit({
                       : tweenStart,
                   duration: tweenDur,
                   keyframes: merged,
+                  ...keyframeEases(existingPositionTween),
                 },
                 { label: "Gesture recording (merge)", softReload: true, keyframeAction: "add" },
               );

package/src/icons/SystemIcons.tsx

@@ -24,6 +24,9 @@ import {
   Link as PhLink,
   Eyedropper as PhEyedropper,
   Trash as PhTrash,
+  Image as PhImage,
+  BezierCurve,
+  FolderSimple,
 } from "@phosphor-icons/react";
 import type { Icon as PhosphorIcon, IconProps as PhosphorIconProps } from "@phosphor-icons/react";
 
@@ -75,3 +78,6 @@ export const Scissors = makeIcon(PhScissors);
 export const Link = makeIcon(PhLink);
 export const Eyedropper = makeIcon(PhEyedropper);
 export const Trash = makeIcon(PhTrash);
+export const ImageIcon = makeIcon(PhImage);
+export const Vector = makeIcon(BezierCurve);
+export const Folder = makeIcon(FolderSimple);

package/src/layersPanelExport.test.tsx

@@ -29,12 +29,17 @@ afterEach(() => {
 });
 
 /** The host's preview (title in front of bg, rows to match) and its edit session, mounted around the panel. */
-async function mountPanel(wrap: (panel: ReactNode) => ReactNode = (panel) => panel) {
+const TWO_BOXES =
+  '<div data-composition-id="main"><div id="bg" style="z-index:1"></div><div id="title" style="z-index:2"></div></div>';
+
+async function mountPanel(
+  wrap: (panel: ReactNode) => ReactNode = (panel) => panel,
+  picture = TWO_BOXES,
+) {
   const iframe = document.createElement("iframe");
   document.body.appendChild(iframe);
   const doc = iframe.contentDocument!;
-  doc.body.innerHTML =
-    '<div data-composition-id="main"><div id="bg" style="z-index:1"></div><div id="title" style="z-index:2"></div></div>';
+  doc.body.innerHTML = picture;
   usePlayerStore.setState({ elements: [clip("title", 0), clip("bg", 1)] });
   const session = {
     domEditSelection: null,
@@ -84,7 +89,7 @@ async function dragBackRowToFront() {
 it("lists, selects and reorders the host's preview layers through the host's session", async () => {
   const { doc, session, root } = await mountPanel();
 
-  expect(rowLabels()).toEqual(["DiTitle", "DiBg"]);
+  expect(rowLabels()).toEqual(["Title", "Bg"]);
 
   const rows = document.querySelectorAll<HTMLElement>("[data-layer-index]");
   await act(async () => rows[0]!.click());
@@ -113,3 +118,39 @@ it("mirrors the reorder into the timeline rows through the host's move handler",
   expect(bgTrack()).not.toBe(1);
   await act(async () => root.unmount());
 });
+
+it("puts a caret only on a group's row and starts each child's icon where its parent's label starts", async () => {
+  const { root } = await mountPanel(
+    undefined,
+    '<div data-composition-id="main"><h1 id="title" style="z-index:2">Hi</h1>' +
+      '<div id="intro" data-hf-group="Intro" style="z-index:1"><img id="logo">' +
+      '<div id="inner" data-hf-group="Inner"><img id="mark"></div></div>' +
+      '<div id="wrap" style="z-index:0"><div id="box"></div></div></div>',
+  );
+  const rows = [...document.querySelectorAll<HTMLElement>("[data-layer-index]")];
+  const byLabel = (label: string) => rows.find((row) => row.textContent?.startsWith(label))!;
+  const kind = (label: string) =>
+    byLabel(label).querySelector("[data-layer-kind]")?.getAttribute("data-layer-kind");
+  expect(["Title", "Intro", "Logo", "Inner", "Mark"].map(kind)).toEqual([
+    "text",
+    "group",
+    "image",
+    "group",
+    "image",
+  ]);
+  expect([kind("Wrap"), kind("Box")]).toEqual(["group", "shape"]);
+  expect(byLabel("Wrap").firstElementChild?.getAttribute("aria-label")).toBe("Collapse children");
+  const icons = ["Title", "Intro", "Logo", "Box"].map(
+    (l) => byLabel(l).querySelector("[data-layer-kind]")!.innerHTML,
+  );
+  expect(new Set(icons).size).toBe(4);
+  for (const row of rows.filter((r) => r.title)) {
+    expect(row.querySelector<HTMLElement>("[data-layer-kind]")!.title).toContain(row.title);
+  }
+  expect(byLabel("Title").firstElementChild?.hasAttribute("data-layer-kind")).toBe(true);
+  expect(byLabel("Intro").firstElementChild?.getAttribute("aria-label")).toBe("Collapse children");
+  expect(
+    ["Title", "Intro", "Logo", "Inner", "Mark"].map((l) => byLabel(l).style.paddingLeft),
+  ).toEqual(["8px", "8px", "56px", "56px", "104px"]);
+  await act(async () => root.unmount());
+});

package/src/utils/gsapKeyframeEases.ts

@@ -50,6 +50,8 @@ function timingEase(runEase: string | undefined): ((progress: number) => number)
   return timingEases.get(runEase) ?? null;
 }
 
+export const warpsTime = (runEase: string | undefined) => timingEase(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);

package/src/utils/gsapLiveRetime.cache.test.ts

@@ -0,0 +1,39 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const reads = vi.hoisted(() => ({ shape: [] as string[] }));
+
+vi.mock("@hyperframes/parsers/gsap-parser-acorn", async (importOriginal) => {
+  const real = await importOriginal<typeof import("@hyperframes/parsers/gsap-parser-acorn")>();
+  return {
+    ...real,
+    scriptShape: (code: string, mask?: boolean) => (
+      reads.shape.push(code), real.scriptShape(code, mask)
+    ),
+  };
+});
+
+const { planLiveRetime } = await import("./gsapLiveRetime");
+
+const at = (start: number) =>
+  `var tl = gsap.timeline({ paused: true });\ntl.to("#a", { x: 1, duration: 1 }, ${start});\nwindow.__timelines["t"] = tl;`;
+
+describe("planLiveRetime", () => {
+  beforeEach(() => {
+    reads.shape.length = 0;
+  });
+
+  it("reads each script's shape once across two drags in a row", () => {
+    expect(planLiveRetime(at(0), at(1)).kind).toBe("retime");
+    expect(planLiveRetime(at(1), at(2)).kind).toBe("retime");
+
+    expect(reads.shape).toEqual([at(0), at(1), at(2)]);
+  });
+
+  it("keeps the live script's shape while saves land before the preview catches up", () => {
+    planLiveRetime(at(10), at(11));
+    planLiveRetime(at(10), at(12));
+    planLiveRetime(at(10), at(13));
+
+    expect(reads.shape).toEqual([at(10), at(11), at(12), at(13)]);
+  });
+});