@tenphi/tasty 3.9.11 → 3.11.0

package/docs/injector.md

@@ -10,10 +10,10 @@ The Style Injector is the core engine behind Tasty's styling system, providing:
 
 - **Hash-based deduplication** - Identical CSS gets the same className
 - **DOM-driven lifetime** - Styles are collected once nothing renders them
-- **CSS nesting flattening** - Handles `&`, `.Class`, `SubElement` patterns
+- **Selector assembly** - Prepends the doubled `.tX.tX` class and root prefix to the pipeline's selector fragments (sub-element and `&` nesting is flattened earlier, by the pipeline)
 - **At-rule injection** - First-class `@keyframes`, `@property`, `@font-face`, `@counter-style`, and `@function` support
 - **Smart cleanup** - CSS rules batched cleanup, keyframes disposed immediately
-- **SSR support** - Deterministic class names and CSS extraction
+- **SSR support** - Deterministic class names shared with `ServerStyleCollector`, and hydration of server-rendered classes
 - **Multiple roots** - Works with Document and ShadowRoot
 - **Non-stacking cleanups** - Prevents timeout accumulation for better performance
 
@@ -55,13 +55,15 @@ Injects CSS rules and returns a className with dispose function.
 ```typescript
 import { inject } from '@tenphi/tasty';
 
-// Component styling - generates tasty class names
+// Rules flagged needsClassName get the generated class prepended (doubled)
 const result = inject([{
-  selector: '.t-abc123',
+  selector: '',
   declarations: 'color: red; padding: 10px;',
+  needsClassName: true,
 }]);
 
-console.log(result.className); // 't-abc123'
+console.log(result.className); // 'th8n0uh' — `t` + base36 hash of the rules
+// Injected: .th8n0uh.th8n0uh { color: red; padding: 10px; }
 
 // Release the pin; the class becomes collectible once nothing renders it
 result.dispose();
@@ -175,7 +177,7 @@ const result = testInjector.inject(rules);
 Injects CSS keyframes with automatic deduplication.
 
 ```typescript
-// Generated name (k0, k1, k2...)
+// Generated name (tk0, tk1, … — namePrefix + 'k' + counter)
 const fadeIn = keyframes({
   from: { opacity: 0 },
   to: { opacity: 1 },
@@ -253,6 +255,7 @@ Dispose, ref-counted cleanup and GC therefore behave identically in every mode.
 - **Configuration is locked after styles are generated** - calling `configure()` after first render will emit a warning and be ignored
 - `gc.touchInterval`: Number of renders between sweeps. When the counter reaches this value, a sweep is scheduled via `requestIdleCallback`; without idle callbacks nothing is collected automatically.
 - `gc.grace`: How long a class is left alone after collection first notices nothing is carrying it, in milliseconds (default `10000`).
+- Automatic sweeps are opt-in: they run only when `configure({ gc })` is set (`gc: {}` enables them with these defaults). Without it nothing is collected until you call `gc()` or `cleanup()`.
 
 **What a sweep does.** Everything the injector holds falls into one of five bands, and only the last is ever deleted:
 
@@ -289,7 +292,7 @@ Beyond ordinary rules, the injector has a dedicated entry point per at-rule. All
 
 Every one of these takes an optional `root` (a `Document` or `ShadowRoot`).
 
-`func()` also accepts `weak: true`, which registers the rule **without** overriding an existing one of the same name. `configure()` uses it for global `@function` definitions so a component-local definition always wins over the global default, regardless of which is injected first.
+`counterStyle()` and `func()` also accept `weak: true`, which registers the rule **without** overriding an existing one of the same name. `configure()` uses it for global `@counter-style` and `@function` definitions so a component-local definition always wins over the global default, regardless of which is injected first.
 
 ```ts
 import { counterStyle, fontFace, func, property } from '@tenphi/tasty';
@@ -306,22 +309,24 @@ func('$$negative', { args: ['$value'], result: '(-1 * $value)' });
 
 ### Style Result Format
 
-The injector works with `StyleResult` objects from the tasty parser:
+The injector works with `StyleResult` objects from the pipeline (`renderStyles`):
 
 ```typescript
 interface StyleResult {
-  selector: string;              // CSS selector
-  declarations: string;          // CSS declarations
-  atRules?: string[];           // @media, @supports, etc.
-  nestingLevel?: number;        // Nesting depth for specificity
+  selector: string;          // full selector, or a fragment when needsClassName
+  declarations: string;      // CSS declarations
+  atRules?: string[];        // @media, @container, @supports, …
+  needsClassName?: boolean;  // prepend the generated `.tX.tX` (OR'd fragments joined with '|||')
+  rootPrefix?: string;       // root-state prefix placed before the class
+  startingStyle?: boolean;   // wrap declarations in @starting-style
 }
 
 // Example StyleResult
 const styleRule: StyleResult = {
-  selector: '.t-button',
+  selector: ':where([data-hovered])',
   declarations: 'padding: 8px 16px; background: blue; color: white;',
   atRules: ['@media (min-width: 768px)'],
-  nestingLevel: 0,
+  needsClassName: true,
 };
 ```
 
@@ -339,28 +344,24 @@ API here calls it for you.
 ### Deduplication & Performance
 
 ```typescript
-// Identical CSS rules get the same className
-const button1 = inject([{
-  selector: '.t-btn1',
-  declarations: 'padding: 8px; color: red;'
-}]);
+const rule = { selector: '', declarations: 'padding: 8px; color: red;', needsClassName: true };
 
-const button2 = inject([{
-  selector: '.t-btn2', 
-  declarations: 'padding: 8px; color: red;' // Same declarations
-}]);
+const button1 = inject([rule], { cacheKey: 'button' });
+const button2 = inject([rule], { cacheKey: 'button' });
 
-// Both get the same className due to deduplication
+// One class, one copy of the CSS
 console.log(button1.className === button2.className); // true
 ```
 
+Without `cacheKey` the class name still matches (it hashes the rules), but the rule is inserted again and the pin count restarts at 1.
+
 ### Pinning
 
 ```typescript
 // Multiple callers using the same styles
-const comp1 = inject([commonStyle]);
-const comp2 = inject([commonStyle]);
-const comp3 = inject([commonStyle]);
+const comp1 = inject([commonStyle], { cacheKey: 'common' });
+const comp2 = inject([commonStyle], { cacheKey: 'common' });
+const comp3 = inject([commonStyle], { cacheKey: 'common' });
 
 // Style is pinned while any caller holds a handle
 comp1.dispose(); // pins: 3 → 2
@@ -439,15 +440,16 @@ const shadowAnimation = keyframes({
 
 ### Server-Side Rendering
 
+`getCSSText()` reads the injector's stylesheets, so it needs a DOM; on a server it throws. Collect server CSS with `ServerStyleCollector` from `@tenphi/tasty/ssr` (`collector.getCSS()`) — see [SSR](./ssr.md).
+
 ```typescript
 import { getCSSText, getCSSTextForNode } from '@tenphi/tasty';
+import { render } from '@testing-library/react';
 
-// Extract all CSS for SSR
-const cssText = getCSSText();
+const cssText = getCSSText(); // everything the injector holds (browser / test DOM)
 
-// Extract CSS for specific DOM subtree (like jest-styled-components)
-const container = render(<MyComponent />);
-const componentCSS = getCSSTextForNode(container);
+const { container } = render(<MyComponent />);
+const componentCSS = getCSSTextForNode(container); // only the CSS this subtree uses
 ```
 
 ### Test Environment Detection
@@ -520,17 +522,14 @@ console.log({
 ### Debug Information
 
 ```typescript
-// Get detailed information about injected styles
-const debugInfo = injector.instance.getDebugInfo();
+import { tastyDebug } from '@tenphi/tasty';
 
-console.log({
-  activeStyles: debugInfo.activeStyles,     // Currently active styles
-  unusedStyles: debugInfo.unusedStyles,     // Styles marked for cleanup
-  totalSheets: debugInfo.totalSheets,       // Number of stylesheets
-  totalRules: debugInfo.totalRules,         // Total CSS rules
-});
+const { activeClasses, unusedClasses, hotClasses, totalRuleCount } =
+  tastyDebug.summary({ raw: true });
 ```
 
+See [Debug Utilities](./debug.md).
+
 ### Cleanup History
 
 ```typescript

package/docs/methodology.md

@@ -119,16 +119,17 @@ Style props accept state maps, so responsive values work through the same API:
 
 Tasty exports predefined style prop lists that group properties by role. Use them instead of hand-picking arrays:
 
-| Preset             | Properties                                                                                                                                                                     | Typical use                                   |
-| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------- |
-| `FLOW_STYLES`      | flow, gap, columnGap, rowGap, align, justify, placeItems, placeContent, alignItems, alignContent, justifyItems, justifyContent, gridColumns, gridRows, gridTemplate, gridAreas | Layout containers (`Space`, `Grid`)           |
-| `POSITION_STYLES`  | gridArea, gridColumn, gridRow, order, placeSelf, alignSelf, justifySelf, zIndex, physical/logical margin, inset, scroll margin/padding, position                                 | Positioned elements (`Button`, `Badge`)       |
-| `DIMENSION_STYLES` | width, height, blockSize, inlineSize, flexBasis, flexGrow, flexShrink, flex                                                                                                    | Sized elements                                |
-| `COLOR_STYLES`     | color, fill, fade, image                                                                                                                                                       | Color-customizable elements                   |
-| `BLOCK_STYLES`     | padding, blockPadding, inlinePadding, overflow, scrollbar, textAlign, border, blockBorder, inlineBorder, radius, shadow, outline                                               | Block-level containers                        |
-| `CONTAINER_STYLES` | All of the above combined (+ BASE_STYLES)                                                                                                                                      | Fully flexible containers                     |
-| `OUTER_STYLES`     | POSITION_STYLES + DIMENSION_STYLES + block outer (border, radius, shadow, outline)                                                                                             | Components whose outer shell is customizable  |
-| `INNER_STYLES`     | BASE_STYLES + COLOR_STYLES + block inner (padding, overflow, scrollbar) + FLOW_STYLES                                                                                          | Components whose inner layout is customizable |
+| Preset             | Properties                                                                                                                                                                            | Typical use                                   |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
+| `FLOW_STYLES`      | flow, gap, columnGap, rowGap, align, justify, place, placeItems, placeContent, alignItems, alignContent, justifyItems, justifyContent, gridColumns, gridRows, gridTemplate, gridAreas | Layout containers (`Space`, `Grid`)           |
+| `POSITION_STYLES`  | gridArea, gridColumn, gridRow, order, placeSelf, alignSelf, justifySelf, zIndex, physical/logical margin, inset, scroll margin/padding, position                                      | Positioned elements (`Button`, `Badge`)       |
+| `DIMENSION_STYLES` | width, height, blockSize, inlineSize, flexBasis, flexGrow, flexShrink, flex                                                                                                           | Sized elements                                |
+| `COLOR_STYLES`     | color, fill, fade, image                                                                                                                                                              | Color-customizable elements                   |
+| `BLOCK_STYLES`     | padding, blockPadding, inlinePadding, overflow, scrollbar, textAlign, border, blockBorder, inlineBorder, radius, shadow, outline                                                      | Block-level containers                        |
+| `TEXT_STYLES`      | textTransform, fontWeight, fontStyle                                                                                                                                                  | Text elements                                 |
+| `CONTAINER_STYLES` | All of the above combined (+ BASE_STYLES)                                                                                                                                             | Fully flexible containers                     |
+| `OUTER_STYLES`     | POSITION_STYLES + DIMENSION_STYLES + block outer (border, radius, shadow, outline)                                                                                                    | Components whose outer shell is customizable  |
+| `INNER_STYLES`     | BASE_STYLES + COLOR_STYLES + block inner (padding, overflow, scrollbar) + FLOW_STYLES                                                                                                 | Components whose inner layout is customizable |
 
 ```tsx
 import { tasty, FLOW_STYLES, POSITION_STYLES } from '@tenphi/tasty';
@@ -156,7 +157,10 @@ Match the preset to the component's role:
 
 - **Layout containers** (`Space`, `Box`, `Grid`) — `FLOW_STYLES`, optionally with `DIMENSION_STYLES`
 - **Positioned elements** (`Button`, `Badge`) — `POSITION_STYLES`
-- **Text elements** — custom: `['preset', 'color']`
+- **Text elements** — `['color', ...TEXT_STYLES]`
+
+`BASE_STYLES` (`display`, `font`, `preset`, `hide`, `whiteSpace`, `opacity`, `transition`) are accepted as props on every component without being listed; extend that set app-wide with [`configure({ baseStyleProps })`](configuration.md#base-style-props).
+
 - **Compound components** — typically none; styling happens via sub-elements and extension
 
 ### The governance trade-off
@@ -220,6 +224,26 @@ modProps: ['isLoading', 'isSelected'] as const,
 
 For the full API reference, see [React API — Mod Props](react-api.md#mod-props).
 
+### variants vs modProps
+
+Use `variants` for looks that replace each other (primary, danger, ghost) and `modProps` for states that combine (`isLoading`, `size`):
+
+```tsx
+const Button = tasty({
+  as: 'button',
+  modProps: { isLoading: Boolean, size: ['sm', 'md', 'lg'] as const },
+  styles: { padding: { '': '1.5x 3x', 'size=sm': '1x 2x' }, radius: '1r' },
+  variants: {
+    default: { fill: '#primary', color: '#on-primary' },
+    danger: { fill: '#danger', color: '#on-danger' },
+  },
+});
+
+<Button variant="danger" size="sm" isLoading />;
+```
+
+`variant` is typed from the variant keys, the `default` variant applies when no `variant` prop is passed, and only variants that render emit CSS. See [React API — Variants](react-api.md#variants).
+
 ---
 
 ## tokens prop for dynamic values
@@ -335,10 +359,9 @@ const LargeCard = tasty(Card, {
 
 Why? Styled wrappers are:
 
-- **Faster** — styles are parsed and injected once at definition time, not on every render
-- **Stable** — the style object is defined once, not recreated on every render
+- **Stable** — the style object is defined once at module level, not recreated on every render
 - **Composable** — another engineer can extend `LargeCard` further
-- **Inspectable** — the component has a name in React DevTools
+- **Inspectable** — give it a `qa` (`tasty(Card, { qa: 'LargeCard', styles })`) and it appears as `TastyWrappedComponent(LargeCard)` in React DevTools and as `data-qa="LargeCard"` in the DOM
 - **Lint-friendly** — the ESLint plugin's `no-styles-prop` rule flags direct usage
 
 The `styles` prop exists as an escape hatch — for prototyping, one-off overrides during development, or cases where wrapping is impractical. It should not be the default way product engineers customize components.
@@ -453,11 +476,13 @@ const DangerCard = tasty(Card, {
 
 This is preferred over `<Card styles={{ border: '1bw solid #danger' }}>` because:
 
-1. Styles are parsed and injected once, not on every render
+1. The styles live in one module-level definition instead of being rebuilt inside render
 2. `DangerCard` can be extended further by others
-3. It has a meaningful name in DevTools and code search
+3. It is searchable in code, and named in DevTools once you give it a `qa`
 4. The ESLint `no-styles-prop` rule encourages this pattern
 
+A wrapper does not re-expose the base's sub-element components: `DangerCard.Title` is `undefined` and not part of its type. Keep using the base's parts inside it — `<DangerCard><Card.Title>…</Card.Title></DangerCard>`. The wrapper's `Title` styles still apply, because they target `[data-element="Title"]`.
+
 ---
 
 ## How configuration simplifies components
@@ -554,7 +579,7 @@ fill: 'oklch(55% 0.25 265)',
 fill: '#primary',
 ```
 
-Tokens ensure consistency across components and make theme changes a one-line update.
+Tokens ensure consistency across components and make theme changes a one-line update. The recommended lint config flags this with `tasty/no-raw-color-values` and `tasty/consistent-token-usage`.
 
 ### Using CSS property names when Tasty alternatives exist
 
@@ -570,7 +595,7 @@ radius: '1r',
 flow: 'column',
 ```
 
-Tasty's enhanced properties provide concise syntax, better composability, and simpler overrides. See [recommended props](styles.md#recommended-props) for the full mapping.
+Tasty's enhanced properties provide concise syntax, better composability, and simpler overrides. See [recommended props](styles.md#recommended-props) for the full mapping. `tasty/prefer-shorthand-property` flags the native spellings.
 
 ### Changing styles prop at runtime
 
@@ -593,7 +618,7 @@ const Card = tasty({
 });
 ```
 
-Modifiers are compiled into exclusive selectors once. Changing `styles` at runtime forces Tasty to regenerate and re-inject CSS.
+Modifiers are compiled into exclusive selectors once. Changing `styles` at runtime forces Tasty to regenerate and re-inject CSS. `tasty/no-styles-prop` and `tasty/no-runtime-styles-mutation` flag these patterns.
 
 ### Overusing style prop
 
@@ -607,7 +632,7 @@ const DangerButton = tasty(Button, {
 });
 ```
 
-The `style` prop bypasses tokens, units, and state maps. It should only be used for third-party library integration.
+The `style` prop bypasses tokens, units, and state maps. It should only be used for third-party library integration. `tasty/no-style-prop` flags it on Tasty components.
 
 ### Skipping elements for compound components
 

package/docs/migration-v3.md

@@ -188,8 +188,8 @@ A key whose prefix doesn't match its value type is ignored with a development wa
 ## 7. Moved subpath
 
 ```diff
-- import { withTasty } from '@tenphi/tasty/next';
-+ import { withTasty } from '@tenphi/tasty/zero/next';
+- import { withTastyZero } from '@tenphi/tasty/next';
++ import { withTastyZero } from '@tenphi/tasty/zero/next';
 ```
 
 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.

package/docs/pipeline.md

@@ -76,7 +76,7 @@ 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.
 
 ---
 
@@ -197,7 +197,9 @@ Merging two same-value entries with conditions `C_h` (higher priority) and `C_l`
 
 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
+```
+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.
 
@@ -362,7 +364,7 @@ This is the companion to **Stage 2a** (user-OR expansion). The split exists beca
 
 | Stage | Runs on | Sees ORs from | Sorts branches? |
 |---|---|---|---|
-| 2a `expandOrConditions` | `ParsedStyleEntry.condition` | User-authored `|` in state keys | No — user order is stable |
+| 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
@@ -522,7 +524,7 @@ Converts condition trees into actual CSS selectors and at-rules.
    - 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 `@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.
 
@@ -545,12 +547,13 @@ 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`).
 
 ---
 
@@ -618,7 +621,7 @@ Applies boolean algebra rules to reduce condition complexity and detect impossib
    - `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).
 
@@ -642,7 +645,7 @@ 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 |
+| `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 |
@@ -702,24 +705,24 @@ 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);
 }
 ```
 

package/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.
 
 ---
 
@@ -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.
 
 ---