@hyperframes/studio 0.8.126 → 0.8.128

package/src/hooks/gsapDragPositionCommit.ts

@@ -1,8 +1,13 @@
-import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import type { GsapAnimation, GsapPercentageKeyframe } from "@hyperframes/core/gsap-parser";
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 import { usePlayerStore } from "../player/store/playerStore";
-import { resolveTweenStart } from "../utils/globalTimeCompiler";
-import { KEYFRAME_PCT_MATCH, resolveEditableTweenDuration } from "./gsapShared";
+import {
+  isTimeWithinTween,
+  resolveTweenDuration,
+  resolveTweenStart,
+} from "../utils/globalTimeCompiler";
+import { KEYFRAME_PCT_MATCH, playsNear } from "./gsapShared";
+import { progressAtTime, runEaseOf, timeAtProgress } from "../utils/gsapKeyframeEases";
 import { roundTo3 } from "../utils/rounding";
 import { computeDraggedGsapPosition } from "./draggedGsapPosition";
 import {
@@ -19,7 +24,8 @@ import { commitValueAtPlayhead, planValueEdit } from "./gsapValueAtPlayhead";
  * server takes a replace-with-keyframes list verbatim, so an append-only build
  * could hand it two keyframes a fraction of a percent apart. The invariant lives
  * here rather than in each caller's own pre-check, which is how the two callers
- * ended up with different tolerances in the first place.
+ * ended up with different tolerances in the first place. Arc writes are linear, so each
+ * keyframe moves to the time GSAP reached it and `percentage` is a time percentage.
  */
 export function buildTemporalArcKeyframes(
   anim: GsapAnimation,
@@ -27,7 +33,7 @@ export function buildTemporalArcKeyframes(
   properties: Record<string, number>,
 ) {
   return [
-    ...(anim.keyframes?.keyframes ?? [])
+    ...linearArcKeyframes(anim)
       .filter((keyframe) => Math.abs(keyframe.percentage - percentage) > KEYFRAME_PCT_MATCH)
       .map((keyframe) => ({
         percentage: keyframe.percentage,
@@ -38,6 +44,46 @@ export function buildTemporalArcKeyframes(
   ].sort((a, b) => a.percentage - b.percentage);
 }
 
+/** An arc's keyframes at the time percentages GSAP plays them, for a write with `ease: "none"`. */
+export function linearArcKeyframes(anim: GsapAnimation): GsapPercentageKeyframe[] {
+  const runEase = runEaseOf(anim);
+  return (anim.keyframes?.keyframes ?? []).map((keyframe) => ({
+    ...keyframe,
+    percentage: roundTo3(timeAtProgress(runEase, keyframe.percentage)),
+  }));
+}
+
+/** Grow a keyframe tween's range to a playhead outside it and add a keyframe there; every
+ *  existing keyframe keeps its absolute time under `writeEase`, the run ease the write keeps. */
+export function buildExtendedKeyframes(
+  anim: GsapAnimation,
+  currentTime: number,
+  position: Record<string, number>,
+  sourceDuration = resolveTweenDuration(anim),
+  writeEase = runEaseOf(anim),
+): { position: number; duration: number; keyframes: GsapPercentageKeyframe[] } {
+  const oldStart = resolveTweenStart(anim) ?? 0;
+  const oldDuration = sourceDuration;
+  const newStart = Math.min(oldStart, currentTime);
+  const newEnd = Math.max(oldStart + oldDuration, currentTime);
+  const newDuration = roundTo3(newEnd - newStart);
+  const oldRunEase = runEaseOf(anim);
+  const toPct = (absoluteTime: number) => {
+    if (newDuration <= 0) return 0;
+    const progress = progressAtTime(writeEase, ((absoluteTime - newStart) / newDuration) * 100);
+    return Math.max(0, Math.min(100, Math.round(progress * 10) / 10));
+  };
+  const stops = anim.keyframes?.keyframes ?? [];
+  const rescaled: GsapPercentageKeyframe[] = stops.map((stop) => ({
+    percentage: toPct(oldStart + (timeAtProgress(oldRunEase, stop.percentage) / 100) * oldDuration),
+    properties: stop.properties,
+    ...(stop.ease ? { ease: stop.ease } : {}),
+  }));
+  const added: GsapPercentageKeyframe = { percentage: toPct(currentTime), properties: position };
+  const keyframes = [...rescaled, added].sort((a, b) => a.percentage - b.percentage);
+  return { position: roundTo3(newStart), duration: newDuration, keyframes };
+}
+
 /** commitGsapPositionFromDrag's refusal, decided without writing. */
 export function gsapPositionFromDragOutcome(
   selection: DomEditSelection,
@@ -87,15 +133,45 @@ export async function commitGsapPositionFromDrag(
   };
 
   if (anim.arcPath?.enabled) {
-    const { activeKeyframePct, setActiveKeyframePct } = usePlayerStore.getState();
+    const { activeKeyframePct, currentTime, setActiveKeyframePct } = usePlayerStore.getState();
+    const tweenStart = resolveTweenStart(anim);
+    const tweenDuration = resolveTweenDuration(anim);
+    if (
+      activeKeyframePct === null &&
+      tweenStart !== null &&
+      !isTimeWithinTween(currentTime, tweenStart, tweenDuration)
+    ) {
+      const extended = buildExtendedKeyframes(
+        anim,
+        currentTime,
+        { x: newX, y: newY },
+        tweenDuration,
+        "none",
+      );
+      await callbacks.commitMutation(
+        selection,
+        {
+          type: "replace-with-keyframes",
+          animationId: anim.id,
+          targetSelector: anim.targetSelector,
+          ...extended,
+          ease: "none",
+        },
+        {
+          label: "Move layer (new keyframe)",
+          keyframeAction: "add",
+          softReload: true,
+          beforeReload: restoreOffset,
+        },
+      );
+      return { status: "persisted" };
+    }
     const pct = activeKeyframePct ?? computeCurrentPercentage(selection, anim);
     const keyframes = anim.keyframes?.keyframes ?? [];
-    // Same tolerance as applyArcKeyframeAtPlayhead and isMotionPathEndpoint. A
-    // tighter one here meant a drag that landed a fraction of a percent off an
-    // authored waypoint skipped the update-point branch and appended instead.
-    const pointIndex = keyframes.findIndex(
-      (kf) => Math.abs(kf.percentage - pct) <= KEYFRAME_PCT_MATCH,
-    );
+    // A drag counts as on a waypoint when it plays within KEYFRAME_PCT_MATCH of it,
+    // so landing a fraction of a percent off an authored waypoint updates that point
+    // instead of appending a new one.
+    const pointIndex = keyframes.findIndex((kf) => playsNear(anim, kf.percentage, pct));
     if (pointIndex >= 0) {
       await callbacks.commitMutation(
         selection,
@@ -113,13 +189,10 @@ export async function commitGsapPositionFromDrag(
       return { status: "persisted" };
     }
 
-    const tweenStart = resolveTweenStart(anim);
-    // Clip-wide, same as applyArcKeyframeAtPlayhead: authoring GSAP's 0.5s
-    // default here would collapse a duration-less arc's window on drag.
-    const tweenDuration = resolveEditableTweenDuration(anim, selection);
     if (tweenStart === null || tweenDuration <= 0 || keyframes.length < 2)
       return { status: "persisted" };
-    const temporalKeyframes = buildTemporalArcKeyframes(anim, pct, { x: newX, y: newY });
+    const timePct = roundTo3(timeAtProgress(runEaseOf(anim), pct));
+    const temporalKeyframes = buildTemporalArcKeyframes(anim, timePct, { x: newX, y: newY });
     await callbacks.commitMutation(
       selection,
       {

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/gsapKeyframeCacheHelpers.test.ts

@@ -78,6 +78,56 @@ describe("non-string cache keys", () => {
   });
 });
 
+describe("replaceKeyframeCacheForFile re-reads", () => {
+  it("publishes nothing when a file re-reads to the same entries, and the change when one differs", () => {
+    const write = (x: number) =>
+      replaceKeyframeCacheForFile(
+        "comp.html",
+        new Map([
+          ["box", { format: "percentage", keyframes: [{ percentage: 0, properties: { x } }] }],
+        ]),
+        new Map([["box", [animWithKeyframes("box")]]]),
+      );
+    write(0);
+    let notified = 0;
+    const stop = usePlayerStore.subscribe(() => notified++);
+    write(0);
+    expect(notified).toBe(0);
+    write(5);
+    stop();
+    expect(notified).toBe(1);
+    expect(cache().get("comp.html#box")?.keyframes[0]?.properties).toEqual({ x: 5 });
+  });
+
+  it("leaves a sub-composition's entries alone when index.html re-reads", () => {
+    const one = (id: string) => new Map([[id, entry()]]);
+    const anims = (id: string) => new Map([[id, [animWithKeyframes(id)]]]);
+    replaceKeyframeCacheForFile("comp.html", one("box"), anims("box"));
+    replaceKeyframeCacheForFile("index.html", one("hero"), anims("hero"));
+    let notified = 0;
+    const stop = usePlayerStore.subscribe(() => notified++);
+    replaceKeyframeCacheForFile("index.html", one("hero"), anims("hero"));
+    stop();
+
+    expect(notified).toBe(0);
+    for (const key of ["comp.html#box", "index.html#box", "box", "index.html#hero", "hero"]) {
+      expect(cache().has(key)).toBe(true);
+    }
+  });
+
+  it("still drops index.html's own element that shares an id with a sub-composition", () => {
+    const one = (id: string) => new Map([[id, entry()]]);
+    const anims = (id: string) => new Map([[id, [animWithKeyframes(id)]]]);
+    const own = { format: "percentage", keyframes: [{ percentage: 0, properties: { x: 9 } }] };
+    replaceKeyframeCacheForFile("comp.html", one("title"), anims("title"));
+    replaceKeyframeCacheForFile("index.html", new Map([["title", own]]), anims("title"));
+    replaceKeyframeCacheForFile("index.html", new Map(), new Map());
+
+    expect(cache().has("index.html#title")).toBe(false);
+    expect(cache().has("comp.html#title")).toBe(true);
+  });
+});
+
 describe("clearKeyframeCacheForElement", () => {
   it("drops the prefixed, index.html fallback, and bare key for a non-index source", () => {
     seed("comp.html#box");

package/src/hooks/gsapKeyframeCacheHelpers.ts

@@ -5,6 +5,7 @@
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import { usePlayerStore, type KeyframeCacheEntry } from "../player/store/playerStore";
 import { trackStudioEvent } from "../utils/studioTelemetry";
+import { sameData } from "../utils/sameData";
 import { resolveClipTimingBasis, resolveSelectorElementIds, toClipKeyframes } from "./gsapShared";
 import {
   deduplicateKeyframes,
@@ -18,6 +19,14 @@ export interface KeyframeCacheDraft {
   gsapAnimations: Map<string, GsapAnimation[]>;
 }
 
+// A rebuilt entry equal to the one shown keeps its object, so re-reading an unchanged file publishes nothing.
+function keepEqualEntries<V>(before: ReadonlyMap<string, V>, draft: Map<string, V>): void {
+  for (const [key, value] of draft) {
+    const shown = before.get(key);
+    if (shown !== undefined && shown !== value && sameData(shown, value)) draft.set(key, shown);
+  }
+}
+
 function sameEntries<V>(before: ReadonlyMap<string, V>, after: ReadonlyMap<string, V>): boolean {
   if (before.size !== after.size) return false;
   for (const [key, value] of before) {
@@ -42,6 +51,8 @@ export function publishKeyframeCache(edit: (draft: KeyframeCacheDraft) => void):
     gsapAnimations: new Map(gsapAnimations),
   };
   edit(draft);
+  keepEqualEntries(keyframeCache, draft.keyframeCache);
+  keepEqualEntries(gsapAnimations, draft.gsapAnimations);
   if (
     sameEntries(keyframeCache, draft.keyframeCache) &&
     sameEntries(gsapAnimations, draft.gsapAnimations)
@@ -175,8 +186,16 @@ function cachedElementIdsForFile(
   const sfPrefix = `${sourceFile}#`;
   const ids = new Set<string>();
   for (const key of [...keyframeCache.keys(), ...gsapAnimations.keys()]) {
-    if (!key.startsWith(sfPrefix)) continue;
-    ids.add(key.slice(sfPrefix.length));
+    if (key.startsWith(sfPrefix)) ids.add(key.slice(sfPrefix.length));
+  }
+  if (sourceFile !== "index.html") return ids;
+  // Another file's element also writes the `index.html#id` fallback, as the very same entry object.
+  for (const [key, entry] of keyframeCache) {
+    const hash = key.indexOf("#");
+    const id = key.slice(hash + 1);
+    if (hash > 0 && !key.startsWith(sfPrefix) && keyframeCache.get(sfPrefix + id) === entry) {
+      ids.delete(id);
+    }
   }
   return ids;
 }

package/src/hooks/gsapMutationClient.ts

@@ -88,9 +88,11 @@ function readMutationError(value: unknown, fallback: string): string {
   return fallback;
 }
 
+type GsapMutationRoute = "gsap-mutations" | "gsap-mutations-batch";
+
 export function requestGsapMutation(
   projectId: string,
-  route: "gsap-mutations" | "gsap-mutations-batch",
+  route: GsapMutationRoute,
   filePath: string,
   body: unknown,
 ): Promise<Response> {
@@ -104,23 +106,49 @@ export function requestGsapMutation(
   );
 }
 
-export async function postGsapMutation(
+async function postOwnedGsapMutation(
+  route: GsapMutationRoute,
   projectId: string,
   filePath: string,
-  mutation: Record<string, unknown>,
+  body: Record<string, unknown>,
   fallback: string,
 ): Promise<GsapMutationStatus> {
   let response: Response;
   try {
-    response = await requestGsapMutation(projectId, "gsap-mutations", filePath, mutation);
+    response = await requestGsapMutation(projectId, route, filePath, body);
   } catch (error) {
     throw new GsapPreviewConvergenceError(`${fallback}: mutation outcome unknown`, {
       cause: error,
     });
   }
-  const body: unknown = await response.json().catch(() => null);
+  const payload: unknown = await response.json().catch(() => null);
   if (!response.ok) {
-    throw new GsapPreviewConvergenceError(readMutationError(body, fallback));
+    throw new GsapPreviewConvergenceError(readMutationError(payload, fallback));
   }
-  return readMutationStatus(body);
+  return readMutationStatus(payload);
+}
+
+export function postGsapMutation(
+  projectId: string,
+  filePath: string,
+  mutation: Record<string, unknown>,
+  fallback: string,
+): Promise<GsapMutationStatus> {
+  return postOwnedGsapMutation("gsap-mutations", projectId, filePath, mutation, fallback);
+}
+
+/** Every mutation in one request: the file is parsed and written once, with one ownership pair. */
+export function postGsapMutations(
+  projectId: string,
+  filePath: string,
+  mutations: readonly Record<string, unknown>[],
+  fallback: string,
+): Promise<GsapMutationStatus> {
+  return postOwnedGsapMutation(
+    "gsap-mutations-batch",
+    projectId,
+    filePath,
+    { mutations },
+    fallback,
+  );
 }

package/src/hooks/gsapOvershootEase.test.ts

@@ -0,0 +1,67 @@
+import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
+import { parseGsapScriptAcorn } from "@hyperframes/parsers/gsap-parser-acorn";
+import { replaceTweenWithKeyframesInScript } from "@hyperframes/parsers/gsap-writer-acorn";
+import { describe, expect, it } from "vitest";
+import { resolveKeyframeRetime } from "../components/editor/keyframeRetime";
+import { absoluteToPercentageForAnimation } from "../utils/globalTimeCompiler";
+import { runEaseOf, timeAtProgress } from "../utils/gsapKeyframeEases";
+import { buildExtendedKeyframes } from "./gsapDragPositionCommit";
+import { keyframeEases } from "./gsapShared";
+
+const script = (ease: string) =>
+  `const tl = gsap.timeline({ paused: true });\ntl.to("#x", { keyframes: { "0%": { x: 0 }, "50%": { x: 600 }, "100%": { x: 1200 } }, duration: 2, ease: "${ease}" }, 1);`;
+
+const percentages = (anim: GsapAnimation) => anim.keyframes!.keyframes.map((k) => k.percentage);
+const distinctInRange = (pcts: number[]) =>
+  pcts.every((p, i) => p >= 0 && p <= 100 && (i === 0 || p > pcts[i - 1]!));
+
+describe.each(["back.out(1.7)", "back.in(1.7)", "elastic.out(1, 0.3)", "steps(4)"])(
+  "an outer %s, which does not map time to progress one to one",
+  (ease) => {
+    const src = script(ease);
+    const anim = parseGsapScriptAcorn(src).animations[0]!;
+
+    it("adding a keyframe past the end keeps every keyframe, distinct and in range, after a reparse", () => {
+      const out = buildExtendedKeyframes(anim, 5, { x: 1500 });
+      const written = replaceTweenWithKeyframesInScript(src, anim.id, {
+        targetSelector: "#x",
+        ...keyframeEases(anim),
+        ...out,
+      })!;
+      const back = parseGsapScriptAcorn(written).animations[0]!;
+      expect(distinctInRange(percentages(back))).toBe(true);
+      expect(back.keyframes!.keyframes.map((k) => k.properties.x)).toEqual([0, 600, 1200, 1500]);
+    });
+
+    it("a keyframe added inside the tween lands within 0-100%", () => {
+      const pct = absoluteToPercentageForAnimation(1 + 0.7 * 2, anim)!;
+      expect(pct).toBeGreaterThanOrEqual(0);
+      expect(pct).toBeLessThanOrEqual(100);
+    });
+
+    it("dragging the last keyframe later keeps every keyframe distinct and in range", () => {
+      const retime = resolveKeyframeRetime({
+        keyframes: anim.keyframes!.keyframes,
+        draggedTweenPct: 100,
+        tweenStart: 1,
+        tweenDuration: 2,
+        dropAbsTime: 4,
+        runEase: runEaseOf(anim),
+      });
+      expect(retime.kind).toBe("resize");
+      expect(distinctInRange(retime.pctRemap!.map((r) => r.to))).toBe(true);
+    });
+  },
+);
+
+it("extending a tween under steps(4) loses no keyframe", () => {
+  const src = `const tl = gsap.timeline({ paused: true });\ntl.to("#x", { keyframes: { "0%": { x: 0 }, "25%": { x: 60 }, "60%": { x: 120 }, "100%": { x: 30 } }, duration: 2, ease: "steps(4)" }, 1);`;
+  const anim = parseGsapScriptAcorn(src).animations[0]!;
+  const out = buildExtendedKeyframes(anim, 4, { x: 999 });
+  expect(distinctInRange(out.keyframes.map((k) => k.percentage))).toBe(true);
+  expect(out.keyframes.map((k) => k.properties.x)).toEqual([0, 60, 120, 30, 999]);
+});
+
+it("still times keyframes through an outer ease that rises one to one", () => {
+  expect(timeAtProgress("power2.in", 50)).toBeCloseTo(79.37, 1);
+});

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,6 +1,7 @@
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import { elementTargets } from "../utils/elementGsap";
 import { resolveTweenStart } from "../utils/globalTimeCompiler";
+import { KEYFRAME_PCT_MATCH } from "./gsapShared";
 import type { ImplicitEndValue } from "./gsapValueAtPlayhead";
 import type { ReadTween } from "./gsapRuntimeKeyframes";
 
@@ -23,7 +24,7 @@ interface ParsedTween {
     seek?: (time: number, suppressEvents?: boolean) => unknown;
     getChildren?: (nested?: boolean, tweens?: boolean, timelines?: boolean) => ParsedTween[];
   };
-  timeline?: { getChildren?: () => ParsedTween[] };
+  timeline?: { getChildren?: () => ParsedTween[]; duration?: () => number };
   targets?: () => unknown[];
   startTime?: () => number;
   duration?: () => number;
@@ -246,14 +247,33 @@ 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;
-  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);
-  if (ends.some((end) => !Number.isFinite(end))) return anim;
+  if (data?.format !== "object-array" || parts.length !== data.keyframes.length) return anim;
+  const ends = parts.map((part) => (part.startTime?.() ?? 0) + (part.duration?.() ?? 0));
+  const total = Math.max(...ends);
+  if (!(total > 0) || ends.some((end) => !Number.isFinite(end))) return anim;
   const keyframes = data.keyframes.map((kf, i) => ({
     ...kf,
-    percentage: Math.round(ends[i]! * 100000) / 1000,
+    percentage: Math.round((ends[i]! / total) * 100000) / 1000,
   }));
   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/gsapPositionDetection.ts

@@ -8,6 +8,7 @@
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import { usePlayerStore } from "../player/store/playerStore";
 import { getIframeGsap, KEYFRAME_PCT_MATCH, queryIframeElement } from "./gsapShared";
+import { runEaseOf, timeAtProgress } from "../utils/gsapKeyframeEases";
 import { resolveTweenStart, resolveTweenDuration } from "../utils/globalTimeCompiler";
 
 // fallow-ignore-next-line complexity
@@ -60,7 +61,7 @@ export function findGsapPositionAnimation(
 
 function playheadProximity(a: GsapAnimation, currentTime: number): number {
   const pos = a.resolvedStart ?? (typeof a.position === "number" ? a.position : 0);
-  const dur = a.duration ?? 0;
+  const dur = resolveTweenDuration(a);
   if (currentTime >= pos - 0.05 && currentTime <= pos + dur + 0.05) return 50;
   return -Math.round(Math.min(Math.abs(currentTime - pos), Math.abs(currentTime - pos - dur)) * 5);
 }
@@ -71,7 +72,9 @@ function statesValueAt(anim: GsapAnimation, time: number): boolean {
   if (!(duration > 0)) return false;
   const pct = ((time - (resolveTweenStart(anim) ?? 0)) / duration) * 100;
   const near = (keyframe: number) => Math.abs(keyframe - pct) <= KEYFRAME_PCT_MATCH;
-  if (anim.keyframes) return anim.keyframes.keyframes.some((kf) => near(kf.percentage));
+  const runEase = runEaseOf(anim);
+  if (anim.keyframes)
+    return anim.keyframes.keyframes.some((kf) => near(timeAtProgress(runEase, kf.percentage)));
   if (anim.method === "from") return near(0);
   return near(100) || (anim.method === "fromTo" && near(0));
 }

package/src/hooks/gsapRuntimeBridge.test.ts

@@ -582,6 +582,41 @@ describe("tryGsapDragIntercept — motion paths", () => {
     );
   });
 
+  it("adds a node at a playhead past a duration-less arc, keeping the other nodes' times", async () => {
+    usePlayerStore.setState({
+      autoKeyframeEnabled: true,
+      activeKeyframePct: null,
+      currentTime: 15.9,
+    });
+    const durationless = { ...motionPathAnim, duration: undefined } as GsapAnimation;
+    const commitMutation = vi.fn();
+    await tryGsapDragIntercept(
+      selection,
+      { x: -50, y: 30 },
+      [durationless],
+      fakeIframe("puck-b", [
+        { ...liveTween, vars: { motionPath: { path: [] } }, duration: () => 0.5 },
+      ]),
+      commitMutation,
+    );
+    // GSAP plays it 12.17-12.67 s; the nodes stay at 12.17, 12.42 and 12.67 s.
+    expect(commitMutation).toHaveBeenCalledWith(
+      selection,
+      expect.objectContaining({
+        type: "replace-with-keyframes",
+        position: 12.17,
+        duration: 3.73,
+        keyframes: [
+          { percentage: 0, properties: { x: -184, y: 326 } },
+          { percentage: 6.7, properties: { x: 416, y: 804 } },
+          { percentage: 13.4, properties: { x: 796, y: 237 } },
+          { percentage: 100, properties: { x: -50, y: 30 } },
+        ],
+      }),
+      expect.objectContaining({ label: "Move layer (new keyframe)", keyframeAction: "add" }),
+    );
+  });
+
   it("keeps an explicitly selected path waypoint as a spatial edit", async () => {
     const { commitMutation, handled } = await dragMotionPath(50);
 

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