@colixsystems/widget-sdk 0.195.0 → 0.197.0

package/README.md

@@ -77,7 +77,24 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.195.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.197.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.197.0 (contract 1.157.0)
+
+**Host navigation: a page's sidebar menu can be opened from any page.** `resolveSidebarUnfold({ entries, active, sections })` used to answer only the section being viewed, so a host could draw a section's menu only while the visitor was inside it. The result now also carries `trees`: one `{ under, items, standalone, inside }` for every sidebar entry that carries a local menu, in menu order. `inside` is true for the section being viewed, which a host draws open; the others it draws folded behind the entry's arrow. `under`, `items` and `standalone` still describe the viewed section, so existing callers keep working. Widgets are unaffected: this is the host surface (`@colixsystems/widget-sdk/host`), and the widget contract version does not change.
+
+### What's new in 0.196.0 (contract 1.157.0)
+
+**A gradient can carry more than two colours.** A component gradient was exactly `{ from, to, angle }`. It now takes an optional `via` list of up to three middle colours, painted in order and evenly spaced between `from` and `to`:
+
+```js
+{ from: "#0f172a", via: ["#7c3aed", "#db2777"], to: "#f59e0b", angle: 135 }
+```
+
+- **`normaliseComponentGradient`** returns `via` only when the value carries some, so a two-colour gradient normalises exactly as before. A malformed `via` (not a list, more than `CONTRACT.themeComponentGradient.maxViaStops` entries, or an entry that is not a hex colour) is dropped and the two ends still paint, so a stored value never loses its gradient over it. Pass `{ strict: true }` to get `null` for a malformed `via` instead, which is what a write boundary wants.
+- **`componentGradientColors(gradient)`** gives a normalised gradient's colours in paint order, ready for `<Gradient colors={…}>`. **`componentGradientMidpoint(gradient)`** gives the colour halfway along it, the basis for choosing readable text.
+- **`<Card>` and `<Button>` paint the middle colours** when their gradient carries them, and a layout container's wash and photo scrim do the same on the web Player and in the exported app. A middle colour of a container wash may bind to the theme (`"theme:colors.primary"`) like its two ends.
+- **Fully additive.** Every stored two-colour gradient renders byte-identically.
 
 ### What's new in 0.195.0 (contract 1.156.0)
 

package/dist/card-style.js

@@ -5,7 +5,13 @@
 // Every resolver emits ONLY the fields that are set, so a widget's own base
 // style keeps whatever the author left alone.
 
-import { CONTRACT, isHexColor, mixHex, normaliseComponentGradient } from "./contract.js";
+import {
+  CONTRACT,
+  isHexColor,
+  normaliseComponentGradient,
+  componentGradientColors,
+  componentGradientMidpoint,
+} from "./contract.js";
 import { normaliseCornerRadius, cornerRadiusStyle } from "./corner-radius.js";
 import { normaliseSpacing, spacingStyle, isZeroSpacing } from "./spacing.js";
 import { flattenStyle } from "./flatten-style.js";
@@ -117,7 +123,7 @@ export function cardLayoutStyle(style) {
 export function gradientProps(value) {
   const gradient = normaliseComponentGradient(value);
   return gradient
-    ? { colors: [gradient.from, gradient.to], angle: gradient.angle }
+    ? { colors: componentGradientColors(gradient), angle: gradient.angle }
     : null;
 }
 
@@ -131,8 +137,13 @@ export function gradientProps(value) {
  */
 export function cardBackdrop(styles, gradient) {
   if (gradient) {
-    const [from, to] = gradient.colors;
-    return isOpaqueHex(from) && isOpaqueHex(to) ? mixHex(from, to, 0.5) : null;
+    const { colors } = gradient;
+    if (!colors.every(isOpaqueHex)) return null;
+    return componentGradientMidpoint({
+      from: colors[0],
+      via: colors.slice(1, -1),
+      to: colors[colors.length - 1],
+    });
   }
   const fill = flattenStyle(styles).backgroundColor;
   return isOpaqueHex(fill) ? fill : null;

package/dist/contract.cjs

@@ -332,6 +332,8 @@ const THEME_COMPONENT_GRADIENT = Object.freeze({
   angleMin: 0,
   angleMax: 359,
   defaultAngle: 180,
+  // sc-10685: middle colours allowed between the two ends (`via`).
+  maxViaStops: 3,
 });
 
 // REQ-THEME-LOOK: the app-wide SPACING MULTIPLIER. Layout spacing lives on the
@@ -5099,7 +5101,14 @@ const CONTRACT = deepFreeze({
   //    `update(userId, { name?, email? })`, gated on `users.write:*`; the
   //    linter requires that scope for a `.update(` call beside `useUsers(`.
   //    `DirectoryError` gains `reason`, the host's specific refusal code.
-  version: "1.156.0",
+  // 1.157.0: additive (sc-10685) — a component gradient takes an optional
+  //    `via` list of up to `themeComponentGradient.maxViaStops` middle colours
+  //    between `from` and `to`, evenly spaced. `normaliseComponentGradient`
+  //    returns it only when present, so a two-colour value normalises exactly
+  //    as before; a malformed `via` is dropped, or voids the gradient under the
+  //    new `{ strict: true }` option. New `componentGradientColors` / `componentGradientMidpoint`
+  //    read the paint list and the ink basis off a normalised gradient.
+  version: "1.157.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -5418,6 +5427,10 @@ const GRADIENT_HEX_RE = HEX_RE;
 
 /**
  * sc-3727 — normalise a component `gradient` to `{ from, to, angle }`, or `null`.
+ * sc-10685: plus `via`, the middle colours, only when the value carries some.
+ * A malformed `via` is dropped and the two ends still paint, so a stored value
+ * never loses its wash over it; `{ strict: true }` voids the gradient instead,
+ * for the boundaries that must refuse the write.
  *
  * ONE validator for a value arriving by two routes — the theme token and the
  * author's never-coerced per-instance `props.style` — so `set_theme` and the
@@ -5426,7 +5439,7 @@ const GRADIENT_HEX_RE = HEX_RE;
  * hex grammar is also the injection guard — these stops are interpolated into
  * CSS and into generated export source.
  */
-function normaliseComponentGradient(raw) {
+function normaliseComponentGradient(raw, options) {
   if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return null;
   const from = typeof raw.from === "string" ? raw.from.trim() : "";
   const to = typeof raw.to === "string" ? raw.to.trim() : "";
@@ -5436,7 +5449,44 @@ function normaliseComponentGradient(raw) {
   // land NaN in a style.
   const angle = raw.angle;
   const deg = Number.isFinite(angle) ? Math.round(angle) : defaultAngle;
-  return { from, to, angle: ((deg % 360) + 360) % 360 };
+  const via = normaliseGradientVia(raw.via);
+  if (!via && options && options.strict) return null;
+  const gradient = { from, to, angle: ((deg % 360) + 360) % 360 };
+  if (via && via.length > 0) gradient.via = via;
+  return gradient;
+}
+
+// All or nothing: one bad middle colour and none of them paint. `null` = malformed.
+function normaliseGradientVia(raw) {
+  if (raw === undefined || raw === null) return [];
+  if (!Array.isArray(raw) || raw.length > THEME_COMPONENT_GRADIENT.maxViaStops) {
+    return null;
+  }
+  const via = [];
+  for (const item of raw) {
+    const stop = typeof item === "string" ? item.trim() : "";
+    if (!GRADIENT_HEX_RE.test(stop)) return null;
+    via.push(stop);
+  }
+  return via;
+}
+
+/**
+ * sc-10685 — a NORMALISED gradient's colours in paint order, evenly spaced:
+ * `[from, ...via, to]`. The one place both hosts read the list from.
+ */
+function componentGradientColors(gradient) {
+  return [gradient.from, ...(gradient.via || []), gradient.to];
+}
+
+/**
+ * sc-10685 — the colour halfway along a NORMALISED gradient, which is what
+ * text laid across it is contrasted against. Two colours: their mix, as before.
+ */
+function componentGradientMidpoint(gradient) {
+  const colors = componentGradientColors(gradient);
+  const middle = (colors.length - 1) / 2;
+  return mixHex(colors[Math.floor(middle)], colors[Math.ceil(middle)], 0.5);
 }
 
 // REQ-THEME-LOOK: coerce a theme's spacing scale into the usable band. Shared
@@ -5479,6 +5529,8 @@ module.exports = {
   INK_CONTRAST,
   gradientAngleToVector,
   normaliseComponentGradient,
+  componentGradientColors,
+  componentGradientMidpoint,
   isThemeColorTokenRef,
   parseThemeColorTokenRef,
   formatThemeColorTokenRef,

package/dist/contract.js

@@ -332,6 +332,8 @@ const THEME_COMPONENT_GRADIENT = Object.freeze({
   angleMin: 0,
   angleMax: 359,
   defaultAngle: 180,
+  // sc-10685: middle colours allowed between the two ends (`via`).
+  maxViaStops: 3,
 });
 
 // REQ-THEME-LOOK: the app-wide SPACING MULTIPLIER. Layout spacing lives on the
@@ -5095,7 +5097,14 @@ const CONTRACT = deepFreeze({
   //    `update(userId, { name?, email? })`, gated on `users.write:*`; the
   //    linter requires that scope for a `.update(` call beside `useUsers(`.
   //    `DirectoryError` gains `reason`, the host's specific refusal code.
-  version: "1.156.0",
+  // 1.157.0: additive (sc-10685) — a component gradient takes an optional
+  //    `via` list of up to `themeComponentGradient.maxViaStops` middle colours
+  //    between `from` and `to`, evenly spaced. `normaliseComponentGradient`
+  //    returns it only when present, so a two-colour value normalises exactly
+  //    as before; a malformed `via` is dropped, or voids the gradient under the
+  //    new `{ strict: true }` option. New `componentGradientColors` / `componentGradientMidpoint`
+  //    read the paint list and the ink basis off a normalised gradient.
+  version: "1.157.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -5414,6 +5423,10 @@ const GRADIENT_HEX_RE = HEX_RE;
 
 /**
  * sc-3727 — normalise a component `gradient` to `{ from, to, angle }`, or `null`.
+ * sc-10685: plus `via`, the middle colours, only when the value carries some.
+ * A malformed `via` is dropped and the two ends still paint, so a stored value
+ * never loses its wash over it; `{ strict: true }` voids the gradient instead,
+ * for the boundaries that must refuse the write.
  *
  * ONE validator for a value arriving by two routes — the theme token and the
  * author's never-coerced per-instance `props.style` — so `set_theme` and the
@@ -5422,7 +5435,7 @@ const GRADIENT_HEX_RE = HEX_RE;
  * hex grammar is also the injection guard — these stops are interpolated into
  * CSS and into generated export source.
  */
-function normaliseComponentGradient(raw) {
+function normaliseComponentGradient(raw, options) {
   if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return null;
   const from = typeof raw.from === "string" ? raw.from.trim() : "";
   const to = typeof raw.to === "string" ? raw.to.trim() : "";
@@ -5432,7 +5445,44 @@ function normaliseComponentGradient(raw) {
   // land NaN in a style.
   const angle = raw.angle;
   const deg = Number.isFinite(angle) ? Math.round(angle) : defaultAngle;
-  return { from, to, angle: ((deg % 360) + 360) % 360 };
+  const via = normaliseGradientVia(raw.via);
+  if (!via && options && options.strict) return null;
+  const gradient = { from, to, angle: ((deg % 360) + 360) % 360 };
+  if (via && via.length > 0) gradient.via = via;
+  return gradient;
+}
+
+// All or nothing: one bad middle colour and none of them paint. `null` = malformed.
+function normaliseGradientVia(raw) {
+  if (raw === undefined || raw === null) return [];
+  if (!Array.isArray(raw) || raw.length > THEME_COMPONENT_GRADIENT.maxViaStops) {
+    return null;
+  }
+  const via = [];
+  for (const item of raw) {
+    const stop = typeof item === "string" ? item.trim() : "";
+    if (!GRADIENT_HEX_RE.test(stop)) return null;
+    via.push(stop);
+  }
+  return via;
+}
+
+/**
+ * sc-10685 — a NORMALISED gradient's colours in paint order, evenly spaced:
+ * `[from, ...via, to]`. The one place both hosts read the list from.
+ */
+function componentGradientColors(gradient) {
+  return [gradient.from, ...(gradient.via || []), gradient.to];
+}
+
+/**
+ * sc-10685 — the colour halfway along a NORMALISED gradient, which is what
+ * text laid across it is contrasted against. Two colours: their mix, as before.
+ */
+function componentGradientMidpoint(gradient) {
+  const colors = componentGradientColors(gradient);
+  const middle = (colors.length - 1) / 2;
+  return mixHex(colors[Math.floor(middle)], colors[Math.ceil(middle)], 0.5);
 }
 
 // REQ-THEME-LOOK: coerce a theme's spacing scale into the usable band. Shared
@@ -5475,6 +5525,8 @@ export {
   INK_CONTRAST,
   gradientAngleToVector,
   normaliseComponentGradient,
+  componentGradientColors,
+  componentGradientMidpoint,
   isThemeColorTokenRef,
   parseThemeColorTokenRef,
   formatThemeColorTokenRef,

package/dist/host.d.ts

@@ -254,14 +254,26 @@ export interface SidebarUnfoldItem {
   [field: string]: unknown;
 }
 
+/** One section's local menu and the sidebar entry it hangs beneath. `inside`
+ *  marks the section the visitor is in — the one that starts unfolded. */
+export interface SidebarUnfoldTree {
+  under: string;
+  items: Array<SidebarUnfoldItem & { current: boolean }>;
+  standalone: boolean;
+  inside: boolean;
+}
+
 /** 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. */
+ *  `under` is the global menu entry the visitor's own section hangs beneath,
+ *  or null when they are in none. `standalone` marks the case where the global
+ *  menu does not list the page, so the page itself is the entry. `trees` is
+ *  every section an entry carries, in menu order, so an entry can offer its
+ *  menu from any page; a `standalone` tree comes last. */
 export interface SidebarUnfold {
   under: string | null;
   items: Array<SidebarUnfoldItem & { current: boolean }>;
   standalone: boolean;
+  trees: SidebarUnfoldTree[];
 }
 
 /** Resolve where the viewed page's local menu unfolds in the sidebar and the

package/dist/index.d.ts

@@ -3449,18 +3449,30 @@ export interface ComponentGradient {
   from: string;
   to: string;
   angle: number;
+  /** Middle colours between `from` and `to`. Present only when there are some. */
+  via?: string[];
 }
 
 /**
  * Normalise a component `gradient` style value to `{ from, to, angle }`, or null
  * when it is unusable. Both stops are required; the angle wraps into 0-359.
+ * An optional `via` list (at most `CONTRACT.themeComponentGradient.maxViaStops`
+ * hex colours) is kept as given. A malformed one is dropped and the two ends
+ * still paint; pass `{ strict: true }` to get null for it instead.
  * Shared by the theme-token coercion and the widget render path, so the same
  * value cannot resolve two ways.
  */
 export function normaliseComponentGradient(
   raw: unknown,
+  options?: { strict?: boolean },
 ): ComponentGradient | null;
 
+/** A normalised gradient's colours in paint order: `[from, ...via, to]`. */
+export function componentGradientColors(gradient: ComponentGradient): string[];
+
+/** The colour halfway along a normalised gradient: the basis for text ink. */
+export function componentGradientMidpoint(gradient: ComponentGradient): string;
+
 /** sc-8326 — the `theme:<path>` binding prefix, shared with the hosts' resolver. */
 export const THEME_TOKEN_REF_PREFIX: string;
 

package/dist/index.js

@@ -178,6 +178,8 @@ export {
   deriveAccentTints,
   gradientAngleToVector,
   normaliseComponentGradient,
+  componentGradientColors,
+  componentGradientMidpoint,
   isThemeColorTokenRef,
   parseThemeColorTokenRef,
   formatThemeColorTokenRef,

package/dist/index.native.js

@@ -171,6 +171,8 @@ export {
   deriveAccentTints,
   gradientAngleToVector,
   normaliseComponentGradient,
+  componentGradientColors,
+  componentGradientMidpoint,
   isThemeColorTokenRef,
   parseThemeColorTokenRef,
   formatThemeColorTokenRef,

package/dist/navigation.cjs

@@ -636,21 +636,25 @@ function resolveTopBarTokens(theme) {
  * inside it, so the menu is never lost — a section off the menu is exactly
  * the case that would otherwise render blank.
  *
+ * sc-10693: `trees` answers EVERY section, not only the visitor's own, so a
+ * section's entry can offer its menu from any page. `under` / `items` /
+ * `standalone` still name the one the visitor is inside.
+ *
  * @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.
+ * @returns {{ under: string|null, items: Array<object>, standalone: boolean, trees: Array<object> }}
+ *   `under` is null when the visitor is in no section; 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. `trees` lists `{ under, items, standalone, inside }` in menu
+ *   order, a `standalone` one last; `inside` marks the visitor's own.
  */
 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 viewed = typeof active === "string" && active ? active : null;
   const bank = isPlainObject(sections) ? sections : {};
   const order = Array.isArray(entries) ? entries : [];
   const sectionAt = (key) => {
@@ -663,31 +667,60 @@ function resolveSidebarUnfold(input) {
     return (
       Boolean(candidate) &&
       candidate.items.some(
-        (item) => isPlainObject(item) && item.key === active,
+        (item) => isPlainObject(item) && item.key === viewed,
       )
     );
   };
   // 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 };
+  const section = viewed
+    ? sectionAt(viewed) ||
+      sectionAt(order.find(lists)) ||
+      sectionAt(Object.keys(bank).find(lists))
+    : null;
+  const mark = (items) =>
+    items.map((item) => ({
+      ...(isPlainObject(item) ? item : {}),
+      current:
+        viewed !== null &&
+        isPlainObject(item) &&
+        typeof item.key === "string" &&
+        item.key === viewed,
+    }));
+  // A saved menu hangs under the FIRST global entry carrying it, so two
+  // entries sharing one menu never draw it twice.
+  const claimed = [];
+  const trees = [];
+  for (const key of order) {
+    if (!isPlainObject(bank[key])) continue;
+    const { menu } = bank[key];
+    if (claimed.includes(menu)) continue;
+    claimed.push(menu);
+    // An unusable key still owns its menu: nothing may hang it elsewhere.
+    if (typeof key !== "string" || !key) continue;
+    const inside = Boolean(section) && menu === section.menu;
+    const own = inside ? section : sectionAt(key);
+    if (!own) continue;
+    trees.push({ under: key, items: mark(own.items), standalone: false, inside });
+  }
+  if (!section) return { under: null, items: [], standalone: false, trees };
+  const owned = trees.find((tree) => tree.inside);
+  if (owned) {
+    return { under: owned.under, items: owned.items, standalone: false, trees };
   }
-  return { under: section.key, items: marked, standalone: true };
+  const alone = {
+    under: section.key,
+    items: mark(section.items),
+    standalone: true,
+    inside: true,
+  };
+  return {
+    under: alone.under,
+    items: alone.items,
+    standalone: true,
+    trees: [...trees, alone],
+  };
 }
 
 /**

package/dist/navigation.js

@@ -627,21 +627,25 @@ export function resolveTopBarTokens(theme) {
  * inside it, so the menu is never lost — a section off the menu is exactly
  * the case that would otherwise render blank.
  *
+ * sc-10693: `trees` answers EVERY section, not only the visitor's own, so a
+ * section's entry can offer its menu from any page. `under` / `items` /
+ * `standalone` still name the one the visitor is inside.
+ *
  * @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.
+ * @returns {{ under: string|null, items: Array<object>, standalone: boolean, trees: Array<object> }}
+ *   `under` is null when the visitor is in no section; 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. `trees` lists `{ under, items, standalone, inside }` in menu
+ *   order, a `standalone` one last; `inside` marks the visitor's own.
  */
 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 viewed = typeof active === "string" && active ? active : null;
   const bank = isPlainObject(sections) ? sections : {};
   const order = Array.isArray(entries) ? entries : [];
   const sectionAt = (key) => {
@@ -654,31 +658,60 @@ export function resolveSidebarUnfold(input) {
     return (
       Boolean(candidate) &&
       candidate.items.some(
-        (item) => isPlainObject(item) && item.key === active,
+        (item) => isPlainObject(item) && item.key === viewed,
       )
     );
   };
   // 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 };
+  const section = viewed
+    ? sectionAt(viewed) ||
+      sectionAt(order.find(lists)) ||
+      sectionAt(Object.keys(bank).find(lists))
+    : null;
+  const mark = (items) =>
+    items.map((item) => ({
+      ...(isPlainObject(item) ? item : {}),
+      current:
+        viewed !== null &&
+        isPlainObject(item) &&
+        typeof item.key === "string" &&
+        item.key === viewed,
+    }));
+  // A saved menu hangs under the FIRST global entry carrying it, so two
+  // entries sharing one menu never draw it twice.
+  const claimed = [];
+  const trees = [];
+  for (const key of order) {
+    if (!isPlainObject(bank[key])) continue;
+    const { menu } = bank[key];
+    if (claimed.includes(menu)) continue;
+    claimed.push(menu);
+    // An unusable key still owns its menu: nothing may hang it elsewhere.
+    if (typeof key !== "string" || !key) continue;
+    const inside = Boolean(section) && menu === section.menu;
+    const own = inside ? section : sectionAt(key);
+    if (!own) continue;
+    trees.push({ under: key, items: mark(own.items), standalone: false, inside });
+  }
+  if (!section) return { under: null, items: [], standalone: false, trees };
+  const owned = trees.find((tree) => tree.inside);
+  if (owned) {
+    return { under: owned.under, items: owned.items, standalone: false, trees };
   }
-  return { under: section.key, items: marked, standalone: true };
+  const alone = {
+    under: section.key,
+    items: mark(section.items),
+    standalone: true,
+    inside: true,
+  };
+  return {
+    under: alone.under,
+    items: alone.items,
+    standalone: true,
+    trees: [...trees, alone],
+  };
 }
 
 /**

package/dist/theme-token-refs.js

@@ -148,7 +148,9 @@ function resolveAgainstSchema(schema, value, theme) {
 // VALUES — colours, sizes, enums — so an allowlisted `theme:` string in it can
 // only ever have been a binding. The depth cap keeps the walk bounded for the
 // structured style values (a gradient's stops, per-corner radii).
-const MAX_STYLE_DEPTH = 3;
+// sc-10685: 4, so a widget gradient's `via` list (style > gradient > via >
+// item) resolves like its two ends.
+const MAX_STYLE_DEPTH = 4;
 
 function resolveStyleBag(value, theme, depth) {
   if (typeof value === "string") {

package/package.json

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

package/src/contract.js

@@ -332,6 +332,8 @@ const THEME_COMPONENT_GRADIENT = Object.freeze({
   angleMin: 0,
   angleMax: 359,
   defaultAngle: 180,
+  // sc-10685: middle colours allowed between the two ends (`via`).
+  maxViaStops: 3,
 });
 
 // REQ-THEME-LOOK: the app-wide SPACING MULTIPLIER. Layout spacing lives on the
@@ -5095,7 +5097,14 @@ const CONTRACT = deepFreeze({
   //    `update(userId, { name?, email? })`, gated on `users.write:*`; the
   //    linter requires that scope for a `.update(` call beside `useUsers(`.
   //    `DirectoryError` gains `reason`, the host's specific refusal code.
-  version: "1.156.0",
+  // 1.157.0: additive (sc-10685) — a component gradient takes an optional
+  //    `via` list of up to `themeComponentGradient.maxViaStops` middle colours
+  //    between `from` and `to`, evenly spaced. `normaliseComponentGradient`
+  //    returns it only when present, so a two-colour value normalises exactly
+  //    as before; a malformed `via` is dropped, or voids the gradient under the
+  //    new `{ strict: true }` option. New `componentGradientColors` / `componentGradientMidpoint`
+  //    read the paint list and the ink basis off a normalised gradient.
+  version: "1.157.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -5414,6 +5423,10 @@ const GRADIENT_HEX_RE = HEX_RE;
 
 /**
  * sc-3727 — normalise a component `gradient` to `{ from, to, angle }`, or `null`.
+ * sc-10685: plus `via`, the middle colours, only when the value carries some.
+ * A malformed `via` is dropped and the two ends still paint, so a stored value
+ * never loses its wash over it; `{ strict: true }` voids the gradient instead,
+ * for the boundaries that must refuse the write.
  *
  * ONE validator for a value arriving by two routes — the theme token and the
  * author's never-coerced per-instance `props.style` — so `set_theme` and the
@@ -5422,7 +5435,7 @@ const GRADIENT_HEX_RE = HEX_RE;
  * hex grammar is also the injection guard — these stops are interpolated into
  * CSS and into generated export source.
  */
-function normaliseComponentGradient(raw) {
+function normaliseComponentGradient(raw, options) {
   if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return null;
   const from = typeof raw.from === "string" ? raw.from.trim() : "";
   const to = typeof raw.to === "string" ? raw.to.trim() : "";
@@ -5432,7 +5445,44 @@ function normaliseComponentGradient(raw) {
   // land NaN in a style.
   const angle = raw.angle;
   const deg = Number.isFinite(angle) ? Math.round(angle) : defaultAngle;
-  return { from, to, angle: ((deg % 360) + 360) % 360 };
+  const via = normaliseGradientVia(raw.via);
+  if (!via && options && options.strict) return null;
+  const gradient = { from, to, angle: ((deg % 360) + 360) % 360 };
+  if (via && via.length > 0) gradient.via = via;
+  return gradient;
+}
+
+// All or nothing: one bad middle colour and none of them paint. `null` = malformed.
+function normaliseGradientVia(raw) {
+  if (raw === undefined || raw === null) return [];
+  if (!Array.isArray(raw) || raw.length > THEME_COMPONENT_GRADIENT.maxViaStops) {
+    return null;
+  }
+  const via = [];
+  for (const item of raw) {
+    const stop = typeof item === "string" ? item.trim() : "";
+    if (!GRADIENT_HEX_RE.test(stop)) return null;
+    via.push(stop);
+  }
+  return via;
+}
+
+/**
+ * sc-10685 — a NORMALISED gradient's colours in paint order, evenly spaced:
+ * `[from, ...via, to]`. The one place both hosts read the list from.
+ */
+function componentGradientColors(gradient) {
+  return [gradient.from, ...(gradient.via || []), gradient.to];
+}
+
+/**
+ * sc-10685 — the colour halfway along a NORMALISED gradient, which is what
+ * text laid across it is contrasted against. Two colours: their mix, as before.
+ */
+function componentGradientMidpoint(gradient) {
+  const colors = componentGradientColors(gradient);
+  const middle = (colors.length - 1) / 2;
+  return mixHex(colors[Math.floor(middle)], colors[Math.ceil(middle)], 0.5);
 }
 
 // REQ-THEME-LOOK: coerce a theme's spacing scale into the usable band. Shared
@@ -5475,6 +5525,8 @@ export {
   INK_CONTRAST,
   gradientAngleToVector,
   normaliseComponentGradient,
+  componentGradientColors,
+  componentGradientMidpoint,
   isThemeColorTokenRef,
   parseThemeColorTokenRef,
   formatThemeColorTokenRef,