@webjsdev/server 0.8.91 → 0.10.0

package/src/action-seed.js

@@ -64,7 +64,7 @@ import * as nodeModule from 'node:module';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { stringify } from '@webjsdev/core';
+import { stringify, installActionBind } from '@webjsdev/core';
 import { hashFile } from './actions.js';
 import { isStreamable } from './action-stream.js';
 import { serverRuntime } from './listener-core.js';
@@ -107,6 +107,28 @@ const _flags = shared('action-seed-flags', () => ({ seedEnabled: false, devMode:
  * @type {WeakMap<Function, { file: string, fnName: string }[]>}
  */
 const _identity = shared('action-identity', () => new WeakMap());
+/** The function each seed Proxy wraps, so its source can still be read
+ * (`Function.prototype.toString` on a Proxy is native code). */
+const _originals = shared('action-originals', () => new WeakMap());
+
+/** The property a facade's exported wrapper reads its real action through. */
+const ORIGINAL = Symbol.for('webjs.action.original');
+
+/**
+ * The action function itself, behind a facade's exported wrapper or a seed
+ * Proxy, or `fn` when it is neither. Used to read the action's own source,
+ * which neither wrapper carries (#1686).
+ * @param {Function} fn
+ * @returns {Function}
+ */
+export function originalAction(fn) {
+  /** @type {any} */
+  const f = fn;
+  let inner;
+  try { inner = f[ORIGINAL]; } catch { inner = undefined; }
+  if (typeof inner === 'function') return inner;
+  return _originals.get(fn) ?? fn;
+}
 
 /** Memoized `absPath -> hash` so a hot action call does not re-hash per call. */
 const _hashCache = shared('action-hash-cache', () => new Map());
@@ -267,6 +289,10 @@ async function assertDeterministic(prev, next, hash, fnName) {
  */
 export function __actionWrap(file, fnName, orig) {
   if (typeof orig !== 'function') return orig;
+  // `action.bind(null, id)` keeps the identity, so the bound function can be
+  // bound to a form (Next.js's way to pass an extra argument). Installed on the
+  // target, so the seed Proxy below forwards it too.
+  installActionBind(orig);
   // APPEND, defining module first. A barrel is faceted too and its body runs
   // AFTER the module it re-exports from, so the first registration is the
   // defining one: the module that also carries `validate` / `middleware` /
@@ -281,6 +307,7 @@ export function __actionWrap(file, fnName, orig) {
   _identity.set(orig, list);
   if (!_flags.seedEnabled) return orig;
   const wrapped = seedProxy(file, fnName, orig);
+  _originals.set(wrapped, orig);
   // The wrapper is a fresh object every time, so it shares the TARGET's list
   // rather than starting one of its own.
   _identity.set(wrapped, list);
@@ -552,6 +579,17 @@ function buildFacade(origUrl, absPath, exports) {
     out += `  const fn = ${v} || (${v} = __w(${file}, ${k}, __orig[${k}]));\n`;
     out += `  return typeof fn === 'function' ? fn.apply(this, args) : fn;\n`;
     out += `}\n`;
+    // Keep the action's declared arity: a form-bound action declaring
+    // `(prevState, formData)` is told apart by `fn.length` (Next's
+    // useActionState contract), and the rest-args wrapper reports 0. It is a
+    // GETTER, read when the dispatcher asks: a circular import can run this
+    // facade before the real module, while a `const` action is still in TDZ,
+    // and a value captured then would freeze the arity at 0.
+    out += `try { Object.defineProperty(${n}, 'length', { configurable: true, get() { try { return (__orig[${k}] && __orig[${k}].length) || 0; } catch { return 0; } } }); } catch {}\n`;
+    // The real function, for reading its source (`originalAction`): the
+    // dispatcher counts DECLARED parameters, which `length` undercounts at a
+    // default (#1686). A getter for the same TDZ reason as `length`.
+    out += `try { Object.defineProperty(${n}, Symbol.for('webjs.action.original'), { configurable: true, get() { try { return __orig[${k}]; } catch { return undefined; } } }); } catch {}\n`;
     out += `__w(${file}, ${k}, ${n});\n`;
   }
   for (const n of exports.valNames) {
@@ -663,10 +701,11 @@ export async function registerActionHooks(opts = {}) {
     g[installed] = true;
     // Bun has no module.registerHooks; install the same facade via Bun.plugin.
     const { installBunSeedPlugin } = await import('./action-seed-bun.js');
-    // Dev rewrites the app's `#` imports to absolute paths (#1575); the
-    // rewrite reads the app roots dev registered, so it is a no-op in prod.
-    const { rewriteAppAliases } = await import('./dev/bun-app-source.js');
-    installBunSeedPlugin({ isSeedCandidate, buildSeedFacade, serverFileRe: SERVER_FILE_RE, rewriteAliases: rewriteAppAliases });
+    // Dev rewrites the app's `#` imports to absolute paths (#1575) and stamps
+    // the module versions (#1689); both read the app roots dev registered, so
+    // the rewrite is a no-op in prod.
+    const { rewriteAppSource } = await import('./dev/bun-app-source.js');
+    installBunSeedPlugin({ isSeedCandidate, buildSeedFacade, serverFileRe: SERVER_FILE_RE, rewriteAliases: rewriteAppSource });
     _flags.hookInstalled = true;
     return;
   }

package/src/actions.js

@@ -1,4 +1,5 @@
 import { digestHex } from './crypto-utils.js';
+import { headerSafeLocation } from './redirect-location.js';
 import { readFile } from 'node:fs/promises';
 import { join, sep } from 'node:path';
 import { walk } from './fs-walk.js';
@@ -16,11 +17,12 @@ import { runActionChain } from './action-middleware.js';
 import { isStreamable, streamActionResponse } from './action-stream.js';
 import { isControlFlowThrow, errorDigest, GENERIC_ERROR_MESSAGE } from './action-error.js';
 import { ifNoneMatchSatisfied } from './conditional-get.js';
-import { getBodyLimits } from './context.js';
+import { getBodyLimits, refreshHeaderValue } from './context.js';
 import { basePath } from './importmap.js';
 import { withBasePath } from './base-path.js';
-import { FORM_ACTION_ID_KEY } from '@webjsdev/core';
+import { FORM_ACTION_ID_KEY, FORM_ACTION_FIELD, isRedirect } from '@webjsdev/core';
 import { devImport } from './dev-import.js';
+import { formInput, isFormData } from './action-input.js';
 
 /**
  * The JSON / RPC body cap in effect for the current request: the per-request
@@ -43,6 +45,49 @@ function jsonBodyLimit() {
  */
 export const RPC_CONTENT_TYPE = 'application/vnd.webjs+json';
 
+/**
+ * The `issues` array a schema library's validation error carries (zod, valibot,
+ * Standard Schema), or null for any other throw.
+ * @param {unknown} e
+ * @returns {Array<{ path?: unknown[], message?: string }> | null}
+ */
+function schemaIssues(e) {
+  const issues = e && typeof e === 'object' ? /** @type {any} */ (e).issues : undefined;
+  return Array.isArray(issues) && issues.length > 0 ? issues : null;
+}
+
+/**
+ * A failure result from a schema error's issues: the first message per field
+ * as `fieldErrors` (a nested path joined with dots), and a form-level `error`
+ * for an issue with no path.
+ * @param {unknown} e
+ */
+function issuesResult(e) {
+  /** @type {Record<string, string>} */
+  const fieldErrors = {};
+  let error;
+  for (const issue of schemaIssues(e) || []) {
+    // A segment is a key, or Standard Schema's { key }; a symbol key is
+    // converted explicitly, since join's implicit conversion throws on one.
+    const path = Array.isArray(issue.path)
+      ? issue.path.map((p) => {
+        const k = p && typeof p === 'object' && 'key' in p ? /** @type {any} */ (p).key : p;
+        return typeof k === 'symbol' ? (k.description ?? '') : String(k);
+      }).join('.')
+      : '';
+    const message = typeof issue.message === 'string' ? issue.message : 'Invalid value.';
+    if (path) {
+      // Own keys only (a field named `constructor` is not already present),
+      // and defined rather than assigned, so `__proto__` is a field, not the
+      // object's prototype.
+      if (!Object.hasOwn(fieldErrors, path)) {
+        Object.defineProperty(fieldErrors, path, { value: message, enumerable: true, writable: true, configurable: true });
+      }
+    } else if (!error) error = message;
+  }
+  return { success: false, fieldErrors, ...(error ? { error } : {}), status: 422 };
+}
+
 /**
  * Run an attached input validator against an action's input, shared by the RPC
  * path (`invokeAction`) and the `route()` REST adapter so the contract is
@@ -52,21 +97,27 @@ export const RPC_CONTENT_TYPE = 'application/vnd.webjs+json';
  * @param {(input: any) => any} validate the attached validator
  * @param {any} input the value handed to the validator (the action's first arg
  *   on RPC, the merged query/params/body object on REST)
- * @returns {{ ok: true, value: any } | { ok: false, result: { success: false, fieldErrors?: Record<string,string>, error?: string, status: number }, thrown?: unknown }}
+ * @returns {{ ok: true, value: any } | { ok: false, result: { success: false, fieldErrors?: Record<string,string>, error?: string, status: number }, thrown?: unknown, invalid?: boolean }}
  *   `ok: true` carries the value to pass to the action (the validated `data`,
  *   the transformed return, or the original input). `ok: false` carries the
  *   structured failure result the caller serializes back; on a THROWN validator
  *   it also carries the original error on `thrown` so a caller can salvage a
  *   schema lib's structured `issues` (the REST path does, for back-compat).
  */
-export function runValidate(validate, input) {
+export async function runValidate(validate, input) {
   let out;
   try {
-    out = validate(input);
+    // Awaited, so an async validator (an async schema check, a lookup) works
+    // like a sync one; a returned Promise must never read as a transformed input.
+    out = await validate(input);
   } catch (e) {
-    // Throw-to-reject (the classic `Schema.parse` contract). Map to a sanitized
-    // failure result; a thrown validator is a 400 (bad input), not a 500.
-    // Surface only the message; `thrown` lets the REST caller recover `issues`.
+    // A schema library's validation error (a throw carrying `issues`: zod's
+    // `.parse`, valibot, Standard Schema) is invalid INPUT, mapped once here so
+    // every transport answers it alike: the issues become fieldErrors with a
+    // 422, as a structured envelope failure is (`invalid` marks it).
+    if (schemaIssues(e)) return { ok: false, result: issuesResult(e), thrown: e, invalid: true };
+    // Any other throw-to-reject: a sanitized failure result, a 400 over REST;
+    // `thrown` lets the RPC path treat it as the crash it may be.
     const msg = e instanceof Error ? e.message : String(e);
     return { ok: false, result: { success: false, error: msg, status: 400 }, thrown: e };
   }
@@ -321,7 +372,7 @@ function buildStubBody({ hash, method, fnNames, actionUrl }) {
   // `method` is a default POST), so the first client call resolves from the
   // seed with no hydration round-trip. The browser-cache staleness check is
   // GET-only (only a GET is browser-cached).
-  const imports = ['stringify as __s', 'parse as __p', 'takeSeed as __seedTake', 'SEED_MISS as __MISS', 'markStale as __markStale', 'parseTagHeader as __tagHdr', 'activeActionSignal as __sig',
+  const imports = ['stringify as __s', 'parse as __p', 'takeSeed as __seedTake', 'SEED_MISS as __MISS', 'markStale as __markStale', 'parseTagHeader as __tagHdr', 'activeActionSignal as __sig', 'applyActionRefresh as __refresh', 'followActionRedirect as __redirect', 'installActionBind as __bindable',
     // Streaming RPC (#489): an action returning a stream / async iterable sends
     // back a framed body; the stub decodes it into an async iterable the caller
     // `for await`s. The imports are small constants + one decoder factory.
@@ -342,6 +393,12 @@ function buildStubBody({ hash, method, fnNames, actionUrl }) {
   // caught on the next read).
   lines.push(`async function __handle(res, fn, key, since) {`);
   lines.push(`  const inv = __tagHdr(res.headers.get('x-webjs-invalidate')); if (inv.length) __markStale(inv);`);
+  // redirect() in the action (Next parity): navigate there; the call's promise
+  // rejects with the redirect sentinel, which the page ignores unhandled.
+  lines.push(`  const rd = res.headers.get('x-webjs-redirect'); if (rd) return __redirect(rd);`);
+  // revalidatePath() in the action: refresh the page on screen in place when
+  // it was revalidated, BEFORE the caller's await resolves (Next behaviour).
+  lines.push(`  const rf = res.headers.get('x-webjs-refresh'); if (rf) await __refresh(rf);`);
   lines.push(`  if (key != null) { const t = __tagHdr(res.headers.get('x-webjs-tags')); if (t.length) __regTags(key, t, since); }`);
   lines.push(`  const ct = res.headers.get('content-type') || '';`);
   // A streamed result (#489): the action returned a stream / async iterable.
@@ -424,7 +481,9 @@ function buildStubBody({ hash, method, fnNames, actionUrl }) {
   // load-hook registry instead; both produce the same string, which is what
   // makes the SSR'd form and the re-rendered one submit the same value.
   // Non-enumerable so `import * as actions` and a spread stay unchanged.
-  lines.push(`const __id = (fn, name) => { try { Object.defineProperty(fn, ${J(FORM_ACTION_ID_KEY)}, { value: __HASH + '/' + name }); } catch {} return fn; };`);
+  // `.bind(null, id)` keeps the identity too (installActionBind), so a bound
+  // stub re-renders to the same hidden field the server emitted.
+  lines.push(`const __id = (fn, name) => { try { Object.defineProperty(fn, ${J(FORM_ACTION_ID_KEY)}, { value: __HASH + '/' + name }); } catch {} return __bindable(fn); };`);
   for (const name of fnNames) {
     lines.push(
       name === 'default'
@@ -447,8 +506,11 @@ function buildStubBody({ hash, method, fnNames, actionUrl }) {
  *   it so a throwing sink can never affect the response.
  * @param {string[]} [allowedOrigins] cross-site origins the CSRF check allows
  *   (the app's `webjs.allowedOrigins`), for reverse-proxy / multi-domain setups.
+ * @param {{ warn?: (msg: string) => void }} [logger] where a dev diagnostic
+ *   goes (the repeated-field warning, #1664), so it lands with the form path's
+ *   warnings instead of on the console. Falls back to `console.warn`.
  */
-export async function invokeAction(idx, hash, fnName, req, onError, allowedOrigins = []) {
+export async function invokeAction(idx, hash, fnName, req, onError, allowedOrigins = [], logger) {
   const file = idx.hashToFile.get(hash);
   if (!file) return rpcResponse({ error: 'Unknown action' }, { status: 404 });
   const mod = await loadModule(file, idx.dev);
@@ -496,6 +558,17 @@ export async function invokeAction(idx, hash, fnName, req, onError, allowedOrigi
   } catch {
     return rpcResponse({ error: 'Invalid request body' }, { status: 400 });
   }
+  // A FormData first argument (the serializer round-trips one) gets the same
+  // shape a bound form submission does, so an action's input never depends on
+  // the boundary it was reached through (#1664, `action-input.js`). It stays a
+  // real FormData, so a caller that built one keeps every FormData behaviour.
+  // A component that intercepts a bound form and passes `new FormData(form)`
+  // carries the framework's hidden identity field, which the form path removes
+  // before the action runs; it is removed here too.
+  if (isFormData(args[0])) {
+    const warn = logger && logger.warn ? (m) => logger.warn(m) : (m) => console.warn(m);
+    args = [formInput(args[0], { omit: FORM_ACTION_FIELD, ...(idx.dev ? { warn, label: fnName } : {}) }), ...args.slice(1)];
+  }
   // Input validation (#245): a validator declared via the `validate` config
   // export (#488) runs SERVER-SIDE before the body on this RPC path. The RPC
   // stub sends an args array; an action conventionally takes one input object,
@@ -504,16 +577,17 @@ export async function invokeAction(idx, hash, fnName, req, onError, allowedOrigi
   // server-to-server call.
   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) {
+      if (v.thrown !== undefined && !v.invalid) {
         // A THROWN validator behaves like a thrown action: a sanitized error
         // response (non-200, so the client stub throws), with prod stack
         // sanitization. The onError sink sees the original error too.
         if (typeof onError === 'function') onError(v.thrown);
         return actionErrorResponse(v.thrown, idx.dev);
       }
-      // A structured `{ success: false, fieldErrors }` envelope is a NORMAL
+      // A structured `{ success: false, fieldErrors }` envelope, or a schema
+      // error's issues mapped to one, is a NORMAL
       // result the action author renders (`result.fieldErrors`): serialized as
       // a 200 RPC payload so the client stub returns it as a real object rather
       // than throwing, the failure status riding inside the envelope.
@@ -521,6 +595,7 @@ export async function invokeAction(idx, hash, fnName, req, onError, allowedOrigi
     }
     args = [v.value, ...args.slice(1)];
   }
+  let ranAction = false;
   try {
     // Run inside the request's AbortSignal scope (#492) and the per-action
     // middleware chain (#490): the chain wraps the action, can short-circuit
@@ -528,7 +603,6 @@ export async function invokeAction(idx, hash, fnName, req, onError, allowedOrigi
     // the action reads via actionContext(). `ranAction` distinguishes a real
     // action completion from a middleware short-circuit (the action never ran).
     const middleware = actionMiddleware(mod);
-    let ranAction = false;
     const result = await runWithActionSignal(req.signal, () =>
       runActionChain(middleware, { request: req, args, signal: req.signal }, () => { ranAction = true; return fn(...args); }));
     // Streaming result (#489): a COMPLETED action returning a ReadableStream /
@@ -542,6 +616,8 @@ export async function invokeAction(idx, hash, fnName, req, onError, allowedOrigi
         const inv = resolveTags(actionConfigFn(mod, 'invalidates'), args);
         if (inv.length) { await revalidateTags(inv); headers['x-webjs-invalidate'] = inv.join(','); }
       }
+      const refresh = refreshHeaderValue();
+      if (refresh) headers['x-webjs-refresh'] = refresh;
       return streamActionResponse(result, { signal: req.signal, onError, headers, dev: idx.dev });
     }
     if (method === 'GET') {
@@ -560,8 +636,29 @@ export async function invokeAction(idx, hash, fnName, req, onError, allowedOrigi
         headers['x-webjs-invalidate'] = inv.join(',');
       }
     }
+    // revalidatePath() during the action (Next parity): the browser refreshes
+    // those paths, and the page on screen in place when it is one of them.
+    const refresh = refreshHeaderValue();
+    if (refresh) headers['x-webjs-refresh'] = refresh;
     return rpcResponse(result ?? null, { headers });
   } catch (e) {
+    // redirect() / permanentRedirect() in an action called over RPC (Next.js
+    // parity): not an error. The response tells the generated stub where to
+    // go (`x-webjs-redirect: <url>;<push|replace>`, push by default as in a
+    // Next server action), and the client router navigates there. A mutation
+    // that ran still evicts its `invalidates` tags and reports revalidatePath.
+    if (isRedirect(e)) {
+      const r = /** @type {any} */ (e);
+      /** @type {Record<string, string>} */
+      const headers = { 'x-webjs-redirect': `${headerSafeLocation(r.url)};${r.redirectType === 'replace' ? 'replace' : 'push'}` };
+      if (ranAction && method !== 'GET') {
+        const inv = resolveTags(actionConfigFn(mod, 'invalidates'), args);
+        if (inv.length) { await revalidateTags(inv); headers['x-webjs-invalidate'] = inv.join(','); }
+      }
+      const refresh = refreshHeaderValue();
+      if (refresh) headers['x-webjs-refresh'] = refresh;
+      return rpcResponse(null, { headers: { ...headers, 'cache-control': 'no-store' } });
+    }
     if (typeof onError === 'function') onError(e);
     return actionErrorResponse(e, idx.dev);
   }

package/src/api.js

@@ -1,14 +1,30 @@
+import { isRedirect, isNotFound, isForbidden, isUnauthorized } from '@webjsdev/core';
+import { headerSafeLocation } from './redirect-location.js';
 import { makeThenable } from './thenable-params.js';
 import { devImport } from './dev-import.js';
+import { decorateRequest } from './middleware-load.js';
+
+/** Every method a route module may export (Next's HTTP_METHODS). */
+const HTTP_METHODS = ['GET', 'HEAD', 'OPTIONS', 'POST', 'PUT', 'DELETE', 'PATCH'];
 
 /**
  * Dispatch an incoming request to a matched API route.
- * API modules export methods as named async functions: GET, POST, PUT, PATCH, DELETE.
+ * API modules export methods as named async functions: GET, HEAD, OPTIONS,
+ * POST, PUT, PATCH, DELETE.
  *
  * Handlers receive a standard `Request` and return a standard `Response`.
  *
+ * Next.js parity:
+ *   - HEAD and OPTIONS are implemented automatically when the module does not
+ *     export them (a port of Next's `autoImplementMethods`): HEAD runs GET and
+ *     drops the body; OPTIONS answers 204 with a sorted `Allow`.
+ *   - `redirect()` thrown from a handler answers 307 (308 from
+ *     `permanentRedirect()`; an explicit status wins), and `notFound()` /
+ *     `forbidden()` / `unauthorized()` answer 404 / 403 / 401 with no body.
+ *     They are answered HERE, so no caller ever sees them as errors.
+ *
  * @param {import('./router.js').ApiRoute} route
- * @param {Record<string,string>} params
+ * @param {Record<string, string | string[]>} params
  * @param {Request} webRequest
  * @param {boolean} dev
  * @returns {Promise<Response>}
@@ -16,11 +32,20 @@ import { devImport } from './dev-import.js';
 export async function handleApi(route, params, webRequest, dev) {
   const mod = await devImport(route.file, dev);
   const method = webRequest.method.toUpperCase();
-  const handler = mod[method];
+  const implemented = HTTP_METHODS.filter((m) => typeof mod[m] === 'function');
+  let handler = typeof mod[method] === 'function' ? mod[method] : null;
+  let headOnly = false;
+  if (!handler && method === 'HEAD' && typeof mod.GET === 'function') {
+    handler = mod.GET;
+    headOnly = true;
+  }
+  if (!handler && method === 'OPTIONS') {
+    return new Response(null, { status: 204, headers: { allow: allowHeader(implemented) } });
+  }
   if (!handler) {
     return new Response(`Method ${method} not allowed`, {
       status: 405,
-      headers: { allow: allowedMethods(mod).join(', ') },
+      headers: { allow: allowHeader(implemented) },
     });
   }
   // Route-handler params are awaitable AND sync-readable (#848, Next parity:
@@ -28,6 +53,9 @@ export async function handleApi(route, params, webRequest, dev) {
   // spreads / JSON-stringifies params is unaffected.
   const thenableParams = makeThenable(params);
   /** @type any */ (webRequest).params = thenableParams;
+  // A Next.js route handler receives a NextRequest, so `request.cookies.get()`
+  // is how agents read a cookie there; it is the request's cookies() store.
+  decorateRequest(webRequest, dev);
   let result;
   try {
     result = await handler(webRequest, { params: thenableParams });
@@ -42,14 +70,43 @@ export async function handleApi(route, params, webRequest, dev) {
         headers: { 'content-type': 'text/plain; charset=utf-8' },
       });
     }
+    const control = controlFlowResponse(e);
+    if (control) return control;
     throw e;
   }
-  if (result instanceof Response) return result;
-  // Convenience: allow returning plain objects as JSON.
-  return Response.json(result);
+  const res = result instanceof Response ? result : Response.json(result);
+  if (!headOnly) return res;
+  // A synthesized HEAD answers GET's status and headers with no body. GET's own
+  // body is never read, so it is cancelled: a streamed one (SSE, a DB cursor)
+  // would otherwise keep producing for no reader until it is collected.
+  if (res.body && !res.bodyUsed) res.body.cancel().catch(() => {});
+  return new Response(null, { status: res.status, statusText: res.statusText, headers: res.headers });
 }
 
-/** @param {Record<string,unknown>} mod */
-function allowedMethods(mod) {
-  return ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].filter((m) => typeof mod[m] === 'function');
+/**
+ * The response Next.js gives a control-flow throw inside a route handler, or
+ * null when `e` is a real error.
+ * @param {unknown} e
+ * @returns {Response | null}
+ */
+export function controlFlowResponse(e) {
+  if (isRedirect(e)) {
+    const r = /** @type any */ (e);
+    return new Response(null, { status: r.status || 307, headers: { location: headerSafeLocation(r.url) } });
+  }
+  if (isNotFound(e)) return new Response(null, { status: 404 });
+  if (isForbidden(e)) return new Response(null, { status: 403 });
+  if (isUnauthorized(e)) return new Response(null, { status: 401 });
+  return null;
+}
+
+/**
+ * The `Allow` header Next sends: the implemented methods plus OPTIONS (always
+ * answered) and HEAD (when GET exists), sorted.
+ * @param {string[]} implemented
+ */
+function allowHeader(implemented) {
+  const allow = new Set(['OPTIONS', ...implemented]);
+  if (allow.has('GET')) allow.add('HEAD');
+  return [...allow].sort().join(', ');
 }

package/src/app-layout.js

@@ -0,0 +1,133 @@
+/**
+ * App layout validation: file arrangements that can never serve correctly,
+ * found from the route table alone (no code is loaded).
+ *
+ * Next.js refuses these at build time. WebJs has no build, so the same
+ * refusal happens in three places, all fed by `validateAppLayout`:
+ *   - `webjs check` reports each problem as a violation (its `rule` id);
+ *   - production refuses to boot (`createRequestHandler` throws);
+ *   - dev answers every app request with a 500 naming the problem and pushes
+ *     it to the error overlay, until an edit fixes it.
+ *
+ * @module app-layout
+ */
+import { relative, sep } from 'node:path';
+
+/**
+ * @typedef {{ rule: string, file: string, message: string, fix: string }} LayoutProblem
+ */
+
+/**
+ * The thrown form of one or more layout problems. `code` lets the request
+ * handler tell it apart from an ordinary analysis failure.
+ */
+export class AppLayoutError extends Error {
+  /** @param {LayoutProblem[]} problems */
+  constructor(problems) {
+    super(problems.map((p) => `[${p.rule}] ${p.file}: ${p.message} Fix: ${p.fix}`).join('\n'));
+    this.name = 'AppLayoutError';
+    this.code = 'WEBJS_APP_LAYOUT';
+    this.problems = problems;
+  }
+}
+
+/**
+ * @param {string} appDir
+ * @param {string} file
+ */
+function rel(appDir, file) {
+  return relative(appDir, file).split(sep).join('/');
+}
+
+/**
+ * Every layout problem in the app, in a stable order.
+ *
+ * @param {string} appDir
+ * @param {import('./router.js').RouteTable} table
+ * @param {Set<string>} [publicFiles] url paths of the files under `public/`
+ * @returns {LayoutProblem[]}
+ */
+export function validateAppLayout(appDir, table, publicFiles) {
+  /** @type {LayoutProblem[]} */
+  const problems = [];
+
+  // A public file at the url of a static page, a route handler or a metadata
+  // route: one would silently shadow the other (public files are served
+  // before routes, as in Next, which refuses the same conflict). A DYNAMIC
+  // route is not a conflict: the public file simply wins for its one url.
+  if (publicFiles && publicFiles.size) {
+    const staticOwner = new Map();
+    for (const r of [...(table.pages || []), ...(table.apis || [])]) {
+      if (r.paramNames && r.paramNames.length) continue;
+      const dir = /** @type {any} */ (r).routeDir;
+      const url = '/' + (dir === '.' ? '' : dir.split('/').filter((s) => !(s.startsWith('(') && s.endsWith(')'))).join('/'));
+      staticOwner.set(url, r.file);
+    }
+    for (const m of table.metadataRoutes || []) staticOwner.set(m.urlPath, m.file);
+    for (const url of publicFiles) {
+      const owner = staticOwner.get(url);
+      if (!owner) continue;
+      problems.push({
+        rule: 'no-public-route-conflict',
+        file: `public${url}`,
+        message: `public${url} is served at ${url}, the same url as ${rel(appDir, owner)}, so one of them can never be reached.`,
+        fix: `Rename or move one of them: public files are served at the url root (public/logo.png is /logo.png), before every route.`,
+      });
+    }
+  }
+
+  // A page and a route handler answering the same URL. Next refuses this
+  // ("Conflicting route and page"); WebJs used to let the route handler win
+  // silently, so the page never rendered.
+  for (const c of table.conflicts || []) {
+    problems.push({
+      rule: 'no-page-route-conflict',
+      file: rel(appDir, c.route),
+      message: `${rel(appDir, c.page)} and ${rel(appDir, c.route)} both answer ${c.url}, so the page can never render.`,
+      fix: 'Keep one: move the route handler to its own folder (for example app/api/...), or delete the page.',
+    });
+  }
+  // A routing file written as `.tsx` / `.jsx`: JSX needs a build step, so the
+  // router never sees it and the route silently does not exist.
+  for (const file of table.ignoredJsx || []) {
+    const r = rel(appDir, file);
+    const ts = r.replace(/\.(t|j)sx$/, (_, t) => `.${t}s`);
+    problems.push({
+      rule: 'no-jsx-route-file',
+      file: r,
+      message: `${r} is a routing file written as JSX, which WebJs never loads (there is no build step), so this route does not exist.`,
+      fix: `Rename it to ${ts} and return an html\`...\` template from @webjsdev/core instead of JSX (interactive parts become a WebComponent).`,
+    });
+  }
+  return problems;
+}
+
+/** The fix every CSS-import refusal names. */
+export const CSS_IMPORT_FIX = 'Load a stylesheet with <link rel="stylesheet" href="..."> in the root layout (Tailwind\'s output included), or scope CSS to a component with `static styles = css`...`` and `static shadow = true`.';
+
+/**
+ * Every `import './x.css'` in the app's module graph, as layout problems. A
+ * CSS import is a bundler feature: Node refuses the extension, Bun silently
+ * turns it into a no-op on the server, and the browser refuses a stylesheet as
+ * a module script, so the importing module never loads there.
+ * @param {Map<string, Set<string>>} graph
+ * @param {(abs: string) => string} rel
+ * @returns {LayoutProblem[]}
+ */
+export function cssImportProblems(graph, rel) {
+  /** @type {LayoutProblem[]} */
+  const out = [];
+  for (const [file, deps] of graph) {
+    if (/[\\/]node_modules[\\/]/.test(file)) continue;
+    for (const dep of deps) {
+      if (!/\.css$/i.test(dep)) continue;
+      out.push({
+        rule: 'no-css-import',
+        file: rel(file),
+        message: `Imports ${rel(dep)}, a stylesheet. WebJs has no bundler: the import fails on Node, is silently dropped on Bun, and stops the module from loading in the browser.`,
+        fix: CSS_IMPORT_FIX,
+      });
+    }
+  }
+  return out;
+}