@warlock.js/web 5.0.0

package/esm/hydration-payload.mjs

@@ -0,0 +1,72 @@
+import { PAYLOAD_SCRIPT_ID } from "./components/document-context.mjs";
+
+//#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
+* claim about a PAST revision — that is exactly how the rev. 3 keys landed with
+* two specs still asserting the rev. 2 shape.
+*/
+const REQUIRED_PAYLOAD_KEYS = [
+	"appData",
+	"layoutData",
+	"pageData",
+	"shared",
+	"name"
+];
+const ABSENT_PAYLOAD_MESSAGE = `Warlock hydration payload is absent: #${PAYLOAD_SCRIPT_ID}, owned by web/src/components/document-context.ts, was not found.`;
+const MALFORMED_PAYLOAD_MESSAGE = `Warlock hydration payload was found at #${PAYLOAD_SCRIPT_ID} but could not be read.`;
+function malformedPayload() {
+	throw new Error(MALFORMED_PAYLOAD_MESSAGE);
+}
+/**
+* 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
+* 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.
+*
+* 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
+* downstream would then be indexing a string. That is MALFORMED under the same
+* 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"];
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireHydrationPayload(value) {
+	if (!isPlainObject(value)) malformedPayload();
+	for (const key of REQUIRED_PAYLOAD_KEYS) if (!Object.prototype.hasOwnProperty.call(value, key)) malformedPayload();
+	for (const key of OPTIONAL_OBJECT_PAYLOAD_KEYS) {
+		const optional = value[key];
+		if (optional !== void 0 && !isPlainObject(optional)) malformedPayload();
+	}
+	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
+* ({@link OPTIONAL_OBJECT_PAYLOAD_KEYS}); it deliberately does not require
+* those to be present.
+*/
+function readHydrationPayload(documentNode) {
+	const element = documentNode.getElementById(PAYLOAD_SCRIPT_ID);
+	if (element === null) throw new Error(ABSENT_PAYLOAD_MESSAGE);
+	let parsed;
+	try {
+		parsed = JSON.parse(element.textContent ?? "");
+	} catch {
+		malformedPayload();
+	}
+	return requireHydrationPayload(parsed);
+}
+
+//#endregion
+export { readHydrationPayload };
+//# sourceMappingURL=hydration-payload.mjs.map

package/esm/hydration-payload.mjs.map

@@ -0,0 +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"}

package/esm/index.d.mts

@@ -0,0 +1,35 @@
+import { AppLoader, LayoutLoader, PageLoader } from "./loaders.mjs";
+import { AppProps, LayoutProps, PageProps } from "./props.mjs";
+import { PageMetadata } from "./metadata.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";
+import { Link } from "./components/link.mjs";
+import { getHash, navigateBack, navigateTo } from "./client/navigation/verbs.mjs";
+import { NavigationEndPayload, NavigationErrorPayload, NavigationStartPayload, createRouterEvents, routerEvents } from "./routing/router-events.mjs";
+import { MatchedRoute, currentRoute, previousRoute } from "./client/navigation/current-route.mjs";
+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
+/**
+ * THE AUDIT SURFACE — everything the browser receives, declared by the app.
+ *
+ * Ships EMPTY and with NO index signature: `shared.anything` does not compile
+ * until the application augments this interface (v5/app does at
+ * `src/web/types.ts:23-59`). Required keys demand an unconditional middleware
+ * writer; optional keys may be written conditionally.
+ *
+ * Declared HERE, in the entry module, and that placement is load-bearing:
+ * applications augment the module `"@warlock.js/web"`, and TypeScript merges a
+ * module augmentation only with interfaces declared in the module that
+ * specifier resolves to — an interface re-exported through the barrel from a
+ * concern file would NOT merge (microsoft/TypeScript#18877). The published
+ * package's entry .d.ts must keep declaring it directly for the same reason.
+ */
+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 };
+//# sourceMappingURL=index.d.mts.map

package/esm/index.mjs

@@ -0,0 +1,12 @@
+import { shared, useShared } from "./shared.mjs";
+import { UnserializableQueryValueError, queryString, queryStringOf, resetQueryStringOptions, setQueryStringOptions } from "./routing/query-string.mjs";
+import { href } from "./routing/route-table.mjs";
+import { Link } from "./components/link.mjs";
+import { getHash, navigateBack, navigateTo } from "./client/navigation/verbs.mjs";
+import { createRouterEvents, routerEvents } from "./routing/router-events.mjs";
+import { currentRoute, previousRoute } from "./client/navigation/current-route.mjs";
+import { refresh } from "./client/navigation/refresh.mjs";
+import { Head } from "./components/head.mjs";
+import { Scripts } from "./components/scripts.mjs";
+
+export { Head, Link, Scripts, UnserializableQueryValueError, createRouterEvents, currentRoute, getHash, href, navigateBack, navigateTo, previousRoute, queryString, queryStringOf, refresh, resetQueryStringOptions, routerEvents, setQueryStringOptions, shared, useShared };

package/esm/loaders.d.mts

@@ -0,0 +1,47 @@
+import { RouteDeclaration, RouteParamsOf } from "./route.mjs";
+import { PageValidation, ValidatedOutput } from "./validation.mjs";
+import { SharedContext } from "./index.mjs";
+import { PageContext, WebRequest, WebResponse } from "./context.mjs";
+
+//#region ../web/src/loaders.d.ts
+/**
+ * The context a PAGE loader receives, narrowed by the page's own sibling
+ * exports: `TValidation` types `request.validated()` off the schema,
+ * `TRoute` types `request.input()` off the path literal. A sibling export
+ * cannot contextually type an already-authored function — the generics are
+ * the mechanism that links them (product-details.page.tsx:20-41).
+ */
+type PageLoaderContext<TValidation extends PageValidation | undefined, TRoute extends RouteDeclaration | undefined> = {
+  request: WebRequest<ValidatedOutput<TValidation>, RouteParamsOf<TRoute>>;
+  response: WebResponse;
+  shared: SharedContext;
+};
+/**
+ * The page controller's contract. Used with `satisfies`, NEVER `:` — an
+ * annotation replaces the inferred type and `PageProps<typeof loader>` loses
+ * `data` (v5/app README §A). The return is `unknown` because `satisfies`
+ * preserves whatever the loader actually returns; the short-circuit brand and
+ * the props types do the narrowing on the way out.
+ *
+ * `TValidation` may be `undefined` — a page with no `validation` export
+ * (product-details.page.tsx:69). `TRoute` may be the config object or a bare
+ * string literal (contact-us.page.tsx:27).
+ */
+type PageLoader<TValidation extends PageValidation | undefined = undefined, TRoute extends RouteDeclaration | undefined = undefined> = (context: PageLoaderContext<TValidation, TRoute>) => unknown;
+/**
+ * A layout's controller. Bare — no generics — in every v5/app use
+ * (products/web/layout.tsx:53-58, dashboard.layout.tsx:34-36): a layout has
+ * no `validation`/`route` exports to link, and the contract is the annotated
+ * type, not a parameter list (`async () => …` is still a controller with the
+ * full context available).
+ */
+type LayoutLoader = (context: PageContext) => unknown;
+/**
+ * The application root's controller (root.tsx:56-58). Same shape as
+ * `LayoutLoader`; a separate name because the two revalidate and nest under
+ * different rules, and conflating them would make that drift invisible.
+ */
+type AppLoader = (context: PageContext) => unknown;
+//#endregion
+export { AppLoader, LayoutLoader, PageLoader };
+//# sourceMappingURL=loaders.d.mts.map

package/esm/metadata.d.mts

@@ -0,0 +1,54 @@
+import { LoaderData, LoaderFunction } from "./props.mjs";
+import { SharedContext } from "./index.mjs";
+
+//#region ../web/src/metadata.d.ts
+/**
+ * What the `metadata` export may produce. The pipeline injects it into
+ * `<head>` before the first byte; `<Head />` only decides placement.
+ */
+type MetadataOutput = {
+  title?: string;
+  description?: string;
+  keywords?: string | readonly string[];
+  canonical?: string;
+  robots?: string;
+  /**
+   * `og:title`/`og:description` fall back to the top-level `title`/
+   * `description` when `openGraph` is present but the member is absent —
+   * no other member has a fallback.
+   */
+  openGraph?: {
+    title?: string;
+    description?: string;
+    image?: string;
+    url?: string;
+    type?: string;
+  };
+  twitter?: {
+    card?: string;
+    title?: string;
+    description?: string;
+    image?: string;
+  };
+};
+/**
+ * Static object OR a function of the loader's data (products.page.tsx:81-84,
+ * product-details.page.tsx:71-74). The function form runs server-side, after
+ * the loader, with the same `data` the component will receive — which is why
+ * it can describe the page instead of guessing at it.
+ *
+ * **`data` is always present, and that is now true rather than merely
+ * declared.** The function form runs only when the loader resolved; when it
+ * rejected, the framework emits `ERROR_PAGE_METADATA` and this never runs
+ * (`server/resolve-page-metadata.ts`, which explains why at length). An earlier
+ * revision passed `{ data: undefined, error }` on the boundary path while
+ * declaring `data` non-optional — every page that read `data` unguarded then
+ * threw a `TypeError` that replaced the loader's real error.
+ */
+type PageMetadata<TLoader extends LoaderFunction | undefined = undefined> = MetadataOutput | ((context: {
+  data: LoaderData<TLoader>;
+  shared: Readonly<SharedContext>;
+}) => MetadataOutput);
+//#endregion
+export { PageMetadata };
+//# sourceMappingURL=metadata.d.mts.map

package/esm/props.d.mts

@@ -0,0 +1,42 @@
+import { SharedContext } from "./index.mjs";
+import { LoaderShortCircuit } from "./context.mjs";
+import { ReactNode } from "react";
+
+//#region ../web/src/props.d.ts
+/** Any loader authored with `satisfies` — the concrete function type. */
+type LoaderFunction = (...args: any[]) => unknown;
+/**
+ * The loader's literal return shape MINUS the branded short-circuits:
+ * `response.notFound()` / `response.redirect()` never union into `data`
+ * (product-details.page.tsx:45-57, login.page.tsx:71-84). No loader → no
+ * data.
+ */
+type LoaderData<TLoader> = TLoader extends LoaderFunction ? Exclude<Awaited<ReturnType<TLoader>>, LoaderShortCircuit> : undefined;
+/**
+ * What the pipeline hands a page component: its own loader's data plus the
+ * per-request payload. Never `request` or `response` — the component also
+ * renders on a machine where neither exists.
+ */
+type PageProps<TLoader extends LoaderFunction | undefined = undefined> = {
+  data: LoaderData<TLoader>;
+  shared: Readonly<SharedContext>;
+};
+/**
+ * A layout additionally receives the subtree it wraps. Usable bare —
+ * `LayoutProps` with no generic — for a layout with no loader
+ * (main/web/layout.tsx:26).
+ */
+type LayoutProps<TLoader extends LoaderFunction | undefined = undefined> = {
+  data: LoaderData<TLoader>;
+  shared: Readonly<SharedContext>;
+  children: ReactNode;
+};
+/** The root component's props (root.tsx:76). */
+type AppProps<TLoader extends LoaderFunction | undefined = undefined> = {
+  data: LoaderData<TLoader>;
+  shared: Readonly<SharedContext>;
+  children: ReactNode;
+};
+//#endregion
+export { AppProps, LayoutProps, LoaderData, LoaderFunction, PageProps };
+//# sourceMappingURL=props.d.mts.map

package/esm/route.d.mts

@@ -0,0 +1,30 @@
+//#region ../web/src/route.d.ts
+/**
+ * The `route` export's accepted shapes: the configured object
+ * (`{ path, name } as const` — the `as const` is what keeps `path` a literal
+ * a conditional type can parse, product-details.page.tsx:6-14) or the bare
+ * path string for the 2-line minimum page (contact-us.page.tsx:27, where the
+ * name is derived).
+ */
+type RouteDeclaration = string | {
+  readonly path: string;
+  readonly name?: string;
+};
+type RoutePath<TRoute> = TRoute extends string ? TRoute : TRoute extends {
+  readonly path: infer TPath extends string;
+} ? TPath : never;
+/**
+ * Parameter names out of a path literal: `"/:id"` → `"id"`,
+ * `"/a/:x/:y"` → `"x" | "y"`, `"/"` and `"*"` → `never` (so `request.input()`
+ * is uncallable where no parameter exists to read).
+ */
+type PathParams<TPath extends string> = TPath extends `${string}:${infer TRest}` ? TRest extends `${infer TParam}/${infer TTail}` ? TParam | PathParams<`/${TTail}`> : TRest : never;
+/**
+ * `undefined` (no route generic supplied) keeps `input()` loose rather than
+ * uncallable — the contract only narrows when the loader links its route via
+ * `satisfies PageLoader<…, typeof route>`.
+ */
+type RouteParamsOf<TRoute> = [TRoute] extends [undefined] ? string : PathParams<RoutePath<TRoute>>;
+//#endregion
+export { RouteDeclaration, RouteParamsOf };
+//# sourceMappingURL=route.d.mts.map

package/esm/routing/compose-route-path.mjs

@@ -0,0 +1,33 @@
+//#region ../web/src/routing/compose-route-path.ts
+/**
+* Route-path composition — the single, pure rule for turning a layout's
+* declared `prefix` and a page's declared `route.path` into the page's
+* effective, registered path. Previously three hand-written copies: the dev
+* installer (`web/src/server/install-page-routes.ts`), the production
+* manifest installer (`web/src/server/install-page-routes-from-manifest.ts`)
+* and build discovery (`web/src/build/discover-pages.ts`) each carried this
+* exact rule so build and boot could not quietly disagree about it; all
+* three now delegate here instead.
+*
+* DIRECTORY CONTRACT — applies to everything in `web/src/routing/`: nothing
+* here may import `node:fs`, `node:path`, `vite`, or `fastify`. This module
+* receives canonical values and trusts nothing about them beyond the input
+* contract asserted below — it asserts rather than trusts, but it never
+* repairs.
+*/
+/**
+* A page's effective path: its nearest layout's `prefix` followed by its own
+* declared `route.path`. A root prefix ("/") and a root path ("/") each
+* contribute nothing, so neither adds a slash of its own; every other case
+* joins on the slash `routePath` already starts with, which is what keeps a
+* double slash out of the result, and an empty concatenation is the site
+* root.
+*/
+function composeRoutePath(layoutPrefix, routePath) {
+	const composed = `${layoutPrefix === "/" ? "" : layoutPrefix.replace(/\/+$/, "")}${routePath === "/" ? "" : routePath}`;
+	return composed === "" ? "/" : composed;
+}
+
+//#endregion
+export { composeRoutePath };
+//# sourceMappingURL=compose-route-path.mjs.map

package/esm/routing/compose-route-path.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose-route-path.mjs","names":[],"sources":["../../../../../../../web/src/routing/compose-route-path.ts"],"sourcesContent":["/**\n * Route-path composition — the single, pure rule for turning a layout's\n * declared `prefix` and a page's declared `route.path` into the page's\n * effective, registered path. Previously three hand-written copies: the dev\n * installer (`web/src/server/install-page-routes.ts`), the production\n * manifest installer (`web/src/server/install-page-routes-from-manifest.ts`)\n * and build discovery (`web/src/build/discover-pages.ts`) each carried this\n * exact rule so build and boot could not quietly disagree about it; all\n * three now delegate here instead.\n *\n * DIRECTORY CONTRACT — applies to everything in `web/src/routing/`: nothing\n * here may import `node:fs`, `node:path`, `vite`, or `fastify`. This module\n * receives canonical values and trusts nothing about them beyond the input\n * contract asserted below — it asserts rather than trusts, but it never\n * repairs.\n */\n\n/**\n * A page's effective path: its nearest layout's `prefix` followed by its own\n * declared `route.path`. A root prefix (\"/\") and a root path (\"/\") each\n * contribute nothing, so neither adds a slash of its own; every other case\n * joins on the slash `routePath` already starts with, which is what keeps a\n * double slash out of the result, and an empty concatenation is the site\n * root.\n */\nexport function composeRoutePath(layoutPrefix: string, routePath: string): string {\n  const normalizedPrefix = layoutPrefix === \"/\" ? \"\" : layoutPrefix.replace(/\\/+$/, \"\");\n  const normalizedRoute = routePath === \"/\" ? \"\" : routePath;\n  const composed = `${normalizedPrefix}${normalizedRoute}`;\n\n  return composed === \"\" ? \"/\" : composed;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,SAAgB,iBAAiB,cAAsB,WAA2B;CAGhF,MAAM,WAAW,GAFQ,iBAAiB,MAAM,KAAK,aAAa,QAAQ,QAAQ,EAAE,IAC5D,cAAc,MAAM,KAAK;CAGjD,OAAO,aAAa,KAAK,MAAM;AACjC"}

package/esm/routing/data-request.mjs

@@ -0,0 +1,52 @@
+//#region ../web/src/routing/data-request.ts
+/**
+* The marker that turns a page request into a DATA request.
+*
+* A client navigation needs exactly what a full page load needs — middleware,
+* validation, loaders, redirects, cookies, the settled status — and differs in
+* one respect only: it wants the hydration payload as JSON instead of a
+* rendered document. So it is deliberately NOT a separate `/_loader` route.
+*
+* WHY NOT A SEPARATE ROUTE. A `/_loader?path=/products/42` endpoint has to
+* resolve that path to a page itself, which is a SECOND implementation of route
+* semantics living beside the server's. This codebase already refuses that
+* bargain for the browser — the hydration payload carries the route `name` so
+* the client never re-matches — and the same reasoning applies here with more
+* force: a loader endpoint that disagreed with the real route about params,
+* prefixes or which page owns a path would answer a different request than the
+* one the user navigated to. Same URL, same route, same matcher, same pipeline;
+* only the final representation differs.
+*
+* WHY A HEADER AND NOT `?_data=1`. The query string belongs to the page — it is
+* what `validation` and loaders read. Injecting a framework key into it means a
+* page with strict query validation rejects its own client navigations, and
+* every loader that echoes its query starts leaking a private flag.
+*
+* Responses to a data request must carry `Vary: <this header>` so a shared
+* cache can never hand a document to a client that asked for JSON, or the
+* reverse. Page responses are `private, no-store` today, which makes that
+* theoretical — `Vary` is what keeps it theoretical if the caching policy
+* changes.
+*/
+const WARLOCK_DATA_REQUEST_HEADER = "x-warlock-data";
+/**
+* Declared explicitly because the payload goes on the wire ALREADY SERIALIZED,
+* as a string, and core only auto-picks `application/json` for object bodies.
+* See the send site for why it must be a string.
+*/
+const DATA_RESPONSE_CONTENT_TYPE = "application/json";
+/**
+* Whether a request asked for the payload rather than the document.
+*
+* Presence-based on purpose: a proxy that rewrites the value, or a client on a
+* newer version that sends something more specific, still means "data". Only an
+* absent or empty header means "render the document".
+*/
+function isDataRequest(headerValue) {
+	const value = Array.isArray(headerValue) ? headerValue[0] : headerValue;
+	return typeof value === "string" && value.length > 0;
+}
+
+//#endregion
+export { DATA_RESPONSE_CONTENT_TYPE, WARLOCK_DATA_REQUEST_HEADER, isDataRequest };
+//# sourceMappingURL=data-request.mjs.map

package/esm/routing/data-request.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-request.mjs","names":[],"sources":["../../../../../../../web/src/routing/data-request.ts"],"sourcesContent":["/**\n * The marker that turns a page request into a DATA request.\n *\n * A client navigation needs exactly what a full page load needs — middleware,\n * validation, loaders, redirects, cookies, the settled status — and differs in\n * one respect only: it wants the hydration payload as JSON instead of a\n * rendered document. So it is deliberately NOT a separate `/_loader` route.\n *\n * WHY NOT A SEPARATE ROUTE. A `/_loader?path=/products/42` endpoint has to\n * resolve that path to a page itself, which is a SECOND implementation of route\n * semantics living beside the server's. This codebase already refuses that\n * bargain for the browser — the hydration payload carries the route `name` so\n * the client never re-matches — and the same reasoning applies here with more\n * force: a loader endpoint that disagreed with the real route about params,\n * prefixes or which page owns a path would answer a different request than the\n * one the user navigated to. Same URL, same route, same matcher, same pipeline;\n * only the final representation differs.\n *\n * WHY A HEADER AND NOT `?_data=1`. The query string belongs to the page — it is\n * what `validation` and loaders read. Injecting a framework key into it means a\n * page with strict query validation rejects its own client navigations, and\n * every loader that echoes its query starts leaking a private flag.\n *\n * Responses to a data request must carry `Vary: <this header>` so a shared\n * cache can never hand a document to a client that asked for JSON, or the\n * reverse. Page responses are `private, no-store` today, which makes that\n * theoretical — `Vary` is what keeps it theoretical if the caching policy\n * changes.\n */\nexport const WARLOCK_DATA_REQUEST_HEADER = \"x-warlock-data\";\n\n/**\n * The value the client sends. Any non-empty value is honoured on the way in —\n * the header's PRESENCE is the signal — but the client sends this one so the\n * traffic is self-describing in a log or a network panel.\n */\nexport const WARLOCK_DATA_REQUEST_VALUE = \"1\";\n\n/**\n * Declared explicitly because the payload goes on the wire ALREADY SERIALIZED,\n * as a string, and core only auto-picks `application/json` for object bodies.\n * See the send site for why it must be a string.\n */\nexport const DATA_RESPONSE_CONTENT_TYPE = \"application/json\";\n\n/**\n * Whether a request asked for the payload rather than the document.\n *\n * Presence-based on purpose: a proxy that rewrites the value, or a client on a\n * newer version that sends something more specific, still means \"data\". Only an\n * absent or empty header means \"render the document\".\n */\nexport function isDataRequest(headerValue: string | string[] | undefined): boolean {\n  const value = Array.isArray(headerValue) ? headerValue[0] : headerValue;\n\n  return typeof value === \"string\" && value.length > 0;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,MAAa,8BAA8B;;;;;;AAc3C,MAAa,6BAA6B;;;;;;;;AAS1C,SAAgB,cAAc,aAAqD;CACjF,MAAM,QAAQ,MAAM,QAAQ,WAAW,IAAI,YAAY,KAAK;CAE5D,OAAO,OAAO,UAAU,YAAY,MAAM,SAAS;AACrD"}

package/esm/routing/layout-policy.mjs

@@ -0,0 +1,78 @@
+//#region ../web/src/routing/layout-policy.ts
+/**
+* Raised when a `chain` passed to {@link selectPageLayout} contains an empty
+* layout identifier. An empty string is not a layout identifier a caller could
+* have meant; this module refuses it rather than silently treating it as
+* absent or as a real selection.
+*/
+var EmptyLayoutChainEntryError = class extends Error {
+	chain;
+	constructor(chain) {
+		super(`layout-policy: chain [${chain.map((entry) => `"${entry}"`).join(", ")}] contains an empty string. Every element of a layout chain passed to selectPageLayout must be a non-empty layout identifier — omit the entry entirely rather than passing an empty string for it.`);
+		this.chain = chain;
+		this.name = "EmptyLayoutChainEntryError";
+	}
+};
+/**
+* The single error contract for a `rejected` selection — the one class and
+* one message every caller of {@link selectPageLayout} raises when it refuses
+* a page whose path holds more than one RENDERING layout. `pageFile` and
+* `layoutFiles` are the caller's context (its audience-appropriate identifiers
+* for the page and the rejected rendering layouts — app-root-relative POSIX
+* paths, in practice); the category and wording are this module's.
+*
+* The wording names the rendering layouts and ONLY the rendering layouts, and
+* it does not offer removal as a remedy. Its predecessor said "remove or
+* consolidate the extra layout", which, on a chain whose second element was a
+* `middleware`-only authorization boundary, instructed the reader to delete
+* their security guard to make the build pass.
+*/
+var NestedLayoutsNotSupportedError = class extends Error {
+	pageFile;
+	layoutFiles;
+	constructor(pageFile, layoutFiles) {
+		super(`"${pageFile}" has more than one layout on its path that renders: ${layoutFiles.map((file) => `"${file}"`).join(", ")}. Pages currently support at most one RENDERING layout — a layout with a default export — and nesting more than one is not yet supported. Layouts that render nothing, such as a \`prefix\`- or \`middleware\`-only layout, do not count against this and may nest freely. To fix: consolidate the rendering layouts named above into one — and do not remove a middleware-only layout to satisfy this, since none of them is what this refuses.`);
+		this.pageFile = pageFile;
+		this.layoutFiles = layoutFiles;
+		this.name = "NestedLayoutsNotSupportedError";
+	}
+};
+/** The classified form of an entry, whichever way the caller spelled it. */
+function toEntry(entry) {
+	return typeof entry === "string" ? {
+		layout: entry,
+		renders: true
+	} : entry;
+}
+/**
+* Selects which layout, if any, a page RENDERS inside, given its layout chain
+* as enumerated outermost-first.
+*
+* Only entries with `renders: true` are counted: no rendering layout yields
+* `{ type: "none" }`; exactly one yields `{ type: "selected"; layout }`; more
+* than one yields `{ type: "rejected"; layouts }` carrying just those rendering
+* layouts — this function throws nothing for that case; see the module doc for
+* why rejection is data, not a throw.
+*
+* Throws {@link EmptyLayoutChainEntryError} when any entry's identifier is an
+* empty string — the one input-contract violation this module refuses rather
+* than passes through as a selection.
+*/
+function selectPageLayout(chain) {
+	const entries = chain.map(toEntry);
+	if (entries.some((entry) => entry.layout === "")) throw new EmptyLayoutChainEntryError(entries.map((entry) => entry.layout));
+	const rendering = entries.filter((entry) => entry.renders).map((entry) => entry.layout);
+	if (rendering.length === 0) return { type: "none" };
+	if (rendering.length === 1) return {
+		type: "selected",
+		layout: rendering[0]
+	};
+	return {
+		type: "rejected",
+		layouts: rendering
+	};
+}
+
+//#endregion
+export { NestedLayoutsNotSupportedError, selectPageLayout };
+//# sourceMappingURL=layout-policy.mjs.map

package/esm/routing/layout-policy.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout-policy.mjs","names":[],"sources":["../../../../../../../web/src/routing/layout-policy.ts"],"sourcesContent":["/**\n * Layout policy — the single, pure rule for turning a page's ENUMERATED\n * layout chain into a selection decision.\n *\n * Enumeration and selection are deliberately separate concerns. Discovery\n * ({@link \"../build/discover-pages.ts\"}'s `layoutChainFor`) walks a page's\n * directory ancestry and reports every `layout.tsx` it finds, outermost\n * first, honestly and unfiltered — it does not decide whether that chain is\n * usable. This module is the one place that decision is made: given a chain,\n * how many layouts does composition get to use, and which one(s)?\n *\n * THE RULE COUNTS RENDERING LAYOUTS, NOT FILES. A layout that contributes no\n * element to the document — one with no default export, carrying only\n * `prefix`, `middleware` or other named exports — is not a second wrapper and\n * never was. Counting files instead of wrappers made an authorization boundary\n * indistinguishable from a nested layout, and the resulting refusal told app\n * authors to delete the boundary to make the build pass. Nested RENDERING\n * layouts remain unsupported; everything else composes freely.\n *\n * DIRECTORY CONTRACT — applies to everything in `web/src/routing/`: nothing\n * here may import `node:fs`, `node:path`, `vite`, or `fastify`. This module\n * receives a canonical chain and trusts nothing about it beyond the input\n * contract asserted below — it asserts rather than trusts, but it never\n * repairs. It therefore never DECIDES what renders either: that answer needs\n * the filesystem, so the caller — which has it — classifies each entry and\n * passes the classification in. Discovery owns the fact; this module owns the\n * rule. The `layout` identifiers are opaque (paths, in practice) and this\n * module never inspects their shape; it only counts and selects.\n *\n * REJECTION IS DATA, NOT A THROW: a chain with two or more rendering layouts\n * does not make {@link selectPageLayout} raise — it returns the rejected\n * rendering layouts, in order. What a rejection MEANS to the user is\n * nonetheless fixed here: {@link NestedLayoutsNotSupportedError} is the single\n * error contract for it — one class, one message shape, built from the\n * rejection data plus caller-supplied page identity. Callers decide only WHEN\n * to raise it and supply that context; none of them wraps the rejection in a\n * category or wording of its own. A shared policy whose failure semantics fork\n * per caller is shared in the happy path and forked in the sad one — and the\n * sad path is the one users meet.\n */\n\n/**\n * One layout in a chain, with the caller's answer to the only question this\n * module needs about it: does it render?\n *\n * `renders` is true when the layout's module has a default export — the thing\n * that puts an element in the document. Everything else it exports (`prefix`,\n * `middleware`, helpers) is invisible to this rule.\n */\nexport type LayoutChainEntry = {\n  /** Opaque identifier for the layout — an app-root-relative POSIX path, in practice. */\n  layout: string;\n  /** Whether this layout contributes an element to the document. */\n  renders: boolean;\n};\n\n/**\n * A chain as {@link selectPageLayout} accepts it: classified entries, or bare\n * identifiers for a caller that has not classified its chain yet.\n *\n * TRANSITIONAL: a bare string is read as a RENDERING layout, which is the\n * conservative reading (it can only make the rule stricter, never looser) and\n * reproduces this module's pre-classification behaviour exactly. It exists so\n * the boot-time manifest installer — which holds loaded modules rather than\n * source files — keeps working unchanged until it classifies too; remove the\n * string arm once every caller passes {@link LayoutChainEntry}s.\n */\nexport type LayoutChainInput = readonly (string | LayoutChainEntry)[];\n\n/**\n * The policy's decision for one page's layout chain:\n *\n * - `\"none\"` — no layout on the chain renders; the page composes against no\n *   layout. A chain of three middleware-only layouts lands here exactly as an\n *   empty chain does, because neither has a wrapper in it.\n * - `\"selected\"` — exactly one layout renders; `layout` is that element, which,\n *   being the only rendering one, is simultaneously the outermost and the\n *   nearest rendering layout — there is no distinction to draw between the two\n *   when there is only one.\n * - `\"rejected\"` — more than one layout renders; `layouts` carries the\n *   RENDERING layouts only, outermost-first, in chain order, so a consumer can\n *   name every layout actually at fault without naming the guards between them.\n */\nexport type LayoutPolicyResult =\n  | { type: \"none\" }\n  | { type: \"selected\"; layout: string }\n  | { type: \"rejected\"; layouts: readonly string[] };\n\n/**\n * Raised when a `chain` passed to {@link selectPageLayout} contains an empty\n * layout identifier. An empty string is not a layout identifier a caller could\n * have meant; this module refuses it rather than silently treating it as\n * absent or as a real selection.\n */\nexport class EmptyLayoutChainEntryError extends Error {\n  public constructor(public readonly chain: readonly string[]) {\n    super(\n      `layout-policy: chain [${chain.map((entry) => `\"${entry}\"`).join(\", \")}] contains an empty ` +\n        \"string. Every element of a layout chain passed to selectPageLayout must be a non-empty \" +\n        \"layout identifier — omit the entry entirely rather than passing an empty string for it.\",\n    );\n    this.name = \"EmptyLayoutChainEntryError\";\n  }\n}\n\n/**\n * The single error contract for a `rejected` selection — the one class and\n * one message every caller of {@link selectPageLayout} raises when it refuses\n * a page whose path holds more than one RENDERING layout. `pageFile` and\n * `layoutFiles` are the caller's context (its audience-appropriate identifiers\n * for the page and the rejected rendering layouts — app-root-relative POSIX\n * paths, in practice); the category and wording are this module's.\n *\n * The wording names the rendering layouts and ONLY the rendering layouts, and\n * it does not offer removal as a remedy. Its predecessor said \"remove or\n * consolidate the extra layout\", which, on a chain whose second element was a\n * `middleware`-only authorization boundary, instructed the reader to delete\n * their security guard to make the build pass.\n */\nexport class NestedLayoutsNotSupportedError extends Error {\n  public constructor(\n    public readonly pageFile: string,\n    public readonly layoutFiles: readonly string[],\n  ) {\n    super(\n      `\"${pageFile}\" has more than one layout on its path that renders: ` +\n        `${layoutFiles.map((file) => `\"${file}\"`).join(\", \")}. Pages currently support at most one ` +\n        \"RENDERING layout — a layout with a default export — and nesting more than one is not yet \" +\n        \"supported. Layouts that render nothing, such as a `prefix`- or `middleware`-only layout, \" +\n        \"do not count against this and may nest freely. To fix: consolidate the rendering layouts \" +\n        \"named above into one — and do not remove a middleware-only layout to satisfy this, since \" +\n        \"none of them is what this refuses.\",\n    );\n    this.name = \"NestedLayoutsNotSupportedError\";\n  }\n}\n\n/** The classified form of an entry, whichever way the caller spelled it. */\nfunction toEntry(entry: string | LayoutChainEntry): LayoutChainEntry {\n  return typeof entry === \"string\" ? { layout: entry, renders: true } : entry;\n}\n\n/**\n * Selects which layout, if any, a page RENDERS inside, given its layout chain\n * as enumerated outermost-first.\n *\n * Only entries with `renders: true` are counted: no rendering layout yields\n * `{ type: \"none\" }`; exactly one yields `{ type: \"selected\"; layout }`; more\n * than one yields `{ type: \"rejected\"; layouts }` carrying just those rendering\n * layouts — this function throws nothing for that case; see the module doc for\n * why rejection is data, not a throw.\n *\n * Throws {@link EmptyLayoutChainEntryError} when any entry's identifier is an\n * empty string — the one input-contract violation this module refuses rather\n * than passes through as a selection.\n */\nexport function selectPageLayout(chain: LayoutChainInput): LayoutPolicyResult {\n  const entries = chain.map(toEntry);\n\n  if (entries.some((entry) => entry.layout === \"\")) {\n    throw new EmptyLayoutChainEntryError(entries.map((entry) => entry.layout));\n  }\n\n  const rendering = entries.filter((entry) => entry.renders).map((entry) => entry.layout);\n\n  if (rendering.length === 0) {\n    return { type: \"none\" };\n  }\n\n  if (rendering.length === 1) {\n    return { type: \"selected\", layout: rendering[0] };\n  }\n\n  return { type: \"rejected\", layouts: rendering };\n}\n"],"mappings":";;;;;;;AA8FA,IAAa,6BAAb,cAAgD,MAAM;CACjB;CAAnC,AAAO,YAAY,AAAgB,OAA0B;EAC3D,MACE,yBAAyB,MAAM,KAAK,UAAU,IAAI,MAAM,EAAE,CAAC,CAAC,KAAK,IAAI,EAAE,mMAGzE;EALiC;EAMjC,KAAK,OAAO;CACd;AACF;;;;;;;;;;;;;;;AAgBA,IAAa,iCAAb,cAAoD,MAAM;CAEtC;CACA;CAFlB,AAAO,YACL,AAAgB,UAChB,AAAgB,aAChB;EACA,MACE,IAAI,SAAS,uDACR,YAAY,KAAK,SAAS,IAAI,KAAK,EAAE,CAAC,CAAC,KAAK,IAAI,EAAE,ibAMzD;EAXgB;EACA;EAWhB,KAAK,OAAO;CACd;AACF;;AAGA,SAAS,QAAQ,OAAoD;CACnE,OAAO,OAAO,UAAU,WAAW;EAAE,QAAQ;EAAO,SAAS;CAAK,IAAI;AACxE;;;;;;;;;;;;;;;AAgBA,SAAgB,iBAAiB,OAA6C;CAC5E,MAAM,UAAU,MAAM,IAAI,OAAO;CAEjC,IAAI,QAAQ,MAAM,UAAU,MAAM,WAAW,EAAE,GAC7C,MAAM,IAAI,2BAA2B,QAAQ,KAAK,UAAU,MAAM,MAAM,CAAC;CAG3E,MAAM,YAAY,QAAQ,QAAQ,UAAU,MAAM,OAAO,CAAC,CAAC,KAAK,UAAU,MAAM,MAAM;CAEtF,IAAI,UAAU,WAAW,GACvB,OAAO,EAAE,MAAM,OAAO;CAGxB,IAAI,UAAU,WAAW,GACvB,OAAO;EAAE,MAAM;EAAY,QAAQ,UAAU;CAAG;CAGlD,OAAO;EAAE,MAAM;EAAY,SAAS;CAAU;AAChD"}

package/esm/routing/navigator.mjs

@@ -0,0 +1,21 @@
+//#region ../web/src/routing/navigator.ts
+let navigator;
+/**
+* Installed by the navigation runtime at mount, and torn down with `undefined`.
+*
+* @returns the previous navigator, so a caller that installs one can restore
+* what was there — the same shape the other `connect*` seams in this package
+* use, and what makes a test able to leave the module as it found it.
+*/
+function connectNavigator(next) {
+	const previous = navigator;
+	navigator = next;
+	return previous;
+}
+function currentNavigator() {
+	return navigator;
+}
+
+//#endregion
+export { connectNavigator, currentNavigator };
+//# sourceMappingURL=navigator.mjs.map

package/esm/routing/navigator.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigator.mjs","names":[],"sources":["../../../../../../../web/src/routing/navigator.ts"],"sourcesContent":["/**\n * The one seam between `<Link>` and the client navigation runtime.\n *\n * `<Link>` is UNIVERSAL — the same component renders on the server and in the\n * browser — so it cannot import the runtime: doing so would drag `fetch`, the\n * page registry and React state into the server render, and into the bundle of\n * any app that never navigates client-side.\n *\n * So the runtime REGISTERS itself here instead, and `<Link>` asks. On the\n * server nothing has registered, `currentNavigator()` is `undefined`, and the\n * anchor behaves as a plain anchor — which is exactly right, because on the\n * server it IS a plain anchor.\n *\n * This is also what makes the feature progressively enhancing rather than\n * load-bearing: until the hydration bundle has run and registered, every link\n * on the page still works as an ordinary link.\n */\n\n/**\n * @returns `true` if the runtime accepted the navigation and the caller should\n * suppress the browser's default. `false` means \"not mine\" — let the browser do\n * what it was going to do.\n */\nexport type Navigator = (url: string, options?: { replace?: boolean }) => boolean;\n\nlet navigator: Navigator | undefined;\n\n/**\n * Installed by the navigation runtime at mount, and torn down with `undefined`.\n *\n * @returns the previous navigator, so a caller that installs one can restore\n * what was there — the same shape the other `connect*` seams in this package\n * use, and what makes a test able to leave the module as it found it.\n */\nexport function connectNavigator(next: Navigator | undefined): Navigator | undefined {\n  const previous = navigator;\n\n  navigator = next;\n\n  return previous;\n}\n\nexport function currentNavigator(): Navigator | undefined {\n  return navigator;\n}\n"],"mappings":";AAyBA,IAAI;;;;;;;;AASJ,SAAgB,iBAAiB,MAAoD;CACnF,MAAM,WAAW;CAEjB,YAAY;CAEZ,OAAO;AACT;AAEA,SAAgB,mBAA0C;CACxD,OAAO;AACT"}