refactor: extract @hyperframes/parsers from core

.fallowrc.jsonc

@@ -142,13 +142,13 @@
         "createFailedCaptureCalibrationEstimate",
       ],
     },
-    // gsapParser.ts is a public-API barrel that re-exports constants, types,
-    // and utilities from gsapConstants, gsapSerialize, and springEase. The
-    // re-exports are intentional public API consumed by callers outside the
+    // gsapParserExports.ts is the public-API barrel that re-exports constants,
+    // types, and utilities from gsapConstants, gsapSerialize, and springEase.
+    // The re-exports are intentional public API consumed by callers outside the
     // changed-file set (e.g. studio, aws-lambda) and therefore appear unused
     // to fallow's static analysis of the PR diff.
     {
-      "file": "packages/core/src/parsers/gsapParser.ts",
+      "file": "packages/parsers/src/gsapParserExports.ts",
       "exports": [
         "PROPERTY_GROUPS",
         "classifyPropertyGroup",
@@ -165,14 +165,20 @@
     // Shared test helpers consumed by gsapParser.test.ts (same file,
     // fallow doesn't trace intra-file test consumption).
     {
-      "file": "packages/core/src/parsers/gsapParser.test-helpers.ts",
+      "file": "packages/parsers/src/gsapParser.test-helpers.ts",
       "exports": [
         "expectKeyframe",
         "expectKeyframesFormat",
         "convertAndReparse",
         "parseSplitAndAssert",
       ],
     },
+    // hfIds: EXCLUDED_TAGS is consumed by tests (htmlParser.test.ts) and
+    // hfIdPersist.ts but fallow's static analyzer may not trace all consumers.
+    {
+      "file": "packages/parsers/src/hfIds.ts",
+      "exports": ["EXCLUDED_TAGS", "mintHfId"],
+    },
     // Shared timeline components extracted for downstream PRs in the
     // razor-blade stack (#1330, #1331). Consumers live on those branches.
     {
@@ -244,6 +250,23 @@
     // require intrusive middleware changes beyond this PR's scope.
     "minLines": 6,
     "ignore": [
+      // gsapParser.ts: recast/babel GSAP writer — intentional duplication between
+      // recast and acorn parallel implementations (pre-existing, moved from core).
+      "packages/parsers/src/gsapParser.ts",
+      // hfIds.ts: 7-line clone with sdk/engine/mutate.ts — pre-existing duplication
+      // from when hfIds lived in packages/core/src/parsers/. Moving the file to the
+      // new package makes fallow see it as a fresh finding; the underlying clone
+      // predates this refactor.
+      "packages/parsers/src/hfIds.ts",
+      // Parser test files: parallel arrange/act/assert test cases — pre-existing
+      // duplication moved from packages/core/src/parsers/.
+      "packages/parsers/src/gsapParser.test.ts",
+      "packages/parsers/src/gsapParser.test-helpers.ts",
+      "packages/parsers/src/gsapWriter.parity.test.ts",
+      "packages/parsers/src/gsapWriterParity.corpus.test.ts",
+      "packages/parsers/src/gsapWriterParity.acorn.test.ts",
+      "packages/parsers/src/htmlParser.roundtrip.test.ts",
+      "packages/parsers/src/htmlParser.test.ts",
       // slideshowPanelHelpers.ts: setSlideNotes/addFragment/addHotspot share an
       // intentional parallel shape (signature + mapSlidesIn → exists-check →
       // map/append); the per-slide mutation differs, so a shared abstraction
@@ -276,26 +299,18 @@
     ],
   },
   "health": {
-    // executeGsapMutation (introduced by Phase 3b / acorn-parser stack, already
-    // merged to origin/main via #1338) has CRITICAL cyclomatic complexity (58)
-    // that pre-dates this PR's scope. Excluding files.ts from health analysis
-    // avoids the inherited-fingerprint line-shift problem that suppression
-    // comments would cause (any inserted line shifts subsequent function line
-    // numbers, breaking fallow's inherited-detection fingerprint).
-    //
     // useGsapTweenCache.ts: pre-existing large React-effect hooks (the populate
     // and runtime-scan effects, the per-element animations memo) whose
     // complexity pre-dates the computed-timeline work. Exempted at file level
-    // for the same reason as files.ts rather than refactored as scope creep.
-    //
-    // gsapParser.ts: the recast/babel GSAP writer is a 2500-line legacy parser
-    // restored as the default server writer by WS-3.F rework (acorn is now
-    // flag-gated behind STUDIO_SDK_CUTOVER_ENABLED). Its complexity pre-dates
-    // this PR and was present on all ancestor branches; the file-level exemption
-    // avoids the line-shift fingerprint problem for inherited findings.
+    // rather than refactored as scope creep.
     "ignore": [
+      // gsapParser.ts: the recast/babel GSAP writer is a 2500-line legacy parser;
+      // moved from packages/core/src/parsers/ — same complexity rationale.
+      "packages/parsers/src/gsapParser.ts",
+      // htmlParser.ts has pre-existing complexity (moved from packages/core).
+      "packages/parsers/src/htmlParser.ts",
+      // executeGsapMutation (CRITICAL) pre-dates this PR; studio-api still lives in core.
       "packages/core/src/studio-api/routes/files.ts",
-      "packages/core/src/parsers/gsapParser.ts",
       // SlideshowPanel.tsx: top-level editor panel that wires several independent
       // sections (slides/inspector/branches/hotspot). Its cyclomatic count comes
       // from that fan-out; splitting it would scatter shared state without
@@ -313,6 +328,23 @@
       // vs base-var args, validation throws) but small and well-tested via the
       // generated table's shape test; this is dev tooling, not shipped runtime.
       "packages/cli/scripts/sync-agent-dirs.ts",
+      // Files modified only for import-path updates (one-line changes to switch
+      // from @hyperframes/core/* subpaths to @hyperframes/parsers). Their complexity
+      // is pre-existing; the line-shift fingerprint problem makes fallow treat
+      // the violations as new even though no logic changed.
+      "packages/core/src/core.types.ts",
+      "packages/core/src/generators/hyperframes.ts",
+      "packages/studio/src/hooks/gsapRuntimeBridge.ts",
+      "packages/studio/src/hooks/gsapShared.ts",
+      "packages/studio/src/hooks/gsapDragPositionCommit.ts",
+      "packages/studio/src/hooks/gsapKeyframeCacheHelpers.ts",
+      // set-version.ts: compareSemver helper has pre-existing complexity from
+      // semver string parsing logic; line-shift fingerprint problem from new
+      // packages added to PACKAGES array makes fallow treat it as new.
+      "scripts/set-version.ts",
+      // gsapRuntimeReaders.ts: pre-existing complexity in readAllAnimatedProperties;
+      // line-shift fingerprint from import-path updates triggers the violation.
+      "packages/studio/src/hooks/gsapRuntimeReaders.ts",
     ],
   },
 }

.github/workflows/ci.yml

@@ -227,6 +227,8 @@ jobs:
       - uses: ./.github/actions/prepare-ffmpeg-bin
       - run: bun install --frozen-lockfile
       - run: bun run test:scripts
+      - run: bun run --filter '@hyperframes/parsers' build
+      - run: bun run --cwd packages/core build
       - run: bun run --cwd packages/core build:hyperframes-runtime
       - run: bun run --filter '!@hyperframes/producer' test
 
@@ -315,6 +317,10 @@ jobs:
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
       - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
       - run: bun install --frozen-lockfile
+      # Build workspace deps so the sdk's @hyperframes/parsers + core subpath
+      # imports resolve via the "node" export condition (dist) under vitest.
+      - run: bun run --filter '@hyperframes/parsers' build
+      - run: bun run --cwd packages/core build
       - run: bun run --filter @hyperframes/sdk test
 
   test-runtime-contract:
@@ -351,6 +357,10 @@ jobs:
           node-version: 22
       - uses: ./.github/actions/prepare-ffmpeg-bin
       - run: bun install --frozen-lockfile
+      # Build workspace deps so the studio vite.config.ts (loaded by Node) can
+      # resolve @hyperframes/core via the "node" export condition (dist).
+      - run: bun run --filter '@hyperframes/parsers' build
+      - run: bun run --cwd packages/core build
       - run: bun run --cwd packages/core build:hyperframes-runtime
       - name: Start studio and check for runtime errors
         run: |

.github/workflows/preview-regression.yml

@@ -36,6 +36,7 @@ jobs:
           filters: |
             preview:
               - "packages/core/**"
+              - "packages/parsers/**"
               - "packages/player/**"
               - "packages/studio/**"
               - "packages/cli/**"
@@ -73,6 +74,11 @@ jobs:
 
       - run: bun install --frozen-lockfile
 
+      - name: Build workspace packages (required for vite config loading)
+        run: |
+          bun run --filter '@hyperframes/parsers' build
+          bun run --cwd packages/core build
+
       - name: Run Studio preview routing regression
         run: |
           bun run --cwd packages/studio test -- vite.thumbnail.test.ts src/utils/projectRouting.test.ts src/utils/frameCapture.test.ts

.github/workflows/publish.yml

@@ -124,6 +124,7 @@ jobs:
             fi
           }
 
+          publish_pkg "@hyperframes/parsers" "@hyperframes/parsers"
           publish_pkg "@hyperframes/core" "@hyperframes/core"
           publish_pkg "@hyperframes/sdk" "@hyperframes/sdk"
           publish_pkg "@hyperframes/engine" "@hyperframes/engine"

Dockerfile.test

@@ -74,6 +74,7 @@ ENV PATH="/root/.bun/bin:$PATH"
 # --frozen-lockfile` treats any member missing from the build context as a
 # lockfile change and fails.
 COPY package.json bun.lock ./
+COPY packages/parsers/package.json packages/parsers/package.json
 COPY packages/core/package.json packages/core/package.json
 COPY packages/engine/package.json packages/engine/package.json
 COPY packages/player/package.json packages/player/package.json
@@ -88,10 +89,15 @@ COPY packages/sdk-playground/package.json packages/sdk-playground/package.json
 RUN bun install --frozen-lockfile
 
 # Copy source
+COPY packages/parsers/ packages/parsers/
 COPY packages/core/ packages/core/
 COPY packages/engine/ packages/engine/
 COPY packages/producer/ packages/producer/
 
+# Build workspace packages so "node" export conditions resolve to built dist
+RUN bun run --filter '@hyperframes/parsers' build \
+    && bun run --cwd packages/core build
+
 # Build core runtime artifacts (needed by renderer)
 RUN bun run --filter @hyperframes/core build:hyperframes-runtime:modular
 

package.json

@@ -11,7 +11,7 @@
   "type": "module",
   "scripts": {
     "dev": "bun run studio",
-    "build": "bun run --filter @hyperframes/core build && bun run --filter '@hyperframes/{core,engine,producer,player,studio,shader-transitions,aws-lambda,gcp-cloud-run,sdk}' build && bun run --filter @hyperframes/cli build",
+    "build": "bun run --filter @hyperframes/parsers build && bun run --filter @hyperframes/core build && bun run --filter '@hyperframes/{core,engine,producer,player,studio,shader-transitions,aws-lambda,gcp-cloud-run,sdk}' build && bun run --filter @hyperframes/cli build",
     "build:producer": "bun run --filter @hyperframes/producer build",
     "studio": "bun run --filter @hyperframes/studio dev",
     "build:hyperframes-runtime": "bun run --filter @hyperframes/core build:hyperframes-runtime",

packages/cli/tsup.config.ts

@@ -61,6 +61,7 @@ var __dirname = __hf_dirname(__filename);`,
   ],
   noExternal: [
     "@hyperframes/core",
+    "@hyperframes/parsers",
     "@hyperframes/producer",
     "@hyperframes/engine",
     "@clack/prompts",

packages/cli/vitest.config.ts

@@ -1,6 +1,21 @@
+import { resolve } from "node:path";
 import { defineConfig } from "vitest/config";
 
 export default defineConfig({
+  resolve: {
+    alias: [
+      // Resolve the bare @hyperframes/core entry to TypeScript source, not built
+      // dist. The published dist intentionally omits runtime/entry.ts, so the
+      // dist build of loadHyperframeRuntimeSource() returns null — which makes
+      // studioServer.test.ts's runtime-source equality assertion diverge. Tests
+      // run under bun against source; subpath imports (@hyperframes/core/*) keep
+      // resolving via the package's export conditions.
+      {
+        find: /^@hyperframes\/core$/,
+        replacement: resolve(__dirname, "../core/src/index.ts"),
+      },
+    ],
+  },
   test: {
     include: ["src/**/*.test.ts"],
   },