@symbiote-native/css-parser 0.2.3 → 0.3.0

package/README.md

@@ -32,32 +32,35 @@ Node build machine — never shipped in the app's native JS bundle. Each adapter
 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') },
+transformer: { babelTransformerPath: require.resolve('@symbiote-native/react/metro-css-parser') },
 ```
 
+The subpath already calls `createCssMetroTransformer` and exports the finished transformer, so an
+app writes no transformer file of its own — point `babelTransformerPath` straight at it. Reach for
+`createCssMetroTransformer` only when building the subpath for a NEW adapter.
+
 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
+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
+<View className="card" style={styles.highlight} /> // React
 ```
+
 ```html
 <!-- Vue SFC -->
 <view :class="['card', { active: isActive }]" />
-<style scoped>.card { padding: 10px; }</style>
+<style scoped>
+  .card {
+    padding: 10px;
+  }
+</style>
 ```
 
 ## The pipeline
@@ -78,12 +81,24 @@ mechanism below runs identically regardless of source language.
 
 ```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,
+  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,
+  globalClassTokensIn,
+  hashFilePath,
 } from '@symbiote-native/css-parser';
 ```
 
@@ -97,6 +112,13 @@ import {
   `.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.
+- **`globalClassNamesIn` / `globalClassTokensIn`** — the two halves of `:global()`, and they answer
+  different questions. The first returns registered KEYS whose selector was global in full, so the
+  key itself skips scoping. The second returns MARKUP TOKENS that came out of a `:global(...)`
+  payload wherever it sat, including inside an otherwise-scoped selector — `.card :global(.reset)`
+  yields the key `cardReset` from neither, and the token `reset` from the second. A caller that
+  suffixes class names needs both: exempting only by key leaves a partial global's token
+  scope-mangled, exempting only by token leaves a fully global compound's rule dead.
 - **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`

package/build/global-selectors.d.ts

@@ -1 +1,25 @@
-export declare function globalClassNamesIn(css: string): Set<string>;
+import { type ICssParserOptions } from './parser/index.ts';
+/**
+ * The registered keys whose ENTIRE selector lived outside the file's scope — `:global(.reset)` →
+ * `reset`, `:global(.btn.primary)` → `btnPrimary`. These register under their plain name and get
+ * no scope suffix.
+ *
+ * A selector with a scoped part (`.card :global(.reset)` → `cardReset`) is deliberately absent:
+ * the rule still only applies where the file's own `.card` does, so its collapsed key belongs to
+ * this file. Only its `:global()` half escapes, which is {@link globalClassTokensIn}'s answer.
+ */
+export declare function globalClassNamesIn(css: string, options?: ICssParserOptions): Set<string>;
+/**
+ * Every class token that came out of a `:global(...)` payload, wherever in a selector it sat —
+ * `.card :global(.legacy-widget) span` → `{ legacyWidget }`.
+ *
+ * This is the set a scope-suffixing caller subtracts from the tokens it owns. A token is in it
+ * whether or not the selector around it was scoped, which is the whole point: the author reached
+ * for `:global()` precisely because that name is spelled the same way in markup this file does
+ * not own, and a suffix would break the match it was reaching for.
+ *
+ * A selector the parser rejects contributes nothing — it registers no key, so it names nothing to
+ * exempt, and letting its payload leak in here would unscope a token some other rule legitimately
+ * owns.
+ */
+export declare function globalClassTokensIn(css: string, options?: ICssParserOptions): Set<string>;

package/build/global-selectors.js

@@ -1,22 +1,98 @@
-// 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/index.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]));
+// What a caller doing its own scope-suffixing (Vue's <style scoped>/<style module>, Svelte's
+// <style>, a standalone .module.css file) must leave alone because the author wrote `:global(...)`
+// around it. parseCSS's output cannot answer that on its own: extractClassName UNWRAPS `:global()`
+// (so `:global(.reset)` parses to the same `reset` key a plain `.reset` would) and its return
+// shape is deliberately just `{ className: style }`, with no per-key metadata.
+//
+// The escape hatch is asked about at TWO levels, and they are genuinely different questions:
+//
+//   :global(.reset)        key `reset`      — the whole selector is outside the scope
+//   .card :global(.reset)  key `cardReset`  — only the `reset` TOKEN is
+//
+// `globalClassNamesIn` answers the first (which registered KEY stays unsuffixed),
+// `globalClassTokensIn` the second (which MARKUP token stays unsuffixed). A partial `:global()`
+// needs both to disagree: the rule as a whole is scoped, because `.card` is the file's own, yet
+// the `reset` half must reach the unscoped markup it was written for. Suffixing it anyway
+// scope-mangles the author's escape hatch into something that matches nothing.
+//
+// Both walk the selectors through the parser's own tokenizer rather than a private regex — the
+// names they hand back are compared against parseCSS's keys and against the markup tokens
+// classTokensIn produces, so any independent spelling of "what class does this selector name" is
+// one more chance to disagree with the pipeline it feeds.
+import postcss from 'postcss';
+import { extractClassName, extractClassTokens, globalPayloadsIn, } from "./parser/index.js";
+function eachSelector(css, options, visit) {
+    if (!css || typeof css !== 'string')
+        return;
+    const root = postcss.parse(css, { from: options?.filename });
+    // Dropped ahead of the rule walk for the same reason parseCSS drops them, silently here since
+    // that pass already warned about each one.
+    root.walkAtRules(atRule => {
+        atRule.remove();
+    });
+    root.walkRules(rule => {
+        for (const selector of rule.selector.split(','))
+            visit(selector.trim());
+    });
+}
+// In source order, so a caller can compare this list against the selector's full token list
+// position by position.
+function globalTokensOf(selector) {
+    const tokens = [];
+    for (const payload of globalPayloadsIn(selector)) {
+        for (const token of extractClassTokens(payload) ?? [])
+            tokens.push(token);
     }
+    return tokens;
+}
+/**
+ * The registered keys whose ENTIRE selector lived outside the file's scope — `:global(.reset)` →
+ * `reset`, `:global(.btn.primary)` → `btnPrimary`. These register under their plain name and get
+ * no scope suffix.
+ *
+ * A selector with a scoped part (`.card :global(.reset)` → `cardReset`) is deliberately absent:
+ * the rule still only applies where the file's own `.card` does, so its collapsed key belongs to
+ * this file. Only its `:global()` half escapes, which is {@link globalClassTokensIn}'s answer.
+ */
+export function globalClassNamesIn(css, options) {
+    const names = new Set();
+    eachSelector(css, options, selector => {
+        const tokens = extractClassTokens(selector);
+        if (tokens === null)
+            return;
+        // Compared position by position rather than as a subset: `.card :global(.card)` repeats a
+        // token, and "every token appears somewhere in a payload" would read that as fully global.
+        const globalTokens = globalTokensOf(selector);
+        if (globalTokens.length !== tokens.length)
+            return;
+        if (!tokens.every((token, index) => token === globalTokens[index]))
+            return;
+        const name = extractClassName(selector);
+        if (name !== null)
+            names.add(name);
+    });
     return names;
 }
+/**
+ * Every class token that came out of a `:global(...)` payload, wherever in a selector it sat —
+ * `.card :global(.legacy-widget) span` → `{ legacyWidget }`.
+ *
+ * This is the set a scope-suffixing caller subtracts from the tokens it owns. A token is in it
+ * whether or not the selector around it was scoped, which is the whole point: the author reached
+ * for `:global()` precisely because that name is spelled the same way in markup this file does
+ * not own, and a suffix would break the match it was reaching for.
+ *
+ * A selector the parser rejects contributes nothing — it registers no key, so it names nothing to
+ * exempt, and letting its payload leak in here would unscope a token some other rule legitimately
+ * owns.
+ */
+export function globalClassTokensIn(css, options) {
+    const tokens = new Set();
+    eachSelector(css, options, selector => {
+        if (extractClassTokens(selector) === null)
+            return;
+        for (const token of globalTokensOf(selector))
+            tokens.add(token);
+    });
+    return tokens;
+}

package/build/index.d.ts

@@ -1,6 +1,6 @@
-export { parseCSS, extractClassName, kebabToCamel } from './parser/index.ts';
+export { parseCSS, extractClassName, extractClassTokens, classTokensIn, kebabToCamel, } from './parser/index.ts';
 export type { ICssParserOptions } from './parser/index.ts';
-export { globalClassNamesIn } from './global-selectors.ts';
+export { globalClassNamesIn, globalClassTokensIn } from './global-selectors.ts';
 export { hashFilePath } from './file-scope-id.ts';
 export { compileCssFile, isCssModuleFile } from './metro-css-module/index.ts';
 export type { ICompiledCssFile } from './metro-css-module/index.ts';

package/build/index.js

@@ -1,5 +1,5 @@
-export { parseCSS, extractClassName, kebabToCamel } from "./parser/index.js";
-export { globalClassNamesIn } from "./global-selectors.js";
+export { parseCSS, extractClassName, extractClassTokens, classTokensIn, kebabToCamel, } from "./parser/index.js";
+export { globalClassNamesIn, globalClassTokensIn } from "./global-selectors.js";
 export { hashFilePath } from "./file-scope-id.js";
 export { compileCssFile, isCssModuleFile } from "./metro-css-module/index.js";
 export { classNamesToDtsSource, generateModuleDts } from "./generate-dts/index.js";

package/build/metro-transformer/index.js

@@ -8,31 +8,23 @@
 // shamefully-hoist pnpm config (.npmrc) makes that resolvable without the app adding
 // @symbiote-native/css-parser to its own package.json.
 //
-// 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.
+// `transform()` is async uniformly, even for plain `.css`: Metro's `metro-transform-worker`
+// already awaits `transformer.transform(...)` before using the result (`transformJSWithBabel` in
+// its `index.js`), so a babelTransformerPath module returning a Promise is a supported shape.
+// SCSS/Less/Stylus compilation is inherently async in Node (Less ships no sync render API;
+// Stylus's render is callback-based; Sass's sync `compileString` still needs an async
+// `import('sass')` — see preprocessors.ts). No separate sync path for plain `.css`: this only
+// runs at Metro build time, content-hash-cached, never a runtime hot path, so forking the
+// function to save one microtask isn't worth the duplication.
 import { createRequire } from 'node:module';
 import { compileCssFile } from "../metro-css-module/index.js";
 import { isStyleFile } from "../preprocessors/index.js";
-// @react-native/metro-babel-transformer is a real `dependency` of this package (not merely a
-// peer/dev dep), so it lands in css-parser's OWN resolvable node_modules under pnpm — no
-// hoisting or `paths`-anchored require.resolve trick needed, unlike the app-local workaround
-// this replaces (formerly duplicated in every adapter's example metro-css-transformer.js).
-// Exported (not just used internally) so a per-framework Metro transformer that ALSO needs to
-// delegate to the upstream RN transformer (the Vue SFC transformer, for its non-.vue passthrough
-// branch) can reuse this instead of its own fragile direct `require('@react-native/metro-babel-
-// transformer')`, which would only resolve for an external install by accident of hoisting.
+// @react-native/metro-babel-transformer is a real `dependency` of this package, so it resolves
+// via css-parser's own node_modules under pnpm — no hoisting/`paths` trick needed, unlike the
+// app-local workaround this replaces (formerly duplicated in every adapter's example
+// metro-css-transformer.js). Exported so a per-framework transformer that also needs the
+// upstream RN transformer (e.g. the Vue SFC transformer's non-.vue passthrough branch) can reuse
+// this instead of its own fragile direct `require('@react-native/metro-babel-transformer')`.
 export function resolveUpstreamTransformer() {
     const require = createRequire(import.meta.url);
     return require('@react-native/metro-babel-transformer');

package/build/parser/index.d.ts

@@ -2,6 +2,19 @@ export type ICssParserOptions = {
     filename?: string;
 };
 export declare function kebabToCamel(value: string): string;
+/**
+ * The payload of every `:global(...)` in a selector, wrapper removed and in source order:
+ * `.card :global(.legacy) span` → `['.legacy']`, `:global(.a):global(.b)` → `['.a', '.b']`.
+ *
+ * The inverse view of {@link stripGlobalWrappers}: that one keeps everything BUT the wrappers,
+ * this one keeps only what they held. Both share {@link closingParenIndex}, so "where does this
+ * `:global(` end" has a single answer — the caller-side scope-suffix question needs to know which
+ * tokens came out of a payload, and re-finding them with a second regex is how the two would
+ * drift apart on `:global(.a:not(.b))`.
+ *
+ * A nested wrapper is left inside the payload it sits in; tokenizing the payload erases it.
+ */
+export declare function globalPayloadsIn(selector: 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
@@ -13,8 +26,32 @@ export declare function kebabToCamel(value: string): string;
  * - `.card .title` / `.card > .title` → `'cardTitle'` (descendant/child, flattened)
  * - `[data-theme]` → `'dataTheme'` (attribute)
  * - `.my-class-name` → `'myClassName'` (kebab → camel)
+ * - `.card :global(.reset)` → `'cardReset'` (the `:global()` wrapper is erased, its payload kept)
  */
 export declare function extractClassName(selector: string): string | null;
+/**
+ * The individual camelCase class tokens a selector is built from — the un-collapsed form of
+ * {@link extractClassName}. `.btn.primary` → `['btn', 'primary']`, `.card .title` →
+ * `['card', 'title']`, `.card` → `['card']`; `null` on the same selectors extractClassName
+ * rejects.
+ *
+ * Needed by every caller that scope-suffixes class names (Vue `<style scoped>`, a Svelte
+ * `<style>` block): the markup those callers rewrite says `class="btn primary"`, so `btn` and
+ * `primary` are the names they must recognize as locally defined — the collapsed `btnPrimary`
+ * key appears nowhere in the markup and would leave both tokens unscoped.
+ *
+ * Tokens from inside a `:global(...)` are included here too, since the rule still only matches an
+ * element carrying them. They are the ones a caller must NOT suffix, which is a distinction this
+ * list does not carry — `globalClassTokensIn` (../global-selectors.ts) is where it lives.
+ */
+export declare function extractClassTokens(selector: string): string[] | null;
+/**
+ * Every registered class key in a stylesheet, mapped back to the class tokens it was built from
+ * (`.card.big { }` → `cardBig` → `['card', 'big']`). Build-time only, same as {@link parseCSS},
+ * whose rule walk this mirrors — at-rules are dropped first for the same reason, silently here
+ * since parseCSS already warns about them on its own pass.
+ */
+export declare function classTokensIn(css: string, options?: ICssParserOptions): Map<string, string[]>;
 /**
  * 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.

package/build/parser/index.js

@@ -20,6 +20,84 @@ function capitalize(value) {
 function unescapeIdentifier(value) {
     return value.replace(/\\(.)/g, '$1');
 }
+const GLOBAL_PSEUDO_OPEN = ':global(';
+// Index of the `)` closing the `(` at `openIndex`, or -1 if the selector is unbalanced. Counting
+// depth rather than reaching for the next `)` is what keeps `:global(.a:not(.b))` in one piece.
+function closingParenIndex(value, openIndex) {
+    let depth = 0;
+    for (let index = openIndex; index < value.length; index++) {
+        if (value[index] === '(')
+            depth++;
+        else if (value[index] === ')' && --depth === 0)
+            return index;
+    }
+    return -1;
+}
+/**
+ * Erase every `:global(...)` wrapper, leaving its payload in place: `.card :global(.legacy) span`
+ * becomes `.card .legacy span`.
+ *
+ * `:global()` says a part of the selector lives outside the file's scope; it never changes which
+ * classes an element must carry for the rule to match. So the wrapper is gone before any selector
+ * shape is recognized below, and its payload participates exactly as if it had been written bare.
+ * Which of the resulting tokens then gets a scope suffix is a separate, caller-side question that
+ * `globalClassTokensIn` (../global-selectors.ts) answers, off the payloads {@link globalPayloadsIn}
+ * hands back.
+ *
+ * This follows SVELTE, not Vue, and the two genuinely disagree. Svelte erases the wrapper per
+ * relative selector and keeps the rest of the chain scoped (`.vendors/svelte-5.53.12-src/compiler/
+ * phases/3-transform/css/index.js`, `ComplexSelector`: a part flagged `is_global` keeps its inner
+ * selectors and only skips the scope class; `css-prune.js`'s `apply_selector` sets
+ * `metadata.scoped` on every part that is not an outer `:global`). Vue's `pluginScoped` instead
+ * does `selector.replaceWith(n.nodes[0])` on `:global` (`.vendors/vue/packages/compiler-sfc/src/
+ * style/pluginScoped.ts`), which throws the REST of the chain away — `.card :global(.reset)`
+ * degrades to a stylesheet-wide `.reset`. One registry serves React, Vue, Angular and Svelte
+ * alike, so the rule that silently widens a rule's reach beyond what the author wrote is the
+ * wrong one to standardize on; Vue itself steers the reach-into-a-child case to `:deep()`.
+ */
+function stripGlobalWrappers(selector) {
+    let result = selector;
+    let start = result.indexOf(GLOBAL_PSEUDO_OPEN);
+    while (start !== -1) {
+        const close = closingParenIndex(result, start + GLOBAL_PSEUDO_OPEN.length - 1);
+        // Unbalanced: leave the text alone and let the pseudo-class guard below drop the whole rule,
+        // the same answer any other unparseable selector gets.
+        if (close === -1)
+            return result;
+        const payload = result.slice(start + GLOBAL_PSEUDO_OPEN.length, close).trim();
+        result = result.slice(0, start) + payload + result.slice(close + 1);
+        // Re-search from the same offset: a payload may itself hold a `:global(...)`, and each pass
+        // removes one wrapper, so this terminates.
+        start = result.indexOf(GLOBAL_PSEUDO_OPEN, start);
+    }
+    return result;
+}
+/**
+ * The payload of every `:global(...)` in a selector, wrapper removed and in source order:
+ * `.card :global(.legacy) span` → `['.legacy']`, `:global(.a):global(.b)` → `['.a', '.b']`.
+ *
+ * The inverse view of {@link stripGlobalWrappers}: that one keeps everything BUT the wrappers,
+ * this one keeps only what they held. Both share {@link closingParenIndex}, so "where does this
+ * `:global(` end" has a single answer — the caller-side scope-suffix question needs to know which
+ * tokens came out of a payload, and re-finding them with a second regex is how the two would
+ * drift apart on `:global(.a:not(.b))`.
+ *
+ * A nested wrapper is left inside the payload it sits in; tokenizing the payload erases it.
+ */
+export function globalPayloadsIn(selector) {
+    const payloads = [];
+    let start = selector.indexOf(GLOBAL_PSEUDO_OPEN);
+    while (start !== -1) {
+        const close = closingParenIndex(selector, start + GLOBAL_PSEUDO_OPEN.length - 1);
+        // Unbalanced: the same answer stripGlobalWrappers gives — stop, and let the selector reach
+        // the pseudo-class guard that drops the whole rule.
+        if (close === -1)
+            return payloads;
+        payloads.push(selector.slice(start + GLOBAL_PSEUDO_OPEN.length, close).trim());
+        start = selector.indexOf(GLOBAL_PSEUDO_OPEN, close + 1);
+    }
+    return payloads;
+}
 /**
  * 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
@@ -31,23 +109,42 @@ function unescapeIdentifier(value) {
  * - `.card .title` / `.card > .title` → `'cardTitle'` (descendant/child, flattened)
  * - `[data-theme]` → `'dataTheme'` (attribute)
  * - `.my-class-name` → `'myClassName'` (kebab → camel)
+ * - `.card :global(.reset)` → `'cardReset'` (the `:global()` wrapper is erased, its payload kept)
  */
 export function extractClassName(selector) {
-    const trimmed = selector.trim();
+    const tokens = extractClassTokens(selector);
+    return tokens === null ? null : joinClassTokens(tokens);
+}
+// The collapsed key is nothing but its tokens concatenated, so both forms come from ONE walk of
+// the selector — a caller that scope-suffixes names needs the tokens, everything else needs the
+// key, and two separate parsers would be two chances to disagree about what `.a\.b.c` means.
+function joinClassTokens(tokens) {
+    return tokens.map((token, index) => (index === 0 ? token : capitalize(token))).join('');
+}
+/**
+ * The individual camelCase class tokens a selector is built from — the un-collapsed form of
+ * {@link extractClassName}. `.btn.primary` → `['btn', 'primary']`, `.card .title` →
+ * `['card', 'title']`, `.card` → `['card']`; `null` on the same selectors extractClassName
+ * rejects.
+ *
+ * Needed by every caller that scope-suffixes class names (Vue `<style scoped>`, a Svelte
+ * `<style>` block): the markup those callers rewrite says `class="btn primary"`, so `btn` and
+ * `primary` are the names they must recognize as locally defined — the collapsed `btnPrimary`
+ * key appears nowhere in the markup and would leave both tokens unscoped.
+ *
+ * Tokens from inside a `:global(...)` are included here too, since the rule still only matches an
+ * element carrying them. They are the ones a caller must NOT suffix, which is a distinction this
+ * list does not carry — `globalClassTokensIn` (../global-selectors.ts) is where it lives.
+ */
+export function extractClassTokens(selector) {
+    // Erased first, ahead of every guard below: `:global(...)` legitimately carries a colon that
+    // the pseudo-class guards would otherwise trip over, and its payload has to reach the shape
+    // checks as ordinary selector text.
+    const trimmed = stripGlobalWrappers(selector.trim()).trim();
     if (/^[a-z]+$/i.test(trimmed))
         return null;
     if (trimmed === '*')
         return null;
-    // `:global(...)` (Vue `<style scoped>` escape hatch) opts a selector out of scope-suffixing —
-    // a caller concern outside this package. Here it just needs unwrapping: when the WHOLE trimmed
-    // selector is one `:global(...)` wrapper, recurse on its inner text and return whatever that
-    // resolves to, reusing every selector shape below instead of duplicating it. Checked before the
-    // "starts with :" / "any colon anywhere" guards, since `:global(...)` legitimately contains a
-    // colon that must not trigger them. Known gap: a `:global(...)` wrapping only PART of a larger
-    // compound/descendant selector (e.g. `.card :global(.reset)`) is NOT unwrapped by this check.
-    const globalMatch = trimmed.match(/^:global\(\s*(.+?)\s*\)$/);
-    if (globalMatch?.[1])
-        return extractClassName(globalMatch[1]);
     if (trimmed.startsWith(':'))
         return null;
     // A pseudo-class/-element trailing a class/id selector (`.card:hover`, `.card::before`) has
@@ -68,13 +165,7 @@ export function extractClassName(selector) {
             const startIndex = startsWithElement ? 1 : 0;
             if (startIndex >= parts.length)
                 return null;
-            return parts
-                .slice(startIndex)
-                .map((part, i) => {
-                const camelPart = kebabToCamel(unescapeIdentifier(part));
-                return i === 0 ? camelPart : capitalize(camelPart);
-            })
-                .join('');
+            return parts.slice(startIndex).map(part => kebabToCamel(unescapeIdentifier(part)));
         }
     }
     // Descendant/child selector (`.card .title`, `.card > .title`) — flattened into one name.
@@ -82,9 +173,16 @@ export function extractClassName(selector) {
         const parts = trimmed.split(/\s+(?:>\s*)?/).filter(Boolean);
         const classNames = [];
         for (const part of parts) {
-            const classMatch = part.match(/\.((?:[a-zA-Z0-9_-]|\\.)+)/);
-            if (classMatch?.[1]) {
-                classNames.push(unescapeIdentifier(classMatch[1]));
+            // Every class of the part, not just the first: a chain link may itself be compound
+            // (`.card .btn.primary`, and now `.card :global(.btn.primary)` after the erase above), and
+            // an element has to carry BOTH names for the rule to apply. Taking only `.btn` would
+            // register the rule under a key that a `class="btn primary"` element never resolves to.
+            const classMatches = [...part.matchAll(/\.((?:[a-zA-Z0-9_-]|\\.)+)/g)];
+            if (classMatches.length > 0) {
+                for (const match of classMatches) {
+                    if (match[1])
+                        classNames.push(unescapeIdentifier(match[1]));
+                }
                 continue;
             }
             const idMatch = part.match(/#((?:[a-zA-Z0-9_-]|\\.)+)/);
@@ -93,27 +191,46 @@ export function extractClassName(selector) {
         }
         if (classNames.length === 0)
             return null;
-        return classNames
-            .map((name, i) => {
-            const camelName = kebabToCamel(name);
-            return i === 0 ? camelName : capitalize(camelName);
-        })
-            .join('');
+        return classNames.map(name => kebabToCamel(name));
     }
     // Single class selector (`.card`).
     const classMatch = trimmed.match(/^\.((?:[a-zA-Z0-9_-]|\\.)+)/);
     if (classMatch?.[1])
-        return kebabToCamel(unescapeIdentifier(classMatch[1]));
+        return [kebabToCamel(unescapeIdentifier(classMatch[1]))];
     // ID selector (`#header`).
     const idMatch = trimmed.match(/^#((?:[a-zA-Z0-9_-]|\\.)+)/);
     if (idMatch?.[1])
-        return kebabToCamel(unescapeIdentifier(idMatch[1]));
+        return [kebabToCamel(unescapeIdentifier(idMatch[1]))];
     // Attribute selector (`[data-theme]`).
     const attrMatch = trimmed.match(/^\[([a-zA-Z0-9_-]+)(?:=[^\]]+)?\]/);
     if (attrMatch?.[1])
-        return kebabToCamel(attrMatch[1]);
+        return [kebabToCamel(attrMatch[1])];
     return null;
 }
+/**
+ * Every registered class key in a stylesheet, mapped back to the class tokens it was built from
+ * (`.card.big { }` → `cardBig` → `['card', 'big']`). Build-time only, same as {@link parseCSS},
+ * whose rule walk this mirrors — at-rules are dropped first for the same reason, silently here
+ * since parseCSS already warns about them on its own pass.
+ */
+export function classTokensIn(css, options) {
+    const tokensByName = new Map();
+    if (!css || typeof css !== 'string')
+        return tokensByName;
+    const root = postcss.parse(css, { from: options?.filename });
+    root.walkAtRules(atRule => {
+        atRule.remove();
+    });
+    root.walkRules(rule => {
+        for (const selector of rule.selector.split(',')) {
+            const tokens = extractClassTokens(selector.trim());
+            if (tokens === null || tokens.length === 0)
+                continue;
+            tokensByName.set(joinClassTokens(tokens), tokens);
+        }
+    });
+    return tokensByName;
+}
 //#endregion Selector utilities
 //#region var() resolution
 function resolveVariables(value, variables) {

package/build/properties.js

@@ -35,9 +35,9 @@ export const PROPERTY_TABLE = {
     overflow: { rnProperty: 'overflow', kind: 'raw' },
     // Only `flex`/`none` are valid RN values; passed through unvalidated per spec.
     display: { rnProperty: 'display', kind: 'raw' },
-    // A genuine 1:1 CSS property (unlike transform/shadow — no shape mismatch), just missing
-    // from the initial table. `2 / 3` string ratios are not accepted here (`parseNumeric`
-    // requires a plain number) — CSS `aspect-ratio: 0.667` works, `aspect-ratio: 2/3` doesn't yet.
+    // A genuine 1:1 CSS property (unlike transform/shadow, no shape mismatch). `2 / 3` string
+    // ratios are not accepted here (`parseNumeric` requires a plain number) — CSS
+    // `aspect-ratio: 0.667` works, `aspect-ratio: 2/3` doesn't yet.
     'aspect-ratio': { rnProperty: 'aspectRatio', kind: 'number' },
     gap: { rnProperty: 'gap', kind: 'dimension' },
     'row-gap': { rnProperty: 'rowGap', kind: 'dimension' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@symbiote-native/css-parser",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Build-time CSS/SCSS/Less/Stylus compiler for SymbioteNative — compiles stylesheets to React Native style objects, resolved at runtime via a cross-adapter class-name registry.",
   "license": "MIT",
   "repository": {

package/typescript-plugin.cjs

@@ -21,22 +21,20 @@
 // a correct, non-approximated preprocessor pipeline can't run here today. Those files still get
 // basic (non-literal) type coverage from the project's ambient `.css` fallback declaration and
 // from `css-dts`'s on-disk generation at pretypecheck time — just without live per-class
-// completion in the plugin. A real follow-up, not a silent gap: recorded here, not hidden.
+// completion in the plugin.
 //
 // SCOPE, second cut: only a SIMPLE `.foo { ... }` class selector is recognized correctly — a
 // compound (`.btn.primary`) or descendant (`.card .title`) selector, which the real
 // src/parser.ts's extractClassName merges into ONE key (`btnPrimary`/`cardTitle`), gets
-// extracted here as TWO separate (wrong, non-existent) keys instead. This is an accepted
-// limitation of the regex-based approach — complex selectors may not be detected correctly.
+// extracted here as TWO separate (wrong, non-existent) keys instead.
 //
 // Hand-written plain CommonJS, NOT compiled from a `.ts`/`.cts` source — same convention already
 // used for each adapter's metro-css-parser.cjs shim. tsserver loads a plugin via a synchronous
 // `require()`, which cannot load this package's own ESM build output; a `.cts` source was tried
-// first and rejected because
-// this package's shared tsconfig (`moduleResolution: "Bundler"`, needed for the rest of the
-// package) doesn't apply the classic .cts→CJS format-forcing TypeScript otherwise gives Node16/
-// NodeNext projects — carving out a second tsconfig/project reference just for one file was more
-// machinery than a ~150-line, dependency-free plugin warrants.
+// first and rejected because this package's shared tsconfig (`moduleResolution: "Bundler"`,
+// needed for the rest of the package) doesn't apply the classic .cts→CJS format-forcing
+// TypeScript otherwise gives Node16/NodeNext projects — carving out a second tsconfig/project
+// reference just for one file was more machinery than a ~150-line, dependency-free plugin warrants.
 'use strict';
 
 const fs = require('node:fs');
@@ -70,7 +68,7 @@ function generateDts(classNames) {
 
   const fields = [...classNames]
     .sort()
-    .map((name) => {
+    .map(name => {
       const key = IDENTIFIER_RE.test(name) ? name : JSON.stringify(name);
       return `  readonly ${key}: string;`;
     })
@@ -118,12 +116,14 @@ function init(modules) {
     const originalGetScriptSnapshot = host.getScriptSnapshot.bind(host);
     const originalResolveModuleNameLiterals = host.resolveModuleNameLiterals;
 
-    host.getScriptKind = (fileName) =>
+    host.getScriptKind = fileName =>
       isCssModuleFile(fileName)
         ? typescript.ScriptKind.TS
-        : (originalGetScriptKind ? originalGetScriptKind(fileName) : typescript.ScriptKind.Unknown);
+        : originalGetScriptKind
+          ? originalGetScriptKind(fileName)
+          : typescript.ScriptKind.Unknown;
 
-    host.getScriptSnapshot = (fileName) =>
+    host.getScriptSnapshot = fileName =>
       isCssModuleFile(fileName)
         ? typescript.ScriptSnapshot.fromString(getDtsForCssFile(fileName))
         : originalGetScriptSnapshot(fileName);