@poly-x/react 0.1.0-alpha.18 → 0.1.0-alpha.19

package/dist/index.cjs

@@ -407,6 +407,40 @@ var BffSessionStore = class {
 			this.loading = false;
 		}
 	}
+	/**
+	* v2 (FR-LIVE-1/2): re-read server truth and update claims, resolving whether **authorization
+	* actually changed**. Drives the live-authz orchestrator (`startLiveAuthz`): a `true` means a
+	* consumer that gates on `useUser()` should re-guard. Never flickers to `resolving`; a definite
+	* signed-out answer signs the user out (revoked), a network blip keeps the last-known claims.
+	* The orchestrator single-flights callers, so this needs no internal in-flight guard.
+	*/
+	refresh = async () => {
+		try {
+			const response = await fetch(SESSION_ENDPOINT, {
+				credentials: "same-origin",
+				headers: { accept: "application/json" }
+			});
+			const body = response.ok ? await response.json() : null;
+			if (!Boolean(body?.isSignedIn && body.claims)) {
+				const changed = this.state.status !== "signed-out";
+				if (changed) this.set({
+					status: "signed-out",
+					reason: "revoked"
+				});
+				return changed;
+			}
+			const prevClaims = this.state.status === "authenticated" ? JSON.stringify(this.state.session.claims) : null;
+			const nextClaims = body.claims;
+			const changed = prevClaims !== JSON.stringify(nextClaims);
+			if (changed) this.set({
+				status: "authenticated",
+				session: { claims: nextClaims }
+			});
+			return changed;
+		} catch {
+			return false;
+		}
+	};
 	set(next) {
 		this.state = next;
 		for (const listener of this.listeners) listener();
@@ -1946,6 +1980,138 @@ const UserButton = Object.assign(UserButtonRoot, {
 	Header
 });
 //#endregion
+//#region src/live-authz.ts
+const DEFAULT_POLL_MS = 6e4;
+const DEFAULT_FOCUS_THROTTLE_MS = 5e3;
+/** Wire the triggers and return a handle. Safe to call with no window/document (SSR → no-op wiring). */
+function startLiveAuthz(opts) {
+	const pollMs = opts.pollMs ?? DEFAULT_POLL_MS;
+	const throttleMs = opts.focusThrottleMs ?? DEFAULT_FOCUS_THROTTLE_MS;
+	const win = opts.win ?? (typeof window !== "undefined" ? window : void 0);
+	const doc = opts.doc ?? (typeof document !== "undefined" ? document : void 0);
+	let stopped = false;
+	let inFlight = false;
+	let pending = false;
+	let lastRefreshAt = -Infinity;
+	/**
+	* Single-flight refresh (FR-LIVE-5). `coalesce` = queue exactly one follow-up run if a refresh
+	* is already in flight — used by the explicit push signal so a change mid-refresh isn't missed.
+	* Ambient triggers (focus/online/poll) pass `false`: if a refresh is already running, drop —
+	* they carry no new information the in-flight run won't already pick up.
+	*/
+	async function run(coalesce) {
+		if (stopped) return;
+		if (inFlight) {
+			if (coalesce) pending = true;
+			return;
+		}
+		inFlight = true;
+		try {
+			let changed = false;
+			try {
+				changed = await opts.refresh();
+			} catch {}
+			lastRefreshAt = Date.now();
+			if (changed && !stopped) opts.onChanged?.();
+		} finally {
+			inFlight = false;
+			if (pending && !stopped) {
+				pending = false;
+				run(true);
+			}
+		}
+	}
+	/** Throttled, non-queuing refresh for ambient triggers (focus/visible/online). */
+	function throttledRun() {
+		if (Date.now() - lastRefreshAt >= throttleMs) run(false);
+	}
+	const isVisible = () => !doc || doc.visibilityState !== "hidden";
+	const onFocus = () => throttledRun();
+	const onOnline = () => throttledRun();
+	const onVisibility = () => {
+		if (isVisible()) throttledRun();
+	};
+	if (win) {
+		win.addEventListener("focus", onFocus);
+		win.addEventListener("online", onOnline);
+	}
+	if (doc) doc.addEventListener("visibilitychange", onVisibility);
+	const unsubscribeSignal = opts.subscribeSignal?.(() => void run(true));
+	let pollTimer;
+	if (pollMs > 0) pollTimer = setInterval(() => {
+		if (isVisible()) run(false);
+	}, pollMs);
+	return {
+		refreshNow: () => void run(true),
+		stop: () => {
+			if (stopped) return;
+			stopped = true;
+			if (win) {
+				win.removeEventListener("focus", onFocus);
+				win.removeEventListener("online", onOnline);
+			}
+			if (doc) doc.removeEventListener("visibilitychange", onVisibility);
+			unsubscribeSignal?.();
+			if (pollTimer !== void 0) clearInterval(pollTimer);
+		}
+	};
+}
+//#endregion
+//#region src/live-session.ts
+/**
+* @poly-x/react/live-session — the React glue that keeps the BFF session live (SDK v2).
+*
+* `useLiveAuthz` starts the framework-agnostic orchestrator (`startLiveAuthz`, F013) bound to the
+* BFF session store's `refresh()`: the platform `authz:changed` signal (when a `subscribeSignal`
+* transport is supplied) + window focus/reconnect + a ~60s safety poll → a single-flight
+* re-introspect that updates reactive `useUser()`. `useAuthzChanged` lets an app with its own guard
+* layer react to a change (FR-REACT-1). Apps that gate on `useUser()` re-guard automatically
+* (FR-REACT-2) — they need no callback.
+*
+* The `subscribeSignal` transport is optional: without it the passive triggers still converge
+* (FR-SIG-4). The default poly-alert transport is provided separately (a later slice) once the
+* subscription-credential custody decision lands.
+*/
+const changeListeners = /* @__PURE__ */ new Set();
+function emitChanged() {
+	for (const listener of changeListeners) listener();
+}
+/**
+* Start the live-authz orchestrator for this app's BFF session. Mount once (e.g. in the app root).
+* Returns nothing; drives `useUser()` reactivity + fires `useAuthzChanged` callbacks on a change.
+*/
+function useLiveAuthz(options = {}) {
+	const { subscribeSignal, pollMs, focusThrottleMs } = options;
+	(0, react.useEffect)(() => {
+		const store = getBffSessionStore();
+		const handle = startLiveAuthz({
+			refresh: () => store.refresh(),
+			onChanged: emitChanged,
+			subscribeSignal,
+			pollMs,
+			focusThrottleMs
+		});
+		return () => handle.stop();
+	}, [
+		subscribeSignal,
+		pollMs,
+		focusThrottleMs
+	]);
+}
+/**
+* Register a callback fired when the user's authorization changes (FR-REACT-1) — for apps that keep
+* their own ability/route model and need to re-run their guard or refetch view data. Apps that gate
+* on `useUser()` do not need this. Requires `useLiveAuthz` to be mounted somewhere in the tree.
+*/
+function useAuthzChanged(callback) {
+	(0, react.useEffect)(() => {
+		changeListeners.add(callback);
+		return () => {
+			changeListeners.delete(callback);
+		};
+	}, [callback]);
+}
+//#endregion
 //#region src/index.ts
 /**
 * @poly-x/react — PolyX SDK for React SPAs. Sign-in UI + orchestration land in
@@ -1974,8 +2140,11 @@ exports.capturePreciseLocation = capturePreciseLocation;
 exports.createLoginController = createLoginController;
 exports.initialsFrom = initialsFrom;
 exports.resolveSide = resolveSide;
+exports.startLiveAuthz = startLiveAuthz;
 exports.useAuth = useAuth;
 exports.useAuthCallback = useAuthCallback;
+exports.useAuthzChanged = useAuthzChanged;
+exports.useLiveAuthz = useLiveAuthz;
 exports.useSession = useSession;
 exports.useUser = useUser;
 exports.version = version;

package/dist/index.d.cts

@@ -631,6 +631,68 @@ declare function UserAvatar({
   className
 }: UserAvatarProps): ReactNode;
 //#endregion
+//#region src/live-authz.d.ts
+/**
+ * @poly-x/react/live-authz — keeps live claims current (SDK v2: FR-LIVE, FR-SIG, FR-TRIG).
+ *
+ * Orchestrates the refresh triggers behind ADR-0008/0009: the platform `authz:changed` signal
+ * (instant), window focus / tab-visible, network reconnect, and a **hidden-pausing safety poll**
+ * (~60s) as the staleness ceiling. Every refresh coalesces through a **single-flight** guard;
+ * focus/reconnect are throttled so churn never storms the platform; the push signal is never
+ * throttled (it's an explicit change). The injected `refresh` reports whether claims actually
+ * changed, so `onChanged` (which drives `useAuthzChanged`) fires only on a real change (FR-REACT-5).
+ *
+ * Pure of React — unit-testable with injected window/document + fake timers.
+ */
+interface LiveAuthzOptions {
+  /** Bring claims current; resolves `true` if the claims actually changed. Errors are swallowed
+   *  (keep last-known — FR-LIVE-1 / EC-LIVE-1). */
+  refresh: () => Promise<boolean>;
+  /** Subscribe to the platform `authz:changed` signal; return an unsubscribe fn (ADR-0008). */
+  subscribeSignal?: (onSignal: () => void) => () => void;
+  /** Fired after a triggered refresh that changed claims (drives `useAuthzChanged`). */
+  onChanged?: () => void;
+  /** Background safety-poll interval in ms. Default 60000; `<= 0` disables the poll. */
+  pollMs?: number;
+  /** Throttle window (ms) for focus/reconnect/visibility refreshes. Default 5000. */
+  focusThrottleMs?: number;
+  /** Injectable window (tests). Defaults to the global `window` when present. */
+  win?: Pick<Window, "addEventListener" | "removeEventListener">;
+  /** Injectable document (tests). Defaults to the global `document` when present. */
+  doc?: Pick<Document, "addEventListener" | "removeEventListener"> & {
+    readonly visibilityState: DocumentVisibilityState;
+  };
+}
+interface LiveAuthzHandle {
+  /** Trigger a coalesced refresh immediately (used by the push signal). */
+  refreshNow: () => void;
+  /** Detach every listener + timer. Idempotent. */
+  stop: () => void;
+}
+/** Wire the triggers and return a handle. Safe to call with no window/document (SSR → no-op wiring). */
+declare function startLiveAuthz(opts: LiveAuthzOptions): LiveAuthzHandle;
+//#endregion
+//#region src/live-session.d.ts
+interface UseLiveAuthzOptions {
+  /** Optional push transport (ADR-0008). Omit to run passive-only (focus/reconnect/poll). */
+  subscribeSignal?: LiveAuthzOptions["subscribeSignal"];
+  /** Safety-poll interval (ms). Default 60000; `<= 0` disables. */
+  pollMs?: number;
+  /** Throttle window (ms) for focus/reconnect refreshes. Default 5000. */
+  focusThrottleMs?: number;
+}
+/**
+ * Start the live-authz orchestrator for this app's BFF session. Mount once (e.g. in the app root).
+ * Returns nothing; drives `useUser()` reactivity + fires `useAuthzChanged` callbacks on a change.
+ */
+declare function useLiveAuthz(options?: UseLiveAuthzOptions): void;
+/**
+ * Register a callback fired when the user's authorization changes (FR-REACT-1) — for apps that keep
+ * their own ability/route model and need to re-run their guard or refetch view data. Apps that gate
+ * on `useUser()` do not need this. Requires `useLiveAuthz` to be mounted somewhere in the tree.
+ */
+declare function useAuthzChanged(callback: () => void): void;
+//#endregion
 //#region src/index.d.ts
 /**
  * @poly-x/react — PolyX SDK for React SPAs. Sign-in UI + orchestration land in
@@ -639,4 +701,4 @@ declare function UserAvatar({
 declare const PACKAGE_NAME = "@poly-x/react";
 declare const version = "0.0.0";
 //#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 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, UserAvatar, type UserAvatarProps, UserButton, type UserButtonActionProps, type UserButtonLabels, type UserButtonLinkProps, type UserButtonProps, type UserButtonSlotProps, WebLocksLock, WindowBrowserBridge, capturePreciseLocation, createLoginController, initialsFrom, resolveSide, useAuth, useAuthCallback, useSession, useUser, version };
+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 };

package/dist/index.d.mts

@@ -631,6 +631,68 @@ declare function UserAvatar({
   className
 }: UserAvatarProps): ReactNode;
 //#endregion
+//#region src/live-authz.d.ts
+/**
+ * @poly-x/react/live-authz — keeps live claims current (SDK v2: FR-LIVE, FR-SIG, FR-TRIG).
+ *
+ * Orchestrates the refresh triggers behind ADR-0008/0009: the platform `authz:changed` signal
+ * (instant), window focus / tab-visible, network reconnect, and a **hidden-pausing safety poll**
+ * (~60s) as the staleness ceiling. Every refresh coalesces through a **single-flight** guard;
+ * focus/reconnect are throttled so churn never storms the platform; the push signal is never
+ * throttled (it's an explicit change). The injected `refresh` reports whether claims actually
+ * changed, so `onChanged` (which drives `useAuthzChanged`) fires only on a real change (FR-REACT-5).
+ *
+ * Pure of React — unit-testable with injected window/document + fake timers.
+ */
+interface LiveAuthzOptions {
+  /** Bring claims current; resolves `true` if the claims actually changed. Errors are swallowed
+   *  (keep last-known — FR-LIVE-1 / EC-LIVE-1). */
+  refresh: () => Promise<boolean>;
+  /** Subscribe to the platform `authz:changed` signal; return an unsubscribe fn (ADR-0008). */
+  subscribeSignal?: (onSignal: () => void) => () => void;
+  /** Fired after a triggered refresh that changed claims (drives `useAuthzChanged`). */
+  onChanged?: () => void;
+  /** Background safety-poll interval in ms. Default 60000; `<= 0` disables the poll. */
+  pollMs?: number;
+  /** Throttle window (ms) for focus/reconnect/visibility refreshes. Default 5000. */
+  focusThrottleMs?: number;
+  /** Injectable window (tests). Defaults to the global `window` when present. */
+  win?: Pick<Window, "addEventListener" | "removeEventListener">;
+  /** Injectable document (tests). Defaults to the global `document` when present. */
+  doc?: Pick<Document, "addEventListener" | "removeEventListener"> & {
+    readonly visibilityState: DocumentVisibilityState;
+  };
+}
+interface LiveAuthzHandle {
+  /** Trigger a coalesced refresh immediately (used by the push signal). */
+  refreshNow: () => void;
+  /** Detach every listener + timer. Idempotent. */
+  stop: () => void;
+}
+/** Wire the triggers and return a handle. Safe to call with no window/document (SSR → no-op wiring). */
+declare function startLiveAuthz(opts: LiveAuthzOptions): LiveAuthzHandle;
+//#endregion
+//#region src/live-session.d.ts
+interface UseLiveAuthzOptions {
+  /** Optional push transport (ADR-0008). Omit to run passive-only (focus/reconnect/poll). */
+  subscribeSignal?: LiveAuthzOptions["subscribeSignal"];
+  /** Safety-poll interval (ms). Default 60000; `<= 0` disables. */
+  pollMs?: number;
+  /** Throttle window (ms) for focus/reconnect refreshes. Default 5000. */
+  focusThrottleMs?: number;
+}
+/**
+ * Start the live-authz orchestrator for this app's BFF session. Mount once (e.g. in the app root).
+ * Returns nothing; drives `useUser()` reactivity + fires `useAuthzChanged` callbacks on a change.
+ */
+declare function useLiveAuthz(options?: UseLiveAuthzOptions): void;
+/**
+ * Register a callback fired when the user's authorization changes (FR-REACT-1) — for apps that keep
+ * their own ability/route model and need to re-run their guard or refetch view data. Apps that gate
+ * on `useUser()` do not need this. Requires `useLiveAuthz` to be mounted somewhere in the tree.
+ */
+declare function useAuthzChanged(callback: () => void): void;
+//#endregion
 //#region src/index.d.ts
 /**
  * @poly-x/react — PolyX SDK for React SPAs. Sign-in UI + orchestration land in
@@ -639,4 +701,4 @@ declare function UserAvatar({
 declare const PACKAGE_NAME = "@poly-x/react";
 declare const version = "0.0.0";
 //#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 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, UserAvatar, type UserAvatarProps, UserButton, type UserButtonActionProps, type UserButtonLabels, type UserButtonLinkProps, type UserButtonProps, type UserButtonSlotProps, WebLocksLock, WindowBrowserBridge, capturePreciseLocation, createLoginController, initialsFrom, resolveSide, useAuth, useAuthCallback, useSession, useUser, version };
+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 };

package/dist/index.mjs

@@ -406,6 +406,40 @@ var BffSessionStore = class {
 			this.loading = false;
 		}
 	}
+	/**
+	* v2 (FR-LIVE-1/2): re-read server truth and update claims, resolving whether **authorization
+	* actually changed**. Drives the live-authz orchestrator (`startLiveAuthz`): a `true` means a
+	* consumer that gates on `useUser()` should re-guard. Never flickers to `resolving`; a definite
+	* signed-out answer signs the user out (revoked), a network blip keeps the last-known claims.
+	* The orchestrator single-flights callers, so this needs no internal in-flight guard.
+	*/
+	refresh = async () => {
+		try {
+			const response = await fetch(SESSION_ENDPOINT, {
+				credentials: "same-origin",
+				headers: { accept: "application/json" }
+			});
+			const body = response.ok ? await response.json() : null;
+			if (!Boolean(body?.isSignedIn && body.claims)) {
+				const changed = this.state.status !== "signed-out";
+				if (changed) this.set({
+					status: "signed-out",
+					reason: "revoked"
+				});
+				return changed;
+			}
+			const prevClaims = this.state.status === "authenticated" ? JSON.stringify(this.state.session.claims) : null;
+			const nextClaims = body.claims;
+			const changed = prevClaims !== JSON.stringify(nextClaims);
+			if (changed) this.set({
+				status: "authenticated",
+				session: { claims: nextClaims }
+			});
+			return changed;
+		} catch {
+			return false;
+		}
+	};
 	set(next) {
 		this.state = next;
 		for (const listener of this.listeners) listener();
@@ -1945,6 +1979,138 @@ const UserButton = Object.assign(UserButtonRoot, {
 	Header
 });
 //#endregion
+//#region src/live-authz.ts
+const DEFAULT_POLL_MS = 6e4;
+const DEFAULT_FOCUS_THROTTLE_MS = 5e3;
+/** Wire the triggers and return a handle. Safe to call with no window/document (SSR → no-op wiring). */
+function startLiveAuthz(opts) {
+	const pollMs = opts.pollMs ?? DEFAULT_POLL_MS;
+	const throttleMs = opts.focusThrottleMs ?? DEFAULT_FOCUS_THROTTLE_MS;
+	const win = opts.win ?? (typeof window !== "undefined" ? window : void 0);
+	const doc = opts.doc ?? (typeof document !== "undefined" ? document : void 0);
+	let stopped = false;
+	let inFlight = false;
+	let pending = false;
+	let lastRefreshAt = -Infinity;
+	/**
+	* Single-flight refresh (FR-LIVE-5). `coalesce` = queue exactly one follow-up run if a refresh
+	* is already in flight — used by the explicit push signal so a change mid-refresh isn't missed.
+	* Ambient triggers (focus/online/poll) pass `false`: if a refresh is already running, drop —
+	* they carry no new information the in-flight run won't already pick up.
+	*/
+	async function run(coalesce) {
+		if (stopped) return;
+		if (inFlight) {
+			if (coalesce) pending = true;
+			return;
+		}
+		inFlight = true;
+		try {
+			let changed = false;
+			try {
+				changed = await opts.refresh();
+			} catch {}
+			lastRefreshAt = Date.now();
+			if (changed && !stopped) opts.onChanged?.();
+		} finally {
+			inFlight = false;
+			if (pending && !stopped) {
+				pending = false;
+				run(true);
+			}
+		}
+	}
+	/** Throttled, non-queuing refresh for ambient triggers (focus/visible/online). */
+	function throttledRun() {
+		if (Date.now() - lastRefreshAt >= throttleMs) run(false);
+	}
+	const isVisible = () => !doc || doc.visibilityState !== "hidden";
+	const onFocus = () => throttledRun();
+	const onOnline = () => throttledRun();
+	const onVisibility = () => {
+		if (isVisible()) throttledRun();
+	};
+	if (win) {
+		win.addEventListener("focus", onFocus);
+		win.addEventListener("online", onOnline);
+	}
+	if (doc) doc.addEventListener("visibilitychange", onVisibility);
+	const unsubscribeSignal = opts.subscribeSignal?.(() => void run(true));
+	let pollTimer;
+	if (pollMs > 0) pollTimer = setInterval(() => {
+		if (isVisible()) run(false);
+	}, pollMs);
+	return {
+		refreshNow: () => void run(true),
+		stop: () => {
+			if (stopped) return;
+			stopped = true;
+			if (win) {
+				win.removeEventListener("focus", onFocus);
+				win.removeEventListener("online", onOnline);
+			}
+			if (doc) doc.removeEventListener("visibilitychange", onVisibility);
+			unsubscribeSignal?.();
+			if (pollTimer !== void 0) clearInterval(pollTimer);
+		}
+	};
+}
+//#endregion
+//#region src/live-session.ts
+/**
+* @poly-x/react/live-session — the React glue that keeps the BFF session live (SDK v2).
+*
+* `useLiveAuthz` starts the framework-agnostic orchestrator (`startLiveAuthz`, F013) bound to the
+* BFF session store's `refresh()`: the platform `authz:changed` signal (when a `subscribeSignal`
+* transport is supplied) + window focus/reconnect + a ~60s safety poll → a single-flight
+* re-introspect that updates reactive `useUser()`. `useAuthzChanged` lets an app with its own guard
+* layer react to a change (FR-REACT-1). Apps that gate on `useUser()` re-guard automatically
+* (FR-REACT-2) — they need no callback.
+*
+* The `subscribeSignal` transport is optional: without it the passive triggers still converge
+* (FR-SIG-4). The default poly-alert transport is provided separately (a later slice) once the
+* subscription-credential custody decision lands.
+*/
+const changeListeners = /* @__PURE__ */ new Set();
+function emitChanged() {
+	for (const listener of changeListeners) listener();
+}
+/**
+* Start the live-authz orchestrator for this app's BFF session. Mount once (e.g. in the app root).
+* Returns nothing; drives `useUser()` reactivity + fires `useAuthzChanged` callbacks on a change.
+*/
+function useLiveAuthz(options = {}) {
+	const { subscribeSignal, pollMs, focusThrottleMs } = options;
+	useEffect(() => {
+		const store = getBffSessionStore();
+		const handle = startLiveAuthz({
+			refresh: () => store.refresh(),
+			onChanged: emitChanged,
+			subscribeSignal,
+			pollMs,
+			focusThrottleMs
+		});
+		return () => handle.stop();
+	}, [
+		subscribeSignal,
+		pollMs,
+		focusThrottleMs
+	]);
+}
+/**
+* Register a callback fired when the user's authorization changes (FR-REACT-1) — for apps that keep
+* their own ability/route model and need to re-run their guard or refetch view data. Apps that gate
+* on `useUser()` do not need this. Requires `useLiveAuthz` to be mounted somewhere in the tree.
+*/
+function useAuthzChanged(callback) {
+	useEffect(() => {
+		changeListeners.add(callback);
+		return () => {
+			changeListeners.delete(callback);
+		};
+	}, [callback]);
+}
+//#endregion
 //#region src/index.ts
 /**
 * @poly-x/react — PolyX SDK for React SPAs. Sign-in UI + orchestration land in
@@ -1953,4 +2119,4 @@ const UserButton = Object.assign(UserButtonRoot, {
 const PACKAGE_NAME = "@poly-x/react";
 const version = "0.0.0";
 //#endregion
-export { AuthCallback, BroadcastAuthChannel, BroadcastChannelSessionChannel, ForgotPassword, PACKAGE_NAME, PolyXContext, PolyXProvider, PopupCancelledError, Protected, ResetPassword, SessionStoragePkceStore, SignIn, UserAvatar, UserButton, WebLocksLock, WindowBrowserBridge, capturePreciseLocation, createLoginController, initialsFrom, resolveSide, useAuth, useAuthCallback, useSession, useUser, version };
+export { AuthCallback, BroadcastAuthChannel, BroadcastChannelSessionChannel, ForgotPassword, PACKAGE_NAME, PolyXContext, PolyXProvider, PopupCancelledError, Protected, ResetPassword, SessionStoragePkceStore, SignIn, UserAvatar, UserButton, WebLocksLock, WindowBrowserBridge, capturePreciseLocation, createLoginController, initialsFrom, resolveSide, startLiveAuthz, useAuth, useAuthCallback, useAuthzChanged, useLiveAuthz, useSession, useUser, version };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poly-x/react",
-  "version": "0.1.0-alpha.18",
+  "version": "0.1.0-alpha.19",
   "description": "PolyX SDK for React SPAs - provider, hooks, drop-in auth UI",
   "license": "MIT",
   "type": "module",
@@ -27,7 +27,7 @@
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.cts",
   "dependencies": {
-    "@poly-x/core": "0.1.0-alpha.18"
+    "@poly-x/core": "0.1.0-alpha.19"
   },
   "peerDependencies": {
     "react": ">=18",