@symbiote-native/css-parser 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 A. Prokopenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,126 @@
+# @symbiote-native/css-parser
+
+The **build-time CSS compiler** of [SymbioteJS](../../README.md) — turns a Vue SFC `<style>` block,
+or a standalone `.css`/`.module.css` file, into a React Native style object at build time, resolved
+back at render time through a class-name registry shared by every adapter (React's `className`,
+Vue's `class`/`:class`, Angular's `addClass`/`removeClass`). It also compiles SCSS/Sass, Less, and
+Stylus sources down to plain CSS before the same pipeline runs, so scoped styles, `:global()`, and
+CSS Modules all work identically regardless of source language.
+
+> New to SymbioteJS? The [root README](../../README.md) has the architecture. Styling with CSS
+> classes (instead of `StyleSheet.create`) is the supported convention across every example app —
+> this package is what makes it work at build time; [`@symbiote-native/engine`](../engine)'s
+> `style-registry` is what resolves it at runtime.
+
+---
+
+## Who calls this, and how
+
+**An app never imports this package directly.** It runs only inside a Metro transformer, on the
+Node build machine — never shipped in the app's native JS bundle. Each adapter package
+(`@symbiote-native/react`, `@symbiote-native/vue`, `@symbiote-native/angular`) depends on `@symbiote-native/css-parser`
+as a regular dependency and re-exports it via its own `./metro-css-parser` subpath, so a consuming
+app's `metro.config.js` wires:
+
+```js
+// metro-css-transformer.js, in the app
+const { createCssMetroTransformer } = require('@symbiote-native/react/metro-css-parser');
+module.exports = createCssMetroTransformer(require('@react-native/metro-babel-transformer'));
+```
+
+```js
+// metro.config.js
+resolver: { sourceExts: [...defaultSourceExts, 'css', 'scss', 'sass', 'less', 'styl'] },
+transformer: { babelTransformerPath: require.resolve('./metro-css-transformer.js') },
+```
+
+From there, a plain stylesheet import just works, from any adapter's own source file:
+
+```ts
+import styles from './Card.module.css';   // CSS Modules — default export is a name→scopedName map
+import './theme.css';                     // plain CSS — registers classes globally, no export
+```
+
+```tsx
+<View className="card" style={styles.highlight} />   // React
+```
+```html
+<!-- Vue SFC -->
+<view :class="['card', { active: isActive }]" />
+<style scoped>.card { padding: 10px; }</style>
+```
+
+## The pipeline
+
+```
+<style> CSS text / .css / .scss / .less / .styl        class="foo" / className / addClass
+      │  (build time, Metro)                                       │  (runtime, all adapters)
+      ▼                                                             ▼
+@symbiote-native/css-parser                              @symbiote-native/engine's style-registry
+  preprocessors.ts → parser.ts (parseCSS)            registerStyles() / resolveClassName()
+```
+
+A preprocessor source is reduced to plain CSS text first (`compileScss`/`compileSass`/
+`compileLess`/`compileStylus`); `parseCSS()` is the single downstream consumer either way, so every
+mechanism below runs identically regardless of source language.
+
+## API surface
+
+```ts
+import {
+  parseCSS, extractClassName, kebabToCamel,       // core compiler
+  compileCssFile, isCssModuleFile,                 // standalone .css/.module.css files
+  createCssMetroTransformer,                       // Metro babelTransformerPath factory
+  compileScss, compileSass, compileLess, compileStylus, compile, detectLanguage, isStyleFile,
+  classNamesToDtsSource, generateModuleDts,        // .d.ts generation for CSS Modules typing
+  globalClassNamesIn, hashFilePath,
+} from '@symbiote-native/css-parser';
+```
+
+- **`parseCSS(css, { filename? })`** — the compiler core: postcss AST walk, `var()`/`calc()`
+  resolution, selector → camelCase key (`.card` → `card`, `.btn.primary` → `btnPrimary` compound,
+  `.card .title` → `cardTitle` descendant). A selector containing a pseudo-class (`:hover`, …) is
+  dropped whole — RN has no pseudo-class concept, so there is no partial-application semantics to
+  preserve.
+- **`compileCssFile` / `isCssModuleFile`** — the standalone-file form: `Card.module.css`'s classes
+  are always scoped to a per-file hash and its default export is the name→scopedName map; a plain
+  `.css` file registers globally via a side-effect import.
+- **`createCssMetroTransformer`** — wraps an upstream RN Babel transformer, detecting a stylesheet
+  extension and compiling it before delegating everything else unchanged.
+- **Preprocessors** — `sass`/`less`/`stylus` are lazy, **optional** `devDependencies`: a project
+  that never authors `.scss`/`.less`/`.styl` never installs any of the three.
+- **CSS Modules type safety** — `css-dts` (bin) walks a directory and writes a real `<file>.d.ts`
+  next to each `.module.css`/`.scss`/`.less`/`.styl` (no index signature, so a typo genuinely fails
+  `tsc`), wired as a `pretypecheck` script; `./typescript-plugin` is a language-service plugin for
+  live in-editor autocomplete. Both are needed — a `tsconfig.json` plugin is invisible to a
+  standalone `tsc`/CI run, and the on-disk `.d.ts` gives no live-while-typing feedback.
+
+## What it does NOT do
+
+- It does not run at app runtime — it is a Node-only, Metro-build-time tool; the runtime half
+  (resolving a class name back into a style object) lives in `@symbiote-native/engine`'s
+  `style-registry`, not here.
+- It does not implement Tailwind CSS — that needs whole-project class scanning and JIT utility
+  generation, a fundamentally different shape than "one source file reduces to CSS text", and is
+  being designed as a separate, future package.
+- It supports `scoped` / `:global()` / CSS Modules and SCSS/Sass/Less/Stylus preprocessing; it does
+  not yet generate a typed `.d.ts` for an **inline** Vue `<style module>` block (only standalone
+  `.module.css` files get the strict, no-index-signature type — Vue's own Volar plugin gives inline
+  blocks a looser, typo-tolerant type for free) and has no Svelte support yet (no Svelte adapter
+  exists in SymbioteJS today).
+
+## Related packages
+
+- [`@symbiote-native/engine`](../engine) — owns the runtime `style-registry` (`registerStyles` /
+  `resolveClassName`) this package's compiled output resolves against, and the class+style merge
+  used by every adapter.
+- [`@symbiote-native/react`](../../adapters/react) / [`@symbiote-native/vue`](../../adapters/vue) /
+  [`@symbiote-native/angular`](../../adapters/angular) — each depends on this package directly and
+  re-exports it via its own `./metro-css-parser` subpath, so a consuming app needs no extra install
+  step.
+
+## Test it
+
+```bash
+pnpm test              # vitest, from the workspace root — parser, preprocessors, metro transformer
+```

package/build/file-scope-id.d.ts

@@ -0,0 +1 @@
+export declare function hashFilePath(filePath: string): string;

package/build/file-scope-id.js

@@ -0,0 +1,14 @@
+// A short, stable id derived from a file path, used to scope CSS classes so two files can each
+// define their own `.card` without colliding in the shared runtime registry (core/engine's
+// style-registry). Deterministic so Metro's cache stays warm across rebuilds. Shared by both
+// the Vue SFC compiler's own scope-id convention (examples/vue-sfc/metro-vue-transformer.js,
+// which prefixes it `data-v-` to match Vue's own attribute-based scoping) and the
+// framework-agnostic standalone `.module.css` file compiler (metro-css-module.ts) — same hash,
+// different prefix per caller, so the algorithm lives once.
+export function hashFilePath(filePath) {
+    let hash = 0;
+    for (let i = 0; i < filePath.length; i++) {
+        hash = (Math.imul(31, hash) + filePath.charCodeAt(i)) | 0;
+    }
+    return Math.abs(hash).toString(36).slice(0, 8);
+}

package/build/generate-dts-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/build/generate-dts-cli.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+// `css-dts <dir-or-file> [...more]` — walks the given paths, finds every `.module.css` (and
+// `.module.scss`/`.module.less`/`.module.styl`) file, and writes a sibling `.d.ts` next to it via
+// generateModuleDts. Kept separate from generate-dts.ts so the actual generation logic stays a
+// pure, disk-free function (source text in, .d.ts text out) — this file is the one place that
+// touches the filesystem, run at dev/build time only, never imported by app code.
+//
+// Deliberately NOT wired into the Metro transformer (metro-css-module.ts/metro-transformer.ts):
+// Metro's transform is content-hash-cached and only ever touches a file that is actually reached
+// by the bundle graph it's currently building — a `tsc`/`vue-tsc` typecheck run in CI has no
+// Metro involved at all, so a Metro-coupled generator would leave `.d.ts` files missing or stale
+// exactly where correctness matters most. The intended hook is `pretypecheck` (runs before every
+// typecheck, local or CI, with zero dependency on a running Metro/dev server) plus an optional
+// `--watch` mode for live autocomplete while actively editing styles.
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { isStyleFile } from "./preprocessors.js";
+import { isCssModuleFile } from "./metro-css-module.js";
+import { generateModuleDts } from "./generate-dts.js";
+const SKIPPED_DIR_NAMES = new Set(['node_modules', 'build', '.git']);
+async function collectModuleStyleFiles(root) {
+    const stat = await fs.stat(root);
+    if (!stat.isDirectory()) {
+        return isStyleFile(root) && isCssModuleFile(root) ? [root] : [];
+    }
+    const entries = await fs.readdir(root, { withFileTypes: true });
+    const found = [];
+    for (const entry of entries) {
+        if (entry.name.startsWith('.') || SKIPPED_DIR_NAMES.has(entry.name))
+            continue;
+        const fullPath = path.join(root, entry.name);
+        if (entry.isDirectory()) {
+            found.push(...(await collectModuleStyleFiles(fullPath)));
+        }
+        else if (isStyleFile(fullPath) && isCssModuleFile(fullPath)) {
+            found.push(fullPath);
+        }
+    }
+    return found;
+}
+async function generateDtsForFile(filename) {
+    const source = await fs.readFile(filename, 'utf8');
+    const dts = await generateModuleDts(source, filename);
+    if (dts === null)
+        return null;
+    const dtsPath = `${filename}.d.ts`;
+    await fs.writeFile(dtsPath, dts, 'utf8');
+    return dtsPath;
+}
+async function generateAll(roots) {
+    const files = (await Promise.all(roots.map(collectModuleStyleFiles))).flat();
+    for (const file of files) {
+        const dtsPath = await generateDtsForFile(file);
+        if (dtsPath)
+            console.log(`css-dts: wrote ${dtsPath}`);
+    }
+    return files.length;
+}
+// Dev-convenience only, not part of the correctness story above — re-runs the full generation
+// pass on any filesystem event under a root (a plain-CSS edit re-triggers it too, harmlessly; a
+// short debounce collapses an editor's typical write+rename burst into one pass) so an open
+// editor's autocomplete stays live while a `.module.css` file is being edited, without requiring
+// Metro or any other dev server to be running.
+async function watch(roots) {
+    console.log(`css-dts: watching ${roots.join(', ')} for changes (ctrl-c to stop)`);
+    let pending;
+    const regenerate = () => {
+        clearTimeout(pending);
+        pending = setTimeout(() => {
+            generateAll(roots).catch((error) => console.error(error));
+        }, 100);
+    };
+    regenerate();
+    await Promise.all(roots.map(async (root) => {
+        const watcher = fs.watch(root, { recursive: true });
+        for await (const _event of watcher)
+            regenerate();
+    }));
+}
+async function main() {
+    const args = process.argv.slice(2);
+    const isWatchMode = args.includes('--watch');
+    const targets = args.filter(arg => arg !== '--watch');
+    if (targets.length === 0) {
+        console.error('Usage: css-dts [--watch] <dir-or-file> [...more]');
+        process.exitCode = 1;
+        return;
+    }
+    if (isWatchMode) {
+        await watch(targets);
+        return;
+    }
+    const fileCount = await generateAll(targets);
+    if (fileCount === 0) {
+        console.log('css-dts: no .module.css (or .module.scss/.less/.styl) files found');
+    }
+}
+main().catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+});

package/build/generate-dts.d.ts

@@ -0,0 +1,2 @@
+export declare function classNamesToDtsSource(classNames: readonly string[]): string;
+export declare function generateModuleDts(source: string, filename: string): Promise<string | null>;

package/build/generate-dts.js

@@ -0,0 +1,43 @@
+// Generates a real on-disk `.d.ts` for a `.module.css` (or `.module.scss`/`.module.less`/
+// `.module.styl`) file — the follow-up the symbiote-sfc-style-compiler skill records as
+// deliberately deferred when CSS Modules shipped. Unlike Volar's built-in `<style module>`
+// typing for inline Vue SFC blocks (which synthesizes `Record<string, string> & {known keys}` —
+// an index signature that still accepts any key, so it never catches a typo), the type emitted
+// here has NO index signature: a typo in `styles.typo` is a genuine `error TS2339` under `tsc`/
+// `vue-tsc`, not a silent runtime miss. Named `<file>.d.ts` (full original filename, extension
+// appended rather than replaced — e.g. `Card.module.css.d.ts`) so TypeScript's own module
+// resolution picks it up for `import styles from './Card.module.css'` without a separate
+// registration step, the same convention typed-css-modules uses.
+import { parseCSS } from "./parser.js";
+import { compile, detectLanguage } from "./preprocessors.js";
+import { isCssModuleFile } from "./metro-css-module.js";
+const IDENTIFIER_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+function formatKey(className) {
+    return IDENTIFIER_RE.test(className) ? className : JSON.stringify(className);
+}
+export function classNamesToDtsSource(classNames) {
+    const fields = [...classNames]
+        .sort()
+        .map(className => `  readonly ${formatKey(className)}: string;`)
+        .join('\n');
+    return [
+        '// Auto-generated by @symbiote-native/css-parser from the matching CSS Modules file.',
+        '// Do not edit by hand — regenerate via `css-dts` instead.',
+        'declare const styles: {',
+        fields,
+        '};',
+        'export default styles;',
+        '',
+    ].join('\n');
+}
+// Mirrors compileCssFile's own module/non-module branch: a plain (non-`.module.*`) style file
+// has no default export to type (registerStyles() runs as a side effect only), so it gets no
+// `.d.ts` at all.
+export async function generateModuleDts(source, filename) {
+    if (!isCssModuleFile(filename))
+        return null;
+    const lang = detectLanguage(filename);
+    const css = lang === 'css' ? source : await compile(source, lang, filename);
+    const parsed = parseCSS(css, { filename });
+    return classNamesToDtsSource(Object.keys(parsed));
+}

package/build/global-selectors.d.ts

@@ -0,0 +1 @@
+export declare function globalClassNamesIn(css: string): Set<string>;

package/build/global-selectors.js

@@ -0,0 +1,22 @@
+// A light, independent scan for `:global(...)`-wrapped selectors inside a scoped CSS block's
+// raw text. parseCSS's extractClassName already UNWRAPS :global(...) (so `:global(.reset)`
+// parses to the same `reset` key a plain `.reset` selector would), but its output has no marker
+// for "this key came from inside :global()" — parseCSS's return shape is deliberately just
+// `{ className: style }`, no per-key metadata. A caller doing its own scope-suffixing (Vue's
+// <style scoped>/<style module>, or a standalone .module.css file) needs that distinction to
+// exempt these names, so it re-derives it here with its own minimal regex, independent of the
+// full CSS-to-style pipeline. Only the single-class form (`:global(.name)`) is recognized,
+// matching extractClassName's own documented narrower gap for partial/nested :global() wrapping.
+import { kebabToCamel } from "./parser.js";
+const GLOBAL_SELECTOR_PATTERN = /:global\(\s*\.([a-zA-Z0-9_-]+)\s*\)/g;
+export function globalClassNamesIn(css) {
+    const names = new Set();
+    let match;
+    while ((match = GLOBAL_SELECTOR_PATTERN.exec(css)) !== null) {
+        // Normalize kebab->camel: parseCSS's output is always camelCase-keyed, but the regex above
+        // captures the CSS text verbatim — a kebab selector like `:global(.reset-btn)` would
+        // otherwise never match its own `resetBtn` key.
+        names.add(kebabToCamel(match[1]));
+    }
+    return names;
+}

package/build/index.d.ts

@@ -0,0 +1,11 @@
+export { parseCSS, extractClassName, kebabToCamel } from './parser.ts';
+export type { ICssParserOptions } from './parser.ts';
+export { globalClassNamesIn } from './global-selectors.ts';
+export { hashFilePath } from './file-scope-id.ts';
+export { compileCssFile, isCssModuleFile } from './metro-css-module.ts';
+export type { ICompiledCssFile } from './metro-css-module.ts';
+export { classNamesToDtsSource, generateModuleDts } from './generate-dts.ts';
+export { createCssMetroTransformer } from './metro-transformer.ts';
+export type { IMetroTransformer, IMetroTransformParams } from './metro-transformer.ts';
+export { compileScss, compileSass, compileLess, compileStylus, compile, detectLanguage, isStyleFile, } from './preprocessors.ts';
+export type { IPreprocessorLanguage } from './preprocessors.ts';

package/build/index.js

@@ -0,0 +1,7 @@
+export { parseCSS, extractClassName, kebabToCamel } from "./parser.js";
+export { globalClassNamesIn } from "./global-selectors.js";
+export { hashFilePath } from "./file-scope-id.js";
+export { compileCssFile, isCssModuleFile } from "./metro-css-module.js";
+export { classNamesToDtsSource, generateModuleDts } from "./generate-dts.js";
+export { createCssMetroTransformer } from "./metro-transformer.js";
+export { compileScss, compileSass, compileLess, compileStylus, compile, detectLanguage, isStyleFile, } from "./preprocessors.js";

package/build/metro-css-module.d.ts

@@ -0,0 +1,6 @@
+import { type ICssParserOptions } from './parser.ts';
+export interface ICompiledCssFile {
+    code: string;
+}
+export declare function isCssModuleFile(filename: string): boolean;
+export declare function compileCssFile(source: string, filename: string, options?: ICssParserOptions): Promise<ICompiledCssFile>;

package/build/metro-css-module.js

@@ -0,0 +1,70 @@
+// Compiles a standalone .css/.scss/.sass/.less/.styl (and their .module.* twins) file into a
+// plain JS module — the framework-agnostic twin of a Vue SFC's inline <style>/<style module>
+// block (examples/vue-sfc/metro-vue-transformer.js), usable from ANY adapter's own source file:
+// `import styles from './Card.module.scss'` works the same from a React .tsx, a Vue <script>, or
+// an Angular .ts. See the symbiote-sfc-style-compiler skill.
+//
+// A plain style file registers its classes globally, exactly like an unscoped Vue <style>
+// block — side-effect import only (`import './theme.scss'`), no default export. A `.module.*`
+// file is ALWAYS scoped (that's the entire point of the extension): each class is suffixed with
+// a hash of the file's own path (core/css-parser's fileScopeId, tagged `__module__` so it can
+// never collide with a Vue <style scoped> block's plain `__<scopeId>` suffix even if the two
+// ever shared a scope id), and the default export is a plain name->scopedName map, so
+// `resolveClassName(styles.card)` (React `style={resolveClassName(styles.card)}`) or a template
+// binding that hands the already-scoped string straight to resolveClassName's exact-match path
+// both just work, no registry changes needed. `:global(.name)` opts a selector out of scoping,
+// same as Vue's <style scoped>.
+//
+// A preprocessor source (SCSS/Sass/Less/Stylus) is reduced to plain CSS text via
+// preprocessors.ts's `compile()` BEFORE any of the CSS-Modules scoping logic below runs — that
+// logic is entirely language-agnostic, it only ever sees `parseCSS`'s plain-CSS output, same as
+// it always did for a `.css` file.
+import * as path from 'node:path';
+import { parseCSS } from "./parser.js";
+import { globalClassNamesIn } from "./global-selectors.js";
+import { hashFilePath } from "./file-scope-id.js";
+import { compile, detectLanguage } from "./preprocessors.js";
+export function isCssModuleFile(filename) {
+    const ext = path.extname(filename);
+    if (!ext)
+        return false;
+    return filename.slice(0, -ext.length).endsWith('.module');
+}
+// Preprocessing (SCSS/Less/Stylus → plain CSS text) is inherently async in Node — Less has no
+// sync render API at all, and Stylus's callback-based render must be Promise-wrapped — so
+// compileCssFile is async uniformly, even for a plain `.css` file that needs no preprocessing.
+// See metro-transformer.ts for the fuller sync-vs-async writeup; the short version is that a
+// sync fast-path for `.css` would fork this function into two shapes for a build-time-only,
+// content-hash-cached call that is never a runtime hot path.
+export async function compileCssFile(source, filename, options) {
+    const lang = detectLanguage(filename);
+    const css = lang === 'css' ? source : await compile(source, lang, filename);
+    const parsed = parseCSS(css, { filename, ...options });
+    if (!isCssModuleFile(filename)) {
+        return {
+            code: `import { registerStyles } from '@symbiote-native/engine';\nregisterStyles(${JSON.stringify(parsed)});\n`,
+        };
+    }
+    const scopeId = hashFilePath(filename);
+    // Scanned against the COMPILED css text, not the raw source: :global(...) isn't native SCSS/
+    // Less/Stylus syntax (each preprocessor just passes an unrecognized selector through
+    // unchanged), but scanning the compiler's actual output — rather than assuming source and
+    // output stay textually identical for this token — is the one that can't drift under nesting/
+    // interpolation.
+    const exemptFromScope = globalClassNamesIn(css);
+    const styles = {};
+    const classMap = {};
+    for (const [className, props] of Object.entries(parsed)) {
+        const isExempt = exemptFromScope.has(className);
+        const scopedName = isExempt ? className : `${className}__module__${scopeId}`;
+        classMap[className] = scopedName;
+        styles[scopedName] = props;
+    }
+    return {
+        code: [
+            `import { registerStyles } from '@symbiote-native/engine';`,
+            `registerStyles(${JSON.stringify(styles)});`,
+            `export default ${JSON.stringify(classMap)};`,
+        ].join('\n') + '\n',
+    };
+}

package/build/metro-transformer.d.ts

@@ -0,0 +1,10 @@
+export interface IMetroTransformParams {
+    filename: string;
+    src: string;
+    [key: string]: unknown;
+}
+export interface IMetroTransformer {
+    transform: (params: IMetroTransformParams) => unknown;
+    getCacheKey?: (...args: unknown[]) => string;
+}
+export declare function createCssMetroTransformer(upstreamTransformer: IMetroTransformer): IMetroTransformer;

package/build/metro-transformer.js

@@ -0,0 +1,41 @@
+// A ready-made Metro babel transformer wrapper for .css/.scss/.sass/.less/.styl (+ their
+// .module.* twins) support, so a consuming app's own metro.config.js needs only a 3-line wiring
+// file instead of hand-rolling the "compile a style file, delegate everything else to upstream"
+// boilerplate three times (once per adapter's example, before this existed). @symbiote-native/css-parser
+// is a regular `dependency` of every adapter package (@symbiote-native/react, @symbiote-native/vue,
+// @symbiote-native/angular), so this is transitively resolvable from any app that already depends on one
+// of them — this repo's shamefully-hoist pnpm config (.npmrc) makes that resolvable without the
+// app adding @symbiote-native/css-parser to its own package.json. See the symbiote-sfc-style-compiler
+// skill.
+//
+// Sync vs async: `transform()` is async uniformly, for every recognized style extension
+// including plain `.css`. Metro's own `metro-transform-worker` already does
+// `await transformer.transform(...)` before touching the result (confirmed by reading the
+// installed metro-transform-worker source directly — `transformJSWithBabel` in its `index.js`),
+// so a babelTransformerPath module's `transform()` returning a Promise is a supported, exercised
+// shape, not a hack. SCSS/Less/Stylus compilation is inherently async in Node (Less ships no sync
+// render API at all; Stylus's callback-based render must be Promise-wrapped; Sass's
+// `compileString` does have a sync API, but the lazy `import('sass')` step itself is async
+// either way — see preprocessors.ts). A sync fast-path could still be kept for plain `.css`, but
+// that forks this function into two shapes to save a single microtask on a call that only ever
+// runs at Metro build time, content-hash-cached, never a runtime hot path — not worth the
+// duplication. `return upstreamTransformer.transform(...)` as the last line of an async function
+// forwards whatever it returns (Promise or not) as this function's own resolved value with no
+// extra `await` needed; Metro awaits the whole chain regardless.
+import { compileCssFile } from "./metro-css-module.js";
+import { isStyleFile } from "./preprocessors.js";
+export function createCssMetroTransformer(upstreamTransformer) {
+    return {
+        async transform(params) {
+            if (!isStyleFile(params.filename))
+                return upstreamTransformer.transform(params);
+            const { code } = await compileCssFile(params.src, params.filename);
+            return upstreamTransformer.transform({
+                ...params,
+                src: code,
+                filename: `${params.filename}.js`,
+            });
+        },
+        getCacheKey: upstreamTransformer.getCacheKey,
+    };
+}

package/build/parser.d.ts

@@ -0,0 +1,22 @@
+export type ICssParserOptions = {
+    filename?: string;
+};
+export declare function kebabToCamel(value: string): string;
+/**
+ * Extract a camelCase class name from a CSS selector, or `null` if the selector has no RN
+ * equivalent (pseudo-classes/-elements, bare element selectors, the universal selector — RN has
+ * no element-selector concept, so those would just pollute the output).
+ *
+ * - `.card` → `'card'`
+ * - `#header` → `'header'`
+ * - `.btn.primary` → `'btnPrimary'` (compound)
+ * - `.card .title` / `.card > .title` → `'cardTitle'` (descendant/child, flattened)
+ * - `[data-theme]` → `'dataTheme'` (attribute)
+ * - `.my-class-name` → `'myClassName'` (kebab → camel)
+ */
+export declare function extractClassName(selector: string): string | null;
+/**
+ * Parse a plain CSS string into a `{ className: RNStyleObject }` map. Build-time only — never
+ * ship this in the app's native JS bundle; it is meant to run inside a Metro transformer.
+ */
+export declare function parseCSS(css: string, options?: ICssParserOptions): Record<string, Record<string, unknown>>;