@tenphi/tasty 0.0.0-snapshot.bbd10c7 → 0.0.0-snapshot.bbfcd75

package/docs/getting-started.md

@@ -1,6 +1,8 @@
 # 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).
+Build one stateful component first. You will see how Tasty expresses priority as a state map, why overlapping states do not compete, and where shared design-system configuration fits afterward.
+
+This is the right starting point when you are ready to try Tasty in code. If you are still evaluating it, read the [Introduction](../README.md), [Comparison](comparison.md), and [Adoption Guide](adoption.md).
 
 ---
 
@@ -10,7 +12,7 @@ This guide walks you from zero to a working Tasty component, then through the op
 - **React** >= 18 (peer dependency)
 - **Package manager**: pnpm, npm, or yarn
 
-Tasty can be used immediately in a React app, but it is most compelling for teams building reusable components with intersecting states, variants, tokens, and design-system conventions.
+No Tasty configuration is required for the first component.
 
 ---
 
@@ -22,36 +24,57 @@ pnpm add @tenphi/tasty
 
 ---
 
-## Your first component
+## Build a button whose states don’t fight
 
 ```tsx
 import { tasty } from '@tenphi/tasty';
 
-const Card = tasty({
-  as: 'div',
+const Button = tasty({
+  as: 'button',
   styles: {
-    display: 'flex',
-    flow: 'column',
-    padding: '4x',
-    gap: '2x',
-    fill: '#white',
-    border: true,
-    radius: true,
+    padding: '12px 20px',
+    radius: '8px',
+    border: '0',
+    fill: {
+      '': 'royalblue',
+      ':hover': 'blue',
+      ':active': 'navy',
+      disabled: 'lightgray',
+    },
+    color: {
+      '': 'white',
+      disabled: 'dimgray',
+    },
+    cursor: {
+      '': 'pointer',
+      disabled: 'not-allowed',
+    },
   },
 });
 
 export default function App() {
-  return <Card>Hello, Tasty!</Card>;
+  return (
+    <>
+      <Button>Save changes</Button>
+      <Button disabled>Disabled</Button>
+    </>
+  );
 }
 ```
 
-`tasty()` returns a normal React component. Values like `4x`, `#white`, `true`, and `1r` are Tasty DSL — they map to CSS custom properties, shorthand expansions, and design tokens. See [Style Properties](styles.md) for the full reference.
+`tasty()` returns a normal React component. The keys in each state map define priority: later branches win over earlier ones. Because `disabled` is last, a disabled button keeps its disabled styles even while the pointer is over it.
+
+`disabled` and `checked` are built-in automatic states. Tasty activates them from the corresponding native prop or attribute, so `disabled` is the concise Tasty form of `[disabled]`, and `checked` is the concise form of `[checked]`.
+
+Tasty compiles that priority into selectors that exclude one another. The hover, active, and disabled background rules cannot all match and ask the CSS cascade to decide the winner.
+
+The example uses ordinary CSS values so it works without setup. A design system will usually replace them with shared tokens, units, and state aliases in the next step. See the [Style DSL](dsl.md) for the complete state-map syntax and [Style Properties](styles.md) for Tasty’s enhanced CSS properties.
 
 ---
 
-## Optional: add shared configuration
+## Add your design system’s language
 
-Use `configure()` once, before your app renders, when your app or design system needs shared state aliases, tokens, recipes, or parser extensions:
+The first component needs no configuration. Use `configure()` once, before your app renders, when your app or design system is ready to share tokens, state aliases, recipes, units, or parser extensions:
 
 ```tsx
 // src/tasty-config.ts
@@ -91,8 +114,8 @@ configure({
     '#primary': 'oklch(55% 0.25 265)',
     '#surface': '#fff',
     '#text': '#111',
-    '$gap': '8px',
-    '$radius': '4px',
+    $gap: '8px',
+    $radius: '4px',
     '$border-width': '1px',
     '$outline-width': '2px',
   },
@@ -148,23 +171,21 @@ export default [
 
 The `recommended` config enables 18 of the plugin's 27 total rules. It covers the most common issues without turning on the stricter governance rules:
 
-| Category | Rules | Examples |
-|----------|-------|---------|
-| Property validation | `known-property`, `valid-boolean-property`, `valid-sub-element` | Flags typos like `pading` or invalid boolean usage |
-| Value validation | `valid-value`, `valid-color-token`, `valid-custom-unit` | Catches `#nonexistent` tokens, bad unit syntax |
-| State validation | `valid-state-key`, `no-nested-state-map`, `require-default-state` | Validates state key syntax, ensures `''` default exists |
-| Structure | `valid-styles-structure`, `no-important`, `no-nested-selector` | Prevents `!important`, invalid nesting |
-| Static mode | `static-no-dynamic-values`, `static-valid-selector` | Enforces build-time constraints in `tastyStatic()` |
-| Style properties | `valid-preset`, `valid-recipe`, `valid-transition`, `valid-directional-modifier`, `valid-radius-shape` | Validates preset names, recipe references, transition syntax |
+| Category            | Rules                                                                                                  | Examples                                                     |
+| ------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ |
+| Property validation | `known-property`, `valid-boolean-property`, `valid-sub-element`                                        | Flags typos like `pading` or invalid boolean usage           |
+| Value validation    | `valid-value`, `valid-color-token`, `valid-custom-unit`                                                | Catches `#nonexistent` tokens, bad unit syntax               |
+| State validation    | `valid-state-key`, `no-nested-state-map`, `require-default-state`                                      | Validates state key syntax, ensures `''` default exists      |
+| Structure           | `valid-styles-structure`, `no-important`, `no-nested-selector`                                         | Prevents `!important`, invalid nesting                       |
+| Static mode         | `static-no-dynamic-values`, `static-valid-selector`                                                    | Enforces build-time constraints in `tastyStatic()`           |
+| Style properties    | `valid-preset`, `valid-recipe`, `valid-transition`, `valid-directional-modifier`, `valid-radius-shape` | Validates preset names, recipe references, transition syntax |
 
 ### Strict config
 
 For stricter governance, use `tasty.configs.strict`. It adds rules that enforce best practices like preferring shorthand properties, consistent token usage, and flagging direct `styles` prop usage:
 
 ```js
-export default [
-  tasty.configs.strict,
-];
+export default [tasty.configs.strict];
 ```
 
 ---
@@ -179,19 +200,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'`. Zero-runtime delivery is not tied to one API: both server-only `tasty()` and build-time `tastyStatic()` can ship no Tasty styling runtime to the browser.
 
-| 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 |
+| Approach                  | Authoring API                               | CSS is generated                    | Tasty runtime in the browser | Best for                                                         |
+| ------------------------- | ------------------------------------------- | ----------------------------------- | ---------------------------- | ---------------------------------------------------------------- |
+| **Server-only React**     | `tasty()`; optional `@tenphi/tasty/ssr/*`   | During server or static rendering   | None                         | Astro without islands, server-only RSC, SSG                      |
+| **Hydrated React**        | `tasty()` plus `@tenphi/tasty/ssr/*`        | During SSR, then on demand in React | Only in hydrated components  | Interactive React apps, Next.js client components, Astro islands |
+| **Build-time extraction** | `tastyStatic()` from `@tenphi/tasty/static` | During the build                    | None in file mode            | Non-React frameworks or extraction before rendering              |
 
-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).
+- **Server-only `tasty()`** keeps the full feature set (`styleProps`, sub-elements, variants) while generating CSS during server rendering. `tasty()` plus `tastyIntegration({ islands: false })` in Astro is the verified concrete setup and ships no client JavaScript. The same server-only architecture applies to Next.js RSC; verify the generated output for your deployment.
+- **Hydrated `tasty()`** uses the SSR integrations to batch and deduplicate server CSS, prevent FOUC, and hydrate the client cache. The browser styling pipeline is available only where React components hydrate. See [Server-Side Rendering](ssr.md).
+- **Build-time extraction** uses the Babel plugin and additional peer dependencies. Choose `tastyStatic()` when CSS must be generated before rendering or when the consumer is not React. File mode ships no styling runtime; inject mode intentionally includes a tiny CSS injector. See [Build-Time Extraction (`tastyStatic`)](tasty-static.md).
 
 ---
 
@@ -200,7 +221,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
@@ -214,4 +235,4 @@ Both share the same DSL, tokens, units, and state mappings.
 
 - Styles are missing on first render: make sure the file that calls `configure()` is imported before any `tasty()` component renders.
 - Token or unit values are not what you expect: check your `configure({ tokens, units })` setup, then inspect the generated CSS variables with [Debug Utilities](debug.md).
-- You need build-time extraction or server-rendered CSS delivery: use [Zero Runtime (tastyStatic)](tasty-static.md) for extraction, or add [Server-Side Rendering](ssr.md) on top of runtime `tasty()` when your framework renders on the server.
+- You need zero-runtime delivery: use server-only [`tasty()` with server rendering](ssr.md) to keep the full React API, or use [`tastyStatic()` build-time extraction](tasty-static.md) when styles must be compiled before rendering.

package/docs/injector.md

@@ -9,9 +9,9 @@ A high-performance CSS-in-JS solution that powers the Tasty design system with e
 The Style Injector is the core engine behind Tasty's styling system, providing:
 
 - **Hash-based deduplication** - Identical CSS gets the same className
-- **Reference counting** - Automatic cleanup when components unmount (refCount = 0)
+- **DOM-driven lifetime** - Styles are collected once nothing renders them
 - **CSS nesting flattening** - Handles `&`, `.Class`, `SubElement` patterns
-- **Keyframes injection** - First-class `@keyframes` support with immediate disposal
+- **At-rule injection** - First-class `@keyframes`, `@property`, `@font-face`, `@counter-style`, and `@function` support
 - **Smart cleanup** - CSS rules batched cleanup, keyframes disposed immediately
 - **SSR support** - Deterministic class names and CSS extraction
 - **Multiple roots** - Works with Document and ShadowRoot
@@ -63,10 +63,16 @@ const result = inject([{
 
 console.log(result.className); // 't-abc123'
 
-// Cleanup when component unmounts (refCount decremented)
+// Release the pin; the class becomes collectible once nothing renders it
 result.dispose();
 ```
 
+`inject()` **pins** the class it returns, and `gc()` never evicts a pinned class
+— that is what `dispose()` releases. Pass `{ pin: false }` when the caller keeps
+no handle and the DOM is the only record that the class is in use; `dispose()`
+is then a no-op. The render path (`tasty()` / `computeStyles()`) injects this
+way, because a hook-free render has no unmount signal to dispose on.
+
 ### `injectGlobal(rules, options?): { dispose: () => void }`
 
 Injects global styles that don't reserve tasty class names.
@@ -115,11 +121,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 +140,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 +148,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 +215,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)',
@@ -223,13 +230,75 @@ configure({
 
 **Auto-Detection Features:**
 - `devMode`: Automatically enabled in development environments (detected via `isDevEnv()`)
-- `forceTextInjection`: Automatically enabled in test environments (Jest, Vitest, Mocha, jsdom)
+- `forceTextInjection`: Automatically enabled in test environments (Jest, Vitest, Mocha, happy-dom, jsdom)
+
+**Injection Modes:**
+
+Each sheet picks its write mode once, when it is created, and keeps it for its
+lifetime:
+
+| Mode | How rules are written | How rules are removed |
+|---|---|---|
+| CSSOM (default) | `styleSheet.insertRule(rule, index)` | `styleSheet.deleteRule(index)` |
+| Text (`forceTextInjection`, or when `styleElement.sheet` is unavailable) | appended to `<style>.textContent` | rule texts are tracked per sheet and the element's text is rebuilt without them |
+| Adopted (ShadowRoot with constructable sheets) | `insertRule` on the constructable sheet | `deleteRule` on the constructable sheet |
+
+Text mode cannot edit a single rule in place the way CSSOM can, so the sheet
+keeps the inserted rule texts in index order and rewrites the element on delete.
+Dispose, ref-counted cleanup and GC therefore behave identically in every mode.
 
 **Configuration Notes:**
 - 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 renders between sweeps. When the counter reaches this value, a sweep is scheduled via `requestIdleCallback`; without idle callbacks nothing is collected automatically.
+- `gc.grace`: How long a class is left alone after collection first notices nothing is carrying it, in milliseconds (default `10000`).
+
+**What a sweep does.** Everything the injector holds falls into one of five bands, and only the last is ever deleted:
+
+| Band | | Deleted |
+|---|---|---|
+| 1 | **Rendered** — some element carries the class right now | never |
+| 2 | **Not ours** — queued for a batched write, pre-allocated, or server-rendered | never |
+| 3 | **Hot** — nothing carries it, but that was noticed less than `grace` ago | never |
+| 4 | **Cached** — cold, but within `capacity` when ordered by when it went cold | never |
+| 5 | Everything else | on every sweep |
+
+`gc({ force: true })` and `cleanup()` take bands 4 and 5 together, ignoring capacity. Band 3 is spared even then: an explicit cleanup is still no reason to take rules from a render that has not committed yet.
+
+> **Why band 3 exists.** Rendering is not commit-aware: a render can resolve a class and commit it a little later, and in between nothing on the page carries it. From outside React that is indistinguishable from a class that is finished, so collection does not try to tell them apart — it leaves alone anything only just noticed to be cold. A render would have to stay pending for the whole window to lose its rules, and it gets them back on its next render.
+>
+> The clock starts when a sweep *notices*, not when the element actually left — nothing observes that moment, so starting it at the sighting is what gives every class the same full window however long ago it went.
+>
+> This is also why collection costs nothing to run: the timestamps are written by the sweep's own DOM scan, so rendering tracks nothing per class.
+- `gc.capacity`: Maximum number of unused styles (not in the DOM, not pinned) to retain. When exceeded, the least recently used are evicted first. Rendered and pinned styles don't count against this limit.
+
+---
+
+### At-rule injection
+
+Beyond ordinary rules, the injector has a dedicated entry point per at-rule. All of them deduplicate by name and are **permanent** — there is no ref-counting or dispose, because a rule that other CSS references by name cannot be safely removed while any of it might still apply.
+
+| Function | Injects | Notes |
+|---|---|---|
+| `keyframes(steps, nameOrOptions?)` | `@keyframes` | The exception: ref-counted and disposed immediately when unused. Returns the injected name, which may differ from the requested one. |
+| `property(name, options?)` | `@property` | `name` accepts `$name`, `#name`, or `--name`. Usually unnecessary — types are inferred automatically unless `configure({ autoPropertyTypes: false })`. |
+| `fontFace(family, descriptors, options?)` | `@font-face` | Deduplicated by family **and** descriptor content, so several faces of one family coexist. |
+| `counterStyle(name, descriptors, options?)` | `@counter-style` | |
+| `func(name, definition, options?)` | `@function` | `name` accepts `$$name`, `$name`, or `--name`. Abbreviated because `function` is a reserved word. |
+
+Every one of these takes an optional `root` (a `Document` or `ShadowRoot`).
+
+`func()` also accepts `weak: true`, which registers the rule **without** overriding an existing one of the same name. `configure()` uses it for global `@function` definitions so a component-local definition always wins over the global default, regardless of which is injected first.
+
+```ts
+import { counterStyle, fontFace, func, property } from '@tenphi/tasty';
+
+property('$card-elevation', { syntax: '<number>', initialValue: '0' });
+fontFace('Inter', { src: 'url(/inter.woff2)', fontWeight: '400 700' });
+counterStyle('dashes', { system: 'cyclic', symbols: '"—"', suffix: ' ' });
+func('$$negative', { args: ['$value'], result: '(-1 * $value)' });
+```
 
 ---
 
@@ -256,6 +325,17 @@ const styleRule: StyleResult = {
 };
 ```
 
+### Batched Injection
+
+`configure({ batchInjection: true })` queues every sheet write — component
+rules, global rules, raw CSS and at-rules — into one FIFO and applies them
+together, so the document is style-invalidated once per flush instead of once per
+component. `<TastyBatchProvider>` flushes in `useInsertionEffect`, before any
+layout effect, so a queued write can never be observed by a measurement. See
+[Batched injection](configuration.md#batched-injection) for the modes and the
+ordering guarantee. `flushStyles()` applies pending writes on demand; every read
+API here calls it for you.
+
 ### Deduplication & Performance
 
 ```typescript
@@ -274,40 +354,65 @@ const button2 = inject([{
 console.log(button1.className === button2.className); // true
 ```
 
-### Reference Counting
+### Pinning
 
 ```typescript
-// Multiple components using the same styles
+// Multiple callers using the same styles
 const comp1 = inject([commonStyle]);
 const comp2 = inject([commonStyle]);
 const comp3 = inject([commonStyle]);
 
-// Style is kept alive while any component uses it
-comp1.dispose(); // refCount: 3 → 2
-comp2.dispose(); // refCount: 2 → 1
-comp3.dispose(); // refCount: 1 → 0, eligible for bulk cleanup
+// Style is pinned while any caller holds a handle
+comp1.dispose(); // pins: 3 → 2
+comp2.dispose(); // pins: 2 → 1
+comp3.dispose(); // pins: 1 → 0, now up to the DOM and gc()
 
-// Rule exists but refCount = 0 means unused
-// Next inject() with same styles will increment refCount and reuse immediately
+// Unpinned does not mean deleted: the rule stays cached and is reused instantly
+// by the next inject(). gc() decides when it actually goes.
 ```
 
-### Smart Cleanup System
+Pinning covers callers that hold a handle. Styles that come from rendering are
+never pinned — see `{ pin: false }` under
+[`inject()`](#injectrules-options-injectresult) — so what keeps them alive is
+being in the DOM, and nothing else.
+
+### 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()
+//
+// A CSS rule is collectible when no element carries its class AND nobody
+// pinned it with inject().
 
 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 });
+
+// cleanup() is the same thing:
+cleanup();
+
+// Every `touchInterval` renders, a sweep is scheduled in idle time. It scans
+// the DOM for the classes actually on the page and sorts everything the
+// injector holds into five bands — only the last one is deleted. See below.
+
 // 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)
+// - Unused styles stay cached until evicted, so re-rendering them is a cache hit
 ```
 
 ### Shadow DOM Support
@@ -335,14 +440,14 @@ const shadowAnimation = keyframes({
 ### Server-Side Rendering
 
 ```typescript
-import { getCssText, getCssTextForNode } from '@tenphi/tasty';
+import { getCSSText, getCSSTextForNode } from '@tenphi/tasty';
 
 // Extract all CSS for SSR
-const cssText = getCssText();
+const cssText = getCSSText();
 
 // Extract CSS for specific DOM subtree (like jest-styled-components)
 const container = render(<MyComponent />);
-const componentCSS = getCssTextForNode(container);
+const componentCSS = getCSSTextForNode(container);
 ```
 
 ### Test Environment Detection
@@ -351,7 +456,7 @@ const componentCSS = getCssTextForNode(container);
 // Automatically detected test environments:
 // - NODE_ENV === 'test'
 // - Jest globals (jest, describe, it, expect)
-// - jsdom user agent
+// - jsdom / HappyDOM user agent
 // - Vitest globals (vitest)
 // - Mocha globals (mocha)
 
@@ -402,11 +507,11 @@ const metrics = injector.instance.getMetrics();
 console.log({
   cacheHits: metrics.hits,           // Successful cache hits  
   cacheMisses: metrics.misses,       // New styles injected
-  unusedHits: metrics.unusedHits,    // Current unused styles (calculated on demand)
+  unusedHits: metrics.unusedHits,    // Styles currently eligible for eviction (scans the DOM)
   bulkCleanups: metrics.bulkCleanups, // Number of bulk cleanup operations
   stylesCleanedUp: metrics.stylesCleanedUp, // Total styles removed in bulk cleanups
   totalInsertions: metrics.totalInsertions, // Lifetime insertions
-  totalUnused: metrics.totalUnused,  // Total styles marked as unused (refCount = 0)
+  totalUnused: metrics.totalUnused,  // Times a pinned style lost its last pin
   startTime: metrics.startTime,      // Metrics collection start timestamp
   cleanupHistory: metrics.cleanupHistory, // Detailed cleanup operation history
 });
@@ -450,10 +555,10 @@ metrics.cleanupHistory.forEach(cleanup => {
 
 ```typescript
 // ✅ Reuse styles - identical CSS gets deduplicated
-const buttonBase = { padding: '8px 16px', borderRadius: '4px' };
+const buttonBase = 'padding: 8px 16px; border-radius: 4px;';
 
 // ✅ Avoid frequent disposal and re-injection
-// Let the reference counting system handle cleanup
+// Let the injector handle cleanup
 
 // ✅ Use bulk operations for global styles
 injectGlobal([
@@ -462,13 +567,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
+  },
 });
 ```
 
@@ -478,13 +584,13 @@ configure({
 // The injector automatically manages memory through:
 
 // 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
+// 2. DOM-driven lifetime - a rendered class is never evicted
+// 3. Pinning - inject() callers hold their classes until they dispose
+// 4. Immediate keyframes cleanup - disposed instantly when refCount = 0
+// 5. Touch-count GC - unused CSS rules are evicted oldest-first when over capacity
 
 // Manual cleanup is rarely needed but available:
-cleanup(); // Force immediate cleanup of all unused CSS rules (refCount = 0)
+cleanup(); // Remove every rule that is neither rendered nor pinned
 destroy(); // Nuclear option: remove all stylesheets and reset
 ```
 
@@ -506,12 +612,12 @@ const StyledButton = tasty({
 
 // Internally uses the injector:
 // 1. Styles are parsed into StyleResult objects
-// 2. inject() is called with the parsed results
+// 2. inject() is called with the parsed results, unpinned
 // 3. Component gets the returned className
-// 4. dispose() is called when component unmounts
+// 4. gc() reclaims the class once no element carries it
 ```
 
-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 +631,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.