@hyperframes/studio 0.8.126 → 0.8.128

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

@@ -1,12 +1,20 @@
 // @vitest-environment happy-dom
 import { gsap } from "gsap";
 import { parseGsapScriptAcorn } from "@hyperframes/parsers/gsap-parser-acorn";
-import { replaceTweenWithKeyframesInScript } from "@hyperframes/parsers/gsap-writer-acorn";
-import { afterEach, expect, it } from "vitest";
+import {
+  replaceTweenWithKeyframesInScript,
+  syncPositionHoldsBeforeKeyframes,
+  updateKeyframeInScript,
+} from "@hyperframes/parsers/gsap-writer-acorn";
+import { afterEach, expect, it, vi } from "vitest";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { usePlayerStore } from "../player/store/playerStore";
 import { findParsedTween, parsedImplicitEndValue, parsedTweenEase } from "./gsapParsedTween";
-import { planValueEdit } from "./gsapValueAtPlayhead";
+import { readRuntimeKeyframes } from "./gsapRuntimeKeyframes";
+import { GsapEditBlockedError } from "./gsapEditOutcome";
+import { toClipKeyframes } from "./gsapShared";
+import { commitValueAtPlayhead, planValueEdit } from "./gsapValueAtPlayhead";
+import { applyKeyframeAtPlayhead, type EnableKeyframesSession } from "./useEnableKeyframes";
 
 /** Runs a composition script as the preview does: a paused timeline, bound, then seeked to `at`. */
 function play(script: string, at: number) {
@@ -18,14 +26,20 @@ function play(script: string, at: number) {
 }
 
 /** Drags `#x` to `x` at `at`, writes the plan into the script, and replays the written file there. */
-function dragAndReplay(script: string, x: number, at: number) {
+function dragAndReplay(
+  script: string,
+  x: number,
+  at: number,
+  selectedPct: number | null = null,
+  { y, backfill }: { y?: number; backfill?: Record<string, number> } = {},
+) {
   const box = document.body.appendChild(document.createElement("div"));
   box.id = "x";
   const { timeline, iframe } = play(script, at);
-  usePlayerStore.setState({ currentTime: at, activeKeyframePct: null });
+  usePlayerStore.setState({ currentTime: at, activeKeyframePct: selectedPct });
   const anim = parseGsapScriptAcorn(script).animations[0]!;
   const selection = { id: "x", selector: "#x", element: box } as DomEditSelection;
-  const plan = planValueEdit(selection, anim, { x }, iframe);
+  const plan = planValueEdit(selection, anim, { x, ...(y != null && { y }) }, iframe, { backfill });
   timeline.kill();
   if (!plan.ok) return { plan };
   const written = replaceTweenWithKeyframesInScript(script, anim.id, plan.mutation)!;
@@ -54,6 +68,64 @@ it("writes a delayed linear tween so GSAP shows the new value at the playhead, n
   expect(shown).toBe(200);
 });
 
+it("reads plain array nodes where the lane puts them, though GSAP fills in step durations", () => {
+  const source = script("keyframes: [{ x: 60 }, { x: 120 }, { x: 180 }], duration: 3");
+  document.body.appendChild(document.createElement("div")).id = "x";
+  const { timeline, iframe } = play(source, 0);
+  const frame = { ...iframe, contentDocument: document } as HTMLIFrameElement;
+  const read = readRuntimeKeyframes(frame, "#x");
+  timeline.kill();
+  const parsed = parseGsapScriptAcorn(source).animations[0]!.keyframes!.keyframes;
+  expect(read?.keyframes.map((kf) => kf.percentage)).toEqual(parsed.map((kf) => kf.percentage));
+});
+
+// Three default 0.5 s steps stretched over 3 s: GSAP reaches the middle one at 2 s, where the parse
+// places it at 66.7%.
+it.each([
+  ["at the playhead, timing array steps on their own timeline", undefined],
+  ["selected in the lane, in place", 66.7],
+])("changes the middle array keyframe %s", (_, selectedPct) => {
+  const { plan, shown } = dragAndReplay(
+    script("keyframes: [{ x: 60 }, { x: 120 }, { x: 180 }], duration: 3"),
+    130,
+    2,
+    selectedPct,
+  );
+  expect(plan.ok && plan.mutation.keyframes.map((kf) => kf.properties.x)).toEqual([60, 130, 180]);
+  expect(shown).toBeCloseTo(130, 2);
+});
+
+it("keeps an array step that leaves a channel out holding it, as GSAP played it", () => {
+  const hold = "keyframes: [{ x: 60, duration: 1 }, { duration: 1 }, { x: 180, duration: 1 }]";
+  const { written } = dragAndReplay(script(hold), 97, 1);
+  const replay = play(written!, 2);
+  expect(gsap.getProperty("#x", "x")).toBe(97);
+  replay.timeline.kill();
+});
+
+it("holds a newly animated channel at rest through a step list's opening pause", () => {
+  const pauseFirst =
+    "keyframes: [{ duration: 1 }, { x: 60, duration: 1 }, { x: 180, duration: 1 }]";
+  const { written } = dragAndReplay(script(pauseFirst), 37, 2, null, { y: 11, backfill: { y: 0 } });
+  for (const [t, y] of [
+    [0.5, 0],
+    [2, 11],
+  ]) {
+    gsap.set("#x", { clearProps: "all" }); // a reloaded preview starts the tween from rest
+    const replay = play(written!, t!);
+    expect(gsap.getProperty("#x", "y")).toBeCloseTo(y!, 2);
+    replay.timeline.kill();
+  }
+});
+
+it("holds a channel at its start until the array step that first animates it", () => {
+  const late = "keyframes: [{ x: 60 }, { x: 120, y: 50 }], duration: 2";
+  const { written } = dragAndReplay(script(late), 200, 2);
+  const replay = play(written!, 1);
+  expect(gsap.getProperty("#x", "y")).toBe(0);
+  replay.timeline.kill();
+});
+
 it("keeps GSAP's default ease, by name, for a tween that authors none", () => {
   const { plan } = dragAndReplay(script("duration: 1, x: 100"), 60, 0.5);
   expect(plan.ok && plan.mutation.easeEach).toBe("power1.out");
@@ -177,3 +249,123 @@ it("writes an edit into a looping tween and keeps its repeat and yoyo, as main d
   expect(plan.ok).toBe(true);
   expect(written).toMatch(/repeat: 1[\s\S]*yoyo: true/);
 });
+
+it("keeps a delayed step list where GSAP plays it, before and after a keyframe edit", () => {
+  const box = Object.assign(document.body.appendChild(document.createElement("div")), { id: "x" });
+  const stepList = `var tl = gsap.timeline({ paused: true });\ntl.to("#x", { keyframes: [{ x: 60 }, { x: 120 }], ease: "none" }, 1);\nwindow.__timelines["t"] = tl;`;
+  const id = parseGsapScriptAcorn(stepList).animations[0]!.id;
+  const edited = syncPositionHoldsBeforeKeyframes(
+    updateKeyframeInScript(stepList, id, 100, { x: 130 }),
+  );
+  const xAt = (file: string, at: number) => {
+    const { timeline } = play(file, at);
+    const x = gsap.getProperty(box, "x");
+    timeline.kill();
+    gsap.set(box, { clearProps: "all" });
+    return x;
+  };
+  for (const file of [stepList, edited]) {
+    expect([xAt(file, 0.5), xAt(file, 1.25)]).toEqual([0, 30]);
+    const tween = parseGsapScriptAcorn(file).animations.find((a) => a.keyframes)!;
+    for (const { percentage, properties } of tween.keyframes!.keyframes) {
+      expect(xAt(file, 1 + percentage / 100)).toBeCloseTo(Number(properties.x), 3);
+    }
+  }
+});
+
+it.each([
+  [
+    "an outer power2.in",
+    `keyframes: { "0%": { x: 0 }, "50%": { x: 60 }, "100%": { x: 120 } }, duration: 1, ease: "power2.in"`,
+  ],
+  ["no duration", `keyframes: [{ x: 60 }, { x: 120 }], ease: "none"`],
+])("draws each diamond of a keyframed tween with %s where GSAP shows its value", (_, vars) => {
+  const box = Object.assign(document.body.appendChild(document.createElement("div")), { id: "x" });
+  const file = `var tl = gsap.timeline({ paused: true });\ntl.to("#x", { ${vars} }, 1);\nwindow.__timelines["t"] = tl;`;
+  const tween = parseGsapScriptAcornAnimation(file);
+  for (const row of toClipKeyframes(tween.keyframes!.keyframes, tween, 0, 4)) {
+    const { timeline } = play(file, (row.percentage / 100) * 4);
+    expect(gsap.getProperty(box, "x")).toBeCloseTo(Number(row.properties.x), 1);
+    timeline.kill();
+    gsap.set(box, { clearProps: "all" });
+  }
+});
+
+function parseGsapScriptAcornAnimation(file: string) {
+  return parseGsapScriptAcorn(file).animations.find((a) => a.keyframes)!;
+}
+
+it("keeps a step list's steps where GSAP plays them when an outer duration stretches it", () => {
+  const { plan, written } = dragAndReplay(
+    script(`keyframes: [{ x: 100 }, { x: 200 }], duration: 2, ease: "none"`),
+    70,
+    0.5,
+  );
+  expect(plan.ok).toBe(true);
+  const box = document.getElementById("x")!;
+  const xAt = (at: number) => {
+    const { timeline } = play(written!, at);
+    const x = gsap.getProperty(box, "x");
+    timeline.kill();
+    return x;
+  };
+  expect([xAt(0.5), xAt(1), xAt(2)]).toEqual([70, 100, 200]);
+});
+
+it("adds a keyframe where GSAP plays a tween whose duration is an expression, and never rewrites the expression", async () => {
+  const src = `var dur = () => 2;\nvar tl = gsap.timeline({ paused: true });\ntl.to("#x", { keyframes: { "0%": { x: 0 }, "100%": { x: 300 } }, duration: dur() }, 1);\nwindow.__timelines["t"] = tl;`;
+  const box = document.body.appendChild(document.createElement("div"));
+  box.id = "x";
+  const { timeline, iframe } = play(src, 2);
+  const anim = parseGsapScriptAcorn(src).animations[0]!;
+  const writes: Array<[string, unknown]> = [];
+  const session = {
+    commitMutation: async (mutation: unknown) => void writes.push(["replace", mutation]),
+    handleGsapRemoveKeyframe: () => void writes.push(["remove", null]),
+    handleGsapAddKeyframeBatch: async (_id: string, pct: number) => void writes.push(["add", pct]),
+  } as unknown as EnableKeyframesSession;
+  const selection = { id: "x", selector: "#x", element: box } as DomEditSelection;
+
+  await applyKeyframeAtPlayhead(session, selection, anim, 2, iframe);
+  await applyKeyframeAtPlayhead(session, selection, anim, 3.5, iframe);
+  timeline.kill();
+
+  expect(anim.durationUnresolved).toBe(true);
+  expect(writes).toEqual([["add", 50]]);
+});
+
+it("leaves a step list with a runBackwards step to the runtime: a rewrite would play it differently", async () => {
+  const flagged = script(
+    "keyframes: [{ x: 60, duration: 1, runBackwards: true }, { x: 180, duration: 1 }], ease: 'none'",
+  );
+  const box = Object.assign(document.body.appendChild(document.createElement("div")), { id: "x" });
+  const xAt = (src: string, t: number) => {
+    gsap.set(box, { clearProps: "all" });
+    const replay = play(src, t);
+    const x = gsap.getProperty(box, "x");
+    replay.timeline.kill();
+    return x;
+  };
+  // The flag plays the first step from 60 back to the start, so a list without it is another animation.
+  expect(xAt(flagged, 0.25)).not.toBe(xAt(flagged.replace(", runBackwards: true", ""), 0.25));
+  const { timeline, iframe } = play(flagged, 1.5);
+  usePlayerStore.setState({ currentTime: 1.5, activeKeyframePct: null });
+  const anim = parseGsapScriptAcorn(flagged).animations[0]!;
+  const commitMutation = vi.fn(async () => {});
+  const selection = { id: "x", selector: "#x", element: box } as DomEditSelection;
+
+  const edit = commitValueAtPlayhead(
+    selection,
+    anim,
+    { x: 90 },
+    iframe,
+    { commitMutation },
+    {
+      label: "Move",
+    },
+  );
+
+  await expect(edit).rejects.toBeInstanceOf(GsapEditBlockedError);
+  timeline.kill();
+  expect(commitMutation).not.toHaveBeenCalled();
+});

package/src/hooks/gsapValueAtPlayhead.test.ts

@@ -3,8 +3,8 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { usePlayerStore } from "../player/store/playerStore";
-import { GSAP_EDIT_BLOCK_COPY } from "./gsapEditOutcome";
-import { liveTween, previewWith, tween } from "./gsapParsedTween.test-helpers";
+import { GSAP_EDIT_BLOCK_COPY, GsapEditBlockedError } from "./gsapEditOutcome";
+import { boxSteps, liveTween, previewWith, tween } from "./gsapParsedTween.test-helpers";
 import { tryGsapResizeIntercept } from "./gsapResizeIntercept";
 import { tryGsapDragIntercept, tryGsapRotationIntercept } from "./gsapRuntimeBridge";
 import { planValueAtPlayhead, planValueEdit, type PlayheadEdit } from "./gsapValueAtPlayhead";
@@ -166,31 +166,12 @@ describe("a move on a GSAP-animated layer, at the playhead", () => {
   });
 
   it("adds a keyframe between two steps of a keyframes array", async () => {
-    const keys = tween({
-      id: "#box-to-0-position",
-      method: "to",
-      properties: {},
-      resolvedStart: 0,
-      duration: 3,
-      keyframes: {
-        format: "object-array",
-        keyframes: [
-          // The parse rounds the step to 66.7%; GSAP times it at 2 s of 3.
-          { percentage: 66.7, properties: { x: 60 } },
-          { percentage: 100, properties: { x: 120 } },
-        ],
-      },
-    });
-    const steps = [
-      { startTime: () => 0, duration: () => 2 },
-      { startTime: () => 2, duration: () => 1 },
-    ];
-    const live = liveTween(
-      el,
-      { start: 0, duration: 3, vars: { keyframes: [] } },
-      { parts: steps },
-    );
-    const { mutations } = await drag([keys], [live], { time: 1, base: [30, 0], dx: 10 });
+    // The parse rounds the first step to 66.7%; GSAP times it at 2 s of 3.
+    const { keys, live } = boxSteps([
+      [2, { x: 60 }],
+      [1, { x: 120 }],
+    ]);
+    const { mutations } = await drag([keys], [live(el)], { time: 1, base: [30, 0], dx: 10 });
     expect(mutations.map((m) => m.type)).toEqual(["replace-with-keyframes"]);
     // An array step eases linearly unless it says otherwise; percentage keyframes would not.
     expect(mutations[0].keyframes).toEqual([
@@ -527,6 +508,30 @@ describe("planValueAtPlayhead", () => {
     ]);
   });
 
+  it("refuses a step that leaves a channel out when GSAP's start for it is unknown", () => {
+    const anim = kf([
+      { percentage: 50, properties: {} },
+      { percentage: 100, properties: { x: 20 } },
+    ]);
+    const steps = { ...anim, keyframes: { ...anim.keyframes!, format: "object-array" as const } };
+    expect(plan({ anim: steps, at: { percentage: 100 }, values: { x: 5 } })).toEqual({
+      ok: false,
+      reason: "implicit-end-unknown",
+    });
+  });
+
+  it("changes the nearer of two keyframes under 1% apart", () => {
+    const anim = kf([
+      { percentage: 50, properties: { x: 100 } },
+      { percentage: 50.5, properties: { x: 100 } },
+      { percentage: 100, properties: { x: 100 } },
+    ]);
+    const result = plan({ anim, at: { percentage: 50.5 }, values: { x: 150 } });
+    expect(result.ok && result.mutation.keyframes.map((k) => k.properties.x)).toEqual([
+      100, 150, 100,
+    ]);
+  });
+
   describe("keyframes eased as a whole", () => {
     const eased = {
       ...kf([
@@ -563,6 +568,42 @@ describe("planValueAtPlayhead", () => {
       });
     });
 
+    it("refuses an inner node of a motionPath tween, which GSAP runs power1.out", () => {
+      const path = kf([
+        { percentage: 0, properties: { x: 0 } },
+        { percentage: 50, properties: { x: 100 } },
+        { percentage: 100, properties: { x: 300 } },
+      ]);
+      const anim = { ...path, keyframes: { ...path.keyframes!, fromMotionPath: true as const } };
+      expect(plan({ anim, at: { time: 2 }, values: { x: 5 } })).toEqual({
+        ok: false,
+        reason: "eased-keyframes",
+      });
+    });
+
+    it("changes an inner keyframe picked by its percentage, which the ease does not move", () => {
+      const anim = {
+        ...kf([
+          { percentage: 0, properties: { x: 0 } },
+          { percentage: 50, properties: { x: 100 } },
+          { percentage: 100, properties: { x: 300 } },
+        ]),
+        ease: "power2.out",
+      };
+      const result = plan({ anim, at: { percentage: 50 }, values: { x: 5 } });
+      expect(result.ok && result.mutation.keyframes.map((k) => k.properties.x)).toEqual([
+        0, 5, 300,
+      ]);
+      expect(result.ok && result.mutation.ease).toBe("power2.out");
+    });
+
+    it("refuses to add a keyframe at a percentage, whose time the ease would move", () => {
+      expect(plan({ anim: eased, at: { percentage: 40 }, values: { x: 5 } })).toEqual({
+        ok: false,
+        reason: "eased-keyframes",
+      });
+    });
+
     it("refuses to add a keyframe, whose time the ease would move", () => {
       expect(plan({ anim: eased, at: { time: 2 }, values: { x: 5 } })).toEqual({
         ok: false,
@@ -593,3 +634,77 @@ it("refuses a tween whose selector also animates a sibling, before it plans anyt
   });
   sibling.remove();
 });
+
+describe("a keyframes array the percentage rewrite would change", () => {
+  const steps = (
+    properties: Array<Record<string, number | string>>,
+    edit: Partial<PlayheadEdit> = {},
+  ) =>
+    planValueAtPlayhead({
+      anim: tween({
+        method: "to",
+        properties: {},
+        resolvedStart: 0,
+        duration: 3,
+        keyframes: {
+          format: "object-array",
+          keyframes: properties.map((p, i) => ({ percentage: ((i + 1) / 3) * 100, properties: p })),
+        },
+      }),
+      at: { percentage: 100 },
+      values: { x: 50 },
+      implicitEndValue: () => 0,
+      ...edit,
+    });
+
+  it.each([
+    ["a step delay", { x: 100, delay: 0.5 }, "array-step-delay", "its own delay"],
+    ["a step callback", { x: 100, onComplete: "__raw:done" }, "array-step-callback", "runs code"],
+    [
+      "an unlisted callback",
+      { x: 100, onInterrupt: "__raw:stop" },
+      "array-step-callback",
+      "runs code",
+    ],
+    [
+      "a step repeat",
+      { x: 100, repeat: 2 },
+      "array-step-config",
+      "tween setting (like repeat or stagger)",
+    ],
+    ["a computed value", { x: "__raw:offset()" }, "array-step-computed", "comes from code"],
+    ["a relative value", { x: "-=40" }, "array-step-relative", '"+=40"'],
+    ["a random value", { x: "random(0, 300)" }, "array-step-random", "random()"],
+    [
+      "a random value inside a string",
+      { filter: "blur(random(1, 9)px)" },
+      "array-step-random",
+      "random()",
+    ],
+  ] as const)("refuses %s and says so", (_, step, reason, says) => {
+    expect(steps([{ x: 60 }, step, { x: 180 }])).toEqual({ ok: false, reason });
+    const message = new GsapEditBlockedError("keyframes-uneditable", reason).message;
+    expect(message).toContain(says);
+    expect(message).toContain("Code tab");
+  });
+
+  it("rewrites absolute values, colours included", () => {
+    const result = steps([{ x: 60, color: "#fff" }, { x: 120, color: "rgb(0, 0, 0)" }, { x: 180 }]);
+    expect(result.ok && result.mutation.keyframes.map((k) => k.properties.x)).toEqual([
+      60, 120, 50,
+    ]);
+  });
+
+  it("holds a pause step at the dropped value of a channel the drop starts animating", () => {
+    const result = steps([{ x: 60 }, {}, { x: 180 }], {
+      at: { percentage: 100 / 3 },
+      values: { x: 37, y: 11 },
+      backfill: { y: 0 },
+    });
+    expect(result.ok && result.mutation.keyframes.map((k) => k.properties)).toEqual([
+      { x: 37, y: 11 },
+      { x: 37, y: 11 },
+      { x: 180, y: 0 },
+    ]);
+  });
+});

package/src/hooks/gsapValueAtPlayhead.ts

@@ -2,14 +2,18 @@ import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { usePlayerStore } from "../player/store/playerStore";
 import { resolveTweenDuration, resolveTweenStart } from "../utils/globalTimeCompiler";
+import { ARRAY_STEP_EASE, PERCENTAGE_SEGMENT_EASE, runEaseOf } from "../utils/gsapKeyframeEases";
 import { roundTo3 } from "../utils/rounding";
 import {
   materializeIfDynamic,
+  stepListBlock,
   parkPlayheadOnKeyframe,
   type GsapDragCommitCallbacks,
 } from "./gsapDragCommit";
 import type { GsapEditOutcome, PlayheadEditRefusal } from "./gsapEditOutcome";
 import {
+  exactKeyframePct,
+  nearestKeyframeIndex,
   findParsedTween,
   parsedImplicitEndValue,
   parsedTweenEase,
@@ -63,10 +67,8 @@ export type PlayheadEditPlan =
     }
   | { ok: false; reason: PlayheadEditRefusal };
 
-// GSAP 3.14 defaults: a percentage keyframe eases its segment power1.inOut; an array step is linear.
-const PERCENTAGE_SEGMENT_EASE = "power1.inOut";
-const ARRAY_STEP_EASE = "none";
 const roundPct = (pct: number) => Math.round(pct * 1000) / 1000;
+
 const isLinear = (ease: string | undefined) => !ease || ease === "none" || ease === "linear";
 
 interface Normalized {
@@ -86,8 +88,10 @@ function normalize(edit: PlayheadEdit): Normalized | { reason: PlayheadEditRefus
   if (data) {
     if (data.format === "simple-array") return { reason: "simple-array-keyframes" };
     const arrayStep = data.format === "object-array";
+    const blocked = stepListBlock(anim);
+    if (blocked) return { reason: blocked };
     return {
-      runEase: data.ease ?? anim.ease,
+      runEase: runEaseOf(anim),
       keyframes: data.keyframes.map((kf) => ({
         ...kf,
         properties: { ...kf.properties },
@@ -129,7 +133,7 @@ function valueAt(keyframes: Keyframe[], prop: string, side: "first" | "last") {
 }
 
 const keyframeAt = (keyframes: Keyframe[], percentage: number) =>
-  keyframes.find((kf) => Math.abs(kf.percentage - percentage) <= KEYFRAME_PCT_MATCH);
+  keyframes[nearestKeyframeIndex(keyframes, percentage)];
 
 function upsert(keyframes: Keyframe[], percentage: number, properties: Props, ease?: string) {
   const hit = keyframeAt(keyframes, percentage);
@@ -164,6 +168,27 @@ function heldEnds(
   return held;
 }
 
+/** An array step without a channel holds it, where a percentage keyframe would tween through it. */
+function holdOmittedChannels(
+  steps: Keyframe[],
+  implicit: ImplicitEndValue,
+  backfilled: Record<string, number>,
+): boolean {
+  const props = new Set(steps.flatMap((kf) => Object.keys(kf.properties)));
+  for (const prop of props) {
+    let held: number | string | null | undefined;
+    for (const kf of steps) {
+      if (kf.properties[prop] != null) held = kf.properties[prop];
+      else {
+        held ??= backfilled[prop] ?? implicit(prop, "start");
+        if (held == null) return false;
+        kf.properties[prop] = held;
+      }
+    }
+  }
+  return true;
+}
+
 /** On a keyframe, change it; between two, add one at the playhead; outside the tween, add one there
  *  and keep the authored ends. Values come from the file's tween or GSAP's parse, never the DOM. */
 // fallow-ignore-next-line complexity
@@ -176,6 +201,7 @@ export function planValueAtPlayhead(edit: PlayheadEdit): PlayheadEditPlan {
   if ("reason" in norm) return refuse(norm.reason);
   const keyframes = norm.keyframes;
   const authored = keyframes.length;
+  const steps = anim.keyframes?.format === "object-array" ? [...keyframes] : [];
   // GSAP runs `scale` beside scaleX/scaleY and the longhands win, so a per-axis edit splits it.
   if ("scaleX" in values || "scaleY" in values) {
     for (const kf of keyframes) {
@@ -184,11 +210,14 @@ export function planValueAtPlayhead(edit: PlayheadEdit): PlayheadEditPlan {
     }
   }
   const backfilled: Record<string, number> = {};
+  const pauseStepsHoldThePrevious = new Set(
+    steps.filter((kf) => Object.keys(kf.properties).length === 0),
+  );
   for (const [prop, value] of Object.entries(edit.backfill ?? {})) {
     if (!(prop in values) || keyframes.some((kf) => kf.properties[prop] != null)) continue;
     if (edit.holdFromStart && !keyframes.some((kf) => kf.percentage <= 0))
       keyframes.unshift({ percentage: 0, properties: {} });
-    for (const kf of keyframes) kf.properties[prop] = value;
+    for (const kf of keyframes) if (!pauseStepsHoldThePrevious.has(kf)) kf.properties[prop] = value;
     backfilled[prop] = value;
   }
   if (Object.keys(values).some((prop) => !keyframes.some((kf) => kf.properties[prop] != null)))
@@ -204,7 +233,9 @@ export function planValueAtPlayhead(edit: PlayheadEdit): PlayheadEditPlan {
   if (pct >= -KEYFRAME_PCT_MATCH && pct <= 100 + KEYFRAME_PCT_MATCH) {
     const at = Math.min(100, Math.max(0, pct));
     const hit = keyframeAt(keyframes, at);
-    if (eased && hit?.percentage !== 0 && hit?.percentage !== 100) return refuse("eased-keyframes");
+    // The ease moves where a time lands, not a keyframe's own percentage or the tween's ends.
+    const onKeyframe = "percentage" in edit.at || hit?.percentage === 0 || hit?.percentage === 100;
+    if (eased && !(hit && onKeyframe)) return refuse("eased-keyframes");
     const next = [...keyframes]
       .sort((a, b) => a.percentage - b.percentage)
       .find((kf) => kf.percentage > at + KEYFRAME_PCT_MATCH);
@@ -231,6 +262,8 @@ export function planValueAtPlayhead(edit: PlayheadEdit): PlayheadEditPlan {
     upsert(keyframes, before ? 0 : 100, { ...held, ...values }, before ? undefined : linear);
   }
 
+  if (!holdOmittedChannels(steps, edit.implicitEndValue, backfilled))
+    return refuse("implicit-end-unknown");
   keyframes.sort((a, b) => a.percentage - b.percentage);
   return {
     ok: true,
@@ -263,7 +296,10 @@ export function planValueEdit(
   const timed = withExactStepTimes(anim, tween);
   return planValueAtPlayhead({
     anim: withLiveTiming(timed, tween),
-    at: activeKeyframePct != null ? { percentage: activeKeyframePct } : { time: currentTime },
+    at:
+      activeKeyframePct != null
+        ? { percentage: exactKeyframePct(anim, tween, activeKeyframePct) }
+        : { time: currentTime },
     values,
     backfill,
     holdFromStart,
@@ -286,6 +322,9 @@ export async function commitValueAtPlayhead(
 ): Promise<GsapEditOutcome> {
   await materializeIfDynamic(anim, iframe, callbacks.commitMutation, selection);
   const { activeKeyframePct, setActiveKeyframePct } = usePlayerStore.getState();
+  const tween = findParsedTween(iframe, selection.element, anim);
+  const parkAt =
+    activeKeyframePct == null ? null : exactKeyframePct(anim, tween, activeKeyframePct);
   const plan = planValueEdit(selection, anim, values, iframe, options);
   if (!plan.ok) return { status: "blocked", reason: "keyframes-uneditable", detail: plan.reason };
   await callbacks.commitMutation(selection, plan.mutation, {
@@ -294,9 +333,9 @@ export async function commitValueAtPlayhead(
     beforeReload: options.beforeReload,
     ...(plan.added && { keyframeAction: "add" as const }),
   });
-  if (activeKeyframePct != null) {
+  if (parkAt != null) {
     setActiveKeyframePct(null);
-    parkPlayheadOnKeyframe(anim, activeKeyframePct);
+    parkPlayheadOnKeyframe(anim, parkAt);
   }
   return { status: "persisted" };
 }

package/src/hooks/gsapWholePropertyOffsetCommit.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it } from "vitest";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
-import type { GsapDragCommitCallbacks } from "./gsapDragCommit";
+import { commitWholePathOffset, type GsapDragCommitCallbacks } from "./gsapDragCommit";
 import { commitWholePropertyOffset } from "./gsapWholePropertyOffsetCommit";
 
 // Regression (#1808): with auto-keyframe recording off, a manual edit on an
@@ -203,3 +203,74 @@ describe("commitWholePropertyOffset", () => {
     expect(mutations[0]).toMatchObject({ easeEach: "none" });
   });
 });
+
+it.each([
+  [{ rotation: "+=40" }, "array-step-relative"],
+  [{ rotation: 40, onComplete: "__raw:done" }, "array-step-callback"],
+  [{ rotation: "random(0, 90)" }, "array-step-random"],
+])("refuses to rewrite a step list holding %o and writes nothing", async (last, detail) => {
+  const steps = [{ rotation: 10 }, last].map((properties, i) => ({
+    percentage: (i + 1) * 50,
+    properties,
+  }));
+  const anim = {
+    id: "#box-steps",
+    targetSelector: "#box",
+    method: "to",
+    resolvedStart: 0,
+    duration: 2,
+    keyframes: { format: "object-array", keyframes: steps },
+  } as unknown as GsapAnimation;
+  const { mutations, callbacks } = recordingCallbacks();
+  const rotate = commitWholePropertyOffset(
+    selection(),
+    anim,
+    { rotation: 50 },
+    100,
+    null,
+    callbacks,
+    "Rotate",
+  );
+  await expect(rotate).rejects.toMatchObject({ reason: "keyframes-uneditable", detail });
+  expect(mutations).toEqual([]);
+});
+
+it("refuses to shift a layer's step list whose step has its own delay, writing nothing", async () => {
+  // No drag baseline on the element: the move starts from a zero offset.
+  const el = {
+    style: { getPropertyValue: () => "", setProperty: () => {} },
+    getAttribute: () => null,
+    removeAttribute: () => {},
+    getBoundingClientRect: () => ({ top: 0, left: 0 }),
+  };
+  const anim = {
+    id: "#box-steps",
+    targetSelector: "#box",
+    method: "to",
+    resolvedStart: 0,
+    duration: 2,
+    keyframes: {
+      format: "object-array",
+      keyframes: [
+        { percentage: 50, properties: { x: 100, delay: 0.5 } },
+        { percentage: 100, properties: { x: 200 } },
+      ],
+    },
+  } as unknown as GsapAnimation;
+  const { mutations, callbacks } = recordingCallbacks();
+  const sel = { ...selection(), element: el } as DomEditSelection;
+  const move = commitWholePathOffset(
+    sel,
+    anim,
+    { x: 40, y: 0 },
+    { x: 0, y: 0 },
+    null,
+    "#box",
+    callbacks,
+  );
+  await expect(move).rejects.toMatchObject({
+    reason: "keyframes-uneditable",
+    detail: "array-step-delay",
+  });
+  expect(mutations).toEqual([]);
+});