@hyperframes/studio 0.8.126 → 0.8.127

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.126",
+  "version": "0.8.127",
   "description": "",
   "repository": {
     "type": "git",
@@ -60,12 +60,12 @@
     "dockview-react": "8.3.1",
     "gsap": "^3.13.0",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.8.126",
-    "@hyperframes/sdk": "0.8.126",
-    "@hyperframes/shader-transitions": "0.8.126",
-    "@hyperframes/player": "0.8.126",
-    "@hyperframes/parsers": "0.8.126",
-    "@hyperframes/studio-server": "0.8.126"
+    "@hyperframes/parsers": "0.8.127",
+    "@hyperframes/sdk": "0.8.127",
+    "@hyperframes/player": "0.8.127",
+    "@hyperframes/core": "0.8.127",
+    "@hyperframes/shader-transitions": "0.8.127",
+    "@hyperframes/studio-server": "0.8.127"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",
@@ -81,7 +81,7 @@
     "vite": "^6.4.2",
     "vitest": "^4.1.11",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.126"
+    "@hyperframes/producer": "0.8.127"
   },
   "peerDependencies": {
     "react": "19",

package/src/components/editor/MotionPathOverlay.layerPress.test.tsx

@@ -2,8 +2,10 @@
 import { act } from "react";
 import { createRoot } from "react-dom/client";
 import { afterEach, expect, it, vi } from "vitest";
+import { GsapEditBlockedError } from "../../hooks/gsapEditOutcome";
 import { usePlayerStore } from "../../player/store/playerStore";
 import { MotionPathOverlay } from "./MotionPathOverlay";
+import { commitNodeDrop } from "./motionPathCommit";
 import type { DomEditSelection } from "./domEditing";
 
 Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
@@ -14,6 +16,14 @@ const { commitMutation } = vi.hoisted(() => ({
 vi.mock("../../contexts/DomEditContext", () => ({
   useDomEditContext: () => ({ selectedGsapAnimations: [], commitMutation }),
 }));
+const showToast = vi.hoisted(() => vi.fn());
+vi.mock("../../contexts/StudioContext", () => ({
+  useStudioShellContextOptional: () => ({ showToast }),
+}));
+vi.mock("./motionPathCommit", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("./motionPathCommit")>()),
+  commitNodeDrop: vi.fn(),
+}));
 vi.mock("./motionPathSelection", () => ({
   selectorFor: () => "#box",
   editableAnimationId: () => "a1",
@@ -189,3 +199,35 @@ it("draws where GSAP started the tween before the first keyframe, as a mark that
   const drawn = host.querySelector("polyline:not(.pointer-events-auto)")!;
   expect(drawn.getAttribute("points")).toBe("50,30 60,30 140,30");
 });
+
+it("a node drop the writer refuses says why", async () => {
+  const refusal = new GsapEditBlockedError("keyframes-uneditable");
+  vi.mocked(commitNodeDrop).mockRejectedValue(refusal);
+  vi.spyOn(Element.prototype, "setPointerCapture").mockImplementation(() => {});
+  const host = document.body.appendChild(document.createElement("div"));
+  const root = createRoot(host);
+  const selection = { element: document.createElement("div") } as unknown as DomEditSelection;
+  try {
+    act(() =>
+      root.render(
+        <MotionPathOverlay
+          iframeRef={{ current: null }}
+          selection={selection}
+          compositionSize={{ width: 1920, height: 1080 }}
+          isPlaying={false}
+        />,
+      ),
+    );
+    const node = host.querySelector('circle.pointer-events-auto[cx="140"]')!;
+    document.elementsFromPoint = () => [node];
+    const at = (clientX: number) => ({ bubbles: true, button: 0, clientX, clientY: 30 });
+    act(() => void node.dispatchEvent(new PointerEvent("pointerdown", at(140))));
+    act(() => void node.dispatchEvent(new PointerEvent("pointermove", at(180))));
+    await act(async () => void node.dispatchEvent(new PointerEvent("pointerup", at(180))));
+    expect(commitNodeDrop).toHaveBeenCalledTimes(1);
+    expect(showToast).toHaveBeenCalledWith(refusal.message, "error");
+  } finally {
+    act(() => root.unmount());
+    host.remove();
+  }
+});

package/src/components/editor/MotionPathOverlay.tsx

@@ -1,13 +1,12 @@
-import { observeGsapGesture } from "../../hooks/gsapGestureOutcome";
-import { trackPreviewEditResult } from "../../utils/previewFeatureUsage";
 import { scopedElementKey } from "../../hooks/gsapKeyframeCacheHelpers";
 import { memo, useEffect, useRef, useState, type RefObject } from "react";
 import type { DomEditSelection } from "./domEditing";
 import { useDomEditContext } from "../../contexts/DomEditContext";
+import { useStudioShellContextOptional } from "../../contexts/StudioContext";
+import { useGsapInteractionFailureTelemetry } from "../../hooks/useGsapInteractionFailureTelemetry";
 import { usePlayerStore } from "../../player/store/playerStore";
 import { useLivePreviewIframe } from "../../player/store/previewIframeStore";
 import { parkPlayheadOnKeyframe } from "../../hooks/gsapDragCommit";
-import { commitWholePropertyOffset } from "../../hooks/gsapWholePropertyOffsetCommit";
 import { nearestPointOnPath, nodeCentre, type MotionNodeRef } from "./motionPathGeometry";
 import { editableAnimationId, selectorFor } from "./motionPathSelection";
 import { controlForNode, controlUnder, pressControl } from "./motionPathLayerNode";
@@ -23,8 +22,9 @@ import {
   commitAddKeyframe,
   commitAddWaypoint,
   commitCreatePath,
-  commitNode,
+  commitNodeDrop,
   commitRemoveWaypoint,
+  nodeDropLabel,
 } from "./motionPathCommit";
 import { elementHome } from "./motionPathHome";
 import { hasMotionPathPlugin, transformWDivisor, useMotionPathData } from "./useMotionPathData";
@@ -66,6 +66,7 @@ const NODE_PX = 6; // node radius in screen pixels (kept constant across zoom)
 // (select the keyframe); at or above it the gesture commits a move. Screen-space
 // (not composition px) so it behaves identically at any zoom.
 const DRAG_THRESHOLD_PX = 3;
+const noToast = () => {};
 
 /**
  * Draws the selected element's GSAP motion path over the canvas — a dashed
@@ -91,6 +92,11 @@ export const MotionPathOverlay = memo(function MotionPathOverlay({
     handleGsapRemoveAllKeyframes,
     handleGsapMoveKeyframeToPlayhead,
   } = useDomEditContext();
+  const shell = useStudioShellContextOptional();
+  const reportFailure = useGsapInteractionFailureTelemetry(
+    shell?.activeCompPath ?? null,
+    shell?.showToast ?? noToast,
+  );
   const { rect, geometry, geometryResolved, visibleInPreview, home, pScale } = useMotionPathData(
     iframeRef,
     selectorFor(selection),
@@ -373,30 +379,18 @@ export const MotionPathOverlay = memo(function MotionPathOverlay({
     // high zoom) would commit an identical value — a no-op undo entry. Skip the
     // commit, but don't treat it as a click either (the user did drag).
     if (x === Math.round(d.initX) && y === Math.round(d.initY)) return;
-    // Auto-keyframe off (#1808): dragging a keyframe's node shifts the whole path.
     const anim =
       d.ref.type === "keyframe" ? selectedGsapAnimations?.find((a) => a.id === animId) : undefined;
-    if (
-      d.ref.type === "keyframe" &&
-      anim &&
-      selection &&
-      !usePlayerStore.getState().autoKeyframeEnabled
-    ) {
-      const writes = observeGsapGesture((_sel, mutation, options) =>
-        commitMutation(mutation, options),
-      );
-      void commitWholePropertyOffset(
-        selection,
-        anim,
-        { x, y },
-        d.ref.pct,
-        iframeRef.current,
-        { commitMutation: writes.commit! },
-        "Move animation path",
-      ).then(() => trackPreviewEditResult("motion_path", "drag", writes.finish()));
-    } else {
-      void commitNode(d.ref, x, y, animId, commitMutation);
-    }
+    const label = nodeDropLabel(d.ref);
+    commitNodeDrop({
+      ref: d.ref,
+      at: { x, y },
+      animId,
+      anim,
+      selection,
+      iframe: iframeRef.current,
+      commitMutation,
+    }).catch((error: unknown) => reportFailure(error, selection, "drag", label));
     // Park on the edited keyframe, or a playhead before the tween hides the edit.
     if (d.ref.type === "keyframe" && anim) {
       parkPlayheadOnKeyframe(anim, d.ref.pct);

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/hooks/gsapDragCommit.ts

@@ -12,7 +12,8 @@ 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,
@@ -117,6 +118,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 +361,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 };
   }

package/src/hooks/gsapEditOutcome.ts

@@ -15,7 +15,7 @@ export type GsapEditBlockReason =
  * true for `provenance-runtime-dynamic`; the others are parser or source-match
  * limits, where the animation may well be plain authored source.
  *
- * Telemetry only. Nothing branches on it.
+ * Telemetry, plus the sharper message a few details get (GSAP_EDIT_DETAIL_COPY).
  */
 export type GsapEditBlockDetail =
   | "provenance-runtime-dynamic"
@@ -33,6 +33,12 @@ export type GsapEditBlockDetail =
 export type PlayheadEditRefusal =
   | "eased-keyframes"
   | "simple-array-keyframes"
+  | "array-step-delay"
+  | "array-step-callback"
+  | "array-step-config"
+  | "array-step-computed"
+  | "array-step-relative"
+  | "array-step-random"
   | "unknown-ease"
   | "implicit-end-unknown"
   | "not-a-tween"
@@ -74,12 +80,31 @@ export const GSAP_EDIT_BLOCK_COPY: Record<GsapEditBlockReason, string> = {
     "These layers are animated in different files. Move each file's layers separately.",
 };
 
+const STEP_LIST = "This animation's keyframes have a step";
+const IN_CODE = "Edit them in the Code tab.";
+/** A refusal a person can act on more precisely than its reason's message: what blocks it, then what to do. */
+const GSAP_EDIT_DETAIL_COPY: Partial<Record<GsapEditBlockDetail, string>> = {
+  "array-step-delay": `${STEP_LIST} with its own delay, which Studio can't keep while it edits them. ${IN_CODE}`,
+  "array-step-callback": `${STEP_LIST} that runs code as it plays (like onComplete), which an edit would run again. ${IN_CODE}`,
+  "array-step-config": `${STEP_LIST} with its own tween setting (like repeat or stagger), which Studio can't keep while it edits them. ${IN_CODE}`,
+  "array-step-computed": `${STEP_LIST} whose value comes from code, which Studio can't keep while it edits them. ${IN_CODE}`,
+  "array-step-relative": `${STEP_LIST} with a relative value (like "+=40"), which an edit would apply again. ${IN_CODE}`,
+  "array-step-random": `${STEP_LIST} with a random() value, which an edit would roll again. ${IN_CODE}`,
+};
+
+export function gsapEditBlockMessage(
+  reason: GsapEditBlockReason,
+  detail?: GsapEditBlockDetail,
+): string {
+  return (detail && GSAP_EDIT_DETAIL_COPY[detail]) ?? GSAP_EDIT_BLOCK_COPY[reason];
+}
+
 export class GsapEditBlockedError extends Error {
   constructor(
     readonly reason: GsapEditBlockReason,
     readonly detail?: GsapEditBlockDetail,
   ) {
-    super(GSAP_EDIT_BLOCK_COPY[reason]);
+    super(gsapEditBlockMessage(reason, detail));
     this.name = "GsapEditBlockedError";
   }
 }

package/src/hooks/gsapParsedTween.test-helpers.ts

@@ -22,7 +22,7 @@ export function liveTween(
     vars: tween.vars,
     _from: from,
     ...(head && { _pt: { d: { _pt: head } } }),
-    ...(parts && { timeline: { getChildren: () => parts } }),
+    ...(parts && { timeline: { getChildren: () => parts, duration: () => tween.duration } }),
   };
 }
 
@@ -47,6 +47,33 @@ export function previewWith(
 export const tween = (fields: Partial<GsapAnimation>): GsapAnimation =>
   ({ targetSelector: "#box", propertyGroup: "position", ...fields }) as GsapAnimation;
 
+/** `#box`'s position as a keyframe step list, parsed and run by GSAP (step `[duration, props]`). */
+export function boxSteps(steps: Array<[number, Record<string, number | string>]>) {
+  const duration = steps.reduce((sum, [d]) => sum + d, 0);
+  let end = 0;
+  const keyframes = steps.map(([d, properties]) => {
+    end += d;
+    return { percentage: Math.round((end / duration) * 1000) / 10, properties };
+  });
+  const keys = tween({
+    id: "#box-to-0-position",
+    method: "to",
+    properties: {},
+    resolvedStart: 0,
+    duration,
+    keyframes: { format: "object-array", keyframes },
+  });
+  let start = 0;
+  const parts = steps.map(([d]) => {
+    const at = start;
+    start += d;
+    return { startTime: () => at, duration: () => d };
+  });
+  const live = (el: Element) =>
+    liveTween(el, { start: 0, duration, vars: { keyframes: [] } }, { parts });
+  return { keys, live };
+}
+
 /** A `to` tween on `#el` from 0, grouped as the parser would; duration 0 is an immediate-render hold. */
 export function elTween(
   id: string,