@symbiote-native/engine 0.1.4 → 0.1.6

package/build/index.d.ts

@@ -1,6 +1,7 @@
-export { createElement, createRawText, createAnchor, isAnchor, appendChild, insertBefore, removeChild, setProp, setEventListener, routeProp, getExplicitStyle, setText, isSymbioteNode, 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';
 export { InteractionManager, Events as InteractionManagerEvents } from './interaction-manager';
 export type { IInteractionEvent, ISimpleTask, IPromiseTask, ITask, IHandle, ICancellable, } from './interaction-manager';
 export { default as PanResponder } from './pan-responder';
@@ -27,8 +28,10 @@ export type { IParsedBackgroundImage } from './process-background-image';
 export { flattenStyle } from './style';
 export type { IViewStyle, ITextStyle, IStyleProp, IDimensionValue, IFlexAlign, IFlexJustify, ITransformProp, IBoxShadowValue, IDropShadowValue, IFilterFunction, IColorStopValue, ILinearGradientValue, IRadialGradientValue, IRadialGradientPosition, IRadialGradientShape, IRadialGradientSize, IBackgroundImageValue, IBlendMode, } from './styles';
 export { StyleSheet, computeHairlineWidth } from './style-sheet';
-export { registerStyles, resolveClassName, clearGlobalStyles, scopeClassName, isClassNameValue, } from './style-registry';
-export type { IClassNameValue, IClassToggleMap, IScopableClassValue } from './style-registry';
+export { registerStyles, resolveClassName, clearGlobalStyles, isClassNameValue, } from './style-registry';
+export type { IClassNameValue } from './style-registry';
+export { scopeClassName } from './style-registry/scope';
+export type { IClassToggleMap, IScopableClassValue } from './style-registry/scope';
 export { Platform } from './platform';
 export type { IPlatformStatic, IPlatformOSType, IPlatformSelectSpec } from './platform';
 export type { IPlatformConstantsIOS } from './platform/index.ios';
@@ -45,6 +48,10 @@ export { Alert } from './alert';
 export type { IAlertType, IAlertButtonStyle, IAlertButton, IAlertButtons, IAlertOptions, } from './alert';
 export { Share } from './share';
 export type { IShareContent, IShareOptions, IShareAction } from './share';
+export { imageStatics } from './image-loader';
+export type { IImageStatics, IImageSize, IImageCacheStatus } from './image-loader';
+export { setImageSourceResolver, resolveImageSource } from './image-source-resolver';
+export type { IImageSource, IImageSourceProp } from './image-source-resolver';
 export { ActionSheetIOS } from './action-sheet-ios';
 export type { IActionSheetIOSOptions, IShareActionSheetIOSOptions, IShareActionSheetError, } from './action-sheet-ios';
 export { Linking } from './linking';

package/build/index.js

@@ -2,9 +2,12 @@
 // 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, 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
+// raw native payloads with this same guard, so it needs it off the package root.
+export { isRecord } from './type-guards.js';
 // InteractionManager: pure JS (timers + emitter), framework-agnostic, so it lives
 // here; every adapter re-exports it.
 export { InteractionManager, Events as InteractionManagerEvents } from './interaction-manager/index.js';
@@ -18,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';
@@ -30,7 +33,8 @@ export { processFontVariant } from './process-font-variant.js';
 export { processBackgroundImage } from './process-background-image/index.js';
 export { flattenStyle } from './style/index.js';
 export { StyleSheet, computeHairlineWidth } from './style-sheet/index.js';
-export { registerStyles, resolveClassName, clearGlobalStyles, scopeClassName, isClassNameValue, } from './style-registry/index.js';
+export { registerStyles, resolveClassName, clearGlobalStyles, isClassNameValue, } from './style-registry/index.js';
+export { scopeClassName } from './style-registry/scope.js';
 export { Platform } from './platform';
 export { dlog, isDebug } from './debug.js';
 export { getNativeModule, getEnforcingNativeModule } from './native-modules.js';
@@ -43,6 +47,11 @@ export { getSlot } from './fabric.js';
 // real device or simulator, not headless (a headless fake resolves any module name).
 export { Alert } from './alert';
 export { Share } from './share';
+// Image statics (getSize/prefetch/queryCache/...): a stateful, native-bridge-touching module with
+// no view of its own, same shape as Alert/Share. The source-resolution seam it shares with
+// @symbiote-native/components' renderImage lives alongside it in image-source-resolver.
+export { imageStatics } from './image-loader.js';
+export { setImageSourceResolver, resolveImageSource } from './image-source-resolver.js';
 export { ActionSheetIOS } from './action-sheet-ios/index.js';
 export { Linking } from './linking';
 export { Vibration } from './vibration';

package/build/keyboard/index.js

@@ -3,22 +3,11 @@
 // subscribes through a NativeEventEmitter bound to the KeyboardObserver native
 // module, which RN keys its keyboard events off of. Mirrors RN's
 // Libraries/Components/Keyboard/Keyboard.js, slimmed to the parts we need.
-import { getNativeModule } from '../native-modules.js';
-import { installDeviceEventHub, NativeEventEmitter, } from '../native-events.js';
+import { createDeviceEventModule } from '../native-modules.js';
+import {} from '../native-events.js';
 import { dlog } from '../debug.js';
 import { blurTextInput, currentlyFocusedInput } from '../text-input-state.js';
 import { LayoutAnimation } from '../layout-animation/index.js';
-// RN's scheduleLayoutAnimation falls back to the 'keyboard' animation type when the
-// event's easing string isn't a known LayoutAnimation type (Keyboard.js:200).
-const KEYBOARD_ANIMATION_TYPE = 'keyboard';
-// Map a raw easing string onto a ILayoutAnimationType without a cast: RN does
-// `LayoutAnimation.Types[easing] || 'keyboard'`, which only yields a real type when
-// the string is a key of the Types table. We mirror that by checking membership in
-// the frozen table before trusting the value.
-function easingToAnimationType(easing) {
-    const types = LayoutAnimation.Types;
-    return types[easing] ?? KEYBOARD_ANIMATION_TYPE;
-}
 // The native module name RN registers the keyboard observer under, confirmed
 // from its spec (specs_DEPRECATED/modules/INativeKeyboardObserver.js:20,
 // `TurboModuleRegistry.get('KeyboardObserver')`).
@@ -39,11 +28,6 @@ function isKeyboardEvent(payload) {
         typeof payload.endCoordinates === 'object' &&
         payload.endCoordinates !== null);
 }
-// Lazily resolved so importing this module has no native side effect: a headless
-// run without a fake __turboModuleProxy still loads it; resolution happens on the
-// first addListener. Null when the module isn't linked.
-let observer;
-let emitter;
 // The latest keyboardDidShow event, or null when the keyboard is hidden. RN's
 // `_currentlyShowing`. Kept fresh by an internal self-subscription (see getEmitter):
 // Keyboard listens to its OWN show/hide events and caches the event so the synchronous
@@ -68,19 +52,18 @@ function trackSubscription(eventType, subscription) {
         },
     };
 }
-function getEmitter() {
-    if (emitter === undefined) {
-        if (observer === undefined) {
-            observer = getNativeModule(KEYBOARD_OBSERVER_MODULE);
-            dlog(`Keyboard: KeyboardObserver module ${observer ? 'resolved' : 'NOT resolved (null)'}`);
-        }
-        // WHY lazy: install on the first subscribe rather than at module load, so the
-        // hub exists before native emits without a hard bootstrap-order dependency for
-        // this first cut. Idempotent, so repeated subscribes cost one boolean check.
-        installDeviceEventHub();
-        emitter = new NativeEventEmitter(observer ?? undefined);
-        // Self-subscription: cache the latest show event, clear on hide (RN's constructor).
-        // Bypasses trackSubscription so removeAllListeners never tears down the cache feed.
+// Lazily resolved so importing this module has no native side effect: a headless
+// run without a fake __turboModuleProxy still loads it; resolution happens on the
+// first addListener. Null when the module isn't linked.
+//
+// The self-subscription policy that diverges from a plain lazy-resolve+emitter:
+// Keyboard caches the latest show event, clearing on hide (RN's constructor), so
+// isVisible()/metrics() read synchronously with no native round-trip. Bypasses
+// trackSubscription so removeAllListeners never tears down the cache feed.
+const deviceEventModule = createDeviceEventModule({
+    moduleName: KEYBOARD_OBSERVER_MODULE,
+    moduleLogPrefix: 'Keyboard: KeyboardObserver module',
+    onEmitterCreated: emitter => {
         emitter.addListener(KEYBOARD_EVENT.didShow, payload => {
             if (isKeyboardEvent(payload))
                 currentlyShowing = payload;
@@ -88,8 +71,10 @@ function getEmitter() {
         emitter.addListener(KEYBOARD_EVENT.didHide, () => {
             currentlyShowing = null;
         });
-    }
-    return emitter;
+    },
+});
+function getEmitter() {
+    return deviceEventModule.getEmitter();
 }
 export const Keyboard = {
     addListener(eventType, listener) {
@@ -128,7 +113,7 @@ export const Keyboard = {
         dlog(`Keyboard.scheduleLayoutAnimation -> duration ${duration}, easing ${easing}`);
         LayoutAnimation.configureNext({
             duration,
-            update: { duration, type: easingToAnimationType(easing) },
+            update: { duration, type: LayoutAnimation.coerceType(easing) },
         });
     },
     // RN's dismissKeyboard blurs the currently-focused input (TextInputState); blurring

package/build/layout-animation/index.d.ts

@@ -61,6 +61,7 @@ declare class LayoutAnimationImpl {
     spring(onAnimationDidEnd?: IOnAnimationDidEndCallback): void;
     setLayoutAnimationEnabled(enabled: boolean): void;
     checkConfig(..._args: unknown[]): void;
+    coerceType(easing: string): ILayoutAnimationType;
 }
 export declare const LayoutAnimation: LayoutAnimationImpl;
 export {};

package/build/layout-animation/index.js

@@ -9,20 +9,17 @@
 // these in the adapter, not in shared, like Keyboard / StatusBar).
 import { getNativeModule } from '../native-modules.js';
 import { dlog } from '../debug.js';
+import { isRecord } from '../type-guards.js';
 // ---- native module routing ----------------------------------------------
-// DEVICE-VERIFY-PENDING: on bridgeless Fabric the layout-animation configure call
-// is exposed by RN through the UIManager surface (RN's non-Fabric path calls
-// `UIManager.configureNextLayoutAnimation`; the Fabric path routes the same args
-// onto `global.nativeFabricUIManager.configureNextLayoutAnimation`). The native
-// MODULE NAME is platform-specific and a headless fake answers to ANY name, so
-// the name below is the most plausible bridgeless candidate, NOT proven. Only the
-// simulator/device resolution log can confirm it; the fallback list is tried in
-// order so a wrong primary still resolves on a real host. Verify on-device before
-// trusting either name. See the `dlog` at the resolution seam below.
-const NATIVE_UI_MANAGER_NAME = {
-    primary: 'UIManager',
-    fallback: 'FabricUIManager',
-};
+// RN's actual dual-path (LayoutAnimation.js): the Fabric global slot
+// (`global.nativeFabricUIManager`, a JSI slot read directly, not a TurboModule
+// lookup) is tried FIRST; only when it lacks `configureNextLayoutAnimation` does
+// RN fall back to the TurboModule `UIManager.configureNextLayoutAnimation`
+// (`TurboModuleRegistry.getEnforcing('UIManager')` in NativeUIManager.js; iOS's
+// RCTUIManager.mm registers under the same bare "UIManager" name via
+// RCT_EXPORT_MODULE()). There is only ONE correct TurboModule name; RN never
+// registers a module under "FabricUIManager".
+const NATIVE_UI_MANAGER_MODULE_NAME = 'UIManager';
 // ---- public type surface (ported from RN's ReactNativeTypes) -------------
 const ANIMATION_TYPE = {
     spring: 'spring',
@@ -38,28 +35,39 @@ const ANIMATION_PROPERTY = {
     scaleY: 'scaleY',
     scaleXY: 'scaleXY',
 };
-// Resolved FRESH on every configureNext, deliberately NOT memoized. The native module can
-// be absent at one moment and linked later, and a cached answer would pin the first result;
-// getNativeModule is a cheap proxy lookup, so per-call resolution costs nothing and stays
-// correct. (Memoizing here also broke the headless smoke, which flips a fake module on/off
-// in one process: a cached module survived the flip-off, so configureNext kept calling native
-// when the module was meant to be absent.)
+// Narrows the Fabric global slot down to whether it ALSO carries the
+// layout-animation hook. `fabric.ts`'s `IFabricSlot` deliberately omits this
+// method (out of scope for the engine's own mutation API), so the slot's static
+// type never has it either; this is the runtime feature-detect RN itself does
+// (`FabricUIManager?.configureNextLayoutAnimation` in LayoutAnimation.js) before
+// calling it, no `as` cast needed.
+function hasConfigureNextLayoutAnimation(value) {
+    return isRecord(value) && typeof value.configureNextLayoutAnimation === 'function';
+}
+// Resolved FRESH on every configureNext, deliberately NOT memoized. Either mechanism can
+// come and go at runtime (the Fabric global installs during bootstrap; a TurboModule can be
+// absent at one moment and linked later), and a cached answer would pin the first result;
+// both lookups are cheap, so per-call resolution costs nothing and stays correct.
+// (Memoizing here also broke the headless smoke, which flips a fake module on/off in one
+// process: a cached module survived the flip-off, so configureNext kept calling native when
+// the module was meant to be absent.)
 function resolveUIManager() {
-    // Try the most plausible bridgeless name first, then fall back. A wrong primary
-    // resolves null on a real host (the bridgeless proxy returns null for an
-    // unlinked name), so the fallback covers a misnamed primary.
-    const candidates = [NATIVE_UI_MANAGER_NAME.primary, NATIVE_UI_MANAGER_NAME.fallback];
-    for (const name of candidates) {
-        const module = getNativeModule(name);
-        if (module !== null) {
-            // DEVICE-VERIFY-PENDING seam: this line on the simulator/device is the only
-            // proof the chosen name is the real one. Keep it permanently (P0 logging gate).
-            dlog(`LayoutAnimation: resolved native UIManager via "${name}"`);
-            return module;
-        }
+    // Mechanism 1: the Fabric global slot, read directly: a JSI global, not a
+    // TurboModule lookup.
+    const fabricUIManager = globalThis.nativeFabricUIManager;
+    if (hasConfigureNextLayoutAnimation(fabricUIManager)) {
+        dlog('LayoutAnimation: resolved native UIManager via the Fabric global slot');
+        return fabricUIManager;
     }
-    dlog(`LayoutAnimation: no native UIManager resolved (tried ${candidates.join(', ')}); ` +
-        `configureNext is a no-op (headless or module not linked)`);
+    // Mechanism 2: the TurboModule fallback (RN's non-Fabric path).
+    const module = getNativeModule(NATIVE_UI_MANAGER_MODULE_NAME);
+    if (module !== null) {
+        dlog(`LayoutAnimation: resolved native UIManager via "${NATIVE_UI_MANAGER_MODULE_NAME}"`);
+        return module;
+    }
+    dlog('LayoutAnimation: no native UIManager resolved (no Fabric global slot, ' +
+        `"${NATIVE_UI_MANAGER_MODULE_NAME}" module not linked); configureNext is a no-op ` +
+        '(headless or module not linked)');
     return null;
 }
 // ---- config builder ------------------------------------------------------
@@ -106,7 +114,7 @@ function setLayoutAnimationEnabled(value) {
 // ---- configureNext -------------------------------------------------------
 // Configures the next commit to be animated. NATIVE drives completion:
 // `onAnimationDidEnd` is passed straight through as the native success callback,
-// so it fires exactly when the native animation actually finishes, including
+// so it fires exactly when the native animation finishes, including
 // when native extends it past `duration` (spring overshoot, OS slowdown,
 // reduce-motion). `onAnimationDidFail` fires only if native config parsing fails.
 // When no native module is linked (headless), this is a logged no-op; an app
@@ -140,7 +148,7 @@ function configureNext(config, onAnimationDidEnd, onAnimationDidFail) {
         onAnimationDidEnd?.();
     };
     dlog(`LayoutAnimation.configureNext: dispatching config (duration=${config.duration})`);
-    // onError only fires if native config parsing fails; default to a no-op.
+    // Default to a no-op when the caller doesn't supply one.
     manager.configureNextLayoutAnimation(config, onComplete, onAnimationDidFail ?? (() => { }));
 }
 // ---- the LayoutAnimation facade ------------------------------------------
@@ -178,5 +186,15 @@ class LayoutAnimationImpl {
     checkConfig(..._args) {
         dlog('LayoutAnimation.checkConfig(...) has been disabled.');
     }
+    // Coerce an arbitrary string (e.g. a keyboard event's `easing` field) onto a known
+    // ILayoutAnimationType, falling back to 'keyboard' when it isn't a key of `Types`.
+    // Owned here, not by a caller: `Types` is this class's own frozen table, so by
+    // Information Expert the coercion belongs on the type it reads (Keyboard's
+    // scheduleLayoutAnimation is the first caller; RN's own
+    // `LayoutAnimation.Types[easing] || 'keyboard'` is the same rule).
+    coerceType(easing) {
+        const types = this.Types;
+        return types[easing] ?? ANIMATION_TYPE.keyboard;
+    }
 }
 export const LayoutAnimation = new LayoutAnimationImpl();

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/native-modules.d.ts

@@ -1,6 +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.js

@@ -5,10 +5,12 @@
 // 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
+// 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.
@@ -55,3 +57,64 @@ export function getEnforcingNativeModule(name) {
     }
     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

@@ -10,6 +10,7 @@ export interface ISymbioteEvent {
     stopPropagation: () => void;
 }
 export type IListener = (event: ISymbioteEvent) => unknown;
+export declare function isSymbioteEvent(value: unknown): value is ISymbioteEvent;
 export interface ISymbioteNode {
     readonly [BRAND]: true;
     readonly component: string;
@@ -22,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.
@@ -15,6 +16,15 @@ const BRAND = Symbol('symbiote.node');
 export const RAW_TEXT_COMPONENT = 'RCTRawText';
 export const TEXT_COMPONENT = 'RCTText';
 export const VIRTUAL_TEXT_COMPONENT = 'RCTVirtualText';
+// Runtime guard narrowing `unknown` to ISymbioteEvent (no `as` cast). Lives with the interface
+// it tests, so every adapter checking for a Symbiote event shares one guard instead of writing
+// its own copy.
+export function isSymbioteEvent(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const nativeEvent = Reflect.get(value, 'nativeEvent');
+    return typeof nativeEvent === 'object' && nativeEvent !== null;
+}
 export function createElement(component, isText = false) {
     return {
         [BRAND]: true,
@@ -43,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
@@ -157,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;
         }