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

package/dist/context/index.d.ts

@@ -1,8 +1,18 @@
+import * as React$1 from 'react';
+import { ReactNode, ReactElement } from 'react';
+import { QueryClient } from '@tanstack/react-query';
+import { v as ResolvedClientStack, T as InferredPluginOverrides, U as RegisteredClientPlugins, y as ClientLocation, H as ClientProviderPluginRuntime, K as ClientStackContext } from '../shared/stack.0O62uXqP.js';
+import { S as StackClientAuth, a as StackIdentity } from '../shared/stack.BYMentwB.js';
+import { a as StackRouterConfig, b as StackRouter, c as StackApiConfig, d as StackClientLike } from '../shared/stack.BRvqQWGt.js';
+export { j as joinBasePath } from '../shared/stack.BRvqQWGt.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ReactNode } from 'react';
-import { a as StackAuthProvider, C as CanParams, b as StackIdentity } from '../shared/stack.C4_gEENS.js';
-export { S as StackServerAuthProvider } from '../shared/stack.C4_gEENS.js';
-import { S as StackRouterConfig, a as StackApiConfig, b as StackRouter } from '../shared/stack.aqVZ6PEW.js';
+import { PermissionRequest } from '../authorization/index.js';
+import '@btst/yar';
+import '@btst/db';
+import 'better-call';
+import '../authorization/server.js';
+import '../shared/stack.CKXzdGiJ.js';
+import 'zod';
 
 /**
  * Optional i18n provider, passed to `StackProvider` via the `i18n` prop.
@@ -83,31 +93,67 @@ 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;
 }
-/**
- * The `overrides` prop shape for `StackProvider`.
- * Plugin blocks are optional; fields inside each block retain the plugin's
- * declared requirements.
- */
-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>;
 /**
  * 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} />,
@@ -118,49 +164,24 @@ type StackProviderOverrides<TPluginOverrides extends Record<string, any>> = Part
  * </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>
  * ```
  */
-declare function StackProvider<TPluginOverrides extends Record<string, any> = Record<string, any>>({ children, overrides, basePath, router, api, auth, 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;
-}): react_jsx_runtime.JSX.Element;
+declare function StackProvider<const TStack extends ResolvedClientStack<any, any>>({ children, overrides, stack, router, auth, initialIdentity, notify, i18n, }: CanonicalStackProviderProps<TStack>): ReactElement;
 /**
  * Hook to access the entire BTST context
  * Useful if you need access to multiple plugins or the full context
@@ -222,6 +243,24 @@ declare function usePluginOverrides<TOverrides = any, TDefaults extends Partial<
  */
 declare function useBasePath(): string;
 
+/**
+ * Resolve one registered plugin's page links and programmatic navigation.
+ *
+ * Uses the plugin's resolved site endpoint, including per-plugin overrides.
+ * Same-origin destinations use the configured router; cross-origin destinations
+ * and stacks without a router use full-page browser navigation.
+ */
+declare function usePluginSiteNavigation(pluginId: string): {
+    Link: string | React$1.ComponentType<React$1.ClassAttributes<HTMLAnchorElement> & React$1.AnchorHTMLAttributes<HTMLAnchorElement> & Record<string, any>>;
+    navigate: (...segments: string[]) => void | Promise<void>;
+    resolve: (...segments: string[]) => {
+        path: string;
+        href: string;
+        crossOrigin: boolean;
+    };
+};
+
+type AnyPermissionRequest = PermissionRequest;
 /**
  * Returns the current user's identity as resolved by the auth provider
  * configured on `StackProvider`.
@@ -237,51 +276,34 @@ declare function useBasePath(): string;
 declare function useIdentity(): {
     identity: StackIdentity | null;
     isPending: boolean;
+    error?: Error;
     refetch: () => Promise<void>;
 };
+/** @internal Serializable identity-resolution key for protected query caches. */
+declare function useIdentitySourceGeneration(): number;
+/** @internal Promise that settles when the current identity lookup finishes. */
+declare function useIdentityResolutionPromise(): Promise<void> | undefined;
 type CanState = {
     can: boolean;
     isPending: boolean;
 };
+/** State yielded by a plugin-owned permission descriptor gate. */
+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 />;
- * ```
- */
-declare function useCan(params: CanParams): CanState;
-/**
- * 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>
- * ```
+ * Evaluate a plugin-owned descriptor through the configured client auth.
+ * Omitting browser authorization remains presentation-only permissive; the
+ * backend is always the security boundary.
  */
-declare function CanAccess({ resource, action, params, fallback, loading, children, }: CanParams & {
-    /** Rendered when access is denied (default `null`) */
+declare function PermissionCheck({ permission, children, }: {
+    permission: AnyPermissionRequest;
+    children: (state: PermissionCheckState) => ReactNode;
+}): react_jsx_runtime.JSX.Element;
+/** Element-level gate for a plugin-owned, schema-backed descriptor. */
+declare function PermissionAccess({ permission, fallback, loading, children, }: {
+    permission: AnyPermissionRequest;
     fallback?: ReactNode;
-    /** Rendered while the permission check is pending (default `null`) */
     loading?: ReactNode;
     children?: ReactNode;
 }): react_jsx_runtime.JSX.Element;
@@ -316,5 +338,5 @@ type TranslateFn = (key: string, defaultValue: string, params?: Record<string, u
  */
 declare function useTranslate(): TranslateFn;
 
-export { CanAccess, CanParams, StackApiConfig, StackAuthProvider, StackIdentity, StackProvider, StackRouter, StackRouterConfig, defaultNotifyProvider, useBasePath, useCan, useIdentity, useNotify, usePluginOverrides, useStack, useStackOrNull, useTranslate };
-export type { NotifyOptions, StackI18nProvider, StackNotifyProvider, StackProviderOverrides, TranslateFn };
+export { PermissionAccess, PermissionCheck, StackApiConfig, StackClientAuth, StackIdentity, StackProvider, StackRouter, StackRouterConfig, defaultNotifyProvider, useBasePath, useIdentity, useIdentityResolutionPromise, useIdentitySourceGeneration, useNotify, usePluginOverrides, usePluginSiteNavigation, useStack, useStackOrNull, useTranslate };
+export type { NotifyOptions, PermissionCheckState, StackI18nProvider, StackNotifyProvider, TranslateFn };

package/dist/context/index.mjs

@@ -1,4 +1,6 @@
 export { StackProvider, useBasePath, usePluginOverrides, useStack, useStackOrNull } from '../packages/stack/src/context/provider.mjs';
-export { CanAccess, useCan, useIdentity } from '../packages/stack/src/context/auth.mjs';
+export { joinBasePath } from '../packages/stack/src/context/router.mjs';
+export { usePluginSiteNavigation } from '../packages/stack/src/context/site-navigation.mjs';
+export { PermissionAccess, PermissionCheck, useIdentity, useIdentityResolutionPromise, useIdentitySourceGeneration } from '../packages/stack/src/context/auth.mjs';
 export { defaultNotifyProvider, useNotify } from '../packages/stack/src/context/notify.mjs';
 export { useTranslate } from '../packages/stack/src/context/i18n.mjs';

package/dist/index.cjs

@@ -5,6 +5,5 @@ const node = require('better-call/node');
 
 
 
-exports.getRequestIdentity = api_index.getRequestIdentity;
-exports.stack = api_index.stack;
+exports.createBackendStack = api_index.createBackendStack;
 exports.toNodeHandler = node.toNodeHandler;

package/dist/index.d.cts

@@ -1,7 +1,12 @@
-export { getRequestIdentity, stack } from './api/index.cjs';
+export { createBackendStack } from './api/index.cjs';
 export { toNodeHandler } from 'better-call/node';
-export { i as BackendLib, h as BackendLibConfig, B as BackendPlugin, j as PluginApis, S as StackContext } from './shared/stack.CBsp9rDM.cjs';
-export { C as CanParams, b as StackIdentity, S as StackServerAuthProvider } from './shared/stack.C4_gEENS.cjs';
+export { B as BackendPlugin, Y as BackendStack, W as BackendStackConfig, _ as PluginOperations, Z as PluginRaw, S as StackContext } from './shared/stack.DiuRuzIs.cjs';
+export { a as StackIdentity } from './shared/stack.BYMentwB.cjs';
+import './authorization/index.cjs';
+import 'zod';
+import './authorization/server.cjs';
+import './shared/stack.CKXzdGiJ.cjs';
 import '@btst/yar';
+import '@tanstack/react-query';
 import '@btst/db';
 import 'better-call';

package/dist/index.d.mts

@@ -1,7 +1,12 @@
-export { getRequestIdentity, stack } from './api/index.mjs';
+export { createBackendStack } from './api/index.mjs';
 export { toNodeHandler } from 'better-call/node';
-export { i as BackendLib, h as BackendLibConfig, B as BackendPlugin, j as PluginApis, S as StackContext } from './shared/stack.BL5PvShn.mjs';
-export { C as CanParams, b as StackIdentity, S as StackServerAuthProvider } from './shared/stack.C4_gEENS.mjs';
+export { B as BackendPlugin, Y as BackendStack, W as BackendStackConfig, _ as PluginOperations, Z as PluginRaw, S as StackContext } from './shared/stack.CfK5NKlK.mjs';
+export { a as StackIdentity } from './shared/stack.BYMentwB.mjs';
+import './authorization/index.mjs';
+import 'zod';
+import './authorization/server.mjs';
+import './shared/stack.CKXzdGiJ.mjs';
 import '@btst/yar';
+import '@tanstack/react-query';
 import '@btst/db';
 import 'better-call';

package/dist/index.d.ts

@@ -1,7 +1,12 @@
-export { getRequestIdentity, stack } from './api/index.js';
+export { createBackendStack } from './api/index.js';
 export { toNodeHandler } from 'better-call/node';
-export { i as BackendLib, h as BackendLibConfig, B as BackendPlugin, j as PluginApis, S as StackContext } from './shared/stack.BqTR6qi2.js';
-export { C as CanParams, b as StackIdentity, S as StackServerAuthProvider } from './shared/stack.C4_gEENS.js';
+export { B as BackendPlugin, Y as BackendStack, W as BackendStackConfig, _ as PluginOperations, Z as PluginRaw, S as StackContext } from './shared/stack.0O62uXqP.js';
+export { a as StackIdentity } from './shared/stack.BYMentwB.js';
+import './authorization/index.js';
+import 'zod';
+import './authorization/server.js';
+import './shared/stack.CKXzdGiJ.js';
 import '@btst/yar';
+import '@tanstack/react-query';
 import '@btst/db';
 import 'better-call';

package/dist/index.mjs

@@ -1,2 +1,2 @@
-export { getRequestIdentity, stack } from './api/index.mjs';
+export { createBackendStack } from './api/index.mjs';
 export { toNodeHandler } from 'better-call/node';

package/dist/next/index.d.cts

@@ -1,10 +1,9 @@
-import { S as StackRequestHandler, R as ResolveStackClient } from '../shared/stack.EOPVnJrF.cjs';
-export { G as GetStackClient } from '../shared/stack.EOPVnJrF.cjs';
+import { S as StackRequestHandler, R as ResolveStackClient, a as StackRouterConfig } from '../shared/stack.BRvqQWGt.cjs';
+export { G as GetStackClient } from '../shared/stack.BRvqQWGt.cjs';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { QueryClient, DehydrateOptions } from '@tanstack/react-query';
 import { Metadata } from 'next';
 import { ReactNode } from 'react';
-import { S as StackRouterConfig } from '../shared/stack.aqVZ6PEW.cjs';
 
 /**
  * Wires a BTST API handler to the five HTTP method exports a Next.js route
@@ -65,16 +64,29 @@ interface CreateNextPageOptions {
  *
  * @example
  * ```tsx
- * // app/pages/[[...all]]/page.tsx
+ * // app/(request)/pages/[[...all]]/page.tsx
  * import { createNextPage } from "@btst/stack/next";
+ * import { headers } from "next/headers";
  * import { getOrCreateQueryClient } from "@/lib/query-client";
- * import { getStackClient } from "@/lib/stack-client";
+ * import { getStackClientForRequest } from "@/lib/stack-client.server";
  *
  * export const dynamic = "force-dynamic";
- * const page = createNextPage({ getStackClient, getQueryClient: getOrCreateQueryClient });
+ * const page = createNextPage({
+ *   getStackClient: async (queryClient) =>
+ *     getStackClientForRequest(queryClient, {
+ *       headers: new Headers(await headers()),
+ *     }),
+ *   getQueryClient: getOrCreateQueryClient,
+ * });
  * export default page.Page;
  * export const generateMetadata = page.generateMetadata;
  * ```
+ *
+ * Keep this request-aware catch-all under `app/(request)/pages`. Put SSG/ISR
+ * pages under `app/(static)/pages`; both groups retain `/pages/*` URLs. Their
+ * layouts should wrap the shared client provider from
+ * `app/pages/client-layout.tsx`, with request origins resolved only in the
+ * request group.
  */
 declare function createNextPage(options: CreateNextPageOptions): {
     Page: (pageProps: NextPageProps) => Promise<react_jsx_runtime.JSX.Element>;
@@ -88,7 +100,7 @@ declare function createNextPage(options: CreateNextPageOptions): {
  * ```tsx
  * import { nextRouter } from "@btst/stack/next";
  *
- * <StackProvider basePath="/pages" router={nextRouter()} api={{ baseURL, basePath: "/api/data" }}>
+ * <StackProvider stack={clientStack} router={nextRouter()}>
  * ```
  */
 declare function nextRouter(): StackRouterConfig;

package/dist/next/index.d.mts

@@ -1,10 +1,9 @@
-import { S as StackRequestHandler, R as ResolveStackClient } from '../shared/stack.EOPVnJrF.mjs';
-export { G as GetStackClient } from '../shared/stack.EOPVnJrF.mjs';
+import { S as StackRequestHandler, R as ResolveStackClient, a as StackRouterConfig } from '../shared/stack.BRvqQWGt.mjs';
+export { G as GetStackClient } from '../shared/stack.BRvqQWGt.mjs';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { QueryClient, DehydrateOptions } from '@tanstack/react-query';
 import { Metadata } from 'next';
 import { ReactNode } from 'react';
-import { S as StackRouterConfig } from '../shared/stack.aqVZ6PEW.mjs';
 
 /**
  * Wires a BTST API handler to the five HTTP method exports a Next.js route
@@ -65,16 +64,29 @@ interface CreateNextPageOptions {
  *
  * @example
  * ```tsx
- * // app/pages/[[...all]]/page.tsx
+ * // app/(request)/pages/[[...all]]/page.tsx
  * import { createNextPage } from "@btst/stack/next";
+ * import { headers } from "next/headers";
  * import { getOrCreateQueryClient } from "@/lib/query-client";
- * import { getStackClient } from "@/lib/stack-client";
+ * import { getStackClientForRequest } from "@/lib/stack-client.server";
  *
  * export const dynamic = "force-dynamic";
- * const page = createNextPage({ getStackClient, getQueryClient: getOrCreateQueryClient });
+ * const page = createNextPage({
+ *   getStackClient: async (queryClient) =>
+ *     getStackClientForRequest(queryClient, {
+ *       headers: new Headers(await headers()),
+ *     }),
+ *   getQueryClient: getOrCreateQueryClient,
+ * });
  * export default page.Page;
  * export const generateMetadata = page.generateMetadata;
  * ```
+ *
+ * Keep this request-aware catch-all under `app/(request)/pages`. Put SSG/ISR
+ * pages under `app/(static)/pages`; both groups retain `/pages/*` URLs. Their
+ * layouts should wrap the shared client provider from
+ * `app/pages/client-layout.tsx`, with request origins resolved only in the
+ * request group.
  */
 declare function createNextPage(options: CreateNextPageOptions): {
     Page: (pageProps: NextPageProps) => Promise<react_jsx_runtime.JSX.Element>;
@@ -88,7 +100,7 @@ declare function createNextPage(options: CreateNextPageOptions): {
  * ```tsx
  * import { nextRouter } from "@btst/stack/next";
  *
- * <StackProvider basePath="/pages" router={nextRouter()} api={{ baseURL, basePath: "/api/data" }}>
+ * <StackProvider stack={clientStack} router={nextRouter()}>
  * ```
  */
 declare function nextRouter(): StackRouterConfig;

package/dist/next/index.d.ts

@@ -1,10 +1,9 @@
-import { S as StackRequestHandler, R as ResolveStackClient } from '../shared/stack.EOPVnJrF.js';
-export { G as GetStackClient } from '../shared/stack.EOPVnJrF.js';
+import { S as StackRequestHandler, R as ResolveStackClient, a as StackRouterConfig } from '../shared/stack.BRvqQWGt.js';
+export { G as GetStackClient } from '../shared/stack.BRvqQWGt.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { QueryClient, DehydrateOptions } from '@tanstack/react-query';
 import { Metadata } from 'next';
 import { ReactNode } from 'react';
-import { S as StackRouterConfig } from '../shared/stack.aqVZ6PEW.js';
 
 /**
  * Wires a BTST API handler to the five HTTP method exports a Next.js route
@@ -65,16 +64,29 @@ interface CreateNextPageOptions {
  *
  * @example
  * ```tsx
- * // app/pages/[[...all]]/page.tsx
+ * // app/(request)/pages/[[...all]]/page.tsx
  * import { createNextPage } from "@btst/stack/next";
+ * import { headers } from "next/headers";
  * import { getOrCreateQueryClient } from "@/lib/query-client";
- * import { getStackClient } from "@/lib/stack-client";
+ * import { getStackClientForRequest } from "@/lib/stack-client.server";
  *
  * export const dynamic = "force-dynamic";
- * const page = createNextPage({ getStackClient, getQueryClient: getOrCreateQueryClient });
+ * const page = createNextPage({
+ *   getStackClient: async (queryClient) =>
+ *     getStackClientForRequest(queryClient, {
+ *       headers: new Headers(await headers()),
+ *     }),
+ *   getQueryClient: getOrCreateQueryClient,
+ * });
  * export default page.Page;
  * export const generateMetadata = page.generateMetadata;
  * ```
+ *
+ * Keep this request-aware catch-all under `app/(request)/pages`. Put SSG/ISR
+ * pages under `app/(static)/pages`; both groups retain `/pages/*` URLs. Their
+ * layouts should wrap the shared client provider from
+ * `app/pages/client-layout.tsx`, with request origins resolved only in the
+ * request group.
  */
 declare function createNextPage(options: CreateNextPageOptions): {
     Page: (pageProps: NextPageProps) => Promise<react_jsx_runtime.JSX.Element>;
@@ -88,7 +100,7 @@ declare function createNextPage(options: CreateNextPageOptions): {
  * ```tsx
  * import { nextRouter } from "@btst/stack/next";
  *
- * <StackProvider basePath="/pages" router={nextRouter()} api={{ baseURL, basePath: "/api/data" }}>
+ * <StackProvider stack={clientStack} router={nextRouter()}>
  * ```
  */
 declare function nextRouter(): StackRouterConfig;

package/dist/next/server.cjs

@@ -0,0 +1,7 @@
+'use strict';
+
+const layout = require('../packages/stack/src/next/layout.cjs');
+
+
+
+exports.createNextLayout = layout.createNextLayout;

package/dist/next/server.d.cts

@@ -0,0 +1,56 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ComponentType, ReactNode } from 'react';
+import { AnyAuthorizationContract, AuthorizationContractIdentity } from '../authorization/index.cjs';
+import { a as StackIdentity } from '../shared/stack.BYMentwB.cjs';
+import { M as MaybePromise } from '../shared/stack.CKXzdGiJ.cjs';
+import { H as HeadersFrameworkIdentitySource } from '../shared/stack.BSACE667.cjs';
+import 'zod';
+
+/** Props passed from a Next.js server layout to the generated client boundary. */
+interface NextClientLayoutProps<TIdentity extends StackIdentity> {
+    /** Validated request identity. `null` means the server resolved anonymous. */
+    initialIdentity: TIdentity | null;
+    /** Deployment-trusted API/site origins serialized for the client provider. */
+    clientOrigins?: {
+        /** Trusted destination for browser API requests. */
+        apiOrigin: string;
+        /** Trusted public origin used to build page and asset URLs. */
+        siteOrigin: string;
+    };
+    /** Nested route content rendered inside the client provider. */
+    children?: ReactNode;
+}
+/** Options for the request-aware Next.js identity layout factory. */
+interface CreateNextLayoutOptions<TContract extends AnyAuthorizationContract> {
+    /** Server-only identity adapter, normally returned by `createServerAuth`. */
+    auth: HeadersFrameworkIdentitySource<TContract>;
+    /** Client boundary that owns `StackProvider` for the complete route subtree. */
+    ClientLayout: ComponentType<NextClientLayoutProps<AuthorizationContractIdentity<TContract>>>;
+    /**
+     * Resolves deployment-trusted API/site origins from the original request
+     * headers. The returned browser-safe values are serialized with identity.
+     */
+    resolveClientOrigins?: (requestHeaders: Headers) => MaybePromise<{
+        apiOrigin: string;
+        siteOrigin: string;
+    }>;
+}
+/**
+ * Creates a Next.js App Router layout that resolves identity on the server and
+ * passes only the validated snapshot to a client-owned provider boundary.
+ *
+ * Import this helper from `@btst/stack/next/server` so `next/headers` and the
+ * application server auth module never enter the client graph.
+ * Because identity is resolved from request headers, the consuming layout must
+ * export `const dynamic = "force-dynamic"`. Keep SSG/ISR pages in a separate
+ * static route group with no server identity snapshot. This helper targets
+ * Next.js route-segment caching with Cache Components disabled.
+ */
+declare function createNextLayout<TContract extends AnyAuthorizationContract>(options: CreateNextLayoutOptions<TContract>): {
+    Layout: ({ children }: {
+        children?: ReactNode;
+    }) => Promise<react_jsx_runtime.JSX.Element>;
+};
+
+export { createNextLayout };
+export type { CreateNextLayoutOptions, NextClientLayoutProps };

package/dist/next/server.d.mts

@@ -0,0 +1,56 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ComponentType, ReactNode } from 'react';
+import { AnyAuthorizationContract, AuthorizationContractIdentity } from '../authorization/index.mjs';
+import { a as StackIdentity } from '../shared/stack.BYMentwB.mjs';
+import { M as MaybePromise } from '../shared/stack.CKXzdGiJ.mjs';
+import { H as HeadersFrameworkIdentitySource } from '../shared/stack.CskhFw3z.mjs';
+import 'zod';
+
+/** Props passed from a Next.js server layout to the generated client boundary. */
+interface NextClientLayoutProps<TIdentity extends StackIdentity> {
+    /** Validated request identity. `null` means the server resolved anonymous. */
+    initialIdentity: TIdentity | null;
+    /** Deployment-trusted API/site origins serialized for the client provider. */
+    clientOrigins?: {
+        /** Trusted destination for browser API requests. */
+        apiOrigin: string;
+        /** Trusted public origin used to build page and asset URLs. */
+        siteOrigin: string;
+    };
+    /** Nested route content rendered inside the client provider. */
+    children?: ReactNode;
+}
+/** Options for the request-aware Next.js identity layout factory. */
+interface CreateNextLayoutOptions<TContract extends AnyAuthorizationContract> {
+    /** Server-only identity adapter, normally returned by `createServerAuth`. */
+    auth: HeadersFrameworkIdentitySource<TContract>;
+    /** Client boundary that owns `StackProvider` for the complete route subtree. */
+    ClientLayout: ComponentType<NextClientLayoutProps<AuthorizationContractIdentity<TContract>>>;
+    /**
+     * Resolves deployment-trusted API/site origins from the original request
+     * headers. The returned browser-safe values are serialized with identity.
+     */
+    resolveClientOrigins?: (requestHeaders: Headers) => MaybePromise<{
+        apiOrigin: string;
+        siteOrigin: string;
+    }>;
+}
+/**
+ * Creates a Next.js App Router layout that resolves identity on the server and
+ * passes only the validated snapshot to a client-owned provider boundary.
+ *
+ * Import this helper from `@btst/stack/next/server` so `next/headers` and the
+ * application server auth module never enter the client graph.
+ * Because identity is resolved from request headers, the consuming layout must
+ * export `const dynamic = "force-dynamic"`. Keep SSG/ISR pages in a separate
+ * static route group with no server identity snapshot. This helper targets
+ * Next.js route-segment caching with Cache Components disabled.
+ */
+declare function createNextLayout<TContract extends AnyAuthorizationContract>(options: CreateNextLayoutOptions<TContract>): {
+    Layout: ({ children }: {
+        children?: ReactNode;
+    }) => Promise<react_jsx_runtime.JSX.Element>;
+};
+
+export { createNextLayout };
+export type { CreateNextLayoutOptions, NextClientLayoutProps };