@ateam-ai-mobile/expo 0.1.7 → 0.1.8

package/dist/index.js

@@ -247,6 +247,30 @@ function unsupported(what) {
   return err;
 }
 
+// src/device-state/events.ts
+function stateEvent(domain, name, payload, timestamp = Date.now()) {
+  return payload === void 0 ? { domain, name, timestamp } : { domain, name, timestamp, payload };
+}
+function listenerSet() {
+  const listeners = /* @__PURE__ */ new Set();
+  return {
+    add(fn) {
+      listeners.add(fn);
+      return { unsubscribe: () => {
+        listeners.delete(fn);
+      } };
+    },
+    emit(event) {
+      for (const fn of listeners) {
+        try {
+          fn(event);
+        } catch {
+        }
+      }
+    }
+  };
+}
+
 // src/device-state/domains/deviceContext.ts
 function createDeviceContextDomain() {
   return {
@@ -282,11 +306,12 @@ function createDeviceContextDomain() {
     },
     // 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" })),
-        ExpoBattery.addBatteryStateListener(() => listener({ type: "chargingChanged" }))
+        ExpoBattery.addBatteryLevelListener(() => listener(stateEvent("deviceContext", "batteryLevelChanged"))),
+        ExpoBattery.addBatteryStateListener(() => listener(stateEvent("deviceContext", "chargingChanged")))
       ];
       return { unsubscribe: () => subs.forEach((x) => x?.remove?.()) };
     }
@@ -422,13 +447,523 @@ function createInteractionDomain() {
     // which is the one part of this domain that works.
     subscribe(listener) {
       const sub2 = import_react_native.AppState.addEventListener("change", (next) => {
-        listener({ type: "appStateChanged", appState: mapState(next) });
+        listener(stateEvent("interaction", "appStateChanged", { appState: mapState(next) }));
       });
       return { unsubscribe: () => sub2.remove() };
     }
   };
 }
 
+// src/device-state/headingSource.ts
+var ExpoLocation = __toESM(require("expo-location"));
+
+// src/device-state/turnDetector.ts
+function signedDelta(a, b) {
+  return (b - a + 540) % 360 - 180;
+}
+var TurnDetector = class {
+  constructor(opts = {}) {
+    /** The heading currently treated as "straight ahead". */
+    this.refDeg = null;
+    this.stableSince = 0;
+    this.lastTurn = null;
+    this.minTurnDeg = opts.minTurnDeg ?? 35;
+    this.stableDeg = opts.stableDeg ?? 12;
+    this.stableMs = opts.stableMs ?? 2500;
+  }
+  /** Feed one compass reading. `null` degrees means the compass said nothing. */
+  push(deg, now) {
+    if (deg === null) return null;
+    if (this.refDeg === null) {
+      this.refDeg = deg;
+      this.stableSince = now;
+      return null;
+    }
+    const delta = signedDelta(this.refDeg, deg);
+    if (Math.abs(delta) >= this.minTurnDeg) {
+      this.lastTurn = { deg: Math.round(delta), timestamp: now };
+      this.refDeg = deg;
+      this.stableSince = now;
+      return this.lastTurn;
+    }
+    if (Math.abs(delta) > this.stableDeg) {
+      this.stableSince = now;
+      return null;
+    }
+    if (now - this.stableSince >= this.stableMs) {
+      this.refDeg = deg;
+      this.stableSince = now;
+    }
+    return null;
+  }
+  /**
+   * The most recent completed turn, or null if none this session.
+   *
+   * It does NOT expire on its own: the age is derivable from `timestamp`, and
+   * "recent enough to mention" is a product judgement this layer must not make
+   * on the caller's behalf.
+   */
+  last() {
+    return this.lastTurn;
+  }
+  reset() {
+    this.refDeg = null;
+    this.stableSince = 0;
+    this.lastTurn = null;
+  }
+};
+
+// src/device-state/headingSource.ts
+var latest = null;
+var sub = null;
+var opening = null;
+var owners = /* @__PURE__ */ new Set();
+var turns = new TurnDetector();
+var turnListeners = listenerSet();
+function startHeading(owner) {
+  owners.add(owner);
+  if (sub) return Promise.resolve();
+  opening ?? (opening = open().finally(() => {
+    opening = null;
+  }));
+  return opening;
+}
+async function open() {
+  try {
+    const s = await ExpoLocation.watchHeadingAsync((h) => {
+      if (!owners.size) return;
+      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;
+      const now = Date.now();
+      latest = { headingDeg: deg, calibration: cal, timestamp: now };
+      const turn = turns.push(deg, now);
+      if (turn) turnListeners.emit(turn);
+    });
+    if (!owners.size) {
+      s.remove();
+      return;
+    }
+    sub = s;
+  } catch {
+    sub = null;
+  }
+}
+function stopHeading(owner) {
+  owners.delete(owner);
+  if (owners.size) return;
+  sub?.remove();
+  sub = null;
+  latest = null;
+  turns.reset();
+}
+function onTurn(fn) {
+  return turnListeners.add(fn);
+}
+function currentHeading() {
+  return latest ? { headingDeg: latest.headingDeg } : null;
+}
+function currentHeadingDetail() {
+  return latest;
+}
+function lastMeaningfulTurn() {
+  return turns.last();
+}
+
+// src/geo.ts
+function distanceOf(path) {
+  const R = 6371e3;
+  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);
+}
+
+// src/device-state/spatialEvents.ts
+var STATIONARY_MPS = 0.4;
+function movementStateOf(speedMps) {
+  return speedMps === null ? "unknown" : speedMps < STATIONARY_MPS ? "stationary" : "moving";
+}
+function fixConfidence(accuracyM) {
+  return accuracyM === null ? "unknown" : accuracyM <= 10 ? "high" : accuracyM <= 50 ? "medium" : "low";
+}
+var SPATIAL_EVENT_PROFILES = {
+  navigation: { movingHoldMs: 3e3, stoppedHoldMs: 5e3, confidenceHoldMs: 3e3, minMoveM: 10 },
+  fitness: { movingHoldMs: 3e3, stoppedHoldMs: 5e3, confidenceHoldMs: 5e3, minMoveM: 10 },
+  preciseLocate: { movingHoldMs: 2e3, stoppedHoldMs: 3e3, confidenceHoldMs: 2e3, minMoveM: 3 },
+  geofence: { movingHoldMs: 1e4, stoppedHoldMs: 3e4, confidenceHoldMs: 1e4, minMoveM: 25 },
+  lowPowerTracking: { movingHoldMs: 1e4, stoppedHoldMs: 3e4, confidenceHoldMs: 1e4, minMoveM: 50 }
+};
+function moveThresholdM(anchor, fix) {
+  const a = anchor.accuracyM ?? 0, b = fix.accuracyM ?? 0;
+  return 2 * Math.sqrt(a * a + b * b);
+}
+function spatialEventProfile(intent) {
+  return SPATIAL_EVENT_PROFILES[intent] ?? SPATIAL_EVENT_PROFILES.navigation;
+}
+var RANK = { high: 3, medium: 2, low: 1 };
+var MIN_FIXES = 2;
+function extend(run, state, fixAt2, now) {
+  if (!run || run.state !== state) return { state, since: now, fixAt: fixAt2, fixes: fixAt2 === null ? 0 : 1 };
+  if (fixAt2 !== null && fixAt2 !== run.fixAt) {
+    run.fixAt = fixAt2;
+    run.fixes++;
+  }
+  return run;
+}
+var settled = (run, now, holdMs) => run.fixes >= MIN_FIXES && now - run.since >= holdMs;
+var fixAt = (s) => s.position?.timestamp ?? null;
+var SpatialEventDetector = class {
+  constructor(profile = SPATIAL_EVENT_PROFILES.navigation) {
+    /** The movement state last settled on. Only MEASURED states settle. */
+    this.movement = "unknown";
+    this.run = 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. */
+    this.lastTurnAt = null;
+    /** The GPS band last settled on; null until the session's first band. */
+    this.band = null;
+    this.bandRun = 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. */
+    this.anchor = null;
+    this.staleArmed = true;
+    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, turnOnRecordAt = null) {
+    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, now) {
+    const out = [];
+    const emit = (name, payload) => {
+      out.push(stateEvent("spatial", name, payload, now));
+    };
+    this.movementFrom(snapshot, now, emit);
+    this.turnFrom(snapshot, emit);
+    this.positionFrom(snapshot, emit);
+    this.confidenceFrom(snapshot, now, emit);
+    this.staleFrom(snapshot, emit);
+    return out;
+  }
+  movementFrom(s, now, emit) {
+    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";
+    }
+  }
+  turnFrom(s, emit) {
+    const at = s.changes?.timestamp ?? null;
+    const deg = s.changes?.lastMeaningfulTurnDeg ?? null;
+    if (at === null || deg === null || at === this.lastTurnAt) return;
+    this.lastTurnAt = at;
+    emit("lastMeaningfulTurnChanged", { lastMeaningfulTurnDeg: deg, timestamp: at });
+  }
+  positionFrom(s, emit) {
+    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))) {
+      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;
+  }
+  confidenceFrom(s, now, emit) {
+    const p = s.position ?? null;
+    if (!p) return;
+    const level = fixConfidence(p.accuracyM ?? null);
+    if (level === "unknown") return;
+    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;
+  }
+  staleFrom(s, emit) {
+    const f = s.quality?.freshness;
+    if (!f) return;
+    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;
+  }
+};
+
+// src/device-state/domains/spatial.ts
+var WATCH_ACCURACY = {
+  navigation: "navigation",
+  preciseLocate: "high",
+  fitness: "high",
+  geofence: "balanced",
+  lowPowerTracking: "low"
+};
+function createSpatialDomain(collectors, speedRef) {
+  const RECENT_PATH_MAX = 60;
+  let recentPath = [];
+  let latest2 = null;
+  let latestSpeed = null;
+  let latestCourse = null;
+  let stopWatch = null;
+  let session = null;
+  const detector = new SpatialEventDetector();
+  const listeners = listenerSet();
+  let ticker = null;
+  let turnSub = null;
+  const nonNegative = (v) => typeof v === "number" && v >= 0 ? v : null;
+  const derivedSpeed = () => {
+    if (recentPath.length < 2) return null;
+    const b = recentPath[recentPath.length - 1];
+    const a = recentPath[recentPath.length - 2];
+    const dtS = (b.timestamp - a.timestamp) / 1e3;
+    if (dtS <= 0 || dtS > 10) return null;
+    return distanceOf([a, b]) / dtS;
+  };
+  const derivedCourse = () => {
+    if (recentPath.length < 2) return null;
+    const b = recentPath[recentPath.length - 1];
+    const a = recentPath[recentPath.length - 2];
+    if (b.timestamp - a.timestamp > 1e4) return null;
+    if (distanceOf([a, b]) < 3) return null;
+    return bearingBetween(a, b);
+  };
+  const snapshotFrom = (point, measuredSpeed, measuredCourse) => {
+    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)
+      )
+    };
+  };
+  const noFix = () => ({
+    position: null,
+    movement: { speedMps: null, bearingDeg: null, distanceRecentM: null, state: "unknown" },
+    orientation: { headingDeg: currentHeadingDetail()?.headingDeg ?? null },
+    recentPath: [],
+    quality: qualityUnknown()
+  });
+  const warmSnapshot = () => latest2 ? snapshotFrom(latest2, latestSpeed, latestCourse) : null;
+  const observe = () => {
+    const snapshot = warmSnapshot();
+    if (!snapshot) return;
+    for (const event of detector.push(snapshot, Date.now())) listeners.emit(event);
+  };
+  const startTicking = () => {
+    ticker = setInterval(observe, 1e3);
+  };
+  const stopTicking = () => {
+    if (ticker) clearInterval(ticker);
+    ticker = null;
+  };
+  return {
+    async getSnapshot() {
+      const warm = warmSnapshot();
+      if (warm) return warm;
+      if (session) return noFix();
+      let point;
+      let speedMps;
+      let courseDeg;
+      try {
+        if (!collectors.location) throw unsupported("location collector");
+        const fix = 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 {
+        return noFix();
+      }
+      return snapshotFrom(point, speedMps, courseDeg);
+    },
+    /**
+     * Open the warm window: position stream + compass + event feed.
+     *
+     * 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 (session) return { ...session };
+      if (!collectors.location) throw unsupported("location collector");
+      const startedAt = Date.now();
+      session = { id: `spatial_${startedAt}`, intent: options.intent, startedAt };
+      detector.reset(spatialEventProfile(options.intent), lastMeaningfulTurn()?.timestamp ?? null);
+      void startHeading("spatial");
+      turnSub = onTurn(observe);
+      stopWatch = collectors.location.watchPosition((pos) => {
+        const p = {
+          latitude: pos.latitude,
+          longitude: pos.longitude,
+          altitude: pos.altitude ?? null,
+          accuracyM: nonNegative(pos.accuracy),
+          timestamp: pos.timestamp ?? Date.now()
+        };
+        latest2 = p;
+        latestSpeed = nonNegative(pos.speed);
+        latestCourse = nonNegative(pos.course);
+        speedRef.mps = latestSpeed;
+        speedRef.at = p.timestamp;
+        recentPath = [...recentPath, p].slice(-RECENT_PATH_MAX);
+        observe();
+      }, { accuracy: WATCH_ACCURACY[options.intent] ?? "balanced" });
+      startTicking();
+      return { ...session };
+    },
+    async stop() {
+      stopWatch?.();
+      stopWatch = null;
+      session = null;
+      stopTicking();
+      turnSub?.unsubscribe();
+      turnSub = null;
+      detector.reset();
+      recentPath = [];
+      latest2 = null;
+      latestSpeed = null;
+      latestCourse = null;
+      speedRef.mps = null;
+      speedRef.at = 0;
+      stopHeading("spatial");
+    },
+    /**
+     * 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);
+    }
+  };
+}
+function spatialConfidence(accuracyM, calibration, derived) {
+  const rank = (v) => v === "high" ? 3 : v === "medium" ? 2 : v === "low" ? 1 : 0;
+  const fromFix = fixConfidence(accuracyM);
+  const fromCompass = calibration === null ? "unknown" : calibration >= 3 ? "high" : calibration >= 2 ? "medium" : "low";
+  const parts = [fromFix, fromCompass, ...derived ? ["low"] : []];
+  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 };
+}
+function bearingBetween(a, b) {
+  const toRad = (d) => 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;
+}
+
 // src/device-state/visualEngine.ts
 var PROFILES = {
   navigation: { intervalMs: 1e3, windowMs: 5e3 },
@@ -642,300 +1177,26 @@ function frameQuality(frame) {
   };
 }
 
-// src/device-state/headingSource.ts
-var ExpoLocation = __toESM(require("expo-location"));
-
-// src/device-state/turnDetector.ts
-function signedDelta(a, b) {
-  return (b - a + 540) % 360 - 180;
-}
-var TurnDetector = class {
-  constructor(opts = {}) {
-    /** The heading currently treated as "straight ahead". */
-    this.refDeg = null;
-    this.stableSince = 0;
-    this.lastTurn = null;
-    this.minTurnDeg = opts.minTurnDeg ?? 35;
-    this.stableDeg = opts.stableDeg ?? 12;
-    this.stableMs = opts.stableMs ?? 2500;
-  }
-  /** Feed one compass reading. `null` degrees means the compass said nothing. */
-  push(deg, now) {
-    if (deg === null) return null;
-    if (this.refDeg === null) {
-      this.refDeg = deg;
-      this.stableSince = now;
-      return null;
-    }
-    const delta = signedDelta(this.refDeg, deg);
-    if (Math.abs(delta) >= this.minTurnDeg) {
-      this.lastTurn = { deg: Math.round(delta), timestamp: now };
-      this.refDeg = deg;
-      this.stableSince = now;
-      return this.lastTurn;
-    }
-    if (Math.abs(delta) > this.stableDeg) {
-      this.stableSince = now;
-      return null;
-    }
-    if (now - this.stableSince >= this.stableMs) {
-      this.refDeg = deg;
-      this.stableSince = now;
-    }
-    return null;
-  }
-  /**
-   * The most recent completed turn, or null if none this session.
-   *
-   * It does NOT expire on its own: the age is derivable from `timestamp`, and
-   * "recent enough to mention" is a product judgement this layer must not make
-   * on the caller's behalf.
-   */
-  last() {
-    return this.lastTurn;
-  }
-  reset() {
-    this.refDeg = null;
-    this.stableSince = 0;
-    this.lastTurn = null;
-  }
-};
-
-// src/device-state/headingSource.ts
-var latest = null;
-var sub = null;
-var turns = new TurnDetector();
-async function startHeading() {
-  if (sub) return;
-  try {
-    sub = await ExpoLocation.watchHeadingAsync((h) => {
-      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 {
-    sub = null;
-  }
-}
-function stopHeading() {
-  sub?.remove();
-  sub = null;
-  latest = null;
-  turns.reset();
-}
-function currentHeading() {
-  return latest ? { headingDeg: latest.headingDeg } : null;
-}
-function currentHeadingDetail() {
-  return latest;
-}
-function lastMeaningfulTurn() {
-  return turns.last();
-}
-
-// src/device-state/domains/spatial.ts
-function createSpatialDomain(collectors, speedRef) {
-  const RECENT_PATH_MAX = 60;
-  const STATIONARY_MPS = 0.4;
-  let recentPath = [];
-  let latest2 = null;
-  let latestSpeed = null;
-  let latestCourse = null;
-  let stopWatch = null;
-  let sessionId = null;
-  const nonNegative = (v) => typeof v === "number" && v >= 0 ? v : null;
-  const derivedSpeed = () => {
-    if (recentPath.length < 2) return null;
-    const b = recentPath[recentPath.length - 1];
-    const a = recentPath[recentPath.length - 2];
-    const dtS = (b.timestamp - a.timestamp) / 1e3;
-    if (dtS <= 0 || dtS > 10) return null;
-    return distanceOf([a, b]) / dtS;
-  };
-  const derivedCourse = () => {
-    if (recentPath.length < 2) return null;
-    const b = recentPath[recentPath.length - 1];
-    const a = recentPath[recentPath.length - 2];
-    if (b.timestamp - a.timestamp > 1e4) return null;
-    if (distanceOf([a, b]) < 3) return null;
-    return bearingBetween(a, b);
-  };
+// src/device-state/domains/visual.ts
+function cameraState() {
+  const session = visualEngine.getSession();
   return {
-    async getSnapshot() {
-      let point = latest2;
-      let speedMps = latestSpeed;
-      let courseDeg = latestCourse;
-      let derived = false;
-      if (!point) {
-        try {
-          if (!collectors.location) throw unsupported("location collector");
-          const fix = 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 {
-          return {
-            position: null,
-            movement: { speedMps: null, bearingDeg: null, distanceRecentM: null, state: "unknown" },
-            orientation: { headingDeg: null },
-            recentPath: [],
-            quality: qualityUnknown()
-          };
-        }
-      }
-      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() };
-      sessionId = `spatial_${Date.now()}`;
-      if (!collectors.location) throw unsupported("location collector");
-      void startHeading();
-      stopWatch = collectors.location.watchPosition((pos) => {
-        const p = {
-          latitude: pos.latitude,
-          longitude: pos.longitude,
-          altitude: pos.altitude ?? null,
-          accuracyM: nonNegative(pos.accuracy),
-          timestamp: pos.timestamp ?? Date.now()
-        };
-        latest2 = 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() };
-    },
-    async stop() {
-      stopWatch?.();
-      stopWatch = null;
-      sessionId = null;
-      recentPath = [];
-      latest2 = null;
-      latestSpeed = null;
-      latestCourse = null;
-      speedRef.mps = null;
-      speedRef.at = 0;
-      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");
-    }
+    // `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"
   };
 }
-function spatialConfidence(accuracyM, calibration, derived) {
-  const rank = (v) => v === "high" ? 3 : v === "medium" ? 2 : v === "low" ? 1 : 0;
-  const fromFix = accuracyM === null ? "unknown" : accuracyM <= 10 ? "high" : accuracyM <= 50 ? "medium" : "low";
-  const fromCompass = calibration === null ? "unknown" : calibration >= 3 ? "high" : calibration >= 2 ? "medium" : "low";
-  const parts = [fromFix, fromCompass, ...derived ? ["low"] : []];
-  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 };
-}
-function bearingBetween(a, b) {
-  const toRad = (d) => 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;
-}
-function distanceOf(path) {
-  const R = 6371e3;
-  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);
-}
-
-// src/device-state/domains/visual.ts
 function createVisualDomain() {
   return {
     async getSnapshot() {
-      const session = visualEngine.getSession();
       const latest2 = 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: latest2,
@@ -946,13 +1207,13 @@ function createVisualDomain() {
     async start(options) {
       const s = visualEngine.startSession(options?.intent || "navigation");
       visualEngine.setContextProvider({ heading: currentHeading });
-      void startHeading();
+      void startHeading("visual");
       return { id: s.id, intent: s.intent, startedAt: s.startedAt };
     },
     async stop() {
       visualEngine.stopSession();
       visualEngine.setContextProvider(null);
-      stopHeading();
+      stopHeading("visual");
     },
     /**
      * A deliberate one-shot. Distinct from getSnapshot because it is an
@@ -983,9 +1244,20 @@ function createVisualDomain() {
       err.code = "TIMEOUT";
       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" });
+        const camera = cameraState();
+        const key = JSON.stringify(camera);
+        if (key === last) return;
+        last = key;
+        listener(stateEvent("visual", "visualStateChanged", { camera }));
       });
       return { unsubscribe: off };
     }
@@ -1545,11 +1817,30 @@ function createReplayDeviceState(fixture) {
   const refusals = new Map((fixture.refusals || []).map((r) => [r.domain, r]));
   const openSessions = /* @__PURE__ */ new Set();
   let cursor = 0;
+  const spatialDetector = new SpatialEventDetector();
+  const spatialListeners = listenerSet();
+  const moveTo = (target) => {
+    const next = Math.min(duration, Math.max(0, target));
+    if (!openSessions.has("spatial")) return cursor = next;
+    if (next < cursor) {
+      cursor = next;
+      spatialDetector.reset(void 0, 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 = {
     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
   };
   const sampleAt = () => {
@@ -1560,22 +1851,28 @@ function createReplayDeviceState(fixture) {
     }
     return found;
   };
+  const turnOnRecordAt = () => sampleAt()?.spatial?.changes?.timestamp ?? null;
   const domainFor = (name) => ({
     async getSnapshot() {
       const s = sampleAt();
       const recorded = s ? s[name] : void 0;
       return recorded ?? unknownSnapshot(name);
     },
-    async start() {
+    async start(options) {
       const r = refusals.get(name);
       if (r) throw refusal(name, r.code, r.message);
+      if (name === "spatial" && !openSessions.has(name)) {
+        spatialDetector.reset(spatialEventProfile(options?.intent), turnOnRecordAt());
+      }
       openSessions.add(name);
       return { id: `replay_${name}`, intent: "replay", startedAt: 0 };
     },
     async stop() {
       openSessions.delete(name);
+      if (name === "spatial") spatialDetector.reset();
     },
-    subscribe() {
+    subscribe(listener) {
+      if (name === "spatial") return spatialListeners.add(listener);
       throw refusal(name, "UNSUPPORTED", `deviceState.${name}.subscribe is not replayable \u2014 advance the clock and read.`);
     }
   });