@ateam-ai-mobile/expo 0.1.7 → 0.1.8

package/src/device-state/replay.ts

@@ -26,8 +26,20 @@
  * are replayed exactly as recorded. They are the most valuable records in the
  * file — they are what a guide must handle correctly, and precisely what a
  * hand-written fixture would never contain.
+ *
+ * SPATIAL EVENTS REPLAY; THE OTHERS REFUSE. Spatial events are derived from
+ * snapshots by the same detector the live engine runs, so feeding it the
+ * recorded snapshots in time order gives the events the walk produced — at the
+ * virtual time of the sample that completed each one. While a listener runs,
+ * the clock stands AT that sample, so a listener that re-reads gets the
+ * snapshot its event came from, as it would live. Two limits, inherited from
+ * recording snapshots: two turns inside one recorded tick collapse to the later
+ * one, because a snapshot carries only the last turn; and a hold completes at
+ * the recording's tick rather than the live engine's one-second one.
  */
-import type { DeviceState } from '@ateam-ai-mobile/plugin-runtime';
+import type { DeviceState, SpatialStateEvent } from '@ateam-ai-mobile/plugin-runtime';
+import { SpatialEventDetector, spatialEventProfile } from './spatialEvents';
+import { listenerSet } from './events';
 
 /** One tick of a recorded walk. Domains are stored verbatim, never normalised. */
 export interface WalkSample {
@@ -138,11 +150,46 @@ export function createReplayDeviceState(fixture: WalkFixture): ReplaySession {
 
   let cursor = 0;
 
+  // Spatial events: the live engine's detector, fed recorded snapshots.
+  const spatialDetector = new SpatialEventDetector();
+  const spatialListeners = listenerSet<SpatialStateEvent>();
+
+  /**
+   * Move the cursor, feeding every spatial sample crossed on the way to the
+   * detector, oldest first, with the sample's own `t` as "now". Only while a
+   * spatial session is open — the live engine has no event feed without one.
+   *
+   * The cursor steps THROUGH each fed sample rather than jumping to the target
+   * first: an event and a read taken inside its listener must describe the same
+   * instant, or the event says "you turned" while the read still shows the
+   * sample before the corner.
+   *
+   * Backwards is not a walk: the detector forgets and says nothing, and the
+   * next step forward starts from the new position as a fresh session would.
+   */
+  const moveTo = (target: number): number => {
+    const next = Math.min(duration, Math.max(0, target));
+    if (!openSessions.has('spatial')) return (cursor = next);
+    if (next < cursor) {
+      cursor = next;
+      spatialDetector.reset(undefined, turnOnRecordAt());
+      return cursor;
+    }
+    const from = cursor;
+    for (const s of samples) {
+      if (s.t <= from || !s.spatial) continue;
+      if (s.t > next) break;
+      cursor = s.t;
+      for (const event of spatialDetector.push(s.spatial, s.t)) spatialListeners.emit(event);
+    }
+    return (cursor = next);
+  };
+
   const clock: ReplayClock = {
     now: () => cursor,
-    advance: ms => (cursor = Math.min(duration, Math.max(0, cursor + ms))),
-    seek: ms => (cursor = Math.min(duration, Math.max(0, ms))),
-    end: () => (cursor = duration),
+    advance: ms => moveTo(cursor + ms),
+    seek: ms => moveTo(ms),
+    end: () => moveTo(duration),
     durationMs: () => duration,
   };
 
@@ -163,6 +210,13 @@ export function createReplayDeviceState(fixture: WalkFixture): ReplaySession {
     return found;
   };
 
+  /**
+   * The turn the recording already holds at the cursor. Taken from the sample,
+   * never compared with the cursor: a recording stamps turns in the phone's
+   * epoch ms, while `t` is ms since the recording started.
+   */
+  const turnOnRecordAt = (): number | null => sampleAt()?.spatial?.changes?.timestamp ?? null;
+
   const domainFor = (name: string): any => ({
     async getSnapshot() {
       const s = sampleAt();
@@ -171,21 +225,32 @@ export function createReplayDeviceState(fixture: WalkFixture): ReplaySession {
       // answer the real gate gives for a domain it cannot serve.
       return recorded ?? unknownSnapshot(name);
     },
-    async start() {
+    async start(options?: { intent?: string }) {
       const r = refusals.get(name);
       // Replay the refusal the real walk hit. A fixture recorded with the
       // pedometer denied must fail here, or a test proves the guide works in
       // conditions the user never had.
       if (r) throw refusal(name, r.code, r.message);
+      // A session opened at `t` hears samples recorded AFTER `t`: the reading
+      // at `t` already existed before it asked, as a live fix would have.
+      if (name === 'spatial' && !openSessions.has(name)) {
+        spatialDetector.reset(spatialEventProfile(options?.intent), turnOnRecordAt());
+      }
       openSessions.add(name);
       return { id: `replay_${name}`, intent: 'replay', startedAt: 0 } as any;
     },
-    async stop() { openSessions.delete(name); },
-    subscribe() {
-      // Deliberately unsupported: a fixture is a timeline a test steps through,
-      // so events would have to fire on `advance()`, and a subscription that
-      // silently never fires reads as "nothing has changed" — the failure this
-      // whole layer exists to prevent. Step the clock and read instead.
+    async stop() {
+      openSessions.delete(name);
+      if (name === 'spatial') spatialDetector.reset();
+    },
+    subscribe(listener: (event: SpatialStateEvent) => void) {
+      // Spatial events are derived from snapshots, and the snapshots are what
+      // this file replays — so they fire as the clock crosses each sample.
+      if (name === 'spatial') return spatialListeners.add(listener);
+      // The rest are deliberately unsupported: their events come from engine
+      // callbacks a fixture does not record, and a subscription that silently
+      // never fires reads as "nothing has changed" — the failure this whole
+      // layer exists to prevent. Step the clock and read instead.
       throw refusal(name, 'UNSUPPORTED', `deviceState.${name}.subscribe is not replayable — advance the clock and read.`);
     },
   });

package/src/device-state/spatialEvents.ts

@@ -0,0 +1,300 @@
+/**
+ * Spatial events, derived from spatial snapshots.
+ *
+ * ONE MODEL, NOT TWO. An event is what changed between two snapshots — the
+ * same snapshots `getSnapshot()` returns — so an event can never say "moving"
+ * while a read says "stationary", and no threshold here has a second copy
+ * somewhere else. The thresholds a read uses (the stationary speed, the GPS
+ * confidence bands, distance along a path) live in this file and the domain
+ * imports them, rather than the other way round, so the detector can be tested
+ * without an Expo import: the live engine feeds it on every fix, every turn and
+ * a one-second tick; replay feeds it recorded samples on a virtual clock.
+ *
+ * THE HARD PART IS NOT DETECTING CHANGES, IT IS NOT INVENTING THEM (the turn
+ * detector's lesson, again). GPS speed wobbles around any threshold, and a fix
+ * band flickers when accuracy sits near a boundary. So every state change must
+ * HOLD before it is reported, and position changes must beat the fix's own
+ * error bar. Holds delay an event on purpose; `since` in the payload carries
+ * the real onset.
+ *
+ * A HOLD IS HELD BY FIXES, NOT BY THE CLOCK ALONE. The one-second tick re-reads
+ * the SAME fix, so a hold measured only in time would let one outlier fix
+ * followed by a gap — sparse fixes at Balanced accuracy, a wifi jump read as
+ * speed — become "you started moving". A state settles only once two distinct
+ * fixes have shown it; after that the tick may complete the hold, which is what
+ * it is for ("stationary for five seconds" completes while nothing arrives).
+ *
+ * Type-only imports from plugin-runtime, so `node --test` can load this file.
+ */
+import type {
+  Confidence,
+  SpatialEvent,
+  SpatialIntent,
+  SpatialPoint,
+  SpatialSnapshot,
+  SpatialStateEvent,
+} from '@ateam-ai-mobile/plugin-runtime';
+import { stateEvent } from './events';
+import { distanceOf } from '../geo';
+
+/**
+ * Below this the user is standing still.
+ *
+ * 0.4 m/s is well under a slow walk (~1.2 m/s) and above the jitter a
+ * stationary phone's GPS produces. The point of the band is that a guide
+ * must not say "keep going straight" to someone who has stopped.
+ */
+export const STATIONARY_MPS = 0.4;
+
+/**
+ * Only claim stationary/moving when a speed was actually obtained. With no
+ * speed the truthful answer is `unknown`, not `stationary` — "you have
+ * stopped" is a false statement, not a neutral default.
+ */
+export function movementStateOf(speedMps: number | null): 'stationary' | 'moving' | 'unknown' {
+  return speedMps === null ? 'unknown' : speedMps < STATIONARY_MPS ? 'stationary' : 'moving';
+}
+
+/**
+ * The GPS fix's confidence band, from metres of horizontal error. ~10m is a
+ * good open-sky fix; beyond ~50m the position is street-level at best and
+ * useless for "turn at the next corner".
+ */
+export function fixConfidence(accuracyM: number | null): Confidence['level'] {
+  return accuracyM === null ? 'unknown' : accuracyM <= 10 ? 'high' : accuracyM <= 50 ? 'medium' : 'low';
+}
+
+
+export interface SpatialEventProfile {
+  /** How long `moving` must hold before `movementStarted`. */
+  movingHoldMs: number;
+  /** How long `stationary` must hold, after moving, before `movementStopped`. */
+  stoppedHoldMs: number;
+  /** How long a new GPS confidence band must hold before it is reported. */
+  confidenceHoldMs: number;
+  /** Floor for `positionChanged`, metres. The real threshold is
+   *  max(this, moveThresholdM(anchor, fix)) — both fixes' uncertainty — so a
+   *  loose fix on EITHER end needs a bigger move. */
+  minMoveM: number;
+}
+
+/**
+ * Intent → how eager the events are.
+ *
+ * These are the engine's judgement, not the freeze's — the architecture doc
+ * says only "thresholds are profile-dependent". Recorded here so the reasoning
+ * is visible and arguable rather than buried. The intent changes ONLY these
+ * holds, not sampling: there is no native strategy layer for it to reach.
+ *
+ * - `navigation`: a guide needs "you've stopped" soon enough to act on, but a
+ *   pause at a crossing is not a stop worth announcing — 3 s to start, 5 s to
+ *   stop. 10 m is about one building frontage.
+ * - `fitness`: same movement holds; a slower confidence hold, because a runner
+ *   under trees dips in and out of a band constantly and nobody needs to hear it.
+ * - `preciseLocate`: the caller is deliberately pinning a position, so the
+ *   holds are shortest and a few metres counts.
+ * - `geofence` / `lowPowerTracking`: coarse by nature — tens of metres, and a
+ *   state must hold for a while before it is worth waking anyone for.
+ */
+export const SPATIAL_EVENT_PROFILES: Record<SpatialIntent, SpatialEventProfile> = {
+  navigation:       { movingHoldMs: 3000,  stoppedHoldMs: 5000,  confidenceHoldMs: 3000,  minMoveM: 10 },
+  fitness:          { movingHoldMs: 3000,  stoppedHoldMs: 5000,  confidenceHoldMs: 5000,  minMoveM: 10 },
+  preciseLocate:    { movingHoldMs: 2000,  stoppedHoldMs: 3000,  confidenceHoldMs: 2000,  minMoveM: 3 },
+  geofence:         { movingHoldMs: 10000, stoppedHoldMs: 30000, confidenceHoldMs: 10000, minMoveM: 25 },
+  lowPowerTracking: { movingHoldMs: 10000, stoppedHoldMs: 30000, confidenceHoldMs: 10000, minMoveM: 50 },
+};
+
+/** The profile for an intent; an unrecognised one gets `navigation`'s. */
+/**
+ * The move two fixes can vouch for. A fix is a circle, not a point, and so is
+ * the anchor it is compared with: two fixes of a phone lying still differ by up
+ * to BOTH their errors. Combined (root-sum-square, each accuracyM ~ one radius)
+ * and doubled, like a single fix's 2× before. No estimate = 0 (the floor rules).
+ * Anchor ±100 m → fix ±5 m: a 20 m difference is noise, not a walk.
+ */
+export function moveThresholdM(anchor: { accuracyM?: number | null }, fix: { accuracyM?: number | null }): number {
+  const a = anchor.accuracyM ?? 0, b = fix.accuracyM ?? 0;
+  return 2 * Math.sqrt(a * a + b * b);
+}
+
+export function spatialEventProfile(intent: string | null | undefined): SpatialEventProfile {
+  return SPATIAL_EVENT_PROFILES[intent as SpatialIntent] ?? SPATIAL_EVENT_PROFILES.navigation;
+}
+
+type Band = 'high' | 'medium' | 'low';
+const RANK: Record<Band, number> = { high: 3, medium: 2, low: 1 };
+type PayloadOf<N extends SpatialEvent> = Extract<SpatialStateEvent, { name: N }>['payload'];
+
+/** Distinct fixes a state must be seen on before its hold can complete. */
+const MIN_FIXES = 2;
+
+/**
+ * An unbroken run of one raw state: when it began, and how many distinct fixes
+ * (by `position.timestamp`) have shown it. A re-read of the same fix extends
+ * the run's time, never its evidence.
+ */
+interface Run<S> { state: S; since: number; fixAt: number | null; fixes: number }
+
+function extend<S>(run: Run<S> | null, state: S, fixAt: number | null, now: number): Run<S> {
+  if (!run || run.state !== state) return { state, since: now, fixAt, fixes: fixAt === null ? 0 : 1 };
+  if (fixAt !== null && fixAt !== run.fixAt) { run.fixAt = fixAt; run.fixes++; }
+  return run;
+}
+
+const settled = (run: Run<unknown>, now: number, holdMs: number): boolean =>
+  run.fixes >= MIN_FIXES && now - run.since >= holdMs;
+
+/** Which fix a snapshot was built from — its identity when counting evidence. */
+const fixAt = (s: SpatialSnapshot): number | null => s.position?.timestamp ?? null;
+
+export class SpatialEventDetector {
+  private profile: SpatialEventProfile;
+
+  /** The movement state last settled on. Only MEASURED states settle. */
+  private movement: 'stationary' | 'moving' | 'unknown' = 'unknown';
+  private run: Run<'stationary' | 'moving' | 'unknown'> | null = null;
+
+  /** The completed turn already on record — reported turns, and the one the
+   *  session opened onto. Only a turn with a new timestamp is news. */
+  private lastTurnAt: number | null = null;
+
+  /** The GPS band last settled on; null until the session's first band. */
+  private band: Band | null = null;
+  private bandRun: Run<Band> | null = null;
+
+  /** The last position REPORTED — distance is measured from here, not from
+   *  the previous fix, so a slow walk still adds up to a change. */
+  private anchor: SpatialPoint | null = null;
+
+  private staleArmed = true;
+
+  constructor(profile: SpatialEventProfile = SPATIAL_EVENT_PROFILES.navigation) {
+    this.profile = profile;
+  }
+
+  /**
+   * Forget everything — a new session, or replay seeking backwards. Emits
+   * nothing. `turnOnRecordAt` is the timestamp of the turn already completed
+   * when the session opens (a visual session shares the compass): history, not
+   * news. Seeded from the turn itself rather than compared against a clock, so
+   * it holds whichever clock the turn was stamped with — epoch live, the
+   * recording's epoch in replay, where `now` is virtual.
+   */
+  reset(profile?: SpatialEventProfile, turnOnRecordAt: number | null = null): void {
+    if (profile) this.profile = profile;
+    this.movement = 'unknown';
+    this.run = null;
+    this.lastTurnAt = turnOnRecordAt;
+    this.band = null;
+    this.bandRun = null;
+    this.anchor = null;
+    this.staleArmed = true;
+  }
+
+  /**
+   * Feed the newest snapshot. Returns what changed since the last one, in this
+   * order: movement, turn, position, confidence, staleness. Fields are read
+   * defensively — replay hands over recorded snapshots verbatim, and a recording
+   * may lack a block the live engine always fills.
+   */
+  push(snapshot: SpatialSnapshot, now: number): SpatialStateEvent[] {
+    const out: SpatialStateEvent[] = [];
+    const emit: Emit = (name, payload) => {
+      // The payload is checked against its name by `Emit`; the union cannot
+      // follow a generic name through stateEvent's return, hence the assertion.
+      out.push(stateEvent('spatial', name, payload as unknown, now) as SpatialStateEvent);
+    };
+    this.movementFrom(snapshot, now, emit);
+    this.turnFrom(snapshot, emit);
+    this.positionFrom(snapshot, emit);
+    this.confidenceFrom(snapshot, now, emit);
+    this.staleFrom(snapshot, emit);
+    return out;
+  }
+
+  private movementFrom(s: SpatialSnapshot, now: number, emit: Emit): void {
+    const state = s.movement?.state ?? 'unknown';
+    this.run = extend(this.run, state, fixAt(s), now);
+    if (state === this.movement) return;
+
+    if (state === 'moving' && settled(this.run, now, this.profile.movingHoldMs)) {
+      emit('movementStarted', {
+        previous: this.movement === 'stationary' ? 'stationary' : 'unknown',
+        speedMps: s.movement?.speedMps ?? null,
+        bearingDeg: s.movement?.bearingDeg ?? null,
+        since: this.run.since,
+      });
+      this.movement = 'moving';
+    } else if (state === 'stationary' && settled(this.run, now, this.profile.stoppedHoldMs)) {
+      if (this.movement === 'moving') emit('movementStopped', { previous: 'moving', since: this.run.since });
+      this.movement = 'stationary';
+    }
+    // `unknown` never settles. Losing the speed is not evidence of stopping, so
+    // moving → unknown says nothing, and a later measured `stationary` is still
+    // reported as the stop it is.
+  }
+
+  private turnFrom(s: SpatialSnapshot, emit: Emit): void {
+    const at = s.changes?.timestamp ?? null;
+    const deg = s.changes?.lastMeaningfulTurnDeg ?? null;
+    // A compass reset clears the turn to null. That is not a new turn.
+    if (at === null || deg === null || at === this.lastTurnAt) return;
+    this.lastTurnAt = at;
+    emit('lastMeaningfulTurnChanged', { lastMeaningfulTurnDeg: deg, timestamp: at });
+  }
+
+  private positionFrom(s: SpatialSnapshot, emit: Emit): void {
+    const p = s.position ?? null;
+    if (!p) return;
+    if (!this.anchor) {
+      emit('positionChanged', { position: { ...p }, previous: null, distanceM: null });
+      this.anchor = p;
+      return;
+    }
+    const d = distanceOf([this.anchor, p]);
+    if (d < Math.max(this.profile.minMoveM, moveThresholdM(this.anchor, p))) {
+      // Not a move — but if this fix is far more precise than the anchor, keep
+      // IT as the reference (silently): measuring later moves from a ±100 m
+      // anchor would hide real ones behind the old fix's error.
+      const aNew = p.accuracyM ?? null, aOld = this.anchor.accuracyM ?? null;
+      if (aNew != null && aOld != null && aNew * 2 < aOld) this.anchor = p;
+      return;
+    }
+    emit('positionChanged', { position: { ...p }, previous: { ...this.anchor }, distanceM: d });
+    this.anchor = p;
+  }
+
+  private confidenceFrom(s: SpatialSnapshot, now: number, emit: Emit): void {
+    const p = s.position ?? null;
+    if (!p) return;
+    const level = fixConfidence(p.accuracyM ?? null);
+    // A fix with no accuracy estimate says nothing about the band — the same
+    // way the snapshot's confidence ignores an `unknown` part.
+    if (level === 'unknown') return;
+    // The first band is where the session starts, not a change.
+    if (this.band === null) { this.band = level; return; }
+    if (level === this.band) { this.bandRun = null; return; }
+    this.bandRun = extend(this.bandRun, level, fixAt(s), now);
+    if (!settled(this.bandRun, now, this.profile.confidenceHoldMs)) return;
+    emit('positionConfidenceChanged', {
+      level,
+      previous: this.band,
+      accuracyM: p.accuracyM ?? null,
+      direction: RANK[level] < RANK[this.band] ? 'dropped' : 'recovered',
+    });
+    this.band = level;
+    this.bandRun = null;
+  }
+
+  private staleFrom(s: SpatialSnapshot, emit: Emit): void {
+    const f = s.quality?.freshness;
+    if (!f) return;
+    // Re-armed only by a FRESH read: `aging` on the way back is not recovery.
+    if (f.state === 'fresh') { this.staleArmed = true; return; }
+    if (f.state !== 'stale' || !this.staleArmed) return;
+    emit('spatialStateStale', { observedAt: f.observedAt, ageMs: f.ageMs });
+    this.staleArmed = false;
+  }
+}
+
+type Emit = <N extends SpatialEvent>(name: N, payload: PayloadOf<N>) => void;

package/src/geo.ts

@@ -0,0 +1,23 @@
+// Great-circle distance — the SDK's one answer to "how far apart are these".
+//
+// Moved out of device-state/domains/spatial.ts when native.maps needed the same
+// question answered (a search result's distance from `near`). Two haversines
+// would be two answers that could drift; both callers import this one.
+//
+// No imports on purpose: it runs under plain `node --test` with the maps
+// normaliser that uses it.
+
+/** Metres along a path, great-circle per leg, rounded to the metre. */
+export function distanceOf(path: ReadonlyArray<{ latitude: number; longitude: number }>): number {
+  const R = 6_371_000;
+  let total = 0;
+  for (let i = 1; i < path.length; i++) {
+    const a = path[i - 1], b = path[i];
+    const dLat = ((b.latitude - a.latitude) * Math.PI) / 180;
+    const dLon = ((b.longitude - a.longitude) * Math.PI) / 180;
+    const la1 = (a.latitude * Math.PI) / 180, la2 = (b.latitude * Math.PI) / 180;
+    const h = Math.sin(dLat / 2) ** 2 + Math.cos(la1) * Math.cos(la2) * Math.sin(dLon / 2) ** 2;
+    total += 2 * R * Math.asin(Math.sqrt(h));
+  }
+  return Math.round(total);
+}

package/src/maps/index.ts

@@ -0,0 +1,81 @@
+// ada-maps — place search + walking directions (Apple MapKit), our own native
+// code, plus the SDK's one reverse geocode.
+//
+// NOT on-device — the opposite of ada-vision. Every call sends the query and the
+// coordinates it is given to a map service over the network. None of it reads
+// the device's location: the caller supplies every coordinate.
+//
+//   search(...)        — MKLocalSearch   (AdaMaps module, iOS only)
+//   route(...)         — MKDirections    (AdaMaps module, iOS only)
+//   reverseGeocode(at) — expo-location's reverseGeocodeAsync, which IS CLGeocoder
+//                        on iOS and the platform Geocoder on Android. No Swift for
+//                        it, and the ONLY reverse geocode in the SDK: the location
+//                        collector and the connector bridge call this too.
+//
+// requireOptionalNativeModule: on a binary WITHOUT the module the import is null,
+// isSupported() is false, and search/route refuse cleanly (no crash). Android has
+// no AdaMaps at all, so it refuses by name the same way.
+
+import { Platform } from 'react-native';
+import { requireOptionalNativeModule } from 'expo-modules-core';
+import * as ExpoLocation from 'expo-location';
+import type { MapsAddress, MapsCoordinate } from '@ateam-ai-mobile/plugin-runtime';
+import { toMapsAddress } from './normalize';
+import type { RawMapsPlace, RawMapsRoute } from './normalize';
+
+interface AdaMapsNative {
+  isSupported(): boolean;
+  search(query: string, lat: number, lng: number, hasNear: boolean, radiusM: number, limit: number): Promise<RawMapsPlace[]>;
+  route(fromLat: number, fromLng: number, toLat: number, toLng: number): Promise<RawMapsRoute | null>;
+}
+
+const native = requireOptionalNativeModule<AdaMapsNative>('AdaMaps');
+
+/** What search/route are missing in THIS build, as the clause after "needs" —
+ *  or null when they can run. A voice assistant reads it out, so it names the
+ *  missing thing rather than giving a code. */
+export function missingReason(): string | null {
+  if (Platform.OS !== 'ios') return `iOS (Apple MapKit) — ${Platform.OS} has no implementation yet`;
+  if (!native) return 'the app build with the AdaMaps module (this build predates it — a native rebuild is needed)';
+  return null;
+}
+
+/** Is the native maps module present in this binary (and on a platform it runs on)? */
+export function isSupported(): boolean {
+  try { return missingReason() === null && (native?.isSupported() ?? false); } catch { return false; }
+}
+
+// search/route hand their arguments to native AS GIVEN: a NaN or Infinity
+// `limit` traps Swift's Int conversion and kills the app. createMapsAPI checks
+// every argument first (searchArgs / coordinateArg in ./normalize); a host
+// calling these directly must pass what those checks would accept.
+
+/** MKLocalSearch around `near` (when given). [] = looked, found nothing; throws =
+ *  couldn't look, with a string code OFFLINE / THROTTLED / UNAVAILABLE. */
+export async function search(
+  query: string,
+  near: MapsCoordinate | null,
+  radiusM: number,
+  limit: number,
+): Promise<RawMapsPlace[]> {
+  if (!native) throw new Error('ada-maps native module not present in this build');
+  // Without `near`, hasNear is false and Swift never reads lat/lng — the zeros
+  // are placeholders for a primitive argument, not a place.
+  return near
+    ? native.search(query, near.latitude, near.longitude, true, radiusM, limit)
+    : native.search(query, 0, 0, false, radiusM, limit);
+}
+
+/** MKDirections, walking, between two caller-supplied points. null = no route. */
+export async function route(from: MapsCoordinate, to: MapsCoordinate): Promise<RawMapsRoute | null> {
+  if (!native) throw new Error('ada-maps native module not present in this build');
+  return native.route(from.latitude, from.longitude, to.latitude, to.longitude);
+}
+
+/** The address at a coordinate, or null when the geocoder has nothing there.
+ *  Throws when it could not look (network, rate limit, Android without location
+ *  permission) — callers decide whether that is fatal. */
+export async function reverseGeocode(at: MapsCoordinate): Promise<MapsAddress | null> {
+  const [first] = await ExpoLocation.reverseGeocodeAsync({ latitude: at.latitude, longitude: at.longitude });
+  return first ? toMapsAddress(first) : null;
+}