@tenphi/tasty 3.3.1 → 3.5.0

package/docs/runtime-benchmarks.md

@@ -0,0 +1,178 @@
+# Runtime Benchmarks
+
+Tasty keeps its performance claims in reproducible benchmarks rather than
+combining unlike measurements into one score. The repository measures three
+different costs:
+
+1. Style parsing and generation in Node.
+2. The React overhead of an empty `tasty({})` wrapper.
+3. Cold browser generation and injection compared with equivalent CSS that is
+   already on the page.
+
+These are focused microbenchmarks, not page-load or interaction scores. Run
+them several times on an otherwise idle machine and use a production profile
+to decide whether any cost matters in an application.
+
+## Reproducing the Results
+
+```bash
+pnpm bench
+pnpm bench:overhead
+pnpm bench:injection
+```
+
+`pnpm bench` runs the core pipeline benchmarks in Node. The other two commands
+use production code paths in headless Chromium. The first checkout may require
+`pnpm test:setup` to download Chromium.
+
+Run the Node and browser suites separately so they do not compete for CPU. The
+browser timer has 0.1 ms resolution, so both browser benchmarks perform many
+matched operations per sample and divide the absolute difference by the number
+of elements or rules. Machine load, browser versions, and CPU power will move
+the results.
+
+## Core Style Pipeline
+
+The following numbers are single-call throughput measured on an Apple M1 Max
+with Node 22:
+
+| Operation                                                   |              ops/sec | Latency (mean) |
+| ----------------------------------------------------------- | -------------------: | -------------: |
+| `renderStyles` — 5 flat properties (cold)                   |              ~60,000 |         ~17 us |
+| `renderStyles` — state map with media/hover/modifier (cold) |              ~18,500 |         ~54 us |
+| `renderStyles` — same styles (cached)                       |           ~5,800,000 |       ~0.17 us |
+| `parseStateKey` — simple key like `:hover` (cold)           |             ~790,000 |        ~1.3 us |
+| `parseStateKey` — complex OR/AND/NOT key (cold)             |             ~140,000 |          ~7 us |
+| `parseStateKey` — any key (cached)                          | ~3,400,000–8,300,000 |    ~0.1–0.3 us |
+| `parseStyle` — value tokens like `2x 4x` (cold)             |             ~344,000 |        ~2.9 us |
+| `parseStyle` — color tokens (cold)                          |             ~567,000 |        ~1.8 us |
+| `parseStyle` — any value (cached)                           |          ~15,250,000 |       ~0.07 us |
+
+“Cold” cases use unique inputs to bypass the relevant caches. Cached cases
+reuse one input and measure the LRU hot path. Expect roughly ±10% between runs.
+These benchmarks do not include React, DOM work, stylesheet injection, style
+resolution, layout, or paint.
+
+The benchmark sources are colocated with the code they exercise:
+[`pipeline.bench.ts`](../src/pipeline/pipeline.bench.ts),
+[`parseStateKey.bench.ts`](../src/pipeline/parseStateKey.bench.ts), and the
+parser benchmark files under [`src/parser`](../src/parser).
+
+## Empty Wrapper Overhead
+
+Skipping the style pipeline does not make a `tasty()` component free. Even
+`tasty({})` is a React component between its parent and the host element. React
+tracks another fiber, and Tasty still processes and forwards the element's
+props.
+
+[`tasty-overhead.bench.tsx`](../src/tasty-overhead.bench.tsx) compares 10,000
+raw `<div className>` siblings with 10,000 instances of one module-scoped
+`tasty({})` component. Both receive the same props, and the benchmark fails if
+they do not produce equivalent DOM.
+
+The benchmark uses production React in headless Chromium. The factory is
+created and its empty class-name cache is warmed before timing, so factory
+creation, style generation, and injection are excluded. A detached container
+excludes layout, paint, and stylesheet matching. Every commit is wrapped in
+`flushSync`, keeping its synchronous reconciliation and commit inside the
+sample. This does not estimate React's concurrent scheduling latency.
+
+On an Apple M3 Pro with React 19.2.4 and Chromium 151, three consecutive runs
+produced these ranges:
+
+| Work on 10,000 siblings             | Raw elements |  `tasty({})` | Extra per wrapped element |
+| ----------------------------------- | -----------: | -----------: | ------------------------: |
+| Mount + remove                      |   4.5–4.9 ms | 14.0–14.9 ms |              0.95–1.00 us |
+| Rerender, same host props           |   1.3–1.4 ms | 10.9–11.4 ms |              0.96–1.00 us |
+| Rerender, change one host attribute |   2.8–3.4 ms | 15.0–15.7 ms |              1.21–1.27 us |
+
+The useful result is the raw/Tasty time difference divided by 10,000, not the
+ratio between the two times. The ratio becomes large because the raw baseline
+is tiny. In this synthetic workload, an empty wrapper adds roughly 1 us per
+participating element, or 1.2–1.3 us when React also changes a DOM attribute.
+
+This is the floor Tasty consumes when it has no styling job. It is not a
+page-level score. Real trees include application components, effects, layout,
+paint, and usually far fewer simultaneous styled-element updates. The benchmark
+also does not measure retained memory; that requires a matched-tree heap
+snapshot experiment with controlled garbage collection.
+
+## Cold Generation and Injection
+
+[`tasty-injection.bench.ts`](../src/tasty-injection.bench.ts) measures the extra
+work when Tasty must generate and inject CSS that an otherwise equivalent page
+already has. It does not compare different stylesheet insertion techniques.
+
+The benchmark covers two useful workloads:
+
+- **One new rule:** add one rule to an existing stylesheet, append its one
+  element, and immediately read its computed style. Each timed sample performs
+  50 independent one-rule transactions and reports their total; dividing the
+  raw/Tasty difference by 50 produces a stable per-rule result despite
+  Chromium's 0.1 ms timer resolution.
+- **1,000 new rules together:** generate and insert all 1,000 rules into one
+  stylesheet, append all 1,000 elements, then read every computed color without
+  another write in between. This gives the browser one style-resolution
+  boundary for the group.
+
+For every transaction, the existing-CSS control has the equivalent stylesheet
+parsed, adopted, and attached before timing. The runtime root has a Tasty
+stylesheet pre-created with an unrelated sentinel rule, but not the measured
+rules. Both paths perform the same class assignment, DOM commit, and
+computed-style reads. Only the runtime path calls `computeStyles()` and inserts
+the new rules.
+
+Preparation and cleanup happen outside the sample timer. Every runtime style
+value is unique within a cycle, the relevant caches are cleared between cycles,
+and a guard verifies that both paths resolve to the same color. React and the
+`tasty()` wrapper are absent so their independently measured costs do not enter
+the result. Pre-creating both stylesheets also excludes one-time sheet creation
+and adoption from the subtraction.
+
+On an Apple M3 Pro with Chromium 151, three consecutive runs produced these
+ranges:
+
+| Workload                                             | CSS already present |  Tasty runtime | Incremental Tasty cost |
+| ---------------------------------------------------- | ------------------: | -------------: | ---------------------: |
+| One new rule + immediate resolution, per transaction |          2.8–3.3 us | 110.3–113.8 us |         107.3–111.0 us |
+| 1,000 new rules + one resolution                     |        1.86–2.06 ms |   9.01–9.98 ms |           7.13–7.92 ms |
+| 1,000-rule workload, incremental cost per rule       |                   — |              — |             7.1–7.9 us |
+
+Directly compared, injecting 1,000 rules before one resolution boundary cost
+about 66–71 times as much in total as injecting one rule and resolving it—not
+1,000 times as much. Its average incremental cost per rule was about 14–16
+times lower. This is the same Tasty generation and injection path in both cases;
+the group amortizes fixed transaction work and lets the browser resolve all the
+stylesheet writes together.
+
+The subtraction is the meaningful result. It includes Tasty's cold style
+generation, cache and injector bookkeeping, rule insertion, and any additional
+style invalidation exposed by that workload's resolution boundary. It does not
+pretend to isolate `insertRule()` from the system that calls it.
+
+This is a deliberately cold workload. Reused styles resolve from cache and do
+not inject another rule. Different rule complexity, DOM shape, stylesheet size,
+browser, and hardware will change the number. The single-rule and 1,000-rule
+results are not interchangeable: the first crosses the injection-to-resolution
+boundary once per rule, while the second lets the browser resolve 1,000 writes
+together. Because the same resolution pattern is present in each workload's
+control, the difference answers the narrower delivery question: how much extra
+work did Tasty perform when the same CSS was not already there?
+
+## Reading the Results Together
+
+Do not add all three benchmark numbers to estimate an application blindly.
+They describe different paths:
+
+- A stable `tasty()` factory can skip the style pipeline on later renders, but
+  its React wrapper still participates in reconciliation.
+- A cached style avoids cold parsing and generation and does not insert a new
+  rule.
+- A genuinely new style pays generation and injection once, then becomes
+  reusable.
+- Browser style resolution, layout, and paint depend on the actual document and
+  need application-level profiling.
+
+The practical optimization target is therefore repeated work: keep style input
+stable when possible, reuse generated chunks, and generate CSS at build or
+server time when runtime flexibility is unnecessary.

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`.
 
@@ -122,13 +128,15 @@ The nonce is automatically applied to all `<style>` and `<script>` tags injected
 
 ## Astro
 
-Tasty offers three levels of Astro integration. Choose the one that matches your needs:
+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 |
+| 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           |
 
 ### Zero setup (static pages)
 
@@ -225,6 +233,39 @@ export default defineConfig({
 
 This gives the same middleware deduplication and hook support, but ships zero client-side JavaScript. No class-list `<script>` is emitted.
 
+#### Build-wide CSS extraction
+
+Static Astro builds can move repeated Tasty CSS into a content-hashed,
+browser-cacheable asset:
+
+```ts
+export default defineConfig({
+  integrations: [
+    react(),
+    tastyIntegration({
+      islands: false,
+      css: {
+        mode: 'extract',
+      },
+    }),
+  ],
+});
+```
+
+`css.mode` defaults to `'inline'`, so existing projects keep their current
+output. Extraction requires Astro 5 or newer and only applies to prerendered
+production pages. Development, preview-time SSR, and on-demand routes continue
+to receive the normal inline `<style data-tasty-ssr>` output.
+
+Extraction moves the largest common block whose position can be preserved on
+every generated page into one stylesheet. Page-only component, global, and raw
+CSS stays inline, so unvisited routes do not receive unrelated styles.
+
+The asset is written under Astro's configured `build.assets` directory (for
+example, `/_astro/tasty.a1b2c3.css`). Links include the configured Astro
+`base`, so nested routes do not need relative-path handling. The content hash
+and output are deterministic for identical builds.
+
 ### Manual middleware (advanced)
 
 If you need to compose Tasty's middleware with other middleware (e.g., via `sequence()`), use `tastyMiddleware()` directly:
@@ -234,10 +275,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:
@@ -260,10 +298,14 @@ Astro's `@astrojs/react` renderer calls `renderToString()` for each React compon
 - **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 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.
+- In extraction mode, prerendered responses also carry temporary structured
+  artifact metadata. `astro:build:done` uses those collector-provided
+  boundaries to write the shared asset and rewrite generated HTML, then removes
+  the metadata. CSS is never split on newlines or parsed heuristically.
 
 ### CSP nonce
 
-Call `configure({ nonce: '...' })` before any rendering happens. The middleware reads the nonce and applies it to injected `<style>` and `<script>` tags.
+Call `configure({ nonce: '...' })` before any rendering happens. The middleware reads the nonce and applies it to injected `<style>` and `<script>` tags. In extraction mode, page-local inline style tags and the external stylesheet link retain the nonce.
 
 ---
 
@@ -285,9 +327,7 @@ import { hydrateRoot } from 'react-dom/client';
 
 const collector = createServerStyleCollector();
 
-const html = await runWithCollector(collector, () =>
-  renderToString(<App />)
-);
+const html = await runWithCollector(collector, () => renderToString(<App />));
 
 const css = collector.getCSS();
 const classNames = collector.getRenderedClassNames();
@@ -338,7 +378,7 @@ const stream = await runWithCollector(collector, () =>
         `<script>(window.__TASTY__=window.__TASTY__||[]).push(${JSON.stringify(classNames)})</script>`,
       );
     },
-  })
+  }),
 );
 ```
 
@@ -348,13 +388,13 @@ 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/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()`. |
+| 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`<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`
 
@@ -362,47 +402,47 @@ Server-safe style collector. One instance per request.
 
 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()`. |
+| 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 |
 
 ### `hydrateTastyClasses(classes?)`
 
@@ -424,11 +464,11 @@ The `TastyRegistry` or `tastyIntegration` is missing. Ensure your layout wraps t
 
 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.
+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.
+**Global CSS** (`:root` tokens, `@property`, `globalStyles`, `@font-face`, `@counter-style`, `@function`) configured via `configure()` is automatically deduplicated. When Tasty detects an inline or extracted `[data-tasty-ssr]` stylesheet 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:
 
@@ -440,11 +480,9 @@ hydrateRoot(root, <App />);
 
 // 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();
-  });
+document.querySelectorAll('script').forEach((el) => {
+  if (el.textContent?.includes('__TASTY__')) el.remove();
+});
 ```
 
 ### `AsyncLocalStorage` not available

package/docs/styles.md

@@ -305,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"
 ```
 
 ---