@tenphi/tasty 3.11.0 → 3.11.2

package/docs/injector.md

@@ -269,6 +269,8 @@ Dispose, ref-counted cleanup and GC therefore behave identically in every mode.
 
 `gc({ force: true })` and `cleanup()` take bands 4 and 5 together, ignoring capacity. Band 3 is spared even then: an explicit cleanup is still no reason to take rules from a render that has not committed yet.
 
+`tasty()` components cache the class names they computed, so a re-render with the same styles skips the pipeline. Whenever `gc()`, `cleanup()` or `destroy()` deletes rules, those caches are dropped too, so a component whose CSS was collected injects it again on its next render.
+
 > **Why band 3 exists.** Rendering is not commit-aware: a render can resolve a class and commit it a little later, and in between nothing on the page carries it. From outside React that is indistinguishable from a class that is finished, so collection does not try to tell them apart — it leaves alone anything only just noticed to be cold. A render would have to stay pending for the whole window to lose its rules, and it gets them back on its next render.
 >
 > The clock starts when a sweep *notices*, not when the element actually left — nothing observes that moment, so starting it at the sighting is what gives every class the same full window however long ago it went.
@@ -353,7 +355,7 @@ const button2 = inject([rule], { cacheKey: 'button' });
 console.log(button1.className === button2.className); // true
 ```
 
-Without `cacheKey` the class name still matches (it hashes the rules), but the rule is inserted again and the pin count restarts at 1.
+Without `cacheKey` the class name is a hash of the rules, so injecting the same rules again reuses the class the same way: the rules are written once, and each call adds a pin that its own `dispose()` releases.
 
 ### Pinning
 

package/docs/methodology.md

@@ -242,7 +242,7 @@ const Button = tasty({
 <Button variant="danger" size="sm" isLoading />;
 ```
 
-`variant` is typed from the variant keys, the `default` variant applies when no `variant` prop is passed, and only variants that render emit CSS. See [React API — Variants](react-api.md#variants).
+`variant` is typed from the variant keys, the `default` variant applies when no `variant` prop is passed (set the `variant` option, as in `variant: 'danger'`, to fall back to another one), and only variants that render emit CSS. See [React API — Variants](react-api.md#variants).
 
 ---
 
@@ -359,9 +359,9 @@ const LargeCard = tasty(Card, {
 
 Why? Styled wrappers are:
 
-- **Stable** — the style object is defined once at module level, not recreated on every render
+- **Stable** — the style object is defined once at module level, so Tasty merges and computes it once instead of on every render
 - **Composable** — another engineer can extend `LargeCard` further
-- **Inspectable** — give it a `qa` (`tasty(Card, { qa: 'LargeCard', styles })`) and it appears as `TastyWrappedComponent(LargeCard)` in React DevTools and as `data-qa="LargeCard"` in the DOM
+- **Inspectable** — give it a `qa` (`tasty(Card, { qa: 'LargeCard', styles })`) and it appears as `data-qa="LargeCard"` in the DOM; React DevTools shows it as `TastyWrappedComponent(…)` around the base's name
 - **Lint-friendly** — the ESLint plugin's `no-styles-prop` rule flags direct usage
 
 The `styles` prop exists as an escape hatch — for prototyping, one-off overrides during development, or cases where wrapping is impractical. It should not be the default way product engineers customize components.
@@ -382,7 +382,7 @@ See [Best practices](#best-practices) below for the full list of do's and don'ts
 
 ## Wrapping and extension
 
-`tasty(Base, { styles })` is the primary extension mechanism. It creates a new component whose styles are merged with the base component's styles.
+`tasty(Base, { styles })` is the primary extension mechanism. It creates a new component whose styles are merged with the base component's styles. The extension can also declare its own `styleProps`, `modProps`, `tokenProps`, `variants`, and `elements`, and it keeps the base's sub-elements — see [React API — Extend an existing component](react-api.md#extend-an-existing-component).
 
 ```tsx
 import { Button } from 'my-ds';
@@ -478,10 +478,10 @@ This is preferred over `<Card styles={{ border: '1bw solid #danger' }}>` because
 
 1. The styles live in one module-level definition instead of being rebuilt inside render
 2. `DangerCard` can be extended further by others
-3. It is searchable in code, and named in DevTools once you give it a `qa`
+3. It is searchable in code, and carries `data-qa` in the DOM once you give it a `qa`
 4. The ESLint `no-styles-prop` rule encourages this pattern
 
-A wrapper does not re-expose the base's sub-element components: `DangerCard.Title` is `undefined` and not part of its type. Keep using the base's parts inside it — `<DangerCard><Card.Title>…</Card.Title></DangerCard>`. The wrapper's `Title` styles still apply, because they target `[data-element="Title"]`.
+A wrapper keeps the base's sub-element components, typed: `DangerCard.Title` is `Card.Title`, so `<DangerCard><DangerCard.Title>…</DangerCard.Title></DangerCard>` works. The wrapper's `Title` styles apply to it, because they target `[data-element="Title"]`.
 
 ---
 
@@ -618,7 +618,7 @@ const Card = tasty({
 });
 ```
 
-Modifiers are compiled into exclusive selectors once. Changing `styles` at runtime forces Tasty to regenerate and re-inject CSS. `tasty/no-styles-prop` and `tasty/no-runtime-styles-mutation` flag these patterns.
+Modifiers are compiled into exclusive selectors once. A `styles` object that stays the same between renders (a module-level constant or a memoized object) is merged and computed once, but a new object on every render is merged and computed on every render, and each new value generates and injects new CSS. `tasty/no-styles-prop` and `tasty/no-runtime-styles-mutation` flag these patterns.
 
 ### Overusing style prop
 

package/docs/migration-v3.md

@@ -204,7 +204,7 @@ The build-time extraction Next.js wrapper already lived under the `zero` namespa
 
 **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.
+**`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. Since 3.11 the extension form applies them as the element factory does; see [Extend an existing component](react-api.md#extend-an-existing-component).
 
 **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).
 

package/docs/pipeline.md

@@ -522,7 +522,7 @@ Converts condition trees into actual CSS selectors and at-rules.
 
 5. **`:where()` specificity equalization**: Every stateful part of the selector is wrapped in `:where(...)` so it contributes **zero specificity**:
    - the flat root modifiers + pseudos and the root element's `:is()`/`:not()` groups are combined into one `:where(...)` (`buildSelectorFromVariant`);
-   - the sub-element (`@own`) groups are wrapped in a **separate** `:where(...)` so the sub-element's structural `[data-element="X"]` specificity is preserved while its states are zeroed;
+   - the sub-element (`@own`) groups are wrapped in a **separate** `:where(...)` so the sub-element's structural `[data-element="X"]` specificity is preserved while its states are zeroed. When the suffix ends in a pseudo-element, these are the pseudo-element's own states and stay after it (`a::before:where(:hover)`). States a pseudo-element can't have (attributes, modifiers, classes, tree-structural pseudo-classes) are dropped with a `PSEUDO_ELEMENT_STATE_IGNORED` warning before Stage 0, using the CSS language alone, never per-browser support (`pseudo-element-states.ts`). A direct selector that ends in a pseudo-element (`.card::before`) is rendered separately: its root states are checked the same way and go after the pseudo-element, its `@parent` segments before it, at the `pseudoElementAt` each `CSSRule` records;
    - `@parent` ancestors (`parentGroupsToCSS`) become `:where(... *)` / `:where(:not(... *))`;
    - the `@root` context prefix (`rootStateToPrefix`) becomes `:where(:root...)` (zeroing the `:root` pseudo too). When a direct selector can only match the root itself (`:root`, `html`, `:where(:root)`), the state segment joins it instead — `:root:where([data-schema="dark"])` — since an ancestor prefix would ask for a `:root` inside the root.
 

package/docs/plugins.md

@@ -69,7 +69,7 @@ Two distinctions do most of the work:
 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.
+- Return a `CSSMap` with **kebab-case** keys, an array of them, or nothing. `$` is a selector suffix, not a property. A property whose value is an array gets one declaration per entry, for fallback chains.
 - 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.
 

package/docs/react-api.md

@@ -2,7 +2,7 @@
 
 Use `tasty()` to turn state-aware style definitions into normal React components, extend existing Tasty components, and expose typed styling APIs to consumers.
 
-Every Tasty style function except `useStyles()` — `tasty()` components, `computeStyles()`, `useGlobalStyles()`, `useRawCSS()`, `useKeyframes()`, `useProperty()`, `useFontFace()`, `useCounterStyle()`, and `useFunction()` — is hook-free and works in React Server Components with no `'use client'` directive. `useStyles()` reads the `TastyRegistry` collector from React context, so it is a real hook; in Server Components and outside React, call `computeStyles()` instead. For state maps, tokens, units, and extension semantics, see [Style DSL](dsl.md). For global configuration, see [Configuration](configuration.md). For the broader docs map, see the [Docs Hub](README.md).
+Every Tasty style function — `tasty()` components, `computeStyles()`, `useStyles()`, `useGlobalStyles()`, `useRawCSS()`, `useKeyframes()`, `useProperty()`, `useFontFace()`, `useCounterStyle()`, and `useFunction()` — works in React Server Components with no `'use client'` directive. All of them except `useStyles()` are hook-free. `useStyles()` reads the `TastyRegistry` collector from React context on the client, so it is a real hook there; outside React, call `computeStyles()` instead. For state maps, tokens, units, and extension semantics, see [Style DSL](dsl.md). For global configuration, see [Configuration](configuration.md). For the broader docs map, see the [Docs Hub](README.md).
 
 > **Note:** This file was previously named `runtime.md`. All functionality documented here works in both server and client contexts — "runtime" referred to style computation during React rendering, not to client-side JavaScript.
 
@@ -44,7 +44,29 @@ const PrimaryButton = tasty(Button, {
 
 Style maps merge intelligently — see [Style DSL — Extending vs. Replacing State Maps](dsl.md#extending-vs-replacing-state-maps) for extend mode, replace mode, `@inherit`, `null`, and `false` tombstones.
 
-The extension form forwards props; it does not re-run the factory. `styleProps`, `modProps`, `tokenProps`, `variants`, and `elements` passed to `tasty(Component, …)` are ignored even though they type-check, and the base's sub-components are not copied (`tasty(Card, …).Title` is `undefined`). Declare them on the base component, or create the component with `tasty({ … })` directly.
+The extension form takes the same component options as `tasty({ … })`:
+
+```jsx
+const ActionCard = tasty(Card, {
+  styles: { fill: { '': '#surface', isRaised: '#surface-raised' } },
+  styleProps: ['gap'] as const, // gap="2x" becomes a style
+  modProps: ['isRaised'] as const, // isRaised becomes a mod (data-is-raised)
+  tokenProps: ['accentColor'] as const, // accentColor sets the #accent token
+  variants: {
+    plain: { border: 0 },
+    framed: { border: '2bw #accent' },
+  },
+  variant: 'framed', // applied when no variant prop is passed
+  elements: { Footer: 'footer' },
+});
+
+<ActionCard gap="2x" isRaised accentColor="#purple">
+  <ActionCard.Title>Kept from Card</ActionCard.Title>
+  <ActionCard.Footer>Added here</ActionCard.Footer>
+</ActionCard>;
+```
+
+The extension turns its own `styleProps`, `modProps`, and `tokenProps` into the `styles`, `mods`, and `tokens` it passes to the base, which renders them as usual: mods as `data-*` attributes, tokens as inline custom properties. Its `variants` merge over its `styles`, and the `variant` prop is still forwarded, so it selects the base's own variants too and accepts either set's names. Both sets share that one prop, so a name only one of them defines leaves the other at its fallback: if `Card` had an `accent` variant, `variant="accent"` would apply it together with `framed`, and `variant="plain"` would leave `Card` on its default. For two independent choices, give one of them its own prop, such as a `modProps` value list. `elements` adds sub-components, and the base's are kept: `ActionCard.Title` is `Card.Title`. The returned component is typed with all of these props and sub-components.
 
 `tasty(Component, ...)` always wraps `Component` and forwards every prop to it, so `Component` must be Tasty-aware (i.e. it accepts `styles`, `mods`, `qa`, etc. and renders them through its own Tasty pipeline). To apply styles to a third-party component or a string DOM tag via `className`, use the options-only form with `as`:
 
@@ -303,6 +325,22 @@ const Button = tasty({
 
 With `variant` omitted, or set to a key `variants` does not define, the `default` variant applies; without a `default` key only the base `styles` apply. `variant` is typed from the variant keys.
 
+To fall back to another variant instead, name it in the `variant` option:
+
+```jsx
+const Button = tasty({
+  styles: { padding: '2x 4x' },
+  variants: {
+    primary: { fill: '#blue', color: '#white' },
+    danger: { fill: '#red', color: '#white' },
+  },
+  variant: 'primary',
+});
+
+<Button>Save</Button>; // primary
+<Button variant="danger">Delete</Button>;
+```
+
 ### Extending Variants with Base State Maps
 
 When base `styles` contain an extend-mode state map (an object **without** a `''` key), it is applied **after** the variant merge. This lets you add or override states across all variants without repeating yourself:
@@ -413,13 +451,13 @@ On the client, CSS is injected synchronously into the DOM (idempotent via the in
 
 ## Style Functions
 
-All style functions below except `useStyles()` are plain functions, not React hooks, and work in client components, SSR with a `ServerStyleCollector`, and React Server Components. They keep the `use` prefix for backward compatibility.
+All style functions below work in client components, SSR with a `ServerStyleCollector`, and React Server Components. All except `useStyles()` are plain functions, not React hooks; they keep the `use` prefix for backward compatibility.
 
 In server-only contexts, components that use only Tasty style functions ship no Tasty styling runtime. Astro without `client:*` directives produces no client JavaScript; server-only Next.js RSC follows the same Tasty architecture, while final output depends on the application deployment. Tasty never forces the `'use client'` boundary — that decision belongs to your component when it needs React interactivity (state, effects, event handlers).
 
 ### useStyles
 
-Generate a className from a style object. A thin wrapper around `computeStyles()` that also picks up the `TastyRegistry` collector through React context. That makes it a hook: call it inside a component, and not in a Server Component — use `computeStyles()` there.
+Generate a className from a style object. A thin wrapper around `computeStyles()` that also picks up the `TastyRegistry` collector through React context. That makes it a hook on the client: call it inside a component, and use `computeStyles()` outside React. It also works in a Server Component, where it skips the context lookup; like the other style functions there, it cannot emit CSS itself, so the next `tasty()` element in the tree emits it.
 
 ```tsx
 import { useStyles } from '@tenphi/tasty';
@@ -456,9 +494,13 @@ function ThemeStyles() {
 The selector can be a list (`'.uni-checkbox, uni-checkbox'`) — every item gets
 the states and sub-elements, with no `:is()` wrapping needed. Root states
 (`@root(...)`) on a selector that is the root itself (`:root`, `html`) apply to
-that element. Local `@keyframes` are injected with the rules, under the same
-resolved names `tasty()` components use, and `@starting` states emit
-`@starting-style`.
+that element. A selector that ends in a pseudo-element takes its states on the
+pseudo-element (`'.card::before'` with `:hover` gives
+`.card::before:where(:hover)`) and `@parent()` on the element before it.
+Attribute and modifier states, which a pseudo-element can't have, are ignored
+with a warning. Local `@keyframes` are injected with the rules,
+under the same resolved names `tasty()` components use, and `@starting` states
+emit `@starting-style`.
 
 A slot — the `id`, or the selector when no `id` is given — holds exactly one
 injection **per `root`**. So:
@@ -685,9 +727,10 @@ See the [Functions section of the DSL reference](dsl.md#functions-function) for
 
 - Styles are not updating: make sure `configure()` runs before first render, and verify the generated class name or global rule with [Debug Utilities](debug.md).
 - SSR output looks wrong: check the [SSR guide](ssr.md) for collector setup. All style functions discover the SSR collector via `AsyncLocalStorage` or the global getter registered by `TastyRegistry`.
+- "Server rendering without a style collector" in development: the server render has no request scope, so each `tasty()` element inlines its own CSS and configured globals are not emitted. Add `tastyIntegration()` (Astro), `TastyRegistry` (Next.js), or `runWithCollector()` — see the [SSR guide](ssr.md).
 - Animation/custom property issues: prefer `useKeyframes()` and `useProperty()` over raw CSS when you want Tasty to manage injection and SSR collection for you.
 - For dynamic styles that change over the component lifecycle, use the `id` option in `useGlobalStyles()` and `useRawCSS()` to enable update tracking.
-- RSC inline mode: CSS accumulated by standalone style functions (`useGlobalStyles`, `useRawCSS`, etc.) is flushed into inline `<style>` tags by the next `tasty()` component in the render tree. If your page uses only standalone style functions without any `tasty()` component, the CSS will not be emitted. Ensure at least one `tasty()` component is present in each RSC render tree.
+- RSC inline mode: CSS accumulated by standalone style functions (`useStyles`, `useGlobalStyles`, `useRawCSS`, etc.) is flushed into inline `<style>` tags by the next `tasty()` component in the render tree. If your page uses only standalone style functions without any `tasty()` component, the CSS will not be emitted. Ensure at least one `tasty()` component is present in each RSC render tree.
 
 ---
 

package/docs/ssr.md

@@ -187,14 +187,14 @@ meaning; use root-relative, absolute, or data URLs.
 
 ### Using Tasty in Server Components
 
-Every Tasty style function except `useStyles()` is hook-free and needs no `'use client'`, so it can be used directly in React Server Components:
+Every Tasty style function needs no `'use client'`, so it can be used directly in React Server Components:
 
 - `tasty()` components — dynamic `styleProps` like `<Grid flow="column">` work normally
-- `computeStyles()` — the hook-free equivalent of `useStyles()`, which reads React context and cannot run in a Server Component
+- `useStyles()` and its hook-free equivalent `computeStyles()` — a class name for any element
 - `useGlobalStyles()`, `useRawCSS()` — inject styles by selector
 - `useKeyframes()`, `useProperty()`, `useFontFace()`, `useCounterStyle()`, `useFunction()` — inject ancillary CSS rules
 
-Next.js renders Server Components in a separate module graph that cannot see the collector `TastyRegistry` registers, so their CSS takes the RSC inline path: it is accumulated in a per-request `React.cache` and emitted as an inline `<style>` tag by the next `tasty()` component in the tree. Standalone style functions cannot emit CSS on their own, so make sure a `tasty()` component renders after them in every RSC tree. The RSC path does not emit configured globals (tokens, `@property`, `globalStyles`); those come from `TastyRegistry`'s collector or the `withTastyNext()` shared stylesheet. For the same reason, import the module that calls `configure()` from `app/layout.tsx` as well as from the registry module, so the RSC graph sees the same states, recipes, and units.
+Next.js renders Server Components in a separate module graph that cannot see the collector `TastyRegistry` registers, so their CSS takes the RSC inline path: it is accumulated in a per-request `React.cache` and emitted as an inline `<style>` tag by the next `tasty()` component in the tree. Standalone style functions, `useStyles()` included, cannot emit CSS on their own, so make sure a `tasty()` component renders after them in every RSC tree. The RSC path does not emit configured globals (tokens, `@property`, `globalStyles`); those come from `TastyRegistry`'s collector or the `withTastyNext()` shared stylesheet. For the same reason, import the module that calls `configure()` from `app/layout.tsx` as well as from the registry module, so the RSC graph sees the same states, recipes, and units.
 
 ### Options
 
@@ -241,9 +241,9 @@ import { tasty } from '@tenphi/tasty';
 const Card = tasty({
   styles: {
     padding: '4x',
-    fill: '#surface',
+    fill: '#fff',
     radius: '1r',
-    border: true,
+    border: '1bw solid #ddd',
   },
 });
 
@@ -263,9 +263,9 @@ import Card from '../components/Card.tsx';
 </html>
 ```
 
-**Trade-offs**: Astro renders React with the standard `react` build, where `React.cache` does nothing, so there is no per-request style cache. Every `tasty()` element inlines the full CSS for its classes, even when the same component renders twice. Configured globals (`:root` tokens, `@property` defaults, `globalStyles`, `@font-face`) are never emitted, because only the SSR collector emits them, and CSS from `useGlobalStyles`, `useRawCSS`, `useKeyframes`, `useProperty`, `useFontFace`, `useCounterStyle`, and `useFunction` is dropped.
+**Trade-offs**: Astro renders React with the standard `react` build, where `React.cache` does nothing, so there is no per-request style cache. Every `tasty()` element inlines the full CSS for its classes, even when the same component renders twice. Configured globals (`:root` tokens, `@property` defaults, `globalStyles`, `@font-face`) are never emitted, because only the SSR collector emits them, and CSS from `useGlobalStyles`, `useRawCSS`, `useKeyframes`, `useProperty`, `useFontFace`, `useCounterStyle`, and `useFunction` is dropped. Without the [default properties](dsl.md#default-properties), styles that read them resolve to nothing: `border: true` and `outline: true` draw nothing, and `transition` with no duration does not animate. In development, Tasty warns once that it is rendering without a style collector.
 
-Best for trying Tasty out with unconfigured styles. Use `tastyIntegration()` for anything that relies on `configure()`.
+Best for trying Tasty out with plain values, as above. Use `tastyIntegration()` for anything that relies on `configure()` or on Tasty's default tokens.
 
 ### Astro Integration (recommended)
 
@@ -463,14 +463,14 @@ const fullHtml = `
 
 ```tsx
 // ── Client ──────────────────────────────────────────────
-// Browser-safe: runs hydrateTastyClasses() with window.__TASTY__ on import
-import '@tenphi/tasty/ssr/astro-client';
+import { hydrateTastyClasses } from '@tenphi/tasty/ssr/client';
 import { hydrateRoot } from 'react-dom/client';
 
+hydrateTastyClasses(); // reads window.__TASTY__
 hydrateRoot(document.getElementById('root'), <App />);
 ```
 
-`@tenphi/tasty/ssr` is server-only: it imports `node:async_hooks`, and in a browser bundle rendering throws `AsyncLocalStorage is not a constructor`. Despite its name, `@tenphi/tasty/ssr/astro-client` works with any framework.
+`@tenphi/tasty/ssr/client` is the browser half: it exports `hydrateTastyClasses()` and has no import side effects. A module shared by the server and the client can import `@tenphi/tasty/ssr` too. It is safe in a browser bundle, where there is no server collector to find, and only `runWithCollector()` throws there.
 
 ### Streaming SSR
 
@@ -517,14 +517,15 @@ runWithCollector(collector, () => {
 
 ### Entry points
 
-| Import path                                                                                                                                                                                      | Description                                                                                                                                                                                                     |
-| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@tenphi/tasty/ssr`                                                                                                                                                                              | Core SSR API (server-only): `ServerStyleCollector`, `createServerStyleCollector`, `runWithCollector`, `getSSRCollector`, `hydrateTastyClasses`; types `ServerStyleArtifact`, `ServerStyleArtifactKind`          |
-| `@tenphi/tasty/ssr/next`                                                                                                                                                                         | Next.js App Router: `TastyRegistry` component                                                                                                                                                                   |
-| `@tenphi/tasty/ssr/next-config`                                                                                                                                                                  | Next.js config wrapper: shared, content-hashed global stylesheet                                                                                                                                                |
-| `@tenphi/tasty/ssr/astro`                                                                                                                                                                        | Astro: `tastyIntegration`, `tastyMiddleware`                                                                                                                                                                    |
-| `@tenphi/tasty/ssr/astro-client`                                                                                                                                                                 | Astro: client-side cache hydration (auto-injected by integration, or import manually)                                                                                                                           |
-| `@tenphi/tasty/ssr/astro-middleware`<br />`@tenphi/tasty/ssr/astro-middleware-static`<br />`@tenphi/tasty/ssr/astro-middleware-extract`<br />`@tenphi/tasty/ssr/astro-middleware-extract-static` | Astro: the middleware entrypoints `tastyIntegration()` registers via `addMiddleware()`. Exported so Astro can resolve them by specifier; you should not import them. For manual setups use `tastyMiddleware()`. |
+| Import path                                                                                                                                                                                      | Description                                                                                                                                                                                                                                                         |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@tenphi/tasty/ssr`                                                                                                                                                                              | Core SSR API: `ServerStyleCollector`, `createServerStyleCollector`, `runWithCollector`, `getSSRCollector`, `hydrateTastyClasses`; types `ServerStyleArtifact`, `ServerStyleArtifactKind`. Safe to import in a browser bundle; `runWithCollector()` needs the server |
+| `@tenphi/tasty/ssr/client`                                                                                                                                                                       | Browser-safe client hydration for any framework: `hydrateTastyClasses`, no import side effects                                                                                                                                                                      |
+| `@tenphi/tasty/ssr/next`                                                                                                                                                                         | Next.js App Router: `TastyRegistry` component                                                                                                                                                                                                                       |
+| `@tenphi/tasty/ssr/next-config`                                                                                                                                                                  | Next.js config wrapper: shared, content-hashed global stylesheet                                                                                                                                                                                                    |
+| `@tenphi/tasty/ssr/astro`                                                                                                                                                                        | Astro: `tastyIntegration`, `tastyMiddleware`                                                                                                                                                                                                                        |
+| `@tenphi/tasty/ssr/astro-client`                                                                                                                                                                 | Astro: client-side cache hydration (auto-injected by integration, or import manually)                                                                                                                                                                               |
+| `@tenphi/tasty/ssr/astro-middleware`<br />`@tenphi/tasty/ssr/astro-middleware-static`<br />`@tenphi/tasty/ssr/astro-middleware-extract`<br />`@tenphi/tasty/ssr/astro-middleware-extract-static` | Astro: the middleware entrypoints `tastyIntegration()` registers via `addMiddleware()`. Exported so Astro can resolve them by specifier; you should not import them. For manual setups use `tastyMiddleware()`.                                                     |
 
 ### `ServerStyleCollector`
 
@@ -587,11 +588,11 @@ Astro middleware factory. Use for manual middleware composition.
 
 ### `hydrateTastyClasses(classes?)`
 
-Pre-populate the client injector's rules map with class names rendered on the server, marking them as already present in the DOM so `computeStyles()` skips re-injection during hydration. When called without arguments, reads the class list from `window.__TASTY__` (populated by the streaming `<script>` tags emitted during SSR).
+Exported from `@tenphi/tasty/ssr/client` and `@tenphi/tasty/ssr`. Pre-populate the client injector's rules map with class names rendered on the server, marking them as already present in the DOM so `computeStyles()` skips re-injection during hydration. When called without arguments, reads the class list from `window.__TASTY__` (populated by the streaming `<script>` tags emitted during SSR).
 
 ### `runWithCollector(collector, fn)`
 
-Run a function with a `ServerStyleCollector` bound to the current async context via `AsyncLocalStorage`. All style function calls within `fn` (and async continuations) — including `computeStyles()`, `useStyles()`, `useGlobalStyles()`, `useRawCSS()`, `useKeyframes()`, `useProperty()`, `useFontFace()`, `useCounterStyle()`, and `useFunction()` — will find this collector. Returns `fn`'s return value, synchronously unless `fn` returns a promise.
+Run a function with a `ServerStyleCollector` bound to the current async context via `AsyncLocalStorage`. All style function calls within `fn` (and async continuations) — including `computeStyles()`, `useStyles()`, `useGlobalStyles()`, `useRawCSS()`, `useKeyframes()`, `useProperty()`, `useFontFace()`, `useCounterStyle()`, and `useFunction()` — will find this collector. Returns `fn`'s return value, synchronously unless `fn` returns a promise. Throws where `AsyncLocalStorage` is unavailable, such as in a browser.
 
 ---
 
@@ -603,7 +604,7 @@ The `TastyRegistry` or `tastyIntegration` is missing. Ensure your layout wraps t
 
 ### Hydration mismatch warnings
 
-Class names are content hashes of the resolved styles, so render order does not affect them. Unnamed `useKeyframes()` and `useCounterStyle()` names are counters (`tk0`, `tc0`) on both server and client; pass `name` if the two sides can call them in a different order. If you see mismatches, ensure `hydrateTastyClasses()` runs before React hydration. For Next.js, this is automatic. For Astro with `tastyIntegration()`, this is also automatic. For manual Astro middleware setups, import `@tenphi/tasty/ssr/astro-client` in your island components. For custom setups, import `@tenphi/tasty/ssr/astro-client` before `hydrateRoot()`.
+Class names are content hashes of the resolved styles, so render order does not affect them. Unnamed `useKeyframes()` and `useCounterStyle()` names are counters (`tk0`, `tc0`) on both server and client; pass `name` if the two sides can call them in a different order. If you see mismatches, ensure `hydrateTastyClasses()` runs before React hydration. For Next.js, this is automatic. For Astro with `tastyIntegration()`, this is also automatic. For manual Astro middleware setups, import `@tenphi/tasty/ssr/astro-client` in your island components. For custom setups, call `hydrateTastyClasses()` from `@tenphi/tasty/ssr/client` before `hydrateRoot()`.
 
 Class names are also derived from the _resolved_ styles, so the server and the client must configure Tasty identically. Anything that changes what a component's styles resolve to will produce a mismatch if it is registered on only one side — `namePrefix`, `recipes`, `handlers`, and the `propHandlers` / `baseStyleProps` extension points described in [Plugins](plugins.md). Call the same `configure()` on both; global CSS is deduplicated automatically, so no `typeof window` guard is needed.
 
@@ -614,8 +615,9 @@ Class names are also derived from the _resolved_ styles, so the server and the c
 **Component CSS**: SSR `<style data-tasty-ssr>` tags remain in the DOM. The client injector creates separate `<style>` elements for any new styles. SSR styles are never modified or removed by the client. If this is a concern for very large apps, you can remove the SSR style tags and hydration scripts manually after hydration:
 
 ```tsx
-import '@tenphi/tasty/ssr/astro-client'; // runs hydrateTastyClasses()
+import { hydrateTastyClasses } from '@tenphi/tasty/ssr/client';
 
+hydrateTastyClasses();
 hydrateRoot(root, <App />);
 
 // Optional: remove SSR style tags and class-list scripts after hydration
@@ -627,4 +629,8 @@ document.querySelectorAll('script').forEach((el) => {
 
 ### `AsyncLocalStorage` not available
 
-`@tenphi/tasty/ssr` imports `node:async_hooks` and is server-only. In a browser bundle the module is stubbed and rendering throws `AsyncLocalStorage is not a constructor`. On the client, import `@tenphi/tasty/ssr/astro-client` (it works with any framework) or use `@tenphi/tasty/ssr/next`, which hydrates automatically.
+`runWithCollector()` throws `runWithCollector() needs AsyncLocalStorage from node:async_hooks` where the runtime has no `AsyncLocalStorage`, such as in a browser bundle. Call it on the server. The rest of `@tenphi/tasty/ssr` is safe to import in a browser bundle; on the client, call `hydrateTastyClasses()` from `@tenphi/tasty/ssr/client`, or use `@tenphi/tasty/ssr/next`, which hydrates automatically.
+
+### "Server rendering without a style collector" warning
+
+Tasty rendered on the server with no collector and no React Server Components request scope: Astro without `tastyIntegration()`, a client component server-rendered without `TastyRegistry`, or a custom setup that skips `runWithCollector()`. Each `tasty()` element then inlines all of its CSS, and configured globals (tokens, the default `@property` set, `globalStyles`, `@font-face`) and the CSS of the standalone style functions are not emitted. Add the integration for your framework. The warning is shown once, in development only.

package/docs/styles.md

@@ -197,6 +197,9 @@ Element width with min/max control. One, two, or three values set `min-width`, `
 | `"min 2x"` | `2x` | auto | initial |
 | `"max 100%"` | initial | auto | `100%` |
 | `"fixed 200px"` | `200px` | `200px` | `200px` |
+| `"min"` | `1x` | auto | initial |
+| `"max"` | initial | auto | `100%` |
+| `"fixed"` | `max-content` | `max-content` | `max-content` |
 
 **Keywords:** `stretch`, `max-content`, `min-content`, `fit-content`
 
@@ -312,6 +315,8 @@ Background color with design token support. Preferred over `backgroundColor` and
 
 When two colors are provided, the first sets the background color and the second is applied as an overlay gradient layer. This enables independent CSS transitions on each color. With `image` or `backgroundImage` on the same element, the image is layered over the overlay color in one `background-image`.
 
+There is no default fill color, so `fill: true` is ignored with a development warning. Use `false` for no fill.
+
 **Related deprecated props:** `backgroundColor` (use `fill`), `background` (overrides all background props when set — avoid).
 
 ### `image`
@@ -341,6 +346,7 @@ Text color with design token support.
 | `"#current.5"` | Current inherited color at 50% opacity |
 | `"(#primary, #secondary)"` | Fallback: use `#primary`, fall back to `#secondary` |
 | `"light-dark(#dark, #light)"` | CSS color function — see [CSS Color Functions](dsl.md#css-color-functions) |
+| `"#ddd"` | Hex literal, read as the `#ddd` token with the literal as fallback: `var(--ddd-color, #ddd)`, as in every color style |
 | `true` | `currentColor` |
 
 Also sets `$current-color` to the same color, for anything that needs the

package/docs/tasty-static.md

@@ -19,22 +19,25 @@ If the styles depend on props, keep `tasty()`: rendered only on the server, it a
 
 Build-time extraction is part of the main `@tenphi/tasty` package but requires additional peer dependencies depending on your setup:
 
-| Dependency                   | Version | Required for                                                                   |
-| ---------------------------- | ------- | ------------------------------------------------------------------------------ |
-| `@babel/core`                | >= 7.24 | Babel plugin (`@tenphi/tasty/babel-plugin`)                                    |
-| `@babel/helper-plugin-utils` | >= 7.24 | Babel plugin                                                                   |
-| `@babel/types`               | >= 7.24 | Babel plugin                                                                   |
-| `jiti`                       | >= 2.6  | Babel plugin and Next.js wrapper (imported on load, even without `configFile`) |
-| `babel-loader`               | any     | Next.js wrapper (`@tenphi/tasty/zero/next`)                                    |
+| Dependency                   | Version | Required for                                         |
+| ---------------------------- | ------- | ---------------------------------------------------- |
+| `@babel/core`                | >= 7.24 | Babel plugin (`@tenphi/tasty/babel-plugin`)          |
+| `@babel/helper-plugin-utils` | >= 7.24 | Babel plugin                                         |
+| `@babel/types`               | >= 7.24 | Babel plugin                                         |
+| `jiti`                       | >= 2.6  | `configFile` only (Babel plugin and Next.js wrapper) |
+| `babel-loader`               | any     | Next.js wrapper (`@tenphi/tasty/zero/next`)          |
 
-The Babel packages and `jiti` are optional peer dependencies of `@tenphi/tasty`; `babel-loader` is resolved from your project. Install what your setup requires:
+The Babel packages and `jiti` are optional peer dependencies of `@tenphi/tasty`; `babel-loader` is resolved from your project. `jiti` is loaded only to read a `configFile`, so a setup that passes `config` directly does not need it; without it, `configFile` fails with an error that says to install it. Install what your setup requires:
 
 ```bash
 # Any Babel-based setup (Vite, custom Babel config, etc.)
-pnpm add -D @babel/core @babel/helper-plugin-utils @babel/types jiti
+pnpm add -D @babel/core @babel/helper-plugin-utils @babel/types
 
 # Next.js
-pnpm add -D @babel/core @babel/helper-plugin-utils @babel/types jiti babel-loader
+pnpm add -D @babel/core @babel/helper-plugin-utils @babel/types babel-loader
+
+# Either, with configFile
+pnpm add -D jiti
 ```
 
 ---
@@ -173,7 +176,7 @@ module.exports = {
 | -------------------------- | ------------------------------------------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `output`                   | `string`                                         | `'tasty.css'` | Path for generated CSS file                                                                                                                                                                      |
 | `mode`                     | `'file' \| 'inject'`                             | `'file'`      | `'file'` writes CSS to disk; `'inject'` embeds CSS inline in JS (see [Inject Mode](#inject-mode))                                                                                                |
-| `configFile`               | `string`                                         | —             | Absolute path to a TS/JS module that default-exports a `TastyZeroConfig` object. JSON-serializable alternative to `config` — required for Turbopack.                                             |
+| `configFile`               | `string`                                         | —             | Absolute path to a TS/JS module that default-exports a `TastyZeroConfig` object. JSON-serializable alternative to `config` — required for Turbopack. Loaded with the optional `jiti` peer.       |
 | `config`                   | `TastyZeroConfig \| () => TastyZeroConfig`       | `{}`          | Inline config object or factory function. Takes precedence over `configFile`.                                                                                                                    |
 | `configDeps`               | `string[]`                                       | `[]`          | Absolute file paths that affect config (for cache invalidation)                                                                                                                                  |
 | `injectImport`             | `boolean`                                        | `true`        | Replace `@tenphi/tasty/static` imports with an import of the generated CSS file. Set to `false` to manage CSS imports manually.                                                                  |
@@ -185,7 +188,8 @@ module.exports = {
 | `config.keyframes`         | `Record<string, KeyframesSteps>`                 | —             | Global `@keyframes` definitions available to all `tastyStatic` calls                                                                                                                             |
 | `config.fontFaces`         | `Record<string, FontFaceInput>`                  | —             | Global `@font-face` definitions                                                                                                                                                                  |
 | `config.counterStyles`     | `Record<string, CounterStyleDescriptors>`        | —             | Global `@counter-style` definitions                                                                                                                                                              |
-| `config.units`             | `Record<string, string \| UnitHandler>`          | —             | Custom units for the style parser (merged with built-ins). E.g. `{ em: 'em', vw: 'vw' }`                                                                                                         |
+| `config.properties`        | `Record<string, PropertyDefinition>`             | —             | Global `@property` definitions, written with Tasty's [default properties](dsl.md#default-properties)                                                                                             |
+| `config.units`             | `Record<string, string \| UnitHandler>`          | —             | Custom units for the style parser (merged with built-ins). E.g. `{ u: 'var(--u)' }` makes `2u` compile to `calc(2 * var(--u))`. Native CSS units need no entry                                   |
 | `config.functions`         | `Record<string, FunctionDefinition \| Function>` | —             | Custom functions (merged). Bare keys → parse functions; `$$name` keys → declarative CSS `@function` definitions                                                                                  |
 | `config.polyfills`         | `{ functions?: boolean }`                        | `{}`          | Opt-in polyfills. `functions: true` inlines `@function` calls into plain CSS at build time                                                                                                       |
 | `config.plugins`           | `TastyPlugin[]`                                  | —             | Plugins that extend tasty with custom functions, units, states, and handlers                                                                                                                     |
@@ -286,7 +290,7 @@ export default withTastyZero({
 
 Starting with Next.js 16, Turbopack is the default bundler. `withTastyZero` supports it out of the box by injecting `turbopack.rules` with `babel-loader` and JSON-serializable options.
 
-The `configFile` option is key for Turbopack — it passes a file path (JSON-serializable) instead of a function, and the Babel plugin loads the config internally via jiti.
+The `configFile` option is key for Turbopack — it passes a file path (JSON-serializable) instead of a function, and the Babel plugin loads the config internally via `jiti`, which must be installed.
 
 **Requirements**: `babel-loader` must be installed in your project (see [Requirements](#requirements)):
 
@@ -331,7 +335,7 @@ extractStylesWithChunks({ display: 'flex', gap: '1u' });
 
 `configure()` takes the same options as the Babel plugin's `config` (see [Plugin Options](#plugin-options)) and replaces the previous configuration on each call; `resetConfig()` returns to the defaults. Options that shape the extracted rules apply — `states`, `units`, parse `functions`, `handlers`, `replaceTokens`, `recipes`, `plugins`, `namePrefix`. Definitions that become at-rules or global CSS of their own are not emitted with the rules: `tokens`, `globalStyles`, `fontFaces`, `counterStyles`, `properties` and `$$` `@function` definitions. Render tokens and global styles with `extractStylesForSelector(':root', tokens)` and `extractStylesForSelector(selector, styles)`.
 
-`extractConfigProperties()` returns the `@property` rules the Babel plugin writes at the top of its output: Tasty's default set (`#border`, `#outline`, `$gap`, `$radius`, `$transition`, …) overlaid with the configured `properties`. Emit them once per stylesheet. Style handlers read several of these tokens with no fallback of their own (`border: true` reads `#border`, `transition` reads `$transition`), so without them those declarations resolve to nothing.
+`extractConfigProperties()` returns the `@property` rules the Babel plugin writes at the top of its output: Tasty's [default set](dsl.md#default-properties) (`#border`, `#outline`, `$gap`, `$radius`, `$transition`, …) overlaid with the configured `properties`, or with the `properties` map you pass it. Emit them once per stylesheet. Style handlers read several of these tokens with no fallback of their own (`border: true` reads `#border`, `transition` reads `$transition`), so without them those declarations resolve to nothing.
 
 The configuration is process-wide and shared with the Babel plugin and the runtime `configure()` from `@tenphi/tasty`. The extractors re-apply their own configuration when the Babel plugin replaced it, but not after a runtime `configure()` — don't mix the runtime and build-time configuration in one process.
 
@@ -438,13 +442,19 @@ The `@tenphi/tasty/static` import becomes an import of the generated file (relat
 ```css
 /* Generated by @tenphi/tasty/zero - DO NOT EDIT */
 
+@property --tasty-second-fill-color {
+  syntax: '<color>';
+  inherits: false;
+  initial-value: transparent;
+}
+
 @property --current-color {
   syntax: '<color>';
   inherits: true;
   initial-value: currentcolor;
 }
 
-/* …the rest of Tasty's default @property rules (--gap, --radius, --white-color, …) */
+/* …the rest of Tasty's default @property rules (--white-color, --border-color, --gap, --transition, …), then config.properties */
 
 .ts3f783b.ts3f783b {
   color: var(--white-color);
@@ -465,7 +475,7 @@ The `@tenphi/tasty/static` import becomes an import of the generated file (relat
 }
 ```
 
-Styles are split into chunks (here appearance and spacing), each with its own class. Color tokens compile to custom properties: `#purple` becomes `var(--purple-color)`. Define it in `config.tokens` and the plugin writes it to `:root` at the top of the same file. Units are literal (`2x` is `16px`). Selector-mode rules use the selector as written, without the doubled specificity of class rules.
+The file starts with Tasty's [default `@property` rules](dsl.md#default-properties) and your `config.properties`, written once. Styles are split into chunks (here appearance and spacing), each with its own class. Color tokens compile to custom properties: `#purple` becomes `var(--purple-color)`. Define it in `config.tokens` and the plugin writes it to `:root` at the top of the same file. Units are literal (`2x` is `16px`). Selector-mode rules use the selector as written, without the doubled specificity of class rules.
 
 ---
 
@@ -537,6 +547,11 @@ tastyStatic('.heading', { preset: 'h1' });
 ```tsx
 import { injectCSS as _$i } from '@tenphi/tasty/static/inject';
 
+_$i(
+  '@property',
+  '@property --tasty-second-fill-color { … }\n@property --current-color { … }\n…',
+);
+
 const button =
   (_$i(
     'tsa903d6 ts070801',
@@ -553,6 +568,8 @@ const button =
 _$i('.heading', '.heading { font-size: var(--h1-font-size, …); … }');
 ```
 
+Each file that calls `tastyStatic()` starts by injecting Tasty's default `@property` rules and your `config.properties` under the `@property` id. `injectCSS()` skips an id it has already injected, so the page gets them once.
+
 ### Dev Mode / HMR
 
 Class names are content-hashed (`ts` + MD5). When styles change, a new hash produces a new `_$i` call that injects fresh CSS. The injector deduplicates by id, so unchanged styles are skipped. Old CSS stays in the DOM but is harmless since no elements reference those class names.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenphi/tasty",
-  "version": "3.11.0",
+  "version": "3.11.2",
   "description": "A design-system-integrated styling system and DSL for concise, state-aware UI styling",
   "type": "module",
   "main": "./dist/index.js",
@@ -211,7 +211,7 @@
       "name": "main (tasty)",
       "path": "dist/index.js",
       "import": "{ tasty }",
-      "limit": "52.67 kB"
+      "limit": "53.84 kB"
     },
     {
       "name": "main (StyleParser)",
@@ -235,7 +235,7 @@
       "name": "core (import *)",
       "path": "dist/core/index.js",
       "import": "*",
-      "limit": "55.23 kB"
+      "limit": "56.29 kB"
     },
     {
       "name": "static",
@@ -252,7 +252,7 @@
         "path",
         "crypto"
       ],
-      "limit": "39.13 kB"
+      "limit": "40.16 kB"
     },
     {
       "name": "babel-plugin",
@@ -265,7 +265,7 @@
         "node:module",
         "node:path"
       ],
-      "limit": "43.55 kB"
+      "limit": "44.79 kB"
     },
     {
       "name": "astro client",