Update docs for unified CSS runtime

Author: cray0000

docs/api/babel.md

@@ -21,7 +21,7 @@ module.exports = {
 |--------|------|---------|-------------|
 | `platform` | `'web'` \| `'ios'` \| `'android'` | `'web'` | Target platform |
 | `reactType` | `'react-native'` \| `'web'` | auto | React target type |
-| `cache` | `'teamplay'` | auto | Caching library |
+| `cache` | `'teamplay'` | auto | Legacy compatibility alias |
 | `transformPug` | `boolean` | `true` | Enable Pug transformation |
 | `transformCss` | `boolean` | `true` | Enable CSS transformation |
 
@@ -33,7 +33,7 @@ module.exports = {
   presets: [
     ['cssxjs/babel', {
       transformPug: false,      // Disable pug if not using it
-      cache: 'teamplay'         // Force teamplay caching
+      cache: 'teamplay'         // Legacy compatibility alias
     }]
   ]
 }
@@ -61,7 +61,9 @@ You can also set platform-specific variables in your Stylus code:
 
 ## Caching
 
-When `cache: 'teamplay'` is set (or auto-detected), the Babel transform generates code that integrates with [teamplay](https://github.com/startupjs/teamplay) for optimized style memoization.
+CSSX uses the built-in resolver cache by default. The old `cache: 'teamplay'`
+option is still accepted so existing configs do not break, but CSSX no longer
+imports Teamplay and components do not need `observer()`.
 
 See the [Caching guide](/guide/caching) for more details.
 
@@ -103,6 +105,7 @@ The Babel preset converts this into optimized runtime code that:
 - Compiles Stylus to style objects at build time
 - Connects `styleName` to the compiled styles
 - Injects part style props automatically
+- Re-renders only when used CSS variables or matching media queries change
 
 ## TypeScript
 

docs/api/css.md

@@ -122,6 +122,39 @@ The custom `u` unit works in `css` too:
 }
 ```
 
+Variables can appear anywhere CSS allows `var()`: whole values, parts of
+shorthands, comma-separated value chunks, and nested fallbacks.
+
+```css
+.card {
+  box-shadow: var(--shadow, 0 4px 12px rgba(0, 0, 0, 0.16));
+  border: var(--border-width, 1px) solid var(--border-color, #ddd);
+}
+```
+
+### JavaScript Interpolation
+
+Function-scoped `css` templates support JavaScript interpolation in CSS value
+positions:
+
+```jsx
+function Badge({ color, size }) {
+  return <View styleName="badge" />
+
+  css`
+    .badge {
+      background-color: ${color};
+      padding: ${size}px 12px;
+    }
+  `
+}
+```
+
+Interpolation is an alternative to `var()`. It is only supported in the same
+places a CSS value can use `var()`, and only inside function-scoped JS tagged
+templates. Module-level templates, imported CSS files, and runtime CSS strings
+must use plain CSS text.
+
 ### Part Selectors
 
 ```css
@@ -134,13 +167,73 @@ The custom `u` unit works in `css` too:
 }
 ```
 
+### Hover and Active Styles
+
+CSSX maps `:hover` and `:active` to the same output as `:part(hover)` and
+`:part(active)`. Components can receive those props as `hoverStyle` and
+`activeStyle`.
+
+```css
+.button:hover {
+  background-color: #0056b3;
+}
+
+.button:active {
+  transform: scale(0.97);
+}
+```
+
+### Filters and Background Images
+
+React Native supports `filter` and experimental background gradients in current
+versions. CSSX passes `filter` through and maps `background-image` to
+`experimental_backgroundImage` on React Native.
+
+```css
+.hero {
+  filter: blur(8px) brightness(0.8);
+  background-image:
+    linear-gradient(0deg, white, rgba(238, 64, 53, 0.8), rgba(238, 64, 53, 0) 70%),
+    radial-gradient(circle, rgba(0, 0, 0, 0.2), transparent 70%);
+}
+```
+
+Only `linear-gradient()` and `radial-gradient()` background images are emitted
+for React Native. Other image values are ignored with a diagnostic.
+
+### Runtime CSS Strings
+
+Use `useCompiledCss()` and `cssx()` for CSS generated at runtime, such as CSS
+returned by an AI system.
+
+```jsx
+import { cssx, useCompiledCss } from 'cssxjs'
+
+function Button({ generatedCss, disabled, label }) {
+  const sheet = useCompiledCss(generatedCss)
+
+  return (
+    <Div {...cssx(['root', { disabled }], sheet, {
+      style: { backgroundColor: 'red' }
+    })}>
+      <Span {...cssx('label', sheet)}>{label}</Span>
+    </Div>
+  )
+}
+```
+
+Runtime compilation uses graceful diagnostics by default. Invalid CSS does not
+throw during render; the returned sheet contains diagnostics and any rules that
+could still be compiled.
+
 ## Limitations
 
 The `css` template does **not** support:
 
 - Stylus variables (`$var`)
 - Stylus mixins
 - Global `styles/index.styl` imports
+- JavaScript interpolation in module-level templates or runtime CSS strings
 
 For these features, use the [styl template](/api/styl) instead.
 
@@ -154,7 +247,9 @@ For these features, use the [styl template](/api/styl) instead.
 | Global imports | `styles/index.styl` | Not supported |
 | `u` unit | Yes | Yes |
 | CSS variables | Yes | Yes |
+| Function-scoped JS interpolation | Yes | Yes |
 | Part selectors | Yes | Yes |
+| Runtime CSS strings | No | `useCompiledCss()` |
 
 ## See Also
 

docs/api/index.md

@@ -12,8 +12,12 @@ import {
   variables,
   setDefaultVariables,
   defaultVariables,
-  dimensions,
-  matcher
+  cssx,
+  useCompiledCss,
+  useCssxSheet,
+  useCssxTemplate,
+  CssxProvider,
+  configureCssx
 } from 'cssxjs'
 ```
 
@@ -28,6 +32,7 @@ import {
 - [styl() Function](/api/styl-function) — Apply styles via spread
 - [JSX Props](/api/jsx-props) — `styleName`, `part`
 - [CSS Variables](/api/variables) — Runtime theming
+- [Caching](/guide/caching) — Built-in cache and runtime CSS helpers
 
 **Configuration:**
 - [Babel Config](/api/babel) — Preset options
@@ -43,5 +48,9 @@ import {
 | `variables` | Observable object | Set CSS variable values at runtime |
 | `setDefaultVariables` | Function | Set default CSS variable values |
 | `defaultVariables` | Object | Read-only default variable values |
-| `dimensions` | Observable object | Current screen width for media queries |
-| `matcher` | Function | Internal style matching (advanced) |
+| `cssx` | Function | Resolve a runtime sheet and `styleName` to props |
+| `useCompiledCss` | Hook | Compile runtime CSS text into a tracked sheet |
+| `useCssxSheet` | Hook | Track an already compiled sheet |
+| `useCssxTemplate` | Hook | Track a compiled sheet with interpolation values |
+| `CssxProvider` | Component | Provide runtime options to a subtree |
+| `configureCssx` | Function | Configure global runtime defaults |

docs/api/jsx-props.md

@@ -66,26 +66,30 @@ The pattern:
 
 ### Dynamic Styles
 
-For truly dynamic values, combine `styleName` with the `style` prop:
+For CSS values that come from props, prefer function-scoped template
+interpolation:
 
 ```jsx
 import { View, Text } from 'react-native'
 
-function ProgressBar({ progress }) {
+function ProgressBar({ progress, color }) {
   return (
-    <View styleName="bar" style={{ width: `${progress}%` }}>
+    <View styleName="bar">
       <Text>{progress}%</Text>
     </View>
   )
 
   styl`
     .bar
+      width ${progress}%
       height 20px
-      background-color #4caf50
+      background-color ${color}
   `
 }
 ```
 
+For ad hoc overrides, combine `styleName` with the regular `style` prop.
+
 ---
 
 ## part
@@ -128,26 +132,35 @@ See the [Component Parts guide](/guide/component-parts) for detailed examples.
 
 ---
 
-## matcher
+## cssx()
 
-The internal function that matches `styleName` values against compiled styles. Advanced use only.
+The low-level runtime helper that resolves a compiled or runtime sheet and
+returns props to spread onto a component. Most components should use
+`styleName`; use `cssx()` when CSS arrives as a runtime string or when a custom
+component cannot use the Babel transform.
 
 **Signature:**
 ```ts
-function matcher(
-  styleName: string,
-  fileStyles: object,
-  globalStyles: object,
-  localStyles: object,
-  inlineStyleProps: object
+function cssx(
+  styleName: string | array | object,
+  sheet: string | CompiledCssSheet | TrackedCssxSheet,
+  inlineStyleProps?: object
 ): object
 ```
 
-**Parameters:**
-- `styleName` - Space-separated class names (supports classnames-like syntax)
-- `fileStyles` - Styles from the imported CSS file
-- `globalStyles` - Module-level `styl` styles
-- `localStyles` - Function-level `styl` styles
-- `inlineStyleProps` - Inline style overrides
+```jsx
+import { cssx, useCompiledCss } from 'cssxjs'
+
+function GeneratedCard({ cssText, selected }) {
+  const sheet = useCompiledCss(cssText)
+
+  return (
+    <Card {...cssx(['card', { selected }], sheet, {
+      style: { marginTop: 16 }
+    })} />
+  )
+}
+```
 
-**Returns:** An object with style props, including `style` and any `{part}Style` props.
+`cssx()` returns an object with `style` and any part style props such as
+`titleStyle`, `hoverStyle`, or `activeStyle`.

docs/api/styl.md

@@ -208,6 +208,28 @@ CSSX adds a custom `u` unit where `1u = 8px` (Material Design grid):
 
 See [CSS Variables](/api/variables) for runtime variable updates.
 
+### JavaScript Interpolation
+
+Function-scoped `styl` templates support JavaScript interpolation in CSS value
+positions:
+
+```jsx
+function Button({ color, spacing }) {
+  return <View styleName="button" />
+
+  styl`
+    .button
+      background ${color}
+      padding ${spacing}px 12px
+  `
+}
+```
+
+Interpolation is lowered through the same runtime value path as `var()`, so it
+can be used for whole values, parts of shorthands, and values nested inside
+functions. It is not supported in module-level templates because there is no
+render-time value array there.
+
 ## Selectors
 
 | Selector | Description |
@@ -216,10 +238,12 @@ See [CSS Variables](/api/variables) for runtime variable updates.
 | `.class1.class2` | Multiple classes (same element) |
 | `&.modifier` | Modifier class (used within parent) |
 | `:part(name)` | Part selector |
+| `:hover` | Emits `hoverStyle`, same as `:part(hover)` |
+| `:active` | Emits `activeStyle`, same as `:part(active)` |
 
 > **Note:** Descendant selectors (`.parent .child`) are not supported. Apply modifiers directly to each element that needs styling.
 
-> **Note:** Pseudo-classes (`:hover`, `:focus`, `:active`, etc.) and pseudo-elements (`::before`, `::after`) are not supported. Use state-based modifiers instead (e.g., `&.focused`, `&.active`).
+> **Note:** `:focus`, other pseudo-classes, and pseudo-elements (`::before`, `::after`) are not supported. Use state-based modifiers for those cases.
 
 ### Part Selector
 
@@ -248,9 +272,9 @@ When the same property is defined in multiple places (highest to lowest):
 
 ## Limitations
 
-- No expression interpolations: `` styl`color ${color}` `` is not allowed
-- Must be a plain template literal
-- For dynamic values, use CSS variables or the `style` prop
+- JavaScript interpolation is local-only: module-level `styl` templates must be plain template literals
+- Interpolation is value-only, not selector or property-name interpolation
+- For runtime-generated plain CSS strings, use `useCompiledCss()` with the `css` runtime API
 
 ## See Also