@nifrajs/web 5.5.1 → 5.6.0

package/dist/internal/page-execution.js

@@ -5,19 +5,124 @@ import { DEFAULT_CSS_LOADING, normalizeCssLoading } from "../css-contract.js";
 import { defer, ndjsonStream, prepareDeferred } from "../deferred.js";
 import { isDraftEnabled } from "../draft.js";
 import { routeTags } from "../isr.js";
-import { createMatcher, DATA_HEADER, NAV_FROM_HEADER, REDIRECT_HEADER, RETAIN_HEADER, REVALIDATE_HEADER, STATUS_HEADER, } from "../router.js";
+import { SWAP_HEADER } from "../render-seam.js";
+import { createMatcher, DATA_HEADER, HOLE_FILL_HEADER, KEEP_HOLES_HEADER, NAV_FROM_HEADER, PREFETCH_HEADER, REDIRECT_HEADER, RETAIN_HEADER, REVALIDATE_HEADER, STATUS_HEADER, } from "../router.js";
 import { searchOf, searchOfChain } from "../search.js";
 import { mergeHeads, resolveChainMeta } from "./head-merge.js";
+import { keepAliveTable, slotDepths } from "./keep-alive-table.js";
+import { holeOwner, } from "./live-contract.js";
 import { prepareModules } from "./module-preparation.js";
-import { EMPTY_RETAIN, isControlFlow, isResponseResult, isStatusSignal, layoutErrorId, notFound, redirect, renderPageResult, STATUS_SIGNAL, STATUS_TEXT, scopeParams, tagLayoutError, withDuplicateInstanceHint, } from "./render-document.js";
+import { isHole, serverHoleComponent, } from "./ppr/contract.js";
+import { EMPTY_RETAIN, isControlFlow, isResponseResult, isRevalidateResult, isStatusSignal, layoutErrorId, notFound, redirect, renderPageResult, STATUS_SIGNAL, STATUS_TEXT, scopeParams, tagLayoutError, withDuplicateInstanceHint, } from "./render-document.js";
 import { originFor, urlPartsFor } from "./request-url.js";
 import { ACTION_SCOPE, DATA_RESPONSE_HEADERS, MIDDLEWARE_SCOPE, PAGE_SCOPE, PageResponseControls, PRIVATE_NO_STORE, PRIVATE_PAGE_HEADERS, privateOutcome, varyOnDataHeader, } from "./response-controls.js";
 /** 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) {
+    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) {
+    const swapSlot = swapSlotOf(req);
+    return swapSlot === undefined ? {} : { swapSlot };
+}
+const headerOf = (c, name) => c.header !== undefined ? c.header(name) : c.req.headers.get(name);
 function isDataRequest(c) {
-    return (c.header !== undefined ? c.header(DATA_HEADER) : c.req.headers.get(DATA_HEADER)) !== null;
+    return headerOf(c, DATA_HEADER) !== null;
+}
+/**
+ * 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, request, live) {
+    if (!isDataRequest(c))
+        return { request };
+    const declared = new Set(request.holes.map((hole) => hole.name));
+    const namesOf = (header) => {
+        const value = headerOf(c, header);
+        const names = new Set();
+        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 = {
+        ...request,
+        ...(fill.size === 0 ? {} : { fill }),
+        ...(kept.size === 0 ? {} : { kept }),
+    };
+    if (live === undefined)
+        return { request: refreshed };
+    const routeId = request.routeId;
+    let finish = () => { };
+    const loaded = new Promise((resolve) => {
+        finish = resolve;
+    });
+    const 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;
+/** `ctx.live` outside a live load: keys are declared for nobody. */
+const NO_LIVE = () => { };
+const headersSent = () => {
+    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 = 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, owners, holes) => 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, owner, loader, ctx) => {
+    let value;
+    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) {
     if ((typeof api !== "object" && typeof api !== "function") || api === null)
@@ -140,12 +245,13 @@ export function createPageRequestExecutor(options) {
     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) => {
+    const localeFor = (key) => {
         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) => 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) => {
         if (i18n === undefined)
@@ -158,6 +264,48 @@ export function createPageRequestExecutor(options) {
     };
     const matchManifestRoute = createMatcher(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;
+    /** A live load holds one admission slot from before its middleware until its body is complete. */
+    const admitLive = (run) => async (c, controls) => {
+        const live = liveLoadOf?.(c.req);
+        if (live === undefined)
+            return run(c, controls);
+        const refused = live.admit();
+        if (refused !== undefined)
+            return refused;
+        let outcome;
+        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, modules, layoutData, retained, mod, skipPage, ctx) => {
+        const fresh = [];
+        const kept = [];
+        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.
     // Param names are indexed by position, so two directories that name one segment differently share
@@ -197,6 +345,16 @@ export function createPageRequestExecutor(options) {
     const draftFlag = (req) => options.draftSecret === undefined
         ? 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, routeId) => {
+        // 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) => {
         const chunks = options.routePreload?.[id];
         return chunks ? { preload: chunks } : {};
@@ -274,7 +432,7 @@ export function createPageRequestExecutor(options) {
      * Run layout loaders, awaiting gates before starting the page loader and retaining only safe data.
      * `gated` carries gates that already ran for this request, so none runs twice.
      */
-    const runLayoutChain = async (route, ctx, controls, retain, gated) => {
+    const runLayoutChain = async (route, ctx, controls, retain, gated, live) => {
         if (route.layoutIds.length === 0)
             return emptyLayoutRun;
         const modules = gated?.modules ?? (await loadLayoutModules(route));
@@ -308,14 +466,19 @@ export function createPageRequestExecutor(options) {
                 params: scopeParams(ctx.params, route.layoutParams?.[i]),
                 set: controls.scope(i),
             };
+            const layoutId = route.layoutIds[i];
             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];
             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")) {
@@ -512,6 +675,11 @@ export function createPageRequestExecutor(options) {
         handles: [...layoutModules.map((layout) => layout.handle), page.handle],
     });
     const dirOfId = (id, suffix) => 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) => {
+        const log = options.logBoundaryError;
+        return log === undefined ? undefined : (error) => log(error, req);
+    };
     const boundaryFor = (route, err) => {
         const ids = route.errorIds ?? [];
         const failing = layoutErrorId(err);
@@ -568,6 +736,8 @@ export function createPageRequestExecutor(options) {
                 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 }),
@@ -645,6 +815,7 @@ export function createPageRequestExecutor(options) {
                 draft,
                 search: loaderSearch(page.searchSchema, c.req),
                 set: controls.scope(PAGE_SCOPE),
+                live: NO_LIVE,
             };
             if (route.middlewareIds !== undefined)
                 await runMiddleware(route, ctx, controls);
@@ -689,6 +860,8 @@ export function createPageRequestExecutor(options) {
             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 } : {}),
@@ -703,6 +876,7 @@ export function createPageRequestExecutor(options) {
             ...copyOption,
             ...localeOption(req),
             ...titleOption,
+            ...slotsFor(layoutIds, routeId),
         };
         if (chain === undefined)
             return renderPageResult(statusPage);
@@ -748,7 +922,7 @@ export function createPageRequestExecutor(options) {
             // A faulty reporter must never break error rendering.
         }
     };
-    const handleDataOrDocument = async (req, isData, env, route, params, mod, data, layoutData, layoutModules, layoutRetained, boundaryStates, assemblyCache, responseHeaders, personalized, serverComponents) => {
+    const handleDataOrDocument = async (req, isData, env, route, params, mod, data, layoutData, layoutModules, layoutRetained, boundaryStates, assemblyCache, responseHeaders, personalized, serverComponents, live) => {
         // Every layout loader settled before the page rendered, so a status or error page can reuse them.
         const settled = async (_page, count) => settledLayouts(layoutModules, layoutData, count);
         if (isStatusSignal(data))
@@ -770,7 +944,14 @@ export function createPageRequestExecutor(options) {
                 ...deferred,
                 ...(boundarySplit === undefined ? [] : boundarySplit.deferred),
             ];
-            const payload = layoutData === undefined && boundarySplit === undefined && serverComponents === undefined
+            // 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 &&
+                live === undefined
                 ? pageSplit.forClient
                 : {
                     v: 1,
@@ -779,11 +960,12 @@ export function createPageRequestExecutor(options) {
                     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), {
+            return new Response(ndjsonStream(payload, allDeferred, undefined, req.signal, deferredLogOf(req)), {
                 headers: {
                     "content-type": "application/x-ndjson; charset=utf-8",
                     ...DATA_RESPONSE_HEADERS,
@@ -813,6 +995,8 @@ export function createPageRequestExecutor(options) {
                 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,
@@ -822,6 +1006,11 @@ export function createPageRequestExecutor(options) {
                 page.serverComponents = serverComponents;
             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)
@@ -919,6 +1108,8 @@ export function createPageRequestExecutor(options) {
             matchChain: matchChainOf(page.layoutIds, layoutModules, id, mod),
             status: 404,
             hydrate: false,
+            signal: req.signal,
+            logError: deferredLogOf(req),
             ...localeOption(req),
             ...(layoutData !== undefined ? { layoutData } : {}),
             ...stylesOf(id),
@@ -984,6 +1175,86 @@ export function createPageRequestExecutor(options) {
             controls.seal();
         }
     };
+    const pprRequestFor = (c, route, mod, layouts, boundaries, shellLoader, requestApi, draft, search) => {
+        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 = () => {
+            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 = 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 = {
+                    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";
@@ -1013,7 +1284,8 @@ export function createPageRequestExecutor(options) {
                 }
                 return slot;
             };
-            return withResponseControls(async (c, controls) => {
+            const page = async (c, controls) => {
+                const live = liveLoadOf?.(c.req);
                 const componentRuntime = options.serverComponents;
                 const componentOwner = componentRuntime?.owns(route.id) === true;
                 let componentRequest;
@@ -1043,6 +1315,9 @@ export function createPageRequestExecutor(options) {
                 let componentState;
                 const requestApi = apiFor(c);
                 let run;
+                let skipPage = false;
+                let liveCtx;
+                let holeOwners;
                 try {
                     const ctx = {
                         params: c.params,
@@ -1053,11 +1328,20 @@ export function createPageRequestExecutor(options) {
                         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);
                     }
-                    run = await runLayoutChain(route, ctx, controls, componentOwner ? undefined : retainContextOf(c));
+                    // 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 || !retains ? undefined : retainContextOf(c), undefined, live);
                     layoutModules = run.modules;
                     layoutRetained = run.retained;
                     const boundaryDefinitions = componentRequest === undefined
@@ -1069,7 +1353,59 @@ export function createPageRequestExecutor(options) {
                     if (boundaryDefinitions.length > 0)
                         boundaryDescriptors(boundaryDefinitions);
                     const effectiveSearch = searchChainOf(run.modules, mod, c.req);
-                    const boundaryBatch = boundaryDefinitions.length === 0
+                    const ppr = options.ppr;
+                    const shellLoader = componentRequest === undefined && !componentOwner ? mod.shellLoader : undefined;
+                    let pprRequest;
+                    // How a document that renders whole gets its holes: complete, unless no shell exists yet.
+                    let wholeHoles = "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 || holeStates !== undefined
                         ? undefined
                         : startDynamicBoundaries(boundaryDefinitions, {
                             request: c.req,
@@ -1079,18 +1415,33 @@ export function createPageRequestExecutor(options) {
                             draft,
                             search: effectiveSearch,
                             signal: c.req.signal,
+                            live: NO_LIVE,
                         });
                     const staticBoundaryPromise = boundaryDefinitions.length === 0
                         ? undefined
                         : resolveStaticBoundaries(boundaryDefinitions, { 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]
                         : staticBoundaryPromise === undefined
                             ? 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];
@@ -1110,8 +1461,17 @@ export function createPageRequestExecutor(options) {
                         }));
                         componentState = await componentRuntime.execute(route.id, componentContext, componentRequest, 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)
@@ -1125,6 +1485,7 @@ export function createPageRequestExecutor(options) {
                     // 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)
@@ -1148,8 +1509,13 @@ export function createPageRequestExecutor(options) {
                     if (nested !== undefined)
                         return nested;
                 }
-                return handleDataOrDocument(c.req, isDataRequest(c), c.env, route, c.params, mod, data, layoutData, layoutModules ?? (await loadLayoutModules(route)), layoutRetained, boundaryStates, layoutModules === undefined ? undefined : assemblyCacheFor(mod, layoutModules, c.req), responseHeaders, controls.personalized, componentState);
-            });
+                const isData = isDataRequest(c);
+                const liveEnvelope = live === undefined || !isData || isStatusSignal(data) || isControlFlow(data)
+                    ? undefined
+                    : await liveEnvelopeOf(live, liveOwners(route, layoutModules, layoutData, layoutRetained, mod, skipPage, liveCtx), holeOwners);
+                return handleDataOrDocument(c.req, isData, c.env, route, c.params, mod, data, layoutData, layoutModules ?? (await loadLayoutModules(route)), layoutRetained, boundaryStates, layoutModules === undefined ? undefined : assemblyCacheFor(mod, layoutModules, c.req), responseHeaders, controls.personalized, componentState, liveEnvelope);
+            };
+            return withResponseControls(liveLoadOf === undefined ? page : admitLive(page));
         },
         post: (route) => withResponseControls(async (c, controls) => {
             const loaded = loadModule(route);
@@ -1195,6 +1561,7 @@ export function createPageRequestExecutor(options) {
                 draft,
                 search: loaderSearch(mod.searchSchema, c.req),
                 set: controls.scope(ACTION_SCOPE),
+                live: NO_LIVE,
             };
             let gated;
             let result;
@@ -1210,13 +1577,16 @@ export function createPageRequestExecutor(options) {
                     return err;
                 throw err;
             }
-            const isRevalidate = result !== null && typeof result === "object" && "__nifraRevalidate" in result;
-            const actionResult = isRevalidate ? result.data : result;
-            const revalidateHeader = isRevalidate
-                ? {
-                    [REVALIDATE_HEADER]: result.__nifraRevalidate.join(","),
-                }
-                : {};
+            const revalidation = isRevalidateResult(result) ? result : undefined;
+            const actionResult = revalidation === undefined ? result : revalidation.data;
+            const revalidateHeader = 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) {
@@ -1229,7 +1599,7 @@ export function createPageRequestExecutor(options) {
                         headers: { ...DATA_RESPONSE_HEADERS, ...revalidateHeader },
                     });
                 }
-                return new Response(ndjsonStream(forClient, deferred), {
+                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,
@@ -1308,6 +1678,7 @@ export function createPageRequestExecutor(options) {
                         draft,
                         search,
                         set: controls.scope(PAGE_SCOPE),
+                        live: NO_LIVE,
                     })
                     : null;
                 const [pageData] = run.pending === undefined
@@ -1344,7 +1715,7 @@ export function createPageRequestExecutor(options) {
                 origin: originFor(c.req),
                 ...(nonce === undefined ? {} : { nonce }),
             }, serverLeafOf(route, mod));
-            return renderPageResult({
+            const page = {
                 adapter,
                 chain,
                 data,
@@ -1357,6 +1728,8 @@ export function createPageRequestExecutor(options) {
                 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),
@@ -1367,8 +1740,18 @@ export function createPageRequestExecutor(options) {
                 ...(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)];
@@ -1394,6 +1777,7 @@ export function createPageRequestExecutor(options) {
                     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);