@tenphi/tasty 3.3.1 → 3.5.0

package/README.md

@@ -5,8 +5,8 @@
 <h1 align="center">Tasty</h1>
 
 <p align="center">
-  <strong>Deterministic styling for stateful component systems.</strong><br>
-  A design-system styling engine that compiles component states into mutually exclusive selectors, so complex components stay predictable as they evolve.
+  <strong>CSS-in-JS for React design systems.</strong><br>
+  Build components whose styles don’t fight.
 </p>
 
 <p align="center">
@@ -17,44 +17,57 @@
 
 ---
 
-Tasty is a styling engine for design systems that generates deterministic CSS for stateful components.
+Describe hover, disabled, variants, themes, and responsive behavior as state maps. Tasty makes one branch win by design—without specificity fights or source-order surprises.
 
-It compiles state maps into **mutually exclusive selectors**, so for a given property and component state, one branch wins by construction instead of competing through cascade and specificity.
+```tsx
+import { tasty } from '@tenphi/tasty';
 
-That is the core guarantee: component styling resolves from declared state logic, not from source-order accidents or specificity fights.
+const Button = tasty({
+  as: 'button',
+  styles: {
+    fill: {
+      '': '#primary',
+      ':hover': '#primary-hover',
+      ':active': '#primary-pressed',
+      '[disabled]': '#surface',
+    },
+  },
+});
+```
 
-The practical payoff shows up later: adding states, variants, and overrides stays inside the state map instead of reopening selector logic by hand.
+Later branches have higher priority. If this button is both hovered and disabled, `[disabled]` wins and the hover rule is excluded. Tasty compiles that decision into mutually exclusive selectors, so the result does not depend on CSS source order.
 
-Tasty fits best when you are building a design system or component library with intersecting states, variants, tokens, sub-elements, responsive rules, and extension semantics that need to stay predictable over time.
+That is the core promise: add states, variants, themes, and overrides without reopening selector logic by hand.
 
-On top of that foundation, Tasty gives teams a governed styling model: a CSS-like DSL, tokens, recipes, typed style props, sub-elements, and multiple rendering modes.
+Tasty fits best when you are building a design system or component library whose components need to stay predictable as their state logic grows. Alongside state maps, it provides a CSS-like DSL, typed style props, tokens, recipes, sub-elements, and client-side, server-only, or build-time CSS delivery.
 
-- **New here?** Start with [Comparison](docs/comparison.md) if you are evaluating fit.
-- **Adopting Tasty?** Read the [Adoption Guide](docs/adoption.md).
-- **Want the mechanism first?** Jump to [How It Actually Works](#how-it-actually-works).
-- **Ready to build?** Go to [Getting Started](docs/getting-started.md).
+- **Ready to try it?** Follow [Getting Started](docs/getting-started.md).
+- **Evaluating fit?** Read [Comparison](docs/comparison.md) and the [Adoption Guide](docs/adoption.md).
+- **Want the compiler model?** Jump to [How It Actually Works](#how-it-actually-works).
+- **Building a component library?** See [Methodology](docs/methodology.md) and [Building a Design System](docs/design-system.md).
 
 ## Why Tasty
 
-- **Deterministic composition, not cascade fights** — Stateful styles resolve from the state map you declared, not from selector competition. See [How It Actually Works](#how-it-actually-works).
-- **Easier to extend over time** — When components gain new states, variants, or overrides, you update declared branches instead of re-deriving selector interactions by hand.
-- **Built for design-system teams** — Best fit for reusable component systems with complex state interactions.
-- **A governed styling model, not just syntax sugar** — Design-system authors define the styling language product teams consume.
-- **DSL that still feels like CSS** — Familiar property names, less selector boilerplate. Start with the [Style DSL](docs/dsl.md), then use [Style Properties](docs/styles.md) as the handler reference.
+- **States that don’t fight** — Each property’s state map compiles into mutually exclusive selectors, so one branch wins by construction.
+- **Safe to extend** — Add variants, overrides, and new states without re-deriving selector interactions.
+- **Built for component systems** — Model roots and sub-elements together and expose governed, typed component APIs.
+- **Your design system’s language** — Define tokens, units, aliases, recipes, style props, and parser rules for your system.
+- **One model for every state** — Pseudo-classes, modifiers, root and parent states, media and container queries, `:has()`, and `@supports` all use state maps.
+- **Client, server, or build time** — Use `tasty()` in client React, React Server Components, SSR, and static server rendering, or use `tastyStatic()` for framework-agnostic build-time extraction.
 
 ### Supporting capabilities
 
 - **Typed style props and mod props** — `styleProps` exposes selected CSS properties as typed React props (`<Space flow="row" gap="2x">`); `modProps` does the same for modifier keys (`<Button isLoading size="large">`). Both support state maps and full TypeScript autocomplete. See [Style Props](#style-props) and [Mod Props](#mod-props).
-- **Server-compatible by default, zero client JS in server-only contexts** — All `tasty()` components and style functions are hook-free. In server-only rendering (Next.js RSC, Astro without islands, SSG), they produce zero client JavaScript with the full feature set. Add SSR integration only when your app also has client-side hydration. Use `tastyStatic()` only when you need build-time extraction without React.
+- **Zero client styling runtime with the full React API** — All `tasty()` components and style functions are hook-free. In server-only rendering, they generate CSS on the server and ship no Tasty styling runtime to the browser. Astro without islands is the concrete integration; server-only Next.js RSC follows the same architecture. Use `tastyStatic()` when you specifically need build-time extraction without React.
 - **Broad modern CSS coverage** — Media queries, container queries, `@supports`, `:has()`, `@starting-style`, `@property`, `@keyframes`, `@font-face`, `@counter-style`, `@function`, and more. Features that do not fit the component model (such as `@layer` and `!important`) are intentionally left out.
-- **Performance and caching** — Runtime mode injects CSS on demand, reuses chunks aggressively, and relies on multi-level caching so large component systems stay practical.
+- **Performance and caching** — When styles are generated in the browser, Tasty injects CSS on demand, reuses chunks aggressively, and relies on multi-level caching so large component systems stay practical.
 - **TypeScript-first and AI-friendly** — Style definitions are declarative, structurally consistent, and fully typed, which helps both humans and tooling understand advanced stateful styles without hidden cascade logic.
 
-## Why It Exists
+## Why State Maps Matter
 
-Modern component styling becomes fragile when multiple selectors can still win for the same property. Hover, disabled, theme, breakpoint, parent state, and root state rules start competing through specificity and source order.
+Component styling becomes fragile when multiple selectors can win for the same property. Hover, disabled, theme, breakpoint, parent state, and root state rules start competing through specificity and source order.
 
-Tasty replaces that competition with explicit state-map resolution. Each property compiles into mutually exclusive branches, so component styling stays deterministic as systems grow. For the full mechanism, jump to [How It Actually Works](#how-it-actually-works).
+Tasty replaces that competition with explicit priority in the state map. Each property compiles into mutually exclusive branches, so only one generated selector can match. For the full mechanism, jump to [How It Actually Works](#how-it-actually-works).
 
 ## Installation
 
@@ -83,7 +96,7 @@ For the fuller docs map beyond the quick routes above, start here:
 - **[Adoption Guide](docs/adoption.md)** — understand who Tasty is for, where it fits, and how to introduce it incrementally
 - **[Getting Started](docs/getting-started.md)** — the canonical onboarding path: install, first component, optional shared `configure()`, ESLint, editor tooling, and rendering mode selection
 - **[Style rendering pipeline](docs/pipeline.md)** — see the selector model behind deterministic style resolution
-- **[Docs Hub](docs/README.md)** — choose docs by role and task: runtime, zero-runtime, runtime SSR integration, design-system authoring, internals, and debugging
+- **[Docs Hub](docs/README.md)** — choose docs by role and task: React rendering, zero-client-runtime delivery, build-time extraction, design-system authoring, internals, and debugging
 - **[Methodology](docs/methodology.md)** — the recommended component model and public API conventions for design-system code
 
 ## Quick Start
@@ -108,7 +121,7 @@ const Card = tasty({
 });
 
 // Just a React component
-<Card>Hello World</Card>
+<Card>Hello World</Card>;
 ```
 
 Every value maps to CSS you'd recognize. This example is intentionally a simple first contact, not a tour of the whole DSL.
@@ -128,22 +141,22 @@ const Button = tasty({
       '': '#primary',
       ':hover': '#primary-hover',
       ':active': '#primary-pressed',
-      '[disabled]': '#surface',
+      disabled: '#surface',
     },
     color: {
       '': '#on-primary',
-      '[disabled]': '#text.40',
+      disabled: '#text.40',
     },
     cursor: {
       '': 'pointer',
-      '[disabled]': 'not-allowed',
+      disabled: 'not-allowed',
     },
     transition: 'theme',
   },
 });
 ```
 
-State keys support pseudo-classes first (`:hover`, `:active`), then modifiers (`theme=danger`), attributes (`[disabled]`), media/container queries, root states, and more. Tasty compiles them into exclusive selectors automatically.
+State keys support pseudo-classes (`:hover`, `:active`), modifiers (`theme=danger`), attributes, media/container queries, root states, and more. The built-in `disabled` and `checked` states automatically track their corresponding native props or attributes; `disabled` is the concise Tasty form of `[disabled]`. Tasty compiles state maps into exclusive selectors automatically.
 
 ### Extend any component
 
@@ -171,7 +184,8 @@ configure({
   states: {
     '@mobile': '@media(w < 768px)',
     '@tablet': '@media(w < 1024px)',
-    '@dark': '@root(schema=dark) | (!@root(schema) & @media(prefers-color-scheme: dark))',
+    '@dark':
+      '@root(schema=dark) | (!@root(schema) & @media(prefers-color-scheme: dark))',
   },
   recipes: {
     card: { padding: '4x', fill: '#surface', radius: '1r', border: true },
@@ -187,7 +201,9 @@ Use `configure()` once when your app or design system needs shared aliases, toke
 
 ```tsx
 <Space flow="row" gap="2x" placeItems="center">
-  <Button isLoading size="large" placeSelf="end">Submit</Button>
+  <Button isLoading size="large" placeSelf="end">
+    Submit
+  </Button>
 </Space>
 ```
 
@@ -195,15 +211,15 @@ See [Style Props](#style-props) and [Mod Props](#mod-props) below, or the full r
 
 ## Choose a Styling Approach
 
-Once you understand the component model, pick the rendering mode that matches your app.
+Once you understand the component model, choose where Tasty should generate CSS. Zero-runtime delivery is an outcome, not a synonym for `tastyStatic()`.
 
-| 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; CSS computed during React rendering (server or client) |
-| **Runtime + SSR integration** | Add `@tenphi/tasty/ssr/*` | Apps with client-side hydration (Next.js client components, Astro islands) | Adds CSS deduplication, FOUC prevention, and client cache hydration |
-| **Zero-runtime** | `tastyStatic()` from `@tenphi/tasty/static` | Non-React frameworks or when you need build-time extraction without React | Requires the Babel plugin; no component-level `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 CSS that must be extracted before rendering |
 
-All `tasty()` components are hook-free and work as React Server Components. In server-only contexts — Next.js RSC without `'use client'`, Astro without `client:*` directives, and other SSG setups — they produce the same end result as `tastyStatic()` (static HTML + CSS, zero client JavaScript) but with the full feature set including `styleProps`, sub-elements, and variants. SSR integration is only needed when your app also has client-side rendering. See [Getting Started](docs/getting-started.md#choosing-a-rendering-mode), [Zero Runtime](docs/tasty-static.md), and [Server-Side Rendering](docs/ssr.md).
+The first approach and `tastyStatic()`'s default file mode both ship zero Tasty styling runtime to the browser. The difference is authoring and timing: server-only `tasty()` retains `styleProps`, sub-elements, variants, and the rest of the React API, while `tastyStatic()` extracts build-time-known styles without a React dependency. (`tastyStatic()` inject mode intentionally ships a tiny CSS injector.) Astro supports the server-only path directly with `tastyIntegration({ islands: false })`; the same server-only model applies to Next.js RSC, though you should verify the output for your deployment. See [Getting Started](docs/getting-started.md#choosing-a-rendering-mode), [Build-Time Extraction](docs/tasty-static.md), and [Server-Side Rendering](docs/ssr.md).
 
 ## How It Actually Works
 
@@ -218,15 +234,19 @@ First, the **cascade** resolves conflicts by specificity and source order: when
 A small example makes this tangible. Two rules for a button's background:
 
 ```css
-.btn:hover     { background: dodgerblue; }
-.btn[disabled] { background: gray; }
+.btn:hover {
+  background: dodgerblue;
+}
+.btn[disabled] {
+  background: gray;
+}
 ```
 
-Both selectors have specificity `(0, 1, 1)`. When the button is hovered **and** disabled, both match — and the last rule in source order wins. Swap the two lines and a hovered disabled button silently turns blue instead of gray. This class of bug is invisible in code review because the logic is correct; only the ordering is wrong.
+Both selectors have specificity `(0, 2, 0)`. When the button is hovered **and** disabled, both match — and the last rule in source order wins. Swap the two lines and a hovered disabled button silently turns blue instead of gray. This class of bug is invisible in code review because the logic is correct; only the ordering is wrong.
 
 ### Why real state logic is hard to author by hand
 
-Authoring selectors that capture real-world state logic is fundamentally hard. A single state like "dark mode" may depend on a root attribute, an OS preference, or both — each branch needing its own selector, proper negation of competing branches, and correct `@media` nesting. The example below shows the CSS you'd write by hand for just *one* property with *one* state. Scale that across dozens of properties, then add breakpoints and container queries, and the selector logic quickly becomes unmanageable.
+Authoring selectors that capture real-world state logic is fundamentally hard. A single state like "dark mode" may depend on a root attribute, an OS preference, or both — each branch needing its own selector, proper negation of competing branches, and correct `@media` nesting. The example below shows the CSS you'd write by hand for just _one_ property with _one_ state. Scale that across dozens of properties, then add breakpoints and container queries, and the selector logic quickly becomes unmanageable.
 
 ### What Tasty generates instead
 
@@ -251,10 +271,16 @@ If `@dark` expands to `@root(schema=dark) | (!@root(schema) & @media(prefers-col
 
 ```css
 /* First attempt — the @media branch is too broad */
-.t0 { color: var(--text-color); }
-:root[data-schema="dark"] .t0 { color: var(--text-on-dark-color); }
+.t0 {
+  color: var(--text-color);
+}
+:root[data-schema='dark'] .t0 {
+  color: var(--text-on-dark-color);
+}
 @media (prefers-color-scheme: dark) {
-  .t0 { color: var(--text-on-dark-color); }
+  .t0 {
+    color: var(--text-on-dark-color);
+  }
 }
 ```
 
@@ -262,20 +288,26 @@ The `@media` branch fires even when `data-schema="light"` is explicitly set. Fix
 
 ```css
 /* Second attempt — @media is scoped, but the default is still too broad */
-.t0 { color: var(--text-color); }
-:root[data-schema="dark"] .t0 { color: var(--text-on-dark-color); }
+.t0 {
+  color: var(--text-color);
+}
+:root[data-schema='dark'] .t0 {
+  color: var(--text-on-dark-color);
+}
 @media (prefers-color-scheme: dark) {
-  :root:not([data-schema]) .t0 { color: var(--text-on-dark-color); }
+  :root:not([data-schema]) .t0 {
+    color: var(--text-on-dark-color);
+  }
 }
 ```
 
 Better — but the bare `.t0` default still matches unconditionally. It matches in dark mode, it matches when `data-schema="dark"` is set, and it can beat the attribute selector by source order if another rule re-declares it later. There is no selector that says "apply this default only when none of the dark branches win."
 
-This is just *one* property with *one* state, and getting it right already takes multiple iterations. The correct selectors require negating every other branch — which is exactly what Tasty generates automatically:
+This is just _one_ property with _one_ state, and getting it right already takes multiple iterations. The correct selectors require negating every other branch — which is exactly what Tasty generates automatically:
 
 ```css
 /* Branch 1: Explicit dark schema */
-:root[data-schema="dark"] .t0.t0 {
+:root[data-schema='dark'] .t0.t0 {
   color: var(--text-on-dark-color);
 }
 
@@ -288,13 +320,13 @@ This is just *one* property with *one* state, and getting it right already takes
 
 /* Default: no schema + OS does not prefer dark */
 @media (not (prefers-color-scheme: dark)) {
-  :root:not([data-schema="dark"]) .t0.t0 {
+  :root:not([data-schema='dark']) .t0.t0 {
     color: var(--text-color);
   }
 }
 
 /* Default: schema is set but not dark (any OS preference) */
-:root:not([data-schema="dark"])[data-schema] .t0.t0 {
+:root:not([data-schema='dark'])[data-schema] .t0.t0 {
   color: var(--text-color);
 }
 ```
@@ -323,13 +355,13 @@ radius: '1r',             // → var(--radius)
 border: '1bw solid #border',
 ```
 
-| Unit | Maps to | Example |
-|------|---------|---------|
-| `x` | `--gap` multiplier | `2x` → `calc(var(--gap) * 2)` |
-| `r` | `--radius` multiplier | `1r` → `var(--radius)` |
-| `bw` | `--border-width` multiplier | `1bw` → `var(--border-width)` |
+| Unit | Maps to                      | Example                        |
+| ---- | ---------------------------- | ------------------------------ |
+| `x`  | `--gap` multiplier           | `2x` → `calc(var(--gap) * 2)`  |
+| `r`  | `--radius` multiplier        | `1r` → `var(--radius)`         |
+| `bw` | `--border-width` multiplier  | `1bw` → `var(--border-width)`  |
 | `ow` | `--outline-width` multiplier | `1ow` → `var(--outline-width)` |
-| `cr` | `--card-radius` multiplier | `1cr` → `var(--card-radius)` |
+| `cr` | `--card-radius` multiplier   | `1cr` → `var(--card-radius)`   |
 
 Define your own units via `configure({ units: { ... } })`.
 
@@ -337,19 +369,19 @@ Define your own units via `configure({ units: { ... } })`.
 
 Every style property accepts a state mapping object. Keys can be combined with boolean logic:
 
-| State type | Syntax | CSS output |
-|------------|--------|------------|
-| Data attribute (boolean modifier) | `disabled` | `[data-disabled]` |
-| Data attribute (value modifier) | `theme=danger` | `[data-theme="danger"]` |
-| Pseudo-class | `:hover` | `:hover` |
-| Attribute selector | `[role="tab"]` | `[role="tab"]` |
-| Class selector (supported) | `.is-active` | `.is-active` |
-| Media query | `@media(w < 768px)` | `@media (width < 768px)` |
-| Container query | `@(panel, w >= 300px)` | `@container panel (width >= 300px)` |
-| Root state | `@root(schema=dark)` | `:root[data-schema="dark"]` |
-| Parent state | `@parent(theme=danger)` | `:is([data-theme="danger"] *)` |
-| Feature query | `@supports(display: grid)` | `@supports (display: grid)` |
-| Entry animation | `@starting` | `@starting-style` |
+| State type                        | Syntax                     | CSS output                          |
+| --------------------------------- | -------------------------- | ----------------------------------- |
+| Data attribute (boolean modifier) | `disabled`                 | `[data-disabled]`                   |
+| Data attribute (value modifier)   | `theme=danger`             | `[data-theme="danger"]`             |
+| Pseudo-class                      | `:hover`                   | `:hover`                            |
+| Attribute selector                | `[role="tab"]`             | `[role="tab"]`                      |
+| Class selector (supported)        | `.is-active`               | `.is-active`                        |
+| Media query                       | `@media(w < 768px)`        | `@media (width < 768px)`            |
+| Container query                   | `@(panel, w >= 300px)`     | `@container panel (width >= 300px)` |
+| Root state                        | `@root(schema=dark)`       | `:root[data-schema="dark"]`         |
+| Parent state                      | `@parent(theme=danger)`    | `:is([data-theme="danger"] *)`      |
+| Feature query                     | `@supports(display: grid)` | `@supports (display: grid)`         |
+| Entry animation                   | `@starting`                | `@starting-style`                   |
 
 Combine with `&` (AND), `|` (OR), `!` (NOT), `^` (XOR):
 
@@ -398,14 +430,16 @@ const Button = tasty({
   },
 });
 
-<Button isLoading size="lg">Submit</Button>
+<Button isLoading size="lg">
+  Submit
+</Button>;
 ```
 
 See [React API - Mod Props](docs/react-api.md#mod-props) and [Methodology - modProps](docs/methodology.md#modprops-and-mods).
 
 ### Variants
 
-Variants let one component expose named visual versions without pre-generating a separate class for every possible combination. In runtime mode, Tasty emits only the variant CSS that is actually used.
+Variants let one component expose named visual versions without pre-generating a separate class for every possible combination. With `tasty()`, Tasty emits only the variant CSS that is actually used, whether rendering happens on the server or in the browser.
 
 See [React API - Variants](docs/react-api.md#variants).
 
@@ -441,12 +475,12 @@ const Card = tasty({
     '@function': {
       $$negative: { args: ['$value'], result: '(-1 * $value)' },
     },
-    marginTop: '$$negative(2x)',
+    margin: '$$negative(2x) top',
   },
 });
 ```
 
-Definitions can also come from `configure({ functions })` or the `useFunction` style function, and work across client, SSR/RSC, and zero-runtime modes. `@function` is an experimental CSS feature, so for browsers that do not ship it yet enable `configure({ polyfills: { functions: true } })` to inline every call into plain CSS at parse time.
+Definitions can also come from `configure({ functions })` or the `useFunction` style function, and work across client rendering, SSR/RSC, and build-time extraction. `@function` is an experimental CSS feature, so for browsers that do not ship it yet enable `configure({ polyfills: { functions: true } })` to inline every call into plain CSS at parse time.
 
 See [Style DSL - Functions](docs/dsl.md#functions-function) and [Configuration - Polyfills](docs/configuration.md#polyfills).
 
@@ -456,21 +490,24 @@ When you do not need a full component wrapper, use the style functions directly:
 
 See [React API - Style Functions](docs/react-api.md#style-functions).
 
-### Zero-Runtime Mode
+### Zero-Runtime Delivery
 
-Use `tastyStatic` when you want the same DSL and state model, but with CSS extracted at build time and no styling runtime in the client bundle. It is a strong fit for static sites, landing pages, and other build-time-first setups.
+There are two ways to ship no Tasty styling runtime to the browser:
 
-See [Zero Runtime (tastyStatic)](docs/tasty-static.md) and [Getting Started - Choosing a rendering mode](docs/getting-started.md#choosing-a-rendering-mode).
+- Render `tasty()` components only on the server, retaining the full React component API. Astro's `tastyIntegration({ islands: false })` is the clearest example.
+- Use `tastyStatic()` to extract build-time-known CSS without React.
+
+See [Server-Side Rendering](docs/ssr.md), [Build-Time Extraction (`tastyStatic`)](docs/tasty-static.md), and [Getting Started - Choosing a rendering mode](docs/getting-started.md#choosing-a-rendering-mode).
 
 ### `tasty` vs `tastyStatic`
 
-`tasty()` returns React components that compute CSS during rendering. In server-only contexts, this produces static HTML + CSS with zero client JavaScript — the same end result as `tastyStatic()` but with the full feature set. `tastyStatic()` returns class names and extracts CSS during the build via a Babel plugin, with no React dependency at runtime. Both share the same DSL, tokens, units, state mappings, and recipes. Use `tasty()` as the default for any React-based setup; use `tastyStatic()` when you need build-time extraction without React.
+`tasty()` returns React components that compute CSS during rendering. That render can happen in the browser or only on the server; the server-only path ships no Tasty styling runtime while retaining the full feature set. `tastyStatic()` returns class names and extracts CSS during the build via a Babel plugin, with no React dependency. Both share the same DSL, tokens, units, state mappings, and recipes. Use `tasty()` as the default for React; use `tastyStatic()` when extraction must happen before rendering or the consumer is not React.
 
-See [Zero Runtime (tastyStatic)](docs/tasty-static.md), [React API](docs/react-api.md), and [Comparison - Build-time vs runtime](docs/comparison.md#build-time-vs-runtime).
+See [Build-Time Extraction (`tastyStatic`)](docs/tasty-static.md), [React API](docs/react-api.md), and [Comparison - Where styles are computed](docs/comparison.md#where-styles-are-computed).
 
 ### Server-Side Rendering
 
-`tasty()` components already work on the server without any SSR integration — they are hook-free and render as React Server Components by default. In server-only contexts (Next.js RSC, Astro without islands), they produce zero client JavaScript with the full feature set.
+`tasty()` components already work on the server without any SSR integration — they are hook-free and render as React Server Components by default. In server-only contexts, they ship no Tasty styling runtime while retaining the full feature set. Astro without islands is the explicit zero-client-JavaScript setup; server-only Next.js RSC follows the same architecture, with output depending on the application deployment.
 
 SSR integration (`TastyRegistry`, `tastyIntegration`) adds CSS batching, deduplication across component trees, FOUC prevention, and client cache hydration. Use it when your app also has client-side rendering:
 
@@ -482,19 +519,19 @@ See the [full SSR guide](docs/ssr.md).
 
 ## Entry Points
 
-| Import | Description | Platform |
-|--------|-------------|----------|
-| `@tenphi/tasty` | Runtime style engine (`tasty`, style functions, `configure`) | Browser |
-| `@tenphi/tasty/static` | Zero-runtime static styles (`tastyStatic`) | Browser |
-| `@tenphi/tasty/static/inject` | Runtime helper the Babel plugin rewrites `tastyStatic` imports to in inject mode | Browser |
-| `@tenphi/tasty/core` | Lower-level internals (config, parser, pipeline, injector, style handlers) for tooling and advanced use | Browser / Node |
-| `@tenphi/tasty/babel-plugin` | Babel plugin for zero-runtime CSS extraction | Node |
-| `@tenphi/tasty/zero` | Programmatic extraction API | Node |
-| `@tenphi/tasty/zero/next` | Next.js integration wrapper | Node |
-| `@tenphi/tasty/ssr` | Core SSR API (collector, context, hydration) | Node |
-| `@tenphi/tasty/ssr/next` | Next.js App Router SSR integration | Node |
-| `@tenphi/tasty/ssr/astro` | Astro integration + middleware | Node |
-| `@tenphi/tasty/ssr/astro-client` | Astro client-side cache hydration | Browser |
+| Import                           | Description                                                                                             | Platform       |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------- | -------------- |
+| `@tenphi/tasty`                  | React style engine (`tasty`, style functions, `configure`)                                              | Browser / Node |
+| `@tenphi/tasty/static`           | Build-time extraction authoring API (`tastyStatic`)                                                     | Build time     |
+| `@tenphi/tasty/static/inject`    | Runtime helper the Babel plugin rewrites `tastyStatic` imports to in inject mode                        | Browser        |
+| `@tenphi/tasty/core`             | Lower-level internals (config, parser, pipeline, injector, style handlers) for tooling and advanced use | Browser / Node |
+| `@tenphi/tasty/babel-plugin`     | Babel plugin for build-time CSS extraction                                                              | Node           |
+| `@tenphi/tasty/zero`             | Programmatic extraction API                                                                             | Node           |
+| `@tenphi/tasty/zero/next`        | Next.js integration wrapper                                                                             | Node           |
+| `@tenphi/tasty/ssr`              | Core SSR API (collector, context, hydration)                                                            | Node           |
+| `@tenphi/tasty/ssr/next`         | Next.js App Router SSR integration                                                                      | Node           |
+| `@tenphi/tasty/ssr/astro`        | Astro integration + middleware                                                                          | Node           |
+| `@tenphi/tasty/ssr/astro-client` | Astro client-side cache hydration                                                                       | Browser        |
 
 ## Browser Requirements
 
@@ -510,43 +547,24 @@ Tasty's exclusive selector system relies on modern CSS pseudo-class syntax:
 
 All sizes measured with [size-limit](https://github.com/ai/size-limit) — minified and brotli-compressed, including all dependencies.
 
-| Entry point | Size |
-|-------------|------|
-| `@tenphi/tasty` (runtime + SSR) | 50.19 kB |
-| `@tenphi/tasty/core` (runtime, no SSR) | 47.76 kB |
-| `@tenphi/tasty/static` (zero-runtime) | 16.43 kB |
-| `@tenphi/tasty/zero` (programmatic extraction) | 29.6 kB |
-| `@tenphi/tasty/babel-plugin` (Babel plugin entry) | 43.7 kB |
+| Entry point                                       | Size     |
+| ------------------------------------------------- | -------- |
+| `@tenphi/tasty` (client + server rendering)       | 50.19 kB |
+| `@tenphi/tasty/core` (runtime, no SSR)            | 47.76 kB |
+| `@tenphi/tasty/static` (build-time authoring API) | 16.43 kB |
+| `@tenphi/tasty/zero` (programmatic extraction)    | 29.6 kB  |
+| `@tenphi/tasty/babel-plugin` (Babel plugin entry) | 43.7 kB  |
 
 Run `pnpm size` to reproduce (outputs may shift slightly with releases).
 
 ### Runtime Benchmarks
 
-If you choose the runtime approach, performance is usually a non-issue in practice. The numbers below show single-call throughput for the core pipeline stages, measured with `pnpm bench` on an Apple M1 Max (Node 22).
-
-| Operation | ops/sec | Latency (mean) |
-|-----------|--------:|---------------:|
-| `renderStyles` — 5 flat properties (cold) | ~60,000 | ~17 us |
-| `renderStyles` — state map with media/hover/modifier (cold) | ~18,500 | ~54 us |
-| `renderStyles` — same styles (cached) | ~5,800,000 | ~0.17 us |
-| `parseStateKey` — simple key like `:hover` (cold) | ~790,000 | ~1.3 us |
-| `parseStateKey` — complex OR/AND/NOT key (cold) | ~140,000 | ~7 us |
-| `parseStateKey` — any key (cached) | ~3,400,000–8,300,000 | ~0.1–0.3 us |
-| `parseStyle` — value tokens like `2x 4x` (cold) | ~344,000 | ~2.9 us |
-| `parseStyle` — color tokens (cold) | ~567,000 | ~1.8 us |
-| `parseStyle` — any value (cached) | ~15,250,000 | ~0.07 us |
-
-"Cold" benchmarks use unique inputs to bypass all caches. Cached benchmarks reuse a single input and measure the LRU hot path. Expect roughly ±10% between runs on an otherwise idle machine.
-
-Run `pnpm bench` to reproduce. `pnpm bench:browser` runs the component-render benchmarks separately, in headless Chromium — those are useful for comparing variants against each other (a plain element vs. one with sub-elements), but the browser's 0.1 ms timer resolution makes their absolute values too coarse to quote. The two suites are deliberately separate commands: running them together lets the browser compete with Node for CPU and depresses both.
-
-#### What This Means in Practice
-
-- **Cached path dominates production.** After a component's first render, subsequent renders with stable styles skip the pipeline entirely (React `useMemo` + LRU cache hits at every level). All cached operations are sub-microsecond — effectively free.
-- **Cold path is fast enough.** The heaviest cold operation — a complex state map with media queries, hover, and modifiers — takes ~54 us. Even a page with 100 unique styled components adds only ~5 ms of total style computation on first render, negligible next to React reconciliation and DOM work.
-- **Cache multipliers are 10x–300x.** The parser sees ~30x, state-key parsing ~10x–25x, and the full pipeline ~100x on flat styles and ~300x on complex state maps — the deeper the work, the more the cache saves. This confirms the multi-level LRU architecture (parser, state-key, simplify, condition, pipeline) is delivering real value.
-- **Comparable to lighter systems.** Emotion's `css()` is typically 5–20 us for simple styles; Tasty's cold `renderStyles` at ~17 us for 5 properties is in the same range despite doing significantly more work (state maps, design tokens, sub-elements, chunking).
-- **On slower devices.** The benchmarks above are from an M1 Max (Geekbench 6 SC ~2,400). A mid-range consumer laptop (~1,800 SC) is roughly 1.3x slower; a mid-range phone (~1,200 SC) is roughly 2x slower; a budget phone (~700 SC) is roughly 3–4x slower. Even at 4x, the heaviest cold operation stays under 250 us and 100 unique components under 25 ms — still well within a single frame budget. The cached path remains sub-microsecond on all devices.
+Reproducible benchmarks cover the core style pipeline, the React overhead of an
+empty `tasty({})` wrapper, cold browser generation plus rule injection against
+equivalent CSS already present on the page, and a representative 1,000-element
+React update with shared styles. See
+[Runtime Benchmarks](docs/runtime-benchmarks.md) for the methodology, exact
+results, limitations, and commands.
 
 ### How It Stays Fast
 
@@ -556,7 +574,7 @@ Run `pnpm bench` to reproduce. `pnpm bench:browser` runs the component-render be
 - Style normalization guarantees equivalent style input resolves to the same chunks, improving deduplication hit rates.
 - A style garbage collector removes unused styles/chunks over time.
 - A dedicated style injector minimizes DOM/style-tag overhead.
-- Optional [batched injection](docs/configuration.md#batched-injection) collapses many `insertRule()` calls into one style invalidation per commit, which matters when components measure layout during render.
+- Optional [batched injection](docs/configuration.md#batched-injection) keeps stylesheet writes together before layout reads, allowing the browser to resolve their effects together instead of between individual insertions.
 - This approach is validated in enterprise-scale apps where runtime styling overhead is not noticeable in normal UI flows.
 
 ## Ecosystem
@@ -604,7 +622,7 @@ Syntax highlighting for Tasty styles in TypeScript, TSX, JavaScript, and JSX. Hi
 
 ### [tasty.style](https://tasty.style) ([source](https://github.com/tenphi/tasty.style))
 
-The official Tasty documentation and landing page — itself built entirely with Tasty. A showcase for zero-runtime styling via `tastyStatic`, SSR with Next.js, and OKHSL color theming with Glaze.
+The official Tasty documentation and landing page — itself built entirely with `tasty()`. A showcase for server-rendered Tasty with Next.js and OKHST color theming with Glaze.
 
 ### [Cube Cloud](https://cube.dev/)
 
@@ -622,7 +640,7 @@ Open-source React UI kit built on Tasty + React Aria. 100+ production components
 
 Start from the docs hub if you want the shortest path to the right guide for your role or styling approach.
 
-- **[Docs Hub](docs/README.md)** — audience-based navigation across onboarding, design-system authoring, runtime, zero-runtime, runtime SSR integration, debugging, and internals
+- **[Docs Hub](docs/README.md)** — audience-based navigation across onboarding, design-system authoring, client and server rendering, build-time extraction, debugging, and internals
 
 ### Start here
 
@@ -649,7 +667,7 @@ Start from the docs hub if you want the shortest path to the right guide for you
 
 ### Rendering modes
 
-- **[Zero Runtime (tastyStatic)](docs/tasty-static.md)** — Build-time static styling: Babel plugin setup, Next.js integration, and static style patterns
+- **[Build-Time Extraction (`tastyStatic`)](docs/tasty-static.md)** — Babel plugin setup, Next.js integration, and static style patterns
 - **[Server-Side Rendering](docs/ssr.md)** — SSR setup for Next.js, Astro, and generic frameworks: streaming support, cache hydration, and troubleshooting
 
 ### Internals