@colixsystems/widget-sdk 0.68.0 → 0.70.0

package/README.md

@@ -30,6 +30,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useToast()` | `{ showToast }` | `ctx.toast.showToast` (falls back to a CustomEvent / console) — no scope |
 | **CORE** | `useGeolocation(options?)` | `{ latitude, longitude, accuracy, loading, error, getCurrentPosition }` | `ctx.device.geolocation` — no scope. Capture is IMPERATIVE: call `getCurrentPosition()` from a user gesture (a tap), never on mount. Resolves to `{ latitude, longitude, accuracy }`; rejects with `GeolocationError` (`.code` in `PERMISSION_DENIED \| UNAVAILABLE \| TIMEOUT \| UNSUPPORTED \| INTERNAL`). Identical on web (`navigator.geolocation`) and the Expo export (`expo-location`). |
 | **CORE** | `useI18n()` | `{ t, locale }` | `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. |
+| **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. |
 | **DATASTORE** (`ctx.datastore`) | `useDatastoreQuery(table, options?)` | `{ data, loading, error, refetch }` | `records(table).list` (unwraps `{ data, meta }` to `data: []`) — `datastore.read:*` |
 | **DATASTORE** | `useDatastoreRecord(table, id)` | `{ data, loading, error, refetch }` | `records(table).get` — `datastore.read:<table>` |
 | **DATASTORE** | `useDatastoreSchema(tableId)` | `{ schema, loading, error, refetch }` | `schema(tableId)` — `datastore.read:<table>` |
@@ -53,7 +54,39 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`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**.
+`v0.70.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.70.0
+
+**Translate content the user typed — `useTranslate()` (sc-3783).** The workspace dictionary only covers strings *you* authored; content living in the app's data — a record's description, a file name, a REST payload — has no translation key because nobody assigned it one, so an app user who picked English still read it in whatever language it was entered. `useTranslate()` closes that gap:
+
+```jsx
+import { useState, useEffect } from "react";
+import { Text, useTranslate } from "@colixsystems/widget-sdk";
+
+const { translate, available, language } = useTranslate();
+const [shown, setShown] = useState(rows.map((r) => r.notes));
+useEffect(() => {
+  if (!available) return;
+  let live = true;
+  // ONE request for the whole batch. On failure keep the original text.
+  translate(rows.map((r) => r.notes))
+    .then((out) => { if (live) setShown(out); })
+    .catch(() => {});
+  return () => { live = false; };
+  // `language` is in the deps on purpose: the app user can switch language
+  // at any time, and this must re-translate when they do.
+}, [rows, available, translate, language]);
+```
+
+- **The target language is the app user's selected language** by default — that is the point of the hook, so a widget never has to know how the language was chosen. Pass `{ target }` only when the widget's purpose is translating into a language the user picks, and `{ source }` when you know the content's language (otherwise the provider auto-detects).
+- **A string in, a string out; an array in, an array out** — positionally aligned, and an array is ONE request. Calling it per row is the mistake to avoid. Limits per call: 50 segments, 5 000 characters each, 20 000 total.
+- **Repeat text is free.** Three caches sit behind it: the hook memoizes per session, the API keeps a short-lived in-process cache, and the platform keeps a durable per-workspace cache keyed by the content itself. Text already in the target language and blank text never reach the network at all.
+- **It costs a metered budget, so use it deliberately.** Each workspace has a monthly translated-character cap (only cache misses count). Exhausting it rejects with `TranslateError` code `TRANSLATION_QUOTA_EXCEEDED`, which — unlike a rate limit — will not clear until the next period; cached translations keep working. `TRANSLATE_NOT_CONFIGURED` means the platform has no provider at all.
+- **Never block a render on it.** Show the original text and swap in the translation when it resolves; always `catch` and fall back. `available` is `false` on a host that brokers no translation client (the Studio canvas preview), where `translate` rejects `UNSUPPORTED` instead of throwing at render — so hide any translate affordance when it is false.
+- **Identical on both hosts.** The web Player and the exported Expo app inject the same new `@colixsystems/translation-client` into `ctx.i18n.translate`, so the hook behaves the same in the browser and on a device.
+
+`CONTRACT.version` → `1.47.0`. Additive: one new hook + its error class, and one optional `ctx.i18n.translate` slice field. No existing export changed signature.
 
 ### What's new in 0.67.0
 
@@ -61,9 +94,10 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 - **`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.themeComponents` / `CONTRACT.themeComponentShadows` / `CONTRACT.themeComponentGradient`** publish the vocabulary: each scope's tokens, their value types and ranges, and the widget → style-field bindings. `themeTokens.components` defaults to `{}`.
+- **The `button` and `card` scopes carry a `gradient` token (sc-3727)** — `{ from: "#hex", to: "#hex", angle: 0-359 }`, painted through the `<Gradient>` primitive. It reaches a widget as an ordinary style field (`gradient`, `cardGradient`, `submitGradient`), so the author rule is unchanged: read `props.style`, and treat an explicit `null` as "this instance opted out of the app-wide gradient" rather than as unset.
 
-`CONTRACT.version` → `1.45.0`. Additive; no existing export changed signature, and an unthemed app renders identically.
+`CONTRACT.version` → `1.46.0`. Additive; no existing export changed signature, and an unthemed app renders identically.
 
 ### What's new in 0.66.0
 
@@ -522,6 +556,7 @@ A widget that works but looks unfinished is only half done. `useTheme()` is the
 - **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 }]}`.
+- **Drag and drop — show what is being dragged.** A drag where the item stays put reads as broken. Three things change the moment a drag starts: the **drag proxy** (the item lifts and follows the finger — `...theme.elevation.lg`, `{ scale: 1.03 }`, `opacity: 0.9`; for a tall or full-width item drag a compact `primarySoft` pill with its icon + one line of label instead), the **source placeholder** (the vacated slot keeps its height as a quiet `colors.surfaceMuted` block so the list doesn't collapse), and the **drop target** (one slot at a time highlighted with `primarySoft` or a 2px `colors.primary` border). Always animate the release — settle into the new slot, or `Animated.spring(pan, { toValue: { x: 0, y: 0 }, useNativeDriver: false })` back to the origin on cancel. Build it with `Animated` + `PanResponder` from `react-native` (the only mechanism that behaves identically on both hosts) — never HTML5 drag events (`draggable` / `onDragStart` / `dataTransfer` are web-only, and `document` / `window` are banned) — and start the drag from a `GripVertical` grip handle whenever the row is also tappable or sits in a `ScrollView`.
 - **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.

package/dist/contract.cjs

@@ -107,6 +107,17 @@ const DEFAULT_THEME_TOKENS = Object.freeze({
 // cannot drift between what Mason may emit and what a host actually applies.
 const THEME_COMPONENT_SHADOWS = Object.freeze(["none", "sm", "md", "lg"]);
 
+// sc-3727 — the `gradient` token's value shape: two hex stops plus a CSS-degree
+// angle, the same grammar as `themeConfig.backgroundGradient` minus the radial
+// variant (a component fill projects through `<Gradient>`, which is linear-only
+// on both hosts). Declared once so the coercion, the Studio control and the
+// planner prompt agree on the bounds.
+const THEME_COMPONENT_GRADIENT = Object.freeze({
+  angleMin: 0,
+  angleMax: 359,
+  defaultAngle: 180,
+});
+
 // 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({
@@ -115,6 +126,7 @@ const CARD_SURFACE_FIELDS = Object.freeze({
   radius: "cardRadius",
   padding: "cardPadding",
   shadow: "shadow",
+  gradient: "cardGradient",
 });
 
 // A form widget's submit button — the `button` scope reaches it through the
@@ -122,6 +134,7 @@ const CARD_SURFACE_FIELDS = Object.freeze({
 const FORM_SUBMIT_FIELDS = Object.freeze({
   background: "submitBackground",
   textColor: "submitTextColor",
+  gradient: "submitGradient",
 });
 
 const THEME_COMPONENTS = Object.freeze({
@@ -134,6 +147,7 @@ const THEME_COMPONENTS = Object.freeze({
       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" }),
+      gradient: Object.freeze({ type: "gradient" }),
     }),
     targets: Object.freeze({
       "appstudio.button": Object.freeze({
@@ -143,6 +157,7 @@ const THEME_COMPONENTS = Object.freeze({
         radius: "radius",
         fontSize: "fontSize",
         shadow: "shadow",
+        gradient: "gradient",
       }),
       "appstudio.form-input": FORM_SUBMIT_FIELDS,
       "appstudio.form-builder": FORM_SUBMIT_FIELDS,
@@ -156,6 +171,7 @@ const THEME_COMPONENTS = Object.freeze({
       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" }),
+      gradient: Object.freeze({ type: "gradient" }),
     }),
     targets: Object.freeze({
       "appstudio.user": CARD_SURFACE_FIELDS,
@@ -166,6 +182,7 @@ const THEME_COMPONENTS = Object.freeze({
       "appstudio.notifications": CARD_SURFACE_FIELDS,
       "appstudio.form-input": CARD_SURFACE_FIELDS,
       "appstudio.form-builder": CARD_SURFACE_FIELDS,
+      "appstudio.user-management": CARD_SURFACE_FIELDS,
     }),
   }),
   text: Object.freeze({
@@ -230,6 +247,31 @@ const HOOKS = [
     requiredContextSlice: ["i18n.t", "i18n.locale"],
     scopes: null,
   },
+  {
+    name: "useTranslate",
+    signature: "useTranslate()",
+    description:
+      "sc-3783 — translate USER-GENERATED content (a record's text, a file name, an API payload) into the app user's selected language. " +
+      "NOT for the app's own copy: author-written strings belong in the workspace dictionary and are resolved for free by useI18n().t(key); " +
+      "reach for translate() only when there is no key because there is no author. Returns { translate, translating, error, language, available }. " +
+      "translate(input, options?) takes a string (resolves to a string) or an array of strings (resolves to an array, positionally aligned) and " +
+      "batches an array into ONE request. options.target defaults to the app user's language; options.source is optional (the provider auto-detects). " +
+      "Text already in the target language, blank text, and text already translated this session cost nothing and never reach the network. " +
+      "Rejects with a TranslateError whose .code is one of UNSUPPORTED | TRANSLATE_NOT_CONFIGURED | TRANSLATION_QUOTA_EXCEEDED | RATE_LIMITED | " +
+      "PAYLOAD_TOO_LARGE | VALIDATION | AUTH_REQUIRED | INTERNAL. Limits per call: 50 segments, 5 000 chars each, 20 000 chars total. " +
+      "`available` is false on a host that brokers no translation client; translate() then rejects UNSUPPORTED instead of throwing at render. " +
+      "Identical on web (Player) and the Expo export — both hosts inject the same @colixsystems/translation-client.",
+    returnShape: {
+      translate:
+        "(input: string | string[], options?: { target?: string, source?: string }) => Promise<string | string[]>  // rejects with TranslateError",
+      translating: "boolean",
+      error: "TranslateError | null",
+      language: "string  // the app user's selected language (the default target)",
+      available: "boolean",
+    },
+    requiredContextSlice: ["i18n.locale"],
+    scopes: null,
+  },
   {
     name: "useUser",
     signature: "useUser()",
@@ -1326,9 +1368,18 @@ const WIDGET_CONTEXT_SHAPE = {
   // ctx.datastore.records(table).permissions(record). See the `directory`
   // and `datastore` slices above.
   i18n: {
-    description: "{ t(key, fallback?), locale }.",
+    // sc-3783 — `translate` is the injected @colixsystems/translation-client
+    // instance backing useTranslate(). OPTIONAL on the slice: a host that
+    // brokers no translation client omits it and the hook reports
+    // available:false (same convention as ctx.toast / ctx.device) rather than
+    // throwing at render. Both the web Player and the Expo export inject it.
+    description:
+      "{ t(key, fallback?), locale, translate? } — `translate` is the injected " +
+      "@colixsystems/translation-client ({ translate(body), status() }) that backs " +
+      "useTranslate() for user-generated content.",
     required: true,
     fields: { t: "function", locale: "string" },
+    optionalFields: { translate: "object" },
   },
   logger: {
     description:
@@ -2150,7 +2201,21 @@ const CONTRACT = deepFreeze({
   //    (`@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",
+  // 1.46.0: additive (sc-3727) — a `gradient` token type on the per-component
+  //    vocabulary. The `button` and `card` scopes each gain a `gradient` token
+  //    whose value is `{ from: "#hex", to: "#hex", angle: 0-359 }` — the
+  //    `backgroundGradient` grammar minus the radial variant, because a component
+  //    fill paints through the `<Gradient>` primitive, which is linear on both
+  //    hosts. `themeComponentGradient` publishes the angle bounds + default so the
+  //    coercion, the Studio control and the planner prompt cannot disagree. The
+  //    token binds to per-instance style fields the target widgets read
+  //    (`gradient` on Button, `cardGradient` on every card surface,
+  //    `submitGradient` on a form's submit button), so the theme value is a
+  //    DEFAULT an author overrides per instance — or suppresses with an explicit
+  //    null, which is how one button stays flat while the rest are gradiented.
+  //    Additive: no export changed signature and a theme with no gradient token
+  //    renders exactly as before.
+  version: "1.47.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -2163,6 +2228,7 @@ const CONTRACT = deepFreeze({
   themeTokens: DEFAULT_THEME_TOKENS,
   themeComponents: THEME_COMPONENTS,
   themeComponentShadows: THEME_COMPONENT_SHADOWS,
+  themeComponentGradient: THEME_COMPONENT_GRADIENT,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,
   bannedApis: BANNED_APIS,
@@ -2305,6 +2371,33 @@ function gradientAngleToVector(angle) {
   };
 }
 
+// Alpha is allowed here (unlike HEX_RE) because the Mason build runner already
+// persists 8-digit component colours; the host must not drop what it accepted.
+const GRADIENT_HEX_RE = /^#(?:[0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+
+/**
+ * sc-3727 — normalise a component `gradient` to `{ from, to, angle }`, or `null`.
+ *
+ * ONE validator for a value arriving by two routes — the theme token and the
+ * author's never-coerced per-instance `props.style` — so `set_theme` and the
+ * renderer cannot disagree about the same value (CLAUDE.md §3). Both stops are
+ * required: a one-stop gradient would paint a fill the author never chose. The
+ * hex grammar is also the injection guard — these stops are interpolated into
+ * CSS and into generated export source.
+ */
+function normaliseComponentGradient(raw) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const from = typeof raw.from === "string" ? raw.from.trim() : "";
+  const to = typeof raw.to === "string" ? raw.to.trim() : "";
+  if (!GRADIENT_HEX_RE.test(from) || !GRADIENT_HEX_RE.test(to)) return null;
+  const { defaultAngle } = THEME_COMPONENT_GRADIENT;
+  // Read once — a second read of an accessor could return a different value and
+  // land NaN in a style.
+  const angle = raw.angle;
+  const deg = Number.isFinite(angle) ? Math.round(angle) : defaultAngle;
+  return { from, to, angle: ((deg % 360) + 360) % 360 };
+}
+
 module.exports = {
   CONTRACT,
   isHookAllowed,
@@ -2315,6 +2408,7 @@ module.exports = {
   readableTextColor,
   deriveAccentTints,
   gradientAngleToVector,
+  normaliseComponentGradient,
   widgetTranslationPrefix,
   widgetTranslationKey,
   sharedTranslationPrefix,

package/dist/contract.js

@@ -107,6 +107,17 @@ const DEFAULT_THEME_TOKENS = Object.freeze({
 // cannot drift between what Mason may emit and what a host actually applies.
 const THEME_COMPONENT_SHADOWS = Object.freeze(["none", "sm", "md", "lg"]);
 
+// sc-3727 — the `gradient` token's value shape: two hex stops plus a CSS-degree
+// angle, the same grammar as `themeConfig.backgroundGradient` minus the radial
+// variant (a component fill projects through `<Gradient>`, which is linear-only
+// on both hosts). Declared once so the coercion, the Studio control and the
+// planner prompt agree on the bounds.
+const THEME_COMPONENT_GRADIENT = Object.freeze({
+  angleMin: 0,
+  angleMax: 359,
+  defaultAngle: 180,
+});
+
 // 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({
@@ -115,6 +126,7 @@ const CARD_SURFACE_FIELDS = Object.freeze({
   radius: "cardRadius",
   padding: "cardPadding",
   shadow: "shadow",
+  gradient: "cardGradient",
 });
 
 // A form widget's submit button — the `button` scope reaches it through the
@@ -122,6 +134,7 @@ const CARD_SURFACE_FIELDS = Object.freeze({
 const FORM_SUBMIT_FIELDS = Object.freeze({
   background: "submitBackground",
   textColor: "submitTextColor",
+  gradient: "submitGradient",
 });
 
 const THEME_COMPONENTS = Object.freeze({
@@ -134,6 +147,7 @@ const THEME_COMPONENTS = Object.freeze({
       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" }),
+      gradient: Object.freeze({ type: "gradient" }),
     }),
     targets: Object.freeze({
       "appstudio.button": Object.freeze({
@@ -143,6 +157,7 @@ const THEME_COMPONENTS = Object.freeze({
         radius: "radius",
         fontSize: "fontSize",
         shadow: "shadow",
+        gradient: "gradient",
       }),
       "appstudio.form-input": FORM_SUBMIT_FIELDS,
       "appstudio.form-builder": FORM_SUBMIT_FIELDS,
@@ -156,6 +171,7 @@ const THEME_COMPONENTS = Object.freeze({
       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" }),
+      gradient: Object.freeze({ type: "gradient" }),
     }),
     targets: Object.freeze({
       "appstudio.user": CARD_SURFACE_FIELDS,
@@ -166,6 +182,7 @@ const THEME_COMPONENTS = Object.freeze({
       "appstudio.notifications": CARD_SURFACE_FIELDS,
       "appstudio.form-input": CARD_SURFACE_FIELDS,
       "appstudio.form-builder": CARD_SURFACE_FIELDS,
+      "appstudio.user-management": CARD_SURFACE_FIELDS,
     }),
   }),
   text: Object.freeze({
@@ -230,6 +247,31 @@ const HOOKS = [
     requiredContextSlice: ["i18n.t", "i18n.locale"],
     scopes: null,
   },
+  {
+    name: "useTranslate",
+    signature: "useTranslate()",
+    description:
+      "sc-3783 — translate USER-GENERATED content (a record's text, a file name, an API payload) into the app user's selected language. " +
+      "NOT for the app's own copy: author-written strings belong in the workspace dictionary and are resolved for free by useI18n().t(key); " +
+      "reach for translate() only when there is no key because there is no author. Returns { translate, translating, error, language, available }. " +
+      "translate(input, options?) takes a string (resolves to a string) or an array of strings (resolves to an array, positionally aligned) and " +
+      "batches an array into ONE request. options.target defaults to the app user's language; options.source is optional (the provider auto-detects). " +
+      "Text already in the target language, blank text, and text already translated this session cost nothing and never reach the network. " +
+      "Rejects with a TranslateError whose .code is one of UNSUPPORTED | TRANSLATE_NOT_CONFIGURED | TRANSLATION_QUOTA_EXCEEDED | RATE_LIMITED | " +
+      "PAYLOAD_TOO_LARGE | VALIDATION | AUTH_REQUIRED | INTERNAL. Limits per call: 50 segments, 5 000 chars each, 20 000 chars total. " +
+      "`available` is false on a host that brokers no translation client; translate() then rejects UNSUPPORTED instead of throwing at render. " +
+      "Identical on web (Player) and the Expo export — both hosts inject the same @colixsystems/translation-client.",
+    returnShape: {
+      translate:
+        "(input: string | string[], options?: { target?: string, source?: string }) => Promise<string | string[]>  // rejects with TranslateError",
+      translating: "boolean",
+      error: "TranslateError | null",
+      language: "string  // the app user's selected language (the default target)",
+      available: "boolean",
+    },
+    requiredContextSlice: ["i18n.locale"],
+    scopes: null,
+  },
   {
     name: "useUser",
     signature: "useUser()",
@@ -1326,9 +1368,18 @@ const WIDGET_CONTEXT_SHAPE = {
   // ctx.datastore.records(table).permissions(record). See the `directory`
   // and `datastore` slices above.
   i18n: {
-    description: "{ t(key, fallback?), locale }.",
+    // sc-3783 — `translate` is the injected @colixsystems/translation-client
+    // instance backing useTranslate(). OPTIONAL on the slice: a host that
+    // brokers no translation client omits it and the hook reports
+    // available:false (same convention as ctx.toast / ctx.device) rather than
+    // throwing at render. Both the web Player and the Expo export inject it.
+    description:
+      "{ t(key, fallback?), locale, translate? } — `translate` is the injected " +
+      "@colixsystems/translation-client ({ translate(body), status() }) that backs " +
+      "useTranslate() for user-generated content.",
     required: true,
     fields: { t: "function", locale: "string" },
+    optionalFields: { translate: "object" },
   },
   logger: {
     description:
@@ -2150,7 +2201,21 @@ const CONTRACT = deepFreeze({
   //    (`@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",
+  // 1.46.0: additive (sc-3727) — a `gradient` token type on the per-component
+  //    vocabulary. The `button` and `card` scopes each gain a `gradient` token
+  //    whose value is `{ from: "#hex", to: "#hex", angle: 0-359 }` — the
+  //    `backgroundGradient` grammar minus the radial variant, because a component
+  //    fill paints through the `<Gradient>` primitive, which is linear on both
+  //    hosts. `themeComponentGradient` publishes the angle bounds + default so the
+  //    coercion, the Studio control and the planner prompt cannot disagree. The
+  //    token binds to per-instance style fields the target widgets read
+  //    (`gradient` on Button, `cardGradient` on every card surface,
+  //    `submitGradient` on a form's submit button), so the theme value is a
+  //    DEFAULT an author overrides per instance — or suppresses with an explicit
+  //    null, which is how one button stays flat while the rest are gradiented.
+  //    Additive: no export changed signature and a theme with no gradient token
+  //    renders exactly as before.
+  version: "1.47.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -2163,6 +2228,7 @@ const CONTRACT = deepFreeze({
   themeTokens: DEFAULT_THEME_TOKENS,
   themeComponents: THEME_COMPONENTS,
   themeComponentShadows: THEME_COMPONENT_SHADOWS,
+  themeComponentGradient: THEME_COMPONENT_GRADIENT,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,
   bannedApis: BANNED_APIS,
@@ -2305,6 +2371,33 @@ function gradientAngleToVector(angle) {
   };
 }
 
+// Alpha is allowed here (unlike HEX_RE) because the Mason build runner already
+// persists 8-digit component colours; the host must not drop what it accepted.
+const GRADIENT_HEX_RE = /^#(?:[0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+
+/**
+ * sc-3727 — normalise a component `gradient` to `{ from, to, angle }`, or `null`.
+ *
+ * ONE validator for a value arriving by two routes — the theme token and the
+ * author's never-coerced per-instance `props.style` — so `set_theme` and the
+ * renderer cannot disagree about the same value (CLAUDE.md §3). Both stops are
+ * required: a one-stop gradient would paint a fill the author never chose. The
+ * hex grammar is also the injection guard — these stops are interpolated into
+ * CSS and into generated export source.
+ */
+function normaliseComponentGradient(raw) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const from = typeof raw.from === "string" ? raw.from.trim() : "";
+  const to = typeof raw.to === "string" ? raw.to.trim() : "";
+  if (!GRADIENT_HEX_RE.test(from) || !GRADIENT_HEX_RE.test(to)) return null;
+  const { defaultAngle } = THEME_COMPONENT_GRADIENT;
+  // Read once — a second read of an accessor could return a different value and
+  // land NaN in a style.
+  const angle = raw.angle;
+  const deg = Number.isFinite(angle) ? Math.round(angle) : defaultAngle;
+  return { from, to, angle: ((deg % 360) + 360) % 360 };
+}
+
 export {
   CONTRACT,
   isHookAllowed,
@@ -2315,6 +2408,7 @@ export {
   readableTextColor,
   deriveAccentTints,
   gradientAngleToVector,
+  normaliseComponentGradient,
   widgetTranslationPrefix,
   widgetTranslationKey,
   sharedTranslationPrefix,

package/dist/hooks.js

@@ -368,6 +368,222 @@ export function useI18n() {
   return { t, locale };
 }
 
+/**
+ * sc-3783 — structured error thrown by `useTranslate().translate`. Carries a
+ * stable `code` so widgets branch without parsing message strings; mirrors the
+ * shape of `NotificationError` / `DirectoryError`.
+ *
+ * `code` is one of:
+ *   - "UNSUPPORTED"                 — the host brokers no translation client
+ *   - "TRANSLATE_NOT_CONFIGURED"    — 503 (platform has no provider configured)
+ *   - "TRANSLATION_QUOTA_EXCEEDED"  — 429 (workspace's monthly character cap;
+ *                                     does NOT clear until the next period)
+ *   - "RATE_LIMITED"                — 429 (too many calls — retry shortly)
+ *   - "PAYLOAD_TOO_LARGE"           — 413 (batch smaller)
+ *   - "VALIDATION"                  — 400 (bad segments or language code)
+ *   - "AUTH_REQUIRED"               — 401 (no signed-in app user)
+ *   - "INTERNAL"                    — anything else (network, 5xx)
+ */
+export class TranslateError extends Error {
+  constructor(code, message, opts) {
+    super(message);
+    this.name = "TranslateError";
+    this.code = code;
+    if (opts && opts.cause) this.cause = opts.cause;
+  }
+}
+
+function toTranslateError(err) {
+  if (err instanceof TranslateError) return err;
+  const status =
+    err && err.response && typeof err.response.status === "number"
+      ? err.response.status
+      : err && typeof err.status === "number"
+        ? err.status
+        : null;
+  const bodyCode =
+    (err && err.response && err.response.data && err.response.data.code) ||
+    (err && typeof err.code === "string" ? err.code : null);
+  const bodyMessage =
+    err && err.response && err.response.data && err.response.data.error;
+  let code = "INTERNAL";
+  if (typeof bodyCode === "string" && bodyCode) code = bodyCode;
+  else if (status === 401) code = "AUTH_REQUIRED";
+  else if (status === 413) code = "PAYLOAD_TOO_LARGE";
+  else if (status === 429) code = "RATE_LIMITED";
+  else if (status === 400) code = "VALIDATION";
+  else if (status === 503) code = "TRANSLATE_NOT_CONFIGURED";
+  const message =
+    (typeof bodyMessage === "string" && bodyMessage) ||
+    (err && typeof err.message === "string" ? err.message : "Translation failed");
+  return new TranslateError(code, message, { cause: err });
+}
+
+// Session-lifetime memo shared by every widget instance on the page. This is
+// the third cache layer (the API keeps an in-process one, the DB keeps the
+// durable one) and the only one that avoids the network entirely — it matters
+// because a list widget re-renders constantly with the same row text. Keyed by
+// the same tuple the server keys by, so it can never answer for the wrong pair.
+const TRANSLATE_MEMO_MAX = 1000;
+const translateMemo = new Map();
+
+function memoKey(text, source, target) {
+  return `${target}|${source || "auto"}|${text}`;
+}
+
+function memoRead(text, source, target) {
+  const key = memoKey(text, source, target);
+  if (!translateMemo.has(key)) return undefined;
+  const value = translateMemo.get(key);
+  translateMemo.delete(key);
+  translateMemo.set(key, value);
+  return value;
+}
+
+function memoWrite(text, source, target, value) {
+  if (translateMemo.size >= TRANSLATE_MEMO_MAX) {
+    const oldest = translateMemo.keys().next();
+    if (!oldest.done) translateMemo.delete(oldest.value);
+  }
+  translateMemo.set(memoKey(text, source, target), value);
+}
+
+/** Exposed so tests (and a host teardown) can drop the session memo. */
+export function _resetTranslateMemo() {
+  translateMemo.clear();
+}
+
+/**
+ * sc-3783 — translate USER-GENERATED content into the app user's language.
+ * Returns `{ translate, translating, error, language, available }`.
+ *
+ * Use this for text nobody authored: a datastore record's description, a file
+ * name, a REST payload. The app's OWN copy belongs in the workspace dictionary
+ * and is resolved for free by `useI18n().t(key)` — reach for `translate` only
+ * when there is no key because there is no author.
+ *
+ *   const { translate } = useTranslate();
+ *   const shown = await translate(record.description);        // → app user's language
+ *   const rows  = await translate(items.map((i) => i.title)); // batch, one request
+ *   const de    = await translate(text, { source: "sv", target: "de" });
+ *
+ * `translate` accepts a string (resolves to a string) or an array of strings
+ * (resolves to an array, positionally aligned). `target` defaults to the app
+ * user's selected language — the whole point of the hook, so a widget never has
+ * to know how the language was chosen. `source` is optional; the provider
+ * auto-detects when it is omitted.
+ *
+ * Text already in the target language, blank text, and text this session has
+ * already translated cost nothing and never reach the network.
+ *
+ * `available` is false when the host brokers no translation client (an older
+ * host). Calling `translate` then rejects with code "UNSUPPORTED" rather than
+ * throwing at render, so a widget degrades to untranslated text instead of
+ * breaking the page.
+ */
+export function useTranslate() {
+  const ctx = useWidgetContextOrThrow("useTranslate");
+  const i18n = ctx.i18n || {};
+  const locale = typeof i18n.locale === "string" && i18n.locale ? i18n.locale : "en";
+  const client =
+    i18n.translate && typeof i18n.translate.translate === "function"
+      ? i18n.translate
+      : null;
+
+  // `ctx` is a fresh identity each host render — hold the client + locale in
+  // refs so the returned callback stays stable across renders.
+  const clientRef = useRef(client);
+  clientRef.current = client;
+  const localeRef = useRef(locale);
+  localeRef.current = locale;
+
+  const [translating, setTranslating] = useState(false);
+  const [error, setError] = useState(null);
+
+  const translate = useCallback(async (input, options) => {
+    const wasArray = Array.isArray(input);
+    const segments = wasArray ? input : [input];
+    for (const segment of segments) {
+      if (typeof segment !== "string") {
+        throw new TranslateError(
+          "VALIDATION",
+          "useTranslate: expected a string or an array of strings",
+        );
+      }
+    }
+    const target =
+      options && typeof options.target === "string" && options.target
+        ? options.target
+        : localeRef.current;
+    const source =
+      options && typeof options.source === "string" && options.source
+        ? options.source
+        : null;
+
+    // Nothing to do: same language in and out, so return the input untouched
+    // without waking the network or the provider.
+    if (source && source === target) return wasArray ? [...segments] : segments[0];
+
+    const out = new Array(segments.length);
+    const missing = [];
+    const missingIndices = [];
+    for (let i = 0; i < segments.length; i++) {
+      const text = segments[i];
+      if (text.trim() === "") {
+        out[i] = text;
+        continue;
+      }
+      const memoized = memoRead(text, source, target);
+      if (memoized !== undefined) {
+        out[i] = memoized;
+        continue;
+      }
+      missing.push(text);
+      missingIndices.push(i);
+    }
+    if (missing.length === 0) return wasArray ? out : out[0];
+
+    if (!clientRef.current) {
+      const err = new TranslateError(
+        "UNSUPPORTED",
+        "useTranslate: the host brokers no translation client",
+      );
+      setError(err);
+      throw err;
+    }
+
+    setTranslating(true);
+    setError(null);
+    try {
+      const res = await clientRef.current.translate({
+        segments: missing,
+        target_language: target,
+        source_language: source || undefined,
+      });
+      const translations = Array.isArray(res && res.translations) ? res.translations : [];
+      for (let m = 0; m < missingIndices.length; m++) {
+        // A short response must not shift results onto the wrong segment; fall
+        // back to the source text for anything the server did not answer.
+        const value =
+          typeof translations[m] === "string" && translations[m].length > 0
+            ? translations[m]
+            : missing[m];
+        out[missingIndices[m]] = value;
+        memoWrite(missing[m], source, target, value);
+      }
+      setTranslating(false);
+      return wasArray ? out : out[0];
+    } catch (err) {
+      const e = toTranslateError(err);
+      setError(e);
+      setTranslating(false);
+      throw e;
+    }
+  }, []);
+
+  return { translate, translating, error, language: locale, available: client !== null };
+}
+
 /* ============================================================================
  * DEVICE — ctx.device (host-brokered device capabilities)
  *

package/dist/host.d.ts

@@ -12,7 +12,17 @@ export function resolveProps<T = Record<string, unknown>>(
   props: unknown,
 ): T;
 
-export type ThemeComponentStyle = Record<string, string | number>;
+// sc-3727: a `gradient` token's value, the one non-scalar token type.
+export interface ThemeComponentGradient {
+  from: string;
+  to: string;
+  angle: number;
+}
+
+export type ThemeComponentStyle = Record<
+  string,
+  string | number | ThemeComponentGradient
+>;
 export type ThemeComponents = Record<string, ThemeComponentStyle>;
 
 /**

package/dist/index.d.ts

@@ -909,6 +909,39 @@ export function useI18n(): {
   t(key: string, fallback?: string): string;
 };
 
+/**
+ * sc-3783 — translate USER-GENERATED content (record text, file names, API
+ * payloads) into the app user's selected language.
+ *
+ * NOT for the app's own copy: author-written strings belong in the workspace
+ * dictionary and are resolved for free by `useI18n().t(key)`. Reach for this
+ * only when there is no key because there is no author.
+ *
+ * A string resolves to a string and an array resolves to an array (positionally
+ * aligned, sent as ONE request). `options.target` defaults to the app user's
+ * language. Text already in the target language, blank text, and text already
+ * translated this session cost nothing and never reach the network.
+ *
+ * `available` is false on a host that brokers no translation client (the Studio
+ * canvas preview); `translate` then rejects with code "UNSUPPORTED" rather than
+ * throwing at render, so the widget can show untranslated text.
+ */
+export function useTranslate(): {
+  translate(input: string, options?: TranslateOptions): Promise<string>;
+  translate(input: string[], options?: TranslateOptions): Promise<string[]>;
+  translating: boolean;
+  error: TranslateError | null;
+  language: string;
+  available: boolean;
+};
+
+export interface TranslateOptions {
+  /** Target language code. Defaults to the app user's selected language. */
+  target?: string;
+  /** Source language code. Omit to let the provider auto-detect. */
+  source?: string;
+}
+
 /**
  * The active end-user identity. `id` is null for anonymous visitors and on
  * the Studio canvas preview; every field is guaranteed present (the host
@@ -1079,6 +1112,29 @@ export class DirectoryError extends Error {
   );
 }
 
+/**
+ * sc-3783 — error class thrown by `useTranslate().translate`. The `code` is a
+ * stable categorisation widgets can branch on. TRANSLATION_QUOTA_EXCEEDED and
+ * TRANSLATE_NOT_CONFIGURED will not clear on a retry — show the original text.
+ */
+export class TranslateError extends Error {
+  code:
+    | "UNSUPPORTED"
+    | "TRANSLATE_NOT_CONFIGURED"
+    | "TRANSLATION_QUOTA_EXCEEDED"
+    | "RATE_LIMITED"
+    | "PAYLOAD_TOO_LARGE"
+    | "VALIDATION"
+    | "AUTH_REQUIRED"
+    | "INTERNAL"
+    | string;
+  constructor(
+    code: TranslateError["code"],
+    message?: string,
+    opts?: { cause?: unknown },
+  );
+}
+
 /**
  * sc-890 — error class thrown by `useSendNotification().send`. The `code` is a
  * stable categorisation widgets can branch on.
@@ -1432,6 +1488,22 @@ export function gradientAngleToVector(angle: number): {
   end: { x: number; y: number };
 };
 
+export interface ComponentGradient {
+  from: string;
+  to: string;
+  angle: number;
+}
+
+/**
+ * Normalise a component `gradient` style value to `{ from, to, angle }`, or null
+ * when it is unusable. Both stops are required; the angle wraps into 0-359.
+ * Shared by the theme-token coercion and the widget render path, so the same
+ * value cannot resolve two ways.
+ */
+export function normaliseComponentGradient(
+  raw: unknown,
+): ComponentGradient | null;
+
 // Linter
 export interface LintFinding {
   rule: string;

package/dist/index.js

@@ -39,6 +39,8 @@ export {
   useTheme,
   useWidgetStyle,
   useI18n,
+  useTranslate,
+  TranslateError,
   useUser,
   useFill,
   useNavigation,
@@ -88,5 +90,6 @@ export {
   readableTextColor,
   deriveAccentTints,
   gradientAngleToVector,
+  normaliseComponentGradient,
 } from "./contract.js";
 export { normalizeLucideIconName } from "./lucideIconName.js";

package/dist/index.native.js

@@ -39,6 +39,8 @@ export {
   useTheme,
   useWidgetStyle,
   useI18n,
+  useTranslate,
+  TranslateError,
   useUser,
   useFill,
   useNavigation,
@@ -86,5 +88,6 @@ export {
   readableTextColor,
   deriveAccentTints,
   gradientAngleToVector,
+  normaliseComponentGradient,
 } from "./contract.js";
 export { normalizeLucideIconName } from "./lucideIconName.js";

package/dist/theme-components.cjs

@@ -23,7 +23,7 @@
 // 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");
+const { CONTRACT, normaliseComponentGradient } = 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.
@@ -47,6 +47,11 @@ function coerceToken(def, value) {
   if (def.type === "shadow") {
     return CONTRACT.themeComponentShadows.includes(value) ? value : undefined;
   }
+  // sc-3727: the gradient value has its own normaliser on the contract, shared
+  // with the widget render path so both routes agree (CLAUDE.md §3).
+  if (def.type === "gradient") {
+    return normaliseComponentGradient(value) || undefined;
+  }
   return undefined;
 }
 

package/dist/theme-components.js

@@ -15,7 +15,7 @@
 // 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";
+import { CONTRACT, normaliseComponentGradient } 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.
@@ -39,6 +39,11 @@ function coerceToken(def, value) {
   if (def.type === "shadow") {
     return CONTRACT.themeComponentShadows.includes(value) ? value : undefined;
   }
+  // sc-3727: the gradient value has its own normaliser on the contract, shared
+  // with the widget render path so both routes agree (CLAUDE.md §3).
+  if (def.type === "gradient") {
+    return normaliseComponentGradient(value) || undefined;
+  }
   return undefined;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.68.0",
+  "version": "0.70.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__/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"
+    "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__/hooks-translate.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"