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

package/dist/index.d.cts

@@ -18,6 +18,14 @@ declare function PolyXProvider({
   children
 }: PolyXProviderProps): ReactNode;
 //#endregion
+//#region src/bff-session.d.ts
+interface BffSignOutOptions {
+  /** `everywhere` ends every session for the user (FR-SSO-5). Default `device`. */
+  scope?: "device" | "everywhere";
+  /** Where to land afterwards. Resolved here, client-side — the server takes no redirect target. */
+  redirectTo?: string;
+}
+//#endregion
 //#region src/auth-channel.d.ts
 /**
  * Same-origin popup→opener handoff of the authorization `code` (F006). The
@@ -115,8 +123,11 @@ interface UseAuth {
   isLoaded: boolean;
   isSignedIn: boolean;
   signIn: (options?: SignInOptions) => Promise<void>;
-  signOut: () => Promise<void>;
-  /** Current access token, refreshing if needed; null when signed out. */
+  signOut: (options?: BffSignOutOptions) => Promise<void>;
+  /**
+   * Current access token, refreshing if needed; null when signed out — and always null under
+   * BFF custody, where the token is httpOnly server-side by design (FR-SES-3).
+   */
   getToken: () => Promise<string | null>;
 }
 declare function useAuth(): UseAuth;
@@ -191,16 +202,179 @@ declare function Protected({
 }: ProtectedProps): ReactNode;
 //#endregion
 //#region src/components/sign-in.d.ts
-interface SignInProps extends SignInOptions {
-  children?: ReactNode;
+/** Every user-facing string, overridable for i18n / white-labelling. */
+interface SignInLabels {
+  heading: string;
+  subheading: string;
+  /** Headline on the `page` variant's brand panel. Empty renders a clean brand panel. */
+  tagline: string;
+  emailLabel: string;
+  emailPlaceholder: string;
+  passwordLabel: string;
+  passwordPlaceholder: string;
+  /** Reveal-toggle a11y labels (aria-label / tooltip on the show-hide button). */
+  showPassword: string;
+  hidePassword: string;
+  submit: string;
+  submitting: string;
+  forgotPassword: string;
+  chooseWorkspace: string;
+  chooseWorkspaceSubheading: string;
+  securedBy: string;
+  setPasswordHeading: string;
+  setPasswordSubheading: string;
+  newPasswordLabel: string;
+  confirmPasswordLabel: string;
+  setPasswordSubmit: string;
+  passwordMismatch: string;
+  weakPassword: string;
+  invalidCredentials: string;
+  noAccess: string;
+  passwordChangeRequired: string;
+  genericError: string;
+}
+/**
+ * `card` renders just the card — drop it into your own layout.
+ * `page` owns the viewport — a split layout with a brand panel beside the form
+ * (the panel collapses away under 64rem, leaving the form on its own).
+ */
+type SignInVariant = "card" | "page";
+interface SignInProps {
+  /** Layout preset. Default `card`. */
+  variant?: SignInVariant;
+  /**
+   * Content for the `page` variant's brand panel. Defaults to your `logo` plus
+   * `labels.tagline`; pass your own node to take the panel over completely.
+   * Ignored by the `card` variant.
+   */
+  panel?: ReactNode;
+  /** BFF endpoint backed by `createAuthHandlers().authenticate`. Default `/api/polyx/authenticate`. */
+  action?: string;
+  /**
+   * URL of your reset flow (where `<ForgotPassword/>` lives). When set, a
+   * "Forgot password?" link appears under the password field. Omit to hide it.
+   */
+  forgotPasswordUrl?: string;
+  /** Where to send the browser after success. Overrides the server's default redirect. */
+  afterSignInPath?: string;
+  /** Pre-scope the login to a single organization (skips org discovery). */
+  organizationCode?: string;
+  /** Rendered above the heading — your wordmark or logo. */
+  logo?: ReactNode;
+  /** Show the "Secured by PolyX" attribution under the form. Default true. */
+  showSecuredBy?: boolean;
+  /** Appended to the root element's class list, for escape-hatch styling. */
   className?: string;
+  labels?: Partial<SignInLabels>;
+  /** Fired when the backend requires the user to set a new password before continuing. */
+  onPasswordChangeRequired?: (userId: string) => void;
 }
-/** Minimal sign-in trigger — popup by default. Style via `className`/children. */
-declare function SignIn({
-  children,
-  className,
-  ...options
-}: SignInProps): ReactNode;
+/**
+ * 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.
+ */
+declare function SignIn(props: SignInProps): ReactNode;
+//#endregion
+//#region src/components/forgot-password.d.ts
+/** Every user-facing string, overridable for i18n / white-labelling. */
+interface ForgotPasswordLabels {
+  heading: string;
+  subheading: string;
+  emailLabel: string;
+  emailPlaceholder: string;
+  submit: string;
+  submitting: string;
+  /** Shown after submit — always, regardless of whether the account exists. */
+  sentHeading: string;
+  /** Confirmation body. `{email}` is replaced with the entered address, emphasized. */
+  sentSubheading: string;
+  differentEmail: string;
+  backToSignIn: string;
+  securedBy: string;
+  genericError: string;
+}
+interface ForgotPasswordProps {
+  /** BFF endpoint backed by `createAuthHandlers().forgotPassword`. Default `/api/polyx/forgot-password`. */
+  action?: string;
+  /** Where the "back to sign in" link points. Default `/sign-in`. */
+  signInPath?: string;
+  /** Rendered above the heading — your wordmark or logo. */
+  logo?: ReactNode;
+  /** Show the "Secured by PolyX" attribution under the form. Default true. */
+  showSecuredBy?: boolean;
+  /** Appended to the root element's class list, for escape-hatch styling. */
+  className?: string;
+  labels?: Partial<ForgotPasswordLabels>;
+}
+/**
+ * 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.
+ */
+declare function ForgotPassword(props: ForgotPasswordProps): ReactNode;
+//#endregion
+//#region src/components/reset-password.d.ts
+/** Every user-facing string, overridable for i18n / white-labelling. */
+interface ResetPasswordLabels {
+  heading: string;
+  subheading: string;
+  newPasswordLabel: string;
+  confirmPasswordLabel: string;
+  passwordPlaceholder: string;
+  submit: string;
+  submitting: string;
+  successHeading: string;
+  successSubheading: string;
+  invalidHeading: string;
+  invalidSubheading: string;
+  requestNewLink: string;
+  backToSignIn: string;
+  securedBy: string;
+  passwordMismatch: string;
+  weakPassword: string;
+  genericError: string;
+}
+interface ResetPasswordProps {
+  /** BFF endpoint backed by `createAuthHandlers().resetPassword`. Default `/api/polyx/reset-password`. */
+  action?: string;
+  /** The opaque reset token. Defaults to `?token=` from the URL (client-side). */
+  token?: string;
+  /** Where to send the browser after a successful reset. Default `/sign-in`. */
+  afterResetPath?: string;
+  /** Where "request a new link" / "back to sign in" point. Default `/forgot-password` and `/sign-in`. */
+  forgotPasswordPath?: string;
+  signInPath?: string;
+  /** Rendered above the heading — your wordmark or logo. */
+  logo?: ReactNode;
+  /** Show the "Secured by PolyX" attribution under the form. Default true. */
+  showSecuredBy?: boolean;
+  /** Client-side minimum password length (the backend enforces the real floor). Default 8. */
+  minLength?: number;
+  /** Appended to the root element's class list, for escape-hatch styling. */
+  className?: string;
+  labels?: Partial<ResetPasswordLabels>;
+}
+/**
+ * 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.
+ */
+declare function ResetPassword(props: ResetPasswordProps): ReactNode;
 //#endregion
 //#region src/components/auth-callback.d.ts
 interface AuthCallbackProps {
@@ -212,6 +386,100 @@ declare function AuthCallback({
   children
 }: AuthCallbackProps): ReactNode;
 //#endregion
+//#region src/components/user-button.d.ts
+/** Every user-facing string, overridable for i18n / white-labelling. */
+interface UserButtonLabels {
+  trigger: string;
+  manageAccount: string;
+  signOut: string;
+  signOutEverywhere: string;
+}
+interface UserButtonActionProps {
+  /**
+   * The menu entry's text — or the name of a built-in (`manageAccount`, `signOut`,
+   * `signOutEverywhere`) to place it at this position instead of appending a second copy.
+   */
+  label: string;
+  /** Icon rendered before the label. */
+  labelIcon?: ReactNode;
+  onClick?: () => void;
+}
+interface UserButtonLinkProps {
+  label: string;
+  labelIcon?: ReactNode;
+  href: string;
+}
+interface UserButtonProps {
+  /** Show the user's name next to the avatar. Default `false`. */
+  showName?: boolean;
+  /** Where to land after signing out. Default the app root. */
+  afterSignOutUrl?: string;
+  /**
+   * Destination for the "Manage account" entry. Omitted entirely when unset — PolyX has no
+   * hosted profile page, so the destination is the consumer's to own.
+   */
+  manageAccountUrl?: string;
+  /** Offer "Sign out everywhere" (ends every session for the user). Default `false`. */
+  showSignOutEverywhere?: boolean;
+  /** Start with the menu open. Default `false`. */
+  defaultOpen?: boolean;
+  /** Rendered while the session resolves, so the header doesn't jump. */
+  fallback?: ReactNode;
+  /** Appended to the root element's class list, for escape-hatch styling. */
+  className?: string;
+  labels?: Partial<UserButtonLabels>;
+  /** `<UserButton.MenuItems>` with custom `<UserButton.Action>` / `<UserButton.Link>` entries. */
+  children?: ReactNode;
+  /** Avatar size in pixels. Default 32. */
+  avatarSize?: number;
+}
+/**
+ * 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>
+ * ```
+ */
+declare const UserButton: ((props: UserButtonProps) => ReactNode) & {
+  MenuItems: (props: {
+    children?: ReactNode;
+  }) => ReactNode;
+  Action: (props: UserButtonActionProps) => ReactNode;
+  Link: (props: UserButtonLinkProps) => ReactNode;
+};
+//#endregion
+//#region src/components/user-avatar.d.ts
+interface UserAvatarProps {
+  /** Image URL. Falls back to initials when absent or when the image fails to load. */
+  src?: string;
+  /** The name initials are derived from; also the image's alt text. */
+  name?: string;
+  /** Pixel size of the (square) avatar. Default 32. */
+  size?: number;
+  /** Appended to the root element's class list, for escape-hatch styling. */
+  className?: string;
+}
+/**
+ * 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.
+ */
+declare function UserAvatar({
+  src,
+  name,
+  size,
+  className
+}: UserAvatarProps): ReactNode;
+//#endregion
 //#region src/index.d.ts
 /**
  * @poly-x/react — PolyX SDK for React SPAs. Sign-in UI + orchestration land in
@@ -220,4 +488,4 @@ declare function AuthCallback({
 declare const PACKAGE_NAME = "@poly-x/react";
 declare const version = "0.0.0";
 //#endregion
-export { AuthCallback, type AuthCallbackMessage, type AuthCallbackProps, type AuthChannel, BroadcastAuthChannel, BroadcastChannelSessionChannel, type BrowserBridge, type CallbackParams, type LoginController, type LoginControllerDeps, PACKAGE_NAME, PolyXContext, type PolyXContextValue, PolyXProvider, type PolyXProviderProps, PopupCancelledError, type PopupHandle, Protected, type ProtectedProps, SessionStoragePkceStore, SignIn, type SignInOptions, type SignInProps, type UseAuth, WebLocksLock, WindowBrowserBridge, createLoginController, useAuth, useAuthCallback, useSession, useUser, version };
+export { AuthCallback, type AuthCallbackMessage, type AuthCallbackProps, type AuthChannel, BroadcastAuthChannel, BroadcastChannelSessionChannel, type BrowserBridge, type CallbackParams, ForgotPassword, type ForgotPasswordLabels, type ForgotPasswordProps, type LoginController, type LoginControllerDeps, PACKAGE_NAME, PolyXContext, type PolyXContextValue, PolyXProvider, type PolyXProviderProps, PopupCancelledError, type PopupHandle, Protected, type ProtectedProps, ResetPassword, type ResetPasswordLabels, type ResetPasswordProps, SessionStoragePkceStore, SignIn, type SignInLabels, type SignInOptions, type SignInProps, type SignInVariant, type UseAuth, UserAvatar, type UserAvatarProps, UserButton, type UserButtonActionProps, type UserButtonLabels, type UserButtonLinkProps, type UserButtonProps, WebLocksLock, WindowBrowserBridge, createLoginController, useAuth, useAuthCallback, useSession, useUser, version };

package/dist/index.d.mts

@@ -18,6 +18,14 @@ declare function PolyXProvider({
   children
 }: PolyXProviderProps): ReactNode;
 //#endregion
+//#region src/bff-session.d.ts
+interface BffSignOutOptions {
+  /** `everywhere` ends every session for the user (FR-SSO-5). Default `device`. */
+  scope?: "device" | "everywhere";
+  /** Where to land afterwards. Resolved here, client-side — the server takes no redirect target. */
+  redirectTo?: string;
+}
+//#endregion
 //#region src/auth-channel.d.ts
 /**
  * Same-origin popup→opener handoff of the authorization `code` (F006). The
@@ -115,8 +123,11 @@ interface UseAuth {
   isLoaded: boolean;
   isSignedIn: boolean;
   signIn: (options?: SignInOptions) => Promise<void>;
-  signOut: () => Promise<void>;
-  /** Current access token, refreshing if needed; null when signed out. */
+  signOut: (options?: BffSignOutOptions) => Promise<void>;
+  /**
+   * Current access token, refreshing if needed; null when signed out — and always null under
+   * BFF custody, where the token is httpOnly server-side by design (FR-SES-3).
+   */
   getToken: () => Promise<string | null>;
 }
 declare function useAuth(): UseAuth;
@@ -191,16 +202,179 @@ declare function Protected({
 }: ProtectedProps): ReactNode;
 //#endregion
 //#region src/components/sign-in.d.ts
-interface SignInProps extends SignInOptions {
-  children?: ReactNode;
+/** Every user-facing string, overridable for i18n / white-labelling. */
+interface SignInLabels {
+  heading: string;
+  subheading: string;
+  /** Headline on the `page` variant's brand panel. Empty renders a clean brand panel. */
+  tagline: string;
+  emailLabel: string;
+  emailPlaceholder: string;
+  passwordLabel: string;
+  passwordPlaceholder: string;
+  /** Reveal-toggle a11y labels (aria-label / tooltip on the show-hide button). */
+  showPassword: string;
+  hidePassword: string;
+  submit: string;
+  submitting: string;
+  forgotPassword: string;
+  chooseWorkspace: string;
+  chooseWorkspaceSubheading: string;
+  securedBy: string;
+  setPasswordHeading: string;
+  setPasswordSubheading: string;
+  newPasswordLabel: string;
+  confirmPasswordLabel: string;
+  setPasswordSubmit: string;
+  passwordMismatch: string;
+  weakPassword: string;
+  invalidCredentials: string;
+  noAccess: string;
+  passwordChangeRequired: string;
+  genericError: string;
+}
+/**
+ * `card` renders just the card — drop it into your own layout.
+ * `page` owns the viewport — a split layout with a brand panel beside the form
+ * (the panel collapses away under 64rem, leaving the form on its own).
+ */
+type SignInVariant = "card" | "page";
+interface SignInProps {
+  /** Layout preset. Default `card`. */
+  variant?: SignInVariant;
+  /**
+   * Content for the `page` variant's brand panel. Defaults to your `logo` plus
+   * `labels.tagline`; pass your own node to take the panel over completely.
+   * Ignored by the `card` variant.
+   */
+  panel?: ReactNode;
+  /** BFF endpoint backed by `createAuthHandlers().authenticate`. Default `/api/polyx/authenticate`. */
+  action?: string;
+  /**
+   * URL of your reset flow (where `<ForgotPassword/>` lives). When set, a
+   * "Forgot password?" link appears under the password field. Omit to hide it.
+   */
+  forgotPasswordUrl?: string;
+  /** Where to send the browser after success. Overrides the server's default redirect. */
+  afterSignInPath?: string;
+  /** Pre-scope the login to a single organization (skips org discovery). */
+  organizationCode?: string;
+  /** Rendered above the heading — your wordmark or logo. */
+  logo?: ReactNode;
+  /** Show the "Secured by PolyX" attribution under the form. Default true. */
+  showSecuredBy?: boolean;
+  /** Appended to the root element's class list, for escape-hatch styling. */
   className?: string;
+  labels?: Partial<SignInLabels>;
+  /** Fired when the backend requires the user to set a new password before continuing. */
+  onPasswordChangeRequired?: (userId: string) => void;
 }
-/** Minimal sign-in trigger — popup by default. Style via `className`/children. */
-declare function SignIn({
-  children,
-  className,
-  ...options
-}: SignInProps): ReactNode;
+/**
+ * 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.
+ */
+declare function SignIn(props: SignInProps): ReactNode;
+//#endregion
+//#region src/components/forgot-password.d.ts
+/** Every user-facing string, overridable for i18n / white-labelling. */
+interface ForgotPasswordLabels {
+  heading: string;
+  subheading: string;
+  emailLabel: string;
+  emailPlaceholder: string;
+  submit: string;
+  submitting: string;
+  /** Shown after submit — always, regardless of whether the account exists. */
+  sentHeading: string;
+  /** Confirmation body. `{email}` is replaced with the entered address, emphasized. */
+  sentSubheading: string;
+  differentEmail: string;
+  backToSignIn: string;
+  securedBy: string;
+  genericError: string;
+}
+interface ForgotPasswordProps {
+  /** BFF endpoint backed by `createAuthHandlers().forgotPassword`. Default `/api/polyx/forgot-password`. */
+  action?: string;
+  /** Where the "back to sign in" link points. Default `/sign-in`. */
+  signInPath?: string;
+  /** Rendered above the heading — your wordmark or logo. */
+  logo?: ReactNode;
+  /** Show the "Secured by PolyX" attribution under the form. Default true. */
+  showSecuredBy?: boolean;
+  /** Appended to the root element's class list, for escape-hatch styling. */
+  className?: string;
+  labels?: Partial<ForgotPasswordLabels>;
+}
+/**
+ * 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.
+ */
+declare function ForgotPassword(props: ForgotPasswordProps): ReactNode;
+//#endregion
+//#region src/components/reset-password.d.ts
+/** Every user-facing string, overridable for i18n / white-labelling. */
+interface ResetPasswordLabels {
+  heading: string;
+  subheading: string;
+  newPasswordLabel: string;
+  confirmPasswordLabel: string;
+  passwordPlaceholder: string;
+  submit: string;
+  submitting: string;
+  successHeading: string;
+  successSubheading: string;
+  invalidHeading: string;
+  invalidSubheading: string;
+  requestNewLink: string;
+  backToSignIn: string;
+  securedBy: string;
+  passwordMismatch: string;
+  weakPassword: string;
+  genericError: string;
+}
+interface ResetPasswordProps {
+  /** BFF endpoint backed by `createAuthHandlers().resetPassword`. Default `/api/polyx/reset-password`. */
+  action?: string;
+  /** The opaque reset token. Defaults to `?token=` from the URL (client-side). */
+  token?: string;
+  /** Where to send the browser after a successful reset. Default `/sign-in`. */
+  afterResetPath?: string;
+  /** Where "request a new link" / "back to sign in" point. Default `/forgot-password` and `/sign-in`. */
+  forgotPasswordPath?: string;
+  signInPath?: string;
+  /** Rendered above the heading — your wordmark or logo. */
+  logo?: ReactNode;
+  /** Show the "Secured by PolyX" attribution under the form. Default true. */
+  showSecuredBy?: boolean;
+  /** Client-side minimum password length (the backend enforces the real floor). Default 8. */
+  minLength?: number;
+  /** Appended to the root element's class list, for escape-hatch styling. */
+  className?: string;
+  labels?: Partial<ResetPasswordLabels>;
+}
+/**
+ * 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.
+ */
+declare function ResetPassword(props: ResetPasswordProps): ReactNode;
 //#endregion
 //#region src/components/auth-callback.d.ts
 interface AuthCallbackProps {
@@ -212,6 +386,100 @@ declare function AuthCallback({
   children
 }: AuthCallbackProps): ReactNode;
 //#endregion
+//#region src/components/user-button.d.ts
+/** Every user-facing string, overridable for i18n / white-labelling. */
+interface UserButtonLabels {
+  trigger: string;
+  manageAccount: string;
+  signOut: string;
+  signOutEverywhere: string;
+}
+interface UserButtonActionProps {
+  /**
+   * The menu entry's text — or the name of a built-in (`manageAccount`, `signOut`,
+   * `signOutEverywhere`) to place it at this position instead of appending a second copy.
+   */
+  label: string;
+  /** Icon rendered before the label. */
+  labelIcon?: ReactNode;
+  onClick?: () => void;
+}
+interface UserButtonLinkProps {
+  label: string;
+  labelIcon?: ReactNode;
+  href: string;
+}
+interface UserButtonProps {
+  /** Show the user's name next to the avatar. Default `false`. */
+  showName?: boolean;
+  /** Where to land after signing out. Default the app root. */
+  afterSignOutUrl?: string;
+  /**
+   * Destination for the "Manage account" entry. Omitted entirely when unset — PolyX has no
+   * hosted profile page, so the destination is the consumer's to own.
+   */
+  manageAccountUrl?: string;
+  /** Offer "Sign out everywhere" (ends every session for the user). Default `false`. */
+  showSignOutEverywhere?: boolean;
+  /** Start with the menu open. Default `false`. */
+  defaultOpen?: boolean;
+  /** Rendered while the session resolves, so the header doesn't jump. */
+  fallback?: ReactNode;
+  /** Appended to the root element's class list, for escape-hatch styling. */
+  className?: string;
+  labels?: Partial<UserButtonLabels>;
+  /** `<UserButton.MenuItems>` with custom `<UserButton.Action>` / `<UserButton.Link>` entries. */
+  children?: ReactNode;
+  /** Avatar size in pixels. Default 32. */
+  avatarSize?: number;
+}
+/**
+ * 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>
+ * ```
+ */
+declare const UserButton: ((props: UserButtonProps) => ReactNode) & {
+  MenuItems: (props: {
+    children?: ReactNode;
+  }) => ReactNode;
+  Action: (props: UserButtonActionProps) => ReactNode;
+  Link: (props: UserButtonLinkProps) => ReactNode;
+};
+//#endregion
+//#region src/components/user-avatar.d.ts
+interface UserAvatarProps {
+  /** Image URL. Falls back to initials when absent or when the image fails to load. */
+  src?: string;
+  /** The name initials are derived from; also the image's alt text. */
+  name?: string;
+  /** Pixel size of the (square) avatar. Default 32. */
+  size?: number;
+  /** Appended to the root element's class list, for escape-hatch styling. */
+  className?: string;
+}
+/**
+ * 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.
+ */
+declare function UserAvatar({
+  src,
+  name,
+  size,
+  className
+}: UserAvatarProps): ReactNode;
+//#endregion
 //#region src/index.d.ts
 /**
  * @poly-x/react — PolyX SDK for React SPAs. Sign-in UI + orchestration land in
@@ -220,4 +488,4 @@ declare function AuthCallback({
 declare const PACKAGE_NAME = "@poly-x/react";
 declare const version = "0.0.0";
 //#endregion
-export { AuthCallback, type AuthCallbackMessage, type AuthCallbackProps, type AuthChannel, BroadcastAuthChannel, BroadcastChannelSessionChannel, type BrowserBridge, type CallbackParams, type LoginController, type LoginControllerDeps, PACKAGE_NAME, PolyXContext, type PolyXContextValue, PolyXProvider, type PolyXProviderProps, PopupCancelledError, type PopupHandle, Protected, type ProtectedProps, SessionStoragePkceStore, SignIn, type SignInOptions, type SignInProps, type UseAuth, WebLocksLock, WindowBrowserBridge, createLoginController, useAuth, useAuthCallback, useSession, useUser, version };
+export { AuthCallback, type AuthCallbackMessage, type AuthCallbackProps, type AuthChannel, BroadcastAuthChannel, BroadcastChannelSessionChannel, type BrowserBridge, type CallbackParams, ForgotPassword, type ForgotPasswordLabels, type ForgotPasswordProps, type LoginController, type LoginControllerDeps, PACKAGE_NAME, PolyXContext, type PolyXContextValue, PolyXProvider, type PolyXProviderProps, PopupCancelledError, type PopupHandle, Protected, type ProtectedProps, ResetPassword, type ResetPasswordLabels, type ResetPasswordProps, SessionStoragePkceStore, SignIn, type SignInLabels, type SignInOptions, type SignInProps, type SignInVariant, type UseAuth, UserAvatar, type UserAvatarProps, UserButton, type UserButtonActionProps, type UserButtonLabels, type UserButtonLinkProps, type UserButtonProps, WebLocksLock, WindowBrowserBridge, createLoginController, useAuth, useAuthCallback, useSession, useUser, version };