@teacss/engine 0.9.1 → 0.9.3

package/README.md

@@ -22,19 +22,64 @@ Every package needs Node.js 22.12.0 or later; the wasm package needs `>=22.13.0
 
 ## Engine selection
 
-- `TEACSS_ENGINE=auto|rust|ts` overrides everything else. An unrecognized value is ignored, and the selection result carries it as `invalidEnv`.
-- Otherwise the integration's `engine` option decides, and without it TeaCSS uses the TypeScript engine.
-- `package.json#engineCompat.defaultMode` sets what the option `"auto"` means. While it is `"opt-in"` (the alpha releases), `engine: "auto"` stays on TypeScript, and only `TEACSS_ENGINE=rust` or `auto`, or `engine: "rust"`, tries Rust. From the beta, `"auto"` tries Rust and falls back when a configuration cannot run there.
-- With `"auto"`, a configuration Rust cannot serve falls back to TypeScript with a machine-readable reason; with `"rust"`, the same failure throws. The fallback reasons are grouped in [docs/architecture.md](../../docs/architecture.md) §9; the complete set is the `fail(...)` calls in `src/select.ts`.
+- `TEACSS_ENGINE=auto|rust|ts` overrides the `engine` option. An unrecognized value is ignored, and the selection result carries it as `invalidEnv`.
+- Otherwise the integration's `engine` option decides. `selectEngineRequest` with no option returns TypeScript; what an unset `engine` means is the teacss-ts hook's call.
+- `package.json#engineCompat.defaultMode` sets what the option `"auto"` means. It is `"auto"`: `engine: "auto"`, which the first-party integrations pass, tries Rust and falls back to TypeScript when the configuration cannot run there. Releases up to 0.9.1 shipped `"opt-in"`, under which the option `"auto"` stayed on TypeScript and only `TEACSS_ENGINE=rust|auto` or `engine: "rust"` tried Rust.
+- With `"auto"`, a configuration Rust cannot serve falls back to TypeScript with a machine-readable reason (see [Fallback reasons](#fallback-reasons)); with `"rust"`, the teacss-ts hook prints the same fallback as a warning, and throws instead when `TEACSS_ENGINE_STRICT=1` is set.
 
 `selectEngineRequest` from `@teacss/engine/select` (which does not load the binding) stays on TypeScript in three cases: `mode: "ts"` (TypeScript chosen explicitly), `resolvedBy: "opt-in"` (the option `"auto"` while `defaultMode` is `"opt-in"`), and `reason: "engine-compat"` (the host `@teacss/core` is outside `engineCompat.core`).
 
+## Fallback reasons
+
+A fallback prints one line per reason and path per process: `[teacss] engine: falling back to the TypeScript engine (<reason> at <path>)`. In teacss-ts, `TEACSS_ENGINE_STATS=1` prints on exit how many generators ran on each engine and which reasons fell back. `TEACSS_ENGINE_DEBUG=1` makes this package print the translated request or the first failure to stderr. The facade stops at the first item it cannot translate, so fixing one reason can reveal the next.
+
+To keep TypeScript for any configuration, set `TEACSS_ENGINE=ts` (it covers every integration), or write `engine: "ts"` in the configuration or in the host's defaults, for example `pluginTeacss(config, { engine: "ts" })`. A fallback is not an error: the TypeScript engine produces the same CSS it always has.
+
+`<i>` is the preset's index after nested presets are flattened and ordered by `enforce`.
+
+| Reason | Path | What it means and why | To run on Rust |
+| --- | --- | --- | --- |
+| `engine-unavailable` | `@teacss/engine` | Reported by the teacss-ts hook, not by this package: importing the facade failed, usually because no platform package matches the machine or the native binding did not load. | Install the platform package for your machine; see [Troubleshooting](#troubleshooting). `TEACSS_ENGINE=rust` throws with the loader's error instead of falling back. |
+| `engine-compat` | `@teacss/core` | The host `@teacss/core` is outside `engineCompat.core`, so the pair was not tested together. `TEACSS_ENGINE=rust` throws `E_ENGINE_COMPAT` instead. | Align `@teacss/core` and `@teacss/engine`; check the lockfile for a second copy of either. |
+| `unknown-key` | the key | A top-level config key the facade does not know, such as a typo or an option from a newer core. Rust cannot know what it means. | Remove or correct the key. |
+| `rules`, `variants`, `extractors`, `extractorDefault`, `preflights`, `preprocess`, `postprocess`, `extendTheme`, `configResolved`, `autocomplete`, `cli` | the key | The key has a non-empty value. These hold functions or matchers that only JavaScript can run, and Rust does not execute JavaScript. | Remove the key from the configuration the integration loads, or express it statically with `shortcuts`, `theme`, `safelist` or a preset option. |
+| `separators` | `separators` | Separators other than the default `[":", "-"]`; Rust parses only the default. | Remove `separators`. |
+| `mergeSelectors` | `mergeSelectors` | `mergeSelectors: false`; Rust always merges selectors. | Remove it. |
+| `details` | `details` | `details` is set; Rust does not support it. | Remove it. |
+| `sortLayers` | `sortLayers` | A `sortLayers` function. | Remove it and order layers with `layers`. |
+| `content` | `content` or `content.filesystem` | `content` is not an object, or `content.filesystem` is not an array of strings. | Use an array of glob strings. |
+| `content.inline` | `content.inline` | Inline content sources, which only the TypeScript engine reads. | Move the content into files matched by `content.filesystem`. |
+| `envMode` | `envMode` | A value other than `"dev"` or `"build"`. | Use one of the two. |
+| `unmatched` | `unmatched` | A value other than `"warn"`, `"error"` or `"off"`. | Use one of the three. |
+| `outputToCssLayers` | `outputToCssLayers` | Neither a boolean nor an object. | Use `true`, `false` or `{ allLayers }`. |
+| `outputToCssLayers.cssLayerName` | `outputToCssLayers.cssLayerName` | A `cssLayerName` value; Rust does not support it. | Remove it. |
+| `transformers` | `transformers` or `transformers[<n>]` | A transformer other than `@teacss/transformer-compile-class` and `@teacss/directives`, or a `transformers` value that is not an array. Other transformers run JavaScript over the source. | Remove the transformer, or keep TypeScript. |
+| `transformers.compile-class` | `transformers[<n>]` | The config lists its own `transformerCompileClass()` and the last Standard preset does not enable `compileClass`, or there is no Standard preset. Its options live in a closure, and the classes it registers never reach Rust. | Enable compile-class through `presetStandard({ compileClass })`, or keep TypeScript. |
+| `shortcuts`, `safelist`, `blocklist`, `theme`, `layers` | the key and the item inside it | A value that is not static data: a shortcut whose expansion is not a string, or that has a regular expression or meta; a `safelist` or `blocklist` item that is not a string; a theme leaf that is not a string or number, the removed `rolePalettes` or `themes` theme key, or a `defaultMode` or mode name that is empty or holds a NUL or a lone surrogate (Standard rejects these; the TypeScript engine raises its error); a layer order that is not a number. | Replace the item with static data. |
+| `preset-not-instantiated` | `presets[<n>]` | A preset that is a function, a promise or not an object. | Call the factory (`presetStandard()`, not `presetStandard`) and await it before passing it. |
+| `preset-cycle` | `presets[<n>]…` | A preset that contains itself through nested `presets`. | Break the cycle. |
+| `accessor` | the key | A getter or setter on the config, the defaults or a preset. Translation would run it once and the TypeScript engine again. | Use plain data properties. |
+| `standard.unknown-option` | `presets[<i>].options.<key>` | A Standard option other than `modeSelectors`, `containers`, `preflight`, `variablePrefix` and `compileClass`. | Remove the option. |
+| `standard.compileClass.hashFn`, `standard.compileClass.trigger` | `presets[<i>].options.compileClass.…` | A custom hash function or trigger for compiled classes. | Remove it; `classPrefix`, `alwaysHash`, `keepUnknown` and `layer` are supported. |
+| `icons.collections` | `presets[<i>].options.collections.<name>` | An icon collection other than the bundled `carbon`, `crypto`, `flagpack`, `logo` and `lucide`. | Use a bundled collection, or keep TypeScript. |
+| `icons.customizations`, `icons.processor` | `presets[<i>].options.…` | Icon customizations or a processor, which run JavaScript. | Remove them. |
+| `role-palettes-without-entry` | `presets[<i>]` | The `@teacss/config/role-palettes` preset in a configuration that did not come from an entry stylesheet. On Rust the preset needs the entry. | Load the configuration from its entry stylesheet through `@teacss/config`. |
+| `preset.name` | `presets[<i>].name` | A preset without a string `name`. | Give the preset a name. |
+| `preset.rules`, `preset.variants`, `preset.extractors`, `preset.preflights`, `preset.preprocess`, `preset.postprocess`, `preset.extendTheme`, `preset.configResolved`, `preset.transformers`, `preset.autocomplete`, `preset.extractorDefault` | `presets[<i>].<key>` | A preset that is not one of the built-in presets carries a dynamic field, as for the top-level keys above. | Remove the field from the preset, or keep TypeScript. |
+| `preset.content` | `presets[<i>].content` | A preset's `content` holds something other than `pipeline`, such as `filesystem` or `inline`; Rust reads content globs only from the configuration. | Move the globs to the configuration's `content.filesystem`. |
+| `preset.shortcuts`, `preset.safelist`, `preset.blocklist`, `preset.theme`, `preset.layers` | `presets[<i>].<key>…` | A preset field that is not static data, as for the top-level keys above. | Replace the item with static data. |
+| `preset.enforce`, `preset.layer` | `presets[<i>].<key>` | `enforce` other than `"pre"` or `"post"`, or a `layer` that is not a string. | Correct the value. |
+| `declarations-unsaved` | the declaration file | A declaration file whose text came from an unsaved editor buffer. Rust reads declaration files from disk. | Save the file. |
+| `declarations-unavailable` | `content.filesystem` | Finding declaration files under `content.filesystem` failed: the `@teacss/config` source scanner could not be loaded, or it threw. | Install `@teacss/config`. |
+
+`content.pipeline` never falls back, in the configuration or in a preset, whatever it holds (RegExp, functions or `false`). It only decides which modules the integration feeds in, so it stays on the facade's `config.content` and is not sent to Rust.
+
 ## Compatibility
 
 | `engineCompat` field | Meaning |
 | --- | --- |
 | `core` | The `@teacss/core` versions this engine accepts, written as `>=A.B.C <X.Y.Z`; prereleases compare by SemVer, so `0.9.0-alpha.1 < 0.9.0` |
-| `defaultMode` | What the option `"auto"` means: `"opt-in"` keeps TypeScript, `"auto"` tries Rust |
+| `defaultMode` | What the option `"auto"` means: `"opt-in"` keeps TypeScript, `"auto"` (the current value) tries Rust |
 | `oracle.teacssTs` / `oracle.commit` | The teacss-ts version and commit this release was compared against byte for byte |
 
 | `@teacss/core` | `@teacss/engine` | `engineCompat.core` | Result |

package/binding.js

@@ -92,8 +92,8 @@ function requireNative() {
       try {
         const binding = require('@teacss/engine-android-arm64')
         const bindingPackageVersion = require('@teacss/engine-android-arm64/package.json').version
-        if (bindingPackageVersion !== '0.9.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.9.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.9.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -108,8 +108,8 @@ function requireNative() {
       try {
         const binding = require('@teacss/engine-android-arm-eabi')
         const bindingPackageVersion = require('@teacss/engine-android-arm-eabi/package.json').version
-        if (bindingPackageVersion !== '0.9.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.9.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.9.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -129,8 +129,8 @@ function requireNative() {
         try {
           const binding = require('@teacss/engine-win32-x64-gnu')
           const bindingPackageVersion = require('@teacss/engine-win32-x64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.9.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.9.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.9.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -145,8 +145,8 @@ function requireNative() {
         try {
           const binding = require('@teacss/engine-win32-x64-msvc')
           const bindingPackageVersion = require('@teacss/engine-win32-x64-msvc/package.json').version
-          if (bindingPackageVersion !== '0.9.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.9.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.9.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -162,8 +162,8 @@ function requireNative() {
       try {
         const binding = require('@teacss/engine-win32-ia32-msvc')
         const bindingPackageVersion = require('@teacss/engine-win32-ia32-msvc/package.json').version
-        if (bindingPackageVersion !== '0.9.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.9.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.9.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -178,8 +178,8 @@ function requireNative() {
       try {
         const binding = require('@teacss/engine-win32-arm64-msvc')
         const bindingPackageVersion = require('@teacss/engine-win32-arm64-msvc/package.json').version
-        if (bindingPackageVersion !== '0.9.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.9.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.9.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -197,8 +197,8 @@ function requireNative() {
     try {
       const binding = require('@teacss/engine-darwin-universal')
       const bindingPackageVersion = require('@teacss/engine-darwin-universal/package.json').version
-      if (bindingPackageVersion !== '0.9.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-        throw new Error(`Native binding package version mismatch, expected 0.9.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+      if (bindingPackageVersion !== '0.9.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+        throw new Error(`Native binding package version mismatch, expected 0.9.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
       }
       return binding
     } catch (e) {
@@ -213,8 +213,8 @@ function requireNative() {
       try {
         const binding = require('@teacss/engine-darwin-x64')
         const bindingPackageVersion = require('@teacss/engine-darwin-x64/package.json').version
-        if (bindingPackageVersion !== '0.9.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.9.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.9.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -229,8 +229,8 @@ function requireNative() {
       try {
         const binding = require('@teacss/engine-darwin-arm64')
         const bindingPackageVersion = require('@teacss/engine-darwin-arm64/package.json').version
-        if (bindingPackageVersion !== '0.9.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.9.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.9.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -249,8 +249,8 @@ function requireNative() {
       try {
         const binding = require('@teacss/engine-freebsd-x64')
         const bindingPackageVersion = require('@teacss/engine-freebsd-x64/package.json').version
-        if (bindingPackageVersion !== '0.9.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.9.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.9.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -265,8 +265,8 @@ function requireNative() {
       try {
         const binding = require('@teacss/engine-freebsd-arm64')
         const bindingPackageVersion = require('@teacss/engine-freebsd-arm64/package.json').version
-        if (bindingPackageVersion !== '0.9.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.9.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.9.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -286,8 +286,8 @@ function requireNative() {
         try {
           const binding = require('@teacss/engine-linux-x64-musl')
           const bindingPackageVersion = require('@teacss/engine-linux-x64-musl/package.json').version
-          if (bindingPackageVersion !== '0.9.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.9.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.9.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -302,8 +302,8 @@ function requireNative() {
         try {
           const binding = require('@teacss/engine-linux-x64-gnu')
           const bindingPackageVersion = require('@teacss/engine-linux-x64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.9.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.9.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.9.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -320,8 +320,8 @@ function requireNative() {
         try {
           const binding = require('@teacss/engine-linux-arm64-musl')
           const bindingPackageVersion = require('@teacss/engine-linux-arm64-musl/package.json').version
-          if (bindingPackageVersion !== '0.9.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.9.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.9.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -336,8 +336,8 @@ function requireNative() {
         try {
           const binding = require('@teacss/engine-linux-arm64-gnu')
           const bindingPackageVersion = require('@teacss/engine-linux-arm64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.9.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.9.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.9.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -354,8 +354,8 @@ function requireNative() {
         try {
           const binding = require('@teacss/engine-linux-arm-musleabihf')
           const bindingPackageVersion = require('@teacss/engine-linux-arm-musleabihf/package.json').version
-          if (bindingPackageVersion !== '0.9.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.9.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.9.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -370,8 +370,8 @@ function requireNative() {
         try {
           const binding = require('@teacss/engine-linux-arm-gnueabihf')
           const bindingPackageVersion = require('@teacss/engine-linux-arm-gnueabihf/package.json').version
-          if (bindingPackageVersion !== '0.9.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.9.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.9.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -388,8 +388,8 @@ function requireNative() {
         try {
           const binding = require('@teacss/engine-linux-loong64-musl')
           const bindingPackageVersion = require('@teacss/engine-linux-loong64-musl/package.json').version
-          if (bindingPackageVersion !== '0.9.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.9.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.9.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -404,8 +404,8 @@ function requireNative() {
         try {
           const binding = require('@teacss/engine-linux-loong64-gnu')
           const bindingPackageVersion = require('@teacss/engine-linux-loong64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.9.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.9.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.9.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -422,8 +422,8 @@ function requireNative() {
         try {
           const binding = require('@teacss/engine-linux-riscv64-musl')
           const bindingPackageVersion = require('@teacss/engine-linux-riscv64-musl/package.json').version
-          if (bindingPackageVersion !== '0.9.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.9.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.9.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -438,8 +438,8 @@ function requireNative() {
         try {
           const binding = require('@teacss/engine-linux-riscv64-gnu')
           const bindingPackageVersion = require('@teacss/engine-linux-riscv64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.9.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.9.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.9.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -455,8 +455,8 @@ function requireNative() {
       try {
         const binding = require('@teacss/engine-linux-ppc64-gnu')
         const bindingPackageVersion = require('@teacss/engine-linux-ppc64-gnu/package.json').version
-        if (bindingPackageVersion !== '0.9.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.9.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.9.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -471,8 +471,8 @@ function requireNative() {
       try {
         const binding = require('@teacss/engine-linux-s390x-gnu')
         const bindingPackageVersion = require('@teacss/engine-linux-s390x-gnu/package.json').version
-        if (bindingPackageVersion !== '0.9.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.9.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.9.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -491,8 +491,8 @@ function requireNative() {
       try {
         const binding = require('@teacss/engine-openharmony-arm64')
         const bindingPackageVersion = require('@teacss/engine-openharmony-arm64/package.json').version
-        if (bindingPackageVersion !== '0.9.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.9.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.9.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -507,8 +507,8 @@ function requireNative() {
       try {
         const binding = require('@teacss/engine-openharmony-x64')
         const bindingPackageVersion = require('@teacss/engine-openharmony-x64/package.json').version
-        if (bindingPackageVersion !== '0.9.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.9.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.9.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -523,8 +523,8 @@ function requireNative() {
       try {
         const binding = require('@teacss/engine-openharmony-arm')
         const bindingPackageVersion = require('@teacss/engine-openharmony-arm/package.json').version
-        if (bindingPackageVersion !== '0.9.1' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.9.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.3' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.9.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -664,8 +664,8 @@ if (!nativeBinding || forceWasi) {
       if (!candidateFailed) {
         if (process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
           const bindingPackageVersion = require('@teacss/engine-wasm32-wasi/package.json').version
-          if (bindingPackageVersion !== '0.9.1') {
-            throw new Error(`WASI binding package version mismatch, expected 0.9.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.3') {
+            throw new Error(`WASI binding package version mismatch, expected 0.9.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
         }
         wasiBinding = require('@teacss/engine-wasm32-wasi')

package/contract.d.ts

@@ -1,4 +1,4 @@
-// Mirror of docs/specs/v02.2-engine-contract.md §3 (spec-revision 11). Do not edit without bumping the spec revision.
+// Mirror of docs/specs/v02.2-engine-contract.md §3 (spec-revision 13). Do not edit without bumping the spec revision.
 export interface InspectEntryRequest {
   /** 项目根（绝对路径）。相对 @source 以声明它的文件所在目录为基准。 */
   root: string;

package/dist/config-view.d.ts

@@ -23,5 +23,14 @@ export interface ConfigViewArgs {
         compileClassShortcuts(): unknown[];
     };
 }
+/**
+ * The merged `content.pipeline` of the presets and the config, as `mergeContentOptions`
+ * (core/config.ts) builds it: `false` anywhere disables it, otherwise includes and excludes
+ * concatenate in source order without duplicates. The runtime builds its module filter from it.
+ */
+export declare function mergePipeline(sources: readonly unknown[]): false | {
+    include?: Array<string | RegExp>;
+    exclude?: Array<string | RegExp>;
+} | undefined;
 export declare function createConfigView({ view, presets, merged, transformers, host, fallback, engine }: ConfigViewArgs): Record<string, unknown>;
 //# sourceMappingURL=config-view.d.ts.map

package/dist/config-view.js

@@ -38,6 +38,40 @@ const RESOLVED_KEYS = Object.freeze([
     "content",
     "transformers",
 ]);
+const ownValue = (source, key) => (source !== null && typeof source === "object" && Object.hasOwn(source, key) ? source[key] : undefined);
+const flattenPatterns = (patterns) => [...new Set(patterns.flatMap((pattern) => (Array.isArray(pattern) ? pattern : pattern ? [pattern] : [])))];
+/**
+ * The merged `content.pipeline` of the presets and the config, as `mergeContentOptions`
+ * (core/config.ts) builds it: `false` anywhere disables it, otherwise includes and excludes
+ * concatenate in source order without duplicates. The runtime builds its module filter from it.
+ */
+export function mergePipeline(sources) {
+    const includes = [];
+    const excludes = [];
+    let configured = false;
+    for (const content of new Set(sources.map((source) => ownValue(source, "content")).filter((content) => content !== undefined && content !== null))) {
+        const pipeline = ownValue(content, "pipeline");
+        if (pipeline === false)
+            return false;
+        if (pipeline === undefined)
+            continue;
+        configured = true;
+        const include = pipeline && ownValue(pipeline, "include");
+        const exclude = pipeline && ownValue(pipeline, "exclude");
+        if (include)
+            includes.push(include);
+        if (exclude)
+            excludes.push(exclude);
+    }
+    if (!configured)
+        return undefined;
+    const merged = {};
+    if (includes.length)
+        merged.include = flattenPatterns(includes);
+    if (excludes.length)
+        merged.exclude = flattenPatterns(excludes);
+    return merged;
+}
 export function createConfigView({ view, presets, merged, transformers, host, fallback, engine }) {
     const config = {};
     const data = (key, value) => Object.defineProperty(config, key, { value, enumerable: true, configurable: true, writable: true });
@@ -54,7 +88,10 @@ export function createConfigView({ view, presets, merged, transformers, host, fa
     const extractors = host.core ? [host.core.extractorSplit] : [{ name: view.extractors?.[0]?.name ?? "@teacss/core/extractor-split" }];
     const fields = {
         presets: () => data("presets", presets),
-        content: () => data("content", view.content ?? {}),
+        content: () => {
+            const pipeline = mergePipeline([...presets, merged]);
+            data("content", pipeline === undefined ? (view.content ?? {}) : { pipeline, ...view.content });
+        },
         transformers: () => data("transformers", transformers),
         extractors: () => data("extractors", extractors),
         extractorDefault: () => data("extractorDefault", extractors[0]),

package/dist/errors.d.ts

@@ -6,6 +6,8 @@ export declare class TeacssEngineError extends Error {
 }
 /** v02.9 §2.1: the member needs `@teacss/core`, which is not installed. */
 export declare function tsRequiredError(member: string): TeacssEngineError;
+/** The generator was disposed; the native Engine reports the same code after its own `dispose()`. */
+export declare function disposedError(member: string): TeacssEngineError;
 /** v02.9 §3.3: the member needs the TypeScript engine, which has not been materialized. */
 export declare function tsNotReadyError(member: string): TeacssEngineError;
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -11,6 +11,10 @@ export class TeacssEngineError extends Error {
 export function tsRequiredError(member) {
     return new TeacssEngineError("E_TS_REQUIRED", `[@teacss/engine] ${member} requires @teacss/core (optional peer) to be installed`, { member });
 }
+/** The generator was disposed; the native Engine reports the same code after its own `dispose()`. */
+export function disposedError(member) {
+    return new TeacssEngineError("E_DISPOSED", `[@teacss/engine] ${member} called after dispose()`);
+}
 /** v02.9 §3.3: the member needs the TypeScript engine, which has not been materialized. */
 export function tsNotReadyError(member) {
     return new TeacssEngineError("E_TS_REQUIRED", `[@teacss/engine] ${member} needs the TypeScript engine; await generator[Symbol.for('@teacss/engine/materialize')]() first or set engine: 'ts'`, { member });

package/dist/generator.d.ts

@@ -19,7 +19,8 @@ export declare function engineStats(): {
 };
 /**
  * v02.9 §9: each reason and path prints once per process; the counter grows on every call. A
- * host `report(reason, path, level)` (the hook's consola) replaces the stderr line.
+ * host `report(reason, path, level)` (core's `reportFallback`) gets every call and does both
+ * itself, so the counter is not touched here.
  */
 export declare function reportFallback(reason: string, path: string, host?: FacadeHost, level?: "info" | "warn"): void;
 export declare class FacadeGenerator {
@@ -121,6 +122,13 @@ export declare class FacadeGenerator {
         userConfig: Record<string, unknown>;
         version: number;
     }): boolean;
+    /**
+     * Releases the Engine this generator owns; later `generate`, `parseToken`, `applyExtractors`,
+     * `prepareConfig` and `commitConfig` throw `E_DISPOSED`, and a second call does nothing. A
+     * candidate committed into another generator handed its Engine over and leaves it alone.
+     */
+    dispose(): void;
+    [Symbol.dispose](): void;
 }
 /**
  * v02.9 §3.1: a Rust facade, or the reason the configuration needs TypeScript. Errors from
@@ -140,7 +148,7 @@ export interface FacadeHost {
         /** core/utils/warn.ts 的 warnOnce；传入时 shortcut 警告与 TS 引擎共用一个去重集合。 */
         warnOnce?: (message: string) => void;
     } | undefined;
-    /** 挂钩注入的日志出口；缺省时写 process.stderr。 */
+    /** 挂钩注入的回退出口（core 的 reportFallback）：每次回退都调用，由它计数并按 reason 与 path 去重打印；缺省时 facade 自己计数并写 process.stderr。 */
     report?: (reason: string, path: string, level: "info" | "warn") => void;
 }
 export type FacadeCreateResult = {

package/dist/generator.js

@@ -6,7 +6,7 @@ import { Engine } from "../binding.js";
 import { createConfigView } from "./config-view.js";
 import { ENGINE_INSTANCE, ENGINE_MATERIALIZE, ENGINE_PACKAGE_VERSION, ENGINE_STATS } from "./constants.js";
 import { BoundedSet, BoundedTokenCache, CountableSet, copyCountableSet, expandInputGroups, isCountableSet, MAX_RUNTIME_CACHE_ENTRIES } from "./countable-set.js";
-import { tsNotReadyError } from "./errors.js";
+import { disposedError, tsNotReadyError } from "./errors.js";
 import { buildMatched, createFacadeResult, describeUnmatched, fallbackIsTokenShaped, formatUnmatchedError, shortcutWarningMessages, splitMatched, toTuple } from "./result.js";
 import { mergeDefinedConfig, translateConfig } from "./select.js";
 import { createCompileClassTransformer } from "./transformer.js";
@@ -232,19 +232,21 @@ export function engineStats() {
 const reported = new Set();
 /**
  * v02.9 §9: each reason and path prints once per process; the counter grows on every call. A
- * host `report(reason, path, level)` (the hook's consola) replaces the stderr line.
+ * host `report(reason, path, level)` (core's `reportFallback`) gets every call and does both
+ * itself, so the counter is not touched here.
  */
 export function reportFallback(reason, path, host = {}, level = "info") {
+    if (typeof host.report === "function") {
+        host.report(reason, path, level);
+        return;
+    }
     const stats = engineStats();
     stats.fallbacks[reason] = (stats.fallbacks[reason] ?? 0) + 1;
     const key = `${reason}\0${path}`;
     if (reported.has(key))
         return;
     reported.add(key);
-    if (typeof host.report === "function")
-        host.report(reason, path, level);
-    else
-        process.stderr.write(`[teacss] engine: falling back to the TypeScript engine (${reason} at ${path})\n`);
+    process.stderr.write(`[teacss] engine: falling back to the TypeScript engine (${reason} at ${path})\n`);
 }
 /** array-internal.ts:7-13: ownership is rechecked before each read. */
 function* ownArrayValues(array) {
@@ -301,7 +303,10 @@ export class FacadeGenerator {
             disposeEngine(held.engine);
     });
     #backend;
+    #disposed = false;
     #held = null;
+    /** A TS candidate's own commit, run when another generator commits it. */
+    #commitTs = null;
     #host;
     #tsFallback;
     /** The compile-class transformer: created once and handed to every candidate (v02.9 §5.2). */
@@ -410,6 +415,7 @@ export class FacadeGenerator {
      * tokens; a counted set adds each token's occurrences.
      */
     async applyExtractors(code, id, extracted = new Set()) {
+        this.#assertLive("applyExtractors");
         await Promise.resolve();
         const backend = this.#backend;
         if (backend.kind === "ts")
@@ -447,6 +453,7 @@ export class FacadeGenerator {
      * runs `applyExtractors` on it, generator.ts:2378).
      */
     async generate(input, options = {}) {
+        this.#assertLive("generate");
         const backend = this.#backend;
         if (backend.kind === "ts") {
             // A rule may commit a new configuration through this facade while the TS backend runs; the
@@ -610,6 +617,7 @@ export class FacadeGenerator {
      * already cached reads back as `null`. With an `alias` nothing is cached.
      */
     async parseToken(raw, alias) {
+        this.#assertLive("parseToken");
         await Promise.resolve();
         const backend = this.#backend;
         if (backend.kind === "ts")
@@ -727,6 +735,7 @@ export class FacadeGenerator {
      * one. A configuration Rust cannot serve gets a TypeScript candidate.
      */
     async prepareConfig(userConfig, defaults) {
+        this.#assertLive("prepareConfig");
         await Promise.resolve();
         const version = ++this.#configVersion;
         const nextDefaults = defaults ?? this.defaults;
@@ -741,13 +750,14 @@ export class FacadeGenerator {
         else {
             this.#reportFallback(translated);
             const ts = await this.#tsFallback.create(userConfig, nextDefaults);
-            candidate = new FacadeGenerator({ ts, userConfig, defaults: nextDefaults, host: this.#host });
+            candidate = new FacadeGenerator({ ts: ts.generator, userConfig, defaults: nextDefaults, host: this.#host });
+            candidate.#commitTs = ts.commit;
         }
         const prepared = Object.freeze({ config: candidate.config, defaults: nextDefaults, generator: candidate, userConfig, version });
         this.#prepared.add(prepared);
         const held = candidate.#backend.kind === "rust" ? { kind: "rust", engine: candidate.#backend.engine, committed: false } : { kind: "ts", committed: false };
         candidate.#held = held;
-        FacadeGenerator.#registry.register(candidate, held);
+        FacadeGenerator.#registry.register(candidate, held, candidate);
         return prepared;
     }
     /**
@@ -755,6 +765,7 @@ export class FacadeGenerator {
      * superseded Rust candidate is disposed; so is the previous Engine once it is replaced.
      */
     commitConfig(prepared) {
+        this.#assertLive("commitConfig");
         if (!this.#prepared.delete(prepared))
             return false;
         const candidate = prepared.generator;
@@ -764,11 +775,18 @@ export class FacadeGenerator {
         }
         if (candidate.config !== prepared.config)
             return false;
+        let next = candidate.#backend;
+        if (candidate.#commitTs) {
+            const committed = candidate.#commitTs();
+            if (!committed)
+                return false;
+            next = { kind: "ts", generator: committed };
+        }
         const previous = this.#backend;
         this.defaults = prepared.defaults;
         this.userConfig = prepared.userConfig;
         this.#clearRuntimeCaches();
-        this.#backend = candidate.#backend;
+        this.#backend = next;
         if (candidate.#held)
             candidate.#held.committed = true;
         this.#tsFallback.invalidate(prepared.userConfig, prepared.defaults);
@@ -777,6 +795,30 @@ export class FacadeGenerator {
         this.#dispatchConfig(this.config);
         return true;
     }
+    /**
+     * Releases the Engine this generator owns; later `generate`, `parseToken`, `applyExtractors`,
+     * `prepareConfig` and `commitConfig` throw `E_DISPOSED`, and a second call does nothing. A
+     * candidate committed into another generator handed its Engine over and leaves it alone.
+     */
+    dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        FacadeGenerator.#registry.unregister(this);
+        const backend = this.#backend;
+        if (backend.kind !== "rust")
+            return;
+        const handedOver = this.#held?.committed === true && this.#held.engine === backend.engine;
+        if (!handedOver)
+            disposeEngine(backend.engine);
+    }
+    [Symbol.dispose]() {
+        this.dispose();
+    }
+    #assertLive(member) {
+        if (this.#disposed)
+            throw disposedError(member);
+    }
     /** An explicit `engine: "rust"` asked for Rust, so its fallback is a warning. */
     #reportFallback(failure) {
         const explicit = this.defaults?.engine === "rust" || this.userConfig?.engine === "rust";

package/dist/select.d.ts

@@ -54,7 +54,7 @@ export declare function pick(obj: Record<string, unknown>, keys: Iterable<string
 export declare function translateTaggedPreset(preset: object, path: string, ctx: {
     hasEntry: boolean;
 }): Success<object | null> | Failure | undefined;
-/** Keys of an unmarked preset whose non-empty value means fallback. */
+/** Keys of an unmarked preset whose non-empty value means fallback; `content` is checked by `hasContentBeyondPipeline`. */
 export declare const PRESET_DYNAMIC_KEYS: readonly string[];
 /**
  * v02.9 §4.5: the static shortcut forms as `[name, expansion]` pairs. A shortcut meta (`[n, e, meta]`)
@@ -88,6 +88,14 @@ export declare const ALLOWED_TRANSFORMER_NAMES: Set<string>;
  * checked per call (v02.9 §6.3), so none are read here.
  */
 export declare function translateTransformers(list: unknown): Success<object[]> | Failure;
+/**
+ * A config's own `transformerCompileClass(options)` keeps its options in a closure the facade
+ * cannot read, and it registers classes by pushing onto `config.shortcuts`, which never reaches
+ * the Engine. It is harmless only when the last Standard preset enables compileClass: the facade's
+ * Rust transformer then comes first and `uniqueNamed` drops it, as the oracle drops it after the
+ * preset's own. Otherwise it would run and its classes would generate no CSS, so it falls back.
+ */
+export declare function hostCompileClass(transformers: readonly object[], presetSpecs: readonly object[]): Failure | undefined;
 export type EntryProvenance = {
     base: string;
     entryFile: string | undefined;

package/dist/select.js

@@ -223,11 +223,23 @@ export function translateTaggedPreset(preset, path, ctx) {
         return ctx.hasEntry ? ok(null) : fail("role-palettes-without-entry", path);
     return undefined;
 }
-/** Keys of an unmarked preset whose non-empty value means fallback. */
-export const PRESET_DYNAMIC_KEYS = Object.freeze(["rules", "variants", "extractors", "preflights", "preprocess", "postprocess", "extendTheme", "configResolved", "transformers", "autocomplete", "extractorDefault", "content"]);
+/** Keys of an unmarked preset whose non-empty value means fallback; `content` is checked by `hasContentBeyondPipeline`. */
+export const PRESET_DYNAMIC_KEYS = Object.freeze(["rules", "variants", "extractors", "preflights", "preprocess", "postprocess", "extendTheme", "configResolved", "transformers", "autocomplete", "extractorDefault"]);
 const isPlainObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
 /** Values `undefined` are left out. */
 const defined = (entries) => Object.fromEntries(Object.entries(entries).filter(([, value]) => value !== undefined));
+/**
+ * `content.pipeline` only filters the modules an integration feeds in; generation never reads it
+ * (v02.2 §4), so it stays in the config view and never reaches Rust. Any other content field of a
+ * preset is not translated.
+ */
+function hasContentBeyondPipeline(content) {
+    if (!isNonEmpty(content))
+        return false;
+    if (!isPlainObject(content))
+        return true;
+    return Object.keys(content).some((key) => key !== "pipeline" && isNonEmpty(content[key]));
+}
 /**
  * v02.9 §4.5: the static shortcut forms as `[name, expansion]` pairs. A shortcut meta (`[n, e, meta]`)
  * has no place in `StaticPreset.shortcuts`, so any meta key falls back.
@@ -282,6 +294,26 @@ export function translateShortcuts(value, path, reasonOnFail) {
     }
     return ok(pairs.length > 0 ? pairs : undefined);
 }
+/** context.ts `isContextName` behind its falsy check: no NUL and no lone surrogate. */
+function isContextName(value) {
+    if (!value)
+        return false;
+    if (typeof value !== "string")
+        return true;
+    for (let index = 0; index < value.length; index++) {
+        const code = value.charCodeAt(index);
+        if (code === 0)
+            return false;
+        if (code >= 0xd800 && code <= 0xdbff) {
+            const next = value.charCodeAt(++index);
+            if (!(next >= 0xdc00 && next <= 0xdfff))
+                return false;
+        }
+        else if (code >= 0xdc00 && code <= 0xdfff)
+            return false;
+    }
+    return true;
+}
 /**
  * v02.9 §4.5: a theme as dotted keys to string leaves (numbers stringified); empty objects vanish.
  *
@@ -299,6 +331,16 @@ export function flattenTheme(theme, path, reasonOnFail) {
         if (isPlainObject(values) && Object.hasOwn(values, "rolePalettes"))
             return fail(reasonOnFail, `${path}.modes.${mode}.rolePalettes`);
     }
+    // Standard's `validateContextNames` (context.ts) throws on these. Flattening drops an empty
+    // object and the binding replaces lone surrogates, so Rust cannot see them.
+    if (Object.hasOwn(theme, "themes"))
+        return fail(reasonOnFail, `${path}.themes`);
+    if (Object.hasOwn(theme, "defaultMode") && !isContextName(theme.defaultMode))
+        return fail(reasonOnFail, `${path}.defaultMode`);
+    for (const [mode] of modes) {
+        if (!isContextName(mode))
+            return fail(reasonOnFail, `${path}.modes.${mode}`);
+    }
     const flat = {};
     const visit = (object, prefix) => {
         for (const [key, value] of Object.entries(object)) {
@@ -354,6 +396,8 @@ export function translateStaticPreset(preset, path) {
         if (isNonEmpty(preset[key]))
             return fail(`preset.${key}`, `${path}.${key}`);
     }
+    if (hasContentBeyondPipeline(preset.content))
+        return fail("preset.content", `${path}.content`);
     const shortcuts = translateShortcuts(preset.shortcuts, `${path}.shortcuts`, "preset.shortcuts");
     if (!shortcuts.ok)
         return shortcuts;
@@ -401,8 +445,6 @@ export function translateInline(merged) {
     if (merged.content !== undefined) {
         if (!isPlainObject(merged.content))
             return fail("content", "content");
-        if (Object.hasOwn(merged.content, "pipeline") && merged.content.pipeline !== undefined)
-            return fail("content.pipeline", "content.pipeline");
         if (isNonEmpty(merged.content.inline))
             return fail("content.inline", "content.inline");
         const filesystem = merged.content.filesystem;
@@ -436,6 +478,22 @@ export function translateTransformers(list) {
     }
     return ok(kept);
 }
+/**
+ * A config's own `transformerCompileClass(options)` keeps its options in a closure the facade
+ * cannot read, and it registers classes by pushing onto `config.shortcuts`, which never reaches
+ * the Engine. It is harmless only when the last Standard preset enables compileClass: the facade's
+ * Rust transformer then comes first and `uniqueNamed` drops it, as the oracle drops it after the
+ * preset's own. Otherwise it would run and its classes would generate no CSS, so it falls back.
+ */
+export function hostCompileClass(transformers, presetSpecs) {
+    const index = transformers.findIndex((transformer) => transformer.name === "@teacss/transformer-compile-class");
+    if (index < 0)
+        return undefined;
+    const standard = presetSpecs.findLast((spec) => spec.kind === "standard");
+    if (standard && standard.options.compileClass !== false)
+        return undefined;
+    return fail("transformers.compile-class", `transformers[${index}]`);
+}
 export const scanners = {
     load: null,
 };
@@ -551,6 +609,9 @@ async function translate(userConfig, defaults) {
     const transformers = translateTransformers(merged.transformers);
     if (!transformers.ok)
         return transformers;
+    const compileClass = hostCompileClass(transformers.value, presetSpecs);
+    if (compileClass)
+        return compileClass;
     const inline = translateInline(merged);
     if (!inline.ok)
         return inline;

package/dist/ts-fallback.d.ts

@@ -16,7 +16,16 @@ export interface TsFallback {
     invalidate(userConfig: object, defaults: object): void;
     generator(member?: string): Promise<TsGenerator>;
     peek(): TsGenerator | null;
-    create(userConfig: object, defaults: object): Promise<TsGenerator>;
+    create(userConfig: object, defaults: object): Promise<TsCandidate>;
+}
+/**
+ * A prepared TS configuration. `commit` runs the base generator's own `commitConfig`, which
+ * re-reads in-place edits of the prepared config (generator.ts:2036-2063), and returns the
+ * generator that now serves it, or `null` when the TS generator refused the commit.
+ */
+export interface TsCandidate {
+    generator: TsGenerator;
+    commit(): TsGenerator | null;
 }
 /**
  * `engine: "ts"` goes into the defaults, which take precedence over `config.engine`, so the TS

package/dist/ts-fallback.js

@@ -70,8 +70,9 @@ export function createTsFallback(host, committed) {
             // translate it, so `createGenerator` resolves to TS and creates no Engine.
             const base = await createTs(binding, typeof binding.createTsGenerator === "function" ? {} : userConfig, defaults);
             if (ENGINE_INSTANCE in Object(base) || typeof base?.prepareConfig !== "function")
-                return base;
-            return (await base.prepareConfig(userConfig, tsDefaults)).generator;
+                return { generator: base, commit: () => base };
+            const prepared = await base.prepareConfig(userConfig, tsDefaults);
+            return { generator: prepared.generator, commit: () => (base.commitConfig(prepared) ? base : null) };
         },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teacss/engine",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "In-process Rust engine for TeaCSS 0.9 (napi-rs binding and 0.8.x-compatible facade)",
   "license": "MIT",
   "type": "module",
@@ -65,21 +65,21 @@
   },
   "engineCompat": {
     "core": ">=0.8.5 <0.10.0",
-    "defaultMode": "opt-in",
+    "defaultMode": "auto",
     "oracle": {
       "teacssTs": "0.8.5",
       "commit": "786b4d40"
     }
   },
   "optionalDependencies": {
-    "@teacss/engine-darwin-arm64": "0.9.1",
-    "@teacss/engine-darwin-x64": "0.9.1",
-    "@teacss/engine-linux-arm64-gnu": "0.9.1",
-    "@teacss/engine-linux-arm64-musl": "0.9.1",
-    "@teacss/engine-linux-x64-gnu": "0.9.1",
-    "@teacss/engine-linux-x64-musl": "0.9.1",
-    "@teacss/engine-win32-arm64-msvc": "0.9.1",
-    "@teacss/engine-win32-x64-msvc": "0.9.1"
+    "@teacss/engine-darwin-arm64": "0.9.3",
+    "@teacss/engine-darwin-x64": "0.9.3",
+    "@teacss/engine-linux-arm64-gnu": "0.9.3",
+    "@teacss/engine-linux-arm64-musl": "0.9.3",
+    "@teacss/engine-linux-x64-gnu": "0.9.3",
+    "@teacss/engine-linux-x64-musl": "0.9.3",
+    "@teacss/engine-win32-arm64-msvc": "0.9.3",
+    "@teacss/engine-win32-x64-msvc": "0.9.3"
   },
   "peerDependencies": {
     "@teacss/config": ">=0.8.5 <0.10.0 || >=0.9.0-alpha.0 <0.10.0",