@btst/stack 3.0.1 → 3.1.0-rc.1

package/src/__tests__/generated-static-identity.test.tsx

@@ -0,0 +1,128 @@
+// @vitest-environment jsdom
+import * as React from "react";
+import { pathToFileURL } from "node:url";
+import { resolve } from "node:path";
+import { act } from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { renderToString } from "react-dom/server";
+import { hydrateRoot } from "react-dom/client";
+import { expect, it, vi } from "vitest";
+import ts from "typescript";
+import { z } from "zod";
+import { defineAuthorization } from "../authorization";
+import { createClientAuth } from "../authorization/client";
+import { createClientStack } from "../client";
+import { StackProvider, useIdentity } from "../context";
+import { blogPermissions } from "../plugins/blog/permissions";
+
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+// Execute the shipped templates. Only framework/application imports are injected;
+// identity state, permission evaluation, SSR, effects and hydration are real.
+function compile(source: string, modules: Record<string, unknown>) {
+	const { outputText } = ts.transpileModule(source, {
+		compilerOptions: {
+			module: ts.ModuleKind.CommonJS,
+			jsx: ts.JsxEmit.ReactJSX,
+		},
+	});
+	const exports: Record<string, any> = {};
+	new Function("require", "exports", outputText)((name: string) => {
+		if (!(name in modules)) throw new Error(`Unexpected import: ${name}`);
+		return modules[name];
+	}, exports);
+	return exports;
+}
+
+it("generated static Blog layout serves public HTML and resolves the browser session", async () => {
+	const authorization = defineAuthorization({
+		identity: z.object({ id: z.string() }),
+		permissions: [blogPermissions] as const,
+		rules: ({ blog }) => [
+			blog.post.read.when(({ facts }) => facts.scope === "published"),
+			blog.post.create.when(({ identity }) => identity !== null),
+		],
+	});
+	const getIdentity = vi.fn(() => ({ id: "browser-user" }));
+	const clientAuth = createClientAuth({ authorization, getIdentity });
+	const queryClient = new QueryClient();
+	const stack = createClientStack({
+		api: { baseURL: "https://app.example", basePath: "/api/data" },
+		site: { baseURL: "https://app.example", basePath: "/pages" },
+		queryClient,
+		plugins: {},
+	});
+	const jsxRuntime = await import("react/jsx-runtime");
+	const { buildScaffoldPlan } = await import(
+		pathToFileURL(resolve(process.cwd(), "../cli/dist/lib.mjs")).href
+	);
+	const plan = await buildScaffoldPlan({
+		framework: "nextjs",
+		adapter: "memory",
+		plugins: ["blog"],
+		alias: "@/",
+		cssFile: "app/globals.css",
+	});
+	const generated = (path: string) =>
+		plan.files.find((file: { path: string }) => file.path === path)
+			.content as string;
+	const modules = {
+		react: React,
+		"react/jsx-runtime": jsxRuntime,
+		"@tanstack/react-query": { QueryClientProvider },
+		"@btst/stack/context": {
+			StackProvider: (props: React.ComponentProps<typeof StackProvider>) => (
+				<StackProvider {...props} auth={clientAuth} />
+			),
+			useIdentity,
+		},
+		"@btst/stack/next": { nextRouter: () => undefined },
+		"@/lib/query-client": { getOrCreateQueryClient: () => queryClient },
+		"@/lib/stack-client": { getStackClient: () => stack },
+	};
+	const client = compile(generated("app/pages/client-layout.tsx"), modules);
+	const { default: Layout } = compile(
+		generated("app/(static)/pages/layout.tsx"),
+		{
+			"react/jsx-runtime": jsxRuntime,
+			"../../pages/client-layout": client,
+			"@/lib/stack-client.server": { getServerClientOrigins: () => ({}) },
+		},
+	);
+	const ui = (
+		<Layout>
+			<clientAuth.CanAccess
+				permission={blogPermissions.post.read({ scope: "published" })}
+				loading={<span>Loading posts</span>}
+			>
+				<h1>Published posts</h1>
+			</clientAuth.CanAccess>
+			<clientAuth.CanAccess
+				permission={blogPermissions.post.create({ publish: "draft" })}
+			>
+				<button type="button">Write a post</button>
+			</clientAuth.CanAccess>
+		</Layout>
+	);
+	const html = renderToString(ui);
+	expect(html).toContain("<h1>Published posts</h1>");
+	expect(html).not.toContain("Loading posts");
+	expect(html).not.toContain("Write a post");
+	expect(getIdentity).not.toHaveBeenCalled();
+	const container = document.createElement("div");
+	container.innerHTML = html;
+	const onRecoverableError = vi.fn();
+	let root: ReturnType<typeof hydrateRoot> | undefined;
+	try {
+		await act(async () => {
+			root = hydrateRoot(container, ui, { onRecoverableError });
+		});
+		expect(container.querySelector("h1")?.textContent).toBe("Published posts");
+		expect(container.querySelector("button")?.textContent).toBe("Write a post");
+		expect(getIdentity).toHaveBeenCalledOnce();
+		expect(onRecoverableError).not.toHaveBeenCalled();
+	} finally {
+		await act(async () => root?.unmount());
+		queryClient.clear();
+	}
+});

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();
+			}
+		},
+	);
+});