@cube-dev/ui-kit 0.125.1 → 0.127.0

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

@@ -1,6 +1,8 @@
-# Runtime API
+# React API
 
-The React-specific `tasty()` component factory, component props, and hooks. 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.
 
 ---
 
@@ -154,6 +156,75 @@ For architecture guidance on when to use modifiers vs `styleProps`, see [Methodo
 
 ---
 
+## Token Props
+
+Use `tokenProps` to expose token keys as direct component props instead of requiring the `tokens` object:
+
+```jsx
+// Before: tokens object
+<ProgressBar tokens={{ $progress: '75%', '#accent': '#purple' }} />
+
+// After: token props
+<ProgressBar progress="75%" accentColor="#purple" />
+```
+
+### Array form
+
+List prop names. Names ending in `Color` map to `#` color tokens; everything else maps to `$` custom property tokens:
+
+```jsx
+const ProgressBar = tasty({
+  tokenProps: ['progress', 'accentColor'] as const,
+  styles: { width: '$progress', fill: '#accent' },
+});
+
+<ProgressBar progress="75%" accentColor="#purple" />
+// 'progress'    → $progress    → --progress
+// 'accentColor' → #accent      → --accent-color + --accent-color-oklch
+```
+
+### Object form
+
+Map prop names to explicit `$`/`#`-prefixed token keys:
+
+```tsx
+const Card = tasty({
+  tokenProps: {
+    size: '$card-size',
+    color: '#card-accent',
+  },
+  styles: { padding: '$card-size', fill: '#card-accent' },
+});
+
+<Card size="4x" color="#purple" />
+```
+
+### Merge with `tokens`
+
+Token props and the `tokens` prop can be used together. Token props take precedence over `tokens`, which takes precedence over default `tokens` in `tasty({...})`:
+
+```jsx
+const Bar = tasty({
+  tokenProps: ['progress'] as const,
+  tokens: { $progress: '0%' },  // default
+});
+
+<Bar tokens={{ $progress: '50%' }} progress="90%" />
+// progress="90%" wins (from token prop)
+```
+
+### When to use `tokenProps` vs `tokens`
+
+| Use case | Recommendation |
+|---|---|
+| Component has a fixed set of known token keys | `tokenProps` — cleaner API, better TypeScript autocomplete |
+| Component needs arbitrary/dynamic token values | `tokens` — open-ended `Record<string, TokenValue>` |
+| Both fixed and dynamic | Combine: `tokenProps` for known keys, `tokens` for ad-hoc |
+
+For architecture guidance, see [Methodology — tokenProps](methodology.md#tokenprops).
+
+---
+
 ## Variants
 
 Define named style variations. Only CSS for variants actually used at runtime is injected:
@@ -264,11 +335,33 @@ For the mental model behind sub-elements — how they share root state context a
 
 ---
 
-## Hooks
+## computeStyles
+
+Hook-free, synchronous style computation. Can be used anywhere — including React Server Components, plain functions, and non-React code:
+
+```tsx
+import { computeStyles } from '@tenphi/tasty';
+
+const { className } = computeStyles({
+  padding: '2x',
+  fill: '#surface',
+  radius: '1r',
+});
+```
+
+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.
+
+---
+
+## 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:
+Generate a className from a style object. Thin wrapper around `computeStyles()`:
 
 ```tsx
 import { useStyles } from '@tenphi/tasty';
@@ -286,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';
@@ -304,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';
@@ -338,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 }) {
@@ -378,11 +471,78 @@ function Spinner() {
 - `#name` defines `--name-color` and auto-infers `<color>`
 - `--name` is also supported for existing CSS variables
 
+### useFontFace
+
+Inject `@font-face` rules for custom fonts. Permanent — no cleanup on unmount. Deduplicates by content.
+
+```tsx
+import { useFontFace } from '@tenphi/tasty';
+
+function App() {
+  useFontFace('Brand Sans', {
+    src: 'url("/fonts/brand-sans.woff2") format("woff2")',
+    fontWeight: '400 700',
+    fontDisplay: 'swap',
+  });
+
+  return <div style={{ fontFamily: '"Brand Sans", sans-serif' }}>Hello</div>;
+}
+```
+
+For multiple weights/styles, pass an array:
+
+```tsx
+useFontFace('Brand Sans', [
+  { src: 'url("/fonts/brand-regular.woff2") format("woff2")', fontWeight: 400, fontDisplay: 'swap' },
+  { src: 'url("/fonts/brand-bold.woff2") format("woff2")', fontWeight: 700, fontDisplay: 'swap' },
+]);
+```
+
+Signature:
+
+```ts
+function useFontFace(family: string, input: FontFaceInput): void;
+```
+
+### useCounterStyle
+
+Inject a `@counter-style` rule and get back the counter style name. Permanent — no cleanup on unmount. Deduplicates by name.
+
+```tsx
+import { useCounterStyle } from '@tenphi/tasty';
+
+function EmojiList() {
+  const styleName = useCounterStyle({
+    system: 'cyclic',
+    symbols: '"👍"',
+    suffix: '" "',
+  }, { name: 'thumbs' });
+
+  return (
+    <ol style={{ listStyleType: styleName }}>
+      <li>First</li>
+      <li>Second</li>
+    </ol>
+  );
+}
+```
+
+Signature:
+
+```ts
+function useCounterStyle(
+  descriptors: CounterStyleDescriptors,
+  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) because the hooks integrate with SSR collectors differently than the client-only runtime path.
+- 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/tasty/ssr.md

@@ -18,16 +18,16 @@ The Astro integration (`@tenphi/tasty/ssr/astro`) has no additional dependencies
 
 ## How It Works
 
-When the environment can execute runtime React code during server rendering, the same `tasty()` and `useStyles()` calls can run there too. In Next.js, generic React SSR, and Astro islands, Tasty simply changes where that runtime-generated CSS goes: `useStyles()` detects a `ServerStyleCollector` and collects CSS into it instead of trying to access the DOM. 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 `useStyles()` 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
 ──────                         ──────
 tasty() renders                hydrateTastyCache() pre-populates cache
-  └─ useStyles()                 └─ cacheKey → className map ready
+  └─ computeStyles()              └─ cacheKey → className map ready
        └─ collector.collect()
                                  tasty() renders
-After render:                    └─ useStyles()
+After render:                    └─ computeStyles()
   <style data-tasty-ssr>              └─ cache hit → skip pipeline
   <script data-tasty-cache>           └─ no CSS re-injection
 ```
@@ -82,15 +82,21 @@ 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.
-- During SSR, `useStyles()` finds the collector via React context and pushes CSS rules to it.
-- `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, `useStyles()` hits the cache and skips the entire pipeline.
+- `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.
+- `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 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 use React hooks internally, so they require `'use client'`. However, this does **not** prevent them from being used in Server Component pages. In Next.js, `'use client'` components are still server-rendered on initial load. Dynamic `styleProps` like `<Grid flow="column">` work normally when a `tasty()` component is imported into a Server Component page.
+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
-
-Create or update your Astro middleware:
+Tasty offers three levels of Astro integration. Choose the one that matches your needs:
 
-```ts
-// src/middleware.ts
-import { tastyMiddleware } from '@tenphi/tasty/ssr/astro';
+| 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 |
 
-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,56 +158,123 @@ 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 `useStyles()` 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 `useStyles()` 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
+
+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';
+---
 
-export default MyIsland;
+<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 the core SSR API:
+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 {
   ServerStyleCollector,
-  TastySSRContext,
+  runWithCollector,
   hydrateTastyCache,
 } from '@tenphi/tasty/ssr';
 import { renderToString } from 'react-dom/server';
@@ -212,10 +284,8 @@ import { hydrateRoot } from 'react-dom/client';
 
 const collector = new ServerStyleCollector();
 
-const html = renderToString(
-  <TastySSRContext.Provider value={collector}>
-    <App />
-  </TastySSRContext.Provider>
+const html = await runWithCollector(collector, () =>
+  renderToString(<App />)
 );
 
 const css = collector.getCSS();
@@ -251,11 +321,8 @@ For streaming with `renderToPipeableStream`, use `flushCSS()` instead of `getCSS
 ```tsx
 const collector = new ServerStyleCollector();
 
-const stream = renderToPipeableStream(
-  <TastySSRContext.Provider value={collector}>
-    <App />
-  </TastySSRContext.Provider>,
-  {
+const stream = await runWithCollector(collector, () =>
+  renderToPipeableStream(<App />, {
     onShellReady() {
       // Flush styles collected so far
       const css = collector.flushCSS();
@@ -270,29 +337,8 @@ const stream = renderToPipeableStream(
       const state = collector.getCacheState();
       res.write(`<script data-tasty-cache type="application/json">${JSON.stringify(state)}</script>`);
     },
-  }
-);
-```
-
-### AsyncLocalStorage (no React context)
-
-If your framework doesn't support wrapping the React tree with a provider, use `runWithCollector`:
-
-```tsx
-import {
-  ServerStyleCollector,
-  runWithCollector,
-  hydrateTastyCache,
-} from '@tenphi/tasty/ssr';
-
-const collector = new ServerStyleCollector();
-
-const html = await runWithCollector(collector, () =>
-  renderToString(<App />)
+  })
 );
-
-const css = collector.getCSS();
-// ... inject into HTML as above
 ```
 
 ---
@@ -303,9 +349,10 @@ const css = collector.getCSS();
 
 | Import path | Description |
 |---|---|
-| `@tenphi/tasty/ssr` | Core SSR API: `ServerStyleCollector`, `TastySSRContext`, `runWithCollector`, `hydrateTastyCache` |
+| `@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`
 
@@ -316,15 +363,18 @@ 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. |
 
-### `TastySSRContext`
-
-React context (`createContext<ServerStyleCollector | null>(null)`). Used by `useStyles()` to find the collector during SSR.
-
 ### `TastyRegistry`
 
 Next.js App Router component. Props:
@@ -334,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 |
 |---|---|---|---|
@@ -348,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 `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.
 
 ---
 
@@ -356,15 +414,17 @@ 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
 
-This is expected and harmless. 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, call `cleanupSSRStyles()` after hydration:
+**Global CSS** (`:root` tokens, `@property`, `globalStyles`, `@font-face`, `@counter-style`) configured via `configure()` is automatically deduplicated. When Tasty detects `<style data-tasty-ssr>` in the document, it skips client-side injection of globals that were already rendered by the SSR collector. This means `configure()` can be called with the full config on both server and client — no `typeof window === 'undefined'` guard is needed.
+
+**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, call `cleanupSSRStyles()` after hydration:
 
 ```tsx
 import { hydrateTastyCache } from '@tenphi/tasty/ssr';