@teacss/engine 0.0.0-stage → 0.8.5-alpha.1

package/README.md

@@ -1,3 +1,105 @@
-# Temporary Holding Version
+# @teacss/engine
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+## 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`.
+
+## 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 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.
+
+`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`).
+
+## 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 |
+| `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`.
+
+## Direct use of the binding
+
+```js
+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`.
+
+## 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 |
+| `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` |
+| 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 |
+
+## Verifying a release
+
+```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
+```
+
+## Development
+
+```sh
+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()))'
+```
+
+`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.

package/binding.d.ts

@@ -0,0 +1,50 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+
+/**
+ * Which binding artifact the generated loader actually loaded: `'native'` for
+ * a native addon, otherwise the `platformArchABI` of the WASI flavor. Every
+ * flavor napi-rs can build is listed, because `NAPI_RS_NATIVE_LIBRARY_PATH`
+ * can point the loader at a WASI artifact this package does not build itself.
+ */
+export declare const __napiBindingTarget: 'native' | 'wasm32-wasi' | 'wasm32-wasip1'
+
+export declare class Engine {
+  constructor()
+  inspectEntry(request: InspectEntryRequest): InspectEntryResult
+  loadProject(request: LoadProjectRequest): LoadProjectResult
+  programKey(): string
+  configView(): ResolvedConfigView
+  configFiles(): string[]
+  customThemeKeys(): string[]
+  updateModule(id: string, code: string): ModuleUpdateResult
+  removeModule(id: string): boolean
+  clearModuleDefinitions(id: string): boolean
+  moduleTokens(id: string): string[] | null
+  allTokens(): string[]
+  extract(code: string, id?: string | undefined | null): string[]
+  extractCounted(code: string, id?: string | undefined | null): Array<{ token: string; count: number }>
+  extractFiles(paths: string[]): ExtractFileResult[]
+  transformSource(id: string, code: string): TransformResult | null
+  transformStylesheet(id: string, code: string): TransformResult | null
+  generate(input: GenerateInput, options?: GenerateOptions | undefined | null): GenerateResult
+  parseToken(raw: string, alias?: string | undefined | null): StringifiedUtil[] | null
+  isBlocked(raw: string): boolean
+  diagnoseUnmatched(tokens: string[]): UnmatchedDiagnostic[]
+  themeValue(path: string): string | null
+  dispose(): void
+}
+
+export declare function diagnoseCustom(css: string, themeKeys: string[]): CustomDiagnostic[]
+
+export declare function diagnoseEntry(css: string): EntryDiagnostic[]
+
+export declare function expandClassGroups(code: string): string
+
+export declare function hash(input: string): string
+
+export declare function parseEntry(css: string, file?: string | undefined | null): EntryConfig
+
+export declare function splitClassTokens(body: string): string[]
+
+export declare function version(): string