@warlock.js/web 5.0.0

package/esm/server/match-page-route.mjs

@@ -0,0 +1,48 @@
+//#region ../web/src/server/match-page-route.ts
+/**
+* Stage 1 — turn a URL into a route entry plus its params.
+*
+* ⚠ **This is a SECOND matcher, and on the HTTP path it is redundant.** Core's
+* router has already matched by the time a page handler runs, and
+* `create-page-route-handler.ts` ignores the match it is handed. The one caller
+* that genuinely needs this is `renderPage(name, options)`, which synthesizes a
+* URL with no HTTP request behind it — and that path is not wired up
+* (`connectPageRoutes()` is never called).
+*
+* Removing it from the HTTP path is carded. Two things must be proven first:
+* that these params agree with core's, since `bundle.route.params` reaches the
+* hydration payload; and that dropping `bundle.route.query` — a public type
+* member — is announced rather than slipped in.
+*/
+function splitSegments(path) {
+	return path.split("/").filter((segment) => segment.length > 0);
+}
+function matchPath(pattern, pathname) {
+	const patternSegments = splitSegments(pattern);
+	const pathSegments = splitSegments(pathname);
+	if (patternSegments.length !== pathSegments.length) return void 0;
+	const params = {};
+	for (let index = 0; index < patternSegments.length; index++) {
+		const patternSegment = patternSegments[index];
+		const pathSegment = pathSegments[index];
+		if (patternSegment.startsWith(":")) {
+			params[patternSegment.slice(1)] = decodeURIComponent(pathSegment);
+			continue;
+		}
+		if (patternSegment !== pathSegment) return void 0;
+	}
+	return params;
+}
+function matchRoute(pathname, routes) {
+	for (const entry of routes) {
+		const params = matchPath(entry.path, pathname);
+		if (params) return {
+			entry,
+			params
+		};
+	}
+}
+
+//#endregion
+export { matchRoute };
+//# sourceMappingURL=match-page-route.mjs.map

package/esm/server/match-page-route.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"match-page-route.mjs","names":[],"sources":["../../../../../../../web/src/server/match-page-route.ts"],"sourcesContent":["import type { PageRouteEntry } from \"./execute-page-request.types\";\n\n/**\n * Stage 1 — turn a URL into a route entry plus its params.\n *\n * ⚠ **This is a SECOND matcher, and on the HTTP path it is redundant.** Core's\n * router has already matched by the time a page handler runs, and\n * `create-page-route-handler.ts` ignores the match it is handed. The one caller\n * that genuinely needs this is `renderPage(name, options)`, which synthesizes a\n * URL with no HTTP request behind it — and that path is not wired up\n * (`connectPageRoutes()` is never called).\n *\n * Removing it from the HTTP path is carded. Two things must be proven first:\n * that these params agree with core's, since `bundle.route.params` reaches the\n * hydration payload; and that dropping `bundle.route.query` — a public type\n * member — is announced rather than slipped in.\n */\n\nfunction splitSegments(path: string): string[] {\n  return path.split(\"/\").filter(segment => segment.length > 0);\n}\n\nexport function matchPath(\n  pattern: string,\n  pathname: string,\n): Record<string, string> | undefined {\n  const patternSegments = splitSegments(pattern);\n  const pathSegments = splitSegments(pathname);\n\n  if (patternSegments.length !== pathSegments.length) return undefined;\n\n  const params: Record<string, string> = {};\n\n  for (let index = 0; index < patternSegments.length; index++) {\n    const patternSegment = patternSegments[index];\n    const pathSegment = pathSegments[index];\n\n    if (patternSegment.startsWith(\":\")) {\n      params[patternSegment.slice(1)] = decodeURIComponent(pathSegment);\n      continue;\n    }\n\n    if (patternSegment !== pathSegment) return undefined;\n  }\n\n  return params;\n}\n\nexport function matchRoute(\n  pathname: string,\n  routes: readonly PageRouteEntry[],\n): { entry: PageRouteEntry; params: Record<string, string> } | undefined {\n  for (const entry of routes) {\n    const params = matchPath(entry.path, pathname);\n\n    if (params) return { entry, params };\n  }\n\n  return undefined;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAkBA,SAAS,cAAc,MAAwB;CAC7C,OAAO,KAAK,MAAM,GAAG,CAAC,CAAC,QAAO,YAAW,QAAQ,SAAS,CAAC;AAC7D;AAEA,SAAgB,UACd,SACA,UACoC;CACpC,MAAM,kBAAkB,cAAc,OAAO;CAC7C,MAAM,eAAe,cAAc,QAAQ;CAE3C,IAAI,gBAAgB,WAAW,aAAa,QAAQ,OAAO;CAE3D,MAAM,SAAiC,CAAC;CAExC,KAAK,IAAI,QAAQ,GAAG,QAAQ,gBAAgB,QAAQ,SAAS;EAC3D,MAAM,iBAAiB,gBAAgB;EACvC,MAAM,cAAc,aAAa;EAEjC,IAAI,eAAe,WAAW,GAAG,GAAG;GAClC,OAAO,eAAe,MAAM,CAAC,KAAK,mBAAmB,WAAW;GAChE;EACF;EAEA,IAAI,mBAAmB,aAAa,OAAO;CAC7C;CAEA,OAAO;AACT;AAEA,SAAgB,WACd,UACA,QACuE;CACvE,KAAK,MAAM,SAAS,QAAQ;EAC1B,MAAM,SAAS,UAAU,MAAM,MAAM,QAAQ;EAE7C,IAAI,QAAQ,OAAO;GAAE;GAAO;EAAO;CACrC;AAGF"}

package/esm/server/page-context.d.mts

@@ -0,0 +1 @@
+export { };

package/esm/server/page-context.mjs

@@ -0,0 +1,33 @@
+//#region ../web/src/server/page-context.ts
+/**
+* Boot-time wiring for the per-request context, once per process.
+*
+* The pipeline never owns an `AsyncLocalStorage` — it borrows core's. A VALUE
+* import of core from web risks resolving a second core instance, and two
+* copies of core means two stores, so `core` stays a type-only peer and the
+* code that already has `requestContext` in scope hands it over:
+*
+* ```ts
+* connectPageContext(requestContext);
+* connectSharedStore(() => requestContext.getStore());
+* ```
+*/
+let pageContextRunner;
+let additionalSharedScopeEntry;
+/** Returns the previous runner so tests can restore it. */
+function connectPageContext(runner) {
+	const previous = pageContextRunner;
+	pageContextRunner = runner;
+	return previous;
+}
+function enterAdditionalSharedScope(store) {
+	additionalSharedScopeEntry?.(store);
+}
+function requireRunner() {
+	if (!pageContextRunner) throw new Error("executePageRequest() has no request context connected (web/src/server/page-context.ts). The pipeline opens the per-request AsyncLocalStorage frame with CORE's own context — it never owns one itself. Fix: the server bootstrap must call connectPageContext(requestContext) (and connectSharedStore(() => requestContext.getStore())) before any page request runs.");
+	return pageContextRunner;
+}
+
+//#endregion
+export { connectPageContext, enterAdditionalSharedScope, requireRunner };
+//# sourceMappingURL=page-context.mjs.map

package/esm/server/page-context.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-context.mjs","names":[],"sources":["../../../../../../../web/src/server/page-context.ts"],"sourcesContent":["import type { PageContextRunner, PipelineStore } from \"./execute-page-request.types\";\n\n/**\n * Boot-time wiring for the per-request context, once per process.\n *\n * The pipeline never owns an `AsyncLocalStorage` — it borrows core's. A VALUE\n * import of core from web risks resolving a second core instance, and two\n * copies of core means two stores, so `core` stays a type-only peer and the\n * code that already has `requestContext` in scope hands it over:\n *\n * ```ts\n * connectPageContext(requestContext);\n * connectSharedStore(() => requestContext.getStore());\n * ```\n */\n\nlet pageContextRunner: PageContextRunner | undefined;\nlet additionalSharedScopeEntry: ((store: PipelineStore) => void) | undefined;\n\n/** Returns the previous runner so tests can restore it. */\nexport function connectPageContext(\n  runner: PageContextRunner | undefined,\n): PageContextRunner | undefined {\n  const previous = pageContextRunner;\n\n  pageContextRunner = runner;\n\n  return previous;\n}\n\n/**\n * Connect an additional shared-module instance that must enter every request.\n * Production has one module graph and needs none; the dev server uses this seam\n * for the Vite SSR graph that evaluates app code.\n */\nexport function connectPageSharedScope(\n  enter: ((store: PipelineStore) => void) | undefined,\n): ((store: PipelineStore) => void) | undefined {\n  const previous = additionalSharedScopeEntry;\n\n  additionalSharedScopeEntry = enter;\n\n  return previous;\n}\n\nexport function enterAdditionalSharedScope(store: PipelineStore): void {\n  additionalSharedScopeEntry?.(store);\n}\n\nexport function requireRunner(): PageContextRunner {\n  if (!pageContextRunner) {\n    throw new Error(\n      \"executePageRequest() has no request context connected \" +\n        \"(web/src/server/page-context.ts). The pipeline opens the per-request \" +\n        \"AsyncLocalStorage frame with CORE's own context — it never owns one \" +\n        \"itself. Fix: the server bootstrap must call \" +\n        \"connectPageContext(requestContext) (and \" +\n        \"connectSharedStore(() => requestContext.getStore())) before any \" +\n        \"page request runs.\",\n    );\n  }\n\n  return pageContextRunner;\n}\n"],"mappings":";;;;;;;;;;;;;;AAgBA,IAAI;AACJ,IAAI;;AAGJ,SAAgB,mBACd,QAC+B;CAC/B,MAAM,WAAW;CAEjB,oBAAoB;CAEpB,OAAO;AACT;AAiBA,SAAgB,2BAA2B,OAA4B;CACrE,6BAA6B,KAAK;AACpC;AAEA,SAAgB,gBAAmC;CACjD,IAAI,CAAC,mBACH,MAAM,IAAI,MACR,uWAOF;CAGF,OAAO;AACT"}

package/esm/server/page-manifest.d.mts

@@ -0,0 +1,102 @@
+//#region ../web/src/server/page-manifest.d.ts
+/**
+ * The build→runtime handoff table for production pages.
+ *
+ * The generated `<productionDir>/pages.ts` barrel — written by
+ * `web/src/build/generate-pages-barrel.ts` — statically imports every page,
+ * layout and the app root, then calls {@link providePageManifest} exactly
+ * once. The connector reads it back at boot with {@link consumePageManifest}.
+ *
+ * DEPENDENCY-FREE ON PURPOSE: this module is re-exported from web's root
+ * barrel (`web/src/index.ts`) so the generated barrel — which lives in the
+ * consuming app's production dir — can reach it by package specifier. Adding
+ * an import here would add that import to every app that loads
+ * `@warlock.js/web`.
+ *
+ * Entries carry MODULES + FILESYSTEM FACTS ONLY — never route paths. A page's
+ * route is read off its module (`route` export) at boot and composed with its
+ * layout `prefix`, exactly as `install-page-routes.ts:123-129,213-221` does in
+ * dev, so explicit-wins semantics live in one place for both modes.
+ */
+type PageManifestLayoutEntry = {
+  /** The imported layout module namespace object (default export = component, optional `prefix`). */module: Record<string, unknown>; /** App-root-relative POSIX source path, e.g. "src/app/main/web/layout.tsx". */
+  sourceFile: string;
+};
+type PageManifestPageEntry = {
+  /** The imported page module namespace object (default export = component, optional `route`). */module: Record<string, unknown>;
+  /**
+   * App-root-relative POSIX source path, e.g. "src/app/main/web/home.page.tsx"
+   * — feeds FS-derived route/name fallback. The anchor is the APP ROOT, not the
+   * repo root; the two differ the moment the app does not sit at the repo root.
+   * Consumers compare these ids VERBATIM — the barrel that wrote them is the
+   * authority on their form, and re-resolving or normalising one on the way in
+   * turns a lookup miss into a silent mis-match.
+   */
+  sourceFile: string; /** Layout chain, outermost first. */
+  layouts: readonly PageManifestLayoutEntry[];
+};
+type PageManifest = {
+  /**
+   * Where the client bundle was written, as an APP-ROOT-RELATIVE POSIX path
+   * (`"dist/client"`). Resolved against the process cwd at boot, the same
+   * anchor `sourceFile` uses.
+   *
+   * BAKED AT BUILD TIME because the runtime has no other way to learn it. The
+   * directory is `<build.outdir>/client`, and `build.outdir` is configurable —
+   * but it lives in `warlock.config.ts`, a BUILD-TIME file that is never
+   * shipped and cannot be loaded by the plain `node dist/app.js` process
+   * `warlock start` spawns. Reading it at runtime through
+   * `resolveBuildConfig()` is what used to throw
+   * `WarlockConfig not loaded` during connector boot, taking the whole server
+   * down before it could listen.
+   *
+   * OPTIONAL for the same reason `app` is: a zero-page build skips the client
+   * bundle entirely, so there is no directory to name. Present whenever
+   * `pages` is non-empty.
+   */
+  clientDir?: string;
+  /**
+   * The application root component every page renders inside.
+   *
+   * OPTIONAL because it is only meaningful when pages exist: a build that
+   * discovered zero pages provides `{ pages: [] }` and has no root to wrap
+   * anything in. The build enforces the other direction — pages without an
+   * app root fail generation — so `app` absent means `pages` is empty. Callers
+   * must still branch on `pages.length` before reading `app`: the invariant is
+   * the generator's, and a consumer that assumes it without checking turns a
+   * malformed manifest into a crash deep in rendering instead of a named error.
+   */
+  app?: {
+    module: Record<string, unknown>;
+    sourceFile: string;
+  };
+  /**
+   * The page table. EMPTY IS A REAL STATE, not a missing one: an empty array
+   * means "this bundle was built with web, and it has no pages", which is what
+   * separates it from {@link consumePageManifest} returning `undefined`.
+   */
+  pages: readonly PageManifestPageEntry[];
+};
+/**
+ * Called exactly once by the generated production/pages.ts barrel.
+ *
+ * A second call throws: two barrels in one process means either a stale
+ * generated file survived into the bundle or the build ran twice, and the
+ * second table silently replacing the first is precisely the drift this
+ * contract exists to make impossible.
+ */
+declare function providePageManifest(manifest: PageManifest): void;
+/**
+ * Connector-side read (WebConnector.boot, prod mode).
+ *
+ * `undefined` = no barrel ran → the app was not built with web. A manifest
+ * whose `pages` is empty is the OTHER answer — built with web, no pages — and
+ * the two are deliberately distinguishable here rather than collapsed into one
+ * falsy result. The registry itself never throws on absence — absence is a
+ * fact, not an error; the connector branches on MODE (prod: boot error; dev:
+ * normal) so `undefined` never means two things at one call site.
+ */
+declare function consumePageManifest(): PageManifest | undefined;
+//#endregion
+export { PageManifest, PageManifestLayoutEntry, PageManifestPageEntry, consumePageManifest, providePageManifest };
+//# sourceMappingURL=page-manifest.d.mts.map

package/esm/server/page-manifest.mjs

@@ -0,0 +1,31 @@
+//#region ../web/src/server/page-manifest.ts
+let providedManifest;
+/**
+* Called exactly once by the generated production/pages.ts barrel.
+*
+* A second call throws: two barrels in one process means either a stale
+* generated file survived into the bundle or the build ran twice, and the
+* second table silently replacing the first is precisely the drift this
+* contract exists to make impossible.
+*/
+function providePageManifest(manifest) {
+	if (providedManifest !== void 0) throw new Error("providePageManifest: a page manifest was already provided (web/src/server/page-manifest.ts). The generated production/pages.ts barrel must run exactly once per process.");
+	providedManifest = manifest;
+}
+/**
+* Connector-side read (WebConnector.boot, prod mode).
+*
+* `undefined` = no barrel ran → the app was not built with web. A manifest
+* whose `pages` is empty is the OTHER answer — built with web, no pages — and
+* the two are deliberately distinguishable here rather than collapsed into one
+* falsy result. The registry itself never throws on absence — absence is a
+* fact, not an error; the connector branches on MODE (prod: boot error; dev:
+* normal) so `undefined` never means two things at one call site.
+*/
+function consumePageManifest() {
+	return providedManifest;
+}
+
+//#endregion
+export { consumePageManifest, providePageManifest };
+//# sourceMappingURL=page-manifest.mjs.map

package/esm/server/page-manifest.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-manifest.mjs","names":[],"sources":["../../../../../../../web/src/server/page-manifest.ts"],"sourcesContent":["/**\n * The build→runtime handoff table for production pages.\n *\n * The generated `<productionDir>/pages.ts` barrel — written by\n * `web/src/build/generate-pages-barrel.ts` — statically imports every page,\n * layout and the app root, then calls {@link providePageManifest} exactly\n * once. The connector reads it back at boot with {@link consumePageManifest}.\n *\n * DEPENDENCY-FREE ON PURPOSE: this module is re-exported from web's root\n * barrel (`web/src/index.ts`) so the generated barrel — which lives in the\n * consuming app's production dir — can reach it by package specifier. Adding\n * an import here would add that import to every app that loads\n * `@warlock.js/web`.\n *\n * Entries carry MODULES + FILESYSTEM FACTS ONLY — never route paths. A page's\n * route is read off its module (`route` export) at boot and composed with its\n * layout `prefix`, exactly as `install-page-routes.ts:123-129,213-221` does in\n * dev, so explicit-wins semantics live in one place for both modes.\n */\n\nexport type PageManifestLayoutEntry = {\n  /** The imported layout module namespace object (default export = component, optional `prefix`). */\n  module: Record<string, unknown>;\n  /** App-root-relative POSIX source path, e.g. \"src/app/main/web/layout.tsx\". */\n  sourceFile: string;\n};\n\nexport type PageManifestPageEntry = {\n  /** The imported page module namespace object (default export = component, optional `route`). */\n  module: Record<string, unknown>;\n  /**\n   * App-root-relative POSIX source path, e.g. \"src/app/main/web/home.page.tsx\"\n   * — feeds FS-derived route/name fallback. The anchor is the APP ROOT, not the\n   * repo root; the two differ the moment the app does not sit at the repo root.\n   * Consumers compare these ids VERBATIM — the barrel that wrote them is the\n   * authority on their form, and re-resolving or normalising one on the way in\n   * turns a lookup miss into a silent mis-match.\n   */\n  sourceFile: string;\n  /** Layout chain, outermost first. */\n  layouts: readonly PageManifestLayoutEntry[];\n};\n\nexport type PageManifest = {\n  /**\n   * Where the client bundle was written, as an APP-ROOT-RELATIVE POSIX path\n   * (`\"dist/client\"`). Resolved against the process cwd at boot, the same\n   * anchor `sourceFile` uses.\n   *\n   * BAKED AT BUILD TIME because the runtime has no other way to learn it. The\n   * directory is `<build.outdir>/client`, and `build.outdir` is configurable —\n   * but it lives in `warlock.config.ts`, a BUILD-TIME file that is never\n   * shipped and cannot be loaded by the plain `node dist/app.js` process\n   * `warlock start` spawns. Reading it at runtime through\n   * `resolveBuildConfig()` is what used to throw\n   * `WarlockConfig not loaded` during connector boot, taking the whole server\n   * down before it could listen.\n   *\n   * OPTIONAL for the same reason `app` is: a zero-page build skips the client\n   * bundle entirely, so there is no directory to name. Present whenever\n   * `pages` is non-empty.\n   */\n  clientDir?: string;\n  /**\n   * The application root component every page renders inside.\n   *\n   * OPTIONAL because it is only meaningful when pages exist: a build that\n   * discovered zero pages provides `{ pages: [] }` and has no root to wrap\n   * anything in. The build enforces the other direction — pages without an\n   * app root fail generation — so `app` absent means `pages` is empty. Callers\n   * must still branch on `pages.length` before reading `app`: the invariant is\n   * the generator's, and a consumer that assumes it without checking turns a\n   * malformed manifest into a crash deep in rendering instead of a named error.\n   */\n  app?: { module: Record<string, unknown>; sourceFile: string };\n  /**\n   * The page table. EMPTY IS A REAL STATE, not a missing one: an empty array\n   * means \"this bundle was built with web, and it has no pages\", which is what\n   * separates it from {@link consumePageManifest} returning `undefined`.\n   */\n  pages: readonly PageManifestPageEntry[];\n};\n\nlet providedManifest: PageManifest | undefined;\n\n/**\n * Called exactly once by the generated production/pages.ts barrel.\n *\n * A second call throws: two barrels in one process means either a stale\n * generated file survived into the bundle or the build ran twice, and the\n * second table silently replacing the first is precisely the drift this\n * contract exists to make impossible.\n */\nexport function providePageManifest(manifest: PageManifest): void {\n  if (providedManifest !== undefined) {\n    throw new Error(\n      \"providePageManifest: a page manifest was already provided \" +\n        \"(web/src/server/page-manifest.ts). The generated production/pages.ts barrel \" +\n        \"must run exactly once per process.\",\n    );\n  }\n\n  providedManifest = manifest;\n}\n\n/**\n * Connector-side read (WebConnector.boot, prod mode).\n *\n * `undefined` = no barrel ran → the app was not built with web. A manifest\n * whose `pages` is empty is the OTHER answer — built with web, no pages — and\n * the two are deliberately distinguishable here rather than collapsed into one\n * falsy result. The registry itself never throws on absence — absence is a\n * fact, not an error; the connector branches on MODE (prod: boot error; dev:\n * normal) so `undefined` never means two things at one call site.\n */\nexport function consumePageManifest(): PageManifest | undefined {\n  return providedManifest;\n}\n"],"mappings":";AAmFA,IAAI;;;;;;;;;AAUJ,SAAgB,oBAAoB,UAA8B;CAChE,IAAI,qBAAqB,QACvB,MAAM,IAAI,MACR,0KAGF;CAGF,mBAAmB;AACrB;;;;;;;;;;;AAYA,SAAgB,sBAAgD;CAC9D,OAAO;AACT"}

package/esm/server/render-page.mjs

@@ -0,0 +1,214 @@
+import { DocumentContext, PAYLOAD_SCRIPT_ID, escapePayload } from "../components/document-context.mjs";
+import DefaultApp from "../components/default-app.mjs";
+import { buildHydrationPayload } from "./build-hydration-payload.mjs";
+import { buildErrorRecord, designateBoundary } from "./settle-page-response.mjs";
+import { executePageRequest } from "./execute-page-request.mjs";
+import { createElement } from "react";
+
+//#region ../web/src/server/render-page.ts
+let pageRoutesRegistry;
+function requireRegistry(options) {
+	const routes = options.routes ?? pageRoutesRegistry?.routes;
+	const createHttp = options.createHttp ?? pageRoutesRegistry?.createHttp;
+	if (!routes || !createHttp) throw new Error("renderPage()/renderPageRequest() has no route registry connected (web/src/server/render-page.ts). Both resolve against the page manifest, which the server bootstrap owns. Fix: call connectPageRoutes({ routes, createHttp }) at boot (tests: in beforeAll), or pass { routes, createHttp } to this call.");
+	return {
+		routes,
+		createHttp
+	};
+}
+/**
+* The framework-owned terminal boundary (P1 §4: designation falls back to
+* `app` even when no level exports one — "the framework owns a root
+* boundary"). Deliberately generic: the error itself is server knowledge and
+* never serialized into the document.
+*/
+function FrameworkRootBoundary() {
+	return createElement("main", { role: "alert" }, "Something went wrong.");
+}
+const DATA_KEYS = {
+	app: "appData",
+	layout: "layoutData",
+	page: "pageData"
+};
+/**
+* Compose the tree root→leaf: `<App><Layout><Page/></Layout></App>`, each
+* level receiving ITS OWN loader data and the same sealed `shared` — the
+* exact props the M1 contract declares (web/src/props.ts) and never
+* request/response (the component also renders on a machine where neither
+* exists, props.ts:19-22).
+*
+* A level with no default export contributes no DOM and passes children
+* through — that is `layout.tsx` omitting its default export to be a guard
+* with no DOM.
+*/
+function buildPageElement(triple, bundle) {
+	return wrapRootward(triple, bundle, "page", buildLeaf(triple.page, bundle, "page"));
+}
+/**
+* The error path renders the DESIGNATED boundary in place of the level it
+* covers, still wrapped by every level rootward of it — a page-level throw
+* keeps its App and Layout chrome, whose data survived the settle rules
+* (P1 §4: fulfilled sibling data stays in the bundle).
+*
+* `record` is explicit rather than read from `bundle.error` — a render-time
+* throw (`finishRender`'s stage 9 escalation loop) designates a NEW boundary on the fly that the stage 1-8 bundle never saw.
+*/
+function buildBoundaryElement(triple, bundle, record) {
+	const { boundary, error } = record;
+	const Boundary = triple[boundary.boundaryLevel].ErrorBoundary;
+	const element = Boundary ? createElement(Boundary, { error }) : createElement(FrameworkRootBoundary, {});
+	const wrapped = wrapRootward(triple, bundle, boundary.boundaryLevel, element);
+	return boundary.boundaryLevel === "app" ? createElement(DefaultApp, { children: wrapped }) : wrapped;
+}
+function buildLeaf(module, bundle, level) {
+	const Component = module.default;
+	if (!Component) return null;
+	return createElement(Component, {
+		data: bundle[DATA_KEYS[level]],
+		shared: bundle.shared
+	});
+}
+function wrapRootward(triple, bundle, from, leaf) {
+	const wrappers = from === "page" ? ["layout", "app"] : from === "layout" ? ["app"] : [];
+	let element = leaf;
+	for (const level of wrappers) {
+		const Component = triple[level].default;
+		if (!Component) {
+			if (level === "app") element = createElement(DefaultApp, { children: element });
+			continue;
+		}
+		element = createElement(Component, {
+			data: bundle[DATA_KEYS[level]],
+			shared: bundle.shared,
+			children: element
+		});
+	}
+	return element;
+}
+/**
+* The root (App or the framework default) now ALWAYS renders a complete
+* `<html>…</html>` document itself — `<Head/>`/
+* `<Scripts/>` read the metadata/payload from `DocumentContext` (provided
+* around the element in `finishRender`, below) and emit real elements.
+* There is nothing left for this stage to assemble by string surgery; it
+* only prepends the doctype `renderToString` never includes.
+*/
+function emitDocument(body) {
+	return "<!DOCTYPE html>" + body;
+}
+/**
+* Wrap the caller's createHttp to capture the real pair (for the document
+* slots, `documentSlotsFrom` below), the matched entry (the only place a
+* URL-based caller learns which triple to render), and to apply `as` —
+* `user` is a plain public property on core's Request
+* (core/src/http/request.ts:92), exactly the write auth middleware performs.
+*/
+function capturingCreateHttp(registry, as) {
+	const state = {};
+	return {
+		state,
+		createHttp(match) {
+			state.match = match;
+			state.captured = registry.createHttp(match);
+			if (as !== void 0) state.captured.request.user = as;
+			return state.captured;
+		}
+	};
+}
+/**
+* Structural read of the two core `Request` fields the slots need. Neither
+* `nonce` nor `locale` is declared on `PipelineRequest`/`WebRequest` (the
+* loader-facing facade only declares `validated`/`input`/`user`,
+* context.ts:30-68) — a narrow typed intersection at the one call site that
+* needs it, the same pattern `execute-page-request.ts` uses for its own
+* `(response as PipelineResponse & { statusCode?: number })` read
+* (execute-page-request.ts:517).
+*/
+function documentSlotsFrom(captured) {
+	const request = captured?.request;
+	return {
+		nonce: request?.nonce,
+		lang: request?.locale
+	};
+}
+async function finishRender(triple, bundle, documentSlots) {
+	const headers = {};
+	for (const header of bundle.commit?.headers ?? []) headers[header.key.toLowerCase()] = header.value;
+	const cookies = bundle.commit?.cookies ?? [];
+	if (bundle.shortCircuit) return {
+		html: "",
+		status: bundle.shortCircuit.stage === "validation" ? bundle.shortCircuit.status : bundle.shortCircuit.stage === "loaders" ? bundle.shortCircuit.statusCode : bundle.shortCircuit.statusCode ?? 200,
+		headers,
+		cookies,
+		data: bundle.pageData,
+		bundle
+	};
+	if (headers["cache-control"] === void 0) headers["cache-control"] = "private";
+	const { renderToString } = await import("react-dom/server");
+	const documentValue = {
+		metadata: bundle.metadata,
+		payload: buildHydrationPayload(bundle),
+		nonce: documentSlots.nonce,
+		lang: documentSlots.lang
+	};
+	const renderWithContext = (element) => renderToString(createElement(DocumentContext.Provider, {
+		value: documentValue,
+		children: element
+	}));
+	let currentError = bundle.error;
+	let renderTimeThrow = false;
+	let body;
+	for (;;) try {
+		body = renderWithContext(currentError ? buildBoundaryElement(triple, bundle, currentError) : buildPageElement(triple, bundle));
+		break;
+	} catch (thrown) {
+		renderTimeThrow = true;
+		if (currentError?.boundary.boundaryLevel === "app") {
+			body = renderWithContext(createElement(DefaultApp, { children: createElement(FrameworkRootBoundary, {}) }));
+			break;
+		}
+		currentError = buildErrorRecord(thrown, designateBoundary(currentError?.boundary.boundaryLevel === "layout" ? "app" : currentError ? "layout" : "page", triple));
+	}
+	const status = renderTimeThrow ? currentError.boundary.boundaryLevel === "app" ? 500 : bundle.commit?.statusCode ?? 200 : bundle.error ? bundle.commit?.statusCode ?? 500 : bundle.commit?.statusCode ?? 200;
+	return {
+		html: emitDocument(body),
+		status,
+		headers,
+		cookies,
+		data: bundle.pageData,
+		bundle
+	};
+}
+/**
+* The URL-based sibling of `renderPage` — the production render surface: a
+* real HTTP server has a URL, not a route name. The url goes STRAIGHT to
+* executePageRequest's stage-1 matcher (no buildUrl), then the same shared
+* tail renders and emits.
+*
+* No-match here is NOT the manifest bug renderPage throws on: an arbitrary
+* URL matching no route is a legitimate 404, and a server must ANSWER it —
+* `{ html: "", status: 404 }` with an undefined `bundle` (see RenderedPage).
+*/
+async function renderPageRequest(url, options = {}) {
+	const registry = requireRegistry(options);
+	const { state, createHttp } = capturingCreateHttp(registry, options.as);
+	const rendered = await executePageRequest({
+		url,
+		routes: registry.routes,
+		createHttp,
+		finish: (bundle) => finishRender(state.match.entry.triple, bundle, documentSlotsFrom(state.captured))
+	});
+	if (!rendered) return {
+		html: "",
+		status: 404,
+		headers: {},
+		cookies: [],
+		data: void 0,
+		bundle: void 0
+	};
+	return rendered;
+}
+
+//#endregion
+export { renderPageRequest };
+//# sourceMappingURL=render-page.mjs.map

package/esm/server/render-page.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-page.mjs","names":[],"sources":["../../../../../../../web/src/server/render-page.ts"],"sourcesContent":["import { createElement, type ComponentType, type ReactNode } from \"react\";\nimport DefaultApp from \"../components/default-app\";\nimport {\n  DocumentContext,\n  escapePayload,\n  PAYLOAD_SCRIPT_ID,\n  type DocumentContextValue,\n} from \"../components/document-context\";\nimport type { SharedContext } from \"../index\";\nimport { buildHydrationPayload } from \"./build-hydration-payload\";\nimport type { BufferedCookie } from \"./buffered-response\";\nimport {\n  buildErrorRecord,\n  designateBoundary,\n  executePageRequest,\n  type ExecutePageRequestOptions,\n  type PageDataBundle,\n  type PageErrorRecord,\n  type PageLevelName,\n  type PageRouteEntry,\n  type PageRouteMatch,\n  type PageTripleModule,\n  type PipelineRequest,\n  type PipelineResponse,\n} from \"./execute-page-request\";\n\nexport { escapePayload, PAYLOAD_SCRIPT_ID };\n\n/**\n * Pipeline stages 9–10: RENDER the page tree from the\n * data bundle stages 1–8 produced, then return finalized { html, status,\n * headers, cookies }. Stage 10 happens at the CALL SITE in two halves —\n * 10a the caller applies status + headers (the single live-response write,\n * after render, before anything flushes), 10b it flushes\n * the document. Nothing in this module writes the live response. It never\n * re-runs any earlier stage — `renderPage` calls `executePageRequest` and\n * everything here consumes its bundle as-is.\n *\n * `renderPage` is deliberately double-duty (dx-differentiators.md §3): it is\n * the production orchestrator AND the test helper. Because a loader IS a\n * controller, `renderPage(\"products.details\", { params: { id: \"42\" } })`\n * returns `{ html, status, headers, data }` in one call — asserting a page's\n * data and its response headers is a unit test, no browser, no server boot.\n */\n\n// ---------------------------------------------------------------------------\n// The routes seam (same pattern as connectPageContext: boot wiring, once)\n// ---------------------------------------------------------------------------\n\nexport type PageRoutesRegistry = {\n  routes: readonly PageRouteEntry[];\n  /** Same contract as ExecutePageRequestOptions[\"createHttp\"]. */\n  createHttp: ExecutePageRequestOptions[\"createHttp\"];\n};\n\nlet pageRoutesRegistry: PageRoutesRegistry | undefined;\n\n/**\n * Boot-time wiring so `renderPage(name, options)` can resolve a route NAME\n * without each call site carrying the manifest. Returns the previous registry\n * so tests can restore it. A per-call `routes`/`createHttp` override wins.\n */\nexport function connectPageRoutes(\n  registry: PageRoutesRegistry | undefined,\n): PageRoutesRegistry | undefined {\n  const previous = pageRoutesRegistry;\n  pageRoutesRegistry = registry;\n  return previous;\n}\n\n// ---------------------------------------------------------------------------\n// renderPage surface\n// ---------------------------------------------------------------------------\n\nexport type RenderPageOptions = {\n  params?: Record<string, string>;\n  query?: Record<string, string>;\n  /**\n   * Impersonation for tests: assigned to `request.user` right after the\n   * request pair is constructed — `user` is a plain public property on core's\n   * Request (core/src/http/request.ts:92) and this is exactly the write auth\n   * middleware would have performed.\n   */\n  as?: unknown;\n  /** Per-call overrides of the connected registry (tests, mostly). */\n  routes?: readonly PageRouteEntry[];\n  createHttp?: ExecutePageRequestOptions[\"createHttp\"];\n};\n\n/**\n * `renderPageRequest` takes the URL itself, so `params`/`query` (the\n * name-based sugar buildUrl consumes) have no meaning here — everything else\n * is the same seam.\n */\nexport type RenderPageRequestOptions = Omit<RenderPageOptions, \"params\" | \"query\">;\n\nexport type RenderedPage = {\n  /** The full document (\"\" when the pipeline short-circuited before render). */\n  html: string;\n  status: number;\n  /** Committed response headers, lowercased key → value. */\n  headers: Record<string, string>;\n  /**\n   * Committed cookies in commit order, attribute-faithful: each entry carries\n   * the loader's raw value (pre-serialization) AND its options\n   * (`httpOnly`/`secure`/`sameSite`/`path`/`expires`/…). Never flattened to a\n   * name→value map — a map cannot express the attributes, and a Set-Cookie\n   * built without them is a security defect, not a convenience.\n   */\n  cookies: BufferedCookie[];\n  /**\n   * The PAGE loader's data — `data.product.name` reads as the dx story\n   * writes it. `unknown`: the pipeline never checks a loader's return shape.\n   */\n  data: unknown;\n  /**\n   * The full stages-1–8 bundle, for assertions beyond the page's own data.\n   * Undefined ONLY on `renderPageRequest`'s no-match path: no route matched,\n   * so no pipeline ran and there is no bundle — the 404 answer stands alone.\n   * `renderPage` always carries one (its no-match throws instead).\n   */\n  bundle: PageDataBundle | undefined;\n};\n\nfunction requireRegistry(\n  options: Pick<RenderPageOptions, \"routes\" | \"createHttp\">,\n): PageRoutesRegistry {\n  const routes = options.routes ?? pageRoutesRegistry?.routes;\n  const createHttp = options.createHttp ?? pageRoutesRegistry?.createHttp;\n\n  if (!routes || !createHttp) {\n    throw new Error(\n      \"renderPage()/renderPageRequest() has no route registry connected \" +\n        \"(web/src/server/render-page.ts). Both resolve against the page \" +\n        \"manifest, which the server bootstrap owns. Fix: \" +\n        \"call connectPageRoutes({ routes, createHttp }) at boot (tests: in \" +\n        \"beforeAll), or pass { routes, createHttp } to this call.\",\n    );\n  }\n\n  return { routes, createHttp };\n}\n\nfunction buildUrl(\n  entry: PageRouteEntry,\n  params: Record<string, string>,\n  query: Record<string, string>,\n): string {\n  const path = entry.path\n    .split(\"/\")\n    .map(segment => {\n      if (!segment.startsWith(\":\")) return segment;\n\n      const name = segment.slice(1);\n      const value = params[name];\n\n      if (value === undefined) {\n        throw new Error(\n          `renderPage(\"${entry.name}\"): route path \"${entry.path}\" needs ` +\n            `param \"${name}\" and the call did not provide it ` +\n            \"(web/src/server/render-page.ts). Fix: pass it in \" +\n            `\\`params: { ${name}: … }\\`.`,\n        );\n      }\n\n      return encodeURIComponent(value);\n    })\n    .join(\"/\");\n\n  const queryString = new URLSearchParams(query).toString();\n\n  return queryString ? `${path}?${queryString}` : path;\n}\n\n// ---------------------------------------------------------------------------\n// Stage 9 — RENDER\n// ---------------------------------------------------------------------------\n\n/**\n * The framework-owned terminal boundary (P1 §4: designation falls back to\n * `app` even when no level exports one — \"the framework owns a root\n * boundary\"). Deliberately generic: the error itself is server knowledge and\n * never serialized into the document.\n */\nfunction FrameworkRootBoundary(): ReactNode {\n  return createElement(\"main\", { role: \"alert\" }, \"Something went wrong.\");\n}\n\ntype LevelProps = {\n  data: unknown;\n  shared: Readonly<SharedContext> | undefined;\n  children?: ReactNode;\n};\n\nconst DATA_KEYS: Record<PageLevelName, \"appData\" | \"layoutData\" | \"pageData\"> = {\n  app: \"appData\",\n  layout: \"layoutData\",\n  page: \"pageData\",\n};\n\n/**\n * Compose the tree root→leaf: `<App><Layout><Page/></Layout></App>`, each\n * level receiving ITS OWN loader data and the same sealed `shared` — the\n * exact props the M1 contract declares (web/src/props.ts) and never\n * request/response (the component also renders on a machine where neither\n * exists, props.ts:19-22).\n *\n * A level with no default export contributes no DOM and passes children\n * through — that is `layout.tsx` omitting its default export to be a guard\n * with no DOM.\n */\nfunction buildPageElement(\n  triple: Record<PageLevelName, PageTripleModule>,\n  bundle: PageDataBundle,\n): ReactNode {\n  return wrapRootward(triple, bundle, \"page\", buildLeaf(triple.page, bundle, \"page\"));\n}\n\n/**\n * The error path renders the DESIGNATED boundary in place of the level it\n * covers, still wrapped by every level rootward of it — a page-level throw\n * keeps its App and Layout chrome, whose data survived the settle rules\n * (P1 §4: fulfilled sibling data stays in the bundle).\n *\n * `record` is explicit rather than read from `bundle.error` — a render-time\n * throw (`finishRender`'s stage 9 escalation loop) designates a NEW boundary on the fly that the stage 1-8 bundle never saw.\n */\nfunction buildBoundaryElement(\n  triple: Record<PageLevelName, PageTripleModule>,\n  bundle: PageDataBundle,\n  record: PageErrorRecord,\n): ReactNode {\n  const { boundary, error } = record;\n  const Boundary = triple[boundary.boundaryLevel].ErrorBoundary as\n    | ((props: { error: unknown }) => ReactNode)\n    | undefined;\n\n  const element = Boundary\n    ? createElement(Boundary, { error })\n    : createElement(FrameworkRootBoundary, {});\n\n  const wrapped = wrapRootward(triple, bundle, boundary.boundaryLevel, element);\n\n  // \"App\" has no level rootward of it, so `wrapRootward` returns `wrapped`\n  // unwrapped when the boundary covers the app level itself — but the\n  // pipeline always emits a complete document, so the\n  // framework default supplies the shell here even though the app's own\n  // (broken) root is what's being bypassed.\n  return boundary.boundaryLevel === \"app\"\n    ? createElement(DefaultApp, { children: wrapped })\n    : wrapped;\n}\n\nfunction buildLeaf(\n  module: PageTripleModule,\n  bundle: PageDataBundle,\n  level: PageLevelName,\n): ReactNode {\n  const Component = module.default as ((props: LevelProps) => ReactNode) | undefined;\n\n  if (!Component) return null;\n\n  return createElement(Component as ComponentType<LevelProps>, {\n    data: bundle[DATA_KEYS[level]],\n    shared: bundle.shared,\n  });\n}\n\nfunction wrapRootward(\n  triple: Record<PageLevelName, PageTripleModule>,\n  bundle: PageDataBundle,\n  from: PageLevelName,\n  leaf: ReactNode,\n): ReactNode {\n  const wrappers: PageLevelName[] = from === \"page\" ? [\"layout\", \"app\"] : from === \"layout\" ? [\"app\"] : [];\n\n  let element = leaf;\n\n  for (const level of wrappers) {\n    const Component = triple[level].default as ((props: LevelProps) => ReactNode) | undefined;\n\n    if (!Component) {\n      // \"App\" is the root: no App export means no custom document, but the\n      // pipeline always emits a complete one — the\n      // framework default App supplies it. Layout has no such fallback: an\n      // omitted layout default export stays a no-DOM passthrough,\n      // unchanged from before.\n      if (level === \"app\") {\n        element = createElement(DefaultApp, { children: element });\n      }\n\n      continue;\n    }\n\n    element = createElement(Component as ComponentType<LevelProps>, {\n      data: bundle[DATA_KEYS[level]],\n      shared: bundle.shared,\n      children: element,\n    });\n  }\n\n  return element;\n}\n\n// ---------------------------------------------------------------------------\n// Document assembly — stage 10 (10a apply + 10b flush) lives at the call site\n// ---------------------------------------------------------------------------\n\n/**\n * The root (App or the framework default) now ALWAYS renders a complete\n * `<html>…</html>` document itself — `<Head/>`/\n * `<Scripts/>` read the metadata/payload from `DocumentContext` (provided\n * around the element in `finishRender`, below) and emit real elements.\n * There is nothing left for this stage to assemble by string surgery; it\n * only prepends the doctype `renderToString` never includes.\n */\nfunction emitDocument(body: string): string {\n  return \"<!DOCTYPE html>\" + body;\n}\n\n// ---------------------------------------------------------------------------\n// The shared tail (stages 9–10) — both orchestrators end here\n// ---------------------------------------------------------------------------\n\n/**\n * The real request/response pair `capturingCreateHttp` captured for this\n * call. `finishRender` itself no longer takes this (D1: the short-circuit\n * status now lives on `bundle.shortCircuit`/`bundle.commit`) — it is used at\n * the two orchestrator call sites for the `as` impersonation write\n * (`state.captured.request.user = as`, below) and to read the document\n * slots (`documentSlotsFrom`, below).\n */\ntype CapturedHttp = {\n  request: PipelineRequest;\n  response: PipelineResponse;\n};\n\n/**\n * Wrap the caller's createHttp to capture the real pair (for the document\n * slots, `documentSlotsFrom` below), the matched entry (the only place a\n * URL-based caller learns which triple to render), and to apply `as` —\n * `user` is a plain public property on core's Request\n * (core/src/http/request.ts:92), exactly the write auth middleware performs.\n */\nfunction capturingCreateHttp(\n  registry: PageRoutesRegistry,\n  as: unknown,\n): {\n  state: { captured?: CapturedHttp; match?: PageRouteMatch };\n  createHttp: ExecutePageRequestOptions[\"createHttp\"];\n} {\n  const state: { captured?: CapturedHttp; match?: PageRouteMatch } = {};\n\n  return {\n    state,\n    createHttp(match) {\n      state.match = match;\n      state.captured = registry.createHttp(match);\n\n      if (as !== undefined) state.captured.request.user = as;\n\n      return state.captured;\n    },\n  };\n}\n\n/**\n * The two request-derived document slots (`nonce`/`lang` on\n * `DocumentContextValue`), extracted at the orchestrator call sites\n * because `finishRender` no longer carries `captured` (D1). `dir` is not\n * here: core's Request has no dir-like field (checked\n * core/src/http/request.ts — only `nonce` at :177 and `locale` at :343\n * exist) — an app supplies `dir` via its own convention.\n */\ntype DocumentSlots = {\n  nonce?: string;\n  lang?: string;\n};\n\n/**\n * Structural read of the two core `Request` fields the slots need. Neither\n * `nonce` nor `locale` is declared on `PipelineRequest`/`WebRequest` (the\n * loader-facing facade only declares `validated`/`input`/`user`,\n * context.ts:30-68) — a narrow typed intersection at the one call site that\n * needs it, the same pattern `execute-page-request.ts` uses for its own\n * `(response as PipelineResponse & { statusCode?: number })` read\n * (execute-page-request.ts:517).\n */\nfunction documentSlotsFrom(captured: CapturedHttp | undefined): DocumentSlots {\n  const request = captured?.request as (PipelineRequest & { nonce?: string; locale?: string }) | undefined;\n\n  return { nonce: request?.nonce, lang: request?.locale };\n}\n\nasync function finishRender(\n  triple: PageRouteEntry[\"triple\"],\n  bundle: PageDataBundle,\n  documentSlots: DocumentSlots,\n): Promise<RenderedPage> {\n  const headers: Record<string, string> = {};\n\n  for (const header of bundle.commit?.headers ?? []) {\n    headers[header.key.toLowerCase()] = header.value;\n  }\n\n  // The commit already deduplicated per name and ordered root→leaf\n  // (execute-page-request.ts settle/commit) — pass it through untransformed so\n  // every attribute survives to the caller's Set-Cookie.\n  const cookies: BufferedCookie[] = bundle.commit?.cookies ?? [];\n\n  // Short-circuit paths emit no document: the status IS the answer\n  // (redirect/notFound/guard/422 — P1 §4), nothing renders to describe.\n  if (bundle.shortCircuit) {\n    const status =\n      bundle.shortCircuit.stage === \"validation\"\n        ? bundle.shortCircuit.status\n        : bundle.shortCircuit.stage === \"loaders\"\n          ? bundle.shortCircuit.statusCode\n          // D1: the middleware variant now carries its own statusCode,\n          // captured at stage 3 where the pipeline legitimately touches the\n          // live response (execute-page-request.ts:514-518) — no live read here.\n          : (bundle.shortCircuit.statusCode ?? 200);\n\n    return { html: \"\", status, headers, cookies, data: bundle.pageData, bundle };\n  }\n\n  // The framework's closed-by-default answer (README rule 8): every document\n  // is `Cache-Control: private` unless a loader's committed headers already\n  // answered for the key. Map-only — `finishRender` never writes the live\n  // response; the caller applies the returned headers.\n  if (headers[\"cache-control\"] === undefined) {\n    headers[\"cache-control\"] = \"private\";\n  }\n\n  // ── stage 9 · RENDER ─────────────────────────────────────────────────────\n  // Lazy import: react-dom is a peer used only on this path, so merely\n  // loading the server barrel never requires it.\n  const { renderToString } = await import(\"react-dom/server\");\n\n  // JSON.stringify omits object properties whose value is undefined. Loader\n  // `<Head/>`/`<Scripts/>` read this context — metadata and the payload are\n  // both already final by this point (stages 1-8 are done), so there is\n  // nothing left for the root to await.\n  //\n  // The payload comes from `buildHydrationPayload` rather than being assembled\n  // here, so that this document and the `_loader` route hand the browser the\n  // SAME object. See that module for why the two must not drift.\n  const documentValue: DocumentContextValue = {\n    metadata: bundle.metadata,\n    payload: buildHydrationPayload(bundle),\n    nonce: documentSlots.nonce,\n    lang: documentSlots.lang,\n  };\n\n  const renderWithContext = (element: ReactNode): string =>\n    renderToString(createElement(DocumentContext.Provider, { value: documentValue, children: element }));\n\n  // A boundary that throws while rendering escalates to\n  // the next enclosing boundary rootward; if none survives, the framework's\n  // last-resort terminal renders. `currentError` starts as whatever stage\n  // 1-8 already designated (`bundle.error`, undefined for a normal page\n  // render) and is replaced by each escalation — `bundle.error` itself is\n  // never mutated, staying a truthful stage 1-8 record.\n  let currentError = bundle.error;\n  let renderTimeThrow = false;\n  let body: string;\n\n  for (;;) {\n    try {\n      const element = currentError\n        ? buildBoundaryElement(triple, bundle, currentError)\n        : buildPageElement(triple, bundle);\n\n      body = renderWithContext(element);\n      break;\n    } catch (thrown) {\n      renderTimeThrow = true;\n\n      if (currentError?.boundary.boundaryLevel === \"app\") {\n        // The floor: the app-level boundary's own render just threw, so\n        // there is nothing rootward of `app` to escalate to (§2's \"none\n        // survives\"). Render the framework's trivial boundary directly —\n        // bypassing the app's ErrorBoundary/App component, since that is\n        // what just failed — wrapped in DefaultApp so the response is still\n        // a complete `<html>` document (default-app.tsx:22-46) rather than\n        // a bare `<main>` fragment.\n        body = renderWithContext(createElement(DefaultApp, { children: createElement(FrameworkRootBoundary, {}) }));\n        break;\n      }\n\n      // Escalate from the level rootward of whatever just threw — searching\n      // from the SAME level would re-select the boundary that just failed.\n      // A throw not yet attributable to a level (a normal page render, no\n      // prior designation) starts the search at `page`.\n      const throwingLevel: PageLevelName =\n        currentError?.boundary.boundaryLevel === \"layout\" ? \"app\" : currentError ? \"layout\" : \"page\";\n\n      currentError = buildErrorRecord(thrown, designateBoundary(throwingLevel, triple));\n    }\n  }\n\n  // Status is chosen after render — the last thing that can change the\n  // outcome — and RETURNED, never applied: `finishRender` writes the live\n  // response zero times (and now zero live response READS either — D1 deleted the last one). The caller applies\n  // status + headers at one site and flushes immediately after (stage\n  // 10a/10b). A render-time throw follows the same status rule as a\n  // pre-render one: a NESTED boundary catch\n  // (page/layout) keeps the committed status; the app boundary or the\n  // framework terminal forces 500. Without a render-time throw, the\n  // pre-render designation already carries this rule — P1's commit forces\n  // 500 only when it designated `app` (execute-page-request.ts:625-637).\n  const status = renderTimeThrow\n    ? currentError!.boundary.boundaryLevel === \"app\"\n      ? 500\n      : (bundle.commit?.statusCode ?? 200)\n    : bundle.error\n      ? (bundle.commit?.statusCode ?? 500)\n      : (bundle.commit?.statusCode ?? 200);\n\n  const html = emitDocument(body);\n\n  return { html, status, headers, cookies, data: bundle.pageData, bundle };\n}\n\n// ---------------------------------------------------------------------------\n// The orchestrators\n// ---------------------------------------------------------------------------\n\nexport async function renderPage(\n  routeName: string,\n  options: RenderPageOptions = {},\n): Promise<RenderedPage> {\n  const registry = requireRegistry(options);\n  const entry = registry.routes.find(candidate => candidate.name === routeName);\n\n  if (!entry) {\n    const known = registry.routes.map(candidate => `\"${candidate.name}\"`).join(\", \");\n\n    throw new Error(\n      `renderPage(\"${routeName}\"): no route with that name ` +\n        `(web/src/server/render-page.ts). Known route names: ${known}. ` +\n        \"Fix: use a name from the manifest, or connect the manifest that \" +\n        \"declares this one.\",\n    );\n  }\n\n  const url = buildUrl(entry, options.params ?? {}, options.query ?? {});\n  const { state, createHttp } = capturingCreateHttp(registry, options.as);\n\n  const rendered = await executePageRequest({\n    url,\n    routes: registry.routes,\n    createHttp,\n    finish: bundle => finishRender(entry.triple, bundle, documentSlotsFrom(state.captured)),\n  });\n\n  if (!rendered) {\n    throw new Error(\n      `renderPage(\"${routeName}\"): the built URL \"${url}\" did not match ` +\n        \"stage 1 (web/src/server/render-page.ts). The name resolved but the \" +\n        \"matcher disagreed — that is a manifest bug, not a caller bug.\",\n    );\n  }\n\n  return rendered;\n}\n\n/**\n * The URL-based sibling of `renderPage` — the production render surface: a\n * real HTTP server has a URL, not a route name. The url goes STRAIGHT to\n * executePageRequest's stage-1 matcher (no buildUrl), then the same shared\n * tail renders and emits.\n *\n * No-match here is NOT the manifest bug renderPage throws on: an arbitrary\n * URL matching no route is a legitimate 404, and a server must ANSWER it —\n * `{ html: \"\", status: 404 }` with an undefined `bundle` (see RenderedPage).\n */\nexport async function renderPageRequest(\n  url: string,\n  options: RenderPageRequestOptions = {},\n): Promise<RenderedPage> {\n  const registry = requireRegistry(options);\n  const { state, createHttp } = capturingCreateHttp(registry, options.as);\n\n  const rendered = await executePageRequest({\n    url,\n    routes: registry.routes,\n    createHttp,\n    finish: bundle => finishRender(state.match!.entry.triple, bundle, documentSlotsFrom(state.captured)),\n  });\n\n  if (!rendered) {\n    return { html: \"\", status: 404, headers: {}, cookies: [], data: undefined, bundle: undefined };\n  }\n\n  // executePageRequest only produces a bundle after createHttp ran for the\n  // match, so the captured entry is present whenever the bundle is.\n  return rendered;\n}\n"],"mappings":"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"}

package/esm/server/resolve-page-metadata.mjs

@@ -0,0 +1,33 @@
+//#region ../web/src/server/resolve-page-metadata.ts
+/**
+* What `<head>` gets when the page did not render.
+*
+* `robots` is the load-bearing member, not `title`. An error render is a
+* transient server state that happens to be reachable at a real URL; letting a
+* crawler index it puts "Something went wrong" in a search result for a page
+* that works. `title` is a fallback a boundary is free to improve on.
+*/
+const ERROR_PAGE_METADATA = Object.freeze({
+	title: "Something went wrong",
+	robots: "noindex"
+});
+function resolvePageMetadata(input) {
+	if (input.failed) return { metadata: ERROR_PAGE_METADATA };
+	const { metadata } = input;
+	if (typeof metadata !== "function") return { metadata };
+	try {
+		return { metadata: metadata({
+			data: input.data,
+			shared: input.shared
+		}) };
+	} catch (thrown) {
+		return {
+			metadata: void 0,
+			thrown
+		};
+	}
+}
+
+//#endregion
+export { resolvePageMetadata };
+//# sourceMappingURL=resolve-page-metadata.mjs.map

package/esm/server/resolve-page-metadata.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-page-metadata.mjs","names":[],"sources":["../../../../../../../web/src/server/resolve-page-metadata.ts"],"sourcesContent":["/**\r\n * Stage 8 of the page pipeline — METADATA.\r\n *\r\n * Its own file because the behaviour that matters here is about ERRORS, and\r\n * reaching an error path through the full ten-stage pipeline means standing up\r\n * a real Request/Response pair to observe a `try`/`catch`. See\r\n * `resolve-page-metadata.spec.ts`.\r\n *\r\n * ## Why a page's `metadata` never runs after a failed loader\r\n *\r\n * It used to. `design/request-lifecycle.md` said \"exactly one of data/error\r\n * set\", and stage 8 duly called `metadata({ data: undefined, error })` when a\r\n * loader rejected — while `PageMetadata` declared `data` as always present.\r\n * **The type lied**, so the natural way to write a metadata function was also\r\n * the broken way:\r\n *\r\n * ```ts\r\n * export const metadata: PageMetadata<typeof loader> = ({ data }) => ({\r\n *   title: \"Home\",\r\n *   description: `${data.products.length} products in stock`,\r\n * });\r\n * ```\r\n *\r\n * All three function-form metadata exports in the reference app were written\r\n * exactly like that, and all three turned a loader's real error — a\r\n * `MissingDataSourceError`, say — into `TypeError: Cannot read properties of\r\n * undefined`, reported against a different file in a different subsystem. The\r\n * cost was never the crash; it was that every future debugging session on a\r\n * failed loader would start by investigating the wrong thing.\r\n *\r\n * The alternative was to widen `data` to `| undefined` and make every author\r\n * handle a path almost none of them care about — and without a discriminant,\r\n * TypeScript cannot narrow `data` from `if (error)` anyway, so authors would\r\n * have reached for `data!` and re-created the lie with extra syntax.\r\n *\r\n * So: a page describes a page it actually has. When there is no data there is\r\n * no page-authored description, and the framework supplies\r\n * {@link ERROR_PAGE_METADATA} instead.\r\n *\r\n * ## Partial failure\r\n *\r\n * Stage 7 runs app, layout and page loaders under `allSettled`, so the page's\r\n * own loader can resolve while an ANCESTOR's rejects. `failed` is still true\r\n * then, and the page's metadata still does not run — deliberately. Any recorded\r\n * error means a boundary renders instead of the page, and metadata describes\r\n * what is on screen. Describing a page the visitor never received is the same\r\n * defect in a quieter form.\r\n *\r\n * If per-page error metadata is ever wanted, it is a separate `errorMetadata`\r\n * export — a distinct signature for a distinct situation, not an arm of this\r\n * one. Nothing has asked for it.\r\n */\r\n\r\nimport type { SharedContext } from \"../index\";\r\nimport type { MetadataOutput, PageMetadata } from \"../metadata\";\r\nimport type { PipelineLoader } from \"./execute-page-request\";\r\n\r\n/**\r\n * What `<head>` gets when the page did not render.\r\n *\r\n * `robots` is the load-bearing member, not `title`. An error render is a\r\n * transient server state that happens to be reachable at a real URL; letting a\r\n * crawler index it puts \"Something went wrong\" in a search result for a page\r\n * that works. `title` is a fallback a boundary is free to improve on.\r\n */\r\nexport const ERROR_PAGE_METADATA: MetadataOutput = Object.freeze({\r\n  title: \"Something went wrong\",\r\n  robots: \"noindex\",\r\n});\r\n\r\nexport type ResolvePageMetadataInput = {\r\n  /** The page module's `metadata` export — absent, object, or function. */\r\n  metadata: PageMetadata<PipelineLoader> | undefined;\r\n  /** `bundle.pageData`. Read only when `failed` is false. */\r\n  data: unknown;\r\n  /** The value an earlier stage already recorded. Diagnostics only. */\r\n  error: unknown;\r\n  /** Whether an earlier stage recorded an error at all. */\r\n  failed: boolean;\r\n  shared: Readonly<SharedContext>;\r\n};\r\n\r\nexport type ResolvedPageMetadata = {\r\n  metadata: MetadataOutput | undefined;\r\n  /**\r\n   * Set only when the page's own metadata function threw on the SUCCESS path.\r\n   * Returned rather than rethrown so the caller can record it the same way a\r\n   * loader throw is recorded — the boundary renders and the framework keeps\r\n   * ownership of the status, instead of an exception escaping stage 8.\r\n   *\r\n   * Never set on the error path: nothing runs there that could throw, and an\r\n   * error arriving at stage 8 has already won.\r\n   */\r\n  thrown?: unknown;\r\n};\r\n\r\n/** The function arm of `PageMetadata`, for the one call this module makes. */\r\ntype PageMetadataFunction = Extract<PageMetadata<PipelineLoader>, (...args: never) => unknown>;\r\n\r\nexport function resolvePageMetadata(input: ResolvePageMetadataInput): ResolvedPageMetadata {\r\n  if (input.failed) {\r\n    return { metadata: ERROR_PAGE_METADATA };\r\n  }\r\n\r\n  const { metadata } = input;\r\n\r\n  if (typeof metadata !== \"function\") {\r\n    return { metadata };\r\n  }\r\n\r\n  try {\r\n    return {\r\n      metadata: (metadata as PageMetadataFunction)({\r\n        data: input.data as Parameters<PageMetadataFunction>[0][\"data\"],\r\n        shared: input.shared,\r\n      }),\r\n    };\r\n  } catch (thrown) {\r\n    return { metadata: undefined, thrown };\r\n  }\r\n}\r\n"],"mappings":";;;;;;;;;AAiEA,MAAa,sBAAsC,OAAO,OAAO;CAC/D,OAAO;CACP,QAAQ;AACV,CAAC;AA+BD,SAAgB,oBAAoB,OAAuD;CACzF,IAAI,MAAM,QACR,OAAO,EAAE,UAAU,oBAAoB;CAGzC,MAAM,EAAE,aAAa;CAErB,IAAI,OAAO,aAAa,YACtB,OAAO,EAAE,SAAS;CAGpB,IAAI;EACF,OAAO,EACL,UAAW,SAAkC;GAC3C,MAAM,MAAM;GACZ,QAAQ,MAAM;EAChB,CAAC,EACH;CACF,SAAS,QAAQ;EACf,OAAO;GAAE,UAAU;GAAW;EAAO;CACvC;AACF"}

package/esm/server/resolve-validation-data.mjs

@@ -0,0 +1,27 @@
+//#region ../web/src/server/resolve-validation-data.ts
+/** The four names a page may list in `validation.validating`. */
+const SOURCES = {
+	body: (request) => request.body,
+	query: (request) => request.query,
+	params: (request) => request.params,
+	headers: (request) => request.headers
+};
+function resolveValidationData(validating, request) {
+	if (!validating || validating.length === 0) return {
+		...request.query,
+		...request.params
+	};
+	let data = {};
+	for (const source of validating) {
+		const read = SOURCES[source];
+		if (read) data = {
+			...data,
+			...read(request) ?? {}
+		};
+	}
+	return data;
+}
+
+//#endregion
+export { resolveValidationData };
+//# sourceMappingURL=resolve-validation-data.mjs.map

package/esm/server/resolve-validation-data.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-validation-data.mjs","names":[],"sources":["../../../../../../../web/src/server/resolve-validation-data.ts"],"sourcesContent":["/**\n * Stage 4's input — what the page's `validation.schema` is handed.\n *\n * ## One request, one parse, one grammar\n *\n * This used to draw its four sources from **two** places. `body` and `headers`\n * came from the request; `query` and `params` came from a match object that\n * `execute-page-request.ts` built by re-parsing the URL itself with\n * `Object.fromEntries(new URLSearchParams(...))`.\n *\n * Core's parser is bracket-aware and preserves repeated keys. That one is\n * neither:\n *\n * ```\n * ?tags=a&tags=b&filter[status]=active\n *   core  → { tags: [\"a\",\"b\"], filter: { status: \"active\" } }\n *   match → { tags: \"b\", \"filter[status]\": \"active\" }\n * ```\n *\n * **So a page's validation rules were checking different data than its loader\n * received.** A rule on `filter.status` could never fire — validation saw a key\n * literally named `filter[status]` — and where a key was sent twice, only the\n * last value was ever examined. A field the author believed was validated was\n * not, and nothing about that was visible from reading the validation rules.\n *\n * Every source is now the request. Core has already parsed the URL by the time\n * this runs; parsing it a second time can only ever produce a second answer.\n *\n * Mirrors core's `validateAll.ts:8-31`, with the page default: **params +\n * query, not body** — a page load is a GET.\n */\n\nexport type ValidationRequest = {\n  body?: Record<string, unknown>;\n  headers?: Record<string, unknown>;\n  query?: Record<string, unknown>;\n  params?: Record<string, unknown>;\n};\n\n/** The four names a page may list in `validation.validating`. */\nconst SOURCES = {\n  body: (request: ValidationRequest) => request.body,\n  query: (request: ValidationRequest) => request.query,\n  params: (request: ValidationRequest) => request.params,\n  headers: (request: ValidationRequest) => request.headers,\n} as const;\n\nexport function resolveValidationData(\n  validating: readonly string[] | undefined,\n  request: ValidationRequest,\n): Record<string, unknown> {\n  // The page default. `params` last so a route parameter wins a query key of\n  // the same name — the URL path is the more authoritative of the two.\n  if (!validating || validating.length === 0) {\n    return { ...request.query, ...request.params };\n  }\n\n  let data: Record<string, unknown> = {};\n\n  for (const source of validating) {\n    const read = SOURCES[source as keyof typeof SOURCES];\n\n    // An unknown source name contributes nothing rather than throwing: the\n    // list is app-authored, and stage 4 is not the place to litigate it.\n    if (read) data = { ...data, ...(read(request) ?? {}) };\n  }\n\n  return data;\n}\n"],"mappings":";;AAwCA,MAAM,UAAU;CACd,OAAO,YAA+B,QAAQ;CAC9C,QAAQ,YAA+B,QAAQ;CAC/C,SAAS,YAA+B,QAAQ;CAChD,UAAU,YAA+B,QAAQ;AACnD;AAEA,SAAgB,sBACd,YACA,SACyB;CAGzB,IAAI,CAAC,cAAc,WAAW,WAAW,GACvC,OAAO;EAAE,GAAG,QAAQ;EAAO,GAAG,QAAQ;CAAO;CAG/C,IAAI,OAAgC,CAAC;CAErC,KAAK,MAAM,UAAU,YAAY;EAC/B,MAAM,OAAO,QAAQ;EAIrB,IAAI,MAAM,OAAO;GAAE,GAAG;GAAM,GAAI,KAAK,OAAO,KAAK,CAAC;EAAG;CACvD;CAEA,OAAO;AACT"}

package/esm/server/settle-page-response.d.mts

@@ -0,0 +1 @@
+export { };