feat(sdk,core): ws-3 — splitAnimationsInScript acorn port + SDK op

- acorn: updateAnimationSelectorInScript, insertInheritedStateSetInScript helpers
- acorn: splitAnimationsInScript exported (parity with recast version)
- parity: 4 new fixtures (3 cases + no-op) — 23 total parity tests
- SDK types: splitAnimations EditOp variant
- mutate.ts: handleSplitAnimations + can() gate
- mutate.gsap.test.ts: 3 new tests (56 total passing)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-authored-by: Miguel Ángel <miguel07alm@protonmail.com>

Author: vanceingalls

packages/core/src/parsers/gsapWriter.parity.test.ts

@@ -14,13 +14,16 @@ import {
   convertToKeyframesInScript as convertRecast,
   materializeKeyframesInScript as materializeRecast,
   splitIntoPropertyGroups as splitGroupsRecast,
+  splitAnimationsInScript as splitAnimsRecast,
+  type SplitAnimationsOptions,
 } from "./gsapParser.js";
 import { parseGsapScriptAcornForWrite, type ParsedGsapAcornForWrite } from "./gsapParserAcorn.js";
 import {
   removeAllKeyframesFromScript as removeAllAcorn,
   convertToKeyframesFromScript as convertAcorn,
   materializeKeyframesFromScript as materializeAcorn,
   splitIntoPropertyGroupsFromScript as splitGroupsAcorn,
+  splitAnimationsInScript as splitAnimsAcorn,
 } from "./gsapWriterAcorn.js";
 
 function acornId(script: string): string {
@@ -301,3 +304,89 @@ describe("parity: splitIntoPropertyGroupsFromScript (recast vs acorn)", () => {
     expect(out).toBe(script);
   });
 });
+
+// ── splitAnimationsInScript parity ────────────────────────────────────────────
+
+function animShapesOf(script: string) {
+  return parseGsapScript(script).animations.map((a) => ({
+    method: a.method,
+    selector: a.targetSelector,
+    properties: a.properties,
+    fromProperties: a.fromProperties,
+    duration: a.duration,
+    position: a.position,
+  }));
+}
+
+const SPLIT_ANIM_CASES: Array<{ name: string; script: string; opts: SplitAnimationsOptions }> = [
+  {
+    name: "all tweens before split — retargets none",
+    script: `
+      const tl = gsap.timeline({ paused: true });
+      tl.to("#hero", { x: 100, duration: 1 }, 0);
+    `,
+    opts: {
+      originalId: "hero",
+      newId: "hero-2",
+      splitTime: 2,
+      elementStart: 0,
+      elementDuration: 4,
+    },
+  },
+  {
+    name: "tween entirely after split — retargeted to newId",
+    script: `
+      const tl = gsap.timeline({ paused: true });
+      tl.to("#hero", { opacity: 0, duration: 0.5 }, 3);
+    `,
+    opts: {
+      originalId: "hero",
+      newId: "hero-2",
+      splitTime: 2,
+      elementStart: 0,
+      elementDuration: 4,
+    },
+  },
+  {
+    name: "tween spanning split — truncated first half + fromTo second half",
+    script: `
+      const tl = gsap.timeline({ paused: true });
+      tl.to("#hero", { x: 200, duration: 4 }, 0);
+    `,
+    opts: {
+      originalId: "hero",
+      newId: "hero-2",
+      splitTime: 2,
+      elementStart: 0,
+      elementDuration: 4,
+    },
+  },
+];
+
+describe("parity: splitAnimationsInScript (recast vs acorn)", () => {
+  for (const { name, script, opts } of SPLIT_ANIM_CASES) {
+    it(name, () => {
+      const { script: recastOut } = splitAnimsRecast(script, opts);
+      const { script: acornOut } = splitAnimsAcorn(script, opts);
+      const sortByPos = (arr: ReturnType<typeof animShapesOf>) =>
+        arr.slice().sort((a, b) => {
+          const pa = typeof a.position === "number" ? a.position : 0;
+          const pb = typeof b.position === "number" ? b.position : 0;
+          return pa - pb || (a.selector ?? "").localeCompare(b.selector ?? "");
+        });
+      expect(sortByPos(animShapesOf(acornOut))).toEqual(sortByPos(animShapesOf(recastOut)));
+    });
+  }
+
+  it("no-op when originalId not found in script", () => {
+    const script = SPLIT_ANIM_CASES[0]!.script;
+    const opts: SplitAnimationsOptions = {
+      originalId: "nonexistent",
+      newId: "x",
+      splitTime: 2,
+      elementStart: 0,
+      elementDuration: 4,
+    };
+    expect(splitAnimsAcorn(script, opts).script).toBe(script);
+  });
+});

packages/core/src/parsers/gsapWriterAcorn.ts

@@ -16,6 +16,7 @@ import {
 } from "./gsapParserAcorn.js";
 import { classifyPropertyGroup } from "./gsapConstants.js";
 import type { PropertyGroupName } from "./gsapConstants.js";
+import type { SplitAnimationsOptions, SplitAnimationsResult } from "./gsapParser.js";
 import * as acornWalk from "acorn-walk";
 
 // ── Code generation helpers ──────────────────────────────────────────────────
@@ -1172,3 +1173,169 @@ export function removeLabelFromScript(script: string, name: string): string {
   }
   return ms.toString();
 }
+
+// ── 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);
+  if (tlDecl) {
+    ms.appendLeft(tlDecl.end, "\n" + code);
+  } else if (parsed.located.length > 0) {
+    const firstCall = parsed.located[0]!.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();
+}
+
+// fallow-ignore-next-line complexity
+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;
+  const inheritedProps: Record<string, number | string> = {};
+
+  // Reverse iteration: updateAnimationSelectorInScript mutates selectors which
+  // can shift count-based ID suffixes for later animations.
+  for (let i = matching.length - 1; i >= 0; i--) {
+    const anim = matching[i]!;
+    const pos = typeof anim.position === "number" ? anim.position : 0;
+    const dur = anim.duration ?? 0;
+    const animEnd = pos + dur;
+
+    if (anim.keyframes) {
+      if (pos >= opts.splitTime) {
+        result = updateAnimationSelectorInScript(result, anim.id, newSelector);
+      } else if (animEnd > opts.splitTime) {
+        skippedSelectors.push(`${originalSelector} (keyframes spanning split)`);
+        const kfs = anim.keyframes.keyframes;
+        for (const kf of kfs) {
+          const kfTime = pos + (kf.percentage / 100) * dur;
+          if (kfTime <= opts.splitTime) {
+            for (const [k, v] of Object.entries(kf.properties)) {
+              inheritedProps[k] = v;
+            }
+          }
+        }
+      } else {
+        const kfs = anim.keyframes.keyframes;
+        if (kfs.length > 0) {
+          for (const [k, v] of Object.entries(kfs[kfs.length - 1]!.properties)) {
+            inheritedProps[k] = v;
+          }
+        }
+      }
+      continue;
+    }
+
+    if (animEnd <= opts.splitTime) {
+      for (const [k, v] of Object.entries(anim.properties)) {
+        inheritedProps[k] = v;
+      }
+      continue;
+    }
+
+    if (pos >= opts.splitTime) {
+      result = updateAnimationSelectorInScript(result, anim.id, newSelector);
+      continue;
+    }
+
+    // Spans the split — linear interpolation to compute mid-values.
+    const progress = dur > 0 ? (opts.splitTime - pos) / dur : 0;
+    const fromSource = anim.fromProperties ?? inheritedProps;
+    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 firstHalfDuration = opts.splitTime - pos;
+    result = updateAnimationInScript(result, anim.id, {
+      duration: firstHalfDuration,
+      properties: midProps,
+    });
+
+    const secondHalfDuration = animEnd - opts.splitTime;
+    const addResult = addAnimationToScript(result, {
+      targetSelector: newSelector,
+      method: "fromTo",
+      position: newElementStart,
+      duration: secondHalfDuration,
+      properties: { ...anim.properties },
+      fromProperties: { ...midProps },
+      ease: anim.ease,
+      extras: anim.extras,
+    });
+    result = addResult.script;
+
+    for (const [k, v] of Object.entries(midProps)) {
+      inheritedProps[k] = v;
+    }
+  }
+
+  if (Object.keys(inheritedProps).length > 0) {
+    result = insertInheritedStateSetInScript(result, newSelector, newElementStart, inheritedProps);
+  }
+
+  return { script: result, skippedSelectors };
+}

packages/sdk/src/engine/mutate.gsap.test.ts

@@ -584,6 +584,64 @@ window.__timelines["t"] = tl;`;
   });
 });
 
+// ─── splitAnimations ──────────────────────────────────────────────────────────
+
+describe("splitAnimations", () => {
+  const SPLIT_SCRIPT = `var tl = gsap.timeline({ paused: true });
+tl.to("#hero", { x: 200, duration: 4 }, 0);
+window.__timelines["t"] = tl;`;
+
+  function freshSplit() {
+    return parseMutable(`<div data-hf-id="hf-stage" data-hf-root style="width:1280px;height:720px">
+  <div data-hf-id="hf-hero"></div>
+  <script>${SPLIT_SCRIPT}</script>
+</div>`);
+  }
+
+  it("retargets post-split tween to newId", () => {
+    const parsed = freshSplit();
+    const result = applyOp(parsed, {
+      type: "splitAnimations",
+      originalId: "hero",
+      newId: "hero-2",
+      splitTime: 3,
+      elementStart: 0,
+      elementDuration: 4,
+    });
+    expect(result.forward).toHaveLength(1);
+    const newScript = String(result.forward[0]?.value ?? "");
+    expect(newScript).toContain("#hero-2");
+  });
+
+  it("spanning tween produces fromTo on new element", () => {
+    const parsed = freshSplit();
+    const result = applyOp(parsed, {
+      type: "splitAnimations",
+      originalId: "hero",
+      newId: "hero-2",
+      splitTime: 2,
+      elementStart: 0,
+      elementDuration: 4,
+    });
+    const newScript = String(result.forward[0]?.value ?? "");
+    expect(newScript).toContain(".fromTo(");
+    expect(newScript).toContain("#hero-2");
+  });
+
+  it("no-op when originalId not found", () => {
+    const parsed = freshSplit();
+    const result = applyOp(parsed, {
+      type: "splitAnimations",
+      originalId: "nonexistent",
+      newId: "x",
+      splitTime: 2,
+      elementStart: 0,
+      elementDuration: 4,
+    });
+    expect(result.forward).toHaveLength(0);
+  });
+});
+
 // ─── Label ops ────────────────────────────────────────────────────────────────
 
 describe("addLabel", () => {

packages/sdk/src/engine/mutate.ts

@@ -53,6 +53,7 @@ import {
   convertToKeyframesFromScript,
   materializeKeyframesFromScript,
   splitIntoPropertyGroupsFromScript,
+  splitAnimationsInScript,
   updateKeyframeInScript,
   addLabelToScript,
   removeLabelFromScript,
@@ -178,6 +179,8 @@ function applyGsapKeyframeOp(parsed: ParsedDocument, op: EditOp): MutationResult
       );
     case "splitIntoPropertyGroups":
       return handleSplitIntoPropertyGroups(parsed, op.animationId);
+    case "splitAnimations":
+      return handleSplitAnimations(parsed, op);
     default:
       return undefined;
   }
@@ -793,6 +796,24 @@ function handleSplitIntoPropertyGroups(
   return gsapScriptChange(script, newScript);
 }
 
+function handleSplitAnimations(
+  parsed: ParsedDocument,
+  op: Extract<EditOp, { type: "splitAnimations" }>,
+): MutationResult {
+  const script = getGsapScript(parsed.document);
+  if (!script) return EMPTY;
+  const { script: newScript } = splitAnimationsInScript(script, {
+    originalId: op.originalId,
+    newId: op.newId,
+    splitTime: op.splitTime,
+    elementStart: op.elementStart,
+    elementDuration: op.elementDuration,
+  });
+  if (newScript === script) return EMPTY;
+  setGsapScript(parsed.document, newScript);
+  return gsapScriptChange(script, newScript);
+}
+
 function handleDeleteAllForSelector(parsed: ParsedDocument, selector: string): MutationResult {
   const script = getGsapScript(parsed.document);
   if (!script) return EMPTY;
@@ -1014,6 +1035,7 @@ export function validateOp(parsed: ParsedDocument, op: EditOp): CanResult {
     case "convertToKeyframes":
     case "materializeKeyframes":
     case "splitIntoPropertyGroups":
+    case "splitAnimations":
     case "deleteAllForSelector":
     case "removeLabel":
       if (getGsapScript(parsed.document) === null)