@nifrajs/web 3.3.0 → 3.5.0

package/src/internal/web-app.ts

@@ -3,56 +3,16 @@ import {
   type BackendMountHandler,
   NIFRA_BACKEND_MOUNT,
 } from "@nifrajs/core/mount"
-import { type ServerOptions, server, type UrlParts, urlPartsOf } from "@nifrajs/core/server"
-import {
-  type BoundaryRequestCtx,
-  type BoundaryStates,
-  boundaryDescriptors,
-  resolveStaticBoundaries,
-  startDynamicBoundaries,
-} from "../boundary.ts"
-import { defer, ndjsonStream, prepareDeferred } from "../deferred.ts"
-import { isDraftEnabled } from "../draft.ts"
+import type { Platform } from "@nifrajs/core/server"
+import { type ServerOptions, server } from "@nifrajs/core/server"
+import type { CssLoadingMode } from "../css-contract.ts"
 import { generateLlmsTxt } from "../llms-txt.ts"
-import type {
-  LayoutEntry,
-  LoaderContext,
-  Manifest,
-  Meta,
-  MetaArgs,
-  RouteEntry,
-  RouteModule,
-} from "../manifest.ts"
+import type { Manifest } from "../manifest.ts"
 import type { RenderAdapter } from "../render-seam.ts"
-import {
-  createMatcher,
-  DATA_HEADER,
-  NAV_FROM_HEADER,
-  RETAIN_HEADER,
-  REVALIDATE_HEADER,
-  STATUS_HEADER,
-} from "../router.ts"
-import { searchOf, searchOfChain } from "../search.ts"
-import { mergeHeads, resolveMeta } from "./head-merge.ts"
-import {
-  actionResponse,
-  EMPTY_RETAIN,
-  type HeadersLike,
-  isControlFlow,
-  isStatusSignal,
-  type LoadedLayoutModules,
-  layoutErrorId,
-  type RenderAssemblyCache,
-  type RenderedPage,
-  type RevalidateResult,
-  renderPageResult,
-  STATUS_SIGNAL,
-  STATUS_TEXT,
-  type StatusSignal,
-  scopeParams,
-  tagLayoutError,
-  withDuplicateInstanceHint,
-} from "./render-document.ts"
+import { createPageRequestExecutor, type NonceResolver } from "./page-execution.ts"
+import { urlPartsFor } from "./request-url.ts"
+
+export type { NonceResolver } from "./page-execution.ts"
 export interface CreateWebAppOptions<Env = unknown> {
   readonly adapter: RenderAdapter
   readonly manifest: Manifest
@@ -60,6 +20,14 @@ export interface CreateWebAppOptions<Env = unknown> {
   readonly clientEntry: string
   /** Default document title for all pages. */
   readonly title?: string
+  /**
+   * Resolve a fresh CSP nonce for each document request. The value is applied to every
+   * framework-owned executable script; return `undefined` to keep the default nonce-free output.
+   * Nonce-bearing documents are marked `private, no-store` so the request-specific value is not
+   * replayed by browser, CDN, or ISR caches. The resolver does not declare a CSP header because the
+   * policy's allowed sources are app-specific.
+   */
+  readonly nonce?: NonceResolver<Env>
   /**
    * Options for the underlying `server()` - `requestTimeoutMs`, `admission`, `gracefulSignals`, and
    * the rest of {@link ServerOptions}.
@@ -154,7 +122,9 @@ export interface CreateWebAppOptions<Env = unknown> {
    */
   readonly mounts?: ReadonlyArray<{
     readonly path: string
-    readonly app: { fetch(request: Request): Response | Promise<Response> }
+    readonly app: {
+      fetch(request: Request, platform?: Platform<Env>): Response | Promise<Response>
+    }
     readonly stripPrefix?: boolean
   }>
   /** Secret for **draft / preview mode** (see `enableDraft`). When set, a request carrying a valid
@@ -174,6 +144,13 @@ export interface CreateWebAppOptions<Env = unknown> {
    * of the aggregate `styles`, so a page ships only the CSS it uses. An empty array ⇒ no `<link>` (the
    * page imports no CSS). Routes absent here fall back to `styles`. Omit ⇒ always use `styles`. */
   readonly routeStyles?: Readonly<Record<string, readonly string[]>>
+  /**
+   * Activation policy for framework-owned stylesheet links (default `"blocking"`). `"deferred"`
+   * emits `media="print"` links; the generated client waits for them and switches them to `all` before
+   * mounting. Pair with an aggregate Vite stylesheet (`cssCodeSplit: false`) to prevent lazy-prefetch
+   * CSS insertion. Non-hydrated pages always keep their stylesheet links blocking.
+   */
+  readonly cssLoading?: CssLoadingMode
   /** SSG: the prerendered-path set (e.g. `enumerateStaticRoutes(routes).paths` or the build's
    * `prerendered.json`). Injected as `window.__NIFRA_PRERENDERED__` on every page so a client soft-nav
    * into a prerendered route fetches its static `_data.json` instead of hitting the worker. */
@@ -208,11 +185,11 @@ export interface CreateWebAppOptions<Env = unknown> {
 }
 
 /** The handler context fields createWebApp uses - a structural subset of nifra's `Context`. */
-interface RouteContext {
+interface RouteContext<Env = unknown> {
   readonly params: Record<string, string>
   readonly req: Request
   /** Platform bindings (Workers env), forwarded to each route's loader/action as `args.env`. */
-  readonly env: unknown
+  readonly env: Env
 }
 
 /**
@@ -240,23 +217,20 @@ function stripMountPrefix(request: Request, prefix: string): Request {
  * Resolve the explicit symbol-keyed backend mount interface. The symbol seam forwards platform
  * context without making web depend on client.
  */
-function backendMountOf(api: unknown): BackendMountHandler | undefined {
+function backendMountOf<Env>(api: unknown): BackendMountHandler<Env> | undefined {
   if ((typeof api !== "object" && typeof api !== "function") || api === null) return undefined
-  const explicit = (api as Partial<BackendMount>)[NIFRA_BACKEND_MOUNT]
+  const explicit = (api as Partial<BackendMount<Env>>)[NIFRA_BACKEND_MOUNT]
   if (typeof explicit !== "function") return undefined
   return (request, platform) => explicit.call(api, request, platform)
 }
 
-// `createWebApp` reaches the same Request object through the mount hook and the page route. Cache the
-// allocation-light core split once so API mounting, path hydration, search parsing, and SSG fallback
-// checks do not each rescan the absolute URL. WeakMap keeps this bounded to requests that are alive.
-const REQUEST_URL_PARTS = new WeakMap<Request, UrlParts>()
-const urlPartsFor = (request: Request): UrlParts => {
-  const cached = REQUEST_URL_PARTS.get(request)
-  if (cached !== undefined) return cached
-  const parts = urlPartsOf(request.url)
-  REQUEST_URL_PARTS.set(request, parts)
-  return parts
+function requestPathOf(request: Request): string {
+  try {
+    const parts = urlPartsFor(request)
+    return parts.pathname + parts.search
+  } catch {
+    return "/"
+  }
 }
 
 /**
@@ -277,26 +251,6 @@ export function createWebApp<Env = unknown>(
   options: CreateWebAppOptions<Env>,
 ): ReturnType<typeof server<Env>> {
   const { adapter, manifest, clientEntry, title, api } = options
-  const titleOption = title === undefined ? {} : { title }
-  // Draft/preview: when a `draftSecret` is configured, each request's signed `__nifra_draft` cookie is
-  // verified once and surfaced to loaders/actions as `ctx.draft`. No secret ⇒ always `false` (sync, free).
-  const draftFlag = (req: Request): Promise<boolean> =>
-    options.draftSecret === undefined
-      ? Promise.resolve(false)
-      : isDraftEnabled(req, options.draftSecret)
-  // Per-route preload chunks (spread into renderPage; omitted when unmapped, for exactOptionalPropertyTypes).
-  const preloadOf = (id: string): { preload?: readonly string[] } => {
-    const chunks = options.routePreload?.[id]
-    return chunks ? { preload: chunks } : {}
-  }
-  // The matched route's stylesheet links (spread into renderPage). Per-route when the build mapped it
-  // (`routeStyles[id]` - only the chain's CSS; an empty array ⇒ no `<link>`), else the aggregate
-  // `styles`. Omitted entirely when CSS-free (for exactOptionalPropertyTypes).
-  const stylesOf = (id: string): { styles?: readonly string[] } => {
-    const perRoute = options.routeStyles?.[id]
-    if (perRoute !== undefined) return { styles: perRoute }
-    return options.styles && options.styles.length > 0 ? { styles: options.styles } : {}
-  }
   // Seed the context with the declared `Env` so `app.fetch(req, { env })` / `toFetchHandler(app)` type
   // the platform bindings (see the `createWebApp` doc). The runtime `env` still arrives per-request via
   // `app.fetch(req, { env })`; this is a compile-time-only seed (`server<Env>()` casts, doesn't store).
@@ -315,7 +269,7 @@ export function createWebApp<Env = unknown>(
   // is registered ONLY when both hold, so a pages-only app keeps core's synchronous no-hook fast path.
   const apiPrefix = options.apiPrefix ?? "/api"
   const apiStrip = options.apiStrip === true
-  const mountedApi = backendMountOf(api)
+  const mountedApi = backendMountOf<Env>(api)
   // Longest path first, so a more specific mount (`/api/auth`) is tried before a broader one (`/api`)
   // regardless of the order they were declared in.
   const mounts = [...(options.mounts ?? [])].sort((a, b) => b.path.length - a.path.length)
@@ -329,7 +283,10 @@ export function createWebApp<Env = unknown>(
       // auth handler mounted at `/api/auth` must not be swallowed by the backend mounted at `/api`.
       for (const mount of mounts) {
         if (!underPrefix(pathname, mount.path)) continue
-        return mount.app.fetch(mount.stripPrefix === true ? stripMountPrefix(req, mount.path) : req)
+        return mount.app.fetch(
+          mount.stripPrefix === true ? stripMountPrefix(req, mount.path) : req,
+          platform,
+        )
       }
       // Exactly the prefix (`/api`) or a sub-path (`/api/…`) - NOT a sibling like `/apixyz` that merely
       // shares the prefix as a string head. Dispatch the original `req` (body intact) to the backend.
@@ -339,758 +296,32 @@ export function createWebApp<Env = unknown>(
       return undefined // not an API path → continue to page routing
     })
   }
-  // SSG `fallback: "404"`: the set of concrete paths that actually exist for those routes. An unlisted
-  // path under a `"404"` route is rejected (it isn't a static file, and the route declared it shouldn't
-  // SSR on demand). O(1) membership via a Set.
-  const prerenderedSet = new Set(options.prerenderedPaths ?? [])
-  const matchManifestRoute = createMatcher(
-    manifest.routes.map((route) => ({ routeId: route.id, pattern: route.pattern })),
-  )
-  const routeById = new Map(manifest.routes.map((route) => [route.id, route]))
-
-  // Load a route's layout modules (outermost layout → innermost), keeping each module whole so the
-  // render path can take both its `default` (the component chain) AND its `meta` (the sitewide head it
-  // contributes). Loaded lazily - the data-only and 405 branches return before any layout is needed.
-  const loadLayoutModules = async (route: RouteEntry): Promise<LoadedLayoutModules> => {
-    const modules = await Promise.all(
-      // layoutIds only reference layouts present in the manifest (buildManifest invariant).
-      route.layoutIds.map((id) => (manifest.layouts[id] as LayoutEntry).load()),
-    )
-    // A layout is not a form target, so an `action` there is a mistake with no meaning to give it.
-    // A `loader`, by contrast, now runs (see `runLayoutChain`).
-    for (let i = 0; i < modules.length; i++) {
-      if ((modules[i] as { action?: unknown }).action === undefined) continue
-      const id = route.layoutIds[i] as string
-      throw new Error(
-        `[nifra/web] "${(manifest.layouts[id] as LayoutEntry).file}" exports an \`action\`, but layouts do not run one - only route files do. Move the mutation into the route that submits to it.`,
-      )
-    }
-    return modules
-  }
-
-  /**
-   * Run a route's layout-chain loaders, honouring declared gates.
-   *
-   * Returns once every **gate** has resolved, with the non-gate loaders still in flight, so the caller
-   * can start the page loader at exactly the right moment: after anything that might reject the
-   * request, alongside anything that merely fetches.
-   *
-   * The ordering is the security-relevant part. Parallel loaders are NOT an authorization boundary -
-   * a page loader running concurrently with a guard has already queried by the time the guard says no.
-   * Remix documents that as a footgun; here it is a declaration instead. `export const gate = true`
-   * makes a layout blocking for everything beneath it, and nothing beneath a rejected gate runs.
-   *
-   * Each layout receives only the params it OWNS ({@link RouteEntry.layoutParams}), not the route's
-   * full set, so a layout at `orgs/[org]/` cannot read a param belonging to a route below it.
-   */
-  /**
-   * Layout indices a client navigation asked to keep, from {@link RETAIN_HEADER}.
-   *
-   * The CLIENT decides retainability: it knows each layout's scoped params (shipped in the bootstrap)
-   * and both the old and new match, so it can tell whether a layout's own prefix changed - without the
-   * server re-matching a path the client already matched.
-   *
-   * It is a HINT, not an instruction. The client is asking to keep data it already holds, which is
-   * harmless for data and unacceptable for a guard, so `runLayoutChain` refuses to skip a gate no
-   * matter what arrives here. Anything unparseable is ignored rather than rejected: the worst case of
-   * a bad hint is a loader that runs when it need not.
-   */
-  const retainedIndices = (header: string | null): ReadonlySet<number> => {
-    if (header === null || header === "") return EMPTY_RETAIN
-    const out = new Set<number>()
-    for (const part of header.split(",")) {
-      // Digits only. `Number("")` is 0 and `Number(" ")` is 0, so a stray comma would otherwise read
-      // as "retain index 0" and silently skip the outermost layout.
-      if (!/^\d+$/.test(part)) continue
-      out.add(Number(part))
-    }
-    return out
-  }
-
-  /**
-   * Validate a data-navigation's retain request against the manifest and its declared source path.
-   * A client may ask to retain every slot it currently has; the server only honours indices whose
-   * layout identity and owned params are unchanged. Hard document GETs never retain anything.
-   */
-  const validatedRetainedIndices = (
-    req: Request,
-    route: RouteEntry,
-    params: Readonly<Record<string, string>>,
-  ): ReadonlySet<number> => {
-    if (req.headers.get(DATA_HEADER) === null) return EMPTY_RETAIN
-    const requested = retainedIndices(req.headers.get(RETAIN_HEADER))
-    const from = req.headers.get(NAV_FROM_HEADER)
-    if (requested.size === 0 || from === null) return EMPTY_RETAIN
-    let fromPath: string
-    try {
-      const current = new URL(req.url)
-      const source = new URL(from, current)
-      if (source.origin !== current.origin) return EMPTY_RETAIN
-      fromPath = source.pathname + source.search
-    } catch {
-      return EMPTY_RETAIN
-    }
-    const previousMatch = matchManifestRoute(fromPath)
-    if (previousMatch === null) return EMPTY_RETAIN
-    const previous = routeById.get(previousMatch.routeId)
-    if (previous === undefined) return EMPTY_RETAIN
-    const valid = new Set<number>()
-    for (const index of requested) {
-      if (route.layoutIds[index] !== previous.layoutIds[index]) continue
-      const owned = route.layoutParams?.[index] ?? []
-      const previouslyOwned = previous.layoutParams?.[index] ?? []
-      if (
-        owned.length !== previouslyOwned.length ||
-        owned.some((name, i) => name !== previouslyOwned[i]) ||
-        owned.some((name) => params[name] !== previousMatch.params[name])
-      ) {
-        continue
-      }
-      valid.add(index)
-    }
-    return valid
-  }
-
-  // The validated (or raw-parsed) search a route's loader context receives; `searchOf` fails closed to
-  // the schema's defaults on hostile input, so this never throws on an attacker-picked query.
-  const loaderSearch = (searchSchema: RouteModule["searchSchema"], request: Request) =>
-    searchOf(searchSchema, urlPartsFor(request).search)
-
-  // The route's EFFECTIVE search once its layout chain is loaded: the layout schemas merged with the
-  // page's (page-wins), the same chain the client mount builds for `useSearch`. Used for the page loader's
-  // `ctx.search` and the render's `RenderProps.search`, so both agree with the client and with each other.
-  const searchChainOf = (
-    layoutMods: LoadedLayoutModules,
-    mod: RouteModule,
-    request: Request,
-  ): Record<string, unknown> =>
-    searchOfChain(
-      [...layoutMods.map((m) => m.searchSchema), mod.searchSchema],
-      urlPartsFor(request).search,
-    )
-
-  const runLayoutChain = async (
-    route: RouteEntry,
-    ctx: LoaderContext,
-    retain: ReadonlySet<number> = new Set(),
-  ): Promise<{
-    readonly modules: LoadedLayoutModules
-    readonly layoutData: readonly unknown[] | undefined
-    readonly retained: readonly number[]
-    readonly pending: Promise<unknown>
-  }> => {
-    const modules = await loadLayoutModules(route)
-    if (!modules.some((m) => m.loader !== undefined)) {
-      // Nothing to run: no array is produced, so a page-only app serializes nothing extra and its
-      // HTML is byte-identical to before this feature.
-      return { modules, layoutData: undefined, retained: [], pending: Promise.resolve() }
-    }
-    const results: unknown[] = new Array(modules.length).fill(null)
-    const retained: number[] = []
-    const pending: Array<Promise<void>> = []
-    for (let i = 0; i < modules.length; i++) {
-      const loader = modules[i]?.loader
-      if (loader === undefined) continue
-      // Unchanged scope: the client keeps what it has. A GATE is never skipped - it is a guard, and a
-      // guard that only runs when the URL prefix changed is not a guard.
-      if (retain.has(i) && modules[i]?.gate !== true) {
-        retained.push(i)
-        continue
-      }
-      const scoped: LoaderContext = {
-        ...ctx,
-        params: scopeParams(ctx.params, route.layoutParams?.[i]),
-      }
-      if (modules[i]?.gate === true) {
-        // Blocking: awaited here, so a throw propagates before anything deeper is started.
-        try {
-          results[i] = await loader(scoped)
-        } catch (err) {
-          throw tagLayoutError(err, route.layoutIds[i] as string)
-        }
-        continue
-      }
-      const layoutId = route.layoutIds[i] as string
-      const index = i
-      // The loader is invoked INSIDE the async function, not before it. `Promise.resolve(loader(x))`
-      // would let a synchronously-throwing loader escape past the rejection handler entirely - the
-      // exception happens while evaluating the argument, before any promise exists to reject.
-      pending.push(
-        (async () => {
-          try {
-            results[index] = await loader(scoped)
-          } catch (err) {
-            throw tagLayoutError(err, layoutId)
-          }
-        })(),
-      )
-    }
-    return { modules, layoutData: results, retained, pending: Promise.all(pending) }
-  }
-
-  /** Run only blocking layout gates before a route action. Non-gate loaders fetch render data and
-   * therefore run after the mutation when a native POST needs a fresh document. */
-  const runLayoutGates = async (
-    route: RouteEntry,
-    ctx: LoaderContext,
-  ): Promise<LoadedLayoutModules> => {
-    const modules = await loadLayoutModules(route)
-    for (let i = 0; i < modules.length; i++) {
-      const mod = modules[i]
-      if (mod?.gate !== true || mod.loader === undefined) continue
-      try {
-        await mod.loader({
-          ...ctx,
-          params: scopeParams(ctx.params, route.layoutParams?.[i]),
-        })
-      } catch (err) {
-        throw tagLayoutError(err, route.layoutIds[i] as string)
-      }
-    }
-    return modules
-  }
-
-  // Build a route's render chain + its merged `<head>` from the already-loaded layout modules + the
-  // page module. The chain is `[…layout components, page]`; the head merges each layout's `meta`
-  // export (outermost→innermost) with the page's (last), so a `head`/`meta` on `_layout.tsx`
-  // contributes sitewide tags. `metaArgs` (loader data + params) feed function-form `meta`s.
-  const resolveChainAndHead = (
-    layoutModules: LoadedLayoutModules,
-    page: RouteModule,
-    metaArgs: MetaArgs,
-  ): { chain: unknown[]; head: Meta } => {
-    const chain = [...layoutModules.map((m) => m.default), page.default]
-    const heads = [
-      ...layoutModules.map((m) => resolveMeta(m.meta, metaArgs)),
-      resolveMeta(page.meta, metaArgs),
-    ]
-    return { chain, head: mergeHeads(heads) }
-  }
-
-  // Dir a special-file id lives in: `_error`→"" , `a/b/_error`→"a/b" (and likewise for `_layout`).
-  const dirOfId = (id: string, suffix: string): string =>
-    id === suffix ? "" : id.slice(0, id.length - suffix.length - 1)
-
-  /**
-   * Choose the `_error` boundary for a failure, respecting where a LAYOUT loader failed.
-   *
-   * A route error uses the nearest boundary, as it always has. A layout error must not: the nearest
-   * boundary can sit BELOW the layout that threw, and rendering there would wrap the boundary in that
-   * very layout - the one whose loader just failed and whose data therefore never arrived.
-   */
-  const boundaryFor = (route: RouteEntry, err: unknown): string | undefined => {
-    const ids = route.errorIds ?? []
-    const failing = layoutErrorId(err)
-    if (failing === undefined) return ids.at(-1)
-    const layoutDir = dirOfId(failing, "_layout")
-    // Deepest boundary at or ABOVE the failing layout's directory.
-    for (let i = ids.length - 1; i >= 0; i--) {
-      const errDir = dirOfId(ids[i] as string, "_error")
-      if (errDir === "" || errDir === layoutDir || layoutDir.startsWith(`${errDir}/`)) return ids[i]
-    }
-    return undefined
-  }
-
-  // The request's origin (scheme + host + port, NO trailing slash) - the one server fact `meta()` needs
-  // for absolute `canonical`/`og:url`/`og:image` but can't otherwise see (it also runs on the client).
-  // `URL.origin` is exactly that shape; it matches the browser's `location.origin` for the same URL, so
-  // a soft-nav's `applyHead` resolves an identical `<head>` (no hydration drift). A malformed `req.url`
-  // (shouldn't happen on a real request) degrades to `""` - the documented unknown-origin default -
-  // rather than throwing during render.
-  const originOf = (req: Request): string => {
-    try {
-      return new URL(req.url).origin
-    } catch {
-      return ""
-    }
-  }
-
-  // The request's `pathname + search` - threaded into `renderPage` so an adapter's `useLocation`/
-  // `useSearchParams` render the current URL server-side and hydrate against the client's initial state
-  // (which the client entry seeds from `location.pathname + location.search`). No hash: it never reaches
-  // the server. A malformed `req.url` degrades to "/" rather than throwing during render.
-  const pathOf = (req: Request): string => {
-    try {
-      const parts = urlPartsFor(req)
-      return parts.pathname + parts.search
-    } catch {
-      return "/"
-    }
-  }
-
-  /**
-   * Render the **nearest `_error` boundary** when a route's loader throws (the agnostic, server-side
-   * half of error UI - works on every adapter, no client takeover). The boundary renders in place of
-   * the page, wrapped by the layouts **at or above** its segment (deeper layouts are dropped). It's
-   * served **non-hydrated** at status 500: a terminal page, and rendering a boundary (not the page the
-   * client maps this route to) would otherwise hydrate-mismatch. The component receives `{ name,
-   * message }` - never the stack (no internals leak into HTML).
-   */
-  const renderError = async (
-    route: RouteEntry,
-    errorId: string,
-    err: unknown,
-  ): Promise<Response | RenderedPage> => {
-    const errDir = dirOfId(errorId, "_error")
-    const keptLayoutIds = route.layoutIds.filter((id) => {
-      const ld = dirOfId(id, "_layout")
-      return ld === "" || ld === errDir || errDir.startsWith(`${ld}/`)
-    })
-    const layouts = await Promise.all(
-      keptLayoutIds.map((id) =>
-        (manifest.layouts[id] as LayoutEntry).load().then((m) => m.default),
-      ),
-    )
-    const { default: errComp } = await (manifest.errors?.[errorId] as LayoutEntry).load()
-    const e = err instanceof Error ? err : new Error(String(err))
-    return renderPageResult({
-      adapter,
-      chain: [...layouts, errComp],
-      data: { name: e.name, message: e.message },
-      clientEntry,
-      routeId: errorId,
-      status: 500,
-      hydrate: false,
-      ...titleOption,
-    })
-  }
-
-  // The 404 response - the `_404` page (status 404) or a plain-text fallback. Shared by the wildcard
-  // catch-all (unmatched paths) and the `fallback: "404"` enforcement (unlisted paths under a route
-  // that opted out of on-demand SSR).
-  const renderNotFound = (path?: string): Promise<Response | RenderedPage> =>
-    renderTerminalStatus(404, path)
-
-  /**
-   * Render a terminal-status page: the `_<status>` page if the app authored one, else `_404`, else
-   * plain text. Shared by the wildcard catch-all, `fallback: "404"` enforcement, and a loader's
-   * `notFound()` / `gone()` / `statusPage()`, so all of them resolve the page and set the status
-   * through one path rather than forking.
-   *
-   * Hydrates, following the `_404` precedent rather than `_error`'s non-hydrated 500: these are
-   * ordinary pages the client router can own, and a 404 arrived at by clicking a link should behave
-   * like any other route.
-   */
-  const renderTerminalStatus = async (
-    status: number,
-    path?: string,
-    extraHeaders?: HeadersLike,
-  ): Promise<Response | RenderedPage> => {
-    const page = manifest.statusPages?.[String(status)] ?? manifest.notFound
-    if (page === undefined) {
-      const headers = new Headers(extraHeaders)
-      headers.set("content-type", "text/plain; charset=utf-8")
-      return new Response(STATUS_TEXT[status] ?? "Error", { status, headers })
-    }
-    // The routeId decides which preload/style bundle and which client component this maps to, so it
-    // must name the page actually rendered - `_410` when `_410.tsx` exists, `_404` when it fell back.
-    const routeId = manifest.statusPages?.[String(status)] !== undefined ? `_${status}` : "_404"
-    const loaded = (await page.load()) as {
-      readonly default: unknown
-      readonly searchSchema?: RouteModule["searchSchema"]
-    }
-    const component = loaded.default
-    return renderPageResult({
-      adapter,
-      chain: [component],
-      data: null,
-      clientEntry,
-      routeId,
-      // The page hydrates, so besides `path` its SSR `search` must equal the client mount's derivation for
-      // this routeId (`searchOf(searchSchema, url.search)`), or a status page reading `useSearch` drifts.
-      // Only when `path` is present (a real URL); a schema-less status page then gets the raw parsed query.
-      ...(path !== undefined
-        ? {
-            search: searchOf(
-              loaded.searchSchema,
-              path.includes("?") ? path.slice(path.indexOf("?")) : "",
-            ),
-          }
-        : {}),
-      // The page hydrates, so its SSR `path` must equal the client's initial
-      // `location.pathname+search` (an unmatched path yields no params → `{}`), or a `useLocation`
-      // on it would drift.
-      ...(path !== undefined ? { path } : {}),
-      status,
-      ...(extraHeaders !== undefined ? { headers: extraHeaders } : {}),
-      ...preloadOf(routeId),
-      ...stylesOf(routeId),
-      prerenderedPaths: options.prerenderedPaths ?? [],
-      ...titleOption,
-    })
-  }
-
-  /**
-   * Answer a loader's terminal-status signal, in whichever form the caller asked for.
-   *
-   * A hard navigation wants the document, so it gets the rendered boundary. A client-side navigation
-   * fetched DATA, not a document, so it gets an empty body plus the status on `X-Nifra-Status`, and
-   * the client router renders the same boundary from its own manifest. Sending the HTML back to a
-   * soft-nav would be answering a different question than the one asked - and skipping the header
-   * entirely is what leaves a crawler seeing a correct 404 while a user who clicked a link sees a
-   * blank page.
-   */
-  const renderStatusSignal = (
-    req: Request,
-    signal: StatusSignal,
-  ): Promise<Response | RenderedPage> | Response => {
-    const { status, headers } = signal[STATUS_SIGNAL]
-    if (req.headers.get(DATA_HEADER) !== null) {
-      const responseHeaders = new Headers(headers)
-      responseHeaders.set(STATUS_HEADER, String(status))
-      return new Response(null, { status, headers: responseHeaders })
-    }
-    return renderTerminalStatus(status, pathOf(req), headers)
-  }
+  const pageExecutor = createPageRequestExecutor<Env>({
+    adapter,
+    manifest,
+    clientEntry,
+    ...(title === undefined ? {} : { title }),
+    ...(api === undefined ? {} : { api }),
+    ...(options.draftSecret === undefined ? {} : { draftSecret: options.draftSecret }),
+    ...(options.routePreload === undefined ? {} : { routePreload: options.routePreload }),
+    ...(options.styles === undefined ? {} : { styles: options.styles }),
+    ...(options.routeStyles === undefined ? {} : { routeStyles: options.routeStyles }),
+    ...(options.cssLoading === undefined ? {} : { cssLoading: options.cssLoading }),
+    ...(options.prerenderedPaths === undefined
+      ? {}
+      : { prerenderedPaths: options.prerenderedPaths }),
+    ...(options.staticFallbacks === undefined ? {} : { staticFallbacks: options.staticFallbacks }),
+    ...(options.staticBoundaryCache === undefined
+      ? {}
+      : { staticBoundaryCache: options.staticBoundaryCache }),
+    ...(options.nonce === undefined ? {} : { nonce: options.nonce }),
+    ...(options.onLoaderError === undefined ? {} : { onLoaderError: options.onLoaderError }),
+  })
 
   for (const route of manifest.routes) {
-    // A dynamic route whose `getStaticPaths` declared `fallback: "404"` - only its prerendered paths
-    // exist; anything else 404s (computed once per route, not per request).
-    const is404Fallback = options.staticFallbacks?.[route.pattern] === "404"
-    // Per-route document-assembly cache (see RenderAssemblyCache): filled on the first GET render and
-    // reused while the route + layout MODULE IDENTITIES are unchanged. Attached only when every meta
-    // in the chain is static - a `meta(data)` function makes the head per-request, so those routes
-    // always assemble fresh. A module reload (dev HMR) yields new module objects, dropping the slot.
-    let assemblySlot: RenderAssemblyCache | undefined
-    let assemblySlotMod: unknown
-    let assemblySlotLayouts: LoadedLayoutModules | undefined
-    const assemblyCacheFor = (
-      mod: RouteModule,
-      lms: LoadedLayoutModules,
-    ): { assemblyCache: RenderAssemblyCache } | Record<string, never> => {
-      if (typeof mod.meta === "function") return {}
-      for (const m of lms) if (typeof m.meta === "function") return {}
-      const layoutsUnchanged =
-        assemblySlotLayouts !== undefined &&
-        assemblySlotLayouts.length === lms.length &&
-        assemblySlotLayouts.every((m, i) => m === lms[i])
-      if (assemblySlotMod !== mod || !layoutsUnchanged) {
-        assemblySlot = {}
-        assemblySlotMod = mod
-        assemblySlotLayouts = lms
-      }
-      return { assemblyCache: assemblySlot as RenderAssemblyCache }
-    }
-    app.register("GET", route.pattern, undefined, async (c: RouteContext) => {
-      // Enforce `fallback: "404"` before any work: an unlisted path under this route doesn't exist.
-      // Covers hard navigation directly; a client soft-nav's data fetch gets the 404, throws, and the
-      // history layer falls back to a full-page navigation (which lands here again, as a document).
-      if (is404Fallback && !prerenderedSet.has(urlPartsFor(c.req).pathname)) {
-        return renderNotFound(pathOf(c.req))
-      }
-      const mod = await route.load()
-      const draft = await draftFlag(c.req)
-      let data: unknown
-      let layoutData: readonly unknown[] | undefined
-      let boundaryStates: BoundaryStates | undefined
-      let layoutModules: LoadedLayoutModules | undefined
-      let layoutRetained: readonly number[] = []
-      try {
-        const ctx = {
-          params: c.params,
-          request: c.req,
-          req: c.req,
-          api,
-          env: c.env,
-          draft,
-          search: loaderSearch(mod.searchSchema, c.req),
-        }
-        // Layout loaders run for BOTH the document and the data-only request. A gate that only ran on
-        // the document path would be bypassed by adding the data header, which is exactly the request
-        // a client navigation makes - a guard has to hold on the path an attacker can pick.
-        //
-        // `runLayoutChain` returns once every GATE has resolved, with the non-gate loaders still in
-        // flight. So the page loader starts as late as correctness requires and as early as speed
-        // allows, and both are awaited together below.
-        const run = await runLayoutChain(
-          route,
-          ctx,
-          validatedRetainedIndices(c.req, route, c.params),
-        )
-        layoutModules = run.modules
-        layoutRetained = run.retained
-        const boundaryDefinitions = [
-          ...run.modules.flatMap((layout) => layout.boundaries ?? []),
-          ...(mod.boundaries ?? []),
-        ]
-        if (boundaryDefinitions.length > 0) boundaryDescriptors(boundaryDefinitions)
-        const effectiveSearch = searchChainOf(run.modules, mod, c.req)
-        const boundaryBatch =
-          boundaryDefinitions.length === 0
-            ? undefined
-            : startDynamicBoundaries(boundaryDefinitions, {
-                request: c.req,
-                params: c.params,
-                api,
-                env: c.env,
-                draft,
-                search: effectiveSearch,
-                signal: c.req.signal,
-              } satisfies BoundaryRequestCtx)
-        const staticBoundaryPromise =
-          boundaryDefinitions.length === 0
-            ? Promise.resolve(undefined)
-            : resolveStaticBoundaries(
-                boundaryDefinitions,
-                { phase: "build", origin: originOf(c.req) },
-                options.staticBoundaryCache,
-              )
-        // Boundary data is attached as one Deferred marker per slot. The shell can render
-        // immediately with each slot pending, while the existing deferred protocol emits the first
-        // completed sibling independently instead of waiting for the slowest boundary.
-        // The page loader gets the EFFECTIVE search (layout chain + page, page-wins), now that the layout
-        // modules are loaded - so `ctx.search` includes a layout's shared keys (`?org`), matching `useSearch`.
-        const [pageData, , staticBoundaries] = await Promise.all([
-          mod.loader ? mod.loader({ ...ctx, search: effectiveSearch }) : null,
-          run.pending, // a non-gate layout loader that rejects must still surface, not go unhandled
-          staticBoundaryPromise,
-        ])
-        data = pageData
-        layoutData = run.layoutData
-        if (boundaryBatch !== undefined) {
-          const streamed = { ...boundaryBatch.initial, ...(staticBoundaries ?? {}) }
-          for (const entry of boundaryBatch.pending) {
-            const initial = streamed[entry.name]
-            if (initial !== undefined)
-              streamed[entry.name] = { ...initial, data: defer(entry.promise) }
-          }
-          boundaryStates = streamed
-        } else if (staticBoundaries !== undefined) {
-          boundaryStates = staticBoundaries
-        }
-      } catch (err) {
-        // A terminal-status signal (`notFound()` / `gone()` / `statusPage(n)`) renders a boundary at
-        // that status. Checked BEFORE the pass-through below: a signal IS a `Response`, so the order
-        // is what keeps a hand-rolled `throw new Response(...)` served verbatim, as it always was.
-        if (isStatusSignal(err)) return renderStatusSignal(c.req, err)
-        // A thrown control-flow signal (a guard's `redirect(...)`, an explicit error response) - let
-        // it propagate to core, which renders it as-is, whether it is a plain render or a
-        // hand-rolled `Response`. Real errors render the nearest `_error` boundary, if any; with
-        // none, rethrow (unchanged 500 behavior).
-        if (isControlFlow(err)) throw err
-        // Let reporting plugins observe the data-layer failure before it's rendered/rethrown/500'd.
-        if (options.onLoaderError !== undefined) {
-          try {
-            options.onLoaderError(err, { request: c.req, params: c.params, route: route.pattern })
-          } catch {
-            // A faulty reporter must never break error rendering.
-          }
-        }
-        const errorId = boundaryFor(route, err)
-        if (errorId === undefined) throw err
-        // A soft-nav data fetch can't render a boundary - 500 so the client falls back to a full-page
-        // navigation, which lands here as a document and renders the `_error` page.
-        if (c.req.headers.get(DATA_HEADER) !== null) {
-          return new Response("Internal Server Error", {
-            status: 500,
-            headers: { "content-type": "text/plain; charset=utf-8" },
-          })
-        }
-        return renderError(route, errorId, withDuplicateInstanceHint(err))
-      }
-      // A loader may RETURN its control-flow signal instead of throwing it - `return redirect(...)`
-      // reads naturally and must not silently serialize the signal as loader data. Mirror the catch
-      // above exactly: a status signal renders its boundary, any other signal (a redirect, a
-      // hand-rolled response) passes through to core verbatim - so return and throw are
-      // interchangeable.
-      if (isStatusSignal(data)) return renderStatusSignal(c.req, data)
-      if (isControlFlow(data)) return data
-      // Client-side navigation asks (via the X-Nifra-Data header) for just the loader data - no full
-      // document, no layout chain. A route with deferred data streams NDJSON (critical data first,
-      // then each deferred value as it settles); otherwise one JSON (the fast path). Same loader,
-      // same auth - only the transport differs.
-      if (c.req.headers.get(DATA_HEADER) !== null) {
-        const pageSplit = prepareDeferred(data)
-        const layoutSplits: Array<ReturnType<typeof prepareDeferred>> = []
-        let offset = pageSplit.deferred.length
-        for (const entry of layoutData ?? []) {
-          const split = prepareDeferred(entry, offset)
-          layoutSplits.push(split)
-          offset += split.deferred.length
-        }
-        const deferred = [...pageSplit.deferred, ...layoutSplits.flatMap((split) => split.deferred)]
-        const boundarySplit =
-          boundaryStates === undefined
-            ? undefined
-            : prepareDeferred(boundaryStates, deferred.length)
-        const allDeferred = [
-          ...deferred,
-          ...(boundarySplit === undefined ? [] : boundarySplit.deferred),
-        ]
-        const payload =
-          layoutData === undefined && boundarySplit === undefined
-            ? pageSplit.forClient
-            : {
-                v: 1 as const,
-                data: pageSplit.forClient,
-                layoutData: layoutSplits.map((split) => split.forClient),
-                retained: layoutRetained,
-                ...(boundarySplit === undefined ? {} : { boundaries: boundarySplit.forClient }),
-              }
-        // Bare value when there is no layout data - the pre-envelope shape, so a client running older
-        // code against a newer server keeps working.
-        if (allDeferred.length === 0) {
-          return Response.json(payload ?? null)
-        }
-        return new Response(ndjsonStream(payload, allDeferred), {
-          headers: { "content-type": "application/x-ndjson; charset=utf-8" },
-        })
-      }
-      const chainLayoutModules = layoutModules ?? (await loadLayoutModules(route))
-      const { chain, head } = resolveChainAndHead(chainLayoutModules, mod, {
-        data,
-        params: c.params,
-        origin: originOf(c.req),
-      })
-      const hydrateRoute = mod.hydrate !== false
-      try {
-        // `await` so a shell-render throw (renderToStream rejects before any byte) is caught here and
-        // can render the `_error` page - not just a loader throw. Mid-stream (post-shell) throws can't
-        // be recovered to a full page; the per-adapter client boundary catches client render errors.
-        return await renderPageResult({
-          adapter,
-          chain,
-          data,
-          head,
-          clientEntry,
-          routeId: route.id,
-          params: c.params,
-          path: pathOf(c.req),
-          // The effective (layout chain + page) search, matching the page loader's `ctx.search` above and
-          // the client mount - so `useSearch` renders SSR-correct and hydrates with no drift. `layoutModules`
-          // is loaded by now (the loader try succeeded to reach here).
-          search: searchChainOf(layoutModules ?? [], mod, c.req),
-          hydrate: hydrateRoute,
-          ...(layoutData !== undefined ? { layoutData } : {}),
-          ...(boundaryStates !== undefined ? { boundaries: boundaryStates } : {}),
-          ...preloadOf(route.id),
-          ...stylesOf(route.id),
-          prerenderedPaths: options.prerenderedPaths ?? [],
-          ...(mod.revalidate !== undefined ? { revalidate: mod.revalidate } : {}),
-          ...(mod.revalidateTags !== undefined ? { revalidateTags: mod.revalidateTags } : {}),
-          ...(mod.islandScripts !== undefined ? { islandScripts: mod.islandScripts } : {}),
-          ...titleOption,
-          ...assemblyCacheFor(mod, chainLayoutModules),
-        })
-      } catch (err) {
-        // Same precedence as the loader catch above - a `meta()` may signal too.
-        if (isStatusSignal(err)) return renderStatusSignal(c.req, err)
-        if (isControlFlow(err)) throw err
-        // Let reporting plugins observe the data-layer failure before it's rendered/rethrown/500'd.
-        if (options.onLoaderError !== undefined) {
-          try {
-            options.onLoaderError(err, { request: c.req, params: c.params, route: route.pattern })
-          } catch {
-            // A faulty reporter must never break error rendering.
-          }
-        }
-        const errorId = boundaryFor(route, err)
-        if (errorId === undefined) throw err
-        return renderError(route, errorId, withDuplicateInstanceHint(err))
-      }
-    })
-
-    // POST runs the route's `action` (mutation). A control-flow return (e.g. a `redirect(...)`)
-    // passes straight through; a data return re-renders the page (the loader re-runs for fresh
-    // data) with `actionData`. Routes without an action reject POST with 405 - not a stray 404.
-    app.register("POST", route.pattern, undefined, async (c: RouteContext) => {
-      const mod = await route.load()
-      const draft = await draftFlag(c.req)
-      if (mod.action === undefined) {
-        return new Response("Method Not Allowed", {
-          status: 405,
-          headers: { allow: "GET", "content-type": "text/plain; charset=utf-8" },
-        })
-      }
-      const actionContext = {
-        params: c.params,
-        request: c.req,
-        req: c.req,
-        api,
-        env: c.env,
-        draft,
-        search: loaderSearch(mod.searchSchema, c.req),
-      }
-      const isDataRequest = c.req.headers.get(DATA_HEADER) !== null
-      let layoutModules: LoadedLayoutModules
-      let result: unknown
-      try {
-        // A gate is an authorization boundary for everything beneath its layout, mutations included.
-        // Run only gates before the action; ordinary layout data loaders run after a native mutation.
-        layoutModules = await runLayoutGates(route, actionContext)
-        result = await mod.action(actionContext)
-      } catch (err) {
-        // A THROWN signal is the same control flow as a returned one (`throw redirect()` in a gate
-        // or an action) - route it through the same conversion as the returned branch below, so
-        // throw and return are interchangeable on the mutation path too.
-        if (isControlFlow(err)) return actionResponse(err, isDataRequest)
-        throw err
-      }
-      // An action may wrap its data in `revalidate(paths, data)` to declare which routes it changed.
-      // Unwrap to the inner data; the paths ride the `X-Nifra-Revalidate` header on the data-mode
-      // responses (the client acts on them - a full-page POST re-runs loaders inline, so no header).
-      const isRevalidate =
-        result !== null && typeof result === "object" && "__nifraRevalidate" in result
-      const actionResult = isRevalidate ? (result as RevalidateResult<unknown>).data : result
-      const revalidateHeader: Record<string, string> = isRevalidate
-        ? { [REVALIDATE_HEADER]: (result as RevalidateResult<unknown>).__nifraRevalidate.join(",") }
-        : {}
-      if (isControlFlow(actionResult)) return actionResponse(actionResult, isDataRequest)
-      // Client submit wants just the action's data (it revalidates the loader itself); a native
-      // form POST re-renders the full page (loader re-runs) with the action data.
-      if (isDataRequest) {
-        // An action may `defer()` slow parts of its result - stream them (critical data first, then
-        // each deferred as it settles) exactly like a loader; a non-deferred action returns one JSON.
-        const { forClient, deferred } = prepareDeferred(actionResult)
-        if (deferred.length === 0)
-          return Response.json(actionResult ?? null, { headers: revalidateHeader })
-        return new Response(ndjsonStream(forClient, deferred), {
-          headers: { "content-type": "application/x-ndjson; charset=utf-8", ...revalidateHeader },
-        })
-      }
-      // Derived once and shared: the loader's `ctx.search` and the render's `RenderProps.search` are the
-      // SAME effective (layout chain + page) value, and the client mount rebuilds it identically. The
-      // layout modules are already loaded (the action ran through their gates above).
-      const search = searchChainOf(layoutModules, mod, c.req)
-      const data = mod.loader
-        ? await mod.loader({
-            params: c.params,
-            request: c.req,
-            req: c.req,
-            api,
-            env: c.env,
-            draft,
-            search,
-          })
-        : null
-      const { chain, head } = resolveChainAndHead(layoutModules, mod, {
-        data,
-        params: c.params,
-        origin: originOf(c.req),
-      })
-      const hydrateRoute = mod.hydrate !== false
-      // A full-page POST streams the action's `defer()`'d parts mid-document behind `<Await>` too -
-      // `renderPage` splits `actionData` like loader data (works with JS off; hydrates after).
-      return renderPageResult({
-        adapter,
-        chain,
-        data,
-        actionData: actionResult,
-        head,
-        clientEntry,
-        routeId: route.id,
-        params: c.params,
-        path: pathOf(c.req),
-        search,
-        hydrate: hydrateRoute,
-        ...preloadOf(route.id),
-        ...stylesOf(route.id),
-        prerenderedPaths: options.prerenderedPaths ?? [],
-        ...titleOption,
-      })
-    })
+    app.register("GET", route.pattern, undefined, pageExecutor.get(route))
+    app.register("POST", route.pattern, undefined, pageExecutor.post(route))
   }
-
   // Register llms.txt & llms-full.txt
   const llmsOptions = { includeLocalGuidelines: options.publishLocalGuidelines === true }
   app.register("GET", "/llms.txt", undefined, async () => {
@@ -1108,7 +339,9 @@ export function createWebApp<Env = unknown>(
   })
 
   // Wildcard catch-all: unmatched paths render `_404` (404), or a plain text 404 if absent.
-  app.register("GET", "/*", undefined, (c: RouteContext) => renderNotFound(pathOf(c.req)))
+  app.register("GET", "/*", undefined, (c: RouteContext<Env>) =>
+    pageExecutor.notFound(c.req, c.env, requestPathOf(c.req)),
+  )
 
   return app
 }