@colixsystems/widget-sdk 0.250.0 → 0.255.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,49 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.250.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.255.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.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)
+
+**A text property's default is real, editable text in the Studio.** The Properties panel used to show a `string` property's `default` as a grey placeholder, so authors took it for a hint and never edited the text the widget actually rendered. It now shows the default as the field's own value. It is still not written until the author edits, so an untouched field keeps following the manifest. Clearing a field that shows a default stores `""`. Your widget gets an empty string and should render it as empty, so read text props with `??`, not `||`. Two `ui` hints are now typed:
+
+- `ui.placeholder` — a grey hint shown while the field is empty.
+- `ui.clearRestoresDefault: true` — clearing brings the default back instead of storing `""`. Use it for a caption that must never render blank, such as a button label.
 
 ### What's new in 0.250.0 (contract 1.204.0)
 
@@ -2089,7 +2132,7 @@ const style = useWidgetStyle();
 <View style={[styles.card, style.cardBackground && { backgroundColor: style.cardBackground }]}>
 ```
 
-Keep `themeDefault` for a fallback that IS a theme token: it stays display-only (a greyed placeholder in the Style panel) so the field tracks the workspace theme. Use `default` for a literal constant your code genuinely falls back to — that value now reaches `props.style`, so it must match what your code applies.
+Keep `themeDefault` for a fallback that IS a theme token: it stays display-only (shown in the Style panel field, never written) so the field tracks the workspace theme. Use `default` for a literal constant your code genuinely falls back to — that value now reaches `props.style`, so it must match what your code applies.
 
 ### What's new in 0.117.0 (contract 1.89.0)
 
@@ -2609,7 +2652,7 @@ Docs-only correction of documented host behaviour: no export, type, runtime, or
 
 **`themeDefault` publishes the value a style field falls back to (sc-4164).** An unset `styleSchema` field rendered as an empty box, so an author adjusting `Title size` could not see the size they were changing. `WidgetPropertyDef` now documents the key the Studio has read since sc-1807:
 
-- **`themeDefault: "<dotted path into the resolved widget theme>"`** — e.g. `"typography.sizes.lg"`, `"radii.md"`, `"colors.onSurface"`. The Studio renders it as greyed placeholder text, resolved against the **workspace's** theme, so the hint stays truthful after a rebrand. Prefer it over a literal `default` whenever your fallback is a theme token — which it usually is, since you style from `useTheme()`.
+- **`themeDefault: "<dotted path into the resolved widget theme>"`** — e.g. `"typography.sizes.lg"`, `"radii.md"`, `"colors.onSurface"`. The Studio shows it in the field, resolved against the **workspace's** theme, so the hint stays truthful after a rebrand. Prefer it over a literal `default` whenever your fallback is a theme token — which it usually is, since you style from `useTheme()`.
 - **A literal `default`** still works and is the right choice for a hard-coded constant your code carries (`default: 1.4` for a line height you wrote yourself).
 - **Both are DISPLAY-ONLY.** Neither is ever written into `props.style`, so a style field keeps its only-when-set contract and continues to inherit the theme. Declare the value your code actually applies — a baseline that disagrees with the render is worse than none.
 - **Optional.** A field whose fallback has no fixed value (a `background` that inherits whatever the container paints) declares neither and renders blank.

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 }).",
@@ -6332,7 +6365,14 @@ const CONTRACT = deepFreeze({
   //    `field-in-bordered-row`, `field-trailing-press-unnamed`.
   // 1.204.0: additive (sc-12244) — `<DataTable showHeader>` (default true);
   //    false drops the wide layout's header row and its sticky index.
-  version: "1.204.0",
+  // 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.
+  // 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.
+  version: "1.206.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -6741,8 +6781,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 }).",
@@ -6328,7 +6361,14 @@ const CONTRACT = deepFreeze({
   //    `field-in-bordered-row`, `field-trailing-press-unnamed`.
   // 1.204.0: additive (sc-12244) — `<DataTable showHeader>` (default true);
   //    false drops the wide layout's header row and its sticky index.
-  version: "1.204.0",
+  // 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.
+  // 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.
+  version: "1.206.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -6737,8 +6777,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

@@ -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

@@ -87,8 +87,8 @@ export interface WidgetPropertyDef {
   // sc-1807 / sc-4164 — the value the widget falls back to when this field is
   // unset, as a dotted path into the resolved widget theme
   // (`"typography.sizes.lg"`, `"radii.md"`, `"colors.onSurface"`). The Studio
-  // shows it as greyed placeholder text so the author can see what they are
-  // adjusting from; it resolves against the WORKSPACE's theme, so the hint stays
+  // shows it in the field (a greyed hint for colours) so the author can see
+  // what they are adjusting from; it resolves against the WORKSPACE's theme, so the hint stays
   // truthful after a rebrand. DISPLAY-ONLY — never written into props.style, so
   // a styleSchema field keeps its only-when-set contract. Prefer this over a
   // literal `default` whenever the fallback is a theme token.
@@ -106,6 +106,11 @@ export interface WidgetPropertyDef {
     // a static `default`). Today: `"tabId"` → seed a unique stable id
     // for newly added Tab Layout tabs.
     defaultFactory?: "tabId";
+    // string: a grey hint shown while the field is empty.
+    placeholder?: string;
+    // string: clearing restores `default` instead of storing "" — for a
+    // caption that must never render blank (a button label).
+    clearRestoresDefault?: boolean;
   };
   validation?: { min?: number; max?: number; pattern?: string };
 }
@@ -840,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;
@@ -2013,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/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.250.0",
+  "version": "0.255.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 }).",
@@ -6328,7 +6361,14 @@ const CONTRACT = deepFreeze({
   //    `field-in-bordered-row`, `field-trailing-press-unnamed`.
   // 1.204.0: additive (sc-12244) — `<DataTable showHeader>` (default true);
   //    false drops the wide layout's header row and its sticky index.
-  version: "1.204.0",
+  // 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.
+  // 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.
+  version: "1.206.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -6737,8 +6777,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,