@colixsystems/widget-sdk 0.150.1 → 0.151.0

package/README.md

@@ -72,7 +72,17 @@ 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.151.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+
+### 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)
 
@@ -1687,8 +1697,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

@@ -2961,7 +2961,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",

package/dist/contract.js

@@ -2957,7 +2957,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",

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

package/dist/host.js

@@ -63,12 +63,17 @@ 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.
+// 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,
   resolveTopBarTokens,
+  resolveSidebarUnfold,
 } from "./navigation.js";
 
 // sc-5717: the codec behind `useWidgetRoute()` — how a widget's own internal

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

@@ -366,6 +366,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 +477,4 @@ function borderWidthOr(...values) {
   return BORDER_WIDTH_MIN;
 }
 
-module.exports = { normaliseNavigation, menuItemCap, resolveFooterTokens, resolveSidebarTokens, resolveTopBarTokens };
+module.exports = { normaliseNavigation, menuItemCap, resolveFooterTokens, resolveSidebarTokens, resolveTopBarTokens, resolveSidebarUnfold };

package/dist/navigation.js

@@ -357,6 +357,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/package.json

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