@poly-x/react 0.1.0-alpha.0

package/README.md

@@ -0,0 +1,51 @@
+# @poly-x/react
+
+PolyX authentication for any React app — a provider, hooks, and drop-in sign-in
+components. On brand, secure by default, with cross-tab session sync and silent
+refresh handled for you.
+
+## Install
+
+```bash
+npm install @poly-x/react
+```
+
+## Quickstart
+
+Wrap your app with the provider (a `pk_…` publishable key is all it needs):
+
+```tsx
+import { PolyXProvider } from "@poly-x/react";
+
+export function Root({ children }) {
+  return <PolyXProvider publishableKey={import.meta.env.VITE_POLYX_PUBLISHABLE_KEY}>{children}</PolyXProvider>;
+}
+```
+
+Drop in sign-in and gate content:
+
+```tsx
+import { SignIn, Protected, useAuth, useUser } from "@poly-x/react";
+
+function Header() {
+  const { isSignedIn, signOut } = useAuth();
+  const user = useUser();
+  return isSignedIn ? <button onClick={() => signOut()}>Sign out {user?.userId}</button> : <SignIn />;
+}
+
+function Dashboard() {
+  return <Protected fallback={<SignIn />} loading={<Spinner />}><SecretStuff /></Protected>;
+}
+```
+
+Add a callback route (`/auth/callback`) that renders `<AuthCallback />` to
+complete sign-in.
+
+## API
+
+`PolyXProvider` · `useAuth` (`isLoaded`, `isSignedIn`, `signIn`, `signOut`,
+`getToken`) · `useUser` · `useSession` · `<SignIn>` · `<Protected>` ·
+`<AuthCallback>`. Sign-in defaults to a popup; pass `mode="redirect"` for a
+full-page flow.
+
+MIT licensed.

package/dist/index.cjs

@@ -0,0 +1,396 @@
+"use client";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _poly_x_core = require("@poly-x/core");
+let react = require("react");
+let react_jsx_runtime = require("react/jsx-runtime");
+//#region src/auth-channel.ts
+var BroadcastAuthChannel = class {
+	supported;
+	channel;
+	listeners = /* @__PURE__ */ new Set();
+	constructor(name = "poly-x.auth") {
+		this.supported = typeof BroadcastChannel !== "undefined";
+		if (this.supported) {
+			this.channel = new BroadcastChannel(name);
+			this.channel.onmessage = (event) => {
+				const data = event.data;
+				if (data?.type === "auth-callback") for (const listener of [...this.listeners]) listener(data);
+			};
+		}
+	}
+	post(message) {
+		this.channel?.postMessage(message);
+	}
+	subscribe(listener) {
+		this.listeners.add(listener);
+		return () => this.listeners.delete(listener);
+	}
+	close() {
+		this.channel?.close();
+	}
+};
+//#endregion
+//#region src/browser-bridge.ts
+var WindowBrowserBridge = class {
+	openPopup(url, name = "polyx-auth") {
+		const win = window.open(url, name, "width=480,height=680");
+		if (!win) return null;
+		return {
+			get closed() {
+				return win.closed;
+			},
+			close: () => win.close()
+		};
+	}
+	redirect(url) {
+		window.location.assign(url);
+	}
+	isPopupContext() {
+		return typeof window !== "undefined" && window.opener != null && window.opener !== window;
+	}
+	readCallbackParams() {
+		const params = new URLSearchParams(window.location.search);
+		return {
+			code: params.get("code") ?? void 0,
+			state: params.get("state") ?? void 0
+		};
+	}
+	currentUrl() {
+		return window.location.href;
+	}
+	currentOrigin() {
+		return window.location.origin;
+	}
+	replaceUrl(url) {
+		window.history.replaceState({}, "", url);
+	}
+	closeSelf() {
+		window.close();
+	}
+};
+//#endregion
+//#region src/context.ts
+const PolyXContext = (0, react.createContext)(null);
+//#endregion
+//#region src/login-controller.ts
+/**
+* Sign-in orchestration (F006), framework-agnostic within the browser: it
+* composes the auth client, PKCE store, browser bridge, and auth channel to run
+* both delivery modes (popup default + redirect, D2b). All decision logic lives
+* here; the `window` specifics are behind the BrowserBridge seam.
+*/
+var PopupCancelledError = class extends Error {
+	constructor() {
+		super("Sign-in was cancelled before it completed.");
+		this.name = "PopupCancelledError";
+	}
+};
+function createLoginController(deps) {
+	const { engine, authClient, pkceStore, bridge, channel } = deps;
+	const pollMs = deps.popupPollMs ?? 300;
+	async function complete(code, state) {
+		const entry = await pkceStore.take(state);
+		if (!entry) throw new Error("Sign-in state did not match a pending request (expired or replayed). Please retry.");
+		const stored = await authClient.exchangeCode({
+			code,
+			codeVerifier: entry.verifier,
+			redirectUri: entry.redirectUri
+		});
+		await engine.establishSession(stored);
+	}
+	async function signIn(options = {}) {
+		const mode = options.mode ?? "popup";
+		const redirectUri = options.redirectUrl ?? `${bridge.currentOrigin()}/auth/callback`;
+		const { verifier, challenge } = await (0, _poly_x_core.generatePkce)();
+		const state = (0, _poly_x_core.randomState)();
+		await pkceStore.save({
+			state,
+			verifier,
+			redirectUri,
+			createdAt: Date.now()
+		});
+		const url = authClient.buildAuthorizeUrl({
+			redirectUri,
+			state,
+			challenge,
+			organizationCode: options.organizationCode
+		});
+		if (mode === "redirect") {
+			bridge.redirect(url);
+			return;
+		}
+		if (!channel.supported) throw new Error("Popup sign-in requires BroadcastChannel; use mode: \"redirect\" instead.");
+		const popup = bridge.openPopup(url);
+		if (!popup) throw new Error("The sign-in popup was blocked. Use mode: \"redirect\" instead.");
+		await new Promise((resolve, reject) => {
+			let settled = false;
+			const finish = (fn) => {
+				if (settled) return;
+				settled = true;
+				unsubscribe();
+				clearInterval(poll);
+				fn();
+			};
+			const unsubscribe = channel.subscribe((message) => {
+				if (message.state !== state) return;
+				complete(message.code, message.state).then(() => finish(() => {
+					popup.close();
+					resolve();
+				}), (error) => finish(() => reject(error)));
+			});
+			const poll = setInterval(() => {
+				if (popup.closed) finish(() => reject(new PopupCancelledError()));
+			}, pollMs);
+		});
+	}
+	async function handleCallback() {
+		const { code, state } = bridge.readCallbackParams();
+		if (!code || !state) return;
+		if (bridge.isPopupContext()) {
+			channel.post({
+				type: "auth-callback",
+				code,
+				state
+			});
+			bridge.closeSelf();
+			return;
+		}
+		await complete(code, state);
+		const url = new URL(bridge.currentUrl());
+		url.searchParams.delete("code");
+		url.searchParams.delete("state");
+		bridge.replaceUrl(url.pathname + url.search + url.hash);
+	}
+	return {
+		signIn,
+		handleCallback
+	};
+}
+//#endregion
+//#region src/seams/broadcast-channel.ts
+/**
+* Cross-tab session channel over `BroadcastChannel` (ADR-0005). Delivers to
+* other tabs only (never echoes to the poster — the correct cross-tab
+* semantic). Falls back to core's in-memory channel where `BroadcastChannel`
+* is unavailable (SSR, older engines) so the provider never crashes.
+*/
+var BroadcastChannelSessionChannel = class {
+	channel;
+	fallback;
+	listeners = /* @__PURE__ */ new Set();
+	constructor(name = "poly-x.session") {
+		if (typeof BroadcastChannel !== "undefined") {
+			this.channel = new BroadcastChannel(name);
+			this.channel.onmessage = (event) => {
+				for (const listener of [...this.listeners]) listener(event.data);
+			};
+		} else this.fallback = new _poly_x_core.InMemorySessionChannel();
+	}
+	publish(event) {
+		if (this.channel) this.channel.postMessage(event);
+		else this.fallback?.publish(event);
+	}
+	subscribe(listener) {
+		if (this.fallback) return this.fallback.subscribe(listener);
+		this.listeners.add(listener);
+		return () => this.listeners.delete(listener);
+	}
+};
+//#endregion
+//#region src/seams/session-storage-pkce.ts
+const KEY_PREFIX = "poly-x.pkce.";
+function hasSessionStorage() {
+	try {
+		return typeof sessionStorage !== "undefined";
+	} catch {
+		return false;
+	}
+}
+/**
+* PKCE-transaction custody in `sessionStorage` so the verifier + redirect
+* survive a full-page redirect to the PolyX login and back (ADR-0005). Falls
+* back to in-memory where `sessionStorage` is unavailable — the transaction
+* then only survives an in-page popup flow, which is the SPA default anyway.
+*/
+var SessionStoragePkceStore = class {
+	fallback;
+	constructor() {
+		if (!hasSessionStorage()) this.fallback = new _poly_x_core.InMemoryPkceStore();
+	}
+	save(entry) {
+		if (this.fallback) return this.fallback.save(entry);
+		sessionStorage.setItem(KEY_PREFIX + entry.state, JSON.stringify(entry));
+		return Promise.resolve();
+	}
+	take(state) {
+		if (this.fallback) return this.fallback.take(state);
+		const raw = sessionStorage.getItem(KEY_PREFIX + state);
+		if (raw === null) return Promise.resolve(null);
+		sessionStorage.removeItem(KEY_PREFIX + state);
+		try {
+			return Promise.resolve(JSON.parse(raw));
+		} catch {
+			return Promise.resolve(null);
+		}
+	}
+};
+//#endregion
+//#region src/seams/web-locks.ts
+function hasWebLocks() {
+	return typeof navigator !== "undefined" && typeof navigator.locks?.request === "function";
+}
+/**
+* Single-flight refresh coordination over the Web Locks API (ADR-0005), so a
+* refresh is serialized across tabs, not just within one. Falls back to core's
+* in-memory lock where `navigator.locks` is absent (Node/happy-dom, older
+* Safari) — serialization within the tab is preserved.
+*/
+var WebLocksLock = class {
+	fallback;
+	constructor() {
+		if (!hasWebLocks()) this.fallback = new _poly_x_core.InMemoryLock();
+	}
+	runExclusive(key, fn) {
+		if (this.fallback) return this.fallback.runExclusive(key, fn);
+		return navigator.locks.request(`poly-x.${key}`, () => fn());
+	}
+};
+//#endregion
+//#region src/provider.tsx
+function PolyXProvider({ publishableKey, baseUrl, children }) {
+	const value = (0, react.useMemo)(() => {
+		const authClient = new _poly_x_core.AuthClient({
+			config: (0, _poly_x_core.resolveConfig)({
+				key: publishableKey,
+				baseUrl,
+				context: "browser"
+			}),
+			transport: new _poly_x_core.FetchTransport()
+		});
+		const engine = (0, _poly_x_core.createSessionEngine)({
+			refreshTokens: authClient.createRefresher(),
+			store: new _poly_x_core.InMemorySessionStore(),
+			channel: new BroadcastChannelSessionChannel(),
+			lock: new WebLocksLock()
+		});
+		return {
+			engine,
+			authClient,
+			controller: createLoginController({
+				engine,
+				authClient,
+				pkceStore: new SessionStoragePkceStore(),
+				bridge: new WindowBrowserBridge(),
+				channel: new BroadcastAuthChannel()
+			})
+		};
+	}, [publishableKey, baseUrl]);
+	(0, react.useEffect)(() => {
+		value.engine.hydrate();
+		return () => value.engine.dispose();
+	}, [value]);
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(PolyXContext.Provider, {
+		value,
+		children
+	});
+}
+//#endregion
+//#region src/hooks.ts
+function usePolyX() {
+	const ctx = (0, react.useContext)(PolyXContext);
+	if (!ctx) throw new Error("PolyX hooks (useAuth/useUser/useSession) must be used within a <PolyXProvider>.");
+	return ctx;
+}
+/** The raw session state machine value — tearing-free under concurrent React. */
+function useSession() {
+	const { engine } = usePolyX();
+	const subscribe = (0, react.useCallback)((onChange) => engine.subscribe(onChange), [engine]);
+	const getSnapshot = (0, react.useCallback)(() => engine.getState(), [engine]);
+	return (0, react.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+}
+function useAuth() {
+	const { engine, controller } = usePolyX();
+	const state = useSession();
+	const signIn = (0, react.useCallback)((options) => controller.signIn(options), [controller]);
+	const signOut = (0, react.useCallback)(() => engine.signOut(), [engine]);
+	const getToken = (0, react.useCallback)(async () => {
+		try {
+			return await engine.getAccessToken();
+		} catch {
+			return null;
+		}
+	}, [engine]);
+	return {
+		isLoaded: state.status !== "resolving",
+		isSignedIn: state.status === "authenticated" || state.status === "refreshing",
+		signIn,
+		signOut,
+		getToken
+	};
+}
+/** Run this on your callback route to complete a sign-in (see `<AuthCallback>`). */
+function useAuthCallback() {
+	const { controller } = usePolyX();
+	return (0, react.useCallback)(() => controller.handleCallback(), [controller]);
+}
+function useUser() {
+	const state = useSession();
+	return state.status === "authenticated" || state.status === "refreshing" ? state.session.claims : null;
+}
+//#endregion
+//#region src/components/protected.tsx
+/** Gate content on authentication state without flashing the wrong branch. */
+function Protected({ children, fallback = null, loading = null }) {
+	const { isLoaded, isSignedIn } = useAuth();
+	if (!isLoaded) return loading;
+	return isSignedIn ? children : fallback;
+}
+//#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__ */ (0, react_jsx_runtime.jsx)("button", {
+		type: "button",
+		className,
+		onClick: () => void signIn(options),
+		children: children ?? "Sign in"
+	});
+}
+//#endregion
+//#region src/components/auth-callback.tsx
+/** Drop on your `/auth/callback` route: completes the sign-in exchange on mount. */
+function AuthCallback({ children = null }) {
+	const handleCallback = useAuthCallback();
+	(0, react.useEffect)(() => {
+		handleCallback();
+	}, [handleCallback]);
+	return children;
+}
+//#endregion
+//#region src/index.ts
+/**
+* @poly-x/react — PolyX SDK for React SPAs. Sign-in UI + orchestration land in
+* F006; this entry is the state foundation (provider, hooks, browser seams).
+*/
+const PACKAGE_NAME = "@poly-x/react";
+const version = "0.0.0";
+//#endregion
+exports.AuthCallback = AuthCallback;
+exports.BroadcastAuthChannel = BroadcastAuthChannel;
+exports.BroadcastChannelSessionChannel = BroadcastChannelSessionChannel;
+exports.PACKAGE_NAME = PACKAGE_NAME;
+exports.PolyXContext = PolyXContext;
+exports.PolyXProvider = PolyXProvider;
+exports.PopupCancelledError = PopupCancelledError;
+exports.Protected = Protected;
+exports.SessionStoragePkceStore = SessionStoragePkceStore;
+exports.SignIn = SignIn;
+exports.WebLocksLock = WebLocksLock;
+exports.WindowBrowserBridge = WindowBrowserBridge;
+exports.createLoginController = createLoginController;
+exports.useAuth = useAuth;
+exports.useAuthCallback = useAuthCallback;
+exports.useSession = useSession;
+exports.useUser = useUser;
+exports.version = version;

package/dist/index.d.cts

@@ -0,0 +1,220 @@
+import { ReactNode } from "react";
+import { AuthClient, Lock, PkceEntry, PkceStore, SessionChannel, SessionChannelEvent, SessionClaims, SessionEngine, SessionState } from "@poly-x/core";
+
+//#region src/provider.d.ts
+interface PolyXProviderProps {
+  /** The `pk_…` publishable key for this app instance. */
+  publishableKey: string;
+  /** Override the key-embedded deployment host (proxies, container-internal). */
+  baseUrl?: string;
+  children: ReactNode;
+}
+declare function PolyXProvider({
+  publishableKey,
+  baseUrl,
+  children
+}: PolyXProviderProps): ReactNode;
+//#endregion
+//#region src/auth-channel.d.ts
+/**
+ * Same-origin popup→opener handoff of the authorization `code` (F006). The
+ * popup posts the short-lived code here and closes; the opener does the token
+ * exchange, so tokens never transit the channel. Falls back to unsupported
+ * (redirect mode still works) where `BroadcastChannel` is absent.
+ */
+interface AuthCallbackMessage {
+  type: "auth-callback";
+  code: string;
+  state: string;
+}
+interface AuthChannel {
+  readonly supported: boolean;
+  post(message: AuthCallbackMessage): void;
+  subscribe(listener: (message: AuthCallbackMessage) => void): () => void;
+  close(): void;
+}
+declare class BroadcastAuthChannel implements AuthChannel {
+  readonly supported: boolean;
+  private readonly channel?;
+  private readonly listeners;
+  constructor(name?: string);
+  post(message: AuthCallbackMessage): void;
+  subscribe(listener: (message: AuthCallbackMessage) => void): () => void;
+  close(): void;
+}
+//#endregion
+//#region src/browser-bridge.d.ts
+/**
+ * The irreducibly browser-specific surface of sign-in behind one seam, so the
+ * login controller's decision logic is unit-testable with a fake and the real
+ * `window` adapter stays a thin, un-unit-tested shim (F006 / ADR-0005).
+ */
+interface PopupHandle {
+  readonly closed: boolean;
+  close(): void;
+}
+interface CallbackParams {
+  code?: string;
+  state?: string;
+}
+interface BrowserBridge {
+  openPopup(url: string, name?: string): PopupHandle | null;
+  redirect(url: string): void;
+  /** True when running inside a popup opened by this SDK (has a distinct opener). */
+  isPopupContext(): boolean;
+  readCallbackParams(): CallbackParams;
+  currentUrl(): string;
+  currentOrigin(): string;
+  replaceUrl(url: string): void;
+  closeSelf(): void;
+}
+declare class WindowBrowserBridge implements BrowserBridge {
+  openPopup(url: string, name?: string): PopupHandle | null;
+  redirect(url: string): void;
+  isPopupContext(): boolean;
+  readCallbackParams(): CallbackParams;
+  currentUrl(): string;
+  currentOrigin(): string;
+  replaceUrl(url: string): void;
+  closeSelf(): void;
+}
+//#endregion
+//#region src/login-controller.d.ts
+interface SignInOptions {
+  mode?: "popup" | "redirect";
+  organizationCode?: string;
+  /** Defaults to `${origin}/auth/callback`. */
+  redirectUrl?: string;
+}
+interface LoginController {
+  signIn(options?: SignInOptions): Promise<void>;
+  handleCallback(): Promise<void>;
+}
+interface LoginControllerDeps {
+  engine: SessionEngine;
+  authClient: AuthClient;
+  pkceStore: PkceStore;
+  bridge: BrowserBridge;
+  channel: AuthChannel;
+  /** Poll interval for popup-closed detection (ms). */
+  popupPollMs?: number;
+}
+declare class PopupCancelledError extends Error {
+  constructor();
+}
+declare function createLoginController(deps: LoginControllerDeps): LoginController;
+//#endregion
+//#region src/hooks.d.ts
+/** The raw session state machine value — tearing-free under concurrent React. */
+declare function useSession(): SessionState;
+interface UseAuth {
+  /** False only while the initial session resolves (no-flash gate). */
+  isLoaded: boolean;
+  isSignedIn: boolean;
+  signIn: (options?: SignInOptions) => Promise<void>;
+  signOut: () => Promise<void>;
+  /** Current access token, refreshing if needed; null when signed out. */
+  getToken: () => Promise<string | null>;
+}
+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;
+//#endregion
+//#region src/context.d.ts
+interface PolyXContextValue {
+  engine: SessionEngine;
+  authClient: AuthClient;
+  controller: LoginController;
+}
+declare const PolyXContext: import("react").Context<PolyXContextValue | null>;
+//#endregion
+//#region src/seams/broadcast-channel.d.ts
+/**
+ * Cross-tab session channel over `BroadcastChannel` (ADR-0005). Delivers to
+ * other tabs only (never echoes to the poster — the correct cross-tab
+ * semantic). Falls back to core's in-memory channel where `BroadcastChannel`
+ * is unavailable (SSR, older engines) so the provider never crashes.
+ */
+declare class BroadcastChannelSessionChannel implements SessionChannel {
+  private readonly channel?;
+  private readonly fallback?;
+  private readonly listeners;
+  constructor(name?: string);
+  publish(event: SessionChannelEvent): void;
+  subscribe(listener: (event: SessionChannelEvent) => void): () => void;
+}
+//#endregion
+//#region src/seams/web-locks.d.ts
+/**
+ * Single-flight refresh coordination over the Web Locks API (ADR-0005), so a
+ * refresh is serialized across tabs, not just within one. Falls back to core's
+ * in-memory lock where `navigator.locks` is absent (Node/happy-dom, older
+ * Safari) — serialization within the tab is preserved.
+ */
+declare class WebLocksLock implements Lock {
+  private readonly fallback?;
+  constructor();
+  runExclusive<T>(key: string, fn: () => Promise<T>): Promise<T>;
+}
+//#endregion
+//#region src/seams/session-storage-pkce.d.ts
+/**
+ * PKCE-transaction custody in `sessionStorage` so the verifier + redirect
+ * survive a full-page redirect to the PolyX login and back (ADR-0005). Falls
+ * back to in-memory where `sessionStorage` is unavailable — the transaction
+ * then only survives an in-page popup flow, which is the SPA default anyway.
+ */
+declare class SessionStoragePkceStore implements PkceStore {
+  private readonly fallback?;
+  constructor();
+  save(entry: PkceEntry): Promise<void>;
+  take(state: string): Promise<PkceEntry | null>;
+}
+//#endregion
+//#region src/components/protected.d.ts
+interface ProtectedProps {
+  children: ReactNode;
+  /** Rendered when signed out. */
+  fallback?: ReactNode;
+  /** Rendered while the initial session resolves (no-flash gate). */
+  loading?: ReactNode;
+}
+/** Gate content on authentication state without flashing the wrong branch. */
+declare function Protected({
+  children,
+  fallback,
+  loading
+}: ProtectedProps): ReactNode;
+//#endregion
+//#region src/components/sign-in.d.ts
+interface SignInProps extends SignInOptions {
+  children?: ReactNode;
+  className?: string;
+}
+/** Minimal sign-in trigger — popup by default. Style via `className`/children. */
+declare function SignIn({
+  children,
+  className,
+  ...options
+}: SignInProps): ReactNode;
+//#endregion
+//#region src/components/auth-callback.d.ts
+interface AuthCallbackProps {
+  /** Rendered while the exchange completes (e.g. a spinner). */
+  children?: ReactNode;
+}
+/** Drop on your `/auth/callback` route: completes the sign-in exchange on mount. */
+declare function AuthCallback({
+  children
+}: AuthCallbackProps): ReactNode;
+//#endregion
+//#region src/index.d.ts
+/**
+ * @poly-x/react — PolyX SDK for React SPAs. Sign-in UI + orchestration land in
+ * F006; this entry is the state foundation (provider, hooks, browser seams).
+ */
+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 };

package/dist/index.d.mts

@@ -0,0 +1,220 @@
+import { AuthClient, Lock, PkceEntry, PkceStore, SessionChannel, SessionChannelEvent, SessionClaims, SessionEngine, SessionState } from "@poly-x/core";
+import { ReactNode } from "react";
+
+//#region src/provider.d.ts
+interface PolyXProviderProps {
+  /** The `pk_…` publishable key for this app instance. */
+  publishableKey: string;
+  /** Override the key-embedded deployment host (proxies, container-internal). */
+  baseUrl?: string;
+  children: ReactNode;
+}
+declare function PolyXProvider({
+  publishableKey,
+  baseUrl,
+  children
+}: PolyXProviderProps): ReactNode;
+//#endregion
+//#region src/auth-channel.d.ts
+/**
+ * Same-origin popup→opener handoff of the authorization `code` (F006). The
+ * popup posts the short-lived code here and closes; the opener does the token
+ * exchange, so tokens never transit the channel. Falls back to unsupported
+ * (redirect mode still works) where `BroadcastChannel` is absent.
+ */
+interface AuthCallbackMessage {
+  type: "auth-callback";
+  code: string;
+  state: string;
+}
+interface AuthChannel {
+  readonly supported: boolean;
+  post(message: AuthCallbackMessage): void;
+  subscribe(listener: (message: AuthCallbackMessage) => void): () => void;
+  close(): void;
+}
+declare class BroadcastAuthChannel implements AuthChannel {
+  readonly supported: boolean;
+  private readonly channel?;
+  private readonly listeners;
+  constructor(name?: string);
+  post(message: AuthCallbackMessage): void;
+  subscribe(listener: (message: AuthCallbackMessage) => void): () => void;
+  close(): void;
+}
+//#endregion
+//#region src/browser-bridge.d.ts
+/**
+ * The irreducibly browser-specific surface of sign-in behind one seam, so the
+ * login controller's decision logic is unit-testable with a fake and the real
+ * `window` adapter stays a thin, un-unit-tested shim (F006 / ADR-0005).
+ */
+interface PopupHandle {
+  readonly closed: boolean;
+  close(): void;
+}
+interface CallbackParams {
+  code?: string;
+  state?: string;
+}
+interface BrowserBridge {
+  openPopup(url: string, name?: string): PopupHandle | null;
+  redirect(url: string): void;
+  /** True when running inside a popup opened by this SDK (has a distinct opener). */
+  isPopupContext(): boolean;
+  readCallbackParams(): CallbackParams;
+  currentUrl(): string;
+  currentOrigin(): string;
+  replaceUrl(url: string): void;
+  closeSelf(): void;
+}
+declare class WindowBrowserBridge implements BrowserBridge {
+  openPopup(url: string, name?: string): PopupHandle | null;
+  redirect(url: string): void;
+  isPopupContext(): boolean;
+  readCallbackParams(): CallbackParams;
+  currentUrl(): string;
+  currentOrigin(): string;
+  replaceUrl(url: string): void;
+  closeSelf(): void;
+}
+//#endregion
+//#region src/login-controller.d.ts
+interface SignInOptions {
+  mode?: "popup" | "redirect";
+  organizationCode?: string;
+  /** Defaults to `${origin}/auth/callback`. */
+  redirectUrl?: string;
+}
+interface LoginController {
+  signIn(options?: SignInOptions): Promise<void>;
+  handleCallback(): Promise<void>;
+}
+interface LoginControllerDeps {
+  engine: SessionEngine;
+  authClient: AuthClient;
+  pkceStore: PkceStore;
+  bridge: BrowserBridge;
+  channel: AuthChannel;
+  /** Poll interval for popup-closed detection (ms). */
+  popupPollMs?: number;
+}
+declare class PopupCancelledError extends Error {
+  constructor();
+}
+declare function createLoginController(deps: LoginControllerDeps): LoginController;
+//#endregion
+//#region src/hooks.d.ts
+/** The raw session state machine value — tearing-free under concurrent React. */
+declare function useSession(): SessionState;
+interface UseAuth {
+  /** False only while the initial session resolves (no-flash gate). */
+  isLoaded: boolean;
+  isSignedIn: boolean;
+  signIn: (options?: SignInOptions) => Promise<void>;
+  signOut: () => Promise<void>;
+  /** Current access token, refreshing if needed; null when signed out. */
+  getToken: () => Promise<string | null>;
+}
+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;
+//#endregion
+//#region src/context.d.ts
+interface PolyXContextValue {
+  engine: SessionEngine;
+  authClient: AuthClient;
+  controller: LoginController;
+}
+declare const PolyXContext: import("react").Context<PolyXContextValue | null>;
+//#endregion
+//#region src/seams/broadcast-channel.d.ts
+/**
+ * Cross-tab session channel over `BroadcastChannel` (ADR-0005). Delivers to
+ * other tabs only (never echoes to the poster — the correct cross-tab
+ * semantic). Falls back to core's in-memory channel where `BroadcastChannel`
+ * is unavailable (SSR, older engines) so the provider never crashes.
+ */
+declare class BroadcastChannelSessionChannel implements SessionChannel {
+  private readonly channel?;
+  private readonly fallback?;
+  private readonly listeners;
+  constructor(name?: string);
+  publish(event: SessionChannelEvent): void;
+  subscribe(listener: (event: SessionChannelEvent) => void): () => void;
+}
+//#endregion
+//#region src/seams/web-locks.d.ts
+/**
+ * Single-flight refresh coordination over the Web Locks API (ADR-0005), so a
+ * refresh is serialized across tabs, not just within one. Falls back to core's
+ * in-memory lock where `navigator.locks` is absent (Node/happy-dom, older
+ * Safari) — serialization within the tab is preserved.
+ */
+declare class WebLocksLock implements Lock {
+  private readonly fallback?;
+  constructor();
+  runExclusive<T>(key: string, fn: () => Promise<T>): Promise<T>;
+}
+//#endregion
+//#region src/seams/session-storage-pkce.d.ts
+/**
+ * PKCE-transaction custody in `sessionStorage` so the verifier + redirect
+ * survive a full-page redirect to the PolyX login and back (ADR-0005). Falls
+ * back to in-memory where `sessionStorage` is unavailable — the transaction
+ * then only survives an in-page popup flow, which is the SPA default anyway.
+ */
+declare class SessionStoragePkceStore implements PkceStore {
+  private readonly fallback?;
+  constructor();
+  save(entry: PkceEntry): Promise<void>;
+  take(state: string): Promise<PkceEntry | null>;
+}
+//#endregion
+//#region src/components/protected.d.ts
+interface ProtectedProps {
+  children: ReactNode;
+  /** Rendered when signed out. */
+  fallback?: ReactNode;
+  /** Rendered while the initial session resolves (no-flash gate). */
+  loading?: ReactNode;
+}
+/** Gate content on authentication state without flashing the wrong branch. */
+declare function Protected({
+  children,
+  fallback,
+  loading
+}: ProtectedProps): ReactNode;
+//#endregion
+//#region src/components/sign-in.d.ts
+interface SignInProps extends SignInOptions {
+  children?: ReactNode;
+  className?: string;
+}
+/** Minimal sign-in trigger — popup by default. Style via `className`/children. */
+declare function SignIn({
+  children,
+  className,
+  ...options
+}: SignInProps): ReactNode;
+//#endregion
+//#region src/components/auth-callback.d.ts
+interface AuthCallbackProps {
+  /** Rendered while the exchange completes (e.g. a spinner). */
+  children?: ReactNode;
+}
+/** Drop on your `/auth/callback` route: completes the sign-in exchange on mount. */
+declare function AuthCallback({
+  children
+}: AuthCallbackProps): ReactNode;
+//#endregion
+//#region src/index.d.ts
+/**
+ * @poly-x/react — PolyX SDK for React SPAs. Sign-in UI + orchestration land in
+ * F006; this entry is the state foundation (provider, hooks, browser seams).
+ */
+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 };

package/dist/index.mjs

@@ -0,0 +1,378 @@
+"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";
+//#region src/auth-channel.ts
+var BroadcastAuthChannel = class {
+	supported;
+	channel;
+	listeners = /* @__PURE__ */ new Set();
+	constructor(name = "poly-x.auth") {
+		this.supported = typeof BroadcastChannel !== "undefined";
+		if (this.supported) {
+			this.channel = new BroadcastChannel(name);
+			this.channel.onmessage = (event) => {
+				const data = event.data;
+				if (data?.type === "auth-callback") for (const listener of [...this.listeners]) listener(data);
+			};
+		}
+	}
+	post(message) {
+		this.channel?.postMessage(message);
+	}
+	subscribe(listener) {
+		this.listeners.add(listener);
+		return () => this.listeners.delete(listener);
+	}
+	close() {
+		this.channel?.close();
+	}
+};
+//#endregion
+//#region src/browser-bridge.ts
+var WindowBrowserBridge = class {
+	openPopup(url, name = "polyx-auth") {
+		const win = window.open(url, name, "width=480,height=680");
+		if (!win) return null;
+		return {
+			get closed() {
+				return win.closed;
+			},
+			close: () => win.close()
+		};
+	}
+	redirect(url) {
+		window.location.assign(url);
+	}
+	isPopupContext() {
+		return typeof window !== "undefined" && window.opener != null && window.opener !== window;
+	}
+	readCallbackParams() {
+		const params = new URLSearchParams(window.location.search);
+		return {
+			code: params.get("code") ?? void 0,
+			state: params.get("state") ?? void 0
+		};
+	}
+	currentUrl() {
+		return window.location.href;
+	}
+	currentOrigin() {
+		return window.location.origin;
+	}
+	replaceUrl(url) {
+		window.history.replaceState({}, "", url);
+	}
+	closeSelf() {
+		window.close();
+	}
+};
+//#endregion
+//#region src/context.ts
+const PolyXContext = createContext(null);
+//#endregion
+//#region src/login-controller.ts
+/**
+* Sign-in orchestration (F006), framework-agnostic within the browser: it
+* composes the auth client, PKCE store, browser bridge, and auth channel to run
+* both delivery modes (popup default + redirect, D2b). All decision logic lives
+* here; the `window` specifics are behind the BrowserBridge seam.
+*/
+var PopupCancelledError = class extends Error {
+	constructor() {
+		super("Sign-in was cancelled before it completed.");
+		this.name = "PopupCancelledError";
+	}
+};
+function createLoginController(deps) {
+	const { engine, authClient, pkceStore, bridge, channel } = deps;
+	const pollMs = deps.popupPollMs ?? 300;
+	async function complete(code, state) {
+		const entry = await pkceStore.take(state);
+		if (!entry) throw new Error("Sign-in state did not match a pending request (expired or replayed). Please retry.");
+		const stored = await authClient.exchangeCode({
+			code,
+			codeVerifier: entry.verifier,
+			redirectUri: entry.redirectUri
+		});
+		await engine.establishSession(stored);
+	}
+	async function signIn(options = {}) {
+		const mode = options.mode ?? "popup";
+		const redirectUri = options.redirectUrl ?? `${bridge.currentOrigin()}/auth/callback`;
+		const { verifier, challenge } = await generatePkce();
+		const state = randomState();
+		await pkceStore.save({
+			state,
+			verifier,
+			redirectUri,
+			createdAt: Date.now()
+		});
+		const url = authClient.buildAuthorizeUrl({
+			redirectUri,
+			state,
+			challenge,
+			organizationCode: options.organizationCode
+		});
+		if (mode === "redirect") {
+			bridge.redirect(url);
+			return;
+		}
+		if (!channel.supported) throw new Error("Popup sign-in requires BroadcastChannel; use mode: \"redirect\" instead.");
+		const popup = bridge.openPopup(url);
+		if (!popup) throw new Error("The sign-in popup was blocked. Use mode: \"redirect\" instead.");
+		await new Promise((resolve, reject) => {
+			let settled = false;
+			const finish = (fn) => {
+				if (settled) return;
+				settled = true;
+				unsubscribe();
+				clearInterval(poll);
+				fn();
+			};
+			const unsubscribe = channel.subscribe((message) => {
+				if (message.state !== state) return;
+				complete(message.code, message.state).then(() => finish(() => {
+					popup.close();
+					resolve();
+				}), (error) => finish(() => reject(error)));
+			});
+			const poll = setInterval(() => {
+				if (popup.closed) finish(() => reject(new PopupCancelledError()));
+			}, pollMs);
+		});
+	}
+	async function handleCallback() {
+		const { code, state } = bridge.readCallbackParams();
+		if (!code || !state) return;
+		if (bridge.isPopupContext()) {
+			channel.post({
+				type: "auth-callback",
+				code,
+				state
+			});
+			bridge.closeSelf();
+			return;
+		}
+		await complete(code, state);
+		const url = new URL(bridge.currentUrl());
+		url.searchParams.delete("code");
+		url.searchParams.delete("state");
+		bridge.replaceUrl(url.pathname + url.search + url.hash);
+	}
+	return {
+		signIn,
+		handleCallback
+	};
+}
+//#endregion
+//#region src/seams/broadcast-channel.ts
+/**
+* Cross-tab session channel over `BroadcastChannel` (ADR-0005). Delivers to
+* other tabs only (never echoes to the poster — the correct cross-tab
+* semantic). Falls back to core's in-memory channel where `BroadcastChannel`
+* is unavailable (SSR, older engines) so the provider never crashes.
+*/
+var BroadcastChannelSessionChannel = class {
+	channel;
+	fallback;
+	listeners = /* @__PURE__ */ new Set();
+	constructor(name = "poly-x.session") {
+		if (typeof BroadcastChannel !== "undefined") {
+			this.channel = new BroadcastChannel(name);
+			this.channel.onmessage = (event) => {
+				for (const listener of [...this.listeners]) listener(event.data);
+			};
+		} else this.fallback = new InMemorySessionChannel();
+	}
+	publish(event) {
+		if (this.channel) this.channel.postMessage(event);
+		else this.fallback?.publish(event);
+	}
+	subscribe(listener) {
+		if (this.fallback) return this.fallback.subscribe(listener);
+		this.listeners.add(listener);
+		return () => this.listeners.delete(listener);
+	}
+};
+//#endregion
+//#region src/seams/session-storage-pkce.ts
+const KEY_PREFIX = "poly-x.pkce.";
+function hasSessionStorage() {
+	try {
+		return typeof sessionStorage !== "undefined";
+	} catch {
+		return false;
+	}
+}
+/**
+* PKCE-transaction custody in `sessionStorage` so the verifier + redirect
+* survive a full-page redirect to the PolyX login and back (ADR-0005). Falls
+* back to in-memory where `sessionStorage` is unavailable — the transaction
+* then only survives an in-page popup flow, which is the SPA default anyway.
+*/
+var SessionStoragePkceStore = class {
+	fallback;
+	constructor() {
+		if (!hasSessionStorage()) this.fallback = new InMemoryPkceStore();
+	}
+	save(entry) {
+		if (this.fallback) return this.fallback.save(entry);
+		sessionStorage.setItem(KEY_PREFIX + entry.state, JSON.stringify(entry));
+		return Promise.resolve();
+	}
+	take(state) {
+		if (this.fallback) return this.fallback.take(state);
+		const raw = sessionStorage.getItem(KEY_PREFIX + state);
+		if (raw === null) return Promise.resolve(null);
+		sessionStorage.removeItem(KEY_PREFIX + state);
+		try {
+			return Promise.resolve(JSON.parse(raw));
+		} catch {
+			return Promise.resolve(null);
+		}
+	}
+};
+//#endregion
+//#region src/seams/web-locks.ts
+function hasWebLocks() {
+	return typeof navigator !== "undefined" && typeof navigator.locks?.request === "function";
+}
+/**
+* Single-flight refresh coordination over the Web Locks API (ADR-0005), so a
+* refresh is serialized across tabs, not just within one. Falls back to core's
+* in-memory lock where `navigator.locks` is absent (Node/happy-dom, older
+* Safari) — serialization within the tab is preserved.
+*/
+var WebLocksLock = class {
+	fallback;
+	constructor() {
+		if (!hasWebLocks()) this.fallback = new InMemoryLock();
+	}
+	runExclusive(key, fn) {
+		if (this.fallback) return this.fallback.runExclusive(key, fn);
+		return navigator.locks.request(`poly-x.${key}`, () => fn());
+	}
+};
+//#endregion
+//#region src/provider.tsx
+function PolyXProvider({ publishableKey, baseUrl, children }) {
+	const value = useMemo(() => {
+		const authClient = new AuthClient({
+			config: resolveConfig({
+				key: publishableKey,
+				baseUrl,
+				context: "browser"
+			}),
+			transport: new FetchTransport()
+		});
+		const engine = createSessionEngine({
+			refreshTokens: authClient.createRefresher(),
+			store: new InMemorySessionStore(),
+			channel: new BroadcastChannelSessionChannel(),
+			lock: new WebLocksLock()
+		});
+		return {
+			engine,
+			authClient,
+			controller: createLoginController({
+				engine,
+				authClient,
+				pkceStore: new SessionStoragePkceStore(),
+				bridge: new WindowBrowserBridge(),
+				channel: new BroadcastAuthChannel()
+			})
+		};
+	}, [publishableKey, baseUrl]);
+	useEffect(() => {
+		value.engine.hydrate();
+		return () => value.engine.dispose();
+	}, [value]);
+	return /* @__PURE__ */ jsx(PolyXContext.Provider, {
+		value,
+		children
+	});
+}
+//#endregion
+//#region src/hooks.ts
+function usePolyX() {
+	const ctx = useContext(PolyXContext);
+	if (!ctx) throw new Error("PolyX hooks (useAuth/useUser/useSession) must be used within a <PolyXProvider>.");
+	return ctx;
+}
+/** 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);
+}
+function useAuth() {
+	const { engine, controller } = usePolyX();
+	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]);
+	return {
+		isLoaded: state.status !== "resolving",
+		isSignedIn: state.status === "authenticated" || state.status === "refreshing",
+		signIn,
+		signOut,
+		getToken
+	};
+}
+/** Run this on your callback route to complete a sign-in (see `<AuthCallback>`). */
+function useAuthCallback() {
+	const { controller } = usePolyX();
+	return useCallback(() => controller.handleCallback(), [controller]);
+}
+function useUser() {
+	const state = useSession();
+	return state.status === "authenticated" || state.status === "refreshing" ? state.session.claims : null;
+}
+//#endregion
+//#region src/components/protected.tsx
+/** Gate content on authentication state without flashing the wrong branch. */
+function Protected({ children, fallback = null, loading = null }) {
+	const { isLoaded, isSignedIn } = useAuth();
+	if (!isLoaded) return loading;
+	return isSignedIn ? children : fallback;
+}
+//#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"
+	});
+}
+//#endregion
+//#region src/components/auth-callback.tsx
+/** Drop on your `/auth/callback` route: completes the sign-in exchange on mount. */
+function AuthCallback({ children = null }) {
+	const handleCallback = useAuthCallback();
+	useEffect(() => {
+		handleCallback();
+	}, [handleCallback]);
+	return children;
+}
+//#endregion
+//#region src/index.ts
+/**
+* @poly-x/react — PolyX SDK for React SPAs. Sign-in UI + orchestration land in
+* F006; this entry is the state foundation (provider, hooks, browser seams).
+*/
+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 };

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@poly-x/react",
+  "version": "0.1.0-alpha.0",
+  "description": "PolyX SDK for React SPAs - provider, hooks, drop-in auth UI",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "dependencies": {
+    "@poly-x/core": "0.1.0-alpha.0"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://dev.azure.com/waiindustries/wAI%20Engineering/_git/poly-x-sdk"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.3",
+    "happy-dom": "^20.10.6",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "lint": "eslint src"
+  }
+}