@tenphi/tasty 1.4.2 → 1.5.1

package/docs/design-system.md

@@ -418,7 +418,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
+- **[Runtime API](runtime.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

@@ -25,7 +25,21 @@ fill: { '': '#white', hovered: '#gray.05', 'theme=danger': '#red' }
 | Pseudo-class | `:hover` | `:hover` |
 | Class selector | `.active` | `.active` |
 | Attribute selector | `[aria-expanded="true"]` | `[aria-expanded="true"]` |
-| Combined | `hovered & .active` | `[data-hovered].active` |
+| Combined (AND) | `hovered & .active` | `[data-hovered].active` |
+| Combined (OR) | `hovered \| focused` | `[data-hovered], [data-focused]` |
+| Negated (NOT) | `!disabled` | `:not([data-disabled])` |
+| Exclusive (XOR) | `hovered ^ focused` | `[data-hovered]:not([data-focused]), :not([data-hovered])[data-focused]` |
+
+Operator precedence (highest to lowest): `!` (NOT) > `^` (XOR) > `|` (OR) > `&` (AND). Use parentheses to override: `hovered & (pressed ^ focused)`.
+
+`^` (XOR) means "exactly one of" — `A ^ B` expands to `(A & !B) | (!A & B)`. This is useful for mutually exclusive states where exactly one should be active:
+
+```jsx
+fill: {
+  '': '#surface',
+  'hovered ^ focused': '#accent',  // active when hovered OR focused, but not both
+}
+```
 
 ### Sub-element
 
@@ -430,7 +444,7 @@ const FadeIn = tasty({
 
 ### `@parent(...)` — Parent Element States
 
-Style based on ancestor element attributes. Uses `:is([selector] *)` / `:not([selector] *)` for symmetric, composable parent checks. Boolean logic (`&`, `|`, `!`) is supported inside `@parent()`.
+Style based on ancestor element attributes. Uses `:is([selector] *)` / `:not([selector] *)` for symmetric, composable parent checks. Boolean logic (`&`, `|`, `!`, `^`) is supported inside `@parent()`.
 
 ```jsx
 const Highlight = tasty({
@@ -508,12 +522,13 @@ const Card = tasty({
 | `!:has(> Icon)` | `:not(:has(> [data-element="Icon"]))` | Negation (use `!`) |
 | `!:is(Panel)` | `:not([data-element="Panel"])` | Negation (use `!:is`) |
 
-Combine with other states using boolean logic:
+Combine with other states using boolean logic (`&`, `|`, `!`, `^`):
 
 ```jsx
-':has(> Icon) & hovered'                // structural + data attribute
-'@parent(hovered) & :has(> Icon)'       // parent check + structural
+':has(> Icon) & hovered'                // AND: structural + data attribute
+'@parent(hovered) & :has(> Icon)'       // AND: parent check + structural
 ':has(> Icon) | :has(> Button)'         // OR: either sub-element present
+':has(> Icon) ^ :has(> Button)'         // XOR: exactly one present
 ```
 
 > **Nesting limit:** The state key parser supports up to 2 levels of nested parentheses inside `:is()`, `:has()`, `:not()`, and `:where()` — e.g. `:has(Input:not(:disabled))` works, but 3+ levels like `:has(:is(:not(:hover)))` will not be tokenized correctly. This covers virtually all practical use cases.
@@ -666,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
+- **[Runtime API](runtime.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

@@ -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
+- **[Runtime API](runtime.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;
 }
@@ -210,11 +212,8 @@ configure({
   forceTextInjection: false,         // Force textContent insertion (auto-detected for tests)
   nonce: 'csp-nonce',                // CSP nonce for security
   gc: {                              // Garbage collection for unused styles
-    auto: true,                      // Enable automatic background sweep
-    baseMaxAge: 60000,               // Base TTL (ms) for single-use styles
-    cooldown: 30000,                 // Minimum time between GC runs
-    autoInterval: 300000,            // Background sweep interval (ms)
-    cacheCapacity: 5000,             // Hard cap on cached styles (optional)
+    touchInterval: 1000,             // Touch events between GC cycles (default: 1000)
+    capacity: 1000,                  // Max unused styles to retain (default: 1000)
   },
   states: {                          // Global predefined states for advanced state mapping
     '@mobile': '@media(w < 768px)',
@@ -231,9 +230,8 @@ configure({
 - Most options have sensible defaults and auto-detection
 - `configure()` is optional - the injector works with defaults
 - **Configuration is locked after styles are generated** - calling `configure()` after first render will emit a warning and be ignored
-- `gc.baseMaxAge`: Base TTL for a style rendered only once. Popular styles get longer TTLs via logarithmic scaling (`baseMaxAge * log2(hitCount + 1)`).
-- `gc.auto`: When true, runs a periodic background sweep at `gc.autoInterval` intervals using `requestIdleCallback`.
-- `gc.cooldown`: Minimum time between GC runs to avoid thrashing.
+- `gc.touchInterval`: Number of touch events between GC cycles. Each style render counts as a touch. When the counter reaches this value, GC is scheduled via `requestIdleCallback`.
+- `gc.capacity`: Maximum number of unused styles (refCount = 0, not in DOM) to retain. When exceeded, the oldest are evicted first. Actively referenced styles don't count against this limit.
 
 ---
 
@@ -298,28 +296,31 @@ comp3.dispose(); // refCount: 1 → 0, eligible for bulk cleanup
 ### Garbage Collection
 
 ```typescript
-import { configure, gc, maybeGC } from '@tenphi/tasty';
+import { configure, gc } from '@tenphi/tasty';
 
 // Keyframes: Disposed immediately when refCount = 0 (safer for global scope)
-// CSS rules: Tracked by popularity and cleaned up via gc()
+// CSS rules: Tracked by touch count and cleaned up via gc()
 
 configure({
   gc: {
-    auto: true,          // Enable background sweep
-    baseMaxAge: 60000,   // 1-minute base TTL
-    cooldown: 30000,     // 30s between runs
+    touchInterval: 1000,   // Schedule GC every 1000 touches
+    capacity: 1000,        // Max unused styles to retain
   },
 });
 
 // Manual GC (synchronous, returns number of swept styles):
 gc();
 
-// Event-driven GC with cooldown (e.g. on route change):
-maybeGC();
+// Force-remove ALL unused styles (e.g. on route change or test teardown):
+gc({ force: true });
+
+// GC is also triggered automatically by touch count during rendering.
+// Every `touchInterval` touches, GC is scheduled via requestIdleCallback.
 
 // Benefits:
-// - Popularity-aware: frequently used styles survive longer
+// - Activity-proportional: busy apps trigger GC more often
 // - DOM-safe: styles currently in the DOM are never evicted
+// - Oldest-first: least recently used styles are evicted first
 // - Keyframes: Immediate cleanup prevents global namespace pollution
 // - Unused styles can be instantly reactivated (just increment refCount)
 ```
@@ -481,8 +482,8 @@ import { configure } from '@tenphi/tasty';
 
 configure({
   gc: {
-    auto: true,            // Enable background sweep for long-lived pages
-    baseMaxAge: 60000,     // Default base TTL (adjust based on app size)
+    touchInterval: 1000,   // Schedule GC every 1000 style touches
+    capacity: 1000,        // Max unused styles to retain
   },
 });
 ```
@@ -495,7 +496,7 @@ configure({
 // 1. Hash-based deduplication - same CSS = same className
 // 2. Reference counting - styles stay alive while in use (refCount > 0)
 // 3. Immediate keyframes cleanup - disposed instantly when refCount = 0
-// 4. Popularity-aware GC - unused CSS rules are scored by hitCount and age
+// 4. Touch-count GC - unused CSS rules are evicted oldest-first when over capacity
 // 5. DOM safety guard - styles visible in the DOM are never evicted
 
 // Manual cleanup is rarely needed but available:

package/docs/methodology.md

@@ -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
+- **[Runtime API](runtime.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

@@ -1,6 +1,6 @@
 # Runtime 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).
 
 ---
 
@@ -351,11 +351,13 @@ 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.
 
 ### 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 +375,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 +393,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 +427,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 +523,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

@@ -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 global getter. All style functions — `tasty()` components, `computeStyles()`, `useStyles()`, `useGlobalStyles()`, `useRawCSS()`, `useKeyframes()`, `useProperty()`, `useFontFace()`, and `useCounterStyle()` — discover the collector through this single global getter. No React context is involved.
 - `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.
 
-### 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 | No | 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 uses streaming-compatible `TransformStream` processing to inject CSS into the response without buffering the entire 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`
 
@@ -306,9 +379,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 +401,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 +409,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

@@ -516,5 +516,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
+- [Runtime API](runtime.md) — Runtime styling: `tasty()` factory, component props, variants, sub-elements, style functions
 - [Configuration](configuration.md) — Global configuration: tokens, recipes, custom units, and style handlers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenphi/tasty",
-  "version": "1.4.2",
+  "version": "1.5.1",
   "description": "A design-system-integrated styling system and DSL for concise, state-aware UI styling",
   "type": "module",
   "main": "./dist/index.js",
@@ -57,6 +57,11 @@
       "import": "./dist/ssr/astro.js",
       "default": "./dist/ssr/astro.js"
     },
+    "./ssr/astro-client": {
+      "types": "./dist/ssr/astro-client.d.ts",
+      "import": "./dist/ssr/astro-client.js",
+      "default": "./dist/ssr/astro-client.js"
+    },
     "./tasty.config": "./tasty.config.ts"
   },
   "files": [
@@ -67,7 +72,8 @@
   "sideEffects": [
     "./dist/ssr/index.js",
     "./dist/ssr/next.js",
-    "./dist/ssr/astro.js"
+    "./dist/ssr/astro.js",
+    "./dist/ssr/astro-client.js"
   ],
   "engines": {
     "node": ">=20"