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

package/src/plugins/ui-builder/client/plugin.tsx

@@ -4,11 +4,13 @@ import {
 	defineClientPlugin,
 	createApiClient,
 	isConnectionError,
+	type ResolvedClientPluginRuntime,
 } from "@btst/stack/plugins/client";
 import { defineRoute, defineRoutes } from "@btst/yar";
 import type { ComponentType } from "react";
 import type { QueryClient } from "@tanstack/react-query";
 import type { CMSApiRouter } from "../../cms/api";
+import { CMS_PLUGIN_ID } from "../../cms/client/constants";
 import { createSanitizedSSRLoaderError } from "../../utils";
 import { createUIBuilderQueryKeys } from "../query-keys";
 import type {
@@ -16,6 +18,11 @@ import type {
 	LoaderContext,
 	ComponentRegistry,
 } from "../types";
+import { UI_BUILDER_PLUGIN_ID } from "./constants";
+import type {
+	UIBuilderPluginOverrides,
+	UIBuilderProviderConfig,
+} from "./overrides";
 
 // Lazy load page components for code splitting
 const PageListPageComponent = lazy(() =>
@@ -30,25 +37,14 @@ const PageBuilderPageComponent = lazy(() =>
 );
 
 /**
- * Configuration for UI Builder client plugin
+ * UI Builder-specific client configuration. Shared API, site, query-client,
+ * and request-header values are inherited from `createClientStack()`.
  */
 export interface UIBuilderClientConfig {
-	/** Base URL for API calls (e.g., "http://localhost:3000") */
-	apiBaseURL: string;
-	/** Path where the API is mounted (e.g., "/api/data") */
-	apiBasePath: string;
-	/** Base URL of your site */
-	siteBaseURL: string;
-	/** Path where pages are mounted (e.g., "/pages") */
-	siteBasePath: string;
-	/** React Query client instance for caching */
-	queryClient: QueryClient;
-	/** Optional headers for SSR (e.g., forwarding cookies) */
-	headers?: Headers;
-	/** Optional hooks for customizing behavior (authorization, redirects, etc.) */
+	/** Component definitions used by the editor and registered page renderers. */
+	components?: ComponentRegistry;
+	/** Optional hooks for route loading, error reporting, and telemetry. */
 	hooks?: UIBuilderClientHooks;
-	/** Component registry to use for the UI Builder */
-	componentRegistry?: ComponentRegistry;
 
 	/**
 	 * Optional page component overrides.
@@ -65,10 +61,68 @@ export interface UIBuilderClientConfig {
 	};
 }
 
+interface ResolvedUIBuilderClientConfig
+	extends Omit<UIBuilderClientConfig, "components"> {
+	apiBaseURL: string;
+	apiBasePath: string;
+	siteBaseURL: string;
+	siteBasePath: string;
+	queryClient: QueryClient;
+	headers?: Headers;
+	credentials?: RequestCredentials;
+}
+
+function resolveUIBuilderClientConfig(
+	config: UIBuilderClientConfig,
+	runtime: ResolvedClientPluginRuntime<typeof UI_BUILDER_PLUGIN_ID>,
+): ResolvedUIBuilderClientConfig {
+	return {
+		hooks: config.hooks,
+		pageComponents: config.pageComponents,
+		apiBaseURL: runtime.api.baseURL,
+		apiBasePath: runtime.api.basePath,
+		siteBaseURL: runtime.site.baseURL,
+		siteBasePath: runtime.site.basePath,
+		queryClient: runtime.queryClient,
+		...(runtime.api.headers ? { headers: runtime.api.headers } : {}),
+		...(runtime.api.credentials
+			? { credentials: runtime.api.credentials }
+			: {}),
+	};
+}
+
+function createUIBuilderApiClient(config: ResolvedUIBuilderClientConfig) {
+	return createApiClient<CMSApiRouter>({
+		baseURL: config.apiBaseURL,
+		basePath: config.apiBasePath,
+		headers: config.headers,
+		credentials: config.credentials,
+	});
+}
+
+function createLoadErrorReporter(
+	hooks: UIBuilderClientHooks | undefined,
+	context: LoaderContext,
+) {
+	let reported = false;
+	return async (error: unknown) => {
+		if (reported || !hooks?.onErrorLoad) return;
+		reported = true;
+		try {
+			await hooks.onErrorLoad(
+				error instanceof Error ? error : new Error(String(error)),
+				context,
+			);
+		} catch {
+			// Loader hooks cannot make an SSR loader throw or run twice.
+		}
+	};
+}
+
 /**
  * Create page list loader for SSR
  */
-function createPageListLoader(config: UIBuilderClientConfig) {
+function createPageListLoader(config: ResolvedUIBuilderClientConfig) {
 	return async () => {
 		if (typeof window === "undefined") {
 			const { queryClient, apiBasePath, apiBaseURL, headers, hooks } = config;
@@ -79,15 +133,14 @@ function createPageListLoader(config: UIBuilderClientConfig) {
 				apiBasePath,
 				headers,
 			};
-			const client = createApiClient<CMSApiRouter>({
-				baseURL: apiBaseURL,
-				basePath: apiBasePath,
-			});
-			const queries = createUIBuilderQueryKeys(client, headers);
+			const reportError = createLoadErrorReporter(hooks, context);
+			const queries = createUIBuilderQueryKeys(
+				createUIBuilderApiClient(config),
+			);
 			const listQuery = queries.cmsContent.list({ limit: 10, offset: 0 });
 
 			try {
-				// Before hook - authorization check
+				// Before-load lifecycle hook
 				if (hooks?.beforeLoadPageList) {
 					await hooks.beforeLoadPageList(context);
 				}
@@ -105,19 +158,19 @@ function createPageListLoader(config: UIBuilderClientConfig) {
 
 				// Check if there was an error
 				const queryState = queryClient.getQueryState(listQuery.queryKey);
-				if (queryState?.error && hooks?.onLoadError) {
+				if (queryState?.error) {
 					const error =
 						queryState.error instanceof Error
 							? queryState.error
 							: new Error(String(queryState.error));
-					await hooks.onLoadError(error, context);
+					await reportError(error);
 				}
 			} catch (error) {
 				// Error hook - log the error but don't throw during SSR
 				if (isConnectionError(error)) {
 					console.warn(
 						"[btst/ui-builder] route.loader() failed — no server running at build time. " +
-							"Use myStack.api.cms.prefetchForRoute() for SSG data prefetching.",
+							"Use myStack.raw.cms.prefetchForRoute() for SSG data prefetching.",
 					);
 				} else {
 					const errToStore = createSanitizedSSRLoaderError();
@@ -130,9 +183,7 @@ function createPageListLoader(config: UIBuilderClientConfig) {
 						retry: false,
 					});
 				}
-				if (hooks?.onLoadError) {
-					await hooks.onLoadError(error as Error, context);
-				}
+				await reportError(error);
 			}
 		}
 	};
@@ -143,7 +194,7 @@ function createPageListLoader(config: UIBuilderClientConfig) {
  */
 function createPageBuilderLoader(
 	id: string | undefined,
-	config: UIBuilderClientConfig,
+	config: ResolvedUIBuilderClientConfig,
 ) {
 	return async () => {
 		if (typeof window === "undefined") {
@@ -156,15 +207,14 @@ function createPageBuilderLoader(
 				apiBasePath,
 				headers,
 			};
-			const client = createApiClient<CMSApiRouter>({
-				baseURL: apiBaseURL,
-				basePath: apiBasePath,
-			});
-			const queries = createUIBuilderQueryKeys(client, headers);
+			const reportError = createLoadErrorReporter(hooks, context);
+			const queries = createUIBuilderQueryKeys(
+				createUIBuilderApiClient(config),
+			);
 			const pageQuery = id ? queries.cmsContent.detail(id) : undefined;
 
 			try {
-				// Before hook - authorization check
+				// Before-load lifecycle hook
 				if (hooks?.beforeLoadPageBuilder) {
 					await hooks.beforeLoadPageBuilder(id, context);
 				}
@@ -182,12 +232,12 @@ function createPageBuilderLoader(
 				// Check if there was an error
 				if (id) {
 					const queryState = queryClient.getQueryState(pageQuery!.queryKey);
-					if (queryState?.error && hooks?.onLoadError) {
+					if (queryState?.error) {
 						const error =
 							queryState.error instanceof Error
 								? queryState.error
 								: new Error(String(queryState.error));
-						await hooks.onLoadError(error, context);
+						await reportError(error);
 					}
 				}
 			} catch (error) {
@@ -195,7 +245,7 @@ function createPageBuilderLoader(
 				if (isConnectionError(error)) {
 					console.warn(
 						"[btst/ui-builder] route.loader() failed — no server running at build time. " +
-							"Use myStack.api.cms.prefetchForRoute() for SSG data prefetching.",
+							"Use myStack.raw.cms.prefetchForRoute() for SSG data prefetching.",
 					);
 				} else if (pageQuery) {
 					const errToStore = createSanitizedSSRLoaderError();
@@ -207,9 +257,7 @@ function createPageBuilderLoader(
 						retry: false,
 					});
 				}
-				if (hooks?.onLoadError) {
-					await hooks.onLoadError(error as Error, context);
-				}
+				await reportError(error);
 			}
 		}
 	};
@@ -234,17 +282,15 @@ function createPageListMeta() {
  */
 function createPageBuilderMeta(
 	id: string | undefined,
-	config: UIBuilderClientConfig,
+	config: ResolvedUIBuilderClientConfig,
 ) {
 	return () => {
-		const { queryClient, apiBasePath, apiBaseURL, headers } = config;
+		const { queryClient } = config;
 		let pageSlug = "";
 		if (id) {
-			const client = createApiClient<CMSApiRouter>({
-				baseURL: apiBaseURL,
-				basePath: apiBasePath,
-			});
-			const queries = createUIBuilderQueryKeys(client, headers);
+			const queries = createUIBuilderQueryKeys(
+				createUIBuilderApiClient(config),
+			);
 			const page = queryClient.getQueryData(
 				queries.cmsContent.detail(id).queryKey,
 			) as { slug: string } | undefined;
@@ -269,30 +315,23 @@ function createPageBuilderMeta(
  * ```typescript
  * import { uiBuilderClientPlugin } from "@btst/stack/plugins/ui-builder/client"
  *
- * "ui-builder": uiBuilderClientPlugin({
- *   apiBaseURL: baseURL,
- *   apiBasePath: "/api/data",
- *   siteBaseURL: baseURL,
- *   siteBasePath: "/pages",
- *   queryClient,
+ * uiBuilder: uiBuilderClientPlugin({
  *   hooks: {
- *     beforeLoadPageList: async (ctx) => {
- *       const session = await getSession(ctx.headers)
- *       if (!session?.user?.isAdmin) throw new Error("Admin access required")
+ *     beforeLoadPageList: async (context) => {
+ *       await warmPageListDependencies(context.headers)
  *     },
- *     beforeLoadPageBuilder: async (pageId, ctx) => {
- *       const session = await getSession(ctx.headers)
- *       if (!session?.user?.isAdmin) throw new Error("Admin access required")
+ *     beforeLoadPageBuilder: async (pageId, context) => {
+ *       await recordPageBuilderLoad(pageId, context.headers)
+ *     },
+ *     onErrorLoad: (error, context) => {
+ *       reportPageLoaderError(error, context)
  *     },
- *     onLoadError: () => redirect("/auth/sign-in"),
  *   },
  * })
  * ```
  */
-export const uiBuilderClientPlugin = (config: UIBuilderClientConfig) =>
-	defineClientPlugin({
-		name: "ui-builder",
-
+function createResolvedUIBuilderPlugin(config: ResolvedUIBuilderClientConfig) {
+	return {
 		routes: () =>
 			defineRoutes(
 				{
@@ -322,4 +361,18 @@ export const uiBuilderClientPlugin = (config: UIBuilderClientConfig) =>
 			// UI Builder admin pages should NOT be in sitemap
 			return [];
 		},
+	};
+}
+
+export const uiBuilderClientPlugin = (config: UIBuilderClientConfig = {}) =>
+	defineClientPlugin<UIBuilderPluginOverrides>()({
+		id: UI_BUILDER_PLUGIN_ID,
+		apiRuntimeFrom: CMS_PLUGIN_ID,
+		providerConfig: {
+			...(config.components ? { components: config.components } : {}),
+		} satisfies UIBuilderProviderConfig,
+		resolve: (runtime) =>
+			createResolvedUIBuilderPlugin(
+				resolveUIBuilderClientConfig(config, runtime),
+			),
 	});

package/src/plugins/ui-builder/client/registry.ts

@@ -829,11 +829,9 @@ export const complexComponentDefinitions: ComponentRegistry = {
  * ```typescript
  * import { defaultComponentRegistry } from "@btst/stack/plugins/ui-builder/client"
  *
- * // Use as-is
- * uiBuilderClientPlugin({
- *   componentRegistry: defaultComponentRegistry,
- *   // ...
- * })
+ * // The built-in editor uses this registry by default. Register a customized
+ * // registry once when creating the UI Builder client plugin.
+ * uiBuilderClientPlugin({ components: defaultComponentRegistry })
  *
  * // Or extend with custom components
  * import { createComponentRegistry } from "@btst/stack/plugins/ui-builder/client"

package/src/plugins/ui-builder/types.ts

@@ -92,7 +92,8 @@ export interface LoaderContext {
  */
 export interface UIBuilderClientHooks {
 	/**
-	 * Called before loading the page list. Throw an error to cancel loading.
+	 * Called before loading the page list. If it throws, remaining loader work
+	 * stops, `onErrorLoad` is notified, and the loader still resolves.
 	 * @param context - Loader context with path, params, etc.
 	 */
 	beforeLoadPageList?: (context: LoaderContext) => Promise<void> | void;
@@ -102,7 +103,8 @@ export interface UIBuilderClientHooks {
 	 */
 	afterLoadPageList?: (context: LoaderContext) => Promise<void> | void;
 	/**
-	 * Called before loading the page builder. Throw an error to cancel loading.
+	 * Called before loading the page builder. If it throws, remaining loader work
+	 * stops, `onErrorLoad` is notified, and the loader still resolves.
 	 * @param pageId - The page ID (undefined for new pages)
 	 * @param context - Loader context
 	 */
@@ -121,11 +123,12 @@ export interface UIBuilderClientHooks {
 	) => Promise<void> | void;
 	/**
 	 * Called when a loading error occurs.
-	 * Use this for redirects on authorization failures.
+	 * This is a reporting-only observer. Callback errors are contained and the
+	 * loader never rejects, so throwing framework redirects are not supported.
 	 * @param error - The error that occurred
 	 * @param context - Loader context
 	 */
-	onLoadError?: (error: Error, context: LoaderContext) => Promise<void> | void;
+	onErrorLoad?: (error: Error, context: LoaderContext) => Promise<void> | void;
 }
 
 // Re-export types from ui-builder for convenience

package/src/plugins/utils.ts

@@ -60,6 +60,8 @@ import type { Router, Endpoint, Status, statusCodes } from "better-call";
 interface CreateApiClientOptions {
 	baseURL?: string;
 	basePath?: string;
+	headers?: HeadersInit;
+	credentials?: RequestCredentials;
 }
 
 /**
@@ -72,7 +74,7 @@ interface CreateApiClientOptions {
 export function createApiClient<
 	TRouter extends Router | Record<string, Endpoint> = Record<string, Endpoint>,
 >(options?: CreateApiClientOptions): ReturnType<typeof createClient<TRouter>> {
-	const { baseURL = "", basePath = "/" } = options ?? {};
+	const { baseURL = "", basePath = "/", headers, credentials } = options ?? {};
 
 	// Normalize baseURL - remove trailing slash if present
 	const normalizedBaseURL = baseURL ? baseURL.replace(/\/$/, "") : "";
@@ -87,5 +89,7 @@ export function createApiClient<
 
 	return createClient<TRouter>({
 		baseURL: apiPath,
+		...(headers !== undefined ? { headers } : {}),
+		...(credentials !== undefined ? { credentials } : {}),
 	});
 }

package/src/react-router/index.tsx

@@ -1,4 +1,9 @@
 export { toReactRouterHandlers } from "./handlers";
+export {
+	type CreateReactRouterLayoutOptions,
+	type ReactRouterLayoutLoaderArgs,
+	createReactRouterLayout,
+} from "./layout";
 export {
 	type CreateReactRouterPageOptions,
 	type ReactRouterPageLoaderArgs,

package/src/react-router/layout.ts

@@ -0,0 +1,43 @@
+import type {
+	AuthorizationContractIdentity,
+	AnyAuthorizationContract,
+} from "../authorization";
+import {
+	type FrameworkIdentitySource,
+	resolveInitialIdentity,
+} from "../shared/initial-identity";
+
+/** Request values supplied to a React Router parent layout loader. */
+export interface ReactRouterLayoutLoaderArgs<TContext = unknown> {
+	request: Request;
+	params: Record<string, string | undefined>;
+	context: TContext;
+}
+
+/** Options for the request-aware React Router identity layout factory. */
+export interface CreateReactRouterLayoutOptions<
+	TContract extends AnyAuthorizationContract,
+> {
+	/** Server-only identity adapter, normally returned by `createServerAuth`. */
+	auth: FrameworkIdentitySource<TContract, Request>;
+}
+
+/**
+ * Creates the loader for a React Router parent layout. Its result is passed to
+ * `StackProvider.initialIdentity` by the layout component around `<Outlet />`.
+ */
+export function createReactRouterLayout<
+	TContract extends AnyAuthorizationContract,
+>(options: CreateReactRouterLayoutOptions<TContract>) {
+	async function loader<TContext = unknown>(
+		args: ReactRouterLayoutLoaderArgs<TContext>,
+	) {
+		return {
+			initialIdentity: await resolveInitialIdentity(options.auth, args.request),
+		} satisfies {
+			initialIdentity: AuthorizationContractIdentity<TContract> | null;
+		};
+	}
+
+	return { loader };
+}

package/src/react-router/page.tsx

@@ -8,6 +8,7 @@ import type { ComponentType, ReactNode } from "react";
 import { useMemo } from "react";
 import { useLoaderData, useRouteError } from "react-router";
 import { normalizePath } from "../client/path-utils";
+import { useStackOrNull } from "../context/provider";
 import {
 	type GetStackClient,
 	type ResolveStackClient,
@@ -119,17 +120,18 @@ export function createReactRouterPage(options: CreateReactRouterPageOptions) {
 		return (args.loaderData ?? args.data)?.meta;
 	}
 
-	function Component() {
-		const data = useLoaderData<typeof loader>();
+	function PageContent({ path }: { path: string }) {
 		const queryClient = useQueryClient();
+		const providerStack = useStackOrNull()?.resolvedStack;
 		// Memoized so PageComponent keeps a stable identity across re-renders:
 		// getRoute() invokes the route handler, which produces new component
 		// references each call. Without the memo, any router state change that
 		// re-renders this component (e.g. a search-param update) would remount
 		// the whole page subtree, losing component state such as open dialogs.
 		const route = useMemo(
-			() => getStackClient(queryClient).router.getRoute(data.path),
-			[queryClient, data.path],
+			() =>
+				(providerStack ?? getStackClient(queryClient)).router.getRoute(path),
+			[providerStack, queryClient, path],
 		);
 		const page = route?.PageComponent ? (
 			<route.PageComponent />
@@ -138,10 +140,15 @@ export function createReactRouterPage(options: CreateReactRouterPageOptions) {
 		) : (
 			<div>Route not found</div>
 		);
+		return wrapPage ? wrapPage(page) : page;
+	}
+
+	function Component() {
+		const data = useLoaderData<typeof loader>();
 
 		return (
 			<HydrationBoundary state={data.dehydratedState}>
-				{wrapPage ? wrapPage(page) : page}
+				<PageContent path={data.path} />
 			</HydrationBoundary>
 		);
 	}

package/src/react-router/router.tsx

@@ -52,7 +52,7 @@ function useReactRouterStackRouter(): StackRouter {
  * ```tsx
  * import { reactRouter } from "@btst/stack/react-router";
  *
- * <StackProvider basePath="/pages" router={reactRouter()} api={{ baseURL, basePath: "/api/data" }}>
+ * <StackProvider stack={clientStack} router={reactRouter()}>
  * ```
  */
 export function reactRouter(): StackRouterConfig {

package/src/shared/auth-types.ts

@@ -2,8 +2,8 @@
  * Shared auth contract types used by both the client provider
  * (`@btst/stack/context`) and the backend (`@btst/stack/api`).
  *
- * This module is intentionally type-only so it can be imported from server
- * and client code alike.
+ * This module is runtime-safe so it can be imported from server and client
+ * code alike without pulling in either implementation.
  */
 
 /**
@@ -24,75 +24,24 @@ export interface StackIdentity {
 }
 
 /**
- * A permission check request: "can the current user perform `action` on
- * `resource`?" (e.g. resource `"blog:post"`, action `"delete"`).
- */
-export interface CanParams {
-	/** The resource being accessed (e.g. "blog:post", "comments:moderate") */
-	resource: string;
-	/** The action being performed (e.g. "read", "create", "delete") */
-	action: string;
-	/** Optional extra parameters (e.g. the specific record id) */
-	params?: Record<string, unknown>;
-}
-
-/**
- * Client-side auth provider, passed to `StackProvider` via the `auth` prop.
- *
- * All fields besides `getIdentity` are optional:
- * - Without `can`, every permission check resolves to `true`.
- * - Without `loginPath`, denied route access is not redirected.
+ * Browser authorization adapter accepted by `StackProvider`.
  *
- * @example
- * ```tsx
- * const authProvider: StackAuthProvider = {
- *   getIdentity: () => authClient.getSession().then((s) => s?.user ?? null),
- *   can: ({ resource, action }) => checkPermission(resource, action),
- *   loginPath: "/login",
- * };
- *
- * <StackProvider auth={authProvider} ...>
- * ```
+ * Applications create this value with `createClientAuth()`. Permission checks
+ * use plugin-owned schema-backed descriptors; there is no open string callback.
  */
-export interface StackAuthProvider {
-	/**
-	 * Resolve the current user's identity. Return `null` when unauthenticated.
-	 */
+export interface StackClientAuth {
+	readonly mode: "one-rule";
+	readonly contract: {
+		parseIdentity(identity: unknown): StackIdentity | null;
+	};
+	/** Resolve the current browser identity. */
 	getIdentity: () => Promise<StackIdentity | null> | StackIdentity | null;
-	/**
-	 * Permission check. When omitted, all `useCan()` / `<CanAccess>` checks
-	 * resolve to `true`.
-	 */
-	can?: (
-		params: CanParams & { identity: StackIdentity | null },
-	) => Promise<boolean> | boolean;
-	/**
-	 * Path unauthenticated users are redirected to when route-level permission
-	 * checks deny access (e.g. "/login").
-	 */
-	loginPath?: string;
-}
-
-/**
- * Server-side auth provider, passed to `stack()` via the `auth` config option.
- * `stack()` resolves the identity lazily and at most once per request; plugin
- * lifecycle hooks can read it via `getRequestIdentity(headers)` from
- * `@btst/stack/api`.
- */
-export interface StackServerAuthProvider {
-	/**
-	 * Resolve the identity for an incoming request (e.g. from a session
-	 * cookie). Return `null` when unauthenticated.
-	 */
-	getIdentity: (ctx: {
-		headers: Headers;
-		request: Request;
-	}) => Promise<StackIdentity | null> | StackIdentity | null;
-	/**
-	 * Optional server-side permission check, for consumers and plugins that
-	 * want to share one `can` implementation across lifecycle hooks.
-	 */
-	can?: (
-		params: CanParams & { identity: StackIdentity | null; headers: Headers },
-	) => Promise<boolean> | boolean;
+	/** Runtime hook used by descriptor-aware built-in plugin gates. */
+	readonly usePermission: (permission: unknown) => {
+		readonly can: boolean;
+		readonly isPending: boolean;
+		readonly error?: Error;
+	};
+	/** Optional login target used by descriptor-aware route gates. */
+	readonly loginPath?: string;
 }

package/src/shared/entry-factories.ts

@@ -7,7 +7,7 @@ import type { ComponentType } from "react";
 
 /**
  * Minimal structural view of a route returned by
- * `createStackClient(...).router.getRoute(path)`. The framework entry
+ * `createClientStack(...).router.getRoute(path)`. The framework entry
  * factories only need these three fields.
  */
 export interface StackRouteLike {
@@ -17,8 +17,8 @@ export interface StackRouteLike {
 }
 
 /**
- * Minimal structural view of the object returned by `createStackClient`.
- * Any concrete `ClientLib<TRoutes>` is assignable to this shape.
+ * Minimal structural view of the object returned by `createClientStack`.
+ * Any concrete `ClientStack<TRoutes>` is assignable to this shape.
  */
 export interface StackClientLike {
 	router: {