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

package/src/plugins/kanban/client/constants.ts

@@ -0,0 +1,2 @@
+/** Canonical programmatic ID for Kanban client registration and overrides. */
+export const KANBAN_PLUGIN_ID = "kanban" as const;

package/src/plugins/kanban/client/hooks/kanban-hooks.tsx

@@ -1,7 +1,11 @@
 "use client";
 
 import { useQuery } from "@tanstack/react-query";
-import { usePluginOverrides } from "@btst/stack/context";
+import {
+	useIdentity,
+	useIdentitySourceGeneration,
+	usePluginOverrides,
+} from "@btst/stack/context";
 import type {
 	ResourceFormConfig,
 	ResourceFormResult,
@@ -13,6 +17,21 @@ import type {
 	SerializedTask,
 } from "../../types";
 import { kanban } from "./kanban-resource";
+import { KANBAN_PLUGIN_ID } from "../constants";
+
+function useIdentityPartition() {
+	const { identity, isPending, error } = useIdentity();
+	const sourceGeneration = useIdentitySourceGeneration();
+	if (isPending) return `pending:${sourceGeneration}` as const;
+	if (error) return `error:${sourceGeneration}` as const;
+	return identity ?? undefined;
+}
+
+function isUnresolvedIdentityPartition(
+	partition: ReturnType<typeof useIdentityPartition>,
+) {
+	return typeof partition === "string";
+}
 
 // ============ Board Hooks ============
 
@@ -22,7 +41,8 @@ export function useBoards(params?: {
 	ownerId?: string;
 	organizationId?: string;
 }) {
-	return kanban.boards.list.use([params]);
+	const identityPartition = useIdentityPartition();
+	return kanban.boards.list.use([params, identityPartition]);
 }
 
 /** Suspense variant of useBoards. */
@@ -31,17 +51,22 @@ export function useSuspenseBoards(params?: {
 	ownerId?: string;
 	organizationId?: string;
 }) {
-	return kanban.boards.list.useSuspense([params]);
+	const identityPartition = useIdentityPartition();
+	return kanban.boards.list.useSuspense([params, identityPartition]);
 }
 
 /** Hook to fetch a single board by ID. */
 export function useBoard(boardId: string) {
-	return kanban.boards.detail.use([boardId], { enabled: !!boardId });
+	const identityPartition = useIdentityPartition();
+	return kanban.boards.detail.use([boardId, identityPartition], {
+		enabled: !!boardId,
+	});
 }
 
 /** Suspense variant of useBoard. */
 export function useSuspenseBoard(boardId: string) {
-	return kanban.boards.detail.useSuspense([boardId]);
+	const identityPartition = useIdentityPartition();
+	return kanban.boards.detail.useSuspense([boardId, identityPartition]);
 }
 
 /**
@@ -173,17 +198,35 @@ export function useTaskMutations() {
 
 // ============ User Resolution Hooks ============
 
+function useKanbanUserCallbacks() {
+	const overrides = usePluginOverrides<KanbanPluginOverrides>(KANBAN_PLUGIN_ID);
+
+	if (
+		typeof overrides.resolveUser !== "function" ||
+		typeof overrides.searchUsers !== "function"
+	) {
+		throw new Error(
+			'[btst/kanban] Missing required StackProvider overrides for "kanban". ' +
+				"Configure overrides={{ kanban: { resolveUser, searchUsers } }} when " +
+				"kanbanClientPlugin() is registered.",
+		);
+	}
+
+	return overrides;
+}
+
 /** Resolve a user from the consumer-provided callback. */
 export function useResolveUser(userId: string | undefined | null) {
-	const { resolveUser } = usePluginOverrides<KanbanPluginOverrides>("kanban");
+	const { resolveUser } = useKanbanUserCallbacks();
+	const identityPartition = useIdentityPartition();
 
 	return useQuery<KanbanUser | null>({
-		queryKey: ["kanban", "users", userId],
+		queryKey: ["kanban", "users", userId, identityPartition],
 		queryFn: async () => {
 			if (!userId) return null;
 			return resolveUser(userId);
 		},
-		enabled: !!userId,
+		enabled: !!userId && !isUnresolvedIdentityPartition(identityPartition),
 		staleTime: 5 * 60 * 1000,
 		gcTime: 10 * 60 * 1000,
 	});
@@ -191,11 +234,13 @@ export function useResolveUser(userId: string | undefined | null) {
 
 /** Search for assignable users through the consumer-provided callback. */
 export function useSearchUsers(query: string, boardId?: string) {
-	const { searchUsers } = usePluginOverrides<KanbanPluginOverrides>("kanban");
+	const { searchUsers } = useKanbanUserCallbacks();
+	const identityPartition = useIdentityPartition();
 
 	return useQuery<KanbanUser[]>({
-		queryKey: ["kanban", "users", "search", query, boardId],
+		queryKey: ["kanban", "users", "search", query, boardId, identityPartition],
 		queryFn: () => searchUsers(query, boardId),
+		enabled: !isUnresolvedIdentityPartition(identityPartition),
 		staleTime: 30_000,
 	});
 }

package/src/plugins/kanban/client/hooks/kanban-resource.ts

@@ -2,12 +2,13 @@
 
 import { createResource } from "@btst/stack/plugins/client/hooks";
 import { kanbanResources } from "../../query-keys";
+import { KANBAN_PLUGIN_ID } from "../constants";
 
 /**
  * Factory-generated Kanban resource hooks. Internal — public hooks preserve
  * the existing Kanban-specific names and return shapes in `kanban-hooks.tsx`.
  */
 export const kanban = createResource({
-	plugin: "kanban",
+	plugin: KANBAN_PLUGIN_ID,
 	resources: kanbanResources,
 });

package/src/plugins/kanban/client/overrides.ts

@@ -42,11 +42,6 @@ export interface KanbanPluginOverrides {
 	 * Whether to show the attribution
 	 */
 	showAttribution?: boolean;
-	/**
-	 * Optional headers to pass with API requests (e.g., for SSR auth)
-	 */
-	headers?: HeadersInit;
-
 	/**
 	 * Function used to upload a new image file from the task description editor
 	 * and return its URL. This is separate from `imagePicker`, which selects an

package/src/plugins/kanban/client/plugin.tsx

@@ -1,17 +1,43 @@
 import {
 	defineClientPlugin,
 	createApiClient,
+	isErrorResponse,
 	isConnectionError,
+	type ResolvedClientPluginRuntime,
 } from "@btst/stack/plugins/client";
+import { normalizePath } from "@btst/stack/client";
 import { defineRoute, defineRoutes } from "@btst/yar";
-import type { ComponentType } from "react";
+import { lazy, type ComponentType } from "react";
 import type { QueryClient } from "@tanstack/react-query";
 import type { KanbanApiRouter } from "../api";
-import { createKanbanQueryKeys } from "../query-keys";
-import type { SerializedBoardWithColumns } from "../types";
-import { BoardsListPageComponent } from "./components/pages/boards-list-page";
-import { NewBoardPageComponent } from "./components/pages/new-board-page";
-import { BoardPageComponent } from "./components/pages/board-page";
+import {
+	createKanbanQueryKeys,
+	type KanbanIdentityPartition,
+} from "../query-keys";
+import type {
+	SerializedBoardSummary,
+	SerializedBoardWithColumns,
+} from "../types";
+import { createSanitizedSSRLoaderError } from "../../utils";
+import { KANBAN_PLUGIN_ID } from "./constants";
+import type { KanbanPluginOverrides } from "./overrides";
+import type { RequiredClientPluginOverrides } from "../../../types";
+
+const BoardsListPageComponent = lazy(() =>
+	import("./components/pages/boards-list-page").then((module) => ({
+		default: module.BoardsListPageComponent,
+	})),
+);
+const NewBoardPageComponent = lazy(() =>
+	import("./components/pages/new-board-page").then((module) => ({
+		default: module.NewBoardPageComponent,
+	})),
+);
+const BoardPageComponent = lazy(() =>
+	import("./components/pages/board-page").then((module) => ({
+		default: module.BoardPageComponent,
+	})),
+);
 
 /**
  * Context passed to route hooks
@@ -51,17 +77,6 @@ export interface LoaderContext {
  * Configuration for kanban client plugin
  */
 export interface KanbanClientConfig {
-	/** 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 for SEO meta tags */
-	siteBaseURL: string;
-	/** Path where pages are mounted (e.g., "/pages") */
-	siteBasePath: string;
-	/** React Query client instance for caching */
-	queryClient: QueryClient;
-
 	/** Optional SEO configuration for meta tags */
 	seo?: {
 		/** Site name for Open Graph tags */
@@ -77,8 +92,8 @@ export interface KanbanClientConfig {
 	/** Optional hooks for customizing behavior */
 	hooks?: KanbanClientHooks;
 
-	/** Optional headers for SSR (e.g., forwarding cookies) */
-	headers?: Headers;
+	/** Identity snapshot used to align protected SSR prefetch and browser keys. */
+	identityPartition?: KanbanIdentityPartition;
 
 	/**
 	 * Optional page component overrides.
@@ -108,7 +123,7 @@ export interface KanbanClientHooks {
 	 * Called after boards are loaded. Throw an error to cancel further processing.
 	 */
 	afterLoadBoards?: (
-		boards: SerializedBoardWithColumns[] | null,
+		boards: SerializedBoardSummary[] | null,
 		context: LoaderContext,
 	) => Promise<void> | void;
 	/**
@@ -135,16 +150,82 @@ export interface KanbanClientHooks {
 	 */
 	afterLoadNewBoard?: (context: LoaderContext) => Promise<void> | void;
 	/**
-	 * Called when a loading error occurs
+	 * Called once to report a loading error. Router error handling remains authoritative.
 	 */
-	onLoadError?: (error: Error, context: LoaderContext) => Promise<void> | void;
+	onErrorLoad?: (error: Error, context: LoaderContext) => Promise<void> | void;
+}
+
+interface ResolvedKanbanClientConfig extends KanbanClientConfig {
+	apiBaseURL: string;
+	apiBasePath: string;
+	siteBaseURL: string;
+	siteBasePath: string;
+	queryClient: QueryClient;
+	headers?: Headers;
+	credentials?: RequestCredentials;
+}
+
+function resolveKanbanClientConfig(
+	config: KanbanClientConfig,
+	runtime: ResolvedClientPluginRuntime<typeof KANBAN_PLUGIN_ID>,
+): ResolvedKanbanClientConfig {
+	return {
+		seo: config.seo,
+		hooks: config.hooks,
+		identityPartition: config.identityPartition,
+		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 createKanbanApiClient(config: ResolvedKanbanClientConfig) {
+	return createApiClient<KanbanApiRouter>({
+		baseURL: config.apiBaseURL,
+		basePath: config.apiBasePath,
+		headers: config.headers,
+		credentials: config.credentials,
+	});
+}
+
+function createLoadErrorReporter(
+	hooks: KanbanClientHooks | 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 {
+			// Reporting hooks cannot make an SSR loader reject or run twice.
+		}
+	};
 }
 
 // Loader for SSR prefetching - boards list
-function createBoardsLoader(config: KanbanClientConfig) {
+function createBoardsLoader(config: ResolvedKanbanClientConfig) {
 	return async () => {
 		if (typeof window === "undefined") {
-			const { queryClient, apiBasePath, apiBaseURL, hooks, headers } = config;
+			const {
+				queryClient,
+				apiBasePath,
+				apiBaseURL,
+				hooks,
+				headers,
+				identityPartition,
+			} = config;
 
 			const context: LoaderContext = {
 				path: "/kanban",
@@ -153,57 +234,65 @@ function createBoardsLoader(config: KanbanClientConfig) {
 				apiBasePath,
 				headers,
 			};
+			const reportError = createLoadErrorReporter(hooks, context);
+			const queries = createKanbanQueryKeys(createKanbanApiClient(config));
+			const listQuery = queries.boards.list({}, identityPartition);
 
 			try {
 				if (hooks?.beforeLoadBoards) {
 					await hooks.beforeLoadBoards(context);
 				}
 
-				const client = createApiClient<KanbanApiRouter>({
-					baseURL: apiBaseURL,
-					basePath: apiBasePath,
-				});
-
-				const queries = createKanbanQueryKeys(client, headers);
-				const listQuery = queries.boards.list({});
-
 				await queryClient.prefetchQuery(listQuery);
 
 				if (hooks?.afterLoadBoards) {
-					const boards = queryClient.getQueryData<SerializedBoardWithColumns[]>(
+					const boards = queryClient.getQueryData<SerializedBoardSummary[]>(
 						listQuery.queryKey,
 					);
 					await hooks.afterLoadBoards(boards || null, context);
 				}
 
 				const queryState = queryClient.getQueryState(listQuery.queryKey);
-				if (queryState?.error && hooks?.onLoadError) {
-					const error =
-						queryState.error instanceof Error
-							? queryState.error
-							: new Error(String(queryState.error));
-					await hooks.onLoadError(error, context);
+				if (queryState?.error) {
+					await reportError(queryState.error);
 				}
 			} catch (error) {
 				if (isConnectionError(error)) {
 					console.warn(
 						"[btst/kanban] route.loader() failed — no server running at build time. " +
-							"Use myStack.api.kanban.prefetchForRoute() for SSG data prefetching.",
+							"Use myStack.raw.kanban.prefetchForRoute() for SSG data prefetching.",
 					);
+				} else {
+					const errToStore = createSanitizedSSRLoaderError();
+					await queryClient.prefetchQuery({
+						queryKey: listQuery.queryKey,
+						queryFn: () => {
+							throw errToStore;
+						},
+						retry: false,
+					});
 				}
-				if (hooks?.onLoadError) {
-					await hooks.onLoadError(error as Error, context);
-				}
+				await reportError(error);
 			}
 		}
 	};
 }
 
 // Loader for SSR prefetching - single board
-function createBoardLoader(boardId: string, config: KanbanClientConfig) {
+function createBoardLoader(
+	boardId: string,
+	config: ResolvedKanbanClientConfig,
+) {
 	return async () => {
 		if (typeof window === "undefined") {
-			const { queryClient, apiBasePath, apiBaseURL, hooks, headers } = config;
+			const {
+				queryClient,
+				apiBasePath,
+				apiBaseURL,
+				hooks,
+				headers,
+				identityPartition,
+			} = config;
 
 			const context: LoaderContext = {
 				path: `/kanban/${boardId}`,
@@ -213,19 +302,15 @@ function createBoardLoader(boardId: string, config: KanbanClientConfig) {
 				apiBasePath,
 				headers,
 			};
+			const reportError = createLoadErrorReporter(hooks, context);
+			const queries = createKanbanQueryKeys(createKanbanApiClient(config));
+			const boardQuery = queries.boards.detail(boardId, identityPartition);
 
 			try {
 				if (hooks?.beforeLoadBoard) {
 					await hooks.beforeLoadBoard(boardId, context);
 				}
 
-				const client = createApiClient<KanbanApiRouter>({
-					baseURL: apiBaseURL,
-					basePath: apiBasePath,
-				});
-
-				const queries = createKanbanQueryKeys(client, headers);
-				const boardQuery = queries.boards.detail(boardId);
 				await queryClient.prefetchQuery(boardQuery);
 
 				if (hooks?.afterLoadBoard) {
@@ -236,30 +321,33 @@ function createBoardLoader(boardId: string, config: KanbanClientConfig) {
 				}
 
 				const queryState = queryClient.getQueryState(boardQuery.queryKey);
-				if (queryState?.error && hooks?.onLoadError) {
-					const error =
-						queryState.error instanceof Error
-							? queryState.error
-							: new Error(String(queryState.error));
-					await hooks.onLoadError(error, context);
+				if (queryState?.error) {
+					await reportError(queryState.error);
 				}
 			} catch (error) {
 				if (isConnectionError(error)) {
 					console.warn(
 						"[btst/kanban] route.loader() failed — no server running at build time. " +
-							"Use myStack.api.kanban.prefetchForRoute() for SSG data prefetching.",
+							"Use myStack.raw.kanban.prefetchForRoute() for SSG data prefetching.",
 					);
+				} else {
+					const errToStore = createSanitizedSSRLoaderError();
+					await queryClient.prefetchQuery({
+						queryKey: boardQuery.queryKey,
+						queryFn: () => {
+							throw errToStore;
+						},
+						retry: false,
+					});
 				}
-				if (hooks?.onLoadError) {
-					await hooks.onLoadError(error as Error, context);
-				}
+				await reportError(error);
 			}
 		}
 	};
 }
 
 // Loader for new board page
-function createNewBoardLoader(config: KanbanClientConfig) {
+function createNewBoardLoader(config: ResolvedKanbanClientConfig) {
 	return async () => {
 		if (typeof window === "undefined") {
 			const { apiBasePath, apiBaseURL, hooks, headers } = config;
@@ -271,6 +359,7 @@ function createNewBoardLoader(config: KanbanClientConfig) {
 				apiBasePath,
 				headers,
 			};
+			const reportError = createLoadErrorReporter(hooks, context);
 
 			try {
 				if (hooks?.beforeLoadNewBoard) {
@@ -281,19 +370,19 @@ function createNewBoardLoader(config: KanbanClientConfig) {
 					await hooks.afterLoadNewBoard(context);
 				}
 			} catch (error) {
-				if (hooks?.onLoadError) {
-					await hooks.onLoadError(error as Error, context);
-				}
+				await reportError(error);
 			}
 		}
 	};
 }
 
 // Meta generators
-function createBoardsListMeta(config: KanbanClientConfig) {
+function createBoardsListMeta(config: ResolvedKanbanClientConfig) {
 	return () => {
 		const { siteBaseURL, siteBasePath, seo } = config;
-		const fullUrl = `${siteBaseURL}${siteBasePath}/kanban`;
+		const fullUrl = `${siteBaseURL}${normalizePath(
+			[siteBasePath, "kanban"].join("/"),
+		)}`;
 		const title = "Kanban Boards";
 		const description =
 			seo?.description || "Manage your projects with kanban boards";
@@ -321,24 +410,13 @@ function createBoardsListMeta(config: KanbanClientConfig) {
 	};
 }
 
-function createBoardMeta(boardId: string, config: KanbanClientConfig) {
+function createBoardMeta(boardId: string, config: ResolvedKanbanClientConfig) {
 	return () => {
-		const {
-			queryClient,
-			apiBaseURL,
-			apiBasePath,
-			siteBaseURL,
-			siteBasePath,
-			seo,
-		} = config;
-		const queries = createKanbanQueryKeys(
-			createApiClient<KanbanApiRouter>({
-				baseURL: apiBaseURL,
-				basePath: apiBasePath,
-			}),
-		);
+		const { queryClient, siteBaseURL, siteBasePath, seo, identityPartition } =
+			config;
+		const queries = createKanbanQueryKeys(createKanbanApiClient(config));
 		const board = queryClient.getQueryData<SerializedBoardWithColumns>(
-			queries.boards.detail(boardId).queryKey,
+			queries.boards.detail(boardId, identityPartition).queryKey,
 		);
 
 		if (!board) {
@@ -348,7 +426,9 @@ function createBoardMeta(boardId: string, config: KanbanClientConfig) {
 			];
 		}
 
-		const fullUrl = `${siteBaseURL}${siteBasePath}/kanban/${board.id}`;
+		const fullUrl = `${siteBaseURL}${normalizePath(
+			[siteBasePath, "kanban", board.id].join("/"),
+		)}`;
 		const title = board.name;
 		const description = board.description || `Kanban board: ${board.name}`;
 
@@ -373,10 +453,12 @@ function createBoardMeta(boardId: string, config: KanbanClientConfig) {
 	};
 }
 
-function createNewBoardMeta(config: KanbanClientConfig) {
+function createNewBoardMeta(config: ResolvedKanbanClientConfig) {
 	return () => {
 		const { siteBaseURL, siteBasePath } = config;
-		const fullUrl = `${siteBaseURL}${siteBasePath}/kanban/new`;
+		const fullUrl = `${siteBaseURL}${normalizePath(
+			[siteBasePath, "kanban", "new"].join("/"),
+		)}`;
 		const title = "Create New Board";
 
 		return [
@@ -397,10 +479,8 @@ function createNewBoardMeta(config: KanbanClientConfig) {
  * Kanban client plugin
  * Provides routes, components, and React Query hooks for kanban boards
  */
-export const kanbanClientPlugin = (config: KanbanClientConfig) =>
-	defineClientPlugin({
-		name: "kanban",
-
+function createResolvedKanbanPlugin(config: ResolvedKanbanClientConfig) {
+	return {
 		routes: () =>
 			defineRoutes(
 				{
@@ -426,7 +506,9 @@ export const kanbanClientPlugin = (config: KanbanClientConfig) =>
 			),
 
 		sitemap: async () => {
-			const origin = `${config.siteBaseURL}${config.siteBasePath}`;
+			const origin = `${config.siteBaseURL}${normalizePath(
+				config.siteBasePath,
+			)}`.replace(/\/$/, "");
 			const indexUrl = `${origin}/kanban`;
 
 			const client = createApiClient<KanbanApiRouter>({
@@ -434,34 +516,40 @@ export const kanbanClientPlugin = (config: KanbanClientConfig) =>
 				basePath: config.apiBasePath,
 			});
 
-			let boards: SerializedBoardWithColumns[] = [];
 			try {
 				const res = await client("/boards", {
 					method: "GET",
 					query: { limit: 100 },
 				});
+				if (isErrorResponse(res)) return [];
 				// /boards returns BoardListResult { items, total, limit, offset }
-				boards = ((res.data as any)?.items ??
-					[]) as SerializedBoardWithColumns[];
+				const boards = ((res.data as any)?.items ??
+					[]) as SerializedBoardSummary[];
+				return [
+					{
+						url: indexUrl,
+						lastModified: new Date(),
+						changeFrequency: "daily" as const,
+						priority: 0.7,
+					},
+					...boards.map((b) => ({
+						url: `${origin}/kanban/${b.id}`,
+						lastModified: b.updatedAt ? new Date(b.updatedAt) : undefined,
+						changeFrequency: "weekly" as const,
+						priority: 0.6,
+					})),
+				];
 			} catch {
-				// Ignore errors for sitemap
+				// Protected-by-default Kanban routes are absent from anonymous sitemaps.
+				return [];
 			}
-
-			const entries = [
-				{
-					url: indexUrl,
-					lastModified: new Date(),
-					changeFrequency: "daily" as const,
-					priority: 0.7,
-				},
-				...boards.map((b) => ({
-					url: `${origin}/kanban/${b.id}`,
-					lastModified: b.updatedAt ? new Date(b.updatedAt) : undefined,
-					changeFrequency: "weekly" as const,
-					priority: 0.6,
-				})),
-			];
-
-			return entries;
 		},
+	};
+}
+
+export const kanbanClientPlugin = (config: KanbanClientConfig = {}) =>
+	defineClientPlugin<RequiredClientPluginOverrides<KanbanPluginOverrides>>()({
+		id: KANBAN_PLUGIN_ID,
+		resolve: (runtime) =>
+			createResolvedKanbanPlugin(resolveKanbanClientConfig(config, runtime)),
 	});