@colixsystems/widget-sdk 0.143.0 → 0.145.0

package/README.md

@@ -71,10 +71,28 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.143.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.145.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.143.0 (contract 1.111.0)
+### What's new in 0.145.0 (contract 1.113.0)
 
+**The app's bottom navigation bar gets its own active-tab look — `resolveFooterTokens` gains three (sc-7951).** `theme_config.footer` already carried an `activeStyle`, but no Studio control ever wrote it, so the SIDEBAR's active-item style silently decided the bottom bar too: an author who accented the rail accented the tab bar, with no way to separate them. The bar was also under-authorable — `"filled"` *bundled* the active tab's surface with its label, pinning the surface to `activeColor` and the label to a hard-coded white, so no author could paint a surface of their own.
+
+- **`footer.activeStyle` is now the bar's**, reachable from the Design page's Bottom navigation bar panel. Unset it still falls back to `sidebar.activeStyle`, so every existing workspace renders exactly as before.
+- **`footer.tabActiveBackgroundColor`** — the active tab's surface. New, and it falls back to **nothing**: a vertical rail item has no tab surface, so unlike the colours this inherits from no one.
+- **`footer.tabLayout`** — `"inline"` (the row the bar has always drawn) or `"stacked"`, the glyph above its label. Also footer-only.
+
+`resolveFooterTokens` now returns the active tab **already decided** — `activeSurface` (hex or `null`) and `activeTint` — so neither host re-derives the back-compat pairing. `"filled"` with nothing named is still the active colour behind a white label; **naming a surface unbundles the two**, and the label goes back to `activeColor` so the author owns both halves. `activeColor` is resolved in the helper now rather than by each caller, so it is a `string` rather than raw-or-null — `FooterTokens.activeColor` narrows accordingly. The inherited colours are also hex-guarded on the way **out**, not only in: the export already refused a malformed stored value while the Player handed it to a style object.
+
+It also settles a divergence the bar carried: under `"accent"` the web Player drew a **left** border (the rail's rule on a horizontal tab) and the export drew no edge at all. Both now mark the edge **facing the page** — a bottom tab's top — reserved transparent at every tab's width so marking one cannot shift the row. A tab is also the same 6px-rounded chip on both hosts, where native used to be square.
+
+### What's new in 0.144.0 (contract 1.112.0)
+
+**The global mobile quick bar is retired — `quickBarMaxItems` and `quickBarCap` leave the contract (sc-7753, REQ-NAV-STRUCTURE / REQ-NAV-LOCAL).** The quick bar was a second global menu bolted to the sidebar: its own per-page flag, its own five-item cap, its own strip on the app's bottom edge. Since sc-7695 a page can carry a bottom navigation bar of its own drawing a saved menu, which is the same strip with an author-chosen list behind it — so the global one was a duplicate shape.
+
+- `CONTRACT.themeMenuTypes.sidebar` is now `{ name, summary, maxItems }`. `menuItemCap` is unchanged; `quickBarCap` is **removed** — a page's bottom bar draws the menu the author composed, so there is no global number to state.
+- `resolveFooterTokens` stays exactly as it is. It was never the quick bar's alone: it is the BOTTOM EDGE's token set, and the page's own bottom bar reads it, so a workspace's bottom-edge colours survive the retirement untouched.
+- The sc-7753 backfill turns each workspace's quick-bar pages into a saved menu and points the pages that drew the strip at it BEFORE this ships, so no destination is lost.
+- Host-integration surface only; no author-facing hook, prop or manifest field changed. `CONTRACT.version` → `1.112.0`.
 **A widget can name the screen it is on — `useScreenTitle(title)` + the optional `ctx.screen` slice (sc-7955).** The app header now shows the PAGE title beside the back control on a sub-page, instead of repeating the app brand on every screen. The page's own name is the default, but a page is often about one record, and only the widget has it:
 
 ```js
@@ -115,8 +133,8 @@ if (triggeredBy && triggeredBy.type === "app_user") {
 
 **The app's global navigation is the sidebar alone — `top-bar` and `bottom-tabs` leave `CONTRACT.themeMenuTypes` (sc-7352, REQ-NAV-STRUCTURE).** A top bar is now a PAGE's local bar drawing a saved menu (REQ-NAV-LOCAL, sc-7103): the same tab row the `top-bar` shape used to draw, themed by the same `topBar` tokens (`resolveTopBarTokens` is unchanged), worn by one page under the sidebar. Two "top bars" competing for one word and one token set was the reason.
 
-- `normaliseNavigation` resolves a stored `top-bar` or `bottom-tabs` to `sidebar`, so a host never has to guard the value. `menuItemCap` / `quickBarCap` keep their signatures (`quickBarCap("sidebar")` is still 5).
-- The global menu never lived in the shape (it is the pages' `show_in_menu` flags), so a workspace that stored a retired shape already draws the sidebar with the same menu. The sc-7352 backfill deletes the stored key BEFORE the shapes disappear; a bottom-tabs app's phone strip becomes the sidebar's quick bar.
+- `normaliseNavigation` resolves a stored `top-bar` or `bottom-tabs` to `sidebar`, so a host never has to guard the value. `menuItemCap` / `quickBarCap` keep their signatures (`quickBarCap("sidebar")` is still 5). *(`quickBarCap` was removed in 0.142.0.)*
+- The global menu never lived in the shape (it is the pages' `show_in_menu` flags), so a workspace that stored a retired shape already draws the sidebar with the same menu. The sc-7352 backfill deletes the stored key BEFORE the shapes disappear; a bottom-tabs app's phone strip becomes the sidebar's quick bar. *(That strip was itself retired in 0.142.0.)*
 - Host-integration surface only; no author-facing hook, prop or manifest field changed. `CONTRACT.version` → `1.109.0`.
 
 ### What's new in 0.140.0 (contract 1.108.0)

package/dist/contract.cjs

@@ -220,16 +220,13 @@ const THEME_WIDGET_STYLES = Object.freeze({
 // REQ-NAV-STRUCTURE (sc-7352): the app's GLOBAL navigation has exactly one
 // shape, the sidebar. A top bar is a PAGE's local bar drawing a saved menu
 // (REQ-NAV-LOCAL), themed by the `topBar` tokens, never an app-wide menu shape.
-// `maxItems` is the menu cap (none for a rail); `quickBarMaxItems` caps the
-// SECONDARY mobile quick bar, which may drop a page because the rail and the
-// drawer still list every one.
+// `maxItems` is the menu cap (none for a rail).
 const THEME_MENU_TYPES = Object.freeze({
   sidebar: Object.freeze({
     name: "Sidebar",
     summary:
-      "A persistent left rail on desktop; a hamburger drawer plus the optional bottom quick bar on mobile.",
+      "A persistent left rail on desktop; a hamburger drawer on mobile.",
     maxItems: null,
-    quickBarMaxItems: 5,
   }),
 });
 const THEME_SPACING_SCALE = Object.freeze({
@@ -4036,7 +4033,28 @@ const CONTRACT = deepFreeze({
   //    integration identity; this describes the caller, it does not grant
   //    anything. The same commit adds `properties` to this list, which the
   //    action-sdk copy had carried since 1.50.0 while this one had not.
-  version: "1.111.0",
+  // 1.112.0: BREAKING on the pre-1.0 channel (sc-7753) — `themeMenuTypes`
+  //    loses `quickBarMaxItems` and the `quickBarCap` host export goes with
+  //    it. The app's global mobile quick bar is retired: it was a SELECTION
+  //    over the global menu, and the rail and drawer list every menu page
+  //    regardless, so nothing was reachable only through it. The bottom edge
+  //    belongs to a PAGE's own bottom navigation bar (`local_nav = BOTTOM_BAR`,
+  //    REQ-NAV-LOCAL), chosen per page. `resolveFooterTokens` is unchanged —
+  //    it is the bottom edge's token set and the surviving bar reads it.
+  // 1.113.0: additive (sc-7951) — `resolveFooterTokens` gains the bottom
+  //    bar's OWN three. `activeStyle` was on the wire but had no Studio
+  //    control, so the SIDEBAR's decided the strip too; `tabActiveBackgroundColor`
+  //    (the active tab's surface) and `tabLayout` (`inline` | `stacked`) are new
+  //    and fall back to nothing, because a vertical rail item has neither. The
+  //    resolver now also returns the active tab already DECIDED — `activeSurface`
+  //    and `activeTint` — so neither host re-derives the back-compat pairing
+  //    ("filled" with nothing named is the active colour behind a white label);
+  //    naming a surface unbundles the two. `activeColor` is resolved here now
+  //    rather than by each caller, so it is a string rather than raw-or-null,
+  //    and the inherited colours are hex-guarded on the way out as well as in.
+  //    Every colour still falls back to the sidebar's: an untouched workspace is
+  //    unchanged.
+  version: "1.113.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -220,16 +220,13 @@ const THEME_WIDGET_STYLES = Object.freeze({
 // REQ-NAV-STRUCTURE (sc-7352): the app's GLOBAL navigation has exactly one
 // shape, the sidebar. A top bar is a PAGE's local bar drawing a saved menu
 // (REQ-NAV-LOCAL), themed by the `topBar` tokens, never an app-wide menu shape.
-// `maxItems` is the menu cap (none for a rail); `quickBarMaxItems` caps the
-// SECONDARY mobile quick bar, which may drop a page because the rail and the
-// drawer still list every one.
+// `maxItems` is the menu cap (none for a rail).
 const THEME_MENU_TYPES = Object.freeze({
   sidebar: Object.freeze({
     name: "Sidebar",
     summary:
-      "A persistent left rail on desktop; a hamburger drawer plus the optional bottom quick bar on mobile.",
+      "A persistent left rail on desktop; a hamburger drawer on mobile.",
     maxItems: null,
-    quickBarMaxItems: 5,
   }),
 });
 const THEME_SPACING_SCALE = Object.freeze({
@@ -4032,7 +4029,28 @@ const CONTRACT = deepFreeze({
   //    integration identity; this describes the caller, it does not grant
   //    anything. The same commit adds `properties` to this list, which the
   //    action-sdk copy had carried since 1.50.0 while this one had not.
-  version: "1.111.0",
+  // 1.112.0: BREAKING on the pre-1.0 channel (sc-7753) — `themeMenuTypes`
+  //    loses `quickBarMaxItems` and the `quickBarCap` host export goes with
+  //    it. The app's global mobile quick bar is retired: it was a SELECTION
+  //    over the global menu, and the rail and drawer list every menu page
+  //    regardless, so nothing was reachable only through it. The bottom edge
+  //    belongs to a PAGE's own bottom navigation bar (`local_nav = BOTTOM_BAR`,
+  //    REQ-NAV-LOCAL), chosen per page. `resolveFooterTokens` is unchanged —
+  //    it is the bottom edge's token set and the surviving bar reads it.
+  // 1.113.0: additive (sc-7951) — `resolveFooterTokens` gains the bottom
+  //    bar's OWN three. `activeStyle` was on the wire but had no Studio
+  //    control, so the SIDEBAR's decided the strip too; `tabActiveBackgroundColor`
+  //    (the active tab's surface) and `tabLayout` (`inline` | `stacked`) are new
+  //    and fall back to nothing, because a vertical rail item has neither. The
+  //    resolver now also returns the active tab already DECIDED — `activeSurface`
+  //    and `activeTint` — so neither host re-derives the back-compat pairing
+  //    ("filled" with nothing named is the active colour behind a white label);
+  //    naming a surface unbundles the two. `activeColor` is resolved here now
+  //    rather than by each caller, so it is a string rather than raw-or-null,
+  //    and the inherited colours are hex-guarded on the way out as well as in.
+  //    Every colour still falls back to the sidebar's: an untouched workspace is
+  //    unchanged.
+  version: "1.113.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/host.d.ts

@@ -173,28 +173,35 @@ export function normaliseNavigation(navigation: unknown): ResolvedNavigation;
  */
 export function menuItemCap(menuType: string): number | null;
 
-/**
- * How many pages the SECONDARY mobile quick bar draws, or `null` where the shape
- * draws none (only `sidebar` has one). Unlike `menuItemCap` this cap MAY drop a
- * page: the rail and drawer still list every menu page.
- */
-export function quickBarCap(menuType: string): number | null;
-
-/** The footer strip's resolved tokens. A `null` colour means the host keeps its
- *  own default; a `null` `borderColor` means no divider is drawn at all. */
+/** The app's bottom edge — a page's own bottom navigation bar. A `null` colour
+ *  means the host keeps its own default; a `null` `borderColor` means no
+ *  divider is drawn at all. */
 export interface FooterTokens {
   backgroundColor: string | null;
   textColor: string | null;
-  activeColor: string | null;
+  /** Never `null`: an unset value resolves to the brand primary here rather
+   *  than in each host, which is what lets the two active-tab fields below be
+   *  resolved here at all. */
+  activeColor: string;
   borderColor: string | null;
   borderWidth: number | null;
   activeStyle: "filled" | "accent";
+  /** Whether a tab's glyph sits beside its label or above it (sc-7951). */
+  tabLayout: "inline" | "stacked";
+  /** The active tab's surface, or `null` for none. Under "filled" with nothing
+   *  named this is the active colour — what both hosts shipped. */
+  activeSurface: string | null;
+  /** The active tab's label and glyph. White only under an unnamed "filled"
+   *  surface, which is the pairing both hosts hard-coded. */
+  activeTint: string;
 }
 
 /**
- * Resolves the footer strip's tokens from a whole `theme_config`. Every field
- * falls back to the sidebar's, so a workspace that never opens the Footer panel
- * renders exactly as it did before the block existed.
+ * Resolves the footer strip's tokens from a whole `theme_config`. Every colour
+ * falls back to the sidebar's, so a workspace that never opens the Bottom
+ * navigation bar panel renders exactly as it did before the block existed.
+ * `tabActiveBackgroundColor` and `tabLayout` are the strip's own and inherit
+ * from nothing — a vertical rail item has neither.
  */
 export function resolveFooterTokens(theme: unknown): FooterTokens;
 

package/dist/host.js

@@ -55,18 +55,17 @@ export {
 // REQ-NAV-STRUCTURE: the navigation resolver both hosts draw their chrome from.
 // `normaliseNavigation` turns a stored `theme_config.navigation` block into the
 // resolved `{ menuType }` — always `sidebar` since sc-7352 retired the other
-// shapes, so a stored value never needs guarding; `menuItemCap` / `quickBarCap`
-// state the caps. One implementation, so the chrome cannot mean one thing in
-// the Player and another in the Expo export. `resolveFooterTokens` is the quick
-// bar's own token set, falling back to the sidebar's so an untouched workspace
-// keeps the appearance it has.
+// shapes, so a stored value never needs guarding; `menuItemCap` states the cap.
+// One implementation, so the chrome cannot mean one thing in the Player and
+// another in the Expo export. `resolveFooterTokens` is the BOTTOM EDGE's token
+// set — a page's own bottom navigation bar (REQ-NAV-LOCAL) — falling back to
+// the sidebar's so an untouched workspace keeps the appearance it has.
 // REQ-THEME-14: `resolveSidebarTokens` and `resolveTopBarTokens` are the same
 // idea for the rail and the app bar, whose defaults used to live inline in each
 // host and had already drifted apart.
 export {
   normaliseNavigation,
   menuItemCap,
-  quickBarCap,
   resolveFooterTokens,
   resolveSidebarTokens,
   resolveTopBarTokens,

package/dist/navigation.cjs

@@ -60,7 +60,7 @@ function normaliseNavigation(navigation) {
 
 /**
  * How many MENU pages the chrome may draw at once, or `null` for no cap. The
- * sidebar has none. Contrast `quickBarCap` below.
+ * sidebar has none.
  *
  * @param {string} menuType — a resolved menu type.
  * @returns {number|null}
@@ -70,68 +70,75 @@ function menuItemCap(menuType) {
   return entry ? entry.maxItems : null;
 }
 
-/**
- * How many pages the SECONDARY mobile quick bar draws, or `null` where that
- * shape draws none. Only the `sidebar` shape has one.
- *
- * This cap MAY drop a page, and that is the difference from `menuItemCap`: the
- * rail and the drawer still list every menu page, so the bar is a shortcut
- * rather than the menu. It lived as a constant on one host and a literal on the
- * other before this, which is exactly how the two would have drifted.
- *
- * @param {string} menuType — a resolved menu type.
- * @returns {number|null}
- */
-function quickBarCap(menuType) {
-  const entry = CONTRACT.themeMenuTypes[menuType];
-  return entry ? entry.quickBarMaxItems : null;
-}
-
-// The strip's surface was hard-coded white on BOTH hosts and its items read the
-// sidebar's tokens. `footer` gives the quick bar tokens of its own.
+// REQ-NAV-LOCAL: the app's BOTTOM EDGE — the tokens a page's own bottom
+// navigation bar is drawn from. Every colour falls back to the sidebar's, so a
+// workspace that never opens the panel keeps the appearance it has.
 //
-// Every colour falls back to the sidebar's, so a workspace that never opens the
-// panel keeps exactly the appearance it has today; only an explicit `footer`
-// value moves anything.
+// sc-7753: the global quick bar these tokens were introduced for is retired;
+// the bar that reads them now is the page's own (`local_nav = BOTTOM_BAR`).
 //
-// sc-7695: this block is the BOTTOM EDGE's, not the quick bar's alone. A page's
-// own bottom bar (REQ-NAV-LOCAL) is the same strip worn by one page and reads
-// exactly these values — the Design panel that edits them is named for that
-// bar, since the quick bar is on its way out (sc-7753) and the look outlives
-// it. No key is the bar's alone: two strips, one look.
+// sc-7951: three of the keys ARE that bar's own — the active-item style it
+// used to borrow from the rail for want of a control, the active tab's
+// surface, and whether the glyph sits beside the label or above it.
 function resolveFooterTokens(theme) {
   const config = isPlainObject(theme) ? theme : {};
   const footer = isPlainObject(config.footer) ? config.footer : {};
   const sidebar = isPlainObject(config.sidebar) ? config.sidebar : {};
-  const pick = (key) => footer[key] || sidebar[key] || null;
+  // Hex-guarded on the way out, not merely on the way in: `theme_config` is an
+  // opaque blob an operator can hand-edit, and the EXPORT already refused a
+  // malformed colour here while the Player passed it to a style object — so the
+  // guard is what stops the two hosts painting a stored junk value differently.
+  const pick = (key) => hexOrNull(footer[key]) || hexOrNull(sidebar[key]) || null;
   const borderColor = pick("borderColor");
+  // sc-7951: the rail's style is the FALLBACK now, not the only source. Unset
+  // still follows the rail, which is what keeps every shipped app where it is.
   const activeStyle = footer.activeStyle || sidebar.activeStyle;
+  const accent = activeStyle === "accent";
+  const activeColor = hexOr(pick("activeColor"), brandPrimary(config));
+  // Footer-only: a rail item is a full-width row with no tab surface to paint,
+  // so this inherits from nothing and unset means "no surface of its own".
+  const namedSurface = hexOrNull(footer.tabActiveBackgroundColor);
   return {
     backgroundColor: pick("backgroundColor"),
     textColor: pick("textColor"),
-    // Unlike the others this has no null state on either host: an unset active
-    // colour resolves to the brand primary, which the caller supplies.
-    activeColor: pick("activeColor"),
+    // Resolved here rather than by each caller, which is what lets the two
+    // active-tab fields below be resolved here too.
+    activeColor,
     // REQ-THEME-LOOK: the divider's COLOUR is its switch. Unset draws no line at
-    // all — which the native quick bar did not honour before this, ruling a
-    // hairline across a tinted strip that had asked for none.
+    // all — which the native strip did not honour before this, ruling a
+    // hairline across a tinted bar that had asked for none.
     borderColor,
     borderWidth: borderColor ? borderWidthOr(footer.borderWidth, sidebar.borderWidth) : null,
-    activeStyle: activeStyle === "accent" ? "accent" : "filled",
+    activeStyle: accent ? "accent" : "filled",
+    // sc-7951: bottom tabs are the only strip tall enough to stack the two, so
+    // the choice is the footer's alone.
+    tabLayout: footer.tabLayout === "stacked" ? "stacked" : "inline",
+    // sc-7951: the active tab's two halves, resolved HERE so neither host
+    // re-derives the back-compat rule. "filled" with nothing named is what both
+    // hosts shipped — the active colour as the fill, the label forced white —
+    // and that pairing is the only reason a marked tab's label is not simply
+    // the active colour. Naming a surface unbundles them: the surface is the
+    // author's and the label goes back to the active colour.
+    activeSurface: namedSurface || (accent ? null : activeColor),
+    activeTint: accent || namedSurface ? activeColor : FILLED_TAB_LABEL,
   };
 }
 
 // REQ-THEME-14 — the rail's and the app bar's tokens, resolved once for both
 // hosts.
 //
-// These return FULLY resolved values where `resolveFooterTokens` above returns
-// raw-or-null, and the difference is deliberate. The footer's two hosts happen
-// to agree on their separately-written defaults; the rail's and the bar's did
-// not. An unset `sidebar.backgroundColor` painted #ffffff on web and the app
+// These return FULLY resolved values where `resolveFooterTokens` above still
+// returns raw-or-null for its SURFACE, LABEL and DIVIDER colours, and the
+// difference is deliberate. The footer's two hosts happen to agree on their
+// separately-written defaults for those three (`#ffffff` / `#475569` / no
+// line); the rail's and the bar's did not. sc-7951 resolved the footer's active
+// tab — `activeColor`, `activeSurface`, `activeTint` — because a rule that
+// pairs a surface with a label cannot live in two hosts; the three above are
+// what remains of the old shape. An unset `sidebar.backgroundColor` painted #ffffff on web and the app
 // background in the export, and an unset `topBar.textColor` painted the brand
 // primary on web and slate-700 in the export. A default that lives in the
-// resolver cannot drift; one that lives in each host already had. The footer
-// wants this same shape next — the same fix, not yet applied.
+// resolver cannot drift; one that lives in each host already had. The footer's
+// three remaining raw colours want this same shape next.
 //
 // 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
@@ -149,6 +156,9 @@ 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";
+// The literal both hosts hard-coded behind an unnamed "filled" surface, before
+// resolveFooterTokens decided the pairing once (sc-7951).
+const FILLED_TAB_LABEL = "#ffffff";
 
 // A gradient shows only when BOTH stops are a flat hex — the rule both hosts'
 // page readers apply (`normaliseThemeGradient`, mirrored frontend/backend). A
@@ -362,4 +372,4 @@ function borderWidthOr(...values) {
   return 1;
 }
 
-module.exports = { normaliseNavigation, menuItemCap, quickBarCap, resolveFooterTokens, resolveSidebarTokens, resolveTopBarTokens };
+module.exports = { normaliseNavigation, menuItemCap, resolveFooterTokens, resolveSidebarTokens, resolveTopBarTokens };

package/dist/navigation.js

@@ -51,7 +51,7 @@ export function normaliseNavigation(navigation) {
 
 /**
  * How many MENU pages the chrome may draw at once, or `null` for no cap. The
- * sidebar has none. Contrast `quickBarCap` below.
+ * sidebar has none.
  *
  * @param {string} menuType — a resolved menu type.
  * @returns {number|null}
@@ -61,68 +61,75 @@ export function menuItemCap(menuType) {
   return entry ? entry.maxItems : null;
 }
 
-/**
- * How many pages the SECONDARY mobile quick bar draws, or `null` where that
- * shape draws none. Only the `sidebar` shape has one.
- *
- * This cap MAY drop a page, and that is the difference from `menuItemCap`: the
- * rail and the drawer still list every menu page, so the bar is a shortcut
- * rather than the menu. It lived as a constant on one host and a literal on the
- * other before this, which is exactly how the two would have drifted.
- *
- * @param {string} menuType — a resolved menu type.
- * @returns {number|null}
- */
-export function quickBarCap(menuType) {
-  const entry = CONTRACT.themeMenuTypes[menuType];
-  return entry ? entry.quickBarMaxItems : null;
-}
-
-// The strip's surface was hard-coded white on BOTH hosts and its items read the
-// sidebar's tokens. `footer` gives the quick bar tokens of its own.
+// REQ-NAV-LOCAL: the app's BOTTOM EDGE — the tokens a page's own bottom
+// navigation bar is drawn from. Every colour falls back to the sidebar's, so a
+// workspace that never opens the panel keeps the appearance it has.
 //
-// Every colour falls back to the sidebar's, so a workspace that never opens the
-// panel keeps exactly the appearance it has today; only an explicit `footer`
-// value moves anything.
+// sc-7753: the global quick bar these tokens were introduced for is retired;
+// the bar that reads them now is the page's own (`local_nav = BOTTOM_BAR`).
 //
-// sc-7695: this block is the BOTTOM EDGE's, not the quick bar's alone. A page's
-// own bottom bar (REQ-NAV-LOCAL) is the same strip worn by one page and reads
-// exactly these values — the Design panel that edits them is named for that
-// bar, since the quick bar is on its way out (sc-7753) and the look outlives
-// it. No key is the bar's alone: two strips, one look.
+// sc-7951: three of the keys ARE that bar's own — the active-item style it
+// used to borrow from the rail for want of a control, the active tab's
+// surface, and whether the glyph sits beside the label or above it.
 export function resolveFooterTokens(theme) {
   const config = isPlainObject(theme) ? theme : {};
   const footer = isPlainObject(config.footer) ? config.footer : {};
   const sidebar = isPlainObject(config.sidebar) ? config.sidebar : {};
-  const pick = (key) => footer[key] || sidebar[key] || null;
+  // Hex-guarded on the way out, not merely on the way in: `theme_config` is an
+  // opaque blob an operator can hand-edit, and the EXPORT already refused a
+  // malformed colour here while the Player passed it to a style object — so the
+  // guard is what stops the two hosts painting a stored junk value differently.
+  const pick = (key) => hexOrNull(footer[key]) || hexOrNull(sidebar[key]) || null;
   const borderColor = pick("borderColor");
+  // sc-7951: the rail's style is the FALLBACK now, not the only source. Unset
+  // still follows the rail, which is what keeps every shipped app where it is.
   const activeStyle = footer.activeStyle || sidebar.activeStyle;
+  const accent = activeStyle === "accent";
+  const activeColor = hexOr(pick("activeColor"), brandPrimary(config));
+  // Footer-only: a rail item is a full-width row with no tab surface to paint,
+  // so this inherits from nothing and unset means "no surface of its own".
+  const namedSurface = hexOrNull(footer.tabActiveBackgroundColor);
   return {
     backgroundColor: pick("backgroundColor"),
     textColor: pick("textColor"),
-    // Unlike the others this has no null state on either host: an unset active
-    // colour resolves to the brand primary, which the caller supplies.
-    activeColor: pick("activeColor"),
+    // Resolved here rather than by each caller, which is what lets the two
+    // active-tab fields below be resolved here too.
+    activeColor,
     // REQ-THEME-LOOK: the divider's COLOUR is its switch. Unset draws no line at
-    // all — which the native quick bar did not honour before this, ruling a
-    // hairline across a tinted strip that had asked for none.
+    // all — which the native strip did not honour before this, ruling a
+    // hairline across a tinted bar that had asked for none.
     borderColor,
     borderWidth: borderColor ? borderWidthOr(footer.borderWidth, sidebar.borderWidth) : null,
-    activeStyle: activeStyle === "accent" ? "accent" : "filled",
+    activeStyle: accent ? "accent" : "filled",
+    // sc-7951: bottom tabs are the only strip tall enough to stack the two, so
+    // the choice is the footer's alone.
+    tabLayout: footer.tabLayout === "stacked" ? "stacked" : "inline",
+    // sc-7951: the active tab's two halves, resolved HERE so neither host
+    // re-derives the back-compat rule. "filled" with nothing named is what both
+    // hosts shipped — the active colour as the fill, the label forced white —
+    // and that pairing is the only reason a marked tab's label is not simply
+    // the active colour. Naming a surface unbundles them: the surface is the
+    // author's and the label goes back to the active colour.
+    activeSurface: namedSurface || (accent ? null : activeColor),
+    activeTint: accent || namedSurface ? activeColor : FILLED_TAB_LABEL,
   };
 }
 
 // REQ-THEME-14 — the rail's and the app bar's tokens, resolved once for both
 // hosts.
 //
-// These return FULLY resolved values where `resolveFooterTokens` above returns
-// raw-or-null, and the difference is deliberate. The footer's two hosts happen
-// to agree on their separately-written defaults; the rail's and the bar's did
-// not. An unset `sidebar.backgroundColor` painted #ffffff on web and the app
+// These return FULLY resolved values where `resolveFooterTokens` above still
+// returns raw-or-null for its SURFACE, LABEL and DIVIDER colours, and the
+// difference is deliberate. The footer's two hosts happen to agree on their
+// separately-written defaults for those three (`#ffffff` / `#475569` / no
+// line); the rail's and the bar's did not. sc-7951 resolved the footer's active
+// tab — `activeColor`, `activeSurface`, `activeTint` — because a rule that
+// pairs a surface with a label cannot live in two hosts; the three above are
+// what remains of the old shape. An unset `sidebar.backgroundColor` painted #ffffff on web and the app
 // background in the export, and an unset `topBar.textColor` painted the brand
 // primary on web and slate-700 in the export. A default that lives in the
-// resolver cannot drift; one that lives in each host already had. The footer
-// wants this same shape next — the same fix, not yet applied.
+// resolver cannot drift; one that lives in each host already had. The footer's
+// three remaining raw colours want this same shape next.
 //
 // 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
@@ -140,6 +147,9 @@ 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";
+// The literal both hosts hard-coded behind an unnamed "filled" surface, before
+// resolveFooterTokens decided the pairing once (sc-7951).
+const FILLED_TAB_LABEL = "#ffffff";
 
 // A gradient shows only when BOTH stops are a flat hex — the rule both hosts'
 // page readers apply (`normaliseThemeGradient`, mirrored frontend/backend). A

package/package.json

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