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

package/docs/design-system.md

@@ -84,25 +84,37 @@ configure({
 
 ### Typography presets
 
-Use `generateTypographyTokens()` to create typography tokens from your own presets, then pass them to `configure({ tokens })`:
+Pass typography presets directly to `configure()` — they are converted to tokens automatically:
 
 ```tsx
-import { configure, generateTypographyTokens } from '@tenphi/tasty';
+import { configure } from '@tenphi/tasty';
 
-const typographyTokens = generateTypographyTokens({
-  h1: { fontSize: '2rem', lineHeight: '1.2', letterSpacing: '-0.02em', fontWeight: 700 },
-  t2: { fontSize: '0.875rem', lineHeight: '1.5', letterSpacing: 'normal', fontWeight: 400 },
+configure({
+  presets: {
+    h1: { fontSize: '2rem', lineHeight: '1.2', letterSpacing: '-0.02em', fontWeight: 700 },
+    t2: { fontSize: '0.875rem', lineHeight: '1.5', letterSpacing: 'normal', fontWeight: 400 },
+  },
 });
+```
+
+Preset values support state maps for responsive or theme-aware typography:
 
+```tsx
 configure({
-  tokens: {
-    ...typographyTokens,
+  presets: {
+    t2: {
+      fontSize: '0.875rem',
+      lineHeight: '1.5',
+      fontWeight: { '': 400, '@dark': 300 },
+    },
   },
 });
 ```
 
 Then use `preset: 'h1'` or `preset: 't2'` in any component's styles.
 
+> You can also call `generateTypographyTokens()` manually and spread the result into `tokens` for more control — `presets` is just a shorthand.
+
 ### Registering brand fonts
 
 Register your design system's custom fonts via `configure({ fontFace })` so every component can reference them:
@@ -334,7 +346,7 @@ Usage:
 
 Sub-elements share the root component's state context by default. A `disabled` modifier on `<Card>` affects `Title`, `Content`, and `Footer` styles automatically — no prop drilling. For the full mental model, see [Methodology — Component architecture](methodology.md#component-architecture-root--sub-elements).
 
-For sub-element syntax details (selector affix `$`, `@own()`, `elements` config), see [Runtime API — Sub-element Styling](runtime.md#sub-element-styling).
+For sub-element syntax details (selector affix `$`, `@own()`, `elements` config), see [React API — Sub-element Styling](react-api.md#sub-element-styling).
 
 ---
 
@@ -404,7 +416,7 @@ ds/
     index.ts              # Recipe definitions (imported by config.ts)
   tokens/
     colors.ts             # Color token definitions
-    typography.ts         # Typography presets via generateTypographyTokens()
+    typography.ts         # Typography presets for configure({ presets })
     spacing.ts            # Spacing token definitions
   index.ts                # Public API: re-exports components + configure
 ```
@@ -418,7 +430,7 @@ The key principle: `config.ts` imports tokens and recipes, calls `configure()`,
 - **[Methodology](methodology.md)** — The recommended patterns for structuring Tasty components
 - **[Getting Started](getting-started.md)** — Installation, first component, tooling setup
 - **[Style DSL](dsl.md)** — State maps, tokens, units, extending semantics, keyframes, @property
-- **[Runtime API](runtime.md)** — `tasty()` factory, component props, variants, sub-elements, hooks
+- **[React API](react-api.md)** — `tasty()` factory, component props, variants, sub-elements, style functions
 - **[Configuration](configuration.md)** — Full `configure()` API: tokens, recipes, custom units, style handlers
 - **[Adoption Guide](adoption.md)** — Who should adopt Tasty, incremental phases, what changes for product engineers
 - **[Style Properties](styles.md)** — Complete reference for all enhanced style properties

package/docs/dsl.md

@@ -2,7 +2,7 @@
 
 This is the Tasty style language reference — the value syntax, state mappings, tokens, units, extending semantics, and special declarations that apply to both runtime `tasty()` and build-time `tastyStatic()`.
 
-For the runtime React API (`tasty()`, hooks, component props), see [Runtime API](runtime.md). For all enhanced style properties, see [Style Properties](styles.md). For global configuration, see [Configuration](configuration.md).
+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).
 
 ---
 
@@ -107,7 +107,7 @@ mods={{ hovered: true, theme: 'danger' }}
 // → data-hovered="" data-theme="danger"
 ```
 
-Modifiers can also be exposed as top-level component props via `modProps` — see [Runtime — Mod Props](runtime.md#mod-props).
+Modifiers can also be exposed as top-level component props via `modProps` — see [Runtime — Mod Props](react-api.md#mod-props).
 
 ---
 
@@ -681,7 +681,7 @@ For a complete reference of all enhanced style properties — syntax, values, mo
 
 ## Learn more
 
-- **[Runtime API](runtime.md)** — `tasty()` factory, component props, variants, sub-elements, hooks
+- **[React API](react-api.md)** — `tasty()` factory, component props, variants, sub-elements, style functions
 - **[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

package/docs/getting-started.md

@@ -1,6 +1,6 @@
 # Getting Started
 
-This guide walks you from zero to a working Tasty component, then through the optional shared configuration and tooling layers. It is the right starting point when you already want to try Tasty in code. If you are still deciding whether Tasty fits your team, start with [Comparison](comparison.md) and [Adoption Guide](adoption.md) first. For a feature overview, see the [README](../README.md). For the full style language reference, see the [Style DSL](dsl.md). For the React API, see the [Runtime API](runtime.md). For the rest of the docs by role or task, see the [Docs Hub](README.md).
+This guide walks you from zero to a working Tasty component, then through the optional shared configuration and tooling layers. It is the right starting point when you already want to try Tasty in code. If you are still deciding whether Tasty fits your team, start with [Comparison](comparison.md) and [Adoption Guide](adoption.md) first. For a feature overview, see the [README](../README.md). For the full style language reference, see the [Style DSL](dsl.md). For the React API, see the [React API](react-api.md). For the rest of the docs by role or task, see the [Docs Hub](README.md).
 
 ---
 
@@ -179,19 +179,19 @@ export default [
 
 ## Choosing a rendering mode
 
-Tasty has two styling approaches. Pick the one that fits your use case, then decide whether your runtime setup also needs server rendering support:
+`tasty()` is the default for all React apps. All `tasty()` components and style functions are hook-free and work as React Server Components without `'use client'`. In server-only contexts, they produce zero client JavaScript with the full feature set.
 
 | Approach | Entry point | Best for | Trade-off |
 |------|-------------|----------|-----------|
-| **Runtime** | `tasty()` from `@tenphi/tasty` | Interactive apps with reusable stateful components, design systems | CSS generated at runtime; full feature set (styleProps, sub-elements, variants) |
-| **Zero-runtime** | `tastyStatic()` from `@tenphi/tasty/static` | Static sites, landing pages, SSG | Zero JS overhead; requires Babel plugin; no dynamic props |
+| **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 |
 
-Both share the same DSL, tokens, units, and state mappings.
+Both `tasty()` and `tastyStatic()` share the same DSL, tokens, units, and state mappings.
 
-- Runtime is the default and requires no extra setup beyond `@tenphi/tasty`.
-- If your framework can execute runtime code during server rendering, add SSR support on top of runtime with `@tenphi/tasty/ssr/next`, `@tenphi/tasty/ssr/astro`, or the core SSR API. This still uses `tasty()`; it just collects CSS on the server and hydrates the cache on the client.
-- Zero-runtime requires the Babel plugin and additional peer dependencies. See [Zero Runtime (tastyStatic)](tasty-static.md).
-- SSR works with existing `tasty()` components — wrap your app with a registry, middleware, or collector. See [Server-Side Rendering](ssr.md).
+- **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).
 
 ---
 
@@ -200,7 +200,7 @@ Both share the same DSL, tokens, units, and state mappings.
 - **[Docs Hub](README.md)** — Pick the next guide by role, styling approach, or task
 - **[Methodology](methodology.md)** — The recommended patterns for structuring Tasty components: sub-elements, styleProps, tokens, extension
 - **[Style DSL](dsl.md)** — State maps, tokens, units, extending semantics, keyframes, @property
-- **[Runtime API](runtime.md)** — `tasty()` factory, component props, variants, sub-elements, hooks
+- **[React API](react-api.md)** — `tasty()` factory, component props, variants, sub-elements, style functions
 - **[Building a Design System](design-system.md)** — Practical guide to building a DS layer with Tasty: tokens, recipes, primitives, compound components
 - **[Adoption Guide](adoption.md)** — Roll out Tasty inside an existing design system or platform team
 - **[Comparison](comparison.md)** — Evaluate Tasty against other styling systems

package/docs/injector.md

@@ -115,11 +115,13 @@ dispose();
 
 ### `useRawCSS(css, options?)` or `useRawCSS(factory, deps, options?)`
 
-React hook for injecting raw CSS. Uses `useInsertionEffect` for proper timing and cleanup.
+Inject raw CSS without parsing. Hook-free — works in client components, SSR, and React Server Components.
 
 Supports two overloads:
-- **Static CSS**: `useRawCSS(cssString, options?)`
-- **Factory function**: `useRawCSS(() => cssString, deps, options?)` - re-evaluates when deps change (like `useMemo`)
+- **Static CSS**: `useRawCSS(cssString, options?)` — content-based deduplication
+- **Factory function**: `useRawCSS(() => cssString, deps, options?)` — factory called on every invocation, dedup handled internally
+
+Use the `id` option for update tracking — when the CSS changes for the same id, the previous injection is replaced:
 
 ```tsx
 import { useRawCSS } from '@tenphi/tasty';
@@ -132,7 +134,7 @@ function GlobalReset() {
   return null;
 }
 
-// Dynamic CSS with factory function (like useMemo)
+// Dynamic CSS with factory function and update tracking
 function ThemeStyles({ theme }: { theme: 'dark' | 'light' }) {
   useRawCSS(() => `
     body {
@@ -140,7 +142,7 @@ function ThemeStyles({ theme }: { theme: 'dark' | 'light' }) {
       background: ${theme === 'dark' ? '#000' : '#fff'};
       color: ${theme === 'dark' ? '#fff' : '#000'};
     }
-  `, [theme]);
+  `, [theme], { id: 'theme-body' });
 
   return null;
 }
@@ -525,7 +527,7 @@ const StyledButton = tasty({
 // 4. dispose() is called when component unmounts
 ```
 
-For most development, you'll use the [Runtime API](./runtime.md) rather than the injector directly. The injector provides the high-performance foundation that makes Tasty's declarative styling possible.
+For most development, you'll use the [React API](./react-api.md) rather than the injector directly. The injector provides the high-performance foundation that makes Tasty's declarative styling possible.
 
 ---
 
@@ -539,4 +541,4 @@ Direct injector usage is recommended for:
 - **Performance-critical scenarios** where you need direct control
 - **Testing utilities** that need to inject or extract CSS
 
-For regular component styling, prefer the [`tasty()` API](./runtime.md) which provides a more developer-friendly interface.
+For regular component styling, prefer the [`tasty()` API](./react-api.md) which provides a more developer-friendly interface.

package/docs/methodology.md

@@ -214,7 +214,7 @@ The array form is simpler but types all values as `ModValue`:
 modProps: ['isLoading', 'isSelected'] as const,
 ```
 
-For the full API reference, see [Runtime — Mod Props](runtime.md#mod-props).
+For the full API reference, see [Runtime — Mod Props](react-api.md#mod-props).
 
 ---
 
@@ -610,7 +610,7 @@ The `elements` prop gives you typed sub-components with automatic `data-element`
 - **[Getting Started](getting-started.md)** — Installation, first component, tooling setup
 - **[Building a Design System](design-system.md)** — Practical guide to building a DS layer with Tasty
 - **[Style DSL](dsl.md)** — State maps, tokens, units, extending semantics, keyframes, @property
-- **[Runtime API](runtime.md)** — `tasty()` factory, component props, variants, sub-elements, hooks
+- **[React API](react-api.md)** — `tasty()` factory, component props, variants, sub-elements, style functions
 - **[Configuration](configuration.md)** — Full `configure()` API: tokens, recipes, custom units, style handlers
 - **[Style Properties](styles.md)** — Complete reference for all enhanced style properties
 - **[Adoption Guide](adoption.md)** — Who should adopt Tasty, incremental phases, what changes for product engineers

package/docs/{runtime.md → react-api.md}

@@ -1,6 +1,8 @@
-# Runtime API
+# React API
 
-The React-specific `tasty()` component factory, component props, and hooks. `tasty()` components are hook-free and compatible with React Server Components — no `'use client'` directive needed. For the shared style language (state maps, tokens, units, extending semantics), see [Style DSL](dsl.md). For global configuration, see [Configuration](configuration.md). For the broader docs map, see the [Docs Hub](README.md).
+The React-specific `tasty()` component factory, component props, and style functions. All Tasty style functions — `tasty()` components, `useStyles()`, `useGlobalStyles()`, `useRawCSS()`, `useKeyframes()`, `useProperty()`, `useFontFace()`, and `useCounterStyle()` — are hook-free and compatible with React Server Components. No `'use client'` directive needed. For the shared style language (state maps, tokens, units, extending 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.
 
 ---
 
@@ -351,11 +353,15 @@ On the client, CSS is injected synchronously into the DOM (idempotent via the in
 
 ---
 
-## Hooks
+## 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.
+
+In server-only contexts (Next.js RSC without `'use client'`, Astro without `client:*` directives, SSG), components that use only Tasty style functions produce zero client JavaScript. 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()` that adds React context-based SSR collector discovery for backward compatibility:
+Generate a className from a style object. Thin wrapper around `computeStyles()`:
 
 ```tsx
 import { useStyles } from '@tenphi/tasty';
@@ -373,7 +379,7 @@ function MyComponent() {
 
 ### useGlobalStyles
 
-Inject global styles for a CSS selector:
+Inject global styles for a CSS selector. Accepts an optional third argument with an `id` for update tracking — when the styles change, the previous injection is disposed and the new one is injected:
 
 ```tsx
 import { useGlobalStyles } from '@tenphi/tasty';
@@ -391,7 +397,7 @@ function ThemeStyles() {
 
 ### useRawCSS
 
-Inject raw CSS strings:
+Inject raw CSS strings. Accepts an optional `id` in the options for update tracking — when the CSS changes for the same id, the previous injection is replaced:
 
 ```tsx
 import { useRawCSS } from '@tenphi/tasty';
@@ -425,7 +431,7 @@ function Spinner() {
 }
 ```
 
-`useKeyframes()` also supports a factory function with dependencies:
+`useKeyframes()` also supports a factory function. The deps array is accepted for backward compatibility but the factory is called on every invocation — deduplication is handled internally by content hash:
 
 ```tsx
 function Pulse({ scale }: { scale: number }) {
@@ -521,43 +527,22 @@ function EmojiList() {
 }
 ```
 
-Factory form with dependencies:
-
-```tsx
-function DynamicList({ marker }: { marker: string }) {
-  const styleName = useCounterStyle(
-    () => ({
-      system: 'cyclic',
-      symbols: `"${marker}"`,
-      suffix: '" "',
-    }),
-    [marker],
-  );
-
-  return <ol style={{ listStyleType: styleName }}>...</ol>;
-}
-```
-
-Signatures:
+Signature:
 
 ```ts
 function useCounterStyle(
   descriptors: CounterStyleDescriptors,
   options?: { name?: string; root?: Document | ShadowRoot },
 ): string;
-
-function useCounterStyle(
-  factory: () => CounterStyleDescriptors,
-  deps: readonly unknown[],
-  options?: { name?: string; root?: Document | ShadowRoot },
-): string;
 ```
 
 ### Troubleshooting
 
 - Styles are not updating: make sure `configure()` runs before first render, and verify the generated class name or global rule with [Debug Utilities](debug.md).
-- SSR output looks wrong: check the [SSR guide](ssr.md) for collector setup. `computeStyles()` discovers the SSR collector via `AsyncLocalStorage` or the global getter registered by `TastyRegistry`.
+- SSR output looks wrong: check the [SSR guide](ssr.md) for collector setup. All style functions discover the SSR collector via `AsyncLocalStorage` or the global getter registered by `TastyRegistry`.
 - Animation/custom property issues: prefer `useKeyframes()` and `useProperty()` over raw CSS when you want Tasty to manage injection and SSR collection for you.
+- For dynamic styles that change over the component lifecycle, use the `id` option in `useGlobalStyles()` and `useRawCSS()` to enable update tracking.
+- RSC inline mode: CSS accumulated by standalone style functions (`useGlobalStyles`, `useRawCSS`, etc.) is flushed into inline `<style>` tags by the next `tasty()` component in the render tree. If your page uses only standalone style functions without any `tasty()` component, the CSS will not be emitted. Ensure at least one `tasty()` component is present in each RSC render tree.
 
 ---
 

package/docs/ssr.md

@@ -18,7 +18,7 @@ The Astro integration (`@tenphi/tasty/ssr/astro`) has no additional dependencies
 
 ## How It Works
 
-`tasty()` components are hook-free and use `computeStyles()` internally — a synchronous, framework-agnostic function. On the server, `computeStyles()` detects a `ServerStyleCollector` (via `AsyncLocalStorage` or an explicit option) and collects CSS into it instead of trying to access the DOM. On the client, CSS is injected synchronously into the DOM during render; the injector's content-based cache makes this idempotent. The collector accumulates all styles, serializes them as `<style>` tags and a cache state script in the HTML. On the client, `hydrateTastyCache()` pre-populates the injector cache so that `computeStyles()` skips the rendering pipeline entirely during hydration.
+`tasty()` components are hook-free and use `computeStyles()` internally — a synchronous, framework-agnostic function. On the server, `computeStyles()` discovers a `ServerStyleCollector` via a registered getter (module-level for Next.js, `globalThis` for Astro/generic frameworks using `AsyncLocalStorage`) and collects CSS into it instead of trying to access the DOM. On the client, CSS is injected synchronously into the DOM during render; the injector's content-based cache makes this idempotent. The collector accumulates all styles, serializes them as `<style>` tags and a cache state script in the HTML. On the client, `hydrateTastyCache()` pre-populates the injector cache so that `computeStyles()` skips the rendering pipeline entirely during hydration.
 
 ```
 Server                         Client
@@ -83,14 +83,20 @@ That's it. All `tasty()` components inside the tree automatically get SSR suppor
 ### 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 global getter. All style computation — whether from `tasty()` components, `computeStyles()`, `useStyles()`, or other hooks like `useGlobalStyles()` — discovers the collector through this single global getter. No React context is involved.
+- 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.
 - `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 `<script>` tag transfers the `cacheKey → className` mapping to the client.
-- When the module loads on the client, `hydrateTastyCache()` runs automatically and pre-populates the injector cache. During hydration, `computeStyles()` hits the cache and skips the entire pipeline.
+- A companion inline `<script>` tag merges the `cacheKey → className` mapping into `window.__TASTY_SSR_CACHE__` for each flush. This streaming-friendly approach accumulates cache entries incrementally as Suspense boundaries resolve.
+- When the `@tenphi/tasty/ssr/next` module loads on the client, `hydrateTastyCache()` runs automatically from `window.__TASTY_SSR_CACHE__` and pre-populates the injector cache. During hydration, `computeStyles()` hits the cache and skips the entire pipeline.
 
-### Using tasty() in Server Components
+### Using Tasty in Server Components
 
-`tasty()` components are hook-free and do not require `'use client'`. They can be used directly in React Server Components. Dynamic `styleProps` like `<Grid flow="column">` work normally in server components. During SSR, `computeStyles()` discovers the collector via the same global getter registered by `TastyRegistry` — no React context or client boundary needed for this path.
+All Tasty style functions are hook-free and do not require `'use client'`. They 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
+
+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.
 
 ### Options
 
@@ -116,18 +122,17 @@ The nonce is automatically applied to all `<style>` and `<script>` tags injected
 
 ## Astro
 
-### 1. Add the middleware
+Tasty offers three levels of Astro integration. Choose the one that matches your needs:
 
-Create or update your Astro middleware:
+| 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 |
 
-```ts
-// src/middleware.ts
-import { tastyMiddleware } from '@tenphi/tasty/ssr/astro';
-
-export const onRequest = tastyMiddleware();
-```
+### Zero setup (static pages)
 
-### 2. Use tasty() components as normal
+`tasty()` components work in Astro with **no configuration**. Each component emits its own inline `<style>` tag during server rendering via the RSC inline path. Just import and use:
 
 ```tsx
 // src/components/Card.tsx
@@ -153,51 +158,118 @@ import Card from '../components/Card.tsx';
 
 <html>
   <body>
-    <Card>Static card — styles collected by middleware</Card>
-    <Card client:load>Island card — styles hydrated on client</Card>
+    <Card>Styled with zero setup</Card>
   </body>
 </html>
 ```
 
-### How it works
+**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.
 
-Astro's `@astrojs/react` renderer calls `renderToString()` for each React component without wrapping the tree in a provider. The middleware uses `AsyncLocalStorage` to make the collector available to all `computeStyles()` calls within the request.
+Best for quick prototyping, small static sites, or trying Tasty out in Astro.
 
-- **Static components** (no `client:*`): Styles are collected during `renderToString` and injected into `</head>`. No JavaScript is shipped for these components.
-- **Islands** (`client:load`, `client:visible`, etc.): Styles are collected during SSR the same way. On the client, importing `@tenphi/tasty/ssr/astro` auto-hydrates the cache from `<script data-tasty-cache>`. The island's `computeStyles()` calls hit the cache during hydration.
+### Astro Integration (recommended)
 
-### Client-side hydration for islands
+For production use, add `tastyIntegration()` to your Astro config. This registers middleware automatically and, by default, injects client-side hydration for islands.
 
-The `@tenphi/tasty/ssr/astro` module auto-hydrates when imported on the client. To ensure the cache is warm before any island renders, import it in a shared entry point or in each island component:
+#### With islands (default)
 
-```tsx
-// src/components/MyIsland.tsx
-import '@tenphi/tasty/ssr/astro'; // auto-hydrates cache on import
-import { tasty } from '@tenphi/tasty';
+```ts
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import react from '@astrojs/react';
+import { tastyIntegration } from '@tenphi/tasty/ssr/astro';
 
-const MyIsland = tasty({
-  styles: { padding: '2x', fill: '#blue' },
+export default defineConfig({
+  integrations: [react(), tastyIntegration()],
 });
+```
+
+This gives you:
+
+- A `ServerStyleCollector` per request via `AsyncLocalStorage`, deduplicating CSS across all React trees on the page
+- A single consolidated `<style data-tasty-ssr>` injected into `</head>`
+- A `<script data-tasty-cache>` tag with the `cacheKey -> className` map for client hydration
+- Auto-injected client hydration script (via `injectScript('before-hydration')`) so islands skip the style pipeline during hydration -- no need to import anything manually in each island component
 
-export default MyIsland;
+All style functions (`useGlobalStyles`, `useRawCSS`, `useKeyframes`, `useProperty`, `useFontFace`, `useCounterStyle`) work on the server.
+
+```astro
+---
+// src/pages/index.astro
+import Card from '../components/Card.tsx';
+import Interactive from '../components/Interactive.tsx';
+---
+
+<html>
+  <body>
+    <Card>Static -- styles in <style data-tasty-ssr></Card>
+    <Interactive client:load>Island -- cache hydrated automatically</Interactive>
+  </body>
+</html>
 ```
 
-### Options
+#### Static only (no client JS)
+
+If your site has no `client:*` islands, skip the hydration script and cache transfer:
+
+```ts
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import react from '@astrojs/react';
+import { tastyIntegration } from '@tenphi/tasty/ssr/astro';
+
+export default defineConfig({
+  integrations: [react(), tastyIntegration({ islands: false })],
+});
+```
+
+This gives the same middleware deduplication and hook support, but ships zero client-side JavaScript. No `<script data-tasty-cache>` is emitted.
+
+### Manual middleware (advanced)
+
+If you need to compose Tasty's middleware with other middleware (e.g., via `sequence()`), use `tastyMiddleware()` directly:
+
+```ts
+// src/middleware.ts
+import { sequence } from 'astro:middleware';
+import { tastyMiddleware } from '@tenphi/tasty/ssr/astro';
+
+export const onRequest = sequence(
+  tastyMiddleware(),
+  myOtherMiddleware,
+);
+```
+
+For island hydration with manual middleware, import the client module in a shared entry point or in each island:
+
+```tsx
+import '@tenphi/tasty/ssr/astro-client';
+```
+
+#### Options
 
 ```ts
-// Skip cache state transfer
+// Skip cache state transfer (static-only, no islands)
 export const onRequest = tastyMiddleware({ transferCache: false });
 ```
 
+### 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.
+
+- **Static components** (no `client:*`): Styles are collected during `renderToString` and injected into `</head>` as a single `<style>` tag. No JavaScript is shipped.
+- **Islands** (`client:load`, `client:visible`, etc.): Styles are collected during SSR the same way. On the client, the hydration script (auto-injected by `tastyIntegration()` or manually via `@tenphi/tasty/ssr/astro-client`) reads the cache state from `<script data-tasty-cache>` and pre-populates the injector. The island's `computeStyles()` calls hit the cache during hydration.
+- The middleware reads the full response body, then injects the collected CSS into `</head>` before sending the final HTML.
+
 ### CSP nonce
 
-Same as Next.js -- call `configure({ nonce: '...' })` before any rendering happens. The middleware reads the nonce and applies it to injected tags.
+Call `configure({ nonce: '...' })` before any rendering happens. The middleware reads the nonce and applies it to injected `<style>` and `<script>` tags.
 
 ---
 
 ## Generic Framework Integration
 
-Any React-based framework can integrate using `runWithCollector`, which binds a `ServerStyleCollector` to the current async context via `AsyncLocalStorage`. All `computeStyles()` and hook calls within the render automatically discover the collector.
+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
 import {
@@ -279,7 +351,8 @@ const stream = await runWithCollector(collector, () =>
 |---|---|
 | `@tenphi/tasty/ssr` | Core SSR API: `ServerStyleCollector`, `runWithCollector`, `hydrateTastyCache` |
 | `@tenphi/tasty/ssr/next` | Next.js App Router: `TastyRegistry` component |
-| `@tenphi/tasty/ssr/astro` | Astro: `tastyMiddleware`, auto-hydration on import |
+| `@tenphi/tasty/ssr/astro` | Astro: `tastyIntegration`, `tastyMiddleware` |
+| `@tenphi/tasty/ssr/astro-client` | Astro: client-side cache hydration (auto-injected by integration, or import manually) |
 
 ### `ServerStyleCollector`
 
@@ -290,9 +363,14 @@ Server-safe style collector. One instance per request.
 | `allocateClassName(cacheKey)` | Allocate a sequential class name (`t0`, `t1`, ...) for a cache key. Returns `{ className, isNewAllocation }`. |
 | `collectChunk(cacheKey, className, rules)` | Record CSS rules for a chunk. Deduplicated by `cacheKey`. |
 | `collectKeyframes(name, css)` | Record a `@keyframes` rule. Deduplicated by name. |
+| `allocateKeyframeName(providedName?)` | Allocate a keyframe name. Returns `providedName` if given, otherwise generates one (`k0`, `k1`, ...). |
 | `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. |
+| `allocateCounterStyleName(providedName?)` | Allocate a counter-style name. Returns `providedName` if given, otherwise generates one (`cs0`, `cs1`, ...). |
+| `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 internal `@property` rules, `:root` token defaults, `@font-face`, and `@counter-style` rules from the global config. 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. |
 | `getCacheState()` | Serialize `{ entries: Record<cacheKey, className>, classCounter }` for client hydration. |
@@ -306,9 +384,17 @@ Next.js App Router component. Props:
 | `children` | `ReactNode` | required | Application tree |
 | `transferCache` | `boolean` | `true` | Embed cache state script for zero-cost hydration |
 
+### `tastyIntegration(options?)`
+
+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. |
+
 ### `tastyMiddleware(options?)`
 
-Astro middleware factory. Options:
+Astro middleware factory. Use for manual middleware composition.
 
 | Option | Type | Default | Description |
 |---|---|---|---|
@@ -320,7 +406,7 @@ Pre-populate the client injector cache. When called without arguments, reads fro
 
 ### `runWithCollector(collector, fn)`
 
-Run a function with a `ServerStyleCollector` bound to the current async context via `AsyncLocalStorage`. All `computeStyles()` and `useStyles()` calls within `fn` (and async continuations) 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()`, and `useCounterStyle()` — will find this collector.
 
 ---
 
@@ -328,11 +414,11 @@ Run a function with a `ServerStyleCollector` bound to the current async context
 
 ### Styles flash on page load (FOUC)
 
-The `TastyRegistry` or `tastyMiddleware` is missing. Ensure your layout wraps the app with `TastyRegistry` (Next.js) or the middleware is registered (Astro).
+The `TastyRegistry` or `tastyIntegration` is missing. Ensure your layout wraps the app with `TastyRegistry` (Next.js) or that `tastyIntegration()` is in your Astro config (or `tastyMiddleware()` is registered manually).
 
 ### Hydration mismatch warnings
 
-Class names are deterministic for the same render order. If you see mismatches, ensure `hydrateTastyCache()` runs before React hydration. For Next.js, this is automatic. For Astro, import `@tenphi/tasty/ssr/astro` in your island components. For custom setups, call `hydrateTastyCache()` before `hydrateRoot()`.
+Class names are deterministic for the same render order. If you see mismatches, ensure `hydrateTastyCache()` 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 `hydrateTastyCache()` before `hydrateRoot()`.
 
 ### Styles duplicated after hydration
 

package/docs/tasty-static.md

@@ -161,11 +161,23 @@ module.exports = {
 | `configFile` | `string` | — | Absolute path to a TS/JS module that default-exports a `TastyZeroConfig` object. JSON-serializable alternative to `config` — required for Turbopack. |
 | `config` | `TastyZeroConfig \| () => TastyZeroConfig` | `{}` | Inline config object or factory function. Takes precedence over `configFile`. |
 | `configDeps` | `string[]` | `[]` | Absolute file paths that affect config (for cache invalidation) |
-| `config.states` | `Record<string, string>` | `{}` | Predefined state aliases |
+| `injectImport` | `boolean` | `true` | Replace `@tenphi/tasty/static` imports with an import of the generated CSS file. Set to `false` to manage CSS imports manually. |
+| `config.states` | `Record<string, string>` | `{}` | Predefined state aliases (e.g. `{ '@mobile': '@media(w < 768px)' }`) |
 | `config.devMode` | `boolean` | `false` | Add source comments to CSS |
+| `config.tokens` | `ConfigTokens` | — | Design tokens injected as CSS custom properties on `:root`. Values are parsed through the Tasty DSL. Supports state maps for responsive/themed tokens. |
+| `config.replaceTokens` | `Record<string, string \| number>` | — | Parse-time token substitution. Keys use `$name` for custom properties and `#name` for color tokens. |
 | `config.recipes` | `Record<string, RecipeStyles>` | `{}` | Predefined style recipes |
+| `config.keyframes` | `Record<string, KeyframesSteps>` | — | Global `@keyframes` definitions available to all `tastyStatic` calls |
 | `config.fontFace` | `Record<string, FontFaceInput>` | — | Global `@font-face` definitions |
 | `config.counterStyle` | `Record<string, CounterStyleDescriptors>` | — | Global `@counter-style` definitions |
+| `config.units` | `Record<string, string \| UnitHandler>` | — | Custom units for the style parser (merged with built-ins). E.g. `{ em: 'em', vw: 'vw' }` |
+| `config.funcs` | `Record<string, Function>` | — | Custom functions for the style parser (merged with existing) |
+| `config.plugins` | `TastyPlugin[]` | — | Plugins that extend tasty with custom functions, units, states, and handlers |
+| `config.handlers` | `Record<string, StyleHandlerDefinition>` | — | Custom style handlers that transform style properties into CSS declarations |
+| `config.presets` | `Record<string, TypographyPreset>` | — | Typography presets — shorthand for `generateTypographyTokens()`. Generated tokens merge under explicit `tokens`. |
+| `config.globalStyles` | `Record<string, Styles>` | — | Global Tasty styles keyed by CSS selector. Supports the full style syntax. |
+| `config.autoPropertyTypes` | `boolean` | `true` | Automatically infer and register CSS `@property` declarations from values |
+| `config.parserCacheSize` | `number` | `1000` | Parser LRU cache size. Larger values improve performance for builds with many unique style values |
 
 ---
 
@@ -516,5 +528,5 @@ const card = tastyStatic({
 
 - [Docs Hub](README.md) — Choose the right guide by task or rendering mode
 - [Style DSL](dsl.md) — State maps, tokens, units, extending semantics (shared by runtime and static)
-- [Runtime API](runtime.md) — Runtime styling: `tasty()` factory, component props, variants, sub-elements, hooks
+- [React API](react-api.md) — Runtime styling: `tasty()` factory, component props, variants, sub-elements, style functions
 - [Configuration](configuration.md) — Global configuration: tokens, recipes, custom units, and style handlers