@webjsdev/server 0.9.0 → 0.10.1

package/index.d.ts

@@ -34,6 +34,13 @@ export * from './src/testing.js';
 
 /** A webjs middleware: receives the request + a `next()` continuation. */
 export type Middleware = (req: Request, next: () => Promise<Response>) => Promise<Response> | Response;
+/**
+ * The request an app's `middleware.ts` / `proxy.ts` (and a segment middleware)
+ * receives: the platform `Request` plus Next's `request.cookies`, the same
+ * store `cookies()` returns. Annotate with it where Next.js code writes
+ * `NextRequest`.
+ */
+export type MiddlewareRequest = Request & { readonly cookies: MiddlewareRequestCookies };
 
 // `Handle` is re-exported from ./src/testing.js (the `export *` above), so it
 // is not re-declared here. It is IMPORTED as well, because `export *` re-exports
@@ -45,16 +52,49 @@ export type Middleware = (req: Request, next: () => Promise<Response>) => Promis
  * Mirrors AGENTS.md's documented shape; `@webjsdev/core` does not export it,
  * so it is defined here (the one server-owned shared type).
  */
-export type ActionResult<T = unknown> =
-  | { success: true; data?: T; redirect?: string }
+export type ActionResult<T = any> =
+  | {
+      success: true;
+      data?: T;
+      redirect?: string;
+      message?: string;
+      // The failure fields, absent here, so a read before narrowing on
+      // `success` (`result.error ?? result.fieldErrors?.body`) type-checks.
+      error?: undefined;
+      errors?: undefined;
+      fieldErrors?: undefined;
+      values?: undefined;
+      status?: undefined;
+    }
   | {
       success: false;
       error?: string;
+      /** Next.js's `{ errors }` spelling, read as a failure like `fieldErrors`. */
+      errors?: Record<string, string | string[]>;
+      message?: string;
       fieldErrors?: Record<string, string>;
       values?: Record<string, string>;
       status?: number;
     };
 
+/**
+ * What a form-bound action receives: a real `FormData` (so `get`, `getAll` and
+ * `instanceof FormData` work, as in Next) that also carries each field as a
+ * property, so `input.title` reads it too. A `name[]` field arrives as an array
+ * under `name`; a file input arrives as a `File`. Pass the field shape for
+ * typed property reads.
+ *
+ * @example
+ * 'use server';
+ * import type { FormInput } from '@webjsdev/server';
+ * export async function createTask(input: FormInput<{ title: string; tags: string[] }>) {
+ *   const title = input.title.trim();          // or input.get('title')
+ *   ...
+ * }
+ */
+export type FormInput<Fields extends Record<string, unknown> = Record<string, string | string[] | File>> =
+  FormData & Fields;
+
 /** The pluggable cache store interface (`memoryStore` / `redisStore` / custom). */
 export interface CacheStore {
   get(key: string): Promise<string | null>;
@@ -165,6 +205,21 @@ export interface ServerHandle {
  * Create an embeddable request handler. Returns `{ handle, rebuild, routeFor,
  * warmup, getRouteTable, appDir, dev, logger }`. Throws at boot on an
  * unsupported Node version or a failed `env.{js,ts}` validation.
+ *
+ * @example
+ * ```ts
+ * // test/home.test.ts, run with `webjs test`: the whole pipeline, no server, no network
+ * import { test } from 'node:test';
+ * import assert from 'node:assert/strict';
+ * import { createRequestHandler } from '@webjsdev/server';
+ *
+ * test('the home page renders', async () => {
+ *   const app = await createRequestHandler({ appDir: process.cwd() });
+ *   const res = await app.handle(new Request('http://localhost/'));
+ *   assert.equal(res.status, 200);
+ *   assert.match(await res.text(), /<h1/);
+ * });
+ * ```
  */
 export declare function createRequestHandler(opts: RequestHandlerOptions): Promise<RequestHandler>;
 
@@ -197,7 +252,25 @@ export declare function assertNodeVersion(opts?: {
 // env-schema.js (#236)
 // ---------------------------------------------------------------------------
 
-/** Pure env validator: check an env object against a schema or validator function. */
+/**
+ * Pure env validator: check an env object against a schema or validator function.
+ *
+ * @example
+ * ```ts
+ * // env.ts at the app root: WebJs runs validateEnv(schema, process.env) at boot
+ * // and refuses to start, listing every missing or invalid variable at once.
+ * export default {
+ *   DATABASE_URL: 'url',
+ *   AUTH_SECRET: { type: 'string', minLength: 32 },
+ *   PORT: { type: 'number', default: 3000 },           // a default makes it optional
+ *   NODE_ENV: { type: 'enum', values: ['development', 'production', 'test'] },
+ * };
+ *
+ * // Calling it yourself (a test, a script) returns the verdict instead of throwing:
+ * import { validateEnv } from '@webjsdev/server';
+ * const { ok, errors } = validateEnv({ API_KEY: 'string' }, process.env);
+ * ```
+ */
 export declare function validateEnv(
   schema: object | ((env: Record<string, string | undefined>) => void),
   env: Record<string, string | undefined>,
@@ -248,6 +321,14 @@ export declare function matchApi(
   table: unknown,
   pathname: string,
 ): { route: { file: string }; params: Record<string, string> } | null;
+/**
+ * The URL paths of every STATIC page route in a route table, sorted and
+ * deduped. Dynamic routes are excluded (listing one would mean inventing
+ * param values).
+ */
+export declare function staticPageRoutes(table: {
+  pages?: Array<{ routeDir?: string; paramNames?: string[] }>;
+} | undefined): string[];
 
 // ---------------------------------------------------------------------------
 // route-types.js (#258)
@@ -315,6 +396,22 @@ export declare function invokeAction(
  * optional boundary validator, and dispatches through the request abort signal
  * + the optional middleware chain. The always-works baseline is a hand-written
  * `route.ts` that imports and calls the action; this is the convenience.
+ *
+ * @example
+ * ```ts
+ * // app/api/posts/[id]/route.ts: GET /api/posts/7 calls getPost({ id: '7' })
+ * import { route } from '@webjsdev/server';
+ * import { getPost } from '#modules/posts/actions/get-post.server.ts';       // 'use server' actions
+ * import { updatePost } from '#modules/posts/actions/update-post.server.ts';
+ *
+ * export const GET = route(getPost);        // the result is sent as JSON, a returned Response as is
+ * export const PUT = route(updatePost, {    // the JSON body merges into the same input object
+ *   validate: (input) => {
+ *     if (typeof input.title !== 'string') throw new Error('title is required');  // a throw answers 400
+ *     return { id: String(input.id), title: input.title };
+ *   },
+ * });
+ * ```
  */
 export declare function route<A, R>(
   action: (input: A, ctx: { req: Request; params: Record<string, string> }) => R | Promise<R>,
@@ -342,8 +439,7 @@ export declare function setVendorEntries(
 /**
  * Bare-specifier npm imports an app could load in the browser, found by walking
  * the module graph from every browser-bound entry rather than by scanning the
- * directory. Applies no elision pruning, so the result is a superset of what the
- * running server serves.
+ * directory. The result is a superset of what the running server serves.
  */
 export declare function scanBareImports(dir: string): Promise<Set<string>>;
 /** Extract the package name from an import specifier (`dayjs/plugin/utc` -> `dayjs`). */
@@ -492,8 +588,8 @@ export declare function extractComponents(src: string): Array<{ className: strin
  * because there is no registration call anywhere or because the tag is
  * computed. The registration cross-reference is app-wide, so a class a sibling
  * module registers is not an orphan. Neither is visible to the
- * scanner, so both always lose the elision verdict, the tag-to-module registry
- * entry, and the preload hint; assume the element does not upgrade either.
+ * scanner, so both always lose the tag-to-module registry entry, the boot import
+ * and the preload hint; assume the element does not upgrade either.
  * This is about REGISTRATION, never about import reachability. The full
  * semantics, including the one case where a computed tag still upgrades, live
  * on `findOrphanComponents` in `src/component-scanner.js`.
@@ -503,75 +599,53 @@ export declare function findOrphanComponents(
 ): Promise<Array<{ className: string; file: string }>>;
 
 // ---------------------------------------------------------------------------
-// elision-report.js (#646, #1308)
+// route-report.js (#1686)
 // ---------------------------------------------------------------------------
 
-/** Which rule in the analyser forced a component to ship. First match wins. */
-export type ElisionEvidence = 'own' | 'observed' | 'closure' | 'render' | 'import' | 'unreadable';
-
-/** One component module's verdict. `evidence` / `reason` / `by` are null when elided. */
-export interface ElisionComponentRow {
-  /** App-relative path of the component module. */
-  file: string;
-  /** Every tag this file registers, sorted. */
-  tags: string[];
-  verdict: 'elided' | 'shipped';
-  evidence: ElisionEvidence | null;
-  reason: string | null;
-  /** App-relative path of the module that forced the ship, where one did. */
-  by: string | null;
-}
-
-/** One page/layout route module's verdict. */
-export interface ElisionRouteModuleRow {
+/**
+ * One route module (page, layout or boundary). A route module never ships to
+ * the browser; the boot imports `emits`, its component frontier, in its place.
+ */
+export interface RouteModuleRow {
   file: string;
-  verdict: 'inert' | 'import-only' | 'shipped';
-  /** For `import-only`: the component modules the boot emits in its place. */
+  kind: 'page' | 'layout' | 'error' | 'loading' | 'not-found' | 'forbidden' | 'unauthorized' | 'global-not-found';
+  /** The component modules the boot imports in this module's place (empty: zero JS). */
   emits: string[];
-  /** For `shipped`: the first client-effecting blocker, or null when its own code is the cause. */
-  blocker: string | null;
-  reason: string | null;
+  /** Advisory notes on code that looks meant for the browser but runs only on the server. */
+  hints: string[];
 }
 
 /** A `class X extends WebComponent` with no literal-tag registration. */
-export interface ElisionOrphanRow {
+export interface OrphanRow {
   file: string;
   className: string;
 }
 
-export interface ElisionSummary {
-  components: number;
-  elided: number;
-  shipped: number;
+export interface RouteReportSummary {
   routeModules: number;
-  inert: number;
-  importOnly: number;
-  shippedWhole: number;
+  /** Route modules whose frontier is empty: the browser loads nothing for them. */
+  zeroJs: number;
+  /** Route modules whose frontier names at least one component. */
+  carriers: number;
   orphans: number;
 }
 
-/** The whole app-level elision verdict. Every path is app-relative; every array is sorted by `file`. */
-export interface ElisionReport {
+/** What each route costs the browser. Every path is app-relative; every array is sorted by `file`. */
+export interface RouteReport {
   analysed: boolean;
   /** Why nothing was analysed, when `analysed` is false. */
-  skipped: 'no-app' | 'elide-off' | 'unanalysable' | null;
-  components: ElisionComponentRow[];
-  routeModules: ElisionRouteModuleRow[];
-  orphans: ElisionOrphanRow[];
-  summary: ElisionSummary;
+  skipped: 'no-app' | 'unanalysable' | null;
+  routeModules: RouteModuleRow[];
+  orphans: OrphanRow[];
+  summary: RouteReportSummary;
 }
 
 /**
- * App-level elision report, BOTH directions (#646, #1308): every component
- * module as elided or shipped (a shipped one naming the evidence and the module
- * that forced it), every page/layout as inert / import-only / shipped (a
- * shipped one naming the first client-effecting blocker), and every orphan
- * component class that gets no verdict at all. A reporting layer over
- * `analyzeElision`, never a second analysis and never a build artifact.
- * Consumed by `webjs elision`, the MCP `list_elision` tool, and both `webjs
- * doctor` elision checks.
+ * Every route module with the components the boot loads in its place and any
+ * hints about browser-looking code in it, plus every orphan component class.
+ * Consumed by both `webjs doctor` route checks.
  */
-export declare function analyzeAppElision(appDir: string): Promise<ElisionReport>;
+export declare function analyzeRouteModules(appDir: string): Promise<RouteReport>;
 
 // ---------------------------------------------------------------------------
 // dev-regenerate.js (#967, #1672)
@@ -615,39 +689,82 @@ export declare function regenerateStatus(
 ): Promise<Array<{ output: string; command: string; state: RegenerateState }>>;
 
 // ---------------------------------------------------------------------------
-// elision-differential.js (#1308)
+// context.js (per-request context helpers)
 // ---------------------------------------------------------------------------
 
 /**
- * Mask the JS-loaded set (importmap, boot script, modulepreload hints, vendor
- * connection hints, content stamps) out of an SSR response so a diff sees only
- * observable output. The ONE definition shared by the framework's own
- * differential guard and `webjs elision --verify`, so an app can diff its own
- * two captures with exactly the framework's comparator.
+ * The in-flight request's headers, read-only as Next.js's `ReadonlyHeaders`:
+ * `set`, `append` and `delete` throw at runtime and are absent from the type.
  */
-export declare function maskJsSet(html: string): string;
-
+export type ReadonlyHeaders = Omit<Headers, 'set' | 'append' | 'delete'>;
+/** Read-only headers for the in-flight request. Throws outside a request scope. */
+export declare function headers(): ReadonlyHeaders;
+/** A cookie as read from the request. */
+export interface RequestCookie { name: string; value: string }
+/** A cookie to write (Next's `ResponseCookie`; `maxAge` in seconds, `path` defaults to `/`). */
+export interface ResponseCookie {
+  name: string;
+  value: string;
+  expires?: Date | number;
+  maxAge?: number;
+  domain?: string;
+  path?: string;
+  secure?: boolean;
+  httpOnly?: boolean;
+  sameSite?: 'lax' | 'strict' | 'none' | 'Lax' | 'Strict' | 'None' | boolean;
+  partitioned?: boolean;
+  priority?: 'low' | 'medium' | 'high';
+}
+/** The request's cookie store (Next.js's `cookies()` shape). */
 /**
- * The URL paths of every STATIC page route in a `buildRouteTable` result,
- * sorted and deduped. Dynamic routes are excluded (rendering one would mean
- * inventing param values).
+ * Next.js's `RequestCookies`, `request.cookies` in middleware and a route
+ * handler. Reads are the request's cookies; `set`, `delete` and `clear` change
+ * what the rest of this request reads (the page's `cookies()` included) and
+ * send nothing to the browser. Set a response cookie with `cookies().set()`.
  */
-export declare function staticPageRoutes(table: {
-  pages?: Array<{ routeDir?: string; paramNames?: string[] }>;
-}): string[];
-
-// ---------------------------------------------------------------------------
-// context.js (per-request context helpers)
-// ---------------------------------------------------------------------------
-
-/** Read-only headers for the in-flight request. Throws outside a request scope. */
-export declare function headers(): Headers;
-/** Read-only cookie jar for the in-flight request. Throws outside a request scope. */
-export declare function cookies(): {
-  get(name: string): string | undefined;
+export interface MiddlewareRequestCookies {
+  get(name: string | { name: string }): RequestCookie | undefined;
+  getAll(name?: string | { name: string }): RequestCookie[];
   has(name: string): boolean;
-  entries(): [string, string][];
-};
+  readonly size: number;
+  set(name: string, value: string): MiddlewareRequestCookies;
+  set(cookie: RequestCookie): MiddlewareRequestCookies;
+  delete(names: string): boolean;
+  delete(names: string[]): boolean[];
+  clear(): MiddlewareRequestCookies;
+  toString(): string;
+  [Symbol.iterator](): IterableIterator<[string, RequestCookie]>;
+}
+export interface RequestCookies {
+  get(name: string | { name: string }): RequestCookie | undefined;
+  getAll(name?: string | { name: string }): RequestCookie[];
+  has(name: string): boolean;
+  readonly size: number;
+  set(name: string, value: string, options?: Omit<ResponseCookie, 'name' | 'value'>): RequestCookies;
+  set(cookie: ResponseCookie): RequestCookies;
+  /** Expire a cookie. Pass the `path` / `domain` it was set with, or the browser keeps it. */
+  delete(name: string, options?: Omit<ResponseCookie, 'name' | 'value' | 'expires' | 'maxAge'>): RequestCookies;
+  delete(cookie: { name: string; path?: string; domain?: string }): RequestCookies;
+  toString(): string;
+  [Symbol.iterator](): IterableIterator<[string, RequestCookie]>;
+}
+/**
+ * The in-flight request's cookies, Next.js's `cookies()`: `cookies().get('x')?.value`
+ * reads, `set` / `delete` write a `Set-Cookie` onto this request's response. Also
+ * awaitable (`(await cookies()).get('x')`). Throws outside a request scope.
+ *
+ * `get` returns a {@link RequestCookie} (`{ name, value }`) or `undefined`, as
+ * in Next.js, never the bare string.
+ *
+ * @example
+ * ```ts
+ * import { cookies } from '@webjsdev/server';
+ * const theme: string = cookies().get('theme')?.value ?? 'light';
+ * cookies().set('theme', 'dark', { path: '/', maxAge: 60 * 60 * 24 * 365, httpOnly: true });
+ * cookies().delete('theme');
+ * ```
+ */
+export declare function cookies(): RequestCookies & Promise<RequestCookies>;
 /** The raw `Request` for the in-flight scope, or null at module top-level. */
 export declare function getRequest(): Request | null;
 /** Run `fn` within a request scope. */
@@ -668,7 +785,18 @@ export declare function defaultLogger(opts?: { dev?: boolean }): Logger;
 // rate-limit.js
 // ---------------------------------------------------------------------------
 
-/** Build a rate-limit middleware `(req, next) => Response`. */
+/**
+ * Build a rate-limit middleware `(req, next) => Response`.
+ *
+ * @example
+ * ```ts
+ * // app/api/auth/middleware.ts: 10 requests a minute per client on every /api/auth route
+ * import { rateLimit } from '@webjsdev/server';
+ * export default rateLimit({ window: '1m', max: 10 });   // over it answers 429 + retry-after
+ * // Behind Cloudflare, key on the visitor rather than the edge:
+ * // rateLimit({ window: '1m', max: 10, trustProxy: true, clientIpHeader: 'cf-connecting-ip' })
+ * ```
+ */
 export declare function rateLimit(opts?: {
   window?: number | string;
   max?: number;
@@ -715,6 +843,19 @@ export declare function parseWindow(w: number | string): number;
  * whenever a CDN sits in front: the default chain's leftmost
  * `X-Forwarded-For` entry is then the CDN's egress address rather than the
  * visitor.
+ *
+ * @example
+ * ```ts
+ * // app/api/votes/route.ts: one vote per client address
+ * import { clientIp } from '@webjsdev/server';
+ * import { recordVote } from '#modules/votes/queries/record-vote.server.ts';
+ *
+ * export async function POST(req: Request) {
+ *   const ip = clientIp(req);   // the socket peer, never a client-sent header
+ *   // Behind Cloudflare: clientIp(req, { trustProxy: true, header: 'cf-connecting-ip' })
+ *   return Response.json({ counted: await recordVote(ip) });
+ * }
+ * ```
  */
 export declare function clientIp(
   req: Request,
@@ -740,7 +881,22 @@ export interface CorsOptions {
   maxAge?: number;
 }
 
-/** Build a CORS middleware `(req, next) => Response`. */
+/**
+ * Build a CORS middleware `(req, next) => Response`.
+ *
+ * @example
+ * ```ts
+ * // app/api/public/middleware.ts: CORS for every route.ts under /api/public,
+ * // the OPTIONS preflight answered for you
+ * import { cors } from '@webjsdev/server';
+ *
+ * export default cors({
+ *   origin: ['https://app.example.com', /\.example\.com$/],   // or '*' for a public, cookie-free API
+ *   credentials: true,                                        // needs a listed origin, never '*'
+ *   maxAge: 600,                                              // preflight cache, in seconds
+ * });
+ * ```
+ */
 export declare function cors(options?: CorsOptions): Middleware;
 /** Resolve the allowed origin for a request given a policy (shared CORS core). */
 export declare function resolveOrigin(
@@ -772,6 +928,21 @@ export declare function setStore(store: CacheStore): void;
  * Wrap an async function with TTL caching. Preserves the wrapped signature and
  * adds an `invalidate()` member. `tags` (static `string[]` or a per-arg
  * `(...args) => string[]`) enable `revalidateTag` cross-module eviction.
+ *
+ * @example
+ * ```ts
+ * // modules/posts/queries/get-post.server.ts
+ * import { cache } from '@webjsdev/server';
+ * import { eq } from 'drizzle-orm';
+ * import { db } from '#db/connection.server.ts';
+ * import { posts } from '#db/schema.server.ts';
+ *
+ * export const getPost = cache(
+ *   async (id: number) => (await db.select().from(posts).where(eq(posts.id, id)).limit(1))[0],
+ *   { key: 'post', ttl: 300, tags: (id) => ['post:' + id] },   // ttl in seconds, default 60
+ * );
+ * // A write elsewhere evicts just that id: await revalidateTag('post:' + id)
+ * ```
  */
 export declare function cache<T extends (...args: any[]) => Promise<any>>(
   fn: T,
@@ -786,8 +957,27 @@ export declare function cache<T extends (...args: any[]) => Promise<any>>(
 // cache-tags.js (#242) + html-cache.js (#241): server cache invalidation
 // ---------------------------------------------------------------------------
 
-/** Evict every `cache()` entry tagged with `tag`. */
-export declare function revalidateTag(tag: string): Promise<void>;
+/**
+ * Evict every `cache()` entry tagged with `tag`. Takes Next.js 16's second
+ * argument, `revalidateTag(tag, 'max')` (a cache-life profile, or
+ * `{ expire }`), for source compatibility: WebJs evicts at once whatever the
+ * profile, since `cache()` has no stale-while-revalidate window to honour.
+ *
+ * @example
+ * ```ts
+ * // modules/posts/actions/rename-post.server.ts
+ * 'use server';
+ * import { revalidateTag } from '@webjsdev/server';
+ * import { updatePostTitle } from '../queries/update-post-title.server.ts';
+ *
+ * export async function renamePost(input: { id: number; title: string }) {
+ *   await updatePostTitle(input.id, input.title);
+ *   await revalidateTag('post:' + input.id);   // every cache() read tagged 'post:<id>' recomputes
+ *   return { success: true };
+ * }
+ * ```
+ */
+export declare function revalidateTag(tag: string, profile?: string | { expire?: number }): Promise<void>;
 /** Evict every `cache()` entry tagged with any of `tags`. */
 export declare function revalidateTags(tags: string[]): Promise<void>;
 /**
@@ -800,7 +990,7 @@ export declare function revalidateTags(tags: string[]): Promise<void>;
  * `webjs.basePath` the absolute url is the PUBLIC one and its mount prefix is
  * stripped, so it evicts the entry the write actually stored.
  */
-export declare function revalidatePath(path: string): Promise<void>;
+export declare function revalidatePath(path: string, type?: 'page' | 'layout'): Promise<void>;
 /** Evict all cached HTML (per-process generation bump). */
 export declare function revalidateAll(): Promise<void>;
 
@@ -826,12 +1016,34 @@ export declare class Session {
   set(key: string, value: unknown): void;
   has(key: string): boolean;
   unset(key: string): void;
-  /** Set a value readable once on the next request, then cleared. */
+  /** Set a value that lasts until a `get()` reads it (Remix's flash); `has()` does not consume it. */
   flash(key: string, value: unknown): void;
   destroy(): void;
+  /**
+   * Give the session a new id, keeping its data. Call it after a login to
+   * prevent session fixation; `deleteOld` also deletes the old id's stored data.
+   */
+  regenerateId(deleteOld?: boolean): void;
 }
 
-/** Session middleware factory. */
+/**
+ * Session middleware factory: a signed session cookie for apps that do not use
+ * `createAuth`. It throws at import without `secret` or `SESSION_SECRET`.
+ *
+ * @example
+ * ```ts
+ * // middleware.ts
+ * import { session } from '@webjsdev/server';
+ * export default session({ secret: process.env.SESSION_SECRET });
+ *
+ * // In a 'use server' action or a page:
+ * import { getRequest, getSession } from '@webjsdev/server';
+ * const s = getSession(getRequest()!);
+ * s.regenerateId(true);       // after a login, against session fixation
+ * s.set('userId', user.id);
+ * const userId = s.get<string>('userId');
+ * ```
+ */
 export declare function session(opts?: {
   storage?: SessionStorage;
   cookieName?: string;
@@ -850,14 +1062,50 @@ export declare function storeSessionStorage(opts?: Record<string, unknown>): Ses
 export declare const cookieSession: typeof cookieSessionStorage;
 /** Alias of `storeSessionStorage`. */
 export declare const storeSession: typeof storeSessionStorage;
-/** Read the session for a request (after the session middleware ran). */
-export declare function getSession(req: Request): Session;
+/**
+ * The session for the current request. With no argument it reads the request
+ * in scope (as `cookies()` and `headers()` do); passing `getRequest()` also works.
+ * Needs `session()` as root middleware; throws outside it.
+ *
+ * @example
+ * ```ts
+ * // middleware.ts
+ * import { session } from '@webjsdev/server';
+ * export default session();             // SESSION_SECRET from .env
+ *
+ * // in a page, action or route handler
+ * import { getSession } from '@webjsdev/server';
+ * const s = getSession();
+ * s.set('cart', [1, 2]);                // persists across requests
+ * s.flash('notice', 'Saved');           // read once by the next request
+ * const notice = s.get('notice');       // unknown; narrow it before use
+ * ```
+ */
+export declare function getSession(req?: Request | null): Session;
 
 // ---------------------------------------------------------------------------
 // broadcast.js
 // ---------------------------------------------------------------------------
 
-/** Broadcast data to all WebSocket clients connected to a route path. */
+/**
+ * Broadcast data to all WebSocket clients connected to a route path.
+ *
+ * @example
+ * ```ts
+ * // app/api/chat/route.ts: each socket that connects here is registered under '/api/chat'
+ * import { broadcast } from '@webjsdev/server';
+ *
+ * type Socket = { on(event: 'message', cb: (data: Buffer) => void): void };   // or ws's own WebSocket type
+ * export function WS(ws: Socket) {
+ *   ws.on('message', (data) => broadcast('/api/chat', data.toString(), { except: ws }));
+ * }
+ * // A 'use server' action can push to the same sockets after a write:
+ * // broadcast('/api/chat', JSON.stringify({ kind: 'joined', name }))
+ * ```
+ * The path is the connected URL's pathname, so a dynamic route broadcasts to
+ * its concrete path (`'/api/rooms/' + params.roomId`). One process only: fan out
+ * across instances yourself (Redis pub/sub).
+ */
 export declare function broadcast(
   path: string,
   data: string | Uint8Array,
@@ -868,9 +1116,14 @@ export declare function broadcast(
 // file-storage.js (#247)
 // ---------------------------------------------------------------------------
 
-/** A streaming handle returned by `FileStore.get` (body is a stream, never buffered). */
+/**
+ * A streaming handle returned by `FileStore.get` (body is a stream, never
+ * buffered). The body is a web `ReadableStream`, so `new Response(file.body)`
+ * serves it as is; an adapter whose SDK returns a Node stream converts it with
+ * `Readable.toWeb`.
+ */
 export interface StoredObjectHandle {
-  body: ReadableStream | import('node:stream').Readable;
+  body: ReadableStream<Uint8Array>;
   size: number;
   contentType: string;
 }
@@ -900,22 +1153,117 @@ export interface FileStore {
 
 /** The default uploads directory (relative to cwd), gitignore-friendly. */
 export declare const DEFAULT_UPLOAD_DIR: string;
-/** Local-disk file store (the default adapter). Streams writes. */
+/**
+ * Local-disk file store (the default adapter). Streams writes.
+ *
+ * @example
+ * ```ts
+ * // instrumentation.ts at the app root: register() runs once at boot
+ * import { setFileStore, diskStore } from '@webjsdev/server';
+ *
+ * export function register() {
+ *   // Defaults: dir '<cwd>/.webjs/uploads', baseUrl '/uploads'. url(key) is baseUrl + '/' + key,
+ *   // and nothing serves it for you: add the route.ts at that path (see verifySignedUrl).
+ *   setFileStore(diskStore({ dir: '/var/data/uploads', baseUrl: '/files' }));
+ * }
+ * ```
+ */
 export declare function diskStore(opts?: { dir?: string; baseUrl?: string }): FileStore;
-/** Set the default file store (call at startup to use a custom dir or S3). */
+/**
+ * Set the default file store (call at startup to use a custom dir or S3).
+ *
+ * @example
+ * ```ts
+ * // instrumentation.ts at the app root: every getFileStore() call follows the swap
+ * import { setFileStore, diskStore } from '@webjsdev/server';
+ * import { r2Store } from '#lib/r2-store.server.ts';   // your adapter: put, get, delete, url
+ *
+ * export function register() {
+ *   setFileStore(process.env.R2_BUCKET ? r2Store(process.env.R2_BUCKET) : diskStore());
+ * }
+ * ```
+ */
 export declare function setFileStore(store: FileStore): void;
-/** Get the default file store (`diskStore` under `<cwd>/.webjs/uploads` unless set). */
+/**
+ * Get the default file store (`diskStore` under `<cwd>/.webjs/uploads` unless set).
+ *
+ * @example
+ * ```ts
+ * // In a 'use server' action bound to <form action=${save} enctype="multipart/form-data">
+ * // with <input type="file" name="photo">: the field arrives as a File.
+ * import { getFileStore, generateKey } from '@webjsdev/server';
+ * const key = generateKey(input.photo.name);   // opaque, traversal-safe
+ * await getFileStore().put(key, input.photo);  // streams to disk
+ *
+ * // app/uploads/[key]/route.ts serves it back:
+ * export async function GET(_req: Request, { params }: { params: { key: string } }) {
+ *   let file;
+ *   try { file = await getFileStore().get(params.key); } catch { file = null; } // an unsafe key throws
+ *   if (!file) return new Response('Not found', { status: 404 });
+ *   return new Response(file.body, { headers: { 'content-type': file.contentType } });
+ * }
+ * ```
+ */
 export declare function getFileStore(): FileStore;
-/** Generate a random, opaque, traversal-safe key, preserving a whitelisted extension. */
+/**
+ * Generate a random, opaque, traversal-safe key, preserving a whitelisted extension.
+ *
+ * @example
+ * ```ts
+ * // modules/photos/actions/upload-photo.server.ts, bound as <form action=${uploadPhoto}>
+ * // holding <input type="file" name="photo">
+ * 'use server';
+ * import { getFileStore, generateKey, type FormInput } from '@webjsdev/server';
+ *
+ * export async function uploadPhoto(input: FormInput<{ photo: File }>) {
+ *   const key = generateKey(input.photo.name);   // '<uuid>.jpg': never the user's own name or path
+ *   await getFileStore().put(key, input.photo);
+ *   return { success: true, data: { key } };    // store the key on the row
+ * }
+ * ```
+ */
 export declare function generateKey(filename?: string): string;
 /** Validate a key and return the absolute path it resolves to (throws on traversal). */
 export declare function assertSafeKey(dir: string, key: string): string;
-/** Mint a signed, expiring URL for a stored object (HMAC-SHA256). */
+/**
+ * Mint a signed, expiring URL for a stored object (HMAC-SHA256).
+ *
+ * @example
+ * ```ts
+ * // modules/photos/utils/photo-url.server.ts: a link that works for an hour, no session needed
+ * import { signedUrl } from '@webjsdev/server';
+ *
+ * export function photoUrl(key: string) {
+ *   return signedUrl(key, {
+ *     secret: process.env.FILE_URL_SECRET!,
+ *     base: '/files/' + encodeURIComponent(key),   // the route.ts serving it (default getFileStore().url(key))
+ *     expiresIn: 3600,                              // seconds, the default (0 or less is already expired)
+ *   });
+ * }
+ * // returns '/files/<key>?key=<key>&exp=<unix seconds>&sig=<hmac>', checked by verifySignedUrl
+ * ```
+ */
 export declare function signedUrl(
   key: string,
   opts: { secret: string; expiresIn?: number; base?: string },
 ): string;
-/** Verify a signed URL (or parsed params); constant-time, checks expiry + tamper. */
+/**
+ * Verify a signed URL (or parsed params); constant-time, checks expiry + tamper.
+ *
+ * @example
+ * ```ts
+ * // app/files/[key]/route.ts: serve a stored file only to a valid, unexpired signed link
+ * import { getFileStore, verifySignedUrl } from '@webjsdev/server';
+ *
+ * export async function GET(req: Request, { params }: { params: { key: string } }) {
+ *   const check = verifySignedUrl(req.url, process.env.FILE_URL_SECRET!);   // { valid, key, reason? }
+ *   if (!check.valid || check.key !== params.key) return new Response('Forbidden', { status: 403 });
+ *   const file = await getFileStore().get(params.key);
+ *   if (!file) return new Response('Not found', { status: 404 });
+ *   return new Response(file.body, { headers: { 'content-type': file.contentType, 'x-content-type-options': 'nosniff' } });
+ * }
+ * ```
+ */
 export declare function verifySignedUrl(
   input: string | URL | URLSearchParams | { key?: string; exp?: string | number; sig?: string },
   secret: string,
@@ -925,9 +1273,39 @@ export declare function verifySignedUrl(
 // json.js
 // ---------------------------------------------------------------------------
 
-/** Content-negotiated JSON response (rich wire format when the client asks for it). */
+/**
+ * Content-negotiated JSON response (rich wire format when the client asks for it).
+ *
+ * @example
+ * ```ts
+ * // app/api/posts/route.ts
+ * import { json } from '@webjsdev/server';
+ * import { listPosts } from '#modules/posts/queries/list-posts.server.ts';
+ *
+ * export async function GET() {
+ *   // Plain JSON for curl and fetch; richFetch from @webjsdev/core gets Date, Map and BigInt back intact.
+ *   return json(await listPosts(), { headers: { 'cache-control': 'max-age=60' } });
+ * }
+ * ```
+ */
 export declare function json<T>(data: T, init?: ResponseInit): Promise<Response>;
-/** Parse a request body (webjs rich format or plain JSON); enforces the body-size limit. */
+/**
+ * Parse a request body (WebJs rich format or plain JSON); enforces the body-size limit.
+ *
+ * @example
+ * ```ts
+ * // app/api/posts/route.ts
+ * import { json, readBody } from '@webjsdev/server';
+ * import { createPost } from '#modules/posts/queries/create-post.server.ts';
+ *
+ * export async function POST(req: Request) {
+ *   const body = (await readBody(req)) as { title?: unknown } | null;   // null for an empty body
+ *   if (typeof body?.title !== 'string' || !body.title) return json({ error: 'title is required' }, { status: 422 });
+ *   return json(await createPost({ title: body.title }), { status: 201 });
+ * }
+ * // A body over the limit (1 MiB by default) is answered 413 before it is parsed.
+ * ```
+ */
 export declare function readBody(req: Request): Promise<unknown>;
 
 // ---------------------------------------------------------------------------
@@ -946,7 +1324,25 @@ export interface SitemapIndexEntry {
   url: string;
   lastModified?: string | Date;
 }
-/** Serialize entries into a spec-valid `<urlset>` XML document. */
+/**
+ * Serialize entries into a spec-valid `<urlset>` XML document.
+ *
+ * @example
+ * ```ts
+ * // app/sitemap.ts, served at /sitemap.xml. Returning the entries array also works,
+ * // sitemap() is for when you want the XML string yourself.
+ * import { sitemap, type MetadataRouteContext } from '@webjsdev/server';
+ * import { listPosts } from '#modules/posts/queries/list-posts.server.ts';
+ *
+ * export default async function ({ siteUrl, pages }: MetadataRouteContext) {
+ *   const posts = await listPosts();
+ *   return sitemap([
+ *     ...(await pages()),   // every static page, already absolute
+ *     ...posts.map((p) => ({ url: siteUrl + '/posts/' + p.id, lastModified: p.updatedAt, priority: 0.7 })),
+ *   ]);
+ * }
+ * ```
+ */
 export declare function sitemap(entries: SitemapEntry[]): string;
 /** Serialize child sitemaps into a `<sitemapindex>` XML document. */
 export declare function sitemapIndex(sitemaps: SitemapIndexEntry[]): string;
@@ -965,7 +1361,23 @@ export interface RobotsConfig {
   sitemap?: string | string[];
   host?: string;
 }
-/** Serialize a robots config into robots.txt text. */
+/**
+ * Serialize a robots config into robots.txt text.
+ *
+ * @example
+ * ```ts
+ * // app/robots.ts, served at /robots.txt. Return the config and WebJs runs robots() on it.
+ * import type { MetadataRouteContext } from '@webjsdev/server';
+ *
+ * export default function ({ siteUrl }: MetadataRouteContext) {
+ *   return { rules: { userAgent: '*', disallow: ['/api/', '/account'] }, sitemap: siteUrl + '/sitemap.xml' };
+ * }
+ *
+ * // Calling it yourself returns the text, for a handler building its own Response:
+ * import { robots } from '@webjsdev/server';
+ * robots({ rules: [{ userAgent: '*', allow: '/' }, { userAgent: 'GPTBot', disallow: '/' }] });
+ * ```
+ */
 export declare function robots(config?: RobotsConfig): string;
 
 /**
@@ -999,9 +1411,42 @@ export type RobotsRouteResult = RobotsConfig | string | Response;
 
 /** The content type that negotiates and carries a stream-action response. */
 export declare const STREAM_MIME: string;
-/** Report whether a request opted into a stream-action response (its `Accept` carries the stream MIME). */
+/**
+ * Report whether a request opted into a stream-action response (its `Accept` carries the stream MIME).
+ *
+ * @example
+ * ```ts
+ * // app/todos/[id]/done/route.ts, posted by <form method="post" action="/todos/7/done">
+ * import { acceptsStream, stream, streamResponse } from '@webjsdev/server';
+ * import { completeTodo } from '#modules/todos/queries/complete-todo.server.ts';
+ *
+ * export async function POST(req: Request, { params }: { params: { id: string } }) {
+ *   await completeTodo(Number(params.id));
+ *   // The client router asks for a stream on a form submit, a browser with JS off does not.
+ *   if (acceptsStream(req)) return streamResponse(stream.remove('todo-' + params.id));
+ *   return Response.redirect(new URL('/todos', req.url), 303);
+ * }
+ * ```
+ */
 export declare function acceptsStream(req: Request | { headers?: Headers }): boolean;
-/** The stream-action builder; each method returns one `<webjs-stream>` HTML string. */
+/**
+ * The stream-action builder; each method returns one `<webjs-stream>` HTML string.
+ *
+ * @example
+ * ```ts
+ * // modules/comments/utils/comment-streams.server.ts
+ * import { stream } from '@webjsdev/server';
+ * import { escapeText } from '@webjsdev/core';
+ *
+ * // The target is an element id. It is escaped, the content is not: escape user text yourself.
+ * export const commentAdded = (c: { id: number; body: string }) =>
+ *   stream.append('comments', '<li id="comment-' + c.id + '">' + escapeText(c.body) + '</li>');
+ * export const commentDeleted = (id: number) => stream.remove('comment-' + id);
+ * // Also prepend, before, after, replace (the element itself) and update (its children).
+ * // Send them with streamResponse(...) to a form submit, or broadcast(path, html) to sockets,
+ * // where connectWS(path, { onMessage: (m) => renderStream(m) }) applies them.
+ * ```
+ */
 export declare const stream: {
   append(target: string, content: string): string;
   prepend(target: string, content: string): string;
@@ -1011,7 +1456,25 @@ export declare const stream: {
   update(target: string, content: string): string;
   remove(target: string): string;
 };
-/** Wrap one or more stream-action strings in a `Response` carrying the stream content type. */
+/**
+ * Wrap one or more stream-action strings in a `Response` carrying the stream content type.
+ *
+ * @example
+ * ```ts
+ * // modules/todos/actions/add-todo.server.ts, bound as <form action=${addTodo}> beside <ul id="todos">
+ * 'use server';
+ * import { acceptsStream, getRequest, stream, streamResponse, type FormInput } from '@webjsdev/server';
+ * import { escapeText } from '@webjsdev/core';
+ * import { insertTodo } from '../queries/insert-todo.server.ts';
+ *
+ * export async function addTodo(input: FormInput<{ title: string }>) {
+ *   const todo = await insertTodo(input.title);
+ *   const req = getRequest();
+ *   if (req && acceptsStream(req)) return streamResponse(stream.append('todos', '<li>' + escapeText(todo.title) + '</li>'));
+ *   return { success: true, redirect: '/todos' };   // JS off: the usual redirect and full render
+ * }
+ * ```
+ */
 export declare function streamResponse(...parts: string[]): Response;
 
 // ---------------------------------------------------------------------------
@@ -1080,13 +1543,102 @@ export type ResolvedAuthUser = keyof AuthUser extends never
   : AuthUser;
 
 /** Auth configuration for `createAuth`. */
+/**
+ * The Auth.js adapter methods `createAuth` calls, the shape `@auth/*-adapter`
+ * packages implement (`@auth/core/adapters`).
+ */
+export interface AuthAdapter {
+  createUser(user: Record<string, any>): Promise<any> | any;
+  getUser?(id: string): Promise<any> | any;
+  getUserByEmail(email: string): Promise<any> | any;
+  getUserByAccount(account: { provider: string; providerAccountId: string }): Promise<any> | any;
+  updateUser?(user: Record<string, any>): Promise<any> | any;
+  linkAccount(account: Record<string, any>): Promise<any> | any;
+  createSession(session: { sessionToken: string; userId: string; expires: Date }): Promise<any> | any;
+  getSessionAndUser(sessionToken: string): Promise<{ session: { sessionToken: string; userId: string; expires: Date }; user: any } | null> | { session: any; user: any } | null;
+  updateSession?(session: { sessionToken: string; expires?: Date }): Promise<any> | any;
+  deleteSession(sessionToken: string): Promise<any> | any;
+}
+/**
+ * The token the `jwt` and `session` callbacks see, Auth.js's `JWT`: the
+ * standard claims plus whatever the `jwt` callback put on it.
+ */
+export interface AuthJWT {
+  sub?: string;
+  name?: string | null;
+  email?: string | null;
+  image?: string | null;
+  iat?: number;
+  exp?: number;
+  [key: string]: unknown;
+}
+
+/** The user the callbacks see, Auth.js's `User`: what `authorize` or the provider returned. */
+export interface AuthCallbackUser {
+  id?: string;
+  name?: string | null;
+  email?: string | null;
+  image?: string | null;
+  [key: string]: unknown;
+}
+
+/** The session the `session` callback receives and returns, Auth.js's `Session`. */
+export interface AuthCallbackSession {
+  user: ResolvedAuthUser & { name?: string | null; email?: string | null; image?: string | null };
+  expires: string;
+  [key: string]: unknown;
+}
+
+type AuthAwaitable<T> = T | Promise<T>;
+
+/**
+ * Auth.js's callbacks, with the parameters Auth.js passes, so a callback
+ * written as Auth.js documents it (`jwt({ token, user })`,
+ * `session({ session, token })`) is typed with no annotation. Declared as
+ * methods so a callback annotated with its own narrower types still compiles.
+ */
+export interface AuthCallbacks {
+  /** At sign-in (`trigger: 'signIn'`, with `user`, `account` and `profile`) and on every session read. */
+  jwt?(params: { token: AuthJWT; user: AuthCallbackUser; account?: Record<string, any> | null; profile?: Record<string, any>; trigger?: 'signIn' | 'signUp' | 'update'; session?: any }): AuthAwaitable<AuthJWT | null>;
+  /** On every session read. `token` under the jwt strategy, `user` under the database strategy. */
+  session?(params: { session: AuthCallbackSession; token: AuthJWT; user: AuthCallbackUser }): AuthAwaitable<any>;
+  /** Return true to allow, a url string to redirect there instead, anything else to deny (Auth.js's rule). */
+  signIn?(params: { user: AuthCallbackUser; account?: Record<string, any> | null; profile?: Record<string, any>; credentials?: Record<string, any> }): AuthAwaitable<boolean | string>;
+  redirect?(params: { url: string; baseUrl: string }): AuthAwaitable<string>;
+  /** Run by `auth` as middleware: true continues, false redirects to sign in, a Response is sent as is. */
+  authorized?: (params: { auth: { user: Record<string, unknown> } | null; request: Request }) => boolean | Response | Promise<boolean | Response>;
+}
+
 export interface AuthConfig {
-  providers: ProviderConfig[];
-  session?: { strategy?: 'jwt' | 'database'; maxAge?: number };
-  secret: string;
-  callbacks?: { session?: Function; jwt?: Function; signIn?: Function; redirect?: Function };
-  adapter?: { load?: Function; save?: Function; destroy?: Function };
+  /** A provider config, or the provider function uncalled (`providers: [GitHub]`), as Auth.js accepts. */
+  providers: Array<ProviderConfig | (() => ProviderConfig)>;
+  /**
+   * `strategy` defaults to `'database'` when an Auth.js adapter is given, else
+   * `'jwt'`. `updateAge` (seconds, default a day) is how often a database
+   * session's expiry is pushed forward, as in Auth.js.
+   */
+  session?: { strategy?: 'jwt' | 'database'; maxAge?: number; updateAge?: number };
+  /** Signs the session. Defaults to `process.env.AUTH_SECRET`, as in Auth.js. */
+  secret?: string | undefined;
+  callbacks?: AuthCallbacks;
+  /**
+   * An Auth.js database adapter (`DrizzleAdapter(db)` from `@auth/drizzle-adapter`,
+   * and the rest), or WebJs's own session store for the database strategy.
+   */
+  adapter?: AuthAdapter | { load?: Function; save?: Function; destroy?: Function };
   pages?: { signIn?: string; signOut?: string; error?: string };
+  /**
+   * Auth.js's `useSecureCookies`: force the Secure flag and the `__Host-`
+   * cookie names on or off. Unset, they follow the auth URL's protocol
+   * (`AUTH_URL`'s when set, else the request's), never `NODE_ENV`.
+   */
+  useSecureCookies?: boolean;
+  /**
+   * Where the auth routes are mounted, as Auth.js's `basePath`. Defaults to
+   * the path of `AUTH_URL` when it has one, else `/api/auth`. `AUTH_URL` (or
+   * `NEXTAUTH_URL`) also sets the origin OAuth callback URLs use.
+   */
+  basePath?: string;
 }
 
 /**
@@ -1097,26 +1649,142 @@ export interface AuthConfig {
  * via `createAuth<MyUser>(...)`.
  */
 export interface AuthInstance<TUser = ResolvedAuthUser> {
-  auth: (req?: Request) => Promise<{ user: TUser } | null>;
-  signIn: (
-    provider: string,
-    data?: Record<string, unknown>,
-    opts?: { redirectTo?: string; req?: Request },
-  ) => Promise<Response>;
-  signOut: (opts?: { redirectTo?: string; req?: Request }) => Promise<Response>;
+  /**
+   * Auth.js's `auth`, in its three shapes: `auth()` / `auth(req)` reads the
+   * session; `export { auth as middleware }` runs as middleware (it sets
+   * `req.auth` and applies `callbacks.authorized`); `auth((req) => ...)` wraps
+   * a middleware whose `req.auth` holds the session.
+   */
+  auth: {
+    (req?: Request | null): Promise<{ user: TUser } | null>;
+    (req: Request, next: unknown): Promise<Response | undefined>;
+    <R>(handler: (req: Request & { auth: { user: TUser } | null }, ...rest: any[]) => R): (req: Request, ...rest: any[]) => Promise<Response | Awaited<R>>;
+  };
+  /**
+   * Auth.js v5's `signIn`. Inside a request (a server action, a route handler,
+   * middleware) it sets the session cookie on the response and throws a
+   * redirect, so `await signIn('credentials', formData)` in a form action signs
+   * in and navigates; a credentials failure throws {@link CredentialsSignin}.
+   * `{ redirect: false }` (in the options or, as Auth.js accepts it, in the
+   * data) returns the target url instead of throwing. With no request in scope
+   * it returns the Response the `/api/auth/*` routes send. The redirecting
+   * form is typed `Promise<Response>`, so `return signIn(...)` fits an action
+   * that returns `ActionResult | Response`.
+   */
+  signIn: {
+    (
+      provider: string,
+      data: (FormData | Record<string, unknown>) | undefined,
+      opts: { redirectTo?: string; redirect: false; req?: Request },
+    ): Promise<string>;
+    (
+      provider: string,
+      data: Record<string, unknown> & { redirect: false },
+      opts?: { redirectTo?: string; req?: Request },
+    ): Promise<string>;
+    (
+      provider: string,
+      data?: FormData | Record<string, unknown>,
+      opts?: { redirectTo?: string; redirect?: true; req?: Request },
+    ): Promise<Response>;
+  };
+  /** Auth.js v5's `signOut`: clears the session and throws a redirect inside a request. */
+  signOut: {
+    (opts: { redirectTo?: string; redirect: false; req?: Request }): Promise<string>;
+    (opts?: { redirectTo?: string; redirect?: true; req?: Request }): Promise<Response>;
+  };
   handlers: { GET: (req: Request) => Promise<Response>; POST: (req: Request) => Promise<Response> };
 }
 
 /**
- * Create the auth system. Parameterise with the session-user shape
- * (`createAuth<MyUser>(...)`) for per-instance typing, or augment the
- * {@link AuthUser} interface for global typing; both make `auth().user` typed
- * with no cast. Defaults to the open {@link AuthUser}, so existing untyped code
- * keeps compiling unchanged.
+ * Create the auth system, Auth.js's API. `createAuth<MyUser>(...)` (or an
+ * augmented {@link AuthUser}) types `auth().user` with no cast.
+ *
+ * @example
+ * ```ts
+ * // modules/auth/auth.server.ts
+ * import { createAuth, Credentials, AuthError } from '@webjsdev/server';
+ * export const { auth, signIn, signOut, handlers } = createAuth({
+ *   providers: [Credentials({
+ *     async authorize(c: { email: string; password: string }) {
+ *       const user = await findUserByEmail(c.email); // your own query
+ *       if (!user || !(await verifyPassword(c.password, user.passwordHash))) return null;
+ *       return { id: String(user.id), email: user.email };
+ *     },
+ *   })],
+ *   pages: { error: '/login' }, // an uncaught failure lands on /login?error=CredentialsSignin
+ * });
+ * // app/api/auth/[...path]/route.ts: export const { GET, POST } = handlers;
+ * // Read the user anywhere on the server: const session = await auth();
+ *
+ * // A 'use server' action bound as <form action=${logIn}>, as with Auth.js in Next.
+ * // AuthError comes from '@webjsdev/server' (as above), never from auth.server.ts:
+ * export async function logIn(formData: FormData) {
+ *   try {
+ *     await signIn('credentials', formData, { redirectTo: '/dashboard' });
+ *   } catch (error) {
+ *     if (error instanceof AuthError) return { success: false, error: 'Wrong email or password.' };
+ *     throw error; // the success redirect
+ *   }
+ * }
+ * // Sign out the same way: await signOut({ redirectTo: '/' }).
+ * ```
  */
 export declare function createAuth<TUser = ResolvedAuthUser>(config: AuthConfig): AuthInstance<TUser>;
-/** The credentials (email/password) provider. */
-export declare function Credentials(opts: Record<string, unknown>): ProviderConfig;
+/** Next.js's navigation helpers (`next/navigation`), re-exported from `@webjsdev/core` so server code can import them from either package. */
+export declare const notFound: typeof import('@webjsdev/core').notFound;
+export declare const forbidden: typeof import('@webjsdev/core').forbidden;
+export declare const unauthorized: typeof import('@webjsdev/core').unauthorized;
+export declare const redirect: typeof import('@webjsdev/core').redirect;
+export declare const permanentRedirect: typeof import('@webjsdev/core').permanentRedirect;
+
+/** Auth.js's base error: `error instanceof AuthError` and `error.type` say why a sign-in failed. */
+export declare class AuthError extends Error {
+  type: string;
+}
+/** Thrown by `signIn('credentials', ...)` when `authorize` returns null. */
+export declare class CredentialsSignin extends AuthError {
+  type: 'CredentialsSignin';
+  code: string;
+}
+/**
+ * Options for the credentials provider, Auth.js's `Credentials`. `C` is the
+ * shape of the submitted fields, inferred from `authorize`'s annotation
+ * (`authorize(credentials: { email: string; password: string })`).
+ */
+export interface CredentialsOptions<C extends Record<string, unknown> = Record<string, unknown>> {
+  /**
+   * Check the submitted fields (the sign-in form's fields, or the object passed
+   * to `signIn('credentials', data)`). Return the session user, or `null` to
+   * refuse the sign-in.
+   */
+  authorize: (credentials: C) => Promise<Record<string, unknown> | null> | Record<string, unknown> | null;
+  [key: string]: unknown;
+}
+/**
+ * The credentials (email/password) provider, Auth.js's `Credentials`.
+ *
+ * @example
+ * ```ts
+ * // modules/auth/auth.server.ts
+ * import { createAuth, Credentials } from '@webjsdev/server';
+ * import { findUserByEmail } from '#modules/users/queries/find-user-by-email.server.ts';
+ * import { verifyPassword } from './password.server.ts';
+ *
+ * export const { auth, signIn, signOut, handlers } = createAuth({
+ *   providers: [Credentials({
+ *     async authorize(credentials: { email: string; password: string }) {
+ *       const user = await findUserByEmail(credentials.email);
+ *       if (!user || !(await verifyPassword(credentials.password, user.passwordHash))) return null;
+ *       return { id: String(user.id), email: user.email };   // the session user, null refuses
+ *     },
+ *   })],
+ * });
+ * ```
+ */
+export declare function Credentials<C extends Record<string, unknown> = Record<string, unknown>>(
+  opts: CredentialsOptions<C>,
+): ProviderConfig;
 /** The Google OAuth provider. */
 export declare function Google(opts?: Record<string, unknown>): ProviderConfig;
 /** The GitHub OAuth provider. */