fix(runner): take the theme module out below the theme API (DEV-2571)

[demtario]

Sentry DEMOS-1P: DemoError: Could not find module in path: 'handsontable/themes' relative to '/handsontable-theme.js'.

The Style panel's generated /handsontable-theme.{ts,js} is a real workspace file, and THEME_API_MIN_MAJOR = 17 only ever disabled the toolbar button. So the module outlived the version that wrote it, and below 17 the preview cannot resolve its own imports.

The reported event was the bare-major hole, not the downgrade

App.tsx's releaseMajor read the major off the raw version string with /^(\d+)\./. A bare 16 or 16.2 has no match, so it answered null — and null is the pass-through that lets next and pkg.pr.new refs be themed. Both are versions validateHandsontableVersion accepts (coerced to 16.0.0), and both reach version state verbatim: the version pencil forwards any trimmed string, and ?v= is read raw. So ?v=16 opened the Style panel on a v16 core.

That is also the one shape where the generated module is the only importer of handsontable/themes — a 16 starter wires themeName — which is why Sandpack named /handsontable-theme.js and nothing else.

Fixed by selectedReleaseMajor in packages/runtime/src/version.ts: validate, then take the major. null now means only "no comparable release major here" — next nightlies, dotted -next prereleases, pkg.pr.new ids, and anything the validator refuses. It replaces the App-local helper entirely, which also retires a duplicate that disagreed with the runtime's own releaseMajor on both "16" and "19.0.0-next.1".

The downgrade is the second path

A version switch on a dirty workspace deliberately keeps the files it finds and only re-pins them (ADR-0021 §6) — and applying a theme is what dirties the workspace, so a themed demo takes exactly that branch on the way down. The same state also arrives ready-made: a saved, shared or imported workspace can open already themed on a sub-17 pin, with no version change anywhere. A guard on the version handler alone would have shipped green and left that path reporting.

Below the floor the app now runs buildResetChanges over the workspace — the same unwire the panel's own Reset uses, restoring the themeName and container class it displaced — and says so in the preview bar. Nothing of the visitor's is lost: the theme state lives in localStorage, and reopening the panel on a supported core reconciles it straight back in.

Four details worth reading in the diff

• The effect is declared above the runtime-mount effect. Effects run in declaration order, so its write to filesRef.current lands before the remount reads it. Below the mount effect, the broken module is compiled once and only then repaired — which is the reported event.
• The notice is its own state, not a versionWarning string. The dirty-switch branches set that one after this runs, into the same single slot, and a theme is what dirtied the workspace — so the message would always have been the generic "unsaved edits may not match the selected version API" one. The two compose now, theme first. Cleared in loadWorkspace, which every workspace install goes through, so it cannot outlive the files it describes.
• hasWiredTheme reads the module's contents, not its filename. Reset does not delete the file — it leaves customTheme = undefined behind, and writes that file even on a demo that never had a theme.
• Not markDirty. This repairs a workspace that cannot run; it is not an edit the visitor made, and dirtying it would light up Save • on a shared demo nobody has touched.

Two things deliberately left alone

• The >=17 starters import handsontable/themes themselves (isLegacyBucket in pipeline/blank-starters.mjs switches to themeName below 17). So a dirty cross-bucket downgrade can still hold a 17+ API on a 16 core, whatever we do about the theme module. That is ADR-0021's documented trade-off and what the second half of the composed notice is for — worth knowing before writing a test that asserts "no file imports handsontable/themes after a downgrade", because the product makes no such promise.
• shellSchemeMode asks the filename question that hasWiredTheme replaces, so it keeps standing the shell down after a Reset and the light/dark toggle stops reaching the grid. I swapped the predicate, measured it live, and it is not sufficient — the #hot-runner-scheme override does not come back, so there is a second cause in the bridge. Left as found rather than half-fixed; it wants its own ticket and its own test.

Tests

• pipeline/version.test.mjs — selectedReleaseMajor across partials, prereleases, pkg.pr.new ids and refused refs. "16" → 16 is the regression test for the reported hole.
• pipeline/theme-wiring.test.mjs — hasWiredTheme over every wiring shape, plus a cleared module, an unrelated module and a TS workspace; and that Reset leaves no handsontable/themes import behind in any shape.
• e2e/style-panel.spec.ts (deterministic, PR CI) — the downgrade transition; a workspace that arrives themed on a sub-17 pin being repaired on load, with the notice not outliving the workspace; and ?v=16 leaving the Style button disabled.
• e2e/style-apply.spec.ts (E2E_LIVE=1) — the one assertion no amount of generated text can make: after the strip, the demo actually compiles and renders on a core with no theme API.

Verification

Each source file was reverted to master in place and the suites re-run: both pipeline files and all three deterministic specs go red, and the live case reproduces the Sentry message verbatim before the fix and renders a grid after it.

• pnpm test — 756 tests, 0 fail, 0 skipped
• pnpm --filter … typecheck — clean for authoring, runtime, editor-shell, api
• deterministic e2e — 198 passed. The 6 share-view.spec.ts failures in my run are its own test.skip(!E2E_BASE_URL) guard misreading a local vite preview as a deployed API (no /api, no /d route); they reproduce identically on master.
• live style-apply.spec.ts + preview-scheme.spec.ts, --workers=1 — 20 passed

Fixes DEMOS-1P

🤖 Generated with Claude Code

---

Note

^{Cursor Bugbot is generating a summary for commit 1740e9c. 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 a70c4c3. Configure here.}