Files
hyperframes/packages/studio/src/hooks/useGsapTweenCache.ts
T
Miguel Ángel db12b3e022 fix(studio): place GSAP step lists and duration-less tweens where GSAP plays them (#5024)
* fix(studio): place GSAP step lists and duration-less tweens where GSAP plays them

* refactor(studio): drop narrated comments and unnest the extend clamp

* fix(studio): match keyframes in time, resolve partial step timing, start readout from prior tween

* fix(studio): time step-list keyframes from the parts' last end and format

* refactor(studio): trim comments to the package's comment share

* fix(parsers): apply timeline defaults as GSAP does to step lists and motion paths

* fix(studio): keep GSAP's ease for motion paths with keyframes and read finished tweens

* refactor(studio): read a live motion path in its own step

* refactor(parsers): leave step-list timing to its one owner and skip timeline defaults there

* refactor(studio): move the live motion-path read into its own module

* test(parsers): pin an unresolved length for a step list stretched by a variable duration

* fix(studio): time keyframes linearly under an outer ease that overshoots or steps

* fix(studio): time a converted expression-duration tween from its live tween, and pin no rewrite
2026-10-05 02:44:49 +00:00

376 lines
16 KiB
TypeScript

import { useEffect, useMemo, useRef, useState, useCallback } from "react";
import type { GsapAnimation, GsapKeyframesData } from "@hyperframes/core/gsap-parser";
import { usePlayerStore } from "../player/store/playerStore";
import type { DomEditSelection } from "../components/editor/domEditingTypes";
import { findPreviewNode } from "../components/editor/domEditingElement";
import { readRuntimeKeyframes, scanAllRuntimeKeyframes } from "./gsapRuntimeBridge";
import {
clearKeyframeCacheForElement,
elementCacheKeys,
pruneKeyframeCacheToFiles,
publishKeyframeCache,
writeGsapAnimationsForElement,
} from "./gsapKeyframeCacheHelpers";
import { resolveClipTimingBasis, toClipKeyframes } from "./gsapShared";
import {
deduplicateKeyframes,
isStaticPositionHold,
synthesizeFlatTweenKeyframes,
type MergeableKeyframe,
} from "./gsapTweenSynth";
import { fetchParsedAnimations, populateKeyframeCacheFromAst } from "./keyframeCacheAstLoad";
import { getAnimationsForElement } from "./gsapElementMatch";
// Re-exported so callers keep importing the GSAP cache surface from one module.
export { resolveClipTimingBasis } from "./gsapShared";
export { fetchParsedAnimations, resolveSelectorElementIds } from "./keyframeCacheAstLoad";
export { getAnimationsForElement } from "./gsapElementMatch";
export function useGsapAnimationsForElement(
projectId: string | null,
sourceFile: string,
target: DomEditSelection | null,
version: number,
iframeRef?: React.RefObject<HTMLIFrameElement | null>,
): {
animations: GsapAnimation[];
multipleTimelines: boolean;
unsupportedTimelinePattern: boolean;
} {
const [allAnimations, setAllAnimations] = useState<GsapAnimation[]>([]);
const [multipleTimelines, setMultipleTimelines] = useState(false);
const [unsupportedTimelinePattern, setUnsupportedTimelinePattern] = useState(false);
const lastFetchKeyRef = useRef("");
// Re-run the per-element cache populate when sub-comp DOM children appear, so a
// sub-comp element gets its host-relative keyframe percentages (not elDuration=1).
const domClipChildrenKey = usePlayerStore((s) =>
s.domClipChildren.map((c) => `${c.id}<${c.hostId}`).join("|"),
);
useEffect(() => {
const targetKey = target?.id ?? target?.selector ?? "";
const fetchKey = `${projectId}:${sourceFile}:${version}:${targetKey}`;
if (fetchKey === lastFetchKeyRef.current) return;
lastFetchKeyRef.current = fetchKey;
if (!projectId) {
setAllAnimations([]);
setMultipleTimelines(false);
setUnsupportedTimelinePattern(false);
return;
}
let cancelled = false;
fetchParsedAnimations(projectId, sourceFile).then((parsed) => {
if (cancelled) {
return;
}
if (!parsed) {
setAllAnimations([]);
setMultipleTimelines(false);
setUnsupportedTimelinePattern(false);
return;
}
setAllAnimations(parsed.animations);
setMultipleTimelines(parsed.multipleTimelines === true);
setUnsupportedTimelinePattern(parsed.unsupportedTimelinePattern === true);
});
return () => {
cancelled = true;
};
}, [projectId, sourceFile, version, target?.id, target?.selector]);
const targetId = target?.id ?? null;
const targetSelector = target?.selector ?? null;
const rawAnimations = useMemo(() => {
if (!targetId && !targetSelector) return [];
// Resolve the live element so class / descendant tweens (e.g.
// gsap.from(".dot", {stagger})) attribute to every matching element, not
// just the one whose exact selector equals the tween's. `version` re-runs
// this after composition reloads.
const element = target ? findPreviewNode(iframeRef?.current?.contentDocument, target) : null;
return getAnimationsForElement(
allAnimations,
{ id: targetId, selector: targetSelector },
element,
);
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [allAnimations, target, version, iframeRef]);
// fallow-ignore-next-line complexity
const animations = useMemo(() => {
const iframe = iframeRef?.current;
let result = rawAnimations;
// Enrich animations with unresolved keyframes from runtime
if (iframe) {
result = result.map((anim) => {
if (!anim.hasUnresolvedKeyframes || anim.keyframes) return anim;
const runtime = readRuntimeKeyframes(iframe, anim.targetSelector);
if (!runtime) return anim;
return {
...anim,
keyframes: {
format: "percentage" as const,
keyframes: runtime.keyframes,
...(runtime.easeEach ? { easeEach: runtime.easeEach } : {}),
},
...(runtime.arcPath ? { arcPath: runtime.arcPath } : {}),
};
});
}
// Match unresolved-selector animations from the parser to runtime tweens
// targeting this element. This handles fully dynamic code (loop with variable selector).
if (iframe && targetId && result.length === 0) {
const unresolvedAnims = allAnimations.filter((a) => a.hasUnresolvedSelector);
if (unresolvedAnims.length > 0) {
const runtimeData = readRuntimeKeyframes(iframe, `#${targetId}`);
if (runtimeData) {
const scanned = scanAllRuntimeKeyframes(iframe);
const runtimeEntry = scanned.get(targetId);
if (runtimeEntry) {
// Find which unresolved animation index matches this element
// by correlating parser order with runtime tween order
const runtimeIds = Array.from(scanned.keys());
const runtimeIndex = runtimeIds.indexOf(targetId);
const matchedAnim =
runtimeIndex >= 0 && runtimeIndex < unresolvedAnims.length
? unresolvedAnims[runtimeIndex]
: unresolvedAnims[0];
if (matchedAnim) {
result = [
{
...matchedAnim,
targetSelector: `#${targetId}`,
keyframes: {
format: "percentage" as const,
keyframes: runtimeEntry.keyframes,
...(runtimeEntry.easeEach ? { easeEach: runtimeEntry.easeEach } : {}),
},
...(runtimeEntry.arcPath ? { arcPath: runtimeEntry.arcPath } : {}),
},
];
}
}
}
}
}
return result;
}, [rawAnimations, allAnimations, iframeRef, targetId]);
// Populate keyframe cache for the selected element.
// Key format must match timeline element keys: "sourceFile#domId".
// Merges keyframes from ALL animations targeting this element and synthesizes
// flat tweens so the cache is never downgraded vs the bulk populate.
const elementId = target?.id ?? null;
// fallow-ignore-next-line complexity
useEffect(() => {
if (!elementId) return;
// Same admission rule as the keyframe cache below (hold skip included) and
// no property-group filter: the two stores must agree, or a hold draws an
// expanded property lane with no collapsed diamond behind it and an
// ungrouped tween draws diamonds with no lane source.
const sourceAnimations = animations.filter(
(animation) =>
!isStaticPositionHold(animation) &&
(animation.keyframes || synthesizeFlatTweenKeyframes(animation)),
);
if (sourceAnimations.length > 0)
writeGsapAnimationsForElement(sourceFile, elementId, sourceAnimations);
// Resolve the element's time range from the player store so we can
// convert tween-relative keyframe percentages to clip-relative ones.
const { elements, domClipChildren } = usePlayerStore.getState();
const { elStart, elDuration } = resolveClipTimingBasis(
elementId,
sourceFile,
elements,
domClipChildren,
);
const allKeyframes: MergeableKeyframe[] = [];
let format: GsapKeyframesData["format"] = "percentage";
let ease: string | undefined;
let easeEach: string | undefined;
for (const anim of animations) {
if (isStaticPositionHold(anim)) continue;
const kf = anim.keyframes ?? synthesizeFlatTweenKeyframes(anim);
if (!kf) continue;
allKeyframes.push(...toClipKeyframes(kf.keyframes, anim, elStart, elDuration));
format = kf.format;
if (kf.ease) ease = kf.ease;
if (kf.easeEach) easeEach = kf.easeEach;
}
if (allKeyframes.length === 0) {
// The per-element parsed-animation match can transiently miss class /
// selector tweens (e.g. `.dot`) that the file-wide populate or runtime
// scan already cached. Only clear when no source cached this element —
// otherwise selecting it would wipe its diamonds.
const { keyframeCache } = usePlayerStore.getState();
const hasCached = elementCacheKeys(sourceFile, elementId).some((key) =>
keyframeCache.has(key),
);
if (!hasCached) clearKeyframeCacheForElement(sourceFile, elementId);
return;
}
const dedupedKeyframes = deduplicateKeyframes(allKeyframes);
const merged: GsapKeyframesData = {
format,
keyframes: dedupedKeyframes,
...(ease ? { ease } : {}),
...(easeEach ? { easeEach } : {}),
};
// elementCacheKeys owns the key-variant list every writer sets (prefixed,
// index.html fallback, bare id). Building it by hand here is what let this
// site drift: it omitted the fallback key, and it wrote the bare id without
// the string coercion that keeps prune from throwing on a non-string. All
// keys land in one publish: a reader that woke between two separate writes
// saw the prefixed key updated and the bare one still stale.
publishKeyframeCache((draft) => {
for (const key of elementCacheKeys(sourceFile, elementId)) {
draft.keyframeCache.set(key, merged);
}
});
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [elementId, sourceFile, animations, domClipChildrenKey]);
return { animations, multipleTimelines, unsupportedTimelinePattern };
}
export function useGsapCacheVersion() {
const [version, setVersion] = useState(0);
const bump = useCallback(() => setVersion((v) => v + 1), []);
return { version, bump };
}
/**
* Fetch GSAP animations for a file and populate the keyframe cache for all
* elements. Called from the Timeline component so diamonds show without
* requiring a selection.
*/
export function usePopulateKeyframeCacheForFile(
projectId: string | null,
sourceFile: string,
version: number,
iframeRef?: React.RefObject<HTMLIFrameElement | null>,
): void {
const elementCount = usePlayerStore((s) => s.elements.length);
// Every sub-composition file the timeline shows rows for. The cache is loaded
// for all of them up front, so keyframe lanes are populated on open instead of
// only once a clip from that file is selected (which is what switches
// `sourceFile`). Only files reachable from the store's elements are covered;
// a composition nested inside another still loads on first selection.
const compositionSrcKey = usePlayerStore((s) =>
Array.from(new Set(s.elements.map((el) => el.compositionSrc).filter((src) => !!src)))
.sort()
.join("|"),
);
// Re-run when sub-comp DOM children appear (they supply the host bounds the
// clip-relative keyframe percentages are computed against; without this the
// cache is computed once before they exist and the percentages stay wrong).
const domClipChildrenKey = usePlayerStore((s) =>
s.domClipChildren.map((c) => `${c.id}<${c.hostId}`).join("|"),
);
const loadedRef = useRef<{ dataKey: string; files: Set<string> }>({
dataKey: "",
files: new Set(),
});
const runtimeScanDoneRef = useRef("");
useEffect(() => {
const dataKey = `kf-cache:${projectId}:${version}:${elementCount}:${domClipChildrenKey}:${compositionSrcKey}`;
if (!projectId) return;
// The active file first: it owns the selection, and each file clears only
// its own cache entries, so the order just decides who writes the bare
// `id` alias last.
const files = Array.from(
new Set([sourceFile, ...(compositionSrcKey ? compositionSrcKey.split("|") : [])]),
);
const sameData = loadedRef.current.dataKey === dataKey;
const stale = sameData ? files.filter((sf) => !loadedRef.current.files.has(sf)) : files;
const covered = sameData ? new Set([...loadedRef.current.files, ...files]) : new Set(files);
loadedRef.current = { dataKey, files: covered };
// Everything the previous scan cached for a file this one no longer covers
// (the composition just switched away from) has no owner left to clear it.
if (!sameData) pruneKeyframeCacheToFiles(files);
if (stale.length === 0) return;
runtimeScanDoneRef.current = "";
const doc = iframeRef?.current?.contentDocument;
for (const sf of stale) {
void populateKeyframeCacheFromAst(projectId, sf, doc).then((loaded) => {
if (!loaded && loadedRef.current.dataKey === dataKey) loadedRef.current.files.delete(sf);
});
}
// elementCount is in the deps because new timeline elements (e.g. after a
// sub-composition expand) need their keyframe cache populated immediately;
// without it the effect won't re-run when elements appear/disappear.
// iframeRef is read for DOM selector resolution but intentionally not a dep
// (it's a stable ref; the separate runtime-scan effect owns iframe timing).
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [projectId, sourceFile, version, elementCount, domClipChildrenKey, compositionSrcKey]);
// Separate effect for runtime keyframe discovery — polls until the iframe
// has loaded GSAP timelines, independent of the AST fetch lifecycle.
useEffect(() => {
if (!projectId) return;
const sf = sourceFile;
let attempts = 0;
const maxAttempts = 10;
// fallow-ignore-next-line complexity
const tryRuntimeScan = () => {
if (runtimeScanDoneRef.current === `kf-cache:${projectId}:${sf}:${version}`) return true;
const iframe = iframeRef?.current;
if (!iframe) return false;
// Clip dims per element so the scan converts tween-relative keyframes to
// clip-relative (matching the static path) instead of timeline-relative.
const clipById = new Map<string, { start: number; duration: number }>();
for (const el of usePlayerStore.getState().elements) {
if (el.domId) clipById.set(el.domId, { start: el.start, duration: el.duration });
}
const scanned = scanAllRuntimeKeyframes(iframe, clipById);
if (scanned.size === 0) return false;
// One publish for the whole scan: a scan of a 120-clip composition used to
// emit up to three store notifications per element, and every subscriber
// in between re-rendered against a cache only partly filled in.
publishKeyframeCache((draft) => {
for (const [id, data] of scanned) {
const keys = elementCacheKeys(sf, id);
if (keys.some((key) => draft.keyframeCache.has(key))) continue;
// Skip position-only set tweens from runtime too, same filter as AST path
const isPosOnly =
data.keyframes.length === 1 &&
Object.keys(data.keyframes[0].properties).every((k) => k === "x" || k === "y");
if (isPosOnly) {
continue;
}
const entry = {
format: "percentage" as const,
keyframes: data.keyframes,
...(data.easeEach ? { easeEach: data.easeEach } : {}),
};
for (const key of keys) draft.keyframeCache.set(key, entry);
}
});
runtimeScanDoneRef.current = `kf-cache:${projectId}:${sf}:${version}`;
return true;
};
if (tryRuntimeScan()) return;
const interval = setInterval(() => {
attempts++;
if (tryRuntimeScan() || attempts >= maxAttempts) clearInterval(interval);
}, 500);
return () => clearInterval(interval);
}, [projectId, sourceFile, version, iframeRef]);
}