@cube-dev/ui-kit 0.126.0 → 0.127.0

package/docs/tasty/comparison.md

@@ -29,14 +29,14 @@ That is why syntax-level comparisons are often shallow. The more meaningful comp
 
 ## High-level positioning
 
-| System | Best described as | Main authoring model | Conflict model | Best fit |
-|---|---|---|---|---|
-| **Tasty** | Design-system styling engine | Custom DSL with tokens, state maps, recipes, style props, sub-elements, custom units | **Mutually exclusive selector resolution** for stateful styles | Teams building shared component APIs or a house styling language |
-| **Tailwind CSS** | Utility-first styling framework | Utility classes in markup | Utility composition, variants, and framework-controlled ordering | Product teams optimizing for speed and direct authoring |
-| **Panda CSS** | Typed styling engine with atomic output | Typed style objects, recipes, generated primitives, style props | Atomic CSS with static analysis | Teams wanting a DS-friendly engine with typed primitives |
-| **vanilla-extract** | Zero-runtime TS-native stylesheet system | `.css.ts` files, theme contracts, style composition | Standard CSS semantics | Teams wanting static CSS and low-level control |
-| **StyleX** | Compiler-based atomic styling system | JS authoring with compiler-generated atomic CSS | Compiler-controlled atomic composition | Large app teams wanting optimized, predictable atomic styling |
-| **Stitches** (deprecated) **/ Emotion** | Component-first CSS-in-JS | Styled components, `css()` APIs, object/string styles | Composition within CSS-in-JS rules | Teams optimizing for component DX and flexible styling |
+| System | Best described as | Main authoring model | Conflict model | RSC / zero-JS SSG | Best fit |
+|---|---|---|---|---|---|
+| **Tasty** | Design-system styling engine | Custom DSL with tokens, state maps, recipes, style props, sub-elements, custom units | **Mutually exclusive selector resolution** for stateful styles | Yes — hook-free, server components by default | Teams building shared component APIs or a house styling language |
+| **Tailwind CSS** | Utility-first styling framework | Utility classes in markup | Utility composition, variants, and framework-controlled ordering | Yes — no JS runtime | Product teams optimizing for speed and direct authoring |
+| **Panda CSS** | Typed styling engine with atomic output | Typed style objects, recipes, generated primitives, style props | Atomic CSS with static analysis | Yes — build-time extraction | Teams wanting a DS-friendly engine with typed primitives |
+| **vanilla-extract** | Zero-runtime TS-native stylesheet system | `.css.ts` files, theme contracts, style composition | Standard CSS semantics | Yes — build-time extraction | Teams wanting static CSS and low-level control |
+| **StyleX** | Compiler-based atomic styling system | JS authoring with compiler-generated atomic CSS | Compiler-controlled atomic composition | Yes — compiler-extracted | Large app teams wanting optimized, predictable atomic styling |
+| **Stitches** (deprecated) **/ Emotion** | Component-first CSS-in-JS | Styled components, `css()` APIs, object/string styles | Composition within CSS-in-JS rules | No — requires `'use client'` | Teams optimizing for component DX and flexible styling |
 
 ---
 
@@ -92,7 +92,7 @@ That makes Tasty less of a "better way to write CSS objects" and more of a **sta
 Beyond state resolution, Tasty also provides several structural capabilities that reinforce the design-system layer:
 
 - **CSS properties as typed React props** — `styleProps` lets a component expose selected style properties as normal props (`<Button placeSelf="end">`), including state maps for responsive values. This keeps layout and composition controls inside a governed component API instead of pushing teams back to ad hoc styling escapes.
-- **Sub-element styling** — Compound components declare inner parts via capitalized keys in `styles` and `data-element` attributes. States, tokens, and recipes apply across the entire element tree from a single definition. See [Runtime API — Sub-element Styling](runtime.md#sub-element-styling).
+- **Sub-element styling** — Compound components declare inner parts via capitalized keys in `styles` and `data-element` attributes. States, tokens, and recipes apply across the entire element tree from a single definition. See [React API — Sub-element Styling](react-api.md#sub-element-styling).
 - **Auto-inferred `@property`** — When a custom property is assigned a concrete value, Tasty infers the CSS `@property` syntax and registers it automatically, enabling smooth transitions on custom properties without manual declarations.
 - **AI-friendly style definitions** — Style definitions are declarative, self-contained, and structurally consistent. AI tools can read, refactor, and generate Tasty styles as confidently as a human — no hidden cascade logic or implicit ordering to second-guess.
 - **Companion ecosystem** — An [ESLint plugin](https://github.com/tenphi/eslint-plugin-tasty) with 27 lint rules, a [VS Code extension](https://github.com/tenphi/tasty-vscode-extension) for syntax highlighting, and [Glaze](https://github.com/tenphi/glaze) for OKHSL color theme generation with automatic WCAG contrast solving.
@@ -235,13 +235,12 @@ Tasty is more opinionated.
 
 It behaves less like "TypeScript that outputs CSS" and more like a **state-aware style compiler**. It is designed to encode higher-level styling semantics rather than only expose CSS primitives in typed form.
 
-This also makes Tasty's static mode notable:
+This also makes Tasty's rendering model notable:
 
-- Runtime `tasty()` creates React components with dynamic injection
-- `tastyStatic()` with the Babel plugin produces static class name strings with zero runtime overhead
-- In static mode, the output is plain CSS + class names, so it can be used with any JavaScript framework — not only React
+- `tasty()` components are hook-free and work as React Server Components. In server-only contexts (Next.js RSC, Astro without islands), they produce static HTML + CSS with zero client JavaScript — the full feature set is available without sacrificing server rendering
+- `tastyStatic()` with the Babel plugin produces static class name strings via build-time extraction, with no React dependency at runtime — the output works with any JavaScript framework
 
-Runtime features like `styleProps`, sub-element components, and dynamic variants are React-specific. The static path is framework-agnostic.
+Runtime features like `styleProps`, sub-element components, and dynamic variants are available in the `tasty()` path. The `tastyStatic()` path is framework-agnostic but limited to the DSL, tokens, and state logic.
 
 So the tradeoff is roughly:
 
@@ -303,6 +302,8 @@ So while Stitches and Emotion are strong tools for building components, Tasty is
 
 That makes it narrower in audience, but deeper in architectural ambition.
 
+There is also a fundamental architectural difference: Emotion and styled-components rely on React context and hooks internally, which means they require `'use client'` in modern React and cannot run as React Server Components. Tasty's style functions and `tasty()` components are hook-free, so they work as server components by default and produce zero client JavaScript in server-only contexts. This is not a minor compatibility detail — it means Tasty-based components stay as server components until *your* code needs interactivity, while Emotion and styled-components force the client boundary at the styling layer.
+
 For teams evaluating runtime styling at scale, Tasty also documents its runtime benchmarks and caching model in the main [README](../README.md#performance). That matters, but it is still secondary to the core question of whether you want Tasty's deterministic selector model.
 
 ---
@@ -311,20 +312,18 @@ For teams evaluating runtime styling at scale, Tasty also documents its runtime
 
 Tasty is not limited to one execution model.
 
-It can be used as a styling system with runtime behavior, but it can also be used as a **fully build-time style compiler** when that is the right fit.
-
-That distinction matters.
+The term "runtime" in `tasty()` refers to *when* style computation happens — during React rendering — not to where that rendering occurs. In server-only contexts (Next.js RSC without `'use client'`, Astro without `client:*` directives, SSG), `tasty()` components render on the server, produce static HTML + CSS, and ship **zero client JavaScript**. The full feature set — `styleProps`, sub-elements, variants, state maps — is available. The result is the same as what `tastyStatic()` produces, but without giving up any runtime capabilities.
 
-In runtime mode, `tasty()` creates React components with dynamic style injection, `styleProps`, sub-element components, and variants. This path is React-specific.
+Client JavaScript only enters the picture when a component needs React interactivity (state, effects, event handlers) — and that is the consuming component's decision, never Tasty's. Tasty never forces the `'use client'` boundary.
 
-In build-time mode, `tastyStatic()` with the Babel plugin generates plain static class names and CSS files. The output is framework-agnostic — any JavaScript framework can consume the resulting class names and CSS. This makes Tasty usable as the compiler layer underneath a design-system implementation, even outside the React ecosystem.
+`tastyStatic()` with the Babel plugin is for a different scenario: when you want build-time CSS extraction **without React at runtime**. The output is framework-agnostic — any JavaScript framework can consume the resulting class names and CSS. This makes Tasty usable as the compiler layer underneath a design-system implementation, even outside the React ecosystem.
 
-The tradeoff is that some capabilities — `styleProps`, sub-element components (`<Card.Title>`), dynamic variants — are tied to the runtime path. The static path is best understood as extraction and compilation of the DSL, tokens, and state logic.
+The tradeoff is that some capabilities — `styleProps`, sub-element components (`<Card.Title>`), dynamic variants — are tied to the `tasty()` path. The `tastyStatic()` path is best understood as extraction and compilation of the DSL, tokens, and state logic without a React dependency.
 
 This flexibility is one of Tasty's more unusual strengths:
 
-- it can be used as a full authoring/runtime system for React
-- or as a static compiler whose output works with any framework
+- `tasty()` as the default for all React setups — zero client JS in server-only contexts, full feature set, SSR integration available when client hydration is needed
+- `tastyStatic()` as a static compiler whose output works with any framework, including non-React ones
 
 ---
 
@@ -337,8 +336,8 @@ These are optimized for styling product code directly.
 
 Examples:
 - Tailwind CSS
-- Emotion
-- Stitches (deprecated)
+- Emotion (requires `'use client'` — not RSC-compatible)
+- Stitches (deprecated, requires `'use client'`)
 
 ### Typed styling engines
 These are optimized for generating CSS with stronger structure and tooling.
@@ -412,7 +411,7 @@ Tasty is most compelling when the problem is not just "how do we write styles,"
 
 - [README](../README.md) — overview, quick start, and feature highlights
 - [Style DSL](dsl.md) — state maps, tokens, units, extending semantics, keyframes, @property
-- [Runtime API](runtime.md) — `tasty()` factory, component props, variants, sub-elements, hooks
+- [React API](react-api.md) — `tasty()` factory, component props, variants, sub-elements, style functions
 - [Style Properties](styles.md) — complete reference for all enhanced style properties
 - [Configuration](configuration.md) — tokens, recipes, custom units, style handlers, and TypeScript extensions
 - [Zero Runtime (tastyStatic)](tasty-static.md) — build-time static styling with Babel plugin

package/docs/tasty/configuration.md

@@ -58,6 +58,8 @@ These docs use `data-schema="dark"` in examples. If your app already standardize
 | `counterStyle` | `Record<string, CounterStyleDescriptors>` | - | Global @counter-style definitions |
 | `autoPropertyTypes` | `boolean` | `true` | Auto-infer and register `@property` types from values |
 | `recipes` | `Record<string, RecipeStyles>` | - | Predefined style recipes (named style bundles) |
+| `presets` | `Record<string, TypographyPreset>` | - | Typography presets — shorthand for `generateTypographyTokens()` |
+| `globalStyles` | `Record<string, Styles>` | - | Global Tasty styles keyed by CSS selector |
 | `colorSpace` | `'rgb' \| 'hsl' \| 'oklch'` | `'oklch'` | Color space for decomposed color token companion variables |
 
 ---
@@ -220,6 +222,72 @@ For how to apply, compose, and override recipes in components, see [Recipes](dsl
 
 ---
 
+## Typography Presets
+
+Typography presets are a shorthand for `generateTypographyTokens()`. Instead of calling the function manually and spreading the result into `tokens`, pass the presets directly:
+
+```jsx
+configure({
+  presets: {
+    h1: { fontSize: '32px', lineHeight: '1.2', fontWeight: '700' },
+    t2: { fontSize: '16px', lineHeight: '1.5', fontWeight: '400' },
+    tag: {
+      fontSize: '10px',
+      lineHeight: '1.4',
+      letterSpacing: '0.04em',
+      fontWeight: '600',
+    },
+  },
+});
+```
+
+Each preset generates `$name-font-size`, `$name-line-height`, `$name-letter-spacing`, `$name-font-weight`, and optional `$name-bold-font-weight`, `$name-icon-size`, `$name-text-transform`, `$name-font-family`, `$name-font-style` tokens.
+
+Preset values support state maps for responsive or theme-aware typography:
+
+```jsx
+configure({
+  presets: {
+    t2: {
+      fontSize: '16px',
+      lineHeight: '1.5',
+      fontWeight: { '': '400', '@dark': '300' },
+    },
+  },
+});
+```
+
+The generated tokens are merged **under** explicit `tokens` — if both `presets` and `tokens` define `$t2-font-weight`, the `tokens` value wins. Plugins can also provide `presets`; plugin presets are merged first, then config presets, then explicit tokens on top.
+
+---
+
+## Global Styles
+
+Apply Tasty styles to any selector via configuration, without needing `useGlobalStyles(selector, ...)` at runtime:
+
+```jsx
+configure({
+  globalStyles: {
+    body: {
+      fill: '#surface',
+      color: '#text',
+      preset: 't2',
+      margin: 0,
+      fontFamily: 'system-ui, sans-serif',
+    },
+    html: {
+      overflow: 'hidden',
+    },
+  },
+});
+```
+
+Each key is a CSS selector, and each value is a Tasty `Styles` object supporting the full style syntax including style properties, tokens, state maps, and selector-based sub-styling (e.g. `$: '> .app'` for elements outside React scope). Global styles are injected alongside `:root` tokens when the first style is rendered.
+
+Global styles are automatically emitted in all rendering modes: runtime (client), SSR, and zero-runtime (Babel plugin). Plugins can also provide `globalStyles`; they are merged per selector with config global styles (config wins on conflict).
+
+---
+
 ## Auto Property Types
 
 CSS cannot transition or animate custom properties unless their type is declared via [`@property`](https://developer.mozilla.org/en-US/docs/Web/CSS/@property). Tasty handles this automatically — when a custom property is assigned a concrete value (e.g. `'$scale': 1`, `'$gap': '10px'`, `'#accent': 'purple'`), the type is inferred and a `@property` rule is registered.
@@ -323,4 +391,4 @@ declare module '@tenphi/tasty' {
 }
 ```
 
-See [Style DSL](dsl.md) for state maps, tokens, units, and extending semantics, and [Runtime API](runtime.md) for `tasty()`, hooks, and component props.
+See [Style DSL](dsl.md) for state maps, tokens, units, and extending semantics, and [React API](react-api.md) for `tasty()`, style functions, and component props.

package/docs/tasty/debug.md

@@ -12,6 +12,8 @@ In development mode (`isDevEnv()` returns `true`), `tastyDebug` is automatically
 
 All methods **log to the console by default**. Pass `{ raw: true }` to suppress logging and only return data.
 
+> **Note (2.0.0+):** Class names use a content-addressed base36 hash format (e.g. `t3a5f`) instead of the previous sequential `t{number}` format. Cross-environment hydration reads the rendered class list from `window.__TASTY__` (the legacy `window.__TASTY_SSR_CACHE__` global was removed in 2.0.0).
+
 ---
 
 ## Quick Start
@@ -69,8 +71,8 @@ Retrieves CSS text for a given target. Logs the result with rule count and size.
 | `'unused'` | CSS with refCount = 0 (cached but not used) |
 | `'global'` | Only global CSS (from `injectGlobal`) |
 | `'page'` | All CSS on the page (including non-tasty) |
-| `'t42'` | CSS for a specific tasty class |
-| `['t0', 't5']` | CSS for multiple tasty classes |
+| `'t3a5f'` | CSS for a specific tasty class (class names are `t` + base36 hash) |
+| `['t3a5f', 't9k2']` | CSS for multiple tasty classes |
 | `'.my-button'` | CSS affecting a DOM element (by selector) |
 | `element` | CSS affecting a DOM element (by reference) |
 
@@ -88,11 +90,11 @@ interface CssOptions extends DebugOptions {
 tastyDebug.css('active');
 
 // Specific class, silent
-const css = tastyDebug.css('t42', { raw: true });
+const css = tastyDebug.css('t3a5f', { raw: true });
 
 // Compare original vs browser-parsed CSS (dev mode only)
-tastyDebug.css('t42');                    // live CSSOM
-tastyDebug.css('t42', { source: true }); // original output
+tastyDebug.css('t3a5f');                    // live CSSOM
+tastyDebug.css('t3a5f', { source: true }); // original output
 
 // Shadow DOM
 tastyDebug.css('all', { root: shadowRoot });
@@ -125,11 +127,11 @@ interface ChunkInfo {
 ```typescript
 tastyDebug.inspect('.my-card');
 // Logs: inspect div — 3 classes, 5 rules, 1.2KB
-//       Chunks: t3→appearance, t7→font, t12→dimension
+//       Chunks: t3a5f→appearance, t9k2→font, tb71→dimension
 
 // Silent
 const result = tastyDebug.inspect('.my-card', { raw: true });
-console.log(result.classes);  // ['t3', 't7', 't12']
+console.log(result.classes);  // ['t3a5f', 't9k2', 'tb71']
 console.log(result.rules);    // 5
 ```
 
@@ -291,10 +293,10 @@ tastyDebug.summary({ root: shadowRoot });
 tastyDebug.inspect('.my-button');
 
 // 2. See CSS for a specific class
-tastyDebug.css('t3');
+tastyDebug.css('t3a5f');
 
 // 3. Compare original vs browser-parsed (dev mode)
-tastyDebug.css('t3', { source: true });
+tastyDebug.css('t3a5f', { source: true });
 ```
 
 ### Checking cache efficiency

package/docs/tasty/design-system.md

@@ -84,25 +84,37 @@ configure({
 
 ### Typography presets
 
-Use `generateTypographyTokens()` to create typography tokens from your own presets, then pass them to `configure({ tokens })`:
+Pass typography presets directly to `configure()` — they are converted to tokens automatically:
 
 ```tsx
-import { configure, generateTypographyTokens } from '@tenphi/tasty';
+import { configure } from '@tenphi/tasty';
 
-const typographyTokens = generateTypographyTokens({
-  h1: { fontSize: '2rem', lineHeight: '1.2', letterSpacing: '-0.02em', fontWeight: 700 },
-  t2: { fontSize: '0.875rem', lineHeight: '1.5', letterSpacing: 'normal', fontWeight: 400 },
+configure({
+  presets: {
+    h1: { fontSize: '2rem', lineHeight: '1.2', letterSpacing: '-0.02em', fontWeight: 700 },
+    t2: { fontSize: '0.875rem', lineHeight: '1.5', letterSpacing: 'normal', fontWeight: 400 },
+  },
 });
+```
+
+Preset values support state maps for responsive or theme-aware typography:
 
+```tsx
 configure({
-  tokens: {
-    ...typographyTokens,
+  presets: {
+    t2: {
+      fontSize: '0.875rem',
+      lineHeight: '1.5',
+      fontWeight: { '': 400, '@dark': 300 },
+    },
   },
 });
 ```
 
 Then use `preset: 'h1'` or `preset: 't2'` in any component's styles.
 
+> You can also call `generateTypographyTokens()` manually and spread the result into `tokens` for more control — `presets` is just a shorthand.
+
 ### Registering brand fonts
 
 Register your design system's custom fonts via `configure({ fontFace })` so every component can reference them:
@@ -334,7 +346,7 @@ Usage:
 
 Sub-elements share the root component's state context by default. A `disabled` modifier on `<Card>` affects `Title`, `Content`, and `Footer` styles automatically — no prop drilling. For the full mental model, see [Methodology — Component architecture](methodology.md#component-architecture-root--sub-elements).
 
-For sub-element syntax details (selector affix `$`, `@own()`, `elements` config), see [Runtime API — Sub-element Styling](runtime.md#sub-element-styling).
+For sub-element syntax details (selector affix `$`, `@own()`, `elements` config), see [React API — Sub-element Styling](react-api.md#sub-element-styling).
 
 ---
 
@@ -404,7 +416,7 @@ ds/
     index.ts              # Recipe definitions (imported by config.ts)
   tokens/
     colors.ts             # Color token definitions
-    typography.ts         # Typography presets via generateTypographyTokens()
+    typography.ts         # Typography presets for configure({ presets })
     spacing.ts            # Spacing token definitions
   index.ts                # Public API: re-exports components + configure
 ```
@@ -418,7 +430,7 @@ The key principle: `config.ts` imports tokens and recipes, calls `configure()`,
 - **[Methodology](methodology.md)** — The recommended patterns for structuring Tasty components
 - **[Getting Started](getting-started.md)** — Installation, first component, tooling setup
 - **[Style DSL](dsl.md)** — State maps, tokens, units, extending semantics, keyframes, @property
-- **[Runtime API](runtime.md)** — `tasty()` factory, component props, variants, sub-elements, hooks
+- **[React API](react-api.md)** — `tasty()` factory, component props, variants, sub-elements, style functions
 - **[Configuration](configuration.md)** — Full `configure()` API: tokens, recipes, custom units, style handlers
 - **[Adoption Guide](adoption.md)** — Who should adopt Tasty, incremental phases, what changes for product engineers
 - **[Style Properties](styles.md)** — Complete reference for all enhanced style properties

package/docs/tasty/dsl.md

@@ -2,7 +2,7 @@
 
 This is the Tasty style language reference — the value syntax, state mappings, tokens, units, extending semantics, and special declarations that apply to both runtime `tasty()` and build-time `tastyStatic()`.
 
-For the runtime React API (`tasty()`, hooks, component props), see [Runtime API](runtime.md). For all enhanced style properties, see [Style Properties](styles.md). For global configuration, see [Configuration](configuration.md).
+For the runtime React API (`tasty()`, hooks, component props), see [React API](react-api.md). For all enhanced style properties, see [Style Properties](styles.md). For global configuration, see [Configuration](configuration.md).
 
 ---
 
@@ -25,7 +25,21 @@ fill: { '': '#white', hovered: '#gray.05', 'theme=danger': '#red' }
 | Pseudo-class | `:hover` | `:hover` |
 | Class selector | `.active` | `.active` |
 | Attribute selector | `[aria-expanded="true"]` | `[aria-expanded="true"]` |
-| Combined | `hovered & .active` | `[data-hovered].active` |
+| Combined (AND) | `hovered & .active` | `[data-hovered].active` |
+| Combined (OR) | `hovered \| focused` | `[data-hovered], [data-focused]` |
+| Negated (NOT) | `!disabled` | `:not([data-disabled])` |
+| Exclusive (XOR) | `hovered ^ focused` | `[data-hovered]:not([data-focused]), :not([data-hovered])[data-focused]` |
+
+Operator precedence (highest to lowest): `!` (NOT) > `^` (XOR) > `|` (OR) > `&` (AND). Use parentheses to override: `hovered & (pressed ^ focused)`.
+
+`^` (XOR) means "exactly one of" — `A ^ B` expands to `(A & !B) | (!A & B)`. This is useful for mutually exclusive states where exactly one should be active:
+
+```jsx
+fill: {
+  '': '#surface',
+  'hovered ^ focused': '#accent',  // active when hovered OR focused, but not both
+}
+```
 
 ### Sub-element
 
@@ -93,7 +107,7 @@ mods={{ hovered: true, theme: 'danger' }}
 // → data-hovered="" data-theme="danger"
 ```
 
-Modifiers can also be exposed as top-level component props via `modProps` — see [Runtime — Mod Props](runtime.md#mod-props).
+Modifiers can also be exposed as top-level component props via `modProps` — see [Runtime — Mod Props](react-api.md#mod-props).
 
 ---
 
@@ -430,7 +444,7 @@ const FadeIn = tasty({
 
 ### `@parent(...)` — Parent Element States
 
-Style based on ancestor element attributes. Uses `:is([selector] *)` / `:not([selector] *)` for symmetric, composable parent checks. Boolean logic (`&`, `|`, `!`) is supported inside `@parent()`.
+Style based on ancestor element attributes. Uses `:is([selector] *)` / `:not([selector] *)` for symmetric, composable parent checks. Boolean logic (`&`, `|`, `!`, `^`) is supported inside `@parent()`.
 
 ```jsx
 const Highlight = tasty({
@@ -508,12 +522,13 @@ const Card = tasty({
 | `!:has(> Icon)` | `:not(:has(> [data-element="Icon"]))` | Negation (use `!`) |
 | `!:is(Panel)` | `:not([data-element="Panel"])` | Negation (use `!:is`) |
 
-Combine with other states using boolean logic:
+Combine with other states using boolean logic (`&`, `|`, `!`, `^`):
 
 ```jsx
-':has(> Icon) & hovered'                // structural + data attribute
-'@parent(hovered) & :has(> Icon)'       // parent check + structural
+':has(> Icon) & hovered'                // AND: structural + data attribute
+'@parent(hovered) & :has(> Icon)'       // AND: parent check + structural
 ':has(> Icon) | :has(> Button)'         // OR: either sub-element present
+':has(> Icon) ^ :has(> Button)'         // XOR: exactly one present
 ```
 
 > **Nesting limit:** The state key parser supports up to 2 levels of nested parentheses inside `:is()`, `:has()`, `:not()`, and `:where()` — e.g. `:has(Input:not(:disabled))` works, but 3+ levels like `:has(:is(:not(:hover)))` will not be tokenized correctly. This covers virtually all practical use cases.
@@ -666,7 +681,7 @@ For a complete reference of all enhanced style properties — syntax, values, mo
 
 ## Learn more
 
-- **[Runtime API](runtime.md)** — `tasty()` factory, component props, variants, sub-elements, hooks
+- **[React API](react-api.md)** — `tasty()` factory, component props, variants, sub-elements, style functions
 - **[Methodology](methodology.md)** — Recommended patterns: root + sub-elements, styleProps, tokens, wrapping
 - **[Configuration](configuration.md)** — Tokens, recipes, custom units, style handlers, TypeScript extensions
 - **[Style Properties](styles.md)** — Complete reference for all enhanced style properties

package/docs/tasty/getting-started.md

@@ -1,6 +1,6 @@
 # Getting Started
 
-This guide walks you from zero to a working Tasty component, then through the optional shared configuration and tooling layers. It is the right starting point when you already want to try Tasty in code. If you are still deciding whether Tasty fits your team, start with [Comparison](comparison.md) and [Adoption Guide](adoption.md) first. For a feature overview, see the [README](../README.md). For the full style language reference, see the [Style DSL](dsl.md). For the React API, see the [Runtime API](runtime.md). For the rest of the docs by role or task, see the [Docs Hub](README.md).
+This guide walks you from zero to a working Tasty component, then through the optional shared configuration and tooling layers. It is the right starting point when you already want to try Tasty in code. If you are still deciding whether Tasty fits your team, start with [Comparison](comparison.md) and [Adoption Guide](adoption.md) first. For a feature overview, see the [README](../README.md). For the full style language reference, see the [Style DSL](dsl.md). For the React API, see the [React API](react-api.md). For the rest of the docs by role or task, see the [Docs Hub](README.md).
 
 ---
 
@@ -179,19 +179,19 @@ export default [
 
 ## Choosing a rendering mode
 
-Tasty has two styling approaches. Pick the one that fits your use case, then decide whether your runtime setup also needs server rendering support:
+`tasty()` is the default for all React apps. All `tasty()` components and style functions are hook-free and work as React Server Components without `'use client'`. In server-only contexts, they produce zero client JavaScript with the full feature set.
 
 | Approach | Entry point | Best for | Trade-off |
 |------|-------------|----------|-----------|
-| **Runtime** | `tasty()` from `@tenphi/tasty` | Interactive apps with reusable stateful components, design systems | CSS generated at runtime; full feature set (styleProps, sub-elements, variants) |
-| **Zero-runtime** | `tastyStatic()` from `@tenphi/tasty/static` | Static sites, landing pages, SSG | Zero JS overhead; requires Babel plugin; no dynamic props |
+| **Runtime (default)** | `tasty()` from `@tenphi/tasty` | All React apps — server-rendered by default, zero client JS until you need interactivity | Full feature set (styleProps, sub-elements, variants); CSS computed during rendering |
+| **Runtime + SSR integration** | Add `@tenphi/tasty/ssr/*` | Apps with client-side hydration (Next.js client components, Astro islands) | Adds CSS batching, deduplication, FOUC prevention, and client cache hydration |
+| **Zero-runtime** | `tastyStatic()` from `@tenphi/tasty/static` | Non-React frameworks or build-time extraction without React | Requires Babel plugin; no `styleProps` or runtime-only APIs |
 
-Both share the same DSL, tokens, units, and state mappings.
+Both `tasty()` and `tastyStatic()` share the same DSL, tokens, units, and state mappings.
 
-- Runtime is the default and requires no extra setup beyond `@tenphi/tasty`.
-- If your framework can execute runtime code during server rendering, add SSR support on top of runtime with `@tenphi/tasty/ssr/next`, `@tenphi/tasty/ssr/astro`, or the core SSR API. This still uses `tasty()`; it just collects CSS on the server and hydrates the cache on the client.
-- Zero-runtime requires the Babel plugin and additional peer dependencies. See [Zero Runtime (tastyStatic)](tasty-static.md).
-- SSR works with existing `tasty()` components — wrap your app with a registry, middleware, or collector. See [Server-Side Rendering](ssr.md).
+- **Runtime** is the default and requires no extra setup beyond `@tenphi/tasty`. In server-only contexts (Next.js RSC, Astro without `client:*` directives, SSG), `tasty()` produces static HTML + CSS with zero client JavaScript — the same end result as `tastyStatic()` but with the full feature set. For example, `tasty()` + `tastyIntegration()` in Astro without islands gives you the complete API with zero JS shipped.
+- **SSR integration** is only needed when your app also has client-side rendering. Add `@tenphi/tasty/ssr/next`, `@tenphi/tasty/ssr/astro`, or the core SSR API to get CSS deduplication and cache hydration. See [Server-Side Rendering](ssr.md).
+- **Zero-runtime** requires the Babel plugin and additional peer dependencies. Use it when you need build-time extraction without a React runtime. See [Zero Runtime (tastyStatic)](tasty-static.md).
 
 ---
 
@@ -200,7 +200,7 @@ Both share the same DSL, tokens, units, and state mappings.
 - **[Docs Hub](README.md)** — Pick the next guide by role, styling approach, or task
 - **[Methodology](methodology.md)** — The recommended patterns for structuring Tasty components: sub-elements, styleProps, tokens, extension
 - **[Style DSL](dsl.md)** — State maps, tokens, units, extending semantics, keyframes, @property
-- **[Runtime API](runtime.md)** — `tasty()` factory, component props, variants, sub-elements, hooks
+- **[React API](react-api.md)** — `tasty()` factory, component props, variants, sub-elements, style functions
 - **[Building a Design System](design-system.md)** — Practical guide to building a DS layer with Tasty: tokens, recipes, primitives, compound components
 - **[Adoption Guide](adoption.md)** — Roll out Tasty inside an existing design system or platform team
 - **[Comparison](comparison.md)** — Evaluate Tasty against other styling systems

package/docs/tasty/injector.md

@@ -115,11 +115,13 @@ dispose();
 
 ### `useRawCSS(css, options?)` or `useRawCSS(factory, deps, options?)`
 
-React hook for injecting raw CSS. Uses `useInsertionEffect` for proper timing and cleanup.
+Inject raw CSS without parsing. Hook-free — works in client components, SSR, and React Server Components.
 
 Supports two overloads:
-- **Static CSS**: `useRawCSS(cssString, options?)`
-- **Factory function**: `useRawCSS(() => cssString, deps, options?)` - re-evaluates when deps change (like `useMemo`)
+- **Static CSS**: `useRawCSS(cssString, options?)` — content-based deduplication
+- **Factory function**: `useRawCSS(() => cssString, deps, options?)` — factory called on every invocation, dedup handled internally
+
+Use the `id` option for update tracking — when the CSS changes for the same id, the previous injection is replaced:
 
 ```tsx
 import { useRawCSS } from '@tenphi/tasty';
@@ -132,7 +134,7 @@ function GlobalReset() {
   return null;
 }
 
-// Dynamic CSS with factory function (like useMemo)
+// Dynamic CSS with factory function and update tracking
 function ThemeStyles({ theme }: { theme: 'dark' | 'light' }) {
   useRawCSS(() => `
     body {
@@ -140,7 +142,7 @@ function ThemeStyles({ theme }: { theme: 'dark' | 'light' }) {
       background: ${theme === 'dark' ? '#000' : '#fff'};
       color: ${theme === 'dark' ? '#fff' : '#000'};
     }
-  `, [theme]);
+  `, [theme], { id: 'theme-body' });
 
   return null;
 }
@@ -207,13 +209,12 @@ import { configure } from '@tenphi/tasty';
 configure({
   devMode: true,                     // Enable development features (auto-detected)
   maxRulesPerSheet: 8192,            // Cap rules per stylesheet (default: 8192)
-  unusedStylesThreshold: 500,        // Trigger cleanup threshold (CSS rules only)
-  bulkCleanupDelay: 5000,            // Cleanup delay (ms) - ignored if idleCleanup is true
-  idleCleanup: true,                 // Use requestIdleCallback for cleanup
-  bulkCleanupBatchRatio: 0.5,        // Clean up oldest 50% per batch
-  unusedStylesMinAgeMs: 10000,       // Minimum age before cleanup (ms)
   forceTextInjection: false,         // Force textContent insertion (auto-detected for tests)
   nonce: 'csp-nonce',                // CSP nonce for security
+  gc: {                              // Garbage collection for unused styles
+    touchInterval: 1000,             // Touch events between GC cycles (default: 1000)
+    capacity: 1000,                  // Max unused styles to retain (default: 1000)
+  },
   states: {                          // Global predefined states for advanced state mapping
     '@mobile': '@media(w < 768px)',
     '@dark': '@root(schema=dark)',
@@ -229,7 +230,8 @@ configure({
 - Most options have sensible defaults and auto-detection
 - `configure()` is optional - the injector works with defaults
 - **Configuration is locked after styles are generated** - calling `configure()` after first render will emit a warning and be ignored
-- `unusedStylesMinAgeMs`: Minimum time (ms) a style must remain unused before being eligible for cleanup. Helps prevent removal of styles that might be quickly reactivated.
+- `gc.touchInterval`: Number of touch events between GC cycles. Each style render counts as a touch. When the counter reaches this value, GC is scheduled via `requestIdleCallback`.
+- `gc.capacity`: Maximum number of unused styles (refCount = 0, not in DOM) to retain. When exceeded, the oldest are evicted first. Actively referenced styles don't count against this limit.
 
 ---
 
@@ -291,21 +293,34 @@ comp3.dispose(); // refCount: 1 → 0, eligible for bulk cleanup
 // Next inject() with same styles will increment refCount and reuse immediately
 ```
 
-### Smart Cleanup System
+### Garbage Collection
 
 ```typescript
-import { configure } from '@tenphi/tasty';
+import { configure, gc } from '@tenphi/tasty';
 
-// CSS rules: Not immediately deleted, marked for bulk cleanup (refCount = 0)
 // Keyframes: Disposed immediately when refCount = 0 (safer for global scope)
+// CSS rules: Tracked by touch count and cleaned up via gc()
 
 configure({
-  unusedStylesThreshold: 100,    // Cleanup when 100+ unused CSS rules
-  bulkCleanupBatchRatio: 0.3,    // Remove oldest 30% each time
+  gc: {
+    touchInterval: 1000,   // Schedule GC every 1000 touches
+    capacity: 1000,        // Max unused styles to retain
+  },
 });
 
+// Manual GC (synchronous, returns number of swept styles):
+gc();
+
+// Force-remove ALL unused styles (e.g. on route change or test teardown):
+gc({ force: true });
+
+// GC is also triggered automatically by touch count during rendering.
+// Every `touchInterval` touches, GC is scheduled via requestIdleCallback.
+
 // Benefits:
-// - CSS rules: Batch cleanup prevents DOM manipulation overhead  
+// - Activity-proportional: busy apps trigger GC more often
+// - DOM-safe: styles currently in the DOM are never evicted
+// - Oldest-first: least recently used styles are evicted first
 // - Keyframes: Immediate cleanup prevents global namespace pollution
 // - Unused styles can be instantly reactivated (just increment refCount)
 ```
@@ -462,13 +477,14 @@ injectGlobal([
   { selector: '.container', declarations: 'max-width: 1200px;' }
 ]);
 
-// ✅ Configure appropriate thresholds for your app (BEFORE first render!)
+// ✅ Configure GC for your app (BEFORE first render!)
 import { configure } from '@tenphi/tasty';
 
 configure({
-  unusedStylesThreshold: 500,      // Default threshold (adjust based on app size)
-  bulkCleanupBatchRatio: 0.5,      // Default: clean oldest 50% per batch
-  unusedStylesMinAgeMs: 10000,     // Wait 10s before cleanup eligibility
+  gc: {
+    touchInterval: 1000,   // Schedule GC every 1000 style touches
+    capacity: 1000,        // Max unused styles to retain
+  },
 });
 ```
 
@@ -480,8 +496,8 @@ configure({
 // 1. Hash-based deduplication - same CSS = same className
 // 2. Reference counting - styles stay alive while in use (refCount > 0)
 // 3. Immediate keyframes cleanup - disposed instantly when refCount = 0
-// 4. Batch CSS cleanup - unused CSS rules (refCount = 0) cleaned in batches
-// 5. Non-stacking cleanups - prevents timeout accumulation
+// 4. Touch-count GC - unused CSS rules are evicted oldest-first when over capacity
+// 5. DOM safety guard - styles visible in the DOM are never evicted
 
 // Manual cleanup is rarely needed but available:
 cleanup(); // Force immediate cleanup of all unused CSS rules (refCount = 0)
@@ -511,7 +527,7 @@ const StyledButton = tasty({
 // 4. dispose() is called when component unmounts
 ```
 
-For most development, you'll use the [Runtime API](./runtime.md) rather than the injector directly. The injector provides the high-performance foundation that makes Tasty's declarative styling possible.
+For most development, you'll use the [React API](./react-api.md) rather than the injector directly. The injector provides the high-performance foundation that makes Tasty's declarative styling possible.
 
 ---
 
@@ -525,4 +541,4 @@ Direct injector usage is recommended for:
 - **Performance-critical scenarios** where you need direct control
 - **Testing utilities** that need to inject or extract CSS
 
-For regular component styling, prefer the [`tasty()` API](./runtime.md) which provides a more developer-friendly interface.
+For regular component styling, prefer the [`tasty()` API](./react-api.md) which provides a more developer-friendly interface.