From a047afcd6b0e9a9e2f5d3179b7e4ae92c6c7317a Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Wed, 3 Jun 2026 21:05:27 +0530
Subject: [PATCH 1/3] feat: ship type declarations for @webjsdev/server (fix
 TS7016)

@webjsdev/core shipped an index.d.ts + a types export condition, but
@webjsdev/server shipped neither, so under strict + nodenext a TS app's
import { createRequestHandler, cors, cache, ... } from '@webjsdev/server'
emitted TS7016 (no declaration file). That blocked the webjs typecheck-in-CI
story and left a core import untyped for every TS app. Ship a hand-authored
index.d.ts overlay typing every named export (precise for the high-traffic
public API, reusing core's PageProps/LayoutProps/RouteHandlerContext), plus
src/check.d.ts and src/testing.d.ts for the subpaths, and add types-first
export conditions. A drift guard asserts the overlay matches index.js's
runtime exports; a fixture + a TS7016 counterfactual prove the fix.

Closes #310
---
 agent-docs/typescript.md                      |  15 +
 packages/server/AGENTS.md                     |  33 +
 packages/server/index.d.ts                    | 650 ++++++++++++++++++
 packages/server/package.json                  |  17 +-
 packages/server/src/check.d.ts                |  38 +
 packages/server/src/testing.d.ts              | 123 ++++
 .../server/test/types/exports-drift.test.mjs  |  64 ++
 .../test/types/server-exports.test-d.ts       | 133 ++++
 .../server/test/types/server-types.test.mjs   |  96 +++
 9 files changed, 1166 insertions(+), 3 deletions(-)
 create mode 100644 packages/server/index.d.ts
 create mode 100644 packages/server/src/check.d.ts
 create mode 100644 packages/server/src/testing.d.ts
 create mode 100644 packages/server/test/types/exports-drift.test.mjs
 create mode 100644 packages/server/test/types/server-exports.test-d.ts
 create mode 100644 packages/server/test/types/server-types.test.mjs

diff --git a/agent-docs/typescript.md b/agent-docs/typescript.md
index 4c7e467ff..7941e91bc 100644
--- a/agent-docs/typescript.md
+++ b/agent-docs/typescript.md
@@ -289,6 +289,21 @@ type, AND the reader in lockstep, the one procedure documented in
 (`packages/server/test/config/webjs-config-schema.test.js`) fails if the schema
 and the reader key set diverge.
 
+### Both runtime packages ship a type overlay
+
+Both `@webjsdev/core` AND `@webjsdev/server` ship a hand-authored `.d.ts`
+overlay plus a `types` export condition, so a `strict` + `nodenext` app
+resolves real types for either import with no TS7016 ("could not find a
+declaration file") error. The server overlay (`packages/server/index.d.ts`,
+with `src/check.d.ts` and `src/testing.d.ts` for the `./check` / `./testing`
+subpaths) types the full public surface (`createRequestHandler`, `startServer`,
+`cors`, `cache`, `createAuth`, `rateLimit`, `sitemap`, `Session`, `json`,
+`readBody`, the `revalidate*` family, the context helpers, the cache stores, the
+auth providers, the test harness, and the convention validator), reusing the
+core prop / metadata types rather than redefining them. The runtime stays plain
+`.js` + JSDoc; the overlay is types-only with zero runtime cost. A drift test
+keeps `index.d.ts` in lockstep with `index.js`'s runtime exports.
+
 ### TypeScript is not required
 
 JS + JSDoc gets the same call-site type safety. The TypeScript language
diff --git a/packages/server/AGENTS.md b/packages/server/AGENTS.md
index 78dd2f877..76d3ce1c6 100644
--- a/packages/server/AGENTS.md
+++ b/packages/server/AGENTS.md
@@ -84,6 +84,39 @@ re-exported from the main entry). The
 (below) so an editor can resolve it from
 `node_modules/@webjsdev/server/webjs-config.schema.json`.
 
+### Type overlay (#310)
+
+The package ships a hand-authored `.d.ts` overlay plus `types` export
+conditions, so a `strict` + `nodenext` TypeScript app's `import { ... } from
+'@webjsdev/server'` resolves real types instead of TS7016. The runtime stays
+plain `.js` + JSDoc; the overlay is types-only with zero runtime cost.
+
+- [`index.d.ts`](./index.d.ts) types every named export of `index.js`. The
+  high-traffic public API (`createRequestHandler`, `startServer`, `cors`,
+  `cache`, `createAuth`, `rateLimit`, `sitemap` / `sitemapIndex`, `Session`,
+  `json`, `readBody`, the `revalidate*` family, the context helpers,
+  `memoryStore` / `redisStore` / `getStore` / `setStore`, the auth providers)
+  is precisely typed from each source function's JSDoc; lower-traffic internals
+  (scanner / importmap / module-graph / vendor) get reasonable structural
+  declarations. It REUSES the core prop / metadata types
+  (`PageProps` / `LayoutProps` / `RouteHandlerContext`) rather than redefining
+  them, and defines the one server-owned shared type, `ActionResult<T>`
+  (`@webjsdev/core` does not export it). The `./testing` types are pulled in via
+  `export * from './src/testing.d.ts'` (no duplication).
+- [`src/check.d.ts`](./src/check.d.ts) types the `./check` subpath
+  (`checkConventions`, `RULES`, `Violation`).
+- [`src/testing.d.ts`](./src/testing.d.ts) types the `./testing` subpath (the
+  handle() harness helpers).
+
+In `package.json`, the top-level `"types"` plus each `exports` entry's `types`
+condition (FIRST in the object, as nodenext requires) wire the resolution; the
+top-level `index.d.ts` is added to the `files` allowlist (`src/*.d.ts` ships via
+the globbed `src`). **A new export added to `index.js` MUST get a declaration in
+`index.d.ts`,** enforced by the drift test
+`test/types/exports-drift.test.js` (asserts the declared set equals the runtime
+export set); the type fixture + TS7016 counterfactual live in
+`test/types/server-exports.test-d.ts` + `test/types/server-types.test.mjs`.
+
 ## The `webjs` package.json config block (typed surface, #259)
 
 The `webjs.*` keys an app sets in `package.json` are typed and validated
diff --git a/packages/server/index.d.ts b/packages/server/index.d.ts
new file mode 100644
index 000000000..c749de0ee
--- /dev/null
+++ b/packages/server/index.d.ts
@@ -0,0 +1,650 @@
+/**
+ * Public type surface for `@webjsdev/server`.
+ *
+ * The runtime is packages/server/index.js + src/*.js (JSDoc-annotated
+ * JavaScript, no build step); this overlay exists so a TypeScript app under
+ * `strict` + `nodenext`/`node16` resolves real types for the server import
+ * instead of emitting TS7016 ("Could not find a declaration file for module
+ * '@webjsdev/server'"). The whole package stays plain `.js` + JSDoc at runtime;
+ * these declarations are types-only with zero runtime cost.
+ *
+ * House style follows packages/core/index.d.ts: `export type` for type-only
+ * surface, `export declare function` / `export declare const` for runtime
+ * values. Shapes the framework consumes from core (`Metadata`, `PageProps`,
+ * `ActionResult`, …) are reused, never redefined; the high-traffic public API
+ * is precisely typed from each source function's JSDoc; lower-traffic internals
+ * (scanner / importmap / module-graph / vendor) get reasonable structural
+ * declarations.
+ *
+ * The drift guard `test/types/exports-drift.test.js` asserts the set of named
+ * exports here exactly matches the runtime named exports of index.js, so a
+ * future export added to index.js without a type is caught.
+ */
+
+import type { LayoutProps, PageProps, RouteHandlerContext } from '@webjsdev/core';
+
+// The `./testing` subpath types are re-exported wholesale (the helpers ship
+// from both the main entry and the subpath; this avoids duplicating them).
+export * from './src/testing.d.ts';
+
+// ---------------------------------------------------------------------------
+// Shared local types
+// ---------------------------------------------------------------------------
+
+/** A webjs middleware: receives the request + a `next()` continuation. */
+export type Middleware = (req: Request, next: () => Promise<Response>) => Promise<Response> | Response;
+
+// `Handle` is re-exported from ./src/testing.d.ts (the `export *` above), so it
+// is not re-declared here. `RequestHandler.handle` / `Handle` reference it.
+
+/**
+ * The `ActionResult<T>` envelope a server action / page action returns.
+ * 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 }
+  | {
+      success: false;
+      error?: string;
+      fieldErrors?: Record<string, string>;
+      values?: Record<string, string>;
+      status?: number;
+    };
+
+/** The pluggable cache store interface (`memoryStore` / `redisStore` / custom). */
+export interface CacheStore {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string, ttlMs?: number): Promise<void>;
+  delete(key: string): Promise<void>;
+  /** Atomically increment a counter; returns the new value (TTL set on creation only). */
+  increment(key: string, ttlMs?: number): Promise<number>;
+}
+
+/** The pluggable logger interface. */
+export interface Logger {
+  info(msg: string, meta?: Record<string, unknown>): void;
+  warn(msg: string, meta?: Record<string, unknown>): void;
+  error(msg: string, meta?: Record<string, unknown>): void;
+  debug?(msg: string, meta?: Record<string, unknown>): void;
+}
+
+/** The wire serializer used by the RPC transport. */
+export interface Serializer {
+  serialize(value: unknown): Promise<string> | string;
+  deserialize(text: string): unknown;
+}
+
+/** Options shared by `createRequestHandler` and `startServer`. */
+export interface RequestHandlerOptions {
+  /** The app root directory (the dir containing `app/`). */
+  appDir: string;
+  /** Dev mode (live reload, TS strip, uncompressed bytes). */
+  dev?: boolean;
+  /** Pluggable logger; defaults to webjs's `defaultLogger`. */
+  logger?: Logger;
+  /**
+   * APM / Sentry sink invoked on a caught unhandled error (#239). Best-effort:
+   * a throw here is swallowed and never affects the response.
+   */
+  onError?: (
+    error: unknown,
+    ctx: { request: Request; requestId: string | null; phase: string },
+  ) => void;
+}
+
+/** A matched page route for a path, as returned by `routeFor`. */
+export interface RouteForResult {
+  moduleUrls: string[];
+}
+
+/** The object `createRequestHandler` resolves to. */
+export interface RequestHandler {
+  /** The request -> response entry point for embedding under any host. */
+  handle: Handle;
+  /** Re-derive the route table / analysis after a source change (dev). */
+  rebuild: () => Promise<void>;
+  /** Resolve a pathname to its page-route module URLs (for 103 Early Hints), or null. */
+  routeFor: (pathname: string) => RouteForResult | null;
+  /** Proactively run the first-request analysis in the background. Idempotent, best-effort. */
+  warmup: () => Promise<void>;
+  /** Current route table getter (used by the WebSocket subsystem). */
+  getRouteTable: () => unknown;
+  /** The resolved app root. */
+  appDir: string;
+  /** Whether the handler is in dev mode. */
+  dev: boolean;
+  /** The active logger. */
+  logger: Logger;
+}
+
+/** Options for `startServer` (a superset of `RequestHandlerOptions`). */
+export interface StartServerOptions extends RequestHandlerOptions {
+  /** Listen port (default 8080; `PORT` env honored by the CLI). */
+  port?: number;
+  /** Response compression (default: on in prod, off in dev). */
+  compress?: boolean;
+}
+
+/** The object `startServer` resolves to. */
+export interface ServerHandle {
+  /** The underlying `node:http` server. */
+  server: import('node:http').Server;
+  /** Gracefully close the server (and abort the dev file watcher). */
+  close: () => Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Server entry: dev.js
+// ---------------------------------------------------------------------------
+
+/**
+ * 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.
+ */
+export declare function createRequestHandler(opts: RequestHandlerOptions): Promise<RequestHandler>;
+
+/** Start a webjs HTTP server (thin wrapper around `createRequestHandler`). */
+export declare function startServer(opts: StartServerOptions): Promise<ServerHandle>;
+
+// ---------------------------------------------------------------------------
+// node-version.js (#238)
+// ---------------------------------------------------------------------------
+
+/** Parse a Node version string to its major integer. */
+export declare function parseMajor(version: string): number;
+/** Parse an `engines.node` range string to the minimum acceptable major. */
+export declare function parseRequiredMajor(engines: string): number;
+/** Pure comparison: is `current` at least `requiredMajor`? */
+export declare function checkNodeVersion(
+  current: string,
+  requiredMajor: number,
+): { ok: boolean; current: string; currentMajor: number; requiredMajor: number; message: string };
+/** The minimum Node major, sourced from this package's `engines.node`. */
+export declare function requiredNodeMajor(): number;
+/** Throw or exit if the running Node is too old. */
+export declare function assertNodeVersion(opts?: {
+  current?: string;
+  requiredMajor?: number;
+  onFail?: 'exit' | 'throw';
+}): void;
+
+// ---------------------------------------------------------------------------
+// env-schema.js (#236)
+// ---------------------------------------------------------------------------
+
+/** Pure env validator: check an env object against a schema or validator function. */
+export declare function validateEnv(
+  schema: object | ((env: Record<string, string | undefined>) => void),
+  env: Record<string, string | undefined>,
+): { ok: boolean; errors: string[]; coerced: Record<string, string> };
+/** Compose the aggregated boot-failure message from a list of errors. */
+export declare function formatEnvErrors(errors: string[]): string;
+/** Read the optional app-root `env.{js,ts}` default export (null when absent). */
+export declare function loadEnvSchema(
+  appDir: string,
+  opts?: { dev?: boolean },
+): Promise<object | ((env: Record<string, string | undefined>) => void) | null>;
+/** Side-effecting boot wrapper: validate `process.env`, write back coerced values, throw on failure. */
+export declare function applyEnvValidation(
+  appDir: string,
+  opts?: { dev?: boolean; env?: Record<string, string | undefined> },
+): Promise<void>;
+
+// ---------------------------------------------------------------------------
+// router.js
+// ---------------------------------------------------------------------------
+
+/** Scan `app/` and build the route table. */
+export declare function buildRouteTable(appDir: string): Promise<unknown>;
+/** Match a pathname against the page routes in a table; null when no page matches. */
+export declare function matchPage(
+  table: unknown,
+  pathname: string,
+): { route: { file: string; layouts: string[] }; params: Record<string, string> } | null;
+/** Match a pathname against the API (`route.{js,ts}`) routes in a table; null when none. */
+export declare function matchApi(
+  table: unknown,
+  pathname: string,
+): { route: { file: string }; params: Record<string, string> } | null;
+
+// ---------------------------------------------------------------------------
+// route-types.js (#258)
+// ---------------------------------------------------------------------------
+
+/** Generate the augmentation `.d.ts` text for an app's routes (backs `webjs types`). */
+export declare function generateRouteTypes(appDir: string): Promise<string>;
+
+// ---------------------------------------------------------------------------
+// ssr.js
+// ---------------------------------------------------------------------------
+
+/** Server-render a matched page route to a `Response`. */
+export declare function ssrPage(
+  route: unknown,
+  params: Record<string, string>,
+  url: string,
+  opts?: Record<string, unknown>,
+): Promise<Response>;
+/** Server-render the nearest `not-found.{js,ts}` to a `Response`. */
+export declare function ssrNotFound(notFoundFile: string, opts?: Record<string, unknown>): Promise<Response>;
+
+// ---------------------------------------------------------------------------
+// api.js
+// ---------------------------------------------------------------------------
+
+/** Dispatch a matched `route.{js,ts}` handler (GET/POST/...) to a `Response`. */
+export declare function handleApi(
+  route: unknown,
+  params: Record<string, string>,
+  webRequest: Request,
+  dev: boolean,
+): Promise<Response>;
+
+// ---------------------------------------------------------------------------
+// actions.js (server-action scanner + RPC endpoint)
+// ---------------------------------------------------------------------------
+
+/** Scan the app for `.server.{js,ts}` files and build the RPC + expose index. */
+export declare function buildActionIndex(appDir: string, dev: boolean): Promise<unknown>;
+/** Whether a file path is a `.server.{js,ts,mjs,mts}` server file. */
+export declare function isServerFile(file: string): boolean;
+/** SHA-256 hash of an action file's absolute path (the RPC endpoint addressing scheme). */
+export declare function hashFile(file: string): Promise<string>;
+/** Resolve a browser-visible URL path to its server module entry in the action index. */
+export declare function resolveServerModule(idx: unknown, urlPath: string): unknown;
+/** Produce the generated RPC / throw-at-load stub source for a server file. */
+export declare function serveActionStub(idx: unknown, absFile: string): Promise<string>;
+/** Invoke a server action over the RPC endpoint, returning the `Response`. */
+export declare function invokeAction(
+  idx: unknown,
+  hash: string,
+  fnName: string,
+  req: Request,
+  onError?: (error: unknown) => void,
+): Promise<Response>;
+
+// ---------------------------------------------------------------------------
+// importmap.js
+// ---------------------------------------------------------------------------
+
+/** Build the browser import map object (optionally content-hash-fingerprinted). */
+export declare function buildImportMap(opts?: { fingerprint?: boolean }): unknown;
+/** Render the `<script type="importmap">` tag (optionally CSP-nonced). */
+export declare function importMapTag(opts?: { nonce?: string }): string;
+/** Set the resolved vendor importmap entries (+ optional SRI integrity by URL). */
+export declare function setVendorEntries(
+  entries: Record<string, string>,
+  integrity?: Record<string, string>,
+): Promise<void>;
+
+// ---------------------------------------------------------------------------
+// vendor.js (the `webjs vendor` CLI surface)
+// ---------------------------------------------------------------------------
+
+/** Scan a directory's source for bare-specifier npm imports. */
+export declare function scanBareImports(dir: string, skipFiles?: Set<string>): Promise<Set<string>>;
+/** Extract the package name from an import specifier (`dayjs/plugin/utc` -> `dayjs`). */
+export declare function extractPackageName(spec: string): string | null;
+/** Resolve bare imports to CDN importmap entries. */
+export declare function vendorImportMapEntries(
+  bareImports: Set<string>,
+  appDir: string,
+): Promise<Record<string, string>>;
+/** Resolve the app's vendor imports (pin file first, else live jspm). */
+export declare function resolveVendorImports(
+  appDir: string,
+  getBareImports: () => Promise<Set<string>> | Set<string>,
+): Promise<{ imports: Record<string, string>; integrity?: Record<string, string>; provider?: string } | null>;
+/** Clear the per-process vendor + live-integrity caches (wired to the dev rebuild). */
+export declare function clearVendorCache(): void;
+/** Read a package's installed version from `node_modules`, or null. */
+export declare function getPackageVersion(pkgName: string, appDir: string): string | null;
+/** Resolve a list of `pkg@version` installs to importmap entries via a provider. */
+export declare function jspmGenerate(installs: string[], provider?: string): Promise<Record<string, string>>;
+/** Pin every (or the named) bare imports to `.webjs/vendor/importmap.json`. */
+export declare function pinAll(
+  appDir: string,
+  opts?: { download?: boolean; from?: string },
+): Promise<unknown>;
+/** Remove a package from the pin file. */
+export declare function unpinPackage(
+  appDir: string,
+  pkg: string,
+): Promise<{ removed: boolean; deletedFile?: string }>;
+/** List the pinned packages. */
+export declare function listPinned(
+  appDir: string,
+): Promise<Array<{ pkg: string; version: string; url: string; bytes?: number }>>;
+/** Run npm security advisories against the pinned versions. */
+export declare function auditPinned(appDir: string): Promise<unknown>;
+/** List pinned packages that have a newer version available. */
+export declare function findOutdated(appDir: string): Promise<unknown>;
+/** Whether the app commits a `.webjs/vendor/importmap.json` pin file. */
+export declare function hasVendorPin(appDir: string): boolean;
+/** Re-pin every outdated package to its latest version. */
+export declare function updatePinned(appDir: string, opts?: { from?: string }): Promise<unknown>;
+/** Read + parse the committed pin file, or null when absent. */
+export declare function readPinFile(
+  appDir: string,
+): Promise<{ imports: Record<string, string>; integrity?: Record<string, string>; provider?: string } | null>;
+/** Serve a downloaded `/__webjs/vendor/*` bundle file (`--download` mode). */
+export declare function serveDownloadedBundle(
+  appDir: string,
+  pathname: string,
+): Promise<Response | null>;
+/** The set of supported CDN providers. */
+export declare const SUPPORTED_PROVIDERS: Set<string>;
+/** Normalize / validate a provider name. */
+export declare function normalizeProvider(name: string): string;
+
+// ---------------------------------------------------------------------------
+// module-graph.js
+// ---------------------------------------------------------------------------
+
+/** Build the app's static import dependency graph. */
+export declare function buildModuleGraph(appDir: string): Promise<unknown>;
+/** Compute the transitive dependency set of a set of entry files (stops at `.server.*`). */
+export declare function transitiveDeps(
+  graph: unknown,
+  entryFiles: string[],
+  appDir: string,
+  skip?: Set<string>,
+): string[];
+
+// ---------------------------------------------------------------------------
+// component-scanner.js
+// ---------------------------------------------------------------------------
+
+/** Scan the app for webjs component classes and their browser-visible URLs. */
+export declare function scanComponents(
+  appDir: string,
+): Promise<Array<{ tag: string; className: string; moduleUrl: string; file: string }>>;
+/** Register scanned components into the server-side registry. */
+export declare function primeComponentRegistry(
+  appDir: string,
+  components?: Array<{ tag: string; className: string; moduleUrl: string; file: string }>,
+): Promise<{ count: number }>;
+/** Extract `{ className, tag }` pairs from a component module's source. */
+export declare function extractComponents(src: string): Array<{ className: string; tag: string }>;
+/** Find component classes that no page / component imports (orphans). */
+export declare function findOrphanComponents(
+  appDir: string,
+): Promise<Array<{ className: string; file: 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;
+  has(name: string): boolean;
+  entries(): [string, string][];
+};
+/** 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. */
+export declare function withRequest<T>(req: Request, fn: () => T): T;
+/** The per-request CSP nonce (`''` when CSP is off). */
+export declare function cspNonce(): string;
+/** The per-request correlation id, or null outside a request scope. */
+export declare function requestId(): string | null;
+
+// ---------------------------------------------------------------------------
+// logger.js
+// ---------------------------------------------------------------------------
+
+/** The default logger (JSON-shaped in prod, pretty in dev). */
+export declare function defaultLogger(opts?: { dev?: boolean }): Logger;
+
+// ---------------------------------------------------------------------------
+// rate-limit.js
+// ---------------------------------------------------------------------------
+
+/** Build a rate-limit middleware `(req, next) => Response`. */
+export declare function rateLimit(opts?: {
+  window?: number | string;
+  max?: number;
+  key?: string | ((req: Request) => string | Promise<string>);
+  message?: string;
+  store?: CacheStore;
+  trustProxy?: boolean;
+}): Middleware;
+/** Parse a window string (`'1m'`, `'30s'`) to milliseconds. */
+export declare function parseWindow(w: number | string): number;
+/** Resolve the client IP for a request (honoring proxy-trust posture). */
+export declare function clientIp(req: Request, opts?: { trustProxy?: boolean }): string;
+/** Stamp the socket remote address onto a request for `clientIp` to read. */
+export declare function stampRemoteIp(req: Request, remoteAddress: string): void;
+
+// ---------------------------------------------------------------------------
+// cors.js
+// ---------------------------------------------------------------------------
+
+/** A single CORS origin rule. */
+export type CorsOriginRule = string | RegExp | ((origin: string) => boolean);
+
+/** Options for the `cors()` middleware factory. */
+export interface CorsOptions {
+  origin?: '*' | true | CorsOriginRule | CorsOriginRule[];
+  credentials?: boolean;
+  methods?: string[] | string;
+  allowedHeaders?: string[] | string;
+  exposedHeaders?: string[] | string;
+  maxAge?: number;
+}
+
+/** Build a CORS middleware `(req, next) => Response`. */
+export declare function cors(options?: CorsOptions): Middleware;
+/** Resolve the allowed origin for a request given a policy (shared CORS core). */
+export declare function resolveOrigin(
+  policy: CorsOptions['origin'],
+  origin: string | null,
+  credentials: boolean,
+): { value: string | null; dynamic: boolean };
+/** Apply the resolved CORS headers to a `Headers` object. */
+export declare function applyCorsHeaders(
+  headers: Headers,
+  resolved: { value: string | null; dynamic: boolean },
+  cfg: CorsOptions,
+): void;
+
+// ---------------------------------------------------------------------------
+// cache.js (pluggable store) + cache-fn.js (query caching)
+// ---------------------------------------------------------------------------
+
+/** In-memory LRU cache store (single-process). */
+export declare function memoryStore(opts?: { maxSize?: number }): CacheStore;
+/** Redis-backed cache store. */
+export declare function redisStore(opts?: Record<string, unknown>): CacheStore;
+/** Get the default cache store (memory unless `setStore` was called). */
+export declare function getStore(): CacheStore;
+/** Set the default cache store (call at startup to switch to Redis). */
+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.
+ */
+export declare function cache<T extends (...args: any[]) => Promise<any>>(
+  fn: T,
+  opts: {
+    key: string;
+    ttl?: number;
+    tags?: string[] | ((...args: Parameters<T>) => string[]);
+  },
+): T & { invalidate: () => Promise<void> };
+
+// ---------------------------------------------------------------------------
+// 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 any of `tags`. */
+export declare function revalidateTags(tags: string[]): Promise<void>;
+/** Evict the cached HTML for a path (the next request re-renders). */
+export declare function revalidatePath(path: string): Promise<void>;
+/** Evict all cached HTML (per-process generation bump). */
+export declare function revalidateAll(): Promise<void>;
+
+// ---------------------------------------------------------------------------
+// session.js
+// ---------------------------------------------------------------------------
+
+/** The session storage adapter interface. */
+export interface SessionStorage {
+  read(cookie: string): Promise<Session>;
+  save(session: Session): Promise<string>;
+}
+
+/** A per-request session: a typed key/value bag with flash + destroy. */
+export declare class Session {
+  constructor(id: string | null, initial?: Record<string, unknown>);
+  readonly id: string | null;
+  readonly dirty: boolean;
+  readonly destroyed: boolean;
+  readonly deleteId: string | null;
+  readonly data: { id: string | null; data: Record<string, unknown> };
+  get<T = unknown>(key: string): T | undefined;
+  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. */
+  flash(key: string, value: unknown): void;
+  destroy(): void;
+}
+
+/** Session middleware factory. */
+export declare function session(opts?: {
+  storage?: SessionStorage;
+  cookieName?: string;
+  secret?: string;
+  maxAge?: number;
+  path?: string;
+  httpOnly?: boolean;
+  secure?: boolean;
+  sameSite?: string;
+}): Middleware;
+/** Cookie-backed session storage. */
+export declare function cookieSessionStorage(): SessionStorage;
+/** Store-backed session storage. */
+export declare function storeSessionStorage(opts?: Record<string, unknown>): SessionStorage;
+/** Alias of `cookieSessionStorage`. */
+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;
+
+// ---------------------------------------------------------------------------
+// broadcast.js
+// ---------------------------------------------------------------------------
+
+/** Broadcast data to all WebSocket clients connected to a route path. */
+export declare function broadcast(
+  path: string,
+  data: string | Uint8Array,
+  opts?: { except?: unknown },
+): void;
+
+// ---------------------------------------------------------------------------
+// json.js
+// ---------------------------------------------------------------------------
+
+/** Content-negotiated JSON response (rich wire format when the client asks for it). */
+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. */
+export declare function readBody(req: Request): Promise<unknown>;
+
+// ---------------------------------------------------------------------------
+// sitemap.js (#276)
+// ---------------------------------------------------------------------------
+
+/** A `<urlset>` entry. */
+export interface SitemapEntry {
+  url: string;
+  lastModified?: string | Date;
+  changeFrequency?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+  priority?: number;
+}
+/** A `<sitemapindex>` child-sitemap entry. */
+export interface SitemapIndexEntry {
+  url: string;
+  lastModified?: string | Date;
+}
+/** Serialize entries into a spec-valid `<urlset>` XML document. */
+export declare function sitemap(entries: SitemapEntry[]): string;
+/** Serialize child sitemaps into a `<sitemapindex>` XML document. */
+export declare function sitemapIndex(sitemaps: SitemapIndexEntry[]): string;
+
+// ---------------------------------------------------------------------------
+// websocket.js
+// ---------------------------------------------------------------------------
+
+/** Attach WebSocket upgrade handling to an HTTP server (invokes a `route.{js,ts}` `WS` export). */
+export declare function attachWebSocket(server: import('node:http').Server, app: RequestHandler): void;
+
+// ---------------------------------------------------------------------------
+// serializer.js
+// ---------------------------------------------------------------------------
+
+/** Get the active RPC wire serializer. */
+export declare function getSerializer(): Serializer;
+/** Replace the RPC wire serializer. */
+export declare function setSerializer(serializer: Serializer): void;
+/** The default rich-type serializer. */
+export declare const defaultSerializer: Serializer;
+
+// ---------------------------------------------------------------------------
+// auth.js (NextAuth-style)
+// ---------------------------------------------------------------------------
+
+/** A provider config produced by `Credentials` / `Google` / `GitHub`. */
+export interface ProviderConfig {
+  id: string;
+  [key: string]: unknown;
+}
+
+/** Auth configuration for `createAuth`. */
+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 };
+  pages?: { signIn?: string; signOut?: string; error?: string };
+}
+
+/** The auth system created by `createAuth`. */
+export interface AuthInstance {
+  auth: (req?: Request) => Promise<{ user: Record<string, unknown> } | null>;
+  signIn: (
+    provider: string,
+    data?: Record<string, unknown>,
+    opts?: { redirectTo?: string; req?: Request },
+  ) => Promise<Response>;
+  signOut: (opts?: { redirectTo?: string; req?: Request }) => Promise<Response>;
+  handlers: { GET: (req: Request) => Promise<Response>; POST: (req: Request) => Promise<Response> };
+}
+
+/** Create the auth system. */
+export declare function createAuth(config: AuthConfig): AuthInstance;
+/** The credentials (email/password) provider. */
+export declare function Credentials(opts: Record<string, unknown>): ProviderConfig;
+/** The Google OAuth provider. */
+export declare function Google(opts?: Record<string, unknown>): ProviderConfig;
+/** The GitHub OAuth provider. */
+export declare function GitHub(opts?: Record<string, unknown>): ProviderConfig;
+
+// ---------------------------------------------------------------------------
+// Re-export the core prop / metadata types so a server consumer can reach them
+// from one place (they are the shapes server functions construct / consume).
+// ---------------------------------------------------------------------------
+
+export type { LayoutProps, PageProps, RouteHandlerContext };
diff --git a/packages/server/package.json b/packages/server/package.json
index 64b45883b..64f49ab39 100644
--- a/packages/server/package.json
+++ b/packages/server/package.json
@@ -4,14 +4,25 @@
   "type": "module",
   "description": "webjs dev/prod server: SSR, router, API, server actions, live reload",
   "main": "index.js",
+  "types": "./index.d.ts",
   "exports": {
-    ".": "./index.js",
-    "./check": "./src/check.js",
-    "./testing": "./src/testing.js",
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./check": {
+      "types": "./src/check.d.ts",
+      "default": "./src/check.js"
+    },
+    "./testing": {
+      "types": "./src/testing.d.ts",
+      "default": "./src/testing.js"
+    },
     "./webjs-config.schema.json": "./webjs-config.schema.json"
   },
   "files": [
     "index.js",
+    "index.d.ts",
     "src",
     "webjs-config.schema.json",
     "README.md"
diff --git a/packages/server/src/check.d.ts b/packages/server/src/check.d.ts
new file mode 100644
index 000000000..f5caf718c
--- /dev/null
+++ b/packages/server/src/check.d.ts
@@ -0,0 +1,38 @@
+/**
+ * Type overlay for `@webjsdev/server/check` (the convention validator backing
+ * `webjs check`, exported on its own subpath so the CLI can load it without
+ * booting the full server).
+ *
+ * The runtime is packages/server/src/check.js (JSDoc-annotated JavaScript);
+ * this overlay exists so a TypeScript consumer's `import { checkConventions }
+ * from '@webjsdev/server/check'` resolves precise types instead of emitting
+ * TS7016. Zero runtime cost.
+ */
+
+/** A single convention violation reported by `checkConventions`. */
+export interface Violation {
+  /** The rule name that fired (e.g. `no-browser-globals-in-render`). */
+  rule: string;
+  /** The offending file path. */
+  file: string;
+  /** What is wrong. */
+  message: string;
+  /** How to fix it. */
+  fix: string;
+}
+
+/** A rule's name + human description, for help text / docs. */
+export interface RuleDescriptor {
+  name: string;
+  description: string;
+}
+
+/** All available correctness rules with descriptions. */
+export declare const RULES: RuleDescriptor[];
+
+/**
+ * Run every correctness check against an app directory, returning the list of
+ * violations (empty when the app is clean). Correctness-only; report-only, no
+ * autofix.
+ */
+export declare function checkConventions(appDir: string): Promise<Violation[]>;
diff --git a/packages/server/src/testing.d.ts b/packages/server/src/testing.d.ts
new file mode 100644
index 000000000..046ccaa64
--- /dev/null
+++ b/packages/server/src/testing.d.ts
@@ -0,0 +1,123 @@
+/**
+ * Type overlay for `@webjsdev/server/testing` (the handle() test harness, #267).
+ *
+ * The runtime is packages/server/src/testing.js (JSDoc-annotated JavaScript);
+ * this overlay exists so a TypeScript app's `import { testRequest, getCsrf }
+ * from '@webjsdev/server/testing'` resolves precise types instead of emitting
+ * TS7016. The same declarations are re-exported from the package's main
+ * `index.d.ts` (the helpers ship from both entry points). Zero runtime cost.
+ */
+
+/** The `handle(req)` function returned by `createRequestHandler`. */
+export type Handle = (req: Request) => Promise<Response> | Response;
+
+/** A `createRequestHandler` return value, or a bare `handle` function. */
+export type AppOrHandle = { handle: Handle; appDir: string } | Handle;
+
+/** A CSRF token + cookie + header-name triple minted off the first SSR response. */
+export interface CsrfPair {
+  /** The bare token value for the `x-webjs-csrf` request header. */
+  token: string;
+  /** The header NAME (`x-webjs-csrf`). */
+  header: string;
+  /** The `name=value` cookie string for the `Cookie` request header. */
+  cookie: string;
+}
+
+/**
+ * Coerce a bare path, full URL string, or pre-built `Request` into a `Request`.
+ * A bare path is prefixed with a dummy origin; `init` is merged when provided.
+ */
+export declare function toRequest(input: string | Request, init?: RequestInit): Request;
+
+/**
+ * Fire a request through the real `handle()` pipeline and return the `Response`.
+ * The documented one-liner: `await testRequest(app.handle, '/about')`.
+ */
+export declare function testRequest(
+  handle: Handle,
+  input: string | Request,
+  init?: RequestInit,
+): Promise<Response>;
+
+/** Read the `webjs_csrf` cookie value off a response's `Set-Cookie` header(s). */
+export declare function readCsrfCookie(res: Response): string | null;
+
+/** Collect all `Set-Cookie` header values off a response. */
+export declare function getSetCookies(res: Response): string[];
+
+/** Reduce raw `Set-Cookie` strings to a single `name=value; name2=value2` `Cookie` header value. */
+export declare function cookiesToHeader(setCookies: string[]): string;
+
+/**
+ * Mint a `{ token, header, cookie }` CSRF triple off the first SSR response.
+ * `path` is the GET path used to issue the cookie (default `/`).
+ */
+export declare function getCsrf(handle: Handle, path?: string): Promise<CsrfPair>;
+
+/** Merge an extra cookie string into a `RequestInit`'s `Cookie` header. */
+export declare function withCookies(init: RequestInit | undefined, cookieValue: string): RequestInit;
+
+/** Merge a session cookie string into a `RequestInit`'s `Cookie` header. */
+export declare function withSessionCookie(init: RequestInit | undefined, sessionCookie: string): RequestInit;
+
+/**
+ * Drive the REAL credentials login (`POST /api/auth/signin/credentials` by
+ * default) and capture the genuine signed session `Set-Cookie`.
+ */
+export declare function loginAndGetCookies(
+  handle: Handle,
+  credentials: { email: string; password: string },
+  opts?: {
+    loginPath?: string;
+    method?: string;
+    body?: BodyInit;
+    contentType?: string;
+    expectStatuses?: number[];
+  },
+): Promise<{ cookies: string; setCookies: string[]; response: Response }>;
+
+/**
+ * Compute the `/__webjs/action/<hash>/<fn>` RPC endpoint path for an action,
+ * addressing it the same way the generated client stub does.
+ */
+export declare function actionEndpoint(
+  appDir: string,
+  serverFilePath: string,
+  fnName: string,
+): Promise<string>;
+
+/**
+ * Round-trip an action through its REAL RPC endpoint (serializer + CSRF + prod
+ * error sanitization) and return the parsed return value.
+ */
+export declare function invokeActionForTest<T = unknown>(
+  app: AppOrHandle,
+  serverFilePath: string,
+  fnName: string,
+  args?: unknown[],
+  opts?: {
+    csrf?: CsrfPair;
+    appDir?: string;
+    extraCookies?: string;
+    throwOnError?: boolean;
+  },
+): Promise<T>;
+
+/**
+ * Lower-level variant of `invokeActionForTest` that returns the raw `Response`
+ * (never throws on a non-2xx), so a test can assert the status directly.
+ */
+export declare function rawActionRequest(
+  app: AppOrHandle,
+  serverFilePath: string,
+  fnName: string,
+  args?: unknown[],
+  opts?: {
+    csrf?: CsrfPair | null;
+    omitCsrf?: boolean;
+    appDir?: string;
+    extraCookies?: string;
+    contentType?: string;
+  },
+): Promise<Response>;
diff --git a/packages/server/test/types/exports-drift.test.mjs b/packages/server/test/types/exports-drift.test.mjs
new file mode 100644
index 000000000..eef28680f
--- /dev/null
+++ b/packages/server/test/types/exports-drift.test.mjs
@@ -0,0 +1,64 @@
+/**
+ * Drift guard (#310): the set of named exports declared in `index.d.ts` MUST
+ * exactly match the named runtime exports of `index.js`. So a future export
+ * added to index.js without a matching type (or a type left behind after a
+ * runtime export is removed) is caught here, not by an app hitting TS7016.
+ *
+ * The runtime side is authoritative: we import the module and read its keys.
+ * The type side is parsed statically from `index.d.ts`, expanding the
+ * `export * from './src/testing.d.ts'` re-export by also parsing that file
+ * (the testing helpers ship from both entry points).
+ *
+ * Type-only re-exports (e.g. `export type { PageProps } from '@webjsdev/core'`)
+ * and local helper TYPE aliases (Middleware, ActionResult, CacheStore, …) are
+ * NOT runtime exports, so they are excluded from the comparison: the contract
+ * is "every runtime export has a declaration", not "the files are identical".
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import * as server from '../../index.js';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const serverDir = join(here, '../..');
+
+/**
+ * Collect the names a `.d.ts` declares as RUNTIME-VALUE exports:
+ *   - `export declare function NAME`
+ *   - `export declare const NAME`
+ *   - `export declare class NAME`
+ * Pure type exports (`export type`, `export interface`) are values-of-types and
+ * are intentionally skipped.
+ */
+function declaredValueExports(dtsPath) {
+  const src = readFileSync(dtsPath, 'utf8');
+  const names = new Set();
+  const re = /export\s+declare\s+(?:async\s+)?(?:function|const|class)\s+([A-Za-z_$][\w$]*)/g;
+  let m;
+  while ((m = re.exec(src))) names.add(m[1]);
+  return names;
+}
+
+test('index.d.ts declares every runtime export of index.js (no drift)', () => {
+  const runtime = new Set(Object.keys(server).filter((k) => k !== 'default'));
+
+  const declared = declaredValueExports(join(serverDir, 'index.d.ts'));
+  // `export * from './src/testing.d.ts'` pulls the testing helpers in.
+  for (const n of declaredValueExports(join(serverDir, 'src/testing.d.ts'))) {
+    declared.add(n);
+  }
+
+  const missing = [...runtime].filter((n) => !declared.has(n)).sort();
+  const extra = [...declared].filter((n) => !runtime.has(n)).sort();
+
+  assert.deepEqual(
+    { missing, extra },
+    { missing: [], extra: [] },
+    `index.d.ts drifted from index.js.\n` +
+      (missing.length ? `  Runtime exports with NO declaration: ${missing.join(', ')}\n` : '') +
+      (extra.length ? `  Declarations with NO runtime export: ${extra.join(', ')}\n` : ''),
+  );
+});
diff --git a/packages/server/test/types/server-exports.test-d.ts b/packages/server/test/types/server-exports.test-d.ts
new file mode 100644
index 000000000..c92162513
--- /dev/null
+++ b/packages/server/test/types/server-exports.test-d.ts
@@ -0,0 +1,133 @@
+/**
+ * Compile-time type fixture for the `@webjsdev/server` public surface (#310).
+ *
+ * NOT executed by node:test directly. The runner `server-types.test.mjs`
+ * consumes it via `tsc --noEmit` under `strict` + `nodenext` (the same
+ * resolution a scaffolded app uses), so a missing or wrong declaration is a
+ * build failure here. The headline acceptance is that the bare server import
+ * resolves a declaration instead of emitting TS7016.
+ *
+ * Each `// @ts-expect-error` line is a self-checking counterfactual: tsc reports
+ * an "unused @ts-expect-error" if the type ever widens to accept the bad value.
+ */
+
+import {
+  createRequestHandler,
+  startServer,
+  cors,
+  cache,
+  createAuth,
+  rateLimit,
+  sitemap,
+  sitemapIndex,
+  Session,
+  json,
+  readBody,
+  revalidatePath,
+  revalidateTag,
+  broadcast,
+  headers,
+  cookies,
+  getRequest,
+  requestId,
+  memoryStore,
+  redisStore,
+  getStore,
+  setStore,
+  defaultLogger,
+  validateEnv,
+} from '@webjsdev/server';
+import { testRequest, getCsrf } from '@webjsdev/server/testing';
+import { checkConventions } from '@webjsdev/server/check';
+
+// createRequestHandler resolves to the documented handler shape.
+const app: Promise<{ handle: (r: Request) => Promise<Response> }> =
+  createRequestHandler({ appDir: '.' });
+
+// startServer takes options + a port and resolves to a server handle.
+async function boot() {
+  const srv = await startServer({ appDir: '.', port: 3000 });
+  await srv.close();
+}
+
+// sitemap / sitemapIndex are pure string serializers.
+const xml: string = sitemap([{ url: 'https://x.com', priority: 0.5 }]);
+const xml2: string = sitemapIndex([{ url: 'https://x.com/s.xml' }]);
+
+// cors / rateLimit return middleware.
+const corsMw = cors({ origin: ['https://app.example.com'], credentials: true });
+const rlMw = rateLimit({ window: '1m', max: 60 });
+
+// cache preserves the wrapped function signature + adds .invalidate().
+const getPost = cache(async (id: string) => ({ id }), { key: 'post', ttl: 60, tags: (id) => ['post:' + id] });
+async function useCache() {
+  const post = await getPost('5');
+  const _id: string = post.id;
+  await getPost.invalidate();
+  void _id;
+}
+
+// The store / cache-invalidation surface.
+const store = memoryStore();
+setStore(store);
+async function invalidate() {
+  await revalidatePath('/blog');
+  await revalidateTag('post:5');
+}
+
+// Auth factory.
+const authInst = createAuth({ secret: 's', providers: [] });
+
+// Session class.
+function useSession(s: Session) {
+  const v = s.get<string>('userId');
+  s.set('userId', 'x');
+  void v;
+}
+
+// Testing helpers consume a handle.
+async function useTesting(handle: (r: Request) => Promise<Response>) {
+  const res = await testRequest(handle, '/about');
+  const csrf = await getCsrf(handle);
+  const _ok: boolean = res.ok;
+  const _t: string = csrf.token;
+  void _ok;
+  void _t;
+}
+
+// checkConventions returns violations.
+async function check() {
+  const violations = await checkConventions('.');
+  const _rule: string = violations[0]?.rule ?? '';
+  void _rule;
+}
+
+// @ts-expect-error appDir is required.
+createRequestHandler({});
+
+// @ts-expect-error sitemap takes an array of entries, not a bare string.
+sitemap('not-an-array');
+
+void boot;
+void app;
+void xml;
+void xml2;
+void corsMw;
+void rlMw;
+void useCache;
+void invalidate;
+void getStore;
+void redisStore;
+void json;
+void readBody;
+void broadcast;
+void headers;
+void cookies;
+void getRequest;
+void requestId;
+void defaultLogger;
+void validateEnv;
+void authInst;
+void useSession;
+void useTesting;
+void check;
diff --git a/packages/server/test/types/server-types.test.mjs b/packages/server/test/types/server-types.test.mjs
new file mode 100644
index 000000000..4ed345766
--- /dev/null
+++ b/packages/server/test/types/server-types.test.mjs
@@ -0,0 +1,96 @@
+/**
+ * Runs `tsc --noEmit` over the `@webjsdev/server` type fixture (#310) under
+ * `strict` + `nodenext` (the SAME resolution a scaffolded app's tsconfig uses,
+ * see packages/cli/lib/create.js), proving the public server surface is typed
+ * and the bare import no longer emits TS7016.
+ *
+ * Three assertions:
+ *  1. The full fixture compiles clean (every export typed, the two
+ *     `@ts-expect-error` counterfactuals genuinely error).
+ *  2. COUNTERFACTUAL: with `index.d.ts` temporarily moved aside, the same
+ *     server import errors TS7016 and tsc exits non-zero. This proves the
+ *     overlay (not something else) is what fixes the gap.
+ *  3. The overlay restored, the bare import is clean again.
+ *
+ * `--skipLibCheck` is on for the same reason as the root type-fixtures runner:
+ * the framework runtime is JSDoc-typed `.js`, so its implicit-any internals are
+ * noise unrelated to the fixture's own checks.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { existsSync, renameSync, writeFileSync, rmSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url));
+const tscBin = join(repoRoot, 'node_modules/typescript/bin/tsc');
+const indexDts = join(repoRoot, 'packages/server/index.d.ts');
+
+const TSC_FLAGS = [
+  '--noEmit',
+  '--strict',
+  '--target', 'esnext',
+  '--module', 'nodenext',
+  '--moduleResolution', 'nodenext',
+  '--lib', 'esnext,dom',
+  '--skipLibCheck',
+];
+
+function runTsc(file) {
+  return spawnSync(process.execPath, [tscBin, ...TSC_FLAGS, file], { encoding: 'utf8' });
+}
+
+test('server type fixture compiles clean under strict + nodenext', () => {
+  assert.ok(existsSync(tscBin), 'typescript must be installed');
+  const res = runTsc(join(here, 'server-exports.test-d.ts'));
+  assert.equal(
+    res.status,
+    0,
+    `tsc reported errors for the server type fixture:\n${res.stdout}${res.stderr}`,
+  );
+});
+
+test('TS7016 counterfactual: removing index.d.ts breaks the bare server import', () => {
+  // A minimal import-only fixture. It must live INSIDE the repo tree so
+  // nodenext resolution finds the workspace `node_modules/@webjsdev/server`.
+  const probe = join(here, '.ts7016-probe.ts');
+  writeFileSync(
+    probe,
+    `import { createRequestHandler } from '@webjsdev/server';\nvoid createRequestHandler;\n`,
+  );
+
+  // Sanity: with the overlay present the probe is clean.
+  const withOverlay = runTsc(probe);
+  assert.equal(
+    withOverlay.status,
+    0,
+    `expected the probe to type-check WITH index.d.ts present:\n${withOverlay.stdout}${withOverlay.stderr}`,
+  );
+
+  // Move the overlay aside and confirm TS7016 fires. Restore in `finally` so a
+  // failure can never leave the repo without its declaration file.
+  const stash = indexDts + '.ts7016-stash';
+  renameSync(indexDts, stash);
+  try {
+    const withoutOverlay = runTsc(probe);
+    assert.notEqual(
+      withoutOverlay.status,
+      0,
+      'expected tsc to FAIL without index.d.ts (TS7016)',
+    );
+    assert.match(
+      withoutOverlay.stdout + withoutOverlay.stderr,
+      /TS7016/,
+      'expected a TS7016 "could not find a declaration file" error',
+    );
+  } finally {
+    renameSync(stash, indexDts);
+    rmSync(probe, { force: true });
+  }
+
+  // The overlay restored, the bare import is clean again.
+  const restored = runTsc(join(here, 'server-exports.test-d.ts'));
+  assert.equal(restored.status, 0, 'fixture should be clean again after restore');
+});

From e93a9044b5ce6ebc8d166af67bbeec8d3dd8fb25 Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Wed, 3 Jun 2026 21:11:01 +0530
Subject: [PATCH 2/3] fix: correct Session.data/redisStore/save types +
 drift-test filename in #310 overlay

---
 packages/server/AGENTS.md  | 2 +-
 packages/server/index.d.ts | 8 ++++----
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/packages/server/AGENTS.md b/packages/server/AGENTS.md
index 76d3ce1c6..b760911d2 100644
--- a/packages/server/AGENTS.md
+++ b/packages/server/AGENTS.md
@@ -113,7 +113,7 @@ condition (FIRST in the object, as nodenext requires) wire the resolution; the
 top-level `index.d.ts` is added to the `files` allowlist (`src/*.d.ts` ships via
 the globbed `src`). **A new export added to `index.js` MUST get a declaration in
 `index.d.ts`,** enforced by the drift test
-`test/types/exports-drift.test.js` (asserts the declared set equals the runtime
+`test/types/exports-drift.test.mjs` (asserts the declared set equals the runtime
 export set); the type fixture + TS7016 counterfactual live in
 `test/types/server-exports.test-d.ts` + `test/types/server-types.test.mjs`.
 
diff --git a/packages/server/index.d.ts b/packages/server/index.d.ts
index c749de0ee..4cc2f392f 100644
--- a/packages/server/index.d.ts
+++ b/packages/server/index.d.ts
@@ -16,7 +16,7 @@
  * (scanner / importmap / module-graph / vendor) get reasonable structural
  * declarations.
  *
- * The drift guard `test/types/exports-drift.test.js` asserts the set of named
+ * The drift guard `test/types/exports-drift.test.mjs` asserts the set of named
  * exports here exactly matches the runtime named exports of index.js, so a
  * future export added to index.js without a type is caught.
  */
@@ -460,7 +460,7 @@ export declare function applyCorsHeaders(
 /** In-memory LRU cache store (single-process). */
 export declare function memoryStore(opts?: { maxSize?: number }): CacheStore;
 /** Redis-backed cache store. */
-export declare function redisStore(opts?: Record<string, unknown>): CacheStore;
+export declare function redisStore(opts?: { url?: string }): CacheStore;
 /** Get the default cache store (memory unless `setStore` was called). */
 export declare function getStore(): CacheStore;
 /** Set the default cache store (call at startup to switch to Redis). */
@@ -500,7 +500,7 @@ export declare function revalidateAll(): Promise<void>;
 /** The session storage adapter interface. */
 export interface SessionStorage {
   read(cookie: string): Promise<Session>;
-  save(session: Session): Promise<string>;
+  save(session: Session): Promise<string | null>;
 }
 
 /** A per-request session: a typed key/value bag with flash + destroy. */
@@ -510,7 +510,7 @@ export declare class Session {
   readonly dirty: boolean;
   readonly destroyed: boolean;
   readonly deleteId: string | null;
-  readonly data: { id: string | null; data: Record<string, unknown> };
+  readonly data: { data: Record<string, unknown>; flash: Record<string, unknown> };
   get<T = unknown>(key: string): T | undefined;
   set(key: string, value: unknown): void;
   has(key: string): boolean;

From a37d05552383820ed0f73e4f1f82a5b051eb101c Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Wed, 3 Jun 2026 21:17:34 +0530
Subject: [PATCH 3/3] fix: move server type fixture to test/types so buildless
 invariant passes

The Conventions CI step rejects any .ts under packages/{core,server,cli,
ts-plugin} that is not a .d.ts. The new type fixture was server-exports.test-d.ts
under packages/server/test/, whose name ends in .test-d.ts (not .d.ts), so the
buildless grep flagged it as TS source in a buildless package. Every other
.test-d.ts already lives at the repo-root test/types/ (outside packages/), so
move the fixture + its nodenext runner there to match the convention; the drift
guard stays near the package (a .mjs, which the grep ignores).
---
 packages/server/AGENTS.md                                 | 8 +++++---
 packages/server/index.d.ts                                | 2 +-
 .../server/test => test}/types/server-exports.test-d.ts   | 0
 .../server/test => test}/types/server-types.test.mjs      | 2 +-
 4 files changed, 7 insertions(+), 5 deletions(-)
 rename {packages/server/test => test}/types/server-exports.test-d.ts (100%)
 rename {packages/server/test => test}/types/server-types.test.mjs (97%)

diff --git a/packages/server/AGENTS.md b/packages/server/AGENTS.md
index b760911d2..fb5ca48ac 100644
--- a/packages/server/AGENTS.md
+++ b/packages/server/AGENTS.md
@@ -113,9 +113,11 @@ condition (FIRST in the object, as nodenext requires) wire the resolution; the
 top-level `index.d.ts` is added to the `files` allowlist (`src/*.d.ts` ships via
 the globbed `src`). **A new export added to `index.js` MUST get a declaration in
 `index.d.ts`,** enforced by the drift test
-`test/types/exports-drift.test.mjs` (asserts the declared set equals the runtime
-export set); the type fixture + TS7016 counterfactual live in
-`test/types/server-exports.test-d.ts` + `test/types/server-types.test.mjs`.
+`packages/server/test/types/exports-drift.test.mjs` (asserts the declared set
+equals the runtime export set); the type fixture + TS7016 counterfactual live at
+the repo-root `test/types/server-exports.test-d.ts` + `test/types/server-types.test.mjs`
+(every `.test-d.ts` lives there, outside `packages/`, so the buildless-no-`.ts`
+invariant does not flag it).
 
 ## The `webjs` package.json config block (typed surface, #259)
 
diff --git a/packages/server/index.d.ts b/packages/server/index.d.ts
index 4cc2f392f..3809081be 100644
--- a/packages/server/index.d.ts
+++ b/packages/server/index.d.ts
@@ -16,7 +16,7 @@
  * (scanner / importmap / module-graph / vendor) get reasonable structural
  * declarations.
  *
- * The drift guard `test/types/exports-drift.test.mjs` asserts the set of named
+ * The drift guard `packages/server/test/types/exports-drift.test.mjs` asserts the set of named
  * exports here exactly matches the runtime named exports of index.js, so a
  * future export added to index.js without a type is caught.
  */
diff --git a/packages/server/test/types/server-exports.test-d.ts b/test/types/server-exports.test-d.ts
similarity index 100%
rename from packages/server/test/types/server-exports.test-d.ts
rename to test/types/server-exports.test-d.ts
diff --git a/packages/server/test/types/server-types.test.mjs b/test/types/server-types.test.mjs
similarity index 97%
rename from packages/server/test/types/server-types.test.mjs
rename to test/types/server-types.test.mjs
index 4ed345766..d2c89e6a1 100644
--- a/packages/server/test/types/server-types.test.mjs
+++ b/test/types/server-types.test.mjs
@@ -24,7 +24,7 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const here = dirname(fileURLToPath(import.meta.url));
-const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url));
+const repoRoot = fileURLToPath(new URL('../../', import.meta.url));
 const tscBin = join(repoRoot, 'node_modules/typescript/bin/tsc');
 const indexDts = join(repoRoot, 'packages/server/index.d.ts');