@colixsystems/widget-sdk 0.150.1 → 0.152.0

package/README.md

@@ -72,7 +72,28 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.150.1` — 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.152.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.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)
+
+**`resolveSidebarUnfold` joins the host navigation surface: where a page's local menu unfolds inside the app's own sidebar (sc-7696, REQ-NAV-LOCAL).** A page's local navigation could only be a bar, above or below its content. `local_nav` now also takes `SIDEBAR`, which takes no strip of the page: the saved menu unfolds in the rail and the drawer, under the global menu entry it belongs to.
+
+- `resolveSidebarUnfold({ entries, active, sections })` answers `{ under, items, standalone }` from host-neutral keys — page slugs on web, screen names in the export — so it is the ONE derivation both chromes read. Web calls it per render; the compiler asks it once per screen at build time, because the only runtime input is which screen is showing.
+- A page belongs to a section in either of two ways, and both keep the tree open: it carries the model, or the section's menu lists it. Clicking a destination must not collapse the menu that led there, and an author should not have to repeat the setting on every sub-page.
+- `standalone` names the case where the global menu carries no page of the section: the section's own page is the entry, for as long as the visitor is inside it, so the menu is never lost.
+- Each returned item carries `current`, so neither host recomputes which destination is the visitor's.
+- **`CONTRACT` is untouched** (`version` stays `1.118.0`): this is a host resolver, not a widget-facing surface, and no existing export changed. `resolveTopBarTokens`, `resolveFooterTokens` and `resolveSidebarTokens` are unchanged — an unfolded row is a sidebar row and wears the rail's own tokens.
 
 ### What's new in 0.150.1 (contract 1.118.0 — unchanged)
 
@@ -231,6 +252,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.
@@ -1687,8 +1720,8 @@ A widget that works but looks unfinished is only half done. `useTheme()` is the
 - **Tint the supporting cast.** `colors.primarySoft` is a tint of the workspace accent over the surface and `colors.onPrimarySoft` is guaranteed readable on it (WCAG AA, on light and dark themes alike). Use the pair for chips, secondary buttons, progress tracks, icon badges and selected rows. One saturated accent moment surrounded by several pale echoes of the same hue is what reads as designed — a row of grey-outlined buttons reads as a form. Never hand-mix a tint with `rgba(...)` or a translucent overlay.
 - **Spend one gradient.** `<Gradient colors={[theme.colors.primary, theme.colors.primaryStrong]} angle={160} style={…}>` is a `View` that paints a gradient behind its children, so it replaces the `View` you'd otherwise give a flat `backgroundColor`. `angle` is CSS degrees (0 = to top, 90 = to right, default 180); text on it uses `colors.onPrimary`. Exactly **one** per widget — on the focal element — and never behind body text. Both hosts render it identically (web paints CSS, native uses `expo-linear-gradient`), so there is no per-platform branching to write; don't import `expo-linear-gradient` yourself and don't write a `backgroundImage` string.
 - **Answer the touch.** Every tappable card, row and list entry lifts while the pointer is over it (web) or it is pressed (touch). One declaration does both: give the Pressable a style FUNCTION and spread `pressableLift` — `<Pressable onPress={open} style={(state) => [styles.card, ...pressableLift(state)]}>`. The lift is a -2px nudge plus one elevation step from `theme.interaction`, with the web transition built in. Never hand-write hover logic or your own pressed shadows, and never fake feedback with `opacity` — a dimmed surface reads as disabling itself.
-- **Size to your container — measure it, don't stretch into it.** The same widget sits in a full-width desktop section (~1400px), a half-width grid cell (~700px) and a phone (~360px), so layout built only from `flex: 1` stretches to fill whatever it is handed — a month calendar ends up with 200px day cells and swallows the page. Measure your own width with `onLayout={(e) => setWidth(e.nativeEvent.layout.width)}` on the root `View` (a React Native primitive, so it behaves identically on both hosts), render nothing size-dependent while `width === 0`, and compute every threshold from the measured value: a widget gets no declared breakpoint prop, but it can always measure. **Cap a repeating cell** rather than giving a grid `flex: 1` — `const cell = Math.max(32, Math.min(Math.floor((usable - gap * (columns - 1)) / columns), 64));`, with a calendar day cell topping out at 56–72px on `aspectRatio: 1`, and the grid given its exact computed width plus `alignSelf: 'center'` when the cap leaves slack. **Split two co-equal surfaces above ~720px measured width** (`flexDirection: width >= 720 ? 'row' : 'column'`, each half `{ flex: 1, minWidth: 0 }`) — a picker beside the form it feeds on a wide canvas, stacked in reading order below it. Never hardcode a width, never put `flex: 1` / `height: '100%'` on a content widget's root, and don't read the screen with `Dimensions` — the screen is not the widget.
-- **Compose forms — pair fields into rows, don't stack one per row.** Put short, related fields side by side (first + last name, city + postal code, expiry + CVC): a row of `{ flexDirection: 'row', flexWrap: 'wrap', gap: theme.spacing.md }` with each field cell `{ flexGrow: 1, flexBasis: 160 }` splits the width on a wide card and wraps to stacked on a narrow phone — the right recipe for field pairs because it needs no measurement (a fixed-width column overflows a phone; when a layout needs a real column count instead of wrapping, measure your width as above). Keep wide fields (email, address, notes) full-width with `width: '100%'` — NEVER `flexBasis: '100%'`, which sizes the main axis and therefore claims the parent's whole HEIGHT in a column (sc-7274) — cap it at two–three per row, group a long form into labelled sections, and label every input above it (not placeholder-only). Give a `multiline` field BOTH a floor and a ceiling (`{ minHeight: 150, maxHeight: 260 }`) so a long value scrolls inside the box instead of growing past its card, and keep the Save / Cancel row in normal flow below the fields, never positioned over them. When a field carries an icon beside it (a search glyph, a clear button), the border belongs on the WRAPPER row and the `TextInput` inside it goes borderless and transparent with `flex: 1, minWidth: 0` (the `minWidth: 0` stops a long value pushing the border past its container) — React Native has no `:focus-within`, so drive the wrapper's `borderColor` between `colors.border` and `colors.primary` from the input's own `onFocus` / `onBlur`. A border left on the input rings only its own `<input>` box on web, leaving the icon outside the ring; never absolutely-position the icon over the field to work around it.
+- **Size to your container — measure it, don't stretch into it.** The same widget sits in a full-width desktop section (~1400px), a half-width grid cell (~700px) and a phone (~360px), so layout built only from `flex: 1` stretches to fill whatever it is handed — a month calendar ends up with 200px day cells and swallows the page. Measure your own width with `onLayout={(e) => setWidth(e.nativeEvent.layout.width)}` on the root `View` (a React Native primitive, so it behaves identically on both hosts), render nothing size-dependent while `width === 0`, and compute every threshold from the measured value: a widget gets no declared breakpoint prop, but it can always measure. **Cap a repeating cell** rather than giving a grid `flex: 1` — `const cell = Math.max(32, Math.min(Math.floor((usable - gap * (columns - 1)) / columns), 64));`, with a calendar day cell topping out at 56–72px on `aspectRatio: 1`, and the grid given its exact computed width plus `alignSelf: 'center'` when the cap leaves slack. **Split two co-equal surfaces above ~720px measured width** (`flexDirection: width >= 720 ? 'row' : 'column'`, each half `{ flex: 1, minWidth: 0 }`) — a picker beside the form it feeds on a wide canvas, stacked in reading order below it. Never hardcode a width, never put `flex: 1` / `height: '100%'` on a content widget's root, and don't read the screen with `Dimensions` — the screen is not the widget. **Whatever you narrow, you centre** — a block that caps its own measure carries all three of `{ width: '100%', maxWidth: FORM_MAX, alignSelf: 'center' }`, because `alignSelf` alone stops the block stretching and sizes it to its content instead, and `maxWidth` alone leaves the widget flush left with dead space beside it; a capped wrap row lays its cells out along the MAIN axis, so it centres with `justifyContent: 'center'` on the row instead. **A metric / stat-tile row WRAPS** — it is a card grid with smaller cells (`{ flexDirection: 'row', flexWrap: 'wrap', gap: theme.spacing.md }`, each tile `{ flexGrow: 1, flexBasis: TILE_MIN }` plus `maxWidth: TILE_MIN * 1.6`), because a bare `flexDirection: 'row'` has no way to break and a React Native flex child defaults to `flexShrink: 0` (unlike CSS), so the tiles cannot give ground either: the row runs past its container, spilling out of the card natively and cut off by the scrolling page column on web, with nothing thrown and nothing logged, once there are enough of them (four fit where five do not). The basis is also the per-line ceiling — `Math.floor((usable + gap) / (TILE_MIN + gap))` tiles fit a line, so 240 tops out at five across a full-width ~1400px section and 320 at four; past four or five a line the tiles stop reading as cards.
+- **Compose forms — pair fields into rows, don't stack one per row.** Cap the form column itself around 560–720px and centre it with the three declarations above, so it neither stretches across a full-width desktop section nor sits flush left with half the canvas empty beside it. Put short, related fields side by side (first + last name, city + postal code, expiry + CVC): a row of `{ flexDirection: 'row', flexWrap: 'wrap', gap: theme.spacing.md }` with each field cell `{ flexGrow: 1, flexBasis: 160 }` splits the width on a wide card and wraps to stacked on a narrow phone — the right recipe for field pairs because it needs no measurement (a fixed-width column overflows a phone; when a layout needs a real column count instead of wrapping, measure your width as above). Keep wide fields (email, address, notes) full-width with `width: '100%'` — NEVER `flexBasis: '100%'`, which sizes the main axis and therefore claims the parent's whole HEIGHT in a column (sc-7274) — cap it at two–three per row, group a long form into labelled sections, and label every input above it (not placeholder-only). Give a `multiline` field BOTH a floor and a ceiling (`{ minHeight: 150, maxHeight: 260 }`) so a long value scrolls inside the box instead of growing past its card, and keep the Save / Cancel row in normal flow below the fields, never positioned over them. When a field carries an icon beside it (a search glyph, a clear button), the border belongs on the WRAPPER row and the `TextInput` inside it goes borderless and transparent with `flex: 1, minWidth: 0` (the `minWidth: 0` stops a long value pushing the border past its container) — React Native has no `:focus-within`, so drive the wrapper's `borderColor` between `colors.border` and `colors.primary` from the input's own `onFocus` / `onBlur`. A border left on the input rings only its own `<input>` box on web, leaving the icon outside the ring; never absolutely-position the icon over the field to work around it.
 - **Respond to touch.** Give every `Pressable` the lift via the function-style `style={(state) => [base, ...pressableLift(state)]}` — see "Answer the touch" above. Never dim with `opacity`, which reads as the surface disabling itself.
 - **Drag and drop — show what is being dragged.** A drag where the item stays put reads as broken. Three things change the moment a drag starts: the **drag proxy** (the item lifts and follows the finger — `...theme.elevation.lg`, `{ scale: 1.03 }`, `opacity: 0.9`; for a tall or full-width item drag a compact `primarySoft` pill with its icon + one line of label instead), the **source placeholder** (the vacated slot keeps its height as a quiet `colors.surfaceMuted` block so the list doesn't collapse), and the **drop target** (one slot at a time highlighted with `primarySoft` or a 2px `colors.primary` border). Always animate the release — settle into the new slot, or `Animated.spring(pan, { toValue: { x: 0, y: 0 }, useNativeDriver: false })` back to the origin on cancel. Build it with `Animated` + `PanResponder` from `react-native` (the only mechanism that behaves identically on both hosts) — never HTML5 drag events (`draggable` / `onDragStart` / `dataTransfer` are web-only, and `document` / `window` are banned) — and start the drag from a `GripVertical` grip handle whenever the row is also tappable or sits in a `ScrollView`. **A board (kanban, pipeline) drops onto ANOTHER column**, which needs four more things: the board's root renders the one proxy (a column clips whatever leaves it); you hit-test the drop yourself — `measureInWindow` every column and the board when the drag starts and compare the gesture's window `moveX` (never `onLayout` frames, which are relative to a padded or scrolled parent) — highlighting exactly one target; the drop WRITES (`update(id, { [statusField]: value })` through `useDatastoreMutation`, optimistic until `refetch()`, a toast and a spring-back on failure); and three or more columns go in a `horizontal` `ScrollView` below `isNarrowWidth`, with the grip claiming the gesture (`onStartShouldSetPanResponder`, `onPanResponderTerminationRequest: () => false`) and carrying `touchAction: 'none'` on web so a finger drag moves the card instead of scrolling the page. And because `useRef(PanResponder.create(...))` runs ONCE, everything its callbacks read — the `useCanWrite` flag included, which starts `false` — goes through a ref refreshed every render (`latest.current.canDrag`); the publish gate `widget.staleResponder` rejects a value read directly.
 - **Use icons for clarity.** Pair a `lucide-react-native` icon with its label at a consistent size, coloured from the theme. The label never repeats the icon as a character — with a `Plus` icon the button says "Add item", never "+ Add item" (that renders a doubled plus).

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
@@ -2961,7 +2975,7 @@ const VETTED_IMPORTS = [
     platforms: ["native"],
     category: "sensors",
     description:
-      "Device motion hardware on the Expo export: Accelerometer, Gyroscope, Magnetometer, DeviceMotion, Barometer, Pedometer and LightSensor, each read as an addListener subscription with setUpdateInterval — always remove the subscription on unmount, a sensor left running drains the battery. Expo SDK 56 ships 56.0.x. Native-only on purpose: the package's own web build derives acceleration from deviceorientation ANGLES rather than real motion, so a shake or tilt threshold tuned on one host would read differently on the other. Author it in widget.native.jsx and pair it with a widget.web.jsx reading window.DeviceMotionEvent (accelerationIncludingGravity / rotationRate), the browser API the same hardware exposes. Both hosts need a user gesture before readings start, and iOS Safari additionally needs an explicit DeviceMotionEvent.requestPermission() grant — so gate the reading behind a Pressable, never start it on mount.",
+      "Device motion hardware on the Expo export: Accelerometer, Gyroscope, Magnetometer, DeviceMotion, Barometer, Pedometer and LightSensor, each read as an addListener subscription with setUpdateInterval — always remove the subscription on unmount, a sensor left running drains the battery. Expo SDK 56 ships 56.0.x. Native-only on purpose: the package's own web build derives acceleration from deviceorientation ANGLES rather than real motion, so a shake or tilt threshold tuned on one host would read differently on the other. Author it in widget.native.jsx. There is NO web path through this package OR through the browser motion API: the browser exposes it as window.DeviceMotionEvent, and `window` is a BANNED widget identifier (see BANNED_APIS), so a widget.web.jsx reading it is rejected by the linter. Give the web half a non-sensor way in instead — manual entry, or a control that does not need motion. On native, readings still need a user gesture, so gate them behind a Pressable and never start them on mount.",
   },
   {
     specifier: "react-native-nfc-manager",
@@ -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
@@ -2957,7 +2971,7 @@ const VETTED_IMPORTS = [
     platforms: ["native"],
     category: "sensors",
     description:
-      "Device motion hardware on the Expo export: Accelerometer, Gyroscope, Magnetometer, DeviceMotion, Barometer, Pedometer and LightSensor, each read as an addListener subscription with setUpdateInterval — always remove the subscription on unmount, a sensor left running drains the battery. Expo SDK 56 ships 56.0.x. Native-only on purpose: the package's own web build derives acceleration from deviceorientation ANGLES rather than real motion, so a shake or tilt threshold tuned on one host would read differently on the other. Author it in widget.native.jsx and pair it with a widget.web.jsx reading window.DeviceMotionEvent (accelerationIncludingGravity / rotationRate), the browser API the same hardware exposes. Both hosts need a user gesture before readings start, and iOS Safari additionally needs an explicit DeviceMotionEvent.requestPermission() grant — so gate the reading behind a Pressable, never start it on mount.",
+      "Device motion hardware on the Expo export: Accelerometer, Gyroscope, Magnetometer, DeviceMotion, Barometer, Pedometer and LightSensor, each read as an addListener subscription with setUpdateInterval — always remove the subscription on unmount, a sensor left running drains the battery. Expo SDK 56 ships 56.0.x. Native-only on purpose: the package's own web build derives acceleration from deviceorientation ANGLES rather than real motion, so a shake or tilt threshold tuned on one host would read differently on the other. Author it in widget.native.jsx. There is NO web path through this package OR through the browser motion API: the browser exposes it as window.DeviceMotionEvent, and `window` is a BANNED widget identifier (see BANNED_APIS), so a widget.web.jsx reading it is rejected by the linter. Give the web half a non-sensor way in instead — manual entry, or a control that does not need motion. On native, readings still need a user gesture, so gate them behind a Pressable and never start them on mount.",
   },
   {
     specifier: "react-native-nfc-manager",
@@ -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/host.d.ts

@@ -224,6 +224,35 @@ export interface SidebarTokens {
  */
 export function resolveSidebarTokens(theme: unknown): SidebarTokens;
 
+/** One destination of a page's local menu, as a host hands it over. `key`
+ *  identifies the target in the caller's own vocabulary (a page slug on web, a
+ *  screen name in the export); a URL item carries none. */
+export interface SidebarUnfoldItem {
+  key?: string | null;
+  [field: string]: unknown;
+}
+
+/** Where a page's `SIDEBAR` local menu unfolds (REQ-NAV-LOCAL, sc-7696).
+ *  `under` is the global menu entry the items hang beneath, or null when
+ *  nothing unfolds. `standalone` marks the case where the global menu does not
+ *  list the page, so the page itself is the entry. */
+export interface SidebarUnfold {
+  under: string | null;
+  items: Array<SidebarUnfoldItem & { current: boolean }>;
+  standalone: boolean;
+}
+
+/** Resolve where the viewed page's local menu unfolds in the sidebar and the
+ *  drawer. The one derivation both hosts read: the Player calls it per render,
+ *  the compiler once per screen, so the rail and the exported drawer cannot
+ *  disagree. */
+export function resolveSidebarUnfold(input: {
+  entries?: readonly string[];
+  active?: string | null;
+  sections?: Record<string, { menu?: unknown; items?: readonly unknown[] }>;
+}): SidebarUnfold;
+
+
 /** The top app bar's resolved tokens. `tintColor` and `titleColor` are separate
  *  because an unthemed bar paints its icons slate and its app name in the brand
  *  colour; an authored `topBar.textColor` drives both. The bar carries NO
@@ -271,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[];
@@ -361,3 +441,14 @@ 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;

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,12 +66,34 @@ 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
+// chromes derive the same tree from the same code.
 export {
   normaliseNavigation,
   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";
 
 // sc-5717: the codec behind `useWidgetRoute()` — how a widget's own internal

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/linter.cjs

@@ -1498,11 +1498,16 @@ const _GENERIC_STYLE_GROUPS = new Set([
   "general",
 ]);
 
-// The three the basic-style gate mandates; they restyle the widget as a whole.
+// The five the basic-style gate mandates; they restyle the widget as a whole.
+// Lockstep with BASIC_STYLE_FIELDS (backend/src/core/services/widget-basic-style.ts)
+// — a mandated field missing here reads as per-element coverage the widget does
+// not have, which silently retires this rule for EVERY generated widget.
 const _WHOLE_WIDGET_STYLE_FIELDS = new Set([
   "background",
   "textColor",
   "align",
+  "padding",
+  "margin",
 ]);
 
 // A second element an author would style apart from the text. Pressable and
@@ -1697,7 +1702,7 @@ function _styleCoverageFindings(manifest, codes) {
       severity: "warning",
       label:
         `The widget renders more than one visual element but its styleSchema ` +
-        `stops at background/textColor/align. Add 2-4 grouped per-element ` +
+        `stops at the whole-widget basics. Add 2-4 grouped per-element ` +
         `fields (cardBackground, titleColor, rowBackground, imageRadius), ` +
         `each applied ONLY when set.`,
       line: 0,

package/dist/linter.js

@@ -1569,11 +1569,16 @@ const _GENERIC_STYLE_GROUPS = new Set([
   "general",
 ]);
 
-// The three the basic-style gate mandates; they restyle the widget as a whole.
+// The five the basic-style gate mandates; they restyle the widget as a whole.
+// Lockstep with BASIC_STYLE_FIELDS (backend/src/core/services/widget-basic-style.ts)
+// — a mandated field missing here reads as per-element coverage the widget does
+// not have, which silently retires this rule for EVERY generated widget.
 const _WHOLE_WIDGET_STYLE_FIELDS = new Set([
   "background",
   "textColor",
   "align",
+  "padding",
+  "margin",
 ]);
 
 // A second element an author would style apart from the text. Pressable and
@@ -1768,7 +1773,7 @@ function _styleCoverageFindings(manifest, codes) {
       severity: "warning",
       label:
         `The widget renders more than one visual element but its styleSchema ` +
-        `stops at background/textColor/align. Add 2-4 grouped per-element ` +
+        `stops at the whole-widget basics. Add 2-4 grouped per-element ` +
         `fields (cardBackground, titleColor, rowBackground, imageRadius), ` +
         `each applied ONLY when set.`,
       line: 0,

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 : {};
@@ -366,6 +535,81 @@ function resolveTopBarTokens(theme) {
   };
 }
 
+/**
+ * REQ-NAV-LOCAL (sc-7696) — where a page's `SIDEBAR` local menu unfolds.
+ *
+ * The one derivation both hosts read, so the web rail, the web drawer and the
+ * exported app's drawer cannot disagree about what hangs under what. Keys are
+ * the caller's own (the web Player passes page slugs, the compiler passes
+ * screen names); this only compares them.
+ *
+ * A page belongs to a section in either of two ways, and both keep the tree
+ * open: it CARRIES the model itself, or the section's menu LISTS it. The
+ * second is what makes the model usable — clicking a destination would
+ * otherwise collapse the menu that led there unless the author repeated the
+ * setting on every sub-page.
+ *
+ * The unfold point is the first GLOBAL menu entry carrying that section's
+ * saved menu, so the tree hangs in the same place from every page of the
+ * section. When the global menu lists no such page, the section's own page
+ * becomes a top-level entry (`standalone`) for as long as the visitor is
+ * inside it, so the menu is never lost — a section off the menu is exactly
+ * the case that would otherwise render blank.
+ *
+ * @param {{ entries?: unknown, active?: unknown, sections?: unknown }} input
+ *   `entries` — the global menu's keys, in menu order.
+ *   `active` — the key of the page being viewed.
+ *   `sections` — `{ [key]: { menu, items } }` for pages whose local nav is
+ *   `SIDEBAR`; `menu` identifies the saved menu, `items` carry their own key.
+ * @returns {{ under: string|null, items: Array<object>, standalone: boolean }}
+ *   `under` is null when nothing unfolds; when `standalone` it names the
+ *   section's own page, which the host draws as the entry. Each item is
+ *   returned with a `current` flag rather than leaving each host to
+ *   recompute it.
+ */
+function resolveSidebarUnfold(input) {
+  const { entries, active, sections } = isPlainObject(input) ? input : {};
+  const nothing = { under: null, items: [], standalone: false };
+  if (typeof active !== "string" || !active) return nothing;
+  const bank = isPlainObject(sections) ? sections : {};
+  const order = Array.isArray(entries) ? entries : [];
+  const sectionAt = (key) => {
+    const candidate = isPlainObject(bank[key]) ? bank[key] : null;
+    const items = candidate && Array.isArray(candidate.items) ? candidate.items : [];
+    return items.length ? { key, menu: candidate.menu, items } : null;
+  };
+  const lists = (key) => {
+    const candidate = sectionAt(key);
+    return (
+      Boolean(candidate) &&
+      candidate.items.some(
+        (item) => isPlainObject(item) && item.key === active,
+      )
+    );
+  };
+  // The page's own section wins; otherwise the section whose menu lists it,
+  // preferring one a global entry carries so the tree hangs where it always
+  // does. Both are the same section from the visitor's side.
+  const section =
+    sectionAt(active) ||
+    sectionAt(order.find(lists)) ||
+    sectionAt(Object.keys(bank).find(lists));
+  if (!section) return nothing;
+  const marked = section.items.map((item) => ({
+    ...(isPlainObject(item) ? item : {}),
+    current:
+      isPlainObject(item) && typeof item.key === "string" && item.key === active,
+  }));
+  const owner = order.find((key) => {
+    const candidate = isPlainObject(bank[key]) ? bank[key] : null;
+    return Boolean(candidate) && candidate.menu === section.menu;
+  });
+  if (typeof owner === "string" && owner) {
+    return { under: owner, items: marked, standalone: false };
+  }
+  return { under: section.key, items: marked, standalone: true };
+}
+
 // REQ-THEME-LOOK: the divider's width in px, bounded HERE so both hosts inherit
 // one range. The export clamped it on its way into the StyleSheet
 // (`coerceBorderWidth(...) ?? 1`) where the Player passed any finite number
@@ -402,4 +646,4 @@ function borderWidthOr(...values) {
   return BORDER_WIDTH_MIN;
 }
 
-module.exports = { normaliseNavigation, menuItemCap, resolveFooterTokens, resolveSidebarTokens, resolveTopBarTokens };
+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 : {};
@@ -357,6 +526,81 @@ export function resolveTopBarTokens(theme) {
   };
 }
 
+/**
+ * REQ-NAV-LOCAL (sc-7696) — where a page's `SIDEBAR` local menu unfolds.
+ *
+ * The one derivation both hosts read, so the web rail, the web drawer and the
+ * exported app's drawer cannot disagree about what hangs under what. Keys are
+ * the caller's own (the web Player passes page slugs, the compiler passes
+ * screen names); this only compares them.
+ *
+ * A page belongs to a section in either of two ways, and both keep the tree
+ * open: it CARRIES the model itself, or the section's menu LISTS it. The
+ * second is what makes the model usable — clicking a destination would
+ * otherwise collapse the menu that led there unless the author repeated the
+ * setting on every sub-page.
+ *
+ * The unfold point is the first GLOBAL menu entry carrying that section's
+ * saved menu, so the tree hangs in the same place from every page of the
+ * section. When the global menu lists no such page, the section's own page
+ * becomes a top-level entry (`standalone`) for as long as the visitor is
+ * inside it, so the menu is never lost — a section off the menu is exactly
+ * the case that would otherwise render blank.
+ *
+ * @param {{ entries?: unknown, active?: unknown, sections?: unknown }} input
+ *   `entries` — the global menu's keys, in menu order.
+ *   `active` — the key of the page being viewed.
+ *   `sections` — `{ [key]: { menu, items } }` for pages whose local nav is
+ *   `SIDEBAR`; `menu` identifies the saved menu, `items` carry their own key.
+ * @returns {{ under: string|null, items: Array<object>, standalone: boolean }}
+ *   `under` is null when nothing unfolds; when `standalone` it names the
+ *   section's own page, which the host draws as the entry. Each item is
+ *   returned with a `current` flag rather than leaving each host to
+ *   recompute it.
+ */
+export function resolveSidebarUnfold(input) {
+  const { entries, active, sections } = isPlainObject(input) ? input : {};
+  const nothing = { under: null, items: [], standalone: false };
+  if (typeof active !== "string" || !active) return nothing;
+  const bank = isPlainObject(sections) ? sections : {};
+  const order = Array.isArray(entries) ? entries : [];
+  const sectionAt = (key) => {
+    const candidate = isPlainObject(bank[key]) ? bank[key] : null;
+    const items = candidate && Array.isArray(candidate.items) ? candidate.items : [];
+    return items.length ? { key, menu: candidate.menu, items } : null;
+  };
+  const lists = (key) => {
+    const candidate = sectionAt(key);
+    return (
+      Boolean(candidate) &&
+      candidate.items.some(
+        (item) => isPlainObject(item) && item.key === active,
+      )
+    );
+  };
+  // The page's own section wins; otherwise the section whose menu lists it,
+  // preferring one a global entry carries so the tree hangs where it always
+  // does. Both are the same section from the visitor's side.
+  const section =
+    sectionAt(active) ||
+    sectionAt(order.find(lists)) ||
+    sectionAt(Object.keys(bank).find(lists));
+  if (!section) return nothing;
+  const marked = section.items.map((item) => ({
+    ...(isPlainObject(item) ? item : {}),
+    current:
+      isPlainObject(item) && typeof item.key === "string" && item.key === active,
+  }));
+  const owner = order.find((key) => {
+    const candidate = isPlainObject(bank[key]) ? bank[key] : null;
+    return Boolean(candidate) && candidate.menu === section.menu;
+  });
+  if (typeof owner === "string" && owner) {
+    return { under: owner, items: marked, standalone: false };
+  }
+  return { under: section.key, items: marked, standalone: true };
+}
+
 // REQ-THEME-LOOK: the divider's width in px, bounded HERE so both hosts inherit
 // one range. The export clamped it on its way into the StyleSheet
 // (`coerceBorderWidth(...) ?? 1`) where the Player passed any finite number

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.150.1",
+  "version": "0.152.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",