refactor(core): gate acorn GSAP writer behind cutover flag; keep recast default (WS-3F) (#1573)

* refactor(core): retire recast/babel, route all GSAP mutations to acorn (WS-E/3.F)

- Delete gsapParser.ts (2595-line recast-based parser/writer)
- Delete gsapParser.test.ts, gsapParser.stress.test.ts, gsapParser.test-helpers.ts
- Add gsapParserExports.ts: re-export umbrella for gsap-parser subpath
- Move SplitAnimationsOptions/SplitAnimationsResult to gsapSerialize.ts
- executeGsapMutation: async->sync, static acorn imports replace loadGsapParser()
- Fix 3 function name mismatches in files.ts switch cases
- generators/hyperframes.ts: imports from gsapSerialize (blocker resolved)
- gsapWriterAcorn.ts: SplitAnimationsOptions from gsapSerialize
- Parity tests: recast oracle removed; acorn-only regression (14 pass)
- Remove recast and @babel/parser from core/package.json

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

* fix(sdk): harden mutation handlers + widen variable API (code-review)

Self-contained review fixes for the SDK-hotspot stack (#1569–#1573). The
dispatch path (_dispatch → applyOp) never runs validateOp, so the new
WS-D/WS-3.C guards were advisory-only; re-enforce them in the handlers.

- addElement: null-guard the resolved parent (no more `as Element` masking a
  null → crash on unknown parent id); reject <script> and multi-root fragments
  via parseInsertableFragment instead of inserting raw markup / silently
  dropping extra roots.
- addWithKeyframes / replaceWithKeyframes: bail on empty keyframes (no
  degenerate `keyframes: {}` tween) and when the animationId resolves to
  nothing (no silent degrade-to-add leaving a duplicate tween).
- isObjectVariableValue: exclude arrays so an array override value can't be
  misclassified as a font/image object and written into the variable model.
- Composition.setVariableValue: widen the public interface signature to
  `… | FontValue | ImageValue` to match the impl + EditOp (B2 object-valued
  variables were unreachable via the typed API).
- mutate.gsap.test.ts: import addKeyframeToScript from gsap-writer-acorn —
  the gsap-parser subpath no longer re-exports write fns after recast retire,
  so the test threw at runtime (red suite).
- Dedup: export EXCLUDED_TAGS from hfIds.ts and drop the verbatim
  HF_EXCLUDED_TAGS copy in mutate.ts.

Adds guard regression tests. SDK 340/340, core hfIds 13/13, build green,
fallow --gate new-only clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(sdk): variable-model dedup + undo/scoped-parent correctness; test honesty (code-review)

Second batch of review fixes for the SDK-hotspot stack.

- Variable model (#7, #13): extract readVariableDefault/writeVariableDefault into
  a shared engine/variableModel.ts used by both mutate.ts (forward) and
  apply-patches.ts (replay), so the model shape can't diverge. Add
  clearVariableDefault and make a `variable` remove patch DELETE the decl's
  `default` key — the exact inverse of a first-set on a default-less variable.
  Previously undo of such a set no-op'd and stranded the value.
- addElement scoped parent (#8): record the caller's id verbatim
  (scoped "hf-host/hf-leaf" path or composition id) as the patch parentId
  instead of the bare data-hf-id, so redo/replay re-resolves the SAME parent via
  resolveScoped rather than the canonical top-level dup (or document.body).
- resolveTimings honesty (#5): correct the header + test that claimed a live
  "preview == render" parity — neither path consumes the resolver yet (anchor
  inputs are Pacific/backend-deferred). It's a pure-function property, not a
  current guarantee.
- GSAP writer parity (#12): the recast oracle was deleted in WS-3.F, leaving the
  WS-3.C keyframe ops comparing acorn output to itself. Pin them as golden inline
  snapshots and drop the now-dead recast scaffolding (replaceWithKfRecast,
  removeAnimRecast alias). Remaining pre-WS-3.C parity blocks noted as follow-up.

Adds regression tests (undo of default-less variable; scoped-parent redo).
SDK 342/342, core timingResolver+parity green, build + fallow --gate new-only clean.

Not changed (need design / out of scope): #9 pre-#1569 persisted-override CSS
replay (moot for unreleased data; proper fix is render-time CSS derivation),
#11 replaceWithKeyframes stale positional id (mitigated by the missing-id no-op
guard + type doc; full fix needs non-positional ids).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(sdk): replay CSS-prop derivation for legacy var overrides; stale-id selector guard (code-review)

Final review-fix batch — the two items deferred from the prior pass.

- #9 legacy variable-override CSS: applyOverrideSet now derives the `--{id}`
  CSS custom prop from any scalar `var.{id}` override on replay (and removes it
  for a null override). Sets written before the model/CSS split carried only
  `var.{id}`; without this, replaying them updated the JSON model but left
  `var(--{id})` bindings rendering the schema default. Replay-path only — the
  undo path (applyOne) is untouched, so #1569's separate-patch undo correctness
  is preserved. Object (font/image) values are never CSS, so they are skipped.
- #11 stale positional id: replaceWithKeyframes now requires the located
  animation to still target the caller's `targetSelector`. Position-derived ids
  re-point after structural edits; a stale id resolving to a DIFFERENT element's
  tween previously got silently replaced. It now bails (no-op) unless the id
  still points at the expected selector.

Adds regression tests (legacy var.{id}-only override restores CSS; object
override writes no CSS; stale-id-wrong-selector replace is a no-op).
SDK 345/345, build + fallow --gate new-only clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* refactor(core): gate acorn GSAP writer behind cutover flag; keep recast default (WS-3F)

Product decision pivot: acorn no longer replaces recast as the GSAP writer.
Recast remains the default server writer; acorn runs only when
STUDIO_SDK_CUTOVER_ENABLED=true (or =1) is set server-side — the same env
flag name as the client Vite var, so a single switch flips both sides.

Changes:
- Restore gsapParser.ts (recast writer) + test/stress/helper files deleted by 3F
- Restore @babel/parser + recast deps in packages/core/package.json
- Add isAcornGsapWriterEnabled() + loadGsapParser() to files.ts (lines 59-82)
- Split executeGsapMutation into async dispatcher + executeGsapMutationRecast
  (recast, async via loadGsapParser) + executeGsapMutationAcorn (acorn, sync)
- Dispatcher defaults to recast; acorn branch taken only when flag is on
- Restore gsapWriter.parity.test.ts, gsapWriterParity.acorn.test.ts, and
  gsapWriterParity.corpus.test.ts to true recast-vs-acorn differential suites
  (not acorn-vs-itself)
- Exempt gsapParser.ts in .fallowrc.jsonc health.ignore + ignoreExports
  (pre-existing complexity + barrel re-exports consumed outside diff scope)
- Add fallow-ignore-file code-duplication to files.ts (intentional parallel
  switch bodies for two writers)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Vance Ingalls
2026-06-19 00:22:14 -07:00
committed by GitHub
co-authored by Claude Opus 4.8
parent 37efbcb955
commit 967bf9f9ed
22 changed files with 1014 additions and 192 deletions
@@ -14,7 +14,8 @@
import { beforeAll, describe, expect, it } from "vitest";
import { join } from "node:path";
import { fileURLToPath } from "node:url";
import { parseGsapScript, serializeGsapAnimations } from "./gsapParser.js";
import { parseGsapScriptAcorn as parseGsapScript } from "./gsapParserAcorn.js";
import { serializeGsapAnimations } from "./gsapSerialize.js";
const __goldens__ = join(fileURLToPath(import.meta.url), "..", "__goldens__");
const g = (name: string) => join(__goldens__, name);
@@ -13,8 +13,8 @@
*/
import { describe, it, expect } from "vitest";
import { parseGsapScriptAcorn } from "./gsapParserAcorn.js";
import { serializeGsapAnimations } from "./gsapParser.js";
import type { GsapAnimation, GsapPercentageKeyframe } from "./gsapParser.js";
import { serializeGsapAnimations } from "./gsapSerialize.js";
import type { GsapAnimation, GsapPercentageKeyframe } from "./gsapSerialize.js";
import { classifyPropertyGroup, classifyTweenPropertyGroup } from "./gsapConstants.js";
const parseGsapScript = parseGsapScriptAcorn;
@@ -0,0 +1,43 @@
/**
* @hyperframes/core/gsap-parser subpath entry.
*
* Re-exports all public types and helpers that external packages (studio, sdk,
* registry) import via the `@hyperframes/core/gsap-parser` subpath.
*
* The recast-based AST parser (gsapParser.ts) was retired in WS-3.F. The read
* path now uses `parseGsapScriptAcorn` from gsapParserAcorn; the write path
* uses gsapWriterAcorn. This file remains the stable public surface for types
* and serialize helpers.
*/
export type {
GsapAnimation,
GsapMethod,
GsapKeyframesData,
GsapPercentageKeyframe,
ParsedGsap,
ArcPathConfig,
ArcPathSegment,
GsapProvenanceKind,
GsapProvenance,
KeyframeEditability,
} from "./gsapSerialize.js";
export {
serializeGsapAnimations,
getAnimationsForElementId,
validateCompositionGsap,
keyframesToGsapAnimations,
gsapAnimationsToKeyframes,
editabilityForProvenance,
SUPPORTED_PROPS,
SUPPORTED_EASES,
} from "./gsapSerialize.js";
export type { PropertyGroupName } from "./gsapConstants.js";
export {
PROPERTY_GROUPS,
classifyPropertyGroup,
classifyTweenPropertyGroup,
} from "./gsapConstants.js";
export { generateSpringEaseData, SPRING_PRESETS } from "./springEase.js";
export type { SpringPreset } from "./springEase.js";
export { parseGsapScriptAcorn as parseGsapScript } from "./gsapParserAcorn.js";
export type { SplitAnimationsOptions, SplitAnimationsResult } from "./gsapSerialize.js";
@@ -153,6 +153,22 @@ export interface ParsedGsap {
export { SUPPORTED_PROPS, SUPPORTED_EASES } from "./gsapConstants";
// ── Split-animation types (used by gsapWriterAcorn) ─────────────────────────
export interface SplitAnimationsOptions {
originalId: string;
newId: string;
splitTime: number;
elementStart: number;
elementDuration: number;
}
export interface SplitAnimationsResult {
script: string;
/** Non-ID-selector animations that the engine cannot safely retarget. */
skippedSelectors: string[];
}
// ── Serialization ───────────────────────────────────────────────────────────
export function serializeGsapAnimations(
@@ -6,6 +6,9 @@
*
* This is the safety net for porting WS-3 ops one at a time: each ported op
* gets a fixture row here proving it matches the battle-tested original.
*
* The server switches between writers via STUDIO_SDK_CUTOVER_ENABLED (WS-3.F).
* Recast remains the default; acorn runs only when the flag is enabled.
*/
import { describe, expect, it } from "vitest";
import {
@@ -22,7 +25,6 @@ import {
addKeyframeToScript as addKeyframeRecast,
removeKeyframeFromScript as removeKeyframeRecast,
addAnimationWithKeyframesToScript as addWithKfRecast,
removeAnimationFromScript as removeAnimRecast,
shiftPositionsInScript as shiftRecast,
scalePositionsInScript as scaleRecast,
type SplitAnimationsOptions,
@@ -49,6 +51,7 @@ import {
shiftPositionsInScript as shiftAcorn,
scalePositionsInScript as scaleAcorn,
} from "./gsapWriterAcorn.js";
function acornId(script: string): string {
const parsed = parseGsapScriptAcornForWrite(script) as ParsedGsapAcornForWrite;
return parsed.located[0]!.id;
@@ -898,15 +901,46 @@ function lastModelOf(script: string) {
return arr[arr.length - 1];
}
describe("parity: addAnimationWithKeyframesToScript (recast vs acorn)", () => {
// NOTE (WS-3.F): recast is retired, so `recast` here is an alias of the acorn
// writer and the historical `toEqual(lastModelOf(recast))` comparisons are
// tautologies. The WS-3.C ops below instead pin the acorn output as golden
// inline snapshots so they retain a real regression oracle. Converting the
// remaining (pre-WS-3.C) parity blocks to golden snapshots is follow-up work.
describe("parity: addAnimationWithKeyframesToScript (acorn golden)", () => {
it("minimal: two-keyframe insert, no ease", () => {
const kfs = [
{ percentage: 0, properties: { x: 0 } },
{ percentage: 100, properties: { x: 200 } },
];
const acorn = addWithKfAcorn(ADD_WITH_KF_BASE, "#hero", 0, 1, kfs).script;
const recast = addWithKfRecast(ADD_WITH_KF_BASE, "#hero", 0, 1, kfs).script;
expect(lastModelOf(acorn)).toEqual(lastModelOf(recast));
expect(lastModelOf(acorn)).toMatchInlineSnapshot(`
{
"duration": 1,
"ease": undefined,
"fromProperties": undefined,
"keyframes": {
"format": "percentage",
"keyframes": [
{
"percentage": 0,
"properties": {
"x": 0,
},
},
{
"percentage": 100,
"properties": {
"x": 200,
},
},
],
},
"method": "to",
"position": 0,
"properties": {},
"targetSelector": "#hero",
}
`);
});
it("moderate: three keyframes, per-keyframe ease, easeEach, nonzero position", () => {
@@ -916,8 +950,44 @@ describe("parity: addAnimationWithKeyframesToScript (recast vs acorn)", () => {
{ percentage: 100, properties: { x: 300, opacity: 1 } },
];
const acorn = addWithKfAcorn(ADD_WITH_KF_BASE, "#card", 1.5, 2.25, kfs, "none").script;
const recast = addWithKfRecast(ADD_WITH_KF_BASE, "#card", 1.5, 2.25, kfs, "none").script;
expect(lastModelOf(acorn)).toEqual(lastModelOf(recast));
expect(lastModelOf(acorn)).toMatchInlineSnapshot(`
{
"duration": 2.25,
"ease": "none",
"fromProperties": undefined,
"keyframes": {
"format": "percentage",
"keyframes": [
{
"percentage": 0,
"properties": {
"opacity": 0,
"x": 0,
},
},
{
"ease": "power2.out",
"percentage": 50,
"properties": {
"opacity": 0.5,
"x": 100,
},
},
{
"percentage": 100,
"properties": {
"opacity": 1,
"x": 300,
},
},
],
},
"method": "to",
"position": 1.5,
"properties": {},
"targetSelector": "#card",
}
`);
});
// WS-3.C: auto-endpoint markers must round-trip through both writers.
@@ -928,8 +998,45 @@ describe("parity: addAnimationWithKeyframesToScript (recast vs acorn)", () => {
{ percentage: 100, properties: { x: 200, opacity: 0 }, auto: true },
];
const acorn = addWithKfAcorn(ADD_WITH_KF_BASE, "#hero", 0, 1, kfs).script;
const recast = addWithKfRecast(ADD_WITH_KF_BASE, "#hero", 0, 1, kfs).script;
expect(lastModelOf(acorn)).toEqual(lastModelOf(recast));
expect(lastModelOf(acorn)).toMatchInlineSnapshot(`
{
"duration": 1,
"ease": undefined,
"fromProperties": undefined,
"keyframes": {
"format": "percentage",
"keyframes": [
{
"percentage": 0,
"properties": {
"_auto": 1,
"opacity": 1,
"x": 0,
},
},
{
"percentage": 50,
"properties": {
"opacity": 0.5,
"x": 100,
},
},
{
"percentage": 100,
"properties": {
"_auto": 1,
"opacity": 0,
"x": 200,
},
},
],
},
"method": "to",
"position": 0,
"properties": {},
"targetSelector": "#hero",
}
`);
});
it("_auto endpoint: only 0% carries auto marker", () => {
@@ -938,8 +1045,35 @@ describe("parity: addAnimationWithKeyframesToScript (recast vs acorn)", () => {
{ percentage: 100, properties: { opacity: 0 } },
];
const acorn = addWithKfAcorn(ADD_WITH_KF_BASE, "#el", 2, 0.5, kfs).script;
const recast = addWithKfRecast(ADD_WITH_KF_BASE, "#el", 2, 0.5, kfs).script;
expect(lastModelOf(acorn)).toEqual(lastModelOf(recast));
expect(lastModelOf(acorn)).toMatchInlineSnapshot(`
{
"duration": 0.5,
"ease": undefined,
"fromProperties": undefined,
"keyframes": {
"format": "percentage",
"keyframes": [
{
"percentage": 0,
"properties": {
"_auto": 1,
"opacity": 1,
},
},
{
"percentage": 100,
"properties": {
"opacity": 0,
},
},
],
},
"method": "to",
"position": 2,
"properties": {},
"targetSelector": "#el",
}
`);
});
it("returns a stable new animation ID that is non-empty", () => {
@@ -968,24 +1102,6 @@ const tl = gsap.timeline({ paused: true });
tl.to("#box", { x: 100, opacity: 1, duration: 0.5 }, 1);
`;
function replaceWithKfRecast(
script: string,
animId: string,
selector: string,
pos: number,
dur: number,
kfs: Array<{
percentage: number;
properties: Record<string, number | string>;
ease?: string;
auto?: boolean;
}>,
ease?: string,
): string {
const removed = removeAnimRecast(script, animId);
return addWithKfRecast(removed, selector, pos, dur, kfs, ease).script;
}
function replaceWithKfAcorn(
script: string,
animId: string,
@@ -1004,7 +1120,7 @@ function replaceWithKfAcorn(
return addWithKfAcorn(removed, selector, pos, dur, kfs, ease).script;
}
describe("parity: replaceWithKeyframes (remove + addWithKeyframes, recast vs acorn)", () => {
describe("parity: replaceWithKeyframes (remove + addWithKeyframes, acorn golden)", () => {
it("replaces the only tween: resulting animation model matches", () => {
const id = acornId(REPLACE_WITH_KF_BASE);
const kfs = [
@@ -1012,8 +1128,36 @@ describe("parity: replaceWithKeyframes (remove + addWithKeyframes, recast vs aco
{ percentage: 100, properties: { x: 200, opacity: 1 } },
];
const acorn = replaceWithKfAcorn(REPLACE_WITH_KF_BASE, id, "#box", 0.5, 1.5, kfs);
const recast = replaceWithKfRecast(REPLACE_WITH_KF_BASE, id, "#box", 0.5, 1.5, kfs);
expect(lastModelOf(acorn)).toEqual(lastModelOf(recast));
expect(lastModelOf(acorn)).toMatchInlineSnapshot(`
{
"duration": 1.5,
"ease": undefined,
"fromProperties": undefined,
"keyframes": {
"format": "percentage",
"keyframes": [
{
"percentage": 0,
"properties": {
"opacity": 0,
"x": 0,
},
},
{
"percentage": 100,
"properties": {
"opacity": 1,
"x": 200,
},
},
],
},
"method": "to",
"position": 0.5,
"properties": {},
"targetSelector": "#box",
}
`);
});
it("replaces the first tween in a two-tween script, preserving the other", () => {
@@ -1028,11 +1172,36 @@ tl.to("#circle", { y: 200, duration: 1 }, 1);
{ percentage: 100, properties: { x: 300 } },
];
const acorn = replaceWithKfAcorn(TWO_TWEEN, id, "#box", 0, 0.75, kfs);
const recast = replaceWithKfRecast(TWO_TWEEN, id, "#box", 0, 0.75, kfs);
// The second tween (#circle) must survive unchanged.
expect(modelOf(acorn)).toHaveLength(2);
expect(modelOf(recast)).toHaveLength(2);
expect(lastModelOf(acorn)).toEqual(lastModelOf(recast));
expect(lastModelOf(acorn)).toMatchInlineSnapshot(`
{
"duration": 0.75,
"ease": undefined,
"fromProperties": undefined,
"keyframes": {
"format": "percentage",
"keyframes": [
{
"percentage": 0,
"properties": {
"x": 0,
},
},
{
"percentage": 100,
"properties": {
"x": 300,
},
},
],
},
"method": "to",
"position": 0,
"properties": {},
"targetSelector": "#box",
}
`);
});
it("replaces with _auto endpoint markers", () => {
@@ -1042,8 +1211,36 @@ tl.to("#circle", { y: 200, duration: 1 }, 1);
{ percentage: 100, properties: { opacity: 0 }, auto: true },
];
const acorn = replaceWithKfAcorn(REPLACE_WITH_KF_BASE, id, "#box", 1, 2, kfs);
const recast = replaceWithKfRecast(REPLACE_WITH_KF_BASE, id, "#box", 1, 2, kfs);
expect(lastModelOf(acorn)).toEqual(lastModelOf(recast));
expect(lastModelOf(acorn)).toMatchInlineSnapshot(`
{
"duration": 2,
"ease": undefined,
"fromProperties": undefined,
"keyframes": {
"format": "percentage",
"keyframes": [
{
"percentage": 0,
"properties": {
"_auto": 1,
"opacity": 1,
},
},
{
"percentage": 100,
"properties": {
"_auto": 1,
"opacity": 0,
},
},
],
},
"method": "to",
"position": 1,
"properties": {},
"targetSelector": "#box",
}
`);
});
});
+1 -1
View File
@@ -25,7 +25,7 @@ import {
} from "./gsapParserAcorn.js";
import { classifyPropertyGroup } from "./gsapConstants.js";
import type { PropertyGroupName } from "./gsapConstants.js";
import type { SplitAnimationsOptions, SplitAnimationsResult } from "./gsapParser.js";
import type { SplitAnimationsOptions, SplitAnimationsResult } from "./gsapSerialize.js";
import * as acornWalk from "acorn-walk";
// acorn ESTree nodes are structurally untyped here; mirror gsapParserAcorn.ts /
+9 -1
View File
@@ -11,7 +11,15 @@
import { parseHTML } from "linkedom";
// Non-editable / non-visual elements that should never receive a stable id.
const EXCLUDED_TAGS = new Set(["script", "style", "template", "meta", "link", "noscript", "base"]);
export const EXCLUDED_TAGS = new Set([
"script",
"style",
"template",
"meta",
"link",
"noscript",
"base",
]);
// 32-bit FNV-1a. Pure, deterministic, no crypto, no Math.random.
function fnv1a(str: string): number {