@nextwebwg/htmlkit 1.0.0-alpha.52 → 1.0.0-alpha.54

package/README.md

@@ -1,9 +1,10 @@
 # HTMLKit
 
 HTMLKit (`@nextwebwg/htmlkit`) builds applications with HTML Next components. It provides routes,
-layouts, server loaders, browser delivery, and development tools. The first production adapter
-generates static pages; [the server-rendering design](./docs/server-rendering.md) preserves a path
-to request-time rendering.
+layouts, server loaders, endpoints, middleware, browser delivery, and development tools. A build
+prerenders pages for any static host and writes a request server for pages that render on each
+request, which `htmlkit start` runs on Node and Deno and Bun run through its `fetch`.
+[The server-rendering design](./docs/server-rendering.md) records how requests are answered.
 
 Use Node `>=22.22.2 <23 || >=24.15 <25`. Install `@nextwebwg/htmlkit` and add its commands to your
 `package.json` scripts:
@@ -13,15 +14,17 @@ Use Node `>=22.22.2 <23 || >=24.15 <25`. Install `@nextwebwg/htmlkit` and add it
   "scripts": {
     "dev": "htmlkit dev",
     "build": "htmlkit build",
-    "preview": "htmlkit preview"
+    "preview": "htmlkit preview",
+    "start": "htmlkit start"
   }
 }
 ```
 
-Then run `pnpm dev`, `pnpm build`, or `pnpm preview` (`npm run dev` and the others work too).
+Then run `pnpm dev`, `pnpm build`, `pnpm preview`, or `pnpm start` (`npm run dev` and the others work too).
 
 **Guide:** [nextwebwg.org/htmlkit](https://nextwebwg.org/htmlkit/) covers pages and routing,
-loading data, navigation, moving between pages, and configuration. Its source is
+loading data, endpoints and middleware, navigation, moving between pages, deployment, and
+configuration. Its source is
 [`docs/guide`](./docs/guide/) in this package.
 [The client-navigation design](./docs/client-navigation.md) records how pages swap in place.
 

package/dist/application.d.ts

@@ -1,12 +1,26 @@
+import { type ComponentDefinition } from "@nextwebwg/html-next";
 import { type ViteDevServer } from "vite";
 import { type PageAssets } from "./document.js";
-import type { Application, ApplicationOptions, RenderedHead, RenderedPage } from "./types.js";
+import { type RenderLayer } from "./server.js";
+import type { Application, ApplicationOptions, ApplicationRoute, BrowserDefinition, RenderedHead, RenderedPage } from "./types.js";
 export declare function headScripts(options: ApplicationOptions, root: string): Promise<readonly string[]>;
 export declare function notFoundPage(scripts: readonly string[]): {
     head: RenderedHead;
     body: string;
     html: string;
 };
+/** A route's components, ready to render: its layers, every component they use, and their browser delivery. */
+export interface RouteGraph {
+    readonly layers: readonly RenderLayer[];
+    readonly definitions: readonly ComponentDefinition[];
+    readonly components: readonly BrowserDefinition[];
+}
+/** The application, plus what a build reads from it: each route's component graph and the concrete page URLs. */
+export declare function createApplicationInternals(input?: ApplicationOptions, moduleServer?: ViteDevServer, assets?: (page: RenderedPage) => PageAssets): Promise<{
+    application: Application;
+    graph: (route: ApplicationRoute) => Promise<RouteGraph>;
+    catalog: () => Promise<ReadonlyMap<string, ApplicationRoute>>;
+}>;
 /** assets supplies a serving adapter's browser modules and stylesheets for fetch(). */
 export declare function createApplication(input?: ApplicationOptions, moduleServer?: ViteDevServer, assets?: (page: RenderedPage) => PageAssets): Promise<Application>;
 //# sourceMappingURL=application.d.ts.map

package/dist/application.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"application.d.ts","sourceRoot":"","sources":["../src/application.ts"],"names":[],"mappings":"AAQA,OAAO,EAA0C,KAAK,aAAa,EAAE,MAAM,MAAM,CAAC;AAGlF,OAAO,EAAoE,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAIlH,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAkI,YAAY,EAAiB,YAAY,EAA4B,MAAM,YAAY,CAAC;AAgDvQ,wBAAsB,WAAW,CAAC,OAAO,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAYvG;AAGD,wBAAgB,YAAY,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE;;;;EAItD;AAED,uFAAuF;AACvF,wBAAsB,iBAAiB,CAAC,KAAK,GAAE,kBAAuB,EAAE,YAAY,CAAC,EAAE,aAAa,EAClG,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAyUnE"}
+{"version":3,"file":"application.d.ts","sourceRoot":"","sources":["../src/application.ts"],"names":[],"mappings":"AAKA,OAAO,EAA0D,KAAK,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAExH,OAAO,EAA0C,KAAK,aAAa,EAAE,MAAM,MAAM,CAAC;AAGlF,OAAO,EAA8B,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAG5E,OAAO,EAAiH,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAC9J,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,iBAAiB,EAA8C,YAAY,EAAE,YAAY,EAC9H,MAAM,YAAY,CAAC;AAoB/C,wBAAsB,WAAW,CAAC,OAAO,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAYvG;AAGD,wBAAgB,YAAY,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE;;;;EAItD;AAED,+GAA+G;AAC/G,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;IACxC,QAAQ,CAAC,WAAW,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACrD,QAAQ,CAAC,UAAU,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACnD;AAED,iHAAiH;AACjH,wBAAsB,0BAA0B,CAAC,KAAK,GAAE,kBAAuB,EAAE,YAAY,CAAC,EAAE,aAAa,EAC3G,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,UAAU;;mBAyEf,gBAAgB,KAAG,OAAO,CAAC,UAAU,CAAC;;GAiJnE;AAED,uFAAuF;AACvF,wBAAsB,iBAAiB,CAAC,KAAK,GAAE,kBAAuB,EAAE,YAAY,CAAC,EAAE,aAAa,EAClG,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAEnE"}

package/dist/application.js

@@ -2,47 +2,14 @@ import { dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
-import { compileComponentStylesForBuild, parseComponentResource, serializePropTarget, serializeTypedValue } from "@nextwebwg/html-next";
+import { compileComponentStylesForBuild, parseComponentResource } from "@nextwebwg/html-next";
 import { loadNodeComponents } from "@nextwebwg/html-next/node-loader";
-import { renderComponents } from "@nextwebwg/html-next/server";
 import { createServer, isRunnableDevEnvironment } from "vite";
 import { configure, HtmlKitError, rootAlias, withPlugins } from "./config.js";
-import { documentHTML, escapeHTML, pagePayload, payloadPath, redirectPage } from "./document.js";
-import { breadth, discover, matchRoute, parameter, redirectLocation, redirectStatuses, redirectTable, validSegment } from "./routes.js";
+import { documentHTML, redirectPage } from "./document.js";
+import { breadth, discover, discoverServerFiles, matchRoute, parameter, redirectTable, validSegment } from "./routes.js";
 import { applicationResource, pageDefinition } from "./resource.js";
-import { renderHead } from "./head.js";
-/** What a loader's redirect() throws, so render answers with the redirect instead of the page. */
-class Redirect {
-    location;
-    status;
-    constructor(location, status) {
-        this.location = location;
-        this.status = status;
-    }
-}
-/** A loader's props as invocation attributes, in their HTML form, defaults included. */
-function invocationAttributes(definition, result) {
-    const props = result.props ?? {};
-    for (const name of Object.keys(props)) {
-        if (!Object.hasOwn(definition.contract.props, name))
-            throw new HtmlKitError(`Undeclared prop ${name}.`, definition.source.file);
-    }
-    const attributes = {};
-    for (const [name, contract] of Object.entries(definition.contract.props)) {
-        serializePropTarget(contract, props[name], name, definition.contract.tag);
-        // The contract target describes lowering onto native DOM. Invocation attributes carry
-        // the public prop name; writing the target name here silently loses remapped props.
-        const provided = props[name] === undefined ? contract.default : props[name];
-        const value = provided == null ? null : serializeTypedValue(provided, contract.type);
-        if (value !== null)
-            attributes[name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase()] = value;
-    }
-    return attributes;
-}
-/** The browser builds the same invocation from a page payload (client.ts). */
-function invocation(tag, attributes, id, child, nested) {
-    return `<${tag} id="${id}"${nested ? ' slot="page"' : ""}${Object.entries(attributes).map(([name, value]) => ` ${name}="${escapeHTML(value)}"`).join("")}>${child}</${tag}>`;
-}
+import { createNavigation, failurePage, pageResponse, renderRoute, respond, serverFailure } from "./server.js";
 // Built-in components need no link: a resource that uses one gets it added after its content, so
 // diagnostics keep their line numbers. The import map below resolves it from this package.
 const builtins = [["hk-nav", "@nextwebwg/htmlkit/components/nav.html"], ["hk-breadcrumbs", "@nextwebwg/htmlkit/components/breadcrumbs.html"],
@@ -79,12 +46,15 @@ export function notFoundPage(scripts) {
     const body = "<main><h1>Page not found</h1></main>";
     return { head, body, html: documentHTML(body, head) };
 }
-/** assets supplies a serving adapter's browser modules and stylesheets for fetch(). */
-export async function createApplication(input = {}, moduleServer, assets) {
+/** The application, plus what a build reads from it: each route's component graph and the concrete page URLs. */
+export async function createApplicationInternals(input = {}, moduleServer, assets) {
     const options = await withPlugins(input);
     const config = configure(options);
     const redirects = redirectTable(config.base, options.redirects);
-    const { routes, notFound: notFoundRoute, sources, files, folderLabels, watched } = await discover(config.root, { ...options, base: config.base });
+    const { routes, notFound: notFoundRoute, error: errorRoute, sources, files, watched } = await discover(config.root, { ...options, base: config.base });
+    // Alias pages name their own URL canonical, absolute when the site sets its origin.
+    const canonicalOrigin = options.origin === undefined ? "" : config.origin;
+    const { endpoints, middleware } = await discoverServerFiles(config.root);
     // A dynamic page's entries are checked the same way when they are listed.
     const shadowed = routes.find(route => route.params.length === 0 && redirects.has(config.base + route.pattern.slice(1)));
     if (shadowed !== undefined)
@@ -112,8 +82,10 @@ export async function createApplication(input = {}, moduleServer, assets) {
         const paths = new Map();
         for (const route of routes) {
             const loaded = await module(route);
+            // A server-rendered dynamic page renders whatever its URL names, so it needs no entries().
             if (route.params.length > 0 && typeof loaded.entries !== "function") {
-                unenumerated.push(route);
+                if (route.render !== "server")
+                    unenumerated.push(route);
                 continue;
             }
             const entries = loaded.entries === undefined ? [{}] : await loaded.entries();
@@ -152,304 +124,173 @@ export async function createApplication(input = {}, moduleServer, assets) {
         }
         return paths;
     })();
-    const checkedFrom = (from = "/") => {
-        if (!/^\/(?:[^/]+\/)*$/.test(from) || from.includes("[") || from.includes("?") || from.includes("#")) {
-            throw new HtmlKitError("Navigation from requires a concrete application-relative directory prefix.", from);
-        }
-        return from;
-    };
-    const item = (href, route, depth, current) => Object.freeze({
-        href, label: route.label ?? decodeURIComponent(href.slice(config.base.length).split("/").filter(Boolean).at(-1) ?? "Home"),
-        current: href === current ? "page" : "false", depth, pageName: route.pageName,
-        ...(route.groups === undefined ? {} : { group: route.groups.at(-1).label })
-    });
-    // A page's place in the file tree: each URL segment, with its (group) folders where they sit.
-    // depth is the URL segments above the element: a segment's index, or a group's depth.
-    // A segment's label is a plugin's folder() label for the folder it names; a catch-all's segments name none.
-    const treePath = (href, route) => {
-        const path = href.slice(config.base.length).split("/").filter(Boolean)
-            .map((name, i) => {
-            const label = i < route.segments.length && breadth(route.segments[i]) < 2 ? folderLabels.get(route.segments.slice(0, i + 1).join("/")) : undefined;
-            return { name, rank: route.order?.[i] ?? null, depth: i, ...(label === undefined ? {} : { label }) };
-        });
-        // Deepest first, so each insertion index is still a count of URL segments.
-        for (const group of (route.groups ?? []).toReversed())
-            path.splice(group.depth, 0, { name: group.label, rank: group.order, depth: group.depth, group: true });
-        return path;
-    };
-    const navigation = async (query = {}) => {
-        const from = checkedFrom(query.from);
-        const prefix = config.base + from.slice(1);
-        const depth = from.split("/").filter(Boolean).length;
-        // Hidden pages and alias routes stay routable but out of navigation.
-        const items = [...await concreteRoutes()].filter(([path, route]) => path.startsWith(prefix) && !route.hidden && route.canonical === undefined);
-        const paths = new Map(items.map(([href, route]) => [href, treePath(href, route)]));
-        items.sort(([a], [b]) => {
-            const aParts = paths.get(a);
-            const bParts = paths.get(b);
-            for (let i = 0; i < Math.min(aParts.length, bParts.length); i++) {
-                const aRank = aParts[i].rank;
-                const bRank = bParts[i].rank;
-                if (aRank !== bRank) {
-                    if (aRank === null)
-                        return 1;
-                    if (bRank === null)
-                        return -1;
-                    const difference = BigInt(aRank) - BigInt(bRank);
-                    if (difference !== 0n)
-                        return difference < 0n ? -1 : 1;
+    const navigation = createNavigation(config.base, routes, concreteRoutes);
+    // Vite owns module caching and dependency invalidation. Per-render results never enter
+    // a shared cache; HTML Next owns the DOM worker and declarative component semantics.
+    const graph = async (route) => {
+        const layers = [...route.layouts, route];
+        const packages = new Map();
+        const resources = new Map();
+        const layerURLs = new Set(layers.map(layer => pathToFileURL(layer.component).href));
+        const resolveCSS = server.config.createResolver({ extensions: [".css"], mainFields: ["style"], conditions: ["style", "development|production"], preferRelative: true, tryIndex: false });
+        const loaded = await loadNodeComponents(layers.map(layer => pathToFileURL(layer.component).href), {
+            readStylesheet: async (url) => ({ url, source: await readFile(fileURLToPath(url), "utf8") }),
+            resolveStylesheet: async (specifier, parentURL) => {
+                const resolved = await resolveCSS(specifier, fileURLToPath(parentURL));
+                return resolved === undefined ? undefined
+                    : pathToFileURL(resolved.replace(/[?#].*$/, "")).href + (/[?#].*$/.exec(resolved)?.[0] ?? "");
+            },
+            stylesheetAssetURL: url => url.startsWith("file:") ? `/@fs/${fileURLToPath(url)}${new URL(url).search}${new URL(url).hash}` : url,
+            // The graph resolver is synchronous. Prepare its bare imports while asynchronously
+            // reading each carrier, using Vite's ESM resolution from the consuming application.
+            importMap: map,
+            readComponent: async (url) => {
+                let source = sources.get(fileURLToPath(url)) ?? await readFile(fileURLToPath(url), "utf8");
+                for (const [tag, href] of builtins)
+                    if (new RegExp(`<${tag}[\\s/>]`).test(source))
+                        source += `\n<link rel="component" href="${href}">`;
+                const parsed = layerURLs.has(url) ? applicationResource(source, url) : parseComponentResource(source, url);
+                if ("configuration" in parsed)
+                    resources.set(url, parsed);
+                const imports = [...parsed.dependencies, ...parsed.definitions.flatMap(definition => definition.controller === undefined ? [] : [definition.controller])];
+                for (const specifier of imports) {
+                    if (/^(?:[A-Za-z][A-Za-z\d+.-]*:|\/|\.\.?\/)/.test(specifier) || Object.keys(map.imports).some(key => specifier.startsWith(key)))
+                        continue;
+                    const resolved = await server.environments.client.pluginContainer.resolveId(specifier, fileURLToPath(url));
+                    if (resolved === null || resolved.external)
+                        throw new HtmlKitError(`Cannot resolve component import ${specifier}.`, url);
+                    packages.set(`${url}\0${specifier}`, packageResource(resolved.id));
                 }
-                const difference = aParts[i].name.localeCompare(bParts[i].name);
-                if (difference !== 0)
-                    return difference;
-            }
-            return aParts.length - bParts.length || a.localeCompare(b);
+                return { url, source };
+            },
+            resolvePackage: (specifier, parentURL) => {
+                const resolved = packages.get(`${parentURL}\0${specifier}`);
+                if (resolved === undefined)
+                    throw new HtmlKitError(`Cannot resolve component import ${specifier}.`, parentURL);
+                return resolved;
+            },
         });
-        return Object.freeze(items.map(([href, route]) => item(href, route, href.slice(config.base.length).split("/").filter(Boolean).length - depth, query.current)));
-    };
-    // Each existing page from `from` down to the current one, by URL; the current page is included even when hidden.
-    const breadcrumbs = async (query = {}) => {
-        const from = checkedFrom(query.from);
-        const current = query.current;
-        if (current === undefined || !current.startsWith(config.base + from.slice(1)))
-            return Object.freeze([]);
-        const paths = await concreteRoutes();
-        const parts = current.slice(config.base.length).split("/").filter(Boolean);
-        const start = from.split("/").filter(Boolean).length;
-        const trail = [];
-        for (let i = start; i <= parts.length; i++) {
-            const href = config.base + parts.slice(0, i).map(part => part + "/").join("");
-            // The page being rendered exists even when no entries() lists it, as for a dynamic page at request time.
-            const route = paths.get(href) ?? (i === parts.length ? matchRoute(routes, href, config.base)?.route : undefined);
-            if (route !== undefined && route.canonical === undefined)
-                trail.push(item(href, route, i - start, current));
+        const definitions = layers.map(layer => {
+            if (layer === route)
+                return pageDefinition(resources.get(pathToFileURL(layer.component).href), layer.component);
+            const roots = loaded.roots.filter(id => loaded.nodes.get(id).url === pathToFileURL(layer.component).href);
+            if (roots.length !== 1)
+                throw new HtmlKitError("A page or layout must declare exactly one root component.", layer.component);
+            return loaded.nodes.get(roots[0]).definition;
+        });
+        if (definitions.at(-1).contract.tag !== route.pageName) {
+            throw new HtmlKitError("Page component name changed; rediscover routes before rendering.", route.component);
         }
-        return Object.freeze(trail);
+        for (const definition of definitions.slice(0, -1)) {
+            if (!definition.slots?.some(slot => slot.name === "page"))
+                throw new HtmlKitError('Layout requires a slot named "page".', definition.source.file);
+        }
+        const components = [...loaded.nodes.values()].map(node => ({ definition: node.definition,
+            styles: compileComponentStylesForBuild(node.definition.css, node.definition),
+            ...(node.controller === undefined ? {} : { controller: fileURLToPath(node.controller.url) }) }));
+        return { components, definitions: components.map(component => component.definition), layers: layers.map((layer, i) => ({ definition: definitions[i],
+                metadata: resources.get(pathToFileURL(layer.component).href).components.get(definitions[i].contract.tag), module: () => module(layer), origin: origin(layer) })) };
     };
-    // navigation()'s pages, which come in tree order, nested under the folders and groups below `from`.
-    const navigationTree = async (query = {}) => {
-        const items = await navigation(query);
-        const paths = await concreteRoutes();
-        const fromDepth = checkedFrom(query.from).split("/").filter(Boolean).length;
-        const top = [];
-        const nodes = new Map();
-        for (const item of items) {
-            const route = paths.get(item.href);
-            let siblings = top;
-            let key = "";
-            let node;
-            // The page's own node is the last element below `from`; `from`'s index page is a top node of its own.
-            for (const element of treePath(item.href, route).filter(element => element.depth >= fromDepth)) {
-                key += `${element.group ? "(" : "/"}${element.name}\0`;
-                node = nodes.get(key);
-                if (node === undefined) {
-                    node = { label: element.label ?? (element.group ? element.name : decodeURIComponent(element.name)), order: element.rank, children: [],
-                        ...(element.label === undefined ? {} : { folder: element.label }) };
-                    nodes.set(key, node);
-                    siblings.push(node);
-                }
-                siblings = node.children;
-            }
-            if (node === undefined) {
-                node = { label: item.label, order: null, children: [] };
-                top.unshift(node);
-            }
-            node.item = item;
-            node.route = route;
+    const builtinNotFound = (pathname) => ({ status: 404, pathname, ...notFoundPage(scripts), css: "", components: [], layers: [] });
+    const redirected = (pathname, location, status, headers) => ({ status, pathname, location, ...redirectPage(location), css: "", components: [], layers: [], ...(headers === undefined ? {} : { headers }) });
+    const builtinFailure = (pathname) => ({ pathname, ...failurePage(serverFailure, scripts), css: "", components: [], layers: [] });
+    // A matched route; without one, the not-found page, or for a failure the error page, through its layouts.
+    // request makes it a request-time render.
+    const renderPage = async (matched, url, request, signal, failure) => {
+        const fallback = failure === undefined ? notFoundRoute : errorRoute;
+        if (matched === undefined && fallback === undefined)
+            return failure === undefined ? builtinNotFound(url.pathname) : builtinFailure(url.pathname);
+        const { route, params } = matched ?? { route: fallback, params: {} };
+        const { layers, definitions, components } = await graph(route);
+        const rendered = await renderRoute({ base: config.base, canonicalOrigin, route, params, url, ...(request === undefined ? {} : { request }), signal, layers,
+            definitions, scripts, navigation, ...(failure === undefined ? {} : { failure }) });
+        if (rendered.kind === "redirect")
+            return redirected(url.pathname, rendered.location, rendered.status, rendered.headers);
+        if (rendered.kind === "notFound") {
+            // The not-found and error pages' own notFound() falls back to the built-in page.
+            const page = matched === undefined ? builtinNotFound(url.pathname) : await renderPage(undefined, url, undefined, signal);
+            return { ...page, headers: rendered.headers };
         }
-        const finish = (draft, depth) => {
-            const children = draft.children.map(child => finish(child, depth + 1));
-            const { item, route } = draft;
-            // A folder's index page labels the folder by its hk:label; then a plugin's folder() label does, then the page's <title>.
-            const label = item === undefined ? draft.label : children.length > 0 && route.label === undefined ? draft.folder ?? route.title ?? draft.label : item.label;
-            const current = item?.current ?? "false";
-            return Object.freeze({ label, ...(item === undefined ? {} : { href: item.href, pageName: item.pageName }), current,
-                open: current === "page" || children.some(child => child.open), depth, order: draft.order, children: Object.freeze(children) });
-        };
-        return Object.freeze(top.map(draft => finish(draft, 0)));
+        return { status: failure?.status ?? (matched === undefined ? 404 : rendered.status), pathname: url.pathname, body: rendered.body, css: rendered.css, head: rendered.head,
+            html: documentHTML(rendered.body, rendered.head), components, layers: rendered.layers, headers: rendered.headers };
     };
-    // The neighbours of the current page in navigation order.
-    const pager = async (query = {}) => {
-        const items = await navigation(query);
-        const index = items.findIndex(entry => entry.current === "page");
-        if (index < 0)
-            return Object.freeze({});
-        return Object.freeze({ ...(index > 0 ? { previous: items[index - 1] } : {}), ...(index < items.length - 1 ? { next: items[index + 1] } : {}) });
+    /**
+     * A failure answers with app/error.html and a safe message; the error itself goes to the console. The
+     * development server, which supplies the module server, shows the error instead.
+     */
+    const failed = async (error, request) => {
+        const report = (error) => { if (!ownsServer || request.signal.aborted)
+            throw error; console.error(error); };
+        report(error);
+        const { pathname } = new URL(request.url);
+        // A failed page has no payload, so the browser loads its document, the error page.
+        if (pathname.startsWith(config.base + "_htmlkit/pages/"))
+            return new Response(null, { status: 500 });
+        // The error page shares the site's layouts, so a failing layout fails it too; the built-in page answers then.
+        const page = pathname.startsWith("//") ? builtinFailure(pathname) : await renderPage(undefined, new URL(pathname, config.origin), undefined, request.signal, serverFailure)
+            .catch((again) => { report(again); return builtinFailure(pathname); });
+        return pageResponse(page, request, false, assets?.(page));
+    };
+    const pipeline = {
+        base: config.base, routes, endpoints,
+        redirects: new Map([...redirects].map(([from, location]) => [from, { location, status: 308 }])),
+        endpoint: async (route) => await environment.runner.import(route.file),
+        ...(middleware === undefined ? {} : { middleware: async () => {
+                const handler = (await environment.runner.import(middleware)).default;
+                if (typeof handler !== "function")
+                    throw new HtmlKitError("Middleware must export a default function.", middleware);
+                return handler;
+            } }),
+        async page(route, params, request, payload) {
+            const url = new URL(request.url);
+            // A prerendered page renders as the build renders it: at its canonical URL, without the request.
+            const server = route.render === "server";
+            const page = await renderPage({ route, params }, server ? url : new URL(url.pathname, config.origin), server ? request : undefined, request.signal);
+            return pageResponse(page, request, payload, assets?.(page));
+        },
+        async notFound(request, payload) {
+            const { pathname } = new URL(request.url);
+            if (payload)
+                return new Response(null, { status: 404 });
+            const page = pathname.startsWith("//") ? builtinNotFound(pathname) : await renderPage(undefined, new URL(pathname, config.origin), undefined, request.signal);
+            return pageResponse(page, request, false, assets?.(page));
+        },
     };
     const application = {
-        ...config, routes, ...(notFoundRoute === undefined ? {} : { notFound: notFoundRoute }), navigation, navigationTree, files, watchFiles: watched,
+        ...config, routes, ...(notFoundRoute === undefined ? {} : { notFound: notFoundRoute }), ...(errorRoute === undefined ? {} : { error: errorRoute }),
+        navigation: navigation.navigation, navigationTree: navigation.navigationTree,
+        files, watchFiles: watched, endpoints, ...(middleware === undefined ? {} : { middleware }),
         async entries() {
             const paths = await concreteRoutes();
             const missing = unenumerated[0];
             if (missing !== undefined)
                 throw new HtmlKitError(`Static entries() must enumerate parameters: ${missing.params.join(", ")}.`, origin(missing));
-            return [...paths.keys()].sort();
+            // Server-rendered pages render on request, so a build lists only prerendered ones.
+            return [...paths].filter(([, route]) => route.render !== "server").map(([path]) => path).sort();
         },
         async render(pathname, signal = new AbortController().signal) {
             signal.throwIfAborted();
-            const notFound = () => ({ status: 404, pathname, ...notFoundPage(scripts), css: "", components: [], layers: [] });
             // A path starting with // would name another origin; no page lives there, for documents or payloads.
             if (pathname.startsWith("//"))
-                return notFound();
+                return builtinNotFound(pathname);
             const url = new URL(pathname, config.origin);
             if (url.origin !== config.origin || url.search || url.hash)
                 throw new HtmlKitError("Static rendering requires an application pathname without a query or fragment.");
-            const redirected = (location, status) => ({ status, pathname: url.pathname, location, ...redirectPage(location), css: "", components: [], layers: [] });
             // The redirects option precedes pages, with or without the trailing slash.
             const configured = redirects.get(url.pathname.endsWith("/") ? url.pathname : url.pathname + "/");
             if (configured !== undefined)
-                return redirected(configured, 308);
-            const matched = matchRoute(routes, url.pathname, config.base);
-            // Unmatched paths render app/pages/404.html through its layouts, or the built-in page.
-            if (matched === undefined && notFoundRoute === undefined)
-                return notFound();
-            const { route, params } = matched ?? { route: notFoundRoute, params: {} };
-            const status = matched === undefined ? 404 : 200;
-            const layers = [...route.layouts, route];
-            // Vite owns module caching and dependency invalidation. Per-render results never enter
-            // a shared cache; HTML Next owns the DOM worker and declarative component semantics.
-            const packages = new Map();
-            const resources = new Map();
-            const layerURLs = new Set(layers.map(layer => pathToFileURL(layer.component).href));
-            const resolveCSS = server.config.createResolver({ extensions: [".css"], mainFields: ["style"], conditions: ["style", "development|production"], preferRelative: true, tryIndex: false });
-            const graph = await loadNodeComponents(layers.map(layer => pathToFileURL(layer.component).href), {
-                readStylesheet: async (url) => ({ url, source: await readFile(fileURLToPath(url), "utf8") }),
-                resolveStylesheet: async (specifier, parentURL) => {
-                    const resolved = await resolveCSS(specifier, fileURLToPath(parentURL));
-                    return resolved === undefined ? undefined
-                        : pathToFileURL(resolved.replace(/[?#].*$/, "")).href + (/[?#].*$/.exec(resolved)?.[0] ?? "");
-                },
-                stylesheetAssetURL: url => url.startsWith("file:") ? `/@fs/${fileURLToPath(url)}${new URL(url).search}${new URL(url).hash}` : url,
-                // The graph resolver is synchronous. Prepare its bare imports while asynchronously
-                // reading each carrier, using Vite's ESM resolution from the consuming application.
-                importMap: map,
-                readComponent: async (url) => {
-                    let source = sources.get(fileURLToPath(url)) ?? await readFile(fileURLToPath(url), "utf8");
-                    for (const [tag, href] of builtins)
-                        if (new RegExp(`<${tag}[\\s/>]`).test(source))
-                            source += `\n<link rel="component" href="${href}">`;
-                    const parsed = layerURLs.has(url) ? applicationResource(source, url) : parseComponentResource(source, url);
-                    if ("configuration" in parsed)
-                        resources.set(url, parsed);
-                    const imports = [...parsed.dependencies, ...parsed.definitions.flatMap(definition => definition.controller === undefined ? [] : [definition.controller])];
-                    for (const specifier of imports) {
-                        if (/^(?:[A-Za-z][A-Za-z\d+.-]*:|\/|\.\.?\/)/.test(specifier) || Object.keys(map.imports).some(key => specifier.startsWith(key)))
-                            continue;
-                        const resolved = await server.environments.client.pluginContainer.resolveId(specifier, fileURLToPath(url));
-                        if (resolved === null || resolved.external)
-                            throw new HtmlKitError(`Cannot resolve component import ${specifier}.`, url);
-                        packages.set(`${url}\0${specifier}`, packageResource(resolved.id));
-                    }
-                    return { url, source };
-                },
-                resolvePackage: (specifier, parentURL) => {
-                    const resolved = packages.get(`${parentURL}\0${specifier}`);
-                    if (resolved === undefined)
-                        throw new HtmlKitError(`Cannot resolve component import ${specifier}.`, parentURL);
-                    return resolved;
-                },
-            });
-            const layerDefinitions = layers.map(layer => {
-                if (layer === route)
-                    return pageDefinition(resources.get(pathToFileURL(layer.component).href), layer.component);
-                const roots = graph.roots.filter(id => graph.nodes.get(id).url === pathToFileURL(layer.component).href);
-                if (roots.length !== 1)
-                    throw new HtmlKitError("A page or layout must declare exactly one root component.", layer.component);
-                return graph.nodes.get(roots[0]).definition;
-            });
-            if (layerDefinitions.at(-1).contract.tag !== route.pageName) {
-                throw new HtmlKitError("Page component name changed; rediscover routes before rendering.", route.component);
-            }
-            for (const definition of layerDefinitions.slice(0, -1)) {
-                if (!definition.slots?.some(slot => slot.name === "page"))
-                    throw new HtmlKitError('Layout requires a slot named "page".', definition.source.file);
-            }
-            const results = [];
-            const attributes = [];
-            let parent = Object.freeze({});
-            let head = {};
-            // An alias marks its page's own entry current.
-            const current = route.canonical === undefined ? url.pathname : config.base + route.canonical.slice(1);
-            for (const layer of layers) {
-                signal.throwIfAborted();
-                const loaded = await module(layer);
-                const context = { phase: "prerender", url: new URL(url), base: config.base, params, parent,
-                    propNames: Object.freeze(Object.keys(layerDefinitions[results.length].contract.props)),
-                    fetch: globalThis.fetch, signal,
-                    navigation: (query) => navigation({ current, ...query }),
-                    navigationTree: (query) => navigationTree({ current, ...query }),
-                    breadcrumbs: (query) => breadcrumbs({ current, ...query }),
-                    pager: (query) => pager({ current, ...query }),
-                    redirect(location, status = 303) {
-                        if (!redirectStatuses.includes(status))
-                            throw new HtmlKitError(`Redirect status ${String(status)} must be 301, 302, 303, 307, or 308.`, origin(layer));
-                        throw new Redirect(redirectLocation(config.base, location, origin(layer)), status);
-                    },
-                    get request() { throw new HtmlKitError("request is unavailable during static generation.", origin(layer)); } };
-                let result;
-                try {
-                    result = loaded.load === undefined ? {} : await loaded.load(context);
-                }
-                catch (error) {
-                    if (error instanceof Redirect)
-                        return redirected(error.location, error.status);
-                    throw error;
-                }
-                if (result === null || typeof result !== "object" || Array.isArray(result))
-                    throw new HtmlKitError("load() must return a LoaderResult object.", origin(layer));
-                results.push(result);
-                parent = Object.freeze({ ...parent, ...result.data });
-                const index = results.length - 1;
-                // Checked against the layer's own component, which a prop's diagnostic names; its head reuses them.
-                attributes.push(invocationAttributes(layerDefinitions[index], result));
-                head = await renderHead(resources.get(pathToFileURL(layer.component).href), layerDefinitions[index], result, head, url.href, definition => invocation(definition.contract.tag, attributes[index], "hk-head", "", false));
-            }
-            if (scripts.length > 0)
-                head = { ...head, scripts };
-            const state = {};
-            const rendered = layers.map((_layer, i) => ({ component: layerDefinitions[i].contract.tag,
-                attributes: attributes[i], ...(results[i].state === undefined ? {} : { state: results[i].state }) }));
-            let body = "";
-            for (let i = layers.length - 1; i >= 0; i--) {
-                const id = `hk-layer-${i}`;
-                const layer = rendered[i];
-                if (layer.state !== undefined)
-                    state[`#${id}`] = layer.state;
-                body = invocation(layer.component, layer.attributes, id, body, i > 0);
-            }
-            const components = [...graph.nodes.values()].map(node => ({ definition: node.definition,
-                styles: compileComponentStylesForBuild(node.definition.css, node.definition),
-                ...(node.controller === undefined ? {} : { controller: fileURLToPath(node.controller.url) }) }));
-            const output = await renderComponents(body, { definitions: components.map(value => value.definition), url: url.href, state });
-            signal.throwIfAborted();
-            return { status, pathname: url.pathname, body: output.html, css: output.css, head,
-                html: documentHTML(output.html, head), components, layers: rendered };
+                return redirected(url.pathname, configured, 308);
+            return renderPage(matchRoute(routes, url.pathname, config.base), url, undefined, signal);
         },
         // Not a method of `this`: runtimes are handed the function itself, as in Deno.serve(application.fetch).
-        async fetch(request) {
-            if (request.method !== "GET" && request.method !== "HEAD")
-                return new Response(null, { status: 405, headers: { allow: "GET, HEAD" } });
-            const { pathname } = new URL(request.url);
-            // A page's payload, through the same render as its document.
-            const pages = config.base + "_htmlkit/pages/";
-            const payload = pathname.startsWith(pages) ? /^(.*\/)?payload\.json$/.exec(pathname.slice(pages.length)) : null;
-            if (payload !== null) {
-                const page = await application.render(config.base + (payload[1] ?? ""), request.signal);
-                const data = page.status === 200 && payloadPath(config.base, page.pathname) === pathname
-                    ? pagePayload(page, assets?.(page) ?? { styles: [], modules: [] }) : undefined;
-                return new Response(data === undefined || request.method === "HEAD" ? null : JSON.stringify(data), { status: data === undefined ? 404 : 200, headers: { "content-type": "application/json" } });
-            }
-            const page = await application.render(pathname, request.signal);
-            if (page.location !== undefined) {
-                return new Response(request.method === "HEAD" ? null : page.html, { status: page.status, headers: { location: page.location, "content-type": "text/html; charset=utf-8" } });
-            }
-            if (page.status === 200 && !pathname.endsWith("/"))
-                return new Response(null, { status: 308, headers: { location: pathname + "/" } });
-            return new Response(request.method === "HEAD" ? null : documentHTML(page.body, page.head, assets?.(page)), { status: page.status, headers: { "content-type": "text/html; charset=utf-8" } });
-        },
+        fetch: request => respond(pipeline, request).catch((error) => failed(error, request)),
         async close() { if (ownsServer)
             await server.close(); },
     };
-    return application;
+    return { application, graph, catalog: concreteRoutes };
+}
+/** assets supplies a serving adapter's browser modules and stylesheets for fetch(). */
+export async function createApplication(input = {}, moduleServer, assets) {
+    return (await createApplicationInternals(input, moduleServer, assets)).application;
 }
 //# sourceMappingURL=application.js.map