@colixsystems/widget-sdk 0.67.0 → 0.68.0

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, 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** | `useTheme()` | `{ colors, elevation, spacing, radii, typography, components }` | `ctx.workspace.theme` — no scope. `elevation` is the shared depth scale (`none / sm / md / lg / xl`) you spread into a style; `colors` includes the accent's quiet tiers (`primarySoft` / `onPrimarySoft` / `primaryStrong`). `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) |
@@ -514,17 +514,19 @@ A widget that works but looks unfinished is only half done. `useTheme()` is the
 
 **Decide before you build:** the widget's shape (card, list, form, control), its hierarchy (the one thing the eye lands on first), its single accent moment, and its empty/loading/error look — then compose. Specific decisions make a distinctive widget; leaving them to default makes a generic one.
 
-- **Pull spacing and corners from tokens.** Use `theme.spacing` (`xs / sm / md / lg / xl`) for a consistent padding and gap rhythm, and `theme.radii` (`sm / md / lg / pill`) for corners. Don't hardcode raw pixel values.
-- **Build a hierarchy.** A clear title (large, bold, `colors.onSurface`), body text, and muted captions in `colors.onSurfaceMuted` — three weights, not one flat size. Reserve `colors.primary` (with `colors.onPrimary` for text on it) for the single most important action or metric.
+- **Pull spacing and corners from tokens.** Use `theme.spacing` (`xs / sm / md / lg / xl`) for a consistent padding and gap rhythm, and `theme.radii` (`sm / md / lg / pill`) for corners — `radii.lg` for cards and hero surfaces, `radii.md` for controls nested inside one. Don't hardcode raw pixel values.
+- **Build a hierarchy.** A clear title (large, bold, `colors.onSurface`), body text, and muted captions in `colors.onSurfaceMuted` — three weights, not one flat size. Reserve full-strength `colors.primary` (with `colors.onPrimary` for text on it) for the single most important action or metric.
 - **Set the theme font on every `Text`.** React Native `Text` does not inherit `fontFamily` from a parent, so a text element that omits it falls back to the system font and ignores the workspace's configured font. Put `theme.typography.fontFamily` on every text style (a shared `StyleSheet` built from `theme` keeps it in one place) and size text with `theme.typography.sizes`.
-- **Contain and elevate.** Wrap a logical unit in a surface: `colors.surface` + padding + `radii.md` + a `colors.border` hairline or a subtle shadow. Use the status roles (`danger / success / warning / info`) for state.
+- **Contain and elevate.** Wrap a logical unit in a surface: `colors.surface` + padding + `radii.lg` + `...theme.elevation.sm`. Give it the elevation **or** a `colors.border` hairline, not both — and prefer the elevation, because a hairline-only card reads as a wireframe. `theme.elevation` is a token table you spread into a style (`...theme.elevation.md`), covering `none / sm / md / lg / xl`; never hand-write `shadowOpacity` / `shadowRadius` / `boxShadow`. Use the status roles (`danger / success / warning / info`) for state.
+- **Tint the supporting cast.** `colors.primarySoft` is a tint of the workspace accent over the surface and `colors.onPrimarySoft` is guaranteed readable on it (WCAG AA, on light and dark themes alike). Use the pair for chips, secondary buttons, progress tracks, icon badges and selected rows. One saturated accent moment surrounded by several pale echoes of the same hue is what reads as designed — a row of grey-outlined buttons reads as a form. Never hand-mix a tint with `rgba(...)` or a translucent overlay.
+- **Spend one gradient.** `<Gradient colors={[theme.colors.primary, theme.colors.primaryStrong]} angle={160} style={…}>` is a `View` that paints a gradient behind its children, so it replaces the `View` you'd otherwise give a flat `backgroundColor`. `angle` is CSS degrees (0 = to top, 90 = to right, default 180); text on it uses `colors.onPrimary`. Exactly **one** per widget — on the focal element — and never behind body text. Both hosts render it identically (web paints CSS, native uses `expo-linear-gradient`), so there is no per-platform branching to write; don't import `expo-linear-gradient` yourself and don't write a `backgroundImage` string.
 - **Compose forms — pair fields into rows, don't stack one per row.** Put short, related fields side by side (first + last name, city + postal code, expiry + CVC): a row of `{ flexDirection: 'row', flexWrap: 'wrap', gap: theme.spacing.md }` with each field cell `{ flexGrow: 1, flexBasis: 160 }` splits the width on a wide card and wraps to stacked on a narrow phone — the native-safe way to go multi-column (widgets have no breakpoint hook, so never hard-code fixed columns). Keep wide fields (email, address, notes) full-width, cap it at two–three per row, group a long form into labelled sections, and label every input above it (not placeholder-only).
 - **Respond to touch.** Give every `Pressable` a pressed state via the function-style `style={({ pressed }) => [base, pressed && { opacity: 0.7 }]}`.
 - **Use icons for clarity.** Pair a `lucide-react-native` icon with its label at a consistent size, coloured from the theme. The label never repeats the icon as a character — with a `Plus` icon the button says "Add item", never "+ Add item" (that renders a doubled plus).
 - **Use imagery deliberately.** Render pictures with the `Image` primitive (`source` takes a URL or `{ uri }`); resolve workspace assets via `useAsset()`. Give every image a sized, `radii`-clipped container so it never renders as a raw rectangle, and never hardcode a credentialed image URL — expose an `image`-type property instead.
 - **Design the empty, loading, and error states.** A blank box on a fresh install reads as broken — show a short helper line when a list is empty, a calm loading line, and a single human sentence in `colors.danger` on error.
 
-**Honest ceilings:** the styling surface is React Native style objects, not full CSS. There are no per-widget gradients, no custom CSS keyframe animations or `transition` strings, and shadows are limited to the five elevation presets (`none / sm / md / lg / xl`). Aim for clean, confident, professional polish within those bounds.
+**Honest ceilings:** the styling surface is React Native style objects, not full CSS. Gradients come from the `<Gradient>` primitive (not a CSS `linear-gradient` string), depth comes from `theme.elevation` (not arbitrary `box-shadow` stacks), and there are no custom CSS keyframe animations or `transition` strings, no `filter` / `backdrop-filter` / `clip-path` / `mask` / blend modes, and no opacity-faked tints (that's what `primarySoft` is for). Aim for clean, confident, professional polish within those bounds — lifted surfaces, generous corners, one accent moment.
 
 ## Managing app users from a widget
 

package/dist/contract.cjs

@@ -8,10 +8,56 @@
 // Keep edits in lockstep between `contract.cjs` and `contract.js`. The
 // SDK build script copies both into `dist/`.
 
+// REQ-AI-AGENT-DESIGN (sc-3696): the ONE cross-platform elevation vocabulary.
+// `shadow*` applies on iOS + react-native-web, `elevation` drives Android.
+// Consumed by `_shared/cardStyle.js` SHADOW_PRESETS (web + baked built-ins),
+// the compiler's generated layout `elevationStyles`, and widgets reading
+// `useTheme().elevation` — so a widget shadow and a container shadow match.
+const ELEVATION = Object.freeze({
+  none: Object.freeze({}),
+  sm: Object.freeze({
+    shadowColor: "#000",
+    shadowOffset: Object.freeze({ width: 0, height: 1 }),
+    shadowOpacity: 0.08,
+    shadowRadius: 2,
+    elevation: 2,
+  }),
+  md: Object.freeze({
+    shadowColor: "#000",
+    shadowOffset: Object.freeze({ width: 0, height: 2 }),
+    shadowOpacity: 0.12,
+    shadowRadius: 4,
+    elevation: 4,
+  }),
+  lg: Object.freeze({
+    shadowColor: "#000",
+    shadowOffset: Object.freeze({ width: 0, height: 4 }),
+    shadowOpacity: 0.16,
+    shadowRadius: 8,
+    elevation: 8,
+  }),
+  xl: Object.freeze({
+    shadowColor: "#000",
+    shadowOffset: Object.freeze({ width: 0, height: 8 }),
+    shadowOpacity: 0.2,
+    shadowRadius: 12,
+    elevation: 12,
+  }),
+});
+
 const DEFAULT_THEME_TOKENS = Object.freeze({
   colors: Object.freeze({
     primary: "#3b82f6",
     onPrimary: "#ffffff",
+    // REQ-AI-AGENT-DESIGN (sc-3696): the accent's quiet tiers. `primarySoft` is
+    // a tint of the accent over the surface (chips, secondary buttons, progress
+    // tracks); `onPrimarySoft` is contrast-guaranteed against it;
+    // `primaryStrong` is the accent's deeper end for a gradient's far stop.
+    // All three are re-derived per tenant by `deriveAccentTints` — these
+    // literals are the derivation applied to the default palette.
+    primarySoft: "#ebf3fe",
+    onPrimarySoft: "#3168c2",
+    primaryStrong: "#326bc8",
     secondary: "#10b981",
     onSecondary: "#ffffff",
     surface: "#ffffff",
@@ -24,6 +70,7 @@ const DEFAULT_THEME_TOKENS = Object.freeze({
     warning: "#d97706",
     info: "#0284c7",
   }),
+  elevation: ELEVATION,
   spacing: Object.freeze({ xs: 4, sm: 8, md: 16, lg: 24, xl: 32 }),
   radii: Object.freeze({ sm: 4, md: 8, lg: 16, pill: 9999 }),
   typography: Object.freeze({
@@ -376,7 +423,13 @@ const HOOKS = [
       "`owner_id`, `folder_id`, plus the binary `file`), and POSTs through " +
       "ctx.filestore.files.upload. `upload(file, { folderId? })` resolves " +
       "to the created file row or throws the wire error; a 404 means the " +
-      "destination folder denied a write (REQ-FSH canWrite gate).",
+      "destination folder denied a write (REQ-FSH canWrite gate). " +
+      "ALWAYS pass spaceType explicitly — omitting it falls back to " +
+      "'project', which is unreadable by a logged-out visitor. Choose it by " +
+      "who must SEE the file: 'public' for content the app displays to " +
+      "anyone browsing (product, catalogue, gallery, cover images), " +
+      "'project' for content restricted to signed-in workspace users, " +
+      "'personal' for a file private to the uploading app user.",
     returnShape: {
       upload: "(file, { folderId? }) => Promise<FilestoreFile>",
       uploading: "boolean",
@@ -958,6 +1011,16 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  // REQ-AI-AGENT-DESIGN (sc-3696) — the gradient surface. Widgets previously had
+  // no gradient at all, which is why generated widgets read flatter than the
+  // competition; this is the ONE cross-platform way to paint one.
+  {
+    name: "Gradient",
+    description:
+      "Linear-gradient surface. `<Gradient colors={[theme.colors.primary, theme.colors.primaryStrong]} angle={160} style={{ borderRadius: theme.radii.lg, padding: theme.spacing.md }}>…</Gradient>`. A View that paints a gradient behind its children — accepts every View style prop, so it replaces the `View` you would otherwise give a flat `backgroundColor`. `colors` takes two or more theme colour roles (never raw hex); `angle` is CSS degrees (0 = to top, 90 = to right, default 180 = to bottom). Web paints a CSS `linear-gradient`; native delegates to expo-linear-gradient with the same angle projection, so the two hosts match. Use it for at most ONE element per widget (the hero action or a stat header) — text on it uses `colors.onPrimary`.",
+    rnComponent: "expo-linear-gradient",
+    docsUrl: "https://docs.expo.dev/versions/latest/sdk/linear-gradient/",
+  },
 ];
 
 const CATEGORIES = [
@@ -1573,7 +1636,7 @@ const VETTED_IMPORTS = [
     platforms: ["web", "native"],
     category: "drawing",
     description:
-      "Linear-gradient fill (<LinearGradient colors={[...]} />). The cross-platform gradient — works on both platforms (react-native-linear-gradient is native-only; prefer this).",
+      "Linear-gradient fill (<LinearGradient colors={[...]} />). Prefer the SDK's <Gradient> primitive: it wraps this on native and CSS on web, so it resolves in an AI-agent widget (which is transpiled, not bundled) where a bare import of this package does not. Reach for the package directly only from a BUNDLED widget needing a gradient shape this primitive can't express.",
   },
   {
     specifier: "lottie-react-native",
@@ -2122,10 +2185,136 @@ function requiredContextKeys() {
   return [...keys];
 }
 
+// ---------------------------------------------------------------------------
+// Theme derivation (REQ-THEME-DARK + REQ-AI-AGENT-DESIGN)
+//
+// The colour maths every host applies on top of a tenant's picked palette.
+// It lives HERE, in the dual-format contract, because BOTH hosts need it and
+// both can reach it: the web Player through `frontend/src/services/widgetTheme.js`
+// and the exported Expo app through the compiler's generated widget-theme
+// module (which already imports `CONTRACT` from this package). Previously each
+// host carried its own hand-mirrored copy of `mixHex` / `readableTextColor` —
+// one source removes that drift (CLAUDE.md §3).
+// ---------------------------------------------------------------------------
+
+const HEX_RE = /^#[0-9a-f]{3}([0-9a-f]{3})?$/i;
+
+function isHexColor(value) {
+  return typeof value === "string" && HEX_RE.test(value);
+}
+
+function hexChannels(hex) {
+  let h = hex.slice(1);
+  if (h.length === 3) {
+    h = h
+      .split("")
+      .map((c) => c + c)
+      .join("");
+  }
+  return [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16));
+}
+
+/** Relative luminance (WCAG 2.1) of a hex colour. */
+function relativeLuminance(hex) {
+  const [r, g, b] = hexChannels(hex).map((v) => v / 255);
+  const lin = (c) => (c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+  return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+}
+
+/** WCAG contrast ratio between two hex colours. Always >= 1. */
+function contrastRatio(a, b) {
+  const la = relativeLuminance(a);
+  const lb = relativeLuminance(b);
+  return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+
+/** Linear sRGB mix of two hex colours (`t` 0 = a, 1 = b). Bad input → `a`. */
+function mixHex(a, b, t) {
+  if (!isHexColor(a) || !isHexColor(b)) return a;
+  const pa = hexChannels(a);
+  const pb = hexChannels(b);
+  const channel = (i) => Math.round(pa[i] + (pb[i] - pa[i]) * t);
+  const hex = (n) =>
+    Math.max(0, Math.min(255, n)).toString(16).padStart(2, "0");
+  return `#${hex(channel(0))}${hex(channel(1))}${hex(channel(2))}`;
+}
+
+/**
+ * Pick a readable text colour (`dark` or `light`) for a solid background.
+ * A light background gets the dark option and vice versa, so `onPrimary` /
+ * `onSecondary` follow whatever accent the tenant picked.
+ */
+function readableTextColor(hex, dark, light) {
+  if (!isHexColor(hex)) return light;
+  return relativeLuminance(hex) > 0.55 ? dark : light;
+}
+
+// A tint at 10% accent reads as "quietly accented" on both a white and a dark
+// surface without competing with the full-strength accent moment.
+const ACCENT_TINT_WEIGHT = 0.9;
+// How far `primaryStrong` travels toward the text colour. Deepens the accent on
+// a light theme and lightens it on a dark one, which is the right direction for
+// a gradient's far stop in both.
+const ACCENT_STRONG_WEIGHT = 0.22;
+const ACCENT_TEXT_MIN_CONTRAST = 4.5;
+
+/**
+ * REQ-AI-AGENT-DESIGN (sc-3696): derive the accent's quiet tiers from the
+ * resolved palette. Returns `{ primarySoft, onPrimarySoft, primaryStrong }`.
+ *
+ * `onPrimarySoft` is not a fixed mix: the accent is stepped toward the surface's
+ * text colour until it clears WCAG AA (4.5:1) against the tint, so a chip label
+ * is legible for EVERY tenant accent rather than only for accents that happen
+ * to be dark enough. Returns `null` when the inputs aren't usable hex, letting
+ * the caller keep the default tokens.
+ */
+function deriveAccentTints(primary, surface, onSurface) {
+  if (!isHexColor(primary) || !isHexColor(surface) || !isHexColor(onSurface)) {
+    return null;
+  }
+  const primarySoft = mixHex(primary, surface, ACCENT_TINT_WEIGHT);
+  let onPrimarySoft = primary;
+  for (let t = 0; t <= 0.9; t += 0.05) {
+    onPrimarySoft = mixHex(primary, onSurface, t);
+    if (contrastRatio(onPrimarySoft, primarySoft) >= ACCENT_TEXT_MIN_CONTRAST) {
+      break;
+    }
+  }
+  return {
+    primarySoft,
+    onPrimarySoft,
+    primaryStrong: mixHex(primary, onSurface, ACCENT_STRONG_WEIGHT),
+  };
+}
+
+/**
+ * Map a CSS-style gradient angle (0 = to top, 90 = to right) to the
+ * `{ start, end }` unit vectors `expo-linear-gradient` expects (origin at
+ * top-left, y down). Single source for the SDK's `<Gradient>` primitive and
+ * the compiler's app-background backdrop, so a widget gradient and the app
+ * gradient read the same angle identically (CLAUDE.md §3).
+ */
+function gradientAngleToVector(angle) {
+  const deg = Number.isFinite(angle) ? angle : 180;
+  const rad = ((deg - 90) * Math.PI) / 180;
+  const dx = Math.cos(rad);
+  const dy = Math.sin(rad);
+  return {
+    start: { x: 0.5 - dx / 2, y: 0.5 - dy / 2 },
+    end: { x: 0.5 + dx / 2, y: 0.5 + dy / 2 },
+  };
+}
+
 module.exports = {
   CONTRACT,
   isHookAllowed,
   requiredContextKeys,
+  isHexColor,
+  mixHex,
+  contrastRatio,
+  readableTextColor,
+  deriveAccentTints,
+  gradientAngleToVector,
   widgetTranslationPrefix,
   widgetTranslationKey,
   sharedTranslationPrefix,

package/dist/contract.js

@@ -8,10 +8,56 @@
 // Keep edits in lockstep between `contract.cjs` and `contract.js`. The
 // SDK build script copies both into `dist/`.
 
+// REQ-AI-AGENT-DESIGN (sc-3696): the ONE cross-platform elevation vocabulary.
+// `shadow*` applies on iOS + react-native-web, `elevation` drives Android.
+// Consumed by `_shared/cardStyle.js` SHADOW_PRESETS (web + baked built-ins),
+// the compiler's generated layout `elevationStyles`, and widgets reading
+// `useTheme().elevation` — so a widget shadow and a container shadow match.
+const ELEVATION = Object.freeze({
+  none: Object.freeze({}),
+  sm: Object.freeze({
+    shadowColor: "#000",
+    shadowOffset: Object.freeze({ width: 0, height: 1 }),
+    shadowOpacity: 0.08,
+    shadowRadius: 2,
+    elevation: 2,
+  }),
+  md: Object.freeze({
+    shadowColor: "#000",
+    shadowOffset: Object.freeze({ width: 0, height: 2 }),
+    shadowOpacity: 0.12,
+    shadowRadius: 4,
+    elevation: 4,
+  }),
+  lg: Object.freeze({
+    shadowColor: "#000",
+    shadowOffset: Object.freeze({ width: 0, height: 4 }),
+    shadowOpacity: 0.16,
+    shadowRadius: 8,
+    elevation: 8,
+  }),
+  xl: Object.freeze({
+    shadowColor: "#000",
+    shadowOffset: Object.freeze({ width: 0, height: 8 }),
+    shadowOpacity: 0.2,
+    shadowRadius: 12,
+    elevation: 12,
+  }),
+});
+
 const DEFAULT_THEME_TOKENS = Object.freeze({
   colors: Object.freeze({
     primary: "#3b82f6",
     onPrimary: "#ffffff",
+    // REQ-AI-AGENT-DESIGN (sc-3696): the accent's quiet tiers. `primarySoft` is
+    // a tint of the accent over the surface (chips, secondary buttons, progress
+    // tracks); `onPrimarySoft` is contrast-guaranteed against it;
+    // `primaryStrong` is the accent's deeper end for a gradient's far stop.
+    // All three are re-derived per tenant by `deriveAccentTints` — these
+    // literals are the derivation applied to the default palette.
+    primarySoft: "#ebf3fe",
+    onPrimarySoft: "#3168c2",
+    primaryStrong: "#326bc8",
     secondary: "#10b981",
     onSecondary: "#ffffff",
     surface: "#ffffff",
@@ -24,6 +70,7 @@ const DEFAULT_THEME_TOKENS = Object.freeze({
     warning: "#d97706",
     info: "#0284c7",
   }),
+  elevation: ELEVATION,
   spacing: Object.freeze({ xs: 4, sm: 8, md: 16, lg: 24, xl: 32 }),
   radii: Object.freeze({ sm: 4, md: 8, lg: 16, pill: 9999 }),
   typography: Object.freeze({
@@ -376,7 +423,13 @@ const HOOKS = [
       "`owner_id`, `folder_id`, plus the binary `file`), and POSTs through " +
       "ctx.filestore.files.upload. `upload(file, { folderId? })` resolves " +
       "to the created file row or throws the wire error; a 404 means the " +
-      "destination folder denied a write (REQ-FSH canWrite gate).",
+      "destination folder denied a write (REQ-FSH canWrite gate). " +
+      "ALWAYS pass spaceType explicitly — omitting it falls back to " +
+      "'project', which is unreadable by a logged-out visitor. Choose it by " +
+      "who must SEE the file: 'public' for content the app displays to " +
+      "anyone browsing (product, catalogue, gallery, cover images), " +
+      "'project' for content restricted to signed-in workspace users, " +
+      "'personal' for a file private to the uploading app user.",
     returnShape: {
       upload: "(file, { folderId? }) => Promise<FilestoreFile>",
       uploading: "boolean",
@@ -958,6 +1011,16 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  // REQ-AI-AGENT-DESIGN (sc-3696) — the gradient surface. Widgets previously had
+  // no gradient at all, which is why generated widgets read flatter than the
+  // competition; this is the ONE cross-platform way to paint one.
+  {
+    name: "Gradient",
+    description:
+      "Linear-gradient surface. `<Gradient colors={[theme.colors.primary, theme.colors.primaryStrong]} angle={160} style={{ borderRadius: theme.radii.lg, padding: theme.spacing.md }}>…</Gradient>`. A View that paints a gradient behind its children — accepts every View style prop, so it replaces the `View` you would otherwise give a flat `backgroundColor`. `colors` takes two or more theme colour roles (never raw hex); `angle` is CSS degrees (0 = to top, 90 = to right, default 180 = to bottom). Web paints a CSS `linear-gradient`; native delegates to expo-linear-gradient with the same angle projection, so the two hosts match. Use it for at most ONE element per widget (the hero action or a stat header) — text on it uses `colors.onPrimary`.",
+    rnComponent: "expo-linear-gradient",
+    docsUrl: "https://docs.expo.dev/versions/latest/sdk/linear-gradient/",
+  },
 ];
 
 const CATEGORIES = [
@@ -1573,7 +1636,7 @@ const VETTED_IMPORTS = [
     platforms: ["web", "native"],
     category: "drawing",
     description:
-      "Linear-gradient fill (<LinearGradient colors={[...]} />). The cross-platform gradient — works on both platforms (react-native-linear-gradient is native-only; prefer this).",
+      "Linear-gradient fill (<LinearGradient colors={[...]} />). Prefer the SDK's <Gradient> primitive: it wraps this on native and CSS on web, so it resolves in an AI-agent widget (which is transpiled, not bundled) where a bare import of this package does not. Reach for the package directly only from a BUNDLED widget needing a gradient shape this primitive can't express.",
   },
   {
     specifier: "lottie-react-native",
@@ -2122,10 +2185,136 @@ function requiredContextKeys() {
   return [...keys];
 }
 
+// ---------------------------------------------------------------------------
+// Theme derivation (REQ-THEME-DARK + REQ-AI-AGENT-DESIGN)
+//
+// The colour maths every host applies on top of a tenant's picked palette.
+// It lives HERE, in the dual-format contract, because BOTH hosts need it and
+// both can reach it: the web Player through `frontend/src/services/widgetTheme.js`
+// and the exported Expo app through the compiler's generated widget-theme
+// module (which already imports `CONTRACT` from this package). Previously each
+// host carried its own hand-mirrored copy of `mixHex` / `readableTextColor` —
+// one source removes that drift (CLAUDE.md §3).
+// ---------------------------------------------------------------------------
+
+const HEX_RE = /^#[0-9a-f]{3}([0-9a-f]{3})?$/i;
+
+function isHexColor(value) {
+  return typeof value === "string" && HEX_RE.test(value);
+}
+
+function hexChannels(hex) {
+  let h = hex.slice(1);
+  if (h.length === 3) {
+    h = h
+      .split("")
+      .map((c) => c + c)
+      .join("");
+  }
+  return [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16));
+}
+
+/** Relative luminance (WCAG 2.1) of a hex colour. */
+function relativeLuminance(hex) {
+  const [r, g, b] = hexChannels(hex).map((v) => v / 255);
+  const lin = (c) => (c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+  return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+}
+
+/** WCAG contrast ratio between two hex colours. Always >= 1. */
+function contrastRatio(a, b) {
+  const la = relativeLuminance(a);
+  const lb = relativeLuminance(b);
+  return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+
+/** Linear sRGB mix of two hex colours (`t` 0 = a, 1 = b). Bad input → `a`. */
+function mixHex(a, b, t) {
+  if (!isHexColor(a) || !isHexColor(b)) return a;
+  const pa = hexChannels(a);
+  const pb = hexChannels(b);
+  const channel = (i) => Math.round(pa[i] + (pb[i] - pa[i]) * t);
+  const hex = (n) =>
+    Math.max(0, Math.min(255, n)).toString(16).padStart(2, "0");
+  return `#${hex(channel(0))}${hex(channel(1))}${hex(channel(2))}`;
+}
+
+/**
+ * Pick a readable text colour (`dark` or `light`) for a solid background.
+ * A light background gets the dark option and vice versa, so `onPrimary` /
+ * `onSecondary` follow whatever accent the tenant picked.
+ */
+function readableTextColor(hex, dark, light) {
+  if (!isHexColor(hex)) return light;
+  return relativeLuminance(hex) > 0.55 ? dark : light;
+}
+
+// A tint at 10% accent reads as "quietly accented" on both a white and a dark
+// surface without competing with the full-strength accent moment.
+const ACCENT_TINT_WEIGHT = 0.9;
+// How far `primaryStrong` travels toward the text colour. Deepens the accent on
+// a light theme and lightens it on a dark one, which is the right direction for
+// a gradient's far stop in both.
+const ACCENT_STRONG_WEIGHT = 0.22;
+const ACCENT_TEXT_MIN_CONTRAST = 4.5;
+
+/**
+ * REQ-AI-AGENT-DESIGN (sc-3696): derive the accent's quiet tiers from the
+ * resolved palette. Returns `{ primarySoft, onPrimarySoft, primaryStrong }`.
+ *
+ * `onPrimarySoft` is not a fixed mix: the accent is stepped toward the surface's
+ * text colour until it clears WCAG AA (4.5:1) against the tint, so a chip label
+ * is legible for EVERY tenant accent rather than only for accents that happen
+ * to be dark enough. Returns `null` when the inputs aren't usable hex, letting
+ * the caller keep the default tokens.
+ */
+function deriveAccentTints(primary, surface, onSurface) {
+  if (!isHexColor(primary) || !isHexColor(surface) || !isHexColor(onSurface)) {
+    return null;
+  }
+  const primarySoft = mixHex(primary, surface, ACCENT_TINT_WEIGHT);
+  let onPrimarySoft = primary;
+  for (let t = 0; t <= 0.9; t += 0.05) {
+    onPrimarySoft = mixHex(primary, onSurface, t);
+    if (contrastRatio(onPrimarySoft, primarySoft) >= ACCENT_TEXT_MIN_CONTRAST) {
+      break;
+    }
+  }
+  return {
+    primarySoft,
+    onPrimarySoft,
+    primaryStrong: mixHex(primary, onSurface, ACCENT_STRONG_WEIGHT),
+  };
+}
+
+/**
+ * Map a CSS-style gradient angle (0 = to top, 90 = to right) to the
+ * `{ start, end }` unit vectors `expo-linear-gradient` expects (origin at
+ * top-left, y down). Single source for the SDK's `<Gradient>` primitive and
+ * the compiler's app-background backdrop, so a widget gradient and the app
+ * gradient read the same angle identically (CLAUDE.md §3).
+ */
+function gradientAngleToVector(angle) {
+  const deg = Number.isFinite(angle) ? angle : 180;
+  const rad = ((deg - 90) * Math.PI) / 180;
+  const dx = Math.cos(rad);
+  const dy = Math.sin(rad);
+  return {
+    start: { x: 0.5 - dx / 2, y: 0.5 - dy / 2 },
+    end: { x: 0.5 + dx / 2, y: 0.5 + dy / 2 },
+  };
+}
+
 export {
   CONTRACT,
   isHookAllowed,
   requiredContextKeys,
+  isHexColor,
+  mixHex,
+  contrastRatio,
+  readableTextColor,
+  deriveAccentTints,
+  gradientAngleToVector,
   widgetTranslationPrefix,
   widgetTranslationKey,
   sharedTranslationPrefix,

package/dist/gradient-stops.js

@@ -0,0 +1,21 @@
+// REQ-AI-AGENT-DESIGN (sc-3696) — the `<Gradient>` colour-stop normaliser,
+// shared by the web (./gradient.js) and native (./gradient.native.js) builds.
+//
+// Its own module because it must be platform-neutral: importing it from
+// ./gradient.js would drag `react-native-web` into the native bundle.
+
+/**
+ * Normalise the author's `colors` prop to at least two colour stops, or `null`
+ * when there is nothing paintable.
+ *
+ * A single stop is a legitimate authoring mistake (a "gradient" of one colour);
+ * doubling it renders a flat fill rather than throwing, which keeps a
+ * half-finished widget visible on the canvas instead of blanking it.
+ */
+export function gradientStops(colors) {
+  const list = (Array.isArray(colors) ? colors : []).filter(
+    (c) => typeof c === "string" && c.trim(),
+  );
+  if (list.length === 0) return null;
+  return list.length === 1 ? [list[0], list[0]] : list;
+}

package/dist/gradient.js

@@ -0,0 +1,35 @@
+// REQ-AI-AGENT-DESIGN (sc-3696) — `<Gradient>` (web).
+//
+// Widgets had no gradient at all: `expo-linear-gradient` is a vetted import, but
+// an AI-agent widget is only TRANSPILED (never bundled), so a bare
+// `expo-linear-gradient` import has nothing to resolve against on the web
+// Player. Exposing the gradient as an SDK primitive fixes that for every widget
+// kind at once — the SDK is already host-shimmed, so authors import from the one
+// entry point they always import from.
+//
+// Web paints a CSS `linear-gradient`. react-native-web (0.21) passes
+// `backgroundImage` straight through to the DOM — it validates only against a
+// shortform blocklist (`background`, `font`, …), and `backgroundImage` is not on
+// it — so a plain `View` carries the gradient with no DOM escape hatch.
+//
+// The native counterpart (./gradient.native.js) delegates to
+// expo-linear-gradient, projecting the SAME CSS angle through the SAME
+// `gradientAngleToVector` from the contract. Keep the two in lockstep.
+
+import React from "react";
+import * as ReactNative from "react-native-web";
+import { gradientStops } from "./gradient-stops.js";
+
+const DEFAULT_ANGLE = 180;
+
+export function Gradient({ colors, angle = DEFAULT_ANGLE, style, ...rest }) {
+  const stops = gradientStops(colors);
+  const deg = Number.isFinite(angle) ? angle : DEFAULT_ANGLE;
+  const gradientStyle = stops
+    ? { backgroundImage: `linear-gradient(${deg}deg, ${stops.join(", ")})` }
+    : null;
+  return React.createElement(ReactNative.View, {
+    ...rest,
+    style: [style, gradientStyle],
+  });
+}

package/dist/gradient.native.js

@@ -0,0 +1,32 @@
+// REQ-AI-AGENT-DESIGN (sc-3696) — `<Gradient>` (native).
+//
+// Delegates to expo-linear-gradient, which is pinned UNCONDITIONALLY in every
+// export (BASE_DEPENDENCIES in backend/src/core/services/export-dependencies.ts,
+// where the app-shell backdrop already uses it), so Metro always resolves it.
+//
+// The web counterpart (./gradient.js) paints a CSS `linear-gradient`. Both take
+// the SAME CSS-degree `angle` and run it through the SAME
+// `gradientAngleToVector` from the contract, so a widget authored once reads
+// identically on both hosts (widget-parity skill).
+
+import React from "react";
+import { LinearGradient } from "expo-linear-gradient";
+import { gradientAngleToVector } from "./contract.js";
+import { gradientStops } from "./gradient-stops.js";
+
+const DEFAULT_ANGLE = 180;
+
+export function Gradient({ colors, angle = DEFAULT_ANGLE, style, ...rest }) {
+  const stops = gradientStops(colors);
+  if (!stops) return React.createElement(LinearGradient, { ...rest, style });
+  const { start, end } = gradientAngleToVector(
+    Number.isFinite(angle) ? angle : DEFAULT_ANGLE,
+  );
+  return React.createElement(LinearGradient, {
+    ...rest,
+    colors: stops,
+    start,
+    end,
+    style,
+  });
+}

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/index.d.ts

@@ -267,10 +267,26 @@ export interface WidgetManifest {
   translations?: Record<string, { en: string } & Record<string, string>>;
 }
 
+/** A React Native shadow style object — one level of `ThemeTokens.elevation`. */
+export interface ElevationLevel {
+  shadowColor?: string;
+  shadowOffset?: { width: number; height: number };
+  shadowOpacity?: number;
+  shadowRadius?: number;
+  /** Android elevation. */
+  elevation?: number;
+}
+
 export interface ThemeTokens {
   colors: {
     primary: string;
     onPrimary: string;
+    /** sc-3696: tint of the accent over the surface — chips, quiet buttons. */
+    primarySoft: string;
+    /** sc-3696: contrast-guaranteed text/icon colour on `primarySoft`. */
+    onPrimarySoft: string;
+    /** sc-3696: the accent's deeper end — a gradient's far stop. */
+    primaryStrong: string;
     secondary: string;
     onSecondary: string;
     surface: string;
@@ -278,6 +294,14 @@ export interface ThemeTokens {
     danger: string;
     [k: string]: string;
   };
+  /** sc-3696: the shared elevation vocabulary. Spread a level into a style. */
+  elevation: {
+    none: ElevationLevel;
+    sm: ElevationLevel;
+    md: ElevationLevel;
+    lg: ElevationLevel;
+    xl: ElevationLevel;
+  };
   spacing: { xs: number; sm: number; md: number; lg: number; xl: number };
   radii: { sm: number; md: number; lg: number; pill: number };
   typography: {
@@ -1339,6 +1363,75 @@ export const Icon: (props: {
   color?: string;
 }) => any;
 
+/**
+ * REQ-AI-AGENT-DESIGN (sc-3696) — linear-gradient surface. A `View` that paints
+ * a gradient behind its children, so it replaces the `View` you would otherwise
+ * give a flat `backgroundColor`. Web paints a CSS `linear-gradient`; native
+ * delegates to expo-linear-gradient through the same angle projection.
+ *
+ * @example
+ *   <Gradient
+ *     colors={[theme.colors.primary, theme.colors.primaryStrong]}
+ *     angle={160}
+ *     style={{ borderRadius: theme.radii.lg, padding: theme.spacing.md }}
+ *   >
+ *     <Text style={{ color: theme.colors.onPrimary }}>Log a glass</Text>
+ *   </Gradient>
+ */
+export const Gradient: (props: {
+  /** Two or more colour stops. Use theme colour roles, never raw hex. */
+  colors: string[];
+  /** CSS degrees: 0 = to top, 90 = to right. Defaults to 180 (to bottom). */
+  angle?: number;
+  style?: any;
+  children?: ReactNode;
+}) => any;
+
+// ------------------------------------------------------- theme derivation
+// sc-3696: the colour maths both hosts resolve `useTheme()` with. Exported so
+// the Player (frontend/src/services/widgetTheme.js) and the exported app's
+// generated theme module share ONE implementation instead of mirrored copies.
+
+/** True when `value` is a 3- or 6-digit hex colour string. */
+export function isHexColor(value: unknown): boolean;
+
+/** Linear sRGB mix of two hex colours (`t` 0 = a, 1 = b). Bad input → `a`. */
+export function mixHex(a: string, b: string, t: number): string;
+
+/** WCAG contrast ratio between two hex colours. Always >= 1. */
+export function contrastRatio(a: string, b: string): number;
+
+/** Pick `dark` or `light` — whichever is readable on the given background. */
+export function readableTextColor(
+  hex: string,
+  dark: string,
+  light: string,
+): string;
+
+/**
+ * Derive the accent's quiet tiers from a resolved palette. `onPrimarySoft` is
+ * stepped toward `onSurface` until it clears WCAG AA against the tint, so a chip
+ * label is legible for every tenant accent. `null` when the inputs aren't hex.
+ */
+export function deriveAccentTints(
+  primary: string,
+  surface: string,
+  onSurface: string,
+): {
+  primarySoft: string;
+  onPrimarySoft: string;
+  primaryStrong: string;
+} | null;
+
+/**
+ * Map a CSS gradient angle (0 = to top, 90 = to right) to the `{ start, end }`
+ * unit vectors expo-linear-gradient expects.
+ */
+export function gradientAngleToVector(angle: number): {
+  start: { x: number; y: number };
+  end: { x: number; y: number };
+};
+
 // Linter
 export interface LintFinding {
   rule: string;

package/dist/index.js

@@ -70,7 +70,23 @@ export {
   Icon,
   DateTimePicker,
   FilePicker,
+  Gradient,
 } from "./primitives.js";
 export { lintSource, bannedIdentifiers } from "./linter.js";
-export { CONTRACT, isHookAllowed, requiredContextKeys } from "./contract.js";
+// sc-3696: the trailing six are the theme-derivation helpers both hosts resolve
+// `useTheme()` with (the Player through widgetTheme.js, the export through its
+// generated theme module), plus the gradient angle projection `<Gradient>`
+// shares with the app-shell backdrop. Keep comments OUT of the export clause —
+// the contract test's orphan-export scanner parses it with a regex.
+export {
+  CONTRACT,
+  isHookAllowed,
+  requiredContextKeys,
+  isHexColor,
+  mixHex,
+  contrastRatio,
+  readableTextColor,
+  deriveAccentTints,
+  gradientAngleToVector,
+} from "./contract.js";
 export { normalizeLucideIconName } from "./lucideIconName.js";

package/dist/index.native.js

@@ -68,7 +68,23 @@ export {
   Icon,
   DateTimePicker,
   FilePicker,
+  Gradient,
 } from "./primitives.native.js";
 export { lintSource, bannedIdentifiers } from "./linter.js";
-export { CONTRACT, isHookAllowed, requiredContextKeys } from "./contract.js";
+// sc-3696: the trailing six are the theme-derivation helpers both hosts resolve
+// `useTheme()` with (the Player through widgetTheme.js, the export through its
+// generated theme module), plus the gradient angle projection `<Gradient>`
+// shares with the app-shell backdrop. Keep comments OUT of the export clause —
+// the contract test's orphan-export scanner parses it with a regex.
+export {
+  CONTRACT,
+  isHookAllowed,
+  requiredContextKeys,
+  isHexColor,
+  mixHex,
+  contrastRatio,
+  readableTextColor,
+  deriveAccentTints,
+  gradientAngleToVector,
+} from "./contract.js";
 export { normalizeLucideIconName } from "./lucideIconName.js";

package/dist/primitives.js

@@ -76,3 +76,7 @@ export { DateTimePicker } from "./datetimepicker.js";
 // a vetted expo-document-picker pin lands. `isSupported` is a static
 // boolean widgets branch on to hide the trigger on native.
 export { FilePicker } from "./filepicker.js";
+// REQ-AI-AGENT-DESIGN (sc-3696) — `<Gradient>` (web). Paints a CSS
+// `linear-gradient` on a View; the native build (./gradient.native.js) delegates
+// to expo-linear-gradient through the same angle projection.
+export { Gradient } from "./gradient.js";

package/dist/primitives.native.js

@@ -36,3 +36,7 @@ export { DateTimePicker } from "./datetimepicker.native.js";
 // equivalent yet, so this build renders a disabled trigger and exposes
 // `FilePicker.isSupported = false` for widgets to branch on.
 export { FilePicker } from "./filepicker.native.js";
+// REQ-AI-AGENT-DESIGN (sc-3696) — `<Gradient>` (native). Delegates to
+// expo-linear-gradient (pinned unconditionally in every export); the web build
+// (./gradient.js) paints the equivalent CSS `linear-gradient`.
+export { Gradient } from "./gradient.native.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.67.0",
+  "version": "0.68.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -48,7 +48,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-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 src/__tests__/theme-components-parity.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 src/__tests__/theme-depth-tokens.test.js"
   },
   "engines": {
     "node": ">=18"