@warlock.js/web 5.0.0

package/esm/client/build-hydrated-tree.mjs

@@ -0,0 +1,113 @@
+import { loadClientRouteComposition } from "./runtime/manifest.mjs";
+import { createElement } from "react";
+
+//#region ../web/src/client/build-hydrated-tree.ts
+/**
+* The hydration COMPOSER: payload + page registry -> the ReactNode to mount.
+*
+* It takes the registry as an ARGUMENT and touches no browser global, which is
+* the whole point of it living apart from `index.ts`: every rule below is
+* testable with a hand-built registry, no bundler, no virtual module, no DOM.
+*
+* LOOKUP BY NAME, NEVER BY MATCH. `payload.name` is the identity of the entry
+* the SERVER matched for this exact request (document-context.ts's `name`
+* field). Re-deriving it from `location.pathname` with `matchClientRoute`
+* would be a second implementation of route semantics running against the one
+* request it is hydrating, free to disagree with the server that produced the
+* markup. `matchClientRoute` is for client-side NAVIGATION, where no server
+* answer exists yet.
+*/
+function describeKnownNames(knownPageNames) {
+	if (knownPageNames.length === 0) return "The client page registry is empty.";
+	return `The registry knows: ${knownPageNames.map((name) => JSON.stringify(name)).join(", ")}.`;
+}
+/**
+* The THIRD hydration failure case, beside an absent and a malformed payload.
+*
+* It fails CLOSED — no default entry, no nearest-path fallback, no silent
+* no-op. A registry that quietly substitutes a page produces a browser showing
+* one page's markup running another page's code, which is precisely the defect
+* this entry point was rewritten to remove; a fallback would reintroduce it
+* wearing a recovery costume. Throwing leaves the server-rendered markup on
+* screen and un-hydrated, which is degraded but honest.
+*/
+var UnknownHydrationPageNameError = class extends Error {
+	pageName;
+	knownPageNames;
+	constructor(pageName, knownPageNames) {
+		super(`Warlock hydration aborted: the payload names page ${JSON.stringify(pageName)}, which is not in the client page registry. ${describeKnownNames(knownPageNames)} The server rendered a page this browser bundle does not carry, so the server and client were built from different page graphs. To fix: rebuild the client bundle, or check that the page's file still exports a \`route\` discovery can see.`);
+		this.pageName = pageName;
+		this.knownPageNames = knownPageNames;
+		this.name = "UnknownHydrationPageNameError";
+	}
+};
+function findEntryByName(pages, name) {
+	const entry = pages.find((candidate) => candidate.name === name);
+	if (entry === void 0) throw new UnknownHydrationPageNameError(name, pages.map((candidate) => candidate.name));
+	return entry;
+}
+/**
+* A level's component, or undefined when the module exports no default.
+*
+* Undefined is NOT an error: `render-page.ts:258` and `:279` treat a missing
+* default as a passthrough server-side, and the client tree has to match the
+* markup React is hydrating against — introducing a level here that the server
+* did not render is a hydration mismatch, not a repair.
+*/
+function componentOf(module) {
+	const component = module.default;
+	return typeof component === "function" ? component : void 0;
+}
+function wrap(module, data, shared, children) {
+	const Component = componentOf(module);
+	if (Component === void 0) return children;
+	return createElement(Component, {
+		data,
+		shared,
+		children
+	});
+}
+/**
+* Compose the tree the server rendered inside `#root`: ordered layouts wrapping
+* the Page, layouts OUTERMOST FIRST as `ClientRouteComposition` declares them,
+* each level receiving `{ data, shared }` and every wrapper additionally
+* `children`.
+*
+* ── THE APP LEVEL IS DELIBERATELY ABSENT, AND MUST STAY ABSENT ──────────────
+* `ClientRouteComposition.App` and `payload.appData` still exist and are still
+* carried; they are contracts owned elsewhere. They are simply not part of THIS
+* tree, because App is not part of the markup this tree hydrates against:
+*
+*  - Server-side, `render-page.ts`'s `wrapRootward` wraps the page leaf in
+*    `["layout", "app"]` (`render-page.ts:274`), so the document React renders
+*    is `App( Layout( Page ) )`.
+*  - The app root is the level that owns `<html>`/`<body>` and renders
+*    `<div id="root">{children}</div>` inside the body. So App CONTAINS the
+*    mount point — the markup actually inside `#root` is `Layout( Page )`.
+*  - `hydrate-page.tsx` mounts at `#root` and nowhere else.
+*
+* Composing App here would therefore hydrate a whole `<html>` document inside a
+* `<div>` the server filled with a layout: a guaranteed hydration mismatch. If
+* you arrived here from the optional `App?` on the composition type and are
+* about to "complete" the tree with it — that would be the defect, not the
+* omission.
+*
+* `load()` is awaited exactly ONCE per hydration and its result reused for all
+* levels — the composition arrives whole, so calling it per layout would be
+* one network waterfall per level for no new information.
+*/
+async function buildHydratedTree(pages, payload) {
+	const composition = await loadClientRouteComposition(findEntryByName(pages, payload.name));
+	const { shared } = payload;
+	const Page = componentOf(composition.Page);
+	let element = Page === void 0 ? null : createElement(Page, {
+		data: payload.pageData,
+		shared
+	});
+	for (let index = composition.layouts.length - 1; index >= 0; index -= 1) element = wrap(composition.layouts[index], payload.layoutData, shared, element);
+	return element;
+}
+
+//#endregion
+export { buildHydratedTree };
+//# sourceMappingURL=build-hydrated-tree.mjs.map

package/esm/client/build-hydrated-tree.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-hydrated-tree.mjs","names":[],"sources":["../../../../../../../web/src/client/build-hydrated-tree.ts"],"sourcesContent":["/**\n * The hydration COMPOSER: payload + page registry -> the ReactNode to mount.\n *\n * It takes the registry as an ARGUMENT and touches no browser global, which is\n * the whole point of it living apart from `index.ts`: every rule below is\n * testable with a hand-built registry, no bundler, no virtual module, no DOM.\n *\n * LOOKUP BY NAME, NEVER BY MATCH. `payload.name` is the identity of the entry\n * the SERVER matched for this exact request (document-context.ts's `name`\n * field). Re-deriving it from `location.pathname` with `matchClientRoute`\n * would be a second implementation of route semantics running against the one\n * request it is hydrating, free to disagree with the server that produced the\n * markup. `matchClientRoute` is for client-side NAVIGATION, where no server\n * answer exists yet.\n */\nimport { createElement, type ComponentType, type ReactNode } from \"react\";\nimport type { HydrationDocumentPayloadSource } from \"../hydration-payload\";\nimport { loadClientRouteComposition } from \"./runtime\";\nimport type { ClientPageEntry, ClientProjectedModule } from \"./runtime/types\";\n\n/** What every composed level receives — the shape `render-page.ts` uses server-side. */\ntype HydratedLevelProps = {\n  readonly data: unknown;\n  readonly shared: unknown;\n  readonly children?: ReactNode;\n};\n\nfunction describeKnownNames(knownPageNames: readonly string[]): string {\n  if (knownPageNames.length === 0) return \"The client page registry is empty.\";\n\n  return `The registry knows: ${knownPageNames.map((name) => JSON.stringify(name)).join(\", \")}.`;\n}\n\n/**\n * The THIRD hydration failure case, beside an absent and a malformed payload.\n *\n * It fails CLOSED — no default entry, no nearest-path fallback, no silent\n * no-op. A registry that quietly substitutes a page produces a browser showing\n * one page's markup running another page's code, which is precisely the defect\n * this entry point was rewritten to remove; a fallback would reintroduce it\n * wearing a recovery costume. Throwing leaves the server-rendered markup on\n * screen and un-hydrated, which is degraded but honest.\n */\nexport class UnknownHydrationPageNameError extends Error {\n  public constructor(\n    public readonly pageName: string,\n    public readonly knownPageNames: readonly string[],\n  ) {\n    super(\n      `Warlock hydration aborted: the payload names page ${JSON.stringify(pageName)}, which is ` +\n        `not in the client page registry. ${describeKnownNames(knownPageNames)} The server ` +\n        \"rendered a page this browser bundle does not carry, so the server and client were \" +\n        \"built from different page graphs. To fix: rebuild the client bundle, or check that \" +\n        \"the page's file still exports a `route` discovery can see.\",\n    );\n    this.name = \"UnknownHydrationPageNameError\";\n  }\n}\n\nfunction findEntryByName(\n  pages: readonly ClientPageEntry[],\n  name: string,\n): ClientPageEntry {\n  const entry = pages.find((candidate) => candidate.name === name);\n\n  if (entry === undefined) {\n    throw new UnknownHydrationPageNameError(\n      name,\n      pages.map((candidate) => candidate.name),\n    );\n  }\n\n  return entry;\n}\n\n/**\n * A level's component, or undefined when the module exports no default.\n *\n * Undefined is NOT an error: `render-page.ts:258` and `:279` treat a missing\n * default as a passthrough server-side, and the client tree has to match the\n * markup React is hydrating against — introducing a level here that the server\n * did not render is a hydration mismatch, not a repair.\n */\nfunction componentOf(\n  module: ClientProjectedModule,\n): ComponentType<HydratedLevelProps> | undefined {\n  const component = module.default;\n\n  return typeof component === \"function\"\n    ? (component as ComponentType<HydratedLevelProps>)\n    : undefined;\n}\n\nfunction wrap(\n  module: ClientProjectedModule,\n  data: unknown,\n  shared: unknown,\n  children: ReactNode,\n): ReactNode {\n  const Component = componentOf(module);\n\n  if (Component === undefined) return children;\n\n  return createElement(Component, { data, shared, children });\n}\n\n/**\n * Compose the tree the server rendered inside `#root`: ordered layouts wrapping\n * the Page, layouts OUTERMOST FIRST as `ClientRouteComposition` declares them,\n * each level receiving `{ data, shared }` and every wrapper additionally\n * `children`.\n *\n * ── THE APP LEVEL IS DELIBERATELY ABSENT, AND MUST STAY ABSENT ──────────────\n * `ClientRouteComposition.App` and `payload.appData` still exist and are still\n * carried; they are contracts owned elsewhere. They are simply not part of THIS\n * tree, because App is not part of the markup this tree hydrates against:\n *\n *  - Server-side, `render-page.ts`'s `wrapRootward` wraps the page leaf in\n *    `[\"layout\", \"app\"]` (`render-page.ts:274`), so the document React renders\n *    is `App( Layout( Page ) )`.\n *  - The app root is the level that owns `<html>`/`<body>` and renders\n *    `<div id=\"root\">{children}</div>` inside the body. So App CONTAINS the\n *    mount point — the markup actually inside `#root` is `Layout( Page )`.\n *  - `hydrate-page.tsx` mounts at `#root` and nowhere else.\n *\n * Composing App here would therefore hydrate a whole `<html>` document inside a\n * `<div>` the server filled with a layout: a guaranteed hydration mismatch. If\n * you arrived here from the optional `App?` on the composition type and are\n * about to \"complete\" the tree with it — that would be the defect, not the\n * omission.\n *\n * `load()` is awaited exactly ONCE per hydration and its result reused for all\n * levels — the composition arrives whole, so calling it per layout would be\n * one network waterfall per level for no new information.\n */\nexport async function buildHydratedTree(\n  pages: readonly ClientPageEntry[],\n  payload: HydrationDocumentPayloadSource,\n): Promise<ReactNode> {\n  const entry = findEntryByName(pages, payload.name);\n  const composition = await loadClientRouteComposition(entry);\n  const { shared } = payload;\n\n  const Page = componentOf(composition.Page);\n  let element: ReactNode =\n    Page === undefined ? null : createElement(Page, { data: payload.pageData, shared });\n\n  // Innermost layout wraps the page, so walk the outermost-first list backwards.\n  for (let index = composition.layouts.length - 1; index >= 0; index -= 1) {\n    element = wrap(composition.layouts[index]!, payload.layoutData, shared, element);\n  }\n\n  return element;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AA2BA,SAAS,mBAAmB,gBAA2C;CACrE,IAAI,eAAe,WAAW,GAAG,OAAO;CAExC,OAAO,uBAAuB,eAAe,KAAK,SAAS,KAAK,UAAU,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE;AAC9F;;;;;;;;;;;AAYA,IAAa,gCAAb,cAAmD,MAAM;CAErC;CACA;CAFlB,AAAO,YACL,AAAgB,UAChB,AAAgB,gBAChB;EACA,MACE,qDAAqD,KAAK,UAAU,QAAQ,EAAE,8CACxC,mBAAmB,cAAc,EAAE,8OAI3E;EATgB;EACA;EAShB,KAAK,OAAO;CACd;AACF;AAEA,SAAS,gBACP,OACA,MACiB;CACjB,MAAM,QAAQ,MAAM,MAAM,cAAc,UAAU,SAAS,IAAI;CAE/D,IAAI,UAAU,QACZ,MAAM,IAAI,8BACR,MACA,MAAM,KAAK,cAAc,UAAU,IAAI,CACzC;CAGF,OAAO;AACT;;;;;;;;;AAUA,SAAS,YACP,QAC+C;CAC/C,MAAM,YAAY,OAAO;CAEzB,OAAO,OAAO,cAAc,aACvB,YACD;AACN;AAEA,SAAS,KACP,QACA,MACA,QACA,UACW;CACX,MAAM,YAAY,YAAY,MAAM;CAEpC,IAAI,cAAc,QAAW,OAAO;CAEpC,OAAO,cAAc,WAAW;EAAE;EAAM;EAAQ;CAAS,CAAC;AAC5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,eAAsB,kBACpB,OACA,SACoB;CAEpB,MAAM,cAAc,MAAM,2BADZ,gBAAgB,OAAO,QAAQ,IACY,CAAC;CAC1D,MAAM,EAAE,WAAW;CAEnB,MAAM,OAAO,YAAY,YAAY,IAAI;CACzC,IAAI,UACF,SAAS,SAAY,OAAO,cAAc,MAAM;EAAE,MAAM,QAAQ;EAAU;CAAO,CAAC;CAGpF,KAAK,IAAI,QAAQ,YAAY,QAAQ,SAAS,GAAG,SAAS,GAAG,SAAS,GACpE,UAAU,KAAK,YAAY,QAAQ,QAAS,QAAQ,YAAY,QAAQ,OAAO;CAGjF,OAAO;AACT"}

package/esm/client/hydrate-page.mjs

@@ -0,0 +1,73 @@
+import { hydrateShared } from "../shared.mjs";
+import { DocumentContext } from "../components/document-context.mjs";
+import { readHydrationPayload } from "../hydration-payload.mjs";
+import { hydrateRoot } from "react-dom/client";
+import { jsx } from "react/jsx-runtime";
+
+//#region ../web/src/client/hydrate-page.tsx
+/**
+* The hydration MOUNT point — a different id from the payload script's id.
+* Not exported anywhere as a named constant (`default-app.tsx:39` only
+* renders the literal `<div id="root">`), so a local literal is fine here:
+* the contract's no-duplicate-literal rule is specifically about the payload
+* script id, which `readHydrationPayload` already owns exclusively
+* (hydration-payload-contract-2026-08-22.md §4).
+*/
+const MOUNT_ELEMENT_ID = "root";
+function isPromise(value) {
+	return typeof value === "object" && value !== null && typeof value.then === "function";
+}
+/**
+* The awaited path's failure sink. By the time a `buildTree` promise rejects
+* the synchronous stack is gone, so there is no caller left to throw at — and
+* an un-attached rejection is a blank console, which is the silent-failure
+* class this pipeline keeps regressing into. Reported loudly, and deliberately
+* WITHOUT touching `#root`: the server's markup is correct and visible, it is
+* only un-hydrated, so clearing it would turn a degraded page into a blank one.
+*/
+function reportHydrationFailure(error) {
+	console.error("Warlock hydration failed after the page tree was requested. The server-rendered markup is left on screen un-hydrated; #root was not cleared.", error);
+}
+/**
+* The one hydration entry point. Mounts at `#root` only — the page subtree —
+* never `document`/`html`/`head`/`body` (hydration-payload-contract-2026-08-22.md
+* §2): `metadata`, `lang`, `dir`, `nonce` are not in the client payload and are
+* never touched here. `readHydrationPayload` (web/src/hydration-payload.ts,
+* Vega's slice B) is the one place ABSENT/MALFORMED are decided, so this
+* function does not re-implement that check — reusing it is what keeps the
+* two throw messages from drifting apart at a second site. On ABSENT/MALFORMED
+* it throws before touching `#root`, so the server-rendered markup stays
+* visible; nothing is cleared or re-rendered.
+*
+* Order is load-bearing and unchanged by the async tree: payload validated,
+* shared snapshot installed, `#root` resolved and its absence thrown on — all
+* SYNCHRONOUSLY, so those three failures still reject the call itself — and
+* only then is the tree built and, if it is a promise, awaited. Nothing is
+* cleared on any failure path.
+*/
+function hydratePage(buildTree) {
+	const payload = readHydrationPayload(document);
+	hydrateShared(payload.shared);
+	const mountElement = document.getElementById(MOUNT_ELEMENT_ID);
+	if (mountElement === null) throw new Error(`Warlock hydration aborted: no element with id "${MOUNT_ELEMENT_ID}" was found. The server is expected to render <div id="root"> as the hydration mount point (web/src/components/default-app.tsx:39).`);
+	const value = {
+		metadata: void 0,
+		payload
+	};
+	const mount = (tree) => {
+		hydrateRoot(mountElement, /* @__PURE__ */ jsx(DocumentContext.Provider, {
+			value,
+			children: tree
+		}));
+	};
+	const tree = buildTree(payload);
+	if (isPromise(tree)) {
+		tree.then(mount, reportHydrationFailure);
+		return;
+	}
+	mount(tree);
+}
+
+//#endregion
+export { hydratePage };
+//# sourceMappingURL=hydrate-page.mjs.map

package/esm/client/hydrate-page.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydrate-page.mjs","names":[],"sources":["../../../../../../../web/src/client/hydrate-page.tsx"],"sourcesContent":["import type { ReactNode } from \"react\";\nimport { hydrateRoot } from \"react-dom/client\";\nimport { DocumentContext, type DocumentContextValue } from \"../components/document-context\";\nimport { readHydrationPayload, type HydrationDocumentPayloadSource } from \"../hydration-payload\";\nimport { hydrateShared } from \"../shared\";\n\n/**\n * The hydration MOUNT point — a different id from the payload script's id.\n * Not exported anywhere as a named constant (`default-app.tsx:39` only\n * renders the literal `<div id=\"root\">`), so a local literal is fine here:\n * the contract's no-duplicate-literal rule is specifically about the payload\n * script id, which `readHydrationPayload` already owns exclusively\n * (hydration-payload-contract-2026-08-22.md §4).\n */\nconst MOUNT_ELEMENT_ID = \"root\";\n\n/**\n * Receives the VALIDATED payload and returns the ReactNode to hydrate. A\n * callback rather than a ready-made ReactNode: composing the real Layout(Page)\n * tree needs `payload.layoutData`/`pageData`/`shared`, which only exist after\n * `readHydrationPayload()` has already succeeded — building the tree first and\n * validating second would get the order backwards.\n *\n * A Promise is allowed because the real composer resolves the page's chunk\n * through the registry's dynamic `import()`. Returning it does NOT move the\n * payload check later: the callback is still only reached once the payload has\n * validated, and only the tree it produces is awaited.\n */\nexport type BuildHydratedTree = (\n  payload: HydrationDocumentPayloadSource,\n) => ReactNode | Promise<ReactNode>;\n\nfunction isPromise(value: ReactNode | Promise<ReactNode>): value is Promise<ReactNode> {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    typeof (value as { then?: unknown }).then === \"function\"\n  );\n}\n\n/**\n * The awaited path's failure sink. By the time a `buildTree` promise rejects\n * the synchronous stack is gone, so there is no caller left to throw at — and\n * an un-attached rejection is a blank console, which is the silent-failure\n * class this pipeline keeps regressing into. Reported loudly, and deliberately\n * WITHOUT touching `#root`: the server's markup is correct and visible, it is\n * only un-hydrated, so clearing it would turn a degraded page into a blank one.\n */\nfunction reportHydrationFailure(error: unknown): void {\n  console.error(\n    \"Warlock hydration failed after the page tree was requested. The server-rendered \" +\n      \"markup is left on screen un-hydrated; #root was not cleared.\",\n    error,\n  );\n}\n\n/**\n * The one hydration entry point. Mounts at `#root` only — the page subtree —\n * never `document`/`html`/`head`/`body` (hydration-payload-contract-2026-08-22.md\n * §2): `metadata`, `lang`, `dir`, `nonce` are not in the client payload and are\n * never touched here. `readHydrationPayload` (web/src/hydration-payload.ts,\n * Vega's slice B) is the one place ABSENT/MALFORMED are decided, so this\n * function does not re-implement that check — reusing it is what keeps the\n * two throw messages from drifting apart at a second site. On ABSENT/MALFORMED\n * it throws before touching `#root`, so the server-rendered markup stays\n * visible; nothing is cleared or re-rendered.\n *\n * Order is load-bearing and unchanged by the async tree: payload validated,\n * shared snapshot installed, `#root` resolved and its absence thrown on — all\n * SYNCHRONOUSLY, so those three failures still reject the call itself — and\n * only then is the tree built and, if it is a promise, awaited. Nothing is\n * cleared on any failure path.\n */\nexport function hydratePage(buildTree: BuildHydratedTree): void {\n  const payload = readHydrationPayload(document);\n\n  hydrateShared(payload.shared);\n\n  const mountElement = document.getElementById(MOUNT_ELEMENT_ID);\n\n  if (mountElement === null) {\n    throw new Error(\n      `Warlock hydration aborted: no element with id \"${MOUNT_ELEMENT_ID}\" was found. The ` +\n        'server is expected to render <div id=\"root\"> as the hydration mount point ' +\n        \"(web/src/components/default-app.tsx:39).\",\n    );\n  }\n\n  const value: DocumentContextValue = { metadata: undefined, payload };\n\n  const mount = (tree: ReactNode): void => {\n    hydrateRoot(\n      mountElement,\n      <DocumentContext.Provider value={value}>{tree}</DocumentContext.Provider>,\n    );\n  };\n\n  const tree = buildTree(payload);\n\n  if (isPromise(tree)) {\n    // `void` on an ALREADY-handled chain: the rejection handler is attached\n    // here, so nothing escapes as an unhandled rejection.\n    void tree.then(mount, reportHydrationFailure);\n\n    return;\n  }\n\n  mount(tree);\n}"],"mappings":";;;;;;;;;;;;;;;AAcA,MAAM,mBAAmB;AAkBzB,SAAS,UAAU,OAAoE;CACrF,OACE,OAAO,UAAU,YACjB,UAAU,QACV,OAAQ,MAA6B,SAAS;AAElD;;;;;;;;;AAUA,SAAS,uBAAuB,OAAsB;CACpD,QAAQ,MACN,gJAEA,KACF;AACF;;;;;;;;;;;;;;;;;;AAmBA,SAAgB,YAAY,WAAoC;CAC9D,MAAM,UAAU,qBAAqB,QAAQ;CAE7C,cAAc,QAAQ,MAAM;CAE5B,MAAM,eAAe,SAAS,eAAe,gBAAgB;CAE7D,IAAI,iBAAiB,MACnB,MAAM,IAAI,MACR,kDAAkD,iBAAiB,oIAGrE;CAGF,MAAM,QAA8B;EAAE,UAAU;EAAW;CAAQ;CAEnE,MAAM,SAAS,SAA0B;EACvC,YACE,cACA,oBAAC,gBAAgB,UAAjB;GAAiC;aAAQ;EAA+B,EAC1E;CACF;CAEA,MAAM,OAAO,UAAU,OAAO;CAE9B,IAAI,UAAU,IAAI,GAAG;EAGnB,AAAK,KAAK,KAAK,OAAO,sBAAsB;EAE5C;CACF;CAEA,MAAM,IAAI;AACZ"}

package/esm/client/navigation/current-route.d.mts

@@ -0,0 +1,91 @@
+//#region ../web/src/client/navigation/current-route.d.ts
+/**
+ * "Which route am I on?", under the name MRR spells it
+ * (`@mongez/react-router` — `src/utilities.tsx`).
+ *
+ * ## The shift, and it is the whole point of this file
+ *
+ * MRR's `currentRoute()` returns the object ITS MATCHER produced: MRR is a CSR
+ * router, so the browser matched the URL and the answer is the browser's own
+ * conclusion. Warlock has no client matcher and must never grow one (canon
+ * `9c8f878b`) — the SERVER router is the only matcher, and a second one can
+ * disagree with it about the very request it is hydrating.
+ *
+ * So the name is MRR's because the QUESTION is the same one, but the ANSWER
+ * comes from somewhere else: the matched entry's name AND ITS PARAMS travel on
+ * the hydration payload (`web/src/components/document-context.ts`), and this
+ * module reports what arrived. Nothing here parses a path, compares a URL to a
+ * pattern, or knows that routes have shapes.
+ *
+ * The practical consequence for a caller: this is the server's match, so it is
+ * as correct as the page on screen and it cannot drift from it — including on
+ * the very first render, before any client navigation, which is most page
+ * views.
+ *
+ * ## The params, and where they come from
+ *
+ * `bundle.route.params` (`web/src/server/execute-page-request.ts:288`) is the
+ * router's own answer; `buildHydrationPayload` puts it on the payload and the
+ * projection below hands it over unchanged. Deriving `{ id: "42" }` from
+ * `location.pathname` here would BE the second matcher this file exists to
+ * refuse — a URL and a pattern are exactly what it must never compare.
+ *
+ * ## Why nothing here touches `window`
+ *
+ * Both readers are importable from universal modules, so both can be CALLED
+ * during the server render and in the gap between first paint and hydration.
+ * They read module state and nothing else, so there is no browser to be missing
+ * — the answer in those contexts is `undefined`, meaning "no page has been
+ * rendered into this module", which is exactly true.
+ */
+/**
+ * What the SERVER matched for the page currently on screen.
+ *
+ * Deliberately not `ClientRouteMatch` (`web/src/client/runtime/types.ts`): that
+ * is the deprecated client matcher's output shape, entry object and all, and
+ * this is the opposite claim — a name the server sent us.
+ */
+type MatchedRoute = {
+  /** The matched page manifest entry's stable `name`, e.g. `products.details`. */readonly name: string;
+  /**
+   * The params the SERVER matched, e.g. `{ id: "42" }` for `/users/:id`, and
+   * `{}` for a route with no dynamic segments.
+   *
+   * `undefined` means the payload carried no `params` key — an older build, or
+   * a document cached across a deploy. It is NOT the same answer as `{}`, and
+   * this module will not collapse the two: `{}` is the server saying "this
+   * route has no params", `undefined` is the server not having said. Inventing
+   * the first from the second would be a lie a caller cannot detect, which is
+   * the same standard {@link previousRoute} is held to below. Every payload a
+   * current server produces carries the key.
+   *
+   * A COPY of the payload's object, so a caller writing to it cannot reach the
+   * payload the page was built from.
+   */
+  readonly params?: Readonly<Record<string, string>>;
+};
+/**
+ * @returns what the SERVER matched for the page on screen — see this file's
+ * header for why that is the answer and not a client-side match. Correct from
+ * the first render of the initial page, since the hydration payload carried the
+ * match with it.
+ *
+ * `undefined` means no page has been rendered into this module: a server
+ * render, or an import evaluated before hydration mounted. Safe to call in
+ * either — it does not throw and does not touch `window`.
+ */
+declare function currentRoute(): MatchedRoute | undefined;
+/**
+ * @returns the entry that was on screen BEFORE the current one, or `undefined`
+ * when the current page is the one the user landed on. That `undefined` is a
+ * real answer, not a missing one — there is no previous route on a first visit,
+ * and reporting the current one would be a lie a caller cannot detect.
+ *
+ * This is the previously SWAPPED page, not the previous history entry: pressing
+ * Back is itself a navigation here, so going A → B → Back leaves the previous
+ * route as B. Safe to call with no browser.
+ */
+declare function previousRoute(): MatchedRoute | undefined;
+//#endregion
+export { MatchedRoute, currentRoute, previousRoute };
+//# sourceMappingURL=current-route.d.mts.map

package/esm/client/navigation/current-route.mjs

@@ -0,0 +1,66 @@
+//#region ../web/src/client/navigation/current-route.ts
+let current;
+let previous;
+/**
+* The payload `current` was projected from, kept ONLY to recognise it again.
+*
+* `NavigationRoot` records on every render pass, because a page component must
+* be able to call `currentRoute()` while it is itself rendering — including on
+* the initial mount, where no effect has run yet. Renders are not navigations
+* though: StrictMode invokes them twice, and a parent re-render invokes them
+* again for free. One swap is one payload OBJECT, so identity is what separates
+* "we moved" from "we rendered again". Comparing names instead would both miss
+* a `/users/1` → `/users/2` move and invent one out of a double render.
+*/
+let source;
+/**
+* Record the payload the page on screen was built from.
+*
+* Called by `NavigationRoot` during render — at mount with the hydration
+* payload, and after each swap with the fetched one. Not part of the public
+* surface: the payload is the navigation runtime's to hand over, and a caller
+* setting the current route by hand would be asserting a match that never
+* happened.
+*
+* Idempotent per payload object, so re-rendering the same page never shifts
+* {@link previousRoute}.
+*/
+function recordCurrentRoute(payload) {
+	if (source === payload) return;
+	source = payload;
+	previous = current;
+	current = payload.params === void 0 ? { name: payload.name } : {
+		name: payload.name,
+		params: { ...payload.params }
+	};
+}
+/**
+* @returns what the SERVER matched for the page on screen — see this file's
+* header for why that is the answer and not a client-side match. Correct from
+* the first render of the initial page, since the hydration payload carried the
+* match with it.
+*
+* `undefined` means no page has been rendered into this module: a server
+* render, or an import evaluated before hydration mounted. Safe to call in
+* either — it does not throw and does not touch `window`.
+*/
+function currentRoute() {
+	return current;
+}
+/**
+* @returns the entry that was on screen BEFORE the current one, or `undefined`
+* when the current page is the one the user landed on. That `undefined` is a
+* real answer, not a missing one — there is no previous route on a first visit,
+* and reporting the current one would be a lie a caller cannot detect.
+*
+* This is the previously SWAPPED page, not the previous history entry: pressing
+* Back is itself a navigation here, so going A → B → Back leaves the previous
+* route as B. Safe to call with no browser.
+*/
+function previousRoute() {
+	return previous;
+}
+
+//#endregion
+export { currentRoute, previousRoute, recordCurrentRoute };
+//# sourceMappingURL=current-route.mjs.map

package/esm/client/navigation/current-route.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"current-route.mjs","names":[],"sources":["../../../../../../../../web/src/client/navigation/current-route.ts"],"sourcesContent":["import type { HydrationDocumentPayloadSource } from \"../../hydration-payload\";\n\n/**\n * \"Which route am I on?\", under the name MRR spells it\n * (`@mongez/react-router` — `src/utilities.tsx`).\n *\n * ## The shift, and it is the whole point of this file\n *\n * MRR's `currentRoute()` returns the object ITS MATCHER produced: MRR is a CSR\n * router, so the browser matched the URL and the answer is the browser's own\n * conclusion. Warlock has no client matcher and must never grow one (canon\n * `9c8f878b`) — the SERVER router is the only matcher, and a second one can\n * disagree with it about the very request it is hydrating.\n *\n * So the name is MRR's because the QUESTION is the same one, but the ANSWER\n * comes from somewhere else: the matched entry's name AND ITS PARAMS travel on\n * the hydration payload (`web/src/components/document-context.ts`), and this\n * module reports what arrived. Nothing here parses a path, compares a URL to a\n * pattern, or knows that routes have shapes.\n *\n * The practical consequence for a caller: this is the server's match, so it is\n * as correct as the page on screen and it cannot drift from it — including on\n * the very first render, before any client navigation, which is most page\n * views.\n *\n * ## The params, and where they come from\n *\n * `bundle.route.params` (`web/src/server/execute-page-request.ts:288`) is the\n * router's own answer; `buildHydrationPayload` puts it on the payload and the\n * projection below hands it over unchanged. Deriving `{ id: \"42\" }` from\n * `location.pathname` here would BE the second matcher this file exists to\n * refuse — a URL and a pattern are exactly what it must never compare.\n *\n * ## Why nothing here touches `window`\n *\n * Both readers are importable from universal modules, so both can be CALLED\n * during the server render and in the gap between first paint and hydration.\n * They read module state and nothing else, so there is no browser to be missing\n * — the answer in those contexts is `undefined`, meaning \"no page has been\n * rendered into this module\", which is exactly true.\n */\n\n/**\n * What the SERVER matched for the page currently on screen.\n *\n * Deliberately not `ClientRouteMatch` (`web/src/client/runtime/types.ts`): that\n * is the deprecated client matcher's output shape, entry object and all, and\n * this is the opposite claim — a name the server sent us.\n */\nexport type MatchedRoute = {\n  /** The matched page manifest entry's stable `name`, e.g. `products.details`. */\n  readonly name: string;\n  /**\n   * The params the SERVER matched, e.g. `{ id: \"42\" }` for `/users/:id`, and\n   * `{}` for a route with no dynamic segments.\n   *\n   * `undefined` means the payload carried no `params` key — an older build, or\n   * a document cached across a deploy. It is NOT the same answer as `{}`, and\n   * this module will not collapse the two: `{}` is the server saying \"this\n   * route has no params\", `undefined` is the server not having said. Inventing\n   * the first from the second would be a lie a caller cannot detect, which is\n   * the same standard {@link previousRoute} is held to below. Every payload a\n   * current server produces carries the key.\n   *\n   * A COPY of the payload's object, so a caller writing to it cannot reach the\n   * payload the page was built from.\n   */\n  readonly params?: Readonly<Record<string, string>>;\n};\n\nlet current: MatchedRoute | undefined;\nlet previous: MatchedRoute | undefined;\n\n/**\n * The payload `current` was projected from, kept ONLY to recognise it again.\n *\n * `NavigationRoot` records on every render pass, because a page component must\n * be able to call `currentRoute()` while it is itself rendering — including on\n * the initial mount, where no effect has run yet. Renders are not navigations\n * though: StrictMode invokes them twice, and a parent re-render invokes them\n * again for free. One swap is one payload OBJECT, so identity is what separates\n * \"we moved\" from \"we rendered again\". Comparing names instead would both miss\n * a `/users/1` → `/users/2` move and invent one out of a double render.\n */\nlet source: HydrationDocumentPayloadSource | undefined;\n\n/**\n * Record the payload the page on screen was built from.\n *\n * Called by `NavigationRoot` during render — at mount with the hydration\n * payload, and after each swap with the fetched one. Not part of the public\n * surface: the payload is the navigation runtime's to hand over, and a caller\n * setting the current route by hand would be asserting a match that never\n * happened.\n *\n * Idempotent per payload object, so re-rendering the same page never shifts\n * {@link previousRoute}.\n */\nexport function recordCurrentRoute(payload: HydrationDocumentPayloadSource): void {\n  if (source === payload) return;\n\n  source = payload;\n  previous = current;\n  // A COPY when the payload carried params, and no key at all when it did not\n  // — the projection reports what arrived and never fills a gap in.\n  current =\n    payload.params === undefined\n      ? { name: payload.name }\n      : { name: payload.name, params: { ...payload.params } };\n}\n\n/**\n * @returns what the SERVER matched for the page on screen — see this file's\n * header for why that is the answer and not a client-side match. Correct from\n * the first render of the initial page, since the hydration payload carried the\n * match with it.\n *\n * `undefined` means no page has been rendered into this module: a server\n * render, or an import evaluated before hydration mounted. Safe to call in\n * either — it does not throw and does not touch `window`.\n */\nexport function currentRoute(): MatchedRoute | undefined {\n  return current;\n}\n\n/**\n * @returns the entry that was on screen BEFORE the current one, or `undefined`\n * when the current page is the one the user landed on. That `undefined` is a\n * real answer, not a missing one — there is no previous route on a first visit,\n * and reporting the current one would be a lie a caller cannot detect.\n *\n * This is the previously SWAPPED page, not the previous history entry: pressing\n * Back is itself a navigation here, so going A → B → Back leaves the previous\n * route as B. Safe to call with no browser.\n */\nexport function previousRoute(): MatchedRoute | undefined {\n  return previous;\n}\n"],"mappings":";AAsEA,IAAI;AACJ,IAAI;;;;;;;;;;;;AAaJ,IAAI;;;;;;;;;;;;;AAcJ,SAAgB,mBAAmB,SAA+C;CAChF,IAAI,WAAW,SAAS;CAExB,SAAS;CACT,WAAW;CAGX,UACE,QAAQ,WAAW,SACf,EAAE,MAAM,QAAQ,KAAK,IACrB;EAAE,MAAM,QAAQ;EAAM,QAAQ,EAAE,GAAG,QAAQ,OAAO;CAAE;AAC5D;;;;;;;;;;;AAYA,SAAgB,eAAyC;CACvD,OAAO;AACT;;;;;;;;;;;AAYA,SAAgB,gBAA0C;CACxD,OAAO;AACT"}

package/esm/client/navigation/fetch-page-data.mjs

@@ -0,0 +1,97 @@
+import { DATA_RESPONSE_CONTENT_TYPE, WARLOCK_DATA_REQUEST_HEADER } from "../../routing/data-request.mjs";
+
+//#region ../web/src/client/navigation/fetch-page-data.ts
+/**
+* Ask the server for a URL's page data instead of its document.
+*
+* This is the browser half of the representation split: the same route the user
+* would have loaded, asked for as JSON via the `x-warlock-data` marker. What
+* comes back is exactly the payload a full page load embeds, so the caller can
+* rebuild the tree from it with no second code path.
+*
+* ## Every failure degrades to a REAL navigation, never to an error screen
+*
+* A client navigation is an OPTIMISATION over what the browser already does
+* perfectly well. So nothing here reports a failure to the user — it reports
+* `hard-navigate`, and the caller hands the URL back to the browser. The user
+* gets the page; they just get it the slow way.
+*
+* That is what makes the whole feature safe to add: the worst case of a bug in
+* this file is the behaviour we had before the file existed. Rendering our own
+* "navigation failed" state would be strictly worse than the fallback we
+* already have, and would turn every unhandled edge — an auth redirect to an
+* external IdP, a maintenance page, a proxy that strips the header, a deploy
+* that changed the payload shape mid-session — into a dead end.
+*/
+/**
+* Whether the body is the payload we asked for.
+*
+* Checked rather than assumed because a 200 does not mean "this came from the
+* page pipeline": a captive portal, an SSO interstitial or a proxy error page
+* all answer 200 with HTML. Parsing that as JSON would throw; treating a
+* successful parse of *something else* as a payload would render garbage.
+*/
+function isPayloadResponse(response) {
+	return (response.headers.get("content-type") ?? "").includes(DATA_RESPONSE_CONTENT_TYPE);
+}
+/**
+* The shape check, kept deliberately narrow: `name` is the only field the tree
+* builder cannot proceed without — it selects the page. The data fields are
+* page-defined and may legitimately be anything, including `null`.
+*/
+function isPayloadShape(value) {
+	return typeof value === "object" && value !== null && typeof value.name === "string";
+}
+async function fetchPageData(url) {
+	let response;
+	try {
+		response = await fetch(url, {
+			headers: {
+				[WARLOCK_DATA_REQUEST_HEADER]: "1",
+				accept: DATA_RESPONSE_CONTENT_TYPE
+			},
+			credentials: "same-origin",
+			redirect: "follow"
+		});
+	} catch (error) {
+		return {
+			type: "hard-navigate",
+			url,
+			reason: `request failed: ${String(error)}`
+		};
+	}
+	if (!response.ok) return {
+		type: "hard-navigate",
+		url,
+		reason: `status ${response.status}`
+	};
+	if (!isPayloadResponse(response)) return {
+		type: "hard-navigate",
+		url,
+		reason: `unexpected content-type "${response.headers.get("content-type") ?? "none"}"`
+	};
+	let parsed;
+	try {
+		parsed = await response.json();
+	} catch (error) {
+		return {
+			type: "hard-navigate",
+			url,
+			reason: `malformed JSON: ${String(error)}`
+		};
+	}
+	if (!isPayloadShape(parsed)) return {
+		type: "hard-navigate",
+		url,
+		reason: "payload has no route name"
+	};
+	return {
+		type: "payload",
+		payload: parsed,
+		url: response.url || url
+	};
+}
+
+//#endregion
+export { fetchPageData };
+//# sourceMappingURL=fetch-page-data.mjs.map

package/esm/client/navigation/fetch-page-data.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-page-data.mjs","names":[],"sources":["../../../../../../../../web/src/client/navigation/fetch-page-data.ts"],"sourcesContent":["/**\n * Ask the server for a URL's page data instead of its document.\n *\n * This is the browser half of the representation split: the same route the user\n * would have loaded, asked for as JSON via the `x-warlock-data` marker. What\n * comes back is exactly the payload a full page load embeds, so the caller can\n * rebuild the tree from it with no second code path.\n *\n * ## Every failure degrades to a REAL navigation, never to an error screen\n *\n * A client navigation is an OPTIMISATION over what the browser already does\n * perfectly well. So nothing here reports a failure to the user — it reports\n * `hard-navigate`, and the caller hands the URL back to the browser. The user\n * gets the page; they just get it the slow way.\n *\n * That is what makes the whole feature safe to add: the worst case of a bug in\n * this file is the behaviour we had before the file existed. Rendering our own\n * \"navigation failed\" state would be strictly worse than the fallback we\n * already have, and would turn every unhandled edge — an auth redirect to an\n * external IdP, a maintenance page, a proxy that strips the header, a deploy\n * that changed the payload shape mid-session — into a dead end.\n */\nimport {\n  DATA_RESPONSE_CONTENT_TYPE,\n  WARLOCK_DATA_REQUEST_HEADER,\n  WARLOCK_DATA_REQUEST_VALUE,\n} from \"../../routing/data-request\";\nimport type { HydrationDocumentPayloadSource } from \"../../hydration-payload\";\n\nexport type PageDataResult =\n  | {\n      type: \"payload\";\n      /**\n       * The payload to rebuild the tree from.\n       */\n      payload: HydrationDocumentPayloadSource;\n      /**\n       * The URL the response actually came from — NOT the one requested. A\n       * redirect is followed by `fetch` transparently, so a login-required page\n       * answers from `/login`, and pushing the requested URL into history would\n       * leave the address bar lying about what is on screen.\n       */\n      url: string;\n    }\n  | {\n      type: \"hard-navigate\";\n      url: string;\n      /** Why, for a console warning — never shown to the user. */\n      reason: string;\n    };\n\n/**\n * Whether the body is the payload we asked for.\n *\n * Checked rather than assumed because a 200 does not mean \"this came from the\n * page pipeline\": a captive portal, an SSO interstitial or a proxy error page\n * all answer 200 with HTML. Parsing that as JSON would throw; treating a\n * successful parse of *something else* as a payload would render garbage.\n */\nfunction isPayloadResponse(response: Response): boolean {\n  return (response.headers.get(\"content-type\") ?? \"\").includes(DATA_RESPONSE_CONTENT_TYPE);\n}\n\n/**\n * The shape check, kept deliberately narrow: `name` is the only field the tree\n * builder cannot proceed without — it selects the page. The data fields are\n * page-defined and may legitimately be anything, including `null`.\n */\nfunction isPayloadShape(value: unknown): value is HydrationDocumentPayloadSource {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    typeof (value as { name?: unknown }).name === \"string\"\n  );\n}\n\nexport async function fetchPageData(url: string): Promise<PageDataResult> {\n  let response: Response;\n\n  try {\n    response = await fetch(url, {\n      headers: {\n        [WARLOCK_DATA_REQUEST_HEADER]: WARLOCK_DATA_REQUEST_VALUE,\n        accept: DATA_RESPONSE_CONTENT_TYPE,\n      },\n      // Same-origin credentials so a navigation carries the session exactly as\n      // a document request would. Without this a client navigation could be\n      // logged out while a full load of the same URL is not.\n      credentials: \"same-origin\",\n      // Redirects are FOLLOWED, not intercepted: the marker header is re-sent,\n      // so the destination answers with a payload too, and `response.url` tells\n      // us where we ended up. Handling redirects ourselves would mean\n      // re-implementing the rules the browser already has.\n      redirect: \"follow\",\n    });\n  } catch (error) {\n    // Offline, DNS, CORS, an aborted connection. The browser can render its own\n    // network error far better than we can fake one.\n    return { type: \"hard-navigate\", url, reason: `request failed: ${String(error)}` };\n  }\n\n  if (!response.ok) {\n    // 404, 500, 403 — all of these have a real page the server renders. Letting\n    // the browser load it gets the correct status AND the correct document,\n    // rather than us inventing a client-side error state that the server's own\n    // error page already covers.\n    return { type: \"hard-navigate\", url, reason: `status ${response.status}` };\n  }\n\n  if (!isPayloadResponse(response)) {\n    return {\n      type: \"hard-navigate\",\n      url,\n      reason: `unexpected content-type \"${response.headers.get(\"content-type\") ?? \"none\"}\"`,\n    };\n  }\n\n  let parsed: unknown;\n\n  try {\n    parsed = await response.json();\n  } catch (error) {\n    return { type: \"hard-navigate\", url, reason: `malformed JSON: ${String(error)}` };\n  }\n\n  if (!isPayloadShape(parsed)) {\n    return { type: \"hard-navigate\", url, reason: \"payload has no route name\" };\n  }\n\n  // `response.url` is absolute and reflects any redirect that was followed.\n  // Falling back to the requested URL keeps this working under test doubles\n  // that do not set it.\n  return { type: \"payload\", payload: parsed, url: response.url || url };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2DA,SAAS,kBAAkB,UAA6B;CACtD,QAAQ,SAAS,QAAQ,IAAI,cAAc,KAAK,GAAE,CAAE,SAAS,0BAA0B;AACzF;;;;;;AAOA,SAAS,eAAe,OAAyD;CAC/E,OACE,OAAO,UAAU,YACjB,UAAU,QACV,OAAQ,MAA6B,SAAS;AAElD;AAEA,eAAsB,cAAc,KAAsC;CACxE,IAAI;CAEJ,IAAI;EACF,WAAW,MAAM,MAAM,KAAK;GAC1B,SAAS;KACN;IACD,QAAQ;GACV;GAIA,aAAa;GAKb,UAAU;EACZ,CAAC;CACH,SAAS,OAAO;EAGd,OAAO;GAAE,MAAM;GAAiB;GAAK,QAAQ,mBAAmB,OAAO,KAAK;EAAI;CAClF;CAEA,IAAI,CAAC,SAAS,IAKZ,OAAO;EAAE,MAAM;EAAiB;EAAK,QAAQ,UAAU,SAAS;CAAS;CAG3E,IAAI,CAAC,kBAAkB,QAAQ,GAC7B,OAAO;EACL,MAAM;EACN;EACA,QAAQ,4BAA4B,SAAS,QAAQ,IAAI,cAAc,KAAK,OAAO;CACrF;CAGF,IAAI;CAEJ,IAAI;EACF,SAAS,MAAM,SAAS,KAAK;CAC/B,SAAS,OAAO;EACd,OAAO;GAAE,MAAM;GAAiB;GAAK,QAAQ,mBAAmB,OAAO,KAAK;EAAI;CAClF;CAEA,IAAI,CAAC,eAAe,MAAM,GACxB,OAAO;EAAE,MAAM;EAAiB;EAAK,QAAQ;CAA4B;CAM3E,OAAO;EAAE,MAAM;EAAW,SAAS;EAAQ,KAAK,SAAS,OAAO;CAAI;AACtE"}