@tenphi/cookbook 0.28.0 → 0.30.1

package/docs/upstream/tasty/docs/pipeline.md

@@ -2,7 +2,7 @@
 
 This document describes the style rendering pipeline that transforms style objects into CSS rules. The pipeline ensures that each style value is applied to exactly one condition through exclusive condition building, boolean simplification, and intelligent CSS generation.
 
-**Implementation:** [`src/pipeline/`](https://github.com/tenphi/tasty/blob/v3.9.10/src/pipeline) — TypeScript file names below are relative to that directory.
+**Implementation:** [`src/pipeline/`](https://github.com/tenphi/tasty/tree/main/src/pipeline) — TypeScript file names below are relative to that directory.
 
 ## Overview
 
@@ -76,9 +76,9 @@ Output: CSSRule[]
 
 **Simplification** (`simplifyCondition` in `simplify.ts`) is not a separate numbered stage. It runs inside OR expansion, exclusive building, `expandExclusiveOrs` branch cleanup, combination ANDs, merge-by-value ORs, and materialization. Every call is cached by condition unique-id, so the repetition is cheap.
 
-**Post-pass:** After `processStyles` collects rules from every handler, `runPipeline` (`index.ts`) filters duplicates using a key of `selector|declarations|atRules|rootPrefix|startingStyle`, then **stable-sorts rules by their cascade `order` hint (ascending source priority)** so lower-priority rules come first and higher-priority rules win, and finally emits every `@starting-style` rule **after** all normal rules. The `order` hint is the highest source priority among the entries that produced each rule (threaded `ComputedRule → CSSRule`). This ordering is cascade-critical because Stage 7 equalizes specificity with `:where()`: once every state selector carries zero specificity, source order alone decides which of two overlapping rules wins — most importantly the `_` fallback floor (low order, emitted first) versus the states layered over it, and `@starting-style` versus its normal counterpart. Mutually-exclusive rules are unaffected by ordering (they never both match), so reordering them is safe.
+**Post-pass:** After `processStyles` collects rules from every handler, `runPipeline` (`index.ts`) filters duplicates using a key of `selector|declarations|atRules|rootPrefix|startingStyle`, then **stable-sorts rules by their cascade `order` hint (ascending source priority)** so lower-priority rules come first and higher-priority rules win, and finally emits every `@starting-style` rule **after** all normal rules. Each Stage 4 snapshot takes the highest source priority among its entries as its `order` hint; when Stage 6 merges same-output rules, the merged rule keeps the lowest `order` of its group, so a rule carrying the `_` floor's value keeps the floor's early position (threaded `ComputedRule → CSSRule`). This ordering is cascade-critical because Stage 7 equalizes specificity with `:where()`: once every state selector carries zero specificity, source order alone decides which of two overlapping rules wins — most importantly the `_` fallback floor (low order, emitted first) versus the states layered over it, and `@starting-style` versus its normal counterpart. Mutually-exclusive rules are unaffected by ordering (they never both match), so reordering them is safe.
 
-***
+---
 
 ## Stage 0: Pre-parse Normalization
 
@@ -114,7 +114,7 @@ Removing don't-care dimensions before parsing prevents combinatorial blowup in l
 { '': 'A', '@dark': 'B' }
 ```
 
-***
+---
 
 ## Stage 1: Parse Conditions
 
@@ -129,9 +129,9 @@ Converts each state key in a style value map (like `'hovered & !disabled'`, `'@m
 ### How It Works
 
 1. **Tokenization**: The state key is split into tokens using a regex pattern that recognizes:
-   * Operators: `&` (AND), `|` (OR), `!` (NOT), `^` (XOR)
-   * Parentheses for grouping
-   * State tokens: `@media(...)`, `@root(...)`, `@parent(...)`, `@own(...)`, `@supports(...)`, `@(...)`, `@starting`, predefined states, modifiers, pseudo-classes
+   - Operators: `&` (AND), `|` (OR), `!` (NOT), `^` (XOR)
+   - Parentheses for grouping
+   - State tokens: `@media(...)`, `@root(...)`, `@parent(...)`, `@own(...)`, `@supports(...)`, `@(...)`, `@starting`, predefined states, modifiers, pseudo-classes
 
 2. **Recursive Descent Parsing**: Tokens are parsed with operator precedence:
    ```
@@ -139,27 +139,26 @@ Converts each state key in a style value map (like `'hovered & !disabled'`, `'@m
    ```
 
 3. **State Token Interpretation**: Each state token is converted to a specific condition type:
-   * `hovered` → `ModifierCondition` with `attribute: 'data-hovered'`
-   * `theme=dark` → `ModifierCondition` with `attribute: 'data-theme', value: 'dark'`
-   * `:hover` → `PseudoCondition`
-   * `@media(w < 768px)` → `MediaCondition` (`subtype: 'dimension'`) with bounds
-   * `@media(prefers-color-scheme: dark)` → `MediaCondition` (`subtype: 'feature'`, `feature` + `featureValue`)
-   * `@root(schema=dark)` → `RootCondition` wrapping the inner condition
-   * `@parent(hovered)` → `ParentCondition` (optional `direct` for immediate parent)
-   * `@own(hovered)` → `OwnCondition` wrapping the parsed inner condition
-   * `@supports(display: grid)` → `SupportsCondition`
-   * `@(w < 600px)` → `ContainerCondition` (dimension, style, or raw subtypes)
-   * `@mobile` → Resolved via predefined states, then parsed recursively
+   - `hovered` → `ModifierCondition` with `attribute: 'data-hovered'`
+   - `theme=dark` → `ModifierCondition` with `attribute: 'data-theme', value: 'dark'`
+   - `:hover` → `PseudoCondition`
+   - `@media(w < 768px)` → `MediaCondition` (`subtype: 'dimension'`) with bounds
+   - `@media(prefers-color-scheme: dark)` → `MediaCondition` (`subtype: 'feature'`, `feature` + `featureValue`)
+   - `@root(schema=dark)` → `RootCondition` wrapping the inner condition
+   - `@parent(hovered)` → `ParentCondition` (optional `direct` for immediate parent)
+   - `@own(hovered)` → `OwnCondition` wrapping the parsed inner condition
+   - `@supports(display: grid)` → `SupportsCondition`
+   - `@(w < 600px)` → `ContainerCondition` (dimension, style, or raw subtypes)
+   - `@mobile` → Resolved via predefined states, then parsed recursively
 
 Pipeline warnings for invalid inputs (e.g. bad `$` selector affix) are emitted from `warnings.ts`.
 
 ### Why
 
 The condition tree representation enables:
-
-* Boolean algebra operations (simplification, negation)
-* Semantic analysis (detect contradictions)
-* Flexible CSS generation (different output for media vs. selectors)
+- Boolean algebra operations (simplification, negation)
+- Semantic analysis (detect contradictions)
+- Flexible CSS generation (different output for media vs. selectors)
 
 ### Example
 
@@ -178,7 +177,7 @@ The condition tree representation enables:
 }
 ```
 
-***
+---
 
 ## Stage 1b: Merge Entries By Value
 
@@ -248,7 +247,7 @@ The compound dark/HC dedup pattern `{ '': light, '@dark': dark, '@hc': hc, '@dar
 // correctly resolved.
 ```
 
-***
+---
 
 ## Stage 2a: Expand User OR Branches
 
@@ -276,7 +275,7 @@ This pass does **not** sort branches — user ORs are authored in the natural or
 
 Running this before exclusive building means the Stage 2b negation cascade sees one branch per entry and never has to reason about nested ORs while computing `!prior`. It also avoids emitting overlapping CSS rules: `{ 'compact | @media(dark)': 'red' }` becomes two mutually exclusive entries rather than one rule whose two branches could both match simultaneously.
 
-***
+---
 
 ## Stage 2b: Build Exclusive Conditions
 
@@ -289,7 +288,6 @@ Ensures each style entry applies in exactly one scenario by ANDing each conditio
 ### How It Works
 
 Given entries ordered by priority (highest first):
-
 ```
 A: value1 (priority 2)
 B: value2 (priority 1)
@@ -297,7 +295,6 @@ C: value3 (priority 0)
 ```
 
 Produces:
-
 ```
 A: A                    (highest priority, no negation needed)
 B: B & !A               (applies only when A doesn't)
@@ -337,10 +334,9 @@ being negated, swaps out cleanly. See the DSL guide's "`_` vs the `''` default".
 ### Why
 
 This eliminates CSS specificity wars. Instead of relying on cascade order, each CSS rule matches in exactly one scenario. Benefits:
-
-* Predictable styling regardless of rule order
-* No conflicts from overlapping conditions
-* Easier debugging (each rule is mutually exclusive)
+- Predictable styling regardless of rule order
+- No conflicts from overlapping conditions
+- Easier debugging (each rule is mutually exclusive)
 
 ### Example
 
@@ -354,7 +350,7 @@ This eliminates CSS specificity wars. Instead of relying on cascade order, each
 // !compact & !@media(w < 768px): default, applies when neither
 ```
 
-***
+---
 
 ## Stage 3: Expand De Morgan OR Branches
 
@@ -366,10 +362,10 @@ Runs **after** `buildExclusiveConditions`. Handles ORs that arise **during** exc
 
 This is the companion to **Stage 2a** (user-OR expansion). The split exists because the two passes have different data and different correctness needs:
 
-| Stage                   | Runs on                                  | Sees ORs from                                        | Sorts branches?              |                           |
-| ----------------------- | ---------------------------------------- | ---------------------------------------------------- | ---------------------------- | ------------------------- |
-| 2a `expandOrConditions` | `ParsedStyleEntry.condition`             | User-authored \`                                     | \` in state keys             | No — user order is stable |
-| 3 `expandExclusiveOrs`  | `ExclusiveStyleEntry.exclusiveCondition` | De Morgan negation inside `buildExclusiveConditions` | Yes — at-rule branches first |                           |
+| Stage | Runs on | Sees ORs from | Sorts branches? |
+|---|---|---|---|
+| 2a `expandOrConditions` | `ParsedStyleEntry.condition` | User-authored `\|` in state keys | No — user order is stable |
+| 3 `expandExclusiveOrs` | `ExclusiveStyleEntry.exclusiveCondition` | De Morgan negation inside `buildExclusiveConditions` | Yes — at-rule branches first |
 
 ### How It Works
 
@@ -383,13 +379,13 @@ This is the companion to **Stage 2a** (user-OR expansion). The split exists beca
 
 **At-rules before selectors.** Consider `!A | !B` where A is an at-rule (e.g. `@supports(grid)`) and B is a modifier (e.g. `:has(foo)`):
 
-* **With at-rule-first sort** (`!A`, then `!B & A`): the first branch emits "outside `@supports`", the second emits "inside `@supports` with `:not(:has(foo))`". Full coverage.
-* **Without the sort** (`!B`, then `!A & B`): the first branch emits `:not(:has(foo))` as a bare selector with no at-rule context — leaking the rule outside `@supports`. The second is incomplete.
+- **With at-rule-first sort** (`!A`, then `!B & A`): the first branch emits "outside `@supports`", the second emits "inside `@supports` with `:not(:has(foo))`". Full coverage.
+- **Without the sort** (`!B`, then `!A & B`): the first branch emits `:not(:has(foo))` as a bare selector with no at-rule context — leaking the rule outside `@supports`. The second is incomplete.
 
 **`@supports` before other at-rules (Kleene logic).** A `@supports` feature query is special: anything ANDed with it can become *unknown* — not simply false — when the feature is unsupported. The canonical case is a feature guard over a dependent query, e.g. `@supports(container-type: scroll-state) & @(scroll-state(scrolled: block-end))` (`S & C`). The default's exclusive is `!(S & C) = !S | !C`, which `simplify` sorts alphabetically into `[!C, !S]`.
 
-* **Expanding `!C` first** emits a bare `@container (not scroll-state(...))` rule. In a browser without `scroll-state` support that query is unknown (not false), so it matches nothing and the default `inset` is never applied — a coverage hole.
-* **Expanding `!S` first** yields `!S | (S & !C)`: a bare `@supports (not (container-type: scroll-state))` fallback carrying the default, plus the dependent negation nested inside the supported scope. Full coverage, and the unsupported path never references the guarded query.
+- **Expanding `!C` first** emits a bare `@container (not scroll-state(...))` rule. In a browser without `scroll-state` support that query is unknown (not false), so it matches nothing and the default `inset` is never applied — a coverage hole.
+- **Expanding `!S` first** yields `!S | (S & !C)`: a bare `@supports (not (container-type: scroll-state))` fallback carrying the default, plus the dependent negation nested inside the supported scope. Full coverage, and the unsupported path never references the guarded query.
 
 Because `!S | (S & !R) ≡ !S | !R` in two-valued logic, this reordering is a no-op for cases without an `@supports` guard. The same supports-first ordering is also applied in `makeOrBranchesExclusive` (`materialize.ts`) for ORs that survive nested inside an AND (e.g. `compact & (!S | !C)`).
 
@@ -399,7 +395,7 @@ The pre-build Stage 2a pass doesn't need this because user-authored ORs aren't p
 
 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.
 
-***
+---
 
 ## Stage 4: Compute State Combinations
 
@@ -416,10 +412,10 @@ When every input is a direct value rather than a state map, the pipeline skips s
 1. Collect exclusive entries for each style the handler uses
 2. Compute Cartesian product: every combination of entries
 3. For each combination:
-   * AND all `exclusiveCondition` values together
-   * `simplifyCondition` the result
-   * Skip if simplified to `FALSE`
-   * Record the values for each style
+   - AND all `exclusiveCondition` values together
+   - `simplifyCondition` the result
+   - Skip if simplified to `FALSE`
+   - Record the values for each style
 
 ### Why
 
@@ -439,7 +435,7 @@ Style handlers often depend on multiple style properties (e.g., `padding` might
 // { padding: '1x', size: 'small', condition: B & D }
 ```
 
-***
+---
 
 ## Stage 5: Call Handlers
 
@@ -452,16 +448,16 @@ Invokes style handlers with computed value snapshots to produce CSS declarations
 ### How It Works
 
 1. For each state snapshot (condition + values):
-   * Call the handler with the values
-   * Handler returns CSS properties (e.g., `{ 'padding-top': '16px', 'padding-bottom': '16px' }`)
-   * Handler may also return `$` (selector suffix) for pseudo-elements
+   - Call the handler with the values
+   - Handler returns CSS properties (e.g., `{ 'padding-top': '16px', 'padding-bottom': '16px' }`)
+   - Handler may also return `$` (selector suffix) for pseudo-elements
 2. Create computed rules with the condition, declarations, and selector suffix
 
 ### Why
 
 Style handlers encapsulate the logic for translating design tokens (like `'2x'`) to actual CSS values (like `'16px'`). They can also handle complex multi-property styles (e.g., `padding` → `padding-top`, `padding-right`, etc.).
 
-***
+---
 
 ## Stage 6: Merge By Value
 
@@ -476,8 +472,8 @@ Zero- and one-rule inputs return unchanged because no merge is possible.
 
 1. Group rules by `selectorSuffix` plus a stable string for declarations (JSON via an internal `declStringCache` `WeakMap` on declaration objects)
 2. For rules in the same group:
-   * Merge their conditions with OR
-   * `simplifyCondition` the resulting condition
+   - Merge their conditions with OR
+   - `simplifyCondition` the resulting condition
 3. Output one rule per group
 
 ### Why
@@ -495,7 +491,7 @@ Different state combinations might produce the same CSS output. Rather than emit
 // condition: A | B → { color: 'red' }
 ```
 
-***
+---
 
 ## Stage 7: Materialize CSS
 
@@ -508,15 +504,15 @@ Converts condition trees into actual CSS selectors and at-rules.
 ### How It Works
 
 1. **Condition to CSS components** (`conditionToCSS`): Walk the condition tree and build `SelectorVariant` data:
-   * `ModifierCondition` → attribute selectors (e.g. `[data-hovered]`); optional `operator` (`=`, `^=`, `$=`, `*=`)
-   * `PseudoCondition` → pseudo-class (e.g. `:hover`)
-   * `MediaCondition` → `@media` (dimension, feature, or type)
-   * `ContainerCondition` → `@container` (dimension, style query, or raw)
-   * `RootCondition` → `rootGroups` / root prefix fragments
-   * `ParentCondition` → `parentGroups` / ancestor selectors (`direct` → child combinator path)
-   * `OwnCondition` → `ownGroups` on the **styled** element (sub-element / `&` scope), optimized with `optimizeGroups`
-   * `SupportsCondition` → `@supports` at-rules
-   * `StartingCondition` → `@starting-style` wrapper
+   - `ModifierCondition` → attribute selectors (e.g. `[data-hovered]`); optional `operator` (`=`, `^=`, `$=`, `*=`)
+   - `PseudoCondition` → pseudo-class (e.g. `:hover`)
+   - `MediaCondition` → `@media` (dimension, feature, or type)
+   - `ContainerCondition` → `@container` (dimension, style query, or raw)
+   - `RootCondition` → `rootGroups` / root prefix fragments
+   - `ParentCondition` → `parentGroups` / ancestor selectors (`direct` → child combinator path)
+   - `OwnCondition` → `ownGroups` on the **styled** element (sub-element / `&` scope), optimized with `optimizeGroups`
+   - `SupportsCondition` → `@supports` at-rules
+   - `StartingCondition` → `@starting-style` wrapper
 
 2. **AND / OR on variants**: AND merges variant dimensions; OR yields multiple variants (later merged into `:is()` / `:not()` groups where appropriate).
 
@@ -525,23 +521,21 @@ Converts condition trees into actual CSS selectors and at-rules.
 4. **`materializeComputedRule`**: Groups variants by sorted at-rules plus root-prefix key; within each group, `mergeVariantsIntoSelectorGroups` merges variants that differ only in flat modifier/pseudo parts; builds selector strings and emits one or more `CSSRule` objects. The rule's `order` hint (cascade priority) is propagated here for the post-pass sort.
 
 5. **`:where()` specificity equalization**: Every stateful part of the selector is wrapped in `:where(...)` so it contributes **zero specificity**:
-
-   * the flat root modifiers + pseudos and the root element's `:is()`/`:not()` groups are combined into one `:where(...)` (`buildSelectorFromVariant`);
-   * the sub-element (`@own`) groups are wrapped in a **separate** `:where(...)` so the sub-element's structural `[data-element="X"]` specificity is preserved while its states are zeroed;
-   * `@parent` ancestors (`parentGroupsToCSS`) become `:where(... *)` / `:where(:not(... *))`;
-   * the `@root` context prefix (`rootGroupsToCSS`) becomes `:where(:root...)` (zeroing the `:root` pseudo too).
+   - the flat root modifiers + pseudos and the root element's `:is()`/`:not()` groups are combined into one `:where(...)` (`buildSelectorFromVariant`);
+   - the sub-element (`@own`) groups are wrapped in a **separate** `:where(...)` so the sub-element's structural `[data-element="X"]` specificity is preserved while its states are zeroed. When the suffix ends in a pseudo-element, these are the pseudo-element's own states and stay after it (`a::before:where(:hover)`). States a pseudo-element can't have (attributes, modifiers, classes, tree-structural pseudo-classes) are dropped with a `PSEUDO_ELEMENT_STATE_IGNORED` warning before Stage 0, using the CSS language alone, never per-browser support (`pseudo-element-states.ts`). A direct selector that ends in a pseudo-element (`.card::before`) is rendered separately: its root states are checked the same way and go after the pseudo-element, its `@parent` segments before it, at the `pseudoElementAt` each `CSSRule` records;
+   - `@parent` ancestors (`parentGroupsToCSS`) become `:where(... *)` / `:where(:not(... *))`;
+   - the `@root` context prefix (`rootStateToPrefix`) becomes `:where(:root...)` (zeroing the `:root` pseudo too). When a direct selector can only match the root itself (`:root`, `html`, `:where(:root)`), the state segment joins it instead — `:root:where([data-schema="dark"])` — since an ancestor prefix would ask for a `:root` inside the root.
 
    The only specificity anchors that remain are the doubled component class (`.tXX.tXX`, added by the injector) and sub-element `[data-element]` attributes. Because Stage 2b already makes ordinary rules mutually exclusive, zeroing specificity never changes *which* rule matches — it only makes additive layering (`_` fallback floor, `@starting-style`) resolve deterministically by source order (see the post-pass). Canonical sorting/dedup/subsumption still run first; `:where()` is only the final wrapper, and both output paths (injector and direct-selector / SSR) consume the same wrapped fragments.
 
 ### Why
 
 CSS has different mechanisms for different condition types:
-
-* Modifiers → attribute selectors
-* Media queries → `@media` blocks
-* Container queries → `@container` blocks
-* Root state → `:root` / root groups
-* Supports → `@supports` blocks
+- Modifiers → attribute selectors
+- Media queries → `@media` blocks
+- Container queries → `@container` blocks
+- Root state → `:root` / root groups
+- Supports → `@supports` blocks
 
 The materialization layer handles these differences while maintaining the logical semantics of the condition tree.
 
@@ -553,14 +547,15 @@ interface CSSRule {
   declarations: string; // CSS declarations (e.g. 'color: red;')
   atRules?: string[]; // Wrapping at-rules
   rootPrefix?: string; // Root state prefix
+  rootState?: string; // Root-state segment without its :root anchor; lets a root selector take states directly
   startingStyle?: boolean; // Wrap declarations in @starting-style
   order?: number; // Internal cascade order hint (ascending source priority); stripped before injection
 }
 ```
 
-When `renderStyles` runs **without** a selector, returned rules include `needsClassName: true` (compatibility field for the injector); that flag is not part of `CSSRule` inside `materialize.ts`.
+When `renderStyles` runs **without** a selector, returned rules include `needsClassName: true` (compatibility field for the injector); that flag is not part of `CSSRule` (defined in `materialize-types.ts`).
 
-***
+---
 
 ## Condition Types
 
@@ -587,12 +582,12 @@ ConditionNode
 
 ### Key Operations
 
-* `and(...conditions)`: Create AND with short-circuit and flattening
-* `or(...conditions)`: Create OR with short-circuit and flattening
-* `not(condition)`: Negate with De Morgan's law support
-* `getConditionUniqueId(condition)`: Get canonical ID for comparison
+- `and(...conditions)`: Create AND with short-circuit and flattening
+- `or(...conditions)`: Create OR with short-circuit and flattening
+- `not(condition)`: Negate with De Morgan's law support
+- `getConditionUniqueId(condition)`: Get canonical ID for comparison
 
-***
+---
 
 ## Simplification
 
@@ -605,33 +600,33 @@ Applies boolean algebra rules to reduce condition complexity and detect impossib
 ### Rules Applied
 
 1. **Identity Laws**:
-   * `A & TRUE = A`
-   * `A | FALSE = A`
+   - `A & TRUE = A`
+   - `A | FALSE = A`
 
 2. **Annihilator Laws**:
-   * `A & FALSE = FALSE`
-   * `A | TRUE = TRUE`
+   - `A & FALSE = FALSE`
+   - `A | TRUE = TRUE`
 
 3. **Contradiction Detection**:
-   * `A & !A = FALSE`
+   - `A & !A = FALSE`
 
 4. **Tautology Detection**:
-   * `A | !A = TRUE`
+   - `A | !A = TRUE`
 
 5. **Idempotent Laws** (via deduplication):
-   * `A & A = A`
-   * `A | A = A`
+   - `A & A = A`
+   - `A | A = A`
 
 6. **Absorption Laws**:
-   * `A & (A | B) = A`
-   * `A | (A & B) = A`
+   - `A & (A | B) = A`
+   - `A | (A & B) = A`
 
-7. **Range intersection**: For **media and container** dimension queries, impossible ranges simplify to `FALSE` (e.g. `@media(w > 400px) & @media(w < 300px)`). Ranges with compatible bounds are also merged in place (`w >= 400 & w <= 800` → a single bounded range).
+7. **Range intersection**: For **media and container** dimension queries, impossible ranges simplify to `FALSE` (e.g. `@media(w > 400px) & @media(w < 300px)`). Ranges with compatible bounds are also merged in place (`w >= 400 & w <= 800` → a single bounded range). Only bounds in the same unit are compared: `600px` and `40em` are never merged or found contradictory, because a query `em` follows the user's default font size. A bound with no numeric value (`calc(…)`) and a range whose two bounds use different units are left as they are.
 
 8. **Container style queries**: Conflicting or redundant `@container` style conditions on the same property can be reduced (see `simplify.ts` around the container-style conflict pass).
 
 9. **Attribute conflict detection**:
-   * `[data-theme="dark"] & [data-theme="light"] = FALSE`
+   - `[data-theme="dark"] & [data-theme="light"] = FALSE`
 
 10. **Complementary factoring** (OR context): `(A & B) | (A & !B) = A`. Also works on **compound complements** — if two AND-clauses differ only by a child that is a compound negation of the other (e.g. `X` vs `!X` where X is itself `(P & Q)`), the clauses factor correctly.
 
@@ -641,22 +636,22 @@ Applies boolean algebra rules to reduce condition complexity and detect impossib
 
 Simplification reduces CSS output size and catches impossible combinations early, preventing invalid CSS rules from being generated. Every `simplifyCondition` call is memoized by the condition's unique id, so the cost of running it many times across stages is negligible after the first hit.
 
-***
+---
 
 ## Caching Strategy
 
 LRU and small auxiliary caches:
 
-| Cache             | Size | Key                                                                                      | Purpose                                                    |
-| ----------------- | ---- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
-| `pipelineCache`   | 5000 | `pipelineCacheKey \|\| stringifyStyles(styles)`                                          | Skip full pipeline for identical styles                    |
-| `parseCache`      | 5000 | `trimmedStateKey + '\\0' + isSubElement + '\\0' + JSON.stringify(localPredefinedStates)` | Skip re-parsing identical state keys in context            |
-| `simplifyCache`   | 5000 | `getConditionUniqueId(node)`                                                             | Skip re-simplifying identical conditions                   |
-| `conditionCache`  | 3000 | `getConditionUniqueId(node)` in `conditionToCSS`                                         | Skip re-materializing identical conditions                 |
-| `variantKeyCache` | —    | `WeakMap<SelectorVariant, string>`                                                       | Stable string keys for variants during materialization     |
-| `declStringCache` | —    | `WeakMap<Record<string,string>, string>`                                                 | Stable JSON keys for declaration objects in `mergeByValue` |
+| Cache | Size | Key | Purpose |
+|-------|------|-----|---------|
+| `pipelineCache` | 5000 | `pipelineCacheKey \|\| stringifyStyles(styles)` | Skip full pipeline for identical styles |
+| `parseCache` | 5000 | `trimmedStateKey + '\0' + (isSubElement ? '1' : '0') + '\0' + (localPredefinedStates non-empty ? JSON.stringify(localPredefinedStates) : '')` | Skip re-parsing identical state keys in context |
+| `simplifyCache` | 5000 | `getConditionUniqueId(node)` | Skip re-simplifying identical conditions |
+| `conditionCache` | 3000 | `getConditionUniqueId(node)` in `conditionToCSS` | Skip re-materializing identical conditions |
+| `variantKeyCache` | — | `WeakMap<SelectorVariant, string>` | Stable string keys for variants during materialization |
+| `declStringCache` | — | `WeakMap<Record<string,string>, string>` | Stable JSON keys for declaration objects in `mergeByValue` |
 
-***
+---
 
 ## Example Walkthrough
 
@@ -710,28 +705,28 @@ Each snapshot yields distinct declarations; no merge.
 
 ### Stage 7: Materialize CSS
 
-Using `renderStyles(styles, '.t1')` (the class is doubled — `.t1.t1` — so Tasty owns specificity without `!important`):
+Using `renderStyles(styles, '.t1', { doubleSelector: true })`. The injector doubles the class the same way (`.t1.t1`) so Tasty owns specificity without `!important`, and every state is wrapped in `:where()` so it adds none. Rules come out in ascending priority:
 
 ```css
-.t1[data-hovered] {
-  color: var(--highlight-color);
-  --current-color: var(--highlight-color);
+@media (not (prefers-color-scheme: dark)) {
+  .t1.t1:where(:not([data-hovered])) {
+    color: var(--white-color);
+    --current-color: var(--white-color);
+  }
 }
 @media (prefers-color-scheme: dark) {
-  .t1:not([data-hovered]) {
+  .t1.t1:where(:not([data-hovered])) {
     color: var(--dark-color);
     --current-color: var(--dark-color);
   }
 }
-@media (not (prefers-color-scheme: dark)) {
-  .t1:not([data-hovered]) {
-    color: var(--white-color);
-    --current-color: var(--white-color);
-  }
+.t1.t1:where([data-hovered]) {
+  color: var(--highlight-color);
+  --current-color: var(--highlight-color);
 }
 ```
 
-***
+---
 
 ## Key Design Decisions
 
@@ -761,13 +756,13 @@ Parse, simplify, condition-to-CSS, and full-pipeline results are cached independ
 
 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.
+- `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/upstream/tasty/docs/plugins.md

@@ -37,7 +37,7 @@ configure({ plugins: [spacingPlugin()] });
 
 **Configuration is locked after the first render.** `configure()` warns and does nothing once any style has been generated, so it must run before your first component renders — at module scope in your entry file, or in a design-system module every component imports. `resetConfig()` reopens it, but it exists for tests.
 
-**Repeated `configure()` calls merge** for `tokens` and `globalStyles` (per selector). See [Configuration](configuration.md) for the current per-key semantics.
+**Repeated `configure()` calls merge.** Each call adds to what earlier calls registered, key by key, in every registry (`states`, `units`, `functions`, `handlers`, `propHandlers`, `baseStyleProps`, `tokens`, `replaceTokens`, `recipes`, `keyframes`, `properties`, `fontFaces`, `counterStyles`); `globalStyles` merges per selector. A later value for the same key wins.
 
 ---
 
@@ -69,7 +69,7 @@ Two distinctions do most of the work:
 A handler receives a map of the style properties it declared and returns CSS declarations. See [Configuration → Custom Style Handlers](configuration.md#custom-style-handlers) for the definition forms, return shape, the shared-handler groups you must be careful of, and chunk membership. The essentials:
 
 - Values arrive **state-resolved but unparsed** — the raw authored DSL string (`'2x'`, `'#purple.5'`, `true`, `4`). Call the exported `parseStyle()` / `parseColor()` yourself.
-- Return a `CSSMap` with **kebab-case** keys, an array of them, or nothing. `$` is a selector suffix, not a property.
+- Return a `CSSMap` with **kebab-case** keys, an array of them, or nothing. `$` is a selector suffix, not a property. A property whose value is an array gets one declaration per entry, for fallback chains.
 - Handlers must be pure and synchronous. They are called once per state combination and the results are cached.
 - Use `defineHandler(deps, fn)` for multi-dependency handlers so the dependency types are inferred.
 
@@ -108,6 +108,7 @@ configure({
 
 ```ts
 import { configure, mergeStyles } from '@tenphi/tasty';
+import type { Styles } from '@tenphi/tasty';
 
 configure({
   propHandlers: {
@@ -115,7 +116,11 @@ configure({
       const { glaze, ...rest } = props;
       if (!glaze) return rest;
 
-      return { ...rest, styles: mergeStyles(glazeStyles(glaze), rest.styles) };
+      // glazeStyles: see the worked example below
+      return {
+        ...rest,
+        styles: mergeStyles(glazeStyles(glaze), rest.styles as Styles),
+      };
     },
   },
 });
@@ -159,7 +164,7 @@ configure({ baseStyleProps: ['radius', 'shadow'] });
 <Card radius="1r" 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.
+Names must start with a lowercase letter and contain only letters and digits, and must not collide with a prop `tasty()` consumes itself (`as`, `styles`, `variant`, `mods`, `tokens`, …); invalid entries are dropped with a development warning. Names are not checked against the style registry, so a misspelled name is still harvested as a style prop.
 
 `configure()` may run _after_ your components are defined — each factory resolves its prop list lazily and refreshes when the registry changes.
 
@@ -169,39 +174,9 @@ Names must be real style properties, must start with a lowercase letter, and mus
 
 ## Typing your extension
 
-Four augmentation points, each matching a runtime registry:
-
-```ts
-// tasty.d.ts
-import type { StylePropValue } from '@tenphi/tasty';
-
-declare module '@tenphi/tasty' {
-  // configure({ handlers }) — a new style property
-  interface StylesInterface {
-    stripe?: StylePropValue<string>;
-  }
-
-  // configure({ propHandlers }) — a new component prop
-  interface TastyCustomProps {
-    glaze: 'soft' | 'strong' | { tone: string; intensity?: number };
-  }
-
-  // configure({ baseStyleProps }) — promoted style names, typed like the style
-  interface TastyBaseStylePropNames {
-    radius: true;
-    shadow: true;
-  }
-
-  // configure({ tokens }) / recipes / presets — autocomplete for names
-  interface TastyNamedColors {
-    'glaze-bg': true;
-  }
-}
-```
+Every extension point has a matching augmentation interface: `StylesInterface` for `handlers`, `TastyCustomProps` for `propHandlers`, `TastyBaseStylePropNames` for `baseStyleProps`, and `TastyNamedColors`, `TastyPresetNames`, and `TastyThemeNames` for the names your `tokens` and `presets` define. [Configuration → TypeScript](configuration.md#typescript) covers all six and the rules that go with them.
 
-`TastyCustomProps` keys become optional props on every component. `TastyBaseStylePropNames` entries are typed exactly like the style they name, so `radius="1r"` accepts the same values as `styles={{ radius: '1r' }}`.
-
-**Also update `tasty.config.ts`.** The ESLint plugin and VS Code extension validate style and token names against it, and neither is derived from the runtime registries:
+**Also update `tasty.config.ts`.** The ESLint plugin and VS Code extension validate style and token names against it, and neither reads the runtime registries or your augmentations:
 
 ```ts
 // tasty.config.ts
@@ -299,6 +274,8 @@ configure({ plugins: [glazePlugin()] });
 
 ```ts
 // tasty.d.ts
+import '@tenphi/tasty';
+
 declare module '@tenphi/tasty' {
   interface TastyCustomProps {
     glaze: import('./glaze-plugin').GlazeConfig | string;
@@ -327,17 +304,20 @@ The object value is unambiguous here precisely because `glaze` is a **prop**. A
 ## Testing a plugin
 
 ```ts
-import { configure, resetConfig, renderStyles } from '@tenphi/tasty';
+import { resetConfig, renderStyles } from '@tenphi/tasty';
+import type { PropHandler, Styles } from '@tenphi/tasty';
 
 describe('glaze plugin', () => {
   beforeEach(() => resetConfig());
   afterEach(() => resetConfig());
 
-  it('expands into a color token declaration', () => {
-    configure({ plugins: [glazePlugin()] });
+  it('turns the glaze prop into styles', () => {
+    const glaze = glazePlugin().propHandlers!.glaze as PropHandler;
+    const out = glaze({ glaze: 'purple' })!;
 
-    const rules = renderStyles({ '#glaze-bg': '#purple.10' }, '.test');
+    expect(out).not.toHaveProperty('glaze');
 
+    const rules = renderStyles(out.styles as Styles, '.test');
     expect(rules[0].declarations).toContain('--glaze-bg-color');
   });
 });
@@ -345,7 +325,7 @@ describe('glaze plugin', () => {
 
 Two things to know:
 
-- **Create components inside each test.** `resetConfig()` does not clear the per-factory class-name cache or prop-list memo, so a module-scope component created in one test carries state into the next.
+- **Create components inside each test.** `resetConfig()` does not clear a component's own class-name cache, which `tasty()` keeps in DOM environments, so a module-scope component can keep returning a class whose CSS the reset removed.
 - **Dev-mode warnings may not fire.** `isDevEnv()` reports `false` for `NODE_ENV=test`. Warnings that check it lazily can be enabled with `vi.stubEnv('NODE_ENV', 'development')`; some older ones capture it at module load and cannot be triggered from a test at all.
 
 ---