@webjsdev/server 0.8.43 → 0.8.45

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.43",
+  "version": "0.8.45",
   "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/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/check.js

@@ -139,6 +139,11 @@ export const RULES = [
     description:
       'API route handlers (`route.{js,ts}`) must NOT call `redirect()` from `@webjsdev/core`. That function throws a control-flow signal designed for the SSR page renderer; in a route handler it goes uncaught and produces a 500. Use `Response.redirect(url, 303)` for external redirects or return a 3xx Response directly. Page functions, layouts, and server actions may still use `redirect()` (caught by the SSR pipeline).',
   },
+  {
+    name: 'no-interpolation-in-raw-text-element',
+    description:
+      'Flags a template interpolation (`${...}`) placed as a child of a `<style>` or `<script>` element inside a COMPONENT `html` template. Raw-text elements are an SSR/client asymmetry trap: the server renderer emits the interpolated content, but the client renderer drops it (a raw-text hole is a `noop`, since the compile cache is keyed on the static strings), so the element renders correctly on the server and then wipes to empty on hydration. Scoped to components (files with a `WebComponent` class), which hydrate; pages and layouts render server-only and never hydrate, so a page interpolating a `css` result into a `<style>` is a legitimate pattern and is not flagged. In a component, author scoped CSS with `static styles` (shadow DOM) or a `css` template. Found dogfooding a tic-tac-toe app (#845): a `<style>${STYLE}</style>` painted at SSR then vanished on hydrate.',
+  },
 ];
 
 /** Set of all known rule names for fast lookup. */
@@ -634,6 +639,50 @@ export async function checkConventions(appDir) {
     }
   }
 
+  // --- Rule: no-interpolation-in-raw-text-element ---
+  // A `${...}` hole inside a `<style>` or `<script>` element in an `html`
+  // template is an SSR/client asymmetry: `renderToString` emits it, but the
+  // client parser drops a raw-text hole as a `noop` (the compile cache is keyed
+  // on the static strings, so a per-render value cannot be baked in), so the
+  // element paints at SSR then wipes to empty on hydration.
+  //
+  // Scoped to COMPONENTS. The drop only happens on the CLIENT renderer, which
+  // runs for components (hydration + re-render). Pages and layouts render
+  // server-only (never hydrate), so a page's `<style>${STYLES.text}</style>` is
+  // a legitimate, taught pattern and must NOT be flagged. Scan raw source with
+  // comments stripped (the tag text lives in a template string, which the
+  // redacted `scan` view blanks). One violation per file.
+  {
+    for (const { rel, content } of files) {
+      // Only files that define a hydrating custom element. A page/layout that
+      // interpolates a `css` result into a `<style>` is server-only and fine.
+      if (!/class\s+\w+\s+extends\s+WebComponent/.test(content)) continue;
+      const stripped = content
+        .replace(/\/\/.*$/gm, '')
+        .replace(/\/\*[\s\S]*?\*\//g, '');
+      for (const tag of ['style', 'script']) {
+        // `<tag ...> ... ${ ... </tag>`, where the hole sits before the close
+        // tag. The negative lookahead keeps the match from crossing `</tag>`.
+        const re = new RegExp(
+          `<${tag}\\b[^>]*>(?:(?!<\\/${tag}>)[\\s\\S])*?\\$\\{(?:(?!<\\/${tag}>)[\\s\\S])*?<\\/${tag}>`,
+          'i',
+        );
+        if (re.test(stripped)) {
+          violations.push({
+            rule: 'no-interpolation-in-raw-text-element',
+            file: rel,
+            message: `An interpolation (\`\${...}\`) sits inside a <${tag}> element in an html template. The server renderer emits it but the client renderer drops it, so it paints at SSR then wipes to empty on hydration.`,
+            fix:
+              tag === 'style'
+                ? `Move the CSS out of the raw-text hole: use \`static styles\` (shadow DOM) or a \`css\` template for a component, or put page CSS in the layout. Static \`<style>...</style>\` with no \`\${}\` is fine.`
+                : `Build the script body outside the raw-text element (set attributes/properties via bindings, or compute the value before the template). Static \`<script>...</script>\` with no \`\${}\` is fine.`,
+          });
+          break; // one violation per file is enough
+        }
+      }
+    }
+  }
+
   // --- Rule: no-server-env-in-components ---
   // Catches `process.env.X` reads in component files where X is not a
   // WEBJS_PUBLIC_* var and not NODE_ENV. The SSR shim only exposes those

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';
@@ -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).
@@ -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 */
@@ -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/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/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/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/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/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/vendor.js

@@ -726,7 +726,8 @@ function pinFilePath(appDir) {
  * The three-line `.gitignore` pattern that ignores the transient
  * `.webjs` caches at any depth while re-including the committed
  * `.webjs/vendor/` pin output. This mirrors the scaffold template
- * (`packages/cli/templates/.gitignore`) and the `vendor-gitignore`
+ * (`packages/cli/templates/gitignore`, shipped dotless so npm cannot
+ * strip it, renamed to `.gitignore` on copy) and the `vendor-gitignore`
  * check in `doctor.js` verbatim, so a self-healed `.gitignore`
  * ends up byte-identical to a freshly scaffolded one.
  */

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),