@teacss/engine 0.9.3 → 0.10.2

package/LICENSE

@@ -0,0 +1,22 @@
+# MIT License
+
+Copyright (c) 2021-PRESENT Anthony Fu <https://github.com/antfu>
+Copyright (c) 2026-PRESENT Billgo <hi@billgo.me>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,94 +2,28 @@
 
 ## What this package is
 
-`@teacss/engine` is the in-process Rust engine for TeaCSS 0.9: a napi-rs binding plus a facade that mirrors the 0.8.x `TeacssGenerator` API, so the TypeScript integrations can hand a build to Rust and get byte-identical CSS back. You do not install it yourself. The teacss-ts 0.9 integration packages (`@teacss/vite`, `@teacss/rsbuild` and the others) depend on it, and npm installs the platform package that matches your machine through `optionalDependencies`. Each `@teacss/engine@0.9.N` is paired with `@teacss/core@0.9.N`.
+`@teacss/engine` is the in-process Rust engine for TeaCSS: a napi-rs binding, the contract types (`contract.d.ts`) and the project helper (`createProject`) that the shells published from this repository (`@teacss/vite`, `@teacss/astro`, `@teacss/rsbuild`, `@teacss/bun`, `@teacss/postcss`, `@teacss/inspector`) and the `teacss` command share. You do not install it yourself. The shells depend on it, and npm installs the platform package that matches your machine through `optionalDependencies`.
 
 ## Supported platforms
 
-| Package | os / cpu / libc | Status | Minimum |
-| --- | --- | --- | --- |
-| @teacss/engine-darwin-arm64 | darwin / arm64 / - | required | macOS 11.0 |
-| @teacss/engine-darwin-x64 | darwin / x64 / - | required | macOS 11.0 |
-| @teacss/engine-linux-x64-gnu | linux / x64 / glibc | required | glibc 2.17 |
-| @teacss/engine-linux-x64-musl | linux / x64 / musl | required | - |
-| @teacss/engine-linux-arm64-gnu | linux / arm64 / glibc | required | glibc 2.17 |
-| @teacss/engine-linux-arm64-musl | linux / arm64 / musl | optional | - |
-| @teacss/engine-win32-x64-msvc | win32 / x64 / - | required | - |
-| @teacss/engine-win32-arm64-msvc | win32 / arm64 / - | optional | - |
-| @teacss/engine-wasm32-wasi | - / - / - | optional | - |
-
-Every package needs Node.js 22.12.0 or later; the wasm package needs `>=22.13.0 <23.0.0-0 || >=23.5.0`. A required platform blocks a release when it fails to build or test; an optional one is published later if it fails. The wasm fallback runs on any host, so it is not in `optionalDependencies` and is never installed by default. Install it explicitly with `npm i @teacss/engine-wasm32-wasi` when no native package fits your platform.
-
-## Engine selection
-
-- `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"` (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 |
-| --- | --- | --- | --- |
-| 0.9.0-alpha.3 | 0.9.0-alpha.3 | `>=0.9.0-alpha.0 <0.10.0` | Paired; selected by `defaultMode` |
-| 0.9.1 | 0.9.0 | `>=0.9.0 <0.10.0` | Allowed; the comparison baseline may lag one 0.8.x release, and diagnostics print `oracle.teacssTs` |
-| 0.10.0 | 0.9.4 | `>=0.9.0 <0.10.0` | Falls back to TypeScript with `engine-compat` |
-| 0.8.2 | any 0.9.x | - | 0.8.2 has no engine hook, so the engine is never loaded |
-
-The teacss-ts version this release is compared against is `package.json#engineCompat.oracle`.
+| Rust target | Package | os / cpu / libc | Status | Minimum |
+| --- | --- | --- | --- | --- |
+| `aarch64-apple-darwin` | @teacss/engine-darwin-arm64 | darwin / arm64 / - | required | macOS 11.0 |
+| `x86_64-apple-darwin` | @teacss/engine-darwin-x64 | darwin / x64 / - | required | macOS 11.0 |
+| `x86_64-unknown-linux-gnu` | @teacss/engine-linux-x64-gnu | linux / x64 / glibc | required | glibc 2.17 |
+| `x86_64-unknown-linux-musl` | @teacss/engine-linux-x64-musl | linux / x64 / musl | required | - |
+| `aarch64-unknown-linux-gnu` | @teacss/engine-linux-arm64-gnu | linux / arm64 / glibc | required | glibc 2.17 |
+| `aarch64-unknown-linux-musl` | @teacss/engine-linux-arm64-musl | linux / arm64 / musl | optional | - |
+| `x86_64-pc-windows-msvc` | @teacss/engine-win32-x64-msvc | win32 / x64 / - | required | - |
+| `aarch64-pc-windows-msvc` | @teacss/engine-win32-arm64-msvc | win32 / arm64 / - | optional | - |
+
+Every package needs Node.js 26 or later. A required platform blocks a release when it fails to build or test; an optional one is published later if it fails.
+
+A platform outside this matrix has no fallback: there is no wasm package, and the TypeScript engine is the only alternative. To run the Rust engine there, build it yourself from this repository with `cargo build -p teacss-napi --release`, rename the cdylib in `target/release/` to `teacss-engine.<os>-<cpu>[-<libc>].node` (the name the loader derives for your host, for example `teacss-engine.linux-riscv64-gnu.node`), and place it in `packages/engine/` next to `binding.js`. The loader tries that file before any platform package.
+
+## Configuration
+
+Configuration comes only from the CSS entry (`@presets`, `@source`, `@shortcut`, `@safelist`, `@custom` and the role directives such as `@primary`; see [the CSS entry](https://github.com/teacss/teacss-rs/blob/master/skills/teacss/references/setup.md#css-entry)) plus a shell's `ShellOptions`, a small static object (`root`, `entry`, `inline`, `envMode`, `unmatched`, `outputToCssLayers`, `shortcutsLayer`, `presetOptions`, `minify`) that maps onto `LoadProjectFromRootRequest`. [Build integrations](https://github.com/teacss/teacss-rs/blob/master/skills/teacss/references/integrations.md#options) describes each option and the options a shell adds on top. There is no `UserConfig`, no preset object and no translation layer: a key the request does not know is `E_INVALID_ARGUMENT`, and the one remaining unsupported case is an `@presets` name that is not `standard`, `official` or `icons`, which `loadProjectFromRoot` reports as `E_UNSUPPORTED` with `details.reason` `preset-not-builtin` and `details.path` `@presets[<i>]`. A project that needs JavaScript rules, variants or hooks runs on the TypeScript ecosystem (teacss-ts), which this package does not load.
 
 ## Direct use of the binding
 
@@ -97,29 +31,29 @@ The teacss-ts version this release is compared against is `package.json#engineCo
 import { Engine, version } from "@teacss/engine/binding";
 ```
 
-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`.
+The types are in `binding.d.ts`. The binding is a tooling-level API and is not part of the stability promise; integrations go through the package root (`createProject` and the contract types).
 
 ## Troubleshooting
 
 | Symptom | Cause | Fix |
 | --- | --- | --- |
 | `Failed to load native binding`, and the detail lists `Cannot find module '@teacss/engine-linux-x64-gnu'` | Optional dependencies were skipped at install time (`--omit=optional`, `--no-optional`, or a CI cache holding another platform's `node_modules`) | Run `npm ci` again without the omit, or install `@teacss/engine-<platform>` explicitly; pnpm users check `supportedArchitectures` |
-| The same, but on Alpine with the detail trying a `-gnu` package | musl detection failed: gcompat makes `process.report.getReport()` report a glibc version, so the loader picked the gnu package | Remove gcompat, or install `@teacss/engine-linux-x64-musl` explicitly and set `TEACSS_ENGINE=rust` to see the detail; if that does not help, set `NAPI_RS_FORCE_WASI=1` with the wasm package installed and report the detection case to napi-rs |
+| The same, but on Alpine with the detail trying a `-gnu` package | musl detection failed: gcompat makes `process.report.getReport()` report a glibc version, so the loader picked the gnu package | Remove gcompat, or install `@teacss/engine-linux-x64-musl` explicitly; if that does not help, report the detection case to napi-rs |
 | `Module did not self-register` or a `NODE_MODULE_VERSION` mismatch | Cannot happen with a Node-API binary; it means the loaded `.node` is not this package's (for example an Electron with a Node-API version below 9, or an old Bun) | Upgrade the runtime |
-| `dlopen` reports `GLIBC_2.xx not found` | glibc is older than the 2.17 build baseline | Not supported; use the wasm fallback or `TEACSS_ENGINE=ts` |
+| `dlopen` reports `GLIBC_2.xx not found` | glibc is older than the 2.17 build baseline | Not supported; build the binding yourself (see [Supported platforms](#supported-platforms)) |
 | macOS reports "code signature invalid" | The `.node` was copied from outside npm and carries the quarantine attribute | `xattr -d com.apple.quarantine <file>`; files installed by npm do not carry it |
-| `TEACSS_ENGINE=rust` throws instead of falling back | Expected: `rust` never falls back | Use `auto`, or fix the load problem |
-| An `engine-compat` fallback | `@teacss/core` and `@teacss/engine` are not a matching pair | Align the two versions; check the lockfile for more than one `@teacss/engine` |
-| teacss-ts still uses TypeScript after a local `build:debug` | `bun link` points at an old directory, or `node_modules/@teacss/engine` is a registry copy | Check with `ls -l node_modules/@teacss/engine` that it is a symlink |
+| A shell in this repository does not pick up a local `build:debug` | Its `node_modules/@teacss/engine` is a registry copy instead of the `file:../engine` link | `npm --prefix packages/<shell> ci` and check with `ls -l packages/<shell>/node_modules/@teacss/engine` that it is a symlink |
 
 ## Verifying a release
 
+Every GitHub release carries `SHA256SUMS` over the `.node` files, the `teacss` binaries and the npm tarballs:
+
 ```sh
 shasum -a 256 -c SHA256SUMS            # Linux: sha256sum -c SHA256SUMS
-npm view @teacss/engine --json | jq .dist.attestations
-gh attestation verify teacss-engine.<platform>.node --owner teacss
 ```
 
+Releases carry no npm provenance or GitHub attestation (v02.11 §1.3).
+
 ## Development
 
 ```sh
@@ -132,19 +66,4 @@ node -e 'import("./packages/engine/dist/index.js").then(m => console.log(m.versi
 
 `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.
 
-To try a local build inside a teacss-ts checkout (bun 1.4.3 workspaces), link it one of two ways, preferring the first:
-
-```sh
-# A: bun link (preferred)
-cd /path/to/teacss-rs/packages/engine && bun link
-cd /path/to/teacss-ts && bun link @teacss/engine
-TEACSS_ENGINE=rust bun test packages-engine/core
-```
-
-```sh
-# B: file: override (temporary; revert with git checkout package.json bun.lock)
-cd /path/to/teacss-ts
-bun add --dev @teacss/engine@file:../teacss-rs/packages/engine
-```
-
-Either way the loader finds the `.node` next to `binding.js` first, so no platform package is needed. After a Rust change, run `build:debug` again; there is no need to link again.
+The shells in this repository (`packages/{vite,astro,rsbuild,bun,postcss,inspector}`) depend on `@teacss/engine` through `file:../engine`, so `npm --prefix packages/<shell> ci` links them to this directory and they use the local build; the loader finds the `.node` next to `binding.js` first, so no platform package is needed. After a Rust change, run `build:debug` again.

package/binding-header.d.ts

@@ -6,17 +6,26 @@ import type {
   EntryConfig,
   EntryDiagnostic,
   ExtractFileResult,
+  ExtractFilesUnionResult,
   GenerateInput,
   GenerateOptions,
   GenerateResult,
+  IconifyJson,
   InspectEntryRequest,
   InspectEntryResult,
+  LoadProjectFromRootRequest,
+  LoadProjectFromRootResult,
   LoadProjectRequest,
   LoadProjectResult,
+  MatchedPosition,
   ModuleUpdateResult,
+  OutputToCssLayersOptions,
   ResolvedConfigView,
   RuleInfo,
   StringifiedUtil,
+  Suggestion,
+  SuggestOptions,
+  TokenInfo,
   TransformResult,
   UnmatchedDiagnostic,
   VariantInfo,

package/binding.d.ts

@@ -6,17 +6,26 @@ import type {
   EntryConfig,
   EntryDiagnostic,
   ExtractFileResult,
+  ExtractFilesUnionResult,
   GenerateInput,
   GenerateOptions,
   GenerateResult,
+  IconifyJson,
   InspectEntryRequest,
   InspectEntryResult,
+  LoadProjectFromRootRequest,
+  LoadProjectFromRootResult,
   LoadProjectRequest,
   LoadProjectResult,
+  MatchedPosition,
   ModuleUpdateResult,
+  OutputToCssLayersOptions,
   ResolvedConfigView,
   RuleInfo,
   StringifiedUtil,
+  Suggestion,
+  SuggestOptions,
+  TokenInfo,
   TransformResult,
   UnmatchedDiagnostic,
   VariantInfo,
@@ -34,13 +43,16 @@ export declare class Engine {
   constructor()
   inspectEntry(request: InspectEntryRequest): InspectEntryResult
   loadProject(request: LoadProjectRequest): LoadProjectResult
+  loadProjectFromRoot(request: LoadProjectFromRootRequest): LoadProjectFromRootResult
   programKey(): string
   configView(): ResolvedConfigView
   rules(): RuleInfo[]
   variants(): VariantInfo[]
   configFiles(): string[]
+  missingImports(): string[]
   customThemeKeys(): string[]
   updateModule(id: string, code: string): ModuleUpdateResult
+  updateModules(ids: string[], codes: string[]): ModuleUpdateResult[]
   removeModule(id: string): boolean
   clearModuleDefinitions(id: string): boolean
   compileClassShortcuts(): Array<[string, string] | [string, string, { layer: string }]>
@@ -49,6 +61,7 @@ export declare class Engine {
   extract(code: string, id?: string | undefined | null): string[]
   extractCounted(code: string, id?: string | undefined | null): Array<{ token: string; count: number }>
   extractFiles(paths: string[]): ExtractFileResult[]
+  extractFilesUnion(paths: string[]): ExtractFilesUnionResult
   transformSource(id: string, code: string): TransformResult | null
   transformStylesheet(id: string, code: string): TransformResult | null
   generate(input: GenerateInput, options?: GenerateOptions | undefined | null): GenerateResult
@@ -57,6 +70,11 @@ export declare class Engine {
   isTokenBlocked(raw: string): boolean
   diagnoseUnmatched(tokens: string[]): UnmatchedDiagnostic[]
   themeValue(path: string): string | null
+  suggest(input: string, options?: SuggestOptions | undefined | null): Suggestion[]
+  tokenInfo(token: string): TokenInfo | null
+  matchedPositions(id: string, code: string): MatchedPosition[]
+  equivalentTokens(token: string): string[]
+  parentOrders(): Array<[string, number]>
   stats(): EngineStats
   dispose(): void
 }
@@ -69,6 +87,17 @@ export declare function expandClassGroups(code: string): string
 
 export declare function hash(input: string): string
 
+export declare function markers(): Markers
+
+/** The scanner's marker strings (v10.2 §2.3), so the shells read them from one place. */
+export interface Markers {
+  cssPlaceholder: string
+  includeComment: string
+  ignoreComment: string
+  skipStartComment: string
+  skipEndComment: string
+}
+
 export declare function parseEntry(css: string, file?: string | undefined | null): EntryConfig
 
 export declare function splitClassTokens(body: string): string[]