@cube-dev/ui-kit 0.0.0-canary-765a571 → 0.0.0-canary-03c39df

package/docs/tasty/ai-agents.md

@@ -0,0 +1,220 @@
+# Tasty Style Rules for AI Agents
+
+A compact ruleset for **writing correct `@tenphi/tasty` styles**. It is not an API tour — most rules here are machine-checked by [`@tenphi/eslint-plugin-tasty`](https://www.npmjs.com/package/@tenphi/eslint-plugin-tasty), so following it generally means clean lint output. The plugin ships separately and can lag a new DSL rule, so treat this page as the source of truth and the plugin as the enforcement that catches most of it. For explanations and the complete API, see [Style DSL](dsl.md), [Style Properties](styles.md), [React API](react-api.md).
+
+Notation: ❌ wrong → ✅ correct.
+
+---
+
+## 0. Read the project config first
+
+Color tokens (`#name`), custom properties (`$name`), `preset` names, `recipe` names, state aliases (`@mobile`) and extra units are **project-defined** in `tasty.config.ts` or a `configure({ … })` call. Look them up before writing styles. Never invent a name — reuse an existing one, or add it to the config.
+
+## 1. Where styles go
+
+```jsx
+const Card = tasty({ as: 'div', styles: { … }, styleProps: ['padding'] }); // new component
+const Hero = tasty(Card, { styles: { … } });                              // extend a component
+const cls = useStyles({ … });                                             // ad-hoc class name
+tastyStatic('.card', { … });                                              // build-time, zero runtime
+```
+
+- Wrap, don't pass styles per instance: ❌ `<Box styles={{ padding: '2x' }} />` → ✅ `const Box = tasty({ styles: { padding: '2x' } })`.
+- Style values are **static**. Route anything conditional through a state map plus `mods` (or `tokens` / `styleProps`):
+  ❌ `fill: isOpen ? '#primary' : '#surface'` → ✅ `fill: { '': '#surface', open: '#primary' }` with `mods={{ open: isOpen }}`.
+
+## 2. Property names
+
+Keys are camelCase — a Tasty property or a real CSS property. No kebab-case, no invented names.
+
+Prefer the Tasty shorthand over its CSS equivalents:
+
+| Use | Instead of |
+|-----|------------|
+| `fill` | `backgroundColor`, `background` |
+| `image` | `backgroundImage` |
+| `border` | `borderColor`, `borderWidth`, `borderStyle`, `borderTop`/`Right`/`Bottom`/`Left` |
+| `radius` | `borderRadius` |
+| `outline` | `outlineColor`, `outlineWidth`, `outlineStyle`, `outlineOffset` |
+| `shadow` | `boxShadow` |
+| `padding` | `paddingTop`/`Right`/`Bottom`/`Left` |
+| `margin` | `marginTop`/`Right`/`Bottom`/`Left` |
+| `inset` | `top`, `right`, `bottom`, `left` |
+| `width` / `height` | `minWidth`/`maxWidth`, `minHeight`/`maxHeight` |
+| `flow` | `flexDirection`, `flexWrap`, `flexFlow`, `gridAutoFlow` |
+| `preset` | `fontSize`, `lineHeight`, `letterSpacing`, `fontWeight`, `fontStyle`, `textTransform` |
+| `font` | `fontFamily` |
+| `scrollbar` | `scrollbarWidth`, `scrollbarColor`, `scrollbarGutter` |
+| `gridColumns` / `gridRows` / `gridAreas` | `gridTemplateColumns` / `Rows` / `Areas` |
+| `textOverflow: 'ellipsis / 3'` | `lineClamp` |
+| `hide: true` | `display: 'none'` |
+| `flexGrow` / `flexShrink` / `flexBasis` | `flex` |
+
+The last row goes the other way — longhands over the shorthand — because `flex` is lossy: it resets the components you omit to non-initial values (`flex: '0'` silently sets `flex-basis: 0%`) and cannot express `flexShrink: 0` at all. The longhands also carry separate state maps.
+
+## 3. Values
+
+### Tokens
+
+| Syntax | Meaning |
+|--------|---------|
+| `#name` | color token → `var(--name-color)` |
+| `#name.50` | token at 50% opacity (`0`–`100`) |
+| `#name.$opacity` | opacity from a custom property |
+| `#clear` / `#current` | `transparent` / `currentcolor` |
+| `$name` | custom property → `var(--name)` |
+| `(#a, #b)` | fallback chain |
+| `$$name` / `##name` | the custom property *name* (not its value) — inside `transition` |
+| `$$name(…)` | call a CSS `@function` declared via `@function`, `useFunction`, or config |
+
+- ❌ `#f5f5f5`, `rgb(0 0 0)`, `oklch(…)`, `okhsl(…)`, `red` → ✅ `#surface` (add the token to the config if it doesn't exist).
+- ❌ `var(--gap)` → ✅ `$gap` · ❌ `$accent-color` → ✅ `#accent` · ❌ `transparent` → ✅ `#clear` · ❌ `currentColor` → ✅ `#current`.
+- A `$name` must be declared as a `'$name': value` key in the same styles object, or in the config.
+
+### Units
+
+Tasty units: `x` (gap multiple), `r` (radius), `cr` (card radius), `bw` (border width), `ow` (outline width), `sf` (`minmax(0, Nfr)`). All CSS units work too, plus anything in `units` in the config. Any other unit is an error.
+
+Prefer units over raw pixels: `8px` → `1x` … `64px` → `8x`; `radius: '6px'` → `'1r'`; `border: '1px …'` → `'1bw …'`.
+
+### Math
+
+❌ `calc(100% - 2x)` → ✅ `(100% - 2x)`. Parentheses are wrapped in `calc()` automatically — and must be balanced.
+
+### `true`
+
+`true` means "the design-system default" and is accepted **only** by: `border`, `radius`, `outline`, `shadow`, `padding`, `margin`, `gap`, `inset`, `width`, `height`, `fill`, `color`, `preset`, `font`, `scrollbar`, `hide`. Anywhere else it is an error.
+
+### `!important`
+
+Never use it. Tasty owns specificity through doubled selectors and state ordering; `!important` breaks that. Express the exception as a state instead.
+
+### Modifiers
+
+A value is `[values…] [modifiers…]`, and several groups can be comma-separated (later groups override earlier ones). A group that names **direction** modifiers takes a **single** value, applied to every direction it names — per-side values come from comma groups. A group naming no direction keeps plain CSS shorthand order (1–4 values). (`inset` + `dock` is the one exception: a second value insets the spanned sides.) Only the modifiers a property knows are valid:
+
+| Property | Modifiers |
+|----------|-----------|
+| `padding`, `margin`, `inset`, `fade` | `top` `right` `bottom` `left` |
+| `border` | the four directions + `solid` `dashed` `dotted` `double` `groove` `ridge` `inset` `outset` `none` `hidden` |
+| `outline` | the style keywords above |
+| `radius` | `top` `right` `bottom` `left` + shapes `round` `ellipse` `leaf` `backleaf` |
+| `width`, `height` | `min` `max` `fixed` |
+| `flow` | `row` `column` `row-reverse` `column-reverse` `wrap` `nowrap` `dense` |
+| `overflow` | `visible` `hidden` `scroll` `clip` `auto` `overlay` |
+| `position` | `static` `relative` `absolute` `fixed` `sticky` |
+| `shadow` | `inset` |
+| `preset` | `name / strong` (or `bold`) `italic` `icon` `tight` |
+| box properties | `longhand` — emit CSS longhands instead of the shorthand |
+
+Directional modifiers beat placeholder zeros:
+
+- ❌ `padding: '0 0 2x 0'` → ✅ `padding: '2x bottom'`
+- ❌ `padding: '1x 1x 2x 1x'` → ✅ `padding: '1x, 2x bottom'`
+- ❌ `border: '0 0 1bw 0'` — four tokens parse as *one* border value, so this renders no border at all → ✅ `border: '1bw bottom'`
+- ❌ `padding: '2x 4x top right'` — a directional group takes one value, so `4x` is dropped → ✅ `padding: '2x top, 4x right'`
+- ❌ `fade: '3x 1x top bottom'` → ✅ `fade: '3x top, 1x bottom'`
+
+Value-only properties reject both colors and modifiers: `gap`, `columnGap`, `rowGap`, `opacity`, `zIndex`, `order`, `flexGrow`, `flexShrink`, `flexBasis`, `aspectRatio`, `lineClamp`, `tabSize`, `paddingInline`, `paddingBlock`. `fill` and `color` take a color (plus `none` / `transparent`); `caretColor` and `accentColor` take a color only.
+
+### `transition`
+
+Use semantic names, not CSS property names: `fade` `fill` `color` `theme` `border` `radius` `shadow` `outline` `preset` `text` `gap` `opacity` `translate` `rotate` `scale` `filter` `image` `background` `width` `height` `zIndex` `inset` `flow` `dimension`.
+
+❌ `transition: 'background-color 0.2s'` → ✅ `transition: 'fill 0.2s'`
+
+## 4. State maps
+
+A property value can be an object of `state: value`. Key order is priority — later keys win.
+
+| Key | Generated selector |
+|-----|--------------------|
+| `hovered` | `[data-hovered]` (boolean modifier from `mods`) |
+| `theme=danger` | `[data-theme="danger"]` (value modifier) |
+| `:hover` | pseudo-class |
+| `.active` | class selector |
+| `[aria-expanded="true"]` | attribute selector |
+| `hovered & .active` | AND |
+| `hovered \| focused` | OR (`,` also means OR) |
+| `!disabled` | NOT |
+| `hovered ^ focused` | XOR — exactly one (keep chains ≤ 4 operands) |
+
+Precedence `!` > `^` > `|` > `&`; use parentheses to override.
+
+Rules:
+
+1. **`''` comes first.** The bare default is the lowest-priority state; placing it later would override everything above it.
+2. **Every state map needs `''` or `_`** — except when extending (`tasty(Parent, …)`), where omitting `''` merges into the parent's states and including `''` replaces them wholesale.
+3. **`_` is standalone-only** and always first (with `''` right after it, if present). `_` is a never-negated fallback floor for cases where a higher-priority branch may be *unknown* (`@supports`, container queries). If a map contains only `_` and `''`, drop the `''`.
+4. **No nested maps:** ❌ `{ hovered: { pressed: 'x' } }` → ✅ `{ 'hovered & pressed': 'x' }`
+5. **State keys never sit at the top level** of a styles object — `:hover`, `.active`, `[open]` belong inside a property value.
+
+```jsx
+color: { '': '#text', hovered: '#accent', disabled: '#text.40' }
+```
+
+Advanced states:
+
+| Prefix | Use | Example |
+|--------|-----|---------|
+| `@media(…)` | media query; dimensions `w` `h`; types `@media:print` `:screen` `:all` `:speech` | `@media(w < 768px)`, `@media(600px <= w < 1200px)` |
+| `@(…)` | container query; dimensions `w` `h` `is` `bs` | `@(layout, w >= 600px)`, `@($variant=primary)` |
+| `@supports(…)` | feature query; `$` first argument tests a selector | `@supports(display: grid)`, `@supports($, :has(*))` |
+| `@root(…)` | condition on `:root` | `@root(schema=dark)` |
+| `@parent(…)` | condition on an ancestor; `, >` for the direct parent | `@parent(hovered, >)` |
+| `@own(…)` | a sub-element's own state — **only inside sub-element styles** | `@own(:hover)` |
+| `@starting` | `@starting-style` entry animation | `@starting` |
+| `@name` | project state alias | `@mobile` |
+
+- At root level write the selector directly: ❌ `'@own(:hover)'` → ✅ `':hover'`.
+- `@name` aliases must exist in `states` in the config or be declared locally as an `'@name': '<state expression>'` key; alias keys start with `@` and their value must be a valid state expression.
+- `:is()` / `:has()` / `:not()` / `:where()` work in state keys but support at most 2 levels of nested parentheses, and `:has()` is expensive — prefer `@parent()`, `@own()` and modifiers.
+
+When extending a parent's state map: `'@inherit'` reuses the parent's value for that state, `null` removes a state (or resets a property, letting recipes fill in), `false` is a tombstone that blocks it entirely.
+
+## 5. Sub-elements
+
+A **capitalized** key targets `[data-element="Name"]`, and its value must be a style object.
+
+```jsx
+styles: { Title: { preset: 'h3' }, Icon: { $: '>@:last-child', color: '#accent' } }
+```
+
+❌ nested-selector keys (`'& .title'`, `'&:hover'`) → ✅ sub-elements and state maps. Use the `$` affix property inside a sub-element to control how its selector attaches (`>` direct child, `@` placeholder for the element itself, `&::before` for a root pseudo-element).
+
+## 6. Special top-level keys
+
+| Key | Shape |
+|-----|-------|
+| `@keyframes` | `{ name: { '0%': styles, … } }` |
+| `@property` | `{ '$name': { syntax, inherits, initialValue } }` |
+| `@font-face` | `{ 'Family Name': descriptors \| descriptors[] }` |
+| `@counter-style` | `{ name: descriptors }` |
+| `@function` | `{ '$$name': { args, returns?, result, '$local'? } }` |
+| `recipe` | a **string** of configured recipe names: `'card elevated'`, `'reset input / autofill'`, `'none / disabled'` |
+
+At-rule keys match the real CSS at-rule names, so they are kebab-case, not camelCase. Inside `@function`, the callable is `$$name` but its parameters and local variables are `$name`:
+
+```jsx
+styles: {
+  '@function': { $$negative: { args: ['$value'], result: '(-1 * $value)' } },
+  marginTop: '$$negative(2x)',
+}
+```
+
+## 7. `tastyStatic()`
+
+The selector must be a string literal and valid CSS. Values must be static — strings, numbers, booleans, `null`, or objects/arrays of those. No variables, template literals, function calls, or spreads.
+
+## 8. Checklist
+
+- Token, preset, recipe, unit and `@alias` names exist in the project config.
+- Tasty shorthand chosen over CSS longhands; `flexGrow`/`flexShrink`/`flexBasis` over `flex`; `hide: true` over `display: 'none'`.
+- Colors are `#tokens`, not hex/rgb/oklch/named; `$prop` not `var(--prop)`.
+- Spacing uses `x`/`r`/`bw`/`ow` units; math uses `(…)`, not `calc(…)`.
+- `true` only on the properties that accept it; no `!important`.
+- Modifiers valid for the property; directional shorthand instead of placeholder zeros.
+- Every state map starts with `''` (or `_`), is flat, and lives inside a property value.
+- `@own()` only inside sub-elements; sub-element keys are capitalized and hold objects.
+- At-rule keys are kebab-case (`@property`, `@font-face`, `@counter-style`, `@function`); `@function` names use `$$`, their args and locals use `$`.
+- Values are static; dynamic behavior comes from `mods` / `tokens` / `styleProps`.

package/docs/tasty/configuration.md

@@ -26,12 +26,15 @@ configure({
     custom: (n) => `${n * 10}px`, // Function-based unit
   },
 
-  // Custom functions for the parser
-  funcs: {
+  // Custom functions — a single map for both flavors, discriminated by value type:
+  functions: {
+    // Bare key + function value → parse-time function, called as `double(...)`
     double: (groups) => {
       const value = parseFloat(groups[0]?.output || '0');
       return `${value * 2}px`;
     },
+    // `$$name` key + object value → declarative CSS @function, called as `$$negative(...)`
+    $$negative: { args: ['$value'], result: '(-1 * $value)' },
   },
 });
 ```
@@ -45,23 +48,31 @@ These docs use `data-schema="dark"` in examples. If your app already standardize
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `nonce` | `string` | - | CSP nonce for style elements |
+| `maxRulesPerSheet` | `number` | `8192` | Maximum rules per injected stylesheet |
+| `forceTextInjection` | `boolean` | auto (`true` in test envs) | Force text-node CSS injection instead of constructable stylesheets |
+| `devMode` | `boolean` | auto | Enable development-mode features: performance metrics and debug info |
 | `states` | `Record<string, string>` | - | Global state aliases for advanced state mapping |
 | `parserCacheSize` | `number` | `1000` | Parser LRU cache size |
-| `units` | `Record<string, string \| Function>` | Built-in | Custom units (merged with built-in). See [built-in units](dsl.md#built-in-units) |
-| `funcs` | `Record<string, Function>` | - | Custom parser functions (merged with existing) |
-| `handlers` | `Record<string, StyleHandlerDefinition>` | Built-in | Custom style handlers (replace built-in) |
+| `units` | `Record<string, string \| UnitHandler>` | Built-in | Custom units (merged with built-in). See [built-in units](dsl.md#built-in-units) |
+| `functions` | `Record<string, FunctionDefinition \| Function>` | - | Custom functions (merged). Bare keys → parse functions; `$$name` keys → declarative CSS `@function` definitions |
+| `handlers` | `Record<string, StyleHandlerDefinition>` | Built-in | Custom style handlers (replace built-in). See [Custom Style Handlers](#custom-style-handlers) |
+| `propHandlers` | `Record<string, PropHandlerDefinition>` | - | Props middleware for every component — props in, props out. See [Props Middleware](#props-middleware) |
+| `baseStyleProps` | `readonly string[]` | - | Style names exposed as props on **every** component. See [Base Style Props](#base-style-props) |
 | `tokens` | `Record<string, value \| stateMap>` | - | Design tokens injected as `:root` CSS custom properties |
-| `replaceTokens` | `Record<string, string \| number>` | - | Parse-time token substitution (inline replacement) |
+| `replaceTokens` | `Record<string, string \| number \| boolean>` | - | Parse-time token substitution (inline replacement). `boolean` is allowed for `#` color tokens |
 | `keyframes` | `Record<string, KeyframesSteps>` | - | Global keyframes for animations |
 | `properties` | `Record<string, PropertyDefinition>` | - | Global CSS @property definitions |
-| `fontFace` | `Record<string, FontFaceInput>` | - | Global @font-face definitions |
-| `counterStyle` | `Record<string, CounterStyleDescriptors>` | - | Global @counter-style definitions |
+| `fontFaces` | `Record<string, FontFaceInput>` | - | Global @font-face definitions |
+| `counterStyles` | `Record<string, CounterStyleDescriptors>` | - | Global @counter-style definitions |
+| `polyfills` | `{ functions?: boolean }` | `{}` | Opt-in polyfills for not-yet-baseline features. `functions: true` inlines `@function` calls into plain CSS at parse time |
 | `autoPropertyTypes` | `boolean` | `true` | Auto-infer and register `@property` types from values |
 | `recipes` | `Record<string, RecipeStyles>` | - | Predefined style recipes (named style bundles) |
 | `presets` | `Record<string, TypographyPreset>` | - | Typography presets — shorthand for `generateTypographyTokens()` |
 | `globalStyles` | `Record<string, Styles>` | - | Global Tasty styles keyed by CSS selector |
+| `plugins` | `TastyPlugin[]` | - | Plugins that bundle any of the above (processed in order; later override earlier, and direct config wins over all). See [Plugins](plugins.md) |
+| `gc` | `GCConfig` | - | Garbage-collection tuning for unused styles (`{ touchInterval, capacity }`) |
 | `colorSpace` | `'rgb' \| 'hsl' \| 'oklch'` | `'oklch'` | Color space for decomposed color token companion variables |
-| `namePrefix` | `string` | `'t'` (runtime) / `'ts'` (zero-runtime) | Prefix prepended to every generated identifier (class, keyframe, counter-style names). See [Name prefix](#name-prefix). |
+| `namePrefix` | `string` | `'t'` (runtime) / `'ts'` (zero-runtime) | Prefix prepended to every generated identifier (class, keyframe, counter-style names). Must match `^[a-zA-Z_][a-zA-Z0-9_-]{0,31}$`. See [Name prefix](#name-prefix). |
 
 ---
 
@@ -187,7 +198,7 @@ Register custom fonts globally so every component can reference them by family n
 
 ```ts
 configure({
-  fontFace: {
+  fontFaces: {
     'Brand Sans': [
       {
         src: 'url("/fonts/brand-regular.woff2") format("woff2")',
@@ -210,7 +221,7 @@ configure({
 
 Now any component can use `fontFamily: '"Brand Sans", sans-serif'` and the browser will already have the `@font-face` rules in the stylesheet.
 
-See [Font Face (`@fontFace`)](dsl.md#font-face-fontface) for inline usage inside component styles and the full list of supported descriptors.
+See [Font Face (`@font-face`)](dsl.md#font-face-font-face) for inline usage inside component styles and the full list of supported descriptors.
 
 ---
 
@@ -220,7 +231,7 @@ Define custom list-marker algorithms globally. Rules are injected eagerly when s
 
 ```ts
 configure({
-  counterStyle: {
+  counterStyles: {
     thumbs: {
       system: 'cyclic',
       symbols: '"👍"',
@@ -236,7 +247,98 @@ configure({
 
 Components can then reference `listStyleType: 'thumbs'` directly.
 
-See [Counter Style (`@counterStyle`)](dsl.md#counter-style-counterstyle) for inline usage inside component styles and the full list of supported descriptors.
+See [Counter Style (`@counter-style`)](dsl.md#counter-style-counter-style) for inline usage inside component styles and the full list of supported descriptors.
+
+---
+
+## Functions
+
+The single `functions` map holds both kinds of custom functions, discriminated by the value type:
+
+- **Parse functions** — a **bare key** with a **function value** `(groups) => string`. Runs at parse time and is called as `name(...)`. Use these for computed/derived CSS that JavaScript produces (e.g. color-space conversions).
+- **CSS `@function` definitions** — a **`$$name` key** with an **object value** (a [`FunctionDefinition`](https://developer.mozilla.org/en-US/docs/Web/CSS/@function)). Injected eagerly as a native `@function` rule and called as `$$name(...)` (→ `--name(...)`).
+
+```ts
+configure({
+  functions: {
+    // Parse function — bare key, function value
+    double: (groups) => `calc(2 * ${groups[0]?.output ?? '0'})`,
+
+    // CSS @function — `$$` key, object value
+    $$negative: { args: ['$value'], result: '(-1 * $value)' },
+    $$shadow: {
+      args: { '$shadow-color': { syntax: '<color>', default: 'inherit' } },
+      returns: '<color>',
+      $offset: '2px',
+      result: '$offset $offset ($shadow-color, black)',
+    },
+  },
+});
+```
+
+Components then invoke parse functions as `double(...)` and CSS functions with the `$$name(...)` sugar, e.g. `marginTop: '$$negative(10px)'`.
+
+> A key whose prefix doesn't match its value type (an object under a bare key, or a function under a `$$` key) is **ignored with a dev-mode warning**.
+
+See [Functions (`@function`)](dsl.md#functions-function) for inline usage inside component styles, the full descriptor shape, and token conventions. `@function` is an experimental CSS feature — unsupported browsers safely ignore the native rule (see the polyfill below).
+
+### Custom color functions
+
+A parse function whose output is an already-supported color (`rgb`, `hsl`, `#…`, `oklch`, …) is treated as a **color function**: it works everywhere a color is accepted — style values, `#token.alpha` opacity injection, token decomposition into the configured color space, and `parseColor` — with no extra registration. This is the same mechanism the built-in `okhsl`/`okhst` plugins use; they are ordinary plugins registered by default.
+
+```ts
+import { configure, createColorFunc } from '@tenphi/tasty';
+
+// A custom color space is just a `functions` entry.
+const myColorPlugin = () => ({
+  name: 'mycolor',
+  functions: {
+    // Hand-written parse function:
+    mycolor: (groups) => {
+      const [r, g, b] = groups[0].all;
+      return `rgb(${r} ${g} ${b})`;
+    },
+  },
+});
+
+configure({ plugins: [myColorPlugin()] });
+
+// Now `mycolor(...)` is a color in every context:
+//   fill: 'mycolor(255 0 0)'
+//   fill: '#brand.5'   (with replaceTokens: { '#brand': 'mycolor(255 0 0)' })
+```
+
+For HSL-style color spaces (a hue angle plus two percentages), the exported `createColorFunc(name, convert, label?)` helper handles angle/percentage parsing, clamping, alpha, and caching. `convert` returns sRGB `[r, g, b]` in 0-1; `label` is an optional string used only in dev warnings (e.g. `'H S L'`) and has no effect on output. This is exactly how `okhslPlugin`/`okhstPlugin` are implemented.
+
+---
+
+## Polyfills
+
+`@function` only ships natively in Chromium 139+. To use CSS functions in browsers that don't support the at-rule yet (Firefox, Safari), enable the **functions polyfill**, which expands every `$$name(...)` call into plain CSS (`calc()`/`var()`/`color-mix()`) at parse time instead of emitting the native `@function` rule:
+
+```ts
+configure({
+  polyfills: {
+    functions: true, // default: false
+  },
+  functions: {
+    $$negative: { args: ['$value'], result: '(-1 * $value)' },
+  },
+});
+
+// Now `marginTop: '$$negative(10px)'` renders `margin-top: calc(-1 * 10px)`
+// — no native @function rule is emitted.
+```
+
+This works across all rendering modes (client, SSR/RSC, and `tastyStatic`) because expansion happens in the parser. Note `polyfills.functions` (the feature toggle) is distinct from the top-level `functions` (the definitions map).
+
+**Decided limitations when the polyfill is on:**
+
+- **No native fallback** — functions are always inlined; we do exactly what is configured.
+- **Conditional results** (`@media`/`@supports`/`if()` inside `result`) are inlined verbatim; the conditional nuance is not resolved per-element.
+- **Typed params / `returns`** are dropped (inlining is purely lexical substitution).
+- **Param name collisions** are avoided by fully inlining argument values (no function-internal custom properties are emitted) and by namespacing the function's own variables.
+- **Recursion** — self/mutually-recursive functions are not expanded; the cycle guard bails and leaves the call untouched.
 
 ---
 
@@ -260,7 +362,7 @@ configure({
 });
 ```
 
-Recipe values are flat tasty styles (no sub-element keys). They may contain base styles, tokens, local states, `@keyframes`, and `@properties`. Recipes cannot reference other recipes.
+Recipe values are flat tasty styles (no sub-element keys). They may contain base styles, tokens, local states, `@keyframes`, and `@property`. Recipes cannot reference other recipes.
 
 For how to apply, compose, and override recipes in components, see [Recipes](dsl.md#recipes) in the Style DSL reference.
 
@@ -349,12 +451,12 @@ Supported types:
 | `300ms`, `1s` (time units) | `<time>` |
 | `#name` tokens (by naming convention) | `<color>` |
 
-Auto-inferred properties use `inherits: true` (the CSS default). Use explicit `@properties` when you need different settings:
+Auto-inferred properties use `inherits: true` (the CSS default). Use explicit `@property` when you need different settings:
 
 ```jsx
 // In component styles
 styles: {
-  '@properties': {
+  '@property': {
     '$scale': { syntax: '<number>', inherits: false, initialValue: 1 },
   },
 }
@@ -367,7 +469,7 @@ configure({
 });
 ```
 
-To disable auto-inference entirely (only explicit `@properties` will be used):
+To disable auto-inference entirely (only explicit `@property` will be used):
 
 ```jsx
 configure({ autoPropertyTypes: false });
@@ -385,21 +487,13 @@ Override or extend the built-in style property handlers. A handler definition ca
 | Single dep | `['styleName', handler]` | Triggered by the specified style property |
 | Multi dep | `[['dep1', 'dep2', ...], handler]` | Triggered by any of the listed properties; receives all of them |
 
-The multi-dep form is useful when output depends on several style properties together (e.g., `gap` needs to know `display` and `flow` to decide the CSS strategy).
+The multi-dep form is useful when output depends on several style properties together (e.g., `gap` needs to know `display` and `flow` to decide the CSS strategy). Use `defineHandler` for it and the dependency types are inferred from the dependency list, so a typo in the destructure is a type error instead of a silent `undefined`.
 
 ```jsx
-import { configure, styleHandlers } from '@tenphi/tasty';
+import { configure, defineHandler, styleHandlers } from '@tenphi/tasty';
 
 configure({
   handlers: {
-    // Function only — overrides built-in fill handler
-    fill: ({ fill }) => {
-      if (fill?.startsWith('gradient:')) {
-        return { background: fill.slice(9) };
-      }
-      return styleHandlers.fill({ fill });
-    },
-
     // Function only — new single-prop handler
     elevation: ({ elevation }) => {
       const level = parseInt(elevation) || 1;
@@ -409,16 +503,112 @@ configure({
       };
     },
 
+    // Overriding a built-in: declare every style the built-in handled and pass
+    // them all through, or the ones you leave out stop working (see below).
+    fill: defineHandler(
+      [
+        'fill', 'backgroundColor', 'image', 'backgroundImage',
+        'backgroundPosition', 'backgroundSize', 'backgroundRepeat',
+      ],
+      (props) => {
+        if (typeof props.fill === 'string' && props.fill.startsWith('gradient:')) {
+          return { background: props.fill.slice(9) };
+        }
+        return styleHandlers.fill(props);
+      },
+    ),
+
     // Multi dep — handler reads multiple style properties
-    gap: [['display', 'flow', 'gap'], ({ display, flow, gap }) => {
+    gap: defineHandler(['display', 'flow', 'gap'], ({ display, flow, gap }) => {
       if (!gap) return;
-      const isGrid = display?.includes('grid');
+      const isGrid = String(display ?? '').includes('grid');
       return { gap: isGrid ? gap : `/* custom logic for ${flow} */` };
-    }],
+    }),
   },
 });
 ```
 
+### Return shape
+
+A handler returns a `CSSMap`, an array of them, or nothing:
+
+- Keys are **kebab-case** CSS property names (`'background-color'`, not `backgroundColor`) or `--custom-property` names. A camelCase key warns in development and is emitted verbatim, which the browser ignores.
+- Values are stringified, so numbers are fine (`{ '-webkit-line-clamp': 3 }`).
+- The reserved `$` key is a **selector suffix**: `{ $: '& > *:not(:last-child)', 'margin-right': gap }` applies the declarations to a nested selector. It accepts an array to fan out over several.
+- Return an array of maps to emit several declaration sets, each with its own `$`.
+
+Values arrive **state-resolved but unparsed** — the raw authored DSL string (`'2x'`, `'#purple.5'`, `true`, `4`). Call the exported `parseStyle()` / `parseColor()` yourself; nothing parses them for you.
+
+### Replacing a built-in handler
+
+Built-in handlers are shared across several style names. Registering a handler for one of those names unregisters the built-in from **all** of them, and the displaced names then fall back to auto-generated CSS aliases — so `hide: true` starts emitting a literal `hide: true` declaration. A development-mode warning lists exactly what was displaced.
+
+The shared groups worth knowing:
+
+| Registering a handler for | Also takes over |
+|---|---|
+| `fill` | `backgroundColor`, `image`, `backgroundImage`, `backgroundPosition`, `backgroundSize`, `backgroundRepeat` |
+| `display` | `hide`, `overflow`, `whiteSpace`, `textOverflow`, `flow`, `gap` |
+| `preset` | `font`, `fontSize`, `fontWeight`, `fontStyle`, `lineHeight`, `letterSpacing`, `textTransform` |
+| `padding` / `margin` / `inset` | their `*Top`/`*Right`/`*Bottom`/`*Left`/`*Block`/`*Inline` longhands |
+
+Either declare the whole group and delegate the rest to `styleHandlers.*`, or pick a name that isn't shared.
+
+### Chunk membership
+
+Tasty renders and caches CSS in independent chunks, and a chunk's cache key covers only its own style values. All of a handler's dependencies must therefore live in one chunk. Custom style names are pulled into their handler's chunk automatically at registration; a handler whose dependencies span two *built-in* chunks (say `fill` and `padding`) warns, because it would be invoked once per chunk with a subset of its inputs.
+
+`configure({ handlers })` must run before the first render, like every other config option.
+
+---
+
+## Props Middleware
+
+`propHandlers` are middleware over a component's props — props in, props out. Where a style *handler* turns a style property into CSS declarations, a prop handler turns a **component prop** into other props, including `styles`. It is the extension point for props whose value isn't a style value.
+
+```jsx
+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) };
+    },
+  },
+});
+
+<Element glaze="purple" />
+```
+
+The map key is the handler's name and, by default, the prop that triggers it, so an absent prop costs one property check rather than a call. A tuple overrides that: `['glaze', fn]`, `[['glaze', 'tint'], fn]`, or `['*', fn]` for unconditional.
+
+Handlers run at the very top of every component's render, before any prop is destructured, so one can rewrite `styles`, `mods`, `tokens`, `variant`, `as`, `element`, and `qa`. They run in registration order — plugins first, then direct config — each receiving the previous one's output.
+
+Handlers must be **pure** and must not mutate their input, and should memoize the styles they build per input value: style values are cached by object identity, so mutating one in place yields stale CSS, and a reference-stable object avoids re-serializing on every render.
+
+Injected styles occupy the `styles` slot, so they beat a component's own default styles and lose to a style prop at the call site. Prop handlers do not apply to sub-elements or to zero-runtime `tastyStatic()`, which has no props.
+
+See [Plugins → Props middleware](plugins.md#props-middleware) for the full contract and a worked example.
+
+---
+
+## Base Style Props
+
+`baseStyleProps` exposes style properties as props on **every** `tasty()` component, on top of the built-in base styles (`display`, `font`, `preset`, `hide`, `whiteSpace`, `opacity`, `transition`):
+
+```jsx
+configure({ baseStyleProps: ['radius', 'shadow'] });
+
+<Card radius="1r" shadow />
+```
+
+`configure()` may run after your components are defined — each factory resolves its prop list lazily.
+
+Each name costs one property check per render of every component, and the effect is app-global, so keep the list short and use a factory's own `styleProps` for anything narrower. Avoid names that collide with real DOM or component props (`width`, `size`, `color`), since every component will then swallow them as styles.
+
 ---
 
 ## Extending Style Types (TypeScript)

package/docs/tasty/debug.md

@@ -79,7 +79,7 @@ Retrieves CSS text for a given target. Logs the result with rule count and size.
 **Extra options:**
 
 ```typescript
-interface CssOptions extends DebugOptions {
+interface CSSOptions extends DebugOptions {
   prettify?: boolean; // Format output (default: true)
   source?: boolean;   // Read original CSS instead of live CSSOM (default: false, dev-mode only)
 }
@@ -111,14 +111,14 @@ Inspects a DOM element and returns detailed information about its tasty styles,
 ```typescript
 interface InspectResult {
   element?: Element | null;
-  classes: string[];    // Tasty classes on the element
-  chunks: ChunkInfo[];  // Chunk assignment per class
-  css: string;          // Prettified CSS
-  size: number;         // CSS size in characters
-  rules: number;        // Number of CSS rule blocks
+  classes: string[];          // Tasty classes on the element
+  chunks: DebugChunkInfo[];   // Chunk assignment per class
+  css: string;                // Prettified CSS
+  size: number;               // CSS size in characters
+  rules: number;              // Number of CSS rule blocks
 }
 
-interface ChunkInfo {
+interface DebugChunkInfo {
   className: string;
   chunkName: string | null; // e.g., 'appearance', 'font', 'dimension'
 }

package/docs/tasty/design-system.md

@@ -117,11 +117,11 @@ Then use `preset: 'h1'` or `preset: 't2'` in any component's styles.
 
 ### Registering brand fonts
 
-Register your design system's custom fonts via `configure({ fontFace })` so every component can reference them:
+Register your design system's custom fonts via `configure({ fontFaces })` so every component can reference them:
 
 ```ts
 configure({
-  fontFace: {
+  fontFaces: {
     'Brand Sans': [
       { src: 'url("/fonts/brand-regular.woff2") format("woff2")', fontWeight: 400, fontDisplay: 'swap' },
       { src: 'url("/fonts/brand-bold.woff2") format("woff2")', fontWeight: 700, fontDisplay: 'swap' },