@webjsdev/server 0.8.91 → 0.10.0

package/src/form-dispatch.js

@@ -1,18 +1,24 @@
-import { isNotFound, isRedirect, isForbidden, isUnauthorized, FORM_ACTION_FIELD } from '@webjsdev/core';
+import { isNotFound, isRedirect, isForbidden, isUnauthorized, FORM_ACTION_FIELD, splitActionId } from '@webjsdev/core';
+import { headerSafeLocation } from './redirect-location.js';
 import { ssrPage, ssrNotFound, ssrForbidden, ssrUnauthorized } from './ssr.js';
 import { readBytesBounded, payloadTooLarge, DEFAULT_MAX_MULTIPART_BYTES } from './body-limit.js';
-import { getBodyLimits } from './context.js';
+import { getBodyLimits, refreshHeaderValue } from './context.js';
+import { readFlash, encodeFlash, flashSetCookie, appRelativePath } from './action-flash.js';
+import { basePath as appBasePath } from './importmap.js';
+import { withBasePath } from './base-path.js';
 import { propagateTrustedRemoteIp } from './rate-limit.js';
-import { makeThenable } from './thenable-params.js';
+import { makeThenable, searchParamsRecord } from './thenable-params.js';
 import { lookupActionIdentity } from './form-action-identity.js';
+import { originalAction } from './action-seed.js';
+import { declaredParamCount, declaredParamDefaults } from './action-params.js';
 import { verifyOrigin } from './csrf.js';
 import { actionMethod, actionConfigFn, actionMiddleware, resolveTags, RESERVED_CONFIG } from './action-config.js';
 import { runValidate } from './actions.js';
+import { formInput } from './action-input.js';
 import { runActionChain } from './action-middleware.js';
 import { runWithActionSignal } from './action-signal.js';
 import { isStreamable } from './action-stream.js';
 import { revalidateTags } from './cache-tags.js';
-import { isControlFlowThrow, errorDigest, GENERIC_ERROR_MESSAGE } from './action-error.js';
 
 /**
  * The form-submission dispatcher (#1155): a non-GET request to a PAGE's own url
@@ -72,7 +78,9 @@ export const ACTION_SKEW_MESSAGE =
  * success (PRG redirect). A result is a failure when ANY of these hold:
  *   - `result.success === false` (explicit), OR
  *   - `result.fieldErrors` is present (per-field validation messages), OR
- *   - `result.error` is present AND `result.success !== true`.
+ *   - `result.error` is present AND `result.success !== true`, OR
+ *   - `result.errors` is present AND `result.success !== true` (the shape
+ *     Next.js examples return from a `useActionState` action, `{ errors }`).
  *
  * Success is the explicit `success: true`, or a bare value (or
  * undefined/null) carrying no error markers. This means an action that returns
@@ -87,6 +95,7 @@ function isFailureResult(result) {
   if (result.success === false) return true;
   if (result.fieldErrors != null) return true;
   if (result.error != null && result.success !== true) return true;
+  if (result.errors != null && result.success !== true) return true;
   return false;
 }
 
@@ -439,6 +448,18 @@ function methodNotAllowed() {
  */
 export async function runFormAction(route, params, url, req, ssrOpts, deps) {
   const { actionIndex, allowedOrigins = [], onError, logger } = deps;
+  // An action that throws answers with the page's nearest error.ts (else
+  // global-error, else the default 500 page), the way a failed page render does
+  // and the way Next.js answers a server action that throws (#1686): not a bare
+  // text 500. The boundary sees a sanitized error in production, and the sink
+  // hears it once, as an action error.
+  /** @param {unknown} e */
+  // `throw undefined` would read as "no error" downstream (renderError is
+  // checked against undefined), so it becomes a real Error first.
+  const errorPage = (e) => ssrPage(route, params, url, {
+    ...ssrOpts, req, onError,
+    renderError: e === undefined ? new Error('[webjs] the action threw undefined') : e,
+  });
 
   // Not a form body at all (a stray JSON POST, a probe): the page path exists
   // and only renders. Answered before the body is touched.
@@ -484,7 +505,20 @@ export async function runFormAction(route, params, url, req, ssrOpts, deps) {
   // 422 re-render) from seeing a key it did not put there.
   formData.delete(FORM_ACTION_FIELD);
 
-  const found = await lookupActionIdentity(actionIndex, id);
+  // `<form action=${rsvp.bind(null, slug)}>` submits `<hash>/<fn>#<args>`: the
+  // action's own identity, then the bound arguments, which the call below puts
+  // ahead of the form input. A visitor can rewrite them like any field, so the
+  // action authorizes them (as in Next, where an action is a public endpoint).
+  /** @type {unknown[]} */
+  let bound;
+  let baseId;
+  try {
+    ({ id: baseId, args: bound } = splitActionId(id));
+  } catch {
+    return new Response('Malformed bound action arguments', { status: 400 });
+  }
+
+  const found = await lookupActionIdentity(actionIndex, baseId);
   if (!found.ok) {
     // The action's module threw at import (a bad env var read at module scope,
     // a syntax error in dev). That is a server fault, not skew: telling the
@@ -492,8 +526,7 @@ export async function runFormAction(route, params, url, req, ssrOpts, deps) {
     // load, and swallowing the error would leave nothing in the log or the APM
     // sink. Surface it the way any other action throw is surfaced.
     if (found.reason === 'load-failed') {
-      if (typeof onError === 'function') onError(found.error);
-      return await formActionErrorResponse(found.error, ssrOpts.dev);
+      return errorPage(found.error);
     }
     if (found.reason === 'skew') {
       return ssrPage(route, params, url, {
@@ -527,35 +560,77 @@ export async function runFormAction(route, params, url, req, ssrOpts, deps) {
     );
   }
 
-  // A form-bound action always receives the `FormData` (#1155). `validate` is
-  // the typing seam: it takes the FormData and its transform-return becomes the
-  // action's typed input, the same `runValidate` contract the RPC path uses.
-  let args = [formData];
+  // A form-bound action receives the submitted fields as ONE object that reads
+  // both ways (`action-input.js`): `input.title`, the shape the same action gets
+  // over RPC and through `route()`, and `input.get('title')`, the FormData
+  // readers. It used to receive the raw FormData, so a validator written for
+  // the RPC shape read `undefined` and answered every submission with a 422
+  // (#1664). `validate`, middleware, the action and `invalidates` all see it.
+  // The raw `formData` local keeps feeding the #1581 submitted-values path.
+  const warn = ssrOpts.dev ? (logger && logger.warn ? (m) => logger.warn(m) : (m) => console.warn(m)) : undefined;
+  let args = [formInput(formData, { warn, label: fnName })];
   const validate = actionConfigFn(mod, 'validate');
   if (typeof validate === 'function') {
-    const v = runValidate(validate, args[0]);
+    const v = await runValidate(validate, args[0]);
     if (!v.ok) {
-      if (v.thrown !== undefined) {
-        // A THROWN validator is answered here rather than rethrown. Letting it
+      if (v.thrown !== undefined && !v.invalid) {
+        // A validator that crashed (any throw but a schema library's
+        // validation error) is answered here rather than rethrown. Letting it
         // escape reaches the handler's last-resort catch, which reports the
         // SAME error to `onError` a second time and answers a bare 500 with no
         // digest, so the one thing that makes a prod error diagnosable is lost.
         // The RPC path does exactly this (`actionErrorResponse` in actions.js).
-        if (typeof onError === 'function') onError(v.thrown);
-        return await formActionErrorResponse(v.thrown, ssrOpts.dev);
+        return errorPage(v.thrown);
       }
-      // A structured failure envelope is a NORMAL result the page renders, so
-      // it takes the 422 re-render path exactly as a failing action would,
-      // submitted values included (#1581).
+      // A structured failure envelope, or a schema library's validation error
+      // (a throw carrying `issues`, mapped to fieldErrors by runValidate for
+      // every transport), is a NORMAL result the page renders, so it takes the
+      // 422 re-render path exactly as a failing action would, submitted values
+      // included (#1581).
       return ssrPage(route, params, url, { ...ssrOpts, req, actionData: withSubmittedValues(v.result, formData), status: 422 });
     }
     args = [v.value];
   }
 
-  const searchParams = Object.fromEntries(url.searchParams.entries());
+  const searchParams = searchParamsRecord(url.searchParams);
+  // Next.js's `useActionState` contract: an action declaring TWO parameters is
+  // called `(prevState, formData)`, prevState being what this same action
+  // returned last time (carried by the signed flash cookie; undefined on the
+  // first submission). validate sees the single input; middleware and
+  // invalidates see the call's arguments, the bound ones first, as over RPC.
+  // Bound arguments come before both, so `(slug, prevState, formData)` reads
+  // its prevState once the bound parameters are counted off, as in Next.
+  // The count is the DECLARED one (#1686): `fn.length` stops at the first
+  // default, so `(prevState = initial, formData)` would read as 0, and that
+  // default is how an action supplies the first submission's state.
+  // The form data's slot is the parameter after prevState, and it has no
+  // default in that shape: `(input, opts = {})` is an ordinary action whose
+  // optional second parameter must not turn its input into a prevState.
+  const original = originalAction(fn);
+  const defaults = declaredParamDefaults(original);
+  const withPrevState = declaredParamCount(original) - bound.length >= 2 && !(defaults && defaults[bound.length + 1]);
+  const flash = withPrevState ? await readFlash(req) : null;
+  const prevState = flash && flash.id === id ? flash.result : undefined;
   /** @type {ActionResult | undefined} */
   let result;
   let ranAction = false;
+  // What a COMPLETED action owes the cache and the browser, whichever way it
+  // finished (a returned result or a thrown redirect()): its `invalidates` tags
+  // evicted and reported, and any revalidatePath() reported. A middleware
+  // short-circuit (the action never ran) evicts nothing.
+  const completionHeaders = async () => {
+    /** @type {string[]} */
+    let invalidated = [];
+    if (ranAction) {
+      invalidated = resolveTags(actionConfigFn(mod, 'invalidates'), [...bound, ...args]);
+      if (invalidated.length) await revalidateTags(invalidated);
+    }
+    /** @type {Record<string, string> | null} */
+    let headers = invalidated.length ? { 'x-webjs-invalidate': invalidated.join(',') } : null;
+    const refresh = refreshHeaderValue();
+    if (refresh) headers = { ...(headers || {}), 'x-webjs-refresh': refresh };
+    return headers;
+  };
   try {
     const middleware = actionMiddleware(mod);
     result = await runWithActionSignal(actionReq.signal, () =>
@@ -563,7 +638,7 @@ export async function runFormAction(route, params, url, req, ssrOpts, deps) {
         middleware,
         {
           request: actionReq,
-          args,
+          args: [...bound, ...args],
           signal: actionReq.signal,
           // Route context a form middleware may want, absent on the RPC path
           // because an RPC call has no page. Params are awaitable AND
@@ -572,17 +647,25 @@ export async function runFormAction(route, params, url, req, ssrOpts, deps) {
           searchParams: makeThenable(searchParams),
           url,
         },
-        () => { ranAction = true; return fn(...args); },
+        () => { ranAction = true; return withPrevState ? fn(...bound, prevState, ...args) : fn(...bound, ...args); },
       ));
   } catch (err) {
     if (isRedirect(err)) {
       const e = /** @type any */ (err);
-      // A thrown redirect from an action (a POST) defaults to 307 Temporary
-      // Redirect, which is method-preserving so the action's intent survives
-      // the bounce; an explicit `redirect(url, status)` overrides it. This is
-      // deliberately NOT the GET gate's 302 default (see ssr.js). PRG (303) is
-      // the SUCCESS-result path below.
-      return new Response(null, { status: e.status || 307, headers: { location: e.url } });
+      // A thrown redirect from a form action ALWAYS answers 303 See Other, as
+      // Next.js does for a server action: the browser follows with a GET, so
+      // the mutation runs once. A 307 (the old default) re-POSTed the body,
+      // identity field included, and ran the action a second time on the
+      // target page. An explicit status is ignored here for the same reason.
+      // The action finished its work before throwing (create, then redirect),
+      // so it evicts and reports exactly as a returned result does.
+      const done = await completionHeaders();
+      const res = new Response(null, { status: 303, headers: { location: headerSafeLocation(e.url), ...done } });
+      // The action finished, so an earlier flash (a failure kept as the next
+      // prevState) no longer describes it: in Next the redirect unmounts the
+      // form and its state goes with it.
+      res.headers.append('set-cookie', flashSetCookie(null));
+      return res;
     }
     // `route` and `params` ride along so the boundary renders inside its
     // layouts, exactly as it does on the page-render path (#1298).
@@ -600,8 +683,7 @@ export async function runFormAction(route, params, url, req, ssrOpts, deps) {
     // boundary as the page-render path (#848), not a generic 500.
     if (isForbidden(err)) return ssrForbidden(route, { ...ssrOpts, req, url, route, params });
     if (isUnauthorized(err)) return ssrUnauthorized(route, { ...ssrOpts, req, url, route, params });
-    if (typeof onError === 'function') onError(err);
-    return await formActionErrorResponse(err, ssrOpts.dev);
+    return errorPage(err);
   }
 
   // A streamed return (#489) has no consumer here. The RPC stub decodes frames;
@@ -613,8 +695,7 @@ export async function runFormAction(route, params, url, req, ssrOpts, deps) {
       `The action ${fnName} returned a stream, which a form submission cannot consume. `
       + 'Return an ActionResult from a form-bound action; stream from a programmatic call instead.',
     );
-    if (typeof onError === 'function') onError(err);
-    return await formActionErrorResponse(err, ssrOpts.dev);
+    return errorPage(err);
   }
 
   // Only a COMPLETED action evicts its `invalidates` tags; a middleware
@@ -628,14 +709,10 @@ export async function runFormAction(route, params, url, req, ssrOpts, deps) {
   // after a successful PRG the client learns nothing from it. The redirect's
   // own re-render is server-side and seeds fresh data, so what remains exposed
   // is only a later client refetch of a separately cached GET key.
-  let invalidated = [];
-  if (ranAction) {
-    invalidated = resolveTags(actionConfigFn(mod, 'invalidates'), args);
-    if (invalidated.length) await revalidateTags(invalidated);
-  }
-  const invalidateHeader = invalidated.length
-    ? { 'x-webjs-invalidate': invalidated.join(',') }
-    : null;
+  // revalidatePath() in the action is reported too: the router drops its
+  // cached copies of those paths when it applies an in-place response (the
+  // redirect a success answers with re-renders the target on the server anyway).
+  const invalidateHeader = await completionHeaders();
 
   // An action MAY return a `Response` directly (e.g. a content-negotiated
   // `streamResponse`, #248). Honor it verbatim, so the action owns the status +
@@ -650,10 +727,32 @@ export async function runFormAction(route, params, url, req, ssrOpts, deps) {
     // page's own path so a poisoned value cannot become an open redirect.
     const ownPath = (url.pathname + url.search) || '/';
     const safe = result ? sameSiteRedirect(result.redirect) : null;
-    return new Response(null, {
+    // The PUBLIC target the browser goes to. The action's own `redirect` is
+    // written as the browser sees it (with the `webjs.basePath` mount, as an
+    // author's links are), while the page's own path comes from the request,
+    // which lost the mount at ingress, so it gets the mount back. Without it a
+    // mounted app's success redirect left the app (`Location: /f`).
+    const mount = appBasePath();
+    const target = safe || withBasePath(ownPath, mount);
+    const res = new Response(null, {
       status: 303,
-      headers: { location: safe || ownPath, ...invalidateHeader },
+      // Header-safe, as every thrown redirect() is: a non-Latin-1 target
+      // would otherwise throw while the Response is built and turn a
+      // successful write into a 500.
+      headers: { location: headerSafeLocation(target), ...invalidateHeader },
     });
+    // The result survives the redirect (Next's useActionState shows a success
+    // message after a submit): the page it lands on reads it as actionData
+    // once, and the next submission of this action gets it as prevState.
+    // A success with nothing to carry still replaces an earlier flash, so the
+    // next submission's prevState is never a stale failure.
+    // Bound to the page the redirect lands on, so no other page shows it,
+    // app-root-relative as the render compares it: the mount stripped ONCE
+    // from the public target.
+    const path = appRelativePath(new URL(target, url).pathname, mount);
+    const value = result !== undefined && result !== null ? await encodeFlash({ id, result, shown: false, path }) : null;
+    res.headers.append('set-cookie', flashSetCookie(value));
+    return res;
   }
 
   // FAILURE: re-render the SAME page with the action result available on
@@ -668,32 +767,14 @@ export async function runFormAction(route, params, url, req, ssrOpts, deps) {
   if (invalidateHeader && page instanceof Response) {
     for (const [k, v] of Object.entries(invalidateHeader)) page.headers.set(k, v);
   }
+  // The failure is already on screen, so it is stored as SHOWN: only the next
+  // submission's prevState reads it.
+  if (page instanceof Response) {
+    const value = await encodeFlash({ id, result, shown: true });
+    if (value) {
+      try { page.headers.append('set-cookie', flashSetCookie(value)); } catch { /* immutable: skip the carry */ }
+    }
+  }
   return page;
 }
 
-/**
- * A thrown form action becomes a 500 whose body is sanitized the same way the
- * RPC path's is (#749): dev shows the real message, prod shows a generic one
- * plus a correlation digest and logs the full error. A raw driver message or an
- * fs path is not author-controlled, so it does not reach the browser, and here
- * the browser is showing it to a person rather than parsing it.
- *
- * @param {unknown} err
- * @param {boolean} [dev]
- * @returns {Promise<Response>}
- */
-async function formActionErrorResponse(err, dev) {
-  if (dev) {
-    console.error('[webjs] form action threw:', err);
-    const msg = err instanceof Error ? err.message : String(err);
-    return new Response(msg, { status: 500 });
-  }
-  if (isControlFlowThrow(err)) {
-    console.error('[webjs] form action threw:', err);
-    const msg = err instanceof Error ? err.message : String(err);
-    return new Response(msg, { status: 500 });
-  }
-  const digest = await errorDigest(err);
-  console.error(`[webjs] form action threw [digest=${digest}]:`, err);
-  return new Response(`${GENERIC_ERROR_MESSAGE} (digest ${digest})`, { status: 500 });
-}

package/src/html-cache.js

@@ -28,8 +28,8 @@ import { getStore } from './cache.js';
 import { STREAM_MARKER } from './conditional-get.js';
 import { createHash } from 'node:crypto';
 import { publishedBuildId, basePath } from './importmap.js';
-import { stripBasePath } from './base-path.js';
-import { dynamicAccessed, getRequest } from './context.js';
+import { stripBasePath, withBasePath } from './base-path.js';
+import { dynamicAccessed, getRequest, recordRevalidatedPath } from './context.js';
 import { shared } from './process-shared.js';
 
 /** Namespace prefix for every cached-HTML key, so a flush can target it. */
@@ -278,11 +278,35 @@ export function isCacheableResponse(res, guards = {}) {
  * is ever seen, or grows an unbounded one. Either way eviction silently stops
  * working, which is worse than the explicit contract above.
  *
+ * Next.js parity: the optional second argument is Next's type. `'layout'`
+ * revalidates the path AND everything below it (here: the whole HTML cache),
+ * and a route PATTERN (`'/blog/[slug]'`) revalidates every page it matches
+ * (also the whole cache, since entries are keyed by concrete url). When called
+ * from a server action invoked over RPC, the paths ride back to the browser on
+ * `x-webjs-refresh`, and the page on screen re-renders in place if it is one
+ * of them, so the caller sees the fresh data with no reload.
+ *
  * @param {string} path  e.g. '/blog', '/blog?page=2', or 'https://app.example/blog'
+ * @param {'page' | 'layout'} [type]
  * @returns {Promise<void>}
  */
-export async function revalidatePath(path) {
+export async function revalidatePath(path, type) {
   if (typeof path !== 'string' || !path) return;
+  const layout = type === 'layout';
+  {
+    // The browser compares the reported path with location.pathname, which
+    // carries webjs.basePath. An absolute url is already the public form; a
+    // bare path is app-relative (what the caller writes), so the base path is
+    // put back for the report.
+    let pathname = path;
+    if (/^https?:\/\//i.test(path)) { try { pathname = new URL(path).pathname; } catch { /* keep */ } }
+    else pathname = withBasePath(pathname, basePath());
+    recordRevalidatedPath(pathname.split('?')[0] || '/', layout);
+  }
+  if (layout || path.includes('[')) {
+    await revalidateAll();
+    return;
+  }
   let url;
   if (/^https?:\/\//i.test(path)) {
     try { url = new URL(path); } catch { return; }
@@ -367,8 +391,15 @@ export async function commitHtmlCache(req, res, url) {
   const marker = res.headers.get(HTML_CACHE_MARKER);
   if (!marker) return res;
   res.headers.delete(HTML_CACHE_MARKER);
-  const revalidateSeconds = Number(marker);
+  // `<seconds>:<generation>`, the generation the render STARTED under (#1689).
+  // A render that straddled a `revalidateAll()` (every dev rebuild ends with
+  // one) produced bytes from before the eviction, and writing them now would
+  // file them under the new generation's key, where every later request would
+  // be served the pre-edit page for the whole window. Skip the write instead.
+  const [secondsPart, generationPart] = marker.split(':');
+  const revalidateSeconds = Number(secondsPart);
   if (!Number.isFinite(revalidateSeconds) || revalidateSeconds <= 0) return res;
+  if (generationPart !== undefined && Number(generationPart) !== _generation.n) return res;
   // Per-user leak defense (#241). The page set `revalidate` (asserting "same
   // for everyone"), but if the render actually read per-user request state
   // (cookies() / headers() / getSession()), its body varies by visitor and

package/src/importmap.js

@@ -36,7 +36,7 @@ let _extraEntries = {};
 /**
  * Per-build memos (#1644), each `{ epoch, value }` keyed on `buildEpoch()`.
  * Every setter in this module bumps the epoch, as do the asset-hash roots,
- * the elision fingerprint, the hash-cache clear, and the dev rebuild.
+ * the serve fingerprint, the hash-cache clear, and the dev rebuild.
  * @type {{ epoch: number, value: { imports: Record<string, string>, integrity?: Record<string, string> } }}
  */
 let _mapMemo = { epoch: 0, value: { imports: {} } };
@@ -550,7 +550,7 @@ export function buildImportMap(opts = {}) {
  * BYTE-IDENTICAL to the importmap target (same base-path + `?v` rewrite): a
  * differing href would make the browser treat the preload and the import as two
  * resources and double-fetch. The matching `integrity` comes from the same map.
- * A specifier NOT in the importmap (an unpinned / unreached / elided vendor)
+ * A specifier NOT in the importmap (an unpinned / unreached vendor)
  * yields nothing, so this never over-fetches. Duplicate hrefs are collapsed.
  *
  * Framework runtime specifiers (`@webjsdev/core`...) are excluded: core is

package/src/instrumentation.js

@@ -20,6 +20,7 @@ import { stat } from 'node:fs/promises';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { devImport } from './dev-import.js';
 import { shared } from './process-shared.js';
+import { errorDigest } from './action-error.js';
 
 /**
  * Per-boot handoff channel for a `register()`-registered error sink. An
@@ -73,7 +74,11 @@ export async function findInstrumentationClient(appDir) {
  *
  * @param {string} appDir
  * @param {{ dev?: boolean, logger?: { error?: (...a: any[]) => void } }} [opts]
- * @returns {Promise<{ onError: ((error: unknown, ctx?: any) => void) | null }>}
+ * The module may also export Next.js's `onRequestError(error, request, context)`,
+ * which is returned as `onRequestError` for the request handler to call on
+ * every reported server error (see `buildRequestErrorReport`).
+ *
+ * @returns {Promise<{ onError: ((error: unknown, ctx?: any) => void) | null, onRequestError: OnRequestError | null }>}
  */
 export async function runInstrumentation(appDir, opts = {}) {
   const { dev = false, logger } = opts;
@@ -82,15 +87,18 @@ export async function runInstrumentation(appDir, opts = {}) {
     const p = join(appDir, name);
     if (await exists(p)) { file = p; break; }
   }
-  if (!file) return { onError: null };
+  if (!file) return { onError: null, onRequestError: null };
   // Per-boot store: setOnError writes here, scoped to THIS run's async context.
   const store = { onError: null };
+  /** @type {OnRequestError | null} */
+  let onRequestError = null;
   await _als.run(store, async () => {
     try {
       const mod = await devImport(file, dev);
       const register = typeof mod.default === 'function'
         ? mod.default
         : (typeof mod.register === 'function' ? mod.register : null);
+      if (typeof mod.onRequestError === 'function') onRequestError = mod.onRequestError;
       if (register) await register();
     } catch (e) {
       // A failing instrumentation hook must not crash boot: log and continue, the
@@ -98,5 +106,53 @@ export async function runInstrumentation(appDir, opts = {}) {
       logger?.error?.(`[webjs] instrumentation.{js,ts} register() failed`, { err: String(e) });
     }
   });
-  return { onError: store.onError };
+  return { onError: store.onError, onRequestError };
+}
+
+/**
+ * @typedef {(
+ *   error: Error & { digest: string },
+ *   request: { path: string, method: string, headers: Record<string, string> },
+ *   context: { routerKind: 'App Router', routePath: string, routeType: 'render' | 'route' | 'action' | 'proxy', revalidateReason: undefined, renderSource?: string },
+ * ) => void | Promise<void>} OnRequestError
+ */
+
+/**
+ * The internal pipeline phase to Next's `routeType`. A page render, a metadata
+ * route, and a last-resort crash in the handler are all `render`; root and
+ * segment middleware are `proxy` (Next 16's name for middleware).
+ * @type {Record<string, 'render' | 'route' | 'action' | 'proxy'>}
+ */
+const ROUTE_TYPE = { ssr: 'render', metadata: 'render', handle: 'render', route: 'route', action: 'action', middleware: 'proxy' };
+
+/**
+ * Build the three arguments Next.js passes to `onRequestError`, from the error
+ * the pipeline caught, the request, and its phase. The error gains a `digest`
+ * (the same hash the sanitized production responses carry, so a report maps
+ * back to what the client saw) when it does not already have one.
+ *
+ * @param {unknown} error
+ * @param {Request} request
+ * @param {string} phase
+ * @param {string} [routePath] the app-relative route file path, `/app/blog/[slug]`
+ * @returns {Promise<Parameters<OnRequestError>>}
+ */
+export async function buildRequestErrorReport(error, request, phase, routePath) {
+  /** @type {any} */
+  let err = error instanceof Error ? error : new Error(String(error));
+  if (typeof err.digest !== 'string') {
+    const digest = await errorDigest(err);
+    if (Object.isExtensible(err)) err.digest = digest;
+    else err = Object.assign(new Error(err.message, { cause: err }), { digest });
+  }
+  /** @type {Record<string, string>} */
+  const headers = {};
+  for (const [k, v] of request.headers) headers[k] = v;
+  let path = '/';
+  try { const u = new URL(request.url); path = u.pathname + u.search; } catch { /* keep / */ }
+  return [
+    err,
+    { path, method: request.method, headers },
+    { routerKind: 'App Router', routePath: routePath || path.split('?')[0], routeType: ROUTE_TYPE[phase] || 'render', revalidateReason: undefined },
+  ];
 }

package/src/js-scan.js

@@ -1,6 +1,7 @@
 /**
  * Low-level lexical scanning helpers shared by the convention validator
- * (`check.js`) and the component-elision analyser (`component-elision.js`).
+ * (`check.js`), the component scanner and the browser-code signals
+ * (`client-signals.js`).
  *
  * These are deliberately a hand-rolled lexer, NOT a full TS parse. The
  * framework prioritises fast dev-time rebuilds; a real parser would be ~50x
@@ -320,7 +321,7 @@ function scanLiterals(src, { placeholder = false, blankStrings = false } = {}) {
  * Blank ONLY comments, keeping string AND template-literal content verbatim
  * (position-preserving: same length, newlines kept). The sibling
  * `redactStringsAndTemplates` blanks templates too, which is wrong for callers
- * that need to read inside `html` templates (the elision render-tag scanner) or
+ * that need to read inside `html` templates (the render-tag scanner) or
  * inside string arguments (`whenDefined('tag')`). This keeps both and removes
  * only comment text, so prose in a comment cannot be read as a real signal
  * (issue #179). It reuses the same regex-versus-division and tagged-template
@@ -434,8 +435,8 @@ export function extractWebComponentClassBodies(content) {
   const bodies = [];
   // The optional `(?:\s*<[^{}();]*?>)?` skips a TypeScript generic parameter
   // list on the class name (`class Grid<T> extends WebComponent`), so a generic
-  // component is not missed (which would let elision wrongly strip an
-  // interactive component, the unsafe direction). The exclusion class keeps the
+  // component is not missed (which would leave its class body unlinted, the
+  // unsafe direction). The exclusion class keeps the
   // generic from swallowing the class body / a call, and stops it staying
   // within the type-parameter list (#753, found differentially).
   const re = /class\s+\w+(?:\s*<[^{}();]*?>)?\s+extends\s+WebComponent/g;