@poly-x/react 0.1.0-alpha.1 → 0.1.0-alpha.11

package/dist/index.mjs

@@ -1,7 +1,7 @@
 "use client";
 import { AuthClient, FetchTransport, InMemoryLock, InMemoryPkceStore, InMemorySessionChannel, InMemorySessionStore, createSessionEngine, generatePkce, randomState, resolveConfig } from "@poly-x/core";
-import { createContext, useCallback, useContext, useEffect, useMemo, useSyncExternalStore } from "react";
-import { jsx } from "react/jsx-runtime";
+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";
 //#region src/auth-channel.ts
 var BroadcastAuthChannel = class {
 	supported;
@@ -299,31 +299,188 @@ 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;
+		}
+	}
+	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"
+		});
+		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 = 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 = useCallback((onChange) => engine.subscribe(onChange), [engine]);
-	const getSnapshot = useCallback(() => engine.getState(), [engine]);
-	return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+	const { source } = useSessionSource();
+	return useSyncExternalStore(useCallback((onChange) => source.subscribe(onChange), [source]), useCallback(() => source.getState(), [source]), useCallback(() => (source.getServerState ?? source.getState)(), [source]));
 }
 function useAuth() {
-	const { engine, controller } = usePolyX();
+	const ctx = useContext(PolyXContext);
+	const { source } = useSessionSource();
 	const state = useSession();
-	const signIn = useCallback((options) => controller.signIn(options), [controller]);
-	const signOut = useCallback(() => engine.signOut(), [engine]);
-	const getToken = useCallback(async () => {
-		try {
-			return await engine.getAccessToken();
-		} catch {
-			return null;
-		}
-	}, [engine]);
+	const signIn = 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 = useCallback((options) => source.signOut(options), [source]);
+	const getToken = useCallback(() => source.getToken(), [source]);
 	return {
 		isLoaded: state.status !== "resolving",
 		isSignedIn: state.status === "authenticated" || state.status === "refreshing",
@@ -334,8 +491,11 @@ function useAuth() {
 }
 /** Run this on your callback route to complete a sign-in (see `<AuthCallback>`). */
 function useAuthCallback() {
-	const { controller } = usePolyX();
-	return useCallback(() => controller.handleCallback(), [controller]);
+	const ctx = useContext(PolyXContext);
+	return 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,14 +511,890 @@ function Protected({ children, fallback = null, loading = null }) {
 }
 //#endregion
 //#region src/components/sign-in.tsx
-/** Minimal sign-in trigger — popup by default. Style via `className`/children. */
-function SignIn({ children, className, ...options }) {
-	const { signIn } = useAuth();
-	return /* @__PURE__ */ jsx("button", {
-		type: "button",
-		className,
-		onClick: () => void signIn(options),
-		children: children ?? "Sign in"
+const DEFAULT_LABELS$3 = {
+	heading: "Sign in",
+	subheading: "Enter your credentials to continue.",
+	tagline: "",
+	emailLabel: "Email",
+	emailPlaceholder: "you@company.com",
+	passwordLabel: "Password",
+	passwordPlaceholder: "••••••••",
+	showPassword: "Show password",
+	hidePassword: "Hide password",
+	submit: "Sign in",
+	submitting: "Signing in…",
+	forgotPassword: "Forgot password?",
+	chooseWorkspace: "Choose a workspace",
+	chooseWorkspaceSubheading: "You have access to more than one workspace.",
+	securedBy: "Secured by PolyX",
+	setPasswordHeading: "Choose a new password",
+	setPasswordSubheading: "Your temporary password must be replaced before you continue.",
+	newPasswordLabel: "New password",
+	confirmPasswordLabel: "Confirm new password",
+	setPasswordSubmit: "Set password and sign in",
+	passwordMismatch: "Those passwords don't match.",
+	weakPassword: "Password must be at least 6 characters.",
+	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."
+};
+/** Mirrors poly-auth's own floor (Joi: min 6). */
+const MIN_PASSWORD_LENGTH = 6;
+function EyeIcon() {
+	return /* @__PURE__ */ jsxs("svg", {
+		viewBox: "0 0 24 24",
+		fill: "none",
+		stroke: "currentColor",
+		strokeWidth: "2",
+		strokeLinecap: "round",
+		strokeLinejoin: "round",
+		"aria-hidden": "true",
+		focusable: "false",
+		children: [/* @__PURE__ */ jsx("path", { d: "M2 12s3.5-7 10-7 10 7 10 7-3.5 7-10 7-10-7-10-7Z" }), /* @__PURE__ */ jsx("circle", {
+			cx: "12",
+			cy: "12",
+			r: "3"
+		})]
+	});
+}
+function EyeOffIcon() {
+	return /* @__PURE__ */ jsxs("svg", {
+		viewBox: "0 0 24 24",
+		fill: "none",
+		stroke: "currentColor",
+		strokeWidth: "2",
+		strokeLinecap: "round",
+		strokeLinejoin: "round",
+		"aria-hidden": "true",
+		focusable: "false",
+		children: [/* @__PURE__ */ jsx("path", { d: "M9.88 4.24A9.1 9.1 0 0 1 12 4c6.5 0 10 7 10 7a13.2 13.2 0 0 1-1.67 2.68M6.61 6.61A13.5 13.5 0 0 0 2 12s3.5 7 10 7a9.7 9.7 0 0 0 5.39-1.61" }), /* @__PURE__ */ jsx("line", {
+			x1: "2",
+			y1: "2",
+			x2: "22",
+			y2: "22"
+		})]
+	});
+}
+/** A password input with an accessible show/hide reveal toggle (own visibility state). */
+function PasswordField(props) {
+	const [visible, setVisible] = useState(false);
+	return /* @__PURE__ */ jsxs("div", {
+		className: "polyx-signin__field",
+		children: [/* @__PURE__ */ jsx("label", {
+			className: "polyx-signin__label",
+			htmlFor: props.id,
+			children: props.label
+		}), /* @__PURE__ */ jsxs("div", {
+			className: "polyx-signin__input-wrap",
+			children: [/* @__PURE__ */ jsx("input", {
+				id: props.id,
+				className: "polyx-signin__input polyx-signin__input--has-reveal",
+				type: visible ? "text" : "password",
+				name: props.name,
+				autoComplete: props.autoComplete,
+				placeholder: props.placeholder,
+				required: true,
+				minLength: props.minLength,
+				value: props.value,
+				disabled: props.disabled,
+				onChange: (event) => props.onChange(event.target.value)
+			}), /* @__PURE__ */ jsx("button", {
+				type: "button",
+				className: "polyx-signin__reveal",
+				"aria-pressed": visible,
+				"aria-label": visible ? props.hideLabel : props.showLabel,
+				title: visible ? props.hideLabel : props.showLabel,
+				disabled: props.disabled,
+				onClick: () => setVisible((value) => !value),
+				children: visible ? /* @__PURE__ */ jsx(EyeOffIcon, {}) : /* @__PURE__ */ jsx(EyeIcon, {})
+			})]
+		})]
+	});
+}
+/**
+* The embedded, Clerk-style sign-in form (D2b). Renders email/password inside the
+* consuming app and POSTs to the SDK's BFF (`@poly-x/next` `authenticate`), which
+* runs the credential authorize server-side and seals an httpOnly session — no
+* redirect to a hosted PolyX login page, no tokens or credentials in the browser
+* after submit. Handles the workspace picker (select_tenant) inline.
+*
+* Ships styled: `import "@poly-x/react/styles.css"` once, then theme it by
+* overriding the `--polyx-*` custom properties on any ancestor.
+*/
+function SignIn(props) {
+	const action = props.action ?? "/api/polyx/authenticate";
+	const variant = props.variant ?? "card";
+	const labels = {
+		...DEFAULT_LABELS$3,
+		...props.labels
+	};
+	const [email, setEmail] = useState("");
+	const [password, setPassword] = useState("");
+	const [newPassword, setNewPassword] = useState("");
+	const [confirmPassword, setConfirmPassword] = useState("");
+	const [mustSetPassword, setMustSetPassword] = useState(false);
+	const [tenants, setTenants] = useState(null);
+	const [submitting, setSubmitting] = useState(false);
+	const [error, setError] = useState(null);
+	const polyx = useContext(PolyXContext);
+	const [branding, setBranding] = useState({});
+	useEffect(() => {
+		if (!polyx) return;
+		let active = true;
+		polyx.authClient.fetchBranding(props.organizationCode ? { organizationCode: props.organizationCode } : {}).then((tokens) => {
+			if (active) setBranding(tokens);
+		});
+		return () => {
+			active = false;
+		};
+	}, [polyx, props.organizationCode]);
+	const brandingStyle = {};
+	if (branding.primaryColor) brandingStyle["--polyx-brand"] = branding.primaryColor;
+	if (branding.backgroundColor) {
+		brandingStyle["--polyx-bg"] = branding.backgroundColor;
+		brandingStyle["--polyx-page-bg"] = branding.backgroundColor;
+	}
+	const brandingLogo = props.logo ?? (branding.logoUrl ? /* @__PURE__ */ jsx("img", {
+		className: "polyx-signin__brand-logo",
+		src: branding.logoUrl,
+		alt: branding.displayName ?? ""
+	}) : void 0);
+	/**
+	* One round-trip to the BFF. `tenantId` picks a workspace; `passwords` completes
+	* the temp-password flow (the BFF re-verifies the temporary password, sets the
+	* new one, and signs the user straight in).
+	*/
+	async function authenticate(options = {}) {
+		setSubmitting(true);
+		setError(null);
+		try {
+			const body = await (await fetch(action, {
+				method: "POST",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify({
+					email,
+					password,
+					organizationCode: props.organizationCode,
+					tenantId: options.tenantId,
+					...options.passwords
+				})
+			})).json().catch(() => ({}));
+			switch (body.status) {
+				case "success":
+					window.location.assign(props.afterSignInPath ?? body.redirectTo ?? "/");
+					return;
+				case "select_tenant":
+					setTenants(body.tenants ?? []);
+					return;
+				case "password_change_required":
+					setMustSetPassword(true);
+					if (body.userId) props.onPasswordChangeRequired?.(body.userId);
+					return;
+				case "password_mismatch":
+					setError(labels.passwordMismatch);
+					return;
+				case "weak_password":
+					setError(labels.weakPassword);
+					return;
+				case "invalid_credentials":
+					setError(labels.invalidCredentials);
+					return;
+				case "no_access":
+					setError(labels.noAccess);
+					return;
+				default:
+					setError(labels.genericError);
+					return;
+			}
+		} catch {
+			setError(labels.genericError);
+		} finally {
+			setSubmitting(false);
+		}
+	}
+	function onSubmit(event) {
+		event.preventDefault();
+		authenticate();
+	}
+	function onSetPasswordSubmit(event) {
+		event.preventDefault();
+		if (newPassword !== confirmPassword) {
+			setError(labels.passwordMismatch);
+			return;
+		}
+		authenticate({ passwords: {
+			newPassword,
+			confirmPassword
+		} });
+	}
+	const picking = tenants !== null;
+	const showHeaderLogo = Boolean(brandingLogo) && !(variant === "page");
+	const rootClass = [
+		"polyx-signin",
+		`polyx-signin--${variant}`,
+		props.className
+	].filter(Boolean).join(" ");
+	const step = picking ? "select_tenant" : mustSetPassword ? "set_password" : "credentials";
+	const HEADINGS = {
+		credentials: {
+			heading: labels.heading,
+			subheading: labels.subheading
+		},
+		select_tenant: {
+			heading: labels.chooseWorkspace,
+			subheading: labels.chooseWorkspaceSubheading
+		},
+		set_password: {
+			heading: labels.setPasswordHeading,
+			subheading: labels.setPasswordSubheading
+		}
+	};
+	const header = /* @__PURE__ */ jsxs("div", {
+		className: "polyx-signin__header",
+		children: [
+			showHeaderLogo ? /* @__PURE__ */ jsx("div", {
+				className: "polyx-signin__logo",
+				children: brandingLogo
+			}) : null,
+			/* @__PURE__ */ jsx("h1", {
+				className: "polyx-signin__heading",
+				children: HEADINGS[step].heading
+			}),
+			/* @__PURE__ */ jsx("p", {
+				className: "polyx-signin__subheading",
+				children: HEADINGS[step].subheading
+			})
+		]
+	});
+	const errorNode = error ? /* @__PURE__ */ jsx("p", {
+		role: "alert",
+		className: "polyx-signin__error",
+		children: error
+	}) : null;
+	const footer = props.showSecuredBy === false ? null : /* @__PURE__ */ jsxs("p", {
+		className: "polyx-signin__footer",
+		children: [/* @__PURE__ */ jsx("svg", {
+			className: "polyx-signin__shield",
+			viewBox: "0 0 16 16",
+			fill: "currentColor",
+			"aria-hidden": "true",
+			focusable: "false",
+			children: /* @__PURE__ */ jsx("path", { d: "M8 0.5 2 3v4.2c0 3.5 2.5 6.7 6 7.8 3.5-1.1 6-4.3 6-7.8V3L8 .5Zm2.9 5.6-3.4 3.4a.7.7 0 0 1-1 0L5.1 8.1a.7.7 0 1 1 1-1l.9.9 2.9-2.9a.7.7 0 0 1 1 1Z" })
+		}), labels.securedBy]
+	});
+	const tenantPicker = /* @__PURE__ */ jsxs("div", {
+		className: "polyx-signin__form",
+		children: [/* @__PURE__ */ jsx("ul", {
+			className: "polyx-signin__tenants",
+			children: (tenants ?? []).map((tenant) => /* @__PURE__ */ jsx("li", { children: /* @__PURE__ */ jsx("button", {
+				type: "button",
+				className: "polyx-signin__tenant",
+				disabled: submitting,
+				onClick: () => void authenticate({ tenantId: tenant.tenantId }),
+				children: tenant.name ?? tenant.slug ?? tenant.organizationCode ?? tenant.tenantId
+			}) }, tenant.tenantId))
+		}), errorNode]
+	});
+	const setPasswordForm = /* @__PURE__ */ jsxs("form", {
+		className: "polyx-signin__form",
+		onSubmit: onSetPasswordSubmit,
+		children: [
+			/* @__PURE__ */ jsx(PasswordField, {
+				id: "polyx-signin-new-password",
+				label: labels.newPasswordLabel,
+				name: "newPassword",
+				autoComplete: "new-password",
+				placeholder: labels.passwordPlaceholder,
+				minLength: MIN_PASSWORD_LENGTH,
+				value: newPassword,
+				disabled: submitting,
+				onChange: setNewPassword,
+				showLabel: labels.showPassword,
+				hideLabel: labels.hidePassword
+			}),
+			/* @__PURE__ */ jsx(PasswordField, {
+				id: "polyx-signin-confirm-password",
+				label: labels.confirmPasswordLabel,
+				name: "confirmPassword",
+				autoComplete: "new-password",
+				placeholder: labels.passwordPlaceholder,
+				minLength: MIN_PASSWORD_LENGTH,
+				value: confirmPassword,
+				disabled: submitting,
+				onChange: setConfirmPassword,
+				showLabel: labels.showPassword,
+				hideLabel: labels.hidePassword
+			}),
+			errorNode,
+			/* @__PURE__ */ jsx("button", {
+				type: "submit",
+				className: "polyx-signin__submit",
+				disabled: submitting,
+				children: submitting ? labels.submitting : labels.setPasswordSubmit
+			})
+		]
+	});
+	const card = /* @__PURE__ */ jsxs("div", {
+		className: "polyx-signin__card",
+		children: [
+			header,
+			step === "select_tenant" ? tenantPicker : step === "set_password" ? setPasswordForm : /* @__PURE__ */ jsxs("form", {
+				className: "polyx-signin__form",
+				onSubmit,
+				children: [
+					/* @__PURE__ */ jsxs("label", {
+						className: "polyx-signin__field",
+						children: [/* @__PURE__ */ jsx("span", {
+							className: "polyx-signin__label",
+							children: labels.emailLabel
+						}), /* @__PURE__ */ jsx("input", {
+							className: "polyx-signin__input",
+							type: "email",
+							name: "email",
+							autoComplete: "username",
+							placeholder: labels.emailPlaceholder,
+							required: true,
+							value: email,
+							disabled: submitting,
+							onChange: (event) => setEmail(event.target.value)
+						})]
+					}),
+					/* @__PURE__ */ jsx(PasswordField, {
+						id: "polyx-signin-password",
+						label: labels.passwordLabel,
+						name: "password",
+						autoComplete: "current-password",
+						placeholder: labels.passwordPlaceholder,
+						value: password,
+						disabled: submitting,
+						onChange: setPassword,
+						showLabel: labels.showPassword,
+						hideLabel: labels.hidePassword
+					}),
+					props.forgotPasswordUrl ? /* @__PURE__ */ jsx("div", {
+						className: "polyx-signin__forgot",
+						children: /* @__PURE__ */ jsx("a", {
+							className: "polyx-signin__link",
+							href: props.forgotPasswordUrl,
+							children: labels.forgotPassword
+						})
+					}) : null,
+					errorNode,
+					/* @__PURE__ */ jsx("button", {
+						type: "submit",
+						className: "polyx-signin__submit",
+						disabled: submitting,
+						children: submitting ? labels.submitting : labels.submit
+					})
+				]
+			}),
+			footer
+		]
+	});
+	if (variant === "page") return /* @__PURE__ */ jsxs("div", {
+		className: rootClass,
+		"data-polyx-signin": step,
+		style: brandingStyle,
+		children: [/* @__PURE__ */ jsx("aside", {
+			className: "polyx-signin__panel",
+			children: props.panel ?? /* @__PURE__ */ jsxs(Fragment$1, { children: [brandingLogo ? /* @__PURE__ */ jsx("div", {
+				className: "polyx-signin__panel-logo",
+				children: brandingLogo
+			}) : null, labels.tagline ? /* @__PURE__ */ jsx("p", {
+				className: "polyx-signin__tagline",
+				children: labels.tagline
+			}) : null] })
+		}), /* @__PURE__ */ jsx("div", {
+			className: "polyx-signin__main",
+			children: card
+		})]
+	});
+	return /* @__PURE__ */ jsx("div", {
+		className: rootClass,
+		"data-polyx-signin": step,
+		style: brandingStyle,
+		children: card
+	});
+}
+//#endregion
+//#region src/components/_recovery-status.tsx
+const ICONS = {
+	mail: /* @__PURE__ */ jsxs("svg", {
+		viewBox: "0 0 24 24",
+		fill: "none",
+		stroke: "currentColor",
+		strokeWidth: "1.75",
+		"aria-hidden": "true",
+		focusable: "false",
+		children: [/* @__PURE__ */ jsx("rect", {
+			x: "3",
+			y: "5",
+			width: "18",
+			height: "14",
+			rx: "2.5"
+		}), /* @__PURE__ */ jsx("path", {
+			d: "m4 7 8 6 8-6",
+			strokeLinecap: "round",
+			strokeLinejoin: "round"
+		})]
+	}),
+	check: /* @__PURE__ */ jsx("svg", {
+		viewBox: "0 0 24 24",
+		fill: "none",
+		stroke: "currentColor",
+		strokeWidth: "2",
+		"aria-hidden": "true",
+		focusable: "false",
+		children: /* @__PURE__ */ jsx("path", {
+			d: "m5 12.5 4.5 4.5L19 7",
+			strokeLinecap: "round",
+			strokeLinejoin: "round"
+		})
+	}),
+	warning: /* @__PURE__ */ jsxs("svg", {
+		viewBox: "0 0 24 24",
+		fill: "none",
+		stroke: "currentColor",
+		strokeWidth: "1.75",
+		"aria-hidden": "true",
+		focusable: "false",
+		children: [
+			/* @__PURE__ */ jsx("circle", {
+				cx: "12",
+				cy: "12",
+				r: "9"
+			}),
+			/* @__PURE__ */ jsx("path", {
+				d: "M12 7.5v5",
+				strokeLinecap: "round"
+			}),
+			/* @__PURE__ */ jsx("circle", {
+				cx: "12",
+				cy: "16",
+				r: "0.6",
+				fill: "currentColor",
+				stroke: "none"
+			})
+		]
+	})
+};
+/**
+* A centered, icon-topped confirmation card — the shape every recovery terminal
+* state shares (link sent, password updated, link expired). Reuses the `<SignIn/>`
+* class anatomy so it themes from the same `--polyx-*` custom properties.
+*/
+function RecoveryStatus(props) {
+	return /* @__PURE__ */ jsxs("div", {
+		className: "polyx-signin__card",
+		children: [
+			/* @__PURE__ */ jsxs("div", {
+				className: "polyx-signin__header polyx-signin__header--center",
+				children: [
+					/* @__PURE__ */ jsx("span", {
+						className: `polyx-signin__status-icon polyx-signin__status-icon--${props.tone ?? "brand"}`,
+						children: ICONS[props.icon]
+					}),
+					/* @__PURE__ */ jsx("h1", {
+						className: "polyx-signin__heading",
+						children: props.heading
+					}),
+					/* @__PURE__ */ jsx("p", {
+						className: "polyx-signin__subheading",
+						children: props.children
+					})
+				]
+			}),
+			props.actions ? /* @__PURE__ */ jsx("div", {
+				className: "polyx-signin__actions",
+				children: props.actions
+			}) : null,
+			props.footer
+		]
+	});
+}
+//#endregion
+//#region src/components/forgot-password.tsx
+const DEFAULT_LABELS$2 = {
+	heading: "Reset your password",
+	subheading: "Enter your email and we'll send you a reset link.",
+	emailLabel: "Email",
+	emailPlaceholder: "you@company.com",
+	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.",
+	differentEmail: "Use a different email",
+	backToSignIn: "Back to sign in",
+	securedBy: "Secured by PolyX",
+	genericError: "Something went wrong. Please try again."
+};
+/** Splits a label on `{email}` and drops the entered address in, emphasized. */
+function withEmail(template, email) {
+	return template.split("{email}").map((chunk, index, all) => /* @__PURE__ */ jsxs(Fragment, { children: [chunk, index < all.length - 1 ? /* @__PURE__ */ jsx("span", {
+		className: "polyx-signin__email",
+		children: email || "that address"
+	}) : null] }, index));
+}
+/**
+* The self-service "forgot password" form (poly-x v5 / F040). Renders an email field
+* inside the consuming app and POSTs to the SDK's BFF (`@poly-x/next` `forgotPassword`),
+* which asks poly-auth to email a single-use reset link SERVER-SIDE. The response is
+* always the same — no token, no account-existence signal — so after submit the form
+* shows an identical "check your email" state whether or not the account exists.
+*
+* Reuses the `<SignIn/>` styling: `import "@poly-x/react/styles.css"` once, then theme
+* via the `--polyx-*` custom properties. Target `.polyx-forgot` for form-specific tweaks.
+*/
+function ForgotPassword(props) {
+	const action = props.action ?? "/api/polyx/forgot-password";
+	const signInPath = props.signInPath ?? "/sign-in";
+	const labels = {
+		...DEFAULT_LABELS$2,
+		...props.labels
+	};
+	const [email, setEmail] = useState("");
+	const [submitting, setSubmitting] = useState(false);
+	const [sent, setSent] = useState(false);
+	const [error, setError] = useState(null);
+	async function onSubmit(event) {
+		event.preventDefault();
+		setSubmitting(true);
+		setError(null);
+		try {
+			if ((await (await fetch(action, {
+				method: "POST",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify({ email })
+			})).json().catch(() => ({}))).status === "accepted") {
+				setSent(true);
+				return;
+			}
+			setError(labels.genericError);
+		} catch {
+			setError(labels.genericError);
+		} finally {
+			setSubmitting(false);
+		}
+	}
+	const rootClass = [
+		"polyx-signin",
+		"polyx-forgot",
+		props.className
+	].filter(Boolean).join(" ");
+	const footer = props.showSecuredBy === false ? null : /* @__PURE__ */ jsxs("p", {
+		className: "polyx-signin__footer",
+		children: [/* @__PURE__ */ jsx("svg", {
+			className: "polyx-signin__shield",
+			viewBox: "0 0 16 16",
+			fill: "currentColor",
+			"aria-hidden": "true",
+			focusable: "false",
+			children: /* @__PURE__ */ jsx("path", { d: "M8 0.5 2 3v4.2c0 3.5 2.5 6.7 6 7.8 3.5-1.1 6-4.3 6-7.8V3L8 .5Zm2.9 5.6-3.4 3.4a.7.7 0 0 1-1 0L5.1 8.1a.7.7 0 1 1 1-1l.9.9 2.9-2.9a.7.7 0 0 1 1 1Z" })
+		}), labels.securedBy]
+	});
+	const header = (heading, subheading) => /* @__PURE__ */ jsxs("div", {
+		className: "polyx-signin__header",
+		children: [
+			props.logo ? /* @__PURE__ */ jsx("div", {
+				className: "polyx-signin__logo",
+				children: props.logo
+			}) : null,
+			/* @__PURE__ */ jsx("h1", {
+				className: "polyx-signin__heading",
+				children: heading
+			}),
+			/* @__PURE__ */ jsx("p", {
+				className: "polyx-signin__subheading",
+				children: subheading
+			})
+		]
+	});
+	if (sent) return /* @__PURE__ */ jsx("div", {
+		className: rootClass,
+		"data-polyx-forgot": "sent",
+		children: /* @__PURE__ */ jsx(RecoveryStatus, {
+			icon: "mail",
+			heading: labels.sentHeading,
+			footer,
+			actions: /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx("button", {
+				type: "button",
+				className: "polyx-signin__link",
+				onClick: () => setSent(false),
+				children: labels.differentEmail
+			}), /* @__PURE__ */ jsx("a", {
+				className: "polyx-signin__link",
+				href: signInPath,
+				children: labels.backToSignIn
+			})] }),
+			children: withEmail(labels.sentSubheading, email)
+		})
+	});
+	return /* @__PURE__ */ jsx("div", {
+		className: rootClass,
+		"data-polyx-forgot": "request",
+		children: /* @__PURE__ */ jsxs("div", {
+			className: "polyx-signin__card",
+			children: [
+				header(labels.heading, labels.subheading),
+				/* @__PURE__ */ jsxs("form", {
+					className: "polyx-signin__form",
+					onSubmit,
+					children: [
+						/* @__PURE__ */ jsxs("label", {
+							className: "polyx-signin__field",
+							children: [/* @__PURE__ */ jsx("span", {
+								className: "polyx-signin__label",
+								children: labels.emailLabel
+							}), /* @__PURE__ */ jsx("input", {
+								className: "polyx-signin__input",
+								type: "email",
+								name: "email",
+								autoComplete: "username",
+								placeholder: labels.emailPlaceholder,
+								required: true,
+								value: email,
+								disabled: submitting,
+								onChange: (event) => setEmail(event.target.value)
+							})]
+						}),
+						error ? /* @__PURE__ */ jsx("p", {
+							role: "alert",
+							className: "polyx-signin__error",
+							children: error
+						}) : null,
+						/* @__PURE__ */ jsx("button", {
+							type: "submit",
+							className: "polyx-signin__submit",
+							disabled: submitting,
+							children: submitting ? labels.submitting : labels.submit
+						})
+					]
+				}),
+				footer
+			]
+		})
+	});
+}
+//#endregion
+//#region src/components/reset-password.tsx
+const DEFAULT_LABELS$1 = {
+	heading: "Choose a new password",
+	subheading: "Enter and confirm your new password.",
+	newPasswordLabel: "New password",
+	confirmPasswordLabel: "Confirm new password",
+	passwordPlaceholder: "••••••••",
+	submit: "Reset password",
+	submitting: "Resetting…",
+	successHeading: "Password updated",
+	successSubheading: "You can now sign in with your new password.",
+	invalidHeading: "This link is invalid or expired",
+	invalidSubheading: "Password reset links can be used once and expire quickly. Request a new one.",
+	requestNewLink: "Request a new link",
+	backToSignIn: "Back to sign in",
+	securedBy: "Secured by PolyX",
+	passwordMismatch: "Those passwords don't match.",
+	weakPassword: "Password must be at least 8 characters.",
+	genericError: "Something went wrong. Please try again."
+};
+/** Matches poly-auth's v5 reset floor (F040). */
+const DEFAULT_MIN_LENGTH = 8;
+/**
+* The reset-completion form (poly-x v5 / F040). Reads the opaque token from the URL,
+* collects a new password, and POSTs to the SDK's BFF (`@poly-x/next` `resetPassword`),
+* which redeems the token single-use server-side. The token is never decoded in the
+* browser — identity, validity, and expiry are all enforced by the backend.
+*
+* Reuses the `<SignIn/>` styling: `import "@poly-x/react/styles.css"` once, then theme
+* via the `--polyx-*` custom properties. Target `.polyx-reset` for form-specific tweaks.
+*/
+function ResetPassword(props) {
+	const action = props.action ?? "/api/polyx/reset-password";
+	const minLength = props.minLength ?? DEFAULT_MIN_LENGTH;
+	const signInPath = props.signInPath ?? "/sign-in";
+	const forgotPasswordPath = props.forgotPasswordPath ?? "/forgot-password";
+	const labels = {
+		...DEFAULT_LABELS$1,
+		...props.labels
+	};
+	const [token] = useState(() => props.token ?? (typeof window !== "undefined" ? new URLSearchParams(window.location.search).get("token") ?? "" : ""));
+	const [newPassword, setNewPassword] = useState("");
+	const [confirmPassword, setConfirmPassword] = useState("");
+	const [submitting, setSubmitting] = useState(false);
+	const [error, setError] = useState(null);
+	const [step, setStep] = useState(token ? "form" : "invalid");
+	async function onSubmit(event) {
+		event.preventDefault();
+		if (newPassword !== confirmPassword) {
+			setError(labels.passwordMismatch);
+			return;
+		}
+		setSubmitting(true);
+		setError(null);
+		try {
+			switch ((await (await fetch(action, {
+				method: "POST",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify({
+					token,
+					newPassword,
+					confirmPassword
+				})
+			})).json().catch(() => ({}))).status) {
+				case "success":
+					setStep("success");
+					if (props.afterResetPath) window.location.assign(props.afterResetPath);
+					return;
+				case "weak_password":
+					setError(labels.weakPassword);
+					return;
+				case "password_mismatch":
+					setError(labels.passwordMismatch);
+					return;
+				case "invalid_or_expired":
+					setStep("invalid");
+					return;
+				default:
+					setError(labels.genericError);
+					return;
+			}
+		} catch {
+			setError(labels.genericError);
+		} finally {
+			setSubmitting(false);
+		}
+	}
+	const rootClass = [
+		"polyx-signin",
+		"polyx-reset",
+		props.className
+	].filter(Boolean).join(" ");
+	const footer = props.showSecuredBy === false ? null : /* @__PURE__ */ jsxs("p", {
+		className: "polyx-signin__footer",
+		children: [/* @__PURE__ */ jsx("svg", {
+			className: "polyx-signin__shield",
+			viewBox: "0 0 16 16",
+			fill: "currentColor",
+			"aria-hidden": "true",
+			focusable: "false",
+			children: /* @__PURE__ */ jsx("path", { d: "M8 0.5 2 3v4.2c0 3.5 2.5 6.7 6 7.8 3.5-1.1 6-4.3 6-7.8V3L8 .5Zm2.9 5.6-3.4 3.4a.7.7 0 0 1-1 0L5.1 8.1a.7.7 0 1 1 1-1l.9.9 2.9-2.9a.7.7 0 0 1 1 1Z" })
+		}), labels.securedBy]
+	});
+	const header = (heading, subheading) => /* @__PURE__ */ jsxs("div", {
+		className: "polyx-signin__header",
+		children: [
+			props.logo ? /* @__PURE__ */ jsx("div", {
+				className: "polyx-signin__logo",
+				children: props.logo
+			}) : null,
+			/* @__PURE__ */ jsx("h1", {
+				className: "polyx-signin__heading",
+				children: heading
+			}),
+			/* @__PURE__ */ jsx("p", {
+				className: "polyx-signin__subheading",
+				children: subheading
+			})
+		]
+	});
+	if (step === "success") return /* @__PURE__ */ jsx("div", {
+		className: rootClass,
+		"data-polyx-reset": "success",
+		children: /* @__PURE__ */ jsx(RecoveryStatus, {
+			icon: "check",
+			heading: labels.successHeading,
+			footer,
+			actions: /* @__PURE__ */ jsx("a", {
+				className: "polyx-signin__link",
+				href: signInPath,
+				children: labels.backToSignIn
+			}),
+			children: labels.successSubheading
+		})
+	});
+	if (step === "invalid") return /* @__PURE__ */ jsx("div", {
+		className: rootClass,
+		"data-polyx-reset": "invalid",
+		children: /* @__PURE__ */ jsx(RecoveryStatus, {
+			icon: "warning",
+			tone: "danger",
+			heading: labels.invalidHeading,
+			footer,
+			actions: /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx("a", {
+				className: "polyx-signin__link",
+				href: forgotPasswordPath,
+				children: labels.requestNewLink
+			}), /* @__PURE__ */ jsx("a", {
+				className: "polyx-signin__link",
+				href: signInPath,
+				children: labels.backToSignIn
+			})] }),
+			children: labels.invalidSubheading
+		})
+	});
+	return /* @__PURE__ */ jsx("div", {
+		className: rootClass,
+		"data-polyx-reset": step,
+		children: /* @__PURE__ */ jsxs("div", {
+			className: "polyx-signin__card",
+			children: [
+				header(labels.heading, labels.subheading),
+				/* @__PURE__ */ jsxs("form", {
+					className: "polyx-signin__form",
+					onSubmit,
+					children: [
+						/* @__PURE__ */ jsxs("label", {
+							className: "polyx-signin__field",
+							children: [/* @__PURE__ */ jsx("span", {
+								className: "polyx-signin__label",
+								children: labels.newPasswordLabel
+							}), /* @__PURE__ */ jsx("input", {
+								className: "polyx-signin__input",
+								type: "password",
+								name: "newPassword",
+								autoComplete: "new-password",
+								placeholder: labels.passwordPlaceholder,
+								required: true,
+								minLength,
+								value: newPassword,
+								disabled: submitting,
+								onChange: (event) => setNewPassword(event.target.value)
+							})]
+						}),
+						/* @__PURE__ */ jsxs("label", {
+							className: "polyx-signin__field",
+							children: [/* @__PURE__ */ jsx("span", {
+								className: "polyx-signin__label",
+								children: labels.confirmPasswordLabel
+							}), /* @__PURE__ */ jsx("input", {
+								className: "polyx-signin__input",
+								type: "password",
+								name: "confirmPassword",
+								autoComplete: "new-password",
+								placeholder: labels.passwordPlaceholder,
+								required: true,
+								minLength,
+								value: confirmPassword,
+								disabled: submitting,
+								onChange: (event) => setConfirmPassword(event.target.value)
+							})]
+						}),
+						error ? /* @__PURE__ */ jsx("p", {
+							role: "alert",
+							className: "polyx-signin__error",
+							children: error
+						}) : null,
+						/* @__PURE__ */ jsx("button", {
+							type: "submit",
+							className: "polyx-signin__submit",
+							disabled: submitting,
+							children: submitting ? labels.submitting : labels.submit
+						})
+					]
+				}),
+				footer
+			]
+		})
 	});
 }
 //#endregion
@@ -372,6 +1408,442 @@ 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__ */ jsx("img", {
+		className: rootClass,
+		style,
+		src,
+		alt: name ?? ""
+	});
+	return /* @__PURE__ */ 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();
+	Children.forEach(children, (child) => {
+		if (!isValidElement(child) || child.type !== MenuItems) return;
+		Children.forEach(child.props.children, (item, index) => {
+			if (!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;
+	Children.forEach(children, (child) => {
+		if (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] = useState(props.defaultOpen ?? false);
+	const [focused, setFocused] = useState(0);
+	const [side, setSide] = useState(props.side && props.side !== "auto" ? props.side : "bottom");
+	const triggerRef = useRef(null);
+	const menuRef = useRef(null);
+	const itemRefs = useRef([]);
+	const menuId = useId();
+	const align = props.align ?? "end";
+	const close = useCallback((returnFocus) => {
+		setOpen(false);
+		if (returnFocus) triggerRef.current?.focus();
+	}, []);
+	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]);
+	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.
+	*/
+	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__ */ jsx(GearIcon, {}),
+		href: props.manageAccountUrl
+	});
+	builtIns.set("signOut", {
+		key: "signOut",
+		label: labels.signOut,
+		labelIcon: /* @__PURE__ */ jsx(ExitIcon, {}),
+		onClick: () => void signOut({ redirectTo: props.afterSignOutUrl })
+	});
+	if (props.showSignOutEverywhere) builtIns.set("signOutEverywhere", {
+		key: "signOutEverywhere",
+		label: labels.signOutEverywhere,
+		labelIcon: /* @__PURE__ */ jsx(ExitIcon, {}),
+		onClick: () => void signOut({
+			scope: "everywhere",
+			redirectTo: props.afterSignOutUrl
+		})
+	});
+	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__ */ jsxs("div", {
+		className: [
+			"polyx-signin",
+			"polyx-userbutton",
+			props.className
+		].filter(Boolean).join(" "),
+		"data-polyx-userbutton": open ? "open" : "closed",
+		children: [/* @__PURE__ */ jsx("button", {
+			ref: triggerRef,
+			type: "button",
+			className: "polyx-userbutton__trigger",
+			"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, {
+					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))
+			})]
+		}) : null]
+	});
+}
+function GearIcon() {
+	return /* @__PURE__ */ jsxs("svg", {
+		className: "polyx-userbutton__icon",
+		viewBox: "0 0 16 16",
+		fill: "none",
+		"aria-hidden": "true",
+		focusable: "false",
+		children: [/* @__PURE__ */ jsx("circle", {
+			cx: "8",
+			cy: "8",
+			r: "2.25",
+			stroke: "currentColor",
+			strokeWidth: "1.3"
+		}), /* @__PURE__ */ 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__ */ jsx("svg", {
+		className: "polyx-userbutton__icon",
+		viewBox: "0 0 16 16",
+		fill: "none",
+		"aria-hidden": "true",
+		focusable: "false",
+		children: /* @__PURE__ */ 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/index.ts
 /**
 * @poly-x/react — PolyX SDK for React SPAs. Sign-in UI + orchestration land in
@@ -380,4 +1852,4 @@ function AuthCallback({ children = null }) {
 const PACKAGE_NAME = "@poly-x/react";
 const version = "0.0.0";
 //#endregion
-export { AuthCallback, BroadcastAuthChannel, BroadcastChannelSessionChannel, PACKAGE_NAME, PolyXContext, PolyXProvider, PopupCancelledError, Protected, SessionStoragePkceStore, SignIn, WebLocksLock, WindowBrowserBridge, createLoginController, useAuth, useAuthCallback, useSession, useUser, version };
+export { AuthCallback, BroadcastAuthChannel, BroadcastChannelSessionChannel, ForgotPassword, PACKAGE_NAME, PolyXContext, PolyXProvider, PopupCancelledError, Protected, ResetPassword, SessionStoragePkceStore, SignIn, UserAvatar, UserButton, WebLocksLock, WindowBrowserBridge, createLoginController, initialsFrom, resolveSide, useAuth, useAuthCallback, useSession, useUser, version };