@tenphi/tasty 3.9.2 → 3.9.4

package/docs/dsl.md

@@ -54,6 +54,8 @@ fill: {
 }
 ```
 
+Modifier and class names start with a letter and may be a single letter (`x` → `[data-x]`, `.x`). Tasty emits an `INVALID_STATE_KEY` warning for a key it cannot fully read and skips the unreadable parts. That covers characters outside the notation (`1st`, or `@media (w < 600px)` with a space before the parenthesis), an operator missing a state (`hovered &`), and two states with no operator between them (`hovered focused`). A partly read key can apply in states you did not mean, so fix the key rather than rely on what it produces.
+
 #### Default State Ordering
 
 Key order sets priority — later keys win and turn off earlier ones via negation. The bare default (`''`) is the lowest-priority state, so it **must be the first key**. If it appears after other states, Tasty moves it to the front and emits a dev warning (`MISPLACED_DEFAULT_STATE`); otherwise it would override every state above it.
@@ -536,13 +538,16 @@ Container style queries use `$prop` (boolean) or `$prop=value` syntax, which map
 
 ### `@supports(...)` — Feature Queries
 
-Feature queries test CSS property support. Use `$` as the first argument to test selector support:
+Feature queries test CSS property support and accept CSS support functions such
+as `at-rule()`. Use `$` as the first argument to test selector support:
 
-| Tasty syntax                | CSS output                        |
-| --------------------------- | --------------------------------- |
-| `@supports(display: grid)`  | `@supports (display: grid)`       |
-| `@supports($, :has(*))`     | `@supports selector(:has(*))`     |
-| `!@supports(display: grid)` | `@supports (not (display: grid))` |
+| Tasty syntax                 | CSS output                         |
+| ---------------------------- | ---------------------------------- |
+| `@supports(display: grid)`   | `@supports (display: grid)`        |
+| `@supports($, :has(*))`       | `@supports selector(:has(*))`      |
+| `@supports(at-rule(@scope))`  | `@supports (at-rule(@scope))`      |
+| `!@supports(display: grid)`  | `@supports (not (display: grid))`  |
+| `!@supports(at-rule(@scope))` | `@supports (not (at-rule(@scope)))` |
 
 ```jsx
 display: {
@@ -551,6 +556,25 @@ display: {
 }
 ```
 
+`at-rule()` tests whether the browser supports the named at-rule. Its surrounding
+parentheses in Tasty's CSS output are valid CSS. Negation and combinations with
+other states use the same syntax as property queries:
+
+```jsx
+color: {
+  _: 'red',
+  '@supports(at-rule(@scope)) & @supports(display: grid)': 'blue',
+}
+```
+
+Use `_` to keep a base value when a browser cannot evaluate a query. A support
+query only detects a browser feature; it does not add an API for authoring the
+queried at-rule in a Tasty style object. For conditional stylesheet imports such
+as `@import url("scoped.css") supports(at-rule(@scope));`, use an ordinary CSS
+stylesheet or document-level `useRawCSS()`. Put imports before other rules in
+that stylesheet. Imports cannot be used in constructable stylesheets, including
+Tasty's adopted-sheet mode for Shadow DOM.
+
 ### `_` — Fallback Floor
 
 By default Tasty makes states **mutually exclusive**: a higher-priority state
@@ -701,7 +725,7 @@ const FadeIn = tasty({
   styles: {
     opacity: { '': '1', '@starting': '0' },
     transform: { '': 'scale(1)', '@starting': 'scale(0.95)' },
-    transition: 'opacity 0.3s, translate 0.3s',
+    transition: 'opacity, translate',
   },
 });
 ```
@@ -833,7 +857,7 @@ const AnimatedGradient = tasty({
     '$gradient-angle': '0deg',
     '#theme': 'okhst(280 80% 50%)',
     image: 'linear-gradient($gradient-angle, #theme, #clear)',
-    transition: '$$gradient-angle 0.3s, ##theme 0.3s',
+    transition: '$$gradient-angle, ##theme',
   },
 });
 ```

package/docs/getting-started.md

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

package/docs/methodology.md

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

package/docs/pipeline.md

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

package/docs/plugins.md

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

package/docs/styles.md

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

package/docs/tasty-static.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenphi/tasty",
-  "version": "3.9.2",
+  "version": "3.9.4",
   "description": "A design-system-integrated styling system and DSL for concise, state-aware UI styling",
   "type": "module",
   "main": "./dist/index.js",