@colixsystems/widget-sdk 0.151.0 → 0.153.0

package/README.md

@@ -72,7 +72,28 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.151.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.153.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.153.0 (contract 1.118.0 — unchanged)
+
+**`./host` publishes the local-clock DATETIME conversion `<DateTimePicker>` uses (sc-8448).** The Studio's Data Manager sliced the stored UTC string and saved the input's value without a zone, so it showed and wrote UTC labelled as local. It now reads the same conversion the picker does, so a stored instant shows the same wall clock in the Studio and in the Player.
+
+- **`isoToDateTimeLocalInput(value)`** — a stored instant as `<input type="datetime-local">`'s `YYYY-MM-DDTHH:mm` on the viewer's clock. A bare `YYYY-MM-DD` is local midnight.
+- **`dateTimeLocalInputToIso(raw)`** — the inverse: a local `YYYY-MM-DDTHH:mm` as a full UTC ISO instant.
+- **`formatDateTimeLabel(value, mode)`** — the picker's trigger label (`YYYY-MM-DD HH:mm` local for `"datetime"`).
+
+Behaviour: a bare date given to a `mode="datetime"` picker now shows local midnight instead of UTC midnight (which read as the previous evening west of Greenwich), and a year before 1000 is zero-padded so typing a year no longer clears the web input. Otherwise additive.
+
+### What's new in 0.152.0 (contract 1.118.0 — unchanged)
+
+**The app header's row is arrangeable, and `./host` publishes the resolver both hosts read (sc-8023).** The row runs across the top of the content outside the side panel, and is drawn three times — as the phone header where the panel is a drawer, as the desktop strip, and as the full-width bar when one is switched on. Each surface hard-coded its own copy of it, so an author could colour the row but never move anything in it.
+
+- **`resolveTopStripeLayout(theme)`** reads `theme.sidebar.stripe` and returns the arrangement fully resolved: `slots` (already filtered and sequenced, so no host re-derives it), `order`, the box (`height`, `paddingX`, `contentOffsetY`), the resolved `backgroundColor`, and `menuSide` — which edge the drawer must arrive from, since the brand grows and a burger ordered after it sits at the trailing edge. The web Player picks the drawer's side with it; the export makes it `drawerPosition`.
+- **`TOP_STRIPE_SLOTS`** is the vocabulary (`back`, `menu`, `brand`, `notifications`) and **`TOP_STRIPE_ALWAYS_SHOWN_SLOTS`** the slots that move but never hide. The burger is the only member: it is drawn only where the panel is a drawer, and there it is the sole route into the menu, so hiding it would strand the visitor. It keeps its place in `order` regardless.
+- **`topStripeShowKey(slot)`** derives the `theme_config` key that shows or hides one slot, in one place, so a control, the write path and the resolver cannot spell it differently.
+- **The bounds travel with the resolver** — `MIN`/`MAX_TOP_STRIPE_HEIGHT_PX`, `MIN`/`MAX_TOP_STRIPE_PADDING_X_PX`, `MAX_TOP_STRIPE_OFFSET_Y_PX` — so a control offers exactly the range the resolver clamps to. `DEFAULT_TOP_STRIPE_HEIGHT_PX` / `DEFAULT_TOP_STRIPE_PADDING_X_PX` are what the DESKTOP row measures with nothing stored, published so a control can show the number an author is departing from; the resolver still answers `null`, because each surface keeps its own box until one is named.
+
+Additive — nothing in the existing `./host` surface changed, and the contract is untouched.
 
 ### What's new in 0.151.0 (contract 1.118.0 — unchanged)
 
@@ -241,6 +262,18 @@ All three are `warning`, so `appstudio-widget lint` reports them and still exits
 
 `lintEditability(manifest, files)` is bundle-level like `lintStyleWiring`, and needs `--manifest` for the same reason. It counts rendered elements PER FILE, though: joining `widget.web.jsx` and `widget.native.jsx` would double every tag and call a single-`<Text>` split-impl widget multi-element.
 
+### What's new in 0.151.0 (contract 1.119.0)
+
+**A container's gradient wash can bind its stops to the theme (sc-8326).** sc-8197 gave a layout container's flat fill a theme-following `surface` role, but a two-stop `backgroundGradient` had no role form — so a generated colour-band opener could only freeze two literals out of whichever palette was active when the app was built, and it stopped following the app's own look from then on.
+
+Each stop of a `backgroundGradient` may now be a binding — `"theme:colors.primary"` or `"theme:colors.secondary"` — as well as a hex.
+
+- **`isThemeColorTokenRef(value)` and `THEME_TOKEN_REF_PREFIX`** are exported from the contract: the one grammar predicate the Studio's writer, both hosts' resolvers and Mason's plan validator read, so what may be written and what will resolve cannot drift.
+- **`resolveGradientTokenStops(gradient, theme)`** is the host-integration call behind it, exported from `@colixsystems/widget-sdk/host`. A layout container's style never reaches `resolveThemeTokenRefs` — containers are painted by the page renderer, not by WidgetHost — so this is its own boundary call. Widget authors never call it.
+- **The hex grammar is still the injection guard.** Stops resolve *before* `normaliseComponentGradient`, so what reaches CSS and generated export source is unchanged, and an unresolvable binding fails that guard and drops the wash rather than painting blank.
+- **Nothing changes for a widget author.** A `styleSchema` gradient field already resolved bindings through `resolveThemeTokenRefs`; this closes the container half.
+- **Fully additive.** Every stored hex gradient is untouched and renders byte-identically.
+
 ### What's new in 0.139.0 (contract 1.108.0)
 
 **An author can BIND a colour field to the workspace brand instead of freezing a hex (sc-7800).** A `type: "color"` field tracked the theme only while it was *unset*, through its `themeDefault` placeholder. The moment the author picked a colour it became a literal that outranked the theme forever, so "make this our brand colour" was inexpressible — the author had to type today's hex, and it went stale silently at the next rebrand.

package/dist/contract.cjs

@@ -192,6 +192,20 @@ const THEME_COLOR_TOKENS = Object.freeze([
   Object.freeze({ path: "colors.secondary", label: "Secondary" }),
 ]);
 
+// sc-8326 — the `theme:<path>` value grammar, as a PREDICATE over a STORED
+// value and declared beside the allowlist it reads. Three readers have to agree
+// on what a binding IS: the Studio's colour picker writes one, both hosts
+// resolve one, and Mason's plan validator must accept one as a gradient stop.
+// One definition, so they cannot drift (CLAUDE.md §3).
+const THEME_TOKEN_REF_PREFIX = "theme:";
+
+function isThemeColorTokenRef(value) {
+  if (typeof value !== "string") return false;
+  if (!value.startsWith(THEME_TOKEN_REF_PREFIX)) return false;
+  const path = value.slice(THEME_TOKEN_REF_PREFIX.length);
+  return THEME_COLOR_TOKENS.some((token) => token.path === path);
+}
+
 
 // REQ-THEME-15 (sc-1497) — per-component style tokens. The global palette is a
 // single lever: remapping `primaryColor` to recolour "the buttons" recolours
@@ -4264,7 +4278,17 @@ const CONTRACT = deepFreeze({
   //    because Newsfeed and Chat both render per-emoji pills over a Reactions
   //    table, and the legacy slug mapping (`like` -> emoji) must not be
   //    re-derived per widget.
-  version: "1.118.0",
+  // 1.119.0: additive (sc-8326) — a component gradient's `from` / `to` stops
+  //    accept a `theme:<path>` binding as well as a hex, with
+  //    `isThemeColorTokenRef` as the shared grammar predicate. `surface` gave a
+  //    container's FLAT fill a theme-following role in sc-8197, but a two-stop
+  //    wash had no role form, so Mason's colour-band opener could only freeze
+  //    two literals out of the creation-time palette and the band stopped
+  //    following the app's own theme. Additive: a stored hex gradient is
+  //    untouched and renders byte-identically, and an unresolvable binding
+  //    fails the existing hex guard, dropping the wash rather than painting it
+  //    blank.
+  version: "1.119.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -4567,6 +4591,8 @@ module.exports = {
   deriveSurfaceTokens,
   gradientAngleToVector,
   normaliseComponentGradient,
+  isThemeColorTokenRef,
+  THEME_TOKEN_REF_PREFIX,
   formatMoneyIn,
   normaliseCurrencyCode,
   sameWidgetRouteValue,

package/dist/contract.js

@@ -192,6 +192,20 @@ const THEME_COLOR_TOKENS = Object.freeze([
   Object.freeze({ path: "colors.secondary", label: "Secondary" }),
 ]);
 
+// sc-8326 — the `theme:<path>` value grammar, as a PREDICATE over a STORED
+// value and declared beside the allowlist it reads. Three readers have to agree
+// on what a binding IS: the Studio's colour picker writes one, both hosts
+// resolve one, and Mason's plan validator must accept one as a gradient stop.
+// One definition, so they cannot drift (CLAUDE.md §3).
+const THEME_TOKEN_REF_PREFIX = "theme:";
+
+function isThemeColorTokenRef(value) {
+  if (typeof value !== "string") return false;
+  if (!value.startsWith(THEME_TOKEN_REF_PREFIX)) return false;
+  const path = value.slice(THEME_TOKEN_REF_PREFIX.length);
+  return THEME_COLOR_TOKENS.some((token) => token.path === path);
+}
+
 
 // REQ-THEME-15 (sc-1497) — per-component style tokens. The global palette is a
 // single lever: remapping `primaryColor` to recolour "the buttons" recolours
@@ -4260,7 +4274,17 @@ const CONTRACT = deepFreeze({
   //    because Newsfeed and Chat both render per-emoji pills over a Reactions
   //    table, and the legacy slug mapping (`like` -> emoji) must not be
   //    re-derived per widget.
-  version: "1.118.0",
+  // 1.119.0: additive (sc-8326) — a component gradient's `from` / `to` stops
+  //    accept a `theme:<path>` binding as well as a hex, with
+  //    `isThemeColorTokenRef` as the shared grammar predicate. `surface` gave a
+  //    container's FLAT fill a theme-following role in sc-8197, but a two-stop
+  //    wash had no role form, so Mason's colour-band opener could only freeze
+  //    two literals out of the creation-time palette and the band stopped
+  //    following the app's own theme. Additive: a stored hex gradient is
+  //    untouched and renders byte-identically, and an unresolvable binding
+  //    fails the existing hex guard, dropping the wash rather than painting it
+  //    blank.
+  version: "1.119.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -4563,6 +4587,8 @@ export {
   deriveSurfaceTokens,
   gradientAngleToVector,
   normaliseComponentGradient,
+  isThemeColorTokenRef,
+  THEME_TOKEN_REF_PREFIX,
   formatMoneyIn,
   normaliseCurrencyCode,
   sameWidgetRouteValue,

package/dist/datetimepicker-format.js

@@ -15,12 +15,33 @@ export function parseToDate(value) {
   return new Date();
 }
 
+const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/;
+
+// A stored DATETIME instant → `<input type="datetime-local">`'s
+// `YYYY-MM-DDTHH:mm` on the viewer's local clock. A bare calendar date is
+// local midnight, not UTC midnight, so it never slips a day west of Greenwich.
+export function isoToDateTimeLocalInput(value) {
+  if (value == null || value === "") return "";
+  if (typeof value === "string" && DATE_ONLY.test(value)) return `${value}T00:00`;
+  const d = new Date(value);
+  if (Number.isNaN(d.getTime())) return "";
+  return `${formatToIso(d, "date")}T${formatToIso(d, "time")}`;
+}
+
+// The inverse: a naive local `YYYY-MM-DDTHH:mm` → a full UTC ISO instant.
+export function dateTimeLocalInputToIso(raw) {
+  if (raw == null || raw === "") return "";
+  const d = new Date(raw);
+  if (Number.isNaN(d.getTime())) return "";
+  return d.toISOString();
+}
+
 export function formatToIso(date, mode) {
   if (!(date instanceof Date) || Number.isNaN(date.getTime())) return null;
   if (mode === "date") {
     // Local-date ISO (yyyy-mm-dd) — calendar dates are timezone-free so a
     // "May 28" picked in Stockholm doesn't read as "May 27" in NYC.
-    const y = date.getFullYear();
+    const y = String(date.getFullYear()).padStart(4, "0");
     const m = String(date.getMonth() + 1).padStart(2, "0");
     const d = String(date.getDate()).padStart(2, "0");
     return `${y}-${m}-${d}`;
@@ -46,10 +67,8 @@ export function formatDisplayLabel(value, mode) {
   }
   if (effectiveMode === "date") return String(value).slice(0, 10);
   if (effectiveMode === "time") return String(value).slice(0, 5);
-  // datetime — render the stored UTC ISO in the user's local clock.
-  const d = new Date(value);
-  if (Number.isNaN(d.getTime())) return String(value);
-  return `${formatToIso(d, "date")} ${formatToIso(d, "time")}`;
+  const local = isoToDateTimeLocalInput(value);
+  return local ? local.replace("T", " ") : String(value);
 }
 
 // Perceived-luminance test for a hex colour (`#rgb` or `#rrggbb`). The web

package/dist/datetimepicker.js

@@ -26,7 +26,11 @@
 
 import React from "react";
 import { useHostTheme } from "./hooks.js";
-import { isDarkColor } from "./datetimepicker-format.js";
+import {
+  isDarkColor,
+  isoToDateTimeLocalInput,
+  dateTimeLocalInputToIso,
+} from "./datetimepicker-format.js";
 import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
 
 const MODE_TO_INPUT_TYPE = {
@@ -51,15 +55,7 @@ function _isoToInputValue(value, mode) {
   if (mode === "time") {
     return String(value).slice(0, 5);
   }
-  // datetime-local
-  const d = new Date(value);
-  if (Number.isNaN(d.getTime())) return "";
-  const y = d.getFullYear();
-  const m = String(d.getMonth() + 1).padStart(2, "0");
-  const day = String(d.getDate()).padStart(2, "0");
-  const hh = String(d.getHours()).padStart(2, "0");
-  const mm = String(d.getMinutes()).padStart(2, "0");
-  return `${y}-${m}-${day}T${hh}:${mm}`;
+  return isoToDateTimeLocalInput(value);
 }
 
 // Translate the input's typed string back to the ISO format the wire wants.
@@ -69,9 +65,7 @@ function _isoToInputValue(value, mode) {
 function _inputValueToIso(raw, mode) {
   if (raw == null || raw === "") return "";
   if (mode === "date" || mode === "time") return raw;
-  const d = new Date(raw);
-  if (Number.isNaN(d.getTime())) return "";
-  return d.toISOString();
+  return dateTimeLocalInputToIso(raw);
 }
 
 export function DateTimePicker({

package/dist/host.d.ts

@@ -300,6 +300,57 @@ export interface TopBarTokens {
  */
 export function resolveTopBarTokens(theme: unknown): TopBarTokens;
 
+/** sc-8023 — the arrangeable contents of the sidebar layout's TOP STRIPE: the
+ *  row across the top of the content, outside the panel and above it. */
+export type TopStripeSlot = "back" | "menu" | "brand" | "notifications";
+
+export const TOP_STRIPE_SLOTS: TopStripeSlot[];
+
+/** The slots that move but never hide. The burger is drawn only where the panel
+ *  is a drawer, and there it is the only route into the menu. */
+export const TOP_STRIPE_ALWAYS_SHOWN_SLOTS: TopStripeSlot[];
+
+export const MIN_TOP_STRIPE_HEIGHT_PX: number;
+export const MAX_TOP_STRIPE_HEIGHT_PX: number;
+export const MIN_TOP_STRIPE_PADDING_X_PX: number;
+export const MAX_TOP_STRIPE_PADDING_X_PX: number;
+export const MAX_TOP_STRIPE_OFFSET_Y_PX: number;
+
+/** What the DESKTOP stripe measures with nothing stored, so a control can
+ *  show the number an author is departing from rather than an empty box. */
+export const DEFAULT_TOP_STRIPE_HEIGHT_PX: number;
+export const DEFAULT_TOP_STRIPE_PADDING_X_PX: number;
+
+/** The `theme_config` key that shows or hides one slot (`back` → `showBack`). */
+export function topStripeShowKey(slot: TopStripeSlot): string;
+
+export interface TopStripeLayout {
+  /** The stripe's own surface, falling back to the app-header colour so an
+   *  untouched app is unmoved and a page's top navigation bar cannot repaint it. */
+  backgroundColor: string;
+  /** The row's box in px, or null to keep each surface's own — the desktop
+   *  bar's 64px, the phone header's content-sized row. */
+  height: number | null;
+  paddingX: number | null;
+  /** How far the row is pushed down, 0-60px. */
+  contentOffsetY: number;
+  /** Every slot in the author's sequence, hidden ones included. */
+  order: TopStripeSlot[];
+  /** What the bar actually SHOWS, already filtered and sequenced. A surface
+   *  still drops what it cannot draw, and a bar left empty is not drawn. */
+  slots: TopStripeSlot[];
+  /** Which edge the drawer arrives from: the brand grows, so a burger ordered
+   *  after it sits at the trailing edge and must open a panel from there.
+   *  Web picks the drawer's side with it, native its `drawerPosition`. */
+  menuSide: "start" | "end";
+}
+
+/**
+ * Resolves the top stripe's arrangement from a whole `theme_config`, reading
+ * `sidebar.stripe`. Both hosts draw the row from this one answer (§8).
+ */
+export function resolveTopStripeLayout(theme: unknown): TopStripeLayout;
+
 /** A value a widget may persist: a scalar, or a flat array of them. */
 export type WidgetRouteScalar = string | number | boolean;
 export type WidgetRouteValue = WidgetRouteScalar | WidgetRouteScalar[];
@@ -390,3 +441,33 @@ export function resolveThemeTokenRefs<T>(
   theme: unknown,
   schemas?: { propertySchema?: unknown; styleSchema?: unknown },
 ): T;
+
+/**
+ * sc-8326 — resolve the `theme:` stops of a layout container's gradient wash.
+ * A container's style never reaches `resolveThemeTokenRefs`, so this is its own
+ * boundary call; the result still goes through `normaliseComponentGradient`,
+ * which stays the hex injection guard.
+ */
+export function resolveGradientTokenStops(
+  gradient: unknown,
+  theme: unknown,
+): unknown;
+
+/**
+ * sc-8448 — a stored DATETIME instant as `<input type="datetime-local">`'s
+ * `YYYY-MM-DDTHH:mm` on the viewer's local clock. A bare `YYYY-MM-DD` is local
+ * midnight. Empty or unparseable input returns `""`.
+ */
+export function isoToDateTimeLocalInput(value: unknown): string;
+
+/** sc-8448 — a local `YYYY-MM-DDTHH:mm` as a full UTC ISO instant, or `""`. */
+export function dateTimeLocalInputToIso(raw: unknown): string;
+
+/**
+ * sc-8448 — the `<DateTimePicker>` trigger label: for `"datetime"` the stored
+ * instant as `YYYY-MM-DD HH:mm` local time, falling back to the raw string.
+ */
+export function formatDateTimeLabel(
+  value: unknown,
+  mode: "date" | "time" | "datetime",
+): string;

package/dist/host.js

@@ -28,10 +28,13 @@ export {
 // at the SAME render boundary on both hosts — so a rebrand repaints the Player,
 // the Canvas and the exported app alike, and the widget still receives a plain
 // colour string.
+// sc-8326 extends the same grammar to a layout container's gradient stops, the
+// one themed value that never passes through WidgetHost.
 export {
   isThemeTokenRef,
   resolveThemeTokenRef,
   resolveThemeTokenRefs,
+  resolveGradientTokenStops,
 } from "./theme-token-refs.js";
 
 // REQ-THEME-SURFACE: the surface-token derivation both hosts apply per painted
@@ -63,6 +66,10 @@ export {
 // 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.
+// sc-8023: `resolveTopStripeLayout` is the app header bar's ARRANGEMENT — what the
+// row above the side panel holds, in what order, and the box it sits in. The
+// same bar is drawn by the desktop top bar, the phone header and the exported
+// app's screen header, and each hard-coded its own row before this.
 // REQ-NAV-LOCAL (sc-7696): `resolveSidebarUnfold` answers where a page's
 // SIDEBAR local menu hangs in the rail and the drawer. The compiler asks it
 // once per screen at build time and the Player once per render, so the two
@@ -72,7 +79,20 @@ export {
   menuItemCap,
   resolveFooterTokens,
   resolveSidebarTokens,
+  resolveTopStripeLayout,
   resolveTopBarTokens,
+  topStripeShowKey,
+  TOP_STRIPE_ALWAYS_SHOWN_SLOTS,
+  TOP_STRIPE_SLOTS,
+  // The bar's BOUNDS travel with it: the Studio's controls offer exactly the
+  // range the resolver clamps to, rather than restating the numbers.
+  MIN_TOP_STRIPE_HEIGHT_PX,
+  MAX_TOP_STRIPE_HEIGHT_PX,
+  MIN_TOP_STRIPE_PADDING_X_PX,
+  MAX_TOP_STRIPE_PADDING_X_PX,
+  MAX_TOP_STRIPE_OFFSET_Y_PX,
+  DEFAULT_TOP_STRIPE_HEIGHT_PX,
+  DEFAULT_TOP_STRIPE_PADDING_X_PX,
   resolveSidebarUnfold,
 } from "./navigation.js";
 
@@ -104,3 +124,10 @@ export {
   normaliseThemeGradient,
   normaliseLoginDesign,
 } from "./theme-background.js";
+
+// sc-8448: one DATETIME local-clock conversion for the picker and the Studio.
+export {
+  isoToDateTimeLocalInput,
+  dateTimeLocalInputToIso,
+  formatDisplayLabel as formatDateTimeLabel,
+} from "./datetimepicker-format.js";

package/dist/index.d.ts

@@ -2674,6 +2674,16 @@ export function normaliseComponentGradient(
   raw: unknown,
 ): ComponentGradient | null;
 
+/** sc-8326 — the `theme:<path>` binding prefix, shared with the hosts' resolver. */
+export const THEME_TOKEN_REF_PREFIX: string;
+
+/**
+ * sc-8326 — true when a stored value is a `theme:<path>` binding naming a token
+ * in `CONTRACT.themeColorTokens`. The one grammar predicate the Studio's writer,
+ * the hosts' resolver and Mason's plan validator all read.
+ */
+export function isThemeColorTokenRef(value: unknown): boolean;
+
 // Linter
 export interface LintFinding {
   rule: string;

package/dist/index.js

@@ -158,6 +158,8 @@ export {
   deriveAccentTints,
   gradientAngleToVector,
   normaliseComponentGradient,
+  isThemeColorTokenRef,
+  THEME_TOKEN_REF_PREFIX,
   clampSpacingScale,
   scaleSpacing,
 } from "./contract.js";

package/dist/index.native.js

@@ -151,6 +151,8 @@ export {
   deriveAccentTints,
   gradientAngleToVector,
   normaliseComponentGradient,
+  isThemeColorTokenRef,
+  THEME_TOKEN_REF_PREFIX,
   clampSpacingScale,
   scaleSpacing,
 } from "./contract.js";

package/dist/navigation.cjs

@@ -301,6 +301,175 @@ function resolveSidebarTokens(theme) {
  *   resolves to the page's, as an `attached` tab's already did (sc-6596).
  * @returns {{ backgroundColor: string, tintColor: string, titleColor: string }}
  */
+// sc-8023 — the TOP STRIPE's arrangement: the row that runs across the top of
+// the content in the sidebar layout, outside the panel and above it.
+//
+// It is NOT the optional full-width top bar, which keeps its own fixed row.
+// The stripe is what an app with a side panel actually shows, and it is drawn
+// twice — across the content on desktop, and as the phone header where the panel
+// is a drawer — each hard-coding its own arrangement, so the author could colour
+// the row but never move anything in it.
+//
+// It lives on the SIDEBAR block because it belongs to that layout: `topBar` is
+// the other bar. Its colours still come from the app-header tokens
+// (`resolveTopBarTokens`), which is what paints all of this chrome today.
+// The identity is deliberately NOT here. On a phone the panel's own foot owns
+// the account and sign-out (sc-5907 — a 120px name pill left the brand nothing
+// to render in), and on desktop they sit in the content strip the rail does not
+// reach. Offering them as arrangeable slots meant two checkboxes that could
+// never move anything, which is worse than not offering them.
+const TOP_STRIPE_SLOTS = ["back", "menu", "brand", "notifications"];
+
+// Everything the bar draws today, so an app that never opens the panel is
+// unmoved. Unlike the slots a surface adds, none of these is new — they are the
+// controls already in the row, now nameable.
+const TOP_STRIPE_SLOT_SHOWN_BY_DEFAULT = {
+  back: true,
+  menu: true,
+  brand: true,
+  notifications: true,
+};
+
+// The burger MOVES but never hides. It is drawn only where the panel is a
+// drawer — a phone — and there it is the sole way in: the REQ-NAV-14 floating
+// button belongs to site mode, so an app page that dropped it would strand the
+// visitor with no route to the menu. Its position still matters (it decides
+// which edge the drawer arrives from), so it stays in `order` and simply
+// offers no visibility of its own, the way the identity offers no slot.
+const TOP_STRIPE_ALWAYS_SHOWN_SLOTS = ["menu"];
+
+// The bar's box. Neither measurement has a shared default: the desktop bar is a
+// fixed `h-16` with `px-4`, the phone header is content-sized with `px-2`.
+// `null` keeps each of those, so nothing moves until an author names one — and
+// then both surfaces take the same, which is the convergence (§3).
+const MIN_TOP_STRIPE_HEIGHT_PX = 40;
+const MAX_TOP_STRIPE_HEIGHT_PX = 200;
+const MIN_TOP_STRIPE_PADDING_X_PX = 0;
+const MAX_TOP_STRIPE_PADDING_X_PX = 64;
+const MAX_TOP_STRIPE_OFFSET_Y_PX = 60;
+
+// What the DESKTOP stripe measures when nothing is stored — the row's shipped
+// `h-16` and `px-4`. Published so a control can show the author the number
+// they are departing from instead of an empty box; the resolver still answers
+// `null`, because the phone header's box is its own and neither surface moves
+// until an author names a value.
+const DEFAULT_TOP_STRIPE_HEIGHT_PX = 64;
+const DEFAULT_TOP_STRIPE_PADDING_X_PX = 16;
+
+/**
+ * The `theme_config` key that shows or hides one slot. Derived in ONE place so
+ * the Studio's control, the write-path coercion and the resolver cannot each
+ * spell it slightly differently.
+ *
+ * @param {string} slot — a member of `TOP_STRIPE_SLOTS`.
+ * @returns {string}
+ */
+function topStripeShowKey(slot) {
+  return `show${slot.charAt(0).toUpperCase()}${slot.slice(1)}`;
+}
+
+// Clamped rather than dropped: a value past the end expresses a real intent and
+// lands on the end. A non-number is a different case and takes the default.
+function topStripeClampedOr(value, min, max, fallback) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  return Math.min(Math.max(Math.round(value), min), max);
+}
+
+// An `order` is at most a permutation; anything longer is not an ordering, and
+// `theme_config` is stored close to verbatim, so it is refused rather than
+// walked. Both hosts resolve on every render.
+const MAX_TOP_STRIPE_ORDER_ENTRIES = TOP_STRIPE_SLOTS.length * 2;
+
+function topStripeOrder(value) {
+  if (!Array.isArray(value) || value.length > MAX_TOP_STRIPE_ORDER_ENTRIES) {
+    return TOP_STRIPE_SLOTS.slice();
+  }
+  const named = [];
+  for (const slot of value) {
+    if (TOP_STRIPE_SLOTS.includes(slot) && !named.includes(slot)) named.push(slot);
+  }
+  // An authored order names what it cares about; everything it leaves out keeps
+  // its default place. Dropping the unnamed slots would make "reorder two" and
+  // "hide the rest" the same gesture, and one of those is an accident.
+  return named.concat(TOP_STRIPE_SLOTS.filter((s) => !named.includes(s)));
+}
+
+/**
+ * The app header bar's arrangement, resolved for every host.
+ *
+ * `slots` is the ordered list of what the bar SHOWS — already filtered and
+ * sequenced, so no surface re-derives it. A surface still drops what it cannot
+ * draw (a desktop bar has no burger; a root page has no back control), and a
+ * bar left holding nothing is not drawn at all.
+ *
+ * @param {unknown} theme — the whole `theme_config`.
+ * @returns {{ backgroundColor: string, height: number|null,
+ *   paddingX: number|null, contentOffsetY: number, order: string[],
+ *   slots: string[], menuSide: "start"|"end" }}
+ */
+function resolveTopStripeLayout(theme) {
+  const config = isPlainObject(theme) ? theme : {};
+  const sidebar = isPlainObject(config.sidebar) ? config.sidebar : {};
+  const stripe = isPlainObject(sidebar.stripe) ? sidebar.stripe : {};
+  const order = topStripeOrder(stripe.order);
+  const shown = (slot) => {
+    if (TOP_STRIPE_ALWAYS_SHOWN_SLOTS.includes(slot)) return true;
+    const value = stripe[topStripeShowKey(slot)];
+    return typeof value === "boolean"
+      ? value
+      : TOP_STRIPE_SLOT_SHOWN_BY_DEFAULT[slot];
+  };
+  const slots = order.filter(shown);
+  return {
+    // There is no alignment to resolve: the brand slot GROWS, so the row has no
+    // free space for `justify-content` to distribute and every value looked
+    // identical. The row spreads because the brand takes the slack.
+    // Unset defers to each surface's own box — the desktop bar's fixed 64px,
+    // the phone header's content-sized row.
+    height: topStripeClampedOr(
+      stripe.height,
+      MIN_TOP_STRIPE_HEIGHT_PX,
+      MAX_TOP_STRIPE_HEIGHT_PX,
+      null,
+    ),
+    paddingX: topStripeClampedOr(
+      stripe.paddingX,
+      MIN_TOP_STRIPE_PADDING_X_PX,
+      MAX_TOP_STRIPE_PADDING_X_PX,
+      null,
+    ),
+    contentOffsetY: topStripeClampedOr(
+      stripe.contentOffsetY,
+      0,
+      MAX_TOP_STRIPE_OFFSET_Y_PX,
+      0,
+    ),
+    // sc-8023: the stripe's OWN surface, inheriting the app-header colour when
+    // unset — so an untouched app is unmoved, and an author who dresses a
+    // page's top navigation bar no longer repaints the stripe above the panel by
+    // accident. Fully resolved here, not raw-or-null, for the reason sc-8033
+    // resolved the footer's: a default that lives in each host drifts.
+    backgroundColor: hexOr(
+      stripe.backgroundColor,
+      resolveTopBarTokens(theme).backgroundColor,
+    ),
+    order,
+    slots,
+    // sc-8023: which edge the panel the burger opens should come in from. The
+    // brand GROWS, so anything ordered after it is pushed to the trailing edge
+    // — a burger over there opening a panel from the opposite side is a panel
+    // that flies past the button that summoned it. With no brand drawn nothing
+    // grows and the whole row packs to the start, so the burger is leading
+    // whatever its index. Both hosts read this: web picks the drawer's side,
+    // native its `drawerPosition`.
+    menuSide:
+      slots.includes("brand") &&
+      slots.indexOf("menu") > slots.indexOf("brand")
+        ? "end"
+        : "start",
+  };
+}
+
 function resolveTopBarTokens(theme) {
   const config = isPlainObject(theme) ? theme : {};
   const topBar = isPlainObject(config.topBar) ? config.topBar : {};
@@ -477,4 +646,4 @@ function borderWidthOr(...values) {
   return BORDER_WIDTH_MIN;
 }
 
-module.exports = { normaliseNavigation, menuItemCap, resolveFooterTokens, resolveSidebarTokens, resolveTopBarTokens, resolveSidebarUnfold };
+module.exports = { normaliseNavigation, menuItemCap, resolveFooterTokens, resolveSidebarTokens, resolveTopStripeLayout, resolveTopBarTokens, topStripeShowKey, TOP_STRIPE_ALWAYS_SHOWN_SLOTS, TOP_STRIPE_SLOTS, MIN_TOP_STRIPE_HEIGHT_PX, MAX_TOP_STRIPE_HEIGHT_PX, MIN_TOP_STRIPE_PADDING_X_PX, MAX_TOP_STRIPE_PADDING_X_PX, MAX_TOP_STRIPE_OFFSET_Y_PX, DEFAULT_TOP_STRIPE_HEIGHT_PX, DEFAULT_TOP_STRIPE_PADDING_X_PX, resolveSidebarUnfold };

package/dist/navigation.js

@@ -292,6 +292,175 @@ export function resolveSidebarTokens(theme) {
  *   resolves to the page's, as an `attached` tab's already did (sc-6596).
  * @returns {{ backgroundColor: string, tintColor: string, titleColor: string }}
  */
+// sc-8023 — the TOP STRIPE's arrangement: the row that runs across the top of
+// the content in the sidebar layout, outside the panel and above it.
+//
+// It is NOT the optional full-width top bar, which keeps its own fixed row.
+// The stripe is what an app with a side panel actually shows, and it is drawn
+// twice — across the content on desktop, and as the phone header where the panel
+// is a drawer — each hard-coding its own arrangement, so the author could colour
+// the row but never move anything in it.
+//
+// It lives on the SIDEBAR block because it belongs to that layout: `topBar` is
+// the other bar. Its colours still come from the app-header tokens
+// (`resolveTopBarTokens`), which is what paints all of this chrome today.
+// The identity is deliberately NOT here. On a phone the panel's own foot owns
+// the account and sign-out (sc-5907 — a 120px name pill left the brand nothing
+// to render in), and on desktop they sit in the content strip the rail does not
+// reach. Offering them as arrangeable slots meant two checkboxes that could
+// never move anything, which is worse than not offering them.
+export const TOP_STRIPE_SLOTS = ["back", "menu", "brand", "notifications"];
+
+// Everything the bar draws today, so an app that never opens the panel is
+// unmoved. Unlike the slots a surface adds, none of these is new — they are the
+// controls already in the row, now nameable.
+const TOP_STRIPE_SLOT_SHOWN_BY_DEFAULT = {
+  back: true,
+  menu: true,
+  brand: true,
+  notifications: true,
+};
+
+// The burger MOVES but never hides. It is drawn only where the panel is a
+// drawer — a phone — and there it is the sole way in: the REQ-NAV-14 floating
+// button belongs to site mode, so an app page that dropped it would strand the
+// visitor with no route to the menu. Its position still matters (it decides
+// which edge the drawer arrives from), so it stays in `order` and simply
+// offers no visibility of its own, the way the identity offers no slot.
+export const TOP_STRIPE_ALWAYS_SHOWN_SLOTS = ["menu"];
+
+// The bar's box. Neither measurement has a shared default: the desktop bar is a
+// fixed `h-16` with `px-4`, the phone header is content-sized with `px-2`.
+// `null` keeps each of those, so nothing moves until an author names one — and
+// then both surfaces take the same, which is the convergence (§3).
+export const MIN_TOP_STRIPE_HEIGHT_PX = 40;
+export const MAX_TOP_STRIPE_HEIGHT_PX = 200;
+export const MIN_TOP_STRIPE_PADDING_X_PX = 0;
+export const MAX_TOP_STRIPE_PADDING_X_PX = 64;
+export const MAX_TOP_STRIPE_OFFSET_Y_PX = 60;
+
+// What the DESKTOP stripe measures when nothing is stored — the row's shipped
+// `h-16` and `px-4`. Published so a control can show the author the number
+// they are departing from instead of an empty box; the resolver still answers
+// `null`, because the phone header's box is its own and neither surface moves
+// until an author names a value.
+export const DEFAULT_TOP_STRIPE_HEIGHT_PX = 64;
+export const DEFAULT_TOP_STRIPE_PADDING_X_PX = 16;
+
+/**
+ * The `theme_config` key that shows or hides one slot. Derived in ONE place so
+ * the Studio's control, the write-path coercion and the resolver cannot each
+ * spell it slightly differently.
+ *
+ * @param {string} slot — a member of `TOP_STRIPE_SLOTS`.
+ * @returns {string}
+ */
+export function topStripeShowKey(slot) {
+  return `show${slot.charAt(0).toUpperCase()}${slot.slice(1)}`;
+}
+
+// Clamped rather than dropped: a value past the end expresses a real intent and
+// lands on the end. A non-number is a different case and takes the default.
+function topStripeClampedOr(value, min, max, fallback) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  return Math.min(Math.max(Math.round(value), min), max);
+}
+
+// An `order` is at most a permutation; anything longer is not an ordering, and
+// `theme_config` is stored close to verbatim, so it is refused rather than
+// walked. Both hosts resolve on every render.
+const MAX_TOP_STRIPE_ORDER_ENTRIES = TOP_STRIPE_SLOTS.length * 2;
+
+function topStripeOrder(value) {
+  if (!Array.isArray(value) || value.length > MAX_TOP_STRIPE_ORDER_ENTRIES) {
+    return TOP_STRIPE_SLOTS.slice();
+  }
+  const named = [];
+  for (const slot of value) {
+    if (TOP_STRIPE_SLOTS.includes(slot) && !named.includes(slot)) named.push(slot);
+  }
+  // An authored order names what it cares about; everything it leaves out keeps
+  // its default place. Dropping the unnamed slots would make "reorder two" and
+  // "hide the rest" the same gesture, and one of those is an accident.
+  return named.concat(TOP_STRIPE_SLOTS.filter((s) => !named.includes(s)));
+}
+
+/**
+ * The app header bar's arrangement, resolved for every host.
+ *
+ * `slots` is the ordered list of what the bar SHOWS — already filtered and
+ * sequenced, so no surface re-derives it. A surface still drops what it cannot
+ * draw (a desktop bar has no burger; a root page has no back control), and a
+ * bar left holding nothing is not drawn at all.
+ *
+ * @param {unknown} theme — the whole `theme_config`.
+ * @returns {{ backgroundColor: string, height: number|null,
+ *   paddingX: number|null, contentOffsetY: number, order: string[],
+ *   slots: string[], menuSide: "start"|"end" }}
+ */
+export function resolveTopStripeLayout(theme) {
+  const config = isPlainObject(theme) ? theme : {};
+  const sidebar = isPlainObject(config.sidebar) ? config.sidebar : {};
+  const stripe = isPlainObject(sidebar.stripe) ? sidebar.stripe : {};
+  const order = topStripeOrder(stripe.order);
+  const shown = (slot) => {
+    if (TOP_STRIPE_ALWAYS_SHOWN_SLOTS.includes(slot)) return true;
+    const value = stripe[topStripeShowKey(slot)];
+    return typeof value === "boolean"
+      ? value
+      : TOP_STRIPE_SLOT_SHOWN_BY_DEFAULT[slot];
+  };
+  const slots = order.filter(shown);
+  return {
+    // There is no alignment to resolve: the brand slot GROWS, so the row has no
+    // free space for `justify-content` to distribute and every value looked
+    // identical. The row spreads because the brand takes the slack.
+    // Unset defers to each surface's own box — the desktop bar's fixed 64px,
+    // the phone header's content-sized row.
+    height: topStripeClampedOr(
+      stripe.height,
+      MIN_TOP_STRIPE_HEIGHT_PX,
+      MAX_TOP_STRIPE_HEIGHT_PX,
+      null,
+    ),
+    paddingX: topStripeClampedOr(
+      stripe.paddingX,
+      MIN_TOP_STRIPE_PADDING_X_PX,
+      MAX_TOP_STRIPE_PADDING_X_PX,
+      null,
+    ),
+    contentOffsetY: topStripeClampedOr(
+      stripe.contentOffsetY,
+      0,
+      MAX_TOP_STRIPE_OFFSET_Y_PX,
+      0,
+    ),
+    // sc-8023: the stripe's OWN surface, inheriting the app-header colour when
+    // unset — so an untouched app is unmoved, and an author who dresses a
+    // page's top navigation bar no longer repaints the stripe above the panel by
+    // accident. Fully resolved here, not raw-or-null, for the reason sc-8033
+    // resolved the footer's: a default that lives in each host drifts.
+    backgroundColor: hexOr(
+      stripe.backgroundColor,
+      resolveTopBarTokens(theme).backgroundColor,
+    ),
+    order,
+    slots,
+    // sc-8023: which edge the panel the burger opens should come in from. The
+    // brand GROWS, so anything ordered after it is pushed to the trailing edge
+    // — a burger over there opening a panel from the opposite side is a panel
+    // that flies past the button that summoned it. With no brand drawn nothing
+    // grows and the whole row packs to the start, so the burger is leading
+    // whatever its index. Both hosts read this: web picks the drawer's side,
+    // native its `drawerPosition`.
+    menuSide:
+      slots.includes("brand") &&
+      slots.indexOf("menu") > slots.indexOf("brand")
+        ? "end"
+        : "start",
+  };
+}
+
 export function resolveTopBarTokens(theme) {
   const config = isPlainObject(theme) ? theme : {};
   const topBar = isPlainObject(config.topBar) ? config.topBar : {};

package/dist/theme-token-refs.js

@@ -18,11 +18,13 @@
 // type today's hex, which went stale silently. A bound field stores the TOKEN,
 // so the intent survives the rebrand.
 
-import { CONTRACT } from "./contract.js";
+import { isThemeColorTokenRef, THEME_TOKEN_REF_PREFIX } from "./contract.js";
 
 // A value is a binding, not a colour, when it carries this prefix. No CSS
 // colour can begin with it, so a stored literal can never be misread as one.
-const PREFIX = "theme:";
+// Sourced from the contract (sc-8326): Mason's plan validator reads the same
+// grammar from there, and two spellings of it would drift.
+const PREFIX = THEME_TOKEN_REF_PREFIX;
 
 /** True when `value` is a theme-token binding rather than a literal colour. */
 export function isThemeTokenRef(value) {
@@ -38,13 +40,11 @@ export function isThemeTokenRef(value) {
  * un-bound field does. A malformed binding must never paint blank.
  */
 export function resolveThemeTokenRef(value, theme) {
-  if (!isThemeTokenRef(value)) return undefined;
-  const path = value.slice(PREFIX.length);
   // The allowlist is the contract's, so what the Studio may WRITE and what a
-  // host will RESOLVE cannot drift apart.
-  if (!CONTRACT.themeColorTokens.some((token) => token.path === path)) {
-    return undefined;
-  }
+  // host will RESOLVE cannot drift apart. sc-8326 moved the test itself there
+  // too, since Mason's plan validator has to ask the same question.
+  if (!isThemeColorTokenRef(value)) return undefined;
+  const path = value.slice(PREFIX.length);
   const resolved = path
     .split(".")
     .reduce((o, k) => (o == null ? undefined : o[k]), theme);
@@ -196,3 +196,27 @@ export function resolveThemeTokenRefs(props, theme, schemas) {
   }
   return out;
 }
+
+/**
+ * sc-8326 — resolve the `theme:` stops of a LAYOUT CONTAINER's gradient wash.
+ *
+ * A container's style never reaches `resolveThemeTokenRefs`: containers are
+ * painted by the page renderer, not by WidgetHost, which is why sc-7800 left
+ * them unbindable. Their gradient is the one place that needs a binding —
+ * sc-8197 gave the flat fill a theme-following `surface` role, but a two-stop
+ * wash has no role form, so Mason's colour-band opener could only freeze two
+ * literals out of the palette that happened to be active at build time.
+ *
+ * Resolution happens HERE, BEFORE `normaliseComponentGradient`: that hex
+ * grammar stays the injection guard for stops reaching CSS and generated export
+ * source, and an unresolvable binding fails it like any other non-hex value,
+ * dropping the wash instead of painting it blank.
+ *
+ * @param {unknown} gradient — a raw `style.backgroundGradient`.
+ * @param {object} theme — the resolved widget theme.
+ * @returns {unknown} the same value with every bound stop resolved.
+ */
+export function resolveGradientTokenStops(gradient, theme) {
+  if (!isPlainObject(gradient)) return gradient;
+  return resolveStyleBag(gradient, theme, 1);
+}

package/package.json

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