@cube-dev/ui-kit 0.154.1 → 0.155.0

package/docs/tasty/plugins.md

@@ -0,0 +1,349 @@
+# Plugins & Extension Points
+
+How to extend Tasty: new value syntax, new units, new states, new style properties, new component props, and how to package any of it as a plugin.
+
+- [What a plugin is](#what-a-plugin-is)
+- [Choosing an extension point](#choosing-an-extension-point)
+- [Custom style handlers](#custom-style-handlers)
+- [Props middleware](#props-middleware)
+- [Base style props](#base-style-props)
+- [Typing your extension](#typing-your-extension)
+- [Worked example: a `glaze` plugin](#worked-example-a-glaze-plugin)
+- [Rendering modes and caveats](#rendering-modes-and-caveats)
+- [Testing a plugin](#testing-a-plugin)
+
+---
+
+## What a plugin is
+
+A plugin is a plain object with a `name` and any subset of the `configure()` options it is allowed to supply. There is no lifecycle and no init hook — a plugin is just pre-packaged configuration.
+
+```ts
+import { configure } from '@tenphi/tasty';
+import type { TastyPluginFactory } from '@tenphi/tasty';
+
+const spacingPlugin: TastyPluginFactory = () => ({
+  name: 'spacing',
+  units: { gu: (n) => `calc(${n} * var(--grid-unit))` },
+  tokens: { '$grid-unit': '4px' },
+});
+
+configure({ plugins: [spacingPlugin()] });
+```
+
+`TastyPluginFactory<TOptions>` types a factory that takes options; with no type argument it types a zero-argument factory.
+
+**Ordering.** Plugins are applied in array order and merged key by key, so a later plugin overrides an earlier one for the same key. Options passed directly to `configure()` are applied last and win over every plugin.
+
+**Configuration is locked after the first render.** `configure()` warns and does nothing once any style has been generated, so it must run before your first component renders — at module scope in your entry file, or in a design-system module every component imports. `resetConfig()` reopens it, but it exists for tests.
+
+**Repeated `configure()` calls merge** for `tokens` and `globalStyles` (per selector). See [Configuration](configuration.md) for the current per-key semantics.
+
+---
+
+## Choosing an extension point
+
+| You want to add | Use | Runs | Zero-runtime |
+|---|---|---|---|
+| New value syntax — `okhsl(…)`, `double(2x)` | `functions` (bare key) | parse time, per value | ✅ |
+| A reusable CSS `@function` | `functions` (`$$name` key) | injected once, globally | ✅ |
+| A new unit — `2gu` | `units` | parse time, per value | ✅ |
+| A new state alias — `@mobile` | `states` | state-key parse | ✅ |
+| A style property → **CSS declarations** | `handlers` | pipeline, per state snapshot | ✅ |
+| A style property on every component | `baseStyleProps` | prop harvest | ✅ (styles only) |
+| A **component prop** → anything | `propHandlers` | render, per component | ❌ (no props to run on) |
+| A named bundle of styles | `recipes` | before chunking | ✅ |
+| Typography scale tokens | `presets` | inject time | ✅ |
+| `:root` variables | `tokens`, `replaceTokens` | inject time | ✅ |
+| Global selector styles | `globalStyles` | inject time | ✅ |
+
+Two distinctions do most of the work:
+
+- **`handlers` vs `propHandlers`.** A handler turns a *style property* into CSS declarations and knows nothing about components. A prop handler turns a *component prop* into other props — including `styles`, which then flow through the normal handlers. Reach for `propHandlers` when the input isn't a style value (an options object, a domain concept) or when it should affect more than styles.
+- **`recipes` vs `propHandlers`.** A recipe is a static named bundle. A prop handler computes its styles from a value.
+
+---
+
+## Custom style handlers
+
+A handler receives a map of the style properties it declared and returns CSS declarations. See [Configuration → Custom Style Handlers](configuration.md#custom-style-handlers) for the definition forms, return shape, the shared-handler groups you must be careful of, and chunk membership. The essentials:
+
+- Values arrive **state-resolved but unparsed** — the raw authored DSL string (`'2x'`, `'#purple.5'`, `true`, `4`). Call the exported `parseStyle()` / `parseColor()` yourself.
+- Return a `CSSMap` with **kebab-case** keys, an array of them, or nothing. `$` is a selector suffix, not a property.
+- Handlers must be pure and synchronous. They are called once per state combination and the results are cached.
+- Use `defineHandler(deps, fn)` for multi-dependency handlers so the dependency types are inferred.
+
+```ts
+import { configure, defineHandler, parseStyle } from '@tenphi/tasty';
+
+configure({
+  handlers: {
+    // Every declaration set the handler returns can target its own selector.
+    stripe: defineHandler(['stripe'], ({ stripe }) => {
+      if (!stripe) return;
+
+      const { values } = parseStyle(String(stripe)).groups[0];
+
+      return [
+        { position: 'relative' },
+        {
+          $: '&::before',
+          content: '""',
+          position: 'absolute',
+          inset: '0 auto 0 0',
+          width: values[0],
+          background: 'var(--purple-color)',
+        },
+      ];
+    }),
+  },
+});
+```
+
+---
+
+## Props middleware
+
+`propHandlers` are middleware over a component's props: props in, props out. They run at the very top of every tasty component's render, before any prop is destructured, so a handler can read and rewrite `styles`, `mods`, `tokens`, `variant`, `as`, `element`, and `qa`, and can strip its own props so they never reach the DOM.
+
+```ts
+import { configure, mergeStyles } from '@tenphi/tasty';
+
+configure({
+  propHandlers: {
+    glaze: (props) => {
+      const { glaze, ...rest } = props;
+      if (!glaze) return rest;
+
+      return { ...rest, styles: mergeStyles(glazeStyles(glaze), rest.styles) };
+    },
+  },
+});
+```
+
+**The key is the trigger.** By default a handler runs only when a prop matching its key is present, so an absent prop costs one property check rather than a call. Override that with a tuple:
+
+| Definition | Runs when |
+|---|---|
+| `fn` | a prop named after the key is present |
+| `['glaze', fn]` | `glaze` is present |
+| `[['glaze', 'tint'], fn]` | either is present |
+| `['*', fn]` | always |
+
+**Chaining.** Handlers run in registration order — plugins first, then direct `configure()` — and each receives the previous one's output. Registering the same key twice replaces the handler in place, keeping its position.
+
+**Returning nothing means unchanged**, with a development-mode warning, because that is almost always a forgotten `return props`. A non-object return is ignored with a warning.
+
+### Rules
+
+- **Be pure. Never mutate the input.** Style values are cached by object identity, so mutating a value object in place yields a stale class name *and* stale CSS. Return fresh objects.
+- **Memoize the styles you build, per input value.** A reference-stable (ideally frozen) styles object lets the cache key reuse its serialization instead of recomputing it on every render. This is the single highest-leverage thing you can do for performance.
+- **Precedence is fixed** and not adjustable from a handler. Styles are merged as `factory defaults → styles → harvested style props`, and injected styles occupy the `styles` slot: they beat a component's own default styles and lose to a style prop passed at the call site. This matches how `recipe` already behaves.
+- **Prefer returning `styles` over bare style props.** Returning `{ fill: '#red' }` only works if `fill` is harvestable on *that* component (in its `styleProps`, or promoted via `baseStyleProps`); otherwise it leaks to the DOM.
+
+### What it cannot do
+
+- **`ref`** — `forwardRef` separates it from props, so it is out of reach.
+- **Sub-elements** (`Card.Title`) — they have no `styles` prop and no style-prop harvest, so middleware does not run on them.
+- **Zero-runtime mode** — see [Rendering modes](#rendering-modes-and-caveats).
+
+---
+
+## Base style props
+
+A small set of style properties — `display`, `font`, `preset`, `hide`, `whiteSpace`, `opacity`, `transition` — are harvested as props on every `tasty()` component. `baseStyleProps` adds to that set globally:
+
+```ts
+configure({ baseStyleProps: ['radius', 'shadow'] });
+
+<Card radius="1r" shadow />
+```
+
+Names must be real style properties, must start with a lowercase letter, and must not collide with a prop `tasty()` consumes itself (`as`, `styles`, `variant`, `mods`, `tokens`, …); invalid entries are dropped with a development warning.
+
+`configure()` may run *after* your components are defined — each factory resolves its prop list lazily and refreshes when the registry changes.
+
+**Costs and caveats.** Each name adds one property check per render of every component, forever, so keep the list short. The effect is app-global and cannot be scoped to a subtree — use a factory's own `styleProps` for that. Be wary of names that collide with real DOM or component props (`width`, `size`, `color`): promoting one means every component swallows it as a style, including when rendering `as={SomeThirdPartyComponent}`.
+
+---
+
+## Typing your extension
+
+Four augmentation points, each matching a runtime registry:
+
+```ts
+// tasty.d.ts
+import type { StylePropValue } from '@tenphi/tasty';
+
+declare module '@tenphi/tasty' {
+  // configure({ handlers }) — a new style property
+  interface StylesInterface {
+    stripe?: StylePropValue<string>;
+  }
+
+  // configure({ propHandlers }) — a new component prop
+  interface TastyCustomProps {
+    glaze: 'soft' | 'strong' | { tone: string; intensity?: number };
+  }
+
+  // configure({ baseStyleProps }) — promoted style names, typed like the style
+  interface TastyBaseStylePropNames {
+    radius: true;
+    shadow: true;
+  }
+
+  // configure({ tokens }) / recipes / presets — autocomplete for names
+  interface TastyNamedColors {
+    'glaze-bg': true;
+  }
+}
+```
+
+`TastyCustomProps` keys become optional props on every component. `TastyBaseStylePropNames` entries are typed exactly like the style they name, so `radius="1r"` accepts the same values as `styles={{ radius: '1r' }}`.
+
+**Also update `tasty.config.ts`.** The ESLint plugin and VS Code extension validate style and token names against it, and neither is derived from the runtime registries:
+
+```ts
+// tasty.config.ts
+export default {
+  styles: ['stripe'],
+  tokens: ['#glaze-bg'],
+};
+```
+
+`propHandlers` keys are JSX props rather than style keys, so they need no entry — but any *style* name or token a handler expands into does.
+
+---
+
+## Worked example: a `glaze` plugin
+
+A `glaze` prop on every component that takes a configuration object and expands into color token declarations. This is the case `propHandlers` exists for: the value is an options object, not a style value, so it cannot be a style property.
+
+```ts
+// glaze-plugin.ts
+import { mergeStyles } from '@tenphi/tasty';
+import type { Styles, TastyPluginFactory } from '@tenphi/tasty';
+
+export interface GlazeConfig {
+  tone: string;
+  /** 0–100. Default 10. */
+  intensity?: number;
+}
+
+type GlazeValue = string | GlazeConfig;
+
+// Memoized per value so the styles object is reference-stable across renders.
+const cache = new Map<string, Styles>();
+
+function glazeStyles(value: GlazeValue): Styles {
+  const { tone, intensity = 10 } =
+    typeof value === 'string' ? { tone: value } : value;
+  const key = `${tone}:${intensity}`;
+
+  let styles = cache.get(key);
+
+  if (!styles) {
+    styles = Object.freeze({
+      '#glaze-bg': `#${tone}.${intensity}`,
+      fill: '#glaze-bg',
+      transition: 'fill 0.2s',
+    }) as Styles;
+    cache.set(key, styles);
+  }
+
+  return styles;
+}
+
+export const glazePlugin: TastyPluginFactory = () => ({
+  name: 'glaze',
+
+  propHandlers: {
+    glaze: (props) => {
+      const { glaze, ...rest } = props;
+      if (!glaze) return rest;
+
+      return {
+        ...rest,
+        styles: mergeStyles(
+          glazeStyles(glaze as GlazeValue),
+          rest.styles as Styles,
+        ),
+      };
+    },
+  },
+
+  // Typed so `#glaze-bg` animates smoothly instead of snapping.
+  properties: {
+    '#glaze-bg': { syntax: '<color>', inherits: false, initialValue: 'transparent' },
+  },
+});
+```
+
+```ts
+// app entry, before the first render
+import { configure } from '@tenphi/tasty';
+
+import { glazePlugin } from './glaze-plugin';
+
+configure({ plugins: [glazePlugin()] });
+```
+
+```tsx
+<Element glaze="purple" />
+<Element glaze={{ tone: 'success', intensity: 30 }} />
+```
+
+```ts
+// tasty.d.ts
+declare module '@tenphi/tasty' {
+  interface TastyCustomProps {
+    glaze: import('./glaze-plugin').GlazeConfig | string;
+  }
+}
+```
+
+The object value is unambiguous here precisely because `glaze` is a **prop**. A style *value* of the same shape would be indistinguishable from a state map (`{ tone: … }` looks exactly like `{ hovered: … }`), which is why this belongs in `propHandlers` rather than `handlers`.
+
+---
+
+## Rendering modes and caveats
+
+| Mode | `functions` / `units` / `states` / `handlers` / `recipes` / `tokens` | `propHandlers` |
+|---|---|---|
+| Client | ✅ | ✅ |
+| SSR / RSC | ✅ | ✅ |
+| Zero-runtime (`tastyStatic`) | ✅ at build time | not applicable |
+
+**Zero-runtime.** The Babel plugin transforms `tastyStatic()` calls, which take styles objects — there are no props in that pipeline, so there is nothing for props middleware to run on. Components you render through `tasty()` are untouched by the plugin and keep the runtime injector, so `propHandlers` work there exactly as in any client app; their CSS simply comes from the injector rather than the extracted stylesheet. Everything else runs at build time, which is why handlers, functions, and units must be pure functions of their input.
+
+**Server and client must configure identically.** Class names are derived from resolved styles, so a handler or promoted prop registered on one side and not the other produces a hydration mismatch. This is the same requirement as `namePrefix` — see [SSR → Hydration mismatch warnings](ssr.md#hydration-mismatch-warnings).
+
+---
+
+## Testing a plugin
+
+```ts
+import { configure, resetConfig, renderStyles } from '@tenphi/tasty';
+
+describe('glaze plugin', () => {
+  beforeEach(() => resetConfig());
+  afterEach(() => resetConfig());
+
+  it('expands into a color token declaration', () => {
+    configure({ plugins: [glazePlugin()] });
+
+    const rules = renderStyles({ '#glaze-bg': '#purple.10' }, '.test');
+
+    expect(rules[0].declarations).toContain('--glaze-bg-color');
+  });
+});
+```
+
+Two things to know:
+
+- **Create components inside each test.** `resetConfig()` does not clear the per-factory class-name cache or prop-list memo, so a module-scope component created in one test carries state into the next.
+- **Dev-mode warnings may not fire.** `isDevEnv()` reports `false` for `NODE_ENV=test`. Warnings that check it lazily can be enabled with `vi.stubEnv('NODE_ENV', 'development')`; some older ones capture it at module load and cannot be triggered from a test at all.
+
+---
+
+See [Configuration](configuration.md) for every option in detail, [Style DSL](dsl.md) for the value syntax your extensions produce, and [React API](react-api.md) for `tasty()`, `styleProps`, `modProps`, and `tokenProps`.

package/docs/tasty/react-api.md

@@ -1,6 +1,6 @@
 # React API
 
-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).
+The React-specific `tasty()` component factory, component props, and style functions. All Tasty style functions — `tasty()` components, `useStyles()`, `useGlobalStyles()`, `useRawCSS()`, `useKeyframes()`, `useProperty()`, `useFontFace()`, `useCounterStyle()`, and `useFunction()` — are hook-free and compatible with React Server Components. No `'use client'` directive 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.
 
@@ -98,6 +98,26 @@ Style props accept state maps, so responsive values work through the same API:
 
 For predefined style prop lists (`FLOW_STYLES`, `POSITION_STYLES`, `DIMENSION_STYLES`, etc.) and guidance on which props to expose per component category, see [Methodology — styleProps as the public API](methodology.md#styleprops-as-the-public-api).
 
+### Always-available style props
+
+A small set of style properties — `display`, `font`, `preset`, `hide`, `whiteSpace`, `opacity`, and `transition` — are always harvested as style props on every `tasty()` component, even when `styleProps` is omitted. This means you can pass `<Card display="grid" />` or `<Text preset="h1" />` without declaring them. When you do declare `styleProps`, these base props are unioned with your list (not replaced).
+
+---
+
+## `Element`
+
+`Element` is the unstyled base component exported from the main entry — equivalent to `tasty({})` (a `div` with no default styles). It accepts all Tasty props (`styles`, `styleProps`, `mods`, `tokens`, `as`, `qa`, `theme`, the `is*` props, etc.) and is useful as a generic styled box or as a building block for layout primitives.
+
+```jsx
+import { Element } from '@tenphi/tasty';
+
+<Element as="section" padding="4x" fill="#surface">
+  Content
+</Element>
+```
+
+> Note: `Element` shadows the global DOM `Element` type when imported from `@tenphi/tasty`. In files that need the DOM type, alias the import: `import { Element as TastyElement } from '@tenphi/tasty'`.
+
 ---
 
 ## Mod Props
@@ -579,6 +599,46 @@ function useCounterStyle(
 ): string;
 ```
 
+### useFunction
+
+Register a CSS `@function` (custom function). Permanent — no cleanup on unmount. Deduplicates by function name. The function name accepts `$$name` (matching the call site `$$name(...)`), `$name`, or `--name`.
+
+```tsx
+import { tasty, useFunction } from '@tenphi/tasty';
+
+const Box = tasty({ styles: { marginTop: '$$negative(10px)' } });
+
+function Layout() {
+  useFunction('$$negative', { args: ['$value'], result: '(-1 * $value)' });
+  return <Box />;
+}
+```
+
+Call the function through the Tasty DSL rather than a raw `style` prop. An inline `style` value reaches the browser unparsed, so the `$$name(...)` sugar is never expanded — and under `configure({ polyfills: { functions: true } })` it silently does nothing, because the polyfill rewrites calls at parse time.
+
+Inside a `tasty()` component you call functions with the same `$$name(...)` sugar:
+
+```tsx
+const Box = tasty({
+  styles: {
+    '@function': { '$$negative': { args: ['$value'], result: '(-1 * $value)' } },
+    marginTop: '$$negative(10px)',
+  },
+});
+```
+
+Signature:
+
+```ts
+function useFunction(
+  name: string,
+  definition: FunctionDefinition,
+  options?: { root?: Document | ShadowRoot },
+): void;
+```
+
+See the [Functions section of the DSL reference](dsl.md#functions-function) for the full descriptor shape, token conventions, and value-sugar support. `@function` is an experimental CSS feature — unsupported browsers safely ignore the native rule, or enable the [`polyfills.functions`](configuration.md#polyfills) inline polyfill for full cross-browser support.
+
 ### 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).

package/docs/tasty/ssr.md

@@ -18,18 +18,18 @@ 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()` 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.
+`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 and serializes them as `<style>` tags plus a class-list script in the HTML. On the client, `hydrateTastyClasses()` pre-populates the injector's rules map with the rendered class names so that `computeStyles()` skips the rendering pipeline entirely during hydration.
 
 ```
 Server                         Client
 ──────                         ──────
-tasty() renders                hydrateTastyCache() pre-populates cache
-  └─ computeStyles()              └─ cacheKey → className map ready
+tasty() renders                hydrateTastyClasses() reads window.__TASTY__
+  └─ computeStyles()              └─ marks rendered class names as already-in-DOM
        └─ collector.collect()
                                  tasty() renders
 After render:                    └─ computeStyles()
-  <style data-tasty-ssr>              └─ cache hit → skip pipeline
-  <script data-tasty-cache>           └─ no CSS re-injection
+  <style data-tasty-ssr>             └─ class name known → skip pipeline
+  <script> (pushes to __TASTY__)     └─ no CSS re-injection
 ```
 
 ---
@@ -85,8 +85,8 @@ That's it. All `tasty()` components inside the tree automatically get SSR suppor
 - `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.
+- A companion inline `<script>` tag pushes the rendered class names into `window.__TASTY__` for each flush. This streaming-friendly approach accumulates the class list incrementally as Suspense boundaries resolve.
+- When the `@tenphi/tasty/ssr/next` module loads on the client, `hydrateTastyClasses()` runs automatically from `window.__TASTY__` and pre-populates the injector's rules map. During hydration, `computeStyles()` sees the class name is already registered and skips the entire pipeline.
 
 ### Using Tasty in Server Components
 
@@ -188,7 +188,7 @@ 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
+- A `<script>` tag pushing the rendered class names into `window.__TASTY__` 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.
@@ -223,7 +223,7 @@ export default defineConfig({
 });
 ```
 
-This gives the same middleware deduplication and hook support, but ships zero client-side JavaScript. No `<script data-tasty-cache>` is emitted.
+This gives the same middleware deduplication and hook support, but ships zero client-side JavaScript. No class-list `<script>` is emitted.
 
 ### Manual middleware (advanced)
 
@@ -258,7 +258,7 @@ export const onRequest = tastyMiddleware({ transferCache: false });
 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.
+- **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 class list from `window.__TASTY__` and pre-populates the injector's rules map. The island's `computeStyles()` calls see the class names as already registered and skip the pipeline during hydration.
 - The middleware reads the full response body, then injects the collected CSS into `</head>` before sending the final HTML.
 
 ### CSP nonce
@@ -274,31 +274,30 @@ Any React-based framework can integrate using `runWithCollector`, which binds a
 ```tsx
 import {
   ServerStyleCollector,
+  createServerStyleCollector,
   runWithCollector,
-  hydrateTastyCache,
+  hydrateTastyClasses,
 } from '@tenphi/tasty/ssr';
 import { renderToString } from 'react-dom/server';
 import { hydrateRoot } from 'react-dom/client';
 
 // ── Server ──────────────────────────────────────────────
 
-const collector = new ServerStyleCollector();
+const collector = createServerStyleCollector();
 
 const html = await runWithCollector(collector, () =>
   renderToString(<App />)
 );
 
 const css = collector.getCSS();
-const cacheState = collector.getCacheState();
+const classNames = collector.getRenderedClassNames();
 
 // Embed in your HTML template:
 const fullHtml = `
   <html>
     <head>
       <style data-tasty-ssr>${css}</style>
-      <script data-tasty-cache type="application/json">
-        ${JSON.stringify(cacheState)}
-      </script>
+      <script>(window.__TASTY__=window.__TASTY__||[]).push(${JSON.stringify(classNames)})</script>
     </head>
     <body>
       <div id="root">${html}</div>
@@ -309,7 +308,7 @@ const fullHtml = `
 // ── Client ──────────────────────────────────────────────
 
 // Before hydration:
-hydrateTastyCache(); // reads from <script data-tasty-cache>
+hydrateTastyClasses(); // reads from window.__TASTY__
 
 hydrateRoot(document.getElementById('root'), <App />);
 ```
@@ -319,7 +318,7 @@ hydrateRoot(document.getElementById('root'), <App />);
 For streaming with `renderToPipeableStream`, use `flushCSS()` instead of `getCSS()`:
 
 ```tsx
-const collector = new ServerStyleCollector();
+const collector = createServerStyleCollector();
 
 const stream = await runWithCollector(collector, () =>
   renderToPipeableStream(<App />, {
@@ -330,12 +329,14 @@ const stream = await runWithCollector(collector, () =>
       stream.pipe(res);
     },
     onAllReady() {
-      // Flush any remaining styles + cache state
+      // Flush any remaining styles + class list
       const css = collector.flushCSS();
       if (css) res.write(`<style data-tasty-ssr>${css}</style>`);
 
-      const state = collector.getCacheState();
-      res.write(`<script data-tasty-cache type="application/json">${JSON.stringify(state)}</script>`);
+      const classNames = collector.getRenderedClassNames();
+      res.write(
+        `<script>(window.__TASTY__=window.__TASTY__||[]).push(${JSON.stringify(classNames)})</script>`,
+      );
     },
   })
 );
@@ -349,16 +350,17 @@ const stream = await runWithCollector(collector, () =>
 
 | Import path | Description |
 |---|---|
-| `@tenphi/tasty/ssr` | Core SSR API: `ServerStyleCollector`, `runWithCollector`, `hydrateTastyCache` |
+| `@tenphi/tasty/ssr` | Core SSR API: `ServerStyleCollector`, `createServerStyleCollector`, `runWithCollector`, `hydrateTastyClasses` |
 | `@tenphi/tasty/ssr/next` | Next.js App Router: `TastyRegistry` component |
 | `@tenphi/tasty/ssr/astro` | Astro: `tastyIntegration`, `tastyMiddleware` |
 | `@tenphi/tasty/ssr/astro-client` | Astro: client-side cache hydration (auto-injected by integration, or import manually) |
+| `@tenphi/tasty/ssr/astro-middleware`<br>`@tenphi/tasty/ssr/astro-middleware-static` | Astro: the middleware entrypoints `tastyIntegration()` registers via `addMiddleware()`. Exported so Astro can resolve them by specifier; you should not import them. For manual setups use `tastyMiddleware()`. |
 
 ### `ServerStyleCollector`
 
 Server-safe style collector. One instance per request.
 
-Constructor: `new ServerStyleCollector(namePrefix?)`. The optional `namePrefix` overrides the value from `configure({ namePrefix })`; in normal usage you pass nothing and let the global config drive it. See [Configuration: Name prefix](configuration.md#name-prefix).
+Constructor: `new ServerStyleCollector(namePrefix?)`, or use the `createServerStyleCollector(namePrefix?)` factory. The optional `namePrefix` overrides the value from `configure({ namePrefix })`; in normal usage you pass nothing and let the global config drive it. See [Configuration: Name prefix](configuration.md#name-prefix).
 
 | Method | Description |
 |---|---|
@@ -375,7 +377,7 @@ Constructor: `new ServerStyleCollector(namePrefix?)`. The optional `namePrefix`
 | `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. |
+| `getRenderedClassNames()` | Get the list of class names rendered so far. Serialized to `window.__TASTY__` for client hydration via `hydrateTastyClasses()`. |
 
 ### `TastyRegistry`
 
@@ -402,9 +404,9 @@ Astro middleware factory. Use for manual middleware composition.
 |---|---|---|---|
 | `transferCache` | `boolean` | `true` | Embed cache state script for island hydration |
 
-### `hydrateTastyCache(state?)`
+### `hydrateTastyClasses(classes?)`
 
-Pre-populate the client injector cache. When called without arguments, reads from `window.__TASTY_SSR_CACHE__` (streaming) or `<script data-tasty-cache>` (non-streaming).
+Pre-populate the client injector's rules map with class names rendered on the server, marking them as already present in the DOM so `computeStyles()` skips re-injection during hydration. When called without arguments, reads the class list from `window.__TASTY__` (populated by the streaming `<script>` tags emitted during SSR).
 
 ### `runWithCollector(collector, fn)`
 
@@ -420,23 +422,29 @@ The `TastyRegistry` or `tastyIntegration` is missing. Ensure your layout wraps t
 
 ### Hydration mismatch warnings
 
-Class names are deterministic for the same render order. If you see mismatches, ensure `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()`.
+Class names are deterministic for the same render order. If you see mismatches, ensure `hydrateTastyClasses()` runs before React hydration. For Next.js, this is automatic. For Astro with `tastyIntegration()`, this is also automatic. For manual Astro middleware setups, import `@tenphi/tasty/ssr/astro-client` in your island components. For custom setups, call `hydrateTastyClasses()` before `hydrateRoot()`.
+
+Class names are also derived from the *resolved* styles, so the server and the client must configure Tasty identically. Anything that changes what a component's styles resolve to will produce a mismatch if it is registered on only one side — `namePrefix`, `recipes`, `handlers`, and the `propHandlers` / `baseStyleProps` extension points described in [Plugins](plugins.md). Call the same `configure()` on both; global CSS is deduplicated automatically, so no `typeof window` guard is needed.
 
 ### Styles duplicated 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:
+**Component CSS**: SSR `<style data-tasty-ssr>` tags remain in the DOM. The client injector creates separate `<style>` elements for any new styles. SSR styles are never modified or removed by the client. If this is a concern for very large apps, you can remove the SSR style tags and hydration scripts manually after hydration:
 
 ```tsx
-import { hydrateTastyCache } from '@tenphi/tasty/ssr';
+import { hydrateTastyClasses } from '@tenphi/tasty/ssr';
 
-hydrateTastyCache();
+hydrateTastyClasses();
 hydrateRoot(root, <App />);
 
-// Optional: remove SSR style tags after hydration
-document.querySelectorAll('style[data-tasty-ssr]').forEach(el => el.remove());
-document.querySelectorAll('script[data-tasty-cache]').forEach(el => el.remove());
+// Optional: remove SSR style tags and class-list scripts after hydration
+document.querySelectorAll('style[data-tasty-ssr]').forEach((el) => el.remove());
+document
+  .querySelectorAll('script')
+  .forEach((el) => {
+    if (el.textContent?.includes('__TASTY__')) el.remove();
+  });
 ```
 
 ### `AsyncLocalStorage` not available