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

package/docs/react-api.md

@@ -1,6 +1,8 @@
 # React API
 
-The React-specific `tasty()` component factory, component props, and style functions. All Tasty style functions — `tasty()` components, `useStyles()`, `useGlobalStyles()`, `useRawCSS()`, `useKeyframes()`, `useProperty()`, `useFontFace()`, and `useCounterStyle()` — are hook-free and compatible with React Server Components. No `'use client'` directive needed. For the shared style language (state maps, tokens, units, extending semantics), see [Style DSL](dsl.md). For global configuration, see [Configuration](configuration.md). For the broader docs map, see the [Docs Hub](README.md).
+Use `tasty()` to turn state-aware style definitions into normal React components, extend existing Tasty components, and expose typed styling APIs to consumers.
+
+All Tasty style functions — `tasty()` components, `useStyles()`, `useGlobalStyles()`, `useRawCSS()`, `useKeyframes()`, `useProperty()`, `useFontFace()`, `useCounterStyle()`, and `useFunction()` — are hook-free and compatible with React Server Components. No `'use client'` directive is needed. For state maps, tokens, units, and extension semantics, see [Style DSL](dsl.md). For global configuration, see [Configuration](configuration.md). For the broader docs map, see the [Docs Hub](README.md).
 
 > **Note:** This file was previously named `runtime.md`. All functionality documented here works in both server and client contexts — "runtime" referred to style computation during React rendering, not to client-side JavaScript.
 
@@ -42,6 +44,32 @@ const PrimaryButton = tasty(Button, {
 
 Style maps merge intelligently — see [Style DSL — Extending vs. Replacing State Maps](dsl.md#extending-vs-replacing-state-maps) for extend mode, replace mode, `@inherit`, `null`, and `false` tombstones.
 
+`tasty(Component, ...)` always wraps `Component` and forwards every prop to it, so `Component` must be Tasty-aware (i.e. it accepts `styles`, `mods`, `qa`, etc. and renders them through its own Tasty pipeline). To apply styles to a third-party component or a string DOM tag via `className`, use the options-only form with `as`:
+
+```jsx
+import NextLink from 'next/link';
+
+const Link = tasty({
+  as: NextLink,
+  styles: {
+    color: { '': '#accent-text', ':hover': '#text' },
+    textDecoration: 'underline',
+  },
+  styleProps: ['padding'],
+});
+
+const Span = tasty({
+  as: 'span',
+  styles: { preset: 'strong' },
+});
+
+<Link href="/blog" padding="1x">
+  Blog
+</Link>;
+```
+
+The wrapped component only needs to forward `className` (and ideally `style`/`ref`). Tasty-specific props (`qa`, `qaVal`, `mods`, `tokens`, `styleProps`, `modProps`, `tokenProps`) are consumed by Tasty and never leak to the DOM.
+
 ---
 
 ## Style Props
@@ -60,7 +88,7 @@ const FlexibleBox = tasty({
 
 <FlexibleBox gap="2x" align="center" fill="#surface">
   Content
-</FlexibleBox>
+</FlexibleBox>;
 ```
 
 Style props accept state maps, so responsive values work through the same API:
@@ -74,6 +102,26 @@ Style props accept state maps, so responsive values work through the same API:
 
 For predefined style prop lists (`FLOW_STYLES`, `POSITION_STYLES`, `DIMENSION_STYLES`, etc.) and guidance on which props to expose per component category, see [Methodology — styleProps as the public API](methodology.md#styleprops-as-the-public-api).
 
+### Always-available style props
+
+A small set of style properties — `display`, `font`, `preset`, `hide`, `whiteSpace`, `opacity`, and `transition` — are always harvested as style props on every `tasty()` component, even when `styleProps` is omitted. This means you can pass `<Card display="grid" />` or `<Text preset="h1" />` without declaring them. When you do declare `styleProps`, these base props are unioned with your list (not replaced).
+
+---
+
+## `Element`
+
+`Element` is the unstyled base component exported from the main entry — equivalent to `tasty({})` (a `div` with no default styles). It accepts all Tasty props (`styles`, `styleProps`, `mods`, `tokens`, `as`, `qa`, `theme`, the `is*` props, etc.) and is useful as a generic styled box or as a building block for layout primitives.
+
+```jsx
+import { Element } from '@tenphi/tasty';
+
+<Element as="section" padding="4x" fill="#surface">
+  Content
+</Element>;
+```
+
+> Note: `Element` shadows the global DOM `Element` type when imported from `@tenphi/tasty`. In files that need the DOM type, alias the import: `import { Element as TastyElement } from '@tenphi/tasty'`.
+
 ---
 
 ## Mod Props
@@ -112,9 +160,9 @@ Map modifier names to type descriptors for precise TypeScript types:
 ```tsx
 const Button = tasty({
   modProps: {
-    isLoading: Boolean,   // isLoading?: boolean
-    isSelected: Boolean,  // isSelected?: boolean
-    size: ['small', 'medium', 'large'] as const,  // size?: 'small' | 'medium' | 'large'
+    isLoading: Boolean, // isLoading?: boolean
+    isSelected: Boolean, // isSelected?: boolean
+    size: ['small', 'medium', 'large'] as const, // size?: 'small' | 'medium' | 'large'
   },
   styles: {
     padding: { '': '2x 4x', 'size=small': '1x 2x', 'size=large': '3x 6x' },
@@ -122,18 +170,20 @@ const Button = tasty({
   },
 });
 
-<Button isLoading size="large">Submit</Button>
+<Button isLoading size="large">
+  Submit
+</Button>;
 // Renders: <button data-is-loading="" data-size="large">Submit</button>
 ```
 
 Available type descriptors:
 
-| Descriptor | TypeScript type | Example |
-|---|---|---|
-| `Boolean` | `boolean` | `isLoading: Boolean` |
-| `String` | `string` | `label: String` |
-| `Number` | `number` | `count: Number` |
-| `['a', 'b'] as const` | `'a' \| 'b'` | `size: ['sm', 'md', 'lg'] as const` |
+| Descriptor            | TypeScript type | Example                             |
+| --------------------- | --------------- | ----------------------------------- |
+| `Boolean`             | `boolean`       | `isLoading: Boolean`                |
+| `String`              | `string`        | `label: String`                     |
+| `Number`              | `number`        | `count: Number`                     |
+| `['a', 'b'] as const` | `'a' \| 'b'`    | `size: ['sm', 'md', 'lg'] as const` |
 
 ### Merge with `mods`
 
@@ -146,11 +196,11 @@ Mod props and the `mods` object can be used together. Mod props take precedence:
 
 ### When to use `modProps` vs `mods`
 
-| Use case | Recommendation |
-|---|---|
+| Use case                                     | Recommendation                                           |
+| -------------------------------------------- | -------------------------------------------------------- |
 | Component has a fixed set of known modifiers | `modProps` — cleaner API, better TypeScript autocomplete |
-| Component needs arbitrary/dynamic modifiers | `mods` — open-ended `Record<string, ModValue>` |
-| Both fixed and dynamic | Combine: `modProps` for known keys, `mods` for ad-hoc |
+| Component needs arbitrary/dynamic modifiers  | `mods` — open-ended `Record<string, ModValue>`           |
+| Both fixed and dynamic                       | Combine: `modProps` for known keys, `mods` for ad-hoc    |
 
 For architecture guidance on when to use modifiers vs `styleProps`, see [Methodology — modProps and mods](methodology.md#modprops-and-mods).
 
@@ -180,7 +230,7 @@ const ProgressBar = tasty({
 
 <ProgressBar progress="75%" accentColor="#purple" />
 // 'progress'    → $progress    → --progress
-// 'accentColor' → #accent      → --accent-color + --accent-color-oklch
+// 'accentColor' → #accent      → --accent-color
 ```
 
 ### Object form
@@ -196,7 +246,7 @@ const Card = tasty({
   styles: { padding: '$card-size', fill: '#card-accent' },
 });
 
-<Card size="4x" color="#purple" />
+<Card size="4x" color="#purple" />;
 ```
 
 ### Merge with `tokens`
@@ -215,11 +265,11 @@ const Bar = tasty({
 
 ### When to use `tokenProps` vs `tokens`
 
-| Use case | Recommendation |
-|---|---|
-| Component has a fixed set of known token keys | `tokenProps` — cleaner API, better TypeScript autocomplete |
-| Component needs arbitrary/dynamic token values | `tokens` — open-ended `Record<string, TokenValue>` |
-| Both fixed and dynamic | Combine: `tokenProps` for known keys, `tokens` for ad-hoc |
+| Use case                                       | Recommendation                                             |
+| ---------------------------------------------- | ---------------------------------------------------------- |
+| Component has a fixed set of known token keys  | `tokenProps` — cleaner API, better TypeScript autocomplete |
+| Component needs arbitrary/dynamic token values | `tokens` — open-ended `Record<string, TokenValue>`         |
+| Both fixed and dynamic                         | Combine: `tokenProps` for known keys, `tokens` for ad-hoc  |
 
 For architecture guidance, see [Methodology — tokenProps](methodology.md#tokenprops).
 
@@ -238,11 +288,11 @@ const Button = tasty({
   variants: {
     default: { fill: '#blue', color: '#white' },
     danger: { fill: '#red', color: '#white' },
-    outline: { fill: 'transparent', color: '#blue', border: '1bw solid #blue' },
+    outline: { fill: '#clear', color: '#blue', border: '1bw solid #blue' },
   },
 });
 
-<Button variant="danger">Delete</Button>
+<Button variant="danger">Delete</Button>;
 ```
 
 ### Extending Variants with Base State Maps
@@ -298,7 +348,7 @@ const Card = tasty({
 <Card>
   <Card.Title>Card Title</Card.Title>
   <Card.Content>Card content</Card.Content>
-</Card>
+</Card>;
 ```
 
 Each entry in `elements` can be a tag name string or a config object:
@@ -324,7 +374,7 @@ const Card = tasty({
 
 <Card>
   <div data-element="Title">Card Title</div>
-</Card>
+</Card>;
 ```
 
 ### Selector Affix (`$`)
@@ -357,7 +407,7 @@ On the client, CSS is injected synchronously into the DOM (idempotent via the in
 
 All style functions below are plain functions (not React hooks) and can be used in any environment: client components, SSR with a `ServerStyleCollector`, and React Server Components. They retain their `use` prefix for backward compatibility, but do not use any React hooks internally.
 
-In server-only contexts (Next.js RSC without `'use client'`, Astro without `client:*` directives, SSG), components that use only Tasty style functions produce zero client JavaScript. Tasty never forces the `'use client'` boundary — that decision belongs to your component when it needs React interactivity (state, effects, event handlers).
+In server-only contexts, components that use only Tasty style functions ship no Tasty styling runtime. Astro without `client:*` directives produces no client JavaScript; server-only Next.js RSC follows the same Tasty architecture, while final output depends on the application deployment. Tasty never forces the `'use client'` boundary — that decision belongs to your component when it needs React interactivity (state, effects, event handlers).
 
 ### useStyles
 
@@ -395,6 +445,15 @@ function ThemeStyles() {
 }
 ```
 
+A slot — the `id`, or the selector when no `id` is given — holds exactly one
+injection **per `root`**. So:
+
+- Changing the styles replaces the previous CSS rather than adding to it.
+- Passing styles that produce no CSS (for example `{}`) clears the slot.
+- The same selector used in two shadow roots keeps a separate injection in each.
+- Two independent call sites that share a selector share a slot, and the last
+  render wins. Give them distinct `id`s if they should coexist.
+
 ### useRawCSS
 
 Inject raw CSS strings. Accepts an optional `id` in the options for update tracking — when the CSS changes for the same id, the previous injection is replaced:
@@ -411,6 +470,9 @@ function GlobalReset() {
 }
 ```
 
+An `id` slot holds one injection per `root`. Without an `id` the CSS is deduped
+by content and permanent — there is nothing to replace it with later.
+
 ### useKeyframes
 
 Inject `@keyframes` rules and return the generated animation name:
@@ -424,14 +486,14 @@ function Spinner() {
       from: { transform: 'rotate(0deg)' },
       to: { transform: 'rotate(360deg)' },
     },
-    { name: 'spin' }
+    { name: 'spin' },
   );
 
   return <div style={{ animation: `${spin} 1s linear infinite` }} />;
 }
 ```
 
-`useKeyframes()` also supports a factory function. The deps array is accepted for backward compatibility but the factory is called on every invocation — deduplication is handled internally by content hash:
+`useKeyframes()` also supports a factory function. Without a `name` the factory runs on every invocation and deduplication is handled internally by content hash; with a `name`, matching deps skip the factory entirely:
 
 ```tsx
 function Pulse({ scale }: { scale: number }) {
@@ -440,13 +502,24 @@ function Pulse({ scale }: { scale: number }) {
       '0%': { transform: 'scale(1)' },
       '100%': { transform: `scale(${scale})` },
     }),
-    [scale]
+    [scale],
+    { name: 'pulse' },
   );
 
-  return <div style={{ animation: `${pulse} 500ms ease-in-out alternate infinite` }} />;
+  return (
+    <div
+      style={{ animation: `${pulse} 500ms ease-in-out alternate infinite` }}
+    />
+  );
 }
 ```
 
+Passing `name` claims a slot owned by that one call site, per `root` — much like
+`id` in `useGlobalStyles()` and `useRawCSS()`. When the steps change the previous
+`@keyframes` rule is disposed and the name is reused, so the rules don't
+accumulate and the returned name stays stable. Anonymous keyframes are permanent
+and shared by content.
+
 ### useProperty
 
 Register a CSS `@property` rule so a custom property can animate smoothly:
@@ -493,8 +566,16 @@ For multiple weights/styles, pass an array:
 
 ```tsx
 useFontFace('Brand Sans', [
-  { src: 'url("/fonts/brand-regular.woff2") format("woff2")', fontWeight: 400, fontDisplay: 'swap' },
-  { src: 'url("/fonts/brand-bold.woff2") format("woff2")', fontWeight: 700, fontDisplay: 'swap' },
+  {
+    src: 'url("/fonts/brand-regular.woff2") format("woff2")',
+    fontWeight: 400,
+    fontDisplay: 'swap',
+  },
+  {
+    src: 'url("/fonts/brand-bold.woff2") format("woff2")',
+    fontWeight: 700,
+    fontDisplay: 'swap',
+  },
 ]);
 ```
 
@@ -512,11 +593,14 @@ Inject a `@counter-style` rule and get back the counter style name. Permanent
 import { useCounterStyle } from '@tenphi/tasty';
 
 function EmojiList() {
-  const styleName = useCounterStyle({
-    system: 'cyclic',
-    symbols: '"👍"',
-    suffix: '" "',
-  }, { name: 'thumbs' });
+  const styleName = useCounterStyle(
+    {
+      system: 'cyclic',
+      symbols: '"👍"',
+      suffix: '" "',
+    },
+    { name: 'thumbs' },
+  );
 
   return (
     <ol style={{ listStyleType: styleName }}>
@@ -536,6 +620,46 @@ function useCounterStyle(
 ): string;
 ```
 
+### useFunction
+
+Register a CSS `@function` (custom function). Permanent — no cleanup on unmount. Deduplicates by function name. The function name accepts `$$name` (matching the call site `$$name(...)`), `$name`, or `--name`.
+
+```tsx
+import { tasty, useFunction } from '@tenphi/tasty';
+
+const Box = tasty({ styles: { margin: '$$negative(10px) top' } });
+
+function Layout() {
+  useFunction('$$negative', { args: ['$value'], result: '(-1 * $value)' });
+  return <Box />;
+}
+```
+
+Call the function through the Tasty DSL rather than a raw `style` prop. An inline `style` value reaches the browser unparsed, so the `$$name(...)` sugar is never expanded — and under `configure({ polyfills: { functions: true } })` it silently does nothing, because the polyfill rewrites calls at parse time.
+
+Inside a `tasty()` component you call functions with the same `$$name(...)` sugar:
+
+```tsx
+const Box = tasty({
+  styles: {
+    '@function': { $$negative: { args: ['$value'], result: '(-1 * $value)' } },
+    margin: '$$negative(10px) top',
+  },
+});
+```
+
+Signature:
+
+```ts
+function useFunction(
+  name: string,
+  definition: FunctionDefinition,
+  options?: { root?: Document | ShadowRoot },
+): void;
+```
+
+See the [Functions section of the DSL reference](dsl.md#functions-function) for the full descriptor shape, token conventions, and value-sugar support. `@function` is an experimental CSS feature — unsupported browsers safely ignore the native rule, or enable the [`polyfills.functions`](configuration.md#polyfills) inline polyfill for full cross-browser support.
+
 ### Troubleshooting
 
 - Styles are not updating: make sure `configure()` runs before first render, and verify the generated class name or global rule with [Debug Utilities](debug.md).
@@ -552,6 +676,6 @@ function useCounterStyle(
 - **[Methodology](methodology.md)** — Recommended patterns: root + sub-elements, styleProps, tokens, wrapping
 - **[Configuration](configuration.md)** — Tokens, recipes, custom units, style handlers, TypeScript extensions
 - **[Style Properties](styles.md)** — Complete reference for all enhanced style properties
-- **[Zero Runtime (tastyStatic)](tasty-static.md)** — Build-time static styling with Babel plugin
+- **[Build-Time Extraction (`tastyStatic`)](tasty-static.md)** — Static styling with the Babel plugin
 - **[Server-Side Rendering](ssr.md)** — SSR setup for Next.js, Astro, and generic frameworks
 - **[Debug Utilities](debug.md)** — Inspect injected CSS, cache state, and active styles at runtime

package/docs/runtime-benchmarks.md

@@ -0,0 +1,216 @@
+# Runtime Benchmarks
+
+Tasty keeps its performance claims in reproducible benchmarks rather than
+combining unlike measurements into one score. The repository measures four
+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.
+4. A representative React update that combines wrapper, cache, generation,
+   injection, and style-resolution work.
+
+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:tree
+```
+
+`pnpm bench` runs the core pipeline benchmarks in Node. The other three 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 four group sizes with one style-resolution boundary per
+group:
+
+- **One new rule:** add one rule, append its element, and immediately read its
+  computed style. Each sample performs 50 independent groups for timer
+  stability.
+- **10 new rules together:** generate and insert 10 rules, append their 10
+  elements, then read every computed color without another write. Each sample
+  performs 10 independent groups.
+- **100 or 1,000 new rules together:** perform the same sequence once per
+  sample with 100 or 1,000 rules before the resolution boundary.
+
+Repeating the smaller groups inside one sample only raises the measurement
+above Chromium's timer resolution. Results are divided by that repetition
+count, so every row below describes one group with one resolution boundary.
+
+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
+normalized ranges:
+
+| New rules before one resolution | Groups per sample | Incremental cost per group | Incremental cost per rule |
+| ------------------------------: | ----------------: | -------------------------: | ------------------------: |
+|                               1 |                50 |             0.111–0.114 ms |                111–114 us |
+|                              10 |                10 |             0.142–0.159 ms |              14.2–15.9 us |
+|                             100 |                 1 |               0.90–0.94 ms |                9.0–9.4 us |
+|                           1,000 |                 1 |               7.58–8.10 ms |                7.6–8.1 us |
+
+The curve makes the fixed work visible. Delivering 1,000 rules before one
+resolution boundary cost roughly 67–73 times as much in total as delivering
+one rule and resolving it, not 1,000 times as much. The average incremental
+cost per rule was roughly 14–15 times lower because the group amortized fixed
+transaction work and let the browser resolve all 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. Because the same group and
+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?
+
+## Representative React Tree
+
+[`tasty-tree.bench.tsx`](../src/tasty-tree.bench.tsx) bridges the isolated
+measurements with one production React update. Every path updates 1,000 host
+elements sharing 20 combinations of `color` and `padding`, then reads computed
+styles after the commit:
+
+- **CSS already present:** raw elements switch between classes whose rules were
+  attached before timing.
+- **Tasty, warm:** the elements switch between two sets of Tasty styles that
+  were generated before timing.
+- **Tasty, cold:** every update introduces 20 new combinations shared across
+  the 1,000 elements.
+
+The Tasty paths use the normal component API and `TastyBatchProvider`. On an
+Apple M3 Pro with production React 19.2.4 and Chromium 151, three consecutive
+runs produced these mean ranges:
+
+| Update path                         | Total time for 1,000 elements |
+| ----------------------------------- | ----------------------------: |
+| CSS already present                 |                  1.64–1.70 ms |
+| Tasty, shared styles already cached |                  4.17–4.43 ms |
+| Tasty, 20 new shared styles         |                  4.62–4.80 ms |
+
+In this workload, the warmed Tasty path added 2.52–2.73 ms over raw elements
+with existing CSS. Introducing 20 new shared combinations added another
+0.38–0.55 ms over the warm Tasty update. This is a synthetic update, not an
+application score: it excludes effects, layout reads, paint, and concurrent
+scheduling, while deliberately making all 1,000 elements participate in every
+commit.
+
+## 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.
+- A tree that shares a small style vocabulary pays the wrapper path per element
+  but cold generation only per new combination.
+- 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.