@warlock.js/web 5.0.0

package/esm/routing/route-identity.mjs

@@ -0,0 +1,68 @@
+//#region ../web/src/routing/route-identity.ts
+/**
+* Raised when a caller passes a `sourceFile` containing a backslash.
+* Canonical means canonical: this module does not normalize Windows path
+* separators on the caller's behalf.
+*/
+var NonPosixSourceFilePathError = class extends Error {
+	sourceFile;
+	constructor(sourceFile) {
+		super(`route-identity: sourceFile "${sourceFile}" contains a backslash. This module's inputs must already be canonical app-root-relative POSIX paths (forward slashes only) — normalize with \`value.replace(/\\\\/g, "/")\` before calling deriveFallbackRouteName.`);
+		this.sourceFile = sourceFile;
+		this.name = "NonPosixSourceFilePathError";
+	}
+};
+/**
+* Canonicalizes a declared `route` export — string or `{ path, name? }` —
+* into `{ path, name? }`. Requires well-formed input; an export that is
+* neither a string nor an object with a `path` is the extractor's problem,
+* already rejected before this function is ever called.
+*/
+function canonicalizeRouteExport(route) {
+	if (typeof route === "string") return { path: route };
+	return route.name === void 0 ? { path: route.path } : {
+		path: route.path,
+		name: route.name
+	};
+}
+/** Strips leading and trailing "." characters — mirrors `trim(value, ".")` as used by the installer's `deriveRouteName`. */
+function trimDots(value) {
+	return value.replace(/^\.+|\.+$/g, "");
+}
+/**
+* The module segment a canonical source path declares, or `undefined` for a
+* global (`src/web/**`) page. `sourceFile` is `<srcDir>/app/<module>/web/...`
+* or `<srcDir>/web/...` — the first segment is the (arbitrarily named) src
+* dir, so the module test looks at the SECOND segment.
+*/
+function moduleSegmentFor(sourceFile) {
+	const segments = sourceFile.split("/");
+	return segments[1] === "app" ? segments[2] : void 0;
+}
+/**
+* Derives the fallback route name for a page whose declared route carries no
+* `name` — the same derivation the dev installer's `deriveRouteName` applies
+* today (`web/src/server/install-page-routes.ts`), expressed against
+* canonical inputs instead of an absolute file path plus an `appSrcRoot`.
+*
+* The installer only ever calls its derivation for a page under
+* `<appSrcRoot>/app/**`, so a global (`src/web/**`) page has no installer
+* behaviour to mirror; for that case this function instead follows
+* discovery's own convention (`routeNameFor` in `discover-pages.ts`) — no
+* module prefix, and `"index"` when there is nothing left to say at all.
+*
+* Throws {@link NonPosixSourceFilePathError} when `sourceFile` contains a
+* backslash.
+*/
+function deriveFallbackRouteName(input) {
+	const { routePath, sourceFile } = input;
+	if (sourceFile.includes("\\")) throw new NonPosixSourceFilePathError(sourceFile);
+	const moduleName = moduleSegmentFor(sourceFile);
+	const suffix = trimDots(routePath.replace(/\//g, "."));
+	if (moduleName !== void 0) return suffix ? `${moduleName}.${suffix}` : moduleName;
+	return suffix || "index";
+}
+
+//#endregion
+export { canonicalizeRouteExport, deriveFallbackRouteName };
+//# sourceMappingURL=route-identity.mjs.map

package/esm/routing/route-identity.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-identity.mjs","names":[],"sources":["../../../../../../../web/src/routing/route-identity.ts"],"sourcesContent":["/**\n * Route identity — the single, pure implementation of \"what is this page's\n * route path and name\". The dev installer\n * (`web/src/server/install-page-routes.ts`), the production manifest\n * installer (`web/src/server/install-page-routes-from-manifest.ts`) and\n * discovery (`web/src/build/discover-pages.ts`) each hand-derived this on\n * their own until all three were made to delegate here.\n *\n * Pure string logic only: no `fs`, no `path`, no Node built-ins. Every input\n * this module accepts is already CANONICAL — a POSIX, app-root-relative\n * source path (e.g. `\"src/app/users/web/account/settings.page.tsx\"` or\n * `\"src/web/index.page.tsx\"`) and an already-validated declared route export.\n * Turning an absolute, OS-specific file path into that canonical form is the\n * caller's job; this module refuses (see {@link NonPosixSourceFilePathError})\n * rather than guess at a normalization.\n *\n * Well-formedness of the declared `route` export itself (is it a string or an\n * object, does the object have a `path`) is the extractor's problem — already\n * rejected at build before either derivation function here is called.\n *\n * DIRECTORY CONTRACT — applies to everything in `web/src/routing/`: nothing\n * here may import `node:fs`, `node:path`, `vite`, or `fastify`. Modules in\n * this directory receive canonical values and trust nothing — they assert\n * rather than trust, but they never repair. A module that needs the\n * filesystem does not belong here. The purity is deliberate: it keeps these\n * modules consumable from the dev server, the build, the production runtime,\n * and — if ever needed — the browser client, without dragging any of those\n * environments along.\n */\n\n/** The shape a page's `route` export may declare — mirrors `PageRouteExport` in `install-page-routes.ts`. */\nexport type DeclaredRouteExport = string | { path: string; name?: string };\n\n/** The canonical form every declared `route` export resolves to. */\nexport type CanonicalRoute = {\n  path: string;\n  name?: string;\n};\n\n/** The canonical inputs {@link deriveFallbackRouteName} requires — see the module doc comment for what \"canonical\" means. */\nexport type RouteNameFallbackInput = {\n  /** The page's declared route path, e.g. `\"/settings\"` or `\"/\"`. */\n  routePath: string;\n  /** The page's app-root-relative POSIX source path, e.g. `\"src/app/main/web/contact-us.page.tsx\"`. */\n  sourceFile: string;\n};\n\n/**\n * Raised when a caller passes a `sourceFile` containing a backslash.\n * Canonical means canonical: this module does not normalize Windows path\n * separators on the caller's behalf.\n */\nexport class NonPosixSourceFilePathError extends Error {\n  public constructor(public readonly sourceFile: string) {\n    super(\n      `route-identity: sourceFile \"${sourceFile}\" contains a backslash. This module's inputs ` +\n        \"must already be canonical app-root-relative POSIX paths (forward slashes only) — \" +\n        'normalize with `value.replace(/\\\\\\\\/g, \"/\")` before calling deriveFallbackRouteName.',\n    );\n    this.name = \"NonPosixSourceFilePathError\";\n  }\n}\n\n/**\n * Canonicalizes a declared `route` export — string or `{ path, name? }` —\n * into `{ path, name? }`. Requires well-formed input; an export that is\n * neither a string nor an object with a `path` is the extractor's problem,\n * already rejected before this function is ever called.\n */\nexport function canonicalizeRouteExport(route: DeclaredRouteExport): CanonicalRoute {\n  if (typeof route === \"string\") {\n    return { path: route };\n  }\n\n  return route.name === undefined ? { path: route.path } : { path: route.path, name: route.name };\n}\n\n/** Strips leading and trailing \".\" characters — mirrors `trim(value, \".\")` as used by the installer's `deriveRouteName`. */\nfunction trimDots(value: string): string {\n  return value.replace(/^\\.+|\\.+$/g, \"\");\n}\n\n/**\n * The module segment a canonical source path declares, or `undefined` for a\n * global (`src/web/**`) page. `sourceFile` is `<srcDir>/app/<module>/web/...`\n * or `<srcDir>/web/...` — the first segment is the (arbitrarily named) src\n * dir, so the module test looks at the SECOND segment.\n */\nfunction moduleSegmentFor(sourceFile: string): string | undefined {\n  const segments = sourceFile.split(\"/\");\n\n  return segments[1] === \"app\" ? segments[2] : undefined;\n}\n\n/**\n * Derives the fallback route name for a page whose declared route carries no\n * `name` — the same derivation the dev installer's `deriveRouteName` applies\n * today (`web/src/server/install-page-routes.ts`), expressed against\n * canonical inputs instead of an absolute file path plus an `appSrcRoot`.\n *\n * The installer only ever calls its derivation for a page under\n * `<appSrcRoot>/app/**`, so a global (`src/web/**`) page has no installer\n * behaviour to mirror; for that case this function instead follows\n * discovery's own convention (`routeNameFor` in `discover-pages.ts`) — no\n * module prefix, and `\"index\"` when there is nothing left to say at all.\n *\n * Throws {@link NonPosixSourceFilePathError} when `sourceFile` contains a\n * backslash.\n */\nexport function deriveFallbackRouteName(input: RouteNameFallbackInput): string {\n  const { routePath, sourceFile } = input;\n\n  if (sourceFile.includes(\"\\\\\")) {\n    throw new NonPosixSourceFilePathError(sourceFile);\n  }\n\n  const moduleName = moduleSegmentFor(sourceFile);\n  const suffix = trimDots(routePath.replace(/\\//g, \".\"));\n\n  if (moduleName !== undefined) {\n    return suffix ? `${moduleName}.${suffix}` : moduleName;\n  }\n\n  return suffix || \"index\";\n}\n"],"mappings":";;;;;;AAoDA,IAAa,8BAAb,cAAiD,MAAM;CAClB;CAAnC,AAAO,YAAY,AAAgB,YAAoB;EACrD,MACE,+BAA+B,WAAW,qNAG5C;EALiC;EAMjC,KAAK,OAAO;CACd;AACF;;;;;;;AAQA,SAAgB,wBAAwB,OAA4C;CAClF,IAAI,OAAO,UAAU,UACnB,OAAO,EAAE,MAAM,MAAM;CAGvB,OAAO,MAAM,SAAS,SAAY,EAAE,MAAM,MAAM,KAAK,IAAI;EAAE,MAAM,MAAM;EAAM,MAAM,MAAM;CAAK;AAChG;;AAGA,SAAS,SAAS,OAAuB;CACvC,OAAO,MAAM,QAAQ,cAAc,EAAE;AACvC;;;;;;;AAQA,SAAS,iBAAiB,YAAwC;CAChE,MAAM,WAAW,WAAW,MAAM,GAAG;CAErC,OAAO,SAAS,OAAO,QAAQ,SAAS,KAAK;AAC/C;;;;;;;;;;;;;;;;AAiBA,SAAgB,wBAAwB,OAAuC;CAC7E,MAAM,EAAE,WAAW,eAAe;CAElC,IAAI,WAAW,SAAS,IAAI,GAC1B,MAAM,IAAI,4BAA4B,UAAU;CAGlD,MAAM,aAAa,iBAAiB,UAAU;CAC9C,MAAM,SAAS,SAAS,UAAU,QAAQ,OAAO,GAAG,CAAC;CAErD,IAAI,eAAe,QACjB,OAAO,SAAS,GAAG,WAAW,GAAG,WAAW;CAG9C,OAAO,UAAU;AACnB"}

package/esm/routing/route-table.d.mts

@@ -0,0 +1,34 @@
+import { QueryStringInput } from "./query-string.mjs";
+
+//#region ../web/src/routing/route-table.d.ts
+/** What `href` accepts for a `:param` segment. Rendered with `String(value)`. */
+type RouteParameters = Readonly<Record<string, unknown>>;
+/**
+ * Query values; an `undefined` value is omitted rather than serialized.
+ *
+ * A value may be a scalar, an array of scalars, or an object one level deep —
+ * the shapes `@warlock.js/core` parses back out of the URL. Anything deeper
+ * throws `UnserializableQueryValueError`; the grammar and the measurements
+ * behind it are documented in query-string.ts.
+ */
+type RouteQuery = QueryStringInput;
+/**
+ * Resolve a route NAME to a URL.
+ *
+ * A name, never a path: a moved page changes its URL and keeps its name, so
+ * every call site keeps working. That is the property the hardcoded table in
+ * the previous `<Link>` could not offer, because it restated six URLs by hand
+ * and silently refused every other page in the app.
+ *
+ * The query half is delegated to `queryStringOf`, which lives next to the
+ * DECODER it has to agree with. It used to live here, and being module-private
+ * meant the read half could not share it — the one-writer rule held only
+ * because nobody had written the second writer yet.
+ *
+ * @throws {UnserializableQueryValueError} when a query value nests deeper than
+ * the wire format core parses can carry.
+ */
+declare function href(name: string, params?: RouteParameters, query?: RouteQuery): string;
+//#endregion
+export { RouteParameters, RouteQuery, href };
+//# sourceMappingURL=route-table.d.mts.map

package/esm/routing/route-table.mjs

@@ -0,0 +1,182 @@
+import { queryStringOf } from "./query-string.mjs";
+
+//#region ../web/src/routing/route-table.ts
+/**
+* The name→URL primitive, and the one route table both sides read.
+*
+* `href(name, params, query)` is the DURABLE primitive; `<Link>` is sugar over
+* it. That ordering is deliberate and ratified: a function serves emails,
+* redirects, `Location` headers and non-React callers, none of which can render
+* a component — and it keeps client-side navigation, when it lands, a behaviour
+* change rather than an API change.
+*
+* ── Why a process-global table is correct HERE ───────────────────────────────
+* Module-level mutable state is normally a defect in a server that handles
+* concurrent requests, and this codebase has a real example of that defect to
+* point at: `@mongez/react-router`'s `RouterWrapper` keeps the RENDERED PAGE
+* CONTENT in a module-level binding, so request B overwrites the tree request A
+* is about to serialize. That is why it is not on the SSR path.
+*
+* A route table is the opposite kind of value. It is derived from the file
+* system at boot, identical for every request in the process, and never written
+* during a request — the same category as the compiled route table the server's
+* own router holds. Nothing here is per-request, so there is nothing for two
+* requests to race over.
+*
+* The rule that keeps it that way: `publishRouteTable` is called at INSTALL
+* time (server) or at hydration entry (browser), and never from a loader, a
+* middleware, or a component.
+*/
+const PARAMETER_PATTERN = /:([A-Za-z0-9_]+)|\*/g;
+/**
+* ── WHY THIS LIVES ON `globalThis` AND NOT IN A MODULE BINDING ───────────────
+*
+* A plain `let` here does not work in development, and the failure is silent
+* enough to be worth spelling out.
+*
+* In dev the process runs TWO module graphs over the same files. Route
+* installation is loaded by tsx/Node (it is CLI bootstrap and imports core
+* directly), while page and layout modules are evaluated by Vite's SSR module
+* runner — which keeps its own registry and its own instance of every module it
+* transforms, `@warlock.js/web` included. So a module-level binding written by
+* the installer is not the binding `<Link>` reads during render: the installer
+* publishes into one instance and the component finds the other one empty.
+*
+* That was measured, not theorised. With a module-level `let`, every anchor on
+* a server-rendered page threw `RouteTableNotPublishedError` with an empty
+* known-names list while installation had demonstrably run.
+*
+* `Symbol.for` resolves through the per-ISOLATE symbol registry, which both
+* graphs share because they are the same isolate. So the table is one value no
+* matter which graph reaches it first, and the module keeps its module-shaped
+* API. `publishedBy` is carried for diagnosis only.
+*/
+const ROUTE_TABLE_SLOT = Symbol.for("warlock.web.routeTable");
+/**
+* `undefined` means "nobody has published yet", which is a DIFFERENT fault from
+* "the table is published and this name is not in it" — an empty Map would
+* conflate them and send the reader hunting a route that was never missing.
+*/
+function readSlot() {
+	return globalThis[ROUTE_TABLE_SLOT];
+}
+var RouteTableNotPublishedError = class extends Error {
+	routeName;
+	constructor(routeName) {
+		super(`Warlock href(${JSON.stringify(routeName)}) was called before the route table was published, so no route name resolves yet. The table is published once at boot — by the server when it installs page routes, and by the hydration entry before it mounts. Seeing this means href() ran outside both: typically a module evaluating at import time, or a unit test that renders a component without publishing a table first.`);
+		this.routeName = routeName;
+		this.name = "RouteTableNotPublishedError";
+	}
+};
+var UnknownRouteNameError = class extends Error {
+	routeName;
+	knownRouteNames;
+	constructor(routeName, knownRouteNames) {
+		super(`Warlock href(${JSON.stringify(routeName)}) does not name a known route. ` + (knownRouteNames.length === 0 ? "The route table is published but empty, so no page declared a `route` discovery could see." : `The table knows: ${knownRouteNames.map((name) => JSON.stringify(name)).join(", ")}.`));
+		this.routeName = routeName;
+		this.knownRouteNames = knownRouteNames;
+		this.name = "UnknownRouteNameError";
+	}
+};
+var MissingRouteParameterError = class extends Error {
+	routeName;
+	parameterName;
+	routePath;
+	constructor(routeName, parameterName, routePath) {
+		super(`Warlock href(${JSON.stringify(routeName)}) is missing the parameter ${JSON.stringify(parameterName)}, required by the route path "${routePath}". It is not defaulted: a missing parameter would otherwise be interpolated as the literal text \`undefined\`, producing a link that renders correctly and 404s for a visitor.`);
+		this.routeName = routeName;
+		this.parameterName = parameterName;
+		this.routePath = routePath;
+		this.name = "MissingRouteParameterError";
+	}
+};
+var UnknownRouteParameterError = class extends Error {
+	routeName;
+	parameterNames;
+	routePath;
+	constructor(routeName, parameterNames, routePath) {
+		super(`Warlock href(${JSON.stringify(routeName)}) was given ${parameterNames.map((name) => JSON.stringify(name)).join(", ")}, which the route path "${routePath}" does not declare. Passing an undeclared parameter is a typo often enough that it is refused rather than dropped; values meant for the query string go in the third argument.`);
+		this.routeName = routeName;
+		this.parameterNames = parameterNames;
+		this.routePath = routePath;
+		this.name = "UnknownRouteParameterError";
+	}
+};
+var DuplicateRouteNameError = class extends Error {
+	routeName;
+	paths;
+	constructor(routeName, paths) {
+		super(`Warlock route table: two routes both claim the name ${JSON.stringify(routeName)} — "${paths[0]}" and "${paths[1]}". A name resolves to exactly one URL, so one of the two would silently win and every link to it would be wrong half the time.`);
+		this.routeName = routeName;
+		this.paths = paths;
+		this.name = "DuplicateRouteNameError";
+	}
+};
+/**
+* Publish the table. WHOLESALE — the previous one is discarded, not merged
+* into.
+*
+* Merging looks harmless until a page is deleted and the dev server restarts:
+* the dead name would stay resolvable, and `<Link>` would go on rendering a URL
+* the server no longer routes. The table has to be able to shrink.
+*/
+function publishRouteTable(entries, publishedBy = "unnamed") {
+	const table = /* @__PURE__ */ new Map();
+	for (const entry of entries) {
+		const existing = table.get(entry.name);
+		if (existing !== void 0) throw new DuplicateRouteNameError(entry.name, [existing, entry.path]);
+		table.set(entry.name, entry.path);
+	}
+	globalThis[ROUTE_TABLE_SLOT] = {
+		table,
+		publishedBy
+	};
+}
+/** The published names, for diagnostics. Empty when nothing is published. */
+function knownRouteNames() {
+	const slot = readSlot();
+	return slot === void 0 ? [] : [...slot.table.keys()];
+}
+function parameterNamesOf(routePath) {
+	const names = [];
+	for (const match of routePath.matchAll(PARAMETER_PATTERN)) names.push(match[1] ?? "*");
+	return names;
+}
+function interpolate(routeName, routePath, params) {
+	const declared = parameterNamesOf(routePath);
+	const undeclared = Object.keys(params ?? {}).filter((key) => params?.[key] !== void 0).filter((key) => !declared.includes(key));
+	if (undeclared.length > 0) throw new UnknownRouteParameterError(routeName, undeclared, routePath);
+	return routePath.replace(PARAMETER_PATTERN, (match) => {
+		const name = match === "*" ? "*" : match.slice(1);
+		const value = params?.[name];
+		if (value === void 0) throw new MissingRouteParameterError(routeName, name, routePath);
+		return encodeURIComponent(String(value));
+	});
+}
+/**
+* Resolve a route NAME to a URL.
+*
+* A name, never a path: a moved page changes its URL and keeps its name, so
+* every call site keeps working. That is the property the hardcoded table in
+* the previous `<Link>` could not offer, because it restated six URLs by hand
+* and silently refused every other page in the app.
+*
+* The query half is delegated to `queryStringOf`, which lives next to the
+* DECODER it has to agree with. It used to live here, and being module-private
+* meant the read half could not share it — the one-writer rule held only
+* because nobody had written the second writer yet.
+*
+* @throws {UnserializableQueryValueError} when a query value nests deeper than
+* the wire format core parses can carry.
+*/
+function href(name, params, query) {
+	const slot = readSlot();
+	if (slot === void 0) throw new RouteTableNotPublishedError(name);
+	const routePath = slot.table.get(name);
+	if (routePath === void 0) throw new UnknownRouteNameError(name, [...slot.table.keys()]);
+	return `${interpolate(name, routePath, params)}${queryStringOf(query)}`;
+}
+
+//#endregion
+export { href, knownRouteNames, publishRouteTable };
+//# sourceMappingURL=route-table.mjs.map

package/esm/routing/route-table.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-table.mjs","names":[],"sources":["../../../../../../../web/src/routing/route-table.ts"],"sourcesContent":["/**\n * The name→URL primitive, and the one route table both sides read.\n *\n * `href(name, params, query)` is the DURABLE primitive; `<Link>` is sugar over\n * it. That ordering is deliberate and ratified: a function serves emails,\n * redirects, `Location` headers and non-React callers, none of which can render\n * a component — and it keeps client-side navigation, when it lands, a behaviour\n * change rather than an API change.\n *\n * ── Why a process-global table is correct HERE ───────────────────────────────\n * Module-level mutable state is normally a defect in a server that handles\n * concurrent requests, and this codebase has a real example of that defect to\n * point at: `@mongez/react-router`'s `RouterWrapper` keeps the RENDERED PAGE\n * CONTENT in a module-level binding, so request B overwrites the tree request A\n * is about to serialize. That is why it is not on the SSR path.\n *\n * A route table is the opposite kind of value. It is derived from the file\n * system at boot, identical for every request in the process, and never written\n * during a request — the same category as the compiled route table the server's\n * own router holds. Nothing here is per-request, so there is nothing for two\n * requests to race over.\n *\n * The rule that keeps it that way: `publishRouteTable` is called at INSTALL\n * time (server) or at hydration entry (browser), and never from a loader, a\n * middleware, or a component.\n */\n\nimport { queryStringOf, type QueryStringInput } from \"./query-string\";\n\n/** The two fields `href` needs. Callers may pass richer entries; the rest is ignored. */\nexport type RouteTableEntry = {\n  readonly name: string;\n  readonly path: string;\n};\n\n/** What `href` accepts for a `:param` segment. Rendered with `String(value)`. */\nexport type RouteParameters = Readonly<Record<string, unknown>>;\n\n/**\n * Query values; an `undefined` value is omitted rather than serialized.\n *\n * A value may be a scalar, an array of scalars, or an object one level deep —\n * the shapes `@warlock.js/core` parses back out of the URL. Anything deeper\n * throws `UnserializableQueryValueError`; the grammar and the measurements\n * behind it are documented in query-string.ts.\n */\nexport type RouteQuery = QueryStringInput;\n\nconst PARAMETER_PATTERN = /:([A-Za-z0-9_]+)|\\*/g;\n\n/**\n * ── WHY THIS LIVES ON `globalThis` AND NOT IN A MODULE BINDING ───────────────\n *\n * A plain `let` here does not work in development, and the failure is silent\n * enough to be worth spelling out.\n *\n * In dev the process runs TWO module graphs over the same files. Route\n * installation is loaded by tsx/Node (it is CLI bootstrap and imports core\n * directly), while page and layout modules are evaluated by Vite's SSR module\n * runner — which keeps its own registry and its own instance of every module it\n * transforms, `@warlock.js/web` included. So a module-level binding written by\n * the installer is not the binding `<Link>` reads during render: the installer\n * publishes into one instance and the component finds the other one empty.\n *\n * That was measured, not theorised. With a module-level `let`, every anchor on\n * a server-rendered page threw `RouteTableNotPublishedError` with an empty\n * known-names list while installation had demonstrably run.\n *\n * `Symbol.for` resolves through the per-ISOLATE symbol registry, which both\n * graphs share because they are the same isolate. So the table is one value no\n * matter which graph reaches it first, and the module keeps its module-shaped\n * API. `publishedBy` is carried for diagnosis only.\n */\nconst ROUTE_TABLE_SLOT = Symbol.for(\"warlock.web.routeTable\");\n\ntype RouteTableSlot = {\n  table: Map<string, string>;\n  publishedBy: string;\n};\n\ntype RouteTableHost = typeof globalThis & {\n  [ROUTE_TABLE_SLOT]?: RouteTableSlot;\n};\n\n/**\n * `undefined` means \"nobody has published yet\", which is a DIFFERENT fault from\n * \"the table is published and this name is not in it\" — an empty Map would\n * conflate them and send the reader hunting a route that was never missing.\n */\nfunction readSlot(): RouteTableSlot | undefined {\n  return (globalThis as RouteTableHost)[ROUTE_TABLE_SLOT];\n}\n\nexport class RouteTableNotPublishedError extends Error {\n  public constructor(public readonly routeName: string) {\n    super(\n      `Warlock href(${JSON.stringify(routeName)}) was called before the route table was ` +\n        \"published, so no route name resolves yet. The table is published once at boot — by \" +\n        \"the server when it installs page routes, and by the hydration entry before it mounts. \" +\n        \"Seeing this means href() ran outside both: typically a module evaluating at import \" +\n        \"time, or a unit test that renders a component without publishing a table first.\",\n    );\n    this.name = \"RouteTableNotPublishedError\";\n  }\n}\n\nexport class UnknownRouteNameError extends Error {\n  public constructor(\n    public readonly routeName: string,\n    public readonly knownRouteNames: readonly string[],\n  ) {\n    super(\n      `Warlock href(${JSON.stringify(routeName)}) does not name a known route. ` +\n        (knownRouteNames.length === 0\n          ? \"The route table is published but empty, so no page declared a `route` discovery could see.\"\n          : `The table knows: ${knownRouteNames.map(name => JSON.stringify(name)).join(\", \")}.`),\n    );\n    this.name = \"UnknownRouteNameError\";\n  }\n}\n\nexport class MissingRouteParameterError extends Error {\n  public constructor(\n    public readonly routeName: string,\n    public readonly parameterName: string,\n    public readonly routePath: string,\n  ) {\n    super(\n      `Warlock href(${JSON.stringify(routeName)}) is missing the parameter ` +\n        `${JSON.stringify(parameterName)}, required by the route path \"${routePath}\". ` +\n        \"It is not defaulted: a missing parameter would otherwise be interpolated as the \" +\n        \"literal text `undefined`, producing a link that renders correctly and 404s for a \" +\n        \"visitor.\",\n    );\n    this.name = \"MissingRouteParameterError\";\n  }\n}\n\nexport class UnknownRouteParameterError extends Error {\n  public constructor(\n    public readonly routeName: string,\n    public readonly parameterNames: readonly string[],\n    public readonly routePath: string,\n  ) {\n    super(\n      `Warlock href(${JSON.stringify(routeName)}) was given ` +\n        `${parameterNames.map(name => JSON.stringify(name)).join(\", \")}, which the route path ` +\n        `\"${routePath}\" does not declare. Passing an undeclared parameter is a typo often ` +\n        \"enough that it is refused rather than dropped; values meant for the query string go \" +\n        \"in the third argument.\",\n    );\n    this.name = \"UnknownRouteParameterError\";\n  }\n}\n\nexport class DuplicateRouteNameError extends Error {\n  public constructor(\n    public readonly routeName: string,\n    public readonly paths: readonly [string, string],\n  ) {\n    super(\n      `Warlock route table: two routes both claim the name ${JSON.stringify(routeName)} — ` +\n        `\"${paths[0]}\" and \"${paths[1]}\". A name resolves to exactly one URL, so one of the ` +\n        \"two would silently win and every link to it would be wrong half the time.\",\n    );\n    this.name = \"DuplicateRouteNameError\";\n  }\n}\n\n/**\n * Publish the table. WHOLESALE — the previous one is discarded, not merged\n * into.\n *\n * Merging looks harmless until a page is deleted and the dev server restarts:\n * the dead name would stay resolvable, and `<Link>` would go on rendering a URL\n * the server no longer routes. The table has to be able to shrink.\n */\nexport function publishRouteTable(\n  entries: readonly RouteTableEntry[],\n  publishedBy = \"unnamed\",\n): void {\n  const table = new Map<string, string>();\n\n  for (const entry of entries) {\n    const existing = table.get(entry.name);\n\n    if (existing !== undefined) {\n      throw new DuplicateRouteNameError(entry.name, [existing, entry.path]);\n    }\n\n    table.set(entry.name, entry.path);\n  }\n\n  (globalThis as RouteTableHost)[ROUTE_TABLE_SLOT] = { table, publishedBy };\n}\n\n/**\n * Drop the table, returning the module to its pre-boot state.\n *\n * Exists for tests: the table is process-global, so a suite that published one\n * would otherwise leak it into every later test in the same worker and pass in\n * file order while failing under `--shuffle`.\n */\nexport function resetRouteTable(): void {\n  delete (globalThis as RouteTableHost)[ROUTE_TABLE_SLOT];\n}\n\n/** The published names, for diagnostics. Empty when nothing is published. */\nexport function knownRouteNames(): readonly string[] {\n  const slot = readSlot();\n\n  return slot === undefined ? [] : [...slot.table.keys()];\n}\n\n/** Who published the live table, for diagnosis. `undefined` when nothing has. */\nexport function routeTablePublisher(): string | undefined {\n  return readSlot()?.publishedBy;\n}\n\nfunction parameterNamesOf(routePath: string): readonly string[] {\n  const names: string[] = [];\n\n  for (const match of routePath.matchAll(PARAMETER_PATTERN)) {\n    names.push(match[1] ?? \"*\");\n  }\n\n  return names;\n}\n\nfunction interpolate(\n  routeName: string,\n  routePath: string,\n  params: RouteParameters | undefined,\n): string {\n  const declared = parameterNamesOf(routePath);\n  const supplied = Object.keys(params ?? {}).filter(key => params?.[key] !== undefined);\n  const undeclared = supplied.filter(key => !declared.includes(key));\n\n  if (undeclared.length > 0) {\n    throw new UnknownRouteParameterError(routeName, undeclared, routePath);\n  }\n\n  return routePath.replace(PARAMETER_PATTERN, match => {\n    const name = match === \"*\" ? \"*\" : match.slice(1);\n    const value = params?.[name];\n\n    if (value === undefined) {\n      throw new MissingRouteParameterError(routeName, name, routePath);\n    }\n\n    return encodeURIComponent(String(value));\n  });\n}\n\n/**\n * Resolve a route NAME to a URL.\n *\n * A name, never a path: a moved page changes its URL and keeps its name, so\n * every call site keeps working. That is the property the hardcoded table in\n * the previous `<Link>` could not offer, because it restated six URLs by hand\n * and silently refused every other page in the app.\n *\n * The query half is delegated to `queryStringOf`, which lives next to the\n * DECODER it has to agree with. It used to live here, and being module-private\n * meant the read half could not share it — the one-writer rule held only\n * because nobody had written the second writer yet.\n *\n * @throws {UnserializableQueryValueError} when a query value nests deeper than\n * the wire format core parses can carry.\n */\nexport function href(\n  name: string,\n  params?: RouteParameters,\n  query?: RouteQuery,\n): string {\n  const slot = readSlot();\n\n  if (slot === undefined) throw new RouteTableNotPublishedError(name);\n\n  const routePath = slot.table.get(name);\n\n  if (routePath === undefined) {\n    throw new UnknownRouteNameError(name, [...slot.table.keys()]);\n  }\n\n  return `${interpolate(name, routePath, params)}${queryStringOf(query)}`;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgDA,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;AAyB1B,MAAM,mBAAmB,OAAO,IAAI,wBAAwB;;;;;;AAgB5D,SAAS,WAAuC;CAC9C,OAAQ,WAA8B;AACxC;AAEA,IAAa,8BAAb,cAAiD,MAAM;CAClB;CAAnC,AAAO,YAAY,AAAgB,WAAmB;EACpD,MACE,gBAAgB,KAAK,UAAU,SAAS,EAAE,oXAK5C;EAPiC;EAQjC,KAAK,OAAO;CACd;AACF;AAEA,IAAa,wBAAb,cAA2C,MAAM;CAE7B;CACA;CAFlB,AAAO,YACL,AAAgB,WAChB,AAAgB,iBAChB;EACA,MACE,gBAAgB,KAAK,UAAU,SAAS,EAAE,oCACvC,gBAAgB,WAAW,IACxB,+FACA,oBAAoB,gBAAgB,KAAI,SAAQ,KAAK,UAAU,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,GACzF;EARgB;EACA;EAQhB,KAAK,OAAO;CACd;AACF;AAEA,IAAa,6BAAb,cAAgD,MAAM;CAElC;CACA;CACA;CAHlB,AAAO,YACL,AAAgB,WAChB,AAAgB,eAChB,AAAgB,WAChB;EACA,MACE,gBAAgB,KAAK,UAAU,SAAS,EAAE,6BACrC,KAAK,UAAU,aAAa,EAAE,gCAAgC,UAAU,+KAI/E;EAVgB;EACA;EACA;EAShB,KAAK,OAAO;CACd;AACF;AAEA,IAAa,6BAAb,cAAgD,MAAM;CAElC;CACA;CACA;CAHlB,AAAO,YACL,AAAgB,WAChB,AAAgB,gBAChB,AAAgB,WAChB;EACA,MACE,gBAAgB,KAAK,UAAU,SAAS,EAAE,cACrC,eAAe,KAAI,SAAQ,KAAK,UAAU,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,0BAC3D,UAAU,+KAGlB;EAVgB;EACA;EACA;EAShB,KAAK,OAAO;CACd;AACF;AAEA,IAAa,0BAAb,cAA6C,MAAM;CAE/B;CACA;CAFlB,AAAO,YACL,AAAgB,WAChB,AAAgB,OAChB;EACA,MACE,uDAAuD,KAAK,UAAU,SAAS,EAAE,MAC3E,MAAM,GAAG,SAAS,MAAM,GAAG,+HAEnC;EAPgB;EACA;EAOhB,KAAK,OAAO;CACd;AACF;;;;;;;;;AAUA,SAAgB,kBACd,SACA,cAAc,WACR;CACN,MAAM,wBAAQ,IAAI,IAAoB;CAEtC,KAAK,MAAM,SAAS,SAAS;EAC3B,MAAM,WAAW,MAAM,IAAI,MAAM,IAAI;EAErC,IAAI,aAAa,QACf,MAAM,IAAI,wBAAwB,MAAM,MAAM,CAAC,UAAU,MAAM,IAAI,CAAC;EAGtE,MAAM,IAAI,MAAM,MAAM,MAAM,IAAI;CAClC;CAEA,AAAC,WAA8B,oBAAoB;EAAE;EAAO;CAAY;AAC1E;;AAcA,SAAgB,kBAAqC;CACnD,MAAM,OAAO,SAAS;CAEtB,OAAO,SAAS,SAAY,CAAC,IAAI,CAAC,GAAG,KAAK,MAAM,KAAK,CAAC;AACxD;AAOA,SAAS,iBAAiB,WAAsC;CAC9D,MAAM,QAAkB,CAAC;CAEzB,KAAK,MAAM,SAAS,UAAU,SAAS,iBAAiB,GACtD,MAAM,KAAK,MAAM,MAAM,GAAG;CAG5B,OAAO;AACT;AAEA,SAAS,YACP,WACA,WACA,QACQ;CACR,MAAM,WAAW,iBAAiB,SAAS;CAE3C,MAAM,aADW,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,CAAC,QAAO,QAAO,SAAS,SAAS,MACjD,CAAC,CAAC,QAAO,QAAO,CAAC,SAAS,SAAS,GAAG,CAAC;CAEjE,IAAI,WAAW,SAAS,GACtB,MAAM,IAAI,2BAA2B,WAAW,YAAY,SAAS;CAGvE,OAAO,UAAU,QAAQ,oBAAmB,UAAS;EACnD,MAAM,OAAO,UAAU,MAAM,MAAM,MAAM,MAAM,CAAC;EAChD,MAAM,QAAQ,SAAS;EAEvB,IAAI,UAAU,QACZ,MAAM,IAAI,2BAA2B,WAAW,MAAM,SAAS;EAGjE,OAAO,mBAAmB,OAAO,KAAK,CAAC;CACzC,CAAC;AACH;;;;;;;;;;;;;;;;;AAkBA,SAAgB,KACd,MACA,QACA,OACQ;CACR,MAAM,OAAO,SAAS;CAEtB,IAAI,SAAS,QAAW,MAAM,IAAI,4BAA4B,IAAI;CAElE,MAAM,YAAY,KAAK,MAAM,IAAI,IAAI;CAErC,IAAI,cAAc,QAChB,MAAM,IAAI,sBAAsB,MAAM,CAAC,GAAG,KAAK,MAAM,KAAK,CAAC,CAAC;CAG9D,OAAO,GAAG,YAAY,MAAM,WAAW,MAAM,IAAI,cAAc,KAAK;AACtE"}

package/esm/routing/router-events.d.mts

@@ -0,0 +1,159 @@
+//#region ../web/src/routing/router-events.d.ts
+/**
+ * The navigation lifecycle emitter — what a progress bar subscribes to.
+ *
+ * A client navigation is a fetch followed by a tree swap
+ * (`client/navigation/navigation-root.tsx`). Nothing about that is visible to
+ * the user while it is in flight, which is the whole reason this module
+ * exists: a progress bar, an analytics hook or a scroll restorer needs to know
+ * that a navigation STARTED, that it FINISHED, and that it FAILED — and none
+ * of them should have to reach into the navigation runtime to find out.
+ *
+ * So the runtime announces, and anyone may listen. The listeners are strangers
+ * to each other and to the runtime; that is the point.
+ *
+ * ## This module ships the emitter only
+ *
+ * Nothing here is wired into the navigation runtime yet — `navigation-root.tsx`
+ * calls the `emit*` methods in a later change. Until then this is a complete,
+ * self-contained emitter with no callers, which is why it has no dependency on
+ * anything in `client/`.
+ *
+ * ## What it deliberately does NOT do
+ *
+ * It carries URLs as OPAQUE STRINGS. There is no matching, no parsing, no
+ * "which route is this" — Warlock's server router is the only matcher (canon
+ * 9c8f878b), and an emitter that started parsing paths would be a second one.
+ * A listener that wants a route name gets it from the payload the navigation
+ * produced, not from this module.
+ *
+ * DIRECTORY CONTRACT — see `route-identity.ts`: nothing in `web/src/routing/`
+ * may import `node:fs`, `node:path`, `vite` or `fastify`. This module also
+ * touches no DOM global, which is what makes it importable from a server
+ * render (see below).
+ *
+ * ## Named for its ancestor
+ *
+ * `routerEvents` is the name `@mongez/react-router` used
+ * (`@mongez/react-router/src/events.ts`), and the subscription ergonomics are
+ * deliberately familiar: `routerEvents.onNavigating(callback)` returns
+ * something you call to stop listening. The implementation is NOT ported —
+ * MRR's delegates to a global `@mongez/events` bus keyed by string
+ * (`"router.navigating"`), which reaches its router singleton and gives up
+ * per-event payload typing in the process. Here the events are the object's
+ * own methods, so each one carries its own payload type and a typo is a
+ * compile error rather than a listener that never fires.
+ *
+ * MRR returns an `EventSubscription` object; this returns the unsubscribe
+ * FUNCTION itself, because that is what a React `useEffect` cleanup wants to
+ * be handed:
+ *
+ * ```ts
+ * useEffect(() => routerEvents.onNavigating(() => setLoading(true)), []);
+ * ```
+ */
+/**
+ * How the navigation will be written to browser history.
+ *
+ * `"replace"` covers both an explicit `<Link replace>` and a Back/Forward
+ * press — the runtime replaces in both cases, because the history entry
+ * already exists. A listener that wants to stay quiet during Back/Forward
+ * cannot tell the two apart from here, and does not need to: what it actually
+ * cares about is that no new entry is being pushed.
+ */
+type NavigationMode = "push" | "replace";
+/** Emitted when a navigation begins — before anything has been fetched. */
+type NavigationStartPayload = {
+  /** The URL the navigation was requested for, verbatim and unparsed. */url: string;
+  mode: NavigationMode;
+};
+/** Emitted when a navigation has completed and the new page is on screen. */
+type NavigationEndPayload = {
+  /** The URL the navigation was requested for — the same string {@link NavigationStartPayload} carried. */url: string;
+  /**
+   * The URL the page data actually came from, which is what landed in the
+   * address bar. It differs from `url` whenever the server redirected — a
+   * page that requires auth answers from `/login` (see
+   * `client/navigation/fetch-page-data.ts`).
+   */
+  resolvedUrl: string;
+  mode: NavigationMode;
+};
+/**
+ * Emitted when a navigation could not complete.
+ *
+ * A failed client navigation is not a dead end — the runtime degrades to a
+ * full browser load — so a listener should treat this as "the in-flight
+ * navigation is over", not as an error to render. A progress bar hides on it.
+ */
+type NavigationErrorPayload = {
+  /** The URL the navigation was requested for. */url: string;
+  mode: NavigationMode;
+  /**
+   * What went wrong. `unknown` rather than `Error` because a caught value has
+   * no such guarantee — narrow it before reading `.message`.
+   */
+  error: unknown;
+};
+/** A listener for one navigation event. Its return value is ignored. */
+type RouterEventListener<Payload> = (payload: Payload) => void;
+/** Call it to stop listening. Calling it more than once is a no-op. */
+type RouterEventUnsubscribe = () => void;
+/**
+ * The navigation lifecycle surface: three events, each with its own payload
+ * type, each subscribable and emittable.
+ *
+ * The `emit*` half belongs to the navigation runtime. Nothing stops other code
+ * from calling it, and nothing needs to — an emitter that lies about
+ * navigations is a bug in whoever called it, not a boundary worth policing.
+ */
+type RouterEvents = {
+  /** Subscribe to the start of every navigation. @returns the unsubscribe function. */onNavigating: (listener: RouterEventListener<NavigationStartPayload>) => RouterEventUnsubscribe; /** Subscribe to every navigation that completed. @returns the unsubscribe function. */
+  onNavigated: (listener: RouterEventListener<NavigationEndPayload>) => RouterEventUnsubscribe; /** Subscribe to every navigation that failed. @returns the unsubscribe function. */
+  onNavigationError: (listener: RouterEventListener<NavigationErrorPayload>) => RouterEventUnsubscribe; /** Announce that a navigation has begun. Called by the navigation runtime. */
+  emitNavigating: (payload: NavigationStartPayload) => void; /** Announce that a navigation has completed. Called by the navigation runtime. */
+  emitNavigated: (payload: NavigationEndPayload) => void; /** Announce that a navigation has failed. Called by the navigation runtime. */
+  emitNavigationError: (payload: NavigationErrorPayload) => void;
+};
+/**
+ * Builds an independent emitter with no listeners.
+ *
+ * This is what makes the module TESTABLE without cross-test bleed, and it is
+ * the escape hatch for anything that needs a private lifecycle bus. The
+ * shared {@link routerEvents} is one of these, created once.
+ */
+declare function createRouterEvents(): RouterEvents;
+/**
+ * The shared navigation lifecycle emitter — the one a progress bar subscribes
+ * to and the one the navigation runtime emits on.
+ *
+ * ## Why a module-level singleton is safe here, when module-level state is a known SSR hazard
+ *
+ * Canon records MRR's `RouterWrapper.tsx:63` as the cautionary case: module
+ * state that holds RENDER state is shared by every concurrent request on the
+ * server, so one visitor's page leaks into another's. That hazard is about
+ * *what* is held, not about module scope itself — `routing/navigator.ts` in
+ * this same directory already holds a module-level registration for the same
+ * reason.
+ *
+ * This object holds ONLY listener registrations. No current route, no payload,
+ * no request-scoped anything — nothing a render reads and nothing a response
+ * is built from. Two concurrent SSR requests observe the same empty listener
+ * sets and neither can learn a thing about the other.
+ *
+ * It is also safe to IMPORT on the server: constructing it touches no DOM
+ * global, no `window`, no `history`, and performs no work beyond allocating
+ * three empty sets. On the server nothing subscribes and nothing emits, so it
+ * simply sits there — which is the correct server behaviour for a progress
+ * bar.
+ *
+ * A singleton (rather than a context or a factory at the call site) is what
+ * lets a progress bar living anywhere in the tree — or outside React
+ * entirely — hear a navigation without being handed a bus by every component
+ * between it and the root. That plumbing is the reason MRR made this global
+ * too. Use {@link createRouterEvents} when you want an isolated one.
+ */
+declare const routerEvents: RouterEvents;
+//#endregion
+export { NavigationEndPayload, NavigationErrorPayload, NavigationStartPayload, createRouterEvents, routerEvents };
+//# sourceMappingURL=router-events.d.mts.map

package/esm/routing/router-events.mjs

@@ -0,0 +1,83 @@
+//#region ../web/src/routing/router-events.ts
+/**
+* One event's registrations and its delivery loop. A `Set` because insertion
+* order is preserved (listeners fire in subscription order) and removal is by
+* identity, which is exactly what an unsubscribe closure holds.
+*/
+function createSignal(eventName) {
+	const registrations = /* @__PURE__ */ new Set();
+	return {
+		subscribe: (listener) => {
+			const registration = { listener };
+			registrations.add(registration);
+			return () => {
+				registrations.delete(registration);
+			};
+		},
+		emit: (payload) => {
+			for (const registration of [...registrations]) {
+				if (!registrations.has(registration)) continue;
+				try {
+					registration.listener(payload);
+				} catch (error) {
+					console.error(`Warlock routerEvents: a ${eventName} listener threw:`, error);
+				}
+			}
+		}
+	};
+}
+/**
+* Builds an independent emitter with no listeners.
+*
+* This is what makes the module TESTABLE without cross-test bleed, and it is
+* the escape hatch for anything that needs a private lifecycle bus. The
+* shared {@link routerEvents} is one of these, created once.
+*/
+function createRouterEvents() {
+	const navigating = createSignal("navigating");
+	const navigated = createSignal("navigated");
+	const navigationError = createSignal("navigation-error");
+	return {
+		onNavigating: navigating.subscribe,
+		onNavigated: navigated.subscribe,
+		onNavigationError: navigationError.subscribe,
+		emitNavigating: navigating.emit,
+		emitNavigated: navigated.emit,
+		emitNavigationError: navigationError.emit
+	};
+}
+/**
+* The shared navigation lifecycle emitter — the one a progress bar subscribes
+* to and the one the navigation runtime emits on.
+*
+* ## Why a module-level singleton is safe here, when module-level state is a known SSR hazard
+*
+* Canon records MRR's `RouterWrapper.tsx:63` as the cautionary case: module
+* state that holds RENDER state is shared by every concurrent request on the
+* server, so one visitor's page leaks into another's. That hazard is about
+* *what* is held, not about module scope itself — `routing/navigator.ts` in
+* this same directory already holds a module-level registration for the same
+* reason.
+*
+* This object holds ONLY listener registrations. No current route, no payload,
+* no request-scoped anything — nothing a render reads and nothing a response
+* is built from. Two concurrent SSR requests observe the same empty listener
+* sets and neither can learn a thing about the other.
+*
+* It is also safe to IMPORT on the server: constructing it touches no DOM
+* global, no `window`, no `history`, and performs no work beyond allocating
+* three empty sets. On the server nothing subscribes and nothing emits, so it
+* simply sits there — which is the correct server behaviour for a progress
+* bar.
+*
+* A singleton (rather than a context or a factory at the call site) is what
+* lets a progress bar living anywhere in the tree — or outside React
+* entirely — hear a navigation without being handed a bus by every component
+* between it and the root. That plumbing is the reason MRR made this global
+* too. Use {@link createRouterEvents} when you want an isolated one.
+*/
+const routerEvents = createRouterEvents();
+
+//#endregion
+export { createRouterEvents, routerEvents };
+//# sourceMappingURL=router-events.mjs.map

package/esm/routing/router-events.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"router-events.mjs","names":[],"sources":["../../../../../../../web/src/routing/router-events.ts"],"sourcesContent":["/**\n * The navigation lifecycle emitter — what a progress bar subscribes to.\n *\n * A client navigation is a fetch followed by a tree swap\n * (`client/navigation/navigation-root.tsx`). Nothing about that is visible to\n * the user while it is in flight, which is the whole reason this module\n * exists: a progress bar, an analytics hook or a scroll restorer needs to know\n * that a navigation STARTED, that it FINISHED, and that it FAILED — and none\n * of them should have to reach into the navigation runtime to find out.\n *\n * So the runtime announces, and anyone may listen. The listeners are strangers\n * to each other and to the runtime; that is the point.\n *\n * ## This module ships the emitter only\n *\n * Nothing here is wired into the navigation runtime yet — `navigation-root.tsx`\n * calls the `emit*` methods in a later change. Until then this is a complete,\n * self-contained emitter with no callers, which is why it has no dependency on\n * anything in `client/`.\n *\n * ## What it deliberately does NOT do\n *\n * It carries URLs as OPAQUE STRINGS. There is no matching, no parsing, no\n * \"which route is this\" — Warlock's server router is the only matcher (canon\n * 9c8f878b), and an emitter that started parsing paths would be a second one.\n * A listener that wants a route name gets it from the payload the navigation\n * produced, not from this module.\n *\n * DIRECTORY CONTRACT — see `route-identity.ts`: nothing in `web/src/routing/`\n * may import `node:fs`, `node:path`, `vite` or `fastify`. This module also\n * touches no DOM global, which is what makes it importable from a server\n * render (see below).\n *\n * ## Named for its ancestor\n *\n * `routerEvents` is the name `@mongez/react-router` used\n * (`@mongez/react-router/src/events.ts`), and the subscription ergonomics are\n * deliberately familiar: `routerEvents.onNavigating(callback)` returns\n * something you call to stop listening. The implementation is NOT ported —\n * MRR's delegates to a global `@mongez/events` bus keyed by string\n * (`\"router.navigating\"`), which reaches its router singleton and gives up\n * per-event payload typing in the process. Here the events are the object's\n * own methods, so each one carries its own payload type and a typo is a\n * compile error rather than a listener that never fires.\n *\n * MRR returns an `EventSubscription` object; this returns the unsubscribe\n * FUNCTION itself, because that is what a React `useEffect` cleanup wants to\n * be handed:\n *\n * ```ts\n * useEffect(() => routerEvents.onNavigating(() => setLoading(true)), []);\n * ```\n */\n\n/**\n * How the navigation will be written to browser history.\n *\n * `\"replace\"` covers both an explicit `<Link replace>` and a Back/Forward\n * press — the runtime replaces in both cases, because the history entry\n * already exists. A listener that wants to stay quiet during Back/Forward\n * cannot tell the two apart from here, and does not need to: what it actually\n * cares about is that no new entry is being pushed.\n */\nexport type NavigationMode = \"push\" | \"replace\";\n\n/** Emitted when a navigation begins — before anything has been fetched. */\nexport type NavigationStartPayload = {\n  /** The URL the navigation was requested for, verbatim and unparsed. */\n  url: string;\n  mode: NavigationMode;\n};\n\n/** Emitted when a navigation has completed and the new page is on screen. */\nexport type NavigationEndPayload = {\n  /** The URL the navigation was requested for — the same string {@link NavigationStartPayload} carried. */\n  url: string;\n  /**\n   * The URL the page data actually came from, which is what landed in the\n   * address bar. It differs from `url` whenever the server redirected — a\n   * page that requires auth answers from `/login` (see\n   * `client/navigation/fetch-page-data.ts`).\n   */\n  resolvedUrl: string;\n  mode: NavigationMode;\n};\n\n/**\n * Emitted when a navigation could not complete.\n *\n * A failed client navigation is not a dead end — the runtime degrades to a\n * full browser load — so a listener should treat this as \"the in-flight\n * navigation is over\", not as an error to render. A progress bar hides on it.\n */\nexport type NavigationErrorPayload = {\n  /** The URL the navigation was requested for. */\n  url: string;\n  mode: NavigationMode;\n  /**\n   * What went wrong. `unknown` rather than `Error` because a caught value has\n   * no such guarantee — narrow it before reading `.message`.\n   */\n  error: unknown;\n};\n\n/** A listener for one navigation event. Its return value is ignored. */\nexport type RouterEventListener<Payload> = (payload: Payload) => void;\n\n/** Call it to stop listening. Calling it more than once is a no-op. */\nexport type RouterEventUnsubscribe = () => void;\n\n/**\n * The navigation lifecycle surface: three events, each with its own payload\n * type, each subscribable and emittable.\n *\n * The `emit*` half belongs to the navigation runtime. Nothing stops other code\n * from calling it, and nothing needs to — an emitter that lies about\n * navigations is a bug in whoever called it, not a boundary worth policing.\n */\nexport type RouterEvents = {\n  /** Subscribe to the start of every navigation. @returns the unsubscribe function. */\n  onNavigating: (listener: RouterEventListener<NavigationStartPayload>) => RouterEventUnsubscribe;\n  /** Subscribe to every navigation that completed. @returns the unsubscribe function. */\n  onNavigated: (listener: RouterEventListener<NavigationEndPayload>) => RouterEventUnsubscribe;\n  /** Subscribe to every navigation that failed. @returns the unsubscribe function. */\n  onNavigationError: (\n    listener: RouterEventListener<NavigationErrorPayload>,\n  ) => RouterEventUnsubscribe;\n  /** Announce that a navigation has begun. Called by the navigation runtime. */\n  emitNavigating: (payload: NavigationStartPayload) => void;\n  /** Announce that a navigation has completed. Called by the navigation runtime. */\n  emitNavigated: (payload: NavigationEndPayload) => void;\n  /** Announce that a navigation has failed. Called by the navigation runtime. */\n  emitNavigationError: (payload: NavigationErrorPayload) => void;\n};\n\n/**\n * One registration. An OBJECT rather than the callback itself, so that\n * subscribing the same function twice is two independent registrations — a\n * registry keyed by the callback would collapse them, and then one component's\n * cleanup would silently deafen another's.\n */\ntype Registration<Payload> = { listener: RouterEventListener<Payload> };\n\ntype Signal<Payload> = {\n  subscribe: (listener: RouterEventListener<Payload>) => RouterEventUnsubscribe;\n  emit: (payload: Payload) => void;\n};\n\n/**\n * One event's registrations and its delivery loop. A `Set` because insertion\n * order is preserved (listeners fire in subscription order) and removal is by\n * identity, which is exactly what an unsubscribe closure holds.\n */\nfunction createSignal<Payload>(eventName: string): Signal<Payload> {\n  const registrations = new Set<Registration<Payload>>();\n\n  return {\n    subscribe: listener => {\n      const registration: Registration<Payload> = { listener };\n\n      registrations.add(registration);\n\n      // `Set.delete` on an absent member is a no-op, so this is idempotent for\n      // free — which matters because React StrictMode runs an effect's cleanup\n      // twice in development.\n      return () => {\n        registrations.delete(registration);\n      };\n    },\n    emit: payload => {\n      /*\n        A SNAPSHOT, not the live set. Listeners subscribe and unsubscribe from\n        inside other listeners — a progress bar that hides itself, a one-shot\n        analytics hook — and mutating the collection being iterated is how an\n        emitter starts skipping listeners. Iterating a copy also fixes the\n        cohort: a listener added during this emit belongs to the next\n        navigation, not to the one already in flight.\n\n        Removals during the emit are still honoured (the deleted-check below),\n        because a listener that has just unsubscribed has said it no longer\n        wants this event, and delivering it anyway is the bug that outlives the\n        component.\n      */\n      for (const registration of [...registrations]) {\n        if (!registrations.has(registration)) continue;\n\n        try {\n          registration.listener(payload);\n        } catch (error) {\n          /*\n            THE POINT OF THE TRY. Everything downstream of an emit — the\n            history entry, the tree swap — happens after this loop returns, so\n            a listener that throws would otherwise take the navigation down\n            with it. One broken progress bar is a broken progress bar; it is\n            not a stuck page.\n\n            Reported rather than swallowed: a listener failing silently on\n            every navigation is worse than noisy. The listener STAYS\n            subscribed, because one bad emit is not consent to deregister\n            something the component still owns and will still try to clean up.\n          */\n          console.error(`Warlock routerEvents: a ${eventName} listener threw:`, error);\n        }\n      }\n    },\n  };\n}\n\n/**\n * Builds an independent emitter with no listeners.\n *\n * This is what makes the module TESTABLE without cross-test bleed, and it is\n * the escape hatch for anything that needs a private lifecycle bus. The\n * shared {@link routerEvents} is one of these, created once.\n */\nexport function createRouterEvents(): RouterEvents {\n  const navigating = createSignal<NavigationStartPayload>(\"navigating\");\n  const navigated = createSignal<NavigationEndPayload>(\"navigated\");\n  const navigationError = createSignal<NavigationErrorPayload>(\"navigation-error\");\n\n  return {\n    onNavigating: navigating.subscribe,\n    onNavigated: navigated.subscribe,\n    onNavigationError: navigationError.subscribe,\n    emitNavigating: navigating.emit,\n    emitNavigated: navigated.emit,\n    emitNavigationError: navigationError.emit,\n  };\n}\n\n/**\n * The shared navigation lifecycle emitter — the one a progress bar subscribes\n * to and the one the navigation runtime emits on.\n *\n * ## Why a module-level singleton is safe here, when module-level state is a known SSR hazard\n *\n * Canon records MRR's `RouterWrapper.tsx:63` as the cautionary case: module\n * state that holds RENDER state is shared by every concurrent request on the\n * server, so one visitor's page leaks into another's. That hazard is about\n * *what* is held, not about module scope itself — `routing/navigator.ts` in\n * this same directory already holds a module-level registration for the same\n * reason.\n *\n * This object holds ONLY listener registrations. No current route, no payload,\n * no request-scoped anything — nothing a render reads and nothing a response\n * is built from. Two concurrent SSR requests observe the same empty listener\n * sets and neither can learn a thing about the other.\n *\n * It is also safe to IMPORT on the server: constructing it touches no DOM\n * global, no `window`, no `history`, and performs no work beyond allocating\n * three empty sets. On the server nothing subscribes and nothing emits, so it\n * simply sits there — which is the correct server behaviour for a progress\n * bar.\n *\n * A singleton (rather than a context or a factory at the call site) is what\n * lets a progress bar living anywhere in the tree — or outside React\n * entirely — hear a navigation without being handed a bus by every component\n * between it and the root. That plumbing is the reason MRR made this global\n * too. Use {@link createRouterEvents} when you want an isolated one.\n */\nexport const routerEvents: RouterEvents = createRouterEvents();\n"],"mappings":";;;;;;AAyJA,SAAS,aAAsB,WAAoC;CACjE,MAAM,gCAAgB,IAAI,IAA2B;CAErD,OAAO;EACL,YAAW,aAAY;GACrB,MAAM,eAAsC,EAAE,SAAS;GAEvD,cAAc,IAAI,YAAY;GAK9B,aAAa;IACX,cAAc,OAAO,YAAY;GACnC;EACF;EACA,OAAM,YAAW;GAcf,KAAK,MAAM,gBAAgB,CAAC,GAAG,aAAa,GAAG;IAC7C,IAAI,CAAC,cAAc,IAAI,YAAY,GAAG;IAEtC,IAAI;KACF,aAAa,SAAS,OAAO;IAC/B,SAAS,OAAO;KAad,QAAQ,MAAM,2BAA2B,UAAU,mBAAmB,KAAK;IAC7E;GACF;EACF;CACF;AACF;;;;;;;;AASA,SAAgB,qBAAmC;CACjD,MAAM,aAAa,aAAqC,YAAY;CACpE,MAAM,YAAY,aAAmC,WAAW;CAChE,MAAM,kBAAkB,aAAqC,kBAAkB;CAE/E,OAAO;EACL,cAAc,WAAW;EACzB,aAAa,UAAU;EACvB,mBAAmB,gBAAgB;EACnC,gBAAgB,WAAW;EAC3B,eAAe,UAAU;EACzB,qBAAqB,gBAAgB;CACvC;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,MAAa,eAA6B,mBAAmB"}