@ateam-ai-mobile/expo 0.1.5 → 0.1.8

package/src/device/createDeviceProvider.ts

@@ -0,0 +1,917 @@
+/**
+ * SDK device-primitive provider (Expo-backed).
+ *
+ * `createDeviceProvider()` builds the FULL, UNGATED `PluginNative` implementation
+ * a host registers once via `setPluginNativeProvider`. Per-plugin capability
+ * gating and per-plugin filesystem scoping are applied downstream by
+ * plugin-runtime's `gatePluginNative` — this module does not gate.
+ *
+ * Not a React hook: it holds no React state and must be safe to build at module
+ * scope, including on a headless background wake before any UI exists.
+ */
+import * as Haptics from 'expo-haptics';
+// Both are already app dependencies and already used by the device-bridge
+// collectors — safe for eager import (unlike cookies/nfc, which need native
+// modules absent from Expo Go).
+import * as ExpoLocation from 'expo-location';
+import * as ImagePicker from 'expo-image-picker';
+import * as Notifications from 'expo-notifications';
+import * as DocumentPicker from 'expo-document-picker';
+import * as FS from 'expo-file-system';
+import * as SQLite from 'expo-sqlite';
+// The broker behind scanner.scanOnce() and camera.recordVideo(): both need a
+// MOUNTED camera, which a function call cannot provide.
+import { cameraTasks } from '../camera/cameraTasks';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+// native.vision: the on-device analyzer (ada-vision module) — resolve a frame id
+// to its local pixels, measure/read/classify on-device, never off the phone.
+import * as adaVision from '../vision';
+// native.maps: place search + walking routes (ada-maps module, MapKit) and the
+// SDK's one reverse geocode. NOT on-device — queries go to Apple's servers.
+import * as adaMaps from '../maps';
+import { countArg, fractionArg, refuseArgument, shown } from '../args';
+import {
+  coordinateArg, mapsFailure, searchArgs, toMapsPlaces, toMapsRoute, toReverseGeocodedPlace,
+} from '../maps/normalize';
+// Device-bridge owns every native module. plugin-sdk delegates so RN
+// plugins never import native modules directly. When adding a new
+// capability: add it to device-bridge, import here, declare in types.ts,
+// wire in the factory below.
+//
+// IMPORTANT: cookies and nfc use native modules NOT available in Expo Go.
+// We lazy-import them so the app doesn't crash at load time.
+// Only biometrics (expo-local-authentication), sharing (expo-sharing),
+// and scanner (expo-camera) are safe for eager import.
+import {
+  biometrics as deviceBiometrics,
+  sharing as deviceSharing,
+  scanner as deviceScanner,
+} from '../device-bridge';
+
+// Lazy loaders for native modules not in Expo Go
+function getDeviceCookies() {
+  try { return require('../device-bridge/cookies'); } catch { return null; }
+}
+function getDeviceNfc() {
+  try { return require('../device-bridge/nfc'); } catch { return null; }
+}
+import type {
+  NativeCapabilities,
+  PluginNative,
+  CameraAPI,
+  LocationAPI,
+  StorageAPI,
+  BiometricsAPI,
+  BiometricsAPIv2,
+  NotificationsAPI,
+  HapticsAPI,
+  ConnectivityAPI,
+  FileSystemAPI,
+  CookiesAPI,
+  WebViewCookie,
+  SharingAPI,
+  ScannerAPI,
+  NfcAPI,
+  BluetoothAPI,
+  VisionAPI,
+  MapsAPI,
+} from '@ateam-ai-mobile/plugin-runtime';
+
+class CapabilityUnavailableError extends Error {
+  code = 'UNAVAILABLE' as const;
+  constructor(capability: string, reason?: string) {
+    super(reason || `${capability} is not yet implemented. Coming in Phase 2.`);
+    this.name = 'CapabilityUnavailableError';
+  }
+}
+
+class CapabilityNotDeclaredError extends Error {
+  code = 'NOT_DECLARED' as const;
+  constructor(capability: string) {
+    super(`Capability '${capability}' not declared in plugin manifest. Add it to the native.${capability} field.`);
+    this.name = 'CapabilityNotDeclaredError';
+  }
+}
+
+function stubApi<T extends object>(capability: string): T {
+  return new Proxy({} as T, {
+    get(_target, prop) {
+      if (typeof prop === 'string') {
+        return () => {
+          throw new CapabilityUnavailableError(capability);
+        };
+      }
+    },
+  });
+}
+
+// ── Location (expo-location — was stubbed, is real now) ───────────
+//
+// `location` was wired to stubApi, so a plugin that correctly DECLARED
+// `location: true` still got "location is not yet implemented. Coming in
+// Phase 2." on every call. expo-location has been a dependency all along and
+// the device-bridge collectors use it; only the plugin-facing API was missing.
+
+function createLocationAPI(): LocationAPI {
+  /** Ask once, and say what the user can do about a refusal. */
+  const ensurePermission = async (): Promise<void> => {
+    const existing = await ExpoLocation.getForegroundPermissionsAsync();
+    if (existing.status === 'granted') return;
+    const asked = await ExpoLocation.requestForegroundPermissionsAsync();
+    if (asked.status !== 'granted') {
+      // A voice assistant reads this out, so it has to be actionable rather
+      // than a status code.
+      throw new Error(
+        'Location permission was not granted. Enable it for this app in Settings > Privacy > Location Services.',
+      );
+    }
+  };
+
+  return {
+    async getCurrent(opts) {
+      await ensurePermission();
+      // 'high' costs battery and a second or two of settling; default balanced,
+      // which is plenty for "which street am I on".
+      const fix = await ExpoLocation.getCurrentPositionAsync({
+        accuracy:
+          opts?.accuracy === 'high'
+            ? ExpoLocation.Accuracy.High
+            : ExpoLocation.Accuracy.Balanced,
+      });
+      return {
+        latitude: fix.coords.latitude,
+        longitude: fix.coords.longitude,
+        altitude: fix.coords.altitude ?? undefined,
+      };
+    },
+
+    watchPosition(cb) {
+      let subscription: { remove(): void } | null = null;
+      let cancelled = false;
+
+      void (async () => {
+        try {
+          await ensurePermission();
+          if (cancelled) return;
+          subscription = await ExpoLocation.watchPositionAsync(
+            { accuracy: ExpoLocation.Accuracy.Balanced },
+            fix => cb({ latitude: fix.coords.latitude, longitude: fix.coords.longitude }),
+          );
+          // Unsubscribed while we were still asking for permission — otherwise
+          // the GPS stays on with nobody listening.
+          if (cancelled) { subscription?.remove(); subscription = null; }
+        } catch (err: any) {
+          console.warn('[location] watchPosition failed:', err?.message || String(err));
+        }
+      })();
+
+      return () => {
+        cancelled = true;
+        subscription?.remove();
+        subscription = null;
+      };
+    },
+  };
+}
+
+// ── Camera (expo-image-picker — was stubbed, is real now) ─────────
+//
+// Every method here opens the SYSTEM camera or picker UI, which is why they
+// are honest one-shot actions rather than a frame source: expo-camera can
+// deliver a live feed, but only through a MOUNTED CameraView component, which
+// a headless tool call has no way to mount. A continuous visual feed is the
+// semantic Visual domain's job (Device Bridge v2), not this API's.
+
+function createCameraAPI(): CameraAPI {
+  const ensurePermission = async (): Promise<void> => {
+    const existing = await ImagePicker.getCameraPermissionsAsync();
+    if (existing.granted) return;
+    const asked = await ImagePicker.requestCameraPermissionsAsync();
+    if (!asked.granted) {
+      throw new Error(
+        'Camera permission was not granted. Enable it for this app in Settings > Privacy > Camera.',
+      );
+    }
+  };
+
+  return {
+    async takePhoto(opts) {
+      await ensurePermission();
+      const res = await ImagePicker.launchCameraAsync({
+        quality: opts?.quality ?? 0.7,
+        cameraType:
+          opts?.facing === 'front'
+            ? ImagePicker.CameraType.front
+            : ImagePicker.CameraType.back,
+      });
+      // The user backing out is not an error — but it is also not a photo, so
+      // it must not come back as an empty-looking success.
+      if (res.canceled || !res.assets?.[0]) {
+        throw new Error('No photo taken — the camera was dismissed.');
+      }
+      const a = res.assets[0];
+      return { uri: a.uri, width: a.width, height: a.height };
+    },
+
+    async scanBarcode(opts) {
+      // Kept refusing, and now the refusal has somewhere to send you. Scanning
+      // is a mounted camera lifecycle, which is why it lives on `scanner`.
+      // Silently forwarding would leave a misleading name in every plugin.
+      throw new CapabilityUnavailableError(
+        'camera.scanBarcode',
+        'Use native.scanner.scanOnce() instead — scanning needs a mounted camera, ' +
+          'which this call cannot provide. Same arguments, and it returns { data, format }.' +
+          (opts?.formats?.length ? ' Pass your formats through to scanOnce.' : ''),
+      );
+    },
+
+    async recordVideo(opts) {
+      // A FILE the user deliberately makes — not the Visual domain's frame
+      // ring, which is ephemeral and nobody keeps. Runs on the shared camera
+      // surface, so it throws the same coded failures as scanOnce.
+      return cameraTasks.run('record', {
+        maxDurationMs: opts?.maxDurationMs,
+        withAudio: opts?.withAudio ?? false,
+      });
+    },
+
+    async pickImage(opts) {
+      const existing = await ImagePicker.getMediaLibraryPermissionsAsync();
+      if (!existing.granted) {
+        const asked = await ImagePicker.requestMediaLibraryPermissionsAsync();
+        if (!asked.granted) {
+          throw new Error(
+            'Photo library permission was not granted. Enable it for this app in Settings > Privacy > Photos.',
+          );
+        }
+      }
+      const res = await ImagePicker.launchImageLibraryAsync({
+        allowsMultipleSelection: !!opts?.multiple,
+      });
+      if (res.canceled) return [];
+      return (res.assets || []).map(a => ({ uri: a.uri }));
+    },
+  };
+}
+
+// ── Storage (AsyncStorage — was stubbed) ──────────────────────────
+//
+// KV is real. `db.execute` is NOT: expo-sqlite is not installed, and a fake
+// SQL layer over AsyncStorage would be a worse lie than an error — it would
+// accept a query and return an empty rowset, which reads as "no rows matched".
+
+/**
+ * One SQLite file for plugin storage, opened lazily and once.
+ *
+ * Lazy because opening a database at module load costs startup time for every
+ * user who never touches a plugin that needs one; once because two handles to
+ * the same file is how you get a locked database under concurrent writes.
+ */
+// Typed `any` for the handle: expo-sqlite is an any-shim in this SDK repo's
+// typecheck (the host supplies the real types), so `SQLite.SQLiteDatabase` is
+// not a nameable type here. Runtime is unchanged — SQLite.openDatabaseAsync
+// still returns a real SQLiteDatabase on device.
+// One handle PER plugin database file, opened lazily and once each. A Map (not a
+// single promise) because storage is now per-plugin: each plugin gets its own
+// file, and two handles to the same file is how you get a locked database.
+const _pluginDbs = new Map<string, Promise<any>>();
+function openPluginDb(file: string): Promise<any> {
+  const existing = _pluginDbs.get(file);
+  if (existing) return existing;
+  const opened: Promise<any> = SQLite.openDatabaseAsync(file);
+  _pluginDbs.set(file, opened);
+  return opened;
+}
+
+// The leading SQL keyword, uppercased, after stripping leading whitespace and
+// leading `-- line` / `/* block */` comments — so a comment cannot smuggle the
+// verb past the cross-file check (e.g. `/* */ ATTACH …`).
+function sqlLeadingKeyword(sql: string): string {
+  let s = String(sql);
+  for (;;) {
+    const before = s;
+    s = s.replace(/^\s+/, '');
+    if (s.startsWith('--')) { const nl = s.indexOf('\n'); s = nl === -1 ? '' : s.slice(nl + 1); }
+    else if (s.startsWith('/*')) { const end = s.indexOf('*/'); s = end === -1 ? '' : s.slice(end + 2); }
+    if (s === before) break;
+  }
+  const m = s.match(/^[A-Za-z]+/);
+  return m ? m[0].toUpperCase() : '';
+}
+
+// R3 SECURITY — per-plugin storage isolation. Both the KV namespace and the
+// SQLite database are scoped to the plugin's OWN id, so Plugin A cannot read,
+// overwrite, or query Plugin B's entries/tables. The id is threaded in from the
+// TRUSTED gate (storageFor(pluginId)) — never a caller-supplied prefix.
+//
+// The id is encoded with encodeURIComponent (not used raw) precisely because KV
+// is a FLAT concatenated keyspace with no structural boundary: a raw id like
+// `mcp:conn:plug` shares the `:` delimiter, so `@plugin:mcp:conn:plug:<k>` from
+// one plugin could collide with another plugin's id+key split. Encoding escapes
+// `:` (→ %3A), making the id segment unambiguous and the mapping injective, so
+// distinct ids can never produce overlapping namespaces regardless of the key.
+// (The filesystem sandbox can use the raw id as a directory name because a
+// directory boundary is structural, not delimiter-based.) The same encoded
+// token names the plugin's database file, giving each plugin a distinct DB.
+function createStorageAPI(pluginId: string): StorageAPI {
+  const ns = encodeURIComponent(pluginId);
+  const key = (k: string) => `@plugin:${ns}:${k}`;
+  const dbFile = `plugin-storage-${ns}.db`;
+
+  return {
+    get: (k) => AsyncStorage.getItem(key(k)),
+    set: (k, v) => AsyncStorage.setItem(key(k), v),
+    delete: (k) => AsyncStorage.removeItem(key(k)),
+    db: {
+      async execute(sql: string, params?: any[]) {
+        const verb = sqlLeadingKeyword(sql);
+        // Per-plugin storage isolation rests on each plugin owning its OWN
+        // database FILE. SQLite can cross files — ATTACH mounts another db,
+        // VACUUM INTO writes one — so the file boundary only holds if those are
+        // refused. Otherwise a plugin could `ATTACH '.../plugin-storage-<other
+        // id>.db'` (the id is public and the filename deterministic) and read or
+        // overwrite another plugin's tables. Refuse cross-file statements at the
+        // trusted gate; a plugin never needs them for its own single database.
+        // (runAsync/getAllAsync compile only the FIRST statement, so a trailing
+        // `; ATTACH …` never runs — the leading verb is the whole surface.)
+        // ATTACH/DETACH/VACUUM are the only cross-FILE statements in the standard
+        // expo-sqlite build: loadable extensions are disabled and the file-vtab
+        // modules (fileio/csv/zipfile) are not compiled in, so there is no other
+        // way for a plugin's own connection to reach another plugin's file. If a
+        // future SQLite build enables those, revisit (an allowlist would be the
+        // durable form).
+        if (verb === 'ATTACH' || verb === 'DETACH' || verb === 'VACUUM') {
+          throw new CapabilityUnavailableError(
+            'storage.db',
+            `SQL '${verb}' is not permitted: a plugin's storage is confined to its own database and cannot reach another file.`,
+          );
+        }
+        const db = await openPluginDb(dbFile);
+        // A statement either RETURNS ROWS or CHANGES THEM, and the two need
+        // different calls. Deciding by the leading keyword rather than by
+        // trying one and falling back: a failed INSERT retried as a query
+        // would run it twice.
+        const returnsRows = verb === 'SELECT' || verb === 'PRAGMA' || verb === 'WITH';
+
+        if (returnsRows) {
+          const rows = await db.getAllAsync(sql, (params ?? []) as any);
+          // changes: 0 is the truth for a SELECT, not a placeholder.
+          return { rows, changes: 0 };
+        }
+        const res = await db.runAsync(sql, (params ?? []) as any);
+        // rows: [] is likewise true for a write — it did not select anything.
+        return { rows: [], changes: res.changes ?? 0 };
+      },
+    },
+  };
+}
+
+/**
+ * Wipe ALL plugin storage — KV, SQLite, and the file sandbox — across EVERY
+ * plugin. Per-plugin isolation (R3) keeps plugins apart from each other; this is
+ * the USER boundary: on sign-out it must run so the NEXT user/tenant cannot read
+ * the previous one's plugin data. Best-effort per store — a hiccup clearing one
+ * must never block sign-out — so each part is guarded independently.
+ */
+export async function clearAllPluginData(): Promise<void> {
+  // 1. KV — every `@plugin:` namespace (all plugins, all keys).
+  try {
+    const keys = await AsyncStorage.getAllKeys();
+    const mine = keys.filter((k: string) => k.startsWith('@plugin:'));
+    if (mine.length) await AsyncStorage.multiRemove(mine);
+  } catch (e: any) {
+    console.warn('[adas] clearAllPluginData: KV clear failed:', e?.message || e);
+  }
+
+  // 2. SQLite — close any open per-plugin handles, then delete the db files.
+  try {
+    for (const [, p] of _pluginDbs) {
+      try { const db = await p; await db.closeAsync?.(); } catch { /* already closed */ }
+    }
+    _pluginDbs.clear();
+    const sqliteDir = new FS.Directory(FS.Paths.document, 'SQLite');
+    if (sqliteDir.exists) {
+      for (const entry of sqliteDir.list()) {
+        if (/^plugin-storage-.*\.db$/.test(String(entry.name ?? ''))) {
+          try { entry.delete(); } catch { /* best effort */ }
+        }
+      }
+    }
+  } catch (e: any) {
+    console.warn('[adas] clearAllPluginData: SQLite clear failed:', e?.message || e);
+  }
+
+  // 3. Files — the whole plugin-files/ sandbox tree (all plugins).
+  try {
+    const dir = new FS.Directory(FS.Paths.document, 'plugin-files');
+    if (dir.exists) dir.delete();
+  } catch (e: any) {
+    console.warn('[adas] clearAllPluginData: file sandbox clear failed:', e?.message || e);
+  }
+}
+
+// ── Notifications (expo-notifications — was stubbed) ──────────────
+
+function createNotificationsAPI(): NotificationsAPI {
+  return {
+    async schedule({ title, body, trigger }) {
+      const perm = await Notifications.getPermissionsAsync();
+      if (!perm.granted) {
+        const asked = await Notifications.requestPermissionsAsync();
+        if (!asked.granted) {
+          throw new Error(
+            'Notification permission was not granted. Enable it for this app in Settings > Notifications.',
+          );
+        }
+      }
+      // `seconds` and `date` are the two the contract declares; anything else
+      // would be this API inventing a scheduling model of its own.
+      const when: any =
+        typeof trigger?.seconds === 'number'
+          ? { type: 'timeInterval', seconds: trigger.seconds, repeats: false }
+          : trigger?.date
+            ? { type: 'date', date: new Date(trigger.date) }
+            : null;
+      if (!when) {
+        throw new Error('schedule() needs trigger.seconds or trigger.date.');
+      }
+      return Notifications.scheduleNotificationAsync({
+        content: { title, body },
+        trigger: when,
+      });
+    },
+
+    cancel: (id) => Notifications.cancelScheduledNotificationAsync(id),
+
+    onReceived(cb) {
+      const sub = Notifications.addNotificationReceivedListener(n => {
+        cb({
+          id: n.request.identifier,
+          title: n.request.content.title || '',
+          body: n.request.content.body || '',
+          data: n.request.content.data,
+        });
+      });
+      return () => sub.remove();
+    },
+  };
+}
+
+// ── File system (expo-document-picker — partially real) ───────────
+//
+// pickDocument works. read/write do NOT: expo-file-system is not installed.
+// Named honestly rather than returning empty strings, which would read as an
+// empty file rather than a missing capability.
+
+function createFileSystemAPI(pluginId: string): FileSystemAPI {
+  /**
+   * Every path a plugin gives us is resolved INSIDE its own sandbox directory.
+   *
+   * A plugin is code a solution ships that runs on someone's phone, so
+   * `readFile('/etc/passwd')` — or, more realistically, reading the app's own
+   * auth store or another solution's data — must not be reachable. This is the
+   * same reasoning that took the `sw.*` filesystem tools out of the kernel and
+   * anchored them per tenant.
+   *
+   * The check is on the RESOLVED path, not the input string: `..` segments are
+   * what a blocklist of prefixes misses, and `plugin-files/../../secrets` looks
+   * innocent until it is normalised.
+   */
+  /**
+   * Resolved on FIRST USE, never at construction.
+   *
+   * `new FS.Directory(FS.Paths.document, …)` is a SYNCHRONOUS NATIVE CALL, and
+   * `createNativeCapabilities({ fileSystem: true, … })` runs at MODULE SCOPE in
+   * src/adas.ts. Building it eagerly therefore did native work during startup
+   * module evaluation — on every launch, including a headless background wake
+   * from a push, before any UI exists. If the native module is missing or
+   * `Paths.document` throws there, the whole app dies with no screen to show it
+   * on. Nothing in this factory may touch native until a method is called.
+   */
+  let _root: InstanceType<typeof FS.Directory> | null = null;
+  const rootDir = () => (_root ??= new FS.Directory(FS.Paths.document, 'plugin-files', pluginId));
+
+  const resolve = (p: string): InstanceType<typeof FS.File> => {
+    const root = rootDir();
+    const file = new FS.File(root, p);
+    if (!file.uri.startsWith(root.uri)) {
+      throw new CapabilityUnavailableError(
+        'fileSystem',
+        `Path escapes the plugin's storage area: ${p}. Plugin files live under plugin-files/ and paths cannot traverse out of it.`,
+      );
+    }
+    return file;
+  };
+
+  return {
+    async readFile(path) {
+      const file = resolve(path);
+      if (!file.exists) {
+        // A missing file is not an empty file. Returning '' would read as a
+        // document that exists and happens to have nothing in it.
+        throw new CapabilityUnavailableError(
+          'fileSystem.readFile',
+          `No such file: ${path}. Nothing was read.`,
+        );
+      }
+      return file.text();
+    },
+
+    async writeFile(path, content) {
+      const file = resolve(path);
+      // Create parents as needed — a plugin writing 'cache/report.json' should
+      // not have to know that directories are a separate concept.
+      const parent = file.parentDirectory;
+      if (!parent.exists) parent.create({ intermediates: true });
+      if (!file.exists) file.create();
+      file.write(content);
+    },
+    async pickDocument(opts) {
+      const res = await DocumentPicker.getDocumentAsync({
+        type: opts?.types?.length ? opts.types : '*/*',
+        copyToCacheDirectory: true,
+      });
+      // Backing out is not a file. Returning zeros here would look like an
+      // empty document the user actually chose.
+      if (res.canceled || !res.assets?.[0]) {
+        throw new Error('No document chosen — the picker was dismissed.');
+      }
+      const a = res.assets[0];
+      return { uri: a.uri, name: a.name, size: a.size ?? 0 };
+    },
+  };
+}
+
+// ── Haptics (fully implemented — expo-haptics already installed) ───
+
+function createHapticsAPI(): HapticsAPI {
+  return {
+    impact(style: 'light' | 'medium' | 'heavy') {
+      const map = {
+        light: Haptics.ImpactFeedbackStyle.Light,
+        medium: Haptics.ImpactFeedbackStyle.Medium,
+        heavy: Haptics.ImpactFeedbackStyle.Heavy,
+      };
+      Haptics.impactAsync(map[style]);
+    },
+    notification(type: 'success' | 'warning' | 'error') {
+      const map = {
+        success: Haptics.NotificationFeedbackType.Success,
+        warning: Haptics.NotificationFeedbackType.Warning,
+        error: Haptics.NotificationFeedbackType.Error,
+      };
+      Haptics.notificationAsync(map[type]);
+    },
+    // Shorthand for notification('error'). Plugins call this; it was never
+    // implemented, and optional chaining meant the failure the user was meant
+    // to FEEL simply did not happen.
+    error() {
+      Haptics.notificationAsync(Haptics.NotificationFeedbackType.Error);
+    },
+    selection() {
+      Haptics.selectionAsync();
+    },
+  };
+}
+
+// ── Connectivity (implemented using basic RN fetch check) ──────
+
+function createConnectivityAPI(reachabilityUrl?: string): ConnectivityAPI {
+  let online = true;
+  const listeners = new Set<(online: boolean) => void>();
+  // Lazy + re-armable polling: the instance is now a singleton shared by ALL
+  // plugins (injected once via setPluginNativeProvider), so the interval must
+  // (a) not run at app boot when nobody is listening, and (b) restart when a
+  // later plugin subscribes after an earlier one unsubscribed to zero.
+  // Pre-singleton, each Plugin mount got its own instance and clearInterval
+  // was harmless; with a shared instance it would kill polling app-wide.
+  let interval: ReturnType<typeof setInterval> | null = null;
+
+  // Simple connectivity check — upgrade to @react-native-community/netinfo in Phase 2.
+  // NO hardcoded URL: the host injects its own health endpoint. With none given
+  // we assume reachable (return true) rather than pin an A-Team-specific default.
+  const checkOnline = async () => {
+    if (!reachabilityUrl) return true;
+    try {
+      const res = await fetch(reachabilityUrl, {
+        method: 'HEAD',
+        signal: AbortSignal.timeout(5000),
+      });
+      return res.ok;
+    } catch {
+      return false;
+    }
+  };
+
+  const startPolling = () => {
+    // Nothing to poll without a reachability URL: `online` stays constant-true,
+    // so an interval would only wake the app to learn the same answer.
+    if (!reachabilityUrl) return;
+    if (interval) return;
+    interval = setInterval(async () => {
+      const newState = await checkOnline();
+      if (newState !== online) {
+        online = newState;
+        listeners.forEach(cb => cb(online));
+      }
+    }, 30000);
+  };
+
+  return {
+    isOnline() {
+      return online;
+    },
+    onChange(cb: (online: boolean) => void) {
+      listeners.add(cb);
+      startPolling();
+      return () => {
+        listeners.delete(cb);
+        if (listeners.size === 0 && interval) {
+          clearInterval(interval);
+          interval = null;
+        }
+      };
+    },
+  };
+}
+
+// ── Cookies (delegates to device-bridge, lazy-loaded) ──
+function createCookiesAPI(): CookiesAPI {
+  return {
+    async get(url: string): Promise<WebViewCookie[]> {
+      const mod = getDeviceCookies();
+      if (!mod) throw new CapabilityUnavailableError('cookies (native module not available — use a dev build)');
+      const list = await mod.get(url, true);
+      return list as WebViewCookie[];
+    },
+    async clear(_url: string): Promise<{ ok: boolean }> {
+      const mod = getDeviceCookies();
+      if (!mod) throw new CapabilityUnavailableError('cookies (native module not available — use a dev build)');
+      const r = await mod.clearAll();
+      return { ok: r.ok };
+    },
+  };
+}
+
+// ── Biometrics v2 (Face ID / Touch ID / fingerprint) ──
+function createBiometricsAPIv2(): BiometricsAPIv2 {
+  return {
+    capabilities: () => deviceBiometrics.capabilities(),
+    authenticate: (opts) => deviceBiometrics.authenticate(opts),
+  };
+}
+
+// ── Sharing (native share sheet) ──
+function createSharingAPI(): SharingAPI {
+  return {
+    isAvailable: () => deviceSharing.isAvailable(),
+    shareFile: (fileUri, opts) => deviceSharing.shareFile(fileUri, opts),
+  };
+}
+
+// ── Scanner (QR / barcode permission helper) ──
+function createScannerAPI(): ScannerAPI {
+  return {
+    requestPermissions: () => deviceScanner.requestPermissions(),
+    // Raises the shared camera surface and settles on the first code read.
+    // The plugin mounts nothing — that lifecycle is owned once, by
+    // CameraTaskHost, instead of by every plugin that wants to scan.
+    scanOnce: (opts) => cameraTasks.run('scan', {
+      formats: opts?.formats,
+      timeoutMs: opts?.timeoutMs,
+    }),
+  };
+}
+
+// ── NFC (tag read, lazy-loaded) ──
+function createNfcAPI(): NfcAPI {
+  return {
+    async isSupported() {
+      const mod = getDeviceNfc();
+      if (!mod) return false;
+      return mod.isSupported();
+    },
+    async isEnabled() {
+      const mod = getDeviceNfc();
+      if (!mod) return false;
+      return mod.isEnabled();
+    },
+    readOnce(timeoutMs) {
+      const mod = getDeviceNfc();
+      if (!mod) return Promise.resolve({ ok: false, error: 'nfc_unavailable' } as any);
+      return mod.readOnce(timeoutMs);
+    },
+  };
+}
+
+// ── Bluetooth / BLE (SHAPE ONLY — every method refuses) ──
+//
+// Nothing implements this yet, and it is wired up anyway. `bluetooth` has been
+// a manifest flag with no API behind it, so a plugin that correctly declared it
+// got `undefined` and crashed with "cannot read properties of undefined" — a
+// failure that names nothing and teaches nothing.
+//
+// Refusing BY NAME is the whole difference. The rule this layer runs on is that
+// absence is an answer, but only when it says what is absent.
+//
+// KEPT rather than dropped because BLE beacons are one of the few indoor
+// position signals that survive where GPS does not — which is precisely where
+// Ada Guide ends up the moment the user walks into a building.
+function createBluetoothAPI(): BluetoothAPI {
+  const refuse = (method: string) =>
+    new CapabilityUnavailableError(
+      `bluetooth.${method}`,
+      'Bluetooth is not implemented in this build — no BLE native module is installed. ' +
+        'The capability is declared so it fails by name rather than silently; nothing was scanned.',
+    );
+
+  return {
+    // These two answer `false` rather than throwing, because "is BLE usable?"
+    // is exactly the question a plugin should be allowed to ask before
+    // committing to a flow, and `false` is the true answer here.
+    async isSupported() { return false; },
+    async isEnabled() { return false; },
+    // scan() THROWS, because there is no honest empty result: an empty device
+    // list is a real finding ("nothing is advertising nearby") and returning
+    // one would report a scan that never happened.
+    async scan() { throw refuse('scan'); },
+  };
+}
+
+
+// ── Vision — on-device image understanding (SHAPE ONLY) ──
+//
+// Nothing implements this yet; every method refuses BY NAME. Declared now
+// because it is the last missing piece of Ada Guide and a solution should be
+// able to design against it before the native side exists.
+//
+// WHY IT IS NOT IN THE VISUAL DOMAIN: the freeze reserves Visual for the frame
+// TIMELINE and puts everything interpretive — what is in the scene, what the
+// sign says — ABOVE Device Bridge. This is that layer.
+//
+// FRAMES MUST NEVER LEAVE THE PHONE (Arie, 2026-08-15). Whoever implements
+// this: iOS Vision (VNRecognizeTextRequest / VNClassifyImageRequest) or
+// Android MLKit, both on-device and free per call. An implementation that
+// POSTs the frame anywhere satisfies these types and violates the design.
+function createVisionAPI(): VisionAPI {
+  // All three methods are implemented on-device via the ada-vision native module:
+  // assessQuality (pixel statistics), readText (VNRecognizeText), describe
+  // (VNClassifyImage). Frames never leave the phone.
+  return {
+    // "Can I see?" — true once the native module is present in the binary. On a
+    // build without it, adaVision.isSupported() answers false, and assessQuality
+    // below refuses cleanly (no crash), exactly the pre-module behaviour.
+    async isSupported() { return adaVision.isSupported(); },
+    // readText: on-device OCR on a published frame (native resolves the id →
+    // pixels). [] = looked, found no text (a real finding); throws = could not
+    // look (unknown/aged-out id). describe (VNClassifyImage) is the next pass.
+    async readText(frameId: string, opts?: { languages?: string[] }) {
+      const langs = opts?.languages;
+      if (langs != null && (!Array.isArray(langs) || langs.some((l) => typeof l !== 'string'))) {
+        throw refuseArgument('vision', 'readText', `languages must be an array of language codes, not ${shown(langs)}`, 'nothing was read');
+      }
+      return adaVision.readText(frameId, langs);
+    },
+    // describe: on-device labels (VNClassifyImage), not prose — the sentence is
+    // the skill's job. [] = looked, recognised nothing.
+    async describe(frameId: string, opts?: { maxLabels?: number }) {
+      // Checked here: a NaN/Infinity count would trap Swift's Int conversion (src/args.ts).
+      return adaVision.describe(frameId, countArg('vision', 'describe', 'maxLabels', opts?.maxLabels, 5, 50, 'nothing was labelled'));
+    },
+    // detectObjects: on-device located objects (bundled detector), each with a
+    // box — what a guidance loop reads to say WHERE a thing is, not just that the
+    // scene contains it. [] = looked, found nothing; throws = could not look.
+    async detectObjects(frameId: string, opts?: { maxItems?: number; minConfidence?: number }) {
+      const nothing = 'nothing was detected';
+      return adaVision.detectObjects(
+        frameId,
+        countArg('vision', 'detectObjects', 'maxItems', opts?.maxItems, 10, 50, nothing),
+        fractionArg('vision', 'detectObjects', 'minConfidence', opts?.minConfidence, 0.25, nothing),
+      );
+    },
+    // assessQuality: resolve the frame id to its LOCAL file, measure on-device,
+    // and record the result back onto the frame so a later read of
+    // VisualFrameRef.quality reflects it. Throwing here means "could not look"
+    // (unknown/aged-out id, or no native module) — never a measured verdict.
+    async assessQuality(frameId: string) {
+      // Quality was measured at publish; the pixels live in the native ring,
+      // resolved by id inside native. Null = the frame is unknown or has aged out
+      // of the ring — "could not look", never "looked and found nothing".
+      const q = adaVision.qualityById(frameId);
+      if (!q) {
+        throw new CapabilityUnavailableError(
+          'vision.assessQuality',
+          `No frame for id "${frameId}" — unknown or aged out of the ring. ` +
+            'This is "could not look", not a measurement.',
+        );
+      }
+      return q;
+    },
+  };
+}
+
+// ── Maps — place search, reverse geocoding, walking routes ──
+//
+// NOT on-device, unlike vision: the query and the coordinates it is given go to
+// Apple's map servers (the platform geocoder on Android). It never reads the
+// user's location — the caller passes every coordinate — so it is not a second
+// door to where the user is.
+//
+// search/route are the ada-maps module (MapKit, iOS only). reverseGeocode is the
+// SDK's one reverse geocode (expo-location), the same call the location
+// collector and the connector bridge make — so it works on Android and on a
+// build without ada-maps.
+function createMapsAPI(): MapsAPI {
+  // Refuse BY NAME before any native call: what this build or platform is
+  // missing, and that nothing left the phone.
+  const refuseIfMissing = (verb: string, nothing: string) => {
+    const missing = adaMaps.missingReason();
+    if (missing) {
+      throw new CapabilityUnavailableError(`maps.${verb}`, `maps.${verb} needs ${missing}; ${nothing}.`);
+    }
+  };
+
+  // Every argument is checked (searchArgs / coordinateArg) BEFORE the missing
+  // check and before anything crosses the bridge: a remote bundle is plain JS,
+  // and a malformed call refuses as INVALID_ARGUMENT instead of crashing Swift
+  // (NaN limit) or searching around 0,0 (`{ lat, lng }`).
+  return {
+    async isSupported() { return adaMaps.isSupported(); },
+    // [] = Apple looked and found nothing (a real finding); throws = could not
+    // look. The defaults (radiusM 3000, limit 8) live in searchArgs.
+    async search(query, opts) {
+      const args = searchArgs(query, opts);
+      refuseIfMissing('search', 'nothing was searched');
+      const raw = await adaMaps
+        .search(args.query, args.near, args.radiusM, args.limit)
+        .catch(err => { throw mapsFailure('search', err); });
+      return toMapsPlaces(raw, args.near);
+    },
+    // null = nothing at that point; throws = could not look.
+    async reverseGeocode(at) {
+      const point = coordinateArg('reverseGeocode', 'at', at, 'nothing was looked up');
+      const address = await adaMaps
+        .reverseGeocode(point)
+        .catch(err => { throw mapsFailure('reverseGeocode', err); });
+      return address ? toReverseGeocodedPlace(point, address) : null;
+    },
+    // null = Apple found no route. Never an empty 0 m route, which would read as
+    // "you have arrived". A remote bundle can pass any string as `mode`, so a
+    // mode this build cannot honour refuses rather than silently walking.
+    async route(from, to, opts) {
+      if (opts?.mode !== undefined && opts.mode !== 'walking') {
+        throw new CapabilityUnavailableError(
+          'maps.route',
+          `maps.route supports walking only, not "${String(opts.mode)}"; no route was requested.`,
+        );
+      }
+      const a = coordinateArg('route', 'from', from, 'no route was requested');
+      const b = coordinateArg('route', 'to', to, 'no route was requested');
+      refuseIfMissing('route', 'no route was requested');
+      const raw = await adaMaps
+        .route(a, b)
+        .catch(err => { throw mapsFailure('route', err); });
+      return raw ? toMapsRoute(raw) : null;
+    },
+  };
+}
+
+// ── Provider factory ───────────────────────────────────────────
+
+export interface DeviceProviderConfig {
+  /** Endpoint the connectivity check HEAD-fetches (host-injected, e.g. the app's
+   *  own health URL). Omitted → connectivity assumes reachable (no hardcoded URL). */
+  reachabilityUrl?: string;
+}
+
+/**
+ * The full device-primitive implementation a host registers once via
+ * setPluginNativeProvider. It is UNGATED — per-plugin capability gating and
+ * per-plugin filesystem scoping are applied by plugin-runtime's gatePluginNative.
+ */
+export function createDeviceProvider(config?: DeviceProviderConfig): PluginNative {
+  const connectivity = createConnectivityAPI(config?.reachabilityUrl);
+  return {
+    camera: createCameraAPI(),
+    location: createLocationAPI(),
+    // Only the per-plugin storageFor/fileSystemFor are exposed — NO shared
+    // `storage`/`fileSystem` bucket. The gate scopes by pluginId and fails
+    // closed without one, so a shared instance would be an unreachable
+    // (and dangerous) fallback. Each plugin gets its own namespace + db file /
+    // sandbox directory, or nothing.
+    storageFor: (pluginId: string) => createStorageAPI(pluginId),
+    biometrics: stubApi<BiometricsAPI>('biometrics'),
+    biometricsV2: createBiometricsAPIv2(),
+    notifications: createNotificationsAPI(),
+    haptics: createHapticsAPI(),
+    connectivity,
+    fileSystemFor: (pluginId: string) => createFileSystemAPI(pluginId),
+    cookies: createCookiesAPI(),
+    sharing: createSharingAPI(),
+    scanner: createScannerAPI(),
+    nfc: createNfcAPI(),
+    bluetooth: createBluetoothAPI(),
+    vision: createVisionAPI(),
+    maps: createMapsAPI(),
+  };
+}