@symbiote-native/engine 0.1.0

package/build/animated/value-xy.d.ts

@@ -0,0 +1,35 @@
+import { AnimatedValue } from './value';
+export interface IValueXY {
+    x: number;
+    y: number;
+}
+type IValueXYListener = (value: IValueXY) => void;
+export declare class AnimatedValueXY {
+    readonly x: AnimatedValue;
+    readonly y: AnimatedValue;
+    private readonly jointListeners;
+    constructor(value?: {
+        x: number | AnimatedValue;
+        y: number | AnimatedValue;
+    });
+    __getValue(): IValueXY;
+    setValue(value: IValueXY): void;
+    setOffset(offset: IValueXY): void;
+    flattenOffset(): void;
+    extractOffset(): void;
+    stopAnimation(callback?: (value: IValueXY) => void): void;
+    resetAnimation(callback?: (value: IValueXY) => void): void;
+    addListener(callback: IValueXYListener): string;
+    removeListener(id: string): void;
+    removeAllListeners(): void;
+    getLayout(): {
+        left: AnimatedValue;
+        top: AnimatedValue;
+    };
+    getTranslateTransform(): [{
+        translateX: AnimatedValue;
+    }, {
+        translateY: AnimatedValue;
+    }];
+}
+export {};

package/build/animated/value-xy.js

@@ -0,0 +1,106 @@
+// AnimatedValueXY: a 2D value for pan-gesture-style animations. It is not a
+// driving node itself: it multiplexes two ordinary AnimatedValues (x, y), so the
+// same clone-on-write and listener machinery that powers AnimatedValue applies
+// per-axis. Ported from RN's AnimatedValueXY.js with the native-driver and
+// platform-config branches removed (ADR 0016). The two child values carry their
+// own native state if they are ever made native.
+import { AnimatedValue } from './value';
+let nextListenerId = 1;
+function isAnimatedValuePair(value) {
+    return value.x instanceof AnimatedValue && value.y instanceof AnimatedValue;
+}
+// Not an AnimatedNode: you bind the inner x/y (via getLayout / getTranslateTransform),
+// never the XY object itself, so it carries no graph-node base, just the two values.
+export class AnimatedValueXY {
+    x;
+    y;
+    // Each joint id maps to the two per-axis listener ids it registered, so
+    // removeListener can tear both down together.
+    jointListeners = new Map();
+    constructor(value = { x: 0, y: 0 }) {
+        if (typeof value.x === 'number' && typeof value.y === 'number') {
+            this.x = new AnimatedValue(value.x);
+            this.y = new AnimatedValue(value.y);
+        }
+        else if (isAnimatedValuePair(value)) {
+            this.x = value.x;
+            this.y = value.y;
+        }
+        else {
+            throw new Error('AnimatedValueXY must be initialized with an object of numbers or AnimatedValues.');
+        }
+    }
+    __getValue() {
+        return { x: this.x.__getValue(), y: this.y.__getValue() };
+    }
+    // Directly set both axes. Stops any running per-axis animation and updates
+    // every bound prop.
+    setValue(value) {
+        this.x.setValue(value.x);
+        this.y.setValue(value.y);
+    }
+    // An offset applied on top of whatever value is set, per axis.
+    setOffset(offset) {
+        this.x.setOffset(offset.x);
+        this.y.setOffset(offset.y);
+    }
+    // Fold each axis's offset into its base value; the output is unchanged.
+    flattenOffset() {
+        this.x.flattenOffset();
+        this.y.flattenOffset();
+    }
+    // Move each axis's base value into its offset; the output is unchanged.
+    extractOffset() {
+        this.x.extractOffset();
+        this.y.extractOffset();
+    }
+    // Stop any running animation on either axis. `callback` receives the final
+    // 2D value, useful for syncing state to the resting position.
+    stopAnimation(callback) {
+        this.x.stopAnimation();
+        this.y.stopAnimation();
+        callback?.(this.__getValue());
+    }
+    // Stop any animation and reset both axes to their original values.
+    resetAnimation(callback) {
+        this.x.resetAnimation();
+        this.y.resetAnimation();
+        callback?.(this.__getValue());
+    }
+    // Observe updates from either axis as a single {x, y} event. Both axes share
+    // one joint callback, so a change on either fires the listener with the
+    // current 2D value.
+    addListener(callback) {
+        const id = String(nextListenerId++);
+        const jointCallback = () => {
+            callback(this.__getValue());
+        };
+        this.jointListeners.set(id, {
+            x: this.x.addListener(jointCallback),
+            y: this.y.addListener(jointCallback),
+        });
+        return id;
+    }
+    removeListener(id) {
+        const pair = this.jointListeners.get(id);
+        if (pair === undefined) {
+            return;
+        }
+        this.x.removeListener(pair.x);
+        this.y.removeListener(pair.y);
+        this.jointListeners.delete(id);
+    }
+    removeAllListeners() {
+        this.x.removeAllListeners();
+        this.y.removeAllListeners();
+        this.jointListeners.clear();
+    }
+    // Convert {x, y} into {left, top} for direct use in a style object.
+    getLayout() {
+        return { left: this.x, top: this.y };
+    }
+    // Convert {x, y} into a usable translation transform array.
+    getTranslateTransform() {
+        return [{ translateX: this.x }, { translateY: this.y }];
+    }
+}

package/build/animated/value.d.ts

@@ -0,0 +1,36 @@
+import type { IAnimation, IEndCallback } from './animation';
+import { AnimatedWithChildren, type IValueListener } from './graph';
+import type { AnimatedTracking } from './animations/tracking';
+import { AnimatedInterpolation } from './interpolation-node';
+import type { IInterpolationConfig } from './interpolation';
+import { type INativeNodeConfig, type IPlatformConfig } from './native/native-animated';
+export declare class AnimatedValue extends AnimatedWithChildren {
+    private value;
+    private readonly startingValue;
+    private offset;
+    private animation;
+    private nativeListening;
+    private tracking;
+    constructor(value: number);
+    __detach(): void;
+    addListener(callback: IValueListener): string;
+    removeListener(id: string): void;
+    removeAllListeners(): void;
+    __makeNative(platformConfig?: IPlatformConfig): void;
+    private startListeningToNativeValueUpdates;
+    private stopListeningToNativeValueUpdates;
+    __getValue(): number;
+    setValue(value: number): void;
+    setOffset(offset: number): void;
+    flattenOffset(): void;
+    extractOffset(): void;
+    __onNativeUpdate(value: number, offset?: number): void;
+    __getNativeConfig(): INativeNodeConfig;
+    stopAnimation(callback?: (value: number) => void): void;
+    track(tracking: AnimatedTracking): void;
+    private stopTracking;
+    resetAnimation(callback?: (value: number) => void): void;
+    interpolate(config: IInterpolationConfig): AnimatedInterpolation;
+    animate(animation: IAnimation, callback?: IEndCallback): void;
+    private updateValue;
+}

package/build/animated/value.js

@@ -0,0 +1,185 @@
+// AnimatedValue: the standard driving value. One value can drive many props in
+// sync but is driven by one mechanism at a time: a new mechanism (a fresh
+// animation, or setValue) stops the previous one. Ported from RN's
+// AnimatedValue.js with the native-driver branches removed (ADR 0016); tracking
+// (animating toward another animated node) is deferred.
+import { AnimatedWithChildren, flushValue } from './graph';
+import { AnimatedInterpolation } from './interpolation-node';
+import { nativeAnimated, } from './native/native-animated';
+export class AnimatedValue extends AnimatedWithChildren {
+    value;
+    startingValue;
+    offset;
+    animation;
+    // True while we are streaming native value updates back to JS listeners (only
+    // meaningful when the value is native-driven and has at least one JS listener).
+    nativeListening = false;
+    // Set while this value is chasing a moving target (Animated.spring toValue: node).
+    tracking = null;
+    constructor(value) {
+        super();
+        if (typeof value !== 'number') {
+            throw new Error('AnimatedValue: Attempting to set value to undefined');
+        }
+        this.startingValue = value;
+        this.value = value;
+        this.offset = 0;
+        this.animation = null;
+    }
+    __detach() {
+        this.stopAnimation();
+        this.stopListeningToNativeValueUpdates();
+        super.__detach();
+    }
+    // A JS listener on a native-driven value sees nothing per frame unless native
+    // streams updates back, so adding the first listener starts that stream and
+    // removing the last stops it. When the value isn't native, these are no-ops and
+    // the base listener machinery alone fires (JS owns the frames).
+    addListener(callback) {
+        const id = super.addListener(callback);
+        if (this.isNative)
+            this.startListeningToNativeValueUpdates();
+        return id;
+    }
+    removeListener(id) {
+        super.removeListener(id);
+        if (!this.hasListeners())
+            this.stopListeningToNativeValueUpdates();
+    }
+    removeAllListeners() {
+        super.removeAllListeners();
+        this.stopListeningToNativeValueUpdates();
+    }
+    // A value made native while listeners already exist must start streaming now.
+    __makeNative(platformConfig) {
+        super.__makeNative(platformConfig);
+        if (this.hasListeners())
+            this.startListeningToNativeValueUpdates();
+    }
+    startListeningToNativeValueUpdates() {
+        if (this.nativeListening || !this.isNative)
+            return;
+        this.nativeListening = true;
+        nativeAnimated.startListeningToValue(this.__getNativeTag(), value => {
+            // __onNativeUpdate syncs the JS value and fires our listeners (no flush:
+            // native already moved the view).
+            this.__onNativeUpdate(value);
+        });
+    }
+    stopListeningToNativeValueUpdates() {
+        if (!this.nativeListening)
+            return;
+        this.nativeListening = false;
+        nativeAnimated.stopListeningToValue(this.__getNativeTag());
+    }
+    __getValue() {
+        return this.value + this.offset;
+    }
+    // Directly set the value. Stops any running animation and updates every bound
+    // prop. When the value is native-driven we skip the JS flush (native owns the
+    // view) and push the value into the native node instead.
+    setValue(value) {
+        if (this.animation) {
+            this.animation.stop();
+            this.animation = null;
+        }
+        this.updateValue(value, !this.isNative);
+        if (this.isNative) {
+            nativeAnimated.setAnimatedNodeValue(this.__getNativeTag(), value);
+        }
+    }
+    // An offset applied on top of whatever value is set (via setValue, an
+    // animation, or Animated.event). Useful for compensating a gesture's start.
+    setOffset(offset) {
+        this.offset = offset;
+        if (this.isNative) {
+            nativeAnimated.setAnimatedNodeOffset(this.__getNativeTag(), offset);
+        }
+    }
+    // Fold the offset into the base value; the output is unchanged.
+    flattenOffset() {
+        this.value += this.offset;
+        this.offset = 0;
+        if (this.isNative) {
+            nativeAnimated.flattenAnimatedNodeOffset(this.__getNativeTag());
+        }
+    }
+    // Move the base value into the offset; the output is unchanged.
+    extractOffset() {
+        this.offset += this.value;
+        this.value = 0;
+        if (this.isNative) {
+            nativeAnimated.extractAnimatedNodeOffset(this.__getNativeTag());
+        }
+    }
+    // Sync the JS value from a native update (the driver's completion callback, or a
+    // native value listener) without re-flushing. Native already moved the view.
+    __onNativeUpdate(value, offset) {
+        this.updateValue(value, false);
+        if (offset !== undefined) {
+            this.offset = offset;
+        }
+    }
+    __getNativeConfig() {
+        return { type: 'value', value: this.value, offset: this.offset };
+    }
+    // Stop any running animation OR tracking. `callback` receives the final value,
+    // useful for syncing state to the animation's resting position.
+    stopAnimation(callback) {
+        this.stopTracking();
+        if (this.animation) {
+            this.animation.stop();
+        }
+        this.animation = null;
+        callback?.(this.__getValue());
+    }
+    // Chase a moving target: the AnimatedTracking subscribes to the target node and
+    // re-launches the animation on every target change. Like RN, animate() itself does
+    // NOT clear tracking (the tracking node calls animate on each update); only
+    // stopAnimation / a new track tears the previous tracking down.
+    track(tracking) {
+        this.stopTracking();
+        this.tracking = tracking;
+        tracking.update();
+    }
+    stopTracking() {
+        if (this.tracking !== null) {
+            this.tracking.__detach();
+            this.tracking = null;
+        }
+    }
+    // Stop any animation and reset to the original value.
+    resetAnimation(callback) {
+        this.stopAnimation(callback);
+        this.value = this.startingValue;
+    }
+    // Map the value before it reaches a prop, e.g. 0..1 -> 0..10.
+    interpolate(config) {
+        return new AnimatedInterpolation(this, config);
+    }
+    // Drive this value with an animation. Typically called by Animated.timing /
+    // spring / decay rather than directly.
+    animate(animation, callback) {
+        const previousAnimation = this.animation;
+        if (this.animation) {
+            this.animation.stop();
+        }
+        this.animation = animation;
+        animation.start(this.value, value => {
+            this.updateValue(value, true);
+        }, result => {
+            this.animation = null;
+            callback?.(result);
+        }, previousAnimation, this);
+    }
+    updateValue(value, flush) {
+        if (value === undefined) {
+            throw new Error('AnimatedValue: Attempting to set value to undefined');
+        }
+        this.value = value;
+        if (flush) {
+            flushValue(this);
+        }
+        this.__callListeners(this.__getValue());
+    }
+}

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

@@ -0,0 +1,40 @@
+import type { IRootTag } from '../fabric';
+export interface IAppParameters {
+    rootTag: IRootTag;
+    initialProps?: object;
+}
+export type IRunnable = (appParameters: IAppParameters) => void;
+export interface IRegistry {
+    sections: string[];
+    runnables: Record<string, IRunnable>;
+}
+export type IHeadlessTask = (taskData: unknown) => Promise<void>;
+export type ITaskProvider = () => IHeadlessTask;
+export type ITaskCanceller = () => void;
+export type ITaskCancelProvider = () => ITaskCanceller;
+export interface IHostRegistrar {
+    registerRunnable(appKey: string, run: IRunnable): string;
+    unmountAtRootTag?(rootTag: IRootTag): void;
+}
+export interface IAppRegistry<TComponentProvider, TWrapperComponentProvider> {
+    registerComponent(appKey: string, componentProvider: TComponentProvider): string;
+    registerRunnable(appKey: string, run: IRunnable): string;
+    registerSection(appKey: string, componentProvider: TComponentProvider): string;
+    runApplication(appKey: string, appParameters: IAppParameters): void;
+    unmountApplicationComponentAtRootTag(rootTag: IRootTag): void;
+    setWrapperComponentProvider(provider: TWrapperComponentProvider): void;
+    getAppKeys(): string[];
+    getRunnable(appKey: string): IRunnable | undefined;
+    getSectionKeys(): string[];
+    getSections(): Record<string, IRunnable>;
+    getRegistry(): IRegistry;
+    registerHeadlessTask(taskKey: string, taskProvider: ITaskProvider): void;
+    registerCancellableHeadlessTask(taskKey: string, taskProvider: ITaskProvider, taskCancelProvider: ITaskCancelProvider): void;
+    startHeadlessTask(taskId: number, taskKey: string, data: unknown): void;
+    cancelHeadlessTask(taskId: number, taskKey: string): void;
+}
+export interface ICreateAppRegistryResult<TComponentProvider, TWrapperComponentProvider> {
+    AppRegistry: IAppRegistry<TComponentProvider, TWrapperComponentProvider>;
+    setHostRegistrar(registrar: IHostRegistrar): void;
+}
+export declare function createAppRegistry<TComponentProvider, TWrapperComponentProvider>(runnableFor: (componentProvider: TComponentProvider, getWrapperComponentProvider: () => TWrapperComponentProvider | undefined) => IRunnable): ICreateAppRegistryResult<TComponentProvider, TWrapperComponentProvider>;

package/build/app-registry/index.js

@@ -0,0 +1,144 @@
+// AppRegistry: the JS entry point RN apps already use — `AppRegistry.registerComponent(appKey,
+// () => App)`. RN's version stores a runnable that calls its own React renderer; every symbiote
+// adapter instead stores a runnable that calls ITS OWN `mount`, driving @symbiote-native/engine. That
+// difference — building a runnable from a component provider — is the ONLY framework-specific
+// bit (React wraps via createElement, Vue via createApp/h, Angular via createComponent), so it is
+// the one thing each adapter supplies; everything else (registry bookkeeping, sections, the
+// host-registrar bridge, headless tasks) is byte-identical across adapters and lives here once.
+//
+// The catch: the native Fabric host invokes RN's AppRegistry (a registered callable module) by
+// app key, and it can't see ours. So registerComponent must also hand its runnable to RN's
+// registrar. Reached the same way shared reaches processColor: a dependency-injected seam
+// (setHostRegistrar), so the core stays react-native-free and the app glue wires the host once
+// at startup.
+import { getNativeModule } from '../native-modules';
+import { dlog } from '../debug';
+const HEADLESS_TASK_MODULE = 'HeadlessJsTaskSupport';
+// Builds one adapter's AppRegistry. `runnableFor` is the sole framework-specific seam: given a
+// component provider and a getter for the CURRENT wrapper-component provider (read at mount
+// time, not registration time — setWrapperComponentProvider must affect every runnable's next
+// run, mirroring AppRegistryImpl.js reading it live inside the runnable it returns), it returns
+// the IRunnable that actually mounts the app for a rootTag — e.g. React's createElement + mount,
+// Vue's createApp(component, props).mount(surface), Angular's createComponent + setInput.
+export function createAppRegistry(runnableFor) {
+    let hostRegistrar;
+    let wrapperComponentProvider;
+    const runnables = new Map();
+    const sections = new Map();
+    const taskProviders = new Map();
+    const taskCancelProviders = new Map();
+    function register(appKey, run, isSection = false) {
+        runnables.set(appKey, run);
+        if (isSection)
+            sections.set(appKey, run);
+        // Bridge to the native registrar so the Fabric host can mount this app by key.
+        // Absent (headless / not yet wired) → registration is local only, which is what
+        // runApplication and the smokes drive directly.
+        hostRegistrar?.registerRunnable(appKey, run);
+        return appKey;
+    }
+    // Runs a registered headless task and drives the native completion/retry
+    // protocol, mirroring RN's `startHeadlessTask` (AppRegistryImpl.js:255). Native
+    // is the only caller; it must be told when the task settles so the OS can release
+    // the wakelock. Headless (no native module) → we just run the task.
+    function runHeadlessTask(taskId, taskKey, data) {
+        const native = getNativeModule(HEADLESS_TASK_MODULE);
+        dlog(`AppRegistry.startHeadlessTask: ${taskKey} (taskId=${taskId})`);
+        const provider = taskProviders.get(taskKey);
+        if (provider === undefined) {
+            dlog(`AppRegistry.startHeadlessTask: no task registered for key "${taskKey}"`);
+            native?.notifyTaskFinished?.(taskId);
+            return;
+        }
+        void provider()(data)
+            .then(() => {
+            native?.notifyTaskFinished?.(taskId);
+        })
+            .catch((reason) => {
+            dlog(`AppRegistry.startHeadlessTask: "${taskKey}" failed: ${String(reason)}`);
+            // RN asks native whether a retry was scheduled; if not, finish the task.
+            // Without the native module there is nothing to notify.
+            const retry = native?.notifyTaskRetry?.(taskId);
+            if (retry === undefined) {
+                native?.notifyTaskFinished?.(taskId);
+                return;
+            }
+            void retry.then(retryPosted => {
+                if (!retryPosted)
+                    native?.notifyTaskFinished?.(taskId);
+            });
+        });
+    }
+    const AppRegistry = {
+        registerComponent(appKey, componentProvider) {
+            return register(appKey, runnableFor(componentProvider, () => wrapperComponentProvider));
+        },
+        registerRunnable(appKey, run) {
+            return register(appKey, run);
+        },
+        registerSection(appKey, componentProvider) {
+            return register(appKey, runnableFor(componentProvider, () => wrapperComponentProvider), true);
+        },
+        runApplication(appKey, appParameters) {
+            const run = runnables.get(appKey);
+            if (run === undefined) {
+                dlog(`AppRegistry.runApplication: no app registered for "${appKey}"`);
+                return;
+            }
+            run(appParameters);
+        },
+        unmountApplicationComponentAtRootTag(rootTag) {
+            dlog(`AppRegistry.unmountApplicationComponentAtRootTag: rootTag ${String(rootTag)}`);
+            hostRegistrar?.unmountAtRootTag?.(rootTag);
+        },
+        setWrapperComponentProvider(provider) {
+            wrapperComponentProvider = provider;
+        },
+        getAppKeys() {
+            return [...runnables.keys()];
+        },
+        getRunnable(appKey) {
+            return runnables.get(appKey);
+        },
+        getSectionKeys() {
+            return [...sections.keys()];
+        },
+        getSections() {
+            return Object.fromEntries(sections);
+        },
+        getRegistry() {
+            return {
+                sections: [...sections.keys()],
+                runnables: Object.fromEntries(runnables),
+            };
+        },
+        registerHeadlessTask(taskKey, taskProvider) {
+            AppRegistry.registerCancellableHeadlessTask(taskKey, taskProvider, () => () => { });
+        },
+        registerCancellableHeadlessTask(taskKey, taskProvider, taskCancelProvider) {
+            if (taskProviders.has(taskKey)) {
+                dlog(`AppRegistry: headless task registered multiple times for key "${taskKey}"`);
+            }
+            taskProviders.set(taskKey, taskProvider);
+            taskCancelProviders.set(taskKey, taskCancelProvider);
+        },
+        startHeadlessTask(taskId, taskKey, data) {
+            runHeadlessTask(taskId, taskKey, data);
+        },
+        cancelHeadlessTask(taskId, taskKey) {
+            dlog(`AppRegistry.cancelHeadlessTask: ${taskKey} (taskId=${taskId})`);
+            const cancelProvider = taskCancelProviders.get(taskKey);
+            if (cancelProvider === undefined) {
+                dlog(`AppRegistry.cancelHeadlessTask: no canceller registered for key "${taskKey}"`);
+                return;
+            }
+            cancelProvider()();
+        },
+    };
+    return {
+        AppRegistry,
+        setHostRegistrar(registrar) {
+            hostRegistrar = registrar;
+        },
+    };
+}

package/build/app-state/index.d.ts

@@ -0,0 +1,16 @@
+import { type IEventSubscription } from '../native-events';
+declare const APP_STATE_EVENT: {
+    readonly change: "change";
+    readonly memoryWarning: "memoryWarning";
+    readonly focus: "focus";
+    readonly blur: "blur";
+};
+export type IAppStateStatus = 'inactive' | 'background' | 'active' | 'extension' | 'unknown';
+export type IAppStateEvent = (typeof APP_STATE_EVENT)[keyof typeof APP_STATE_EVENT];
+declare class AppStateImpl {
+    get isAvailable(): boolean;
+    get currentState(): string | null;
+    addEventListener(type: IAppStateEvent, handler: (...args: unknown[]) => void): IEventSubscription;
+}
+export declare const AppState: AppStateImpl;
+export {};

package/build/app-state/index.js

@@ -0,0 +1,105 @@
+// AppState module: reports whether the app is foreground/background/inactive and
+// notifies on change, memory warnings, and (iOS) focus/blur. Native emits the
+// device events `appStateDidChange` ({ app_state }), `memoryWarning`, and
+// `appStateFocusChange` (boolean) through the device hub; this subscribes via a
+// NativeEventEmitter bound to the AppState native module and maps them onto the
+// public 'change'/'memoryWarning'/'focus'/'blur' listeners, mirroring RN's
+// Libraries/AppState/AppState.js.
+import { getNativeModule } from '../native-modules';
+import { installDeviceEventHub, NativeEventEmitter, } from '../native-events';
+import { dlog } from '../debug';
+// The native module name RN registers AppState under, confirmed from its spec
+// (specs_DEPRECATED/modules/INativeAppState.js, `TurboModuleRegistry.getEnforcing('AppState')`).
+const APP_STATE_MODULE = 'AppState';
+// The device events native emits. RN's NativeAppStateEventDefinitions.
+const NATIVE_EVENT = {
+    stateDidChange: 'appStateDidChange',
+    focusChange: 'appStateFocusChange',
+    memoryWarning: 'memoryWarning',
+};
+// The public event names callers subscribe to. RN's IAppStateEvent.
+const APP_STATE_EVENT = {
+    change: 'change',
+    memoryWarning: 'memoryWarning',
+    focus: 'focus',
+    blur: 'blur',
+};
+function isStateChangePayload(value) {
+    return typeof value === 'object' && value !== null && 'app_state' 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 first
+// use. `null` when the module isn't linked.
+let appStateModule;
+let emitter;
+let currentState = null;
+function getModule() {
+    if (appStateModule === undefined) {
+        appStateModule = getNativeModule(APP_STATE_MODULE);
+        dlog(`AppState: module ${appStateModule ? 'resolved' : 'NOT resolved (null)'}`);
+    }
+    return appStateModule;
+}
+function getEmitter() {
+    if (emitter === undefined) {
+        // WHY lazy: install on first use so the hub exists before native emits, without
+        // a hard bootstrap-order dependency. Idempotent.
+        installDeviceEventHub();
+        const module = getModule();
+        if (module !== null) {
+            currentState = module.getConstants().initialAppState;
+        }
+        emitter = new NativeEventEmitter(module ?? undefined);
+        // Keep `currentState` fresh even when nobody listens, so a read after a state
+        // change returns the new value; RN registers the same always-on observer.
+        emitter.addListener(NATIVE_EVENT.stateDidChange, payload => {
+            if (!isStateChangePayload(payload))
+                return;
+            dlog(`AppState: ${NATIVE_EVENT.stateDidChange} -> ${payload.app_state}`);
+            currentState = payload.app_state;
+        });
+    }
+    return emitter;
+}
+class AppStateImpl {
+    // Feature-detect: true when the native AppState module resolved, false when it
+    // isn't linked. RN exposes the same field so callers can guard before subscribing.
+    get isAvailable() {
+        return getModule() !== null;
+    }
+    // The current foreground/background state, populated from getConstants and kept
+    // fresh by the change observer. Null until the module resolves (or never linked).
+    get currentState() {
+        getEmitter();
+        return currentState;
+    }
+    // Subscribe to an AppState event. Native delivers `appStateDidChange`,
+    // `memoryWarning`, and `appStateFocusChange`; this maps each onto the requested
+    // public event. Never throws; a missing module yields a live-but-silent
+    // subscription (the counters are no-ops without a module).
+    addEventListener(type, handler) {
+        const eventEmitter = getEmitter();
+        dlog(`AppState.addEventListener -> ${type}`);
+        switch (type) {
+            case APP_STATE_EVENT.change:
+                return eventEmitter.addListener(NATIVE_EVENT.stateDidChange, payload => {
+                    if (!isStateChangePayload(payload))
+                        return;
+                    handler(payload.app_state);
+                });
+            case APP_STATE_EVENT.memoryWarning:
+                return eventEmitter.addListener(NATIVE_EVENT.memoryWarning, () => handler());
+            case APP_STATE_EVENT.focus:
+                return eventEmitter.addListener(NATIVE_EVENT.focusChange, hasFocus => {
+                    if (hasFocus === true)
+                        handler();
+                });
+            case APP_STATE_EVENT.blur:
+                return eventEmitter.addListener(NATIVE_EVENT.focusChange, hasFocus => {
+                    if (hasFocus === false)
+                        handler();
+                });
+        }
+    }
+}
+export const AppState = new AppStateImpl();