@ultimat3/http 10.0.0 → 11.0.0

package/CLAUDE.md

@@ -84,12 +84,28 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   TLS-terminating ingress would be refused. **`mode: 'token'` is deliberately NOT shipped** — a
   double-submit token needs a cookie issuer and a form-field helper at tier 4/5, and a half-built
   token mode is worse than an honest `'origin' | 'off'`.
+- **An unclassified 5xx tells the CALLER nothing off the throwable** (`As of 2026-08-23`).
+  `error-page.ts` has always shown a browser the status, the code and the request id and said so in
+  its header; `toProblem` rendered `facts.cause`, which for a 500 nobody classified falls through to
+  the exception's own `message` — a driver's DSN, the row Postgres rejected, an absolute path. One
+  condition, two audiences, and they disagreed. The discriminator is a code nobody declared a status
+  for, plus `X_INTERNAL` itself: core's `toError()` wraps a caught value into an `InternalError`
+  whose cause is `renderCauseValue(value)`, so the framework's own word for "unclassified" is where
+  the leak arrives. `toProblem(error, { dev })` is the seam and `dev` DEFAULTS TO FALSE: the
+  `error-map` stage is the one call site that can see the config, and every degraded `problem()` in
+  the tail must stay opaque. The real text is not lost — it is the log field and the error report,
+  both keyed by the request id the caller was given.
 - **A rejected value is a log FIELD, never part of the message.** `logger.emit()` redacts `bound`,
   `contextFields` and `fields` — and never `msg` — so `logger.error(\`${code}: ${cause}\`)` in the
   `error-map` stage wrote a rejected password verbatim into the log store, at 4xx, which is logged
   and not reported and therefore kept for the full retention. The message is the CODE alone. The
   other half is `@ultimat3/schema`'s `describeValue` (shape, never content) and it is the
   load-bearing one; this half is what makes the value redactable at all.
+- **A repeated field is a LIST, in all three parsers.** `collectFields` in `request.ts` is the one
+  collector for the query, `application/x-www-form-urlencoded` and `multipart/form-data`. The last
+  two were `Object.fromEntries`, which keeps the LAST value: a checkbox group posting `tags` three
+  times reached the body schema as one string, while the query parser three functions up had built
+  an array for the same shape since it shipped.
 - **A rejected BODY is not a log field either — `bodyInvalid`'s `issues` may name only what the
   framework chose** (`As of 2026-08-19`). `request.ts` built `could not parse ${type}: ${String(error)}`,
   and the runtime's `SyntaxError` quotes the token it choked on: a `POST` of
@@ -120,6 +136,17 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   goes through the same capped bytes (re-parsed by `Response.formData()` off the announced
   boundary) rather than being handed to the runtime as an unbounded stream, which is what left it
   with no byte guard at all when the length was undeclared.
+- **The `cache-headers` stage is the ONE owner of the final cache answer, `As of 2026-08-23`.** It
+  used to apply the actor-aware default only when nothing had set a header — and every page route
+  in every app sets one, because `@ultimat3/render`'s `ssrHeaders` writes
+  `public, max-age=0, s-maxage=30, stale-while-revalidate=300` for any route that declares no
+  `policy`, which is exactly what `x g route --surface app` scaffolds. So the rule below was
+  unreachable for the surface it was written for. A render mode states the MODE's intent; this
+  stage decides, and `offersSharedCache` is the discriminator: a shared answer for an identified
+  request becomes `PRIVATE_CACHE`, an anonymous one gains `SHARED_CACHE_VARY`. `immutable` is left
+  alone in both directions — it asserts the body is a function of the URL, which is what a
+  content-addressed island chunk is, and demoting those would re-download every chunk on every
+  navigation for every signed-in user.
 - **The cache default reads the ACTOR, not just the route, and `vary` is added and never set.**
   `meta.auth` is only `'public' | 'required'`, so the page that greets a signed-in visitor by name
   is a `'public'` route: keying the default off the route alone put that visitor's personalised
@@ -127,6 +154,23 @@ Owned request lifecycle over `Bun.serve`. Tier 2.
   an anonymous one stays shared-cacheable and carries `vary: accept-language, cookie`. Both halves
   are required — either alone leaves the hole. `addVary` (`response.ts`) is how the `response`
   stage merges CORS's `vary: origin` into the cache stage's key instead of replacing it.
+- **A `security.csp.extend` entry is refused at `defineHttpConfig` unless it can only emit the
+  directive it names.** A directive name and a source both go into the header VERBATIM and the
+  header's own separators are `;` and ` `, so `extend: { 'x; script-src *': [] }` was not one badly
+  named directive — it was a second directive nobody declared, widening the one this package locks
+  down hardest. `X_CSP_DIRECTIVE_INVALID`, at boot, because there is no encoding for a CSP source
+  and escaping one at emission time is not a repair. `buildCsp` builds through a **`Map`** for the
+  other half of the same class: `directives[name]` was a computed read of an object literal keyed by
+  a caller-chosen name, so `extend: { toString: [...] }` spread a function off `Object.prototype`
+  and threw a bare `TypeError` at boot. `proto-index` cannot see it — `baseline()` is what produces
+  the object.
+- **`config.drainTimeoutMs` is `number | null`, and `null` is the default** (`As of 2026-08-23`).
+  `createServer` calls `configureLifecycle({ deadlineMs })` only when an app DECLARED one. It used
+  to call it unconditionally with a value `defineHttpConfig` had defaulted to 15s, so an app that
+  wrote `configureLifecycle({ deadlineMs: 600_000 })` — the edit `X_SHUTDOWN_TIMEOUT`'s own `fix:`
+  prints — had it silently reverted by the next line of boot, in every process that serves web.
+  "Nobody said" and "the app said 15 seconds" are different claims and only one of them may move a
+  process-global deadline.
 - **`cors.origins: ['*']` with `credentials: true` is refused at `defineHttpConfig`.** No browser
   accepts that pair, and `allowedOrigin` answering `null` for it meant the natural "open it up"
   edit emitted no CORS headers at all, silently, on every request — with `DEFAULT_CORS.credentials`

package/README.md

@@ -47,7 +47,10 @@ What the lifecycle refuses on the caller's behalf, `As of 2026-08`:
 | Guard | Answer |
 |---|---|
 | a body past `bodyLimitBytes` | read through the stream and abandoned the instant the running total crosses the limit — `content-length` or not, multipart included — as `X_BODY_INVALID` |
-| a request carrying an identity on an `auth: 'public'` route | `cache-control: private`, never `s-maxage`; an anonymous one is shared-cacheable and keyed `vary: accept-language, cookie` |
+| a request carrying an identity on an `auth: 'public'` route | `cache-control: private`, never `s-maxage`; an anonymous one is shared-cacheable and keyed `vary: accept-language, cookie, x-timezone`. **Whatever the handler wrote**, `As of 2026-08-23`: the `cache-headers` stage REVIEWS a declared `cache-control` instead of standing down, because `@ultimat3/render`'s `ssrHeaders` offers every page without a `policy` to a CDN for 30s. An `immutable` answer is left alone — a content-addressed body is a function of its URL |
+| a 5xx nobody declared a status for | the code, the request id and a `fix:`; never the exception's own text. `error-page.ts` locked the browser out of it, and the problem document handed the same string to an agent — a driver's DSN, the row Postgres rejected. The real text goes to the log and the error report. `dev: true` renders it in full |
+| a `security.csp.extend` key that is not a CSP token, or a source carrying `;`, `,` or a space | `X_CSP_DIRECTIVE_INVALID` at `defineHttpConfig` — `{ 'x; script-src *': [] }` is a second directive nobody declared |
+| a repeated form field | a LIST, exactly as a repeated query parameter is. One collector for query, urlencoded and multipart; `Object.fromEntries` kept the last value, so a checkbox group reached the schema as one string |
 | a cross-origin request from an origin the allow-list refuses | no `access-control-allow-origin`, but always `vary: origin`, so a shared cache never answers an allowed origin out of the refusal's slot |
 | `cors.origins: ['*']` with `credentials: true` | `X_CORS_CONFIG_INVALID` at `defineHttpConfig`, because a browser accepts that pair from nobody |
 | `?next=` carrying anything but a same-origin path | the fallback — including a value whose TAB/CR/LF a browser strips back into `//evil.test` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/http",
-  "version": "10.0.0",
+  "version": "11.0.0",
   "description": "Owned request lifecycle over Bun.serve: router, ordered pipeline, problem+json errors",
   "license": "MIT",
   "type": "module",
@@ -31,9 +31,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "10.0.0",
-    "@ultimat3/i18n": "10.0.0",
-    "@ultimat3/schema": "10.0.0",
-    "@ultimat3/time": "10.0.0"
+    "@ultimat3/core": "11.0.0",
+    "@ultimat3/i18n": "11.0.0",
+    "@ultimat3/schema": "11.0.0",
+    "@ultimat3/time": "11.0.0"
   }
 }

package/src/auth-redirect.ts

@@ -3,7 +3,7 @@
 // sign-in page. One condition, two audiences, decided here so the error stage stays one branch.
 
 import type { RequestContext } from './context';
-import { wantsOverlay } from './overlay';
+import { acceptsHtml } from './html-render';
 import type { RedirectIntent } from './response';
 
 /** The query parameter carrying where the visitor was going. One spelling, both halves. */
@@ -28,9 +28,9 @@ export function signInRedirect(input: {
 }): RedirectIntent | undefined {
   const { code, signInPath, request, ctx } = input;
   if (code !== 'X_UNAUTHENTICATED' || signInPath === null) return undefined;
-  // The same question `wantsOverlay` asks — "does this client render HTML?" — and deliberately
-  // the same answer, so a client cannot get the overlay in dev and JSON in production.
-  if (!wantsOverlay(request)) return undefined;
+  // The same question the overlay and the error page ask — "does this client render HTML?" — and
+  // deliberately the same answer, so a client cannot get a page in dev and JSON in production.
+  if (!acceptsHtml(request)) return undefined;
   // A sign-in page that declares `auth: 'required'` by mistake would otherwise redirect to
   // itself forever, and a browser reports that as a bare "too many redirects" with no code.
   if (ctx.url.pathname === signInPath) return undefined;

package/src/cache-policy.ts

@@ -7,6 +7,24 @@ import { isAnonymous } from '@ultimat3/core';
 import type { CacheHint } from './response';
 import type { Route } from './router';
 
+/** The one answer for an identified request, whoever asked. */
+export const PRIVATE_CACHE: CacheHint = { mode: 'private', maxAgeSeconds: 0 };
+
+// `public` or an `s-maxage` is an OFFER to a shared cache; `immutable` withdraws the question,
+// because it asserts the body is a function of the URL alone — which is what a content-addressed
+// island chunk or image is, and demoting those would re-download every chunk on every navigation
+// for every signed-in user.
+const OFFERS_SHARED = /(?:^|,)\s*(?:public\b|s-maxage=)/i;
+const IMMUTABLE = /(?:^|,)\s*immutable\b/i;
+
+/**
+ * Whether a `cache-control` a HANDLER wrote offers the response to a shared cache. A render mode
+ * states the MODE's intent — `ssr` offers an ungated page to a CDN for 30 seconds — and the actor
+ * is the half it cannot see, so the stage reviews the declaration rather than deferring to it.
+ */
+export const offersSharedCache = (declared: string): boolean =>
+  OFFERS_SHARED.test(declared) && !IMMUTABLE.test(declared);
+
 /**
  * Authenticated responses are never shared-cacheable; that default is not overridable.
  *
@@ -19,6 +37,6 @@ import type { Route } from './router';
  */
 export const defaultCache = (route: Route | undefined, actor: Actor): CacheHint => {
   if (route === undefined || route.meta.auth === 'required') return { mode: 'no-store' };
-  if (!isAnonymous(actor)) return { mode: 'private', maxAgeSeconds: 0 };
+  if (!isAnonymous(actor)) return PRIVATE_CACHE;
   return { mode: 'public', maxAgeSeconds: 0, sMaxAgeSeconds: 60, staleWhileRevalidateSeconds: 600 };
 };

package/src/config.ts

@@ -11,7 +11,7 @@ import {
   type TimeZoneConfig,
 } from './locale';
 import { type RateLimitConfig, resolveRateLimitConfig } from './rate-limit';
-import { DEFAULT_SECURITY, type SecurityConfig } from './security-headers';
+import { assertCspExtend, DEFAULT_SECURITY, type SecurityConfig } from './security-headers';
 
 export interface HttpConfig {
   readonly port: number;
@@ -56,8 +56,18 @@ export interface HttpConfig {
    * retries multiply the load.
    */
   readonly maxInflight: number;
-  /** How long SIGTERM waits for in-flight requests before hard-stopping. */
-  readonly drainTimeoutMs: number;
+  /**
+   * How long SIGTERM waits for in-flight requests before hard-stopping, or `null` when this app
+   * has not said and core's own deadline stands.
+   *
+   * `null` and not a 15s default, because the two are different claims and only one of them may
+   * reach `configureLifecycle`. `createServer` applied the resolved number unconditionally, so an
+   * app that had already written `configureLifecycle({ deadlineMs: 600_000 })` — the edit
+   * `X_SHUTDOWN_TIMEOUT`'s own `fix:` line prints — had it silently reverted by the next line of
+   * boot, in every process that serves web. Declaring this key IS declaring the drain budget for
+   * the whole process; leaving it out is declining to.
+   */
+  readonly drainTimeoutMs: number | null;
   readonly locale: LocaleConfig;
   readonly tz: TimeZoneConfig;
   readonly cors: CorsConfig;
@@ -123,6 +133,11 @@ export const defineHttpConfig = (input: HttpConfigInput = {}): HttpConfig => {
   // Refused here, not on the first request: "trust the header" and "know which entry of it" are
   // one declaration, and half of it is a header the caller writes.
   if (trustProxy && input.trustedProxyHops === undefined) throw trustProxyUnset();
+  const csp = { ...DEFAULT_SECURITY.csp, reportOnly: dev, ...input.security?.csp };
+  // Beside `assertCorsConfig`, and for its reason: a merged value is the only one that can be
+  // judged, and a directive name that is not a token would otherwise be a bare `TypeError` out of
+  // the first response's header build — or worse, a second directive nobody declared.
+  assertCspExtend(csp.extend);
   return {
     port: input.port ?? Number.parseInt(env('PORT') ?? '3000', 10),
     hostname: input.hostname ?? env('HOSTNAME') ?? '0.0.0.0',
@@ -138,16 +153,12 @@ export const defineHttpConfig = (input: HttpConfigInput = {}): HttpConfig => {
     // two, so a rolling restart cannot be held open by work started just before SIGTERM.
     requestTimeoutMs: input.requestTimeoutMs ?? 30_000,
     maxInflight: input.maxInflight ?? 1_000,
-    drainTimeoutMs: input.drainTimeoutMs ?? 15_000,
+    drainTimeoutMs: input.drainTimeoutMs ?? null,
     locale: { ...DEFAULT_LOCALE_CONFIG, ...input.locale },
     tz: { ...DEFAULT_TZ_CONFIG, ...input.tz },
     cors,
     csrf: { ...DEFAULT_CSRF, ...input.csrf },
-    security: {
-      ...DEFAULT_SECURITY,
-      ...input.security,
-      csp: { ...DEFAULT_SECURITY.csp, reportOnly: dev, ...input.security?.csp },
-    },
+    security: { ...DEFAULT_SECURITY, ...input.security, csp },
     rateLimit: resolveRateLimitConfig(input.rateLimit),
   };
 };

package/src/error-map.ts

@@ -38,6 +38,7 @@ export const ERROR_STATUS = {
   // Thrown while `app.config.ts` resolves, so no request is ever answered with it — the row exists
   // because a code with no status is a 500 anyway and this table is the closed one.
   X_CORS_CONFIG_INVALID: 500,
+  X_CSP_DIRECTIVE_INVALID: 500,
   // Thrown while the server is being constructed, so no request is ever answered with it either.
   // The row exists because this table is the closed one: a code missing from it is a 500 anyway,
   // and a code the framework owns must never fall through to the app's table.
@@ -424,19 +425,51 @@ export interface ProblemDocument {
   readonly requestId: string | undefined;
 }
 
+/** The title a caller gets for a failure the framework cannot name. */
+const INTERNAL_TITLE = 'unhandled server error';
+
+/**
+ * The cause a caller gets for one. An unclassified 5xx has no `cause` of its own, so `factsOf`
+ * falls through to the throwable's `message` — a driver's DSN, the row Postgres rejected, an
+ * absolute path — and `toProblem` handed it to whoever asked. `error-page.ts` locked the BROWSER
+ * out of exactly this and said so in its header; the two audiences then disagreed about one
+ * condition. The real text is not lost: the `error-map` stage logs it as a redactable FIELD and
+ * reports every 5xx to the error monitor, both keyed by the request id below.
+ */
+const INTERNAL_CAUSE =
+  'the server failed while handling this request; the details are in this process\u2019s logs and ' +
+  'error reports, under this request id';
+
+/**
+ * A 5xx nobody declared a status for — not the framework's table, not the app's
+ * `registerErrorStatus` — or one whose code is `X_INTERNAL`. That is the discriminator, and not
+ * `status >= 500` alone: a declared code has an authored cause, and blanking `X_DRAINING`'s would
+ * take away the one instruction in it.
+ *
+ * `X_INTERNAL` is in the framework's table and still belongs here, because it is the framework's
+ * own word for "nobody classified this": `factsOf` mints it for a throwable carrying no code, and
+ * core's `toError()` wraps a caught value into an `InternalError` whose cause is
+ * `renderCauseValue(value)` — the driver's message, verbatim. Nothing in an `X_INTERNAL` is
+ * actionable by the caller; the code and the request id are.
+ */
+const isUnclassifiedFailure = (code: string, status: number): boolean =>
+  status >= 500 &&
+  (code === 'X_INTERNAL' || (frameworkStatus(code) === undefined && !APP_ERROR_STATUS.has(code)));
+
 export const toProblem = (
   error: unknown,
-  meta: { instance?: string; requestId?: string } = {},
+  meta: { instance?: string; requestId?: string; dev?: boolean } = {},
 ): ProblemDocument => {
   const facts = factsOf(error);
+  const opaque = meta.dev !== true && isUnclassifiedFailure(facts.code, facts.status);
   return {
     type: problemTypeFor(facts.code),
-    title: facts.title,
+    title: opaque ? INTERNAL_TITLE : facts.title,
     status: facts.status,
-    detail: facts.cause,
+    detail: opaque ? INTERNAL_CAUSE : facts.cause,
     instance: meta.instance,
     code: facts.code,
-    cause: facts.cause,
+    cause: opaque ? INTERNAL_CAUSE : facts.cause,
     fix: facts.fix,
     docs: facts.docs,
     requestId: meta.requestId,

package/src/error-page.ts

@@ -0,0 +1,201 @@
+// The page a BROWSER gets when a request fails and this process is not in dev: Rails' `404.html`,
+// with the framework's own words. The dev overlay stays the dev answer — it prints the cause, the
+// fix and the stack, which is exactly what a visitor may never see — so this renderer shows the
+// status, the code and the request id and nothing else off the throwable.
+//
+// An app overrides it with a file per status; `ServerHooks.errorPage` is the seam that reads one,
+// because this package cannot see a disk.
+import { singleLine } from '@ultimat3/core';
+import type { InterpolationVars } from '@ultimat3/i18n';
+import { t } from '@ultimat3/i18n';
+import { escapeHtml } from './html-render';
+import { OVERLAY_STYLE } from './overlay-style';
+import { html } from './response';
+
+/**
+ * Where "Built with Ultimate" goes. Two literals and not a derivation off `ERROR_DOCS_URL`: the
+ * wiki page it points at is a different destination that merely shares a prefix today. They live
+ * here, next to their one renderer — a second surface that wants them (a CLI banner, a scaffolded
+ * footer) is what would move them to `@ultimat3/core`.
+ */
+export const ERROR_PAGE_LINKS = Object.freeze<Record<'repository' | 'homepage', string>>({
+  repository: 'https://github.com/developerz-ai/ultimate',
+  homepage: 'https://www.developerz.ai',
+});
+
+/** One key group in the framework catalog's `errors.*` namespace, which is what this page renders. */
+export type ErrorPageGroup =
+  | 'notFound'
+  | 'forbidden'
+  | 'unauthorized'
+  | 'rateLimited'
+  | 'serverError'
+  | 'unavailable'
+  | 'badRequest';
+
+/** Where the page's one link goes. A closed set, because a fourth destination is a design change. */
+export type ErrorPageAction = 'home' | 'retry' | 'signIn';
+
+export interface ErrorPageInput {
+  readonly status: number;
+  readonly code: string;
+  /**
+   * The pathname that failed, when there IS one. Supplied to the translator so an app that
+   * overrides `errors.notFound.body` can name it; the framework's own sentence deliberately does
+   * not, because the same renderer writes `404.html` into a static export, where no request
+   * exists and a reflected path would be a sentence with a hole in it.
+   */
+  readonly path?: string | undefined;
+  /** `x-request-id` for this request. Absent for a page built with no request behind it. */
+  readonly requestId?: string | undefined;
+  /** BCP-47 tag for `<html lang>`; the copy itself comes from the ambient translator. */
+  readonly locale: string;
+  /** `route.meta.policy` — the only thing a 403 page can name, and it names a rule, never a row. */
+  readonly permission?: string | undefined;
+  readonly retryAfterSeconds?: number | undefined;
+  /** `config.signInPath`, or null when the app has not declared one. */
+  readonly signInPath?: string | null;
+}
+
+export interface ErrorPageCopy {
+  readonly group: ErrorPageGroup;
+  readonly action: ErrorPageAction;
+  readonly vars: InterpolationVars;
+}
+
+/**
+ * The statuses with words of their own. A `Map` and not an object literal for `statusFor`'s
+ * reason one file over: the key is a number this package computed, but a table read by a value is
+ * a prototype member away from answering a function.
+ */
+const BY_STATUS = new Map<number, { group: ErrorPageGroup; action: ErrorPageAction }>([
+  [401, { group: 'unauthorized', action: 'signIn' }],
+  [403, { group: 'forbidden', action: 'home' }],
+  [404, { group: 'notFound', action: 'home' }],
+  [429, { group: 'rateLimited', action: 'retry' }],
+  [503, { group: 'unavailable', action: 'retry' }],
+]);
+
+/**
+ * The variables that group's sentence needs, or `undefined` when this request cannot supply one.
+ * `interpolate` renders a missing variable as `⟦permission⟧` — loud, and correct for an author,
+ * but it is a bracketed token in front of a visitor — so a group that cannot be filled degrades to
+ * the class below instead of shipping the hole.
+ */
+function varsFor(group: ErrorPageGroup, input: ErrorPageInput): InterpolationVars | undefined {
+  if (group === 'notFound') return input.path === undefined ? {} : { path: singleLine(input.path) };
+  if (group === 'serverError')
+    return input.requestId === undefined ? undefined : { traceId: singleLine(input.requestId) };
+  if (group === 'forbidden')
+    return input.permission === undefined
+      ? undefined
+      : { permission: singleLine(input.permission) };
+  if (group === 'rateLimited')
+    return input.retryAfterSeconds === undefined ? undefined : { seconds: input.retryAfterSeconds };
+  return {};
+}
+
+/** 4xx and 5xx each have one sentence that needs nothing, which is what a degrade falls to. */
+const classPlan = (status: number): { group: ErrorPageGroup; action: ErrorPageAction } =>
+  status < 500
+    ? { group: 'badRequest', action: 'home' }
+    : { group: 'serverError', action: 'retry' };
+
+/**
+ * Which words this status gets. Derived from the status alone — never from the code — because
+ * `ERROR_STATUS` already decided what a code MEANS to a client, and a second table keyed by code
+ * would be a second answer to that question.
+ */
+export function resolveErrorPageCopy(input: ErrorPageInput): ErrorPageCopy {
+  const plan = BY_STATUS.get(input.status) ?? classPlan(input.status);
+  const vars = varsFor(plan.group, input);
+  if (vars !== undefined) return { ...plan, vars };
+  const fallback = classPlan(input.status);
+  const fallbackVars = varsFor(fallback.group, input);
+  if (fallbackVars !== undefined) return { ...fallback, vars: fallbackVars };
+  // The last rung, and it is a rung rather than a `?? {}` because the ladder has to END on copy
+  // that needs nothing: one group in this table asks for no variable, and landing anywhere else
+  // ships `⟦traceId⟧` to a visitor.
+  return { group: 'badRequest', action: 'home', vars: {} };
+}
+
+const hrefFor = (copy: ErrorPageCopy, input: ErrorPageInput): string => {
+  if (copy.action === 'signIn' && input.signInPath !== null && input.signInPath !== undefined)
+    return input.signInPath;
+  // A retry has to be the page the visitor was on; with no request behind the page there is no
+  // such address, so it degrades to the one link that is always right.
+  return (copy.action === 'retry' ? input.path : undefined) ?? '/';
+};
+
+const link = (href: string, label: string): string =>
+  `<a href="${escapeHtml(href)}">${escapeHtml(label)}</a>`;
+
+/**
+ * The framework's page. One document, every status — the words are a catalog lookup and the shape
+ * never changes, so an app that wants a different shape ships its own file rather than configuring
+ * this one into something else.
+ *
+ * The key is built from the group, which is what makes `errors.*` one namespace with one reader
+ * instead of seven call sites that can each drift from the table above.
+ */
+export function renderErrorPage(input: ErrorPageInput): string {
+  const copy = resolveErrorPageCopy(input);
+  const title = t(`errors.${copy.group}.title`);
+  return `<!doctype html>
+<html lang="${escapeHtml(input.locale)}">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex">
+<title>${escapeHtml(`${String(input.status)} ${title}`)}</title>
+<style>${OVERLAY_STYLE}</style>
+</head>
+<body>
+<main>
+  <section class="card">
+    <p class="status">${escapeHtml(String(input.status))}</p>
+    <h1>${escapeHtml(title)}</h1>
+    <p class="lede">${escapeHtml(t(`errors.${copy.group}.body`, copy.vars))}</p>
+    <p>${link(hrefFor(copy, input), t(`errors.${copy.group}.action`))}</p>
+    <dl>
+      <dt>code</dt><dd>${escapeHtml(singleLine(input.code))}</dd>${
+        input.requestId === undefined
+          ? ''
+          : `
+      <dt>request</dt><dd>${escapeHtml(singleLine(input.requestId))}</dd>`
+      }
+    </dl>
+  </section>
+  <footer class="card">
+    ${link(ERROR_PAGE_LINKS.repository, t('errors.page.builtWith'))}
+    ${link(ERROR_PAGE_LINKS.homepage, 'developerz.ai')}
+  </footer>
+</main>
+</body>
+</html>`;
+}
+
+export interface ErrorPageOptions {
+  /** The app's own file for this status, if it has one. */
+  readonly override?: string | undefined;
+  /** Headers the refusal computed — `retry-after` today, and nothing else so far. */
+  readonly headers?: Readonly<Record<string, string>> | undefined;
+}
+
+/**
+ * The answer itself. `override` is the app's own file, served BYTE FOR BYTE — a framework that
+ * interpolated a `{{status}}` into it would be a second template language, and a page an app
+ * cannot predict is not an override.
+ *
+ * `no-store`, always: an error page filed by a shared cache under the URL that failed is served to
+ * the next visitor after the incident is over. `retry-after` rides along for the same reason it
+ * rides on the problem document — a 503 that does not say when to come back comes back at once.
+ */
+export const errorPageResponse = (
+  input: ErrorPageInput,
+  options: ErrorPageOptions = {},
+): Response =>
+  html(options.override ?? renderErrorPage(input), {
+    status: input.status,
+    headers: { 'cache-control': 'no-store', ...options.headers },
+  });

package/src/errors.ts

@@ -23,6 +23,7 @@ export const HTTP_OWNED_ERROR_CODES = [
   'X_NO_REQUEST',
   'X_ERROR_STATUS_INVALID',
   'X_CORS_CONFIG_INVALID',
+  'X_CSP_DIRECTIVE_INVALID',
   'X_RATE_LIMIT_NOT_SHARED',
   'X_RATE_LIMIT_BUCKET_CONFLICT',
   'X_RATE_LIMIT_BUCKET_UNBOUND',
@@ -75,6 +76,7 @@ export const HTTP_ERROR_TITLES: Readonly<Record<HttpOwnedErrorCode, string>> = {
   X_NO_REQUEST: 'the inbound request is not in scope here',
   X_ERROR_STATUS_INVALID: 'an error code cannot be mapped to that status',
   X_CORS_CONFIG_INVALID: 'the cors config can never produce a working response',
+  X_CSP_DIRECTIVE_INVALID: 'a csp extension would emit something other than the directive it names',
   X_RATE_LIMIT_NOT_SHARED: 'the rate limit is declared fleet-wide and the store is per-process',
   X_RATE_LIMIT_BUCKET_CONFLICT: 'a route and the config declare different numbers for one bucket',
   X_RATE_LIMIT_BUCKET_UNBOUND: 'the installed limiter cannot enforce a bucket a route declares',
@@ -290,6 +292,20 @@ export const corsConfigInvalid = (reason: string): HttpError =>
     fix: "in app.config.ts set http.cors.credentials: false, or replace http.cors.origins: ['*'] with the exact origins allowed to call this app",
   });
 
+/**
+ * At `defineHttpConfig`. A directive name and a source both go into the header VERBATIM, and the
+ * header's own separators are `;` and ` ` — so `extend: { 'x; script-src *': [] }` is not one
+ * badly named directive, it is a second directive nobody declared, widening the one this
+ * framework locks down hardest. Refused where it is written rather than escaped where it is
+ * emitted: there is no encoding for a CSP directive, so the only total answer is not to have one.
+ */
+export const cspDirectiveInvalid = (where: string, value: string): HttpError =>
+  new HttpError({
+    code: 'X_CSP_DIRECTIVE_INVALID',
+    cause: `${where} is not a csp token: ${JSON.stringify(value)}`,
+    fix: 'in app.config.ts write one http.security.csp.extend entry per directive, each source its own array element — a directive name is [a-z][a-z0-9-]*, and no source may contain a space, a comma or a semicolon',
+  });
+
 export const routeConflict = (path: string, detail: string): HttpError =>
   new HttpError({
     code: 'X_ROUTE_CONFLICT',

package/src/hooks.ts

@@ -37,6 +37,20 @@ export interface ServerHooks {
    * a production process never calls it; `x dev` is the only host that supplies one.
    */
   readonly devNotices?: (ctx: RequestContext) => readonly OverlayNotice[];
+  /**
+   * The app's OWN error page for a status, served byte for byte, or `undefined` to render the
+   * framework's. A seam and not a config value because the answer lives on a disk this package
+   * cannot see: `@ultimat3/cli` reads `apps/web/site/errors/<status>.html`, per request, so a file
+   * dropped into a running server takes effect without a restart — the rule `/favicon.ico`
+   * already follows for the same class of file.
+   *
+   * Consulted only on the production HTML path: a dev process answers a browser with the overlay,
+   * and an agent gets the problem document in both.
+   */
+  readonly errorPage?: (
+    status: number,
+    ctx: RequestContext,
+  ) => Promise<string | undefined> | string | undefined;
 }
 
 export type Authenticator = NonNullable<ServerHooks['authenticate']>;

package/src/html-render.ts

@@ -0,0 +1,25 @@
+// The two questions every HTML answer this package renders has to ask, in one place: is the caller
+// a browser, and how does a value become markup. Both were the dev overlay's private helpers while
+// the production error page needs the identical answers — a second accept sniff would let a client
+// get the overlay in dev and JSON in production, and a second escape set is one hole away.
+
+/**
+ * `'` is escaped even though every attribute the renderers write is double-quoted: the escape set
+ * is what the next author reads as the guarantee, and a single-quoted attribute written later
+ * would inherit a hole nothing here would have flagged.
+ */
+export const escapeHtml = (value: string): string =>
+  value
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;');
+
+/**
+ * Does this caller render HTML? One sniff, three readers — the dev overlay, the production error
+ * page and the sign-in redirect — so a browser cannot be handed a page by one of them and a
+ * problem document by the next for the same request.
+ */
+export const acceptsHtml = (request: Request): boolean =>
+  (request.headers.get('accept') ?? '').includes('text/html');

package/src/index.ts

@@ -37,6 +37,19 @@ export {
   statusFor,
   toProblem,
 } from './error-map';
+export type {
+  ErrorPageAction,
+  ErrorPageCopy,
+  ErrorPageGroup,
+  ErrorPageInput,
+  ErrorPageOptions,
+} from './error-page';
+export {
+  ERROR_PAGE_LINKS,
+  errorPageResponse,
+  renderErrorPage,
+  resolveErrorPageCopy,
+} from './error-page';
 export type { HttpErrorCode } from './errors';
 export {
   bodyInvalid,
@@ -73,6 +86,7 @@ export {
 } from './forwarded';
 export type { Authenticator, AuthzDecision, ServerHooks } from './hooks';
 export { configureAuthenticator, configuredAuthenticator, resetAuthenticator } from './hooks';
+export { acceptsHtml, escapeHtml } from './html-render';
 export type { LocaleConfig, TimeZoneConfig } from './locale';
 export { DEFAULT_LOCALE_CONFIG, DEFAULT_TZ_CONFIG, readCookie } from './locale';
 export type { Middleware } from './middleware';

package/src/overlay-style.ts

@@ -1,6 +1,8 @@
-// The dev overlay's stylesheet, split from the document that carries it so `security-headers.ts`
-// can hash it into the CSP without importing the renderer — and so the hash is computed from the
-// one copy of the text, never from a constant that drifted away from what the `<style>` holds.
+// The stylesheet of every document this package renders — the dev overlay and the production
+// error page — split from both so `security-headers.ts` can hash it into the CSP without importing
+// a renderer, and so the hash is computed from the one copy of the text rather than from a constant
+// that drifted away from what the `<style>` holds. ONE stylesheet and not two: a second inline body
+// is a second `style-src` hash, and the page that shipped without one renders unstyled.
 
 // Token definitions live here and nowhere else; every rule below uses var().
 export const OVERLAY_STYLE = `
@@ -40,4 +42,10 @@ a { color: var(--x-accent); }
    card exists to show would sit on top of their own causes. */
 .notices dl { grid-template-columns: 14rem 1fr; }
 .notices dt { overflow-wrap: anywhere; }
+/* The production error page's three rules. The status is the one number a visitor reads first, so
+   it leads at display size in the muted role — never the danger role, which the overlay's h1 owns
+   and which says "a defect" rather than "this page moved". */
+.status { font-size: 2.5rem; line-height: 1.1; margin: 0; color: var(--x-muted); }
+.lede { margin: .25rem 0 1rem; }
+footer { display: flex; flex-wrap: wrap; gap: 1rem; color: var(--x-muted); }
 `;

package/src/overlay.ts

@@ -3,20 +3,10 @@
 // surfaces. Labels here ("cause", "fix", "notices") are protocol strings from the
 // error contract, not UI copy, so they are not routed through the i18n catalog.
 import { factsOf, renderErrorLines, toProblem } from './error-map';
+import { acceptsHtml, escapeHtml } from './html-render';
 import { OVERLAY_STYLE } from './overlay-style';
 import { html } from './response';
 
-// `'` is escaped even though every attribute below is double-quoted: the escape set is what the
-// next author reads as the guarantee, and a single-quoted attribute written later would inherit a
-// hole nothing here would have flagged.
-const escapeHtml = (value: string): string =>
-  value
-    .replaceAll('&', '&')
-    .replaceAll('<', '&lt;')
-    .replaceAll('>', '&gt;')
-    .replaceAll('"', '&quot;')
-    .replaceAll("'", '&#39;');
-
 /**
  * An `href` is a SCHEME decision, not an escaping one: `javascript:alert(1)` survives every entity
  * replacement intact and becomes a link the agent debugging this page clicks. A `docs` value comes
@@ -78,6 +68,9 @@ export const renderOverlay = (error: unknown, meta: OverlayMeta = {}): string =>
   const problem = toProblem(error, {
     ...(meta.requestId === undefined ? {} : { requestId: meta.requestId }),
     ...(meta.path === undefined ? {} : { instance: meta.path }),
+    // The overlay is rendered on the dev branch and nowhere else (`stages.ts`), and its whole job
+    // is showing the developer the cause a production caller may not see.
+    dev: true,
   });
   const where = `${meta.method ?? ''} ${meta.path ?? ''}`.trim();
   return `<style>${OVERLAY_STYLE}</style>
@@ -119,6 +112,10 @@ export const overlayResponse = (error: unknown, meta: OverlayMeta = {}): Respons
     headers: { 'cache-control': 'no-store' },
   });
 
-/** Dev only, and only when the caller is a browser: agents and RPC want problem+json. */
-export const wantsOverlay = (request: Request): boolean =>
-  (request.headers.get('accept') ?? '').includes('text/html');
+/**
+ * Dev only, and only when the caller is a browser: agents and RPC want problem+json. The sniff
+ * itself is `acceptsHtml`, shared with the production error page — the two documents answer the
+ * same caller in two environments, so asking the question twice is how one of them starts
+ * disagreeing with the other.
+ */
+export const wantsOverlay = (request: Request): boolean => acceptsHtml(request);

package/src/request.ts

@@ -26,9 +26,9 @@ const contentTypeOf = (request: Request): string =>
  * `coerceQuery` decides whether to coerce a declared property — stops answering true for every
  * member of `Object.prototype`.
  */
-const parseQuery = (url: URL): QueryValues => {
-  const out: Record<string, string | string[]> = Object.create(null);
-  for (const [key, value] of url.searchParams) {
+const collectFields = <T>(entries: Iterable<[string, T]>): Record<string, T | T[]> => {
+  const out: Record<string, T | T[]> = Object.create(null);
+  for (const [key, value] of entries) {
     const existing = out[key];
     if (existing === undefined) out[key] = value;
     else if (Array.isArray(existing)) existing.push(value);
@@ -37,6 +37,8 @@ const parseQuery = (url: URL): QueryValues => {
   return out;
 };
 
+const parseQuery = (url: URL): QueryValues => collectFields(url.searchParams);
+
 export class UltimateRequest {
   readonly raw: Request;
   readonly ctx: RequestContext;
@@ -184,7 +186,10 @@ export class UltimateRequest {
         const form = await new Response(new Uint8Array(read.bytes), {
           headers: { 'content-type': this.raw.headers.get('content-type') ?? type },
         }).formData();
-        return Object.fromEntries(form);
+        // `collectFields`, never `Object.fromEntries`: a repeated name is a LIST here for the
+        // reason it is one in the query — a checkbox group posts its name once per checked box,
+        // and collapsing to the last one silently discards every other answer.
+        return collectFields(form);
       } catch (error) {
         // The parser's own message is a diagnostic, not an instruction, and it quotes the bytes
         // it choked on — so it rides in `meta`, rendered by core rather than by `String(error)`,
@@ -199,7 +204,7 @@ export class UltimateRequest {
     try {
       if (type === 'application/json' || type.endsWith('+json')) return JSON.parse(body);
       if (type === 'application/x-www-form-urlencoded') {
-        return Object.fromEntries(new URLSearchParams(body));
+        return collectFields(new URLSearchParams(body));
       }
       if (type.startsWith('text/')) return body;
     } catch (error) {

package/src/response.ts

@@ -1,5 +1,6 @@
 // Response constructors. Every response in the framework is built here so that
 // content types, charsets and cache semantics are decided once instead of per route.
+import { TIMEZONE_HEADER } from '@ultimat3/time';
 import { toProblem } from './error-map';
 
 type HeaderSource = { readonly headers?: HeadersInit | undefined } | undefined;
@@ -73,11 +74,21 @@ export interface RedirectIntent {
  */
 export const problem = (
   error: unknown,
-  meta: { instance?: string; requestId?: string; headers?: Record<string, string> } = {},
+  meta: {
+    instance?: string;
+    requestId?: string;
+    headers?: Record<string, string>;
+    /**
+     * `config.dev`. Absent means NOT dev: a degraded path that cannot see the config must not be
+     * the one that reveals an unclassified 500's text, and the stage that can see it passes it.
+     */
+    dev?: boolean;
+  } = {},
 ): Response => {
   const document = toProblem(error, {
     ...(meta.instance === undefined ? {} : { instance: meta.instance }),
     ...(meta.requestId === undefined ? {} : { requestId: meta.requestId }),
+    ...(meta.dev === undefined ? {} : { dev: meta.dev }),
   });
   return new Response(JSON.stringify(document), {
     status: document.status,
@@ -134,6 +145,16 @@ export const addVary = (response: Response, values: readonly string[]): Response
   return response;
 };
 
+/**
+ * The request dimensions a SHARED copy of a response is keyed on. `cookie` because every session
+ * in this framework travels in one; `accept-language` and the time-zone header because both are
+ * ambient inputs to a server render — they become `ctx.locale` and `ctx.tz`, which is what
+ * `@ultimat3/ui` formats every date with — so the body is a function of them and a cache that
+ * ignores one hands the next visitor the previous one's document. One list, two readers: the hint
+ * this file applies, and the `cache-headers` stage for a shared `cache-control` a handler wrote.
+ */
+export const SHARED_CACHE_VARY: readonly string[] = ['accept-language', 'cookie', TIMEZONE_HEADER];
+
 /** Mutates the response headers in place — responses are per-request, never shared. */
 export const applyCacheHeaders = (response: Response, hint: CacheHint): Response => {
   response.headers.set('cache-control', cacheControl(hint));
@@ -142,11 +163,10 @@ export const applyCacheHeaders = (response: Response, hint: CacheHint): Response
   }
   // `cookie` is not optional on the shared path. A `public` response is stored by a CDN under the
   // URL, and every session in this framework travels in a cookie — so without it the first
-  // signed-in render of a public page is what every later visitor is served.
-  return addVary(
-    response,
-    hint.vary ?? (hint.mode === 'public' ? ['accept-language', 'cookie'] : []),
-  );
+  // signed-in render of a public page is what every later visitor is served. `SHARED_CACHE_VARY`
+  // rather than a literal: the stage that reviews a handler's own `cache-control` adds the same
+  // dimensions, and two lists is one of them missing the key that mattered.
+  return addVary(response, hint.vary ?? (hint.mode === 'public' ? SHARED_CACHE_VARY : []));
 };
 
 export const withHeaders = (response: Response, headers: Record<string, string>): Response => {

package/src/security-headers.ts

@@ -3,6 +3,7 @@
 // config change. Inline style is admitted by sha256 hash, never `'unsafe-inline'`: a prerendered
 // document is a file on disk, so no per-response nonce can reach it, but its body is fixed.
 
+import { cspDirectiveInvalid } from './errors';
 import { OVERLAY_STYLE } from './overlay-style';
 
 export interface SecurityConfig {
@@ -72,12 +73,42 @@ const baseline = (config: SecurityConfig): Record<string, readonly string[]> =>
   'object-src': ["'none'"],
 });
 
+/** A CSP directive name, per the grammar. Lowercase because that is what this file emits. */
+const DIRECTIVE_NAME = /^[a-z][a-z0-9-]*$/;
+
+/**
+ * A source expression may not carry one of the header's own separators. Checked and never escaped:
+ * there is no encoding for a CSP source, so the only total answer is refusing the value.
+ */
+const SOURCE_DELIMITER = /[\s;,]/;
+
+/**
+ * Refuse an `extend` entry that would emit something other than the directive it names. Called
+ * from `defineHttpConfig`, beside `assertCorsConfig`, so the refusal lands at boot rather than on
+ * the first response — and never per request, where this runs for every header built.
+ */
+export const assertCspExtend = (extend: Readonly<Record<string, readonly string[]>>): void => {
+  for (const [name, sources] of Object.entries(extend)) {
+    if (!DIRECTIVE_NAME.test(name)) throw cspDirectiveInvalid('a csp directive name', name);
+    for (const source of sources) {
+      if (SOURCE_DELIMITER.test(source)) {
+        throw cspDirectiveInvalid(`a source of ${name}`, source);
+      }
+    }
+  }
+};
+
 export const buildCsp = (config: SecurityConfig): string => {
-  const directives = baseline(config);
+  // A `Map`, never the record: `directives[name]` was a computed read of an object LITERAL keyed
+  // by a name the caller chose, so `extend: { toString: [...] }` read a FUNCTION off
+  // `Object.prototype` and the spread beside it threw a bare `TypeError` at boot — and
+  // `directives['__proto__'] = […]` would have run the prototype setter instead of adding a
+  // directive. `proto-index` cannot see either, because `baseline()` is what produces the object.
+  const directives = new Map<string, readonly string[]>(Object.entries(baseline(config)));
   for (const [name, sources] of Object.entries(config.csp.extend)) {
-    directives[name] = [...(directives[name] ?? []), ...sources];
+    directives.set(name, [...(directives.get(name) ?? []), ...sources]);
   }
-  const parts = Object.entries(directives).map(([name, sources]) => `${name} ${sources.join(' ')}`);
+  const parts = [...directives].map(([name, sources]) => `${name} ${sources.join(' ')}`);
   if (config.csp.reportUri !== null) parts.push(`report-uri ${config.csp.reportUri}`);
   return parts.join('; ');
 };

package/src/server.ts

@@ -93,8 +93,12 @@ export const createServer = (options: ServerOptions): ServerHandle => {
         }),
   });
 
-  // The one HTTP-owned knob feeds core's deadline, so there is a single drain budget.
-  configureLifecycle({ deadlineMs: config.drainTimeoutMs });
+  // The one HTTP-owned knob feeds core's deadline, so there is a single drain budget — and only
+  // when this app DECLARED it. Unconditional, with `defineHttpConfig` defaulting the number, this
+  // line reverted `configureLifecycle({ deadlineMs: 600_000 })` — the edit `X_SHUTDOWN_TIMEOUT`'s
+  // own `fix:` prints — back to 15s on every boot that serves web, silently. "Nobody said" and
+  // "the app said 15 seconds" are different claims and `null` is what keeps them apart.
+  if (config.drainTimeoutMs !== null) configureLifecycle({ deadlineMs: config.drainTimeoutMs });
 
   let server: BunServer | undefined;
   let unregister: (() => void) | undefined;

package/src/stages.ts

@@ -14,12 +14,13 @@ import {
 import { resolveLocale } from '@ultimat3/i18n';
 import { resolveTimeZone } from '@ultimat3/time';
 import { signInRedirect } from './auth-redirect';
-import { defaultCache } from './cache-policy';
+import { defaultCache, offersSharedCache, PRIVATE_CACHE } from './cache-policy';
 import { type HttpConfig, stripBasePath } from './config';
 import { actorView, elapsedMs, type RequestContext } from './context';
 import { corsHeaders, preflight } from './cors';
 import { checkCsrf, selfOrigin } from './csrf';
 import { factsOf, retryAfterOf } from './error-map';
+import { errorPageResponse } from './error-page';
 import {
   bodyInvalid,
   csrfBlocked,
@@ -32,13 +33,14 @@ import {
   unauthenticated,
 } from './errors';
 import type { ServerHooks } from './hooks';
+import { acceptsHtml } from './html-render';
 import { readCookie } from './locale';
 import { compose, type Middleware } from './middleware';
-import { overlayResponse, wantsOverlay } from './overlay';
+import { overlayResponse } from './overlay';
 import { type RateLimiter, rateLimitKey } from './rate-limit';
 import { rateLimited } from './rate-limit-errors';
 import type { UltimateRequest } from './request';
-import { addVary, applyCacheHeaders, problem, redirect } from './response';
+import { addVary, applyCacheHeaders, problem, redirect, SHARED_CACHE_VARY } from './response';
 import { matchRoute, type Route, type RouteHandler, type RouteTable } from './router';
 import { securityHeaders } from './security-headers';
 import { validate } from './validate';
@@ -288,16 +290,30 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
     'cache-headers': (_request, ctx) => {
       const response = ctx.response;
       if (response === undefined) return undefined;
-      if (!response.headers.has('cache-control')) {
+      const declared = response.headers.get('cache-control');
+      if (declared === null) {
         applyCacheHeaders(
           response,
           ctx.cache ?? ctx.route?.meta.cache ?? defaultCache(ctx.route, ctx.actor),
         );
+        return undefined;
       }
+      // A declaration is the MODE's intent, never the last word: `@ultimat3/render`'s `ssrHeaders`
+      // offers any route without a `policy` to a CDN for 30 seconds, and `meta.auth` is
+      // `'public' | 'required'` — so the page that greets a signed-in visitor by name is a
+      // `'public'` route whose own header says `s-maxage`. This stage is the one owner of the
+      // final answer, which is why it REVIEWS what the handler wrote instead of standing down;
+      // the rule beside it was otherwise unreachable for every page route in every app.
+      if (!offersSharedCache(declared)) return undefined;
+      if (!isAnonymous(ctx.actor)) {
+        applyCacheHeaders(response, PRIVATE_CACHE);
+        return undefined;
+      }
+      addVary(response, SHARED_CACHE_VARY);
       return undefined;
     },
 
-    'error-map': (request, ctx) => {
+    'error-map': async (request, ctx) => {
       const error = ctx.error;
       const facts = factsOf(error);
       // This package's ONE error-reporting call site, and it is the framework's own — `onError`
@@ -336,19 +352,6 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
         ctx,
       });
       if (toSignIn !== undefined) return redirect(toSignIn.location, toSignIn.status);
-      if (config.dev && wantsOverlay(request.raw)) {
-        // Asked for inside the branch, never above it: the overlay is the only surface a notice
-        // has, so a production process — or an agent that asked for json — must not pay a
-        // diagnostic's per-request cost to produce findings nothing will render.
-        const notices = hooks.devNotices?.(ctx) ?? [];
-        return overlayResponse(error, {
-          requestId: ctx.requestId,
-          method: ctx.method,
-          path: ctx.url.pathname,
-          buildId: config.buildId,
-          ...(notices.length === 0 ? {} : { notices }),
-        });
-      }
       // The limiter's own decision first — it is the live one and it knows this request's bucket —
       // then whatever the THROWABLE computed. Only the first half existed, so every other refusal
       // that had a delay to give told the caller to come back without saying when:
@@ -365,10 +368,50 @@ export const stageRunners = (input: StageRunnersInput): Record<StageName, StageR
           : undefined;
       const seconds = decided ?? retryAfterOf(error);
       const retryAfter = seconds === undefined ? {} : { 'retry-after': String(seconds) };
+      // One sniff, two documents: a browser is never handed a problem document, and an agent is
+      // never handed a page. Which of the two a browser gets is the ENVIRONMENT — the overlay
+      // prints the cause, the fix and the stack, which is what a visitor may never see.
+      if (acceptsHtml(request.raw)) {
+        if (config.dev) {
+          // Asked for inside the branch, never above it: the overlay is the only surface a notice
+          // has, so a production process — or an agent that asked for json — must not pay a
+          // diagnostic's per-request cost to produce findings nothing will render.
+          const notices = hooks.devNotices?.(ctx) ?? [];
+          return overlayResponse(error, {
+            requestId: ctx.requestId,
+            method: ctx.method,
+            path: ctx.url.pathname,
+            buildId: config.buildId,
+            ...(notices.length === 0 ? {} : { notices }),
+          });
+        }
+        return errorPageResponse(
+          {
+            status: facts.status,
+            code: facts.code,
+            path: ctx.url.pathname,
+            requestId: ctx.requestId,
+            locale: ctx.locale,
+            // The rule the 403 page may name, and the one the `authz` stage was evaluating —
+            // never a row, never the actor. `forbidden`'s own `fix:` already cites this field.
+            ...(ctx.route?.meta.policy === undefined ? {} : { permission: ctx.route.meta.policy }),
+            ...(seconds === undefined ? {} : { retryAfterSeconds: seconds }),
+            signInPath: config.signInPath,
+          },
+          // The app's own file, read per request by whoever mounted the hook. A throw here is
+          // caught by `recoverWith` and degrades to the problem document, which is the answer a
+          // page whose renderer failed can still give.
+          { override: await hooks.errorPage?.(facts.status, ctx), headers: retryAfter },
+        );
+      }
       return problem(error, {
         instance: ctx.url.pathname,
         requestId: ctx.requestId,
         headers: retryAfter,
+        // The one call site that can see the config, so it is the one that may reveal an
+        // unclassified 500's own text. Every other `problem()` in this package is a degraded
+        // path and stays opaque by default.
+        dev: config.dev,
       });
     },