@webjsdev/server 0.8.44 → 0.8.46

package/index.d.ts

@@ -212,6 +212,23 @@ export declare function applyEnvValidation(
   opts?: { dev?: boolean; env?: Record<string, string | undefined> },
 ): Promise<void>;
 
+// ---------------------------------------------------------------------------
+// instrumentation.js (#848)
+// ---------------------------------------------------------------------------
+
+/**
+ * Register an error sink from inside `instrumentation.register()`. Composes with
+ * the `createRequestHandler({ onError })` option (both fire).
+ */
+export declare function setOnError(
+  fn: (error: unknown, ctx?: { request?: Request; requestId?: string; phase?: string }) => void,
+): void;
+/** Run the app's boot-time `instrumentation.{js,ts}` hook once; returns any registered error sink. */
+export declare function runInstrumentation(
+  appDir: string,
+  opts?: { dev?: boolean; logger?: { error?: (...a: unknown[]) => void } },
+): Promise<{ onError: ((error: unknown, ctx?: unknown) => void) | null }>;
+
 // ---------------------------------------------------------------------------
 // router.js
 // ---------------------------------------------------------------------------

package/index.js

@@ -1,6 +1,7 @@
 export { startServer, createRequestHandler } from './src/dev.js';
 export { assertNodeVersion, checkNodeVersion, requiredNodeMajor, parseMajor, parseRequiredMajor } from './src/node-version.js';
 export { validateEnv, formatEnvErrors, loadEnvSchema, applyEnvValidation } from './src/env-schema.js';
+export { setOnError, runInstrumentation } from './src/instrumentation.js';
 export { buildRouteTable, matchPage, matchApi } from './src/router.js';
 export { generateRouteTypes } from './src/route-types.js';
 export { ssrPage, ssrNotFound } from './src/ssr.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.44",
+  "version": "0.8.46",
   "type": "module",
   "description": "webjs dev/prod server: SSR, router, API, server actions, live reload",
   "main": "index.js",

package/src/action-error.js

@@ -18,7 +18,7 @@
  * @module action-error
  */
 
-import { isRedirect, isNotFound } from '@webjsdev/core';
+import { isRedirect, isNotFound, isForbidden, isUnauthorized } from '@webjsdev/core';
 import { digestHex } from './crypto-utils.js';
 
 /** The generic client-facing message for a sanitized prod action error. */
@@ -38,7 +38,7 @@ export const GENERIC_ERROR_MESSAGE = 'Internal server error';
  * @returns {boolean}
  */
 export function isControlFlowThrow(err) {
-  return isRedirect(err) || isNotFound(err);
+  return isRedirect(err) || isNotFound(err) || isForbidden(err) || isUnauthorized(err);
 }
 
 /**

package/src/action-route.js

@@ -1,7 +1,7 @@
 /**
  * The optional `route(action, opts?)` convenience adapter (#488).
  *
- * REST endpoints in webjs go through `route.ts` (the framework's first-class
+ * REST endpoints in WebJs go through `route.ts` (the framework's first-class
  * HTTP handler). The ALWAYS-WORKS baseline is a hand-written `route.ts` that
  * imports a `'use server'` action and calls it:
  *
@@ -28,6 +28,22 @@
  * export const POST = route(createPost, { validate: createPostSchema });
  * ```
  *
+ * Passing the action's MODULE NAMESPACE instead of the function auto-applies the
+ * action's declared `export const middleware` and `export const validate`, so a
+ * guard declared once next to the action protects the REST boundary the same way
+ * it protects the RPC boundary (#876). This is the way to keep "declare once,
+ * protected on every entry point" true without re-listing the config:
+ *
+ * ```js
+ * // app/api/posts/route.ts
+ * import { route } from '@webjsdev/server';
+ * import * as postActions from '../../../modules/posts/actions/create-post.server.ts';
+ * export const POST = route(postActions);   // its declared middleware + validate apply
+ * ```
+ *
+ * The function form still takes explicit `opts`, and an explicit `opts.middleware`
+ * / `opts.validate` overrides the module's declared config when both are given.
+ *
  * Adapter rules when invoked over HTTP:
  *   - URL query params, route params (`ctx.params`), and the parsed JSON body
  *     (for a method with a body) are merged into a single object argument
@@ -51,6 +67,7 @@
 import { runValidate } from './actions.js';
 import { runWithActionSignal } from './action-signal.js';
 import { runActionChain } from './action-middleware.js';
+import { actionFunctionNames, actionMiddleware } from './action-config.js';
 import { readTextBounded, payloadTooLarge, DEFAULT_MAX_BODY_BYTES } from './body-limit.js';
 import { getBodyLimits } from './context.js';
 
@@ -69,16 +86,48 @@ function jsonBodyLimit() {
  * Expose a plain `'use server'` action over REST as a `route.ts`-style handler.
  *
  * @template A, R
- * @param {(input: A, ctx: { req: Request, params: Record<string,string> }) => R | Promise<R>} action
- *   the server action to call (its source is unchanged; this only wraps the
- *   HTTP-to-action adapter around it).
+ * @param {((input: A, ctx: { req: Request, params: Record<string,string> }) => R | Promise<R>) | Record<string, unknown>} actionOrModule
+ *   the server action to call, OR the action's module namespace (`import * as m`)
+ *   so its declared `middleware` / `validate` config is auto-applied (#876). Its
+ *   source is unchanged; this only wraps the HTTP-to-action adapter around it.
  * @param {{
  *   validate?: (input: any) => any,
  *   middleware?: Function[],
  * }} [opts]
  * @returns {(req: Request, ctx?: { params?: Record<string,string> }) => Promise<Response>}
  */
-export function route(action, opts = {}) {
+export function route(actionOrModule, opts = {}) {
+  // Resolve the callable action plus any config the caller did not pass
+  // explicitly. A function is used verbatim (the original form). A module
+  // namespace exposes the single action function and its declared config, so
+  // `route(mod)` inherits the same `middleware` / `validate` the RPC boundary
+  // reads (#876). An explicit `opts` value still wins over the declared one.
+  let action;
+  /** @type {{ middleware?: Function[], validate?: Function }} */
+  let declared = {};
+  if (typeof actionOrModule === 'function') {
+    action = actionOrModule;
+  } else if (actionOrModule && typeof actionOrModule === 'object') {
+    const names = actionFunctionNames(actionOrModule);
+    if (names.length !== 1) {
+      throw new Error(
+        `route(module) expects exactly one action function in the module, found ${names.length}` +
+          (names.length ? ` (${names.join(', ')})` : ''),
+      );
+    }
+    action = /** @type {Function} */ (actionOrModule[names[0]]);
+    declared = {
+      middleware: actionMiddleware(actionOrModule),
+      validate: typeof actionOrModule.validate === 'function'
+        ? /** @type {Function} */ (actionOrModule.validate)
+        : undefined,
+    };
+  } else {
+    throw new Error('route() expects an action function or a module namespace');
+  }
+  const validate = opts.validate ?? declared.validate;
+  const middlewareChain = opts.middleware ?? declared.middleware ?? [];
+
   return async function handler(req, ctx) {
     const params = (ctx && ctx.params) || {};
     const url = new URL(req.url);
@@ -102,13 +151,13 @@ export function route(action, opts = {}) {
     }
 
     let arg = { ...query, ...params, ...body };
-    if (typeof opts.validate === 'function') {
+    if (typeof validate === 'function') {
       // Run the validator through the SHARED contract (#245) so the REST adapter
       // and the RPC path interpret a `{ success, fieldErrors }` envelope, a
       // throw, and a transform-return identically. A structured failure becomes
       // a 422 JSON; a throw stays a 400 (keeping a schema lib's `issues`); a
       // transform-return replaces the input.
-      const v = runValidate(opts.validate, arg);
+      const v = runValidate(validate, arg);
       if (!v.ok) {
         if (v.thrown !== undefined) {
           const msg = v.result.error || 'Invalid input';
@@ -126,10 +175,9 @@ export function route(action, opts = {}) {
     // The action runs inside the request signal scope (#492) and the per-action
     // middleware chain (#490). `ranAction` distinguishes a real completion from
     // a middleware short-circuit (the action never ran).
-    const middleware = opts.middleware || [];
     let ranAction = false;
     const result = await runWithActionSignal(req.signal, () =>
-      runActionChain(middleware, { request: req, args: [arg], signal: req.signal }, () => {
+      runActionChain(middlewareChain, { request: req, args: [arg], signal: req.signal }, () => {
         ranAction = true;
         return action(/** @type any */ (arg), { req, params });
       }));

package/src/actions.js

@@ -33,12 +33,12 @@ function jsonBodyLimit() {
 }
 
 /**
- * Internal RPC wire-format content type. Distinguishes webjs action
+ * Internal RPC wire-format content type. Distinguishes WebJs action
  * responses from plain `application/json` so the stub can pick the right
  * parser and external JSON consumers aren't confused.
  *
  * Uses the content type from the active serializer (defaults to
- * `application/vnd.webjs+json` with the built-in webjs serializer).
+ * `application/vnd.webjs+json` with the built-in WebJs serializer).
  */
 export const RPC_CONTENT_TYPE = 'application/vnd.webjs+json';
 

package/src/api.js

@@ -1,4 +1,5 @@
 import { pathToFileURL } from 'node:url';
+import { makeThenable } from './thenable-params.js';
 
 /**
  * Dispatch an incoming request to a matched API route.
@@ -24,10 +25,14 @@ export async function handleApi(route, params, webRequest, dev) {
       headers: { allow: allowedMethods(mod).join(', ') },
     });
   }
-  /** @type any */ (webRequest).params = params;
+  // Route-handler params are awaitable AND sync-readable (#848, Next parity:
+  // `const { id } = await params`). Non-enumerable `then`, so a handler that
+  // spreads / JSON-stringifies params is unaffected.
+  const thenableParams = makeThenable(params);
+  /** @type any */ (webRequest).params = thenableParams;
   let result;
   try {
-    result = await handler(webRequest, { params });
+    result = await handler(webRequest, { params: thenableParams });
   } catch (e) {
     // A route handler that read its body via `readBody` (json.js) over the
     // size limit (issue #237) throws a BodyLimitError; surface it as 413 rather

package/src/auth.js

@@ -1,5 +1,5 @@
 /**
- * NextAuth/Auth.js-style authentication for webjs.
+ * NextAuth/Auth.js-style authentication for WebJs.
  *
  * JWT or database sessions, Credentials + OAuth (Google, GitHub) providers.
  * Uses Web Crypto HMAC-SHA256: no external dependencies.

package/src/body-limit.js

@@ -252,7 +252,7 @@ export async function readBytesBounded(req, limit) {
 /**
  * Read a request body as text, bounded by `limit`. Used by the RPC endpoint,
  * `readBody`, and the exposed-action REST path, all of which then parse the
- * text (webjs wire or JSON).
+ * text (WebJs wire or JSON).
  *
  * @param {Request} req
  * @param {number} limit max bytes (0 / negative = unlimited)

package/src/check.js

@@ -14,7 +14,7 @@ import { analyzeElision } from './component-elision.js';
 import { RESERVED_CONFIG } from './action-config.js';
 
 /**
- * Convention validator for webjs apps.
+ * Convention validator for WebJs apps.
  *
  * Scans an app directory and reports correctness violations: things that
  * crash the app, leak a secret, or fail the build / type-strip. Designed to be
@@ -380,7 +380,7 @@ function findBrowserMemberUses(code) {
 }
 
 /**
- * Scan a webjs app directory and report convention violations.
+ * Scan a WebJs app directory and report convention violations.
  *
  * Every rule is a correctness check (a crash, a security leak, or a
  * build/type-strip failure), so they all run unconditionally. There is no
@@ -436,7 +436,7 @@ export async function checkConventions(appDir) {
       // redactor leaves them alone.
       if (!/class\s+\w+\s+extends\s+WebComponent/.test(scan)) continue;
       // Accept either registration pattern:
-      //   Counter.register('tag')                    (webjs idiom)
+      //   Counter.register('tag')                    (WebJs idiom)
       //   customElements.define('tag', Counter)      (native)
       if (/\b[A-Z][A-Za-z0-9_$]*\.register\s*\(\s*['"`]/.test(scan)) continue;
       if (/\bcustomElements\.define\s*\(/.test(scan)) continue;
@@ -1208,7 +1208,7 @@ function findImportChain(graph, from, to) {
  * @param {Violation[]} violations  appended to in place
  */
 async function checkServerImportInBrowserModule(appDir, violations) {
-  // No `app/` directory means this is not a routable webjs app (e.g. a bare
+  // No `app/` directory means this is not a routable WebJs app (e.g. a bare
   // component library, or a fixture with only `lib/`); nothing ships, so the
   // rule has nothing to police. Skip rather than do the heavy analysis.
   if (!(await pathExists(join(appDir, 'app')))) return;

package/src/component-elision.js

@@ -1,5 +1,5 @@
 /**
- * Static analyser deciding whether a webjs component module can be
+ * Static analyser deciding whether a WebJs component module can be
  * ELIDED from the browser, that is, never downloaded as JS because its
  * SSR'd HTML is the complete, final output and the component does no
  * client-side work.
@@ -34,7 +34,7 @@
  *      packages/core/AGENTS.md and the MAINTAINER NOTE on the
  *      WebComponent lifecycle in packages/core/src/component.js both
  *      direct anyone adding an interactivity surface to update these
- *      lists, since webjs development is largely AI-agent driven.
+ *      lists, since WebJs development is largely AI-agent driven.
  */
 
 import {
@@ -101,7 +101,7 @@ export const CLIENT_LIFECYCLE_HOOKS = [
   'connectedCallback',
   'disconnectedCallback',
   'attributeChangedCallback',
-  // Standard custom-element callback webjs does not itself define (so it
+  // Standard custom-element callback WebJs does not itself define (so it
   // is absent from the prototype guard's CLASSIFICATION), but an author
   // can still override it to do client work. Kept for conservatism.
   'adoptedCallback',

package/src/component-scanner.js

@@ -1,13 +1,13 @@
 /**
  * Server-side scanner that walks the app tree and records the
- * browser-visible URL for every webjs component module.
+ * browser-visible URL for every WebJs component module.
  *
  * Called once on the first request (lazily, via `ensureReady`), then memoized. Results are used to prime the core
  * registry (`primeModuleUrl`) BEFORE any SSR render: so when a page
  * renders a component tag, `lookupModuleUrl(tag)` already has the URL
  * ready for `<link rel="modulepreload">` hints.
  *
- * The convention webjs uses is the web-standard one:
+ * The convention WebJs uses is the web-standard one:
  *
  *     class Counter extends WebComponent { … }
  *     customElements.define('my-counter', Counter);

package/src/cors.js

@@ -1,7 +1,7 @@
 /**
- * Reusable CORS primitive for webjs.
+ * Reusable CORS primitive for WebJs.
  *
- * `cors(options)` returns a webjs MIDDLEWARE `(req, next) => Response`,
+ * `cors(options)` returns a WebJs MIDDLEWARE `(req, next) => Response`,
  * usable in `middleware.js` (root or per-segment) or wrapped around a
  * `route.js` handler. This is the public app-facing API. The shared
  * origin-resolution + header-building core (`resolveOrigin` /

package/src/csp.js

@@ -181,7 +181,7 @@ export function readCspConfig(pkg) {
 export function mintNonce() {
   const bytes = new Uint8Array(16);
   crypto.getRandomValues(bytes);
-  // Buffer is available in every webjs server runtime (Node 24+). Avoids a
+  // Buffer is available in every WebJs server runtime (Node 24+). Avoids a
   // hand-rolled base64 of a binary string.
   return Buffer.from(bytes).toString('base64');
 }

package/src/csrf.js

@@ -4,7 +4,7 @@
  * `cop-middleware` and Go 1.25's `http.CrossOriginProtection` use, and the
  * spiritual sibling of Next.js / Astro's Origin-vs-Host check.
  *
- * Why not a token cookie: webjs previously issued a per-request `webjs_csrf`
+ * Why not a token cookie: WebJs previously issued a per-request `webjs_csrf`
  * double-submit cookie on every SSR response. That made SSR HTML
  * un-cacheable at a CDN (a CDN skips a response with `Set-Cookie`, and a
  * cached one would share / poison the token across visitors). A header check

package/src/dev-error.js

@@ -19,7 +19,7 @@ import { readFileSync } from 'node:fs';
 /**
  * Pull the first useful `file:line:column` out of an error stack. Prefers a
  * frame under `appDir` (the user's own code) over a framework / node_modules
- * frame, so the overlay points at the edit that broke, not webjs internals.
+ * frame, so the overlay points at the edit that broke, not WebJs internals.
  *
  * Handles the V8 stack forms `at fn (/abs/file.ts:12:5)`, `at /abs/file.ts:12:5`,
  * and `at file:///abs/file.ts:12:5`.

package/src/dev.js

@@ -30,6 +30,7 @@ import { stripTypeScript, ensureStripper } from './ts-strip.js';
 import { defaultLogger } from './logger.js';
 import { assertNodeVersion } from './node-version.js';
 import { applyEnvValidation } from './env-schema.js';
+import { runInstrumentation, findInstrumentationClient } from './instrumentation.js';
 import { withRequest, setCspNonce, setBodyLimits, setRequestId, requestId as getRequestId } from './context.js';
 import { buildInfoResponse } from './build-info.js';
 import { readCspConfig, mintNonce, buildCspHeader, cspHeaderName } from './csp.js';
@@ -135,7 +136,7 @@ const MIME = {
  * `namespace` with values, parameter properties, legacy decorators
  * with `emitDecoratorMetadata`, `import = require`) throws at strip
  * time. The `erasable-typescript-only` and `no-non-erasable-typescript`
- * lint rules catch these at edit time. webjs is buildless end-to-end:
+ * lint rules catch these at edit time. WebJs is buildless end-to-end:
  * there is no bundler fallback.
  *
  * The transformed bytes are cached per request handler in `state.tsCache`
@@ -440,7 +441,7 @@ export async function readServerTimeoutsFromApp(appDir) {
 }
 
 /**
- * Create a reusable, framework-agnostic request handler for a webjs app.
+ * Create a reusable, framework-agnostic request handler for a WebJs app.
  * The returned `handle(req)` takes a standard `Request` and resolves to a
  * standard `Response`: suitable for Node http, Deno, Bun, Cloudflare Workers,
  * or embedding inside an Express/Fastify app.
@@ -455,7 +456,7 @@ export async function readServerTimeoutsFromApp(appDir) {
  * }} opts
  */
 export async function createRequestHandler(opts) {
-  // Preflight: webjs needs Node 24+ (built-in TS strip + recursive fs.watch).
+  // Preflight: WebJs needs Node 24+ (built-in TS strip + recursive fs.watch).
   // Throw a clear Error here so an embedded host (Express/Fastify/Bun/Deno)
   // gets the actionable message at boot, not a cryptic API failure mid-request.
   assertNodeVersion({ onFail: 'throw' });
@@ -482,6 +483,13 @@ export async function createRequestHandler(opts) {
   await applyEnvValidation(appDir, { dev: !!opts.dev });
   const dev = !!opts.dev;
   const logger = opts.logger || defaultLogger({ dev });
+  // Boot-time instrumentation hook (#848): run the optional app-root
+  // instrumentation.{js,ts} register() ONCE, after env validation and before
+  // the route table / action index are built, so observability plumbing starts
+  // before traffic. Any error sink it registers via setOnError composes with
+  // the programmatic opts.onError (both fire). Fail-open (a throwing hook is
+  // logged, not fatal).
+  const { onError: instrumentationOnError } = await runInstrumentation(appDir, { dev, logger });
   // APM / Sentry integration point (issue #239). Called whenever the request
   // pipeline catches an unhandled error: the top-level handle() catch (the
   // last-resort 500), an unexpected throw inside the produce() funnel, or a
@@ -490,20 +498,26 @@ export async function createRequestHandler(opts) {
   // sanitized 500 / existing error behavior is unchanged (the hook is purely
   // additive). The sink receives the error plus the correlation id so it can
   // tie the report to the same id the access log and X-Request-Id carry.
-  const onError = typeof opts.onError === 'function' ? opts.onError : null;
+  // Both the programmatic opts.onError AND any sink an instrumentation.{js,ts}
+  // register() installed via setOnError fire (they compose, #848).
+  const onErrorSinks = [opts.onError, instrumentationOnError].filter((f) => typeof f === 'function');
+  const hasOnError = onErrorSinks.length > 0;
   /**
-   * Invoke the app's onError sink defensively. The phase is a coarse label of
-   * where the pipeline caught the error, for the sink's own grouping.
+   * Invoke every registered onError sink defensively. The phase is a coarse
+   * label of where the pipeline caught the error, for the sink's own grouping.
    * @param {unknown} error
    * @param {Request} request
    * @param {string} phase
    */
   function reportError(error, request, phase) {
-    if (!onError) return;
-    try {
-      onError(error, { request, requestId: getRequestId(), phase });
-    } catch (e) {
-      logger.error?.('[webjs] onError hook threw (ignored)', { err: String(e) });
+    if (!hasOnError) return;
+    const ctx = { request, requestId: getRequestId(), phase };
+    for (const sink of onErrorSinks) {
+      try {
+        sink(error, ctx);
+      } catch (e) {
+        logger.error?.('[webjs] onError hook threw (ignored)', { err: String(e) });
+      }
     }
   }
   // Sub-path deployment base path (issue #256), read once from the app's
@@ -616,6 +630,10 @@ export async function createRequestHandler(opts) {
   // eagerly: it is a cheap directory scan (no code reads), and routing, Early
   // Hints, and WebSocket lookups need it available before the first request.
   const routeTable = await buildRouteTable(appDir);
+  // instrumentation-client.{js,ts} (#848) is an app-ROOT file (sibling of app/,
+  // like env.js / readiness.js), not a router stem. Resolve it once and stash it
+  // on the route table so ssrOpts + the browser-servable gate reach it uniformly.
+  routeTable.instrumentationClient = await findInstrumentationClient(appDir);
 
   // Emit `.webjs/routes.d.ts` (typed Route union + per-route params, #258) in
   // dev so an editor's tsserver always has up-to-date route types without the
@@ -1011,6 +1029,7 @@ export async function createRequestHandler(opts) {
     // The route table is the only eager artifact (cheap directory scan); rebuild
     // it so routing reflects added/removed route files immediately.
     state.routeTable = await buildRouteTable(appDir);
+    state.routeTable.instrumentationClient = await findInstrumentationClient(appDir);
     // Refresh the generated route types (#258) so adding/removing a route file
     // updates `.webjs/routes.d.ts` without a manual `webjs types`. Dev only,
     // best-effort (see emitRouteTypes).
@@ -1445,7 +1464,7 @@ export async function createRequestHandler(opts) {
 }
 
 /**
- * Start a webjs HTTP server. Thin wrapper around `createRequestHandler`.
+ * Start a WebJs HTTP server. Thin wrapper around `createRequestHandler`.
  *
  * Speaks plain HTTP/1.1. TLS termination + HTTP/2 to the browser is
  * expected to be handled by a reverse proxy (PaaS edge, nginx, Caddy,
@@ -2010,6 +2029,14 @@ async function handleCore(req, ctx) {
         inertRouteModules: state.inertRouteModules,
         importOnlyRouteModules: state.importOnlyRouteModules,
         notFoundFile: state.routeTable.notFound,
+        // Root-only boundaries (#848): the app-wide catch-all error page and the
+        // unmatched-anywhere 404, rendered by ssr.js when a nested boundary is
+        // absent.
+        globalError: state.routeTable.globalError,
+        globalNotFound: state.routeTable.globalNotFound,
+        // instrumentation-client.{js,ts} (#848): imported first in the client
+        // boot so it runs before app modules.
+        instrumentationClient: state.routeTable.instrumentationClient,
         // Server HTML cache (#241): a CSP-enabled page emits a fresh
         // per-request nonce into its body, so its bytes vary per request and
         // it must never be HTML-cached. Pass the flag so the cache guard skips
@@ -2039,7 +2066,9 @@ async function handleCore(req, ctx) {
   if (wantsJson(req, path)) {
     return Response.json({ error: 'Not found', path }, { status: 404 });
   }
-  return ssrNotFound(state.routeTable.notFound, { dev, appDir, req, url });
+  // Unmatched anywhere: prefer the root not-found.{js,ts}, then a
+  // global-not-found.{js,ts} (#848), else the default 404 page.
+  return ssrNotFound(state.routeTable.notFound || state.routeTable.globalNotFound, { dev, appDir, req, url });
 }
 
 /** @param {Request} req @param {string} path */
@@ -2109,7 +2138,7 @@ async function loadMiddleware(appDir, dev, logger) {
  * @param {import('./logger.js').Logger} logger
  */
 /**
- * Create a plain HTTP/1.1 server. webjs deploys are expected to sit
+ * Create a plain HTTP/1.1 server. WebJs deploys are expected to sit
  * behind a reverse proxy (PaaS edge, nginx, Caddy, etc.) that handles
  * TLS termination and speaks HTTP/2 to clients: Node's http2 module
  * doesn't need to be involved on the framework side.
@@ -2298,7 +2327,7 @@ async function exists(p) {
  * dev server returns the error to the caller. The
  * `erasable-typescript-only` and `no-non-erasable-typescript` lint
  * rules catch these at edit time. There is no bundler fallback;
- * webjs is buildless end-to-end.
+ * WebJs is buildless end-to-end.
  *
  * The backend is the runtime-appropriate stripper (#508): Node 24+'s built-in
  * `module.stripTypeScriptTypes`, or `amaro` on Bun (byte-identical, equally
@@ -2487,11 +2516,18 @@ function computeBrowserBoundFiles(routeTable, moduleGraph, components, appDir) {
     for (const f of page.layouts || []) entries.add(f);
     for (const f of page.errors || []) entries.add(f);
     for (const f of page.loadings || []) entries.add(f);
+    for (const f of page.forbiddens || []) entries.add(f);
+    for (const f of page.unauthorizeds || []) entries.add(f);
   }
   if (routeTable.notFound) entries.add(routeTable.notFound);
   if (routeTable.notFounds) {
     for (const f of routeTable.notFounds.values()) entries.add(f);
   }
+  if (routeTable.globalError) entries.add(routeTable.globalError);
+  if (routeTable.globalNotFound) entries.add(routeTable.globalNotFound);
+  // instrumentation-client is browser-bound (imported first in the boot), so it
+  // must be servable through the gate.
+  if (routeTable.instrumentationClient) entries.add(routeTable.instrumentationClient);
   // Lazy components live in the registry but no page imports their
   // class directly; the lazy-loader fetches their module URLs on
   // viewport entry. Add every discovered component file as an entry so

package/src/elision-report.js

@@ -2,7 +2,7 @@
  * App-level elision report (#646).
  *
  * A reporting layer over the `analyzeElision` verdict, NOT a second analysis
- * and NOT a build (webjs is no-build; elision is the server's analysis pass,
+ * and NOT a build (WebJs is no-build; elision is the server's analysis pass,
  * run at dev-server start and re-derived after each fs.watch rebuild). It
  * builds the module graph, runs `analyzeElision`, and returns the page / layout
  * route modules that SHIP WHOLE to the browser, each with the first

package/src/env-schema.js

@@ -1,7 +1,7 @@
 /**
  * Startup env-var validation with a typed schema hook (issue #236).
  *
- * webjs auto-loads `<appDir>/.env` into `process.env` at boot, but does no
+ * WebJs auto-loads `<appDir>/.env` into `process.env` at boot, but does no
  * validation, so a missing or misconfigured required var (DATABASE_URL,
  * AUTH_SECRET, ...) fails late and cryptically (a database connect error
  * mid-request, an undefined secret signing a token). This module adds an

package/src/file-storage.js

@@ -2,7 +2,7 @@
  * File storage primitive: a pluggable `FileStore` with a streaming local-disk
  * default adapter (issue #247).
  *
- * webjs already round-trips a native `File` / `Blob` / `FormData` over the RPC
+ * WebJs already round-trips a native `File` / `Blob` / `FormData` over the RPC
  * wire (the serializer), but nothing decided WHERE the bytes land. This module
  * is that answer. The model mirrors `cache.js` exactly: a documented interface,
  * a default adapter (`diskStore`), and a module singleton (`setFileStore` /
@@ -35,7 +35,7 @@
  *     (`File` / `Blob` / `ReadableStream` / `Uint8Array` in, a `{ body, size,
  *     contentType }` handle out), so an S3 / R2 / GCS adapter is a drop-in: it
  *     implements the same `put` / `get` / `delete` / `url` and the call sites do
- *     not change. webjs ships no S3 SDK; see the JSDoc on `FileStore` below.
+ *     not change. WebJs ships no S3 SDK; see the JSDoc on `FileStore` below.
  *
  * @module file-storage
  */

package/src/forwarded.js

@@ -2,7 +2,7 @@
  * Build a full URL from a Node IncomingMessage, respecting standard
  * reverse-proxy headers (`X-Forwarded-Proto`, `X-Forwarded-Host`).
  *
- * Why: webjs apps are almost always deployed behind a reverse proxy
+ * Why: WebJs apps are almost always deployed behind a reverse proxy
  * (Railway, Fly, Render, Vercel, Cloudflare, nginx, Caddy, Traefik -
  * see the no-build architecture docs). The proxy terminates TLS and
  * speaks plain HTTP/1.1 to the container, so `req.url` inside the

package/src/headers.js

@@ -2,7 +2,7 @@
  * Secure-by-default response headers plus a small declarative per-path
  * header config (issue #232).
  *
- * webjs sets a baseline of standard security headers on every document
+ * WebJs sets a baseline of standard security headers on every document
  * and asset response, so a scaffolded app is not clickjackable or
  * MIME-sniffable out of the box (no reverse proxy required for the
  * baseline). The defaults are LITERAL HTTP headers, no abstraction.

package/src/instrumentation.js

@@ -0,0 +1,103 @@
+/**
+ * Boot-time instrumentation hook (#848, Next parity for instrumentation.ts).
+ *
+ * An optional app-root `instrumentation.{js,ts}` default-exports (or names) a
+ * `register()` function the framework runs ONCE at boot, before the route table
+ * is built and before any request is served. It is the place to wire
+ * observability plumbing (OpenTelemetry, an APM, a logger) that must start
+ * before the app handles traffic.
+ *
+ * Inside `register()`, the app may call `setOnError(fn)` (imported from
+ * `@webjsdev/server`) to register an error sink. It COMPOSES with the
+ * programmatic `createRequestHandler({ onError })` option (both fire), so the
+ * file-based hook and the option-based sink coexist.
+ *
+ * @module instrumentation
+ */
+
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { stat } from 'node:fs/promises';
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+/**
+ * Per-boot handoff channel for a `register()`-registered error sink. An
+ * AsyncLocalStorage (NOT a module global) so two `runInstrumentation` calls
+ * racing in one process (e.g. `Promise.all` of two `createRequestHandler`s in a
+ * test) each get their OWN store: `setOnError` writes to whichever run's context
+ * is active, so a concurrent boot can never capture the other's sink. The
+ * context propagates across the `await register()` awaits.
+ * @type {AsyncLocalStorage<{ onError: ((error: unknown, ctx?: any) => void) | null }>}
+ */
+const _als = new AsyncLocalStorage();
+
+/**
+ * Register an error sink from inside `instrumentation.register()`. Composes with
+ * the `createRequestHandler({ onError })` option. Passing a non-function clears
+ * it. A call made outside a `runInstrumentation` context (no active store) is a
+ * safe no-op.
+ * @param {(error: unknown, ctx?: any) => void} fn
+ */
+export function setOnError(fn) {
+  const store = _als.getStore();
+  if (store) store.onError = typeof fn === 'function' ? fn : null;
+}
+
+async function exists(p) {
+  try { await stat(p); return true; } catch { return false; }
+}
+
+/**
+ * Locate the optional app-root `instrumentation-client.{js,ts,mts,mjs}` (#848),
+ * the browser boot hook imported first in the client boot script. Lives at the
+ * app root (sibling of `app/`), like the server `instrumentation.{js,ts}` and
+ * Next's instrumentation-client. Returns the absolute path or null.
+ * @param {string} appDir
+ * @returns {Promise<string | null>}
+ */
+export async function findInstrumentationClient(appDir) {
+  for (const name of ['instrumentation-client.ts', 'instrumentation-client.js', 'instrumentation-client.mts', 'instrumentation-client.mjs']) {
+    const p = join(appDir, name);
+    if (await exists(p)) return p;
+  }
+  return null;
+}
+
+/**
+ * Run the app's boot-time instrumentation hook exactly once. Loads
+ * `instrumentation.{js,ts,mts,mjs}` at the app root (opt-in: absent is a no-op)
+ * and calls its `register()` (the default export if it is a function, else a
+ * named `register` export). Returns any error sink the hook registered via
+ * `setOnError`, so the caller can compose it with its own `onError`.
+ *
+ * @param {string} appDir
+ * @param {{ dev?: boolean, logger?: { error?: (...a: any[]) => void } }} [opts]
+ * @returns {Promise<{ onError: ((error: unknown, ctx?: any) => void) | null }>}
+ */
+export async function runInstrumentation(appDir, opts = {}) {
+  const { dev = false, logger } = opts;
+  let file = null;
+  for (const name of ['instrumentation.ts', 'instrumentation.js', 'instrumentation.mts', 'instrumentation.mjs']) {
+    const p = join(appDir, name);
+    if (await exists(p)) { file = p; break; }
+  }
+  if (!file) return { onError: null };
+  // Per-boot store: setOnError writes here, scoped to THIS run's async context.
+  const store = { onError: null };
+  await _als.run(store, async () => {
+    try {
+      const url = pathToFileURL(file).toString();
+      const bust = dev ? `?t=${Date.now()}-${Math.random().toString(36).slice(2)}` : '';
+      const mod = await import(url + bust);
+      const register = typeof mod.default === 'function'
+        ? mod.default
+        : (typeof mod.register === 'function' ? mod.register : null);
+      if (register) await register();
+    } catch (e) {
+      // A failing instrumentation hook must not crash boot: log and continue, the
+      // same fail-open posture as the readiness loader. The app still serves.
+      logger?.error?.(`[webjs] instrumentation.{js,ts} register() failed`, { err: String(e) });
+    }
+  });
+  return { onError: store.onError };
+}

package/src/json.js

@@ -15,7 +15,7 @@ import { readTextBounded, BodyLimitError, DEFAULT_MAX_BODY_BYTES } from './body-
  * The helper reads the in-flight Request from the AsyncLocalStorage
  * request context. If the caller sent `Accept: application/vnd.webjs+json`
  * (e.g. via the `richFetch` client helper), the response body is
- * encoded with the webjs serializer so rich types (Date, Map, Set,
+ * encoded with the WebJs serializer so rich types (Date, Map, Set,
  * BigInt, TypedArrays, Blob, File, FormData, cycles) survive. Otherwise
  * the response is plain `application/json`, unchanged behaviour for
  * curl / external consumers.
@@ -47,7 +47,7 @@ export async function json(data, init = {}) {
 }
 
 /**
- * Parse a request body using the webjs serializer when the client sent
+ * Parse a request body using the WebJs serializer when the client sent
  * our content type, otherwise as plain JSON. Handy for route handlers
  * that accept rich bodies from the `richFetch` helper but plain JSON
  * from everyone else.

package/src/listener-bun.js

@@ -73,7 +73,7 @@ export function startBunListener(ctx) {
   const server = Bun.serve({
     port,
     idleTimeout: bunIdleTimeout(timeouts),
-    // webjs owns its dev error overlay (over SSE) and handles thrown errors in
+    // WebJs owns its dev error overlay (over SSE) and handles thrown errors in
     // `fetch`, so Bun's own development error page must never interfere; keep it
     // deterministic (off) rather than tied to NODE_ENV.
     development: false,
@@ -172,7 +172,7 @@ export function startBunListener(ctx) {
  * the `open` handler; messages/close are forwarded to its emitter from the
  * `websocket.message` / `websocket.close` handlers.
  *
- * Only `'message'` and `'close'` are forwarded (the events webjs WS handlers and
+ * Only `'message'` and `'close'` are forwarded (the events WebJs WS handlers and
  * `broadcast()` use). Bun exposes no per-socket `'error'` / `'ping'` / `'pong'`
  * handler to bridge; a socket failure on Bun surfaces as a `'close'`, so
  * `'close'`-keyed cleanup still runs. Documented in the WebSockets doc.

package/src/logger.js

@@ -1,7 +1,7 @@
 /**
  * Minimal pluggable logger.
  *
- * webjs doesn't pick pino/winston/bunyan for you. The default in prod emits
+ * WebJs doesn't pick pino/winston/bunyan for you. The default in prod emits
  * one JSON object per line to stdout: trivially ingestable by any log
  * aggregator. In dev, lines are plain text for readability.
  *

package/src/node-version.js

@@ -1,7 +1,7 @@
 /**
  * Node-version preflight guard (issue #238).
  *
- * webjs depends on Node 24+ built-ins: `module.stripTypeScriptTypes` (the
+ * WebJs depends on Node 24+ built-ins: `module.stripTypeScriptTypes` (the
  * no-build TypeScript strip) and recursive `fs.watch` (dev live-reload). On an
  * older Node the failure surfaces late and cryptically (a strip error or a
  * missing API deep inside a request), not as a clear "you need Node 24+". This

package/src/page-action.js

@@ -1,8 +1,9 @@
-import { isNotFound, isRedirect } from '@webjsdev/core';
-import { ssrPage, ssrNotFound, loadModule } from './ssr.js';
+import { isNotFound, isRedirect, isForbidden, isUnauthorized } from '@webjsdev/core';
+import { ssrPage, ssrNotFound, ssrForbidden, ssrUnauthorized, loadModule } from './ssr.js';
 import { readBytesBounded, payloadTooLarge, DEFAULT_MAX_MULTIPART_BYTES } from './body-limit.js';
 import { getBodyLimits } from './context.js';
 import { propagateTrustedRemoteIp } from './rate-limit.js';
+import { makeThenable } from './thenable-params.js';
 
 /**
  * Page server actions: a `page.{js,ts}` may export an `action` function that
@@ -201,7 +202,14 @@ export async function runPageAction(route, params, url, loaded, req, ssrOpts) {
   /** @type {ActionResult | undefined} */
   let result;
   try {
-    result = await action({ request: actionReq, params, searchParams, url, formData });
+    // params / searchParams are awaitable AND sync-readable here too (#848).
+    result = await action({
+      request: actionReq,
+      params: makeThenable(params),
+      searchParams: makeThenable(searchParams),
+      url,
+      formData,
+    });
   } catch (err) {
     if (isRedirect(err)) {
       const e = /** @type any */ (err);
@@ -215,6 +223,14 @@ export async function runPageAction(route, params, url, loaded, req, ssrOpts) {
     if (isNotFound(err)) {
       return ssrNotFound(ssrOpts.notFoundFile ?? null, { ...ssrOpts, req, url });
     }
+    // forbidden()/unauthorized() from a page action render the same 403/401
+    // boundary as the page-render path (#848), not a generic 500.
+    if (isForbidden(err)) {
+      return ssrForbidden(route, { ...ssrOpts, req, url });
+    }
+    if (isUnauthorized(err)) {
+      return ssrUnauthorized(route, { ...ssrOpts, req, url });
+    }
     throw err;
   }
 

package/src/redirects.js

@@ -1,7 +1,7 @@
 /**
  * Declarative permanent / temporary redirects (issue #254).
  *
- * webjs already ships `redirect(url)` (a per-request throw sentinel) for
+ * WebJs already ships `redirect(url)` (a per-request throw sentinel) for
  * imperative, request-time redirects. This module adds the missing
  * DECLARATIVE surface: a config of old-path -> new-path rules an app
  * declares once and the framework applies at the very start of request

package/src/router.js

@@ -10,6 +10,9 @@ import { walk } from './fs-walk.js';
  *   layouts: string[],
  *   errors: string[],
  *   loadings: string[],
+ *   notFounds: string[],
+ *   forbiddens: string[],
+ *   unauthorizeds: string[],
  *   metadataFiles: string[],
  *   middlewares: string[],
  *   isCatchAll: boolean
@@ -29,6 +32,8 @@ import { walk } from './fs-walk.js';
  *   apis: ApiRoute[],
  *   notFound: string | null,
  *   notFounds: Map<string, string>,
+ *   globalError: string | null,
+ *   globalNotFound: string | null,
  *   metadataRoutes: MetadataRoute[],
  *   appDir: string
  * }} RouteTable
@@ -75,6 +80,14 @@ export async function buildRouteTable(appDir) {
   /** @type {Map<string, string>} */
   const notFounds = new Map();
   let notFound = null;
+  /** @type {Map<string,string>} */
+  const forbiddens = new Map();
+  /** @type {Map<string,string>} */
+  const unauthorizeds = new Map();
+  // Root-only boundaries (#848): the app-wide catch-all error and the
+  // unmatched-anywhere 404, set only at dir '.'.
+  let globalError = null;
+  let globalNotFound = null;
   /** @type {MetadataRoute[]} */
   const metadataRoutes = [];
 
@@ -114,6 +127,8 @@ export async function buildRouteTable(appDir) {
         layouts: [],
         errors: [],
         loadings: [],
+        forbiddens: [],
+        unauthorizeds: [],
         metadataFiles: [],
         middlewares: [],
         isCatchAll,
@@ -129,6 +144,14 @@ export async function buildRouteTable(appDir) {
     } else if (stem === 'not-found') {
       notFounds.set(dir, file);
       if (dir === '.') notFound = file;
+    } else if (stem === 'forbidden') {
+      forbiddens.set(dir, file);
+    } else if (stem === 'unauthorized') {
+      unauthorizeds.set(dir, file);
+    } else if (stem === 'global-error') {
+      if (dir === '.') globalError = file;
+    } else if (stem === 'global-not-found') {
+      if (dir === '.') globalNotFound = file;
     } else if (METADATA_STEMS.has(stem) && (dir === '.' || dir.split('/').every(s => !s.startsWith('[')))) {
       // Metadata route: sitemap.ts, robots.ts, icon.ts, etc.
       // Only at root or static segments (no dynamic params in metadata routes).
@@ -148,6 +171,9 @@ export async function buildRouteTable(appDir) {
     page.layouts = chainDirs.map((d) => layouts.get(d)).filter(Boolean);
     page.errors = chainDirs.map((d) => errors.get(d)).filter(Boolean);
     page.loadings = chainDirs.map((d) => loadings.get(d)).filter(Boolean);
+    page.notFounds = chainDirs.map((d) => notFounds.get(d)).filter(Boolean);
+    page.forbiddens = chainDirs.map((d) => forbiddens.get(d)).filter(Boolean);
+    page.unauthorizeds = chainDirs.map((d) => unauthorizeds.get(d)).filter(Boolean);
     page.middlewares = chainDirs.map((d) => middlewares.get(d)).filter(Boolean);
     page.metadataFiles = [...page.layouts, page.file];
   }
@@ -159,7 +185,7 @@ export async function buildRouteTable(appDir) {
   }
 
   pages.sort(compareSpecificity);
-  return { pages, apis, notFound, notFounds, metadataRoutes, appDir };
+  return { pages, apis, notFound, notFounds, globalError, globalNotFound, metadataRoutes, appDir };
 }
 
 /**

package/src/serializer.js

@@ -2,7 +2,7 @@ import { stringify, parse } from '@webjsdev/core';
 
 /**
  * @typedef {Object} Serializer
- * A pluggable serializer that controls how webjs server actions encode and
+ * A pluggable serializer that controls how WebJs server actions encode and
  * decode values on the RPC wire.
  *
  * **AI hint:** The default serializer uses webjs's built-in
@@ -50,7 +50,7 @@ let current = defaultSerializer;
  *
  * **AI hint:** Use this in server-side code that needs to encode or decode
  * RPC payloads. It returns whatever serializer was set via `setSerializer`,
- * or the default webjs serializer if none was set.
+ * or the default WebJs serializer if none was set.
  *
  * @returns {Serializer}
  */

package/src/ssr.js

@@ -1,6 +1,6 @@
 import { pathToFileURL, fileURLToPath } from 'node:url';
 import { resolve } from 'node:path';
-import { renderToString, isNotFound, isRedirect, lookupModuleUrl, isLazy, cspNonce } from '@webjsdev/core';
+import { renderToString, isNotFound, isRedirect, isForbidden, isUnauthorized, lookupModuleUrl, isLazy, cspNonce } from '@webjsdev/core';
 import { importMapTag, vendorIntegrityFor, publishedBuildId, basePath, vendorPreconnectOrigins, vendorPreloadTargets } from './importmap.js';
 import { withBasePath } from './base-path.js';
 import { withAssetHash } from './asset-hash.js';
@@ -14,6 +14,7 @@ import {
   HTML_CACHE_MARKER,
 } from './html-cache.js';
 import { requestedFrameId, extractFrameSubtree } from './frame-render.js';
+import { makeThenable } from './thenable-params.js';
 
 /**
  * SSR a matched page route to a Response.
@@ -67,8 +68,11 @@ export async function ssrPage(route, params, url, opts) {
   }
 
   const ctx = {
-    params,
-    searchParams: Object.fromEntries(url.searchParams.entries()),
+    // params / searchParams are awaitable AND synchronously readable (#848):
+    // `params.id` still works, `await params` also works (Next 15/16 parity).
+    // The `then` is non-enumerable so spread / JSON / Object.keys are unchanged.
+    params: makeThenable(params),
+    searchParams: makeThenable(Object.fromEntries(url.searchParams.entries())),
     url: url.toString(),
     // Populated only when this render is the re-render after a failed page
     // `action` submission (#244). The page function and every layout receive
@@ -172,6 +176,16 @@ export async function ssrPage(route, params, url, opts) {
         else push(f);
       }
     }
+    // instrumentation-client.{js,ts} (#848): import it FIRST in the client boot
+    // so it runs before app modules (Next's instrumentation-client ordering).
+    // It ships even on an otherwise-static page (the app opted into client work),
+    // so it is prepended AFTER the component/page modules are collected.
+    if (opts.instrumentationClient) {
+      const u = toUrlPath(opts.instrumentationClient, opts.appDir);
+      const i = moduleUrls.indexOf(u);
+      if (i !== -1) moduleUrls.splice(i, 1);
+      moduleUrls.unshift(u);
+    }
     // Emit <link rel="modulepreload"> for every custom element that
     // actually rendered PLUS their transitive dependencies (from the
     // module graph). URLs are deduplicated so the browser never sees
@@ -274,9 +288,17 @@ export async function ssrPage(route, params, url, opts) {
       return new Response(null, { status: e.status || 302, headers: { location: e.url } });
     }
     if (isNotFound(err)) {
-      const html = await ssrNotFoundHtml(null, opts);
+      // Nearest not-found.{js,ts} in the page's chain wins (#848 fix: previously
+      // this always rendered the bare default, ignoring even a root not-found);
+      // fall back to a root global-not-found.{js,ts}, else the default page.
+      const html = await ssrNotFoundHtml(nearest(route.notFounds) || opts.globalNotFound || null, opts);
       return htmlResponse(html, 404, opts.req, url);
     }
+    // forbidden() / unauthorized() sentinels (#848, Next 15/16 parity): render
+    // the nearest forbidden.{js,ts} / unauthorized.{js,ts} boundary (innermost
+    // wins), else a default page, at 403 / 401.
+    if (isForbidden(err)) return ssrForbidden(route, { ...opts, url });
+    if (isUnauthorized(err)) return ssrUnauthorized(route, { ...opts, url });
     // APM / Sentry sink (issue #239): a page render error that becomes a 500
     // (an error.js boundary OR the default 500 page) is an unhandled error the
     // app should see in its error tracker. Report it best-effort BEFORE
@@ -309,6 +331,23 @@ export async function ssrPage(route, params, url, opts) {
         // fall through to next error boundary
       }
     }
+    // Root global-error.{js,ts} (#848): the app-wide catch-all, tried after the
+    // nested error boundaries are exhausted. It renders the FULL document (its
+    // own <!doctype><html><body>, like the root layout), since a root-layout
+    // failure is exactly when it fires, so its rendered output is returned
+    // verbatim without wrapInDocument. Status 500.
+    if (opts.globalError) {
+      try {
+        const mod = await loadModule(opts.globalError, opts.dev);
+        if (mod.default) {
+          const tree = await mod.default({ error: err });
+          const body = await renderToString(tree, { ssr: true, dev: opts.dev });
+          return htmlResponse(body, 500, opts.req, url);
+        }
+      } catch (nested) {
+        // fall through to the default 500 page
+      }
+    }
     // Default: dev shows stack, prod shows a terse message (no stack trace leaks).
     console.error('[webjs] unhandled render error:', err);
     const body = opts.dev
@@ -335,6 +374,30 @@ export async function ssrNotFound(notFoundFile, opts) {
   return htmlResponse(html, 404, opts.req, opts.url);
 }
 
+/**
+ * 403 response for a thrown forbidden() (#848). Renders the nearest
+ * forbidden.{js,ts} in the page's chain, else a default 403 page. Shared by the
+ * page-render catch (ssr.js) and the page-action write path (page-action.js) so
+ * both behave identically.
+ * @param {{ forbiddens?: string[] }} route
+ * @param {{ dev: boolean, appDir: string, req?: Request, url?: URL }} opts
+ */
+export async function ssrForbidden(route, opts) {
+  const html = await ssrBoundaryHtml(nearest(route.forbiddens), '403: Forbidden', opts);
+  return htmlResponse(html, 403, opts.req, opts.url);
+}
+
+/**
+ * 401 response for a thrown unauthorized() (#848). Renders the nearest
+ * unauthorized.{js,ts} in the page's chain, else a default 401 page.
+ * @param {{ unauthorizeds?: string[] }} route
+ * @param {{ dev: boolean, appDir: string, req?: Request, url?: URL }} opts
+ */
+export async function ssrUnauthorized(route, opts) {
+  const html = await ssrBoundaryHtml(nearest(route.unauthorizeds), '401: Unauthorized', opts);
+  return htmlResponse(html, 401, opts.req, opts.url);
+}
+
 /**
  * Build an HTML Response. Sets no cookie: action CSRF is an Origin /
  * Sec-Fetch-Site check, so the page response is cookieless (CDN-cacheable).
@@ -389,6 +452,45 @@ function cachedHtmlResponse(rec, req, url) {
 
 /* ------------ internals ------------ */
 
+/**
+ * Nearest-wins boundary file from a chain projected outermost -> innermost
+ * (the router builds these arrays via chainOf). The innermost (last) wins, the
+ * same "nearest boundary" rule error.js uses. Returns null for an empty chain.
+ * @param {string[] | undefined} files
+ * @returns {string | null}
+ */
+function nearest(files) {
+  return files && files.length ? files[files.length - 1] : null;
+}
+
+/**
+ * Render a simple boundary page (forbidden / unauthorized, #848) at the given
+ * default heading. Loads the nearest boundary module when one exists (its
+ * default export receives no props, like not-found), else emits the default
+ * heading. Mirrors ssrNotFoundHtml.
+ * @param {string | null} file
+ * @param {string} heading  e.g. '403: Forbidden'
+ * @param {{ dev: boolean, appDir: string, req?: Request }} opts
+ */
+async function ssrBoundaryHtml(file, heading, opts) {
+  let body = `<h1>${heading}</h1>`;
+  if (file) {
+    try {
+      const mod = await loadModule(file, opts.dev);
+      if (mod.default) body = await renderToString(await mod.default({}), { ssr: true, dev: opts.dev });
+    } catch (e) {
+      body = `<h1>${heading}</h1><pre>${escapeHtml(String(e))}</pre>`;
+    }
+  }
+  const nonce = opts.req ? getNonce(opts.req) : undefined;
+  return wrapInDocument(body, {
+    metadata: { title: heading.replace(/^\d+:\s*/, '') },
+    moduleUrls: [],
+    dev: opts.dev,
+    nonce,
+  });
+}
+
 async function ssrNotFoundHtml(notFoundFile, opts) {
   let body = '<h1>404: Not found</h1>';
   if (notFoundFile) {

package/src/testing.js

@@ -1,7 +1,7 @@
 /**
  * Server-side test harness helpers (issue #267).
  *
- * `createRequestHandler(...).handle(request)` drives the FULL webjs pipeline
+ * `createRequestHandler(...).handle(request)` drives the FULL WebJs pipeline
  * (middleware, routing, SSR, page actions, server-action RPC, auth + CSRF), and
  * the framework's own suite already drives it. These helpers are THIN builders
  * over the native `Request` / `Response` around that `handle()`, so an app test
@@ -350,7 +350,7 @@ export async function rawActionRequest(app, serverFilePath, fnName, args = [], o
 }
 
 /**
- * Browser-test harness (#806): build a webjs handler that a `web-test-runner`
+ * Browser-test harness (#806): build a WebJs handler that a `web-test-runner`
  * config can proxy module requests to, so a `test/**​/browser/*.test.js` file
  * can import a real `.ts` component that imports a `'use server'` action and it
  * loads + hydrates in a real browser. Plain WTR serves raw TS with no webjs
@@ -369,7 +369,7 @@ export async function rawActionRequest(app, serverFilePath, fnName, args = [], o
  * of `@webjsdev/server/testing` stays light (they pull the full server + the
  * `ws` WebSocket subsystem).
  *
- * @param {string} appDir  the webjs app root (usually `process.cwd()`)
+ * @param {string} appDir  the WebJs app root (usually `process.cwd()`)
  * @returns {Promise<{ handle: Handle, warmup: () => Promise<void>, importmapHtml: () => string }>}
  */
 export async function createBrowserTestHandler(appDir) {

package/src/thenable-params.js

@@ -0,0 +1,42 @@
+/**
+ * Make a routing `params` / `searchParams` object awaitable WITHOUT losing
+ * synchronous access (#848, Next.js 15/16 parity where these are Promises).
+ *
+ * Both forms work after wrapping:
+ *
+ *   const id = params.id;            // sync, unchanged
+ *   const { id } = await params;     // Next-style, now also valid
+ *
+ * The `then` method is added NON-ENUMERABLE and NON-OWN-ENUMERABLE, so a
+ * `{ ...obj }` spread, `Object.keys`, `JSON.stringify`, and `for...in` never
+ * see it. That is the whole safety story: nothing that copies or serializes the
+ * object can accidentally turn a copy into a thenable and poison a downstream
+ * `Promise.resolve`. Only an explicit `await` / `.then` observes it.
+ *
+ * @template {object} T
+ * @param {T} obj the plain params/searchParams record
+ * @returns {T} the same object, now thenable (or `obj` unchanged when it is not
+ *   a plain object or already carries a `then` data key)
+ */
+export function makeThenable(obj) {
+  if (obj == null || typeof obj !== 'object') return obj;
+  // A real `then` data key (an app route literally named its param "then")
+  // must not be clobbered; leave such an object un-wrapped.
+  if (Object.prototype.hasOwnProperty.call(obj, 'then')) return obj;
+  Object.defineProperty(obj, 'then', {
+    value: /** @param {(v: any) => void} resolve @param {(e: any) => void} [reject] */ (
+      resolve,
+      reject
+    ) => {
+      // Resolve to a PLAIN shallow copy (the non-enumerable `then` is not
+      // copied), so the awaited value is a clean object and `await` cannot
+      // recursively re-await the same thenable.
+      const plain = { ...obj };
+      return Promise.resolve(plain).then(resolve, reject);
+    },
+    enumerable: false,
+    writable: true,
+    configurable: true,
+  });
+  return obj;
+}

package/src/ts-strip.js

@@ -1,8 +1,8 @@
 /**
- * Pluggable TypeScript stripper (#508), the one seam that lets webjs run on both
+ * Pluggable TypeScript stripper (#508), the one seam that lets WebJs run on both
  * Node and Bun.
  *
- * webjs serves `.ts` / `.mts` source to the browser as JavaScript by ERASING the
+ * WebJs serves `.ts` / `.mts` source to the browser as JavaScript by ERASING the
  * type syntax in place (position-preserving whitespace replacement, so no
  * sourcemap is shipped and stack traces stay byte-exact). On Node 24+ that is the
  * built-in `module.stripTypeScriptTypes`. Bun has no such built-in, so this

package/src/vendor.js

@@ -1,7 +1,7 @@
 /**
  * Resolve bare npm imports to browser-loadable URLs via jspm.io.
  *
- * webjs follows the Rails 7 + importmap-rails posture exactly. When user
+ * WebJs follows the Rails 7 + importmap-rails posture exactly. When user
  * code imports a bare specifier (e.g. `import dayjs from 'dayjs'`), the
  * browser can't resolve it natively. The framework's job is to emit an
  * importmap that translates each bare specifier to a real URL.
@@ -10,7 +10,7 @@
  *
  *   importmap: { "dayjs": "https://ga.jspm.io/npm:dayjs@1.11.13/index.js" }
  *
- * The browser fetches the bundle directly from jspm.io. The webjs server
+ * The browser fetches the bundle directly from jspm.io. The WebJs server
  * does not proxy, cache, or bundle anything. jspm.io has done the work
  * server-side (CJS-to-ESM conversion, transitive bundling, browser
  * polyfills).
@@ -85,7 +85,7 @@ const FRAMEWORK_SERVER_ONLY = new Set(['@webjsdev/cli', '@webjsdev/server', '@we
  * Excludes:
  *   - `node_modules`, `.webjs`, `public` directories
  *   - Any directory starting with `_` (webjs `_private/` convention)
- *   - `test/` and `tests/` (server-only by webjs convention)
+ *   - `test/` and `tests/` (server-only by WebJs convention)
  *   - Files whose name marks them as server-only:
  *       * `*.server.{js,ts,mjs,mts}` (path-level boundary)
  *       * `route.{js,ts,mjs,mts}` (file-router HTTP handler)
@@ -1030,7 +1030,7 @@ export async function readPinFile(appDir) {
  * When `integrity` is provided and non-empty, it's included alongside
  * `imports` as a sibling key (matching the browser importmap-integrity
  * spec: a flat `{url: 'sha384-...'}` map). Omitted entirely when empty
- * so older webjs versions read the file as before.
+ * so older WebJs versions read the file as before.
  *
  * `provider` is persisted alongside imports when non-default. It lets
  * `webjs vendor update` know which CDN to re-resolve against, and
@@ -1343,7 +1343,7 @@ export async function pinAll(appDir, opts = {}) {
   }
 
   // The app legitimately has zero bare-specifier imports (or the
-  // scanner is running outside a webjs project). Don't create an
+  // scanner is running outside a WebJs project). Don't create an
   // empty `.webjs/vendor/importmap.json`. Without this guard the file
   // gets written as `{ imports: {} }` in whatever cwd the CLI was
   // invoked from, then immediately rejected by readPinFile's empty

package/src/websocket.js

@@ -3,6 +3,7 @@ import { matchApi } from './router.js';
 import { urlFromRequest } from './forwarded.js';
 import { registerClient } from './broadcast.js';
 import { loadWsModule } from './listener-core.js';
+import { makeThenable } from './thenable-params.js';
 
 /**
  * WebSocket support.
@@ -57,7 +58,7 @@ export function attachWebSocket(server, getRouteTable, opts) {
         try {
           registerClient(url.pathname, ws);
           const webReq = buildRequestFromUpgrade(req, url);
-          mod.WS(ws, webReq, { params: match.params });
+          mod.WS(ws, webReq, { params: makeThenable(match.params) });
         } catch (e) {
           opts.logger.error('WebSocket handler threw', {
             err: e instanceof Error ? e.stack || e.message : String(e),