@cube-dev/ui-kit 0.125.1 → 0.127.0

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).
 
 ---
 
@@ -119,8 +133,6 @@ color: '(#primary, #secondary)',  // Fallback syntax
 | `cr` | Card border radius | `1cr` | `var(--card-radius)` |
 | `bw` | Border width | `2bw` | `calc(var(--border-width) * 2)` |
 | `ow` | Outline width | `1ow` | `var(--outline-width)` |
-| `fs` | Font size | `1fs` | `var(--font-size)` |
-| `lh` | Line height | `1lh` | `var(--line-height)` |
 | `sf` | Stable fraction | `1sf` | `minmax(0, 1fr)` |
 
 You can register additional custom units via [`configure()`](configuration.md#options).
@@ -432,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({
@@ -510,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.
@@ -569,6 +582,97 @@ Use explicit `@properties` when you need non-default settings like `inherits: fa
 
 ---
 
+## Font Face (`@fontFace`)
+
+Register custom fonts directly inside a `styles` object. Keys are font-family names, values are descriptor objects (or arrays of them for multiple weights/styles).
+
+```ts
+const Heading = tasty({
+  styles: {
+    '@fontFace': {
+      'Brand Sans': {
+        src: 'url("/fonts/brand-sans.woff2") format("woff2")',
+        fontDisplay: 'swap',
+      },
+    },
+    fontFamily: '"Brand Sans", sans-serif',
+  },
+});
+```
+
+### Multiple weights
+
+Supply an array to register several variants of the same family:
+
+```ts
+'@fontFace': {
+  'Brand Sans': [
+    { src: 'url("/fonts/brand-regular.woff2") format("woff2")', fontWeight: 400, fontDisplay: 'swap' },
+    { src: 'url("/fonts/brand-bold.woff2") format("woff2")', fontWeight: 700, fontDisplay: 'swap' },
+  ],
+}
+```
+
+### Supported descriptors
+
+| Descriptor | CSS property | Type |
+|---|---|---|
+| `src` (required) | `src` | `string` |
+| `fontWeight` | `font-weight` | `string \| number` |
+| `fontStyle` | `font-style` | `string` |
+| `fontStretch` | `font-stretch` | `string` |
+| `fontDisplay` | `font-display` | `'auto' \| 'block' \| 'swap' \| 'fallback' \| 'optional'` |
+| `unicodeRange` | `unicode-range` | `string` |
+| `ascentOverride` | `ascent-override` | `string` |
+| `descentOverride` | `descent-override` | `string` |
+| `lineGapOverride` | `line-gap-override` | `string` |
+| `sizeAdjust` | `size-adjust` | `string` |
+| `fontFeatureSettings` | `font-feature-settings` | `string` |
+| `fontVariationSettings` | `font-variation-settings` | `string` |
+
+> Font-face rules are permanent — they are injected once and never cleaned up, matching how browsers handle `@font-face`.
+
+---
+
+## Counter Style (`@counterStyle`)
+
+Define custom list markers via the CSS `@counter-style` at-rule. Keys are counter-style names, values are descriptor objects.
+
+```ts
+const EmojiList = tasty({
+  tag: 'ol',
+  styles: {
+    '@counterStyle': {
+      thumbs: {
+        system: 'cyclic',
+        symbols: '"👍"',
+        suffix: '" "',
+      },
+    },
+    listStyleType: 'thumbs',
+  },
+});
+```
+
+### Supported descriptors
+
+| Descriptor | CSS property | Type |
+|---|---|---|
+| `system` (required) | `system` | `'cyclic' \| 'numeric' \| 'alphabetic' \| 'symbolic' \| 'additive' \| 'fixed' \| string` |
+| `symbols` | `symbols` | `string` |
+| `additiveSymbols` | `additive-symbols` | `string` |
+| `prefix` | `prefix` | `string` |
+| `suffix` | `suffix` | `string` |
+| `negative` | `negative` | `string` |
+| `range` | `range` | `string` |
+| `pad` | `pad` | `string` |
+| `fallback` | `fallback` | `string` |
+| `speakAs` | `speak-as` | `string` |
+
+> Counter-style rules are permanent — they are injected once and never cleaned up, matching how browsers handle `@counter-style`.
+
+---
+
 ## Style Properties
 
 For a complete reference of all enhanced style properties — syntax, values, modifiers, and recommendations — see **[Style Properties Reference](styles.md)**.
@@ -577,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.

package/docs/tasty/methodology.md

@@ -214,7 +214,7 @@ The array form is simpler but types all values as `ModValue`:
 modProps: ['isLoading', 'isSelected'] as const,
 ```
 
-For the full API reference, see [Runtime — Mod Props](runtime.md#mod-props).
+For the full API reference, see [Runtime — Mod Props](react-api.md#mod-props).
 
 ---
 
@@ -256,6 +256,54 @@ The `tokens` prop sets `style="--progress: 75%"` on the DOM element. The `$progr
 
 Design tokens (via `configure({ tokens })`) are injected as CSS custom properties on `:root`. Replace tokens (via `configure({ replaceTokens })`) are resolved at parse time and baked into the generated CSS. The `tokens` prop on components is resolved at render time via inline CSS custom properties. Use design tokens for design-system constants, replace tokens for value aliases, and the `tokens` prop for truly dynamic per-instance values.
 
+### tokenProps
+
+`tokenProps` expose token keys as top-level component props — the token equivalent of `styleProps` and `modProps`. Use them when a component has a fixed set of known dynamic token values.
+
+#### Array form
+
+Prop names are plain camelCase identifiers. Names ending in `Color` map to `#` color tokens; everything else maps to `$` custom property tokens:
+
+```tsx
+const ProgressBar = tasty({
+  tokenProps: ['progress', 'accentColor'] as const,
+  styles: { width: '$progress', fill: '#accent' },
+});
+
+// Clean prop API — no tokens object needed
+<ProgressBar progress="75%" accentColor="#purple" />
+
+// Conversion:
+//   'progress'    → $progress    → --progress
+//   'accentColor' → #accent      → --accent-color + --accent-color-oklch
+```
+
+#### Object form
+
+Keys are prop names; values are `$`/`#`-prefixed token keys. No suffix convention needed — the prefix in the value is explicit:
+
+```tsx
+const Card = tasty({
+  tokenProps: {
+    size: '$card-size',
+    color: '#card-accent',
+  },
+  styles: { padding: '$card-size', fill: '#card-accent' },
+});
+
+<Card size="4x" color="#purple" />
+```
+
+#### Merge order
+
+When all three token sources are present, values merge with increasing priority:
+
+1. `tokens` option in `tasty({...})` — default tokens (lowest)
+2. `tokens` prop on the component instance — runtime overrides
+3. `tokenProps`-derived values — highest priority (explicit named props win)
+
+The `tokens` prop remains available for ad-hoc or dynamic tokens alongside `tokenProps`.
+
 ---
 
 ## styles prop vs style prop
@@ -458,7 +506,8 @@ See [Configuration](configuration.md) for the full `configure()` API.
 - **Use `elements` prop** to declare typed sub-components for compound components
 - **Use `styleProps`** to define what product engineers can customize
 - **Use `modProps`** to expose known modifier states as clean component props
-- **Use `tokens` prop** for per-instance dynamic values (progress, user color)
+- **Use `tokenProps`** to expose known token keys as clean component props
+- **Use `tokens` prop** for ad-hoc or dynamic per-instance token values (progress, user color)
 - **Use modifiers** (`mods` or `modProps`) for state-driven style changes instead of runtime `styles` prop changes
 
 ### Avoid
@@ -561,7 +610,7 @@ The `elements` prop gives you typed sub-components with automatic `data-element`
 - **[Getting Started](getting-started.md)** — Installation, first component, tooling setup
 - **[Building a Design System](design-system.md)** — Practical guide to building a DS layer with Tasty
 - **[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
 - **[Style Properties](styles.md)** — Complete reference for all enhanced style properties
 - **[Adoption Guide](adoption.md)** — Who should adopt Tasty, incremental phases, what changes for product engineers

package/docs/tasty/{PIPELINE.md → pipeline.md}

@@ -55,7 +55,7 @@ Output: CSSRule[]
 
 **Simplification** (`simplifyCondition` in `simplify.ts`) is not a separate numbered stage. It runs inside exclusive building, `expandExclusiveOrs` branch cleanup, combination ANDs, merge-by-value ORs, and materialization as needed.
 
-**Post-pass:** After `processStyles` collects rules from every handler, `runPipeline` filters duplicates using a key of `selector|declarations|atRules|rootPrefix` so identical emitted rules appear once.
+**Post-pass:** After `processStyles` collects rules from every handler, `runPipeline` filters duplicates using a key of `selector|declarations|atRules|rootPrefix|startingStyle` so identical emitted rules appear once.
 
 ---