@cube-dev/ui-kit 0.154.1 → 0.156.0

package/docs/tasty/migration-v3.md

@@ -0,0 +1,285 @@
+# Migration Guide: v2 → v3
+
+Everything that changes when you upgrade from `@tenphi/tasty` 2.x to 3.0, in the order you will hit it.
+
+Most of the work is mechanical renames — see the [search-and-replace cheat sheet](#search-and-replace-cheat-sheet) at the end. The parts that need real attention are the [directional shorthand](#2-directional-shorthand) rule and the [behavior changes](#8-behavior-changes-that-are-not-renames).
+
+- [At a glance](#at-a-glance)
+- [1. Styles-object keys](#1-styles-object-keys)
+- [2. Directional shorthand](#2-directional-shorthand)
+- [3. Config keys](#3-config-keys)
+- [4. Renamed exports](#4-renamed-exports)
+- [5. Removed exports](#5-removed-exports)
+- [6. Removed props](#6-removed-props)
+- [7. Moved subpath](#7-moved-subpath)
+- [8. Behavior changes that are not renames](#8-behavior-changes-that-are-not-renames)
+- [9. New in v3](#9-new-in-v3)
+- [Search-and-replace cheat sheet](#search-and-replace-cheat-sheet)
+- [Not changed](#not-changed)
+
+---
+
+## At a glance
+
+| v2.11 | v3.0 | Find it with |
+|---|---|---|
+| `'@properties': { … }` | `'@property': { … }` | `rg "'@properties'"` |
+| `'@fontFace': { … }` | `'@font-face': { … }` | `rg "'@fontFace'"` |
+| `'@counterStyle': { … }` | `'@counter-style': { … }` | `rg "'@counterStyle'"` |
+| `padding: '2x 4x top right'` | `padding: '2x top, 4x right'` | dev-mode console warning |
+| `fade: '3x 1x top bottom'` | `fade: '3x top, 1x bottom'` | dev-mode console warning |
+| `configure({ funcs })` | `configure({ functions })` | `rg "funcs"` |
+| `configure({ fontFace })` | `configure({ fontFaces })` | `rg "fontFace:"` |
+| `configure({ counterStyle })` | `configure({ counterStyles })` | `rg "counterStyle:"` |
+| `getCssText()` | `getCSSText()` | `rg "getCssText"` |
+| `getCssTextForNode()` | `getCSSTextForNode()` | `rg "getCssTextForNode"` |
+| `getCssTextForClasses()` | `getCSSTextForClasses()` | `rg "getCssTextForClasses"` |
+| `getGlobalFontFace()` | `getGlobalFontFaces()` | `rg "getGlobalFontFace\b"` |
+| `getGlobalCounterStyle()` | `getGlobalCounterStyles()` | `rg "getGlobalCounterStyle\b"` |
+| `getGlobalFunction()` | `getGlobalFunctions()` | `rg "getGlobalFunction\b"` |
+| `okhslFunc` / `okhstFunc` | `okhslFunction` / `okhstFunction` | `rg "okhs[lt]Func\b"` |
+| `CssOptions` | `CSSOptions` | `rg "CssOptions"` |
+| `ParserOptions.funcs` | `ParserOptions.functions` | `rg "funcs:"` |
+| `StyleParser#setFuncs()` | `StyleParser#setFunctions()` | `rg "setFuncs"` |
+| `ChunkInfo` (from `tastyDebug`) | `DebugChunkInfo` | `rg "ChunkInfo"` |
+| `@tenphi/tasty/next` | `@tenphi/tasty/zero/next` | `rg "tasty/next"` |
+| `getIsTestEnvironment()` | `isTestEnvironment()` | `rg "getIsTestEnvironment"` |
+| `hydrateTastyCache()` | `hydrateTastyClasses()` | `rg "hydrateTastyCache"` |
+
+---
+
+## 1. Styles-object keys
+
+At-rule keys now match the real CSS at-rule names Tasty already emits, so they are kebab-case rather than camelCase. The generated CSS is unchanged.
+
+```diff
+  const Card = tasty({
+    styles: {
+-     '@properties': { '$elevation': { syntax: '<number>' } },
+-     '@fontFace': { Inter: { src: 'url(/inter.woff2)' } },
+-     '@counterStyle': { dashes: { system: 'cyclic', symbols: '"—"' } },
++     '@property': { '$elevation': { syntax: '<number>' } },
++     '@font-face': { Inter: { src: 'url(/inter.woff2)' } },
++     '@counter-style': { dashes: { system: 'cyclic', symbols: '"—"' } },
+    },
+  });
+```
+
+`@keyframes` and `@starting` are unchanged — they were already spec-faithful.
+
+---
+
+## 2. Directional shorthand
+
+**This is the one change that can alter rendered CSS without a rename.** A style group that names direction modifiers now takes a **single** value, applied to every direction it names.
+
+The old form looked positional but never was: the parser buckets values and modifiers into separate arrays per comma group, so `'2x 4x top right'`, `'2x top 4x right'`, and `'top 2x right 4x'` were all the same input, and the pairing was decided by the order the *modifiers* happened to appear in. `'1x 2x right top'` and `'1x 2x top right'` produced different CSS, and `'1x 2x top top'` silently assigned `top` twice.
+
+Per-side values now come from comma-separated groups:
+
+```diff
+- padding: '2x 4x top right'
++ padding: '2x top, 4x right'
+
+- margin: 'right 1x top 2x'
++ margin: '1x right, 2x top'
+
+- inset: 'left 2x right 1x'
++ inset: '2x left, 1x right'
+
+- fade: '3x 1x top bottom'
++ fade: '3x top, 1x bottom'
+```
+
+Affects `padding`, `margin`, `inset`, `scrollMargin`, and `fade`. Extra values are ignored with a **development-mode warning** naming the offending value, so run your app in dev and watch the console — that is the reliable way to find every occurrence. Production is silent and never throws.
+
+**Unchanged:** single-value directional groups (`padding: '2x top'`, `'1x left right'`), every value-only CSS shorthand form (`padding: '1x 2x'`, `'1x 2x 3x 4x'`, and `fade: '3x 1x'` — a group that names no direction is unambiguous and keeps plain shorthand order), CSS-wide keywords, and the `longhand` modifier.
+
+`inset`'s `dock` modifier keeps its two-value form with sharper semantics: the first value applies to the named edge, the second to the perpendicular sides it spans, so `inset: '2x 4x bottom dock'` still gives `auto 32px 16px 32px`. A third value with `dock`, or a second value without it, now warns.
+
+---
+
+## 3. Config keys
+
+```diff
+  configure({
+-   funcs: { double: (groups) => `calc(2 * ${groups[0].output})` },
+-   fontFace: { Inter: { src: 'url(/inter.woff2)' } },
+-   counterStyle: { dashes: { system: 'cyclic', symbols: '"—"' } },
++   functions: { double: (groups) => `calc(2 * ${groups[0].output})` },
++   fontFaces: { Inter: { src: 'url(/inter.woff2)' } },
++   counterStyles: { dashes: { system: 'cyclic', symbols: '"—"' } },
+  });
+```
+
+`functions` is a single map holding both flavors, discriminated by value type:
+
+- **bare key + function value** → a parse-time function, called as `name(...)`
+- **`$$name` key + object value** → a declarative CSS `@function`, called as `$$name(...)`
+
+A key whose prefix doesn't match its value type is ignored with a development warning.
+
+> If you are coming from a pre-release build of v3, note the intermediate `function` config key never shipped. Upgraders from 2.x only ever wrote `funcs`.
+
+---
+
+## 4. Renamed exports
+
+**Raw-CSS family** — aligned on the `CSS` initialism already used by `useRawCSS` / `injectRawCSS` / `getRawCSSText`:
+
+- `getCssText()` → `getCSSText()`
+- `getCssTextForNode()` → `getCSSTextForNode()`
+- `StyleInjector#getCssTextForClasses()` → `getCSSTextForClasses()`
+- `CssOptions` → `CSSOptions`
+
+**Config getters** — pluralized to match their already-plural config keys:
+
+- `getGlobalFontFace()` → `getGlobalFontFaces()`
+- `getGlobalCounterStyle()` → `getGlobalCounterStyles()`
+- `getGlobalFunction()` → `getGlobalFunctions()`
+
+**Color functions** — aligned with the `useFunction` / `FunctionDefinition` family:
+
+- `okhslFunc` → `okhslFunction`
+- `okhstFunc` → `okhstFunction`
+- `createColorFunc(name, channelLabel, convert)` → `createColorFunc(name, convert, label?)` — the label is now an optional trailing argument used only to format development warnings
+
+**Parser** (`@tenphi/tasty/core`):
+
+- `ParserOptions.funcs` → `ParserOptions.functions`
+- `StyleParser#setFuncs()` → `StyleParser#setFunctions()`
+
+**Debug types:** the debug-local `ChunkInfo` is now `DebugChunkInfo`, so it no longer collides with the parser's `ChunkInfo`.
+
+---
+
+## 5. Removed exports
+
+| Removed | Use instead |
+|---|---|
+| `getIsTestEnvironment()` | `isTestEnvironment()` |
+| `hydrateTastyCache()` | `hydrateTastyClasses()` |
+| `customFunc()` | `configure({ functions })` |
+| `getGlobalFuncs()` | `getGlobalFunctions()` for `@function` definitions; the parse-function registry is internal |
+| `resetGlobalFuncs()` | `resetConfig()` |
+| `setGlobalPredefinedTokens()` | `configure({ replaceTokens })` |
+| `resetGlobalPredefinedTokens()` | `resetConfig()` |
+| `setMiddlewareTransferCache()` / `getMiddlewareTransferCache()` | internal; no replacement needed |
+| `clearWriterCache()` | internal test utility |
+| `DEFAULT_PLUGINS` | nothing — it was never consumed, and passing it to `configure({ plugins })` was a no-op. The default `okhsl`/`okhst` functions are registered automatically. |
+| `registerDefaultFunctions()` | internal bootstrap helper |
+| `warn()` / `deprecationWarning()` | internal helpers with no callers |
+| `Bucket` enum | parser-internal |
+| `Props` type | inline `Record<string, any>` |
+| `UseStylesOptions` | `useStyles()` takes `Styles \| undefined` directly |
+| `GlobalStyledProps` | its only member was the already-dead `breakpoints` prop |
+| duplicate `PropertyOptions` | the single `PropertyOptions` from `injector/types` |
+
+`getGlobalFuncs()` deserves a note: it returned the **live mutable internal registry**, and writing to it bypassed the parser's cache invalidation, so the write silently never took effect. If you were mutating it, move to `configure({ functions })`.
+
+---
+
+## 6. Removed props
+
+`css`, `block`, `inline`, and `breakpoints` are gone from `BaseProps` / `TastySpecificKeys`. All four were typed but never consumed — passing them did nothing in v2 either.
+
+---
+
+## 7. Moved subpath
+
+```diff
+- import { withTasty } from '@tenphi/tasty/next';
++ import { withTasty } from '@tenphi/tasty/zero/next';
+```
+
+The zero-runtime Next.js wrapper already lived under the `zero` namespace internally; the top-level `/next` path collided confusingly with `@tenphi/tasty/ssr/next`, which is a different integration.
+
+---
+
+## 8. Behavior changes that are not renames
+
+**Repeated `configure()` calls now merge.** `recipes`, `keyframes`, `properties`, `fontFaces`, `counterStyles`, and CSS `@function` definitions used to replace wholesale, so a design-system `configure()` followed by an application `configure()` silently dropped the design system's values. All of them now merge, with the later call winning on a key conflict — matching `tokens` and `globalStyles`, which already merged. If you were relying on a second call to *clear* a collection, use `resetConfig()`.
+
+`configure({ polyfills })` is now correctly rejected after the first render, like every sibling option, and shallow-merges so an unrelated later call cannot switch a polyfill off.
+
+**The `theme` prop is now implemented.** It maps to a `data-theme` attribute on the rendered element; previously it fell through and was spread onto the DOM raw. Augment `TastyThemeNames` for autocomplete.
+
+**`tasty(Component, options)` no longer leaks factory-only options.** `variants`, `elements`, `styleProps`, `modProps`, and `tokenProps` are stripped instead of being passed to the wrapped component as runtime props, matching the element factory.
+
+**Replacing a built-in style handler now warns.** Built-in handlers are shared across style names, so `configure({ handlers: { fill } })` also takes over `image` and the whole `background-*` family, and `configure({ handlers: { display } })` takes down `flow`, `gap`, `hide`, `overflow`, `whiteSpace`, and `textOverflow`. This was always true; what's new is that a development-mode warning now names exactly what was displaced. If you see it, either declare the whole group and delegate the rest to `styleHandlers.*`, or pick a narrower name. See [Plugins](plugins.md#custom-style-handlers).
+
+**Multi-dependency custom handlers are fixed.** A handler whose dependencies mixed known and unknown style names was invoked once per chunk with only *part* of its dependencies, and could emit stale CSS. Unknown names now join their handler's chunk, so it is invoked once with all of them. No built-in style moved, so no existing class name changes.
+
+**`isChecked` added to the root prop types.** It already worked at runtime; it was just missing from `BaseProps` / `AllBaseProps`.
+
+**The `okhsl`/`okhst` "expected 3 values" warning is now development-only** and follows the `[Tasty]` prefix convention: `[Tasty] okhsl(): expected 3 values (H S L), got: …`. It previously fired in production.
+
+---
+
+## 9. New in v3
+
+Nothing here is required to upgrade.
+
+- **CSS `@function` support** — reusable, parameterized functions via the `'@function'` styles key, the `useFunction` style function, or `configure({ functions })`. Works across client, SSR/RSC, and zero-runtime. `configure({ polyfills: { functions: true } })` inlines every call into plain CSS for browsers that don't ship the at-rule yet. See [Style DSL](dsl.md#functions-function).
+- **Custom color plugins with no core special-casing** — `okhsl`/`okhst` are now ordinary one-line plugins, and a third-party color space can achieve identical integration. New `createColorFunc` and `resolveFunctionColor` helpers.
+- **`configure({ propHandlers })`** — props middleware for every component: props in, props out. The extension point for props that aren't style values.
+- **`configure({ baseStyleProps })`** — expose style properties as props on every component without listing them in each `styleProps`.
+- **`defineHandler(deps, fn)`** — infers a multi-dependency handler's parameter types from its dependency list.
+- **Plugins can supply `properties`, `keyframes`, `fontFaces`, and `counterStyles`** in addition to what they already could.
+- See [Plugins & Extension Points](plugins.md) for all of the above.
+
+---
+
+## Search-and-replace cheat sheet
+
+Run these in order — the `Css` → `CSS` renames must happen before any broader pattern, and the quoted at-rule keys must stay quote-anchored so they can't hit `configure({ properties })`.
+
+```bash
+# 1. Raw-CSS family (before anything that touches "Css")
+rg -l 'getCssTextForClasses' | xargs sed -i '' 's/getCssTextForClasses/getCSSTextForClasses/g'
+rg -l 'getCssTextForNode'    | xargs sed -i '' 's/getCssTextForNode/getCSSTextForNode/g'
+rg -l 'getCssText'           | xargs sed -i '' 's/getCssText/getCSSText/g'
+rg -l 'CssOptions'           | xargs sed -i '' 's/CssOptions/CSSOptions/g'
+
+# 2. Styles-object at-rule keys (quote-anchored)
+rg -l "'@properties'"   | xargs sed -i '' "s/'@properties'/'@property'/g"
+rg -l "'@fontFace'"     | xargs sed -i '' "s/'@fontFace'/'@font-face'/g"
+rg -l "'@counterStyle'" | xargs sed -i '' "s/'@counterStyle'/'@counter-style'/g"
+
+# 3. Config getters (word-anchored so the plural forms are not double-pluralized)
+rg -l 'getGlobalFontFace\b'     | xargs sed -i '' 's/getGlobalFontFace\b/getGlobalFontFaces/g'
+rg -l 'getGlobalCounterStyle\b' | xargs sed -i '' 's/getGlobalCounterStyle\b/getGlobalCounterStyles/g'
+rg -l 'getGlobalFunction\b'     | xargs sed -i '' 's/getGlobalFunction\b/getGlobalFunctions/g'
+
+# 4. Color functions and parser methods
+rg -l 'okhslFunc\b' | xargs sed -i '' 's/okhslFunc\b/okhslFunction/g'
+rg -l 'okhstFunc\b' | xargs sed -i '' 's/okhstFunc\b/okhstFunction/g'
+rg -l 'setFuncs'    | xargs sed -i '' 's/setFuncs/setFunctions/g'
+
+# 5. Removed exports with direct replacements
+rg -l 'getIsTestEnvironment' | xargs sed -i '' 's/getIsTestEnvironment/isTestEnvironment/g'
+rg -l 'hydrateTastyCache'    | xargs sed -i '' 's/hydrateTastyCache/hydrateTastyClasses/g'
+
+# 6. Moved subpath
+rg -l "@tenphi/tasty/next" | xargs sed -i '' "s|@tenphi/tasty/next|@tenphi/tasty/zero/next|g"
+
+# 7. Verify nothing is left (should print nothing)
+rg "getCssText|CssOptions|'@properties'|'@fontFace'|'@counterStyle'|okhs[lt]Func\b|setFuncs|getIsTestEnvironment|hydrateTastyCache|@tenphi/tasty/next|getGlobalFontFace\b|getGlobalCounterStyle\b|getGlobalFunction\b"
+```
+
+`configure({ funcs })` → `functions`, `fontFace` → `fontFaces`, and `counterStyle` → `counterStyles` are deliberately **not** scripted: those words appear in many other contexts, so change them by hand and let TypeScript find the call sites.
+
+The directional shorthand cannot be scripted at all — the whole point is that the old form's meaning was not recoverable from its text. Run your app in development and follow the console warnings.
+
+---
+
+## Not changed
+
+Worth stating explicitly, because it's easy to assume otherwise:
+
+- **At-rule styles-object keys are CSS-spec-faithful, not JS-conventional.** `@keyframes`, `@property`, `@font-face`, `@counter-style`, `@function`, `@starting` — kebab-case, matching what Tasty emits.
+- **The `func()` injector method stays abbreviated.** `function` is a reserved word.
+- `injector.fontFace()` and `injector.counterStyle()` keep their singular names — only the *config keys* and *getters* were pluralized.
+- `useFontFace` and `useCounterStyle` are unchanged.
+- `configure({ properties })` and `autoPropertyTypes` are unchanged; only the styles-object `@property` key was renamed.
+- **The deprecated style aliases are retained deliberately.** `backgroundColor`, `background`, `backgroundImage`, `flex`, `grid`, and `flexDirection` still carry `@deprecated` tags and still work. They are the guardrail that discourages their use in projects that have not enabled `@tenphi/eslint-plugin-tasty` yet — read the tags as guidance, not as a removal notice.

package/docs/tasty/pipeline.md

@@ -6,7 +6,7 @@ This document describes the style rendering pipeline that transforms style objec
 
 ## Overview
 
-The pipeline takes a `Styles` object and produces an array of `CSSRule` objects ready for injection into the DOM. Entry points include `renderStylesPipeline` (full pipeline + optional class-name prefixing) and `renderStyles` (direct selector/class mode). The per-handler flow is:
+The pipeline takes a `Styles` object and produces an array of `CSSRule` objects ready for injection into the DOM. The entry point is `renderStyles`, which has two overloads: called with a selector or class (`renderStyles(styles, '.t1')`) it returns the rules directly; called without one (`renderStyles(styles)`) it returns `{ rules }` for a caller that will allocate the class name itself. The per-handler flow is:
 
 ```
 Input: Styles Object
@@ -539,7 +539,7 @@ interface CSSRule {
 }
 ```
 
-When `renderStylesPipeline` runs **without** a class name, returned rules include `needsClassName: true` (compatibility field for the injector); that flag is not part of `CSSRule` inside `materialize.ts`.
+When `renderStyles` runs **without** a selector, returned rules include `needsClassName: true` (compatibility field for the injector); that flag is not part of `CSSRule` inside `materialize.ts`.
 
 ---
 
@@ -691,7 +691,7 @@ Each snapshot yields distinct declarations; no merge.
 
 ### Stage 7: Materialize CSS
 
-Using `renderStyles(styles, '.t1')` (single class prefix; `renderStylesPipeline` doubles the class for specificity when a class name is supplied):
+Using `renderStyles(styles, '.t1')` (the class is doubled — `.t1.t1` — so Tasty owns specificity without `!important`):
 
 ```css
 .t1[data-hovered] {

package/docs/tasty/plugins.md

@@ -0,0 +1,349 @@
+# Plugins & Extension Points
+
+How to extend Tasty: new value syntax, new units, new states, new style properties, new component props, and how to package any of it as a plugin.
+
+- [What a plugin is](#what-a-plugin-is)
+- [Choosing an extension point](#choosing-an-extension-point)
+- [Custom style handlers](#custom-style-handlers)
+- [Props middleware](#props-middleware)
+- [Base style props](#base-style-props)
+- [Typing your extension](#typing-your-extension)
+- [Worked example: a `glaze` plugin](#worked-example-a-glaze-plugin)
+- [Rendering modes and caveats](#rendering-modes-and-caveats)
+- [Testing a plugin](#testing-a-plugin)
+
+---
+
+## What a plugin is
+
+A plugin is a plain object with a `name` and any subset of the `configure()` options it is allowed to supply. There is no lifecycle and no init hook — a plugin is just pre-packaged configuration.
+
+```ts
+import { configure } from '@tenphi/tasty';
+import type { TastyPluginFactory } from '@tenphi/tasty';
+
+const spacingPlugin: TastyPluginFactory = () => ({
+  name: 'spacing',
+  units: { gu: (n) => `calc(${n} * var(--grid-unit))` },
+  tokens: { '$grid-unit': '4px' },
+});
+
+configure({ plugins: [spacingPlugin()] });
+```
+
+`TastyPluginFactory<TOptions>` types a factory that takes options; with no type argument it types a zero-argument factory.
+
+**Ordering.** Plugins are applied in array order and merged key by key, so a later plugin overrides an earlier one for the same key. Options passed directly to `configure()` are applied last and win over every plugin.
+
+**Configuration is locked after the first render.** `configure()` warns and does nothing once any style has been generated, so it must run before your first component renders — at module scope in your entry file, or in a design-system module every component imports. `resetConfig()` reopens it, but it exists for tests.
+
+**Repeated `configure()` calls merge** for `tokens` and `globalStyles` (per selector). See [Configuration](configuration.md) for the current per-key semantics.
+
+---
+
+## Choosing an extension point
+
+| You want to add | Use | Runs | Zero-runtime |
+|---|---|---|---|
+| New value syntax — `okhsl(…)`, `double(2x)` | `functions` (bare key) | parse time, per value | ✅ |
+| A reusable CSS `@function` | `functions` (`$$name` key) | injected once, globally | ✅ |
+| A new unit — `2gu` | `units` | parse time, per value | ✅ |
+| A new state alias — `@mobile` | `states` | state-key parse | ✅ |
+| A style property → **CSS declarations** | `handlers` | pipeline, per state snapshot | ✅ |
+| A style property on every component | `baseStyleProps` | prop harvest | ✅ (styles only) |
+| A **component prop** → anything | `propHandlers` | render, per component | ❌ (no props to run on) |
+| A named bundle of styles | `recipes` | before chunking | ✅ |
+| Typography scale tokens | `presets` | inject time | ✅ |
+| `:root` variables | `tokens`, `replaceTokens` | inject time | ✅ |
+| Global selector styles | `globalStyles` | inject time | ✅ |
+
+Two distinctions do most of the work:
+
+- **`handlers` vs `propHandlers`.** A handler turns a *style property* into CSS declarations and knows nothing about components. A prop handler turns a *component prop* into other props — including `styles`, which then flow through the normal handlers. Reach for `propHandlers` when the input isn't a style value (an options object, a domain concept) or when it should affect more than styles.
+- **`recipes` vs `propHandlers`.** A recipe is a static named bundle. A prop handler computes its styles from a value.
+
+---
+
+## Custom style handlers
+
+A handler receives a map of the style properties it declared and returns CSS declarations. See [Configuration → Custom Style Handlers](configuration.md#custom-style-handlers) for the definition forms, return shape, the shared-handler groups you must be careful of, and chunk membership. The essentials:
+
+- Values arrive **state-resolved but unparsed** — the raw authored DSL string (`'2x'`, `'#purple.5'`, `true`, `4`). Call the exported `parseStyle()` / `parseColor()` yourself.
+- Return a `CSSMap` with **kebab-case** keys, an array of them, or nothing. `$` is a selector suffix, not a property.
+- Handlers must be pure and synchronous. They are called once per state combination and the results are cached.
+- Use `defineHandler(deps, fn)` for multi-dependency handlers so the dependency types are inferred.
+
+```ts
+import { configure, defineHandler, parseStyle } from '@tenphi/tasty';
+
+configure({
+  handlers: {
+    // Every declaration set the handler returns can target its own selector.
+    stripe: defineHandler(['stripe'], ({ stripe }) => {
+      if (!stripe) return;
+
+      const { values } = parseStyle(String(stripe)).groups[0];
+
+      return [
+        { position: 'relative' },
+        {
+          $: '&::before',
+          content: '""',
+          position: 'absolute',
+          inset: '0 auto 0 0',
+          width: values[0],
+          background: 'var(--purple-color)',
+        },
+      ];
+    }),
+  },
+});
+```
+
+---
+
+## Props middleware
+
+`propHandlers` are middleware over a component's props: props in, props out. They run at the very top of every tasty component's render, before any prop is destructured, so a handler can read and rewrite `styles`, `mods`, `tokens`, `variant`, `as`, `element`, and `qa`, and can strip its own props so they never reach the DOM.
+
+```ts
+import { configure, mergeStyles } from '@tenphi/tasty';
+
+configure({
+  propHandlers: {
+    glaze: (props) => {
+      const { glaze, ...rest } = props;
+      if (!glaze) return rest;
+
+      return { ...rest, styles: mergeStyles(glazeStyles(glaze), rest.styles) };
+    },
+  },
+});
+```
+
+**The key is the trigger.** By default a handler runs only when a prop matching its key is present, so an absent prop costs one property check rather than a call. Override that with a tuple:
+
+| Definition | Runs when |
+|---|---|
+| `fn` | a prop named after the key is present |
+| `['glaze', fn]` | `glaze` is present |
+| `[['glaze', 'tint'], fn]` | either is present |
+| `['*', fn]` | always |
+
+**Chaining.** Handlers run in registration order — plugins first, then direct `configure()` — and each receives the previous one's output. Registering the same key twice replaces the handler in place, keeping its position.
+
+**Returning nothing means unchanged**, with a development-mode warning, because that is almost always a forgotten `return props`. A non-object return is ignored with a warning.
+
+### Rules
+
+- **Be pure. Never mutate the input.** Style values are cached by object identity, so mutating a value object in place yields a stale class name *and* stale CSS. Return fresh objects.
+- **Memoize the styles you build, per input value.** A reference-stable (ideally frozen) styles object lets the cache key reuse its serialization instead of recomputing it on every render. This is the single highest-leverage thing you can do for performance.
+- **Precedence is fixed** and not adjustable from a handler. Styles are merged as `factory defaults → styles → harvested style props`, and injected styles occupy the `styles` slot: they beat a component's own default styles and lose to a style prop passed at the call site. This matches how `recipe` already behaves.
+- **Prefer returning `styles` over bare style props.** Returning `{ fill: '#red' }` only works if `fill` is harvestable on *that* component (in its `styleProps`, or promoted via `baseStyleProps`); otherwise it leaks to the DOM.
+
+### What it cannot do
+
+- **`ref`** — `forwardRef` separates it from props, so it is out of reach.
+- **Sub-elements** (`Card.Title`) — they have no `styles` prop and no style-prop harvest, so middleware does not run on them.
+- **Zero-runtime mode** — see [Rendering modes](#rendering-modes-and-caveats).
+
+---
+
+## Base style props
+
+A small set of style properties — `display`, `font`, `preset`, `hide`, `whiteSpace`, `opacity`, `transition` — are harvested as props on every `tasty()` component. `baseStyleProps` adds to that set globally:
+
+```ts
+configure({ baseStyleProps: ['radius', 'shadow'] });
+
+<Card radius="1r" shadow />
+```
+
+Names must be real style properties, must start with a lowercase letter, and must not collide with a prop `tasty()` consumes itself (`as`, `styles`, `variant`, `mods`, `tokens`, …); invalid entries are dropped with a development warning.
+
+`configure()` may run *after* your components are defined — each factory resolves its prop list lazily and refreshes when the registry changes.
+
+**Costs and caveats.** Each name adds one property check per render of every component, forever, so keep the list short. The effect is app-global and cannot be scoped to a subtree — use a factory's own `styleProps` for that. Be wary of names that collide with real DOM or component props (`width`, `size`, `color`): promoting one means every component swallows it as a style, including when rendering `as={SomeThirdPartyComponent}`.
+
+---
+
+## Typing your extension
+
+Four augmentation points, each matching a runtime registry:
+
+```ts
+// tasty.d.ts
+import type { StylePropValue } from '@tenphi/tasty';
+
+declare module '@tenphi/tasty' {
+  // configure({ handlers }) — a new style property
+  interface StylesInterface {
+    stripe?: StylePropValue<string>;
+  }
+
+  // configure({ propHandlers }) — a new component prop
+  interface TastyCustomProps {
+    glaze: 'soft' | 'strong' | { tone: string; intensity?: number };
+  }
+
+  // configure({ baseStyleProps }) — promoted style names, typed like the style
+  interface TastyBaseStylePropNames {
+    radius: true;
+    shadow: true;
+  }
+
+  // configure({ tokens }) / recipes / presets — autocomplete for names
+  interface TastyNamedColors {
+    'glaze-bg': true;
+  }
+}
+```
+
+`TastyCustomProps` keys become optional props on every component. `TastyBaseStylePropNames` entries are typed exactly like the style they name, so `radius="1r"` accepts the same values as `styles={{ radius: '1r' }}`.
+
+**Also update `tasty.config.ts`.** The ESLint plugin and VS Code extension validate style and token names against it, and neither is derived from the runtime registries:
+
+```ts
+// tasty.config.ts
+export default {
+  styles: ['stripe'],
+  tokens: ['#glaze-bg'],
+};
+```
+
+`propHandlers` keys are JSX props rather than style keys, so they need no entry — but any *style* name or token a handler expands into does.
+
+---
+
+## Worked example: a `glaze` plugin
+
+A `glaze` prop on every component that takes a configuration object and expands into color token declarations. This is the case `propHandlers` exists for: the value is an options object, not a style value, so it cannot be a style property.
+
+```ts
+// glaze-plugin.ts
+import { mergeStyles } from '@tenphi/tasty';
+import type { Styles, TastyPluginFactory } from '@tenphi/tasty';
+
+export interface GlazeConfig {
+  tone: string;
+  /** 0–100. Default 10. */
+  intensity?: number;
+}
+
+type GlazeValue = string | GlazeConfig;
+
+// Memoized per value so the styles object is reference-stable across renders.
+const cache = new Map<string, Styles>();
+
+function glazeStyles(value: GlazeValue): Styles {
+  const { tone, intensity = 10 } =
+    typeof value === 'string' ? { tone: value } : value;
+  const key = `${tone}:${intensity}`;
+
+  let styles = cache.get(key);
+
+  if (!styles) {
+    styles = Object.freeze({
+      '#glaze-bg': `#${tone}.${intensity}`,
+      fill: '#glaze-bg',
+      transition: 'fill 0.2s',
+    }) as Styles;
+    cache.set(key, styles);
+  }
+
+  return styles;
+}
+
+export const glazePlugin: TastyPluginFactory = () => ({
+  name: 'glaze',
+
+  propHandlers: {
+    glaze: (props) => {
+      const { glaze, ...rest } = props;
+      if (!glaze) return rest;
+
+      return {
+        ...rest,
+        styles: mergeStyles(
+          glazeStyles(glaze as GlazeValue),
+          rest.styles as Styles,
+        ),
+      };
+    },
+  },
+
+  // Typed so `#glaze-bg` animates smoothly instead of snapping.
+  properties: {
+    '#glaze-bg': { syntax: '<color>', inherits: false, initialValue: 'transparent' },
+  },
+});
+```
+
+```ts
+// app entry, before the first render
+import { configure } from '@tenphi/tasty';
+
+import { glazePlugin } from './glaze-plugin';
+
+configure({ plugins: [glazePlugin()] });
+```
+
+```tsx
+<Element glaze="purple" />
+<Element glaze={{ tone: 'success', intensity: 30 }} />
+```
+
+```ts
+// tasty.d.ts
+declare module '@tenphi/tasty' {
+  interface TastyCustomProps {
+    glaze: import('./glaze-plugin').GlazeConfig | string;
+  }
+}
+```
+
+The object value is unambiguous here precisely because `glaze` is a **prop**. A style *value* of the same shape would be indistinguishable from a state map (`{ tone: … }` looks exactly like `{ hovered: … }`), which is why this belongs in `propHandlers` rather than `handlers`.
+
+---
+
+## Rendering modes and caveats
+
+| Mode | `functions` / `units` / `states` / `handlers` / `recipes` / `tokens` | `propHandlers` |
+|---|---|---|
+| Client | ✅ | ✅ |
+| SSR / RSC | ✅ | ✅ |
+| Zero-runtime (`tastyStatic`) | ✅ at build time | not applicable |
+
+**Zero-runtime.** The Babel plugin transforms `tastyStatic()` calls, which take styles objects — there are no props in that pipeline, so there is nothing for props middleware to run on. Components you render through `tasty()` are untouched by the plugin and keep the runtime injector, so `propHandlers` work there exactly as in any client app; their CSS simply comes from the injector rather than the extracted stylesheet. Everything else runs at build time, which is why handlers, functions, and units must be pure functions of their input.
+
+**Server and client must configure identically.** Class names are derived from resolved styles, so a handler or promoted prop registered on one side and not the other produces a hydration mismatch. This is the same requirement as `namePrefix` — see [SSR → Hydration mismatch warnings](ssr.md#hydration-mismatch-warnings).
+
+---
+
+## Testing a plugin
+
+```ts
+import { configure, resetConfig, renderStyles } from '@tenphi/tasty';
+
+describe('glaze plugin', () => {
+  beforeEach(() => resetConfig());
+  afterEach(() => resetConfig());
+
+  it('expands into a color token declaration', () => {
+    configure({ plugins: [glazePlugin()] });
+
+    const rules = renderStyles({ '#glaze-bg': '#purple.10' }, '.test');
+
+    expect(rules[0].declarations).toContain('--glaze-bg-color');
+  });
+});
+```
+
+Two things to know:
+
+- **Create components inside each test.** `resetConfig()` does not clear the per-factory class-name cache or prop-list memo, so a module-scope component created in one test carries state into the next.
+- **Dev-mode warnings may not fire.** `isDevEnv()` reports `false` for `NODE_ENV=test`. Warnings that check it lazily can be enabled with `vi.stubEnv('NODE_ENV', 'development')`; some older ones capture it at module load and cannot be triggered from a test at all.
+
+---
+
+See [Configuration](configuration.md) for every option in detail, [Style DSL](dsl.md) for the value syntax your extensions produce, and [React API](react-api.md) for `tasty()`, `styleProps`, `modProps`, and `tokenProps`.