@colixsystems/widget-sdk 0.96.0 → 0.98.0

package/README.md

@@ -64,7 +64,42 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.91.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.95.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.95.0 (contract 1.68.0)
+
+**One number for the quick bar's cap — `quickBarMaxItems` + `quickBarCap`.** The sidebar's secondary mobile quick bar caps at five, and that five lived in two places: a named constant in the web chrome and a bare literal in the compiler. Nothing stopped them drifting, and no Studio surface could state the number at all.
+
+`CONTRACT.themeMenuTypes.*.quickBarMaxItems` now carries it (5 on `sidebar`, `null` on the two shapes that draw no quick bar), read through the new `quickBarCap(menuType)` host export.
+
+The distinction from `menuItemCap` is the point and is worth keeping straight: **`quickBarCap` may drop a page** — the rail and the drawer still list every menu page, so the bar is a shortcut. **`menuItemCap` may not** — where the chrome IS the menu (`bottom-tabs`), the surplus moves behind a More sheet instead.
+
+Host-integration surface only. `CONTRACT.version` → `1.68.0`.
+
+### What's new in 0.94.0 (contract 1.67.0)
+
+**The footer strip is themeable — `resolveFooterTokens` (REQ-NAV-STRUCTURE).** The bottom strip's surface was hard-coded white on both hosts and its items read the SIDEBAR's tokens. That is fine while the strip is the sidebar's secondary quick bar, and untenable once it IS the menu: the `bottom-tabs` shape hides the sidebar panel, so those tokens have nowhere to be set.
+
+A `theme_config.footer` block now carries `backgroundColor`, `textColor`, `activeColor` and the opt-in divider `borderColor` + `borderWidth`. **Every field falls back to the sidebar's**, so a workspace that never touches it renders exactly as before and only an explicit value moves anything.
+
+`resolveFooterTokens(theme)` (from `@colixsystems/widget-sdk/host`) is the one resolver both hosts read it with. It also settles two divergences the strip carried: the native bar ruled a permanent `#e2e8f0` hairline the theme could not reach — REQ-THEME-LOOK's rule is that the divider's **colour** is its switch — and it tinted the active tab's *label* where the web painted a filled pill, so `activeStyle: "filled"` meant two different things per host.
+
+Host-integration surface only: no author-facing hook, prop, primitive, or manifest field changed. `CONTRACT.version` → `1.67.0`.
+
+### What's new in 0.93.0 (contract 1.66.0)
+
+**An app picks the SHAPE its navigation takes — `CONTRACT.themeMenuTypes` (REQ-NAV-STRUCTURE).** Until now the chrome was always a sidebar: a persistent left rail on desktop, a hamburger drawer plus an optional bottom quick bar on mobile. That is the right default for an admin tool and the wrong one for a phone-first app or a site, and there was no way to say so. `CONTRACT.themeMenuTypes` publishes the closed catalogue — `sidebar`, `top-bar`, `bottom-tabs` — each entry carrying `{ name, summary, maxItems }`.
+
+`maxItems` caps how many menu pages the chrome draws at once, and its meaning differs per type deliberately: the sidebar's mobile quick bar is a **secondary** curated bar whose cap may drop a page (the rail still lists every one), while a `bottom-tabs` strip **is** the menu, so its cap must never drop one — the surplus moves behind a More sheet instead.
+
+**New host exports (`@colixsystems/widget-sdk/host`)** — `normaliseNavigation(navigation)` resolves a stored `theme_config.navigation` block to the `{ menuType }` a host switches its chrome on, and `menuItemCap(menuType)` states that shape's cap. One implementation for both hosts, so a menu type cannot mean one thing in the web Player and another in the exported Expo app. An absent or unknown value resolves to `sidebar`, so every app authored before menu types existed renders and compiles byte-identically.
+
+Host-integration surface only: no author-facing hook, prop, primitive, or manifest field changed. `CONTRACT.version` → `1.66.0`.
+
+### What's new in 0.97.0 (contract 1.69.0)
+
+**`CONTRACT.themeComponents` gains five scopes: `accent`, `destructive`, `muted`, `popover`, `ring` (sc-5392).** The vocabulary shipped with exactly `button`/`card`/`text` (sc-1497), so a shadcn/Tailwind app import's `--accent`, `--destructive`, `--muted`, `--popover` and `--ring` custom properties had no `themeConfig` home and were reported "no theme home" on every import. Each new scope binds to real `styleSchema` fields on the built-ins that already had a matching surface — `accent` (a highlight/tag surface: `background`/`borderColor`/`radius`) to the Label widget's own fields, `destructive` (a themed danger/delete action: `background`/`textColor`/`borderColor`) to a new "Danger" Button variant, `muted` (a subtle/secondary surface: `background`/`textColor`/`borderColor`/`radius`) to Form Input's and Form Builder's pre-existing input fields, `popover` (a dropdown/menu surface: `background`/`textColor`/`borderColor`) to the same two widgets' choice-field option list, and `ring` (the app-wide focus-visible outline: `color`/`width`) to a new emphasis border on Button. **This is HOST-ONLY plumbing, exactly like the three scopes before it** — `useTheme()`'s documented `components` slice is unchanged, no widget-authoring hook or `propertySchema` type moved, and no scope declares `universalFields`, so a third-party or AI-generated widget's contract is unaffected; the Developer guide and `DEFAULT_SYSTEM_PROMPT` need no update because neither ever documented this internal vocabulary. Fully additive: a theme with no `components` key, or one using only `button`/`card`/`text`, resolves exactly as before.
+- **`CONTRACT.version` → `1.69.0`** (additive: five new `themeComponents` scopes + their target-field bindings). No existing scope, token, or export changed shape.
 
 ### What's new in 0.96.0 (contract 1.68.0)
 

package/dist/contract.cjs

@@ -159,6 +159,42 @@ const THEME_WIDGET_STYLES = Object.freeze({
   // Matches the styleSchema field cap the widget agent is held to.
   maxFieldsPerWidget: 12,
 });
+// REQ-NAV-STRUCTURE: the SHAPE an app's navigation takes. One catalogue, four
+// consumers -- the Studio's Navigation page, Mason's set_theme coercion, the web
+// PlayerChrome and the compiler's navigator -- so a type cannot be offered to an
+// author without every host actually drawing it.
+//
+// `maxItems` caps how many menu pages the chrome draws at once, and its meaning
+// differs per type deliberately. The sidebar's mobile quick bar is a SECONDARY
+// curated bar, so its own cap may drop a page -- the rail still lists every one.
+// A bottom-tabs strip IS the menu, so its cap must never drop one: the surplus
+// moves behind a "More" sheet instead.
+const THEME_MENU_TYPES = Object.freeze({
+  sidebar: Object.freeze({
+    name: "Sidebar",
+    summary:
+      "A persistent left rail on desktop; a hamburger drawer plus the optional bottom quick bar on mobile.",
+    maxItems: null,
+    // The SECONDARY mobile quick bar's cap. It may drop a page past it, because
+    // the rail and the drawer still list every one -- the opposite of
+    // `bottom-tabs`' `maxItems`, where the strip IS the menu.
+    quickBarMaxItems: 5,
+  }),
+  "top-bar": Object.freeze({
+    name: "Top bar",
+    summary:
+      "A horizontal row of links in the app header, scrolling sideways when it runs out of room. No rail at any width.",
+    maxItems: null,
+    quickBarMaxItems: null,
+  }),
+  "bottom-tabs": Object.freeze({
+    name: "Bottom tabs",
+    summary:
+      "A sticky bottom strip at every width -- the phone-native shape. Pages past the cap move behind a More sheet.",
+    maxItems: 4,
+    quickBarMaxItems: null,
+  }),
+});
 const THEME_SPACING_SCALE = Object.freeze({
   min: 0.5,
   max: 2,
@@ -211,6 +247,34 @@ const CARD_UNIVERSAL_FIELDS = Object.freeze({
   gradient: "cardGradient",
 });
 
+// The Form widgets' text-entry surface, already read by both form widgets
+// (REQ-THEME-13, predating this scope) -- a genuine subtle/secondary surface
+// distinct from the card that hosts it.
+const MUTED_INPUT_FIELDS = Object.freeze({
+  background: "inputBackground",
+  textColor: "inputTextColor",
+  borderColor: "inputBorderColor",
+  radius: "inputRadius",
+});
+
+// The Form widgets' choice-field option list -- the closest thing this
+// catalog has to a menu/dropdown surface (singleChoice/multiChoice render an
+// inline list of options here).
+const POPOVER_FIELDS = Object.freeze({
+  background: "popoverBackground",
+  textColor: "popoverTextColor",
+  borderColor: "popoverBorderColor",
+});
+
+// The Button widget's danger-variant fields -- kept separate from its own
+// `background`/`textColor`/`borderColor` (the `button` scope's fields above)
+// so a themed destructive action never collides with the button's normal look.
+const DANGER_BUTTON_FIELDS = Object.freeze({
+  background: "dangerBackground",
+  textColor: "dangerTextColor",
+  borderColor: "dangerBorderColor",
+});
+
 const THEME_COMPONENTS = Object.freeze({
   button: Object.freeze({
     label: "Buttons",
@@ -277,6 +341,82 @@ const THEME_COMPONENTS = Object.freeze({
       "appstudio.data-value": TEXT_TYPOGRAPHY_FIELDS,
     }),
   }),
+  // sc-5392 -- a highlight/tag surface. Bound to Label's OWN background/
+  // borderColor/radius fields (REQ-THEME-13, predating this scope) rather
+  // than its `color` field, which the `text` scope already owns -- two
+  // scopes writing the same field on the same widget would race.
+  accent: Object.freeze({
+    label: "Accent",
+    tokens: Object.freeze({
+      background: Object.freeze({ type: "color", uiDefault: "colors.primarySoft" }),
+      borderColor: Object.freeze({ type: "color", uiDefault: "colors.primary" }),
+      radius: Object.freeze({ type: "size", min: 0, max: 48, uiDefault: "radii.pill" }),
+    }),
+    targets: Object.freeze({
+      "appstudio.label": Object.freeze({
+        background: "background",
+        borderColor: "borderColor",
+        radius: "radius",
+      }),
+    }),
+  }),
+  // sc-5392 -- the Button widget's danger/delete variant. Separate token set
+  // from `button` above so "make the buttons coral" never recolours Delete.
+  destructive: Object.freeze({
+    label: "Destructive",
+    tokens: Object.freeze({
+      background: Object.freeze({ type: "color", uiDefault: "colors.danger" }),
+      textColor: Object.freeze({ type: "color", uiDefault: "colors.onPrimary" }),
+      borderColor: Object.freeze({ type: "color", uiDefault: "colors.danger" }),
+    }),
+    targets: Object.freeze({
+      "appstudio.button": DANGER_BUTTON_FIELDS,
+    }),
+  }),
+  // sc-5392 -- a subtle/secondary surface, bound to the form widgets' own
+  // text-entry fields (already REQ-THEME-13 style fields, predating this
+  // scope) rather than to Text/Label/Data Value, whose `color` field the
+  // `text` scope already owns.
+  muted: Object.freeze({
+    label: "Muted",
+    tokens: Object.freeze({
+      background: Object.freeze({ type: "color", uiDefault: "colors.surfaceMuted" }),
+      textColor: Object.freeze({ type: "color", uiDefault: "colors.onSurfaceMuted" }),
+      borderColor: Object.freeze({ type: "color", uiDefault: "colors.border" }),
+      radius: Object.freeze({ type: "size", min: 0, max: 48, uiDefault: "radii.sm" }),
+    }),
+    targets: Object.freeze({
+      "appstudio.form-input": MUTED_INPUT_FIELDS,
+      "appstudio.form-builder": MUTED_INPUT_FIELDS,
+    }),
+  }),
+  // sc-5392 -- dropdown/menu surfaces. The form widgets' choice-field option
+  // list is the closest thing the built-in catalog has to a popover panel.
+  popover: Object.freeze({
+    label: "Popover",
+    tokens: Object.freeze({
+      background: Object.freeze({ type: "color", uiDefault: "colors.surface" }),
+      textColor: Object.freeze({ type: "color", uiDefault: "colors.onSurface" }),
+      borderColor: Object.freeze({ type: "color", uiDefault: "colors.border" }),
+    }),
+    targets: Object.freeze({
+      "appstudio.form-input": POPOVER_FIELDS,
+      "appstudio.form-builder": POPOVER_FIELDS,
+    }),
+  }),
+  // sc-5392 -- the app-wide focus-visible outline. A themed emphasis border
+  // on the Button widget, applied after its variant colours and beaten by the
+  // widget's own per-instance `borderColor` (REQ-THEME-13 stays final).
+  ring: Object.freeze({
+    label: "Focus ring",
+    tokens: Object.freeze({
+      color: Object.freeze({ type: "color", uiDefault: "colors.primary" }),
+      width: Object.freeze({ type: "size", min: 0, max: 8 }),
+    }),
+    targets: Object.freeze({
+      "appstudio.button": Object.freeze({ color: "ringColor", width: "ringWidth" }),
+    }),
+  }),
 });
 
 // sc-4505 — the value types a widget event payload field may declare. Narrower
@@ -2956,7 +3096,31 @@ const CONTRACT = deepFreeze({
   //    action script now sees a `request` global — `{ body }` on a run fired
   //    by the workspace-granted `http_post` webhook trigger, null otherwise.
   //    `app` and `http_post` stay operator-granted and are NOT declarable.
-  version: "1.68.0",
+  // 1.69.0: additive (sc-5392) — `themeComponents` gains five scopes:
+  //    `accent`, `destructive`, `muted`, `popover` and `ring`, so a
+  //    shadcn/Tailwind import's matching custom properties have a themeConfig
+  //    home instead of being reported lost. Host-only plumbing: no scope
+  //    declares `universalFields`, so a third-party manifest is unaffected.
+  // 1.70.0: additive (REQ-NAV-STRUCTURE) -- `themeMenuTypes`, the closed
+  //    catalogue of navigation shapes an app can take (`sidebar`, `top-bar`,
+  //    `bottom-tabs`) with the per-type item cap. Read from `theme_config`
+  //    as `navigation.menuType`; absent or unknown resolves to `sidebar`, so
+  //    every app that exists today renders and compiles byte-identically.
+  //    Resolved through the new `normaliseNavigation` host export rather than
+  //    a literal per host.
+  // 1.71.0: additive (REQ-NAV-STRUCTURE) -- `resolveFooterTokens` (host
+  //    export). The footer strip's surface was hard-coded white on BOTH hosts
+  //    and its items read the SIDEBAR's tokens, which stops being tenable the
+  //    moment the strip IS the menu (`bottom-tabs` hides the sidebar panel, so
+  //    those tokens have nowhere to be set). A `theme_config.footer` block now
+  //    carries its own, every field falling back to the sidebar's so an
+  //    untouched workspace is unchanged.
+  // 1.72.0: additive (REQ-NAV-STRUCTURE) -- `themeMenuTypes.*.quickBarMaxItems`
+  //    and the `quickBarCap` host export. The sidebar's secondary quick bar
+  //    capped at five in TWO places -- a named constant on web and a bare `5`
+  //    literal in the compiler -- so the number could drift between the hosts
+  //    and no Studio surface could state it at all.
+  version: "1.72.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -2972,6 +3136,7 @@ const CONTRACT = deepFreeze({
   themeComponentTextTransforms: THEME_COMPONENT_TEXT_TRANSFORMS,
   themeComponentGradient: THEME_COMPONENT_GRADIENT,
   themeSpacingScale: THEME_SPACING_SCALE,
+  themeMenuTypes: THEME_MENU_TYPES,
   themeWidgetStyles: THEME_WIDGET_STYLES,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,

package/dist/contract.js

@@ -159,6 +159,42 @@ const THEME_WIDGET_STYLES = Object.freeze({
   // Matches the styleSchema field cap the widget agent is held to.
   maxFieldsPerWidget: 12,
 });
+// REQ-NAV-STRUCTURE: the SHAPE an app's navigation takes. One catalogue, four
+// consumers -- the Studio's Navigation page, Mason's set_theme coercion, the web
+// PlayerChrome and the compiler's navigator -- so a type cannot be offered to an
+// author without every host actually drawing it.
+//
+// `maxItems` caps how many menu pages the chrome draws at once, and its meaning
+// differs per type deliberately. The sidebar's mobile quick bar is a SECONDARY
+// curated bar, so its own cap may drop a page -- the rail still lists every one.
+// A bottom-tabs strip IS the menu, so its cap must never drop one: the surplus
+// moves behind a "More" sheet instead.
+const THEME_MENU_TYPES = Object.freeze({
+  sidebar: Object.freeze({
+    name: "Sidebar",
+    summary:
+      "A persistent left rail on desktop; a hamburger drawer plus the optional bottom quick bar on mobile.",
+    maxItems: null,
+    // The SECONDARY mobile quick bar's cap. It may drop a page past it, because
+    // the rail and the drawer still list every one -- the opposite of
+    // `bottom-tabs`' `maxItems`, where the strip IS the menu.
+    quickBarMaxItems: 5,
+  }),
+  "top-bar": Object.freeze({
+    name: "Top bar",
+    summary:
+      "A horizontal row of links in the app header, scrolling sideways when it runs out of room. No rail at any width.",
+    maxItems: null,
+    quickBarMaxItems: null,
+  }),
+  "bottom-tabs": Object.freeze({
+    name: "Bottom tabs",
+    summary:
+      "A sticky bottom strip at every width -- the phone-native shape. Pages past the cap move behind a More sheet.",
+    maxItems: 4,
+    quickBarMaxItems: null,
+  }),
+});
 const THEME_SPACING_SCALE = Object.freeze({
   min: 0.5,
   max: 2,
@@ -211,6 +247,34 @@ const CARD_UNIVERSAL_FIELDS = Object.freeze({
   gradient: "cardGradient",
 });
 
+// The Form widgets' text-entry surface, already read by both form widgets
+// (REQ-THEME-13, predating this scope) -- a genuine subtle/secondary surface
+// distinct from the card that hosts it.
+const MUTED_INPUT_FIELDS = Object.freeze({
+  background: "inputBackground",
+  textColor: "inputTextColor",
+  borderColor: "inputBorderColor",
+  radius: "inputRadius",
+});
+
+// The Form widgets' choice-field option list -- the closest thing this
+// catalog has to a menu/dropdown surface (singleChoice/multiChoice render an
+// inline list of options here).
+const POPOVER_FIELDS = Object.freeze({
+  background: "popoverBackground",
+  textColor: "popoverTextColor",
+  borderColor: "popoverBorderColor",
+});
+
+// The Button widget's danger-variant fields -- kept separate from its own
+// `background`/`textColor`/`borderColor` (the `button` scope's fields above)
+// so a themed destructive action never collides with the button's normal look.
+const DANGER_BUTTON_FIELDS = Object.freeze({
+  background: "dangerBackground",
+  textColor: "dangerTextColor",
+  borderColor: "dangerBorderColor",
+});
+
 const THEME_COMPONENTS = Object.freeze({
   button: Object.freeze({
     label: "Buttons",
@@ -277,6 +341,82 @@ const THEME_COMPONENTS = Object.freeze({
       "appstudio.data-value": TEXT_TYPOGRAPHY_FIELDS,
     }),
   }),
+  // sc-5392 -- a highlight/tag surface. Bound to Label's OWN background/
+  // borderColor/radius fields (REQ-THEME-13, predating this scope) rather
+  // than its `color` field, which the `text` scope already owns -- two
+  // scopes writing the same field on the same widget would race.
+  accent: Object.freeze({
+    label: "Accent",
+    tokens: Object.freeze({
+      background: Object.freeze({ type: "color", uiDefault: "colors.primarySoft" }),
+      borderColor: Object.freeze({ type: "color", uiDefault: "colors.primary" }),
+      radius: Object.freeze({ type: "size", min: 0, max: 48, uiDefault: "radii.pill" }),
+    }),
+    targets: Object.freeze({
+      "appstudio.label": Object.freeze({
+        background: "background",
+        borderColor: "borderColor",
+        radius: "radius",
+      }),
+    }),
+  }),
+  // sc-5392 -- the Button widget's danger/delete variant. Separate token set
+  // from `button` above so "make the buttons coral" never recolours Delete.
+  destructive: Object.freeze({
+    label: "Destructive",
+    tokens: Object.freeze({
+      background: Object.freeze({ type: "color", uiDefault: "colors.danger" }),
+      textColor: Object.freeze({ type: "color", uiDefault: "colors.onPrimary" }),
+      borderColor: Object.freeze({ type: "color", uiDefault: "colors.danger" }),
+    }),
+    targets: Object.freeze({
+      "appstudio.button": DANGER_BUTTON_FIELDS,
+    }),
+  }),
+  // sc-5392 -- a subtle/secondary surface, bound to the form widgets' own
+  // text-entry fields (already REQ-THEME-13 style fields, predating this
+  // scope) rather than to Text/Label/Data Value, whose `color` field the
+  // `text` scope already owns.
+  muted: Object.freeze({
+    label: "Muted",
+    tokens: Object.freeze({
+      background: Object.freeze({ type: "color", uiDefault: "colors.surfaceMuted" }),
+      textColor: Object.freeze({ type: "color", uiDefault: "colors.onSurfaceMuted" }),
+      borderColor: Object.freeze({ type: "color", uiDefault: "colors.border" }),
+      radius: Object.freeze({ type: "size", min: 0, max: 48, uiDefault: "radii.sm" }),
+    }),
+    targets: Object.freeze({
+      "appstudio.form-input": MUTED_INPUT_FIELDS,
+      "appstudio.form-builder": MUTED_INPUT_FIELDS,
+    }),
+  }),
+  // sc-5392 -- dropdown/menu surfaces. The form widgets' choice-field option
+  // list is the closest thing the built-in catalog has to a popover panel.
+  popover: Object.freeze({
+    label: "Popover",
+    tokens: Object.freeze({
+      background: Object.freeze({ type: "color", uiDefault: "colors.surface" }),
+      textColor: Object.freeze({ type: "color", uiDefault: "colors.onSurface" }),
+      borderColor: Object.freeze({ type: "color", uiDefault: "colors.border" }),
+    }),
+    targets: Object.freeze({
+      "appstudio.form-input": POPOVER_FIELDS,
+      "appstudio.form-builder": POPOVER_FIELDS,
+    }),
+  }),
+  // sc-5392 -- the app-wide focus-visible outline. A themed emphasis border
+  // on the Button widget, applied after its variant colours and beaten by the
+  // widget's own per-instance `borderColor` (REQ-THEME-13 stays final).
+  ring: Object.freeze({
+    label: "Focus ring",
+    tokens: Object.freeze({
+      color: Object.freeze({ type: "color", uiDefault: "colors.primary" }),
+      width: Object.freeze({ type: "size", min: 0, max: 8 }),
+    }),
+    targets: Object.freeze({
+      "appstudio.button": Object.freeze({ color: "ringColor", width: "ringWidth" }),
+    }),
+  }),
 });
 
 // sc-4505 — the value types a widget event payload field may declare. Narrower
@@ -2956,7 +3096,31 @@ const CONTRACT = deepFreeze({
   //    action script now sees a `request` global — `{ body }` on a run fired
   //    by the workspace-granted `http_post` webhook trigger, null otherwise.
   //    `app` and `http_post` stay operator-granted and are NOT declarable.
-  version: "1.68.0",
+  // 1.69.0: additive (sc-5392) — `themeComponents` gains five scopes:
+  //    `accent`, `destructive`, `muted`, `popover` and `ring`, so a
+  //    shadcn/Tailwind import's matching custom properties have a themeConfig
+  //    home instead of being reported lost. Host-only plumbing: no scope
+  //    declares `universalFields`, so a third-party manifest is unaffected.
+  // 1.70.0: additive (REQ-NAV-STRUCTURE) -- `themeMenuTypes`, the closed
+  //    catalogue of navigation shapes an app can take (`sidebar`, `top-bar`,
+  //    `bottom-tabs`) with the per-type item cap. Read from `theme_config`
+  //    as `navigation.menuType`; absent or unknown resolves to `sidebar`, so
+  //    every app that exists today renders and compiles byte-identically.
+  //    Resolved through the new `normaliseNavigation` host export rather than
+  //    a literal per host.
+  // 1.71.0: additive (REQ-NAV-STRUCTURE) -- `resolveFooterTokens` (host
+  //    export). The footer strip's surface was hard-coded white on BOTH hosts
+  //    and its items read the SIDEBAR's tokens, which stops being tenable the
+  //    moment the strip IS the menu (`bottom-tabs` hides the sidebar panel, so
+  //    those tokens have nowhere to be set). A `theme_config.footer` block now
+  //    carries its own, every field falling back to the sidebar's so an
+  //    untouched workspace is unchanged.
+  // 1.72.0: additive (REQ-NAV-STRUCTURE) -- `themeMenuTypes.*.quickBarMaxItems`
+  //    and the `quickBarCap` host export. The sidebar's secondary quick bar
+  //    capped at five in TWO places -- a named constant on web and a bare `5`
+  //    literal in the compiler -- so the number could drift between the hosts
+  //    and no Studio surface could state it at all.
+  version: "1.72.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -2972,6 +3136,7 @@ const CONTRACT = deepFreeze({
   themeComponentTextTransforms: THEME_COMPONENT_TEXT_TRANSFORMS,
   themeComponentGradient: THEME_COMPONENT_GRADIENT,
   themeSpacingScale: THEME_SPACING_SCALE,
+  themeMenuTypes: THEME_MENU_TYPES,
   themeWidgetStyles: THEME_WIDGET_STYLES,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,

package/dist/host.d.ts

@@ -133,3 +133,52 @@ export function resolveToastTokens(
 export function createToastController(
   opts?: ToastControllerOptions,
 ): ToastController;
+
+// REQ-NAV-STRUCTURE — the navigation SHAPE a host draws its chrome in. The
+// vocabulary is closed by `CONTRACT.themeMenuTypes`; these are the resolvers
+// both hosts switch on.
+
+export type ThemeMenuType = "sidebar" | "top-bar" | "bottom-tabs";
+
+export interface ResolvedNavigation {
+  menuType: ThemeMenuType;
+}
+
+/**
+ * Resolves a stored `theme_config.navigation` block. Always returns a usable
+ * shape — a junk, partial, or absent input yields the default sidebar, so a
+ * host never has to guard the value it switches on.
+ */
+export function normaliseNavigation(navigation: unknown): ResolvedNavigation;
+
+/**
+ * How many menu pages this shape may draw at once, or `null` for no cap. The
+ * cap's meaning differs per type: the sidebar's quick bar may drop a page past
+ * it, a bottom-tabs strip must move its surplus behind a More sheet.
+ */
+export function menuItemCap(menuType: string): number | null;
+
+/**
+ * How many pages the SECONDARY mobile quick bar draws, or `null` where the shape
+ * draws none (only `sidebar` has one). Unlike `menuItemCap` this cap MAY drop a
+ * page: the rail and drawer still list every menu page.
+ */
+export function quickBarCap(menuType: string): number | null;
+
+/** The footer strip's resolved tokens. A `null` colour means the host keeps its
+ *  own default; a `null` `borderColor` means no divider is drawn at all. */
+export interface FooterTokens {
+  backgroundColor: string | null;
+  textColor: string | null;
+  activeColor: string | null;
+  borderColor: string | null;
+  borderWidth: number | null;
+  activeStyle: "filled" | "accent";
+}
+
+/**
+ * Resolves the footer strip's tokens from a whole `theme_config`. Every field
+ * falls back to the sidebar's, so a workspace that never opens the Footer panel
+ * renders exactly as it did before the block existed.
+ */
+export function resolveFooterTokens(theme: unknown): FooterTokens;

package/dist/host.js

@@ -39,3 +39,19 @@ export {
   normalizeToastKind,
   TOAST_DEFAULTS,
 } from "./toast-host.js";
+
+// REQ-NAV-STRUCTURE: the navigation-shape resolver both hosts draw their chrome
+// from. `normaliseNavigation` turns a stored `theme_config.navigation` block into
+// the resolved `{ menuType }` the chrome switches on; `menuItemCap` states how
+// many menu pages that shape may draw at once. One implementation, so a menu
+// type cannot mean one thing in the Player and another in the Expo export.
+// `resolveFooterTokens` is the footer strip's own token set, falling back to
+// the sidebar's so an untouched workspace keeps the appearance it has. It
+// exists because the strip IS the menu under `bottom-tabs`, where the sidebar
+// panel is hidden and those tokens can no longer be set at all.
+export {
+  normaliseNavigation,
+  menuItemCap,
+  quickBarCap,
+  resolveFooterTokens,
+} from "./navigation.js";

package/dist/navigation.cjs

@@ -0,0 +1,124 @@
+// CommonJS mirror of navigation.js — the CJS compiler and the Mason build runner
+// resolve a `theme_config.navigation` block with the SAME rules the web host
+// applies, so an app's menu type cannot mean one thing on web and another in the
+// exported Expo app.
+//
+// The BODY below is copied VERBATIM from navigation.js; only the module syntax
+// differs. navigation-parity.test.js pins both facts — identical bodies AND
+// identical behaviour over a shared case table — so drift fails CI.
+
+// REQ-NAV-STRUCTURE — the host side of an app's navigation SHAPE and the
+// tokens its footer strip is painted with.
+//
+// Host-integration surface, re-exported from `host.js`: consumed by the platform
+// hosts that draw an app's chrome (the web PlayerChrome, the compiler that emits
+// the exported Expo app's navigator) and by the Studio surface that authors it —
+// never by a widget author.
+//
+// Living here — one implementation both hosts import — is what makes a menu type
+// behave identically in the Player and the export (widget-parity skill). The
+// alternative, a resolver copied per host, is the drift this file exists to
+// prevent.
+//
+// `CONTRACT.themeMenuTypes` is the single source of the vocabulary: which shapes
+// exist and each one's item cap. Mason's `set_theme` coercion validates against
+// the SAME literal, so what a planner may persist and what a host draws cannot
+// diverge.
+
+const { CONTRACT } = require("./contract.cjs");
+
+// Absent or unknown resolves here, so every app authored before menu types
+// existed renders and compiles byte-identically.
+const DEFAULT_MENU_TYPE = "sidebar";
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Resolve a `theme_config.navigation` block to the shape both hosts read.
+ *
+ * Always returns a fully resolved object — a junk, partial, or absent input
+ * yields the default sidebar rather than something a host has to guard against.
+ *
+ * @param {unknown} navigation — the raw `theme_config.navigation` value.
+ * @returns {{ menuType: string }} the resolved navigation structure.
+ */
+function normaliseNavigation(navigation) {
+  const raw = isPlainObject(navigation) ? navigation.menuType : undefined;
+  const menuType =
+    typeof raw === "string" && Object.hasOwn(CONTRACT.themeMenuTypes, raw)
+      ? raw
+      : DEFAULT_MENU_TYPE;
+  return { menuType };
+}
+
+/**
+ * How many MENU pages the chrome may draw at once, or `null` for no cap.
+ *
+ * Where the chrome IS the menu (`bottom-tabs`) this cap must never drop a page:
+ * the surplus moves behind a More sheet. Contrast `quickBarCap` below.
+ *
+ * @param {string} menuType — a resolved menu type.
+ * @returns {number|null}
+ */
+function menuItemCap(menuType) {
+  const entry = CONTRACT.themeMenuTypes[menuType];
+  return entry ? entry.maxItems : null;
+}
+
+/**
+ * How many pages the SECONDARY mobile quick bar draws, or `null` where that
+ * shape draws none. Only the `sidebar` shape has one.
+ *
+ * This cap MAY drop a page, and that is the difference from `menuItemCap`: the
+ * rail and the drawer still list every menu page, so the bar is a shortcut
+ * rather than the menu. It lived as a constant on one host and a literal on the
+ * other before this, which is exactly how the two would have drifted.
+ *
+ * @param {string} menuType — a resolved menu type.
+ * @returns {number|null}
+ */
+function quickBarCap(menuType) {
+  const entry = CONTRACT.themeMenuTypes[menuType];
+  return entry ? entry.quickBarMaxItems : null;
+}
+
+// The strip's surface was hard-coded white on BOTH hosts and its items read the
+// sidebar's tokens — which is fine while it is the sidebar's secondary quick bar
+// and fatal once it IS the menu (`bottom-tabs` hides the sidebar panel, so those
+// tokens have nowhere to be set). `footer` gives it tokens of its own.
+//
+// Every field falls back to the sidebar's, so a workspace that never opens the
+// Footer panel keeps exactly the appearance it has today; only an explicit
+// `footer` value moves anything.
+function resolveFooterTokens(theme) {
+  const config = isPlainObject(theme) ? theme : {};
+  const footer = isPlainObject(config.footer) ? config.footer : {};
+  const sidebar = isPlainObject(config.sidebar) ? config.sidebar : {};
+  const pick = (key) => footer[key] || sidebar[key] || null;
+  const borderColor = pick("borderColor");
+  const activeStyle = footer.activeStyle || sidebar.activeStyle;
+  return {
+    backgroundColor: pick("backgroundColor"),
+    textColor: pick("textColor"),
+    // Unlike the others this has no null state on either host: an unset active
+    // colour resolves to the brand primary, which the caller supplies.
+    activeColor: pick("activeColor"),
+    // REQ-THEME-LOOK: the divider's COLOUR is its switch. Unset draws no line at
+    // all — which the native quick bar did not honour before this, ruling a
+    // hairline across a tinted strip that had asked for none.
+    borderColor,
+    borderWidth: borderColor ? borderWidthOr(footer.borderWidth, sidebar.borderWidth) : null,
+    activeStyle: activeStyle === "accent" ? "accent" : "filled",
+  };
+}
+
+function borderWidthOr(...values) {
+  for (const value of values) {
+    if (typeof value === "number" && Number.isFinite(value)) return value;
+  }
+  return 1;
+}
+
+module.exports = { normaliseNavigation, menuItemCap, quickBarCap, resolveFooterTokens };

package/dist/navigation.js

@@ -0,0 +1,113 @@
+// REQ-NAV-STRUCTURE — the host side of an app's navigation SHAPE and the
+// tokens its footer strip is painted with.
+//
+// Host-integration surface, re-exported from `host.js`: consumed by the platform
+// hosts that draw an app's chrome (the web PlayerChrome, the compiler that emits
+// the exported Expo app's navigator) and by the Studio surface that authors it —
+// never by a widget author.
+//
+// Living here — one implementation both hosts import — is what makes a menu type
+// behave identically in the Player and the export (widget-parity skill). The
+// alternative, a resolver copied per host, is the drift this file exists to
+// prevent.
+//
+// `CONTRACT.themeMenuTypes` is the single source of the vocabulary: which shapes
+// exist and each one's item cap. Mason's `set_theme` coercion validates against
+// the SAME literal, so what a planner may persist and what a host draws cannot
+// diverge.
+
+import { CONTRACT } from "./contract.js";
+
+// Absent or unknown resolves here, so every app authored before menu types
+// existed renders and compiles byte-identically.
+const DEFAULT_MENU_TYPE = "sidebar";
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Resolve a `theme_config.navigation` block to the shape both hosts read.
+ *
+ * Always returns a fully resolved object — a junk, partial, or absent input
+ * yields the default sidebar rather than something a host has to guard against.
+ *
+ * @param {unknown} navigation — the raw `theme_config.navigation` value.
+ * @returns {{ menuType: string }} the resolved navigation structure.
+ */
+export function normaliseNavigation(navigation) {
+  const raw = isPlainObject(navigation) ? navigation.menuType : undefined;
+  const menuType =
+    typeof raw === "string" && Object.hasOwn(CONTRACT.themeMenuTypes, raw)
+      ? raw
+      : DEFAULT_MENU_TYPE;
+  return { menuType };
+}
+
+/**
+ * How many MENU pages the chrome may draw at once, or `null` for no cap.
+ *
+ * Where the chrome IS the menu (`bottom-tabs`) this cap must never drop a page:
+ * the surplus moves behind a More sheet. Contrast `quickBarCap` below.
+ *
+ * @param {string} menuType — a resolved menu type.
+ * @returns {number|null}
+ */
+export function menuItemCap(menuType) {
+  const entry = CONTRACT.themeMenuTypes[menuType];
+  return entry ? entry.maxItems : null;
+}
+
+/**
+ * How many pages the SECONDARY mobile quick bar draws, or `null` where that
+ * shape draws none. Only the `sidebar` shape has one.
+ *
+ * This cap MAY drop a page, and that is the difference from `menuItemCap`: the
+ * rail and the drawer still list every menu page, so the bar is a shortcut
+ * rather than the menu. It lived as a constant on one host and a literal on the
+ * other before this, which is exactly how the two would have drifted.
+ *
+ * @param {string} menuType — a resolved menu type.
+ * @returns {number|null}
+ */
+export function quickBarCap(menuType) {
+  const entry = CONTRACT.themeMenuTypes[menuType];
+  return entry ? entry.quickBarMaxItems : null;
+}
+
+// The strip's surface was hard-coded white on BOTH hosts and its items read the
+// sidebar's tokens — which is fine while it is the sidebar's secondary quick bar
+// and fatal once it IS the menu (`bottom-tabs` hides the sidebar panel, so those
+// tokens have nowhere to be set). `footer` gives it tokens of its own.
+//
+// Every field falls back to the sidebar's, so a workspace that never opens the
+// Footer panel keeps exactly the appearance it has today; only an explicit
+// `footer` value moves anything.
+export function resolveFooterTokens(theme) {
+  const config = isPlainObject(theme) ? theme : {};
+  const footer = isPlainObject(config.footer) ? config.footer : {};
+  const sidebar = isPlainObject(config.sidebar) ? config.sidebar : {};
+  const pick = (key) => footer[key] || sidebar[key] || null;
+  const borderColor = pick("borderColor");
+  const activeStyle = footer.activeStyle || sidebar.activeStyle;
+  return {
+    backgroundColor: pick("backgroundColor"),
+    textColor: pick("textColor"),
+    // Unlike the others this has no null state on either host: an unset active
+    // colour resolves to the brand primary, which the caller supplies.
+    activeColor: pick("activeColor"),
+    // REQ-THEME-LOOK: the divider's COLOUR is its switch. Unset draws no line at
+    // all — which the native quick bar did not honour before this, ruling a
+    // hairline across a tinted strip that had asked for none.
+    borderColor,
+    borderWidth: borderColor ? borderWidthOr(footer.borderWidth, sidebar.borderWidth) : null,
+    activeStyle: activeStyle === "accent" ? "accent" : "filled",
+  };
+}
+
+function borderWidthOr(...values) {
+  for (const value of values) {
+    if (typeof value === "number" && Number.isFinite(value)) return value;
+  }
+  return 1;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.96.0",
+  "version": "0.98.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -48,7 +48,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-invites.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-payments.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-section-empty.test.js src/__tests__/hooks-widget-event.test.js src/__tests__/hooks-widget-input.test.js src/__tests__/hooks-identification.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-translation-api.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-measured-padding.test.js src/__tests__/linter-payment-error.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/hooks-translate.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/theme-components-parity.test.js src/__tests__/theme-depth-tokens.test.js src/__tests__/toast-host.test.js src/__tests__/hooks-domain-error-mapping.test.js src/__tests__/linter-datastore-error.test.js src/__tests__/linter-write-gating.test.js src/__tests__/hooks-speech-to-text.test.js"
+    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-invites.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-payments.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-section-empty.test.js src/__tests__/hooks-widget-event.test.js src/__tests__/hooks-widget-input.test.js src/__tests__/hooks-identification.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-translation-api.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-measured-padding.test.js src/__tests__/linter-payment-error.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/hooks-translate.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/theme-components-parity.test.js src/__tests__/navigation-parity.test.js src/__tests__/theme-depth-tokens.test.js src/__tests__/toast-host.test.js src/__tests__/hooks-domain-error-mapping.test.js src/__tests__/linter-datastore-error.test.js src/__tests__/linter-write-gating.test.js src/__tests__/hooks-speech-to-text.test.js"
   },
   "engines": {
     "node": ">=18"