@hyperframes/studio 0.8.125 → 0.8.127

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

@@ -0,0 +1,48 @@
+// @vitest-environment happy-dom
+import { gsap } from "gsap";
+import { expect, it } from "vitest";
+import { readRuntimeKeyframes } from "./gsapRuntimeKeyframes";
+
+/** The edit bench's `keys` layer: GSAP starts it at x 40, 260 wide, and plays it to 1 s. */
+function read(keyframes: string) {
+  const box = Object.assign(document.body.appendChild(document.createElement("div")), { id: "x" });
+  box.style.width = "260px";
+  gsap.set(box, { x: 40 });
+  const win = { __timelines: {} as Record<string, gsap.core.Timeline> };
+  new Function(
+    "gsap",
+    "window",
+    `var tl = gsap.timeline({ paused: true });
+tl.to("#x", { keyframes: ${keyframes} }, 0);
+window.__timelines["t"] = tl;`,
+  )(gsap, win);
+  const timeline = win.__timelines.t!;
+  timeline.progress(0.0001, true).seek(1);
+  const iframe = { contentWindow: { ...win, gsap }, contentDocument: document };
+  const got = readRuntimeKeyframes(iframe as unknown as HTMLIFrameElement, "#x");
+  timeline.kill();
+  box.remove();
+  return got;
+}
+
+it("reads where GSAP started a step list whose first keyframe comes later", () => {
+  const got = read(
+    `[{ x: 60, width: 280, duration: 2, ease: "none" }, { x: 120, width: 320, duration: 1, ease: "none" }]`,
+  );
+  expect(got?.start).toEqual({ x: 40, width: 260 });
+});
+
+it.each([
+  [`{ "50%": { x: 60, y: 20 }, "100%": { x: 120, y: 40 } }, duration: 2`, { x: 40, y: 0 }],
+  [
+    `{ "50%": { x: 60, width: 280 }, "100%": { x: 120, width: 320 } }, duration: 2`,
+    { x: 40, width: 260 },
+  ],
+])("reads every channel's start for a percentage list past 0%: %s", (keyframes, start) => {
+  expect(read(keyframes)?.start).toEqual(start);
+});
+
+it("reads no start for keyframes that begin at 0%, or a step list that begins where GSAP started", () => {
+  expect(read(`{ "0%": { x: 10 }, "100%": { x: 120 } }, duration: 3`)?.start).toBeUndefined();
+  expect(read(`[{ x: 40, duration: 0 }, { x: 120, duration: 1 }]`)?.start).toBeUndefined();
+});

package/src/hooks/gsapRuntimeKeyframes.ts

@@ -11,6 +11,7 @@
 import { buildArcPath, type ArcPathConfig } from "@hyperframes/core/gsap-parser-acorn";
 import { parsePercentageKeyframes, toAbsoluteTime } from "./gsapShared";
 import { roundTo3 } from "../utils/rounding";
+import { withParsedStart } from "./gsapParsedTween";
 import { BOX_SIZE_STYLE_PROPS } from "../components/editor/manualEditsDomPatches";
 import { gsapRendersTransform } from "../components/editor/gsapAnimatesProperty";
 
@@ -42,8 +43,14 @@ export interface RuntimeTimeline {
   to?: (targets: Element[], vars: GsapVars, position?: number) => RuntimeTween;
 }
 
-type Pct = { percentage: number; properties: Record<string, number | string> };
-export type ReadTween = { keyframes: Pct[]; easeEach?: string; arcPath?: ArcPathConfig };
+type Pct = { percentage: number; properties: Record<string, number | string>; step?: number };
+export type ReadTween = {
+  keyframes: Pct[];
+  easeEach?: string;
+  arcPath?: ArcPathConfig;
+  /** GSAP's start values when the first keyframe is after 0%. */
+  start?: Record<string, number>;
+};
 
 export interface RuntimeKeyframeEntry {
   keyframes: Pct[];
@@ -365,11 +372,11 @@ export function readRuntimeKeyframes(
       const read = readTween(tween.vars);
       if (!read) continue;
       if (requireChannels && !readCarriesChannel(read, requireChannels)) continue;
-      if (firstRead === null) firstRead = read;
+      if (firstRead === null) firstRead = withParsedStart(read, tween);
       // Prefer the tween whose [start, start+dur] contains the playhead.
       if (now != null) {
         const start = typeof tween.startTime === "function" ? tween.startTime() : 0;
-        if (now >= start - 1e-3 && now <= start + dur + 1e-3) return read;
+        if (now >= start - 1e-3 && now <= start + dur + 1e-3) return withParsedStart(read, tween);
       }
     }
   }

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

@@ -3,6 +3,7 @@
  * Centralises duplicated interfaces, constants, and small utilities
  * to reduce drift risk.
  */
+import { isHtmlElement } from "@hyperframes/core/runtime/dom-realm";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import {
@@ -223,7 +224,7 @@ function structuralSelector(element: Element): string | null {
   const parts: string[] = [];
   for (let node: Element | null = element; node; node = node.parentElement) {
     if (node !== element) {
-      const id = node instanceof HTMLElement ? node.id : "";
+      const id = isHtmlElement(node) ? node.id : "";
       const hfId = node.getAttribute("data-hf-id");
       if (id) {
         parts.unshift(idSelector(id));
@@ -398,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;
 }
 
@@ -441,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/gsapShared.writeTarget.test.ts

@@ -110,6 +110,16 @@ describe("writeTargetSelector", () => {
     expect(writeTargetSelector(selection)).toBe("#scene > div:nth-child(2)");
   });
 
+  it("anchors on an ancestor's id in the preview, whichever window built its nodes", () => {
+    const frame = document.body.appendChild(document.createElement("iframe"));
+    const doc = frame.contentDocument!;
+    doc.body.innerHTML = `<div id="scene"><div></div><div></div></div>`;
+    const el = doc.querySelectorAll<HTMLElement>("#scene > div")[1]!;
+    const selection = { ...stableSelectionFor(el), selector: "div[unclosed" } as DomEditSelection;
+
+    expect(writeTargetSelector(selection)).toBe("#scene > div:nth-child(2)");
+  });
+
   it("returns null when a live DOM is present and no rung addresses one element", () => {
     document.body.innerHTML = `<div id="scene"><div class="group"></div><div class="group"></div></div>`;
     const el = document.querySelectorAll<HTMLElement>(".group")[1]!;

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" };
 }