@hyperframes/studio 0.7.76 → 0.7.78

package/src/hooks/gsapDragPositionCommit.ts

@@ -2,6 +2,7 @@ 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 { KEYFRAME_PCT_MATCH, resolveEditableTweenDuration } from "./gsapShared";
 import { roundTo3 } from "../utils/rounding";
 import { computeDraggedGsapPosition } from "./draggedGsapPosition";
 import {
@@ -11,6 +12,31 @@ import {
   materializeIfDynamic,
 } from "./gsapDragCommit";
 
+/**
+ * The tween's keyframes with one inserted at `percentage`. Any existing keyframe
+ * within {@link KEYFRAME_PCT_MATCH} of the insert is REPLACED, not kept: the
+ * 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.
+ */
+export function buildTemporalArcKeyframes(
+  anim: GsapAnimation,
+  percentage: number,
+  properties: Record<string, number>,
+) {
+  return [
+    ...(anim.keyframes?.keyframes ?? [])
+      .filter((keyframe) => Math.abs(keyframe.percentage - percentage) > KEYFRAME_PCT_MATCH)
+      .map((keyframe) => ({
+        percentage: keyframe.percentage,
+        properties: { ...keyframe.properties },
+        ...(keyframe.ease ? { ease: keyframe.ease } : {}),
+      })),
+    { percentage, properties },
+  ].sort((a, b) => a.percentage - b.percentage);
+}
+
 async function extendTweenAndAddKeyframe(
   selection: DomEditSelection,
   anim: GsapAnimation,
@@ -143,7 +169,7 @@ async function commitFlatViaKeyframes(
 ): Promise<void> {
   const ct = usePlayerStore.getState().currentTime;
   const ts = resolveTweenStart(anim);
-  const td = resolveTweenDuration(anim);
+  const td = resolveEditableTweenDuration(anim, selection);
   const { activeKeyframePct, setActiveKeyframePct } = usePlayerStore.getState();
   const outsideRange =
     activeKeyframePct == null && ts !== null && td > 0 && (ct < ts - 0.01 || ct > ts + td + 0.01);
@@ -184,8 +210,13 @@ async function commitFlatViaKeyframes(
       { label: "Convert to keyframes for drag", skipReload: true, coalesceKey },
     );
     const fresh = callbacks.fetchAnimations ? await callbacks.fetchAnimations() : [];
+    // By id first: a target with several tweens (two `to`s on the same selector)
+    // matches the selector lookup on whichever one happens to be first, and the
+    // extend-and-add below would then rewrite a tween the drag never touched.
     const converted =
-      fresh.find((a) => a.targetSelector === anim.targetSelector && a.keyframes) ?? anim;
+      fresh.find((a) => a.id === anim.id && a.keyframes) ??
+      fresh.find((a) => a.targetSelector === anim.targetSelector && a.keyframes) ??
+      anim;
     const convertedStart = resolveTweenStart(converted) ?? ts;
     const convertedDur = resolveTweenDuration(converted) || td;
     await extendTweenAndAddKeyframe(
@@ -259,13 +290,61 @@ export async function commitGsapPositionFromDrag(
 
   const backfillDefaults: Record<string, number> = { x: baseGsapX, y: baseGsapY };
   const ct = usePlayerStore.getState().currentTime;
+  if (anim.arcPath?.enabled) {
+    const { activeKeyframePct, setActiveKeyframePct } = usePlayerStore.getState();
+    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,
+    );
+    if (pointIndex >= 0) {
+      await callbacks.commitMutation(
+        selection,
+        {
+          type: "update-motion-path-point",
+          animationId: anim.id,
+          pointIndex,
+          x: newX,
+          y: newY,
+        },
+        { label: "Move layer (waypoint)", softReload: true, beforeReload: restoreOffset },
+      );
+      setActiveKeyframePct(null);
+      parkPlayheadOnKeyframe(anim, pct);
+      return;
+    }
+
+    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;
+    const temporalKeyframes = buildTemporalArcKeyframes(anim, pct, { x: newX, y: newY });
+    await callbacks.commitMutation(
+      selection,
+      {
+        type: "replace-with-keyframes",
+        animationId: anim.id,
+        targetSelector: anim.targetSelector,
+        position: roundTo3(tweenStart),
+        duration: roundTo3(tweenDuration),
+        keyframes: temporalKeyframes,
+        ease: "none",
+      },
+      { label: "Move layer (new keyframe)", softReload: true, beforeReload: restoreOffset },
+    );
+    return;
+  }
   if (anim.keyframes) {
     const newId = await materializeIfDynamic(anim, iframe, callbacks.commitMutation, selection);
     const effectiveAnim = newId ? { ...anim, id: newId } : anim;
     const dragProps: Record<string, number> = { x: newX, y: newY };
 
     const ts = resolveTweenStart(effectiveAnim);
-    const td = resolveTweenDuration(effectiveAnim);
+    const td = resolveEditableTweenDuration(effectiveAnim, selection);
     const outsideRange = ts !== null && td > 0 && (ct < ts - 0.01 || ct > ts + td + 0.01);
     const hasSelectedKeyframe = usePlayerStore.getState().activeKeyframePct != null;
     if (outsideRange && !hasSelectedKeyframe) {
@@ -293,7 +372,7 @@ export async function commitGsapPositionFromDrag(
   } else if (anim.method === "from" || anim.method === "fromTo") {
     const ct = usePlayerStore.getState().currentTime;
     const ts = resolveTweenStart(anim);
-    const td = resolveTweenDuration(anim);
+    const td = resolveEditableTweenDuration(anim, selection);
     const hasSelectedKeyframe = usePlayerStore.getState().activeKeyframePct != null;
     const outsideRange =
       !hasSelectedKeyframe && ts !== null && td > 0 && (ct < ts - 0.01 || ct > ts + td + 0.01);
@@ -313,7 +392,7 @@ export async function commitGsapPositionFromDrag(
 
       if (existingPosAnim?.keyframes) {
         const posTs = resolveTweenStart(existingPosAnim);
-        const posTd = resolveTweenDuration(existingPosAnim);
+        const posTd = resolveEditableTweenDuration(existingPosAnim, selection);
         if (posTs !== null) {
           await extendTweenAndAddKeyframe(
             selection,

package/src/hooks/gsapKeyframeCacheHelpers.test.ts

@@ -4,6 +4,7 @@ import { usePlayerStore, type KeyframeCacheEntry } from "../player/store/playerS
 import {
   clearKeyframeCacheForElement,
   clearKeyframeCacheForFile,
+  pruneKeyframeCacheToFiles,
   updateKeyframeCacheFromParsed,
 } from "./gsapKeyframeCacheHelpers";
 
@@ -28,7 +29,7 @@ const animWithKeyframes = (id: string): GsapAnimation => ({
 });
 
 beforeEach(() => {
-  usePlayerStore.setState({ keyframeCache: new Map(), elements: [] });
+  usePlayerStore.setState({ keyframeCache: new Map(), gsapAnimations: new Map(), elements: [] });
 });
 
 describe("clearKeyframeCacheForElement", () => {
@@ -84,6 +85,20 @@ describe("clearKeyframeCacheForFile", () => {
     }
   });
 
+  // Several composition files re-scan concurrently, so a clear that walked the
+  // index.html alias would delete rows a sibling file had just written.
+  it("leaves an index.html-owned element alone when another file re-scans", () => {
+    seed("index.html#title");
+    seed("title");
+    seed("comp.html#a");
+
+    clearKeyframeCacheForFile("comp.html");
+
+    expect(cache().has("index.html#title")).toBe(true);
+    expect(cache().has("title")).toBe(true);
+    expect(cache().has("comp.html#a")).toBe(false);
+  });
+
   it("leaves entries that belong to a different source file", () => {
     seed("comp.html#a");
     seed("a");
@@ -97,7 +112,84 @@ describe("clearKeyframeCacheForFile", () => {
   });
 });
 
+describe("pruneKeyframeCacheToFiles", () => {
+  // Switching composition leaves the previous comp's elements cached with no
+  // owner left to clear them: each file only ever clears its own entries.
+  it("drops every element of a file the next scan no longer covers", () => {
+    seed("index.html#stress-1");
+    seed("stress-1");
+    seed("index.html#stress-2");
+    seed("stress-2");
+    seed("kf200.html#kf200");
+    seed("index.html#kf200");
+    seed("kf200");
+
+    pruneKeyframeCacheToFiles(["kf200.html"]);
+
+    for (const key of ["index.html#stress-1", "stress-1", "index.html#stress-2", "stress-2"]) {
+      expect(cache().has(key)).toBe(false);
+    }
+    expect(cache().has("kf200.html#kf200")).toBe(true);
+  });
+
+  it("prunes gsapAnimations alongside keyframeCache", () => {
+    usePlayerStore.getState().setGsapAnimations("index.html#stress-1", [animWithKeyframes("t")]);
+    usePlayerStore.getState().setGsapAnimations("kf200.html#kf200", [animWithKeyframes("u")]);
+
+    pruneKeyframeCacheToFiles(["kf200.html"]);
+
+    const animations = usePlayerStore.getState().gsapAnimations;
+    expect(animations.has("index.html#stress-1")).toBe(false);
+    expect(animations.has("kf200.html#kf200")).toBe(true);
+  });
+
+  it("keeps everything when every cached file is still covered", () => {
+    seed("index.html#hero");
+    seed("comp.html#a");
+
+    pruneKeyframeCacheToFiles(["index.html", "comp.html"]);
+
+    expect(cache().has("index.html#hero")).toBe(true);
+    expect(cache().has("comp.html#a")).toBe(true);
+  });
+});
+
 describe("updateKeyframeCacheFromParsed", () => {
+  it("serializes a multi-keyframe tween with a stable shape and animation identity", () => {
+    const animation: GsapAnimation = {
+      ...animWithKeyframes("hero"),
+      duration: 2,
+      resolvedStart: 3,
+      keyframes: {
+        format: "percentage",
+        keyframes: [
+          { percentage: 0, properties: { x: 0 } },
+          { percentage: 50, properties: { x: 100 }, ease: "power1.inOut" },
+          { percentage: 100, properties: { x: 200 } },
+        ],
+        easeEach: "power1.inOut",
+      },
+    };
+    usePlayerStore.setState({
+      elements: [
+        {
+          id: "hero-clip",
+          domId: "hero",
+          tag: "div",
+          start: 2,
+          duration: 4,
+          track: 0,
+        },
+      ],
+    });
+
+    updateKeyframeCacheFromParsed([animation], "scene.html", "hero", {});
+
+    expect(JSON.stringify(cache().get("scene.html#hero"))).toBe(
+      '{"format":"percentage","keyframes":[{"percentage":25,"properties":{"x":0},"tweenPercentage":0,"propertyGroup":"position","animationId":"hero"},{"percentage":50,"properties":{"x":100},"ease":"power1.inOut","tweenPercentage":50,"propertyGroup":"position","animationId":"hero"},{"percentage":75,"properties":{"x":200},"tweenPercentage":100,"propertyGroup":"position","animationId":"hero"}],"easeEach":"power1.inOut"}',
+    );
+  });
+
   it("clears the bare key when the selected element no longer has keyframes", () => {
     // Element previously had keyframes, so a bare entry exists (writes set both).
     seed("index.html#box");
@@ -118,4 +210,87 @@ describe("updateKeyframeCacheFromParsed", () => {
     expect(cache().has("index.html#hero")).toBe(true);
     expect(cache().has("hero")).toBe(true);
   });
+
+  it("caches flat tweens as clip-relative start and end keyframes", () => {
+    const animation: GsapAnimation = {
+      id: "flat-box",
+      targetSelector: "#box",
+      method: "to",
+      position: 1,
+      properties: { x: 420 },
+      duration: 2,
+      resolvedStart: 1,
+      ease: "power2.out",
+      propertyGroup: "position",
+    };
+    usePlayerStore.setState({
+      elements: [{ id: "box-clip", domId: "box", tag: "div", start: 1, duration: 2, track: 0 }],
+    });
+
+    updateKeyframeCacheFromParsed([animation], "scene.html", "box", {});
+
+    expect(cache().get("scene.html#box")).toEqual({
+      format: "percentage",
+      keyframes: [
+        {
+          percentage: 0,
+          properties: { x: 0 },
+          tweenPercentage: 0,
+          propertyGroup: "position",
+          animationId: "flat-box",
+        },
+        {
+          percentage: 100,
+          properties: { x: 420 },
+          ease: "power2.out",
+          tweenPercentage: 100,
+          propertyGroup: "position",
+          animationId: "flat-box",
+        },
+      ],
+    });
+    expect(usePlayerStore.getState().gsapAnimations.get("scene.html#box")).toEqual([animation]);
+  });
+
+  it("records an ungrouped tween in gsapAnimations too, so the two stores agree", () => {
+    // `{ x, opacity }` spans two property groups, so the parser leaves
+    // propertyGroup undefined. Skipping it here used to cache diamonds with no
+    // source animation behind them: the collapsed row drew keyframes the
+    // expanded lanes could not render.
+    const animation: GsapAnimation = {
+      id: "mixed-box",
+      targetSelector: "#box",
+      method: "to",
+      position: 0,
+      properties: { x: 100, opacity: 0 },
+      duration: 1,
+      resolvedStart: 0,
+    };
+    usePlayerStore.setState({
+      elements: [{ id: "box-clip", domId: "box", tag: "div", start: 0, duration: 1, track: 0 }],
+    });
+
+    updateKeyframeCacheFromParsed([animation], "scene.html", "box", {});
+
+    expect(cache().has("scene.html#box")).toBe(true);
+    expect(usePlayerStore.getState().gsapAnimations.get("scene.html#box")).toEqual([animation]);
+  });
+
+  it("does not cache a flat tween without animatable numeric properties", () => {
+    const animation: GsapAnimation = {
+      id: "flat-box",
+      targetSelector: "#box",
+      method: "to",
+      position: 0,
+      properties: { backgroundColor: "#fff" },
+      duration: 1,
+      propertyGroup: "visual",
+    };
+
+    updateKeyframeCacheFromParsed([animation], "scene.html", "box", {});
+
+    expect(cache().has("scene.html#box")).toBe(false);
+    expect(cache().has("box")).toBe(false);
+    expect(usePlayerStore.getState().gsapAnimations.has("scene.html#box")).toBe(false);
+  });
 });

package/src/hooks/gsapKeyframeCacheHelpers.ts

@@ -4,7 +4,8 @@
  */
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import { usePlayerStore, type KeyframeCacheEntry } from "../player/store/playerStore";
-import { toAbsoluteTime } from "./gsapShared";
+import { idFromSelector, toClipKeyframes } from "./gsapShared";
+import { deduplicateKeyframes, synthesizeFlatTweenKeyframes } from "./gsapTweenSynth";
 
 export function updateKeyframeCacheFromParsed(
   animations: GsapAnimation[],
@@ -15,57 +16,52 @@ export function updateKeyframeCacheFromParsed(
   const { setKeyframeCache, elements } = usePlayerStore.getState();
   const idsWithKeyframes = new Set<string>();
   const merged = new Map<string, KeyframeCacheEntry>();
+  const sourceAnimations = new Map<string, GsapAnimation[]>();
   for (const anim of animations) {
-    const id = anim.targetSelector.match(/^#([\w-]+)/)?.[1];
-    if (!id || !anim.keyframes) continue;
+    const id = idFromSelector(anim.targetSelector);
+    const kfSource =
+      anim.keyframes?.keyframes ?? synthesizeFlatTweenKeyframes(anim)?.keyframes ?? [];
+    if (!id || kfSource.length === 0) continue;
     idsWithKeyframes.add(id);
+    // Every tween that fed keyframeCache also lands in gsapAnimations, group or
+    // not: a mixed-group tween (`{ x, opacity }` classifies to undefined) used to
+    // cache diamonds with no source animation behind them, so the collapsed row
+    // drew keyframes the expanded lanes couldn't render. Lane consumers do the
+    // group filtering themselves (animationContributesLane).
+    sourceAnimations.set(id, [...(sourceAnimations.get(id) ?? []), anim]);
 
     // Convert tween-relative percentages to clip-relative so diamonds
     // render at the correct position within the timeline clip.
-    const tweenPos = anim.resolvedStart ?? (typeof anim.position === "number" ? anim.position : 0);
-    const tweenDur = anim.duration ?? 1;
     const timelineEl = elements.find(
       (el) => el.domId === id || (el.key ?? el.id) === `${targetPath}#${id}`,
     );
-    const elStart = timelineEl?.start ?? 0;
-    const elDuration = timelineEl?.duration ?? 1;
-    const clipKeyframes = anim.keyframes.keyframes.map((kf) => {
-      const absTime = toAbsoluteTime(tweenPos, tweenDur, kf.percentage);
-      const clipPct =
-        elDuration > 0 ? Math.round(((absTime - elStart) / elDuration) * 1000) / 10 : kf.percentage;
-      return {
-        ...kf,
-        percentage: clipPct,
-        tweenPercentage: kf.percentage,
-        propertyGroup: anim.propertyGroup,
-      };
-    });
+    const clipKeyframes = toClipKeyframes(
+      kfSource,
+      anim,
+      timelineEl?.start ?? 0,
+      timelineEl?.duration ?? 1,
+    );
 
     const existing = merged.get(id);
     if (existing) {
-      const byPct = new Map<number, (typeof existing.keyframes)[0]>();
-      for (const kf of [...existing.keyframes, ...clipKeyframes]) {
-        const prev = byPct.get(kf.percentage);
-        if (prev) {
-          prev.properties = { ...prev.properties, ...kf.properties };
-          if (kf.ease) prev.ease = kf.ease;
-        } else {
-          byPct.set(kf.percentage, { ...kf, properties: { ...kf.properties } });
-        }
-      }
-      existing.keyframes = Array.from(byPct.values()).sort((a, b) => a.percentage - b.percentage);
+      // deduplicateKeyframes owns the same-% merge (including the easeAmbiguous
+      // flag downstream lanes read); a second copy of that rule here is how the
+      // two writers drift.
+      existing.keyframes = deduplicateKeyframes([...existing.keyframes, ...clipKeyframes]);
     } else {
-      merged.set(id, { ...anim.keyframes, keyframes: clipKeyframes });
+      merged.set(id, {
+        ...anim.keyframes,
+        format: anim.keyframes?.format ?? "percentage",
+        keyframes: clipKeyframes,
+      });
     }
   }
   for (const [id, entry] of merged) {
-    setKeyframeCache(`${targetPath}#${id}`, entry);
-    setKeyframeCache(id, entry);
-    if (targetPath !== "index.html") setKeyframeCache(`index.html#${id}`, entry);
+    for (const key of elementCacheKeys(targetPath, id)) setKeyframeCache(key, entry);
+    writeGsapAnimationsForElement(targetPath, id, sourceAnimations.get(id));
   }
   const targetId =
-    (mutation as { targetSelector?: string }).targetSelector?.match(/^#([\w-]+)/)?.[1] ??
-    selectionId;
+    idFromSelector((mutation as { targetSelector?: string }).targetSelector) ?? selectionId;
   if (targetId && !idsWithKeyframes.has(targetId)) {
     clearKeyframeCacheForElement(targetPath, targetId);
   }
@@ -84,40 +80,85 @@ export function updateKeyframeCacheFromParsed(
  * a new cache map and re-render every subscriber.
  */
 export function clearKeyframeCacheForElement(sourceFile: string, elementId: string): void {
-  const { keyframeCache, setKeyframeCache } = usePlayerStore.getState();
-  const keys =
-    sourceFile === "index.html"
-      ? [`index.html#${elementId}`, elementId]
-      : [`${sourceFile}#${elementId}`, `index.html#${elementId}`, elementId];
+  const { keyframeCache, setKeyframeCache, gsapAnimations, setGsapAnimations } =
+    usePlayerStore.getState();
+  const keys = elementCacheKeys(sourceFile, elementId);
   for (const key of keys) {
     if (keyframeCache.has(key)) setKeyframeCache(key, undefined);
+    if (gsapAnimations.has(key)) setGsapAnimations(key, undefined);
   }
 }
 
 /**
  * Clear every cached element of `sourceFile` before a full re-scan repopulates
- * it. Collects the element ids that currently have a prefixed or index.html
- * fallback key for the file and drops each through clearKeyframeCacheForElement
- * so the bare key goes too — an element whose keyframes were removed (and so is
- * absent from the re-scan) leaves no stale bare entry behind.
+ * it. Only the file's OWN prefixed keys name the ids to clear: every write sets
+ * the prefixed key (see elementCacheKeys), so the file's elements are all
+ * reachable that way, and clearKeyframeCacheForElement then takes the
+ * index.html alias and the bare key with them — an element whose keyframes were
+ * removed (and so is absent from the re-scan) leaves no stale bare entry
+ * behind. Reading the alias prefix here instead would collect ids owned by
+ * OTHER files, and several files re-scan concurrently, so this file's clear
+ * would wipe the entries a sibling file had just written.
  */
 export function clearKeyframeCacheForFile(sourceFile: string): void {
-  const { keyframeCache } = usePlayerStore.getState();
+  const { keyframeCache, gsapAnimations } = usePlayerStore.getState();
   const sfPrefix = `${sourceFile}#`;
-  const fallbackPrefix = "index.html#";
   const ids = new Set<string>();
-  for (const key of keyframeCache.keys()) {
-    const matchesFile =
-      key.startsWith(sfPrefix) || (sourceFile !== "index.html" && key.startsWith(fallbackPrefix));
-    if (!matchesFile) continue;
-    const hashIdx = key.indexOf("#");
-    if (hashIdx !== -1) ids.add(key.slice(hashIdx + 1));
+  for (const key of [...keyframeCache.keys(), ...gsapAnimations.keys()]) {
+    if (!key.startsWith(sfPrefix)) continue;
+    ids.add(key.slice(sfPrefix.length));
   }
   for (const id of ids) {
     clearKeyframeCacheForElement(sourceFile, id);
   }
 }
 
+/**
+ * Drop every cached element owned by a file that is no longer on screen. Each
+ * file only ever clears its OWN entries (see clearKeyframeCacheForFile), so
+ * switching composition left the previous composition's elements cached forever
+ * — 240 entries per switch on a 120-clip comp, in both keyframeCache and
+ * gsapAnimations, with nothing to evict them. Called once before a re-scan, with
+ * the full set of files that scan covers.
+ */
+export function pruneKeyframeCacheToFiles(files: readonly string[]): void {
+  const keep = new Set(files);
+  const { keyframeCache, gsapAnimations } = usePlayerStore.getState();
+  const stale = new Map<string, Set<string>>();
+  for (const key of [...keyframeCache.keys(), ...gsapAnimations.keys()]) {
+    const hash = key.indexOf("#");
+    // Bare-id aliases carry no owner; clearKeyframeCacheForElement takes them
+    // with their prefixed key, so skipping them here loses nothing.
+    if (hash < 0) continue;
+    const sourceFile = key.slice(0, hash);
+    if (keep.has(sourceFile)) continue;
+    const ids = stale.get(sourceFile) ?? new Set<string>();
+    ids.add(key.slice(hash + 1));
+    stale.set(sourceFile, ids);
+  }
+  for (const [sourceFile, ids] of stale) {
+    for (const id of ids) clearKeyframeCacheForElement(sourceFile, id);
+  }
+}
+
+/** Every cache key a write for this element sets, in read-preference order. */
+export function elementCacheKeys(sourceFile: string, elementId: string): string[] {
+  return sourceFile === "index.html"
+    ? [`index.html#${elementId}`, elementId]
+    : [`${sourceFile}#${elementId}`, `index.html#${elementId}`, elementId];
+}
+
+export function writeGsapAnimationsForElement(
+  sourceFile: string,
+  elementId: string,
+  animations: GsapAnimation[] | undefined,
+): void {
+  const { setGsapAnimations } = usePlayerStore.getState();
+  for (const key of elementCacheKeys(sourceFile, elementId)) {
+    setGsapAnimations(key, animations);
+  }
+}
+
 function buildCacheKey(sourceFile: string, elementId: string): string {
   return `${sourceFile}#${elementId}`;
 }

package/src/hooks/gsapRuntimeBridge.test.ts

@@ -280,3 +280,103 @@ describe("tryGsapDragIntercept — autoKeyframeEnabled toggle (#1808)", () => {
     expect(types).not.toContain("replace-with-keyframes");
   });
 });
+
+describe("tryGsapDragIntercept — motion paths", () => {
+  const motionPathAnim = {
+    id: "#puck-b-to-12170-position",
+    targetSelector: "#puck-b",
+    propertyGroup: "position",
+    method: "to",
+    position: 12.17,
+    resolvedStart: 12.17,
+    duration: 16.055,
+    ease: "power1.inOut",
+    properties: {},
+    keyframes: {
+      keyframes: [
+        { percentage: 0, properties: { x: -184, y: 326 } },
+        { percentage: 50, properties: { x: 416, y: 804 } },
+        { percentage: 100, properties: { x: 796, y: 237 } },
+      ],
+    },
+    arcPath: {
+      enabled: true,
+      autoRotate: false,
+      segments: [{ curviness: 1 }, { curviness: 1 }],
+    },
+  } as unknown as GsapAnimation;
+  const liveTween = {
+    targets: () => [{ id: "puck-b" }],
+    vars: { motionPath: { path: [] }, duration: 16.055 },
+    duration: () => 16.055,
+    startTime: () => 12.17,
+  };
+
+  async function dragMotionPath(activeKeyframePct: number | null) {
+    usePlayerStore.setState({
+      autoKeyframeEnabled: true,
+      activeKeyframePct,
+      currentTime: 15.9,
+    });
+    const commitMutation = vi.fn();
+    const handled = await tryGsapDragIntercept(
+      selection,
+      { x: -50, y: 30 },
+      [motionPathAnim],
+      fakeIframe("puck-b", [liveTween]),
+      commitMutation,
+    );
+    return { commitMutation, handled };
+  }
+
+  afterEach(() => {
+    usePlayerStore.setState({ activeKeyframePct: null });
+  });
+
+  it("creates a temporal keyframe at the exact playhead instead of redistributing path waypoints", async () => {
+    const { commitMutation, handled } = await dragMotionPath(null);
+
+    expect(handled).toBe(true);
+    expect(commitMutation).toHaveBeenCalledWith(
+      selection,
+      {
+        type: "replace-with-keyframes",
+        animationId: motionPathAnim.id,
+        targetSelector: "#puck-b",
+        position: 12.17,
+        duration: 16.055,
+        keyframes: [
+          { percentage: 0, properties: { x: -184, y: 326 } },
+          { percentage: 23.233, properties: { x: -50, y: 30 } },
+          { percentage: 50, properties: { x: 416, y: 804 } },
+          { percentage: 100, properties: { x: 796, y: 237 } },
+        ],
+        ease: "none",
+      },
+      expect.objectContaining({ label: "Move layer (new keyframe)", softReload: true }),
+    );
+    expect(commitMutation.mock.calls.map(([, mutation]) => mutation.type)).not.toContain(
+      "add-motion-path-point",
+    );
+  });
+
+  it("keeps an explicitly selected path waypoint as a spatial edit", async () => {
+    const { commitMutation, handled } = await dragMotionPath(50);
+
+    expect(handled).toBe(true);
+    expect(commitMutation).toHaveBeenCalledWith(
+      selection,
+      {
+        type: "update-motion-path-point",
+        animationId: motionPathAnim.id,
+        pointIndex: 1,
+        x: -50,
+        y: 30,
+      },
+      expect.objectContaining({ label: "Move layer (waypoint)", softReload: true }),
+    );
+    expect(commitMutation.mock.calls.map(([, mutation]) => mutation.type)).not.toContain(
+      "replace-with-keyframes",
+    );
+  });
+});

package/src/hooks/gsapScriptCommitHelpers.ts

@@ -2,12 +2,13 @@ import { findUnsafeDomPatchValues } from "@hyperframes/core/studio-api/finite-mu
 import type { DomEditSelection } from "../components/editor/domEditingTypes";
 
 export { PROPERTY_DEFAULTS } from "./gsapShared";
+import { idSelector } from "./gsapShared";
 
 export function ensureElementAddressable(selection: DomEditSelection): {
   selector: string;
   autoId?: string;
 } {
-  if (selection.id) return { selector: `#${selection.id}` };
+  if (selection.id) return { selector: idSelector(selection.id) };
   if (selection.selector) return { selector: selection.selector };
 
   const el = selection.element;
@@ -20,7 +21,7 @@ export function ensureElementAddressable(selection: DomEditSelection): {
     id = `${tag}-${n}`;
   }
   el.setAttribute("id", id);
-  return { selector: `#${id}`, autoId: id };
+  return { selector: idSelector(id), autoId: id };
 }
 
 export class GsapMutationHttpError extends Error {