@colixsystems/widget-sdk 0.194.0 → 0.196.0

package/README.md

@@ -60,7 +60,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **FILES** (`ctx.assets`) | `useAsset(id)` | `{ url, file, loading, error, refetch }` | `ctx.assets.get` — no scope |
 | **FILES** | `useAssetsByTag(tag, { type })` (optional: the whole argument, and `type` within it) | `{ assets, loading, error, refetch }` | `ctx.assets.list` (unwraps `{ data, meta }` to `assets`) — no scope. `type` defaults to `"image"`; pass `"all"` / `"audio"` / `"video"` / `"document"` to widen. Falsy `tag` collapses to `assets: []` without a round-trip. |
 | **DIRECTORY** (`ctx.directory`) | `useDirectory(query)` (optional: query) | `{ users, loading, error, refetch }` | `directory.users.list` — `directory.read:users` |
-| **DIRECTORY** | `useUsers(query)` (optional: query) | `{ users, loading, error, refetch, invite, deactivate, reactivate, remove, sendPasswordReset }` | `directory.users.*` — `users.read:*` plus the `users.read` (or `users.write`) capability, else `FORBIDDEN` (edits, incl. `sendPasswordReset()`, also `users.write:*`; `remove()` also `users.delete:*`) |
+| **DIRECTORY** | `useUsers(query)` (optional: query) | `{ users, loading, error, refetch, invite, deactivate, reactivate, remove, sendPasswordReset, update }` | `directory.users.*` — `users.read:*` plus the `users.read` (or `users.write`) capability, else `FORBIDDEN` (edits, incl. `sendPasswordReset()` and `update()`, also `users.write:*`; `remove()` also `users.delete:*`) |
 | **DIRECTORY** | `useGroups(query)` (optional: query) | `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` | `directory.groups.*` — `groups.read:*` (mutations also `groups.write:*`) |
 | **DIRECTORY** | `useInvites(query)` (optional: query) | `{ invites, loading, error, refetch, resend, revoke }` | `directory.invites.*` — `users.write:*` + the SystemAcl `users.write` capability (the whole invite surface, list included). `query` is `{ status?, q?, app_user_id?, limit?, offset? }` with `status` ∈ `pending \| accepted \| revoked \| expired \| open \| all` (endpoint default `all`; `open` = `pending` or `expired`); `q` matches the invite's name or email, `app_user_id` returns the invites reserving that user id. |
 | **DIRECTORY** | `useBankIdLink()` | `{ linked, available, status, qr, message, startLink, refresh, cancel, unlink, refetchStatus, … }` | `directory.bankid.*` — no scope (JWT-gated self-service) |
@@ -77,7 +77,68 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.194.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.196.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.196.0 (contract 1.157.0)
+
+**A gradient can carry more than two colours.** A component gradient was exactly `{ from, to, angle }`. It now takes an optional `via` list of up to three middle colours, painted in order and evenly spaced between `from` and `to`:
+
+```js
+{ from: "#0f172a", via: ["#7c3aed", "#db2777"], to: "#f59e0b", angle: 135 }
+```
+
+- **`normaliseComponentGradient`** returns `via` only when the value carries some, so a two-colour gradient normalises exactly as before. A malformed `via` (not a list, more than `CONTRACT.themeComponentGradient.maxViaStops` entries, or an entry that is not a hex colour) is dropped and the two ends still paint, so a stored value never loses its gradient over it. Pass `{ strict: true }` to get `null` for a malformed `via` instead, which is what a write boundary wants.
+- **`componentGradientColors(gradient)`** gives a normalised gradient's colours in paint order, ready for `<Gradient colors={…}>`. **`componentGradientMidpoint(gradient)`** gives the colour halfway along it, the basis for choosing readable text.
+- **`<Card>` and `<Button>` paint the middle colours** when their gradient carries them, and a layout container's wash and photo scrim do the same on the web Player and in the exported app. A middle colour of a container wash may bind to the theme (`"theme:colors.primary"`) like its two ends.
+- **Fully additive.** Every stored two-colour gradient renders byte-identically.
+
+### What's new in 0.195.0 (contract 1.156.0)
+
+**An admin can correct a member's name or email — `useUsers().update(userId, { name, email })`.** Send either key or both; it resolves `{ id, name, email }`. Call `refetch()` afterwards to refresh the list.
+
+```jsx
+import { useUsers } from "@colixsystems/widget-sdk";
+
+// Manifest: requestedScopes: ["users.read:*", "users.write:*"]
+function ChangeMemberEmail({ user }) {
+  const { update, refetch } = useUsers();
+  const save = async (email) => {
+    try {
+      await update(user.id, { email });
+      await refetch();
+    } catch (err) {
+      if (err.reason === "EMAIL_TAKEN") { /* mark the email field */ }
+      // err.message is a sentence written for the person reading it.
+    }
+  };
+  return null;
+}
+```
+
+- **It needs `users.write:*`**, the same scope as `invite` and `deactivate`, plus the workspace's `users.write` capability for the signed-in person. **That scope now also covers changing a member's name and sign-in email**, which is a sensitive power: request it only for a surface meant for the people who administer the app. The linter asks for the scope when a source that calls `useUsers(` also calls `.update(`. If that `.update(` belongs to something else, end the line with `// @appstudio-skip-scope-check`.
+- **An email change is announced to the user at their previous address**, so a change they did not expect never goes unnoticed. You do not send that message yourself.
+- **Refusals name their reason.** `DirectoryError` gains `reason`, the host's specific refusal code, or `null` when it gave none. `code` stays the broad category.
+
+| `err.code` | `err.reason` | Meaning |
+| --- | --- | --- |
+| `VALIDATION` | `INVALID_UPDATE` | Neither `name` nor `email` was sent |
+| `VALIDATION` | `INVALID_NAME` / `INVALID_EMAIL` | The value is empty, too long or not an address |
+| `VALIDATION` | `EMAIL_TAKEN` | The address is not available |
+| `VALIDATION` | `EMAIL_RESERVED` | A reserved address |
+| `VALIDATION` | `SCIM_MANAGED_NAME` / `SCIM_MANAGED_EMAIL` | The profile is synced from an identity provider; change it there |
+| `VALIDATION` | `SSO_LINKED_EMAIL` | The user signs in through an identity provider; change the email there |
+| `VALIDATION` | `SERVICE_ACCOUNT_PROTECTED` | A service account's email cannot be changed |
+| `VALIDATION` | `SEED_USER_PROTECTED` / `REVIEW_USER_PROTECTED` | The app's preview or store-review account: its email address cannot be changed |
+| `VALIDATION` | `OWN_EMAIL_CHANGE_REFUSED` | The signed-in user cannot change their own email here; they use their account screen |
+| `NOT_FOUND` | | No such user in this workspace |
+| `FORBIDDEN` | | The signed-in person may not edit users |
+| `INTERNAL` (`err.status === 429`) | | Too many email changes in a short time; `err.retryable` is `true` |
+
+Every refusal from `EMAIL_TAKEN` down to `OWN_EMAIL_CHANGE_REFUSED`, except the `SCIM_MANAGED_*` pair, concerns the email only: a rename sent as `{ name }` alone still succeeds. `useUsers()` lists service accounts, so expect `SERVICE_ACCOUNT_PROTECTED`; better, do not offer an email field on a row whose `role` is `INTEGRATION`.
+
+Email changes are rate-limited per caller. The call is never retried automatically, so a 429 reaches you at once: ask the person to try again later rather than looping.
+
+`reason` is set on every `DirectoryError` the host explains, so `sendPasswordReset()` refusals read `err.reason === "USER_INACTIVE"` or `"NO_PASSWORD_CREDENTIAL"`. Additive: a host that does not offer `update` yet rejects the call with an `INTERNAL` `DirectoryError`.
 
 ### What's new in 0.194.0 (contract 1.155.0)
 
@@ -2236,7 +2297,7 @@ A widget that works but looks unfinished is only half done. `useTheme()` is the
 
 ## Managing app users from a widget
 
-`useUsers()` and `useGroups()` let a widget invite, deactivate, reactivate, and remove members, plus create / delete groups and add / remove their members. Two gates apply: the manifest must declare the scope (the static analyzer + the host's signed `X-Widget-Scopes` header agree), and the calling APP_USER must hold the matching `users.*` / `groups.*` capability (a SystemAcl grant the Studio admin issues via the Roles UI). A widget that declares `users.write:*` but whose caller lacks the grant gets a `DirectoryError` with `code: 'FORBIDDEN'` — surface that as a "you do not have permission" message.
+`useUsers()` and `useGroups()` let a widget invite, deactivate, reactivate, and remove members, change a member's name or sign-in email, plus create / delete groups and add / remove their members. `users.write:*` covers every edit, the name and sign-in email included (the member is told at their previous address when the email changes), so request it only for a surface meant for the people who administer the app. Two gates apply: the manifest must declare the scope (the static analyzer + the host's signed `X-Widget-Scopes` header agree), and the calling APP_USER must hold the matching `users.*` / `groups.*` capability (a SystemAcl grant the Studio admin issues via the Roles UI). A widget that declares `users.write:*` but whose caller lacks the grant gets a `DirectoryError` with `code: 'FORBIDDEN'` — surface that as a "you do not have permission" message.
 
 ```js
 import { Text, View, Pressable, useUsers, useGroups } from "@colixsystems/widget-sdk";

package/dist/card-style.js

@@ -5,7 +5,13 @@
 // Every resolver emits ONLY the fields that are set, so a widget's own base
 // style keeps whatever the author left alone.
 
-import { CONTRACT, isHexColor, mixHex, normaliseComponentGradient } from "./contract.js";
+import {
+  CONTRACT,
+  isHexColor,
+  normaliseComponentGradient,
+  componentGradientColors,
+  componentGradientMidpoint,
+} from "./contract.js";
 import { normaliseCornerRadius, cornerRadiusStyle } from "./corner-radius.js";
 import { normaliseSpacing, spacingStyle, isZeroSpacing } from "./spacing.js";
 import { flattenStyle } from "./flatten-style.js";
@@ -117,7 +123,7 @@ export function cardLayoutStyle(style) {
 export function gradientProps(value) {
   const gradient = normaliseComponentGradient(value);
   return gradient
-    ? { colors: [gradient.from, gradient.to], angle: gradient.angle }
+    ? { colors: componentGradientColors(gradient), angle: gradient.angle }
     : null;
 }
 
@@ -131,8 +137,13 @@ export function gradientProps(value) {
  */
 export function cardBackdrop(styles, gradient) {
   if (gradient) {
-    const [from, to] = gradient.colors;
-    return isOpaqueHex(from) && isOpaqueHex(to) ? mixHex(from, to, 0.5) : null;
+    const { colors } = gradient;
+    if (!colors.every(isOpaqueHex)) return null;
+    return componentGradientMidpoint({
+      from: colors[0],
+      via: colors.slice(1, -1),
+      to: colors[colors.length - 1],
+    });
   }
   const fill = flattenStyle(styles).backgroundColor;
   return isOpaqueHex(fill) ? fill : null;

package/dist/contract.cjs

@@ -332,6 +332,8 @@ const THEME_COMPONENT_GRADIENT = Object.freeze({
   angleMin: 0,
   angleMax: 359,
   defaultAngle: 180,
+  // sc-10685: middle colours allowed between the two ends (`via`).
+  maxViaStops: 3,
 });
 
 // REQ-THEME-LOOK: the app-wide SPACING MULTIPLIER. Layout spacing lives on the
@@ -1746,7 +1748,7 @@ const HOOKS = [
   // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUser administration. Returns
   // `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }`.
   // Reads need `users.read:*` scope; edit-style mutations (invite /
-  // deactivate / reactivate / sendPasswordReset) additionally need
+  // deactivate / reactivate / sendPasswordReset / update) additionally need
   // `users.write:*`, and the
   // destructive `remove` needs `users.delete:*` (SC-902). The `invite`
   // call accepts `{ email, name, groupIds? }` and returns the resulting
@@ -1760,26 +1762,52 @@ const HOOKS = [
     optionalArgs: ["query"],
     description:
       "AppUser administration via the injected directory-client at " +
-      "ctx.directory.users.{list,get,invite,deactivate,reactivate,sendPasswordReset}. " +
+      "ctx.directory.users.{list,get,invite,deactivate,reactivate,sendPasswordReset,update}. " +
       "Returns { users, loading, error, refetch, invite, deactivate, " +
-      "reactivate, remove, sendPasswordReset }. " +
+      "reactivate, remove, sendPasswordReset, update }. " +
       "list returns the { data, meta } envelope verbatim — the hook unwraps " +
       "res.data; rows are snake_case (is_active, …). Reads need users.read:* " +
       "scope; edit-style mutations (invite/deactivate/reactivate/" +
-      "sendPasswordReset) need users.write:*, and the destructive remove() " +
+      "sendPasswordReset/update) need users.write:*, and the destructive remove() " +
       "additionally needs users.delete:* (SC-902). The `invite` call accepts " +
       "{ email, name, group_ids? } and returns the resulting AppUserInvite row " +
       "(the email is sent by the host). sendPasswordReset(userId) mails the " +
       "standard self-serve reset link to that user's own registered address " +
       "and resolves { sent, email_masked } — never the token or the link, so " +
       "it cannot be used to sign in as them. It rejects with a DirectoryError " +
-      "coded USER_INACTIVE (deactivated) or NO_PASSWORD_CREDENTIAL (an " +
-      "INTEGRATION service account); surface those as an explanation rather " +
-      "than a generic failure.",
+      "whose reason is USER_INACTIVE (deactivated) or NO_PASSWORD_CREDENTIAL " +
+      "(an INTEGRATION service account); surface those as an explanation " +
+      "rather than a generic failure. update(userId, { name?, email? }) " +
+      "changes a user's name, email, or both (at least one key) and resolves " +
+      "{ id, name, email }; refetch() to refresh the list. An email change " +
+      "notifies the user at their previous address. users.write:* therefore " +
+      "lets a widget change a member's name and sign-in email: request it " +
+      "only for a surface meant for the people who administer the app. It " +
+      "rejects with a DirectoryError; code is the broad category and reason " +
+      "the specific refusal. code VALIDATION comes with reason " +
+      "INVALID_UPDATE (neither key), INVALID_NAME, INVALID_EMAIL, " +
+      "EMAIL_TAKEN (the address is not available), EMAIL_RESERVED (a " +
+      "reserved address), SCIM_MANAGED_NAME / SCIM_MANAGED_EMAIL (the " +
+      "profile is synced from an identity provider, so it is changed there), " +
+      "SSO_LINKED_EMAIL (the user signs in through an identity provider, so " +
+      "the email is changed there), SERVICE_ACCOUNT_PROTECTED (a service " +
+      "account's email cannot be changed), SEED_USER_PROTECTED / " +
+      "REVIEW_USER_PROTECTED (the app's preview or store-review account: " +
+      "its email address cannot be changed) or OWN_EMAIL_CHANGE_REFUSED " +
+      "(the signed-in user cannot change their own email here; they use " +
+      "their account screen). Every refusal from EMAIL_TAKEN on, except " +
+      "the SCIM_MANAGED pair, concerns the email only: a rename sent as " +
+      "{ name } alone still succeeds. code NOT_FOUND is an unknown user; " +
+      "code FORBIDDEN a caller without the users.write capability. Email " +
+      "changes are rate-limited per caller: an HTTP 429 arrives as code " +
+      "INTERNAL with status 429 and retryable true, and is never retried " +
+      "automatically, so ask the person to try again later. " +
+      "DirectoryError.reason is the host's specific refusal code, or null " +
+      "when it gave none; branch on it, and show error.message to the person.",
     returnShape: {
       users: "Array<{ id, name, email?, role, is_active }>  // snake_case rows; unwrapped from { data, meta }",
       loading: "boolean",
-      error: "DirectoryError | null  // { code, message, retryable }",
+      error: "DirectoryError | null  // { code, reason, message, retryable }",
       refetch: "() => Promise<void>",
       invite:
         "({ email, name, group_ids? }) => Promise<Invite>  // rejects with DirectoryError",
@@ -1788,6 +1816,8 @@ const HOOKS = [
       remove: "(userId) => Promise<void>  // rejects with DirectoryError",
       sendPasswordReset:
         "(userId) => Promise<{ sent, email_masked }>  // rejects with DirectoryError",
+      update:
+        "(userId, { name?, email? }) => Promise<{ id, name, email }>  // at least one key; an email change notifies the user at their previous address; rejects with DirectoryError (reason EMAIL_TAKEN, SERVICE_ACCOUNT_PROTECTED, …; status 429 when rate-limited)",
     },
     requiredContextSlice: ["directory.users"],
     scopes: ["users.read:*"],
@@ -5067,7 +5097,18 @@ const CONTRACT = deepFreeze({
   // 1.155.0: narrowing (sc-10566) — withdraws 1.144.0: `useUsers().invite`
   //    takes no `send_invitation` and always emails, invite rows carry no
   //    `sent_at`, and `not_sent` is no longer a status.
-  version: "1.155.0",
+  // 1.156.0: additive (sc-10429) — `useUsers()` gains
+  //    `update(userId, { name?, email? })`, gated on `users.write:*`; the
+  //    linter requires that scope for a `.update(` call beside `useUsers(`.
+  //    `DirectoryError` gains `reason`, the host's specific refusal code.
+  // 1.157.0: additive (sc-10685) — a component gradient takes an optional
+  //    `via` list of up to `themeComponentGradient.maxViaStops` middle colours
+  //    between `from` and `to`, evenly spaced. `normaliseComponentGradient`
+  //    returns it only when present, so a two-colour value normalises exactly
+  //    as before; a malformed `via` is dropped, or voids the gradient under the
+  //    new `{ strict: true }` option. New `componentGradientColors` / `componentGradientMidpoint`
+  //    read the paint list and the ink basis off a normalised gradient.
+  version: "1.157.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -5386,6 +5427,10 @@ const GRADIENT_HEX_RE = HEX_RE;
 
 /**
  * sc-3727 — normalise a component `gradient` to `{ from, to, angle }`, or `null`.
+ * sc-10685: plus `via`, the middle colours, only when the value carries some.
+ * A malformed `via` is dropped and the two ends still paint, so a stored value
+ * never loses its wash over it; `{ strict: true }` voids the gradient instead,
+ * for the boundaries that must refuse the write.
  *
  * 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
@@ -5394,7 +5439,7 @@ const GRADIENT_HEX_RE = HEX_RE;
  * hex grammar is also the injection guard — these stops are interpolated into
  * CSS and into generated export source.
  */
-function normaliseComponentGradient(raw) {
+function normaliseComponentGradient(raw, options) {
   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() : "";
@@ -5404,7 +5449,44 @@ function normaliseComponentGradient(raw) {
   // 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 };
+  const via = normaliseGradientVia(raw.via);
+  if (!via && options && options.strict) return null;
+  const gradient = { from, to, angle: ((deg % 360) + 360) % 360 };
+  if (via && via.length > 0) gradient.via = via;
+  return gradient;
+}
+
+// All or nothing: one bad middle colour and none of them paint. `null` = malformed.
+function normaliseGradientVia(raw) {
+  if (raw === undefined || raw === null) return [];
+  if (!Array.isArray(raw) || raw.length > THEME_COMPONENT_GRADIENT.maxViaStops) {
+    return null;
+  }
+  const via = [];
+  for (const item of raw) {
+    const stop = typeof item === "string" ? item.trim() : "";
+    if (!GRADIENT_HEX_RE.test(stop)) return null;
+    via.push(stop);
+  }
+  return via;
+}
+
+/**
+ * sc-10685 — a NORMALISED gradient's colours in paint order, evenly spaced:
+ * `[from, ...via, to]`. The one place both hosts read the list from.
+ */
+function componentGradientColors(gradient) {
+  return [gradient.from, ...(gradient.via || []), gradient.to];
+}
+
+/**
+ * sc-10685 — the colour halfway along a NORMALISED gradient, which is what
+ * text laid across it is contrasted against. Two colours: their mix, as before.
+ */
+function componentGradientMidpoint(gradient) {
+  const colors = componentGradientColors(gradient);
+  const middle = (colors.length - 1) / 2;
+  return mixHex(colors[Math.floor(middle)], colors[Math.ceil(middle)], 0.5);
 }
 
 // REQ-THEME-LOOK: coerce a theme's spacing scale into the usable band. Shared
@@ -5447,6 +5529,8 @@ module.exports = {
   INK_CONTRAST,
   gradientAngleToVector,
   normaliseComponentGradient,
+  componentGradientColors,
+  componentGradientMidpoint,
   isThemeColorTokenRef,
   parseThemeColorTokenRef,
   formatThemeColorTokenRef,

package/dist/contract.js

@@ -332,6 +332,8 @@ const THEME_COMPONENT_GRADIENT = Object.freeze({
   angleMin: 0,
   angleMax: 359,
   defaultAngle: 180,
+  // sc-10685: middle colours allowed between the two ends (`via`).
+  maxViaStops: 3,
 });
 
 // REQ-THEME-LOOK: the app-wide SPACING MULTIPLIER. Layout spacing lives on the
@@ -1746,7 +1748,7 @@ const HOOKS = [
   // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUser administration. Returns
   // `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }`.
   // Reads need `users.read:*` scope; edit-style mutations (invite /
-  // deactivate / reactivate / sendPasswordReset) additionally need
+  // deactivate / reactivate / sendPasswordReset / update) additionally need
   // `users.write:*`, and the
   // destructive `remove` needs `users.delete:*` (SC-902). The `invite`
   // call accepts `{ email, name, groupIds? }` and returns the resulting
@@ -1760,26 +1762,52 @@ const HOOKS = [
     optionalArgs: ["query"],
     description:
       "AppUser administration via the injected directory-client at " +
-      "ctx.directory.users.{list,get,invite,deactivate,reactivate,sendPasswordReset}. " +
+      "ctx.directory.users.{list,get,invite,deactivate,reactivate,sendPasswordReset,update}. " +
       "Returns { users, loading, error, refetch, invite, deactivate, " +
-      "reactivate, remove, sendPasswordReset }. " +
+      "reactivate, remove, sendPasswordReset, update }. " +
       "list returns the { data, meta } envelope verbatim — the hook unwraps " +
       "res.data; rows are snake_case (is_active, …). Reads need users.read:* " +
       "scope; edit-style mutations (invite/deactivate/reactivate/" +
-      "sendPasswordReset) need users.write:*, and the destructive remove() " +
+      "sendPasswordReset/update) need users.write:*, and the destructive remove() " +
       "additionally needs users.delete:* (SC-902). The `invite` call accepts " +
       "{ email, name, group_ids? } and returns the resulting AppUserInvite row " +
       "(the email is sent by the host). sendPasswordReset(userId) mails the " +
       "standard self-serve reset link to that user's own registered address " +
       "and resolves { sent, email_masked } — never the token or the link, so " +
       "it cannot be used to sign in as them. It rejects with a DirectoryError " +
-      "coded USER_INACTIVE (deactivated) or NO_PASSWORD_CREDENTIAL (an " +
-      "INTEGRATION service account); surface those as an explanation rather " +
-      "than a generic failure.",
+      "whose reason is USER_INACTIVE (deactivated) or NO_PASSWORD_CREDENTIAL " +
+      "(an INTEGRATION service account); surface those as an explanation " +
+      "rather than a generic failure. update(userId, { name?, email? }) " +
+      "changes a user's name, email, or both (at least one key) and resolves " +
+      "{ id, name, email }; refetch() to refresh the list. An email change " +
+      "notifies the user at their previous address. users.write:* therefore " +
+      "lets a widget change a member's name and sign-in email: request it " +
+      "only for a surface meant for the people who administer the app. It " +
+      "rejects with a DirectoryError; code is the broad category and reason " +
+      "the specific refusal. code VALIDATION comes with reason " +
+      "INVALID_UPDATE (neither key), INVALID_NAME, INVALID_EMAIL, " +
+      "EMAIL_TAKEN (the address is not available), EMAIL_RESERVED (a " +
+      "reserved address), SCIM_MANAGED_NAME / SCIM_MANAGED_EMAIL (the " +
+      "profile is synced from an identity provider, so it is changed there), " +
+      "SSO_LINKED_EMAIL (the user signs in through an identity provider, so " +
+      "the email is changed there), SERVICE_ACCOUNT_PROTECTED (a service " +
+      "account's email cannot be changed), SEED_USER_PROTECTED / " +
+      "REVIEW_USER_PROTECTED (the app's preview or store-review account: " +
+      "its email address cannot be changed) or OWN_EMAIL_CHANGE_REFUSED " +
+      "(the signed-in user cannot change their own email here; they use " +
+      "their account screen). Every refusal from EMAIL_TAKEN on, except " +
+      "the SCIM_MANAGED pair, concerns the email only: a rename sent as " +
+      "{ name } alone still succeeds. code NOT_FOUND is an unknown user; " +
+      "code FORBIDDEN a caller without the users.write capability. Email " +
+      "changes are rate-limited per caller: an HTTP 429 arrives as code " +
+      "INTERNAL with status 429 and retryable true, and is never retried " +
+      "automatically, so ask the person to try again later. " +
+      "DirectoryError.reason is the host's specific refusal code, or null " +
+      "when it gave none; branch on it, and show error.message to the person.",
     returnShape: {
       users: "Array<{ id, name, email?, role, is_active }>  // snake_case rows; unwrapped from { data, meta }",
       loading: "boolean",
-      error: "DirectoryError | null  // { code, message, retryable }",
+      error: "DirectoryError | null  // { code, reason, message, retryable }",
       refetch: "() => Promise<void>",
       invite:
         "({ email, name, group_ids? }) => Promise<Invite>  // rejects with DirectoryError",
@@ -1788,6 +1816,8 @@ const HOOKS = [
       remove: "(userId) => Promise<void>  // rejects with DirectoryError",
       sendPasswordReset:
         "(userId) => Promise<{ sent, email_masked }>  // rejects with DirectoryError",
+      update:
+        "(userId, { name?, email? }) => Promise<{ id, name, email }>  // at least one key; an email change notifies the user at their previous address; rejects with DirectoryError (reason EMAIL_TAKEN, SERVICE_ACCOUNT_PROTECTED, …; status 429 when rate-limited)",
     },
     requiredContextSlice: ["directory.users"],
     scopes: ["users.read:*"],
@@ -5063,7 +5093,18 @@ const CONTRACT = deepFreeze({
   // 1.155.0: narrowing (sc-10566) — withdraws 1.144.0: `useUsers().invite`
   //    takes no `send_invitation` and always emails, invite rows carry no
   //    `sent_at`, and `not_sent` is no longer a status.
-  version: "1.155.0",
+  // 1.156.0: additive (sc-10429) — `useUsers()` gains
+  //    `update(userId, { name?, email? })`, gated on `users.write:*`; the
+  //    linter requires that scope for a `.update(` call beside `useUsers(`.
+  //    `DirectoryError` gains `reason`, the host's specific refusal code.
+  // 1.157.0: additive (sc-10685) — a component gradient takes an optional
+  //    `via` list of up to `themeComponentGradient.maxViaStops` middle colours
+  //    between `from` and `to`, evenly spaced. `normaliseComponentGradient`
+  //    returns it only when present, so a two-colour value normalises exactly
+  //    as before; a malformed `via` is dropped, or voids the gradient under the
+  //    new `{ strict: true }` option. New `componentGradientColors` / `componentGradientMidpoint`
+  //    read the paint list and the ink basis off a normalised gradient.
+  version: "1.157.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -5382,6 +5423,10 @@ const GRADIENT_HEX_RE = HEX_RE;
 
 /**
  * sc-3727 — normalise a component `gradient` to `{ from, to, angle }`, or `null`.
+ * sc-10685: plus `via`, the middle colours, only when the value carries some.
+ * A malformed `via` is dropped and the two ends still paint, so a stored value
+ * never loses its wash over it; `{ strict: true }` voids the gradient instead,
+ * for the boundaries that must refuse the write.
  *
  * 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
@@ -5390,7 +5435,7 @@ const GRADIENT_HEX_RE = HEX_RE;
  * hex grammar is also the injection guard — these stops are interpolated into
  * CSS and into generated export source.
  */
-function normaliseComponentGradient(raw) {
+function normaliseComponentGradient(raw, options) {
   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() : "";
@@ -5400,7 +5445,44 @@ function normaliseComponentGradient(raw) {
   // 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 };
+  const via = normaliseGradientVia(raw.via);
+  if (!via && options && options.strict) return null;
+  const gradient = { from, to, angle: ((deg % 360) + 360) % 360 };
+  if (via && via.length > 0) gradient.via = via;
+  return gradient;
+}
+
+// All or nothing: one bad middle colour and none of them paint. `null` = malformed.
+function normaliseGradientVia(raw) {
+  if (raw === undefined || raw === null) return [];
+  if (!Array.isArray(raw) || raw.length > THEME_COMPONENT_GRADIENT.maxViaStops) {
+    return null;
+  }
+  const via = [];
+  for (const item of raw) {
+    const stop = typeof item === "string" ? item.trim() : "";
+    if (!GRADIENT_HEX_RE.test(stop)) return null;
+    via.push(stop);
+  }
+  return via;
+}
+
+/**
+ * sc-10685 — a NORMALISED gradient's colours in paint order, evenly spaced:
+ * `[from, ...via, to]`. The one place both hosts read the list from.
+ */
+function componentGradientColors(gradient) {
+  return [gradient.from, ...(gradient.via || []), gradient.to];
+}
+
+/**
+ * sc-10685 — the colour halfway along a NORMALISED gradient, which is what
+ * text laid across it is contrasted against. Two colours: their mix, as before.
+ */
+function componentGradientMidpoint(gradient) {
+  const colors = componentGradientColors(gradient);
+  const middle = (colors.length - 1) / 2;
+  return mixHex(colors[Math.floor(middle)], colors[Math.ceil(middle)], 0.5);
 }
 
 // REQ-THEME-LOOK: coerce a theme's spacing scale into the usable band. Shared
@@ -5443,6 +5525,8 @@ export {
   INK_CONTRAST,
   gradientAngleToVector,
   normaliseComponentGradient,
+  componentGradientColors,
+  componentGradientMidpoint,
   isThemeColorTokenRef,
   parseThemeColorTokenRef,
   formatThemeColorTokenRef,

package/dist/hooks.js

@@ -5394,6 +5394,8 @@ export function useFolderPermissions(folderId, options = {}) {
  *   - "INVITE_ONLY" — 409 from accept-invite-style flows where the tenant
  *                     is invite-only and the email is not on the list.
  *   - "INTERNAL"    — anything else (network, 5xx).
+ *
+ * `reason` is the host's own refusal code ("EMAIL_TAKEN", …) or null.
  */
 // sc-4986 — the directory refusals retrying the same call can never clear.
 const NON_RETRYABLE_DIRECTORY_CODES = new Set([
@@ -5415,6 +5417,10 @@ export class DirectoryError extends Error {
       opts && opts.retryable !== undefined
         ? Boolean(opts.retryable)
         : !NON_RETRYABLE_DIRECTORY_CODES.has(code);
+    this.reason =
+      opts && typeof opts.reason === "string" && opts.reason
+        ? opts.reason
+        : null;
     if (opts && opts.cause) this.cause = opts.cause;
   }
 }
@@ -5440,7 +5446,12 @@ function toDirectoryError(err) {
       (err && typeof err.message === "string"
         ? err.message
         : "Directory call failed"),
-    { cause: err, status, retryable: isRetryableDomainStatus(status) },
+    {
+      cause: err,
+      status,
+      retryable: isRetryableDomainStatus(status),
+      reason: envelopeCode,
+    },
   );
 }
 
@@ -5534,9 +5545,9 @@ export function useDirectory(query) {
  * REQ-USERMGMT / REQ-ACL-SYS M3 — AppUser administration hook.
  *
  * Returns `{ users, loading, error, refetch, invite, deactivate,
- * reactivate, remove }`. Reads through the injected
+ * reactivate, remove, sendPasswordReset, update }`. Reads through the injected
  * `@colixsystems/directory-client` at `ctx.directory.users.{list, get,
- * invite, deactivate, reactivate}` — `list` resolves to the `{ data, meta }`
+ * invite, deactivate, reactivate, sendPasswordReset, update}` — `list` resolves to the `{ data, meta }`
  * envelope VERBATIM, so we unwrap `res.data` (default `[]`). User rows are
  * snake_case (`id`, `name`, `email`, `role`, `is_active`, …) and bodies
  * (e.g. `{ email, name, group_ids? }`) pass through verbatim. `query` is an
@@ -5637,7 +5648,7 @@ export function useUsers(query) {
   // sc-5335: mail the self-serve reset link to a user who has locked
   // themselves out. Resolves `{ sent, email_masked }`; the host never returns
   // the token, so this cannot be used to sign in as that user. Rejects with a
-  // DirectoryError carrying `code` USER_INACTIVE or NO_PASSWORD_CREDENTIAL
+  // DirectoryError carrying `reason` USER_INACTIVE or NO_PASSWORD_CREDENTIAL
   // when the target cannot receive one.
   const sendPasswordReset = useCallback(async (userId) => {
     if (typeof usersRef.current.sendPasswordReset !== "function") {
@@ -5653,6 +5664,19 @@ export function useUsers(query) {
       throw toDirectoryError(err);
     }
   }, []);
+  // An email change notifies the user at their previous address.
+  const update = useCallback(async (userId, changes) => {
+    if (typeof usersRef.current.update !== "function") {
+      throw toDirectoryError(
+        new Error("useUsers: this host's directory client predates update"),
+      );
+    }
+    try {
+      return await usersRef.current.update(userId, changes);
+    } catch (err) {
+      throw toDirectoryError(err);
+    }
+  }, []);
 
   return {
     users,
@@ -5664,6 +5688,7 @@ export function useUsers(query) {
     reactivate,
     remove,
     sendPasswordReset,
+    update,
   };
 }
 

package/dist/index.d.ts

@@ -521,6 +521,8 @@ export interface DirectoryClient {
     invite(body: Record<string, unknown>): Promise<unknown>;
     deactivate(userId: string): Promise<unknown>;
     reactivate(userId: string): Promise<unknown>;
+    sendPasswordReset?(userId: string): Promise<unknown>;
+    update?(userId: string, body: Record<string, unknown>): Promise<unknown>;
   };
   groups: {
     list(query?: GroupsQuery): Promise<ListEnvelope>;
@@ -2316,12 +2318,15 @@ export class DirectoryError extends Error {
   status: number | null;
   /** sc-4986 — whether retrying the SAME call could plausibly succeed. */
   retryable: boolean;
+  /** The host's specific refusal code (`"EMAIL_TAKEN"`, …); null when none. */
+  reason: string | null;
   constructor(
     code: DirectoryError["code"],
     message: string,
     opts?: {
       status?: number | null;
       retryable?: boolean;
+      reason?: string | null;
       cause?: unknown;
     },
   );
@@ -2472,6 +2477,17 @@ export interface AppUserInviteRow {
   invited_by_studio_user_id?: string | null;
 }
 
+export interface UserProfileChanges {
+  name?: string;
+  email?: string;
+}
+
+export interface AppUserProfile {
+  id: string;
+  name: string | null;
+  email: string | null;
+}
+
 export interface UsersApi {
   users: AppUserRow[];
   loading: boolean;
@@ -2481,11 +2497,29 @@ export interface UsersApi {
   deactivate(userId: string): Promise<AppUserRow>;
   reactivate(userId: string): Promise<AppUserRow>;
   remove(userId: string): Promise<void>;
+  sendPasswordReset(
+    userId: string,
+  ): Promise<{ sent: boolean; email_masked: string }>;
+  /**
+   * Changes a user's name, sign-in email, or both; at least one key is
+   * required. An email change notifies the user at their previous address.
+   * Rejects with a `DirectoryError` whose `reason` names the refusal:
+   * `INVALID_UPDATE`, `INVALID_NAME`, `INVALID_EMAIL`, `EMAIL_TAKEN`,
+   * `EMAIL_RESERVED`, `SCIM_MANAGED_NAME`, `SCIM_MANAGED_EMAIL`,
+   * `SSO_LINKED_EMAIL`, `SERVICE_ACCOUNT_PROTECTED`, `SEED_USER_PROTECTED`,
+   * `REVIEW_USER_PROTECTED`, `OWN_EMAIL_CHANGE_REFUSED`. Email changes are
+   * rate-limited: a 429 rejects with `status: 429`, `code: "INTERNAL"`,
+   * `retryable: true`, and is never retried automatically.
+   */
+  update(
+    userId: string,
+    changes: UserProfileChanges,
+  ): Promise<AppUserProfile>;
 }
 
 /**
  * AppUser administration. Reads through the injected directory-client at
- * `ctx.directory.users.{list,get,invite,deactivate,reactivate}`. Reads
+ * `ctx.directory.users.{list,get,invite,deactivate,reactivate,sendPasswordReset,update}`. Reads
  * require the `users.read:*` scope in the manifest; mutations additionally
  * require `users.write:*`. Widgets that declare the scopes but whose calling
  * APP_USER lacks the corresponding SystemAcl `users.*` capability grant get a
@@ -3415,18 +3449,30 @@ export interface ComponentGradient {
   from: string;
   to: string;
   angle: number;
+  /** Middle colours between `from` and `to`. Present only when there are some. */
+  via?: string[];
 }
 
 /**
  * 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.
+ * An optional `via` list (at most `CONTRACT.themeComponentGradient.maxViaStops`
+ * hex colours) is kept as given. A malformed one is dropped and the two ends
+ * still paint; pass `{ strict: true }` to get null for it instead.
  * Shared by the theme-token coercion and the widget render path, so the same
  * value cannot resolve two ways.
  */
 export function normaliseComponentGradient(
   raw: unknown,
+  options?: { strict?: boolean },
 ): ComponentGradient | null;
 
+/** A normalised gradient's colours in paint order: `[from, ...via, to]`. */
+export function componentGradientColors(gradient: ComponentGradient): string[];
+
+/** The colour halfway along a normalised gradient: the basis for text ink. */
+export function componentGradientMidpoint(gradient: ComponentGradient): string;
+
 /** sc-8326 — the `theme:<path>` binding prefix, shared with the hosts' resolver. */
 export const THEME_TOKEN_REF_PREFIX: string;
 

package/dist/index.js

@@ -178,6 +178,8 @@ export {
   deriveAccentTints,
   gradientAngleToVector,
   normaliseComponentGradient,
+  componentGradientColors,
+  componentGradientMidpoint,
   isThemeColorTokenRef,
   parseThemeColorTokenRef,
   formatThemeColorTokenRef,

package/dist/index.native.js

@@ -171,6 +171,8 @@ export {
   deriveAccentTints,
   gradientAngleToVector,
   normaliseComponentGradient,
+  componentGradientColors,
+  componentGradientMidpoint,
   isThemeColorTokenRef,
   parseThemeColorTokenRef,
   formatThemeColorTokenRef,

package/dist/linter.cjs

@@ -657,6 +657,7 @@ const USER_MUTATION_METHODS = [
   // sc-5335 — mailing a reset link is edit-style, so it rides `users.write`
   // alongside deactivate rather than the destructive `users.delete`.
   "sendPasswordReset",
+  "update",
 ];
 // SC-902 — destructive user removal is gated on the dedicated
 // `users.delete` capability, NOT `users.write`. A widget that calls

package/dist/linter.js

@@ -587,7 +587,7 @@ function _translationApiRules(source) {
 // REQ-USERMGMT / REQ-ACL-SYS M3 — scope-required-for-user-mutation.
 //
 // A widget that calls `useUsers().invite()` / `.deactivate()` /
-// `.reactivate()` / `.sendPasswordReset()` / `.remove()` MUST declare
+// `.reactivate()` / `.sendPasswordReset()` / `.update()` / `.remove()` MUST declare
 // `users.write:*` in its
 // manifest's `requestedScopes`; similarly `useGroups()` mutation methods
 // require `groups.write:*`. The rule is enforced statically so a manifest
@@ -608,6 +608,7 @@ const USER_MUTATION_METHODS = [
   // sc-5335 — mailing a reset link is edit-style, so it rides `users.write`
   // alongside deactivate rather than the destructive `users.delete`.
   "sendPasswordReset",
+  "update",
 ];
 // SC-902 — destructive user removal is gated on the dedicated
 // `users.delete` capability, NOT `users.write`. A widget that calls

package/dist/theme-token-refs.js

@@ -148,7 +148,9 @@ function resolveAgainstSchema(schema, value, theme) {
 // VALUES — colours, sizes, enums — so an allowlisted `theme:` string in it can
 // only ever have been a binding. The depth cap keeps the walk bounded for the
 // structured style values (a gradient's stops, per-corner radii).
-const MAX_STYLE_DEPTH = 3;
+// sc-10685: 4, so a widget gradient's `via` list (style > gradient > via >
+// item) resolves like its two ends.
+const MAX_STYLE_DEPTH = 4;
 
 function resolveStyleBag(value, theme, depth) {
   if (typeof value === "string") {

package/package.json

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

package/src/contract.js

@@ -332,6 +332,8 @@ const THEME_COMPONENT_GRADIENT = Object.freeze({
   angleMin: 0,
   angleMax: 359,
   defaultAngle: 180,
+  // sc-10685: middle colours allowed between the two ends (`via`).
+  maxViaStops: 3,
 });
 
 // REQ-THEME-LOOK: the app-wide SPACING MULTIPLIER. Layout spacing lives on the
@@ -1746,7 +1748,7 @@ const HOOKS = [
   // REQ-USERMGMT / REQ-ACL-SYS M3 — AppUser administration. Returns
   // `{ users, loading, error, refetch, invite, deactivate, reactivate, remove }`.
   // Reads need `users.read:*` scope; edit-style mutations (invite /
-  // deactivate / reactivate / sendPasswordReset) additionally need
+  // deactivate / reactivate / sendPasswordReset / update) additionally need
   // `users.write:*`, and the
   // destructive `remove` needs `users.delete:*` (SC-902). The `invite`
   // call accepts `{ email, name, groupIds? }` and returns the resulting
@@ -1760,26 +1762,52 @@ const HOOKS = [
     optionalArgs: ["query"],
     description:
       "AppUser administration via the injected directory-client at " +
-      "ctx.directory.users.{list,get,invite,deactivate,reactivate,sendPasswordReset}. " +
+      "ctx.directory.users.{list,get,invite,deactivate,reactivate,sendPasswordReset,update}. " +
       "Returns { users, loading, error, refetch, invite, deactivate, " +
-      "reactivate, remove, sendPasswordReset }. " +
+      "reactivate, remove, sendPasswordReset, update }. " +
       "list returns the { data, meta } envelope verbatim — the hook unwraps " +
       "res.data; rows are snake_case (is_active, …). Reads need users.read:* " +
       "scope; edit-style mutations (invite/deactivate/reactivate/" +
-      "sendPasswordReset) need users.write:*, and the destructive remove() " +
+      "sendPasswordReset/update) need users.write:*, and the destructive remove() " +
       "additionally needs users.delete:* (SC-902). The `invite` call accepts " +
       "{ email, name, group_ids? } and returns the resulting AppUserInvite row " +
       "(the email is sent by the host). sendPasswordReset(userId) mails the " +
       "standard self-serve reset link to that user's own registered address " +
       "and resolves { sent, email_masked } — never the token or the link, so " +
       "it cannot be used to sign in as them. It rejects with a DirectoryError " +
-      "coded USER_INACTIVE (deactivated) or NO_PASSWORD_CREDENTIAL (an " +
-      "INTEGRATION service account); surface those as an explanation rather " +
-      "than a generic failure.",
+      "whose reason is USER_INACTIVE (deactivated) or NO_PASSWORD_CREDENTIAL " +
+      "(an INTEGRATION service account); surface those as an explanation " +
+      "rather than a generic failure. update(userId, { name?, email? }) " +
+      "changes a user's name, email, or both (at least one key) and resolves " +
+      "{ id, name, email }; refetch() to refresh the list. An email change " +
+      "notifies the user at their previous address. users.write:* therefore " +
+      "lets a widget change a member's name and sign-in email: request it " +
+      "only for a surface meant for the people who administer the app. It " +
+      "rejects with a DirectoryError; code is the broad category and reason " +
+      "the specific refusal. code VALIDATION comes with reason " +
+      "INVALID_UPDATE (neither key), INVALID_NAME, INVALID_EMAIL, " +
+      "EMAIL_TAKEN (the address is not available), EMAIL_RESERVED (a " +
+      "reserved address), SCIM_MANAGED_NAME / SCIM_MANAGED_EMAIL (the " +
+      "profile is synced from an identity provider, so it is changed there), " +
+      "SSO_LINKED_EMAIL (the user signs in through an identity provider, so " +
+      "the email is changed there), SERVICE_ACCOUNT_PROTECTED (a service " +
+      "account's email cannot be changed), SEED_USER_PROTECTED / " +
+      "REVIEW_USER_PROTECTED (the app's preview or store-review account: " +
+      "its email address cannot be changed) or OWN_EMAIL_CHANGE_REFUSED " +
+      "(the signed-in user cannot change their own email here; they use " +
+      "their account screen). Every refusal from EMAIL_TAKEN on, except " +
+      "the SCIM_MANAGED pair, concerns the email only: a rename sent as " +
+      "{ name } alone still succeeds. code NOT_FOUND is an unknown user; " +
+      "code FORBIDDEN a caller without the users.write capability. Email " +
+      "changes are rate-limited per caller: an HTTP 429 arrives as code " +
+      "INTERNAL with status 429 and retryable true, and is never retried " +
+      "automatically, so ask the person to try again later. " +
+      "DirectoryError.reason is the host's specific refusal code, or null " +
+      "when it gave none; branch on it, and show error.message to the person.",
     returnShape: {
       users: "Array<{ id, name, email?, role, is_active }>  // snake_case rows; unwrapped from { data, meta }",
       loading: "boolean",
-      error: "DirectoryError | null  // { code, message, retryable }",
+      error: "DirectoryError | null  // { code, reason, message, retryable }",
       refetch: "() => Promise<void>",
       invite:
         "({ email, name, group_ids? }) => Promise<Invite>  // rejects with DirectoryError",
@@ -1788,6 +1816,8 @@ const HOOKS = [
       remove: "(userId) => Promise<void>  // rejects with DirectoryError",
       sendPasswordReset:
         "(userId) => Promise<{ sent, email_masked }>  // rejects with DirectoryError",
+      update:
+        "(userId, { name?, email? }) => Promise<{ id, name, email }>  // at least one key; an email change notifies the user at their previous address; rejects with DirectoryError (reason EMAIL_TAKEN, SERVICE_ACCOUNT_PROTECTED, …; status 429 when rate-limited)",
     },
     requiredContextSlice: ["directory.users"],
     scopes: ["users.read:*"],
@@ -5063,7 +5093,18 @@ const CONTRACT = deepFreeze({
   // 1.155.0: narrowing (sc-10566) — withdraws 1.144.0: `useUsers().invite`
   //    takes no `send_invitation` and always emails, invite rows carry no
   //    `sent_at`, and `not_sent` is no longer a status.
-  version: "1.155.0",
+  // 1.156.0: additive (sc-10429) — `useUsers()` gains
+  //    `update(userId, { name?, email? })`, gated on `users.write:*`; the
+  //    linter requires that scope for a `.update(` call beside `useUsers(`.
+  //    `DirectoryError` gains `reason`, the host's specific refusal code.
+  // 1.157.0: additive (sc-10685) — a component gradient takes an optional
+  //    `via` list of up to `themeComponentGradient.maxViaStops` middle colours
+  //    between `from` and `to`, evenly spaced. `normaliseComponentGradient`
+  //    returns it only when present, so a two-colour value normalises exactly
+  //    as before; a malformed `via` is dropped, or voids the gradient under the
+  //    new `{ strict: true }` option. New `componentGradientColors` / `componentGradientMidpoint`
+  //    read the paint list and the ink basis off a normalised gradient.
+  version: "1.157.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -5382,6 +5423,10 @@ const GRADIENT_HEX_RE = HEX_RE;
 
 /**
  * sc-3727 — normalise a component `gradient` to `{ from, to, angle }`, or `null`.
+ * sc-10685: plus `via`, the middle colours, only when the value carries some.
+ * A malformed `via` is dropped and the two ends still paint, so a stored value
+ * never loses its wash over it; `{ strict: true }` voids the gradient instead,
+ * for the boundaries that must refuse the write.
  *
  * 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
@@ -5390,7 +5435,7 @@ const GRADIENT_HEX_RE = HEX_RE;
  * hex grammar is also the injection guard — these stops are interpolated into
  * CSS and into generated export source.
  */
-function normaliseComponentGradient(raw) {
+function normaliseComponentGradient(raw, options) {
   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() : "";
@@ -5400,7 +5445,44 @@ function normaliseComponentGradient(raw) {
   // 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 };
+  const via = normaliseGradientVia(raw.via);
+  if (!via && options && options.strict) return null;
+  const gradient = { from, to, angle: ((deg % 360) + 360) % 360 };
+  if (via && via.length > 0) gradient.via = via;
+  return gradient;
+}
+
+// All or nothing: one bad middle colour and none of them paint. `null` = malformed.
+function normaliseGradientVia(raw) {
+  if (raw === undefined || raw === null) return [];
+  if (!Array.isArray(raw) || raw.length > THEME_COMPONENT_GRADIENT.maxViaStops) {
+    return null;
+  }
+  const via = [];
+  for (const item of raw) {
+    const stop = typeof item === "string" ? item.trim() : "";
+    if (!GRADIENT_HEX_RE.test(stop)) return null;
+    via.push(stop);
+  }
+  return via;
+}
+
+/**
+ * sc-10685 — a NORMALISED gradient's colours in paint order, evenly spaced:
+ * `[from, ...via, to]`. The one place both hosts read the list from.
+ */
+function componentGradientColors(gradient) {
+  return [gradient.from, ...(gradient.via || []), gradient.to];
+}
+
+/**
+ * sc-10685 — the colour halfway along a NORMALISED gradient, which is what
+ * text laid across it is contrasted against. Two colours: their mix, as before.
+ */
+function componentGradientMidpoint(gradient) {
+  const colors = componentGradientColors(gradient);
+  const middle = (colors.length - 1) / 2;
+  return mixHex(colors[Math.floor(middle)], colors[Math.ceil(middle)], 0.5);
 }
 
 // REQ-THEME-LOOK: coerce a theme's spacing scale into the usable band. Shared
@@ -5443,6 +5525,8 @@ export {
   INK_CONTRAST,
   gradientAngleToVector,
   normaliseComponentGradient,
+  componentGradientColors,
+  componentGradientMidpoint,
   isThemeColorTokenRef,
   parseThemeColorTokenRef,
   formatThemeColorTokenRef,