@symbiote-native/css-parser 0.3.0 → 0.4.0

package/build/lightning/rules.d.ts

@@ -0,0 +1,52 @@
+import type { CSSModuleExports } from 'lightningcss';
+import { type IStyleObject } from './declarations.ts';
+import { type ISelectorCombinator } from './selectors.ts';
+export interface IStyleRule {
+    /** Class names as authored, then through {@link ICompiledCss.exports} when a pattern renamed them. */
+    readonly tokens: readonly string[];
+    readonly specificity: readonly [number, number, number];
+    /** Source order across the whole file, 0-based. Breaks a specificity tie, as the cascade does. */
+    readonly order: number;
+    readonly style: IStyleObject;
+    /**
+     * One per gap between tokens. Carried but NOT yet consumed: the registry matches a rule by token
+     * SUBSET, so `.a .b` still fires like `.a.b` today (trap 6). Stage 4 is where this starts to
+     * mean something — it needs parent pointers, which only exist after the engine's commit walk.
+     */
+    readonly combinators: readonly ISelectorCombinator[];
+}
+export interface ICompileRulesOptions {
+    readonly filename: string;
+    /** Root font size for `rem`. */
+    readonly remToPx?: number;
+    /**
+     * A lightningcss CSS-Modules pattern, `[local]` first — `[local]__module__<hash>` for a
+     * `.module.*` file or a Vue `<style module>`, `[local]__data-v-<hash>` for a Vue `<style
+     * scoped>`, `[local]__svelte-<hash>` for a Svelte `<style>`. Omitted for a plain global `.css`.
+     */
+    readonly pattern?: string;
+}
+export interface ICompiledCss {
+    readonly rules: readonly IStyleRule[];
+    /**
+     * Authored class name -> the name it registers under, straight out of lightningcss. Empty
+     * without a `pattern`. The markup rewriter reads THIS — never its own recomputation of the
+     * name, which is the bug class the single-renamer design exists to close.
+     */
+    readonly exports: Readonly<Record<string, string>>;
+    /**
+     * The same map unflattened, kept because CSS Modules needs more than the new name: `composes`
+     * lives on the entry, and resolving a chain (`.a composes .b composes .c`) walks it. Empty
+     * without a `pattern`.
+     */
+    readonly moduleExports: CSSModuleExports;
+    /**
+     * Class tokens the rules use that lightningcss did NOT rename. Under a `pattern` that means
+     * exactly one thing — the name came out of a `:global()` — so the escape hatch is DERIVED here
+     * rather than re-detected by walking selectors a second time (which is all
+     * a retired second selector walk ever was). Without a pattern nothing is renamed, so this is
+     * simply every token in the file, and no caller has a use for it.
+     */
+    readonly globals: ReadonlySet<string>;
+}
+export declare function compileCssToRules(css: string, options: ICompileRulesOptions): ICompiledCss;

package/build/lightning/rules.js

@@ -0,0 +1,157 @@
+// The glue of the lightningcss-typed pipeline: CSS text in, engine style RULES out. One
+// `transform()` call feeds both halves — `./selectors.ts` for the selector, `./declarations.ts`
+// for the values — and nothing in between re-derives a name from text.
+//
+// WHY a rule instead of a key. The retired text pipeline COLLAPSED a selector into one string
+// key (`.a.b` -> `aB`, camelCased) and the runtime registry reversed that guess by
+// permuting the element's class tokens. Every lossy step in the collapse mapped two different
+// selectors onto one key and the later rule silently overwrote the earlier — the seventh trap in
+// `.claude/rules/style-registry-collisions.md`. A rule carries the TOKEN SET the selector was
+// written with, so the registry matches by subset and there is nothing to guess or reverse.
+//
+// Class names are emitted AS AUTHORED (`card-title` stays `card-title`, plus whatever the scoping
+// rename appended). No camelCase anywhere in this file: normalization is what the trap was made of.
+//
+// Measured 2026-08-20 and the reason this is ONE pass, not two: with `cssModules` on, the visitor
+// still sees the ORIGINAL class names — lightningcss renames AFTER the visitor walk. So the AST
+// gives authored tokens and `exports` gives their renamed spelling, and the renamed CSS text never
+// has to be parsed a second time (which is exactly what `../metro-css-module/index.ts` had to do,
+// and what mangled a scope tail whose base36 hash began with a letter).
+//
+// `:global()` is the one thing the mode DOES change, and it changes shape rather than presence:
+// with `cssModules` off it is a `custom-function` pseudo-class holding a raw token stream, with it
+// on a `kind:'global'` pseudo-class holding a real parsed selector. `./selectors.ts` handles both;
+// either way the tokens come out and `exports` not naming them is what marks them global.
+import { transform } from 'lightningcss';
+import { declarationToStyle, variablesIn, } from "./declarations.js";
+import { selectorsToMatches } from "./selectors.js";
+import { warnOnce } from "../values.js";
+// A conditional at-rule is DROPPED WHOLE, its nested rules with it. There is no media-query engine
+// in React Native, so applying `.responsive` from `@media (min-width: 900px)` would paint it on
+// every phone — worse than not supporting the rule, because it looks supported. The retired text
+// pass dropped these too, but silently: it simply never walked into an at-rule. Measured
+// 2026-08-20: returning `[]` from the at-rule visitor removes it BEFORE the walk descends, so a
+// nested style rule never reaches the collector; without it lightningcss hoists it out.
+//
+// `@keyframes` and `@font-face` need no entry here — neither emits a style rule to begin with.
+const CONDITIONAL_AT_RULES = ['media', 'supports', 'container'];
+// The wrappers `./selectors.ts` unwraps itself. lightningcss implements neither, so it reports both
+// as an unsupported pseudo-class even though the rule survives.
+const HANDLED_PSEUDO_CLASSES = new Set(['global', 'deep']);
+function isHandledPseudoClass(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const record = { ...value };
+    return (record.type === 'UnsupportedPseudoClass' &&
+        typeof record.value === 'string' &&
+        HANDLED_PSEUDO_CLASSES.has(record.value));
+}
+export function compileCssToRules(css, options) {
+    const { filename, pattern, remToPx } = options;
+    const collected = [];
+    const exports = {};
+    const warned = new Set();
+    const dropAtRule = (name) => () => {
+        warnOnce(warned, `at-rule:${name}`, `[@symbiote-native/css-parser] ${filename}: \`@${name}\` is not supported — the rules ` +
+            'inside it are dropped. React Native evaluates no CSS condition at all; branch in JS ' +
+            '(useWindowDimensions, Platform) instead.');
+        return [];
+    };
+    const result = transform({
+        filename,
+        code: Buffer.from(css),
+        // A rule lightningcss cannot use must not take the whole file down: the retired text pass
+        // never threw either, and a stylesheet is authored content, not our code.
+        errorRecovery: true,
+        // Without this `>>>` / `/deep/` die at parse as a dangling combinator, so the selector half
+        // never gets the chance to fold them. Inert until stage 4 consumes a combinator.
+        nonStandard: { deepSelectorCombinator: true },
+        ...(pattern === undefined ? {} : { cssModules: { pattern } }),
+        visitor: {
+            Rule: {
+                ...Object.fromEntries(CONDITIONAL_AT_RULES.map(name => [name, dropAtRule(name)])),
+                style(rule) {
+                    // Every reason but `root` is announced by `selectorsToMatches` itself, with the
+                    // explanation spelled out for the author — warning again from this level printed the
+                    // same drop twice. `root` is the exception it hands back silently, because only here
+                    // are the declarations in scope, and a `:root` block is worth a word ONLY when it
+                    // carries something that would have painted. Custom properties are its whole purpose
+                    // and are already collected by `collectCustomProperties`.
+                    const { matches, dropped } = selectorsToMatches(rule.value.selectors, filename);
+                    // `importantDeclarations` last: `!important` wins inside its own rule, and a later
+                    // entry overwrites an earlier one when both name the same RN property.
+                    const declarations = [
+                        ...rule.value.declarations.declarations,
+                        ...rule.value.declarations.importantDeclarations,
+                    ];
+                    if (dropped.some(entry => entry.reason === 'root') &&
+                        declarations.some(declaration => declaration.property !== 'custom')) {
+                        warnOnce(warned, `root-paints:${filename}`, `[@symbiote-native/css-parser] ${filename}: a \`:root\` rule declares more than ` +
+                            'custom properties — everything else in it is dropped, because `:root` matches no ' +
+                            'node in React Native. Move those declarations onto a class.');
+                    }
+                    for (const match of matches) {
+                        collected.push({ ...match, declarations });
+                    }
+                },
+            },
+        },
+    });
+    // `errorRecovery` keeps a malformed rule from taking the file down, but silence is how a whole
+    // rule disappears unnoticed: `examples/angular/**/ApiPlaygroundScreen.css` had a comment closed
+    // early by a `.hero-*/` inside it, which swept the real class after it into a garbage selector.
+    // The retired text pass "recovered" by registering the garbage; this one drops it — either way
+    // the author has to be told.
+    //
+    // Two things this loop must NOT do. It must not claim an outcome — a SelectorError drops the
+    // rule but a value-level one drops only the declaration, and asserting the wrong one is worse
+    // than staying quiet about it. And it must not repeat a complaint we deliberately answer:
+    // lightningcss does not implement `:global()` or `:deep()`, so it warns "not recognized as a
+    // valid pseudo-class" for both while `./selectors.ts` unwraps them and keeps the rule. Passing
+    // that through told the author their working rule was thrown away.
+    for (const warning of result.warnings) {
+        if (isHandledPseudoClass(warning.value))
+            continue;
+        const where = `${warning.loc.line}:${warning.loc.column}`;
+        warnOnce(warned, `lightningcss:${warning.type}:${warning.message}`, `[@symbiote-native/css-parser] ${filename}:${where}: ${warning.message}`);
+    }
+    // Sorted: `exports` is a Rust HashMap whose iteration order is randomized PER PROCESS, and this
+    // map is emitted into a generated module — an unsorted one churns Metro's content cache.
+    for (const [local, entry] of Object.entries(result.exports ?? {}).sort(([left], [right]) => (left < right ? -1 : 1))) {
+        exports[local] = entry.name;
+    }
+    // Custom properties come from their own pass because nothing guarantees `:root` is declared
+    // before the rule that reads it — the retired text pass had the same two-phase shape.
+    const variables = variablesIn(css, filename);
+    const context = {
+        filename,
+        variables,
+        ...(remToPx === undefined ? {} : { remToPx }),
+    };
+    const globals = new Set();
+    const rules = collected.map((rule, order) => ({
+        tokens: rule.tokens.map(token => {
+            const renamed = exports[token];
+            if (renamed === undefined)
+                globals.add(token);
+            return renamed ?? token;
+        }),
+        specificity: rule.specificity,
+        combinators: rule.combinators,
+        order,
+        style: rule.declarations.reduce((style, declaration) => ({
+            ...style,
+            ...declarationToStyle(declaration, context),
+        }), {}),
+    }));
+    // A rule whose every declaration was dropped — all unsupported, or all `var()`s declared in
+    // another file — has nothing to contribute, and keeping it only adds a candidate the registry
+    // must consider on every lookup of those tokens.
+    const painting = rules.filter(rule => Object.keys(rule.style).length > 0);
+    return {
+        rules: painting,
+        exports,
+        moduleExports: result.exports ?? {},
+        globals,
+    };
+}

package/build/lightning/selectors.d.ts

@@ -0,0 +1,21 @@
+export type ISelectorCombinator = 'none' | 'descendant' | 'child' | 'next-sibling' | 'later-sibling' | 'deep';
+export interface ISelectorMatch {
+    /** Class names AS AUTHORED — NO camelCase, NO collapsing, in source order. */
+    readonly tokens: readonly string[];
+    /** CSS specificity (a,b,c) = (id, class/attr/pseudo-class, element/pseudo-element). */
+    readonly specificity: readonly [number, number, number];
+    /** The combinators between the tokens, one per gap (length === tokens.length - 1). */
+    readonly combinators: readonly ISelectorCombinator[];
+}
+export interface IDroppedSelector {
+    readonly reason: 'root' | 'pseudo-class' | 'pseudo-element' | 'attribute' | 'element' | 'id' | 'universal' | 'unsupported';
+    /** e.g. 'hover', '[data-x]', 'div'. */
+    readonly detail: string;
+}
+export interface ISelectorResult {
+    /** One per comma-separated selector that is usable. */
+    readonly matches: readonly ISelectorMatch[];
+    /** The rest, with a reason. */
+    readonly dropped: readonly IDroppedSelector[];
+}
+export declare function selectorsToMatches(selectors: unknown, filename: string): ISelectorResult;

package/build/lightning/selectors.js

@@ -0,0 +1,372 @@
+// Selector reading for the lightningcss pipeline: an AST walk that replaced the retired
+// text-based `extractClassName` / `extractClassTokens` pair.
+//
+// That pair derived a registry key from the SELECTOR TEXT — it camelCased each class, collapsed
+// every class in the selector into one concatenated key, and returned `null` for whatever its
+// regexes failed to recognize. Each of those steps is lossy in a way that maps two different
+// rules onto ONE key, and the later rule then overwrites the earlier per property, silently:
+//
+//   .card-title{…} .cardTitle{…}   -> both key `cardTitle`   the first rule is GONE
+//   .card:hover{…} .card{…}        -> both key `card`        the :hover rule OVERWRITES the base
+//   .card[data-x]{…}               -> key `card[dataX]`      a key no element can ever carry
+//   .a.b / .a .b / .a>.b / .a+.b   -> all key `aB`           five selectors, one key, merged
+//
+// (Traps six and seven in `.claude/rules/style-registry-collisions.md`, measured 2026-08-20.)
+//
+// So this module reports what the selector ACTUALLY says and refuses to guess:
+//   - tokens stay AS AUTHORED — `card-title` is `card-title`. Casing is the caller's problem, and
+//     a caller that never re-cases can never collide two spellings onto one key.
+//   - the class list stays a LIST, with the combinator of every gap beside it, so a descendant
+//     rule is distinguishable from a compound one instead of both flattening to a concatenation.
+//   - a selector RN can never match (pseudo-class/-element, attribute, element, id, universal) is
+//     dropped WITH a reason and a warning, rather than silently degrading into a key that either
+//     collides with a real rule or matches nothing at all.
+//
+// The caller must pass `nonStandard: { deepSelectorCombinator: true }` to lightningcss's
+// `transform`/`bundle` for a `deep` combinator to ever appear: without it `>>>` and `/deep/` are
+// rejected at parse time as an invalid dangling combinator and the whole rule is lost before this
+// walk sees it. That flag covers ONLY those two spellings — the other three deep forms are not
+// lightningcss features at all and need no flag, so do not go re-reading its docs looking for
+// them: `::v-deep` / `::ng-deep` arrive as an ordinary custom pseudo-element between two
+// descendant combinators, and Vue's `:deep(X)` as a custom-function pseudo-class whose payload is
+// a raw token stream — structurally the same thing `:global(X)` is under that same mode. All three
+// are folded into `deep` here.
+//
+// `:global(X)` arrives in TWO DIFFERENT SHAPES and BOTH are live, so both are handled (measured
+// 2026-08-20, lightningcss 1.32, same CSS through both modes):
+//
+//   cssModules OFF  {kind:'custom-function', name:'global', arguments:[…raw token stream…]}
+//   cssModules ON   {kind:'global',          selector:[…parsed SelectorComponent[]…]}
+//
+// A `.module.css` / scoped file runs WITH cssModules and gets the parsed form; the plain-`.css`
+// pipeline runs WITHOUT it and gets the token stream. Handling only one of them silently drops the
+// whole rule on the other — which is exactly how `:global(.reset)` in a `.module.css` came to
+// contribute no rule and no export. `:deep()` does NOT have this split: lightningcss implements no
+// `:deep()` at all, so it is the raw custom-function form under BOTH modes.
+// Why the rule can never fire on a device, per reason — the half of the warning that tells an
+// author what to do instead of just what was thrown away.
+const DROP_EXPLANATION = {
+    root: 'a `:root` rule paints nothing — it exists to declare custom properties, which are collected by their own pass',
+    'pseudo-class': 'React Native has no pseudo-class state (no hover/focus/nth-child)',
+    'pseudo-element': 'React Native has no pseudo-elements',
+    attribute: 'React Native has no attribute selectors',
+    element: 'React Native has no element/tag selectors',
+    id: 'React Native has no id selectors',
+    universal: 'React Native has no universal selector',
+    unsupported: 'this selector shape has no React Native equivalent',
+};
+const DEEP_PSEUDO_ELEMENTS = new Set(['v-deep', 'ng-deep']);
+// Every `SelectorComponent['type']`, so the guard below rejects a shape lightningcss does not
+// produce instead of trusting any object that happens to carry a `type` string.
+const SELECTOR_COMPONENT_TYPES = new Set([
+    'combinator',
+    'universal',
+    'namespace',
+    'type',
+    'id',
+    'class',
+    'attribute',
+    'pseudo-class',
+    'pseudo-element',
+    'nesting',
+]);
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function isSelectorComponent(value) {
+    return (isRecord(value) &&
+        typeof value.type === 'string' &&
+        SELECTOR_COMPONENT_TYPES.has(value.type));
+}
+function isTokenOrValue(value) {
+    return isRecord(value) && typeof value.type === 'string';
+}
+/** The subset of lightningcss combinators this pipeline can act on; the rest drop the rule. */
+function combinatorFor(value) {
+    switch (value) {
+        case 'descendant':
+        case 'child':
+        case 'next-sibling':
+        case 'later-sibling':
+            return value;
+        // `>>>` and `/deep/` differ only in spelling; a caller that treats them apart would be
+        // encoding CSS trivia, not a matching rule.
+        case 'deep-descendant':
+        case 'deep':
+            return 'deep';
+        default:
+            return null;
+    }
+}
+function createBuilder() {
+    return {
+        tokens: [],
+        combinators: [],
+        specificity: [0, 0, 0],
+        pending: 'none',
+        drop: null,
+    };
+}
+function pushToken(builder, name) {
+    if (builder.tokens.length > 0)
+        builder.combinators.push(builder.pending);
+    builder.tokens.push(name);
+    builder.pending = 'none';
+}
+function setCombinator(builder, next) {
+    // A descendant never downgrades an explicit combinator already pending. lightningcss brackets
+    // `::v-deep` with a synthetic descendant on BOTH sides, and inside a `:global()` token stream
+    // `>` arrives surrounded by whitespace — in either case the second descendant would otherwise
+    // erase the real combinator the author wrote.
+    if (next === 'descendant' && builder.pending !== 'none')
+        return;
+    builder.pending = next;
+}
+function drop(builder, reason, detail) {
+    builder.drop ??= { reason, detail };
+}
+//#region custom-function payload token streams
+/**
+ * Fold the payload of a custom-function pseudo-class into the builder as if its classes had been
+ * written bare. Serves both `:global(X)` and `:deep(X)` — lightningcss implements neither, so both
+ * arrive in the identical shape and one unwrapper covers them.
+ *
+ * This is the RAW-TOKEN half of `:global()`, which is the shape a PLAIN `.css` file produces —
+ * it is not run through cssModules, so `:global()` stays a `custom-function` pseudo-class whose
+ * arguments are an unparsed token stream (measured, lightningcss 1.32): `:global(.a > .b)` arrives
+ * as delim `.` · ident `a` · white-space · delim `>` · white-space · delim `.` · ident `b`.
+ * With cssModules ON the same source arrives as `kind:'global'` carrying a real parsed selector,
+ * handled where that kind is matched — `:global()` never disappears, it changes shape, and
+ * assuming the mode erased it is what silently killed the rule in every `.module.*` file.
+ *
+ * Neither wrapper changes which classes an element must carry — `:global()` only says a name lives
+ * outside the file's scope, `:deep()` only says the match may cross a scope boundary. So the
+ * payload participates exactly as if unwrapped, the rule `stripGlobalWrappers` follows in the text
+ * parser. `wrapper` is the authored spelling, used only so a drop warning names the right one.
+ */
+function consumePayload(builder, args, wrapper) {
+    for (let index = 0; index < args.length; index++) {
+        const argument = args[index];
+        if (!isTokenOrValue(argument) || argument.type !== 'token') {
+            drop(builder, 'unsupported', wrapper);
+            return;
+        }
+        const token = argument.value;
+        switch (token.type) {
+            case 'white-space':
+                setCombinator(builder, 'descendant');
+                break;
+            case 'delim': {
+                if (token.value === '>') {
+                    setCombinator(builder, 'child');
+                    break;
+                }
+                if (token.value === '+') {
+                    setCombinator(builder, 'next-sibling');
+                    break;
+                }
+                if (token.value === '~') {
+                    setCombinator(builder, 'later-sibling');
+                    break;
+                }
+                if (token.value === '*') {
+                    drop(builder, 'universal', '*');
+                    break;
+                }
+                if (token.value !== '.') {
+                    drop(builder, 'unsupported', `${wrapper.slice(0, -1)}${token.value})`);
+                    break;
+                }
+                // A class is two tokens — delim `.` then the ident. A `.` with no ident behind it means
+                // the payload is malformed, and nothing about it is then trustworthy.
+                const name = identAt(args, index + 1);
+                if (name === null) {
+                    drop(builder, 'unsupported', wrapper);
+                    return;
+                }
+                builder.specificity[1]++;
+                pushToken(builder, name);
+                index++;
+                break;
+            }
+            case 'colon': {
+                // One colon is a pseudo-class, two a pseudo-element; either way the name is the ident
+                // after them, and reporting it is the difference between a warning an author can act on
+                // and one that only says ":global()" / ":deep()".
+                const isPseudoElement = isColonAt(args, index + 1);
+                const nameIndex = index + (isPseudoElement ? 2 : 1);
+                const name = identAt(args, nameIndex) ?? wrapper;
+                builder.specificity[isPseudoElement ? 2 : 1]++;
+                drop(builder, isPseudoElement ? 'pseudo-element' : 'pseudo-class', name);
+                index = nameIndex;
+                break;
+            }
+            case 'ident':
+                builder.specificity[2]++;
+                drop(builder, 'element', token.value);
+                break;
+            case 'id-hash':
+                builder.specificity[0]++;
+                drop(builder, 'id', `#${token.value}`);
+                break;
+            case 'square-bracket-block': {
+                // The parsed shape reports `[data-x]` by name, so the token stream reads the name too —
+                // otherwise the same CSS would warn differently depending on the cssModules flag. The
+                // block's remaining tokens are left to fall through: they can only add a second drop, and
+                // the first one already recorded is the one reported.
+                const name = identAt(args, index + 1);
+                builder.specificity[1]++;
+                drop(builder, 'attribute', name === null ? '[…]' : `[${name}]`);
+                break;
+            }
+            default:
+                drop(builder, 'unsupported', wrapper);
+                break;
+        }
+    }
+}
+function identAt(args, index) {
+    const argument = args[index];
+    if (!isTokenOrValue(argument) || argument.type !== 'token')
+        return null;
+    return argument.value.type === 'ident' ? argument.value.value : null;
+}
+function isColonAt(args, index) {
+    const argument = args[index];
+    return (isTokenOrValue(argument) &&
+        argument.type === 'token' &&
+        argument.value.type === 'colon');
+}
+//#endregion custom-function payload token streams
+function consumeComponent(builder, component) {
+    switch (component.type) {
+        case 'class':
+            builder.specificity[1]++;
+            pushToken(builder, component.name);
+            return;
+        case 'combinator': {
+            const combinator = combinatorFor(component.value);
+            if (combinator === null) {
+                drop(builder, 'unsupported', component.value);
+                return;
+            }
+            setCombinator(builder, combinator);
+            return;
+        }
+        case 'id':
+            builder.specificity[0]++;
+            drop(builder, 'id', `#${component.name}`);
+            return;
+        case 'type':
+            builder.specificity[2]++;
+            drop(builder, 'element', component.name);
+            return;
+        case 'universal':
+            drop(builder, 'universal', '*');
+            return;
+        case 'attribute':
+            builder.specificity[1]++;
+            drop(builder, 'attribute', `[${component.name}]`);
+            return;
+        case 'pseudo-class':
+            // Neither wrapper contributes specificity of its own — the payload's classes carry it.
+            // The parsed `:global(X)` of cssModules mode. Its payload is an ordinary component array, so
+            // the SAME walk reads it — which is also why a non-class payload drops with the payload's
+            // own reason here for free, identically to the token-stream branch below.
+            if (component.kind === 'global') {
+                consumeSelector(builder, component.selector);
+                return;
+            }
+            // `:root` is not state — it is where an author is SUPPOSED to declare custom properties, and
+            // `collectCustomProperties` has already read them by the time this runs. Reported with its
+            // own reason so the caller can stay silent about the ordinary token sheet and speak up only
+            // when the rule also carries a declaration that would have painted. Warning unconditionally
+            // meant every stylesheet with a `:root { --token: … }` block printed "it can never match",
+            // about the one construct the docs tell people to write.
+            if (component.kind === 'root') {
+                drop(builder, 'root', 'root');
+                return;
+            }
+            if (component.kind === 'custom-function') {
+                if (component.name === 'global') {
+                    consumePayload(builder, component.arguments, ':global()');
+                    return;
+                }
+                if (component.name === 'deep') {
+                    // `:deep(X)` reaches THROUGH a scope boundary into X — the same relation `>>>` and
+                    // `::v-deep` express, so the gap into X's own tokens is `deep`, overriding the
+                    // descendant lightningcss reports just before it.
+                    setCombinator(builder, 'deep');
+                    consumePayload(builder, component.arguments, ':deep()');
+                    return;
+                }
+            }
+            // `:not()`/`:is()` take the specificity of their argument rather than a flat 1, but they are
+            // dropped here regardless, and only a KEPT selector's specificity is ever read.
+            builder.specificity[1]++;
+            drop(builder, 'pseudo-class', component.kind === 'custom' || component.kind === 'custom-function'
+                ? component.name
+                : component.kind);
+            return;
+        case 'pseudo-element':
+            if (component.kind === 'custom' &&
+                DEEP_PSEUDO_ELEMENTS.has(component.name)) {
+                setCombinator(builder, 'deep');
+                return;
+            }
+            builder.specificity[2]++;
+            drop(builder, 'pseudo-element', component.kind === 'custom' || component.kind === 'custom-function'
+                ? component.name
+                : component.kind);
+            return;
+        // `namespace` (`ns|div`) and `nesting` (`&`) both need context this compiler does not have.
+        default:
+            drop(builder, 'unsupported', component.type);
+            return;
+    }
+}
+/**
+ * `selectors` is lightningcss's own `rule.value.selectors` (an array of selector-component
+ * arrays). Each entry is one comma-separated selector and is judged on its own: a list where some
+ * parts survive and some drop yields both a match and a drop.
+ */
+function consumeSelector(builder, selector) {
+    for (const component of selector) {
+        if (!isSelectorComponent(component)) {
+            drop(builder, 'unsupported', String(component));
+            continue;
+        }
+        consumeComponent(builder, component);
+    }
+}
+export function selectorsToMatches(selectors, filename) {
+    if (!Array.isArray(selectors))
+        return { matches: [], dropped: [] };
+    const matches = [];
+    const dropped = [];
+    for (const selector of selectors) {
+        if (!Array.isArray(selector) || selector.length === 0)
+            continue;
+        const builder = createBuilder();
+        consumeSelector(builder, selector);
+        // No class survived and nothing explained why (a lone `::v-deep`, an empty compound) — there
+        // is still nothing to register, so say so rather than emitting a match with zero tokens.
+        if (builder.drop === null && builder.tokens.length === 0)
+            drop(builder, 'unsupported', 'no class selector');
+        const problem = builder.drop;
+        if (problem !== null) {
+            dropped.push(problem);
+            // `root` is returned, never announced from here — see DROP_EXPLANATION.root.
+            if (problem.reason === 'root')
+                continue;
+            console.warn(`[@symbiote-native/css-parser] ${filename}: dropped a rule on \`${problem.detail}\` — ${DROP_EXPLANATION[problem.reason]}, so it can never match in React Native.`);
+            continue;
+        }
+        matches.push({
+            tokens: builder.tokens,
+            combinators: builder.combinators,
+            specificity: builder.specificity,
+        });
+    }
+    return { matches, dropped };
+}

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

@@ -1,6 +1,34 @@
-import { type ICssParserOptions } from '../parser/index.ts';
+import { type IStyleRule } from '../lightning/rules.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>;
+export type ICompiledCssModule = {
+    /** The rules, their tokens already carrying the scope. */
+    rules: readonly IStyleRule[];
+    /** The default export: authored name -> the token(s) to put in the markup. */
+    classMap: Record<string, string>;
+};
+/**
+ * One CSS source compiled as a CSS MODULE — a standalone `.module.*` file and a Vue
+ * `<style module>` block are the same thing and go through this, so neither can register a class
+ * under a name the other would not.
+ *
+ * The scope tail is our own `hashFilePath`, not lightningcss's `[hash]`: the runtime registry
+ * parses this tail to factor a scope back out (SCOPE_TAIL_PATTERN in
+ * core/engine/src/style-registry) and its alphabet is lowercase base36, which lightningcss's
+ * mixed-case hash does not fit — that would silently kill scoped-token base layering. Same hash
+ * the `<style scoped>` and Svelte scopers use, so all three scoping shapes stay one algorithm.
+ */
+export declare function compileCssModule(css: string, filename: string): ICompiledCssModule;
+/**
+ * The names a `.module.*` file's default export actually carries.
+ *
+ * The `.d.ts` generator MUST read them from here rather than re-deriving names off the raw
+ * source: what a rule MATCHES on and what the module EXPORTS are different sets. A compound
+ * rule `.card.big` matches on both its tokens, but only the names the author wrote as classes
+ * are exports. Typing off a re-derived set invents members that are `undefined` at runtime and
+ * hides valid ones behind a TS2339.
+ */
+export declare function moduleClassNames(source: string, filename: string): Promise<string[]>;
+export declare function compileCssFile(source: string, filename: string): Promise<ICompiledCssFile>;