@colixsystems/widget-sdk 0.118.0 → 0.119.0

package/README.md

@@ -35,7 +35,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useRefresh(handler)` | `void` | `ctx.refresh.subscribe` — no scope. Subscribes the handler to the page-level refresh tick (pull-to-refresh on mobile). Handler may return a Promise — the host waits for `allSettled` before clearing the spinner. The three datastore hooks auto-subscribe their own `refetch`; widgets only call this directly to re-run non-datastore work. No-op on a host that doesn't implement refresh. |
 | **CORE** | `useClipboard()` | `{ copy, paste, hasContent }` | platform clipboard (web `navigator.clipboard` / native `expo-clipboard`); rejects with `ClipboardError` — no scope |
 | **CORE** | `useToast()` | `{ showToast }` | `ctx.toast.showToast` — wired by the Player and the Expo export; an authoring preview omits it and the call is a no-op — no scope |
-| **CORE** | `useGeolocation(options?)` | `{ latitude, longitude, accuracy, loading, error, getCurrentPosition }` | `ctx.device.geolocation` — no scope. Capture is IMPERATIVE: call `getCurrentPosition()` from a user gesture (a tap), never on mount. Resolves to `{ latitude, longitude, accuracy }`; rejects with `GeolocationError` (`.code` in `PERMISSION_DENIED \| UNAVAILABLE \| TIMEOUT \| UNSUPPORTED \| INTERNAL`). Identical on web (`navigator.geolocation`) and the Expo export (`expo-location`). |
+| **CORE** | `useGeolocation(options?)` | `{ latitude, longitude, accuracy, loading, error, getCurrentPosition, backgroundSupported, backgroundWatching, startBackgroundWatch, stopBackgroundWatch }` | `ctx.device.geolocation` — no scope. Capture is IMPERATIVE: call `getCurrentPosition()` from a user gesture (a tap), never on mount. Resolves to `{ latitude, longitude, accuracy }`; rejects with `GeolocationError` (`.code` in `PERMISSION_DENIED \| UNAVAILABLE \| TIMEOUT \| UNSUPPORTED \| INTERNAL`). Identical on web (`navigator.geolocation`) and the Expo export (`expo-location`). **Background watch (sc-6450)** — `startBackgroundWatch({ enableHighAccuracy, distanceIntervalMeters, timeIntervalMs })` keeps positions arriving while the app is backgrounded; `stopBackgroundWatch()` releases it. NATIVE-ONLY and opt-in per app: gate the control on `backgroundSupported` (false on web, and in an export whose workspace did not opt in). The watch outlives the widget's mount, and its positions land in the same `latitude`/`longitude`/`accuracy` slots. |
 | **CORE** | `useSpeechToText(options?)` | `{ transcript, partial, listening, supported, error, start, stop, abort, reset }` | `ctx.device.speech` — no scope. Dictation with the device's **on-device** recogniser: no audio is uploaded and no AI credit is spent. Capture is IMPERATIVE: call `start()` from a user gesture (a tap), never on mount. `transcript` accumulates finalised speech, `partial` holds the uncommitted guess (needs `options.interimResults`); `stop()` keeps it, `abort()` discards it. Rejects with `SpeechToTextError` (`.code` in `PERMISSION_DENIED \| NO_SPEECH \| LANGUAGE_UNSUPPORTED \| NETWORK \| ABORTED \| UNSUPPORTED \| INTERNAL`). **Gate your mic button on `supported`** — Firefox ships no `SpeechRecognition`. Identical on web (`SpeechRecognition`) and the Expo export (`expo-speech-recognition`). |
 | **CORE** | `useCamera(options?)` | `{ asset, loading, error, supported, capture, pick, reset }` | `ctx.device.camera` — no scope. Take a photo (`capture()`) or choose one (`pick()`). Capture is IMPERATIVE: call from a user gesture (a tap), never on mount. Both resolve a normalised `{ uri, name, mimeType, width, height, size, file }`, or **`null` when the user dismisses the picker** — dismissal is not an error, so no `try/catch` is needed on the happy path. Rejects with `CameraError` (`.code` in `PERMISSION_DENIED \| UNSUPPORTED \| INTERNAL`). `asset.file` is already the right upload part for the host, so `fd.append("file", asset.file)` → `ctx.assets.upload(fd)` is ONE code path on both. **Gate your camera button on `supported`.** Identical on web (file input) and the Expo export (`expo-image-picker`). |
 | **CORE** | `useI18n()` | `{ t, locale }` | `ctx.i18n` — no scope. `t(key)` resolves the widget-namespaced key (`widget.<id>.<key>`, declared in `manifest.translations`) first, then a **predefined shared key** (`shared.<key>`) when `key` is one of the standard strings (`submit`, `cancel`, `save`, `loading`, …), then the raw key. Use a shared key for an identical default string so it translates once and any per-instance `widget.<id>.<key>` override still wins. |
@@ -70,8 +70,41 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.118.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.119.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
 
+### What's new in 0.119.0 (contract 1.91.0)
+
+**`useGeolocation()` can now track location while the app is BACKGROUNDED (sc-6450).** The hook only ever read a position while the app was in the foreground, so the whole class of field-work apps — delivery tracking, site visits, mileage and timesheet logging — could not be built. Its result gains four members; the existing foreground API is untouched:
+
+| Member | Shape | Notes |
+| --- | --- | --- |
+| `backgroundSupported` | `boolean` | **Check this before rendering the control.** |
+| `backgroundWatching` | `boolean` | Whether a watch is running on this device. |
+| `startBackgroundWatch` | `(options?) => Promise<void>` | `options`: `{ enableHighAccuracy, distanceIntervalMeters, timeIntervalMs }`. |
+| `stopBackgroundWatch` | `() => Promise<void>` | Releases the OS subscription. |
+
+```jsx
+const { latitude, longitude, backgroundSupported, backgroundWatching, startBackgroundWatch, stopBackgroundWatch } = useGeolocation();
+
+{backgroundSupported && (
+  <Button
+    label={backgroundWatching ? "Stop trip" : "Start trip"}
+    onPress={() => (backgroundWatching ? stopBackgroundWatch() : startBackgroundWatch({ distanceIntervalMeters: 50 }))}
+  />
+)}
+```
+
+The watch is **native-only and opt-in per app**. `backgroundSupported` is `false` on the web Player — a browser tab genuinely cannot track in the background, the same capability-gated honesty `useSpeechToText` applies on Firefox — and it is also `false` in an exported app whose workspace has not enabled background location in **Publishing Settings**. That opt-in exists so an app that never uses the capability declares no background mode and stays clear of the extra store review.
+
+Three behaviours to design around. Tracking covers the app **running in the background**; it does not survive the OS terminating the app, so don't promise an unattended log. The watch **outlives the widget's mount** — that is the point — so it is released only by `stopBackgroundWatch()`, never on unmount; `backgroundWatching` is seeded from the host so a remounted widget reports a running watch honestly. And background positions land in the **same** `latitude` / `longitude` / `accuracy` slots as the foreground read, so a widget renders one position regardless of how it arrived.
+
+`startBackgroundWatch()` rejects with the existing `GeolocationError`: `.code` `UNSUPPORTED` when the host or build does not offer the capability, `PERMISSION_DENIED` when the user refuses always-on location. On Android 11+ the always-on grant cannot be made from a runtime dialog — the user has to pick "Allow all the time" in system Settings — so treat `PERMISSION_DENIED` as a prompt to explain that, not as a dead end.
+
+`backgroundWatching` is a mirror of the host, not of your calls: the OS can end the watch on its own (a permission downgrade, a killed foreground service) and a sibling widget can start or stop it, so render from the flag rather than from whether you called `start`.
+
+**Store review:** Apple and Google both require a *visible user benefit* plus a justification for background location. Your app must show the user that tracking is running and let them stop it, and your store listing must explain why the app needs it. A build that turns the opt-in on without that is rejected at review.
+
+`CONTRACT.version` → `1.91.0`. Additive — four new result members and six new optional `ctx.device.geolocation` broker members; no existing export changed signature.
 ### What's new in 0.118.0 (contract 1.90.0)
 
 **A `styleSchema` field's `default` now actually applies.** Declaring `default` on a style field wrote it into the manifest and nothing ever read it back, so a widget's own styling baseline — and any design saved from the Widget Builder preview — was silently dropped on the next render. The host now resolves it onto `props.style`.

package/dist/contract.cjs

@@ -1570,7 +1570,17 @@ const HOOKS = [
       "permission prompt on a gesture, so it NEVER fires on mount. The promise resolves to { latitude, longitude, accuracy } " +
       "and stores the same values on the hook; it rejects with a GeolocationError whose .code is one of PERMISSION_DENIED | " +
       "UNAVAILABLE | TIMEOUT | UNSUPPORTED | INTERNAL. options pass through to the host ({ enableHighAccuracy, timeout, " +
-      "maximumAge }). Identical on web (navigator.geolocation) and the Expo export (expo-location).",
+      "maximumAge }). Identical on web (navigator.geolocation) and the Expo export (expo-location). " +
+      "BACKGROUND WATCH (sc-6450): startBackgroundWatch(options?) keeps positions arriving while the app is BACKGROUNDED — the " +
+      "field-work case (delivery tracking, site visits, mileage logging) — and stopBackgroundWatch() releases the OS " +
+      "subscription. It is NATIVE-ONLY and opt-in per app: ALWAYS check `backgroundSupported` before rendering the control, " +
+      "because the web Player reports false (a browser tab cannot track in the background) and so does an exported app whose " +
+      "workspace has not enabled background location in Publishing Settings. The watch OUTLIVES the widget mount by design, so " +
+      "it stops ONLY on stopBackgroundWatch(); `backgroundWatching` is seeded from the host so a remounted widget reports it " +
+      "honestly. Background positions land in the SAME latitude/longitude/accuracy slots. startBackgroundWatch rejects with a " +
+      "GeolocationError (.code UNSUPPORTED when the host or build does not offer it, PERMISSION_DENIED when the user refuses " +
+      "always-on location). options: { enableHighAccuracy, distanceIntervalMeters, timeIntervalMs }. Tracking continues while the " +
+      "app is running in the BACKGROUND; it does not survive the OS terminating the app, so do not promise an unattended log.",
     returnShape: {
       latitude: "number | null",
       longitude: "number | null",
@@ -1579,6 +1589,13 @@ const HOOKS = [
       error: "GeolocationError | null",
       getCurrentPosition:
         "() => Promise<{ latitude, longitude, accuracy }>  // rejects with GeolocationError",
+      backgroundSupported:
+        "boolean  // GATE THE CONTROL ON THIS: false on the web Player and in an export that did not opt in",
+      backgroundWatching: "boolean  // a background watch is running on this device",
+      startBackgroundWatch:
+        "(options?) => Promise<void>  // NATIVE-ONLY; { enableHighAccuracy, distanceIntervalMeters, timeIntervalMs }; rejects with GeolocationError",
+      stopBackgroundWatch:
+        "() => Promise<void>  // the ONLY release - the watch outlives the widget's mount",
     },
     requiredContextSlice: [],
     scopes: null,
@@ -2259,7 +2276,10 @@ const WIDGET_CONTEXT_SHAPE = {
   device: {
     description:
       "Optional host-brokered device capabilities. " +
-      "{ geolocation: { getCurrentPosition(options?) -> Promise<{ latitude, longitude, accuracy }> }, " +
+      "{ geolocation: { getCurrentPosition(options?) -> Promise<{ latitude, longitude, accuracy }>, " +
+      "isBackgroundSupported() -> boolean, startBackgroundWatch(options?) -> Promise<void>, stopBackgroundWatch() -> Promise<void>, " +
+      "isBackgroundWatching() -> boolean, subscribeBackgroundPositions(cb) -> unsubscribe, " +
+      "subscribeBackgroundWatchState(cb) -> unsubscribe }, " +
       "speech: { isSupported() -> boolean, start(options, { onResult, onError, onEnd }) -> Promise<{ stop(), abort() }> }, " +
       "camera: { isSupported() -> boolean, capture(options?) -> Promise<asset | null>, pick(options?) -> Promise<asset | null> } }. " +
       "Backs useGeolocation(), useSpeechToText() and useCamera(). The web Player brokers them via navigator.geolocation, " +
@@ -2269,7 +2289,14 @@ const WIDGET_CONTEXT_SHAPE = {
       "speech.start streams { transcript, isFinal } to onResult and runs ON DEVICE — it uploads no audio and spends no AI credit; " +
       "its onError carries the Web Speech error vocabulary (not-allowed | no-speech | language-not-supported | network | aborted). " +
       "camera.capture/pick resolve a normalised { uri, name, mimeType, width, height, size, file, release? } or NULL when the " +
-      "user dismisses the picker, and reject with a CameraError (.code PERMISSION_DENIED | UNSUPPORTED | INTERNAL).",
+      "user dismisses the picker, and reject with a CameraError (.code PERMISSION_DENIED | UNSUPPORTED | INTERNAL). " +
+      "sc-6450 — the geolocation background-watch members are NATIVE-ONLY and opt-in per app: the web Player and an export that " +
+      "did not opt in both report isBackgroundSupported() false, and the Expo export backs it with expo-location + " +
+      "expo-task-manager. subscribeBackgroundPositions and subscribeBackgroundWatchState are plain subscriptions — they start no " +
+      "sensor and prompt for nothing, so the watch can outlive any one widget mount. The HOST owns whether a watch is running: " +
+      "it is primed asynchronously after a cold relaunch, the OS can end it on its own (a permission downgrade, a killed " +
+      "foreground service), and a sibling widget may start or stop it — so subscribeBackgroundWatchState is how every mounted " +
+      "widget stays truthful, and isBackgroundWatching() is only the synchronous first read.",
     required: false,
     fields: { geolocation: "object", speech: "object", camera: "object" },
   },
@@ -3527,7 +3554,21 @@ const CONTRACT = deepFreeze({
   // theme still outranks a widget's own baseline and a field the author never
   // defaulted follows the theme exactly as before. The host still never
   // applies style to elements — the widget owns placement.
-  version: "1.90.0",
+  // 1.91.0: additive (sc-6450) — the geolocation BACKGROUND watch:
+  // `useGeolocation()` gains backgroundSupported / backgroundWatching /
+  // startBackgroundWatch / stopBackgroundWatch, and the optional
+  // `device.geolocation` broker gains isBackgroundSupported,
+  // startBackgroundWatch, stopBackgroundWatch, isBackgroundWatching,
+  // subscribeBackgroundPositions and subscribeBackgroundWatchState. Field-work
+  // apps — delivery tracking, site visits, mileage — could not be built at all
+  // while a position could only be read in the foreground. Native-only and
+  // opt-in per app: the web Player reports backgroundSupported false because a
+  // tab is suspended once backgrounded, and so does an export whose workspace
+  // did not opt in. The HOST owns whether a watch is running (it is primed
+  // asynchronously after an OS relaunch, the OS can end it, and a sibling
+  // widget can start or stop it), so subscribeBackgroundWatchState is how every
+  // mounted widget stays truthful.
+  version: "1.91.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1570,7 +1570,17 @@ const HOOKS = [
       "permission prompt on a gesture, so it NEVER fires on mount. The promise resolves to { latitude, longitude, accuracy } " +
       "and stores the same values on the hook; it rejects with a GeolocationError whose .code is one of PERMISSION_DENIED | " +
       "UNAVAILABLE | TIMEOUT | UNSUPPORTED | INTERNAL. options pass through to the host ({ enableHighAccuracy, timeout, " +
-      "maximumAge }). Identical on web (navigator.geolocation) and the Expo export (expo-location).",
+      "maximumAge }). Identical on web (navigator.geolocation) and the Expo export (expo-location). " +
+      "BACKGROUND WATCH (sc-6450): startBackgroundWatch(options?) keeps positions arriving while the app is BACKGROUNDED — the " +
+      "field-work case (delivery tracking, site visits, mileage logging) — and stopBackgroundWatch() releases the OS " +
+      "subscription. It is NATIVE-ONLY and opt-in per app: ALWAYS check `backgroundSupported` before rendering the control, " +
+      "because the web Player reports false (a browser tab cannot track in the background) and so does an exported app whose " +
+      "workspace has not enabled background location in Publishing Settings. The watch OUTLIVES the widget mount by design, so " +
+      "it stops ONLY on stopBackgroundWatch(); `backgroundWatching` is seeded from the host so a remounted widget reports it " +
+      "honestly. Background positions land in the SAME latitude/longitude/accuracy slots. startBackgroundWatch rejects with a " +
+      "GeolocationError (.code UNSUPPORTED when the host or build does not offer it, PERMISSION_DENIED when the user refuses " +
+      "always-on location). options: { enableHighAccuracy, distanceIntervalMeters, timeIntervalMs }. Tracking continues while the " +
+      "app is running in the BACKGROUND; it does not survive the OS terminating the app, so do not promise an unattended log.",
     returnShape: {
       latitude: "number | null",
       longitude: "number | null",
@@ -1579,6 +1589,13 @@ const HOOKS = [
       error: "GeolocationError | null",
       getCurrentPosition:
         "() => Promise<{ latitude, longitude, accuracy }>  // rejects with GeolocationError",
+      backgroundSupported:
+        "boolean  // GATE THE CONTROL ON THIS: false on the web Player and in an export that did not opt in",
+      backgroundWatching: "boolean  // a background watch is running on this device",
+      startBackgroundWatch:
+        "(options?) => Promise<void>  // NATIVE-ONLY; { enableHighAccuracy, distanceIntervalMeters, timeIntervalMs }; rejects with GeolocationError",
+      stopBackgroundWatch:
+        "() => Promise<void>  // the ONLY release - the watch outlives the widget's mount",
     },
     requiredContextSlice: [],
     scopes: null,
@@ -2259,7 +2276,10 @@ const WIDGET_CONTEXT_SHAPE = {
   device: {
     description:
       "Optional host-brokered device capabilities. " +
-      "{ geolocation: { getCurrentPosition(options?) -> Promise<{ latitude, longitude, accuracy }> }, " +
+      "{ geolocation: { getCurrentPosition(options?) -> Promise<{ latitude, longitude, accuracy }>, " +
+      "isBackgroundSupported() -> boolean, startBackgroundWatch(options?) -> Promise<void>, stopBackgroundWatch() -> Promise<void>, " +
+      "isBackgroundWatching() -> boolean, subscribeBackgroundPositions(cb) -> unsubscribe, " +
+      "subscribeBackgroundWatchState(cb) -> unsubscribe }, " +
       "speech: { isSupported() -> boolean, start(options, { onResult, onError, onEnd }) -> Promise<{ stop(), abort() }> }, " +
       "camera: { isSupported() -> boolean, capture(options?) -> Promise<asset | null>, pick(options?) -> Promise<asset | null> } }. " +
       "Backs useGeolocation(), useSpeechToText() and useCamera(). The web Player brokers them via navigator.geolocation, " +
@@ -2269,7 +2289,14 @@ const WIDGET_CONTEXT_SHAPE = {
       "speech.start streams { transcript, isFinal } to onResult and runs ON DEVICE — it uploads no audio and spends no AI credit; " +
       "its onError carries the Web Speech error vocabulary (not-allowed | no-speech | language-not-supported | network | aborted). " +
       "camera.capture/pick resolve a normalised { uri, name, mimeType, width, height, size, file, release? } or NULL when the " +
-      "user dismisses the picker, and reject with a CameraError (.code PERMISSION_DENIED | UNSUPPORTED | INTERNAL).",
+      "user dismisses the picker, and reject with a CameraError (.code PERMISSION_DENIED | UNSUPPORTED | INTERNAL). " +
+      "sc-6450 — the geolocation background-watch members are NATIVE-ONLY and opt-in per app: the web Player and an export that " +
+      "did not opt in both report isBackgroundSupported() false, and the Expo export backs it with expo-location + " +
+      "expo-task-manager. subscribeBackgroundPositions and subscribeBackgroundWatchState are plain subscriptions — they start no " +
+      "sensor and prompt for nothing, so the watch can outlive any one widget mount. The HOST owns whether a watch is running: " +
+      "it is primed asynchronously after a cold relaunch, the OS can end it on its own (a permission downgrade, a killed " +
+      "foreground service), and a sibling widget may start or stop it — so subscribeBackgroundWatchState is how every mounted " +
+      "widget stays truthful, and isBackgroundWatching() is only the synchronous first read.",
     required: false,
     fields: { geolocation: "object", speech: "object", camera: "object" },
   },
@@ -3527,7 +3554,21 @@ const CONTRACT = deepFreeze({
   // theme still outranks a widget's own baseline and a field the author never
   // defaulted follows the theme exactly as before. The host still never
   // applies style to elements — the widget owns placement.
-  version: "1.90.0",
+  // 1.91.0: additive (sc-6450) — the geolocation BACKGROUND watch:
+  // `useGeolocation()` gains backgroundSupported / backgroundWatching /
+  // startBackgroundWatch / stopBackgroundWatch, and the optional
+  // `device.geolocation` broker gains isBackgroundSupported,
+  // startBackgroundWatch, stopBackgroundWatch, isBackgroundWatching,
+  // subscribeBackgroundPositions and subscribeBackgroundWatchState. Field-work
+  // apps — delivery tracking, site visits, mileage — could not be built at all
+  // while a position could only be read in the foreground. Native-only and
+  // opt-in per app: the web Player reports backgroundSupported false because a
+  // tab is suspended once backgrounded, and so does an export whose workspace
+  // did not opt in. The HOST owns whether a watch is running (it is primed
+  // asynchronously after an OS relaunch, the OS can end it, and a sibling
+  // widget can start or stop it), so subscribeBackgroundWatchState is how every
+  // mounted widget stays truthful.
+  version: "1.91.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -987,9 +987,55 @@ function toGeolocationError(err) {
   return new GeolocationError(code, message, { cause: err });
 }
 
+/** Normalise a host position onto the hook's three numeric slots. */
+function normalizeGeolocationPosition(pos) {
+  return {
+    latitude: pos && typeof pos.latitude === "number" ? pos.latitude : null,
+    longitude: pos && typeof pos.longitude === "number" ? pos.longitude : null,
+    accuracy: pos && typeof pos.accuracy === "number" ? pos.accuracy : null,
+  };
+}
+
+/**
+ * Ask the host whether a background watch is running. The watch outlives the
+ * widget's mount, so the host — not the hook — owns this truth.
+ */
+function readBackgroundWatching(client) {
+  if (!client || typeof client.isBackgroundWatching !== "function") return false;
+  try {
+    return Boolean(client.isBackgroundWatching());
+  } catch {
+    return false;
+  }
+}
+
+/** Whether this host offers the background watch. Never throws at render. */
+function readBackgroundSupported(client) {
+  if (!client || typeof client.startBackgroundWatch !== "function") return false;
+  if (typeof client.isBackgroundSupported !== "function") return true;
+  try {
+    return Boolean(client.isBackgroundSupported());
+  } catch {
+    return false;
+  }
+}
+
+/** Subscribe defensively; a host that throws simply yields no subscription. */
+function safeSubscribe(client, method, handler) {
+  if (!client || typeof client[method] !== "function") return null;
+  try {
+    const unsubscribe = client[method](handler);
+    return typeof unsubscribe === "function" ? unsubscribe : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Read the device's current position. Returns
- *   `{ latitude, longitude, accuracy, loading, error, getCurrentPosition }`.
+ *   `{ latitude, longitude, accuracy, loading, error, getCurrentPosition,
+ *     backgroundSupported, backgroundWatching, startBackgroundWatch,
+ *     stopBackgroundWatch }`.
  *
  * Capture is IMPERATIVE — call `getCurrentPosition()` from a user gesture (a
  * tap on a button). Browsers and the mobile OS gate the permission prompt on a
@@ -1004,6 +1050,21 @@ function toGeolocationError(err) {
  * Safe-by-default: on a host that does not inject `ctx.device.geolocation`,
  * `getCurrentPosition()` rejects with `code: "UNSUPPORTED"` rather than
  * throwing at render, so a widget can call the hook unconditionally.
+ *
+ * BACKGROUND WATCH (sc-6450) — `startBackgroundWatch(options?)` keeps positions
+ * arriving while the app is BACKGROUNDED, which is what field-work apps
+ * (delivery tracking, site visits, mileage logging) need. It is capability-
+ * gated: check `backgroundSupported` before offering the control. The web
+ * Player reports false — a browser tab cannot track in the background — and so
+ * does an exported app whose workspace has not opted into background location
+ * in Publishing Settings, because a build that never uses it must declare no
+ * background mode and stay clear of the extra store review.
+ *
+ * The watch OUTLIVES the widget's mount by design, so it is released only by
+ * `stopBackgroundWatch()`, never on unmount; `backgroundWatching` is seeded
+ * from the host so a remounted widget reports a running watch honestly.
+ * Delivered positions land in the SAME `latitude` / `longitude` / `accuracy`
+ * slots as the foreground read.
  */
 export function useGeolocation(options) {
   const ctx = useWidgetContextOrThrow("useGeolocation");
@@ -1019,6 +1080,45 @@ export function useGeolocation(options) {
   optionsRef.current = options;
   const runRef = useRef(0);
 
+  const client = ctx.device && ctx.device.geolocation;
+  const backgroundSupported = readBackgroundSupported(client);
+  const [backgroundWatching, setBackgroundWatching] = useState(() =>
+    readBackgroundWatching(client),
+  );
+
+  // Attach to the host's two background channels on MOUNT rather than inside
+  // startBackgroundWatch: the watch survives unmount, so a remounted widget
+  // must still receive its positions. Subscribing prompts for nothing and
+  // starts no sensor — only startBackgroundWatch() does, from a user gesture.
+  //
+  // The host is the SINGLE source of `backgroundWatching`: the OS can end the
+  // watch on its own (a permission downgrade, a killed service), the answer is
+  // primed asynchronously after a cold relaunch, and a sibling widget may start
+  // or stop it — none of which this hook could observe on its own. Keyed on the
+  // client so a host that injects the slice late still gets wired up.
+  useEffect(() => {
+    if (!client) return undefined;
+    setBackgroundWatching(readBackgroundWatching(client));
+    const unsubscribers = [
+      safeSubscribe(client, "subscribeBackgroundPositions", (pos) => {
+        setCoords(normalizeGeolocationPosition(pos));
+      }),
+      safeSubscribe(client, "subscribeBackgroundWatchState", (watching) => {
+        setBackgroundWatching(Boolean(watching));
+      }),
+    ];
+    return () => {
+      for (const unsubscribe of unsubscribers) {
+        if (!unsubscribe) continue;
+        try {
+          unsubscribe();
+        } catch {
+          /* the host already tore the subscription down */
+        }
+      }
+    };
+  }, [client]);
+
   const getCurrentPosition = useCallback(async () => {
     const myRun = ++runRef.current;
     const client = clientRef.current;
@@ -1037,14 +1137,7 @@ export function useGeolocation(options) {
     setError(null);
     try {
       const pos = await client.getCurrentPosition(optionsRef.current);
-      const next = {
-        latitude:
-          pos && typeof pos.latitude === "number" ? pos.latitude : null,
-        longitude:
-          pos && typeof pos.longitude === "number" ? pos.longitude : null,
-        accuracy:
-          pos && typeof pos.accuracy === "number" ? pos.accuracy : null,
-      };
+      const next = normalizeGeolocationPosition(pos);
       if (runRef.current !== myRun) return next;
       setCoords(next);
       setLoading(false);
@@ -1059,6 +1152,48 @@ export function useGeolocation(options) {
     }
   }, []);
 
+  const startBackgroundWatch = useCallback(async (watchOptions) => {
+    const client = clientRef.current;
+    if (!client || typeof client.startBackgroundWatch !== "function") {
+      const e = new GeolocationError(
+        "UNSUPPORTED",
+        "This host does not track location in the background.",
+      );
+      setError(e);
+      throw e;
+    }
+    setError(null);
+    try {
+      await client.startBackgroundWatch(watchOptions);
+    } catch (err) {
+      const ge = toGeolocationError(err);
+      setError(ge);
+      throw ge;
+    } finally {
+      // Re-read rather than assume: the host knows whether the OS actually
+      // took the subscription, and a failed start may still leave one.
+      setBackgroundWatching(readBackgroundWatching(client));
+    }
+  }, []);
+
+  const stopBackgroundWatch = useCallback(async () => {
+    const client = clientRef.current;
+    if (!client || typeof client.stopBackgroundWatch !== "function") {
+      setBackgroundWatching(false);
+      return;
+    }
+    try {
+      await client.stopBackgroundWatch();
+    } catch (err) {
+      const ge = toGeolocationError(err);
+      setError(ge);
+      throw ge;
+    } finally {
+      // A REFUSED stop leaves the watch running; only the host knows.
+      setBackgroundWatching(readBackgroundWatching(client));
+    }
+  }, []);
+
   return {
     latitude: coords ? coords.latitude : null,
     longitude: coords ? coords.longitude : null,
@@ -1066,6 +1201,10 @@ export function useGeolocation(options) {
     loading,
     error,
     getCurrentPosition,
+    backgroundSupported,
+    backgroundWatching,
+    startBackgroundWatch,
+    stopBackgroundWatch,
   };
 }
 

package/dist/index.d.ts

@@ -645,6 +645,29 @@ export interface WidgetContext<TProps = unknown> {
         longitude: number;
         accuracy: number;
       }>;
+      /** sc-6450 — false on web and on an export that did not opt in. */
+      isBackgroundSupported?(): boolean;
+      startBackgroundWatch?(
+        options?: BackgroundLocationOptions,
+      ): Promise<void>;
+      stopBackgroundWatch?(): Promise<void>;
+      isBackgroundWatching?(): boolean;
+      /** Attach to the running watch; starts no sensor and prompts for nothing. */
+      subscribeBackgroundPositions?(
+        onPosition: (pos: {
+          latitude: number;
+          longitude: number;
+          accuracy: number;
+        }) => void,
+      ): () => void;
+      /**
+       * sc-6450 — the host pushes whether a watch is running: it is primed
+       * asynchronously after a cold relaunch, the OS can end it on its own, and
+       * a sibling widget may start or stop it.
+       */
+      subscribeBackgroundWatchState?(
+        onChange: (watching: boolean) => void,
+      ): () => void;
     };
   };
 }
@@ -1429,6 +1452,15 @@ export interface GeolocationOptions {
   maximumAge?: number;
 }
 
+/** sc-6450 — pass-through options for `startBackgroundWatch(...)`. */
+export interface BackgroundLocationOptions {
+  enableHighAccuracy?: boolean;
+  /** Report only after the device has moved this far, in metres. */
+  distanceIntervalMeters?: number;
+  /** Report no more often than this, in milliseconds. */
+  timeIntervalMs?: number;
+}
+
 export interface GeolocationResult {
   latitude: number | null;
   longitude: number | null;
@@ -1446,6 +1478,26 @@ export interface GeolocationResult {
     longitude: number;
     accuracy: number;
   }>;
+  /**
+   * sc-6450 — whether this host can track location while BACKGROUNDED. False
+   * on the web Player and on an exported app whose workspace did not opt into
+   * background location. Check it before rendering the control.
+   */
+  backgroundSupported: boolean;
+  /** Whether a background watch is currently running on this device. */
+  backgroundWatching: boolean;
+  /**
+   * Start tracking while backgrounded — call from a user gesture. The watch
+   * OUTLIVES the widget's mount; only `stopBackgroundWatch()` releases it.
+   * Delivered positions land in the same `latitude`/`longitude`/`accuracy`
+   * slots. Rejects with a `GeolocationError`.
+   *
+   * Tracking continues while the app RUNS in the background; it does not
+   * survive the OS terminating the app.
+   */
+  startBackgroundWatch(options?: BackgroundLocationOptions): Promise<void>;
+  /** Release the OS subscription. */
+  stopBackgroundWatch(): Promise<void>;
 }
 
 /**
@@ -1455,6 +1507,9 @@ export interface GeolocationResult {
  * `navigator.geolocation`, the Expo export via `expo-location`. Safe to call on
  * a host that doesn't broker geolocation: `getCurrentPosition()` then rejects
  * with `code: "UNSUPPORTED"`.
+ *
+ * sc-6450 — the same hook also drives the native-only background watch; see
+ * `backgroundSupported` / `startBackgroundWatch` on the result.
  */
 export function useGeolocation(options?: GeolocationOptions): GeolocationResult;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.118.0",
+  "version": "0.119.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",