@tenphi/cookbook 0.21.1 → 0.21.2

package/docs/upstream/tasty/docs/getting-started.md

@@ -169,20 +169,22 @@ export default [
 
 ### What `recommended` catches
 
-The `recommended` config enables 18 of the plugin's 27 total rules. It covers the most common issues without turning on the stricter governance rules:
-
-| Category            | Rules                                                                                                  | Examples                                                     |
-| ------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ |
-| Property validation | `known-property`, `valid-boolean-property`, `valid-sub-element`                                        | Flags typos like `pading` or invalid boolean usage           |
-| Value validation    | `valid-value`, `valid-color-token`, `valid-custom-unit`                                                | Catches `#nonexistent` tokens, bad unit syntax               |
-| State validation    | `valid-state-key`, `no-nested-state-map`, `require-default-state`                                      | Validates state key syntax, ensures `''` default exists      |
-| Structure           | `valid-styles-structure`, `no-important`, `no-nested-selector`                                         | Prevents `!important`, invalid nesting                       |
-| Static mode         | `static-no-dynamic-values`, `static-valid-selector`                                                    | Enforces build-time constraints in `tastyStatic()`           |
-| Style properties    | `valid-preset`, `valid-recipe`, `valid-transition`, `valid-directional-modifier`, `valid-radius-shape` | Validates preset names, recipe references, transition syntax |
+The `recommended` config covers common correctness and style issues:
+
+| Category            | Rules                                                                                                  | Examples                                                              |
+| ------------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
+| Property validation | `known-property`, `valid-boolean-property`, `valid-sub-element`                                        | Flags typos like `pading` or invalid boolean usage                    |
+| Value validation    | `valid-value`, `valid-color-token`, `valid-custom-unit`                                                | Catches `#nonexistent` tokens, bad unit syntax                        |
+| State validation    | `valid-state-key`, `no-nested-state-map`, `require-default-state`                                      | Validates state key syntax, ensures `''` default exists               |
+| Structure           | `valid-styles-structure`, `no-important`, `no-nested-selector`                                         | Prevents `!important`, invalid nesting                                |
+| Static mode         | `static-no-dynamic-values`, `static-valid-selector`                                                    | Enforces build-time constraints in `tastyStatic()`                    |
+| Style properties    | `valid-preset`, `valid-recipe`, `valid-transition`, `valid-directional-modifier`, `valid-radius-shape` | Validates preset names, recipe references, transition syntax          |
+| Motion guidance     | `no-raw-transition-duration`                                                                           | Suggests timing tokens or the default timing for transition durations |
+| Dynamic styles      | `no-runtime-styles-mutation`, `no-style-spread`                                                         | Warns on JavaScript values and spreads inside runtime style objects   |
 
 ### Strict config
 
-For stricter governance, use `tasty.configs.strict`. It adds rules that enforce best practices like preferring shorthand properties, consistent token usage, and flagging direct `styles` prop usage:
+For stricter governance, use `tasty.configs.strict`. It adds rules that flag direct `styles` prop usage and other patterns:
 
 ```js
 export default [tasty.configs.strict];

package/docs/upstream/tasty/docs/methodology.md

@@ -236,7 +236,7 @@ const ProgressBar = tasty({
       width: '$progress',
       height: '100%',
       fill: '#primary',
-      transition: 'width 0.3s',
+      transition: 'width',
     },
   },
   elements: { Bar: 'div' },
@@ -534,7 +534,7 @@ See [Configuration](configuration.md) for the full `configure()` API.
 
 - **Create styled wrappers** instead of passing `styles` directly — faster, composable, inspectable
 - **Use design tokens and custom units** (`#text`, `2x`, `1r`) instead of raw CSS values
-- **Use semantic transition names** (`transition: 'theme 0.3s'`) instead of listing CSS properties
+- **Use semantic transition names** (`transition: 'theme'`) instead of listing CSS properties; omit the duration to use the motion tokens
 - **Use `elements` prop** to declare typed sub-components for compound components
 - **Use `styleProps`** to define what product engineers can customize
 - **Use `modProps`** to expose known modifier states as clean component props

package/docs/upstream/tasty/docs/pipeline.md

@@ -2,7 +2,7 @@
 
 This document describes the style rendering pipeline that transforms style objects into CSS rules. The pipeline ensures that each style value is applied to exactly one condition through exclusive condition building, boolean simplification, and intelligent CSS generation.
 
-**Implementation:** [`src/pipeline/`](https://github.com/tenphi/tasty/blob/v3.8.0/src/pipeline) — TypeScript file names below are relative to that directory.
+**Implementation:** [`src/pipeline/`](https://github.com/tenphi/tasty/blob/v3.9.6/src/pipeline) — TypeScript file names below are relative to that directory.
 
 ## Overview
 
@@ -86,18 +86,22 @@ Output: CSSRule[]
 
 ### What It Does
 
-Runs on each style's value map **before** any parsing. If a compound AND state key shares a value with the "atom absent" variant, the atom is a don't-care and every key is simplified by dropping it. Duplicate keys collapse.
+Runs on each style's value map **before** any parsing, when the map has at least three keys and one of them uses `&`. An atom is a **don't-care** when flipping it never changes which value the map resolves to; every key that mentions a don't-care atom is dropped.
 
 ### How It Works
 
-1. Gather the unique set of top-level AND atoms across all keys.
-2. An atom is **redundant** when every entry that contains it has a same-value partner with the atom absent and the rest of the atoms identical.
-3. Keys containing `|`, `^`, or `,` at top level are treated as opaque single atoms (they don't participate in atom-level extraction).
-4. Drop redundant atoms from every key; collapse duplicates.
+1. Split each key into its top-level `&` atoms. Keys containing `|`, `^`, or `,` at top level are a single opaque atom. The `_` floor (and a misused `_` key) is kept verbatim and left out of the analysis.
+2. Treat the map as the cascade it is: the last authored key whose atoms all hold wins, and `''` is always the lowest priority.
+3. An atom is a don't-care when, in every state, the cascade resolves to the same value with the atom present as with it absent. Only the states `(K₁ minus the atom) ∪ K₀`, for every key `K₁` that contains the atom and every key `K₀` that does not (or none), can tell the two apart, so the check is quadratic in the number of keys rather than exponential in atoms.
+4. Drop every key that contains a don't-care atom. With the atom forced absent those keys never match, and by definition the result is unchanged.
+
+The check is over the cascade, not over pairs of keys. In `{ '': A, checked: B, 'invalid & checked': C, disabled: A }`, `disabled` has the default's value, but it outranks `checked`: a checked, disabled element gets `A`, so `disabled` is not a don't-care. (An earlier pairwise rule — "every key with the atom has a same-value partner without it" — folded `disabled` into `''` here and lost that priority.)
+
+Atoms are compared as strings and treated as independent. Real atoms can be related (`theme=dark` vs `theme=light`, nested media ranges); that only rules states out, so a don't-care over independent atoms is one for every real state too. Two guards keep the rewrite safe: a map with more than 32 distinct atoms is left unreduced, and a reduction that would leave the `_` floor alone with `''` (which means "use the floor", see Stage 1) is skipped.
 
 ### Why
 
-Removing don't-care dimensions before parsing prevents combinatorial blowup in later stages. `mergeEntriesByValue`, `buildExclusiveConditions`, and materialization all see fewer entries and fewer spurious conditions. Implemented as part of the Apr 2026 fix for overlapping CSS rules (commit 7cd9dbe).
+Removing don't-care dimensions before parsing prevents combinatorial blowup in later stages. `mergeEntriesByValue`, `buildExclusiveConditions`, and materialization all see fewer entries and fewer spurious conditions.
 
 ### Example
 
@@ -200,6 +204,8 @@ simplify(C_m & C_l & !C_h) = FALSE
 
 i.e. there is no scenario where the intermediate state could have matched, the lower same-value entry would also have matched, and the higher one would not. This is the only way the merge could leak through and shadow the intermediate state.
 
+An intermediate whose condition always holds (a tautological key, or same-value keys that already merged into one, like `beta | !beta`) is checked like any other. Only the `''` default and the `_` floor are exempt from the check, and they are always the lowest priorities, so they are never intermediates.
+
 ### Why
 
 Without this pass a value map like `{ '@dark': 'red', '@dark & @hc': 'red' }` would create two separate entries that later produce two CSS rules with identical output. Merging before exclusive building keeps the exclusive condition algebra small and avoids duplicate CSS. The safety check ensures we never break the cascade in service of this optimization.
@@ -298,7 +304,9 @@ B: B & !A               (applies only when A doesn't)
 C: C & !A & !B          (applies only when neither A nor B)
 ```
 
-Each exclusive condition is passed through `simplifyCondition`. Entries that simplify to `FALSE` (impossible) are filtered out. The default state (`''` → `TrueCondition`) is not added to the “prior” list for negation (see `buildExclusiveConditions`).
+Each exclusive condition is passed through `simplifyCondition`. Entries that simplify to `FALSE` (impossible) are filtered out.
+
+Every entry is added to the "prior" list, including one whose condition is `TRUE`. That can be a tautological key, or same-value keys that merged into one in Stage 1b (`alpha: X, '!alpha': X` → `TRUE`). Such an entry always applies at its priority, so negating it correctly makes every lower entry `FALSE`. The bare `''` default is `TRUE` too, but it is always the lowest priority, so no entry comes after it.
 
 ### `_` fallback floor
 
@@ -389,7 +397,7 @@ The pre-build Stage 2a pass doesn't need this because user-authored ORs aren't p
 
 ### Example (conceptual)
 
-See the comment block in `exclusive.ts:500-523`: a default value whose higher-priority sibling is `@supports(...) & :has(...)` gets an exclusive of `!@supports | !:has`. Expansion yields one branch under `@supports (not ...)` and another under `@supports (...) { :not(:has()) }` instead of a bare `:not(:has())` rule.
+See the comment block on `expandExclusiveOrs` in `exclusive.ts`: a default value whose higher-priority sibling is `@supports(...) & :has(...)` gets an exclusive of `!@supports | !:has`. Expansion yields one branch under `@supports (not ...)` and another under `@supports (...) { :not(:has()) }` instead of a bare `:not(:has())` rule.
 
 ***
 
@@ -401,6 +409,8 @@ See the comment block in `exclusive.ts:500-523`: a default value whose higher-pr
 
 Computes the Cartesian product of all style entries for a handler, creating snapshots of which value each style has for each possible state combination.
 
+When every input is a direct value rather than a state map, the pipeline skips stages 0–4 and passes one unconditional snapshot directly to the handler. This avoids building exclusive entries and a Cartesian product for ordinary state-free styles.
+
 ### How It Works
 
 1. Collect exclusive entries for each style the handler uses
@@ -460,6 +470,7 @@ Style handlers encapsulate the logic for translating design tokens (like `'2x'`)
 ### What It Does
 
 Combines rules that have identical CSS output into a single rule with an OR condition.
+Zero- and one-rule inputs return unchanged because no merge is possible.
 
 ### How It Works
 
@@ -747,3 +758,16 @@ Impossible combinations are detected at multiple levels (simplification, variant
 ### 4. Aggressive Caching
 
 Parse, simplify, condition-to-CSS, and full-pipeline results are cached independently, enabling fast re-rendering when only parts of the style object change.
+
+Cache keys must respect key order where it carries meaning. A state map resolves by key order, so `{ '': A, checked: B, disabled: C }` and `{ '': A, disabled: C, checked: B }` are different styles and must get different keys (and classes). Only the style keys of a styles object, including a sub-element's, are order-insensitive, so they may be sorted. `stringifyStyles` (pipeline cache) and `generateChunkCacheKey` (class allocation) both follow this rule.
+
+***
+
+## Testing Priority
+
+Every stage above is an optimization that must leave one thing unchanged: in any state, the value that applies is the value of the last authored key whose condition holds. `src/test/state-oracle.ts` states that rule directly, with none of the pipeline's machinery, and two suites compare the pipeline against it:
+
+* `src/pipeline/exclusive.test.ts` (Node) evaluates the conditions after each of Stages 0–3 on thousands of generated maps, and names the stage that disagrees.
+* `src/pipeline/state-priority.test.ts` (browser) renders hand-written, permuted, and generated maps to CSS, applies every combination of states (modifiers, value modifiers, `:has()`, `@root`, `@parent`, `@own`, media, supports), and compares what the browser computes against the oracle. It also checks that rules stay mutually exclusive, which a correct computed value alone can hide. It runs through the pipeline, the runtime injector, and the SSR collector, with all maps mounted at once so a cache-key collision shows up.
+
+A change to any stage should keep both green. When a generated map fails, the message includes the map, the failing states, and the CSS; the map is usually worth adding to the hand-written cases once it is reduced.

package/docs/upstream/tasty/docs/plugins.md

@@ -246,7 +246,7 @@ function glazeStyles(value: GlazeValue): Styles {
     styles = Object.freeze({
       '#glaze-bg': `#${tone}.${intensity}`,
       fill: '#glaze-bg',
-      transition: 'fill 0.2s',
+      transition: 'fill',
     }) as Styles;
     cache.set(key, styles);
   }

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

@@ -40,32 +40,49 @@ of elements, rules or interactions. Machine load, browser versions, and CPU
 power will move the results — on a loaded machine the absolute columns drift
 several percent while the raw/Tasty delta holds, so read the delta.
 
+**On a laptop, check the power state first.** Low Power Mode caps CPU frequency,
+and it is the single largest source of error here — larger than background load.
+Measured on the machine below, running on battery with Low Power Mode enabled
+made every one of the 53 Node cases slower, by a median of 26%, and halving the
+background load recovered only 3 points of that. A frequency cap scales every
+case by roughly the same factor, so it does not look like noise; it looks like a
+uniformly slower library. Verify before trusting a run:
+
+```bash
+pmset -g ps | head -2      # want 'AC Power'
+pmset -g | grep -i lowpowermode   # want 0
+```
+
 ## Core Style Pipeline
 
-The following numbers are single-call throughput measured on an Apple M1 Max
-with Node 22:
+Single-call throughput, three consecutive runs on an Apple M3 Pro with Node
+24.18.0 on AC power:
 
 | 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 |
+| `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 |
+| `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 |
+| `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 |
 
 “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.
+reuse one input and measure the LRU hot path. Run-to-run spread on an idle
+machine was 1–7% for most cases, rising to 10–16% for the two `renderStyles`
+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.8.0/src/pipeline/pipeline.bench.ts),
-[`parseStateKey.bench.ts`](https://github.com/tenphi/tasty/blob/v3.8.0/src/pipeline/parseStateKey.bench.ts), and the
-parser benchmark files under [`src/parser`](https://github.com/tenphi/tasty/blob/v3.8.0/src/parser).
+[`pipeline.bench.ts`](https://github.com/tenphi/tasty/blob/v3.9.6/src/pipeline/pipeline.bench.ts),
+[`parseStateKey.bench.ts`](https://github.com/tenphi/tasty/blob/v3.9.6/src/pipeline/parseStateKey.bench.ts), and the
+parser benchmark files under [`src/parser`](https://github.com/tenphi/tasty/blob/v3.9.6/src/parser).
 
 ## Empty Wrapper Overhead
 
@@ -74,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.8.0/src/tasty-overhead.bench.tsx) compares 10,000
+[`tasty-overhead.bench.tsx`](https://github.com/tenphi/tasty/blob/v3.9.6/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.
@@ -86,19 +103,19 @@ 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
+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.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 |
+| 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 1 us per
-participating element, or 1.2–1.3 us when React also changes a DOM attribute.
+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.
 
 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,
@@ -108,7 +125,7 @@ snapshot experiment with controlled garbage collection.
 
 ## Cold Generation and Injection
 
-[`tasty-injection.bench.ts`](https://github.com/tenphi/tasty/blob/v3.8.0/src/tasty-injection.bench.ts) measures the extra
+[`tasty-injection.bench.ts`](https://github.com/tenphi/tasty/blob/v3.9.6/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.
 
@@ -143,17 +160,23 @@ 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 |
+| One new rule + immediate resolution, per transaction |          2.6–3.0 us | 102.8–107.0 us |         100.3–104.3 us |
+| 1,000 new rules + one resolution                     |        1.69–1.79 ms |   7.42–7.67 ms |           5.73–5.94 ms |
+| 1,000-rule workload, incremental cost per rule       |                   — |              — |             5.7–5.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
+about 55–59 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 17–18
 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 per-transaction single-rule figure is the one number here that engine work
+does not move: it is dominated by the browser's injection-to-resolution
+boundary, which is crossed once per rule regardless of how fast generation is.
+The 1,000-rule column, where Tasty's own generation dominates, is where engine
+changes show up.
+
 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
@@ -178,7 +201,7 @@ 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
 other benchmark here.
 
-[`tasty-interaction.bench.tsx`](https://github.com/tenphi/tasty/blob/v3.8.0/src/tasty-interaction.bench.tsx) pairs each
+[`tasty-interaction.bench.tsx`](https://github.com/tenphi/tasty/blob/v3.9.6/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
@@ -207,32 +230,32 @@ if the hovered rule is not already there. That a style map's states all ship in
 one chunk on first render is the premise of this case; if the hovered rule
 arrived lazily, the first sample would be timing injection.
 
-On an Apple M1 Max with React 19.2.8 and Chromium 151, across several runs:
+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 |   2.1–2.5 ms |   2.7–3.1 ms | 1.6–2.1 us / interaction |
-| 20 mount + unmount cycles of a 200-element subtree   |   7.6–8.0 ms | 12.6–12.7 ms |   1.22–1.27 us / element |
+| 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 |
 
 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.
 
 Two things are worth reading out of this.
 
-A mod flip on an already-mounted element costs about 2 us. The CSS for both
+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 \~1 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 \~1.25 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.8.0/scripts/cold-start) measures exactly
+the first render. [`scripts/cold-start`](https://github.com/tenphi/tasty/blob/v3.9.6/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.
 
@@ -257,7 +280,7 @@ 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.
-  The bundle is 52.0 KB on the wire and 186 KB decoded; putting the decoded
+  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
   reads `encodedBodySize` back out of resource timing and fails if what
   crossed the wire is not the compressed size the table reports.
@@ -266,35 +289,48 @@ straw man, so both are enforced rather than assumed:
   would be. Re-exporting the whole library adds \~4 KB brotli of code no page
   here calls.
 
-On an Apple M1 Max with React 19.2.8 and Chromium 151, first contentful paint:
+On an Apple M3 Pro with React 19.2.8 and Chromium 151, first contentful paint,
+median of three full runs of the matrix:
+
+| Link / CPU            | baseline | runtime | prewarm | Tasty's cost | noise |
+| --------------------- | -------: | ------: | ------: | -----------: | ----: |
+| No throttling, 1x     |    36 ms |   40 ms |   40 ms |        +4 ms |  0 ms |
+| Fast 4G, 1x           |   628 ms |  672 ms |  688 ms |       +44 ms | 20 ms |
+| Slow 4G, 1x           |  2044 ms | 2308 ms | 2308 ms |      +264 ms | 24 ms |
+| No throttling, 4x CPU |   112 ms |  144 ms |  144 ms |       +32 ms | 16 ms |
+| Fast 4G, 4x CPU       |   656 ms |  728 ms |  736 ms |       +72 ms |  4 ms |
+| Slow 4G, 4x CPU       |  2064 ms | 2360 ms | 2360 ms |      +296 ms |  8 ms |
+
+The `noise` column is not an estimate. The `baseline` page contains no Tasty at
+all, so its three samples should be identical; the spread they actually show is
+this cell's measurement error, and it applies to the other columns too.
 
-| Link / CPU            | baseline | runtime | prewarm | Tasty's cost |
-| --------------------- | -------: | ------: | ------: | -----------: |
-| No throttling, 1x     |    40 ms |   52 ms |   52 ms |       +12 ms |
-| Fast 4G, 1x           |   624 ms |  680 ms |  676 ms |       +56 ms |
-| Slow 4G, 1x           |  2028 ms | 2304 ms | 2304 ms |      +276 ms |
-| No throttling, 4x CPU |   148 ms |  196 ms |  196 ms |       +48 ms |
-| Fast 4G, 4x CPU       |   684 ms |  784 ms |  788 ms |      +100 ms |
-| Slow 4G, 4x CPU       |  2096 ms | 2416 ms | 2408 ms |      +320 ms |
+Read that column before any other. Only the Slow 4G rows carry a cost an order
+of magnitude above their own noise. The unthrottled 1x row (+4 ms) means "too
+small to measure this way", not "4 ms". And a single run is genuinely not
+enough here: taken alone, the first of these three runs put Fast 4G 1x at
++72 ms, which the median over three corrects to +44 ms.
 
-That is one full run of the matrix; a second moved every cell by a few percent.
+For the same reason, `prewarm` landing above `runtime` in the Fast 4G 1x row is
+noise, not a cost — the two modes differ only in when the engine compiles, and
+that difference is measured in the phase table below, not in FCP.
 
 **The cost is the bundle, not the work.** On Slow 4G the extra transfer alone
-accounts for 262 ms of the 276 ms FCP delta — nearly all of it. Everything
-Tasty then *does* is small by comparison:
+accounts for 263 ms of the 264 ms FCP delta — effectively all of it. Everything
+Tasty then *does* is small by comparison (median of three runs):
 
 | Phase (Slow 4G, 1x)     | baseline | runtime | prewarm |
 | ----------------------- | -------: | ------: | ------: |
-| js+css transfer         |  1420 ms | 1682 ms | 1681 ms |
-| module compile (shared) |   1.2 ms |  1.5 ms |  2.0 ms |
-| tasty top-level execute |        — |  1.2 ms |  0.9 ms |
-| `configure()`           |        — |  0.6 ms |  0.5 ms |
-| prewarm                 |        — |       — |  5.3 ms |
-| render 1st component    |   2.0 ms |  8.2 ms |  2.7 ms |
-| render 49 more          |   1.0 ms |  7.1 ms |  6.0 ms |
+| js+css transfer         |  1423 ms | 1686 ms | 1690 ms |
+| module compile (shared) |   3.5 ms |  3.3 ms |  3.0 ms |
+| tasty top-level execute |        — |  1.2 ms |  0.8 ms |
+| `configure()`           |        — |  0.6 ms |  0.4 ms |
+| prewarm                 |        — |       — |  3.3 ms |
+| render 1st component    |   3.0 ms |  7.3 ms |  1.9 ms |
+| render 49 more          |   1.3 ms |  5.2 ms |  3.8 ms |
 
 Importing Tasty costs about 1 ms of top-level execution; `configure()` costs
-half of one. The rest of the CPU delta — about 13 ms for 50 components — is
+half of one. The rest of the CPU delta — about 10 ms for 50 components — is
 generation and injection, which is the cost the injection benchmark isolates.
 
 One asymmetry is worth naming: the control links a render-blocking stylesheet
@@ -304,20 +340,21 @@ 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 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 8.2 ms to
-2.7 ms. The prewarm itself costs 5.3 ms, so FCP does not move. It is worth
-doing only when something else can overlap it, or when the first render is on a
-latency-critical path and the page has idle time before it.
+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
+removed and FCP does not move. It is worth doing only when something else can
+overlap it, or when the first render is on a latency-critical path and the page
+has idle time before it.
 
 **Retained heap.** After a forced collection, the runtime page holds about
-1,013 KB more than the control (2,632 KB vs 1,619 KB) for 50 components — the
+985 KB more than the control (2,605 KB vs 1,619 KB) for 50 components — the
 parser caches, the chunk cache, the injector's registry and the generated CSS.
 The control is not zero either; most of its 1.6 MB is React and the DOM.
 
 CPU throttling changes which line moves. At 4x, module compilation of the
-larger graph becomes visible (5.9 ms → 25 ms) where at 1x it is free: V8
+larger graph becomes visible (2.6 ms → 19 ms) where at 1x it is free: V8
 pre-parses at import and compiles lazily, so a slower CPU pays for code the
 faster one never fully compiled. Transfer numbers from the unthrottled cells
 are not worth reading — with no emulated link, resource timings are scheduling
@@ -341,8 +378,8 @@ blindly. They describe different paths:
 
 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 — 262 ms of a 276 ms delta — while the generation and injection the
-microbenchmarks obsess over is \~13 ms for 50 components. Bundle size is
+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
 therefore the lever with the largest effect on first paint, and the runtime
 levers matter for what happens after it.
 

package/docs/upstream/tasty/docs/ssr.md

@@ -506,7 +506,7 @@ const stream = await runWithCollector(collector, () =>
 | `@tenphi/tasty/ssr/next-config`                                                                                                                                                            | Next.js config wrapper: shared, content-hashed global stylesheet                                                                                                                                                |
 | `@tenphi/tasty/ssr/astro`                                                                                                                                                                  | Astro: `tastyIntegration`, `tastyMiddleware`                                                                                                                                                                    |
 | `@tenphi/tasty/ssr/astro-client`                                                                                                                                                           | Astro: client-side cache hydration (auto-injected by integration, or import manually)                                                                                                                           |
-| `@tenphi/tasty/ssr/astro-middleware`<br>`@tenphi/tasty/ssr/astro-middleware-static`<br>`@tenphi/tasty/ssr/astro-middleware-extract`<br>`@tenphi/tasty/ssr/astro-middleware-extract-static` | Astro: the middleware entrypoints `tastyIntegration()` registers via `addMiddleware()`. Exported so Astro can resolve them by specifier; you should not import them. For manual setups use `tastyMiddleware()`. |
+| `@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`
 

package/docs/upstream/tasty/docs/styles.md

@@ -37,6 +37,24 @@ Use these instead of their raw CSS counterparts:
 
 ## Layout
 
+### `overscrollBehavior`
+
+The native `overscrollBehavior` shorthand and its `overscrollBehaviorBlock`,
+`overscrollBehaviorInline`, `overscrollBehaviorX`, and `overscrollBehaviorY`
+longhands support `auto`, `contain`, `none`, and `chain`. The shorthand can set
+separate X and Y values, for example `overscrollBehavior: 'chain contain'`.
+
+`chain` allows scroll chaining to another scrollable area while suppressing
+boundary effects such as bounce. It requires browser support; use a feature
+query and a fallback floor when targeting browsers without it:
+
+```jsx
+overscrollBehaviorBlock: {
+  _: 'auto',
+  '@supports(overscroll-behavior-block: chain)': 'chain',
+}
+```
+
 ### `display`
 
 Standard CSS display values. Handled together with `hide`, `textOverflow`, `overflow`, and `whiteSpace` for priority resolution.
@@ -566,15 +584,17 @@ When easing is provided without a duration, the default timing variable is used
 | `zIndex` | `z-index` |
 | `inset` | `inset`, `top`, `right`, `bottom`, `left` |
 
-Default timing: `$transition` (or `${name}-transition` with `$transition` fallback per semantic name).
+When two entries cover the same property, an entry that names that one property wins over a group such as `theme`, in either order: `opacity 120ms ease-in-out, theme` keeps the opacity timing. Otherwise the later entry wins, as in CSS.
+
+Default timing: `$transition` (or `${name}-transition` with `$transition` fallback per semantic name). Prefer omitting the duration or using a duration token instead of repeating raw time values across components. Explicit zero can disable motion.
 
 ```jsx
-transition="theme 0.3s"
-transition="fill 0.2s, radius 0.3s"
-transition="fade 0.15s ease-in"
+transition="theme"
+transition="fill, radius"
+transition="fade $transition ease-in"
 transition="fill ease-in"           // easing without duration (uses default timing)
 transition="radius ease-in-out"     // easing keyword only
-transition="$$custom-prop 0.3s"     // custom property transition
+transition="$$custom-prop"          // custom property transition
 ```
 
 **Recognized easing keywords:** `ease`, `ease-in`, `ease-out`, `ease-in-out`, `linear`, `step-start`, `step-end`. CSS easing functions (`cubic-bezier(...)`, `steps(...)`, `linear(...)`) are also recognized.
@@ -583,6 +603,24 @@ If the name is not a semantic name, it is used as a literal CSS property name.
 
 ---
 
+### `animation`
+
+`animation` is the native CSS shorthand. Tasty parses tokens in its value and
+tracks local `@keyframes` names referenced by it, so it needs no custom style
+handler. Define a complete animation with the shorthand, using a configured
+duration token where appropriate (for example,
+`animation: 'pulse $animation-duration ease-in infinite'`).
+
+Use `animationDuration`, `animationTimeline`, `animationRange`, and other CSS
+longhands when changing just one part of an existing animation in a state or
+component extension. Setting `animation` resets omitted parts, including its
+timeline and range. The same principle applies to `transitionDuration` and
+other transition longhands when a base `transition` is already defined.
+`transitionBehavior` remains a separate CSS longhand; Tasty's semantic
+`transition` syntax covers name, timing, easing, and delay.
+
+---
+
 ## Scrollbar & Overflow
 
 ### `scrollbar`

package/docs/upstream/tasty/docs/tasty-static.md

@@ -489,7 +489,7 @@ const button = tastyStatic({
   radius: '1r',
   fill: '#gray.20',
   color: '#text',
-  transition: 'fill 0.15s',
+  transition: 'fill',
 });
 
 // Variants

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenphi/cookbook",
-  "version": "0.21.1",
+  "version": "0.21.2",
   "description": "Repository-native static documentation for Astro",
   "type": "module",
   "keywords": [
@@ -68,8 +68,8 @@
   "author": "Andrey Yamanov",
   "license": "MIT",
   "dependencies": {
-    "@tenphi/docs": "0.21.1",
-    "@tenphi/renderer": "0.21.1"
+    "@tenphi/docs": "0.21.2",
+    "@tenphi/renderer": "0.21.2"
   },
   "peerDependencies": {
     "astro": "^7.3.2"