refactor: extract @hyperframes/parsers from core by miguel-heygen · Pull Request #1755 · heygen-com/hyperframes

miguel-heygen · 2026-06-27T01:16:39Z

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 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

bun run --filter @hyperframes/parsers test — 660 tests pass
bun run --filter @hyperframes/sdk test — 382 tests pass
bun run build — full monorepo build succeeds
Fallow audit passes on CI

Moves all GSAP parser/writer modules, HTML parser, hf-ids, spring ease, and related types from packages/core/src/parsers/ into a new standalone packages/parsers package with its own build pipeline. Core keeps thin re-export stubs at the old subpath locations for backward compatibility. Consumer imports (studio hooks, sdk, studio-api routes) are updated to import from @hyperframes/parsers directly.

Moves all lint rules, hyperframeLinter, lintProject, and related types from packages/core/src/lint/ into a new standalone packages/lint package. Core keeps a thin re-export stub at @hyperframes/core/lint for backward compatibility. Consumer imports (cli lint command, producer hyperframeLint) are updated to import from @hyperframes/lint directly. Depends on @hyperframes/parsers (PR #1755).

Moves all studio-api routes, helpers, and Hono server wiring from packages/core/src/studio-api/ into a new standalone packages/studio-server package (@hyperframes/studio-server). Core keeps thin re-export stubs at @hyperframes/core/studio-api and the subpath helpers (screenshot-clip, draft-markers, etc.) for backward compatibility. Consumer imports (cli studioServer, vite adapter/config, producer htmlCompiler, studio manualEditsTypes) are updated to import from @hyperframes/studio-server directly. Also exports rewriteInlineStyleAssetUrls from @hyperframes/core root (was in compiler/rewriteSubCompPaths.ts but not re-exported), required by @hyperframes/studio-server/helpers/subComposition. Removes postcss-selector-parser from @hyperframes/core dependencies (moved to @hyperframes/studio-server which owns the routes that used it). Depends on @hyperframes/parsers (PR #1755).

miguel-heygen · 2026-06-27T02:42:13Z

refactor: extract @hyperframes/parsers from core #1755 : 2 dependent PRs (#1756 , #1757 ) 👈 (View in Graphite)
main

This stack of pull requests is managed by Graphite. Learn more about stacking.

Moves all lint rules, hyperframeLinter, lintProject, and related types from packages/core/src/lint/ into a new standalone packages/lint package. Core keeps a thin re-export stub at @hyperframes/core/lint for backward compatibility. Consumer imports (cli lint command, producer hyperframeLint) are updated to import from @hyperframes/lint directly. Depends on @hyperframes/parsers (PR #1755).

Moves all studio-api routes, helpers, and Hono server wiring from packages/core/src/studio-api/ into a new standalone packages/studio-server package (@hyperframes/studio-server). Core keeps thin re-export stubs at @hyperframes/core/studio-api and the subpath helpers (screenshot-clip, draft-markers, etc.) for backward compatibility. Consumer imports (cli studioServer, vite adapter/config, producer htmlCompiler, studio manualEditsTypes) are updated to import from @hyperframes/studio-server directly. Also exports rewriteInlineStyleAssetUrls from @hyperframes/core root (was in compiler/rewriteSubCompPaths.ts but not re-exported), required by @hyperframes/studio-server/helpers/subComposition. Removes postcss-selector-parser from @hyperframes/core dependencies (moved to @hyperframes/studio-server which owns the routes that used it). Depends on @hyperframes/parsers (PR #1755).

… test holds

Moves all lint rules, hyperframeLinter, lintProject, and related types from packages/core/src/lint/ into a new standalone packages/lint package. Core keeps a thin re-export stub at @hyperframes/core/lint for backward compatibility. Consumer imports (cli lint command, producer hyperframeLint) are updated to import from @hyperframes/lint directly. Depends on @hyperframes/parsers (PR #1755).

Moves all studio-api routes, helpers, and Hono server wiring from packages/core/src/studio-api/ into a new standalone packages/studio-server package (@hyperframes/studio-server). Core keeps thin re-export stubs at @hyperframes/core/studio-api and the subpath helpers (screenshot-clip, draft-markers, etc.) for backward compatibility. Consumer imports (cli studioServer, vite adapter/config, producer htmlCompiler, studio manualEditsTypes) are updated to import from @hyperframes/studio-server directly. Also exports rewriteInlineStyleAssetUrls from @hyperframes/core root (was in compiler/rewriteSubCompPaths.ts but not re-exported), required by @hyperframes/studio-server/helpers/subComposition. Removes postcss-selector-parser from @hyperframes/core dependencies (moved to @hyperframes/studio-server which owns the routes that used it). Depends on @hyperframes/parsers (PR #1755).

Moves all lint rules, hyperframeLinter, lintProject, and related types from packages/core/src/lint/ into a new standalone packages/lint package. Core keeps a thin re-export stub at @hyperframes/core/lint for backward compatibility. Consumer imports (cli lint command, producer hyperframeLint) are updated to import from @hyperframes/lint directly. Depends on @hyperframes/parsers (PR #1755).

Moves all studio-api routes, helpers, and Hono server wiring from packages/core/src/studio-api/ into a new standalone packages/studio-server package (@hyperframes/studio-server). Core keeps thin re-export stubs at @hyperframes/core/studio-api and the subpath helpers (screenshot-clip, draft-markers, etc.) for backward compatibility. Consumer imports (cli studioServer, vite adapter/config, producer htmlCompiler, studio manualEditsTypes) are updated to import from @hyperframes/studio-server directly. Also exports rewriteInlineStyleAssetUrls from @hyperframes/core root (was in compiler/rewriteSubCompPaths.ts but not re-exported), required by @hyperframes/studio-server/helpers/subComposition. Removes postcss-selector-parser from @hyperframes/core dependencies (moved to @hyperframes/studio-server which owns the routes that used it). Depends on @hyperframes/parsers (PR #1755).

terencecho

Textbook-clean extraction. Every load-bearing axis checks out:

Verified

Shim completeness: 6 @deprecated stubs in packages/core/src/parsers/ (gsapConstants / gsapParserAcorn / gsapParserExports / gsapWriterAcorn / hfIds / springEase), each a one-liner export * from the new package. core/package.json keeps all 6 old subpath exports. core.types.ts re-exports every moved type + runtime symbol. Repo-wide search for gsap-parser-recast (the one parsers-only subpath) finds zero consumers — no stub needed for it.
Public surface: packages/core/src/index.ts keeps every previously-exported name; only 4 source-path lines change.
Test parity: 19 *.test.ts files move 1:1, no orphans.
Dep hygiene: core drops @babel/parser / acorn / acorn-walk / magic-string / recast; parsers picks up exactly those 5. Post-PR packages/core/src/ has zero direct imports of any of them outside the 6 stubs.
Bun-first exports: { "bun": "./src/...ts", "node": "./dist/...js", ... } ordering consistent; publishConfig.exports correctly maps to dist/ only.
Fallow audit: new ignore entries are scoped to relocated files (intentional recast↔acorn parity blocks); no suspicious masking.
CI ordering: bun run --filter '@hyperframes/parsers' build && bun run --cwd packages/core build lands before every vitest/studio job that resolves via the "node" condition. preview-regression.yml path filter includes packages/parsers/**. Publish order: parsers before core. ✓

Non-blocking polish

packages/parsers/src/index.ts re-exports gsapUnroll / cssSelector as named (unrollComputedTimeline, queryByAttr) rather than full export *. If those modules grow new public symbols, they won't surface via the top-level barrel — only via subpaths. Tight by design, just worth knowing.
linkedom is now in both core and parsers deps. Both genuinely use it (parsers for HTML parsing, core for non-parser runtime DOM), so the dup is real, not a leak — workspace dedupes at install.

— Review by tai (pr-review)

miguel-heygen · 2026-06-27T04:46:11Z

Merge activity

Jun 27, 4:46 AM UTC: A user started a stack merge that includes this pull request via Graphite.
Jun 27, 4:46 AM UTC: @miguel-heygen merged this pull request with Graphite.

Moves all lint rules, hyperframeLinter, lintProject, and related types from packages/core/src/lint/ into a new standalone packages/lint package. Core keeps a thin re-export stub at @hyperframes/core/lint for backward compatibility. Consumer imports (cli lint command, producer hyperframeLint) are updated to import from @hyperframes/lint directly. Depends on @hyperframes/parsers (PR #1755).

Moves all studio-api routes, helpers, and Hono server wiring from packages/core/src/studio-api/ into a new standalone packages/studio-server package (@hyperframes/studio-server). Core keeps thin re-export stubs at @hyperframes/core/studio-api and the subpath helpers (screenshot-clip, draft-markers, etc.) for backward compatibility. Consumer imports (cli studioServer, vite adapter/config, producer htmlCompiler, studio manualEditsTypes) are updated to import from @hyperframes/studio-server directly. Also exports rewriteInlineStyleAssetUrls from @hyperframes/core root (was in compiler/rewriteSubCompPaths.ts but not re-exported), required by @hyperframes/studio-server/helpers/subComposition. Removes postcss-selector-parser from @hyperframes/core dependencies (moved to @hyperframes/studio-server which owns the routes that used it). Depends on @hyperframes/parsers (PR #1755).

* refactor: extract @hyperframes/lint package from core Moves all lint rules, hyperframeLinter, lintProject, and related types from packages/core/src/lint/ into a new standalone packages/lint package. Core keeps a thin re-export stub at @hyperframes/core/lint for backward compatibility. Consumer imports (cli lint command, producer hyperframeLint) are updated to import from @hyperframes/lint directly. Depends on @hyperframes/parsers (PR #1755). * fix: restore postcss-selector-parser in core (sourceMutation.ts still uses it) * fix(ci): add parsers+lint to Dockerfile and build before preview tests * chore: update bun.lock after restoring postcss-selector-parser dep * test(cli): update lintProject test for string-dir signature from @hyperframes/lint * refactor(core): single-source the lint engine in @hyperframes/lint Delete core's byte-identical copy of the lint rule engine and re-point staticGuard at @hyperframes/lint, so the render-time render-gate and the studio preview share one rule engine instead of two copies that could silently diverge. Back-compat preserved via the @hyperframes/core/lint stub. Addresses review feedback on the dual-copy footgun.

* refactor: extract @hyperframes/studio-server package from core Moves all studio-api routes, helpers, and Hono server wiring from packages/core/src/studio-api/ into a new standalone packages/studio-server package (@hyperframes/studio-server). Core keeps thin re-export stubs at @hyperframes/core/studio-api and the subpath helpers (screenshot-clip, draft-markers, etc.) for backward compatibility. Consumer imports (cli studioServer, vite adapter/config, producer htmlCompiler, studio manualEditsTypes) are updated to import from @hyperframes/studio-server directly. Also exports rewriteInlineStyleAssetUrls from @hyperframes/core root (was in compiler/rewriteSubCompPaths.ts but not re-exported), required by @hyperframes/studio-server/helpers/subComposition. Removes postcss-selector-parser from @hyperframes/core dependencies (moved to @hyperframes/studio-server which owns the routes that used it). Depends on @hyperframes/parsers (PR #1755). * fix(ci): add parsers+studio-server to Dockerfile and build before preview tests * fix(ci): build @hyperframes/studio-server before Test and studio load smoke Studio's vite.config.ts imports @hyperframes/studio-server, which resolves via its "node" export condition to built dist. The Test and studio-load-smoke jobs only built parsers + core, so esbuild's config load failed to resolve the package entry. Build studio-server too. * fix(studio): repoint sdkCutoverParity test import to studio-server sourceMutation moved from core's studio-api to @hyperframes/studio-server; the test still imported the deleted core path. This was masked while studio's vite.config failed to load (couldn't resolve studio-server); now that the config loads, the test runs and the stale import surfaced.

New docs pages for the three packages extracted from core (#1755, #1756, #1757), wired into the Packages nav after @hyperframes/core. Each covers when-to-use, exports, and API with cross-links. Core's parser/lint sections now point at the dedicated packages and its Related Packages lists all three.

This was referenced Jun 27, 2026

refactor: extract @hyperframes/lint from core #1756

Merged

refactor: extract @hyperframes/studio-server from core #1757

Merged

refactor: extract @hyperframes/parsers, @hyperframes/lint, @hyperframes/studio-server #1754

Closed

miguel-heygen force-pushed the refactor/extract-parsers branch from 9b0a843 to 019278f Compare June 27, 2026 02:40

fix(ci): build parsers + core before tests and Docker regression run

1a4e0db

fix(cli): alias @hyperframes/core to source in vitest so runtime-load…

459551e

… test holds

fix(ci): build parsers + core before sdk tests and studio load smoke

0eb1a42

terencecho approved these changes Jun 27, 2026

View reviewed changes

miguel-heygen merged commit cdf9c81 into main Jun 27, 2026
76 checks passed

miguel-heygen deleted the refactor/extract-parsers branch June 27, 2026 04:46

WaterrrForever mentioned this pull request Jun 27, 2026

fix(ci): build @hyperframes/lint before core in Test and Studio jobs #1769

Closed

3 tasks

miguel-heygen mentioned this pull request Jun 27, 2026

docs: add package pages for parsers, lint, and studio-server #1772

Merged

Breno-Oliveira10 mentioned this pull request Jun 27, 2026

feat: RFC — lightweight @hyperframes/validator package & browser-side pipeline for third-party integrations #1749

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

refactor: extract @hyperframes/parsers from core#1755

refactor: extract @hyperframes/parsers from core#1755
miguel-heygen merged 4 commits into
mainfrom
refactor/extract-parsers

miguel-heygen commented Jun 27, 2026 •

edited

Loading

Uh oh!

miguel-heygen commented Jun 27, 2026

Uh oh!

terencecho left a comment

Uh oh!

miguel-heygen commented Jun 27, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

miguel-heygen commented Jun 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What moves

Bundle footprint of the new package

How @hyperframes/core changes

Design notes

Test plan

Uh oh!

miguel-heygen commented Jun 27, 2026

Uh oh!

terencecho left a comment

Choose a reason for hiding this comment

Uh oh!

miguel-heygen commented Jun 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge activity

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

miguel-heygen commented Jun 27, 2026 •

edited

Loading

How `@hyperframes/core` changes

miguel-heygen commented Jun 27, 2026 •

edited

Loading