@teacss/engine 0.9.0-alpha.3 → 0.9.0

package/README.md

@@ -25,7 +25,7 @@ Every package needs Node.js 22.12.0 or later; the wasm package needs `>=22.13.0
 - `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 full list of fallback reasons is in [docs/specs/v02.9-facade-and-hook.md](../../docs/specs/v02.9-facade-and-hook.md) §4.6.
+- 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`.
 
 `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`).
 
@@ -52,7 +52,7 @@ The teacss-ts version this release is compared against is `package.json#engineCo
 import { Engine, version } from "@teacss/engine/binding";
 ```
 
-The types are in `index.d.ts`. The binding is a tooling-level API and is not part of the 0.9 stability promise; integrations should go through `@teacss/core`.
+The types are in `binding.d.ts`. The binding is a tooling-level API and is not part of the 0.9 stability promise; integrations should go through `@teacss/core`.
 
 ## Troubleshooting
 
@@ -81,8 +81,8 @@ gh attestation verify teacss-engine.<platform>.node --owner teacss
 npm --prefix packages/engine ci
 npm --prefix packages/engine run build:debug      # teacss-engine.<platform>.node, binding.js, binding.d.ts
 npm --prefix packages/engine test
-npm --prefix packages/engine run check:dts
-node -e 'import("./packages/engine/index.js").then(m => console.log(m.version()))'
+npm --prefix packages/engine run check:types
+node -e 'import("./packages/engine/dist/index.js").then(m => console.log(m.version()))'
 ```
 
 `build:debug` uses the `dev` profile and rebuilds incrementally in seconds. `npm run build` uses the release profile with `lto = "fat"`; use it only to reproduce the size budget or the import checks locally.

package/binding-header.d.ts

@@ -2,6 +2,7 @@
 /* eslint-disable */
 import type {
   CustomDiagnostic,
+  EngineStats,
   EntryConfig,
   EntryDiagnostic,
   ExtractFileResult,
@@ -14,7 +15,9 @@ import type {
   LoadProjectResult,
   ModuleUpdateResult,
   ResolvedConfigView,
+  RuleInfo,
   StringifiedUtil,
   TransformResult,
   UnmatchedDiagnostic,
+  VariantInfo,
 } from "./contract.js";

package/binding.d.ts

@@ -2,6 +2,7 @@
 /* eslint-disable */
 import type {
   CustomDiagnostic,
+  EngineStats,
   EntryConfig,
   EntryDiagnostic,
   ExtractFileResult,
@@ -14,9 +15,11 @@ import type {
   LoadProjectResult,
   ModuleUpdateResult,
   ResolvedConfigView,
+  RuleInfo,
   StringifiedUtil,
   TransformResult,
   UnmatchedDiagnostic,
+  VariantInfo,
 } from "./contract.js";
 
 /**
@@ -33,6 +36,8 @@ export declare class Engine {
   loadProject(request: LoadProjectRequest): LoadProjectResult
   programKey(): string
   configView(): ResolvedConfigView
+  rules(): RuleInfo[]
+  variants(): VariantInfo[]
   configFiles(): string[]
   customThemeKeys(): string[]
   updateModule(id: string, code: string): ModuleUpdateResult
@@ -49,8 +54,10 @@ export declare class Engine {
   generate(input: GenerateInput, options?: GenerateOptions | undefined | null): GenerateResult
   parseToken(raw: string, alias?: string | undefined | null): StringifiedUtil[] | null
   isBlocked(raw: string): boolean
+  isTokenBlocked(raw: string): boolean
   diagnoseUnmatched(tokens: string[]): UnmatchedDiagnostic[]
   themeValue(path: string): string | null
+  stats(): EngineStats
   dispose(): void
 }
 

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.0-alpha.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.0-alpha.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.0' && 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.0 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.0-alpha.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.0-alpha.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.0' && 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.0 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.0-alpha.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.0-alpha.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.0' && 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.0 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.0-alpha.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.0-alpha.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.0' && 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.0 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.0-alpha.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.0-alpha.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.0' && 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.0 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.0-alpha.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.0-alpha.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.0' && 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.0 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.0-alpha.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.0-alpha.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+      if (bindingPackageVersion !== '0.9.0' && 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.0 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.0-alpha.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.0-alpha.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.0' && 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.0 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.0-alpha.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.0-alpha.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.0' && 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.0 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.0-alpha.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.0-alpha.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.0' && 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.0 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.0-alpha.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.0-alpha.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.0' && 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.0 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.0-alpha.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.0-alpha.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.0' && 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.0 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.0-alpha.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.0-alpha.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.0' && 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.0 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.0-alpha.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.0-alpha.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.0' && 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.0 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.0-alpha.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.0-alpha.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.0' && 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.0 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.0-alpha.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.0-alpha.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.0' && 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.0 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.0-alpha.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.0-alpha.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.0' && 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.0 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.0-alpha.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.0-alpha.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.0' && 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.0 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.0-alpha.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.0-alpha.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.0' && 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.0 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.0-alpha.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.0-alpha.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.0' && 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.0 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.0-alpha.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.0-alpha.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.0' && 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.0 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.0-alpha.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.0-alpha.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.0' && 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.0 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.0-alpha.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.0-alpha.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.0' && 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.0 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.0-alpha.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.0-alpha.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.0' && 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.0 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.0-alpha.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.0-alpha.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.0' && 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.0 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.0-alpha.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.0-alpha.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.9.0' && 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.0 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.0-alpha.3') {
-            throw new Error(`WASI binding package version mismatch, expected 0.9.0-alpha.3 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.9.0') {
+            throw new Error(`WASI binding package version mismatch, expected 0.9.0 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 2). Do not edit without bumping the spec revision.
+// Mirror of docs/specs/v02.2-engine-contract.md §3 (spec-revision 11). Do not edit without bumping the spec revision.
 export interface InspectEntryRequest {
   /** 项目根（绝对路径）。相对 @source 以声明它的文件所在目录为基准。 */
   root: string;
@@ -153,20 +153,31 @@ export interface GenerateOptions {
   /** 默认 false；为 true 时填充 matchedInfo */
   extendedInfo?: boolean | undefined | null;
   scope?: string | undefined | null;
+  /** 默认 true；false 时不拼、不传整表 css，result.css 为 ""。facade 传 false，它用 layers 重建。 */
+  css?: boolean | undefined | null;
 }
 
 export interface GenerateResult {
-  /** 与 oracle `result.css` 逐字节相同。 */
+  /** 与 oracle `result.css` 逐字节相同；`options.css` 为 false 时为 ""。 */
   css: string;
   /** 有序层；oracle `result.layers` 与 `getLayer(name)` 的来源。 */
   layers: Array<{ name: string; css: string }>;
-  /** oracle `result.matched`（Set）按首次出现顺序。 */
-  matched: string[];
+  /** oracle `result.matched`（Set）按首次出现顺序，以 "\0" 分隔；没有时为 ""。 */
+  matched: string;
   /** extendedInfo 时填充。input 为 {kind:"code"} 时 count 是该 token 在抽取结果中的出现次数（oracle CountableSet 语义）；tokens/all 输入时为 -1（oracle 对不可计数输入的语义）。 */
   matchedInfo: Array<{ token: string; data: StringifiedUtil[]; count: number }> | null;
   programKey: string;
+  /** 有 shortcut 留下警告时才有这个键，按 token 的访问顺序（输入，再 safelist），每个 token 至多一项。facade 据此打印 oracle `stringifyShortcuts` 的警告（§6.8）。 */
+  shortcutWarnings?: ShortcutWarning[];
 }
 
+/**
+ * 一个 shortcut token 留下的警告。`shortcut` 是去掉 token 自身条件与 `!` 后的名（oracle `parent[1]`）。
+ * `unmatched`：不匹配任何规则的成员（blocklist 不作用于成员），按叶子顺序每个名一次，不带 token 自身的修饰；
+ * `leafLimit`：展开后成员超过该上限（§8），token 不匹配，成员不再报告。
+ */
+export type ShortcutWarning = { shortcut: string; unmatched: string[] } | { shortcut: string; leafLimit: number };
+
 /** oracle `StringifiedUtil` 元组的对象形式；`context` 字段不跨边界，facade 以 undefined 填充。 */
 export interface StringifiedUtil {
   index: number;
@@ -244,3 +255,36 @@ export interface ResolvedConfigView {
   standard: { preflight: boolean | "on-demand"; variablePrefix: string; compileClass: boolean } | null;
   icons: { collections: string[]; mode: "mask" | "bg" | "auto"; layer: string } | null;
 }
+
+export interface RuleInfo {
+  /** `RuleDescriptor` 的 id（如 "standard.spacing.p"）；shortcut 为 "shortcut:<name>"。 */
+  id: string;
+  /** `RuleMeta.layer`。 */
+  layer: string | null;
+  /** `RuleDescriptor` 的 priority；shortcut 为 0。 */
+  priority: number;
+  /** `MatcherKey` 的变体：Property、PropertyPrefix、Keyword；shortcut 按名作 keyword。 */
+  matcher: { kind: "property" | "prefix" | "keyword"; value: string };
+  source: "standard" | "official" | "icons" | "shortcut";
+}
+
+export interface VariantInfo {
+  /** 用户写在 `@` 之后的名字：表项按名，开放族为 `prefix-*`，括号参数为 `[…]`。 */
+  name: string;
+  /** 接受它的解析器：pseudo、relational、attribute、language、media、at-rule、container、breakpoint、arbitrary。 */
+  kind: string;
+  source: RuleInfo["source"];
+}
+
+export interface EngineStats {
+  moduleCount: number;
+  /** 所有模块 token 的总数（含跨模块重复）。 */
+  tokenCount: number;
+  distinctTokens: number;
+  /** fragment 缓存条数，含未匹配或被 blocklist 拦截的负条目。 */
+  fragmentEntries: number;
+  /** 估算：每条键的 token 字节 + 每个 util 的 selector、body、parent 字节 + 结构体大小。 */
+  fragmentBytes: number;
+  /** 上一次 generate 结果：css、各层 css、matched 的字节和；没有时为 0。 */
+  memoBytes: number;
+}

package/dist/{facade/config-view.d.ts → config-view.d.ts}

@@ -6,8 +6,8 @@ export interface ConfigViewArgs {
     view: Record<string, any>;
     request: object;
     presets: object[];
-    /** The merged config (`mergeDefinedConfig(defaults, userConfig)`) the oracle spreads. */
-    userConfig: Record<string, unknown>;
+    /** The merged config (`mergeDefinedConfig(defaults, userConfig)`, config.ts:210) the oracle spreads. */
+    merged: Record<string, unknown>;
     transformers: object[];
     host: {
         core?: {
@@ -23,5 +23,5 @@ export interface ConfigViewArgs {
         compileClassShortcuts(): unknown[];
     };
 }
-export declare function createConfigView({ view, presets, userConfig, transformers, host, fallback, engine }: ConfigViewArgs): Record<string, unknown>;
+export declare function createConfigView({ view, presets, merged, transformers, host, fallback, engine }: ConfigViewArgs): Record<string, unknown>;
 //# sourceMappingURL=config-view.d.ts.map

package/dist/{facade/config-view.js → config-view.js}

@@ -38,7 +38,7 @@ const RESOLVED_KEYS = Object.freeze([
     "content",
     "transformers",
 ]);
-export function createConfigView({ view, presets, userConfig, transformers, host, fallback, engine }) {
+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 });
     const tsOnly = (key) => Object.defineProperty(config, key, {
@@ -62,6 +62,8 @@ export function createConfigView({ view, presets, userConfig, transformers, host
     };
     for (const key of VIEW_FIELDS)
         fields[key] = () => data(key, view[key]);
+    // config.ts:263. Rust never warns, so its view does not carry the option.
+    fields.warn = () => data("warn", (Object.hasOwn(merged, "warn") ? merged.warn : undefined) ?? true);
     if (engine) {
         // compile-class.ts:84-106 pushes each definition onto `config.shortcuts` and splices it out
         // when its last module drops it; the definitions live in the Engine, so one array is kept in
@@ -80,13 +82,13 @@ export function createConfigView({ view, presets, userConfig, transformers, host
     }
     for (const key of TS_ONLY_FIELDS)
         fields[key] = () => tsOnly(key);
-    for (const key of Object.keys(userConfig ?? {})) {
+    for (const key of Object.keys(merged)) {
         if (key === "engine")
             continue;
         if (Object.hasOwn(fields, key))
             fields[key]();
         else
-            data(key, userConfig[key]);
+            data(key, merged[key]);
     }
     // Redefining a spread key keeps its position, as the object literal does.
     for (const key of RESOLVED_KEYS)

package/dist/{facade/constants.js → constants.js}

@@ -1,7 +1,7 @@
 // The facade's symbols and package constants. It imports nothing from the facade, so every
 // facade module can import it without a cycle through `index.ts`.
 import { createRequire } from "node:module";
-const pkg = createRequire(import.meta.url)("../../package.json");
+const pkg = createRequire(import.meta.url)("../package.json");
 /** `@teacss/engine`'s own package.json version; the facade `generator.version` without a host. */
 export const ENGINE_PACKAGE_VERSION = pkg.version;
 /** `package.json#engineCompat` (v02.11 §7.3); without it `core` is unrestricted and `defaultMode` is `"auto"`. */

package/dist/{facade/countable-set.d.ts → countable-set.d.ts}

@@ -17,7 +17,10 @@ export declare function copyCountableSet<K>(input: CountableSet<K>): CountableSe
 export declare function expandInputGroups<T extends Set<string>>(tokens: T): T;
 /**
  * The part of the oracle `BoundedMap` the facade uses: ordinary keys are evicted oldest first,
- * retained keys never count toward the limit.
+ * retained keys never count toward the limit. An entry can be pending (`setPending`,
+ * `replaceRetainedPending`): its value is `resolve(token)`, computed on the first read through
+ * `get`, `forEach` or iteration and kept in place; `has`, `size`, `delete` and eviction never
+ * resolve.
  */
 export declare class BoundedTokenCache<V> extends Map<string, V> {
     #private;
@@ -25,14 +28,25 @@ export declare class BoundedTokenCache<V> extends Map<string, V> {
     retained: Set<string>;
     /** Ordinary keys in insertion order, the order the native map iterates them. */
     order: Set<string>;
-    constructor(maxEntries?: number);
+    /** The value of a pending entry, called once per entry on its first read. */
+    resolve: (token: string) => V;
+    constructor(maxEntries?: number, resolve?: (token: string) => V);
     get retainedSize(): number;
     isRetained(key: string): boolean;
+    get(key: string): V | undefined;
+    entries(): MapIterator<[string, V]>;
+    values(): MapIterator<V>;
+    [Symbol.iterator](): MapIterator<[string, V]>;
+    forEach(callback: (value: V, key: string, map: Map<string, V>) => void, thisArg?: unknown): void;
     set(key: string, value: V): this;
+    /** Caches `key` with the value `resolve` supplies on its first read. */
+    setPending(key: string): this;
     delete(key: string): boolean;
     clear(): void;
     /** Replaces the retained entries (bounded-cache.ts:188-205 without the revision check). */
     replaceRetained(entries: Iterable<readonly [string, V]>): void;
+    /** `replaceRetained` with every value pending. */
+    replaceRetainedPending(keys: Iterable<string>): void;
 }
 /** FIFO bounded Set (the oracle `BoundedSet` without its `assumeNoPrototypeBypass` fast path). */
 export declare class BoundedSet extends Set<string> {

package/dist/{facade/countable-set.js → countable-set.js}

@@ -1,6 +1,6 @@
 // Token collections the facade shares with `@teacss/core`: CountableSet (core/utils/countable-set.ts),
 // expandInputGroups (core/generator.ts:517-535) and the FIFO caches of core/bounded-cache.ts.
-import { expandClassGroups, splitClassTokens } from "../../binding.js";
+import { expandClassGroups, splitClassTokens } from "../binding.js";
 export const MAX_RUNTIME_CACHE_ENTRIES = 10_000;
 export class CountableSet extends Set {
     _map = new Map();
@@ -64,16 +64,25 @@ export function expandInputGroups(tokens) {
     }
     return tokens;
 }
+/** The value of an entry whose token has not been resolved yet; never a valid `V`. */
+const PENDING = Symbol("@teacss/engine/pending");
+function noResolver(token) {
+    throw new TypeError(`[@teacss/engine] pending cache entry "${token}" has no resolver`);
+}
 /**
  * The part of the oracle `BoundedMap` the facade uses: ordinary keys are evicted oldest first,
- * retained keys never count toward the limit.
+ * retained keys never count toward the limit. An entry can be pending (`setPending`,
+ * `replaceRetainedPending`): its value is `resolve(token)`, computed on the first read through
+ * `get`, `forEach` or iteration and kept in place; `has`, `size`, `delete` and eviction never
+ * resolve.
  */
 export class BoundedTokenCache extends Map {
-    constructor(maxEntries = MAX_RUNTIME_CACHE_ENTRIES) {
+    constructor(maxEntries = MAX_RUNTIME_CACHE_ENTRIES, resolve = noResolver) {
         super();
         this.maxEntries = maxEntries;
         this.retained = new Set();
         this.order = new Set();
+        this.resolve = resolve;
     }
     get retainedSize() {
         return this.retained.size;
@@ -81,13 +90,31 @@ export class BoundedTokenCache extends Map {
     isRetained(key) {
         return this.retained.has(key);
     }
+    get(key) {
+        const stored = super.get(key);
+        return stored === PENDING ? this.#materialize(key) : stored;
+    }
+    *entries() {
+        for (const [key, stored] of super.entries())
+            yield [key, this.#value(key, stored)];
+    }
+    *values() {
+        for (const [key, stored] of super.entries())
+            yield this.#value(key, stored);
+    }
+    [Symbol.iterator]() {
+        return this.entries();
+    }
+    forEach(callback, thisArg) {
+        for (const [key, value] of this.entries())
+            callback.call(thisArg, value, key, this);
+    }
     set(key, value) {
-        const exists = super.has(key);
-        super.set(key, value);
-        if (!exists && !this.retained.has(key))
-            this.order.add(key);
-        this.#enforceLimit();
-        return this;
+        return this.#insert(key, value);
+    }
+    /** Caches `key` with the value `resolve` supplies on its first read. */
+    setPending(key) {
+        return this.#insert(key, PENDING);
     }
     delete(key) {
         const deleted = super.delete(key);
@@ -102,7 +129,32 @@ export class BoundedTokenCache extends Map {
     }
     /** Replaces the retained entries (bounded-cache.ts:188-205 without the revision check). */
     replaceRetained(entries) {
-        const next = new Map(entries);
+        this.#replaceRetained(new Map(entries));
+    }
+    /** `replaceRetained` with every value pending. */
+    replaceRetainedPending(keys) {
+        const next = new Map();
+        for (const key of keys)
+            next.set(key, PENDING);
+        this.#replaceRetained(next);
+    }
+    #value(key, stored) {
+        return stored === PENDING ? this.#materialize(key) : stored;
+    }
+    #materialize(key) {
+        const value = this.resolve(key);
+        super.set(key, value);
+        return value;
+    }
+    #insert(key, value) {
+        const exists = super.has(key);
+        this.#store(key, value);
+        if (!exists && !this.retained.has(key))
+            this.order.add(key);
+        this.#enforceLimit();
+        return this;
+    }
+    #replaceRetained(next) {
         for (const key of this.retained) {
             if (next.has(key))
                 continue;
@@ -111,11 +163,15 @@ export class BoundedTokenCache extends Map {
         }
         for (const [key, value] of next) {
             this.order.delete(key);
-            super.set(key, value);
+            this.#store(key, value);
             this.retained.add(key);
         }
         this.#enforceLimit();
     }
+    /** The marker is stored as a `V`; every read path above resolves it before a caller sees it. */
+    #store(key, value) {
+        super.set(key, value);
+    }
     #enforceLimit() {
         while (this.size - this.retained.size > this.maxEntries) {
             const oldest = this.order.values().next();

package/dist/{facade/generator.d.ts → generator.d.ts}

@@ -137,6 +137,8 @@ export interface FacadeHost {
         isCountableSet?: (value: unknown) => boolean;
         isTokenShaped?: (token: string) => boolean;
         toEscapedSelector?: (raw: string) => string;
+        /** core/utils/warn.ts 的 warnOnce；传入时 shortcut 警告与 TS 引擎共用一个去重集合。 */
+        warnOnce?: (message: string) => void;
     } | undefined;
     /** 挂钩注入的日志出口；缺省时写 process.stderr。 */
     report?: (reason: string, path: string, level: "info" | "warn") => void;

package/dist/{facade/generator.js → generator.js}

@@ -2,15 +2,29 @@
 // (v02.9 §3.2) and backed by the Rust engine or, after a fallback, a TypeScript generator.
 // The tooling members (`makeContext`, `parseUtil`, ...) forward to a TypeScript generator and
 // return its objects: a `RuleContext.generator` there is that generator, not the facade.
-import { Engine } from "../../binding.js";
+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 } from "./countable-set.js";
+import { BoundedSet, BoundedTokenCache, CountableSet, copyCountableSet, expandInputGroups, isCountableSet, MAX_RUNTIME_CACHE_ENTRIES } from "./countable-set.js";
 import { tsNotReadyError } from "./errors.js";
-import { buildMatched, createFacadeResult, describeUnmatched, fallbackIsTokenShaped, formatUnmatchedError, toTuple } from "./result.js";
-import { translateConfig } from "./select.js";
+import { buildMatched, createFacadeResult, describeUnmatched, fallbackIsTokenShaped, formatUnmatchedError, shortcutWarningMessages, splitMatched, toTuple } from "./result.js";
+import { mergeDefinedConfig, translateConfig } from "./select.js";
 import { createCompileClassTransformer } from "./transformer.js";
 import { createTsFallback } from "./ts-fallback.js";
+const warned = new Set();
+/** Port of core/utils/warn.ts:3-12: one set per process; a message `console.warn` throws on is released. */
+function warnOnce(message) {
+    if (warned.has(message))
+        return;
+    warned.add(message);
+    try {
+        console.warn("[Teacss]", message);
+    }
+    catch (error) {
+        warned.delete(message);
+        throw error;
+    }
+}
 /** Port of core/utils/events.ts:84-112. */
 export function createNanoEvents() {
     return {
@@ -251,7 +265,15 @@ export class FacadeGenerator {
     #tsFallback;
     /** The compile-class transformer: created once and handed to every candidate (v02.9 §5.2). */
     #transformer;
-    #cache = new BoundedTokenCache();
+    /**
+     * The value of a pending `#cache` entry: `engine.parseToken` takes the compile path and fragment
+     * cache `generate` took, so it returns the utils `matchedInfo` would have carried.
+     */
+    #resolvePending = (token) => {
+        const utils = this.#backend.engine.parseToken(token);
+        return utils === null ? null : utils.map(toTuple);
+    };
+    #cache = new BoundedTokenCache(MAX_RUNTIME_CACHE_ENTRIES, this.#resolvePending);
     #blocked = new BoundedSet();
     #parentOrders = new Map();
     #activatedRules = new Set();
@@ -284,7 +306,7 @@ export class FacadeGenerator {
         const view = engine.configView();
         const own = view.standard?.compileClass === true ? [this.#transformer] : [];
         const list = uniqueNamed([...own, ...transformers]);
-        const config = createConfigView({ view, request, presets, userConfig, transformers: list, host, fallback: this.#tsFallback, engine: own.length ? engine : undefined });
+        const config = createConfigView({ view, request, presets, merged: mergeDefinedConfig(defaults, userConfig), transformers: list, host, fallback: this.#tsFallback, engine: own.length ? engine : undefined });
         this.#backend = { kind: "rust", engine, request, presets, config, transformer: this.#transformer };
     }
     get version() {
@@ -313,10 +335,11 @@ export class FacadeGenerator {
             return;
         }
         if (value instanceof BoundedTokenCache) {
+            value.resolve = this.#resolvePending;
             this.#cache = value;
             return;
         }
-        const cache = new BoundedTokenCache();
+        const cache = new BoundedTokenCache(MAX_RUNTIME_CACHE_ENTRIES, this.#resolvePending);
         for (const [token, utils] of value)
             cache.set(token, utils);
         this.#cache = cache;
@@ -418,13 +441,22 @@ export class FacadeGenerator {
         const minify = own("minify") ?? false;
         const extendedInfo = own("extendedInfo") ?? false;
         const { rustInput, countOf, collection, tokens } = this.#normalizeInput(input, own("id"), extendedInfo);
-        // Payloads are always requested: the cache stores them even when the caller did not ask.
-        const rust = backend.engine.generate(rustInput, { id: own("id"), preflights, safelist, minify, extendedInfo: true, scope: own("scope") });
+        // The whole-sheet css is not requested: `createFacadeResult` rebuilds it from `layers`.
+        const rust = backend.engine.generate(rustInput, { id: own("id"), preflights, safelist, minify, extendedInfo, scope: own("scope"), css: false });
         const config = backend.config;
-        const matched = buildMatched({ rust: extendedInfo ? rust : { ...rust, matchedInfo: null }, extendedInfo, countOf });
+        if (rust.shortcutWarnings && config.warn) {
+            // generator.ts:3600-3609: each message after an input check, before the unmatched check.
+            const warn = this.#host.core?.warnOnce ?? warnOnce;
+            for (const message of shortcutWarningMessages(rust.shortcutWarnings)) {
+                checkInput();
+                warn(message);
+            }
+        }
+        const matchedTokens = splitMatched(rust);
+        const matched = buildMatched({ rust, matched: matchedTokens, extendedInfo, countOf });
         const candidates = this.#candidates(tokens, safelist ? config.safelist : []);
-        this.#recordGeneration(rust, candidates, collection);
-        const unmatchedTokens = this.#collectUnmatched(rust, candidates, config);
+        this.#recordGeneration(rust, matchedTokens, candidates, collection);
+        const unmatchedTokens = this.#collectUnmatched(matchedTokens, candidates, config);
         let resolved;
         const resolveUnmatched = () => (resolved ??= unmatchedTokens.length ? backend.engine.diagnoseUnmatched(unmatchedTokens) : []);
         if (unmatchedTokens.length && config.unmatched === "error") {
@@ -500,32 +532,41 @@ export class FacadeGenerator {
     /**
      * v02.9 §3.7: every visited token is cached in order (a miss as `null`, a blocked one also in
      * `blocked`); a collection's matches then become the retained entries (generator.ts:2626-2630).
-     * `parentOrders` is not written: the Rust utils carry no parent order, and the oracle's
-     * Standard rules record none.
+     * A match is cached as its payload when `matchedInfo` came back and as a pending entry otherwise,
+     * so each `generate` replaces the matched entries either way. `parentOrders` is not written: the
+     * Rust utils carry no parent order, and the oracle's Standard rules record none.
      */
-    #recordGeneration(rust, candidates, collection) {
+    #recordGeneration(rust, matched, candidates, collection) {
         const engine = this.#backend.engine;
-        const payloads = new Map((rust.matchedInfo ?? []).map((info) => [info.token, info.data.map(toTuple)]));
+        const matchedSet = new Set(matched);
+        const payloads = rust.matchedInfo ? new Map(rust.matchedInfo.map((info) => [info.token, info.data.map(toTuple)])) : null;
         for (const token of candidates) {
-            const payload = payloads.get(token);
-            if (payload) {
-                if (!collection)
-                    this.#cache.set(token, payload);
+            if (matchedSet.has(token)) {
+                if (collection)
+                    continue;
+                if (payloads)
+                    this.#cache.set(token, payloads.get(token) ?? []);
+                else
+                    this.#cache.setPending(token);
                 continue;
             }
-            if (engine.isBlocked(token))
+            if (engine.isTokenBlocked(token))
                 this.#blocked.add(token);
             this.#cache.set(token, null);
         }
-        if (collection)
-            this.#cache.replaceRetained(rust.matched.map((token) => [token, payloads.get(token) ?? []]));
+        if (!collection)
+            return;
+        if (payloads)
+            this.#cache.replaceRetained(matched.map((token) => [token, payloads.get(token) ?? []]));
+        else
+            this.#cache.replaceRetainedPending(matched);
     }
     /** Token-shaped misses that no blocklist explains, in visiting order. */
-    #collectUnmatched(rust, candidates, config) {
+    #collectUnmatched(matchedTokens, candidates, config) {
         if (config.unmatched !== "warn" && config.unmatched !== "error")
             return [];
         const engine = this.#backend.engine;
-        const matched = new Set(rust.matched);
+        const matched = new Set(matchedTokens);
         const isTokenShaped = this.#host.core?.isTokenShaped ?? fallbackIsTokenShaped;
         return candidates.filter((token) => !matched.has(token) && isTokenShaped(token) && !this.#blocked.has(token) && !engine.isBlocked(token));
     }
@@ -549,7 +590,7 @@ export class FacadeGenerator {
         }
         const utils = backend.engine.parseToken(raw, alias);
         if (utils === null) {
-            if (backend.engine.isBlocked(raw)) {
+            if (backend.engine.isTokenBlocked(raw)) {
                 if (shared) {
                     this.#blocked.add(raw);
                     this.#cache.set(raw, null);

package/dist/index.d.ts

@@ -1,4 +1,8 @@
 export * from "../binding.js";
 export type * from "../contract.js";
-export * from "./facade/index.js";
+export { CONFIG_ENTRY_PROVENANCE, CONFIG_SOURCE_DECLARATIONS, ENGINE_COMPAT, ENGINE_INSTANCE, ENGINE_MATERIALIZE, ENGINE_PACKAGE_VERSION, ENGINE_STATS, PRESET_OPTIONS, } from "./constants.js";
+export { TeacssEngineError } from "./errors.js";
+export { createGenerator, engineStats, type FacadeCreateResult, FacadeGenerator, type FacadeHost, reportFallback } from "./generator.js";
+export { selectEngineRequest, type TranslateResult, translateConfig } from "./select.js";
+export { createCompileClassTransformer } from "./transformer.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,3 +1,10 @@
+// Facade modules import `Engine`, `expandClassGroups`, `splitClassTokens` and `version` from
+// `../binding.js`, never from `index.js`, which re-exports them (a cycle otherwise).
+// This file imports no peer (`@teacss/core`, `@teacss/config`).
 export * from "../binding.js";
-export * from "./facade/index.js";
+export { CONFIG_ENTRY_PROVENANCE, CONFIG_SOURCE_DECLARATIONS, ENGINE_COMPAT, ENGINE_INSTANCE, ENGINE_MATERIALIZE, ENGINE_PACKAGE_VERSION, ENGINE_STATS, PRESET_OPTIONS, } from "./constants.js";
+export { TeacssEngineError } from "./errors.js";
+export { createGenerator, engineStats, FacadeGenerator, reportFallback } from "./generator.js";
+export { selectEngineRequest, translateConfig } from "./select.js";
+export { createCompileClassTransformer } from "./transformer.js";
 //# sourceMappingURL=index.js.map

package/dist/{facade/result.d.ts → result.d.ts}

@@ -12,14 +12,28 @@ export interface RustGenerateResult {
         name: string;
         css: string;
     }>;
-    matched: string[];
+    /** The matched tokens joined with `"\0"`, `""` when none (v02.2 §3). */
+    matched: string;
     matchedInfo: Array<{
         token: string;
         data: RustUtil[];
         count: number;
     }> | null;
     programKey: string;
+    /** Present only when a shortcut left a warning (v02.2 §6.8). */
+    shortcutWarnings?: RustShortcutWarning[];
 }
+export type RustShortcutWarning = {
+    shortcut: string;
+    unmatched: string[];
+} | {
+    shortcut: string;
+    leafLimit: number;
+};
+/** The `stringifyShortcuts` warnings (generator.ts:3445) and the leaf-limit warning, in order. */
+export declare function shortcutWarningMessages(warnings: RustShortcutWarning[]): string[];
+/** `rust.matched` as the token list, split once at the boundary. */
+export declare function splitMatched(rust: RustGenerateResult): string[];
 export interface UnmatchedEntry {
     token: string;
     suggestions: string[];
@@ -31,8 +45,9 @@ export declare function uniq(items: string[]): string[];
 export declare function sortLayerNames(names: string[], configuredLayers: Record<string, number>): string[];
 /** A v02.2 `StringifiedUtil` as the oracle 7-tuple; `null` meta values are dropped. */
 export declare function toTuple(util: RustUtil): UtilTuple;
-export declare function buildMatched({ rust, extendedInfo, countOf }: {
+export declare function buildMatched({ rust, matched, extendedInfo, countOf }: {
     rust: RustGenerateResult;
+    matched: string[];
     extendedInfo: boolean;
     countOf?: (token: string, rustCount: number) => number;
 }): Set<string> | Map<string, {

package/dist/{facade/result.js → result.js}

@@ -1,4 +1,12 @@
 // The facade's `generate` result, shaped like the 0.8.2 `GenerateResult` (core/generator.ts:1540-1575).
+/** The `stringifyShortcuts` warnings (generator.ts:3445) and the leaf-limit warning, in order. */
+export function shortcutWarningMessages(warnings) {
+    return warnings.flatMap((warning) => ("unmatched" in warning ? warning.unmatched.map((member) => `unmatched utility "${member}" in shortcut "${warning.shortcut}"`) : [`shortcut "${warning.shortcut}" expands to more than ${warning.leafLimit} members (repeats included) and matches nothing`]));
+}
+/** `rust.matched` as the token list, split once at the boundary. */
+export function splitMatched(rust) {
+    return rust.matched === "" ? [] : rust.matched.split("\0");
+}
 export function uniq(items) {
     return [...new Set(items)];
 }
@@ -18,9 +26,9 @@ export function toTuple(util) {
     }
     return [util.index, util.selector ?? undefined, util.body, util.parent ?? undefined, meta, undefined, util.noMerge ?? undefined];
 }
-export function buildMatched({ rust, extendedInfo, countOf }) {
+export function buildMatched({ rust, matched, extendedInfo, countOf }) {
     if (!extendedInfo)
-        return new Set(rust.matched);
+        return new Set(matched);
     return new Map((rust.matchedInfo ?? []).map(({ token, data, count }) => [token, { data: data.map(toTuple), count: countOf ? countOf(token, count) : count }]));
 }
 export function describeUnmatched({ token, suggestions }) {

package/dist/{facade/select.d.ts → select.d.ts}

@@ -1,4 +1,4 @@
-import type { LoadProjectRequest } from "../../contract.js";
+import type { LoadProjectRequest } from "../contract.js";
 export type Failure = {
     ok: false;
     reason: string;

package/dist/{facade/transformer.d.ts → transformer.d.ts}

@@ -1,4 +1,4 @@
-import type { HighlightAnnotation, TransformResult } from "../../contract.js";
+import type { HighlightAnnotation, TransformResult } from "../contract.js";
 import { ENGINE_INSTANCE } from "./constants.js";
 interface EditTarget {
     update(start: number, end: number, text: string): unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teacss/engine",
-  "version": "0.9.0-alpha.3",
+  "version": "0.9.0",
   "description": "In-process Rust engine for TeaCSS 0.9 (napi-rs binding and 0.8.x-compatible facade)",
   "license": "MIT",
   "type": "module",
@@ -10,33 +10,31 @@
     "directory": "packages/engine"
   },
   "homepage": "https://github.com/teacss/teacss-rs/tree/master/packages/engine#readme",
-  "main": "index.js",
-  "types": "index.d.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./index.d.ts",
-      "default": "./index.js"
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     },
     "./binding": {
       "types": "./binding.d.ts",
       "default": "./binding.js"
     },
     "./facade": {
-      "types": "./dist/facade/index.d.ts",
-      "default": "./dist/facade/index.js"
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     },
     "./select": {
-      "types": "./dist/facade/select.d.ts",
-      "default": "./dist/facade/select.js"
+      "types": "./dist/select.d.ts",
+      "default": "./dist/select.js"
     },
     "./package.json": "./package.json"
   },
   "imports": {
-    "#facade/*": "./dist/facade/*"
+    "#src/*": "./dist/*"
   },
   "files": [
-    "index.js",
-    "index.d.ts",
     "contract.d.ts",
     "binding.js",
     "binding.d.ts",
@@ -74,14 +72,14 @@
     }
   },
   "optionalDependencies": {
-    "@teacss/engine-darwin-arm64": "0.9.0-alpha.3",
-    "@teacss/engine-darwin-x64": "0.9.0-alpha.3",
-    "@teacss/engine-linux-arm64-gnu": "0.9.0-alpha.3",
-    "@teacss/engine-linux-arm64-musl": "0.9.0-alpha.3",
-    "@teacss/engine-linux-x64-gnu": "0.9.0-alpha.3",
-    "@teacss/engine-linux-x64-musl": "0.9.0-alpha.3",
-    "@teacss/engine-win32-arm64-msvc": "0.9.0-alpha.3",
-    "@teacss/engine-win32-x64-msvc": "0.9.0-alpha.3"
+    "@teacss/engine-darwin-arm64": "0.9.0",
+    "@teacss/engine-darwin-x64": "0.9.0",
+    "@teacss/engine-linux-arm64-gnu": "0.9.0",
+    "@teacss/engine-linux-arm64-musl": "0.9.0",
+    "@teacss/engine-linux-x64-gnu": "0.9.0",
+    "@teacss/engine-linux-x64-musl": "0.9.0",
+    "@teacss/engine-win32-arm64-msvc": "0.9.0",
+    "@teacss/engine-win32-x64-msvc": "0.9.0"
   },
   "peerDependencies": {
     "@teacss/config": ">=0.8.5 <0.10.0 || >=0.9.0-alpha.0 <0.10.0",
@@ -112,7 +110,7 @@
     "test": "npm run build:ts && npm run check:types && node --expose-gc --test \"build/test/**/*.test.js\"",
     "check:version": "npm run build:ts && node build/scripts/sync-version.js --check",
     "check:size": "node build/scripts/size-budget.js",
-    "version": "napi version && npm run build:ts && node build/scripts/sync-version.js --write && git add npm/*/package.json ../../Cargo.toml ../../Cargo.lock",
+    "version": "napi version && npm run build:ts && node build/scripts/sync-version.js --write && git add npm/*/package.json package-lock.json ../../Cargo.toml ../../Cargo.lock ../../package-lock.json",
     "build:ts": "tsc -p tsconfig.json && tsc -p tsconfig.test.json",
     "check:types": "tsc -p test/consumer/tsconfig.json --noEmit",
     "check:publish": "node build/scripts/check-publish.js",

package/dist/facade/index.d.ts

@@ -1,6 +0,0 @@
-export { CONFIG_ENTRY_PROVENANCE, CONFIG_SOURCE_DECLARATIONS, ENGINE_COMPAT, ENGINE_INSTANCE, ENGINE_MATERIALIZE, ENGINE_PACKAGE_VERSION, ENGINE_STATS, PRESET_OPTIONS, } from "./constants.js";
-export { TeacssEngineError } from "./errors.js";
-export { createGenerator, engineStats, type FacadeCreateResult, FacadeGenerator, type FacadeHost, reportFallback } from "./generator.js";
-export { selectEngineRequest, type TranslateResult, translateConfig } from "./select.js";
-export { createCompileClassTransformer } from "./transformer.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/facade/index.js

@@ -1,9 +0,0 @@
-// Facade modules import `Engine`, `expandClassGroups`, `splitClassTokens` and `version` from
-// `../../binding.js`, never from `index.js`, which re-exports this file (a cycle otherwise).
-// This file imports no peer (`@teacss/core`, `@teacss/config`).
-export { CONFIG_ENTRY_PROVENANCE, CONFIG_SOURCE_DECLARATIONS, ENGINE_COMPAT, ENGINE_INSTANCE, ENGINE_MATERIALIZE, ENGINE_PACKAGE_VERSION, ENGINE_STATS, PRESET_OPTIONS, } from "./constants.js";
-export { TeacssEngineError } from "./errors.js";
-export { createGenerator, engineStats, FacadeGenerator, reportFallback } from "./generator.js";
-export { selectEngineRequest, translateConfig } from "./select.js";
-export { createCompileClassTransformer } from "./transformer.js";
-//# sourceMappingURL=index.js.map

package/index.d.ts

@@ -1 +0,0 @@
-export * from "./dist/index.js";

package/index.js

@@ -1,2 +0,0 @@
-export * from "./binding.js";
-export * from "./dist/facade/index.js";