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

package/docs/pipeline.md

@@ -0,0 +1,765 @@
+# Tasty Style Rendering Pipeline
+
+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/`](../src/pipeline/) — TypeScript file names below are relative to that directory.
+
+## Overview
+
+The pipeline takes a `Styles` object and produces an array of `CSSRule` objects ready for injection into the DOM. The entry point is `renderStyles`, which has two overloads: called with a selector or class (`renderStyles(styles, '.t1')`) it returns the rules directly; called without one (`renderStyles(styles)`) it returns `{ rules }` for a caller that will allocate the class name itself. The per-handler flow is:
+
+```
+Input: Styles Object
+         ↓
+    ┌──────────────────────────────────────────┐
+    │  0. PRE-PARSE NORMALIZATION              │
+    │     extractCompoundStates                │
+    │     (drop don't-care AND atoms)          │
+    └──────────────────────────────────────────┘
+         ↓
+    ┌──────────────────────────────────────────┐
+    │  1. PARSE CONDITIONS                     │
+    │     parseStyleEntries + parseStateKey    │
+    └──────────────────────────────────────────┘
+         ↓
+    ┌──────────────────────────────────────────┐
+    │  1b. MERGE ENTRIES BY VALUE              │
+    │     mergeEntriesByValue                  │
+    │     (collapse same-value non-defaults)   │
+    └──────────────────────────────────────────┘
+         ↓
+    ┌──────────────────────────────────────────┐
+    │  2a. EXPAND USER OR BRANCHES             │
+    │     expandOrConditions                   │
+    │     (A | B | C → A, B&!A, C&!A&!B)       │
+    └──────────────────────────────────────────┘
+         ↓
+    ┌──────────────────────────────────────────┐
+    │  2b. BUILD EXCLUSIVE CONDITIONS          │
+    │     Negate higher-priority entries       │
+    └──────────────────────────────────────────┘
+         ↓
+    ┌──────────────────────────────────────────┐
+    │  3. EXPAND DE MORGAN OR BRANCHES         │
+    │     expandExclusiveOrs                   │
+    │     (only for at-rule ORs from negation) │
+    └──────────────────────────────────────────┘
+         ↓
+    ┌──────────────────────────────────────────┐
+    │  4. COMPUTE STATE COMBINATIONS           │
+    │     Cartesian product across styles      │
+    └──────────────────────────────────────────┘
+         ↓
+    ┌──────────────────────────────────────────┐
+    │  5. CALL HANDLERS                        │
+    │     Compute CSS declarations             │
+    └──────────────────────────────────────────┘
+         ↓
+    ┌──────────────────────────────────────────┐
+    │  6. MERGE BY VALUE                       │
+    │     Combine rules with same output       │
+    └──────────────────────────────────────────┘
+         ↓
+    ┌──────────────────────────────────────────┐
+    │  7. MATERIALIZE CSS                      │
+    │     Condition → selectors + at-rules     │
+    └──────────────────────────────────────────┘
+         ↓
+    ┌──────────────────────────────────────────┐
+    │  runPipeline post-pass:                  │
+    │  - dedupe identical rules                │
+    │  - emit @starting-style rules last       │
+    └──────────────────────────────────────────┘
+         ↓
+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.
+
+---
+
+## Stage 0: Pre-parse Normalization
+
+**File:** `exclusive.ts` (`extractCompoundStates`)
+
+### What It Does
+
+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. 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.
+
+### Example
+
+```typescript
+// Input (value map)
+{ '': 'A', '@dark': 'B', '@hc': 'A', '@dark & @hc': 'B' }
+// @hc is a don't-care: its presence never changes the value.
+
+// Output
+{ '': 'A', '@dark': 'B' }
+```
+
+---
+
+## Stage 1: Parse Conditions
+
+**Files:** `exclusive.ts` (`parseStyleEntries`), `parseStateKey.ts` (`parseStateKey`)
+
+### What It Does
+
+Converts each state key in a style value map (like `'hovered & !disabled'`, `'@media(w < 768px)'`) into `ConditionNode` trees. `parseStyleEntries` walks the object keys in source order and assigns priorities; `parseStateKey` parses a single key string.
+
+`parseStyleEntries` also handles the bare `''` default and the standalone `_` fallback floor before the priority order is finalized. The bare `''` default only behaves correctly as the lowest-priority state, so a misplaced one is moved to the front (`MISPLACED_DEFAULT_STATE` warning). The `_` key is pulled out as a separate floor entry (`floor: true`, `TrueCondition`) and always assigned the lowest priority. If a map defines only `_` and a bare `''` (no other states), the `''` default is redundant — it is dropped in favor of the `_` value (`REDUNDANT_DEFAULT_STATE` warning). A `_` combined with state logic (`_ & hovered`, `_ | x`) is ignored (`INVALID_FALLBACK_KEY` warning).
+
+### 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
+
+2. **Recursive Descent Parsing**: Tokens are parsed with operator precedence:
+   ```
+   ! (NOT) > ^ (XOR) > | (OR) > & (AND)
+   ```
+
+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
+
+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)
+
+### Example
+
+```typescript
+// Input
+'hovered & @media(w < 768px)'
+
+// Output ConditionNode
+{
+  kind: 'compound',
+  operator: 'AND',
+  children: [
+    { kind: 'state', type: 'modifier', attribute: 'data-hovered', ... },
+    { kind: 'state', type: 'media', subtype: 'dimension', upperBound: { value: '768px', ... }, ... }
+  ]
+}
+```
+
+---
+
+## Stage 1b: Merge Entries By Value
+
+**File:** `exclusive.ts` (`mergeEntriesByValue`)
+
+### What It Does
+
+Collapses parsed entries that share the same value when doing so provably preserves the authored cascade. Only **non-default** entries are merged — an entry with the default state (`''` → `TrueCondition`) is never merged with a non-default entry.
+
+### How It Works
+
+Entries arrive sorted highest-priority-first. For each entry the pass walks already-emitted entries from most-recent backward, looking for the nearest same-value entry where merging is safe. If found, the two entries collapse into one (priority becomes the maximum of the pair, condition becomes the simplified `OR`). Default entries are emitted as singletons and never participate in a merge.
+
+### The Safety Condition
+
+Merging two same-value entries with conditions `C_h` (higher priority) and `C_l` (lower priority) lifts the lower one up to `p_h` and changes the higher-priority "blocker" for every intermediate-priority entry from `!C_h` to `!(C_h | C_l) = !C_h & !C_l`. The added `!C_l` constraint can incorrectly block an intermediate entry that should have won.
+
+The merge is safe iff for every entry `e_m` strictly between them in priority with a different value,
+
+    simplify(C_m & C_l & !C_h) = FALSE
+
+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.
+
+**Why defaults are kept separate:** merging `TRUE | X` collapses to `TRUE`, destroying X's participation in the exclusive cascade. Intermediate-priority states would then lose their `:not(X)` negation, producing overlapping CSS rules.
+
+### Example — Safe merge (still collapses)
+
+```typescript
+// { '@dark & @hc': 'red', '@dark': 'red' }
+// Input entries (highest priority first), no intermediate different-value entry
+[
+  { stateKey: '@dark & @hc', value: 'red', condition: dark & hc, priority: 1 },
+  { stateKey: '@dark',       value: 'red', condition: dark,      priority: 0 },
+]
+
+// Safe: no intermediates. Output: one merged entry
+[
+  { stateKey: '@dark & @hc | @dark', value: 'red',
+    condition: simplify((dark & hc) | dark) = dark, priority: 1 }
+]
+```
+
+The compound dark/HC dedup pattern `{ '': light, '@dark': dark, '@hc': hc, '@dark & @hc': dark }` also collapses cleanly because `@hc & @dark & !(@dark & @hc)` simplifies to FALSE — the intermediate `@hc` is structurally blocked by the contradiction.
+
+### Example — Unsafe merge (must NOT collapse)
+
+```typescript
+// { hovered: 'red', pressed: 'blue', disabled: 'red' }
+// Authored cascade: disabled > pressed > hovered.
+// Merging hovered (priority 0) with disabled (priority 2) would lift
+// hovered to priority 2 and rewrite `pressed`'s exclusive from
+// `pressed & !disabled` to `pressed & !disabled & !hovered`, making
+// `pressed + hovered` resolve to red instead of blue.
+
+// `simplify(pressed & hovered & !disabled)` is not FALSE — three
+// independent modifiers can all be active — so the entries are kept
+// separate. Stage 6 `mergeByValue` will later combine the two red
+// CSS rules into one selector group, but only after the cascade is
+// correctly resolved.
+```
+
+---
+
+## Stage 2a: Expand User OR Branches
+
+**File:** `exclusive.ts` (`expandOrConditions`)
+
+### What It Does
+
+Runs **before** `buildExclusiveConditions`. Splits any user-authored OR in a parsed entry's condition into multiple sibling entries, each made exclusive against the OR branches that come before it.
+
+### How It Works
+
+For an entry with condition `A | B | C`:
+
+```
+A            (first branch, no prior)
+B & !A       (second branch exclusive from first)
+C & !A & !B  (third branch exclusive from first two)
+```
+
+Each expanded branch gets a `stateKey` suffix like `[0]`, `[1]`, `[2]`. Branches that simplify to `FALSE` are dropped. Branches inherit the original entry's priority.
+
+This pass does **not** sort branches — user ORs are authored in the natural order they appear and aren't the product of De Morgan negation, so at-rule-aware sorting isn't required here (that's Stage 3's job).
+
+### Why
+
+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
+
+**File:** `exclusive.ts` (`buildExclusiveConditions`)
+
+### What It Does
+
+Ensures each style entry applies in exactly one scenario by ANDing each condition with the negation of all higher-priority conditions.
+
+### How It Works
+
+Given entries ordered by priority (highest first):
+```
+A: value1 (priority 2)
+B: value2 (priority 1)
+C: value3 (priority 0)
+```
+
+Produces:
+```
+A: A                    (highest priority, no negation needed)
+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.
+
+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
+
+An entry flagged `floor: true` (from the standalone `_` key) is the one
+exception to the negation cascade above. `buildExclusiveConditions` **pulls the
+floor entries out** before the negation pass, builds the remaining entries with a
+plain unconditional negation loop, then re-appends each floor with its own
+(`TRUE`) condition as the exclusive condition. So the floor **always applies**,
+never receives `!prior`, and never negates lower-priority entries. Because its
+condition is `TRUE`, Stage 1 `mergeEntriesByValue` already leaves it untouched
+(same guard as the bare `''` default), so no floor-specific merge handling is
+needed.
+
+This exists to fix the *unknown-query hole*: CSS three-valued logic makes
+`not(unknown) = unknown`, so a negated `@supports(...)` / container-query default
+branch silently never applies. A `_` floor sidesteps negation entirely and lets
+the positive override layer on top via the cascade (see Stage 7's `:where()`
+equalization and the ascending-priority post-pass).
+
+Because the floor is **additive** (always emitted, never negated) rather than
+mutually exclusive, it differs observably from the `''` default in two ways
+beyond the unknown-query fix: an "empty" higher-priority state (one that emits no
+declarations) cannot unset the property — the floor still applies — and when
+states emit different declaration sets, the floor's declarations bleed through
+wherever a winning state does not override the same property. The `''` default,
+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)
+
+### Example
+
+```typescript
+// Style value mapping
+{ padding: { '': '2x', 'compact': '1x', '@media(w < 768px)': '0.5x' } }
+
+// After exclusive building (highest priority first):
+// @media(w < 768px): applies when media matches
+// compact & !@media(w < 768px): applies when compact but NOT media
+// !compact & !@media(w < 768px): default, applies when neither
+```
+
+---
+
+## Stage 3: Expand De Morgan OR Branches
+
+**File:** `exclusive.ts` (`expandExclusiveOrs`, `sortOrBranchesForExpansion`)
+
+### What It Does
+
+Runs **after** `buildExclusiveConditions`. Handles ORs that arise **during** exclusive building from De Morgan negation — e.g. when a higher-priority condition `A & B` gets negated into the next entry's exclusive as `!(A & B) = !A | !B`. When such an OR mixes **at-rule** context (`media`, `container`, `supports`, `starting`) with other branches, each branch needs to keep its own at-rule wrapping.
+
+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 |
+
+### How It Works
+
+1. Collect top-level OR branches of `exclusiveCondition`.
+2. If there is no OR (single branch), the entry is unchanged. Pure selector ORs with no at-rule context are also left alone (materialization handles them via `:is()` / variant merging).
+3. Otherwise `sortOrBranchesForExpansion` reorders branches by a three-tier rank — `@supports` branches first, then other at-rule branches (media / container / starting), then pure-selector branches. This is load-bearing for correctness (see below).
+4. Each branch is made exclusive against prior branches: `branch & !prior[0] & !prior[1] & ...`, then simplified.
+5. Impossible branches are dropped; expanded entries get a synthetic `stateKey` suffix like `[or:0]`.
+
+### Why the sort matters
+
+**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.
+
+**`@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.
+
+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)`).
+
+The pre-build Stage 2a pass doesn't need this because user-authored ORs aren't produced by negation and their branches are expected to apply in each branch's own scope.
+
+### Example (conceptual)
+
+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
+
+**File:** `index.ts` (`computeStateCombinations`)
+
+### What It Does
+
+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
+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
+
+### Why
+
+Style handlers often depend on multiple style properties (e.g., `padding` might look at both `padding` and `gap`). By computing all valid combinations, we can call the handler once per unique state and get the correct CSS output.
+
+### Example
+
+```typescript
+// Handler looks up: ['padding', 'size']
+// padding has entries: [{ value: '2x', condition: A }, { value: '1x', condition: B }]
+// size has entries: [{ value: 'large', condition: C }, { value: 'small', condition: D }]
+
+// Combinations:
+// { padding: '2x', size: 'large', condition: A & C }
+// { padding: '2x', size: 'small', condition: A & D }
+// { padding: '1x', size: 'large', condition: B & C }
+// { padding: '1x', size: 'small', condition: B & D }
+```
+
+---
+
+## Stage 5: Call Handlers
+
+**File:** `index.ts` (within `processStyles`)
+
+### What It Does
+
+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
+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
+
+**File:** `index.ts` (`mergeByValue`)
+
+### 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
+
+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
+3. Output one rule per group
+
+### Why
+
+Different state combinations might produce the same CSS output. Rather than emitting duplicate CSS, we combine them into a single rule. This reduces CSS size and improves performance.
+
+### Example
+
+```typescript
+// Before merging:
+// condition: A → { color: 'red' }
+// condition: B → { color: 'red' }
+
+// After merging:
+// condition: A | B → { color: 'red' }
+```
+
+---
+
+## Stage 7: Materialize CSS
+
+**File:** `materialize.ts` (`conditionToCSS`, `materializeComputedRule` in `index.ts`)
+
+### What It Does
+
+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
+
+2. **AND / OR on variants**: AND merges variant dimensions; OR yields multiple variants (later merged into `:is()` / `:not()` groups where appropriate).
+
+3. **Contradiction detection**: During variant merging, impossible combinations are dropped (e.g. conflicting media, root, or modifier negations).
+
+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 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
+
+The materialization layer handles these differences while maintaining the logical semantics of the condition tree.
+
+### Output Structure
+
+```typescript
+interface CSSRule {
+  selector: string | string[]; // Selector fragment(s); array when OR’d selector branches
+  declarations: string; // CSS declarations (e.g. 'color: red;')
+  atRules?: string[]; // Wrapping at-rules
+  rootPrefix?: string; // Root state prefix
+  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`.
+
+---
+
+## Condition Types
+
+**File:** `conditions.ts`
+
+### ConditionNode Hierarchy
+
+```
+ConditionNode
+├── TrueCondition     (matches everything)
+├── FalseCondition    (matches nothing)
+├── CompoundCondition (AND/OR of children)
+└── StateCondition
+    ├── ModifierCondition    (data attributes; optional value + match operator)
+    ├── PseudoCondition      (CSS pseudo-classes: :hover)
+    ├── MediaCondition       (subtype: dimension | feature | type)
+    ├── ContainerCondition   (subtype: dimension | style | raw)
+    ├── RootCondition        (inner condition under :root)
+    ├── ParentCondition      (@parent(...); optional direct parent)
+    ├── OwnCondition         (@own(...); scoped to styled / sub-element)
+    ├── SupportsCondition    (@supports(...))
+    └── StartingCondition    (@starting-style wrapper)
+```
+
+### 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
+
+---
+
+## Simplification
+
+**File:** `simplify.ts`
+
+### What It Does
+
+Applies boolean algebra rules to reduce condition complexity and detect impossible combinations.
+
+### Rules Applied
+
+1. **Identity Laws**:
+   - `A & TRUE = A`
+   - `A | FALSE = A`
+
+2. **Annihilator Laws**:
+   - `A & FALSE = FALSE`
+   - `A | TRUE = TRUE`
+
+3. **Contradiction Detection**:
+   - `A & !A = FALSE`
+
+4. **Tautology Detection**:
+   - `A | !A = TRUE`
+
+5. **Idempotent Laws** (via deduplication):
+   - `A & A = A`
+   - `A | A = A`
+
+6. **Absorption Laws**:
+   - `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).
+
+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`
+
+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.
+
+11. **Consensus / resolution** (AND context, dual of #10): `(A | B) & (A | !B) = A`. Added in commit f9038bd to eliminate overlapping CSS selectors from compound-state OR branches.
+
+### Why
+
+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` |
+
+---
+
+## Example Walkthrough
+
+### Input
+
+```typescript
+const styles = {
+  color: {
+    '': '#white',
+    '@media(prefers-color-scheme: dark)': '#dark',
+    hovered: '#highlight',
+  },
+};
+```
+
+### Stage 1: Parse Conditions
+
+```
+'' → TrueCondition
+'@media(prefers-color-scheme: dark)' → MediaCondition(subtype: 'feature', feature: 'prefers-color-scheme', featureValue: 'dark')
+'hovered' → ModifierCondition(attribute: 'data-hovered')
+```
+
+### Stage 0 + 1b: Normalization
+
+No compound AND keys, no same-value duplicates — the value map is unchanged.
+
+### Stage 1 + 2a: Parse and expand user ORs
+
+No user ORs — three entries pass through unchanged.
+
+### Stage 2b + 3: Exclusive conditions + De Morgan expansion
+
+Processing order (highest priority first): `hovered`, `@media(dark)`, default.
+
+```
+hovered: [data-hovered]
+@media(dark) & !hovered: @media(dark) & :not([data-hovered])
+!hovered & !@media(dark): :not([data-hovered]) & not @media(dark)
+```
+
+The default entry's exclusive is `!hovered & !@media(dark)` — no top-level OR, so Stage 3 expansion does nothing. If a higher-priority entry had been `@media(dark) & :has(foo)`, the default's exclusive would have expanded via De Morgan into two at-rule-aware branches (see Stage 3 for that scenario).
+
+### Stages 4–5: Compute combinations and call handler
+
+Single style, three snapshots; the `color` handler emits `color` plus a `--current-color` variable.
+
+### Stage 6: Merge by value
+
+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`):
+
+```css
+.t1[data-hovered] {
+  color: var(--highlight-color);
+  --current-color: var(--highlight-color);
+}
+@media (prefers-color-scheme: dark) {
+  .t1: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);
+  }
+}
+```
+
+---
+
+## Key Design Decisions
+
+### 1. Exclusive Conditions Over CSS Specificity
+
+Rather than relying on CSS cascade rules, we generate mutually exclusive selectors. This makes styling predictable and debuggable.
+
+### 2. OR Handling in Three Layers
+
+Boolean OR appears in three different shapes during the pipeline, and each is handled where it's cheapest to get right:
+
+1. **User-authored ORs in state keys** (Stage 2a, `expandOrConditions`): A user-authored condition like `'compact | @media(w < 768px)'` is split into multiple exclusive entries **before** exclusive building so the negation cascade doesn't have to reason about nested ORs.
+
+2. **De Morgan ORs from negation** (Stage 3, `expandExclusiveOrs`): When `buildExclusiveConditions` negates a higher-priority compound like `A & B`, the result is `!A | !B`. If branches involve at-rules, they're split with `sortOrBranchesForExpansion` so at-rule context is preserved per branch.
+
+3. **Pure selector ORs** (materialization): ORs that only mention modifiers/pseudos are kept intact until the `conditionToCSS` layer, where they're merged into `:is()` / `:not()` groups or emitted as comma-separated selectors. There's no gain from expanding these earlier — CSS already has compact syntax for selector-only disjunction.
+
+Ultimately every emitted CSS rule corresponds to one conjunctive clause (DNF), produced by whichever of the three paths handled the OR.
+
+### 3. Early Contradiction Detection
+
+Impossible combinations are detected at multiple levels (simplification, variant merging) to avoid generating invalid CSS.
+
+### 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.