Unify CSS-to-RN compiler and runtime pipeline

.github/workflows/test.yml

@@ -24,3 +24,12 @@ jobs:
 
     - name: Run tests
       run: yarn test
+
+    - name: Smoke source-condition package imports
+      run: |
+        node -C cssx-ts --input-type=module -e "import { cssx, useCssxLayer } from 'cssxjs'; if (typeof cssx !== 'function' || typeof useCssxLayer !== 'function') throw new Error('cssxjs source-condition import failed')"
+
+    - name: Smoke built package imports
+      run: |
+        yarn workspace @cssxjs/css-to-rn build
+        node --input-type=module -e "import { compileCss, resolveCssx } from '@cssxjs/css-to-rn'; const sheet = compileCss('.root { color: red; }'); const result = resolveCssx({ styleName: 'root', layers: sheet }); if (result.props.style.color !== 'red') throw new Error('built css-to-rn import failed')"

.gitignore

@@ -11,6 +11,7 @@
 
 # Node dependencies
 node_modules
+packages/*/dist
 
 # npm-debug log
 npm-debug.*

AGENTS.md

@@ -2,7 +2,7 @@
 
 Read this first, then use `architecture.md` for the detailed system map.
 
-CSSX is a monorepo for a CSS-in-JS toolchain. Users write `styl`, `css`, or optional `pug` templates plus `styleName` and `part` props. Babel compiles that authoring syntax into style objects and runtime calls. The runtime matches class selectors, applies CSS variables/media queries, supports component parts, and can memoize with teamplay.
+CSSX is a monorepo for a CSS-in-JS toolchain. Users write `css`, `styl`, or optional `pug` templates plus `styleName` and `part` props. Babel compiles that authoring syntax into compiled CSS sheet IR and runtime calls. The unified `@cssxjs/css-to-rn` package owns CSS parsing, CSS value resolution, React Native/web style transformation, runtime caching, variables, media/dimension tracking, and React subscriptions.
 
 ## Start Here
 
@@ -12,11 +12,11 @@ CSSX is a monorepo for a CSS-in-JS toolchain. Users write `styl`, `css`, or opti
 
 ## Package Map
 
-- `packages/cssxjs/`: public `cssxjs` facade, CLI, wrappers, package exports.
-- `packages/runtime/`: `process()`, `matcher()`, variables, dimensions, platform helpers, teamplay caching.
-- `packages/loaders/`: Stylus/CSS loaders and direct compiler wrappers.
-- `packages/babel-plugin-rn-stylename-inline/`: compiles inline `css` and `styl` templates.
-- `packages/babel-plugin-rn-stylename-to-style/`: rewrites JSX `styleName`, `part`, old `*StyleName`, and helper calls.
+- `packages/css-to-rn/`: unified compiler/runtime engine. Start here for CSS parsing, selector IR, value resolution, property transforms, caching, `cssx()`, `useRuntimeCss()`, variables, and dimensions.
+- `packages/cssxjs/`: public `cssxjs` facade, CLI, package exports, runtime compatibility wrappers, Babel preset wrapper, loader wrappers, and Metro wrappers.
+- `packages/loaders/`: Stylus/CSS loaders and direct compiler wrappers. CSS compilation delegates to `@cssxjs/css-to-rn`.
+- `packages/babel-plugin-rn-stylename-inline/`: compiles inline `css` and `styl` templates, including local template interpolation lowering.
+- `packages/babel-plugin-rn-stylename-to-style/`: rewrites JSX `styleName`, `part`, old `*StyleName`, and helper calls into runtime calls.
 - `packages/babel-preset-cssxjs/`: transform ordering and public Babel options.
 - `packages/bundler/`: Metro hot-reload path for separate style files.
 - `packages/eslint-plugin-cssxjs/`: wrapper around React Pug ESLint processor.
@@ -26,13 +26,17 @@ CSSX is a monorepo for a CSS-in-JS toolchain. Users write `styl`, `css`, or opti
 ## Core Contracts
 
 - `__CSS_GLOBAL__` and `__CSS_LOCAL__` connect the inline Babel plugin to the JSX/runtime plugin.
-- Compiled style metadata `__hash__`, `__vars`, and `__hasMedia` connects loaders to cached and uncached runtime processing.
-- Runtime calls have this shape: `runtime(styleName, fileStyles, globalStyles, localStyles, inlineStyleProps)`.
-- Style priority is file styles, then global templates, then local templates, then inline props.
-- Selector specificity is approximated by class count only.
+- Runtime calls generated by Babel keep the compatibility shape `runtime(styleName, fileStyles, globalStyles, localStyles, inlineStyleProps)`.
+- `cssxjs/runtime/*` wrappers adapt that call shape to `@cssxjs/css-to-rn` platform entrypoints.
+- Style priority is file/imported sheets, then global templates, then local templates, then inline props.
+- 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`.
-- `css`/`styl` template interpolation is intentionally unsupported.
-- Cached runtime is selected by `cache: 'teamplay'` or by importing `observer` from `teamplay` or `startupjs`.
+- `: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.
 
 ## Commands
 
@@ -51,7 +55,7 @@ yarn test
 Run targeted tests:
 
 ```sh
-cd packages/runtime && yarn test
+cd packages/css-to-rn && npm test
 cd packages/babel-plugin-rn-stylename-inline && yarn test
 cd packages/babel-plugin-rn-stylename-to-style && yarn test
 ```
@@ -70,9 +74,10 @@ yarn start
 
 ## Change Guidance
 
-- For runtime matching changes, update `packages/runtime/test/matcher.mjs` and `packages/runtime/test/process.mjs`.
-- For Babel changes, update the relevant Jest snapshots.
-- For public API or behavior changes, update `docs/` and `architecture.md`.
+- For CSS parsing, selector, value, transform, cache, variable, media, or React tracking behavior, update `packages/css-to-rn/test/engine/**` or `packages/css-to-rn/test/react/**`.
+- For inline template or interpolation compilation, update `packages/babel-plugin-rn-stylename-inline` snapshots.
+- For JSX `styleName`/`part` behavior, update `packages/babel-plugin-rn-stylename-to-style` snapshots.
+- For public API or behavior changes, update `docs/`, `architecture.md`, and this guide.
 - For Pug, type checking, or ESLint behavior, check whether the implementation lives in `@react-pug/*`; this repo often only wraps it.
 - For separate style files, check both Babel `compileCssImports` behavior and Metro transformer behavior.
 - Prefer current source code and `docs/` over older package READMEs when they conflict.

README.md

@@ -23,6 +23,18 @@ Install the following extension for full CSSX support with Pug and CSS/Stylus in
 
 [`vscode-react-pug-tsx`](https://marketplace.visualstudio.com/items?itemName=startupjs.vscode-react-pug-tsx)
 
+## Credits
+
+CSSX's unified CSS-to-React-Native compiler/runtime was inspired by and replaces
+the separate roles previously handled by:
+
+- [`css-to-react-native`](https://github.com/styled-components/css-to-react-native)
+- [`css-to-react-native-transform`](https://github.com/kristerkari/css-to-react-native-transform)
+
+The runtime and API design also benefited from studying:
+
+- [`cssta`](https://github.com/jacobp100/cssta)
+
 ## License
 
 MIT