@warlock.js/web 5.0.2 → 5.2.0

package/esm/components/document-context.d.mts

@@ -1,7 +1,45 @@
-//#region ../web/src/components/document-context.d.ts
+//#region web/src/components/document-context.d.ts
+/**
+ * The JSON-safe error shape carried from the server document to browser
+ * hydration.
+ *
+ * This is deliberately NOT the original thrown object. Error prototypes,
+ * identity, non-enumerable fields and arbitrary custom values do not survive a
+ * JSON boundary reliably. The server renders `ErrorPageProps` with the
+ * original value, then normalizes it to this lossy representation only for the
+ * hydration payload. Normalization also owns disclosure: `stack` is optional
+ * and must be omitted or redacted when server internals are not safe to expose
+ * to the browser.
+ */
+type SerializedPageError = {
+  readonly name: string;
+  readonly message: string;
+  readonly stack?: string;
+};
+/**
+ * Props received by the application-owned `error.page.tsx` during SSR.
+ *
+ * Deliberately preserve the thrown value here. An application can use its own
+ * error classes, symbols, or structured values while rendering on the server;
+ * this public component contract is not a JSON boundary.
+ */
+type ErrorPageProps = {
+  readonly error: unknown;
+  readonly status: number;
+};
+/**
+ * The JSON-safe counterpart of {@link ErrorPageProps}, used only after the
+ * document crosses from SSR into browser hydration. Keeping this distinct
+ * prevents a serialized approximation from being mistaken for the original
+ * thrown value available to the server render.
+ */
+type SerializedErrorPageProps = {
+  readonly error: SerializedPageError;
+  readonly status: number;
+};
 declare const PAYLOAD_SCRIPT_ID = "__WARLOCK_DATA__";
 /** Escape JSON text for raw insertion into an application/json script. */
 declare function escapePayload(json: string): string;
 //#endregion
-export { PAYLOAD_SCRIPT_ID, escapePayload };
+export { ErrorPageProps, PAYLOAD_SCRIPT_ID, SerializedErrorPageProps, SerializedPageError, escapePayload };
 //# sourceMappingURL=document-context.d.mts.map

package/esm/components/document-context.mjs

@@ -1,6 +1,6 @@
 import { createContext, useContext } from "react";
 
-//#region ../web/src/components/document-context.ts
+//#region web/src/components/document-context.ts
 const PAYLOAD_SCRIPT_ID = "__WARLOCK_DATA__";
 const LINE_SEPARATOR = String.fromCharCode(8232);
 const PARAGRAPH_SEPARATOR = String.fromCharCode(8233);

package/esm/components/document-context.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"document-context.mjs","names":[],"sources":["../../../../../../../web/src/components/document-context.ts"],"sourcesContent":["import { createContext, useContext } from \"react\";\nimport type { MetadataOutput } from \"../metadata\";\n\nexport type HydrationDocumentPayloadSource = {\n  readonly appData: unknown;\n  readonly layoutData: unknown;\n  readonly pageData: unknown;\n  readonly shared: unknown;\n  /**\n   * The matched page manifest entry's stable `name` — the same field the\n   * manifest entry contract `{ type, name, path, load }` declares. It is on\n   * the wire so the browser can look up WHICH page the server rendered\n   * instead of re-matching `location.pathname` itself: re-matching is a\n   * second implementation of route semantics, and it can disagree with the\n   * server on the very request it is hydrating.\n   */\n  readonly name: string;\n  /**\n   * The params the SERVER matched for this request — `bundle.route.params`\n   * (`server/execute-page-request.ts:288`), carried untransformed. Same reason\n   * `name` is here: the browser must not re-derive them from\n   * `location.pathname`, because deriving them IS a second matcher.\n   *\n   * OPTIONAL, and ungated on purpose — see {@link metadata} below for the rule\n   * both new keys share. The server always emits it (`{}` for a route with no\n   * dynamic segments), so absence means the payload came from a producer that\n   * predates this key; `currentRoute()` then reports `{}` rather than failing a\n   * page over an accessor.\n   */\n  readonly params?: Readonly<Record<string, string>>;\n  /**\n   * The page metadata the server resolved at stage 8, carried WHOLE — the same\n   * `MetadataOutput` `<Head/>` rendered into the document on the first request.\n   *\n   * Why it has to be on the wire at all: `<Head/>` renders inside the App\n   * level, and the App level is not part of the hydrated tree (the client\n   * mounts at `#root`, which App contains). So on a client navigation there is\n   * no React render that can reach `<head>` — without this key the browser\n   * never learns the new page's title and the tab keeps the old one.\n   *\n   * OPTIONAL, deliberately: `bundle.metadata` is itself optional\n   * (`server/execute-page-request.ts:296`) — a page that exports no `metadata`\n   * produces none, and a loader short-circuit skips stage 8 entirely. Gating a\n   * key the server is right not to produce would make `readHydrationPayload`\n   * throw on a valid page. Present-but-not-an-object is still MALFORMED and\n   * still throws; only ABSENT is accepted.\n   */\n  readonly metadata?: MetadataOutput;\n};\n\nexport const PAYLOAD_SCRIPT_ID = \"__WARLOCK_DATA__\";\n\nconst LINE_SEPARATOR = String.fromCharCode(0x2028);\nconst PARAGRAPH_SEPARATOR = String.fromCharCode(0x2029);\n\n/** Escape JSON text for raw insertion into an application/json script. */\nexport function escapePayload(json: string): string {\n  return json\n    .split(\"<\")\n    .join(\"\\\\u003c\")\n    .split(\">\")\n    .join(\"\\\\u003e\")\n    .split(LINE_SEPARATOR)\n    .join(\"\\\\u2028\")\n    .split(PARAGRAPH_SEPARATOR)\n    .join(\"\\\\u2029\");\n}\n\n/**\n * What `<Head/>`/`<Scripts/>` need to render real elements instead of the\n * framework injecting them by string surgery post-render (Suki, room seq\n * 1205): the resolved page metadata and the exact payload the hydration\n * script will read back. Provided once, around the root element, before\n * `renderToString` runs (`render-page.ts`'s stage 9 — the bundle is already\n * complete by then). Universal: no server-only imports, so the client's\n * hydration entry (a later slice) can provide the same shape from the parsed\n * payload script.\n */\nexport type DocumentContextValue = {\n  metadata: MetadataOutput | undefined;\n  payload: HydrationDocumentPayloadSource;\n  /**\n   * The nonce/lang/dir SLOTS: fed by the render provider from CORE request\n   * fields — request nonce, request locale — never from app-owned `shared`\n   * keys, which an app can overwrite. The provider-side\n   * wiring is a separate slice, so these are absent at runtime until it\n   * lands; every reader must treat them as optional.\n   */\n  nonce?: string;\n  lang?: string;\n  dir?: string;\n};\n\nexport const DocumentContext = createContext<DocumentContextValue | undefined>(undefined);\n\n/**\n * Require the page pipeline's universal document state. The payload id and\n * escaping helpers remain exported above for the existing server seam.\n */\nexport function useDocumentContext(componentName: string): DocumentContextValue {\n  const value = useContext(DocumentContext);\n\n  if (!value) {\n    throw new Error(\n      `<${componentName}/> was rendered outside the page pipeline's document context ` +\n        \"(web/src/components/document-context.ts). Fix: only render it inside \" +\n        \"an App/Layout/Page component tree the pipeline itself renders.\",\n    );\n  }\n\n  return value;\n}\n"],"mappings":";;;AAkDA,MAAa,oBAAoB;AAEjC,MAAM,iBAAiB,OAAO,aAAa,IAAM;AACjD,MAAM,sBAAsB,OAAO,aAAa,IAAM;;AAGtD,SAAgB,cAAc,MAAsB;CAClD,OAAO,KACJ,MAAM,GAAG,CAAC,CACV,KAAK,SAAS,CAAC,CACf,MAAM,GAAG,CAAC,CACV,KAAK,SAAS,CAAC,CACf,MAAM,cAAc,CAAC,CACrB,KAAK,SAAS,CAAC,CACf,MAAM,mBAAmB,CAAC,CAC1B,KAAK,SAAS;AACnB;AA2BA,MAAa,kBAAkB,cAAgD,MAAS;;;;;AAMxF,SAAgB,mBAAmB,eAA6C;CAC9E,MAAM,QAAQ,WAAW,eAAe;CAExC,IAAI,CAAC,OACH,MAAM,IAAI,MACR,IAAI,cAAc,iMAGpB;CAGF,OAAO;AACT"}
+{"version":3,"file":"document-context.mjs","names":[],"sources":["C:/Work/Warlock.js/web/src/components/document-context.ts"],"sourcesContent":["import { createContext, useContext } from \"react\";\nimport type { MetadataOutput } from \"../metadata\";\n\n/**\n * The JSON-safe error shape carried from the server document to browser\n * hydration.\n *\n * This is deliberately NOT the original thrown object. Error prototypes,\n * identity, non-enumerable fields and arbitrary custom values do not survive a\n * JSON boundary reliably. The server renders `ErrorPageProps` with the\n * original value, then normalizes it to this lossy representation only for the\n * hydration payload. Normalization also owns disclosure: `stack` is optional\n * and must be omitted or redacted when server internals are not safe to expose\n * to the browser.\n */\nexport type SerializedPageError = {\n  readonly name: string;\n  readonly message: string;\n  readonly stack?: string;\n};\n\n/**\n * Props received by the application-owned `error.page.tsx` during SSR.\n *\n * Deliberately preserve the thrown value here. An application can use its own\n * error classes, symbols, or structured values while rendering on the server;\n * this public component contract is not a JSON boundary.\n */\nexport type ErrorPageProps = {\n  readonly error: unknown;\n  readonly status: number;\n};\n\n/**\n * The JSON-safe counterpart of {@link ErrorPageProps}, used only after the\n * document crosses from SSR into browser hydration. Keeping this distinct\n * prevents a serialized approximation from being mistaken for the original\n * thrown value available to the server render.\n */\nexport type SerializedErrorPageProps = {\n  readonly error: SerializedPageError;\n  readonly status: number;\n};\n\nexport type HydrationDocumentPayloadSource = {\n  readonly appData: unknown;\n  readonly layoutData: unknown;\n  readonly pageData: unknown;\n  readonly shared: unknown;\n  /**\n   * The matched page manifest entry's stable `name` — the same field the\n   * manifest entry contract `{ type, name, path, load }` declares. It is on\n   * the wire so the browser can look up WHICH page the server rendered\n   * instead of re-matching `location.pathname` itself: re-matching is a\n   * second implementation of route semantics, and it can disagree with the\n   * server on the very request it is hydrating.\n   */\n  readonly name: string;\n  /**\n   * The params the SERVER matched for this request — `bundle.route.params`\n   * (`server/execute-page-request.ts:288`), carried untransformed. Same reason\n   * `name` is here: the browser must not re-derive them from\n   * `location.pathname`, because deriving them IS a second matcher.\n   *\n   * OPTIONAL, and ungated on purpose — see {@link metadata} below for the rule\n   * both new keys share. The server always emits it (`{}` for a route with no\n   * dynamic segments), so absence means the payload came from a producer that\n   * predates this key; `currentRoute()` then reports `{}` rather than failing a\n   * page over an accessor.\n   */\n  readonly params?: Readonly<Record<string, string>>;\n  /**\n   * The page metadata the server resolved at stage 8, carried WHOLE — the same\n   * `MetadataOutput` `<Head/>` rendered into the document on the first request.\n   *\n   * Why it has to be on the wire at all: `<Head/>` renders inside the App\n   * level, and the App level is not part of the hydrated tree (the client\n   * mounts at `#root`, which App contains). So on a client navigation there is\n   * no React render that can reach `<head>` — without this key the browser\n   * never learns the new page's title and the tab keeps the old one.\n   *\n   * OPTIONAL, deliberately: `bundle.metadata` is itself optional\n   * (`server/execute-page-request.ts:296`) — a page that exports no `metadata`\n   * produces none, and a loader short-circuit skips stage 8 entirely. Gating a\n   * key the server is right not to produce would make `readHydrationPayload`\n   * throw on a valid page. Present-but-not-an-object is still MALFORMED and\n   * still throws; only ABSENT is accepted.\n   */\n  readonly metadata?: MetadataOutput;\n  /**\n   * Present only when the server selected the application-owned error page for\n   * this response. Atomic rather than two independently optional top-level\n   * fields: a status without an error (or the reverse) cannot describe a tree\n   * the browser can hydrate.\n   *\n   * `name` above intentionally remains the ORIGINAL matched route. This field\n   * selects the `ErrorPage` module projected into that route's client\n   * composition; it does not turn the error page into a second browsable route.\n   */\n  readonly errorPage?: SerializedErrorPageProps;\n};\n\nexport const PAYLOAD_SCRIPT_ID = \"__WARLOCK_DATA__\";\n\nconst LINE_SEPARATOR = String.fromCharCode(0x2028);\nconst PARAGRAPH_SEPARATOR = String.fromCharCode(0x2029);\n\n/** Escape JSON text for raw insertion into an application/json script. */\nexport function escapePayload(json: string): string {\n  return json\n    .split(\"<\")\n    .join(\"\\\\u003c\")\n    .split(\">\")\n    .join(\"\\\\u003e\")\n    .split(LINE_SEPARATOR)\n    .join(\"\\\\u2028\")\n    .split(PARAGRAPH_SEPARATOR)\n    .join(\"\\\\u2029\");\n}\n\n/**\n * What `<Head/>`/`<Scripts/>` need to render real elements instead of the\n * framework injecting them by string surgery post-render (Suki, room seq\n * 1205): the resolved page metadata and the exact payload the hydration\n * script will read back. Provided once, around the root element, before\n * `renderToString` runs (`render-page.ts`'s stage 9 — the bundle is already\n * complete by then). Universal: no server-only imports, so the client's\n * hydration entry (a later slice) can provide the same shape from the parsed\n * payload script.\n */\nexport type DocumentContextValue = {\n  metadata: MetadataOutput | undefined;\n  payload: HydrationDocumentPayloadSource;\n  /**\n   * The nonce/lang/dir SLOTS: fed by the render provider from CORE request\n   * fields — request nonce, request locale — never from app-owned `shared`\n   * keys, which an app can overwrite. The provider-side\n   * wiring is a separate slice, so these are absent at runtime until it\n   * lands; every reader must treat them as optional.\n   */\n  nonce?: string;\n  lang?: string;\n  dir?: string;\n};\n\nexport const DocumentContext = createContext<DocumentContextValue | undefined>(undefined);\n\n/**\n * Require the page pipeline's universal document state. The payload id and\n * escaping helpers remain exported above for the existing server seam.\n */\nexport function useDocumentContext(componentName: string): DocumentContextValue {\n  const value = useContext(DocumentContext);\n\n  if (!value) {\n    throw new Error(\n      `<${componentName}/> was rendered outside the page pipeline's document context ` +\n        \"(web/src/components/document-context.ts). Fix: only render it inside \" +\n        \"an App/Layout/Page component tree the pipeline itself renders.\",\n    );\n  }\n\n  return value;\n}\n"],"mappings":";;;AAsGA,MAAa,oBAAoB;AAEjC,MAAM,iBAAiB,OAAO,aAAa,IAAM;AACjD,MAAM,sBAAsB,OAAO,aAAa,IAAM;;AAGtD,SAAgB,cAAc,MAAsB;CAClD,OAAO,KACJ,MAAM,GAAG,EACT,KAAK,SAAS,EACd,MAAM,GAAG,EACT,KAAK,SAAS,EACd,MAAM,cAAc,EACpB,KAAK,SAAS,EACd,MAAM,mBAAmB,EACzB,KAAK,SAAS;AACnB;AA2BA,MAAa,kBAAkB,cAAgD,MAAS;;;;;AAMxF,SAAgB,mBAAmB,eAA6C;CAC9E,MAAM,QAAQ,WAAW,eAAe;CAExC,IAAI,CAAC,OACH,MAAM,IAAI,MACR,IAAI,cAAc,iMAGpB;CAGF,OAAO;AACT"}

package/esm/components/head.d.mts

@@ -1,6 +1,6 @@
 import { ReactElement } from "react";
 
-//#region ../web/src/components/head.d.ts
+//#region web/src/components/head.d.ts
 /**
  * OPTIONAL placement override for the framework's `<head>` injection — the
  * page's `metadata` output, the stylesheet/preload tags and the

package/esm/components/head.mjs

@@ -1,7 +1,7 @@
 import { useDocumentContext } from "./document-context.mjs";
 import { Fragment, createElement } from "react";
 
-//#region ../web/src/components/head.ts
+//#region web/src/components/head.ts
 /**
 * OPTIONAL placement override for the framework's `<head>` injection — the
 * page's `metadata` output, the stylesheet/preload tags and the

package/esm/components/head.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"head.mjs","names":[],"sources":["../../../../../../../web/src/components/head.ts"],"sourcesContent":["import { createElement, Fragment, type ReactElement } from \"react\";\nimport { useDocumentContext } from \"./document-context\";\n\n/**\n * OPTIONAL placement override for the framework's `<head>` injection — the\n * page's `metadata` output, the stylesheet/preload tags and the\n * canonical/alternate links land here when it is present, and at the default\n * position when it is not (root.tsx:85-92). Takes no props: it says WHERE, and\n * only that.\n */\nexport function Head(): ReactElement {\n  const { metadata } = useDocumentContext(\"Head\");\n\n  const keywords =\n    metadata?.keywords === undefined\n      ? undefined\n      : Array.isArray(metadata.keywords)\n        ? metadata.keywords.join(\", \")\n        : metadata.keywords;\n\n  const openGraph = metadata?.openGraph;\n  // Falls back to the top-level fields — the only two fallbacks the type declares.\n  const ogTitle = openGraph?.title ?? metadata?.title;\n  const ogDescription = openGraph?.description ?? metadata?.description;\n\n  const twitter = metadata?.twitter;\n\n  return createElement(\n    Fragment,\n    null,\n    createElement(\"meta\", { charSet: \"utf-8\" }),\n    metadata?.title !== undefined ? createElement(\"title\", null, metadata.title) : null,\n    metadata?.description !== undefined\n      ? createElement(\"meta\", { name: \"description\", content: metadata.description })\n      : null,\n    keywords !== undefined ? createElement(\"meta\", { name: \"keywords\", content: keywords }) : null,\n    metadata?.canonical !== undefined\n      ? createElement(\"link\", { rel: \"canonical\", href: metadata.canonical })\n      : null,\n    metadata?.robots !== undefined\n      ? createElement(\"meta\", { name: \"robots\", content: metadata.robots })\n      : null,\n    openGraph !== undefined && ogTitle !== undefined\n      ? createElement(\"meta\", { property: \"og:title\", content: ogTitle })\n      : null,\n    openGraph !== undefined && ogDescription !== undefined\n      ? createElement(\"meta\", { property: \"og:description\", content: ogDescription })\n      : null,\n    openGraph?.image !== undefined\n      ? createElement(\"meta\", { property: \"og:image\", content: openGraph.image })\n      : null,\n    openGraph?.url !== undefined\n      ? createElement(\"meta\", { property: \"og:url\", content: openGraph.url })\n      : null,\n    openGraph?.type !== undefined\n      ? createElement(\"meta\", { property: \"og:type\", content: openGraph.type })\n      : null,\n    twitter?.card !== undefined\n      ? createElement(\"meta\", { name: \"twitter:card\", content: twitter.card })\n      : null,\n    twitter?.title !== undefined\n      ? createElement(\"meta\", { name: \"twitter:title\", content: twitter.title })\n      : null,\n    twitter?.description !== undefined\n      ? createElement(\"meta\", { name: \"twitter:description\", content: twitter.description })\n      : null,\n    twitter?.image !== undefined\n      ? createElement(\"meta\", { name: \"twitter:image\", content: twitter.image })\n      : null,\n  );\n}\n"],"mappings":";;;;;;;;;;;AAUA,SAAgB,OAAqB;CACnC,MAAM,EAAE,aAAa,mBAAmB,MAAM;CAE9C,MAAM,WACJ,UAAU,aAAa,SACnB,SACA,MAAM,QAAQ,SAAS,QAAQ,IAC7B,SAAS,SAAS,KAAK,IAAI,IAC3B,SAAS;CAEjB,MAAM,YAAY,UAAU;CAE5B,MAAM,UAAU,WAAW,SAAS,UAAU;CAC9C,MAAM,gBAAgB,WAAW,eAAe,UAAU;CAE1D,MAAM,UAAU,UAAU;CAE1B,OAAO,cACL,UACA,MACA,cAAc,QAAQ,EAAE,SAAS,QAAQ,CAAC,GAC1C,UAAU,UAAU,SAAY,cAAc,SAAS,MAAM,SAAS,KAAK,IAAI,MAC/E,UAAU,gBAAgB,SACtB,cAAc,QAAQ;EAAE,MAAM;EAAe,SAAS,SAAS;CAAY,CAAC,IAC5E,MACJ,aAAa,SAAY,cAAc,QAAQ;EAAE,MAAM;EAAY,SAAS;CAAS,CAAC,IAAI,MAC1F,UAAU,cAAc,SACpB,cAAc,QAAQ;EAAE,KAAK;EAAa,MAAM,SAAS;CAAU,CAAC,IACpE,MACJ,UAAU,WAAW,SACjB,cAAc,QAAQ;EAAE,MAAM;EAAU,SAAS,SAAS;CAAO,CAAC,IAClE,MACJ,cAAc,UAAa,YAAY,SACnC,cAAc,QAAQ;EAAE,UAAU;EAAY,SAAS;CAAQ,CAAC,IAChE,MACJ,cAAc,UAAa,kBAAkB,SACzC,cAAc,QAAQ;EAAE,UAAU;EAAkB,SAAS;CAAc,CAAC,IAC5E,MACJ,WAAW,UAAU,SACjB,cAAc,QAAQ;EAAE,UAAU;EAAY,SAAS,UAAU;CAAM,CAAC,IACxE,MACJ,WAAW,QAAQ,SACf,cAAc,QAAQ;EAAE,UAAU;EAAU,SAAS,UAAU;CAAI,CAAC,IACpE,MACJ,WAAW,SAAS,SAChB,cAAc,QAAQ;EAAE,UAAU;EAAW,SAAS,UAAU;CAAK,CAAC,IACtE,MACJ,SAAS,SAAS,SACd,cAAc,QAAQ;EAAE,MAAM;EAAgB,SAAS,QAAQ;CAAK,CAAC,IACrE,MACJ,SAAS,UAAU,SACf,cAAc,QAAQ;EAAE,MAAM;EAAiB,SAAS,QAAQ;CAAM,CAAC,IACvE,MACJ,SAAS,gBAAgB,SACrB,cAAc,QAAQ;EAAE,MAAM;EAAuB,SAAS,QAAQ;CAAY,CAAC,IACnF,MACJ,SAAS,UAAU,SACf,cAAc,QAAQ;EAAE,MAAM;EAAiB,SAAS,QAAQ;CAAM,CAAC,IACvE,IACN;AACF"}
+{"version":3,"file":"head.mjs","names":[],"sources":["C:/Work/Warlock.js/web/src/components/head.ts"],"sourcesContent":["import { createElement, Fragment, type ReactElement } from \"react\";\nimport { useDocumentContext } from \"./document-context\";\n\n/**\n * OPTIONAL placement override for the framework's `<head>` injection — the\n * page's `metadata` output, the stylesheet/preload tags and the\n * canonical/alternate links land here when it is present, and at the default\n * position when it is not (root.tsx:85-92). Takes no props: it says WHERE, and\n * only that.\n */\nexport function Head(): ReactElement {\n  const { metadata } = useDocumentContext(\"Head\");\n\n  const keywords =\n    metadata?.keywords === undefined\n      ? undefined\n      : Array.isArray(metadata.keywords)\n        ? metadata.keywords.join(\", \")\n        : metadata.keywords;\n\n  const openGraph = metadata?.openGraph;\n  // Falls back to the top-level fields — the only two fallbacks the type declares.\n  const ogTitle = openGraph?.title ?? metadata?.title;\n  const ogDescription = openGraph?.description ?? metadata?.description;\n\n  const twitter = metadata?.twitter;\n\n  return createElement(\n    Fragment,\n    null,\n    createElement(\"meta\", { charSet: \"utf-8\" }),\n    metadata?.title !== undefined ? createElement(\"title\", null, metadata.title) : null,\n    metadata?.description !== undefined\n      ? createElement(\"meta\", { name: \"description\", content: metadata.description })\n      : null,\n    keywords !== undefined ? createElement(\"meta\", { name: \"keywords\", content: keywords }) : null,\n    metadata?.canonical !== undefined\n      ? createElement(\"link\", { rel: \"canonical\", href: metadata.canonical })\n      : null,\n    metadata?.robots !== undefined\n      ? createElement(\"meta\", { name: \"robots\", content: metadata.robots })\n      : null,\n    openGraph !== undefined && ogTitle !== undefined\n      ? createElement(\"meta\", { property: \"og:title\", content: ogTitle })\n      : null,\n    openGraph !== undefined && ogDescription !== undefined\n      ? createElement(\"meta\", { property: \"og:description\", content: ogDescription })\n      : null,\n    openGraph?.image !== undefined\n      ? createElement(\"meta\", { property: \"og:image\", content: openGraph.image })\n      : null,\n    openGraph?.url !== undefined\n      ? createElement(\"meta\", { property: \"og:url\", content: openGraph.url })\n      : null,\n    openGraph?.type !== undefined\n      ? createElement(\"meta\", { property: \"og:type\", content: openGraph.type })\n      : null,\n    twitter?.card !== undefined\n      ? createElement(\"meta\", { name: \"twitter:card\", content: twitter.card })\n      : null,\n    twitter?.title !== undefined\n      ? createElement(\"meta\", { name: \"twitter:title\", content: twitter.title })\n      : null,\n    twitter?.description !== undefined\n      ? createElement(\"meta\", { name: \"twitter:description\", content: twitter.description })\n      : null,\n    twitter?.image !== undefined\n      ? createElement(\"meta\", { name: \"twitter:image\", content: twitter.image })\n      : null,\n  );\n}\n"],"mappings":";;;;;;;;;;;AAUA,SAAgB,OAAqB;CACnC,MAAM,EAAE,aAAa,mBAAmB,MAAM;CAE9C,MAAM,WACJ,UAAU,aAAa,SACnB,SACA,MAAM,QAAQ,SAAS,QAAQ,IAC7B,SAAS,SAAS,KAAK,IAAI,IAC3B,SAAS;CAEjB,MAAM,YAAY,UAAU;CAE5B,MAAM,UAAU,WAAW,SAAS,UAAU;CAC9C,MAAM,gBAAgB,WAAW,eAAe,UAAU;CAE1D,MAAM,UAAU,UAAU;CAE1B,OAAO,cACL,UACA,MACA,cAAc,QAAQ,EAAE,SAAS,QAAQ,CAAC,GAC1C,UAAU,UAAU,SAAY,cAAc,SAAS,MAAM,SAAS,KAAK,IAAI,MAC/E,UAAU,gBAAgB,SACtB,cAAc,QAAQ;EAAE,MAAM;EAAe,SAAS,SAAS;CAAY,CAAC,IAC5E,MACJ,aAAa,SAAY,cAAc,QAAQ;EAAE,MAAM;EAAY,SAAS;CAAS,CAAC,IAAI,MAC1F,UAAU,cAAc,SACpB,cAAc,QAAQ;EAAE,KAAK;EAAa,MAAM,SAAS;CAAU,CAAC,IACpE,MACJ,UAAU,WAAW,SACjB,cAAc,QAAQ;EAAE,MAAM;EAAU,SAAS,SAAS;CAAO,CAAC,IAClE,MACJ,cAAc,UAAa,YAAY,SACnC,cAAc,QAAQ;EAAE,UAAU;EAAY,SAAS;CAAQ,CAAC,IAChE,MACJ,cAAc,UAAa,kBAAkB,SACzC,cAAc,QAAQ;EAAE,UAAU;EAAkB,SAAS;CAAc,CAAC,IAC5E,MACJ,WAAW,UAAU,SACjB,cAAc,QAAQ;EAAE,UAAU;EAAY,SAAS,UAAU;CAAM,CAAC,IACxE,MACJ,WAAW,QAAQ,SACf,cAAc,QAAQ;EAAE,UAAU;EAAU,SAAS,UAAU;CAAI,CAAC,IACpE,MACJ,WAAW,SAAS,SAChB,cAAc,QAAQ;EAAE,UAAU;EAAW,SAAS,UAAU;CAAK,CAAC,IACtE,MACJ,SAAS,SAAS,SACd,cAAc,QAAQ;EAAE,MAAM;EAAgB,SAAS,QAAQ;CAAK,CAAC,IACrE,MACJ,SAAS,UAAU,SACf,cAAc,QAAQ;EAAE,MAAM;EAAiB,SAAS,QAAQ;CAAM,CAAC,IACvE,MACJ,SAAS,gBAAgB,SACrB,cAAc,QAAQ;EAAE,MAAM;EAAuB,SAAS,QAAQ;CAAY,CAAC,IACnF,MACJ,SAAS,UAAU,SACf,cAAc,QAAQ;EAAE,MAAM;EAAiB,SAAS,QAAQ;CAAM,CAAC,IACvE,IACN;AACF"}

package/esm/components/link.d.mts

@@ -1,6 +1,6 @@
 import { AnchorHTMLAttributes, ComponentType, ReactElement } from "react";
 
-//#region ../web/src/components/link.d.ts
+//#region web/src/components/link.d.ts
 /**
  * `<Link>` is SUGAR over `href()`, and deliberately thin.
  *

package/esm/components/link.mjs

@@ -3,7 +3,7 @@ import { prefetchPageData } from "../client/navigation/prefetch.mjs";
 import { currentNavigator } from "../routing/navigator.mjs";
 import { createElement } from "react";
 
-//#region ../web/src/components/link.ts
+//#region web/src/components/link.ts
 const DESTINATION_PROPS = [
 	"to",
 	"href",

package/esm/components/link.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"link.mjs","names":[],"sources":["../../../../../../../web/src/components/link.ts"],"sourcesContent":["import { createElement } from \"react\";\nimport type {\n  AnchorHTMLAttributes,\n  ComponentType,\n  FocusEvent,\n  MouseEvent,\n  ReactElement,\n} from \"react\";\nimport { prefetchPageData } from \"../client/navigation/prefetch\";\nimport { currentNavigator } from \"../routing/navigator\";\nimport { href, knownRouteNames } from \"../routing/route-table\";\n\n/**\n * `<Link>` is SUGAR over `href()`, and deliberately thin.\n *\n * `href(name, params, query)` is the durable primitive — it serves emails,\n * redirects, `Location` headers and every non-React caller, none of which can\n * render a component. This file adds one thing to it: an anchor element.\n *\n * It renders a real `<a href>`. Client-side interception is a later slice of\n * the navigation runtime and lands here without changing this API, which is the\n * point of routing everything through `href` first: navigation becomes a\n * BEHAVIOUR change, not an API change.\n *\n * ── Parity with `@mongez/react-router` ───────────────────────────────────────\n * `href`, `newTab`, `email`, `tel`, `component` and `prefetch` are spelled\n * exactly as MRR spells them, so a component moved across keeps compiling.\n * `params` and `query` are ours and have no MRR equivalent: they pair with the\n * typed `href()` helper, which is what makes a route NAME — rather than a URL —\n * the thing a call site names.\n *\n * ── The semantic divergence this file bridges ────────────────────────────────\n * MRR's `to` is a PATH. Ours was a route NAME, and only a name — which meant a\n * component moved across from MRR compiled and then threw at render, because\n * `\"/products\"` is not the name of anything. The two packages disagreed about\n * what the most-used prop in either of them MEANS.\n *\n * Since 2026-08-24 (owner ruling) `to`/`href` accept BOTH, discriminated by\n * SHAPE — see {@link isLiteralUrl}. That is what makes MRR code portable, and\n * it costs nothing at a Warlock call site, because the two grammars cannot\n * collide: a route name never begins with `/` and never carries a `scheme:`.\n * The ruling RESTS on that, so this file asserts it rather than trusting it\n * ({@link RouteNameShapeCollisionError}).\n */\n\ntype AnchorProps = Omit<AnchorHTMLAttributes<HTMLAnchorElement>, \"href\">;\n\n/**\n * Where the link goes. Every field is documented here once; which COMBINATIONS\n * are legal is decided by {@link LinkDestination}.\n */\ntype LinkDestinationProps = {\n  /**\n   * A route NAME, or a literal URL — told apart by SHAPE.\n   *\n   * `\"products.details\"` is a NAME and is resolved through the route table. A\n   * page that moves changes its URL and keeps its name, so every call site\n   * survives the move; a dead name throws at render naming the routes that do\n   * exist, rather than rendering an anchor that 404s. This is the form to\n   * prefer, and the only one `params` and `query` apply to.\n   *\n   * `\"/pricing\"`, `\"https://stripe.com\"`, `\"mailto:sales@example.com\"` and any\n   * other `scheme:` are LITERAL — passed through to the element untouched, with\n   * no route lookup at all. An app links out, and a route name is not a thing\n   * you can have for a page that is not yours.\n   */\n  to?: string;\n  /**\n   * An alias of {@link to}, for parity with `@mongez/react-router`. Identical\n   * in every respect, including which shapes it accepts.\n   */\n  href?: string;\n  /** Renders a `mailto:` link. Not an in-app navigation. */\n  email?: string;\n  /** Renders a `tel:` link. Not an in-app navigation. */\n  tel?: string;\n  /**\n   * Values for the route's `:param` segments, e.g. `{ id }` for\n   * `\"/products/:id\"`. Only meaningful with a route NAME.\n   */\n  params?: Record<string, unknown>;\n  /**\n   * Query string values; an `undefined` value is omitted. Only meaningful with\n   * a route NAME.\n   */\n  query?: Record<string, unknown>;\n};\n\n/**\n * EXACTLY ONE destination, enforced by the type.\n *\n * The alternative — a documented precedence such as \"`to` wins over `href`\" —\n * is silent by construction: the losing prop goes on compiling and goes on\n * reading like it works at the call site, and the anchor points at the wrong\n * page. Refusing the pair costs a call site one edit and can never be\n * misread. The runtime refuses it as well, because a JavaScript caller and a\n * cast both get past this.\n */\ntype LinkDestination =\n  | { to: string; href?: never; email?: never; tel?: never }\n  | { href: string; to?: never; email?: never; tel?: never }\n  | { email: string; to?: never; href?: never; tel?: never }\n  | { tel: string; to?: never; href?: never; email?: never };\n\nexport type LinkProps = AnchorProps &\n  LinkDestinationProps &\n  LinkDestination & {\n    /**\n     * Open in a new browsing context: `target=\"_blank\"` plus the `rel` that\n     * stops the opened page from reaching back through `window.opener`.\n     *\n     * A caller's own `target`/`rel` win — this only fills in what was not said.\n     */\n    newTab?: boolean;\n    /**\n     * Render as something other than `<a>` — a tag name or a component.\n     *\n     * It receives the resolved `href`, the click handler and every remaining\n     * prop, so a design-system anchor keeps client-side navigation as long as\n     * it spreads what it is given onto the element it renders.\n     *\n     * `ComponentType<any>` is MRR's signature, kept verbatim: the component is\n     * the caller's and its props are unknowable from here.\n     */\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    component?: ComponentType<any> | string;\n    /**\n     * Fetch this page's data when the pointer or the keyboard reaches the link,\n     * so the click that follows swaps without a round trip.\n     *\n     * A GUESS, and treated as one everywhere: it is never awaited, a failure is\n     * silent, and the click behaves exactly as it would without it. Opt-in per\n     * link rather than on by default, because every prefetch is a request the\n     * user did not ask for and someone pays for the bandwidth.\n     *\n     * IGNORED for anything that is not an in-app navigation — an external URL,\n     * `mailto:`, `tel:`, `newTab`, any explicit `target`. Prefetching those\n     * would mean issuing a cross-origin request to a third party on hover,\n     * which is not a thing a link component may decide to do.\n     */\n    prefetch?: boolean;\n  };\n\nconst DESTINATION_PROPS = [\"to\", \"href\", \"email\", \"tel\"] as const;\n\nexport class AmbiguousLinkDestinationError extends Error {\n  public constructor(public readonly providedProps: readonly string[]) {\n    super(\n      `Warlock <Link> was given ${providedProps\n        .map(name => JSON.stringify(name))\n        .join(\" and \")}, but a link goes to exactly one place. There is no ` +\n        \"precedence between them on purpose: one of the two would silently win, and the \" +\n        \"call site would go on naming a destination that never renders. Delete the one \" +\n        \"you did not mean.\",\n    );\n    this.name = \"AmbiguousLinkDestinationError\";\n  }\n}\n\nexport class MissingLinkDestinationError extends Error {\n  public constructor() {\n    super(\n      `Warlock <Link> was given no destination. Pass exactly one of ${DESTINATION_PROPS.map(\n        name => JSON.stringify(name),\n      ).join(\", \")}. It is not defaulted to the current page: an anchor with an empty ` +\n        \"`href` renders as a working link and reloads the page when clicked, which is a \" +\n        \"harder fault to see than this message.\",\n    );\n    this.name = \"MissingLinkDestinationError\";\n  }\n}\n\nexport class RouteArgumentsOnLiteralUrlError extends Error {\n  public constructor(\n    public readonly url: string,\n    public readonly providedProps: readonly string[],\n  ) {\n    super(\n      `Warlock <Link> was given ${providedProps\n        .map(name => JSON.stringify(name))\n        .join(\" and \")} alongside the literal URL \"${url}\". Those apply to a route NAME, ` +\n        \"which is resolved through the route table; a literal URL is passed through exactly \" +\n        \"as written, so they would have been dropped and the link would have pointed at an \" +\n        \"unfiltered page that still looked right at the call site. Put the values in the URL, \" +\n        \"or name the route.\",\n    );\n    this.name = \"RouteArgumentsOnLiteralUrlError\";\n  }\n}\n\n/**\n * The ruling's one assumption, broken. See the module doc comment: telling a\n * literal URL from a route NAME by shape is only safe while no route is NAMED\n * like a URL, and nothing in the route pipeline validates a hand-declared\n * `route.name`. So the collision is checked at the one place it could do harm,\n * where it is a loud refusal instead of an anchor that silently points\n * somewhere else.\n */\nexport class RouteNameShapeCollisionError extends Error {\n  public constructor(public readonly routeName: string) {\n    super(\n      `Warlock route table: a route is NAMED ${JSON.stringify(routeName)}, which is shaped ` +\n        \"like a URL. <Link> tells a literal URL from a route name by shape — a destination \" +\n        \"starting with `/` or carrying a `scheme:` is passed through untouched — so this name \" +\n        \"can never be resolved, and every link to it would silently point at that path \" +\n        \"instead. Rename the route (`route = { path, name }`) to a dotted name such as \" +\n        `${JSON.stringify(routeName.replace(/^\\/+/, \"\").replace(/\\//g, \".\") || \"index\")}.`,\n    );\n    this.name = \"RouteNameShapeCollisionError\";\n  }\n}\n\ntype Destination = {\n  /** What lands on the element's `href`. */\n  url: string;\n  /**\n   * Whether this URL is a page in THIS app — the only kind the client\n   * navigation runtime may be asked about, and the only kind that may be\n   * prefetched. `mailto:`, `tel:` and an external URL hand off to another\n   * application or another origin entirely, so intercepting any of them would\n   * break it, and speculatively fetching one would be a cross-origin request\n   * the developer never asked for.\n   */\n  isInApp: boolean;\n};\n\n/**\n * Any RFC 3986 scheme — `https:`, `mailto:`, `tel:`, `whatsapp:`, an app's own\n * custom one. Matched generically rather than as a list of known schemes: a\n * list would silently resolve `bitcoin:...` through the route table, which is\n * the exact failure this ruling exists to remove, and it would have to grow\n * forever.\n */\nconst SCHEME_PATTERN = /^[a-z][a-z0-9+.-]*:/i;\n\n/**\n * Whether this destination is a URL to be used as written, rather than a route\n * name to resolve.\n *\n * The whole discriminator, and deliberately the whole of it: two cheap shape\n * tests, no parsing, no matching. Anything more would be a SECOND route matcher\n * living beside the server's, which this codebase refuses everywhere it comes\n * up — a matcher that disagreed with the real one would produce links to pages\n * that do not exist.\n */\nfunction isLiteralUrl(destination: string): boolean {\n  return destination.startsWith(\"/\") || SCHEME_PATTERN.test(destination);\n}\n\n/**\n * Whether a literal URL addresses THIS app.\n *\n * A path is ours. A `scheme:` is not — including `https:` to our own origin,\n * which would need `window.location` to recognise and would make the answer\n * depend on where the code is running. And `//host/path` is PROTOCOL-RELATIVE:\n * it starts with a slash and is nonetheless another origin, which is precisely\n * the case a \"starts with `/`\" test alone would hand to the navigator, where it\n * becomes a `pushState` to a foreign origin — a SecurityError — or a\n * speculative fetch of a third-party host.\n */\nfunction addressesThisApp(url: string): boolean {\n  return url.startsWith(\"/\") && !url.startsWith(\"//\");\n}\n\n/**\n * Refuses the one table that would make {@link isLiteralUrl} wrong.\n *\n * Reached only for a destination already judged literal, so the cost is a scan\n * of the published names for links that were never going to hit the table\n * anyway — and zero for the route-name form, which is the common one. The right\n * permanent home for this is `publishRouteTable`, at boot, once (see the report\n * on this card).\n */\nfunction assertNotARouteName(url: string): void {\n  if (knownRouteNames().includes(url)) throw new RouteNameShapeCollisionError(url);\n}\n\nconst ROUTE_ARGUMENT_PROPS = [\"params\", \"query\"] as const;\n\nfunction resolveDestination(props: LinkDestinationProps): Destination {\n  const provided = DESTINATION_PROPS.filter(name => props[name] !== undefined);\n\n  if (provided.length > 1) throw new AmbiguousLinkDestinationError(provided);\n\n  if (provided.length === 0) throw new MissingLinkDestinationError();\n\n  if (props.email !== undefined) return { url: `mailto:${props.email}`, isInApp: false };\n\n  if (props.tel !== undefined) return { url: `tel:${props.tel}`, isInApp: false };\n\n  const destination = (props.to ?? props.href) as string;\n\n  /*\n    LITERAL: `/pricing`, `https://stripe.com`, `mailto:…`, `whatsapp://…`. It\n    goes to the element exactly as written and the route table is never\n    consulted — there is nothing to look up, and looking anyway is what used to\n    throw `UnknownRouteNameError` on every link out of the application.\n  */\n  if (isLiteralUrl(destination)) {\n    const routeArguments = ROUTE_ARGUMENT_PROPS.filter(name => props[name] !== undefined);\n\n    if (routeArguments.length > 0) {\n      throw new RouteArgumentsOnLiteralUrlError(destination, routeArguments);\n    }\n\n    assertNotARouteName(destination);\n\n    return { url: destination, isInApp: addressesThisApp(destination) };\n  }\n\n  /*\n    A NAME, resolved against the route table published at boot from the SAME\n    discovery result the server registered its routes from. The previous version\n    of this file restated six URLs in a literal map, so linking to any seventh\n    page in the application threw — the map was the limit on what could be\n    linked, and nothing said so at the call site.\n  */\n  return { url: href(destination, props.params, props.query), isInApp: true };\n}\n\n/**\n * Whether this click should be left entirely to the browser.\n *\n * Every case here is a click that MEANS something other than \"go there in this\n * tab\", and intercepting any of them would take away behaviour the user\n * explicitly asked for:\n *\n *   - a modifier or middle button: open in a new tab/window, or download\n *   - `download`: save the resource, do not render it\n *   - already prevented: something upstream in the tree handled this click\n *\n * Left button with no modifiers is the only click that means plain navigation.\n * The `target` case is decided before this, from the RESOLVED target, because\n * `newTab` sets it after the caller's props are read.\n */\nfunction isPlainLeftClick(event: MouseEvent<HTMLAnchorElement>): boolean {\n  return (\n    event.button === 0 &&\n    !event.metaKey &&\n    !event.ctrlKey &&\n    !event.shiftKey &&\n    !event.altKey &&\n    !event.defaultPrevented\n  );\n}\n\n/**\n * A target other than `_self` names ANOTHER browsing context — `_blank`, but\n * also `_parent`, `_top` and any named frame. Client navigation rewrites the\n * history of THIS one, so none of them are ours to intercept.\n */\nfunction opensAnotherContext(target: string | undefined): boolean {\n  return target !== undefined && target !== \"_self\";\n}\n\nexport function Link({\n  to,\n  href: hrefAlias,\n  email,\n  tel,\n  params,\n  query,\n  newTab,\n  prefetch,\n  component: Component = \"a\",\n  children,\n  onClick,\n  ...elementProps\n}: LinkProps): ReactElement {\n  const { url, isInApp } = resolveDestination({\n    to,\n    href: hrefAlias,\n    email,\n    tel,\n    params,\n    query,\n  });\n\n  const target = elementProps.target ?? (newTab === true ? \"_blank\" : undefined);\n\n  // Only a DEFAULT: a caller that wrote its own `rel` (`\"me noopener\"`,\n  // `\"external\"`) meant it, and overwriting it would delete a value the page\n  // depends on to say something this component knows nothing about.\n  const rel =\n    elementProps.rel ?? (target === \"_blank\" ? \"noopener noreferrer\" : undefined);\n\n  const handleClick = (event: MouseEvent<HTMLAnchorElement>): void => {\n    // The caller's handler runs FIRST and unconditionally — it may be doing\n    // analytics, closing a menu, or calling `preventDefault()` to veto the\n    // navigation outright. Deciding before it ran would let this component\n    // navigate away from a click the application had already cancelled.\n    onClick?.(event);\n\n    // `mailto:`, `tel:` and anything aimed at another browsing context leave\n    // this page standing. The runtime is not consulted at all — asking it would\n    // spend a page-data fetch on a click that was never going to navigate here.\n    if (!isInApp || opensAnotherContext(target)) return;\n\n    if (!isPlainLeftClick(event)) return;\n\n    /*\n      Asked for per click, never captured at render: the runtime registers\n      itself when the hydration bundle mounts, which is AFTER the first render\n      of every anchor on the page. A value read at render time would be\n      `undefined` forever for exactly the links present at hydration — that is,\n      all of them.\n\n      Absent (server render, or before hydration) the anchor is left alone and\n      does what an anchor does. That is the whole progressive-enhancement story:\n      links work before this code runs, and work better after.\n    */\n    if (currentNavigator()?.(url) !== true) return;\n\n    event.preventDefault();\n  };\n\n  /*\n    The SAME gate the click uses, asked before any speculative request exists:\n    only a destination this app would have navigated to itself may be fetched\n    ahead of time. `mailto:`, `tel:`, an external URL and anything aimed at\n    another browsing context are all clicks that leave this page, and none of\n    them has page data to fetch.\n  */\n  const prefetchesOnInteraction =\n    prefetch === true && isInApp && !opensAnotherContext(target);\n\n  /*\n    Attached ONLY when prefetching — a link without the prop keeps whatever\n    handlers the caller passed, on the element, unwrapped.\n\n    Hover AND focus, because a keyboard user never generates the first one and\n    would otherwise be the only visitor who never gets the optimisation.\n\n    Fire-and-forget by construction: `prefetchPageData` never rejects and is\n    never awaited, so nothing here can delay the event or surface a failure. It\n    is also safe to reach on the server — it no-ops without a browser — which is\n    why this file can import it directly rather than through a `connect*` seam\n    like the navigator's. The navigator needs a seam because the runtime behind\n    it drags React state and the page registry into the server bundle; the\n    prefetch cache is a `Map` and a `fetch` call, inert until an event fires.\n  */\n  const prefetchHandlers = prefetchesOnInteraction\n    ? {\n        onMouseEnter: (event: MouseEvent<HTMLAnchorElement>): void => {\n          elementProps.onMouseEnter?.(event);\n          void prefetchPageData(url);\n        },\n        onFocus: (event: FocusEvent<HTMLAnchorElement>): void => {\n          elementProps.onFocus?.(event);\n          void prefetchPageData(url);\n        },\n      }\n    : undefined;\n\n  return createElement(\n    Component,\n    { ...elementProps, ...prefetchHandlers, target, rel, href: url, onClick: handleClick },\n    children,\n  );\n}\n"],"mappings":"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"}
+{"version":3,"file":"link.mjs","names":[],"sources":["C:/Work/Warlock.js/web/src/components/link.ts"],"sourcesContent":["import { createElement } from \"react\";\nimport type {\n  AnchorHTMLAttributes,\n  ComponentType,\n  FocusEvent,\n  MouseEvent,\n  ReactElement,\n} from \"react\";\nimport { prefetchPageData } from \"../client/navigation/prefetch\";\nimport { currentNavigator } from \"../routing/navigator\";\nimport { href, knownRouteNames } from \"../routing/route-table\";\n\n/**\n * `<Link>` is SUGAR over `href()`, and deliberately thin.\n *\n * `href(name, params, query)` is the durable primitive — it serves emails,\n * redirects, `Location` headers and every non-React caller, none of which can\n * render a component. This file adds one thing to it: an anchor element.\n *\n * It renders a real `<a href>`. Client-side interception is a later slice of\n * the navigation runtime and lands here without changing this API, which is the\n * point of routing everything through `href` first: navigation becomes a\n * BEHAVIOUR change, not an API change.\n *\n * ── Parity with `@mongez/react-router` ───────────────────────────────────────\n * `href`, `newTab`, `email`, `tel`, `component` and `prefetch` are spelled\n * exactly as MRR spells them, so a component moved across keeps compiling.\n * `params` and `query` are ours and have no MRR equivalent: they pair with the\n * typed `href()` helper, which is what makes a route NAME — rather than a URL —\n * the thing a call site names.\n *\n * ── The semantic divergence this file bridges ────────────────────────────────\n * MRR's `to` is a PATH. Ours was a route NAME, and only a name — which meant a\n * component moved across from MRR compiled and then threw at render, because\n * `\"/products\"` is not the name of anything. The two packages disagreed about\n * what the most-used prop in either of them MEANS.\n *\n * Since 2026-08-24 (owner ruling) `to`/`href` accept BOTH, discriminated by\n * SHAPE — see {@link isLiteralUrl}. That is what makes MRR code portable, and\n * it costs nothing at a Warlock call site, because the two grammars cannot\n * collide: a route name never begins with `/` and never carries a `scheme:`.\n * The ruling RESTS on that, so this file asserts it rather than trusting it\n * ({@link RouteNameShapeCollisionError}).\n */\n\ntype AnchorProps = Omit<AnchorHTMLAttributes<HTMLAnchorElement>, \"href\">;\n\n/**\n * Where the link goes. Every field is documented here once; which COMBINATIONS\n * are legal is decided by {@link LinkDestination}.\n */\ntype LinkDestinationProps = {\n  /**\n   * A route NAME, or a literal URL — told apart by SHAPE.\n   *\n   * `\"products.details\"` is a NAME and is resolved through the route table. A\n   * page that moves changes its URL and keeps its name, so every call site\n   * survives the move; a dead name throws at render naming the routes that do\n   * exist, rather than rendering an anchor that 404s. This is the form to\n   * prefer, and the only one `params` and `query` apply to.\n   *\n   * `\"/pricing\"`, `\"https://stripe.com\"`, `\"mailto:sales@example.com\"` and any\n   * other `scheme:` are LITERAL — passed through to the element untouched, with\n   * no route lookup at all. An app links out, and a route name is not a thing\n   * you can have for a page that is not yours.\n   */\n  to?: string;\n  /**\n   * An alias of {@link to}, for parity with `@mongez/react-router`. Identical\n   * in every respect, including which shapes it accepts.\n   */\n  href?: string;\n  /** Renders a `mailto:` link. Not an in-app navigation. */\n  email?: string;\n  /** Renders a `tel:` link. Not an in-app navigation. */\n  tel?: string;\n  /**\n   * Values for the route's `:param` segments, e.g. `{ id }` for\n   * `\"/products/:id\"`. Only meaningful with a route NAME.\n   */\n  params?: Record<string, unknown>;\n  /**\n   * Query string values; an `undefined` value is omitted. Only meaningful with\n   * a route NAME.\n   */\n  query?: Record<string, unknown>;\n};\n\n/**\n * EXACTLY ONE destination, enforced by the type.\n *\n * The alternative — a documented precedence such as \"`to` wins over `href`\" —\n * is silent by construction: the losing prop goes on compiling and goes on\n * reading like it works at the call site, and the anchor points at the wrong\n * page. Refusing the pair costs a call site one edit and can never be\n * misread. The runtime refuses it as well, because a JavaScript caller and a\n * cast both get past this.\n */\ntype LinkDestination =\n  | { to: string; href?: never; email?: never; tel?: never }\n  | { href: string; to?: never; email?: never; tel?: never }\n  | { email: string; to?: never; href?: never; tel?: never }\n  | { tel: string; to?: never; href?: never; email?: never };\n\nexport type LinkProps = AnchorProps &\n  LinkDestinationProps &\n  LinkDestination & {\n    /**\n     * Open in a new browsing context: `target=\"_blank\"` plus the `rel` that\n     * stops the opened page from reaching back through `window.opener`.\n     *\n     * A caller's own `target`/`rel` win — this only fills in what was not said.\n     */\n    newTab?: boolean;\n    /**\n     * Render as something other than `<a>` — a tag name or a component.\n     *\n     * It receives the resolved `href`, the click handler and every remaining\n     * prop, so a design-system anchor keeps client-side navigation as long as\n     * it spreads what it is given onto the element it renders.\n     *\n     * `ComponentType<any>` is MRR's signature, kept verbatim: the component is\n     * the caller's and its props are unknowable from here.\n     */\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    component?: ComponentType<any> | string;\n    /**\n     * Fetch this page's data when the pointer or the keyboard reaches the link,\n     * so the click that follows swaps without a round trip.\n     *\n     * A GUESS, and treated as one everywhere: it is never awaited, a failure is\n     * silent, and the click behaves exactly as it would without it. Opt-in per\n     * link rather than on by default, because every prefetch is a request the\n     * user did not ask for and someone pays for the bandwidth.\n     *\n     * IGNORED for anything that is not an in-app navigation — an external URL,\n     * `mailto:`, `tel:`, `newTab`, any explicit `target`. Prefetching those\n     * would mean issuing a cross-origin request to a third party on hover,\n     * which is not a thing a link component may decide to do.\n     */\n    prefetch?: boolean;\n  };\n\nconst DESTINATION_PROPS = [\"to\", \"href\", \"email\", \"tel\"] as const;\n\nexport class AmbiguousLinkDestinationError extends Error {\n  public constructor(public readonly providedProps: readonly string[]) {\n    super(\n      `Warlock <Link> was given ${providedProps\n        .map(name => JSON.stringify(name))\n        .join(\" and \")}, but a link goes to exactly one place. There is no ` +\n        \"precedence between them on purpose: one of the two would silently win, and the \" +\n        \"call site would go on naming a destination that never renders. Delete the one \" +\n        \"you did not mean.\",\n    );\n    this.name = \"AmbiguousLinkDestinationError\";\n  }\n}\n\nexport class MissingLinkDestinationError extends Error {\n  public constructor() {\n    super(\n      `Warlock <Link> was given no destination. Pass exactly one of ${DESTINATION_PROPS.map(\n        name => JSON.stringify(name),\n      ).join(\", \")}. It is not defaulted to the current page: an anchor with an empty ` +\n        \"`href` renders as a working link and reloads the page when clicked, which is a \" +\n        \"harder fault to see than this message.\",\n    );\n    this.name = \"MissingLinkDestinationError\";\n  }\n}\n\nexport class RouteArgumentsOnLiteralUrlError extends Error {\n  public constructor(\n    public readonly url: string,\n    public readonly providedProps: readonly string[],\n  ) {\n    super(\n      `Warlock <Link> was given ${providedProps\n        .map(name => JSON.stringify(name))\n        .join(\" and \")} alongside the literal URL \"${url}\". Those apply to a route NAME, ` +\n        \"which is resolved through the route table; a literal URL is passed through exactly \" +\n        \"as written, so they would have been dropped and the link would have pointed at an \" +\n        \"unfiltered page that still looked right at the call site. Put the values in the URL, \" +\n        \"or name the route.\",\n    );\n    this.name = \"RouteArgumentsOnLiteralUrlError\";\n  }\n}\n\n/**\n * The ruling's one assumption, broken. See the module doc comment: telling a\n * literal URL from a route NAME by shape is only safe while no route is NAMED\n * like a URL, and nothing in the route pipeline validates a hand-declared\n * `route.name`. So the collision is checked at the one place it could do harm,\n * where it is a loud refusal instead of an anchor that silently points\n * somewhere else.\n */\nexport class RouteNameShapeCollisionError extends Error {\n  public constructor(public readonly routeName: string) {\n    super(\n      `Warlock route table: a route is NAMED ${JSON.stringify(routeName)}, which is shaped ` +\n        \"like a URL. <Link> tells a literal URL from a route name by shape — a destination \" +\n        \"starting with `/` or carrying a `scheme:` is passed through untouched — so this name \" +\n        \"can never be resolved, and every link to it would silently point at that path \" +\n        \"instead. Rename the route (`route = { path, name }`) to a dotted name such as \" +\n        `${JSON.stringify(routeName.replace(/^\\/+/, \"\").replace(/\\//g, \".\") || \"index\")}.`,\n    );\n    this.name = \"RouteNameShapeCollisionError\";\n  }\n}\n\ntype Destination = {\n  /** What lands on the element's `href`. */\n  url: string;\n  /**\n   * Whether this URL is a page in THIS app — the only kind the client\n   * navigation runtime may be asked about, and the only kind that may be\n   * prefetched. `mailto:`, `tel:` and an external URL hand off to another\n   * application or another origin entirely, so intercepting any of them would\n   * break it, and speculatively fetching one would be a cross-origin request\n   * the developer never asked for.\n   */\n  isInApp: boolean;\n};\n\n/**\n * Any RFC 3986 scheme — `https:`, `mailto:`, `tel:`, `whatsapp:`, an app's own\n * custom one. Matched generically rather than as a list of known schemes: a\n * list would silently resolve `bitcoin:...` through the route table, which is\n * the exact failure this ruling exists to remove, and it would have to grow\n * forever.\n */\nconst SCHEME_PATTERN = /^[a-z][a-z0-9+.-]*:/i;\n\n/**\n * Whether this destination is a URL to be used as written, rather than a route\n * name to resolve.\n *\n * The whole discriminator, and deliberately the whole of it: two cheap shape\n * tests, no parsing, no matching. Anything more would be a SECOND route matcher\n * living beside the server's, which this codebase refuses everywhere it comes\n * up — a matcher that disagreed with the real one would produce links to pages\n * that do not exist.\n */\nfunction isLiteralUrl(destination: string): boolean {\n  return destination.startsWith(\"/\") || SCHEME_PATTERN.test(destination);\n}\n\n/**\n * Whether a literal URL addresses THIS app.\n *\n * A path is ours. A `scheme:` is not — including `https:` to our own origin,\n * which would need `window.location` to recognise and would make the answer\n * depend on where the code is running. And `//host/path` is PROTOCOL-RELATIVE:\n * it starts with a slash and is nonetheless another origin, which is precisely\n * the case a \"starts with `/`\" test alone would hand to the navigator, where it\n * becomes a `pushState` to a foreign origin — a SecurityError — or a\n * speculative fetch of a third-party host.\n */\nfunction addressesThisApp(url: string): boolean {\n  return url.startsWith(\"/\") && !url.startsWith(\"//\");\n}\n\n/**\n * Refuses the one table that would make {@link isLiteralUrl} wrong.\n *\n * Reached only for a destination already judged literal, so the cost is a scan\n * of the published names for links that were never going to hit the table\n * anyway — and zero for the route-name form, which is the common one. The right\n * permanent home for this is `publishRouteTable`, at boot, once (see the report\n * on this card).\n */\nfunction assertNotARouteName(url: string): void {\n  if (knownRouteNames().includes(url)) throw new RouteNameShapeCollisionError(url);\n}\n\nconst ROUTE_ARGUMENT_PROPS = [\"params\", \"query\"] as const;\n\nfunction resolveDestination(props: LinkDestinationProps): Destination {\n  const provided = DESTINATION_PROPS.filter(name => props[name] !== undefined);\n\n  if (provided.length > 1) throw new AmbiguousLinkDestinationError(provided);\n\n  if (provided.length === 0) throw new MissingLinkDestinationError();\n\n  if (props.email !== undefined) return { url: `mailto:${props.email}`, isInApp: false };\n\n  if (props.tel !== undefined) return { url: `tel:${props.tel}`, isInApp: false };\n\n  const destination = (props.to ?? props.href) as string;\n\n  /*\n    LITERAL: `/pricing`, `https://stripe.com`, `mailto:…`, `whatsapp://…`. It\n    goes to the element exactly as written and the route table is never\n    consulted — there is nothing to look up, and looking anyway is what used to\n    throw `UnknownRouteNameError` on every link out of the application.\n  */\n  if (isLiteralUrl(destination)) {\n    const routeArguments = ROUTE_ARGUMENT_PROPS.filter(name => props[name] !== undefined);\n\n    if (routeArguments.length > 0) {\n      throw new RouteArgumentsOnLiteralUrlError(destination, routeArguments);\n    }\n\n    assertNotARouteName(destination);\n\n    return { url: destination, isInApp: addressesThisApp(destination) };\n  }\n\n  /*\n    A NAME, resolved against the route table published at boot from the SAME\n    discovery result the server registered its routes from. The previous version\n    of this file restated six URLs in a literal map, so linking to any seventh\n    page in the application threw — the map was the limit on what could be\n    linked, and nothing said so at the call site.\n  */\n  return { url: href(destination, props.params, props.query), isInApp: true };\n}\n\n/**\n * Whether this click should be left entirely to the browser.\n *\n * Every case here is a click that MEANS something other than \"go there in this\n * tab\", and intercepting any of them would take away behaviour the user\n * explicitly asked for:\n *\n *   - a modifier or middle button: open in a new tab/window, or download\n *   - `download`: save the resource, do not render it\n *   - already prevented: something upstream in the tree handled this click\n *\n * Left button with no modifiers is the only click that means plain navigation.\n * The `target` case is decided before this, from the RESOLVED target, because\n * `newTab` sets it after the caller's props are read.\n */\nfunction isPlainLeftClick(event: MouseEvent<HTMLAnchorElement>): boolean {\n  return (\n    event.button === 0 &&\n    !event.metaKey &&\n    !event.ctrlKey &&\n    !event.shiftKey &&\n    !event.altKey &&\n    !event.defaultPrevented\n  );\n}\n\n/**\n * A target other than `_self` names ANOTHER browsing context — `_blank`, but\n * also `_parent`, `_top` and any named frame. Client navigation rewrites the\n * history of THIS one, so none of them are ours to intercept.\n */\nfunction opensAnotherContext(target: string | undefined): boolean {\n  return target !== undefined && target !== \"_self\";\n}\n\nexport function Link({\n  to,\n  href: hrefAlias,\n  email,\n  tel,\n  params,\n  query,\n  newTab,\n  prefetch,\n  component: Component = \"a\",\n  children,\n  onClick,\n  ...elementProps\n}: LinkProps): ReactElement {\n  const { url, isInApp } = resolveDestination({\n    to,\n    href: hrefAlias,\n    email,\n    tel,\n    params,\n    query,\n  });\n\n  const target = elementProps.target ?? (newTab === true ? \"_blank\" : undefined);\n\n  // Only a DEFAULT: a caller that wrote its own `rel` (`\"me noopener\"`,\n  // `\"external\"`) meant it, and overwriting it would delete a value the page\n  // depends on to say something this component knows nothing about.\n  const rel =\n    elementProps.rel ?? (target === \"_blank\" ? \"noopener noreferrer\" : undefined);\n\n  const handleClick = (event: MouseEvent<HTMLAnchorElement>): void => {\n    // The caller's handler runs FIRST and unconditionally — it may be doing\n    // analytics, closing a menu, or calling `preventDefault()` to veto the\n    // navigation outright. Deciding before it ran would let this component\n    // navigate away from a click the application had already cancelled.\n    onClick?.(event);\n\n    // `mailto:`, `tel:` and anything aimed at another browsing context leave\n    // this page standing. The runtime is not consulted at all — asking it would\n    // spend a page-data fetch on a click that was never going to navigate here.\n    if (!isInApp || opensAnotherContext(target)) return;\n\n    if (!isPlainLeftClick(event)) return;\n\n    /*\n      Asked for per click, never captured at render: the runtime registers\n      itself when the hydration bundle mounts, which is AFTER the first render\n      of every anchor on the page. A value read at render time would be\n      `undefined` forever for exactly the links present at hydration — that is,\n      all of them.\n\n      Absent (server render, or before hydration) the anchor is left alone and\n      does what an anchor does. That is the whole progressive-enhancement story:\n      links work before this code runs, and work better after.\n    */\n    if (currentNavigator()?.(url) !== true) return;\n\n    event.preventDefault();\n  };\n\n  /*\n    The SAME gate the click uses, asked before any speculative request exists:\n    only a destination this app would have navigated to itself may be fetched\n    ahead of time. `mailto:`, `tel:`, an external URL and anything aimed at\n    another browsing context are all clicks that leave this page, and none of\n    them has page data to fetch.\n  */\n  const prefetchesOnInteraction =\n    prefetch === true && isInApp && !opensAnotherContext(target);\n\n  /*\n    Attached ONLY when prefetching — a link without the prop keeps whatever\n    handlers the caller passed, on the element, unwrapped.\n\n    Hover AND focus, because a keyboard user never generates the first one and\n    would otherwise be the only visitor who never gets the optimisation.\n\n    Fire-and-forget by construction: `prefetchPageData` never rejects and is\n    never awaited, so nothing here can delay the event or surface a failure. It\n    is also safe to reach on the server — it no-ops without a browser — which is\n    why this file can import it directly rather than through a `connect*` seam\n    like the navigator's. The navigator needs a seam because the runtime behind\n    it drags React state and the page registry into the server bundle; the\n    prefetch cache is a `Map` and a `fetch` call, inert until an event fires.\n  */\n  const prefetchHandlers = prefetchesOnInteraction\n    ? {\n        onMouseEnter: (event: MouseEvent<HTMLAnchorElement>): void => {\n          elementProps.onMouseEnter?.(event);\n          void prefetchPageData(url);\n        },\n        onFocus: (event: FocusEvent<HTMLAnchorElement>): void => {\n          elementProps.onFocus?.(event);\n          void prefetchPageData(url);\n        },\n      }\n    : undefined;\n\n  return createElement(\n    Component,\n    { ...elementProps, ...prefetchHandlers, target, rel, href: url, onClick: handleClick },\n    children,\n  );\n}\n"],"mappings":"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"}

package/esm/components/scripts.d.mts

@@ -1,6 +1,6 @@
 import { ReactElement } from "react";
 
-//#region ../web/src/components/scripts.d.ts
+//#region web/src/components/scripts.d.ts
 type ScriptsProps = {
   /** Per-request CSP nonce for the inline payload script (root.tsx:119). */nonce?: string;
 };

package/esm/components/scripts.mjs

@@ -1,13 +1,15 @@
 import { PAYLOAD_SCRIPT_ID, escapePayload, useDocumentContext } from "./document-context.mjs";
-import { createElement } from "react";
+import { isNonHydrating } from "../server/page-render-bundle.mjs";
+import { Fragment, createElement } from "react";
 
-//#region ../web/src/components/scripts.ts
+//#region web/src/components/scripts.ts
 /**
 * OPTIONAL placement override for the serialized loader data and `shared`.
 * Hydration module emission is separate wiring.
 */
 function Scripts(props) {
 	const { payload, nonce } = useDocumentContext("Scripts");
+	if (isNonHydrating(payload)) return createElement(Fragment, null);
 	return createElement("script", {
 		id: PAYLOAD_SCRIPT_ID,
 		type: "application/json",

package/esm/components/scripts.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"scripts.mjs","names":[],"sources":["../../../../../../../web/src/components/scripts.ts"],"sourcesContent":["import { createElement, type ReactElement } from \"react\";\nimport { escapePayload, PAYLOAD_SCRIPT_ID, useDocumentContext } from \"./document-context\";\n\nexport type ScriptsProps = {\n  /** Per-request CSP nonce for the inline payload script (root.tsx:119). */\n  nonce?: string;\n};\n\n/**\n * OPTIONAL placement override for the serialized loader data and `shared`.\n * Hydration module emission is separate wiring.\n */\nexport function Scripts(props: ScriptsProps): ReactElement {\n  const { payload, nonce } = useDocumentContext(\"Scripts\");\n\n  // Explicit prop wins: v5/app's root.tsx passes `shared.nonce` today\n  // (root.tsx:119) and must keep working unchanged. Only an absent prop falls\n  // back to the framework's nonce slot (document-context.ts).\n  const resolvedNonce = props.nonce ?? nonce;\n\n  // `dangerouslySetInnerHTML`, not children: the serializer's escaped output must\n  // reach the document byte-for-byte. React's default child-text escaping\n  // (HTML-entity escaping) would double-process it and corrupt the JSON\n  // (spike P7's escaping contract).\n  return createElement(\"script\", {\n    id: PAYLOAD_SCRIPT_ID,\n    type: \"application/json\",\n    nonce: resolvedNonce,\n    dangerouslySetInnerHTML: { __html: escapePayload(JSON.stringify(payload)) },\n  });\n}\n"],"mappings":";;;;;;;;AAYA,SAAgB,QAAQ,OAAmC;CACzD,MAAM,EAAE,SAAS,UAAU,mBAAmB,SAAS;CAWvD,OAAO,cAAc,UAAU;EAC7B,IAAI;EACJ,MAAM;EACN,OAToB,MAAM,SAAS;EAUnC,yBAAyB,EAAE,QAAQ,cAAc,KAAK,UAAU,OAAO,CAAC,EAAE;CAC5E,CAAC;AACH"}
+{"version":3,"file":"scripts.mjs","names":[],"sources":["C:/Work/Warlock.js/web/src/components/scripts.ts"],"sourcesContent":["import { createElement, Fragment, type ReactElement } from \"react\";\nimport { escapePayload, PAYLOAD_SCRIPT_ID, useDocumentContext } from \"./document-context\";\nimport { isNonHydrating } from \"../server/page-render-bundle\";\n\nexport type ScriptsProps = {\n  /** Per-request CSP nonce for the inline payload script (root.tsx:119). */\n  nonce?: string;\n};\n\n/**\n * OPTIONAL placement override for the serialized loader data and `shared`.\n * Hydration module emission is separate wiring.\n */\nexport function Scripts(props: ScriptsProps): ReactElement {\n  const { payload, nonce } = useDocumentContext(\"Scripts\");\n\n  // `renderPageFailure` marks its payload non-hydrating (page-render-bundle.ts):\n  // a module-load/registration throw happens before any triple exists, so\n  // there is nothing trustworthy for a hydration script to describe. A normal\n  // app `error.page.tsx` payload (from `finishRender`) is never marked and\n  // keeps emitting `__WARLOCK_DATA__` below.\n  if (isNonHydrating(payload)) return createElement(Fragment, null);\n\n  // Explicit prop wins: v5/app's root.tsx passes `shared.nonce` today\n  // (root.tsx:119) and must keep working unchanged. Only an absent prop falls\n  // back to the framework's nonce slot (document-context.ts).\n  const resolvedNonce = props.nonce ?? nonce;\n\n  // `dangerouslySetInnerHTML`, not children: the serializer's escaped output must\n  // reach the document byte-for-byte. React's default child-text escaping\n  // (HTML-entity escaping) would double-process it and corrupt the JSON\n  // (spike P7's escaping contract).\n  return createElement(\"script\", {\n    id: PAYLOAD_SCRIPT_ID,\n    type: \"application/json\",\n    nonce: resolvedNonce,\n    dangerouslySetInnerHTML: { __html: escapePayload(JSON.stringify(payload)) },\n  });\n}\n"],"mappings":";;;;;;;;;AAaA,SAAgB,QAAQ,OAAmC;CACzD,MAAM,EAAE,SAAS,UAAU,mBAAmB,SAAS;CAOvD,IAAI,eAAe,OAAO,GAAG,OAAO,cAAc,UAAU,IAAI;CAWhE,OAAO,cAAc,UAAU;EAC7B,IAAI;EACJ,MAAM;EACN,OAToB,MAAM,SAAS;EAUnC,yBAAyB,EAAE,QAAQ,cAAc,KAAK,UAAU,OAAO,CAAC,EAAE;CAC5E,CAAC;AACH"}

package/esm/context.d.mts

@@ -1,107 +1,11 @@
 import { SharedContext } from "./index.mjs";
+import { HttpContext, Request } from "@warlock.js/core";
 
-//#region ../web/src/context.d.ts
-/**
- * The brand behind loader short-circuits.
- *
- * Core's `Response#notFound()` / `#redirect()` return an unbranded
- * `Response`/`this` (core/src/http/response.ts:862-866, 1028-1034). The page
- * contract needs those returns to NOT union into `PageProps["data"]`
- * (v5/app/src/app/products/web/product-details.page.tsx:45-57), so web brands
- * them on ITS OWN response surface — the one a loader's context carries —
- * without touching core. `LoaderData` excludes exactly this brand.
- */
-declare const loaderShortCircuit: unique symbol;
-interface LoaderShortCircuit {
-  readonly [loaderShortCircuit]: true;
-}
-/**
- * The request as a loader sees it. Structural and deliberately minimal for M1:
- * exactly the members the v5/app loaders exercise, typed by the page's own
- * `validation` and `route` generics.
- *
- * TODO(Stream A.6 — core ctx migration): once core ships
- * `HttpContext { request, response }` and the declared `request.user` /
- * `request.locals` / `request.nonce`, this narrows to a refinement of core's `Request`
- * instead of a standalone structural type.
- */
-interface WebRequest<TValidated = Record<string, never>, TParams extends string = string> {
-  /**
-   * The validated inputs, typed off the page's `validation.schema` with
-   * `Infer.Output` semantics — `.default()` fields stay required
-   * (v5/app/src/app/auth/schema/login.schema.ts:29-38). The key-list parameter
-   * is optional and selects a subset, mirroring core
-   * (core/src/http/request.ts:610).
-   */
-  validated(inputs?: readonly (keyof TValidated | (string & {}))[]): TValidated;
-  /**
-   * Typed FROM THE ROUTE: `TParams` is derived from the route path literal, so
-   * `request.input("id")` types against `path: "/:id"` and a key that is not a
-   * route parameter is a compile error
-   * (v5/app/src/web/__type-tests__/route-params.type-test.ts).
-   */
-  input(key: TParams, defaultValue?: unknown): string;
-  /**
-   * The authenticated user, when middleware resolved one.
-   *
-   * `any`, deliberately, and recorded as a deviation in the M1 report: the
-   * reference app hands `request.user` to services typed against the APP's own
-   * model (`navService.forUser(user: User)`,
-   * v5/app/src/web/layouts/dashboard.layout.tsx:35) and reads `.id` with no
-   * null-check (settings.page.tsx:65). No type this package can declare is
-   * assignable to an app-owned model class; the real declaration has to come
-   * from core's own `Request.user` and lands with Stream A.6.
-   *
-   * Optional, matching core (`Request.user?`, core/src/http/request.ts:94) —
-   * a required member here would reject core's real `Request` at the seam.
-   * `any` absorbs the `undefined`, so loader-side `request.user.id` reads
-   * keep compiling (the recorded M1 deviation stands).
-   */
-  user?: any;
-}
-/**
- * The response as a loader sees it. A loader may mutate the response during
- * render (headers, status) and may SHORT-CIRCUIT it — the short-circuiting
- * methods return the branded type that never reaches `PageProps["data"]`.
- *
- * TODO(Stream A.6): same story as `WebRequest` — becomes a refinement of
- * core's `Response` once the ctx object lands in core.
- */
-interface WebResponse {
-  /** Buffered, committed in tree order after every loader settles. */
-  header(key: string, value: string): WebResponse;
-  /** The not-found page's loader's real output is the status (not-found.page.tsx:25). */
-  setStatusCode(statusCode: number): WebResponse;
-  /** A short-circuit, not a value — never unions into `data`. */
-  redirect(url: string, statusCode?: number): LoaderShortCircuit;
-  /** 301 flavour of the same short-circuit. */
-  permanentRedirect(url: string): LoaderShortCircuit;
-  /** A 404 is an ANSWER, not an incident (product-details.page.tsx:45-57). */
-  notFound(body?: unknown): LoaderShortCircuit;
-}
-/**
- * The one context object every handler receives.
- *
- * TODO(Stream A.6): core is to OWN `HttpContext { request, response }` and the
- * re-parameterised `Middleware<TContext extends HttpContext>`. Core today has
- * no `HttpContext` and its `Middleware` is positional `(request, response)`
- * (core/src/router/types.ts:17), so importing the type from
- * `@warlock.js/core` cannot resolve to the v5 shape yet — this structural
- * declaration stands in until core declares it.
- */
-interface HttpContext {
-  request: WebRequest;
-  response: WebResponse;
-}
-/**
- * The web layer's context: `HttpContext` plus the per-request payload. The
- * keys are framework-owned and the list is closed — `request`, `response`,
- * `shared`. App data goes on `request.locals` (private) or `shared` (public),
- * never onto the context itself.
- */
-interface PageContext extends HttpContext {
+//#region web/src/context.d.ts
+type HttpContext$1<TRequest extends Request = Request> = HttpContext<TRequest>;
+type PageContext<TRequest extends Request = Request> = HttpContext<TRequest> & {
   shared: SharedContext;
-}
+};
 //#endregion
-export { LoaderShortCircuit, PageContext, WebRequest, WebResponse };
+export { HttpContext$1 as HttpContext, PageContext };
 //# sourceMappingURL=context.d.mts.map

package/esm/hydration/index.mjs

@@ -5,7 +5,7 @@ import { NavigationRoot } from "../client/navigation/navigation-root.mjs";
 import { createElement } from "react";
 import { pages } from "virtual:warlock/pages";
 
-//#region ../web/src/hydration/index.ts
+//#region web/src/hydration/index.ts
 /**
 * The client entry: registry in, hydration out. No page names, no app paths.
 *

package/esm/hydration/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../../../../../../../web/src/hydration/index.ts"],"sourcesContent":["/**\n * The client entry: registry in, hydration out. No page names, no app paths.\n *\n * The page graph arrives from the Vite virtual module the build plugin serves,\n * so this file works for ANY page in ANY app. The previous version imported one\n * page and one layout by relative path into the monorepo's reference app, which\n * both hydrated every URL as the home page and made `@warlock.js/web`\n * uninstallable anywhere outside this checkout. Neither a page name nor an app\n * path appears here now, and nothing about the composition lives here either -\n * that is `buildHydratedTree`, which takes the registry as an argument and is\n * therefore testable without a bundler.\n */\nimport { createElement } from \"react\";\nimport { pages } from \"virtual:warlock/pages\";\nimport { buildHydratedTree } from \"../client/build-hydrated-tree\";\nimport { hydratePage } from \"../client/hydrate-page\";\nimport { NavigationRoot } from \"../client/navigation/navigation-root\";\nimport { publishRouteTable } from \"../routing/route-table\";\n\n/*\n  BEFORE the mount, not after: `<Link>` resolves its URL through the route table\n  during render, and the first render is the hydration render. Publishing\n  afterwards would make every anchor in the initial tree throw.\n\n  The registry entries already carry `name` and `path` - the same pair the\n  server registered its routes from, out of the same discovery result - so the\n  browser's table cannot drift from the server's without the two being built\n  from different page graphs, which hydration already refuses.\n*/\npublishRouteTable(pages, \"hydration client entry\");\n\n/*\n  The hydrated tree is wrapped in `NavigationRoot` so the page can be REPLACED\n  later without a document load. The first render is still exactly the tree the\n  server produced - `NavigationRoot` renders `initialTree` verbatim and adds no\n  markup of its own - so hydration still matches the server byte for byte, and\n  the wrapper only starts to matter on the first navigation.\n\n  NO MRR HISTORY BRIDGE IS INSTALLED HERE YET, and that is a pending decision\n  rather than an oversight. This runtime drives `window.history` itself and is\n  complete without MRR. Handing history to `@mongez/react-router` as well means\n  `@warlock.js/web` importing it, which puts MRR in the bundle of EVERY app that\n  uses this package - a packaging choice (dependency vs. peer vs. app-level\n  opt-in) with consequences for apps that never navigate through MRR. The bridge\n  itself is written and documented in\n  `conversations/2026-08-24-production-ssr-session.md`; it lands the moment that\n  choice is made.\n*/\nhydratePage(async (payload) => {\n  const tree = await buildHydratedTree(pages, payload);\n\n  return createElement(NavigationRoot, {\n    pages,\n    initialPayload: payload,\n    initialTree: tree,\n    buildTree: buildHydratedTree,\n  });\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AA6BA,kBAAkB,OAAO,wBAAwB;AAmBjD,YAAY,OAAO,YAAY;CAG7B,OAAO,cAAc,gBAAgB;EACnC;EACA,gBAAgB;EAChB,aAAa,MALI,kBAAkB,OAAO,OAAO;EAMjD,WAAW;CACb,CAAC;AACH,CAAC"}
+{"version":3,"file":"index.mjs","names":[],"sources":["C:/Work/Warlock.js/web/src/hydration/index.ts"],"sourcesContent":["/**\n * The client entry: registry in, hydration out. No page names, no app paths.\n *\n * The page graph arrives from the Vite virtual module the build plugin serves,\n * so this file works for ANY page in ANY app. The previous version imported one\n * page and one layout by relative path into the monorepo's reference app, which\n * both hydrated every URL as the home page and made `@warlock.js/web`\n * uninstallable anywhere outside this checkout. Neither a page name nor an app\n * path appears here now, and nothing about the composition lives here either -\n * that is `buildHydratedTree`, which takes the registry as an argument and is\n * therefore testable without a bundler.\n */\nimport { createElement } from \"react\";\nimport { pages } from \"virtual:warlock/pages\";\nimport { buildHydratedTree } from \"../client/build-hydrated-tree\";\nimport { hydratePage } from \"../client/hydrate-page\";\nimport { NavigationRoot } from \"../client/navigation/navigation-root\";\nimport { publishRouteTable } from \"../routing/route-table\";\n\n/*\n  BEFORE the mount, not after: `<Link>` resolves its URL through the route table\n  during render, and the first render is the hydration render. Publishing\n  afterwards would make every anchor in the initial tree throw.\n\n  The registry entries already carry `name` and `path` - the same pair the\n  server registered its routes from, out of the same discovery result - so the\n  browser's table cannot drift from the server's without the two being built\n  from different page graphs, which hydration already refuses.\n*/\npublishRouteTable(pages, \"hydration client entry\");\n\n/*\n  The hydrated tree is wrapped in `NavigationRoot` so the page can be REPLACED\n  later without a document load. The first render is still exactly the tree the\n  server produced - `NavigationRoot` renders `initialTree` verbatim and adds no\n  markup of its own - so hydration still matches the server byte for byte, and\n  the wrapper only starts to matter on the first navigation.\n\n  NO MRR HISTORY BRIDGE IS INSTALLED HERE YET, and that is a pending decision\n  rather than an oversight. This runtime drives `window.history` itself and is\n  complete without MRR. Handing history to `@mongez/react-router` as well means\n  `@warlock.js/web` importing it, which puts MRR in the bundle of EVERY app that\n  uses this package - a packaging choice (dependency vs. peer vs. app-level\n  opt-in) with consequences for apps that never navigate through MRR. The bridge\n  itself is written and documented in\n  `conversations/2026-08-24-production-ssr-session.md`; it lands the moment that\n  choice is made.\n*/\nhydratePage(async (payload) => {\n  const tree = await buildHydratedTree(pages, payload);\n\n  return createElement(NavigationRoot, {\n    pages,\n    initialPayload: payload,\n    initialTree: tree,\n    buildTree: buildHydratedTree,\n  });\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AA6BA,kBAAkB,OAAO,wBAAwB;AAmBjD,YAAY,OAAO,YAAY;CAG7B,OAAO,cAAc,gBAAgB;EACnC;EACA,gBAAgB;EAChB,aAAa,MALI,kBAAkB,OAAO,OAAO;EAMjD,WAAW;CACb,CAAC;AACH,CAAC"}

package/esm/hydration-payload.d.mts

@@ -1 +1 @@
-export { };
+import { ErrorPageProps, SerializedErrorPageProps, SerializedPageError } from "./components/document-context.mjs";

package/esm/hydration-payload.mjs

@@ -1,6 +1,6 @@
 import { PAYLOAD_SCRIPT_ID } from "./components/document-context.mjs";
 
-//#region ../web/src/hydration-payload.ts
+//#region web/src/hydration-payload.ts
 /**
 * Exported so a payload-shape assertion can be written against the contract
 * itself. A spec that hardcodes its own copy of this list silently becomes a
@@ -22,11 +22,11 @@ function malformedPayload() {
 /**
 * The keys that are allowed to be ABSENT but not allowed to be wrong.
 *
-* `metadata` and `params` are optional because the server is right not to
+* `metadata`, `params` and `errorPage` are optional because the server is right
 * always produce them — a page with no `metadata` export resolves none, and a
-* payload written by a build that predates these keys carries neither. Failing
-* a whole page over an absent accessor would turn a cosmetic gap into a blank
-* screen, so absence is accepted and the readers default it.
+* older payload carries none of these additions. Failing a whole page over an
+* absent accessor would turn a compatible payload into a blank screen, so
+* absence is accepted.
 *
 * Present-but-not-an-object is a different claim entirely: it means something
 * produced a payload with these names meaning something else, and every reader
@@ -34,10 +34,36 @@ function malformedPayload() {
 * rule the required keys live by, so it throws. Arrays included — `typeof []`
 * is `"object"`, and an array of params is not params.
 */
-const OPTIONAL_OBJECT_PAYLOAD_KEYS = ["metadata", "params"];
+const OPTIONAL_OBJECT_PAYLOAD_KEYS = [
+	"metadata",
+	"params",
+	"errorPage"
+];
 function isPlainObject(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function hasExactStringKeys(value, required, optional = []) {
+	const allowed = new Set([...required, ...optional]);
+	const keys = Reflect.ownKeys(value);
+	return required.every((key) => Object.prototype.hasOwnProperty.call(value, key)) && keys.every((key) => typeof key === "string" && allowed.has(key));
+}
+/**
+* Validate the explicit serialization boundary, not an `Error` instance.
+* `JSON.stringify(new Error("boom"))` is normally `{}` because its useful
+* fields are non-enumerable; accepting that would hydrate an error page with a
+* different contract from the one the server rendered.
+*/
+function requireErrorPagePayload(value) {
+	if (!isPlainObject(value)) malformedPayload();
+	const errorPage = value;
+	if (!hasExactStringKeys(errorPage, ["error", "status"])) malformedPayload();
+	if (!isPlainObject(errorPage.error)) malformedPayload();
+	const error = errorPage.error;
+	if (!hasExactStringKeys(error, ["name", "message"], ["stack"])) malformedPayload();
+	if (typeof error.name !== "string" || typeof error.message !== "string") malformedPayload();
+	if (error.stack !== void 0 && typeof error.stack !== "string") malformedPayload();
+	if (typeof errorPage.status !== "number" || !Number.isInteger(errorPage.status) || errorPage.status < 500 || errorPage.status > 599) malformedPayload();
+}
 function requireHydrationPayload(value) {
 	if (!isPlainObject(value)) malformedPayload();
 	for (const key of REQUIRED_PAYLOAD_KEYS) if (!Object.prototype.hasOwnProperty.call(value, key)) malformedPayload();
@@ -45,15 +71,18 @@ function requireHydrationPayload(value) {
 		const optional = value[key];
 		if (optional !== void 0 && !isPlainObject(optional)) malformedPayload();
 	}
+	const errorPage = value.errorPage;
+	if (errorPage !== void 0) requireErrorPagePayload(errorPage);
 	return value;
 }
 /**
 * Read the fixed payload script without changing the server-rendered root.
 *
 * Extra fields are ignored. The gate owns the FIVE required keys — absent or
-* malformed, both throw — plus a shape check on the two optional ones
+* malformed, both throw — plus a shape check on the three optional ones
 * ({@link OPTIONAL_OBJECT_PAYLOAD_KEYS}); it deliberately does not require
-* those to be present.
+* those to be present. `errorPage`, when present, is additionally validated as
+* one atomic `{ error, status }` selection with a serialized error and a 5xx.
 */
 function readHydrationPayload(documentNode) {
 	const element = documentNode.getElementById(PAYLOAD_SCRIPT_ID);

package/esm/hydration-payload.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"hydration-payload.mjs","names":[],"sources":["../../../../../../web/src/hydration-payload.ts"],"sourcesContent":["import {\n  PAYLOAD_SCRIPT_ID,\n  type HydrationDocumentPayloadSource,\n} from \"./components/document-context\";\n\nexport type { HydrationDocumentPayloadSource } from \"./components/document-context\";\n\n/**\n * Exported so a payload-shape assertion can be written against the contract\n * itself. A spec that hardcodes its own copy of this list silently becomes a\n * claim about a PAST revision — that is exactly how the rev. 3 keys landed with\n * two specs still asserting the rev. 2 shape.\n */\nexport const REQUIRED_PAYLOAD_KEYS = [\n  \"appData\",\n  \"layoutData\",\n  \"pageData\",\n  \"shared\",\n  \"name\",\n] as const;\n\nconst ABSENT_PAYLOAD_MESSAGE =\n  `Warlock hydration payload is absent: #${PAYLOAD_SCRIPT_ID}, owned by ` +\n  \"web/src/components/document-context.ts, was not found.\";\nconst MALFORMED_PAYLOAD_MESSAGE =\n  `Warlock hydration payload was found at #${PAYLOAD_SCRIPT_ID} but could not be read.`;\n\nfunction malformedPayload(): never {\n  throw new Error(MALFORMED_PAYLOAD_MESSAGE);\n}\n\n/**\n * The keys that are allowed to be ABSENT but not allowed to be wrong.\n *\n * `metadata` and `params` are optional because the server is right not to\n * always produce them — a page with no `metadata` export resolves none, and a\n * payload written by a build that predates these keys carries neither. Failing\n * a whole page over an absent accessor would turn a cosmetic gap into a blank\n * screen, so absence is accepted and the readers default it.\n *\n * Present-but-not-an-object is a different claim entirely: it means something\n * produced a payload with these names meaning something else, and every reader\n * downstream would then be indexing a string. That is MALFORMED under the same\n * rule the required keys live by, so it throws. Arrays included — `typeof []`\n * is `\"object\"`, and an array of params is not params.\n */\nexport const OPTIONAL_OBJECT_PAYLOAD_KEYS = [\"metadata\", \"params\"] as const;\n\nfunction isPlainObject(value: unknown): boolean {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction requireHydrationPayload(value: unknown): HydrationDocumentPayloadSource {\n  if (!isPlainObject(value)) malformedPayload();\n\n  for (const key of REQUIRED_PAYLOAD_KEYS) {\n    if (!Object.prototype.hasOwnProperty.call(value, key)) malformedPayload();\n  }\n\n  for (const key of OPTIONAL_OBJECT_PAYLOAD_KEYS) {\n    const optional = (value as Record<string, unknown>)[key];\n\n    if (optional !== undefined && !isPlainObject(optional)) malformedPayload();\n  }\n\n  return value as HydrationDocumentPayloadSource;\n}\n\n/**\n * Read the fixed payload script without changing the server-rendered root.\n *\n * Extra fields are ignored. The gate owns the FIVE required keys — absent or\n * malformed, both throw — plus a shape check on the two optional ones\n * ({@link OPTIONAL_OBJECT_PAYLOAD_KEYS}); it deliberately does not require\n * those to be present.\n */\nexport function readHydrationPayload(documentNode: Document): HydrationDocumentPayloadSource {\n  const element = documentNode.getElementById(PAYLOAD_SCRIPT_ID);\n\n  if (element === null) throw new Error(ABSENT_PAYLOAD_MESSAGE);\n\n  let parsed: unknown;\n\n  try {\n    parsed = JSON.parse(element.textContent ?? \"\");\n  } catch {\n    malformedPayload();\n  }\n\n  return requireHydrationPayload(parsed);\n}\n"],"mappings":";;;;;;;;;AAaA,MAAa,wBAAwB;CACnC;CACA;CACA;CACA;CACA;AACF;AAEA,MAAM,yBACJ,yCAAyC,kBAAkB;AAE7D,MAAM,4BACJ,2CAA2C,kBAAkB;AAE/D,SAAS,mBAA0B;CACjC,MAAM,IAAI,MAAM,yBAAyB;AAC3C;;;;;;;;;;;;;;;;AAiBA,MAAa,+BAA+B,CAAC,YAAY,QAAQ;AAEjE,SAAS,cAAc,OAAyB;CAC9C,OAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAC5E;AAEA,SAAS,wBAAwB,OAAgD;CAC/E,IAAI,CAAC,cAAc,KAAK,GAAG,iBAAiB;CAE5C,KAAK,MAAM,OAAO,uBAChB,IAAI,CAAC,OAAO,UAAU,eAAe,KAAK,OAAO,GAAG,GAAG,iBAAiB;CAG1E,KAAK,MAAM,OAAO,8BAA8B;EAC9C,MAAM,WAAY,MAAkC;EAEpD,IAAI,aAAa,UAAa,CAAC,cAAc,QAAQ,GAAG,iBAAiB;CAC3E;CAEA,OAAO;AACT;;;;;;;;;AAUA,SAAgB,qBAAqB,cAAwD;CAC3F,MAAM,UAAU,aAAa,eAAe,iBAAiB;CAE7D,IAAI,YAAY,MAAM,MAAM,IAAI,MAAM,sBAAsB;CAE5D,IAAI;CAEJ,IAAI;EACF,SAAS,KAAK,MAAM,QAAQ,eAAe,EAAE;CAC/C,QAAQ;EACN,iBAAiB;CACnB;CAEA,OAAO,wBAAwB,MAAM;AACvC"}
+{"version":3,"file":"hydration-payload.mjs","names":[],"sources":["C:/Work/Warlock.js/web/src/hydration-payload.ts"],"sourcesContent":["import {\n  PAYLOAD_SCRIPT_ID,\n  type HydrationDocumentPayloadSource,\n} from \"./components/document-context\";\n\nexport type { HydrationDocumentPayloadSource } from \"./components/document-context\";\nexport type {\n  ErrorPageProps,\n  SerializedErrorPageProps,\n  SerializedPageError,\n} from \"./components/document-context\";\n\n/**\n * Exported so a payload-shape assertion can be written against the contract\n * itself. A spec that hardcodes its own copy of this list silently becomes a\n * claim about a PAST revision — that is exactly how the rev. 3 keys landed with\n * two specs still asserting the rev. 2 shape.\n */\nexport const REQUIRED_PAYLOAD_KEYS = [\n  \"appData\",\n  \"layoutData\",\n  \"pageData\",\n  \"shared\",\n  \"name\",\n] as const;\n\nconst ABSENT_PAYLOAD_MESSAGE =\n  `Warlock hydration payload is absent: #${PAYLOAD_SCRIPT_ID}, owned by ` +\n  \"web/src/components/document-context.ts, was not found.\";\nconst MALFORMED_PAYLOAD_MESSAGE =\n  `Warlock hydration payload was found at #${PAYLOAD_SCRIPT_ID} but could not be read.`;\n\nfunction malformedPayload(): never {\n  throw new Error(MALFORMED_PAYLOAD_MESSAGE);\n}\n\n/**\n * The keys that are allowed to be ABSENT but not allowed to be wrong.\n *\n * `metadata`, `params` and `errorPage` are optional because the server is right\n * always produce them — a page with no `metadata` export resolves none, and a\n * older payload carries none of these additions. Failing a whole page over an\n * absent accessor would turn a compatible payload into a blank screen, so\n * absence is accepted.\n *\n * Present-but-not-an-object is a different claim entirely: it means something\n * produced a payload with these names meaning something else, and every reader\n * downstream would then be indexing a string. That is MALFORMED under the same\n * rule the required keys live by, so it throws. Arrays included — `typeof []`\n * is `\"object\"`, and an array of params is not params.\n */\nexport const OPTIONAL_OBJECT_PAYLOAD_KEYS = [\"metadata\", \"params\", \"errorPage\"] as const;\n\nfunction isPlainObject(value: unknown): boolean {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction hasExactStringKeys(\n  value: Record<PropertyKey, unknown>,\n  required: readonly string[],\n  optional: readonly string[] = [],\n): boolean {\n  const allowed = new Set([...required, ...optional]);\n  const keys = Reflect.ownKeys(value);\n\n  return (\n    required.every((key) => Object.prototype.hasOwnProperty.call(value, key)) &&\n    keys.every((key) => typeof key === \"string\" && allowed.has(key))\n  );\n}\n\n/**\n * Validate the explicit serialization boundary, not an `Error` instance.\n * `JSON.stringify(new Error(\"boom\"))` is normally `{}` because its useful\n * fields are non-enumerable; accepting that would hydrate an error page with a\n * different contract from the one the server rendered.\n */\nfunction requireErrorPagePayload(value: unknown): void {\n  if (!isPlainObject(value)) malformedPayload();\n\n  const errorPage = value as Record<PropertyKey, unknown>;\n\n  if (!hasExactStringKeys(errorPage, [\"error\", \"status\"])) malformedPayload();\n  if (!isPlainObject(errorPage.error)) malformedPayload();\n\n  const error = errorPage.error as Record<PropertyKey, unknown>;\n\n  if (!hasExactStringKeys(error, [\"name\", \"message\"], [\"stack\"])) malformedPayload();\n  if (typeof error.name !== \"string\" || typeof error.message !== \"string\") {\n    malformedPayload();\n  }\n  if (error.stack !== undefined && typeof error.stack !== \"string\") malformedPayload();\n\n  if (\n    typeof errorPage.status !== \"number\" ||\n    !Number.isInteger(errorPage.status) ||\n    errorPage.status < 500 ||\n    errorPage.status > 599\n  ) {\n    malformedPayload();\n  }\n}\n\nfunction requireHydrationPayload(value: unknown): HydrationDocumentPayloadSource {\n  if (!isPlainObject(value)) malformedPayload();\n\n  for (const key of REQUIRED_PAYLOAD_KEYS) {\n    if (!Object.prototype.hasOwnProperty.call(value, key)) malformedPayload();\n  }\n\n  for (const key of OPTIONAL_OBJECT_PAYLOAD_KEYS) {\n    const optional = (value as Record<string, unknown>)[key];\n\n    if (optional !== undefined && !isPlainObject(optional)) malformedPayload();\n  }\n\n  const errorPage = (value as Record<string, unknown>).errorPage;\n  if (errorPage !== undefined) requireErrorPagePayload(errorPage);\n\n  return value as HydrationDocumentPayloadSource;\n}\n\n/**\n * Read the fixed payload script without changing the server-rendered root.\n *\n * Extra fields are ignored. The gate owns the FIVE required keys — absent or\n * malformed, both throw — plus a shape check on the three optional ones\n * ({@link OPTIONAL_OBJECT_PAYLOAD_KEYS}); it deliberately does not require\n * those to be present. `errorPage`, when present, is additionally validated as\n * one atomic `{ error, status }` selection with a serialized error and a 5xx.\n */\nexport function readHydrationPayload(documentNode: Document): HydrationDocumentPayloadSource {\n  const element = documentNode.getElementById(PAYLOAD_SCRIPT_ID);\n\n  if (element === null) throw new Error(ABSENT_PAYLOAD_MESSAGE);\n\n  let parsed: unknown;\n\n  try {\n    parsed = JSON.parse(element.textContent ?? \"\");\n  } catch {\n    malformedPayload();\n  }\n\n  return requireHydrationPayload(parsed);\n}\n"],"mappings":";;;;;;;;;AAkBA,MAAa,wBAAwB;CACnC;CACA;CACA;CACA;CACA;AACF;AAEA,MAAM,yBACJ,yCAAyC,kBAAkB;AAE7D,MAAM,4BACJ,2CAA2C,kBAAkB;AAE/D,SAAS,mBAA0B;CACjC,MAAM,IAAI,MAAM,yBAAyB;AAC3C;;;;;;;;;;;;;;;;AAiBA,MAAa,+BAA+B;CAAC;CAAY;CAAU;AAAW;AAE9E,SAAS,cAAc,OAAyB;CAC9C,OAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAC5E;AAEA,SAAS,mBACP,OACA,UACA,WAA8B,CAAC,GACtB;CACT,MAAM,UAAU,IAAI,IAAI,CAAC,GAAG,UAAU,GAAG,QAAQ,CAAC;CAClD,MAAM,OAAO,QAAQ,QAAQ,KAAK;CAElC,OACE,SAAS,OAAO,QAAQ,OAAO,UAAU,eAAe,KAAK,OAAO,GAAG,CAAC,KACxE,KAAK,OAAO,QAAQ,OAAO,QAAQ,YAAY,QAAQ,IAAI,GAAG,CAAC;AAEnE;;;;;;;AAQA,SAAS,wBAAwB,OAAsB;CACrD,IAAI,CAAC,cAAc,KAAK,GAAG,iBAAiB;CAE5C,MAAM,YAAY;CAElB,IAAI,CAAC,mBAAmB,WAAW,CAAC,SAAS,QAAQ,CAAC,GAAG,iBAAiB;CAC1E,IAAI,CAAC,cAAc,UAAU,KAAK,GAAG,iBAAiB;CAEtD,MAAM,QAAQ,UAAU;CAExB,IAAI,CAAC,mBAAmB,OAAO,CAAC,QAAQ,SAAS,GAAG,CAAC,OAAO,CAAC,GAAG,iBAAiB;CACjF,IAAI,OAAO,MAAM,SAAS,YAAY,OAAO,MAAM,YAAY,UAC7D,iBAAiB;CAEnB,IAAI,MAAM,UAAU,UAAa,OAAO,MAAM,UAAU,UAAU,iBAAiB;CAEnF,IACE,OAAO,UAAU,WAAW,YAC5B,CAAC,OAAO,UAAU,UAAU,MAAM,KAClC,UAAU,SAAS,OACnB,UAAU,SAAS,KAEnB,iBAAiB;AAErB;AAEA,SAAS,wBAAwB,OAAgD;CAC/E,IAAI,CAAC,cAAc,KAAK,GAAG,iBAAiB;CAE5C,KAAK,MAAM,OAAO,uBAChB,IAAI,CAAC,OAAO,UAAU,eAAe,KAAK,OAAO,GAAG,GAAG,iBAAiB;CAG1E,KAAK,MAAM,OAAO,8BAA8B;EAC9C,MAAM,WAAY,MAAkC;EAEpD,IAAI,aAAa,UAAa,CAAC,cAAc,QAAQ,GAAG,iBAAiB;CAC3E;CAEA,MAAM,YAAa,MAAkC;CACrD,IAAI,cAAc,QAAW,wBAAwB,SAAS;CAE9D,OAAO;AACT;;;;;;;;;;AAWA,SAAgB,qBAAqB,cAAwD;CAC3F,MAAM,UAAU,aAAa,eAAe,iBAAiB;CAE7D,IAAI,YAAY,MAAM,MAAM,IAAI,MAAM,sBAAsB;CAE5D,IAAI;CAEJ,IAAI;EACF,SAAS,KAAK,MAAM,QAAQ,eAAe,EAAE;CAC/C,QAAQ;EACN,iBAAiB;CACnB;CAEA,OAAO,wBAAwB,MAAM;AACvC"}

package/esm/index.d.mts

@@ -1,6 +1,8 @@
+import { HttpContext, PageContext } from "./context.mjs";
 import { AppLoader, LayoutLoader, PageLoader } from "./loaders.mjs";
 import { AppProps, LayoutProps, PageProps } from "./props.mjs";
 import { PageMetadata } from "./metadata.mjs";
+import { ErrorPageProps, SerializedErrorPageProps, SerializedPageError } from "./components/document-context.mjs";
 import { shared, useShared } from "./shared.mjs";
 import { QueryStringInput, QueryStringLeaf, QueryStringNested, QueryStringObject, QueryStringOptions, QueryStringValue, RepeatedKeyStrategy, UnserializableQueryValueError, queryString, queryStringOf, resetQueryStringOptions, setQueryStringOptions } from "./routing/query-string.mjs";
 import { RouteParameters, RouteQuery, href } from "./routing/route-table.mjs";
@@ -11,9 +13,8 @@ import { MatchedRoute, currentRoute, previousRoute } from "./client/navigation/c
 import { refresh } from "./client/navigation/refresh.mjs";
 import { Head } from "./components/head.mjs";
 import { Scripts } from "./components/scripts.mjs";
-import { PageContext } from "./context.mjs";
 
-//#region ../web/src/index.d.ts
+//#region web/src/index.d.ts
 /**
  * THE AUDIT SURFACE — everything the browser receives, declared by the app.
  *
@@ -31,5 +32,5 @@ import { PageContext } from "./context.mjs";
  */
 interface SharedContext {}
 //#endregion
-export { type AppLoader, type AppProps, Head, type LayoutLoader, type LayoutProps, Link, type MatchedRoute, type NavigationEndPayload, type NavigationErrorPayload, type NavigationStartPayload, type PageContext, type PageLoader, type PageMetadata, type PageProps, type QueryStringInput, type QueryStringLeaf, type QueryStringNested, type QueryStringObject, type QueryStringOptions, type QueryStringValue, type RepeatedKeyStrategy, type RouteParameters, type RouteQuery, Scripts, SharedContext, UnserializableQueryValueError, createRouterEvents, currentRoute, getHash, href, navigateBack, navigateTo, previousRoute, queryString, queryStringOf, refresh, resetQueryStringOptions, routerEvents, setQueryStringOptions, shared, useShared };
+export { type AppLoader, type AppProps, type ErrorPageProps, Head, type HttpContext, type LayoutLoader, type LayoutProps, Link, type MatchedRoute, type NavigationEndPayload, type NavigationErrorPayload, type NavigationStartPayload, type PageContext, type PageLoader, type PageMetadata, type PageProps, type QueryStringInput, type QueryStringLeaf, type QueryStringNested, type QueryStringObject, type QueryStringOptions, type QueryStringValue, type RepeatedKeyStrategy, type RouteParameters, type RouteQuery, Scripts, type SerializedErrorPageProps, type SerializedPageError, SharedContext, UnserializableQueryValueError, createRouterEvents, currentRoute, getHash, href, navigateBack, navigateTo, previousRoute, queryString, queryStringOf, refresh, resetQueryStringOptions, routerEvents, setQueryStringOptions, shared, useShared };
 //# sourceMappingURL=index.d.mts.map