@symbiote-native/engine 0.1.0

package/build/appearance/index.d.ts

@@ -0,0 +1,12 @@
+import { type IEventSubscription } from '../native-events';
+export type IColorSchemeName = 'light' | 'dark';
+export type IColorSchemePreference = IColorSchemeName | 'unspecified';
+interface IAppearancePreferences {
+    colorScheme: IColorSchemeName | null;
+}
+export declare const Appearance: {
+    getColorScheme(): IColorSchemeName | null;
+    setColorScheme(colorScheme: IColorSchemePreference): void;
+    addChangeListener(listener: (preferences: IAppearancePreferences) => void): IEventSubscription;
+};
+export {};

package/build/appearance/index.js

@@ -0,0 +1,84 @@
+// Appearance module: reads/sets the device color scheme and reports changes.
+// Native emits the device event `appearanceChanged` ({ colorScheme }) through the
+// device hub; this subscribes via a NativeEventEmitter bound to the Appearance
+// native module (which RN keys its appearance events off of) and re-broadcasts to
+// JS listeners as a plain `{ colorScheme }` payload. Mirrors RN's
+// Libraries/Utilities/Appearance.js, slimmed to the parts we need.
+import { getNativeModule } from '../native-modules';
+import { installDeviceEventHub, NativeEventEmitter, } from '../native-events';
+import { dlog } from '../debug';
+// The native module name RN registers the appearance module under, confirmed from
+// its spec (specs_DEPRECATED/modules/INativeAppearance.js, `TurboModuleRegistry.get('Appearance')`).
+const APPEARANCE_MODULE = 'Appearance';
+// The device event native emits when the system color scheme changes. RN's
+// INativeAppearance spec / Appearance.js.
+const APPEARANCE_CHANGED_EVENT = 'appearanceChanged';
+function isAppearancePreferences(value) {
+    return typeof value === 'object' && value !== null && 'colorScheme' in value;
+}
+// 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 use. `null` when the module isn't linked.
+let appearanceModule;
+let emitter;
+// Cached scheme, kept fresh by the change listener; mirrors RN's `state.appearance`.
+let cachedScheme;
+function getModule() {
+    if (appearanceModule === undefined) {
+        appearanceModule = getNativeModule(APPEARANCE_MODULE);
+        dlog(`Appearance: module ${appearanceModule ? 'resolved' : 'NOT resolved (null)'}`);
+    }
+    return appearanceModule;
+}
+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 module = getModule();
+        emitter = new NativeEventEmitter(module ?? undefined);
+        // Keep the cached scheme fresh even when nobody is listening, so a later
+        // getColorScheme() after a system change reads the new value. RN does the same.
+        emitter.addListener(APPEARANCE_CHANGED_EVENT, payload => {
+            if (!isAppearancePreferences(payload))
+                return;
+            dlog(`Appearance: ${APPEARANCE_CHANGED_EVENT} -> ${String(payload.colorScheme)}`);
+            cachedScheme = payload.colorScheme;
+        });
+    }
+    return emitter;
+}
+export const Appearance = {
+    // The current color scheme, or null when no module is linked / the device is in
+    // 'unspecified'. Never throws; a missing module reads as null.
+    getColorScheme() {
+        const module = getModule();
+        if (module === null)
+            return null;
+        // Ensure the change listener is wired so the cache stays fresh after this read.
+        getEmitter();
+        if (cachedScheme === undefined)
+            cachedScheme = module.getColorScheme();
+        return cachedScheme;
+    },
+    // Override the color scheme (or 'unspecified' to follow the system). No-op when
+    // the module isn't linked.
+    setColorScheme(colorScheme) {
+        const module = getModule();
+        if (module === null) {
+            dlog('Appearance.setColorScheme -> no module (no-op)');
+            return;
+        }
+        module.setColorScheme(colorScheme);
+        cachedScheme = colorScheme === 'unspecified' ? (module.getColorScheme() ?? null) : colorScheme;
+    },
+    // Subscribe to color-scheme changes. The listener receives `{ colorScheme }`.
+    addChangeListener(listener) {
+        dlog('Appearance.addChangeListener');
+        return getEmitter().addListener(APPEARANCE_CHANGED_EVENT, payload => {
+            if (!isAppearancePreferences(payload))
+                return;
+            listener({ colorScheme: payload.colorScheme });
+        });
+    },
+};

package/build/back-handler/index.d.ts

@@ -0,0 +1,14 @@
+import { type IEventSubscription } from '../native-events';
+declare const BACK_PRESS_EVENT: {
+    readonly backPress: "backPress";
+    readonly hardwareBackPress: "hardwareBackPress";
+};
+export type IBackPressEventName = (typeof BACK_PRESS_EVENT)[keyof typeof BACK_PRESS_EVENT];
+export type IBackPressHandler = () => boolean | null | undefined | void;
+declare class BackHandlerImpl {
+    exitApp(): void;
+    addEventListener(_eventName: IBackPressEventName, handler: IBackPressHandler): IEventSubscription;
+    removeEventListener(_eventName: IBackPressEventName, handler: IBackPressHandler): void;
+}
+export declare const BackHandler: BackHandlerImpl;
+export {};

package/build/back-handler/index.js

@@ -0,0 +1,106 @@
+// BackHandler module: intercepts the Android hardware back button. Native emits
+// the device event `hardwareBackPress` through the device hub; this subscribes via a
+// NativeEventEmitter and runs the registered handlers in REVERSE registration order
+// (last-registered first). The first handler to return true consumes the press and
+// stops the chain; if none consume it, the native default fires (the app exits).
+// Android-only by intent: iOS has no hardware back button, so the whole module
+// degrades to a no-op when the native module is absent, matching RN's
+// BackHandler.ios.js stub. Mirrors RN's Libraries/Utilities/BackHandler.android.js.
+import { getNativeModule } from '../native-modules';
+import { installDeviceEventHub, NativeEventEmitter, } from '../native-events';
+import { dlog } from '../debug';
+// The native module name RN registers this under. NOTE: this is the name the
+// INativeDeviceEventManager spec resolves via
+// `TurboModuleRegistry.get('DeviceEventManager')`, NOT the spec filename
+// `INativeDeviceEventManager`. Per the symbiote invariant, a module name is only
+// provable on a real host (a headless fake answers to any name); this name is
+// device-verify-pending (Android). See .docs/native-module-platform-routing.md.
+const DEVICE_EVENT_MANAGER_MODULE = 'DeviceEventManager';
+// The device event native emits when the hardware back button is pressed.
+const DEVICE_BACK_EVENT = 'hardwareBackPress';
+// The public event names callers subscribe to. `backPress` is RN's legacy alias
+// for `hardwareBackPress`; both map to the same chain.
+const BACK_PRESS_EVENT = {
+    backPress: 'backPress',
+    hardwareBackPress: 'hardwareBackPress',
+};
+// The registry, in registration order. Invoked in reverse on a back press.
+const backPressSubscriptions = [];
+function isHandled(result) {
+    return result === true;
+}
+// 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 use. `null` when the module isn't linked (e.g. iOS).
+let deviceEventManager;
+let emitter;
+function getModule() {
+    if (deviceEventManager === undefined) {
+        deviceEventManager = getNativeModule(DEVICE_EVENT_MANAGER_MODULE);
+        dlog(`BackHandler: module ${deviceEventManager ? 'resolved' : 'NOT resolved (null)'}`);
+    }
+    return deviceEventManager;
+}
+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();
+        emitter = new NativeEventEmitter(getModule() ?? undefined);
+        // Wire the native back-press event to the reverse-order chain exactly once.
+        emitter.addListener(DEVICE_BACK_EVENT, dispatchBackPress);
+    }
+    return emitter;
+}
+// Run handlers last-registered-first; the first to return true consumes the press
+// and the rest are skipped. If none consume it, fall through to the native default.
+function dispatchBackPress() {
+    for (let i = backPressSubscriptions.length - 1; i >= 0; i--) {
+        const handler = backPressSubscriptions[i];
+        if (handler !== undefined && isHandled(handler())) {
+            dlog(`BackHandler: back press consumed by handler ${i}`);
+            return;
+        }
+    }
+    dlog('BackHandler: back press unhandled -> native default');
+    BackHandler.exitApp();
+}
+class BackHandlerImpl {
+    // Trigger Android's default back behavior (exit the app). No-op without a module
+    // (e.g. iOS); never throws, mirroring RN's BackHandler.ios.js stub.
+    exitApp() {
+        const module = getModule();
+        if (module === null) {
+            dlog('BackHandler.exitApp -> no module (no-op)');
+            return;
+        }
+        module.invokeDefaultBackPressHandler();
+    }
+    // Register a hardware-back handler. The returned subscription's remove()
+    // unregisters it. Idempotent on the same handler reference (RN semantics).
+    addEventListener(_eventName, handler) {
+        // Install the hub/emitter on first subscribe so native back presses reach the chain.
+        getEmitter();
+        dlog('BackHandler.addEventListener -> hardwareBackPress');
+        if (backPressSubscriptions.indexOf(handler) === -1) {
+            backPressSubscriptions.push(handler);
+        }
+        return {
+            remove: () => {
+                const index = backPressSubscriptions.indexOf(handler);
+                if (index !== -1) {
+                    backPressSubscriptions.splice(index, 1);
+                }
+            },
+        };
+    }
+    // Legacy unsubscribe kept for RN parity. The modern path is the subscription's
+    // remove() returned by addEventListener.
+    removeEventListener(_eventName, handler) {
+        const index = backPressSubscriptions.indexOf(handler);
+        if (index !== -1) {
+            backPressSubscriptions.splice(index, 1);
+        }
+    }
+}
+export const BackHandler = new BackHandlerImpl();

package/build/commit.d.ts

@@ -0,0 +1,16 @@
+import { type IFabricNode, type IRootTag, type IMeasureOnSuccess, type IMeasureInWindowOnSuccess, type IMeasureLayoutOnSuccess } from './fabric';
+import { type ISymbioteNode } from './node';
+import { type IColorValue } from './platform-color';
+export declare function setColorProcessor(process: (value: IColorValue) => unknown): void;
+export declare function processColor(color: IColorValue): unknown;
+export declare function disposeRoot(rootTag: IRootTag): void;
+export declare function commitChildren(rootTag: IRootTag, children: readonly ISymbioteNode[]): void;
+export declare function setNativeProps(node: ISymbioteNode, partial: Record<string, unknown>): void;
+export declare function getNativeTag(node: ISymbioteNode): number | undefined;
+export declare function whenCommitted(node: ISymbioteNode, action: () => void): () => void;
+export declare function getNativeNode(node: ISymbioteNode): IFabricNode | undefined;
+export declare function dispatchViewCommand(node: ISymbioteNode, commandName: string, args: readonly unknown[]): void;
+export declare function sendAccessibilityEvent(node: ISymbioteNode, eventType: string): void;
+export declare function measure(node: ISymbioteNode, callback: IMeasureOnSuccess): void;
+export declare function measureInWindow(node: ISymbioteNode, callback: IMeasureInWindowOnSuccess): void;
+export declare function measureLayout(node: ISymbioteNode, relativeTo: ISymbioteNode, onSuccess: IMeasureLayoutOnSuccess, onFail?: () => void): void;