@ateam-ai-mobile/expo 0.1.7 → 0.1.8

package/ios/AdaVisionModule.swift

@@ -154,6 +154,17 @@ enum LumaMath {
 // frame/sec, not 24). Emits `visionFrame` {id, ts, quality, expiresAt} per
 // published frame; `qualityById` / (later) readText resolve the id inside here.
 // The buffer/pixels never cross to JS.
+//
+// ORIENTATION — frames are UPRIGHT PORTRAIT at the source. The sensor delivers
+// landscape buffers; `orientUpright` rotates the data-output connection to
+// portrait (the host app is portrait-locked) every time configureAndRun creates
+// that connection, so AVFoundation hands over already-upright buffers. The luma
+// quality read, the ring's CGImage and every Vision / Core ML call therefore see
+// the same upright image the user is pointing at, and boxes come back in upright
+// coordinates (x = 0 is the user's LEFT). This is the ONE rotation mechanism:
+// VNImageRequestHandler is always given the default .up orientation — passing an
+// orientation there as well would rotate twice. Back camera only (position:
+// .back), so nothing is mirrored: image-left is scene-left.
 final class VisionSession: NSObject, AVCaptureVideoDataOutputSampleBufferDelegate {
   private let session = AVCaptureSession()
   private let queue = DispatchQueue(label: "ai.ateam.adavision.session")
@@ -175,11 +186,41 @@ final class VisionSession: NSObject, AVCaptureVideoDataOutputSampleBufferDelegat
   private var ring: [Retained] = []
   private static let ciContext = CIContext(options: nil)
 
+  // A straight copy: the buffer is already upright (see ORIENTATION above), so no
+  // rotation happens here.
   private static func makeCGImage(_ pb: CVPixelBuffer) -> CGImage? {
     let ci = CIImage(cvPixelBuffer: pb)
     return ciContext.createCGImage(ci, from: ci.extent)
   }
 
+  /// Rotate a video-data-output connection so its sample buffers arrive UPRIGHT
+  /// in portrait. AVFoundation physically rotates the buffers, so every consumer
+  /// downstream gets the upright image. 90° is portrait (videoOrientation
+  /// .portrait below iOS 17); 0° is the sensor's native landscape. Returns false
+  /// when the connection can't rotate — frames would then stay sensor-landscape.
+  private static func orientUpright(_ connection: AVCaptureConnection) -> Bool {
+    if #available(iOS 17.0, *) {
+      if connection.isVideoRotationAngleSupported(90) {
+        connection.videoRotationAngle = 90
+        return true
+      }
+    }
+    if connection.isVideoOrientationSupported {
+      connection.videoOrientation = .portrait
+      return true
+    }
+    return false
+  }
+
+  /// Vision's normalized box (origin BOTTOM-left) → the API contract: normalized
+  /// 0..1, origin TOP-left, in the upright frame. A y-flip is the whole transform
+  /// because the image handed to Vision is already upright (.up) — no rotation
+  /// here, by design (see ORIENTATION above). One helper for readText AND
+  /// detectObjects, so the two can never disagree about where a thing is.
+  private static func topLeftBox(_ bb: CGRect) -> [String: CGFloat] {
+    return ["x": bb.origin.x, "y": 1.0 - bb.origin.y - bb.height, "width": bb.width, "height": bb.height]
+  }
+
   func retentionMs() -> Int { return ringCap * intervalMs }
 
   func qualityById(_ id: String) -> [String: Any]? {
@@ -210,6 +251,8 @@ final class VisionSession: NSObject, AVCaptureVideoDataOutputSampleBufferDelegat
       self.generation += 1 // new session → old ids can no longer resolve
       self.session.beginConfiguration()
       self.session.sessionPreset = .medium
+      // Back camera only. Offering the front camera would also need the connection
+      // mirrored (isVideoMirrored) so boxes match the mirrored view the user sees.
       guard let device = AVCaptureDevice.default(.builtInWideAngleCamera, for: .video, position: .back),
             let input = try? AVCaptureDeviceInput(device: device), self.session.canAddInput(input) else {
         self.session.commitConfiguration()
@@ -225,6 +268,12 @@ final class VisionSession: NSObject, AVCaptureVideoDataOutputSampleBufferDelegat
         onReady(NSError(domain: "AdaVision", code: 5, userInfo: [NSLocalizedDescriptionKey: "Cannot attach video output"])); return
       }
       self.session.addOutput(out)
+      // addOutput just created this output's connection; stop() discards it and
+      // every start builds a fresh one, so rotating here covers every (re)creation.
+      let upright = out.connection(with: .video).map { VisionSession.orientUpright($0) } ?? false
+      if !upright {
+        NSLog("AdaVision: cannot rotate the camera data output to portrait — frames stay sensor-landscape, so box x/y will not match left/right")
+      }
       self.session.commitConfiguration()
       self.running = true
       self.session.startRunning()
@@ -293,13 +342,10 @@ final class VisionSession: NSObject, AVCaptureVideoDataOutputSampleBufferDelegat
         if let err = err { completion(nil, err); return }
         let out: [[String: Any]] = (req.results as? [VNRecognizedTextObservation])?.compactMap { obs in
           guard let top = obs.topCandidates(1).first else { return nil }
-          let bb = obs.boundingBox // normalized, origin BOTTOM-left
           return [
             "text": top.string,
             "confidence": Double(top.confidence),
-            // Normalize to TOP-left origin (the API contract). Full device-rotation
-            // transform is a later step; this is the y-flip.
-            "box": ["x": bb.origin.x, "y": 1.0 - bb.origin.y - bb.height, "width": bb.width, "height": bb.height],
+            "box": VisionSession.topLeftBox(obs.boundingBox),
           ]
         } ?? []
         completion(out, nil)
@@ -356,8 +402,9 @@ final class VisionSession: NSObject, AVCaptureVideoDataOutputSampleBufferDelegat
   }()
 
   // MARK: detectObjects — on-device object detection (bundled Core ML), by id.
-  // Same latest-wins discipline as readText/describe (serial `queue`). Boxes are
-  // normalised 0..1, flipped to TOP-left origin to match the readText contract.
+  // Same latest-wins discipline as readText/describe (serial `queue`). Boxes go
+  // through the same topLeftBox as readText: normalised 0..1, TOP-left origin, in
+  // the upright portrait frame.
   func detectObjects(_ id: String, maxItems: Int, minConfidence: Double, completion: @escaping ([[String: Any]]?, Error?) -> Void) {
     queue.async {
       guard let cg = self.ring.first(where: { $0.id == id })?.image else {
@@ -376,11 +423,10 @@ final class VisionSession: NSObject, AVCaptureVideoDataOutputSampleBufferDelegat
         let out: [[String: Any]] = objs.compactMap { obs -> (Double, [String: Any])? in
           // .labels is sorted by confidence; take the top class for this box.
           guard let top = obs.labels.first, Double(top.confidence) >= minConfidence else { return nil }
-          let bb = obs.boundingBox // normalized, origin BOTTOM-left
           return (Double(top.confidence), [
             "label": top.identifier,
             "confidence": Double(top.confidence),
-            "box": ["x": bb.origin.x, "y": 1.0 - bb.origin.y - bb.height, "width": bb.width, "height": bb.height],
+            "box": VisionSession.topLeftBox(obs.boundingBox),
           ])
         }
         .sorted { $0.0 > $1.0 }
@@ -388,7 +434,11 @@ final class VisionSession: NSObject, AVCaptureVideoDataOutputSampleBufferDelegat
         .map { $0.1 }
         completion(Array(out), nil)
       }
-      request.imageCropAndScaleOption = .scaleFill // match the model's 640² letterless input
+      // Vision stretches the whole (portrait, 3:4) frame onto the model's square
+      // 640² input and maps the boxes back itself. The stretch is per-axis, so a
+      // normalised box means the same thing in the frame as in the model input —
+      // no letterbox math here, whatever the frame's aspect.
+      request.imageCropAndScaleOption = .scaleFill
       do {
         try VNImageRequestHandler(cgImage: cg, options: [:]).perform([request])
       } catch {
@@ -403,6 +453,10 @@ final class VisionSession: NSObject, AVCaptureVideoDataOutputSampleBufferDelegat
 // A native view bound to the SAME AVCaptureSession the headless VisionSession
 // runs — so it shows exactly what the reader sees, WITHOUT opening a second
 // camera. The real Guide never mounts this; it exists only so a tester can aim.
+// The preview layer has its OWN connection (portrait by default); orientUpright
+// rotates only the data output's, so both show the same upright portrait. Note
+// resizeAspectFill crops the frame's sides on a tall screen, so a thing at the
+// frame's left/right edge can be detected yet sit just outside the preview.
 final class AdaVisionSessionHub {
   static let shared = AdaVisionSessionHub()
   private(set) weak var session: AVCaptureSession?

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ateam-ai-mobile/expo",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "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,9 +9,9 @@
     "build": "tsup"
   },
   "dependencies": {
-    "@ateam-ai-mobile/core": "0.1.7",
-    "@ateam-ai-mobile/plugin-runtime": "0.1.7",
-    "@ateam-ai-mobile/ui": "0.1.7"
+    "@ateam-ai-mobile/core": "0.1.8",
+    "@ateam-ai-mobile/plugin-runtime": "0.1.8",
+    "@ateam-ai-mobile/ui": "0.1.8"
   },
   "peerDependencies": {
     "@react-native-async-storage/async-storage": "*",
@@ -131,6 +131,12 @@
       "import": "./dist/vision/index.mjs",
       "require": "./dist/vision/index.js"
     },
+    "./maps": {
+      "react-native": "./src/maps/index.ts",
+      "types": "./dist/maps/index.d.ts",
+      "import": "./dist/maps/index.mjs",
+      "require": "./dist/maps/index.js"
+    },
     "./device": {
       "react-native": "./src/device/createDeviceProvider.ts",
       "types": "./dist/device/createDeviceProvider.d.ts",

package/src/args.ts

@@ -0,0 +1,56 @@
+// Argument checks for native verbs — one place, shared by every capability that
+// hands caller numbers to Swift.
+//
+// Why this exists: expo-modules-core converts a JS number to a Swift Int with
+// `Int(double.rounded())`, which TRAPS on NaN, ±Infinity or anything past
+// Int.max. A plugin (or a model driving a device tool) passing `limit: Infinity`
+// or `maxItems: NaN` would therefore kill the host app. Every count that crosses
+// the bridge is checked here first and refused BY NAME instead.
+//
+// No imports on purpose: it runs under plain `node --test`.
+
+/** A malformed call, refused before anything is sent. Retrying will not help;
+ *  fixing the call will. */
+export type ArgumentError = Error & { code: 'INVALID_ARGUMENT' };
+
+/** What the caller passed, short enough to quote back in a refusal. NaN and
+ *  Infinity are spelled out, unquoted (JSON would print them as null). */
+export const shown = (v: unknown): string => {
+  let s: string | undefined;
+  try {
+    s = JSON.stringify(v, (_k, x) => (typeof x === 'number' && !Number.isFinite(x) ? `\u0001${x}\u0001` : x))
+      ?.replace(/"\\u0001(NaN|-?Infinity)\\u0001"/g, '$1');
+  } catch { /* cyclic — fall back to String */ }
+  s = s ?? String(v);
+  return s.length > 80 ? `${s.slice(0, 77)}...` : s;
+};
+
+/** `<capability>.<verb>: <problem>; <what was not done>.` with code INVALID_ARGUMENT. */
+export function refuseArgument(capability: string, verb: string, problem: string, nothing: string): ArgumentError {
+  const e = new Error(`${capability}.${verb}: ${problem}; ${nothing}.`) as ArgumentError;
+  e.code = 'INVALID_ARGUMENT';
+  return e;
+}
+
+/** A count bound for a Swift Int: absent → `def`; otherwise a finite number ≥ 1,
+ *  floored and capped at `max`. Anything else refuses by name. */
+export function countArg(
+  capability: string, verb: string, name: string, value: unknown, def: number, max: number, nothing: string,
+): number {
+  const v = value ?? def;
+  if (typeof v !== 'number' || !Number.isFinite(v) || v < 1) {
+    throw refuseArgument(capability, verb, `${name} must be a number from 1 (at most ${max} are used), not ${shown(value)}`, nothing);
+  }
+  return Math.min(max, Math.floor(v));
+}
+
+/** A 0..1 fraction (a confidence): absent → `def`; NaN or out of range refuses. */
+export function fractionArg(
+  capability: string, verb: string, name: string, value: unknown, def: number, nothing: string,
+): number {
+  const v = value ?? def;
+  if (typeof v !== 'number' || !Number.isFinite(v) || v < 0 || v > 1) {
+    throw refuseArgument(capability, verb, `${name} must be a number from 0 to 1, not ${shown(value)}`, nothing);
+  }
+  return v;
+}

package/src/createBridge.ts

@@ -16,6 +16,8 @@ import * as ExpoSMS from 'expo-sms';
 import * as ExpoLinking from 'expo-linking';
 import { Platform } from 'react-native';
 import * as Device from 'expo-device';
+// The SDK's one reverse geocode — the same call native.maps.reverseGeocode makes.
+import { reverseGeocode } from './maps';
 
 import type { Bridge } from '@ateam-ai-mobile/plugin-runtime';
 
@@ -361,7 +363,7 @@ export function createBridge(connectorId: string, deviceId: string): Bridge {
             accuracy: ExpoLocation.Accuracy.Balanced,
           });
 
-          const [geo] = await ExpoLocation.reverseGeocodeAsync({
+          const geo = await reverseGeocode({
             latitude: location.coords.latitude,
             longitude: location.coords.longitude,
           });

package/src/device/createDeviceProvider.ts

@@ -26,6 +26,13 @@ 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,
@@ -67,6 +74,7 @@ import type {
   NfcAPI,
   BluetoothAPI,
   VisionAPI,
+  MapsAPI,
 } from '@ateam-ai-mobile/plugin-runtime';
 
 class CapabilityUnavailableError extends Error {
@@ -758,18 +766,28 @@ function createVisionAPI(): VisionAPI {
     // 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[] }) {
-      return adaVision.readText(frameId, opts?.languages);
+      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 }) {
-      return adaVision.describe(frameId, opts?.maxLabels ?? 5);
+      // 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 }) {
-      return adaVision.detectObjects(frameId, opts?.maxItems ?? 10, opts?.minConfidence ?? 0.25);
+      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
@@ -792,6 +810,72 @@ function createVisionAPI(): VisionAPI {
   };
 }
 
+// ── 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 {
@@ -828,5 +912,6 @@ export function createDeviceProvider(config?: DeviceProviderConfig): PluginNativ
     nfc: createNfcAPI(),
     bluetooth: createBluetoothAPI(),
     vision: createVisionAPI(),
+    maps: createMapsAPI(),
   };
 }

package/src/device-bridge/collectors/location.ts

@@ -4,11 +4,9 @@
  */
 
 import * as ExpoLocation from 'expo-location';
-// Type-only alias: the value namespace above cannot be used in type
-// position, so `ExpoLocation.Calendar`-style annotations need this.
-// Not re-exported from the package entry — derive from the API that
-// returns it, so the shape follows the installed expo-location.
-type LocationGeocodedAddress = Awaited<ReturnType<typeof ExpoLocation.reverseGeocodeAsync>>[number];
+import type { MapsAddress } from '@ateam-ai-mobile/plugin-runtime';
+// The SDK's one reverse geocode — the same call native.maps.reverseGeocode makes.
+import { reverseGeocode } from '../../maps';
 import type { LocationData } from '../types';
 
 /**
@@ -50,7 +48,7 @@ export async function collectCurrent(): Promise<LocationData> {
   let locationType = 'unknown';
 
   try {
-    const [geocoded] = await ExpoLocation.reverseGeocodeAsync({
+    const geocoded = await reverseGeocode({
       latitude: location.coords.latitude,
       longitude: location.coords.longitude,
     });
@@ -177,11 +175,25 @@ function nonNegative(v: unknown): number | undefined {
   return typeof v === 'number' && v >= 0 ? v : undefined;
 }
 
+const WATCH_TIER = {
+  navigation: ExpoLocation.Accuracy.BestForNavigation,
+  high: ExpoLocation.Accuracy.High,
+  balanced: ExpoLocation.Accuracy.Balanced,
+  low: ExpoLocation.Accuracy.Low,
+} as const;
+
 /**
  * Stream position updates. Returns an unsubscribe function — call it, or the
  * GPS keeps running and drains the battery.
+ *
+ * `accuracy` picks the GPS tier. The default stays Balanced (≈100 m on iOS),
+ * which is right for "which city block" and wrong for "turn at the next corner":
+ * a navigation session asks for BestForNavigation and pays the battery for it.
  */
-export function watchPosition(cb: (pos: Position) => void): () => void {
+export function watchPosition(
+  cb: (pos: Position) => void,
+  opts?: { accuracy?: keyof typeof WATCH_TIER },
+): () => void {
   let subscription: { remove(): void } | null = null;
   let cancelled = false;
 
@@ -190,7 +202,7 @@ export function watchPosition(cb: (pos: Position) => void): () => void {
       await ensurePermission();
       if (cancelled) return;
       subscription = await ExpoLocation.watchPositionAsync(
-        { accuracy: ExpoLocation.Accuracy.Balanced },
+        { accuracy: WATCH_TIER[opts?.accuracy ?? 'balanced'] },
         fix => cb(toPosition(fix)),
       );
       // Unsubscribed while we were still asking for permission.
@@ -209,7 +221,7 @@ export function watchPosition(cb: (pos: Position) => void): () => void {
 
 // ─── Helpers ───
 
-function classifyLocation(geocoded: LocationGeocodedAddress): string {
+function classifyLocation(geocoded: MapsAddress): string {
   // Simple heuristic — can be enhanced with user-labeled places from memory
   const name = (geocoded.name || '').toLowerCase();
   const street = (geocoded.street || '').toLowerCase();

package/src/device-state/collectors.ts

@@ -6,11 +6,15 @@
  * in one of them. Injection also matches how the rest of this SDK takes host
  * capabilities, and lets a test drive the engines without an Expo runtime.
  */
+/** GPS tier for a position stream: turn-by-turn, precise, city-block, coarse. */
+export type WatchAccuracy = 'navigation' | 'high' | 'balanced' | 'low';
+
 export interface DeviceStateCollectors {
   connectivity?: { collectConnectivity(): Promise<any> };
   location?: {
     getPosition(opts?: { accuracy?: 'low' | 'high' }): Promise<any>;
-    watchPosition(cb: (pos: any) => void): () => void;
+    /** `accuracy` is the GPS tier the stream runs at (battery vs precision). */
+    watchPosition(cb: (pos: any) => void, opts?: { accuracy?: WatchAccuracy }): () => void;
     hasPermission(): Promise<boolean>;
   };
 }

package/src/device-state/domains/deviceContext.ts

@@ -3,6 +3,7 @@
 import * as ExpoBattery from 'expo-battery';
 import type { DeviceState, DeviceContextSnapshot } from '@ateam-ai-mobile/plugin-runtime';
 import { qualityFrom, qualityUnknown } from '../quality';
+import { stateEvent } from '../events';
 
 export function createDeviceContextDomain(): DeviceState['deviceContext'] {
   return {
@@ -43,11 +44,12 @@ export function createDeviceContextDomain(): DeviceState['deviceContext'] {
 
     // Real events, not a placeholder: expo-battery exposes native listeners,
     // so a plugin that subscribes genuinely hears about a change rather than
-    // sitting on a subscription that can never fire.
+    // sitting on a subscription that can never fire. Nudges without a payload:
+    // no Device Context payload schema is decided, so the subscriber re-reads.
     subscribe(listener) {
       const subs = [
-        ExpoBattery.addBatteryLevelListener(() => listener({ type: 'batteryLevelChanged' } as any)),
-        ExpoBattery.addBatteryStateListener(() => listener({ type: 'chargingChanged' } as any)),
+        ExpoBattery.addBatteryLevelListener(() => listener(stateEvent('deviceContext', 'batteryLevelChanged'))),
+        ExpoBattery.addBatteryStateListener(() => listener(stateEvent('deviceContext', 'chargingChanged'))),
       ];
       return { unsubscribe: () => subs.forEach(x => x?.remove?.()) };
     },

package/src/device-state/domains/interaction.ts

@@ -3,6 +3,7 @@
 import { AppState } from 'react-native';
 import type { DeviceState, InteractionSnapshot } from '@ateam-ai-mobile/plugin-runtime';
 import { qualityFrom } from '../quality';
+import { stateEvent } from '../events';
 
 /**
  * Lifecycle only, and honest about the rest.
@@ -51,7 +52,7 @@ export function createInteractionDomain(): DeviceState['interaction'] {
     // which is the one part of this domain that works.
     subscribe(listener) {
       const sub = AppState.addEventListener('change', next => {
-        listener({ type: 'appStateChanged', appState: mapState(next as string) } as any);
+        listener(stateEvent('interaction', 'appStateChanged', { appState: mapState(next as string) }));
       });
       return { unsubscribe: () => sub.remove() };
     },