@colixsystems/widget-sdk 0.117.0 → 0.119.0

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/host.d.ts

@@ -59,10 +59,14 @@ export function normaliseWidgetStyleFields(
 export function normaliseWidgetStyles(raw: unknown): ThemeWidgetStyles;
 
 /**
- * REQ-THEME-15 host render-boundary helper: folds the theme's per-component
- * tokens into a widget's props as `style` DEFAULTS, with the author's
- * per-instance values winning. Returns the same `props` reference when the theme
- * sets nothing for this widget. Applied by the platform hosts, never by authors.
+ * REQ-THEME-15 host render-boundary helper: folds the widget's declared
+ * `styleSchema` defaults and the theme's per-component tokens into a widget's
+ * props as `style` DEFAULTS, with the author's per-instance values winning.
+ *
+ * sc-6750 — precedence, weakest first: `styleSchema` default ->
+ * palette/`components.<scope>` -> `widgetStyles[manifestId]` -> per-instance
+ * `props.style`. Returns the same `props` reference when neither the theme nor
+ * the schema sets anything. Applied by the platform hosts, never by authors.
  */
 export function applyThemeComponentStyle<T = Record<string, unknown>>(
   manifestId: string,

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/dist/linter.js

@@ -56,152 +56,9 @@ const CONTRACT_RULES = CONTRACT.bannedApis.map((b) =>
   _ruleForIdentifier(b.identifier, b.reason),
 );
 
-// Replace the *content* of comments and string / template literals with
-// spaces so the banned-identifier scan only ever sees executable code. A
-// banned host-escape identifier (`window`, `document`, `eval`, `process`, …)
-// is only dangerous as a real identifier reference — never as prose in a
-// `//` comment or as character data inside a string — so matching the bare
-// word there is a false positive that blocks an otherwise-clean widget (a
-// comment that reads "the hour window the grid renders" must not trip
-// `no-window`).
-//
-// Newlines are preserved verbatim so reported line numbers still line up
-// with the original source. Template-literal `${ … }` expression holes are
-// left intact: real code lives there and must still be scanned (`${window}`
-// is a genuine escape). Backslash escapes inside strings/templates are
-// consumed so an escaped quote (`"\""`) doesn't end the literal early.
-function _stripNonCode(source, { keepStrings = false } = {}) {
-  let out = "";
-  const n = source.length;
-  let mode = "code"; // code | line | block | sq | dq | tmpl
-  // Brace depth, plus a stack of the depths at which an enclosing template
-  // literal resumes — lets a `${ … }` hole (which may itself contain `{}`,
-  // strings, or nested templates) be told apart from the literal text.
-  let braceDepth = 0;
-  const tmplStack = [];
-  const keep = (ch) => {
-    out += ch;
-  };
-  const blank = (ch) => {
-    out += ch === "\n" || ch === "\r" ? ch : " ";
-  };
-  // String / template CONTENT: blanked for the banned-identifier scan
-  // (prose must not trip `no-window`), kept for the host-API-URL scan,
-  // whose whole job is to find a URL literal.
-  const str = keepStrings ? keep : blank;
-  let i = 0;
-  while (i < n) {
-    const ch = source[i];
-    const nx = source[i + 1];
-    if (mode === "code") {
-      if (ch === "/" && nx === "/") {
-        mode = "line";
-        blank(ch);
-        blank(nx);
-        i += 2;
-      } else if (ch === "/" && nx === "*") {
-        mode = "block";
-        blank(ch);
-        blank(nx);
-        i += 2;
-      } else if (ch === "'") {
-        mode = "sq";
-        str(ch);
-        i += 1;
-      } else if (ch === '"') {
-        mode = "dq";
-        str(ch);
-        i += 1;
-      } else if (ch === "`") {
-        mode = "tmpl";
-        str(ch);
-        i += 1;
-      } else if (ch === "{") {
-        braceDepth += 1;
-        keep(ch);
-        i += 1;
-      } else if (ch === "}") {
-        braceDepth -= 1;
-        if (
-          tmplStack.length > 0 &&
-          tmplStack[tmplStack.length - 1] === braceDepth
-        ) {
-          tmplStack.pop();
-          mode = "tmpl";
-          str(ch);
-        } else {
-          keep(ch);
-        }
-        i += 1;
-      } else {
-        keep(ch);
-        i += 1;
-      }
-    } else if (mode === "line") {
-      if (ch === "\n") {
-        mode = "code";
-        keep(ch);
-      } else {
-        blank(ch);
-      }
-      i += 1;
-    } else if (mode === "block") {
-      if (ch === "*" && nx === "/") {
-        mode = "code";
-        blank(ch);
-        blank(nx);
-        i += 2;
-      } else {
-        blank(ch);
-        i += 1;
-      }
-    } else if (mode === "sq" || mode === "dq") {
-      const quote = mode === "sq" ? "'" : '"';
-      if (ch === "\\") {
-        str(ch);
-        if (i + 1 < n) str(nx);
-        i += 2;
-      } else if (ch === quote) {
-        mode = "code";
-        str(ch);
-        i += 1;
-      } else if (ch === "\n") {
-        // A bare newline terminates an unterminated string in JS; bail back
-        // to code so malformed input can't blank the rest of the file.
-        mode = "code";
-        keep(ch);
-        i += 1;
-      } else {
-        str(ch);
-        i += 1;
-      }
-    } else {
-      // mode === "tmpl"
-      if (ch === "\\") {
-        str(ch);
-        if (i + 1 < n) str(nx);
-        i += 2;
-      } else if (ch === "`") {
-        mode = "code";
-        str(ch);
-        i += 1;
-      } else if (ch === "$" && nx === "{") {
-        // Enter an expression hole. Remember the brace depth the template
-        // resumes at, then count the `{` so its matching `}` is recognised.
-        tmplStack.push(braceDepth);
-        braceDepth += 1;
-        mode = "code";
-        keep(ch);
-        keep(nx);
-        i += 2;
-      } else {
-        str(ch);
-        i += 1;
-      }
-    }
-  }
-  return out;
-}
+// sc-6086: moved to source-mask.js so the packer's scanner masks source the
+// same way this linter does. Alias kept — the rules below read _stripNonCode.
+import { stripNonCode as _stripNonCode } from "./source-mask.js";
 
 // Extra rules that don't map 1:1 to a banned identifier in the contract:
 // host-internal imports that widgets must never touch.

package/dist/source-mask.js

@@ -0,0 +1,162 @@
+// sc-6086: the shared source masker, extracted verbatim from linter.js so the
+// linter, the packer's import scanner, and the dev-server guard all agree on
+// what is code and what is a comment or string literal (CLAUDE.md §3).
+//
+// Length-preserving: every blanked character becomes a space and newlines are
+// kept, so an index into the mask is the SAME index in the original source.
+// That is what lets a caller match against the mask and splice the original.
+
+// Replace the *content* of comments and string / template literals with
+// spaces so the banned-identifier scan only ever sees executable code. A
+// banned host-escape identifier (`window`, `document`, `eval`, `process`, …)
+// is only dangerous as a real identifier reference — never as prose in a
+// `//` comment or as character data inside a string — so matching the bare
+// word there is a false positive that blocks an otherwise-clean widget (a
+// comment that reads "the hour window the grid renders" must not trip
+// `no-window`).
+//
+// Newlines are preserved verbatim so reported line numbers still line up
+// with the original source. Template-literal `${ … }` expression holes are
+// left intact: real code lives there and must still be scanned (`${window}`
+// is a genuine escape). Backslash escapes inside strings/templates are
+// consumed so an escaped quote (`"\""`) doesn't end the literal early.
+export function stripNonCode(
+  source,
+  { keepStrings = false, keepTemplates = keepStrings } = {},
+) {
+  let out = "";
+  const n = source.length;
+  let mode = "code"; // code | line | block | sq | dq | tmpl
+  // Brace depth, plus a stack of the depths at which an enclosing template
+  // literal resumes — lets a `${ … }` hole (which may itself contain `{}`,
+  // strings, or nested templates) be told apart from the literal text.
+  let braceDepth = 0;
+  const tmplStack = [];
+  const keep = (ch) => {
+    out += ch;
+  };
+  const blank = (ch) => {
+    out += ch === "\n" || ch === "\r" ? ch : " ";
+  };
+  // String / template CONTENT: blanked for the banned-identifier scan
+  // (prose must not trip `no-window`), kept for the host-API-URL scan,
+  // whose whole job is to find a URL literal.
+  const str = keepStrings ? keep : blank;
+  // An import specifier is always a quoted string, never a template literal —
+  // so the import scanner keeps quoted content and blanks templates, which is
+  // what stops an `import … from "./x"` line inside a backtick block from
+  // reading as a real statement.
+  const tmplStr = keepTemplates ? keep : blank;
+  let i = 0;
+  while (i < n) {
+    const ch = source[i];
+    const nx = source[i + 1];
+    if (mode === "code") {
+      if (ch === "/" && nx === "/") {
+        mode = "line";
+        blank(ch);
+        blank(nx);
+        i += 2;
+      } else if (ch === "/" && nx === "*") {
+        mode = "block";
+        blank(ch);
+        blank(nx);
+        i += 2;
+      } else if (ch === "'") {
+        mode = "sq";
+        str(ch);
+        i += 1;
+      } else if (ch === '"') {
+        mode = "dq";
+        str(ch);
+        i += 1;
+      } else if (ch === "`") {
+        mode = "tmpl";
+        tmplStr(ch);
+        i += 1;
+      } else if (ch === "{") {
+        braceDepth += 1;
+        keep(ch);
+        i += 1;
+      } else if (ch === "}") {
+        braceDepth -= 1;
+        if (
+          tmplStack.length > 0 &&
+          tmplStack[tmplStack.length - 1] === braceDepth
+        ) {
+          tmplStack.pop();
+          mode = "tmpl";
+          str(ch);
+        } else {
+          keep(ch);
+        }
+        i += 1;
+      } else {
+        keep(ch);
+        i += 1;
+      }
+    } else if (mode === "line") {
+      if (ch === "\n") {
+        mode = "code";
+        keep(ch);
+      } else {
+        blank(ch);
+      }
+      i += 1;
+    } else if (mode === "block") {
+      if (ch === "*" && nx === "/") {
+        mode = "code";
+        blank(ch);
+        blank(nx);
+        i += 2;
+      } else {
+        blank(ch);
+        i += 1;
+      }
+    } else if (mode === "sq" || mode === "dq") {
+      const quote = mode === "sq" ? "'" : '"';
+      if (ch === "\\") {
+        str(ch);
+        if (i + 1 < n) str(nx);
+        i += 2;
+      } else if (ch === quote) {
+        mode = "code";
+        str(ch);
+        i += 1;
+      } else if (ch === "\n") {
+        // A bare newline terminates an unterminated string in JS; bail back
+        // to code so malformed input can't blank the rest of the file.
+        mode = "code";
+        keep(ch);
+        i += 1;
+      } else {
+        str(ch);
+        i += 1;
+      }
+    } else {
+      // mode === "tmpl"
+      if (ch === "\\") {
+        tmplStr(ch);
+        if (i + 1 < n) tmplStr(nx);
+        i += 2;
+      } else if (ch === "`") {
+        mode = "code";
+        tmplStr(ch);
+        i += 1;
+      } else if (ch === "$" && nx === "{") {
+        // Enter an expression hole. Remember the brace depth the template
+        // resumes at, then count the `{` so its matching `}` is recognised.
+        tmplStack.push(braceDepth);
+        braceDepth += 1;
+        mode = "code";
+        keep(ch);
+        keep(nx);
+        i += 2;
+      } else {
+        tmplStr(ch);
+        i += 1;
+      }
+    }
+  }
+  return out;
+}