@dimina-kit/compiler 0.0.1 → 0.0.2-dev.20260711062001

package/dist/stage-worker.node.js

@@ -3,12 +3,12 @@ import {
   preloadStage,
   resetCompilerState,
   runStage
-} from "./pool.node-chunks/chunk-MHOA4NGC.js";
+} from "./pool.node-chunks/chunk-PDHO4Y56.js";
 import {
   getAppId,
   getAppName,
   resetStoreInfo
-} from "./pool.node-chunks/chunk-UYQ7D5I5.js";
+} from "./pool.node-chunks/chunk-7FGOYOXU.js";
 
 // src/stage-worker-node.js
 import { createRequire } from "node:module";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dimina-kit/compiler",
-  "version": "0.0.1",
+  "version": "0.0.2-dev.20260711062001",
   "description": "dmcc compiler bundles (browser + node) that drive @dimina/compiler against a caller-injected node:fs replacement (no bundled fs)",
   "license": "MIT",
   "type": "module",
@@ -83,6 +83,7 @@
     "test:pool-node": "node scripts/build-compiler.js node && node --import ./scripts/register-kit.js scripts/test-pool-node.js",
     "test:pool-scopehash": "node scripts/build-compiler.js node && node --import ./scripts/register-kit.js scripts/test-pool-scopehash.js",
     "test:pool-hardening": "node scripts/build-compiler.js node && node scripts/test-pool-hardening.js",
+    "test:pool-toolchain-death": "node scripts/build-compiler.js node && node scripts/test-pool-toolchain-death.js",
     "test:pool-worker-hardening": "node scripts/test-pool-worker-hardening.js",
     "test:worker-slot": "node scripts/test-worker-slot.js",
     "test:pool-watchdog": "node scripts/test-pool-watchdog.js",
@@ -92,6 +93,7 @@
     "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",
     "test:stage-worker-message-order": "node scripts/build-compiler.js node && node scripts/test-stage-worker-message-order.js",
-    "test:stage-load-retry": "node scripts/build-compiler.js node && node scripts/test-stage-load-retry.js"
+    "test:stage-load-retry": "node scripts/build-compiler.js node && node scripts/test-stage-load-retry.js",
+    "test:pool-filetypes": "node scripts/build-compiler.js node && node scripts/build-compiler.js browser && node scripts/test-pool-filetypes.js"
   }
 }

package/scripts/test-pool-filetypes.js

@@ -0,0 +1,159 @@
+// Red/green coverage for `options.fileTypes` (custom template/style/view-script
+// dialect, e.g. .qdml/.qdss/.qds) reaching the browser pool's compile protocol.
+//
+// dmcc's env.js already normalizes options.fileTypes into a `compilerOptions`
+// bundle inside storeInfo (dimina/fe/packages/compiler/src/env.js:91-120), and
+// that bundle rides inside bundle.storeInfo through the setup->compile-subset
+// broadcast (compile-core.js's compileStage -> resetStoreInfo, env.js:122-132) —
+// see src/pool.js's runAttempt and src/stage-worker.js's runSetup/compileSubset.
+// This test drives the REAL browser bundles (dist/pool.browser.js +
+// dist/stage-worker.browser.js) in Node, so it fails (red) without the
+// options-threading fix and passes (green) with it — no reimplementation of the
+// protocol handlers under test.
+//
+// Fixture mirrors qdmp's e2e "qd-app" (see
+// ~/code/qdmp/main/packages/qdmp-devtools/e2e/qd-app): a page using .qdml/.qdss/.qds
+// instead of .wxml/.wxss/.wxs, with a <wxs src="./index.qds" module="m" /> view
+// script and a `{{ m.shout(title) }}` mustache expression — so a correct compile
+// must recognize the custom template AND the custom view-script extension.
+//
+// Also covers compile-core.js's compileMiniApp (the one-shot worker entry point)
+// at the bottom, since it shares the exact same options-threading gap.
+
+// Warm real esbuild/oxc-parser module eval AND esbuild's long-lived service child
+// process with the REAL process object BEFORE masking (below) — the service, once
+// spawned, is reused for later transforms even under a masked process, so this
+// must run first.
+import { transform } from 'esbuild'
+import 'oxc-parser'
+
+await transform('const __warm = 1', {})
+
+// dart-sass's bundled browser shim checks process.versions.node at module-eval
+// time (only reached once the lazily-loaded style-compiler chunk imports it) —
+// masking to a browser-shaped stub makes it take the browser branch instead of
+// crashing on `Dynamic require of "url" is not supported` (see
+// scripts/test-stage-toolchain.js for the same technique). Saved so PART B below
+// (a Node-target bundle, which needs the real process — its transitive deps
+// module-eval-check process.versions.node too) can restore it.
+const realProcess = globalThis.process
+globalThis.process = { env: {}, cwd: () => '/' }
+
+const WORKER_URL = new URL('../dist/stage-worker.browser.js', import.meta.url).href
+const TOOLCHAIN_URL = new URL('./toolchain-setup-node-native.js', import.meta.url).href
+const WORK_PATH = '/work'
+
+const FIXTURE_FILES = {
+  'app.json': JSON.stringify({ pages: ['pages/index/index'], window: { navigationBarTitleText: 'QD Ext Demo' } }),
+  'project.config.json': JSON.stringify({ appid: 'qd_ext_demo_001', projectname: 'qd-ext-demo' }),
+  'app.js': "App({\n  onLaunch() {\n    console.log('[QDExt] App launched')\n  },\n})\n",
+  'pages/index/index.js': "Page({\n  data: {\n    title: 'QD Extensions',\n    count: 3,\n  },\n})\n",
+  'pages/index/index.qdss': '.qd-box {\n  padding: 20rpx;\n}\n\n.qd-title {\n  font-size: 36rpx;\n  color: #4A90D9;\n}\n\n.qd-item {\n  font-size: 28rpx;\n  color: #333;\n}\n',
+  'pages/index/index.qdml': '<wxs src="./index.qds" module="m" />\n<view class="qd-box">\n  <view class="qd-title" id="qd-title">{{ m.shout(title) }}</view>\n  <view class="qd-item" wx:for="{{count}}" wx:key="*this">item-{{item}}</view>\n</view>\n',
+  'pages/index/index.json': JSON.stringify({ navigationBarTitleText: 'QD Ext Index' }),
+  'pages/index/index.qds': "function shout(text) {\n  return text + '!'\n}\n\nmodule.exports = {\n  shout: shout,\n}\n",
+}
+const FILE_TYPES_OPTIONS = { fileTypes: { template: ['qdml'], style: ['qdss'], viewScript: ['qds'] } }
+
+let failed = false
+const chk = (cond, msg) => { if (!cond) { failed = true; console.error(`❌ ${msg}`) } else console.log(`✅ ${msg}`) }
+
+// Real page module: exists, non-empty, and carries the compiled .qds wxs module
+// (`shout`) plus the compiled .qdml view (`qd-title`) — the assertion this whole
+// test hinges on. Without options.fileTypes this is guaranteed to fail (the
+// custom extensions are unrecognized, so the page template/view-script are never
+// found), which is exactly the RED this test protects against regressing to.
+function pageModuleIsCompiled(files) {
+  const js = files && files['main/pages_index_index.js']
+  return typeof js === 'string' && js.length > 0 && js.includes('shout') && js.includes('qd-title')
+}
+
+// --- PART A: real browser pool (dist/pool.browser.js + dist/stage-worker.browser.js) ---
+//
+// Each stage worker is its own dynamically-imported module instance (own closure
+// state, mirroring a real Web Worker realm); ALL of them funnel through one shared
+// `chain` so only one is ever "in flight" at a time. This matters because the
+// worker module resolves the bare `self` identifier against whatever
+// `globalThis.self` currently is (see test-stage-toolchain.js's note on the same
+// mechanism) — serializing every send means no two realms' async continuations
+// can ever race over that shared global.
+let chain = Promise.resolve()
+let instanceCounter = 0
+async function makeStageWorker() {
+  const worker = { onmessage: null, onerror: null, terminate() {} }
+  const fakeSelf = {
+    onmessage: null,
+    postMessage(msg) { if (worker.onmessage) worker.onmessage({ data: msg }) },
+  }
+  globalThis.self = fakeSelf
+  instanceCounter += 1
+  await import(`${WORKER_URL}?n=${instanceCounter}`)
+  // stage-worker.js does `self.onmessage = async (e) => {...}` at module top level
+  // against whatever `globalThis.self` was AT IMPORT TIME — capture it now.
+  const boundOnMessage = fakeSelf.onmessage
+  worker.postMessage = (msg) => {
+    chain = chain.then(async () => {
+      globalThis.self = fakeSelf
+      try {
+        await boundOnMessage({ data: msg })
+      } catch (err) {
+        // The real handler already catches internally and posts { type:'error' };
+        // an escaping exception would mean it threw before its own try, so surface
+        // it the same way rather than hanging the pool's pending request forever.
+        fakeSelf.postMessage({ type: 'error', error: String((err && err.stack) || err) })
+      }
+    })
+  }
+  return worker
+}
+
+const { createCompilerPool } = await import('../dist/pool.browser.js')
+
+// One pool, pre-spawned with exactly the 3 default-stage workers this test needs
+// (no crash/respawn expected) — createWorker must be synchronous (pool.js calls it
+// inline), so every worker instance is built up front and handed out from a queue.
+const stageWorkers = []
+for (const stage of ['logic', 'view', 'style']) stageWorkers.push(await makeStageWorker())
+let nextWorker = 0
+const pool = createCompilerPool({
+  createWorker: () => stageWorkers[nextWorker++],
+  toolchainSetupURL: TOOLCHAIN_URL,
+})
+
+const withoutOptions = await pool.compile({ files: FIXTURE_FILES, workPath: WORK_PATH })
+chk(!pageModuleIsCompiled(withoutOptions.files),
+  'PART A (pool.js + stage-worker.js): WITHOUT options.fileTypes, the .qdml/.qdss/.qds page module is NOT compiled '
+  + `(demonstrates the gap this feature closes; got main/pages_index_index.js=${JSON.stringify(withoutOptions.files['main/pages_index_index.js'])})`)
+
+const withOptions = await pool.compile({ files: FIXTURE_FILES, workPath: WORK_PATH, options: FILE_TYPES_OPTIONS })
+chk(pageModuleIsCompiled(withOptions.files),
+  'PART A (pool.js + stage-worker.js): WITH options.fileTypes, the .qdml/.qdss/.qds page module IS compiled and non-empty '
+  + `(main/pages_index_index.js length=${(withOptions.files['main/pages_index_index.js'] || '').length})`)
+chk(withOptions.appId === 'qd_ext_demo_001', `PART A: compiled appId matches project.config.json (got ${withOptions.appId})`)
+const compiledCss = withOptions.files['main/pages_index_index.css'] || ''
+chk(compiledCss.includes('qd-title'), `PART A: .qdss style file compiled into page CSS (got ${JSON.stringify(compiledCss)})`)
+
+await pool.dispose()
+
+// --- PART B: compile-core.js's compileMiniApp (one-shot worker entry point) ---
+// Same options-threading gap, covered directly at the compile-core level (no
+// pool/worker-protocol involved) so a future pool refactor still has this pinned
+// independently of the browser-pool wiring above. This is the NODE-target bundle
+// (dist/compile-core.node.js), whose deps expect a real `process` — restore it
+// before importing.
+globalThis.process = realProcess
+const { compileMiniApp } = await import('../dist/compile-core.node.js')
+const { Volume, createFsFromVolume } = await import('memfs')
+const freshFs = () => createFsFromVolume(Volume.fromJSON(FIXTURE_FILES, WORK_PATH))
+
+const coreWithout = await compileMiniApp({ fs: freshFs(), workPath: WORK_PATH })
+chk(!pageModuleIsCompiled(coreWithout.files),
+  'PART B (compile-core.js compileMiniApp): WITHOUT options.fileTypes, page module NOT compiled')
+
+const coreWith = await compileMiniApp({ fs: freshFs(), workPath: WORK_PATH, options: FILE_TYPES_OPTIONS })
+chk(pageModuleIsCompiled(coreWith.files),
+  'PART B (compile-core.js compileMiniApp): WITH options.fileTypes, page module IS compiled and non-empty '
+  + `(length=${(coreWith.files['main/pages_index_index.js'] || '').length})`)
+
+console.log(failed ? '\n❌ FAIL' : '\n✅ PASS: options.fileTypes reaches the browser pool protocol (pool.js/stage-worker.js) and compile-core.js\'s compileMiniApp')
+process.exit(failed ? 1 : 0)

package/scripts/test-pool-node.js

@@ -8,7 +8,7 @@
 // and require our pool to match dmcc only where dmcc matches itself. Assets (uuid-named)
 // are matched by CONTENT hash multiset instead of name. Sourcemap is asserted against
 // dmcc's own map (parity), since that is the format devtools already consumes.
-import { readdirSync, readFileSync, statSync, rmSync, mkdirSync } from 'node:fs'
+import { readdirSync, readFileSync, statSync, rmSync, mkdirSync, writeFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { createHash } from 'node:crypto'
 import path from 'node:path'
@@ -42,7 +42,12 @@ function readTree(root) {
 }
 
 const dmccBuild = (await import('../../../dimina/fe/packages/compiler/src/index.js')).default
-const { createNodeCompilerPool } = await import('../dist/pool.node.js')
+const poolNodeModule = await import('../dist/pool.node.js')
+const { createNodeCompilerPool } = poolNodeModule
+// Destructured lazily below (may be absent pre-fix): the default drop-in build(),
+// the pure oxc-native-binding-hint mapper, and the lazy-singleton disposer.
+const defaultBuild = poolNodeModule.default
+const { oxcNativeBindingHint, disposeDefaultPool } = poolNodeModule
 
 // --- reference: dmcc twice ------------------------------------------------
 console.log(`[ref] dmcc build ×2 (sourcemap) from ${APP}`)
@@ -113,5 +118,90 @@ checkAgainstDmcc(readTree(path.join(dir('ours1'), appInfo1.appId)), 'cold')
 checkAgainstDmcc(readTree(path.join(dir('ours2'), appInfo2.appId)), 'warm')
 
 console.log(`[sourcemap] logic.js.map: ${refMap.sources.length} sources, sourcesContent present, matches dmcc ✅`)
-console.log(failed ? '\n❌ FAIL' : '\n✅ PASS: resident Node pool is dmcc-equivalent (incl. sourcemap) on cold+warm builds')
+
+// --- failure contract: the default drop-in build() must REJECT a broken compile ------------------
+// (never resolve undefined and let the caller mistake a failed compile for success), and the pool
+// must expose a pure helper that turns a missing-oxc-native-binding message into an actionable
+// packaging hint (checked as a string mapping only — a real environment can't be made to lack the
+// binding on demand).
+console.log("[fail] broken fixture: default build() must reject, not resolve undefined")
+function writeBrokenFixture(root) {
+  const write = (rel, content) => {
+    const target = path.join(root, rel)
+    mkdirSync(path.dirname(target), { recursive: true })
+    writeFileSync(target, content)
+  }
+  write('project.config.json', JSON.stringify({ appid: 'fixture_app_broken', projectname: 'fixture-broken' }))
+  write('app.json', JSON.stringify({ pages: ['pages/index/index'] }))
+  write('app.js', 'App({})\n')
+  write('app.wxss', 'page { font-size: 14px; }\n')
+  write('pages/index/index.json', '{}\n')
+  // Unbalanced brace + bad tokens — same corruption shape used by devkit's
+  // open-project-compile-log fixture, chosen because it fails the logic stage
+  // rather than being silently absorbed by esbuild's error-tolerant fallback.
+  write('pages/index/index.js', 'Page({ data: { msg: "hi" } })\nconst broken = {{{ ;;; <<<\n')
+  write('pages/index/index.wxml', '<view>{{msg}}</view>\n')
+  write('pages/index/index.wxss', '.x { color: red; }\n')
+}
+const brokenRoot = dir('broken-fixture')
+mkdirSync(brokenRoot, { recursive: true })
+writeBrokenFixture(brokenRoot)
+
+if (typeof defaultBuild !== 'function') {
+  fail('pool.node.js must have a default export `build(outputDir, workPath, useAppIdDir?, options?)` — default export is missing/not a function')
+}
+else {
+  let brokenResolvedValue
+  let brokenRejectedError
+  try {
+    brokenResolvedValue = await defaultBuild(dir('broken-out'), brokenRoot, true, {})
+  }
+  catch (e) {
+    brokenRejectedError = e
+  }
+  if (brokenRejectedError === undefined) {
+    fail(`default build() must REJECT on a broken compile — instead it resolved to ${JSON.stringify(brokenResolvedValue)} (a swallowed error looks like success to every caller)`)
+  }
+  else if (!(brokenRejectedError instanceof Error) || !brokenRejectedError.message) {
+    fail(`default build() rejected but without a usable Error message: ${brokenRejectedError}`)
+  }
+  else if (!/stage "logic" failed/.test(brokenRejectedError.message)) {
+    fail(`default build() rejection message must name the failing stage, got: ${brokenRejectedError.message.split('\n')[0]}`)
+  }
+  else if (!/Transform failed/.test(brokenRejectedError.message)) {
+    fail(`default build() rejection message must carry the underlying compile reason (esbuild transform failure), got: ${brokenRejectedError.message.split('\n')[0]}`)
+  }
+  else {
+    console.log(`[fail] ✅ default build() rejected with: ${brokenRejectedError.message.split('\n')[0]}`)
+  }
+}
+
+// --- oxcNativeBindingHint: pure message -> actionable-packaging-hint mapper -----------------------
+if (typeof oxcNativeBindingHint !== 'function') {
+  fail('pool.node.js must export a named `oxcNativeBindingHint(message)` helper — export is missing')
+}
+else {
+  const hint = oxcNativeBindingHint('Cannot find native binding. It means oxc-parser was not installed correctly for this platform.')
+  if (typeof hint !== 'string' || !hint.includes('@oxc-parser/binding-') || !hint.includes('wasm32-wasi')) {
+    fail(`oxcNativeBindingHint must mention both the native platform binding package (@oxc-parser/binding-*) and the wasm32-wasi fallback, got: ${JSON.stringify(hint)}`)
+  }
+  else {
+    console.log('[fail] ✅ oxcNativeBindingHint surfaces a packaging fix for a missing native binding')
+  }
+  const noHint = oxcNativeBindingHint('some unrelated compile error')
+  if (noHint !== null) {
+    fail(`oxcNativeBindingHint must return null for a message that is not the native-binding failure, got: ${JSON.stringify(noHint)}`)
+  }
+}
+
+// The default export is a lazy module-level singleton pool (resident worker threads) — the
+// broken-fixture build above spun it up, so the process cannot exit cleanly without disposing it.
+if (typeof disposeDefaultPool !== 'function') {
+  fail('pool.node.js must export `disposeDefaultPool()` to tear down the lazy default-export singleton pool')
+}
+else {
+  await disposeDefaultPool()
+}
+
+console.log(failed ? '\n❌ FAIL' : '\n✅ PASS: resident Node pool is dmcc-equivalent (incl. sourcemap) on cold+warm builds, and rejects broken compiles')
 process.exit(failed ? 1 : 0)

package/scripts/test-pool-toolchain-death.js

@@ -0,0 +1,135 @@
+// Regression coverage for the resident Node disk pool's handling of a DEAD esbuild
+// toolchain service — the Windows-packaged-app crash pattern: esbuild's JS lib spawns
+// a long-lived binary child process (the "service"), and in a packaged Electron app
+// that spawn can fail (e.g. the binary sits inside app.asar, which fs.existsSync()
+// sees but child_process.spawn() cannot exec). Once that service is dead inside a
+// warm worker realm, EVERY later esbuild call in that same realm fails with
+// "The service is no longer running: write EPIPE" — a message shape that looks
+// nothing like the real cause. Today the pool classifies this as
+// `code: 'compiler-stage-error'` ("deterministic, never retried") and keeps the
+// broken worker, so the pool never recovers even after the environment is healed.
+//
+// Fault injection needs no source changes: esbuild's node lib honors
+// ESBUILD_BINARY_PATH, and each worker_threads realm captures a COPY of
+// process.env at spawn. Pointing that var (before the pool spawns its workers) at
+// a real, executable file whose shebang interpreter does not exist reproduces the
+// exact "fs.existsSync() true, spawn() ENOENT" split a binary trapped inside
+// app.asar produces — child_process.spawn() reports ENOENT because the kernel's
+// own shebang-interpreter lookup fails, not because the file is missing.
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const APP = process.env.APP_DIR
+  || fileURLToPath(new URL('../../../dimina/fe/example/base', import.meta.url))
+const TMP = fileURLToPath(new URL('../.tmp-pool-toolchain-death/', import.meta.url))
+fs.rmSync(TMP, { recursive: true, force: true })
+fs.mkdirSync(TMP, { recursive: true })
+const dir = (n) => path.join(TMP, n)
+
+const FAKE_ESBUILD = path.join(TMP, 'fake-esbuild-service')
+fs.writeFileSync(FAKE_ESBUILD, '#!/nonexistent/esbuild-interpreter\necho unreachable\n')
+fs.chmodSync(FAKE_ESBUILD, 0o755)
+
+let failed = false
+const chk = (cond, msg) => { if (!cond) { failed = true; console.error(`❌ ${msg}`) } else console.log(`✅ ${msg}`) }
+const withTimeout = (p, ms, label) => Promise.race([
+  p,
+  new Promise((_, rej) => setTimeout(() => rej(new Error(`TIMEOUT: ${label} did not settle in ${ms}ms`)), ms).unref()),
+])
+const settle = (p) => p.then((v) => ({ ok: true, v }), (e) => ({ ok: false, e }))
+const treeOk = (d, i) => fs.existsSync(path.join(d, i.appId, 'main', 'logic.js'))
+
+// Property access (not a named import) so a dist build that has not yet added
+// esbuildAsarSpawnHint fails this script's own assertion instead of a module-link
+// SyntaxError that would abort before any other scenario runs.
+const poolModule = await import('../dist/pool.node.js')
+const { createNodeCompilerPool } = poolModule
+const esbuildAsarSpawnHint = poolModule.esbuildAsarSpawnHint
+
+// --- classification + recycle ------------------------------------------------------
+// A dead esbuild service must be coded distinctly from a real compile error, and the
+// worker(s) that hit it must be recycled so the NEXT build — once the environment is
+// healed — runs on a fresh realm instead of replaying the same dead service forever.
+process.env.ESBUILD_BINARY_PATH = FAKE_ESBUILD
+const pool = createNodeCompilerPool({ retryOnWorkerDeath: false })
+// Read immediately after creation, before the pool's own eager ensureAlive() settles —
+// the pristine pre-spawn baseline every later generation count is compared against.
+const gensPristine = pool._slots.map((x) => x.slot.generation)
+
+const first = await withTimeout(
+  settle(pool.build(dir('a1'), APP, true, {})), 60000, 'first build against a dead esbuild service',
+)
+chk(!first.ok, 'first build against a dead esbuild service rejects')
+const firstErr = first.ok ? null : first.e
+chk(!!firstErr && firstErr.code === 'compiler-toolchain-dead',
+  `dead-esbuild-service failure is coded 'compiler-toolchain-dead' (got ${firstErr && firstErr.code})`)
+chk(!!firstErr && typeof firstErr.stage === 'string' && firstErr.stage.length > 0,
+  `error carries .stage (got ${firstErr && firstErr.stage})`)
+chk(!!firstErr && /^\[compiler\] stage "[^"]+" failed: .*The service (was stopped|is no longer running)/.test(firstErr.message || ''),
+  `error message keeps the stage-shaped prefix around the dead-service cause: ${firstErr && firstErr.message}`)
+
+// Heal the environment the way a real fix would (repackage / relaunch): only NEWLY
+// spawned worker realms see this — the pool must actually recycle, not get lucky that
+// the already-spawned realm somehow un-breaks itself.
+delete process.env.ESBUILD_BINARY_PATH
+
+const second = await withTimeout(
+  settle(pool.build(dir('a2'), APP, true, {})), 60000, 'build after healing the toolchain env',
+)
+chk(second.ok && treeOk(dir('a2'), second.v),
+  `build after healing the env succeeds via recycled workers, not a permanent write EPIPE: ${second.ok ? 'ok' : second.e && second.e.message}`)
+
+const gensAfterHeal = pool._slots.map((x) => x.slot.generation)
+chk(gensAfterHeal.some((g, i) => g - gensPristine[i] > 1),
+  `pool recycled at least one worker slot between the dead-service failure and the next build (pristine ${gensPristine.join(',')} -> after-heal ${gensAfterHeal.join(',')})`)
+
+await pool.dispose()
+
+// --- transparent retry on a persistently broken toolchain --------------------------
+// retryOnWorkerDeath defaults to true and already gives worker crashes one whole-build
+// retry; a dead-toolchain failure must get the same treatment. With the environment
+// STILL broken the retry cannot succeed either, so the build must still reject (no
+// hang) — but by then the affected slot(s) should have been recycled on both the
+// initial attempt and its retry.
+process.env.ESBUILD_BINARY_PATH = FAKE_ESBUILD
+const poolR = createNodeCompilerPool() // retryOnWorkerDeath defaults to true
+const gensPristineR = poolR._slots.map((x) => x.slot.generation)
+
+const retried = await withTimeout(
+  settle(poolR.build(dir('r1'), APP, true, {})), 120000, 'build against a persistently dead esbuild service with retry enabled',
+)
+chk(!retried.ok, 'build against a persistently dead toolchain still rejects rather than hanging')
+chk(!retried.ok && retried.e && retried.e.code === 'compiler-toolchain-dead',
+  `the final rejection after the transparent retry is still coded 'compiler-toolchain-dead' (got ${retried.ok ? undefined : retried.e && retried.e.code})`)
+
+const gensAfterRetry = poolR._slots.map((x) => x.slot.generation)
+chk(gensAfterRetry.some((g, i) => g - gensPristineR[i] > 1),
+  `a persistently dead toolchain is recycled on both the initial attempt and its retry (pristine ${gensPristineR.join(',')} -> after-retry ${gensAfterRetry.join(',')})`)
+
+await poolR.dispose()
+delete process.env.ESBUILD_BINARY_PATH
+
+// --- pure helper: actionable asar-unpack hint for a dead esbuild service ------------
+chk(typeof esbuildAsarSpawnHint === 'function', 'esbuildAsarSpawnHint is exported from the pool module')
+if (typeof esbuildAsarSpawnHint === 'function') {
+  const asarMsg = 'The service was stopped: spawn C:\\Users\\x\\AppData\\Local\\Programs\\myapp\\resources\\app.asar\\node_modules\\@esbuild\\win32-x64\\esbuild.exe ENOENT'
+  const hint = esbuildAsarSpawnHint(asarMsg)
+  chk(typeof hint === 'string' && /asarUnpack/.test(hint),
+    `an asar-packaged esbuild ENOENT message gets an asarUnpack hint (got ${JSON.stringify(hint)})`)
+
+  const syntaxMsg = 'Transform failed with 1 error:\nfile.js:1:1: ERROR: Unexpected "}"'
+  chk(esbuildAsarSpawnHint(syntaxMsg) === null,
+    `an unrelated esbuild syntax error gets no hint (got ${JSON.stringify(esbuildAsarSpawnHint(syntaxMsg))})`)
+
+  const oxcMsg = 'Cannot find native binding. Napi module could not be resolved.'
+  chk(esbuildAsarSpawnHint(oxcMsg) === null,
+    `an oxc native-binding message (oxcNativeBindingHint's own territory) gets no hint here (got ${JSON.stringify(esbuildAsarSpawnHint(oxcMsg))})`)
+} else {
+  failed = true
+  console.error('❌ skipped esbuildAsarSpawnHint behavior checks (not exported)')
+}
+
+fs.rmSync(TMP, { recursive: true, force: true })
+console.log(failed ? '\n❌ FAIL' : '\n✅ PASS: dead-esbuild-service classification, recycle-on-failure, retry-still-rejects, asar hint')
+process.exit(failed ? 1 : 0)

package/scripts/toolchain-setup-node-native.js

@@ -0,0 +1,13 @@
+// Test-only toolchainSetupURL: installs globalThis.__esbuildTransform /
+// __oxcParseSync from the NATIVE esbuild/oxc-parser already in this package's own
+// dependencies (see package.json), instead of the real esbuild-wasm/oxc wasm32-wasi
+// bindings a real browser host would fetch. Both native functions have the exact
+// signature the browser shims (src/shims/esbuild-wasm.js / oxc-parser.js) forward
+// to verbatim (transform(input,options) / parseSync(filename,code,opts)), so this
+// exercises the REAL dist/stage-worker.browser.js code path end-to-end in Node
+// without paying for a wasm toolchain load.
+import { transform } from 'esbuild'
+import { parseSync } from 'oxc-parser'
+
+globalThis.__esbuildTransform = (input, options) => transform(input, options)
+globalThis.__oxcParseSync = parseSync

package/src/compile-core.js

@@ -455,13 +455,16 @@ let compileChain = Promise.resolve()
  * Compile a mini-program against a caller-injected fs. Calls are serialized per
  * realm (see the singleton note above). Convenience wrapper that runs
  * `setupCompile` + all stages + `collectOutputs` in one realm.
- * @param {{ fs: object, workPath?: string }} opts
+ * @param {{ fs: object, workPath?: string, options?: { fileTypes?: { template?: string[], style?: string[], viewScript?: string[] } } }} opts
  *   fs:       a node:fs replacement (sync subset: existsSync/readFileSync/
  *             readdirSync{withFileTypes}/statSync/writeFileSync/mkdirSync{recursive}/
  *             copyFileSync/rmSync), already seeded with the project source under
  *             `workPath`. The compiler also writes products back into it, and a
  *             missing project.config.json appid is written into it.
  *   workPath: project root inside the fs, default '/work'.
+ *   options:  forwarded to `setupCompile` -> dmcc's `storeInfo` (custom file-type
+ *             dialect, e.g. { fileTypes: { template: ['qdml'], style: ['qdss'],
+ *             viewScript: ['qds'] } }).
  * @returns {Promise<{ appId: string, name: string, files: Record<string,string> }>}
  */
 export function compileMiniApp(opts = {}) {
@@ -472,12 +475,12 @@ export function compileMiniApp(opts = {}) {
   return result
 }
 
-async function runCompile({ fs, workPath = '/work' } = {}) {
-  const ctx = await setupCompile({ fs, workPath })
+async function runCompile({ fs, workPath = '/work', options = {} } = {}) {
+  const ctx = await setupCompile({ fs, workPath, options })
   const { storeInfo: bundle, pages, appId, name, targetPath } = ctx
   // Same order as the original single pass. Stages are independent (no product
-  // read-back), so the order is not load-bearing — Phase 3 runs them concurrently
-  // in separate worker realms over a shared fs.
+  // read-back), so the order is not load-bearing — the worker pool (pool.js) runs
+  // them concurrently in separate worker realms over a shared fs.
   await compileStage({ stage: 'logic', pages, storeInfo: bundle, fs })
   await compileStage({ stage: 'view', pages, storeInfo: bundle, fs })
   await compileStage({ stage: 'style', pages, storeInfo: bundle, fs })

package/src/pool-node.js

@@ -38,7 +38,18 @@ const { Worker } = createRequire(import.meta.url)('node:worker_threads')
 // generous than the browser default: disk builds run whole real projects.
 const DEFAULT_SEND_TIMEOUT_MS = 120000
 
-const WORKER_DEATH_CODES = new Set(['compiler-worker-timeout', 'compiler-worker-crashed', 'compiler-worker-dead'])
+// 'compiler-toolchain-dead' belongs here even though the worker THREAD is alive: the
+// realm's esbuild service child process is gone, so the realm is just as unusable as a
+// crashed worker — the same one-retry-on-fresh-workers policy applies.
+const WORKER_DEATH_CODES = new Set(['compiler-worker-timeout', 'compiler-worker-crashed', 'compiler-worker-dead', 'compiler-toolchain-dead'])
+
+// esbuild's node lib drives a spawned long-lived binary child (its "service"). When that
+// child dies (spawn ENOENT in a packaged app, OOM kill, AV kill), esbuild reports every
+// call with one of these two phrases — and the service NEVER restarts inside that realm,
+// so the warm worker is permanently broken and must be recycled, not kept.
+function isDeadToolchainServiceError(message) {
+  return /The service (was stopped|is no longer running)/.test(String(message))
+}
 
 // Default idle window before the pool shrinks (terminates its resident stage workers to
 // release their memory — a warm worker set holds hundreds of MB of toolchain + compile
@@ -164,16 +175,33 @@ export function createNodeCompilerPool({
         if (err && err.code && !err.stage) err.stage = x.stage
         throw err
       })))
-    for (const r of results) {
-      if (!r || r.type === 'error') {
-        const info = r && r.error
-        const err = new Error(`[compiler] stage "${r && r.stage}" failed: ${(info && info.message) || 'unknown error'}`)
-        if (info && info.stack) err.stack = info.stack
-        err.stage = r && r.stage
+    // Walk EVERY result before throwing: when more than one stage hit a dead toolchain
+    // service (logic and view both drive esbuild), each broken realm must be recycled
+    // now — throwing on the first would leave the sibling's dead service warm, and the
+    // next build would fail on it all over again.
+    let firstErr = null
+    for (let i = 0; i < results.length; i++) {
+      const r = results[i]
+      if (r && r.type !== 'error') continue
+      const info = r && r.error
+      const cause = (info && info.message) || 'unknown error'
+      const hint = oxcNativeBindingHint(cause) || esbuildAsarSpawnHint(cause)
+      const err = new Error(`[compiler] stage "${r && r.stage}" failed: ${cause}${hint ? ` — ${hint}` : ''}`)
+      if (info && info.stack) err.stack = info.stack
+      err.stage = r && r.stage
+      if (isDeadToolchainServiceError(cause)) {
+        // The realm's toolchain service child is dead and never comes back — terminate
+        // the worker so the next attempt (the transparent retry, or the next build once
+        // the environment is healed) respawns a fresh realm with a fresh service.
+        // shrink() is safe here: settleAll above guarantees no request is in flight.
+        err.code = 'compiler-toolchain-dead'
+        workers[i].slot.shrink()
+      } else {
         err.code = 'compiler-stage-error' // worker-reported compile error — never retried
-        throw err
       }
+      if (!firstErr) firstErr = err
     }
+    if (firstErr) throw firstErr
 
     // 3) Publish the staging dir to the caller's outputDir (dmcc-identical layout).
     publishToDist(outputDir, useAppIdDir)
@@ -232,19 +260,58 @@ export function createNodeCompilerPool({
 // user-facing compile-log lines a host (e.g. devkit/devtools' log panel) already scrapes.
 const STAGE_TITLES = { logic: '编译页面逻辑', view: '编译页面文件', style: '编译样式文件' }
 
+/**
+ * Map a failure message to an actionable packaging hint when it is esbuild failing to
+ * spawn its native binary from inside an Electron app.asar archive. Electron patches
+ * child_process.execFile for asar paths but NOT child_process.spawn (which esbuild
+ * uses), so an in-archive binary path always ENOENTs at spawn even though fs sees the
+ * file — the raw message points at a path that plainly exists, which is why it needs
+ * a hint. Returns null for every other message.
+ * @param {string} message
+ * @returns {string | null}
+ */
+export function esbuildAsarSpawnHint(message) {
+  const msg = String(message)
+  if (!/app\.asar/.test(msg) || !/esbuild/i.test(msg) || !/ENOENT/.test(msg)) return null
+  return 'esbuild 的原生二进制无法从 app.asar 内 spawn（Electron 只为 execFile 打 asar 补丁）：'
+    + "打包配置需 asarUnpack '**/node_modules/esbuild/**' 与 '**/node_modules/@esbuild/**'，"
+    + '并确保 ESBUILD_BINARY_PATH 指向 app.asar.unpacked 下的真实二进制（@dimina-kit/devkit 在 asar 内运行时会自动设置）'
+}
+
+/**
+ * Map a failure message to an actionable packaging hint when it is oxc-parser's
+ * "missing runtime binding" error (thrown when NEITHER the platform-native
+ * `@oxc-parser/binding-<platform>` package NOR the `@oxc-parser/binding-wasm32-wasi`
+ * fallback resolves at runtime). Neither package is a direct dependency of a
+ * typical host, so app bundlers (e.g. electron-builder's dependency collection)
+ * silently drop them — and the raw oxc message says nothing about packaging.
+ * Returns null for every other message.
+ * @param {string} message
+ * @returns {string | null}
+ */
+export function oxcNativeBindingHint(message) {
+  if (!/Cannot find native binding/i.test(String(message))) return null
+  return 'oxc-parser 的运行时绑定没有被打进宿主应用：@dimina-kit/compiler 的 Node 编译路径需要 '
+    + `@oxc-parser/binding-${process.platform}-${process.arch}（平台原生绑定）或 `
+    + '@oxc-parser/binding-wasm32-wasi（wasm 兜底）二者之一实际存在于包内。'
+    + '打包分发（如 electron-builder）时请把其中一个显式声明为宿主依赖，避免依赖收集时被丢弃'
+}
+
 // Lazy singleton pool — a DROP-IN replacement for dmcc's `build(targetPath, workPath,
-// useAppIdDir, options)`, matching its behavior on BOTH the happy and error paths so a
-// host that consumed dmcc keeps working unchanged:
+// useAppIdDir, options)` with ONE deliberate divergence on the error path:
 //   • the first call spins up the resident workers; every later call (a watch rebuild)
 //     reuses them warm;
 //   • on success it emits `✔ 输出编译产物` on stdout (dmcc's listr2 completion line — the
 //     pool has no listr2, so the equivalent user-facing line is surfaced here);
-//   • on failure it reports the failing stage + summary on stderr and RESOLVES undefined
-//     (never rethrows), exactly like dmcc's build() catch (index.js) — the host normalizes
-//     undefined to a null appInfo and the error detail (incl. dmcc's own
-//     `[logic] esbuild 转换失败 …`) still reaches the log channel.
-// Callers that want structured throwing errors + explicit teardown should use
-// createNodeCompilerPool() directly instead.
+//   • on failure it reports the failing stage + summary on stderr (same lines a dmcc
+//     host already scrapes: `✖ <stage>` + `<workPath> 编译出错: …`) and then REJECTS
+//     with the error. dmcc's own build() swallows the error and resolves undefined,
+//     which makes a failed compile indistinguishable from benign "no app info" — a
+//     host would start a session that can only 404. Rejecting keeps the log surface
+//     identical while giving callers a real failure signal; a resolved null/undefined
+//     no longer means "compile failed", only "no app info to report".
+// Callers that want structured errors (`.stage`/`.code`) + explicit teardown should
+// use createNodeCompilerPool() directly instead.
 let singleton = null
 export default async function build(outputDir, workPath, useAppIdDir = true, options = {}) {
   if (!singleton) singleton = createNodeCompilerPool()
@@ -255,7 +322,7 @@ export default async function build(outputDir, workPath, useAppIdDir = true, opt
   } catch (e) {
     if (e && e.stage) console.error(`✖ ${STAGE_TITLES[e.stage] || e.stage}`)
     console.error(`${workPath} 编译出错: ${e && e.message}`)
-    return undefined
+    throw e
   }
 }