@ateam-ai-mobile/expo 0.1.4 → 0.1.7

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

@@ -0,0 +1,55 @@
+// ── deviceContext ──────────────────────────────────────────────────────────
+//   power ✓   thermal ✗ (needs a native module)   memory/storage ✗
+import * as ExpoBattery from 'expo-battery';
+import type { DeviceState, DeviceContextSnapshot } from '@ateam-ai-mobile/plugin-runtime';
+import { qualityFrom, qualityUnknown } from '../quality';
+
+export function createDeviceContextDomain(): DeviceState['deviceContext'] {
+  return {
+    async getSnapshot(): Promise<DeviceContextSnapshot> {
+      const observedAt = Date.now();
+      try {
+        const [level, state, lowPower] = await Promise.all([
+          ExpoBattery.getBatteryLevelAsync(),
+          ExpoBattery.getBatteryStateAsync(),
+          ExpoBattery.isLowPowerModeEnabledAsync(),
+        ]);
+        return {
+          power: {
+            // expo-battery returns -1 when it cannot tell. That is not a level.
+            batteryLevel: typeof level === 'number' && level >= 0 ? level : null,
+            charging:
+              state === ExpoBattery.BatteryState.CHARGING ||
+              state === ExpoBattery.BatteryState.FULL,
+            lowPowerMode: lowPower,
+          },
+          // No Expo API for either. iOS needs ProcessInfo.thermalState, Android
+          // PowerManager.getThermalStatus — a native module that does not exist.
+          thermal: { state: 'unknown' },
+          resources: { memoryPressure: 'unknown', storagePressure: 'unknown' },
+          quality: qualityFrom(observedAt),
+        };
+      } catch {
+        // The battery read failing is rare and uninteresting; reporting it as
+        // 0% would not be.
+        return {
+          power: { batteryLevel: null, charging: null, lowPowerMode: null },
+          thermal: { state: 'unknown' },
+          resources: { memoryPressure: 'unknown', storagePressure: 'unknown' },
+          quality: qualityUnknown(),
+        };
+      }
+    },
+
+    // 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.
+    subscribe(listener) {
+      const subs = [
+        ExpoBattery.addBatteryLevelListener(() => listener({ type: 'batteryLevelChanged' } as any)),
+        ExpoBattery.addBatteryStateListener(() => listener({ type: 'chargingChanged' } as any)),
+      ];
+      return { unsubscribe: () => subs.forEach(x => x?.remove?.()) };
+    },
+  };
+}

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

@@ -0,0 +1,59 @@
+// ── interaction ──────────────────────────────────────────────────────────
+//   app lifecycle ✓  screenOn ✗  audio ✗
+import { AppState } from 'react-native';
+import type { DeviceState, InteractionSnapshot } from '@ateam-ai-mobile/plugin-runtime';
+import { qualityFrom } from '../quality';
+
+/**
+ * Lifecycle only, and honest about the rest.
+ *
+ * `screenOn` is NOT derivable from AppState: RN reports `inactive` for a
+ * notification shade, a control centre swipe, an incoming call AND a locked
+ * screen. Mapping `inactive` to "screen off" would be wrong most of the time
+ * it fired — so it stays null until a native module can answer it.
+ *
+ * The whole `audio` block reports unknown for the same reason. `interruption`
+ * carries the distinction that matters: `none` means "checked, nothing is
+ * interrupting", `unknown` means "no knowledge" — and we have the latter.
+ */
+export function createInteractionDomain(): DeviceState['interaction'] {
+  const mapState = (s: string): InteractionSnapshot['lifecycle']['appState'] =>
+    s === 'active' ? 'foreground'
+      : s === 'background' ? 'background'
+      : s === 'inactive' ? 'inactive'
+      : 'unknown';
+
+  return {
+    async getSnapshot(): Promise<InteractionSnapshot> {
+      const observedAt = Date.now();
+      return {
+        lifecycle: {
+          appState: mapState(AppState.currentState as string),
+          screenOn: null,
+          userActive: null,
+          idleDurationMs: null,
+        },
+        audio: {
+          captureActive: null,
+          playbackActive: null,
+          route: 'unknown',
+          interruption: 'unknown',
+        },
+        // The voice block is OMITTED rather than filled with nulls: the design
+        // says a platform that cannot report voice session state leaves the
+        // group out instead of guessing `false` for each field. The app's own
+        // voice store knows this, but it is not reachable from the SDK.
+        quality: qualityFrom(observedAt),
+      };
+    },
+
+    // Real: AppState genuinely emits on every foreground/background change,
+    // 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);
+      });
+      return { unsubscribe: () => sub.remove() };
+    },
+  };
+}

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

@@ -0,0 +1,283 @@
+// ── 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';
+import { qualityFrom, qualityUnknown, unsupported } from '../quality';
+
+/**
+ * Position, movement, facing and a short recent path.
+ *
+ * The design's performance rule is that navigation reads come from a WARM
+ * native cache, not a fresh GPS+compass call per invocation. There is no such
+ * cache today, so `getSnapshot` takes a fix — correct but not cheap. That is
+ * why `start()` matters: it opens a `watchPosition` stream AND a compass watch,
+ * and every later snapshot serves the newest streamed values instead, which is
+ * the warm path this layer can offer without a native module.
+ *
+ * TWO DIRECTIONS, NOT ONE, and conflating them is the bug this replaced.
+ *
+ *   `orientation.headingDeg`  — where the phone is POINTING. The compass.
+ *   `movement.bearingDeg`     — where the user is GOING. Course over ground.
+ *
+ * They disagree constantly and each answers a different sentence. "Turn right
+ * at the corner" is decided by the compass; "you are heading north on Main
+ * Street" by the course. The previous version assigned the same variable to
+ * both, which is only right by accident, and that variable was permanently
+ * null because the streaming collector dropped the fields.
+ *
+ * TURNS ARE SIGNED. `changes.lastMeaningfulTurnDeg` is positive for clockwise
+ * (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.
+ */
+export function createSpatialDomain(
+  collectors: DeviceStateCollectors,
+  speedRef: SpeedRef,
+): DeviceState['spatial'] {
+  // 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;
+  /** Speed and course from the newest STREAMED fix — see `latest`. */
+  let latestSpeed: number | null = null;
+  let latestCourse: number | null = null;
+  let stopWatch: (() => void) | null = null;
+  let sessionId: string | null = null;
+
+  const nonNegative = (v: unknown): number | null =>
+    typeof v === 'number' && v >= 0 ? v : null;
+
+  /**
+   * Speed from the path when the OS declined to estimate one.
+   *
+   * Only over the last two points and only if they are close in time: two fixes
+   * a minute apart give an average that describes neither moment. Returns null
+   * rather than a number the caller cannot tell apart from a measured one —
+   * the confidence on the snapshot is what marks it as derived.
+   */
+  const derivedSpeed = (): number | null => {
+    if (recentPath.length < 2) return null;
+    const b = recentPath[recentPath.length - 1];
+    const a = recentPath[recentPath.length - 2];
+    const dtS = (b.timestamp - a.timestamp) / 1000;
+    if (dtS <= 0 || dtS > 10) return null;
+    return distanceOf([a, b]) / dtS;
+  };
+
+  /** Course from the path, for the same reason and with the same caution. */
+  const derivedCourse = (): number | null => {
+    if (recentPath.length < 2) return null;
+    const b = recentPath[recentPath.length - 1];
+    const a = recentPath[recentPath.length - 2];
+    if (b.timestamp - a.timestamp > 10_000) return null;
+    // Too small a step is noise, not a direction.
+    if (distanceOf([a, b]) < 3) return null;
+    return bearingBetween(a, b);
+  };
+
+  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;
+
+      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(),
+          };
+        }
+      }
+
+      // 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),
+        ),
+      };
+    },
+
+    /**
+     * Open the warm window: position stream + compass.
+     *
+     * 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.
+     */
+    async start(options) {
+      if (stopWatch) return { id: sessionId!, intent: options.intent, startedAt: Date.now() } as any;
+      sessionId = `spatial_${Date.now()}`;
+      if (!collectors.location) throw unsupported('location collector');
+      // 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();
+      stopWatch = collectors.location.watchPosition((pos: any) => {
+        const p: SpatialPoint = {
+          latitude: pos.latitude,
+          longitude: pos.longitude,
+          altitude: pos.altitude ?? null,
+          accuracyM: nonNegative(pos.accuracy),
+          timestamp: pos.timestamp ?? Date.now(),
+        };
+        latest = p;
+        latestSpeed = nonNegative(pos.speed);
+        latestCourse = nonNegative(pos.course);
+        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;
+    },
+
+    async stop() {
+      stopWatch?.();
+      stopWatch = null;
+      sessionId = null;
+      // 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 = [];
+      latest = null;
+      latestSpeed = null;
+      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();
+    },
+
+    // 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'); },
+  };
+}
+
+/**
+ * How much to trust this spatial reading.
+ *
+ * Three things degrade it and they are not interchangeable: a loose GPS fix
+ * (the position is vague), an uncalibrated compass (the FACING is vague, which
+ * is what breaks "turn left"), and values derived from the path rather than
+ * measured by the OS. The lowest of the three wins, because a caller acting on
+ * the snapshot is exposed to the worst part of it, not the average.
+ *
+ * This is the signal that decides Ada Guide's modality switch: indoors the fix
+ * degrades, confidence drops, and that drop is what makes the guide ask for the
+ * camera instead of guessing from a GPS fix it should not trust.
+ */
+function spatialConfidence(
+  accuracyM: number | null,
+  calibration: number | null,
+  derived: boolean,
+): StateQuality['confidence'] {
+  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';
+
+  // iOS calibration rank: 3 high, 2 medium, 1 low, 0 none.
+  const fromCompass: 'high' | 'medium' | 'low' | 'unknown' =
+    calibration === null ? 'unknown'
+      : calibration >= 3 ? 'high'
+      : calibration >= 2 ? 'medium'
+      : 'low';
+
+  const parts = [fromFix, fromCompass, ...(derived ? (['low'] as const) : [])];
+  const known = parts.filter(p => p !== 'unknown');
+  if (!known.length) return { level: 'unknown' };
+  const worst = known.reduce((a, b) => (rank(a) <= rank(b) ? a : b));
+  return { level: worst };
+}
+
+/** Initial bearing from `a` to `b`, degrees clockwise from north. */
+function bearingBetween(a: SpatialPoint, b: SpatialPoint): number {
+  const toRad = (d: number) => (d * Math.PI) / 180;
+  const la1 = toRad(a.latitude), la2 = toRad(b.latitude);
+  const dLon = toRad(b.longitude - a.longitude);
+  const y = Math.sin(dLon) * Math.cos(la2);
+  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

@@ -0,0 +1,100 @@
+// ── visual ───────────────────────────────────────────────────────────────
+//   frames ✓ heading ✓ freshness ✓   blur/exposure ✗
+//
+// Visual owns the semantic frame timeline/retention: the rolling ring, opaque
+// frame ids, and the freshness the frames carry (frameQuality) — see
+// visualEngine.ts. Opaque ids only above L1; pixels never cross to JS.
+import type { DeviceState, VisualSnapshot } from '@ateam-ai-mobile/plugin-runtime';
+import { visualEngine, frameQuality } from '../visualEngine';
+import { currentHeading, startHeading, stopHeading } from '../headingSource';
+import { unsupported } from '../quality';
+
+/**
+ * Reads the rolling timeline the engine maintains. See visualEngine.ts for why
+ * the capture half lives in a mounted component.
+ *
+ * `getSnapshot` NEVER opens the camera and never takes a picture — that is the
+ * design's explicit performance rule, and the reason a guidance loop can ask
+ * every turn without paying for it. What it costs is one array read.
+ */
+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',
+        },
+        // 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,
+        recentTimeline: timeline as any,
+        quality: frameQuality(latest),
+      };
+    },
+
+    async start(options) {
+      const s = visualEngine.startSession((options?.intent as any) || 'navigation');
+      // Warm the compass alongside the camera. Started here rather than at app
+      // 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();
+      return { id: s.id, intent: s.intent, startedAt: s.startedAt } as any;
+    },
+
+    async stop() {
+      visualEngine.stopSession();
+      visualEngine.setContextProvider(null);
+      stopHeading();
+    },
+
+    /**
+     * A deliberate one-shot. Distinct from getSnapshot because it is an
+     * OPERATION: it waits for a frame rather than serving the newest one.
+     *
+     * Throws when it cannot, rather than returning an empty result — the
+     * design is explicit that capture is an operation and reads are state.
+     */
+    async capture() {
+      if (!visualEngine.getSession()) {
+        throw unsupported('visual.capture without an open session — call start({ intent }) first');
+      }
+      if (!visualEngine.isCameraReady()) {
+        const err: any = new Error(
+          'The camera is not running right now — the app may be in the background.',
+        );
+        err.code = 'TEMPORARILY_UNAVAILABLE';
+        throw err;
+      }
+      // Wait briefly for the NEXT frame rather than returning the last one:
+      // "capture" means now, and the newest ring entry may be a second old.
+      const before = visualEngine.latest()?.timestamp ?? 0;
+      const deadline = Date.now() + 4000;
+      while (Date.now() < deadline) {
+        const f = visualEngine.latest();
+        if (f && f.timestamp > before) return { frame: f } as any;
+        await new Promise(r => setTimeout(r, 100));
+      }
+      const err: any = new Error('No frame arrived within 4s.');
+      err.code = 'TIMEOUT';
+      throw err;
+    },
+
+    subscribe(listener) {
+      const off = visualEngine.subscribe(() => {
+        listener({ type: 'visualStateChanged' } as any);
+      });
+      return { unsubscribe: off };
+    },
+  };
+}

package/src/device-state/headingSource.ts

@@ -0,0 +1,84 @@
+/**
+ * The compass, kept warm — and the turn detector fed from it.
+ *
+ * `getHeadingAsync()` is not usable on the capture path: it starts a watch,
+ * waits for a reading and stops it, which costs hundreds of milliseconds — per
+ * frame. So this holds ONE subscription while a session is open and callers
+ * read the last value synchronously.
+ *
+ * Returns null until a reading arrives, and null means NOT MEASURED. A heading
+ * of 0 is due north, so an unstarted compass must never report 0.
+ *
+ * WHY THE TURN DETECTOR IS FED HERE. A turn happens BETWEEN reads — it is an
+ * 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.
+ */
+import * as ExpoLocation from 'expo-location';
+
+import { TurnDetector, type TurnEvent } from './turnDetector';
+
+export type { TurnEvent };
+export { signedDelta } from './turnDetector';
+
+interface HeadingReading {
+  headingDeg: number | null;
+  /**
+   * iOS calibration rank: 3 high, 2 medium, 1 low, 0 none. NOT degrees of
+   * error, which is why it is never surfaced as `headingAccuracyDeg` — that
+   * field wants degrees, and converting a rank into one would be a fabricated
+   * error bar. It drives CONFIDENCE instead, which is what it can honestly say.
+   */
+  calibration: number | null;
+  timestamp: number;
+}
+
+let latest: HeadingReading | null = null;
+let sub: { remove(): void } | null = null;
+const turns = new TurnDetector();
+
+/** Start watching. Idempotent; safe to call on every session start. */
+export async function startHeading(): Promise<void> {
+  if (sub) return;
+  try {
+    sub = await ExpoLocation.watchHeadingAsync(h => {
+      // 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());
+    });
+  } catch {
+    // No compass, or permission refused. Callers get headingDeg: null, which
+    // is the honest answer and does not stop anything else working.
+    sub = null;
+  }
+}
+
+export function stopHeading(): void {
+  sub?.remove();
+  sub = null;
+  // Clear everything: a heading from a finished session describes a direction
+  // the user may have long since turned away from, and a turn from a previous
+  // walk is not something a new one should report.
+  latest = null;
+  turns.reset();
+}
+
+/** 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;
+}
+
+/** The newest reading with its calibration and age. */
+export function currentHeadingDetail(): HeadingReading | null {
+  return latest;
+}
+
+/** The most recent completed turn. Signed: positive = clockwise = right. */
+export function lastMeaningfulTurn(): TurnEvent | null {
+  return turns.last();
+}

package/src/device-state/index.ts

@@ -0,0 +1,77 @@
+/**
+ * Device Bridge v2 — the runtime behind `props.deviceState`.
+ *
+ * R5 split the former monolith into one module per domain (./domains/*), a
+ * single quality module that owns freshness/confidence/unknown (./quality), and
+ * this composition root, which wires the domains and injects their dependencies.
+ * The behaviour — and every snapshot shape — is unchanged; only the file layout is.
+ *
+ * WHAT IS AND IS NOT HERE — stated up front, because a half-built state layer
+ * that pretends to be whole is the exact failure this whole effort exists to
+ * end:
+ *
+ *   deviceContext  power ✓   thermal ✗   memory/storage ✗
+ *   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 ✗
+ *   visual         frames ✓ heading ✓ freshness ✓   blur/exposure ✗
+ *   activity / 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
+ * 'nominal' thermal state is indistinguishable from a measured one, and that is
+ * how 56 fabrications reached users from the layer below.
+ *
+ * A domain with no engine here is not simply missing: `gateDeviceState` (in
+ * plugin-runtime/src/deviceStateHost.ts) fills the gap with a domain whose
+ * reads answer explicit `unknown`s and whose ACTIONS throw. So a plugin can
+ * call any of the eight without an existence check, and still cannot mistake
+ * "not built" for "nothing to report". `environment` is deliberately absent
+ * from the composition below for exactly that reason.
+ */
+import type { DeviceState } from '@ateam-ai-mobile/plugin-runtime';
+import { DeviceStateCollectors, SpeedRef } from './collectors';
+import { createDeviceContextDomain } from './domains/deviceContext';
+import { createConnectivityDomain } from './domains/connectivity';
+import { createCapabilityDomain } from './domains/capability';
+import { createInteractionDomain } from './domains/interaction';
+import { createSpatialDomain } from './domains/spatial';
+import { createVisualDomain } from './domains/visual';
+import { createActivityDomain } from './domains/activity';
+
+export type { DeviceStateCollectors, SpeedRef } from './collectors';
+
+/**
+ * Build the semantic surface.
+ *
+ * Only implemented domains appear. `environment` is deliberately absent: a
+ * plugin touching it gets a TypeError naming it, which is a far better failure
+ * than a snapshot of nulls that reads like a quiet device.
+ */
+export function createDeviceState(collectors: DeviceStateCollectors = {}): Partial<DeviceState> {
+  // The ONE explicit cross-domain dependency: Activity needs Spatial's newest
+  // speed to tell "walking" from "sitting in a moving car". Passed as a shared
+  // reference, not a cross-domain import — see SpeedRef.
+  const speedRef: SpeedRef = { mps: null, at: 0 };
+  return {
+    deviceContext: createDeviceContextDomain(),
+    connectivity: createConnectivityDomain(collectors),
+    capability: createCapabilityDomain(collectors),
+    interaction: createInteractionDomain(),
+    spatial: createSpatialDomain(collectors, speedRef),
+    visual: createVisualDomain(),
+    activity: createActivityDomain(speedRef),
+  };
+}
+
+/** Which domains this build can actually answer. */
+export const IMPLEMENTED_DOMAINS = [
+  'deviceContext',
+  'connectivity',
+  'capability',
+  'interaction',
+  'spatial',
+  'visual',
+  'activity',
+] as const;