@tenphi/tasty 0.0.0-snapshot.27b6708 → 0.0.0-snapshot.28eb83c

package/docs/comparison.md

@@ -259,12 +259,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 rendering model notable:
+This also makes Tasty's delivery model notable:
 
-- `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
+- `tasty()` components are hook-free and work as React Server Components. In server-only contexts, they produce HTML + CSS with zero Tasty styling runtime in the browser while retaining the full React feature set. Astro without islands is the concrete integration; server-only Next.js RSC uses the same architecture.
+- `tastyStatic()` with the Babel plugin produces static class-name objects via build-time extraction, with no React dependency — the output works with any JavaScript framework.
 
-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.
+React component features like `styleProps`, sub-element components, and dynamic variants are available in the `tasty()` path whether it renders on the server or in the browser. The `tastyStatic()` path is framework-agnostic but limited to the DSL, tokens, and state logic.
 
 So the tradeoff is roughly:
 
@@ -326,28 +326,28 @@ 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.
+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 ship no Tasty styling runtime 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.
 
 ---
 
-## Build-time vs runtime
+## Where styles are computed
 
 Tasty is not limited to one execution model.
 
-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.
+Zero-runtime delivery is an outcome, not a synonym for `tastyStatic()`. `tasty()` computes styles during React rendering, but that rendering can happen only on the server. In that case it produces HTML + CSS and ships **zero Tasty styling runtime** to the browser. The full feature set — `styleProps`, sub-elements, variants, state maps — remains available. Astro's `tastyIntegration({ islands: false })` is the explicit setup for this path. Server-only Next.js RSC follows the same architecture; verify the generated output for the target deployment.
 
 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.
 
-`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.
+`tastyStatic()` with the Babel plugin reaches zero-runtime delivery differently: CSS is extracted **during the build**, without React. 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 `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:
+This gives Tasty two zero-runtime paths:
 
-- `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
+- server-only `tasty()` for the full React component API, with CSS generated during server or static rendering
+- `tastyStatic()` as a build-time compiler whose output works with any framework, including non-React ones
 
 ---
 
@@ -443,6 +443,6 @@ Tasty is most compelling when the problem is not just "how do we write styles,"
 - [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
+- [Build-Time Extraction (`tastyStatic`)](tasty-static.md) — static styling with the Babel plugin
 - [Adoption Guide](adoption.md) — where Tasty sits in the stack, incremental adoption, and what changes for product engineers
 - [Server-Side Rendering](ssr.md) — SSR setup for Next.js, Astro, and generic frameworks

package/docs/configuration.md

@@ -47,35 +47,35 @@ These docs use `data-schema="dark"` in examples. If your app already standardize
 
 ## Options
 
-| Option               | Type                                             | Default                                 | Description                                                                                                                                                          |
-| -------------------- | ------------------------------------------------ | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `nonce`              | `string`                                         | -                                       | CSP nonce for style elements                                                                                                                                         |
-| `maxRulesPerSheet`   | `number`                                         | `8192`                                  | Maximum rules per injected stylesheet                                                                                                                                |
-| `forceTextInjection` | `boolean`                                        | auto (`true` in test envs)              | Force text-node CSS injection instead of constructable stylesheets                                                                                                   |
-| `devMode`            | `boolean`                                        | auto                                    | Enable development-mode features: performance metrics and debug info                                                                                                 |
-| `states`             | `Record<string, string>`                         | -                                       | Global state aliases for advanced state mapping                                                                                                                      |
-| `parserCacheSize`    | `number`                                         | `1000`                                  | Parser LRU cache size                                                                                                                                                |
-| `units`              | `Record<string, string \| UnitHandler>`          | Built-in                                | Custom units (merged with built-in). See [built-in units](dsl.md#built-in-units)                                                                                     |
-| `functions`          | `Record<string, FunctionDefinition \| Function>` | -                                       | Custom functions (merged). Bare keys → parse functions; `$$name` keys → declarative CSS `@function` definitions                                                      |
-| `handlers`           | `Record<string, StyleHandlerDefinition>`         | Built-in                                | Custom style handlers (replace built-in). See [Custom Style Handlers](#custom-style-handlers)                                                                        |
-| `propHandlers`       | `Record<string, PropHandlerDefinition>`          | -                                       | Props middleware for every component — props in, props out. See [Props Middleware](#props-middleware)                                                                |
-| `baseStyleProps`     | `readonly string[]`                              | -                                       | Style names exposed as props on **every** component. See [Base Style Props](#base-style-props)                                                                       |
-| `tokens`             | `Record<string, value \| stateMap>`              | -                                       | Design tokens injected as `:root` CSS custom properties                                                                                                              |
-| `replaceTokens`      | `Record<string, string \| number \| boolean>`    | -                                       | Parse-time token substitution (inline replacement). `boolean` is allowed for `#` color tokens                                                                        |
-| `keyframes`          | `Record<string, KeyframesSteps>`                 | -                                       | Global keyframes for animations                                                                                                                                      |
-| `properties`         | `Record<string, PropertyDefinition>`             | -                                       | Global CSS @property definitions                                                                                                                                     |
-| `fontFaces`          | `Record<string, FontFaceInput>`                  | -                                       | Global @font-face definitions                                                                                                                                        |
-| `counterStyles`      | `Record<string, CounterStyleDescriptors>`        | -                                       | Global @counter-style definitions                                                                                                                                    |
-| `polyfills`          | `{ functions?: boolean }`                        | `{}`                                    | Opt-in polyfills for not-yet-baseline features. `functions: true` inlines `@function` calls into plain CSS at parse time                                             |
-| `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                                                                                                                            |
-| `plugins`            | `TastyPlugin[]`                                  | -                                       | Plugins that bundle any of the above (processed in order; later override earlier, and direct config wins over all). See [Plugins](plugins.md)                        |
-| `gc`                 | `GCConfig`                                       | -                                       | Garbage-collection tuning for unused styles (`{ touchInterval, capacity }`)                                                                                          |
-| `batchInjection`     | `boolean \| 'always'`                            | `false`                                 | Defer stylesheet writes and apply them in one batch. See [Batched injection](#batched-injection)                                                                     |
-| `colorSpace`         | `'rgb' \| 'hsl' \| 'oklch'`                      | -                                       | **Deprecated** — no longer has any effect. See [Color space](#color-space)                                                                                           |
-| `namePrefix`         | `string`                                         | `'t'` (runtime) / `'ts'` (zero-runtime) | Prefix prepended to every generated identifier (class, keyframe, counter-style names). Must match `^[a-zA-Z_][a-zA-Z0-9_-]{0,31}$`. See [Name prefix](#name-prefix). |
+| Option               | Type                                             | Default                               | Description                                                                                                                                                          |
+| -------------------- | ------------------------------------------------ | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `nonce`              | `string`                                         | -                                     | CSP nonce for style elements                                                                                                                                         |
+| `maxRulesPerSheet`   | `number`                                         | `8192`                                | Maximum rules per injected stylesheet                                                                                                                                |
+| `forceTextInjection` | `boolean`                                        | auto (`true` in test envs)            | Force text-node CSS injection instead of constructable stylesheets                                                                                                   |
+| `devMode`            | `boolean`                                        | auto                                  | Enable development-mode features: performance metrics and debug info                                                                                                 |
+| `states`             | `Record<string, string>`                         | -                                     | Global state aliases for advanced state mapping                                                                                                                      |
+| `parserCacheSize`    | `number`                                         | `1000`                                | Parser LRU cache size                                                                                                                                                |
+| `units`              | `Record<string, string \| UnitHandler>`          | Built-in                              | Custom units (merged with built-in). See [built-in units](dsl.md#built-in-units)                                                                                     |
+| `functions`          | `Record<string, FunctionDefinition \| Function>` | -                                     | Custom functions (merged). Bare keys → parse functions; `$$name` keys → declarative CSS `@function` definitions                                                      |
+| `handlers`           | `Record<string, StyleHandlerDefinition>`         | Built-in                              | Custom style handlers (replace built-in). See [Custom Style Handlers](#custom-style-handlers)                                                                        |
+| `propHandlers`       | `Record<string, PropHandlerDefinition>`          | -                                     | Props middleware for every component — props in, props out. See [Props Middleware](#props-middleware)                                                                |
+| `baseStyleProps`     | `readonly string[]`                              | -                                     | Style names exposed as props on **every** component. See [Base Style Props](#base-style-props)                                                                       |
+| `tokens`             | `Record<string, value \| stateMap>`              | -                                     | Design tokens injected as `:root` CSS custom properties                                                                                                              |
+| `replaceTokens`      | `Record<string, string \| number \| boolean>`    | -                                     | Parse-time token substitution (inline replacement). `boolean` is allowed for `#` color tokens                                                                        |
+| `keyframes`          | `Record<string, KeyframesSteps>`                 | -                                     | Global keyframes for animations                                                                                                                                      |
+| `properties`         | `Record<string, PropertyDefinition>`             | -                                     | Global CSS @property definitions                                                                                                                                     |
+| `fontFaces`          | `Record<string, FontFaceInput>`                  | -                                     | Global @font-face definitions                                                                                                                                        |
+| `counterStyles`      | `Record<string, CounterStyleDescriptors>`        | -                                     | Global @counter-style definitions                                                                                                                                    |
+| `polyfills`          | `{ functions?: boolean }`                        | `{}`                                  | Opt-in polyfills for not-yet-baseline features. `functions: true` inlines `@function` calls into plain CSS at parse time                                             |
+| `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                                                                                                                            |
+| `plugins`            | `TastyPlugin[]`                                  | -                                     | Plugins that bundle any of the above (processed in order; later override earlier, and direct config wins over all). See [Plugins](plugins.md)                        |
+| `gc`                 | `GCConfig`                                       | -                                     | Garbage-collection tuning for unused styles (`{ touchInterval, capacity }`)                                                                                          |
+| `batchInjection`     | `boolean \| 'always'`                            | `false`                               | Defer stylesheet writes and apply them in one batch. See [Batched injection](#batched-injection)                                                                     |
+| `colorSpace`         | `'rgb' \| 'hsl' \| 'oklch'`                      | -                                     | **Deprecated** — no longer has any effect. See [Color space](#color-space)                                                                                           |
+| `namePrefix`         | `string`                                         | `'t'` (`tasty`) / `'ts'` (build-time) | Prefix prepended to every generated identifier (class, keyframe, counter-style names). Must match `^[a-zA-Z_][a-zA-Z0-9_-]{0,31}$`. See [Name prefix](#name-prefix). |
 
 ---
 
@@ -150,7 +150,7 @@ All writes share one FIFO queue — component rules, global rules, raw CSS,
 Draining it in insertion order keeps the sheet byte-identical to unbatched
 output, which matters because equal-specificity rules resolve by document order.
 
-### SSR, RSC and zero-runtime
+### Client rendering, server rendering, and build-time extraction
 
 **Server render — nothing to batch, safe to leave enabled.** SSR and RSC collect
 CSS as text through `ServerStyleCollector`; the runtime injector never runs
@@ -175,12 +175,12 @@ tasty components to be worth it. `'always'` needs no provider and covers every
 island, at the cost of the measurement hazard above. Either way, an island that
 only re-hydrates server-rendered classes has nothing to batch.
 
-**Zero-runtime (`tastyStatic`) — unaffected.** Build-time extraction never
+**Build-time extraction (`tastyStatic`) — unaffected.** The Babel plugin never
 touches the injector: the babel plugin emits either a CSS file import or an
 `injectCSS()` call from `@tenphi/tasty/static/inject`, which appends text to a
 single `<style data-tasty-static>` element. `batchInjection` only defers CSSOM
-writes made by the runtime injector, so extracted styles are unchanged. In an app
-that mixes both, it still applies to the runtime half.
+writes made by the browser injector, so extracted styles are unchanged. In an app
+that mixes both, it still applies to the `tasty()` half.
 
 ### `flushStyles()`
 
@@ -284,7 +284,7 @@ color syntax works on every `<color>`, including a `color-mix()`, a
 
 ## Name Prefix
 
-Every identifier Tasty generates — class names, keyframe names, counter-style names — starts with a configurable prefix. The runtime, SSR, and RSC paths default to `'t'`; the zero-runtime build path (`tastyStatic` via the Babel plugin) defaults to `'ts'` so static-extracted classes can never collide with runtime classes when both are loaded on the same page.
+Every identifier Tasty generates — class names, keyframe names, counter-style names — starts with a configurable prefix. The `tasty()` client, SSR, and RSC paths default to `'t'`; the build-time extraction path (`tastyStatic` via the Babel plugin) defaults to `'ts'` so extracted classes can never collide with `tasty()` classes when both are loaded on the same page.
 
 ```jsx
 configure({
@@ -294,12 +294,12 @@ configure({
 
 The prefix is prepended verbatim to the hash, so include any separator inside the prefix string itself:
 
-| Setting                       | Class         | Keyframe       | Counter-style  |
-| ----------------------------- | ------------- | -------------- | -------------- |
-| `'t'` (runtime default)       | `t1a2b3`      | `tk1a2b3`      | `tc1a2b3`      |
-| `'ts'` (zero-runtime default) | `ts1a2b3`     | `tsk1a2b3`     | `tsc1a2b3`     |
-| `'mb'`                        | `mb1a2b3`     | `mbk1a2b3`     | `mbc1a2b3`     |
-| `'myapp-'`                    | `myapp-1a2b3` | `myapp-k1a2b3` | `myapp-c1a2b3` |
+| Setting                     | Class         | Keyframe       | Counter-style  |
+| --------------------------- | ------------- | -------------- | -------------- |
+| `'t'` (`tasty` default)     | `t1a2b3`      | `tk1a2b3`      | `tc1a2b3`      |
+| `'ts'` (build-time default) | `ts1a2b3`     | `tsk1a2b3`     | `tsc1a2b3`     |
+| `'mb'`                      | `mb1a2b3`     | `mbk1a2b3`     | `mbc1a2b3`     |
+| `'myapp-'`                  | `myapp-1a2b3` | `myapp-k1a2b3` | `myapp-c1a2b3` |
 
 The single-letter discriminators (`k` for keyframes, `c` for counter-styles) keep the three kinds visually distinct in devtools — they are not required for correctness because CSS keeps these in separate namespaces.
 
@@ -309,12 +309,12 @@ The single-letter discriminators (`k` for keyframes, `c` for counter-styles) kee
 - Validated at `configure()` time; an invalid prefix throws synchronously rather than silently producing broken hydration.
 - Locked once styles have been generated, like all other config.
 
-### Coexistence with the zero-runtime build
+### Coexistence with build-time extraction
 
-The runtime and zero-runtime builds **must use different prefixes** when both are loaded on the same page. Defaults already guarantee this; if you customize one, customize the other accordingly:
+The `tasty()` and `tastyStatic()` paths **must use different prefixes** when both are loaded on the same page. Defaults already guarantee this; if you customize one, customize the other accordingly:
 
 ```jsx
-// app config (runtime / SSR / RSC)
+// app config (client / SSR / RSC)
 configure({ namePrefix: 'mb' });
 
 // tasty-zero.config.ts (Babel plugin)
@@ -352,7 +352,7 @@ configure({
 - `#name` keys become `--name-color` custom properties
 - Names keep their case, since CSS custom properties are case-sensitive: `$myVar` is `--myVar` and is referenced as `$myVar`. A leading capital is not supported and folds — `$Foo` and `#Purple` become `--foo` and `--purple-color` — so start names lowercase. Kebab-case (`$my-var`) remains the convention.
 
-Tokens are automatically emitted in all rendering modes: runtime (client), SSR, and zero-runtime (Babel plugin).
+Tokens are automatically emitted in all delivery modes: client rendering, server rendering, and build-time extraction with the Babel plugin.
 
 ---
 
@@ -617,7 +617,7 @@ configure({
 
 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).
+Global styles are automatically emitted in all delivery modes: client rendering, server rendering, and build-time extraction with the Babel plugin. Plugins can also provide `globalStyles`; they are merged per selector with config global styles (config wins on conflict).
 
 ---
 
@@ -625,7 +625,7 @@ Global styles are automatically emitted in all rendering modes: runtime (client)
 
 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.
 
-This works across all declaration contexts: component styles, `@keyframes`, global config, and the zero-runtime Babel plugin. It also resolves `var()` chains — if `$a` references `var(--b)`, the type propagates once `--b` is resolved.
+This works across all declaration contexts: component styles, `@keyframes`, global config, and build-time extraction with the Babel plugin. It also resolves `var()` chains — if `$a` references `var(--b)`, the type propagates once `--b` is resolved.
 
 Supported types:
 
@@ -784,7 +784,7 @@ Handlers run at the very top of every component's render, before any prop is des
 
 Handlers must be **pure** and must not mutate their input, and should memoize the styles they build per input value: style values are cached by object identity, so mutating one in place yields stale CSS, and a reference-stable object avoids re-serializing on every render.
 
-Injected styles occupy the `styles` slot, so they beat a component's own default styles and lose to a style prop at the call site. Prop handlers do not apply to sub-elements or to zero-runtime `tastyStatic()`, which has no props.
+Injected styles occupy the `styles` slot, so they beat a component's own default styles and lose to a style prop at the call site. Prop handlers do not apply to sub-elements or to build-time `tastyStatic()`, which has no props.
 
 See [Plugins → Props middleware](plugins.md#props-middleware) for the full contract and a worked example.
 

package/docs/debug.md

@@ -6,9 +6,7 @@ Runtime CSS inspection and diagnostics for the Tasty styling system. Inspect inj
 
 ## Overview
 
-`tastyDebug` is a diagnostic object that exposes Tasty's runtime CSS state. It is designed for development use but can be manually installed in production for debugging.
-
-In development mode (`isDevEnv()` returns `true`), `tastyDebug` is automatically installed on `window.tastyDebug`. In production, install it manually when needed.
+`tastyDebug` is a diagnostic object that exposes Tasty's runtime CSS state. It is designed for development use and can be installed on `window` explicitly when needed.
 
 All methods **log to the console by default**. Pass `{ raw: true }` to suppress logging and only return data.
 
@@ -19,7 +17,6 @@ All methods **log to the console by default**. Pass `{ raw: true }` to suppress
 ## Quick Start
 
 ```typescript
-// Auto-installed in dev mode. Otherwise:
 import { tastyDebug } from '@tenphi/tasty';
 tastyDebug.install();
 
@@ -54,6 +51,19 @@ interface DebugOptions {
 
 When `raw` is `false` (the default), results are logged to the console **and** returned. When `raw` is `true`, results are returned silently.
 
+### Environments Without a DOM
+
+`tastyDebug` reads the document, so on a server — SSR, a Node REPL, a test
+runner in the `node` environment — there is nothing for it to read. Every
+method returns its empty result (`''`, an empty `InspectResult`, a summary of
+zeroes, `metrics: null`) instead of throwing, and explains itself once with a
+console warning. `{ raw: true }` suppresses that warning along with the rest of
+the logging.
+
+To see the styles a server render produced, read the `ServerStyleCollector`
+instead — `collector.getCSS()` and `collector.getRenderedClassNames()`. See
+[SSR](./ssr.md).
+
 ---
 
 ## API Reference
@@ -68,7 +78,7 @@ Retrieves CSS text for a given target. Logs the result with rule count and size.
 |---|---|
 | `'all'` | All tasty CSS (component + global + raw) |
 | `'active'` | CSS for classes currently in the DOM |
-| `'unused'` | CSS with refCount = 0 (cached but not used) |
+| `'unused'` | CSS for injected classes no element carries (cached but not rendered) |
 | `'global'` | Only global CSS (from `injectGlobal`) |
 | `'page'` | All CSS on the page (including non-tasty) |
 | `'t3a5f'` | CSS for a specific tasty class (class names are `t` + base36 hash) |
@@ -241,7 +251,9 @@ tastyDebug.cache();
 
 ### `cleanup(opts?): void`
 
-Forces immediate cleanup of all unused styles (those with `refCount = 0`).
+Removes every injected style that is neither carried by an element nor pinned by
+an outstanding `inject()` handle — the same set `summary()` reports as unused.
+Equivalent to `gc({ force: true })`.
 
 ```typescript
 tastyDebug.cleanup();
@@ -262,7 +274,7 @@ tastyDebug.help();
 
 ### `install(): void`
 
-Attaches `tastyDebug` to `window.tastyDebug`. Called automatically in development mode.
+Attaches `tastyDebug` to `window.tastyDebug`.
 
 ```typescript
 import { tastyDebug } from '@tenphi/tasty';

package/docs/dsl.md

@@ -2,9 +2,9 @@
 
 This is the language behind Tasty’s predictable state resolution. Every property can use a state map; later branches declare higher priority, and Tasty compiles them so only one generated selector can match.
 
-The same value syntax, state maps, tokens, units, extension semantics, and special declarations apply to runtime `tasty()` and build-time `tastyStatic()`.
+The same value syntax, state maps, tokens, units, extension semantics, and special declarations apply to React `tasty()`—whether rendered on the client or server—and build-time `tastyStatic()`.
 
-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).
+For the React API (`tasty()`, style functions, 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).
 
 ---
 
@@ -1018,4 +1018,4 @@ For a complete reference of all enhanced style properties — syntax, values, mo
 - **[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
-- **[Zero Runtime (tastyStatic)](tasty-static.md)** — Build-time static styling with Babel plugin
+- **[Build-Time Extraction (`tastyStatic`)](tasty-static.md)** — Static styling with the Babel plugin

package/docs/getting-started.md

@@ -200,19 +200,19 @@ export default [tasty.configs.strict];
 
 ## 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).
 
 ---
 
@@ -235,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,7 +9,7 @@ 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
 - **At-rule injection** - First-class `@keyframes`, `@property`, `@font-face`, `@counter-style`, and `@function` support
 - **Smart cleanup** - CSS rules batched cleanup, keyframes disposed immediately
@@ -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.
@@ -245,8 +251,27 @@ Dispose, ref-counted cleanup and GC therefore behave identically in every mode.
 - 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.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.
 
 ---
 
@@ -329,23 +354,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
@@ -353,6 +383,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: {
@@ -367,15 +400,19 @@ 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();
+
+// 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:
 // - 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
@@ -470,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
 });
@@ -521,7 +558,7 @@ metrics.cleanupHistory.forEach(cleanup => {
 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([
@@ -547,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. 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
 ```
 
@@ -575,9 +612,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.

package/docs/methodology.md

@@ -122,10 +122,10 @@ Tasty exports predefined style prop lists that group properties by role. Use the
 | Preset             | Properties                                                                                                                                                                     | Typical use                                   |
 | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------- |
 | `FLOW_STYLES`      | flow, gap, columnGap, rowGap, align, justify, placeItems, placeContent, alignItems, alignContent, justifyItems, justifyContent, gridColumns, gridRows, gridTemplate, gridAreas | Layout containers (`Space`, `Grid`)           |
-| `POSITION_STYLES`  | gridArea, gridColumn, gridRow, order, placeSelf, alignSelf, justifySelf, zIndex, margin, inset, position                                                                       | Positioned elements (`Button`, `Badge`)       |
-| `DIMENSION_STYLES` | width, height, flexBasis, flexGrow, flexShrink, flex                                                                                                                           | Sized elements                                |
+| `POSITION_STYLES`  | gridArea, gridColumn, gridRow, order, placeSelf, alignSelf, justifySelf, zIndex, physical/logical margin, inset, scroll margin/padding, position                                 | Positioned elements (`Button`, `Badge`)       |
+| `DIMENSION_STYLES` | width, height, blockSize, inlineSize, flexBasis, flexGrow, flexShrink, flex                                                                                                    | Sized elements                                |
 | `COLOR_STYLES`     | color, fill, fade, image                                                                                                                                                       | Color-customizable elements                   |
-| `BLOCK_STYLES`     | padding, paddingInline, paddingBlock, overflow, scrollbar, textAlign, border, radius, shadow, outline                                                                          | Block-level containers                        |
+| `BLOCK_STYLES`     | padding, blockPadding, inlinePadding, overflow, scrollbar, textAlign, border, blockBorder, inlineBorder, radius, shadow, outline                                               | Block-level containers                        |
 | `CONTAINER_STYLES` | All of the above combined (+ BASE_STYLES)                                                                                                                                      | Fully flexible containers                     |
 | `OUTER_STYLES`     | POSITION_STYLES + DIMENSION_STYLES + block outer (border, radius, shadow, outline)                                                                                             | Components whose outer shell is customizable  |
 | `INNER_STYLES`     | BASE_STYLES + COLOR_STYLES + block inner (padding, overflow, scrollbar) + FLOW_STYLES                                                                                          | Components whose inner layout is customizable |