@symbiote-native/engine 0.1.0

package/build/debug.d.ts

@@ -0,0 +1,5 @@
+declare global {
+    var __SYMBIOTE_DEBUG__: boolean | undefined;
+}
+export declare function isDebug(): boolean;
+export declare function dlog(message: string): void;

package/build/debug.js

@@ -0,0 +1,18 @@
+// Opt-in diagnostic logging, off by default. Two switches, either flips it on:
+//   - env: DEBUG=1 — read directly off process.env.DEBUG at call time (Node,
+//     headless smokes); each example's index.js also mirrors it onto
+//     globalThis.__SYMBIOTE_DEBUG__ once at start, so changing it needs a fresh
+//     Metro start (--reset-cache), not a rebuild.
+//   - runtime: globalThis.__SYMBIOTE_DEBUG__ = true, an escape hatch for hosts
+//     where the env isn't reachable.
+// Production with neither set pays one property read per call and nothing else.
+function envEnabled() {
+    return typeof process !== 'undefined' && process.env.DEBUG === '1';
+}
+export function isDebug() {
+    return globalThis.__SYMBIOTE_DEBUG__ === true || envEnabled();
+}
+export function dlog(message) {
+    if (isDebug())
+        console.log(`[symbiote] ${message}`);
+}

package/build/dimensions/index.d.ts

@@ -0,0 +1,28 @@
+import { type IEventSubscription } from '../native-events';
+export interface IDisplayMetrics {
+    width: number;
+    height: number;
+    scale: number;
+    fontScale: number;
+}
+export interface IDisplayMetricsAndroid extends IDisplayMetrics {
+    densityDpi: number;
+}
+export interface IDimensionsPayload {
+    window?: IDisplayMetrics;
+    screen?: IDisplayMetrics;
+    windowPhysicalPixels?: IDisplayMetricsAndroid;
+    screenPhysicalPixels?: IDisplayMetricsAndroid;
+}
+export interface IDimensionsSet {
+    window: IDisplayMetrics;
+    screen: IDisplayMetrics;
+}
+export type IDimensionsKey = keyof IDimensionsSet;
+export type IDimensionsChangeListener = (set: IDimensionsSet) => void;
+export interface IDimensionsStatic {
+    get(dim: IDimensionsKey): IDisplayMetrics;
+    set(dims: IDimensionsPayload): void;
+    addEventListener(type: 'change', listener: IDimensionsChangeListener): IEventSubscription;
+}
+export declare const Dimensions: IDimensionsStatic;

package/build/dimensions/index.js

@@ -0,0 +1,148 @@
+// Screen metrics: a faithful, iOS-first port of React Native's
+// Libraries/Utilities/Dimensions.js. Native ships initial window/screen metrics in
+// the DeviceInfo module's getConstants().Dimensions, and pushes later updates (e.g.
+// rotation, font-scale change) through the device hub as a 'didUpdateDimensions'
+// event whose payload IS a fresh IDimensionsPayload. We cache the metrics and notify
+// 'change' listeners on each update, exactly as RN does.
+//
+// The native contract is confirmed from RN's TurboModule spec at
+// .vendors/.../specs_DEPRECATED/modules/INativeDeviceInfo.js:
+//   getConstants(): { Dimensions: { window?, screen?, windowPhysicalPixels?,
+//                     screenPhysicalPixels? } }
+// We resolve it through the same generic native-module bridge as Platform
+// (getNativeModule), so this module stays importable headless before a fake proxy
+// is installed.
+import { getNativeModule } from '../native-modules';
+import { installDeviceEventHub, NativeEventEmitter, } from '../native-events';
+import { dlog } from '../debug';
+// The native module name RN registers device metrics under.
+const DEVICE_INFO_MODULE = 'DeviceInfo';
+// The device event native emits when metrics change; its payload is a fresh
+// IDimensionsPayload (INativeDeviceInfo / Dimensions.js subscribe to this name).
+const DID_UPDATE_DIMENSIONS = 'didUpdateDimensions';
+// Used when the native module is unresolvable (headless, or a binary without it):
+// RN's getConstants() would throw, but a Dimensions read must never crash a render.
+// A scale of 1 is the neutral "non-retina" default PixelRatio falls back to.
+const DEFAULT_SCALE = 1;
+const ZERO_METRICS = {
+    width: 0,
+    height: 0,
+    scale: DEFAULT_SCALE,
+    fontScale: DEFAULT_SCALE,
+};
+// The trust boundary: native getConstants() crosses from an untyped HostObject into
+// our types here, behind a structural guard (no per-call cast). A shape that fails
+// the guard is treated as "module absent".
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function isDimensionsConstants(value) {
+    return isRecord(value) && isRecord(value.Dimensions);
+}
+function isDimensionsPayload(value) {
+    return isRecord(value);
+}
+const changeListeners = new Set();
+// Cached, resolved metrics. `undefined` = not yet set, so we know to swallow the
+// first 'change' (RN's dimensionsInitialized flag: native pushes an initial set we
+// must not surface as a change).
+let cached;
+// Derive point-space metrics from a payload, mirroring Dimensions.set(): the Android
+// *PhysicalPixels variants divide by scale into points; absent a screen, it mirrors
+// the window.
+function resolveMetrics(payload) {
+    let window = payload.window;
+    if (payload.windowPhysicalPixels !== undefined) {
+        window = toPointSpace(payload.windowPhysicalPixels);
+    }
+    let screen = payload.screen;
+    if (payload.screenPhysicalPixels !== undefined) {
+        screen = toPointSpace(payload.screenPhysicalPixels);
+    }
+    else if (screen === undefined) {
+        screen = window;
+    }
+    return {
+        window: window ?? ZERO_METRICS,
+        screen: screen ?? window ?? ZERO_METRICS,
+    };
+}
+function toPointSpace(pixels) {
+    return {
+        width: pixels.width / pixels.scale,
+        height: pixels.height / pixels.scale,
+        scale: pixels.scale,
+        fontScale: pixels.fontScale,
+    };
+}
+// Apply a fresh payload and notify 'change' subscribers, except the very first
+// set, which seeds the cache without firing (the initial native push is not a
+// "change"). This is the sink for both getConstants() and 'didUpdateDimensions'.
+function setDimensions(payload) {
+    const isFirst = cached === undefined;
+    cached = resolveMetrics(payload);
+    if (isFirst)
+        return;
+    dlog(`Dimensions: 'change' -> window ${cached.window.width}x${cached.window.height}`);
+    for (const listener of [...changeListeners])
+        listener(cached);
+}
+// Resolve initial metrics lazily and subscribe to native updates once. Re-attempts
+// on each call until a valid module is cached, so a later-installed DeviceInfo still
+// gets picked up (same pattern as platform.ts).
+let updateSubscription;
+function ensureResolved() {
+    if (cached !== undefined)
+        return cached;
+    // Subscribe BEFORE reading constants so an update fired in between isn't missed
+    // (RN orders the addListener before the getConstants call for the same reason).
+    if (updateSubscription === undefined) {
+        const module = getNativeModule(DEVICE_INFO_MODULE);
+        installDeviceEventHub();
+        const emitter = new NativeEventEmitter(undefined);
+        updateSubscription = emitter.addListener(DID_UPDATE_DIMENSIONS, payload => {
+            if (isDimensionsPayload(payload))
+                setDimensions(payload);
+        });
+        if (module === null) {
+            dlog('Dimensions: DeviceInfo not resolvable via native bridge — using zero metrics');
+        }
+        else {
+            const constants = module.getConstants();
+            if (isDimensionsConstants(constants)) {
+                dlog('Dimensions: resolved initial metrics from DeviceInfo.getConstants()');
+                setDimensions(constants.Dimensions);
+            }
+            else {
+                dlog('Dimensions: DeviceInfo.getConstants() returned an unexpected shape — using zero metrics');
+            }
+        }
+    }
+    return cached ?? { window: ZERO_METRICS, screen: ZERO_METRICS };
+}
+export const Dimensions = {
+    get(dim) {
+        return ensureResolved()[dim];
+    },
+    // RN exposes this as a public static (Dimensions.js:63); native pushes metrics
+    // through it. Delegates to the internal setter, which caches and fires 'change'.
+    set(dims) {
+        setDimensions(dims);
+    },
+    // `_type` is fixed to 'change' for RN signature parity; Dimensions emits no other.
+    addEventListener(_type, listener) {
+        // Resolve on first subscribe too, so the native update bridge is wired even if
+        // get() was never called first.
+        ensureResolved();
+        changeListeners.add(listener);
+        let removed = false;
+        return {
+            remove: () => {
+                if (removed)
+                    return;
+                removed = true;
+                changeListeners.delete(listener);
+            },
+        };
+    },
+};

package/build/dispatch.d.ts

@@ -0,0 +1,2 @@
+export declare function setEventDispatcher(wrap: (run: () => void) => void): void;
+export declare function runWrapped(run: () => void): void;

package/build/dispatch.js

@@ -0,0 +1,18 @@
+// The one place a native event re-enters a framework's update loop. A native
+// event (a touch from Fabric, a keyboard event from the device hub) runs its
+// listener (which may call setState) OUTSIDE the framework's own loop. The
+// adapter injects a wrapper that runs the listener at the right priority and
+// flushes synchronously so the result paints (React: discrete lane +
+// flushSyncWork). Both event rails, Fabric events (events.ts) and device-module
+// events (native-events.ts), route through this single seam, so the adapter
+// wires it once and both are covered. Default is a pass-through for adapters (and
+// the headless harness) that need no wrapping.
+let wrapDispatch = run => {
+    run();
+};
+export function setEventDispatcher(wrap) {
+    wrapDispatch = wrap;
+}
+export function runWrapped(run) {
+    wrapDispatch(run);
+}

package/build/events/index.d.ts

@@ -0,0 +1 @@
+export declare function installEventHandler(): void;