@poly-x/react 0.1.1 → 0.3.0

package/dist/index.mjs

@@ -1,7 +1,8 @@
 "use client";
-import { AuthClient, FetchTransport, InMemoryLock, InMemoryPkceStore, InMemorySessionChannel, InMemorySessionStore, createSessionEngine, generatePkce, randomState, resolveConfig } from "@poly-x/core";
+import { AuthClient, FetchTransport, InMemoryLock, InMemoryPkceStore, InMemorySessionChannel, InMemorySessionStore, PROFILE_FIELDS, buildProfileUpdate, conflictField, createSessionEngine, generatePkce, parseAuthorizeOutcome, randomState, resolveConfig, validateProfileDraft, validateProfileImage } from "@poly-x/core";
 import { Children, Fragment, createContext, isValidElement, useCallback, useContext, useEffect, useId, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+import { createPortal } from "react-dom";
 //#region src/auth-channel.ts
 var BroadcastAuthChannel = class {
 	supported;
@@ -198,7 +199,7 @@ var BroadcastChannelSessionChannel = class {
 //#endregion
 //#region src/seams/session-storage-pkce.ts
 const KEY_PREFIX = "poly-x.pkce.";
-function hasSessionStorage() {
+function hasSessionStorage$1() {
 	try {
 		return typeof sessionStorage !== "undefined";
 	} catch {
@@ -214,7 +215,7 @@ function hasSessionStorage() {
 var SessionStoragePkceStore = class {
 	fallback;
 	constructor() {
-		if (!hasSessionStorage()) this.fallback = new InMemoryPkceStore();
+		if (!hasSessionStorage$1()) this.fallback = new InMemoryPkceStore();
 	}
 	save(entry) {
 		if (this.fallback) return this.fallback.save(entry);
@@ -479,6 +480,198 @@ function getBffSessionStore() {
 	return store;
 }
 //#endregion
+//#region src/warm-hop.ts
+/**
+* Warm hop — the browser half (F027/F028 · FR-HOP-1…6, FR-FALL-1…3, FR-SWITCH-1…7).
+*
+* The probe is made **from here, by the browser**, and that is not a style choice. The
+* platform resolves the ecosystem session from a cookie on its own domain; a server-side
+* request carries no browser cookie, so it would be told "sign-in required" every time and
+* the whole feature would look built while never working. `@poly-x/core` refuses the
+* server-side call outright for that reason.
+*
+* The three steps, and why the credential stays safe throughout:
+*
+*   1. Ask our own BFF to prepare (`/api/polyx/hop`). It mints PKCE and keeps the verifier
+*      in an httpOnly cookie; we receive only a URL.
+*   2. Call that URL with `credentials:"include"` so the browser attaches the ecosystem
+*      cookie. This is the one request that must not come from a server.
+*   3. Hand the resulting `code` back to our BFF (`/api/polyx/hop-complete`), which does the
+*      exchange. The code is worthless to anyone who intercepts it — the PKCE verifier that
+*      redeems it never left the server — so a page holding it briefly is not a custody leak.
+*
+* Nothing here navigates. That matters beyond tidiness: this exact flow produced a redirect
+* loop in a hand-rolled implementation once already, and a fetch cannot loop.
+*/
+const HOP_ENDPOINT = "/api/polyx/hop";
+const HOP_COMPLETE_ENDPOINT = "/api/polyx/hop-complete";
+/**
+* How long to wait for the silent attempt before giving up and showing the form.
+*
+* A guess, and labelled as one. The requirement it serves (FR-FALL-2) is that a slow or
+* dead platform must never leave someone watching a spinner — and for that, *any* bound
+* beats none. The person this protects is already signed out and gains nothing from
+* waiting, so the bound is deliberately short. Override it if you have measured yours.
+*/
+const WARM_HOP_TIMEOUT_MS = 5e3;
+/**
+* Survives navigation on purpose (FR-FALL-3).
+*
+* The fall-back from a failed attempt renders the sign-in page, which in most apps is a
+* route change — so a guard held in React state or a module variable is reset exactly when
+* it is needed. `sessionStorage` is scoped to the tab and cleared when it closes, which is
+* the same lifetime as "this entry".
+*/
+const ATTEMPTED_KEY = "polyx.warmHop.attempted";
+function hasSessionStorage() {
+	try {
+		return typeof sessionStorage !== "undefined";
+	} catch {
+		return false;
+	}
+}
+/** Has an automatic attempt already run in this tab? */
+function warmHopAttempted() {
+	if (!hasSessionStorage()) return false;
+	try {
+		return sessionStorage.getItem(ATTEMPTED_KEY) === "1";
+	} catch {
+		return false;
+	}
+}
+function markWarmHopAttempted() {
+	if (!hasSessionStorage()) return;
+	try {
+		sessionStorage.setItem(ATTEMPTED_KEY, "1");
+	} catch {}
+}
+/** Clear the once-per-entry marker. Exported for sign-out, so the next sign-in may try again. */
+function resetWarmHop() {
+	if (!hasSessionStorage()) return;
+	try {
+		sessionStorage.removeItem(ATTEMPTED_KEY);
+	} catch {}
+}
+async function postJson(url, body, signal) {
+	return fetch(url, {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify(body ?? {}),
+		signal,
+		credentials: "same-origin"
+	});
+}
+/**
+* Run one silent attempt and report what the platform said.
+*
+* Never throws: every failure resolves to `failed`, because a caller in the middle of
+* rendering a sign-in page has no better answer than "show the form" and an exception
+* there is how a blank screen happens.
+*/
+async function attemptWarmHop(options = {}) {
+	if (typeof window === "undefined") return {
+		status: "failed",
+		reason: "warm hop attempted outside a browser"
+	};
+	const controller = new AbortController();
+	const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? 5e3);
+	try {
+		const prepared = await postJson(HOP_ENDPOINT, options.workspace ? { tenantId: options.workspace } : {}, controller.signal);
+		if (!prepared.ok) return {
+			status: "failed",
+			reason: `hop preparation failed (${prepared.status})`
+		};
+		const { authorizeUrl } = await prepared.json();
+		if (!authorizeUrl) return {
+			status: "failed",
+			reason: "hop preparation returned no authorize URL"
+		};
+		const probe = await fetch(authorizeUrl, {
+			method: "GET",
+			credentials: "include",
+			headers: { accept: "application/json" },
+			signal: controller.signal
+		});
+		const body = await probe.json().catch(() => ({}));
+		const outcome = parseAuthorizeOutcome(probe.status, body);
+		switch (outcome.type) {
+			case "login_required": return { status: "sign_in_required" };
+			case "no_access": return { status: "no_access" };
+			case "select_tenant": return {
+				status: "select_workspace",
+				workspaces: outcome.tenants
+			};
+			case "authorized": {
+				const completed = await postJson(HOP_COMPLETE_ENDPOINT, {
+					code: outcome.code,
+					state: outcome.state
+				}, controller.signal);
+				const settled = await completed.json().catch(() => ({}));
+				if (completed.ok) {
+					if (settled.status === "workspace_mismatch" && settled.requested && settled.workspace) return {
+						status: "workspace_mismatch",
+						requested: settled.requested,
+						workspace: settled.workspace
+					};
+					return {
+						status: "signed_in",
+						...settled.workspace ? { workspace: settled.workspace } : {}
+					};
+				}
+				return {
+					status: "failed",
+					reason: settled.status ?? `exchange failed (${completed.status})`
+				};
+			}
+		}
+	} catch (error) {
+		return {
+			status: "failed",
+			reason: error instanceof Error ? error.message : "warm hop failed"
+		};
+	} finally {
+		clearTimeout(timeout);
+	}
+}
+/**
+* Move to another workspace (F028 / FR-SWITCH-1…6).
+*
+* The same mechanism as the entry attempt, aimed deliberately rather than on arrival — and
+* deliberately **not** subject to the once-per-entry guard, because this one is a thing the
+* person asked for.
+*
+* Eligibility is decided by the platform at this moment, not from any list held here, so a
+* workspace revoked since the picker was drawn can never be entered (FR-SWITCH-4). Which
+* refusal you get depends on what is left, verified against a live platform: still holding
+* other workspaces gives `select_workspace` listing them; having lost them all gives
+* `no_access`. Do not treat `no_access` as the only refusal.
+*
+* On `signed_in` the session cookie now names the new workspace. The caller decides what to
+* do next — the SDK does not reload the page or discard anything on their behalf, because it
+* cannot know what is unsaved on the screen (FR-SWITCH-7).
+*/
+async function switchWorkspace(workspace, options = {}) {
+	if (!workspace) return {
+		status: "failed",
+		reason: "no workspace given"
+	};
+	return attemptWarmHop({
+		...options,
+		workspace
+	});
+}
+/**
+* The automatic entry attempt: at most once per tab, whatever the caller does (FR-HOP-2).
+*
+* Returns `null` when it declines to attempt — already tried this entry — so a caller can
+* tell "we tried and they must sign in" from "we did not try".
+*/
+async function attemptWarmHopOnce(options = {}) {
+	if (warmHopAttempted()) return null;
+	markWarmHopAttempted();
+	return attemptWarmHop(options);
+}
+//#endregion
 //#region src/hooks.ts
 function useSessionSource() {
 	const ctx = useContext(PolyXContext);
@@ -498,6 +691,14 @@ function useSessionSource() {
 				} catch {
 					return null;
 				}
+			},
+			refresh: async () => {
+				try {
+					await engine.getAccessToken();
+					return true;
+				} catch {
+					return false;
+				}
 			}
 		},
 		canSignIn: Boolean(controller)
@@ -518,12 +719,14 @@ function useAuth() {
 	}, [ctx]);
 	const signOut = useCallback((options) => source.signOut(options), [source]);
 	const getToken = useCallback(() => source.getToken(), [source]);
+	const refresh = useCallback(() => source.refresh(), [source]);
 	return {
 		isLoaded: state.status !== "resolving",
 		isSignedIn: state.status === "authenticated" || state.status === "refreshing",
 		signIn,
 		signOut,
-		getToken
+		getToken,
+		refresh
 	};
 }
 /** Run this on your callback route to complete a sign-in (see `<AuthCallback>`). */
@@ -538,6 +741,52 @@ function useUser() {
 	const state = useSession();
 	return state.status === "authenticated" || state.status === "refreshing" ? state.session.claims : null;
 }
+/**
+* Try a silent sign-in once when this component mounts (F027 / FR-HOP-2, FR-FALL-1…3).
+*
+* The contract that matters is D11's: **an attempt that fails must be invisible.** Someone who
+* is genuinely signed out pays the whole cost of this feature and gets nothing from it, so they
+* must not see a flicker, a spinner that outlives their patience, or — worst — a redirect loop.
+* Hence: no navigation anywhere in the flow, a hard timeout, and a guard that survives the route
+* change to the sign-in page (a guard in React state would reset exactly when it is needed).
+*
+* ```tsx
+* const hop = useWarmHop();
+* if (hop.status !== "settled" ) return null;              // no half-drawn form
+* if (hop.result.status === "signed_in") return <Redirect/>;
+* return <SignIn />;                                       // the ordinary path
+* ```
+*
+* Strict Mode's double-mount does not produce two attempts: the marker is written before the
+* first request goes out.
+*/
+function useWarmHop(options = {}) {
+	const { enabled = true, workspace, timeoutMs } = options;
+	const [state, setState] = useState({ status: "idle" });
+	useEffect(() => {
+		if (!enabled) return;
+		let live = true;
+		setState({ status: "attempting" });
+		attemptWarmHopOnce({
+			workspace,
+			timeoutMs
+		}).then((result) => {
+			if (!live) return;
+			setState({
+				status: "settled",
+				result: result ?? { status: "sign_in_required" }
+			});
+		});
+		return () => {
+			live = false;
+		};
+	}, [
+		enabled,
+		workspace,
+		timeoutMs
+	]);
+	return state;
+}
 //#endregion
 //#region src/components/protected.tsx
 /** Gate content on authentication state without flashing the wrong branch. */
@@ -629,7 +878,7 @@ function captureDeviceContext() {
 }
 //#endregion
 //#region src/components/sign-in.tsx
-const DEFAULT_LABELS$3 = {
+const DEFAULT_LABELS$4 = {
 	heading: "Sign in",
 	subheading: "Enter your credentials to continue.",
 	tagline: "",
@@ -655,7 +904,8 @@ const DEFAULT_LABELS$3 = {
 	invalidCredentials: "Invalid email or password.",
 	noAccess: "You don't have access to this application.",
 	passwordChangeRequired: "You must reset your password before you can sign in.",
-	genericError: "Something went wrong. Please try again."
+	genericError: "Something went wrong. Please try again.",
+	verificationRequired: "Additional verification is required to sign in."
 };
 /** Mirrors poly-auth's own floor (Joi: min 6). */
 const MIN_PASSWORD_LENGTH = 6;
@@ -744,7 +994,7 @@ function SignIn(props) {
 	const action = props.action ?? "/api/polyx/authenticate";
 	const variant = props.variant ?? "card";
 	const labels = {
-		...DEFAULT_LABELS$3,
+		...DEFAULT_LABELS$4,
 		...props.labels
 	};
 	const [email, setEmail] = useState("");
@@ -825,6 +1075,9 @@ function SignIn(props) {
 				case "no_access":
 					setError(labels.noAccess);
 					return;
+				case "verification_required":
+					setError(labels.verificationRequired ?? labels.genericError);
+					return;
 				default:
 					setError(labels.genericError);
 					return;
@@ -1137,7 +1390,7 @@ function RecoveryStatus(props) {
 }
 //#endregion
 //#region src/components/forgot-password.tsx
-const DEFAULT_LABELS$2 = {
+const DEFAULT_LABELS$3 = {
 	heading: "Reset your password",
 	subheading: "Enter your email and we'll send you a reset link.",
 	emailLabel: "Email",
@@ -1172,7 +1425,7 @@ function ForgotPassword(props) {
 	const action = props.action ?? "/api/polyx/forgot-password";
 	const signInPath = props.signInPath ?? "/sign-in";
 	const labels = {
-		...DEFAULT_LABELS$2,
+		...DEFAULT_LABELS$3,
 		...props.labels
 	};
 	const [email, setEmail] = useState("");
@@ -1300,7 +1553,7 @@ function ForgotPassword(props) {
 }
 //#endregion
 //#region src/components/reset-password.tsx
-const DEFAULT_LABELS$1 = {
+const DEFAULT_LABELS$2 = {
 	heading: "Choose a new password",
 	subheading: "Enter and confirm your new password.",
 	newPasswordLabel: "New password",
@@ -1336,7 +1589,7 @@ function ResetPassword(props) {
 	const signInPath = props.signInPath ?? "/sign-in";
 	const forgotPasswordPath = props.forgotPasswordPath ?? "/forgot-password";
 	const labels = {
-		...DEFAULT_LABELS$1,
+		...DEFAULT_LABELS$2,
 		...props.labels
 	};
 	const [token] = useState(() => props.token ?? (typeof window !== "undefined" ? new URLSearchParams(window.location.search).get("token") ?? "" : ""));
@@ -1619,6 +1872,511 @@ function UserAvatar({ src, name, size = 32, className }) {
 	});
 }
 //#endregion
+//#region src/components/user-profile.tsx
+const PROFILE_ENDPOINT = "/api/polyx/profile";
+const DEFAULT_LABELS$1 = {
+	trigger: "Manage profile",
+	title: "Your profile",
+	description: "Update your personal details.",
+	firstName: "First name",
+	lastName: "Last name",
+	phoneNumber: "Phone number",
+	cnic: "National ID",
+	gender: "Gender",
+	photo: "Photo",
+	changePhoto: "Change photo",
+	optional: "optional",
+	save: "Save changes",
+	saving: "Saving…",
+	cancel: "Cancel",
+	close: "Close",
+	loading: "Loading your profile…",
+	loadFailed: "We couldn't load your profile. Close this and try again.",
+	saveFailed: "We couldn't save your changes. Your edits are still here — try again.",
+	saved: "Profile updated.",
+	signedOut: "Your session ended. Sign in again to make changes.",
+	genderUnset: "Prefer not to say",
+	genderMale: "Male",
+	genderFemale: "Female",
+	genderOther: "Other"
+};
+/** Matches the console's options, so the same stored values round-trip. */
+const GENDERS = [
+	"male",
+	"female",
+	"other"
+];
+const EMPTY = {
+	firstName: "",
+	lastName: "",
+	phoneNumber: "",
+	cnic: "",
+	gender: ""
+};
+function readProfile(user) {
+	const draft = { ...EMPTY };
+	for (const field of PROFILE_FIELDS) {
+		const value = user[field];
+		if (typeof value === "string") draft[field] = value;
+	}
+	return draft;
+}
+/**
+* The signed-in person's own profile, as a dialog (v0.4 / FR-PROF).
+*
+* Every application that wanted this had to build the same four things: a form, a validation
+* ruleset guessed at from error messages, a file upload, and — because the browser holds no
+* credential under BFF custody — a server route to carry the call. The last of those is
+* security-adjacent work that had no business being duplicated per app.
+*
+* The credential never comes near this component: it posts to the SDK's own route, which
+* attaches the session server-side and takes the identity from the sealed session rather than
+* from anything sent here. This surface cannot be aimed at another person's profile even if a
+* caller tries (FR-CUSTODY-4 / D24).
+*
+* ```tsx
+* <UserProfile onSaved={() => router.refresh()} />
+* ```
+*/
+function UserProfile(props) {
+	const labels = {
+		...DEFAULT_LABELS$1,
+		...props.labels
+	};
+	const { isLoaded, isSignedIn, refresh } = useAuth();
+	const controlled = props.open !== void 0;
+	const [internalOpen, setInternalOpen] = useState(props.defaultOpen ?? false);
+	const open = controlled ? props.open === true : internalOpen;
+	const [status, setStatus] = useState("loading");
+	const [stored, setStored] = useState(EMPTY);
+	const [draft, setDraft] = useState(EMPTY);
+	const [errors, setErrors] = useState({});
+	const [photo, setPhoto] = useState(null);
+	const [photoError, setPhotoError] = useState(null);
+	const [storedPhoto, setStoredPhoto] = useState(void 0);
+	const [saving, setSaving] = useState(false);
+	const [feedback, setFeedback] = useState(null);
+	const [portalHost, setPortalHost] = useState(null);
+	useEffect(() => {
+		const host = document.createElement("div");
+		host.setAttribute("data-polyx-userprofile-portal", "");
+		document.body.appendChild(host);
+		setPortalHost(host);
+		return () => host.remove();
+	}, []);
+	const triggerRef = useRef(null);
+	const dialogRef = useRef(null);
+	const fileRef = useRef(null);
+	const titleId = useId();
+	const fieldId = useId();
+	const onOpenChange = props.onOpenChange;
+	const setOpen = useCallback((next) => {
+		if (!controlled) setInternalOpen(next);
+		onOpenChange?.(next);
+	}, [controlled, onOpenChange]);
+	const polyx = useContext(PolyXContext);
+	const [branding, setBranding] = useState({});
+	useEffect(() => {
+		if (!polyx || !open) return;
+		let active = true;
+		polyx.authClient.fetchBranding({}).then((tokens) => {
+			if (active) setBranding(tokens);
+		});
+		return () => {
+			active = false;
+		};
+	}, [polyx, open]);
+	const brandingStyle = {};
+	if (branding.primaryColor) brandingStyle["--polyx-brand"] = branding.primaryColor;
+	/** Load on open. Never leaves blank fields looking like a stored (empty) profile — EC-PROF-1. */
+	useEffect(() => {
+		if (!open) return;
+		let active = true;
+		setStatus("loading");
+		setFeedback(null);
+		(async () => {
+			try {
+				const response = await fetch(PROFILE_ENDPOINT, { headers: { Accept: "application/json" } });
+				const body = await response.json().catch(() => ({}));
+				if (!active) return;
+				if (!response.ok || !body.user) {
+					setStatus("load_failed");
+					return;
+				}
+				const loaded = readProfile(body.user);
+				setStored(loaded);
+				setDraft(loaded);
+				setStoredPhoto(typeof body.user.profilePicture === "string" ? body.user.profilePicture : void 0);
+				setErrors({});
+				setStatus("ready");
+			} catch {
+				if (active) setStatus("load_failed");
+			}
+		})();
+		return () => {
+			active = false;
+		};
+	}, [open]);
+	useEffect(() => {
+		const preview = photo?.preview;
+		return () => {
+			if (preview) URL.revokeObjectURL(preview);
+		};
+	}, [photo]);
+	/**
+	* Hide the rest of the page from assistive technology while the dialog is open.
+	*
+	* `aria-modal="true"` alone is not enough — screen-reader support for it is inconsistent, so a
+	* virtual cursor can still read and act on everything behind the dialog. The keyboard focus trap
+	* does not cover this either: it constrains Tab, not the virtual cursor. Without both, the dialog
+	* announces itself as modal and then does not behave modally.
+	*
+	* Every direct child of `<body>` except the dialog's own portal is marked, and only attributes
+	* this effect added are removed again — a host that set its own `aria-hidden` keeps it.
+	*/
+	useEffect(() => {
+		if (!open || !portalHost) return;
+		const marked = [];
+		for (const node of Array.from(document.body.children)) {
+			if (node === portalHost || !(node instanceof HTMLElement)) continue;
+			if (node.hasAttribute("aria-hidden")) continue;
+			node.setAttribute("aria-hidden", "true");
+			node.setAttribute("inert", "");
+			marked.push(node);
+		}
+		return () => {
+			for (const node of marked) {
+				node.removeAttribute("aria-hidden");
+				node.removeAttribute("inert");
+			}
+		};
+	}, [open, portalHost]);
+	/**
+	* Move focus into the dialog once there is something to focus (FR-A11Y-1).
+	*
+	* Deliberately keyed on `status`, not just `open`: the dialog opens in its loading state with
+	* no focusable content, so placing focus at open time silently leaves it on the page behind —
+	* which is exactly nowhere for anyone navigating by keyboard or screen reader.
+	*/
+	useEffect(() => {
+		if (!open || status === "loading") return;
+		dialogRef.current?.querySelector("input, select, button")?.focus();
+	}, [open, status]);
+	/** Escape closes; focus is trapped while open (FR-A11Y-2/3). */
+	useEffect(() => {
+		if (!open) return;
+		const node = dialogRef.current;
+		const previous = document.activeElement;
+		const onKeyDown = (event) => {
+			if (event.key === "Escape") {
+				setOpen(false);
+				return;
+			}
+			if (event.key !== "Tab" || !node) return;
+			const focusable = [...node.querySelectorAll("input, select, button, a[href]")].filter((element) => !element.hasAttribute("disabled"));
+			if (focusable.length === 0) return;
+			const first = focusable[0];
+			const last = focusable[focusable.length - 1];
+			if (event.shiftKey && document.activeElement === first) {
+				event.preventDefault();
+				last.focus();
+			} else if (!event.shiftKey && document.activeElement === last) {
+				event.preventDefault();
+				first.focus();
+			}
+		};
+		document.addEventListener("keydown", onKeyDown);
+		return () => {
+			document.removeEventListener("keydown", onKeyDown);
+			(triggerRef.current ?? previous)?.focus();
+		};
+	}, [open, setOpen]);
+	function set(field, value) {
+		setDraft((current) => ({
+			...current,
+			[field]: value
+		}));
+		setErrors((current) => ({
+			...current,
+			[field]: void 0
+		}));
+		setFeedback(null);
+	}
+	/** Validate on leaving a field, so a mistake is caught next to where it was made (FR-VALID-8). */
+	function blur(field) {
+		const found = validateProfileDraft(draft)[field];
+		setErrors((current) => ({
+			...current,
+			[field]: found
+		}));
+	}
+	function choosePhoto(file) {
+		if (!file) return;
+		const invalid = validateProfileImage(file);
+		if (invalid) {
+			setPhotoError(invalid);
+			setPhoto(null);
+			return;
+		}
+		setPhotoError(null);
+		setPhoto({
+			file,
+			preview: URL.createObjectURL(file)
+		});
+		setFeedback(null);
+	}
+	async function save() {
+		if (saving) return;
+		const found = validateProfileDraft(draft);
+		if (Object.keys(found).length > 0) {
+			setErrors(found);
+			return;
+		}
+		const changed = buildProfileUpdate(draft, stored);
+		if (Object.keys(changed).length === 0 && !photo) {
+			setOpen(false);
+			return;
+		}
+		const body = new FormData();
+		for (const [field, value] of Object.entries(changed)) body.append(field, value);
+		if (photo) body.append("image", photo.file);
+		setSaving(true);
+		setFeedback(null);
+		try {
+			const response = await fetch(PROFILE_ENDPOINT, {
+				method: "POST",
+				body
+			});
+			const payload = await response.json().catch(() => ({}));
+			if (response.status === 401) {
+				setFeedback({
+					kind: "error",
+					message: labels.signedOut
+				});
+				return;
+			}
+			if (!response.ok) {
+				const field = conflictField(payload.message);
+				if (field) {
+					setErrors((current) => ({
+						...current,
+						[field]: payload.message
+					}));
+					return;
+				}
+				setFeedback({
+					kind: "error",
+					message: payload.message ?? labels.saveFailed
+				});
+				return;
+			}
+			const saved = payload.user ?? {};
+			setStored(readProfile(saved));
+			if (typeof saved.profilePicture === "string") setStoredPhoto(saved.profilePicture);
+			setPhoto(null);
+			setFeedback({
+				kind: "success",
+				message: labels.saved
+			});
+			await refresh().catch(() => false);
+			props.onSaved?.(saved);
+			setOpen(false);
+		} catch {
+			setFeedback({
+				kind: "error",
+				message: labels.saveFailed
+			});
+		} finally {
+			setSaving(false);
+		}
+	}
+	if (!isLoaded || !isSignedIn) return null;
+	const rootClass = [
+		"polyx-signin",
+		"polyx-userprofile",
+		props.className
+	].filter(Boolean).join(" ");
+	const displayName = [draft.firstName, draft.lastName].filter(Boolean).join(" ");
+	function field(name, label, extra = {}) {
+		const id = `${fieldId}-${name}`;
+		const error = errors[name];
+		return /* @__PURE__ */ jsxs("div", {
+			className: "polyx-signin__field",
+			children: [
+				/* @__PURE__ */ jsxs("label", {
+					className: "polyx-signin__label",
+					htmlFor: id,
+					children: [label, extra.optional ? /* @__PURE__ */ jsxs("span", {
+						className: "polyx-userprofile__optional",
+						children: [
+							" (",
+							labels.optional,
+							")"
+						]
+					}) : null]
+				}),
+				/* @__PURE__ */ jsx("input", {
+					id,
+					className: "polyx-signin__input",
+					type: extra.type ?? "text",
+					value: draft[name] ?? "",
+					placeholder: extra.placeholder,
+					disabled: saving,
+					"aria-required": extra.optional ? void 0 : true,
+					"aria-invalid": error ? true : void 0,
+					"aria-describedby": error ? `${id}-error` : void 0,
+					onChange: (event) => set(name, event.target.value),
+					onBlur: () => blur(name)
+				}),
+				error ? /* @__PURE__ */ jsx("p", {
+					id: `${id}-error`,
+					className: "polyx-userprofile__field-error",
+					children: error
+				}) : null
+			]
+		});
+	}
+	return /* @__PURE__ */ jsxs("div", {
+		className: rootClass,
+		style: brandingStyle,
+		children: [props.open === void 0 ? /* @__PURE__ */ jsx("button", {
+			ref: triggerRef,
+			type: "button",
+			className: ["polyx-userprofile__trigger", props.triggerClassName].filter(Boolean).join(" "),
+			onClick: () => setOpen(true),
+			children: props.trigger ?? labels.trigger
+		}) : null, open && portalHost ? createPortal(/* @__PURE__ */ jsx("div", {
+			className: "polyx-signin polyx-userprofile polyx-userprofile__overlay",
+			style: brandingStyle,
+			onMouseDown: () => setOpen(false),
+			children: /* @__PURE__ */ jsxs("div", {
+				ref: dialogRef,
+				role: "dialog",
+				"aria-modal": "true",
+				"aria-labelledby": titleId,
+				className: ["polyx-userprofile__dialog", props.dialogClassName].filter(Boolean).join(" "),
+				onMouseDown: (event) => event.stopPropagation(),
+				children: [/* @__PURE__ */ jsxs("div", {
+					className: "polyx-userprofile__header",
+					children: [/* @__PURE__ */ jsx("h2", {
+						id: titleId,
+						className: "polyx-userprofile__title",
+						children: labels.title
+					}), /* @__PURE__ */ jsx("p", {
+						className: "polyx-userprofile__description",
+						children: labels.description
+					})]
+				}), status === "loading" ? /* @__PURE__ */ jsx("p", {
+					className: "polyx-userprofile__status",
+					role: "status",
+					children: labels.loading
+				}) : status === "load_failed" ? /* @__PURE__ */ jsx("p", {
+					className: "polyx-signin__error",
+					role: "alert",
+					children: labels.loadFailed
+				}) : /* @__PURE__ */ jsxs("form", {
+					className: "polyx-signin__form",
+					onSubmit: (event) => {
+						event.preventDefault();
+						save();
+					},
+					children: [
+						/* @__PURE__ */ jsxs("div", {
+							className: "polyx-userprofile__photo",
+							children: [/* @__PURE__ */ jsx(UserAvatar, {
+								src: photo?.preview ?? storedPhoto,
+								name: displayName,
+								size: 56
+							}), /* @__PURE__ */ jsxs("div", {
+								className: "polyx-userprofile__photo-actions",
+								children: [
+									/* @__PURE__ */ jsx("button", {
+										type: "button",
+										className: "polyx-userprofile__photo-button",
+										disabled: saving,
+										onClick: () => fileRef.current?.click(),
+										children: labels.changePhoto
+									}),
+									/* @__PURE__ */ jsx("input", {
+										ref: fileRef,
+										type: "file",
+										accept: "image/*",
+										className: "polyx-userprofile__file",
+										"aria-label": labels.photo,
+										onChange: (event) => choosePhoto(event.target.files?.[0])
+									}),
+									photoError ? /* @__PURE__ */ jsx("p", {
+										className: "polyx-userprofile__field-error",
+										children: photoError
+									}) : null
+								]
+							})]
+						}),
+						/* @__PURE__ */ jsxs("div", {
+							className: "polyx-userprofile__row",
+							children: [field("firstName", labels.firstName), field("lastName", labels.lastName)]
+						}),
+						field("phoneNumber", labels.phoneNumber, {
+							optional: true,
+							type: "tel",
+							placeholder: "+14155552671"
+						}),
+						field("cnic", labels.cnic, { optional: true }),
+						/* @__PURE__ */ jsxs("div", {
+							className: "polyx-signin__field",
+							children: [/* @__PURE__ */ jsxs("label", {
+								className: "polyx-signin__label",
+								htmlFor: `${fieldId}-gender`,
+								children: [labels.gender, /* @__PURE__ */ jsxs("span", {
+									className: "polyx-userprofile__optional",
+									children: [
+										" (",
+										labels.optional,
+										")"
+									]
+								})]
+							}), /* @__PURE__ */ jsxs("select", {
+								id: `${fieldId}-gender`,
+								className: "polyx-signin__input",
+								value: draft.gender ?? "",
+								disabled: saving,
+								onChange: (event) => set("gender", event.target.value),
+								children: [/* @__PURE__ */ jsx("option", {
+									value: "",
+									children: labels.genderUnset
+								}), GENDERS.map((value) => /* @__PURE__ */ jsx("option", {
+									value,
+									children: value === "male" ? labels.genderMale : value === "female" ? labels.genderFemale : labels.genderOther
+								}, value))]
+							})]
+						}),
+						feedback ? /* @__PURE__ */ jsx("p", {
+							className: feedback.kind === "error" ? "polyx-signin__error" : "polyx-userprofile__success",
+							role: feedback.kind === "error" ? "alert" : "status",
+							children: feedback.message
+						}) : null,
+						/* @__PURE__ */ jsxs("div", {
+							className: "polyx-userprofile__actions",
+							children: [/* @__PURE__ */ jsx("button", {
+								type: "button",
+								className: "polyx-userprofile__cancel",
+								disabled: saving,
+								onClick: () => setOpen(false),
+								children: labels.cancel
+							}), /* @__PURE__ */ jsx("button", {
+								type: "submit",
+								className: "polyx-signin__submit",
+								disabled: saving,
+								children: saving ? labels.saving : labels.save
+							})]
+						})
+					]
+				})]
+			})
+		}), portalHost) : null]
+	});
+}
+//#endregion
 //#region src/components/user-button.tsx
 const DEFAULT_LABELS = {
 	trigger: "Account menu",
@@ -1725,6 +2483,7 @@ function UserButtonRoot(props) {
 	const { isLoaded, isSignedIn, signOut } = useAuth();
 	const user = useUser();
 	const [open, setOpen] = useState(props.defaultOpen ?? false);
+	const [profileOpen, setProfileOpen] = useState(false);
 	const [focused, setFocused] = useState(0);
 	const [side, setSide] = useState(props.side && props.side !== "auto" ? props.side : "bottom");
 	const triggerRef = useRef(null);
@@ -1801,6 +2560,12 @@ function UserButtonRoot(props) {
 		labelIcon: /* @__PURE__ */ jsx(GearIcon, {}),
 		href: props.manageAccountUrl
 	});
+	else if (props.showUserProfile) builtIns.set("manageAccount", {
+		key: "manageAccount",
+		label: labels.manageAccount,
+		labelIcon: /* @__PURE__ */ jsx(GearIcon, {}),
+		onClick: () => setProfileOpen(true)
+	});
 	builtIns.set("signOut", {
 		key: "signOut",
 		label: labels.signOut,
@@ -1840,81 +2605,89 @@ function UserButtonRoot(props) {
 			props.className
 		].filter(Boolean).join(" "),
 		"data-polyx-userbutton": open ? "open" : "closed",
-		children: [/* @__PURE__ */ jsx("button", {
-			ref: triggerRef,
-			type: "button",
-			className: ["polyx-userbutton__trigger", props.triggerClassName].filter(Boolean).join(" "),
-			"aria-haspopup": "menu",
-			"aria-expanded": open,
-			"aria-controls": open ? menuId : void 0,
-			"aria-label": labels.trigger,
-			onClick: () => {
-				setFocused(0);
-				setOpen((current) => !current);
-			},
-			children: props.trigger ?? /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(UserAvatar, {
-				src: user.avatarUrl,
-				name,
-				size: props.avatarSize
-			}), props.showName ? /* @__PURE__ */ jsx("span", {
-				className: "polyx-userbutton__trigger-name",
-				children: name
-			}) : null] })
-		}), open ? /* @__PURE__ */ jsxs("div", {
-			ref: menuRef,
-			id: menuId,
-			role: "menu",
-			className: "polyx-userbutton__menu",
-			"data-polyx-side": side,
-			"data-polyx-align": align,
-			onKeyDown: onMenuKeyDown,
-			children: [customHeader ?? /* @__PURE__ */ jsxs("div", {
-				className: "polyx-userbutton__identity",
-				children: [/* @__PURE__ */ jsx(UserAvatar, {
+		children: [
+			/* @__PURE__ */ jsx("button", {
+				ref: triggerRef,
+				type: "button",
+				className: ["polyx-userbutton__trigger", props.triggerClassName].filter(Boolean).join(" "),
+				"aria-haspopup": "menu",
+				"aria-expanded": open,
+				"aria-controls": open ? menuId : void 0,
+				"aria-label": labels.trigger,
+				onClick: () => {
+					setFocused(0);
+					setOpen((current) => !current);
+				},
+				children: props.trigger ?? /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(UserAvatar, {
 					src: user.avatarUrl,
 					name,
-					size: 36
-				}), /* @__PURE__ */ jsxs("div", {
-					className: "polyx-userbutton__identity-text",
-					children: [user.displayName ? /* @__PURE__ */ jsx("span", {
-						className: "polyx-userbutton__name",
-						children: user.displayName
-					}) : null, user.email ? /* @__PURE__ */ jsx("span", {
-						className: "polyx-userbutton__email",
-						children: user.email
-					}) : null]
+					size: props.avatarSize
+				}), props.showName ? /* @__PURE__ */ jsx("span", {
+					className: "polyx-userbutton__trigger-name",
+					children: name
+				}) : null] })
+			}),
+			open ? /* @__PURE__ */ jsxs("div", {
+				ref: menuRef,
+				id: menuId,
+				role: "menu",
+				className: "polyx-userbutton__menu",
+				"data-polyx-side": side,
+				"data-polyx-align": align,
+				onKeyDown: onMenuKeyDown,
+				children: [customHeader ?? /* @__PURE__ */ jsxs("div", {
+					className: "polyx-userbutton__identity",
+					children: [/* @__PURE__ */ jsx(UserAvatar, {
+						src: user.avatarUrl,
+						name,
+						size: 36
+					}), /* @__PURE__ */ jsxs("div", {
+						className: "polyx-userbutton__identity-text",
+						children: [user.displayName ? /* @__PURE__ */ jsx("span", {
+							className: "polyx-userbutton__name",
+							children: user.displayName
+						}) : null, user.email ? /* @__PURE__ */ jsx("span", {
+							className: "polyx-userbutton__email",
+							children: user.email
+						}) : null]
+					})]
+				}), /* @__PURE__ */ jsx("ul", {
+					className: "polyx-userbutton__items",
+					children: items.map((item, index) => /* @__PURE__ */ jsx("li", { children: item.custom ? /* @__PURE__ */ jsx("div", {
+						className: "polyx-userbutton__custom",
+						children: item.custom
+					}) : item.href ? /* @__PURE__ */ jsxs("a", {
+						ref: (node) => {
+							itemRefs.current[index] = node;
+						},
+						role: "menuitem",
+						tabIndex: index === focused ? 0 : -1,
+						className: "polyx-userbutton__item",
+						href: item.href,
+						onClick: () => close(false),
+						children: [item.labelIcon, item.label]
+					}) : /* @__PURE__ */ jsxs("button", {
+						ref: (node) => {
+							itemRefs.current[index] = node;
+						},
+						role: "menuitem",
+						tabIndex: index === focused ? 0 : -1,
+						type: "button",
+						className: "polyx-userbutton__item",
+						onClick: () => {
+							close(false);
+							item.onClick?.();
+						},
+						children: [item.labelIcon, item.label]
+					}) }, item.key))
 				})]
-			}), /* @__PURE__ */ jsx("ul", {
-				className: "polyx-userbutton__items",
-				children: items.map((item, index) => /* @__PURE__ */ jsx("li", { children: item.custom ? /* @__PURE__ */ jsx("div", {
-					className: "polyx-userbutton__custom",
-					children: item.custom
-				}) : item.href ? /* @__PURE__ */ jsxs("a", {
-					ref: (node) => {
-						itemRefs.current[index] = node;
-					},
-					role: "menuitem",
-					tabIndex: index === focused ? 0 : -1,
-					className: "polyx-userbutton__item",
-					href: item.href,
-					onClick: () => close(false),
-					children: [item.labelIcon, item.label]
-				}) : /* @__PURE__ */ jsxs("button", {
-					ref: (node) => {
-						itemRefs.current[index] = node;
-					},
-					role: "menuitem",
-					tabIndex: index === focused ? 0 : -1,
-					type: "button",
-					className: "polyx-userbutton__item",
-					onClick: () => {
-						close(false);
-						item.onClick?.();
-					},
-					children: [item.labelIcon, item.label]
-				}) }, item.key))
-			})]
-		}) : null]
+			}) : null,
+			props.showUserProfile && !props.manageAccountUrl ? /* @__PURE__ */ jsx(UserProfile, {
+				...props.userProfileProps,
+				open: profileOpen,
+				onOpenChange: setProfileOpen
+			}) : null
+		]
 	});
 }
 function GearIcon() {
@@ -1979,6 +2752,33 @@ const UserButton = Object.assign(UserButtonRoot, {
 	Header
 });
 //#endregion
+//#region src/auth-event.ts
+/**
+* Read a one-shot auth event published by the BFF (F017 / FR-CLIENT-5).
+*
+* Sign-in and sign-out are full-page navigations, so an app cannot simply react in the
+* handler that triggered them — the page is gone. The BFF leaves a short-lived, readable
+* cookie; the destination page consumes it once.
+*/
+/** Must match `AUTH_EVENT_COOKIE` in `@poly-x/next`. */
+const AUTH_EVENT_COOKIE = "polyx_auth_event";
+function readCookie(name) {
+	if (typeof document === "undefined") return void 0;
+	return document.cookie.split(";").map((part) => part.trim()).find((part) => part.startsWith(`${name}=`))?.slice(name.length + 1);
+}
+/**
+* Read the pending auth event and clear it, so it fires exactly once.
+*
+* Returns `null` when there is nothing pending — which is the normal case on almost every
+* page load. Safe to call during render or in an effect; it is a no-op on the server.
+*/
+function consumeAuthEvent() {
+	const value = readCookie(AUTH_EVENT_COOKIE);
+	if (value !== "signed-in" && value !== "signed-out") return null;
+	document.cookie = `${AUTH_EVENT_COOKIE}=; Path=/; Max-Age=0; SameSite=Lax`;
+	return value;
+}
+//#endregion
 //#region src/live-authz.ts
 const DEFAULT_POLL_MS = 6e4;
 const DEFAULT_FOCUS_THROTTLE_MS = 5e3;
@@ -2117,6 +2917,7 @@ function useAuthzChanged(callback) {
 * F006; this entry is the state foundation (provider, hooks, browser seams).
 */
 const PACKAGE_NAME = "@poly-x/react";
-const version = "0.0.0";
+/** The published version of this package, injected at build time. */
+const version = "0.3.0";
 //#endregion
-export { AuthCallback, BroadcastAuthChannel, BroadcastChannelSessionChannel, ForgotPassword, PACKAGE_NAME, PolyXContext, PolyXProvider, PopupCancelledError, Protected, ResetPassword, SessionStoragePkceStore, SignIn, UserAvatar, UserButton, WebLocksLock, WindowBrowserBridge, capturePreciseLocation, createLoginController, initialsFrom, resolveSide, startLiveAuthz, useAuth, useAuthCallback, useAuthzChanged, useLiveAuthz, useSession, useUser, version };
+export { AuthCallback, BroadcastAuthChannel, BroadcastChannelSessionChannel, ForgotPassword, PACKAGE_NAME, PolyXContext, PolyXProvider, PopupCancelledError, Protected, ResetPassword, SessionStoragePkceStore, SignIn, UserAvatar, UserButton, UserProfile, WARM_HOP_TIMEOUT_MS, WebLocksLock, WindowBrowserBridge, attemptWarmHop, attemptWarmHopOnce, capturePreciseLocation, consumeAuthEvent, createLoginController, initialsFrom, resetWarmHop, resolveSide, startLiveAuthz, switchWorkspace, useAuth, useAuthCallback, useAuthzChanged, useLiveAuthz, useSession, useUser, useWarmHop, version, warmHopAttempted };