@warlock.js/web 5.1.0 → 5.2.0

package/esm/server/install-page-routes-from-manifest.mjs

@@ -1,12 +1,16 @@
 import { publishRouteTable } from "../routing/route-table.mjs";
+import { isLoaderShortCircuit } from "./settle-page-response.mjs";
 import { createPageModuleLoader } from "./create-page-module-loader.mjs";
 import { composeRoutePath } from "../routing/compose-route-path.mjs";
+import { deriveFilesystemRouteName, deriveFilesystemRoutePath } from "../routing/filesystem-route.mjs";
 import { NestedLayoutsNotSupportedError, selectPageLayout } from "../routing/layout-policy.mjs";
 import { canonicalizeRouteExport, deriveFallbackRouteName } from "../routing/route-identity.mjs";
 import { createPageRouteHandler } from "./create-page-route-handler.mjs";
+import { productionStylesheetUrls } from "./stylesheet-urls.mjs";
 import { DuplicateNotFoundPageError, NOT_FOUND_ROUTE_NAME, NOT_FOUND_ROUTE_PATH, NotFoundPageDeclaresRouteError, createNotFoundRouteHandler, isNotFoundPageFile } from "./not-found-page.mjs";
+import { Response } from "@warlock.js/core";
 
-//#region ../web/src/server/install-page-routes-from-manifest.ts
+//#region web/src/server/install-page-routes-from-manifest.ts
 /**
 * Page-route registration for a built application.
 *
@@ -31,7 +35,27 @@ import { DuplicateNotFoundPageError, NOT_FOUND_ROUTE_NAME, NOT_FOUND_ROUTE_PATH,
 * in memory, so registration has nothing to await; the loader handed to each
 * handler is a lookup over the same table, not an evaluation step.
 */
+/**
+* `sourceFile`'s path relative to the web root — `src/web/**`, the only page
+* root discovery enumerates (`discoverWebRoots`,
+* `web/src/build/discover-pages.ts:210-213`). Manifest `sourceFile`s are
+* app-root-relative (`"src/web/..."`, `page-manifest.ts`'s own doc comment),
+* so dropping the first two segments — `<srcDir>`, then the literal `"web"` —
+* recovers exactly what `deriveFilesystemRoutePath`/`deriveFilesystemRouteName`
+* expect: the same value dev computes as `filesystemPageFileFor`
+* (`install-page-routes.ts:101-103`).
+*/
+function webRelativeSourceFile(sourceFile) {
+	return sourceFile.split("/").slice(2).join("/");
+}
 function resolveRoute(routeExport, sourceFile) {
+	if (routeExport === void 0) {
+		const pageFile = webRelativeSourceFile(sourceFile);
+		return {
+			path: deriveFilesystemRoutePath({ pageFile }),
+			name: deriveFilesystemRouteName(pageFile)
+		};
+	}
 	const canonical = canonicalizeRouteExport(routeExport);
 	return {
 		path: canonical.path,
@@ -41,6 +65,22 @@ function resolveRoute(routeExport, sourceFile) {
 		})
 	};
 }
+/**
+* Every layout's declared `prefix`, keyed by its directory relative to the
+* web root — the same table dev builds as `LayoutLevel.prefixesByDirectory`
+* (`install-page-routes.ts:214-222`) and the one
+* {@link deriveFilesystemRoutePath} uses to let a directory's own layout
+* rename the URL segment a bare directory name would otherwise contribute.
+*/
+function layoutPrefixesOf(page) {
+	return Object.fromEntries(page.layouts.flatMap((layout) => {
+		const prefix = layout.module.prefix;
+		if (prefix === void 0) return [];
+		const relative = webRelativeSourceFile(layout.sourceFile);
+		const slashIndex = relative.lastIndexOf("/");
+		return [[slashIndex === -1 ? "" : relative.slice(0, slashIndex), prefix]];
+	}));
+}
 function layoutLevelOf(page) {
 	const selection = selectPageLayout(page.layouts.map((layout) => ({
 		layout: layout.sourceFile,
@@ -67,9 +107,19 @@ function layoutLevelOf(page) {
 * already in memory and cannot change under a running process.
 */
 function composeLayoutLevel(page, host) {
+	const hostIndex = page.layouts.indexOf(host);
 	return {
 		...host.module,
-		middleware: page.layouts.flatMap((layout) => [...layout.module.middleware ?? []])
+		middleware: page.layouts.flatMap((layout) => [...layout.module.middleware ?? []]),
+		loader: async (context) => {
+			let hostData;
+			for (let index = 0; index < page.layouts.length; index++) {
+				const value = await page.layouts[index].module.loader?.(context);
+				if (value instanceof Response || isLoaderShortCircuit(value)) return value;
+				if (index === hostIndex) hostData = value;
+			}
+			return hostData;
+		}
 	};
 }
 /**
@@ -87,11 +137,12 @@ function composeLayoutLevel(page, host) {
 * them silently loses at runtime.
 */
 function installPageRoutesFromManifest(options) {
-	const { router, manifest, hydrationClientModuleUrl, stylesheetUrls, applyBufferedCookie, createHandler = createPageRouteHandler } = options;
+	const { router, manifest, hydrationClientModuleUrl, clientDir, createHandler = createPageRouteHandler } = options;
 	if (manifest.pages.length === 0) return [];
 	const app = manifest.app;
 	if (app === void 0) throw new Error(`installPageRoutesFromManifest: this build's page manifest carries ${manifest.pages.length} page(s) but no application root. Every page renders inside the app component, so no page can be registered without it. Re-run the build so the generated pages barrel provides an \`app\` entry.`);
 	const loadModule = createPageModuleLoader(manifest);
+	const loadErrorPage = manifest.errorPage === void 0 ? void 0 : async () => manifest.errorPage.module;
 	const notFoundPages = manifest.pages.filter((page) => isNotFoundPageFile(page.sourceFile));
 	const pages = manifest.pages.filter((page) => !isNotFoundPageFile(page.sourceFile));
 	if (notFoundPages.length > 1) throw new DuplicateNotFoundPageError(notFoundPages.map((page) => page.sourceFile));
@@ -102,13 +153,20 @@ function installPageRoutesFromManifest(options) {
 	for (const page of pages) {
 		const { host: layout, prefix: layoutPrefix } = layoutLevelOf(page);
 		const routeExport = page.module.route;
-		if (routeExport === void 0) continue;
 		const { path: routePath, name } = resolveRoute(routeExport, page.sourceFile);
-		const effectivePath = composeRoutePath(layoutPrefix, routePath);
+		const effectivePath = routeExport === void 0 ? deriveFilesystemRoutePath({
+			pageFile: webRelativeSourceFile(page.sourceFile),
+			layoutPrefixes: layoutPrefixesOf(page)
+		}) : composeRoutePath(layoutPrefix, routePath);
 		const existingFile = fileByPath.get(effectivePath);
 		if (existingFile) throw new Error(`installPageRoutesFromManifest: composed route path "${effectivePath}" (layout prefix "${layoutPrefix}" + route.path "${routePath}") is declared by two pages — "${existingFile}" and "${page.sourceFile}". Every page's composed route path must be unique.`);
 		fileByPath.set(effectivePath, page.sourceFile);
 		const composedLayout = page.layouts.length > 1 && layout !== void 0 ? composeLayoutLevel(page, layout) : void 0;
+		const stylesheetUrls = clientDir === void 0 ? [] : productionStylesheetUrls(clientDir, [
+			app.sourceFile,
+			...page.layouts.map((pageLayout) => pageLayout.sourceFile),
+			page.sourceFile
+		]);
 		router.get(effectivePath, createHandler({
 			path: effectivePath,
 			name,
@@ -116,14 +174,16 @@ function installPageRoutesFromManifest(options) {
 			pageFile: page.sourceFile,
 			layoutFile: layout?.sourceFile,
 			loadModule: composedLayout === void 0 ? loadModule : (moduleId) => moduleId === layout?.sourceFile ? Promise.resolve(composedLayout) : loadModule(moduleId),
+			loadRegistrationLayouts: () => Promise.resolve(page.layouts.map((layout) => layout.module)),
 			hydrationClientModuleUrl,
-			stylesheetUrls,
-			applyBufferedCookie
+			loadErrorPage,
+			stylesheetUrls
 		}), {
 			name,
 			isPage: true
 		});
 		installed.push({
+			declaredPath: routePath,
 			path: effectivePath,
 			name,
 			file: page.sourceFile,
@@ -138,10 +198,11 @@ function installPageRoutesFromManifest(options) {
 		layoutFile: void 0,
 		loadModule,
 		hydrationClientModuleUrl,
-		stylesheetUrls,
-		applyBufferedCookie,
+		loadErrorPage,
+		stylesheetUrls: clientDir === void 0 ? [] : productionStylesheetUrls(clientDir, [app.sourceFile, notFoundPage.sourceFile]),
 		matchPath: (requestPath) => requestPath,
-		statusForRenderedOk: 404
+		statusForRenderedOk: 404,
+		skipPageLoader: true
 	}) }), {
 		name: NOT_FOUND_ROUTE_NAME,
 		isPage: true

package/esm/server/install-page-routes-from-manifest.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"install-page-routes-from-manifest.mjs","names":[],"sources":["../../../../../../../web/src/server/install-page-routes-from-manifest.ts"],"sourcesContent":["/**\r\n * Page-route registration for a built application.\r\n *\r\n * `installPageRoutes` answers \"which pages exist?\" by walking the filesystem\r\n * and \"what is this module?\" by asking Vite to evaluate it. Neither question\r\n * can be asked of a running production process: there is no `app/` tree beside\r\n * the bundle and no Vite. Both answers were therefore moved to build time — the\r\n * generated `pages.ts` barrel statically imported every page, layout and the\r\n * app root and handed them over as a {@link PageManifest}, and this module\r\n * turns that table into registered routes.\r\n *\r\n * WHAT IS DELIBERATELY IDENTICAL TO DEVELOPMENT: the route a page ends up on,\r\n * and the guards that run before it renders. A page's `route` export and the\r\n * `prefix` and `middleware` exports of EVERY layout on its path are read off the\r\n * module namespaces here, at boot, and composed by the same rules dev composes\r\n * them by ({@link layoutLevelOf}, {@link composeLayoutLevel}) — so the URL a page\r\n * answers on and the chain that guards it are decided by the page's own source\r\n * in both modes, and a build cannot quietly disagree with the dev server about\r\n * either.\r\n *\r\n * WHAT IS DELIBERATELY DIFFERENT: this is synchronous. Every module is already\r\n * in memory, so registration has nothing to await; the loader handed to each\r\n * handler is a lookup over the same table, not an evaluation step.\r\n */\r\nimport { composeRoutePath } from \"../routing/compose-route-path\";\r\nimport { NestedLayoutsNotSupportedError, selectPageLayout } from \"../routing/layout-policy\";\r\nimport { canonicalizeRouteExport, deriveFallbackRouteName } from \"../routing/route-identity\";\r\nimport { publishRouteTable } from \"../routing/route-table\";\r\nimport type { Response, Router } from \"@warlock.js/core\";\r\nimport type { BufferedCookie } from \"./buffered-response\";\r\nimport { createPageModuleLoader } from \"./create-page-module-loader\";\r\nimport {\r\n  createPageRouteHandler,\r\n  type PageRouteHandler,\r\n  type PageRouteHandlerOptions,\r\n} from \"./create-page-route-handler\";\r\nimport type { PipelineMiddleware } from \"./execute-page-request\";\r\nimport {\r\n  createNotFoundRouteHandler,\r\n  DuplicateNotFoundPageError,\r\n  isNotFoundPageFile,\r\n  NotFoundPageDeclaresRouteError,\r\n  NOT_FOUND_ROUTE_NAME,\r\n  NOT_FOUND_ROUTE_PATH,\r\n  type RegisteredRouteShape,\r\n} from \"./not-found-page\";\r\nimport type { PageManifest, PageManifestLayoutEntry, PageManifestPageEntry } from \"./page-manifest\";\r\n\r\n/** A page declares either a bare path or a path plus an explicit route name. */\r\ntype PageRouteExport = string | { path: string; name?: string };\r\n\r\n/** The only export this module reads off a page module namespace. */\r\ntype PageModuleShape = {\r\n  route?: PageRouteExport;\r\n};\r\n\r\n/** The exports this module reads off a layout module namespace. */\r\ntype LayoutModuleShape = {\r\n  prefix?: string;\r\n  /**\r\n   * The default export — the thing that puts an element in the document, and\r\n   * therefore the ONLY export that decides whether a layout counts against the\r\n   * single-rendering-layout rule (`../routing/layout-policy.ts`). The manifest\r\n   * carries LOADED modules, so this is a fact rather than a guess, exactly as it\r\n   * is in dev (`install-page-routes.ts:145-150`).\r\n   */\r\n  default?: unknown;\r\n  /** The layout's guards, in the order it declared them. */\r\n  middleware?: readonly PipelineMiddleware[];\r\n};\r\n\r\n/**\r\n * How a handler is built for one page. Defaults to `createPageRouteHandler`;\r\n * taking it as an input keeps this module's own job — reading the manifest and\r\n * registering routes — provable without a render pipeline behind it.\r\n */\r\nexport type PageRouteHandlerFactory = (options: PageRouteHandlerOptions) => PageRouteHandler;\r\n\r\nexport type InstalledManifestPageRoute = {\r\n  /** The composed path the route was registered on. */\r\n  path: string;\r\n  /** The resolved route name; shared namespace with API routes. */\r\n  name: string;\r\n  /** The page's manifest `sourceFile`. */\r\n  file: string;\r\n  /** The layout's manifest `sourceFile`, when the page has one. */\r\n  layoutFile: string | undefined;\r\n};\r\n\r\nexport type InstallPageRoutesFromManifestOptions = {\r\n  router: Router;\r\n  /** The table the generated production barrel provided at import time. */\r\n  manifest: PageManifest;\r\n  /** Browser module loaded after the server-rendered application and payload. */\r\n  hydrationClientModuleUrl?: string;\r\n  /** Stylesheet URLs emitted into every page's `<head>`. */\r\n  stylesheetUrls?: readonly string[];\r\n  /** Same helper `dev-server.ts` exports — passed in, never imported. */\r\n  applyBufferedCookie: (response: Response, cookie: BufferedCookie) => void;\r\n  createHandler?: PageRouteHandlerFactory;\r\n};\r\n\r\nfunction resolveRoute(\r\n  routeExport: PageRouteExport,\r\n  sourceFile: string,\r\n): { path: string; name: string } {\r\n  const canonical = canonicalizeRouteExport(routeExport);\r\n\r\n  return {\r\n    path: canonical.path,\r\n    name: canonical.name ?? deriveFallbackRouteName({ routePath: canonical.path, sourceFile }),\r\n  };\r\n}\r\n\r\n/**\r\n * The page's layout LEVEL, resolved from the whole chain the manifest carries\r\n * rather than from the one layout nearest to it — the same resolution dev makes\r\n * (`install-page-routes.ts:138-164`), against loaded modules instead of Vite's.\r\n *\r\n * The manifest carries the FULL chain, outermost first, and the render pipeline\r\n * has exactly one layout slot per page (`execute-page-request.ts`'s\r\n * `PageRouteEntry[\"triple\"]`), so the chain has to be collapsed into one module\r\n * before it reaches a handler. Two things collapse differently and both matter:\r\n *\r\n * - RENDERING is a selection: at most one layout on the chain may render, and\r\n *   the policy picks it. `renders` is read off the loaded module\r\n *   (`typeof module.default !== \"undefined\"`), never off the entry's presence in\r\n *   the chain — a `middleware`-only layout has no default export and is not a\r\n *   wrapper. Passing bare `sourceFile` strings had every layout read as a\r\n *   rendering one, so boot refused a middleware-only guard chain that the build\r\n *   had already accepted: an application that builds and will not start.\r\n * - MIDDLEWARE and PREFIX are compositions: every layout on the path\r\n *   contributes, outermost first. A guard on an outer layout that the page's own\r\n *   directory knows nothing about is exactly the guard that must still run, and\r\n *   a prefix nobody composed is a URL nobody wrote down.\r\n *\r\n * A chain with more than one RENDERING layout is still refused here, at boot,\r\n * before a single request can observe the wrong document. Like the missing\r\n * app-root refusal below, that arm defends against stale or hand-edited build\r\n * artifacts: the build refuses to emit such a chain, but a manifest can reach a\r\n * running process without that build having produced it.\r\n */\r\ntype LayoutLevel = {\r\n  /**\r\n   * The layout entry the handler's layout slot is registered under, or\r\n   * `undefined` when the page has no layout at all: the layout that RENDERS,\r\n   * or — when none does — the nearest one, which is the slot production has\r\n   * always used and so the choice that changes nothing but the middleware for a\r\n   * chain with no wrapper in it.\r\n   */\r\n  host: PageManifestLayoutEntry | undefined;\r\n  /** Every layout's `prefix`, composed outermost first — `discoverPages`' own reduction. */\r\n  prefix: string;\r\n};\r\n\r\nfunction layoutLevelOf(page: PageManifestPageEntry): LayoutLevel {\r\n  const selection = selectPageLayout(\r\n    page.layouts.map((layout) => ({\r\n      layout: layout.sourceFile,\r\n      renders: typeof (layout.module as LayoutModuleShape).default !== \"undefined\",\r\n    })),\r\n  );\r\n\r\n  if (selection.type === \"rejected\") {\r\n    throw new NestedLayoutsNotSupportedError(page.sourceFile, selection.layouts);\r\n  }\r\n\r\n  return {\r\n    host:\r\n      selection.type === \"selected\"\r\n        ? page.layouts.find((layout) => layout.sourceFile === selection.layout)\r\n        : page.layouts.at(-1),\r\n    prefix: page.layouts.reduce(\r\n      (composed, layout) =>\r\n        composeRoutePath(composed, (layout.module as LayoutModuleShape).prefix ?? \"/\"),\r\n      \"/\",\r\n    ),\r\n  };\r\n}\r\n\r\n/**\r\n * The layout slot's module for one page: the slot host's own namespace, with the\r\n * whole chain's middleware in place of its own — outermost first, which is the\r\n * order stage 3 runs the array in (`execute-page-request.ts:519-524`) and the\r\n * order an outer `optionalAuth` needs in order to have resolved an identity\r\n * before an inner `gate()` checks it.\r\n *\r\n * Deliberately NOT core's route-level `middleware` option: that runs before the\r\n * pipeline's App-level middleware, which would invert outermost-first — the one\r\n * property this composition exists to guarantee.\r\n *\r\n * Built once at registration, not per request: unlike dev, every module here is\r\n * already in memory and cannot change under a running process.\r\n */\r\nfunction composeLayoutLevel(\r\n  page: PageManifestPageEntry,\r\n  host: PageManifestLayoutEntry,\r\n): Record<string, unknown> {\r\n  return {\r\n    ...host.module,\r\n    middleware: page.layouts.flatMap((layout) => [\r\n      ...((layout.module as LayoutModuleShape).middleware ?? []),\r\n    ]),\r\n  };\r\n}\r\n\r\n/**\r\n * Registers every page the manifest carries into `options.router`.\r\n *\r\n * An empty manifest registers nothing and is not an error: \"built with web, no\r\n * pages\" is a legal state of a built application, and treating it as a failure\r\n * would make an empty project unbootable. A manifest that DOES carry pages but\r\n * no app root is the opposite — every page renders inside the application root,\r\n * so that combination is a broken table rather than an empty one, and it is\r\n * refused before any route exists to serve a request with a missing root.\r\n *\r\n * Two pages composing to the same path is refused the moment the second one is\r\n * seen, naming both — a registration-time failure, rather than a route one of\r\n * them silently loses at runtime.\r\n */\r\nexport function installPageRoutesFromManifest(\r\n  options: InstallPageRoutesFromManifestOptions,\r\n): InstalledManifestPageRoute[] {\r\n  const {\r\n    router,\r\n    manifest,\r\n    hydrationClientModuleUrl,\r\n    stylesheetUrls,\r\n    applyBufferedCookie,\r\n    createHandler = createPageRouteHandler,\r\n  } = options;\r\n\r\n  if (manifest.pages.length === 0) return [];\r\n\r\n  const app = manifest.app;\r\n\r\n  if (app === undefined) {\r\n    throw new Error(\r\n      `installPageRoutesFromManifest: this build's page manifest carries ${manifest.pages.length} ` +\r\n        \"page(s) but no application root. Every page renders inside the app component, so no \" +\r\n        \"page can be registered without it. Re-run the build so the generated pages barrel \" +\r\n        \"provides an `app` entry.\",\r\n    );\r\n  }\r\n\r\n  // Ids are the manifest's own `sourceFile` strings and are passed on untouched:\r\n  // the loader below matches them by exact string equality, so resolving,\r\n  // joining or swapping separators on one side of that comparison would turn\r\n  // every lookup into a miss.\r\n  const loadModule = createPageModuleLoader(manifest);\r\n\r\n  // Same partition development makes, on the same rule (the filename), so the\r\n  // two modes cannot disagree about which file is the not-found page. It is\r\n  // taken OUT of the registration loop rather than skipped inside it: every step\r\n  // in there composes and claims a URL, and `404.page.tsx` has none.\r\n  const notFoundPages = manifest.pages.filter((page) => isNotFoundPageFile(page.sourceFile));\r\n  const pages = manifest.pages.filter((page) => !isNotFoundPageFile(page.sourceFile));\r\n\r\n  if (notFoundPages.length > 1) {\r\n    throw new DuplicateNotFoundPageError(notFoundPages.map((page) => page.sourceFile));\r\n  }\r\n\r\n  const notFoundPage = notFoundPages[0];\r\n\r\n  if (notFoundPage !== undefined && (notFoundPage.module as PageModuleShape).route !== undefined) {\r\n    throw new NotFoundPageDeclaresRouteError(notFoundPage.sourceFile);\r\n  }\r\n\r\n  const installed: InstalledManifestPageRoute[] = [];\r\n  const fileByPath = new Map<string, string>();\r\n\r\n  for (const page of pages) {\r\n    const { host: layout, prefix: layoutPrefix } = layoutLevelOf(page);\r\n    const routeExport = (page.module as PageModuleShape).route;\r\n\r\n    // A page that declares no route has no public URL to be registered under —\r\n    // the same page discovery skips in development.\r\n    if (routeExport === undefined) continue;\r\n\r\n    const { path: routePath, name } = resolveRoute(routeExport, page.sourceFile);\r\n    const effectivePath = composeRoutePath(layoutPrefix, routePath);\r\n    const existingFile = fileByPath.get(effectivePath);\r\n\r\n    if (existingFile) {\r\n      throw new Error(\r\n        `installPageRoutesFromManifest: composed route path \"${effectivePath}\" (layout ` +\r\n          `prefix \"${layoutPrefix}\" + route.path \"${routePath}\") is declared by two pages — ` +\r\n          `\"${existingFile}\" and \"${page.sourceFile}\". Every page's composed route path must ` +\r\n          \"be unique.\",\r\n      );\r\n    }\r\n\r\n    fileByPath.set(effectivePath, page.sourceFile);\r\n\r\n    // The layout slot's id resolves to the COMPOSED level — every layout's\r\n    // middleware, in chain order — and every other id goes straight to the\r\n    // manifest lookup. A one-layout chain has nothing to compose, so it is left\r\n    // to resolve as the exact namespace object the manifest carries, untouched.\r\n    const composedLayout =\r\n      page.layouts.length > 1 && layout !== undefined\r\n        ? composeLayoutLevel(page, layout)\r\n        : undefined;\r\n\r\n    router.get(\r\n      effectivePath,\r\n      createHandler({\r\n        path: effectivePath,\r\n        name,\r\n        appFile: app.sourceFile,\r\n        pageFile: page.sourceFile,\r\n        layoutFile: layout?.sourceFile,\r\n        loadModule:\r\n          composedLayout === undefined\r\n            ? loadModule\r\n            : (moduleId) =>\r\n                moduleId === layout?.sourceFile\r\n                  ? Promise.resolve(composedLayout)\r\n                  : loadModule(moduleId),\r\n        hydrationClientModuleUrl,\r\n        stylesheetUrls,\r\n        applyBufferedCookie,\r\n      }),\r\n      // `isPage` marks this route as SSR-served. Pages and API routes share one\r\n      // router and one route-name namespace, so the router's duplicate-name\r\n      // error reads this flag to say which claimant is the page.\r\n      { name, isPage: true },\r\n    );\r\n\r\n    installed.push({\r\n      path: effectivePath,\r\n      name,\r\n      file: page.sourceFile,\r\n      layoutFile: layout?.sourceFile,\r\n    });\r\n  }\r\n\r\n  /*\r\n    THE CATCH-ALL — the same route dev registers, built the same way, differing\r\n    only in where a module comes from. Registered last, and registered even when\r\n    the build carried no `404.page.tsx`, so a production deployment answers 404\r\n    with the right STATUS whether or not anyone has designed the page yet.\r\n  */\r\n  router.get(\r\n    NOT_FOUND_ROUTE_PATH,\r\n    createNotFoundRouteHandler({\r\n      renderPage:\r\n        notFoundPage === undefined\r\n          ? undefined\r\n          : createHandler({\r\n              path: NOT_FOUND_ROUTE_PATH,\r\n              name: NOT_FOUND_ROUTE_NAME,\r\n              appFile: app.sourceFile,\r\n              pageFile: notFoundPage.sourceFile,\r\n              // No layout, and therefore no layout middleware — see the dev\r\n              // installer for why the not-found path takes nothing that can\r\n              // redirect or throw.\r\n              layoutFile: undefined,\r\n              loadModule,\r\n              hydrationClientModuleUrl,\r\n              stylesheetUrls,\r\n              applyBufferedCookie,\r\n              matchPath: (requestPath) => requestPath,\r\n              statusForRenderedOk: 404,\r\n            }),\r\n    }),\r\n    // `isPage` for the same reason the dev installer carries it — the router's\r\n    // duplicate-name error reads the flag to say which claimant is the page.\r\n    { name: NOT_FOUND_ROUTE_NAME, isPage: true },\r\n  );\r\n\r\n  /*\r\n    Same publish as the dev installer, for the same reason: `href()` and the\r\n    router must agree, and they only can if both read the one loop that\r\n    registered the routes. Production installs once at boot, so the wholesale\r\n    replacement is a single write before the first request.\r\n  */\r\n  publishRouteTable(installed, \"installPageRoutesFromManifest (production)\");\r\n\r\n  return installed;\r\n}\r\n"],"mappings":"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"}
+{"version":3,"file":"install-page-routes-from-manifest.mjs","names":[],"sources":["C:/Work/Warlock.js/web/src/server/install-page-routes-from-manifest.ts"],"sourcesContent":["/**\r\n * Page-route registration for a built application.\r\n *\r\n * `installPageRoutes` answers \"which pages exist?\" by walking the filesystem\r\n * and \"what is this module?\" by asking Vite to evaluate it. Neither question\r\n * can be asked of a running production process: there is no `app/` tree beside\r\n * the bundle and no Vite. Both answers were therefore moved to build time — the\r\n * generated `pages.ts` barrel statically imported every page, layout and the\r\n * app root and handed them over as a {@link PageManifest}, and this module\r\n * turns that table into registered routes.\r\n *\r\n * WHAT IS DELIBERATELY IDENTICAL TO DEVELOPMENT: the route a page ends up on,\r\n * and the guards that run before it renders. A page's `route` export and the\r\n * `prefix` and `middleware` exports of EVERY layout on its path are read off the\r\n * module namespaces here, at boot, and composed by the same rules dev composes\r\n * them by ({@link layoutLevelOf}, {@link composeLayoutLevel}) — so the URL a page\r\n * answers on and the chain that guards it are decided by the page's own source\r\n * in both modes, and a build cannot quietly disagree with the dev server about\r\n * either.\r\n *\r\n * WHAT IS DELIBERATELY DIFFERENT: this is synchronous. Every module is already\r\n * in memory, so registration has nothing to await; the loader handed to each\r\n * handler is a lookup over the same table, not an evaluation step.\r\n */\r\nimport { composeRoutePath } from \"../routing/compose-route-path\";\r\nimport { deriveFilesystemRouteName, deriveFilesystemRoutePath } from \"../routing/filesystem-route\";\r\nimport { NestedLayoutsNotSupportedError, selectPageLayout } from \"../routing/layout-policy\";\r\nimport { canonicalizeRouteExport, deriveFallbackRouteName } from \"../routing/route-identity\";\r\nimport { publishRouteTable } from \"../routing/route-table\";\r\nimport { Response, type Router } from \"@warlock.js/core\";\r\nimport { createPageModuleLoader } from \"./create-page-module-loader\";\r\nimport type { ErrorPageModule } from \"./error-page\";\r\nimport {\r\n  createPageRouteHandler,\r\n  type PageRouteHandler,\r\n  type PageRouteHandlerOptions,\r\n} from \"./create-page-route-handler\";\r\nimport type { PipelineLoader, PipelineMiddleware } from \"./execute-page-request\";\nimport { isLoaderShortCircuit } from \"./settle-page-response\";\nimport { productionStylesheetUrls } from \"./stylesheet-urls\";\r\nimport {\r\n  createNotFoundRouteHandler,\r\n  DuplicateNotFoundPageError,\r\n  isNotFoundPageFile,\r\n  NotFoundPageDeclaresRouteError,\r\n  NOT_FOUND_ROUTE_NAME,\r\n  NOT_FOUND_ROUTE_PATH,\r\n  type RegisteredRouteShape,\r\n} from \"./not-found-page\";\r\nimport type { PageManifest, PageManifestLayoutEntry, PageManifestPageEntry } from \"./page-manifest\";\r\n\r\n/** A page declares either a bare path or a path plus an explicit route name. */\r\ntype PageRouteExport = string | { path: string; name?: string };\r\n\r\n/** The only export this module reads off a page module namespace. */\r\ntype PageModuleShape = {\r\n  route?: PageRouteExport;\r\n};\r\n\r\n/** The exports this module reads off a layout module namespace. */\r\ntype LayoutModuleShape = {\r\n  prefix?: string;\r\n  /**\r\n   * The default export — the thing that puts an element in the document, and\r\n   * therefore the ONLY export that decides whether a layout counts against the\r\n   * single-rendering-layout rule (`../routing/layout-policy.ts`). The manifest\r\n   * carries LOADED modules, so this is a fact rather than a guess, exactly as it\r\n   * is in dev (`install-page-routes.ts:145-150`).\r\n   */\r\n  default?: unknown;\r\n  /** The layout's guards, in the order it declared them. */\r\n  middleware?: readonly PipelineMiddleware[];\r\n  loader?: PipelineLoader;\r\n};\r\n\r\n/**\r\n * How a handler is built for one page. Defaults to `createPageRouteHandler`;\r\n * taking it as an input keeps this module's own job — reading the manifest and\r\n * registering routes — provable without a render pipeline behind it.\r\n */\r\nexport type PageRouteHandlerFactory = (options: PageRouteHandlerOptions) => PageRouteHandler;\r\n\r\nexport type InstalledManifestPageRoute = {\r\n  /** The canonical declared route path, before layout-prefix composition. */\r\n  declaredPath: string;\r\n  /** The composed path the route was registered on. */\r\n  path: string;\r\n  /** The resolved route name; shared namespace with API routes. */\r\n  name: string;\r\n  /** The page's manifest `sourceFile`. */\r\n  file: string;\r\n  /** The layout's manifest `sourceFile`, when the page has one. */\r\n  layoutFile: string | undefined;\r\n};\r\n\r\nexport type InstallPageRoutesFromManifestOptions = {\r\n  router: Router;\r\n  /** The table the generated production barrel provided at import time. */\r\n  manifest: PageManifest;\r\n  /** Browser module loaded after the server-rendered application and payload. */\r\n  hydrationClientModuleUrl?: string;\r\n  /**\r\n   * Where the client build wrote its output — `productionStylesheetUrls`'s own\r\n   * `clientDir` argument, forwarded here rather than pre-read into a flat list:\r\n   * each registered handler needs its OWN chain\r\n   * (`[root, ...outer-to-inner matched layouts, page]`, matched by the\r\n   * manifest's own `sourceFile` ids), not one list shared by every page.\r\n   *\r\n   * OPTIONAL for the same reason `PageManifest.clientDir` is: a build that\r\n   * discovered zero pages emits no client bundle, so there is no directory to\r\n   * read stylesheets from — and no page that could need one either.\r\n   */\r\n  clientDir?: string;\r\n  /** Same helper `dev-server.ts` exports — passed in, never imported. */\r\n  createHandler?: PageRouteHandlerFactory;\r\n};\r\n\r\n/**\r\n * `sourceFile`'s path relative to the web root — `src/web/**`, the only page\r\n * root discovery enumerates (`discoverWebRoots`,\r\n * `web/src/build/discover-pages.ts:210-213`). Manifest `sourceFile`s are\r\n * app-root-relative (`\"src/web/...\"`, `page-manifest.ts`'s own doc comment),\r\n * so dropping the first two segments — `<srcDir>`, then the literal `\"web\"` —\r\n * recovers exactly what `deriveFilesystemRoutePath`/`deriveFilesystemRouteName`\r\n * expect: the same value dev computes as `filesystemPageFileFor`\r\n * (`install-page-routes.ts:101-103`).\r\n */\r\nfunction webRelativeSourceFile(sourceFile: string): string {\r\n  return sourceFile.split(\"/\").slice(2).join(\"/\");\r\n}\r\n\r\nfunction resolveRoute(\r\n  routeExport: PageRouteExport | undefined,\r\n  sourceFile: string,\r\n): { path: string; name: string } {\r\n  if (routeExport === undefined) {\r\n    const pageFile = webRelativeSourceFile(sourceFile);\r\n\r\n    return {\r\n      path: deriveFilesystemRoutePath({ pageFile }),\r\n      name: deriveFilesystemRouteName(pageFile),\r\n    };\r\n  }\r\n\r\n  const canonical = canonicalizeRouteExport(routeExport);\r\n\r\n  return {\r\n    path: canonical.path,\r\n    name: canonical.name ?? deriveFallbackRouteName({ routePath: canonical.path, sourceFile }),\r\n  };\r\n}\r\n\r\n/**\r\n * Every layout's declared `prefix`, keyed by its directory relative to the\r\n * web root — the same table dev builds as `LayoutLevel.prefixesByDirectory`\r\n * (`install-page-routes.ts:214-222`) and the one\r\n * {@link deriveFilesystemRoutePath} uses to let a directory's own layout\r\n * rename the URL segment a bare directory name would otherwise contribute.\r\n */\r\nfunction layoutPrefixesOf(page: PageManifestPageEntry): Record<string, string> {\r\n  return Object.fromEntries(\r\n    page.layouts.flatMap((layout) => {\r\n      const prefix = (layout.module as LayoutModuleShape).prefix;\r\n\r\n      if (prefix === undefined) return [];\r\n\r\n      const relative = webRelativeSourceFile(layout.sourceFile);\r\n      const slashIndex = relative.lastIndexOf(\"/\");\r\n      const directory = slashIndex === -1 ? \"\" : relative.slice(0, slashIndex);\r\n\r\n      return [[directory, prefix]];\r\n    }),\r\n  );\r\n}\r\n\r\n/**\r\n * The page's layout LEVEL, resolved from the whole chain the manifest carries\r\n * rather than from the one layout nearest to it — the same resolution dev makes\r\n * (`install-page-routes.ts:138-164`), against loaded modules instead of Vite's.\r\n *\r\n * The manifest carries the FULL chain, outermost first, and the render pipeline\r\n * has exactly one layout slot per page (`execute-page-request.ts`'s\r\n * `PageRouteEntry[\"triple\"]`), so the chain has to be collapsed into one module\r\n * before it reaches a handler. Two things collapse differently and both matter:\r\n *\r\n * - RENDERING is a selection: at most one layout on the chain may render, and\r\n *   the policy picks it. `renders` is read off the loaded module\r\n *   (`typeof module.default !== \"undefined\"`), never off the entry's presence in\r\n *   the chain — a `middleware`-only layout has no default export and is not a\r\n *   wrapper. Passing bare `sourceFile` strings had every layout read as a\r\n *   rendering one, so boot refused a middleware-only guard chain that the build\r\n *   had already accepted: an application that builds and will not start.\r\n * - MIDDLEWARE and PREFIX are compositions: every layout on the path\r\n *   contributes, outermost first. A guard on an outer layout that the page's own\r\n *   directory knows nothing about is exactly the guard that must still run, and\r\n *   a prefix nobody composed is a URL nobody wrote down.\r\n *\r\n * A chain with more than one RENDERING layout is still refused here, at boot,\r\n * before a single request can observe the wrong document. Like the missing\r\n * app-root refusal below, that arm defends against stale or hand-edited build\r\n * artifacts: the build refuses to emit such a chain, but a manifest can reach a\r\n * running process without that build having produced it.\r\n */\r\ntype LayoutLevel = {\r\n  /**\r\n   * The layout entry the handler's layout slot is registered under, or\r\n   * `undefined` when the page has no layout at all: the layout that RENDERS,\r\n   * or — when none does — the nearest one, which is the slot production has\r\n   * always used and so the choice that changes nothing but the middleware for a\r\n   * chain with no wrapper in it.\r\n   */\r\n  host: PageManifestLayoutEntry | undefined;\r\n  /** Every layout's `prefix`, composed outermost first — `discoverPages`' own reduction. */\r\n  prefix: string;\r\n};\r\n\r\nfunction layoutLevelOf(page: PageManifestPageEntry): LayoutLevel {\r\n  const selection = selectPageLayout(\r\n    page.layouts.map((layout) => ({\r\n      layout: layout.sourceFile,\r\n      renders: typeof (layout.module as LayoutModuleShape).default !== \"undefined\",\r\n    })),\r\n  );\r\n\r\n  if (selection.type === \"rejected\") {\r\n    throw new NestedLayoutsNotSupportedError(page.sourceFile, selection.layouts);\r\n  }\r\n\r\n  return {\r\n    host:\r\n      selection.type === \"selected\"\r\n        ? page.layouts.find((layout) => layout.sourceFile === selection.layout)\r\n        : page.layouts.at(-1),\r\n    prefix: page.layouts.reduce(\r\n      (composed, layout) =>\r\n        composeRoutePath(composed, (layout.module as LayoutModuleShape).prefix ?? \"/\"),\r\n      \"/\",\r\n    ),\r\n  };\r\n}\r\n\r\n/**\r\n * The layout slot's module for one page: the slot host's own namespace, with the\r\n * whole chain's middleware in place of its own — outermost first, which is the\r\n * order stage 3 runs the array in (`execute-page-request.ts:519-524`) and the\r\n * order an outer `optionalAuth` needs in order to have resolved an identity\r\n * before an inner `gate()` checks it.\r\n *\r\n * Deliberately NOT core's route-level `middleware` option: that runs before the\r\n * pipeline's App-level middleware, which would invert outermost-first — the one\r\n * property this composition exists to guarantee.\r\n *\r\n * Built once at registration, not per request: unlike dev, every module here is\r\n * already in memory and cannot change under a running process.\r\n */\r\nfunction composeLayoutLevel(\r\n  page: PageManifestPageEntry,\r\n  host: PageManifestLayoutEntry,\r\n): Record<string, unknown> {\r\n  const hostIndex = page.layouts.indexOf(host);\r\n\r\n  return {\r\n    ...host.module,\r\n    middleware: page.layouts.flatMap((layout) => [\r\n      ...((layout.module as LayoutModuleShape).middleware ?? []),\r\n    ]),\r\n    loader: async (context: Parameters<NonNullable<LayoutModuleShape[\"loader\"]>>[0]) => {\r\n      let hostData: unknown;\r\n\r\n      for (let index = 0; index < page.layouts.length; index++) {\r\n        const value = await (page.layouts[index].module as LayoutModuleShape).loader?.(context);\r\n\r\n        if (value instanceof Response || isLoaderShortCircuit(value)) return value;\n        if (index === hostIndex) hostData = value;\r\n      }\r\n\r\n      return hostData;\r\n    },\r\n  };\r\n}\r\n\r\n/**\r\n * Registers every page the manifest carries into `options.router`.\r\n *\r\n * An empty manifest registers nothing and is not an error: \"built with web, no\r\n * pages\" is a legal state of a built application, and treating it as a failure\r\n * would make an empty project unbootable. A manifest that DOES carry pages but\r\n * no app root is the opposite — every page renders inside the application root,\r\n * so that combination is a broken table rather than an empty one, and it is\r\n * refused before any route exists to serve a request with a missing root.\r\n *\r\n * Two pages composing to the same path is refused the moment the second one is\r\n * seen, naming both — a registration-time failure, rather than a route one of\r\n * them silently loses at runtime.\r\n */\r\nexport function installPageRoutesFromManifest(\r\n  options: InstallPageRoutesFromManifestOptions,\r\n): InstalledManifestPageRoute[] {\r\n  const {\r\n    router,\r\n    manifest,\r\n    hydrationClientModuleUrl,\r\n    clientDir,\r\n    createHandler = createPageRouteHandler,\r\n  } = options;\r\n\r\n  if (manifest.pages.length === 0) return [];\r\n\r\n  const app = manifest.app;\r\n\r\n  if (app === undefined) {\r\n    throw new Error(\r\n      `installPageRoutesFromManifest: this build's page manifest carries ${manifest.pages.length} ` +\r\n        \"page(s) but no application root. Every page renders inside the app component, so no \" +\r\n        \"page can be registered without it. Re-run the build so the generated pages barrel \" +\r\n        \"provides an `app` entry.\",\r\n    );\r\n  }\r\n\r\n  // Ids are the manifest's own `sourceFile` strings and are passed on untouched:\r\n  // the loader below matches them by exact string equality, so resolving,\r\n  // joining or swapping separators on one side of that comparison would turn\r\n  // every lookup into a miss.\r\n  const loadModule = createPageModuleLoader(manifest);\r\n  // The namespace is already statically imported by the generated barrel, but\r\n  // do not hand it to the render pipeline until a request actually fails.\r\n  const loadErrorPage = manifest.errorPage === undefined\r\n    ? undefined\r\n    : async () => manifest.errorPage!.module as ErrorPageModule;\r\n\r\n  // Same partition development makes, on the same rule (the filename), so the\r\n  // two modes cannot disagree about which file is the not-found page. It is\r\n  // taken OUT of the registration loop rather than skipped inside it: every step\r\n  // in there composes and claims a URL, and `404.page.tsx` has none.\r\n  const notFoundPages = manifest.pages.filter((page) => isNotFoundPageFile(page.sourceFile));\r\n  const pages = manifest.pages.filter((page) => !isNotFoundPageFile(page.sourceFile));\r\n\r\n  if (notFoundPages.length > 1) {\r\n    throw new DuplicateNotFoundPageError(notFoundPages.map((page) => page.sourceFile));\r\n  }\r\n\r\n  const notFoundPage = notFoundPages[0];\r\n\r\n  if (notFoundPage !== undefined && (notFoundPage.module as PageModuleShape).route !== undefined) {\r\n    throw new NotFoundPageDeclaresRouteError(notFoundPage.sourceFile);\r\n  }\r\n\r\n  const installed: InstalledManifestPageRoute[] = [];\r\n  const fileByPath = new Map<string, string>();\r\n\r\n  for (const page of pages) {\r\n    const { host: layout, prefix: layoutPrefix } = layoutLevelOf(page);\r\n    const routeExport = (page.module as PageModuleShape).route;\r\n\r\n    const { path: routePath, name } = resolveRoute(routeExport, page.sourceFile);\r\n\r\n    // Explicit wins; otherwise the path is derived from the page's own source\r\n    // location and the layouts on its path — the same rule dev applies at\r\n    // registration (`install-page-routes.ts:377-382`) and discovery applies at\r\n    // build (`discover-pages.ts:925-935`), read here off the manifest's own\r\n    // `sourceFile`s instead of the filesystem.\r\n    const effectivePath =\r\n      routeExport === undefined\r\n        ? deriveFilesystemRoutePath({\r\n            pageFile: webRelativeSourceFile(page.sourceFile),\r\n            layoutPrefixes: layoutPrefixesOf(page),\r\n          })\r\n        : composeRoutePath(layoutPrefix, routePath);\r\n    const existingFile = fileByPath.get(effectivePath);\r\n\r\n    if (existingFile) {\r\n      throw new Error(\r\n        `installPageRoutesFromManifest: composed route path \"${effectivePath}\" (layout ` +\r\n          `prefix \"${layoutPrefix}\" + route.path \"${routePath}\") is declared by two pages — ` +\r\n          `\"${existingFile}\" and \"${page.sourceFile}\". Every page's composed route path must ` +\r\n          \"be unique.\",\r\n      );\r\n    }\r\n\r\n    fileByPath.set(effectivePath, page.sourceFile);\r\n\r\n    // The layout slot's id resolves to the COMPOSED level — every layout's\r\n    // middleware, in chain order — and every other id goes straight to the\r\n    // manifest lookup. A one-layout chain has nothing to compose, so it is left\r\n    // to resolve as the exact namespace object the manifest carries, untouched.\r\n    const composedLayout =\r\n      page.layouts.length > 1 && layout !== undefined\r\n        ? composeLayoutLevel(page, layout)\r\n        : undefined;\r\n\r\n    // Every registered handler gets ITS OWN immutable, ordered, deduped CSS\r\n    // chain: root, then every matched layout outer to inner (`page.layouts`,\r\n    // the manifest's own chain — the same one dev walks as\r\n    // `layoutLevel.chain`), then the page. `PageManifest.clientDir` is present\r\n    // whenever `pages` is non-empty (`page-manifest.ts`), which this loop only\r\n    // ever reaches when it is — `clientDir === undefined` is handled anyway,\r\n    // rather than trusted away, because a caller can still pass this function\r\n    // a manifest that violates its own generator's invariant.\r\n    const stylesheetUrls =\r\n      clientDir === undefined\r\n        ? []\r\n        : productionStylesheetUrls(clientDir, [\r\n            app.sourceFile,\r\n            ...page.layouts.map((pageLayout) => pageLayout.sourceFile),\r\n            page.sourceFile,\r\n          ]);\r\n\r\n    router.get(\r\n      effectivePath,\r\n      createHandler({\r\n        path: effectivePath,\r\n        name,\r\n        appFile: app.sourceFile,\r\n        pageFile: page.sourceFile,\r\n        layoutFile: layout?.sourceFile,\r\n        loadModule:\r\n          composedLayout === undefined\r\n            ? loadModule\r\n            : (moduleId) =>\r\n                moduleId === layout?.sourceFile\r\n                  ? Promise.resolve(composedLayout)\r\n                  : loadModule(moduleId),\r\n        loadRegistrationLayouts: () =>\r\n          Promise.resolve(page.layouts.map((layout) => layout.module)),\r\n        hydrationClientModuleUrl,\r\n        loadErrorPage,\r\n        stylesheetUrls,\r\n      }),\r\n      // `isPage` marks this route as SSR-served. Pages and API routes share one\r\n      // router and one route-name namespace, so the router's duplicate-name\r\n      // error reads this flag to say which claimant is the page.\r\n      { name, isPage: true },\r\n    );\r\n\r\n    installed.push({\r\n      declaredPath: routePath,\r\n      path: effectivePath,\r\n      name,\r\n      file: page.sourceFile,\r\n      layoutFile: layout?.sourceFile,\r\n    });\r\n  }\r\n\r\n  /*\r\n    THE CATCH-ALL — the same route dev registers, built the same way, differing\r\n    only in where a module comes from. Registered last, and registered even when\r\n    the build carried no `404.page.tsx`, so a production deployment answers 404\r\n    with the right STATUS whether or not anyone has designed the page yet.\r\n  */\r\n  router.get(\r\n    NOT_FOUND_ROUTE_PATH,\r\n    createNotFoundRouteHandler({\r\n      renderPage:\r\n        notFoundPage === undefined\r\n          ? undefined\r\n          : createHandler({\r\n              path: NOT_FOUND_ROUTE_PATH,\r\n              name: NOT_FOUND_ROUTE_NAME,\r\n              appFile: app.sourceFile,\r\n              pageFile: notFoundPage.sourceFile,\r\n              // No layout, and therefore no layout middleware — see the dev\r\n              // installer for why the not-found path takes nothing that can\r\n              // redirect or throw.\r\n              layoutFile: undefined,\r\n              loadModule,\r\n              hydrationClientModuleUrl,\r\n              loadErrorPage,\r\n              // NO LAYOUT means no layout CSS either — just root and the\r\n              // not-found page's own stylesheets, same reasoning as above.\r\n              stylesheetUrls:\r\n                clientDir === undefined\r\n                  ? []\r\n                  : productionStylesheetUrls(clientDir, [app.sourceFile, notFoundPage.sourceFile]),\r\n              matchPath: (requestPath) => requestPath,\n              statusForRenderedOk: 404,\n              skipPageLoader: true,\n            }),\n    }),\r\n    // `isPage` for the same reason the dev installer carries it — the router's\r\n    // duplicate-name error reads the flag to say which claimant is the page.\r\n    { name: NOT_FOUND_ROUTE_NAME, isPage: true },\r\n  );\r\n\r\n  /*\r\n    Same publish as the dev installer, for the same reason: `href()` and the\r\n    router must agree, and they only can if both read the one loop that\r\n    registered the routes. Production installs once at boot, so the wholesale\r\n    replacement is a single write before the first request.\r\n  */\r\n  publishRouteTable(installed, \"installPageRoutesFromManifest (production)\");\r\n\r\n  return installed;\r\n}\r\n"],"mappings":"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"}

package/esm/server/install-page-routes.d.mts

@@ -1,10 +1,9 @@
 import { composeRoutePath } from "../routing/compose-route-path.mjs";
-import { BufferedCookie } from "./buffered-response.mjs";
-import { PipelineMiddleware } from "./execute-page-request.types.mjs";
-import { Response, Router } from "@warlock.js/core";
+import { PipelineLoader, PipelineMiddleware } from "./execute-page-request.types.mjs";
+import { Router } from "@warlock.js/core";
 import { ViteDevServer } from "vite";
 
-//#region ../web/src/server/install-page-routes.d.ts
+//#region web/src/server/install-page-routes.d.ts
 type PageRouteExport = string | {
   path: string;
   name?: string;
@@ -13,12 +12,14 @@ type PageModuleShape = {
   route?: PageRouteExport;
 };
 type InstalledPageRoute = {
+  /** The canonical declared route path, before layout-prefix composition. */declaredPath: string;
   path: string;
   name: string;
   file: string;
   layoutFile: string | undefined;
 };
 type LayoutModuleShape = {
+  /** Universal registration hook; invoked on this real namespace, never a composed wrapper. */register?: () => unknown;
   prefix?: string;
   /**
    * The default export — the thing that puts an element in the document, and
@@ -28,21 +29,39 @@ type LayoutModuleShape = {
    */
   default?: unknown; /** The layout's guards, in the order it declared them. */
   middleware?: readonly PipelineMiddleware[];
+  loader?: PipelineLoader;
 };
 type InstallPageRoutesOptions = {
   router: Router;
   vite: ViteDevServer; /** v5/app/src — pages live under "<appSrcRoot>/app/*\/web/**" and "<appSrcRoot>/web/**". */
   appSrcRoot: string; /** v5/app/src/web/root.tsx — the single global app-root file. */
-  appFile: string; /** Browser module loaded after the server-rendered application and payload. */
-  hydrationClientModuleUrl?: string;
+  appFile: string;
   /**
-   * Stylesheet URLs emitted into every page's `<head>`.
+   * The application root Vite's dev server serves from — `dev-server.ts`'s
+   * `paths.appRoot`, i.e. `<appRoot>/src === appSrcRoot` by default. Every
+   * handler's stylesheet URLs are expressed relative to THIS, because that is
+   * the root Vite's dev server actually resolves `/…` URLs against
+   * (`stylesheet-urls.ts`'s `devStylesheetUrls`) — not `appSrcRoot`, which is
+   * one directory level in.
    *
-   * In dev these are Vite source URLs; see `devStylesheetUrls` for why they
-   * carry `?direct`.
+   * OPTIONAL and defaulted to `path.dirname(appSrcRoot)`: the caller that
+   * wires dev boot (`web-connector.ts`) does not pass this field today, and
+   * that default is exactly the relationship it constructs `appSrcRoot` from
+   * (`appSrcRoot = path.join(appRoot, "src")`) — correct for every actual
+   * deployment, and overridable by a caller with a non-default layout.
+   */
+  appRoot?: string; /** Browser module loaded after the server-rendered application and payload. */
+  hydrationClientModuleUrl?: string;
+  /**
+   * UNUSED. Retained on this type only because `web-connector.ts` still builds
+   * an options object naming it (`devStylesheetUrls(paths.appRoot,
+   * paths.appFile)`, computed once for the whole application). Each handler
+   * now computes its OWN stylesheet chain — `[root, ...outer-to-inner matched
+   * layouts, page]`, via `devHandlerStylesheetUrls` — inside the registration
+   * loop below, because a single application-wide list cannot express "this
+   * page's own CSS" without also carrying every other page's.
    */
-  stylesheetUrls?: readonly string[]; /** Same helper `dev-server.ts` exports — passed in, not imported, to avoid a dev-server.ts <-> this-file cycle. */
-  applyBufferedCookie: (response: Response, cookie: BufferedCookie) => void;
+  stylesheetUrls?: readonly string[];
 };
 /**
  * Registers every discoverable page into `options.router`. Throws
@@ -50,10 +69,8 @@ type InstallPageRoutesOptions = {
  * `route.path` — a registration-time failure, not a runtime 404 one of them
  * silently loses.
  *
- * Pages with no `route` export are REFUSED, not skipped, with the same
- * `MissingRouteExportError` the build throws: discovery cannot invent a public
- * URL for an undeclared page, and a dev server that silently drops the file you
- * just wrote is indistinguishable from a typo in the URL.
+ * Pages with no `route` export derive their path and name from their location
+ * below `src/web`, using the same pure filesystem-routing helper as the build.
  */
 declare function installPageRoutes(options: InstallPageRoutesOptions): Promise<InstalledPageRoute[]>;
 //#endregion

package/esm/server/install-page-routes.mjs

@@ -1,13 +1,18 @@
 import { publishRouteTable } from "../routing/route-table.mjs";
+import { isLoaderShortCircuit } from "./settle-page-response.mjs";
 import { composeRoutePath } from "../routing/compose-route-path.mjs";
+import { deriveFilesystemRouteName, deriveFilesystemRoutePath } from "../routing/filesystem-route.mjs";
 import { NestedLayoutsNotSupportedError, selectPageLayout } from "../routing/layout-policy.mjs";
-import { canonicalizeRouteExport, deriveFallbackRouteName } from "../routing/route-identity.mjs";
+import { canonicalizeRouteExport } from "../routing/route-identity.mjs";
 import { createPageRouteHandler } from "./create-page-route-handler.mjs";
+import { devHandlerStylesheetUrls } from "./stylesheet-urls.mjs";
 import { DuplicateNotFoundPageError, NOT_FOUND_ROUTE_NAME, NOT_FOUND_ROUTE_PATH, NotFoundPageDeclaresRouteError, createNotFoundRouteHandler, isNotFoundPageFile } from "./not-found-page.mjs";
-import { MissingRouteExportError, discoverPageFiles, layoutChainFor, toPosix } from "../build/discover-pages.mjs";
+import { NonLiteralRouteExportError, readRouteExports } from "../build/read-route-exports.mjs";
+import { ErrorPageDeclaresRouteError, discoverPageFiles, isErrorPageFile, layoutChainFor, toPosix } from "../build/discover-pages.mjs";
+import { Response } from "@warlock.js/core";
 import path from "node:path";
 
-//#region ../web/src/server/install-page-routes.ts
+//#region web/src/server/install-page-routes.ts
 /**
 * Registers every page {@link discoverPageFiles} finds under `<appSrcRoot>`
 * into Warlock's router (`router.get`, `core/src/router/router.ts:359-361`)
@@ -42,25 +47,38 @@ import path from "node:path";
 * page module must be the one Vite serves, warm cache and all.
 */
 /**
-* The page's app-root-relative POSIX source path, e.g.
-* ".../v5/app/src/app/main/web/home.page.tsx" with appSrcRoot
-* ".../v5/app/src" -> "src/app/main/web/home.page.tsx" — the canonical form
-* `deriveFallbackRouteName` (`../routing/route-identity`) requires. The first
-* segment's actual name is arbitrary to that function (it only inspects the
-* segment AFTER it), so `appSrcRoot`'s own basename is used rather than
-* discovering the true app root.
+* Ownership key for the framework's fallback 404 route. A NUL-prefixed value
+* cannot be a real filesystem path, so it cannot collide with an app page's
+* canonical source-file key.
+*/
+const FRAMEWORK_DEFAULT_NOT_FOUND_SOURCE_FILE = "\0warlock:framework-default-404";
+/**
+* The page's application-source-relative POSIX source path used as the router's
+* stable ownership key. `appSrcRoot`'s own basename preserves the existing
+* `src/web/...` source-file convention.
 */
 function canonicalSourceFileFor(pageFile, appSrcRoot) {
 	return `${path.basename(appSrcRoot)}/${toPosix(path.relative(appSrcRoot, pageFile))}`;
 }
-function resolveRoute(routeExport, sourceFile) {
-	const canonical = canonicalizeRouteExport(routeExport);
+function filesystemPageFileFor(pageFile, appSrcRoot) {
+	return toPosix(path.relative(path.join(appSrcRoot, "web"), pageFile));
+}
+/**
+* Resolve the stable identity used to distinguish a route-export edit from an
+* ordinary component-body edit. The declared path is retained before layout
+* composition so `/settings` under `/admin` compares with the next declared
+* `/settings`, not with the effective `/admin/settings` route.
+*/
+function resolvePageRouteIdentity(routeExport, pageFile, appSrcRoot) {
+	const filesystemPageFile = filesystemPageFileFor(pageFile, appSrcRoot);
+	if (routeExport === void 0) return {
+		declaredPath: deriveFilesystemRoutePath({ pageFile: filesystemPageFile }),
+		name: deriveFilesystemRouteName(filesystemPageFile)
+	};
+	const route = canonicalizeRouteExport(routeExport);
 	return {
-		path: canonical.path,
-		name: canonical.name ?? deriveFallbackRouteName({
-			routePath: canonical.path,
-			sourceFile
-		})
+		declaredPath: route.path,
+		name: route.name ?? deriveFilesystemRouteName(filesystemPageFile)
 	};
 }
 async function resolveLayoutLevel(pageFile, webRoot, loadLayout) {
@@ -74,7 +92,11 @@ async function resolveLayoutLevel(pageFile, webRoot, loadLayout) {
 	return {
 		chain,
 		layoutFile: selection.type === "selected" ? selection.layout : chain.at(-1),
-		prefix: modules.reduce((composed, layoutModule) => composeRoutePath(composed, layoutModule.prefix ?? "/"), "/")
+		prefix: modules.reduce((composed, layoutModule) => composeRoutePath(composed, layoutModule.prefix ?? "/"), "/"),
+		prefixesByDirectory: Object.fromEntries(chain.flatMap((layoutFile, index) => {
+			const prefix = modules[index].prefix;
+			return prefix === void 0 ? [] : [[toPosix(path.relative(webRoot, path.dirname(layoutFile))), prefix]];
+		}))
 	};
 }
 /**
@@ -89,9 +111,19 @@ async function resolveLayoutLevel(pageFile, webRoot, loadLayout) {
 */
 async function composeLayoutLevel(level, loadLayout) {
 	const modules = await Promise.all(level.chain.map(loadLayout));
+	const hostIndex = level.chain.indexOf(level.layoutFile);
 	return {
-		...modules[level.chain.indexOf(level.layoutFile)],
-		middleware: modules.flatMap((layoutModule) => [...layoutModule.middleware ?? []])
+		...modules[hostIndex],
+		middleware: modules.flatMap((layoutModule) => [...layoutModule.middleware ?? []]),
+		loader: async (context) => {
+			let hostData;
+			for (let index = 0; index < modules.length; index++) {
+				const value = await modules[index].loader?.(context);
+				if (value instanceof Response || isLoaderShortCircuit(value)) return value;
+				if (index === hostIndex) hostData = value;
+			}
+			return hostData;
+		}
 	};
 }
 /**
@@ -100,32 +132,47 @@ async function composeLayoutLevel(level, loadLayout) {
 * `route.path` — a registration-time failure, not a runtime 404 one of them
 * silently loses.
 *
-* Pages with no `route` export are REFUSED, not skipped, with the same
-* `MissingRouteExportError` the build throws: discovery cannot invent a public
-* URL for an undeclared page, and a dev server that silently drops the file you
-* just wrote is indistinguishable from a typo in the URL.
+* Pages with no `route` export derive their path and name from their location
+* below `src/web`, using the same pure filesystem-routing helper as the build.
 */
 async function installPageRoutes(options) {
-	const { router, vite, appSrcRoot, appFile, hydrationClientModuleUrl, stylesheetUrls, applyBufferedCookie } = options;
+	const { router, vite, appSrcRoot, appFile, hydrationClientModuleUrl } = options;
+	const stylesheetRoot = options.appRoot ?? path.dirname(appSrcRoot);
 	const discovered = [...discoverPageFiles(appSrcRoot)].sort((left, right) => left.pageFile < right.pageFile ? -1 : left.pageFile > right.pageFile ? 1 : 0);
+	const errorPageFiles = discovered.filter((page) => isErrorPageFile(page.pageFile));
 	const notFoundPageFiles = discovered.filter((page) => isNotFoundPageFile(page.pageFile));
-	const pageFiles = discovered.filter((page) => !isNotFoundPageFile(page.pageFile));
+	const pageFiles = discovered.filter((page) => !isNotFoundPageFile(page.pageFile) && !isErrorPageFile(page.pageFile));
+	if (errorPageFiles.length > 1) throw new Error(`Two error pages were found: ${errorPageFiles.map((page) => page.pageFile).join(", ")}.`);
+	const errorPageFile = errorPageFiles[0]?.pageFile;
+	if (errorPageFile !== void 0) {
+		const declarations = readRouteExports(errorPageFile);
+		if (!declarations.ok) throw new NonLiteralRouteExportError(declarations.rejection);
+		if (declarations.route !== void 0) throw new ErrorPageDeclaresRouteError(errorPageFile);
+	}
+	const loadErrorPage = errorPageFile === void 0 ? void 0 : () => vite.ssrLoadModule(errorPageFile);
 	if (notFoundPageFiles.length > 1) throw new DuplicateNotFoundPageError(notFoundPageFiles.map((page) => page.pageFile));
 	const installed = [];
 	const fileByPath = /* @__PURE__ */ new Map();
 	for (const { pageFile, webRoot } of pageFiles) {
 		const pageModule = await vite.ssrLoadModule(pageFile);
 		const sourceFile = canonicalSourceFileFor(pageFile, appSrcRoot);
-		if (pageModule.route === void 0) throw new MissingRouteExportError(sourceFile);
-		const { path: routePath, name } = resolveRoute(pageModule.route, sourceFile);
+		const { declaredPath: routePath, name } = resolvePageRouteIdentity(pageModule.route, pageFile, appSrcRoot);
 		const loadLayout = (layoutFile) => vite.ssrLoadModule(layoutFile);
 		const layoutLevel = await resolveLayoutLevel(pageFile, webRoot, loadLayout);
 		const { layoutFile, prefix: layoutPrefix } = layoutLevel;
-		const effectivePath = composeRoutePath(layoutPrefix, routePath);
+		const effectivePath = pageModule.route === void 0 ? deriveFilesystemRoutePath({
+			pageFile: filesystemPageFileFor(pageFile, appSrcRoot),
+			layoutPrefixes: layoutLevel.prefixesByDirectory
+		}) : composeRoutePath(layoutPrefix, routePath);
 		const existingFile = fileByPath.get(effectivePath);
 		if (existingFile) throw new Error(`installPageRoutes: composed route path "${effectivePath}" (layout prefix "${layoutPrefix}" + route.path "${routePath}") is declared by two pages (web/src/server/install-page-routes.ts) — "${existingFile}" and "${pageFile}". Every page's composed route path must be unique.`);
 		fileByPath.set(effectivePath, pageFile);
-		router.get(effectivePath, createPageRouteHandler({
+		const stylesheetUrls = devHandlerStylesheetUrls(stylesheetRoot, [
+			appFile,
+			...layoutLevel.chain,
+			pageFile
+		]);
+		await router.withSourceFile(sourceFile, () => router.get(effectivePath, createPageRouteHandler({
 			path: effectivePath,
 			name,
 			appFile,
@@ -135,26 +182,28 @@ async function installPageRoutes(options) {
 				...layoutLevel,
 				layoutFile
 			}, loadLayout) : vite.ssrLoadModule(moduleId) : (moduleId) => vite.ssrLoadModule(moduleId),
+			loadRegistrationLayouts: () => Promise.all(layoutLevel.chain.map(loadLayout)),
 			hydrationClientModuleUrl,
-			stylesheetUrls,
-			applyBufferedCookie
+			loadErrorPage,
+			stylesheetUrls
 		}), {
 			name,
 			isPage: true
-		});
+		}));
 		installed.push({
+			declaredPath: routePath,
 			path: effectivePath,
 			name,
 			file: pageFile,
 			layoutFile
 		});
 	}
-	if (discovered.length > 0) {
+	if (pageFiles.length > 0 || notFoundPageFiles.length > 0) {
 		const notFoundPageFile = notFoundPageFiles[0]?.pageFile;
 		if (notFoundPageFile !== void 0) {
 			if ((await vite.ssrLoadModule(notFoundPageFile)).route !== void 0) throw new NotFoundPageDeclaresRouteError(notFoundPageFile);
 		}
-		router.get("*", createNotFoundRouteHandler({ renderPage: notFoundPageFile === void 0 ? void 0 : createPageRouteHandler({
+		const registerNotFoundRoute = () => router.get("*", createNotFoundRouteHandler({ renderPage: notFoundPageFile === void 0 ? void 0 : createPageRouteHandler({
 			path: "*",
 			name: NOT_FOUND_ROUTE_NAME,
 			appFile,
@@ -162,19 +211,22 @@ async function installPageRoutes(options) {
 			layoutFile: void 0,
 			loadModule: (moduleId) => vite.ssrLoadModule(moduleId),
 			hydrationClientModuleUrl,
-			stylesheetUrls,
-			applyBufferedCookie,
+			loadErrorPage,
+			stylesheetUrls: devHandlerStylesheetUrls(stylesheetRoot, [appFile, notFoundPageFile]),
 			matchPath: (requestPath) => requestPath,
-			statusForRenderedOk: 404
+			statusForRenderedOk: 404,
+			skipPageLoader: true
 		}) }), {
 			name: NOT_FOUND_ROUTE_NAME,
 			isPage: true
 		});
+		if (notFoundPageFile === void 0) await router.withSourceFile(FRAMEWORK_DEFAULT_NOT_FOUND_SOURCE_FILE, registerNotFoundRoute);
+		else await router.withSourceFile(canonicalSourceFileFor(notFoundPageFile, appSrcRoot), registerNotFoundRoute);
 	}
 	publishRouteTable(installed, "installPageRoutes (dev)");
 	return installed;
 }
 
 //#endregion
-export { installPageRoutes };
+export { installPageRoutes, resolvePageRouteIdentity };
 //# sourceMappingURL=install-page-routes.mjs.map