@ateam-ai-mobile/expo 0.1.5 → 0.1.8

package/src/maps/normalize.ts

@@ -0,0 +1,225 @@
+// Pure shaping for native.maps — no Expo, no React Native, so it runs under
+// plain `node --test` (tests/adaMapsNormalize.test.mjs pins it).
+//
+// The native side hands back loose dictionaries — AdaMaps (MapKit) for search
+// and route, expo-location's geocoder for reverse geocoding. This turns them
+// into the typed MapsAPI shapes, and one set of failure codes. Unknown is
+// `null`, never '' or 0: an empty street reads as a street with no name, and a
+// 0 m route reads as "you have arrived".
+//
+// It also checks what a caller sends BEFORE it crosses the bridge (searchArgs,
+// coordinateArg). A remote bundle is plain JS at runtime, so the types promise
+// nothing: a NaN or Infinity `limit` traps Swift's Int conversion and kills the
+// app, and a `{ lat, lng }` near would search around 0,0 and answer "found
+// nothing" with confidence.
+
+import type {
+  MapsAddress,
+  MapsCoordinate,
+  MapsPlace,
+  MapsRoute,
+  MapsRouteStep,
+} from '@ateam-ai-mobile/plugin-runtime';
+import { distanceOf } from '../geo';
+import { countArg, refuseArgument as refuse, shown, type ArgumentError } from '../args';
+
+/** An address as the native geocoders spell it. AdaMaps sends exactly these
+ *  keys; expo-location sends these plus `subregion`/`timezone`/
+ *  `formattedAddress`, which MapsAddress does not carry. */
+export interface RawMapsAddress {
+  name?: string | null;
+  street?: string | null;
+  streetNumber?: string | null;
+  district?: string | null;
+  city?: string | null;
+  region?: string | null;
+  postalCode?: string | null;
+  country?: string | null;
+  isoCountryCode?: string | null;
+}
+
+/** One AdaMaps search hit (AdaMapsModule.place). */
+export interface RawMapsPlace {
+  name: string | null;
+  latitude: number;
+  longitude: number;
+  /** MKPointOfInterestCategory raw value, e.g. "MKPOICategoryPharmacy". */
+  category: string | null;
+  address: RawMapsAddress;
+}
+
+/** An AdaMaps walking route (AdaMapsModule.route) — distances in metres,
+ *  expectedTravelTime in SECONDS, as MapKit reports them. */
+export interface RawMapsRoute {
+  distance: number;
+  expectedTravelTime: number;
+  steps: Array<{ instructions: string | null; distance: number; notice: string | null; polyline: MapsCoordinate[] }>;
+  polyline: MapsCoordinate[];
+}
+
+/** The three ways a maps call can fail to look — see MapsAPI. */
+export type MapsFailureCode = 'UNAVAILABLE' | 'OFFLINE' | 'THROTTLED';
+
+/** A malformed call, refused before anything is sent. Not a fourth way to fail
+ *  to look: retrying will not help, fixing the call will. */
+export type MapsArgumentError = ArgumentError;
+
+const SEARCH_RADIUS_DEFAULT_M = 3000;
+/** Keeps the region MapKit is handed a small, valid one. A "near" search wider
+ *  than this is a different question. */
+const SEARCH_RADIUS_MAX_M = 100_000;
+const SEARCH_LIMIT_DEFAULT = 8;
+const SEARCH_LIMIT_MAX = 25;
+
+const text = (v: unknown): string | null =>
+  typeof v === 'string' && v.trim() !== '' ? v : null;
+
+const refuseArgument = (verb: string, problem: string, nothing: string): MapsArgumentError =>
+  refuse('maps', verb, problem, nothing);
+
+/** A caller's coordinate, checked and copied to exactly `{ latitude, longitude }`.
+ *  Anything else — `{ lat, lng }`, strings, NaN, out of range — refuses BY NAME
+ *  rather than being sent as 0,0 or NaN. */
+export function coordinateArg(verb: string, name: string, value: unknown, nothing: string): MapsCoordinate {
+  const c = value as { latitude?: unknown; longitude?: unknown } | null | undefined;
+  const latitude = c?.latitude, longitude = c?.longitude;
+  if (
+    typeof latitude === 'number' && Number.isFinite(latitude) && Math.abs(latitude) <= 90 &&
+    typeof longitude === 'number' && Number.isFinite(longitude) && Math.abs(longitude) <= 180
+  ) {
+    return { latitude, longitude };
+  }
+  throw refuseArgument(
+    verb,
+    `${name} must be { latitude, longitude } numbers (latitude -90..90, longitude -180..180), not ${shown(value)}`,
+    nothing,
+  );
+}
+
+/** search's arguments, checked and defaulted (radiusM 3000, limit 8). `limit`
+ *  is floored and capped at 25; everything else out of range refuses. */
+export function searchArgs(
+  query: unknown,
+  opts: { near?: unknown; radiusM?: unknown; limit?: unknown } | null | undefined,
+): { query: string; near: MapsCoordinate | null; radiusM: number; limit: number } {
+  const nothing = 'nothing was searched';
+  if (typeof query !== 'string' || query.trim() === '') {
+    throw refuseArgument('search', `query must be a non-empty string, not ${shown(query)}`, nothing);
+  }
+  const near = opts?.near == null ? null : coordinateArg('search', 'near', opts.near, nothing);
+  const radiusM = opts?.radiusM ?? SEARCH_RADIUS_DEFAULT_M;
+  if (typeof radiusM !== 'number' || !(radiusM > 0 && radiusM <= SEARCH_RADIUS_MAX_M)) {
+    throw refuseArgument(
+      'search', `radiusM must be metres above 0 and at most ${SEARCH_RADIUS_MAX_M}, not ${shown(radiusM)}`, nothing);
+  }
+  const limit = countArg('maps', 'search', 'limit', opts?.limit, SEARCH_LIMIT_DEFAULT, SEARCH_LIMIT_MAX, nothing);
+  return { query, near, radiusM, limit };
+}
+
+const point = (c: MapsCoordinate): MapsCoordinate => ({
+  latitude: Number(c.latitude),
+  longitude: Number(c.longitude),
+});
+
+export function toMapsAddress(raw: RawMapsAddress | null | undefined): MapsAddress {
+  const r = raw ?? {};
+  return {
+    name: text(r.name),
+    street: text(r.street),
+    streetNumber: text(r.streetNumber),
+    district: text(r.district),
+    city: text(r.city),
+    region: text(r.region),
+    postalCode: text(r.postalCode),
+    country: text(r.country),
+    isoCountryCode: text(r.isoCountryCode),
+  };
+}
+
+/** "MKPOICategoryPharmacy" → "Pharmacy": the vocabulary term, without the
+ *  framework's prefix. */
+export function toMapsCategory(raw: unknown): string | null {
+  const c = text(raw);
+  return c ? c.replace(/^MKPOICategory/, '') || null : null;
+}
+
+/** Search hits → places. `distanceM` is straight-line from `near`, and only
+ *  when the caller gave one — a distance from nowhere would be invented. */
+export function toMapsPlaces(raw: RawMapsPlace[] | null | undefined, near: MapsCoordinate | null): MapsPlace[] {
+  return (raw ?? []).map(r => {
+    const coordinate = point(r);
+    return {
+      name: text(r.name),
+      coordinate,
+      address: toMapsAddress(r.address),
+      category: toMapsCategory(r.category),
+      distanceM: near ? distanceOf([near, coordinate]) : null,
+    };
+  });
+}
+
+/** A reverse-geocoded address → a place AT the point asked about. The platform
+ *  geocoder returns an address, not a snapped point or a category. */
+export function toReverseGeocodedPlace(at: MapsCoordinate, address: MapsAddress): MapsPlace {
+  return {
+    name: address.name,
+    coordinate: point(at),
+    address,
+    category: null,
+    distanceM: null,
+  };
+}
+
+/** A MapKit route → MapsRoute. Seconds become ms; every step is kept, including
+ *  Apple's empty-instruction origin step, so indexes match Apple's. */
+export function toMapsRoute(raw: RawMapsRoute): MapsRoute {
+  const steps: MapsRouteStep[] = (raw.steps ?? []).map(s => ({
+    instructions: typeof s.instructions === 'string' ? s.instructions : '',
+    distanceM: Number(s.distance),
+    notice: text(s.notice),
+    polyline: (s.polyline ?? []).map(point),
+  }));
+  return {
+    mode: 'walking',
+    distanceM: Number(raw.distance),
+    expectedTravelTimeMs: Math.round(Number(raw.expectedTravelTime) * 1000),
+    steps,
+    polyline: (raw.polyline ?? []).map(point),
+  };
+}
+
+/**
+ * A native rejection → an Error whose `code` is one of MapsAPI's three.
+ *
+ * AdaMaps already rejects with OFFLINE / THROTTLED / UNAVAILABLE. expo-location
+ * (reverseGeocode) has its own codes: on iOS a CLError.network becomes
+ * ERR_GEOCODING_NETWORK, which Apple uses for BOTH a lost connection and a rate
+ * limit — so it maps to OFFLINE and the message says it may be either. Anything
+ * else is UNAVAILABLE, with the platform's own words kept beside ours.
+ */
+export function mapsFailure(verb: string, err: unknown): Error & { code: MapsFailureCode } {
+  const nativeCode = String((err as any)?.code ?? '');
+  const detail = String((err as any)?.message ?? err ?? '').trim();
+  let code: MapsFailureCode;
+  let why: string;
+  if (nativeCode === 'THROTTLED') {
+    code = 'THROTTLED';
+    why = 'Apple is rate-limiting map requests from this app — wait before retrying';
+  } else if (nativeCode === 'OFFLINE') {
+    code = 'OFFLINE';
+    why = 'the map service could not be reached — the phone may be offline';
+  } else if (nativeCode === 'ERR_GEOCODING_NETWORK') {
+    code = 'OFFLINE';
+    why = 'the geocoder could not be reached — the phone may be offline, or Apple is ' +
+      'rate-limiting requests (iOS reports both the same way)';
+  } else {
+    code = 'UNAVAILABLE';
+    why = 'the map service failed';
+  }
+  const failure = new Error(
+    `maps.${verb} could not look: ${why}. This is not "found nothing".` +
+      (detail ? ` (${nativeCode ? nativeCode + ': ' : ''}${detail})` : ''),
+  ) as Error & { code: MapsFailureCode };
+  failure.code = code;
+  return failure;
+}

package/src/oauth/expoOAuth.tsx

@@ -0,0 +1,113 @@
+/**
+ * @ateam-ai-mobile/expo/oauth — the native OAuth provider for the relocated
+ * auth screens (LoginScreen / JoinScreen / OpenJoinScreen in @ateam-ai-mobile/ui).
+ *
+ * This is the ONLY place @react-native-google-signin + expo-apple-authentication
+ * are imported. The `ui` package stays native-free: its screens call
+ * getOAuthProvider() for the id_token acquisition + the real Apple HIG button.
+ *
+ * Deliberately a SUBPATH (`@ateam-ai-mobile/expo/oauth`), not part of the main
+ * entry — same rule as `/bridge` and `/device`: a host that doesn't install
+ * these native modules must still be able to build @ateam-ai-mobile/expo.
+ *
+ * Behaviour is ported verbatim from the app's old login.tsx so the iPhone
+ * parity gate sees no change:
+ *   - Google: configure({ webClientId, iosClientId }) → hasPlayServices →
+ *     signIn → normalize the v15-vs-older id_token shape. A missing iosClientId
+ *     silently falls back to a web flow (unchanged); the caller gates on
+ *     webClientId, so we never reach here without one for the login path.
+ *   - a user-cancel (SIGN_IN_CANCELLED / IN_PROGRESS / ERR_REQUEST_CANCELED)
+ *     resolves to null — the screen treats null as "no error", never a red flash.
+ */
+import React from 'react';
+import { Platform } from 'react-native';
+import {
+  GoogleSignin,
+  statusCodes,
+  type ConfigureParams,
+} from '@react-native-google-signin/google-signin';
+import * as AppleAuthentication from 'expo-apple-authentication';
+import type { OAuthProvider, OAuthGoogleConfig } from '@ateam-ai-mobile/ui';
+
+const NOOP = () => {};
+
+export interface ExpoOAuthConfig {
+  /**
+   * The host's bundled Google client ids, used by the join / open-join screens
+   * that carry no tenant config (they pass no cfg to signInWithGoogle). The
+   * login screen passes the tenant's configured ids and overrides these.
+   */
+  googleWebClientId?: string;
+  googleIosClientId?: string;
+}
+
+/**
+ * Build the native OAuth provider. Wire it once at startup:
+ *   setOAuthProvider(createExpoOAuthProvider({ googleWebClientId, googleIosClientId }));
+ */
+export function createExpoOAuthProvider(host: ExpoOAuthConfig = {}): OAuthProvider {
+  return {
+    async signInWithGoogle(cfg?: OAuthGoogleConfig): Promise<string | null> {
+      const webClientId = cfg?.webClientId || host.googleWebClientId || '';
+      const iosClientId = cfg?.iosClientId || host.googleIosClientId || '';
+      // configure is idempotent + cheap; do it at sign-in time so the tenant's
+      // ids are always current (replaces login.tsx's configure effect).
+      const params: ConfigureParams = { webClientId };
+      if (iosClientId) (params as any).iosClientId = iosClientId;
+      GoogleSignin.configure(params);
+      try {
+        // android-only; no-op on iOS. Called defensively, as before.
+        await GoogleSignin.hasPlayServices({ showPlayServicesUpdateDialog: true });
+        const result: any = await GoogleSignin.signIn();
+        // v15+ returns { data: { idToken } }; older returns { idToken }.
+        return result?.data?.idToken || result?.idToken || null;
+      } catch (err: any) {
+        const code = err?.code;
+        if (code === statusCodes.SIGN_IN_CANCELLED || code === statusCodes.IN_PROGRESS) {
+          return null;
+        }
+        throw err;
+      }
+    },
+
+    async signInWithApple(): Promise<string | null> {
+      try {
+        const credential = await AppleAuthentication.signInAsync({
+          requestedScopes: [
+            AppleAuthentication.AppleAuthenticationScope.FULL_NAME,
+            AppleAuthentication.AppleAuthenticationScope.EMAIL,
+          ],
+        });
+        return credential.identityToken || null;
+      } catch (err: any) {
+        // ERR_REQUEST_CANCELED = the user dismissed the sheet.
+        if (err?.code === 'ERR_REQUEST_CANCELED') return null;
+        throw err;
+      }
+    },
+
+    async isAppleAvailable(): Promise<boolean> {
+      if (Platform.OS !== 'ios') return false;
+      try {
+        return await AppleAuthentication.isAvailableAsync();
+      } catch {
+        return false;
+      }
+    },
+
+    renderAppleButton({ onPress, disabled, style }): React.ReactNode {
+      // Apple's HIG requires their own styled button when Apple Sign-In sits
+      // alongside other providers. Same chrome the app shipped: CONTINUE /
+      // BLACK / fully-rounded. Layout (width/height) comes from the screen.
+      return (
+        <AppleAuthentication.AppleAuthenticationButton
+          buttonType={AppleAuthentication.AppleAuthenticationButtonType.CONTINUE}
+          buttonStyle={AppleAuthentication.AppleAuthenticationButtonStyle.BLACK}
+          cornerRadius={999}
+          style={style as any}
+          onPress={disabled ? NOOP : onPress}
+        />
+      );
+    },
+  };
+}

package/src/vision/analysis.js

@@ -0,0 +1,80 @@
+// Frame-quality analysis — the REFERENCE algorithm, in plain JS so it can be
+// unit-tested exhaustively without a device. The native iOS (Objective-C++) and
+// Android (Kotlin) implementations mirror this math and these thresholds exactly;
+// this file is the spec they must match, and the thing the tests exercise.
+//
+// Input is a luma (grayscale) plane — one byte per pixel, 0..255. We subsample
+// to a fixed grid so the work is bounded and thresholds are resolution-independent,
+// then derive:
+//   exposure   from mean luminance          (good | dark | bright)
+//   obstructed from darkness + low variance  (covered lens vs a real scene)
+//   blur       from variance of the Laplacian (the classic focus metric)
+
+export const THRESHOLDS = {
+  grid: 128,
+  exposureDark: 45,
+  exposureBright: 205,
+  obstructedMean: 22,
+  obstructedStd: 8,
+  blurSharp: 120,
+  blurSlight: 30,
+};
+
+/**
+ * @param {number} width
+ * @param {number} height
+ * @param {Uint8Array|number[]} luma  row-major luma bytes
+ * @param {number} [rowStride]        bytes per row (defaults to width)
+ * @returns {{blur:string, exposure:string, obstructed:boolean|null}}
+ */
+export function assessLuma(width, height, luma, rowStride) {
+  const stride = rowStride || width;
+  const S = THRESHOLDS.grid;
+  if (!width || !height || !luma || luma.length === 0) {
+    return { blur: 'unknown', exposure: 'unknown', obstructed: null };
+  }
+
+  // Grid dimensions, capped at S. Sample coordinates span the FULL frame
+  // [0, width-1] / [0, height-1] — the first sample is the top-left pixel and
+  // the last is the bottom-right, so no edge (a bright window, an occlusion,
+  // strong detail) is ever omitted. A floor-step + capped-count scheme would
+  // systematically miss the right/bottom strip when the size isn't a multiple
+  // of S.
+  const cols = Math.min(S, width);
+  const rows = Math.min(S, height);
+  const sxAt = (gx) => (cols > 1 ? Math.round((gx * (width - 1)) / (cols - 1)) : 0);
+  const syAt = (gy) => (rows > 1 ? Math.round((gy * (height - 1)) / (rows - 1)) : 0);
+
+  const grid = new Uint8Array(cols * rows);
+  let n = 0, sum = 0, sumSq = 0;
+  for (let gy = 0; gy < rows; gy++) {
+    const rowBase = syAt(gy) * stride;
+    for (let gx = 0; gx < cols; gx++) {
+      const v = luma[rowBase + sxAt(gx)] & 0xff;
+      grid[gy * cols + gx] = v;
+      sum += v; sumSq += v * v; n++;
+    }
+  }
+  if (n === 0) return { blur: 'unknown', exposure: 'unknown', obstructed: null };
+
+  const mean = sum / n;
+  const variance = Math.max(0, sumSq / n - mean * mean);
+  const std = Math.sqrt(variance);
+
+  let lapSum = 0, lapSumSq = 0, lapN = 0;
+  for (let y = 1; y < rows - 1; y++) {
+    for (let x = 1; x < cols - 1; x++) {
+      const i = y * cols + x;
+      const lap = 4 * grid[i] - grid[i - 1] - grid[i + 1] - grid[i - cols] - grid[i + cols];
+      lapSum += lap; lapSumSq += lap * lap; lapN++;
+    }
+  }
+  const lapVar = lapN > 0 ? Math.max(0, lapSumSq / lapN - (lapSum / lapN) ** 2) : 0;
+
+  const t = THRESHOLDS;
+  const exposure = mean < t.exposureDark ? 'dark' : (mean > t.exposureBright ? 'bright' : 'good');
+  const obstructed = mean < t.obstructedMean && std < t.obstructedStd;
+  const blur = lapVar > t.blurSharp ? 'sharp' : (lapVar > t.blurSlight ? 'slight' : 'severe');
+
+  return { blur, exposure, obstructed };
+}

package/src/vision/index.ts

@@ -0,0 +1,146 @@
+// ada-vision — on-device image understanding, our own native code (no camera lib).
+//
+// On-device, frames never leave the phone:
+//   assessQuality(uri)          — one-shot quality of a LOCAL frame file.
+//   startVision()/onVisionFrame — the headless camera session that publishes a
+//                                 timeline frame (id + quality, never pixels) at a
+//                                 cadence; readText/describe/detectObjects resolve
+//                                 a published id ON-DEVICE.
+//
+// The luma math mirrors ./analysis.js (which has the exhaustive unit tests).
+//
+// requireOptionalNativeModule: on a binary WITHOUT the native module, the import
+// is null, isSupported() is false, and the session calls refuse cleanly (no crash).
+
+import type { ComponentType } from 'react';
+import { requireOptionalNativeModule } from 'expo-modules-core';
+import { requireNativeView } from 'expo';
+
+/** TEST-ONLY live preview bound to the same headless session (so a tester can
+ *  aim). The real Guide runs headless and never mounts this. Null on a binary
+ *  without the native view, so importing this module never crashes. */
+export const CameraPreview: ComponentType<any> | null = (() => {
+  try { return requireNativeView('AdaVision'); } catch { return null; }
+})();
+
+export interface RawFrameQuality {
+  blur: 'sharp' | 'slight' | 'severe' | 'unknown';
+  exposure: 'good' | 'dark' | 'bright' | 'unknown';
+  /** true = lens covered; false = clearly not; null = not assessed. */
+  obstructed: boolean | null;
+}
+
+interface Subscription { remove(): void }
+
+/** A published timeline frame from the vision session (metadata only — never
+ *  pixels; the buffer stays in the native ring, resolved by id). */
+export interface VisionFrame {
+  id: string;
+  ts: number;
+  expiresAt: number;
+  blur: RawFrameQuality['blur'];
+  exposure: RawFrameQuality['exposure'];
+  obstructed: RawFrameQuality['obstructed'];
+}
+
+/** One OCR result on a frame — matches the SDK's VisionText. */
+export interface VisionText {
+  text: string;
+  /** 0..1 recogniser confidence (never a 1.0 filler). */
+  confidence: number | null;
+  /** Normalised 0..1 box, origin TOP-left, in the UPRIGHT portrait frame (native
+   *  rotates frames at capture) — x runs from the user's left to their right. */
+  box?: { x: number; y: number; width: number; height: number };
+}
+
+/** One classifier label — a vocabulary term, NOT prose. Matches VisionLabel. */
+export interface VisionLabel {
+  label: string;
+  confidence: number | null;
+}
+
+/** One detected object — a located item with a box, from the bundled detector. */
+export interface VisionObject {
+  /** Open-Images class name (e.g. "Car", "Traffic light", "Building", "Person"). */
+  label: string;
+  /** 0..1 detector confidence. */
+  confidence: number | null;
+  /** Normalised 0..1 box, origin TOP-left, in the UPRIGHT portrait frame (native
+   *  rotates frames at capture) — x runs from the user's left to their right. */
+  box?: { x: number; y: number; width: number; height: number };
+}
+
+interface AdaVisionNative {
+  isSupported(): boolean;
+  assessQuality(uri: string): Promise<RawFrameQuality>;
+  startVision(intervalMs: number): Promise<void>;
+  stopVision(): void;
+  visionRetentionMs(): number;
+  qualityById(id: string): RawFrameQuality | null;
+  readText(id: string, languages: string[] | null): Promise<VisionText[]>;
+  describe(id: string, maxLabels: number): Promise<VisionLabel[]>;
+  detectObjects(id: string, maxItems: number, minConfidence: number): Promise<VisionObject[]>;
+  addListener(event: 'visionFrame', cb: (f: VisionFrame) => void): Subscription;
+}
+
+const native = requireOptionalNativeModule<AdaVisionNative>('AdaVision');
+
+/** Is the native vision module present in this binary? */
+export function isSupported(): boolean {
+  try { return native?.isSupported() ?? false; } catch { return false; }
+}
+
+/** One-shot: measure a frame's quality from its LOCAL file. Throws if it cannot look. */
+export async function assessQuality(uri: string): Promise<RawFrameQuality> {
+  if (!native) throw new Error('ada-vision native module not present in this build');
+  return native.assessQuality(uri);
+}
+
+// ── Vision session (feeds the Visual Engine) ──
+
+/** Start the vision session — publishes a timeline frame every `intervalMs`. */
+export async function startVision(intervalMs = 1000): Promise<void> {
+  if (!native) throw new Error('ada-vision native module not present in this build');
+  return native.startVision(intervalMs);
+}
+
+/** Stop the vision session and release the camera. */
+export function stopVision(): void {
+  native?.stopVision?.();
+}
+
+/** Subscribe to published timeline frames (id + quality + expiry; no pixels). */
+export function onVisionFrame(cb: (f: VisionFrame) => void): Subscription {
+  if (!native) return { remove() {} };
+  return native.addListener('visionFrame', cb);
+}
+
+/** How far back the native ring can still resolve a frame id (ms). */
+export function visionRetentionMs(): number {
+  return native?.visionRetentionMs?.() ?? 0;
+}
+
+/** Resolve a published frame id → its measured quality (null if evicted). */
+export function qualityById(id: string): RawFrameQuality | null {
+  return native?.qualityById?.(id) ?? null;
+}
+
+/** On-device OCR on a published frame. [] = looked, no text; throws = couldn't look. */
+export async function readText(id: string, languages?: string[]): Promise<VisionText[]> {
+  if (!native) throw new Error('ada-vision native module not present in this build');
+  return native.readText(id, languages ?? null);
+}
+
+/** On-device image classification → labels (not prose). [] = nothing recognised. */
+export async function describe(id: string, maxLabels = 5): Promise<VisionLabel[]> {
+  if (!native) throw new Error('ada-vision native module not present in this build');
+  return native.describe(id, maxLabels);
+}
+
+/** On-device object detection (bundled YOLOv8n, Open-Images vocabulary) → located
+ *  items with boxes. [] = looked, found nothing above `minConfidence`; throws =
+ *  couldn't look (id aged out, or the model isn't in this build). */
+export async function detectObjects(id: string, maxItems = 10, minConfidence = 0.25): Promise<VisionObject[]> {
+  if (!native) throw new Error('ada-vision native module not present in this build');
+  return native.detectObjects(id, maxItems, minConfidence);
+}

package/src/vision/ring.js

@@ -0,0 +1,35 @@
+// Reference for the native VisionSession frame ring (ios/AdaVisionModule.swift).
+// The native side mirrors this; the tests pin the invariant GPT flagged:
+//   a frame id from an OLD camera session, or one evicted from the ring, must
+//   NEVER resolve. "Cannot look at that frame" (null) must never be confusable
+//   with a stale hit from a previous session.
+//
+// Two independent guarantees, both modelled here: ids are generation-scoped
+// (vf_<gen>_<ts>), AND the ring is cleared on start(). Either alone prevents a
+// stale resolve; together it can't happen.
+
+export function createRing({ cap = 12, intervalMs = 1000 } = {}) {
+  let generation = 0;
+  let entries = []; // { id, quality }
+
+  return {
+    /** A new camera session: bump generation, clear the ring. */
+    start() { generation += 1; entries = []; },
+    /** Session ended: nothing is resolvable. */
+    stop() { entries = []; },
+    /** The ring's actual retention (ms) — feeds the engine's window clamp. */
+    retentionMs() { return cap * intervalMs; },
+    /** Publish a frame → mint a generation-scoped id, retain (bounded). */
+    publish(quality, tsMs) {
+      const id = `vf_${generation}_${tsMs}`;
+      entries.push({ id, quality });
+      if (entries.length > cap) entries.splice(0, entries.length - cap);
+      return id;
+    },
+    /** Resolve by id → quality, or null when evicted / old-generation / unknown. */
+    qualityById(id) {
+      const e = entries.find(x => x.id === id);
+      return e ? e.quality : null;
+    },
+  };
+}