Add CSSX provider theming primitives

Author: cray0000

AGENTS.md

@@ -32,6 +32,9 @@ CSSX is a monorepo for a CSS-in-JS toolchain. Users write `css`, `styl`, or opti
 - Compiled sheets are JSON-serializable IR. Runtime cache/tracking state must stay outside the sheet.
 - `part='root'` maps to `style`; other parts map to `{partName}Style`.
 - `:hover` and `:active` compile to `hoverStyle` and `activeStyle`.
+- Provider/global `:root` custom properties compile to `sheet.rootVariables` and resolve as scoped defaults below runtime `variables` and above `defaultVariables`.
+- Component tag selectors such as `Button` and `Button:part(text)` apply only inside components wrapped with `themed('Button', Component)` or explicit resolver tag options.
+- `variables` and `defaultVariables` are validating proxies. Direct assignment/deletion works for valid `--name` keys; bulk updates use `.assign()`, `.set()`, and `.clear()`.
 - Local JS template interpolation is lowered to synthetic `var(--__cssx_dynamic_N)` slots and passed as `values`.
 - `cache: 'teamplay'` remains accepted as a Babel option for compatibility, but runtime caching is owned by `@cssxjs/css-to-rn`, not Teamplay.
 

architecture.md

@@ -230,14 +230,21 @@ Supported selectors:
 - `.root`
 - `.root.active`
 - `.root:part(label)`
+- `.root::part(label)`
 - `.root.active:part(icon)`
 - `.root:hover`
 - `.root:active`
+- `Button`
+- `Button.primary`
+- `Button:part(text)`
+- `Button::part(text)`
+- `Button.primary:part(text)`
 - `:export`
+- bare `:root` custom-property declarations
 
-`:hover` maps to `hoverStyle`; `:active` maps to `activeStyle`. Unsupported selectors are ignored with diagnostics in runtime mode.
+`:hover` maps to `hoverStyle`; `:active` maps to `activeStyle`. Tag selectors apply only when the current component tag is provided by `themed(tagName, Component)` or explicit resolver options. Unsupported selectors are ignored with diagnostics in runtime mode.
 
-`:root` custom-property declarations and declaration-level custom properties are intentionally not used as defaults. Use `setDefaultVariables()` for defaults.
+Bare `:root` custom-property declarations are compiled into `sheet.rootVariables` and become scoped defaults when the sheet is supplied through `CssxProvider style` or another layer. Declaration-level custom properties outside `:root` are ignored with diagnostics.
 
 ### Value Resolution
 
@@ -246,13 +253,17 @@ Supported selectors:
 1. Replace interpolation slots from `values`.
 2. Recursively resolve nested `var()`.
 3. Resolve `u`, viewport units, and supported `calc()`.
-4. Return dependencies for variables and dimensions.
+4. Normalize supported modern color functions (`oklch()`, `oklab()`, `color-mix()`) to `rgba(...)`.
+5. Return dependencies for variables and dimensions.
 
 Variable priority is:
 
-1. runtime `variables['--name']`
-2. `defaultVariables['--name']`
-3. inline fallback `var(--name, fallback)`
+1. template interpolation values.
+2. runtime `variables['--name']`.
+3. nearest scoped provider/sheet `:root` variable.
+4. outer scoped provider/sheet `:root` variables.
+5. `defaultVariables['--name']`.
+6. inline fallback `var(--name, fallback)`.
 
 Unresolved variables, cycles, depth limits, invalid interpolations, and unsupported `calc()` invalidate only the containing declaration. Earlier fallback declarations in the same rule still apply.
 
@@ -288,7 +299,7 @@ Resolver order:
 
 1. Normalize `styleName` with classcat-like semantics.
 2. Normalize one or more sheet layers.
-3. Match selectors by class set.
+3. Match selectors by component tag and class set.
 4. Filter inactive media rules.
 5. Group by output prop: `style`, `{part}Style`, `hoverStyle`, `activeStyle`.
 6. Apply cascade by layer, specificity, and source order.
@@ -307,14 +318,16 @@ Runtime caches are bounded. Static cache keys include sheet identity, style name
 
 Key pieces:
 
-- `store.ts`: `variables`, `defaultVariables`, `setDefaultVariables()`, dimensions/media state, microtask-batched notifications.
+- `store.ts`: `variables`, `defaultVariables`, `setDefaultVariables()`, variable bulk methods, dimensions/media state, microtask-batched notifications.
 - `tracker.ts`: `TrackedCssxSheet`, committed dependency snapshots, per-tracker cache.
 - `cssx.ts`: ergonomic `cssx()` wrapper that delegates to `resolveCssx()` and records dependencies into tracked sheets during render.
-- `hooks.ts`: `useCssxSheet()`, `useRuntimeCss()`, `useCssxTemplate()`, `useCssxLayer()`.
-- `config.ts`: optional `CssxProvider`, `configureCssx()`, and `useCssxConfig()`.
+- `hooks.ts`: `useCssxSheet()`, `useRuntimeCss()`, `useCssxTemplate()`, `useCssxLayer()`, `useCssVariable()`, `useCssVariableRaw()`, `getCssVariable()`, and `getCssVariableRaw()`.
+- `config.ts`: optional `CssxProvider`, `configureCssx()`, `useCssxConfig()`, and `themed()`.
 
 `useCssxSheet()` starts a render-local dependency collection before render and commits it in a layout/effect phase. If a render is aborted, for example because a component throws a promise into Suspense, the pending dependencies are not committed and do not leak global subscriptions.
 
+`CssxProvider style` accepts raw CSS strings, compiled sheets, tracked sheets, layer objects, arrays, and falsey values. Provider layers are appended after parent provider layers and before component-local layers. Nested providers append additional `:root` variable scopes, with inner scopes winning over outer scopes. `themed()` adds the current component tag and a render-local dependency tracker so provider/global styles that read variables can update themed components even when they have no local sheet.
+
 Variable writes and deletes notify subscribers once per microtask. Subscribers only rerender when a variable they actually used changes. Viewport-unit subscribers are tied to dimension changes. Media-query dependencies store the match value observed during the committed render; dimension changes and platform media adapter changes only rerender subscribers whose committed media result changed. Browser `matchMedia` is used on web when available, and tests can install a media-query adapter for non-DOM media features such as `prefers-color-scheme`, `hover`, and `pointer`. Web resize uses leading plus trailing debounced updates.
 
 ## Loaders And Separate Files

docs/api/css.md

@@ -132,6 +132,27 @@ shorthands, comma-separated value chunks, and nested fallbacks.
 }
 ```
 
+Provider/global CSS can define subtree-scoped variables with `:root`:
+
+```css
+:root {
+  --primary-color: oklch(62% 0.18 250);
+}
+```
+
+Those variables are scoped by `CssxProvider`, not stored as global defaults.
+
+### Modern Color Functions
+
+CSSX resolves `oklch()`, `oklab()`, and `color-mix()` to legacy `rgba(...)`
+strings so the same CSS works on React Native:
+
+```css
+.button {
+  background-color: color-mix(in oklch, var(--brand), white 20%);
+}
+```
+
 ### JavaScript Interpolation
 
 Function-scoped `css` templates support JavaScript interpolation in CSS value
@@ -162,11 +183,30 @@ must use plain CSS text.
   color: red;
 }
 
-.button:part(text) {
+.button::part(text) {
   font-weight: bold;
 }
 ```
 
+Both `:part()` and `::part()` are supported.
+
+### Component Tag Selectors
+
+Provider/global CSS can target components wrapped with `themed()` by tag:
+
+```css
+Button {
+  background: var(--button-bg);
+}
+
+Button.primary:part(text) {
+  color: white;
+}
+```
+
+Tag selectors are intended for global component overrides. Class selectors still
+work as utility classes everywhere.
+
 ### Hover and Active Styles
 
 CSSX maps `:hover` and `:active` to the same output as `:part(hover)` and

docs/api/index.md

@@ -14,10 +14,13 @@ import {
   defaultVariables,
   cssx,
   useRuntimeCss,
+  useCssVariable,
+  useCssVariableRaw,
   useCssxSheet,
   useCssxTemplate,
   CssxProvider,
-  configureCssx
+  configureCssx,
+  themed
 } from 'cssxjs'
 ```
 
@@ -46,12 +49,15 @@ import {
 | `styl` | Template literal / Function | Write styles in Stylus syntax, or apply styles via spread |
 | `css` | Template literal | Write styles in plain CSS syntax |
 | `pug` | Template literal | Write JSX in Pug syntax, with TypeScript expressions and embedded `style` blocks |
-| `variables` | Observable object | Set CSS variable values at runtime |
-| `setDefaultVariables` | Function | Set default CSS variable values |
-| `defaultVariables` | Object | Read-only default variable values |
+| `variables` | Reactive object | Set CSS variable values at runtime; supports `.assign()`, `.set()`, `.clear()` |
+| `setDefaultVariables` | Function | Replace default CSS variable values |
+| `defaultVariables` | Reactive object | Default variable values; supports `.assign()`, `.set()`, `.clear()` |
 | `cssx` | Function | Resolve a runtime sheet and `styleName` to props |
 | `useRuntimeCss` | Hook | Compile runtime CSS text into a tracked sheet |
+| `useCssVariable` | Hook | Read a CSS variable as an RN-friendly value and subscribe to it |
+| `useCssVariableRaw` | Hook | Read a CSS variable as raw resolved CSS text |
 | `useCssxSheet` | Hook | Track an already compiled sheet |
 | `useCssxTemplate` | Hook | Track a compiled sheet with interpolation values |
-| `CssxProvider` | Component | Provide runtime options to a subtree |
+| `CssxProvider` | Component | Provide runtime options and global/scoped CSS to a subtree |
+| `themed` | Function | Give a component a CSS tag for provider/global component overrides |
 | `configureCssx` | Function | Configure global runtime defaults |

docs/api/runtime.md

@@ -120,6 +120,61 @@ Only variables used by the resolved element are tracked. If `--border-color`
 changes, elements that used it update. If an unrelated variable changes, they do
 not.
 
+## Provider Styles
+
+`CssxProvider` can provide global CSS to a subtree through its `style` prop.
+Provider styles can define utility classes, component tag overrides, and scoped
+`:root` variables:
+
+```jsx
+import { CssxProvider, themed } from 'cssxjs'
+
+const Button = themed('Button', function Button({ children }) {
+  return (
+    <Pressable part="root">
+      <Text part="text">{children}</Text>
+    </Pressable>
+  )
+})
+
+function App() {
+  return (
+    <CssxProvider style={`
+      :root { --brand: oklch(62% 0.18 250); }
+      .p2 { padding: 2u; }
+      Button { background: var(--brand); }
+      Button:part(text) { color: white; }
+    `}>
+      <Button styleName="p2">Save</Button>
+    </CssxProvider>
+  )
+}
+```
+
+Nested providers override outer `:root` variables for their subtree. Runtime
+`variables['--name']` still has higher priority than provider `:root` values.
+
+Use `themed(tagName, Component)` for components that should be addressable by
+tag selectors in provider/global CSS. Class selectors remain global utilities
+and do not require a tag.
+
+## Reading Variables In JS
+
+Use `useCssVariable()` when component logic needs the resolved value:
+
+```jsx
+import { useCssVariable } from 'cssxjs'
+
+function Avatar() {
+  const size = useCssVariable('--avatar-size', '4u') // 32
+  return <Image style={{ width: size, height: size }} />
+}
+```
+
+`useCssVariable()` returns an RN-friendly value: `2u` and `16px` become numbers,
+percentages stay strings, and modern color functions are normalized. Use
+`useCssVariableRaw()` when you need the raw resolved CSS string.
+
 ## Media Queries
 
 Runtime CSS can use media queries:
@@ -164,6 +219,9 @@ useCssxTemplate(compiledSheet, values, options?)
 useCssxLayer(input, options?)
 CssxProvider
 configureCssx(options)
+themed(tagName, Component)
+useCssVariable(name, fallback?)
+useCssVariableRaw(name, fallback?)
 ```
 
 `useCssxSheet()` tracks an already compiled sheet. `useCssxTemplate()` is used by
@@ -172,7 +230,8 @@ accepts strings, compiled sheets, tracked sheets, or layer objects and returns
 the tracked equivalent.
 
 `CssxProvider` and `configureCssx()` configure runtime defaults such as target
-and dimension debounce behavior.
+and dimension debounce behavior. `CssxProvider` also accepts a `style` prop for
+subtree-scoped CSS.
 
 ## Platform Resolution
 

docs/api/variables.md

@@ -4,9 +4,10 @@ CSSX provides a reactive system for CSS variables that works at runtime.
 
 ## variables
 
-A reactive object for setting CSS variable values at runtime. Assigning values triggers automatic re-renders in components using those variables.
+A reactive object for setting CSS variable values at runtime. Assigning values
+triggers automatic re-renders in components using those variables.
 
-**Type:** `Record<string, unknown>`
+**Type:** `CssxVariableStore`
 
 ```jsx
 import { variables } from 'cssxjs'
@@ -17,13 +18,24 @@ variables['--primary-color'] = '#007bff'
 // Read a variable
 console.log(variables['--primary-color'])
 
-// Set multiple variables
-Object.assign(variables, {
+// Merge multiple variables
+variables.assign({
   '--primary-color': '#007bff',
   '--text-color': '#333'
 })
+
+// Replace the whole runtime variable set
+variables.set({
+  '--primary-color': '#007bff'
+})
+
+// Clear all runtime variables
+variables.clear()
 ```
 
+Only valid CSS custom property names can be assigned. Names must start with
+`--`; invalid names throw.
+
 **Reactivity:**
 When you assign to `variables`, components that used those specific variables in
 their resolved styles automatically re-render with the new values.
@@ -82,32 +94,57 @@ setDefaultVariables({
 
 ## defaultVariables
 
-A reactive object containing the default variable values set by
-`setDefaultVariables`.
+A reactive object containing default variable values. It supports the same
+`.assign()`, `.set()`, and `.clear()` methods as `variables`.
 
-**Type:** `Record<string, string>`
+**Type:** `CssxVariableStore`
 
 ```jsx
 import { defaultVariables } from 'cssxjs'
 
 console.log(defaultVariables['--primary-color']) // '#007bff'
 ```
 
+`setDefaultVariables(vars)` is an alias for `defaultVariables.set(vars)`.
+
+## Reading Variables In Components
+
+Use `useCssVariable()` when JavaScript needs the resolved value:
+
+```jsx
+import { useCssVariable } from 'cssxjs'
+
+function Box() {
+  const gap = useCssVariable('--gap', '2u') // 16
+  return <View style={{ gap }} />
+}
+```
+
+`useCssVariable()` subscribes only to the variables it resolves, including nested
+`var()` references. It returns RN-friendly values: `2u` and `16px` become
+numbers, percentages remain strings, and modern color functions are normalized.
+
+Use `useCssVariableRaw()` to read raw resolved CSS text. Outside React, use
+`getCssVariable()` and `getCssVariableRaw()` for global variables only.
+
 ## Variable Resolution Order
 
 CSS variables resolve in this priority (highest first):
 
-1. **Runtime:** `variables['--name']`
-2. **Default:** `setDefaultVariables({ '--name': value })`
-3. **Inline fallback:** `var(--name, fallback)`
+1. **Template interpolation values**
+2. **Runtime:** `variables['--name']`
+3. **Nearest provider `:root` variable**
+4. **Outer provider `:root` variables**
+5. **Default:** `defaultVariables['--name']`
+6. **Inline fallback:** `var(--name, fallback)`
 
 ```jsx
-setDefaultVariables({ '--color': 'blue' })  // Priority 2
-variables['--color'] = 'red'                 // Priority 1 (wins)
+setDefaultVariables({ '--color': 'blue' })
+variables['--color'] = 'red' // wins over provider and defaults
 
 styl`
   .box
-    color var(--color, green)  // Will be 'red'
+    color var(--color, green) // Will be 'red'
 `
 ```