fix(parsers): holds and trims change only the tweens an edit touches

Author: miguel-heygen

packages/parsers/src/gsapConstants.ts

@@ -139,13 +139,40 @@ function knownStart(animation: GsapAnimation): number | undefined {
   return typeof animation.position === "number" ? animation.position : undefined;
 }
 
+export interface HoldScope {
+  touched: (animation: GsapAnimation) => boolean;
+  held: (selector: string) => ReadonlyMap<string, unknown>;
+}
+
+const tweenSignature = (a: GsapAnimation) =>
+  JSON.stringify([a.targetSelector, a.method, a.position, a.duration, a.properties, a.keyframes]);
+
+/** The tweens an edit touched (not in `previous`; none without it), and what the script's holds already pin. */
+export function holdScope(
+  before: readonly GsapAnimation[],
+  previous: readonly GsapAnimation[] | null,
+): HoldScope {
+  const kept = new Set(previous?.map(tweenSignature));
+  const held = new Map<string, Map<string, unknown>>();
+  for (const a of before.filter((b) => b.method === "set" && b.properties?.data === "hf-hold")) {
+    const props = held.get(a.targetSelector) ?? new Map<string, unknown>();
+    for (const [property, value] of Object.entries(a.properties)) props.set(property, value);
+    held.set(a.targetSelector, props);
+  }
+  return {
+    touched: (a) => previous !== null && !kept.has(tweenSignature(a)),
+    held: (selector) => held.get(selector) ?? new Map(),
+  };
+}
+
 /**
- * What a Studio hold pins from t=0 under a lone keyframe (GSAP renders none) or before a later keyframed tween:
- * its 0% keyframe's position props, and size props of a lone key only, minus those an earlier tween writes.
+ * What a Studio hold pins from t=0: a keyframed tween's 0% position props before a later start, and the position and
+ * size of a lone key (GSAP renders none) only where this edit made it or a hold already pins it, minus earlier tweens.
  */
 export function keyframeHoldForAnimation(
   animation: GsapAnimation,
   animations: readonly GsapAnimation[],
+  scope: HoldScope,
 ): Record<string, number> | null {
   if (!animation.keyframes) return null;
   const start = knownStart(animation);
@@ -164,15 +191,22 @@ export function keyframeHoldForAnimation(
       otherStart < start - 0.001
     );
   });
-  const held: Record<string, number> = {};
+  const touched = scope.touched(animation);
+  const pinned = scope.held(animation.targetSelector);
+  // An untouched tween keeps only the hold it made: one with its own first value.
+  const kept = (property: string, value: unknown) =>
+    touched ? pinned.has(property) : pinned.get(property) === value;
+  const pins = (group: PropertyGroupName, property: string, value: unknown) =>
+    (group === "position" && start > 0.001) ||
+    ((group === "position" || group === "size") && ((lone && touched) || kept(property, value)));
+  const hold: Record<string, number> = {};
   for (const [property, value] of Object.entries(atStart.properties)) {
-    const group = classifyPropertyGroup(property);
-    if (!(group === "position" || (group === "size" && lone)) || typeof value !== "number")
+    if (!pins(classifyPropertyGroup(property), property, value) || typeof value !== "number")
       continue;
     if (earlier.some((other) => writesProperty(other, property))) continue;
-    held[property] = value;
+    hold[property] = value;
   }
-  return Object.keys(held).length > 0 ? held : null;
+  return Object.keys(hold).length > 0 ? hold : null;
 }
 
 export const SUPPORTED_EASES = [

packages/parsers/src/gsapParser.test.ts

@@ -1796,11 +1796,14 @@ describe("keyframe mutations", () => {
       ["recast", syncPositionHoldsBeforeKeyframes],
       ["acorn", syncPositionHoldsBeforeKeyframesAcorn],
     ])("%s: holds a lone size keyframe from t=0, wherever its tween starts", (_, sync) => {
+      const timeline = `const tl = gsap.timeline({ paused: true });\n`;
       for (const start of [0, 1.5]) {
         const script =
           `const tl = gsap.timeline({ paused: true });\n` +
           `tl.to("#s", { keyframes: { "0%": { width: 440, height: 294 } }, duration: 3 }, ${start});`;
-        const hold = parseGsapScript(sync(script)).animations.find((a) => a.method === "set");
+        const hold = parseGsapScript(sync(script, timeline)).animations.find(
+          (a) => a.method === "set",
+        );
         expect(hold!.position).toBe(0);
         expect(hold!.properties).toEqual({ width: 440, height: 294, data: "hf-hold" });
       }
@@ -1814,11 +1817,33 @@ describe("keyframe mutations", () => {
       (_, sync) => {
         const timeline = `const tl = gsap.timeline({ paused: true });\n`;
         const keys = `"0%": { width: 100 }, "100%": { width: 400 }`;
-        expect(
-          sync(`${timeline}tl.to("#s", { keyframes: { ${keys} }, duration: 1 }, 2);`),
-        ).not.toContain("hf-hold");
+        const twoKeys = `${timeline}tl.to("#s", { keyframes: { ${keys} }, duration: 1 }, 2);`;
+        expect(sync(twoKeys, timeline)).not.toContain("hf-hold");
         const atLabel = `${timeline}tl.to("#s", { width: 300, duration: 1 }, 1);\ntl.to("#s", { keyframes: { "0%": { width: 500 } }, duration: 1 }, "later");`;
-        expect(sync(atLabel)).not.toContain("hf-hold");
+        expect(sync(atLabel, timeline)).not.toContain("hf-hold");
+      },
+    );
+
+    it.each([
+      ["recast", syncPositionHoldsBeforeKeyframes],
+      ["acorn", syncPositionHoldsBeforeKeyframesAcorn],
+    ])(
+      "%s: keeps a size hold when its lone key gains a second, and adds none to a tween left alone",
+      (_, sync) => {
+        const timeline = `const tl = gsap.timeline({ paused: true });\n`;
+        const held = `tl.set("#s", { width: 440, height: 294, data: "hf-hold" }, 0);\n`;
+        const lone = `tl.to("#s", { keyframes: { "0%": { width: 440, height: 294 } }, duration: 2 }, 3);`;
+        const two = `tl.to("#s", { keyframes: { "0%": { width: 380, height: 250 }, "100%": { width: 440, height: 294 } }, duration: 1 }, 2);`;
+        const hold = parseGsapScript(
+          sync(timeline + held + two, timeline + held + lone),
+        ).animations.find((a) => a.method === "set");
+        expect(hold?.properties).toEqual({ width: 380, height: 250, data: "hf-hold" });
+
+        const untouched = `${timeline}tl.to("#u", { keyframes: { "0%": { width: 500 } }, duration: 1 }, 1);\n`;
+        const edited = `${untouched}tl.to("#v", { opacity: 1, duration: 1 }, 0);`;
+        const deleted = `${timeline}${held}tl.to("#s", { keyframes: { "0%": { width: 600 }, "100%": { width: 700 } }, duration: 1 }, 6);`;
+        expect(sync(deleted, deleted + `\n${lone}`)).not.toContain("hf-hold");
+        expect(sync(edited, untouched)).not.toContain("hf-hold");
       },
     );
 

packages/parsers/src/gsapParser.ts

@@ -55,6 +55,7 @@ import {
   classifyTweenPropertyGroup,
   GSAP_DEFAULT_DURATION,
   isXYPositionWrite,
+  holdScope,
   keyframeHoldForAnimation,
 } from "./gsapConstants";
 import type { PropertyGroupName } from "./gsapConstants";
@@ -1866,7 +1867,15 @@ export function isStudioHoldSet(anim: GsapAnimation): boolean {
  * authored pre-tween behavior. A tween already starting at 0 needs no hold, unless
  * it is a lone keyframe, which GSAP never renders by itself.
  */
-export function syncPositionHoldsBeforeKeyframes(script: string): string {
+function animationsOf(script: string): GsapAnimation[] | null {
+  try {
+    return parseGsapScript(script).animations;
+  } catch {
+    return null;
+  }
+}
+
+export function syncPositionHoldsBeforeKeyframes(script: string, previous?: string): string {
   let parsed: ParsedGsap;
   try {
     parsed = parseGsapScript(script);
@@ -1885,8 +1894,12 @@ export function syncPositionHoldsBeforeKeyframes(script: string): string {
   } catch {
     return result;
   }
+  const scope = holdScope(
+    parsed.animations,
+    previous === undefined ? null : animationsOf(previous),
+  );
   for (const anim of reparsed.animations) {
-    const posProps = keyframeHoldForAnimation(anim, reparsed.animations);
+    const posProps = keyframeHoldForAnimation(anim, reparsed.animations, scope);
     if (!posProps) continue;
     result = insertInheritedStateSet(result, anim.targetSelector, 0, {
       ...posProps,

packages/parsers/src/gsapWriterAcorn.trailingSpan.test.ts

@@ -28,6 +28,19 @@ describe("trimTrailingKeyframeSpans", () => {
     });
   });
 
+  it("trims beside a static gsap.set, which no tween's length moves", () => {
+    const out = trimTrailingKeyframeSpans(
+      timeline,
+      `${timeline}gsap.set("#g", { x: 5 });\n${shortOfEnd}`,
+    );
+    expect(keyed(out).duration).toBe(2);
+  });
+
+  it("leaves a looping timeline, whose cycle the tail is part of", () => {
+    const looping = `const tl = gsap.timeline({ paused: true, repeat: -1 });\n`;
+    expect(trimTrailingKeyframeSpans(looping, looping + shortOfEnd)).toBe(looping + shortOfEnd);
+  });
+
   it("leaves a chained tween the mutation did not touch when it edits the link before", () => {
     const chain = (x: number) =>
       `tl.to("#a", { x: ${x}, duration: 1 }, 0).to("#t", { keyframes: { "0%": { x: 300 }, "50%": { x: 48 } }, duration: 2 }, 1);`;
@@ -56,6 +69,13 @@ describe("trimTrailingKeyframeSpans", () => {
       "every tween when one is placed after another's end",
       `${shortOfEnd}\ntl.to("#u", { opacity: 1, duration: 1 }, ">");`,
     ],
+    ["a yoyo tween", tween(`"0%": { x: 300 }, "50%": { x: 48 }`, 3, ", yoyo: true")],
+    [
+      "a tween whose repeat key is quoted",
+      tween(`"0%": { x: 300 }, "50%": { x: 48 }`, 3, `, "repeat": -1`),
+    ],
+    ["every tween when a label sits at the timeline's end", `${shortOfEnd}\ntl.addLabel("end");`],
+    ["every tween when the timeline is set to repeat later", `${shortOfEnd}\ntl.repeat(-1);`],
   ])("leaves %s", (_, written) => {
     expect(trimTrailingKeyframeSpans(timeline, timeline + written)).toBe(timeline + written);
   });

packages/parsers/src/gsapWriterAcorn.ts

@@ -29,6 +29,7 @@ import {
   classifyPropertyGroup,
   isTweenConfigKey,
   isXYPositionWrite,
+  holdScope,
   keyframeHoldForAnimation,
 } from "./gsapConstants.js";
 import type { PropertyGroupName } from "./gsapConstants.js";
@@ -2490,15 +2491,21 @@ function removeStudioHoldSets(script: string, parsed: ParsedGsapAcornForWrite):
 }
 
 /** Acorn-native, byte-preserving hold synchronization used after mutations. */
-export function syncPositionHoldsBeforeKeyframes(script: string): string {
+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);
+    const position = keyframeHoldForAnimation(animation, animations, scope);
     if (!position) continue;
     result = insertInheritedStateSetInScript(result, animation.targetSelector, 0, {
       ...position,
@@ -2511,6 +2518,9 @@ export function syncPositionHoldsBeforeKeyframes(script: string): string {
 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) {
@@ -2551,9 +2561,10 @@ function trailingSpanTrim(animation: GsapAnimation) {
 export function trimTrailingKeyframeSpans(previous: string, script: string): string {
   if (script === previous) return script;
   const located = parseGsapScriptAcornForWrite(script)?.located ?? [];
-  // A shorter tween moves every tween placed after its end ("+=", ">", no position).
-  if (located.some(({ animation: a }) => a.implicitPosition || typeof a.position !== "number"))
-    return script;
+  // 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 }] : [];

packages/studio-server/src/helpers/compositionInputs.ts

@@ -1,8 +1,10 @@
 import { readFileSync } from "node:fs";
 import { createHash } from "node:crypto";
+import { parseHTML } from "linkedom";
 import { createProjectSignature } from "./projectSignature.js";
 import { rootHeadContent } from "./subComposition.js";
 import { resolveWithinProject } from "./safePath.js";
+import { descendants } from "./compositionInsertion.js";
 
 const ROOT_COMPOSITION = "index.html";
 // A regex, not a parser: a stray match (say, inside a script string) only widens what a
@@ -49,6 +51,33 @@ function closureOf(read: SourceReader, compPath: string): Set<string> {
   return closure;
 }
 
+/** Whether `compPath` lasts as long as its own timeline (so a trim there could end the film early). */
+export function lengthIsTimeline(projectDir: string, compPath: string): boolean {
+  const read = projectReader(projectDir);
+  const documents = new Map<string, Document>();
+  const elements = (path: string, selector: string) => {
+    let document = documents.get(path);
+    if (!document) documents.set(path, (document = parseHTML(read(path) ?? "").document));
+    return descendants(document, selector);
+  };
+  const comp = normalizeSource(compPath) ?? compPath;
+  const unsized = (path: string) => {
+    const [root] = elements(path, "[data-composition-id]");
+    return Boolean(root && !root.hasAttribute("data-duration"));
+  };
+  // An unsized root lasts as long as every timeline it plays, its compositions' included.
+  if (unsized(ROOT_COMPOSITION)) return true;
+  const hosts = [...closureOf(read, ROOT_COMPOSITION)].flatMap((path) =>
+    elements(path, "[data-composition-src]").filter(
+      (host) => normalizeSource(host.getAttribute("data-composition-src") ?? "") === comp,
+    ),
+  );
+  if (comp === ROOT_COMPOSITION || hosts.length === 0) return unsized(comp);
+  return hosts.some(
+    (host) => !host.hasAttribute("data-duration") && !host.hasAttribute("data-end"),
+  );
+}
+
 // ponytail: this and projectSignature's per-exclusion cache keep one small entry per (project,
 // composition) ever thumbnailed, never evicted; LRU them if a server ever holds thousands.
 const inputSignatures = new Map<string, { projectSignature: string; inputSignature: string }>();

packages/studio-server/src/helpers/compositionInsertion.ts

@@ -15,7 +15,7 @@ export class CompositionInsertionError extends Error {
   }
 }
 
-function descendants(root: Document | Element, selector: string): Element[] {
+export function descendants(root: Document | Element, selector: string): Element[] {
   const found = Array.from(root.querySelectorAll(selector));
   for (const template of root.querySelectorAll("template")) {
     found.push(...descendants(template, selector));