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

package/docs/ssr.md

@@ -1,16 +1,22 @@
 # Server-Side Rendering (SSR)
 
-Tasty supports server-side rendering with zero-cost client hydration. This does **not** introduce a separate styling engine: SSR uses the same runtime `tasty()` pipeline you already use on the client, then adds server-side CSS collection and client-side cache hydration. Your existing `tasty()` components work unchanged, and SSR remains opt-in with no per-component modifications. For the broader docs map, see the [Docs Hub](README.md).
+Tasty supports server-side rendering with zero-cost client hydration. This does **not** introduce a separate styling engine: `tasty()` uses the same rendering pipeline on the server and in the browser, while the SSR integrations add server-side CSS collection and client-side cache hydration. Your existing `tasty()` components work unchanged, and SSR remains opt-in with no per-component modifications. For the broader docs map, see the [Docs Hub](README.md).
+
+## Zero-runtime terminology
+
+Zero-runtime delivery is an outcome, not an alias for `tastyStatic()`. When `tasty()` components render only on the server, their CSS is delivered with the HTML and no Tasty styling runtime is shipped to the browser. Astro's `tastyIntegration({ islands: false })` is the explicit integration for this setup. Server-only Next.js React Server Components follow the same architecture, although you should verify the generated output for your deployment.
+
+`tastyStatic()` reaches the same client-side outcome by extracting CSS during the build instead of during React rendering. Use it when extraction must happen before rendering or when the consumer is not React; see [Build-Time Extraction](tasty-static.md).
 
 ---
 
 ## Requirements
 
-| 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` |
-| Node.js | >= 20 | Generic / streaming SSR (`@tenphi/tasty/ssr`) — uses `node:async_hooks` for `AsyncLocalStorage` |
+| 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`        |
+| 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`.
 
@@ -18,18 +24,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 +91,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
 
@@ -124,11 +130,11 @@ The nonce is automatically applied to all `<style>` and `<script>` tags injected
 
 Tasty offers three 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 |
+| 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 |
 
 ### Zero setup (static pages)
 
@@ -188,7 +194,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 +229,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)
 
@@ -234,10 +240,7 @@ If you need to compose Tasty's middleware with other middleware (e.g., via `sequ
 import { sequence } from 'astro:middleware';
 import { tastyMiddleware } from '@tenphi/tasty/ssr/astro';
 
-export const onRequest = sequence(
-  tastyMiddleware(),
-  myOtherMiddleware,
-);
+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:
@@ -258,7 +261,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 +277,28 @@ 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 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 +309,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 +319,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,14 +330,16 @@ 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>`,
+      );
     },
-  })
+  }),
 );
 ```
 
@@ -347,62 +349,65 @@ const stream = await runWithCollector(collector, () =>
 
 ### Entry points
 
-| Import path | Description |
-|---|---|
-| `@tenphi/tasty/ssr` | Core SSR API: `ServerStyleCollector`, `runWithCollector`, `hydrateTastyCache` |
-| `@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) |
+| 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/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.
 
-| Method | Description |
-|---|---|
-| `allocateClassName(cacheKey)` | Allocate a sequential class name (`t0`, `t1`, ...) for a cache key. Returns `{ className, isNewAllocation }`. |
-| `collectChunk(cacheKey, className, rules)` | Record CSS rules for a chunk. Deduplicated by `cacheKey`. |
-| `collectKeyframes(name, css)` | Record a `@keyframes` rule. Deduplicated by name. |
-| `allocateKeyframeName(providedName?)` | Allocate a keyframe name. Returns `providedName` if given, otherwise generates one (`k0`, `k1`, ...). |
-| `collectProperty(name, css)` | Record a `@property` rule. Deduplicated by name. |
-| `collectFontFace(key, css)` | Record a `@font-face` rule. Deduplicated by content hash. |
-| `collectCounterStyle(name, css)` | Record a `@counter-style` rule. Deduplicated by name. |
-| `allocateCounterStyleName(providedName?)` | Allocate a counter-style name. Returns `providedName` if given, otherwise generates one (`cs0`, `cs1`, ...). |
-| `collectGlobalStyles(key, css)` | Record global styles (from `useGlobalStyles`). Deduplicated by key. |
-| `collectRawCSS(key, css)` | Record raw CSS text (from `useRawCSS`). Deduplicated by key. |
-| `collectInternals()` | Collect internal `@property` rules, `:root` token defaults, `@font-face`, and `@counter-style` rules from the global config. Called automatically on first chunk collection; idempotent. |
-| `getCSS()` | Get all collected CSS as a single string. For non-streaming SSR. |
-| `flushCSS()` | Get only CSS collected since the last flush. For streaming SSR. |
-| `getCacheState()` | Serialize `{ entries: Record<cacheKey, className>, classCounter }` for client hydration. |
+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                                                                                                                                                                                                                                                                |
+| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `allocateClassName(cacheKey)`              | Allocate a deterministic, content-hashed class name for a cache key (e.g. `t1a2b3` with the default prefix). The same `cacheKey` always produces the same class name on server and client when both share the same `namePrefix`. Returns `{ className, isNewAllocation }`. |
+| `collectChunk(cacheKey, className, rules)` | Record CSS rules for a chunk. Deduplicated by `cacheKey`.                                                                                                                                                                                                                  |
+| `collectKeyframes(name, css)`              | Record a `@keyframes` rule. Deduplicated by name.                                                                                                                                                                                                                          |
+| `allocateKeyframeName(providedName?)`      | Allocate a keyframe name. Returns `providedName` if given, otherwise generates one 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.                                                                                                                                                                                                                      |
+| `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 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.                                                                                                                                                                                                            |
+| `getRenderedClassNames()`                  | Get the list of class names rendered so far. Serialized to `window.__TASTY__` for client hydration via `hydrateTastyClasses()`.                                                                                                                                            |
 
 ### `TastyRegistry`
 
 Next.js App Router component. Props:
 
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `children` | `ReactNode` | required | Application tree |
-| `transferCache` | `boolean` | `true` | Embed cache state script for zero-cost hydration |
+| Prop            | Type        | Default  | Description                                      |
+| --------------- | ----------- | -------- | ------------------------------------------------ |
+| `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. |
+| 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. Use for manual middleware composition.
 
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `transferCache` | `boolean` | `true` | Embed cache state script for island hydration |
+| Option          | Type      | Default | Description                                   |
+| --------------- | --------- | ------- | --------------------------------------------- |
+| `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)`
 
@@ -418,21 +423,27 @@ 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
 
-This is expected and harmless. SSR `<style data-tasty-ssr>` tags remain in the DOM. The client injector creates separate `<style>` elements for any new styles. SSR styles are never modified or removed by the client. If this is a concern for very large apps, call `cleanupSSRStyles()` after hydration:
+**Global CSS** (`:root` tokens, `@property`, `globalStyles`, `@font-face`, `@counter-style`) configured via `configure()` is automatically deduplicated. When Tasty detects `<style data-tasty-ssr>` in the document, it skips client-side injection of globals that were already rendered by the SSR collector. This means `configure()` can be called with the full config on both server and client — no `typeof window === 'undefined'` guard is needed.
+
+**Component CSS**: SSR `<style data-tasty-ssr>` tags remain in the DOM. The client injector creates separate `<style>` elements for any new styles. SSR styles are never modified or removed by the client. If this is a concern for very large apps, 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

package/docs/styles.md

@@ -1,6 +1,6 @@
 # Style Properties Reference
 
-All standard CSS properties are supported in Tasty and benefit from its syntax sugar: design tokens (`$name`, `#name`), custom units (`2x`, `1r`, `1bw`), color opacity (`#purple.5`), auto-calc (`(100% - 2x)`), and custom functions. Values are parsed through the Tasty engine automatically.
+All standard CSS properties are supported in Tasty and benefit from its syntax sugar: design tokens (`$name`, `#name`), custom units (`2x`, `1r`, `1bw`), color opacity (`#purple.5`), auto-calc (`(100% - 2x)`), and [custom functions](dsl.md#functions-function) (`$$negative(10px)`). Values are parsed through the Tasty engine automatically.
 
 The properties documented below have **custom handlers** with enhanced syntax. They should be **preferred** over their raw CSS equivalents because they:
 
@@ -100,18 +100,23 @@ For flex/grid layouts, outputs native `gap`. For block layouts, emulates gap usi
 
 Element padding with directional modifiers and multi-group support. Use **comma-separated groups** to set a base value and then override specific directions.
 
-**Syntax:** `[value]` | `[top right]` | `[top right bottom left]` | `[value directions...]` — comma-separated for multiple groups
+**Syntax:** `[value]` | `[block inline]` | `[top right bottom left]` | `[value direction...]` — comma-separated for multiple groups
 
 **Direction modifiers:** `top`, `right`, `bottom`, `left`
 
 **Output modifier:** `longhand` — forces output as individual CSS longhand properties (`padding-top`, `padding-right`, `padding-bottom`, `padding-left`) instead of the `padding` shorthand. Useful when children need to selectively inherit individual directions.
 
+**One value per directional group.** A group that names direction modifiers takes **exactly one** value, applied to every direction it names. For different values per side, use comma-separated groups: `padding: '2x top, 4x right'`. Writing `padding: '2x 4x top right'` ignores `4x` and warns in development — the parser keeps values and modifiers in separate buckets, so their interleaving in the source is not recoverable and `'2x 4x top right'`, `'2x top 4x right'` and `'top 2x right 4x'` are all the same input.
+
+A group that names *no* direction keeps plain CSS shorthand order, which is unambiguous and unchanged.
+
 | Value | Effect |
 |-------|--------|
 | `"2x"` | All sides `2x` |
 | `"2x 1x"` | Top/bottom `2x`, left/right `1x` |
 | `"2x top"` | Top `2x`, right/bottom/left `0` |
 | `"1x left right"` | Left and right `1x`, top/bottom `0` |
+| `"2x top, 4x right"` | Top `2x`, right `4x`, bottom/left `0` |
 | `"1x, 2x top"` | All sides `1x`, then top overridden to `2x` |
 | `"1x, 2x top bottom"` | Left/right `1x`, top/bottom `2x` |
 | `"2x longhand"` | All sides `2x`, output as 4 individual `padding-*` properties |
@@ -128,17 +133,20 @@ Individual props `paddingTop`, `paddingRight`, `paddingBottom`, `paddingLeft`, `
 
 Element margin. Same syntax, modifiers, and multi-group support as `padding`.
 
-**Syntax:** `[value]` | `[top right]` | `[top right bottom left]` | `[value directions...]` — comma-separated for multiple groups
+**Syntax:** `[value]` | `[block inline]` | `[top right bottom left]` | `[value direction...]` — comma-separated for multiple groups
 
 **Direction modifiers:** `top`, `right`, `bottom`, `left`
 
 **Output modifier:** `longhand` — forces output as individual CSS longhand properties (`margin-top`, etc.) instead of the `margin` shorthand.
 
+The [one-value-per-directional-group rule](#padding) from `padding` applies here too.
+
 | Value | Effect |
 |-------|--------|
 | `"2x"` | All sides `2x` |
 | `"2x 1x"` | Top/bottom `2x`, left/right `1x` |
 | `"2x top"` | Top `2x`, right/bottom/left `0` |
+| `"2x top, 4x right"` | Top `2x`, right `4x`, bottom/left `0` |
 | `"auto left right, 1x top bottom"` | Left/right `auto`, top/bottom `1x` |
 | `true` | All sides `1x` |
 | Number | Converted to `px` |
@@ -191,10 +199,23 @@ Separate `minHeight` and `maxHeight` props are supported and override values fro
 
 Positioning offsets with directional modifiers and multi-group support. Same directional syntax as `padding`.
 
-**Syntax:** `[value]` | `[top right]` | `[top right bottom left]` | `[value directions...]` — comma-separated for multiple groups
+**Syntax:** `[value]` | `[block inline]` | `[top right bottom left]` | `[value direction...]` — comma-separated for multiple groups
 
 **Direction modifiers:** `top`, `right`, `bottom`, `left`
 
+The [one-value-per-directional-group rule](#padding) from `padding` applies here too, with `dock`
+as the single exception.
+
+**`dock` modifier:** pins the named edge and spans its full length, by also applying the value
+to the two perpendicular sides. `inset: 'bottom dock'` gives `inset: auto 0 0 0` — anchored to
+the bottom, full width. Without a direction, `dock` fills every side.
+
+`dock` is the one place a directional group takes **two** values: the first insets the named
+edge, the second the sides it spans. `inset: '2x 4x bottom dock'` pins the bottom at `2x` and
+insets the sides by `4x`. A third value, or a second value without `dock`, is ignored and warns
+in development. With several directions the first value applies to each named edge and the
+second to every side they span.
+
 **Output modifier:** `longhand` — forces output as individual CSS properties (`top`, `right`, `bottom`, `left`) instead of the `inset` shorthand.
 
 | Value | Effect |
@@ -205,6 +226,11 @@ Positioning offsets with directional modifiers and multi-group support. Same dir
 | `"0, 2x top"` | All sides `0`, then top overridden to `2x` |
 | `"0 longhand"` | All sides `0`, output as individual `top`/`right`/`bottom`/`left` |
 | `true` | All sides `0` |
+| `"bottom dock"` | Bottom/left/right `0`, top `auto` — bottom-anchored, full width |
+| `"right dock"` | Right/top/bottom `0`, left `auto` — right-anchored, full height |
+| `"2x bottom dock"` | Bottom/left/right `2x`, top `auto` |
+| `"2x 4x bottom dock"` | Bottom `2x`, left/right `4x`, top `auto` |
+| `"dock"` | All sides `0` |
 
 Later comma-separated groups override earlier groups for conflicting directions.
 
@@ -228,6 +254,7 @@ Background color with design token support. Preferred over `backgroundColor` and
 | `"#purple.10"` | Token color at 10% opacity |
 | `"#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.
@@ -260,9 +287,17 @@ Text color with design token support.
 | `"#current"` | Current inherited color |
 | `"#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) |
 | `true` | `currentColor` |
 
-When set to a named color token, also sets `$current-color` and `$current-color-{colorSpace}` custom properties for downstream use (suffix depends on the configured `colorSpace`, default `oklch`).
+Also sets `$current-color` to the same color, for anything that needs the
+inherited color as a color rather than as the `currentcolor` keyword. Every color
+publishes it, not just a named token, so a reader below always takes the nearest
+`color` rather than the nearest *token* color. A value that already reads the
+inherited color — `#current` itself, a `#current` fade, a bare `currentColor` —
+is not republished: resolving it a second time one level down would fade it
+twice, and the variable into itself is a self-reference. `#current` does not go
+through it; it is the keyword.
 
 ### `svgFill`
 
@@ -270,7 +305,7 @@ SVG fill color. Same color token syntax as `fill` and `color`. Outputs the nativ
 
 ```jsx
 svgFill="#purple.10"
-svgFill="currentColor"
+svgFill="#current"
 ```
 
 ---
@@ -319,7 +354,11 @@ Border radius with shape presets and directional modifiers.
 | `"backleaf"` | Asymmetric: round, sharp, round, sharp |
 | `"inherit"` | Inherit border-radius from parent |
 
-**Direction modifiers:** `top`, `right`, `bottom`, `left` — rounds only the specified corners.
+**Edge modifiers:** `top`, `right`, `bottom`, `left` — rounds the *pair* of corners along that edge.
+
+**Corner modifiers:** `top-left`, `top-right`, `bottom-right`, `bottom-left` — rounds a single corner.
+Use these when an edge modifier would round one corner too many. Edge and corner modifiers combine
+(`radius: 'top bottom-right'`).
 
 **Output modifier:** `longhand` — forces output as individual CSS longhand properties (`border-top-left-radius`, `border-top-right-radius`, `border-bottom-right-radius`, `border-bottom-left-radius`) instead of the `border-radius` shorthand. Useful when children need to selectively inherit individual corners via `radius: 'inherit left'`.
 
@@ -334,6 +373,9 @@ Border radius with shape presets and directional modifiers.
 | `"1r longhand"` | All corners `1r`, output as 4 individual `border-*-radius` properties |
 | `"inherit"` | All corners inherit from parent (`border-radius: inherit`) |
 | `"inherit right"` | Right corners inherit from parent (uses longhand properties) |
+| `"top-right"` | Top-right corner `1r`, every other corner `0` |
+| `"4px top-left"` | Top-left corner `4px`, every other corner `0` |
+| `"top bottom-right"` | Both top corners and bottom-right `1r`, bottom-left `0` |
 
 ### `outline`
 
@@ -378,11 +420,11 @@ Multiple shadows: `shadow="1x 1x 2x #dark.20, inset 0 0 4x #dark.10"`
 
 Typography preset that sets font-size, line-height, letter-spacing, font-weight, font-style, and text-transform from named design tokens.
 
-**Syntax:** `name`, `name / modifier`, or `modifier` (shorthand)
+**Syntax:** `name`, `name / modifier...`, or `modifier...` (shorthand)
 
 Preset names are project-specific (e.g. `h1`–`h6`, `t1`–`t4`, `p1`–`p4`). Register them for autocomplete by augmenting `TastyPresetNames`.
 
-Use `/` to separate the preset name from a modifier. When a modifier is used alone (without a name), the preset name defaults to `inherit`.
+Use `/` to separate the preset name from one or more space-separated modifiers. When modifiers are used alone (without a name), the preset name defaults to `inherit`. Modifiers can be combined freely because they target different properties.
 
 **Modifiers:**
 
@@ -394,11 +436,13 @@ Use `/` to separate the preset name from a modifier. When a modifier is used alo
 | `tight` | Sets line-height equal to font-size |
 
 ```jsx
-preset="h1"              // heading 1
-preset="h2 / strong"     // bold heading 2
-preset="t3 / italic"     // italic text 3
-preset="t2 / tight"      // text 2 with tight line-height
-preset="bold"             // inherit preset with bold (shorthand for "inherit / bold")
+preset="h1"                    // heading 1
+preset="h2 / strong"           // bold heading 2
+preset="h2 / strong italic"    // bold + italic heading 2
+preset="t3 / italic"           // italic text 3
+preset="t2 / strong tight"     // bold text 2 with tight line-height
+preset="bold"                  // inherit preset with bold (shorthand)
+preset="bold italic"           // inherit preset with bold + italic (shorthand)
 ```
 
 Individual typography props (`fontSize`, `lineHeight`, `letterSpacing`, `fontWeight`, `fontStyle`, `textTransform`) can be used alongside `preset` to override specific values, but using `preset` alone is recommended.
@@ -550,15 +594,20 @@ Scrollbar styling using CSS standard properties (`scrollbar-width`, `scrollbar-c
 
 Gradient-based edge fading using CSS masks. Use **comma-separated groups** to set different widths and colors per direction.
 
-**Syntax:** `[width] [directions...] [#from-color] [#to-color]` — comma-separated for multiple groups
+**Syntax:** `[width] [direction...] [#from-color] [#to-color]` — comma-separated for multiple groups
 
 **Direction modifiers:** `top`, `right`, `bottom`, `left`
 
+A group that names edges takes a **single** width, applied to every edge it names — different
+widths per edge come from comma groups. A group that names no edge covers all four and keeps
+plain CSS shorthand order, like `padding`. See the [`padding` rule](#padding).
+
 | Value | Effect |
 |-------|--------|
 | `"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 top bottom"` | Fade top with `3x` width, bottom with `1x` width |
+| `"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` |
 | `"top #a #b, bottom #c #d"` | Top fades from `#a` to `#b`, bottom fades from `#c` to `#d` |