@ateam-ai-mobile/expo 0.1.4 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ateam-ai-mobile/expo",
-  "version": "0.1.4",
+  "version": "0.1.7",
   "description": "Expo-backed providers for the ADAS SDK — haptics, bundle disk cache, attachment cache, device bridge.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,29 +9,45 @@
     "build": "tsup"
   },
   "dependencies": {
-    "@ateam-ai-mobile/core": "^0.1.4",
-    "@ateam-ai-mobile/plugin-runtime": "^0.1.4",
-    "@ateam-ai-mobile/ui": "^0.1.4"
+    "@ateam-ai-mobile/core": "0.1.7",
+    "@ateam-ai-mobile/plugin-runtime": "0.1.7",
+    "@ateam-ai-mobile/ui": "0.1.7"
   },
   "peerDependencies": {
     "@react-native-async-storage/async-storage": "*",
+    "@react-native-cookies/cookies": "*",
+    "@react-native-google-signin/google-signin": "*",
+    "expo": "*",
+    "expo-apple-authentication": "*",
+    "expo-background-fetch": "*",
     "expo-battery": "*",
     "expo-calendar": "*",
+    "expo-camera": "*",
+    "expo-clipboard": "*",
     "expo-contacts": "*",
     "expo-device": "*",
     "expo-file-system": "*",
     "expo-haptics": "*",
     "expo-linking": "*",
+    "expo-local-authentication": "*",
     "expo-location": "*",
+    "expo-modules-core": "*",
     "expo-network": "*",
     "expo-notifications": "*",
+    "expo-sharing": "*",
     "expo-sms": "*",
+    "expo-task-manager": "*",
     "expo-web-browser": "*",
     "react": ">=18",
-    "react-native": "*",
-    "expo-clipboard": "*"
+    "react-native": "*"
   },
   "peerDependenciesMeta": {
+    "@react-native-google-signin/google-signin": {
+      "optional": true
+    },
+    "expo-apple-authentication": {
+      "optional": true
+    },
     "expo-battery": {
       "optional": true
     },
@@ -55,6 +71,33 @@
     },
     "expo-sms": {
       "optional": true
+    },
+    "expo-camera": {
+      "optional": true
+    },
+    "expo-task-manager": {
+      "optional": true
+    },
+    "expo-background-fetch": {
+      "optional": true
+    },
+    "expo-local-authentication": {
+      "optional": true
+    },
+    "expo-sharing": {
+      "optional": true
+    },
+    "@react-native-cookies/cookies": {
+      "optional": true
+    },
+    "expo-linking": {
+      "optional": true
+    },
+    "expo": {
+      "optional": true
+    },
+    "expo-modules-core": {
+      "optional": true
     }
   },
   "exports": {
@@ -69,6 +112,42 @@
       "types": "./dist/createBridge.d.ts",
       "import": "./dist/createBridge.mjs",
       "require": "./dist/createBridge.js"
+    },
+    "./device-bridge": {
+      "react-native": "./src/device-bridge/index.ts",
+      "types": "./dist/device-bridge/index.d.ts",
+      "import": "./dist/device-bridge/index.mjs",
+      "require": "./dist/device-bridge/index.js"
+    },
+    "./device-bridge/*": {
+      "react-native": "./src/device-bridge/*.ts",
+      "types": "./dist/device-bridge/*.d.ts",
+      "import": "./dist/device-bridge/*.mjs",
+      "require": "./dist/device-bridge/*.js"
+    },
+    "./vision": {
+      "react-native": "./src/vision/index.ts",
+      "types": "./dist/vision/index.d.ts",
+      "import": "./dist/vision/index.mjs",
+      "require": "./dist/vision/index.js"
+    },
+    "./device": {
+      "react-native": "./src/device/createDeviceProvider.ts",
+      "types": "./dist/device/createDeviceProvider.d.ts",
+      "import": "./dist/device/createDeviceProvider.mjs",
+      "require": "./dist/device/createDeviceProvider.js"
+    },
+    "./oauth": {
+      "react-native": "./src/oauth/expoOAuth.tsx",
+      "types": "./dist/oauth/expoOAuth.d.ts",
+      "import": "./dist/oauth/expoOAuth.mjs",
+      "require": "./dist/oauth/expoOAuth.js"
+    },
+    "./bootstrap": {
+      "react-native": "./src/bootstrap.ts",
+      "types": "./dist/bootstrap.d.ts",
+      "import": "./dist/bootstrap.mjs",
+      "require": "./dist/bootstrap.js"
     }
   },
   "module": "dist/index.mjs",
@@ -76,9 +155,30 @@
   "react-native": "src/index.ts",
   "files": [
     "dist",
-    "src"
+    "src",
+    "ios",
+    "android",
+    "expo-module.config.json"
   ],
   "publishConfig": {
     "access": "public"
+  },
+  "devDependencies": {
+    "@react-native-cookies/cookies": "*",
+    "@react-native-google-signin/google-signin": "*",
+    "expo-apple-authentication": "*",
+    "expo-background-fetch": "*",
+    "expo-battery": "*",
+    "expo-calendar": "*",
+    "expo-camera": "*",
+    "expo-contacts": "*",
+    "expo-local-authentication": "*",
+    "expo-location": "*",
+    "expo-network": "*",
+    "expo-notifications": "*",
+    "expo-sharing": "*",
+    "expo-sms": "*",
+    "expo-task-manager": "*",
+    "react-native-nfc-manager": "*"
   }
 }

package/src/bootstrap.ts

@@ -0,0 +1,159 @@
+/**
+ * bootstrapExpoAdas — the single, self-contained SDK bootstrap (R10).
+ *
+ * The final high-level entry point of the "fat SDK / thin shell" arc: it folds
+ * the ~15 hand-wired seams the host used to assemble in its own adas.ts into ONE
+ * call, so the shell stops manually assembling platform providers/collectors/
+ * plugins. Internally it initializes, in the order the migrated code established:
+ * the Expo providers (haptics/bundle cache/clipboard/attachment cache + the
+ * device-primitive provider), the host-bundled native plugins, the plugin-WebView
+ * allow-list, native OAuth, the ACS reachability reporter, the L3 DeviceState
+ * engine (with the SDK's OWN collectors — the shell injects none), the plugin/
+ * UI-action navigator, and finally the core config+token bridge (initAdas).
+ *
+ * The API is DERIVED from the host's migrated adas.ts, not invented. Everything
+ * the host still owns is passed in as a small values-and-getters bag: endpoint
+ * getters (the host owns the dev/prod switch), the identity/token bridge, its
+ * branded Google client id, its host-bundled plugin resolvers, the native
+ * WebView module from its build, and its router callback.
+ *
+ * A SUBPATH (`@ateam-ai-mobile/expo/bootstrap`), like /device and /oauth: it
+ * statically pulls the optional expo native modules (via createDeviceProvider /
+ * the device-state collectors / the OAuth provider), so it must not sit on the
+ * package's main entry, which a host without those modules still has to build.
+ *
+ * The two physical reasoning paths stay DISTINCT and are wired as SEPARATE
+ * statements — never a merged bridge: LOCAL (the local tool registry + device
+ * state the plugin/voice runtime reads) and SERVER (the relay allow-list here;
+ * the DeviceBridge relay runtime itself is started by the host lifecycle, out of
+ * this module-load bootstrap's scope).
+ */
+import { initAdas, setAcsReachabilityReporter, type TokenProvider, type AdasUser, type AdasSession } from '@ateam-ai-mobile/core';
+import { setDeviceStateProvider, registerNativePlugin, registerPlatformDeviceTools, type RegisteredPlugin } from '@ateam-ai-mobile/plugin-runtime';
+import { setOAuthProvider, setUIActionNavigator, setPluginWebViewExtraHosts, type UIActionRoute } from '@ateam-ai-mobile/ui';
+
+import { setupExpoProviders, type ExpoAttachmentCache } from './index';
+import { createDeviceProvider } from './device/createDeviceProvider';
+import { createDeviceState } from './device-state';
+import { createExpoOAuthProvider } from './oauth/expoOAuth';
+import * as deviceConnectivity from './device-bridge/collectors/connectivity';
+import * as deviceLocation from './device-bridge/collectors/location';
+
+/** A host-bundled native plugin: one lazy resolver registered under one or more ids. */
+export interface NativePluginRegistration {
+  resolver: () => Promise<RegisteredPlugin>;
+  ids: string[];
+}
+
+export interface BootstrapExpoAdasOptions {
+  /**
+   * Endpoint GETTERS — the host owns the dev/prod env switch, so these are read
+   * live on every SDK request (never snapshotted). `core` is required; the rest
+   * are optional (voice/consumer-auth features light up when present).
+   */
+  urls: {
+    core: () => string;
+    voice?: () => string;
+    consumerAuth?: () => string;
+    /** Trusted extra host for plugin WebViews (the relay device-bridge auth flows). */
+    relay?: () => string;
+  };
+  /** The host's token bridge — outcome mapping (transient vs auth_failed) owned by the host. */
+  tokenProvider: TokenProvider;
+  /** Current user projection for chat routing (host reads its auth store). */
+  getUser: () => AdasUser | null;
+  /** Active tenant getter (signed-in tenant, falling back to the pre-auth pick). */
+  tenant?: () => string;
+  /** Adopt a freshly-minted session on tenant switch (host persists tenant-first, then logs in). */
+  onSession?: (session: AdasSession) => void | Promise<void>;
+  /** The host's bundled Google iOS client id, for the join/open-join OAuth path. */
+  googleIosClientId?: string;
+  /** Host-bundled native plugins (AuthWebView, ConnectionsPanel, …) — lazy resolvers. */
+  nativePlugins?: NativePluginRegistration[];
+  /** Native modules remote bundles may require() (e.g. react-native-webview) — from the host build. */
+  bundleModules?: Record<string, unknown>;
+  /** Pre-SDK AsyncStorage keys, so an existing install keeps its warm caches. */
+  storageKeys?: { attachmentIndex?: string; bundleIndex?: string };
+  /** Connectivity sink — the SDK reports fetch reachability up/down; the host feeds its banner. */
+  onReachabilityChange?: (up: boolean) => void;
+  /** Open the host's plugin screen for a UI-action chip (the host owns its router). */
+  navigateToPlugin: (route: UIActionRoute) => void;
+  /**
+   * Reachability probe URL for the device-primitive connectivity API. The host
+   * passes this EXPLICITLY (typically `${core}/health`) as a load-time snapshot —
+   * deliberately NOT derived from `urls.core()`, so a dev/E2E core override does
+   * not silently flow into the health probe (the asymmetry the host relied on).
+   */
+  reachabilityUrl?: string;
+}
+
+/**
+ * Wire the entire Expo-backed ADAS platform in one call. Run for its side effect
+ * at module load, before the router mounts. Returns the attachment cache so the
+ * host can hand it to anything that needs it (initAdas already received it).
+ */
+export function bootstrapExpoAdas(opts: BootstrapExpoAdasOptions): { attachmentCache: ExpoAttachmentCache } {
+  // Expo providers + the device-primitive implementation (props.device). The SDK
+  // owns createDeviceProvider; the shell injects only its reachability URL.
+  const { attachmentCache } = setupExpoProviders({
+    bundleModules: opts.bundleModules,
+    attachmentIndexKey: opts.storageKeys?.attachmentIndex,
+    bundleIndexKey: opts.storageKeys?.bundleIndex,
+    deviceProvider: createDeviceProvider({ reachabilityUrl: opts.reachabilityUrl }),
+  });
+
+  // Host-bundled native plugins: register each lazy resolver under its id aliases.
+  for (const plugin of opts.nativePlugins ?? []) {
+    for (const id of plugin.ids) registerNativePlugin(id, plugin.resolver);
+  }
+
+  // Plugin WebViews may navigate to the relay (device-bridge auth flows) —
+  // whitelist it alongside core/voice. Getter → live across env switches.
+  const relay = opts.urls.relay;
+  setPluginWebViewExtraHosts(() => (relay ? [relay()] : []));
+
+  // Native OAuth for the relocated auth screens (the ONLY native OAuth wiring).
+  setOAuthProvider(createExpoOAuthProvider({ googleIosClientId: opts.googleIosClientId }));
+
+  // ACS fetch outcomes feed the host's connectivity banner (any response = up,
+  // thrown fetch = down). The host's sink stays host-side (lazy, no load cycle).
+  if (opts.onReachabilityChange) {
+    const onReach = opts.onReachabilityChange;
+    setAcsReachabilityReporter({ up: () => onReach(true), down: () => onReach(false) });
+  }
+
+  // L3 DeviceState (props.deviceState) — the SEMANTIC layer, wired with the SDK's
+  // OWN device-bridge collectors. The shell injects none (the R10 payoff): an
+  // undeclared/unimplemented domain returns explicit `unknown`s, never a silent
+  // undefined. Kept a SEPARATE statement from the SERVER relay — the two
+  // reasoning paths never merge.
+  setDeviceStateProvider(
+    createDeviceState({ connectivity: deviceConnectivity, location: deviceLocation }),
+  );
+
+  // LOCAL device tools — register the static, host-owned platform tools
+  // (device.echo / device.ping) at load, so the device path answers even before
+  // any plugin bundle or sign-in: the platform tier deliberately does not depend
+  // on the thing being proved. A tenant's EXTERNAL device tools load on
+  // session-authenticated, which the host wires to its auth-session subscription
+  // via syncDeviceToolsForSession() — ambient, not voice-triggered.
+  registerPlatformDeviceTools();
+
+  // Plugin/UI-action chips delegate navigation to the host's router.
+  setUIActionNavigator(opts.navigateToPlugin);
+
+  // Core config + token bridge. URL getters (not snapshots) so the env switch
+  // flows through; identity/token bridge owned by the host.
+  initAdas({
+    coreUrl: opts.urls.core,
+    ...(opts.urls.voice ? { voiceUrl: opts.urls.voice } : {}),
+    ...(opts.urls.consumerAuth ? { consumerAuthUrl: opts.urls.consumerAuth } : {}),
+    ...(opts.onSession ? { onSession: opts.onSession } : {}),
+    ...(opts.tenant ? { tenant: opts.tenant } : {}),
+    getUser: opts.getUser,
+    tokenProvider: opts.tokenProvider,
+    attachmentCache,
+  });
+
+  return { attachmentCache };
+}

package/src/camera/CameraTaskHost.tsx

@@ -0,0 +1,175 @@
+/**
+ * The mounted half of the camera tasks — scanning and recording.
+ *
+ * The app renders this ONCE, near the root. It draws nothing until a plugin
+ * asks for a scan or a recording; then it takes over the screen with a live
+ * preview and settles the plugin's promise when the work is done.
+ *
+ * WHY IT IS VISIBLE, unlike VisualEngineHost's 1×1 invisible camera. These two
+ * tasks need the USER to aim: a barcode has to be framed, a clip has to point
+ * at something. An invisible scanner is not a privacy nicety, it is unusable —
+ * the user cannot tell what the camera sees or when it has read something.
+ *
+ * WHY IT CAN ALWAYS BE CANCELLED. The camera is on and pointed at whatever is
+ * in front of the person holding it. A capture surface with no way out is a
+ * trap; the cancel path settles the promise with a distinct CANCELLED code so
+ * the caller can tell "they chose not to" from "it broke".
+ */
+import React, { useEffect, useRef, useState } from 'react';
+import { Pressable, StyleSheet, Text, View } from 'react-native';
+import { CameraView, useCameraPermissions, useMicrophonePermissions } from 'expo-camera';
+
+import { cameraTasks, cameraError, type CameraTask } from './cameraTasks';
+
+/** How long a scan waits before giving up. */
+const SCAN_TIMEOUT_MS = 30_000;
+/** Ceiling on a single clip, so a forgotten recording cannot fill the disk. */
+const MAX_RECORD_MS = 60_000;
+
+export function CameraTaskHost(): React.ReactElement | null {
+  const [task, setTask] = useState<CameraTask | null>(cameraTasks.current());
+  const [camPermission, requestCamPermission] = useCameraPermissions();
+  const [micPermission, requestMicPermission] = useMicrophonePermissions();
+  const cameraRef = useRef<CameraView | null>(null);
+  /** Guards against a barcode firing twice before the task is cleared. */
+  const settling = useRef(false);
+
+  // Announce that a surface exists. Without this the broker rejects every
+  // request immediately, which is the correct behaviour when no host is
+  // mounted — a plugin must never await a promise nothing can settle.
+  useEffect(() => {
+    cameraTasks.setHostMounted(true);
+    return () => cameraTasks.setHostMounted(false);
+  }, []);
+
+  useEffect(() => cameraTasks.subscribe(() => {
+    settling.current = false;
+    setTask(cameraTasks.current());
+  }), []);
+
+  // Ask for permission when a task arrives, not at app start: a camera prompt
+  // with no visible reason attached is one users refuse.
+  useEffect(() => {
+    if (!task) return;
+    let cancelled = false;
+    void (async () => {
+      const cam = camPermission?.granted ? camPermission : await requestCamPermission();
+      if (cancelled) return;
+      if (!cam?.granted) {
+        cameraTasks.fail(cameraError(
+          'PERMISSION_DENIED',
+          'Camera permission was not granted. Enable it for this app in Settings > Privacy > Camera.',
+        ));
+        return;
+      }
+      if (task.kind === 'record' && task.opts.withAudio) {
+        const mic = micPermission?.granted ? micPermission : await requestMicPermission();
+        if (cancelled) return;
+        if (!mic?.granted) {
+          // Refuse rather than silently recording a silent video — a caller
+          // that asked for audio and got none has no way to find out.
+          cameraTasks.fail(cameraError(
+            'PERMISSION_DENIED',
+            'Microphone permission was not granted, so a video with sound cannot be recorded.',
+          ));
+        }
+      }
+    })();
+    return () => { cancelled = true; };
+  }, [task]);
+
+  // Scan timeout. A scan that never finds a code must END, and say so: leaving
+  // the camera up indefinitely is both a battery drain and a promise that
+  // never settles.
+  useEffect(() => {
+    if (task?.kind !== 'scan') return;
+    const ms = task.opts.timeoutMs ?? SCAN_TIMEOUT_MS;
+    const t = setTimeout(() => {
+      cameraTasks.fail(cameraError('TIMEOUT', `No barcode was found within ${Math.round(ms / 1000)}s.`));
+    }, ms);
+    return () => clearTimeout(t);
+  }, [task]);
+
+  // Recording runs for its duration and resolves with the file.
+  useEffect(() => {
+    if (task?.kind !== 'record' || !camPermission?.granted) return;
+    let cancelled = false;
+    const maxMs = Math.min(task.opts.maxDurationMs ?? 15_000, MAX_RECORD_MS);
+    const startedAt = Date.now();
+
+    void (async () => {
+      // A frame late is better than a crash: the ref is attached on the render
+      // after the task arrives.
+      await new Promise(r => setTimeout(r, 50));
+      if (cancelled || !cameraRef.current) return;
+      try {
+        const video = await cameraRef.current.recordAsync({ maxDuration: Math.ceil(maxMs / 1000) });
+        if (cancelled) return;
+        if (!video?.uri) {
+          cameraTasks.fail(cameraError('INTERNAL', 'Recording finished but produced no file.'));
+          return;
+        }
+        cameraTasks.complete({ uri: video.uri, durationMs: Date.now() - startedAt });
+      } catch (err: any) {
+        if (!cancelled) cameraTasks.fail(cameraError('INTERNAL', err?.message || 'Recording failed.'));
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+      // Stop the hardware if the surface goes away mid-take.
+      try { cameraRef.current?.stopRecording(); } catch { /* already stopped */ }
+    };
+  }, [task, camPermission?.granted]);
+
+  if (!task || !camPermission?.granted) return null;
+
+  const isScan = task.kind === 'scan';
+
+  return (
+    <View style={styles.overlay}>
+      <CameraView
+        ref={cameraRef}
+        style={StyleSheet.absoluteFill}
+        facing="back"
+        mode={isScan ? 'picture' : 'video'}
+        barcodeScannerSettings={
+          isScan && task.opts.formats?.length
+            ? { barcodeTypes: task.opts.formats as any }
+            : undefined
+        }
+        onBarcodeScanned={
+          isScan
+            ? ({ data, type }) => {
+                // onBarcodeScanned fires continuously while a code is in frame.
+                // Without this guard the same scan resolves, then tries to
+                // resolve an already-cleared task on the very next frame.
+                if (settling.current) return;
+                settling.current = true;
+                cameraTasks.complete({ data, format: type });
+              }
+            : undefined
+        }
+      />
+
+      <View style={styles.hud} pointerEvents="box-none">
+        <Text style={styles.hint}>
+          {isScan ? 'Point the camera at the code' : 'Recording…'}
+        </Text>
+        <Pressable style={styles.cancel} onPress={() => cameraTasks.cancel()} accessibilityRole="button">
+          <Text style={styles.cancelText}>Cancel</Text>
+        </Pressable>
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  overlay: { ...StyleSheet.absoluteFillObject, backgroundColor: '#000', zIndex: 9999 },
+  hud: { flex: 1, justifyContent: 'space-between', paddingVertical: 64, alignItems: 'center' },
+  hint: { color: '#fff', fontSize: 16, textAlign: 'center', paddingHorizontal: 24 },
+  cancel: { paddingHorizontal: 28, paddingVertical: 14, borderRadius: 24, backgroundColor: 'rgba(255,255,255,0.18)' },
+  cancelText: { color: '#fff', fontSize: 16, fontWeight: '600' },
+});
+
+export default CameraTaskHost;

package/src/camera/cameraTasks.ts

@@ -0,0 +1,129 @@
+/**
+ * The broker between a plugin's `await` and a mounted camera.
+ *
+ * WHY THIS EXISTS. expo-camera has no headless capture: scanning a barcode and
+ * recording a clip both require a MOUNTED `<CameraView>`. But a plugin calls
+ * `native.scanner.scanOnce()` and expects a promise — it has no way to mount
+ * anything, and it must not have to.
+ *
+ * So the API enqueues a TASK here and awaits it; `CameraTaskHost`, mounted once
+ * by the app, notices, shows the camera, does the work, and settles the
+ * promise. This is the same split as the Visual engine, for the same reason —
+ * and it is why `native.camera.scanBarcode` refuses and points here rather than
+ * pretending a function call can own a React lifecycle.
+ *
+ * ONE TASK AT A TIME, and it is the phone that says so: there is one camera. A
+ * second request while one is running is REJECTED rather than queued, because a
+ * queued scan would open the camera again minutes later, long after the user
+ * moved on and with no idea why it appeared.
+ */
+export interface ScanTask {
+  kind: 'scan';
+  opts: { formats?: string[]; timeoutMs?: number };
+  resolve: (v: { data: string; format: string }) => void;
+  reject: (e: Error) => void;
+}
+
+export interface RecordTask {
+  kind: 'record';
+  opts: { maxDurationMs?: number; withAudio?: boolean };
+  resolve: (v: { uri: string; durationMs: number | null }) => void;
+  reject: (e: Error) => void;
+}
+
+export type CameraTask = ScanTask | RecordTask;
+
+type Listener = () => void;
+
+/** Typed failure, so a caller can say something specific and true. */
+export function cameraError(code: string, message: string): Error {
+  const err: any = new Error(message);
+  err.code = code;
+  return err;
+}
+
+class CameraTaskBroker {
+  private task: CameraTask | null = null;
+  private listeners = new Set<Listener>();
+  /** Set by the host while a camera is mounted and ready. */
+  private hostMounted = false;
+
+  current(): CameraTask | null { return this.task; }
+
+  subscribe(fn: Listener): () => void {
+    this.listeners.add(fn);
+    return () => this.listeners.delete(fn);
+  }
+
+  /**
+   * Declare that a `CameraTaskHost` exists.
+   *
+   * Without it nothing will ever settle the promise, so a request must fail
+   * IMMEDIATELY and say why. The alternative is a plugin awaiting forever,
+   * which is the worst failure of the set: no error, no timeout, no camera,
+   * and a conversation that simply stops.
+   */
+  setHostMounted(mounted: boolean): void {
+    this.hostMounted = mounted;
+    if (!mounted) this.fail(cameraError('UNAVAILABLE', 'The camera surface was dismissed before the task completed.'));
+    this.notify();
+  }
+
+  isHostMounted(): boolean { return this.hostMounted; }
+
+  /** Enqueue and hand back the promise the plugin awaits. */
+  run<T>(kind: CameraTask['kind'], opts: any): Promise<T> {
+    if (!this.hostMounted) {
+      return Promise.reject(cameraError(
+        'UNAVAILABLE',
+        'No camera surface is mounted in this app, so the camera cannot be shown. ' +
+          'The host must render <CameraTaskHost /> once, near the app root.',
+      ));
+    }
+    if (this.task) {
+      return Promise.reject(cameraError(
+        'BUSY',
+        `The camera is already in use (${this.task.kind}). Only one camera task can run at a time.`,
+      ));
+    }
+    return new Promise<T>((resolve, reject) => {
+      this.task = { kind, opts, resolve, reject } as unknown as CameraTask;
+      this.notify();
+    });
+  }
+
+  /** Settle the running task successfully and clear it. */
+  complete(value: any): void {
+    const t = this.task;
+    if (!t) return;
+    this.task = null;
+    this.notify();
+    t.resolve(value);
+  }
+
+  /** Settle the running task with a failure and clear it. */
+  fail(err: Error): void {
+    const t = this.task;
+    if (!t) return;
+    this.task = null;
+    this.notify();
+    t.reject(err);
+  }
+
+  /**
+   * The user backed out.
+   *
+   * A distinct code, because "the user chose not to" is not a malfunction and
+   * a guide should say something different about it than about a broken lens.
+   */
+  cancel(): void {
+    this.fail(cameraError('CANCELLED', 'Cancelled — the camera was dismissed before anything was captured.'));
+  }
+
+  private notify(): void {
+    for (const fn of this.listeners) { try { fn(); } catch { /* a bad listener is not the broker's problem */ } }
+  }
+}
+
+/** One broker per app: there is one camera. */
+export const cameraTasks = new CameraTaskBroker();