@colixsystems/widget-sdk 0.119.0 → 0.121.0

package/README.md

@@ -72,6 +72,33 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 `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.121.0 (contract 1.93.0)
+
+**An unset nav-chrome surface follows the PAGE, not a flat white — `resolveSidebarTokens` / `resolveTopBarTokens` (sc-6596).** 1.84.0 converged the two hosts' separately-written chrome defaults onto the web Player's `#ffffff`. Converging was right; the value was not. An app with a themed page and no explicit `sidebar`/`topBar` `backgroundColor` got bright white chrome beside the colour its author had picked — consistently on both hosts, and consistently wrong.
+
+Both resolvers now resolve an unset `backgroundColor` to the colour the page actually shows: the app's `backgroundColor`, or a configured `backgroundGradient`'s start colour, falling back to the app default (`#f8fafc`) when the theme names neither. A gradient counts only when BOTH its stops are flat hex, which is what the hosts' own page readers require — a half-configured gradient paints nothing, so the chrome must not adopt its start colour. Per REQ-THEME-17 the page is read at FULL STRENGTH: a stored `#RRGGBBAA` reaches the chrome as its opaque base, because an alpha on the app's bottom layer composites against the host's canvas rather than anything the author chose.
+
+This is deliberately NOT the rule an `attached` top-bar tab follows. A tab JOINED to the page refuses a translucent page rather than approximate it; chrome sitting BESIDE the page follows what the page renders. Both read one shared chain, which differs by exactly that rule.
+
+An explicitly coloured rail or bar is unaffected. An app that themed nothing moves from `#ffffff` to the `#f8fafc` its page already was. The footer strip is untouched and still floors at white — it keeps `resolveFooterTokens`' raw-or-null shape and wants this same treatment next.
+
+**Behaviour change, not additive:** no signature, field or export moved — only what a host renders for an unset chrome surface. Host-integration surface only; nothing a widget imports changed. `CONTRACT.version` → `1.93.0`.
+
+### 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:
@@ -242,7 +269,7 @@ return <View style={[styles.card, spacingStyle(padding, "padding")]} />;
 
 **`resolveSidebarTokens` and `resolveTopBarTokens` — the rail's and the app bar's tokens, resolved once for both hosts (sc-6289).** The footer strip got a shared resolver in 1.71.0; the two chrome parts beside it did not, so their defaults lived inline in the web Player and again in the compiler — and had drifted. An unset `sidebar.backgroundColor` painted the app background in the Expo export where the Player painted it white, so a dark app shipped a dark drawer beside a white rail; an unset `topBar.textColor` painted the app name slate in the export where the Player has always used the brand colour.
 
-Both resolvers now own their defaults, which are what the web Player renders, so the export follows the appearance the author approved in the Studio rather than the other way round. Unlike `resolveFooterTokens`, the colours are never `null` — a default that lives in the resolver cannot drift, and one that lived in each host already had. `borderColor` stays nullable: the colour is the divider's switch.
+Both resolvers now own their defaults, which at this version are what the web Player renders, so the export follows the appearance the author approved in the Studio rather than the other way round. (**Superseded in 1.93.0** for `backgroundColor` alone: the shared default became the page's own colour, moving both hosts rather than only the export.) Unlike `resolveFooterTokens`, the colours are never `null` — a default that lives in the resolver cannot drift, and one that lived in each host already had. `borderColor` stays nullable: the colour is the divider's switch.
 
 The top bar resolves **two** text colours. An unthemed bar paints its icons slate and its app name in the brand colour, and React Navigation's single `headerTintColor` cannot say both — so `tintColor` and `titleColor` are separate, and an authored `topBar.textColor` drives both. `show` is deliberately not among them: it depends on the menu type rather than the theme, and REQ-THEME-14 makes it a no-op on native.
 

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,
@@ -3568,7 +3580,30 @@ const CONTRACT = deepFreeze({
   // 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",
+  // 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.
+  // 1.93.0: BEHAVIOUR (sc-6596) -- `resolveSidebarTokens` and
+  //    `resolveTopBarTokens` resolve an UNSET `backgroundColor` to the page's
+  //    own surface instead of a flat `#ffffff`. No signature or field changed;
+  //    what a host RENDERS for an unset chrome surface did. 1.84.0 converged
+  //    the two hosts' separately-written defaults onto the Player's white,
+  //    which fixed the drift and kept the wrong value: a themed app got a dark
+  //    page and bright white chrome on both hosts. The surface now comes from
+  //    `chromeSurface`, which shares its chain with the `attached` tab's
+  //    `pageSurface` and differs in exactly one rule: a gradient contributes
+  //    its start colour to both, but chrome reads a translucent app background
+  //    at FULL STRENGTH (trimmed to its opaque base, REQ-THEME-17) where a tab
+  //    JOINED to the page refuses it. An app that colours its rail or bar
+  //    explicitly is untouched; an app that themed NOTHING moves from
+  //    `#ffffff` to the `#f8fafc` its page already was.
+  version: "1.93.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -3585,6 +3620,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,
@@ -3568,7 +3580,30 @@ const CONTRACT = deepFreeze({
   // 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",
+  // 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.
+  // 1.93.0: BEHAVIOUR (sc-6596) -- `resolveSidebarTokens` and
+  //    `resolveTopBarTokens` resolve an UNSET `backgroundColor` to the page's
+  //    own surface instead of a flat `#ffffff`. No signature or field changed;
+  //    what a host RENDERS for an unset chrome surface did. 1.84.0 converged
+  //    the two hosts' separately-written defaults onto the Player's white,
+  //    which fixed the drift and kept the wrong value: a themed app got a dark
+  //    page and bright white chrome on both hosts. The surface now comes from
+  //    `chromeSurface`, which shares its chain with the `attached` tab's
+  //    `pageSurface` and differs in exactly one rule: a gradient contributes
+  //    its start colour to both, but chrome reads a translucent app background
+  //    at FULL STRENGTH (trimmed to its opaque base, REQ-THEME-17) where a tab
+  //    JOINED to the page refuses it. An app that colours its rail or bar
+  //    explicitly is untouched; an app that themed NOTHING moves from
+  //    `#ffffff` to the `#f8fafc` its page already was.
+  version: "1.93.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -3585,6 +3620,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/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;
 }
 
 /**
@@ -213,7 +219,10 @@ export interface SidebarTokens {
 /**
  * Resolves the sidebar rail's tokens from a whole `theme_config`. Every default
  * is what the web Player renders, so the export follows the Player rather than
- * the other way round.
+ * the other way round — except `backgroundColor`, which sc-6596 moved on BOTH
+ * hosts: an unset surface takes the colour the PAGE shows (the app's
+ * `backgroundColor`, or a fully configured `backgroundGradient`'s start colour,
+ * read at full strength) rather than a flat white.
  */
 export function resolveSidebarTokens(theme: unknown): SidebarTokens;
 
@@ -226,12 +235,44 @@ 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;
 }
 
 /**
  * Resolves the top app bar's tokens from a whole `theme_config`. `show` is not
  * among them: it depends on the menu type, not the theme, and is a no-op on
- * native.
+ * native. An unset `backgroundColor` follows the PAGE's colour, as the rail's
+ * does (sc-6596).
  */
 export function resolveTopBarTokens(theme: unknown): TopBarTokens;
 

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 };
 }
 
 /**
@@ -129,14 +143,112 @@ function resolveFooterTokens(theme) {
 // Every default is what the WEB Player renders today, so the Player does not
 // move and the export converges onto it. That is the direction the footer was
 // converged in too (compiler.service's footerBg defaults to the web's #ffffff).
+//
+// sc-6596 — the ONE exception, and it moves BOTH hosts: an unset rail or bar
+// takes the page's own colour. Converging on the Player's white left a themed
+// app's chrome contradicting its own theme.
 
 const DEFAULT_PRIMARY_COLOR = "#3b82f6";
-// The web rail's and app bar's `bg-white`.
-const DEFAULT_CHROME_SURFACE = "#ffffff";
 // The web nav item's `text-slate-600`.
 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";
+
+// A gradient shows only when BOTH stops are a flat hex — the rule both hosts'
+// page readers apply (`normaliseThemeGradient`, mirrored frontend/backend). A
+// half-configured or alpha-carrying gradient paints NOTHING, so reading its
+// `from` would hand the chrome a colour the page never shows.
+function gradientStart(config) {
+  const gradient = isPlainObject(config.backgroundGradient)
+    ? config.backgroundGradient
+    : null;
+  if (!gradient) return null;
+  const from = flatHexOrNull(gradient.from);
+  return from && flatHexOrNull(gradient.to) ? from : null;
+}
+
+// The colour the PAGE actually shows. A gradient owns the visible background,
+// so its START colour wins — the flat colour shows nowhere under one.
+//
+// `alphaRule` is the only thing the two callers differ by, and they differ for a
+// reason: a tab JOINED to the page refuses a translucent page rather than
+// approximate it, while chrome BESIDE the page follows what the page renders —
+// the alpha-trimmed value both hosts paint (REQ-THEME-17). Sharing the chain is
+// what keeps them from drifting on everything else.
+function pageColor(config, alphaRule) {
+  return hexOr(
+    gradientStart(config) || alphaRule(config.backgroundColor),
+    DEFAULT_APP_SURFACE,
+  );
+}
+
+// An `attached` tab: opaque, or the bar shows through the page it joins.
+function pageSurface(config) {
+  return pageColor(config, opaqueOr);
+}
+
+// sc-6596: what an UNSET rail or bar is painted. Read at full strength — an
+// alpha on the bottom layer would mean nothing to chrome above it.
+function chromeSurface(config) {
+  return pageColor(config, flattenedHex);
+}
+
+// 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;
+}
+
+// A gradient stop as the page readers admit one: flat hex, never alpha.
+function flatHexOrNull(value) {
+  return isHexColor(value) && value.length !== 9 ? value : null;
+}
+
+// `#RRGGBBAA` trimmed to its opaque base rather than refused — what both hosts'
+// page readers paint (web `opaqueColor`, compiler `opaqueHex`).
+function flattenedHex(value) {
+  if (!isHexColor(value)) return null;
+  return value.length === 9 ? value.slice(0, 7) : value;
+}
 
 // The contract's own guard, which already admits the 8-digit form a look uses
 // to float a translucent rail (#RRGGBBAA).
@@ -156,7 +268,9 @@ function brandPrimary(config) {
  * The sidebar rail's surface, labels, active item and opt-in divider.
  *
  * @param {unknown} theme — the whole `theme_config`; `primaryColor` is read
- *   because an unset active colour resolves to the brand.
+ *   because an unset active colour resolves to the brand, and the app's
+ *   `backgroundColor`/`backgroundGradient` because an unset surface resolves to
+ *   the page's (sc-6596).
  * @returns {{ backgroundColor: string, textColor: string, activeColor: string,
  *   activeStyle: string, borderColor: string|null, borderWidth: number|null }}
  */
@@ -165,7 +279,7 @@ function resolveSidebarTokens(theme) {
   const sidebar = isPlainObject(config.sidebar) ? config.sidebar : {};
   const borderColor = hexOrNull(sidebar.borderColor);
   return {
-    backgroundColor: hexOr(sidebar.backgroundColor, DEFAULT_CHROME_SURFACE),
+    backgroundColor: hexOr(sidebar.backgroundColor, chromeSurface(config)),
     textColor: hexOr(sidebar.textColor, DEFAULT_CHROME_TEXT),
     activeColor: hexOr(sidebar.activeColor, brandPrimary(config)),
     activeStyle: sidebar.activeStyle === "accent" ? "accent" : "filled",
@@ -187,7 +301,9 @@ function resolveSidebarTokens(theme) {
  * `show` is deliberately absent: it depends on the menu TYPE, not the theme,
  * and REQ-THEME-14 makes it a no-op on native — so it is not a shared token.
  *
- * @param {unknown} theme — the whole `theme_config`.
+ * @param {unknown} theme — the whole `theme_config`; the app's
+ *   `backgroundColor`/`backgroundGradient` are read because an unset surface
+ *   resolves to the page's, as an `attached` tab's already did (sc-6596).
  * @returns {{ backgroundColor: string, tintColor: string, titleColor: string,
  *   borderColor: string|null, borderWidth: number|null }}
  */
@@ -198,11 +314,68 @@ function resolveTopBarTokens(theme) {
   // An explicit colour drives BOTH slots; only the unset case splits.
   const authored = hexOrNull(topBar.textColor);
   return {
-    backgroundColor: hexOr(topBar.backgroundColor, DEFAULT_CHROME_SURFACE),
+    backgroundColor: hexOr(topBar.backgroundColor, chromeSurface(config)),
     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 };
 }
 
 /**
@@ -120,14 +134,112 @@ export function resolveFooterTokens(theme) {
 // Every default is what the WEB Player renders today, so the Player does not
 // move and the export converges onto it. That is the direction the footer was
 // converged in too (compiler.service's footerBg defaults to the web's #ffffff).
+//
+// sc-6596 — the ONE exception, and it moves BOTH hosts: an unset rail or bar
+// takes the page's own colour. Converging on the Player's white left a themed
+// app's chrome contradicting its own theme.
 
 const DEFAULT_PRIMARY_COLOR = "#3b82f6";
-// The web rail's and app bar's `bg-white`.
-const DEFAULT_CHROME_SURFACE = "#ffffff";
 // The web nav item's `text-slate-600`.
 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";
+
+// A gradient shows only when BOTH stops are a flat hex — the rule both hosts'
+// page readers apply (`normaliseThemeGradient`, mirrored frontend/backend). A
+// half-configured or alpha-carrying gradient paints NOTHING, so reading its
+// `from` would hand the chrome a colour the page never shows.
+function gradientStart(config) {
+  const gradient = isPlainObject(config.backgroundGradient)
+    ? config.backgroundGradient
+    : null;
+  if (!gradient) return null;
+  const from = flatHexOrNull(gradient.from);
+  return from && flatHexOrNull(gradient.to) ? from : null;
+}
+
+// The colour the PAGE actually shows. A gradient owns the visible background,
+// so its START colour wins — the flat colour shows nowhere under one.
+//
+// `alphaRule` is the only thing the two callers differ by, and they differ for a
+// reason: a tab JOINED to the page refuses a translucent page rather than
+// approximate it, while chrome BESIDE the page follows what the page renders —
+// the alpha-trimmed value both hosts paint (REQ-THEME-17). Sharing the chain is
+// what keeps them from drifting on everything else.
+function pageColor(config, alphaRule) {
+  return hexOr(
+    gradientStart(config) || alphaRule(config.backgroundColor),
+    DEFAULT_APP_SURFACE,
+  );
+}
+
+// An `attached` tab: opaque, or the bar shows through the page it joins.
+function pageSurface(config) {
+  return pageColor(config, opaqueOr);
+}
+
+// sc-6596: what an UNSET rail or bar is painted. Read at full strength — an
+// alpha on the bottom layer would mean nothing to chrome above it.
+function chromeSurface(config) {
+  return pageColor(config, flattenedHex);
+}
+
+// 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;
+}
+
+// A gradient stop as the page readers admit one: flat hex, never alpha.
+function flatHexOrNull(value) {
+  return isHexColor(value) && value.length !== 9 ? value : null;
+}
+
+// `#RRGGBBAA` trimmed to its opaque base rather than refused — what both hosts'
+// page readers paint (web `opaqueColor`, compiler `opaqueHex`).
+function flattenedHex(value) {
+  if (!isHexColor(value)) return null;
+  return value.length === 9 ? value.slice(0, 7) : value;
+}
 
 // The contract's own guard, which already admits the 8-digit form a look uses
 // to float a translucent rail (#RRGGBBAA).
@@ -147,7 +259,9 @@ function brandPrimary(config) {
  * The sidebar rail's surface, labels, active item and opt-in divider.
  *
  * @param {unknown} theme — the whole `theme_config`; `primaryColor` is read
- *   because an unset active colour resolves to the brand.
+ *   because an unset active colour resolves to the brand, and the app's
+ *   `backgroundColor`/`backgroundGradient` because an unset surface resolves to
+ *   the page's (sc-6596).
  * @returns {{ backgroundColor: string, textColor: string, activeColor: string,
  *   activeStyle: string, borderColor: string|null, borderWidth: number|null }}
  */
@@ -156,7 +270,7 @@ export function resolveSidebarTokens(theme) {
   const sidebar = isPlainObject(config.sidebar) ? config.sidebar : {};
   const borderColor = hexOrNull(sidebar.borderColor);
   return {
-    backgroundColor: hexOr(sidebar.backgroundColor, DEFAULT_CHROME_SURFACE),
+    backgroundColor: hexOr(sidebar.backgroundColor, chromeSurface(config)),
     textColor: hexOr(sidebar.textColor, DEFAULT_CHROME_TEXT),
     activeColor: hexOr(sidebar.activeColor, brandPrimary(config)),
     activeStyle: sidebar.activeStyle === "accent" ? "accent" : "filled",
@@ -178,7 +292,9 @@ export function resolveSidebarTokens(theme) {
  * `show` is deliberately absent: it depends on the menu TYPE, not the theme,
  * and REQ-THEME-14 makes it a no-op on native — so it is not a shared token.
  *
- * @param {unknown} theme — the whole `theme_config`.
+ * @param {unknown} theme — the whole `theme_config`; the app's
+ *   `backgroundColor`/`backgroundGradient` are read because an unset surface
+ *   resolves to the page's, as an `attached` tab's already did (sc-6596).
  * @returns {{ backgroundColor: string, tintColor: string, titleColor: string,
  *   borderColor: string|null, borderWidth: number|null }}
  */
@@ -189,11 +305,68 @@ export function resolveTopBarTokens(theme) {
   // An explicit colour drives BOTH slots; only the unset case splits.
   const authored = hexOrNull(topBar.textColor);
   return {
-    backgroundColor: hexOr(topBar.backgroundColor, DEFAULT_CHROME_SURFACE),
+    backgroundColor: hexOr(topBar.backgroundColor, chromeSurface(config)),
     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.119.0",
+  "version": "0.121.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",