@colixsystems/widget-sdk 0.251.0 → 0.256.0

package/README.md

@@ -46,6 +46,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useSpeechToText(options)` (optional: options) | `{ transcript, partial, listening, supported, error, start, stop, abort, reset }` | `ctx.device.speech` — no scope. Dictation with the device's **on-device** recogniser: no audio is uploaded and no AI credit is spent. Capture is IMPERATIVE: call `start()` from a user gesture (a tap), never on mount. `transcript` accumulates finalised speech, `partial` holds the uncommitted guess (needs `options.interimResults`); `stop()` keeps it, `abort()` discards it. Rejects with `SpeechToTextError` (`.code` in `PERMISSION_DENIED \| NO_SPEECH \| LANGUAGE_UNSUPPORTED \| NETWORK \| ABORTED \| UNSUPPORTED \| INTERNAL`). **Gate your mic button on `supported`** — Firefox ships no `SpeechRecognition`. Identical on web (`SpeechRecognition`) and the Expo export (`expo-speech-recognition`). |
 | **CORE** | `useCamera(options)` (optional: options) | `{ asset, loading, error, supported, capture, pick, reset }` | `ctx.device.camera` — no scope. Take a photo (`capture()`) or choose one (`pick()`). Capture is IMPERATIVE: call from a user gesture (a tap), never on mount. Both resolve a normalised `{ uri, name, mimeType, width, height, size, file }`, or **`null` when the user dismisses the picker** — dismissal is not an error, so no `try/catch` is needed on the happy path. Rejects with `CameraError` (`.code` in `PERMISSION_DENIED \| UNSUPPORTED \| INTERNAL`). `asset.file` is already the right upload part for the host, so `fd.append("file", asset.file)` → `ctx.assets.upload(fd)` is ONE code path on both. **Gate your camera button on `supported`.** Identical on web (a live `getUserMedia` preview, phones included; a file input only where getUserMedia is absent) and the Expo export (`expo-image-picker`). |
 | **CORE** | `useI18n()` | `{ t, locale, languages, canSetLocale, setLocale }` | `ctx.i18n` — no scope. `t(key)` resolves the widget-namespaced key (`widget.<id>.<key>`, declared in `manifest.translations`) first, then a **predefined shared key** (`shared.<key>`) when `key` is one of the standard strings (`submit`, `cancel`, `save`, `loading`, …), then the raw key. Use a shared key for an identical default string so it translates once and any per-instance `widget.<id>.<key>` override still wins. `languages` lists the app's active languages (`[{ code, name, is_base }]`); `setLocale(code)` switches the whole app live — saved to a signed-in user's account, kept on the device for a visitor, `null` for the app default. Rejects with `.code` `INVALID_LOCALE` \| `UNSUPPORTED`; `canSetLocale` is false where the host cannot switch (the Builder canvas). |
+| **CORE** | `useAppearance()` | `{ mode, preference, canSwitch, setPreference }` | `ctx.appearance` — no scope. `mode` is the palette showing (`light` \| `dark`), `preference` what the app follows (`light` \| `dark` \| `system`). `setPreference(p)` switches the whole app live — saved to a signed-in user's account, kept on the device for a visitor, `null` for the app default. Rejects with `.code` `UNSUPPORTED` \| `INVALID_APPEARANCE`; `canSwitch` is false where the app does not let users switch and on the Builder canvas. |
 | **CORE** | `useTranslate()` | `{ translate, translating, error, language, available }` | `ctx.i18n.translate` — no scope. Machine-translates **user-generated content** (record text, file names, API payloads) into the app user's language; `useI18n().t()` is still the answer for your own copy. `translate(str)` → `Promise<string>`, `translate(str[])` → `Promise<string[]>` in ONE request. Target defaults to the app user's language. Cached per session, per pod, and durably per workspace, so repeat text is free. Limits: 50 segments / 5 000 chars each / 20 000 total. Rejects with `TranslateError`; `available` is false where the host cannot translate. |
 | **CORE** | `useLinkPreview(url)` | `{ preview, loading, error, available }` — `preview` is `{ url, title, description, site_name, image_url } \| null` | `ctx.linkPreviews.get` — no scope. A link's title, description, site name and image, fetched by the platform (the device never contacts the linked site). A page with nothing to show resolves with null fields, not an error — render the plain link. A non-http(s) `url` makes no request. Memoized for up to an hour across widgets; concurrent calls for one URL share a request. `error` is a `LinkPreviewError` (`VALIDATION` \| `AUTH_REQUIRED` \| `RATE_LIMITED` \| `NETWORK` \| `INTERNAL`). `available` is false on a host with no link-preview client |
 | **CORE** | `useStableQuery(buildQuery)` | `T \| undefined` (whatever `buildQuery()` returns) | No context slice, no scope. Keeps `buildQuery()`'s result at a STABLE reference across renders when its (JSON-serialised) content hasn't changed, so `useDatastoreQuery(tableId, useStableQuery(() => ({...})))` replaces a hand-rolled `useMemo` with an easy-to-get-wrong deps array. Never throws: a `buildQuery` that itself throws degrades to a stable `undefined`; a result that can't be diffed (e.g. circular) degrades to "always a new reference". |
@@ -84,7 +85,46 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.251.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.256.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.256.0 (contract 1.207.0)
+
+**A page's top navigation bar can centre its tabs again.** `resolveTopBarTokens().tabAlignment` is `"left"` | `"center"` | `"right"`. A `theme_config.topBar.tabAlignment` of `"center"` places the tabs between two flexible spacers, never by centring the row, so a row with more tabs than fit still scrolls from its first tab. Unset or unknown still resolves to `"left"`, so an app that never chose is unchanged. Host-integration surface only — no author-facing hook, prop, primitive, or manifest field changed.
+
+### What's new in 0.255.0
+
+**Storing a look in both modes.** `themeInBothModes(theme, mode, twin)` on `@colixsystems/widget-sdk/host` takes a theme painted in `mode` and the palette of the other mode, and returns it the way an app with a light and a dark palette stores it: the base is the light palette and `dark` the dark one. Painted light, the theme stays and `twin` becomes `dark`. Painted dark, its own colours become `dark` and `twin` is laid over the base. `DARK_PALETTE_KEYS` names the top-level theme keys a dark palette may recolour. Host-integration only; nothing changes for widget authors.
+
+### What's new in 0.254.0
+
+**A widget can switch the app between light and dark — `useAppearance()`.** Where an app has a light and a dark palette and lets its users choose, `useAppearance()` returns `{ mode, preference, canSwitch, setPreference }`. `mode` is the palette showing (`"light"` or `"dark"`); `preference` is what the app follows (`"light"`, `"dark"` or `"system"`, the device's setting). `setPreference(preference)` switches the whole app at once, with no reload, through the same switch as the account screen: a signed-in user's choice is saved to their account, a visitor's stays on this device, and `null` returns to the app's default. It rejects with an `Error` whose `.code` is `UNSUPPORTED` (the app does not let users switch, or the Builder canvas) or `INVALID_APPEARANCE`. Render your controls disabled when `canSwitch` is false. You need no hook for colours: `useTheme()` already returns the palette showing. An app without the setting reads `mode: "light"`, `canSwitch: false`. The same on the web Player and the exported app.
+
+```jsx
+import { useAppearance, Pressable, Text } from "@colixsystems/widget-sdk";
+
+export default function DarkSwitch() {
+  const { mode, canSwitch, setPreference } = useAppearance();
+  const next = mode === "dark" ? "light" : "dark";
+  return (
+    <Pressable disabled={!canSwitch} onPress={() => setPreference(next).catch(() => {})}>
+      <Text>{mode === "dark" ? "Use light" : "Use dark"}</Text>
+    </Pressable>
+  );
+}
+```
+
+### What's new in 0.253.0
+
+**Knowing when to follow the device.** `resolveAppearancePreference({ appearance, userChoice })` on `@colixsystems/widget-sdk/host` returns what an app follows: `"light"`, `"dark"` or `"system"`. It applies the same precedence as `resolveAppearanceMode` but stops before asking the device, so a host can subscribe to the device's colour scheme only while the answer is `"system"`. `resolveAppearanceMode` is now built on it and returns the same results. Host-integration only; nothing changes for widget authors.
+
+### What's new in 0.252.0
+
+**Host helpers for an app's light and dark palettes.** A workspace theme can now carry a second, colour-only palette (`themeConfig.dark`) and a setting for which palette an app opens on (`themeConfig.appearance`: `{ default: "light" | "dark" | "system", userCanSwitch }`). Two helpers on `@colixsystems/widget-sdk/host` decide what to render, and both hosts call them, so a dark palette means the same thing in the web Player and in the exported app:
+
+- `resolveAppearanceMode({ appearance, userChoice, systemScheme })` returns `"light"` or `"dark"`. A user's choice wins only where the app lets users switch. Otherwise the app's default applies, and `"system"` follows the device, falling back to light when the device reports nothing. No setting means light.
+- `resolveThemeForAppearance(themeConfig, mode)` returns the theme to render, without `dark` or `appearance`. In dark mode it lays the palette's colours over the base, key by key. A theme carrying neither key comes back unchanged.
+
+`themePaletteOf(theme)` returns the colour-bearing part of a theme, which is the shape a dark palette may hold. `normaliseAppearance`, `APPEARANCE_MODES` and `APPEARANCE_PREFERENCES` come with them. These are host-integration helpers, not something a widget imports. Nothing changes for widget authors: `useTheme()` keeps returning the resolved theme.
 
 ### What's new in 0.251.0 (contract 1.205.0)
 

package/dist/contract.cjs

@@ -885,6 +885,29 @@ const HOOKS = [
     requiredContextSlice: ["i18n.t", "i18n.locale"],
     scopes: null,
   },
+  {
+    name: "useAppearance",
+    signature: "useAppearance()",
+    description:
+      "The app's light or dark palette, and the app user's own choice of it. mode is the palette showing (\"light\" | \"dark\"); " +
+      "preference is what the app follows (\"light\" | \"dark\" | \"system\", where system follows the device). " +
+      "setPreference(preference) switches the WHOLE app live, with no reload, through the same switch as the account screen: " +
+      "a signed-in user's choice is saved to their account, a visitor who is not signed in keeps it on this device, and null " +
+      "returns to the app's default. It resolves once the choice is saved and rejects with an Error whose .code is UNSUPPORTED " +
+      "(canSwitch is false: the app does not let its users switch, or this is the Builder canvas) or INVALID_APPEARANCE — always " +
+      "catch it. canSwitch is false on such a host: render the choices disabled then, never a dead button. Colours need no " +
+      "hook: useTheme() already returns the palette showing. An app without an appearance setting reads light, canSwitch false. " +
+      "Identical on web (Player) and the Expo export.",
+    returnShape: {
+      mode: "\"light\" | \"dark\"",
+      preference: "\"light\" | \"dark\" | \"system\"",
+      canSwitch: "boolean",
+      setPreference:
+        "(preference: \"light\" | \"dark\" | \"system\" | null) => Promise<void>  // rejects with Error .code UNSUPPORTED | INVALID_APPEARANCE",
+    },
+    requiredContextSlice: [],
+    scopes: null,
+  },
   {
     name: "useTranslate",
     signature: "useTranslate()",
@@ -3998,6 +4021,16 @@ const WIDGET_CONTEXT_SHAPE = {
     required: false,
     fields: { setPhoto: "function", removePhoto: "function", anonymous: "object" },
   },
+  // REQ-THEME-APPEARANCE — backs useAppearance().
+  appearance: {
+    description:
+      "Optional. { mode: \"light\" | \"dark\", preference: \"light\" | \"dark\" | \"system\", setPreference?(preference) -> Promise<void> } " +
+      "backs useAppearance(). setPreference is the host's own appearance switch and is present only where the app user may " +
+      "switch. The whole slice is absent where the app has no appearance setting, and for a badge counter.",
+    required: false,
+    fields: { mode: "string", preference: "string" },
+    optionalFields: { setPreference: "function" },
+  },
   workspace: {
     description:
       "Workspace identity + resolved theme + charge currency ({ id, slug, theme, locale, currency }).",
@@ -6335,7 +6368,13 @@ const CONTRACT = deepFreeze({
   // 1.205.0: additive (sc-11840) — a string property's `default` shows as the
   //    field's editable text and clearing stores ""; `ui.placeholder` and
   //    `ui.clearRestoresDefault` are typed.
-  version: "1.205.0",
+  // 1.206.0: additive (sc-12335) — `useAppearance()` returns the palette
+  //    showing, the app's appearance preference, `canSwitch` and
+  //    `setPreference`, backed by the optional `appearance` host slice. Hosts
+  //    without it read light / false.
+  // 1.207.0: additive (sc-12198) — `resolveTopBarTokens().tabAlignment` is
+  //    "left" | "center" | "right" again; "center" centres the tabs.
+  version: "1.207.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -6744,8 +6783,14 @@ function scaleSpacing(value, scale) {
   return Math.round(value * clampSpacingScale(scale));
 }
 
+// REQ-THEME-APPEARANCE (sc-12335): what an app opens on, and what its users
+// may choose — a palette or the device's. One list for useAppearance() and the
+// host resolvers in theme-appearance.js.
+const APPEARANCE_PREFERENCES = Object.freeze(["light", "dark", "system"]);
+
 module.exports = {
   CONTRACT,
+  APPEARANCE_PREFERENCES,
   clampSpacingScale,
   scaleSpacing,
   normaliseActionTriggerTypes,

package/dist/contract.js

@@ -885,6 +885,29 @@ const HOOKS = [
     requiredContextSlice: ["i18n.t", "i18n.locale"],
     scopes: null,
   },
+  {
+    name: "useAppearance",
+    signature: "useAppearance()",
+    description:
+      "The app's light or dark palette, and the app user's own choice of it. mode is the palette showing (\"light\" | \"dark\"); " +
+      "preference is what the app follows (\"light\" | \"dark\" | \"system\", where system follows the device). " +
+      "setPreference(preference) switches the WHOLE app live, with no reload, through the same switch as the account screen: " +
+      "a signed-in user's choice is saved to their account, a visitor who is not signed in keeps it on this device, and null " +
+      "returns to the app's default. It resolves once the choice is saved and rejects with an Error whose .code is UNSUPPORTED " +
+      "(canSwitch is false: the app does not let its users switch, or this is the Builder canvas) or INVALID_APPEARANCE — always " +
+      "catch it. canSwitch is false on such a host: render the choices disabled then, never a dead button. Colours need no " +
+      "hook: useTheme() already returns the palette showing. An app without an appearance setting reads light, canSwitch false. " +
+      "Identical on web (Player) and the Expo export.",
+    returnShape: {
+      mode: "\"light\" | \"dark\"",
+      preference: "\"light\" | \"dark\" | \"system\"",
+      canSwitch: "boolean",
+      setPreference:
+        "(preference: \"light\" | \"dark\" | \"system\" | null) => Promise<void>  // rejects with Error .code UNSUPPORTED | INVALID_APPEARANCE",
+    },
+    requiredContextSlice: [],
+    scopes: null,
+  },
   {
     name: "useTranslate",
     signature: "useTranslate()",
@@ -3994,6 +4017,16 @@ const WIDGET_CONTEXT_SHAPE = {
     required: false,
     fields: { setPhoto: "function", removePhoto: "function", anonymous: "object" },
   },
+  // REQ-THEME-APPEARANCE — backs useAppearance().
+  appearance: {
+    description:
+      "Optional. { mode: \"light\" | \"dark\", preference: \"light\" | \"dark\" | \"system\", setPreference?(preference) -> Promise<void> } " +
+      "backs useAppearance(). setPreference is the host's own appearance switch and is present only where the app user may " +
+      "switch. The whole slice is absent where the app has no appearance setting, and for a badge counter.",
+    required: false,
+    fields: { mode: "string", preference: "string" },
+    optionalFields: { setPreference: "function" },
+  },
   workspace: {
     description:
       "Workspace identity + resolved theme + charge currency ({ id, slug, theme, locale, currency }).",
@@ -6331,7 +6364,13 @@ const CONTRACT = deepFreeze({
   // 1.205.0: additive (sc-11840) — a string property's `default` shows as the
   //    field's editable text and clearing stores ""; `ui.placeholder` and
   //    `ui.clearRestoresDefault` are typed.
-  version: "1.205.0",
+  // 1.206.0: additive (sc-12335) — `useAppearance()` returns the palette
+  //    showing, the app's appearance preference, `canSwitch` and
+  //    `setPreference`, backed by the optional `appearance` host slice. Hosts
+  //    without it read light / false.
+  // 1.207.0: additive (sc-12198) — `resolveTopBarTokens().tabAlignment` is
+  //    "left" | "center" | "right" again; "center" centres the tabs.
+  version: "1.207.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -6740,8 +6779,14 @@ function scaleSpacing(value, scale) {
   return Math.round(value * clampSpacingScale(scale));
 }
 
+// REQ-THEME-APPEARANCE (sc-12335): what an app opens on, and what its users
+// may choose — a palette or the device's. One list for useAppearance() and the
+// host resolvers in theme-appearance.js.
+const APPEARANCE_PREFERENCES = Object.freeze(["light", "dark", "system"]);
+
 export {
   CONTRACT,
+  APPEARANCE_PREFERENCES,
   clampSpacingScale,
   scaleSpacing,
   normaliseActionTriggerTypes,

package/dist/hooks.js

@@ -48,6 +48,8 @@ import {
   // host codec so the hook and the encoder can never disagree about it.
   sameWidgetRouteValue,
   deriveSurfaceTokens,
+  // sc-12335 — the light/dark vocabulary useAppearance() validates against.
+  APPEARANCE_PREFERENCES,
 } from "./contract.js";
 
 /** @internal — host-injected context value of shape WidgetContext (see index.d.ts). */
@@ -1105,6 +1107,47 @@ export function useI18n() {
   return { t, locale, languages, canSetLocale: hostSetLocale !== null, setLocale };
 }
 
+function appearanceError(code, message) {
+  const err = new Error(message);
+  err.code = code;
+  return err;
+}
+
+/**
+ * REQ-THEME-APPEARANCE — `{ mode, preference, canSwitch, setPreference }`.
+ * `mode` is the palette showing ("light" | "dark"); `preference` is what the
+ * app follows ("light" | "dark" | "system"). `setPreference` is the host's own
+ * switch, the one its account screen uses; it rejects UNSUPPORTED where the
+ * user may not switch (`canSwitch` false) and INVALID_APPEARANCE for any other
+ * value. Without the optional `ctx.appearance` slice: light, and no switch.
+ */
+export function useAppearance() {
+  const ctx = useWidgetContextOrThrow("useAppearance");
+  const slice = ctx.appearance || null;
+  const mode = slice && slice.mode === "dark" ? "dark" : "light";
+  const preference =
+    slice && APPEARANCE_PREFERENCES.includes(slice.preference) ? slice.preference : mode;
+  const hostSetPreference =
+    slice && typeof slice.setPreference === "function" ? slice.setPreference : null;
+  // Validated here so both hosts refuse a bad value identically.
+  const setPreference = useCallback(
+    async (next) => {
+      if (!hostSetPreference) {
+        throw appearanceError("UNSUPPORTED", "The appearance cannot be changed here.");
+      }
+      if (next !== null && !APPEARANCE_PREFERENCES.includes(next)) {
+        throw appearanceError(
+          "INVALID_APPEARANCE",
+          `"${next}" is not one of: ${APPEARANCE_PREFERENCES.join(", ")}.`,
+        );
+      }
+      await hostSetPreference(next);
+    },
+    [hostSetPreference],
+  );
+  return { mode, preference, canSwitch: hostSetPreference !== null, setPreference };
+}
+
 /**
  * sc-3783 — structured error thrown by `useTranslate().translate`. Carries a
  * stable `code` so widgets branch without parsing message strings; mirrors the

package/dist/host.d.ts

@@ -409,7 +409,7 @@ export interface TopBarTokens {
    *  current tab so the page shows through it. */
   tabStyle: "underline" | "attached";
   /** Where the row's tabs sit across its width; `left` unless authored. */
-  tabAlignment: "left" | "right";
+  tabAlignment: "left" | "center" | "right";
   /** The column the tabs sit in: the whole bar, or the page content's. The
    *  bar's surface spans the full width either way. */
   tabRowWidth: "full" | "content";
@@ -653,3 +653,62 @@ export function formatDateTimeLabel(
   mode: "date" | "time" | "datetime",
   locale?: string,
 ): string;
+
+/** REQ-THEME-APPEARANCE — the two palettes an app can render. */
+export type AppearanceMode = "light" | "dark";
+
+/** What an app opens on, and what a user may choose: a mode or the device's. */
+export type AppearancePreference = AppearanceMode | "system";
+
+/** A normalised `theme_config.appearance`. */
+export interface AppearanceSettings {
+  default: AppearancePreference;
+  userCanSwitch: boolean;
+}
+
+export const APPEARANCE_MODES: readonly AppearanceMode[];
+export const APPEARANCE_PREFERENCES: readonly AppearancePreference[];
+
+/**
+ * The colour-bearing part of a theme (every hex leaf and every gradient, at its
+ * path): exactly the shape a `theme_config.dark` palette may hold.
+ */
+export function themePaletteOf(theme: unknown): Record<string, unknown>;
+
+/** A stored `theme_config.appearance`, or null when it is not one. */
+export function normaliseAppearance(raw: unknown): AppearanceSettings | null;
+
+/**
+ * What an app follows: the user's choice where the app lets users switch,
+ * else the app's default. No appearance setting resolves to light.
+ */
+export function resolveAppearancePreference(input?: {
+  appearance?: unknown;
+  userChoice?: unknown;
+}): AppearancePreference;
+
+/**
+ * Which palette an app shows: its preference, where `system` follows
+ * `systemScheme` and reads light when unknown.
+ */
+export function resolveAppearanceMode(input?: {
+  appearance?: unknown;
+  userChoice?: unknown;
+  systemScheme?: unknown;
+}): AppearanceMode;
+
+/**
+ * The theme to render in `mode`, without `dark` or `appearance`. Dark lays the
+ * `dark` palette's colours over the base; light is the base. A theme carrying
+ * neither key is returned by reference.
+ */
+export function resolveThemeForAppearance<T>(themeConfig: T, mode: AppearanceMode): T;
+
+/** The top-level theme keys a `dark` palette may recolour. */
+export const DARK_PALETTE_KEYS: readonly string[];
+
+/**
+ * A theme painted in `mode`, plus the other mode's palette, as an app with an
+ * appearance setting stores it: the base light, `dark` the dark palette.
+ */
+export function themeInBothModes<T>(theme: T, mode: AppearanceMode, twin: unknown): T;

package/dist/host.js

@@ -152,6 +152,21 @@ export {
   resolveLoginTextVisibility,
 } from "./theme-background.js";
 
+// REQ-THEME-APPEARANCE (sc-12335): an app's light and dark palettes. Each host
+// resolves the mode it shows and the theme it renders through these, so a dark
+// palette and the choice of palette mean the same thing on web and native.
+export {
+  APPEARANCE_MODES,
+  APPEARANCE_PREFERENCES,
+  themePaletteOf,
+  normaliseAppearance,
+  resolveAppearancePreference,
+  resolveAppearanceMode,
+  resolveThemeForAppearance,
+  DARK_PALETTE_KEYS,
+  themeInBothModes,
+} from "./theme-appearance.js";
+
 // sc-8448: one DATETIME local-clock conversion for the picker and the Studio.
 export {
   isoToDateTimeLocalInput,

package/dist/index.d.ts

@@ -845,6 +845,15 @@ export interface WidgetContext<TProps = unknown> {
     removePhoto?(): Promise<{ photoUrl: null }>;
     anonymous?: AnonymousAccountHost;
   };
+  /**
+   * Optional; backs `useAppearance()`. `setPreference` is present only where
+   * the app user may switch. Absent where the app has no appearance setting.
+   */
+  appearance?: {
+    mode: "light" | "dark";
+    preference: AppearancePreference;
+    setPreference?(preference: AppearancePreference | null): Promise<void>;
+  };
   workspace: {
     id: string;
     slug: string;
@@ -2018,6 +2027,26 @@ export function useI18n(): {
   setLocale(code: string | null): Promise<void>;
 };
 
+/** What an app follows: a fixed palette, or the device's setting. */
+export type AppearancePreference = "light" | "dark" | "system";
+
+/**
+ * The app's light or dark palette, and the app user's own choice of it.
+ * `mode` is the palette showing; `preference` is what the app follows.
+ * `setPreference` switches the whole app live, through the same switch as the
+ * account screen: a signed-in user's choice is saved to their account, a
+ * visitor's stays on the device, and `null` returns to the app's default.
+ * Rejects with an Error whose `.code` is `UNSUPPORTED` (`canSwitch` is false:
+ * the app does not let users switch, or this is the Builder canvas) or
+ * `INVALID_APPEARANCE`.
+ */
+export function useAppearance(): {
+  mode: "light" | "dark";
+  preference: AppearancePreference;
+  canSwitch: boolean;
+  setPreference(preference: AppearancePreference | null): Promise<void>;
+};
+
 /**
  * sc-3783 — translate USER-GENERATED content (record text, file names, API
  * payloads) into the app user's selected language.

package/dist/index.js

@@ -72,6 +72,7 @@ export {
   useTheme,
   useWidgetStyle,
   useI18n,
+  useAppearance,
   useTranslate,
   TranslateError,
   useLinkPreview,

package/dist/index.native.js

@@ -72,6 +72,7 @@ export {
   useTheme,
   useWidgetStyle,
   useI18n,
+  useAppearance,
   useTranslate,
   TranslateError,
   useLinkPreview,

package/dist/navigation.cjs

@@ -566,11 +566,8 @@ function resolveTopStripeLayout(theme) {
     // reading the bar; so does the SITE header, which is shown instead of this
     // row rather than beside it.
     //
-    // The notification bell is the one member of `slots` this does not reach.
-    // It keeps its own resting colour on both hosts — web reads the authored
-    // `topBar.textColor` and the export tints it not at all — and moving it
-    // here would widen that difference rather than close it. Whoever closes it
-    // should move both hosts at once.
+    // The notification bell is one of the row's icons and takes this tint on
+    // both hosts; the bells outside the row keep the bar's.
     tintColor: hexOr(stripe.textColor, barTokens.tintColor),
     titleColor: hexOr(stripe.textColor, barTokens.titleColor),
     order,
@@ -617,7 +614,7 @@ function resolveAppLogo(logo, darkSurfaceLogo, onDark) {
   return onDark && darkSurfaceLogo ? darkSurfaceLogo : logo;
 }
 
-const TAB_ALIGNMENTS = ["left", "right"];
+const TAB_ALIGNMENTS = ["left", "center", "right"];
 const TAB_ROW_WIDTHS = ["full", "content"];
 
 function resolveTopBarTokens(theme) {

package/dist/navigation.js

@@ -557,11 +557,8 @@ export function resolveTopStripeLayout(theme) {
     // reading the bar; so does the SITE header, which is shown instead of this
     // row rather than beside it.
     //
-    // The notification bell is the one member of `slots` this does not reach.
-    // It keeps its own resting colour on both hosts — web reads the authored
-    // `topBar.textColor` and the export tints it not at all — and moving it
-    // here would widen that difference rather than close it. Whoever closes it
-    // should move both hosts at once.
+    // The notification bell is one of the row's icons and takes this tint on
+    // both hosts; the bells outside the row keep the bar's.
     tintColor: hexOr(stripe.textColor, barTokens.tintColor),
     titleColor: hexOr(stripe.textColor, barTokens.titleColor),
     order,
@@ -608,7 +605,7 @@ export function resolveAppLogo(logo, darkSurfaceLogo, onDark) {
   return onDark && darkSurfaceLogo ? darkSurfaceLogo : logo;
 }
 
-const TAB_ALIGNMENTS = ["left", "right"];
+const TAB_ALIGNMENTS = ["left", "center", "right"];
 const TAB_ROW_WIDTHS = ["full", "content"];
 
 export function resolveTopBarTokens(theme) {

package/dist/theme-appearance.cjs

@@ -0,0 +1,195 @@
+// CommonJS mirror of theme-appearance.js, for the backend's theme coercion and
+// the compiler. The BODY is copied VERBATIM; theme-appearance-parity.test.js
+// pins identical bodies and identical behaviour.
+
+const { isHexColor, APPEARANCE_PREFERENCES } = require("./contract.cjs");
+
+// REQ-THEME-APPEARANCE (sc-12335) — the ONE implementation of an app's light and
+// dark palettes, and of which one is showing. Host surface, not author API.
+
+// Deeper than any stored theme nests, so a hand-edited blob stays bounded.
+const MAX_PALETTE_DEPTH = 8;
+
+// Assigned onto object literals, `__proto__` would set a prototype.
+const UNSAFE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+const APPEARANCE_THEME_KEYS = ["dark", "appearance"];
+
+/** The two palettes an app can render. */
+const APPEARANCE_MODES = Object.freeze(["light", "dark"]);
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+// A gradient is one colour value: its angle and type travel with its stops.
+function isGradient(value) {
+  return isPlainObject(value) && isHexColor(value.from) && isHexColor(value.to);
+}
+
+function isPaletteColour(value) {
+  return isHexColor(value) || isGradient(value);
+}
+
+function paletteAt(value, depth) {
+  const out = {};
+  if (!isPlainObject(value) || depth > MAX_PALETTE_DEPTH) return out;
+  for (const [key, child] of Object.entries(value)) {
+    if (UNSAFE_KEYS.has(key)) continue;
+    if (isPaletteColour(child)) {
+      out[key] = child;
+      continue;
+    }
+    const nested = paletteAt(child, depth + 1);
+    if (Object.keys(nested).length) out[key] = nested;
+  }
+  return out;
+}
+
+/**
+ * The colour-bearing part of a theme: every hex leaf and every gradient, at
+ * the path it sits on. Fonts, sizes, radii, spacing, enums, booleans and arrays
+ * drop out, and an object left with no colour is omitted, so the result is
+ * exactly the shape a `dark` palette may hold.
+ *
+ * @param {unknown} theme — a `theme_config`, or any part of one.
+ * @returns {Record<string, unknown>} never null.
+ */
+function themePaletteOf(theme) {
+  return paletteAt(theme, 0);
+}
+
+/**
+ * A stored or untrusted `theme_config.appearance`, or null when it is not one.
+ * `default` must be a known preference; `userCanSwitch` is true only when it
+ * is literally true.
+ *
+ * @returns {{ default: "light"|"dark"|"system", userCanSwitch: boolean } | null}
+ */
+function normaliseAppearance(raw) {
+  if (!isPlainObject(raw)) return null;
+  if (!APPEARANCE_PREFERENCES.includes(raw.default)) return null;
+  return { default: raw.default, userCanSwitch: raw.userCanSwitch === true };
+}
+
+/**
+ * What an app follows: a fixed mode, or the device's. A user's choice wins
+ * only where the app lets users switch; otherwise the app's default applies.
+ * No appearance setting is today's fixed light palette.
+ *
+ * @param {{ appearance?: unknown, userChoice?: unknown }} [input]
+ * @returns {"light"|"dark"|"system"}
+ */
+function resolveAppearancePreference({ appearance, userChoice } = {}) {
+  const settings = normaliseAppearance(appearance);
+  if (!settings) return "light";
+  return settings.userCanSwitch && APPEARANCE_PREFERENCES.includes(userChoice)
+    ? userChoice
+    : settings.default;
+}
+
+/**
+ * Which palette an app shows: its preference, where `system` follows the
+ * device and reads light when the device reports nothing.
+ *
+ * @param {{ appearance?: unknown, userChoice?: unknown, systemScheme?: unknown }} [input]
+ * @returns {"light"|"dark"}
+ */
+function resolveAppearanceMode({ appearance, userChoice, systemScheme } = {}) {
+  const preference = resolveAppearancePreference({ appearance, userChoice });
+  if (preference === "system") return systemScheme === "dark" ? "dark" : "light";
+  return preference;
+}
+
+function overlayPalette(base, palette) {
+  const out = { ...base };
+  for (const [key, value] of Object.entries(palette)) {
+    out[key] = isPaletteColour(value)
+      ? value
+      : overlayPalette(isPlainObject(base[key]) ? base[key] : {}, value);
+  }
+  return out;
+}
+
+/**
+ * The theme a host renders in `mode`, with no `dark` or `appearance` key left
+ * on it. In dark mode the `dark` palette is laid over the base key by key, and
+ * only its colours are read. Light mode, or a theme with no `dark`, is the base.
+ * A theme carrying neither key is returned as is, by reference.
+ *
+ * @param {unknown} themeConfig — a stored `theme_config`.
+ * @param {"light"|"dark"} mode — from `resolveAppearanceMode`.
+ */
+function resolveThemeForAppearance(themeConfig, mode) {
+  if (!isPlainObject(themeConfig)) return themeConfig;
+  if (!APPEARANCE_THEME_KEYS.some((key) => Object.hasOwn(themeConfig, key))) {
+    return themeConfig;
+  }
+  // `fromEntries`, not assignment, so a stored `__proto__` stays a plain key.
+  const base = Object.fromEntries(
+    Object.entries(themeConfig).filter(([key]) => !APPEARANCE_THEME_KEYS.includes(key)),
+  );
+  if (mode !== "dark") return base;
+  return overlayPalette(base, themePaletteOf(themeConfig.dark));
+}
+
+/**
+ * The top-level keys a `dark` palette may recolour. The backend's theme
+ * coercion derives the same set from its own vocabulary; a test pins the two.
+ */
+const DARK_PALETTE_KEYS = Object.freeze([
+  "primaryColor",
+  "secondaryColor",
+  "backgroundColor",
+  "backgroundGradient",
+  "loaderColor",
+  "login",
+  "sidebar",
+  "topBar",
+  "footer",
+  "siteHeader",
+  "typographyRoles",
+  "components",
+  "widgetStyles",
+]);
+
+function recolourablePalette(palette) {
+  return Object.fromEntries(
+    Object.entries(themePaletteOf(palette)).filter(([key]) => DARK_PALETTE_KEYS.includes(key)),
+  );
+}
+
+function withDarkPalette(base, palette) {
+  return Object.keys(palette).length ? { ...base, dark: palette } : base;
+}
+
+/**
+ * `theme`, painted in `mode`, stored the way an app with an appearance setting
+ * keeps it: the base is the light palette and `dark` the dark one. `twin` is the
+ * palette of the other mode. Painted light, the base stays and `twin` becomes
+ * `dark`. Painted dark, the theme's own colours become `dark` and `twin` is laid
+ * over the base. Everything that is not a colour stays as `theme` has it.
+ *
+ * @param {unknown} theme — a `theme_config`; any `dark` it carries is replaced.
+ * @param {"light"|"dark"} mode — the mode `theme`'s base is painted in.
+ * @param {unknown} twin — the other mode's palette (`themePaletteOf` shape).
+ */
+function themeInBothModes(theme, mode, twin) {
+  if (!isPlainObject(theme)) return theme;
+  const base = Object.fromEntries(Object.entries(theme).filter(([key]) => key !== "dark"));
+  const twinPalette = recolourablePalette(twin);
+  if (mode !== "dark") return withDarkPalette(base, twinPalette);
+  return withDarkPalette(overlayPalette(base, twinPalette), recolourablePalette(base));
+}
+
+module.exports = {
+  APPEARANCE_MODES,
+  APPEARANCE_PREFERENCES,
+  themePaletteOf,
+  normaliseAppearance,
+  resolveAppearancePreference,
+  resolveAppearanceMode,
+  resolveThemeForAppearance,
+  DARK_PALETTE_KEYS,
+  themeInBothModes,
+};

package/dist/theme-appearance.js

@@ -0,0 +1,182 @@
+import { isHexColor, APPEARANCE_PREFERENCES } from "./contract.js";
+
+// What an app opens on and a user may choose; one list, in the contract.
+export { APPEARANCE_PREFERENCES };
+
+// REQ-THEME-APPEARANCE (sc-12335) — the ONE implementation of an app's light and
+// dark palettes, and of which one is showing. Host surface, not author API.
+
+// Deeper than any stored theme nests, so a hand-edited blob stays bounded.
+const MAX_PALETTE_DEPTH = 8;
+
+// Assigned onto object literals, `__proto__` would set a prototype.
+const UNSAFE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+const APPEARANCE_THEME_KEYS = ["dark", "appearance"];
+
+/** The two palettes an app can render. */
+export const APPEARANCE_MODES = Object.freeze(["light", "dark"]);
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+// A gradient is one colour value: its angle and type travel with its stops.
+function isGradient(value) {
+  return isPlainObject(value) && isHexColor(value.from) && isHexColor(value.to);
+}
+
+function isPaletteColour(value) {
+  return isHexColor(value) || isGradient(value);
+}
+
+function paletteAt(value, depth) {
+  const out = {};
+  if (!isPlainObject(value) || depth > MAX_PALETTE_DEPTH) return out;
+  for (const [key, child] of Object.entries(value)) {
+    if (UNSAFE_KEYS.has(key)) continue;
+    if (isPaletteColour(child)) {
+      out[key] = child;
+      continue;
+    }
+    const nested = paletteAt(child, depth + 1);
+    if (Object.keys(nested).length) out[key] = nested;
+  }
+  return out;
+}
+
+/**
+ * The colour-bearing part of a theme: every hex leaf and every gradient, at
+ * the path it sits on. Fonts, sizes, radii, spacing, enums, booleans and arrays
+ * drop out, and an object left with no colour is omitted, so the result is
+ * exactly the shape a `dark` palette may hold.
+ *
+ * @param {unknown} theme — a `theme_config`, or any part of one.
+ * @returns {Record<string, unknown>} never null.
+ */
+export function themePaletteOf(theme) {
+  return paletteAt(theme, 0);
+}
+
+/**
+ * A stored or untrusted `theme_config.appearance`, or null when it is not one.
+ * `default` must be a known preference; `userCanSwitch` is true only when it
+ * is literally true.
+ *
+ * @returns {{ default: "light"|"dark"|"system", userCanSwitch: boolean } | null}
+ */
+export function normaliseAppearance(raw) {
+  if (!isPlainObject(raw)) return null;
+  if (!APPEARANCE_PREFERENCES.includes(raw.default)) return null;
+  return { default: raw.default, userCanSwitch: raw.userCanSwitch === true };
+}
+
+/**
+ * What an app follows: a fixed mode, or the device's. A user's choice wins
+ * only where the app lets users switch; otherwise the app's default applies.
+ * No appearance setting is today's fixed light palette.
+ *
+ * @param {{ appearance?: unknown, userChoice?: unknown }} [input]
+ * @returns {"light"|"dark"|"system"}
+ */
+export function resolveAppearancePreference({ appearance, userChoice } = {}) {
+  const settings = normaliseAppearance(appearance);
+  if (!settings) return "light";
+  return settings.userCanSwitch && APPEARANCE_PREFERENCES.includes(userChoice)
+    ? userChoice
+    : settings.default;
+}
+
+/**
+ * Which palette an app shows: its preference, where `system` follows the
+ * device and reads light when the device reports nothing.
+ *
+ * @param {{ appearance?: unknown, userChoice?: unknown, systemScheme?: unknown }} [input]
+ * @returns {"light"|"dark"}
+ */
+export function resolveAppearanceMode({ appearance, userChoice, systemScheme } = {}) {
+  const preference = resolveAppearancePreference({ appearance, userChoice });
+  if (preference === "system") return systemScheme === "dark" ? "dark" : "light";
+  return preference;
+}
+
+function overlayPalette(base, palette) {
+  const out = { ...base };
+  for (const [key, value] of Object.entries(palette)) {
+    out[key] = isPaletteColour(value)
+      ? value
+      : overlayPalette(isPlainObject(base[key]) ? base[key] : {}, value);
+  }
+  return out;
+}
+
+/**
+ * The theme a host renders in `mode`, with no `dark` or `appearance` key left
+ * on it. In dark mode the `dark` palette is laid over the base key by key, and
+ * only its colours are read. Light mode, or a theme with no `dark`, is the base.
+ * A theme carrying neither key is returned as is, by reference.
+ *
+ * @param {unknown} themeConfig — a stored `theme_config`.
+ * @param {"light"|"dark"} mode — from `resolveAppearanceMode`.
+ */
+export function resolveThemeForAppearance(themeConfig, mode) {
+  if (!isPlainObject(themeConfig)) return themeConfig;
+  if (!APPEARANCE_THEME_KEYS.some((key) => Object.hasOwn(themeConfig, key))) {
+    return themeConfig;
+  }
+  // `fromEntries`, not assignment, so a stored `__proto__` stays a plain key.
+  const base = Object.fromEntries(
+    Object.entries(themeConfig).filter(([key]) => !APPEARANCE_THEME_KEYS.includes(key)),
+  );
+  if (mode !== "dark") return base;
+  return overlayPalette(base, themePaletteOf(themeConfig.dark));
+}
+
+/**
+ * The top-level keys a `dark` palette may recolour. The backend's theme
+ * coercion derives the same set from its own vocabulary; a test pins the two.
+ */
+export const DARK_PALETTE_KEYS = Object.freeze([
+  "primaryColor",
+  "secondaryColor",
+  "backgroundColor",
+  "backgroundGradient",
+  "loaderColor",
+  "login",
+  "sidebar",
+  "topBar",
+  "footer",
+  "siteHeader",
+  "typographyRoles",
+  "components",
+  "widgetStyles",
+]);
+
+function recolourablePalette(palette) {
+  return Object.fromEntries(
+    Object.entries(themePaletteOf(palette)).filter(([key]) => DARK_PALETTE_KEYS.includes(key)),
+  );
+}
+
+function withDarkPalette(base, palette) {
+  return Object.keys(palette).length ? { ...base, dark: palette } : base;
+}
+
+/**
+ * `theme`, painted in `mode`, stored the way an app with an appearance setting
+ * keeps it: the base is the light palette and `dark` the dark one. `twin` is the
+ * palette of the other mode. Painted light, the base stays and `twin` becomes
+ * `dark`. Painted dark, the theme's own colours become `dark` and `twin` is laid
+ * over the base. Everything that is not a colour stays as `theme` has it.
+ *
+ * @param {unknown} theme — a `theme_config`; any `dark` it carries is replaced.
+ * @param {"light"|"dark"} mode — the mode `theme`'s base is painted in.
+ * @param {unknown} twin — the other mode's palette (`themePaletteOf` shape).
+ */
+export function themeInBothModes(theme, mode, twin) {
+  if (!isPlainObject(theme)) return theme;
+  const base = Object.fromEntries(Object.entries(theme).filter(([key]) => key !== "dark"));
+  const twinPalette = recolourablePalette(twin);
+  if (mode !== "dark") return withDarkPalette(base, twinPalette);
+  return withDarkPalette(overlayPalette(base, twinPalette), recolourablePalette(base));
+}

package/package.json

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

package/src/contract.js

@@ -885,6 +885,29 @@ const HOOKS = [
     requiredContextSlice: ["i18n.t", "i18n.locale"],
     scopes: null,
   },
+  {
+    name: "useAppearance",
+    signature: "useAppearance()",
+    description:
+      "The app's light or dark palette, and the app user's own choice of it. mode is the palette showing (\"light\" | \"dark\"); " +
+      "preference is what the app follows (\"light\" | \"dark\" | \"system\", where system follows the device). " +
+      "setPreference(preference) switches the WHOLE app live, with no reload, through the same switch as the account screen: " +
+      "a signed-in user's choice is saved to their account, a visitor who is not signed in keeps it on this device, and null " +
+      "returns to the app's default. It resolves once the choice is saved and rejects with an Error whose .code is UNSUPPORTED " +
+      "(canSwitch is false: the app does not let its users switch, or this is the Builder canvas) or INVALID_APPEARANCE — always " +
+      "catch it. canSwitch is false on such a host: render the choices disabled then, never a dead button. Colours need no " +
+      "hook: useTheme() already returns the palette showing. An app without an appearance setting reads light, canSwitch false. " +
+      "Identical on web (Player) and the Expo export.",
+    returnShape: {
+      mode: "\"light\" | \"dark\"",
+      preference: "\"light\" | \"dark\" | \"system\"",
+      canSwitch: "boolean",
+      setPreference:
+        "(preference: \"light\" | \"dark\" | \"system\" | null) => Promise<void>  // rejects with Error .code UNSUPPORTED | INVALID_APPEARANCE",
+    },
+    requiredContextSlice: [],
+    scopes: null,
+  },
   {
     name: "useTranslate",
     signature: "useTranslate()",
@@ -3994,6 +4017,16 @@ const WIDGET_CONTEXT_SHAPE = {
     required: false,
     fields: { setPhoto: "function", removePhoto: "function", anonymous: "object" },
   },
+  // REQ-THEME-APPEARANCE — backs useAppearance().
+  appearance: {
+    description:
+      "Optional. { mode: \"light\" | \"dark\", preference: \"light\" | \"dark\" | \"system\", setPreference?(preference) -> Promise<void> } " +
+      "backs useAppearance(). setPreference is the host's own appearance switch and is present only where the app user may " +
+      "switch. The whole slice is absent where the app has no appearance setting, and for a badge counter.",
+    required: false,
+    fields: { mode: "string", preference: "string" },
+    optionalFields: { setPreference: "function" },
+  },
   workspace: {
     description:
       "Workspace identity + resolved theme + charge currency ({ id, slug, theme, locale, currency }).",
@@ -6331,7 +6364,13 @@ const CONTRACT = deepFreeze({
   // 1.205.0: additive (sc-11840) — a string property's `default` shows as the
   //    field's editable text and clearing stores ""; `ui.placeholder` and
   //    `ui.clearRestoresDefault` are typed.
-  version: "1.205.0",
+  // 1.206.0: additive (sc-12335) — `useAppearance()` returns the palette
+  //    showing, the app's appearance preference, `canSwitch` and
+  //    `setPreference`, backed by the optional `appearance` host slice. Hosts
+  //    without it read light / false.
+  // 1.207.0: additive (sc-12198) — `resolveTopBarTokens().tabAlignment` is
+  //    "left" | "center" | "right" again; "center" centres the tabs.
+  version: "1.207.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -6740,8 +6779,14 @@ function scaleSpacing(value, scale) {
   return Math.round(value * clampSpacingScale(scale));
 }
 
+// REQ-THEME-APPEARANCE (sc-12335): what an app opens on, and what its users
+// may choose — a palette or the device's. One list for useAppearance() and the
+// host resolvers in theme-appearance.js.
+const APPEARANCE_PREFERENCES = Object.freeze(["light", "dark", "system"]);
+
 export {
   CONTRACT,
+  APPEARANCE_PREFERENCES,
   clampSpacingScale,
   scaleSpacing,
   normaliseActionTriggerTypes,