@smileid/usesmileid 12.0.0-beta01

package/src/l10n/use_smile_id_localizations_provider.tsx

@@ -0,0 +1,71 @@
+import { createContext, useContext, useMemo, type ReactNode } from "react";
+import { UseSmileIDLocalizations } from "./use_smile_id_localizations";
+
+/**
+ * React Context for the SDK's localized strings.
+ *
+ * `<UseSmileIDBuilder>` wraps its tree with this provider automatically
+ * when `configuration.localizations` is set. Partners who render SDK
+ * screens outside the orchestrator can wrap manually:
+ *
+ * ```tsx
+ * <UseSmileIDLocalizationsProvider value={localizations}>
+ *   <UseSmileIDConsentScreen partnerName="Acme" />
+ * </UseSmileIDLocalizationsProvider>
+ * ```
+ *
+ * Default value is an English-only `UseSmileIDLocalizations` so screens
+ * rendered without an explicit provider still display the canonical
+ * defaults rather than crashing with a "no provider" error.
+ */
+const UseSmileIDLocalizationsContext = createContext<UseSmileIDLocalizations>(
+  new UseSmileIDLocalizations(),
+);
+
+export type UseSmileIDLocalizationsProviderProps = {
+  readonly value: UseSmileIDLocalizations;
+  readonly children: ReactNode;
+};
+
+export function UseSmileIDLocalizationsProvider({
+  value,
+  children,
+}: UseSmileIDLocalizationsProviderProps) {
+  return (
+    <UseSmileIDLocalizationsContext.Provider value={value}>
+      {children}
+    </UseSmileIDLocalizationsContext.Provider>
+  );
+}
+
+/**
+ * Read the current `UseSmileIDLocalizations` from context. Returns the
+ * English-only default if no `<UseSmileIDLocalizationsProvider>`
+ * wraps the caller.
+ */
+export function useUseSmileIDLocalizations(): UseSmileIDLocalizations {
+  return useContext(UseSmileIDLocalizationsContext);
+}
+
+/**
+ * Memo helper for partners who construct a fresh `UseSmileIDLocalizations`
+ * from a locale-resolved overrides map on every render. Without this,
+ * the context value identity changes every render and every consumer
+ * re-renders. Concrete scenario: a partner reads
+ * `useUseSmileIDLocalizations()` in a deep tree of 50 SDK screens —
+ * the unmemoized provider would re-render the lot on every parent
+ * tick. Honest stub note: the SDK's screens are stubs today so the
+ * cost is theoretical; the helper still ships so the fix is in place
+ * before real screens land.
+ */
+export function useStableLocalizations(
+  overrides: Partial<Record<string, string>>,
+): UseSmileIDLocalizations {
+  // Concrete reliability: useMemo's dep is the overrides object
+  // identity. Partners passing a stable module-level constant get
+  // one instance; partners passing inline `{ … }` get a fresh
+  // instance per render — they should hoist to module scope. The
+  // helper does what it can; a fully stable cache isn't possible
+  // without a deep-equal which would be its own perf drag.
+  return useMemo(() => new UseSmileIDLocalizations(overrides), [overrides]);
+}

package/src/metadata/__tests__/use_smile_id_metadata.test.ts

@@ -0,0 +1,436 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+
+vi.mock("react-native", () => ({
+  Platform: { OS: "ios", Version: "17.4" },
+  Dimensions: {
+    get: (kind: "screen" | "window") =>
+      kind === "screen"
+        ? { width: 390, height: 844, scale: 3 }
+        : { width: 390, height: 844, scale: 3 },
+  },
+}));
+
+import {
+  UseSmileIDMetadata,
+  type UseSmileIDMetadataFields,
+} from "../use_smile_id_metadata";
+import { UseSmileIDMetadataFactory } from "../use_smile_id_metadata_factory";
+import type { SdkConfig } from "../../data/model/sdk_config";
+import { SdkConfigSource } from "../../data/model/sdk_config_source";
+
+// Minimum baseline — every conditional field empty / zero. The
+// only fields that survive `toEntries()` from this fixture are the
+// truly-always-present ones (SDK constants, sessionId, booleans, sdk_config_source).
+const baseFields: UseSmileIDMetadataFields = Object.freeze({
+  sdkVersion: "12.0.0",
+  sdk: "react-native-expo",
+  deviceOs: "",
+  deviceModel: "",
+  appName: "",
+  sessionId: "abc-123",
+  clientIp: "",
+  networkConnection: "",
+  carrierInfo: "",
+  proxy: false,
+  timezone: "",
+  locale: "",
+  screenResolution: "",
+  memoryInfoMb: 0,
+  deviceOrientation: "",
+  systemArchitecture: "",
+  numberOfCameras: 0,
+  hostApplication: "",
+  proximitySensor: false,
+  securityPolicyVersion: "12.0.0",
+  // sdk_config provenance — always-present (non-empty by construction).
+  sdkConfigSource: SdkConfigSource.defaultSource,
+  // Dimensions — zero in baseline fixture → omitted from entries.
+  imageWidth: 0,
+  imageHeight: 0,
+});
+
+describe("UseSmileIDMetadata.toEntries — standardized multipart wire format", () => {
+  it("always emits the always-present fields, including device_os / device_model / app_name even when empty", () => {
+    // `device_os`, `device_model`, and `app_name` are part of the
+    // always-present field set: they are emitted unconditionally (even
+    // when empty), alongside the SDK constants, the session UUID, and
+    // the booleans. `sdk_config_source` is also always-present.
+    const meta = new UseSmileIDMetadata(baseFields);
+    const names = meta.toEntries().map((e) => e.name);
+    expect(names).toEqual([
+      "sdk_version",
+      "sdk",
+      "device_os",
+      "device_model",
+      "app_name",
+      "session_id",
+      "proxy",
+      "proximity_sensor",
+      "security_policy_version",
+      "sdk_config_source",
+    ]);
+  });
+
+  it("emits device_os / device_model / app_name when populated", () => {
+    // Same fields that drop on empty must appear when populated —
+    // exact placement preserved (between `sdk` and `session_id`).
+    const meta = new UseSmileIDMetadata({
+      ...baseFields,
+      deviceOs: "iOS 17.4",
+      deviceModel: "Apple iPhone",
+      appName: "AcmeApp",
+    });
+    const names = meta.toEntries().map((e) => e.name);
+    expect(names).toEqual([
+      "sdk_version",
+      "sdk",
+      "device_os",
+      "device_model",
+      "app_name",
+      "session_id",
+      "proxy",
+      "proximity_sensor",
+      "security_policy_version",
+      "sdk_config_source",
+    ]);
+  });
+
+  it("omits empty conditional strings (concrete scenario: emulator with no carrier)", () => {
+    const meta = new UseSmileIDMetadata({
+      ...baseFields,
+      timezone: "",
+      locale: "",
+      carrierInfo: "",
+    });
+    const names = meta.toEntries().map((e) => e.name);
+    expect(names).not.toContain("timezone");
+    expect(names).not.toContain("locale");
+    expect(names).not.toContain("carrier_info");
+  });
+
+  it("omits zero-valued conditional integers (memory_info, number_of_cameras)", () => {
+    // Concrete scenario: RN can't read `memory_info` without
+    // `expo-device` so the default is 0. The wire format must NOT
+    // ship `memory_info: 0` — it should be absent. Pin the contract.
+    const meta = new UseSmileIDMetadata({
+      ...baseFields,
+      memoryInfoMb: 0,
+      numberOfCameras: 0,
+    });
+    const names = meta.toEntries().map((e) => e.name);
+    expect(names).not.toContain("memory_info");
+    expect(names).not.toContain("number_of_cameras");
+  });
+
+  it("emits non-empty conditionals between the booleans and the trailer", () => {
+    const meta = new UseSmileIDMetadata({
+      ...baseFields,
+      // Populate the upper-conditional triple so the canonical
+      // "fully populated" order shows.
+      deviceOs: "iOS 17.4",
+      deviceModel: "Apple iPhone",
+      appName: "AcmeApp",
+      timezone: "America/New_York",
+      locale: "en-US",
+      memoryInfoMb: 4096,
+      numberOfCameras: 2,
+    });
+    const names = meta.toEntries().map((e) => e.name);
+    expect(names).toEqual([
+      "sdk_version",
+      "sdk",
+      "device_os",
+      "device_model",
+      "app_name",
+      "session_id",
+      "proxy",
+      "proximity_sensor",
+      "timezone",
+      "locale",
+      "memory_info",
+      "number_of_cameras",
+      "security_policy_version",
+      "sdk_config_source",
+    ]);
+  });
+
+  it('stringifies booleans as "true" / "false" (wire-format contract)', () => {
+    // Concrete scenario: a JSON parser receiving native bool would
+    // need a different schema than other entries. The wire contract
+    // is `value: string` for every entry; booleans are stringified.
+    const meta = new UseSmileIDMetadata({
+      ...baseFields,
+      proxy: true,
+      proximitySensor: false,
+    });
+    const entries = meta.toEntries();
+    expect(entries.find((e) => e.name === "proxy")).toEqual({
+      name: "proxy",
+      value: "true",
+    });
+    expect(entries.find((e) => e.name === "proximity_sensor")).toEqual({
+      name: "proximity_sensor",
+      value: "false",
+    });
+  });
+
+  it("returns a frozen array — partners can`t mutate the snapshot", () => {
+    const meta = new UseSmileIDMetadata(baseFields);
+    const entries = meta.toEntries();
+    expect(Object.isFrozen(entries)).toBe(true);
+  });
+});
+
+describe("UseSmileIDMetadataFactory", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("caches sessionId across make() calls — one session per factory", () => {
+    // Concrete scenario: a flow makes auth → submit → status calls in
+    // sequence. All three must carry the SAME session_id so partner
+    // analytics can correlate them.
+    const factory = new UseSmileIDMetadataFactory();
+    const a = factory.make().toFields().sessionId;
+    const b = factory.make().toFields().sessionId;
+    expect(a).toBe(b);
+    expect(a).toMatch(/[0-9a-f-]{8,}/);
+  });
+
+  it("mints a new sessionId for a new factory instance", () => {
+    const f1 = new UseSmileIDMetadataFactory();
+    const f2 = new UseSmileIDMetadataFactory();
+    expect(f1.make().toFields().sessionId).not.toBe(
+      f2.make().toFields().sessionId,
+    );
+  });
+
+  it("resolves device_os from Platform.OS + Platform.Version", () => {
+    const factory = new UseSmileIDMetadataFactory();
+    expect(factory.make().toFields().deviceOs).toBe("iOS 17.4");
+  });
+
+  it('always emits sdk = "react-native-expo" — matches the auth header `smileid-source-sdk`', () => {
+    // Concrete scenario: partner analytics groups submissions by
+    // SDK identifier. Drift on this value would split the RN bucket
+    // across multiple identifiers (e.g. metadata says `react_native`
+    // while the auth header says `react-native-expo` — same fleet,
+    // two buckets).
+    const factory = new UseSmileIDMetadataFactory();
+    expect(factory.make().toFields().sdk).toBe("react-native-expo");
+  });
+
+  it("resolves screen_resolution as physical pixels with the × separator", () => {
+    // Format: `<w> × <h>` with the U+00D7 multiplication sign
+    // (not ASCII `x`). Pin so a future refactor doesn't accidentally
+    // use ASCII.
+    const factory = new UseSmileIDMetadataFactory();
+    expect(factory.make().toFields().screenResolution).toBe("1170 × 2532");
+  });
+
+  it("resolves device_orientation from Dimensions(window) aspect", () => {
+    const factory = new UseSmileIDMetadataFactory();
+    expect(factory.make().toFields().deviceOrientation).toBe("Portrait");
+  });
+
+  it("passes appName / hostApplication through from constructor options", () => {
+    const factory = new UseSmileIDMetadataFactory({
+      appName: "AcmeApp",
+      hostApplication: "AcmeApp v2.0.1",
+    });
+    const f = factory.make().toFields();
+    expect(f.appName).toBe("AcmeApp");
+    expect(f.hostApplication).toBe("AcmeApp v2.0.1");
+  });
+
+  it("produces a wire-format array that drops empty / zero fields", () => {
+    // End-to-end: the factory's defaults leave several fields empty
+    // (no native-bridge access). Those must NOT appear in the wire
+    // payload. Concrete scenario: a partner running RN inside an
+    // emulator would otherwise send a payload with empty
+    // `device_model`, `host_application`, `client_ip`, etc.
+    const factory = new UseSmileIDMetadataFactory();
+    const names = factory
+      .make()
+      .toEntries()
+      .map((e) => e.name);
+    expect(names).not.toContain("client_ip");
+    expect(names).not.toContain("network_connection");
+    expect(names).not.toContain("carrier_info");
+    expect(names).not.toContain("memory_info");
+    expect(names).not.toContain("number_of_cameras");
+    expect(names).not.toContain("host_application");
+    // device_os / device_model / app_name are always-present and emitted
+    // even at their empty factory defaults.
+    expect(names).toContain("device_os");
+    expect(names).toContain("device_model");
+    expect(names).toContain("app_name");
+    // sdk_config_source is always-present (non-empty string by construction).
+    expect(names).toContain("sdk_config_source");
+    // image_width / image_height are emitted when > 0.
+    // Factory defaults to 480 × 640 so they appear without an sdkConfig override.
+    expect(names).toContain("image_width");
+    expect(names).toContain("image_height");
+  });
+});
+
+describe("UseSmileIDMetadata.toEntries — device-integrity fields", () => {
+  const valueByName = (meta: UseSmileIDMetadata): Record<string, string> =>
+    Object.fromEntries(meta.toEntries().map((e) => [e.name, e.value]));
+
+  it("omits every attestation field before the warm-up resolves", () => {
+    const names = new UseSmileIDMetadata(baseFields)
+      .toEntries()
+      .map((e) => e.name);
+    expect(names).not.toContain("supports_hardware_attestation");
+    expect(names).not.toContain("attestation_certificate_chain");
+    expect(names).not.toContain("supports_app_attest");
+  });
+
+  it("emits supports_hardware_attestation as the security-level integer", () => {
+    // StrongBox-backed key → KeyInfo.getSecurityLevel() === 2.
+    const values = valueByName(
+      new UseSmileIDMetadata({
+        ...baseFields,
+        hardwareAttestationSecurityLevel: 2,
+      }),
+    );
+    expect(values.supports_hardware_attestation).toBe("2");
+  });
+
+  it("emits security level -2 (unknown) for an unsupported device", () => {
+    const values = valueByName(
+      new UseSmileIDMetadata({
+        ...baseFields,
+        hardwareAttestationSecurityLevel: -2,
+      }),
+    );
+    expect(values.supports_hardware_attestation).toBe("-2");
+  });
+
+  it("serialises the certificate chain as a JSON-array string", () => {
+    const values = valueByName(
+      new UseSmileIDMetadata({
+        ...baseFields,
+        hardwareAttestationSecurityLevel: 1,
+        attestationCertificateChain: ["certA", "certB"],
+      }),
+    );
+    expect(values.attestation_certificate_chain).toBe('["certA","certB"]');
+  });
+
+  it("omits the certificate chain when empty even if level present", () => {
+    const names = new UseSmileIDMetadata({
+      ...baseFields,
+      hardwareAttestationSecurityLevel: 0,
+      attestationCertificateChain: [],
+    })
+      .toEntries()
+      .map((e) => e.name);
+    expect(names).toContain("supports_hardware_attestation");
+    expect(names).not.toContain("attestation_certificate_chain");
+  });
+
+  it("emits supports_app_attest as a boolean string", () => {
+    expect(
+      valueByName(
+        new UseSmileIDMetadata({ ...baseFields, supportsAppAttest: true }),
+      ).supports_app_attest,
+    ).toBe("true");
+    expect(
+      valueByName(
+        new UseSmileIDMetadata({ ...baseFields, supportsAppAttest: false }),
+      ).supports_app_attest,
+    ).toBe("false");
+  });
+});
+
+describe("UseSmileIDMetadata.toEntries — sdk_config provenance", () => {
+  const valueByName = (meta: UseSmileIDMetadata): Record<string, string> =>
+    Object.fromEntries(meta.toEntries().map((e) => [e.name, e.value]));
+
+  it("always emits sdk_config_source — the backend gates its dimension-consistency check on this", () => {
+    const names = new UseSmileIDMetadata(baseFields)
+      .toEntries()
+      .map((e) => e.name);
+    expect(names).toContain("sdk_config_source");
+  });
+
+  it('emits sdk_config_source = "default" from the baseline fixture', () => {
+    expect(
+      valueByName(new UseSmileIDMetadata(baseFields)).sdk_config_source,
+    ).toBe("default");
+  });
+
+  it('emits sdk_config_source = "sdk_config" when the field is set', () => {
+    const meta = new UseSmileIDMetadata({
+      ...baseFields,
+      sdkConfigSource: SdkConfigSource.sdkConfig,
+      imageWidth: 640,
+      imageHeight: 480,
+    });
+    expect(valueByName(meta).sdk_config_source).toBe("sdk_config");
+  });
+
+  it("emits image_width and image_height when > 0", () => {
+    const values = valueByName(
+      new UseSmileIDMetadata({
+        ...baseFields,
+        sdkConfigSource: SdkConfigSource.sdkConfig,
+        imageWidth: 640,
+        imageHeight: 480,
+      }),
+    );
+    expect(values["image_width"]).toBe("640");
+    expect(values["image_height"]).toBe("480");
+  });
+
+  it("omits image_width and image_height when zero (fallback to SDK defaults not set)", () => {
+    // baseFields has imageWidth: 0 / imageHeight: 0 — these must be absent
+    // from the wire payload so the server doesn't see an explicit zero.
+    const names = new UseSmileIDMetadata(baseFields)
+      .toEntries()
+      .map((e) => e.name);
+    expect(names).not.toContain("image_width");
+    expect(names).not.toContain("image_height");
+  });
+});
+
+describe("UseSmileIDMetadataFactory — sdk_config provenance", () => {
+  it('defaults to sdk_config_source = "default" when make() is called without sdkConfig', () => {
+    const factory = new UseSmileIDMetadataFactory();
+    const fields = factory.make().toFields();
+    expect(fields.sdkConfigSource).toBe(SdkConfigSource.defaultSource);
+  });
+
+  it("defaults image_width / image_height to the SDK defaults (480 × 640) when make() has no sdkConfig", () => {
+    const factory = new UseSmileIDMetadataFactory();
+    const fields = factory.make().toFields();
+    // SDK defaults: 480 × 640 — the canonical selfie capture size.
+    expect(fields.imageWidth).toBe(480);
+    expect(fields.imageHeight).toBe(640);
+  });
+
+  it('emits sdk_config_source = "sdk_config" when sdkConfig is supplied with valid selfie dimensions', () => {
+    const factory = new UseSmileIDMetadataFactory();
+    const sdkConfig: SdkConfig = {
+      selfie: { width: 640, height: 480 },
+    };
+    const fields = factory.make(sdkConfig).toFields();
+    expect(fields.sdkConfigSource).toBe(SdkConfigSource.sdkConfig);
+    expect(fields.imageWidth).toBe(640);
+    expect(fields.imageHeight).toBe(480);
+  });
+
+  it('emits sdk_config_source = "sdk_config" and falls back to defaults when pair rule fails', () => {
+    // Pair rule: both width AND height must be > 0; width-only fails.
+    // sdkConfig is still defined so source = "sdk_config", but dims fall back.
+    const factory = new UseSmileIDMetadataFactory();
+    const sdkConfig: SdkConfig = { selfie: { width: 640 } };
+    const fields = factory.make(sdkConfig).toFields();
+    expect(fields.sdkConfigSource).toBe(SdkConfigSource.sdkConfig);
+    // SDK default dimensions should apply when pair rule fails.
+    expect(fields.imageWidth).toBe(480);
+    expect(fields.imageHeight).toBe(640);
+  });
+});

package/src/metadata/document_image_origin.ts

@@ -0,0 +1,22 @@
+/**
+ * How a captured document side was produced, emitted per side in submission
+ * metadata. The string values are the wire contract — do not localize or abbreviate.
+ */
+export const DocumentImageOrigin = {
+  /** Captured automatically by the native detection pipeline. */
+  CameraAutoCapture: "CameraAutoCapture",
+  /** Captured by an explicit shutter tap. */
+  CameraManualCapture: "CameraManualCapture",
+  /** Imported from the device photo library. */
+  Gallery: "Gallery",
+} as const;
+
+export type DocumentImageOrigin =
+  (typeof DocumentImageOrigin)[keyof typeof DocumentImageOrigin];
+
+/**
+ * Per-side document-origin wire keys. PascalCase per the v11 metadata contract —
+ * fixed by the wire format, distinct from the snake_case device-metadata keys.
+ */
+export const DOCUMENT_FRONT_IMAGE_ORIGIN_KEY = "DocumentFrontImageOrigin";
+export const DOCUMENT_BACK_IMAGE_ORIGIN_KEY = "DocumentBackImageOrigin";

package/src/metadata/optional_native_modules.ts

@@ -0,0 +1,120 @@
+/**
+ * Lazy bridges to optional `expo-device` / `expo-network` peer deps.
+ * Both are declared `optional: true` in `peerDependenciesMeta` so
+ * partners who don't need richer metadata don't pay the install cost.
+ *
+ * **Pattern:** dynamic `require()` wrapped in `try/catch`. Metro
+ * tolerates the missing-module case without failing the build —
+ * resolution attempts at runtime, the catch swallows the failure,
+ * and the metadata factory falls back to empty / zero defaults.
+ *
+ * Concrete scenario this prevents: a hard `import` would fail the
+ * bundle for every partner, even those who don't want richer
+ * metadata. The optional peer + try/require pattern keeps the
+ * default install footprint minimal.
+ */
+
+type DeviceModule = {
+  readonly modelName?: string | null;
+  readonly brand?: string | null;
+  readonly supportedCpuArchitectures?: readonly string[] | null;
+  readonly totalMemory?: number | null;
+};
+
+type NetworkModule = {
+  getNetworkStateAsync(): Promise<{
+    readonly type?: string | null;
+    readonly isConnected?: boolean | null;
+    readonly isInternetReachable?: boolean | null;
+  }>;
+  getIpAddressAsync?(): Promise<string>;
+};
+
+let _device: DeviceModule | null | undefined;
+let _network: NetworkModule | null | undefined;
+
+/**
+ * Load `expo-device`'s native module once, cached for the process
+ * lifetime. Returns `null` if the native module isn't linked into
+ * the host app (graceful degradation).
+ *
+ * **Why bypass `require("expo-device")`:** `expo-device`'s entry
+ * (`Device.js`) does `import ExpoDevice from './ExpoDevice'`, which
+ * evaluates `ExpoDevice.js` whose top-level statement is
+ * `export default requireNativeModule('ExpoDevice')`. The
+ * **throwing** variant — `requireNativeModule` throws "Cannot find
+ * native module 'ExpoDevice'" synchronously when the native side
+ * isn't linked. Concrete scenario this caused: pnpm-hoisted
+ * `expo-device` JS at the workspace root was reachable from a host
+ * app's Metro bundle even though the host app didn't link the native
+ * module. The throw at module init bypassed every try/catch we
+ * wrapped the require in.
+ *
+ * The fix: skip `expo-device`'s entry entirely. Pull the native
+ * module via `expo-modules-core`'s `requireOptionalNativeModule`,
+ * which returns `null` instead of throwing. The raw native module
+ * exposes the same fields (`brand`, `modelName`,
+ * `supportedCpuArchitectures`, `totalMemory`) that
+ * `expo-device/Device.js` re-exports — see `expo-device`'s
+ * native-module schema in `node_modules/expo-device/build/Device.js`.
+ * `expo-modules-core` is a transitive dep of `expo` so it's always
+ * present in any Expo app.
+ */
+export function loadExpoDevice(): DeviceModule | null {
+  if (_device !== undefined) return _device;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const core = require("expo-modules-core") as {
+      requireOptionalNativeModule?: <T>(name: string) => T | null;
+    };
+    _device =
+      core.requireOptionalNativeModule?.<DeviceModule>("ExpoDevice") ?? null;
+  } catch {
+    _device = null;
+  }
+  return _device;
+}
+
+/**
+ * Load `expo-network`'s native module once, cached for the process
+ * lifetime. Returns `null` if the native module isn't linked into the
+ * host app (graceful degradation).
+ *
+ * **Why bypass `require("expo-network")`:** like `expo-device`, its
+ * entry (`Network.js`) imports `./ExpoNetwork`, whose top-level
+ * statement is `requireNativeModule('ExpoNetwork')` — the **throwing**
+ * variant that raises "Cannot find native module 'ExpoNetwork'"
+ * synchronously at module init when the native side isn't linked. That
+ * throw fires during Metro's module evaluation and bypasses a
+ * `try/catch` wrapped around the `require`, so a host app that reaches
+ * the pnpm-hoisted `expo-network` JS without linking the native module
+ * crashes on construction. The fix mirrors `loadExpoDevice`: pull the
+ * raw native module via `expo-modules-core`'s
+ * `requireOptionalNativeModule`, which returns `null` instead of
+ * throwing. The raw module exposes `getNetworkStateAsync` /
+ * `getIpAddressAsync` directly — the same methods `expo-network`'s
+ * `Network.js` calls on it.
+ *
+ * Note: `getNetworkStateAsync()` is async — the factory warms it up
+ * fire-and-forget and falls back to empty defaults until it settles.
+ */
+export function loadExpoNetwork(): NetworkModule | null {
+  if (_network !== undefined) return _network;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const core = require("expo-modules-core") as {
+      requireOptionalNativeModule?: <T>(name: string) => T | null;
+    };
+    _network =
+      core.requireOptionalNativeModule?.<NetworkModule>("ExpoNetwork") ?? null;
+  } catch {
+    _network = null;
+  }
+  return _network;
+}
+
+/** Test-only seam — clears the module cache so tests can re-evaluate. */
+export function _resetOptionalModulesForTesting(): void {
+  _device = undefined;
+  _network = undefined;
+}