@colixsystems/widget-sdk 0.119.0 → 0.120.0

package/README.md

@@ -72,6 +72,21 @@ 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.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:

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,16 @@ 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.
+  version: "1.92.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -3585,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,
@@ -3568,7 +3580,16 @@ 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.
+  version: "1.92.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -3585,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/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/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.119.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",