Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
// fallow-ignore-file code-duplication
/**
* Browser-safe GSAP write path — magic-string offset-splice.
*
* T6c: edits GSAP scripts by overwriting/removing byte ranges in the original
* source. Every byte outside the edited span is preserved verbatim — no
* pretty-printer churn. Consumes ParsedGsapAcornForWrite from gsapParserAcorn.ts.
*/
import MagicString from "magic-string";
import type {
GsapAnimation,
GsapPercentageKeyframe,
ArcPathConfig,
ArcPathSegment,
} from "./gsapSerialize.js";
import {
authorsKeyframes,
resolveConversionProps,
extractArcWaypoints,
buildMotionPathObjectCode,
mergePercentageKeyframes,
plainPercentKey,
} from "./gsapSerialize.js";
import {
parseGsapScriptAcornForWrite,
type ParsedGsapAcornForWrite,
type TweenCallInfo,
} from "./gsapParserAcorn.js";
import {
classifyPropertyGroup,
isTweenConfigKey,
isXYPositionWrite,
holdScope,
keyframeHoldForAnimation,
} from "./gsapConstants.js";
import type { PropertyGroupName } from "./gsapConstants.js";
import {
findObjectArrayKeyframeIndex,
getCompatibleObjectArrayKeyframeTiming,
} from "./gsapObjectArrayTiming.js";
import type { SplitAnimationsOptions, SplitAnimationsResult } from "./gsapSerialize.js";
import * as acornWalk from "acorn-walk";
import { clipQueryRoot, clipTweenMatcher, hasExplicitTime } from "./clipTweens.js";
export { clipQueryRoot, clipTweenMatcher, hasExplicitTime };
// acorn ESTree nodes are structurally untyped here; mirror gsapParserAcorn.ts /
// gsapInline.ts rather than re-deriving the full ESTree union for every access.
type Node = any;
// ── Code generation helpers ──────────────────────────────────────────────────
// Local serializer for the tween-statement path, which may carry boolean/object
// extras (stagger config). serializeValue stringifies objects to "[object
// Object]", so keep this richer JSON fallback for that path. Keyframe values are
// always number|string and use the shared serializeValue (recast parity).
function valueToCode(value: unknown): string {
if (typeof value === "string" && value.startsWith("__raw:")) return value.slice(6);
if (typeof value === "string") return JSON.stringify(value);
if (typeof value === "number") return Number.isNaN(value) ? "0" : String(value);
if (typeof value === "boolean") return String(value);
return JSON.stringify(value);
}
function safeKey(key: string): string {
return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key) ? key : JSON.stringify(key);
}
// fallow-ignore-next-line complexity
function buildTweenStatementCode(timelineVar: string, anim: Omit<GsapAnimation, "id">): string {
const selector = JSON.stringify(anim.targetSelector);
const props: Record<string, number | string> = { ...anim.properties };
if (anim.method !== "set" && anim.duration !== undefined) props.duration = anim.duration;
if (anim.ease) props.ease = anim.ease;
const entries = Object.entries(props).map(([k, v]) => `${safeKey(k)}: ${valueToCode(v)}`);
const emitted = new Set(Object.keys(props));
if (anim.extras) {
for (const [k, v] of Object.entries(anim.extras)) {
// A key carried by both properties and extras (a set's parsed
// `immediateRender: true`) must emit once — properties win. Same
// dedupe shape as the recast twin (gsapParser.ts buildTweenStatementCode).
if (emitted.has(k)) continue;
emitted.add(k);
entries.push(`${safeKey(k)}: ${valueToCode(v)}`);
}
}
const objCode = `{ ${entries.join(", ")} }`;
const posCode = valueToCode(
typeof anim.position === "number" ? anim.position : (anim.position ?? 0),
);
if (anim.method === "fromTo") {
const fromEntries = Object.entries(anim.fromProperties ?? {}).map(
([k, v]) => `${safeKey(k)}: ${valueToCode(v)}`,
);
return `${timelineVar}.fromTo(${selector}, { ${fromEntries.join(", ")} }, ${objCode}, ${posCode});`;
}
// A base `gsap.set` is off the timeline: no timeline var, no position arg.
if (anim.method === "set" && anim.global) {
return `gsap.set(${selector}, ${objCode});`;
}
return `${timelineVar}.${anim.method}(${selector}, ${objCode}, ${posCode});`;
}
// ── AST node helpers ─────────────────────────────────────────────────────────
function isObjectProperty(prop: Node): boolean {
return prop?.type === "ObjectProperty" || prop?.type === "Property";
}
function propKeyName(prop: Node): string | undefined {
return prop?.key?.name ?? prop?.key?.value;
}
function findPropertyNode(varsArgNode: Node, key: string): Node | undefined {
if (varsArgNode?.type !== "ObjectExpression") return undefined;
for (const prop of varsArgNode.properties ?? []) {
if (!isObjectProperty(prop)) continue;
if (propKeyName(prop) === key) return prop;
}
return undefined;
}
/** The `keyframes` property's ObjectExpression value, or null when not a keyframe tween. */
function keyframesObjectNode(varsNode: Node): Node | null {
const kfProp = findPropertyNode(varsNode, "keyframes");
return kfProp?.value?.type === "ObjectExpression" ? kfProp.value : null;
}
function findEnclosingExpressionStatement(ancestors: Node[]): Node | null {
for (let i = ancestors.length - 2; i >= 0; i--) {
if (ancestors[i]?.type === "ExpressionStatement") return ancestors[i];
}
return null;
}
/** Find the VariableDeclaration statement for `tl = gsap.timeline(...)`. */
function findTimelineDeclarationStatement(ast: Node, timelineVar: string): Node | null {
let found: Node = null;
acornWalk.simple(ast, {
// fallow-ignore-next-line complexity
VariableDeclaration(node: Node) {
if (found) return;
for (const decl of node.declarations ?? []) {
if (
decl.id?.name === timelineVar &&
decl.init?.type === "CallExpression" &&
decl.init.callee?.type === "MemberExpression" &&
decl.init.callee.object?.name === "gsap" &&
decl.init.callee.property?.name === "timeline"
) {
found = node;
}
}
},
});
return found;
}
// ── Property splice helpers ───────────────────────────────────────────────────
/**
* Remove a property from a properties array, handling its comma.
* `editableProps` must be the isObjectProperty-filtered subset in source order.
*/
function removeProp(ms: MagicString, propNode: Node, editableProps: Node[]): void {
const idx = editableProps.indexOf(propNode);
if (idx === -1) return;
if (editableProps.length === 1) {
ms.remove(propNode.start, propNode.end);
} else if (idx === 0) {
// First prop: remove from its start to next prop start (drops trailing ", ")
ms.remove(editableProps[0].start, editableProps[1].start);
} else {
// Non-first: remove from prev prop end to this prop end (drops leading ", ")
ms.remove(editableProps[idx - 1].end, propNode.end);
}
}
/** Serialize a vars record to an object-literal source: `{ k: v, ... }`. */
function buildVarsObjectCode(record: Record<string, number | string | boolean>): string {
const entries = Object.entries(record).map(([k, v]) => `${safeKey(k)}: ${valueToCode(v)}`);
return entries.length > 0 ? `{ ${entries.join(", ")} }` : "{}";
}
/** Overwrite a tween call's vars ObjectExpression with freshly-built source. */
function overwriteVarsArg(ms: MagicString, call: TweenCallInfo, objCode: string): void {
if (!call.varsArg) return;
ms.overwrite(call.varsArg.start, call.varsArg.end, objCode);
}
/**
* Update a property value if it exists, or append a new key: val before the
* closing `}`. Call with the full ObjectExpression node.
*/
function upsertProp(ms: MagicString, objNode: Node, key: string, value: unknown): void {
if (objNode?.type !== "ObjectExpression") return;
const existing = findPropertyNode(objNode, key);
if (existing) {
ms.overwrite(existing.value.start, existing.value.end, valueToCode(value));
} else {
const sep = objNode.properties.length > 0 ? ", " : "";
ms.appendLeft(objNode.end - 1, `${sep}${safeKey(key)}: ${valueToCode(value)}`);
}
}
/** Editable transform/style key test, the same split both parsers make. */
function isEditableVarKey(key: string): boolean {
return !isTweenConfigKey(key);
}
/**
* Collect verbatim `key: value` entries to PRESERVE from a vars/keyframe
* ObjectExpression: every property whose key `drop` does not reject, sliced from
* source — except keys present in `overrides`, whose value is replaced. Returns
* the entries plus the set of keys it kept, so callers can append new keys.
*/
function preservedEntries(
objNode: Node,
source: string,
drop: (key: string) => boolean,
overrides: Record<string, unknown>,
): { entries: string[]; keys: Set<string> } {
const entries: string[] = [];
const keys = new Set<string>();
for (const prop of objNode.properties ?? []) {
if (!isObjectProperty(prop)) continue;
const key = propKeyName(prop);
if (typeof key !== "string" || drop(key)) continue;
keys.add(key);
const code =
key in overrides
? valueToCode(overrides[key])
: source.slice(prop.value.start, prop.value.end);
entries.push(`${safeKey(key)}: ${code}`);
}
return { entries, keys };
}
/**
* Replace the editable-property keys on a vars ObjectExpression with exactly
* `newProps`, leaving non-editable keys (duration/ease/stagger/callbacks/…)
* untouched unless overridden in `nonEditableOverrides`. Mirrors recast's
* reconcileEditableProperties: editable keys absent from `newProps` are DROPPED,
* not merged. Rebuilt in a single ms.overwrite so the splice can never overlap a
* sibling edit — non-editable updates that also target this node (duration/ease/
* extras) are folded into the same rebuild rather than spliced separately.
*/
function reconcileEditableProps(
ms: MagicString,
objNode: Node,
source: string,
newProps: Record<string, number | string>,
nonEditableOverrides?: Record<string, unknown>,
): void {
if (objNode?.type !== "ObjectExpression") return;
const overrides = nonEditableOverrides ?? {};
const { entries, keys } = preservedEntries(objNode, source, isEditableVarKey, overrides);
for (const [key, value] of Object.entries(overrides)) {
if (!keys.has(key)) {
keys.add(key);
entries.push(`${safeKey(key)}: ${valueToCode(value)}`);
}
}
for (const [key, value] of Object.entries(newProps)) {
// A non-editable key riding along in newProps (immediateRender read off
// live tween vars) is already preserved above — emitting it again writes
// `immediateRender: true, immediateRender: true` into the file.
if (!keys.has(key)) entries.push(`${safeKey(key)}: ${valueToCode(value)}`);
}
ms.overwrite(objNode.start, objNode.end, `{ ${entries.join(", ")} }`);
}
// ── Insertion helpers ─────────────────────────────────────────────────────────
/** Traverse callee.object chain to check if a call ultimately roots at timelineVar. */
function isTimelineRooted(node: Node, timelineVar: string, script: string): boolean {
if (node?.type === "Identifier") return node.name === timelineVar;
// Inline/member timelines: `timelineVar` is the source slice (e.g.
// `window.__timelines["scene"]`); match a MemberExpression callee by its source.
if (node?.type === "MemberExpression") return script.slice(node.start, node.end) === timelineVar;
if (node?.type === "CallExpression")
return isTimelineRooted(node.callee?.object, timelineVar, script);
return false;
}
/**
* Byte offset to insert a new tween or label at: never above the timeline declaration.
* Returns null when no timeline declaration exists in the script — callers must
* not emit `tl.xxx()` calls in that case as `tl` would be undefined at render.
*/
function findInsertionPoint(parsed: ParsedGsapAcornForWrite): number | null {
const tlDecl = findTimelineDeclarationStatement(parsed.ast, parsed.timelineVar);
const lastLocated = parsed.located[parsed.located.length - 1];
if (lastLocated) {
const lastCall = lastLocated.call;
const exprStmt = findEnclosingExpressionStatement(lastCall.ancestors);
const lastCallEnd = exprStmt?.end ?? lastCall.node.end;
return Math.max(lastCallEnd, tlDecl?.end ?? 0);
}
if (!parsed.hasTimeline) return null;
return tlDecl?.end ?? (parsed.ast.end as number);
}
/**
* Line-start offset of the timeline declaration — where a global `gsap.set`
* must be inserted. A base set emitted AFTER the tween calls gets wiped on the
* next seek-driven rebuild: when a `from()` tween on the same target lazily
* initializes during a backwards render (the studio rebind's `progress(0.0001)`
* after a soft reload), GSAP reverts its internal isFromStart set, removing the
* whole inline `transform` — and the base set's x/y with it. Emitted BEFORE the
* timeline, the set is part of the pre-tween state the from() records, so every
* revert restores it instead. Returns null when no declaration exists.
*/
function findGlobalSetInsertionPoint(
parsed: ParsedGsapAcornForWrite,
script: string,
): number | null {
const tlDecl = findTimelineDeclarationStatement(parsed.ast, parsed.timelineVar);
if (!tlDecl) return null;
return script.lastIndexOf("\n", tlDecl.start) + 1;
}
// ── Public write API ─────────────────────────────────────────────────────────
// fallow-ignore-next-line complexity
export function updateAnimationInScript(
script: string,
animationId: string,
updates: Partial<GsapAnimation> & { easeEach?: string; resetKeyframeEases?: boolean },
): string {
if (!Object.keys(updates).length) return script;
const parsed = parseGsapScriptAcornForWrite(script);
if (!parsed) return script;
const target = parsed.located.find((l) => l.id === animationId);
if (!target || (updates.properties && target.animation.hasUnresolvedKeyframes)) return script;
const ms = new MagicString(script);
const { call }: { call: TweenCallInfo } = target;
// When `properties` is present we REPLACE the editable set (recast parity:
// editable keys absent from the update are dropped). Fold any concurrent
// non-editable updates (duration/ease/extras) into the single varsArg rebuild
// so their splices can't overlap the rebuild's overwrite of the whole node.
if (updates.properties) {
const overrides: Record<string, unknown> = {};
if (updates.duration !== undefined) overrides.duration = updates.duration;
if (updates.ease !== undefined) overrides.ease = updates.ease;
if (updates.extras) Object.assign(overrides, updates.extras);
reconcileEditableProps(ms, call.varsArg, script, updates.properties, overrides);
} else {
if (updates.duration !== undefined) {
upsertProp(ms, call.varsArg, "duration", updates.duration);
}
const easeValue = updates.easeEach ?? updates.ease;
if (easeValue !== undefined) {
const kfNode = keyframesObjectNode(call.varsArg);
if (kfNode) {
upsertProp(ms, kfNode, "easeEach", easeValue);
// "Apply to all segments": drop every per-keyframe `ease` override so the
// single easeEach governs all segments uniformly (AE select-all + F9).
if (updates.resetKeyframeEases) {
for (const kfEntry of kfNode.properties ?? []) {
if (!isObjectProperty(kfEntry)) continue;
const val = kfEntry.value;
if (val?.type !== "ObjectExpression") continue;
const easeNode = findPropertyNode(val, "ease");
if (easeNode) removeProp(ms, easeNode, val.properties);
}
}
} else {
upsertProp(ms, call.varsArg, "ease", easeValue);
}
}
if (updates.extras) {
for (const [key, value] of Object.entries(updates.extras)) {
upsertProp(ms, call.varsArg, key, value);
}
}
}
if (updates.fromProperties && call.method === "fromTo" && call.fromArg) {
// fromTo's from-vars carry only editable props — REPLACE them too (recast
// parity). fromArg is a distinct node from varsArg, so this rebuild never
// overlaps the varsArg edits above.
reconcileEditableProps(ms, call.fromArg, script, updates.fromProperties);
}
if (updates.position !== undefined) {
overwritePosition(ms, call, updates.position);
}
// Heal legacy scripts: a global `gsap.set` sitting after the timeline
// declaration is subject to the from()-init revert wipe (see
// findGlobalSetInsertionPoint) — relocate it above the declaration whenever
// it's touched, so the next nudge fixes files written before the reorder.
if (target.animation.method === "set" && target.animation.global) {
const globalSetPoint = findGlobalSetInsertionPoint(parsed, script);
const exprStmt = findEnclosingExpressionStatement(call.ancestors);
if (globalSetPoint !== null && exprStmt && exprStmt.start > globalSetPoint) {
const lineStart = script.lastIndexOf("\n", exprStmt.start) + 1;
const moveStart = /^\s*$/.test(script.slice(lineStart, exprStmt.start))
? lineStart
: exprStmt.start;
const moveEnd =
exprStmt.end < script.length && script[exprStmt.end] === "\n"
? exprStmt.end + 1
: exprStmt.end;
ms.move(moveStart, moveEnd, globalSetPoint);
}
}
return ms.toString();
}
/**
* Overwrite a tween call's numeric position argument (the positionArg the parser
* located: 3rd arg for fromTo, else 2nd), or append one when the call has no
* explicit position. Shared by updateAnimationInScript and the
* shift/scalePositionsInScript timeline ops.
*/
function overwritePosition(ms: MagicString, call: TweenCallInfo, position: number | string): void {
if (call.positionArg) {
ms.overwrite(call.positionArg.start, call.positionArg.end, valueToCode(position));
} else {
const last = call.node.arguments.at(-1);
ms.appendLeft(last ? last.end : call.node.end - 1, `, ${valueToCode(position)}`);
}
}
/**
* Shift every tween the clip at `targetSelector` carries by `delta` seconds (clamped ≥0),
* rewriting each call's position argument. Mirrors recast's shiftPositionsInScript
* (used by timeline clip-move to keep GSAP positions in sync with the clip start).
*/
export function shiftPositionsInScript(
script: string,
targetSelector: string,
delta: number,
root?: ParentNode,
): string {
return retimeClipTweensInScript(script, [{ kind: "shift", targetSelector, delta }], root).script;
}
export type ClipTweenRetime =
| { kind: "shift"; targetSelector: string; delta: number }
| {
kind: "scale";
targetSelector: string;
oldStart: number;
oldDuration: number;
newStart: number;
newDuration: number;
};
const isLiveRetime = (r: ClipTweenRetime) =>
r.kind === "shift" || (r.oldDuration > 0 && r.newDuration > 0);
/** Moves `animation`'s written position and duration for one retime; says which of the two it wrote. */
function applyRetime(
animation: GsapAnimation,
retime: ClipTweenRetime,
): { position: boolean; duration: boolean } {
if (retime.kind === "shift") {
if (!hasExplicitTime(animation)) return { position: false, duration: false };
animation.position = shiftedPosition(animation.position, retime.delta);
return { position: true, duration: false };
}
const touched = { position: false, duration: false };
if (!isLiveRetime(retime) || typeof animation.position !== "number") return touched;
const ratio = retime.newDuration / retime.oldDuration;
if (hasExplicitTime(animation)) {
const scaled = retime.newStart + (animation.position - retime.oldStart) * ratio;
animation.position = Math.max(0, Math.round(scaled * 1000) / 1000);
touched.position = true;
}
if (typeof animation.duration === "number" && animation.duration > 0) {
animation.duration = Math.max(0.001, Math.round(animation.duration * ratio * 1000) / 1000);
touched.duration = true;
}
return touched;
}
/**
* Applies `retimes` in order with one parse: the bytes equal running shift/scalePositionsInScript once
* per retime. `changed[i]` says whether retime i moved a value.
*/
export function retimeClipTweensInScript(
script: string,
retimes: readonly ClipTweenRetime[],
root?: ParentNode,
): { script: string; changed: boolean[] } {
const changed = retimes.map(() => false);
const parsed = retimes.some(isLiveRetime) ? parseGsapScriptAcornForWrite(script) : null;
if (!parsed) return { script, changed };
// Matchers share one query cache: each selector is looked up in the DOM once, not once per clip.
const queries = new Map<string, Element[]>();
const matchers = retimes.map((r) => clipTweenMatcher(r.targetSelector, root, queries));
const ms = new MagicString(script);
let wrote = false;
for (const entry of parsed.located) {
const animation = { ...entry.animation };
let position = false;
let duration = false;
retimes.forEach((retime, i) => {
if (!matchers[i]!(animation)) return;
const before = [animation.position, animation.duration];
const touched = applyRetime(animation, retime);
position ||= touched.position;
duration ||= touched.duration;
if (before[0] !== animation.position || before[1] !== animation.duration) changed[i] = true;
});
if (position) overwritePosition(ms, entry.call, animation.position as number);
if (duration) upsertProp(ms, entry.call.varsArg, "duration", animation.duration);
wrote ||= position || duration;
}
return { script: wrote ? ms.toString() : script, changed };
}
/** Copies each tween on `fromSelector` for `toSelector`, `delta` seconds later, in its own argument text. Exact or
* absent: only a tween at a number, written straight in the timeline's own block, is copied. */
export function copyAnimationsInScript(
script: string,
fromSelector: string,
toSelector: string,
delta: number,
): string {
const parsed = parseGsapScriptAcornForWrite(script);
if (!parsed) return script;
const block = timelineBlock(parsed);
const target = JSON.stringify(toSelector);
const ms = new MagicString(script);
const tweens: string[] = [];
for (const { animation, call } of parsed.located) {
if (animation.targetSelector !== fromSelector || !copyable(call)) continue;
const args = [target, ...argumentText(call, script)];
const statement = findEnclosingExpressionStatement(call.ancestors);
if (call.global && statement && inBlock(call, statement)) {
ms.appendLeft(
statement.end,
`\n${indentAt(script, statement.start)}gsap.set(${args.join(", ")});`,
);
} else if (block.body.includes(statement) && typeof call.positionArg?.value === "number") {
const position = valueToCode(shiftedPosition(call.positionArg.value, delta));
tweens.push(`${parsed.timelineVar}.${call.method}(${[...args, position].join(", ")});`);
}
}
appendAtBlockEnd(ms, script, block, tweens);
return ms.toString();
}
/** A tween in a loop runs once per pass, one on a variable reads a name bound elsewhere, and one inside a callback or a
* guard may never run: none is copied. The statement must be the tween's own chain. */
function copyable(call: TweenCallInfo): boolean {
if (call.node.arguments[0]?.type !== "Literal" || call.ancestors.some(isLoopOrForEach))
return false;
let link = findEnclosingExpressionStatement(call.ancestors)?.expression;
while (link?.type === "CallExpression" && link !== call.node) link = link.callee?.object;
return link === call.node;
}
/** A statement straight in a block or the script: one that is an `if`'s bare body runs only when the `if` does. */
function inBlock(call: TweenCallInfo, statement: Node): boolean {
return Array.isArray(call.ancestors[call.ancestors.indexOf(statement) - 1]?.body);
}
/** The call's own text for every argument but its target and position. */
function argumentText(call: TweenCallInfo, script: string): string[] {
return call.node.arguments
.slice(1)
.filter((arg: Node) => arg !== call.positionArg)
.map((arg: Node) => script.slice(arg.start, arg.end));
}
function indentAt(script: string, at: number): string {
return /^[ \t]*/.exec(script.slice(script.lastIndexOf("\n", at - 1) + 1))![0];
}
/** At the end of the timeline's own block, before its return, so nothing that follows in its scope is pushed back. */
function appendAtBlockEnd(
ms: MagicString,
script: string,
block: { body: Node[]; end: number },
lines: string[],
): void {
if (lines.length === 0) return;
const last = block.body.at(-1);
const indent = last ? indentAt(script, last.start) : "";
const code = lines.map((line) => `${indent}${line}`).join("\n");
if (last?.type === "ReturnStatement") ms.appendLeft(last.start, `${code.trimStart()}\n${indent}`);
else ms.appendLeft(last?.end ?? block.end, `\n${code}`);
}
function shiftedPosition(position: number, delta: number): number {
return Math.max(0, Math.round((position + delta) * 1000) / 1000);
}
/** The block (or program) whose statements declare the timeline; a timeline with no declaration lives at the top. */
function timelineBlock(parsed: ParsedGsapAcornForWrite): { body: Node[]; end: number } {
const declaration = findTimelineDeclarationStatement(parsed.ast, parsed.timelineVar);
let block: Node = parsed.ast;
if (declaration) {
acornWalk.ancestor(parsed.ast, {
VariableDeclaration(node: Node, _state: unknown, ancestors: Node[]) {
if (node === declaration) block = ancestors[ancestors.length - 2];
},
});
}
return Array.isArray(block?.body) ? block : parsed.ast;
}
function isLoopOrForEach(node: Node): boolean {
return isLoopNode(node) || isForEachStatement(node) || node?.type === "DoWhileStatement";
}
/**
* Linearly remap every tween the clip at `targetSelector` carries from the old clip
* [oldStart, oldDuration] onto the new [newStart, newDuration] (position and,
* when present, duration scaled by the duration ratio). Mirrors recast's
* scalePositionsInScript (used by timeline clip-resize).
*/
export function scalePositionsInScript(
script: string,
targetSelector: string,
oldStart: number,
oldDuration: number,
newStart: number,
newDuration: number,
root?: ParentNode,
): string {
return retimeClipTweensInScript(
script,
[{ kind: "scale", targetSelector, oldStart, oldDuration, newStart, newDuration }],
root,
).script;
}
export function addAnimationToScript(
script: string,
animation: Omit<GsapAnimation, "id">,
): { script: string; id: string } {
const parsed = parseGsapScriptAcornForWrite(script);
if (!parsed) return { script, id: "" };
const ms = new MagicString(script);
const statementCode = buildTweenStatementCode(parsed.timelineVar, animation);
const globalSetPoint =
animation.method === "set" && animation.global
? findGlobalSetInsertionPoint(parsed, script)
: null;
if (globalSetPoint !== null) {
ms.appendLeft(globalSetPoint, statementCode + "\n");
} else {
const insertionPoint = findInsertionPoint(parsed);
if (insertionPoint === null) return { script, id: "" };
ms.appendLeft(insertionPoint, "\n" + statementCode);
}
const result = ms.toString();
const reParsed = parseGsapScriptAcornForWrite(result);
// IDs are content-based, not positional — the new statement isn't necessarily
// the last located entry (a global set is inserted before the timeline).
// Diff against the pre-insert ids, counting duplicates.
const oldIdCounts = new Map<string, number>();
for (const entry of parsed.located) {
oldIdCounts.set(entry.id, (oldIdCounts.get(entry.id) ?? 0) + 1);
}
let newId = "";
for (const entry of reParsed?.located ?? []) {
const remaining = oldIdCounts.get(entry.id) ?? 0;
if (remaining === 0) {
newId = entry.id;
break;
}
oldIdCounts.set(entry.id, remaining - 1);
}
return { script: result, id: newId };
}
/** Splice a single located tween call out of a MagicString (standalone stmt or chain link). */
function removeCallFromMagicString(ms: MagicString, call: TweenCallInfo, script: string): void {
const N = call.node;
const exprStmt = findEnclosingExpressionStatement(call.ancestors);
if (N.callee?.object?.type !== "CallExpression" && exprStmt?.expression === N) {
// Standalone `tl.method(...)` — remove the whole ExpressionStatement
const end =
exprStmt.end < script.length && script[exprStmt.end] === "\n"
? exprStmt.end + 1
: exprStmt.end;
ms.remove(exprStmt.start, end);
} else {
// Chain link — splice out `.method(args)` from N.callee.object.end to N.end
ms.remove(N.callee.object.end, N.end);
}
}
export function removeAnimationFromScript(script: string, animationId: string): string {
const parsed = parseGsapScriptAcornForWrite(script);
if (!parsed) return script;
const target = parsed.located.find((l) => l.id === animationId);
if (!target) return script;
const ms = new MagicString(script);
removeCallFromMagicString(ms, target.call, script);
return ms.toString();
}
/**
* Enforce "exactly one position write per element". Position commits (drag, add
* keyframe, static hold) must never leave the same selector with two conflicting
* position representations (e.g. a degenerate `tl.to("#box",{duration:0,x,y})`
* AND a `gsap.set("#box",{x,y})`) — the later one silently overrides the earlier,
* so the element "can't move" / snaps / leaves residue on delete.
*
* Keeps `keepId` (the write the commit just edited); falls back to the LAST
* position write in source order (the runtime-effective one) if `keepId` is stale.
* Removes every OTHER x/y position write (`isXYPositionWrite`, which
* covers tl.to/from/fromTo flat-or-keyframed, tl.set, and standalone gsap.set,
* including degenerate duration:0 tweens). Non-position writes for the same
* selector (rotation / opacity / size / mixed) are left untouched.
*/
export function dedupePositionWritesInScript(
script: string,
selector: string,
keepId?: string,
): string {
const parsed = parseGsapScriptAcornForWrite(script);
if (!parsed) return script;
const posWrites = parsed.located.filter(
(l) => l.animation.targetSelector === selector && isXYPositionWrite(l.animation),
);
if (posWrites.length <= 1) return script;
const keeper = posWrites.find((l) => l.id === keepId) ?? posWrites[posWrites.length - 1]!;
const ms = new MagicString(script);
for (const l of posWrites) {
if (l === keeper) continue;
removeCallFromMagicString(ms, l.call, script);
}
return ms.toString();
}
// ── Flat-tween → keyframes conversion ──────────────────────────────────────────
//
// Mirror recast's convertToKeyframesInScript: when the first keyframe op lands
// on a flat to()/from()/fromTo() tween, rewrite its vars object to
// `{ keyframes: { "0%": {from}, "100%": {to} }, <preserved non-editable keys>,
// ease: "none"? }` and convert from()/fromTo() to to(). We rebuild the whole
// vars ObjectExpression in one ms.overwrite (single-edit-per-node), so the next
// keyframe-add re-parses cleanly.
// Identity value for an editable transform/style prop (recast's CSS_IDENTITY).
const CSS_IDENTITY: Record<string, number> = {
opacity: 1,
autoAlpha: 1,
scale: 1,
scaleX: 1,
scaleY: 1,
};
function cssIdentityValue(prop: string): number {
return CSS_IDENTITY[prop] ?? 0;
}
// Keys NOT in the editable set — preserved verbatim on the converted vars object
// (matches the parser's classification: builtin/dropped/extras keys).
const NON_EDITABLE_VAR_KEYS = new Set([
"duration",
"delay",
"onComplete",
"onStart",
"onUpdate",
"onRepeat",
"stagger",
"yoyo",
"repeat",
"repeatDelay",
"snap",
"overwrite",
"immediateRender",
]);
/** The CSS-identity counterpart of a props record (numbers → identity value). */
function identityProps(
properties: Record<string, number | string>,
): Record<string, number | string> {
const identity: Record<string, number | string> = {};
for (const [k, v] of Object.entries(properties)) {
if (v != null) identity[k] = typeof v === "number" ? cssIdentityValue(k) : v;
}
return identity;
}
/** Resolve the 0%/100% endpoint records for a tween being converted. */
function conversionEndpoints(animation: GsapAnimation): {
fromProps: Record<string, number | string>;
toProps: Record<string, number | string>;
} {
if (animation.method === "from") {
return { fromProps: { ...animation.properties }, toProps: identityProps(animation.properties) };
}
if (animation.method === "fromTo") {
return {
fromProps: { ...(animation.fromProperties ?? {}) },
toProps: { ...animation.properties },
};
}
// to(): 0% is the CSS identity state, 100% is the authored props.
return { fromProps: identityProps(animation.properties), toProps: { ...animation.properties } };
}
/** Collect preserved (non-editable) `key: value` entries from the original vars node. */
function preservedVarsEntries(varsNode: Node, source: string): string[] {
const entries: string[] = [];
if (varsNode?.type !== "ObjectExpression") return entries;
for (const prop of varsNode.properties ?? []) {
if (!isObjectProperty(prop)) continue;
const key = propKeyName(prop);
if (typeof key !== "string" || !NON_EDITABLE_VAR_KEYS.has(key)) continue;
entries.push(`${safeKey(key)}: ${source.slice(prop.value.start, prop.value.end)}`);
}
return entries;
}
/** Build the rebuilt vars-object code for a converted flat tween. */
function buildConvertedVarsCode(animation: GsapAnimation, varsNode: Node, source: string): string {
const { fromProps, toProps } = conversionEndpoints(animation);
const easeEach = animation.ease;
const easeEachEntry = easeEach ? `, easeEach: ${valueToCode(easeEach)}` : "";
const kfCode = `{ "0%": ${recordToCode(fromProps)}, "100%": ${recordToCode(toProps)}${easeEachEntry} }`;
const entries = [`keyframes: ${kfCode}`, ...preservedVarsEntries(varsNode, source)];
if (easeEach) entries.push(`ease: "none"`);
return `{ ${entries.join(", ")} }`;
}
/** Rename a from()/fromTo() call to to(), dropping fromTo's leading from-vars arg. */
function convertMethodToTo(
ms: MagicString,
animation: GsapAnimation,
call: Node,
varsNode: Node,
): void {
if (animation.method !== "from" && animation.method !== "fromTo") return;
const calleeProp = call.node.callee?.property;
if (calleeProp) ms.overwrite(calleeProp.start, calleeProp.end, "to");
// Remove the from-vars arg and its trailing separator up to the to-vars arg.
if (animation.method === "fromTo" && call.fromArg) ms.remove(call.fromArg.start, varsNode.start);
}
function convertFlatTweenToKeyframes(script: string, target: Node): string {
const animation: GsapAnimation = target.animation;
if (animation.keyframes || animation.method === "set") return script;
const call = target.call;
const varsNode = call.varsArg;
if (varsNode?.type !== "ObjectExpression") return script;
const ms = new MagicString(script);
ms.overwrite(varsNode.start, varsNode.end, buildConvertedVarsCode(animation, varsNode, script));
convertMethodToTo(ms, animation, call, varsNode);
return ms.toString();
}
// ── Keyframe write ops ────────────────────────────────────────────────────────
//
// Design: mirror the recast writer's rebuild-the-node model. The recast writer
// mutates AST nodes in place and re-prints, so it never has an offset-overlap
// problem. Here we instead compute the FINAL property record for every keyframe
// value node that must change (the target merge, `_auto` endpoint sync, and
// backfilled siblings) against the ORIGINAL parsed AST, then emit exactly ONE
// `ms.overwrite(valueNode.start, valueNode.end, code)` per changed node (and a
// single insert for a brand-new key). No node is ever both overwritten and
// appended into, so the splices can never overlap.
const PERCENTAGE_KEY_RE = /^(\d+(?:\.\d+)?)%$/;
// Matches recast's PCT_TOLERANCE: percentages within 2 of an existing key are
// treated as the same keyframe (merge), not a new insert.
const PCT_TOLERANCE = 2;
// Below this (tween-%) a retime resolves onto its own source keyframe → skip the
// write. Mirrors the drag layer's NOOP_EPSILON so a deliberate 1% retime commits.
const MOVE_NOOP_EPSILON_PCT = 0.05;
function percentageFromKey(key: string): number {
const m = PERCENTAGE_KEY_RE.exec(key);
return m ? Number.parseFloat(m[1] ?? "0") : Number.NaN;
}
/** Serialize a final keyframe property record (number|string values) to code. */
function recordToCode(record: Record<string, number | string>): string {
const entries = Object.entries(record).map(([k, v]) => `${safeKey(k)}: ${valueToCode(v)}`);
return `{ ${entries.join(", ")} }`;
}
/** Percentage-keyed property nodes of a keyframes ObjectExpression, in source order. */
function percentagePropsOf(kfNode: Node): Node[] {
return (kfNode.properties ?? []).filter((p: Node) => {
if (!isObjectProperty(p)) return false;
const key = propKeyName(p);
return typeof key === "string" && PERCENTAGE_KEY_RE.test(key);
});
}
const LITERAL_NODE_TYPES = new Set(["Literal", "NumericLiteral", "StringLiteral"]);
/** Read one value node: a number/string literal, a negative number, or raw source. */
// fallow-ignore-next-line complexity
function readValueNode(v: Node, source: string): number | string {
if (
LITERAL_NODE_TYPES.has(v?.type) &&
(typeof v.value === "number" || typeof v.value === "string")
) {
return v.value;
}
if (
v?.type === "UnaryExpression" &&
v.operator === "-" &&
typeof v.argument?.value === "number"
) {
return -v.argument.value;
}
return `__raw:${source.slice(v.start, v.end)}`;
}
/**
* Read a keyframe value ObjectExpression into a record, mirroring the parser's
* `objectExpressionToRecord`: literals resolve to their value; anything else is
* preserved as `__raw:<source>` so serializeValue round-trips it verbatim.
* Keyframe values are literals in practice, so the raw fallback is rarely hit.
*/
function valueNodeToRecord(valueNode: Node, source: string): Record<string, number | string> {
const record: Record<string, number | string> = {};
if (valueNode?.type !== "ObjectExpression") return record;
for (const prop of valueNode.properties ?? []) {
if (!isObjectProperty(prop)) continue;
const key = propKeyName(prop);
if (typeof key !== "string") continue;
record[key] = readValueNode(prop.value, source);
}
return record;
}
/** True when a keyframe value record carries the synthetic `_auto` marker. */
function recordHasAuto(record: Record<string, number | string>): boolean {
return "_auto" in record;
}
/**
* Compute `_auto` endpoint overwrites: when the new keyframe is the immediate
* neighbor of an `_auto` 0% or 100% endpoint, that endpoint is rewritten to
* `{ ...newProps, _auto: 1 }`. Only fires for interior keyframes. Returns the
* percentage→overwrite map so the caller can fold these into the per-node final
* records (never a separate splice).
*/
function autoEndpointOverwrites(
kfNode: Node,
source: string,
percentage: number,
properties: Record<string, number | string>,
): Map<any, Record<string, number | string>> {
const result = new Map<any, Record<string, number | string>>();
if (percentage <= 0 || percentage >= 100) return result;
const pctProps = percentagePropsOf(kfNode);
const allPcts = pctProps
.map((p: Node) => percentageFromKey(propKeyName(p) ?? ""))
.filter((n: number) => !Number.isNaN(n) && n !== percentage)
.sort((a: number, b: number) => a - b);
const leftNeighbor = allPcts.filter((p: number) => p < percentage).pop();
const rightNeighbor = allPcts.find((p: number) => p > percentage);
for (const endPct of [0, 100]) {
const isNeighbor = endPct === 0 ? leftNeighbor === 0 : rightNeighbor === 100;
if (!isNeighbor) continue;
const endProp = pctProps.find((p: Node) => percentageFromKey(propKeyName(p) ?? "") === endPct);
if (!endProp) continue;
const rec = valueNodeToRecord(endProp.value, source);
if (!recordHasAuto(rec)) continue;
result.set(endProp, { ...properties, _auto: 1 });
}
return result;
}
function findKfPropByPct(kfNode: Node, percentage: number): { prop: Node; idx: number } | null {
// Match the CLOSEST keyframe within tolerance, not the first one within range.
// Keyframes at e.g. 0/49/50/100 are all valid (the SDK dedups to a unique
// match at TOLERANCE=0.001 upstream); picking the first-within-PCT_TOLERANCE=2
// would hit 49% when the caller meant 50%. Tie-break on the earliest index so
// the choice stays deterministic.
const props = kfNode.properties ?? [];
let best: { prop: Node; idx: number } | null = null;
let bestDist = Number.POSITIVE_INFINITY;
for (let i = 0; i < props.length; i++) {
const prop = props[i];
if (!isObjectProperty(prop)) continue;
const key = propKeyName(prop);
if (typeof key !== "string") continue;
const dist = Math.abs(percentageFromKey(key) - percentage);
if (dist <= PCT_TOLERANCE && dist < bestDist) {
best = { prop, idx: i };
bestDist = dist;
}
}
return best;
}
function updateMotionPathPosition(
script: string,
target: ParsedGsapAcornForWrite["located"][number],
percentage: number,
properties: Record<string, number | string>,
): string | undefined {
const waypoints = extractArcWaypoints(target.animation);
if (waypoints.length < 2) return undefined;
const pointIndex = Math.max(
0,
Math.min(waypoints.length - 1, Math.round((percentage / 100) * (waypoints.length - 1))),
);
const current = waypoints[pointIndex];
if (!current) return undefined;
const x = properties.x ?? current.x;
const y = properties.y ?? current.y;
if (typeof x !== "number" || typeof y !== "number") return undefined;
return updateMotionPathPointInScript(script, target.id, pointIndex, { x, y });
}
function updateTweenEase(script: string, animationId: string, ease: string): string | undefined {
const reparsed = parseGsapScriptAcornForWrite(script);
const target = reparsed?.located.find((entry) => entry.id === animationId);
if (!target) return undefined;
const ms = new MagicString(script);
upsertProp(ms, target.call.varsArg, "ease", ease);
return ms.toString();
}
function updateMotionPathKeyframe(
script: string,
target: ParsedGsapAcornForWrite["located"][number],
percentage: number,
properties: Record<string, number | string>,
ease?: string,
): string | undefined {
if (!target.animation.arcPath?.enabled || !findPropertyNode(target.call.varsArg, "motionPath")) {
return undefined;
}
const propertyKeys = Object.keys(properties);
if (propertyKeys.some((key) => key !== "x" && key !== "y")) return undefined;
const next =
propertyKeys.length === 0
? script
: updateMotionPathPosition(script, target, percentage, properties);
if (next === undefined || ease === undefined) return next;
return updateTweenEase(next, target.id, ease);
}
function updateObjectKeyframe(
script: string,
prop: Node,
properties: Record<string, number | string>,
ease?: string,
): string {
const ms = new MagicString(script);
// Merge into the authored object so an edit cannot discard unrelated
// keyframed properties at the same percentage.
if (prop.value?.type === "ObjectExpression") {
for (const [key, value] of Object.entries(properties)) {
upsertProp(ms, prop.value, key, value);
}
if (ease !== undefined) upsertProp(ms, prop.value, "ease", ease);
} else {
const record: Record<string, number | string> = { ...properties };
if (ease) record.ease = ease;
ms.overwrite(prop.value.start, prop.value.end, recordToCode(record));
}
return ms.toString();
}
export function updateKeyframeInScript(
script: string,
animationId: string,
percentage: number,
properties: Record<string, number | string>,
ease?: string,
): string {
const parsed = parseGsapScriptAcornForWrite(script);
if (!parsed) return script;
const target = parsed.located.find((l) => l.id === animationId);
if (!target || target.animation.hasUnresolvedKeyframes) return script;
const kfPropNode = findPropertyNode(target.call.varsArg, "keyframes");
if (!kfPropNode) {
// motionPath waypoints are exposed to Studio as synthetic keyframes, but
// GSAP authors their positions in `motionPath.path` and one ease for the
// whole tween. Commit both parts when a Studio gesture carries x/y + ease.
return updateMotionPathKeyframe(script, target, percentage, properties, ease) ?? script;
}
// Array-form keyframes (`keyframes: [{x,y}, ...]`) carry no explicit percentages
// — GSAP ends step i of n at its cumulative share (getObjectArrayKeyframeTiming).
// Map the percentage back to an array index and overwrite that
// element in place (preserving the array form). Without this the function bailed
// on the ObjectExpression check, so dragging a motion-path node on an array-form
// tween committed nothing (server no-op).
if (kfPropNode.value?.type === "ArrayExpression") {
return updateArrayKeyframeByPct(script, kfPropNode.value, percentage, properties, ease);
}
if (kfPropNode.value?.type !== "ObjectExpression") return script;
const match = findKfPropByPct(kfPropNode.value, percentage);
if (!match) return script;
return updateObjectKeyframe(script, match.prop, properties, ease);
}
function updateArrayKeyframeByPct(
script: string,
arrayNode: Node,
percentage: number,
properties: Record<string, number | string>,
ease?: string,
): string {
const elements = ((arrayNode.elements ?? []) as Array<Node | null>).filter(
(el): el is Node => !!el && el.type === "ObjectExpression",
);
if (elements.length === 0) return script;
const records = elements.map((element) => valueNodeToRecord(element, script));
const idx = findObjectArrayKeyframeIndex(
records.map((record) => record.duration),
percentage,
{ fallbackToNearest: true },
);
if (idx === null) return script;
const el = elements[idx];
if (!el) return script;
const merged: Record<string, number | string> = {
...records[idx],
...properties,
};
if (ease) merged.ease = ease;
const ms = new MagicString(script);
ms.overwrite(el.start, el.end, recordToCode(merged));
return ms.toString();
}
/**
* Build the final property record for the keyframe at `percentage`. If a
* keyframe already exists there, MERGE the new props over the existing record
* (preserve untouched props, preserve `_auto`, preserve the existing per-keyframe
* ease when the op omits one); otherwise it's just the new props.
*/
function buildTargetRecord(
existing: { prop: Node; idx: number } | null,
source: string,
properties: Record<string, number | string>,
ease: string | undefined,
): Record<string, number | string> {
if (!existing || existing.prop.value?.type !== "ObjectExpression") {
const record: Record<string, number | string> = { ...properties };
if (ease) record.ease = ease;
return record;
}
const existingRecord = valueNodeToRecord(existing.prop.value, source);
const existingEase = typeof existingRecord.ease === "string" ? existingRecord.ease : undefined;
const merged: Record<string, number | string> = { ...existingRecord };
for (const [k, v] of Object.entries(properties)) merged[k] = v;
const finalEase = ease ?? existingEase;
if (finalEase) merged.ease = finalEase;
else delete merged.ease;
return merged;
}
/**
* Compute the backfilled final record for one sibling keyframe: append any of
* `newPropKeys` it's missing, using the backfill default. Returns null when
* nothing changes (so the caller emits no overwrite for it).
*/
function backfilledSiblingRecord(
valueNode: Node,
source: string,
newPropKeys: string[],
backfillDefaults: Record<string, number | string>,
): Record<string, number | string> | null {
if (valueNode?.type !== "ObjectExpression") return null;
const record = valueNodeToRecord(valueNode, source);
let changed = false;
for (const pk of newPropKeys) {
const defaultVal = backfillDefaults[pk];
if (pk in record || defaultVal == null) continue;
record[pk] = defaultVal;
changed = true;
}
return changed ? record : null;
}
/** A located tween whose varsArg has a static keyframes ObjectExpression, or null. */
function locateWithKeyframes(
script: string,
animationId: string,
): { script: string; parsed: ParsedGsapAcornForWrite; target: Node; kfNode: Node } | null {
const parsed = parseGsapScriptAcornForWrite(script);
if (!parsed) return null;
// Converting from()/fromTo() to to() rewrites the content-derived id; match
// recast's locateAnimationWithFallback by remapping the method segment.
const convertedId = animationId.replace(/-from-|-fromTo-/, "-to-");
const target =
parsed.located.find((l) => l.id === animationId) ??
parsed.located.find((l) => l.id === convertedId);
if (!target || target.animation.hasUnresolvedKeyframes) return null;
const kfPropNode = findPropertyNode(target.call.varsArg, "keyframes");
if (!kfPropNode || kfPropNode.value?.type !== "ObjectExpression") return null;
return { script, parsed, target, kfNode: kfPropNode.value };
}
/** Locate a tween's keyframes object, converting a flat tween first if absent. */
// Array-form keyframes → percentage-object form. Duration-authored entries use
// cumulative positions; duration metadata moves to the outer tween.
function convertArrayKeyframesToObject(script: string, target: Node): string {
const kfPropNode = findPropertyNode(target.call.varsArg, "keyframes");
if (!kfPropNode || kfPropNode.value?.type !== "ArrayExpression") return script;
const els = ((kfPropNode.value.elements ?? []) as Array<Node | null>).filter(
(el): el is Node => !!el && el.type === "ObjectExpression",
);
if (els.length === 0) return script;
const records = els.map((element) => valueNodeToRecord(element, script));
const outerDuration = valueNodeToRecord(target.call.varsArg, script).duration;
const timing = getCompatibleObjectArrayKeyframeTiming(
records.map((record) => record.duration),
outerDuration,
);
if (!timing) return script;
const entries = els.map((el, i) => {
const { duration: _duration, ...record } = records[i]!;
return `${JSON.stringify(plainPercentKey(timing.percentages[i]!))}: ${recordToCode(record)}`;
});
const ms = new MagicString(script);
ms.overwrite(
kfPropNode.value.start,
kfPropNode.value.end,
`{ ${entries.join(", ")}, easeEach: "none" }`,
);
if (findPropertyNode(target.call.varsArg, "duration") === undefined) {
upsertProp(ms, target.call.varsArg, "duration", timing.totalDuration);
}
return ms.toString();
}
function ensureKeyframesNode(
script: string,
animationId: string,
): { script: string; parsed: ParsedGsapAcornForWrite; target: Node; kfNode: Node } | null {
const direct = locateWithKeyframes(script, animationId);
if (direct) return direct;
const parsed = parseGsapScriptAcornForWrite(script);
const target = parsed?.located.find((l) => l.id === animationId);
if (!target || target.animation.hasUnresolvedKeyframes) return null;
// Array-form keyframes → normalize to object form, then re-locate.
const kfProp = findPropertyNode(target.call.varsArg, "keyframes");
if (kfProp?.value?.type === "ArrayExpression") {
const normalized = convertArrayKeyframesToObject(script, target);
if (normalized !== script) return locateWithKeyframes(normalized, animationId);
return null;
}
// No static keyframes object — convert the flat tween, then re-locate.
const converted = convertFlatTweenToKeyframes(script, target);
if (converted === script) return null;
return locateWithKeyframes(converted, animationId);
}
/**
* Compute the sibling keyframe nodes that need a backfilled prop, excluding the
* target keyframe and any node already being overwritten as an `_auto` endpoint.
*/
function collectBackfillOverwrites(
kfNode: Node,
src: string,
properties: Record<string, number | string>,
backfillDefaults: Record<string, number | string> | undefined,
skip: { existingProp: Node; endpoints: Map<any, unknown> },
): Map<any, Record<string, number | string>> {
const result = new Map<any, Record<string, number | string>>();
if (!backfillDefaults) return result;
const newPropKeys = Object.keys(properties);
for (const prop of percentagePropsOf(kfNode)) {
if (prop === skip.existingProp || skip.endpoints.has(prop)) continue;
const rec = backfilledSiblingRecord(prop.value, src, newPropKeys, backfillDefaults);
if (rec) result.set(prop, rec);
}
return result;
}
export function addKeyframeToScript(
script: string,
animationId: string,
percentage: number,
properties: Record<string, number | string>,
ease?: string,
backfillDefaults?: Record<string, number | string>,
): string {
const located = ensureKeyframesNode(script, animationId);
if (!located) return script;
const { script: src, kfNode } = located;
const existing = findKfPropByPct(kfNode, percentage);
// Final record for the target keyframe (merge if it already exists).
const targetRecord = buildTargetRecord(existing, src, properties, ease);
// `_auto` endpoint syncs fire only on new inserts; a merge landing ON an
// endpoint already preserves `_auto` via buildTargetRecord.
const endpointOverwrites = existing
? new Map<any, Record<string, number | string>>()
: autoEndpointOverwrites(kfNode, src, percentage, properties);
// Backfilled siblings (each node changes at most once).
const backfillOverwrites = collectBackfillOverwrites(kfNode, src, properties, backfillDefaults, {
existingProp: existing?.prop,
endpoints: endpointOverwrites,
});
// Emit exactly one overwrite per changed node, plus one insert for a new key.
const ms = new MagicString(src);
if (existing) {
// Merge into the existing keyframe at this percentage, preserving sibling
// properties — overwrite only the given keys. (A whole-value overwrite here
// would silently drop other properties already keyframed at this percent.)
if (existing.prop.value?.type === "ObjectExpression") {
for (const [k, v] of Object.entries(properties)) {
upsertProp(ms, existing.prop.value, k, v);
}
if (ease !== undefined) upsertProp(ms, existing.prop.value, "ease", ease);
} else {
ms.overwrite(existing.prop.value.start, existing.prop.value.end, recordToCode(targetRecord));
}
} else {
insertNewKeyframe(
ms,
kfNode,
percentage,
plainPercentKey(percentage),
recordToCode(targetRecord),
);
}
for (const [prop, rec] of [...endpointOverwrites, ...backfillOverwrites]) {
ms.overwrite(prop.value.start, prop.value.end, recordToCode(rec));
}
return ms.toString();
}
/** Insert a brand-new `"pct%": {...}` property in sorted order. */
function insertNewKeyframe(
ms: MagicString,
kfNode: Node,
percentage: number,
pctKey: string,
valueCode: string,
): void {
const allProps = (kfNode.properties ?? []).filter((p: Node) => isObjectProperty(p));
let insertBeforeProp: Node = null;
for (const prop of allProps) {
const key = propKeyName(prop);
if (typeof key === "string" && percentageFromKey(key) > percentage) {
insertBeforeProp = prop;
break;
}
}
if (insertBeforeProp) {
ms.appendLeft(insertBeforeProp.start, `${JSON.stringify(pctKey)}: ${valueCode}, `);
} else {
const sep = allProps.length > 0 ? ", " : "";
ms.appendLeft(kfNode.end - 1, `${sep}${JSON.stringify(pctKey)}: ${valueCode}`);
}
}
/**
* Rebuild a vars ObjectExpression that has just dropped below two keyframes,
* collapsing `keyframes: {…}` back to a flat tween. Mirrors recast's
* collapseKeyframesToFlat: drop the `keyframes` + `easeEach` keys, preserve every
* other vars key verbatim, and splice the remaining keyframe's properties (minus
* its per-keyframe `ease`) in as flat vars keys. Single ms.overwrite of the whole
* vars node so the splice can't overlap the keyframe removal.
*/
function collapseKeyframesToFlat(
ms: MagicString,
varsNode: Node,
source: string,
remainingRecord: Record<string, number | string>,
): void {
if (varsNode?.type !== "ObjectExpression") return;
const dropKeyframeKeys = (key: string) => key === "keyframes" || key === "easeEach";
const { entries } = preservedEntries(varsNode, source, dropKeyframeKeys, {});
for (const [k, v] of Object.entries(remainingRecord)) {
if (k !== "ease") entries.push(`${safeKey(k)}: ${valueToCode(v)}`);
}
ms.overwrite(varsNode.start, varsNode.end, `{ ${entries.join(", ")} }`);
}
// Resolve an array entry through the parser's cumulative/even timing rule, then
// splice it out; collapse when fewer than two remain.
function removeArrayKeyframe(
ms: MagicString,
varsArg: Node,
arrNode: Node,
script: string,
percentage: number,
): boolean {
const elements: Node[] = (arrNode.elements ?? []).filter(
(e: Node | null): e is Node => !!e && e.type === "ObjectExpression",
);
if (elements.length === 0) return false;
const records = elements.map((element) => valueNodeToRecord(element, script));
const matchIdx = findObjectArrayKeyframeIndex(
records.map((record) => record.duration),
percentage,
);
if (matchIdx === null) return false;
const remaining = elements.filter((_, i) => i !== matchIdx);
if (remaining.length < 2) {
const sole = remaining[0];
const record = sole ? valueNodeToRecord(sole, script) : {};
collapseKeyframesToFlat(ms, varsArg, script, record);
return true;
}
removeProp(ms, elements[matchIdx], elements);
return true;
}
export function removeKeyframeFromScript(
script: string,
animationId: string,
percentage: number,
): string {
const parsed = parseGsapScriptAcornForWrite(script);
if (!parsed) return script;
const target = parsed.located.find((l) => l.id === animationId);
if (!target || target.animation.hasUnresolvedKeyframes) return script;
const kfPropNode = findPropertyNode(target.call.varsArg, "keyframes");
if (!kfPropNode) return script;
if (kfPropNode.value?.type === "ArrayExpression") {
const ms = new MagicString(script);
return removeArrayKeyframe(ms, target.call.varsArg, kfPropNode.value, script, percentage)
? ms.toString()
: script;
}
if (kfPropNode.value?.type !== "ObjectExpression") return script;
const kfNode = kfPropNode.value;
const match = findKfPropByPct(kfNode, percentage);
if (!match) return script;
const ms = new MagicString(script);
// If removing this keyframe leaves fewer than two, collapse the keyframes
// object back to a flat tween (recast parity) instead of leaving a lone
// keyframe. We rebuild the whole vars node, so we never also splice the kf
// node — the two edits would overlap.
const remaining = percentagePropsOf(kfNode).filter((p) => p !== match.prop);
if (remaining.length < 2) {
const sole = remaining[0];
const record = sole ? valueNodeToRecord(sole.value, script) : {};
collapseKeyframesToFlat(ms, target.call.varsArg, script, record);
return ms.toString();
}
const allProps = (kfNode.properties ?? []).filter((p: Node) => isObjectProperty(p));
removeProp(ms, match.prop, allProps);
return ms.toString();
}
/**
* Retime a keyframe: move the keyframe at `fromPercentage` to `toPercentage`,
* PRESERVING its properties and per-keyframe ease (the Studio "Move to Playhead"
* gesture). Re-sorts keyframes by percentage. No-op when the animation/keyframe
* isn't found, the tween has no object-form keyframes, the move resolves onto the
* same keyframe, or the destination is occupied.
*/
export function moveKeyframeInScript(
script: string,
animationId: string,
fromPercentage: number,
toPercentage: number,
): string {
// ensureKeyframesNode (not locateWithKeyframes) so array-form `keyframes: [...]`
// tweens normalize to percentage-object form first — locateWithKeyframes alone
// bails on ArrayExpression, silently no-op'ing every move on an array-form tween.
const located = ensureKeyframesNode(script, animationId);
if (!located) return script;
const { script: src, kfNode } = located;
const match = findKfPropByPct(kfNode, fromPercentage);
if (!match) return src;
// No-op ONLY for a negligible move (matches the drag's NOOP_EPSILON). The old
// `collision.prop === match.prop` guard dropped EVERY sub-PCT_TOLERANCE (2%)
// retime, because findKfPropByPct resolves the destination back onto the
// from-keyframe — so a deliberate 1% drag committed nothing.
if (Math.abs(fromPercentage - toPercentage) < MOVE_NOOP_EPSILON_PCT) return src;
// Never overwrite another authored keyframe. Resolving the destination back
// onto the source keyframe is not a collision (the tolerance is intentionally
// wider than MOVE_NOOP_EPSILON_PCT).
const dest = findKfPropByPct(kfNode, toPercentage);
if (dest && dest.prop !== match.prop) return script;
// Rebuild the keyframes object: drop the moved keyframe, re-key the moved
// record to toPercentage, then re-sort. recordToCode round-trips properties +
// per-keyframe ease + _auto.
const entries: Array<{ pct: number; record: Record<string, number | string> }> = [];
for (const prop of percentagePropsOf(kfNode)) {
if (prop === match.prop) continue;
const pct = percentageFromKey(propKeyName(prop) ?? "");
if (Number.isNaN(pct)) continue;
entries.push({ pct, record: valueNodeToRecord(prop.value, src) });
}
entries.push({ pct: toPercentage, record: valueNodeToRecord(match.prop.value, src) });
entries.sort((a, b) => a.pct - b.pct);
const pctProps = new Set(percentagePropsOf(kfNode));
const kept = (kfNode.properties ?? [])
.filter((p: Node) => !pctProps.has(p))
.map((p: Node) => src.slice(p.start, p.end));
const body = [
...entries.map((e) => `${JSON.stringify(plainPercentKey(e.pct))}: ${recordToCode(e.record)}`),
...kept,
].join(", ");
const ms = new MagicString(src);
ms.overwrite(kfNode.start, kfNode.end, `{ ${body} }`);
return ms.toString();
}
/**
* Resize a keyframed tween's window (boundary drag-to-retime): set the tween's
* `position` (trailing position arg) + `duration`, and RE-KEY each existing
* keyframe to its new percentage via `pctRemap` (each `{ from, to }` matches an
* existing keyframe by its current tween-% and re-keys it to `to`).
*
* Unlike replace-with-keyframes (which rebuilds the keyframes object from a plain
* array and loses author intent), this re-keys the percentage KEY in place and
* leaves every value node, each keyframe's `_auto` + per-keyframe `ease`, the
* keyframes-object `easeEach`, and the OUTER tween `ease` byte-for-byte verbatim.
* No-op when the animation/keyframes can't be located.
*/
export function resizeKeyframedTweenInScript(
script: string,
animationId: string,
newPosition: number,
newDuration: number,
pctRemap: ReadonlyArray<{ from: number; to: number }>,
): string {
// ensureKeyframesNode (not locateWithKeyframes) so array-form `keyframes: [...]`
// tweens normalize to percentage-object form first — see moveKeyframeInScript.
const located = ensureKeyframesNode(script, animationId);
if (!located) return script;
const { script: src, target, kfNode } = located;
// Resolve every re-key against the ORIGINAL AST first (offsets stay stable),
// then splice — distinct key nodes, so the overwrites never overlap. A Set
// guards the degenerate case where two remaps resolve to the same key.
const edits: Array<{ keyNode: Node; to: number }> = [];
const seen = new Set<Node>();
for (const { from, to } of pctRemap) {
const match = findKfPropByPct(kfNode, from);
if (!match || seen.has(match.prop.key)) continue;
seen.add(match.prop.key);
edits.push({ keyNode: match.prop.key, to });
}
const ms = new MagicString(src);
for (const { keyNode, to } of edits) {
ms.overwrite(keyNode.start, keyNode.end, JSON.stringify(plainPercentKey(to)));
}
overwritePosition(ms, target.call, newPosition);
// Resizing is an explicit duration-authoring gesture. Promote GSAP's implicit
// default to source so the dragged window is the window that plays.
upsertProp(ms, target.call.varsArg, "duration", newDuration);
return ms.toString();
}
export function removePropertyFromAnimation(
script: string,
animationId: string,
property: string,
from = false,
): string {
const parsed = parseGsapScriptAcornForWrite(script);
if (!parsed) return script;
const target = parsed.located.find((l) => l.id === animationId);
if (!target) return script;
const { call } = target;
const objNode = from ? (call.method === "fromTo" ? call.fromArg : null) : call.varsArg;
if (!objNode) return script;
const propNode = findPropertyNode(objNode, property);
if (!propNode) return script;
const allProps = (objNode.properties ?? []).filter((p: Node) => isObjectProperty(p));
const ms = new MagicString(script);
removeProp(ms, propNode, allProps);
return ms.toString();
}
/**
* Remove all keyframes from a tween, collapsing to a flat tween with one
* keyframe's properties: the first for `from()`, the last otherwise (the
* destination = the visible resting state).
*/
// fallow-ignore-next-line complexity
export function removeAllKeyframesFromScript(script: string, animationId: string): string {
const parsed = parseGsapScriptAcornForWrite(script);
if (!parsed) return script;
const target = parsed.located.find((l) => l.id === animationId);
if (!target) return script;
const kfs = target.animation.keyframes?.keyframes;
if (!kfs || kfs.length === 0) return script;
const sorted = [...kfs].sort((a, b) => a.percentage - b.percentage);
const collapse = target.call.method === "from" ? sorted[0] : sorted[sorted.length - 1];
if (!collapse) return script;
const ms = new MagicString(script);
overwriteVarsArg(
ms,
target.call,
buildVarsObjectCode(buildCollapsedFlatVars(target.animation, collapse)),
);
// Removing all keyframes of a POSITION tween must leave exactly ONE held state:
// strip every sibling position write for the same selector (a stray gsap.set or
// a second tl.to/tl.set) so the collapsed hold is the lone position source. Only
// position siblings are stripped; rotation/opacity/etc. for the selector remain.
if (target.animation.propertyGroup === "position") {
for (const l of parsed.located) {
if (l === target) continue;
if (
l.animation.targetSelector === target.animation.targetSelector &&
l.animation.propertyGroup === "position"
) {
removeCallFromMagicString(ms, l.call, script);
}
}
}
return ms.toString();
}
// Flat vars for a tween collapsing its keyframes onto one stop: existing
// top-level props, then the collapse keyframe's props (skip per-keyframe
// `ease`), then extras. Removing all keyframes HOLDS the element statically —
// collapse to a zero-duration immediateRender tween (a `gsap.set` equivalent),
// dropping the original duration/ease so the element does not re-animate.
function buildCollapsedFlatVars(
animation: GsapAnimation,
collapse: { properties: Record<string, number | string> },
): Record<string, number | string | boolean> {
const flat: Record<string, number | string | boolean> = { ...animation.properties };
for (const [k, v] of Object.entries(collapse.properties)) {
if (k !== "ease") flat[k] = v;
}
for (const [k, v] of Object.entries(animation.extras ?? {})) {
if (typeof v === "number" || typeof v === "string") flat[k] = v;
}
// Static hold wins over any carried extras: zero duration + immediateRender,
// no ease.
flat.duration = 0;
flat.immediateRender = true;
return flat;
}
/** Build the full replacement vars object for a tween being converted to keyframes. */
function buildKeyframesVarsCode(
animation: GsapAnimation,
fromProps: Record<string, number | string>,
toProps: Record<string, number | string>,
varsNode: Node,
source: string,
setDuration?: number,
): string {
const fromEntries = Object.entries(fromProps).map(([k, v]) => `${safeKey(k)}: ${valueToCode(v)}`);
const toEntries = Object.entries(toProps).map(([k, v]) => `${safeKey(k)}: ${valueToCode(v)}`);
const easeEntry = animation.ease ? `, easeEach: ${valueToCode(animation.ease)}` : "";
const kfCode = `{ "0%": { ${fromEntries.join(", ")} }, "100%": { ${toEntries.join(", ")} }${easeEntry} }`;
// Preserve every non-editable key (duration/delay/callbacks/stagger/yoyo/…)
// verbatim from source — rebuilding from the animation object alone dropped
// `delay` (not a GsapAnimation field), shifting the tween's start time.
let preserved = preservedVarsEntries(varsNode, source);
// Converting a static `set` → drop its hold markers and give it a real duration
// so the keyframes span time.
if (setDuration !== undefined) {
preserved = preserved.filter((e) => !/^\s*(immediateRender|data|duration)\s*:/.test(e));
}
const parts: string[] = [`keyframes: ${kfCode}`, ...preserved];
if (setDuration !== undefined) parts.push(`duration: ${Math.max(0.001, setDuration)}`);
if (animation.ease) parts.push(`ease: "none"`);
return `{ ${parts.join(", ")} }`;
}
/**
* Convert a flat tween (to/from/fromTo) to percentage-keyframes format.
* `resolvedFromValues` supplies the current DOM state: overrides the 0% endpoint
* for `to()`, the 100% endpoint for `from()`, or merges into toProps for `fromTo()`.
*/
export function convertToKeyframesFromScript(
script: string,
animationId: string,
resolvedFromValues?: Record<string, number | string>,
setDuration = 1,
): string {
const parsed = parseGsapScriptAcornForWrite(script);
if (!parsed) return script;
const target = parsed.located.find((l) => l.id === animationId);
if (!target) return script;
const { animation, call } = target;
if (authorsKeyframes(animation)) return script;
const isSet = call.method === "set";
const { fromProps, toProps } = resolveConversionProps(animation, resolvedFromValues);
const ms = new MagicString(script);
// A GLOBAL `gsap.set(...)` is off-timeline; rewriting only the method emits
// `gsap.to(...)`, which fires once at load and isn't on the paused master
// timeline (the engine can't seek/render it). Re-root onto the timeline var
// and add the position arg the set lacks so the converted tween is seekable.
if (isSet && animation.global) {
const calleeObj = call.node.callee.object;
if (calleeObj?.type === "Identifier") {
ms.overwrite(calleeObj.start, calleeObj.end, parsed.timelineVar);
}
const args = call.node.arguments;
if (args.length > 0 && args.length < 3) {
ms.appendLeft(args[args.length - 1].end, ", 0");
}
}
// set/from/fromTo all become `to`; fromTo also drops its `from` argument.
if (call.method === "from" || call.method === "fromTo" || isSet) {
ms.overwrite(call.node.callee.property.start, call.node.callee.property.end, "to");
}
if (call.method === "fromTo" && call.fromArg) {
ms.remove(call.fromArg.start, call.varsArg.start);
}
overwriteVarsArg(
ms,
call,
buildKeyframesVarsCode(
animation,
fromProps,
toProps,
call.varsArg,
script,
isSet ? setDuration : undefined,
),
);
return ms.toString();
}
// ── Keyframe-object code builder ─────────────────────────────────────────────
/** Build a percentage-keyframes object literal: `{ "0%": { x: 0 }, "100%": { x: 100 } }`. */
function buildKeyframeObjectCode(
keyframes: Array<{
percentage: number;
properties: Record<string, number | string>;
ease?: string;
auto?: boolean;
}>,
easeEach?: string,
): string {
const entries = mergePercentageKeyframes(keyframes).map((kf) => {
const props = Object.entries(kf.properties).map(([k, v]) => `${safeKey(k)}: ${valueToCode(v)}`);
if (kf.ease) props.push(`ease: ${valueToCode(kf.ease)}`);
if (kf.auto) props.push(`_auto: 1`);
return `${JSON.stringify(plainPercentKey(kf.percentage))}: { ${props.join(", ")} }`;
});
if (easeEach) entries.push(`easeEach: ${valueToCode(easeEach)}`);
return `{ ${entries.join(", ")} }`;
}
// ── Materialize keyframes ────────────────────────────────────────────────────
/**
* Replace a dynamic or static keyframes expression with a fully-resolved
* percentage-keyframes object. Called when a user first edits a dynamically-
* generated keyframe in the studio so it becomes statically editable.
*/
export function materializeKeyframesFromScript(
script: string,
animationId: string,
keyframes: Array<{
percentage: number;
properties: Record<string, number | string>;
ease?: string;
}>,
easeEach?: string,
resolvedSelector?: string,
): string {
// An empty keyframe list has no materialized form — rebuilding vars with an
// empty keyframes object would empty the animation. No-op instead.
if (keyframes.length === 0) return script;
const parsed = parseGsapScriptAcornForWrite(script);
if (!parsed) return script;
const target = parsed.located.find((l) => l.id === animationId);
if (!target) return script;
const { call } = target;
const sorted = [...keyframes].sort((a, b) => a.percentage - b.percentage);
const kfObjCode = buildKeyframeObjectCode(sorted, easeEach);
const ms = new MagicString(script);
if (resolvedSelector) {
const selectorArg = call.node.arguments[0];
if (selectorArg)
ms.overwrite(selectorArg.start, selectorArg.end, JSON.stringify(resolvedSelector));
}
const kfProp = findPropertyNode(call.varsArg, "keyframes");
if (kfProp) {
ms.overwrite(kfProp.value.start, kfProp.value.end, kfObjCode);
} else if (call.varsArg?.type === "ObjectExpression") {
const vars = call.varsArg;
if (vars.properties.length > 0) {
ms.prependLeft(vars.properties[0].start, `keyframes: ${kfObjCode}, `);
} else {
ms.appendLeft(vars.end - 1, `keyframes: ${kfObjCode}`);
}
}
const eachProp = findPropertyNode(call.varsArg, "easeEach");
if (eachProp) {
const allProps = (call.varsArg.properties ?? []).filter((p: Node) => isObjectProperty(p));
removeProp(ms, eachProp, allProps);
}
return ms.toString();
}
/**
* Rewrites a tween as `to()` with these keyframes where it stands: the call keeps its place in the
* script and its position argument, so a tween placed after it ('>', '<', '+=', none) stays put.
*/
export function replaceTweenWithKeyframesInScript(
script: string,
animationId: string,
edit: {
targetSelector: string;
position: number;
duration: number;
keyframes: Array<{
percentage: number;
properties: Record<string, number | string>;
ease?: string;
auto?: boolean;
}>;
ease?: string;
easeEach?: string;
},
): string | null {
const parsed = parseGsapScriptAcornForWrite(script);
const target = parsed?.located.find((l) => l.id === animationId);
const call = target?.call;
if (!target || call?.varsArg?.type !== "ObjectExpression") return null;
const { animation } = target;
if (animation.method !== "to" && animation.method !== "from" && animation.method !== "fromTo")
return null;
const ms = new MagicString(script);
const start = animation.resolvedStart ?? animation.position;
const moved = typeof start !== "number" || Math.abs(start - edit.position) > 5e-4;
const kept = preservedVarsEntries(call.varsArg, script).filter(
(e) => !/^\s*duration\s*:/.test(e) && !(moved && /^\s*delay\s*:/.test(e)),
);
const sorted = [...edit.keyframes].sort((a, b) => a.percentage - b.percentage);
const parts = [`keyframes: ${buildKeyframeObjectCode(sorted, edit.easeEach)}`, ...kept];
parts.push(`duration: ${valueToCode(edit.duration)}`);
if (edit.ease) parts.push(`ease: ${valueToCode(edit.ease)}`);
if (animation.hasUnresolvedSelector || animation.targetSelector !== edit.targetSelector) {
const selectorArg = call.node.arguments[0];
ms.overwrite(selectorArg.start, selectorArg.end, JSON.stringify(edit.targetSelector));
}
convertMethodToTo(ms, animation, call, call.varsArg);
overwriteVarsArg(ms, call, `{ ${parts.join(", ")} }`);
if (moved) overwritePosition(ms, call, edit.position);
return ms.toString();
}
// ── Add animation with keyframes ──────────────────────────────────────────────
/** Insert a new keyframed `to()` call and return the new animation ID. */
export function addAnimationWithKeyframesToScript(
script: string,
targetSelector: string,
position: number,
duration: number,
keyframes: Array<{
percentage: number;
properties: Record<string, number | string>;
ease?: string;
auto?: boolean;
}>,
ease?: string,
easeEach?: string,
): { script: string; id: string } {
const parsed = parseGsapScriptAcornForWrite(script);
if (!parsed) return { script, id: "" };
const insertionPoint = findInsertionPoint(parsed);
if (insertionPoint === null) return { script, id: "" };
const sorted = [...keyframes].sort((a, b) => a.percentage - b.percentage);
const kfObjCode = buildKeyframeObjectCode(sorted, easeEach);
const varParts = [`keyframes: ${kfObjCode}`, `duration: ${valueToCode(duration)}`];
if (ease) varParts.push(`ease: ${valueToCode(ease)}`);
const stmtCode = `${parsed.timelineVar}.to(${JSON.stringify(targetSelector)}, { ${varParts.join(", ")} }, ${valueToCode(position)});`;
const ms = new MagicString(script);
ms.appendLeft(insertionPoint, "\n" + stmtCode);
const result = ms.toString();
const reParsed = parseGsapScriptAcornForWrite(result);
const newId = reParsed?.located[reParsed.located.length - 1]?.id ?? "";
return { script: result, id: newId };
}
// ── Split into property groups ────────────────────────────────────────────────
function collectPropertyKeys(anim: GsapAnimation): Set<string> {
const keys = new Set<string>();
if (anim.keyframes) {
for (const kf of anim.keyframes.keyframes) {
for (const k of Object.keys(kf.properties)) keys.add(k);
}
} else {
for (const k of Object.keys(anim.properties)) keys.add(k);
}
return keys;
}
function partitionPropertyGroups(keys: Set<string>): Map<PropertyGroupName, string[]> {
const groups = new Map<PropertyGroupName, string[]>();
for (const key of keys) {
if (key === "transformOrigin") continue;
const group = classifyPropertyGroup(key);
let arr = groups.get(group);
if (!arr) {
arr = [];
groups.set(group, arr);
}
arr.push(key);
}
return groups;
}
function assignTransformOrigin(groupProps: Map<PropertyGroupName, string[]>): void {
let largestGroup: PropertyGroupName | undefined;
let largestCount = 0;
for (const [group, props] of groupProps) {
if (props.length > largestCount) {
largestCount = props.length;
largestGroup = group;
}
}
const largest = largestGroup ? groupProps.get(largestGroup) : undefined;
if (largest) largest.push("transformOrigin");
}
function filterGroupKeyframes(
kfs: GsapPercentageKeyframe[],
propSet: Set<string>,
): Array<{ percentage: number; properties: Record<string, number | string>; ease?: string }> {
const result: Array<{
percentage: number;
properties: Record<string, number | string>;
ease?: string;
}> = [];
for (const kf of kfs) {
const filtered: Record<string, number | string> = {};
for (const [k, v] of Object.entries(kf.properties)) {
if (propSet.has(k)) filtered[k] = v;
}
if (Object.keys(filtered).length > 0) {
result.push({
percentage: kf.percentage,
properties: filtered,
...(kf.ease ? { ease: kf.ease } : {}),
});
}
}
return result;
}
function filterGroupProperties(
properties: Record<string, number | string>,
propSet: Set<string>,
): Record<string, number | string> {
const result: Record<string, number | string> = {};
for (const [k, v] of Object.entries(properties)) {
if (propSet.has(k)) result[k] = v;
}
return result;
}
function addGroupAnimToScript(
script: string,
anim: GsapAnimation,
propSet: Set<string>,
): { script: string; id: string } {
if (anim.keyframes) {
const groupKeyframes = filterGroupKeyframes(anim.keyframes.keyframes, propSet);
if (groupKeyframes.length === 0) return { script, id: "" };
const pos = typeof anim.position === "number" ? anim.position : 0;
return addAnimationWithKeyframesToScript(
script,
anim.targetSelector,
pos,
anim.duration ?? 0.5,
groupKeyframes,
anim.keyframes.ease ?? anim.ease,
anim.keyframes.easeEach,
);
}
const groupProperties = filterGroupProperties(anim.properties, propSet);
if (Object.keys(groupProperties).length === 0) return { script, id: "" };
const fromProperties =
anim.method === "fromTo" && anim.fromProperties
? filterGroupProperties(anim.fromProperties, propSet)
: undefined;
return addAnimationToScript(script, {
targetSelector: anim.targetSelector,
method: anim.method,
position: anim.position,
duration: anim.duration,
ease: anim.ease,
properties: groupProperties,
fromProperties,
extras: anim.extras,
});
}
/**
* Split a mixed-property tween into one tween per property group (position,
* scale, visual, etc.) so each group can be edited independently.
* Returns the updated script and the IDs of the newly-created tweens.
*/
export function splitIntoPropertyGroupsFromScript(
script: string,
animationId: string,
): { script: string; ids: string[] } {
const parsed = parseGsapScriptAcornForWrite(script);
if (!parsed) return { script, ids: [animationId] };
const target = parsed.located.find((l) => l.id === animationId);
if (!target) return { script, ids: [animationId] };
const { animation } = target;
if (animation.hasUnresolvedKeyframes) return { script, ids: [animationId] };
const allPropKeys = collectPropertyKeys(animation);
const groupProps = partitionPropertyGroups(allPropKeys);
if (groupProps.size <= 1) return { script, ids: [animationId] };
if (allPropKeys.has("transformOrigin")) assignTransformOrigin(groupProps);
let result = removeAnimationFromScript(script, animationId);
for (const [, props] of groupProps) {
const { script: next, id } = addGroupAnimToScript(result, animation, new Set(props));
if (id) result = next;
}
const reParsed = parseGsapScriptAcornForWrite(result);
const newIds = (reParsed?.located ?? [])
.filter((l) => l.animation.targetSelector === animation.targetSelector)
.map((l) => l.id);
return { script: result, ids: newIds };
}
// ── Label write ops ───────────────────────────────────────────────────────────
/** True when `expr` is `tl.<method>(…)` rooted at the timeline var. */
function isTimelineMethodCall(
expr: Node,
timelineVar: string,
method: string,
script: string,
): boolean {
return (
expr?.type === "CallExpression" &&
expr.callee?.type === "MemberExpression" &&
isTimelineRooted(expr.callee.object, timelineVar, script) &&
expr.callee.property?.name === method
);
}
/** True when `expr` is `tl.addLabel("<name>", …)` rooted at the timeline var. */
function isAddLabelCall(expr: Node, timelineVar: string, name: string, script: string): boolean {
const firstArg = expr?.arguments?.[0];
return (
isTimelineMethodCall(expr, timelineVar, "addLabel", script) &&
firstArg?.type === "Literal" &&
firstArg.value === name
);
}
/** Every `tl.addLabel("<name>", …)` ExpressionStatement in the script. */
function findLabelStatements(
parsed: ParsedGsapAcornForWrite,
name: string,
script: string,
): Node[] {
const targets: Node[] = [];
acornWalk.simple(parsed.ast, {
ExpressionStatement(node: Node) {
if (isAddLabelCall(node.expression, parsed.timelineVar, name, script)) targets.push(node);
},
});
return targets;
}
export function addLabelToScript(script: string, name: string, position: number): string {
const parsed = parseGsapScriptAcornForWrite(script);
if (!parsed) return script;
// If the label already exists, MOVE it (overwrite its position) rather than
// appending a duplicate. Two same-named addLabel statements make removeLabel
// over-remove — it deletes every match, including a pre-existing label the
// user never touched.
const existing = findLabelStatements(parsed, name, script)[0];
if (existing) {
const ms = new MagicString(script);
const posArg = existing.expression.arguments?.[1];
if (posArg) ms.overwrite(posArg.start, posArg.end, valueToCode(position));
else ms.appendLeft(existing.expression.end - 1, `, ${valueToCode(position)}`);
return ms.toString();
}
const insertionPoint = findInsertionPoint(parsed);
if (insertionPoint === null) return script;
const ms = new MagicString(script);
const labelCode = `${parsed.timelineVar}.addLabel(${JSON.stringify(name)}, ${valueToCode(position)});`;
ms.appendLeft(insertionPoint, "\n" + labelCode);
return ms.toString();
}
export function removeLabelFromScript(script: string, name: string): string {
const parsed = parseGsapScriptAcornForWrite(script);
if (!parsed) return script;
const targets = findLabelStatements(parsed, name, script);
if (!targets.length) return script;
const ms = new MagicString(script);
for (const target of targets) {
const end =
target.end < script.length && script[target.end] === "\n" ? target.end + 1 : target.end;
ms.remove(target.start, end);
}
return ms.toString();
}
// ── Arc path helpers ─────────────────────────────────────────────────────────
/**
* Remove a set of properties from an ObjectExpression in a single pass.
* Groups consecutive marked props into blocks to avoid overlapping remove ranges.
*/
function removePropsByKey(ms: MagicString, objNode: Node, keys: Set<string>): void {
if (objNode?.type !== "ObjectExpression") return;
const allProps = (objNode.properties ?? []).filter(isObjectProperty);
const marked = allProps.map((p: Node) => keys.has(propKeyName(p) ?? ""));
let i = 0;
while (i < allProps.length) {
if (!marked[i]) {
i++;
continue;
}
const blockStart = i;
while (i < allProps.length && marked[i]) i++;
ms.remove(...blockRemoveRange(allProps, blockStart, i));
}
}
function blockRemoveRange(
allProps: Node[],
blockStart: number,
blockEnd: number,
): [number, number] {
if (blockStart === 0 && blockEnd === allProps.length)
return [allProps[0].start, allProps[allProps.length - 1].end];
if (blockStart === 0) return [allProps[0].start, allProps[blockEnd].start];
return [allProps[blockStart - 1].end, allProps[blockEnd - 1].end];
}
// fallow-ignore-next-line complexity
function readLastWaypointXY(mpVal: Node): { x: number | null; y: number | null } {
if (mpVal?.type !== "ObjectExpression") return { x: null, y: null };
const pathProp = findPropertyNode(mpVal, "path");
if (pathProp?.value?.type !== "ArrayExpression") return { x: null, y: null };
const elems: Node[] = pathProp.value.elements ?? [];
const last = elems[elems.length - 1];
if (last?.type !== "ObjectExpression") return { x: null, y: null };
return {
x: readNumericLiteralNode(findPropertyNode(last, "x")?.value),
y: readNumericLiteralNode(findPropertyNode(last, "y")?.value),
};
}
/**
* Read a numeric value node — a plain numeric literal or a unary-minus negative
* literal (e.g. `-120`). Returns null for anything non-numeric. Without the
* UnaryExpression branch, negative waypoint coords (parsed as a UnaryExpression
* with no `.value`) would be lost when disabling an arc path.
*/
function readNumericLiteralNode(v: Node): number | null {
if (LITERAL_NODE_TYPES.has(v?.type) && typeof v.value === "number") return v.value;
if (
v?.type === "UnaryExpression" &&
v.operator === "-" &&
typeof v.argument?.value === "number"
) {
return -v.argument.value;
}
return null;
}
function disableArcPath(ms: MagicString, call: TweenCallInfo): boolean {
const mpProp = findPropertyNode(call.varsArg, "motionPath");
if (!mpProp) return false;
const { x, y } = readLastWaypointXY(mpProp.value);
if (x === null && y === null) {
const allProps = (call.varsArg.properties ?? []).filter(isObjectProperty);
removeProp(ms, mpProp, allProps);
return true;
}
// Overwrite the entire motionPath property with the recovered x/y pair — avoids
// the appendLeft+remove range-boundary issue in MagicString.
const parts: string[] = [];
if (x !== null) parts.push(`x: ${x}`);
if (y !== null) parts.push(`y: ${y}`);
ms.overwrite(mpProp.start, mpProp.end, parts.join(", "));
return true;
}
function stripXYFromKeyframes(ms: MagicString, kfPropNode: Node): void {
if (kfPropNode?.value?.type !== "ObjectExpression") return;
const xyKeys = new Set(["x", "y"]);
for (const pctProp of (kfPropNode.value.properties ?? []).filter(isObjectProperty)) {
const k = propKeyName(pctProp);
if (typeof k === "string" && k.endsWith("%") && pctProp.value?.type === "ObjectExpression") {
removePropsByKey(ms, pctProp.value, xyKeys);
}
}
}
function enableArcPath(
ms: MagicString,
call: TweenCallInfo,
animation: GsapAnimation,
config: ArcPathConfig,
): boolean {
const waypoints = extractArcWaypoints(animation);
if (waypoints.length < 2) return false;
const segments: ArcPathSegment[] =
config.segments.length === waypoints.length - 1
? config.segments
: Array.from({ length: waypoints.length - 1 }, () => ({ curviness: 1 }));
const motionPathCode = buildMotionPathObjectCode({
waypoints,
segments,
autoRotate: config.autoRotate,
});
const vars = call.varsArg;
if (vars?.type !== "ObjectExpression") return false;
// Insert motionPath right after the opening `{` (appendRight at start+1) so the
// insertion point can never coincide with the end boundary of the x/y removal
// range. upsertProp would appendLeft at `end - 1`, which collides with a
// remove-range that ends at the same offset when x/y are the only props —
// MagicString then discards the append and the output loses everything.
const editable = (vars.properties ?? []).filter(isObjectProperty);
const survivesRemoval = editable.some((p: Node) => {
const k = propKeyName(p);
return k !== "x" && k !== "y";
});
const sep = survivesRemoval ? ", " : "";
ms.appendRight(vars.start + 1, ` motionPath: ${motionPathCode}${sep}`);
stripXYFromKeyframes(ms, findPropertyNode(call.varsArg, "keyframes"));
removePropsByKey(ms, call.varsArg, new Set(["x", "y"]));
return true;
}
export function setArcPathInScript(
script: string,
animationId: string,
config: ArcPathConfig,
): string {
const parsed = parseGsapScriptAcornForWrite(script);
if (!parsed) return script;
const target = parsed.located.find((l) => l.id === animationId);
if (!target) return script;
const ms = new MagicString(script);
const handled = config.enabled
? enableArcPath(ms, target.call, target.animation, config)
: disableArcPath(ms, target.call);
return handled ? ms.toString() : script;
}
export function updateArcSegmentInScript(
script: string,
animationId: string,
segmentIndex: number,
update: Partial<ArcPathSegment>,
): string {
const parsed = parseGsapScriptAcornForWrite(script);
if (!parsed) return script;
const target = parsed.located.find((l) => l.id === animationId);
if (!target) return script;
const { call, animation } = target;
if (!animation.arcPath?.enabled) return script;
const segments = [...animation.arcPath.segments];
const existingSeg = segments[segmentIndex];
if (segmentIndex < 0 || segmentIndex >= segments.length || !existingSeg) return script;
segments[segmentIndex] = { ...existingSeg, ...update };
const waypoints = extractArcWaypoints(animation);
if (waypoints.length < 2) return script;
const motionPathCode = buildMotionPathObjectCode({
waypoints,
segments,
autoRotate: animation.arcPath.autoRotate,
});
const mpProp = findPropertyNode(call.varsArg, "motionPath");
if (!mpProp) return script;
const ms = new MagicString(script);
ms.overwrite(mpProp.value.start, mpProp.value.end, motionPathCode);
return ms.toString();
}
function hasCubicSegments(segments: ArcPathSegment[]): boolean {
return segments.some((segment) => segment.cp1 != null || segment.cp2 != null);
}
function writeMotionPathValue(
script: string,
target: ParsedGsapAcornForWrite["located"][number],
waypoints: Array<{ x: number; y: number }>,
segments: ArcPathSegment[],
autoRotate: boolean | number,
): string {
const motionPath = findPropertyNode(target.call.varsArg, "motionPath");
if (!motionPath) return script;
const code = buildMotionPathObjectCode({ waypoints, segments, autoRotate });
const ms = new MagicString(script);
ms.overwrite(motionPath.value.start, motionPath.value.end, code);
return ms.toString();
}
export function updateMotionPathPointInScript(
script: string,
animationId: string,
pointIndex: number,
point: { x: number; y: number },
): string {
const parsed = parseGsapScriptAcornForWrite(script);
const target = parsed?.located.find((entry) => entry.id === animationId);
if (!target?.animation.arcPath?.enabled) return script;
const waypoints = extractArcWaypoints(target.animation);
if (waypoints.length < 2 || pointIndex < 0 || pointIndex >= waypoints.length) return script;
const next = waypoints.map((waypoint, index) => (index === pointIndex ? { ...point } : waypoint));
return writeMotionPathValue(
script,
target,
next,
target.animation.arcPath.segments,
target.animation.arcPath.autoRotate,
);
}
export function addMotionPathPointInScript(
script: string,
animationId: string,
index: number,
point: { x: number; y: number },
): string {
const parsed = parseGsapScriptAcornForWrite(script);
const target = parsed?.located.find((entry) => entry.id === animationId);
const arc = target?.animation.arcPath;
if (!target || !arc?.enabled || hasCubicSegments(arc.segments)) return script;
const waypoints = extractArcWaypoints(target.animation);
if (index < 1 || index > waypoints.length - 1) return script;
const segments = [...arc.segments];
waypoints.splice(index, 0, { ...point });
segments.splice(index - 1, 0, { curviness: segments[index - 1]?.curviness ?? 1 });
return writeMotionPathValue(script, target, waypoints, segments, arc.autoRotate);
}
export function removeMotionPathPointInScript(
script: string,
animationId: string,
index: number,
): string {
const parsed = parseGsapScriptAcornForWrite(script);
const target = parsed?.located.find((entry) => entry.id === animationId);
const arc = target?.animation.arcPath;
if (!target || !arc?.enabled || hasCubicSegments(arc.segments)) return script;
const waypoints = extractArcWaypoints(target.animation);
if (waypoints.length <= 2 || index < 0 || index >= waypoints.length) return script;
const segments = [...arc.segments];
waypoints.splice(index, 1);
segments.splice(Math.min(index, segments.length - 1), 1);
return writeMotionPathValue(script, target, waypoints, segments, arc.autoRotate);
}
export function addMotionPathToScript(
script: string,
targetSelector: string,
position: number,
duration: number,
point: { x: number; y: number },
ease = "power1.inOut",
): { script: string; id: string | null } {
const motionPath = buildMotionPathObjectCode({
waypoints: [{ x: 0, y: 0 }, { ...point }],
segments: [{ curviness: 1 }],
autoRotate: false,
});
const result = addAnimationToScript(script, {
targetSelector,
method: "to",
position,
duration,
ease,
properties: { motionPath: `__raw:${motionPath}` },
});
return { script: result.script, id: result.id || null };
}
export function removeArcPathFromScript(script: string, animationId: string): string {
return setArcPathInScript(script, animationId, {
enabled: false,
autoRotate: false,
segments: [],
});
}
// ── splitAnimationsInScript helpers ──────────────────────────────────────────
/** Overwrite the selector (first arg) of a tween call. */
function updateAnimationSelectorInScript(
script: string,
animationId: string,
newSelector: string,
): string {
const parsed = parseGsapScriptAcornForWrite(script);
if (!parsed) return script;
const target = parsed.located.find((l) => l.id === animationId);
if (!target) return script;
const selectorArg = target.call.node.arguments?.[0];
if (!selectorArg) return script;
const ms = new MagicString(script);
ms.overwrite(selectorArg.start, selectorArg.end, JSON.stringify(newSelector));
return ms.toString();
}
/**
* Insert a `tl.set()` call immediately after the timeline declaration
* (before existing tweens) to establish inherited state on a new element.
*/
function insertInheritedStateSetInScript(
script: string,
selector: string,
position: number,
properties: Record<string, number | string>,
): string {
const parsed = parseGsapScriptAcornForWrite(script);
if (!parsed) return script;
const props = Object.entries(properties)
.map(([k, v]) => `${safeKey(k)}: ${valueToCode(v)}`)
.join(", ");
const code = `${parsed.timelineVar}.set(${JSON.stringify(selector)}, { ${props} }, ${position});`;
const ms = new MagicString(script);
const tlDecl = findTimelineDeclarationStatement(parsed.ast, parsed.timelineVar);
const firstLocated = parsed.located[0];
if (tlDecl) {
const ownLineEnd = script[tlDecl.end] === "\n" ? "" : "\n";
ms.appendLeft(tlDecl.end, "\n" + code + ownLineEnd);
} else if (firstLocated) {
const firstCall = firstLocated.call;
const exprStmt = findEnclosingExpressionStatement(firstCall.ancestors);
const insertAt = exprStmt?.start ?? firstCall.node.start;
ms.prependLeft(insertAt, code + "\n");
} else {
ms.append("\n" + code);
}
return ms.toString();
}
const STUDIO_HOLD_MARKER = "hf-hold";
function isStudioHoldSet(animation: GsapAnimation): boolean {
return animation.method === "set" && animation.properties.data === STUDIO_HOLD_MARKER;
}
function removeStudioHoldSets(script: string, parsed: ParsedGsapAcornForWrite): string {
const staleHolds = parsed.located.filter((entry) => isStudioHoldSet(entry.animation));
if (staleHolds.length === 0) return script;
const ms = new MagicString(script);
for (const hold of staleHolds) removeCallFromMagicString(ms, hold.call, script);
return ms.toString();
}
/** Acorn-native, byte-preserving hold synchronization used after mutations. */
export function syncPositionHoldsBeforeKeyframes(script: string, previous?: string): string {
const parsed = parseGsapScriptAcornForWrite(script);
if (!parsed) return script;
const tweensOf = (text: string) =>
parseGsapScriptAcornForWrite(text)?.located.map((entry) => entry.animation) ?? null;
const scope = holdScope(
parsed.located.map((entry) => entry.animation),
previous === undefined ? null : tweensOf(previous),
);
let result = removeStudioHoldSets(script, parsed);
const current = parseGsapScriptAcornForWrite(result);
if (!current) return result;
const animations = current.located.map((entry) => entry.animation);
for (const animation of animations) {
const position = keyframeHoldForAnimation(animation, animations, scope);
if (!position) continue;
result = insertInheritedStateSetInScript(result, animation.targetSelector, 0, {
...position,
data: STUDIO_HOLD_MARKER,
});
}
return result;
}
const roundPct = (pct: number) => Math.round(pct * 1000) / 1000;
const LINEAR_RUN = new Set(["none", "linear"]);
// ponytail: any .add( .duration( repeat: or yoyo: in the script skips the trim, classList.add included.
const PLACED_BY_TIMELINE =
/\.(?:add|addLabel|addPause|call|repeat|yoyo|duration|timeScale)\s*\(|\b(?:repeat|yoyo)\s*:/;
/** A percentage keyframe list whose timing is known and whose run is linear, so a trim keeps its render. */
function linearPercentageKeys(animation: GsapAnimation) {
const data = animation.keyframes;
if (data?.format !== "percentage" || data.fromMotionPath || animation.arcPath) return null;
if (animation.durationUnresolved || !LINEAR_RUN.has(animation.ease || "none")) return null;
return data.keyframes;
}
const loops = (animation: GsapAnimation) =>
Boolean(animation.extras?.repeat || animation.extras?.yoyo);
function trimmableKeyframes(animation: GsapAnimation) {
const keyframes = loops(animation) ? null : linearPercentageKeys(animation);
const { duration, position } = animation;
if (!keyframes || typeof position !== "number" || typeof duration !== "number") return null;
return duration > 0 ? { keyframes, duration, position } : null;
}
/** The keyless tail of a keyframe tween, as the remap that ends it on its last key; null when it has none. */
function trailingSpanTrim(animation: GsapAnimation) {
const tween = trimmableKeyframes(animation);
if (!tween) return null;
const last = Math.max(...tween.keyframes.map((keyframe) => keyframe.percentage));
if (tween.keyframes.length < 2 || !(last > 0) || last >= 99.999) return null;
return {
position: tween.position,
duration: Math.round(tween.duration * last * 10) / 1000,
pctRemap: tween.keyframes.map(({ percentage: from }) => ({
from,
to: roundPct((from / last) * 100),
})),
};
}
/** GSAP 3.15 stretches a keyframe tween that stops short of 100% on its first render, unlike once played:
* each tween this mutation wrote or edited ends on its last key instead. Tweens it left alone keep their tail. */
export function trimTrailingKeyframeSpans(previous: string, script: string): string {
if (script === previous) return script;
const located = parseGsapScriptAcornForWrite(script)?.located ?? [];
// A shorter tween moves what is placed after its end ("+=", ">", no position, add/call/addLabel).
const placedAfter = ({ animation: a }: { animation: GsapAnimation }) =>
!a.global && (a.implicitPosition || typeof a.position !== "number");
if (PLACED_BY_TIMELINE.test(script) || located.some(placedAfter)) return script;
const trims = located.flatMap((entry) => {
const trim = trailingSpanTrim(entry.animation);
return trim ? [{ entry, trim }] : [];
});
if (!trims.length) return script;
const source = (text: string, { call }: { call: TweenCallInfo }) =>
`${call.method}${text.slice(call.node.arguments[0]?.start, call.node.end)}`;
const previousTweens = parseGsapScriptAcornForWrite(previous)?.located ?? [];
const untouched = new Set(previousTweens.map((entry) => source(previous, entry)));
let result = script;
for (const { entry, trim } of trims) {
if (untouched.has(source(script, entry))) continue;
result = resizeKeyframedTweenInScript(
result,
entry.id,
trim.position,
trim.duration,
trim.pctRemap,
);
}
return result;
}
/**
* Compute, in forward (timeline) order, the inherited-props baseline available
* BEFORE each matching tween, plus the final cumulative state at the split point.
* A tween contributes to later baselines when it ends at/before the split (full
* props or last keyframe), spans the split via keyframes (kfs at/before split),
* or spans the split as a flat tween (its interpolated midpoint). Decoupled from
* the reverse write loop so the spanning-tween midpoint reads earlier tweens.
*/
// fallow-ignore-next-line complexity
function computeForwardBaselines(
matching: GsapAnimation[],
splitTime: number,
): { before: Array<Record<string, number | string>>; final: Record<string, number | string> } {
const before: Array<Record<string, number | string>> = [];
const acc: Record<string, number | string> = {};
for (const anim of matching) {
before.push({ ...acc });
const pos = typeof anim.position === "number" ? anim.position : 0;
const dur = anim.duration ?? 0;
const animEnd = pos + dur;
if (authorsKeyframes(anim)) {
const kfs = anim.keyframes?.keyframes ?? [];
if (pos >= splitTime) {
// Moves wholly to the new element — contributes nothing to the baseline.
} else if (animEnd > splitTime) {
for (const kf of kfs) {
const kfTime = pos + (kf.percentage / 100) * dur;
if (kfTime <= splitTime) {
for (const [k, v] of Object.entries(kf.properties)) acc[k] = v;
}
}
} else {
const lastKf = kfs[kfs.length - 1];
if (lastKf) {
for (const [k, v] of Object.entries(lastKf.properties)) acc[k] = v;
}
}
continue;
}
if (animEnd <= splitTime) {
for (const [k, v] of Object.entries(anim.properties)) acc[k] = v;
continue;
}
if (pos >= splitTime) continue;
// Flat tween spanning the split — its midpoint becomes the inherited value.
const progress = dur > 0 ? (splitTime - pos) / dur : 0;
const fromSource = anim.fromProperties ?? acc;
for (const [k, v] of Object.entries(anim.properties)) {
if (typeof v !== "number") {
acc[k] = v;
continue;
}
const fromVal = typeof fromSource[k] === "number" ? (fromSource[k] as number) : 0;
acc[k] = fromVal + (v - fromVal) * progress;
}
}
return { before, final: { ...acc } };
}
// Split one tween that straddles the split point: trim the original to the
// first half (interpolated midpoint as its new end) and add a fromTo for the
// second half on the new element. `fromSource` is the forward baseline.
function buildSpanningSplit(
result: string,
anim: GsapAnimation,
pos: number,
dur: number,
fromSource: Record<string, number | string>,
ctx: { splitTime: number; newSelector: string; newElementStart: number },
): string {
const progress = dur > 0 ? (ctx.splitTime - pos) / dur : 0;
const midProps: Record<string, number | string> = {};
for (const [k, v] of Object.entries(anim.properties)) {
if (typeof v !== "number") {
midProps[k] = v;
continue;
}
const fromVal = typeof fromSource[k] === "number" ? (fromSource[k] as number) : 0;
midProps[k] = fromVal + (v - fromVal) * progress;
}
const trimmed = updateAnimationInScript(result, anim.id, {
duration: ctx.splitTime - pos,
properties: midProps,
});
return addAnimationToScript(trimmed, {
targetSelector: ctx.newSelector,
method: "fromTo",
position: ctx.newElementStart,
duration: pos + dur - ctx.splitTime,
properties: { ...anim.properties },
fromProperties: { ...midProps },
ease: anim.ease,
extras: anim.extras,
}).script;
}
type SplitCtx = {
splitTime: number;
originalSelector: string;
newSelector: string;
newElementStart: number;
};
function applyKeyframedTweenSplit(
result: string,
anim: GsapAnimation,
pos: number,
animEnd: number,
ctx: SplitCtx,
skippedSelectors: string[],
): string {
if (pos >= ctx.splitTime)
return updateAnimationSelectorInScript(result, anim.id, ctx.newSelector);
if (animEnd > ctx.splitTime) {
skippedSelectors.push(`${ctx.originalSelector} (keyframes spanning split)`);
} else if (anim.hasUnresolvedKeyframes) {
skippedSelectors.push(`${ctx.originalSelector} (unreadable keyframes before split)`);
}
return result;
}
// Decide what one matching tween does at the split point: move to the new
// element (wholly after), stay (wholly before / keyframes before), get skipped
// (keyframes spanning), or get interpolated in half (spanning). Returns the
// updated script; pushes any skip reason into `skippedSelectors`.
function applyTweenSplit(
result: string,
anim: GsapAnimation,
baselineBefore: Record<string, number | string>,
ctx: SplitCtx,
skippedSelectors: string[],
): string {
const pos = typeof anim.position === "number" ? anim.position : 0;
const dur = anim.duration ?? 0;
const animEnd = pos + dur;
if (authorsKeyframes(anim)) {
return applyKeyframedTweenSplit(result, anim, pos, animEnd, ctx, skippedSelectors);
}
// Wholly before the split — kept on the original element.
if (animEnd <= ctx.splitTime) return result;
// Wholly after — move to the new element.
if (pos >= ctx.splitTime)
return updateAnimationSelectorInScript(result, anim.id, ctx.newSelector);
// Spans the split — interpolate the midpoint from the FORWARD baseline.
const fromSource = anim.fromProperties ?? baselineBefore;
return buildSpanningSplit(result, anim, pos, dur, fromSource, ctx);
}
export function splitAnimationsInScript(
script: string,
opts: SplitAnimationsOptions,
): SplitAnimationsResult {
const parsed = parseGsapScriptAcornForWrite(script);
if (!parsed) return { script, skippedSelectors: [] };
const originalSelector = `#${opts.originalId}`;
const newSelector = `#${opts.newId}`;
const animations = parsed.located.map((l) => l.animation);
const skippedSelectors: string[] = [];
for (const a of animations) {
if (a.targetSelector !== originalSelector && a.targetSelector.includes(opts.originalId)) {
skippedSelectors.push(a.targetSelector);
}
}
const matching = animations.filter((a) => a.targetSelector === originalSelector);
if (matching.length === 0) return { script, skippedSelectors };
let result = script;
const newElementStart = opts.splitTime;
// Forward pre-pass: compute the inherited-props baseline available BEFORE each
// matching tween, in source/timeline order. The write loop below runs in
// REVERSE (so updateAnimationSelectorInScript's selector edits can't shift the
// count-based IDs of not-yet-processed tweens), but the spanning-tween midpoint
// interpolation needs the baseline from EARLIER tweens — which a reverse
// accumulator hasn't seen yet. Decoupling the two fixes the wrong midpoint.
const { before: baselineBefore, final: finalInheritedProps } = computeForwardBaselines(
matching,
opts.splitTime,
);
// Reverse iteration: updateAnimationSelectorInScript mutates selectors which
// can shift count-based ID suffixes for later animations.
const ctx = { splitTime: opts.splitTime, originalSelector, newSelector, newElementStart };
for (let i = matching.length - 1; i >= 0; i--) {
const anim = matching[i];
if (!anim) continue;
result = applyTweenSplit(result, anim, baselineBefore[i] ?? {}, ctx, skippedSelectors);
}
if (Object.keys(finalInheritedProps).length > 0) {
result = insertInheritedStateSetInScript(
result,
newSelector,
newElementStart,
finalInheritedProps,
);
}
return { script: result, skippedSelectors };
}
// ── Unroll dynamic animations ────────────────────────────────────────────────
function isLoopNode(node: Node): boolean {
const t = node?.type;
return (
t === "ForStatement" ||
t === "ForInStatement" ||
t === "ForOfStatement" ||
t === "WhileStatement"
);
}
function isForEachStatement(node: Node): boolean {
return (
node?.type === "ExpressionStatement" &&
node.expression?.type === "CallExpression" &&
node.expression.callee?.property?.name === "forEach"
);
}
/** The nearest enclosing loop / forEach AST node (not just its byte range). */
function findEnclosingLoopNode(ancestors: Node[]): Node | null {
for (let i = ancestors.length - 2; i >= 0; i--) {
const node = ancestors[i];
if (isLoopNode(node) || isForEachStatement(node)) return node;
}
return null;
}
/** Statements making up a loop's body block, or null when not a simple block. */
function loopBodyStatements(loopNode: Node): Node[] | null {
let body: Node;
if (loopNode?.type === "ExpressionStatement") {
// forEach(cb): body is the callback's block.
const cb = loopNode.expression?.arguments?.[0];
body = cb?.body;
} else {
body = loopNode?.body;
}
if (body?.type !== "BlockStatement") return null;
return (body.body ?? []).filter((s: Node) => s?.type === "ExpressionStatement");
}
/** The loop's index identifier name (`for (let i …)`), used for per-iteration substitution. */
function loopIndexVarName(loopNode: Node): string | null {
if (loopNode?.type === "ForStatement") {
const decl = loopNode.init?.declarations?.[0];
return typeof decl?.id?.name === "string" ? decl.id.name : null;
}
return null;
}
/**
* Rewrite one body statement's source for iteration `idx`: replace USES of the
* loop index variable (AST Identifier nodes) with the literal index. AST-based,
* not a text regex, so the index name appearing inside a string literal (e.g. a
* selector ".row-i") or as a non-computed member/key (`obj.i`, `{ i: … }`) is
* left untouched — only real references to the variable are substituted.
*/
// An identifier in "binding position" is a name, not a value reference: a
// non-computed member property (`obj.i`) or object-literal key (`{ i: … }`).
// Those must NOT be substituted with the iteration index.
function isIndexBindingPosition(node: Node, parent: Node): boolean {
if (parent?.type === "MemberExpression") return parent.property === node && !parent.computed;
if (parent?.type === "Property" || parent?.type === "ObjectProperty") {
return parent.key === node && !parent.computed;
}
return false;
}
function substituteLoopIndex(stmt: Node, indexVar: string, idx: number, script: string): string {
const base = stmt.start as number;
const src = script.slice(base, stmt.end as number);
const ranges: Array<[number, number]> = [];
acornWalk.ancestor(stmt, {
Identifier(node: Node, _state: unknown, ancestors: Node[]) {
if (node.name !== indexVar) return;
if (isIndexBindingPosition(node, ancestors[ancestors.length - 2])) return;
ranges.push([(node.start as number) - base, (node.end as number) - base]);
},
});
if (ranges.length === 0) return src;
ranges.sort((a, b) => b[0] - a[0]);
let out = src;
for (const [s, e] of ranges) out = out.slice(0, s) + String(idx) + out.slice(e);
return out;
}
function buildUnrollReplacement(
timelineVar: string,
animation: GsapAnimation,
elements: Array<{
selector: string;
keyframes: Array<{ percentage: number; properties: Record<string, number | string> }>;
easeEach?: string;
}>,
): string {
const duration = typeof animation.duration === "number" ? animation.duration : 8;
const ease = typeof animation.ease === "string" ? animation.ease : "none";
const pos = animation.position ?? 0;
const posCode = typeof pos === "number" ? String(pos) : JSON.stringify(pos);
const calls = elements.map((el) => {
const sorted = [...el.keyframes].sort((a, b) => a.percentage - b.percentage);
const kfCode = buildKeyframeObjectCode(sorted, el.easeEach);
return `${timelineVar}.to(${JSON.stringify(el.selector)}, { keyframes: ${kfCode}, duration: ${duration}, ease: ${valueToCode(ease)} }, ${posCode});`;
});
return calls.join("\n ");
}
export type UnrollElement = {
selector: string;
keyframes: Array<{ percentage: number; properties: Record<string, number | string> }>;
easeEach?: string;
};
/** Build one element's unrolled `tl.to(...)` call from the target animation. */
function buildUnrollCallForElement(
timelineVar: string,
animation: GsapAnimation,
el: UnrollElement,
): string {
const duration = typeof animation.duration === "number" ? animation.duration : 8;
const ease = typeof animation.ease === "string" ? animation.ease : "none";
const pos = animation.position ?? 0;
const posCode = typeof pos === "number" ? String(pos) : JSON.stringify(pos);
const sorted = [...el.keyframes].sort((a, b) => a.percentage - b.percentage);
const kfCode = buildKeyframeObjectCode(sorted, el.easeEach);
return `${timelineVar}.to(${JSON.stringify(el.selector)}, { keyframes: ${kfCode}, duration: ${duration}, ease: ${valueToCode(ease)} }, ${posCode});`;
}
/** Sentinel: the unroll cannot safely reproduce the loop body — caller no-ops. */
const REFUSE_UNROLL = Symbol("refuse-unroll");
/** Every statement in a loop's body block (unfiltered), or [] when not a block. */
function loopBodyRawStatements(loopNode: Node): Node[] {
const body =
loopNode?.type === "ExpressionStatement"
? loopNode.expression?.arguments?.[0]?.body
: loopNode?.body;
return body?.type === "BlockStatement" ? (body.body ?? []) : [];
}
/** A node that re-binds `indexVar`: a re-declaration or a function param. */
function rebindsIndex(node: Node, indexVar: string): boolean {
if (node.type === "VariableDeclarator") return node.id?.name === indexVar;
if (
node.type === "FunctionExpression" ||
node.type === "FunctionDeclaration" ||
node.type === "ArrowFunctionExpression"
) {
return (node.params ?? []).some((p: Node) => p?.name === indexVar);
}
return false;
}
/** Object shorthand `{ i }` — substituting the value would yield invalid `{ 0 }`. */
function isShorthandIndexUse(node: Node, indexVar: string): boolean {
return (
(node.type === "Property" || node.type === "ObjectProperty") &&
node.shorthand === true &&
propKeyName(node) === indexVar
);
}
/**
* A sibling statement can't be safely index-substituted when it re-binds the
* loop index (shadowing — a nested `for (let i …)`, a callback param `i`) or
* uses it in object shorthand (`{ i }`, which would splice to the invalid
* `{ 0 }`). substituteLoopIndex has no scope analysis, so in these cases it
* would emit broken or wrong code — the unroll must refuse instead.
*/
function hasUnsafeLoopIndexUse(stmt: Node, indexVar: string): boolean {
let unsafe = false;
acornWalk.full(stmt, (node: Node) => {
if (!unsafe && (isShorthandIndexUse(node, indexVar) || rebindsIndex(node, indexVar))) {
unsafe = true;
}
});
return unsafe;
}
/** How to handle the loop body's non-target siblings when unrolling. */
function unrollSiblingStrategy(
loopNode: Node,
targetStmt: Node,
stmts: Node[],
indexVar: string | null,
): "blanket" | "refuse" | "preserve" {
const siblings = stmts.filter((s) => s !== targetStmt);
// A sibling the filtered statement list doesn't model (non-ExpressionStatement)
// would be silently lost by either path — refuse if any exists.
const hasUnmodeledSibling = loopBodyRawStatements(loopNode).some(
(s) => s !== targetStmt && !stmts.includes(s),
);
if (siblings.length === 0 && !hasUnmodeledSibling) return "blanket";
if (hasUnmodeledSibling || !indexVar) return "refuse";
return siblings.some((s) => hasUnsafeLoopIndexUse(s, indexVar)) ? "refuse" : "preserve";
}
/** Emit the per-iteration unrolled lines (target → static tl.to, siblings → index-substituted). */
function emitUnrolledLines(
stmts: Node[],
targetStmt: Node,
elements: UnrollElement[],
timelineVar: string,
animation: GsapAnimation,
indexVar: string,
script: string,
): string {
const lines: string[] = [];
for (let idx = 0; idx < elements.length; idx++) {
const el = elements[idx];
if (!el) continue;
for (const stmt of stmts) {
lines.push(
stmt === targetStmt
? buildUnrollCallForElement(timelineVar, animation, el)
: substituteLoopIndex(stmt, indexVar, idx, script),
);
}
}
return lines.join("\n ");
}
/**
* Unroll the loop body, preserving every statement that is NOT the target tween.
* For each iteration, emit each non-target statement with the loop index
* substituted (e.g. `tl.set(items[i], …)` → `tl.set(items[0], …)`), and replace
* the target tween statement with that element's static `tl.to()` call.
*
* Returns null when a blanket overwrite is lossless (no sibling statements), and
* REFUSE_UNROLL when siblings exist but can't be safely reproduced — a non-`for`
* loop (no numeric index to splice), a statement we don't model, or an unsafe
* index use (shadowing / shorthand). Refusing no-ops the unroll, which is safe:
* the dynamic loop keeps rendering correctly, just un-flattened.
*/
function buildLoopUnrollPreserving(
script: string,
timelineVar: string,
animation: GsapAnimation,
elements: UnrollElement[],
loopNode: Node,
targetStmt: Node,
): string | null | typeof REFUSE_UNROLL {
const stmts = loopBodyStatements(loopNode);
if (!stmts || !stmts.includes(targetStmt)) return null;
const indexVar = loopIndexVarName(loopNode);
const strategy = unrollSiblingStrategy(loopNode, targetStmt, stmts, indexVar);
if (strategy === "blanket") return null;
if (strategy === "refuse" || !indexVar) return REFUSE_UNROLL;
return emitUnrolledLines(stmts, targetStmt, elements, timelineVar, animation, indexVar, script);
}
/**
* Replace a dynamic loop that generates multiple tween calls with individual
* static `tl.to()` calls — one per element. Finds the loop containing the
* animation and replaces the loop with unrolled static calls, preserving every
* non-target statement in the loop body per iteration.
*/
export function unrollDynamicAnimations(
script: string,
animationId: string,
elements: UnrollElement[],
): string {
// An empty element list has no unrolled form — replacing the loop/statement
// with zero calls would silently delete the animation. No-op instead.
if (elements.length === 0) return script;
const parsed = parseGsapScriptAcornForWrite(script);
if (!parsed) return script;
const target = parsed.located.find((l) => l.id === animationId);
if (!target) return script;
const ms = new MagicString(script);
const loopNode = findEnclosingLoopNode(target.call.ancestors);
if (loopNode) {
const targetStmt = findEnclosingExpressionStatement(target.call.ancestors);
const preserving = targetStmt
? buildLoopUnrollPreserving(
script,
parsed.timelineVar,
target.animation,
elements,
loopNode,
targetStmt,
)
: null;
// Siblings exist but can't be safely reproduced — leave the loop untouched
// rather than drop or corrupt them. The op no-ops (before === after).
if (preserving === REFUSE_UNROLL) return script;
// Fall back to the simple whole-body replacement when the body isn't a plain
// block of statements we can preserve.
const replacement =
preserving ?? buildUnrollReplacement(parsed.timelineVar, target.animation, elements);
ms.overwrite(loopNode.start as number, loopNode.end as number, replacement);
} else {
const stmt = findEnclosingExpressionStatement(target.call.ancestors);
if (!stmt) return script;
const replacement = buildUnrollReplacement(parsed.timelineVar, target.animation, elements);
ms.overwrite(stmt.start as number, stmt.end as number, replacement);
}
return ms.toString();
}