@nifrajs/web 5.5.1 → 5.7.0

package/src/internal/page-execution.ts

@@ -10,21 +10,24 @@ import {
   status as statusResult,
 } from "@nifrajs/core/server"
 import {
+  type BoundaryRegistration,
   type BoundaryRequestCtx,
   type BoundaryStates,
   boundaryDescriptors,
   resolveStaticBoundaries,
+  type ShellCtx,
   type StaticBoundaryCache,
   startDynamicBoundaries,
 } from "../boundary.ts"
 import type { CspPolicy } from "../csp.ts"
 import { type CssLoadingMode, DEFAULT_CSS_LOADING, normalizeCssLoading } from "../css-contract.ts"
-import { defer, ndjsonStream, prepareDeferred } from "../deferred.ts"
+import { type Deferred, defer, ndjsonStream, prepareDeferred } from "../deferred.ts"
 import { isDraftEnabled } from "../draft.ts"
 import { routeTags } from "../isr.ts"
 import type {
   LayoutEntry,
   LoaderContext,
+  LoaderResponseControls,
   Manifest,
   Meta,
   MetaArgs,
@@ -35,10 +38,14 @@ import type {
 } from "../manifest.ts"
 import type { NonceResolver } from "../nonce.ts"
 import type { MatchChain, PageLocale, PageLocales, RenderAdapter } from "../render-seam.ts"
+import { SWAP_HEADER } from "../render-seam.ts"
 import {
   createMatcher,
   DATA_HEADER,
+  HOLE_FILL_HEADER,
+  KEEP_HOLES_HEADER,
   NAV_FROM_HEADER,
+  PREFETCH_HEADER,
   REDIRECT_HEADER,
   RETAIN_HEADER,
   REVALIDATE_HEADER,
@@ -46,25 +53,36 @@ import {
 } from "../router.ts"
 import { searchOf, searchOfChain } from "../search.ts"
 import { mergeHeads, resolveChainMeta } from "./head-merge.ts"
+import { keepAliveTable, slotDepths } from "./keep-alive-table.ts"
+import {
+  holeOwner,
+  type LiveEnvelope,
+  type LiveFinish,
+  type LiveLoad,
+  type LiveRouteMatch,
+} from "./live-contract.ts"
 import { prepareModules } from "./module-preparation.ts"
+import {
+  type HoleLive,
+  isHole,
+  type PprIntegration,
+  type PprRequest,
+  serverHoleComponent,
+} from "./ppr/contract.ts"
 import {
   EMPTY_RETAIN,
-  type HeadersLike,
   isControlFlow,
   isResponseResult,
-  isStatusSignal,
+  isRevalidateResult,
   type LoadedLayoutModules,
   layoutErrorId,
-  notFound,
   type RenderAssemblyCache,
   type RenderedPage,
   type RenderPageOptions,
   type RevalidateResult,
   redirect,
   renderPageResult,
-  STATUS_SIGNAL,
   STATUS_TEXT,
-  type StatusSignal,
   scopeParams,
   tagLayoutError,
   withDuplicateInstanceHint,
@@ -82,6 +100,13 @@ import {
   privateOutcome,
   varyOnDataHeader,
 } from "./response-controls.ts"
+import {
+  type HeadersLike,
+  isStatusSignal,
+  notFound,
+  STATUS_SIGNAL,
+  type StatusSignal,
+} from "./status-page.ts"
 
 export type { NonceResolver } from "../nonce.ts"
 
@@ -101,13 +126,145 @@ export interface PageRouteContext<Env = unknown> {
 }
 
 /** Whether `c` is a client navigation's data request. On Node, `req.headers` builds every header. */
+// The slot name is echoed in a response header, so only a plain identifier is honored.
+const SLOT_NAME = /^[A-Za-z][\w-]{0,63}$/
+
+/** The slot an `x-nifra-swap` request names, when it is a valid slot name. */
+function swapSlotOf(req: Request): string | undefined {
+  const name = req.headers.get(SWAP_HEADER)
+  return name !== null && SLOT_NAME.test(name) ? name : undefined
+}
+
+/** The `swapSlot` render option for `req`, empty when it is not a swap request. */
+function swapOption(req: Request): { readonly swapSlot?: string } {
+  const swapSlot = swapSlotOf(req)
+  return swapSlot === undefined ? {} : { swapSlot }
+}
+
+const headerOf = (c: PageRouteContext<unknown>, name: string): string | null =>
+  c.header !== undefined ? c.header(name) : c.req.headers.get(name)
+
 function isDataRequest(c: PageRouteContext<unknown>): boolean {
-  return (c.header !== undefined ? c.header(DATA_HEADER) : c.req.headers.get(DATA_HEADER)) !== null
+  return headerOf(c, DATA_HEADER) !== null
+}
+
+/** The live owners of one response's holes, settled once the last hole that ran does. */
+interface HoleOwners {
+  readonly kept: readonly string[]
+  readonly loaded: Promise<readonly string[]>
+}
+
+/**
+ * A data request's hole refresh: the hosts the client holds, which reload as fills, the holes it
+ * keeps, and in a live load each hole's owner. A name the route does not declare is a 400.
+ */
+function holeRefresh(
+  c: PageRouteContext<unknown>,
+  request: PprRequest,
+  live: LiveLoad | undefined,
+): { readonly request: PprRequest; readonly owners?: HoleOwners } | Response {
+  if (!isDataRequest(c)) return { request }
+  const declared = new Set(request.holes.map((hole) => hole.name))
+  const namesOf = (header: string): Set<string> | undefined => {
+    const value = headerOf(c, header)
+    const names = new Set<string>()
+    if (value === null) return names
+    for (const name of value.split(",")) {
+      const trimmed = name.trim()
+      if (declared.has(trimmed)) names.add(trimmed)
+      // A live load's names come from a grant this server sealed and the page's own client: one
+      // naming a hole an older build declared is skipped.
+      else if (live === undefined) return undefined
+    }
+    return names
+  }
+  const kept = namesOf(KEEP_HOLES_HEADER)
+  const fill = namesOf(HOLE_FILL_HEADER)
+  if (kept === undefined || fill === undefined) {
+    return new Response("Bad Request: the route has no such hole", {
+      status: 400,
+      headers: { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" },
+    })
+  }
+  const refreshed: PprRequest = {
+    ...request,
+    ...(fill.size === 0 ? {} : { fill }),
+    ...(kept.size === 0 ? {} : { kept }),
+  }
+  if (live === undefined) return { request: refreshed }
+  const routeId = request.routeId
+  let finish: (loaded: readonly string[]) => void = () => {}
+  const loaded = new Promise<readonly string[]>((resolve) => {
+    finish = resolve
+  })
+  const holeLive: HoleLive = {
+    collector: (hole) => live.collector(holeOwner(hole, routeId)),
+    seal: (hole) => live.seal(holeOwner(hole, routeId)),
+    done: (names) => finish(names.map((hole) => holeOwner(hole, routeId))),
+  }
+  return {
+    request: { ...refreshed, live: holeLive },
+    owners: { kept: [...kept].map((hole) => holeOwner(hole, routeId)), loaded },
+  }
 }
 
 /** The page slot of an `ssr = false` route with no `HydrateFallback`: a component that renders nothing. */
 const EMPTY_LEAF = (): null => null
 
+/** `ctx.live` outside a live load: keys are declared for nobody. */
+const NO_LIVE = (): void => {}
+
+const headersSent = (): never => {
+  throw new TypeError(
+    "[nifra/web] ppr: a hole's server component cannot set a cookie: the shell already sent the headers",
+  )
+}
+
+/** A hole's response headers went out with the shell, so its server component sets none. */
+const SENT_CONTROLS: LoaderResponseControls = Object.freeze({
+  headers: Object.freeze({}),
+  cookie: headersSent,
+  deleteCookie: headersSent,
+})
+
+/**
+ * The envelope's `live` member. With holes running it trails them: one grant, issued once the last hole
+ * settled, holding each hole that loaded and each the client kept.
+ */
+const liveEnvelopeOf = (
+  live: LiveLoad,
+  owners: LiveFinish,
+  holes: HoleOwners | undefined,
+): Promise<LiveEnvelope> | Deferred<LiveEnvelope> =>
+  holes === undefined
+    ? live.finish(owners)
+    : defer(
+        holes.loaded.then((loaded) =>
+          live.finish({
+            ...owners,
+            fresh: [...owners.fresh, ...loaded],
+            retained: [...owners.retained, ...holes.kept],
+          }),
+        ),
+      )
+
+/** Run one owner's loader with its `ctx.live`, closing the collector once the loader settles. */
+const runLiveLoader = (
+  live: LiveLoad,
+  owner: string,
+  loader: (ctx: LoaderContext) => unknown,
+  ctx: LoaderContext,
+): Promise<unknown> => {
+  let value: unknown
+  try {
+    value = loader({ ...ctx, live: live.collector(owner) })
+  } catch (err) {
+    live.seal(owner)
+    return Promise.reject(err)
+  }
+  return Promise.resolve(value).finally(() => live.seal(owner))
+}
+
 /** The request-scoping seam of an in-process `api` (see `inProcessClient`), if it carries one. */
 function platformBinderOf(api: unknown): BackendPlatformBinder | undefined {
   if ((typeof api !== "object" && typeof api !== "function") || api === null) return undefined
@@ -244,6 +401,18 @@ export interface PageExecutionOptions<Env = unknown> {
   readonly csp?: CspPolicy
   /** Set once a cache wrapper attaches; until then a route's freshness and tags stay off the response. */
   readonly cacheChannel?: { readonly enabled: boolean }
+  /**
+   * Run, or hand to the cache wrapper, what an action's `revalidate()` made stale. A promise is awaited
+   * before the action answers; `undefined` means nothing runs it. Never throws, never changes the answer.
+   */
+  readonly invalidate?: (
+    revalidation: RevalidateResult<unknown>,
+    request: Request,
+  ) => Promise<void> | undefined
+  /** The live load a request belongs to; only set when the app configures `live`. */
+  readonly liveLoadOf?: ((request: Request) => LiveLoad | undefined) | undefined
+  /** The seed a rendered document collects its keys into; only set when the app configures `live`. */
+  readonly liveSeedOf?: ((request: Request, routeId: string) => LiveLoad | undefined) | undefined
   readonly onLoaderError?: (
     error: unknown,
     ctx: {
@@ -255,6 +424,8 @@ export interface PageExecutionOptions<Env = unknown> {
   /** Logs a failure an `_error` boundary answered. Without a boundary the error propagates and the
    * server logs it, so this runs only where the server never sees the throw. */
   readonly logBoundaryError?: (error: unknown, request: Request) => void
+  /** Experimental partial prerendering: routes with a `shellLoader` stream a shared shell, then holes. */
+  readonly ppr?: PprIntegration
 }
 
 type PageResponse = Response | ResponseResult | RenderedPage
@@ -264,6 +435,8 @@ export interface PageRequestExecutor<Env = unknown> {
   post(route: RouteEntry): (ctx: PageRouteContext<Env>) => Promise<PageResponse>
   /** Answer a URL no route matched: the nearest nested `_404` for it, else the root one. */
   fallback(ctx: PageRouteContext<Env>): Promise<PageResponse>
+  /** The route a `pathname + search` renders, with its layout chain. */
+  matchRoute(path: string): LiveRouteMatch | null
 }
 
 /** One URL pattern a nested `_404` answers, as the executor indexes it. */
@@ -355,11 +528,13 @@ export function createPageRequestExecutor<Env = unknown>(
   const { i18n } = options
   const pageLocales = new Map(i18n?.locales.locales.map((locale) => [locale.key, locale]))
   /** The request's locale for a document, with the served locales the client names locales from. */
-  const localeOption = (req: Request): { locale?: PageLocale; locales?: PageLocales } => {
+  const localeFor = (key: string): { locale?: PageLocale; locales?: PageLocales } => {
     if (i18n === undefined) return {}
-    const locale = pageLocales.get(i18n.localeOf(pathOf(req)))
+    const locale = pageLocales.get(key)
     return locale === undefined ? { locales: i18n.locales } : { locale, locales: i18n.locales }
   }
+  const localeOption = (req: Request): { locale?: PageLocale; locales?: PageLocales } =>
+    i18n === undefined ? {} : localeFor(i18n.localeOf(pathOf(req)))
   /** Whether a route sits under a `[lang]` or `[[lang]]` directory, which the locale routing checks. */
   const localeGuarded = (route: RouteEntry): boolean => {
     if (i18n === undefined) return false
@@ -372,6 +547,52 @@ export function createPageRequestExecutor<Env = unknown>(
     manifest.routes.map((route) => ({ routeId: route.id, pattern: route.pattern })),
   )
   const routeById = new Map(manifest.routes.map((route) => [route.id, route]))
+  const liveLoadOf = options.liveLoadOf
+  const liveSeedOf = options.liveSeedOf
+
+  /** A live load holds one admission slot from before its middleware until its body is complete. */
+  const admitLive =
+    (run: (c: PageRouteContext<Env>, controls: PageResponseControls) => Promise<PageResponse>) =>
+    async (c: PageRouteContext<Env>, controls: PageResponseControls): Promise<PageResponse> => {
+      const live = liveLoadOf?.(c.req)
+      if (live === undefined) return run(c, controls)
+      const refused = live.admit()
+      if (refused !== undefined) return refused
+      let outcome: PageResponse
+      try {
+        outcome = await run(c, controls)
+      } catch (err) {
+        live.release()
+        throw err
+      }
+      if (outcome instanceof Response) return live.settle(outcome)
+      live.release()
+      return outcome
+    }
+
+  /** Which owners a successful live load ran and which it kept, by their wire ids. */
+  const liveOwners = (
+    route: RouteEntry,
+    modules: LoadedLayoutModules | undefined,
+    layoutData: readonly unknown[] | undefined,
+    retained: readonly number[],
+    mod: RouteModule,
+    skipPage: boolean,
+    ctx: LoaderContext,
+  ): LiveFinish => {
+    const fresh: string[] = []
+    const kept: string[] = []
+    for (let i = 0; i < (modules?.length ?? 0); i++) {
+      if (modules?.[i]?.loader === undefined) continue
+      const owner = `L:${route.layoutIds[i]}`
+      if (retained.includes(i)) kept.push(owner)
+      // A layout that answered with a status declared keys for data nobody is shown.
+      else if (!isStatusSignal(layoutData?.[i])) fresh.push(owner)
+    }
+    if (skipPage) kept.push(`P:${route.id}`)
+    else if (mod.loader !== undefined) fresh.push(`P:${route.id}`)
+    return { fresh, retained: kept, ctx }
+  }
 
   // A nested `_404` answers an unmatched URL from inside the catch-all, never as a route of its own:
   // a registered `/admin/*` would take URLs from a route the router only reaches by backtracking.
@@ -419,6 +640,19 @@ export function createPageRequestExecutor<Env = unknown>(
       ? Promise.resolve(false)
       : isDraftEnabled(req, options.draftSecret)
 
+  // Where the browser's keep-alive view puts slot wrappers, so the document it hydrates has them:
+  // nothing outside an app with a `keepAlive` route.
+  const keepTable = keepAliveTable(manifest)
+  const slotsFor = (
+    layoutIds: readonly string[],
+    routeId: string,
+  ): { slots?: readonly number[] } => {
+    // Every page of a keep-alive app renders through the adapter's keep-alive root, wrappers or none,
+    // as the browser hydrates it.
+    if (keepTable === undefined) return {}
+    return { slots: slotDepths(keepTable, layoutIds, routeId) }
+  }
+
   const preloadOf = (id: string): { preload?: readonly string[] } => {
     const chunks = options.routePreload?.[id]
     return chunks ? { preload: chunks } : {}
@@ -521,6 +755,7 @@ export function createPageRequestExecutor<Env = unknown>(
     controls: PageResponseControls,
     retain?: RetainContext,
     gated?: GatedLayouts,
+    live?: LiveLoad,
   ): Promise<LayoutRun> => {
     if (route.layoutIds.length === 0) return emptyLayoutRun
     const modules = gated?.modules ?? (await loadLayoutModules(route))
@@ -552,14 +787,25 @@ export function createPageRequestExecutor<Env = unknown>(
         params: scopeParams(ctx.params, route.layoutParams?.[i]),
         set: controls.scope(i),
       }
+      const layoutId = route.layoutIds[i] as string
       if (modules[i]?.gate === true) {
-        results[i] = gated === undefined ? await runGate(route, i, loader, scoped) : gated.gates[i]
+        results[i] =
+          gated !== undefined
+            ? gated.gates[i]
+            : await runGate(
+                route,
+                i,
+                live === undefined
+                  ? loader
+                  : (gateCtx) => runLiveLoader(live, `L:${layoutId}`, loader, gateCtx),
+                scoped,
+              )
         continue
       }
-      const layoutId = route.layoutIds[i] as string
       const index = i
       try {
-        const value = loader(scoped)
+        const value =
+          live === undefined ? loader(scoped) : runLiveLoader(live, `L:${layoutId}`, loader, scoped)
         // Scalars settle synchronously. Objects keep await's intrinsic promise/thenable
         // assimilation: property-presence and prototype probes are unsafe for proxies.
         if (value !== null && (typeof value === "object" || typeof value === "function")) {
@@ -792,6 +1038,12 @@ export function createPageRequestExecutor<Env = unknown>(
   const dirOfId = (id: string, suffix: string): string =>
     id === suffix ? "" : id.slice(0, id.length - suffix.length - 1)
 
+  /** The server's error log for one request, where a rejected `defer()` value is written. */
+  const deferredLogOf = (req: Request): ((error: unknown) => void) | undefined => {
+    const log = options.logBoundaryError
+    return log === undefined ? undefined : (error) => log(error, req)
+  }
+
   const boundaryFor = (route: RouteEntry, err: unknown): string | undefined => {
     const ids = route.errorIds ?? []
     const failing = layoutErrorId(err)
@@ -859,6 +1111,8 @@ export function createPageRequestExecutor<Env = unknown>(
         routeId: errorId,
         status: 500,
         hydrate: false,
+        signal: req.signal,
+        logError: deferredLogOf(req),
         ...(layoutData === undefined ? {} : { layoutData }),
         ...(personalized || layoutData !== undefined ? { headers: PRIVATE_PAGE_HEADERS } : {}),
         ...(nonce === undefined ? {} : { nonce }),
@@ -952,6 +1206,7 @@ export function createPageRequestExecutor<Env = unknown>(
           draft,
           search: loaderSearch(page.searchSchema, c.req),
           set: controls.scope(PAGE_SCOPE),
+          live: NO_LIVE,
         }
         if (route.middlewareIds !== undefined) await runMiddleware(route, ctx, controls)
         const run = await runLayoutChain(route, ctx, controls)
@@ -1007,6 +1262,8 @@ export function createPageRequestExecutor<Env = unknown>(
       search: searchChainOf(modules, loaded, req),
       path: pathOf(req),
       status,
+      signal: req.signal,
+      logError: deferredLogOf(req),
       // The browser renders this page inside the root layout, so a page that had to render alone
       // stays server-only, as a nested `_404` does.
       ...(wraps && chain === undefined ? { hydrate: false } : {}),
@@ -1021,6 +1278,7 @@ export function createPageRequestExecutor<Env = unknown>(
       ...copyOption,
       ...localeOption(req),
       ...titleOption,
+      ...slotsFor(layoutIds, routeId),
     }
     if (chain === undefined) return renderPageResult(statusPage)
     try {
@@ -1091,6 +1349,8 @@ export function createPageRequestExecutor<Env = unknown>(
     responseHeaders: Record<string, string> | undefined,
     personalized: boolean,
     serverComponents?: import("../server-components/types.ts").ComponentState,
+    live?: LiveEnvelope | Deferred<LiveEnvelope>,
+    liveSeed?: LiveEnvelope,
   ): Promise<PageResponse> => {
     // Every layout loader settled before the page rendered, so a status or error page can reuse them.
     const settled: LayoutChainSource = async (_page, count) =>
@@ -1113,8 +1373,14 @@ export function createPageRequestExecutor<Env = unknown>(
         ...deferred,
         ...(boundarySplit === undefined ? [] : boundarySplit.deferred),
       ]
+      // Deferred when holes run: their owners are known only once the last one settles.
+      const liveSplit = live === undefined ? undefined : prepareDeferred(live, allDeferred.length)
+      if (liveSplit !== undefined) allDeferred.push(...liveSplit.deferred)
       const payload =
-        layoutData === undefined && boundarySplit === undefined && serverComponents === undefined
+        layoutData === undefined &&
+        boundarySplit === undefined &&
+        serverComponents === undefined &&
+        live === undefined
           ? pageSplit.forClient
           : {
               v: 1 as const,
@@ -1123,16 +1389,20 @@ export function createPageRequestExecutor<Env = unknown>(
               retained: layoutRetained,
               ...(boundarySplit === undefined ? {} : { boundaries: boundarySplit.forClient }),
               ...(serverComponents === undefined ? {} : { serverComponents }),
+              ...(liveSplit === undefined ? {} : { live: liveSplit.forClient }),
             }
       if (allDeferred.length === 0) {
         return Response.json(payload ?? null, { headers: DATA_RESPONSE_HEADERS })
       }
-      return new Response(ndjsonStream(payload, allDeferred), {
-        headers: {
-          "content-type": "application/x-ndjson; charset=utf-8",
-          ...DATA_RESPONSE_HEADERS,
+      return new Response(
+        ndjsonStream(payload, allDeferred, undefined, req.signal, deferredLogOf(req)),
+        {
+          headers: {
+            "content-type": "application/x-ndjson; charset=utf-8",
+            ...DATA_RESPONSE_HEADERS,
+          },
         },
-      })
+      )
     }
 
     const nonce = options.nonce === undefined ? undefined : await resolveNonce(req, env)
@@ -1164,13 +1434,19 @@ export function createPageRequestExecutor<Env = unknown>(
         search: searchChainOf(layoutModules, mod, req),
         matchChain: matchChainOf(route.layoutIds, layoutModules, route.id, mod),
         hydrate: mod.hydrate !== false,
+        signal: req.signal,
+        logError: deferredLogOf(req),
         ...preloadOf(route.id),
         ...stylesOf(route.id),
         ...appDocumentOptions,
         ...localeOption(req),
       }
       if (serverComponents !== undefined) page.serverComponents = serverComponents
+      if (liveSeed?.grant !== undefined) page.live = liveSeed
       if (progressiveActionData.has(req)) page.actionData = progressiveActionData.get(req)
+      const swapSlot = swapSlotOf(req)
+      if (swapSlot !== undefined) page.swapSlot = swapSlot
+      if (keepTable !== undefined) Object.assign(page, slotsFor(route.layoutIds, route.id))
       if (layoutData !== undefined) page.layoutData = layoutData
       if (boundaryStates !== undefined) page.boundaries = boundaryStates
       if (responseHeaders !== undefined) page.headers = responseHeaders
@@ -1293,6 +1569,8 @@ export function createPageRequestExecutor<Env = unknown>(
       matchChain: matchChainOf(page.layoutIds, layoutModules, id, mod),
       status: 404,
       hydrate: false,
+      signal: req.signal,
+      logError: deferredLogOf(req),
       ...localeOption(req),
       ...(layoutData !== undefined ? { layoutData } : {}),
       ...stylesOf(id),
@@ -1382,6 +1660,113 @@ export function createPageRequestExecutor<Env = unknown>(
       }
     }
 
+  const pprRequestFor = (
+    c: PageRouteContext<Env>,
+    route: RouteEntry,
+    mod: RouteModule,
+    layouts: LoadedLayoutModules,
+    boundaries: readonly BoundaryRegistration[],
+    shellLoader: NonNullable<RouteModule["shellLoader"]>,
+    requestApi: unknown,
+    draft: boolean,
+    search: Record<string, unknown>,
+  ): PprRequest => {
+    const path = urlPartsFor(c.req).pathname
+    const locale = i18n?.localeOf(path)
+    const params = c.params
+    const shellOrigin = options.ppr?.origin
+    const variations =
+      options.ppr?.variationsOf(mod.shellVariations, urlPartsFor(c.req).search) ?? {}
+    const shellSearch = options.ppr?.variationQuery(variations) ?? ""
+    // What a shared entry's tags read: its key's parts, never the Host or an undeclared query, which
+    // the first visitor of a key could set so a later purge misses the entry.
+    const shellUrl = (): URL => {
+      const url = new URL(shellOrigin ?? "http://shell.invalid")
+      url.pathname = path
+      url.search = shellSearch
+      return url
+    }
+    // The unbound `api`: a shell is built for every visitor, so no visitor's platform reaches it.
+    const shellContext: Omit<ShellCtx, "signal"> =
+      shellOrigin === undefined
+        ? { phase: "shell", params, locale, variations, api }
+        : { phase: "shell", params, locale, variations, api, origin: shellOrigin }
+    return {
+      routeId: route.id,
+      path,
+      locale,
+      variations,
+      request: c.req,
+      holes: boundaries.filter(isHole),
+      holeContext: { request: c.req, params, api: requestApi, env: c.env, draft, search },
+      shellContext,
+      revalidate: mod.revalidate,
+      waitUntil: c.waitUntil,
+      tags: () =>
+        mod.revalidateTags === undefined
+          ? []
+          : routeTags(mod.revalidateTags, { params, url: shellUrl() }, route.id),
+      holeTags: (hole) =>
+        hole.revalidateTags === undefined
+          ? []
+          : routeTags(hole.revalidateTags, { params, url: shellUrl() }, `${route.id}#${hole.name}`),
+      loadShell: async (signal) => shellLoader({ ...shellContext, signal }),
+      renderShellDocument: async (shellData, states) => {
+        const statics = boundaries.some((boundary) => boundary.mode === "static")
+          ? await resolveStaticBoundaries(
+              boundaries,
+              { phase: "build" },
+              options.staticBoundaryCache,
+            )
+          : undefined
+        const { chain, head } = resolveChainAndHead(
+          layouts,
+          undefined,
+          mod,
+          // A Host header is the client's to choose, so a shared shell's meta gets the configured one.
+          { data: shellData, pageData: shellData, params, origin: shellOrigin ?? "" },
+          serverLeafOf(route, mod),
+        )
+        // Nothing here reads the request beyond its pathname: no origin, search, nonce or headers.
+        const page: DocumentInput = {
+          adapter,
+          chain,
+          data: shellData,
+          head,
+          clientEntry,
+          routeId: route.id,
+          params,
+          path,
+          search: searchOfChain(
+            [...layouts.map((m) => m.searchSchema), mod.searchSchema],
+            shellSearch === "" ? "" : `?${shellSearch}`,
+          ),
+          matchChain: matchChainOf(route.layoutIds, layouts, route.id, mod),
+          hydrate: mod.hydrate !== false,
+          boundaries: { ...statics, ...states },
+          ...preloadOf(route.id),
+          ...stylesOf(route.id),
+          ...appDocumentOptions,
+          ...(locale === undefined ? {} : localeFor(locale)),
+          ...slotsFor(route.layoutIds, route.id),
+        }
+        if (mod.islandScripts !== undefined) page.islandScripts = mod.islandScripts
+        const result = await renderPageResult(page)
+        // A buffered page hands over its string: a Response round trip to read it back cost more.
+        const rendered = result.toNodeBody?.() ?? result.toResponse()
+        if (rendered.status !== 200) {
+          throw new Error(
+            `[nifra/web] ppr: the shell of "${route.id}" rendered status ${rendered.status}`,
+          )
+        }
+        if (rendered instanceof Response) return rendered.text()
+        return typeof rendered.body === "string"
+          ? rendered.body
+          : new TextDecoder().decode(rendered.body)
+      },
+    }
+  }
+
   return {
     get: (route) => {
       const is404Fallback = options.staticFallbacks?.[route.pattern] === "404"
@@ -1414,7 +1799,11 @@ export function createPageRequestExecutor<Env = unknown>(
         return slot
       }
 
-      return withResponseControls(async (c, controls) => {
+      const page = async (
+        c: PageRouteContext<Env>,
+        controls: PageResponseControls,
+      ): Promise<PageResponse> => {
+        let live = liveLoadOf?.(c.req)
         const componentRuntime = options.serverComponents
         const componentOwner = componentRuntime?.owns(route.id) === true
         let componentRequest:
@@ -1431,6 +1820,17 @@ export function createPageRequestExecutor<Env = unknown>(
         }
         const loaded = loadModule(route)
         const mod = cacheModules && !(loaded instanceof Promise) ? loaded : await loaded
+        // A document's loaders declare their keys into a seed, which the page exchanges for a grant
+        // once its socket opens, instead of loading itself again. Partially prerendered pages, whose
+        // holes settle after the shell, and server-component routes load as before.
+        const seeding =
+          live === undefined &&
+          liveSeedOf !== undefined &&
+          !componentOwner &&
+          componentRequest === undefined &&
+          (options.ppr === undefined || mod.shellLoader === undefined) &&
+          !isDataRequest(c)
+        if (seeding) live = liveSeedOf(c.req, route.id)
         const draft = await draftFlag(c.req)
         // Unpublished content is the editor's alone: whatever cache-control a loader sets, no cache keeps it.
         if (draft) controls.personalize()
@@ -1443,6 +1843,9 @@ export function createPageRequestExecutor<Env = unknown>(
         let componentState: import("../server-components/types.ts").ComponentState | undefined
         const requestApi = apiFor(c)
         let run: LayoutRun | undefined
+        let skipPage = false
+        let liveCtx: LoaderContext
+        let holeOwners: HoleOwners | undefined
         try {
           const ctx: LoaderContext = {
             params: c.params,
@@ -1453,15 +1856,26 @@ export function createPageRequestExecutor<Env = unknown>(
             draft,
             search: loaderSearch(mod.searchSchema, c.req),
             set: controls.scope(PAGE_SCOPE),
+            live: NO_LIVE,
           }
           if (route.middlewareIds !== undefined || localeGuarded(route)) {
             await runMiddleware(route, ctx, controls)
           }
+          // After middleware, before any loader: a grant issued to another viewer keeps nothing.
+          const retains = live === undefined || (await live.bind(ctx))
+          skipPage =
+            live !== undefined &&
+            retains &&
+            !componentOwner &&
+            live.retainPage &&
+            live.routeId === route.id
           run = await runLayoutChain(
             route,
             ctx,
             controls,
-            componentOwner ? undefined : retainContextOf(c),
+            componentOwner || !retains ? undefined : retainContextOf(c),
+            undefined,
+            live,
           )
           layoutModules = run.modules
           layoutRetained = run.retained
@@ -1474,8 +1888,89 @@ export function createPageRequestExecutor<Env = unknown>(
               : []
           if (boundaryDefinitions.length > 0) boundaryDescriptors(boundaryDefinitions)
           const effectiveSearch = searchChainOf(run.modules, mod, c.req)
+          const ppr = options.ppr
+          const shellLoader =
+            componentRequest === undefined && !componentOwner ? mod.shellLoader : undefined
+          let pprRequest: PprRequest | undefined
+          // How a document that renders whole gets its holes: complete, unless no shell exists yet.
+          let wholeHoles: "settled" | "deferred" = "settled"
+          if (ppr !== undefined && shellLoader !== undefined) {
+            ppr.assertRoute(route, run.modules, boundaryDefinitions)
+            pprRequest = pprRequestFor(
+              c,
+              route,
+              mod,
+              run.modules,
+              boundaryDefinitions,
+              shellLoader,
+              requestApi,
+              draft,
+              effectiveSearch,
+            )
+            const refresh = holeRefresh(c, pprRequest, live)
+            if (refresh instanceof Response) return refresh
+            pprRequest = refresh.request
+            holeOwners = refresh.owners
+            const components = options.serverComponents
+            const renderHole = components?.hosts?.(route.id) === true ? components.hole : undefined
+            if (
+              renderHole === undefined &&
+              pprRequest.holes.some((hole) => serverHoleComponent(hole.render) !== undefined)
+            ) {
+              throw new Error(
+                `[nifra/web] ppr: route "${route.id}" has a hole that shows a server component; list the component under createServerComponents({ holes }) for this route`,
+              )
+            }
+            if (renderHole !== undefined) {
+              const loaderCtx = ctx
+              pprRequest = {
+                ...pprRequest,
+                // The owner path's context, but with the hole's signal and no response to change.
+                component: (name, component, input, signal) =>
+                  renderHole.call(
+                    components,
+                    route.id,
+                    component,
+                    name,
+                    input,
+                    Object.create(
+                      c,
+                      Object.getOwnPropertyDescriptors({
+                        ...loaderCtx,
+                        search: effectiveSearch,
+                        set: SENT_CONTROLS,
+                        signal,
+                        data: undefined,
+                        layoutData: [],
+                      }),
+                    ),
+                  ),
+              }
+            }
+            // A draft is the editor's alone, so it never reads or fills the shared shell.
+            if (!draft && !isDataRequest(c)) {
+              const streamed = await ppr.stream(pprRequest, () => controls.documentHeaders())
+              if (streamed instanceof Response) return streamed
+              wholeHoles = streamed
+            }
+            // Its holes are one visitor's, so no cache may store the page they render into.
+            controls.personalize()
+          }
+          // Every PPR hole runs through the PPR server, so each has admission and its own deadline.
+          const holeStates =
+            pprRequest === undefined || ppr === undefined
+              ? undefined
+              : ppr.server.holeStates(
+                  pprRequest,
+                  !isDataRequest(c)
+                    ? wholeHoles
+                    : c.req.headers.get(PREFETCH_HEADER) === null
+                      ? "deferred"
+                      : "omitted",
+                  c.req.signal,
+                )
           const boundaryBatch =
-            boundaryDefinitions.length === 0
+            boundaryDefinitions.length === 0 || holeStates !== undefined
               ? undefined
               : startDynamicBoundaries(boundaryDefinitions, {
                   request: c.req,
@@ -1485,6 +1980,7 @@ export function createPageRequestExecutor<Env = unknown>(
                   draft,
                   search: effectiveSearch,
                   signal: c.req.signal,
+                  live: NO_LIVE,
                 } satisfies BoundaryRequestCtx)
           const staticBoundaryPromise =
             boundaryDefinitions.length === 0
@@ -1494,7 +1990,20 @@ export function createPageRequestExecutor<Env = unknown>(
                   { phase: "build" },
                   options.staticBoundaryCache,
                 )
-          const pageResult = mod.loader ? mod.loader({ ...ctx, search: effectiveSearch }) : null
+          const pageResult =
+            pprRequest !== undefined && ppr !== undefined
+              ? // A key with no shell yet must not build one through its data either.
+                draft || wholeHoles === "deferred"
+                ? pprRequest.loadShell(c.req.signal)
+                : ppr.shellData(pprRequest, c.req.signal)
+              : mod.loader === undefined || skipPage
+                ? null
+                : live === undefined
+                  ? mod.loader({ ...ctx, search: effectiveSearch })
+                  : runLiveLoader(live, `P:${route.id}`, mod.loader, {
+                      ...ctx,
+                      search: effectiveSearch,
+                    })
           const [pageData, , staticBoundaries] =
             run.pending === undefined && staticBoundaryPromise === undefined
               ? ([await pageResult, undefined, undefined] as const)
@@ -1502,7 +2011,9 @@ export function createPageRequestExecutor<Env = unknown>(
                 ? await Promise.all([pageResult, run.pending])
                 : await Promise.all([pageResult, run.pending, staticBoundaryPromise])
           data = pageData
-          layoutData = run.layoutData
+          // A gate on a PPR route runs for its redirect or refusal only. Its data reaches no response,
+          // so a soft navigation renders the layouts exactly as the shared shell did.
+          layoutData = pprRequest === undefined ? run.layoutData : undefined
           if (componentOwner) {
             for (let i = 0; i < (layoutData?.length ?? 0); i++) {
               const outcome = layoutData?.[i]
@@ -1531,8 +2042,15 @@ export function createPageRequestExecutor<Env = unknown>(
               options.nonce === undefined ? undefined : await resolveNonce(c.req, c.env),
             )
           }
-          if (boundaryBatch !== undefined) {
-            const streamed = { ...boundaryBatch.initial, ...(staticBoundaries ?? {}) }
+          if (holeStates !== undefined) {
+            // The static resolver names every boundary, leaving the dynamic ones to the holes.
+            boundaryStates = { ...staticBoundaries, ...(await holeStates) }
+          } else if (boundaryBatch !== undefined) {
+            // Each resolver returns a state for every boundary and marks the other's modes
+            // `unresolved`, so a slot takes its state from the resolver of its own mode.
+            const streamed = { ...boundaryBatch.initial }
+            for (const [name, state] of Object.entries(staticBoundaries ?? {}))
+              if (state.mode === "static") streamed[name] = state
             for (const entry of boundaryBatch.pending) {
               const initial = streamed[entry.name]
               if (initial !== undefined)
@@ -1545,6 +2063,7 @@ export function createPageRequestExecutor<Env = unknown>(
           // Inside the loader `try`: a header the response cannot carry is a loader error, rendered
           // by the same boundary as one.
           responseHeaders = controls.documentHeaders()
+          liveCtx = ctx
         } catch (err) {
           if (componentRequest !== undefined) return componentRuntime!.failure(err)
           if (isStatusSignal(err)) {
@@ -1591,9 +2110,26 @@ export function createPageRequestExecutor<Env = unknown>(
           )
           if (nested !== undefined) return nested
         }
+        const isData = isDataRequest(c)
+        const liveEnvelope =
+          live === undefined || (!isData && !seeding) || isStatusSignal(data) || isControlFlow(data)
+            ? undefined
+            : await liveEnvelopeOf(
+                live,
+                liveOwners(
+                  route,
+                  layoutModules,
+                  layoutData,
+                  layoutRetained,
+                  mod,
+                  skipPage,
+                  liveCtx,
+                ),
+                holeOwners,
+              )
         return handleDataOrDocument(
           c.req,
-          isDataRequest(c),
+          isData,
           c.env,
           route,
           c.params,
@@ -1607,8 +2143,13 @@ export function createPageRequestExecutor<Env = unknown>(
           responseHeaders,
           controls.personalized,
           componentState,
+          seeding ? undefined : liveEnvelope,
+          seeding && liveEnvelope !== undefined && !("__nifra_deferred" in liveEnvelope)
+            ? liveEnvelope
+            : undefined,
         )
-      })
+      }
+      return withResponseControls(liveLoadOf === undefined ? page : admitLive(page))
     },
 
     post: (route) =>
@@ -1659,6 +2200,7 @@ export function createPageRequestExecutor<Env = unknown>(
           draft,
           search: loaderSearch(mod.searchSchema, c.req),
           set: controls.scope(ACTION_SCOPE),
+          live: NO_LIVE,
         }
         let gated: GatedLayouts
         let result: unknown
@@ -1672,16 +2214,17 @@ export function createPageRequestExecutor<Env = unknown>(
           if (isControlFlow(err)) return err
           throw err
         }
-        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(
-                ",",
-              ),
-            }
-          : {}
+        const revalidation = isRevalidateResult(result) ? result : undefined
+        const actionResult = revalidation === undefined ? result : revalidation.data
+        const revalidateHeader: Record<string, string> =
+          revalidation === undefined
+            ? {}
+            : { [REVALIDATE_HEADER]: revalidation.__nifraRevalidate.join(",") }
+        // The write is done, whatever the action answers with (a redirect included): what it made
+        // stale is invalidated before the answer leaves.
+        const settling =
+          revalidation === undefined ? undefined : options.invalidate?.(revalidation, c.req)
+        if (settling !== undefined) await settling
         if (isControlFlow(actionResult)) return actionResult
         if (isDataRequest) {
           // Headers shape the document only, but a bad one fails here too, so a navigation and a full
@@ -1693,13 +2236,16 @@ export function createPageRequestExecutor<Env = unknown>(
               headers: { ...DATA_RESPONSE_HEADERS, ...revalidateHeader },
             })
           }
-          return new Response(ndjsonStream(forClient, deferred), {
-            headers: {
-              "content-type": "application/x-ndjson; charset=utf-8",
-              ...DATA_RESPONSE_HEADERS,
-              ...revalidateHeader,
+          return new Response(
+            ndjsonStream(forClient, deferred, undefined, c.req.signal, deferredLogOf(c.req)),
+            {
+              headers: {
+                "content-type": "application/x-ndjson; charset=utf-8",
+                ...DATA_RESPONSE_HEADERS,
+                ...revalidateHeader,
+              },
             },
-          })
+          )
         }
         if (options.serverComponents?.owns(route.id)) {
           if (options.rerenderOwnerGET === undefined) throw new Error("component_contract")
@@ -1768,6 +2314,7 @@ export function createPageRequestExecutor<Env = unknown>(
                 draft,
                 search,
                 set: controls.scope(PAGE_SCOPE),
+                live: NO_LIVE,
               })
             : null
           const [pageData] =
@@ -1837,7 +2384,7 @@ export function createPageRequestExecutor<Env = unknown>(
           },
           serverLeafOf(route, mod),
         )
-        return renderPageResult({
+        const page: DocumentInput = {
           adapter,
           chain,
           data,
@@ -1850,6 +2397,8 @@ export function createPageRequestExecutor<Env = unknown>(
           search,
           matchChain: matchChainOf(route.layoutIds, layoutModules, route.id, mod),
           hydrate: mod.hydrate !== false,
+          signal: c.req.signal,
+          logError: deferredLogOf(c.req),
           ...layoutProps,
           ...preloadOf(route.id),
           ...stylesOf(route.id),
@@ -1860,9 +2409,19 @@ export function createPageRequestExecutor<Env = unknown>(
           ...(nonce === undefined ? {} : { nonce }),
           ...cspOption,
           ...titleOption,
-        })
+          ...swapOption(c.req),
+          ...slotsFor(route.layoutIds, route.id),
+        }
+        if (mod.islandScripts !== undefined) page.islandScripts = mod.islandScripts
+        return renderPageResult(page)
       }),
 
+    matchRoute: (path) => {
+      const matched = matchManifestRoute(path)
+      const route = matched === null ? undefined : routeById.get(matched.routeId)
+      return route === undefined ? null : { routeId: route.id, layoutIds: route.layoutIds }
+    },
+
     fallback: withResponseControls(async (c, controls) => {
       const match = matchNotFoundScope?.(pathOf(c.req)) ?? null
       const target = match === null ? undefined : notFoundTargets[Number(match.routeId)]
@@ -1887,6 +2446,7 @@ export function createPageRequestExecutor<Env = unknown>(
           draft,
           search: loaderSearch(mod.searchSchema, c.req),
           set: controls.scope(PAGE_SCOPE),
+          live: NO_LIVE,
         }
         if (target.route.middlewareIds !== undefined) {
           await runMiddleware(target.route, ctx, controls)