@warlock.js/web 5.0.0

package/esm/components/link.d.mts

@@ -0,0 +1,157 @@
+import { AnchorHTMLAttributes, ComponentType, ReactElement } from "react";
+
+//#region ../web/src/components/link.d.ts
+/**
+ * `<Link>` is SUGAR over `href()`, and deliberately thin.
+ *
+ * `href(name, params, query)` is the durable primitive — it serves emails,
+ * redirects, `Location` headers and every non-React caller, none of which can
+ * render a component. This file adds one thing to it: an anchor element.
+ *
+ * It renders a real `<a href>`. Client-side interception is a later slice of
+ * the navigation runtime and lands here without changing this API, which is the
+ * point of routing everything through `href` first: navigation becomes a
+ * BEHAVIOUR change, not an API change.
+ *
+ * ── Parity with `@mongez/react-router` ───────────────────────────────────────
+ * `href`, `newTab`, `email`, `tel`, `component` and `prefetch` are spelled
+ * exactly as MRR spells them, so a component moved across keeps compiling.
+ * `params` and `query` are ours and have no MRR equivalent: they pair with the
+ * typed `href()` helper, which is what makes a route NAME — rather than a URL —
+ * the thing a call site names.
+ *
+ * ── The semantic divergence this file bridges ────────────────────────────────
+ * MRR's `to` is a PATH. Ours was a route NAME, and only a name — which meant a
+ * component moved across from MRR compiled and then threw at render, because
+ * `"/products"` is not the name of anything. The two packages disagreed about
+ * what the most-used prop in either of them MEANS.
+ *
+ * Since 2026-08-24 (owner ruling) `to`/`href` accept BOTH, discriminated by
+ * SHAPE — see {@link isLiteralUrl}. That is what makes MRR code portable, and
+ * it costs nothing at a Warlock call site, because the two grammars cannot
+ * collide: a route name never begins with `/` and never carries a `scheme:`.
+ * The ruling RESTS on that, so this file asserts it rather than trusting it
+ * ({@link RouteNameShapeCollisionError}).
+ */
+type AnchorProps = Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href">;
+/**
+ * Where the link goes. Every field is documented here once; which COMBINATIONS
+ * are legal is decided by {@link LinkDestination}.
+ */
+type LinkDestinationProps = {
+  /**
+   * A route NAME, or a literal URL — told apart by SHAPE.
+   *
+   * `"products.details"` is a NAME and is resolved through the route table. A
+   * page that moves changes its URL and keeps its name, so every call site
+   * survives the move; a dead name throws at render naming the routes that do
+   * exist, rather than rendering an anchor that 404s. This is the form to
+   * prefer, and the only one `params` and `query` apply to.
+   *
+   * `"/pricing"`, `"https://stripe.com"`, `"mailto:sales@example.com"` and any
+   * other `scheme:` are LITERAL — passed through to the element untouched, with
+   * no route lookup at all. An app links out, and a route name is not a thing
+   * you can have for a page that is not yours.
+   */
+  to?: string;
+  /**
+   * An alias of {@link to}, for parity with `@mongez/react-router`. Identical
+   * in every respect, including which shapes it accepts.
+   */
+  href?: string; /** Renders a `mailto:` link. Not an in-app navigation. */
+  email?: string; /** Renders a `tel:` link. Not an in-app navigation. */
+  tel?: string;
+  /**
+   * Values for the route's `:param` segments, e.g. `{ id }` for
+   * `"/products/:id"`. Only meaningful with a route NAME.
+   */
+  params?: Record<string, unknown>;
+  /**
+   * Query string values; an `undefined` value is omitted. Only meaningful with
+   * a route NAME.
+   */
+  query?: Record<string, unknown>;
+};
+/**
+ * EXACTLY ONE destination, enforced by the type.
+ *
+ * The alternative — a documented precedence such as "`to` wins over `href`" —
+ * is silent by construction: the losing prop goes on compiling and goes on
+ * reading like it works at the call site, and the anchor points at the wrong
+ * page. Refusing the pair costs a call site one edit and can never be
+ * misread. The runtime refuses it as well, because a JavaScript caller and a
+ * cast both get past this.
+ */
+type LinkDestination = {
+  to: string;
+  href?: never;
+  email?: never;
+  tel?: never;
+} | {
+  href: string;
+  to?: never;
+  email?: never;
+  tel?: never;
+} | {
+  email: string;
+  to?: never;
+  href?: never;
+  tel?: never;
+} | {
+  tel: string;
+  to?: never;
+  href?: never;
+  email?: never;
+};
+type LinkProps = AnchorProps & LinkDestinationProps & LinkDestination & {
+  /**
+   * Open in a new browsing context: `target="_blank"` plus the `rel` that
+   * stops the opened page from reaching back through `window.opener`.
+   *
+   * A caller's own `target`/`rel` win — this only fills in what was not said.
+   */
+  newTab?: boolean;
+  /**
+   * Render as something other than `<a>` — a tag name or a component.
+   *
+   * It receives the resolved `href`, the click handler and every remaining
+   * prop, so a design-system anchor keeps client-side navigation as long as
+   * it spreads what it is given onto the element it renders.
+   *
+   * `ComponentType<any>` is MRR's signature, kept verbatim: the component is
+   * the caller's and its props are unknowable from here.
+   */
+  component?: ComponentType<any> | string;
+  /**
+   * Fetch this page's data when the pointer or the keyboard reaches the link,
+   * so the click that follows swaps without a round trip.
+   *
+   * A GUESS, and treated as one everywhere: it is never awaited, a failure is
+   * silent, and the click behaves exactly as it would without it. Opt-in per
+   * link rather than on by default, because every prefetch is a request the
+   * user did not ask for and someone pays for the bandwidth.
+   *
+   * IGNORED for anything that is not an in-app navigation — an external URL,
+   * `mailto:`, `tel:`, `newTab`, any explicit `target`. Prefetching those
+   * would mean issuing a cross-origin request to a third party on hover,
+   * which is not a thing a link component may decide to do.
+   */
+  prefetch?: boolean;
+};
+declare function Link({
+  to,
+  href: hrefAlias,
+  email,
+  tel,
+  params,
+  query,
+  newTab,
+  prefetch,
+  component: Component,
+  children,
+  onClick,
+  ...elementProps
+}: LinkProps): ReactElement;
+//#endregion
+export { Link };
+//# sourceMappingURL=link.d.mts.map

package/esm/components/link.mjs

@@ -0,0 +1,194 @@
+import { href, knownRouteNames } from "../routing/route-table.mjs";
+import { prefetchPageData } from "../client/navigation/prefetch.mjs";
+import { currentNavigator } from "../routing/navigator.mjs";
+import { createElement } from "react";
+
+//#region ../web/src/components/link.ts
+const DESTINATION_PROPS = [
+	"to",
+	"href",
+	"email",
+	"tel"
+];
+var AmbiguousLinkDestinationError = class extends Error {
+	providedProps;
+	constructor(providedProps) {
+		super(`Warlock <Link> was given ${providedProps.map((name) => JSON.stringify(name)).join(" and ")}, but a link goes to exactly one place. There is no precedence between them on purpose: one of the two would silently win, and the call site would go on naming a destination that never renders. Delete the one you did not mean.`);
+		this.providedProps = providedProps;
+		this.name = "AmbiguousLinkDestinationError";
+	}
+};
+var MissingLinkDestinationError = class extends Error {
+	constructor() {
+		super(`Warlock <Link> was given no destination. Pass exactly one of ${DESTINATION_PROPS.map((name) => JSON.stringify(name)).join(", ")}. It is not defaulted to the current page: an anchor with an empty \`href\` renders as a working link and reloads the page when clicked, which is a harder fault to see than this message.`);
+		this.name = "MissingLinkDestinationError";
+	}
+};
+var RouteArgumentsOnLiteralUrlError = class extends Error {
+	url;
+	providedProps;
+	constructor(url, providedProps) {
+		super(`Warlock <Link> was given ${providedProps.map((name) => JSON.stringify(name)).join(" and ")} alongside the literal URL "${url}". Those apply to a route NAME, which is resolved through the route table; a literal URL is passed through exactly as written, so they would have been dropped and the link would have pointed at an unfiltered page that still looked right at the call site. Put the values in the URL, or name the route.`);
+		this.url = url;
+		this.providedProps = providedProps;
+		this.name = "RouteArgumentsOnLiteralUrlError";
+	}
+};
+/**
+* The ruling's one assumption, broken. See the module doc comment: telling a
+* literal URL from a route NAME by shape is only safe while no route is NAMED
+* like a URL, and nothing in the route pipeline validates a hand-declared
+* `route.name`. So the collision is checked at the one place it could do harm,
+* where it is a loud refusal instead of an anchor that silently points
+* somewhere else.
+*/
+var RouteNameShapeCollisionError = class extends Error {
+	routeName;
+	constructor(routeName) {
+		super(`Warlock route table: a route is NAMED ${JSON.stringify(routeName)}, which is shaped like a URL. <Link> tells a literal URL from a route name by shape — a destination starting with \`/\` or carrying a \`scheme:\` is passed through untouched — so this name can never be resolved, and every link to it would silently point at that path instead. Rename the route (\`route = { path, name }\`) to a dotted name such as ${JSON.stringify(routeName.replace(/^\/+/, "").replace(/\//g, ".") || "index")}.`);
+		this.routeName = routeName;
+		this.name = "RouteNameShapeCollisionError";
+	}
+};
+/**
+* Any RFC 3986 scheme — `https:`, `mailto:`, `tel:`, `whatsapp:`, an app's own
+* custom one. Matched generically rather than as a list of known schemes: a
+* list would silently resolve `bitcoin:...` through the route table, which is
+* the exact failure this ruling exists to remove, and it would have to grow
+* forever.
+*/
+const SCHEME_PATTERN = /^[a-z][a-z0-9+.-]*:/i;
+/**
+* Whether this destination is a URL to be used as written, rather than a route
+* name to resolve.
+*
+* The whole discriminator, and deliberately the whole of it: two cheap shape
+* tests, no parsing, no matching. Anything more would be a SECOND route matcher
+* living beside the server's, which this codebase refuses everywhere it comes
+* up — a matcher that disagreed with the real one would produce links to pages
+* that do not exist.
+*/
+function isLiteralUrl(destination) {
+	return destination.startsWith("/") || SCHEME_PATTERN.test(destination);
+}
+/**
+* Whether a literal URL addresses THIS app.
+*
+* A path is ours. A `scheme:` is not — including `https:` to our own origin,
+* which would need `window.location` to recognise and would make the answer
+* depend on where the code is running. And `//host/path` is PROTOCOL-RELATIVE:
+* it starts with a slash and is nonetheless another origin, which is precisely
+* the case a "starts with `/`" test alone would hand to the navigator, where it
+* becomes a `pushState` to a foreign origin — a SecurityError — or a
+* speculative fetch of a third-party host.
+*/
+function addressesThisApp(url) {
+	return url.startsWith("/") && !url.startsWith("//");
+}
+/**
+* Refuses the one table that would make {@link isLiteralUrl} wrong.
+*
+* Reached only for a destination already judged literal, so the cost is a scan
+* of the published names for links that were never going to hit the table
+* anyway — and zero for the route-name form, which is the common one. The right
+* permanent home for this is `publishRouteTable`, at boot, once (see the report
+* on this card).
+*/
+function assertNotARouteName(url) {
+	if (knownRouteNames().includes(url)) throw new RouteNameShapeCollisionError(url);
+}
+const ROUTE_ARGUMENT_PROPS = ["params", "query"];
+function resolveDestination(props) {
+	const provided = DESTINATION_PROPS.filter((name) => props[name] !== void 0);
+	if (provided.length > 1) throw new AmbiguousLinkDestinationError(provided);
+	if (provided.length === 0) throw new MissingLinkDestinationError();
+	if (props.email !== void 0) return {
+		url: `mailto:${props.email}`,
+		isInApp: false
+	};
+	if (props.tel !== void 0) return {
+		url: `tel:${props.tel}`,
+		isInApp: false
+	};
+	const destination = props.to ?? props.href;
+	if (isLiteralUrl(destination)) {
+		const routeArguments = ROUTE_ARGUMENT_PROPS.filter((name) => props[name] !== void 0);
+		if (routeArguments.length > 0) throw new RouteArgumentsOnLiteralUrlError(destination, routeArguments);
+		assertNotARouteName(destination);
+		return {
+			url: destination,
+			isInApp: addressesThisApp(destination)
+		};
+	}
+	return {
+		url: href(destination, props.params, props.query),
+		isInApp: true
+	};
+}
+/**
+* Whether this click should be left entirely to the browser.
+*
+* Every case here is a click that MEANS something other than "go there in this
+* tab", and intercepting any of them would take away behaviour the user
+* explicitly asked for:
+*
+*   - a modifier or middle button: open in a new tab/window, or download
+*   - `download`: save the resource, do not render it
+*   - already prevented: something upstream in the tree handled this click
+*
+* Left button with no modifiers is the only click that means plain navigation.
+* The `target` case is decided before this, from the RESOLVED target, because
+* `newTab` sets it after the caller's props are read.
+*/
+function isPlainLeftClick(event) {
+	return event.button === 0 && !event.metaKey && !event.ctrlKey && !event.shiftKey && !event.altKey && !event.defaultPrevented;
+}
+/**
+* A target other than `_self` names ANOTHER browsing context — `_blank`, but
+* also `_parent`, `_top` and any named frame. Client navigation rewrites the
+* history of THIS one, so none of them are ours to intercept.
+*/
+function opensAnotherContext(target) {
+	return target !== void 0 && target !== "_self";
+}
+function Link({ to, href: hrefAlias, email, tel, params, query, newTab, prefetch, component: Component = "a", children, onClick, ...elementProps }) {
+	const { url, isInApp } = resolveDestination({
+		to,
+		href: hrefAlias,
+		email,
+		tel,
+		params,
+		query
+	});
+	const target = elementProps.target ?? (newTab === true ? "_blank" : void 0);
+	const rel = elementProps.rel ?? (target === "_blank" ? "noopener noreferrer" : void 0);
+	const handleClick = (event) => {
+		onClick?.(event);
+		if (!isInApp || opensAnotherContext(target)) return;
+		if (!isPlainLeftClick(event)) return;
+		if (currentNavigator()?.(url) !== true) return;
+		event.preventDefault();
+	};
+	const prefetchHandlers = prefetch === true && isInApp && !opensAnotherContext(target) ? {
+		onMouseEnter: (event) => {
+			elementProps.onMouseEnter?.(event);
+			prefetchPageData(url);
+		},
+		onFocus: (event) => {
+			elementProps.onFocus?.(event);
+			prefetchPageData(url);
+		}
+	} : void 0;
+	return createElement(Component, {
+		...elementProps,
+		...prefetchHandlers,
+		target,
+		rel,
+		href: url,
+		onClick: handleClick
+	}, children);
+}
+
+//#endregion
+export { Link };
+//# sourceMappingURL=link.mjs.map

package/esm/components/link.mjs.map

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

package/esm/components/scripts.d.mts

@@ -0,0 +1,14 @@
+import { ReactElement } from "react";
+
+//#region ../web/src/components/scripts.d.ts
+type ScriptsProps = {
+  /** Per-request CSP nonce for the inline payload script (root.tsx:119). */nonce?: string;
+};
+/**
+ * OPTIONAL placement override for the serialized loader data and `shared`.
+ * Hydration module emission is separate wiring.
+ */
+declare function Scripts(props: ScriptsProps): ReactElement;
+//#endregion
+export { Scripts };
+//# sourceMappingURL=scripts.d.mts.map

package/esm/components/scripts.mjs

@@ -0,0 +1,21 @@
+import { PAYLOAD_SCRIPT_ID, escapePayload, useDocumentContext } from "./document-context.mjs";
+import { createElement } from "react";
+
+//#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");
+	return createElement("script", {
+		id: PAYLOAD_SCRIPT_ID,
+		type: "application/json",
+		nonce: props.nonce ?? nonce,
+		dangerouslySetInnerHTML: { __html: escapePayload(JSON.stringify(payload)) }
+	});
+}
+
+//#endregion
+export { Scripts };
+//# sourceMappingURL=scripts.mjs.map

package/esm/components/scripts.mjs.map

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

package/esm/connector/index.d.mts

@@ -0,0 +1,6 @@
+import { WebBuildOptions, WebPackageRootResolutionError, createWebBuildContribution } from "../build/contribution.mjs";
+import { PageManifest, PageManifestLayoutEntry, PageManifestPageEntry, consumePageManifest, providePageManifest } from "../server/page-manifest.mjs";
+import { CLIENT_ASSET_URL_PREFIX } from "../server/client-asset-url-prefix.mjs";
+import { ResolveHydrationClientUrlOptions, WebClientAssetPrefixViolationError, WebClientManifestEntryMissingError, WebClientManifestMalformedError, WebClientManifestMissingError, resolveHydrationClientUrl } from "../server/hydration-client-url.mjs";
+import { webConnector } from "../server/web-connector-factory.mjs";
+export { CLIENT_ASSET_URL_PREFIX, type PageManifest, type PageManifestLayoutEntry, type PageManifestPageEntry, type ResolveHydrationClientUrlOptions, type WebBuildOptions, WebClientAssetPrefixViolationError, WebClientManifestEntryMissingError, WebClientManifestMalformedError, WebClientManifestMissingError, WebPackageRootResolutionError, consumePageManifest, createWebBuildContribution, providePageManifest, resolveHydrationClientUrl, webConnector };

package/esm/connector/index.mjs

@@ -0,0 +1,7 @@
+import { WebPackageRootResolutionError, createWebBuildContribution } from "../build/contribution.mjs";
+import { consumePageManifest, providePageManifest } from "../server/page-manifest.mjs";
+import { CLIENT_ASSET_URL_PREFIX } from "../server/client-asset-url-prefix.mjs";
+import { WebClientAssetPrefixViolationError, WebClientManifestEntryMissingError, WebClientManifestMalformedError, WebClientManifestMissingError, resolveHydrationClientUrl } from "../server/hydration-client-url.mjs";
+import { webConnector } from "../server/web-connector-factory.mjs";
+
+export { CLIENT_ASSET_URL_PREFIX, WebClientAssetPrefixViolationError, WebClientManifestEntryMissingError, WebClientManifestMalformedError, WebClientManifestMissingError, WebPackageRootResolutionError, consumePageManifest, createWebBuildContribution, providePageManifest, resolveHydrationClientUrl, webConnector };

package/esm/context.d.mts

@@ -0,0 +1,107 @@
+import { SharedContext } from "./index.mjs";
+
+//#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 {
+  shared: SharedContext;
+}
+//#endregion
+export { LoaderShortCircuit, PageContext, WebRequest, WebResponse };
+//# sourceMappingURL=context.d.mts.map

package/esm/hydration/index.d.mts

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

package/esm/hydration/index.mjs

@@ -0,0 +1,33 @@
+import { publishRouteTable } from "../routing/route-table.mjs";
+import { buildHydratedTree } from "../client/build-hydrated-tree.mjs";
+import { hydratePage } from "../client/hydrate-page.mjs";
+import { NavigationRoot } from "../client/navigation/navigation-root.mjs";
+import { createElement } from "react";
+import { pages } from "virtual:warlock/pages";
+
+//#region ../web/src/hydration/index.ts
+/**
+* The client entry: registry in, hydration out. No page names, no app paths.
+*
+* The page graph arrives from the Vite virtual module the build plugin serves,
+* so this file works for ANY page in ANY app. The previous version imported one
+* page and one layout by relative path into the monorepo's reference app, which
+* both hydrated every URL as the home page and made `@warlock.js/web`
+* uninstallable anywhere outside this checkout. Neither a page name nor an app
+* path appears here now, and nothing about the composition lives here either -
+* that is `buildHydratedTree`, which takes the registry as an argument and is
+* therefore testable without a bundler.
+*/
+publishRouteTable(pages, "hydration client entry");
+hydratePage(async (payload) => {
+	return createElement(NavigationRoot, {
+		pages,
+		initialPayload: payload,
+		initialTree: await buildHydratedTree(pages, payload),
+		buildTree: buildHydratedTree
+	});
+});
+
+//#endregion
+export {  };
+//# sourceMappingURL=index.mjs.map

package/esm/hydration/index.mjs.map

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

package/esm/hydration-payload.d.mts

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