@poly-x/react 0.1.1 → 0.3.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { ReactNode } from "react";
-import { AuthClient, Lock, PkceEntry, PkceStore, SessionChannel, SessionChannelEvent, SessionClaims, SessionEngine, SessionState } from "@poly-x/core";
+import { AuthClient, Lock, PkceEntry, PkceStore, SessionChannel, SessionChannelEvent, SessionClaims, SessionEngine, SessionState, TenantOption } from "@poly-x/core";
 
 //#region src/provider.d.ts
 interface PolyXProviderProps {
@@ -122,6 +122,95 @@ declare class PopupCancelledError extends Error {
 }
 declare function createLoginController(deps: LoginControllerDeps): LoginController;
 //#endregion
+//#region src/warm-hop.d.ts
+/**
+ * How long to wait for the silent attempt before giving up and showing the form.
+ *
+ * A guess, and labelled as one. The requirement it serves (FR-FALL-2) is that a slow or
+ * dead platform must never leave someone watching a spinner — and for that, *any* bound
+ * beats none. The person this protects is already signed out and gains nothing from
+ * waiting, so the bound is deliberately short. Override it if you have measured yours.
+ */
+declare const WARM_HOP_TIMEOUT_MS = 5000;
+type WarmHopResult = /** Signed in. The session cookie is set; `workspace` names the tenant actually entered. */{
+  status: "signed_in";
+  workspace?: string;
+}
+/**
+ * Signed in — but **not** where you asked.
+ *
+ * The platform only honours a workspace hint when the person has more than one candidate for
+ * that application; with exactly one it seats them there regardless and still answers
+ * "authorized". The session is valid and the person is somewhere they are entitled to be, so
+ * this is not a failure — but it is not what was requested, and being silently put to work in
+ * the wrong tenant is worse than being asked. Decide deliberately: accept it, or send them to
+ * a picker.
+ */
+| {
+  status: "workspace_mismatch";
+  requested: string;
+  workspace: string;
+} /** Several workspaces are available and none was requested — ask, never guess (D14). */ | {
+  status: "select_workspace";
+  workspaces: readonly TenantOption[];
+} /** Recognised, but not entitled to this application or workspace (D15). */ | {
+  status: "no_access";
+} /** Not recognised. The ordinary signed-out path — not an error. */ | {
+  status: "sign_in_required";
+} /** The attempt could not be completed. Treated as signed-out by callers; surfaced for logs. */ | {
+  status: "failed";
+  reason: string;
+};
+/** Has an automatic attempt already run in this tab? */
+declare function warmHopAttempted(): boolean;
+/** Clear the once-per-entry marker. Exported for sign-out, so the next sign-in may try again. */
+declare function resetWarmHop(): void;
+interface WarmHopOptions {
+  /**
+   * Pin a workspace by tenant id, organization code or slug.
+   *
+   * The platform matches this **only within the person's own memberships**, so it can
+   * narrow a choice but never widen access — which is why passing it is safe even when the
+   * value came from something the page was holding.
+   */
+  workspace?: string;
+  /** Override the fall-back bound. See `WARM_HOP_TIMEOUT_MS`. */
+  timeoutMs?: number;
+}
+/**
+ * Run one silent attempt and report what the platform said.
+ *
+ * Never throws: every failure resolves to `failed`, because a caller in the middle of
+ * rendering a sign-in page has no better answer than "show the form" and an exception
+ * there is how a blank screen happens.
+ */
+declare function attemptWarmHop(options?: WarmHopOptions): Promise<WarmHopResult>;
+/**
+ * Move to another workspace (F028 / FR-SWITCH-1…6).
+ *
+ * The same mechanism as the entry attempt, aimed deliberately rather than on arrival — and
+ * deliberately **not** subject to the once-per-entry guard, because this one is a thing the
+ * person asked for.
+ *
+ * Eligibility is decided by the platform at this moment, not from any list held here, so a
+ * workspace revoked since the picker was drawn can never be entered (FR-SWITCH-4). Which
+ * refusal you get depends on what is left, verified against a live platform: still holding
+ * other workspaces gives `select_workspace` listing them; having lost them all gives
+ * `no_access`. Do not treat `no_access` as the only refusal.
+ *
+ * On `signed_in` the session cookie now names the new workspace. The caller decides what to
+ * do next — the SDK does not reload the page or discard anything on their behalf, because it
+ * cannot know what is unsaved on the screen (FR-SWITCH-7).
+ */
+declare function switchWorkspace(workspace: string, options?: WarmHopOptions): Promise<WarmHopResult>;
+/**
+ * The automatic entry attempt: at most once per tab, whatever the caller does (FR-HOP-2).
+ *
+ * Returns `null` when it declines to attempt — already tried this entry — so a caller can
+ * tell "we tried and they must sign in" from "we did not try".
+ */
+declare function attemptWarmHopOnce(options?: WarmHopOptions): Promise<WarmHopResult | null>;
+//#endregion
 //#region src/hooks.d.ts
 /** The raw session state machine value — tearing-free under concurrent React. */
 declare function useSession(): SessionState;
@@ -136,11 +225,52 @@ interface UseAuth {
    * BFF custody, where the token is httpOnly server-side by design (FR-SES-3).
    */
   getToken: () => Promise<string | null>;
+  /**
+   * Re-read the session's authorization from the server and resolve whether it actually
+   * changed (FR-CLIENT-3).
+   *
+   * This capability already existed on the BFF store but was not reachable from the public
+   * surface, so both consuming apps wrote their own refresher — and they already differ:
+   * one treats a module change as an authorization change, the other only a permission
+   * change. Pair it with `useLiveAuthz`/`startLiveAuthz`, which single-flights callers.
+   */
+  refresh: () => Promise<boolean>;
 }
 declare function useAuth(): UseAuth;
 /** Run this on your callback route to complete a sign-in (see `<AuthCallback>`). */
 declare function useAuthCallback(): () => Promise<void>;
 declare function useUser(): SessionClaims | null;
+/** What `useWarmHop` reports while and after it tries. */
+type WarmHopState = {
+  status: "idle";
+} | {
+  status: "attempting";
+} | {
+  status: "settled";
+  result: WarmHopResult;
+};
+/**
+ * Try a silent sign-in once when this component mounts (F027 / FR-HOP-2, FR-FALL-1…3).
+ *
+ * The contract that matters is D11's: **an attempt that fails must be invisible.** Someone who
+ * is genuinely signed out pays the whole cost of this feature and gets nothing from it, so they
+ * must not see a flicker, a spinner that outlives their patience, or — worst — a redirect loop.
+ * Hence: no navigation anywhere in the flow, a hard timeout, and a guard that survives the route
+ * change to the sign-in page (a guard in React state would reset exactly when it is needed).
+ *
+ * ```tsx
+ * const hop = useWarmHop();
+ * if (hop.status !== "settled" ) return null;              // no half-drawn form
+ * if (hop.result.status === "signed_in") return <Redirect/>;
+ * return <SignIn />;                                       // the ordinary path
+ * ```
+ *
+ * Strict Mode's double-mount does not produce two attempts: the marker is written before the
+ * first request goes out.
+ */
+declare function useWarmHop(options?: WarmHopOptions & {
+  enabled?: boolean;
+}): WarmHopState;
 //#endregion
 //#region src/context.d.ts
 interface PolyXContextValue {
@@ -239,6 +369,8 @@ interface SignInLabels {
   noAccess: string;
   passwordChangeRequired: string;
   genericError: string;
+  /** Reserved second-factor step (F020). Unreachable until MFA ships. */
+  verificationRequired?: string;
 }
 /**
  * `card` renders just the card — drop it into your own layout.
@@ -500,6 +632,70 @@ interface Viewport {
  */
 declare function resolveSide(preferred: SideOption, trigger: Rect, menu: Size, viewport: Viewport, gap?: number): Side;
 //#endregion
+//#region src/components/user-profile.d.ts
+/** Every user-facing string, overridable for i18n / white-labelling (FR-BRAND-4). */
+interface UserProfileLabels {
+  trigger: string;
+  title: string;
+  description: string;
+  firstName: string;
+  lastName: string;
+  phoneNumber: string;
+  cnic: string;
+  gender: string;
+  photo: string;
+  changePhoto: string;
+  optional: string;
+  save: string;
+  saving: string;
+  cancel: string;
+  close: string;
+  loading: string;
+  loadFailed: string;
+  saveFailed: string;
+  saved: string;
+  signedOut: string;
+  genderUnset: string;
+  genderMale: string;
+  genderFemale: string;
+  genderOther: string;
+}
+interface UserProfileProps {
+  /** Replaces the trigger's contents. The SDK still owns the button and its dialog semantics. */
+  trigger?: ReactNode;
+  /** Render no trigger at all and control the dialog from outside (`open` / `onOpenChange`). */
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  /** Notified after a successful save, with the saved profile (FR-PROF-10). */
+  onSaved?: (user: Record<string, unknown>) => void;
+  /** Appended to the root element's class list. */
+  className?: string;
+  /** Appended to the trigger button's class list — the element a consumer places in their layout. */
+  triggerClassName?: string;
+  /** Appended to the dialog's class list. */
+  dialogClassName?: string;
+  labels?: Partial<UserProfileLabels>;
+}
+/**
+ * The signed-in person's own profile, as a dialog (v0.4 / FR-PROF).
+ *
+ * Every application that wanted this had to build the same four things: a form, a validation
+ * ruleset guessed at from error messages, a file upload, and — because the browser holds no
+ * credential under BFF custody — a server route to carry the call. The last of those is
+ * security-adjacent work that had no business being duplicated per app.
+ *
+ * The credential never comes near this component: it posts to the SDK's own route, which
+ * attaches the session server-side and takes the identity from the sealed session rather than
+ * from anything sent here. This surface cannot be aimed at another person's profile even if a
+ * caller tries (FR-CUSTODY-4 / D24).
+ *
+ * ```tsx
+ * <UserProfile onSaved={() => router.refresh()} />
+ * ```
+ */
+declare function UserProfile(props: UserProfileProps): ReactNode;
+//#endregion
 //#region src/components/user-button.d.ts
 /** Every user-facing string, overridable for i18n / white-labelling. */
 interface UserButtonLabels {
@@ -542,6 +738,17 @@ interface UserButtonProps {
    * hosted profile page, so the destination is the consumer's to own.
    */
   manageAccountUrl?: string;
+  /**
+   * Make "Manage account" open the SDK's own `<UserProfile/>` dialog instead of navigating
+   * (v0.4 / FR-PROF-8). Opt-in, so an app that already links its menu to its own account page
+   * keeps that behavior untouched (FR-COMPAT-2).
+   *
+   * Ignored when `manageAccountUrl` is set — a menu entry that both navigates and opens a
+   * dialog is a bug, so the explicit destination wins and this is a no-op.
+   */
+  showUserProfile?: boolean;
+  /** Passed through to the dialog `showUserProfile` opens. */
+  userProfileProps?: Omit<UserProfileProps, "open" | "onOpenChange">;
   /** Offer "Sign out everywhere" (ends every session for the user). Default `false`. */
   showSignOutEverywhere?: boolean;
   /** Start with the menu open. Default `false`. */
@@ -631,6 +838,23 @@ declare function UserAvatar({
   className
 }: UserAvatarProps): ReactNode;
 //#endregion
+//#region src/auth-event.d.ts
+/**
+ * Read a one-shot auth event published by the BFF (F017 / FR-CLIENT-5).
+ *
+ * Sign-in and sign-out are full-page navigations, so an app cannot simply react in the
+ * handler that triggered them — the page is gone. The BFF leaves a short-lived, readable
+ * cookie; the destination page consumes it once.
+ */
+type AuthEventKind = "signed-in" | "signed-out";
+/**
+ * Read the pending auth event and clear it, so it fires exactly once.
+ *
+ * Returns `null` when there is nothing pending — which is the normal case on almost every
+ * page load. Safe to call during render or in an effect; it is a no-op on the server.
+ */
+declare function consumeAuthEvent(): AuthEventKind | null;
+//#endregion
 //#region src/live-authz.d.ts
 /**
  * @poly-x/react/live-authz — keeps live claims current (SDK v2: FR-LIVE, FR-SIG, FR-TRIG).
@@ -699,6 +923,7 @@ declare function useAuthzChanged(callback: () => void): void;
  * F006; this entry is the state foundation (provider, hooks, browser seams).
  */
 declare const PACKAGE_NAME = "@poly-x/react";
-declare const version = "0.0.0";
+/** The published version of this package, injected at build time. */
+declare const version: string;
 //#endregion
-export { type Align, AuthCallback, type AuthCallbackMessage, type AuthCallbackProps, type AuthChannel, BroadcastAuthChannel, BroadcastChannelSessionChannel, type BrowserBridge, type CallbackParams, type CaptureOptions, type CapturedGeo, ForgotPassword, type ForgotPasswordLabels, type ForgotPasswordProps, type GeolocationLike, type LiveAuthzHandle, type LiveAuthzOptions, type LoginController, type LoginControllerDeps, PACKAGE_NAME, PolyXContext, type PolyXContextValue, PolyXProvider, type PolyXProviderProps, PopupCancelledError, type PopupHandle, Protected, type ProtectedProps, ResetPassword, type ResetPasswordLabels, type ResetPasswordProps, SessionStoragePkceStore, type Side, type SideOption, SignIn, type SignInLabels, type SignInOptions, type SignInProps, type SignInVariant, type UseAuth, type UseLiveAuthzOptions, UserAvatar, type UserAvatarProps, UserButton, type UserButtonActionProps, type UserButtonLabels, type UserButtonLinkProps, type UserButtonProps, type UserButtonSlotProps, WebLocksLock, WindowBrowserBridge, capturePreciseLocation, createLoginController, initialsFrom, resolveSide, startLiveAuthz, useAuth, useAuthCallback, useAuthzChanged, useLiveAuthz, useSession, useUser, version };
+export { type Align, AuthCallback, type AuthCallbackMessage, type AuthCallbackProps, type AuthChannel, type AuthEventKind, BroadcastAuthChannel, BroadcastChannelSessionChannel, type BrowserBridge, type CallbackParams, type CaptureOptions, type CapturedGeo, ForgotPassword, type ForgotPasswordLabels, type ForgotPasswordProps, type GeolocationLike, type LiveAuthzHandle, type LiveAuthzOptions, type LoginController, type LoginControllerDeps, PACKAGE_NAME, PolyXContext, type PolyXContextValue, PolyXProvider, type PolyXProviderProps, PopupCancelledError, type PopupHandle, Protected, type ProtectedProps, ResetPassword, type ResetPasswordLabels, type ResetPasswordProps, SessionStoragePkceStore, type Side, type SideOption, SignIn, type SignInLabels, type SignInOptions, type SignInProps, type SignInVariant, type UseAuth, type UseLiveAuthzOptions, UserAvatar, type UserAvatarProps, UserButton, type UserButtonActionProps, type UserButtonLabels, type UserButtonLinkProps, type UserButtonProps, type UserButtonSlotProps, UserProfile, type UserProfileLabels, type UserProfileProps, WARM_HOP_TIMEOUT_MS, type WarmHopOptions, type WarmHopResult, type WarmHopState, WebLocksLock, WindowBrowserBridge, attemptWarmHop, attemptWarmHopOnce, capturePreciseLocation, consumeAuthEvent, createLoginController, initialsFrom, resetWarmHop, resolveSide, startLiveAuthz, switchWorkspace, useAuth, useAuthCallback, useAuthzChanged, useLiveAuthz, useSession, useUser, useWarmHop, version, warmHopAttempted };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { AuthClient, Lock, PkceEntry, PkceStore, SessionChannel, SessionChannelEvent, SessionClaims, SessionEngine, SessionState } from "@poly-x/core";
+import { AuthClient, Lock, PkceEntry, PkceStore, SessionChannel, SessionChannelEvent, SessionClaims, SessionEngine, SessionState, TenantOption } from "@poly-x/core";
 import { ReactNode } from "react";
 
 //#region src/provider.d.ts
@@ -122,6 +122,95 @@ declare class PopupCancelledError extends Error {
 }
 declare function createLoginController(deps: LoginControllerDeps): LoginController;
 //#endregion
+//#region src/warm-hop.d.ts
+/**
+ * How long to wait for the silent attempt before giving up and showing the form.
+ *
+ * A guess, and labelled as one. The requirement it serves (FR-FALL-2) is that a slow or
+ * dead platform must never leave someone watching a spinner — and for that, *any* bound
+ * beats none. The person this protects is already signed out and gains nothing from
+ * waiting, so the bound is deliberately short. Override it if you have measured yours.
+ */
+declare const WARM_HOP_TIMEOUT_MS = 5000;
+type WarmHopResult = /** Signed in. The session cookie is set; `workspace` names the tenant actually entered. */{
+  status: "signed_in";
+  workspace?: string;
+}
+/**
+ * Signed in — but **not** where you asked.
+ *
+ * The platform only honours a workspace hint when the person has more than one candidate for
+ * that application; with exactly one it seats them there regardless and still answers
+ * "authorized". The session is valid and the person is somewhere they are entitled to be, so
+ * this is not a failure — but it is not what was requested, and being silently put to work in
+ * the wrong tenant is worse than being asked. Decide deliberately: accept it, or send them to
+ * a picker.
+ */
+| {
+  status: "workspace_mismatch";
+  requested: string;
+  workspace: string;
+} /** Several workspaces are available and none was requested — ask, never guess (D14). */ | {
+  status: "select_workspace";
+  workspaces: readonly TenantOption[];
+} /** Recognised, but not entitled to this application or workspace (D15). */ | {
+  status: "no_access";
+} /** Not recognised. The ordinary signed-out path — not an error. */ | {
+  status: "sign_in_required";
+} /** The attempt could not be completed. Treated as signed-out by callers; surfaced for logs. */ | {
+  status: "failed";
+  reason: string;
+};
+/** Has an automatic attempt already run in this tab? */
+declare function warmHopAttempted(): boolean;
+/** Clear the once-per-entry marker. Exported for sign-out, so the next sign-in may try again. */
+declare function resetWarmHop(): void;
+interface WarmHopOptions {
+  /**
+   * Pin a workspace by tenant id, organization code or slug.
+   *
+   * The platform matches this **only within the person's own memberships**, so it can
+   * narrow a choice but never widen access — which is why passing it is safe even when the
+   * value came from something the page was holding.
+   */
+  workspace?: string;
+  /** Override the fall-back bound. See `WARM_HOP_TIMEOUT_MS`. */
+  timeoutMs?: number;
+}
+/**
+ * Run one silent attempt and report what the platform said.
+ *
+ * Never throws: every failure resolves to `failed`, because a caller in the middle of
+ * rendering a sign-in page has no better answer than "show the form" and an exception
+ * there is how a blank screen happens.
+ */
+declare function attemptWarmHop(options?: WarmHopOptions): Promise<WarmHopResult>;
+/**
+ * Move to another workspace (F028 / FR-SWITCH-1…6).
+ *
+ * The same mechanism as the entry attempt, aimed deliberately rather than on arrival — and
+ * deliberately **not** subject to the once-per-entry guard, because this one is a thing the
+ * person asked for.
+ *
+ * Eligibility is decided by the platform at this moment, not from any list held here, so a
+ * workspace revoked since the picker was drawn can never be entered (FR-SWITCH-4). Which
+ * refusal you get depends on what is left, verified against a live platform: still holding
+ * other workspaces gives `select_workspace` listing them; having lost them all gives
+ * `no_access`. Do not treat `no_access` as the only refusal.
+ *
+ * On `signed_in` the session cookie now names the new workspace. The caller decides what to
+ * do next — the SDK does not reload the page or discard anything on their behalf, because it
+ * cannot know what is unsaved on the screen (FR-SWITCH-7).
+ */
+declare function switchWorkspace(workspace: string, options?: WarmHopOptions): Promise<WarmHopResult>;
+/**
+ * The automatic entry attempt: at most once per tab, whatever the caller does (FR-HOP-2).
+ *
+ * Returns `null` when it declines to attempt — already tried this entry — so a caller can
+ * tell "we tried and they must sign in" from "we did not try".
+ */
+declare function attemptWarmHopOnce(options?: WarmHopOptions): Promise<WarmHopResult | null>;
+//#endregion
 //#region src/hooks.d.ts
 /** The raw session state machine value — tearing-free under concurrent React. */
 declare function useSession(): SessionState;
@@ -136,11 +225,52 @@ interface UseAuth {
    * BFF custody, where the token is httpOnly server-side by design (FR-SES-3).
    */
   getToken: () => Promise<string | null>;
+  /**
+   * Re-read the session's authorization from the server and resolve whether it actually
+   * changed (FR-CLIENT-3).
+   *
+   * This capability already existed on the BFF store but was not reachable from the public
+   * surface, so both consuming apps wrote their own refresher — and they already differ:
+   * one treats a module change as an authorization change, the other only a permission
+   * change. Pair it with `useLiveAuthz`/`startLiveAuthz`, which single-flights callers.
+   */
+  refresh: () => Promise<boolean>;
 }
 declare function useAuth(): UseAuth;
 /** Run this on your callback route to complete a sign-in (see `<AuthCallback>`). */
 declare function useAuthCallback(): () => Promise<void>;
 declare function useUser(): SessionClaims | null;
+/** What `useWarmHop` reports while and after it tries. */
+type WarmHopState = {
+  status: "idle";
+} | {
+  status: "attempting";
+} | {
+  status: "settled";
+  result: WarmHopResult;
+};
+/**
+ * Try a silent sign-in once when this component mounts (F027 / FR-HOP-2, FR-FALL-1…3).
+ *
+ * The contract that matters is D11's: **an attempt that fails must be invisible.** Someone who
+ * is genuinely signed out pays the whole cost of this feature and gets nothing from it, so they
+ * must not see a flicker, a spinner that outlives their patience, or — worst — a redirect loop.
+ * Hence: no navigation anywhere in the flow, a hard timeout, and a guard that survives the route
+ * change to the sign-in page (a guard in React state would reset exactly when it is needed).
+ *
+ * ```tsx
+ * const hop = useWarmHop();
+ * if (hop.status !== "settled" ) return null;              // no half-drawn form
+ * if (hop.result.status === "signed_in") return <Redirect/>;
+ * return <SignIn />;                                       // the ordinary path
+ * ```
+ *
+ * Strict Mode's double-mount does not produce two attempts: the marker is written before the
+ * first request goes out.
+ */
+declare function useWarmHop(options?: WarmHopOptions & {
+  enabled?: boolean;
+}): WarmHopState;
 //#endregion
 //#region src/context.d.ts
 interface PolyXContextValue {
@@ -239,6 +369,8 @@ interface SignInLabels {
   noAccess: string;
   passwordChangeRequired: string;
   genericError: string;
+  /** Reserved second-factor step (F020). Unreachable until MFA ships. */
+  verificationRequired?: string;
 }
 /**
  * `card` renders just the card — drop it into your own layout.
@@ -500,6 +632,70 @@ interface Viewport {
  */
 declare function resolveSide(preferred: SideOption, trigger: Rect, menu: Size, viewport: Viewport, gap?: number): Side;
 //#endregion
+//#region src/components/user-profile.d.ts
+/** Every user-facing string, overridable for i18n / white-labelling (FR-BRAND-4). */
+interface UserProfileLabels {
+  trigger: string;
+  title: string;
+  description: string;
+  firstName: string;
+  lastName: string;
+  phoneNumber: string;
+  cnic: string;
+  gender: string;
+  photo: string;
+  changePhoto: string;
+  optional: string;
+  save: string;
+  saving: string;
+  cancel: string;
+  close: string;
+  loading: string;
+  loadFailed: string;
+  saveFailed: string;
+  saved: string;
+  signedOut: string;
+  genderUnset: string;
+  genderMale: string;
+  genderFemale: string;
+  genderOther: string;
+}
+interface UserProfileProps {
+  /** Replaces the trigger's contents. The SDK still owns the button and its dialog semantics. */
+  trigger?: ReactNode;
+  /** Render no trigger at all and control the dialog from outside (`open` / `onOpenChange`). */
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  /** Notified after a successful save, with the saved profile (FR-PROF-10). */
+  onSaved?: (user: Record<string, unknown>) => void;
+  /** Appended to the root element's class list. */
+  className?: string;
+  /** Appended to the trigger button's class list — the element a consumer places in their layout. */
+  triggerClassName?: string;
+  /** Appended to the dialog's class list. */
+  dialogClassName?: string;
+  labels?: Partial<UserProfileLabels>;
+}
+/**
+ * The signed-in person's own profile, as a dialog (v0.4 / FR-PROF).
+ *
+ * Every application that wanted this had to build the same four things: a form, a validation
+ * ruleset guessed at from error messages, a file upload, and — because the browser holds no
+ * credential under BFF custody — a server route to carry the call. The last of those is
+ * security-adjacent work that had no business being duplicated per app.
+ *
+ * The credential never comes near this component: it posts to the SDK's own route, which
+ * attaches the session server-side and takes the identity from the sealed session rather than
+ * from anything sent here. This surface cannot be aimed at another person's profile even if a
+ * caller tries (FR-CUSTODY-4 / D24).
+ *
+ * ```tsx
+ * <UserProfile onSaved={() => router.refresh()} />
+ * ```
+ */
+declare function UserProfile(props: UserProfileProps): ReactNode;
+//#endregion
 //#region src/components/user-button.d.ts
 /** Every user-facing string, overridable for i18n / white-labelling. */
 interface UserButtonLabels {
@@ -542,6 +738,17 @@ interface UserButtonProps {
    * hosted profile page, so the destination is the consumer's to own.
    */
   manageAccountUrl?: string;
+  /**
+   * Make "Manage account" open the SDK's own `<UserProfile/>` dialog instead of navigating
+   * (v0.4 / FR-PROF-8). Opt-in, so an app that already links its menu to its own account page
+   * keeps that behavior untouched (FR-COMPAT-2).
+   *
+   * Ignored when `manageAccountUrl` is set — a menu entry that both navigates and opens a
+   * dialog is a bug, so the explicit destination wins and this is a no-op.
+   */
+  showUserProfile?: boolean;
+  /** Passed through to the dialog `showUserProfile` opens. */
+  userProfileProps?: Omit<UserProfileProps, "open" | "onOpenChange">;
   /** Offer "Sign out everywhere" (ends every session for the user). Default `false`. */
   showSignOutEverywhere?: boolean;
   /** Start with the menu open. Default `false`. */
@@ -631,6 +838,23 @@ declare function UserAvatar({
   className
 }: UserAvatarProps): ReactNode;
 //#endregion
+//#region src/auth-event.d.ts
+/**
+ * Read a one-shot auth event published by the BFF (F017 / FR-CLIENT-5).
+ *
+ * Sign-in and sign-out are full-page navigations, so an app cannot simply react in the
+ * handler that triggered them — the page is gone. The BFF leaves a short-lived, readable
+ * cookie; the destination page consumes it once.
+ */
+type AuthEventKind = "signed-in" | "signed-out";
+/**
+ * Read the pending auth event and clear it, so it fires exactly once.
+ *
+ * Returns `null` when there is nothing pending — which is the normal case on almost every
+ * page load. Safe to call during render or in an effect; it is a no-op on the server.
+ */
+declare function consumeAuthEvent(): AuthEventKind | null;
+//#endregion
 //#region src/live-authz.d.ts
 /**
  * @poly-x/react/live-authz — keeps live claims current (SDK v2: FR-LIVE, FR-SIG, FR-TRIG).
@@ -699,6 +923,7 @@ declare function useAuthzChanged(callback: () => void): void;
  * F006; this entry is the state foundation (provider, hooks, browser seams).
  */
 declare const PACKAGE_NAME = "@poly-x/react";
-declare const version = "0.0.0";
+/** The published version of this package, injected at build time. */
+declare const version: string;
 //#endregion
-export { type Align, AuthCallback, type AuthCallbackMessage, type AuthCallbackProps, type AuthChannel, BroadcastAuthChannel, BroadcastChannelSessionChannel, type BrowserBridge, type CallbackParams, type CaptureOptions, type CapturedGeo, ForgotPassword, type ForgotPasswordLabels, type ForgotPasswordProps, type GeolocationLike, type LiveAuthzHandle, type LiveAuthzOptions, type LoginController, type LoginControllerDeps, PACKAGE_NAME, PolyXContext, type PolyXContextValue, PolyXProvider, type PolyXProviderProps, PopupCancelledError, type PopupHandle, Protected, type ProtectedProps, ResetPassword, type ResetPasswordLabels, type ResetPasswordProps, SessionStoragePkceStore, type Side, type SideOption, SignIn, type SignInLabels, type SignInOptions, type SignInProps, type SignInVariant, type UseAuth, type UseLiveAuthzOptions, UserAvatar, type UserAvatarProps, UserButton, type UserButtonActionProps, type UserButtonLabels, type UserButtonLinkProps, type UserButtonProps, type UserButtonSlotProps, WebLocksLock, WindowBrowserBridge, capturePreciseLocation, createLoginController, initialsFrom, resolveSide, startLiveAuthz, useAuth, useAuthCallback, useAuthzChanged, useLiveAuthz, useSession, useUser, version };
+export { type Align, AuthCallback, type AuthCallbackMessage, type AuthCallbackProps, type AuthChannel, type AuthEventKind, BroadcastAuthChannel, BroadcastChannelSessionChannel, type BrowserBridge, type CallbackParams, type CaptureOptions, type CapturedGeo, ForgotPassword, type ForgotPasswordLabels, type ForgotPasswordProps, type GeolocationLike, type LiveAuthzHandle, type LiveAuthzOptions, type LoginController, type LoginControllerDeps, PACKAGE_NAME, PolyXContext, type PolyXContextValue, PolyXProvider, type PolyXProviderProps, PopupCancelledError, type PopupHandle, Protected, type ProtectedProps, ResetPassword, type ResetPasswordLabels, type ResetPasswordProps, SessionStoragePkceStore, type Side, type SideOption, SignIn, type SignInLabels, type SignInOptions, type SignInProps, type SignInVariant, type UseAuth, type UseLiveAuthzOptions, UserAvatar, type UserAvatarProps, UserButton, type UserButtonActionProps, type UserButtonLabels, type UserButtonLinkProps, type UserButtonProps, type UserButtonSlotProps, UserProfile, type UserProfileLabels, type UserProfileProps, WARM_HOP_TIMEOUT_MS, type WarmHopOptions, type WarmHopResult, type WarmHopState, WebLocksLock, WindowBrowserBridge, attemptWarmHop, attemptWarmHopOnce, capturePreciseLocation, consumeAuthEvent, createLoginController, initialsFrom, resetWarmHop, resolveSide, startLiveAuthz, switchWorkspace, useAuth, useAuthCallback, useAuthzChanged, useLiveAuthz, useSession, useUser, useWarmHop, version, warmHopAttempted };