@poly-x/react 0.1.0-alpha.9 → 0.1.1

package/dist/index.cjs

@@ -300,31 +300,225 @@ function PolyXProvider({ publishableKey, baseUrl, signInUrl, children }) {
 	});
 }
 //#endregion
+//#region src/bff-session.ts
+/**
+* Client session under BFF custody (ADR-0004).
+*
+* `@poly-x/next` seals the tokens in an httpOnly cookie, so a consuming app mounts no
+* `<PolyXProvider>` and there is no client engine to read — there is nothing for it to own.
+* The hooks still have to work there, so they fall back to this: a single module-level store
+* that reads server truth from the `session` route handler once and feeds the *same*
+* `SessionState` machine the engine drives. That is what ADR-0004 meant by custody being
+* "invisible to the consumer API surface".
+*
+* It follows `<SignIn/>`'s precedent — work without a provider, degrade quietly — rather than
+* asking BFF apps to adopt a provider whose whole purpose is holding tokens they don't have.
+*/
+const SESSION_ENDPOINT = "/api/polyx/session";
+const SIGNOUT_ENDPOINT = "/api/polyx/signout";
+var BffSessionStore = class {
+	state = { status: "resolving" };
+	listeners = /* @__PURE__ */ new Set();
+	loading = false;
+	watching = false;
+	getState = () => this.state;
+	/** SSR has no session to read; render the resolving branch and settle on the client. */
+	getServerState = () => ({ status: "resolving" });
+	subscribe = (listener) => {
+		this.listeners.add(listener);
+		this.load();
+		this.watchFocus();
+		return () => {
+			this.listeners.delete(listener);
+		};
+	};
+	/**
+	* The platform revokes every session for a user when an admin changes their permission,
+	* suspends them, or resets their password — and it pushes nothing, so a revoked user keeps
+	* looking signed in until they happen to make a request. Re-checking when the tab regains
+	* focus is the cheapest way to notice: come back to the tab, discover you're signed out.
+	*
+	* It is not a replacement for the 401 the next request will get; it just moves the discovery
+	* to a moment the user is actually looking at the screen.
+	*/
+	watchFocus() {
+		if (this.watching || typeof window === "undefined") return;
+		this.watching = true;
+		const recheck = () => {
+			if (typeof document !== "undefined" && document.visibilityState === "hidden") return;
+			this.revalidate();
+		};
+		window.addEventListener("focus", recheck);
+		document?.addEventListener?.("visibilitychange", recheck);
+	}
+	/**
+	* Re-read the session without passing through `resolving` — a confirmed session must not
+	* flicker the UI back to a loading state. Only a definite signed-out answer signs the user
+	* out: an unreachable server is a blip, not a revocation.
+	*/
+	async revalidate() {
+		if (this.loading || this.state.status === "resolving") return;
+		this.loading = true;
+		try {
+			const response = await fetch(SESSION_ENDPOINT, {
+				credentials: "same-origin",
+				headers: { accept: "application/json" }
+			});
+			const body = response.ok ? await response.json() : null;
+			const signedIn = Boolean(body?.isSignedIn && body.claims);
+			if (!signedIn && this.state.status !== "signed-out") this.set({
+				status: "signed-out",
+				reason: "revoked"
+			});
+			else if (signedIn && body?.claims) this.set({
+				status: "authenticated",
+				session: { claims: body.claims }
+			});
+		} catch {} finally {
+			this.loading = false;
+		}
+	}
+	/**
+	* Reading the session is a one-shot per page load, shared by every component that asks —
+	* a user menu and three gates must not mean four round-trips.
+	*/
+	async load() {
+		if (this.loading || this.state.status !== "resolving") return;
+		this.loading = true;
+		try {
+			const response = await fetch(SESSION_ENDPOINT, {
+				credentials: "same-origin",
+				headers: { accept: "application/json" }
+			});
+			const body = response.ok ? await response.json() : null;
+			this.set(body?.isSignedIn && body.claims ? {
+				status: "authenticated",
+				session: { claims: body.claims }
+			} : {
+				status: "signed-out",
+				reason: "signed-out"
+			});
+		} catch {
+			this.set({
+				status: "signed-out",
+				reason: "signed-out"
+			});
+		} finally {
+			this.loading = false;
+		}
+	}
+	/**
+	* v2 (FR-LIVE-1/2): re-read server truth and update claims, resolving whether **authorization
+	* actually changed**. Drives the live-authz orchestrator (`startLiveAuthz`): a `true` means a
+	* consumer that gates on `useUser()` should re-guard. Never flickers to `resolving`; a definite
+	* signed-out answer signs the user out (revoked), a network blip keeps the last-known claims.
+	* The orchestrator single-flights callers, so this needs no internal in-flight guard.
+	*/
+	refresh = async () => {
+		try {
+			const response = await fetch(SESSION_ENDPOINT, {
+				credentials: "same-origin",
+				headers: { accept: "application/json" }
+			});
+			const body = response.ok ? await response.json() : null;
+			if (!Boolean(body?.isSignedIn && body.claims)) {
+				const changed = this.state.status !== "signed-out";
+				if (changed) this.set({
+					status: "signed-out",
+					reason: "revoked"
+				});
+				return changed;
+			}
+			const prevClaims = this.state.status === "authenticated" ? JSON.stringify(this.state.session.claims) : null;
+			const nextClaims = body.claims;
+			const changed = prevClaims !== JSON.stringify(nextClaims);
+			if (changed) this.set({
+				status: "authenticated",
+				session: { claims: nextClaims }
+			});
+			return changed;
+		} catch {
+			return false;
+		}
+	};
+	set(next) {
+		this.state = next;
+		for (const listener of this.listeners) listener();
+	}
+	/**
+	* Sign-out has to reach the server — only it can unseal an httpOnly cookie, and only it
+	* holds the token needed to revoke the session upstream (X002).
+	*
+	* A same-origin fetch, not a navigation: the response's Set-Cookie still applies, and it
+	* leaves the destination to the caller. That is why the handler is content-negotiated —
+	* a server-side redirect target would be an open redirect on the auth path, and the client
+	* already knows where it wants to land.
+	*/
+	signOut = async (options) => {
+		const query = options?.scope === "everywhere" ? "?scope=everywhere" : "";
+		try {
+			await fetch(`${SIGNOUT_ENDPOINT}${query}`, {
+				method: "POST",
+				credentials: "same-origin",
+				headers: { accept: "application/json" }
+			});
+		} catch {}
+		this.set({
+			status: "signed-out",
+			reason: "signed-out"
+		});
+		if (options?.onSignOut) try {
+			await options.onSignOut();
+		} catch {}
+		window.location.assign(options?.redirectTo ?? "/");
+	};
+	/** Null by design: under BFF custody the token never reaches the browser (FR-SES-3). */
+	getToken = async () => null;
+};
+let store = new BffSessionStore();
+function getBffSessionStore() {
+	return store;
+}
+//#endregion
 //#region src/hooks.ts
-function usePolyX() {
+function useSessionSource() {
 	const ctx = (0, react.useContext)(PolyXContext);
-	if (!ctx) throw new Error("PolyX hooks (useAuth/useUser/useSession) must be used within a <PolyXProvider>.");
-	return ctx;
+	if (!ctx) return {
+		source: getBffSessionStore(),
+		canSignIn: false
+	};
+	const { engine, controller } = ctx;
+	return {
+		source: {
+			getState: () => engine.getState(),
+			subscribe: (listener) => engine.subscribe(listener),
+			signOut: () => engine.signOut(),
+			getToken: async () => {
+				try {
+					return await engine.getAccessToken();
+				} catch {
+					return null;
+				}
+			}
+		},
+		canSignIn: Boolean(controller)
+	};
 }
 /** The raw session state machine value — tearing-free under concurrent React. */
 function useSession() {
-	const { engine } = usePolyX();
-	const subscribe = (0, react.useCallback)((onChange) => engine.subscribe(onChange), [engine]);
-	const getSnapshot = (0, react.useCallback)(() => engine.getState(), [engine]);
-	return (0, react.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+	const { source } = useSessionSource();
+	return (0, react.useSyncExternalStore)((0, react.useCallback)((onChange) => source.subscribe(onChange), [source]), (0, react.useCallback)(() => source.getState(), [source]), (0, react.useCallback)(() => (source.getServerState ?? source.getState)(), [source]));
 }
 function useAuth() {
-	const { engine, controller } = usePolyX();
+	const ctx = (0, react.useContext)(PolyXContext);
+	const { source } = useSessionSource();
 	const state = useSession();
-	const signIn = (0, react.useCallback)((options) => controller.signIn(options), [controller]);
-	const signOut = (0, react.useCallback)(() => engine.signOut(), [engine]);
-	const getToken = (0, react.useCallback)(async () => {
-		try {
-			return await engine.getAccessToken();
-		} catch {
-			return null;
-		}
-	}, [engine]);
+	const signIn = (0, react.useCallback)(async (options) => {
+		if (!ctx) throw new Error("PolyX: signIn() needs a <PolyXProvider> (it owns the publishable key and the popup flow). Under BFF custody, render <SignIn/> or link to your sign-in route instead.");
+		return ctx.controller.signIn(options);
+	}, [ctx]);
+	const signOut = (0, react.useCallback)((options) => source.signOut(options), [source]);
+	const getToken = (0, react.useCallback)(() => source.getToken(), [source]);
 	return {
 		isLoaded: state.status !== "resolving",
 		isSignedIn: state.status === "authenticated" || state.status === "refreshing",
@@ -335,8 +529,11 @@ function useAuth() {
 }
 /** Run this on your callback route to complete a sign-in (see `<AuthCallback>`). */
 function useAuthCallback() {
-	const { controller } = usePolyX();
-	return (0, react.useCallback)(() => controller.handleCallback(), [controller]);
+	const ctx = (0, react.useContext)(PolyXContext);
+	return (0, react.useCallback)(() => {
+		if (!ctx) throw new Error("PolyX: <AuthCallback> / useAuthCallback() must be used within a <PolyXProvider>.");
+		return ctx.controller.handleCallback();
+	}, [ctx]);
 }
 function useUser() {
 	const state = useSession();
@@ -351,8 +548,89 @@ function Protected({ children, fallback = null, loading = null }) {
 	return isSignedIn ? children : fallback;
 }
 //#endregion
+//#region src/geolocation.ts
+/** W3C Geolocation `PositionError.PERMISSION_DENIED`. The only code that means a real "no". */
+const PERMISSION_DENIED = 1;
+/** One capture attempt at a given accuracy. Never rejects. */
+function attemptCapture(geo, highAccuracy, timeout) {
+	return new Promise((resolve) => {
+		let settled = false;
+		const done = (outcome) => {
+			if (settled) return;
+			settled = true;
+			resolve(outcome);
+		};
+		const timer = setTimeout(() => done({
+			result: { consent: "granted" },
+			retriable: true
+		}), timeout + 1500);
+		const finish = (outcome) => {
+			clearTimeout(timer);
+			done(outcome);
+		};
+		try {
+			geo.getCurrentPosition((position) => finish({
+				result: {
+					latitude: String(position.coords.latitude),
+					longitude: String(position.coords.longitude),
+					accuracyMeters: typeof position.coords.accuracy === "number" ? position.coords.accuracy : void 0,
+					consent: "granted"
+				},
+				retriable: false
+			}), (err) => {
+				const code = err?.code;
+				const denied = typeof code === "number" && code === PERMISSION_DENIED;
+				finish({
+					result: { consent: denied ? "denied" : "granted" },
+					retriable: !denied
+				});
+			}, {
+				enableHighAccuracy: highAccuracy,
+				timeout,
+				maximumAge: 0
+			});
+		} catch {
+			finish({
+				result: { consent: "granted" },
+				retriable: true
+			});
+		}
+	});
+}
+/**
+* Capture the browser's precise location. Resolves to a consent-labelled result and never
+* throws/rejects. High-accuracy first; on a no-fix (not a denial) retries once at low accuracy.
+*/
+async function capturePreciseLocation(consented, opts = {}) {
+	if (!consented) return { consent: "denied" };
+	const geo = opts.geolocation ?? (typeof navigator !== "undefined" ? navigator.geolocation : void 0);
+	if (!geo) return { consent: "denied" };
+	const highAccuracyMs = opts.timeoutMs ?? 8e3;
+	const lowAccuracyMs = opts.fallbackTimeoutMs ?? 12e3;
+	const first = await attemptCapture(geo, true, highAccuracyMs);
+	if (first.result.latitude !== void 0 || !first.retriable) return first.result;
+	return (await attemptCapture(geo, false, lowAccuracyMs)).result;
+}
+//#endregion
+//#region src/device-context.ts
+/** Capture the browser's timezone + screen resolution. Never throws; omits anything unavailable. */
+function captureDeviceContext() {
+	const context = {};
+	try {
+		const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+		if (typeof timezone === "string" && timezone) context.timezone = timezone;
+	} catch {}
+	try {
+		if (typeof window !== "undefined" && window.screen) {
+			const { width, height } = window.screen;
+			if (Number.isFinite(width) && Number.isFinite(height) && width > 0 && height > 0) context.screenResolution = `${Math.round(width)}x${Math.round(height)}`;
+		}
+	} catch {}
+	return context;
+}
+//#endregion
 //#region src/components/sign-in.tsx
-const DEFAULT_LABELS$2 = {
+const DEFAULT_LABELS$3 = {
 	heading: "Sign in",
 	subheading: "Enter your credentials to continue.",
 	tagline: "",
@@ -467,7 +745,7 @@ function SignIn(props) {
 	const action = props.action ?? "/api/polyx/authenticate";
 	const variant = props.variant ?? "card";
 	const labels = {
-		...DEFAULT_LABELS$2,
+		...DEFAULT_LABELS$3,
 		...props.labels
 	};
 	const [email, setEmail] = (0, react.useState)("");
@@ -510,6 +788,8 @@ function SignIn(props) {
 		setSubmitting(true);
 		setError(null);
 		try {
+			const geo = props.captureLocation ? await capturePreciseLocation(true) : void 0;
+			const deviceContext = captureDeviceContext();
 			const body = await (await fetch(action, {
 				method: "POST",
 				headers: { "content-type": "application/json" },
@@ -518,6 +798,8 @@ function SignIn(props) {
 					password,
 					organizationCode: props.organizationCode,
 					tenantId: options.tenantId,
+					...geo ? { geo } : {},
+					...Object.keys(deviceContext).length ? { deviceContext } : {},
 					...options.passwords
 				})
 			})).json().catch(() => ({}));
@@ -856,7 +1138,7 @@ function RecoveryStatus(props) {
 }
 //#endregion
 //#region src/components/forgot-password.tsx
-const DEFAULT_LABELS$1 = {
+const DEFAULT_LABELS$2 = {
 	heading: "Reset your password",
 	subheading: "Enter your email and we'll send you a reset link.",
 	emailLabel: "Email",
@@ -864,7 +1146,7 @@ const DEFAULT_LABELS$1 = {
 	submit: "Send reset link",
 	submitting: "Sending…",
 	sentHeading: "Check your email",
-	sentSubheading: "If an account exists for {email}, a password reset link is on its way. It expires in 30 minutes.",
+	sentSubheading: "If an account exists for {email}, a password reset link is on its way — it expires in 30 minutes. If it doesn't arrive within a few minutes, check your spam folder, then contact your workspace administrator.",
 	differentEmail: "Use a different email",
 	backToSignIn: "Back to sign in",
 	securedBy: "Secured by PolyX",
@@ -891,7 +1173,7 @@ function ForgotPassword(props) {
 	const action = props.action ?? "/api/polyx/forgot-password";
 	const signInPath = props.signInPath ?? "/sign-in";
 	const labels = {
-		...DEFAULT_LABELS$1,
+		...DEFAULT_LABELS$2,
 		...props.labels
 	};
 	const [email, setEmail] = (0, react.useState)("");
@@ -1019,7 +1301,7 @@ function ForgotPassword(props) {
 }
 //#endregion
 //#region src/components/reset-password.tsx
-const DEFAULT_LABELS = {
+const DEFAULT_LABELS$1 = {
 	heading: "Choose a new password",
 	subheading: "Enter and confirm your new password.",
 	newPasswordLabel: "New password",
@@ -1055,7 +1337,7 @@ function ResetPassword(props) {
 	const signInPath = props.signInPath ?? "/sign-in";
 	const forgotPasswordPath = props.forgotPasswordPath ?? "/forgot-password";
 	const labels = {
-		...DEFAULT_LABELS,
+		...DEFAULT_LABELS$1,
 		...props.labels
 	};
 	const [token] = (0, react.useState)(() => props.token ?? (typeof window !== "undefined" ? new URLSearchParams(window.location.search).get("token") ?? "" : ""));
@@ -1249,6 +1531,587 @@ function AuthCallback({ children = null }) {
 	return children;
 }
 //#endregion
+//#region src/components/placement.ts
+const OPPOSITE = {
+	top: "bottom",
+	bottom: "top",
+	left: "right",
+	right: "left"
+};
+/** Preference order when nothing is requested: vertical reads better for a menu than sideways. */
+const AUTO_ORDER = [
+	"bottom",
+	"top",
+	"right",
+	"left"
+];
+/** Room between the trigger and each viewport edge. */
+function spaceAround(trigger, viewport) {
+	return {
+		top: trigger.top,
+		bottom: viewport.height - trigger.bottom,
+		left: trigger.left,
+		right: viewport.width - trigger.right
+	};
+}
+function required(menu, gap) {
+	return {
+		top: menu.height + gap,
+		bottom: menu.height + gap,
+		left: menu.width + gap,
+		right: menu.width + gap
+	};
+}
+/**
+* Which side the menu should open on.
+*
+* An explicit side is honoured when it fits and flipped to its opposite when it doesn't — a
+* requested side that runs off-screen is a worse answer than the one that doesn't. `auto` takes
+* the first side that fits, and if none do, the roomiest: something has to be chosen, and the
+* least-bad option beats an arbitrary default.
+*/
+function resolveSide(preferred, trigger, menu, viewport, gap = 8) {
+	const space = spaceAround(trigger, viewport);
+	const need = required(menu, gap);
+	const fits = (side) => space[side] >= need[side];
+	if (preferred !== "auto") {
+		if (fits(preferred)) return preferred;
+		const opposite = OPPOSITE[preferred];
+		return fits(opposite) ? opposite : preferred;
+	}
+	const firstFitting = AUTO_ORDER.find(fits);
+	if (firstFitting) return firstFitting;
+	return AUTO_ORDER.reduce((best, side) => space[side] > space[best] ? side : best, AUTO_ORDER[0]);
+}
+//#endregion
+//#region src/components/user-avatar.tsx
+/**
+* Up to two initials from a display name. Handles the shapes the platform actually
+* produces — "Ali Ikram", a bare username, an email address.
+*/
+function initialsFrom(name) {
+	const source = (name ?? "").trim();
+	if (source.length === 0) return "?";
+	const words = (source.includes("@") ? source.split("@")[0] : source).split(/[\s._-]+/).filter(Boolean);
+	if (words.length === 0) return "?";
+	return (words.length === 1 ? [words[0][0]] : [words[0][0], words[words.length - 1][0]]).join("").toUpperCase();
+}
+/**
+* The user's picture, or their initials. A missing avatar is the ordinary case rather than
+* an error, so initials are a first-class state, not a broken image.
+*/
+function UserAvatar({ src, name, size = 32, className }) {
+	const rootClass = ["polyx-userbutton__avatar", className].filter(Boolean).join(" ");
+	const style = {
+		width: `${size}px`,
+		height: `${size}px`
+	};
+	if (src) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("img", {
+		className: rootClass,
+		style,
+		src,
+		alt: name ?? ""
+	});
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+		className: rootClass,
+		style,
+		"aria-hidden": "true",
+		children: initialsFrom(name)
+	});
+}
+//#endregion
+//#region src/components/user-button.tsx
+const DEFAULT_LABELS = {
+	trigger: "Account menu",
+	manageAccount: "Manage account",
+	signOut: "Sign out",
+	signOutEverywhere: "Sign out everywhere"
+};
+const BUILT_INS = [
+	"manageAccount",
+	"signOut",
+	"signOutEverywhere"
+];
+function isBuiltIn(label) {
+	return BUILT_INS.includes(label);
+}
+/**
+* Declarative markers. `<UserButton/>` reads their props off the element tree and renders the
+* menu itself, so these never render anything. Their public prop types come from the signatures
+* declared on the exported object below.
+*
+* `Custom` and `Header` take arbitrary nodes on purpose: an app adopting this component in place
+* of its own user menu has to be able to bring its own UI, or it won't adopt it. That is
+* composition, not the style injection FR-BRAND-1 guards against — a consumer renders their own
+* subtree in a slot; they still cannot restyle the SDK's own chrome.
+*/
+function MenuItems() {
+	return null;
+}
+function Action() {
+	return null;
+}
+function Link() {
+	return null;
+}
+function Custom() {
+	return null;
+}
+function Header() {
+	return null;
+}
+/**
+* Read the declarative children into a flat item list. A custom entry naming a built-in
+* *moves* it; unnamed built-ins keep their default order at the end. This is the whole reason
+* the API is declarative rather than a config array: it composes without letting a consumer
+* inject arbitrary markup or styles into the menu (FR-BRAND-1).
+*/
+function resolveItems(children, builtIns) {
+	const supplied = [];
+	const placed = /* @__PURE__ */ new Set();
+	react.Children.forEach(children, (child) => {
+		if (!(0, react.isValidElement)(child) || child.type !== MenuItems) return;
+		react.Children.forEach(child.props.children, (item, index) => {
+			if (!(0, react.isValidElement)(item)) return;
+			if (item.type === Action) {
+				const props = item.props;
+				if (isBuiltIn(props.label)) {
+					const builtIn = builtIns.get(props.label);
+					if (builtIn) {
+						supplied.push(builtIn);
+						placed.add(props.label);
+					}
+					return;
+				}
+				supplied.push({
+					key: `action-${index}`,
+					label: props.label,
+					labelIcon: props.labelIcon,
+					onClick: props.onClick
+				});
+				return;
+			}
+			if (item.type === Link) {
+				const props = item.props;
+				supplied.push({
+					key: `link-${index}`,
+					label: props.label,
+					labelIcon: props.labelIcon,
+					href: props.href
+				});
+				return;
+			}
+			if (item.type === Custom) supplied.push({
+				key: `custom-${index}`,
+				custom: item.props.children
+			});
+		});
+	});
+	const remaining = [...builtIns.entries()].filter(([name]) => !placed.has(name)).map(([, item]) => item);
+	return [...supplied, ...remaining];
+}
+/** The consumer's replacement for the identity block, if they supplied one. */
+function findHeader(children) {
+	let header;
+	react.Children.forEach(children, (child) => {
+		if ((0, react.isValidElement)(child) && child.type === Header) header = child.props.children;
+	});
+	return header;
+}
+function UserButtonRoot(props) {
+	const labels = {
+		...DEFAULT_LABELS,
+		...props.labels
+	};
+	const { isLoaded, isSignedIn, signOut } = useAuth();
+	const user = useUser();
+	const [open, setOpen] = (0, react.useState)(props.defaultOpen ?? false);
+	const [focused, setFocused] = (0, react.useState)(0);
+	const [side, setSide] = (0, react.useState)(props.side && props.side !== "auto" ? props.side : "bottom");
+	const triggerRef = (0, react.useRef)(null);
+	const menuRef = (0, react.useRef)(null);
+	const itemRefs = (0, react.useRef)([]);
+	const menuId = (0, react.useId)();
+	const align = props.align ?? "end";
+	const close = (0, react.useCallback)((returnFocus) => {
+		setOpen(false);
+		if (returnFocus) triggerRef.current?.focus();
+	}, []);
+	const onOpenChange = props.onOpenChange;
+	const mounted = (0, react.useRef)(false);
+	(0, react.useEffect)(() => {
+		if (!mounted.current) {
+			mounted.current = true;
+			return;
+		}
+		onOpenChange?.(open);
+	}, [open, onOpenChange]);
+	(0, react.useEffect)(() => {
+		if (!open) return;
+		const onKeyDown = (event) => {
+			if (event.key === "Escape") close(true);
+		};
+		const onPointerDown = (event) => {
+			const root = triggerRef.current?.closest(".polyx-userbutton");
+			if (root && !root.contains(event.target)) close(false);
+		};
+		document.addEventListener("keydown", onKeyDown);
+		document.addEventListener("mousedown", onPointerDown);
+		return () => {
+			document.removeEventListener("keydown", onKeyDown);
+			document.removeEventListener("mousedown", onPointerDown);
+		};
+	}, [open, close]);
+	(0, react.useEffect)(() => {
+		if (open) itemRefs.current[focused]?.focus();
+	}, [open, focused]);
+	/**
+	* Choose the side once the menu exists and can be measured. `useLayoutEffect` runs before
+	* paint, so the correction never shows as a jump — the menu is only ever painted where it
+	* belongs. Re-measured on resize and on scroll, since either can invalidate the choice.
+	*/
+	(0, react.useLayoutEffect)(() => {
+		if (!open) return;
+		const place = () => {
+			const trigger = triggerRef.current?.getBoundingClientRect();
+			const menu = menuRef.current?.getBoundingClientRect();
+			if (!trigger || !menu) return;
+			setSide(resolveSide(props.side ?? "auto", trigger, {
+				width: menu.width,
+				height: menu.height
+			}, {
+				width: window.innerWidth,
+				height: window.innerHeight
+			}));
+		};
+		place();
+		window.addEventListener("resize", place);
+		window.addEventListener("scroll", place, true);
+		return () => {
+			window.removeEventListener("resize", place);
+			window.removeEventListener("scroll", place, true);
+		};
+	}, [open, props.side]);
+	if (!isLoaded) return props.fallback ?? null;
+	if (!isSignedIn || !user) return null;
+	const name = user.displayName ?? user.email ?? "";
+	const builtIns = /* @__PURE__ */ new Map();
+	if (props.manageAccountUrl) builtIns.set("manageAccount", {
+		key: "manageAccount",
+		label: labels.manageAccount,
+		labelIcon: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(GearIcon, {}),
+		href: props.manageAccountUrl
+	});
+	builtIns.set("signOut", {
+		key: "signOut",
+		label: labels.signOut,
+		labelIcon: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ExitIcon, {}),
+		onClick: () => void signOut({
+			redirectTo: props.afterSignOutUrl,
+			onSignOut: props.onSignOut
+		})
+	});
+	if (props.showSignOutEverywhere) builtIns.set("signOutEverywhere", {
+		key: "signOutEverywhere",
+		label: labels.signOutEverywhere,
+		labelIcon: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ExitIcon, {}),
+		onClick: () => void signOut({
+			scope: "everywhere",
+			redirectTo: props.afterSignOutUrl,
+			onSignOut: props.onSignOut
+		})
+	});
+	const items = resolveItems(props.children, builtIns);
+	const customHeader = findHeader(props.children);
+	const navigable = items.map((item, index) => ({
+		item,
+		index
+	})).filter(({ item }) => !item.custom);
+	const onMenuKeyDown = (event) => {
+		if (navigable.length === 0) return;
+		if (event.key !== "ArrowDown" && event.key !== "ArrowUp") return;
+		event.preventDefault();
+		const next = (navigable.findIndex(({ index }) => index === focused) + (event.key === "ArrowDown" ? 1 : -1) + navigable.length) % navigable.length;
+		setFocused(navigable[next].index);
+	};
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+		className: [
+			"polyx-signin",
+			"polyx-userbutton",
+			props.className
+		].filter(Boolean).join(" "),
+		"data-polyx-userbutton": open ? "open" : "closed",
+		children: [/* @__PURE__ */ (0, react_jsx_runtime.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__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(UserAvatar, {
+				src: user.avatarUrl,
+				name,
+				size: props.avatarSize
+			}), props.showName ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+				className: "polyx-userbutton__trigger-name",
+				children: name
+			}) : null] })
+		}), open ? /* @__PURE__ */ (0, react_jsx_runtime.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__ */ (0, react_jsx_runtime.jsxs)("div", {
+				className: "polyx-userbutton__identity",
+				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(UserAvatar, {
+					src: user.avatarUrl,
+					name,
+					size: 36
+				}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+					className: "polyx-userbutton__identity-text",
+					children: [user.displayName ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+						className: "polyx-userbutton__name",
+						children: user.displayName
+					}) : null, user.email ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+						className: "polyx-userbutton__email",
+						children: user.email
+					}) : null]
+				})]
+			}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("ul", {
+				className: "polyx-userbutton__items",
+				children: items.map((item, index) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("li", { children: item.custom ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+					className: "polyx-userbutton__custom",
+					children: item.custom
+				}) : item.href ? /* @__PURE__ */ (0, react_jsx_runtime.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__ */ (0, react_jsx_runtime.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]
+	});
+}
+function GearIcon() {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("svg", {
+		className: "polyx-userbutton__icon",
+		viewBox: "0 0 16 16",
+		fill: "none",
+		"aria-hidden": "true",
+		focusable: "false",
+		children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("circle", {
+			cx: "8",
+			cy: "8",
+			r: "2.25",
+			stroke: "currentColor",
+			strokeWidth: "1.3"
+		}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("path", {
+			d: "M8 1.75v1.5M8 12.75v1.5M14.25 8h-1.5M3.25 8h-1.5M12.42 3.58l-1.06 1.06M4.64 11.36l-1.06 1.06M12.42 12.42l-1.06-1.06M4.64 4.64L3.58 3.58",
+			stroke: "currentColor",
+			strokeWidth: "1.3",
+			strokeLinecap: "round"
+		})]
+	});
+}
+function ExitIcon() {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("svg", {
+		className: "polyx-userbutton__icon",
+		viewBox: "0 0 16 16",
+		fill: "none",
+		"aria-hidden": "true",
+		focusable: "false",
+		children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("path", {
+			d: "M6 2.75H3.75a1 1 0 0 0-1 1v8.5a1 1 0 0 0 1 1H6M10.5 10.5 13 8l-2.5-2.5M13 8H6",
+			stroke: "currentColor",
+			strokeWidth: "1.3",
+			strokeLinecap: "round",
+			strokeLinejoin: "round"
+		})
+	});
+}
+/**
+* The signed-in user surface: avatar trigger + a menu with their identity and sign-out
+* (FR-SIGNIN-6). Reads only the hooks, so it behaves identically under either custody model
+* — an httpOnly BFF session or an in-memory SPA one — and needs no provider in a
+* `@poly-x/next` app.
+*
+* Custom entries compose declaratively:
+*
+* ```tsx
+* <UserButton manageAccountUrl="/account">
+*   <UserButton.MenuItems>
+*     <UserButton.Action label="signOut" />          // reposition a built-in
+*     <UserButton.Link label="Docs" href="/docs" />
+*   </UserButton.MenuItems>
+* </UserButton>
+* ```
+*/
+const UserButton = Object.assign(UserButtonRoot, {
+	MenuItems,
+	Action,
+	Link,
+	Custom,
+	Header
+});
+//#endregion
+//#region src/live-authz.ts
+const DEFAULT_POLL_MS = 6e4;
+const DEFAULT_FOCUS_THROTTLE_MS = 5e3;
+/** Wire the triggers and return a handle. Safe to call with no window/document (SSR → no-op wiring). */
+function startLiveAuthz(opts) {
+	const pollMs = opts.pollMs ?? DEFAULT_POLL_MS;
+	const throttleMs = opts.focusThrottleMs ?? DEFAULT_FOCUS_THROTTLE_MS;
+	const win = opts.win ?? (typeof window !== "undefined" ? window : void 0);
+	const doc = opts.doc ?? (typeof document !== "undefined" ? document : void 0);
+	let stopped = false;
+	let inFlight = false;
+	let pending = false;
+	let lastRefreshAt = -Infinity;
+	/**
+	* Single-flight refresh (FR-LIVE-5). `coalesce` = queue exactly one follow-up run if a refresh
+	* is already in flight — used by the explicit push signal so a change mid-refresh isn't missed.
+	* Ambient triggers (focus/online/poll) pass `false`: if a refresh is already running, drop —
+	* they carry no new information the in-flight run won't already pick up.
+	*/
+	async function run(coalesce) {
+		if (stopped) return;
+		if (inFlight) {
+			if (coalesce) pending = true;
+			return;
+		}
+		inFlight = true;
+		try {
+			let changed = false;
+			try {
+				changed = await opts.refresh();
+			} catch {}
+			lastRefreshAt = Date.now();
+			if (changed && !stopped) opts.onChanged?.();
+		} finally {
+			inFlight = false;
+			if (pending && !stopped) {
+				pending = false;
+				run(true);
+			}
+		}
+	}
+	/** Throttled, non-queuing refresh for ambient triggers (focus/visible/online). */
+	function throttledRun() {
+		if (Date.now() - lastRefreshAt >= throttleMs) run(false);
+	}
+	const isVisible = () => !doc || doc.visibilityState !== "hidden";
+	const onFocus = () => throttledRun();
+	const onOnline = () => throttledRun();
+	const onVisibility = () => {
+		if (isVisible()) throttledRun();
+	};
+	if (win) {
+		win.addEventListener("focus", onFocus);
+		win.addEventListener("online", onOnline);
+	}
+	if (doc) doc.addEventListener("visibilitychange", onVisibility);
+	const unsubscribeSignal = opts.subscribeSignal?.(() => void run(true));
+	let pollTimer;
+	if (pollMs > 0) pollTimer = setInterval(() => {
+		if (isVisible()) run(false);
+	}, pollMs);
+	return {
+		refreshNow: () => void run(true),
+		stop: () => {
+			if (stopped) return;
+			stopped = true;
+			if (win) {
+				win.removeEventListener("focus", onFocus);
+				win.removeEventListener("online", onOnline);
+			}
+			if (doc) doc.removeEventListener("visibilitychange", onVisibility);
+			unsubscribeSignal?.();
+			if (pollTimer !== void 0) clearInterval(pollTimer);
+		}
+	};
+}
+//#endregion
+//#region src/live-session.ts
+/**
+* @poly-x/react/live-session — the React glue that keeps the BFF session live (SDK v2).
+*
+* `useLiveAuthz` starts the framework-agnostic orchestrator (`startLiveAuthz`, F013) bound to the
+* BFF session store's `refresh()`: the platform `authz:changed` signal (when a `subscribeSignal`
+* transport is supplied) + window focus/reconnect + a ~60s safety poll → a single-flight
+* re-introspect that updates reactive `useUser()`. `useAuthzChanged` lets an app with its own guard
+* layer react to a change (FR-REACT-1). Apps that gate on `useUser()` re-guard automatically
+* (FR-REACT-2) — they need no callback.
+*
+* The `subscribeSignal` transport is optional: without it the passive triggers still converge
+* (FR-SIG-4). The default poly-alert transport is provided separately (a later slice) once the
+* subscription-credential custody decision lands.
+*/
+const changeListeners = /* @__PURE__ */ new Set();
+function emitChanged() {
+	for (const listener of changeListeners) listener();
+}
+/**
+* Start the live-authz orchestrator for this app's BFF session. Mount once (e.g. in the app root).
+* Returns nothing; drives `useUser()` reactivity + fires `useAuthzChanged` callbacks on a change.
+*/
+function useLiveAuthz(options = {}) {
+	const { subscribeSignal, pollMs, focusThrottleMs } = options;
+	(0, react.useEffect)(() => {
+		const store = getBffSessionStore();
+		const handle = startLiveAuthz({
+			refresh: () => store.refresh(),
+			onChanged: emitChanged,
+			subscribeSignal,
+			pollMs,
+			focusThrottleMs
+		});
+		return () => handle.stop();
+	}, [
+		subscribeSignal,
+		pollMs,
+		focusThrottleMs
+	]);
+}
+/**
+* Register a callback fired when the user's authorization changes (FR-REACT-1) — for apps that keep
+* their own ability/route model and need to re-run their guard or refetch view data. Apps that gate
+* on `useUser()` do not need this. Requires `useLiveAuthz` to be mounted somewhere in the tree.
+*/
+function useAuthzChanged(callback) {
+	(0, react.useEffect)(() => {
+		changeListeners.add(callback);
+		return () => {
+			changeListeners.delete(callback);
+		};
+	}, [callback]);
+}
+//#endregion
 //#region src/index.ts
 /**
 * @poly-x/react — PolyX SDK for React SPAs. Sign-in UI + orchestration land in
@@ -1269,11 +2132,19 @@ exports.Protected = Protected;
 exports.ResetPassword = ResetPassword;
 exports.SessionStoragePkceStore = SessionStoragePkceStore;
 exports.SignIn = SignIn;
+exports.UserAvatar = UserAvatar;
+exports.UserButton = UserButton;
 exports.WebLocksLock = WebLocksLock;
 exports.WindowBrowserBridge = WindowBrowserBridge;
+exports.capturePreciseLocation = capturePreciseLocation;
 exports.createLoginController = createLoginController;
+exports.initialsFrom = initialsFrom;
+exports.resolveSide = resolveSide;
+exports.startLiveAuthz = startLiveAuthz;
 exports.useAuth = useAuth;
 exports.useAuthCallback = useAuthCallback;
+exports.useAuthzChanged = useAuthzChanged;
+exports.useLiveAuthz = useLiveAuthz;
 exports.useSession = useSession;
 exports.useUser = useUser;
 exports.version = version;