@variantlab/react-native 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,322 @@
+export { UseExperimentResult, Variant, VariantErrorBoundary, VariantErrorBoundaryProps, VariantLabContext, VariantLabProvider, VariantLabProviderProps, VariantProps, VariantValue, VariantValueProps, useExperiment, useRouteExperiments, useSetVariant, useVariant, useVariantLabEngine, useVariantValue } from '@variantlab/react';
+import { VariantContext, VariantEngine } from '@variantlab/core';
+import { V as ValidationResult, S as SharePayload, a as ValidationFailure } from './types-CnSyez2D.cjs';
+export { b as ShareVersion } from './types-CnSyez2D.cjs';
+
+/**
+ * `getAutoContext()` — best-effort detection of the runtime context
+ * for variantlab targeting on React Native.
+ *
+ * The goal is to fill in `platform`, `screenSize`, and `locale` from
+ * native modules so that targeting like `{ platform: ["ios"] }` and
+ * `{ screenSize: ["small"] }` Just Works without the user having to
+ * import any RN modules themselves. `appVersion` is filled in when
+ * `expo-constants` is installed (it almost always is on Expo apps).
+ *
+ * Implementation rules:
+ *
+ *   - Every native module is imported through a guarded `try / require`
+ *     so a missing optional peer never crashes. Failing to read any
+ *     individual field returns `undefined` for that field — never throws.
+ *   - The function is **synchronous** because variantlab's resolution
+ *     hot path is synchronous; we cannot wait on a Promise here.
+ *   - Locale detection prefers `expo-localization` (the only RN-supported
+ *     way that works in production). Falls back to `NativeModules` for
+ *     bare RN apps and finally to `undefined`.
+ *
+ * The screen-size buckets follow the same thresholds as the rest of
+ * variantlab (see `targeting-dsl.md`):
+ *
+ *   - small  → < 360 pt wide  (iPhone SE, older Androids)
+ *   - medium → 360–767 pt wide (most phones)
+ *   - large  → ≥ 768 pt wide (tablets, foldables in unfolded mode)
+ */
+
+interface AutoContextOptions {
+    /** Inject `expo-constants` for `appVersion`. Optional. */
+    readonly constants?: {
+        expoConfig?: {
+            version?: string;
+        } | null;
+    } | null;
+    /** Inject `expo-localization` for `locale`. Optional. */
+    readonly localization?: {
+        getLocales: () => Array<{
+            languageTag: string;
+        }>;
+    } | null;
+}
+declare function getAutoContext(options?: AutoContextOptions): VariantContext;
+type ScreenSizeBucket = NonNullable<VariantContext["screenSize"]>;
+declare function bucketScreenWidth(width: number): ScreenSizeBucket;
+
+/**
+ * Encode and decode share payloads for deep links and QR codes.
+ *
+ * The wire format is documented in `docs/features/qr-sharing.md`:
+ *
+ *   1. Serialise the payload as compact JSON.
+ *   2. Optionally gzip-like compress (deferred — we ship plain base64
+ *      first; the wire format is forward-compatible because the prefix
+ *      byte tells the decoder which mode was used).
+ *   3. Base64url-encode the bytes (RFC 4648 §5: `+` → `-`, `/` → `_`,
+ *      no `=` padding).
+ *
+ * We implement base64url by hand because we cannot rely on
+ * `globalThis.btoa` / `Buffer` being present on every RN runtime,
+ * and pulling in a base64 polyfill would burst the bundle budget.
+ * The encoder/decoder operates on UTF-8 byte arrays via `TextEncoder`
+ * / `TextDecoder`, both of which ship in Hermes.
+ *
+ * The format prefix byte is `0` for "raw JSON" and reserved for future
+ * compression schemes (`1` = deflate-raw, `2` = brotli, etc.). On
+ * decode we tolerate a missing prefix to keep older clients working.
+ */
+
+/**
+ * Encode a payload to its on-the-wire base64url string. Throws on
+ * the rare case where validation fails on a payload constructed by
+ * the caller themselves — that's a developer error worth surfacing.
+ */
+declare function encodeSharePayload(payload: SharePayload): string;
+/**
+ * Decode a base64url string back into a validated payload. Returns
+ * a `ValidationResult` so callers can branch on `ok` rather than
+ * wrap the call in try/catch.
+ */
+declare function decodeSharePayload(encoded: string, now?: number): ValidationResult;
+declare function bytesToBase64Url(bytes: Uint8Array): string;
+declare function base64UrlToBytes(input: string): Uint8Array;
+
+/**
+ * Deep link handler for variantlab share payloads.
+ *
+ * Wires React Native's `Linking` module to the engine: when the OS
+ * delivers a URL with our share scheme, we decode the `?p=...` query
+ * parameter, validate it, and apply the overrides.
+ *
+ * Design notes:
+ *
+ *   - The handler accepts the engine *and* the `Linking` module from
+ *     the caller. In a real app the caller passes `Linking` from
+ *     `react-native`; in tests the caller passes a mock that records
+ *     `addEventListener` and `getInitialURL` calls. This keeps the
+ *     module free of any real RN imports for the test runner.
+ *   - URL parsing is hand-rolled because RN's `URL` polyfill is
+ *     unreliable across versions and we only need to extract one
+ *     query param.
+ *   - Each apply emits via `engine.setVariant(id, variantId, "deeplink")`
+ *     so the source field on `variantChanged` events lets debug overlays
+ *     and telemetry distinguish deep-link writes from manual ones.
+ *   - We rate-limit deep-link applies to one per second by default
+ *     (`qr-sharing.md` §Rate limiting). Callers can override the
+ *     interval but cannot disable it entirely.
+ */
+
+/** The minimal Linking surface we depend on. */
+interface LinkingLike {
+    addEventListener(type: "url", handler: (event: {
+        url: string;
+    }) => void): {
+        remove: () => void;
+    };
+    getInitialURL(): Promise<string | null>;
+}
+interface RegisterDeepLinkOptions {
+    /** App URL scheme, e.g. `"drishtikon"`. Required to filter foreign URLs. */
+    readonly scheme?: string;
+    /** Optional host portion, e.g. `"variantlab"`. Defaults to any host. */
+    readonly host?: string;
+    /** Query parameter holding the encoded payload. Default: `"p"`. */
+    readonly param?: string;
+    /** Called after each successful apply with the decoded payload. */
+    readonly onApply?: (payload: SharePayload) => void;
+    /** Called whenever a candidate link fails validation. */
+    readonly onError?: (reason: ValidationFailure | "wrong-scheme" | "no-payload") => void;
+    /** Minimum ms between successful applies. Default: 1000. */
+    readonly minIntervalMs?: number;
+}
+/**
+ * Register the deep-link handler. Returns an unsubscribe function
+ * that removes the listener and stops handling pending initial URLs.
+ *
+ * The handler also fires once for the URL that launched the app
+ * (via `getInitialURL`) so cold-launches via QR scan still apply
+ * the override on first render.
+ */
+declare function registerDeepLinkHandler(engine: VariantEngine, linking: LinkingLike, options?: RegisterDeepLinkOptions): () => void;
+/**
+ * Apply a previously-decoded payload to the engine. Exposed publicly
+ * so callers that build their own URL-handling pipeline (Next.js
+ * middleware, web router) can reuse the same logic.
+ */
+declare function applyPayload(engine: VariantEngine, payload: SharePayload): void;
+
+/**
+ * Validate a candidate share payload before applying it.
+ *
+ * Share payloads come from untrusted input — a deep link, a QR code,
+ * a clipboard paste — so we treat them as adversarial. The validator
+ * walks the structure with `Object.create(null)` semantics in mind:
+ *
+ *   - Reject prototype-pollution keys (`__proto__`, `constructor`,
+ *     `prototype`) anywhere in the tree.
+ *   - Enforce strict id regexes on every override key/value so a
+ *     malformed payload cannot smuggle non-printable bytes into a
+ *     `setVariant` call.
+ *   - Cap the override count and total decoded size to bound memory.
+ *   - Honor an optional `expires` field so QR codes shared earlier
+ *     in the day cannot be replayed forever.
+ *
+ * The validator returns a `ValidationResult` discriminated union
+ * instead of throwing because callers (deep-link handler, QR scanner)
+ * almost always want to silently surface a failure to the UI rather
+ * than treat it as a runtime error.
+ */
+
+declare function validatePayload(input: unknown, now?: number): ValidationResult;
+
+/**
+ * The pluggable storage interface used by every adapter in this package.
+ *
+ * Mirrors the surface in `API.md` §`Storage interface` so that callers
+ * can persist engine overrides to whichever native KV store fits their
+ * app — AsyncStorage by default, MMKV when bundle/perf matter, or
+ * SecureStore when the override list itself is sensitive.
+ *
+ * Methods may be sync or async to match the underlying backing store.
+ * `@variantlab/core` does not yet wire this into `EngineOptions`; for
+ * now adapters expose them as standalone factories so that callers can
+ * implement persistence at the app boundary (e.g. by serialising
+ * `engine.getHistory()` after every `variantChanged` event).
+ */
+interface Storage {
+    getItem(key: string): string | null | Promise<string | null>;
+    setItem(key: string, value: string): void | Promise<void>;
+    removeItem(key: string): void | Promise<void>;
+    /** Optional bulk-key listing for debug overlay export and tests. */
+    keys?(): string[] | Promise<string[]>;
+    /** Optional clear-all helper used by `engine.resetAll()` integrations. */
+    clear?(): void | Promise<void>;
+}
+/** Prefix every variantlab key with this so storage stays sandboxed. */
+declare const STORAGE_KEY_PREFIX = "variantlab:";
+/** Build a fully-qualified storage key from a logical name. */
+declare function buildKey(name: string): string;
+
+/**
+ * `Storage` adapter backed by `@react-native-async-storage/async-storage`.
+ *
+ * AsyncStorage is the de-facto standard KV store on React Native and
+ * the only one we recommend by default — it's bundled with every
+ * Expo project, ships in the New Architecture, and works on iOS,
+ * Android, web, and tvOS. It is, however, async on every method, so
+ * the returned `Storage` is a fully async implementation.
+ *
+ * The adapter is constructed lazily: callers pass in their AsyncStorage
+ * module rather than us importing it. This keeps `@variantlab/react-native`
+ * itself free of any RN package imports at module load — the user's
+ * bundler resolves the peer, we never see it. The factory accepts the
+ * module directly so the surface is dependency-injected and trivially
+ * testable.
+ */
+
+/** Subset of `AsyncStorageStatic` we actually use. */
+interface AsyncStorageLike {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+    getAllKeys(): Promise<readonly string[]>;
+    clear?(): Promise<void>;
+}
+declare function createAsyncStorageAdapter(asyncStorage: AsyncStorageLike): Storage;
+
+/**
+ * In-memory `Storage` implementation. Useful for tests, SSR fallbacks,
+ * and any code path where the host platform's native KV is unavailable.
+ *
+ * The implementation is intentionally trivial: a `Map` keyed on the
+ * fully-qualified key, no namespacing logic, no async wrappers. Real
+ * adapters wrap a native module and may be async; this one is sync to
+ * keep tests deterministic.
+ */
+
+declare function createMemoryStorage(): Storage;
+
+/**
+ * `Storage` adapter backed by `react-native-mmkv`.
+ *
+ * MMKV is a fully synchronous KV store implemented in C++ on top of
+ * mmap. It's the fastest option on RN by a wide margin and is
+ * particularly nice for variantlab because variant resolution is
+ * synchronous on the hot path — using MMKV means storage round trips
+ * never block on a JS-bridge call.
+ *
+ * Like `async-storage`, the underlying instance is dependency-injected
+ * rather than imported here. The caller constructs an `MMKV` instance
+ * (typically with their own `id` namespace and optional encryption key)
+ * and hands it in. We only require a tiny subset of the surface so
+ * users can also pass any compatible mock in tests.
+ */
+
+/** Subset of the real MMKV instance we depend on. */
+interface MMKVLike {
+    set(key: string, value: string): void;
+    getString(key: string): string | undefined;
+    contains(key: string): boolean;
+    delete(key: string): void;
+    getAllKeys(): string[];
+    clearAll?(): void;
+}
+declare function createMMKVStorageAdapter(mmkv: MMKVLike): Storage;
+
+/**
+ * `Storage` adapter backed by `expo-secure-store`.
+ *
+ * SecureStore writes through to Keychain (iOS) and the EncryptedSharedPreferences
+ * /Keystore pair (Android). It's appropriate when the override payload
+ * is itself sensitive — e.g. an experiment that toggles an internal
+ * staging endpoint, an enterprise feature flag, or a beta-channel key.
+ *
+ * SecureStore has two notable constraints:
+ *
+ *   1. **No bulk key listing.** The native API does not expose a
+ *      "list every key" operation, so `keys()` is intentionally absent.
+ *      Callers that need bulk operations should layer an index in a
+ *      separate AsyncStorage entry, or compose with `createMemoryStorage`.
+ *   2. **Slow on Android.** Each read/write hits the native module.
+ *      Don't use this on hot paths where latency matters.
+ *
+ * As with the other adapters, the upstream module is injected so this
+ * file imports nothing from `expo-secure-store` itself.
+ */
+
+/** Subset of the real `expo-secure-store` namespace we use. */
+interface SecureStoreLike {
+    getItemAsync(key: string): Promise<string | null>;
+    setItemAsync(key: string, value: string): Promise<void>;
+    deleteItemAsync(key: string): Promise<void>;
+}
+declare function createSecureStoreAdapter(secureStore: SecureStoreLike): Storage;
+
+/**
+ * `@variantlab/react-native` — public barrel.
+ *
+ * This entrypoint deliberately **re-exports everything** from
+ * `@variantlab/react` so a React Native app can
+ *
+ *     import { VariantLabProvider, useVariant } from "@variantlab/react-native";
+ *
+ * without the user having to remember that the hook layer lives in
+ * the web-React package. The hooks and components are 100% compatible
+ * with React Native — they rely only on React's own APIs.
+ *
+ * RN-specific surface sits alongside: storage adapters, auto-context
+ * detection, and the deep-link handler. The debug overlay and the
+ * QR helpers are intentionally split into their own sub-entrypoints
+ * (`/debug`, `/qr`) so tree-shaking works at the package level:
+ * production bundles that never import `/debug` do not pay for it.
+ */
+declare const VERSION = "0.0.0";
+
+export { type AsyncStorageLike, type AutoContextOptions, type LinkingLike, type MMKVLike, type RegisterDeepLinkOptions, STORAGE_KEY_PREFIX, type ScreenSizeBucket, type SecureStoreLike, SharePayload, type Storage, VERSION, ValidationFailure, ValidationResult, applyPayload, base64UrlToBytes, bucketScreenWidth, buildKey, bytesToBase64Url, createAsyncStorageAdapter, createMMKVStorageAdapter, createMemoryStorage, createSecureStoreAdapter, decodeSharePayload, encodeSharePayload, getAutoContext, registerDeepLinkHandler, validatePayload };

package/dist/index.d.ts

@@ -0,0 +1,322 @@
+export { UseExperimentResult, Variant, VariantErrorBoundary, VariantErrorBoundaryProps, VariantLabContext, VariantLabProvider, VariantLabProviderProps, VariantProps, VariantValue, VariantValueProps, useExperiment, useRouteExperiments, useSetVariant, useVariant, useVariantLabEngine, useVariantValue } from '@variantlab/react';
+import { VariantContext, VariantEngine } from '@variantlab/core';
+import { V as ValidationResult, S as SharePayload, a as ValidationFailure } from './types-CnSyez2D.js';
+export { b as ShareVersion } from './types-CnSyez2D.js';
+
+/**
+ * `getAutoContext()` — best-effort detection of the runtime context
+ * for variantlab targeting on React Native.
+ *
+ * The goal is to fill in `platform`, `screenSize`, and `locale` from
+ * native modules so that targeting like `{ platform: ["ios"] }` and
+ * `{ screenSize: ["small"] }` Just Works without the user having to
+ * import any RN modules themselves. `appVersion` is filled in when
+ * `expo-constants` is installed (it almost always is on Expo apps).
+ *
+ * Implementation rules:
+ *
+ *   - Every native module is imported through a guarded `try / require`
+ *     so a missing optional peer never crashes. Failing to read any
+ *     individual field returns `undefined` for that field — never throws.
+ *   - The function is **synchronous** because variantlab's resolution
+ *     hot path is synchronous; we cannot wait on a Promise here.
+ *   - Locale detection prefers `expo-localization` (the only RN-supported
+ *     way that works in production). Falls back to `NativeModules` for
+ *     bare RN apps and finally to `undefined`.
+ *
+ * The screen-size buckets follow the same thresholds as the rest of
+ * variantlab (see `targeting-dsl.md`):
+ *
+ *   - small  → < 360 pt wide  (iPhone SE, older Androids)
+ *   - medium → 360–767 pt wide (most phones)
+ *   - large  → ≥ 768 pt wide (tablets, foldables in unfolded mode)
+ */
+
+interface AutoContextOptions {
+    /** Inject `expo-constants` for `appVersion`. Optional. */
+    readonly constants?: {
+        expoConfig?: {
+            version?: string;
+        } | null;
+    } | null;
+    /** Inject `expo-localization` for `locale`. Optional. */
+    readonly localization?: {
+        getLocales: () => Array<{
+            languageTag: string;
+        }>;
+    } | null;
+}
+declare function getAutoContext(options?: AutoContextOptions): VariantContext;
+type ScreenSizeBucket = NonNullable<VariantContext["screenSize"]>;
+declare function bucketScreenWidth(width: number): ScreenSizeBucket;
+
+/**
+ * Encode and decode share payloads for deep links and QR codes.
+ *
+ * The wire format is documented in `docs/features/qr-sharing.md`:
+ *
+ *   1. Serialise the payload as compact JSON.
+ *   2. Optionally gzip-like compress (deferred — we ship plain base64
+ *      first; the wire format is forward-compatible because the prefix
+ *      byte tells the decoder which mode was used).
+ *   3. Base64url-encode the bytes (RFC 4648 §5: `+` → `-`, `/` → `_`,
+ *      no `=` padding).
+ *
+ * We implement base64url by hand because we cannot rely on
+ * `globalThis.btoa` / `Buffer` being present on every RN runtime,
+ * and pulling in a base64 polyfill would burst the bundle budget.
+ * The encoder/decoder operates on UTF-8 byte arrays via `TextEncoder`
+ * / `TextDecoder`, both of which ship in Hermes.
+ *
+ * The format prefix byte is `0` for "raw JSON" and reserved for future
+ * compression schemes (`1` = deflate-raw, `2` = brotli, etc.). On
+ * decode we tolerate a missing prefix to keep older clients working.
+ */
+
+/**
+ * Encode a payload to its on-the-wire base64url string. Throws on
+ * the rare case where validation fails on a payload constructed by
+ * the caller themselves — that's a developer error worth surfacing.
+ */
+declare function encodeSharePayload(payload: SharePayload): string;
+/**
+ * Decode a base64url string back into a validated payload. Returns
+ * a `ValidationResult` so callers can branch on `ok` rather than
+ * wrap the call in try/catch.
+ */
+declare function decodeSharePayload(encoded: string, now?: number): ValidationResult;
+declare function bytesToBase64Url(bytes: Uint8Array): string;
+declare function base64UrlToBytes(input: string): Uint8Array;
+
+/**
+ * Deep link handler for variantlab share payloads.
+ *
+ * Wires React Native's `Linking` module to the engine: when the OS
+ * delivers a URL with our share scheme, we decode the `?p=...` query
+ * parameter, validate it, and apply the overrides.
+ *
+ * Design notes:
+ *
+ *   - The handler accepts the engine *and* the `Linking` module from
+ *     the caller. In a real app the caller passes `Linking` from
+ *     `react-native`; in tests the caller passes a mock that records
+ *     `addEventListener` and `getInitialURL` calls. This keeps the
+ *     module free of any real RN imports for the test runner.
+ *   - URL parsing is hand-rolled because RN's `URL` polyfill is
+ *     unreliable across versions and we only need to extract one
+ *     query param.
+ *   - Each apply emits via `engine.setVariant(id, variantId, "deeplink")`
+ *     so the source field on `variantChanged` events lets debug overlays
+ *     and telemetry distinguish deep-link writes from manual ones.
+ *   - We rate-limit deep-link applies to one per second by default
+ *     (`qr-sharing.md` §Rate limiting). Callers can override the
+ *     interval but cannot disable it entirely.
+ */
+
+/** The minimal Linking surface we depend on. */
+interface LinkingLike {
+    addEventListener(type: "url", handler: (event: {
+        url: string;
+    }) => void): {
+        remove: () => void;
+    };
+    getInitialURL(): Promise<string | null>;
+}
+interface RegisterDeepLinkOptions {
+    /** App URL scheme, e.g. `"drishtikon"`. Required to filter foreign URLs. */
+    readonly scheme?: string;
+    /** Optional host portion, e.g. `"variantlab"`. Defaults to any host. */
+    readonly host?: string;
+    /** Query parameter holding the encoded payload. Default: `"p"`. */
+    readonly param?: string;
+    /** Called after each successful apply with the decoded payload. */
+    readonly onApply?: (payload: SharePayload) => void;
+    /** Called whenever a candidate link fails validation. */
+    readonly onError?: (reason: ValidationFailure | "wrong-scheme" | "no-payload") => void;
+    /** Minimum ms between successful applies. Default: 1000. */
+    readonly minIntervalMs?: number;
+}
+/**
+ * Register the deep-link handler. Returns an unsubscribe function
+ * that removes the listener and stops handling pending initial URLs.
+ *
+ * The handler also fires once for the URL that launched the app
+ * (via `getInitialURL`) so cold-launches via QR scan still apply
+ * the override on first render.
+ */
+declare function registerDeepLinkHandler(engine: VariantEngine, linking: LinkingLike, options?: RegisterDeepLinkOptions): () => void;
+/**
+ * Apply a previously-decoded payload to the engine. Exposed publicly
+ * so callers that build their own URL-handling pipeline (Next.js
+ * middleware, web router) can reuse the same logic.
+ */
+declare function applyPayload(engine: VariantEngine, payload: SharePayload): void;
+
+/**
+ * Validate a candidate share payload before applying it.
+ *
+ * Share payloads come from untrusted input — a deep link, a QR code,
+ * a clipboard paste — so we treat them as adversarial. The validator
+ * walks the structure with `Object.create(null)` semantics in mind:
+ *
+ *   - Reject prototype-pollution keys (`__proto__`, `constructor`,
+ *     `prototype`) anywhere in the tree.
+ *   - Enforce strict id regexes on every override key/value so a
+ *     malformed payload cannot smuggle non-printable bytes into a
+ *     `setVariant` call.
+ *   - Cap the override count and total decoded size to bound memory.
+ *   - Honor an optional `expires` field so QR codes shared earlier
+ *     in the day cannot be replayed forever.
+ *
+ * The validator returns a `ValidationResult` discriminated union
+ * instead of throwing because callers (deep-link handler, QR scanner)
+ * almost always want to silently surface a failure to the UI rather
+ * than treat it as a runtime error.
+ */
+
+declare function validatePayload(input: unknown, now?: number): ValidationResult;
+
+/**
+ * The pluggable storage interface used by every adapter in this package.
+ *
+ * Mirrors the surface in `API.md` §`Storage interface` so that callers
+ * can persist engine overrides to whichever native KV store fits their
+ * app — AsyncStorage by default, MMKV when bundle/perf matter, or
+ * SecureStore when the override list itself is sensitive.
+ *
+ * Methods may be sync or async to match the underlying backing store.
+ * `@variantlab/core` does not yet wire this into `EngineOptions`; for
+ * now adapters expose them as standalone factories so that callers can
+ * implement persistence at the app boundary (e.g. by serialising
+ * `engine.getHistory()` after every `variantChanged` event).
+ */
+interface Storage {
+    getItem(key: string): string | null | Promise<string | null>;
+    setItem(key: string, value: string): void | Promise<void>;
+    removeItem(key: string): void | Promise<void>;
+    /** Optional bulk-key listing for debug overlay export and tests. */
+    keys?(): string[] | Promise<string[]>;
+    /** Optional clear-all helper used by `engine.resetAll()` integrations. */
+    clear?(): void | Promise<void>;
+}
+/** Prefix every variantlab key with this so storage stays sandboxed. */
+declare const STORAGE_KEY_PREFIX = "variantlab:";
+/** Build a fully-qualified storage key from a logical name. */
+declare function buildKey(name: string): string;
+
+/**
+ * `Storage` adapter backed by `@react-native-async-storage/async-storage`.
+ *
+ * AsyncStorage is the de-facto standard KV store on React Native and
+ * the only one we recommend by default — it's bundled with every
+ * Expo project, ships in the New Architecture, and works on iOS,
+ * Android, web, and tvOS. It is, however, async on every method, so
+ * the returned `Storage` is a fully async implementation.
+ *
+ * The adapter is constructed lazily: callers pass in their AsyncStorage
+ * module rather than us importing it. This keeps `@variantlab/react-native`
+ * itself free of any RN package imports at module load — the user's
+ * bundler resolves the peer, we never see it. The factory accepts the
+ * module directly so the surface is dependency-injected and trivially
+ * testable.
+ */
+
+/** Subset of `AsyncStorageStatic` we actually use. */
+interface AsyncStorageLike {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+    getAllKeys(): Promise<readonly string[]>;
+    clear?(): Promise<void>;
+}
+declare function createAsyncStorageAdapter(asyncStorage: AsyncStorageLike): Storage;
+
+/**
+ * In-memory `Storage` implementation. Useful for tests, SSR fallbacks,
+ * and any code path where the host platform's native KV is unavailable.
+ *
+ * The implementation is intentionally trivial: a `Map` keyed on the
+ * fully-qualified key, no namespacing logic, no async wrappers. Real
+ * adapters wrap a native module and may be async; this one is sync to
+ * keep tests deterministic.
+ */
+
+declare function createMemoryStorage(): Storage;
+
+/**
+ * `Storage` adapter backed by `react-native-mmkv`.
+ *
+ * MMKV is a fully synchronous KV store implemented in C++ on top of
+ * mmap. It's the fastest option on RN by a wide margin and is
+ * particularly nice for variantlab because variant resolution is
+ * synchronous on the hot path — using MMKV means storage round trips
+ * never block on a JS-bridge call.
+ *
+ * Like `async-storage`, the underlying instance is dependency-injected
+ * rather than imported here. The caller constructs an `MMKV` instance
+ * (typically with their own `id` namespace and optional encryption key)
+ * and hands it in. We only require a tiny subset of the surface so
+ * users can also pass any compatible mock in tests.
+ */
+
+/** Subset of the real MMKV instance we depend on. */
+interface MMKVLike {
+    set(key: string, value: string): void;
+    getString(key: string): string | undefined;
+    contains(key: string): boolean;
+    delete(key: string): void;
+    getAllKeys(): string[];
+    clearAll?(): void;
+}
+declare function createMMKVStorageAdapter(mmkv: MMKVLike): Storage;
+
+/**
+ * `Storage` adapter backed by `expo-secure-store`.
+ *
+ * SecureStore writes through to Keychain (iOS) and the EncryptedSharedPreferences
+ * /Keystore pair (Android). It's appropriate when the override payload
+ * is itself sensitive — e.g. an experiment that toggles an internal
+ * staging endpoint, an enterprise feature flag, or a beta-channel key.
+ *
+ * SecureStore has two notable constraints:
+ *
+ *   1. **No bulk key listing.** The native API does not expose a
+ *      "list every key" operation, so `keys()` is intentionally absent.
+ *      Callers that need bulk operations should layer an index in a
+ *      separate AsyncStorage entry, or compose with `createMemoryStorage`.
+ *   2. **Slow on Android.** Each read/write hits the native module.
+ *      Don't use this on hot paths where latency matters.
+ *
+ * As with the other adapters, the upstream module is injected so this
+ * file imports nothing from `expo-secure-store` itself.
+ */
+
+/** Subset of the real `expo-secure-store` namespace we use. */
+interface SecureStoreLike {
+    getItemAsync(key: string): Promise<string | null>;
+    setItemAsync(key: string, value: string): Promise<void>;
+    deleteItemAsync(key: string): Promise<void>;
+}
+declare function createSecureStoreAdapter(secureStore: SecureStoreLike): Storage;
+
+/**
+ * `@variantlab/react-native` — public barrel.
+ *
+ * This entrypoint deliberately **re-exports everything** from
+ * `@variantlab/react` so a React Native app can
+ *
+ *     import { VariantLabProvider, useVariant } from "@variantlab/react-native";
+ *
+ * without the user having to remember that the hook layer lives in
+ * the web-React package. The hooks and components are 100% compatible
+ * with React Native — they rely only on React's own APIs.
+ *
+ * RN-specific surface sits alongside: storage adapters, auto-context
+ * detection, and the deep-link handler. The debug overlay and the
+ * QR helpers are intentionally split into their own sub-entrypoints
+ * (`/debug`, `/qr`) so tree-shaking works at the package level:
+ * production bundles that never import `/debug` do not pay for it.
+ */
+declare const VERSION = "0.0.0";
+
+export { type AsyncStorageLike, type AutoContextOptions, type LinkingLike, type MMKVLike, type RegisterDeepLinkOptions, STORAGE_KEY_PREFIX, type ScreenSizeBucket, type SecureStoreLike, SharePayload, type Storage, VERSION, ValidationFailure, ValidationResult, applyPayload, base64UrlToBytes, bucketScreenWidth, buildKey, bytesToBase64Url, createAsyncStorageAdapter, createMMKVStorageAdapter, createMemoryStorage, createSecureStoreAdapter, decodeSharePayload, encodeSharePayload, getAutoContext, registerDeepLinkHandler, validatePayload };