fix(runner): resolve the compiler chunk's real module shape on retry (DEV-2569)

[demtario]

Closes DEV-2569 (second pass). Sentry DEMOS-15.

Why this is reopened

The retry mechanism shipped in #235 recovers the fetch and then cannot compile. Verification on deployed master c83975c2 found the card flipping to Failed to transpile /index.js for the parcel sandbox: e.transform is not a function, status stuck on error, 0 grid cells.

Re-confirmed independently against the live bundle (/assets/index-uxATgr1X.js, /assets/babel-Du2YGyP9.js, fetched 2026-08-20):

primary: import("./babel-Du2YGyP9.js").then(t => t.b).then(t => t.default ?? t)
retry:   import(`${n}${r}hotRetry=${e+1}`).then(o => o.default ?? o)
chunk:   const Hke = Mke({__proto__: null, default: qke}, [bH]); export { Hke as b };

Mke is Vite's _mergeNamespaces. Vite rewrites only the bare specifier, and @babel/standalone is CJS, so the primary site gets a CJS-interop hop that /* @vite-ignore */ suppresses on the retry — the retry resolved the chunk's raw module record {b: {…}}, m.default was undefined, m.default ?? m returned the record, and .transform was not a function.

Second half of the defect: because no CompilerUnavailableError was ever constructed, the TypeError surfaced downstream inside babel.transform, fell past the compiler-asset branch in tier1Report.ts, and landed in the visitor bucket ["demo-runtime","sandpack-compile"] at level: warning — our own broken retry filed inside DEMOS-15 as if it were a visitor's typo.

Part A — resolve the real module shape

asBabel(ns, url) replaces the fixed default ?? m unwrap at both import sites: a shape walk over the record, its default, and one wrapper level, preferring default at each — so the primary keeps resolving exactly the object it resolves today, and the retry stops depending on an interop hop it never gets. Walking values rather than unwrapping a hardcoded b is what survives Rollup renaming that export; the name is bundler-generated and pinned by nothing.

Three measured shapes it has to accept:

where	shape
Node / dist (what pipeline/*.test.mjs sees)	{ default: babel, …named }
bundled primary, after Vite's hop	{ __proto__: null, default: babel }
bundled retry, no hop	{ b: { default: babel, transform } }

A miss throws, from inside the loaders, so the rejection reaches createRetryingLoader and becomes a CompilerUnavailableError — latched, carded, and filed under ["tier1-compiler-asset"] at level: error. Wrapped around babelLoader.load instead it would have kept landing in the visitor bucket. The URL rides in the thrown message because assetUrl is recovered by assetUrlFrom regexing the cause, and that hashed path exists nowhere else at runtime.

Unchanged: the bounded two attempts, the ?hotRetry= query (a browser caches a failed module fetch in the document's module map, so a retry must ask for a URL it has never seen), the latch, and rearmCompilerLoad. Safari also stays terminal on the first failure — assetUrlFrom gets no URL out of "Load failed", so retryOf declines.

Part B — remove the exposure that made a retry necessary

The compiler now ships as assets/compiler-babel.js, with no content hash. wrangler.jsonc serves this app from Workers Assets with not_found_handling: "single-page-application", so a deploy removed the previous build's hashed chunks and their paths answered 200 text/html rather than a 404 — an HTML body is not a module, so a tab that had not yet fetched the compiler when a deploy landed was asking for a file that no longer existed, forever. A stable path always exists in the deploy that is live.

No cache-header work goes with it. Measured on prod 2026-08-20, Workers Assets already serves every asset, hashed or not, as cache-control: public, max-age=0, must-revalidate with an ETag, so the stable URL revalidates on each use and picks up new bytes. No _headers file exists and none is needed.

Two accepted consequences, both written into the config comment: a tab open across a deploy that fetches the compiler afterwards gets the new build's babel (benign — we only call transform, and strictly better than a permanent failure), and the Sentry plugin matches sourcemaps by embedded debug id rather than filename, so a name reused across releases does not confuse symbolication.

Renaming only — no manualChunks. The obvious form (manualChunks: id => id.includes("/@babel/standalone/") ? "compiler-babel" : undefined) was measured to pull Rollup's shared getDefaultExportFromCjs into that chunk (export { … as b, … as g }), after which two ordinary chunks imported the 2.3 MB compiler statically and index.html gained a modulepreload for it — every visitor paying for a compiler only Tier-1 examples use. manualChunks assigns a module to a chunk; it does not keep the chunk lazy. Rollup already splits the dynamic import under the implicit name babel, so a one-line chunkFileNames is the whole change.

Tests — and why the existing suite could not see this

pipeline/transpile-loader.test.mjs imports packages/runtime/dist/transpile.js, where both import paths really are equivalent. That is why #235's ten loader tests were green over a broken retry, and it means any test added to that file is green with or without this fix. The shape rule is pinned three ways instead.

1. Unit (pipeline/transpile-loader.test.mjs, +5 cases). The three measured namespace shapes, bundler-export-name independence, and the routing: a module that resolves without transform satisfies isCompilerUnavailable and keeps its assetUrl. Verified red: with the old default ?? m semantics restored, 4 fail — the wrapper is not the compiler.

2. Deterministic Playwright (e2e/preview-recovery.spec.ts). playwright.config.ts already serves a real vite build, which is the only place the divergence exists. The case blocks **/assets/compiler-babel.js* (trailing * load-bearing, or the ?hotRetry=n requests slip past), asserts the card copy and exactly two bounded attempts, then lifts the block and clicks Restart preview.

Two things I got wrong on the way there, both fixed, because they are the kind of thing that reads as coverage and is not:

• stubShell does not make a Tier-1 parcel example deterministic. Its globs are sandpack.codesandbox.io and sandpack-bundler.codesandbox.io; a parcel sandbox loads a versioned host (2-19-8-sandpack.codesandbox.io) plus jsdelivr and prod-packager-packages. The case now aborts everything off-localhost on top.
• data-preview-status is not the oracle. booting is on the failure path too (it precedes error), so asserting it passed with the fix reverted. The oracle is an attempted bundler request: buildSetup throws inside sandboxFiles() before the client is created, so a failed transpile never reaches the bundler. Measured 2 attempts with this fix, 0 without. The requests are aborted at the route layer, so nothing leaves the machine.

Verified red: with only the two asBabel calls reverted, Expected: > 0, Received: 0.

3. scripts/check-compiler-chunk.mjs, run in the authoring CI job (the job that has the build). Pins the hash-free name, that index.html never references the chunk, that nothing imports it statically, and that exactly one chunk imports it dynamically. Verified red against the manualChunks variant above.

A second case behind E2E_LIVE=1 drives the same recovery through a real bundler to ready + expectGridRendered — the visible recovery that was never clicked through before #235 shipped. preview-recovery.spec.ts is already named in e2e-live.yml, so no workflow change. Not run here (needs the external bundler).

Verification

Run from runner/ with raw pnpm (rtk filters have fabricated pass summaries on this repo), against my own preview port — 4173 was held by another worktree.

	result
pnpm test	845 pass / 0 fail / 2 todo
pnpm typecheck	clean
node scripts/check-compiler-chunk.mjs	compiler chunk ok: assets/compiler-babel.js, lazily imported by index-DrczjuWM.js only
pnpm e2e e2e/preview-recovery.spec.ts	4 passed, 5 skipped (live)
full deterministic suite	201 passed
presence gate	pass — 3 source files changed with a matching test change

The 6 share-view.spec.ts failures in the full run are its own documented E2E_BASE_URL gate ("needs a deployed API origin — vite preview has no /api or /d routes") firing because pointing at a private port sets that variable. They skip in PR CI.

Left for testing

Only the grouping half of the original acceptance, and it is structurally not machine-checkable: reportingGate.ts gates on navigator.webdriver, so no automated run can mint a Sentry event. DEMOS-15's title and the ["tier1-compiler-asset"] split need one human look at the issue list after real post-fix traffic. Nothing in this PR verifies that, and the green e2e should not be read as if it does.

🤖 Generated with Claude Code

---

Note

Medium Risk
Touches Tier‑1 transpile loading and production bundle splitting; wrong chunk naming or asBabel logic could break all parcel previews or regress initial load size, though coverage is strong.

Overview
Fixes DEV-2569 / DEMOS-15: Tier‑1 preview could stay broken after a compiler fetch retry because the ?hotRetry= import got a different module shape than the primary @babel/standalone chunk (Vite CJS interop vs @vite-ignore), yielding e.transform is not a function and mis-filed Sentry noise.

Runtime: asBabel walks namespace/default/nested values at both load and retry sites; a miss throws with the URL so createRetryingLoader surfaces CompilerUnavailableError instead of a visitor compile error.

Build: Authoring Vite chunkFileNames emits a hash-free assets/compiler-babel.js so deploys don’t leave stale tabs fetching rotated hashed chunks that Workers SPA fallback serves as HTML. scripts/check-compiler-chunk.mjs (CI after build + pnpm check:compiler-chunk) asserts the stable name, lazy dynamic import only, and no index.html preload.

Tests: Five loader unit cases for measured namespace shapes; Playwright blocks compiler-babel.js, asserts Restart preview reaches the bundler after recovery; optional E2E_LIVE grid check.

^{Reviewed by Cursor Bugbot for commit 001de30. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 001de30. Configure here.}