@hyperframes/studio 0.8.125 → 0.8.127

package/src/components/editor/useMotionPathData.test.tsx

@@ -1,7 +1,9 @@
 // @vitest-environment happy-dom
+import { gsap } from "gsap";
 import { act, useRef } from "react";
 import { createRoot } from "react-dom/client";
 import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import { elementHome } from "./motionPathHome";
 import { useMotionPathData } from "./useMotionPathData";
 import { resetOverlayFrameLoopForTests } from "./overlayFrameLoop";
 import { usePlayerStore } from "../../player/store/playerStore";
@@ -92,3 +94,237 @@ it("reads no layout per frame until there is a path or a create ring to draw", (
     act(() => root.unmount());
   }
 });
+
+it("finds the layer whichever window built its node, so the path draws on every load", () => {
+  runtime.read = {
+    keyframes: [
+      { percentage: 0, properties: { x: 0, y: 0 } },
+      { percentage: 100, properties: { x: 100, y: 0 } },
+    ],
+  };
+  const iframe = document.createElement("iframe");
+  document.body.append(iframe);
+  const box = iframe.contentDocument!.createElement("div");
+  box.id = "box";
+  iframe.contentDocument!.body.append(box);
+  // happy-dom shares one realm, so the frame's own constructor stands in for another window's.
+  Object.defineProperty(iframe.contentWindow!, "HTMLElement", { value: class {} });
+  let home: unknown = null;
+  function Probe() {
+    const ref = useRef(iframe);
+    home = useMotionPathData(ref, "#box").home;
+    return null;
+  }
+  const root = createRoot(document.body.appendChild(document.createElement("div")));
+  try {
+    act(() => root.render(<Probe />));
+    runFrames(3);
+    expect(home).not.toBeNull();
+  } finally {
+    act(() => root.unmount());
+  }
+});
+
+it("redraws a node whose keyframe changes only its size", () => {
+  const read = (width: number) => ({
+    keyframes: [
+      { percentage: 66.667, properties: { x: 60, width } },
+      { percentage: 100, properties: { x: 120, width: 320 } },
+    ],
+  });
+  runtime.read = read(280);
+  runtime.gsapPosition = { x: 50, y: 30 };
+  let w: number | undefined;
+  function Probe() {
+    const ref = useRef(document.createElement("iframe"));
+    w = useMotionPathData(ref, "#box").geometry?.nodes[0]?.w;
+    return null;
+  }
+  const root = createRoot(document.body.appendChild(document.createElement("div")));
+  try {
+    act(() => root.render(<Probe />));
+    expect(w).toBe(280);
+    runtime.read = read(300);
+    act(() => vi.advanceTimersByTime(250));
+    expect(w).toBe(300);
+  } finally {
+    act(() => root.unmount());
+  }
+});
+
+/** A layer laid out at (960, 540), 240 x 160, with `css` inline and `cache` as GSAP's `_gsap`. */
+function layer(css: Partial<CSSStyleDeclaration>, cache?: Record<string, number>) {
+  const el = document.body.appendChild(document.createElement("div"));
+  Object.assign(el.style, css);
+  const box = {
+    offsetLeft: 960,
+    offsetTop: 540,
+    offsetWidth: 240,
+    offsetHeight: 160,
+    offsetParent: null,
+  };
+  for (const [key, value] of Object.entries(box)) Object.defineProperty(el, key, { value });
+  return cache ? Object.assign(el, { _gsap: cache }) : el;
+}
+
+it("anchors a layer GSAP centres with xPercent/yPercent -50 on its centre", () => {
+  const el = layer(
+    { position: "absolute", left: "50%", top: "50%" },
+    { x: 0, y: 0, xPercent: -50, yPercent: -50 },
+  );
+  expect(elementHome(el)).toEqual({ x: 960, y: 540, w: 240, h: 160, ax: 0, ay: 0 });
+});
+
+it("moves a resized layer's centre by half the change from a set left, against it from a set right, and not in flow", () => {
+  const fromLeft = layer({ position: "absolute", left: "10px", top: "10px" });
+  expect(elementHome(fromLeft)).toMatchObject({ x: 1080, y: 620, ax: 0.5, ay: 0.5 });
+  const fromRight = layer({ position: "absolute", right: "10px", bottom: "10px" });
+  const auto = new Set(["left", "top"]);
+  fromRight.computedStyleMap = () =>
+    ({
+      get: (side: string) => (auto.has(side) ? "auto" : "10px"),
+    }) as unknown as StylePropertyMapReadOnly;
+  expect(elementHome(fromRight)).toMatchObject({ ax: -0.5, ay: -0.5 });
+  expect(elementHome(layer({}))).toMatchObject({ x: 1080, ax: 0, ay: 0 });
+});
+
+const resolved = (style: CSSStyleDeclaration) =>
+  (style.translate ?? "").replace(/var\((--[\w-]+)\)/g, (_, name) =>
+    style.getPropertyValue(name),
+  ) || "none";
+
+/** Computes `translate` and `transform` as Chromium does (happy-dom does not), so GSAP's parse would fold them. */
+function computeTranslate() {
+  const real = window.getComputedStyle.bind(window);
+  const computed = (node: Element, pseudo?: string | null) =>
+    new Proxy(real(node, pseudo), {
+      get(style, key) {
+        if (key === "translate") return resolved((node as HTMLElement).style);
+        if (key === "transform") return (node as HTMLElement).style.transform || "none";
+        if (key === "scale" || key === "rotate") return "none";
+        const value = Reflect.get(style, key);
+        return typeof value === "function" ? value.bind(style) : value;
+      },
+    });
+  vi.stubGlobal("getComputedStyle", computed);
+  vi.spyOn(window, "getComputedStyle").mockImplementation(
+    computed as typeof window.getComputedStyle,
+  );
+}
+
+it("leaves a layer's CSS translate alone and anchors where GSAP's parse will put it (real GSAP)", () => {
+  vi.stubGlobal("gsap", gsap);
+  computeTranslate();
+  try {
+    const offset = "var(--hf-studio-offset-x) var(--hf-studio-offset-y)";
+    const cases: [string, number, number][] = [
+      // GSAP folds these into x, which a created path sets.
+      ["40px 30px", 1080, 620],
+      [offset, 1080, 620],
+      // Minus half the size becomes xPercent/yPercent -50.
+      ["-50% -50%", 960, 540],
+      ["-120px -80px", 960, 540],
+    ];
+    // GSAP sums the layer's own transform with its translate: Chromium's matrix for translate(-50%, -50%).
+    const centred = layer({ position: "absolute", transform: "matrix(1, 0, 0, 1, -120, -80)" });
+    expect(elementHome(centred)).toMatchObject({ x: 960, y: 540 });
+    for (const [translate, x, y] of cases) {
+      const el = layer({ position: "absolute", left: "10px", top: "10px", translate });
+      el.style.setProperty("--hf-studio-offset-x", "40px");
+      el.style.setProperty("--hf-studio-offset-y", "30px");
+      expect(elementHome(el), translate).toMatchObject({ x, y });
+      expect([el.style.translate, el.style.transform]).toEqual([translate, ""]);
+    }
+    // A drag's offset on a layer GSAP already parsed composes with its transform.
+    const dragged = layer({ position: "absolute", left: "10px", top: "10px" });
+    gsap.set(dragged, { x: 20 });
+    dragged.style.setProperty("--hf-studio-offset-x", "40px");
+    dragged.style.setProperty("--hf-studio-offset-y", "30px");
+    dragged.style.translate = offset;
+    expect(elementHome(dragged)).toMatchObject({ x: 1120, y: 650 });
+    // After clearProps GSAP marks its cache uncache and its next parse folds the translate again.
+    const css = { position: "absolute", left: "10px", top: "10px", translate: "40px 30px" };
+    expect(elementHome(layer(css, { x: 0, y: 0, uncache: 1 }))).toMatchObject({ x: 1080, y: 620 });
+    // A fade gives GSAP a cache with no transform in it yet, so its next parse still folds.
+    expect(elementHome(layer(css, { opacity: 1 }))).toMatchObject({ x: 1080, y: 620 });
+    const owned = layer({ position: "absolute", left: "50%", top: "50%" });
+    gsap.set(owned, { xPercent: -50, yPercent: -50 });
+    expect(elementHome(owned)).toMatchObject({ x: 960, y: 540, ax: 0, ay: 0 });
+  } finally {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  }
+});
+
+it("redraws the start ring when only GSAP's start changes", () => {
+  const read = (start?: Record<string, number>) => ({
+    keyframes: [
+      { percentage: 50, properties: { x: 60 } },
+      { percentage: 100, properties: { x: 120 } },
+    ],
+    ...(start && { start }),
+  });
+  runtime.read = read();
+  runtime.gsapPosition = { x: 50, y: 30 };
+  let start: unknown;
+  function Probe() {
+    const ref = useRef(document.createElement("iframe"));
+    start = useMotionPathData(ref, "#box").geometry?.start;
+    return null;
+  }
+  const root = createRoot(document.body.appendChild(document.createElement("div")));
+  try {
+    act(() => root.render(<Probe />));
+    expect(start).toBeUndefined();
+    runtime.read = read({ x: 40 });
+    act(() => vi.advanceTimersByTime(250));
+    expect(start).toEqual({ x: 40, y: 30 });
+  } finally {
+    act(() => root.unmount());
+  }
+});
+
+it("updates the home when the layer's size or anchoring changes but its centre does not", () => {
+  runtime.read = {
+    keyframes: [
+      { percentage: 0, properties: { x: 0, width: 200 } },
+      { percentage: 100, properties: { x: 100, width: 240 } },
+    ],
+  };
+  const iframe = document.body.appendChild(document.createElement("iframe"));
+  const layout = { offsetLeft: 100, offsetWidth: 200 };
+  const box = iframe.contentDocument!.body.appendChild(
+    iframe.contentDocument!.createElement("div"),
+  );
+  box.id = "box";
+  for (const key of ["offsetLeft", "offsetWidth"] as const)
+    Object.defineProperty(box, key, { get: () => layout[key] });
+  let w: number | undefined;
+  let ax: number | undefined;
+  function Probe() {
+    const ref = useRef(iframe);
+    ({ w, ax } = useMotionPathData(ref, "#box").home ?? {});
+    return null;
+  }
+  const root = createRoot(document.body.appendChild(document.createElement("div")));
+  try {
+    act(() => root.render(<Probe />));
+    runFrames(2);
+    expect(w).toBe(200);
+    Object.assign(layout, { offsetLeft: 80, offsetWidth: 240 });
+    runFrames(2);
+    expect(w).toBe(240);
+    // Re-anchored from the left to the right edge without moving: the share a size change moves changes.
+    Object.assign(box.style, { position: "absolute", left: "10px" });
+    runFrames(2);
+    expect(ax).toBe(0.5);
+    box.computedStyleMap = () =>
+      ({
+        get: (side: string) => (side === "left" ? "auto" : "0px"),
+      }) as unknown as StylePropertyMapReadOnly;
+    runFrames(2);
+    expect(ax).toBe(-0.5);
+  } finally {
+    act(() => root.unmount());
+  }
+});

package/src/components/editor/useMotionPathData.ts

@@ -1,31 +1,19 @@
 import { useEffect, useRef, useState, type RefObject } from "react";
+import { isHtmlElement } from "@hyperframes/core/runtime/dom-realm";
 import { readRuntimeKeyframes } from "../../hooks/gsapRuntimeKeyframes";
 import { readGsapPositionFromIframe } from "../../hooks/gsapPositionDetection";
 import { isElementVisibleForOverlay } from "./domEditOverlayGeometry";
-import { buildMotionPathGeometry, type MotionPathGeometry } from "./motionPathGeometry";
+import {
+  buildMotionPathGeometry,
+  type MotionPathGeometry,
+  type MotionPathHome,
+} from "./motionPathGeometry";
+import { elementHome } from "./motionPathHome";
 import { subscribeOverlayFrame } from "./overlayFrameLoop";
 import { usePlayerStore } from "../../player/store/playerStore";
 
 type Rect = { left: number; top: number; width: number; height: number };
 
-// The translate (e/f) components of an element's computed transform, in comp px.
-// A group wrapper dragged via GSAP carries its offset here, not in offsetLeft/Top.
-function transformTranslate(el: HTMLElement): { x: number; y: number } {
-  const t = el.ownerDocument?.defaultView?.getComputedStyle(el).transform;
-  if (!t || t === "none") return { x: 0, y: 0 };
-  const m3 = t.match(/matrix3d\(([^)]+)\)/);
-  if (m3) {
-    const v = m3[1].split(",").map(Number);
-    return { x: v[12] || 0, y: v[13] || 0 };
-  }
-  const m = t.match(/matrix\(([^)]+)\)/);
-  if (m) {
-    const v = m[1].split(",").map(Number);
-    return { x: v[4] || 0, y: v[5] || 0 };
-  }
-  return { x: 0, y: 0 };
-}
-
 // Perspective foreshortening of the element's OWN transform (matrix3d m44). A
 // depth element (translateZ toward the viewer) renders 1/m44× larger, so its
 // animated x/y offsets travel 1/m44× further on screen than the flat preview
@@ -40,43 +28,6 @@ export function transformWDivisor(el: HTMLElement): number {
   return Number.isFinite(w) && w > 0 ? w : 1;
 }
 
-export function elementHome(el: HTMLElement): { x: number; y: number } {
-  let left = 0;
-  let top = 0;
-  let node: HTMLElement | null = el;
-  while (node) {
-    left += node.offsetLeft;
-    top += node.offsetTop;
-    // Ancestor transforms (e.g. a group wrapper moved via GSAP) shift where the
-    // element actually renders, so the path must anchor on top of them. The element's
-    // OWN transform is excluded — that's the animated offset the path itself draws.
-    if (node !== el) {
-      const t = transformTranslate(node);
-      left += t.x;
-      top += t.y;
-    }
-    const parent = node.offsetParent as HTMLElement | null;
-    if (!parent || parent.hasAttribute("data-composition-id")) break;
-    node = parent;
-  }
-  let x = left + el.offsetWidth / 2;
-  let y = top + el.offsetHeight / 2;
-  if ((el.style.translate ?? "").includes("var(")) {
-    x += Number.parseFloat(el.style.getPropertyValue("--hf-studio-offset-x")) || 0;
-    y += Number.parseFloat(el.style.getPropertyValue("--hf-studio-offset-y")) || 0;
-  }
-  return { x, y };
-}
-
-export function isPreviewHtmlElement(
-  node: Element | null | undefined,
-  iframe: HTMLIFrameElement | null,
-): node is HTMLElement {
-  const Ctor = (iframe?.contentWindow as unknown as { HTMLElement?: typeof HTMLElement } | null)
-    ?.HTMLElement;
-  return Boolean(node && Ctor && node instanceof Ctor);
-}
-
 function rectsClose(a: Rect, b: Rect): boolean {
   return (
     Math.abs(a.left - b.left) < 0.5 &&
@@ -104,7 +55,7 @@ export function useMotionPathData(
   geometry: MotionPathGeometry | null;
   geometryResolved: boolean;
   visibleInPreview: boolean;
-  home: { x: number; y: number } | null;
+  home: MotionPathHome | null;
   pScale: number;
 } {
   const [rect, setRect] = useState<Rect | null>(null);
@@ -112,7 +63,7 @@ export function useMotionPathData(
   const resolvedForRef = useRef<string | null>(null);
   const geometryResolved = resolvedForRef.current === selector;
   const [visibleInPreview, setVisibleInPreview] = useState(true);
-  const [home, setHome] = useState<{ x: number; y: number } | null>(null);
+  const [home, setHome] = useState<MotionPathHome | null>(null);
   // Perspective magnification (1/m44) of the selected element — applied to the
   // path's offset points so depth (translateZ) elements' paths track on screen.
   const [pScale, setPScale] = useState(1);
@@ -146,13 +97,21 @@ export function useMotionPathData(
         } catch {
           /* cross-origin guard */
         }
-        const live = isPreviewHtmlElement(target, el) ? target : null;
+        const live = isHtmlElement(target) ? target : null;
         const vis = live ? isElementVisibleForOverlay(live) : true;
         setVisibleInPreview((prev) => (prev === vis ? prev : vis));
         if (live) {
           const h = elementHome(live);
           setHome((prev) =>
-            prev && Math.abs(prev.x - h.x) < 0.5 && Math.abs(prev.y - h.y) < 0.5 ? prev : h,
+            prev &&
+            Math.abs(prev.x - h.x) < 0.5 &&
+            Math.abs(prev.y - h.y) < 0.5 &&
+            prev.w === h.w &&
+            prev.h === h.h &&
+            prev.ax === h.ax &&
+            prev.ay === h.ay
+              ? prev
+              : h,
           );
           const ps = 1 / transformWDivisor(live);
           setPScale((p) => (Math.abs(p - ps) < 0.001 ? p : ps));
@@ -173,7 +132,10 @@ export function useMotionPathData(
       const base = read ? readGsapPositionFromIframe(iframeRef.current, selector) : null;
       const next = buildMotionPathGeometry(read, base ?? undefined);
       setGeometry((prev) =>
-        prev?.points === next?.points && prev?.kind === next?.kind ? prev : next,
+        prev?.kind === next?.kind &&
+        JSON.stringify([prev?.nodes, prev?.start]) === JSON.stringify([next?.nodes, next?.start])
+          ? prev
+          : next,
       );
       resolvedForRef.current = selector;
     };

package/src/components/sidebar/CompositionsTab.thumbnails.test.tsx

@@ -39,6 +39,7 @@ class ViewportObserver {
     const entry = { isIntersecting: true } as IntersectionObserverEntry;
     this.callback([entry], this as unknown as IntersectionObserver);
   }
+  unobserve() {}
   disconnect() {}
 }
 

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,

package/src/hooks/gsapParsedTween.ts

@@ -1,7 +1,9 @@
 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";
 
 // GSAP 3 internals: a property tween in a tween's `_pt` chain; CSSPlugin keeps its own under `d._pt`.
 interface PropTween {
@@ -22,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;
@@ -57,6 +59,21 @@ function endsIn(tween: ParsedTween, prop: string): [number, number] | null {
   return tween._from ? [pair[1], pair[0]] : pair;
 }
 
+/** `read` plus GSAP's start for a step list or a first key past 0%, read per channel. */
+export function withParsedStart(read: ReadTween, live: unknown): ReadTween {
+  const tween = live as ParsedTween;
+  const first = read.keyframes[0];
+  if (!Array.isArray(tween.vars?.keyframes) && !((first?.percentage ?? 0) > 0)) return read;
+  const children = tween.timeline?.getChildren?.() ?? [tween];
+  const start: Record<string, number> = {};
+  for (const prop of ["x", "y", "width", "height"]) {
+    const ends = children.map((child) => endsIn(child, prop)).find(Boolean);
+    if (ends) start[prop] = ends[0];
+  }
+  const moved = Object.entries(start).some(([prop, value]) => value !== first?.properties[prop]);
+  return moved ? { ...read, start } : read;
+}
+
 /** The live tween GSAP built from `anim`: same element, start and channels, parsed. */
 // fallow-ignore-next-line complexity
 export function findParsedTween(
@@ -230,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);
@@ -241,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);
 }