@hyperframes/studio 0.8.126 → 0.8.128

package/src/components/editor/motionPathCommit.nodeDrop.test.ts

@@ -0,0 +1,212 @@
+// @vitest-environment happy-dom
+import { afterEach, expect, it, onTestFinished, vi } from "vitest";
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { DomEditSelection } from "./domEditing";
+import { boxSteps, previewWith, tween } from "../../hooks/gsapParsedTween.test-helpers";
+import { usePlayerStore } from "../../player/store/playerStore";
+import { GsapEditBlockedError } from "../../hooks/gsapEditOutcome";
+import { commitNodeDrop, nodeDropLabel, type CommitFn } from "./motionPathCommit";
+
+it("names a node drop for its undo entry by what it moved", () => {
+  const { autoKeyframeEnabled } = usePlayerStore.getState();
+  onTestFinished(() => usePlayerStore.setState({ autoKeyframeEnabled }));
+  usePlayerStore.setState({ autoKeyframeEnabled: true });
+  expect(nodeDropLabel({ type: "keyframe", pct: 50 })).toBe("Move keyframe");
+  usePlayerStore.setState({ autoKeyframeEnabled: false });
+  expect(nodeDropLabel({ type: "keyframe", pct: 50 })).toBe("Move animation path");
+  expect(nodeDropLabel({ type: "waypoint", index: 0 })).toBe("Move waypoint");
+});
+
+afterEach(() => {
+  usePlayerStore.setState({ currentTime: 0, activeKeyframePct: null, requestedSeekTime: null });
+  document.body.innerHTML = "";
+});
+
+function box(id = "box") {
+  const element = document.body.appendChild(document.createElement("div"));
+  element.id = id;
+  return { element, selection: { id, selector: `#${id}`, element } as DomEditSelection };
+}
+
+type Drop = Parameters<typeof commitNodeDrop>[0];
+
+function drop(fields: Omit<Drop, "animId" | "commitMutation"> & { anim: GsapAnimation }) {
+  const commitMutation = vi.fn<CommitFn>(async () => {});
+  const done = commitNodeDrop({ ...fields, animId: fields.anim.id, commitMutation });
+  const written = () =>
+    (commitMutation.mock.calls[0]![0] as { keyframes: { properties: object }[] }).keyframes.map(
+      (kf) => kf.properties,
+    );
+  return { done, commitMutation, written };
+}
+
+it("a keyframe node's drop changes that keyframe and keeps a newly animated channel on the others", async () => {
+  const { element, selection } = box();
+  // Over a CSS translate GSAP reads as y 30.
+  const { keys, live } = boxSteps([
+    [2, { x: 60 }],
+    [1, { x: 120 }],
+  ]);
+  usePlayerStore.setState({ currentTime: 2, autoKeyframeEnabled: true });
+
+  const { done, commitMutation, written } = drop({
+    ref: { type: "keyframe", pct: 100 },
+    at: { x: 150, y: 90 },
+    anim: keys,
+    selection,
+    iframe: previewWith(element, [live(element)], { x: 60, y: 30 }),
+  });
+  await done;
+
+  expect(commitMutation.mock.calls[0]![0].type).toBe("replace-with-keyframes");
+  expect(written()).toEqual([
+    { x: 60, y: 30 },
+    { x: 150, y: 90 },
+  ]);
+});
+
+it("a drop on an array step's node edits that step, though the path spaces nodes evenly", async () => {
+  const { element, selection } = box();
+  // Step ends at 2 s and 3 s; the path draws the first node at 0%, the parser and lane at 66.7%.
+  const { keys, live } = boxSteps([
+    [2, { x: 60, y: 30 }],
+    [1, { x: 120, y: 30 }],
+  ]);
+  usePlayerStore.setState({ currentTime: 1, autoKeyframeEnabled: true, activeKeyframePct: null });
+
+  const { done, written } = drop({
+    ref: { type: "keyframe", pct: 0, step: 0 },
+    at: { x: 40, y: 90 },
+    anim: keys,
+    selection,
+    iframe: previewWith(element, [live(element)], { x: 60, y: 30 }),
+  });
+  await done;
+
+  expect(written()).toEqual([
+    { x: 40, y: 90 },
+    { x: 120, y: 30 },
+  ]);
+  expect(usePlayerStore.getState().requestedSeekTime).toBe(2);
+});
+
+it("a drop the writer refuses rejects with the reason, writes nothing and selects nothing", async () => {
+  const [a, b] = [box("a"), box("b")];
+  for (const { element } of [a, b]) element.className = "card";
+  const shared = tween({
+    targetSelector: ".card",
+    method: "to",
+    properties: {},
+    resolvedStart: 0,
+    duration: 1,
+    keyframes: { format: "percentage", keyframes: [{ percentage: 100, properties: { x: 20 } }] },
+  });
+  usePlayerStore.setState({ autoKeyframeEnabled: true, activeKeyframePct: null });
+
+  const { done, commitMutation } = drop({
+    ref: { type: "keyframe", pct: 100 },
+    at: { x: 5, y: 0 },
+    anim: shared,
+    selection: a.selection,
+    iframe: previewWith(b.element, [], { x: 0, y: 0 }),
+  });
+
+  await expect(done).rejects.toBeInstanceOf(GsapEditBlockedError);
+  expect(commitMutation).not.toHaveBeenCalled();
+  expect(usePlayerStore.getState().activeKeyframePct).toBeNull();
+});
+
+it.each([true, false])(
+  "a drop on a step list with a step delay says the delay blocks it and writes nothing (auto-keyframe %s)",
+  async (autoKeyframeEnabled) => {
+    const { element, selection } = box();
+    const { keys } = boxSteps([
+      [1.5, { x: 100, delay: 0.5 }],
+      [1.5, { x: 200, delay: 0.5 }],
+    ]);
+    usePlayerStore.setState({ autoKeyframeEnabled, activeKeyframePct: null });
+
+    const { done, commitMutation } = drop({
+      ref: { type: "keyframe", pct: 100 },
+      at: { x: 150, y: 0 },
+      anim: keys,
+      selection,
+      iframe: previewWith(element, [], { x: 0, y: 0 }),
+    });
+
+    await expect(done).rejects.toThrow(/its own delay.*Code tab/);
+    expect(commitMutation).not.toHaveBeenCalled();
+  },
+);
+
+it("with auto-keyframe off, a step's node shifts the path by its own keyframe's move", async () => {
+  const { selection } = box();
+  // Steps of 4 s, 1 s and 1 s: drawn at 0/50/100%, parsed at their step ends.
+  const { keys } = boxSteps([
+    [4, { x: 60, y: 0 }],
+    [1, { x: 120, y: 0 }],
+    [1, { x: 180, y: 0 }],
+  ]);
+  usePlayerStore.setState({ autoKeyframeEnabled: false, activeKeyframePct: null });
+
+  const { done, written } = drop({
+    ref: { type: "keyframe", pct: 50, step: 1 },
+    at: { x: 157, y: 0 },
+    anim: keys,
+    selection,
+    iframe: null,
+  });
+  await done;
+
+  expect(written().map((props) => (props as { x: number }).x)).toEqual([97, 157, 217]);
+});
+
+it("a drop on an inner keyframe of a tween eased as a whole changes that keyframe", async () => {
+  const { element, selection } = box();
+  const keys = tween({
+    id: "#box-to-0-position",
+    method: "to",
+    properties: {},
+    resolvedStart: 0,
+    duration: 2,
+    ease: "power1.inOut",
+    keyframes: {
+      format: "percentage",
+      keyframes: [0, 100, 200].map((x, i) => ({ percentage: i * 50, properties: { x, y: 0 } })),
+    },
+  });
+  usePlayerStore.setState({ autoKeyframeEnabled: true, activeKeyframePct: null });
+
+  const { done, written } = drop({
+    ref: { type: "keyframe", pct: 50 },
+    at: { x: 150, y: 0 },
+    anim: keys,
+    selection,
+    iframe: previewWith(element, [], { x: 0, y: 0 }),
+  });
+  await done;
+
+  expect(written().map((props) => (props as { x: number }).x)).toEqual([0, 150, 200]);
+});
+
+it("a drop on a short step under 1% from the one before edits the dragged step", async () => {
+  const { element, selection } = box();
+  // Parsed at 50, 50.5 and 100%: a 0.05 s pop step in a 10 s list.
+  const { keys, live } = boxSteps([
+    [5, { x: 0, y: 0 }],
+    [0.05, { x: 100, y: 0 }],
+    [4.95, { x: 100, y: 0 }],
+  ]);
+  usePlayerStore.setState({ autoKeyframeEnabled: true, activeKeyframePct: null });
+
+  const { done, written } = drop({
+    ref: { type: "keyframe", pct: 50, step: 1 },
+    at: { x: 150, y: 0 },
+    anim: keys,
+    selection,
+    iframe: previewWith(element, [live(element)], { x: 0, y: 0 }),
+  });
+  await done;
+
+  expect(written().map((props) => (props as { x: number }).x)).toEqual([0, 150, 100]);
+});

package/src/components/editor/motionPathCommit.ts

@@ -5,7 +5,17 @@ import { trackPreviewFeatureUsed, type PreviewMethod } from "../../utils/preview
  * GSAP source mutation routed through the (selection-bound) commit facade, which
  * handles the soft reload, undo snapshot, and save-failure feedback.
  */
+import type { GsapAnimation } from "@hyperframes/parsers/gsap-parser";
+import { assertGsapEditPersisted } from "../../hooks/gsapEditOutcome";
+import { observeGsapGesture } from "../../hooks/gsapGestureOutcome";
+import { readGsapPositionFromIframe } from "../../hooks/gsapPositionDetection";
+import { commitValueAtPlayhead } from "../../hooks/gsapValueAtPlayhead";
+import { commitWholePropertyOffset } from "../../hooks/gsapWholePropertyOffsetCommit";
+import { usePlayerStore } from "../../player/store/playerStore";
+import { trackPreviewEditResult } from "../../utils/previewFeatureUsage";
+import type { DomEditSelection } from "./domEditing";
 import type { MotionNodeRef } from "./motionPathGeometry";
+import { selectorFor } from "./motionPathSelection";
 
 export type CommitFn = (
   mutation: Record<string, unknown>,
@@ -41,6 +51,54 @@ export function commitNode(
   );
 }
 
+type NodeDrop = {
+  ref: MotionNodeRef;
+  at: { x: number; y: number };
+  animId: string;
+  anim: GsapAnimation | undefined;
+  selection: DomEditSelection | null;
+  iframe: HTMLIFrameElement | null;
+  commitMutation: CommitFn;
+};
+
+/** What a node drop does, for its undo entry and its failure report. */
+export function nodeDropLabel(ref: MotionNodeRef): string {
+  if (ref.type !== "keyframe") return "Move waypoint";
+  return usePlayerStore.getState().autoKeyframeEnabled ? "Move keyframe" : "Move animation path";
+}
+
+/** A dropped keyframe goes through the layer drag's writer, GSAP's live values backfilling others
+ *  (auto-keyframe off, #1808: the whole path shifts); a waypoint moves in place. */
+export function commitNodeDrop(drop: NodeDrop): Promise<void> {
+  const { ref, at, anim, selection, iframe, commitMutation } = drop;
+  if (ref.type !== "keyframe" || !anim || !selection)
+    return commitNode(ref, at.x, at.y, drop.animId, commitMutation);
+  const writes = observeGsapGesture((_sel, mutation, options) => commitMutation(mutation, options));
+  const callbacks = { commitMutation: writes.commit! };
+  let done: Promise<unknown>;
+  const store = usePlayerStore.getState();
+  const step = ref.step == null ? undefined : anim.keyframes?.keyframes[ref.step];
+  const pct = step?.percentage ?? ref.pct;
+  if (store.autoKeyframeEnabled) {
+    const selected = store.activeKeyframePct;
+    store.setActiveKeyframePct(pct);
+    const live = readGsapPositionFromIframe(iframe, selectorFor(selection) ?? "");
+    done = commitValueAtPlayhead(selection, anim, at, iframe, callbacks, {
+      label: nodeDropLabel(ref),
+      backfill: live ?? undefined,
+    })
+      .then(assertGsapEditPersisted)
+      .catch((error: unknown) => {
+        usePlayerStore.getState().setActiveKeyframePct(selected);
+        throw error;
+      });
+  } else {
+    const label = nodeDropLabel(ref);
+    done = commitWholePropertyOffset(selection, anim, at, pct, iframe, callbacks, label);
+  }
+  return done.then(() => trackPreviewEditResult("motion_path", "drag", writes.finish()));
+}
+
 export function commitAddWaypoint(
   animationId: string,
   index: number,

package/src/components/editor/motionPathGeometry.test.ts

@@ -182,3 +182,16 @@ describe("start", () => {
     );
   });
 });
+
+it("an array step's node carries its step, so a drop finds that keyframe whatever its time", () => {
+  const read = {
+    keyframes: [
+      { percentage: 0, properties: { x: 60 }, step: 0 },
+      { percentage: 100, properties: { x: 120 }, step: 1 },
+    ],
+  };
+  expect(buildMotionPathGeometry(read)!.nodes.map((n) => n.ref)).toEqual([
+    { type: "keyframe", pct: 0, step: 0 },
+    { type: "keyframe", pct: 100, step: 1 },
+  ]);
+});

package/src/components/editor/motionPathGeometry.ts

@@ -8,7 +8,7 @@ import type { ReadTween } from "../../hooks/gsapRuntimeKeyframes";
 
 /** Which source edit a dragged node maps to. */
 export type MotionNodeRef =
-  | { type: "keyframe"; pct: number } // x/y position keyframe at this tween-relative %
+  | { type: "keyframe"; pct: number; step?: number } // x/y keyframe at this tween-relative %, array slot
   | { type: "waypoint"; index: number }; // motionPath waypoint (anchor) at this index
 
 /** An offset on the path and the layout width/height set there, when one is. */
@@ -141,7 +141,9 @@ export function buildMotionPathGeometry(
     if (!at) return;
     nodes.push({
       ...at,
-      ref: isArc ? { type: "waypoint", index: i } : { type: "keyframe", pct: kf.percentage },
+      ref: isArc
+        ? { type: "waypoint", index: i }
+        : { type: "keyframe", pct: kf.percentage, ...(kf.step == null ? {} : { step: kf.step }) },
     });
   });
 

package/src/components/editor/probeSourceElement.ts

@@ -1,7 +1,23 @@
 import { buildProjectApiPath } from "../../utils/projectRouting";
 import { studioApiFetch } from "../../utils/studioApiFetch";
+import type { DomEditSelection } from "./domEditingTypes";
 
-type ProbeTarget = { id?: string; hfId?: string; selector?: string; selectorIndex?: number };
+export type ProbeTarget = { id?: string; hfId?: string; selector?: string; selectorIndex?: number };
+
+export function knownSourceAnswer(
+  previous: DomEditSelection | null | undefined,
+  element: HTMLElement,
+  sourceFile: string,
+  target: ProbeTarget,
+): boolean | undefined {
+  if (!previous || previous.element !== element || previous.sourceFile !== sourceFile) return;
+  const same =
+    previous.id === target.id &&
+    previous.hfId === target.hfId &&
+    previous.selector === target.selector &&
+    previous.selectorIndex === target.selectorIndex;
+  return same ? previous.existsInSource : undefined;
+}
 
 interface PendingProbe {
   target: ProbeTarget;

package/src/components/nle/useCanvasZOrderTimelineMirror.test.tsx

@@ -79,24 +79,14 @@ function mountMirrorHarness(history: {
   moveCoalesceKeys: string[];
   records: RecordedWrite[];
 }) {
-  const record = (
-    label: string,
-    coalesceKey: string,
-    _coalesceMs: number | undefined,
-    after: string,
-  ) => {
+  const record = (label: string, coalesceKey: string, after: string) => {
     history.records.push({ label, coalesceKey, after });
     history.fileContent.current = after;
   };
 
-  const onMoveElements: TimelineEditCallbacks["onMoveElements"] = (
-    _edits,
-    coalesceKey,
-    _operation,
-    coalesceMs,
-  ) => {
+  const onMoveElements: TimelineEditCallbacks["onMoveElements"] = (_edits, coalesceKey) => {
     history.moveCoalesceKeys.push(coalesceKey ?? "<none>");
-    record("Move timeline clips", coalesceKey ?? "<none>", coalesceMs, "C-move");
+    record("Move timeline clips", coalesceKey ?? "<none>", "C-move");
   };
 
   const api: Partial<HarnessApi> = {};
@@ -104,7 +94,7 @@ function mountMirrorHarness(history: {
     const { handleDomZIndexReorderCommit } = useElementLifecycleOps(
       makeLifecycleOpsParams({
         commitDomEditPatchBatches: async (_batches, options) => {
-          record(options.label, options.coalesceKey, options.coalesceMs, "B-z");
+          record(options.label, options.coalesceKey, "B-z");
           return { durable: true, allMatched: true, changed: true };
         },
       }),

package/src/components/nle/useCanvasZOrderTimelineMirror.ts

@@ -163,13 +163,6 @@ function useMirrorLaneMoveCommit(): (
           // stacking sync must not re-trigger and fight the just-set z values.
         },
         coalesceKey,
-        // Unbounded fold window: this record lands only AFTER the z persist's
-        // server round-trip resolved, so the gap between the gesture's two
-        // records exceeds editHistory's 300ms default under real latency and
-        // the fold would silently split into two undo entries. The shared key
-        // is unique per gesture (zReorderCoalesceKey's gesture seq), so the
-        // unbounded window can never merge two distinct user actions.
-        Number.POSITIVE_INFINITY,
       );
     },
     [onMoveElements],

package/src/components/nle/useTimelineEditCallbacks.test.tsx

@@ -679,6 +679,33 @@ describe("useTimelineEditCallbacks — flat tween keyframe lanes", () => {
     view.unmount();
   });
 
+  it("retimes a duration-less tween's keyframe in the window GSAP plays it, not the clip", async () => {
+    const durationless = { ...authoredInteriorAnimation(), duration: undefined };
+    mocks.animations = [durationless];
+    usePlayerStore.setState({ gsapAnimations: new Map([["box", [durationless]]]) });
+    const view = renderCallbacks();
+
+    // GSAP plays it 0-0.5 s of the 1 s clip, so a drop at 0.4 s is 80% of the tween.
+    await view.callbacks.onMoveKeyframe?.(
+      "box",
+      {
+        percentage: 25,
+        propertyGroup: "position",
+        tweenPercentage: 50,
+        animationId: durationless.id,
+      },
+      40,
+    );
+
+    expect(mocks.actions.handleGsapMoveKeyframe).toHaveBeenCalledWith(
+      durationless.id,
+      50,
+      80,
+      mocks.selection,
+    );
+    view.unmount();
+  });
+
   // A drag starts on whatever diamond the pointer is over, which need not be the
   // selected element. Resolving against the selection would retime the selected
   // element's tween and commit it through the selected element's file.
@@ -777,46 +804,4 @@ describe("useTimelineEditCallbacks — flat tween keyframe lanes", () => {
     expect(mocks.actions.handleGsapMoveKeyframe).not.toHaveBeenCalled();
     view.unmount();
   });
-
-  it("uses the clip timing basis when retiming a duration-less tween", async () => {
-    const durationless = {
-      ...authoredInteriorAnimation(),
-      position: 3.2,
-      resolvedStart: 3.2,
-      duration: undefined,
-    };
-    const wideElement = { ...element, start: 10.94, duration: 16.26 };
-    mocks.animations = [durationless];
-    usePlayerStore.setState({
-      elements: [wideElement],
-      gsapAnimations: new Map([["box", [durationless]]]),
-    });
-    const view = renderCallbacks();
-
-    await expect(
-      view.callbacks.onMoveKeyframe?.(
-        "box",
-        {
-          percentage: 19.1,
-          propertyGroup: "position",
-          tweenPercentage: 50,
-          animationId: durationless.id,
-        },
-        40,
-      ),
-    ).resolves.toBe(true);
-
-    // The whole point of the clip basis: the drop lands at 10.94 + 0.40 * 16.26 =
-    // 17.444s, and the duration-less tween borrows the clip's 16.26s window from
-    // its 3.2s start, so 17.444 - 3.2 over 16.26 is 87.601%. Any other basis (a
-    // zero-length tween, or the clip's own 0-100 %) produces a different number.
-    expect(mocks.actions.handleGsapMoveKeyframe).toHaveBeenCalledWith(
-      durationless.id,
-      50,
-      expect.closeTo(87.601, 3),
-      mocks.selection,
-    );
-    expect(mocks.actions.handleGsapResizeKeyframedTween).not.toHaveBeenCalled();
-    view.unmount();
-  });
 });

package/src/components/nle/useTimelineEditCallbacks.ts

@@ -12,6 +12,7 @@ import {
   useDomEditSelectionContext,
 } from "../../contexts/DomEditContext";
 import { resolveTweenStart, resolveTweenDuration } from "../../utils/globalTimeCompiler";
+import { runEaseOf } from "../../utils/gsapKeyframeEases";
 import { resolveClipTimingBasis } from "../../hooks/useGsapTweenCache";
 import { elementCacheKeys } from "../../hooks/gsapKeyframeCacheHelpers";
 import { resolveKeyframeRetime } from "../editor/keyframeRetime";
@@ -32,7 +33,6 @@ export interface TimelineEditCallbackDeps {
     edits: Array<{ element: TimelineElement; updates: Pick<TimelineElement, "start" | "track"> }>,
     coalesceKey?: string,
     operation?: TimelineMoveOperation,
-    coalesceMs?: number,
   ) => Promise<void> | void;
   handleTimelineElementResize: (
     element: TimelineElement,
@@ -332,7 +332,7 @@ export function useTimelineEditCallbacks({
           elements,
           domClipChildren,
         );
-        const tweenDuration = resolveTweenDuration(anim, elDuration);
+        const tweenDuration = resolveTweenDuration(anim);
         const dropAbsTime = elStart + (toClipPct / 100) * elDuration;
         const decision = resolveKeyframeRetime({
           keyframes: anim.keyframes?.keyframes ?? [],
@@ -340,6 +340,7 @@ export function useTimelineEditCallbacks({
           tweenStart,
           tweenDuration,
           dropAbsTime,
+          runEase: runEaseOf(anim),
         });
         if (decision.kind === "move" && decision.toTweenPct != null) {
           return handleGsapMoveKeyframe(target.animId, target.tweenPct, decision.toTweenPct, sel);

package/src/hooks/gsapDragCommit.ts

@@ -5,14 +5,19 @@
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { usePlayerStore } from "../player/store/playerStore";
-import { resolveTweenStart, resolveTweenDuration } from "../utils/globalTimeCompiler";
+import {
+  percentageToAbsoluteForAnimation,
+  resolveTweenStart,
+  resolveTweenDuration,
+} from "../utils/globalTimeCompiler";
 import { roundTo3, roundToLayoutPx } from "../utils/rounding";
 import { computeElementPercentage, keyframeEases, writeTargetSelector } from "./gsapShared";
 import { computeDraggedGsapPosition } from "./draggedGsapPosition";
 import type { CommitMutation } from "./gsapScriptCommitTypes";
 import { isGestureTransactionCommit, runGestureTransaction } from "./gestureTransaction";
 import { setPatchFromUpdateProperty } from "./gsapDragStaticSetHelpers";
-import { GsapEditBlockedError } from "./gsapEditOutcome";
+import { GsapEditBlockedError, type PlayheadEditRefusal } from "./gsapEditOutcome";
+import { isTweenConfigKey } from "@hyperframes/parsers/gsap-constants";
 export {
   findExistingPositionWrite,
   findRotationSetAnimation,
@@ -53,10 +58,9 @@ export function computeCurrentPercentage(
 // 1.2 start), so the post-commit reseek renders the element's base pose and the edit
 // looks like it snapped away. Keeping the playhead on the edited keyframe avoids that.
 export function parkPlayheadOnKeyframe(anim: GsapAnimation, pct: number): void {
-  const ts = resolveTweenStart(anim);
-  const td = resolveTweenDuration(anim);
-  if (ts == null || !td || td <= 0) return;
-  usePlayerStore.getState().requestSeek(roundTo3(ts + (pct / 100) * td));
+  const time = percentageToAbsoluteForAnimation(pct, anim);
+  if (time === null || resolveTweenDuration(anim) <= 0) return;
+  usePlayerStore.getState().requestSeek(roundTo3(time));
 }
 
 async function replaceKeyframedPositionHold(
@@ -117,6 +121,36 @@ export async function materializeIfDynamic(
   throw new GsapEditBlockedError("source-uneditable", "geometry-unresolved-source");
 }
 
+/** Why a percentage keyframe can't stand in for this array step entry, or null when it can. */
+function stepBlock([key, value]: [string, number | string]): PlayheadEditRefusal | null {
+  if (key === "delay") return "array-step-delay";
+  if (/^on[A-Z]/.test(key)) return "array-step-callback";
+  if (isTweenConfigKey(key)) return "array-step-config";
+  if (typeof value === "number") return null;
+  return STEP_VALUE_BLOCKS.find(([pattern]) => pattern.test(value))?.[1] ?? null;
+}
+
+/** First match wins: code is computed, even when it calls random(). */
+const STEP_VALUE_BLOCKS: Array<[RegExp, PlayheadEditRefusal]> = [
+  [/^__raw:/, "array-step-computed"],
+  [/random\(/, "array-step-random"],
+  [/[-+*/]=/, "array-step-relative"],
+];
+
+/** Why a step list can't be rewritten as percentage keyframes, or null. */
+export function stepListBlock(anim: GsapAnimation): PlayheadEditRefusal | null {
+  const data = anim.keyframes;
+  if (data?.format !== "object-array") return null;
+  const entries = data.keyframes.flatMap((kf) => Object.entries(kf.properties));
+  return entries.map(stepBlock).find(Boolean) ?? null;
+}
+
+/** Whole-offset writers rewrite every step as a keyframe; refuse a list that holds more than values. */
+export function refuseStepListRewrite(anim: GsapAnimation): void {
+  const step = stepListBlock(anim);
+  if (step) throw new GsapEditBlockedError("keyframes-uneditable", step);
+}
+
 // ── Drag → GSAP position math ──────────────────────────────────────────────
 
 /**
@@ -330,6 +364,7 @@ export async function commitWholePathOffset(
   // fallow-ignore-next-line code-duplication
   let effectiveAnim = anim;
   if (anim.keyframes) {
+    refuseStepListRewrite(anim);
     const newId = await materializeIfDynamic(anim, iframe, callbacks.commitMutation, selection);
     if (newId) effectiveAnim = { ...anim, id: newId };
   }