@tenphi/cookbook 0.28.0 → 0.30.1

package/docs/upstream/tasty/docs/react-api.md

@@ -2,7 +2,7 @@
 
 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).
+Every Tasty style function — `tasty()` components, `computeStyles()`, `useStyles()`, `useGlobalStyles()`, `useRawCSS()`, `useKeyframes()`, `useProperty()`, `useFontFace()`, `useCounterStyle()`, and `useFunction()` — works in React Server Components with no `'use client'` directive. All of them except `useStyles()` are hook-free. `useStyles()` reads the `TastyRegistry` collector from React context on the client, so it is a real hook there; outside React, call `computeStyles()` instead. 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.
 
@@ -44,6 +44,30 @@ 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.
 
+The extension form takes the same component options as `tasty({ … })`:
+
+```jsx
+const ActionCard = tasty(Card, {
+  styles: { fill: { '': '#surface', isRaised: '#surface-raised' } },
+  styleProps: ['gap'] as const, // gap="2x" becomes a style
+  modProps: ['isRaised'] as const, // isRaised becomes a mod (data-is-raised)
+  tokenProps: ['accentColor'] as const, // accentColor sets the #accent token
+  variants: {
+    plain: { border: 0 },
+    framed: { border: '2bw #accent' },
+  },
+  variant: 'framed', // applied when no variant prop is passed
+  elements: { Footer: 'footer' },
+});
+
+<ActionCard gap="2x" isRaised accentColor="#purple">
+  <ActionCard.Title>Kept from Card</ActionCard.Title>
+  <ActionCard.Footer>Added here</ActionCard.Footer>
+</ActionCard>;
+```
+
+The extension turns its own `styleProps`, `modProps`, and `tokenProps` into the `styles`, `mods`, and `tokens` it passes to the base, which renders them as usual: mods as `data-*` attributes, tokens as inline custom properties. Its `variants` merge over its `styles`, and the `variant` prop is still forwarded, so it selects the base's own variants too and accepts either set's names. Both sets share that one prop, so a name only one of them defines leaves the other at its fallback: if `Card` had an `accent` variant, `variant="accent"` would apply it together with `framed`, and `variant="plain"` would leave `Card` on its default. For two independent choices, give one of them its own prop, such as a `modProps` value list. `elements` adds sub-components, and the base's are kept: `ActionCard.Title` is `Card.Title`. The returned component is typed with all of these props and sub-components.
+
 `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
@@ -68,7 +92,7 @@ const Span = tasty({
 </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.
+The wrapped component only needs to forward `className` (and ideally `style`/`ref`). Tasty's own props (`styles`, `mods`, `tokens`, `qa`, `qaVal`, `theme`, `element`, the `is*` props) and the props you declared with `styleProps`, `modProps`, or `tokenProps` are consumed by Tasty; mods, `qa`, `qaVal`, `theme`, and `element` reach the DOM only as `data-*` attributes.
 
 Props forwarded to the `as` component keep their declared types and requiredness. For example, a component with `position: 'top-right' | 'bottom-left'` accepts those values through `tasty({ as: Component })`; CSS positioning can still be set through `styles.position`. A prop explicitly listed in `styleProps` is consumed as a style value instead. The always-available base style props below are also consumed by Tasty, so keep component-specific prop names separate from those reserved names.
 
@@ -112,12 +136,12 @@ A small set of style properties — `display`, `font`, `preset`, `hide`, `whiteS
 
 ## `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.
+`Element` is the unstyled base component exported from the main entry — equivalent to `tasty({})` (a `div` with no default styles). It accepts the props every Tasty component has (`as`, `styles`, `mods`, `tokens`, `qa`, `theme`, the `is*` props) plus the [always-available style props](#always-available-style-props), and is useful as a generic box or as a building block for layout primitives. Other style names, such as `padding`, are not props on it: create a component with `styleProps` for those, or pass them through `styles`.
 
 ```jsx
 import { Element } from '@tenphi/tasty';
 
-<Element as="section" padding="4x" fill="#surface">
+<Element as="section" display="grid" preset="t2" styles={{ padding: '4x' }}>
   Content
 </Element>;
 ```
@@ -144,6 +168,7 @@ List modifier key names. Types default to `ModValue` (`boolean | string | number
 
 ```jsx
 const Button = tasty({
+  as: 'button',
   modProps: ['isLoading', 'isSelected'] as const,
   styles: {
     fill: { '': '#surface', isLoading: '#surface.5' },
@@ -161,6 +186,7 @@ Map modifier names to type descriptors for precise TypeScript types:
 
 ```tsx
 const Button = tasty({
+  as: 'button',
   modProps: {
     isLoading: Boolean, // isLoading?: boolean
     isSelected: Boolean, // isSelected?: boolean
@@ -297,6 +323,24 @@ const Button = tasty({
 <Button variant="danger">Delete</Button>;
 ```
 
+With `variant` omitted, or set to a key `variants` does not define, the `default` variant applies; without a `default` key only the base `styles` apply. `variant` is typed from the variant keys.
+
+To fall back to another variant instead, name it in the `variant` option:
+
+```jsx
+const Button = tasty({
+  styles: { padding: '2x 4x' },
+  variants: {
+    primary: { fill: '#blue', color: '#white' },
+    danger: { fill: '#red', color: '#white' },
+  },
+  variant: 'primary',
+});
+
+<Button>Save</Button>; // primary
+<Button variant="danger">Delete</Button>;
+```
+
 ### Extending Variants with Base State Maps
 
 When base `styles` contain an extend-mode state map (an object **without** a `''` key), it is applied **after** the variant merge. This lets you add or override states across all variants without repeating yourself:
@@ -362,7 +406,7 @@ elements: {
 }
 ```
 
-The sub-components produced by `elements` support `mods`, `tokens`, `isDisabled`, `isHidden`, and `isChecked` props — the same modifier interface as the root component.
+The sub-components produced by `elements` support `mods`, `tokens`, `theme`, `isDisabled`, `isHidden`, and `isChecked` props — the same modifier interface as the root component. As on the root, `theme` renders as `data-theme`, and an explicit `data-theme` wins over it.
 
 If you don't need sub-components (e.g., the inner elements are already rendered by a third-party library), you can still style them by key alone — just omit `elements` and apply `data-element` manually:
 
@@ -401,19 +445,19 @@ const { className } = computeStyles({
 });
 ```
 
-On the client, CSS is injected synchronously into the DOM (idempotent via the injector cache). On the server, CSS is collected via the SSR collector if one is available. This is the same function that `tasty()` components use internally.
+On the client, CSS is injected synchronously into the DOM (idempotent via the injector cache). On the server with an SSR collector (from `runWithCollector()` or `TastyRegistry`), the CSS goes to the collector. With neither a collector nor a `document` — a React Server Component — nothing is injected: the CSS comes back as `css`, and you render it in a `style` tag yourself, as `tasty()` components do. This is the same function that `tasty()` components use internally.
 
 ---
 
 ## Style Functions
 
-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.
+All style functions below work in client components, SSR with a `ServerStyleCollector`, and React Server Components. All except `useStyles()` are plain functions, not React hooks; they keep the `use` prefix for backward compatibility.
 
 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
 
-Generate a className from a style object. Thin wrapper around `computeStyles()`:
+Generate a className from a style object. A thin wrapper around `computeStyles()` that also picks up the `TastyRegistry` collector through React context. That makes it a hook on the client: call it inside a component, and use `computeStyles()` outside React. It also works in a Server Component, where it skips the context lookup; like the other style functions there, it cannot emit CSS itself, so the next `tasty()` element in the tree emits it.
 
 ```tsx
 import { useStyles } from '@tenphi/tasty';
@@ -447,6 +491,17 @@ function ThemeStyles() {
 }
 ```
 
+The selector can be a list (`'.uni-checkbox, uni-checkbox'`) — every item gets
+the states and sub-elements, with no `:is()` wrapping needed. Root states
+(`@root(...)`) on a selector that is the root itself (`:root`, `html`) apply to
+that element. A selector that ends in a pseudo-element takes its states on the
+pseudo-element (`'.card::before'` with `:hover` gives
+`.card::before:where(:hover)`) and `@parent()` on the element before it.
+Attribute and modifier states, which a pseudo-element can't have, are ignored
+with a warning. Local `@keyframes` are injected with the rules,
+under the same resolved names `tasty()` components use, and `@starting` states
+emit `@starting-style`.
+
 A slot — the `id`, or the selector when no `id` is given — holds exactly one
 injection **per `root`**. So:
 
@@ -475,6 +530,8 @@ 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.
 
+It also accepts a factory and deps — `useRawCSS(() => css, [deps], { id })` — and skips the factory while the deps for that `id` are unchanged.
+
 ### useKeyframes
 
 Inject `@keyframes` rules and return the generated animation name:
@@ -584,7 +641,11 @@ useFontFace('Brand Sans', [
 Signature:
 
 ```ts
-function useFontFace(family: string, input: FontFaceInput): void;
+function useFontFace(
+  family: string,
+  input: FontFaceInput,
+  options?: { root?: Document | ShadowRoot },
+): void;
 ```
 
 ### useCounterStyle
@@ -666,9 +727,10 @@ See the [Functions section of the DSL reference](dsl.md#functions-function) for
 
 - 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).
 - SSR output looks wrong: check the [SSR guide](ssr.md) for collector setup. All style functions discover the SSR collector via `AsyncLocalStorage` or the global getter registered by `TastyRegistry`.
+- "Server rendering without a style collector" in development: the server render has no request scope, so each `tasty()` element inlines its own CSS and configured globals are not emitted. Add `tastyIntegration()` (Astro), `TastyRegistry` (Next.js), or `runWithCollector()` — see the [SSR guide](ssr.md).
 - Animation/custom property issues: prefer `useKeyframes()` and `useProperty()` over raw CSS when you want Tasty to manage injection and SSR collection for you.
 - For dynamic styles that change over the component lifecycle, use the `id` option in `useGlobalStyles()` and `useRawCSS()` to enable update tracking.
-- RSC inline mode: CSS accumulated by standalone style functions (`useGlobalStyles`, `useRawCSS`, etc.) is flushed into inline `<style>` tags by the next `tasty()` component in the render tree. If your page uses only standalone style functions without any `tasty()` component, the CSS will not be emitted. Ensure at least one `tasty()` component is present in each RSC render tree.
+- RSC inline mode: CSS accumulated by standalone style functions (`useStyles`, `useGlobalStyles`, `useRawCSS`, etc.) is flushed into inline `<style>` tags by the next `tasty()` component in the render tree. If your page uses only standalone style functions without any `tasty()` component, the CSS will not be emitted. Ensure at least one `tasty()` component is present in each RSC render tree.
 
 ---
 
@@ -677,6 +739,7 @@ See the [Functions section of the DSL reference](dsl.md#functions-function) for
 - **[Style DSL](dsl.md)** — State maps, tokens, units, extending semantics, keyframes, @property
 - **[Methodology](methodology.md)** — Recommended patterns: root + sub-elements, styleProps, tokens, wrapping
 - **[Configuration](configuration.md)** — Tokens, recipes, custom units, style handlers, TypeScript extensions
+- **[Configuration → TypeScript](configuration.md#typescript)** — How props are typed and how to register your names
 - **[Style Properties](styles.md)** — Complete reference for all enhanced style properties
 - **[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

package/docs/upstream/tasty/docs/runtime-benchmarks.md

@@ -63,15 +63,15 @@ Single-call throughput, three consecutive runs on an Apple M3 Pro with Node
 | `renderStyles` — 5 flat properties (cold)                   |       143,000–158,000 |     6.3–7.0 us |
 | `renderStyles` — state map with media/hover/modifier (cold) |         31,000–36,000 |       28–32 us |
 | `renderStyles` — OR state map across contexts (cold)        |         13,000–14,000 |       71–76 us |
-| `renderStyles` — same styles (cached)                       |  9,830,000–10,420,000 |      \~0.10 us |
-| `parseStateKey` — simple key like `:hover` (cold)           |   1,910,000–1,980,000 |      \~0.50 us |
-| `parseStateKey` — value modifier key (cold)                 |   1,120,000–1,160,000 |      \~0.90 us |
+| `renderStyles` — same styles (cached)                       |  9,830,000–10,420,000 |       ~0.10 us |
+| `parseStateKey` — simple key like `:hover` (cold)           |   1,910,000–1,980,000 |       ~0.50 us |
+| `parseStateKey` — value modifier key (cold)                 |   1,120,000–1,160,000 |       ~0.90 us |
 | `parseStateKey` — complex OR/AND/NOT key (cold)             |       341,000–357,000 |     2.8–2.9 us |
-| `parseStateKey` — any key (cached)                          |  4,900,000–16,530,000 |   0.10–0.20 us |
-| `parseStyle` — value tokens like `2x 4x` (cold)             |       575,000–605,000 |       \~1.7 us |
-| `parseStyle` — color tokens (cold)                          |   1,160,000–1,240,000 |   0.80–0.90 us |
+| `parseStateKey` — any key (cached)                          |  4,900,000–16,530,000 |    0.10–0.20 us |
+| `parseStyle` — value tokens like `2x 4x` (cold)             |       575,000–605,000 |       ~1.7 us |
+| `parseStyle` — color tokens (cold)                          |   1,160,000–1,240,000 |    0.80–0.90 us |
 | `parseStyle` — layered functions (cold)                     |       175,000–184,000 |     5.4–5.7 us |
-| `parseStyle` — any value (cached)                           | 29,500,000–30,750,000 |      \~0.03 us |
+| `parseStyle` — any value (cached)                           | 29,500,000–30,750,000 |      ~0.03 us |
 
 “Cold” cases use unique inputs to bypass the relevant caches. Cached cases
 reuse one input and measure the LRU hot path. Run-to-run spread on an idle
@@ -80,9 +80,9 @@ cold cases. 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`](https://github.com/tenphi/tasty/blob/v3.9.10/src/pipeline/pipeline.bench.ts),
-[`parseStateKey.bench.ts`](https://github.com/tenphi/tasty/blob/v3.9.10/src/pipeline/parseStateKey.bench.ts), and the
-parser benchmark files under [`src/parser`](https://github.com/tenphi/tasty/blob/v3.9.10/src/parser).
+[`pipeline.bench.ts`](https://github.com/tenphi/tasty/blob/main/src/pipeline/pipeline.bench.ts),
+[`parseStateKey.bench.ts`](https://github.com/tenphi/tasty/blob/main/src/pipeline/parseStateKey.bench.ts), and the
+parser benchmark files under [`src/parser`](https://github.com/tenphi/tasty/tree/main/src/parser).
 
 ## Empty Wrapper Overhead
 
@@ -91,7 +91,7 @@ Skipping the style pipeline does not make a `tasty()` component free. Even
 tracks another fiber, and Tasty still processes and forwards the element's
 props.
 
-[`tasty-overhead.bench.tsx`](https://github.com/tenphi/tasty/blob/v3.9.10/src/tasty-overhead.bench.tsx) compares 10,000
+[`tasty-overhead.bench.tsx`](https://github.com/tenphi/tasty/blob/main/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.
@@ -106,16 +106,16 @@ sample. This does not estimate React's concurrent scheduling latency.
 On an Apple M3 Pro with React 19.2.8 and Chromium 151, three consecutive runs
 produced these ranges:
 
-| Work on 10,000 siblings             | Raw elements |  `tasty({})` | Extra per wrapped element |
-| ----------------------------------- | -----------: | -----------: | ------------------------: |
-| Mount + remove                      |   4.2–4.3 ms |   9.2–9.7 ms |              0.50–0.54 us |
-| Rerender, same host props           |   1.2–1.3 ms |   6.3–6.5 ms |              0.51–0.52 us |
-| Rerender, change one host attribute |   2.5–2.7 ms | 11.2–11.6 ms |              0.86–0.91 us |
+| Work on 10,000 siblings             | Raw elements | `tasty({})` | Extra per wrapped element |
+| ----------------------------------- | -----------: | ----------: | ------------------------: |
+| Mount + remove                      |   4.2–4.3 ms |  9.2–9.7 ms |              0.50–0.54 us |
+| Rerender, same host props           |   1.2–1.3 ms |  6.3–6.5 ms |              0.51–0.52 us |
+| Rerender, change one host attribute |   2.5–2.7 ms | 11.2–11.6 ms |             0.86–0.91 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 0.5 us per
-participating element, or \~0.9 us when React also changes a DOM attribute.
+participating element, or ~0.9 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,
@@ -125,18 +125,18 @@ snapshot experiment with controlled garbage collection.
 
 ## Cold Generation and Injection
 
-[`tasty-injection.bench.ts`](https://github.com/tenphi/tasty/blob/v3.9.10/src/tasty-injection.bench.ts) measures the extra
+[`tasty-injection.bench.ts`](https://github.com/tenphi/tasty/blob/main/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
+- **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
+- **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.
@@ -197,11 +197,11 @@ The benchmarks above measure mounting and whole-tree updates. A running
 application spends most of its time on neither. It flips mods — hovered,
 pressed, selected, expanded — on elements whose styles never change, one
 element at a time, and it mounts and unmounts small styled subtrees as menus
-and dialogs open. Both paths go through the state-map and ref-counting
-machinery rather than the parser, so a regression in them is invisible to every
+and dialogs open. Both paths go through mod handling and the chunk cache
+rather than the parser, so a regression in them is invisible to every
 other benchmark here.
 
-[`tasty-interaction.bench.tsx`](https://github.com/tenphi/tasty/blob/v3.9.10/src/tasty-interaction.bench.tsx) pairs each
+[`tasty-interaction.bench.tsx`](https://github.com/tenphi/tasty/blob/main/src/tasty-interaction.bench.tsx) pairs each
 case with a raw-DOM equivalent driven by a hand-written stylesheet that
 produces the same computed color and background in both states. The benchmark
 fails if either arm resolves to anything else, so an arm that quietly rendered
@@ -216,12 +216,12 @@ performs 20 open/close cycles. Divide the raw/Tasty difference by those counts.
 Two things had to be sized deliberately, and both are the difference between a
 readable number and noise:
 
-* **The tree is small (100 elements), not large.** React locates a leaf's
+- **The tree is small (100 elements), not large.** React locates a leaf's
   pending update by walking the sibling list, so in a 1,000-element tree a
-  single-element update costs \~68 us of traversal — identical in both arms and
+  single-element update costs ~68 us of traversal — identical in both arms and
   an order of magnitude above anything the styling layer contributes.
-* **The sample resolves style once, not once per flip.** Forcing a recalc
-  between flips costs \~70 us in both arms, which buries the delta the same way.
+- **The sample resolves style once, not once per flip.** Forcing a recalc
+  between flips costs ~70 us in both arms, which buries the delta the same way.
   The browser's side of an interaction is real, but it is the browser's;
   resolution boundaries are what the injection benchmark above measures.
 
@@ -235,7 +235,7 @@ On an Apple M3 Pro with React 19.2.8 and Chromium 151, three consecutive runs:
 | Workload                                             | Raw elements | Tasty mods |           Extra per unit |
 | ---------------------------------------------------- | -----------: | ---------: | -----------------------: |
 | 300 single-element mod toggles in a 100-element tree |   1.7–1.8 ms | 2.0–2.1 ms | 1.2–1.3 us / interaction |
-| 20 mount + unmount cycles of a 200-element subtree   |   5.2–5.4 ms | 8.3–8.6 ms |   0.77–0.81 us / element |
+| 20 mount + unmount cycles of a 200-element subtree    |   5.2–5.4 ms | 8.3–8.6 ms |   0.77–0.81 us / element |
 
 The absolute columns move several percent with machine load; the delta between
 the arms is the stable quantity, so read that rather than either column.
@@ -245,29 +245,29 @@ Two things are worth reading out of this.
 A mod flip on an already-mounted element costs about 1.2 us. The CSS for both
 states already exists — Tasty emits every state of a style map in one chunk on
 first render — so both arms perform the same commit, and what is left is
-Tasty's props and mod handling. That is the same order as the \~0.5 us empty
+Tasty's props and mod handling. That is the same order as the ~0.5 us empty
 wrapper measured above, which is most of where it comes from.
 
-Subtree churn is not about styling at all. Its \~0.8 us per element sits right
+Subtree churn is not about styling at all. Its ~0.8 us per element sits right
 on the empty-wrapper mount cost, because the styles are already cached:
 reopening a menu re-pays the React wrapper, not the style pipeline.
 
 ## Page-Load Cold Start
 
 Every benchmark above deliberately excludes the network, module compilation and
-the first render. [`scripts/cold-start`](https://github.com/tenphi/tasty/blob/v3.9.10/scripts/cold-start) measures exactly
+the first render. [`scripts/cold-start`](https://github.com/tenphi/tasty/tree/main/scripts/cold-start) measures exactly
 those: what a visitor waits for between requesting a page and seeing styled
 content, in a real Chromium under CDP network and CPU throttling.
 
 Three pages render the same 50 styled components and are verified, before any
 timing, to produce the same 50 elements at the same computed color:
 
-* **baseline** — the components server-rendered: identical markup, identical
+- **baseline** — the components server-rendered: identical markup, identical
   class names, a linked stylesheet, and no Tasty on the page. Every other
   column is a delta against this one.
-* **runtime** — Tasty generates the CSS in the browser, as a client-rendered
+- **runtime** — Tasty generates the CSS in the browser, as a client-rendered
   application does. The run asserts it really did (69 rules generated).
-* **prewarm** — the same, after one throwaway `computeStyles()` against a
+- **prewarm** — the same, after one throwaway `computeStyles()` against a
   detached root before the first component renders.
 
 Each cell is the median of 5 uncached loads in a fresh browser context. The run
@@ -279,14 +279,14 @@ painted yet.
 Two things about the payload decide whether this measures a deployment or a
 straw man, so both are enforced rather than assumed:
 
-* **Assets are served brotli-compressed**, the way a static host serves them.
+- **Assets are served brotli-compressed**, the way a static host serves them.
   The bundle is 51.5 KB on the wire and 180 KB decoded; putting the decoded
-  bytes on a 1.6 Mbps link would add \~700 ms and charge it to Tasty. The run
+  bytes on a 1.6 Mbps link would add ~700 ms and charge it to Tasty. The run
   reads `encodedBodySize` back out of resource timing and fails if what
   crossed the wire is not the compressed size the table reports.
-* **The bundle is built from what the page imports** (`tasty`, `configure`,
+- **The bundle is built from what the page imports** (`tasty`, `configure`,
   `computeStyles`, `tastyDebug`), so it is tree-shaken as an application's
-  would be. Re-exporting the whole library adds \~4 KB brotli of code no page
+  would be. Re-exporting the whole library adds ~4 KB brotli of code no page
   here calls.
 
 On an Apple M3 Pro with React 19.2.8 and Chromium 151, first contentful paint,
@@ -340,7 +340,7 @@ delivery models, not a thumb on the scale, but it means the FCP delta is not
 purely "what Tasty costs to execute".
 
 **Prewarming moves the wake-up, it does not remove it.** The first styled render
-is \~5.4 ms more expensive than the ones after it, because that is when the
+is ~5.4 ms more expensive than the ones after it, because that is when the
 engine's deferred payload is actually compiled. A throwaway `computeStyles()`
 against a detached root pays it early: `render 1st` drops from 7.3 ms to
 1.9 ms. The prewarm itself costs 3.3 ms, so the work is moved rather than
@@ -365,21 +365,21 @@ jitter.
 Do not add the microbenchmark numbers together to estimate an application
 blindly. They describe different paths:
 
-* A stable `tasty()` factory can skip the style pipeline on later renders, but
+- 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
+- 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
+- A genuinely new style pays generation and injection once, then becomes
   reusable.
-* A mod flip on an already-styled element pays neither; it is a class-name
-  change.
-* Browser style resolution, layout, and paint depend on the actual document and
+- A mod flip on an already-styled element pays neither; it toggles a `data-*`
+  attribute and the class stays the same.
+- Browser style resolution, layout, and paint depend on the actual document and
   need application-level profiling.
 
 The cold-start measurement is the one that puts the rest in proportion. On a
 slow connection, nearly all of Tasty's page-load cost is transferring the
 library — 263 ms of a 264 ms delta — while the generation and injection the
-microbenchmarks obsess over is \~10 ms for 50 components. Bundle size is
+microbenchmarks obsess over is ~10 ms for 50 components. Bundle size is
 therefore the lever with the largest effect on first paint, and the runtime
 levers matter for what happens after it.