@rs-native-kit/version-check 0.1.2

package/src/domain/models/VersionManagerOptions.ts

@@ -0,0 +1,150 @@
+import type { IPlatformBridge } from '../ports/IPlatformBridge';
+import type {
+  SignatureAlgorithm,
+  VersionManagerConfigDocument,
+} from './ConfigDocument';
+import type { RemoteVersionInfo } from './RemoteVersionInfo';
+
+export type LogLevel =
+  'silent' | 'error' | 'warn' | 'info' | 'debug' | 'verbose';
+
+export interface LogEntry {
+  readonly level: LogLevel;
+  readonly message: string;
+  readonly timestamp: number;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+
+export interface ILogSink {
+  write(entry: LogEntry): void;
+}
+
+export interface LoggingOptions {
+  level?: LogLevel;
+  sink?: ILogSink;
+}
+
+export interface CacheOptions {
+  ttlMs?: number;
+  storage?: 'memory' | 'persistent';
+  bustOnManualCheck?: boolean;
+}
+
+export interface RetryOptions {
+  maxAttempts?: number;
+  backoff?: 'fixed' | 'exponential-jitter';
+  baseDelayMs?: number;
+}
+
+export interface FallbackOptions {
+  onNetworkError?: 'useCache' | 'useDefaultConfig' | 'noAction';
+  defaultConfig?: RemoteVersionInfo;
+  requestTimeoutMs?: number;
+  retry?: RetryOptions;
+}
+
+export interface StoreLinksOptions {
+  /**
+   * appStoreId is optional — when omitted, the App Store lookup falls back to the
+   * running app's bundle id (IAppInfoProvider.getBundleId(), read at check time)
+   * instead of the numeric App Store Connect id.
+   */
+  ios?: { appStoreId?: string; region?: string };
+  /**
+   * packageName is optional — when omitted, the Google Play lookup falls back to the
+   * running app's bundle id (which *is* the Android package name) at check time.
+   */
+  android?: { packageName?: string };
+  huawei?: { appId: string };
+  amazon?: { asin: string };
+  custom?: { url: string; headers?: Record<string, string> };
+}
+
+export interface PolicyOptions {
+  forceUpdateBelow?: string;
+  reminderIntervalMs?: number;
+  rolloutPercentage?: number;
+}
+
+/** Doc 03 §1.1 Security field group — fixed by the app developer, tier-4 only. */
+export interface SecurityOptions {
+  signatureAlgorithm?: SignatureAlgorithm;
+  trustedKeyIds?: string[];
+}
+
+/**
+ * Doc 03 §0/§4 — optional loadable-config-document extension points layered on top of
+ * the VersionManagerOptions "default fallback" tier. All optional; an app that supplies
+ * none of these still works, driven entirely by configure() options (tier 4 only).
+ */
+export interface ConfigSourcesOptions {
+  /**
+   * Bundled local config envelope. Metro/webpack natively supports JSON imports
+   * (`import localConfig from './vm-config.json'`), which already avoids the
+   * double-buffer-copy §5.1 is concerned about for a <=64KB document without requiring
+   * a dedicated native mmap reader — pass the imported envelope object directly.
+   */
+  local?: import('./ConfigDocument').SignedConfigEnvelope;
+  /** Extra headers/timeout for the remote fetch beyond FallbackOptions.requestTimeoutMs. */
+  remoteFetchHeaders?: Record<string, string>;
+  /** Explicit runtime overrides — highest-precedence tier (§4.2 tier 1). */
+  envOverrides?: Partial<VersionManagerConfigDocument>;
+  /** Registered customUiHookIds -> handler ids that a config document is allowed to activate (§1.2, §7.1 VM-1009). */
+  registeredUiHookIds?: string[];
+}
+
+export interface VersionManagerOptions {
+  appVersion?: string;
+  logging?: LoggingOptions;
+  cache?: CacheOptions;
+  fallback?: FallbackOptions;
+  stores: StoreLinksOptions;
+  policy?: PolicyOptions;
+  /** DI override, advanced/testing use only (Prompt 2 §1.1). */
+  platformBridge?: IPlatformBridge;
+  strictReadiness?: boolean;
+  /** Doc 03 §1.1 — if absent, the SDK operates in local-file/default-only mode. */
+  remoteConfigUrl?: string;
+  security?: SecurityOptions;
+  configSources?: ConfigSourcesOptions;
+}
+
+/**
+ * Fully-defaulted, immutable configuration actually consumed at runtime, produced by
+ * IConfigProvider.resolve() from a VersionManagerOptions "default fallback" tier
+ * (Prompt 3 §4.2). Local-file/remote/env overlay tiers are extension points on
+ * IConfigProvider, not yet wired into a signed-envelope pipeline in this pass —
+ * see docs/architecture/03-configuration-system.md §3 for that follow-up scope.
+ */
+export interface ResolvedVersionManagerConfig {
+  readonly appVersion: string | null;
+  readonly logging: { readonly level: LogLevel; readonly sink: ILogSink };
+  readonly cache: {
+    readonly ttlMs: number;
+    readonly storage: 'memory' | 'persistent';
+    readonly bustOnManualCheck: boolean;
+  };
+  readonly fallback: {
+    readonly onNetworkError: 'useCache' | 'useDefaultConfig' | 'noAction';
+    readonly defaultConfig: RemoteVersionInfo | null;
+    readonly requestTimeoutMs: number;
+    readonly retry: {
+      readonly maxAttempts: number;
+      readonly backoff: 'fixed' | 'exponential-jitter';
+      readonly baseDelayMs: number;
+    };
+  };
+  readonly stores: StoreLinksOptions;
+  readonly policy: {
+    readonly forceUpdateBelow: string | null;
+    readonly reminderIntervalMs: number;
+    readonly rolloutPercentage: number;
+  };
+  readonly strictReadiness: boolean;
+  readonly remoteConfigUrl: string | null;
+  readonly security: {
+    readonly signatureAlgorithm: SignatureAlgorithm;
+    readonly trustedKeyIds: readonly string[];
+  };
+  readonly schemaVersion: string;
+}

package/src/domain/ports/ICacheStore.ts

@@ -0,0 +1,5 @@
+export interface ICacheStore<T> {
+  get(key: string): Promise<T | null>;
+  set(key: string, value: T, ttlMs?: number): Promise<void>;
+  invalidate(key: string): Promise<void>;
+}

package/src/domain/ports/IClock.ts

@@ -0,0 +1,3 @@
+export interface IClock {
+  now(): number;
+}

package/src/domain/ports/IConfigProvider.ts

@@ -0,0 +1,18 @@
+import type { ConfigLoadRequest } from '../models/ConfigDocument';
+import type {
+  ResolvedVersionManagerConfig,
+  VersionManagerOptions,
+} from '../models/VersionManagerOptions';
+import type { Unsubscribe } from './IPlatformBridge';
+
+export interface IConfigProvider {
+  resolve(
+    defaults: VersionManagerOptions
+  ): Promise<ResolvedVersionManagerConfig>;
+  /** Doc 03 §0's named surface (`load(request)`) — delegates to resolve(request.defaults). */
+  load(request: ConfigLoadRequest): Promise<ResolvedVersionManagerConfig>;
+  /** Fires when a later resolution (e.g. a remote refresh) produces a changed config. */
+  subscribe(
+    listener: (config: ResolvedVersionManagerConfig) => void
+  ): Unsubscribe;
+}

package/src/domain/ports/IConfigSources.ts

@@ -0,0 +1,44 @@
+import type {
+  BoundaryValidationResult,
+  FetchOptions,
+  RawConfigDocument,
+  SchemaValidationResult,
+  SignedConfigEnvelope,
+  SignatureVerificationResult,
+  TrustedKeySet,
+} from '../models/ConfigDocument';
+import type { ResolvedVersionManagerConfig } from '../models/VersionManagerOptions';
+
+/** Doc 03 §0 — small pipeline of ports living under src/data/config/. */
+
+export interface ILocalConfigSource {
+  /** null if no bundled config asset/envelope was supplied. */
+  read(): Promise<RawConfigDocument | null>;
+}
+
+export interface IRemoteConfigSource {
+  fetch(url: string, options: FetchOptions): Promise<RawConfigDocument>;
+}
+
+export interface IEnvironmentOverrideSource {
+  read(): Promise<
+    Partial<import('../models/ConfigDocument').VersionManagerConfigDocument>
+  >;
+}
+
+export interface IConfigCache {
+  getLastValid(): Promise<ResolvedVersionManagerConfig | null>;
+  setLastValid(config: ResolvedVersionManagerConfig): Promise<void>;
+}
+
+export interface IConfigValidator {
+  validateSchema(doc: RawConfigDocument): SchemaValidationResult;
+  validateBoundaries(doc: RawConfigDocument): BoundaryValidationResult;
+}
+
+export interface ISignatureVerifier {
+  verify(
+    envelope: SignedConfigEnvelope,
+    trustedKeys: TrustedKeySet
+  ): Promise<SignatureVerificationResult>;
+}

package/src/domain/ports/IPlatformBridge.ts

@@ -0,0 +1,97 @@
+import type { PlatformId } from '../models/PlatformId';
+import type { Unsubscribe } from '../models/Unsubscribe';
+import type { IClock } from './IClock';
+
+export type { Unsubscribe };
+
+export interface HttpRequest {
+  readonly url: string;
+  readonly method: 'GET' | 'POST';
+  readonly headers?: Readonly<Record<string, string>>;
+  readonly body?: string;
+  readonly timeoutMs: number;
+}
+
+export interface HttpResponse {
+  readonly status: number;
+  readonly headers: Readonly<Record<string, string>>;
+  readonly body: string;
+}
+
+export interface IHttpClient {
+  request(req: HttpRequest): Promise<HttpResponse>;
+}
+
+export interface IKeyValueStorage {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string): Promise<void>;
+  remove(key: string): Promise<void>;
+}
+
+export interface ISecureStorage {
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+  removeItem(key: string): Promise<void>;
+}
+
+export interface IAppInfoProvider {
+  getCurrentVersion(): Promise<string>;
+  getBuildNumber(): Promise<string>;
+  getBundleId(): Promise<string>;
+}
+
+export interface IDeviceInfoProvider {
+  getOsVersion(): Promise<string>;
+  getDeviceModel(): Promise<string>;
+  getLocale(): Promise<string>;
+}
+
+export interface BackgroundTaskDescriptor {
+  readonly taskId: string;
+  readonly minIntervalMs: number;
+}
+
+export interface IBackgroundScheduler {
+  schedule(task: BackgroundTaskDescriptor): Promise<void>;
+  cancel(taskId: string): Promise<void>;
+}
+
+export interface IAppLifecycleObserver {
+  onForeground(cb: () => void): Unsubscribe;
+  onBackground(cb: () => void): Unsubscribe;
+}
+
+/**
+ * Additive port (not in doc 01 §4's original table) backing ISignatureVerifier
+ * (doc 03 §3.4): "OS-provided cryptography exclusively." Optional because it is only
+ * required when a consumer configures remote/local signed config documents with
+ * algorithm !== 'none'. `keyId` (not raw key material) crosses the JS/native boundary —
+ * per doc 03 §3.4 the actual public key / HMAC secret is embedded at build time on the
+ * native side (iOS Info.plist/Secrets.xcconfig, Android BuildConfig) and resolved from
+ * `keyId` inside the native implementation; JS never sees key material.
+ */
+export interface ICryptoProvider {
+  verifyEd25519(
+    keyId: string,
+    messageBase64: string,
+    signatureBase64: string
+  ): Promise<boolean>;
+  verifyHmacSha256(
+    keyId: string,
+    messageBase64: string,
+    macBase64: string
+  ): Promise<boolean>;
+}
+
+export interface IPlatformBridge {
+  readonly platform: PlatformId;
+  readonly http: IHttpClient;
+  readonly storage: IKeyValueStorage;
+  readonly secureStorage: ISecureStorage;
+  readonly appInfo: IAppInfoProvider;
+  readonly deviceInfo: IDeviceInfoProvider;
+  readonly scheduler: IBackgroundScheduler;
+  readonly clock: IClock;
+  readonly lifecycle: IAppLifecycleObserver;
+  readonly crypto?: ICryptoProvider;
+}

package/src/domain/ports/IStoreProvider.ts

@@ -0,0 +1,12 @@
+import type { StoreProviderId } from '../models/PlatformId';
+import type {
+  StoreLookupRequest,
+  StoreLookupResult,
+} from '../models/StoreLookup';
+
+export interface IStoreProvider {
+  readonly id: StoreProviderId;
+  fetchLatestVersionInfo(
+    request: StoreLookupRequest
+  ): Promise<StoreLookupResult>;
+}

package/src/domain/ports/IVersionRepository.ts

@@ -0,0 +1,14 @@
+import type {
+  RemoteVersionInfo,
+  UserVersionDecision,
+  VersionCheckRequest,
+} from '../models/RemoteVersionInfo';
+
+export interface IVersionRepository {
+  getRemoteVersionInfo(
+    request: VersionCheckRequest
+  ): Promise<RemoteVersionInfo>;
+  getCachedVersionInfo(): Promise<RemoteVersionInfo | null>;
+  persistUserDecision(decision: UserVersionDecision): Promise<void>;
+  getUserDecision(): Promise<UserVersionDecision | null>;
+}

package/src/domain/statemachine/LifecycleStateMachine.ts

@@ -0,0 +1,76 @@
+import {
+  LIFECYCLE_TRANSITIONS,
+  LifecycleState,
+} from '../models/LifecycleState';
+import type { Unsubscribe } from '../models/Unsubscribe';
+
+/** Internal invariant violation — not part of the public VersionManagerException hierarchy. */
+export class InvalidTransitionError extends Error {
+  constructor(from: LifecycleState, to: LifecycleState) {
+    super(`Invalid lifecycle transition: ${from} -> ${to}`);
+    this.name = 'InvalidTransitionError';
+  }
+}
+
+export interface ILifecycleStateMachine {
+  readonly current: LifecycleState;
+  transition(to: LifecycleState): void;
+  onEnter(state: LifecycleState, handler: () => void): Unsubscribe;
+  onExit(state: LifecycleState, handler: () => void): Unsubscribe;
+}
+
+type HandlerMap = Map<LifecycleState, Set<() => void>>;
+
+export class LifecycleStateMachine implements ILifecycleStateMachine {
+  private state: LifecycleState = LifecycleState.UNINITIALIZED;
+  private readonly enterHandlers: HandlerMap = new Map();
+  private readonly exitHandlers: HandlerMap = new Map();
+
+  get current(): LifecycleState {
+    return this.state;
+  }
+
+  transition(to: LifecycleState): void {
+    const allowed = LIFECYCLE_TRANSITIONS[this.state];
+    if (!allowed.includes(to)) {
+      throw new InvalidTransitionError(this.state, to);
+    }
+    const from = this.state;
+    this.notify(this.exitHandlers, from);
+    this.state = to;
+    this.notify(this.enterHandlers, to);
+  }
+
+  onEnter(state: LifecycleState, handler: () => void): Unsubscribe {
+    return this.register(this.enterHandlers, state, handler);
+  }
+
+  onExit(state: LifecycleState, handler: () => void): Unsubscribe {
+    return this.register(this.exitHandlers, state, handler);
+  }
+
+  private register(
+    map: HandlerMap,
+    state: LifecycleState,
+    handler: () => void
+  ): Unsubscribe {
+    let set = map.get(state);
+    if (!set) {
+      set = new Set();
+      map.set(state, set);
+    }
+    set.add(handler);
+    return () => {
+      set?.delete(handler);
+    };
+  }
+
+  /** Copy-on-write snapshot dispatch (Prompt 1 §9.2) — safe if a handler unsubscribes mid-dispatch. */
+  private notify(map: HandlerMap, state: LifecycleState): void {
+    const set = map.get(state);
+    if (!set) return;
+    for (const handler of Array.from(set)) {
+      handler();
+    }
+  }
+}

package/src/domain/usecases/CheckForUpdatesUseCase.ts

@@ -0,0 +1,63 @@
+import type { DecisionEngine } from '../engines/decision/DecisionEngine';
+import type { IUpdatePolicyEngine } from '../engines/policy/IUpdatePolicyEngine';
+import type { IVersionComparator } from '../engines/semver/IVersionComparator';
+import type { ActionPlan } from '../models/ActionPlan';
+import type { PlatformId } from '../models/PlatformId';
+import type { IClock } from '../ports/IClock';
+import type { IVersionRepository } from '../ports/IVersionRepository';
+
+export interface CheckForUpdatesUseCaseDeps {
+  readonly repository: IVersionRepository;
+  readonly comparator: IVersionComparator;
+  readonly policyEngine: IUpdatePolicyEngine;
+  readonly decisionEngine: DecisionEngine;
+  readonly clock: IClock;
+}
+
+export interface CheckForUpdatesInput {
+  readonly currentVersion: string;
+  readonly bundleId: string;
+  readonly platform: PlatformId;
+  readonly bypassCache: boolean;
+  readonly timeoutMs: number;
+  readonly forceUpdateBelow: string | null;
+  readonly rolloutPercentage: number;
+  readonly rolloutBucket: number;
+}
+
+export class CheckForUpdatesUseCase {
+  constructor(private readonly deps: CheckForUpdatesUseCaseDeps) {}
+
+  async execute(input: CheckForUpdatesInput): Promise<ActionPlan> {
+    const remote = await this.deps.repository.getRemoteVersionInfo({
+      currentVersion: input.currentVersion,
+      bundleId: input.bundleId,
+      platform: input.platform,
+      bypassCache: input.bypassCache,
+      timeoutMs: input.timeoutMs,
+    });
+
+    const currentParsed = this.deps.comparator.parse(input.currentVersion);
+    const remoteParsed = this.deps.comparator.parse(remote.latestVersion);
+    const forceUpdateBelowParsed = input.forceUpdateBelow
+      ? this.deps.comparator.parse(input.forceUpdateBelow)
+      : null;
+    const userDecision = await this.deps.repository.getUserDecision();
+
+    const actionType = this.deps.policyEngine.evaluate({
+      currentVersion: currentParsed,
+      remoteVersion: remoteParsed,
+      forceUpdateBelow: forceUpdateBelowParsed,
+      userDecision,
+      now: this.deps.clock.now(),
+      rolloutPercentage: input.rolloutPercentage,
+      rolloutBucket: input.rolloutBucket,
+    });
+
+    return this.deps.decisionEngine.buildActionPlan(
+      actionType,
+      input.currentVersion,
+      remote
+    );
+  }
+}

package/src/domain/usecases/ForceTriggerUpdateUseCase.ts

@@ -0,0 +1,35 @@
+import { ActionType } from '../models/ActionPlan';
+import type { ActionPlan } from '../models/ActionPlan';
+import type { DecisionEngine } from '../engines/decision/DecisionEngine';
+import type { PlatformId } from '../models/PlatformId';
+import type { IVersionRepository } from '../ports/IVersionRepository';
+
+export interface ForceTriggerUpdateInput {
+  readonly currentVersion: string;
+  readonly bundleId: string;
+  readonly platform: PlatformId;
+  readonly timeoutMs: number;
+}
+
+export class ForceTriggerUpdateUseCase {
+  constructor(
+    private readonly repository: IVersionRepository,
+    private readonly decisionEngine: DecisionEngine
+  ) {}
+
+  async execute(input: ForceTriggerUpdateInput): Promise<ActionPlan> {
+    const remote = await this.repository.getRemoteVersionInfo({
+      currentVersion: input.currentVersion,
+      bundleId: input.bundleId,
+      platform: input.platform,
+      bypassCache: true,
+      timeoutMs: input.timeoutMs,
+    });
+
+    return this.decisionEngine.buildActionPlan(
+      ActionType.FORCE_UPDATE,
+      input.currentVersion,
+      remote
+    );
+  }
+}

package/src/domain/usecases/ResetIgnoredVersionsUseCase.ts

@@ -0,0 +1,26 @@
+import type { IVersionRepository } from '../ports/IVersionRepository';
+
+export class ResetIgnoredVersionsUseCase {
+  constructor(private readonly repository: IVersionRepository) {}
+
+  async execute(versions?: readonly string[]): Promise<void> {
+    const current = await this.repository.getUserDecision();
+    const remindMeLaterUntil = current?.remindMeLaterUntil ?? null;
+
+    if (!versions || versions.length === 0) {
+      await this.repository.persistUserDecision({
+        ignoredVersions: [],
+        remindMeLaterUntil,
+      });
+      return;
+    }
+
+    const remaining = (current?.ignoredVersions ?? []).filter(
+      (v) => !versions.includes(v)
+    );
+    await this.repository.persistUserDecision({
+      ignoredVersions: remaining,
+      remindMeLaterUntil,
+    });
+  }
+}

package/src/index.tsx

@@ -0,0 +1,84 @@
+// Public API entry point (core only — no React/UI code reachable from this path,
+// see src/ui.tsx for the Hooks adapter). Prompt 2.
+
+export { VersionManager, VersionManagerBuilder } from './publicApi';
+
+export type {
+  IVersionManagerCore,
+  IVersionManagerEvents,
+} from './domain/IVersionManagerCore';
+
+export type { ActionPlan } from './domain/models/ActionPlan';
+export { ActionType } from './domain/models/ActionPlan';
+export type { ParsedVersion } from './domain/models/ParsedVersion';
+export type { UpdateInfo } from './domain/models/UpdateInfo';
+export { LifecycleState } from './domain/models/LifecycleState';
+export type { PlatformId, StoreProviderId } from './domain/models/PlatformId';
+export type {
+  RemoteVersionInfo,
+  UserVersionDecision,
+  VersionCheckRequest,
+} from './domain/models/RemoteVersionInfo';
+export type { Unsubscribe } from './domain/models/Unsubscribe';
+export type {
+  CheckForUpdatesOptions,
+  ForceTriggerOptions,
+  ResetIgnoredVersionsOptions,
+} from './domain/models/PublicApiOptions';
+export type {
+  CacheOptions,
+  FallbackOptions,
+  ILogSink,
+  LogEntry,
+  LoggingOptions,
+  LogLevel,
+  PolicyOptions,
+  ResolvedVersionManagerConfig,
+  RetryOptions,
+  StoreLinksOptions,
+  VersionManagerOptions,
+} from './domain/models/VersionManagerOptions';
+export type {
+  ErrorPhase,
+  StateChangedEvent,
+  UpdateDetectedEvent,
+  UpdateNotAvailableEvent,
+  UserActionEvent,
+  UserActionType,
+  VersionManagerErrorEvent,
+  VersionManagerEventMap,
+  VersionManagerEventType,
+} from './domain/models/Events';
+
+export type { IPlatformBridge } from './domain/ports/IPlatformBridge';
+
+export {
+  AppNotFoundException,
+  BoundaryValidationException,
+  CacheCorruptionException,
+  CacheException,
+  CacheWriteException,
+  ConfigSizeLimitExceededException,
+  EnvironmentOverrideConflictException,
+  InvalidConfigException,
+  InvalidVersionFormatException,
+  NetworkException,
+  NotInitializedException,
+  NotReadyException,
+  OfflineException,
+  PlatformBridgeException,
+  PolicyEvaluationException,
+  RateLimitException,
+  RequestTimeoutException,
+  SchemaValidationException,
+  SignatureVerificationException,
+  StorePermissionException,
+  StoreProviderException,
+  StoreResponseParseException,
+  TlsHandshakeException,
+  UnknownVersionManagerException,
+  UnsupportedStoreException,
+  UntrustedKeyIdException,
+  VersionManagerException,
+} from './domain/errors/VersionManagerException';
+export type { VersionManagerErrorCode } from './domain/errors/VersionManagerException';

package/src/platform/contracts/IPlatformBridge.ts

@@ -0,0 +1,14 @@
+export type {
+  IPlatformBridge,
+  IHttpClient,
+  IKeyValueStorage,
+  ISecureStorage,
+  IAppInfoProvider,
+  IDeviceInfoProvider,
+  IBackgroundScheduler,
+  IAppLifecycleObserver,
+  ICryptoProvider,
+  BackgroundTaskDescriptor,
+  HttpRequest,
+  HttpResponse,
+} from '../../domain/ports/IPlatformBridge';

package/src/platform/createPlatformBridge.native.ts

@@ -0,0 +1,7 @@
+import type { IPlatformBridge } from '../domain/ports/IPlatformBridge';
+import { NativePlatformBridge } from './native/NativePlatformBridge';
+
+/** iOS/Android implementation — see createPlatformBridge.ts for why this is a separate file. */
+export function createPlatformBridge(): IPlatformBridge {
+  return new NativePlatformBridge();
+}

package/src/platform/createPlatformBridge.ts

@@ -0,0 +1,15 @@
+import type { IPlatformBridge } from '../domain/ports/IPlatformBridge';
+import { WebPlatformBridge } from './web/WebPlatformBridge';
+
+/**
+ * Web/default implementation. Metro (React Native's bundler) prefers
+ * createPlatformBridge.native.ts for iOS/Android builds; Vite (the web build, see
+ * example/vite.config.mjs) has no such resolution rule and always resolves this file
+ * — the same convention already used by src/multiply.tsx / multiply.native.tsx. This
+ * indirection matters: NativePlatformBridge.ts imports NativeVersionCheck, whose
+ * top-level TurboModuleRegistry.getEnforcing() call would throw if ever evaluated on
+ * Web, so the native module must never even be imported into a web bundle.
+ */
+export function createPlatformBridge(): IPlatformBridge {
+  return new WebPlatformBridge();
+}