@cube-dev/ui-kit 0.197.0 → 0.198.0

package/docs/tasty/ssr.md

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

package/docs/tasty/styles.md

@@ -10,6 +10,8 @@ The properties documented below have **custom handlers** with enhanced syntax. T
 
 Other CSS properties (e.g. `opacity`, `transform`, `cursor`, `position`, `zIndex`) are passed through with standard Tasty value parsing but no special handler logic.
 
+[`@tenphi/eslint-plugin-tasty`](getting-started.md#eslint-plugin) reports raw CSS properties that have a handler here (`prefer-shorthand-property`) and modifiers a property does not accept (`valid-directional-modifier`, `valid-radius-shape`).
+
 ---
 
 ## Recommended Props
@@ -64,7 +66,7 @@ Standard CSS display values. Handled together with `hide`, `textOverflow`, `over
 | `display` | Any CSS display value | Overridden by `hide` or multi-line `textOverflow` |
 | `hide` | `true` / `false` | Shortcut for `display: none`. Highest priority |
 | `overflow` | Any CSS overflow value | Overridden when `textOverflow` sets `hidden` |
-| `whiteSpace` | Any CSS white-space value | Overridden when `textOverflow` sets `nowrap` or `initial` |
+| `whiteSpace` | Any CSS white-space value | Explicit value wins over the `nowrap` / `initial` that `textOverflow` sets |
 
 ### `textOverflow`
 
@@ -78,7 +80,7 @@ Text truncation with optional multi-line clamping.
 | `"ellipsis / 3"` | Multi-line clamp (3 lines) with ellipsis, sets `overflow: hidden` and `white-space: initial` |
 | `"clip"` | Single-line truncation without ellipsis, sets `overflow: hidden` and `white-space: nowrap` |
 | `"clip / 2"` | Multi-line clip (2 lines), sets `overflow: hidden` and `white-space: initial` |
-| `true` or `"initial"` | Reset text-overflow to initial |
+| `"initial"` | Reset text-overflow to initial |
 
 Explicit `whiteSpace` overrides the default white-space set by `textOverflow`.
 
@@ -144,6 +146,8 @@ A group that names *no* direction keeps plain CSS shorthand order, which is unam
 
 Later comma-separated groups override earlier groups for conflicting directions.
 
+A group with directions but no value (`padding: 'top'`) uses `1x`, the same as `padding: true`, so it follows `configure({ units })`.
+
 Individual physical props `paddingTop`, `paddingRight`, `paddingBottom`, and `paddingLeft` are supported, but `padding` with modifiers is recommended. Use `blockPadding` or `inlinePadding` for an enhanced logical-axis shorthand; native declarations such as `paddingInlineStart` remain ordinary CSS properties. See [Logical properties](#logical-properties).
 
 ### `margin`
@@ -193,12 +197,15 @@ Element width with min/max control. One, two, or three values set `min-width`, `
 | `"min 2x"` | `2x` | auto | initial |
 | `"max 100%"` | initial | auto | `100%` |
 | `"fixed 200px"` | `200px` | `200px` | `200px` |
+| `"min"` | `1x` | auto | initial |
+| `"max"` | initial | auto | `100%` |
+| `"fixed"` | `max-content` | `max-content` | `max-content` |
 
 **Keywords:** `stretch`, `max-content`, `min-content`, `fit-content`
 
 | Value | Effect |
 |-------|--------|
-| `"stretch"` | Fill available space (cross-browser) |
+| `"stretch"` | Fill the available space, margins included. Emitted with `-webkit-fill-available` and `-moz-available` fallbacks for engines without the standard keyword |
 | `true` | Reset to `auto` / `initial` / `initial` |
 | Number | Converted to `px` |
 
@@ -206,7 +213,7 @@ Separate `minWidth` and `maxWidth` props are supported and override values from
 
 ### `height`
 
-Element height. Same syntax, modifiers, and positional patterns as `width`.
+Element height. Same syntax, modifiers, keywords, and positional patterns as `width`, including `stretch`.
 
 Separate `minHeight` and `maxHeight` props are supported and override values from the `height` syntax.
 
@@ -305,9 +312,10 @@ Background color with design token support. Preferred over `backgroundColor` and
 | `"#surface #primary.10"` | Background `#surface` with `#primary.10` overlay (two colors enable smooth transitions between both) |
 | `"rgb(255 128 0)"` | CSS color value |
 | `"color-mix(in oklab, #primary 50%, #surface)"` | CSS color function — see [CSS Color Functions](dsl.md#css-color-functions) |
-| `true` | Default fill color |
 
-When two colors are provided, the first sets the background color and the second is applied as an overlay gradient layer. This enables independent CSS transitions on each color. The overlay is only applied when no explicit `image` or `backgroundImage` is set.
+When two colors are provided, the first sets the background color and the second is applied as an overlay gradient layer. This enables independent CSS transitions on each color. With `image` or `backgroundImage` on the same element, the image is layered over the overlay color in one `background-image`.
+
+There is no default fill color, so `fill: true` is ignored with a development warning. Use `false` for no fill.
 
 **Related deprecated props:** `backgroundColor` (use `fill`), `background` (overrides all background props when set — avoid).
 
@@ -338,6 +346,7 @@ Text color with design token support.
 | `"#current.5"` | Current inherited color at 50% opacity |
 | `"(#primary, #secondary)"` | Fallback: use `#primary`, fall back to `#secondary` |
 | `"light-dark(#dark, #light)"` | CSS color function — see [CSS Color Functions](dsl.md#css-color-functions) |
+| `"#ddd"` | Hex literal, read as the `#ddd` token with the literal as fallback: `var(--ddd-color, #ddd)`, as in every color style |
 | `true` | `currentColor` |
 
 Also sets `$current-color` to the same color, for anything that needs the
@@ -368,7 +377,7 @@ Border shorthand with directional and multi-group support. Use **comma-separated
 
 **Syntax:** `[width] [style] [color] [directions...]` — comma-separated for multiple groups
 
-**Defaults:** width = `1bw`, style = `solid`, color = `#border`
+**Defaults:** width = `1bw`, style = `solid`, color = `#border`, which is the text color (`currentColor`) until your tokens define `#border`
 
 **Styles:** `none`, `hidden`, `dotted`, `dashed`, `solid`, `double`, `groove`, `ridge`, `inset`, `outset`
 
@@ -385,9 +394,12 @@ Border shorthand with directional and multi-group support. Use **comma-separated
 | `"1bw longhand"` | All sides: 1bw solid `#border`, output as 4 individual `border-*` properties |
 | `"1bw #red, 2bw #blue top"` | All sides: 1bw solid `#red`, top overridden to 2bw solid `#blue` |
 | `"1bw, dashed top bottom, #purple left right"` | Base: 1bw solid `#border`, top/bottom: 1bw dashed `#border`, left/right: 1bw solid `#purple` |
+| `"1bw CanvasText"` | All sides: 1bw solid in the system color `CanvasText` (see [Color keywords](dsl.md#color-keywords)) |
 
 Later comma-separated groups override earlier groups for conflicting directions.
 
+A directional group without a width (`'dotted left'`) uses `1bw`, the same as `border: true`, so it follows `configure({ units })`.
+
 ### `radius`
 
 Border radius with shape presets and directional modifiers.
@@ -427,13 +439,15 @@ Use these when an edge modifier would round one corner too many. Edge and corner
 | `"4px top-left"` | Top-left corner `4px`, every other corner `0` |
 | `"top bottom-right"` | Both top corners and bottom-right `1r`, bottom-left `0` |
 
+A value-less corner group (`'top-right'`, `'top bottom-right'`) uses `1r`, the same as `radius: true`, so it follows `configure({ units })`.
+
 ### `outline`
 
 Outline with inline offset support.
 
 **Syntax:** `[width] [style] [color] / [offset]`
 
-**Defaults:** width = `1ow`, style = `solid`, color = `#outline`
+**Defaults:** width = `1ow`, style = `solid`, color = `#outline`, which is the text color (`currentColor`) until your tokens define `#outline`
 
 **Styles:** Same as `border` (`none`, `dotted`, `dashed`, `solid`, etc.)
 
@@ -468,7 +482,7 @@ Multiple shadows: `shadow="1x 1x 2x #dark.20, inset 0 0 4x #dark.10"`
 
 ### `preset`
 
-Typography preset that sets font-size, line-height, letter-spacing, font-weight, font-style, and text-transform from named design tokens.
+Typography preset that sets font-size, line-height, letter-spacing, font-weight, font-style, text-transform, and font-family (unless `font` or `fontFamily` is set) from named design tokens. It also sets the `--bold-font-weight` and `--icon-size` variables that `strong` and `icon` read.
 
 **Syntax:** `name`, `name / modifier...`, or `modifier...` (shorthand)
 
@@ -480,10 +494,11 @@ Use `/` to separate the preset name from one or more space-separated modifiers.
 
 | Modifier | Effect |
 |----------|--------|
-| `strong` (or `bold`) | Sets `font-weight` to bold (from `$bold-font-weight` token) |
+| `strong` (or `bold`) | Sets `font-weight` to bold (from `$bold-font-weight` token, `700` until your tokens define it) |
 | `italic` | Sets `font-style: italic` |
 | `icon` | Sets font-size and line-height to icon size |
 | `tight` | Sets line-height equal to font-size |
+| `normal` | Sets `line-height: normal` |
 
 ```jsx
 preset="h1"                    // heading 1
@@ -503,9 +518,9 @@ Font family with design-system fallback. Preferred over `fontFamily`.
 
 | Value | Effect |
 |-------|--------|
-| `"monospace"` | Monospace font stack (from `$monospace-font` token) |
-| `true` | Default system font (from `$font` token) |
-| `"CustomFont"` | Custom font with system font fallback |
+| `"monospace"` | Monospace stack from `$font-mono`, falling back to the built-in `$font-mono-fallback` |
+| `true` | Default sans stack from `$font-sans`, falling back to `$font-sans-fallback` |
+| `"CustomFont"` | Custom font followed by the `$font-sans` stack |
 
 `fontFamily` is supported as a direct pass-through without fallback logic.
 
@@ -581,12 +596,14 @@ When easing is provided without a duration, the default timing variable is used
 | `width` | `width`, `min-width`, `max-width` |
 | `height` | `height`, `min-height`, `max-height` |
 | `gap` | `gap`, `margin` |
-| `zIndex` | `z-index` |
+| `zIndex` | `z-index` (same as writing `z-index`) |
 | `inset` | `inset`, `top`, `right`, `bottom`, `left` |
 
+Any other name passes through as a CSS property.
+
 When two entries cover the same property, an entry that names that one property wins over a group such as `theme`, in either order: `opacity 120ms ease-in-out, theme` keeps the opacity timing. Otherwise the later entry wins, as in CSS.
 
-Default timing: `$transition` (or `${name}-transition` with `$transition` fallback per semantic name). Prefer omitting the duration or using a duration token instead of repeating raw time values across components. Explicit zero can disable motion.
+Default timing: `$transition` (or `${name}-transition` with `$transition` fallback per semantic name). `$transition` is `80ms` until your tokens define it. Prefer omitting the duration or using a duration token instead of repeating raw time values across components. Explicit zero can disable motion.
 
 ```jsx
 transition="theme"
@@ -595,8 +612,11 @@ transition="fade $transition ease-in"
 transition="fill ease-in"           // easing without duration (uses default timing)
 transition="radius ease-in-out"     // easing keyword only
 transition="$$custom-prop"          // custom property transition
+transition="none"                   // no transition at all, e.g. under @media(prefers-reduced-motion: reduce)
 ```
 
+`none` and the CSS-wide keywords (`inherit`, `initial`, `unset`, `revert`, `revert-layer`) are the whole value, not a name to transition.
+
 **Recognized easing keywords:** `ease`, `ease-in`, `ease-out`, `ease-in-out`, `linear`, `step-start`, `step-end`. CSS easing functions (`cubic-bezier(...)`, `steps(...)`, `linear(...)`) are also recognized.
 
 If the name is not a semantic name, it is used as a literal CSS property name.
@@ -674,11 +694,11 @@ plain CSS shorthand order, like `padding`. See the [`padding` rule](#padding).
 
 | Value | Effect |
 |-------|--------|
-| `"top"` | Fade top edge, default width (`2x`), all other edges unfaded |
+| `"top"` | Fade top edge, default width `2x`, all other edges unfaded |
 | `"2x left right"` | Fade left and right edges with `2x` width, top/bottom unfaded |
 | `"3x 1x"` | All edges faded — top/bottom `3x`, left/right `1x` (CSS shorthand order) |
 | `"3x top, 1x bottom"` | Fade top with `3x` width, bottom with `1x` width |
-| `"2x #transparent #dark"` | All edges faded with `2x` width, from `#transparent` to `#dark` |
+| `"2x #clear #dark"` | All edges faded with `2x` width, from `#clear` to `#dark` |
 | `"top #a #b, bottom #c #d"` | Top fades from `#a` to `#b`, bottom fades from `#c` to `#d` |
 
 Colors are optional: first = transparent mask start, second = opaque mask end.