@tenphi/tasty 3.10.0 → 3.11.0

package/docs/plugins.md

@@ -37,7 +37,7 @@ configure({ plugins: [spacingPlugin()] });
 
 **Configuration is locked after the first render.** `configure()` warns and does nothing once any style has been generated, so it must run before your first component renders — at module scope in your entry file, or in a design-system module every component imports. `resetConfig()` reopens it, but it exists for tests.
 
-**Repeated `configure()` calls merge** for `tokens` and `globalStyles` (per selector). See [Configuration](configuration.md) for the current per-key semantics.
+**Repeated `configure()` calls merge.** Each call adds to what earlier calls registered, key by key, in every registry (`states`, `units`, `functions`, `handlers`, `propHandlers`, `baseStyleProps`, `tokens`, `replaceTokens`, `recipes`, `keyframes`, `properties`, `fontFaces`, `counterStyles`); `globalStyles` merges per selector. A later value for the same key wins.
 
 ---
 
@@ -108,6 +108,7 @@ configure({
 
 ```ts
 import { configure, mergeStyles } from '@tenphi/tasty';
+import type { Styles } from '@tenphi/tasty';
 
 configure({
   propHandlers: {
@@ -115,7 +116,11 @@ configure({
       const { glaze, ...rest } = props;
       if (!glaze) return rest;
 
-      return { ...rest, styles: mergeStyles(glazeStyles(glaze), rest.styles) };
+      // glazeStyles: see the worked example below
+      return {
+        ...rest,
+        styles: mergeStyles(glazeStyles(glaze), rest.styles as Styles),
+      };
     },
   },
 });
@@ -159,7 +164,7 @@ configure({ baseStyleProps: ['radius', 'shadow'] });
 <Card radius="1r" shadow />
 ```
 
-Names must be real style properties, must start with a lowercase letter, and must not collide with a prop `tasty()` consumes itself (`as`, `styles`, `variant`, `mods`, `tokens`, …); invalid entries are dropped with a development warning.
+Names must start with a lowercase letter and contain only letters and digits, and must not collide with a prop `tasty()` consumes itself (`as`, `styles`, `variant`, `mods`, `tokens`, …); invalid entries are dropped with a development warning. Names are not checked against the style registry, so a misspelled name is still harvested as a style prop.
 
 `configure()` may run _after_ your components are defined — each factory resolves its prop list lazily and refreshes when the registry changes.
 
@@ -169,39 +174,9 @@ Names must be real style properties, must start with a lowercase letter, and mus
 
 ## Typing your extension
 
-Four augmentation points, each matching a runtime registry:
-
-```ts
-// tasty.d.ts
-import type { StylePropValue } from '@tenphi/tasty';
-
-declare module '@tenphi/tasty' {
-  // configure({ handlers }) — a new style property
-  interface StylesInterface {
-    stripe?: StylePropValue<string>;
-  }
-
-  // configure({ propHandlers }) — a new component prop
-  interface TastyCustomProps {
-    glaze: 'soft' | 'strong' | { tone: string; intensity?: number };
-  }
-
-  // configure({ baseStyleProps }) — promoted style names, typed like the style
-  interface TastyBaseStylePropNames {
-    radius: true;
-    shadow: true;
-  }
-
-  // configure({ tokens }) / recipes / presets — autocomplete for names
-  interface TastyNamedColors {
-    'glaze-bg': true;
-  }
-}
-```
+Every extension point has a matching augmentation interface: `StylesInterface` for `handlers`, `TastyCustomProps` for `propHandlers`, `TastyBaseStylePropNames` for `baseStyleProps`, and `TastyNamedColors`, `TastyPresetNames`, and `TastyThemeNames` for the names your `tokens` and `presets` define. [Configuration → TypeScript](configuration.md#typescript) covers all six and the rules that go with them.
 
-`TastyCustomProps` keys become optional props on every component. `TastyBaseStylePropNames` entries are typed exactly like the style they name, so `radius="1r"` accepts the same values as `styles={{ radius: '1r' }}`.
-
-**Also update `tasty.config.ts`.** The ESLint plugin and VS Code extension validate style and token names against it, and neither is derived from the runtime registries:
+**Also update `tasty.config.ts`.** The ESLint plugin and VS Code extension validate style and token names against it, and neither reads the runtime registries or your augmentations:
 
 ```ts
 // tasty.config.ts
@@ -299,6 +274,8 @@ configure({ plugins: [glazePlugin()] });
 
 ```ts
 // tasty.d.ts
+import '@tenphi/tasty';
+
 declare module '@tenphi/tasty' {
   interface TastyCustomProps {
     glaze: import('./glaze-plugin').GlazeConfig | string;
@@ -327,17 +304,20 @@ The object value is unambiguous here precisely because `glaze` is a **prop**. A
 ## Testing a plugin
 
 ```ts
-import { configure, resetConfig, renderStyles } from '@tenphi/tasty';
+import { resetConfig, renderStyles } from '@tenphi/tasty';
+import type { PropHandler, Styles } from '@tenphi/tasty';
 
 describe('glaze plugin', () => {
   beforeEach(() => resetConfig());
   afterEach(() => resetConfig());
 
-  it('expands into a color token declaration', () => {
-    configure({ plugins: [glazePlugin()] });
+  it('turns the glaze prop into styles', () => {
+    const glaze = glazePlugin().propHandlers!.glaze as PropHandler;
+    const out = glaze({ glaze: 'purple' })!;
 
-    const rules = renderStyles({ '#glaze-bg': '#purple.10' }, '.test');
+    expect(out).not.toHaveProperty('glaze');
 
+    const rules = renderStyles(out.styles as Styles, '.test');
     expect(rules[0].declarations).toContain('--glaze-bg-color');
   });
 });
@@ -345,7 +325,7 @@ describe('glaze plugin', () => {
 
 Two things to know:
 
-- **Create components inside each test.** `resetConfig()` does not clear the per-factory class-name cache or prop-list memo, so a module-scope component created in one test carries state into the next.
+- **Create components inside each test.** `resetConfig()` does not clear a component's own class-name cache, which `tasty()` keeps in DOM environments, so a module-scope component can keep returning a class whose CSS the reset removed.
 - **Dev-mode warnings may not fire.** `isDevEnv()` reports `false` for `NODE_ENV=test`. Warnings that check it lazily can be enabled with `vi.stubEnv('NODE_ENV', 'development')`; some older ones capture it at module load and cannot be triggered from a test at all.
 
 ---

package/docs/react-api.md

@@ -2,7 +2,7 @@
 
 Use `tasty()` to turn state-aware style definitions into normal React components, extend existing Tasty components, and expose typed styling APIs to consumers.
 
-All Tasty style functions — `tasty()` components, `useStyles()`, `useGlobalStyles()`, `useRawCSS()`, `useKeyframes()`, `useProperty()`, `useFontFace()`, `useCounterStyle()`, and `useFunction()` — are hook-free and compatible with React Server Components. No `'use client'` directive is needed. For state maps, tokens, units, and extension semantics, see [Style DSL](dsl.md). For global configuration, see [Configuration](configuration.md). For the broader docs map, see the [Docs Hub](README.md).
+Every Tasty style function except `useStyles()` — `tasty()` components, `computeStyles()`, `useGlobalStyles()`, `useRawCSS()`, `useKeyframes()`, `useProperty()`, `useFontFace()`, `useCounterStyle()`, and `useFunction()` — is hook-free and works in React Server Components with no `'use client'` directive. `useStyles()` reads the `TastyRegistry` collector from React context, so it is a real hook; in Server Components and outside React, call `computeStyles()` instead. For state maps, tokens, units, and extension semantics, see [Style DSL](dsl.md). For global configuration, see [Configuration](configuration.md). For the broader docs map, see the [Docs Hub](README.md).
 
 > **Note:** This file was previously named `runtime.md`. All functionality documented here works in both server and client contexts — "runtime" referred to style computation during React rendering, not to client-side JavaScript.
 
@@ -44,6 +44,8 @@ const PrimaryButton = tasty(Button, {
 
 Style maps merge intelligently — see [Style DSL — Extending vs. Replacing State Maps](dsl.md#extending-vs-replacing-state-maps) for extend mode, replace mode, `@inherit`, `null`, and `false` tombstones.
 
+The extension form forwards props; it does not re-run the factory. `styleProps`, `modProps`, `tokenProps`, `variants`, and `elements` passed to `tasty(Component, …)` are ignored even though they type-check, and the base's sub-components are not copied (`tasty(Card, …).Title` is `undefined`). Declare them on the base component, or create the component with `tasty({ … })` directly.
+
 `tasty(Component, ...)` always wraps `Component` and forwards every prop to it, so `Component` must be Tasty-aware (i.e. it accepts `styles`, `mods`, `qa`, etc. and renders them through its own Tasty pipeline). To apply styles to a third-party component or a string DOM tag via `className`, use the options-only form with `as`:
 
 ```jsx
@@ -68,7 +70,7 @@ const Span = tasty({
 </Link>;
 ```
 
-The wrapped component only needs to forward `className` (and ideally `style`/`ref`). Tasty-specific props (`qa`, `qaVal`, `mods`, `tokens`, `styleProps`, `modProps`, `tokenProps`) are consumed by Tasty and never leak to the DOM.
+The wrapped component only needs to forward `className` (and ideally `style`/`ref`). Tasty's own props (`styles`, `mods`, `tokens`, `qa`, `qaVal`, `theme`, `element`, the `is*` props) and the props you declared with `styleProps`, `modProps`, or `tokenProps` are consumed by Tasty; mods, `qa`, `qaVal`, `theme`, and `element` reach the DOM only as `data-*` attributes.
 
 Props forwarded to the `as` component keep their declared types and requiredness. For example, a component with `position: 'top-right' | 'bottom-left'` accepts those values through `tasty({ as: Component })`; CSS positioning can still be set through `styles.position`. A prop explicitly listed in `styleProps` is consumed as a style value instead. The always-available base style props below are also consumed by Tasty, so keep component-specific prop names separate from those reserved names.
 
@@ -112,12 +114,12 @@ A small set of style properties — `display`, `font`, `preset`, `hide`, `whiteS
 
 ## `Element`
 
-`Element` is the unstyled base component exported from the main entry — equivalent to `tasty({})` (a `div` with no default styles). It accepts all Tasty props (`styles`, `styleProps`, `mods`, `tokens`, `as`, `qa`, `theme`, the `is*` props, etc.) and is useful as a generic styled box or as a building block for layout primitives.
+`Element` is the unstyled base component exported from the main entry — equivalent to `tasty({})` (a `div` with no default styles). It accepts the props every Tasty component has (`as`, `styles`, `mods`, `tokens`, `qa`, `theme`, the `is*` props) plus the [always-available style props](#always-available-style-props), and is useful as a generic box or as a building block for layout primitives. Other style names, such as `padding`, are not props on it: create a component with `styleProps` for those, or pass them through `styles`.
 
 ```jsx
 import { Element } from '@tenphi/tasty';
 
-<Element as="section" padding="4x" fill="#surface">
+<Element as="section" display="grid" preset="t2" styles={{ padding: '4x' }}>
   Content
 </Element>;
 ```
@@ -144,6 +146,7 @@ List modifier key names. Types default to `ModValue` (`boolean | string | number
 
 ```jsx
 const Button = tasty({
+  as: 'button',
   modProps: ['isLoading', 'isSelected'] as const,
   styles: {
     fill: { '': '#surface', isLoading: '#surface.5' },
@@ -161,6 +164,7 @@ Map modifier names to type descriptors for precise TypeScript types:
 
 ```tsx
 const Button = tasty({
+  as: 'button',
   modProps: {
     isLoading: Boolean, // isLoading?: boolean
     isSelected: Boolean, // isSelected?: boolean
@@ -297,6 +301,8 @@ const Button = tasty({
 <Button variant="danger">Delete</Button>;
 ```
 
+With `variant` omitted, or set to a key `variants` does not define, the `default` variant applies; without a `default` key only the base `styles` apply. `variant` is typed from the variant keys.
+
 ### Extending Variants with Base State Maps
 
 When base `styles` contain an extend-mode state map (an object **without** a `''` key), it is applied **after** the variant merge. This lets you add or override states across all variants without repeating yourself:
@@ -401,19 +407,19 @@ const { className } = computeStyles({
 });
 ```
 
-On the client, CSS is injected synchronously into the DOM (idempotent via the injector cache). On the server, CSS is collected via the SSR collector if one is available. This is the same function that `tasty()` components use internally.
+On the client, CSS is injected synchronously into the DOM (idempotent via the injector cache). On the server with an SSR collector (from `runWithCollector()` or `TastyRegistry`), the CSS goes to the collector. With neither a collector nor a `document` — a React Server Component — nothing is injected: the CSS comes back as `css`, and you render it in a `style` tag yourself, as `tasty()` components do. This is the same function that `tasty()` components use internally.
 
 ---
 
 ## Style Functions
 
-All style functions below are plain functions (not React hooks) and can be used in any environment: client components, SSR with a `ServerStyleCollector`, and React Server Components. They retain their `use` prefix for backward compatibility, but do not use any React hooks internally.
+All style functions below except `useStyles()` are plain functions, not React hooks, and work in client components, SSR with a `ServerStyleCollector`, and React Server Components. They keep the `use` prefix for backward compatibility.
 
 In server-only contexts, components that use only Tasty style functions ship no Tasty styling runtime. Astro without `client:*` directives produces no client JavaScript; server-only Next.js RSC follows the same Tasty architecture, while final output depends on the application deployment. Tasty never forces the `'use client'` boundary — that decision belongs to your component when it needs React interactivity (state, effects, event handlers).
 
 ### useStyles
 
-Generate a className from a style object. Thin wrapper around `computeStyles()`:
+Generate a className from a style object. A thin wrapper around `computeStyles()` that also picks up the `TastyRegistry` collector through React context. That makes it a hook: call it inside a component, and not in a Server Component — use `computeStyles()` there.
 
 ```tsx
 import { useStyles } from '@tenphi/tasty';
@@ -482,6 +488,8 @@ function GlobalReset() {
 An `id` slot holds one injection per `root`. Without an `id` the CSS is deduped
 by content and permanent — there is nothing to replace it with later.
 
+It also accepts a factory and deps — `useRawCSS(() => css, [deps], { id })` — and skips the factory while the deps for that `id` are unchanged.
+
 ### useKeyframes
 
 Inject `@keyframes` rules and return the generated animation name:
@@ -591,7 +599,11 @@ useFontFace('Brand Sans', [
 Signature:
 
 ```ts
-function useFontFace(family: string, input: FontFaceInput): void;
+function useFontFace(
+  family: string,
+  input: FontFaceInput,
+  options?: { root?: Document | ShadowRoot },
+): void;
 ```
 
 ### useCounterStyle
@@ -684,6 +696,7 @@ See the [Functions section of the DSL reference](dsl.md#functions-function) for
 - **[Style DSL](dsl.md)** — State maps, tokens, units, extending semantics, keyframes, @property
 - **[Methodology](methodology.md)** — Recommended patterns: root + sub-elements, styleProps, tokens, wrapping
 - **[Configuration](configuration.md)** — Tokens, recipes, custom units, style handlers, TypeScript extensions
+- **[Configuration → TypeScript](configuration.md#typescript)** — How props are typed and how to register your names
 - **[Style Properties](styles.md)** — Complete reference for all enhanced style properties
 - **[Build-Time Extraction (`tastyStatic`)](tasty-static.md)** — Static styling with the Babel plugin
 - **[Server-Side Rendering](ssr.md)** — SSR setup for Next.js, Astro, and generic frameworks

package/docs/runtime-benchmarks.md

@@ -197,8 +197,8 @@ The benchmarks above measure mounting and whole-tree updates. A running
 application spends most of its time on neither. It flips mods — hovered,
 pressed, selected, expanded — on elements whose styles never change, one
 element at a time, and it mounts and unmounts small styled subtrees as menus
-and dialogs open. Both paths go through the state-map and ref-counting
-machinery rather than the parser, so a regression in them is invisible to every
+and dialogs open. Both paths go through mod handling and the chunk cache
+rather than the parser, so a regression in them is invisible to every
 other benchmark here.
 
 [`tasty-interaction.bench.tsx`](https://github.com/tenphi/tasty/blob/main/src/tasty-interaction.bench.tsx) pairs each
@@ -371,8 +371,8 @@ blindly. They describe different paths:
   rule.
 - A genuinely new style pays generation and injection once, then becomes
   reusable.
-- A mod flip on an already-styled element pays neither; it is a class-name
-  change.
+- A mod flip on an already-styled element pays neither; it toggles a `data-*`
+  attribute and the class stays the same.
 - Browser style resolution, layout, and paint depend on the actual document and
   need application-level profiling.
 

package/docs/ssr.md

@@ -15,10 +15,10 @@ Zero-runtime delivery is an outcome, not an alias for `tastyStatic()`. When `tas
 | Dependency | Version | Required for                                                                                    |
 | ---------- | ------- | ----------------------------------------------------------------------------------------------- |
 | `react`    | >= 18   | All SSR entry points (matches the current peer dependency of `@tenphi/tasty`)                   |
-| `next`     | >= 13   | Next.js integration (`@tenphi/tasty/ssr/next`) — App Router with `useServerInsertedHTML`        |
+| `next`     | >= 14   | Next.js integration (`@tenphi/tasty/ssr/next`) — App Router with `useServerInsertedHTML`        |
 | Node.js    | >= 20   | Generic / streaming SSR (`@tenphi/tasty/ssr`) — uses `node:async_hooks` for `AsyncLocalStorage` |
 
-The Astro integration (`@tenphi/tasty/ssr/astro`) has no additional dependencies beyond `react`.
+The Astro integration (`@tenphi/tasty/ssr/astro`) needs `@astrojs/react`. Like `@tenphi/tasty/ssr`, it imports `node:async_hooks`, so the server runtime must provide it. `css: { mode: 'extract' }` requires Astro 5 or newer.
 
 ---
 
@@ -137,7 +137,11 @@ import config from './tasty.config';
 
 configure(config);
 
-export default function TastyStyleRegistry({ children }) {
+export default function TastyStyleRegistry({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
   return <TastyRegistry>{children}</TastyRegistry>;
 }
 ```
@@ -147,8 +151,9 @@ The generated file contains eager configuration artifacts: built-in and custom
 CSS `@function` definitions, and `globalStyles`. Route-dependent component
 rules and calls to `useGlobalStyles`, `useRawCSS`, `useKeyframes`,
 `useProperty`, `useFontFace`, `useCounterStyle`, and `useFunction` remain
-route-specific. Configured keyframes also remain lazy and are streamed only
-when a route references them.
+route-specific. Configured keyframes referenced by `globalStyles` are included in the file; all
+other configured keyframes stay lazy and stream only when a route references
+them.
 
 The default output directory is `public/_tasty`. The wrapper adds the generated
 URL to `TastyRegistry`, respects `basePath`, preserves existing `env` and
@@ -175,20 +180,21 @@ meaning; use root-relative, absolute, or data URLs.
 ### How it works
 
 - `TastyRegistry` is a `'use client'` component, but Next.js still server-renders it on initial page load. The `'use client'` boundary is required solely to access `useServerInsertedHTML` — **not** because `tasty()` components need the client.
-- During SSR, `TastyRegistry` creates a `ServerStyleCollector` and registers it via a module-level getter (not `globalThis` — this avoids leaking between Next.js's separate RSC and SSR module graphs). It also wraps children in a React context provider so that hooks inside the SSR tree can discover the collector. All style functions — `tasty()` components, `computeStyles()`, `useStyles()`, `useGlobalStyles()`, `useRawCSS()`, `useKeyframes()`, `useProperty()`, `useFontFace()`, and `useCounterStyle()` — discover the collector through the module-level getter or context provider.
+- During SSR, `TastyRegistry` creates a `ServerStyleCollector` and registers it via a module-level getter (not `globalThis` — this avoids leaking between Next.js's separate RSC and SSR module graphs). It also wraps children in a React context provider so that hooks inside the SSR tree can discover the collector. All style functions — `tasty()` components, `computeStyles()`, `useStyles()`, `useGlobalStyles()`, `useRawCSS()`, `useKeyframes()`, `useProperty()`, `useFontFace()`, `useCounterStyle()`, and `useFunction()` — discover the collector through the module-level getter or context provider.
 - `TastyRegistry` uses `useServerInsertedHTML` to flush collected CSS into the HTML stream as `<style data-tasty-ssr>` tags. This is fully streaming-compatible — styles are injected alongside each Suspense boundary as it resolves.
 - A companion inline `<script>` tag pushes the rendered class names into `window.__TASTY__` for each flush. This streaming-friendly approach accumulates the class list incrementally as Suspense boundaries resolve.
 - When the `@tenphi/tasty/ssr/next` module loads on the client, `hydrateTastyClasses()` runs automatically from `window.__TASTY__` and pre-populates the injector's rules map. During hydration, `computeStyles()` sees the class name is already registered and skips the entire pipeline.
 
 ### Using Tasty in Server Components
 
-All Tasty style functions are hook-free and do not require `'use client'`. They can be used directly in React Server Components:
+Every Tasty style function except `useStyles()` is hook-free and needs no `'use client'`, so it can be used directly in React Server Components:
 
 - `tasty()` components — dynamic `styleProps` like `<Grid flow="column">` work normally
-- `useStyles()`, `useGlobalStyles()`, `useRawCSS()` — inject styles by class or selector
-- `useKeyframes()`, `useProperty()`, `useFontFace()`, `useCounterStyle()` — inject ancillary CSS rules
+- `computeStyles()` — the hook-free equivalent of `useStyles()`, which reads React context and cannot run in a Server Component
+- `useGlobalStyles()`, `useRawCSS()` — inject styles by selector
+- `useKeyframes()`, `useProperty()`, `useFontFace()`, `useCounterStyle()`, `useFunction()` — inject ancillary CSS rules
 
-During SSR, all functions discover the collector via the same global getter registered by `TastyRegistry` — no React context or client boundary needed. In RSC mode without a collector (e.g., Astro zero-setup), CSS is accumulated in a per-request cache and flushed into an inline `<style>` tag by the next `tasty()` component in the tree. Ensure at least one `tasty()` component is present in every RSC render tree — standalone style functions alone cannot emit their CSS without a `tasty()` component to trigger the flush.
+Next.js renders Server Components in a separate module graph that cannot see the collector `TastyRegistry` registers, so their CSS takes the RSC inline path: it is accumulated in a per-request `React.cache` and emitted as an inline `<style>` tag by the next `tasty()` component in the tree. Standalone style functions cannot emit CSS on their own, so make sure a `tasty()` component renders after them in every RSC tree. The RSC path does not emit configured globals (tokens, `@property`, `globalStyles`); those come from `TastyRegistry`'s collector or the `withTastyNext()` shared stylesheet. For the same reason, import the module that calls `configure()` from `app/layout.tsx` as well as from the registry module, so the RSC graph sees the same states, recipes, and units.
 
 ### Options
 
@@ -202,13 +208,13 @@ During SSR, all functions discover the collector via the same global getter regi
 If your app uses Content Security Policy with nonces, configure it before rendering:
 
 ```tsx
-// app/layout.tsx or a server-side init file
+// app/tasty-registry.tsx: the 'use client' module that renders TastyRegistry
 import { configure } from '@tenphi/tasty';
 
 configure({ nonce: 'your-nonce-value' });
 ```
 
-The nonce is automatically applied to all `<style>` and `<script>` tags injected by `TastyRegistry`.
+The nonce is automatically applied to all `<style>` and `<script>` tags injected by `TastyRegistry`. Call it in the module that renders `TastyRegistry`; `app/layout.tsx` is a Server Component and configures a separate module instance.
 
 ---
 
@@ -216,13 +222,13 @@ The nonce is automatically applied to all `<style>` and `<script>` tags injected
 
 Tasty offers several levels of Astro integration. Choose the one that matches your needs:
 
-| Setup                                                            | Config needed | Deduplication             | Hooks work             | Client JS      |
-| ---------------------------------------------------------------- | ------------- | ------------------------- | ---------------------- | -------------- |
-| Zero setup                                                       | None          | Per render tree           | Yes (within each tree) | None           |
-| `tastyIntegration({ islands: false })`                           | One line      | Cross-tree                | Yes                    | None           |
-| `tastyIntegration()`                                             | One line      | Cross-tree                | Yes                    | Auto-hydration |
-| `tastyIntegration({ css: { mode: 'extract' } })`                 | One line      | Cross-tree and cross-page | Yes                    | Auto-hydration |
-| `tastyIntegration({ islands: false, css: { mode: 'extract' } })` | One line      | Cross-tree and cross-page | Yes                    | None           |
+| Setup                                                            | Config needed | Deduplication                       | Hooks work                        | Client JS      |
+| ---------------------------------------------------------------- | ------------- | ----------------------------------- | --------------------------------- | -------------- |
+| Zero setup                                                       | None          | None (each element inlines its CSS) | No (style functions emit nothing) | None           |
+| `tastyIntegration({ islands: false })`                           | One line      | Cross-tree                          | Yes                               | None           |
+| `tastyIntegration()`                                             | One line      | Cross-tree                          | Yes                               | Auto-hydration |
+| `tastyIntegration({ css: { mode: 'extract' } })`                 | One line      | Cross-tree and cross-page           | Yes                               | Auto-hydration |
+| `tastyIntegration({ islands: false, css: { mode: 'extract' } })` | One line      | Cross-tree and cross-page           | Yes                               | None           |
 
 ### Zero setup (static pages)
 
@@ -257,9 +263,9 @@ import Card from '../components/Card.tsx';
 </html>
 ```
 
-**Trade-offs**: Styles are deduplicated within each React render tree, but Astro renders separate component trees independently, so shared CSS (tokens, `@property` rules) may appear more than once. All style functions (`useGlobalStyles`, `useRawCSS`, `useKeyframes`, `useProperty`, `useFontFace`, `useCounterStyle`) work in zero-setup mode — their CSS is accumulated in the RSC cache and flushed by the next `tasty()` component in the tree.
+**Trade-offs**: Astro renders React with the standard `react` build, where `React.cache` does nothing, so there is no per-request style cache. Every `tasty()` element inlines the full CSS for its classes, even when the same component renders twice. Configured globals (`:root` tokens, `@property` defaults, `globalStyles`, `@font-face`) are never emitted, because only the SSR collector emits them, and CSS from `useGlobalStyles`, `useRawCSS`, `useKeyframes`, `useProperty`, `useFontFace`, `useCounterStyle`, and `useFunction` is dropped.
 
-Best for quick prototyping, small static sites, or trying Tasty out in Astro.
+Best for trying Tasty out with unconfigured styles. Use `tastyIntegration()` for anything that relies on `configure()`.
 
 ### Astro Integration (recommended)
 
@@ -296,7 +302,7 @@ import Interactive from '../components/Interactive.tsx';
 
 <html>
   <body>
-    <Card>Static -- styles in <style data-tasty-ssr></Card>
+    <Card>Static -- styles are inlined into the page head</Card>
     <Interactive client:load>Island -- cache hydrated automatically</Interactive>
   </body>
 </html>
@@ -401,6 +407,8 @@ import '@tenphi/tasty/ssr/astro-client';
 export const onRequest = tastyMiddleware({ transferCache: false });
 ```
 
+Build-wide extraction (`css: { mode: 'extract' }`) is available only through `tastyIntegration()`; `tastyMiddleware()` always inlines CSS.
+
 ### How it works
 
 Astro's `@astrojs/react` renderer calls `renderToString()` for each React component without wrapping the tree in a provider. The middleware creates a `ServerStyleCollector` and binds it via `AsyncLocalStorage`. All `computeStyles()` calls within the request discover this collector automatically.
@@ -425,20 +433,16 @@ Call `configure({ nonce: '...' })` before any rendering happens. The middleware
 Any React-based framework can integrate using `runWithCollector`, which binds a `ServerStyleCollector` to the current async context via `AsyncLocalStorage`. All style function calls within the render automatically discover the collector.
 
 ```tsx
+// ── Server ──────────────────────────────────────────────
 import {
-  ServerStyleCollector,
   createServerStyleCollector,
   runWithCollector,
-  hydrateTastyClasses,
 } from '@tenphi/tasty/ssr';
 import { renderToString } from 'react-dom/server';
-import { hydrateRoot } from 'react-dom/client';
-
-// ── Server ──────────────────────────────────────────────
 
 const collector = createServerStyleCollector();
 
-const html = await runWithCollector(collector, () => renderToString(<App />));
+const html = runWithCollector(collector, () => renderToString(<App />));
 
 const css = collector.getCSS();
 const classNames = collector.getRenderedClassNames();
@@ -455,42 +459,56 @@ const fullHtml = `
     </body>
   </html>
 `;
+```
 
+```tsx
 // ── Client ──────────────────────────────────────────────
-
-// Before hydration:
-hydrateTastyClasses(); // reads from window.__TASTY__
+// Browser-safe: runs hydrateTastyClasses() with window.__TASTY__ on import
+import '@tenphi/tasty/ssr/astro-client';
+import { hydrateRoot } from 'react-dom/client';
 
 hydrateRoot(document.getElementById('root'), <App />);
 ```
 
+`@tenphi/tasty/ssr` is server-only: it imports `node:async_hooks`, and in a browser bundle rendering throws `AsyncLocalStorage is not a constructor`. Despite its name, `@tenphi/tasty/ssr/astro-client` works with any framework.
+
 ### Streaming SSR
 
 For streaming with `renderToPipeableStream`, use `flushCSS()` instead of `getCSS()`:
 
 ```tsx
+import { PassThrough } from 'node:stream';
+import { renderToPipeableStream } from 'react-dom/server';
+
 const collector = createServerStyleCollector();
 
-const stream = await runWithCollector(collector, () =>
-  renderToPipeableStream(<App />, {
+// React ends the stream it pipes into, so pipe into a PassThrough and
+// append the remaining styles and the class list after it ends.
+const body = new PassThrough();
+body.pipe(res, { end: false });
+body.on('end', () => {
+  // Styles collected after the shell (Suspense boundaries) + class list
+  const css = collector.flushCSS();
+  if (css) res.write(`<style data-tasty-ssr>${css}</style>`);
+
+  const classNames = collector.getRenderedClassNames();
+  res.end(
+    `</div><script>(window.__TASTY__=window.__TASTY__||[]).push(${JSON.stringify(classNames)})</script></body></html>`,
+  );
+});
+
+runWithCollector(collector, () => {
+  const { pipe } = renderToPipeableStream(<App />, {
     onShellReady() {
-      // Flush styles collected so far
-      const css = collector.flushCSS();
-      res.write(`<style data-tasty-ssr>${css}</style>`);
-      stream.pipe(res);
-    },
-    onAllReady() {
-      // Flush any remaining styles + class list
+      // Styles collected for the shell
       const css = collector.flushCSS();
-      if (css) res.write(`<style data-tasty-ssr>${css}</style>`);
-
-      const classNames = collector.getRenderedClassNames();
       res.write(
-        `<script>(window.__TASTY__=window.__TASTY__||[]).push(${JSON.stringify(classNames)})</script>`,
+        `<!DOCTYPE html><html><head><style data-tasty-ssr>${css}</style></head><body><div id="root">`,
       );
+      pipe(body);
     },
-  }),
-);
+  });
+});
 ```
 
 ---
@@ -499,13 +517,13 @@ const stream = await runWithCollector(collector, () =>
 
 ### Entry points
 
-| Import path                                                                                                                                                                                | Description                                                                                                                                                                                                     |
-| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@tenphi/tasty/ssr`                                                                                                                                                                        | Core SSR API: `ServerStyleCollector`, `createServerStyleCollector`, `runWithCollector`, `hydrateTastyClasses`                                                                                                   |
-| `@tenphi/tasty/ssr/next`                                                                                                                                                                   | Next.js App Router: `TastyRegistry` component                                                                                                                                                                   |
-| `@tenphi/tasty/ssr/next-config`                                                                                                                                                            | Next.js config wrapper: shared, content-hashed global stylesheet                                                                                                                                                |
-| `@tenphi/tasty/ssr/astro`                                                                                                                                                                  | Astro: `tastyIntegration`, `tastyMiddleware`                                                                                                                                                                    |
-| `@tenphi/tasty/ssr/astro-client`                                                                                                                                                           | Astro: client-side cache hydration (auto-injected by integration, or import manually)                                                                                                                           |
+| Import path                                                                                                                                                                                      | Description                                                                                                                                                                                                     |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@tenphi/tasty/ssr`                                                                                                                                                                              | Core SSR API (server-only): `ServerStyleCollector`, `createServerStyleCollector`, `runWithCollector`, `getSSRCollector`, `hydrateTastyClasses`; types `ServerStyleArtifact`, `ServerStyleArtifactKind`          |
+| `@tenphi/tasty/ssr/next`                                                                                                                                                                         | Next.js App Router: `TastyRegistry` component                                                                                                                                                                   |
+| `@tenphi/tasty/ssr/next-config`                                                                                                                                                                  | Next.js config wrapper: shared, content-hashed global stylesheet                                                                                                                                                |
+| `@tenphi/tasty/ssr/astro`                                                                                                                                                                        | Astro: `tastyIntegration`, `tastyMiddleware`                                                                                                                                                                    |
+| `@tenphi/tasty/ssr/astro-client`                                                                                                                                                                 | Astro: client-side cache hydration (auto-injected by integration, or import manually)                                                                                                                           |
 | `@tenphi/tasty/ssr/astro-middleware`<br />`@tenphi/tasty/ssr/astro-middleware-static`<br />`@tenphi/tasty/ssr/astro-middleware-extract`<br />`@tenphi/tasty/ssr/astro-middleware-extract-static` | Astro: the middleware entrypoints `tastyIntegration()` registers via `addMiddleware()`. Exported so Astro can resolve them by specifier; you should not import them. For manual setups use `tastyMiddleware()`. |
 
 ### `ServerStyleCollector`
@@ -522,14 +540,16 @@ Constructor: `new ServerStyleCollector(namePrefix?)`, or use the `createServerSt
 | `allocateKeyframeName(providedName?)`      | Allocate a keyframe name. Returns `providedName` if given, otherwise generates one using `${namePrefix}k${counter}` (e.g. `tk0`, `tk1`, ...).                                                                                                                              |
 | `collectProperty(name, css)`               | Record a `@property` rule. Deduplicated by name.                                                                                                                                                                                                                           |
 | `collectFontFace(key, css)`                | Record a `@font-face` rule. Deduplicated by content hash.                                                                                                                                                                                                                  |
-| `collectCounterStyle(name, css)`           | Record a `@counter-style` rule. Deduplicated by name.                                                                                                                                                                                                                      |
+| `collectCounterStyle(name, css, options?)` | Record a `@counter-style` rule, keyed by name. A different rule under the same name replaces the earlier one (and is re-flushed when streaming); `{ weak: true }`, used for `configure()` definitions, never replaces.                                                     |
+| `collectFunction(name, css, options?)`     | Record a CSS `@function` rule (from `useFunction` or `@function` styles). Same replace/`weak` semantics as `collectCounterStyle`.                                                                                                                                          |
 | `allocateCounterStyleName(providedName?)`  | Allocate a counter-style name. Returns `providedName` if given, otherwise generates one using `${namePrefix}c${counter}` (e.g. `tc0`, `tc1`, ...).                                                                                                                         |
 | `collectGlobalStyles(key, css)`            | Record global styles (from `useGlobalStyles`). Deduplicated by key.                                                                                                                                                                                                        |
 | `collectRawCSS(key, css)`                  | Record raw CSS text (from `useRawCSS`). Deduplicated by key.                                                                                                                                                                                                               |
 | `collectInternals()`                       | Collect eager configured globals: `@property`, `:root` tokens and presets, `@font-face`, `@counter-style`, `@function`, and `globalStyles`. Called automatically on first chunk collection; idempotent.                                                                    |
 | `getCSS()`                                 | Get all collected CSS as a single string. For non-streaming SSR.                                                                                                                                                                                                           |
 | `flushCSS()`                               | Get only CSS collected since the last flush. For streaming SSR.                                                                                                                                                                                                            |
-| `getRenderedClassNames()`                  | Get the list of class names rendered so far. Serialized to `window.__TASTY__` for client hydration via `hydrateTastyClasses()`.                                                                                                                                            |
+| `getRenderedClassNames()`                  | Get the class names allocated since the previous call (the first call returns all so far). Push each batch to `window.__TASTY__` for hydration via `hydrateTastyClasses()`.                                                                                                |
+| `getArtifacts()`                           | Return the collected CSS as ordered, typed artifacts (`property`, `font-face`, `counter-style`, `function`, `raw`, `global`, `chunk`, `keyframes`).                                                                                                                        |
 
 ### `TastyRegistry`
 
@@ -552,9 +572,10 @@ into the Next config. Route-specific CSS continues through `TastyRegistry`.
 
 Astro integration factory. Registers middleware and optionally injects client hydration.
 
-| Option    | Type      | Default | Description                                                                                                      |
-| --------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
-| `islands` | `boolean` | `true`  | When `true`, injects client hydration script and enables `transferCache`. When `false`, no client JS is shipped. |
+| Option    | Type                               | Default              | Description                                                                                                                                                      |
+| --------- | ---------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `islands` | `boolean`                          | `true`               | When `true`, injects client hydration script and enables `transferCache`. When `false`, no client JS is shipped.                                                 |
+| `css`     | `{ mode?: 'inline' \| 'extract' }` | `{ mode: 'inline' }` | `'extract'` writes content-hashed shared and per-page stylesheets for prerendered pages (Astro 5+). See [Build-wide CSS extraction](#build-wide-css-extraction). |
 
 ### `tastyMiddleware(options?)`
 
@@ -570,7 +591,7 @@ Pre-populate the client injector's rules map with class names rendered on the se
 
 ### `runWithCollector(collector, fn)`
 
-Run a function with a `ServerStyleCollector` bound to the current async context via `AsyncLocalStorage`. All style function calls within `fn` (and async continuations) — including `computeStyles()`, `useStyles()`, `useGlobalStyles()`, `useRawCSS()`, `useKeyframes()`, `useProperty()`, `useFontFace()`, and `useCounterStyle()` — will find this collector.
+Run a function with a `ServerStyleCollector` bound to the current async context via `AsyncLocalStorage`. All style function calls within `fn` (and async continuations) — including `computeStyles()`, `useStyles()`, `useGlobalStyles()`, `useRawCSS()`, `useKeyframes()`, `useProperty()`, `useFontFace()`, `useCounterStyle()`, and `useFunction()` — will find this collector. Returns `fn`'s return value, synchronously unless `fn` returns a promise.
 
 ---
 
@@ -582,7 +603,7 @@ The `TastyRegistry` or `tastyIntegration` is missing. Ensure your layout wraps t
 
 ### Hydration mismatch warnings
 
-Class names are deterministic for the same render order. If you see mismatches, ensure `hydrateTastyClasses()` runs before React hydration. For Next.js, this is automatic. For Astro with `tastyIntegration()`, this is also automatic. For manual Astro middleware setups, import `@tenphi/tasty/ssr/astro-client` in your island components. For custom setups, call `hydrateTastyClasses()` before `hydrateRoot()`.
+Class names are content hashes of the resolved styles, so render order does not affect them. Unnamed `useKeyframes()` and `useCounterStyle()` names are counters (`tk0`, `tc0`) on both server and client; pass `name` if the two sides can call them in a different order. If you see mismatches, ensure `hydrateTastyClasses()` runs before React hydration. For Next.js, this is automatic. For Astro with `tastyIntegration()`, this is also automatic. For manual Astro middleware setups, import `@tenphi/tasty/ssr/astro-client` in your island components. For custom setups, import `@tenphi/tasty/ssr/astro-client` before `hydrateRoot()`.
 
 Class names are also derived from the _resolved_ styles, so the server and the client must configure Tasty identically. Anything that changes what a component's styles resolve to will produce a mismatch if it is registered on only one side — `namePrefix`, `recipes`, `handlers`, and the `propHandlers` / `baseStyleProps` extension points described in [Plugins](plugins.md). Call the same `configure()` on both; global CSS is deduplicated automatically, so no `typeof window` guard is needed.
 
@@ -593,9 +614,8 @@ Class names are also derived from the _resolved_ styles, so the server and the c
 **Component CSS**: SSR `<style data-tasty-ssr>` tags remain in the DOM. The client injector creates separate `<style>` elements for any new styles. SSR styles are never modified or removed by the client. If this is a concern for very large apps, you can remove the SSR style tags and hydration scripts manually after hydration:
 
 ```tsx
-import { hydrateTastyClasses } from '@tenphi/tasty/ssr';
+import '@tenphi/tasty/ssr/astro-client'; // runs hydrateTastyClasses()
 
-hydrateTastyClasses();
 hydrateRoot(root, <App />);
 
 // Optional: remove SSR style tags and class-list scripts after hydration
@@ -607,4 +627,4 @@ document.querySelectorAll('script').forEach((el) => {
 
 ### `AsyncLocalStorage` not available
 
-The `@tenphi/tasty/ssr` entry point imports from `node:async_hooks`. This is excluded from client bundles by the build configuration. If you see import errors on the client, ensure your bundler treats `node:async_hooks` as external or use the `@tenphi/tasty/ssr/next` entry point (which does not use ALS).
+`@tenphi/tasty/ssr` imports `node:async_hooks` and is server-only. In a browser bundle the module is stubbed and rendering throws `AsyncLocalStorage is not a constructor`. On the client, import `@tenphi/tasty/ssr/astro-client` (it works with any framework) or use `@tenphi/tasty/ssr/next`, which hydrates automatically.