@symbiote-native/engine 0.4.0 → 1.0.0

package/build/process-transform/index.js

@@ -1,114 +1,32 @@
-// JS-side port of RN's processTransform (Libraries/StyleSheet/processTransform.js).
-// 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.
+// RN's own processTransform, imported rather than ported.
 //
-// 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.
+// Why it is needed at all: RN parses `transform` in JS only when nativeCSSParsing is off (the
+// default), and only for a STRING - an ARRAY comes back unchanged. Symbiote forwarded a raw
+// string once with no JS parse, and Android cast it to a ReadableArray and crashed
+// (`String cannot be cast to ReadableArray`). This restores the missing parse.
+//
+// Why the try/catch: upstream validates through `invariant`, i.e. it THROWS, and a commit path
+// must never throw - a malformed transform is the app's bug, not a frame to abort. Catching keeps
+// that guarantee while inheriting every one of upstream's ~12 checks. The hand-written port this
+// replaces implemented two of them, so an Animated.Value handed to a non-animated component
+// reached Fabric as an opaque object where RN redboxes, and `{perspective: 0}`, a matrix of the
+// wrong length and an unknown key all forwarded silently.
+//
+// The dev/release split is upstream's, not ours: `_validateTransforms` runs under `__DEV__`, so a
+// Release bundle skips it exactly as RN's does, and the array comes back BY IDENTITY - which the
+// animated / sticky-header hot path depends on, since it produces a transform array every commit.
 import { dlog } from '../debug.js';
-// RN processTransform.js:28: matches each `name(args)` in the CSS string.
-const TRANSFORM_REGEX = /(\w+)\(([^)]+)\)/g;
-// RN processTransform.js:59: splits one arg into [, number, , unit?].
-const ARG_WITH_UNITS_REGEX = /([+-]?\d+(\.\d+)?)([a-zA-Z]+|%)?/g;
-// RN processTransform.js:63: pulls every signed/decimal number out of a matrix arg list.
-const MATRIX_NUMBER_REGEX = /[+-]?\d+(\.\d+)?/g;
-// RN processTransform.js:52-139. Mirrors _getKeyAndValueFromCSSTransform: turns one
-// `key(args)` pair into the entry value native expects.
-function getKeyAndValueFromCSSTransform(key, args) {
-    switch (key) {
-        case 'matrix': {
-            // RN processTransform.js:62-63.
-            const numbers = args.match(MATRIX_NUMBER_REGEX);
-            return { key, value: numbers == null ? undefined : numbers.map(Number) };
-        }
-        case 'translate':
-        case 'translate3d': {
-            // RN processTransform.js:64-113.
-            const parsedArgs = [];
-            ARG_WITH_UNITS_REGEX.lastIndex = 0;
-            let matches;
-            while ((matches = ARG_WITH_UNITS_REGEX.exec(args))) {
-                const value = Number(matches[1]);
-                const unitOfMeasurement = matches[3];
-                if (value !== 0 && !unitOfMeasurement) {
-                    dlog(`processTransform: ${key}(${args}) length must have a unit unless 0`);
-                }
-                if (unitOfMeasurement === '%') {
-                    parsedArgs.push(`${value}%`);
-                }
-                else {
-                    parsedArgs.push(value);
-                }
-            }
-            // RN processTransform.js:109-111: a single-axis translate gets an implicit y of 0.
-            if (parsedArgs.length === 1) {
-                parsedArgs.push(0);
-            }
-            // RN normalizes translate3d down to the `translate` key.
-            return { key: 'translate', value: parsedArgs };
-        }
-        case 'translateX':
-        case 'translateY':
-        case 'perspective': {
-            // RN processTransform.js:114-134.
-            ARG_WITH_UNITS_REGEX.lastIndex = 0;
-            const argMatches = ARG_WITH_UNITS_REGEX.exec(args);
-            if (argMatches == null || argMatches.length === 0) {
-                return { key, value: undefined };
-            }
-            const value = Number(argMatches[1]);
-            const unitOfMeasurement = argMatches[3];
-            if (value !== 0 && !unitOfMeasurement) {
-                dlog(`processTransform: ${key}(${args}) must have a unit unless 0`);
-            }
-            return { key, value };
-        }
-        default:
-            // RN processTransform.js:136-137: a numeric arg (scale, rotate '10' would be NaN)
-            // becomes a number; an angle string ('6deg', '1.16rad') stays a string.
-            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 (see file header for why).
+// @ts-expect-error - untyped Flow source. Metro compiles it; vitest.config.ts strips the types.
+import processTransformUpstream from 'react-native/Libraries/StyleSheet/processTransform';
 export function processTransform(transform) {
-    if (transform == null) {
+    if (transform == null)
         return [];
+    try {
+        return processTransformUpstream(transform);
     }
-    if (typeof transform !== 'string') {
-        // Hot path: return the same reference, no clone (see file header).
-        warnInvalidTransforms(transform);
-        return transform;
-    }
-    TRANSFORM_REGEX.lastIndex = 0;
-    const transformArray = [];
-    let matches;
-    while ((matches = TRANSFORM_REGEX.exec(transform))) {
-        const { key, value } = getKeyAndValueFromCSSTransform(matches[1], matches[2]);
-        if (value !== undefined) {
-            transformArray.push({ [key]: value });
-        }
-    }
-    return transformArray;
-}
-// RN processTransform.js:141-159 (_validateTransforms) rewritten to NEVER throw: it only
-// dlogs the same conditions RN's invariant would have flagged, then returns. The commit
-// path keeps the array regardless: an invalid transform is the caller's bug, not ours to
-// abort a frame over.
-function warnInvalidTransforms(transform) {
-    for (const transformation of transform) {
-        const keys = Object.keys(transformation);
-        if (keys.length !== 1) {
-            dlog(`processTransform: each transform object must have exactly one key, got ${keys.length}`);
-            continue;
-        }
-        if (keys[0] === 'matrix' && transform.length > 1) {
-            dlog('processTransform: a matrix transform must be the only transform in the list');
-        }
+    catch (error) {
+        // Upstream's message names the offending key and value, so it is worth more than ours was.
+        dlog(`processTransform: dropped an invalid transform - ${error instanceof Error ? error.message : String(error)}`);
+        return [];
     }
 }

package/build/process-transform-origin/index.d.ts

@@ -1,3 +1,3 @@
 type ITransformOriginValue = string | number;
-export declare function processTransformOrigin(transformOrigin: Array<ITransformOriginValue> | string | undefined): Array<ITransformOriginValue>;
+export declare function processTransformOrigin(transformOrigin: Array<ITransformOriginValue> | string | undefined): Array<ITransformOriginValue> | undefined;
 export {};

package/build/process-transform-origin/index.js

@@ -1,108 +1,35 @@
-// JS-side port of RN's processTransformOrigin (Libraries/StyleSheet/processTransformOrigin.js).
-// Same root cause as boxShadow/filter: ReactNativeStyleAttributes registers `transformOrigin`
-// with `nativeCSSParsing ? true : {process: processTransformOrigin}`, and enableNativeCSSParsing()
-// DEFAULTS TO FALSE, so RN's stock path runs processTransformOrigin IN JS, turning the CSS
-// string ('top left') into the [x, y, z] array native expects. symbiote forwarded the raw
-// string: iOS native tolerated it, Android native casts it to ReadableArray and crashes with
-// `java.lang.String cannot be cast to com.facebook.react.bridge.ReadableArray`. This restores
-// the missing JS parse so native always receives the [x, y, z] array.
+// RN's own processTransformOrigin, imported rather than ported.
 //
-// RN throws via invariant() on a malformed value; we instead dlog and keep the partial array
-// (matching the boxShadow/filter idiom of never throwing into the commit path).
+// Why it is needed at all: ReactNativeStyleAttributes registers `transformOrigin` with
+// `nativeCSSParsing ? true : {process: processTransformOrigin}`, and enableNativeCSSParsing()
+// DEFAULTS TO FALSE - so RN's stock path parses the CSS string ('top left') into the [x, y, z]
+// array native expects. Symbiote forwarded the raw string: iOS tolerated it, Android cast it to a
+// ReadableArray and crashed. This restores the missing parse.
+//
+// Why the try/catch: upstream rejects a malformed origin through `invariant`, i.e. it THROWS, and
+// a commit path must never throw. Which of its invariants survive a Release build is worth being
+// precise about, because this comment said "these invariants are NOT __DEV__-gated" and that is
+// only half true: `_validateTransformOrigin` IS gated (processTransformOrigin.js:115), while the
+// four invariants inside the parse loop (:42, :52, :79, :91) are not. '50% left' hits an ungated
+// one - a horizontal keyword in the y slot - so upstream does refuse it in Release, and the
+// try/catch is load-bearing there. A malformed ARRAY, by contrast, is only caught in dev.
+//
+// The hand-written port this replaces kept whatever it had parsed and returned a PARTIAL origin.
+// That is not the safer option it looks like: a partial origin is a real, wrong origin, applied
+// silently. `undefined` is the honest answer, and it is what the payload builder drops.
 import { dlog } from '../debug.js';
-// RN processTransformOrigin.js:14, pre-compiled pattern matching each keyword / length token.
-const TRANSFORM_ORIGIN_REGEX = /(top|bottom|left|right|center|\d+(?:%|px)|0)/gi;
-// RN processTransformOrigin.js:16-18.
-const INDEX_X = 0;
-const INDEX_Y = 1;
-const INDEX_Z = 2;
-// RN processTransformOrigin.js:21-120. Parses the CSS string into the [x, y, z] array,
-// or normalizes/passes through an array input unchanged.
+// @ts-expect-error - untyped Flow source. Metro compiles it; vitest.config.ts strips the types.
+import processTransformOriginUpstream from 'react-native/Libraries/StyleSheet/processTransformOrigin';
 export function processTransformOrigin(transformOrigin) {
-    if (transformOrigin == null) {
-        // RN never receives undefined here (the registry only calls the processor for a
-        // present value), but the commit path may; default to center/center/0.
-        return ['50%', '50%', 0];
-    }
-    if (typeof transformOrigin !== 'string') {
-        // Array input passes through, like RN (which only re-validates in __DEV__).
-        return transformOrigin;
+    // Absent input means an absent prop. The port answered with the CSS default here, so
+    // `transformOrigin: null` committed a real center origin - a write RN never makes.
+    if (transformOrigin == null)
+        return undefined;
+    try {
+        return processTransformOriginUpstream(transformOrigin);
     }
-    const transformOriginString = transformOrigin;
-    TRANSFORM_ORIGIN_REGEX.lastIndex = 0;
-    const transformOriginArray = ['50%', '50%', 0];
-    let index = INDEX_X;
-    let matches;
-    outer: while ((matches = TRANSFORM_ORIGIN_REGEX.exec(transformOriginString))) {
-        let nextIndex = index + 1;
-        const value = matches[0];
-        const valueLower = value.toLowerCase();
-        switch (valueLower) {
-            case 'left':
-            case 'right': {
-                // RN processTransformOrigin.js:42-46, left/right are x-only.
-                if (index !== INDEX_X) {
-                    dlog(`processTransformOrigin reject: "${value}" can only be used for x-position`);
-                    return transformOriginArray;
-                }
-                transformOriginArray[INDEX_X] = valueLower === 'left' ? 0 : '100%';
-                break;
-            }
-            case 'top':
-            case 'bottom': {
-                // RN processTransformOrigin.js:52-56, top/bottom are not valid for z.
-                if (index === INDEX_Z) {
-                    dlog(`processTransformOrigin reject: "${value}" can only be used for y-position`);
-                    return transformOriginArray;
-                }
-                transformOriginArray[INDEX_Y] = valueLower === 'top' ? 0 : '100%';
-                // RN processTransformOrigin.js:59-86, handle [[ center | left | right ] &&
-                // [ center | top | bottom ]] <length>?  When y came first, the next token is x.
-                if (index === INDEX_X) {
-                    const horizontal = TRANSFORM_ORIGIN_REGEX.exec(transformOriginString);
-                    if (horizontal == null) {
-                        break outer;
-                    }
-                    switch (horizontal[0].toLowerCase()) {
-                        case 'left':
-                            transformOriginArray[INDEX_X] = 0;
-                            break;
-                        case 'right':
-                            transformOriginArray[INDEX_X] = '100%';
-                            break;
-                        case 'center':
-                            transformOriginArray[INDEX_X] = '50%';
-                            break;
-                        default:
-                            dlog(`processTransformOrigin reject: could not parse "${transformOriginString}"`);
-                            return transformOriginArray;
-                    }
-                    nextIndex = INDEX_Z;
-                }
-                break;
-            }
-            case 'center': {
-                // RN processTransformOrigin.js:91-95, center is invalid for z.
-                if (index === INDEX_Z) {
-                    dlog(`processTransformOrigin reject: "${value}" cannot be used for z-position`);
-                    return transformOriginArray;
-                }
-                transformOriginArray[index] = '50%';
-                break;
-            }
-            default: {
-                // RN processTransformOrigin.js:99-105, a percentage stays a string, a length
-                // drops its `px` and becomes a number.
-                if (value.endsWith('%')) {
-                    transformOriginArray[index] = value;
-                }
-                else {
-                    transformOriginArray[index] = parseFloat(value);
-                }
-                break;
-            }
-        }
-        index = nextIndex;
+    catch (error) {
+        dlog(`processTransformOrigin: dropped an invalid origin - ${error instanceof Error ? error.message : String(error)}`);
+        return undefined;
     }
-    return transformOriginArray;
 }

package/build/registry.d.ts

@@ -1,3 +1,4 @@
+import type { IPayloadFold } from './host-behavior';
 export type IPropProcessor = (value: unknown) => unknown;
 export interface INativeEventBinding {
     raw: string;
@@ -28,4 +29,39 @@ export declare function registerComponent(name: string, registration?: IComponen
 export declare function isRegisteredEvent(component: string, listener: string): boolean;
 export declare function registeredNativeEvent(component: string, raw: string): INativeEventBinding | undefined;
 export declare function registeredProcessor(component: string, key: string): IPropProcessor | undefined;
+/**
+ * A component's ViewConfig processors, as a payload fold — or undefined when it has none.
+ *
+ * WHY A FOLD AND NOT A LOOKUP AT PAYLOAD-BUILD TIME. The payload is built in C++ on a device
+ * (`core/engine/cpp/SymbioteFabricProps.cpp`) and only in JS headless, and this registry cannot
+ * cross that boundary: it is populated lazily from an INJECTED `ReactNativeViewConfigRegistry`
+ * lookup, holding JS closures. `payloadFold` is the one seam that already runs in JS on both paths
+ * — the C++ probes it once per node and calls back — so putting the processors there is what makes
+ * a third-party view behave the same on a device as it does in a test.
+ *
+ * The alternative was a list of prop NAMES in C++, and that is what this replaces. It cost a day:
+ * `@symbiote-native/slider` declares `minimumTrackTintColor` / `maximumTrackTintColor` in its own
+ * ViewConfig, neither name was in the C++ list, both reached Fabric as CSS strings, and iOS answers
+ * a string colour with `clearColor()`. The slider dragged and reported values correctly with no
+ * track drawn at all. Any list of names is a list somebody has to extend for a component we have
+ * never seen — which would have meant editing C++ to add a native view, and that is exactly the
+ * coupling `<native_core_is_untouched>` exists to prevent.
+ *
+ * Resolved ONCE per component and cached, because `createElement` asks per node. A built-in
+ * short-circuits inside `resolve` before any of this.
+ */
+/**
+ * The prop names a component's OWN ViewConfig claims a processor for — i.e. exactly the keys
+ * `configPayloadFold` has already converted by the time the payload builder's own passes run.
+ *
+ * It exists so "a colour is converted exactly once" can be a stated rule rather than a lucky one.
+ * The overlap is real: `thumbTintColor` is claimed by @symbiote-native/slider's config AND by the
+ * engine's built-in COLOR_PROPS, and for a while nothing broke only because a processed colour came
+ * back as a NUMBER and the engine skipped numbers. That guard died when a numeric colour became
+ * processable in its own right — an author writing `color: 0xff0000ff` means rrggbbaa and owes the
+ * same rotation a string owes — and the second conversion then turned an already-correct int into
+ * a different colour.
+ */
+export declare function configProcessedKeys(component: string): ReadonlySet<string> | undefined;
+export declare function configPayloadFold(component: string): IPayloadFold | undefined;
 export {};

package/build/registry.js

@@ -48,11 +48,17 @@ const BUILTIN_COMPONENTS = new Set([
 // Manual overrides per component (usually none): the escape hatch.
 const overrides = new Map();
 const resolvedCache = new Map();
+// `configPayloadFold`'s answer, boxed so a component with no processors caches its `undefined`
+// instead of re-resolving on every `createElement`.
+const foldCache = new Map();
+// Same boxing, for the key set `configProcessedKeys` answers.
+const keysCache = new Map();
 let viewConfigSource;
 // Wired once by the adapter on a real host: `name => ReactNativeViewConfigRegistry.get(name)`.
 export function setNativeViewConfigSource(source) {
     viewConfigSource = source;
     resolvedCache.clear();
+    foldCache.clear();
 }
 // Escape hatch: override a derived config, or supply one for a view with no codegen
 // ViewConfig. NOT needed on the common path; views derive from the source.
@@ -63,6 +69,7 @@ export function registerComponent(name, registration = {}) {
     else
         list.push(registration);
     resolvedCache.delete(name);
+    foldCache.delete(name);
 }
 // onChange -> change (mirrors node.ts listenerName; the split of the handler prop).
 function splitListener(handlerProp) {
@@ -149,3 +156,69 @@ export function registeredNativeEvent(component, raw) {
 export function registeredProcessor(component, key) {
     return resolve(component).processors.get(key);
 }
+/**
+ * A component's ViewConfig processors, as a payload fold — or undefined when it has none.
+ *
+ * WHY A FOLD AND NOT A LOOKUP AT PAYLOAD-BUILD TIME. The payload is built in C++ on a device
+ * (`core/engine/cpp/SymbioteFabricProps.cpp`) and only in JS headless, and this registry cannot
+ * cross that boundary: it is populated lazily from an INJECTED `ReactNativeViewConfigRegistry`
+ * lookup, holding JS closures. `payloadFold` is the one seam that already runs in JS on both paths
+ * — the C++ probes it once per node and calls back — so putting the processors there is what makes
+ * a third-party view behave the same on a device as it does in a test.
+ *
+ * The alternative was a list of prop NAMES in C++, and that is what this replaces. It cost a day:
+ * `@symbiote-native/slider` declares `minimumTrackTintColor` / `maximumTrackTintColor` in its own
+ * ViewConfig, neither name was in the C++ list, both reached Fabric as CSS strings, and iOS answers
+ * a string colour with `clearColor()`. The slider dragged and reported values correctly with no
+ * track drawn at all. Any list of names is a list somebody has to extend for a component we have
+ * never seen — which would have meant editing C++ to add a native view, and that is exactly the
+ * coupling `<native_core_is_untouched>` exists to prevent.
+ *
+ * Resolved ONCE per component and cached, because `createElement` asks per node. A built-in
+ * short-circuits inside `resolve` before any of this.
+ */
+/**
+ * The prop names a component's OWN ViewConfig claims a processor for — i.e. exactly the keys
+ * `configPayloadFold` has already converted by the time the payload builder's own passes run.
+ *
+ * It exists so "a colour is converted exactly once" can be a stated rule rather than a lucky one.
+ * The overlap is real: `thumbTintColor` is claimed by @symbiote-native/slider's config AND by the
+ * engine's built-in COLOR_PROPS, and for a while nothing broke only because a processed colour came
+ * back as a NUMBER and the engine skipped numbers. That guard died when a numeric colour became
+ * processable in its own right — an author writing `color: 0xff0000ff` means rrggbbaa and owes the
+ * same rotation a string owes — and the second conversion then turned an already-correct int into
+ * a different colour.
+ */
+export function configProcessedKeys(component) {
+    const cached = keysCache.get(component);
+    if (cached !== undefined)
+        return cached.keys;
+    const { processors } = resolve(component);
+    const keys = processors.size === 0 ? undefined : new Set(processors.keys());
+    keysCache.set(component, { keys });
+    return keys;
+}
+export function configPayloadFold(component) {
+    const cached = foldCache.get(component);
+    if (cached !== undefined)
+        return cached.fold;
+    const { processors } = resolve(component);
+    const fold = processors.size === 0
+        ? undefined
+        : props => {
+            // Copied only when a processor actually claims a key present in the bag: the fold
+            // contract forbids mutating `node.props`, and a component whose config declares
+            // processors for props this node never sets must still hand its input back by identity.
+            let out;
+            for (const [key, process] of processors) {
+                if (!(key in props))
+                    continue;
+                const claimed = out ?? { ...props };
+                claimed[key] = process(props[key]);
+                out = claimed;
+            }
+            return out ?? props;
+        };
+    foldCache.set(component, { fold });
+    return fold;
+}

package/build/sound-manager/index.d.ts

@@ -0,0 +1,3 @@
+export declare const SoundManager: {
+    playTouchSound(): void;
+};

package/build/sound-manager/index.js

@@ -0,0 +1,36 @@
+// SoundManager: plays the Android system touch-sound feedback. Mirrors RN's
+// Libraries/Components/Sound/SoundManager.js — a single method, `playTouchSound`, wrapping the
+// TurboModule the same way (`NativeSoundManager` resolves via `TurboModuleRegistry.get`, not
+// `getEnforcing`, so a missing module degrades to a no-op there too).
+//
+// The native contract, from `src/private/specs_DEPRECATED/modules/NativeSoundManager.js`:
+//   playTouchSound(): void
+//
+// Called from `core/components/src/state/pressable.ts`'s press machine, on Android, right before
+// `onPress` fires, gated by `android_disableSound !== true` — Pressability.js:754-756. Not a Fabric
+// prop: no ViewConfig declares `android_disableSound`, it only ever gates this JS-side call.
+import { dlog } from '../debug.js';
+import { getNativeModule } from '../native-modules/index.js';
+const SOUND_MODULE = 'SoundManager';
+// Lazily resolved so importing this module has no native side effect.
+let soundModule;
+function getModule() {
+    if (soundModule === undefined) {
+        soundModule = getNativeModule(SOUND_MODULE);
+        dlog(`SoundManager: SoundManager module ${soundModule ? 'resolved' : 'NOT resolved (null)'}`);
+    }
+    return soundModule;
+}
+export const SoundManager = {
+    // Degrades to a no-op (logged) when the module is absent — never throws — matching every other
+    // optional native module in this layer.
+    playTouchSound() {
+        const module = getModule();
+        if (module === null) {
+            dlog('SoundManager.playTouchSound -> SoundManager native module unavailable, no-op');
+            return;
+        }
+        dlog('SoundManager.playTouchSound');
+        module.playTouchSound();
+    },
+};

package/build/structured-style.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A style value with its structured keys resolved — the same value by identity when there was
+ * nothing to resolve, which is nearly always.
+ *
+ * Accepts what a style slot can hold: one object, or a (nested) array of them. An array is not
+ * memoized — `pushClassStyle` mints a fresh one on every publish, so a cache keyed on it could
+ * never hit; its ENTRIES carry the memo instead, and the original array comes back untouched when
+ * none of them moved.
+ */
+export declare function resolveStructuredStyle(style: unknown): unknown;