@tenphi/tasty 0.0.0-snapshot.1d29633 → 0.0.0-snapshot.1f1c00a

package/docs/migration-v3.md

@@ -21,30 +21,30 @@ Most of the work is mechanical renames — see the [search-and-replace cheat she
 
 ## At a glance
 
-| v2.11 | v3.0 | Find it with |
-|---|---|---|
-| `'@properties': { … }` | `'@property': { … }` | `rg "'@properties'"` |
-| `'@fontFace': { … }` | `'@font-face': { … }` | `rg "'@fontFace'"` |
-| `'@counterStyle': { … }` | `'@counter-style': { … }` | `rg "'@counterStyle'"` |
-| `padding: '2x 4x top right'` | `padding: '2x top, 4x right'` | dev-mode console warning |
-| `fade: '3x 1x top bottom'` | `fade: '3x top, 1x bottom'` | dev-mode console warning |
-| `configure({ funcs })` | `configure({ functions })` | `rg "funcs"` |
-| `configure({ fontFace })` | `configure({ fontFaces })` | `rg "fontFace:"` |
-| `configure({ counterStyle })` | `configure({ counterStyles })` | `rg "counterStyle:"` |
-| `getCssText()` | `getCSSText()` | `rg "getCssText"` |
-| `getCssTextForNode()` | `getCSSTextForNode()` | `rg "getCssTextForNode"` |
-| `getCssTextForClasses()` | `getCSSTextForClasses()` | `rg "getCssTextForClasses"` |
-| `getGlobalFontFace()` | `getGlobalFontFaces()` | `rg "getGlobalFontFace\b"` |
-| `getGlobalCounterStyle()` | `getGlobalCounterStyles()` | `rg "getGlobalCounterStyle\b"` |
-| `getGlobalFunction()` | `getGlobalFunctions()` | `rg "getGlobalFunction\b"` |
-| `okhslFunc` / `okhstFunc` | `okhslFunction` / `okhstFunction` | `rg "okhs[lt]Func\b"` |
-| `CssOptions` | `CSSOptions` | `rg "CssOptions"` |
-| `ParserOptions.funcs` | `ParserOptions.functions` | `rg "funcs:"` |
-| `StyleParser#setFuncs()` | `StyleParser#setFunctions()` | `rg "setFuncs"` |
-| `ChunkInfo` (from `tastyDebug`) | `DebugChunkInfo` | `rg "ChunkInfo"` |
-| `@tenphi/tasty/next` | `@tenphi/tasty/zero/next` | `rg "tasty/next"` |
-| `getIsTestEnvironment()` | `isTestEnvironment()` | `rg "getIsTestEnvironment"` |
-| `hydrateTastyCache()` | `hydrateTastyClasses()` | `rg "hydrateTastyCache"` |
+| v2.11                           | v3.0                              | Find it with                   |
+| ------------------------------- | --------------------------------- | ------------------------------ |
+| `'@properties': { … }`          | `'@property': { … }`              | `rg "'@properties'"`           |
+| `'@fontFace': { … }`            | `'@font-face': { … }`             | `rg "'@fontFace'"`             |
+| `'@counterStyle': { … }`        | `'@counter-style': { … }`         | `rg "'@counterStyle'"`         |
+| `padding: '2x 4x top right'`    | `padding: '2x top, 4x right'`     | dev-mode console warning       |
+| `fade: '3x 1x top bottom'`      | `fade: '3x top, 1x bottom'`       | dev-mode console warning       |
+| `configure({ funcs })`          | `configure({ functions })`        | `rg "funcs"`                   |
+| `configure({ fontFace })`       | `configure({ fontFaces })`        | `rg "fontFace:"`               |
+| `configure({ counterStyle })`   | `configure({ counterStyles })`    | `rg "counterStyle:"`           |
+| `getCssText()`                  | `getCSSText()`                    | `rg "getCssText"`              |
+| `getCssTextForNode()`           | `getCSSTextForNode()`             | `rg "getCssTextForNode"`       |
+| `getCssTextForClasses()`        | `getCSSTextForClasses()`          | `rg "getCssTextForClasses"`    |
+| `getGlobalFontFace()`           | `getGlobalFontFaces()`            | `rg "getGlobalFontFace\b"`     |
+| `getGlobalCounterStyle()`       | `getGlobalCounterStyles()`        | `rg "getGlobalCounterStyle\b"` |
+| `getGlobalFunction()`           | `getGlobalFunctions()`            | `rg "getGlobalFunction\b"`     |
+| `okhslFunc` / `okhstFunc`       | `okhslFunction` / `okhstFunction` | `rg "okhs[lt]Func\b"`          |
+| `CssOptions`                    | `CSSOptions`                      | `rg "CssOptions"`              |
+| `ParserOptions.funcs`           | `ParserOptions.functions`         | `rg "funcs:"`                  |
+| `StyleParser#setFuncs()`        | `StyleParser#setFunctions()`      | `rg "setFuncs"`                |
+| `ChunkInfo` (from `tastyDebug`) | `DebugChunkInfo`                  | `rg "ChunkInfo"`               |
+| `@tenphi/tasty/next`            | `@tenphi/tasty/zero/next`         | `rg "tasty/next"`              |
+| `getIsTestEnvironment()`        | `isTestEnvironment()`             | `rg "getIsTestEnvironment"`    |
+| `hydrateTastyCache()`           | `hydrateTastyClasses()`           | `rg "hydrateTastyCache"`       |
 
 ---
 
@@ -73,7 +73,7 @@ At-rule keys now match the real CSS at-rule names Tasty already emits, so they a
 
 **This is the one change that can alter rendered CSS without a rename.** A style group that names direction modifiers now takes a **single** value, applied to every direction it names.
 
-The old form looked positional but never was: the parser buckets values and modifiers into separate arrays per comma group, so `'2x 4x top right'`, `'2x top 4x right'`, and `'top 2x right 4x'` were all the same input, and the pairing was decided by the order the *modifiers* happened to appear in. `'1x 2x right top'` and `'1x 2x top right'` produced different CSS, and `'1x 2x top top'` silently assigned `top` twice.
+The old form looked positional but never was: the parser buckets values and modifiers into separate arrays per comma group, so `'2x 4x top right'`, `'2x top 4x right'`, and `'top 2x right 4x'` were all the same input, and the pairing was decided by the order the _modifiers_ happened to appear in. `'1x 2x right top'` and `'1x 2x top right'` produced different CSS, and `'1x 2x top top'` silently assigned `top` twice.
 
 Per-side values now come from comma-separated groups:
 
@@ -155,25 +155,25 @@ A key whose prefix doesn't match its value type is ignored with a development wa
 
 ## 5. Removed exports
 
-| Removed | Use instead |
-|---|---|
-| `getIsTestEnvironment()` | `isTestEnvironment()` |
-| `hydrateTastyCache()` | `hydrateTastyClasses()` |
-| `customFunc()` | `configure({ functions })` |
-| `getGlobalFuncs()` | `getGlobalFunctions()` for `@function` definitions; the parse-function registry is internal |
-| `resetGlobalFuncs()` | `resetConfig()` |
-| `setGlobalPredefinedTokens()` | `configure({ replaceTokens })` |
-| `resetGlobalPredefinedTokens()` | `resetConfig()` |
-| `setMiddlewareTransferCache()` / `getMiddlewareTransferCache()` | internal; no replacement needed |
-| `clearWriterCache()` | internal test utility |
-| `DEFAULT_PLUGINS` | nothing — it was never consumed, and passing it to `configure({ plugins })` was a no-op. The default `okhsl`/`okhst` functions are registered automatically. |
-| `registerDefaultFunctions()` | internal bootstrap helper |
-| `warn()` / `deprecationWarning()` | internal helpers with no callers |
-| `Bucket` enum | parser-internal |
-| `Props` type | inline `Record<string, any>` |
-| `UseStylesOptions` | `useStyles()` takes `Styles \| undefined` directly |
-| `GlobalStyledProps` | its only member was the already-dead `breakpoints` prop |
-| duplicate `PropertyOptions` | the single `PropertyOptions` from `injector/types` |
+| Removed                                                         | Use instead                                                                                                                                                  |
+| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `getIsTestEnvironment()`                                        | `isTestEnvironment()`                                                                                                                                        |
+| `hydrateTastyCache()`                                           | `hydrateTastyClasses()`                                                                                                                                      |
+| `customFunc()`                                                  | `configure({ functions })`                                                                                                                                   |
+| `getGlobalFuncs()`                                              | `getGlobalFunctions()` for `@function` definitions; the parse-function registry is internal                                                                  |
+| `resetGlobalFuncs()`                                            | `resetConfig()`                                                                                                                                              |
+| `setGlobalPredefinedTokens()`                                   | `configure({ replaceTokens })`                                                                                                                               |
+| `resetGlobalPredefinedTokens()`                                 | `resetConfig()`                                                                                                                                              |
+| `setMiddlewareTransferCache()` / `getMiddlewareTransferCache()` | internal; no replacement needed                                                                                                                              |
+| `clearWriterCache()`                                            | internal test utility                                                                                                                                        |
+| `DEFAULT_PLUGINS`                                               | nothing — it was never consumed, and passing it to `configure({ plugins })` was a no-op. The default `okhsl`/`okhst` functions are registered automatically. |
+| `registerDefaultFunctions()`                                    | internal bootstrap helper                                                                                                                                    |
+| `warn()` / `deprecationWarning()`                               | internal helpers with no callers                                                                                                                             |
+| `Bucket` enum                                                   | parser-internal                                                                                                                                              |
+| `Props` type                                                    | inline `Record<string, any>`                                                                                                                                 |
+| `UseStylesOptions`                                              | `useStyles()` takes `Styles \| undefined` directly                                                                                                           |
+| `GlobalStyledProps`                                             | its only member was the already-dead `breakpoints` prop                                                                                                      |
+| duplicate `PropertyOptions`                                     | the single `PropertyOptions` from `injector/types`                                                                                                           |
 
 `getGlobalFuncs()` deserves a note: it returned the **live mutable internal registry**, and writing to it bypassed the parser's cache invalidation, so the write silently never took effect. If you were mutating it, move to `configure({ functions })`.
 
@@ -192,13 +192,13 @@ A key whose prefix doesn't match its value type is ignored with a development wa
 + import { withTasty } from '@tenphi/tasty/zero/next';
 ```
 
-The zero-runtime Next.js wrapper already lived under the `zero` namespace internally; the top-level `/next` path collided confusingly with `@tenphi/tasty/ssr/next`, which is a different integration.
+The build-time extraction Next.js wrapper already lived under the `zero` namespace internally; the top-level `/next` path collided confusingly with `@tenphi/tasty/ssr/next`, which is a different integration.
 
 ---
 
 ## 8. Behavior changes that are not renames
 
-**Repeated `configure()` calls now merge.** `recipes`, `keyframes`, `properties`, `fontFaces`, `counterStyles`, and CSS `@function` definitions used to replace wholesale, so a design-system `configure()` followed by an application `configure()` silently dropped the design system's values. All of them now merge, with the later call winning on a key conflict — matching `tokens` and `globalStyles`, which already merged. If you were relying on a second call to *clear* a collection, use `resetConfig()`.
+**Repeated `configure()` calls now merge.** `recipes`, `keyframes`, `properties`, `fontFaces`, `counterStyles`, and CSS `@function` definitions used to replace wholesale, so a design-system `configure()` followed by an application `configure()` silently dropped the design system's values. All of them now merge, with the later call winning on a key conflict — matching `tokens` and `globalStyles`, which already merged. If you were relying on a second call to _clear_ a collection, use `resetConfig()`.
 
 `configure({ polyfills })` is now correctly rejected after the first render, like every sibling option, and shallow-merges so an unrelated later call cannot switch a polyfill off.
 
@@ -208,7 +208,7 @@ The zero-runtime Next.js wrapper already lived under the `zero` namespace intern
 
 **Replacing a built-in style handler now warns.** Built-in handlers are shared across style names, so `configure({ handlers: { fill } })` also takes over `image` and the whole `background-*` family, and `configure({ handlers: { display } })` takes down `flow`, `gap`, `hide`, `overflow`, `whiteSpace`, and `textOverflow`. This was always true; what's new is that a development-mode warning now names exactly what was displaced. If you see it, either declare the whole group and delegate the rest to `styleHandlers.*`, or pick a narrower name. See [Plugins](plugins.md#custom-style-handlers).
 
-**Multi-dependency custom handlers are fixed.** A handler whose dependencies mixed known and unknown style names was invoked once per chunk with only *part* of its dependencies, and could emit stale CSS. Unknown names now join their handler's chunk, so it is invoked once with all of them. No built-in style moved, so no existing class name changes.
+**Multi-dependency custom handlers are fixed.** A handler whose dependencies mixed known and unknown style names was invoked once per chunk with only _part_ of its dependencies, and could emit stale CSS. Unknown names now join their handler's chunk, so it is invoked once with all of them. No built-in style moved, so no existing class name changes.
 
 **`isChecked` added to the root prop types.** It already worked at runtime; it was just missing from `BaseProps` / `AllBaseProps`.
 
@@ -220,7 +220,7 @@ The zero-runtime Next.js wrapper already lived under the `zero` namespace intern
 
 Nothing here is required to upgrade.
 
-- **CSS `@function` support** — reusable, parameterized functions via the `'@function'` styles key, the `useFunction` style function, or `configure({ functions })`. Works across client, SSR/RSC, and zero-runtime. `configure({ polyfills: { functions: true } })` inlines every call into plain CSS for browsers that don't ship the at-rule yet. See [Style DSL](dsl.md#functions-function).
+- **CSS `@function` support** — reusable, parameterized functions via the `'@function'` styles key, the `useFunction` style function, or `configure({ functions })`. Works across client rendering, SSR/RSC, and build-time extraction. `configure({ polyfills: { functions: true } })` inlines every call into plain CSS for browsers that don't ship the at-rule yet. See [Style DSL](dsl.md#functions-function).
 - **Custom color plugins with no core special-casing** — `okhsl`/`okhst` are now ordinary one-line plugins, and a third-party color space can achieve identical integration. New `createColorFunc` and `resolveFunctionColor` helpers.
 - **`configure({ propHandlers })`** — props middleware for every component: props in, props out. The extension point for props that aren't style values.
 - **`configure({ baseStyleProps })`** — expose style properties as props on every component without listing them in each `styleProps`.
@@ -279,7 +279,7 @@ Worth stating explicitly, because it's easy to assume otherwise:
 
 - **At-rule styles-object keys are CSS-spec-faithful, not JS-conventional.** `@keyframes`, `@property`, `@font-face`, `@counter-style`, `@function`, `@starting` — kebab-case, matching what Tasty emits.
 - **The `func()` injector method stays abbreviated.** `function` is a reserved word.
-- `injector.fontFace()` and `injector.counterStyle()` keep their singular names — only the *config keys* and *getters* were pluralized.
+- `injector.fontFace()` and `injector.counterStyle()` keep their singular names — only the _config keys_ and _getters_ were pluralized.
 - `useFontFace` and `useCounterStyle` are unchanged.
 - `configure({ properties })` and `autoPropertyTypes` are unchanged; only the styles-object `@property` key was renamed.
 - **The deprecated style aliases are retained deliberately.** `backgroundColor`, `background`, `backgroundImage`, `flex`, `grid`, and `flexDirection` still carry `@deprecated` tags and still work. They are the guardrail that discourages their use in projects that have not enabled `@tenphi/eslint-plugin-tasty` yet — read the tags as guidance, not as a removal notice.

package/docs/pipeline.md

@@ -86,18 +86,22 @@ Output: CSSRule[]
 
 ### What It Does
 
-Runs on each style's value map **before** any parsing. If a compound AND state key shares a value with the "atom absent" variant, the atom is a don't-care and every key is simplified by dropping it. Duplicate keys collapse.
+Runs on each style's value map **before** any parsing, when the map has at least three keys and one of them uses `&`. An atom is a **don't-care** when flipping it never changes which value the map resolves to; every key that mentions a don't-care atom is dropped.
 
 ### How It Works
 
-1. Gather the unique set of top-level AND atoms across all keys.
-2. An atom is **redundant** when every entry that contains it has a same-value partner with the atom absent and the rest of the atoms identical.
-3. Keys containing `|`, `^`, or `,` at top level are treated as opaque single atoms (they don't participate in atom-level extraction).
-4. Drop redundant atoms from every key; collapse duplicates.
+1. Split each key into its top-level `&` atoms. Keys containing `|`, `^`, or `,` at top level are a single opaque atom. The `_` floor (and a misused `_` key) is kept verbatim and left out of the analysis.
+2. Treat the map as the cascade it is: the last authored key whose atoms all hold wins, and `''` is always the lowest priority.
+3. An atom is a don't-care when, in every state, the cascade resolves to the same value with the atom present as with it absent. Only the states `(K₁ minus the atom) ∪ K₀`, for every key `K₁` that contains the atom and every key `K₀` that does not (or none), can tell the two apart, so the check is quadratic in the number of keys rather than exponential in atoms.
+4. Drop every key that contains a don't-care atom. With the atom forced absent those keys never match, and by definition the result is unchanged.
+
+The check is over the cascade, not over pairs of keys. In `{ '': A, checked: B, 'invalid & checked': C, disabled: A }`, `disabled` has the default's value, but it outranks `checked`: a checked, disabled element gets `A`, so `disabled` is not a don't-care. (An earlier pairwise rule — "every key with the atom has a same-value partner without it" — folded `disabled` into `''` here and lost that priority.)
+
+Atoms are compared as strings and treated as independent. Real atoms can be related (`theme=dark` vs `theme=light`, nested media ranges); that only rules states out, so a don't-care over independent atoms is one for every real state too. Two guards keep the rewrite safe: a map with more than 32 distinct atoms is left unreduced, and a reduction that would leave the `_` floor alone with `''` (which means "use the floor", see Stage 1) is skipped.
 
 ### Why
 
-Removing don't-care dimensions before parsing prevents combinatorial blowup in later stages. `mergeEntriesByValue`, `buildExclusiveConditions`, and materialization all see fewer entries and fewer spurious conditions. Implemented as part of the Apr 2026 fix for overlapping CSS rules (commit 7cd9dbe).
+Removing don't-care dimensions before parsing prevents combinatorial blowup in later stages. `mergeEntriesByValue`, `buildExclusiveConditions`, and materialization all see fewer entries and fewer spurious conditions.
 
 ### Example
 
@@ -197,6 +201,8 @@ The merge is safe iff for every entry `e_m` strictly between them in priority wi
 
 i.e. there is no scenario where the intermediate state could have matched, the lower same-value entry would also have matched, and the higher one would not. This is the only way the merge could leak through and shadow the intermediate state.
 
+An intermediate whose condition always holds (a tautological key, or same-value keys that already merged into one, like `beta | !beta`) is checked like any other. Only the `''` default and the `_` floor are exempt from the check, and they are always the lowest priorities, so they are never intermediates.
+
 ### Why
 
 Without this pass a value map like `{ '@dark': 'red', '@dark & @hc': 'red' }` would create two separate entries that later produce two CSS rules with identical output. Merging before exclusive building keeps the exclusive condition algebra small and avoids duplicate CSS. The safety check ensures we never break the cascade in service of this optimization.
@@ -293,7 +299,9 @@ B: B & !A               (applies only when A doesn't)
 C: C & !A & !B          (applies only when neither A nor B)
 ```
 
-Each exclusive condition is passed through `simplifyCondition`. Entries that simplify to `FALSE` (impossible) are filtered out. The default state (`''` → `TrueCondition`) is not added to the “prior” list for negation (see `buildExclusiveConditions`).
+Each exclusive condition is passed through `simplifyCondition`. Entries that simplify to `FALSE` (impossible) are filtered out.
+
+Every entry is added to the "prior" list, including one whose condition is `TRUE`. That can be a tautological key, or same-value keys that merged into one in Stage 1b (`alpha: X, '!alpha': X` → `TRUE`). Such an entry always applies at its priority, so negating it correctly makes every lower entry `FALSE`. The bare `''` default is `TRUE` too, but it is always the lowest priority, so no entry comes after it.
 
 ### `_` fallback floor
 
@@ -383,7 +391,7 @@ The pre-build Stage 2a pass doesn't need this because user-authored ORs aren't p
 
 ### Example (conceptual)
 
-See the comment block in `exclusive.ts:500-523`: a default value whose higher-priority sibling is `@supports(...) & :has(...)` gets an exclusive of `!@supports | !:has`. Expansion yields one branch under `@supports (not ...)` and another under `@supports (...) { :not(:has()) }` instead of a bare `:not(:has())` rule.
+See the comment block on `expandExclusiveOrs` in `exclusive.ts`: a default value whose higher-priority sibling is `@supports(...) & :has(...)` gets an exclusive of `!@supports | !:has`. Expansion yields one branch under `@supports (not ...)` and another under `@supports (...) { :not(:has()) }` instead of a bare `:not(:has())` rule.
 
 ---
 
@@ -395,6 +403,8 @@ See the comment block in `exclusive.ts:500-523`: a default value whose higher-pr
 
 Computes the Cartesian product of all style entries for a handler, creating snapshots of which value each style has for each possible state combination.
 
+When every input is a direct value rather than a state map, the pipeline skips stages 0–4 and passes one unconditional snapshot directly to the handler. This avoids building exclusive entries and a Cartesian product for ordinary state-free styles.
+
 ### How It Works
 
 1. Collect exclusive entries for each style the handler uses
@@ -454,6 +464,7 @@ Style handlers encapsulate the logic for translating design tokens (like `'2x'`)
 ### What It Does
 
 Combines rules that have identical CSS output into a single rule with an OR condition.
+Zero- and one-rule inputs return unchanged because no merge is possible.
 
 ### How It Works
 
@@ -739,3 +750,16 @@ Impossible combinations are detected at multiple levels (simplification, variant
 ### 4. Aggressive Caching
 
 Parse, simplify, condition-to-CSS, and full-pipeline results are cached independently, enabling fast re-rendering when only parts of the style object change.
+
+Cache keys must respect key order where it carries meaning. A state map resolves by key order, so `{ '': A, checked: B, disabled: C }` and `{ '': A, disabled: C, checked: B }` are different styles and must get different keys (and classes). Only the style keys of a styles object, including a sub-element's, are order-insensitive, so they may be sorted. `stringifyStyles` (pipeline cache) and `generateChunkCacheKey` (class allocation) both follow this rule.
+
+---
+
+## Testing Priority
+
+Every stage above is an optimization that must leave one thing unchanged: in any state, the value that applies is the value of the last authored key whose condition holds. `src/test/state-oracle.ts` states that rule directly, with none of the pipeline's machinery, and two suites compare the pipeline against it:
+
+- `src/pipeline/exclusive.test.ts` (Node) evaluates the conditions after each of Stages 0–3 on thousands of generated maps, and names the stage that disagrees.
+- `src/pipeline/state-priority.test.ts` (browser) renders hand-written, permuted, and generated maps to CSS, applies every combination of states (modifiers, value modifiers, `:has()`, `@root`, `@parent`, `@own`, media, supports), and compares what the browser computes against the oracle. It also checks that rules stay mutually exclusive, which a correct computed value alone can hide. It runs through the pipeline, the runtime injector, and the SSR collector, with all maps mounted at once so a cache-key collision shows up.
+
+A change to any stage should keep both green. When a generated map fails, the message includes the map, the failing states, and the CSS; the map is usually worth adding to the hand-written cases once it is reduced.

package/docs/plugins.md

@@ -43,23 +43,23 @@ configure({ plugins: [spacingPlugin()] });
 
 ## Choosing an extension point
 
-| You want to add | Use | Runs | Zero-runtime |
-|---|---|---|---|
-| New value syntax — `okhsl(…)`, `double(2x)` | `functions` (bare key) | parse time, per value | ✅ |
-| A reusable CSS `@function` | `functions` (`$$name` key) | injected once, globally | ✅ |
-| A new unit — `2gu` | `units` | parse time, per value | ✅ |
-| A new state alias — `@mobile` | `states` | state-key parse | ✅ |
-| A style property → **CSS declarations** | `handlers` | pipeline, per state snapshot | ✅ |
-| A style property on every component | `baseStyleProps` | prop harvest | ✅ (styles only) |
-| A **component prop** → anything | `propHandlers` | render, per component | ❌ (no props to run on) |
-| A named bundle of styles | `recipes` | before chunking | ✅ |
-| Typography scale tokens | `presets` | inject time | ✅ |
-| `:root` variables | `tokens`, `replaceTokens` | inject time | ✅ |
-| Global selector styles | `globalStyles` | inject time | ✅ |
+| You want to add                             | Use                        | Runs                         | Build-time extraction   |
+| ------------------------------------------- | -------------------------- | ---------------------------- | ----------------------- |
+| New value syntax — `okhsl(…)`, `double(2x)` | `functions` (bare key)     | parse time, per value        | ✅                      |
+| A reusable CSS `@function`                  | `functions` (`$$name` key) | injected once, globally      | ✅                      |
+| A new unit — `2gu`                          | `units`                    | parse time, per value        | ✅                      |
+| A new state alias — `@mobile`               | `states`                   | state-key parse              | ✅                      |
+| A style property → **CSS declarations**     | `handlers`                 | pipeline, per state snapshot | ✅                      |
+| A style property on every component         | `baseStyleProps`           | prop harvest                 | ✅ (styles only)        |
+| A **component prop** → anything             | `propHandlers`             | render, per component        | ❌ (no props to run on) |
+| A named bundle of styles                    | `recipes`                  | before chunking              | ✅                      |
+| Typography scale tokens                     | `presets`                  | inject time                  | ✅                      |
+| `:root` variables                           | `tokens`, `replaceTokens`  | inject time                  | ✅                      |
+| Global selector styles                      | `globalStyles`             | inject time                  | ✅                      |
 
 Two distinctions do most of the work:
 
-- **`handlers` vs `propHandlers`.** A handler turns a *style property* into CSS declarations and knows nothing about components. A prop handler turns a *component prop* into other props — including `styles`, which then flow through the normal handlers. Reach for `propHandlers` when the input isn't a style value (an options object, a domain concept) or when it should affect more than styles.
+- **`handlers` vs `propHandlers`.** A handler turns a _style property_ into CSS declarations and knows nothing about components. A prop handler turns a _component prop_ into other props — including `styles`, which then flow through the normal handlers. Reach for `propHandlers` when the input isn't a style value (an options object, a domain concept) or when it should affect more than styles.
 - **`recipes` vs `propHandlers`.** A recipe is a static named bundle. A prop handler computes its styles from a value.
 
 ---
@@ -123,12 +123,12 @@ configure({
 
 **The key is the trigger.** By default a handler runs only when a prop matching its key is present, so an absent prop costs one property check rather than a call. Override that with a tuple:
 
-| Definition | Runs when |
-|---|---|
-| `fn` | a prop named after the key is present |
-| `['glaze', fn]` | `glaze` is present |
-| `[['glaze', 'tint'], fn]` | either is present |
-| `['*', fn]` | always |
+| Definition                | Runs when                             |
+| ------------------------- | ------------------------------------- |
+| `fn`                      | a prop named after the key is present |
+| `['glaze', fn]`           | `glaze` is present                    |
+| `[['glaze', 'tint'], fn]` | either is present                     |
+| `['*', fn]`               | always                                |
 
 **Chaining.** Handlers run in registration order — plugins first, then direct `configure()` — and each receives the previous one's output. Registering the same key twice replaces the handler in place, keeping its position.
 
@@ -136,16 +136,16 @@ configure({
 
 ### Rules
 
-- **Be pure. Never mutate the input.** Style values are cached by object identity, so mutating a value object in place yields a stale class name *and* stale CSS. Return fresh objects.
+- **Be pure. Never mutate the input.** Style values are cached by object identity, so mutating a value object in place yields a stale class name _and_ stale CSS. Return fresh objects.
 - **Memoize the styles you build, per input value.** A reference-stable (ideally frozen) styles object lets the cache key reuse its serialization instead of recomputing it on every render. This is the single highest-leverage thing you can do for performance.
 - **Precedence is fixed** and not adjustable from a handler. Styles are merged as `factory defaults → styles → harvested style props`, and injected styles occupy the `styles` slot: they beat a component's own default styles and lose to a style prop passed at the call site. This matches how `recipe` already behaves.
-- **Prefer returning `styles` over bare style props.** Returning `{ fill: '#red' }` only works if `fill` is harvestable on *that* component (in its `styleProps`, or promoted via `baseStyleProps`); otherwise it leaks to the DOM.
+- **Prefer returning `styles` over bare style props.** Returning `{ fill: '#red' }` only works if `fill` is harvestable on _that_ component (in its `styleProps`, or promoted via `baseStyleProps`); otherwise it leaks to the DOM.
 
 ### What it cannot do
 
 - **`ref`** — `forwardRef` separates it from props, so it is out of reach.
 - **Sub-elements** (`Card.Title`) — they have no `styles` prop and no style-prop harvest, so middleware does not run on them.
-- **Zero-runtime mode** — see [Rendering modes](#rendering-modes-and-caveats).
+- **Build-time extraction** — see [Rendering modes](#rendering-modes-and-caveats).
 
 ---
 
@@ -161,7 +161,7 @@ configure({ baseStyleProps: ['radius', 'shadow'] });
 
 Names must be real style properties, must start with a lowercase letter, and must not collide with a prop `tasty()` consumes itself (`as`, `styles`, `variant`, `mods`, `tokens`, …); invalid entries are dropped with a development warning.
 
-`configure()` may run *after* your components are defined — each factory resolves its prop list lazily and refreshes when the registry changes.
+`configure()` may run _after_ your components are defined — each factory resolves its prop list lazily and refreshes when the registry changes.
 
 **Costs and caveats.** Each name adds one property check per render of every component, forever, so keep the list short. The effect is app-global and cannot be scoped to a subtree — use a factory's own `styleProps` for that. Be wary of names that collide with real DOM or component props (`width`, `size`, `color`): promoting one means every component swallows it as a style, including when rendering `as={SomeThirdPartyComponent}`.
 
@@ -211,7 +211,7 @@ export default {
 };
 ```
 
-`propHandlers` keys are JSX props rather than style keys, so they need no entry — but any *style* name or token a handler expands into does.
+`propHandlers` keys are JSX props rather than style keys, so they need no entry — but any _style_ name or token a handler expands into does.
 
 ---
 
@@ -246,7 +246,7 @@ function glazeStyles(value: GlazeValue): Styles {
     styles = Object.freeze({
       '#glaze-bg': `#${tone}.${intensity}`,
       fill: '#glaze-bg',
-      transition: 'fill 0.2s',
+      transition: 'fill',
     }) as Styles;
     cache.set(key, styles);
   }
@@ -274,7 +274,11 @@ export const glazePlugin: TastyPluginFactory = () => ({
 
   // Typed so `#glaze-bg` animates smoothly instead of snapping.
   properties: {
-    '#glaze-bg': { syntax: '<color>', inherits: false, initialValue: 'transparent' },
+    '#glaze-bg': {
+      syntax: '<color>',
+      inherits: false,
+      initialValue: 'transparent',
+    },
   },
 });
 ```
@@ -302,19 +306,19 @@ declare module '@tenphi/tasty' {
 }
 ```
 
-The object value is unambiguous here precisely because `glaze` is a **prop**. A style *value* of the same shape would be indistinguishable from a state map (`{ tone: … }` looks exactly like `{ hovered: … }`), which is why this belongs in `propHandlers` rather than `handlers`.
+The object value is unambiguous here precisely because `glaze` is a **prop**. A style _value_ of the same shape would be indistinguishable from a state map (`{ tone: … }` looks exactly like `{ hovered: … }`), which is why this belongs in `propHandlers` rather than `handlers`.
 
 ---
 
 ## Rendering modes and caveats
 
-| Mode | `functions` / `units` / `states` / `handlers` / `recipes` / `tokens` | `propHandlers` |
-|---|---|---|
-| Client | ✅ | ✅ |
-| SSR / RSC | ✅ | ✅ |
-| Zero-runtime (`tastyStatic`) | ✅ at build time | not applicable |
+| Mode                       | `functions` / `units` / `states` / `handlers` / `recipes` / `tokens` | `propHandlers` |
+| -------------------------- | -------------------------------------------------------------------- | -------------- |
+| Client                     | ✅                                                                   | ✅             |
+| SSR / RSC                  | ✅                                                                   | ✅             |
+| Build-time (`tastyStatic`) | ✅ at build time                                                     | not applicable |
 
-**Zero-runtime.** The Babel plugin transforms `tastyStatic()` calls, which take styles objects — there are no props in that pipeline, so there is nothing for props middleware to run on. Components you render through `tasty()` are untouched by the plugin and keep the runtime injector, so `propHandlers` work there exactly as in any client app; their CSS simply comes from the injector rather than the extracted stylesheet. Everything else runs at build time, which is why handlers, functions, and units must be pure functions of their input.
+**Build-time extraction.** The Babel plugin transforms `tastyStatic()` calls, which take styles objects — there are no props in that pipeline, so there is nothing for props middleware to run on. Components rendered through `tasty()` are untouched by the plugin; `propHandlers` work whether those components render on the server or in the browser. Everything in the `tastyStatic()` path runs at build time, which is why handlers, functions, and units must be pure functions of their input.
 
 **Server and client must configure identically.** Class names are derived from resolved styles, so a handler or promoted prop registered on one side and not the other produces a hydration mismatch. This is the same requirement as `namePrefix` — see [SSR → Hydration mismatch warnings](ssr.md#hydration-mismatch-warnings).