@cube-dev/ui-kit 0.197.0 → 0.198.0

package/docs/tasty/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/`](../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,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
@@ -520,9 +522,9 @@ Converts condition trees into actual CSS selectors and at-rules.
 
 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;
+   - 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 (`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/tasty/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.
 
 ---

package/docs/tasty/react-api.md

@@ -2,7 +2,7 @@
 
 Use `tasty()` to turn state-aware style definitions into normal React components, extend existing Tasty components, and expose typed styling APIs to consumers.
 
-All Tasty style functions — `tasty()` components, `useStyles()`, `useGlobalStyles()`, `useRawCSS()`, `useKeyframes()`, `useProperty()`, `useFontFace()`, `useCounterStyle()`, and `useFunction()` — are hook-free and compatible with React Server Components. No `'use client'` directive is needed. For state maps, tokens, units, and extension semantics, see [Style DSL](dsl.md). For global configuration, see [Configuration](configuration.md). For the broader docs map, see the [Docs Hub](README.md).
+Every Tasty style function — `tasty()` components, `computeStyles()`, `useStyles()`, `useGlobalStyles()`, `useRawCSS()`, `useKeyframes()`, `useProperty()`, `useFontFace()`, `useCounterStyle()`, and `useFunction()` — works in React Server Components with no `'use client'` directive. All of them except `useStyles()` are hook-free. `useStyles()` reads the `TastyRegistry` collector from React context on the client, so it is a real hook there; outside React, call `computeStyles()` instead. For state maps, tokens, units, and extension semantics, see [Style DSL](dsl.md). For global configuration, see [Configuration](configuration.md). For the broader docs map, see the [Docs Hub](README.md).
 
 > **Note:** This file was previously named `runtime.md`. All functionality documented here works in both server and client contexts — "runtime" referred to style computation during React rendering, not to client-side JavaScript.
 
@@ -44,6 +44,30 @@ const PrimaryButton = tasty(Button, {
 
 Style maps merge intelligently — see [Style DSL — Extending vs. Replacing State Maps](dsl.md#extending-vs-replacing-state-maps) for extend mode, replace mode, `@inherit`, `null`, and `false` tombstones.
 
+The extension form takes the same component options as `tasty({ … })`:
+
+```jsx
+const ActionCard = tasty(Card, {
+  styles: { fill: { '': '#surface', isRaised: '#surface-raised' } },
+  styleProps: ['gap'] as const, // gap="2x" becomes a style
+  modProps: ['isRaised'] as const, // isRaised becomes a mod (data-is-raised)
+  tokenProps: ['accentColor'] as const, // accentColor sets the #accent token
+  variants: {
+    plain: { border: 0 },
+    framed: { border: '2bw #accent' },
+  },
+  variant: 'framed', // applied when no variant prop is passed
+  elements: { Footer: 'footer' },
+});
+
+<ActionCard gap="2x" isRaised accentColor="#purple">
+  <ActionCard.Title>Kept from Card</ActionCard.Title>
+  <ActionCard.Footer>Added here</ActionCard.Footer>
+</ActionCard>;
+```
+
+The extension turns its own `styleProps`, `modProps`, and `tokenProps` into the `styles`, `mods`, and `tokens` it passes to the base, which renders them as usual: mods as `data-*` attributes, tokens as inline custom properties. Its `variants` merge over its `styles`, and the `variant` prop is still forwarded, so it selects the base's own variants too and accepts either set's names. Both sets share that one prop, so a name only one of them defines leaves the other at its fallback: if `Card` had an `accent` variant, `variant="accent"` would apply it together with `framed`, and `variant="plain"` would leave `Card` on its default. For two independent choices, give one of them its own prop, such as a `modProps` value list. `elements` adds sub-components, and the base's are kept: `ActionCard.Title` is `Card.Title`. The returned component is typed with all of these props and sub-components.
+
 `tasty(Component, ...)` always wraps `Component` and forwards every prop to it, so `Component` must be Tasty-aware (i.e. it accepts `styles`, `mods`, `qa`, etc. and renders them through its own Tasty pipeline). To apply styles to a third-party component or a string DOM tag via `className`, use the options-only form with `as`:
 
 ```jsx
@@ -68,7 +92,7 @@ const Span = tasty({
 </Link>;
 ```
 
-The wrapped component only needs to forward `className` (and ideally `style`/`ref`). Tasty-specific props (`qa`, `qaVal`, `mods`, `tokens`, `styleProps`, `modProps`, `tokenProps`) are consumed by Tasty and never leak to the DOM.
+The wrapped component only needs to forward `className` (and ideally `style`/`ref`). Tasty's own props (`styles`, `mods`, `tokens`, `qa`, `qaVal`, `theme`, `element`, the `is*` props) and the props you declared with `styleProps`, `modProps`, or `tokenProps` are consumed by Tasty; mods, `qa`, `qaVal`, `theme`, and `element` reach the DOM only as `data-*` attributes.
 
 Props forwarded to the `as` component keep their declared types and requiredness. For example, a component with `position: 'top-right' | 'bottom-left'` accepts those values through `tasty({ as: Component })`; CSS positioning can still be set through `styles.position`. A prop explicitly listed in `styleProps` is consumed as a style value instead. The always-available base style props below are also consumed by Tasty, so keep component-specific prop names separate from those reserved names.
 
@@ -112,12 +136,12 @@ A small set of style properties — `display`, `font`, `preset`, `hide`, `whiteS
 
 ## `Element`
 
-`Element` is the unstyled base component exported from the main entry — equivalent to `tasty({})` (a `div` with no default styles). It accepts all Tasty props (`styles`, `styleProps`, `mods`, `tokens`, `as`, `qa`, `theme`, the `is*` props, etc.) and is useful as a generic styled box or as a building block for layout primitives.
+`Element` is the unstyled base component exported from the main entry — equivalent to `tasty({})` (a `div` with no default styles). It accepts the props every Tasty component has (`as`, `styles`, `mods`, `tokens`, `qa`, `theme`, the `is*` props) plus the [always-available style props](#always-available-style-props), and is useful as a generic box or as a building block for layout primitives. Other style names, such as `padding`, are not props on it: create a component with `styleProps` for those, or pass them through `styles`.
 
 ```jsx
 import { Element } from '@tenphi/tasty';
 
-<Element as="section" padding="4x" fill="#surface">
+<Element as="section" display="grid" preset="t2" styles={{ padding: '4x' }}>
   Content
 </Element>;
 ```
@@ -144,6 +168,7 @@ List modifier key names. Types default to `ModValue` (`boolean | string | number
 
 ```jsx
 const Button = tasty({
+  as: 'button',
   modProps: ['isLoading', 'isSelected'] as const,
   styles: {
     fill: { '': '#surface', isLoading: '#surface.5' },
@@ -161,6 +186,7 @@ Map modifier names to type descriptors for precise TypeScript types:
 
 ```tsx
 const Button = tasty({
+  as: 'button',
   modProps: {
     isLoading: Boolean, // isLoading?: boolean
     isSelected: Boolean, // isSelected?: boolean
@@ -297,6 +323,24 @@ const Button = tasty({
 <Button variant="danger">Delete</Button>;
 ```
 
+With `variant` omitted, or set to a key `variants` does not define, the `default` variant applies; without a `default` key only the base `styles` apply. `variant` is typed from the variant keys.
+
+To fall back to another variant instead, name it in the `variant` option:
+
+```jsx
+const Button = tasty({
+  styles: { padding: '2x 4x' },
+  variants: {
+    primary: { fill: '#blue', color: '#white' },
+    danger: { fill: '#red', color: '#white' },
+  },
+  variant: 'primary',
+});
+
+<Button>Save</Button>; // primary
+<Button variant="danger">Delete</Button>;
+```
+
 ### Extending Variants with Base State Maps
 
 When base `styles` contain an extend-mode state map (an object **without** a `''` key), it is applied **after** the variant merge. This lets you add or override states across all variants without repeating yourself:
@@ -401,19 +445,19 @@ const { className } = computeStyles({
 });
 ```
 
-On the client, CSS is injected synchronously into the DOM (idempotent via the injector cache). On the server, CSS is collected via the SSR collector if one is available. This is the same function that `tasty()` components use internally.
+On the client, CSS is injected synchronously into the DOM (idempotent via the injector cache). On the server with an SSR collector (from `runWithCollector()` or `TastyRegistry`), the CSS goes to the collector. With neither a collector nor a `document` — a React Server Component — nothing is injected: the CSS comes back as `css`, and you render it in a `style` tag yourself, as `tasty()` components do. This is the same function that `tasty()` components use internally.
 
 ---
 
 ## Style Functions
 
-All style functions below are plain functions (not React hooks) and can be used in any environment: client components, SSR with a `ServerStyleCollector`, and React Server Components. They retain their `use` prefix for backward compatibility, but do not use any React hooks internally.
+All style functions below work in client components, SSR with a `ServerStyleCollector`, and React Server Components. All except `useStyles()` are plain functions, not React hooks; they keep the `use` prefix for backward compatibility.
 
 In server-only contexts, components that use only Tasty style functions ship no Tasty styling runtime. Astro without `client:*` directives produces no client JavaScript; server-only Next.js RSC follows the same Tasty architecture, while final output depends on the application deployment. Tasty never forces the `'use client'` boundary — that decision belongs to your component when it needs React interactivity (state, effects, event handlers).
 
 ### useStyles
 
-Generate a className from a style object. Thin wrapper around `computeStyles()`:
+Generate a className from a style object. A thin wrapper around `computeStyles()` that also picks up the `TastyRegistry` collector through React context. That makes it a hook on the client: call it inside a component, and use `computeStyles()` outside React. It also works in a Server Component, where it skips the context lookup; like the other style functions there, it cannot emit CSS itself, so the next `tasty()` element in the tree emits it.
 
 ```tsx
 import { useStyles } from '@tenphi/tasty';
@@ -447,6 +491,17 @@ function ThemeStyles() {
 }
 ```
 
+The selector can be a list (`'.uni-checkbox, uni-checkbox'`) — every item gets
+the states and sub-elements, with no `:is()` wrapping needed. Root states
+(`@root(...)`) on a selector that is the root itself (`:root`, `html`) apply to
+that element. A selector that ends in a pseudo-element takes its states on the
+pseudo-element (`'.card::before'` with `:hover` gives
+`.card::before:where(:hover)`) and `@parent()` on the element before it.
+Attribute and modifier states, which a pseudo-element can't have, are ignored
+with a warning. Local `@keyframes` are injected with the rules,
+under the same resolved names `tasty()` components use, and `@starting` states
+emit `@starting-style`.
+
 A slot — the `id`, or the selector when no `id` is given — holds exactly one
 injection **per `root`**. So:
 
@@ -475,6 +530,8 @@ function GlobalReset() {
 An `id` slot holds one injection per `root`. Without an `id` the CSS is deduped
 by content and permanent — there is nothing to replace it with later.
 
+It also accepts a factory and deps — `useRawCSS(() => css, [deps], { id })` — and skips the factory while the deps for that `id` are unchanged.
+
 ### useKeyframes
 
 Inject `@keyframes` rules and return the generated animation name:
@@ -584,7 +641,11 @@ useFontFace('Brand Sans', [
 Signature:
 
 ```ts
-function useFontFace(family: string, input: FontFaceInput): void;
+function useFontFace(
+  family: string,
+  input: FontFaceInput,
+  options?: { root?: Document | ShadowRoot },
+): void;
 ```
 
 ### useCounterStyle
@@ -666,9 +727,10 @@ See the [Functions section of the DSL reference](dsl.md#functions-function) for
 
 - Styles are not updating: make sure `configure()` runs before first render, and verify the generated class name or global rule with [Debug Utilities](debug.md).
 - SSR output looks wrong: check the [SSR guide](ssr.md) for collector setup. All style functions discover the SSR collector via `AsyncLocalStorage` or the global getter registered by `TastyRegistry`.
+- "Server rendering without a style collector" in development: the server render has no request scope, so each `tasty()` element inlines its own CSS and configured globals are not emitted. Add `tastyIntegration()` (Astro), `TastyRegistry` (Next.js), or `runWithCollector()` — see the [SSR guide](ssr.md).
 - Animation/custom property issues: prefer `useKeyframes()` and `useProperty()` over raw CSS when you want Tasty to manage injection and SSR collection for you.
 - For dynamic styles that change over the component lifecycle, use the `id` option in `useGlobalStyles()` and `useRawCSS()` to enable update tracking.
-- RSC inline mode: CSS accumulated by standalone style functions (`useGlobalStyles`, `useRawCSS`, etc.) is flushed into inline `<style>` tags by the next `tasty()` component in the render tree. If your page uses only standalone style functions without any `tasty()` component, the CSS will not be emitted. Ensure at least one `tasty()` component is present in each RSC render tree.
+- RSC inline mode: CSS accumulated by standalone style functions (`useStyles`, `useGlobalStyles`, `useRawCSS`, etc.) is flushed into inline `<style>` tags by the next `tasty()` component in the render tree. If your page uses only standalone style functions without any `tasty()` component, the CSS will not be emitted. Ensure at least one `tasty()` component is present in each RSC render tree.
 
 ---
 
@@ -677,6 +739,7 @@ See the [Functions section of the DSL reference](dsl.md#functions-function) for
 - **[Style DSL](dsl.md)** — State maps, tokens, units, extending semantics, keyframes, @property
 - **[Methodology](methodology.md)** — Recommended patterns: root + sub-elements, styleProps, tokens, wrapping
 - **[Configuration](configuration.md)** — Tokens, recipes, custom units, style handlers, TypeScript extensions
+- **[Configuration → TypeScript](configuration.md#typescript)** — How props are typed and how to register your names
 - **[Style Properties](styles.md)** — Complete reference for all enhanced style properties
 - **[Build-Time Extraction (`tastyStatic`)](tasty-static.md)** — Static styling with the Babel plugin
 - **[Server-Side Rendering](ssr.md)** — SSR setup for Next.js, Astro, and generic frameworks

package/docs/tasty/runtime-benchmarks.md

@@ -80,9 +80,9 @@ cold cases. These benchmarks do not include React, DOM work, stylesheet
 injection, style resolution, layout, or paint.
 
 The benchmark sources are colocated with the code they exercise:
-[`pipeline.bench.ts`](../src/pipeline/pipeline.bench.ts),
-[`parseStateKey.bench.ts`](../src/pipeline/parseStateKey.bench.ts), and the
-parser benchmark files under [`src/parser`](../src/parser).
+[`pipeline.bench.ts`](https://github.com/tenphi/tasty/blob/main/src/pipeline/pipeline.bench.ts),
+[`parseStateKey.bench.ts`](https://github.com/tenphi/tasty/blob/main/src/pipeline/parseStateKey.bench.ts), and the
+parser benchmark files under [`src/parser`](https://github.com/tenphi/tasty/tree/main/src/parser).
 
 ## Empty Wrapper Overhead
 
@@ -91,7 +91,7 @@ Skipping the style pipeline does not make a `tasty()` component free. Even
 tracks another fiber, and Tasty still processes and forwards the element's
 props.
 
-[`tasty-overhead.bench.tsx`](../src/tasty-overhead.bench.tsx) compares 10,000
+[`tasty-overhead.bench.tsx`](https://github.com/tenphi/tasty/blob/main/src/tasty-overhead.bench.tsx) compares 10,000
 raw `<div className>` siblings with 10,000 instances of one module-scoped
 `tasty({})` component. Both receive the same props, and the benchmark fails if
 they do not produce equivalent DOM.
@@ -125,7 +125,7 @@ snapshot experiment with controlled garbage collection.
 
 ## Cold Generation and Injection
 
-[`tasty-injection.bench.ts`](../src/tasty-injection.bench.ts) measures the extra
+[`tasty-injection.bench.ts`](https://github.com/tenphi/tasty/blob/main/src/tasty-injection.bench.ts) measures the extra
 work when Tasty must generate and inject CSS that an otherwise equivalent page
 already has. It does not compare different stylesheet insertion techniques.
 
@@ -197,11 +197,11 @@ The benchmarks above measure mounting and whole-tree updates. A running
 application spends most of its time on neither. It flips mods — hovered,
 pressed, selected, expanded — on elements whose styles never change, one
 element at a time, and it mounts and unmounts small styled subtrees as menus
-and dialogs open. Both paths go through the state-map and ref-counting
-machinery rather than the parser, so a regression in them is invisible to every
+and dialogs open. Both paths go through mod handling and the chunk cache
+rather than the parser, so a regression in them is invisible to every
 other benchmark here.
 
-[`tasty-interaction.bench.tsx`](../src/tasty-interaction.bench.tsx) pairs each
+[`tasty-interaction.bench.tsx`](https://github.com/tenphi/tasty/blob/main/src/tasty-interaction.bench.tsx) pairs each
 case with a raw-DOM equivalent driven by a hand-written stylesheet that
 produces the same computed color and background in both states. The benchmark
 fails if either arm resolves to anything else, so an arm that quietly rendered
@@ -255,7 +255,7 @@ reopening a menu re-pays the React wrapper, not the style pipeline.
 ## Page-Load Cold Start
 
 Every benchmark above deliberately excludes the network, module compilation and
-the first render. [`scripts/cold-start`](../scripts/cold-start) measures exactly
+the first render. [`scripts/cold-start`](https://github.com/tenphi/tasty/tree/main/scripts/cold-start) measures exactly
 those: what a visitor waits for between requesting a page and seeing styled
 content, in a real Chromium under CDP network and CPU throttling.
 
@@ -371,8 +371,8 @@ blindly. They describe different paths:
   rule.
 - A genuinely new style pays generation and injection once, then becomes
   reusable.
-- A mod flip on an already-styled element pays neither; it is a class-name
-  change.
+- A mod flip on an already-styled element pays neither; it toggles a `data-*`
+  attribute and the class stays the same.
 - Browser style resolution, layout, and paint depend on the actual document and
   need application-level profiling.