@tenphi/tasty 0.0.0-snapshot.d2dcdeb → 0.0.0-snapshot.d4ccea8

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 [React API](react-api.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()` 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.
+`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 (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 |
+| 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 `tasty()` and `tastyStatic()` share the same DSL, tokens, units, and state mappings.
 
-- **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).
+- **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).
 
 ---
 
@@ -214,4 +235,4 @@ Both `tasty()` and `tastyStatic()` share the same DSL, tokens, units, and state
 
 - 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.
@@ -224,14 +230,62 @@ 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
-- `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.
+- `gc.unsafeAutoCollect`: Sweep automatically as rendering goes, rather than only when you call `gc()` or `cleanup()` (default `false`). See the caveat below.
+- `gc.touchInterval`: Number of touch events between automatic GC cycles, used only with `unsafeAutoCollect`. Each style render counts as a touch. When the counter reaches this value, GC is scheduled via `requestIdleCallback`.
+- `gc.timeoutFallback`: With `unsafeAutoCollect`, schedule the sweep with a timeout where `requestIdleCallback` is unavailable (default `false`). Collection is a background chore, so it otherwise runs only in idle time; opting in trades that for automatic collection on engines that cannot offer any.
+
+> **Why `unsafeAutoCollect` is named that.** A sweep decides what is finished by scanning the DOM, and rendering is not commit-aware: a concurrent render can yield between the `inject()` that creates a class and the commit that attaches it. A sweep landing in that window sees no element carrying the class and deletes rules the pending render is about to use, so the element commits unstyled until something re-renders it. A pending render is indistinguishable from one that already committed and unmounted — React reports neither commit nor discard for a class name handed out during render — so no heuristic closes this; only a real commit signal would.
+>
+> Prefer `gc()` or `cleanup()` at a moment of your choosing: a route change, an idle callback of your own, test teardown.
+- `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)' });
+```
 
 ---
 
@@ -258,6 +312,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
@@ -276,23 +341,28 @@ 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.
 ```
 
+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
@@ -300,6 +370,9 @@ import { configure, gc } from '@tenphi/tasty';
 
 // 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({
   gc: {
@@ -314,15 +387,20 @@ 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.
+// cleanup() is the same thing:
+cleanup();
+
+// Collection is on demand by default: gc() and cleanup() are the whole story,
+// and nothing sweeps behind your back. `gc.unsafeAutoCollect` opts into a sweep
+// every `touchInterval` touches, scheduled via requestIdleCallback — read the
+// caveat below before turning it on.
 
 // Benefits:
 // - 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
@@ -350,14 +428,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
@@ -366,7 +444,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)
 
@@ -417,11 +495,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
 });
@@ -465,10 +543,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([
@@ -494,13 +572,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. 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
+// 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
 ```
 
@@ -522,9 +600,9 @@ 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 [React API](./react-api.md) rather than the injector directly. The injector provides the high-performance foundation that makes Tasty's declarative styling possible.