@symbiote-native/engine 0.1.7 → 0.3.0

package/build/process-transform/index.js

@@ -1,19 +1,15 @@
 // JS-side port of RN's processTransform (Libraries/StyleSheet/processTransform.js).
-// Same root cause as transformOrigin/boxShadow: ReactNativeStyleAttributes registers
-// `transform` with `nativeCSSParsing ? true : {process: processTransform}`, and
-// enableNativeCSSParsing() DEFAULTS TO FALSE, so RN's stock path runs processTransform
-// IN JS. It only does work for a STRING input (parses the CSS string into the entry
-// array); an ARRAY input is returned UNCHANGED. symbiote forwarded a raw string, which
-// Android native cast to ReadableArray and crashed with
-// `java.lang.String cannot be cast to com.facebook.react.bridge.ReadableArray`. This
-// restores the missing JS parse so native always receives the entry array.
+// Same root cause as transformOrigin/boxShadow: RN only parses `transform` in JS when
+// nativeCSSParsing is off (the default), and only for a STRING input - an ARRAY is
+// returned unchanged. symbiote forwarded a raw string once, which Android native cast
+// to ReadableArray and crashed (`String cannot be cast to ReadableArray`). This
+// restores the missing JS parse.
 //
-// CRITICAL: the animated / sticky-header hot path produces transform ARRAYS and flows
-// through commit's processValue on every flush, so the array branch MUST return the
-// byte-identical reference (no decompose, no clone). RN's only array-path work is
-// _validateTransforms, which is __DEV__-only and THROWS via invariant; we never throw
-// into the commit path, so we run a non-throwing check that dlogs and still returns the
-// array unchanged (matching the boxShadow/transformOrigin idiom).
+// CRITICAL: the animated / sticky-header hot path produces transform ARRAYS on every
+// commit flush, so the array branch MUST return the byte-identical reference (no
+// decompose, no clone). RN's only array-path check, _validateTransforms, is __DEV__-only
+// and throws via invariant; we never throw in commit, so we dlog instead and still
+// return the array unchanged.
 import { dlog } from '../debug.js';
 // RN processTransform.js:28: matches each `name(args)` in the CSS string.
 const TRANSFORM_REGEX = /(\w+)\(([^)]+)\)/g;
@@ -78,16 +74,14 @@ function getKeyAndValueFromCSSTransform(key, args) {
             return { key, value: isNaN(Number(args)) ? args : Number(args) };
     }
 }
-// RN processTransform.js:24-50. STRING input is parsed into the entry array; ARRAY input
-// is returned UNCHANGED (RN's only array work, _validateTransforms, is __DEV__-only and
-// throws; we never throw, so we skip it and run a non-throwing dlog sanity check).
+// RN processTransform.js:24-50. String input is parsed into the entry array; array
+// input is returned unchanged (see file header for why).
 export function processTransform(transform) {
     if (transform == null) {
         return [];
     }
     if (typeof transform !== 'string') {
-        // Hot path: animated / sticky-header transforms arrive here as arrays. Return the
-        // same reference (no decompose, no clone) so the flush is a no-op.
+        // Hot path: return the same reference, no clone (see file header).
         warnInvalidTransforms(transform);
         return transform;
     }

package/build/registry.js

@@ -19,7 +19,11 @@
 // NOT in that set derives. The list never grows with the community; it grows only
 // when we add a core primitive of our own.
 import { isRecord } from './type-guards.js';
-const EMPTY = { listeners: new Set(), byRaw: new Map(), processors: new Map() };
+const EMPTY = {
+    listeners: new Set(),
+    byRaw: new Map(),
+    processors: new Map(),
+};
 // OUR own primitives: the finite set shared hand-tunes (view-config events,
 // commit COLOR_PROPS). The source is never consulted for these, so they can't
 // drift. Everything else derives. This list grows only when WE add a core
@@ -81,7 +85,11 @@ function deriveFromConfig(config, into) {
         for (const raw in directEventTypes) {
             const registrationName = directEventTypes[raw]?.registrationName;
             if (typeof registrationName === 'string') {
-                addEvent(into, { raw, listener: splitListener(registrationName), direct: true });
+                addEvent(into, {
+                    raw,
+                    listener: splitListener(registrationName),
+                    direct: true,
+                });
             }
         }
     }

package/build/report-error.d.ts

@@ -0,0 +1,5 @@
+export type IUncaughtErrorInfo = {
+    readonly origin: string;
+    readonly componentStack?: string | null;
+};
+export declare function reportUncaughtError(value: unknown, info: IUncaughtErrorInfo): void;

package/build/report-error.js

@@ -0,0 +1,63 @@
+// Hand an error to the host the way React Native itself does, for the seams where an adapter
+// catches something its framework would otherwise have surfaced on its own.
+//
+// RN routes an uncaught render error through ReactFiberErrorDialog -> ExceptionsManager
+// (Libraries/Core/ReactFiberErrorDialog.js), which is reachable only by a deep path into RN's
+// Libraries. `global.ErrorUtils` is the same surface through the documented global that
+// @react-native/js-polyfills installs before any module evaluates - RN's own
+// Libraries/vendor/core/ErrorUtils.js is nothing but `export default global.ErrorUtils`. Off a
+// native host (vitest, node smokes) the global is absent and console.error is the whole channel.
+//
+// This is NOT the dlog channel. dlog is DEBUG-gated and therefore the developer's; an error that
+// blanked the screen has to reach the app whether or not anyone turned diagnostics on.
+// Read off globalThis through Reflect rather than named as an identifier, and deliberately NOT
+// declared in an ambient block: react-native ships its own `const ErrorUtils: ErrorUtils` in
+// src/types/globals.d.ts, so a `declare global { var ErrorUtils }` here redeclares it (TS2451) for
+// every package whose tsconfig pulls in RN's types - the engine's own does not, so it typechecks
+// clean here and breaks ngc downstream. RN's declared shape also lists only the two
+// get/setGlobalHandler members, not reportError, which the polyfill does install.
+function nativeReporter() {
+    const utils = Reflect.get(globalThis, 'ErrorUtils');
+    if (typeof utils !== 'object' || utils === null)
+        return null;
+    const report = Reflect.get(utils, 'reportError');
+    if (typeof report !== 'function')
+        return null;
+    return error => {
+        Reflect.apply(report, utils, [error]);
+    };
+}
+// A throw is not required to be an Error - a string, or null, reaches here just as easily, and
+// the host's reporter wants something with a message and a stack. RN wraps the same way, via
+// SyntheticError.
+function toError(value, origin) {
+    if (value instanceof Error)
+        return value;
+    return new Error(`${origin}: ${String(value)}`);
+}
+export function reportUncaughtError(value, info) {
+    const error = toError(value, info.origin);
+    if (info.componentStack) {
+        // LogBox reads these two off the error to render the component frames; RN's own
+        // ReactFiberErrorDialog sets exactly the same pair, in a try/catch because a frozen or
+        // sealed error still deserves to be reported, just without the frames.
+        try {
+            Object.assign(error, {
+                componentStack: info.componentStack,
+                isComponentError: true,
+            });
+        }
+        catch {
+            // Reported below regardless.
+        }
+    }
+    const report = nativeReporter();
+    if (report !== null) {
+        // Exactly one channel, never both: RN routes console.error into LogBox as well, so logging
+        // here too would double-report every error. Upstream returns false from showErrorDialog for
+        // this same reason (Libraries/Core/ReactFiberErrorDialog.js:57).
+        report(error);
+        return;
+    }
+    console.error(`[symbiote] ${info.origin}:`, error);
+}

package/build/share/index.android.js

@@ -9,7 +9,7 @@
 // name, so it is only proven on a real Android host (a bridgeless resolution log there).
 import { dlog } from '../debug.js';
 import { getNativeModule } from '../native-modules/index.js';
-import { validateContent, shareActions, SHARED_ACTION, DISMISSED_ACTION } from './shared.js';
+import { validateContent, shareActions, SHARED_ACTION, DISMISSED_ACTION, } from './shared.js';
 const SHARE_MODULE = 'ShareModule';
 // ShareModule.share resolves an untyped value at the native boundary; narrow it before
 // reading `action` (no `as`).

package/build/share/index.ios.js

@@ -7,7 +7,7 @@
 import { dlog } from '../debug.js';
 import { getNativeModule } from '../native-modules/index.js';
 import { ACTION_SHEET_MANAGER, } from '../action-sheet-ios/index.js';
-import { validateContent, shareActions, SHARED_ACTION, DISMISSED_ACTION } from './shared.js';
+import { validateContent, shareActions, SHARED_ACTION, DISMISSED_ACTION, } from './shared.js';
 export const Share = {
     ...shareActions,
     // Open the iOS share sheet for `content`. Resolves with the user's action

package/build/status-bar/index.android.js

@@ -4,16 +4,15 @@
 // setColor/setTranslucent, same module name ('StatusBarManager'). Metro picks this on an
 // Android host; iOS keeps its own shape. Each adapter wraps these with its declarative component.
 //
-// History: this used to be a no-op. Driving the window flags from our bridgeless surface
-// blanked the app: a status-bar relayout triggered stopSurface, which threw "Global was
-// not installed" because RN installs global.RN$stopSurface from its own renderer, which we
-// replace. Now that render.ts installs RN$stopSurface and tears surfaces down cleanly, the
-// relayout survives and the bar updates without blanking (verified on device: show/hide +
-// light/dark text). See render.ts's installStopSurfaceGlobal.
+// Driving window flags from our bridgeless surface used to blank the app: a status-bar
+// relayout triggered stopSurface, which threw "Global was not installed" because RN's
+// own renderer installs global.RN$stopSurface and we replace that renderer. Fixed by
+// render.ts installing RN$stopSurface itself (see installStopSurfaceGlobal) - verified
+// on device: show/hide + light/dark text survive the relayout without blanking.
 import { getNativeModule } from '../native-modules/index.js';
 import { dlog } from '../debug.js';
 import { processColor } from '../platform-color/index.js';
-import { STATUS_BAR_MANAGER } from './shared.js';
+import { STATUS_BAR_MANAGER, } from './shared.js';
 // processColor returns `unknown` (its result is platform-dependent); narrow to the
 // number Fabric/native expects, like RN's invariant before setColor. A non-number
 // (null for an unparseable color, headless identity passthrough of a string) is dropped.
@@ -32,7 +31,7 @@ function applyBackgroundColor(manager, color, animated) {
 // single-arg Android setters. The adapter calls this from its declarative component's effect,
 // on mount and on every prop change.
 export function applyStatusBarProps(props) {
-    const { barStyle, hidden, animated = false, backgroundColor, translucent } = props;
+    const { barStyle, hidden, animated = false, backgroundColor, translucent, } = props;
     const manager = getNativeModule(STATUS_BAR_MANAGER);
     if (manager === null) {
         dlog('StatusBar android: StatusBarManager not resolvable — skipping');
@@ -78,6 +77,5 @@ export const statusBarImperative = {
 // constant is absent (older RN, or a fake that doesn't define getConstants). Read lazily
 // so nothing touches native at import time.
 export function statusBarCurrentHeight() {
-    return getNativeModule(STATUS_BAR_MANAGER)?.getConstants?.()
-        .HEIGHT;
+    return getNativeModule(STATUS_BAR_MANAGER)?.getConstants?.().HEIGHT;
 }

package/build/status-bar/index.ios.js

@@ -21,7 +21,7 @@ import { STATUS_BAR_MANAGER, STATIC_HIDE_TRANSITION, hideTransition, } from './s
 // (deepest/last wins); we direct-apply a single component's props, which is correct for one
 // StatusBar and a fine first cut.
 export function applyStatusBarProps(props) {
-    const { barStyle, hidden, animated = false, networkActivityIndicatorVisible } = props;
+    const { barStyle, hidden, animated = false, networkActivityIndicatorVisible, } = props;
     const manager = getNativeModule(STATUS_BAR_MANAGER);
     if (manager === null) {
         dlog('StatusBar: StatusBarManager not resolvable via __turboModuleProxy — skipping');

package/build/style-registry/index.d.ts

@@ -1,9 +1,16 @@
 import type { IViewStyle, ITextStyle } from '../styles';
 type IResolvedStyle = Partial<IViewStyle & ITextStyle>;
 export type IClassNameValue = string | IResolvedStyle | Array<string | IResolvedStyle> | undefined | null;
-export declare function registerStyles(styles: Record<string, IResolvedStyle>): void;
+export interface IStyleRule {
+    /** Class names AS AUTHORED / as renamed by the scoping pass. No normalization. */
+    readonly tokens: readonly string[];
+    readonly specificity: readonly [number, number, number];
+    /** Source order within its file; the registry adds a per-registration epoch on top. */
+    readonly order: number;
+    readonly style: IResolvedStyle;
+}
+export declare function registerRules(rules: readonly IStyleRule[]): void;
 export declare function clearGlobalStyles(): void;
 export declare function isClassNameValue(value: unknown): value is IClassNameValue;
 export declare function resolveClassName(className: IClassNameValue): IResolvedStyle;
-export declare function kebabToCamel(value: string): string;
 export {};

package/build/style-registry/index.js

@@ -1,39 +1,101 @@
 // Runtime style registry. Side-effect CSS imports (compiled by the sibling CSS-to-style
-// build package, not this module) call registerStyles() with camelCase keys; components
-// look them up via resolveClassName(). No CSS parsing here - just a Map<string, ...> lookup.
+// build package, not this module) call registerRules() with the token SET each selector
+// names; components look them up via resolveClassName(). No CSS parsing here - just an
+// inverted Map<token, rules> and a subset test.
 //
-// No Tailwind-utility detection layer: this repo's style surface has no Tailwind layer,
-// so the compound lookup below always runs for 2-4-part class strings instead of being
-// gated behind "no part looks like a utility class".
+// A rule matches when its tokens are a SUBSET of the element's class list, in any order and
+// at any length, and the matches cascade by (derived-scope, specificity, epoch, order).
+// That replaced an earlier flat Map<key, style>, where the compiler COLLAPSED a selector's
+// tokens into one camelCase name (`.a.b` -> `aB`) and the runtime guessed the split back
+// apart by permuting the class string: 60 built keys on a 4-token miss, a camelCase
+// round-trip that could not survive a scope suffix, no real cascade, and a silent cliff at
+// 5 tokens where the compound branch stopped running at all. Tokens now arrive AS AUTHORED,
+// so there is nothing left to guess.
+// The scope tail as OUR OWN compilers emit it — all three shapes, the hash being css-parser's
+// base36 hashFilePath:
+//   `card__data-v-<h>`   Vue `<style scoped>`
+//   `card__svelte-<h>`   Svelte `<style>`
+//   `card__module__<h>`  CSS Modules — BOTH a standalone `.module.css` and Vue's `<style module>`
+// (A preprocessor source — SCSS/Less/Stylus — reduces to plain CSS before any of this, so it
+// carries whichever of the three its host block uses; there is no fourth shape.)
 //
-// kebab-case authoring: a CSS selector `.section-label` always registers under the
-// camelCase key `sectionLabel` (@symbiote-native/css-parser's extractClassName), so a template
-// can write EITHER `class="sectionLabel"` OR `class="section-label"` - resolveOne below
-// falls back to the kebab->camel form on a miss, since authors don't reliably write the
-// exact camelCase key.
-// Compound lookup tries every ordering of 2-4 space-separated class parts joined by
-// '.' (e.g. "btn primary" -> "btn.primary" / "primary.btn") before falling back to a
-// per-class merge, mirroring CSS compound-selector registration (`.btn.primary { }`).
-const COMPOUND_MIN_PARTS = 2;
-const COMPOUND_MAX_PARTS = 4;
-const globalStyles = new Map();
-// Called by generated code from side-effect style imports. Last import wins on a
-// name collision, matching CSS cascade behavior.
-export function registerStyles(styles) {
-    for (const [name, style] of Object.entries(styles)) {
-        globalStyles.set(name, style);
+// Matched by SHAPE, never by "there is a `__` somewhere in the name" — a BEM class
+// (`card__title`) must never be read as a scoped `card`, which would silently merge the block's
+// styles into the element's.
+//
+// Matched as ONE TAIL UNIT anchored at the end, rather than as "split on the last `__`, then
+// shape-test what follows": the module form carries its own `__`, so a `lastIndexOf` split cuts
+// `badge__module__<h>` into base `badge__module` + scope `<h>` and the base it hands back names
+// no class. Widening the shape test alone would NOT fix that — the split POINT is wrong, not the
+// alphabet.
+//
+// Note this suffix scheme is ours, not the frameworks'. Svelte appends a SEPARATE token
+// (`class="card svelte-<h>"`) and Vue `<style scoped>` renames nothing at all (it adds a
+// `data-v-<h>` attribute). We have no DOM and no attribute matching, so a scope is expressed by
+// renaming the token; the names only borrow their vocabulary.
+const SCOPE_TAIL_PATTERN = /__((?:data-v|svelte)-[0-9a-z]+|module__[0-9a-z]+)$/;
+function splitScopedToken(token) {
+    const match = SCOPE_TAIL_PATTERN.exec(token);
+    // index 0 would mean the token is nothing BUT a scope tail, which names no class.
+    if (match === null || match.index <= 0)
+        return null;
+    return { base: token.slice(0, match.index), scope: match[1] };
+}
+// Inverted index, ONE bucket per rule rather than one per token: a rule can only match when the
+// element carries every one of its tokens, so any single token of it is a sufficient hook. The
+// alternative (indexing under all of them) surfaces the same rule once per shared token and buys
+// nothing but a dedupe pass.
+const ruleIndex = new Map();
+let ruleEpoch = 0;
+// resolveClassName runs from routeProp on every class-prop WRITE, per node, and a screen only
+// ever uses a few dozen distinct class strings — so after warm-up the whole resolution collapses
+// to one Map.get. Only the STRING branch is memoized: an object/array argument has no stable key
+// (a fresh literal every render) and would just fill the map.
+//
+// Safe to hand the SAME object out repeatedly because no caller mutates it — every consumer
+// (routeProp's commitClassStyle, and the ScrollView / VirtualizedList / FlatList / ImageBackground
+// class-to-style props in all five adapters) spreads it or drops it into a style array, and
+// flattenStyle shallow-copies.
+const resolvedCache = new Map();
+// Bounded so a screen generating unique class strings at runtime cannot grow it without limit.
+// Overflow drops everything rather than evicting one entry: the cache is a warm-up optimization,
+// not a working set, and an LRU's bookkeeping costs more than the rebuild it saves.
+const RESOLVED_CACHE_LIMIT = 512;
+// Every registration is a cascade change, so nothing resolved before it can be trusted. Clearing
+// wholesale beats versioning each entry — registration happens at import time, resolution happens
+// per commit, and only the second one is hot.
+function invalidateResolved() {
+    resolvedCache.clear();
+}
+export function registerRules(rules) {
+    invalidateResolved();
+    const epoch = ruleEpoch++;
+    for (const rule of rules) {
+        const hook = rule.tokens[0];
+        // The empty set is a subset of every element's tokens, so a token-less rule would paint
+        // everything. It names no class and can only come from a broken compile.
+        if (hook === undefined)
+            continue;
+        const bucket = ruleIndex.get(hook);
+        if (bucket === undefined) {
+            ruleIndex.set(hook, [{ rule, epoch }]);
+            continue;
+        }
+        bucket.push({ rule, epoch });
     }
 }
 // Used between tests to reset registry state.
 export function clearGlobalStyles() {
-    globalStyles.clear();
+    ruleIndex.clear();
+    ruleEpoch = 0;
+    invalidateResolved();
 }
 // A `class`/`className` prop arrives as `unknown` at the routeProp boundary (any adapter can
 // hand over anything); this narrows before resolveClassName without an `as` cast. Shared with
 // adapters/vue/src/components/scroll-view/shared.ts's identical need, rather than each keeping
 // its own copy - that file imports this one instead of redeclaring it.
 export function isClassNameValue(value) {
-    return typeof value === 'string' || (typeof value === 'object' && value !== null);
+    return (typeof value === 'string' || (typeof value === 'object' && value !== null));
 }
 export function resolveClassName(className) {
     if (!className)
@@ -46,83 +108,75 @@ export function resolveClassName(className) {
             return { ...acc, ...resolveClassName(item) };
         }, {});
     }
-    const trimmed = className.trim();
-    if (!trimmed)
-        return {};
-    const exactMatch = globalStyles.get(trimmed) ?? globalStyles.get(kebabToCamel(trimmed));
-    if (exactMatch)
-        return exactMatch;
-    const parts = trimmed.split(/\s+/).filter(Boolean);
-    if (parts.length >= COMPOUND_MIN_PARTS && parts.length <= COMPOUND_MAX_PARTS) {
-        const compound = tryCompoundLookup(parts);
-        if (compound)
-            return compound;
-    }
-    return parts.reduce((acc, cls) => {
-        return { ...acc, ...resolveOne(cls) };
-    }, {});
+    const cached = resolvedCache.get(className);
+    if (cached !== undefined)
+        return cached;
+    const resolved = resolveClassString(className);
+    if (resolvedCache.size >= RESOLVED_CACHE_LIMIT)
+        resolvedCache.clear();
+    resolvedCache.set(className, resolved);
+    return resolved;
 }
-function generateCompoundPermutations(parts) {
-    if (parts.length < COMPOUND_MIN_PARTS)
-        return [];
-    const compounds = [];
-    for (let size = COMPOUND_MIN_PARTS; size <= parts.length; size++) {
-        compounds.push(...generateKPermutations(parts, size));
-    }
-    return compounds;
-}
-function generateKPermutations(parts, size) {
-    if (size === 0)
-        return [''];
+function resolveClassString(className) {
+    const parts = className.trim().split(/\s+/).filter(Boolean);
     if (parts.length === 0)
-        return [];
-    const result = [];
-    function helper(current, remaining, depth) {
-        if (depth === size) {
-            result.push(toCompoundKey(current));
-            return;
-        }
-        for (let i = 0; i < remaining.length; i++) {
-            helper([...current, remaining[i]], remaining.slice(0, i).concat(remaining.slice(i + 1)), depth + 1);
+        return {};
+    return matchRules(parts) ?? {};
+}
+// `null` rather than `{}` for "nothing matched", so the caller can skip the empty-object churn on
+// every class-prop set that has no rules.
+function matchRules(parts) {
+    const literal = new Set(parts);
+    const tokens = elementTokens(parts);
+    let matched = null;
+    for (const token of tokens) {
+        const bucket = ruleIndex.get(token);
+        if (bucket === undefined)
+            continue;
+        for (const indexed of bucket) {
+            if (!indexed.rule.tokens.every(needed => tokens.has(needed)))
+                continue;
+            matched ??= [];
+            matched.push({
+                indexed,
+                derivedTokens: indexed.rule.tokens.filter(token => !literal.has(token))
+                    .length,
+            });
         }
     }
-    helper([], parts, 0);
-    return result;
-}
-// Compound permutations join as camelCase ("btn primary" -> "btnPrimary") because this
-// repo's CSS-to-style compiler emits plain camelCase keys for every class, single or
-// compound, so "btn primary" must resolve against a registered "btnPrimary".
-function toCompoundKey(parts) {
-    return parts.reduce((key, part, index) => (index === 0 ? part : key + capitalize(part)), '');
-}
-function capitalize(value) {
-    return value.length === 0 ? value : value[0].toUpperCase() + value.slice(1);
-}
-// Duplicated from @symbiote-native/css-parser's identical helper rather than imported: css-parser
-// pulls in postcss and is build-time only (never shipped in the app bundle), and this registry
-// is the opposite - pure runtime, in every app bundle - so importing it here would leak a
-// build-time dependency into the shipped app. The conversion itself is two lines; keeping both
-// copies in sync is a smaller cost than the alternative.
-//
-// Exported (not just local to this file) because ./scope.ts's Vue `<style scoped>` name
-// rewriter needs the same kebab->camel normalization and is a different responsibility living
-// in a sibling module - see that file's own doc comment for why it's split out of this one.
-export function kebabToCamel(value) {
-    return value.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
-}
-function tryCompoundLookup(parts) {
-    if (parts.length < COMPOUND_MIN_PARTS)
+    if (matched === null)
         return null;
-    for (const compound of generateCompoundPermutations(parts)) {
-        const style = globalStyles.get(compound);
-        if (style)
-            return style;
+    matched.sort(byCascadeOrder);
+    return matched.reduce((acc, match) => ({ ...acc, ...match.indexed.rule.style }), {});
+}
+// A scoped token contributes its BASE as well: the scope is expressed by RENAMING the token
+// rather than adding a second one, so a global `.card` in App.css only survives a component
+// defining its own `.card` if the base is put back into the set here. On the web the element
+// would carry both names and no such step would exist.
+function elementTokens(parts) {
+    const tokens = new Set();
+    for (const part of parts) {
+        tokens.add(part);
+        const split = splitScopedToken(part);
+        if (split !== null)
+            tokens.add(split.base);
     }
-    return null;
+    return tokens;
 }
-function resolveOne(name) {
-    const trimmed = name.trim();
-    if (!trimmed)
-        return {};
-    return globalStyles.get(trimmed) ?? globalStyles.get(kebabToCamel(trimmed)) ?? {};
+// Ascending, because the caller merges left to right: the winner has to be spread LAST. Ties
+// break the way the cascade does — later import first, then later line in the file.
+function byCascadeOrder(left, right) {
+    if (left.derivedTokens !== right.derivedTokens) {
+        return right.derivedTokens - left.derivedTokens;
+    }
+    const leftRule = left.indexed.rule;
+    const rightRule = right.indexed.rule;
+    for (let index = 0; index < leftRule.specificity.length; index++) {
+        const diff = leftRule.specificity[index] - rightRule.specificity[index];
+        if (diff !== 0)
+            return diff;
+    }
+    return left.indexed.epoch === right.indexed.epoch
+        ? leftRule.order - rightRule.order
+        : left.indexed.epoch - right.indexed.epoch;
 }

package/build/style-registry/scope.d.ts

@@ -1,3 +1,17 @@
 export type IClassToggleMap = Record<string, boolean | undefined>;
 export type IScopableClassValue = string | IClassToggleMap | Array<string | IClassToggleMap> | undefined | null;
-export declare function scopeClassName(value: IScopableClassValue, localNames: ReadonlySet<string>, scopeId: string): IScopableClassValue;
+export type IClassNameRenames = Readonly<Record<string, string>>;
+/**
+ * Rewrites every class token the style compiler renamed, leaving the rest alone.
+ *
+ * The names come from the compiler's own rename table, emitted verbatim, rather than being
+ * RECOMPUTED here as `token + '__' + scopeId`. Recomputing made the runtime a second,
+ * independent implementation of "what is this class called now" beside the style compiler —
+ * they agreed by construction until a rename mechanism changed under one of them. lightningcss
+ * renames the class; this reads the result.
+ *
+ * A token absent from the table is left alone: it belongs to another file (a `:global()` escape
+ * hatch, App.css, a class handed down by a parent), and the registry resolves it under its own
+ * authored name.
+ */
+export declare function renameClassTokens(value: IScopableClassValue, renames: IClassNameRenames): IScopableClassValue;

package/build/style-registry/scope.js

@@ -1,41 +1,43 @@
-// Vue `<style scoped>` class-name rewriter. Distinct responsibility from the sibling
-// ./index.ts (the CSS class -> style registry): this module does pure NAME rewriting,
-// no registry lookup, no CSS parsing. It runs at the compiled call site of a Vue SFC's
-// scoped-style template - `adapters/vue/metro-vue-transformer.cjs` emits calls to
-// scopeClassName (imported there as `__scopeClass`) - BEFORE Vue's own normalizeClass()
-// collapses string/object/array `class` values to a final string, so it must pre-process
-// all three shapes normalizeClass understands. resolveClassName in ./index.ts still does
-// the actual style lookup, unchanged, against the rewritten (possibly suffixed) name.
-import { kebabToCamel } from './index.js';
-// Suffixes every class token that this file's scoped block locally defines with
-// `__${scopeId}`, leaving unrecognized tokens (globals, external classes) untouched.
-export function scopeClassName(value, localNames, scopeId) {
+// Class-name rewriter for scoped styles. Distinct responsibility from the sibling ./index.ts
+// (the CSS class -> style registry): this module does pure NAME rewriting, no registry lookup,
+// no CSS parsing. It runs at the compiled call site of a scoped-style template -
+// `adapters/vue/metro-vue-transformer.cjs` emits calls to renameClassTokens (imported there as
+// `__scopeClass`) - BEFORE Vue's own normalizeClass() collapses string/object/array `class`
+// values to a final string, so it must pre-process all three shapes normalizeClass understands.
+// resolveClassName in ./index.ts still does the actual style lookup, unchanged, against the
+// rewritten name.
+/**
+ * Rewrites every class token the style compiler renamed, leaving the rest alone.
+ *
+ * The names come from the compiler's own rename table, emitted verbatim, rather than being
+ * RECOMPUTED here as `token + '__' + scopeId`. Recomputing made the runtime a second,
+ * independent implementation of "what is this class called now" beside the style compiler —
+ * they agreed by construction until a rename mechanism changed under one of them. lightningcss
+ * renames the class; this reads the result.
+ *
+ * A token absent from the table is left alone: it belongs to another file (a `:global()` escape
+ * hatch, App.css, a class handed down by a parent), and the registry resolves it under its own
+ * authored name.
+ */
+export function renameClassTokens(value, renames) {
     if (value === undefined || value === null)
         return value;
     if (Array.isArray(value)) {
-        return value.map(item => scopeClassEntry(item, localNames, scopeId));
+        return value.map(item => renameClassEntry(item, renames));
     }
-    return scopeClassEntry(value, localNames, scopeId);
+    return renameClassEntry(value, renames);
 }
-// A token arrives as either the camelCase registry key (`sectionLabel`) or its kebab-case
-// authoring form (`section-label`) - normalize to camelCase FIRST, then decide scoping, so
-// `localNames` (always camelCase, built from the css-parser's registered keys) recognizes a
-// kebab-written token. The emitted (possibly suffixed) name is always the camelCase form.
-function scopeToken(token, localNames, scopeId) {
-    const camelToken = kebabToCamel(token);
-    return localNames.has(camelToken) ? `${camelToken}__${scopeId}` : camelToken;
-}
-function scopeClassEntry(value, localNames, scopeId) {
+function renameClassEntry(value, renames) {
     if (typeof value === 'object') {
-        const scoped = {};
+        const renamed = {};
         for (const [name, enabled] of Object.entries(value)) {
-            scoped[scopeToken(name, localNames, scopeId)] = enabled;
+            renamed[renames[name] ?? name] = enabled;
         }
-        return scoped;
+        return renamed;
     }
     return value
         .split(/\s+/)
         .filter(Boolean)
-        .map(token => scopeToken(token, localNames, scopeId))
+        .map(token => renames[token] ?? token)
         .join(' ');
 }

package/build/style-sheet/index.js

@@ -49,8 +49,10 @@ const absoluteFill = Object.freeze({
     top: 0,
     bottom: 0,
 });
-// RN's composeStyles: falsy left → right, falsy right → left, else the pair [a, b]
-// (which flatten later collapses, later keys winning).
+// RN's composeStyles: a null/undefined side yields the other, else the pair [a, b]
+// (which flatten later collapses, later keys winning). The test is null/undefined, NOT
+// falsy - compose(0, y) returns [0, y], matching react-native's own
+// src/private/styles/composeStyles.js, which branches on `== null`.
 function compose(style1, style2) {
     if (style1 === null || style1 === undefined)
         return style2;