[BREAKING] 0.4 Alpha

.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

@@ -1,42 +1,100 @@
 # Agent Guide
 
-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.
+Read this first, then read `architecture.md` for the detailed system map. Keep
+this file focused on day-to-day orientation for agents; put durable architecture
+details in `architecture.md`.
+
+CSSX is the CSS toolchain used by StartupJS and usable on its own. Users write
+`css`, `styl`, and optional `pug` templates with `styleName` and `part` props.
+Babel compiles that authoring syntax into CSSX sheet IR plus runtime calls.
+The unified `@cssxjs/css-to-rn` package owns CSS parsing, selector matching,
+CSS variable resolution, CSS value evaluation, React Native/web style
+transforms, runtime caching, provider themes, custom media, dimensions, and
+React subscriptions.
 
 ## Start Here
 
-1. Read `docs/guide/index.md`, `docs/guide/usage.md`, and `docs/guide/component-parts.md` for the public model.
-2. Read `architecture.md` before changing cross-package behavior.
+1. Read `architecture.md` before changing cross-package behavior.
+2. Read `docs/guide/index.md`, `docs/guide/usage.md`,
+   `docs/guide/component-parts.md`, `docs/guide/variables.md`,
+   `docs/guide/theming.md`, and `docs/examples/theme.md` for the public model.
 3. Use the package map below to choose the smallest code area to edit.
+4. Check `plan.md` only for future/backlog items. Completed architecture should
+   live in `architecture.md`, not in `plan.md`.
 
 ## 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, color functions, property transforms,
+  caching, `cssx()`, `useRuntimeCss()`, variables, dimensions, provider themes,
+  custom media, and React tracking.
+- `packages/cssxjs/`: public `cssxjs` facade, package exports, CLI, runtime
+  compatibility wrappers, Babel preset wrapper, loader wrappers, Metro wrappers,
+  and built-in theme entrypoints such as `cssxjs/themes/tailwind` and
+  `cssxjs/themes/shadcn`.
+- `packages/loaders/`: Stylus/CSS loaders and direct compiler wrappers. Pure
+  CSS compilation delegates to `@cssxjs/css-to-rn`; Stylus remains a separate
+  preprocessing step.
+- `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`, legacy `*StyleName`, imported style sheets, 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.
+- `packages/eslint-plugin-cssxjs/`: wrapper around the React Pug ESLint
+  processor.
 - `docs/`: user-facing docs; update these when public behavior changes.
 - `example/`: web demo using Babel plus esbuild.
 
 ## 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.
+- `__CSS_GLOBAL__` and `__CSS_LOCAL__` connect the inline Babel plugin to the
+  JSX/runtime plugin.
+- Runtime calls generated by Babel keep the compatibility shape
+  `runtime(styleName, fileStyles, globalStyles, localStyles, inlineStyleProps)`.
+- `cssxjs/runtime/*` wrappers adapt that call shape to the platform entrypoints
+  exported by `@cssxjs/css-to-rn`.
+- Style priority is outer provider layers, inner provider layers, file/imported
+  sheets, global templates, local templates, then inline props. Matching rules
+  also sort by specificity and source order.
+- Compiled sheets are JSON-serializable IR. Runtime cache, subscriptions, and
+  dependency tracking 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`, `:active`, `:part(hover)`, and `:part(active)` compile to
+  `hoverStyle` and `activeStyle`.
+- Component tag selectors such as `Button` and `Button:part(text)` apply only
+  inside components wrapped with `themed('Button', Component)` or an explicit
+  resolver tag option.
+- Provider/global `:root` custom properties compile to `sheet.rootVariables`.
+  Theme variables use `:root.<theme>`, for example `:root.dark`.
+- `CssxProvider` layers provider styles, root variables, custom media, and the
+  active theme. At the root, no `theme` prop uses the persisted global
+  preference, or `default` when no preference exists. Root `theme='auto'` uses
+  the system color scheme as the initial preference, then saved/user-selected
+  preference takes priority.
+- CSSX reserves custom media names matching `--theme-*`. `@media (--theme-dark)`
+  is the standard way to write theme-specific rules.
+- `@custom-media --name (...)` is supported in provider and component CSS.
+  StartupJS UI uses breakpoint aliases such as `--breakpoint-tablet`.
+- `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`.
+- Runtime CSS uses `useRuntimeCss(rawCss)` plus
+  `cssx(styleName, sheet, inlineStyleProps)` for dynamic client-side
+  compilation. Variables come from `variables`, `defaultVariables`, provider
+  `:root`, or template/layer `values`.
+- `getCssColor()` and `useCssColor()` bridge CSS variables/colors into JS and
+  return React Native-friendly values.
+- `useMedia()` bridges CSSX custom media/media-query evaluation into JS.
+- `cache: 'teamplay'` remains accepted as a Babel option for compatibility, but
+  runtime caching is owned by `@cssxjs/css-to-rn`, not Teamplay.
 
 ## Commands
 
-Install dependencies with the repo package manager:
+Install dependencies:
 
 ```sh
 yarn install
@@ -51,9 +109,12 @@ yarn test
 Run targeted tests:
 
 ```sh
-cd packages/runtime && yarn test
+cd packages/css-to-rn && npm test
+cd packages/css-to-rn && npm run test:types
 cd packages/babel-plugin-rn-stylename-inline && yarn test
 cd packages/babel-plugin-rn-stylename-to-style && yarn test
+cd packages/loaders && yarn test
+cd packages/cssxjs && npm test
 ```
 
 Run docs locally:
@@ -70,9 +131,23 @@ 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 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.
+- Treat `AGENTS.md` and `architecture.md` as living onboarding docs. If your
+  change alters package boundaries, public APIs, build/runtime flow, commands,
+  testing expectations, or maintenance rules, update these files in the same
+  change before handing work back.
+- For CSS parsing, selector, value, transform, cache, variable, media, theme, 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 exports or wrapper behavior, update `packages/cssxjs` smoke tests.
+- 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.

CHANGELOG.md

@@ -3,6 +3,68 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [0.4.0-alpha.6](https://github.com/startupjs/cssx/compare/v0.4.0-alpha.5...v0.4.0-alpha.6) (2026-06-25)
+
+
+### Bug Fixes
+
+* make auto theme opt-in ([7132a31](https://github.com/startupjs/cssx/commit/7132a3189c49facdce8aa8bc47de63135313e82b))
+
+
+
+
+
+# [0.4.0-alpha.5](https://github.com/startupjs/cssx/compare/v0.4.0-alpha.4...v0.4.0-alpha.5) (2026-06-25)
+
+**Note:** Version bump only for package cssx
+
+
+
+
+
+# [0.4.0-alpha.4](https://github.com/startupjs/cssx/compare/v0.4.0-alpha.3...v0.4.0-alpha.4) (2026-06-25)
+
+**Note:** Version bump only for package cssx
+
+
+
+
+
+# [0.4.0-alpha.3](https://github.com/startupjs/cssx/compare/v0.4.0-alpha.2...v0.4.0-alpha.3) (2026-06-24)
+
+**Note:** Version bump only for package cssx
+
+
+
+
+
+# [0.4.0-alpha.2](https://github.com/startupjs/cssx/compare/v0.4.0-alpha.1...v0.4.0-alpha.2) (2026-06-24)
+
+**Note:** Version bump only for package cssx
+
+
+
+
+
+# [0.4.0-alpha.1](https://github.com/startupjs/cssx/compare/v0.4.0-alpha.0...v0.4.0-alpha.1) (2026-06-24)
+
+**Note:** Version bump only for package cssx
+
+
+
+
+
+# [0.4.0-alpha.0](https://github.com/startupjs/cssx/compare/v0.3.0...v0.4.0-alpha.0) (2026-06-24)
+
+
+### Features
+
+* Unify CSS-to-RN compiler and runtime pipeline ([#5](https://github.com/startupjs/cssx/issues/5)) ([cd205cf](https://github.com/startupjs/cssx/commit/cd205cfcf0e7772f79263a47d6ca5c7b802edc31)), closes [startupjs/startupjs#1327](https://github.com/startupjs/startupjs/issues/1327) [startupjs/startupjs-ui#41](https://github.com/startupjs/startupjs-ui/issues/41)
+
+
+
+
+
 # [0.3.0](https://github.com/startupjs/cssx/compare/v0.2.33...v0.3.0) (2026-05-03)
 
 

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