@hyperframes/studio 0.7.79 → 0.7.80

package/src/hooks/gsapKeyframeCacheHelpers.ts

@@ -5,7 +5,52 @@
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import { usePlayerStore, type KeyframeCacheEntry } from "../player/store/playerStore";
 import { resolveClipTimingBasis, resolveSelectorElementIds, toClipKeyframes } from "./gsapShared";
-import { deduplicateKeyframes, synthesizeFlatTweenKeyframes } from "./gsapTweenSynth";
+import {
+  deduplicateKeyframes,
+  synthesizeFlatTweenKeyframes,
+  type MergeableKeyframe,
+} from "./gsapTweenSynth";
+
+/** Both cache maps mid-edit, before the single store publish. */
+export interface KeyframeCacheDraft {
+  keyframeCache: Map<string, KeyframeCacheEntry>;
+  gsapAnimations: Map<string, GsapAnimation[]>;
+}
+
+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) {
+    if (after.get(key) !== value) return false;
+  }
+  return true;
+}
+
+/**
+ * Every multi-key cache writer publishes through here: clone both maps once,
+ * let the caller edit the drafts, publish once. The per-key store setters turned
+ * one logical refresh into N notifications, and every subscriber that rendered
+ * in between saw a cache that was half the old file and half the new one. The
+ * identity check keeps an edit that changed nothing from allocating fresh maps
+ * and re-rendering every subscriber, which is the guard the per-key setters used
+ * to carry individually.
+ */
+export function publishKeyframeCache(edit: (draft: KeyframeCacheDraft) => void): void {
+  const { keyframeCache, gsapAnimations } = usePlayerStore.getState();
+  const draft: KeyframeCacheDraft = {
+    keyframeCache: new Map(keyframeCache),
+    gsapAnimations: new Map(gsapAnimations),
+  };
+  edit(draft);
+  if (
+    sameEntries(keyframeCache, draft.keyframeCache) &&
+    sameEntries(gsapAnimations, draft.gsapAnimations)
+  )
+    return;
+  usePlayerStore.setState({
+    keyframeCache: draft.keyframeCache,
+    gsapAnimations: draft.gsapAnimations,
+  });
+}
 
 export function updateKeyframeCacheFromParsed(
   animations: GsapAnimation[],
@@ -14,9 +59,13 @@ export function updateKeyframeCacheFromParsed(
   mutation: Record<string, unknown>,
   doc?: Document | null,
 ): void {
-  const { setKeyframeCache, elements, domClipChildren } = usePlayerStore.getState();
+  const { elements, domClipChildren } = usePlayerStore.getState();
   const idsWithKeyframes = new Set<string>();
-  const merged = new Map<string, KeyframeCacheEntry>();
+  // Attributed keyframes only: everything in here came from a parsed tween via
+  // toClipKeyframes, so the merge can rely on the source identity. It widens
+  // back into KeyframeCacheEntry on the way to the store, which also holds the
+  // runtime scan's unattributed keyframes.
+  const merged = new Map<string, KeyframeCacheEntry & { keyframes: MergeableKeyframe[] }>();
   const sourceAnimations = new Map<string, GsapAnimation[]>();
   for (const anim of animations) {
     const kfSource =
@@ -49,9 +98,9 @@ export function updateKeyframeCacheFromParsed(
 
       const existing = merged.get(id);
       if (existing) {
-        // 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.
+        // deduplicateKeyframes owns the same-% merge (including the colliding
+        // animation targets 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, {
@@ -62,15 +111,41 @@ export function updateKeyframeCacheFromParsed(
       }
     }
   }
-  for (const [id, entry] of merged) {
-    for (const key of elementCacheKeys(targetPath, id)) setKeyframeCache(key, entry);
-    writeGsapAnimationsForElement(targetPath, id, sourceAnimations.get(id));
-  }
   const mutationSelector = (mutation as { targetSelector?: string }).targetSelector;
   const mutated = mutationSelector ? resolveSelectorElementIds(mutationSelector, doc) : [];
   const targetIds = mutated.length > 0 ? mutated : selectionId ? [selectionId] : [];
-  for (const targetId of targetIds) {
-    if (!idsWithKeyframes.has(targetId)) clearKeyframeCacheForElement(targetPath, targetId);
+  publishKeyframeCache((draft) => {
+    for (const [id, entry] of merged) {
+      writeElementIntoDraft(draft, targetPath, id, entry, sourceAnimations.get(id));
+    }
+    for (const targetId of targetIds) {
+      if (!idsWithKeyframes.has(targetId)) deleteElementFromDraft(draft, targetPath, targetId);
+    }
+  });
+}
+
+function writeElementIntoDraft(
+  draft: KeyframeCacheDraft,
+  sourceFile: string,
+  elementId: string,
+  entry: KeyframeCacheEntry,
+  animations: GsapAnimation[] | undefined,
+): void {
+  for (const key of elementCacheKeys(sourceFile, elementId)) {
+    draft.keyframeCache.set(key, entry);
+    if (animations) draft.gsapAnimations.set(key, animations);
+    else draft.gsapAnimations.delete(key);
+  }
+}
+
+function deleteElementFromDraft(
+  draft: KeyframeCacheDraft,
+  sourceFile: string,
+  elementId: string,
+): void {
+  for (const key of elementCacheKeys(sourceFile, elementId)) {
+    draft.keyframeCache.delete(key);
+    draft.gsapAnimations.delete(key);
   }
 }
 
@@ -83,50 +158,37 @@ export function updateKeyframeCacheFromParsed(
  * preview overlay) fall back to the bare id when an element has no
  * source-prefixed key — so a clear that drops only the prefixed keys leaves the
  * bare entry behind and those readers keep showing keyframes the element no
- * longer has. Each delete is guarded by `has` so an absent key doesn't allocate
- * a new cache map and re-render every subscriber.
+ * longer has. publishKeyframeCache skips the store write entirely when none of
+ * the keys were present, so an absent element doesn't re-render every
+ * subscriber.
  */
 export function clearKeyframeCacheForElement(sourceFile: string, elementId: string): void {
-  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);
-  }
+  publishKeyframeCache((draft) => deleteElementFromDraft(draft, sourceFile, elementId));
 }
 
-/**
- * Clear every cached element of `sourceFile` before a full re-scan repopulates
- * 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, gsapAnimations } = usePlayerStore.getState();
+function cachedElementIdsForFile(
+  sourceFile: string,
+  keyframeCache: ReadonlyMap<string, KeyframeCacheEntry>,
+  gsapAnimations: ReadonlyMap<string, GsapAnimation[]>,
+): Set<string> {
   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));
   }
-  for (const id of ids) {
-    clearKeyframeCacheForElement(sourceFile, id);
-  }
+  return ids;
 }
 
 /**
  * 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
+ * file only ever writes its OWN prefixed entries (see elementCacheKeys), 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.
+ * (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, and it publishes once: the prune
+ * runs immediately before the atomic repopulate, so a per-element publish here
+ * would reintroduce the empty-cache flash that repopulate was made to avoid.
  */
 export function pruneKeyframeCacheToFiles(files: readonly string[]): void {
   const keep = new Set(files);
@@ -134,8 +196,8 @@ export function pruneKeyframeCacheToFiles(files: readonly string[]): void {
   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.
+    // Bare-id aliases carry no owner; deleteElementFromDraft 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;
@@ -143,9 +205,25 @@ export function pruneKeyframeCacheToFiles(files: readonly string[]): void {
     ids.add(key.slice(hash + 1));
     stale.set(sourceFile, ids);
   }
-  for (const [sourceFile, ids] of stale) {
-    for (const id of ids) clearKeyframeCacheForElement(sourceFile, id);
-  }
+  publishKeyframeCache((draft) => {
+    for (const [sourceFile, ids] of stale) {
+      for (const id of ids) deleteElementFromDraft(draft, sourceFile, id);
+    }
+  });
+}
+
+/**
+ * The source-scoped key that names one element across panels and the store
+ * (focused ease segment, keyframe cache reads). Four call sites built this
+ * string by hand and two of them omitted the index.html fallback, so an element
+ * with no sourceFile was addressed as `#box` by one panel and `index.html#box`
+ * by another and the two never matched. One builder keeps them on one key.
+ */
+export function scopedElementKey(element: {
+  sourceFile?: string | null;
+  id?: string | null;
+}): string {
+  return `${element.sourceFile || "index.html"}#${element.id}`;
 }
 
 /** Every cache key a write for this element sets, in read-preference order. */
@@ -155,15 +233,37 @@ export function elementCacheKeys(sourceFile: string, elementId: string): string[
     : [`${sourceFile}#${elementId}`, `index.html#${elementId}`, elementId];
 }
 
+/** Replace one file's complete cache snapshot with one atomic store publish. */
+export function replaceKeyframeCacheForFile(
+  sourceFile: string,
+  entries: ReadonlyMap<string, KeyframeCacheEntry>,
+  animationsByElement: ReadonlyMap<string, GsapAnimation[]>,
+): void {
+  publishKeyframeCache((draft) => {
+    for (const id of cachedElementIdsForFile(
+      sourceFile,
+      draft.keyframeCache,
+      draft.gsapAnimations,
+    )) {
+      deleteElementFromDraft(draft, sourceFile, id);
+    }
+    for (const [id, entry] of entries) {
+      writeElementIntoDraft(draft, sourceFile, id, entry, animationsByElement.get(id));
+    }
+  });
+}
+
 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);
-  }
+  publishKeyframeCache((draft) => {
+    for (const key of elementCacheKeys(sourceFile, elementId)) {
+      if (animations) draft.gsapAnimations.set(key, animations);
+      else draft.gsapAnimations.delete(key);
+    }
+  });
 }
 
 function buildCacheKey(sourceFile: string, elementId: string): string {

package/src/hooks/gsapTweenSynth.test.ts

@@ -54,31 +54,86 @@ describe("synthesizeFlatTweenKeyframes", () => {
   });
 });
 
-describe("deduplicateKeyframes ease ambiguity", () => {
-  it("flags a same-% collision from different animations (different eases)", () => {
+describe("deduplicateKeyframes colliding animation targets", () => {
+  it("records each animation's tween percentage in first-seen order", () => {
     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" },
+      {
+        percentage: 45,
+        tweenPercentage: 20,
+        properties: { x: 10 },
+        ease: "power2.in",
+        animationId: "#a-position",
+      },
+      {
+        percentage: 45,
+        tweenPercentage: 80,
+        properties: { opacity: 1 },
+        ease: "power2.out",
+        animationId: "#a-visual",
+      },
     ]);
     const kf = merged.find((k) => k.percentage === 45);
-    expect(kf?.easeAmbiguous).toBe(true);
+    expect(kf?.collidingAnimationTargets).toEqual([
+      { animationId: "#a-position", tweenPercentage: 20 },
+      { animationId: "#a-visual", tweenPercentage: 80 },
+    ]);
   });
 
-  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.
+  it("deduplicates three colliding animations while preserving first-seen order", () => {
     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" },
+      {
+        percentage: 45,
+        tweenPercentage: 20,
+        properties: { x: 10 },
+        ease: "power2.in",
+        animationId: "#a-position",
+      },
+      {
+        percentage: 45,
+        tweenPercentage: 80,
+        properties: { opacity: 1 },
+        ease: "power2.in",
+        animationId: "#a-visual",
+      },
+      {
+        percentage: 45,
+        tweenPercentage: 40,
+        properties: { y: 20 },
+        ease: "power2.out",
+        animationId: "#a-position",
+      },
+      {
+        percentage: 45,
+        tweenPercentage: 60,
+        properties: { scale: 2 },
+        ease: "power2.in",
+        animationId: "#a-scale",
+      },
+    ]);
+    expect(merged.find((k) => k.percentage === 45)?.collidingAnimationTargets).toEqual([
+      { animationId: "#a-position", tweenPercentage: 20 },
+      { animationId: "#a-visual", tweenPercentage: 80 },
+      { animationId: "#a-scale", tweenPercentage: 60 },
     ]);
-    expect(merged.find((k) => k.percentage === 45)?.easeAmbiguous).toBe(true);
   });
 
-  it("does not flag a same-% collision within a single animation", () => {
+  it("leaves the collision set undefined 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" },
+      {
+        percentage: 45,
+        tweenPercentage: 20,
+        properties: { x: 10 },
+        ease: "power2.in",
+        animationId: "#a-position",
+      },
+      {
+        percentage: 45,
+        tweenPercentage: 80,
+        properties: { y: 20 },
+        ease: "power2.out",
+        animationId: "#a-position",
+      },
     ]);
-    expect(merged.find((k) => k.percentage === 45)?.easeAmbiguous).toBeFalsy();
+    expect(merged.find((k) => k.percentage === 45)?.collidingAnimationTargets).toBeUndefined();
   });
 });

package/src/hooks/gsapTweenSynth.ts

@@ -1,7 +1,7 @@
 import type {
   GsapAnimation,
   GsapKeyframesData,
-  GsapPercentageKeyframe,
+  SourcedGsapPercentageKeyframe,
 } from "@hyperframes/core/gsap-parser";
 import { PROPERTY_DEFAULTS } from "./gsapShared";
 
@@ -22,33 +22,60 @@ export function isStaticPositionHold(anim: GsapAnimation): boolean {
   return propKeys.length > 0 && propKeys.every((k) => k === "x" || k === "y");
 }
 
-export function deduplicateKeyframes<
-  T extends GsapPercentageKeyframe & { animationId?: string; easeAmbiguous?: boolean },
->(keyframes: T[]): T[] {
+export interface AnimationKeyframeTarget {
+  animationId: string;
+  tweenPercentage: number;
+}
+
+function accumulateCollidingAnimationTargets(
+  keyframe: AnimationKeyframeTarget & {
+    collidingAnimationTargets?: AnimationKeyframeTarget[];
+  },
+  incoming: AnimationKeyframeTarget,
+): void {
+  const primaryId = keyframe.animationId;
+  // One tween meeting itself is not a collision. Both identity fields are
+  // required by the parameter types rather than guarded at runtime: a keyframe
+  // that arrives without them cannot be attributed to a tween at all, and an
+  // early return here would silently record no collision and let the inline
+  // ease button edit an arbitrary one of the tweens that met at this
+  // percentage. The compiler now refuses the incomplete keyframe instead.
+  if (primaryId === incoming.animationId) return;
+  const collisionTargets = keyframe.collidingAnimationTargets;
+  if (collisionTargets?.some((target) => target.animationId === incoming.animationId)) return;
+  keyframe.collidingAnimationTargets = [
+    ...(collisionTargets === undefined || collisionTargets.length === 0
+      ? [{ animationId: primaryId, tweenPercentage: keyframe.tweenPercentage }]
+      : collisionTargets),
+    { animationId: incoming.animationId, tweenPercentage: incoming.tweenPercentage },
+  ];
+}
+
+/**
+ * What a keyframe looks like once it has been attributed to its source tween
+ * and is ready to be merged with the other tweens landing on the same row. The
+ * runtime scan produces unattributed keyframes and they never reach a merge, so
+ * they are deliberately not this type.
+ */
+export type MergeableKeyframe = SourcedGsapPercentageKeyframe & {
+  propertyGroup?: string;
+  collidingAnimationTargets?: AnimationKeyframeTarget[];
+};
+
+export function deduplicateKeyframes<T extends MergeableKeyframe>(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 };
-      // 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;
+      accumulateCollidingAnimationTargets(existing, kf);
+      // Whichever tween iterated last used to win `ease`, so the merged keyframe
+      // carried an arbitrary one of the colliding curves. Readers that show a
+      // single curve (drag readouts, lane hints, the inline ease button) then
+      // displayed one belonging to a different animation than the one an edit
+      // targets. A collision means "no single ease", and dropping it is the only
+      // honest answer; collidingAnimationTargets still names every tween there.
+      if ((existing.collidingAnimationTargets?.length ?? 0) > 1) delete existing.ease;
       else if (kf.ease) existing.ease = kf.ease;
     } else {
       byPct.set(kf.percentage, { ...kf, properties: { ...kf.properties } });

package/src/hooks/keyframeCacheAstLoad.ts

@@ -6,16 +6,13 @@
 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 { replaceKeyframeCacheForFile } from "./gsapKeyframeCacheHelpers";
 import { resolveClipTimingBasis, resolveSelectorElementIds, toClipKeyframes } from "./gsapShared";
 import {
   deduplicateKeyframes,
   isStaticPositionHold,
   synthesizeFlatTweenKeyframes,
+  type MergeableKeyframe,
 } from "./gsapTweenSynth";
 
 export { resolveSelectorElementIds };
@@ -80,10 +77,8 @@ export async function populateKeyframeCacheFromAst(
 ): 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 mergedByElement = new Map<string, GsapKeyframesData<MergeableKeyframe>>();
   const sourceByElement = new Map<string, GsapAnimation[]>();
   for (const anim of parsed.animations) {
     if (anim.hasUnresolvedKeyframes) continue;
@@ -108,8 +103,5 @@ export async function populateKeyframeCacheFromAst(
       }
     }
   }
-  for (const [id, kfData] of mergedByElement) {
-    for (const key of elementCacheKeys(sf, id)) setKeyframeCache(key, kfData);
-    writeGsapAnimationsForElement(sf, id, sourceByElement.get(id));
-  }
+  replaceKeyframeCacheForFile(sf, mergedByElement, sourceByElement);
 }