@colixsystems/widget-sdk 0.185.0 → 0.187.0

package/README.md

@@ -20,7 +20,8 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useTheme()` | `{ colors, elevation, interaction, spacing, spacingScale, radii, typography, components, widgetStyles }` | `ctx.workspace.theme` — no scope. `elevation` is the shared depth scale (`none / sm / md / lg / xl`) you spread into a style; `colors` includes the accent's quiet tiers (`primarySoft` / `onPrimarySoft` / `primaryStrong`) and `loader`, the spinner colour for your own loading state. `components` is HOST-OWNED (the theme's per-component style tokens); the host has already folded it into your `props.style`, so read `useWidgetStyle()` and ignore this slice. |
 | **CORE** | `useWorkspaceCurrency()` | `{ currency, formatMoney }` | `ctx.workspace.currency` — no scope. The currency this workspace charges its app users in, resolved at RENDER time. Render every price as `formatMoney(minorUnits)` and never write a currency symbol or code into a widget: the owner can change it after the widget ships, and a baked label then contradicts the charge. |
 | **CORE** | `useWidgetStyle()` | `{ [styleField]: value }` | `ctx.props.style` — no scope. The author-set per-widget style values declared in `manifest.styleSchema`; apply each onto whatever element you choose. |
-| **CORE** | `useUser()` | `{ id, email, displayName, roles, groupIds }` | `ctx.user` (host-built context, **camelCase** — not a wire payload; `id` null when anonymous) — no scope |
+| **CORE** | `useUser()` | `{ id, email, displayName, photoUrl, roles, groupIds }` | `ctx.user` (host-built context, **camelCase** — not a wire payload; `id` null when anonymous) — no scope. `photoUrl` is the user's own profile photo as an absolute URL, or `null`. |
+| **CORE** | `useUserPhoto()` | `{ url, canEdit, upload, remove, uploading, error }` | `ctx.user` + the optional `ctx.account` — no scope. Changes the signed-in user's OWN profile photo. `canEdit` is false when nobody is signed in or the host cannot change it; `upload` / `remove` then reject. |
 | **CORE** | `useNavigation()` | `{ goTo, goBack, push, replace, back, currentRoute, openLink }` | `ctx.navigation` — no scope. `goTo(pageIdOrSlug, params?)` accepts a page UUID (a `pageRef` prop) **or its slug** (a row's page-key field) — both hosts resolve either (`openLink` for a link of unknown shape; a known external URL can also use the `Linking` primitive) |
 | **CORE** | `useRouteParams()` | `{ [paramKey]: value }` | `ctx.navigation.currentRoute.params` — no scope. The nav params the previous page passed via `goTo(pageId, params)`; the flat accessor for master→detail (read `recordId` on a detail page). Empty object when none. |
 | **CORE** | `usePageContext()` | `{ params, records }` | `ctx.pageContext` — no scope. The page's DECLARED parameters, resolved once by the host: `params` are coerced to their declared types, `records` holds the row already fetched for each `record` param (read it instead of fetching again). Both empty when the page declares none. |
@@ -74,7 +75,53 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.185.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.187.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.187.0 (contract 1.148.0)
+
+**App users have a profile photo, and a widget can show and change it.** `useUser()` now returns `photoUrl`, and the new `useUserPhoto()` hook lets the signed-in person replace or remove their own picture:
+
+```jsx
+import { useUser, useUserPhoto, Avatar, FilePicker, Pressable, Text, View } from "@colixsystems/widget-sdk";
+
+function ProfileHeader() {
+  const user = useUser();
+  const { canEdit, upload, remove, uploading, error } = useUserPhoto();
+
+  return (
+    <View>
+      <Avatar name={user.displayName} url={user.photoUrl} size="xl" />
+      {canEdit ? (
+        <FilePicker
+          accept="image/png,image/jpeg,image/webp"
+          disabled={uploading}
+          onPick={(file) => upload(file).catch(() => {})}
+        >
+          <Text>{uploading ? "Saving…" : "Change photo"}</Text>
+        </FilePicker>
+      ) : null}
+      {canEdit && user.photoUrl ? (
+        <Pressable disabled={uploading} onPress={() => remove().catch(() => {})}>
+          <Text>Remove photo</Text>
+        </Pressable>
+      ) : null}
+      {error ? <Text>{error.status === 413 ? "That image is too large." : "Could not save the photo."}</Text> : null}
+    </View>
+  );
+}
+```
+
+- **`useUser().photoUrl`** is an absolute URL you pass straight to `<Avatar url>` or `<Image source={{ uri }}>`. It is `null` when no photo is set, for anonymous visitors, and on a host that does not provide one. `<Avatar>` falls back to the name's initials, so the slot is never blank.
+- **`useUserPhoto()`** returns `{ url, canEdit, upload, remove, uploading, error }`. `url` is the same value as `useUser().photoUrl`. `upload(file)` takes the file `<FilePicker>` gives you, or `asset.file` from `useCamera()` / `useImageEditor()` — never the asset itself (a browser `File` on web, expo-file-system's `File` in the exported app) and resolves `{ photoUrl }`; `remove()` resolves `{ photoUrl: null }`. Once either resolves, every widget on the page reads the new `useUser().photoUrl`.
+- **The server crops the image to a square and resizes it.** PNG, JPEG or WebP, 10 MB at most. A refusal carries `err.status`: `413` too large, `415` unsupported type, `400` unreadable image.
+- **Check `canEdit` before offering the control.** It is false when nobody is signed in and on a host that cannot change the photo, such as the Builder canvas preview. `upload()` and `remove()` then reject (`"Sign in to change your photo"` / `"Changing your photo is not available here"`) and set `error`; the hook itself never throws at render.
+- **Only the signed-in user's own photo.** There is no way to read another user's photo: `useUsers()` and `useDirectory()` rows do not carry one.
+- **No new scope.** The hook only ever touches the caller's own account.
+
+A host backs the hook with the new optional `WidgetContext.account` slice, `{ setPhoto(file), removePhoto() }`. A host without it needs no change: `photoUrl` reads `null` and `canEdit` is false.
+### What's new in 0.186.0 (contract 1.147.0)
+
+**A page's top navigation bar puts its tabs on the left or the right; the centred option is gone.** `resolveTopBarTokens().tabAlignment` is now `"left"` | `"right"`. A `theme_config.topBar.tabAlignment` of `"center"` resolves to `"left"`, like any other unknown value, and the Studio drops it the next time the theme is saved. Host-integration surface only — no author-facing hook, prop, primitive, or manifest field changed.
 
 ### What's new in 0.185.0 (contract 1.146.0)
 

package/dist/contract.cjs

@@ -808,12 +808,39 @@ const HOOKS = [
       id: "string | null",
       email: "string | null",
       displayName: "string | null",
+      photoUrl:
+        "string | null  // the signed-in user's own profile photo, an absolute URL ready for <Avatar url> or <Image source={{ uri }}>; null when none is set, for anonymous visitors, and on a host that does not provide it",
       roles: "string[]",
       groupIds: "string[]",
     },
     requiredContextSlice: ["user"],
     scopes: null,
   },
+  {
+    name: "useUserPhoto",
+    signature: "useUserPhoto()",
+    description:
+      "Read and change the signed-in user's OWN profile photo. url mirrors useUser().photoUrl. upload(file) takes a browser " +
+      "File on web and expo-file-system's File on native: the file <FilePicker> gives you, or asset.file from useCamera() / " +
+      "useImageEditor() — NEVER the asset itself — and the host sends it; never build a FormData or call an endpoint yourself. The server crops " +
+      "the image to a square and resizes it. PNG, JPEG or WebP, 10 MB at most; a refusal carries err.status: 413 too large, " +
+      "415 unsupported type, 400 unreadable image. remove() clears the photo. After either resolves, useUser().photoUrl and " +
+      "url update in every widget on the page. canEdit is false when nobody is signed in and on a host that cannot change " +
+      "the photo (the Builder canvas preview): hide or disable the control then — upload() / remove() reject with an Error and " +
+      "set error rather than the hook throwing at render, as does upload() with no file. uploading is true while any call is in flight; error holds the last " +
+      "failure and clears on the next attempt. Needs no scope: it only ever touches the caller's own account. There is NO way " +
+      "to read another user's photo — useUsers() and useDirectory() rows carry none. Identical on web (Player) and the Expo export.",
+    returnShape: {
+      url: "string | null  // same value as useUser().photoUrl",
+      canEdit: "boolean  // signed in AND the host can change the photo",
+      upload: "(file: File) => Promise<{ photoUrl: string | null }>",
+      remove: "() => Promise<{ photoUrl: null }>",
+      uploading: "boolean",
+      error: "Error | null",
+    },
+    requiredContextSlice: ["user", "account.setPhoto", "account.removePhoto"],
+    scopes: null,
+  },
   {
     name: "useFill",
     signature: "useFill()",
@@ -2792,9 +2819,26 @@ const WIDGET_CONTEXT_SHAPE = {
   },
   user: {
     description:
-      "Signed-in user, host-built context object (camelCase: { id, email, displayName, roles, groupIds }) — NOT a wire payload, so it is the one camelCase island among the hooks. Not a data-client.",
+      "Signed-in user, host-built context object (camelCase: { id, email, displayName, photoUrl, roles, groupIds }) — NOT a wire payload, so it is the one camelCase island among the hooks. photoUrl is the user's own profile photo as an absolute URL, or null. Not a data-client.",
     required: true,
-    fields: { id: "string", email: "string", displayName: "string" },
+    fields: {
+      id: "string",
+      email: "string",
+      displayName: "string",
+      photoUrl: "string | null",
+    },
+  },
+  // Optional so a host that cannot change the photo needs no stub:
+  // useUserPhoto() reports canEdit false when it is absent.
+  account: {
+    description:
+      "Optional self-service account actions for the signed-in user: " +
+      "{ setPhoto(file) -> Promise<{ photoUrl }>, removePhoto() -> Promise<{ photoUrl: null }> }. " +
+      "Backs useUserPhoto(). The host performs the request AND updates its own session, so user.photoUrl changes for every " +
+      "widget. setPhoto takes a browser File on web and expo-file-system's File on native. Absent on a host that cannot " +
+      "change the photo (the Builder canvas preview), where useUserPhoto() degrades to canEdit: false rather than throwing.",
+    required: false,
+    fields: { setPhoto: "function", removePhoto: "function" },
   },
   workspace: {
     description:
@@ -4813,7 +4857,14 @@ const CONTRACT = deepFreeze({
   //    sized to their content. `<Button>` / `<ListRow>` read their `style`
   //    through the same flatten; their behaviour is unchanged. `<Stat>`'s
   //    icon, figure and delta wrap in a tile too narrow to hold them.
-  version: "1.146.0",
+  // 1.147.0: narrowing (sc-10123) — `resolveTopBarTokens().tabAlignment` is
+  //    "left" | "right". A stored "center" resolves to "left".
+  // 1.148.0: additive (sc-10142) — `useUser()` returns `photoUrl`, the
+  //    signed-in user's own profile photo (null when unset or not provided).
+  //    New `useUserPhoto()` changes it through the new OPTIONAL context
+  //    slice `account` ({ setPhoto, removePhoto }); a host without it reads
+  //    `canEdit: false`.
+  version: "1.148.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -808,12 +808,39 @@ const HOOKS = [
       id: "string | null",
       email: "string | null",
       displayName: "string | null",
+      photoUrl:
+        "string | null  // the signed-in user's own profile photo, an absolute URL ready for <Avatar url> or <Image source={{ uri }}>; null when none is set, for anonymous visitors, and on a host that does not provide it",
       roles: "string[]",
       groupIds: "string[]",
     },
     requiredContextSlice: ["user"],
     scopes: null,
   },
+  {
+    name: "useUserPhoto",
+    signature: "useUserPhoto()",
+    description:
+      "Read and change the signed-in user's OWN profile photo. url mirrors useUser().photoUrl. upload(file) takes a browser " +
+      "File on web and expo-file-system's File on native: the file <FilePicker> gives you, or asset.file from useCamera() / " +
+      "useImageEditor() — NEVER the asset itself — and the host sends it; never build a FormData or call an endpoint yourself. The server crops " +
+      "the image to a square and resizes it. PNG, JPEG or WebP, 10 MB at most; a refusal carries err.status: 413 too large, " +
+      "415 unsupported type, 400 unreadable image. remove() clears the photo. After either resolves, useUser().photoUrl and " +
+      "url update in every widget on the page. canEdit is false when nobody is signed in and on a host that cannot change " +
+      "the photo (the Builder canvas preview): hide or disable the control then — upload() / remove() reject with an Error and " +
+      "set error rather than the hook throwing at render, as does upload() with no file. uploading is true while any call is in flight; error holds the last " +
+      "failure and clears on the next attempt. Needs no scope: it only ever touches the caller's own account. There is NO way " +
+      "to read another user's photo — useUsers() and useDirectory() rows carry none. Identical on web (Player) and the Expo export.",
+    returnShape: {
+      url: "string | null  // same value as useUser().photoUrl",
+      canEdit: "boolean  // signed in AND the host can change the photo",
+      upload: "(file: File) => Promise<{ photoUrl: string | null }>",
+      remove: "() => Promise<{ photoUrl: null }>",
+      uploading: "boolean",
+      error: "Error | null",
+    },
+    requiredContextSlice: ["user", "account.setPhoto", "account.removePhoto"],
+    scopes: null,
+  },
   {
     name: "useFill",
     signature: "useFill()",
@@ -2788,9 +2815,26 @@ const WIDGET_CONTEXT_SHAPE = {
   },
   user: {
     description:
-      "Signed-in user, host-built context object (camelCase: { id, email, displayName, roles, groupIds }) — NOT a wire payload, so it is the one camelCase island among the hooks. Not a data-client.",
+      "Signed-in user, host-built context object (camelCase: { id, email, displayName, photoUrl, roles, groupIds }) — NOT a wire payload, so it is the one camelCase island among the hooks. photoUrl is the user's own profile photo as an absolute URL, or null. Not a data-client.",
     required: true,
-    fields: { id: "string", email: "string", displayName: "string" },
+    fields: {
+      id: "string",
+      email: "string",
+      displayName: "string",
+      photoUrl: "string | null",
+    },
+  },
+  // Optional so a host that cannot change the photo needs no stub:
+  // useUserPhoto() reports canEdit false when it is absent.
+  account: {
+    description:
+      "Optional self-service account actions for the signed-in user: " +
+      "{ setPhoto(file) -> Promise<{ photoUrl }>, removePhoto() -> Promise<{ photoUrl: null }> }. " +
+      "Backs useUserPhoto(). The host performs the request AND updates its own session, so user.photoUrl changes for every " +
+      "widget. setPhoto takes a browser File on web and expo-file-system's File on native. Absent on a host that cannot " +
+      "change the photo (the Builder canvas preview), where useUserPhoto() degrades to canEdit: false rather than throwing.",
+    required: false,
+    fields: { setPhoto: "function", removePhoto: "function" },
   },
   workspace: {
     description:
@@ -4809,7 +4853,14 @@ const CONTRACT = deepFreeze({
   //    sized to their content. `<Button>` / `<ListRow>` read their `style`
   //    through the same flatten; their behaviour is unchanged. `<Stat>`'s
   //    icon, figure and delta wrap in a tile too narrow to hold them.
-  version: "1.146.0",
+  // 1.147.0: narrowing (sc-10123) — `resolveTopBarTokens().tabAlignment` is
+  //    "left" | "right". A stored "center" resolves to "left".
+  // 1.148.0: additive (sc-10142) — `useUser()` returns `photoUrl`, the
+  //    signed-in user's own profile photo (null when unset or not provided).
+  //    New `useUserPhoto()` changes it through the new OPTIONAL context
+  //    slice `account` ({ setPhoto, removePhoto }); a host without it reads
+  //    `canEdit: false`.
+  version: "1.148.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/hooks.js

@@ -242,8 +242,10 @@ export function useWidgetStyle() {
 }
 
 /**
- * Returns the active end-user identity VERBATIM from the host, e.g.
- *   `{ id, email, displayName, roles, groupIds }` (camelCase — host-built context, not a wire payload).
+ * Returns the active end-user identity the host provides, e.g.
+ *   `{ id, email, displayName, photoUrl, roles, groupIds }` (camelCase — host-built context, not a wire payload).
+ * It is the host's own object, or a memoised copy carrying `photoUrl: null`
+ * when the host omits that field.
  *
  * `id` is `null` for anonymous visitors (and on the Studio canvas preview,
  * which renders widgets as if signed-out so the public branch shows). The
@@ -251,12 +253,112 @@ export function useWidgetStyle() {
  * fields; widgets read them directly. The current principal is host-provided
  * — this hook does NOT read a data-client.
  *
- * Use this to render the signed-in user's name in a header, branch on
- * roles, or stamp a created-by field.
+ * `photoUrl` is the user's own profile photo as an absolute URL, ready for
+ * `<Avatar url>` or `<Image source={{ uri }}>`; `null` when none is set, for
+ * anonymous visitors, and on a host that does not provide it.
+ *
+ * Use this to render the signed-in user's name and photo in a header, branch
+ * on roles, or stamp a created-by field.
  */
 export function useUser() {
   const ctx = useWidgetContextOrThrow("useUser");
-  return ctx.user;
+  const user = ctx.user;
+  // A host predating photoUrl omits it; the type promises null.
+  return useMemo(
+    () => (user && user.photoUrl === undefined ? { ...user, photoUrl: null } : user),
+    [user],
+  );
+}
+
+const USER_PHOTO_UNAVAILABLE = "Changing your photo is not available here";
+const USER_PHOTO_SIGNED_OUT = "Sign in to change your photo";
+const USER_PHOTO_NO_FILE = "useUserPhoto: file is required";
+
+/**
+ * Read and change the signed-in user's OWN profile photo. Returns
+ * `{ url, canEdit, upload, remove, uploading, error }`.
+ *
+ * `url` mirrors `useUser().photoUrl`. `upload(file)` takes a browser `File`
+ * on the web Player and expo-file-system's `File` on the Expo export: the
+ * file `<FilePicker>` gives you, or `asset.file` from `useCamera()` /
+ * `useImageEditor()` — never the asset itself. The server crops the image to
+ * a square and resizes it; PNG, JPEG or WebP, 10 MB at most. A refusal
+ * carries `err.status`: 413 too large, 415 unsupported type, 400 unreadable
+ * image. `uploading` is true while any `upload` / `remove` is in flight.
+ *
+ * The host owns the request and its own session (`ctx.account`), so a change
+ * reaches every widget's `useUser().photoUrl` at once. `ctx.account` is
+ * optional: where it is absent (the Builder canvas preview) or nobody is
+ * signed in, `canEdit` is false and `upload` / `remove` reject instead of the
+ * hook throwing at render.
+ *
+ * There is no way to read ANOTHER user's photo: `useUsers()` and
+ * `useDirectory()` rows carry none.
+ */
+export function useUserPhoto() {
+  const ctx = useWidgetContextOrThrow("useUserPhoto");
+  const user = ctx.user;
+  const account = ctx.account;
+  const hostCanEdit =
+    Boolean(account) &&
+    typeof account.setPhoto === "function" &&
+    typeof account.removePhoto === "function";
+  const signedIn = Boolean(user && user.id);
+  const canEdit = hostCanEdit && signedIn;
+  const url =
+    user && typeof user.photoUrl === "string" && user.photoUrl
+      ? user.photoUrl
+      : null;
+
+  const accountRef = useRef(null);
+  accountRef.current = hostCanEdit ? account : null;
+  const refusalRef = useRef(null);
+  refusalRef.current = !hostCanEdit
+    ? USER_PHOTO_UNAVAILABLE
+    : !signedIn
+      ? USER_PHOTO_SIGNED_OUT
+      : null;
+
+  const inFlightRef = useRef(0);
+  const [uploading, setUploading] = useState(false);
+  const [error, setError] = useState(null);
+
+  const change = useCallback(async (perform, invalidCall) => {
+    const refusal = refusalRef.current || invalidCall;
+    if (refusal) {
+      const err = new Error(refusal);
+      setError(err);
+      throw err;
+    }
+    inFlightRef.current += 1;
+    setUploading(true);
+    setError(null);
+    try {
+      return await perform(accountRef.current);
+    } catch (err) {
+      setError(err);
+      throw err;
+    } finally {
+      // upload() and remove() may overlap; the last one clears it.
+      inFlightRef.current -= 1;
+      setUploading(inFlightRef.current > 0);
+    }
+  }, []);
+
+  const upload = useCallback(
+    (file) =>
+      change(
+        (host) => host.setPhoto(file),
+        file ? null : USER_PHOTO_NO_FILE,
+      ),
+    [change],
+  );
+  const remove = useCallback(
+    () => change((host) => host.removePhoto()),
+    [change],
+  );
+
+  return { url, canEdit, upload, remove, uploading, error };
 }
 
 /**
@@ -3030,11 +3132,11 @@ export function useAgent(agentRef) {
           cancelled ||
           agentIdRef.current !== agentId ||
           resumeGenerationRef.current !== generation ||
-          suppressResumeRef.current ||
-          // A `send` that started during the resume already latched a thread.
-          // Overwriting it would orphan that PAID turn in a conversation
-          // nothing reads again, and point the next send somewhere else.
-          conversationRef.current
+          suppressResumeRef.current ||
+          // A `send` that started during the resume already latched a thread.
+          // Overwriting it would orphan that PAID turn in a conversation
+          // nothing reads again, and point the next send somewhere else.
+          conversationRef.current
         ) {
           return;
         }

package/dist/host.d.ts

@@ -292,7 +292,7 @@ export interface TopBarTokens {
    *  current tab so the page shows through it. */
   tabStyle: "underline" | "attached";
   /** Where the row's tabs sit across its width; `left` unless authored. */
-  tabAlignment: "left" | "center" | "right";
+  tabAlignment: "left" | "right";
   /** The column the tabs sit in: the whole bar, or the page content's. The
    *  bar's surface spans the full width either way. */
   tabRowWidth: "full" | "content";

package/dist/index.d.ts

@@ -646,9 +646,21 @@ export interface WidgetContext<TProps = unknown> {
     id: string | null;
     email: string | null;
     displayName: string | null;
+    /** The user's own profile photo as an absolute URL; null when none is set. */
+    photoUrl: string | null;
     roles: string[];
     groupIds: string[];
   };
+  /**
+   * Optional self-service account actions backing `useUserPhoto()`. The host
+   * performs the request and updates its own session, so `user.photoUrl`
+   * changes for every widget. Absent where the photo cannot be changed (the
+   * Builder canvas preview); `useUserPhoto().canEdit` is then false.
+   */
+  account?: {
+    setPhoto(file: UserPhotoFile): Promise<{ photoUrl: string | null }>;
+    removePhoto(): Promise<{ photoUrl: null }>;
+  };
   workspace: {
     id: string;
     slug: string;
@@ -1510,10 +1522,54 @@ export function useUser(): {
   id: string | null;
   email: string | null;
   displayName: string | null;
+  /**
+   * The user's own profile photo as an absolute URL, ready for `<Avatar url>`
+   * or `<Image source={{ uri }}>`. Null when none is set, for anonymous
+   * visitors, and on a host that does not provide it.
+   */
+  photoUrl: string | null;
   roles: string[];
   groupIds: string[];
 };
 
+/**
+ * The file `useUserPhoto().upload` takes: a browser `File` on the web Player
+ * and expo-file-system's `File` on the Expo export. It is the file
+ * `<FilePicker>` gives you, or `asset.file` from `useCamera()` /
+ * `useImageEditor()` — never the asset itself.
+ */
+export type UserPhotoFile = Blob & { name?: string };
+
+export interface UserPhotoApi {
+  /** Same value as `useUser().photoUrl`. */
+  url: string | null;
+  /** True when a user is signed in and the host can change the photo. */
+  canEdit: boolean;
+  /**
+   * Replace the photo. The server crops the image to a square and resizes it.
+   * PNG, JPEG or WebP, 10 MB at most. A refusal carries `status`: 413 too
+   * large, 415 unsupported type, 400 unreadable image. Rejects, and sets
+   * `error`, when `canEdit` is false or no file is passed.
+   */
+  upload(file: UserPhotoFile): Promise<{ photoUrl: string | null }>;
+  /** Clear the photo. Rejects when `canEdit` is false. */
+  remove(): Promise<{ photoUrl: null }>;
+  /** True while any `upload` or `remove` call is in flight. */
+  uploading: boolean;
+  /** The last failure; cleared by the next attempt. */
+  error: (Error & { status?: number }) | null;
+}
+
+/**
+ * Read and change the signed-in user's OWN profile photo. Never throws at
+ * render: where nobody is signed in, or the host cannot change the photo,
+ * `canEdit` is false and `upload` / `remove` reject. Pass `upload` the
+ * file `<FilePicker>` gives you, or `asset.file` from `useCamera()` /
+ * `useImageEditor()`. There is no way to read another user's photo;
+ * `useUsers()` and `useDirectory()` rows carry none.
+ */
+export function useUserPhoto(): UserPhotoApi;
+
 /**
  * REQ-LAY-08 — returns `true` when the host has sized this widget to fill its
  * layout slot's available height (a page-grid tile set to "Fill tile height",

package/dist/index.js

@@ -71,6 +71,7 @@ export {
   useTranslate,
   TranslateError,
   useUser,
+  useUserPhoto,
   useFill,
   useNavigation,
   useRouteParams,

package/dist/index.native.js

@@ -71,6 +71,7 @@ export {
   useTranslate,
   TranslateError,
   useUser,
+  useUserPhoto,
   useFill,
   useNavigation,
   useRouteParams,

package/dist/navigation.cjs

@@ -535,7 +535,7 @@ function resolveTopStripeLayout(theme) {
   };
 }
 
-const TAB_ALIGNMENTS = ["left", "center", "right"];
+const TAB_ALIGNMENTS = ["left", "right"];
 const TAB_ROW_WIDTHS = ["full", "content"];
 
 function resolveTopBarTokens(theme) {
@@ -569,8 +569,8 @@ function resolveTopBarTokens(theme) {
     // surface and meets the page beneath it, so the two read as one plane. Meaningless on a shape that draws no tab row — a host
     // reads it only where it has tabs to draw.
     tabStyle: topBar.tabStyle === "attached" ? "attached" : "underline",
-    // sc-10123: where the row's tabs sit across its width. Both hosts place
-    // them with flexible spacers rather than centring the row, so a row that
+    // sc-10123: which end of the row the tabs sit at. Both hosts place them
+    // with a flexible spacer rather than justifying the row, so a row that
     // overflows still scrolls from its first tab instead of clipping it.
     tabAlignment: TAB_ALIGNMENTS.includes(topBar.tabAlignment)
       ? topBar.tabAlignment

package/dist/navigation.js

@@ -526,7 +526,7 @@ export function resolveTopStripeLayout(theme) {
   };
 }
 
-const TAB_ALIGNMENTS = ["left", "center", "right"];
+const TAB_ALIGNMENTS = ["left", "right"];
 const TAB_ROW_WIDTHS = ["full", "content"];
 
 export function resolveTopBarTokens(theme) {
@@ -560,8 +560,8 @@ export function resolveTopBarTokens(theme) {
     // surface and meets the page beneath it, so the two read as one plane. Meaningless on a shape that draws no tab row — a host
     // reads it only where it has tabs to draw.
     tabStyle: topBar.tabStyle === "attached" ? "attached" : "underline",
-    // sc-10123: where the row's tabs sit across its width. Both hosts place
-    // them with flexible spacers rather than centring the row, so a row that
+    // sc-10123: which end of the row the tabs sit at. Both hosts place them
+    // with a flexible spacer rather than justifying the row, so a row that
     // overflows still scrolls from its first tab instead of clipping it.
     tabAlignment: TAB_ALIGNMENTS.includes(topBar.tabAlignment)
       ? topBar.tabAlignment

package/package.json

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