@ateam-ai-mobile/expo 0.1.7 → 0.1.8

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

@@ -1,10 +1,25 @@
 // ── spatial ──────────────────────────────────────────────────────────────
-//   position ✓  path ✓ (while a session is open)  heading ✓  speed ~derived
-import type { DeviceState, SpatialSnapshot, SpatialPoint, StateQuality } from '@ateam-ai-mobile/plugin-runtime';
-import { visualEngine } from '../visualEngine';
-import { startHeading, stopHeading, currentHeadingDetail, lastMeaningfulTurn } from '../headingSource';
-import type { DeviceStateCollectors, SpeedRef } from '../collectors';
+//   position ✓  path ✓ heading ✓ turns ✓ events ✓ (while a session is open)  speed ~derived
+import type {
+  DeviceState,
+  SpatialIntent,
+  SpatialSnapshot,
+  SpatialStateEvent,
+  SpatialPoint,
+  StateQuality,
+  Subscription,
+} from '@ateam-ai-mobile/plugin-runtime';
+import { startHeading, stopHeading, currentHeadingDetail, lastMeaningfulTurn, onTurn } from '../headingSource';
+import type { DeviceStateCollectors, SpeedRef, WatchAccuracy } from '../collectors';
 import { qualityFrom, qualityUnknown, unsupported } from '../quality';
+import { distanceOf } from '../../geo';
+import { listenerSet } from '../events';
+import {
+  SpatialEventDetector,
+  fixConfidence,
+  movementStateOf,
+  spatialEventProfile,
+} from '../spatialEvents';
 
 /**
  * Position, movement, facing and a short recent path.
@@ -31,7 +46,23 @@ import { qualityFrom, qualityUnknown, unsupported } from '../quality';
  * (right) and negative for anticlockwise (left), so a guide can say which way
  * the user just went without a second field to consult. The freeze names the
  * field but states no convention; this is a decision, recorded here.
+ *
+ * EVENTS ARE THE SNAPSHOT, DIFFED. `subscribe` publishes what changed between
+ * successive warm snapshots — the same ones `getSnapshot` returns — via the
+ * pure detector in spatialEvents.ts. It is fed on every fix, the moment a turn
+ * completes, and once a second, so a transition that happens between fixes
+ * (fixes stopping is itself one: the state goes stale) is still noticed.
  */
+/** The GPS tier each intent's stream runs at. Navigation is the one that needs
+ *  "which side of the street"; everything else trades precision for battery. */
+const WATCH_ACCURACY: Record<SpatialIntent, WatchAccuracy> = {
+  navigation: 'navigation',
+  preciseLocate: 'high',
+  fitness: 'high',
+  geofence: 'balanced',
+  lowPowerTracking: 'low',
+};
+
 export function createSpatialDomain(
   collectors: DeviceStateCollectors,
   speedRef: SpeedRef,
@@ -39,14 +70,6 @@ export function createSpatialDomain(
   // The warm cache, when a session is open. Newest last, bounded — an unbounded
   // path on a walking user grows without limit.
   const RECENT_PATH_MAX = 60;
-  /**
-   * 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.
-   */
-  const STATIONARY_MPS = 0.4;
 
   let recentPath: SpatialPoint[] = [];
   let latest: SpatialPoint | null = null;
@@ -54,7 +77,13 @@ export function createSpatialDomain(
   let latestSpeed: number | null = null;
   let latestCourse: number | null = null;
   let stopWatch: (() => void) | null = null;
-  let sessionId: string | null = null;
+  /** The running session. A second `start()` joins it, and is told so. */
+  let session: { id: string; intent: SpatialIntent; startedAt: number } | null = null;
+
+  const detector = new SpatialEventDetector();
+  const listeners = listenerSet<SpatialStateEvent>();
+  let ticker: ReturnType<typeof setInterval> | null = null;
+  let turnSub: Subscription | null = null;
 
   const nonNegative = (v: unknown): number | null =>
     typeof v === 'number' && v >= 0 ? v : null;
@@ -87,95 +116,155 @@ export function createSpatialDomain(
     return bearingBetween(a, b);
   };
 
+  /**
+   * The snapshot for a fix — the ONE builder, used by the read and by the
+   * event detector alike. Synchronous: everything it needs is already in hand.
+   */
+  const snapshotFrom = (
+    point: SpatialPoint,
+    measuredSpeed: number | null,
+    measuredCourse: number | null,
+  ): SpatialSnapshot => {
+    // Fall back to the path only where the OS said nothing.
+    let speedMps = measuredSpeed;
+    let courseDeg = measuredCourse;
+    let derived = false;
+    if (speedMps === null) { const d = derivedSpeed(); if (d !== null) { speedMps = d; derived = true; } }
+    if (courseDeg === null) { const d = derivedCourse(); if (d !== null) { courseDeg = d; derived = true; } }
+
+    const heading = currentHeadingDetail();
+    const turn = lastMeaningfulTurn();
+
+    return {
+      position: point,
+      movement: {
+        speedMps,
+        bearingDeg: courseDeg,
+        // Needs two points from the SAME session; without a stream there is
+        // nothing to measure against, and a distance of 0 would read as
+        // "the user has not moved".
+        distanceRecentM: recentPath.length >= 2 ? distanceOf(recentPath) : null,
+        state: movementStateOf(speedMps),
+      },
+      orientation: {
+        headingDeg: heading?.headingDeg ?? null,
+        // NOT the calibration rank. iOS reports 0–3 (none…high), which is not
+        // a number of degrees, and converting one to the other would be an
+        // invented error bar. The rank drives `confidence` below instead.
+        headingAccuracyDeg: null,
+      },
+      changes: {
+        lastMeaningfulTurnDeg: turn ? turn.deg : null,
+        timestamp: turn ? turn.timestamp : null,
+      },
+      recentPath: [...recentPath],
+      quality: qualityFrom(
+        point.timestamp,
+        spatialConfidence(point.accuracyM ?? null, heading?.calibration ?? null, derived),
+      ),
+    };
+  };
+
+  /** "No position" — honest nulls, never a (0,0). The compass may still know
+   *  which way the phone points, so heading is kept when it has one. */
+  const noFix = (): SpatialSnapshot => ({
+    position: null,
+    movement: { speedMps: null, bearingDeg: null, distanceRecentM: null, state: 'unknown' },
+    orientation: { headingDeg: currentHeadingDetail()?.headingDeg ?? null },
+    recentPath: [],
+    quality: qualityUnknown(),
+  });
+
+  /** The warm snapshot, or null before the session's first streamed fix. */
+  const warmSnapshot = (): SpatialSnapshot | null =>
+    latest ? snapshotFrom(latest, latestSpeed, latestCourse) : null;
+
+  /**
+   * Diff the snapshot a read would get RIGHT NOW against the last one, and
+   * publish what changed. Before the first fix there is nothing to diff; a
+   * turn completed meanwhile is not lost, it is reported with the first fix.
+   */
+  const observe = () => {
+    const snapshot = warmSnapshot();
+    if (!snapshot) return;
+    for (const event of detector.push(snapshot, Date.now())) listeners.emit(event);
+  };
+
+  /**
+   * Re-diff once a second while a session is open. Fixes alone are not enough:
+   * the OS may pause them while the phone is still, and "the state has gone
+   * stale" or "you have been stationary for five seconds" are exactly the
+   * transitions that complete while nothing arrives. A tick re-reads the same
+   * fix, so it only completes a state the fixes already showed — it never
+   * turns one outlier fix into an event (spatialEvents.ts, MIN_FIXES).
+   */
+  const startTicking = () => {
+    ticker = setInterval(observe, 1000);
+  };
+
+  const stopTicking = () => {
+    if (ticker) clearInterval(ticker);
+    ticker = null;
+  };
+
   return {
     async getSnapshot(): Promise<SpatialSnapshot> {
       // Serve the warm fix when a session is streaming; otherwise take one.
-      let point = latest;
-      let speedMps = latestSpeed;
-      let courseDeg = latestCourse;
-      let derived = false;
+      const warm = warmSnapshot();
+      if (warm) return warm;
+      // A session is open but its stream has not delivered yet: say so NOW.
+      // A one-shot fix here would make every read wait on a cold GPS (seconds),
+      // stalling whatever loop reads us — and the stream answers soon anyway.
+      if (session) return noFix();
 
-      if (!point) {
-        try {
-          if (!collectors.location) throw unsupported('location collector');
-          const fix: any = await collectors.location.getPosition({ accuracy: 'low' });
-          point = {
-            latitude: fix.latitude,
-            longitude: fix.longitude,
-            altitude: fix.altitude ?? null,
-            accuracyM: nonNegative(fix.accuracy),
-            timestamp: fix.timestamp ?? Date.now(),
-          };
-          speedMps = nonNegative(fix.speed);
-          courseDeg = nonNegative(fix.course);
-        } catch {
-          // Permission refused, or no fix. Not a position at (0,0).
-          return {
-            position: null,
-            movement: { speedMps: null, bearingDeg: null, distanceRecentM: null, state: 'unknown' },
-            orientation: { headingDeg: null },
-            recentPath: [],
-            quality: qualityUnknown(),
-          };
-        }
+      let point: SpatialPoint;
+      let speedMps: number | null;
+      let courseDeg: number | null;
+      try {
+        if (!collectors.location) throw unsupported('location collector');
+        const fix: any = await collectors.location.getPosition({ accuracy: 'low' });
+        point = {
+          latitude: fix.latitude,
+          longitude: fix.longitude,
+          altitude: fix.altitude ?? null,
+          accuracyM: nonNegative(fix.accuracy),
+          timestamp: fix.timestamp ?? Date.now(),
+        };
+        speedMps = nonNegative(fix.speed);
+        courseDeg = nonNegative(fix.course);
+      } catch {
+        // Permission refused, or no fix. Not a position at (0,0).
+        return noFix();
       }
-
-      // Fall back to the path only where the OS said nothing.
-      if (speedMps === null) { const d = derivedSpeed(); if (d !== null) { speedMps = d; derived = true; } }
-      if (courseDeg === null) { const d = derivedCourse(); if (d !== null) { courseDeg = d; derived = true; } }
-
-      const heading = currentHeadingDetail();
-      const turn = lastMeaningfulTurn();
-
-      return {
-        position: point,
-        movement: {
-          speedMps,
-          bearingDeg: courseDeg,
-          // Needs two points from the SAME session; without a stream there is
-          // nothing to measure against, and a distance of 0 would read as
-          // "the user has not moved".
-          distanceRecentM: recentPath.length >= 2 ? distanceOf(recentPath) : null,
-          // 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.
-          state: speedMps === null ? 'unknown' : speedMps < STATIONARY_MPS ? 'stationary' : 'moving',
-        },
-        orientation: {
-          headingDeg: heading?.headingDeg ?? null,
-          // NOT the calibration rank. iOS reports 0–3 (none…high), which is not
-          // a number of degrees, and converting one to the other would be an
-          // invented error bar. The rank drives `confidence` below instead.
-          headingAccuracyDeg: null,
-        },
-        changes: {
-          lastMeaningfulTurnDeg: turn ? turn.deg : null,
-          timestamp: turn ? turn.timestamp : null,
-        },
-        recentPath: [...recentPath],
-        quality: qualityFrom(
-          point.timestamp,
-          spatialConfidence(point.accuracyM ?? null, heading?.calibration ?? null, derived),
-        ),
-      };
+      return snapshotFrom(point, speedMps, courseDeg);
     },
 
     /**
-     * Open the warm window: position stream + compass.
+     * Open the warm window: position stream + compass + event feed.
      *
-     * The intent is recorded but does NOT yet change sampling — no native
-     * strategy layer exists — so it is accepted rather than refused only
-     * because the streams it opens are real and useful.
+     * The intent selects how eager the EVENTS are (spatialEvents.ts profiles)
+     * and the GPS TIER the stream runs at (WATCH_ACCURACY): navigation pays the
+     * battery for BestForNavigation; low-power tracking does not.
+     *
+     * A second `start()` while one is open joins the running session and is
+     * told ITS intent, not handed back the one it asked for: answering with the
+     * caller's intent would claim a profile that is not in force.
      */
     async start(options) {
-      if (stopWatch) return { id: sessionId!, intent: options.intent, startedAt: Date.now() } as any;
-      sessionId = `spatial_${Date.now()}`;
+      if (session) return { ...session };
       if (!collectors.location) throw unsupported('location collector');
+      const startedAt = Date.now();
+      session = { id: `spatial_${startedAt}`, intent: options.intent, startedAt };
+      // A turn the compass completed before this session (a visual session
+      // shares it) is already on record, not news.
+      detector.reset(spatialEventProfile(options.intent), lastMeaningfulTurn()?.timestamp ?? null);
       // The compass is what makes heading and turn detection possible, and it
       // has to run for the session's whole life: a turn happens between reads,
       // so a compass started on demand would miss exactly the event a guide
-      // most needs. Idempotent, and shared with a visual session if one is open.
-      void startHeading();
+      // most needs. Shared with a visual session if one is open.
+      void startHeading('spatial');
+      // A turn is published the moment it completes, not on the next tick.
+      turnSub = onTurn(observe);
       stopWatch = collectors.location.watchPosition((pos: any) => {
         const p: SpatialPoint = {
           latitude: pos.latitude,
@@ -190,14 +279,22 @@ export function createSpatialDomain(
         speedRef.mps = latestSpeed;
         speedRef.at = p.timestamp;
         recentPath = [...recentPath, p].slice(-RECENT_PATH_MAX);
-      });
-      return { id: sessionId, intent: options.intent, startedAt: Date.now() } as any;
+        observe();
+      }, { accuracy: WATCH_ACCURACY[options.intent] ?? 'balanced' });
+      startTicking();
+      return { ...session };
     },
 
     async stop() {
       stopWatch?.();
       stopWatch = null;
-      sessionId = null;
+      session = null;
+      stopTicking();
+      turnSub?.unsubscribe();
+      turnSub = null;
+      // Listeners are KEPT: a subscription outlives a session, and hears the
+      // next one. Only what this session observed is forgotten.
+      detector.reset();
       // The path belongs to the session that recorded it. Keeping it would let
       // a later snapshot report movement from a walk that ended hours ago.
       recentPath = [];
@@ -206,14 +303,18 @@ export function createSpatialDomain(
       latestCourse = null;
       speedRef.mps = null;
       speedRef.at = 0;
-      // Leave the compass alone if a visual session is still using it — it is
-      // shared, and stopping it here would silently blind the frame stamps.
-      if (!visualEngine.getSession()) stopHeading();
+      // Releases only spatial's hold — a visual session keeps the compass.
+      stopHeading('spatial');
     },
 
-    // No event vocabulary is frozen for spatial, and inventing names here would
-    // put them in plugins before the freeze can contradict them.
-    subscribe() { throw unsupported('spatial.subscribe'); },
+    /**
+     * The six spatial events (see `SpatialEvent`). Subscribing opens no sensor:
+     * events flow only while a session is open, and a subscription made before
+     * `start()` hears that session from its first fix.
+     */
+    subscribe(listener) {
+      return listeners.add(listener);
+    },
   };
 }
 
@@ -238,10 +339,8 @@ function spatialConfidence(
   const rank = (v: 'high' | 'medium' | 'low' | 'unknown') =>
     v === 'high' ? 3 : v === 'medium' ? 2 : v === 'low' ? 1 : 0;
 
-  // 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".
-  const fromFix: 'high' | 'medium' | 'low' | 'unknown' =
-    accuracyM === null ? 'unknown' : accuracyM <= 10 ? 'high' : accuracyM <= 50 ? 'medium' : 'low';
+  // The fix band is shared with positionConfidenceChanged — one set of numbers.
+  const fromFix = fixConfidence(accuracyM);
 
   // iOS calibration rank: 3 high, 2 medium, 1 low, 0 none.
   const fromCompass: 'high' | 'medium' | 'low' | 'unknown' =
@@ -266,18 +365,3 @@ function bearingBetween(a: SpatialPoint, b: SpatialPoint): number {
   const x = Math.cos(la1) * Math.sin(la2) - Math.sin(la1) * Math.cos(la2) * Math.cos(dLon);
   return (((Math.atan2(y, x) * 180) / Math.PI) + 360) % 360;
 }
-
-/** Metres along a path, great-circle per leg. */
-function distanceOf(path: SpatialPoint[]): 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/device-state/domains/visual.ts

@@ -8,6 +8,24 @@ import type { DeviceState, VisualSnapshot } from '@ateam-ai-mobile/plugin-runtim
 import { visualEngine, frameQuality } from '../visualEngine';
 import { currentHeading, startHeading, stopHeading } from '../headingSource';
 import { unsupported } from '../quality';
+import { stateEvent } from '../events';
+
+/**
+ * The camera block of a visual snapshot — one builder, so the read and the
+ * change event cannot describe the camera two ways.
+ */
+function cameraState(): VisualSnapshot['camera'] {
+  const session = visualEngine.getSession();
+  return {
+    // `available` = the app could use a camera at all. `active` = one is
+    // running RIGHT NOW. They differ exactly when it matters: a pocketed
+    // phone is available but not active, and answering `true` to both
+    // would let a guide speak about a scene nothing is watching.
+    available: !!session,
+    active: visualEngine.isCameraReady(),
+    facing: session ? 'back' : 'unknown',
+  };
+}
 
 /**
  * Reads the rolling timeline the engine maintains. See visualEngine.ts for why
@@ -20,20 +38,11 @@ import { unsupported } from '../quality';
 export function createVisualDomain(): DeviceState['visual'] {
   return {
     async getSnapshot(): Promise<VisualSnapshot> {
-      const session = visualEngine.getSession();
       const latest = visualEngine.latest();
       const timeline = visualEngine.timeline();
 
       return {
-        camera: {
-          // `available` = the app could use a camera at all. `active` = one is
-          // running RIGHT NOW. They differ exactly when it matters: a pocketed
-          // phone is available but not active, and answering `true` to both
-          // would let a guide speak about a scene nothing is watching.
-          available: !!session,
-          active: visualEngine.isCameraReady(),
-          facing: session ? 'back' : 'unknown',
-        },
+        camera: cameraState(),
         // null, not a stale frame dressed as current. A caller with no usable
         // frame must see nothing rather than something old.
         latest: latest as any,
@@ -48,14 +57,15 @@ export function createVisualDomain(): DeviceState['visual'] {
       // launch: a magnetometer subscription running all day for a feature
       // nobody opened is exactly the kind of cost this layer is meant to avoid.
       visualEngine.setContextProvider({ heading: currentHeading });
-      void startHeading();
+      void startHeading('visual');
       return { id: s.id, intent: s.intent, startedAt: s.startedAt } as any;
     },
 
     async stop() {
       visualEngine.stopSession();
       visualEngine.setContextProvider(null);
-      stopHeading();
+      // Releases only visual's hold — a spatial session keeps the compass.
+      stopHeading('visual');
     },
 
     /**
@@ -90,9 +100,20 @@ export function createVisualDomain(): DeviceState['visual'] {
       throw err;
     },
 
+    /**
+     * Fires when the CAMERA block changes — a session opening or closing, the
+     * camera coming up or going down. The engine notifies on every frame too,
+     * and forwarding that made this a raw frame stream, which the freeze's core
+     * rule 4 forbids. A frame arriving is what `getSnapshot()` is for.
+     */
     subscribe(listener) {
+      let last = JSON.stringify(cameraState());
       const off = visualEngine.subscribe(() => {
-        listener({ type: 'visualStateChanged' } as any);
+        const camera = cameraState();
+        const key = JSON.stringify(camera);
+        if (key === last) return;
+        last = key;
+        listener(stateEvent('visual', 'visualStateChanged', { camera }));
       });
       return { unsubscribe: off };
     },

package/src/device-state/events.ts

@@ -0,0 +1,49 @@
+/**
+ * The ONE event envelope every domain emits, and the one way listeners are held.
+ *
+ * The frozen shape is `StateEvent { domain, name, timestamp, payload }`. Three
+ * domains were born emitting `{ type: '…' }` instead, so a plugin written
+ * against the contract — `e.name === 'appStateChanged'` — never matched, and
+ * `e.name.endsWith(…)` threw on `undefined`. Building every event here is what
+ * keeps a second shape from growing back.
+ *
+ * Type-only imports, so the pure modules that use this (the spatial event
+ * detector) stay testable under plain `node --test`.
+ */
+import type { DeviceBridgeDomain, StateEvent, Subscription } from '@ateam-ai-mobile/plugin-runtime';
+
+/**
+ * Build an event. `payload` is omitted, not `undefined`, when there is none —
+ * an event that is only a nudge ("re-read the snapshot") says so by shape.
+ * `timestamp` is when the change was recognised; it defaults to now, and replay
+ * passes its virtual clock.
+ */
+export function stateEvent<TDomain extends DeviceBridgeDomain, TName extends string, TPayload = never>(
+  domain: TDomain,
+  name: TName,
+  payload?: TPayload,
+  timestamp: number = Date.now(),
+): StateEvent<TName, TPayload> & { domain: TDomain } {
+  return payload === undefined
+    ? { domain, name, timestamp }
+    : { domain, name, timestamp, payload };
+}
+
+/**
+ * Listeners, each isolated from the others. A listener that throws must not
+ * stop the next one hearing the event, nor the engine that emitted it.
+ */
+export function listenerSet<E>() {
+  const listeners = new Set<(event: E) => void>();
+  return {
+    add(fn: (event: E) => void): Subscription {
+      listeners.add(fn);
+      return { unsubscribe: () => { listeners.delete(fn); } };
+    },
+    emit(event: E): void {
+      for (const fn of listeners) {
+        try { fn(event); } catch { /* a bad listener is not the engine's problem */ }
+      }
+    },
+  };
+}

package/src/device-state/headingSource.ts

@@ -13,15 +13,25 @@
  * event, not a state — so a detector driven by sampled snapshots would miss
  * exactly the moment a guide needs. It runs on the compass callback instead.
  * The logic itself lives in `turnDetector.ts`, free of any Expo import, so it
- * can be tested against a scripted walk.
+ * can be tested against a scripted walk. A completed turn is also PUSHED to
+ * `onTurn` listeners — spatial publishes it as an event the moment it lands.
+ *
+ * SHARED, SO COUNTED. Spatial and visual both keep the compass warm, and each
+ * used to stop it on its own `stop()`: visual's stop killed the compass — and
+ * wiped the turn history — under a live spatial session. Each caller now names
+ * itself, and the watch stops only when the last one leaves.
  */
 import * as ExpoLocation from 'expo-location';
 
 import { TurnDetector, type TurnEvent } from './turnDetector';
+import { listenerSet } from './events';
 
 export type { TurnEvent };
 export { signedDelta } from './turnDetector';
 
+/** Who is holding the compass open. */
+export type HeadingOwner = 'spatial' | 'visual';
+
 interface HeadingReading {
   headingDeg: number | null;
   /**
@@ -36,21 +46,38 @@ interface HeadingReading {
 
 let latest: HeadingReading | null = null;
 let sub: { remove(): void } | null = null;
+/** The watch being opened, so two owners starting at once open ONE. */
+let opening: Promise<void> | null = null;
+const owners = new Set<HeadingOwner>();
 const turns = new TurnDetector();
+const turnListeners = listenerSet<TurnEvent>();
+
+/** Start watching on behalf of `owner`. Idempotent per owner. */
+export function startHeading(owner: HeadingOwner): Promise<void> {
+  owners.add(owner);
+  if (sub) return Promise.resolve();
+  opening ??= open().finally(() => { opening = null; });
+  return opening;
+}
 
-/** Start watching. Idempotent; safe to call on every session start. */
-export async function startHeading(): Promise<void> {
-  if (sub) return;
+async function open(): Promise<void> {
   try {
-    sub = await ExpoLocation.watchHeadingAsync(h => {
+    const s = await ExpoLocation.watchHeadingAsync(h => {
+      // A reading landing after the last owner left is not kept.
+      if (!owners.size) return;
       // trueHeading is -1 until the compass calibrates; magHeading is the
       // fallback the OS itself recommends.
       const raw = h.trueHeading >= 0 ? h.trueHeading : h.magHeading;
       const deg = typeof raw === 'number' && raw >= 0 ? raw : null;
       const cal = typeof h.accuracy === 'number' && h.accuracy >= 0 ? h.accuracy : null;
-      latest = { headingDeg: deg, calibration: cal, timestamp: Date.now() };
-      turns.push(deg, Date.now());
+      const now = Date.now();
+      latest = { headingDeg: deg, calibration: cal, timestamp: now };
+      const turn = turns.push(deg, now);
+      if (turn) turnListeners.emit(turn);
     });
+    // Every owner may have left while the OS was starting the watch.
+    if (!owners.size) { s.remove(); return; }
+    sub = s;
   } catch {
     // No compass, or permission refused. Callers get headingDeg: null, which
     // is the honest answer and does not stop anything else working.
@@ -58,7 +85,10 @@ export async function startHeading(): Promise<void> {
   }
 }
 
-export function stopHeading(): void {
+/** Release `owner`'s hold. The watch stops only when no owner is left. */
+export function stopHeading(owner: HeadingOwner): void {
+  owners.delete(owner);
+  if (owners.size) return;
   sub?.remove();
   sub = null;
   // Clear everything: a heading from a finished session describes a direction
@@ -68,6 +98,11 @@ export function stopHeading(): void {
   turns.reset();
 }
 
+/** Hear each completed turn as it completes. Signed: positive = right. */
+export function onTurn(fn: (turn: TurnEvent) => void) {
+  return turnListeners.add(fn);
+}
+
 /** The newest reading, or null if the compass has said nothing yet. */
 export function currentHeading(): { headingDeg: number | null } | null {
   return latest ? { headingDeg: latest.headingDeg } : null;

package/src/device-state/index.ts

@@ -14,9 +14,10 @@
  *   connectivity   reachability ✓ transport ✓   quality/stability/metered ✗
  *   capability     permission ✓   availability ✗   restriction ✗
  *   interaction    app lifecycle ✓  screenOn ✗  audio ✗
- *   spatial        position ✓  path ✓ (while a session is open)  heading/speed ✗
+ *   spatial        position ✓ heading ✓ turns ✓  path/events ✓ (while a session is open)  speed ~derived
  *   visual         frames ✓ heading ✓ freshness ✓   blur/exposure ✗
- *   activity / environment — NOT IMPLEMENTED AT ALL
+ *   activity       walking/running/stationary ✓ pose ✓   cycling/driving ✗   events ✗
+ *   environment    NOT IMPLEMENTED AT ALL
  *
  * Everything marked ✗ reports `unknown`, which is a real answer in this design
  * and the only honest one. It never reports a plausible default: an invented