@btst/stack 3.0.0-rc.2 → 3.0.0-rc.3

package/src/context/auth.tsx

@@ -4,23 +4,29 @@ import {
 	useCallback,
 	useContext,
 	useEffect,
+	useMemo,
 	useRef,
 	useState,
 	type ReactNode,
 } from "react";
-import type {
-	CanParams,
-	StackAuthProvider,
-	StackIdentity,
-} from "../shared/auth-types";
-
-interface AuthContextValue {
-	provider: StackAuthProvider;
+import type { StackClientAuth, StackIdentity } from "../shared/auth-types";
+import type { PermissionRequest } from "../authorization";
+
+type AnyPermissionRequest = PermissionRequest;
+
+export interface AuthContextValue {
+	provider: StackClientAuth;
 	identity: StackIdentity | null;
-	/** True until the initial `getIdentity()` call settles */
+	/** True while `getIdentity()` is resolving. */
 	isPending: boolean;
+	/** Serializable generation for the current identity resolution. */
+	sourceGeneration: number;
+	/** Identity resolution or validation failure. */
+	error?: Error;
 	/** Re-run `getIdentity()` (e.g. after login/logout) */
 	refetch: () => Promise<void>;
+	/** Promise used by suspense consumers to wait for the active resolution. */
+	waitForResolution: () => Promise<void>;
 }
 
 /**
@@ -29,46 +35,174 @@ interface AuthContextValue {
  * `<CanAccess>` renders its children — preserving pre-auth behavior exactly.
  */
 const AuthContext = createContext<AuthContextValue | null>(null);
+let nextAuthSourceGeneration = 0;
+
+function createInitialAuthState(
+	provider: StackClientAuth,
+	initialIdentity: StackIdentity | null | undefined,
+): {
+	identity: StackIdentity | null;
+	isPending: boolean;
+	error?: Error;
+} {
+	if (initialIdentity === undefined) {
+		return { identity: null, isPending: true };
+	}
+
+	try {
+		return {
+			identity: provider.contract.parseIdentity(initialIdentity),
+			isPending: false,
+		};
+	} catch (error) {
+		return {
+			identity: null,
+			isPending: false,
+			error: error instanceof Error ? error : new Error(String(error)),
+		};
+	}
+}
 
 /**
  * Internal boundary rendered by `StackProvider` when an `auth` provider is
- * configured. Resolves `getIdentity()` once on the client (effects don't run
- * during SSR, so server renders see `isPending: true`) and shares the result
- * with all `useIdentity()` / `useCan()` / `<CanAccess>` consumers.
+ * configured. A supplied identity snapshot is used for the first server and
+ * client render; otherwise `getIdentity()` resolves once in the browser. The
+ * result is shared with all identity and permission consumers.
  */
 export function StackAuthBoundary({
 	provider,
+	initialIdentity,
 	children,
 }: {
-	provider: StackAuthProvider;
+	provider: StackClientAuth;
+	initialIdentity?: StackIdentity | null;
 	children?: ReactNode;
 }) {
-	const [state, setState] = useState<{
+	type BoundaryState = {
 		identity: StackIdentity | null;
 		isPending: boolean;
-	}>({ identity: null, isPending: true });
-
-	const refetch = useCallback(async () => {
-		try {
-			const identity = await provider.getIdentity();
-			setState({ identity: identity ?? null, isPending: false });
-		} catch (error) {
-			console.error("[btst/auth] getIdentity() failed:", error);
-			setState({ identity: null, isPending: false });
-		}
-	}, [provider]);
+		error?: Error;
+		sourceGeneration: { readonly id: number };
+		resolutionGeneration: number;
+	};
+
+	const hydratedState = useMemo(
+		() => createInitialAuthState(provider, initialIdentity),
+		[provider, initialIdentity],
+	);
+	const sourceGeneration = useMemo(
+		() => ({ id: ++nextAuthSourceGeneration }),
+		[provider, initialIdentity],
+	);
+	const [state, setState] = useState<BoundaryState>(() => ({
+		...hydratedState,
+		sourceGeneration,
+		resolutionGeneration: sourceGeneration.id,
+	}));
+	const sourceChanged = state.sourceGeneration !== sourceGeneration;
+	const currentState = sourceChanged ? hydratedState : state;
+	const currentResolutionGeneration = sourceChanged
+		? sourceGeneration.id
+		: state.resolutionGeneration;
+	const latestResolutionGeneration = useRef(0);
+	const activeSourceGeneration = useRef<object | null>(sourceGeneration);
+	const resolutionWaiters = useRef(new Set<() => void>());
+	const settleResolutionWaiters = useCallback(() => {
+		for (const resolve of resolutionWaiters.current) resolve();
+		resolutionWaiters.current.clear();
+	}, []);
+	const waitForResolution = useCallback(
+		() =>
+			currentState.isPending
+				? new Promise<void>((resolve) => {
+						resolutionWaiters.current.add(resolve);
+					})
+				: Promise.resolve(),
+		[currentState.isPending],
+	);
+
+	useEffect(() => {
+		if (!currentState.isPending) settleResolutionWaiters();
+	}, [currentState.isPending, settleResolutionWaiters]);
+	useEffect(() => settleResolutionWaiters, [settleResolutionWaiters]);
+
+	useEffect(() => {
+		activeSourceGeneration.current = sourceGeneration;
+		return () => {
+			if (activeSourceGeneration.current === sourceGeneration) {
+				activeSourceGeneration.current = null;
+			}
+		};
+	}, [sourceGeneration]);
 
 	useEffect(() => {
-		void refetch();
-	}, [refetch]);
+		if (!sourceChanged) return;
+		setState({
+			...hydratedState,
+			sourceGeneration,
+			resolutionGeneration: sourceGeneration.id,
+		});
+	}, [hydratedState, sourceChanged, sourceGeneration]);
+
+	const resolveIdentity = useCallback(
+		async (markPending: boolean) => {
+			if (activeSourceGeneration.current !== sourceGeneration) return;
+			const resolutionGeneration = ++latestResolutionGeneration.current;
+			const cacheGeneration = markPending
+				? ++nextAuthSourceGeneration
+				: sourceGeneration.id;
+			if (markPending) {
+				setState({
+					identity: null,
+					isPending: true,
+					sourceGeneration,
+					resolutionGeneration: cacheGeneration,
+				});
+			}
+			const isLatestResolution = () =>
+				latestResolutionGeneration.current === resolutionGeneration &&
+				activeSourceGeneration.current === sourceGeneration;
+			try {
+				const identity = await provider.getIdentity();
+				if (!isLatestResolution()) return;
+				setState({
+					identity: identity ?? null,
+					isPending: false,
+					sourceGeneration,
+					resolutionGeneration: cacheGeneration,
+				});
+			} catch (error) {
+				if (!isLatestResolution()) return;
+				const identityError =
+					error instanceof Error ? error : new Error(String(error));
+				setState({
+					identity: null,
+					isPending: false,
+					error: identityError,
+					sourceGeneration,
+					resolutionGeneration: cacheGeneration,
+				});
+			}
+		},
+		[provider, sourceGeneration],
+	);
+	const refetch = useCallback(() => resolveIdentity(true), [resolveIdentity]);
+
+	useEffect(() => {
+		if (initialIdentity !== undefined) return;
+		void resolveIdentity(false);
+	}, [initialIdentity, resolveIdentity]);
 
 	return (
 		<AuthContext.Provider
 			value={{
 				provider,
-				identity: state.identity,
-				isPending: state.isPending,
+				identity: currentState.identity,
+				isPending: currentState.isPending,
+				sourceGeneration: currentResolutionGeneration,
+				...(currentState.error ? { error: currentState.error } : {}),
 				refetch,
+				waitForResolution,
 			}}
 		>
 			{children}
@@ -96,6 +230,7 @@ export function useAuthContext(): AuthContextValue | null {
 export function useIdentity(): {
 	identity: StackIdentity | null;
 	isPending: boolean;
+	error?: Error;
 	refetch: () => Promise<void>;
 } {
 	const auth = useContext(AuthContext);
@@ -107,149 +242,65 @@ export function useIdentity(): {
 	return {
 		identity: auth.identity,
 		isPending: auth.isPending,
+		...(auth.error ? { error: auth.error } : {}),
 		refetch: auth.refetch,
 	};
 }
 
+/** @internal Serializable identity-resolution key for protected query caches. */
+export function useIdentitySourceGeneration(): number {
+	return useContext(AuthContext)?.sourceGeneration ?? 0;
+}
+
+/** @internal Promise that settles when the current identity lookup finishes. */
+export function useIdentityResolutionPromise(): Promise<void> | undefined {
+	const auth = useContext(AuthContext);
+	return auth?.isPending ? auth.waitForResolution() : undefined;
+}
+
 type CanState = { can: boolean; isPending: boolean };
 
-/**
- * A resolved `can()` result together with the inputs it was computed for.
- * `useCan` only trusts it while those inputs are still current, so a change
- * in identity (login/logout/user switch) or check parameters immediately
- * reads as pending instead of momentarily returning the previous user's
- * permission.
- */
-type ResolvedCan = {
-	can: boolean;
-	forIdentity: StackIdentity | null;
-	forKey: string;
-};
+/** State yielded by a plugin-owned permission descriptor gate. */
+export type PermissionCheckState = CanState & { error?: Error };
 
 /**
- * Checks whether the current user can perform `action` on `resource` using
- * the auth provider's `can()` function.
- *
- * Resolves to `{ can: true, isPending: false }` immediately when no auth
- * provider is configured or the provider has no `can()` function — permission
- * checks are opt-in and non-breaking.
- *
- * While the identity or the `can()` result is still resolving, returns
- * `{ can: false, isPending: true }` so callers can avoid flashing
- * permission-gated UI.
- *
- * @example
- * ```tsx
- * const { can, isPending } = useCan({ resource: "blog:post", action: "delete" });
- * if (!isPending && can) return <DeletePostButton />;
- * ```
+ * Evaluate a plugin-owned descriptor through the configured client auth.
+ * Omitting browser authorization remains presentation-only permissive; the
+ * backend is always the security boundary.
  */
-export function useCan(params: CanParams): CanState {
+export function PermissionCheck({
+	permission,
+	children,
+}: {
+	permission: AnyPermissionRequest;
+	children: (state: PermissionCheckState) => ReactNode;
+}) {
 	const auth = useContext(AuthContext);
-	const canFn = auth?.provider.can;
-	const identity = auth?.identity ?? null;
-	const identityPending = auth?.isPending ?? false;
-
-	const { resource, action, params: extraParams } = params;
-	// Serialized only for change detection: plain-object literals must not
-	// retrigger the effect on every render. The original object (via ref) is
-	// what gets passed to can(), so non-JSON-safe values survive intact.
-	const extraParamsKey = extraParams ? JSON.stringify(extraParams) : "";
-	const extraParamsRef = useRef(extraParams);
-	extraParamsRef.current = extraParams;
-
-	const checkKey = `${resource}\u0000${action}\u0000${extraParamsKey}`;
-
-	const [resolved, setResolved] = useState<ResolvedCan | null>(null);
-
-	useEffect(() => {
-		if (!canFn || identityPending) return;
-
-		let cancelled = false;
-
-		void (async () => {
-			try {
-				const currentParams = extraParamsRef.current;
-				const allowed = await canFn({
-					resource,
-					action,
-					...(currentParams ? { params: currentParams } : {}),
-					identity,
-				});
-				if (!cancelled) {
-					setResolved({
-						can: allowed,
-						forIdentity: identity,
-						forKey: checkKey,
-					});
-				}
-			} catch (error) {
-				console.error("[btst/auth] can() failed:", error);
-				if (!cancelled) {
-					setResolved({ can: false, forIdentity: identity, forKey: checkKey });
-				}
-			}
-		})();
-
-		return () => {
-			cancelled = true;
-		};
-	}, [canFn, identity, identityPending, resource, action, checkKey]);
-
-	// No provider or no can() function: always allowed, never pending.
-	if (!auth || !canFn) {
-		return { can: true, isPending: false };
-	}
-
-	if (identityPending) {
-		return { can: false, isPending: true };
-	}
-
-	// Only trust a result computed for the current identity and inputs;
-	// anything else (including right after an identity change) is pending.
-	if (
-		!resolved ||
-		resolved.forIdentity !== identity ||
-		resolved.forKey !== checkKey
-	) {
-		return { can: false, isPending: true };
+	if (!auth) {
+		return <>{children({ can: true, isPending: false })}</>;
 	}
-
-	return { can: resolved.can, isPending: false };
+	return <>{children(auth.provider.usePermission(permission))}</>;
 }
 
-/**
- * Element-level permission gate (Refine's `<CanAccess>` pattern).
- *
- * - Without an auth provider configured, always renders `children`.
- * - While the check is pending, renders `loading` (default `null`) to avoid
- *   flashing gated UI.
- * - Renders `children` when `can()` allows, `fallback` (default `null`)
- *   otherwise.
- *
- * @example
- * ```tsx
- * <CanAccess resource="blog:post" action="delete" fallback={null}>
- *   <DeletePostButton />
- * </CanAccess>
- * ```
- */
-export function CanAccess({
-	resource,
-	action,
-	params,
+/** Element-level gate for a plugin-owned, schema-backed descriptor. */
+export function PermissionAccess({
+	permission,
 	fallback = null,
 	loading = null,
 	children,
-}: CanParams & {
-	/** Rendered when access is denied (default `null`) */
+}: {
+	permission: AnyPermissionRequest;
 	fallback?: ReactNode;
-	/** Rendered while the permission check is pending (default `null`) */
 	loading?: ReactNode;
 	children?: ReactNode;
 }) {
-	const { can, isPending } = useCan({ resource, action, params });
-
-	if (isPending) return <>{loading}</>;
-	return <>{can ? children : fallback}</>;
+	return (
+		<PermissionCheck permission={permission}>
+			{({ can, isPending, error }) => {
+				if (error) throw error;
+				if (isPending) return loading;
+				return can ? children : fallback;
+			}}
+		</PermissionCheck>
+	);
 }

package/src/context/index.ts

@@ -1,13 +1,19 @@
 export * from "./provider";
 export * from "./router";
-export { CanAccess, useCan, useIdentity } from "./auth";
+export { usePluginSiteNavigation } from "./site-navigation";
+export {
+	PermissionAccess,
+	PermissionCheck,
+	useIdentity,
+	useIdentityResolutionPromise,
+	useIdentitySourceGeneration,
+} from "./auth";
+export type { PermissionCheckState } from "./auth";
 export { useNotify, defaultNotifyProvider } from "./notify";
 export { useTranslate, type TranslateFn } from "./i18n";
 export type {
-	CanParams,
-	StackAuthProvider,
+	StackClientAuth,
 	StackIdentity,
-	StackServerAuthProvider,
 } from "../shared/auth-types";
 export type {
 	StackNotifyProvider,

package/src/context/provider.tsx

@@ -1,6 +1,21 @@
 "use client";
-import { createContext, useContext, type ReactNode } from "react";
-import type { StackAuthProvider } from "../shared/auth-types";
+import {
+	createContext,
+	useContext,
+	type ReactElement,
+	type ReactNode,
+} from "react";
+import type { QueryClient } from "@tanstack/react-query";
+import type {
+	ClientLocation,
+	ClientStackContext,
+	ClientProviderPluginRuntime,
+	InferredPluginOverrides,
+	RegisteredClientPlugins,
+	ResolvedClientStack,
+} from "../types";
+import type { StackClientAuth, StackIdentity } from "../shared/auth-types";
+import type { StackClientLike } from "../shared/entry-factories";
 import type { StackI18nProvider } from "../shared/i18n-types";
 import type { StackNotifyProvider } from "../shared/notify-types";
 import { StackAuthBoundary } from "./auth";
@@ -30,20 +45,59 @@ interface StackContextValue<TPluginOverrides extends Record<string, any>> {
 	 * Top-level API config applied to all plugins.
 	 */
 	api?: StackApiConfig;
+	/** Resolved top-level site location used to compare plugin site origins. */
+	site?: ClientLocation;
+	/** Effective browser-safe runtime for each registered client plugin. */
+	plugins?: Record<string, ClientProviderPluginRuntime>;
+	/** The query client owned by the resolved client stack. */
+	queryClient?: QueryClient;
+	/** Resolved plugin definitions used by client-only introspection helpers. */
+	clientStackContext?: ClientStackContext;
+	/** Canonical resolved stack supplied to this provider. */
+	resolvedStack?: StackClientLike;
 	/** Top-level auth provider used by identity-aware components. */
-	auth?: StackAuthProvider;
+	auth?: StackClientAuth;
 }
 
 const StackContext = createContext<StackContextValue<any> | null>(null);
 
-/**
- * The `overrides` prop shape for `StackProvider`.
- * Plugin blocks are optional; fields inside each block retain the plugin's
- * declared requirements.
- */
-export type StackProviderOverrides<
-	TPluginOverrides extends Record<string, any>,
-> = Partial<TPluginOverrides>;
+type StackProviderServices = {
+	children?: ReactNode;
+	router?: StackRouterConfig;
+	/**
+	 * Browser authorization created by `createClientAuth()`. When omitted,
+	 * identity is `null` and presentation-only descriptor checks remain
+	 * permissive; backend authorization is independent and authoritative.
+	 */
+	auth?: StackClientAuth;
+	/**
+	 * Request identity resolved on the server. `undefined` means no snapshot was
+	 * supplied; `null` is an explicitly hydrated anonymous identity.
+	 */
+	initialIdentity?: StackIdentity | null;
+	notify?: StackNotifyProvider;
+	i18n?: StackI18nProvider;
+};
+
+type CanonicalStackProviderOverrideProps<
+	TStack extends ResolvedClientStack<any, any>,
+> = InferredPluginOverrides<
+	NoInfer<RegisteredClientPlugins<TStack>>
+> extends infer TOverrides extends Record<string, any>
+	? {} extends TOverrides
+		? { overrides?: TOverrides }
+		: { overrides: TOverrides }
+	: never;
+
+type CanonicalStackProviderProps<TStack extends ResolvedClientStack<any, any>> =
+	StackProviderServices & {
+		/** Resolved browser client stack; supplies API/site/plugin runtime once. */
+		stack: TStack;
+		/** API configuration belongs to createClientStack(). */
+		api?: never;
+		/** Site paths belong to createClientStack(). */
+		basePath?: never;
+	} & CanonicalStackProviderOverrideProps<TStack>;
 
 /** Removes keys whose value is `undefined` so they don't clobber lower layers in spreads. */
 function stripUndefined<T extends Record<string, any>>(obj: T): Partial<T> {
@@ -97,18 +151,20 @@ function RouterBridge({
  * Provider component for BTST context
  * Provides type-safe access to plugin-specific overrides
  *
- * Only requires override values, not plugin objects - keeps bundle size minimal!
- *
  * @example
  * ```tsx
- * // Define the type shape (no import of plugin values needed!)
- * type MyPluginOverrides = {
- *   messages: MessagesPluginOverrides;
- * };
+ * const clientStack = createClientStack({
+ *   api,
+ *   site,
+ *   queryClient,
+ *   plugins: {
+ *     messages: messagesClientPlugin(),
+ *   },
+ * });
  *
- * <StackProvider<MyPluginOverrides>
+ * <StackProvider
+ *   stack={clientStack}
  *   router={frameworkRouter}
- *   api={{ baseURL, basePath: "/api/data" }}
  *   overrides={{
  *     messages: {
  *       MarkdownRenderer: (props) => <ReactMarkdown {...props} />,
@@ -119,70 +175,53 @@ function RouterBridge({
  * </StackProvider>
  * ```
  *
- * Framework router and API wiring live at the top level. Per-plugin overrides
- * carry only genuinely plugin-specific values:
+ * Runtime locations and plugin override types come from the resolved stack.
+ * Framework services and optional identity hydration remain provider concerns.
  *
  * @example
  * ```tsx
  * import { nextRouter } from "@btst/stack/next";
  *
- * <StackProvider<MyPluginOverrides>
- *   basePath="/pages"
+ * <StackProvider
+ *   stack={clientStack}
  *   router={nextRouter()}
- *   api={{ baseURL, basePath: "/api/data" }}
- *   overrides={{
- *     blog: { uploadImage },
- *   }}
+ *   auth={clientAuth}
+ *   initialIdentity={initialIdentity}
  * >
  *   {children}
  * </StackProvider>
  * ```
  */
 export function StackProvider<
-	TPluginOverrides extends Record<string, any> = Record<string, any>,
+	const TStack extends ResolvedClientStack<any, any>,
 >({
 	children,
 	overrides,
-	basePath,
+	stack,
 	router,
-	api,
 	auth,
+	initialIdentity,
 	notify,
 	i18n,
-}: {
-	children?: ReactNode;
-	overrides?: StackProviderOverrides<TPluginOverrides>;
-	basePath: string;
-	router?: StackRouterConfig;
-	api?: StackApiConfig;
-	/**
-	 * Optional auth provider. When set, `useIdentity()` / `useCan()` and
-	 * `<CanAccess>` resolve identity and permissions through it. When omitted,
-	 * behavior is identical to before: identity is `null` and all permission
-	 * checks pass.
-	 */
-	auth?: StackAuthProvider;
-	/**
-	 * Optional notification provider. When omitted, sonner toasts are used via
-	 * `useNotify()`.
-	 */
-	notify?: StackNotifyProvider;
-	/**
-	 * Optional i18n provider. When omitted, `useTranslate()` returns English
-	 * defaults with `{{param}}` interpolation.
-	 */
-	i18n?: StackI18nProvider;
-}) {
+}: CanonicalStackProviderProps<TStack>): ReactElement {
+	const projection = stack.provider;
 	const staticRouter = resolveStaticRouter(router);
 	const value: Omit<StackContextValue<any>, "router"> = {
 		overrides: overrides ?? {},
-		basePath,
-		api,
+		basePath: projection.site.basePath,
+		api: projection.api,
+		site: projection.site,
+		plugins: projection.plugins,
+		queryClient: projection.queryClient,
+		clientStackContext: stack.context,
+		resolvedStack: stack,
 		auth,
 	};
 
 	const content = auth ? (
-		<StackAuthBoundary provider={auth}>{children}</StackAuthBoundary>
+		<StackAuthBoundary provider={auth} initialIdentity={initialIdentity}>
+			{children}
+		</StackAuthBoundary>
 	) : (
 		children
 	);

package/src/context/router.tsx

@@ -1,5 +1,12 @@
 import type { ComponentType } from "react";
 
+/** Join a resolved site base path to an application route without `//`. */
+export function joinBasePath(basePath: string, path: string): string {
+	const normalizedBasePath = basePath.replace(/\/+$/, "");
+	const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+	return `${normalizedBasePath}${normalizedPath}`;
+}
+
 /**
  * Framework routing primitives shared by all plugins.
  *