@cube-dev/ui-kit 0.154.1 → 0.155.0

package/docs/tasty/README.md

@@ -20,13 +20,15 @@ Tasty is a styling engine for design systems that turns component state into det
 - **React components**: [React API](react-api.md)
 - **Zero-runtime / build-time extraction**: [Zero Runtime (tastyStatic)](tasty-static.md)
 - **Runtime `tasty()` with server collection and hydration**: [Server-Side Rendering](ssr.md)
+- **Upgrading from v2**: [Migration Guide (v2 → v3)](migration-v3.md)
 
 ## By Task
 
 - **Learn the style language**: [Style DSL](dsl.md)
 - **Brief an AI agent (or yourself) on writing correct styles**: [Style Rules for AI Agents](ai-agents.md)
 - **Look up a property handler**: [Style Properties](styles.md)
-- **Define tokens, units, recipes, keyframes, or properties globally**: [Configuration](configuration.md)
+- **Define tokens, units, recipes, keyframes, properties, functions, or polyfills globally**: [Configuration](configuration.md)
+- **Extend Tasty with a plugin, custom handler, or custom prop**: [Plugins & Extension Points](plugins.md)
 - **Debug generated CSS or cache behavior**: [Debug Utilities](debug.md)
 - **Understand how selector generation works internally**: [Style rendering pipeline](pipeline.md)
 - **Understand runtime injection internals**: [Style Injector](injector.md)

package/docs/tasty/ai-agents.md

@@ -1,6 +1,6 @@
 # Tasty Style Rules for AI Agents
 
-A compact ruleset for **writing correct `@tenphi/tasty` styles**. It is not an API tour — every rule here is machine-checked by [`@tenphi/eslint-plugin-tasty`](https://www.npmjs.com/package/@tenphi/eslint-plugin-tasty), so following it means clean lint output. For explanations and the complete API, see [Style DSL](dsl.md), [Style Properties](styles.md), [React API](react-api.md).
+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.
 
@@ -64,7 +64,8 @@ The last row goes the other way — longhands over the shorthand — because `fl
 | `#clear` / `#current` | `transparent` / `currentcolor` |
 | `$name` | custom property → `var(--name)` |
 | `(#a, #b)` | fallback chain |
-| `$$name` / `##name` | the property *name* — only inside `transition` |
+| `$$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`.
@@ -82,7 +83,7 @@ Prefer units over raw pixels: `8px` → `1x` … `64px` → `8x`; `radius: '6px'
 
 ### `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.
+`true` means "the design-system default" and is accepted **only** by: `border`, `radius`, `outline`, `shadow`, `padding`, `margin`, `gap`, `inset`, `width`, `height`, `fill`, `color`, `fade`, `preset`, `font`, `scrollbar`, `hide`. Anywhere else it is an error.
 
 ### `!important`
 
@@ -90,7 +91,7 @@ Never use it. Tasty owns specificity through doubled selectors and state orderin
 
 ### Modifiers
 
-A value is `[values…] [modifiers…]`, and several groups can be comma-separated (later groups override earlier ones). Only the modifiers a property knows are valid:
+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 |
 |----------|-----------|
@@ -111,6 +112,8 @@ 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.
 
@@ -184,11 +187,21 @@ styles: { Title: { preset: 'h3' }, Icon: { $: '>@:last-child', color: '#accent'
 | Key | Shape |
 |-----|-------|
 | `@keyframes` | `{ name: { '0%': styles, … } }` |
-| `@properties` | `{ '$name': { syntax, inherits, initialValue } }` |
-| `@fontFace` | `{ 'Family Name': descriptors \| descriptors[] }` |
-| `@counterStyle` | `{ name: descriptors }` |
+| `@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.
@@ -203,4 +216,5 @@ The selector must be a string literal and valid CSS. Values must be static — s
 - 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' },

package/docs/tasty/dsl.md

@@ -123,7 +123,7 @@ mods={{ hovered: true, theme: 'danger' }}
 // → data-hovered="" data-theme="danger"
 ```
 
-Modifiers can also be exposed as top-level component props via `modProps` — see [Runtime — Mod Props](react-api.md#mod-props).
+Modifiers can also be exposed as top-level component props via `modProps` — see [React API — Mod Props](react-api.md#mod-props).
 
 ---
 
@@ -683,24 +683,24 @@ const AnimatedGradient = tasty({
 
 Here `$gradient-angle: '0deg'` is detected as `<angle>` and `#theme` as `<color>` (via the `#name` naming convention), so both transitions work without any manual `@property` declarations. Numeric types (`<number>`, `<length>`, `<percentage>`, `<angle>`, `<time>`) are inferred from values; `<color>` is inferred from `#name` tokens.
 
-Use explicit `@properties` when you need non-default settings like `inherits: false`:
+Use explicit `@property` when you need non-default settings like `inherits: false`:
 
 ```jsx
-'@properties': {
+'@property': {
   '$gradient-angle': { syntax: '<angle>', inherits: false, initialValue: '0deg' },
 },
 ```
 
 ---
 
-## Font Face (`@fontFace`)
+## Font Face (`@font-face`)
 
 Register custom fonts directly inside a `styles` object. Keys are font-family names, values are descriptor objects (or arrays of them for multiple weights/styles).
 
 ```ts
 const Heading = tasty({
   styles: {
-    '@fontFace': {
+    '@font-face': {
       'Brand Sans': {
         src: 'url("/fonts/brand-sans.woff2") format("woff2")',
         fontDisplay: 'swap',
@@ -716,7 +716,7 @@ const Heading = tasty({
 Supply an array to register several variants of the same family:
 
 ```ts
-'@fontFace': {
+'@font-face': {
   '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' },
@@ -745,7 +745,7 @@ Supply an array to register several variants of the same family:
 
 ---
 
-## Counter Style (`@counterStyle`)
+## Counter Style (`@counter-style`)
 
 Define custom list markers via the CSS `@counter-style` at-rule. Keys are counter-style names, values are descriptor objects.
 
@@ -753,7 +753,7 @@ Define custom list markers via the CSS `@counter-style` at-rule. Keys are counte
 const EmojiList = tasty({
   tag: 'ol',
   styles: {
-    '@counterStyle': {
+    '@counter-style': {
       thumbs: {
         system: 'cyclic',
         symbols: '"👍"',
@@ -784,6 +784,66 @@ const EmojiList = tasty({
 
 ---
 
+## Functions (`@function`)
+
+Define reusable, parameterized CSS [custom functions](https://developer.mozilla.org/en-US/docs/Web/CSS/@function) via the CSS `@function` at-rule. A custom function takes parameters and returns a single value — like a dynamic custom property.
+
+The token convention follows Tasty's `$` vs `$$` distinction:
+
+- **`$$name`** — the literal callable name (`--name`). Used for the **definition key** and for **invocation** `$$name(...)`, mirroring the existing `$$gradient-angle` → `--gradient-angle` sugar. The definition key matches the call site.
+- **`$name`** — a custom-property declaration/reference (`var(--name)`). Used for **parameters** and **local variables**, exactly like declaring custom props in a styles object.
+- **Local variables** are declared directly as `$name` keys on the descriptor — the body reads like a mini styles object.
+- `result`, local-variable values, and parameter `default` values flow through the full Tasty DSL, so units (`2x`), color tokens (`#theme`), auto-calc (`(-1 * $value)` → `calc(-1 * var(--value))`), and fallbacks (`($shadow-color, black)` → `var(--shadow-color, black)`) all work.
+
+```ts
+const Box = tasty({
+  styles: {
+    '@function': {
+      // simplest: one bare param + result (auto-calc, no explicit calc())
+      '$$negative': { args: ['$value'], result: '(-1 * $value)' },
+
+      // typed param + default + return type + local variable
+      '$$shadow': {
+        args: { '$shadow-color': { syntax: '<color>', default: 'inherit' } },
+        returns: '<color>',
+        '$offset': '2px', // local variable
+        result: '$offset $offset ($shadow-color, black)',
+      },
+    },
+    marginTop: '$$negative(10px)', // → margin-top: --negative(10px)
+    boxShadow: '$$shadow(#accent)', // → box-shadow: --shadow(var(--accent-color))
+  },
+});
+```
+
+Generated CSS:
+
+```css
+@function --negative(--value) { result: calc(-1 * var(--value)); }
+@function --shadow(--shadow-color <color>: inherit) returns <color> {
+  --offset: 2px;
+  result: var(--offset) var(--offset) var(--shadow-color, black);
+}
+.t0 { margin-top: --negative(10px); box-shadow: --shadow(var(--accent-color)); }
+```
+
+### Descriptor shape
+
+| Field | Type | Notes |
+|---|---|---|
+| `result` (required) | `string` | The `result:` value, parsed through the Tasty DSL. |
+| `args` | `string[]` \| `Record<string, FunctionParameter>` | Ordered parameters. Array form lists bare names; object form maps names to type/default. |
+| `returns` | `string` | Optional return type, e.g. `'<color>'`. |
+| `$name` keys | `string \| number` | Any `$name` key declares a local variable `--name` (value parsed). |
+
+A `FunctionParameter` is one of: `true` (bare param), a string CSS type shorthand (`'<length>'`), or `{ syntax?: string; default?: string | number }`.
+
+Functions can also be registered with the [`useFunction`](react-api.md#usefunction) hook or globally via [`configure({ functions })`](configuration.md#functions) (the same map also accepts bare-key parse functions).
+
+> `@function` is permanent — injected once and never cleaned up, like `@counter-style`. It is an experimental CSS feature ([Chrome 139+](https://developer.mozilla.org/en-US/docs/Web/CSS/@function)); unsupported browsers safely ignore the native rule, so use it as progressive enhancement — or enable the [`configure({ polyfills: { functions: true } })`](configuration.md#polyfills) inline polyfill to expand `$$name(...)` calls into plain CSS for full cross-browser support.
+
+---
+
 ## Style Properties
 
 For a complete reference of all enhanced style properties — syntax, values, modifiers, and recommendations — see **[Style Properties Reference](styles.md)**.