@dimina-kit/compiler 0.0.1-dev.20260702173719 → 0.0.1-dev.20260702182435

package/README.md

@@ -71,10 +71,12 @@ const { appId, name, files } = await pool.compile({ files: source, workPath: '/p
 pool.dispose()                                       // 用完终止 worker
 ```
 
-> **上面是最小接入代码,但浏览器环境有前置要求**(不满足会在别处报错,不像示例不完整):页面与 worker 开 COOP/COEP;`toolchainSetupURL` 能被 worker 运行时 import;esbuild browser ESM 与 `esbuild.wasm` 可作静态资源访问;npm 用户需显式装 `@oxc-parser/binding-wasm32-wasi`(`cpu:wasm32` 会被跳过);本包经 `file:`/link 引用时要配 Vite `server.fs.allow`。逐条见文末「故障排查」。
+> **上面是最小接入代码,但浏览器环境有前置要求**(不满足会在别处报错,不像示例不完整):页面与 worker 开 COOP/COEP;`toolchainSetupURL` 能被 worker 运行时 import;esbuild browser ESM 与 `esbuild.wasm` 可作静态资源访问;npm 用户需显式装 `@oxc-parser/binding-wasm32-wasi`(`cpu:wasm32` 会被跳过);本包经 `file:`/link 引用时要配 Vite `server.fs.allow`。逐条见本节末尾的「故障排查」。
 
 `compile()` 内部：三个常驻 worker **各跑一个完整 stage**（logic / view / style），各自 seed 私有 memfs、各自 `setupCompile` + 编译该 stage，产物取并集回传；跨 `compile()` 复用同一批 worker（每次编译前自动 `resetCompilerState`）。多个 `compile()` 会自动串行（共享常驻 realm 不能并发）。
 
+> **连续触发（watch / 保存即编）要自己收敛：** pool 只保证串行，**不合并**——编译进行中再调 N 次 `compile()` 就排队 N 个全量编译，一个不少地跑完（正确性没问题，但白烧算力、垫高最后一次的延迟）。源码快照在**轮到该次编译派发时**才结构化克隆，不是调用时。触发侧应收敛成"至多一个在跑 + 一个待跑"（dirty-flag / debounce）。另外**整个应用共用一个 pool 单例**：多实例之间 realm 全隔离、不会互相污染，但结果没有跨实例顺序保证（旧编译可能晚于新编译返回，按到达顺序应用产物会拿旧盖新），还多付一份工具链常驻内存。
+
 ```ts
 createCompilerPool(options: {
   createWorker: () => Worker      // 必填:起 stage worker 的工厂;pool 按 stage 数(默认 3)调用它多次
@@ -121,12 +123,30 @@ await installEsbuildFromURL('/esbuild-browser.mjs', '/esbuild.wasm')   // 见下
 - **`installOxc(oxcModule)`**：把 `await import('oxc-parser')`（你的 bundler 才能解析它 + 取它的 wasm）装成 `__oxcParseSync`。
 - **`installEsbuildFromURL(moduleURL, wasmURL)`**：从**静态资源 URL** 加载 esbuild-wasm 浏览器 ESM 并 `initialize`，装成 `__esbuildTransform`。
 
+> **不是每个 worker 都会加载它：** style stage 的编译链路不调用这两个 wasm 钩子（CSS 工具链已内联，见下），所以 **style worker 在 warmup/compile 时会直接跳过 `import(toolchainSetupURL)`**——省掉一份 esbuild.wasm（~13MB）+ oxc 的加载与常驻内存。因此 **setup 模块只应安装这两个钩子**，不要在里面夹带编译所依赖的其他全局（style worker 看不到它们）；未知的自定义 stage 会保守照旧加载。
+>
 > **为什么是 URL 而不是 `import`：** esbuild-wasm 的浏览器构建通常只能当**静态资源**托管（把它的 Go 运行时打包会坏），而 bundler（Vite/Webpack/Rollup）**不允许** `import()` 一个静态资源目录里的 JS——`installEsbuildFromURL` 内部用 `fetch + Blob URL` 绕过 bundler 的模块图,替你把这个坑填了。若你的 esbuild-wasm 是 npm 依赖（bundler 能解析），也可以自己 `import * as esbuild from 'esbuild-wasm'` + `esbuild.initialize({ wasmURL })` + 设 `globalThis.__esbuildTransform`,不必用这个助手。
 >
-> **cross-origin isolation：** oxc 的 wasm32-wasi 绑定用到 SharedArrayBuffer，页面与 worker 需开 COOP/COEP（`Cross-Origin-Opener-Policy: same-origin` + `Cross-Origin-Embedder-Policy: require-corp`）。**CSS 工具链不用宿主管**：浏览器 bundle 已内联真实 `cssnano` + `autoprefixer`（autoprefixer pin 到 node 版 `compile-core.node.js` 运行时解析的同一份，当前 10.5.0），CSS 产物与 node 版逐字节一致。宿主只需提供 esbuild + oxc 两个 wasm 钩子。
+> **cross-origin isolation：** oxc 的 wasm32-wasi 绑定用到 SharedArrayBuffer，页面与 worker 需开 COOP/COEP（`Cross-Origin-Opener-Policy: same-origin` + `Cross-Origin-Embedder-Policy: require-corp`）。**CSS 工具链不用宿主管**：浏览器 bundle 已内联真实 `cssnano` + `autoprefixer`（autoprefixer pin 到 node 版 `compile-core.node.js` 运行时解析的同一份，当前 10.5.2），CSS 产物与 node 版逐字节一致。宿主只需提供 esbuild + oxc 两个 wasm 钩子。
 
 参考实现与验证：`dimina-web-client` 的 `demo/toolchain-setup.js`（用上面两个助手）+ `demo/pool-test.html`，`npm run test:pool`（三项目产物与单线程逐结构一致，并演示 `onLog`）。
 
+### 故障排查（接入环境）
+
+pool 的 API 本身很小，但**浏览器/bundler/包管理器环境**有几个已知坑，报错往往指向别处、很难一眼看出是环境问题。按现象对号入座：
+
+- **worker 请求 403 `outside of Vite serving allow list`（本包通过 `file:` / `pnpm link` / monorepo workspace 引用时）。** `new Worker(new URL('@dimina-kit/compiler/stage-worker', import.meta.url))` 是**运行时懒解析**,不走 Vite 依赖爬虫的预热白名单,而本包真实目录在你项目 root 之外 → 被 `server.fs.allow` 拦。把本包的**真实目录**（symlink resolve 后的 realpath,不是 node_modules 里的软链）加进 `server.fs.allow`：
+  ```js
+  // vite.config.js
+  import fs from 'node:fs'; import path from 'node:path'
+  const wcDir = fs.realpathSync(path.dirname(new URL('./node_modules/@dimina-kit/compiler/package.json', import.meta.url).pathname))
+  export default defineConfig({ server: { fs: { allow: ['.', wcDir] } }, /* … */ })
+  ```
+  （静态 `import` 的 `pool` 能穿透是因为它被爬虫预热了——这个不对称很反直觉。）
+- **`Failed to resolve import "@oxc-parser/binding-wasm32-wasi"`（用 npm、非 pnpm 时）。** `oxc-parser` 的 wasm binding 的 `package.json` 写了 `"cpu": "wasm32"`,**npm 会把它当成和 arm64/x64 互斥的真实架构而跳过安装**（optionalDependencies 平台过滤）。把它**显式**列进你自己的 `dependencies`（别指望 optional 自动装）：`npm i @oxc-parser/binding-wasm32-wasi`。pnpm 一般不会踩这个。
+- **`toolchainSetupURL` 这个文件放哪。** 它被 worker 在运行时 `import(url)`。放 `public/`（静态资源、URL 稳定）最省心,dev/prod 都成立;若放 `src/` 用 bundler 处理,dev 能过但 `vite build` 需要把它声明为独立 entry（`build.rollupOptions.input`），否则生产构建不产出这个文件。
+- **dev 模式下 3 条 `[vite] connecting…` 噪音**：3 个 stage worker 各建一条 HMR 连接,属正常,不是 worker 池重复初始化。
+
 ## Node 常驻 pool（`./pool-node`，devtools 在用）
 
 Node 宿主（Electron devtools、CLI watch 服务等）用这个导出替代直接依赖 dmcc（`@dimina/compiler`）。它复刻 dmcc 的磁盘编译流程——主线程准备（配置/产物目录/npm 包）→ 3 个 stage worker 并发写共享 staging → 发布到 `outputDir/{appId}`——**产物与 dmcc 逐字节等价**（含 sourcemap 与自定义 `fileTypes`），区别只有一个：**worker 常驻**。
@@ -301,22 +321,6 @@ async function filesFromDir(dir, prefix = '') {           // 只读递来的 han
 - **`targetPath` 来自环境。** compiler 产物目录取 `process.env.TARGET_PATH`，否则 `os.tmpdir()/dimina-fe-dist-<时间戳>`（浏览器 os shim 下通常 `/tmp/...`）。`setupCompile` 会先 `rmSync` 清空它——别把 `TARGET_PATH` 指到源码目录或共享目录。用 `setupCompile` 返回的 `targetPath` 喂 `collectOutputs`。
 - **不是全 fail-fast。** 缺 fs 方法、坏 appid、坏 `project.config.json`、miniprogram_npm 构建失败会 **reject**；但**样式预处理器失败（如当前浏览器构建暂不支持 `.less`）会被吞掉、降级用原始 CSS**，PostCSS 解析失败返回空串，资源拷贝失败只 `console.log`，logic esbuild 压缩失败回退未压缩代码。**用 pool 时把这些拿出来的办法是 `createCompilerPool({ onLog })`**——它把 worker 内编译器的 `console.*` 诊断（带 stage 标签）转发给你；也可在产物为空/缺失时二次校验。
 
-## 故障排查（接入环境）
-
-pool 的 API 本身很小，但**浏览器/bundler/包管理器环境**有几个已知坑，报错往往指向别处、很难一眼看出是环境问题。按现象对号入座：
-
-- **worker 请求 403 `outside of Vite serving allow list`（本包通过 `file:` / `pnpm link` / monorepo workspace 引用时）。** `new Worker(new URL('@dimina-kit/compiler/stage-worker', import.meta.url))` 是**运行时懒解析**,不走 Vite 依赖爬虫的预热白名单,而本包真实目录在你项目 root 之外 → 被 `server.fs.allow` 拦。把本包的**真实目录**（symlink resolve 后的 realpath,不是 node_modules 里的软链）加进 `server.fs.allow`：
-  ```js
-  // vite.config.js
-  import fs from 'node:fs'; import path from 'node:path'
-  const wcDir = fs.realpathSync(path.dirname(new URL('./node_modules/@dimina-kit/compiler/package.json', import.meta.url).pathname))
-  export default defineConfig({ server: { fs: { allow: ['.', wcDir] } }, /* … */ })
-  ```
-  （静态 `import` 的 `pool` 能穿透是因为它被爬虫预热了——这个不对称很反直觉。）
-- **`Failed to resolve import "@oxc-parser/binding-wasm32-wasi"`（用 npm、非 pnpm 时）。** `oxc-parser` 的 wasm binding 的 `package.json` 写了 `"cpu": "wasm32"`,**npm 会把它当成和 arm64/x64 互斥的真实架构而跳过安装**（optionalDependencies 平台过滤）。把它**显式**列进你自己的 `dependencies`（别指望 optional 自动装）：`npm i @oxc-parser/binding-wasm32-wasi`。pnpm 一般不会踩这个。
-- **`toolchainSetupURL` 这个文件放哪。** 它被 worker 在运行时 `import(url)`。放 `public/`（静态资源、URL 稳定）最省心,dev/prod 都成立;若放 `src/` 用 bundler 处理,dev 能过但 `vite build` 需要把它声明为独立 entry（`build.rollupOptions.input`），否则生产构建不产出这个文件。
-- **dev 模式下 3 条 `[vite] connecting…` 噪音**：3 个 stage worker 各建一条 HMR 连接,属正常,不是 worker 池重复初始化。
-
 ## 依赖前置
 
 编译器实体源码在 `dimina` 子模块里，dart-sass 等在其 fe workspace。构建前确保子模块已初始化、依赖已装：

package/dist/pool.browser.js

@@ -49,7 +49,7 @@ function createCompilerPool(options = {}) {
   let warmed = null;
   async function warmup() {
     if (!warmed) {
-      warmed = Promise.all(workers.map((x) => x.send({ type: "warmup", toolchainSetupURL }))).then((rs) => rs.forEach((r, i) => {
+      warmed = Promise.all(workers.map((x) => x.send({ type: "warmup", toolchainSetupURL, stages: [x.stage] }))).then((rs) => rs.forEach((r, i) => {
         if (r && r.type === "error") throw new Error(r.error || `[compiler] stage '${workers[i].stage}' warmup failed`);
       })).catch((err) => {
         warmed = null;

package/dist/stage-worker.browser.js

@@ -290964,6 +290964,11 @@ function ensureToolchain(url) {
   }
   return toolchainReady;
 }
+var TOOLCHAIN_FREE_STAGES = /* @__PURE__ */ new Set(["style"]);
+function needsToolchain(stages) {
+  if (!Array.isArray(stages) || stages.length === 0) return true;
+  return stages.some((s) => !TOOLCHAIN_FREE_STAGES.has(s));
+}
 function freshFs(files, workPath) {
   return (0, import_memfs.createFsFromVolume)(import_memfs.Volume.fromJSON(files, workPath));
 }
@@ -290984,13 +290989,15 @@ self.onmessage = async (e) => {
   try {
     if (type === "warmup") {
       const t0 = performance.now();
-      await ensureToolchain(e.data.toolchainSetupURL);
+      if (e.data.toolchainSetupURL) toolchainURL = e.data.toolchainSetupURL;
+      if (needsToolchain(e.data.stages)) await ensureToolchain();
       self.postMessage({ type: "ready", ms: Math.round(performance.now() - t0) });
       return;
     }
     if (type === "compile-subset") {
       const { files, workPath = "/work", stages = ["logic", "view", "style"], toolchainSetupURL } = e.data;
-      await ensureToolchain(toolchainSetupURL);
+      if (toolchainSetupURL) toolchainURL = toolchainSetupURL;
+      if (needsToolchain(stages)) await ensureToolchain();
       const warm = !!toolchainReady;
       const t = performance.now();
       const result2 = await compileSubset(files, workPath, stages);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dimina-kit/compiler",
-  "version": "0.0.1-dev.20260702173719",
+  "version": "0.0.1-dev.20260702182435",
   "description": "dmcc compiler bundles (browser + node) that drive @dimina/compiler against a caller-injected node:fs replacement (no bundled fs)",
   "license": "MIT",
   "type": "module",
@@ -82,6 +82,7 @@
     "test:realm-reuse": "node scripts/build-compiler.js node && node --import ./scripts/register-kit.js scripts/test-realm-reuse.js",
     "test:pool-node": "node scripts/build-compiler.js node && node --import ./scripts/register-kit.js scripts/test-pool-node.js",
     "test:pool-hardening": "node scripts/build-compiler.js node && node scripts/test-pool-hardening.js",
-    "test:npm-scan": "node scripts/build-compiler.js node && node --import ./scripts/register-kit.js scripts/test-npm-scan.js"
+    "test:npm-scan": "node scripts/build-compiler.js node && node --import ./scripts/register-kit.js scripts/test-npm-scan.js",
+    "test:stage-toolchain": "node scripts/build-compiler.js browser && node scripts/test-stage-toolchain.js"
   }
 }

package/scripts/test-stage-toolchain.js

@@ -0,0 +1,263 @@
+// Per-stage toolchain skip: dist/stage-worker.browser.js currently `import()`s the
+// host's wasm toolchainSetupURL (esbuild-wasm + oxc) on EVERY warmup and
+// compile-subset call, regardless of which stage the worker actually runs. The
+// style stage's compile path (postcss/cssnano/autoprefixer) is bundled in and never
+// touches `__esbuildTransform`/`__oxcParseSync`, so a style-only worker paying that
+// import cost is pure waste — and, observably, it means a style worker can't warm up
+// at all if the host's toolchainSetupURL is broken/unreachable, even though style
+// never needed it.
+//
+// This drives the raw worker message protocol directly (no bundler / real Worker):
+// dist/stage-worker.browser.js is a self-contained ESM (browser platform, memfs +
+// browser shims inlined), so it can be `import()`ed straight into Node once a fake
+// `self` (postMessage/onmessage) is installed on globalThis and the REAL Node
+// `process` global is masked during the import — dart-sass's bundled browser shim
+// checks `process.versions.node` at module-eval time and takes a `require()` path
+// that esbuild's browser platform build cannot satisfy (`Dynamic require of "url"
+// is not supported`) when it sees the real Node process object.
+//
+// Each `import(url + '?n=' + n)` with a distinct query string forces Node to load a
+// FRESH module instance (own `toolchainReady` cache, own `self.onmessage` closure),
+// which is how independent worker instances are simulated here. The worker's console
+// patch forwards console.* to `self.postMessage({ type: 'log' })` after the first
+// import — this test never calls console.* through a live `self`, only through a
+// `rawLog` reference captured before any import.
+import { createRequire } from 'node:module'
+
+const require = createRequire(import.meta.url)
+const realProcessExit = process.exit.bind(process)
+const rawLog = console.log.bind(console)
+
+// dart-sass's node-vs-browser branch (see stage-worker.browser.js bundle) reads
+// `process.versions.node` once at module-eval time. Masking the global with a
+// browser-shaped process (no `versions`) BEFORE any worker import makes the bundle
+// take the same path it would in a real browser. `realProcessExit` above keeps a
+// working exit for this script's own end regardless of this override.
+globalThis.process = { env: {}, cwd: () => '/' }
+
+const WORKER_URL = new URL('../dist/stage-worker.browser.js', import.meta.url).href
+const POOL_MODULE = require.resolve('../dist/pool.browser.js')
+
+let failed = 0
+function chk(cond, msg) {
+  if (cond) rawLog(`✅ ${msg}`)
+  else { rawLog(`❌ ${msg}`); failed++ }
+}
+
+// A toolchainSetupURL that always fails to import — stands in for both "points at
+// a URL that doesn't exist" and "points at a module whose import throws" (memfs/oxc
+// setup modules do the latter in practice; the failure shape ensureToolchain()
+// surfaces is identical either way).
+const UNREACHABLE_TOOLCHAIN_URL = 'file:///no/such/path/toolchain-setup-nonexistent.mjs'
+
+// A distinct `data:` URL per marker name is a distinct module specifier, so Node
+// gives each a fresh module record — importing it increments a globalThis counter
+// exactly once per actual `import()` call. Reusing the SAME marker name across two
+// sends would hit Node's module cache on the second import and silently read as
+// "imported once" even if the code path runs twice, so every assertion below uses
+// its own marker name.
+const sideEffectURL = (markerName) => `data:text/javascript,globalThis.${markerName}=(globalThis.${markerName}||0)%2B1`
+
+// --- fake `self` (Worker global scope) + message round-trip -------------------
+function makeFakeSelf() {
+  const inbox = []
+  let waiter = null
+  const fakeSelf = {
+    onmessage: null,
+    postMessage(msg) {
+      inbox.push(msg)
+      if (waiter) { const w = waiter; waiter = null; w() }
+    },
+  }
+  // Diagnostics arrive out-of-band as { type:'log' } (see stage-worker.js's console
+  // forwarding) interleaved with the real reply — skip them, same as pool.js does.
+  fakeSelf.waitForReply = () => new Promise((resolve) => {
+    function tryDrain() {
+      while (inbox.length) {
+        const m = inbox.shift()
+        if (m && m.type === 'log') continue
+        resolve(m)
+        return
+      }
+      waiter = tryDrain
+    }
+    tryDrain()
+  })
+  return fakeSelf
+}
+
+let instanceCounter = 0
+async function loadWorkerInstance() {
+  const fakeSelf = makeFakeSelf()
+  globalThis.self = fakeSelf
+  instanceCounter += 1
+  await import(`${WORKER_URL}?n=${instanceCounter}`)
+  return {
+    // Sends are driven strictly sequentially (never two in-flight sends across
+    // different instances) — the worker module resolves the bare `self` identifier
+    // against whatever `globalThis.self` is AT CALL TIME, not at import time, so an
+    // in-flight send from a different instance would misdirect this one's reply.
+    async send(msg) {
+      globalThis.self = fakeSelf
+      const reply = fakeSelf.waitForReply()
+      fakeSelf.onmessage({ data: msg })
+      return reply
+    },
+  }
+}
+
+const FIXTURE_FILES = {
+  'app.json': JSON.stringify({ pages: ['pages/index/index'] }),
+  'app.js': 'App({})',
+  'pages/index/index.js': 'Page({})',
+  'pages/index/index.wxml': '<view>hi</view>',
+  'pages/index/index.wxss': '.x{color:red}',
+  'pages/index/index.json': '{}',
+}
+const WORK_PATH = '/work'
+
+function findCompiledCss(files) {
+  return Object.entries(files || {}).find(([k, v]) => k.endsWith('.css') && typeof v === 'string' && v.includes('color:red'))
+}
+
+// --- A + B: style-only worker never needs the wasm toolchain ------------------
+{
+  const styleWorker = await loadWorkerInstance()
+  const warmupReply = await styleWorker.send({
+    type: 'warmup',
+    toolchainSetupURL: UNREACHABLE_TOOLCHAIN_URL,
+    stages: ['style'],
+  })
+  chk(warmupReply && warmupReply.type === 'ready',
+    `style-only worker warmup succeeds with an unreachable toolchainSetupURL (skips the wasm import) — got ${JSON.stringify(warmupReply)}`)
+}
+{
+  // Fresh instance, no prior warmup at all — isolates compile-subset's OWN skip
+  // decision from warmup's memoized toolchainReady state.
+  const styleWorker = await loadWorkerInstance()
+  const compileReply = await styleWorker.send({
+    type: 'compile-subset',
+    files: FIXTURE_FILES,
+    workPath: WORK_PATH,
+    stages: ['style'],
+    toolchainSetupURL: UNREACHABLE_TOOLCHAIN_URL,
+  })
+  chk(compileReply && compileReply.type === 'done',
+    `style-only compile-subset succeeds with an unreachable toolchainSetupURL — got ${JSON.stringify(compileReply && compileReply.type === 'error' ? compileReply.error : compileReply)}`)
+  const css = compileReply && compileReply.type === 'done' ? findCompiledCss(compileReply.result.files) : null
+  chk(!!css, `style-only compile-subset produced a real compiled CSS product (found "${css && css[0]}": ${css && JSON.stringify(css[1])})`)
+}
+
+// --- C: logic / view stage worker behavior is unchanged — still imports the
+// toolchain exactly once per warmup ---------------------------------------------
+for (const stage of ['logic', 'view']) {
+  const marker = `__stageToolchainMark_${stage}`
+  const worker = await loadWorkerInstance()
+  const reply = await worker.send({
+    type: 'warmup',
+    toolchainSetupURL: sideEffectURL(marker),
+    stages: [stage],
+  })
+  chk(reply && reply.type === 'ready', `${stage} worker warmup succeeds`)
+  chk(globalThis[marker] === 1, `${stage} worker warmup imports toolchainSetupURL exactly once (count=${globalThis[marker]})`)
+}
+
+// --- D: an unrecognized custom stage name loads the toolchain conservatively ---
+{
+  const marker = '__stageToolchainMark_custom'
+  const worker = await loadWorkerInstance()
+  const reply = await worker.send({
+    type: 'warmup',
+    toolchainSetupURL: sideEffectURL(marker),
+    stages: ['my-custom-stage'],
+  })
+  chk(reply && reply.type === 'ready', 'unknown custom stage worker warmup succeeds')
+  chk(globalThis[marker] === 1, `unknown custom stage "my-custom-stage" still imports toolchainSetupURL (conservative default; count=${globalThis[marker]})`)
+}
+
+// --- E: warmup with no `stages` field at all (pre-optimization callers) stays
+// conservative too ---------------------------------------------------------------
+{
+  const marker = '__stageToolchainMark_legacy'
+  const worker = await loadWorkerInstance()
+  const reply = await worker.send({
+    type: 'warmup',
+    toolchainSetupURL: sideEffectURL(marker),
+    // no `stages` field — the pre-optimization warmup message shape
+  })
+  chk(reply && reply.type === 'ready', 'legacy warmup (no stages field) succeeds')
+  chk(globalThis[marker] === 1, `legacy warmup without a stages field still imports toolchainSetupURL (count=${globalThis[marker]})`)
+}
+
+// --- G: a worker that skipped the import at warmup must still REMEMBER the
+// warmup URL — a later compile-subset that needs the toolchain (logic stage) and
+// carries no toolchainSetupURL of its own must import the remembered URL instead
+// of failing "no toolchainSetupURL / not warmed up" ------------------------------
+{
+  const marker = '__stageToolchainMark_deferred'
+  // Besides counting the import, install stand-in toolchain hooks so the logic
+  // compile has SOMETHING to call if it gets that far. The compile outcome itself
+  // is not the guarded contract (stand-in hooks may not satisfy the full logic
+  // pipeline) — what must hold is that the remembered URL gets imported and the
+  // failure mode is NOT the "no toolchainSetupURL" warmup error.
+  const setupURL = 'data:text/javascript,' + encodeURIComponent(
+    `globalThis.${marker}=(globalThis.${marker}||0)+1;`
+    + 'globalThis.__esbuildTransform=async(code)=>({code});'
+    + 'globalThis.__oxcParseSync=()=>{throw new Error("stand-in oxc hook")};',
+  )
+  const worker = await loadWorkerInstance()
+  const warmupReply = await worker.send({
+    type: 'warmup',
+    toolchainSetupURL: setupURL,
+    stages: ['style'],
+  })
+  chk(warmupReply && warmupReply.type === 'ready', 'style-declared worker warmup succeeds with a working setup module')
+  chk((globalThis[marker] || 0) === 0,
+    `style-declared warmup defers the setup-module import (count=${globalThis[marker] || 0})`)
+  const compileReply = await worker.send({
+    type: 'compile-subset',
+    files: FIXTURE_FILES,
+    workPath: WORK_PATH,
+    stages: ['logic'],
+    // no toolchainSetupURL — the worker must fall back to the URL remembered at warmup
+  })
+  chk(globalThis[marker] === 1,
+    `logic compile-subset without its own toolchainSetupURL imports the URL remembered at warmup (count=${globalThis[marker]})`)
+  chk(!!compileReply && !(compileReply.type === 'error' && /no toolchainSetupURL|not warmed up/.test(String(compileReply.error))),
+    `logic compile-subset after a deferred warmup does not fail as un-warmed — got ${JSON.stringify(compileReply && (compileReply.type === 'error' ? String(compileReply.error).slice(0, 100) : compileReply.type))}`)
+}
+
+// --- F: createCompilerPool tells each resident worker its own stage identity ---
+{
+  const { createCompilerPool } = await import(POOL_MODULE)
+  const createdWorkers = []
+  function createWorker() {
+    const messages = []
+    const w = {
+      onmessage: null,
+      postMessage(m) {
+        messages.push(m)
+        // Reply asynchronously, like a real Worker would, so pool.warmup()'s
+        // send()/Promise pairing is exercised the same way it is in production.
+        queueMicrotask(() => { if (w.onmessage) w.onmessage({ data: { type: 'ready' } }) })
+      },
+      terminate() {},
+    }
+    createdWorkers.push(messages)
+    return w
+  }
+
+  const stages = ['logic', 'view', 'style']
+  const pool = createCompilerPool({ createWorker, toolchainSetupURL: 'data:text/javascript,export default {}', stages })
+  await pool.warmup()
+
+  for (let i = 0; i < stages.length; i++) {
+    const firstMessage = createdWorkers[i] && createdWorkers[i][0]
+    chk(firstMessage && firstMessage.type === 'warmup', `pool sent a warmup message to the "${stages[i]}" worker`)
+    chk(!!firstMessage && Array.isArray(firstMessage.stages) && firstMessage.stages.length === 1 && firstMessage.stages[0] === stages[i],
+      `pool's warmup message to the "${stages[i]}" worker carries its own stage identity (stages:${JSON.stringify(firstMessage && firstMessage.stages)})`)
+  }
+}
+
+rawLog(failed ? `\n❌ ${failed} stage-toolchain assertion(s) failed.` : '\n✅ style stage skips the wasm toolchain; logic/view/custom/legacy stay conservative; pool announces worker stage identity.')
+realProcessExit(failed ? 1 : 0)

package/src/pool.js

@@ -67,7 +67,9 @@ export function createCompilerPool(options = {}) {
   let warmed = null
   async function warmup() {
     if (!warmed) {
-      warmed = Promise.all(workers.map((x) => x.send({ type: 'warmup', toolchainSetupURL })))
+      // stages tells the worker its stage identity so toolchain-free stages (style)
+      // can skip importing toolchainSetupURL at warmup.
+      warmed = Promise.all(workers.map((x) => x.send({ type: 'warmup', toolchainSetupURL, stages: [x.stage] })))
         .then((rs) => rs.forEach((r, i) => {
           // The worker's own try/catch reports the REAL cause (e.g. a toolchainSetupURL
           // import failure) as r.error — surface it verbatim, tagged with the stage.

package/src/stage-worker.js

@@ -43,6 +43,17 @@ function ensureToolchain(url) {
   return toolchainReady
 }
 
+// Stages whose compile path never calls the wasm hooks (__esbuildTransform /
+// __oxcParseSync). The CSS pipeline (postcss + cssnano + autoprefixer) is inlined
+// in this bundle, so a style-only worker skips importing toolchainSetupURL entirely
+// (~13MB esbuild.wasm + oxc WASI it would never call). Unknown/custom stages and
+// messages without stage identity conservatively load the toolchain.
+const TOOLCHAIN_FREE_STAGES = new Set(['style'])
+function needsToolchain(stages) {
+  if (!Array.isArray(stages) || stages.length === 0) return true
+  return stages.some((s) => !TOOLCHAIN_FREE_STAGES.has(s))
+}
+
 function freshFs(files, workPath) {
   return createFsFromVolume(Volume.fromJSON(files, workPath))
 }
@@ -69,13 +80,18 @@ self.onmessage = async (e) => {
   try {
     if (type === 'warmup') {
       const t0 = performance.now()
-      await ensureToolchain(e.data.toolchainSetupURL)
+      // Remember the URL even when this worker's stages skip the load, so a later
+      // compile-subset that DOES need the toolchain (protocol allows any stages)
+      // can still resolve it without re-sending the URL.
+      if (e.data.toolchainSetupURL) toolchainURL = e.data.toolchainSetupURL
+      if (needsToolchain(e.data.stages)) await ensureToolchain()
       self.postMessage({ type: 'ready', ms: Math.round(performance.now() - t0) })
       return
     }
     if (type === 'compile-subset') {
       const { files, workPath = '/work', stages = ['logic', 'view', 'style'], toolchainSetupURL } = e.data
-      await ensureToolchain(toolchainSetupURL)
+      if (toolchainSetupURL) toolchainURL = toolchainSetupURL
+      if (needsToolchain(stages)) await ensureToolchain()
       const warm = !!toolchainReady
       const t = performance.now()
       const result = await compileSubset(files, workPath, stages)