@colixsystems/widget-sdk 0.150.0 → 0.151.0

package/README.md

@@ -72,9 +72,27 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.149.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.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.149.0 (contract 1.117.0)
+### 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)
+
+**A capability's fallback belongs to the web build, not to native (sc-8381).** The barcode guidance here, in the in-Studio hooks reference and in both AI agents' prompts told you to gate the scan button on `supported` **and** keep a manual-entry path — unconditionally, while the reason given was a browser-only gap. `supported` is always `true` on the Expo export, so that read shipped a redundant "or type the code" field on every phone: the exact typing the scanner exists to remove. The rule is now scoped to the host that actually fails the gate.
+
+- **Gate the substitute on the same flag that gates the button.** Where `supported` is `false` — the web Player in Safari and Firefox, which ship no `BarcodeDetector` — render the typed field instead of the scan button. Where it is `true`, the capability is the whole input. Nothing about the API changed; only the guidance did.
+- **A native `catch` is an error state, not a web substitute.** The `react-native-nfc-manager` notes said to render "the same fallback from the `catch` that `widget.web.jsx` uses". A workspace that has not switched the NFC device capability on in Publish settings is a **misconfiguration** the widget should name, not a reason to park a permanent manual-entry field beside the tap target.
+- **The web half is still required.** This narrows where a *substitute* belongs; it does not relax the parity rule. A native-only capability still ships a real way in on `widget.web.jsx` — a typed code, a QR scan, a non-sensor path — and still degrades visibly rather than rendering blank.
+
+### What's new in 0.150.0 (contract 1.118.0)
 
 **New primitive `<EmojiPicker>` — pick an emoji without leaving for the OS keyboard (sc-8104).** Typed emoji always worked: a plain `<TextInput>` stores and renders them on both hosts, and nothing about that changes. What was missing was an in-app way to *choose* one — for a message composer, or to react to something.
 
@@ -99,6 +117,10 @@ It presents inside `<Overlay>`, so it escapes the widget's clipping box on both
 
 **Also new: a shared reaction model.** `groupReactions(rows, { typeField, userField, userId })` turns reaction rows into per-emoji pill groups — one row per (target, user, emoji), de-duplicated per user — and `readReactionEmoji(value)` maps a stored value to its emoji, ignoring anything it does not recognise. Widgets storing reactions should group through these rather than rolling their own, so pills behave identically wherever they appear.
 
+### What's new in 0.149.0 (contract 1.117.0)
+
+**Six text roles on the theme, so every widget speaks one typographic voice (sc-8058).** See the theme section above for the roles and how to read them.
+
 ### What's new in 0.148.0 (contract 1.116.0)
 
 **New `useAgent(agentRef)` hook — a widget can talk to the WORKSPACE's own AI agent (sc-7991).** A new `agents` host client (`@colixsystems/agents-client`), a new `agentRef` propertySchema type and a new `ai.invoke:*` scope. Everything is additive; nothing existing changes shape.
@@ -299,7 +321,7 @@ Also tightened in this release: the `publicGrant` flags are now type-checked. Th
 **NFC tags are vetted, native-only (`react-native-nfc-manager`).** A widget can now read and write NFC tags on the Expo export — NDEF over `NfcManager.requestTechnology(NfcTech.Ndef)`, plus the raw technologies a badge, asset tag or transit card uses: `NfcTech.IsoDep` on both hosts, `NfcTech.MifareClassic` on Android, `NfcTech.MifareIOS` / `FelicaIOS` / `Iso15693IOS` on iOS. (There is no `NfcTech.FeliCa` — check `index.d.ts` before naming one.) This is the last common "tap a physical thing" input the allowlist was missing; barcode and QR already had `useBarcodeScanner()`.
 
 - **Native-only, and the browser is why.** Web NFC ships in Chrome on Android alone — Safari, Firefox and every desktop browser omit it — so there is no web build to pair with. Put the import in `widget.native.jsx` and give `widget.web.jsx` a real way in: a typed code field, or the SDK's `useBarcodeScanner()` QR path. The linter's `import-platform-mismatch` enforces the split.
-- **Opt-in per workspace — and `isSupported()` cannot see that.** The export claims the iOS NFC entitlement and the Android `NFC` permission only when the publisher enables the **NFC tags** device capability in Publish settings. `isSupported()` probes the **device** (`readingAvailable` on iOS, `hasSystemFeature` on Android), not the gate: on a capable phone in an app that never asked, it returns `true` and the read then fails — Android throws a `SecurityException` from `registerTagEvent`, iOS cannot open the reader session. So wrap `start()` / `requestTechnology()` in a `try` and render the **same** fallback from the `catch` that `widget.web.jsx` uses. That `catch` is the degradation path.
+- **Opt-in per workspace — and `isSupported()` cannot see that.** The export claims the iOS NFC entitlement and the Android `NFC` permission only when the publisher enables the **NFC tags** device capability in Publish settings. `isSupported()` probes the **device** (`readingAvailable` on iOS, `hasSystemFeature` on Android), not the gate: on a capable phone in an app that never asked, it returns `true` and the read then fails — Android throws a `SecurityException` from `registerTagEvent`, iOS cannot open the reader session. So wrap `start()` / `requestTechnology()` in a `try` and render a clear **error state** from the `catch` — name what is missing and say the capability has to be switched on in Publish settings. That `catch` is an error path, **not** the web build's typed-code substitute: do not give `widget.native.jsx` a permanent manual-entry field beside the tap target, because in a correctly-configured app the radio works and the field is the typing the tag was meant to replace.
 - **Clean up the session.** `cancelTechnologyRequest()` in your effect cleanup; an abandoned request leaves the reader sheet up on iOS.
 - **It is a write capability too.** Read with `getNdefMessage()`; write with `writeNdefMessage(bytes)`, `formatNdef(bytes)` (Android only, for a blank tag) and `transceive(bytes)` on the `IsoDep` / `NfcA` / `NfcV` handlers. One capability covers both — Android expresses read and write through the single `android.permission.NFC` — so the workspace owner who enables it is consenting to every widget in the workspace being able to rewrite the tags their users tap. Raw ISO7816 `transceive` on iOS additionally needs `select-identifiers` on the entitlement, which the export does not declare; NDEF read and write work on both hosts.
 - **`makeReadOnly()` is irreversible.** It permanently locks the tag — no later write will ever succeed, on any device, by any app. Call it only where the feature genuinely wants a one-time-programmable tag, and never as a cleanup step after writing.
@@ -378,13 +400,19 @@ const hit = await scan();          // { value, format } | null
 
 It is deliberately **one-shot** rather than a start/stop subscription — to read several codes, call `scan()` again. There is no loop to leave running and no camera to forget to release.
 
-**Gate the button on `supported`, and always keep a manual-entry path.** `BarcodeDetector` is Chromium-only today, so the web Player reports `supported: false` in Safari and Firefox. That is a genuine browser gap, not a missing feature, so a scanner must never be the only way to enter a code:
+**Gate the button on `supported`, and keep the manual-entry path for the host that fails that gate.** `BarcodeDetector` is Chromium-only today, so the web Player reports `supported: false` in Safari and Firefox — a genuine browser gap, not a missing feature, and there the scanner must not be the only way to enter a code. The Expo export always reports `true`, so do **not** mirror the typed field onto native: on the phone the scanner is the whole input, and the twin field is the typing the scan was meant to remove. Gate the substitute on the same flag that gates the button:
 
 ```jsx
-<TextInput value={code} onChangeText={setCode} />
-{supported ? <Pressable onPress={scan}><Text>Scan</Text></Pressable> : null}
+{supported
+  ? <Pressable onPress={scan}><Text>Scan</Text></Pressable>
+  : <TextInput value={code} onChangeText={setCode} placeholder="Enter the code" />}
+{/* On the phone there is no typed field to fall back to, so a denied
+    camera has to say so rather than leave a button that does nothing. */}
+{error ? <Text>Camera access is off — turn it on in Settings to scan.</Text> : null}
 ```
 
+That error line is not optional on native. `supported` is `true` there, so the scan button is the only way in — a `PERMISSION_DENIED` the widget swallows leaves the user tapping a control that silently does nothing.
+
 **Host-brokered, not a vetted import.** Like the camera and speech-to-text, your widget never imports the native module: `expo-camera` is pinned by the Expo export only, so a widget that does not scan gains no native dependency and nothing new enters widget bundles.
 
 ### What's new in 0.128.0 (contract 1.99.0 — unchanged)
@@ -1669,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

@@ -1860,9 +1860,12 @@ const HOOKS = [
       "PERMISSION_DENIED | UNSUPPORTED | INTERNAL. `value` is the decoded text; `format` is a lowercase symbology name " +
       "(qr_code, code_128, ean_13, …) — treat it as a hint, not a promise, because the two hosts detect different sets. " +
       "It is deliberately ONE-SHOT rather than a start/stop subscription: to scan several codes, call scan() again. " +
-      "reset() clears the last result and error. ALWAYS check `supported` before rendering a scan button and give the " +
-      "widget a manual-entry path — the web Player reports false wherever the browser has no BarcodeDetector (Safari and " +
-      "Firefox today), which is a real browser gap, not a missing feature. options: { formats } is a HINT narrowing the " +
+      "reset() clears the last result and error. ALWAYS check `supported` before rendering a scan button, and give the " +
+      "widget a manual-entry path WHERE THAT GUARD FAILS — which is the WEB Player, wherever the browser ships no " +
+      "BarcodeDetector (Safari and Firefox today), a real browser gap rather than a missing feature. The Expo export " +
+      "ALWAYS reports true, so do NOT pair the scan button with a typed-code twin there: on the phone the scanner is the " +
+      "whole input, and a redundant 'or type it in' field is the manual step the capability exists to remove. " +
+      "options: { formats } is a HINT narrowing the " +
       "symbologies to look for. The Expo export scans via expo-camera; the web Player via BarcodeDetector over the same " +
       "getUserMedia preview useCamera() uses. The camera is released on every exit path, including a dismissal.",
     returnShape: {
@@ -2634,7 +2637,8 @@ const WIDGET_CONTEXT_SHAPE = {
       "BarcodeError (.code PERMISSION_DENIED | UNSUPPORTED | INTERNAL). Its formats hint and its format output BOTH speak " +
       "BarcodeDetector names (qr_code, code_128, ean_13, ...) on both hosts; the Expo export maps them to expo-camera own " +
       "vocabulary internally and DROPS a name it cannot map. isSupported() is false wherever the browser ships no " +
-      "BarcodeDetector (Safari, Firefox), so a widget must always offer manual entry beside a scan button. " +
+      "BarcodeDetector (Safari, Firefox), so a WEB build must offer manual entry beside a scan button; the Expo export " +
+      "always reports true and takes the scanner alone — no typed-code twin on native. " +
       "sc-6450 — the geolocation background-watch members are NATIVE-ONLY and opt-in per app: the web Player and an export that " +
       "did not opt in both report isBackgroundSupported() false, and the Expo export backs it with expo-location + " +
       "expo-task-manager. subscribeBackgroundPositions and subscribeBackgroundWatchState are plain subscriptions — they start no " +
@@ -2957,14 +2961,14 @@ 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",
     platforms: ["native"],
     category: "system",
     description:
-      "Read and write NFC tags on the Expo export: NDEF records via NfcManager.requestTechnology(NfcTech.Ndef), plus the raw technologies a badge, asset tag or transit card uses - NfcTech.IsoDep on both hosts, NfcTech.MifareClassic on Android, NfcTech.MifareIOS / FelicaIOS / Iso15693IOS on iOS (there is no NfcTech.FeliCa; check index.d.ts before naming one). Read with ndefHandler.getNdefMessage(); WRITE with writeNdefMessage(bytes), formatNdef(bytes) (Android only, for a blank tag) and transceive(bytes) on the IsoDep / NfcA / NfcV handlers. makeReadOnly() PERMANENTLY locks a tag - it cannot be undone and no later write will ever succeed, so call it only where the brief actually asks for a one-time-programmable tag, never as a tidy-up step. Raw ISO7816 transceive on iOS additionally needs select-identifiers on the entitlement, which this export does not declare - NDEF read and write work on both hosts. Always cancelTechnologyRequest() in a cleanup - an abandoned session leaves the reader sheet up on iOS. Native-only because no browser hands the Player a reader: Web NFC exists in Chrome on Android alone (Safari, Firefox and every desktop browser omit it), so there is no web build to pair with. Author it in widget.native.jsx and give widget.web.jsx a real way in instead - a typed code field, or the SDK's useBarcodeScanner() QR path. The radio is ALSO opt-in per workspace: the export claims the iOS NFC entitlement and the Android NFC permission only when the publisher enables the 'nfc' device capability in Publish settings. isSupported() does NOT see that gate - it probes the DEVICE (readingAvailable on iOS, hasSystemFeature on Android), so on a capable phone in an app that never asked it returns true and the read then fails: Android throws a SecurityException from registerTagEvent, iOS cannot open the reader session. So wrap start() / requestTechnology() in a try and render the SAME fallback from the catch that widget.web.jsx uses - that catch IS the degradation path, not a nicety. Pinned at 3.17.2, the current stable release (4.x is still beta); a community package, so Expo bundledNativeModules has no version opinion on it.",
+      "Read and write NFC tags on the Expo export: NDEF records via NfcManager.requestTechnology(NfcTech.Ndef), plus the raw technologies a badge, asset tag or transit card uses - NfcTech.IsoDep on both hosts, NfcTech.MifareClassic on Android, NfcTech.MifareIOS / FelicaIOS / Iso15693IOS on iOS (there is no NfcTech.FeliCa; check index.d.ts before naming one). Read with ndefHandler.getNdefMessage(); WRITE with writeNdefMessage(bytes), formatNdef(bytes) (Android only, for a blank tag) and transceive(bytes) on the IsoDep / NfcA / NfcV handlers. makeReadOnly() PERMANENTLY locks a tag - it cannot be undone and no later write will ever succeed, so call it only where the brief actually asks for a one-time-programmable tag, never as a tidy-up step. Raw ISO7816 transceive on iOS additionally needs select-identifiers on the entitlement, which this export does not declare - NDEF read and write work on both hosts. Always cancelTechnologyRequest() in a cleanup - an abandoned session leaves the reader sheet up on iOS. Native-only because no browser hands the Player a reader: Web NFC exists in Chrome on Android alone (Safari, Firefox and every desktop browser omit it), so there is no web build to pair with. Author it in widget.native.jsx and give widget.web.jsx a real way in instead - a typed code field, or the SDK's useBarcodeScanner() QR path. The radio is ALSO opt-in per workspace: the export claims the iOS NFC entitlement and the Android NFC permission only when the publisher enables the 'nfc' device capability in Publish settings. isSupported() does NOT see that gate - it probes the DEVICE (readingAvailable on iOS, hasSystemFeature on Android), so on a capable phone in an app that never asked it returns true and the read then fails: Android throws a SecurityException from registerTagEvent, iOS cannot open the reader session. So wrap start() / requestTechnology() in a try and render a clear ERROR STATE from the catch - name what is missing and say the maker must switch 'nfc' on in Publish settings. That catch is an ERROR path, NOT the web build's typed-code substitute: do not give widget.native.jsx a permanent manual-entry field beside the tap target, because in a correctly-configured app the radio works and the field is the typing the tag was meant to replace. Pinned at 3.17.2, the current stable release (4.x is still beta); a community package, so Expo bundledNativeModules has no version opinion on it.",
   },
   {
     specifier: "decimal.js",

package/dist/contract.js

@@ -1860,9 +1860,12 @@ const HOOKS = [
       "PERMISSION_DENIED | UNSUPPORTED | INTERNAL. `value` is the decoded text; `format` is a lowercase symbology name " +
       "(qr_code, code_128, ean_13, …) — treat it as a hint, not a promise, because the two hosts detect different sets. " +
       "It is deliberately ONE-SHOT rather than a start/stop subscription: to scan several codes, call scan() again. " +
-      "reset() clears the last result and error. ALWAYS check `supported` before rendering a scan button and give the " +
-      "widget a manual-entry path — the web Player reports false wherever the browser has no BarcodeDetector (Safari and " +
-      "Firefox today), which is a real browser gap, not a missing feature. options: { formats } is a HINT narrowing the " +
+      "reset() clears the last result and error. ALWAYS check `supported` before rendering a scan button, and give the " +
+      "widget a manual-entry path WHERE THAT GUARD FAILS — which is the WEB Player, wherever the browser ships no " +
+      "BarcodeDetector (Safari and Firefox today), a real browser gap rather than a missing feature. The Expo export " +
+      "ALWAYS reports true, so do NOT pair the scan button with a typed-code twin there: on the phone the scanner is the " +
+      "whole input, and a redundant 'or type it in' field is the manual step the capability exists to remove. " +
+      "options: { formats } is a HINT narrowing the " +
       "symbologies to look for. The Expo export scans via expo-camera; the web Player via BarcodeDetector over the same " +
       "getUserMedia preview useCamera() uses. The camera is released on every exit path, including a dismissal.",
     returnShape: {
@@ -2630,7 +2633,8 @@ const WIDGET_CONTEXT_SHAPE = {
       "BarcodeError (.code PERMISSION_DENIED | UNSUPPORTED | INTERNAL). Its formats hint and its format output BOTH speak " +
       "BarcodeDetector names (qr_code, code_128, ean_13, ...) on both hosts; the Expo export maps them to expo-camera own " +
       "vocabulary internally and DROPS a name it cannot map. isSupported() is false wherever the browser ships no " +
-      "BarcodeDetector (Safari, Firefox), so a widget must always offer manual entry beside a scan button. " +
+      "BarcodeDetector (Safari, Firefox), so a WEB build must offer manual entry beside a scan button; the Expo export " +
+      "always reports true and takes the scanner alone — no typed-code twin on native. " +
       "sc-6450 — the geolocation background-watch members are NATIVE-ONLY and opt-in per app: the web Player and an export that " +
       "did not opt in both report isBackgroundSupported() false, and the Expo export backs it with expo-location + " +
       "expo-task-manager. subscribeBackgroundPositions and subscribeBackgroundWatchState are plain subscriptions — they start no " +
@@ -2953,14 +2957,14 @@ 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",
     platforms: ["native"],
     category: "system",
     description:
-      "Read and write NFC tags on the Expo export: NDEF records via NfcManager.requestTechnology(NfcTech.Ndef), plus the raw technologies a badge, asset tag or transit card uses - NfcTech.IsoDep on both hosts, NfcTech.MifareClassic on Android, NfcTech.MifareIOS / FelicaIOS / Iso15693IOS on iOS (there is no NfcTech.FeliCa; check index.d.ts before naming one). Read with ndefHandler.getNdefMessage(); WRITE with writeNdefMessage(bytes), formatNdef(bytes) (Android only, for a blank tag) and transceive(bytes) on the IsoDep / NfcA / NfcV handlers. makeReadOnly() PERMANENTLY locks a tag - it cannot be undone and no later write will ever succeed, so call it only where the brief actually asks for a one-time-programmable tag, never as a tidy-up step. Raw ISO7816 transceive on iOS additionally needs select-identifiers on the entitlement, which this export does not declare - NDEF read and write work on both hosts. Always cancelTechnologyRequest() in a cleanup - an abandoned session leaves the reader sheet up on iOS. Native-only because no browser hands the Player a reader: Web NFC exists in Chrome on Android alone (Safari, Firefox and every desktop browser omit it), so there is no web build to pair with. Author it in widget.native.jsx and give widget.web.jsx a real way in instead - a typed code field, or the SDK's useBarcodeScanner() QR path. The radio is ALSO opt-in per workspace: the export claims the iOS NFC entitlement and the Android NFC permission only when the publisher enables the 'nfc' device capability in Publish settings. isSupported() does NOT see that gate - it probes the DEVICE (readingAvailable on iOS, hasSystemFeature on Android), so on a capable phone in an app that never asked it returns true and the read then fails: Android throws a SecurityException from registerTagEvent, iOS cannot open the reader session. So wrap start() / requestTechnology() in a try and render the SAME fallback from the catch that widget.web.jsx uses - that catch IS the degradation path, not a nicety. Pinned at 3.17.2, the current stable release (4.x is still beta); a community package, so Expo bundledNativeModules has no version opinion on it.",
+      "Read and write NFC tags on the Expo export: NDEF records via NfcManager.requestTechnology(NfcTech.Ndef), plus the raw technologies a badge, asset tag or transit card uses - NfcTech.IsoDep on both hosts, NfcTech.MifareClassic on Android, NfcTech.MifareIOS / FelicaIOS / Iso15693IOS on iOS (there is no NfcTech.FeliCa; check index.d.ts before naming one). Read with ndefHandler.getNdefMessage(); WRITE with writeNdefMessage(bytes), formatNdef(bytes) (Android only, for a blank tag) and transceive(bytes) on the IsoDep / NfcA / NfcV handlers. makeReadOnly() PERMANENTLY locks a tag - it cannot be undone and no later write will ever succeed, so call it only where the brief actually asks for a one-time-programmable tag, never as a tidy-up step. Raw ISO7816 transceive on iOS additionally needs select-identifiers on the entitlement, which this export does not declare - NDEF read and write work on both hosts. Always cancelTechnologyRequest() in a cleanup - an abandoned session leaves the reader sheet up on iOS. Native-only because no browser hands the Player a reader: Web NFC exists in Chrome on Android alone (Safari, Firefox and every desktop browser omit it), so there is no web build to pair with. Author it in widget.native.jsx and give widget.web.jsx a real way in instead - a typed code field, or the SDK's useBarcodeScanner() QR path. The radio is ALSO opt-in per workspace: the export claims the iOS NFC entitlement and the Android NFC permission only when the publisher enables the 'nfc' device capability in Publish settings. isSupported() does NOT see that gate - it probes the DEVICE (readingAvailable on iOS, hasSystemFeature on Android), so on a capable phone in an app that never asked it returns true and the read then fails: Android throws a SecurityException from registerTagEvent, iOS cannot open the reader session. So wrap start() / requestTechnology() in a try and render a clear ERROR STATE from the catch - name what is missing and say the maker must switch 'nfc' on in Publish settings. That catch is an ERROR path, NOT the web build's typed-code substitute: do not give widget.native.jsx a permanent manual-entry field beside the tap target, because in a correctly-configured app the radio works and the field is the typing the tag was meant to replace. Pinned at 3.17.2, the current stable release (4.x is still beta); a community package, so Expo bundledNativeModules has no version opinion on it.",
   },
   {
     specifier: "decimal.js",

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.0",
+  "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",