@hyperframes/studio 0.8.126 → 0.8.127

package/src/hooks/gsapParsedTween.ts

@@ -1,6 +1,7 @@
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import { elementTargets } from "../utils/elementGsap";
 import { resolveTweenStart } from "../utils/globalTimeCompiler";
+import { KEYFRAME_PCT_MATCH } from "./gsapShared";
 import type { ImplicitEndValue } from "./gsapValueAtPlayhead";
 import type { ReadTween } from "./gsapRuntimeKeyframes";
 
@@ -23,7 +24,7 @@ interface ParsedTween {
     seek?: (time: number, suppressEvents?: boolean) => unknown;
     getChildren?: (nested?: boolean, tweens?: boolean, timelines?: boolean) => ParsedTween[];
   };
-  timeline?: { getChildren?: () => ParsedTween[] };
+  timeline?: { getChildren?: () => ParsedTween[]; duration?: () => number };
   targets?: () => unknown[];
   startTime?: () => number;
   duration?: () => number;
@@ -246,7 +247,7 @@ 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?.duration?.() ?? 0;
+  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);
@@ -257,3 +258,23 @@ export function withExactStepTimes(anim: GsapAnimation, tween: ParsedTween | nul
   }));
   return { ...anim, keyframes: { ...data, keyframes } };
 }
+
+/** The keyframe nearest `pct` within {@link KEYFRAME_PCT_MATCH}, or -1: two steps can sit under 1% apart. */
+export function nearestKeyframeIndex(keyframes: { percentage: number }[], pct: number): number {
+  let best = -1;
+  keyframes.forEach((kf, i) => {
+    const off = Math.abs(kf.percentage - pct);
+    if (
+      off <= KEYFRAME_PCT_MATCH &&
+      (best < 0 || off < Math.abs(keyframes[best]!.percentage - pct))
+    )
+      best = i;
+  });
+  return best;
+}
+
+export function exactKeyframePct(anim: GsapAnimation, tween: ParsedTween | null, pct: number) {
+  const authored = anim.keyframes?.keyframes ?? [];
+  const i = nearestKeyframeIndex(authored, pct);
+  return withExactStepTimes(anim, tween).keyframes?.keyframes[i]?.percentage ?? pct;
+}

package/src/hooks/gsapRuntimeBridge.ts

@@ -23,6 +23,7 @@ import {
   computeCurrentPercentage,
   findExistingPositionWrite,
   findRotationSetAnimation,
+  stepListBlock,
 } from "./gsapDragCommit";
 import { commitWholePropertyOffset } from "./gsapWholePropertyOffsetCommit";
 import { isGestureTransactionCommit } from "./gestureTransaction";
@@ -218,7 +219,12 @@ async function planDrag(
   if (!posAnim) {
     return { status: "blocked", reason: "source-uneditable", detail: "no-position-tween" };
   }
-  if (route === "whole-path") return { status: "persisted" };
+  if (route === "whole-path") {
+    const step = stepListBlock(posAnim);
+    return step
+      ? { status: "blocked", reason: "keyframes-uneditable", detail: step }
+      : { status: "persisted" };
+  }
   const gsapPos = readGsapPositionFromIframe(iframe, selector) ?? { x: 0, y: 0 };
   return gsapPositionFromDragOutcome(selection, posAnim, offset, gsapPos, iframe);
 }

package/src/hooks/gsapRuntimeKeyframes.ts

@@ -43,7 +43,7 @@ export interface RuntimeTimeline {
   to?: (targets: Element[], vars: GsapVars, position?: number) => RuntimeTween;
 }
 
-type Pct = { percentage: number; properties: Record<string, number | string> };
+type Pct = { percentage: number; properties: Record<string, number | string>; step?: number };
 export type ReadTween = {
   keyframes: Pct[];
   easeEach?: string;

package/src/hooks/gsapShared.test.ts

@@ -64,6 +64,7 @@ describe("parsePercentageKeyframes", () => {
       { x: 1480, y: 160 },
     ] as unknown as Record<string, unknown>);
     expect(out?.keyframes.map((k) => k.percentage)).toEqual([0, 33.3, 66.7, 100]);
+    expect(out?.keyframes.map((k) => k.step)).toEqual([0, 1, 2, 3]);
     expect(out?.keyframes[1]!.properties).toEqual({ x: 520, y: 120 });
   });
 

package/src/hooks/gsapShared.ts

@@ -399,7 +399,11 @@ export function queryIframeElement(
 // ── Keyframe parsing ──────────────────────────────────────────────────────────
 
 export interface ParsedPercentageKeyframes {
-  keyframes: Array<{ percentage: number; properties: Record<string, number | string> }>;
+  keyframes: Array<{
+    percentage: number;
+    properties: Record<string, number | string>;
+    step?: number;
+  }>;
   easeEach?: string;
 }
 
@@ -442,7 +446,7 @@ export function parsePercentageKeyframes(
       if (!entry || typeof entry !== "object") return;
       const percentage = steps.length > 1 ? Math.round((i / (steps.length - 1)) * 1000) / 10 : 0;
       const properties = collectAnimatableKeyframeProperties(entry);
-      if (Object.keys(properties).length > 0) keyframes.push({ percentage, properties });
+      if (Object.keys(properties).length > 0) keyframes.push({ percentage, properties, step: i });
     });
     return keyframes.length > 0 ? { keyframes } : null;
   }

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

@@ -2,11 +2,13 @@
 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 { 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 { commitValueAtPlayhead, planValueEdit } from "./gsapValueAtPlayhead";
 
 /** Runs a composition script as the preview does: a paused timeline, bound, then seeked to `at`. */
 function play(script: string, at: number) {
@@ -18,14 +20,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 +62,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 50%.
+it.each([
+  ["at the playhead, timing array steps on their own timeline", undefined],
+  ["selected in the lane, in place", 50],
+])("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 +243,39 @@ 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("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,29 @@ describe("planValueAtPlayhead", () => {
       });
     });
 
+    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 +621,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

@@ -5,11 +5,14 @@ import { resolveTweenDuration, resolveTweenStart } from "../utils/globalTimeComp
 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,
@@ -86,6 +89,8 @@ 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,
       keyframes: data.keyframes.map((kf) => ({
@@ -129,7 +134,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 +169,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 +202,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 +211,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 +234,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 +263,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 +297,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 +323,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 +334,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([]);
+});