fix(core): harden runtime resolution + inline prebuilt constant

[miguel-heygen]

Summary

Eliminates the "source tree assumed co-located with the bundle" failure mode from @hyperframes/core so future bundler-consumers don't rediscover the #452 bug. Three atomic commits:

1. Guard in core (2A): buildHyperframesRuntimeScript() now checks existsSync(entryPath) before calling esbuild.buildSync(). Returns null when entry.ts is missing instead of crashing with stderr output. Any consumer that bundles core is safe without needing their own guard.

2. Inline prebuilt constant (2B): The build script now generates src/generated/runtime-inline.ts containing the IIFE as a string constant. New export getHyperframeRuntimeScript() returns this constant — no esbuild, no file I/O, no import.meta.url arithmetic. This is the production-safe default path.

3. CLI consumer update: loadRuntimeSource() resolution chain is now:

1. buildFromSource() — esbuild from entry.ts (dev only)
2. getInlinedRuntime() — baked-in constant via getHyperframeRuntimeScript() (production)
3. readPrebuiltArtifact() — reads IIFE file from dist/ (fallback)

The split follows the design Rames called out: loadHyperframeRuntimeSource stays as the dev-only helper that reaches for entry.ts, and getHyperframeRuntimeScript() is the new production path. Consumers don't need to know the difference.

Design

                    ┌──────────────────────────┐
                    │  @hyperframes/core       │
                    ├──────────────────────────┤
  dev-only ──────── │ loadHyperframeRuntimeSource()  │ → esbuild from entry.ts
                    │   returns null if missing      │
                    ├──────────────────────────┤
  production ────── │ getHyperframeRuntimeScript()   │ → returns string constant
                    │   no I/O, no esbuild           │
                    └──────────────────────────┘

The generated file src/generated/runtime-inline.ts is:

• Created by scripts/build-hyperframes-runtime-artifact.ts during bun run build
• Gitignored (build artifact)
• Compiled by tsc into dist/generated/runtime-inline.js
• Included in the published package via "files": ["dist"]

Test plan

• bun run build — passes (build order changed: build:hyperframes-runtime && tsc so generated file exists before tsc)
• bun run --cwd packages/core test — 514 tests pass
• bun run --cwd packages/cli test — 161 tests pass
• oxlint + oxfmt clean on all changed files
• npm pack --dry-run confirms dist/generated/runtime-inline.js ships in the published package
• CI green

[jrusso1020]

Verdict: approve

Clean execution of the design we discussed, split into three self-contained commits.

(2A) Guard is at the right layer now. buildHyperframesRuntimeScript gates on existsSync(entryPath) and returns null before touching esbuild — eliminating the stderr output class (not just suppressing it). Signature change to string | null propagates correctly: all callers handle null — loadHyperframeRuntimeSource loses its non-null guarantee and passes through, the dev-only test scripts (test-hyperframe-runtime-behavior.ts, test-hyperframe-runtime-contract.ts, engine's test-fitTextFontSize-browser.ts) add explicit assert(x !== null, ...) because they run in the dev workspace where entry.ts must exist, and build-hyperframes-runtime-artifact.ts throws loudly if source is missing (which would mean the build is misconfigured — correct place to fail).

(2B) Inline constant is the right shape. The build script now emits src/generated/runtime-inline.ts containing RUNTIME_IIFE as a JSON.stringify-escaped string literal — handles quotes, newlines, and any unicode in the IIFE safely. getHyperframeRuntimeScript() returns it verbatim: no file I/O, no esbuild, no import.meta.url arithmetic. Exported from src/index.ts, so consumers (including the CLI bundled via tsup's noExternal) will inline the constant directly into their bundle — which is the whole point.

Build order flip is necessary, not cosmetic. "build": "bun run build:hyperframes-runtime && tsc" — artifact gen has to run first so src/generated/runtime-inline.ts exists before tsc tries to compile + emit types for it. The artifact script uses bun run which handles TS imports at runtime, so it doesn't depend on tsc having run yet — no circular dep.

CLI consumer chain:

buildFromSource   (dev only)        → entry.ts via esbuild
getInlinedRuntime (production)       → baked-in constant
readPrebuiltArtifact (fallback)      → IIFE file on disk

Strategy 3 is effectively redundant in production once strategy 2 is reliable, but keeping it as a safety net is fine — costs nothing, covers the "old @hyperframes/core without getHyperframeRuntimeScript" transition case during rollout.

Matches the design I flagged earlier — loadHyperframeRuntimeSource stays dev-only (reaches for entry.ts), getHyperframeRuntimeScript is the new production default, consumers don't need to know the difference.

Two non-blockers:

1. Fresh-clone DX footgun. src/generated/ is gitignored, but src/index.ts re-exports getHyperframeRuntimeScript from ./generated/runtime-inline. On a fresh clone, tsc --noEmit (editor typecheck, IDE integration, or any CI step that runs before bun run build) will fail with Cannot find module './generated/runtime-inline' until the artifact script runs. Easy fix later: add a postinstall script ("postinstall": "bun run build:hyperframes-runtime") in packages/core/package.json so bun install always leaves the workspace in a typecheck-clean state. Not required today since bun run build runs the artifact step before tsc — but the first engineer who opens the repo in an editor without running build first will hit this.

2. Tarball bloat (trivial). @hyperframes/core's published dist/ now ships both the IIFE as a file AND the IIFE inlined into dist/generated/runtime-inline.js. ~hundreds of KB of duplicated JS text. Fine — the DX win trades favorably.

Typecheck/Test/Lint/Windows jobs are still in-flight as I review; if any of them trip (specifically Typecheck, given the generated-file arithmetic above), worth double-checking that build:hyperframes-runtime runs before typecheck in every CI path. Local passes (bun run build, 514 core tests, 161 CLI tests, oxlint clean) are strong priors that it's wired correctly.

Ship it.

---

Review by hyperframes