@colixsystems/widget-sdk 0.118.0 → 0.120.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,56 @@ 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.120.0 (contract 1.92.0)
+
+**A `top-bar` app chooses which ROW its menu lives in, and how that row looks — `CONTRACT.themeTopBarMenuStyles` plus the `topBar` tab vocabulary (REQ-NAV-STRUCTURE).** The shape drew its menu as text links beside the brand, sharing the bar's one row wherever there was space. That reads as part of the header rather than as the app's global navigation. `topBarMenuStyle` now picks between `links` (that row, unchanged) and `tabs` — a dedicated tab row under the bar at every width, icon and label per page, scrolling sideways rather than dropping one. `normaliseNavigation` returns it beside `menuType`, so one resolver still answers both questions and the Player and the export cannot disagree about which row an app draws. Absent, unknown, or set on any other shape resolves to `links`.
+
+`resolveTopBarTokens` gains the vocabulary that row is painted with:
+
+- **`activeColor`** — the current page's mark: the active link's label, and an active tab's label and indicator. Its fallback chain is the FOOTER's rather than a new one: the bar's own value, else the **rail's**, else the brand. An app should not have to state the same navigation colour three times, and the rail is where an author already sets it. Unlike the footer's, this chain ends in the brand rather than in null — an active mark has no null state.
+- **`tabStyle`** (`underline` | `attached`) and **`contentSurface`**. `attached` makes the current tab a folder tab joined to the page. The join is made by CONSTRUCTION rather than by matching: an opaque tab cannot track a page that is not flat, so the content area takes the same surface and becomes the panel the tab sits in. `contentSurface` is that shared value — always opaque, following a gradient to its start colour, and honouring an authored active surface so moving the tab moves the page with it.
+- **`tabBackgroundColor`** / **`tabActiveBackgroundColor`** — a tab's own surface per state, authored or null. Null paints none and the bar shows through.
+- **`tabIndicatorWidth`** (0-8, default 2) — the underline under the current tab. Zero draws none, so the WIDTH is its switch: the indicator shares `activeColor` with the label and has no null colour to switch on.
+- **`tabCornerRadius`** (0-24) rounds the tab's TOP corners only — its feet stay square whatever the value, because a rounded foot notches the join — and **`tabPaddingX`** / **`tabPaddingY`** (0-32) replace the frozen 12/8, which remain the defaults.
+
+Every measurement is CLAMPED rather than dropped: landing on the end of the range is what an author dragging a slider means. Host-integration surface only — no author-facing hook, prop, primitive, or manifest field changed.
+
+
+### 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

@@ -228,6 +228,18 @@ const THEME_MENU_TYPES = Object.freeze({
     quickBarMaxItems: null,
   }),
 });
+const THEME_TOP_BAR_MENU_STYLES = Object.freeze({
+  links: Object.freeze({
+    name: "Links",
+    summary:
+      "Text links beside the brand, dropping to their own row only when a phone leaves them no space.",
+  }),
+  tabs: Object.freeze({
+    name: "Tabs",
+    summary:
+      "A dedicated tab row under the bar at every width -- icon and label per page, marked by the brand, scrolling sideways when it runs out of room.",
+  }),
+});
 const THEME_SPACING_SCALE = Object.freeze({
   min: 0.5,
   max: 2,
@@ -1570,7 +1582,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 +1601,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 +2288,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 +2301,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 +3566,30 @@ 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.
+  // 1.92.0: additive (REQ-NAV-STRUCTURE) -- `themeTopBarMenuStyles`, the closed
+  //    catalogue of how a `top-bar` app draws its menu: `links` (today's row of
+  //    text links beside the brand) or `tabs` (a dedicated tab row under the
+  //    bar at every width, so the menu reads as global navigation rather than
+  //    as part of the header). Resolved with the shape by `normaliseNavigation`,
+  //    which now returns `topBarMenuStyle` beside `menuType` -- one resolver, so
+  //    the Player and the export cannot disagree about which row an app draws.
+  //    Absent, unknown, or set on any other shape resolves to `links`, so every
+  //    app authored before the choice existed renders and compiles identically.
+  version: "1.92.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -3544,6 +3606,7 @@ const CONTRACT = deepFreeze({
   themeComponentGradient: THEME_COMPONENT_GRADIENT,
   themeSpacingScale: THEME_SPACING_SCALE,
   themeMenuTypes: THEME_MENU_TYPES,
+  themeTopBarMenuStyles: THEME_TOP_BAR_MENU_STYLES,
   themeWidgetStyles: THEME_WIDGET_STYLES,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,

package/dist/contract.js

@@ -228,6 +228,18 @@ const THEME_MENU_TYPES = Object.freeze({
     quickBarMaxItems: null,
   }),
 });
+const THEME_TOP_BAR_MENU_STYLES = Object.freeze({
+  links: Object.freeze({
+    name: "Links",
+    summary:
+      "Text links beside the brand, dropping to their own row only when a phone leaves them no space.",
+  }),
+  tabs: Object.freeze({
+    name: "Tabs",
+    summary:
+      "A dedicated tab row under the bar at every width -- icon and label per page, marked by the brand, scrolling sideways when it runs out of room.",
+  }),
+});
 const THEME_SPACING_SCALE = Object.freeze({
   min: 0.5,
   max: 2,
@@ -1570,7 +1582,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 +1601,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 +2288,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 +2301,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 +3566,30 @@ 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.
+  // 1.92.0: additive (REQ-NAV-STRUCTURE) -- `themeTopBarMenuStyles`, the closed
+  //    catalogue of how a `top-bar` app draws its menu: `links` (today's row of
+  //    text links beside the brand) or `tabs` (a dedicated tab row under the
+  //    bar at every width, so the menu reads as global navigation rather than
+  //    as part of the header). Resolved with the shape by `normaliseNavigation`,
+  //    which now returns `topBarMenuStyle` beside `menuType` -- one resolver, so
+  //    the Player and the export cannot disagree about which row an app draws.
+  //    Absent, unknown, or set on any other shape resolves to `links`, so every
+  //    app authored before the choice existed renders and compiles identically.
+  version: "1.92.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -3544,6 +3606,7 @@ const CONTRACT = deepFreeze({
   themeComponentGradient: THEME_COMPONENT_GRADIENT,
   themeSpacingScale: THEME_SPACING_SCALE,
   themeMenuTypes: THEME_MENU_TYPES,
+  themeTopBarMenuStyles: THEME_TOP_BAR_MENU_STYLES,
   themeWidgetStyles: THEME_WIDGET_STYLES,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,

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

@@ -155,8 +155,14 @@ export function createToastController(
 
 export type ThemeMenuType = "sidebar" | "top-bar" | "bottom-tabs";
 
+// How a `top-bar` app draws its menu — closed by
+// `CONTRACT.themeTopBarMenuStyles`. Meaningless on the other two shapes, where
+// the resolver always reports "links".
+export type ThemeTopBarMenuStyle = "links" | "tabs";
+
 export interface ResolvedNavigation {
   menuType: ThemeMenuType;
+  topBarMenuStyle: ThemeTopBarMenuStyle;
 }
 
 /**
@@ -226,6 +232,37 @@ export interface TopBarTokens {
   titleColor: string;
   borderColor: string | null;
   borderWidth: number | null;
+  /** The current page's mark — the active link's label, and an active tab's
+   *  label plus its indicator. Falls back to the RAIL's `activeColor` and then
+   *  to the brand, so an app states its navigation colour once. */
+  activeColor: string;
+  /** How a `tabs` menu row marks its current page. `underline` keeps the tab in
+   *  the bar's surface behind an indicator; `attached` makes it a folder tab
+   *  that takes `contentSurface` and sits over the row's divider. Meaningless
+   *  under the `links` style, which draws no tabs. */
+  tabStyle: "underline" | "attached";
+  /** The surface an `attached` tab AND its content panel share — always
+   *  opaque, because a translucent tab would show the bar through the page it
+   *  is part of. Honours `tabActiveBackgroundColor`, so moving the tab moves
+   *  the page with it. */
+  contentSurface: string;
+  /** A tab's own surface, authored or null. Null paints none and the bar shows
+   *  through. */
+  tabBackgroundColor: string | null;
+  /** The underline under the current tab in px, 0-8. Zero draws none and
+   *  leaves the tab marked by its label colour alone, so the WIDTH is this
+   *  one's switch — it shares `activeColor` with the label and so has no null
+   *  colour to switch on. */
+  tabIndicatorWidth: number;
+  /** The tab's TOP corner rounding in px, 0-24. Its feet stay square whatever
+   *  this says — a rounded foot notches the join with the content. */
+  tabCornerRadius: number;
+  /** The room inside a tab in px, 0-32, defaulting to the row's shipped 12/8. */
+  tabPaddingX: number;
+  tabPaddingY: number;
+  /** The current tab's own surface, authored or null. Under `attached` the
+   *  resolved surface is `contentSurface` above, which already honours it. */
+  tabActiveBackgroundColor: string | null;
 }
 
 /**

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/navigation.cjs

@@ -30,6 +30,9 @@ const { CONTRACT, isHexColor } = require("./contract.cjs");
 // Absent or unknown resolves here, so every app authored before menu types
 // existed renders and compiles byte-identically.
 const DEFAULT_MENU_TYPE = "sidebar";
+// Today's row of text links, so an app that never made the choice draws exactly
+// what it drew before it existed.
+const DEFAULT_TOP_BAR_MENU_STYLE = "links";
 
 function isPlainObject(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -42,15 +45,26 @@ function isPlainObject(value) {
  * yields the default sidebar rather than something a host has to guard against.
  *
  * @param {unknown} navigation — the raw `theme_config.navigation` value.
- * @returns {{ menuType: string }} the resolved navigation structure.
+ * @returns {{ menuType: string, topBarMenuStyle: string }} the resolved
+ *   navigation structure.
  */
 function normaliseNavigation(navigation) {
-  const raw = isPlainObject(navigation) ? navigation.menuType : undefined;
+  const block = isPlainObject(navigation) ? navigation : {};
+  const raw = block.menuType;
   const menuType =
     typeof raw === "string" && Object.hasOwn(CONTRACT.themeMenuTypes, raw)
       ? raw
       : DEFAULT_MENU_TYPE;
-  return { menuType };
+  const rawStyle = block.topBarMenuStyle;
+  // Resolved to `links` for every shape but `top-bar`, so a host reading it can
+  // never act on a value the app's own chrome has no row to draw.
+  const topBarMenuStyle =
+    menuType === "top-bar" &&
+    typeof rawStyle === "string" &&
+    Object.hasOwn(CONTRACT.themeTopBarMenuStyles, rawStyle)
+      ? rawStyle
+      : DEFAULT_TOP_BAR_MENU_STYLE;
+  return { menuType, topBarMenuStyle };
 }
 
 /**
@@ -137,6 +151,69 @@ const DEFAULT_CHROME_SURFACE = "#ffffff";
 const DEFAULT_CHROME_TEXT = "#475569";
 // The web mobile header's icon colour, `text-slate-700`.
 const DEFAULT_TOP_BAR_TINT = "#334155";
+// The page beneath the chrome — the web's `DEFAULT_APP_BACKGROUND_COLOR`
+// (frontend/src/utils/theme.js) and the compiler's, which are the same slate-50.
+const DEFAULT_APP_SURFACE = "#f8fafc";
+
+// An `attached` tab is joined to the page, so its surface must be OPAQUE: the
+// 8-digit form a look uses to float a translucent rail would show the bar
+// through the page the tab claims to be part of. Both hosts already drop alpha
+// for the page itself (web `opaqueColor`, compiler `opaqueHex`); this is the
+// same rule, in the one place the tab reads it from.
+// The colour the PAGE actually shows where a tab meets it. A gradient owns the
+// visible background wherever one is configured and the flat `backgroundColor`
+// shows nowhere, so an attached tab matching the flat colour under a gradient is
+// the mismatch this exists to avoid — it takes the gradient's START colour,
+// which is what the page paints at the top edge the tab is joined to.
+function pageSurface(config) {
+  const gradient = isPlainObject(config.backgroundGradient)
+    ? config.backgroundGradient
+    : null;
+  const from = gradient ? opaqueOr(gradient.from) : null;
+  return hexOr(from || opaqueOr(config.backgroundColor), DEFAULT_APP_SURFACE);
+}
+
+// The rail's raw block — the fallback every other chrome's active colour ends
+// up at, so an app states its navigation colour once.
+function sidebarBlock(config) {
+  return isPlainObject(config.sidebar) ? config.sidebar : {};
+}
+
+// REQ-NAV-STRUCTURE: the tab's TOP corners, in px. Zero is the default and the
+// square tab the row shipped with; the feet stay square whatever this says,
+// because a rounded foot notches the join. Clamped rather than dropped, so a
+// value past the end lands on the end instead of silently reverting to square.
+const TAB_RADIUS_MAX = 24;
+function tabRadiusOr(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return 0;
+  return Math.min(Math.max(Math.round(value), 0), TAB_RADIUS_MAX);
+}
+
+// The room inside a tab, in px. The defaults are the row's shipped `px-3 py-2`.
+const TAB_PADDING_MAX = 32;
+const DEFAULT_TAB_PADDING_X = 12;
+const DEFAULT_TAB_PADDING_Y = 8;
+function tabSpaceOr(value, fallback) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  return Math.min(Math.max(Math.round(value), 0), TAB_PADDING_MAX);
+}
+
+// The current tab's underline, in px. Two is what the row shipped with; zero is
+// off. Clamped rather than dropped, like the tab's other measurements.
+const TAB_INDICATOR_MAX = 8;
+const DEFAULT_TAB_INDICATOR = 2;
+function tabIndicatorOr(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return DEFAULT_TAB_INDICATOR;
+  }
+  return Math.min(Math.max(Math.round(value), 0), TAB_INDICATOR_MAX);
+}
+
+function opaqueOr(value) {
+  return isHexColor(value) && value.length !== 9 && value.length !== 5
+    ? value
+    : null;
+}
 
 // The contract's own guard, which already admits the 8-digit form a look uses
 // to float a translucent rail (#RRGGBBAA).
@@ -201,8 +278,65 @@ function resolveTopBarTokens(theme) {
     backgroundColor: hexOr(topBar.backgroundColor, DEFAULT_CHROME_SURFACE),
     tintColor: authored || DEFAULT_TOP_BAR_TINT,
     titleColor: authored || brandPrimary(config),
+    // REQ-NAV-STRUCTURE: the CURRENT page's mark — the active link's label, and
+    // an active tab's label plus its indicator. It read the brand directly
+    // before, which is right as a default and wrong as a rule: an attached tab
+    // wears the page's surface, and the brand that reads well on the bar can
+    // fail on the page.
+    //
+    // The fallback chain is the FOOTER's, deliberately: the bar's own value,
+    // else the RAIL's, else the brand. One app should not have to state the
+    // same navigation colour three times, and the rail is where an author
+    // already sets it — so the bar follows the app's navigation by default and
+    // departs from it only when asked. Unlike the footer's `pick`, this one
+    // ends in the brand rather than in null: an active mark has no null state.
+    activeColor: hexOr(
+      topBar.activeColor,
+      hexOr(sidebarBlock(config).activeColor, brandPrimary(config)),
+    ),
     borderColor,
     borderWidth: borderColor ? borderWidthOr(topBar.borderWidth) : null,
+    // REQ-NAV-STRUCTURE: how the tab row marks its current page.
+    // `underline` keeps the tab in the bar's surface and marks it with an
+    // indicator. `attached` makes it a real folder tab: it takes the CONTENT's
+    // surface and sits over the row's divider, so the tab and the page beneath
+    // read as one plane. Meaningless under the `links` style, which draws no
+    // tabs — a host reads it only where it has tabs to draw.
+    tabStyle: topBar.tabStyle === "attached" ? "attached" : "underline",
+    // The surface an `attached` tab AND its content panel share. One value for
+    // both, so the join cannot come apart: whatever the current tab is painted,
+    // the page beneath it is painted too. An authored active surface therefore
+    // moves both. Resolved HERE rather than by each host, because a tab that
+    // fails to match the page it is joined to reads as a mismatched box instead
+    // of a tab, and two hosts computing it separately is exactly how that
+    // drifts. Opaque by construction: a translucent tab would show the bar
+    // through the page it claims to be part of.
+    contentSurface: hexOr(
+      opaqueOr(topBar.tabActiveBackgroundColor),
+      pageSurface(config),
+    ),
+    // REQ-NAV-STRUCTURE: the underline that marks the current tab, in px. Zero
+    // turns it OFF and leaves the tab marked by its label colour alone, which
+    // is a real choice rather than an unstyled state — so unlike the chrome
+    // divider, whose COLOUR is its switch, this one's width is. It takes
+    // `activeColor` above; a mark and its label disagreeing about which colour
+    // means "you are here" would be two marks, not one.
+    tabIndicatorWidth: tabIndicatorOr(topBar.tabIndicatorWidth),
+    // The tab's TOP corners. Its feet stay square regardless — see tabRadiusOr.
+    tabCornerRadius: tabRadiusOr(topBar.tabCornerRadius),
+    // The room inside a tab. Defaulted to what the row shipped with (12/8), so
+    // an app that never touches them is unchanged, and clamped rather than
+    // dropped for the same reason the radius is.
+    tabPaddingX: tabSpaceOr(topBar.tabPaddingX, DEFAULT_TAB_PADDING_X),
+    tabPaddingY: tabSpaceOr(topBar.tabPaddingY, DEFAULT_TAB_PADDING_Y),
+    // A tab's own surface, authored or nothing. Null means the tab paints none
+    // and the bar shows through it, which is what both styles did before the
+    // keys existed — so an app that never set them is unchanged.
+    tabBackgroundColor: hexOrNull(topBar.tabBackgroundColor),
+    // Only meaningful where the style draws no panel: under `attached` the
+    // active surface IS `contentSurface` above. Null under `underline` leaves
+    // the current tab unpainted, marked by its indicator alone.
+    tabActiveBackgroundColor: hexOrNull(topBar.tabActiveBackgroundColor),
   };
 }
 

package/dist/navigation.js

@@ -21,6 +21,9 @@ import { CONTRACT, isHexColor } from "./contract.js";
 // Absent or unknown resolves here, so every app authored before menu types
 // existed renders and compiles byte-identically.
 const DEFAULT_MENU_TYPE = "sidebar";
+// Today's row of text links, so an app that never made the choice draws exactly
+// what it drew before it existed.
+const DEFAULT_TOP_BAR_MENU_STYLE = "links";
 
 function isPlainObject(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -33,15 +36,26 @@ function isPlainObject(value) {
  * yields the default sidebar rather than something a host has to guard against.
  *
  * @param {unknown} navigation — the raw `theme_config.navigation` value.
- * @returns {{ menuType: string }} the resolved navigation structure.
+ * @returns {{ menuType: string, topBarMenuStyle: string }} the resolved
+ *   navigation structure.
  */
 export function normaliseNavigation(navigation) {
-  const raw = isPlainObject(navigation) ? navigation.menuType : undefined;
+  const block = isPlainObject(navigation) ? navigation : {};
+  const raw = block.menuType;
   const menuType =
     typeof raw === "string" && Object.hasOwn(CONTRACT.themeMenuTypes, raw)
       ? raw
       : DEFAULT_MENU_TYPE;
-  return { menuType };
+  const rawStyle = block.topBarMenuStyle;
+  // Resolved to `links` for every shape but `top-bar`, so a host reading it can
+  // never act on a value the app's own chrome has no row to draw.
+  const topBarMenuStyle =
+    menuType === "top-bar" &&
+    typeof rawStyle === "string" &&
+    Object.hasOwn(CONTRACT.themeTopBarMenuStyles, rawStyle)
+      ? rawStyle
+      : DEFAULT_TOP_BAR_MENU_STYLE;
+  return { menuType, topBarMenuStyle };
 }
 
 /**
@@ -128,6 +142,69 @@ const DEFAULT_CHROME_SURFACE = "#ffffff";
 const DEFAULT_CHROME_TEXT = "#475569";
 // The web mobile header's icon colour, `text-slate-700`.
 const DEFAULT_TOP_BAR_TINT = "#334155";
+// The page beneath the chrome — the web's `DEFAULT_APP_BACKGROUND_COLOR`
+// (frontend/src/utils/theme.js) and the compiler's, which are the same slate-50.
+const DEFAULT_APP_SURFACE = "#f8fafc";
+
+// An `attached` tab is joined to the page, so its surface must be OPAQUE: the
+// 8-digit form a look uses to float a translucent rail would show the bar
+// through the page the tab claims to be part of. Both hosts already drop alpha
+// for the page itself (web `opaqueColor`, compiler `opaqueHex`); this is the
+// same rule, in the one place the tab reads it from.
+// The colour the PAGE actually shows where a tab meets it. A gradient owns the
+// visible background wherever one is configured and the flat `backgroundColor`
+// shows nowhere, so an attached tab matching the flat colour under a gradient is
+// the mismatch this exists to avoid — it takes the gradient's START colour,
+// which is what the page paints at the top edge the tab is joined to.
+function pageSurface(config) {
+  const gradient = isPlainObject(config.backgroundGradient)
+    ? config.backgroundGradient
+    : null;
+  const from = gradient ? opaqueOr(gradient.from) : null;
+  return hexOr(from || opaqueOr(config.backgroundColor), DEFAULT_APP_SURFACE);
+}
+
+// The rail's raw block — the fallback every other chrome's active colour ends
+// up at, so an app states its navigation colour once.
+function sidebarBlock(config) {
+  return isPlainObject(config.sidebar) ? config.sidebar : {};
+}
+
+// REQ-NAV-STRUCTURE: the tab's TOP corners, in px. Zero is the default and the
+// square tab the row shipped with; the feet stay square whatever this says,
+// because a rounded foot notches the join. Clamped rather than dropped, so a
+// value past the end lands on the end instead of silently reverting to square.
+const TAB_RADIUS_MAX = 24;
+function tabRadiusOr(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return 0;
+  return Math.min(Math.max(Math.round(value), 0), TAB_RADIUS_MAX);
+}
+
+// The room inside a tab, in px. The defaults are the row's shipped `px-3 py-2`.
+const TAB_PADDING_MAX = 32;
+const DEFAULT_TAB_PADDING_X = 12;
+const DEFAULT_TAB_PADDING_Y = 8;
+function tabSpaceOr(value, fallback) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  return Math.min(Math.max(Math.round(value), 0), TAB_PADDING_MAX);
+}
+
+// The current tab's underline, in px. Two is what the row shipped with; zero is
+// off. Clamped rather than dropped, like the tab's other measurements.
+const TAB_INDICATOR_MAX = 8;
+const DEFAULT_TAB_INDICATOR = 2;
+function tabIndicatorOr(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return DEFAULT_TAB_INDICATOR;
+  }
+  return Math.min(Math.max(Math.round(value), 0), TAB_INDICATOR_MAX);
+}
+
+function opaqueOr(value) {
+  return isHexColor(value) && value.length !== 9 && value.length !== 5
+    ? value
+    : null;
+}
 
 // The contract's own guard, which already admits the 8-digit form a look uses
 // to float a translucent rail (#RRGGBBAA).
@@ -192,8 +269,65 @@ export function resolveTopBarTokens(theme) {
     backgroundColor: hexOr(topBar.backgroundColor, DEFAULT_CHROME_SURFACE),
     tintColor: authored || DEFAULT_TOP_BAR_TINT,
     titleColor: authored || brandPrimary(config),
+    // REQ-NAV-STRUCTURE: the CURRENT page's mark — the active link's label, and
+    // an active tab's label plus its indicator. It read the brand directly
+    // before, which is right as a default and wrong as a rule: an attached tab
+    // wears the page's surface, and the brand that reads well on the bar can
+    // fail on the page.
+    //
+    // The fallback chain is the FOOTER's, deliberately: the bar's own value,
+    // else the RAIL's, else the brand. One app should not have to state the
+    // same navigation colour three times, and the rail is where an author
+    // already sets it — so the bar follows the app's navigation by default and
+    // departs from it only when asked. Unlike the footer's `pick`, this one
+    // ends in the brand rather than in null: an active mark has no null state.
+    activeColor: hexOr(
+      topBar.activeColor,
+      hexOr(sidebarBlock(config).activeColor, brandPrimary(config)),
+    ),
     borderColor,
     borderWidth: borderColor ? borderWidthOr(topBar.borderWidth) : null,
+    // REQ-NAV-STRUCTURE: how the tab row marks its current page.
+    // `underline` keeps the tab in the bar's surface and marks it with an
+    // indicator. `attached` makes it a real folder tab: it takes the CONTENT's
+    // surface and sits over the row's divider, so the tab and the page beneath
+    // read as one plane. Meaningless under the `links` style, which draws no
+    // tabs — a host reads it only where it has tabs to draw.
+    tabStyle: topBar.tabStyle === "attached" ? "attached" : "underline",
+    // The surface an `attached` tab AND its content panel share. One value for
+    // both, so the join cannot come apart: whatever the current tab is painted,
+    // the page beneath it is painted too. An authored active surface therefore
+    // moves both. Resolved HERE rather than by each host, because a tab that
+    // fails to match the page it is joined to reads as a mismatched box instead
+    // of a tab, and two hosts computing it separately is exactly how that
+    // drifts. Opaque by construction: a translucent tab would show the bar
+    // through the page it claims to be part of.
+    contentSurface: hexOr(
+      opaqueOr(topBar.tabActiveBackgroundColor),
+      pageSurface(config),
+    ),
+    // REQ-NAV-STRUCTURE: the underline that marks the current tab, in px. Zero
+    // turns it OFF and leaves the tab marked by its label colour alone, which
+    // is a real choice rather than an unstyled state — so unlike the chrome
+    // divider, whose COLOUR is its switch, this one's width is. It takes
+    // `activeColor` above; a mark and its label disagreeing about which colour
+    // means "you are here" would be two marks, not one.
+    tabIndicatorWidth: tabIndicatorOr(topBar.tabIndicatorWidth),
+    // The tab's TOP corners. Its feet stay square regardless — see tabRadiusOr.
+    tabCornerRadius: tabRadiusOr(topBar.tabCornerRadius),
+    // The room inside a tab. Defaulted to what the row shipped with (12/8), so
+    // an app that never touches them is unchanged, and clamped rather than
+    // dropped for the same reason the radius is.
+    tabPaddingX: tabSpaceOr(topBar.tabPaddingX, DEFAULT_TAB_PADDING_X),
+    tabPaddingY: tabSpaceOr(topBar.tabPaddingY, DEFAULT_TAB_PADDING_Y),
+    // A tab's own surface, authored or nothing. Null means the tab paints none
+    // and the bar shows through it, which is what both styles did before the
+    // keys existed — so an app that never set them is unchanged.
+    tabBackgroundColor: hexOrNull(topBar.tabBackgroundColor),
+    // Only meaningful where the style draws no panel: under `attached` the
+    // active surface IS `contentSurface` above. Null under `underline` leaves
+    // the current tab unpainted, marked by its indicator alone.
+    tabActiveBackgroundColor: hexOrNull(topBar.tabActiveBackgroundColor),
   };
 }
 

package/package.json

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