@colixsystems/widget-sdk 0.117.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,7 +70,61 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.117.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`.
+
+It is the **weakest** layer, deliberately: it applies only when nothing above it sets that field.
+
+```
+styleSchema `default`  ->  palette / components.<scope>  ->  widgetStyles[manifestId]  ->  per-instance props.style
+```
+
+So a workspace theme still outranks a widget's own baseline, and a field you leave undefaulted keeps following the theme exactly as before. Nothing changes for a widget that declares no style defaults.
+
+The host still does **not** apply style to elements — your widget owns placement and keeps reading `props.style.<field>` (or `useWidgetStyle()`) and applying each value where it chooses:
+
+```jsx
+const style = useWidgetStyle();
+<View style={[styles.card, style.cardBackground && { backgroundColor: style.cardBackground }]}>
+```
+
+Keep `themeDefault` for a fallback that IS a theme token: it stays display-only (a greyed placeholder in the Style panel) so the field tracks the workspace theme. Use `default` for a literal constant your code genuinely falls back to — that value now reaches `props.style`, so it must match what your code applies.
 
 ### What's new in 0.117.0 (contract 1.89.0)
 

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,
@@ -1967,8 +1984,11 @@ const MANIFEST_SCHEMA = {
       "exposes; the Studio Properties Panel renders a \"Style\" section from " +
       "it. The author's resolved values are delivered to the widget under " +
       "props.style (one object keyed by style-field name); the widget reads " +
-      "props.style.<field> and applies each wherever it chooses. The host " +
-      "never auto-applies style — the widget owns placement.",
+      "props.style.<field> and applies each wherever it chooses. A field's " +
+      "own `default` is resolved onto props.style as the WEAKEST layer " +
+      "(sc-6750): it applies only when no theme layer and no per-instance " +
+      "value sets that field. The host never applies style to elements " +
+      "— the widget owns placement.",
     default: {},
   },
   rendersOwnChrome: {
@@ -2256,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, " +
@@ -2266,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" },
   },
@@ -3515,7 +3545,30 @@ const CONTRACT = deepFreeze({
   // web build reads deviceorientation angles rather than real acceleration —
   // the web half is a widget.web.jsx over window.DeviceMotionEvent. Pinned in
   // the compiler's export dependencies, like every other native-module member.
-  version: "1.89.0",
+  // 1.90.0: additive (sc-6750) — a `styleSchema` field's declared `default`
+  // now RESOLVES onto `props.style`, as the weakest style layer. It was
+  // written into the manifest and then read by nothing, so an author's saved
+  // colour was silently dropped on the next render. Precedence is unchanged
+  // above it: styleSchema `default` -> palette/`components.<scope>` ->
+  // `widgetStyles[manifestId]` -> per-instance `props.style`, so a workspace
+  // 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.
+  // 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,
@@ -1967,8 +1984,11 @@ const MANIFEST_SCHEMA = {
       "exposes; the Studio Properties Panel renders a \"Style\" section from " +
       "it. The author's resolved values are delivered to the widget under " +
       "props.style (one object keyed by style-field name); the widget reads " +
-      "props.style.<field> and applies each wherever it chooses. The host " +
-      "never auto-applies style — the widget owns placement.",
+      "props.style.<field> and applies each wherever it chooses. A field's " +
+      "own `default` is resolved onto props.style as the WEAKEST layer " +
+      "(sc-6750): it applies only when no theme layer and no per-instance " +
+      "value sets that field. The host never applies style to elements " +
+      "— the widget owns placement.",
     default: {},
   },
   rendersOwnChrome: {
@@ -2256,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, " +
@@ -2266,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" },
   },
@@ -3515,7 +3545,30 @@ const CONTRACT = deepFreeze({
   // web build reads deviceorientation angles rather than real acceleration —
   // the web half is a widget.web.jsx over window.DeviceMotionEvent. Pinned in
   // the compiler's export dependencies, like every other native-module member.
-  version: "1.89.0",
+  // 1.90.0: additive (sc-6750) — a `styleSchema` field's declared `default`
+  // now RESOLVES onto `props.style`, as the weakest style layer. It was
+  // written into the manifest and then read by nothing, so an author's saved
+  // colour was silently dropped on the next render. Precedence is unchanged
+  // above it: styleSchema `default` -> palette/`components.<scope>` ->
+  // `widgetStyles[manifestId]` -> per-instance `props.style`, so a workspace
+  // 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.
+  // 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/devserver.js

@@ -67,32 +67,38 @@ import {
   shimSpecifierFromSlug,
 } from "./dev-shims.js";
 import { bundleWebEntry } from "./webbundle.js";
+import {
+  findImportStatements,
+  findRelativeImportStatements,
+} from "./flatten-entry.js";
 
 // Bare-import / relative-import detection. The loader rewrites bare specifiers
 // in the ENTRY to client-side blob shims, so they resolve fine. Relative
 // imports in a SINGLE-FILE entry have nowhere to resolve — single-file mode
 // refuses them with guidance. In directory mode, relative imports in the entry
 // AND in siblings are rewritten to absolute dev-server URLs.
-const RELATIVE_IMPORT_RE =
-  /(?:^|\n)\s*(?:import|export)[^;\n]*?from\s*['"](\.\.?\/[^'"]+)['"]/g;
-
-// Static-import / static-export-from anchored at a statement boundary
-// (start-of-line, `;`, or newline before `import`/`export`) so the rewriter
-// doesn't touch occurrences inside string literals or comment bodies. The
-// dynamic-import form (`import("...")`) is matched separately by
-// `DYNAMIC_IMPORT_RE` below — it's safe to anchor in the same way because
-// it's also valid only as an expression.
 //
-// Capture groups for both regexes:
-//   1 = leading keyword + whitespace (and the leading boundary char, which we
-//       preserve verbatim during replace so the surrounding statement isn't
-//       glued onto the previous line)
+// STATIC imports are found by the packer's scanner (`findImportStatements`),
+// never by a local regex. sc-6086 removed RELATIVE_IMPORT_RE and sc-6670 the
+// rewriter's STATIC_IMPORT_RE for the same defect: a `[^'";\n]` clause body
+// cannot span newlines, so a multi-line `import {\n a,\n} from "react"` — the
+// norm in this codebase — read as no import at all and was served verbatim.
+// The scanner walks the clause character by character, so line breaks are
+// nothing special, and it returns the specifier's quote offsets so the
+// rewriter splices exactly the specifier and can never bleed into an adjacent
+// statement. One scanner for the guard, the packer, and the rewriter (§3).
+
+// Dynamic import (`import("…")`) is an EXPRESSION, valid at any brace depth,
+// so the statement scanner does not see it — it keeps its own regex. That
+// regex separates the specifier from `import` with `\s*`, which does match
+// newlines, so it has no multi-line gap (sc-6670 verified).
+//
+// Capture groups:
+//   1 = `import` + whitespace + `(` (and the leading boundary char, preserved
+//       verbatim during replace so the call isn't glued onto what precedes it)
 //   2 = opening quote
 //   3 = specifier
-const STATIC_IMPORT_RE =
-  /((?:^|[\n;])\s*(?:import|export)\s+(?:[^'";\n]*?\s+from\s*)?)(['"])([^'"]+)\2/gm;
-const DYNAMIC_IMPORT_RE =
-  /((?:^|[\s;\(,!?:=])import\s*\(\s*)(['"])([^'"]+)\2/g;
+const DYNAMIC_IMPORT_RE = /((?:^|[\s;\(,!?:=])import\s*\(\s*)(['"])([^'"]+)\2/g;
 
 /**
  * Lazily resolve `sucrase`'s `transform`. Kept out of the module's static
@@ -137,15 +143,21 @@ export function transpile(transform, source) {
  * single-file mode to reject split-impl bundles with a clear message instead
  * of serving a module the browser can't resolve.
  *
+ * sc-6086: this delegates to the packer's statement scanner rather than
+ * `RELATIVE_IMPORT_RE`, whose `[^;\n]` body cannot span newlines — so a
+ * MULTI-LINE `import {\n  a,\n  b,\n} from "./lib/x.js"` was invisible to it.
+ * That blind spot is why `worktime-employer` passed every local check and
+ * still shipped an unresolvable import to the marketplace. One scanner, so
+ * the dev guard and the packer agree on what a relative import is
+ * (CLAUDE.md §3).
+ *
  * @param {string} source
  * @returns {string[]} unique relative specifiers
  */
 export function findRelativeImports(source) {
-  const out = new Set();
-  let m;
-  RELATIVE_IMPORT_RE.lastIndex = 0;
-  while ((m = RELATIVE_IMPORT_RE.exec(source))) out.add(m[1]);
-  return Array.from(out);
+  return Array.from(
+    new Set(findRelativeImportStatements(source).map((s) => s.specifier)),
+  );
 }
 
 /**
@@ -201,15 +213,16 @@ export function resolveRelativeImport(fromRel, specifier) {
 export function rewriteImportsForDirectoryMode(source, ctx) {
   const { fromRel, baseUrl, shimmable } = ctx;
   const unresolved = new Set();
-  const handler = (match, prefix, quote, spec) => {
+  // The URL a specifier should become, or null to leave it exactly as written.
+  const resolveSpecifier = (spec) => {
     // Relative — resolve under the widget dir.
     if (spec.startsWith("./") || spec.startsWith("../")) {
       const rel = resolveRelativeImport(fromRel, spec);
       if (!rel) {
         unresolved.add(spec);
-        return match;
+        return null;
       }
-      return `${prefix}${quote}${baseUrl}/file/${rel}${quote}`;
+      return `${baseUrl}/file/${rel}`;
     }
     // Absolute or already-resolved — leave alone.
     if (
@@ -219,21 +232,36 @@ export function rewriteImportsForDirectoryMode(source, ctx) {
       spec.startsWith("blob:") ||
       spec.startsWith("data:")
     ) {
-      return match;
+      return null;
     }
     // Bare — rewrite if shimmable, else surface as unresolved.
     if (shimmable.includes(spec)) {
-      return `${prefix}${quote}${baseUrl}/shim/${shimSlugFor(spec)}${quote}`;
+      return `${baseUrl}/shim/${shimSlugFor(spec)}`;
     }
     unresolved.add(spec);
-    return match;
+    return null;
   };
-  // Two passes: anchored static-import + anchored dynamic-import. The split
-  // (vs. one mega-regex) keeps each pattern simple AND lets us anchor each at
-  // its real statement boundary — so substrings inside string literals like
-  // `const s = "import x from 'react'"` never match.
-  let out = source.replace(STATIC_IMPORT_RE, handler);
-  out = out.replace(DYNAMIC_IMPORT_RE, handler);
+
+  // Pass 1 — static imports, spliced by the scanner's quote offsets. Splicing
+  // only what sits BETWEEN the quotes is what makes span bleed impossible:
+  // the clause, the trailing `;`, and any adjacent statement are never part of
+  // the replaced range. Walk back-to-front so earlier offsets stay valid.
+  const statements = findImportStatements(source);
+  let out = source;
+  for (let i = statements.length - 1; i >= 0; i -= 1) {
+    const { specifier, quoteStart, quoteEnd } = statements[i];
+    const url = resolveSpecifier(specifier);
+    if (url === null) continue;
+    out = out.slice(0, quoteStart + 1) + url + out.slice(quoteEnd);
+  }
+
+  // Pass 2 — dynamic `import("…")`, an expression the statement scanner does
+  // not report. Its own anchor keeps it off substrings inside string literals
+  // like `const s = "import('react')"`.
+  out = out.replace(DYNAMIC_IMPORT_RE, (match, prefix, quote, spec) => {
+    const url = resolveSpecifier(spec);
+    return url === null ? match : `${prefix}${quote}${url}${quote}`;
+  });
   return { code: out, unresolved: Array.from(unresolved) };
 }
 
@@ -315,7 +343,10 @@ export function loadWidgetJson(widgetDir) {
     const candidates = [
       resolve(widgetDir, p),
       p.startsWith(`first-party-widgets/${widgetSlug}/`)
-        ? resolve(widgetDir, p.slice(`first-party-widgets/${widgetSlug}/`.length))
+        ? resolve(
+            widgetDir,
+            p.slice(`first-party-widgets/${widgetSlug}/`.length),
+          )
         : null,
       resolve(widgetDir, "..", "..", p),
     ].filter(Boolean);
@@ -326,7 +357,10 @@ export function loadWidgetJson(widgetDir) {
       `${configPath}: ${label} must point at a file under ${widgetDir} (got "${p}")`,
     );
   }
-  const manifestAbs = _resolveUnderWidget("manifestSource", config.manifestSource);
+  const manifestAbs = _resolveUnderWidget(
+    "manifestSource",
+    config.manifestSource,
+  );
 
   let entryAbs;
   if (config.componentSources && typeof config.componentSources === "object") {
@@ -353,7 +387,12 @@ export function loadWidgetJson(widgetDir) {
     );
   }
   const entryRel = relative(widgetDir, entryAbs).split(sep).join("/");
-  return { widgetDir, manifestPath: manifestAbs, entryPath: entryAbs, entryRel };
+  return {
+    widgetDir,
+    manifestPath: manifestAbs,
+    entryPath: entryAbs,
+    entryRel,
+  };
 }
 
 function _isUnder(parentAbs, childAbs) {
@@ -444,7 +483,13 @@ export function createDevServer({
   // entry's own ancestor node_modules by default, so a widget that vendored
   // its deps locally still resolves.
   const bundleNodePaths = [];
-  const _frontendNm = resolve(watchRoot, "..", "..", "frontend", "node_modules");
+  const _frontendNm = resolve(
+    watchRoot,
+    "..",
+    "..",
+    "frontend",
+    "node_modules",
+  );
   if (existsSync(_frontendNm)) bundleNodePaths.push(_frontendNm);
 
   const sseClients = new Set();
@@ -700,7 +745,13 @@ export function createDevServer({
     if (url === "/__dev/events") return serveEvents(req, res);
     if (url === "/__dev/health") {
       res.writeHead(200, { "Content-Type": "application/json" });
-      res.end(JSON.stringify({ ok: true, manifestId, mode: directoryMode ? "directory" : "single-file" }));
+      res.end(
+        JSON.stringify({
+          ok: true,
+          manifestId,
+          mode: directoryMode ? "directory" : "single-file",
+        }),
+      );
       return;
     }
     if (directoryMode && url.startsWith("/file/")) {
@@ -736,7 +787,8 @@ export function createDevServer({
       if (ok) onLint("lint: clean");
       else {
         onLint(`lint: ${findings.length} finding(s)`);
-        for (const f of findings) onLint(`  [${f.rule}] line ${f.line}: ${f.label}`);
+        for (const f of findings)
+          onLint(`  [${f.rule}] line ${f.line}: ${f.label}`);
       }
     }
   }