mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-12 07:09:59 +00:00
Miguel Ángel
cdf9c817e1
## Summary Extracts the GSAP parser/writer suite, HTML parser, hf-ids, spring-ease, and the shared composition data types out of `@hyperframes/core/src/parsers/` into a new, independently-publishable **`@hyperframes/parsers`** package. This is the foundation of the [#1749](https://github.com/heygen-com/hyperframes/issues/1749) effort: make HyperFrames' parsing/linting/validation usable as plain libraries in a Node app, without shelling out to the CLI. Parsers is the standalone base every other extracted package builds on. **Part 1 of 3** — splits #1754 into independently-reviewable pieces. Parts 2 (lint) and 3 (studio-server) stack on this branch. ## What moves | | | |---|---| | Source moved out of core | **~9,900 LOC** (`src/parsers/` → `packages/parsers/src/`) | | Total lines removed from core (incl. tests + goldens) | ~19,600 | | Files relocated | 39 | | Tests carried over | **660 passing** (5 skipped, 3 todo) | The big movers: `gsapParser` / `gsapParserAcorn` (the recast + acorn dual parsers), `gsapWriterAcorn`, `gsapSerialize`, `gsapUnroll`, `htmlParser`, `hfIds`, `springEase`, `stableIds`, plus the `__goldens__` corpus. ## Bundle footprint of the new package | Artifact | Size | |---|---| | `dist/` (unpacked) | 1.7 MB | | npm tarball (packed) | 409 KB | | `dist/index.js` | 90 KB (**~21 KB gzipped**) | | Heaviest entries | `gsapWriterAcorn.js` 93 KB · `gsapParser.js` 91 KB | Most of the weight is the GSAP AST machinery (recast/babel/acorn). It's tree-shakeable via subpath entries (`@hyperframes/parsers/hf-ids`, `/gsap-constants`, etc.) so a consumer that only needs `hf-ids` (2 KB) doesn't pull the parsers. ## How `@hyperframes/core` changes The interesting part: **core sheds its entire AST toolchain.** | core `dependencies` | before | after | |---|---|---| | count | 9 | 6 | | removed | — | `@babel/parser`, `acorn`, `acorn-walk`, `magic-string`, `recast` | | added | — | `@hyperframes/parsers`, `linkedom` | Before this PR, importing `@hyperframes/core` at all dragged in babel + recast + acorn just to construct types. Now those live behind `@hyperframes/parsers`, and a consumer that only wants core's runtime/compiler types never resolves the parser stack. Core keeps thin `@deprecated` re-export stubs at the old subpaths (`@hyperframes/core/gsap-parser`, `/gsap-constants`, …) so nothing downstream breaks. ## Design notes - **`"bun"` export condition before `"node"`** in every package export. Bun resolves the TypeScript source directly (no pre-built `dist/`), while Node/tsx/Docker contexts fall through to `"node"` → `dist/`. This keeps the dev loop zero-build while published artifacts stay Node-consumable. - `@hyperframes/parsers` is **standalone** — zero `@hyperframes/*` dependencies — so it can be the base of the stack. ## Test plan - [x] `bun run --filter @hyperframes/parsers test` — 660 tests pass - [x] `bun run --filter @hyperframes/sdk test` — 382 tests pass - [x] `bun run build` — full monorepo build succeeds - [x] Fallow audit passes on CI
63 lines
2.8 KiB
TypeScript
63 lines
2.8 KiB
TypeScript
import { describe, it, expect } from "vitest";
|
|
import { unrollComputedTimeline } from "./gsapUnroll.js";
|
|
import { parseGsapScriptAcorn } from "./gsapParserAcorn.js";
|
|
|
|
const ARC_SCRIPT = `
|
|
const tl = gsap.timeline({ paused: true });
|
|
const DX = 852, DY = -322, FLY_SCALE = 56 / 160;
|
|
tl.from("#product", { opacity: 0, scale: 0.8, duration: 0.5 }, 0.1);
|
|
function addCycle(at, path, curviness, spin) {
|
|
tl.to("#product", { y: -15, scale: 1.05, duration: 0.15 }, at + 0.15);
|
|
tl.to("#product", { motionPath: { path, curviness }, scale: FLY_SCALE, rotation: spin, duration: 0.55 }, at + 0.3);
|
|
tl.to("#basket", { keyframes: { "0%": { y: 0 }, "50%": { y: -12 }, "100%": { y: 0 }, easeEach: "power2.out" }, duration: 0.5 }, at + 0.85);
|
|
}
|
|
addCycle(1.0, [{x:0,y:-15},{x:180,y:-300},{x:520,y:-360},{x:DX,y:DY}], 2, 18);
|
|
addCycle(3.6, [{x:0,y:-15},{x:-120,y:-220},{x:350,y:-380},{x:DX,y:DY}], 2.5, -22);
|
|
`;
|
|
|
|
const sig = (anims: ReturnType<typeof parseGsapScriptAcorn>["animations"]) =>
|
|
anims
|
|
.map(
|
|
(a) =>
|
|
`${a.targetSelector}|${a.method}|${a.resolvedStart}|arc:${a.arcPath?.segments.length ?? 0}|kf:${a.keyframes?.keyframes.length ?? 0}`,
|
|
)
|
|
.join("\n");
|
|
|
|
describe("unrollComputedTimeline", () => {
|
|
it("unrolls helper calls into literal tweens (visual no-op)", () => {
|
|
const before = parseGsapScriptAcorn(ARC_SCRIPT);
|
|
const unrolled = unrollComputedTimeline(ARC_SCRIPT);
|
|
const after = parseGsapScriptAcorn(unrolled);
|
|
|
|
// Same animations, same times, same arcs/keyframes — the render is unchanged.
|
|
expect(after.animations).toHaveLength(before.animations.length);
|
|
expect(sig(after.animations)).toBe(sig(before.animations));
|
|
});
|
|
|
|
it("produces only literal tweens (no helper, no provenance)", () => {
|
|
const unrolled = unrollComputedTimeline(ARC_SCRIPT);
|
|
expect(unrolled).not.toContain("addCycle");
|
|
expect(unrolled).not.toContain("function ");
|
|
const after = parseGsapScriptAcorn(unrolled);
|
|
expect(after.animations.every((a) => a.provenance === undefined)).toBe(true);
|
|
// Arc tweens survive as real motionPath arcs.
|
|
expect(after.animations.filter((a) => a.arcPath?.enabled)).toHaveLength(2);
|
|
});
|
|
|
|
it("unrolls a bounded for-loop", () => {
|
|
const script = `const tl = gsap.timeline();
|
|
for (let i = 0; i < 3; i++) { tl.to("#x", { x: 100, duration: 0.5 }, i * 0.5); }`;
|
|
const unrolled = unrollComputedTimeline(script);
|
|
expect(unrolled).not.toContain("for (");
|
|
const after = parseGsapScriptAcorn(unrolled);
|
|
expect(after.animations.map((a) => a.resolvedStart)).toEqual([0, 0.5, 1]);
|
|
expect(after.animations.every((a) => a.provenance === undefined)).toBe(true);
|
|
});
|
|
|
|
it("leaves a fully-literal composition unchanged", () => {
|
|
const script = `const tl = gsap.timeline();
|
|
tl.from("#a", { opacity: 0, duration: 0.5 }, 0.1);`;
|
|
expect(unrollComputedTimeline(script)).toBe(script);
|
|
});
|
|
});
|