@colixsystems/widget-sdk 0.120.0 → 0.121.0

package/README.md

@@ -72,6 +72,18 @@ 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`.
@@ -257,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

@@ -3589,7 +3589,21 @@ const CONTRACT = deepFreeze({
   //    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",
+  // 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,

package/dist/contract.js

@@ -3589,7 +3589,21 @@ const CONTRACT = deepFreeze({
   //    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",
+  // 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,

package/dist/host.d.ts

@@ -219,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;
 
@@ -268,7 +271,8 @@ export interface TopBarTokens {
 /**
  * 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

@@ -143,10 +143,12 @@ 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`.
@@ -155,22 +157,43 @@ const DEFAULT_TOP_BAR_TINT = "#334155";
 // (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) {
+// 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;
-  const from = gradient ? opaqueOr(gradient.from) : null;
-  return hexOr(from || opaqueOr(config.backgroundColor), DEFAULT_APP_SURFACE);
+  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
@@ -215,6 +238,18 @@ function opaqueOr(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).
 function hexOrNull(value) {
@@ -233,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 }}
  */
@@ -242,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",
@@ -264,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 }}
  */
@@ -275,7 +314,7 @@ 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

package/dist/navigation.js

@@ -134,10 +134,12 @@ 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`.
@@ -146,22 +148,43 @@ const DEFAULT_TOP_BAR_TINT = "#334155";
 // (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) {
+// 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;
-  const from = gradient ? opaqueOr(gradient.from) : null;
-  return hexOr(from || opaqueOr(config.backgroundColor), DEFAULT_APP_SURFACE);
+  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
@@ -206,6 +229,18 @@ function opaqueOr(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).
 function hexOrNull(value) {
@@ -224,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 }}
  */
@@ -233,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",
@@ -255,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 }}
  */
@@ -266,7 +305,7 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.120.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",