@btst/stack 3.0.2 → 3.1.0-rc.1

package/src/__tests__/provider-hydration.test.tsx

@@ -0,0 +1,164 @@
+// @vitest-environment jsdom
+import {
+	act,
+	createContext,
+	lazy,
+	useContext,
+	useEffect,
+	useLayoutEffect,
+	useState,
+	type ReactNode,
+	type ComponentType,
+} from "react";
+import { createRoot, hydrateRoot } from "react-dom/client";
+import { renderToString } from "react-dom/server";
+import { QueryClient } from "@tanstack/react-query";
+import { expect, it, vi } from "vitest";
+import { z } from "zod";
+import {
+	defineAuthorization,
+	definePermissions,
+	permission,
+} from "../authorization";
+import { createClientAuth } from "../authorization/client";
+import { createClientStack } from "../client";
+import { ComposedRoute } from "../client/components/compose";
+import { StackProvider, useStack } from "../context";
+
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+const permissions = definePermissions("records", {
+	read: permission(z.object({ id: z.string() })),
+});
+const authorization = defineAuthorization({
+	identity: z.object({ id: z.string() }),
+	permissions: [permissions],
+	rules: ({ records }) => [
+		records.read.when(({ identity }) => identity?.id === "owner"),
+	],
+});
+const auth = createClientAuth({ authorization, getIdentity: () => null });
+const owner = { id: "owner" };
+const access = permissions.read({ id: "one" });
+const navigate = () => {};
+const useRouter = () => undefinedRouter;
+const undefinedRouter = {};
+const onError = () => {};
+const Content = () => <div data-content>Prefetched content</div>;
+const Loading = () => <div data-loading>Loading</div>;
+const ErrorPage = () => <div data-denied>Denied</div>;
+
+function createStack() {
+	return createClientStack({
+		api: { baseURL: "http://test.local", basePath: "/api/data" },
+		site: { baseURL: "http://test.local", basePath: "/pages" },
+		queryClient: new QueryClient(),
+		plugins: {},
+	});
+}
+
+it.each([false, true])(
+	"keeps pending page hydration safe when a provider rerenders (revoke: %s)",
+	async (revoke) => {
+		const stack = createStack();
+		function Provider({ children }: { children: ReactNode }) {
+			const [updated, setUpdated] = useState(false);
+			useEffect(() => setUpdated(true), []);
+			return (
+				<StackProvider
+					stack={stack}
+					router={{ navigate, useRouter }}
+					auth={auth}
+					initialIdentity={updated && revoke ? null : owner}
+				>
+					<output>{updated ? "updated" : "initial"}</output>
+					{children}
+				</StackProvider>
+			);
+		}
+		const tree = (Page: ComponentType) => (
+			<Provider>
+				<ComposedRoute
+					path="/record/one"
+					permission={access}
+					PageComponent={Page}
+					LoadingComponent={Loading}
+					ErrorComponent={ErrorPage}
+					onError={onError}
+				/>
+			</Provider>
+		);
+		const container = document.createElement("div");
+		container.innerHTML = renderToString(tree(Content));
+		expect(container.querySelector("[data-content]")).not.toBeNull();
+		const Pending = lazy(
+			() => new Promise<{ default: typeof Content }>(() => {}),
+		);
+		const consoleError = vi
+			.spyOn(console, "error")
+			.mockImplementation(() => {});
+		const consoleWarn = vi.spyOn(console, "warn").mockImplementation(() => {});
+		const onRecoverableError = vi.fn();
+		let root: ReturnType<typeof hydrateRoot> | undefined;
+		try {
+			await act(async () => {
+				root = hydrateRoot(container, tree(Pending), { onRecoverableError });
+			});
+			expect(container.querySelector("output")?.textContent).toBe("updated");
+			expect(container.querySelector("[data-content]") !== null).toBe(!revoke);
+			expect(container.querySelector("[data-denied]") !== null).toBe(revoke);
+			expect(container.querySelector("[data-loading]")).toBeNull();
+			expect(onRecoverableError).not.toHaveBeenCalled();
+		} finally {
+			await act(async () => root?.unmount());
+			stack.provider.queryClient.clear();
+			consoleError.mockRestore();
+			consoleWarn.mockRestore();
+		}
+	},
+);
+
+it("applies new router callbacks with the current host context before page effects", async () => {
+	const Workspace = createContext("A");
+	const stack = createStack();
+	const observations: string[] = [];
+	function Page() {
+		const workspace = useContext(Workspace);
+		const { router } = useStack();
+		useLayoutEffect(() => {
+			void router?.navigate?.(workspace);
+		}, [workspace]);
+		return null;
+	}
+	function App() {
+		const [workspace, setWorkspace] = useState("A");
+		useEffect(() => setWorkspace("B"), []);
+		return (
+			<Workspace.Provider value={workspace}>
+				<StackProvider
+					stack={stack}
+					router={{
+						navigate: (current) => {
+							observations.push(`${current}:${workspace}`);
+						},
+					}}
+				>
+					<ComposedRoute
+						path="/record"
+						PageComponent={Page}
+						LoadingComponent={Loading}
+						onError={onError}
+					/>
+				</StackProvider>
+			</Workspace.Provider>
+		);
+	}
+	const root = createRoot(document.createElement("div"));
+	try {
+		await act(async () => root.render(<App />));
+		expect(observations).toEqual(["A:A", "B:B"]);
+	} finally {
+		await act(async () => root.unmount());
+		stack.provider.queryClient.clear();
+	}
+});

package/src/context/auth.tsx

@@ -193,21 +193,28 @@ export function StackAuthBoundary({
 		void resolveIdentity(false);
 	}, [initialIdentity, resolveIdentity]);
 
-	return (
-		<AuthContext.Provider
-			value={{
-				provider,
-				identity: currentState.identity,
-				isPending: currentState.isPending,
-				sourceGeneration: currentResolutionGeneration,
-				...(currentState.error ? { error: currentState.error } : {}),
-				refetch,
-				waitForResolution,
-			}}
-		>
-			{children}
-		</AuthContext.Provider>
+	const value = useMemo(
+		() => ({
+			provider,
+			identity: currentState.identity,
+			isPending: currentState.isPending,
+			sourceGeneration: currentResolutionGeneration,
+			...(currentState.error ? { error: currentState.error } : {}),
+			refetch,
+			waitForResolution,
+		}),
+		[
+			provider,
+			currentState.identity,
+			currentState.isPending,
+			currentResolutionGeneration,
+			currentState.error,
+			refetch,
+			waitForResolution,
+		],
 	);
+
+	return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
 }
 
 /** @internal Access the raw auth context (or `null` when no provider is set). */

package/src/context/provider.tsx

@@ -2,6 +2,7 @@
 import {
 	createContext,
 	useContext,
+	useMemo,
 	type ReactElement,
 	type ReactNode,
 } from "react";
@@ -79,6 +80,10 @@ type StackProviderServices = {
 	i18n?: StackI18nProvider;
 };
 
+/** Plugin override configuration inferred from a resolved client stack. */
+export type ClientStackOverrides<TStack extends ResolvedClientStack<any, any>> =
+	InferredPluginOverrides<RegisteredClientPlugins<TStack>>;
+
 type CanonicalStackProviderOverrideProps<
 	TStack extends ResolvedClientStack<any, any>,
 > = InferredPluginOverrides<
@@ -110,12 +115,24 @@ function stripUndefined<T extends Record<string, any>>(obj: T): Partial<T> {
 	return result as Partial<T>;
 }
 
-function resolveStaticRouter(
-	router: StackRouterConfig | undefined,
-): StackRouter | undefined {
-	if (!router) return undefined;
-	const { useRouter: _useRouter, ...staticFields } = router;
-	return stripUndefined(staticFields);
+function useStaticRouter(router: StackRouterConfig | undefined) {
+	const { Link, Image, navigate, refresh, getSearchParams, setSearchParams } =
+		router ?? {};
+	const present = router !== undefined;
+	return useMemo(
+		() =>
+			present
+				? stripUndefined({
+						Link,
+						Image,
+						navigate,
+						refresh,
+						getSearchParams,
+						setSearchParams,
+					})
+				: undefined,
+		[present, Link, Image, navigate, refresh, getSearchParams, setSearchParams],
+	);
 }
 
 /**
@@ -135,15 +152,16 @@ function RouterBridge({
 	children?: ReactNode;
 }) {
 	const hookRouter = useRouter();
-	const router: StackRouter = {
-		...staticRouter,
-		...stripUndefined(hookRouter),
-	};
+	const context = useMemo(
+		() => ({
+			...value,
+			router: { ...staticRouter, ...stripUndefined(hookRouter) },
+		}),
+		[value, staticRouter, hookRouter],
+	);
 
 	return (
-		<StackContext.Provider value={{ ...value, router }}>
-			{children}
-		</StackContext.Provider>
+		<StackContext.Provider value={context}>{children}</StackContext.Provider>
 	);
 }
 
@@ -205,18 +223,25 @@ export function StackProvider<
 	i18n,
 }: CanonicalStackProviderProps<TStack>): ReactElement {
 	const projection = stack.provider;
-	const staticRouter = resolveStaticRouter(router);
-	const value: Omit<StackContextValue<any>, "router"> = {
-		overrides: overrides ?? {},
-		basePath: projection.site.basePath,
-		api: projection.api,
-		site: projection.site,
-		plugins: projection.plugins,
-		queryClient: projection.queryClient,
-		clientStackContext: stack.context,
-		resolvedStack: stack,
-		auth,
-	};
+	const staticRouter = useStaticRouter(router);
+	const value = useMemo(
+		() => ({
+			overrides: overrides ?? {},
+			basePath: projection.site.basePath,
+			api: projection.api,
+			site: projection.site,
+			plugins: projection.plugins,
+			queryClient: projection.queryClient,
+			clientStackContext: stack.context,
+			resolvedStack: stack,
+			auth,
+		}),
+		[overrides, stack, auth],
+	);
+	const context = useMemo(
+		() => ({ ...value, router: staticRouter }),
+		[value, staticRouter],
+	);
 
 	const content = auth ? (
 		<StackAuthBoundary provider={auth} initialIdentity={initialIdentity}>
@@ -235,9 +260,7 @@ export function StackProvider<
 			{content}
 		</RouterBridge>
 	) : (
-		<StackContext.Provider value={{ ...value, router: staticRouter }}>
-			{content}
-		</StackContext.Provider>
+		<StackContext.Provider value={context}>{content}</StackContext.Provider>
 	);
 
 	return (

package/src/plugins/blog/__tests__/page-load-error.test.tsx

@@ -0,0 +1,53 @@
+// @vitest-environment jsdom
+import { act, lazy } from "react";
+import { createRoot } from "react-dom/client";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { expect, it, vi } from "vitest";
+import { createClientStack } from "@btst/stack/client";
+import { StackProvider } from "@btst/stack/context";
+import { blogClientPlugin } from "@btst/stack/plugins/blog/client";
+import { createHomePage } from "../client/components/pages/home-page";
+
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+it("reports a failed page module through the existing blog error hook and UI", async () => {
+	const error = new Error("Page module unavailable");
+	const Page = createHomePage(lazy(() => Promise.reject(error)));
+	const onRouteError = vi.fn();
+	const queryClient = new QueryClient();
+	const stack = createClientStack({
+		api: { baseURL: "http://test.local", basePath: "/api/data" },
+		site: { baseURL: "http://test.local", basePath: "/pages" },
+		queryClient,
+		plugins: { blog: blogClientPlugin() },
+	});
+	const container = document.createElement("div");
+	const root = createRoot(container);
+	const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+	try {
+		await act(async () =>
+			root.render(
+				<QueryClientProvider client={queryClient}>
+					<StackProvider
+						stack={stack}
+						overrides={{ blog: { onRouteError, uploadImage: async () => "" } }}
+					>
+						<Page />
+					</StackProvider>
+				</QueryClientProvider>,
+			),
+		);
+		expect(
+			container.querySelector('[data-testid="error-placeholder"]'),
+		).not.toBeNull();
+		expect(onRouteError).toHaveBeenCalledExactlyOnceWith("posts", error, {
+			path: "/blog",
+			isSSR: false,
+			published: true,
+		});
+	} finally {
+		await act(async () => root.unmount());
+		queryClient.clear();
+		consoleError.mockRestore();
+	}
+});

package/src/plugins/blog/__tests__/page-loading.test.tsx

@@ -0,0 +1,106 @@
+import { renderToString } from "react-dom/server";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { describe, expect, it, vi } from "vitest";
+import { StackProvider } from "@btst/stack/context";
+import { createClientStack } from "@btst/stack/client";
+import { blogClientPlugin } from "@btst/stack/plugins/blog/client";
+import { PostListPage } from "@btst/stack/plugins/blog/client/pages/posts";
+import { PostPage } from "@btst/stack/plugins/blog/client/pages/post";
+import { TagPage } from "@btst/stack/plugins/blog/client/pages/tag";
+import { defineAuthorization } from "@btst/stack/authorization";
+import { createClientAuth } from "@btst/stack/authorization/client";
+import { blogPermissions } from "@btst/stack/plugins/blog/permissions";
+import { z } from "zod";
+import { BLOG_QUERY_KEYS } from "../api/query-key-defs";
+
+const post = {
+	id: "prefetched-post",
+	slug: "prefetched-post",
+	title: "Prefetched article",
+	content: "Article available before hydration.",
+	excerpt: "Article excerpt",
+	published: true,
+	tags: [],
+	image: null,
+	authorId: null,
+	createdAt: "2026-09-16T12:00:00.000Z",
+	updatedAt: "2026-09-16T12:00:00.000Z",
+	publishedAt: "2026-09-16T12:00:00.000Z",
+};
+
+const authorization = defineAuthorization({
+	identity: z.object({ id: z.string() }),
+	permissions: [blogPermissions] as const,
+	rules: ({ blog }) => [
+		blog.post.read.when(
+			({ facts }) =>
+				facts.scope === "published" ||
+				(facts.scope === "post" && (!facts.exists || facts.published)),
+		),
+		blog.tag.read.allow(),
+	],
+});
+const auth = createClientAuth({ authorization, getIdentity: () => null });
+
+describe("blog pages in native framework routes", () => {
+	it.each(["list", "post", "tag", "draft list", "draft post", "missing post"])(
+		"renders prefetched %s with the existing public-access rules",
+		(page) => {
+			const fetch = vi
+				.spyOn(globalThis, "fetch")
+				.mockRejectedValue(new Error("Unexpected fetch"));
+			const published = !page.startsWith("draft");
+			const queryClient = new QueryClient({
+				defaultOptions: { queries: { retry: false, staleTime: Infinity } },
+			});
+			queryClient.setQueryData(
+				BLOG_QUERY_KEYS.postDetail(post.slug),
+				page === "missing post" ? null : { ...post, published },
+			);
+			queryClient.setQueryData(
+				BLOG_QUERY_KEYS.postsList({
+					published,
+					...(page === "tag" ? { tagSlug: "news" } : {}),
+				}),
+				{
+					pages: [[post]],
+					pageParams: [0],
+				},
+			);
+			queryClient.setQueryData(BLOG_QUERY_KEYS.tagsList(), [
+				{ id: "news", slug: "news", name: "News" },
+			]);
+			const stack = createClientStack({
+				api: { baseURL: "http://test.local", basePath: "/api/data" },
+				site: { baseURL: "http://test.local", basePath: "/pages" },
+				queryClient,
+				plugins: { blog: blogClientPlugin() },
+			});
+			try {
+				const html = renderToString(
+					<QueryClientProvider client={queryClient}>
+						<StackProvider stack={stack} auth={auth} initialIdentity={null}>
+							{page.endsWith("list") ? (
+								<PostListPage published={published} />
+							) : page === "tag" ? (
+								<TagPage tagSlug="news" />
+							) : (
+								<PostPage slug={post.slug} />
+							)}
+						</StackProvider>
+					</QueryClientProvider>,
+				);
+				if (published && page !== "missing post")
+					expect(html).toContain(post.title);
+				else expect(html).not.toContain(post.title);
+				if (page === "missing post") expect(html).toContain("does not exist");
+				if (published)
+					expect(html).not.toMatch(/data-testid="(?:posts|post)-skeleton"/);
+				expect(fetch).not.toHaveBeenCalled();
+			} finally {
+				queryClient.clear();
+				fetch.mockRestore();
+			}
+		},
+	);
+});

package/src/plugins/blog/client/components/pages/home-page.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { lazy } from "react";
+import { lazy, type ComponentType } from "react";
 import { usePluginOverrides } from "@btst/stack/context";
 import type { BlogPluginOverrides } from "../../overrides";
 import { BLOG_PLUGIN_ID } from "../../constants";
@@ -10,39 +10,43 @@ import { PostsLoading } from "../loading";
 import { NotFoundPage } from "./404-page";
 import { blogPermissions } from "../../../permissions";
 
-// Lazy load the internal component with actual page content
-const HomePage = lazy(() =>
-	import("./home-page.internal").then((m) => ({ default: m.HomePage })),
-);
+// Share the guarded page between the lazy registry and native route entry.
+export function createHomePage(
+	HomePage: ComponentType<{ published: boolean }>,
+) {
+	// Exported wrapped component with error and loading boundaries
+	function HomePageComponent({ published = true }: { published?: boolean }) {
+		const { onRouteError } =
+			usePluginOverrides<BlogPluginOverrides>(BLOG_PLUGIN_ID);
+		return (
+			<ComposedRoute
+				path={published ? "/blog" : "/blog/drafts"}
+				PageComponent={HomePage}
+				ErrorComponent={DefaultError}
+				LoadingComponent={PostsLoading}
+				NotFoundComponent={NotFoundPage}
+				permission={blogPermissions.post.read({
+					scope: published ? "published" : "drafts",
+				})}
+				props={{ published }}
+				onError={(error) => {
+					if (onRouteError) {
+						onRouteError("posts", error, {
+							path: published ? "/blog" : "/blog/drafts",
+							isSSR: typeof window === "undefined",
+							published,
+						});
+					}
+				}}
+			/>
+		);
+	}
 
-// Exported wrapped component with error and loading boundaries
-export function HomePageComponent({
-	published = true,
-}: {
-	published?: boolean;
-}) {
-	const { onRouteError } =
-		usePluginOverrides<BlogPluginOverrides>(BLOG_PLUGIN_ID);
-	return (
-		<ComposedRoute
-			path={published ? "/blog" : "/blog/drafts"}
-			PageComponent={HomePage}
-			ErrorComponent={DefaultError}
-			LoadingComponent={PostsLoading}
-			NotFoundComponent={NotFoundPage}
-			permission={blogPermissions.post.read({
-				scope: published ? "published" : "drafts",
-			})}
-			props={{ published }}
-			onError={(error) => {
-				if (onRouteError) {
-					onRouteError("posts", error, {
-						path: published ? "/blog" : "/blog/drafts",
-						isSSR: typeof window === "undefined",
-						published,
-					});
-				}
-			}}
-		/>
-	);
+	return HomePageComponent;
 }
+
+export const HomePageComponent = createHomePage(
+	lazy(() =>
+		import("./home-page.internal").then((m) => ({ default: m.HomePage })),
+	),
+);