@btst/stack 2.12.2 → 3.0.0-rc.2

package/README.md

@@ -62,7 +62,7 @@ You keep your codebase, database, and deployment.
 
 ---
 
-## Minimal usage
+## Minimal setup (Next.js)
 
 ```ts title="lib/stack.ts"
 import { stack } from "@btst/stack"
@@ -97,20 +97,55 @@ export const getStackClient = (queryClient: QueryClient) =>
   })
 ```
 
-Now you have a working blog with API, pages, SSR, and SEO. See the [full installation guide](https://www.better-stack.ai/docs/installation) for database adapters, auth hooks, and framework-specific setup.
+Use the v3 framework entry factories for the two catch-all routes:
 
-## Database schemas & migrations
+```ts title="app/api/data/[[...all]]/route.ts"
+import { toNextRouteHandlers } from "@btst/stack/next"
+import { handler } from "@/lib/stack"
 
-Optional CLI to generate schemas and run migrations from enabled plugins:
+export const { GET, POST, PUT, PATCH, DELETE } =
+  toNextRouteHandlers(handler)
+```
 
-```bash
-npm install -D @btst/cli
+```tsx title="app/pages/[[...all]]/page.tsx"
+import { createNextPage } from "@btst/stack/next"
+import { getStackClient } from "@/lib/stack-client"
+import { getOrCreateQueryClient } from "@/lib/query-client"
+
+const page = createNextPage({
+  getStackClient,
+  getQueryClient: getOrCreateQueryClient,
+})
+export default page.Page
+export const generateMetadata = page.generateMetadata
 ```
 
-Generate drizzle schema:
+Wrap the pages subtree with one `StackProvider`:
+
+```tsx
+<StackProvider
+  basePath="/pages"
+  router={nextRouter()}
+  api={{ baseURL, basePath: "/api/data" }}
+  auth={authProvider}
+  overrides={{ blog: { uploadImage } }}
+>
+  {children}
+</StackProvider>
+```
+
+Router, API, and auth services belong at the top level; plugin overrides contain
+only plugin-specific customization. See the [full installation guide](https://www.better-stack.ai/docs/installation)
+for QueryClient wiring, database adapters, all three frameworks, and auth.
+
+## Database schemas & migrations
+
+Generate schemas and run migrations through the v3 codegen CLI. It runs the
+aligned Better DB CLI in isolation, so its dependencies and `btst` binary do
+not enter your application graph:
 
 ```bash
-npx @btst/cli generate --orm drizzle --config lib/stack.ts --output db/schema.ts
+npx @btst/codegen@next generate --orm drizzle --config lib/stack.ts --output db/schema.ts
 ```
 
 Supports Prisma, Drizzle, MongoDB and Kysely SQL dialects.

package/dist/api/index.cjs

@@ -4,8 +4,23 @@ const betterCall = require('better-call');
 const db = require('@btst/db');
 const node = require('better-call/node');
 
+const identityResolvers = /* @__PURE__ */ new WeakMap();
+function registerIdentityResolver(request, auth) {
+  let cached;
+  identityResolvers.set(request.headers, () => {
+    cached ??= Promise.resolve().then(() => auth.getIdentity({ headers: request.headers, request })).then((identity) => identity ?? null).catch((error) => {
+      console.error("[btst/auth] getIdentity() failed:", error);
+      return null;
+    });
+    return cached;
+  });
+}
+async function getRequestIdentity(headers) {
+  const resolve = headers ? identityResolvers.get(headers) : void 0;
+  return resolve ? resolve() : null;
+}
 function stack(config) {
-  const { plugins, adapter, dbSchema, basePath } = config;
+  const { plugins, adapter, dbSchema, basePath, auth } = config;
   const allRoutes = {};
   let betterDbSchema = dbSchema ?? db.defineDb({});
   for (const [pluginKey, plugin] of Object.entries(plugins)) {
@@ -15,7 +30,8 @@ function stack(config) {
   const context = {
     plugins,
     basePath,
-    adapter: adapterInstance
+    adapter: adapterInstance,
+    auth
   };
   for (const [pluginKey, plugin] of Object.entries(plugins)) {
     const pluginRoutes = plugin.routes(adapterInstance, context);
@@ -33,8 +49,12 @@ function stack(config) {
   const router = betterCall.createRouter(allRoutes, {
     basePath
   });
+  const handler = auth ? (request) => {
+    registerIdentityResolver(request, auth);
+    return router.handler(request);
+  } : router.handler;
   return {
-    handler: router.handler,
+    handler,
     router,
     dbSchema: betterDbSchema,
     adapter: adapterInstance,
@@ -43,4 +63,5 @@ function stack(config) {
 }
 
 exports.toNodeHandler = node.toNodeHandler;
+exports.getRequestIdentity = getRequestIdentity;
 exports.stack = stack;

package/dist/api/index.d.cts

@@ -1,10 +1,36 @@
-import { g as PrefixedPluginRoutes, h as BackendLibConfig, i as BackendLib, j as PluginApis } from '../shared/stack.CQnwAN7x.cjs';
-export { B as BackendPlugin, S as StackContext } from '../shared/stack.CQnwAN7x.cjs';
+import { g as PrefixedPluginRoutes, h as BackendLibConfig, i as BackendLib, j as PluginApis } from '../shared/stack.CBsp9rDM.cjs';
+export { B as BackendPlugin, S as StackContext } from '../shared/stack.CBsp9rDM.cjs';
+import { b as StackIdentity } from '../shared/stack.C4_gEENS.cjs';
+export { C as CanParams, S as StackServerAuthProvider } from '../shared/stack.C4_gEENS.cjs';
 export { toNodeHandler } from 'better-call/node';
 import '@btst/yar';
 import '@btst/db';
 import 'better-call';
 
+/**
+ * Returns the identity of the request that carried these headers, as resolved
+ * by the `auth` provider configured on `stack()`.
+ *
+ * The provider's `getIdentity` runs at most once per request (memoized), no
+ * matter how many hooks call this. Returns `null` when no auth provider is
+ * configured, when called outside a request handled by `stack().handler`, or
+ * when the user is unauthenticated.
+ *
+ * @example
+ * ```ts
+ * import { getRequestIdentity } from "@btst/stack/api";
+ *
+ * const blogBackend = blogBackendPlugin({
+ *   hooks: {
+ *     onBeforeCreatePost: async (data, ctx) => {
+ *       const identity = await getRequestIdentity(ctx.headers);
+ *       if (!identity) throw new Error("Unauthorized");
+ *     },
+ *   },
+ * });
+ * ```
+ */
+declare function getRequestIdentity(headers: Headers | undefined): Promise<StackIdentity | null>;
 /**
  * Creates the backend library with plugin support
  *
@@ -27,4 +53,4 @@ import 'better-call';
  */
 declare function stack<TPlugins extends Record<string, any>, TRoutes extends PrefixedPluginRoutes<TPlugins> = PrefixedPluginRoutes<TPlugins>>(config: BackendLibConfig<TPlugins>): BackendLib<TRoutes, PluginApis<TPlugins>>;
 
-export { BackendLib, BackendLibConfig, PluginApis, stack };
+export { BackendLib, BackendLibConfig, PluginApis, StackIdentity, getRequestIdentity, stack };

package/dist/api/index.d.mts

@@ -1,10 +1,36 @@
-import { g as PrefixedPluginRoutes, h as BackendLibConfig, i as BackendLib, j as PluginApis } from '../shared/stack.CQnwAN7x.mjs';
-export { B as BackendPlugin, S as StackContext } from '../shared/stack.CQnwAN7x.mjs';
+import { g as PrefixedPluginRoutes, h as BackendLibConfig, i as BackendLib, j as PluginApis } from '../shared/stack.BL5PvShn.mjs';
+export { B as BackendPlugin, S as StackContext } from '../shared/stack.BL5PvShn.mjs';
+import { b as StackIdentity } from '../shared/stack.C4_gEENS.mjs';
+export { C as CanParams, S as StackServerAuthProvider } from '../shared/stack.C4_gEENS.mjs';
 export { toNodeHandler } from 'better-call/node';
 import '@btst/yar';
 import '@btst/db';
 import 'better-call';
 
+/**
+ * Returns the identity of the request that carried these headers, as resolved
+ * by the `auth` provider configured on `stack()`.
+ *
+ * The provider's `getIdentity` runs at most once per request (memoized), no
+ * matter how many hooks call this. Returns `null` when no auth provider is
+ * configured, when called outside a request handled by `stack().handler`, or
+ * when the user is unauthenticated.
+ *
+ * @example
+ * ```ts
+ * import { getRequestIdentity } from "@btst/stack/api";
+ *
+ * const blogBackend = blogBackendPlugin({
+ *   hooks: {
+ *     onBeforeCreatePost: async (data, ctx) => {
+ *       const identity = await getRequestIdentity(ctx.headers);
+ *       if (!identity) throw new Error("Unauthorized");
+ *     },
+ *   },
+ * });
+ * ```
+ */
+declare function getRequestIdentity(headers: Headers | undefined): Promise<StackIdentity | null>;
 /**
  * Creates the backend library with plugin support
  *
@@ -27,4 +53,4 @@ import 'better-call';
  */
 declare function stack<TPlugins extends Record<string, any>, TRoutes extends PrefixedPluginRoutes<TPlugins> = PrefixedPluginRoutes<TPlugins>>(config: BackendLibConfig<TPlugins>): BackendLib<TRoutes, PluginApis<TPlugins>>;
 
-export { BackendLib, BackendLibConfig, PluginApis, stack };
+export { BackendLib, BackendLibConfig, PluginApis, StackIdentity, getRequestIdentity, stack };

package/dist/api/index.d.ts

@@ -1,10 +1,36 @@
-import { g as PrefixedPluginRoutes, h as BackendLibConfig, i as BackendLib, j as PluginApis } from '../shared/stack.CQnwAN7x.js';
-export { B as BackendPlugin, S as StackContext } from '../shared/stack.CQnwAN7x.js';
+import { g as PrefixedPluginRoutes, h as BackendLibConfig, i as BackendLib, j as PluginApis } from '../shared/stack.BqTR6qi2.js';
+export { B as BackendPlugin, S as StackContext } from '../shared/stack.BqTR6qi2.js';
+import { b as StackIdentity } from '../shared/stack.C4_gEENS.js';
+export { C as CanParams, S as StackServerAuthProvider } from '../shared/stack.C4_gEENS.js';
 export { toNodeHandler } from 'better-call/node';
 import '@btst/yar';
 import '@btst/db';
 import 'better-call';
 
+/**
+ * Returns the identity of the request that carried these headers, as resolved
+ * by the `auth` provider configured on `stack()`.
+ *
+ * The provider's `getIdentity` runs at most once per request (memoized), no
+ * matter how many hooks call this. Returns `null` when no auth provider is
+ * configured, when called outside a request handled by `stack().handler`, or
+ * when the user is unauthenticated.
+ *
+ * @example
+ * ```ts
+ * import { getRequestIdentity } from "@btst/stack/api";
+ *
+ * const blogBackend = blogBackendPlugin({
+ *   hooks: {
+ *     onBeforeCreatePost: async (data, ctx) => {
+ *       const identity = await getRequestIdentity(ctx.headers);
+ *       if (!identity) throw new Error("Unauthorized");
+ *     },
+ *   },
+ * });
+ * ```
+ */
+declare function getRequestIdentity(headers: Headers | undefined): Promise<StackIdentity | null>;
 /**
  * Creates the backend library with plugin support
  *
@@ -27,4 +53,4 @@ import 'better-call';
  */
 declare function stack<TPlugins extends Record<string, any>, TRoutes extends PrefixedPluginRoutes<TPlugins> = PrefixedPluginRoutes<TPlugins>>(config: BackendLibConfig<TPlugins>): BackendLib<TRoutes, PluginApis<TPlugins>>;
 
-export { BackendLib, BackendLibConfig, PluginApis, stack };
+export { BackendLib, BackendLibConfig, PluginApis, StackIdentity, getRequestIdentity, stack };

package/dist/api/index.mjs

@@ -2,8 +2,23 @@ import { createRouter } from 'better-call';
 import { defineDb } from '@btst/db';
 export { toNodeHandler } from 'better-call/node';
 
+const identityResolvers = /* @__PURE__ */ new WeakMap();
+function registerIdentityResolver(request, auth) {
+  let cached;
+  identityResolvers.set(request.headers, () => {
+    cached ??= Promise.resolve().then(() => auth.getIdentity({ headers: request.headers, request })).then((identity) => identity ?? null).catch((error) => {
+      console.error("[btst/auth] getIdentity() failed:", error);
+      return null;
+    });
+    return cached;
+  });
+}
+async function getRequestIdentity(headers) {
+  const resolve = headers ? identityResolvers.get(headers) : void 0;
+  return resolve ? resolve() : null;
+}
 function stack(config) {
-  const { plugins, adapter, dbSchema, basePath } = config;
+  const { plugins, adapter, dbSchema, basePath, auth } = config;
   const allRoutes = {};
   let betterDbSchema = dbSchema ?? defineDb({});
   for (const [pluginKey, plugin] of Object.entries(plugins)) {
@@ -13,7 +28,8 @@ function stack(config) {
   const context = {
     plugins,
     basePath,
-    adapter: adapterInstance
+    adapter: adapterInstance,
+    auth
   };
   for (const [pluginKey, plugin] of Object.entries(plugins)) {
     const pluginRoutes = plugin.routes(adapterInstance, context);
@@ -31,8 +47,12 @@ function stack(config) {
   const router = createRouter(allRoutes, {
     basePath
   });
+  const handler = auth ? (request) => {
+    registerIdentityResolver(request, auth);
+    return router.handler(request);
+  } : router.handler;
   return {
-    handler: router.handler,
+    handler,
     router,
     dbSchema: betterDbSchema,
     adapter: adapterInstance,
@@ -40,4 +60,4 @@ function stack(config) {
   };
 }
 
-export { stack };
+export { getRequestIdentity, stack };

package/dist/client/components/index.d.cts

@@ -3,6 +3,7 @@ import React__default, { ErrorInfo } from 'react';
 import { FallbackProps } from 'react-error-boundary';
 export { FallbackProps } from 'react-error-boundary';
 import { createRouter } from '@btst/yar';
+import { C as CanParams } from '../../shared/stack.C4_gEENS.cjs';
 
 /**
  * Route type with optional components
@@ -38,10 +39,16 @@ declare function RouteRenderer({ router, path, NotFoundComponent, onNotFound, on
  * @param LoadingComponent - Component to show during suspense
  * @param onNotFound - Optional callback when route is not found
  * @param NotFoundComponent - Optional component to show for 404s
- * @param props - Additional props to pass to the page component
+ * @param props - Additional props to pass to the page component. For routes
+ *   created with `defineRoute`, these are merged after the route context, so
+ *   a prop named `params` or `query` intentionally takes precedence over the
+ *   router-extracted values. Only pass trusted, framework-controlled values.
  * @param onError - Error handler callback for the error boundary
+ * @param permission - Optional route-level permission requirement (e.g.
+ *   `{ resource: "blog:draft", action: "read" }`). Only enforced when an
+ *   auth provider is configured on `StackProvider`; see `RouteGuard`.
  */
-declare function ComposedRoute({ path, PageComponent, ErrorComponent, LoadingComponent, onNotFound, NotFoundComponent, props, onError, }: {
+declare function ComposedRoute({ path, PageComponent, ErrorComponent, LoadingComponent, onNotFound, NotFoundComponent, props, onError, permission, }: {
     path: string;
     PageComponent: React__default.ComponentType<any>;
     ErrorComponent?: React__default.ComponentType<FallbackProps>;
@@ -52,6 +59,7 @@ declare function ComposedRoute({ path, PageComponent, ErrorComponent, LoadingCom
     }>;
     props?: any;
     onError: (error: Error, info: ErrorInfo) => void;
+    permission?: CanParams;
 }): react_jsx_runtime.JSX.Element | undefined;
 
 /**

package/dist/client/components/index.d.mts

@@ -3,6 +3,7 @@ import React__default, { ErrorInfo } from 'react';
 import { FallbackProps } from 'react-error-boundary';
 export { FallbackProps } from 'react-error-boundary';
 import { createRouter } from '@btst/yar';
+import { C as CanParams } from '../../shared/stack.C4_gEENS.mjs';
 
 /**
  * Route type with optional components
@@ -38,10 +39,16 @@ declare function RouteRenderer({ router, path, NotFoundComponent, onNotFound, on
  * @param LoadingComponent - Component to show during suspense
  * @param onNotFound - Optional callback when route is not found
  * @param NotFoundComponent - Optional component to show for 404s
- * @param props - Additional props to pass to the page component
+ * @param props - Additional props to pass to the page component. For routes
+ *   created with `defineRoute`, these are merged after the route context, so
+ *   a prop named `params` or `query` intentionally takes precedence over the
+ *   router-extracted values. Only pass trusted, framework-controlled values.
  * @param onError - Error handler callback for the error boundary
+ * @param permission - Optional route-level permission requirement (e.g.
+ *   `{ resource: "blog:draft", action: "read" }`). Only enforced when an
+ *   auth provider is configured on `StackProvider`; see `RouteGuard`.
  */
-declare function ComposedRoute({ path, PageComponent, ErrorComponent, LoadingComponent, onNotFound, NotFoundComponent, props, onError, }: {
+declare function ComposedRoute({ path, PageComponent, ErrorComponent, LoadingComponent, onNotFound, NotFoundComponent, props, onError, permission, }: {
     path: string;
     PageComponent: React__default.ComponentType<any>;
     ErrorComponent?: React__default.ComponentType<FallbackProps>;
@@ -52,6 +59,7 @@ declare function ComposedRoute({ path, PageComponent, ErrorComponent, LoadingCom
     }>;
     props?: any;
     onError: (error: Error, info: ErrorInfo) => void;
+    permission?: CanParams;
 }): react_jsx_runtime.JSX.Element | undefined;
 
 /**

package/dist/client/components/index.d.ts

@@ -3,6 +3,7 @@ import React__default, { ErrorInfo } from 'react';
 import { FallbackProps } from 'react-error-boundary';
 export { FallbackProps } from 'react-error-boundary';
 import { createRouter } from '@btst/yar';
+import { C as CanParams } from '../../shared/stack.C4_gEENS.js';
 
 /**
  * Route type with optional components
@@ -38,10 +39,16 @@ declare function RouteRenderer({ router, path, NotFoundComponent, onNotFound, on
  * @param LoadingComponent - Component to show during suspense
  * @param onNotFound - Optional callback when route is not found
  * @param NotFoundComponent - Optional component to show for 404s
- * @param props - Additional props to pass to the page component
+ * @param props - Additional props to pass to the page component. For routes
+ *   created with `defineRoute`, these are merged after the route context, so
+ *   a prop named `params` or `query` intentionally takes precedence over the
+ *   router-extracted values. Only pass trusted, framework-controlled values.
  * @param onError - Error handler callback for the error boundary
+ * @param permission - Optional route-level permission requirement (e.g.
+ *   `{ resource: "blog:draft", action: "read" }`). Only enforced when an
+ *   auth provider is configured on `StackProvider`; see `RouteGuard`.
  */
-declare function ComposedRoute({ path, PageComponent, ErrorComponent, LoadingComponent, onNotFound, NotFoundComponent, props, onError, }: {
+declare function ComposedRoute({ path, PageComponent, ErrorComponent, LoadingComponent, onNotFound, NotFoundComponent, props, onError, permission, }: {
     path: string;
     PageComponent: React__default.ComponentType<any>;
     ErrorComponent?: React__default.ComponentType<FallbackProps>;
@@ -52,6 +59,7 @@ declare function ComposedRoute({ path, PageComponent, ErrorComponent, LoadingCom
     }>;
     props?: any;
     onError: (error: Error, info: ErrorInfo) => void;
+    permission?: CanParams;
 }): react_jsx_runtime.JSX.Element | undefined;
 
 /**

package/dist/client/index.cjs

@@ -4,6 +4,8 @@ const yar = require('@btst/yar');
 const sitemapUtils = require('../packages/stack/src/client/sitemap-utils.cjs');
 const metaUtils = require('../packages/stack/src/client/meta-utils.cjs');
 const pathUtils = require('../packages/stack/src/client/path-utils.cjs');
+const useListState = require('../packages/stack/src/client/hooks/use-list-state.cjs');
+const listState = require('../packages/stack/src/shared/list-state.cjs');
 
 function createStackClient(config) {
   const { plugins, basePath } = config;
@@ -42,4 +44,8 @@ function createStackClient(config) {
 exports.sitemapEntryToXmlString = sitemapUtils.sitemapEntryToXmlString;
 exports.metaElementsToObject = metaUtils.metaElementsToObject;
 exports.normalizePath = pathUtils.normalizePath;
+exports.useListState = useListState.useListState;
+exports.listStateParamKey = listState.listStateParamKey;
+exports.parseListStateFromSearchParams = listState.parseListStateFromSearchParams;
+exports.serializeListStateToSearchParams = listState.serializeListStateToSearchParams;
 exports.createStackClient = createStackClient;

package/dist/client/index.d.cts

@@ -1,8 +1,9 @@
-import { c as Sitemap, C as ClientPlugin, d as PluginRoutes, e as ClientLibConfig, f as ClientLib } from '../shared/stack.CQnwAN7x.cjs';
-export { b as ClientStackContext } from '../shared/stack.CQnwAN7x.cjs';
+import { c as Sitemap, C as ClientPlugin, d as PluginRoutes, e as ClientLibConfig, f as ClientLib } from '../shared/stack.CBsp9rDM.cjs';
+export { b as ClientStackContext } from '../shared/stack.CBsp9rDM.cjs';
 import '@btst/yar';
 import '@btst/db';
 import 'better-call';
+import '../shared/stack.C4_gEENS.cjs';
 
 /**
  * Converts an array of sitemap entries into an XML string following the sitemap.org protocol.
@@ -96,6 +97,65 @@ declare function metaElementsToObject(metaElements: Array<React.JSX.IntrinsicEle
  */
 declare function normalizePath(path?: string | Array<string> | undefined): string;
 
+type ListStateFieldType = "string" | "number" | "boolean";
+interface ListStateField<T extends ListStateFieldType = ListStateFieldType> {
+    type: T;
+    default: T extends "string" ? string : T extends "number" ? number : boolean;
+    /**
+     * How URL history is updated when this field changes.
+     * - `"push"` (default): discrete changes (tab switch, page change) — back button undoes.
+     * - `"replace"`: rapid changes (typing in a filter) — no extra history entries.
+     */
+    history?: "push" | "replace";
+}
+type ListStateSchema = Record<string, ListStateField>;
+type InferListStateValue<F extends ListStateField> = F["type"] extends "string" ? string : F["type"] extends "number" ? number : boolean;
+type InferListState<S extends ListStateSchema> = {
+    [K in keyof S]: InferListStateValue<S[K]>;
+};
+/**
+ * URL query param key for a list-state field.
+ * The `namespace` argument identifies the hook instance for SSR helpers but
+ * does not prefix URL keys — field names are used directly (e.g. `?tab=spam`).
+ */
+declare function listStateParamKey(_namespace: string, fieldKey: string): string;
+/**
+ * Parse list state from URL search params (SSR-safe — pass the request URL's
+ * search string or a `URLSearchParams` instance).
+ */
+declare function parseListStateFromSearchParams<S extends ListStateSchema>(namespace: string, schema: S, searchParams: URLSearchParams | string): InferListState<S>;
+/**
+ * Serialize list state into URL search params. Default values are omitted for
+ * clean URLs.
+ */
+declare function serializeListStateToSearchParams<S extends ListStateSchema>(namespace: string, schema: S, state: InferListState<S>, baseParams?: URLSearchParams): URLSearchParams;
+
+type SetListStateOptions = {
+    /** Force `replace` vs `push` history semantics for this update */
+    replace?: boolean;
+};
+type SetListState<S extends ListStateSchema> = (updates: Partial<InferListState<S>> | ((prev: InferListState<S>) => Partial<InferListState<S>>), options?: SetListStateOptions) => void;
+/**
+ * Sync list UI state (filters, tabs, pagination) with URL search params.
+ *
+ * Defaults are omitted from the URL. Field-level `history: "replace"` is used
+ * for rapid changes; discrete changes (tab/page) default to `push` so the back
+ * button undoes them.
+ *
+ * The `namespace` identifies this list state for SSR helpers; URL keys use
+ * the schema field names directly.
+ *
+ * @example
+ * ```tsx
+ * const [state, setState] = useListState("comments-moderation", {
+ *   tab: { type: "string", default: "pending" },
+ *   page: { type: "number", default: 1 },
+ * });
+ * // URL: ?tab=spam&page=3
+ * ```
+ */
+declare function useListState<S extends ListStateSchema>(namespace: string, schema: S): [InferListState<S>, SetListState<S>];
+
 /**
  * Creates the client library with plugin support
  *
@@ -145,4 +205,5 @@ declare function normalizePath(path?: string | Array<string> | undefined): strin
  */
 declare function createStackClient<TPlugins extends Record<string, ClientPlugin<any, any>>, TRoutes extends PluginRoutes<TPlugins> = PluginRoutes<TPlugins>>(config: ClientLibConfig<TPlugins>): ClientLib<TRoutes>;
 
-export { ClientLib, ClientLibConfig, ClientPlugin, createStackClient, metaElementsToObject, normalizePath, sitemapEntryToXmlString };
+export { ClientLib, ClientLibConfig, ClientPlugin, createStackClient, listStateParamKey, metaElementsToObject, normalizePath, parseListStateFromSearchParams, serializeListStateToSearchParams, sitemapEntryToXmlString, useListState };
+export type { InferListState, ListStateField, ListStateSchema, SetListState, SetListStateOptions };

package/dist/client/index.d.mts

@@ -1,8 +1,9 @@
-import { c as Sitemap, C as ClientPlugin, d as PluginRoutes, e as ClientLibConfig, f as ClientLib } from '../shared/stack.CQnwAN7x.mjs';
-export { b as ClientStackContext } from '../shared/stack.CQnwAN7x.mjs';
+import { c as Sitemap, C as ClientPlugin, d as PluginRoutes, e as ClientLibConfig, f as ClientLib } from '../shared/stack.BL5PvShn.mjs';
+export { b as ClientStackContext } from '../shared/stack.BL5PvShn.mjs';
 import '@btst/yar';
 import '@btst/db';
 import 'better-call';
+import '../shared/stack.C4_gEENS.mjs';
 
 /**
  * Converts an array of sitemap entries into an XML string following the sitemap.org protocol.
@@ -96,6 +97,65 @@ declare function metaElementsToObject(metaElements: Array<React.JSX.IntrinsicEle
  */
 declare function normalizePath(path?: string | Array<string> | undefined): string;
 
+type ListStateFieldType = "string" | "number" | "boolean";
+interface ListStateField<T extends ListStateFieldType = ListStateFieldType> {
+    type: T;
+    default: T extends "string" ? string : T extends "number" ? number : boolean;
+    /**
+     * How URL history is updated when this field changes.
+     * - `"push"` (default): discrete changes (tab switch, page change) — back button undoes.
+     * - `"replace"`: rapid changes (typing in a filter) — no extra history entries.
+     */
+    history?: "push" | "replace";
+}
+type ListStateSchema = Record<string, ListStateField>;
+type InferListStateValue<F extends ListStateField> = F["type"] extends "string" ? string : F["type"] extends "number" ? number : boolean;
+type InferListState<S extends ListStateSchema> = {
+    [K in keyof S]: InferListStateValue<S[K]>;
+};
+/**
+ * URL query param key for a list-state field.
+ * The `namespace` argument identifies the hook instance for SSR helpers but
+ * does not prefix URL keys — field names are used directly (e.g. `?tab=spam`).
+ */
+declare function listStateParamKey(_namespace: string, fieldKey: string): string;
+/**
+ * Parse list state from URL search params (SSR-safe — pass the request URL's
+ * search string or a `URLSearchParams` instance).
+ */
+declare function parseListStateFromSearchParams<S extends ListStateSchema>(namespace: string, schema: S, searchParams: URLSearchParams | string): InferListState<S>;
+/**
+ * Serialize list state into URL search params. Default values are omitted for
+ * clean URLs.
+ */
+declare function serializeListStateToSearchParams<S extends ListStateSchema>(namespace: string, schema: S, state: InferListState<S>, baseParams?: URLSearchParams): URLSearchParams;
+
+type SetListStateOptions = {
+    /** Force `replace` vs `push` history semantics for this update */
+    replace?: boolean;
+};
+type SetListState<S extends ListStateSchema> = (updates: Partial<InferListState<S>> | ((prev: InferListState<S>) => Partial<InferListState<S>>), options?: SetListStateOptions) => void;
+/**
+ * Sync list UI state (filters, tabs, pagination) with URL search params.
+ *
+ * Defaults are omitted from the URL. Field-level `history: "replace"` is used
+ * for rapid changes; discrete changes (tab/page) default to `push` so the back
+ * button undoes them.
+ *
+ * The `namespace` identifies this list state for SSR helpers; URL keys use
+ * the schema field names directly.
+ *
+ * @example
+ * ```tsx
+ * const [state, setState] = useListState("comments-moderation", {
+ *   tab: { type: "string", default: "pending" },
+ *   page: { type: "number", default: 1 },
+ * });
+ * // URL: ?tab=spam&page=3
+ * ```
+ */
+declare function useListState<S extends ListStateSchema>(namespace: string, schema: S): [InferListState<S>, SetListState<S>];
+
 /**
  * Creates the client library with plugin support
  *
@@ -145,4 +205,5 @@ declare function normalizePath(path?: string | Array<string> | undefined): strin
  */
 declare function createStackClient<TPlugins extends Record<string, ClientPlugin<any, any>>, TRoutes extends PluginRoutes<TPlugins> = PluginRoutes<TPlugins>>(config: ClientLibConfig<TPlugins>): ClientLib<TRoutes>;
 
-export { ClientLib, ClientLibConfig, ClientPlugin, createStackClient, metaElementsToObject, normalizePath, sitemapEntryToXmlString };
+export { ClientLib, ClientLibConfig, ClientPlugin, createStackClient, listStateParamKey, metaElementsToObject, normalizePath, parseListStateFromSearchParams, serializeListStateToSearchParams, sitemapEntryToXmlString, useListState };
+export type { InferListState, ListStateField, ListStateSchema, SetListState, SetListStateOptions };