@colixsystems/widget-sdk 0.108.0 → 0.110.0

package/README.md

@@ -46,6 +46,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **DATASTORE** | `useBoundColumns(tableId, shape, props)` | `{ columns, resolved, missing, loading, error }` | `schema(tableId)` (built on `useDatastoreSchema`) — `datastore.read:<table>`. Resolves author-bound column NAMES from `props` by exact name → case-insensitive name → first unclaimed column matching `shape[key].dataType`, so a column an author renamed after install still resolves instead of `record[props.titleField]` reading `undefined`. `columns` holds the resolved NAME (`record[columns.titleField]`); `resolved` holds the full `Column`; `missing` lists non-`optional` keys that never resolved. Falsy `tableId` collapses to `{ columns: {}, resolved: {}, missing: Object.keys(shape), loading: false, error: null }`. |
 | **DATASTORE** | `useInterpretDraft(tableId)` | `{ interpret, interpreting, error, result, available }` | `interpret(tableId, body)` — `datastore.read:<table>`. Turns ONE sentence a user typed ("walk at 11 am tomorrow") into DRAFT column values so a form can prefill itself. IMPERATIVE: call `interpret(text, { fields?, timeZone? })` from an event handler, never on mount. It DRAFTS and writes nothing — show the values for review, then submit through `useDatastoreMutation().create`. Resolves to `{ values, unresolved }`; `values` is keyed by column NAME (the shape `create()` takes) and `unresolved` names the fields the sentence did not state. Only text / number / boolean / date / datetime / array columns are drafted — `FILE`, `RELATION`, `USER` and `USER_GROUP` carry ids and are never guessed. Fails closed to an empty draft. **Every call spends the workspace's AI credits** and is rate-limited per actor, so call it once per user action (never on mount or in a render loop); once the workspace runs out the call is refused with a generic 429 — an app user is deliberately **not** told the workspace's billing state, since they have never heard of an AI credit and cannot buy one. Never surface a raw error to the person filling the form: say drafting is unavailable and keep every field editable by hand. `available` is false where the host brokers no interpreter. |
 | **DATASTORE** | `useDatastoreMutation(table)` | `{ create, update, delete }` | `records(table).{ create, update (PATCH), delete }` — `datastore.write:*` |
+| **DATASTORE** | `useDatastoreSubscription(table, handlers, options?)` | `{ status }` — `"connecting" \| "live" \| "reconnecting" \| "fallback"` | `records(table).subscribe` — `datastore.read:<table>`. Live `onCreated` / `onUpdated` / `onDeleted` off the REQ-RT-07 socket; never throws, resolving to `{ status: "fallback" }` so the widget polls instead. A whole-table subscribe is gated on read-EVERY-row, because one envelope reaches every subscriber of the table — so for a table governed by per-record grants pass `options.scope`: `{ kind: "record", record_id }` for one row, or `{ kind: "parent", relation_column, record_id }` for the rows whose RELATION column points at that parent (the column must carry `inheritAcl`, else the subscribe reports `"fallback"`). Re-subscribes on the scope's VALUES, so a fresh object literal each render is fine. |
 | **DATASTORE** | `useRecordPermissions(tableId, recordId)` | `{ permissions, loading, error, grant, revoke, update, refetch }` | `records(table).permissions(record).{ list, grant, update, revoke }` — `acl.write:records` (+ `can_grant` on the record) |
 | **DATASTORE** | `useCanWrite(tableId, options?)` | `{ canWrite, loading, error, refetch }` | `myPermissions(tableId, { recordId? })` — scope `datastore.read:<table>`. A FLOOR, not a full replacement for domain-specific write rules: answers "is this caller signed in AND permitted", reading the same table-ACL answer the write endpoint enforces. Pass `{ recordId }` for a per-row check. A widget whose own rule is MORE SPECIFIC than the table ACL (e.g. "only the assigned user may edit this row") must still hand-check that in addition. Pair with `useUser()` to also tell "not signed in" apart from "signed in but forbidden" — both resolve `canWrite: false` here. Falsy `tableId`, or a host that hasn't injected `myPermissions` (an older host), collapses to `{ canWrite: false, loading: false, error: null, refetch: async () => undefined }` rather than throwing. |
 | **FILES** (`ctx.assets`) | `useAsset(id)` | `{ url, file, loading, error, refetch }` | `ctx.assets.get` — no scope |
@@ -68,7 +69,17 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.108.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.110.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.110.0 (contract 1.84.0)
+
+**`resolveSidebarTokens` and `resolveTopBarTokens` — the rail's and the app bar's tokens, resolved once for both hosts (sc-6289).** The footer strip got a shared resolver in 1.71.0; the two chrome parts beside it did not, so their defaults lived inline in the web Player and again in the compiler — and had drifted. An unset `sidebar.backgroundColor` painted the app background in the Expo export where the Player painted it white, so a dark app shipped a dark drawer beside a white rail; an unset `topBar.textColor` painted the app name slate in the export where the Player has always used the brand colour.
+
+Both resolvers now own their defaults, which are what the web Player renders, so the export follows the appearance the author approved in the Studio rather than the other way round. Unlike `resolveFooterTokens`, the colours are never `null` — a default that lives in the resolver cannot drift, and one that lived in each host already had. `borderColor` stays nullable: the colour is the divider's switch.
+
+The top bar resolves **two** text colours. An unthemed bar paints its icons slate and its app name in the brand colour, and React Navigation's single `headerTintColor` cannot say both — so `tintColor` and `titleColor` are separate, and an authored `topBar.textColor` drives both. `show` is deliberately not among them: it depends on the menu type rather than the theme, and REQ-THEME-14 makes it a no-op on native.
+
+Host-integration surface only — nothing a widget imports changed. `CONTRACT.version` → `1.84.0`.
 
 ### What's new in 0.108.0 (contract 1.82.0)
 

package/dist/contract.cjs

@@ -1469,7 +1469,15 @@ const HOOKS = [
       "{ status: 'fallback' } WITHOUT throwing so the widget can poll instead. " +
       "Reads the same datastore.read scope as useDatastoreQuery — declare " +
       "datastore.read for the table you subscribe to. Pair with " +
-      "useDatastoreQuery for the initial load and merge the streamed envelopes.",
+      "useDatastoreQuery for the initial load and merge the streamed " +
+      "envelopes. `options.scope` narrows the subscription: " +
+      "{ kind: 'record', record_id } streams one record, and " +
+      "{ kind: 'parent', relation_column, record_id } streams the rows whose " +
+      "RELATION column points at that parent — the only way to subscribe to a " +
+      "table governed by per-record grants, since a scope-less subscribe must " +
+      "prove read-every-row. A `parent` scope requires the column be an " +
+      "inheritAcl RELATION, else the subscribe resolves to " +
+      "{ status: 'fallback' }.",
     returnShape: {
       status:
         "'connecting' | 'live' | 'reconnecting' | 'fallback'  // transport state; 'fallback' → poll",
@@ -3341,7 +3349,32 @@ const CONTRACT = deepFreeze({
   //    dark theme's spinner visible instead of grey-on-grey.
   //    `useTheme().colors.loader` is the value a widget reads for its own
   //    loading state; both hosts paint their chrome spinners from the same key.
-  version: "1.82.0",
+  //
+  // 1.83.0: additive (sc-6270) — `useDatastoreSubscription` gains
+  //    `options.scope`, narrowing a subscription from the whole table to one
+  //    record (`{ kind: "record", record_id }`) or to a parent's inheriting
+  //    children (`{ kind: "parent", relation_column, record_id }`). Without it
+  //    a table whose rows are governed by PER-RECORD grants could not stream
+  //    at all: the plane fans one envelope to every subscriber, so a
+  //    scope-less subscribe must prove read-every-row (sc-4311) and a channel
+  //    member never can. A scoped subscribe is gated on the per-record read
+  //    check instead — the same predicate REST applies per row — and `parent`
+  //    additionally requires an `inheritAcl` RELATION column, which is what
+  //    makes the stream a strict subset of what `list()` already returns.
+  //    Backed by datastore-client 0.15.0. Omitting `scope` is unchanged.
+  // 1.84.0: additive (sc-6289) -- `resolveSidebarTokens` and
+  //    `resolveTopBarTokens` (host exports), the rail's and the app bar's
+  //    tokens beside the footer's. Their defaults used to be written separately
+  //    in each host and had drifted: an unset rail took the app background in
+  //    the export where the Player painted it white, and an unset header
+  //    painted the app name slate where the Player used the brand colour. The
+  //    resolvers own the defaults, so a host cannot keep its own. The top bar
+  //    resolves `tintColor` and `titleColor` separately because the web bar has
+  //    always painted its icons slate and its name in the brand colour, which
+  //    one `headerTintColor` cannot express; an authored `topBar.textColor`
+  //    drives both. `show` is deliberately absent -- it depends on the menu
+  //    type, not the theme, and is a no-op on native.
+  version: "1.84.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1469,7 +1469,15 @@ const HOOKS = [
       "{ status: 'fallback' } WITHOUT throwing so the widget can poll instead. " +
       "Reads the same datastore.read scope as useDatastoreQuery — declare " +
       "datastore.read for the table you subscribe to. Pair with " +
-      "useDatastoreQuery for the initial load and merge the streamed envelopes.",
+      "useDatastoreQuery for the initial load and merge the streamed " +
+      "envelopes. `options.scope` narrows the subscription: " +
+      "{ kind: 'record', record_id } streams one record, and " +
+      "{ kind: 'parent', relation_column, record_id } streams the rows whose " +
+      "RELATION column points at that parent — the only way to subscribe to a " +
+      "table governed by per-record grants, since a scope-less subscribe must " +
+      "prove read-every-row. A `parent` scope requires the column be an " +
+      "inheritAcl RELATION, else the subscribe resolves to " +
+      "{ status: 'fallback' }.",
     returnShape: {
       status:
         "'connecting' | 'live' | 'reconnecting' | 'fallback'  // transport state; 'fallback' → poll",
@@ -3341,7 +3349,32 @@ const CONTRACT = deepFreeze({
   //    dark theme's spinner visible instead of grey-on-grey.
   //    `useTheme().colors.loader` is the value a widget reads for its own
   //    loading state; both hosts paint their chrome spinners from the same key.
-  version: "1.82.0",
+  //
+  // 1.83.0: additive (sc-6270) — `useDatastoreSubscription` gains
+  //    `options.scope`, narrowing a subscription from the whole table to one
+  //    record (`{ kind: "record", record_id }`) or to a parent's inheriting
+  //    children (`{ kind: "parent", relation_column, record_id }`). Without it
+  //    a table whose rows are governed by PER-RECORD grants could not stream
+  //    at all: the plane fans one envelope to every subscriber, so a
+  //    scope-less subscribe must prove read-every-row (sc-4311) and a channel
+  //    member never can. A scoped subscribe is gated on the per-record read
+  //    check instead — the same predicate REST applies per row — and `parent`
+  //    additionally requires an `inheritAcl` RELATION column, which is what
+  //    makes the stream a strict subset of what `list()` already returns.
+  //    Backed by datastore-client 0.15.0. Omitting `scope` is unchanged.
+  // 1.84.0: additive (sc-6289) -- `resolveSidebarTokens` and
+  //    `resolveTopBarTokens` (host exports), the rail's and the app bar's
+  //    tokens beside the footer's. Their defaults used to be written separately
+  //    in each host and had drifted: an unset rail took the app background in
+  //    the export where the Player painted it white, and an unset header
+  //    painted the app name slate where the Player used the brand colour. The
+  //    resolvers own the defaults, so a host cannot keep its own. The top bar
+  //    resolves `tintColor` and `titleColor` separately because the web bar has
+  //    always painted its icons slate and its name in the brand colour, which
+  //    one `headerTintColor` cannot express; an authored `topBar.textColor`
+  //    drives both. `show` is deliberately absent -- it depends on the menu
+  //    type, not the theme, and is a no-op on native.
+  version: "1.84.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -2482,7 +2482,9 @@ export function useCanWrite(tableId, options) {
  *
  * @param {string} table  Bound table id (falsy → no subscription, status "fallback").
  * @param {{ onCreated?, onUpdated?, onDeleted? }} [handlers]  Per-event callbacks; each receives the snake_case record.
- * @param {{ fallbackAfterMs?: number }} [options]
+ * @param {{ fallbackAfterMs?: number, scope?: { kind: "record"|"parent", relation_column?: string, record_id: string } }} [options]
+ *   `scope` narrows the stream below whole-table — required for a table
+ *   governed by per-record grants. Re-subscribes on its VALUES, not identity.
  * @returns {{ status: "connecting" | "live" | "reconnecting" | "fallback" }}
  */
 export function useDatastoreSubscription(table, handlers, options) {
@@ -2510,7 +2512,23 @@ export function useDatastoreSubscription(table, handlers, options) {
       ? options.fallbackAfterMs
       : undefined;
 
+  // sc-6270: a scope narrows the subscription to one record or to a parent's
+  // inheriting children. Authors pass a fresh object literal every render, so
+  // the effect keys on the scope's VALUES — depending on its identity would
+  // tear down and reopen the socket on each render.
+  const scope = options && options.scope ? options.scope : null;
+  const scopeKey = scope
+    ? [scope.kind, scope.relation_column, scope.record_id]
+        .map((part) => part || "")
+        .join("|")
+    : "";
+  const scopeRef = useRef(scope);
+  scopeRef.current = scope;
+
   useEffect(() => {
+    // Re-scoping starts a new connection, so a stale "live" from the previous
+    // scope must not mask the gap while it opens.
+    setStatus("connecting");
     if (!table || typeof recordsRef.current !== "function") {
       setStatus("fallback");
       return undefined;
@@ -2527,6 +2545,9 @@ export function useDatastoreSubscription(table, handlers, options) {
       setStatus("fallback");
       return undefined;
     }
+    const subscribeOptions = {};
+    if (fallbackAfterMs != null) subscribeOptions.fallbackAfterMs = fallbackAfterMs;
+    if (scopeRef.current) subscribeOptions.scope = scopeRef.current;
     const stop = ns.subscribe(
       {
         onCreated: (r) => handlersRef.current?.onCreated?.(r),
@@ -2534,13 +2555,13 @@ export function useDatastoreSubscription(table, handlers, options) {
         onDeleted: (r) => handlersRef.current?.onDeleted?.(r),
         onStatus: (s) => setStatus(s),
       },
-      fallbackAfterMs != null ? { fallbackAfterMs } : undefined,
+      Object.keys(subscribeOptions).length > 0 ? subscribeOptions : undefined,
     );
     return () => {
       if (typeof stop === "function") stop();
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [table, fallbackAfterMs]);
+  }, [table, fallbackAfterMs, scopeKey]);
 
   return { status };
 }

package/dist/host.d.ts

@@ -194,6 +194,43 @@ export interface FooterTokens {
  */
 export function resolveFooterTokens(theme: unknown): FooterTokens;
 
+/** The sidebar rail's resolved tokens. Unlike the footer's, the colours are
+ *  never `null`: the default lives here so the two hosts cannot each keep a
+ *  different one. `borderColor` is still nullable — no colour, no divider. */
+export interface SidebarTokens {
+  backgroundColor: string;
+  textColor: string;
+  activeColor: string;
+  activeStyle: "filled" | "accent";
+  borderColor: string | null;
+  borderWidth: number | null;
+}
+
+/**
+ * Resolves the sidebar rail's tokens from a whole `theme_config`. Every default
+ * is what the web Player renders, so the export follows the Player rather than
+ * the other way round.
+ */
+export function resolveSidebarTokens(theme: unknown): SidebarTokens;
+
+/** 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. */
+export interface TopBarTokens {
+  backgroundColor: string;
+  tintColor: string;
+  titleColor: string;
+  borderColor: string | null;
+  borderWidth: number | null;
+}
+
+/**
+ * Resolves the top app bar's tokens from a whole `theme_config`. `show` is not
+ * among them: it depends on the menu type, not the theme, and is a no-op on
+ * native.
+ */
+export function resolveTopBarTokens(theme: unknown): TopBarTokens;
+
 /** A value a widget may persist: a scalar, or a flat array of them. */
 export type WidgetRouteScalar = string | number | boolean;
 export type WidgetRouteValue = WidgetRouteScalar | WidgetRouteScalar[];

package/dist/host.js

@@ -50,11 +50,16 @@ export {
 // 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.
+// 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.
 export {
   normaliseNavigation,
   menuItemCap,
   quickBarCap,
   resolveFooterTokens,
+  resolveSidebarTokens,
+  resolveTopBarTokens,
 } from "./navigation.js";
 
 // sc-5717: the codec behind `useWidgetRoute()` — how a widget's own internal

package/dist/index.d.ts

@@ -1137,8 +1137,16 @@ export interface DatastoreSubscriptionHandlers {
   onDeleted?: (record: Record<string, unknown>) => void;
 }
 
+// sc-6270: see SubscriptionScope in @colixsystems/datastore-client. A scoped
+// subscribe is gated on the per-record read check instead of read-every-row,
+// which is what lets a per-record-ACL table stream at all.
+export type DatastoreSubscriptionScope =
+  | { kind: "record"; record_id: string }
+  | { kind: "parent"; relation_column: string; record_id: string };
+
 export interface DatastoreSubscriptionOptions {
   fallbackAfterMs?: number;
+  scope?: DatastoreSubscriptionScope;
 }
 
 /**
@@ -1148,6 +1156,10 @@ export interface DatastoreSubscriptionOptions {
  * is `"fallback"` (no socket support, ACL-rejected, or connect timed out) run
  * REST polling instead. Never throws — degrades to `{ status: "fallback" }` on
  * a host whose datastore client predates realtime.
+ *
+ * `options.scope` narrows the stream to one record or to a parent's
+ * inheriting children; re-subscribes when the scope's values change, not on
+ * every render.
  */
 export function useDatastoreSubscription(
   tableId: string | null | undefined,

package/dist/navigation.cjs

@@ -25,7 +25,7 @@
 // the SAME literal, so what a planner may persist and what a host draws cannot
 // diverge.
 
-const { CONTRACT } = require("./contract.cjs");
+const { CONTRACT, isHexColor } = require("./contract.cjs");
 
 // Absent or unknown resolves here, so every app authored before menu types
 // existed renders and compiles byte-identically.
@@ -114,6 +114,98 @@ function resolveFooterTokens(theme) {
   };
 }
 
+// REQ-THEME-14 — the rail's and the app bar's tokens, resolved once for both
+// hosts.
+//
+// These return FULLY resolved values where `resolveFooterTokens` above returns
+// raw-or-null, and the difference is deliberate. The footer's two hosts happen
+// to agree on their separately-written defaults; the rail's and the bar's did
+// not. An unset `sidebar.backgroundColor` painted #ffffff on web and the app
+// background in the export, and an unset `topBar.textColor` painted the brand
+// primary on web and slate-700 in the export. A default that lives in the
+// resolver cannot drift; one that lives in each host already had. The footer
+// wants this same shape next — the same fix, not yet applied.
+//
+// Every default is what the WEB Player renders today, so the Player does not
+// move and the export converges onto it. That is the direction the footer was
+// converged in too (compiler.service's footerBg defaults to the web's #ffffff).
+
+const DEFAULT_PRIMARY_COLOR = "#3b82f6";
+// The web rail's and app bar's `bg-white`.
+const DEFAULT_CHROME_SURFACE = "#ffffff";
+// The web nav item's `text-slate-600`.
+const DEFAULT_CHROME_TEXT = "#475569";
+// The web mobile header's icon colour, `text-slate-700`.
+const DEFAULT_TOP_BAR_TINT = "#334155";
+
+// The contract's own guard, which already admits the 8-digit form a look uses
+// to float a translucent rail (#RRGGBBAA).
+function hexOrNull(value) {
+  return isHexColor(value) ? value : null;
+}
+
+function hexOr(value, fallback) {
+  return hexOrNull(value) || fallback;
+}
+
+function brandPrimary(config) {
+  return hexOr(config.primaryColor, DEFAULT_PRIMARY_COLOR);
+}
+
+/**
+ * The sidebar rail's surface, labels, active item and opt-in divider.
+ *
+ * @param {unknown} theme — the whole `theme_config`; `primaryColor` is read
+ *   because an unset active colour resolves to the brand.
+ * @returns {{ backgroundColor: string, textColor: string, activeColor: string,
+ *   activeStyle: string, borderColor: string|null, borderWidth: number|null }}
+ */
+function resolveSidebarTokens(theme) {
+  const config = isPlainObject(theme) ? theme : {};
+  const sidebar = isPlainObject(config.sidebar) ? config.sidebar : {};
+  const borderColor = hexOrNull(sidebar.borderColor);
+  return {
+    backgroundColor: hexOr(sidebar.backgroundColor, DEFAULT_CHROME_SURFACE),
+    textColor: hexOr(sidebar.textColor, DEFAULT_CHROME_TEXT),
+    activeColor: hexOr(sidebar.activeColor, brandPrimary(config)),
+    activeStyle: sidebar.activeStyle === "accent" ? "accent" : "filled",
+    // REQ-THEME-LOOK: the colour is the switch — no colour, no line.
+    borderColor,
+    borderWidth: borderColor ? borderWidthOr(sidebar.borderWidth) : null,
+  };
+}
+
+/**
+ * The top app bar's surface, its two text colours and its opt-in divider.
+ *
+ * `tintColor` and `titleColor` are SEPARATE because the web bar has always
+ * painted them differently when the author names nothing: the hamburger and
+ * icons take slate, the app name takes the brand. React Navigation's single
+ * `headerTintColor` could not express that, which is why the export used to
+ * paint the name slate. One token, two resolved fields, both hosts agree.
+ *
+ * `show` is deliberately absent: it depends on the menu TYPE, not the theme,
+ * and REQ-THEME-14 makes it a no-op on native — so it is not a shared token.
+ *
+ * @param {unknown} theme — the whole `theme_config`.
+ * @returns {{ backgroundColor: string, tintColor: string, titleColor: string,
+ *   borderColor: string|null, borderWidth: number|null }}
+ */
+function resolveTopBarTokens(theme) {
+  const config = isPlainObject(theme) ? theme : {};
+  const topBar = isPlainObject(config.topBar) ? config.topBar : {};
+  const borderColor = hexOrNull(topBar.borderColor);
+  // An explicit colour drives BOTH slots; only the unset case splits.
+  const authored = hexOrNull(topBar.textColor);
+  return {
+    backgroundColor: hexOr(topBar.backgroundColor, DEFAULT_CHROME_SURFACE),
+    tintColor: authored || DEFAULT_TOP_BAR_TINT,
+    titleColor: authored || brandPrimary(config),
+    borderColor,
+    borderWidth: borderColor ? borderWidthOr(topBar.borderWidth) : null,
+  };
+}
+
 function borderWidthOr(...values) {
   for (const value of values) {
     if (typeof value === "number" && Number.isFinite(value)) return value;
@@ -121,4 +213,4 @@ function borderWidthOr(...values) {
   return 1;
 }
 
-module.exports = { normaliseNavigation, menuItemCap, quickBarCap, resolveFooterTokens };
+module.exports = { normaliseNavigation, menuItemCap, quickBarCap, resolveFooterTokens, resolveSidebarTokens, resolveTopBarTokens };

package/dist/navigation.js

@@ -16,7 +16,7 @@
 // the SAME literal, so what a planner may persist and what a host draws cannot
 // diverge.
 
-import { CONTRACT } from "./contract.js";
+import { CONTRACT, isHexColor } from "./contract.js";
 
 // Absent or unknown resolves here, so every app authored before menu types
 // existed renders and compiles byte-identically.
@@ -105,6 +105,98 @@ export function resolveFooterTokens(theme) {
   };
 }
 
+// REQ-THEME-14 — the rail's and the app bar's tokens, resolved once for both
+// hosts.
+//
+// These return FULLY resolved values where `resolveFooterTokens` above returns
+// raw-or-null, and the difference is deliberate. The footer's two hosts happen
+// to agree on their separately-written defaults; the rail's and the bar's did
+// not. An unset `sidebar.backgroundColor` painted #ffffff on web and the app
+// background in the export, and an unset `topBar.textColor` painted the brand
+// primary on web and slate-700 in the export. A default that lives in the
+// resolver cannot drift; one that lives in each host already had. The footer
+// wants this same shape next — the same fix, not yet applied.
+//
+// Every default is what the WEB Player renders today, so the Player does not
+// move and the export converges onto it. That is the direction the footer was
+// converged in too (compiler.service's footerBg defaults to the web's #ffffff).
+
+const DEFAULT_PRIMARY_COLOR = "#3b82f6";
+// The web rail's and app bar's `bg-white`.
+const DEFAULT_CHROME_SURFACE = "#ffffff";
+// The web nav item's `text-slate-600`.
+const DEFAULT_CHROME_TEXT = "#475569";
+// The web mobile header's icon colour, `text-slate-700`.
+const DEFAULT_TOP_BAR_TINT = "#334155";
+
+// The contract's own guard, which already admits the 8-digit form a look uses
+// to float a translucent rail (#RRGGBBAA).
+function hexOrNull(value) {
+  return isHexColor(value) ? value : null;
+}
+
+function hexOr(value, fallback) {
+  return hexOrNull(value) || fallback;
+}
+
+function brandPrimary(config) {
+  return hexOr(config.primaryColor, DEFAULT_PRIMARY_COLOR);
+}
+
+/**
+ * The sidebar rail's surface, labels, active item and opt-in divider.
+ *
+ * @param {unknown} theme — the whole `theme_config`; `primaryColor` is read
+ *   because an unset active colour resolves to the brand.
+ * @returns {{ backgroundColor: string, textColor: string, activeColor: string,
+ *   activeStyle: string, borderColor: string|null, borderWidth: number|null }}
+ */
+export function resolveSidebarTokens(theme) {
+  const config = isPlainObject(theme) ? theme : {};
+  const sidebar = isPlainObject(config.sidebar) ? config.sidebar : {};
+  const borderColor = hexOrNull(sidebar.borderColor);
+  return {
+    backgroundColor: hexOr(sidebar.backgroundColor, DEFAULT_CHROME_SURFACE),
+    textColor: hexOr(sidebar.textColor, DEFAULT_CHROME_TEXT),
+    activeColor: hexOr(sidebar.activeColor, brandPrimary(config)),
+    activeStyle: sidebar.activeStyle === "accent" ? "accent" : "filled",
+    // REQ-THEME-LOOK: the colour is the switch — no colour, no line.
+    borderColor,
+    borderWidth: borderColor ? borderWidthOr(sidebar.borderWidth) : null,
+  };
+}
+
+/**
+ * The top app bar's surface, its two text colours and its opt-in divider.
+ *
+ * `tintColor` and `titleColor` are SEPARATE because the web bar has always
+ * painted them differently when the author names nothing: the hamburger and
+ * icons take slate, the app name takes the brand. React Navigation's single
+ * `headerTintColor` could not express that, which is why the export used to
+ * paint the name slate. One token, two resolved fields, both hosts agree.
+ *
+ * `show` is deliberately absent: it depends on the menu TYPE, not the theme,
+ * and REQ-THEME-14 makes it a no-op on native — so it is not a shared token.
+ *
+ * @param {unknown} theme — the whole `theme_config`.
+ * @returns {{ backgroundColor: string, tintColor: string, titleColor: string,
+ *   borderColor: string|null, borderWidth: number|null }}
+ */
+export function resolveTopBarTokens(theme) {
+  const config = isPlainObject(theme) ? theme : {};
+  const topBar = isPlainObject(config.topBar) ? config.topBar : {};
+  const borderColor = hexOrNull(topBar.borderColor);
+  // An explicit colour drives BOTH slots; only the unset case splits.
+  const authored = hexOrNull(topBar.textColor);
+  return {
+    backgroundColor: hexOr(topBar.backgroundColor, DEFAULT_CHROME_SURFACE),
+    tintColor: authored || DEFAULT_TOP_BAR_TINT,
+    titleColor: authored || brandPrimary(config),
+    borderColor,
+    borderWidth: borderColor ? borderWidthOr(topBar.borderWidth) : null,
+  };
+}
+
 function borderWidthOr(...values) {
   for (const value of values) {
     if (typeof value === "number" && Number.isFinite(value)) return value;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.108.0",
+  "version": "0.110.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",