@colixsystems/widget-sdk 0.66.0 → 0.67.1

package/README.md

@@ -17,7 +17,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 
 | Group | Hook (signature) | Returns | Reads / scope |
 | ----- | ---------------- | ------- | ------------- |
-| **CORE** | `useTheme()` | `{ colors, spacing, radii, typography }` | `ctx.workspace.theme` — no scope |
+| **CORE** | `useTheme()` | `{ colors, spacing, radii, typography, components }` | `ctx.workspace.theme` — no scope. `components` is HOST-OWNED (the theme's per-component style tokens); the host has already folded it into your `props.style`, so read `useWidgetStyle()` and ignore this slice. |
 | **CORE** | `useWidgetStyle()` | `{ [styleField]: value }` | `ctx.props.style` — no scope. The author-set per-widget style values declared in `manifest.styleSchema`; apply each onto whatever element you choose. |
 | **CORE** | `useUser()` | `{ id, email, displayName, roles, groupIds }` | `ctx.user` (host-built context, **camelCase** — not a wire payload; `id` null when anonymous) — no scope |
 | **CORE** | `useNavigation()` | `{ goTo, goBack, push, replace, back, currentRoute }` | `ctx.navigation` — no scope (external URLs use the `Linking` primitive) |
@@ -53,7 +53,17 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.66.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.67.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.67.0
+
+**The theme can restyle ONE component type — buttons, cards or text — without moving the global palette (sc-1497).** A workspace theme may now carry `themeConfig.components` (`{ button, card, text }`), and the host resolves each scope onto the `styleSchema` fields the target widgets already read. **Nothing changes for a widget author:** you keep reading `props.style` / `useWidgetStyle()`, and an author's per-instance value still wins over a theme token — the theme is the app-wide default underneath it.
+
+- **`useTheme()` gains a `components` slice.** It is HOST-OWNED plumbing, not an author API: by the time your component renders, the host has already folded the matching tokens into `props.style`. Do not read `theme.components` and do not re-apply it — you would double-apply the theme and defeat the author's own styling.
+- **New host-only exports on `@colixsystems/widget-sdk/host`:** `normaliseThemeComponents(raw)` and `applyThemeComponentStyle(manifestId, theme, props)`. These are the platform-host surface (the web Player / Studio canvas and the exported Expo app), never the author API — one implementation, so the two hosts cannot diverge.
+- **`CONTRACT.themeComponents` / `CONTRACT.themeComponentShadows`** publish the vocabulary: each scope's tokens, their value types and ranges, and the widget → style-field bindings. `themeTokens.components` defaults to `{}`.
+
+`CONTRACT.version` → `1.45.0`. Additive; no existing export changed signature, and an unthemed app renders identically.
 
 ### What's new in 0.66.0
 

package/dist/contract.cjs

@@ -31,6 +31,111 @@ const DEFAULT_THEME_TOKENS = Object.freeze({
       'ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
     sizes: Object.freeze({ xs: 12, sm: 14, md: 16, lg: 20, xl: 24, xxl: 32 }),
   }),
+  // REQ-THEME-15: the tenant's per-component style tokens, folded in by the
+  // host so ONE channel carries them to the Player and the export. Empty by
+  // default — an unconfigured theme resolves to no component overrides.
+  components: Object.freeze({}),
+});
+
+// REQ-THEME-15 (sc-1497) — per-component style tokens. The global palette is a
+// single lever: remapping `primaryColor` to recolour "the buttons" recolours
+// every element that shares it. A theme may therefore also carry
+// `themeConfig.components` — `{ <scope>: { <token>: <value> } }` — that restyles
+// ONE component type app-wide.
+//
+// This is NOT a second styling vocabulary. Each scope's tokens bind to the
+// REQ-THEME-13 per-instance `styleSchema` fields the target widgets ALREADY
+// read, so a theme-level token needs no widget change: the host resolves the
+// scope's tokens into the widget's `props.style` DEFAULTS and an author's
+// per-instance value still wins.
+//
+// `tokens` declares each token's value type once per scope (what the Mason
+// `set_theme` coercion and the host boundary validate against); `targets` binds
+// token → the style field each widget reads, so one scope can drive differently
+// named fields on different widgets (a Form's submit button is `submitBackground`,
+// a Button's is `background`). The keys of `targets` ARE the widgets in scope.
+//
+// Single source for four consumers — the build runner's set_theme coercion, the
+// shared host resolver, the planner prompt, and the SDK docs — so the vocabulary
+// cannot drift between what Mason may emit and what a host actually applies.
+const THEME_COMPONENT_SHADOWS = Object.freeze(["none", "sm", "md", "lg"]);
+
+// The card-surface field names shared by every widget that paints its own card
+// (frontend/src/components/widgets/_shared/cardStyle.js CARD_STYLE_SCHEMA).
+const CARD_SURFACE_FIELDS = Object.freeze({
+  background: "cardBackground",
+  borderColor: "cardBorderColor",
+  radius: "cardRadius",
+  padding: "cardPadding",
+  shadow: "shadow",
+});
+
+// A form widget's submit button — the `button` scope reaches it through the
+// form's own submit* fields, so "make the buttons coral" does not skip forms.
+const FORM_SUBMIT_FIELDS = Object.freeze({
+  background: "submitBackground",
+  textColor: "submitTextColor",
+});
+
+const THEME_COMPONENTS = Object.freeze({
+  button: Object.freeze({
+    label: "Buttons",
+    tokens: Object.freeze({
+      background: Object.freeze({ type: "color", uiDefault: "colors.primary" }),
+      textColor: Object.freeze({ type: "color", uiDefault: "colors.onPrimary" }),
+      borderColor: Object.freeze({ type: "color", uiDefault: "colors.border" }),
+      radius: Object.freeze({ type: "size", min: 0, max: 48, uiDefault: "radii.sm" }),
+      fontSize: Object.freeze({ type: "size", min: 8, max: 96, uiDefault: "typography.sizes.sm" }),
+      shadow: Object.freeze({ type: "shadow" }),
+    }),
+    targets: Object.freeze({
+      "appstudio.button": Object.freeze({
+        background: "background",
+        textColor: "textColor",
+        borderColor: "borderColor",
+        radius: "radius",
+        fontSize: "fontSize",
+        shadow: "shadow",
+      }),
+      "appstudio.form-input": FORM_SUBMIT_FIELDS,
+      "appstudio.form-builder": FORM_SUBMIT_FIELDS,
+    }),
+  }),
+  card: Object.freeze({
+    label: "Cards",
+    tokens: Object.freeze({
+      background: Object.freeze({ type: "color", uiDefault: "colors.surface" }),
+      borderColor: Object.freeze({ type: "color", uiDefault: "colors.border" }),
+      radius: Object.freeze({ type: "size", min: 0, max: 48, uiDefault: "radii.md" }),
+      padding: Object.freeze({ type: "size", min: 0, max: 64, uiDefault: "spacing.md" }),
+      shadow: Object.freeze({ type: "shadow" }),
+    }),
+    targets: Object.freeze({
+      "appstudio.user": CARD_SURFACE_FIELDS,
+      "appstudio.data-list": CARD_SURFACE_FIELDS,
+      "appstudio.gallery": CARD_SURFACE_FIELDS,
+      "appstudio.files": CARD_SURFACE_FIELDS,
+      "appstudio.newsfeed": CARD_SURFACE_FIELDS,
+      "appstudio.notifications": CARD_SURFACE_FIELDS,
+      "appstudio.form-input": CARD_SURFACE_FIELDS,
+      "appstudio.form-builder": CARD_SURFACE_FIELDS,
+    }),
+  }),
+  text: Object.freeze({
+    label: "Text",
+    tokens: Object.freeze({
+      color: Object.freeze({ type: "color", uiDefault: "colors.onSurface" }),
+      fontSize: Object.freeze({ type: "size", min: 8, max: 96, uiDefault: "typography.sizes.md" }),
+    }),
+    targets: Object.freeze({
+      "appstudio.text": Object.freeze({ color: "color", fontSize: "fontSize" }),
+      "appstudio.label": Object.freeze({ color: "color", fontSize: "fontSize" }),
+      "appstudio.data-value": Object.freeze({
+        color: "color",
+        fontSize: "fontSize",
+      }),
+    }),
+  }),
 });
 
 const HOOKS = [
@@ -43,6 +148,10 @@ const HOOKS = [
       spacing: "{ xs, sm, md, lg, xl }",
       radii: "{ sm, md, lg, pill }",
       typography: "{ fontFamily, sizes: { xs, sm, md, lg, xl, xxl } }",
+      components:
+        "{ [scope]: { [token]: value } } — REQ-THEME-15 per-component theme " +
+        "tokens. HOST-OWNED: the host already folds them into your " +
+        "props.style, so read props.style / useWidgetStyle() instead.",
     },
     requiredContextSlice: ["workspace.theme"],
     scopes: null,
@@ -1960,7 +2069,25 @@ const CONTRACT = deepFreeze({
   //    matching, so a comment quoting the bad path is not a finding, and a
   //    legitimate third-party relative path can opt out with an
   //    `appstudio-lint-ignore no-host-api-url` comment. Additive.
-  version: "1.44.0",
+  //
+  // 1.45.0: additive (REQ-THEME-15, sc-1497) — per-component style tokens. A
+  //    workspace theme may carry `themeConfig.components` (`{ button, card, text }`)
+  //    that restyles ONE component type app-wide instead of remapping the shared
+  //    global palette. New `themeComponents` (the scope -> token -> target-field
+  //    vocabulary, with each token's value type + range) and
+  //    `themeComponentShadows` (the closed shadow enum) publish that vocabulary as
+  //    the SINGLE source read by the Mason build runner's set_theme coercion, the
+  //    shared host resolver, and the planner prompt. `themeTokens` gains a
+  //    `components` namespace (default `{}`) because the resolved theme is the
+  //    channel that carries the tokens to both hosts, so `useTheme()` returnShape
+  //    gains `components` — HOST-OWNED: the host folds the matching tokens into a
+  //    widget's `props.style` before render, so an author still reads
+  //    `props.style` / `useWidgetStyle()` and must NOT re-apply this slice. The
+  //    resolvers themselves ship on the host-only entry
+  //    (`@colixsystems/widget-sdk/host`), never the author surface. Additive: no
+  //    export changed signature and a theme with no `components` key resolves to
+  //    an empty override, rendering identically to before.
+  version: "1.45.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -1971,6 +2098,8 @@ const CONTRACT = deepFreeze({
   actionScriptGlobals: ACTION_SCRIPT_GLOBALS,
   actionScriptMaxBytes: ACTION_SCRIPT_MAX_BYTES,
   themeTokens: DEFAULT_THEME_TOKENS,
+  themeComponents: THEME_COMPONENTS,
+  themeComponentShadows: THEME_COMPONENT_SHADOWS,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,
   bannedApis: BANNED_APIS,

package/dist/contract.js

@@ -31,6 +31,111 @@ const DEFAULT_THEME_TOKENS = Object.freeze({
       'ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
     sizes: Object.freeze({ xs: 12, sm: 14, md: 16, lg: 20, xl: 24, xxl: 32 }),
   }),
+  // REQ-THEME-15: the tenant's per-component style tokens, folded in by the
+  // host so ONE channel carries them to the Player and the export. Empty by
+  // default — an unconfigured theme resolves to no component overrides.
+  components: Object.freeze({}),
+});
+
+// REQ-THEME-15 (sc-1497) — per-component style tokens. The global palette is a
+// single lever: remapping `primaryColor` to recolour "the buttons" recolours
+// every element that shares it. A theme may therefore also carry
+// `themeConfig.components` — `{ <scope>: { <token>: <value> } }` — that restyles
+// ONE component type app-wide.
+//
+// This is NOT a second styling vocabulary. Each scope's tokens bind to the
+// REQ-THEME-13 per-instance `styleSchema` fields the target widgets ALREADY
+// read, so a theme-level token needs no widget change: the host resolves the
+// scope's tokens into the widget's `props.style` DEFAULTS and an author's
+// per-instance value still wins.
+//
+// `tokens` declares each token's value type once per scope (what the Mason
+// `set_theme` coercion and the host boundary validate against); `targets` binds
+// token → the style field each widget reads, so one scope can drive differently
+// named fields on different widgets (a Form's submit button is `submitBackground`,
+// a Button's is `background`). The keys of `targets` ARE the widgets in scope.
+//
+// Single source for four consumers — the build runner's set_theme coercion, the
+// shared host resolver, the planner prompt, and the SDK docs — so the vocabulary
+// cannot drift between what Mason may emit and what a host actually applies.
+const THEME_COMPONENT_SHADOWS = Object.freeze(["none", "sm", "md", "lg"]);
+
+// The card-surface field names shared by every widget that paints its own card
+// (frontend/src/components/widgets/_shared/cardStyle.js CARD_STYLE_SCHEMA).
+const CARD_SURFACE_FIELDS = Object.freeze({
+  background: "cardBackground",
+  borderColor: "cardBorderColor",
+  radius: "cardRadius",
+  padding: "cardPadding",
+  shadow: "shadow",
+});
+
+// A form widget's submit button — the `button` scope reaches it through the
+// form's own submit* fields, so "make the buttons coral" does not skip forms.
+const FORM_SUBMIT_FIELDS = Object.freeze({
+  background: "submitBackground",
+  textColor: "submitTextColor",
+});
+
+const THEME_COMPONENTS = Object.freeze({
+  button: Object.freeze({
+    label: "Buttons",
+    tokens: Object.freeze({
+      background: Object.freeze({ type: "color", uiDefault: "colors.primary" }),
+      textColor: Object.freeze({ type: "color", uiDefault: "colors.onPrimary" }),
+      borderColor: Object.freeze({ type: "color", uiDefault: "colors.border" }),
+      radius: Object.freeze({ type: "size", min: 0, max: 48, uiDefault: "radii.sm" }),
+      fontSize: Object.freeze({ type: "size", min: 8, max: 96, uiDefault: "typography.sizes.sm" }),
+      shadow: Object.freeze({ type: "shadow" }),
+    }),
+    targets: Object.freeze({
+      "appstudio.button": Object.freeze({
+        background: "background",
+        textColor: "textColor",
+        borderColor: "borderColor",
+        radius: "radius",
+        fontSize: "fontSize",
+        shadow: "shadow",
+      }),
+      "appstudio.form-input": FORM_SUBMIT_FIELDS,
+      "appstudio.form-builder": FORM_SUBMIT_FIELDS,
+    }),
+  }),
+  card: Object.freeze({
+    label: "Cards",
+    tokens: Object.freeze({
+      background: Object.freeze({ type: "color", uiDefault: "colors.surface" }),
+      borderColor: Object.freeze({ type: "color", uiDefault: "colors.border" }),
+      radius: Object.freeze({ type: "size", min: 0, max: 48, uiDefault: "radii.md" }),
+      padding: Object.freeze({ type: "size", min: 0, max: 64, uiDefault: "spacing.md" }),
+      shadow: Object.freeze({ type: "shadow" }),
+    }),
+    targets: Object.freeze({
+      "appstudio.user": CARD_SURFACE_FIELDS,
+      "appstudio.data-list": CARD_SURFACE_FIELDS,
+      "appstudio.gallery": CARD_SURFACE_FIELDS,
+      "appstudio.files": CARD_SURFACE_FIELDS,
+      "appstudio.newsfeed": CARD_SURFACE_FIELDS,
+      "appstudio.notifications": CARD_SURFACE_FIELDS,
+      "appstudio.form-input": CARD_SURFACE_FIELDS,
+      "appstudio.form-builder": CARD_SURFACE_FIELDS,
+    }),
+  }),
+  text: Object.freeze({
+    label: "Text",
+    tokens: Object.freeze({
+      color: Object.freeze({ type: "color", uiDefault: "colors.onSurface" }),
+      fontSize: Object.freeze({ type: "size", min: 8, max: 96, uiDefault: "typography.sizes.md" }),
+    }),
+    targets: Object.freeze({
+      "appstudio.text": Object.freeze({ color: "color", fontSize: "fontSize" }),
+      "appstudio.label": Object.freeze({ color: "color", fontSize: "fontSize" }),
+      "appstudio.data-value": Object.freeze({
+        color: "color",
+        fontSize: "fontSize",
+      }),
+    }),
+  }),
 });
 
 const HOOKS = [
@@ -43,6 +148,10 @@ const HOOKS = [
       spacing: "{ xs, sm, md, lg, xl }",
       radii: "{ sm, md, lg, pill }",
       typography: "{ fontFamily, sizes: { xs, sm, md, lg, xl, xxl } }",
+      components:
+        "{ [scope]: { [token]: value } } — REQ-THEME-15 per-component theme " +
+        "tokens. HOST-OWNED: the host already folds them into your " +
+        "props.style, so read props.style / useWidgetStyle() instead.",
     },
     requiredContextSlice: ["workspace.theme"],
     scopes: null,
@@ -1960,7 +2069,25 @@ const CONTRACT = deepFreeze({
   //    matching, so a comment quoting the bad path is not a finding, and a
   //    legitimate third-party relative path can opt out with an
   //    `appstudio-lint-ignore no-host-api-url` comment. Additive.
-  version: "1.44.0",
+  //
+  // 1.45.0: additive (REQ-THEME-15, sc-1497) — per-component style tokens. A
+  //    workspace theme may carry `themeConfig.components` (`{ button, card, text }`)
+  //    that restyles ONE component type app-wide instead of remapping the shared
+  //    global palette. New `themeComponents` (the scope -> token -> target-field
+  //    vocabulary, with each token's value type + range) and
+  //    `themeComponentShadows` (the closed shadow enum) publish that vocabulary as
+  //    the SINGLE source read by the Mason build runner's set_theme coercion, the
+  //    shared host resolver, and the planner prompt. `themeTokens` gains a
+  //    `components` namespace (default `{}`) because the resolved theme is the
+  //    channel that carries the tokens to both hosts, so `useTheme()` returnShape
+  //    gains `components` — HOST-OWNED: the host folds the matching tokens into a
+  //    widget's `props.style` before render, so an author still reads
+  //    `props.style` / `useWidgetStyle()` and must NOT re-apply this slice. The
+  //    resolvers themselves ship on the host-only entry
+  //    (`@colixsystems/widget-sdk/host`), never the author surface. Additive: no
+  //    export changed signature and a theme with no `components` key resolves to
+  //    an empty override, rendering identically to before.
+  version: "1.45.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -1971,6 +2098,8 @@ const CONTRACT = deepFreeze({
   actionScriptGlobals: ACTION_SCRIPT_GLOBALS,
   actionScriptMaxBytes: ACTION_SCRIPT_MAX_BYTES,
   themeTokens: DEFAULT_THEME_TOKENS,
+  themeComponents: THEME_COMPONENTS,
+  themeComponentShadows: THEME_COMPONENT_SHADOWS,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,
   bannedApis: BANNED_APIS,

package/dist/hooks.js

@@ -593,6 +593,12 @@ function toDatastoreError(err) {
   });
 }
 
+// sc-1579 — consecutive renders with a different serialized query before
+// `useDatastoreQuery` calls the loop out. High enough that no real interaction
+// reaches it (a settled fetch resets the count), low enough to fire instantly
+// on a genuine loop.
+const VOLATILE_QUERY_RENDER_LIMIT = 10;
+
 /**
  * Stateful datastore query hook. Returns { data, loading, error, refetch }.
  *
@@ -682,6 +688,35 @@ export function useDatastoreQuery(table, query) {
       return null;
     }
   })();
+
+  // sc-1579 — a query argument built from a volatile value (`Date.now()`,
+  // `new Date()`, `Math.random()`) serialises differently every render, so the
+  // effect below re-fetches forever and the widget never settles. A genuine
+  // edit (a typed filter) settles within one render because the re-render the
+  // fetch triggers reuses the same argument; a volatile one never does. That
+  // gap is the signal — no timers, no heuristics. Warned once per instance,
+  // and in production too: the Studio canvas and the widget agent's render
+  // smoke check both run production builds, which is where this must surface.
+  const volatileKeyRef = useRef({ key: queryKey, changes: 0, warned: false });
+  const keyWatch = volatileKeyRef.current;
+  if (keyWatch.key === queryKey) {
+    keyWatch.changes = 0;
+  } else {
+    keyWatch.key = queryKey;
+    keyWatch.changes += 1;
+    if (keyWatch.changes >= VOLATILE_QUERY_RENDER_LIMIT && !keyWatch.warned) {
+      keyWatch.warned = true;
+      // eslint-disable-next-line no-console
+      console.warn(
+        `useDatastoreQuery(${JSON.stringify(table)}): the query argument changed on ` +
+          `${keyWatch.changes} consecutive renders, so this widget is re-fetching in a ` +
+          "loop. Something in the query is regenerated every render — usually a date " +
+          "or random value. Compute it once outside render (or with useMemo) and pass " +
+          "the stable value in.",
+      );
+    }
+  }
+
   useEffect(() => {
     doFetch();
     // eslint-disable-next-line react-hooks/exhaustive-deps

package/dist/host.d.ts

@@ -11,3 +11,26 @@ export function resolveProps<T = Record<string, unknown>>(
   schema: WidgetPropertySchema,
   props: unknown,
 ): T;
+
+export type ThemeComponentStyle = Record<string, string | number>;
+export type ThemeComponents = Record<string, ThemeComponentStyle>;
+
+/**
+ * REQ-THEME-15 host helper: validates a raw `themeConfig.components` blob down
+ * to `CONTRACT.themeComponents` — unknown scopes/tokens and malformed values are
+ * dropped. Called when a host folds the tenant theme into the resolved widget
+ * theme, so `theme.components` is always clean.
+ */
+export function normaliseThemeComponents(raw: unknown): ThemeComponents;
+
+/**
+ * REQ-THEME-15 host render-boundary helper: folds the theme's per-component
+ * tokens into a widget's props as `style` DEFAULTS, with the author's
+ * per-instance values winning. Returns the same `props` reference when the theme
+ * sets nothing for this widget. Applied by the platform hosts, never by authors.
+ */
+export function applyThemeComponentStyle<T = Record<string, unknown>>(
+  manifestId: string,
+  theme: { components?: ThemeComponents } | null | undefined,
+  props: T,
+): T;

package/dist/host.js

@@ -10,3 +10,13 @@
 // not appear in the author import surface or the Developer guide.
 
 export { resolveProps } from "./property-schema.js";
+
+// REQ-THEME-15: the per-component theme-token resolvers. `normaliseThemeComponents`
+// validates a raw `themeConfig.components` blob when the host folds it into the
+// resolved widget theme; `applyThemeComponentStyle` turns that slice into a
+// widget's `style` defaults at the render boundary. One implementation for both
+// hosts, so the Player and the Expo export cannot diverge.
+export {
+  normaliseThemeComponents,
+  applyThemeComponentStyle,
+} from "./theme-components.js";

package/dist/theme-components.cjs

@@ -0,0 +1,134 @@
+// CommonJS mirror of theme-components.js — the Mason build runner (CJS)
+// validates a `set_theme` components blob against the SAME vocabulary the hosts
+// apply, so what a planner may persist and what a widget renders cannot diverge.
+//
+// The BODY below is copied VERBATIM from theme-components.js; only the module
+// syntax differs. theme-components-parity.test.js pins both facts — identical
+// bodies AND identical behaviour over a shared case table — so drift fails CI.
+
+// REQ-THEME-15 (sc-1497) — the host side of per-component style tokens.
+//
+// Host-integration surface, re-exported from `host.js`: consumed ONLY by the
+// platform hosts that render widgets (the web Player / Studio Canvas via
+// buildHostWidgetContext.js, and the exported Expo app's generated WidgetHost),
+// never by a widget author. A widget keeps reading `props.style` /
+// `useWidgetStyle()` and never learns a theme token was involved.
+//
+// Living here — one implementation both hosts import — is what makes the tokens
+// render identically in the Player and the export (widget-parity skill). The
+// alternative, a copy per host, is the drift this file exists to prevent.
+//
+// `CONTRACT.themeComponents` is the single source of the vocabulary: which
+// scopes exist, each token's value type, and the `styleSchema` field each target
+// widget reads. The Mason build runner validates `set_theme` against the SAME
+// literal, so what a planner may emit and what a host applies cannot diverge.
+
+const { CONTRACT } = require("./contract.cjs");
+
+// 3-, 6- and 8-digit hex, matching what the build runner persists — the host
+// must never drop a colour the runner already accepted.
+const HEX_COLOR = /^#(?:[0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function coerceToken(def, value) {
+  if (def.type === "color") {
+    if (typeof value !== "string") return undefined;
+    const trimmed = value.trim();
+    return HEX_COLOR.test(trimmed) ? trimmed : undefined;
+  }
+  if (def.type === "size") {
+    const n = typeof value === "number" ? value : Number(value);
+    if (!Number.isFinite(n)) return undefined;
+    return Math.min(def.max, Math.max(def.min, Math.round(n)));
+  }
+  if (def.type === "shadow") {
+    return CONTRACT.themeComponentShadows.includes(value) ? value : undefined;
+  }
+  return undefined;
+}
+
+/**
+ * Validate a raw `themeConfig.components` blob down to the declared vocabulary:
+ * unknown scopes, unknown tokens and malformed values are dropped, and an
+ * emptied scope is omitted rather than kept as `{}`.
+ *
+ * `theme_config` is a JSON bag any workspace admin can PUT verbatim, so this is
+ * the guard that keeps a hand-edited theme from handing a widget a style value
+ * its renderer can't use. Returns a frozen-shaped plain object, never null, so
+ * callers can fold the result in unconditionally.
+ *
+ * @param {unknown} raw — `themeConfig.components`.
+ * @returns {Record<string, Record<string, string|number>>}
+ */
+function normaliseThemeComponents(raw) {
+  if (!isPlainObject(raw)) return {};
+  const out = {};
+  for (const [scope, definition] of Object.entries(CONTRACT.themeComponents)) {
+    const requested = raw[scope];
+    if (!isPlainObject(requested)) continue;
+    const tokens = {};
+    for (const [token, def] of Object.entries(definition.tokens)) {
+      if (requested[token] === undefined) continue;
+      const coerced = coerceToken(def, requested[token]);
+      if (coerced !== undefined) tokens[token] = coerced;
+    }
+    if (Object.keys(tokens).length > 0) out[scope] = tokens;
+  }
+  return out;
+}
+
+/**
+ * The per-component style fields that apply to one widget, keyed by the
+ * `styleSchema` field name the widget actually reads. A widget may sit in more
+ * than one scope (a Form is a `card` whose submit button is a `button`), so
+ * every matching scope contributes.
+ *
+ * Re-validates the slice rather than trusting it: this is the last boundary
+ * before a value becomes a widget's style, and a host that folded the theme in
+ * without normalising must not be able to hand a widget malformed input.
+ *
+ * @returns {Record<string, string|number>|null} null when nothing applies.
+ */
+function componentStyleFor(manifestId, components) {
+  if (typeof manifestId !== "string") return null;
+  const validated = normaliseThemeComponents(components);
+  const out = {};
+  for (const [scope, definition] of Object.entries(CONTRACT.themeComponents)) {
+    const tokens = validated[scope];
+    const fields = definition.targets[manifestId];
+    if (!tokens || !fields) continue;
+    for (const [token, field] of Object.entries(fields)) {
+      if (tokens[token] !== undefined) out[field] = tokens[token];
+    }
+  }
+  return Object.keys(out).length > 0 ? out : null;
+}
+
+/**
+ * Fold the theme's per-component tokens into a widget's props as `style`
+ * DEFAULTS. The author's per-instance REQ-THEME-13 values are spread last and
+ * therefore always win — the theme token is the app-wide baseline, the
+ * Properties Panel is the final word.
+ *
+ * Returns the SAME `props` reference when the theme sets nothing for this
+ * widget, so an unthemed app takes no extra render work and behaves exactly as
+ * it did before REQ-THEME-15.
+ *
+ * @param {string} manifestId — the widget's canonical manifest id.
+ * @param {object} theme — the resolved widget theme (`workspace.theme`); its
+ *   `components` slice is read.
+ * @param {object} props — the widget's resolved props (post-`resolveProps`).
+ * @returns {object} props, with `style` folded when the theme applies.
+ */
+function applyThemeComponentStyle(manifestId, theme, props) {
+  const themed = componentStyleFor(manifestId, theme && theme.components);
+  if (!themed) return props;
+  const base = isPlainObject(props) ? props : {};
+  const authored = isPlainObject(base.style) ? base.style : null;
+  return { ...base, style: { ...themed, ...authored } };
+}
+
+module.exports = { normaliseThemeComponents, applyThemeComponentStyle };

package/dist/theme-components.js

@@ -0,0 +1,124 @@
+// REQ-THEME-15 (sc-1497) — the host side of per-component style tokens.
+//
+// Host-integration surface, re-exported from `host.js`: consumed ONLY by the
+// platform hosts that render widgets (the web Player / Studio Canvas via
+// buildHostWidgetContext.js, and the exported Expo app's generated WidgetHost),
+// never by a widget author. A widget keeps reading `props.style` /
+// `useWidgetStyle()` and never learns a theme token was involved.
+//
+// Living here — one implementation both hosts import — is what makes the tokens
+// render identically in the Player and the export (widget-parity skill). The
+// alternative, a copy per host, is the drift this file exists to prevent.
+//
+// `CONTRACT.themeComponents` is the single source of the vocabulary: which
+// scopes exist, each token's value type, and the `styleSchema` field each target
+// widget reads. The Mason build runner validates `set_theme` against the SAME
+// literal, so what a planner may emit and what a host applies cannot diverge.
+
+import { CONTRACT } from "./contract.js";
+
+// 3-, 6- and 8-digit hex, matching what the build runner persists — the host
+// must never drop a colour the runner already accepted.
+const HEX_COLOR = /^#(?:[0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function coerceToken(def, value) {
+  if (def.type === "color") {
+    if (typeof value !== "string") return undefined;
+    const trimmed = value.trim();
+    return HEX_COLOR.test(trimmed) ? trimmed : undefined;
+  }
+  if (def.type === "size") {
+    const n = typeof value === "number" ? value : Number(value);
+    if (!Number.isFinite(n)) return undefined;
+    return Math.min(def.max, Math.max(def.min, Math.round(n)));
+  }
+  if (def.type === "shadow") {
+    return CONTRACT.themeComponentShadows.includes(value) ? value : undefined;
+  }
+  return undefined;
+}
+
+/**
+ * Validate a raw `themeConfig.components` blob down to the declared vocabulary:
+ * unknown scopes, unknown tokens and malformed values are dropped, and an
+ * emptied scope is omitted rather than kept as `{}`.
+ *
+ * `theme_config` is a JSON bag any workspace admin can PUT verbatim, so this is
+ * the guard that keeps a hand-edited theme from handing a widget a style value
+ * its renderer can't use. Returns a frozen-shaped plain object, never null, so
+ * callers can fold the result in unconditionally.
+ *
+ * @param {unknown} raw — `themeConfig.components`.
+ * @returns {Record<string, Record<string, string|number>>}
+ */
+export function normaliseThemeComponents(raw) {
+  if (!isPlainObject(raw)) return {};
+  const out = {};
+  for (const [scope, definition] of Object.entries(CONTRACT.themeComponents)) {
+    const requested = raw[scope];
+    if (!isPlainObject(requested)) continue;
+    const tokens = {};
+    for (const [token, def] of Object.entries(definition.tokens)) {
+      if (requested[token] === undefined) continue;
+      const coerced = coerceToken(def, requested[token]);
+      if (coerced !== undefined) tokens[token] = coerced;
+    }
+    if (Object.keys(tokens).length > 0) out[scope] = tokens;
+  }
+  return out;
+}
+
+/**
+ * The per-component style fields that apply to one widget, keyed by the
+ * `styleSchema` field name the widget actually reads. A widget may sit in more
+ * than one scope (a Form is a `card` whose submit button is a `button`), so
+ * every matching scope contributes.
+ *
+ * Re-validates the slice rather than trusting it: this is the last boundary
+ * before a value becomes a widget's style, and a host that folded the theme in
+ * without normalising must not be able to hand a widget malformed input.
+ *
+ * @returns {Record<string, string|number>|null} null when nothing applies.
+ */
+function componentStyleFor(manifestId, components) {
+  if (typeof manifestId !== "string") return null;
+  const validated = normaliseThemeComponents(components);
+  const out = {};
+  for (const [scope, definition] of Object.entries(CONTRACT.themeComponents)) {
+    const tokens = validated[scope];
+    const fields = definition.targets[manifestId];
+    if (!tokens || !fields) continue;
+    for (const [token, field] of Object.entries(fields)) {
+      if (tokens[token] !== undefined) out[field] = tokens[token];
+    }
+  }
+  return Object.keys(out).length > 0 ? out : null;
+}
+
+/**
+ * Fold the theme's per-component tokens into a widget's props as `style`
+ * DEFAULTS. The author's per-instance REQ-THEME-13 values are spread last and
+ * therefore always win — the theme token is the app-wide baseline, the
+ * Properties Panel is the final word.
+ *
+ * Returns the SAME `props` reference when the theme sets nothing for this
+ * widget, so an unthemed app takes no extra render work and behaves exactly as
+ * it did before REQ-THEME-15.
+ *
+ * @param {string} manifestId — the widget's canonical manifest id.
+ * @param {object} theme — the resolved widget theme (`workspace.theme`); its
+ *   `components` slice is read.
+ * @param {object} props — the widget's resolved props (post-`resolveProps`).
+ * @returns {object} props, with `style` folded when the theme applies.
+ */
+export function applyThemeComponentStyle(manifestId, theme, props) {
+  const themed = componentStyleFor(manifestId, theme && theme.components);
+  if (!themed) return props;
+  const base = isPlainObject(props) ? props : {};
+  const authored = isPlainObject(base.style) ? base.style : null;
+  return { ...base, style: { ...themed, ...authored } };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.66.0",
+  "version": "0.67.1",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -48,7 +48,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-subscription.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js"
+    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/theme-components-parity.test.js"
   },
   "engines": {
     "node": ">=18"