@symbiote-native/engine 0.1.5 → 0.1.6

package/build/animated/index.d.ts

@@ -17,4 +17,4 @@ export { nativeAnimated, isNativeAnimatedAvailable, type INativeNodeConfig, type
 export { AnimatedProps } from './props';
 export { AnimatedStyle, AnimatedTransform } from './style';
 export { AnimatedMock } from './mock';
-export { reduceProps, isAnimatedNode, readPassthroughStyle, resolveHostNode, } from './animated-component-shared';
+export { reduceProps, isAnimatedNode, readPassthroughStyle, resolveHostNode } from './shared';

package/build/animated/index.js

@@ -25,4 +25,4 @@ export { AnimatedProps } from './props.js';
 export { AnimatedStyle, AnimatedTransform } from './style.js';
 export { AnimatedMock } from './mock.js';
 // Framework-agnostic createAnimatedComponent helpers. Both adapters import them.
-export { reduceProps, isAnimatedNode, readPassthroughStyle, resolveHostNode, } from './animated-component-shared.js';
+export { reduceProps, isAnimatedNode, readPassthroughStyle, resolveHostNode } from './shared.js';

package/build/commit.js

@@ -13,7 +13,7 @@
 // references to specific child handles. That bubble is inherent to a persistent
 // tree and is exactly what React's own Fabric renderer does.
 import { getSlot, } from './fabric.js';
-import { createElement, isAnchor, VIRTUAL_TEXT_COMPONENT } from './node.js';
+import { createElement, debugNodeId, isAnchor, VIRTUAL_TEXT_COMPONENT, } from './node.js';
 import { dlog, isDebug } from './debug.js';
 import { flattenStyle } from './style/index.js';
 import { nextTag } from './tags.js';
@@ -23,7 +23,7 @@ import { isRecord } from './type-guards.js';
 // processColor/setColorProcessor now live in ./platform-color (the stable color-processing
 // leaf every color-touching module imports from); re-exported here so nothing outside this
 // module needs to change its import path.
-export { processColor, setColorProcessor } from './platform-color.js';
+export { processColor, setColorProcessor } from './platform-color/index.js';
 // Per-commit work counters, surfaced via dlog so a device run can prove the
 // engine is incremental (created=0 with clones after the first mount).
 const stats = { created: 0, cloneProps: 0, cloneChildren: 0, reused: 0 };
@@ -210,6 +210,13 @@ function reconcile(slot, node, rootTag, hasTextAncestor, renderableParent, force
             slot.appendChild(handle, reconcile(slot, child, rootTag, childInText, node, true).handle);
         }
         logScrollChildren(node, viewName, tag);
+        // Investigation instrumentation (search-bar-ref "node not committed" bug): scoped to RNS* so
+        // it can be directly compared against the ref-attach log in stack.ts and the dispatch-miss
+        // log below — same debugNodeId on both sides proves/disproves an identity mismatch. Kept
+        // behind DEBUG per <keep_logs_gate_behind_DEBUG>, never removed.
+        if (viewName.startsWith('RNS')) {
+            dlog(`mirror.set (create) node=${debugNodeId(node)} tag=${tag} view=${viewName}`);
+        }
         mirror.set(node, {
             handle,
             tag,
@@ -259,6 +266,11 @@ function reconcile(slot, node, rootTag, hasTextAncestor, renderableParent, force
         guardSerializable(propsDiff, viewName, committed.tag);
         handle = slot.cloneNodeWithNewProps(committed.handle, propsDiff);
     }
+    // Investigation instrumentation (search-bar-ref "node not committed" bug): see the create-path
+    // dlog above. Kept behind DEBUG per <keep_logs_gate_behind_DEBUG>, never removed.
+    if (viewName.startsWith('RNS')) {
+        dlog(`mirror.set (update) node=${debugNodeId(node)} tag=${committed.tag} view=${viewName}`);
+    }
     // The clone keeps the node's family, so its reactTag is unchanged; carry it.
     mirror.set(node, {
         handle,
@@ -428,10 +440,12 @@ export function getNativeNode(node) {
 export function dispatchViewCommand(node, commandName, args) {
     const record = mirror.get(node);
     if (record === undefined) {
-        dlog(`dispatchViewCommand "${commandName}" skipped: node not committed`);
+        // node=... compares directly against the mirror.set logs above (same debugNodeId scheme) to
+        // prove/disprove a node-identity mismatch — see the search-bar-ref investigation note there.
+        dlog(`dispatchViewCommand "${commandName}" skipped: node not committed (node=${debugNodeId(node)} component=${node.component})`);
         return;
     }
-    dlog(`dispatchViewCommand "${commandName}"`);
+    dlog(`dispatchViewCommand "${commandName}" (node=${debugNodeId(node)})`);
     getSlot().dispatchCommand(record.handle, commandName, args);
 }
 // Emit an accessibility event (focus/click/viewHoverEnter/windowStateChange) at a node's

package/build/fabric-props.js

@@ -7,7 +7,7 @@
 import { RAW_TEXT_COMPONENT } from './node.js';
 import { flattenStyle } from './style/index.js';
 import { registeredProcessor } from './registry.js';
-import { isProcessableColor, processColor } from './platform-color.js';
+import { isProcessableColor, processColor } from './platform-color/index.js';
 import { processBoxShadow } from './process-box-shadow/index.js';
 import { processFilter } from './process-filter.js';
 import { processTransformOrigin } from './process-transform-origin/index.js';

package/build/image-loader/index.d.ts

@@ -0,0 +1,24 @@
+import { type IImageSourceProp } from '../image-source-resolver';
+export type IImageSize = {
+    width: number;
+    height: number;
+};
+export type IImageCacheStatus = 'memory' | 'disk' | 'disk/memory';
+type ISizeSuccess = (width: number, height: number) => void;
+type ISizeFailure = (error: unknown) => void;
+declare function getSize(uri: string, success?: ISizeSuccess, failure?: ISizeFailure): Promise<IImageSize>;
+declare function getSizeWithHeaders(uri: string, headers: Record<string, string>, success?: ISizeSuccess, failure?: ISizeFailure): Promise<IImageSize>;
+declare function prefetch(uri: string, callback?: (requestId: number) => void): Promise<boolean>;
+declare function abortPrefetch(requestId: number): void;
+declare function queryCache(uris: string[]): Promise<Record<string, IImageCacheStatus>>;
+declare function resolveAssetSource(source: IImageSourceProp): unknown;
+export type IImageStatics = {
+    getSize: typeof getSize;
+    getSizeWithHeaders: typeof getSizeWithHeaders;
+    prefetch: typeof prefetch;
+    abortPrefetch: typeof abortPrefetch;
+    queryCache: typeof queryCache;
+    resolveAssetSource: typeof resolveAssetSource;
+};
+export declare const imageStatics: IImageStatics;
+export {};

package/build/image-loader/index.js

@@ -0,0 +1,175 @@
+// Image static methods (RN's Image.getSize / prefetch / queryCache / etc).
+//
+// These mirror RN's iOS Image statics (Libraries/Image/Image.ios.js), which delegate to the
+// `ImageLoader` native (Turbo)Module declared in NativeImageLoaderIOS.js. The Android spec
+// (NativeImageLoaderAndroid.js) registers under the SAME module name ('ImageLoader'), so this
+// stays a flat, non-platform-split module - only the Android prefetch call signature differs (a
+// second `requestId` arg), branched on Platform.OS below, not on module name. NOTE the asymmetry
+// in the iOS spec: `getSize` resolves a `[width, height]` ARRAY, while `getSizeWithHeaders`
+// resolves a `{width, height}` OBJECT, both are guarded below before reading. The native result
+// crosses the I/O boundary as `unknown`; we never cast it, we narrow its shape.
+//
+// This is a stateful, native-bridge-touching imperative module (module-level ImageLoader cache +
+// prefetch requestId counter) with no view of its own - it belongs in @symbiote-native/engine
+// alongside Alert/Share, not in a view/render-*.ts file (whose contract is zero state / zero
+// native bridge).
+import { dlog } from '../debug.js';
+import { resolveImageSource } from '../image-source-resolver.js';
+import { getNativeModule } from '../native-modules.js';
+import { Platform } from '../platform';
+import { isNumber } from '../type-guards.js';
+// The iOS native module name RN registers this under (NativeImageLoaderIOS.js resolves
+// `TurboModuleRegistry.getEnforcing<Spec>('ImageLoader')`). A module name like this is only
+// provable on a real host - a headless fake answers to any name - so this iOS name is
+// device-verify-pending.
+const IMAGE_LOADER_MODULE = 'ImageLoader';
+let imageLoaderModule;
+function getImageLoader() {
+    if (imageLoaderModule === undefined) {
+        imageLoaderModule = getNativeModule(IMAGE_LOADER_MODULE);
+        dlog(`Image: ImageLoader module ${imageLoaderModule ? 'resolved' : 'NOT resolved (null)'}`);
+    }
+    return imageLoaderModule;
+}
+// Narrow native's getSize result. The spec resolves a `[width, height]` array, but tolerate a
+// `{width, height}` object too (getSizeWithHeaders uses that shape).
+function toImageSize(result) {
+    if (Array.isArray(result) && isNumber(result[0]) && isNumber(result[1])) {
+        return { width: result[0], height: result[1] };
+    }
+    if (typeof result === 'object' && result !== null) {
+        const width = Reflect.get(result, 'width');
+        const height = Reflect.get(result, 'height');
+        if (isNumber(width) && isNumber(height))
+            return { width, height };
+    }
+    throw new Error(`Image: unexpected size result from native: ${JSON.stringify(result)}`);
+}
+function requireLoader(method) {
+    const loader = getImageLoader();
+    if (loader === null) {
+        throw new Error(`Image.${method}: ImageLoader native module is not available ` +
+            '(running headless or not linked on this host).');
+    }
+    return loader;
+}
+// Resolve image dimensions, optionally via success/failure callbacks. Always returns the Promise
+// too (RN returns void when a callback is passed, but a promise-and-callback shape is friendlier
+// and a strict superset).
+function getSize(uri, success, failure) {
+    const promise = Promise.resolve()
+        .then(() => requireLoader('getSize').getSize(uri))
+        .then(toImageSize);
+    if (typeof success === 'function') {
+        promise
+            .then(size => success(size.width, size.height))
+            .catch((error) => {
+            if (typeof failure === 'function')
+                failure(error);
+            else
+                dlog(`Image.getSize failed for ${uri}: ${String(error)}`);
+        });
+    }
+    return promise;
+}
+function getSizeWithHeaders(uri, headers, success, failure) {
+    const promise = Promise.resolve()
+        .then(() => requireLoader('getSizeWithHeaders').getSizeWithHeaders(uri, headers))
+        .then(toImageSize);
+    if (typeof success === 'function') {
+        promise
+            .then(size => success(size.width, size.height))
+            .catch((error) => {
+            if (typeof failure === 'function')
+                failure(error);
+            else
+                dlog(`Image.getSizeWithHeaders failed for ${uri}: ${String(error)}`);
+        });
+    }
+    return promise;
+}
+// Android keys an in-flight prefetch by a monotonic requestId (so abortRequest can cancel it);
+// RN's Image.android.js generates the same way. iOS ignores the arg.
+let prefetchRequestId = 0;
+// Download a remote image into the disk cache. Resolves to whether it succeeded. `callback`
+// receives the requestId (RN's Image.android.js shape) so the caller can later pass it to
+// abortPrefetch.
+async function prefetch(uri, callback) {
+    prefetchRequestId += 1;
+    const requestId = prefetchRequestId;
+    if (typeof callback === 'function')
+        callback(requestId);
+    const loader = requireLoader('prefetch');
+    return (Promise.resolve()
+        // Android's prefetchImage keys an abortable request on requestId; iOS takes ONLY the uri and
+        // throws on an extra arg (bridgeless TurboModule arg-count check). Match RN's per-platform call.
+        .then(() => Platform.OS === 'android'
+        ? loader.prefetchImage(uri, requestId)
+        : loader.prefetchImage(uri))
+        .then(result => result === true)
+        .catch((error) => {
+        dlog(`Image.prefetch failed for ${uri}: ${String(error)}`);
+        throw error;
+    }));
+}
+// Cancel an in-flight prefetch by the requestId prefetch handed back. Android only (mirrors
+// Image.android.js -> NativeImageLoaderAndroid.abortRequest); a missing abortRequest (iOS,
+// headless) is a no-op rather than a throw.
+function abortPrefetch(requestId) {
+    const loader = getImageLoader();
+    if (loader === null || typeof loader.abortRequest !== 'function') {
+        dlog(`Image.abortPrefetch(${requestId}): no abortRequest on this host, ignoring`);
+        return;
+    }
+    loader.abortRequest(requestId);
+}
+// Narrow native's queryCache result: an object mapping each known uri to its cache status.
+// Unknown statuses are dropped rather than trusted blindly.
+const CACHE_STATUS = {
+    memory: 'memory',
+    disk: 'disk',
+    'disk/memory': 'disk/memory',
+};
+function toCacheRecord(result) {
+    const record = {};
+    if (typeof result !== 'object' || result === null)
+        return record;
+    for (const key of Object.keys(result)) {
+        const value = Reflect.get(result, key);
+        if (typeof value === 'string' && Object.hasOwn(CACHE_STATUS, value)) {
+            record[key] = CACHE_STATUS[value];
+        }
+    }
+    return record;
+}
+async function queryCache(uris) {
+    return Promise.resolve()
+        .then(() => {
+        const loader = requireLoader('queryCache');
+        // The native queryCache never rejects (RCTImageLoader resolves getImageCacheStatus), so a
+        // rejection here is a JS/native boundary fault: log whether the method is even callable and
+        // the arg shape, to tell "not a function" (interop gap) from a marshalling reject.
+        dlog(`Image.queryCache: typeof loader.queryCache=${typeof loader.queryCache} uris=${uris.length}`);
+        return loader.queryCache(uris);
+    })
+        .then(toCacheRecord)
+        .catch((error) => {
+        dlog(`Image.queryCache failed: ${String(error)}`);
+        throw error;
+    });
+}
+// PURE JS: run the currently-installed source resolver (the same machinery the Image component
+// uses via resolveImageSource). RN's resolveAssetSource turns a require() asset id into
+// {uri, scale, ...}; the app injects the real one with setImageSourceResolver, and this exposes
+// its output to callers directly.
+function resolveAssetSource(source) {
+    return resolveImageSource(source);
+}
+export const imageStatics = {
+    getSize,
+    getSizeWithHeaders,
+    prefetch,
+    abortPrefetch,
+    queryCache,
+    resolveAssetSource,
+};

package/build/image-source-resolver/index.d.ts

@@ -0,0 +1,9 @@
+export declare function setImageSourceResolver(resolve: (source: unknown) => unknown): void;
+export declare function resolveImageSource(source: unknown): unknown;
+export type IImageSource = {
+    uri?: string;
+    scale?: number;
+    width?: number;
+    height?: number;
+};
+export type IImageSourceProp = IImageSource | IImageSource[] | number;

package/build/image-source-resolver/index.js

@@ -0,0 +1,16 @@
+// Image source resolution seam: require('./x.png') asset ids and {uri} sources are resolved by
+// RN's own resolveAssetSource before reaching the shared render fn. The actual resolution is
+// RN-platform-specific, so it is injected here rather than imported, mirroring platform-color.ts's
+// processColor seam - this keeps @symbiote-native/components free of a react-native dependency (and
+// the headless harness working). BOTH the pure renderImage view (@symbiote-native/components) and
+// this package's own image-loader statics (resolveAssetSource) call resolveImageSource; neither
+// reaches into the mutable resolver directly.
+let sourceResolver = source => source;
+export function setImageSourceResolver(resolve) {
+    sourceResolver = resolve;
+}
+// Public mirror of RN's Image.resolveAssetSource: run a source through the injected resolver.
+// Headless (no resolver wired) it is the identity, so smokes see the input unchanged.
+export function resolveImageSource(source) {
+    return sourceResolver(source);
+}

package/build/index.d.ts

@@ -1,4 +1,4 @@
-export { createElement, createRawText, createAnchor, isAnchor, appendChild, insertBefore, removeChild, setProp, setEventListener, routeProp, getExplicitStyle, setText, isSymbioteNode, isSymbioteEvent, RAW_TEXT_COMPONENT, } from './node';
+export { createElement, createRawText, createAnchor, isAnchor, appendChild, insertBefore, removeChild, setProp, setEventListener, routeProp, getExplicitStyle, setText, isSymbioteNode, isSymbioteEvent, RAW_TEXT_COMPONENT, debugNodeId, } from './node';
 export { isEventFor } from './view-config';
 export { registerComponent, setNativeViewConfigSource } from './registry';
 export { isRecord } from './type-guards';

package/build/index.js

@@ -2,7 +2,7 @@
 // Every framework adapter drives this tiny mutation API; all Fabric-specific
 // logic (tag allocation, view-name resolution, clone-on-write, event
 // normalization) lives behind it, in one place.
-export { createElement, createRawText, createAnchor, isAnchor, appendChild, insertBefore, removeChild, setProp, setEventListener, routeProp, getExplicitStyle, setText, isSymbioteNode, isSymbioteEvent, RAW_TEXT_COMPONENT, } from './node.js';
+export { createElement, createRawText, createAnchor, isAnchor, appendChild, insertBefore, removeChild, setProp, setEventListener, routeProp, getExplicitStyle, setText, isSymbioteNode, isSymbioteEvent, RAW_TEXT_COMPONENT, debugNodeId, } from './node.js';
 export { isEventFor } from './view-config.js';
 export { registerComponent, setNativeViewConfigSource } from './registry.js';
 // Real cross-package consumer: core/components' KeyboardAvoidingView render narrows
@@ -21,7 +21,7 @@ export { setColorProcessor, processColor, dispatchViewCommand, sendAccessibility
 // the Vue renderer's createElement): the imperative measure/setNativeProps/focus API. Lives
 // here because it depends only on engine internals, so all adapters inherit it identically.
 export { toPublicInstance } from './host-instance/index.js';
-export { PlatformColor, DynamicColorIOS, isOpaqueColorValue } from './platform-color.js';
+export { PlatformColor, DynamicColorIOS, isOpaqueColorValue } from './platform-color/index.js';
 // CSS-style processors (boxShadow/filter): RN parses these in JS before native because
 // enableNativeCSSParsing() defaults to false. Exported so an adapter / test can reuse them.
 export { processBoxShadow } from './process-box-shadow/index.js';

package/build/native-modules/index.d.ts

@@ -0,0 +1,18 @@
+import { NativeEventEmitter } from '../native-events';
+declare global {
+    var __turboModuleProxy: (<T>(name: string) => T | null) | undefined;
+    var nativeModuleProxy: Record<string, unknown> | undefined;
+}
+export declare function getNativeModule<T>(name: string): T | null;
+export declare function getEnforcingNativeModule<T>(name: string): T;
+export interface IDeviceEventModuleConfig<TModule> {
+    moduleName: string;
+    moduleLogPrefix: string;
+    bindModuleToEmitter?: boolean;
+    onEmitterCreated?: (emitter: NativeEventEmitter, module: TModule | null) => void;
+}
+export interface IDeviceEventModule<TModule> {
+    getModule(): TModule | null;
+    getEmitter(): NativeEventEmitter;
+}
+export declare function createDeviceEventModule<TModule>(config: IDeviceEventModuleConfig<TModule>): IDeviceEventModule<TModule>;

package/build/native-modules/index.js

@@ -0,0 +1,120 @@
+// JS -> native: reaching a native (Turbo)Module. The New Architecture installs
+// `global.__turboModuleProxy(name)`: a JSI function that returns the native
+// module registered under `name` (a HostObject whose methods call into native),
+// or null. React Native's own `TurboModuleRegistry.get` is just this call; we are
+// one more client of the same global, exactly as `getSlot` is for the view tree.
+//
+// This is first-party access, for symbiote's own modules (StatusBarManager,
+// KeyboardObserver, ...). Third-party RN packages import `TurboModuleRegistry` from
+// `'react-native'` and read the same global themselves; they do not go through
+// here.
+import { dlog } from '../debug.js';
+import { installDeviceEventHub, NativeEventEmitter, } from '../native-events.js';
+import { isRecord } from '../type-guards.js';
+// The native module value crosses from an untyped HostObject into our types here;
+// the caller vouches for its shape via T (the single trust-boundary narrowing, no
+// per-call `as`). Native modules are always non-null objects.
+function isNativeModule(value) {
+    return value !== null && value !== undefined;
+}
+// The native module `name`, typed as the caller's interface `T`, or null when no
+// module by that name is registered in the binary (or the proxy is absent, e.g.
+// running headless without a fake installed).
+export function getNativeModule(name) {
+    // Non-bridgeless: the function proxy. Call it by name.
+    const turboProxy = globalThis.__turboModuleProxy;
+    if (typeof turboProxy === 'function') {
+        const module = turboProxy(name);
+        if (module !== null && module !== undefined)
+            return module;
+    }
+    // Bridgeless: the HostObject proxy, indexed by name. Guard the access: a
+    // HostObject may throw for an unlinked name, and a throw here would propagate
+    // into a render effect and blank the tree.
+    const bridgelessProxy = globalThis.nativeModuleProxy;
+    if (bridgelessProxy !== undefined) {
+        try {
+            const module = bridgelessProxy[name];
+            if (isNativeModule(module))
+                return module;
+        }
+        catch (error) {
+            dlog(`nativeModuleProxy["${name}"] threw: ${String(error)}`);
+        }
+    }
+    dlog(`native module "${name}" not found ` +
+        `(turbo=${typeof turboProxy}, bridgeless=${typeof globalThis.nativeModuleProxy})`);
+    return null;
+}
+// Same, but throws when the module is missing, for modules a feature hard-depends
+// on (StatusBar without StatusBarManager cannot function, so failing loud beats a
+// silent no-op).
+export function getEnforcingNativeModule(name) {
+    const module = getNativeModule(name);
+    if (module === null) {
+        throw new Error(`Native module "${name}" is not registered in the binary. ` +
+            'Verify it is linked (New Architecture / bridgeless host with __turboModuleProxy installed).');
+    }
+    return module;
+}
+// ---- device-event module factory ------------------------------------------
+//
+// AccessibilityInfo (iOS + Android), AppState, Appearance, BackHandler, Keyboard,
+// and Dimensions each hand-rolled the identical plumbing: lazily resolve a native
+// module, lazily build a NativeEventEmitter bound to it, install the device-event
+// hub on first subscribe. `createLinking` (linking/shared.ts) proved this factors
+// out safely for Linking's iOS/Android split; this is the general form for every
+// other lazy-module + emitter pair in the runtime-module layer.
+//
+// Each caller's DEGRADE POLICY stays its own, via config - the factory owns only
+// the plumbing:
+//   - `bindModuleToEmitter` (default true): whether the resolved module is wired
+//     into the emitter so its addListener/removeListeners observe-counters get
+//     pinged. Dimensions' DeviceInfo module has no observe-counters, so it opts out
+//     (matching its original `new NativeEventEmitter(undefined)`).
+//   - `onEmitterCreated`: runs exactly once, right after the emitter is built -
+//     the hook for a caller's own permanent self-subscription (AppState/Appearance/
+//     BackHandler/Keyboard each keep a cache fresh or dispatch a chain this way) or
+//     one-time hydration from the module's constants (AppState's initial state,
+//     Dimensions' initial metrics - the latter also relies on this hook running
+//     `addListener` BEFORE the constants read, preserving the original
+//     subscribe-before-resolve ordering that guards against missing an update).
+// A structural check, not a cast: narrows an arbitrary resolved module down to
+// IEventEmitterModule only when it actually carries both observe-counter methods.
+// Needed because `TModule` is unconstrained (Dimensions' INativeDeviceInfo doesn't
+// extend IEventEmitterModule at all) - NativeEventEmitter itself re-checks the same
+// shape internally, so this exists to satisfy the type system, not to change
+// behavior.
+function hasEventEmitterShape(value) {
+    return (isRecord(value) &&
+        typeof value.addListener === 'function' &&
+        typeof value.removeListeners === 'function');
+}
+// Build one module's lazy-resolve + lazy-emitter pair. Each call owns its own
+// cache, so two callers (or two platform builds loaded together in one smoke) stay
+// independent - the same guarantee `createLinking` documents.
+export function createDeviceEventModule(config) {
+    let module;
+    let emitter;
+    function getModule() {
+        if (module === undefined) {
+            module = getNativeModule(config.moduleName);
+            dlog(`${config.moduleLogPrefix} ${module ? 'resolved' : 'NOT resolved (null)'}`);
+        }
+        return module;
+    }
+    function getEmitter() {
+        if (emitter === undefined) {
+            // WHY lazy: install on first subscribe so the hub exists before native
+            // emits, without a hard bootstrap-order dependency. Idempotent.
+            installDeviceEventHub();
+            const resolved = getModule();
+            const bindModule = config.bindModuleToEmitter ?? true;
+            const boundModule = bindModule && resolved !== null && hasEventEmitterShape(resolved) ? resolved : undefined;
+            emitter = new NativeEventEmitter(boundModule);
+            config.onEmitterCreated?.(emitter, resolved);
+        }
+        return emitter;
+    }
+    return { getModule, getEmitter };
+}

package/build/node.d.ts

@@ -23,6 +23,7 @@ export interface ISymbioteNode {
 export declare function createElement(component: string, isText?: boolean): ISymbioteNode;
 export declare function createRawText(text: string): ISymbioteNode;
 export declare function isSymbioteNode(value: unknown): value is ISymbioteNode;
+export declare function debugNodeId(node: ISymbioteNode): number;
 export declare const ANCHOR_COMPONENT = "#anchor";
 export declare function createAnchor(): ISymbioteNode;
 export declare function isAnchor(node: ISymbioteNode): boolean;

package/build/node.js

@@ -6,6 +6,7 @@
 // lives here in shared so no adapter re-implements it.
 import { isEventFor } from './view-config.js';
 import { isClassNameValue, resolveClassName } from './style-registry/index.js';
+import { dlog } from './debug.js';
 const BRAND = Symbol('symbiote.node');
 // A node carries the Fabric view name directly, so adding a primitive (Image,
 // ScrollView, TextInput) is just a new string from the adapter, no core change.
@@ -52,6 +53,21 @@ export function createRawText(text) {
 export function isSymbioteNode(value) {
     return typeof value === 'object' && value !== null && BRAND in value;
 }
+// Investigation instrumentation (HeaderOptionsScreen search-bar-ref "node not committed" bug):
+// a WeakMap can't be logged, so this gives every node a small human-readable id, assigned lazily
+// on first call — lets a dlog at ref-attach time and a dlog at commit/dispatch time be compared
+// directly to prove whether they're the SAME node object or two different ones. Kept behind
+// DEBUG per <keep_logs_gate_behind_DEBUG>, never removed.
+const debugIds = new WeakMap();
+let nextDebugId = 1;
+export function debugNodeId(node) {
+    let id = debugIds.get(node);
+    if (id === undefined) {
+        id = nextDebugId++;
+        debugIds.set(node, id);
+    }
+    return id;
+}
 // Vue's runtime-core needs comment/anchor nodes (fragments, v-if, v-for) to track
 // sibling order; Fabric has no such concept. An anchor is a real retained node so
 // insert/nextSibling/parentNode ordering stays correct, but the commit walk SKIPS it
@@ -166,7 +182,17 @@ export function routeProp(node, key, value) {
     }
     if (ON_PREFIX.test(key)) {
         const name = listenerName(key);
-        if (RESPONDER_EVENTS.has(name) || isEventFor(node.component, name)) {
+        const isRegisteredEvent = RESPONDER_EVENTS.has(name) || isEventFor(node.component, name);
+        // Investigation instrumentation (HeaderOptionsScreen unresponsive-buttons bug): RNS* views
+        // derive their events from react-native-screens' own codegen ViewConfig (registry.ts), so an
+        // unregistered event silently falls through to setProp below — a dead prop Fabric ignores,
+        // indistinguishable from "the button did nothing" at the UI. Scoped to RNS* to avoid noise
+        // from the rest of the app. Kept behind DEBUG per <keep_logs_gate_behind_DEBUG>, never removed.
+        if (node.component.startsWith('RNS')) {
+            dlog(`routeProp: ${node.component} "${key}" -> listener "${name}" ` +
+                `registered=${isRegisteredEvent} at t=${Date.now()}`);
+        }
+        if (isRegisteredEvent) {
             setEventListener(node, name, value);
             return;
         }

package/build/process-background-image/index.js

@@ -3,7 +3,7 @@
 // enableNativeCSSParsing(), which DEFAULTS TO FALSE, so RN's stock path parses the CSS gradient
 // string / structured array in JS and sends only the processed array to native - Fabric's C++
 // never sees the raw string. This restores that missing JS parse.
-import { isOpaqueColorValue, processColor } from '../platform-color.js';
+import { isOpaqueColorValue, processColor } from '../platform-color/index.js';
 import { dlog } from '../debug.js';
 import { isRecord } from '../type-guards.js';
 // RN processBackgroundImage.js: pre-compiled patterns.

package/build/process-box-shadow/index.js

@@ -4,7 +4,7 @@
 // processed array to native; Fabric's C++ never sees the raw string. symbiote was
 // forwarding the raw value, which native (CSS parsing off) silently ignores: shadow
 // rendered nothing. This restores the missing JS parse + per-color processColor.
-import { isOpaqueColorValue, processColor } from '../platform-color.js';
+import { isOpaqueColorValue, processColor } from '../platform-color/index.js';
 import { dlog } from '../debug.js';
 // RN processBoxShadow.js:16-19: split args only on the delimiters that are NOT inside
 // a parenthesized color like rgba(0,0,0,1).

package/build/process-filter.js

@@ -4,7 +4,7 @@
 // structured result. symbiote forwarded the raw value; the array form already worked
 // (Fabric accepts it raw, `filter:[{brightness:0.5}]` was device-verified), but the
 // CSS-string form and drop-shadow color processing were missing. This restores them.
-import { isOpaqueColorValue, processColor } from './platform-color.js';
+import { isOpaqueColorValue, processColor } from './platform-color/index.js';
 import { dlog } from './debug.js';
 import { isRecord } from './type-guards.js';
 // RN processFilter.js:19-24: pre-compiled patterns.

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

@@ -12,7 +12,7 @@
 // light/dark text). See render.ts's installStopSurfaceGlobal.
 import { getNativeModule } from '../native-modules.js';
 import { dlog } from '../debug.js';
-import { processColor } from '../platform-color.js';
+import { processColor } from '../platform-color/index.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

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

@@ -0,0 +1,3 @@
+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;

package/build/style-registry/scope/index.js

@@ -0,0 +1,41 @@
+// 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) {
+    if (value === undefined || value === null)
+        return value;
+    if (Array.isArray(value)) {
+        return value.map(item => scopeClassEntry(item, localNames, scopeId));
+    }
+    return scopeClassEntry(value, localNames, scopeId);
+}
+// 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) {
+    if (typeof value === 'object') {
+        const scoped = {};
+        for (const [name, enabled] of Object.entries(value)) {
+            scoped[scopeToken(name, localNames, scopeId)] = enabled;
+        }
+        return scoped;
+    }
+    return value
+        .split(/\s+/)
+        .filter(Boolean)
+        .map(token => scopeToken(token, localNames, scopeId))
+        .join(' ');
+}

package/build/touch-history/index.d.ts

@@ -0,0 +1,23 @@
+interface ITouchRecord {
+    touchActive: boolean;
+    startPageX: number;
+    startPageY: number;
+    startTimeStamp: number;
+    currentPageX: number;
+    currentPageY: number;
+    currentTimeStamp: number;
+    previousPageX: number;
+    previousPageY: number;
+    previousTimeStamp: number;
+}
+interface ITouchHistory {
+    touchBank: ITouchRecord[];
+    numberActiveTouches: number;
+    indexOfSingleActiveTouch: number;
+    mostRecentTimeStamp: number;
+}
+export declare const touchHistory: ITouchHistory;
+export declare function recordTouchTrack(kind: 'start' | 'move' | 'end', nativeEvent: Record<string, unknown>): void;
+export declare function resetTouchHistory(): void;
+export declare function attachTouchHistory(nativeEvent: Record<string, unknown>): void;
+export {};

package/build/touch-history/index.js

@@ -0,0 +1,150 @@
+// Per-touch position/time tracking, ported from RN's
+// react-native-renderer/.../legacy-events/ResponderTouchHistoryStore.js. PanResponder's
+// multitouch dx/vx math needs each touch's own previous->current delta (RN counts only
+// touches that moved since `_accountsForMovesUpTo`), which a grant-relative centroid of
+// ALL live touches cannot reconstruct. We maintain the bank as touches flow and ATTACH
+// `touchHistory` onto the nativeEvent reaching responder handlers, exactly how
+// ResponderEventPlugin.js sets `*.touchHistory`.
+//
+// events/index.ts consumes only this file's public surface (recordTouchTrack,
+// attachTouchHistory, resetTouchHistory, touchHistory); everything else here is a
+// private implementation detail of the bank.
+import { isRecord } from '../type-guards.js';
+// RN's bank is indexed by touch identifier and warns above 20; we never warn (headless
+// events may carry larger or absent ids), we just skip anything out of a sane range.
+const MAX_TOUCH_BANK = 20;
+const touchBank = [];
+export const touchHistory = {
+    touchBank,
+    numberActiveTouches: 0,
+    indexOfSingleActiveTouch: -1,
+    mostRecentTimeStamp: 0,
+};
+function toFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+// Pull a recordable touch out of an untyped entry. RN's getTouchIdentifier throws on
+// a null id; we skip instead, so events without touch geometry leave the bank untouched.
+function normalizeTouch(raw) {
+    if (!isRecord(raw))
+        return undefined;
+    const identifier = toFiniteNumber(raw.identifier);
+    const pageX = toFiniteNumber(raw.pageX);
+    const pageY = toFiniteNumber(raw.pageY);
+    if (identifier === undefined || pageX === undefined || pageY === undefined)
+        return undefined;
+    if (identifier < 0 || identifier > MAX_TOUCH_BANK)
+        return undefined;
+    return { identifier, pageX, pageY, timestamp: toFiniteNumber(raw.timestamp) ?? 0 };
+}
+// The changed touches for this frame (start/move/end), defensively read.
+function changedTouchesOf(nativeEvent) {
+    const raw = nativeEvent.changedTouches;
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const entry of raw) {
+        const touch = normalizeTouch(entry);
+        if (touch !== undefined)
+            out.push(touch);
+    }
+    return out;
+}
+// Count of all touches still down (RN reads nativeEvent.touches.length directly).
+function activeTouchCount(nativeEvent) {
+    const raw = nativeEvent.touches;
+    return Array.isArray(raw) ? raw.length : 0;
+}
+function recordTouchStart(touch) {
+    const record = touchBank[touch.identifier];
+    if (record) {
+        record.touchActive = true;
+        record.startPageX = touch.pageX;
+        record.startPageY = touch.pageY;
+        record.startTimeStamp = touch.timestamp;
+        record.currentPageX = touch.pageX;
+        record.currentPageY = touch.pageY;
+        record.currentTimeStamp = touch.timestamp;
+        record.previousPageX = touch.pageX;
+        record.previousPageY = touch.pageY;
+        record.previousTimeStamp = touch.timestamp;
+    }
+    else {
+        touchBank[touch.identifier] = {
+            touchActive: true,
+            startPageX: touch.pageX,
+            startPageY: touch.pageY,
+            startTimeStamp: touch.timestamp,
+            currentPageX: touch.pageX,
+            currentPageY: touch.pageY,
+            currentTimeStamp: touch.timestamp,
+            previousPageX: touch.pageX,
+            previousPageY: touch.pageY,
+            previousTimeStamp: touch.timestamp,
+        };
+    }
+    touchHistory.mostRecentTimeStamp = touch.timestamp;
+}
+// Move and end share the previous<-current shift; only `touchActive` differs.
+function shiftTouchRecord(touch, active) {
+    const record = touchBank[touch.identifier];
+    if (!record)
+        return;
+    record.touchActive = active;
+    record.previousPageX = record.currentPageX;
+    record.previousPageY = record.currentPageY;
+    record.previousTimeStamp = record.currentTimeStamp;
+    record.currentPageX = touch.pageX;
+    record.currentPageY = touch.pageY;
+    record.currentTimeStamp = touch.timestamp;
+    touchHistory.mostRecentTimeStamp = touch.timestamp;
+}
+function arrayFirst(value) {
+    return Array.isArray(value) ? value[0] : undefined;
+}
+// Maintain the bank as a touch frame flows. Mirrors RN's recordTouchTrack: moveish
+// shifts records, startish records + recomputes numberActiveTouches, endish marks the
+// record inactive + rescans for the single remaining touch. `kind` is the touch phase.
+export function recordTouchTrack(kind, nativeEvent) {
+    if (kind === 'move') {
+        for (const touch of changedTouchesOf(nativeEvent))
+            shiftTouchRecord(touch, true);
+        return;
+    }
+    if (kind === 'start') {
+        for (const touch of changedTouchesOf(nativeEvent))
+            recordTouchStart(touch);
+        touchHistory.numberActiveTouches = activeTouchCount(nativeEvent);
+        if (touchHistory.numberActiveTouches === 1) {
+            const first = normalizeTouch(arrayFirst(nativeEvent.touches));
+            touchHistory.indexOfSingleActiveTouch = first?.identifier ?? -1;
+        }
+        return;
+    }
+    for (const touch of changedTouchesOf(nativeEvent))
+        shiftTouchRecord(touch, false);
+    touchHistory.numberActiveTouches = activeTouchCount(nativeEvent);
+    if (touchHistory.numberActiveTouches === 1) {
+        for (let i = 0; i < touchBank.length; i++) {
+            const record = touchBank[i];
+            if (record !== undefined && record.touchActive) {
+                touchHistory.indexOfSingleActiveTouch = i;
+                break;
+            }
+        }
+    }
+}
+// Drop all touch state. Called on a fully-released / cancelled gesture so a stale bank
+// never leaks geometry into the next gesture's first frame.
+export function resetTouchHistory() {
+    touchBank.length = 0;
+    touchHistory.numberActiveTouches = 0;
+    touchHistory.indexOfSingleActiveTouch = -1;
+    touchHistory.mostRecentTimeStamp = 0;
+}
+// Attach the live touch history onto the event the responder handlers receive, matching
+// ResponderEventPlugin.js (`grantEvent.touchHistory = ...`, etc.). PanResponder reads
+// it for the per-touch dx/vx math; handlers that ignore it are unaffected.
+export function attachTouchHistory(nativeEvent) {
+    nativeEvent.touchHistory = touchHistory;
+}

package/build/type-guards/index.d.ts

@@ -0,0 +1,4 @@
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function isBoolean(value: unknown): value is boolean;
+export declare function isNumber(value: unknown): value is number;
+export declare function isString(value: unknown): value is string;

package/build/type-guards/index.js

@@ -0,0 +1,15 @@
+// Runtime guards to narrow `unknown` at trust boundaries (native payloads, ViewConfig
+// attributes, style values) without an `as` cast. `isRecord` excludes arrays - most
+// call sites mean "a native payload keyed by string," never a list.
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function isBoolean(value) {
+    return typeof value === 'boolean';
+}
+export function isNumber(value) {
+    return typeof value === 'number';
+}
+export function isString(value) {
+    return typeof value === 'string';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@symbiote-native/engine",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "SymbioteNative's retained shadow-tree engine — clone-on-write commit path + event normalization over React Native Fabric, shared by every framework adapter.",
   "repository": {
     "type": "git",