@colixsystems/widget-sdk 0.186.0 → 0.188.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,8 +75,75 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.186.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.188.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.188.0 (contract 1.149.0)
+
+**New linter rules for Leaflet maps: `leaflet-css-missing` and `leaflet-default-marker-icon`.** A widget's web entry is bundled with its own copy of Leaflet, and nothing else loads Leaflet's stylesheet. A map that skipped `import "leaflet/dist/leaflet.css"` drew a small patch of tiles inside an otherwise empty box, with its panes out of place and its markers invisible. Even with the stylesheet, Leaflet looks up its default marker image relative to the page, which 404s inside a widget, so a `<Marker>` with no `icon` showed no pin.
+
+- **`leaflet-css-missing` (severity `error`).** A file that imports `leaflet` or `react-leaflet` code (an image-only import does not count) must also import `"leaflet/dist/leaflet.css"`. The bundler turns that import into an injected `<style>`. Import it in every file that uses Leaflet; the bundler includes it once.
+- **`leaflet-default-marker-icon` (severity `warning`).** A react-leaflet `<Marker>` with no `icon` prop. Import the marker PNGs (the bundler inlines them as data URLs), build the icon once at module scope and pass it in:
+
+```jsx
+import L from "leaflet";
+import "leaflet/dist/leaflet.css";
+import markerIcon from "leaflet/dist/images/marker-icon.png";
+import markerIcon2x from "leaflet/dist/images/marker-icon-2x.png";
+import markerShadow from "leaflet/dist/images/marker-shadow.png";
+
+const pin = L.icon({
+  iconUrl: markerIcon, iconRetinaUrl: markerIcon2x, shadowUrl: markerShadow,
+  iconSize: [25, 41], iconAnchor: [12, 41], popupAnchor: [1, -34], shadowSize: [41, 41],
+});
+// <Marker position={[lat, lng]} icon={pin} />
+```
+
+  It is a warning because a widget that configures `L.Icon.Default` itself is fine, and is not flagged. `<CircleMarker>` needs no icon.
+
+The `leaflet` and `react-leaflet` entries in `CONTRACT.vettedImports` now say the same. Comments are not scanned, so documenting the pattern is safe.
+
+### 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.

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:
@@ -3252,13 +3296,16 @@ const VETTED_IMPORTS = [
     platforms: ["web"],
     category: "geo",
     description:
-      "Web-only mapping library. Use alongside react-leaflet in widget.web.jsx as the web counterpart to react-native-maps.",
+      "Web-only mapping library. Use alongside react-leaflet in widget.web.jsx as the web counterpart to react-native-maps. " +
+      'Every file that imports it must also `import "leaflet/dist/leaflet.css"` (the linter enforces it), and a marker needs an ' +
+      "explicit `L.icon` built from the imported `leaflet/dist/images/*.png`: Leaflet's default icon cannot resolve its image inside a bundle.",
   },
   {
     specifier: "react-leaflet",
     platforms: ["web"],
     category: "geo",
-    description: "React bindings for leaflet. Web-only.",
+    description:
+      'React bindings for leaflet. Web-only. Import "leaflet/dist/leaflet.css" alongside it and pass `icon` to every <Marker>.',
   },
   {
     specifier: "expo-audio",
@@ -4815,7 +4862,16 @@ const CONTRACT = deepFreeze({
   //    icon, figure and delta wrap in a tile too narrow to hold them.
   // 1.147.0: narrowing (sc-10123) — `resolveTopBarTokens().tabAlignment` is
   //    "left" | "right". A stored "center" resolves to "left".
-  version: "1.147.0",
+  // 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`.
+  // 1.149.0: narrowing (sc-10466) — new linter rule `leaflet-css-missing`
+  //    (error): a file importing leaflet / react-leaflet must import
+  //    "leaflet/dist/leaflet.css". `leaflet-default-marker-icon` (warning)
+  //    flags a react-leaflet <Marker> with no `icon`.
+  version: "1.149.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:
@@ -3248,13 +3292,16 @@ const VETTED_IMPORTS = [
     platforms: ["web"],
     category: "geo",
     description:
-      "Web-only mapping library. Use alongside react-leaflet in widget.web.jsx as the web counterpart to react-native-maps.",
+      "Web-only mapping library. Use alongside react-leaflet in widget.web.jsx as the web counterpart to react-native-maps. " +
+      'Every file that imports it must also `import "leaflet/dist/leaflet.css"` (the linter enforces it), and a marker needs an ' +
+      "explicit `L.icon` built from the imported `leaflet/dist/images/*.png`: Leaflet's default icon cannot resolve its image inside a bundle.",
   },
   {
     specifier: "react-leaflet",
     platforms: ["web"],
     category: "geo",
-    description: "React bindings for leaflet. Web-only.",
+    description:
+      'React bindings for leaflet. Web-only. Import "leaflet/dist/leaflet.css" alongside it and pass `icon` to every <Marker>.',
   },
   {
     specifier: "expo-audio",
@@ -4811,7 +4858,16 @@ const CONTRACT = deepFreeze({
   //    icon, figure and delta wrap in a tile too narrow to hold them.
   // 1.147.0: narrowing (sc-10123) — `resolveTopBarTokens().tabAlignment` is
   //    "left" | "right". A stored "center" resolves to "left".
-  version: "1.147.0",
+  // 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`.
+  // 1.149.0: narrowing (sc-10466) — new linter rule `leaflet-css-missing`
+  //    (error): a file importing leaflet / react-leaflet must import
+  //    "leaflet/dist/leaflet.css". `leaflet-default-marker-icon` (warning)
+  //    flags a react-leaflet <Marker> with no `icon`.
+  version: "1.149.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/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/linter.cjs

@@ -252,7 +252,9 @@ function _packageRoot(spec) {
   const parts = spec.split("/");
   // A traversal / empty segment is a non-canonical specifier — never resolve it
   // to a vetted root, or "leaflet/../evil" would pass the gate as "leaflet".
-  if (parts.some((p) => p === "" || p === "." || p === "..")) return null;
+  if (parts.some((p) => p === "" || p === "." || p === ".." || p.includes("\\"))) {
+    return null;
+  }
   return spec.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0];
 }
 
@@ -336,6 +338,87 @@ function _importRules(source, manifest) {
   return findings;
 }
 
+// sc-10466 — Leaflet is bundled per widget; no host supplies its stylesheet.
+// Without `leaflet/dist/leaflet.css` the tiles, panes and markers are
+// unpositioned: a patch of map in an empty box, and no visible pin. And once
+// the CSS is injected inline its default marker image resolves against the
+// page URL and 404s, so a `<Marker>` needs an explicit `icon`.
+const _LEAFLET_ROOTS = new Set(["leaflet", "react-leaflet"]);
+const _LEAFLET_CSS = "leaflet/dist/leaflet.css";
+const _MARKER_TAG_RE = /<Marker\b/g;
+
+const _ASSET_SPECIFIER_RE = /\.(css|png|jpe?g|gif)$/i;
+const _ICON_DEFAULT_CONFIGURED_RE =
+  /\bIcon\s*\.\s*Default\s*(\.\s*mergeOptions\s*\(|\.\s*imagePath\s*=)/;
+
+function _lineAt(code, index) {
+  return code.slice(0, index).split(/\r?\n/).length;
+}
+
+function _leafletRules(source) {
+  const code = _stripNonCode(source, { keepStrings: true });
+  const sourceLines = source.split(/\r?\n/);
+  let firstLeafletLine = 0;
+  let importsCss = false;
+  let importsReactLeaflet = false;
+  // Whole-source scan: a Prettier-wrapped import spans several lines.
+  IMPORT_SPECIFIER_RE.lastIndex = 0;
+  let m;
+  while ((m = IMPORT_SPECIFIER_RE.exec(code))) {
+    const spec = m[1];
+    if (spec === _LEAFLET_CSS) importsCss = true;
+    const root = _packageRoot(spec);
+    if (!_LEAFLET_ROOTS.has(root) || _ASSET_SPECIFIER_RE.test(spec)) continue;
+    if (root === "react-leaflet") importsReactLeaflet = true;
+    if (!firstLeafletLine) firstLeafletLine = _lineAt(code, m.index + m[0].length);
+  }
+  IMPORT_SPECIFIER_RE.lastIndex = 0;
+  if (!firstLeafletLine) return [];
+  const findings = [];
+  if (!importsCss) {
+    findings.push({
+      rule: "leaflet-css-missing",
+      severity: "error",
+      label:
+        `this file uses Leaflet but never imports its stylesheet — without ` +
+        `it the map draws a partial patch of tiles inside an empty box and ` +
+        `markers are invisible. Add \`import "${_LEAFLET_CSS}";\` to this file.`,
+      line: firstLeafletLine,
+      snippet: (sourceLines[firstLeafletLine - 1] || "").trim().slice(0, 200),
+    });
+  }
+  if (
+    !importsReactLeaflet ||
+    _ICON_DEFAULT_CONFIGURED_RE.test(_stripNonCode(source))
+  ) {
+    return findings;
+  }
+  _MARKER_TAG_RE.lastIndex = 0;
+  let tag;
+  while ((tag = _MARKER_TAG_RE.exec(code))) {
+    const end = _jsxOpenTagEnd(code, tag.index + tag[0].length);
+    if (/(^|\s)icon\s*=/.test(code.slice(tag.index, end))) continue;
+    const line = _lineAt(code, tag.index);
+    findings.push({
+      rule: "leaflet-default-marker-icon",
+      severity: "warning",
+      label:
+        `<Marker> uses Leaflet's default icon, whose image path cannot ` +
+        `resolve inside a widget bundle, so the pin does not show. Import the ` +
+        `images (\`import markerIcon from "leaflet/dist/images/marker-icon.png"\`, ` +
+        `plus marker-icon-2x.png and marker-shadow.png), build ` +
+        `\`L.icon({ iconUrl, iconRetinaUrl, shadowUrl, iconSize: [25, 41], ` +
+        `iconAnchor: [12, 41] })\` once at module scope, and pass it as ` +
+        `\`icon={…}\`. Warning only — a widget that sets \`L.Icon.Default\` ` +
+        `itself (\`mergeOptions\` / \`imagePath\`) is not flagged.`,
+      line,
+      snippet: (sourceLines[line - 1] || "").trim().slice(0, 200),
+    });
+    _MARKER_TAG_RE.lastIndex = end;
+  }
+  return findings;
+}
+
 // Explicit opt-out. A widget legitimately calling a THIRD-PARTY API with a
 // relative path against an `axios` baseURL cannot avoid the substring match,
 // and post-sc-3589 an unavoidable finding burns AI repair turns on correct
@@ -1853,6 +1936,7 @@ function lintSource(source, options) {
       severity: f.severity || "error",
     })),
   );
+  findings.push(..._leafletRules(source));
   findings.push(..._hostApiUrlRules(source));
   // sc-6970 — soft warning: HTML markup spliced into a content string.
   findings.push(..._htmlInContentRules(source));

package/dist/linter.js

@@ -135,7 +135,9 @@ function _packageRoot(spec) {
   const parts = spec.split("/");
   // A traversal / empty segment is a non-canonical specifier — never resolve it
   // to a vetted root, or "leaflet/../evil" would pass the gate as "leaflet".
-  if (parts.some((p) => p === "" || p === "." || p === "..")) return null;
+  if (parts.some((p) => p === "" || p === "." || p === ".." || p.includes("\\"))) {
+    return null;
+  }
   return spec.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0];
 }
 
@@ -229,6 +231,87 @@ function _importRules(source, manifest) {
   return findings;
 }
 
+// sc-10466 — Leaflet is bundled per widget; no host supplies its stylesheet.
+// Without `leaflet/dist/leaflet.css` the tiles, panes and markers are
+// unpositioned: a patch of map in an empty box, and no visible pin. And once
+// the CSS is injected inline its default marker image resolves against the
+// page URL and 404s, so a `<Marker>` needs an explicit `icon`.
+const _LEAFLET_ROOTS = new Set(["leaflet", "react-leaflet"]);
+const _LEAFLET_CSS = "leaflet/dist/leaflet.css";
+const _MARKER_TAG_RE = /<Marker\b/g;
+
+const _ASSET_SPECIFIER_RE = /\.(css|png|jpe?g|gif)$/i;
+const _ICON_DEFAULT_CONFIGURED_RE =
+  /\bIcon\s*\.\s*Default\s*(\.\s*mergeOptions\s*\(|\.\s*imagePath\s*=)/;
+
+function _lineAt(code, index) {
+  return code.slice(0, index).split(/\r?\n/).length;
+}
+
+function _leafletRules(source) {
+  const code = _stripNonCode(source, { keepStrings: true });
+  const sourceLines = source.split(/\r?\n/);
+  let firstLeafletLine = 0;
+  let importsCss = false;
+  let importsReactLeaflet = false;
+  // Whole-source scan: a Prettier-wrapped import spans several lines.
+  IMPORT_SPECIFIER_RE.lastIndex = 0;
+  let m;
+  while ((m = IMPORT_SPECIFIER_RE.exec(code))) {
+    const spec = m[1];
+    if (spec === _LEAFLET_CSS) importsCss = true;
+    const root = _packageRoot(spec);
+    if (!_LEAFLET_ROOTS.has(root) || _ASSET_SPECIFIER_RE.test(spec)) continue;
+    if (root === "react-leaflet") importsReactLeaflet = true;
+    if (!firstLeafletLine) firstLeafletLine = _lineAt(code, m.index + m[0].length);
+  }
+  IMPORT_SPECIFIER_RE.lastIndex = 0;
+  if (!firstLeafletLine) return [];
+  const findings = [];
+  if (!importsCss) {
+    findings.push({
+      rule: "leaflet-css-missing",
+      severity: "error",
+      label:
+        `this file uses Leaflet but never imports its stylesheet — without ` +
+        `it the map draws a partial patch of tiles inside an empty box and ` +
+        `markers are invisible. Add \`import "${_LEAFLET_CSS}";\` to this file.`,
+      line: firstLeafletLine,
+      snippet: (sourceLines[firstLeafletLine - 1] || "").trim().slice(0, 200),
+    });
+  }
+  if (
+    !importsReactLeaflet ||
+    _ICON_DEFAULT_CONFIGURED_RE.test(_stripNonCode(source))
+  ) {
+    return findings;
+  }
+  _MARKER_TAG_RE.lastIndex = 0;
+  let tag;
+  while ((tag = _MARKER_TAG_RE.exec(code))) {
+    const end = _jsxOpenTagEnd(code, tag.index + tag[0].length);
+    if (/(^|\s)icon\s*=/.test(code.slice(tag.index, end))) continue;
+    const line = _lineAt(code, tag.index);
+    findings.push({
+      rule: "leaflet-default-marker-icon",
+      severity: "warning",
+      label:
+        `<Marker> uses Leaflet's default icon, whose image path cannot ` +
+        `resolve inside a widget bundle, so the pin does not show. Import the ` +
+        `images (\`import markerIcon from "leaflet/dist/images/marker-icon.png"\`, ` +
+        `plus marker-icon-2x.png and marker-shadow.png), build ` +
+        `\`L.icon({ iconUrl, iconRetinaUrl, shadowUrl, iconSize: [25, 41], ` +
+        `iconAnchor: [12, 41] })\` once at module scope, and pass it as ` +
+        `\`icon={…}\`. Warning only — a widget that sets \`L.Icon.Default\` ` +
+        `itself (\`mergeOptions\` / \`imagePath\`) is not flagged.`,
+      line,
+      snippet: (sourceLines[line - 1] || "").trim().slice(0, 200),
+    });
+    _MARKER_TAG_RE.lastIndex = end;
+  }
+  return findings;
+}
+
 // REQ-WSDK-PLATFORM §3.5: soft warning when source contains host-API URL
 // substrings. `severity: "warning"` so a HUMAN-authored submission still
 // publishes and the marketplace review queue flags it for a human pass.
@@ -1925,6 +2008,7 @@ export function lintSource(source, options) {
       severity: f.severity || "error",
     })),
   );
+  findings.push(..._leafletRules(source));
   // REQ-WSDK-PLATFORM §3.5: soft host-API URL warning (does not block).
   findings.push(..._hostApiUrlRules(source));
   // sc-6970 — soft warning: HTML markup spliced into a content string.

package/package.json

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