@hyperframes/studio 0.7.75 → 0.7.77

package/src/hooks/gsapShared.ts

@@ -53,14 +53,87 @@ export function isInstantHold(animation: GsapAnimation): boolean {
  * Returns `#id` if the selection has an id, otherwise the raw selector,
  * or null if neither exists.
  */
+/**
+ * A CSS-valid selector for an element id. `#id` for a valid CSS identifier,
+ * otherwise an `[id="..."]` attribute selector. IDs that start with a digit
+ * (e.g. "01-hook-hero-word") make `#id` an invalid selector, so
+ * `document.querySelector("#01-...")` / GSAP's `querySelectorAll` throw a
+ * SyntaxError — which surfaces as a masked cross-origin "Script error." and
+ * crashes the preview the moment such a target is committed (e.g. dragging).
+ */
+// Conservative: matches only ids that are unquestionably safe as a `#id`
+// selector — ASCII identifier, starts with a letter/underscore (or a single
+// leading hyphen), no dots/colons/spaces/digits-first. Anything it rejects
+// (digit-leading like "01-hook-...", dots, spaces, non-ASCII, …) falls through
+// to the attribute selector below, which is always valid. It can only ever err
+// toward the safe form, never toward a `#id` that throws — and, unlike
+// `CSS.escape`, it needs no browser global (this runs in node tests too).
+const SAFE_HASH_ID = /^-?[A-Za-z_][\w-]*$/;
+
+/**
+ * How close (in tween-%) a playhead has to be to count as sitting ON an existing
+ * keyframe. Every "is there already a keyframe here?" test shares this: with two
+ * different tolerances in play, one path decided "no keyframe here, append one"
+ * while another decided "yes, edit that one", and a drag near a waypoint left two
+ * keyframes a fraction of a percent apart.
+ */
+export const KEYFRAME_PCT_MATCH = 1;
+
+export function idSelector(id: string): string {
+  // A `#id` selector is only valid for a CSS identifier. IDs that start with a
+  // digit (e.g. "01-hook-hero-word") make `document.querySelector("#01-...")` and
+  // GSAP's `querySelectorAll` throw a SyntaxError — surfacing as a masked
+  // cross-origin "Script error." that crashes the preview the moment such a
+  // target is committed (e.g. dragging the element). Address those via an
+  // attribute selector instead (quotes/backslashes escaped for the string).
+  return SAFE_HASH_ID.test(id) ? `#${id}` : `[id="${id.replace(/(["\\])/g, "\\$1")}"]`;
+}
+
+/**
+ * Inverse of {@link idSelector}: the element id a target selector addresses, or
+ * null for a selector that is not id-based (a class, a tag, a descendant path).
+ *
+ * Both shapes have to be read back, not just `#id`. Every writer emits through
+ * `idSelector`, so a digit-leading, dotted or otherwise CSS-unsafe id lands in
+ * the source as `[id="01-hook-hero"]`. A reader that only matched `#id` saw no
+ * id at all for those elements and skipped them — which is how the post-commit
+ * keyframe-cache refresh silently stopped running for exactly the ids
+ * `idSelector` was added to support.
+ */
+export function idFromSelector(selector: string | undefined | null): string | null {
+  if (!selector) return null;
+  const hash = selector.match(/^#([\w-]+)/);
+  if (hash) return hash[1] ?? null;
+  const attribute = selector.match(/^\[id="((?:\\.|[^"\\])*)"\]/);
+  if (!attribute) return null;
+  // Undo the quote/backslash escaping idSelector applies.
+  return (attribute[1] ?? "").replace(/\\(["\\])/g, "$1");
+}
+
 export function selectorFromSelection(selection: DomEditSelection): string | null {
-  if (selection.id) return `#${selection.id}`;
+  if (selection.id) return idSelector(selection.id);
   if (selection.selector) return selection.selector;
   return null;
 }
 
 // ── Percentage computation ────────────────────────────────────────────────────
 
+/**
+ * Resolve the timing basis used by editor keyframes. The timeline renders a
+ * duration-less tween across its owning clip, so mutations must use that same
+ * duration instead of silently falling back to GSAP's 0.5s default.
+ */
+export function resolveEditableTweenDuration(
+  animation: GsapAnimation,
+  selection: DomEditSelection,
+): number {
+  const clipDuration = Number.parseFloat(selection.dataAttributes?.duration ?? "");
+  return resolveTweenDuration(
+    animation,
+    Number.isFinite(clipDuration) && clipDuration > 0 ? clipDuration : 0.5,
+  );
+}
+
 /**
  * Compute the current playback percentage within an element's animation range.
  * Uses the animation's resolved timing if available, otherwise falls back to
@@ -73,7 +146,7 @@ export function computeElementPercentage(
 ): number {
   if (animation) {
     const start = resolveTweenStart(animation);
-    const duration = resolveTweenDuration(animation);
+    const duration = resolveEditableTweenDuration(animation, selection);
     if (duration <= 0) return 0;
     if (start !== null) {
       return absoluteToPercentage(currentTime, start, duration);
@@ -81,9 +154,7 @@ export function computeElementPercentage(
   }
   const elStart = Number.parseFloat(selection.dataAttributes?.start ?? "0") || 0;
   const elDuration = Number.parseFloat(selection.dataAttributes?.duration ?? "1") || 1;
-  return elDuration > 0
-    ? Math.max(0, Math.min(100, Math.round(((currentTime - elStart) / elDuration) * 1000) / 10))
-    : 0;
+  return absoluteToPercentage(currentTime, elStart, elDuration);
 }
 
 // ── Iframe accessors ──────────────────────────────────────────────────────────
@@ -118,6 +189,16 @@ export interface ParsedPercentageKeyframes {
   easeEach?: string;
 }
 
+function collectAnimatableKeyframeProperties(entry: object): Record<string, number | string> {
+  const properties: Record<string, number | string> = {};
+  for (const [property, value] of Object.entries(entry)) {
+    if (property === "ease") continue;
+    if (typeof value === "number") properties[property] = Math.round(value * 1000) / 1000;
+    else if (typeof value === "string") properties[property] = value;
+  }
+  return properties;
+}
+
 /**
  * Parse a GSAP percentage-keyframe object (`{ "0%": { x: 10 }, "100%": { x: 200 } }`)
  * into a sorted array of `{ percentage, properties }` entries.
@@ -146,12 +227,7 @@ export function parsePercentageKeyframes(
     steps.forEach((entry, i) => {
       if (!entry || typeof entry !== "object") return;
       const percentage = steps.length > 1 ? Math.round((i / (steps.length - 1)) * 1000) / 10 : 0;
-      const properties: Record<string, number | string> = {};
-      for (const [pk, pv] of Object.entries(entry as Record<string, unknown>)) {
-        if (pk === "ease") continue;
-        if (typeof pv === "number") properties[pk] = Math.round(pv * 1000) / 1000;
-        else if (typeof pv === "string") properties[pk] = pv;
-      }
+      const properties = collectAnimatableKeyframeProperties(entry);
       if (Object.keys(properties).length > 0) keyframes.push({ percentage, properties });
     });
     return keyframes.length > 0 ? { keyframes } : null;
@@ -165,12 +241,7 @@ export function parsePercentageKeyframes(
     const pctMatch = key.match(/^(\d+(?:\.\d+)?)%$/);
     if (!pctMatch || !val || typeof val !== "object") continue;
     const percentage = parseFloat(pctMatch[1]);
-    const properties: Record<string, number | string> = {};
-    for (const [pk, pv] of Object.entries(val as Record<string, unknown>)) {
-      if (pk === "ease") continue;
-      if (typeof pv === "number") properties[pk] = Math.round(pv * 1000) / 1000;
-      else if (typeof pv === "string") properties[pk] = pv;
-    }
+    const properties = collectAnimatableKeyframeProperties(val);
     if (Object.keys(properties).length > 0) {
       keyframes.push({ percentage, properties });
     }
@@ -187,3 +258,57 @@ export function parsePercentageKeyframes(
 export function toAbsoluteTime(tweenPos: number, tweenDur: number, percentage: number): number {
   return tweenPos + (percentage / 100) * tweenDur;
 }
+
+/**
+ * An absolute time as a percentage of a timeline clip, at the one precision every
+ * keyframe-cache writer must share. 0.001% keeps a beat-snapped keyframe centered
+ * on the beat dot, and because selection keys embed this number, a writer that
+ * rounds coarser would orphan a live selection the moment it rewrites the cache.
+ * A zero-length clip has no percentage to give, so the tween-% passes through.
+ */
+export function toClipPercentage(
+  absoluteTime: number,
+  clipStart: number,
+  clipDuration: number,
+  fallbackPercentage: number,
+): number {
+  if (clipDuration <= 0) return fallbackPercentage;
+  return Math.round(((absoluteTime - clipStart) / clipDuration) * 100000) / 1000;
+}
+
+/**
+ * One keyframe-cache row per tween keyframe: the percentage re-based onto the
+ * clip, the original tween percentage kept alongside it, and the animation
+ * identity every lane and selection key needs. Shared by the cache writers so
+ * they cannot drift in precision or in which identity fields they record.
+ */
+export function toClipKeyframes<T extends { percentage: number }>(
+  source: readonly T[],
+  anim: GsapAnimation,
+  clipStart: number,
+  clipDuration: number,
+): Array<
+  T & {
+    tweenPercentage: number;
+    propertyGroup: GsapAnimation["propertyGroup"];
+    animationId: string;
+  }
+> {
+  const tweenStart = anim.resolvedStart ?? (typeof anim.position === "number" ? anim.position : 0);
+  // A duration-less tween spans the clip, the same rule the edit paths use
+  // (resolveEditableTweenDuration). A fixed 1s here put its keyframes at a
+  // percentage no editor agreed with.
+  const tweenDuration = anim.duration ?? clipDuration;
+  return source.map((keyframe) => ({
+    ...keyframe,
+    percentage: toClipPercentage(
+      toAbsoluteTime(tweenStart, tweenDuration, keyframe.percentage),
+      clipStart,
+      clipDuration,
+      keyframe.percentage,
+    ),
+    tweenPercentage: keyframe.percentage,
+    propertyGroup: anim.propertyGroup,
+    animationId: anim.id,
+  }));
+}

package/src/hooks/gsapTweenSynth.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
-import { synthesizeFlatTweenKeyframes } from "./gsapTweenSynth";
+import { deduplicateKeyframes, synthesizeFlatTweenKeyframes } from "./gsapTweenSynth";
 
 function anim(overrides: Partial<GsapAnimation>): GsapAnimation {
   return {
@@ -53,3 +53,32 @@ describe("synthesizeFlatTweenKeyframes", () => {
     expect(out).not.toBeNull();
   });
 });
+
+describe("deduplicateKeyframes ease ambiguity", () => {
+  it("flags a same-% collision from different animations (different eases)", () => {
+    const merged = deduplicateKeyframes([
+      { percentage: 45, properties: { x: 10 }, ease: "power2.in", animationId: "#a-position" },
+      { percentage: 45, properties: { opacity: 1 }, ease: "power2.out", animationId: "#a-visual" },
+    ]);
+    const kf = merged.find((k) => k.percentage === 45);
+    expect(kf?.easeAmbiguous).toBe(true);
+  });
+
+  it("flags a cross-animation collision even when the raw eases match", () => {
+    // The button can still only target one arbitrary animation, and each may
+    // inherit a different easeEach/animation ease that raw comparison misses.
+    const merged = deduplicateKeyframes([
+      { percentage: 45, properties: { x: 10 }, ease: "power2.in", animationId: "#a-position" },
+      { percentage: 45, properties: { opacity: 1 }, ease: "power2.in", animationId: "#a-visual" },
+    ]);
+    expect(merged.find((k) => k.percentage === 45)?.easeAmbiguous).toBe(true);
+  });
+
+  it("does not flag a same-% collision within a single animation", () => {
+    const merged = deduplicateKeyframes([
+      { percentage: 45, properties: { x: 10 }, ease: "power2.in", animationId: "#a-position" },
+      { percentage: 45, properties: { y: 20 }, ease: "power2.out", animationId: "#a-position" },
+    ]);
+    expect(merged.find((k) => k.percentage === 45)?.easeAmbiguous).toBeFalsy();
+  });
+});

package/src/hooks/gsapTweenSynth.ts

@@ -5,15 +5,51 @@ import type {
 } from "@hyperframes/core/gsap-parser";
 import { PROPERTY_DEFAULTS } from "./gsapShared";
 
-export function deduplicateKeyframes(
-  keyframes: GsapPercentageKeyframe[],
-): GsapPercentageKeyframe[] {
-  const byPct = new Map<number, GsapPercentageKeyframe>();
+/**
+ * A static position hold (only x/y, no real motion) is a `set`, not a keyframe —
+ * it must not synthesize a diamond. Covers both `tl.set(...)` and the
+ * `tl.to({ duration: 0, immediateRender: true })` hold that remove-all-keyframes
+ * collapses to (otherwise shown as a stray 0% keyframe).
+ *
+ * Single owner: the collapsed keyframe cache and the expanded property lanes'
+ * `gsapAnimations` map MUST agree on it, or a hold draws a phantom expanded lane
+ * with no matching collapsed diamond.
+ */
+export function isStaticPositionHold(anim: GsapAnimation): boolean {
+  if (anim.keyframes) return false;
+  if (anim.method !== "set" && (anim.duration ?? 0) !== 0) return false;
+  const propKeys = Object.keys(anim.properties).filter((k) => k !== "immediateRender");
+  return propKeys.length > 0 && propKeys.every((k) => k === "x" || k === "y");
+}
+
+export function deduplicateKeyframes<
+  T extends GsapPercentageKeyframe & { animationId?: string; easeAmbiguous?: boolean },
+>(keyframes: T[]): T[] {
+  const byPct = new Map<number, T>();
   for (const kf of keyframes) {
     const existing = byPct.get(kf.percentage);
     if (existing) {
       existing.properties = { ...existing.properties, ...kf.properties };
-      if (kf.ease) existing.ease = kf.ease;
+      // Two DIFFERENT source animations with a keyframe at the same clip %: a
+      // single inline ease button can only target one of them, and which one is
+      // arbitrary (each may also inherit a different easeEach/animation ease, so
+      // comparing raw keyframe eases isn't enough). Flag it so the collapsed row
+      // hides the button there and the user edits per-lane instead.
+      if (
+        existing.animationId !== undefined &&
+        kf.animationId !== undefined &&
+        existing.animationId !== kf.animationId
+      ) {
+        existing.easeAmbiguous = true;
+      }
+      // Whichever tween iterated last used to win `ease`, so the merged
+      // keyframe carried an arbitrary one of the colliding curves. Readers that
+      // do not check easeAmbiguous (drag readouts, lane hints) then showed a
+      // curve belonging to a different animation than the one an edit targets.
+      // Drop it instead: ambiguous means "no single ease", and the flag is the
+      // only honest answer.
+      if (existing.easeAmbiguous) delete existing.ease;
+      else if (kf.ease) existing.ease = kf.ease;
     } else {
       byPct.set(kf.percentage, { ...kf, properties: { ...kf.properties } });
     }
@@ -41,29 +77,40 @@ export function synthesizeFlatTweenKeyframes(anim: GsapAnimation): GsapKeyframes
   const fromProps = anim.fromProperties;
   if (!toProps || Object.keys(toProps).length === 0) return null;
 
-  const startProps: Record<string, number | string> = {};
-  const endProps: Record<string, number | string> = {};
+  const rawStart: Record<string, number | string> = {};
+  const rawEnd: Record<string, number | string> = {};
 
   if (anim.method === "from") {
     for (const [k, v] of Object.entries(toProps)) {
-      startProps[k] = v;
-      endProps[k] = PROPERTY_DEFAULTS[k] ?? 0;
+      rawStart[k] = v;
+      rawEnd[k] = PROPERTY_DEFAULTS[k] ?? 0;
     }
   } else if (anim.method === "fromTo" && fromProps) {
-    Object.assign(startProps, fromProps);
-    Object.assign(endProps, toProps);
+    Object.assign(rawStart, fromProps);
+    Object.assign(rawEnd, toProps);
   } else {
     for (const [k, v] of Object.entries(toProps)) {
-      startProps[k] = PROPERTY_DEFAULTS[k] ?? 0;
-      endProps[k] = v;
+      rawStart[k] = PROPERTY_DEFAULTS[k] ?? 0;
+      rawEnd[k] = v;
     }
   }
 
+  // Only numeric props are keyframe-interpolatable — a flat tween of a
+  // non-numeric prop (e.g. backgroundColor: "#fff") can't be a 2-keyframe lane.
+  const numericKeys = Object.keys(rawEnd).filter(
+    (k) => typeof rawStart[k] === "number" && typeof rawEnd[k] === "number",
+  );
+  if (numericKeys.length === 0) return null;
+  const startProps = Object.fromEntries(numericKeys.map((k) => [k, rawStart[k]]));
+  const endProps = Object.fromEntries(numericKeys.map((k) => [k, rawEnd[k]]));
+
   return {
     format: "percentage",
     keyframes: [
       { percentage: 0, properties: startProps },
-      { percentage: 100, properties: endProps },
+      // Segment ease lives on the destination keyframe (Figma/AE model) so the
+      // lane + cache surface it; also kept data-level for useGsapTweenCache.
+      { percentage: 100, properties: endProps, ...(anim.ease ? { ease: anim.ease } : {}) },
     ],
     ...(anim.ease ? { ease: anim.ease } : {}),
   };

package/src/hooks/keyframeCacheAstLoad.ts

@@ -0,0 +1,181 @@
+/**
+ * Reading a composition file's GSAP tweens into the keyframe cache: fetch,
+ * selector -> element id resolution, and the clip-relative timing basis.
+ * Split from useGsapTweenCache to keep that file under the 600-line limit.
+ */
+import type { GsapAnimation, GsapKeyframesData, ParsedGsap } from "@hyperframes/core/gsap-parser";
+import { isStudioHoldSet } from "@hyperframes/core/gsap-parser";
+import { usePlayerStore } from "../player/store/playerStore";
+import {
+  clearKeyframeCacheForFile,
+  elementCacheKeys,
+  writeGsapAnimationsForElement,
+} from "./gsapKeyframeCacheHelpers";
+import { idFromSelector, toClipKeyframes } from "./gsapShared";
+import {
+  deduplicateKeyframes,
+  isStaticPositionHold,
+  synthesizeFlatTweenKeyframes,
+} from "./gsapTweenSynth";
+
+/**
+ * Resolve a tween's target selector to the ids of the element(s) it animates.
+ * A bare `#id` resolves directly; anything else (a class like `.dot`, a group
+ * `.a, .b`, or a descendant selector) is matched against the live preview DOM so
+ * class/selector tweens (e.g. `gsap.from(".dot", {stagger})`) attribute to every
+ * element they animate — not just one parsed from the string. Falls back to a
+ * leading `#id` when there's no DOM (so the cache still populates pre-iframe).
+ */
+// fallow-ignore-next-line complexity
+export function resolveSelectorElementIds(
+  selector: string,
+  doc: Document | null | undefined,
+): string[] {
+  // A whole-selector id match (either shape) addresses exactly one element.
+  const bareId = /^(#[\w-]+|\[id="(?:\\.|[^"\\])*"\])$/.test(selector)
+    ? idFromSelector(selector)
+    : null;
+  if (bareId) return [bareId];
+  if (!doc) {
+    const lead = idFromSelector(selector);
+    return lead ? [lead] : [];
+  }
+  const ids = new Set<string>();
+  for (const part of selector.split(",")) {
+    const sel = part.trim();
+    if (!sel) continue;
+    try {
+      for (const el of Array.from(doc.querySelectorAll(sel))) {
+        if (el.id) ids.add(el.id);
+      }
+    } catch {
+      const lead = idFromSelector(sel);
+      if (lead) ids.add(lead);
+    }
+  }
+  return Array.from(ids);
+}
+/**
+ * The slice of the parse response callers actually read. The endpoint returns
+ * the full `ParsedGsap` (preamble/postamble and all), but nothing downstream of
+ * this fetch touches the source-text fields, so the guard below only has to
+ * vouch for what gets used.
+ */
+type ParsedGsapAnimations = Pick<
+  ParsedGsap,
+  "animations" | "multipleTimelines" | "unsupportedTimelinePattern"
+>;
+
+/**
+ * A proxy, an error page, or a stale server can answer 200 with something that
+ * has no `animations` array — the case where the old blind cast crashed on
+ * `.animations.filter`.
+ */
+function hasAnimations(value: unknown): value is ParsedGsapAnimations {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "animations" in value &&
+    Array.isArray(value.animations)
+  );
+}
+
+export async function fetchParsedAnimations(
+  projectId: string,
+  sourceFile: string,
+): Promise<ParsedGsapAnimations | null> {
+  try {
+    const res = await fetch(
+      `/api/projects/${encodeURIComponent(projectId)}/gsap-animations/${encodeURIComponent(sourceFile)}`,
+      // Always re-read the freshly-parsed source; no per-call timestamp (which
+      // would defeat caching forever and is a deterministic-render no-no).
+      { cache: "no-store" },
+    );
+    if (!res.ok) return null;
+    const parsed: unknown = await res.json();
+    if (!hasAnimations(parsed)) return null;
+    // Studio-emitted pre-keyframe hold `set`s are an internal runtime detail (they
+    // hold an element's first keyframe before its tween). They must not surface as
+    // user animations — otherwise they pollute the keyframe cache / timeline diamonds.
+    return { ...parsed, animations: parsed.animations.filter((a) => !isStudioHoldSet(a)) };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Clip-relative timing basis for an element. Sub-composition internals (e.g. pills
+ * inside a scene) aren't timeline clips themselves — they're derived at expand time
+ * — so they're absent from `elements`. Without a basis, elDuration defaulted to 1
+ * and clip-relative keyframe percentages blew past 100% (rendering off the clip).
+ * Fall back to the sub-comp HOST's bounds, resolved via domClipChildren (the host's
+ * data-composition-src is stripped in the rendered DOM, so we can't query it).
+ */
+export function resolveClipTimingBasis(
+  elementId: string,
+  sourceFile: string,
+  elements: ReadonlyArray<{
+    domId?: string;
+    key?: string;
+    id: string;
+    start: number;
+    duration: number;
+  }>,
+  domClipChildren: ReadonlyArray<{ id: string; hostId: string }>,
+): { elStart: number; elDuration: number } {
+  const direct = elements.find(
+    (el) => el.domId === elementId || (el.key ?? el.id) === `${sourceFile}#${elementId}`,
+  );
+  if (direct) return { elStart: direct.start, elDuration: direct.duration };
+  const hostId = domClipChildren.find((c) => c.id === elementId)?.hostId;
+  const host = hostId
+    ? elements.find((el) => el.domId === hostId || (el.key ?? el.id) === `index.html#${hostId}`)
+    : undefined;
+  return { elStart: host?.start ?? 0, elDuration: host?.duration ?? 1 };
+}
+
+/**
+ * Read one composition file's tweens into the keyframe cache. Split out of the
+ * hook so the effect can run it per file without re-nesting the whole body.
+ */
+// fallow-ignore-next-line complexity
+export async function populateKeyframeCacheFromAst(
+  projectId: string,
+  sf: string,
+  doc: Document | null | undefined,
+): Promise<void> {
+  const parsed = await fetchParsedAnimations(projectId, sf);
+  if (!parsed) return;
+  const { setKeyframeCache } = usePlayerStore.getState();
+  clearKeyframeCacheForFile(sf);
+  const { elements, domClipChildren } = usePlayerStore.getState();
+  const mergedByElement = new Map<string, GsapKeyframesData>();
+  const sourceByElement = new Map<string, GsapAnimation[]>();
+  for (const anim of parsed.animations) {
+    if (anim.hasUnresolvedKeyframes) continue;
+    if (isStaticPositionHold(anim)) continue;
+    const kfData = anim.keyframes ?? synthesizeFlatTweenKeyframes(anim);
+    if (!kfData) continue;
+    // Attribute the tween to every element it animates (handles class /
+    // group / descendant selectors, not just `#id`).
+    for (const id of resolveSelectorElementIds(anim.targetSelector, doc)) {
+      // kfData is already resolved (real keyframes OR a synthesized flat
+      // tween), so a flat tween joins the store like a keyframed one. No
+      // property-group filter: this map must cover every tween the cache
+      // below records, or expanded lanes have nothing to render.
+      sourceByElement.set(id, [...(sourceByElement.get(id) ?? []), anim]);
+      const { elStart, elDuration } = resolveClipTimingBasis(id, sf, elements, domClipChildren);
+      const clipKeyframes = toClipKeyframes(kfData.keyframes, anim, elStart, elDuration);
+      const existing = mergedByElement.get(id);
+      if (existing) {
+        existing.keyframes = deduplicateKeyframes([...existing.keyframes, ...clipKeyframes]);
+      } else {
+        mergedByElement.set(id, { ...kfData, keyframes: clipKeyframes });
+      }
+    }
+  }
+  for (const [id, kfData] of mergedByElement) {
+    for (const key of elementCacheKeys(sf, id)) setKeyframeCache(key, kfData);
+    writeGsapAnimationsForElement(sf, id, sourceByElement.get(id));
+  }
+}

package/src/hooks/timelineEditingHelpers.test.ts

@@ -12,6 +12,7 @@ import {
 import type { TimelineElement } from "../player/store/playerStore";
 import { usePlayerStore } from "../player/store/playerStore";
 import type { CommitMutationOptions } from "./gsapScriptCommitTypes";
+import { timelineKeyframeSelectionKey } from "../player/components/timelineKeyframeIdentity";
 
 afterEach(() => {
   usePlayerStore.getState().reset();
@@ -342,4 +343,83 @@ describe("deleteSelectedKeyframes", () => {
     expect(options[1]).not.toHaveProperty("softReload");
     expect(options[2]).not.toHaveProperty("skipReload");
   });
+
+  it("deletes two expanded lanes through their own animation and tween percentages", () => {
+    usePlayerStore.setState({
+      selectedElementId: "card",
+      selectedKeyframes: new Set([
+        timelineKeyframeSelectionKey("card", {
+          percentage: 30,
+          tweenPercentage: 20,
+          propertyGroup: "position",
+          animationId: "card-position",
+        }),
+        timelineKeyframeSelectionKey("card", {
+          percentage: 70,
+          tweenPercentage: 80,
+          propertyGroup: "visual",
+          animationId: "card-visual",
+        }),
+      ]),
+    });
+    const handleGsapRemoveKeyframe =
+      vi.fn<(animId: string, pct: number, options?: Partial<CommitMutationOptions>) => void>();
+
+    deleteSelectedKeyframes({
+      selectedGsapAnimations: [
+        { id: "card-position", keyframes: {} },
+        { id: "card-visual", keyframes: {} },
+      ],
+      handleGsapRemoveKeyframe,
+    });
+
+    expect(handleGsapRemoveKeyframe).toHaveBeenCalledTimes(2);
+    expect(
+      handleGsapRemoveKeyframe.mock.calls.map(([animationId, percentage]) => [
+        animationId,
+        percentage,
+      ]),
+    ).toEqual([
+      ["card-position", 20],
+      ["card-visual", 80],
+    ]);
+    expect(handleGsapRemoveKeyframe.mock.calls[0]?.[2]).toEqual(
+      expect.objectContaining({ skipReload: true }),
+    );
+    expect(handleGsapRemoveKeyframe.mock.calls[1]?.[2]).toEqual(
+      expect.objectContaining({ softReload: true }),
+    );
+  });
+
+  it("drops keyframes that belong to other elements", () => {
+    // A stale selection from a previously active element must not delete
+    // anything on the element that is active now.
+    usePlayerStore.setState({
+      selectedElementId: "card",
+      selectedKeyframes: new Set([
+        timelineKeyframeSelectionKey("card", {
+          percentage: 30,
+          tweenPercentage: 20,
+          propertyGroup: "position",
+          animationId: "card-position",
+        }),
+        timelineKeyframeSelectionKey("other", {
+          percentage: 70,
+          tweenPercentage: 80,
+          propertyGroup: "position",
+          animationId: "card-position",
+        }),
+      ]),
+    });
+    const handleGsapRemoveKeyframe =
+      vi.fn<(animId: string, pct: number, options?: Partial<CommitMutationOptions>) => void>();
+
+    deleteSelectedKeyframes({
+      selectedGsapAnimations: [{ id: "card-position", keyframes: {} }],
+      handleGsapRemoveKeyframe,
+    });
+
+    expect(handleGsapRemoveKeyframe).toHaveBeenCalledTimes(1);
+    expect(handleGsapRemoveKeyframe.mock.calls[0]?.[1]).toBe(20);
+  });
 });

package/src/hooks/timelineMoveAdapter.ts

@@ -4,7 +4,7 @@ import type {
   TimelineGroupMoveChange,
 } from "./useTimelineGroupEditing";
 
-interface MoveEdit {
+export interface TimelineMoveEdit {
   element: TimelineElement;
   updates: Pick<TimelineElement, "start" | "track">;
 }
@@ -18,8 +18,15 @@ interface AtomicMoveDeps {
 
 export type TimelineMoveOperation = "timing" | "lane-reorder" | "track-insert";
 
+export type TimelineMoveEditsHandler = (
+  edits: TimelineMoveEdit[],
+  coalesceKey?: string,
+  operation?: TimelineMoveOperation,
+  coalesceMs?: number,
+) => Promise<void>;
+
 export function persistTimelineMoveEditsAtomically(
-  edits: MoveEdit[],
+  edits: TimelineMoveEdit[],
   coalesceKey: string | undefined,
   operation: TimelineMoveOperation,
   deps: AtomicMoveDeps,

package/src/hooks/useDomEditWiring.ts

@@ -92,14 +92,14 @@ export interface UseDomEditWiringParams {
     animId: string,
     fromPercentage: number,
     toPercentage: number,
-  ) => void;
+  ) => Promise<boolean>;
   resizeKeyframedTween: (
     sel: DomEditSelection,
     animId: string,
     position: number,
     duration: number,
     pctRemap: Array<{ from: number; to: number }>,
-  ) => void;
+  ) => Promise<boolean>;
   convertToKeyframes: (
     sel: DomEditSelection,
     animId: string,