@k8ordo/router 0.1.0 → 1.0.0

package/README.md

@@ -21,18 +21,27 @@ npm install @k8ordo/router
 pnpm add @k8ordo/router
 ```
 
-Under `@k8ordo/static` or `@k8ordo/server` this package is what the framework
-builds on: the table is generated from `src/routes/`, and what an application
-uses of it is `href`, `usePathname` and `useMatch`. On its own it is the whole
-router for an application that renders in the browser.
+Under `@k8ordo/framework` this package is what the framework builds on: the
+table is generated from `src/routes/`, and what an application uses of it is
+the half that needs no table — `href`, `navigateTo` and `bindParams`;
+`usePathname`, `useMatch` and `matchPath` — plus the route files' props types,
+`PageProps` and `LayoutProps`. There it is installed as the framework's peer,
+and the application imports that half from `@k8ordo/framework`, which
+re-exports it. On its own it is the whole router for an application that
+renders in the browser.
 
 ## Peer Dependencies
 
-| Package        | Version  | Needed for                    |
-| -------------- | -------- | ----------------------------- |
-| `react`        | ≥19.2.6  | `<Router>` and the hooks      |
-| `typescript`   | ≥7.0.2   | the shipped type declarations |
-| `@types/react` | ≥19.2.18 | the shipped type declarations |
+<!-- peers -->
+
+| Package        | Version | Required | Needed for                      |
+| -------------- | ------- | -------- | ------------------------------- |
+| `react`        | ≥19.3.0 | yes      | `<Router>` and the hooks        |
+| `react-dom`    | ≥19.3.0 | yes      | `BrowserPathname` (`browser()`) |
+| `typescript`   | ≥7.0.0  | optional | the shipped type declarations   |
+| `@types/react` | ≥19.3.0 | optional | the shipped type declarations   |
+
+<!-- /peers -->
 
 No runtime dependencies. The Navigation API and URLPattern are the platform's.
 

package/dist/base.d.mts

@@ -0,0 +1,16 @@
+//#region src/base.d.ts
+/**
+ * A pathname in the table's terms, as the URL spells it: the base in front.
+ * Under `base: '/docs/'`, `/products` → `/docs/products` and `/` → `/docs/`.
+ * `href` and `navigateTo` build every link through it, so a table written
+ * from the root works wherever the application is served.
+ */
+export declare const withBase: (pathname: string, base?: string) => string;
+/**
+ * The inverse: a URL's pathname in the table's terms, or `null` when it is
+ * not under the base — a URL the application does not serve. Under
+ * `base: '/docs/'`, `/docs/products` → `/products`, and `/docs` and `/docs/`
+ * → `/`.
+ */
+export declare const withoutBase: (pathname: string, base?: string) => string | null;
+//#endregion

package/dist/base.mjs

@@ -0,0 +1,45 @@
+import { normalizePathname } from "./paths.mjs";
+//#region src/base.ts
+/**
+* Where Vite serves the application — its `base`, as `import.meta.env.BASE_URL`
+* spells it (`/`, `/docs/`). Read when a caller does not pass a base: code
+* Node loads without Vite (the static build, `serve`) has no `import.meta.env`
+* and passes the configured base instead.
+*/
+const viteBase = () => import.meta.env.BASE_URL;
+/**
+* The base as a prefix of the URL's pathname: `''` at the root, `/docs` under
+* `/docs/`. Only a path names one — Vite's relative `./` does not say where
+* the pages are, so it adds nothing.
+*/
+const prefixOf = (base) => {
+	if (!base.startsWith("/")) return "";
+	const prefix = normalizePathname(base);
+	return prefix === "/" ? "" : prefix;
+};
+/**
+* A pathname in the table's terms, as the URL spells it: the base in front.
+* Under `base: '/docs/'`, `/products` → `/docs/products` and `/` → `/docs/`.
+* `href` and `navigateTo` build every link through it, so a table written
+* from the root works wherever the application is served.
+*/
+const withBase = (pathname, base = viteBase()) => {
+	const prefix = prefixOf(base);
+	if (prefix === "") return pathname;
+	return pathname === "/" ? `${prefix}/` : `${prefix}${pathname}`;
+};
+/**
+* The inverse: a URL's pathname in the table's terms, or `null` when it is
+* not under the base — a URL the application does not serve. Under
+* `base: '/docs/'`, `/docs/products` → `/products`, and `/docs` and `/docs/`
+* → `/`.
+*/
+const withoutBase = (pathname, base = viteBase()) => {
+	const prefix = prefixOf(base);
+	if (prefix === "") return pathname;
+	if (pathname === prefix) return "/";
+	if (!pathname.startsWith(`${prefix}/`)) return null;
+	return pathname.slice(prefix.length);
+};
+//#endregion
+export { withBase, withoutBase };

package/dist/boundary.d.mts

@@ -4,21 +4,24 @@ import { ComponentType, ReactNode } from "react";
  * What a route table's `error` component receives: what was thrown, and a
  * way to try the subtree again in place.
  */
-type ErrorProps = {
+export type ErrorProps = {
   readonly error: unknown;
   readonly reset: () => void;
 };
-type ErrorComponent = ComponentType<ErrorProps>;
-type CatchProps = {
+export type ErrorComponent = ComponentType<ErrorProps>;
+type BoundaryProps = {
   readonly fallback: ErrorComponent;
   readonly children?: ReactNode;
 };
 /**
- * The boundary a table's `error` component renders inside. Keyed by the
- * navigation that put the tree on screen, so leaving the page that failed
- * leaves the failure behind — and not by the pathname, which commits before
- * the tree arrives and would remount the boundary onto the old tree.
+ * The boundary a table's `error` component renders inside. The navigation
+ * that puts the next tree on screen clears the failure, so leaving the page
+ * that failed leaves it behind — and not the pathname, which commits before
+ * the tree arrives and would clear it onto the old tree.
+ *
+ * Cleared, not keyed: a key would remount everything below the boundary on
+ * every page change, failed or not, and a root boundary would take the whole
+ * application's layouts with it.
  */
-declare const RouteErrorBoundary: ({ fallback, children }: CatchProps) => ReactNode;
-//#endregion
-export { ErrorComponent, ErrorProps, RouteErrorBoundary };
+export declare const RouteErrorBoundary: ({ fallback, children }: BoundaryProps) => ReactNode;
+//#endregion

package/dist/boundary.mjs

@@ -5,7 +5,8 @@ import { Component, Suspense, createElement, use } from "react";
 var Catch = class extends Component {
 	state = {
 		error: void 0,
-		failed: false
+		failed: false,
+		generation: this.props.generation
 	};
 	static getDerivedStateFromError(error) {
 		return {
@@ -13,6 +14,14 @@ var Catch = class extends Component {
 			failed: true
 		};
 	}
+	static getDerivedStateFromProps(props, state) {
+		if (props.generation === state.generation) return null;
+		return {
+			error: void 0,
+			failed: false,
+			generation: props.generation
+		};
+	}
 	reset = () => {
 		this.setState({
 			error: void 0,
@@ -28,15 +37,19 @@ var Catch = class extends Component {
 	}
 };
 /**
-* The boundary a table's `error` component renders inside. Keyed by the
-* navigation that put the tree on screen, so leaving the page that failed
-* leaves the failure behind — and not by the pathname, which commits before
-* the tree arrives and would remount the boundary onto the old tree.
+* The boundary a table's `error` component renders inside. The navigation
+* that puts the next tree on screen clears the failure, so leaving the page
+* that failed leaves it behind — and not the pathname, which commits before
+* the tree arrives and would clear it onto the old tree.
+*
+* Cleared, not keyed: a key would remount everything below the boundary on
+* every page change, failed or not, and a root boundary would take the whole
+* application's layouts with it.
 */
 const RouteErrorBoundary = ({ fallback, children }) => {
 	const generation = use(NavigationGeneration);
 	return createElement(Suspense, { fallback: null }, createElement(Catch, {
-		key: generation,
+		generation,
 		fallback
 	}, children));
 };

package/dist/define-routes.d.mts

@@ -1,5 +1,5 @@
 import { ErrorComponent } from "./boundary.mjs";
-import { Join, PathFor } from "./paths.mjs";
+import { Join, PathMatching } from "./paths.mjs";
 import { ComponentType, ReactNode } from "react";
 //#region src/define-routes.d.ts
 /**
@@ -9,41 +9,46 @@ import { ComponentType, ReactNode } from "react";
  * their `children` — so the stored type has to admit them all. `never` props
  * is the type-safe spelling of that; each renderer states what it passes.
  */
-type RouteComponent = ComponentType<never>;
+export type RouteComponent = ComponentType<never>;
 /**
  * A leaf renders; a branch wraps its children in an optional layout, and
  * may name an `error` component to show in place of what is below when it
- * throws — inside the layout, so the frame survives the failure. Lazy
- * components (`React.lazy`) are objects, not functions, so a branch is
- * recognized by its `children` key rather than by `typeof`.
+ * throws — inside the layout, so the frame survives the failure — and a
+ * `loading` component to show while what is below suspends. Lazy components
+ * (`React.lazy`) are objects, not functions, so a branch is recognized by
+ * its `children` key rather than by `typeof`.
  */
-type RouteNode = RouteComponent | {
+export type RouteNode = RouteComponent | {
   layout?: RouteComponent;
   error?: ErrorComponent;
+  loading?: ComponentType;
   children: RoutesRecord;
 };
-type RoutesRecord = Record<`/${string}`, RouteNode>;
+export type RoutesRecord = Record<`/${string}`, RouteNode>;
 type Below<Prefix extends string, Key extends string> = Join<Prefix, Key> extends '/' ? '' : Join<Prefix, Key>;
 type PatternsIn<Record_, Prefix extends string> = { [K in keyof Record_ & string]: Record_[K] extends {
   children: infer C;
 } ? PatternsIn<C, Below<Prefix, K>> : Join<Prefix, K>; }[keyof Record_ & string];
 /** Every full leaf pattern in the table, as written. */
-type PatternOf<R extends RoutesRecord> = PatternsIn<R, ''> & string;
+export type PatternOf<R extends RoutesRecord> = PatternsIn<R, ''> & string;
 /** Patterns a link can point at — wildcards are matched, never linked. */
-type NavigablePatternOf<R extends RoutesRecord> = Exclude<PatternOf<R>, `${string}*${string}`>;
+export type NavigablePatternOf<R extends RoutesRecord> = Exclude<PatternOf<R>, `${string}*${string}`>;
 /**
- * The app's pathname space as a type: the union state's `Register` (and any
- * other typed-path consumer) is fed with.
+ * `Path` when one of the table's navigable patterns matches it, segment by
+ * segment — a literal spelled as the pattern spells it, a `:param` taking any
+ * one non-empty segment — and `never` when none does. What `@k8ordo/state`
+ * checks a path against with the `routes` its `Register` is given, and what
+ * any other typed-path consumer takes.
  */
-type RouteOf<D> = D extends Routes<infer R> ? PathFor<NavigablePatternOf<R>> : never;
-type Match = {
+export type NavigablePath<D, Path extends string> = D extends Routes<infer R extends RoutesRecord> ? PathMatching<Path, NavigablePatternOf<R>> : never;
+export type Match = {
   /** The full pattern that won, as written in the table. */
   pattern: string;
   params: Readonly<Record<string, string>>;
   /** Layouts outer-first, the leaf last. */
   stack: readonly RouteComponent[];
 };
-type Routes<R extends RoutesRecord = RoutesRecord> = {
+export type Routes<R extends RoutesRecord = RoutesRecord> = {
   kind: 'routes';
   /** The table as passed. */
   record: R;
@@ -61,7 +66,6 @@ type Routes<R extends RoutesRecord = RoutesRecord> = {
    */
   match: (pathname: string, accept?: (match: Match) => boolean) => Match | null;
 };
-declare const setBoundaryOutlet: (render: () => ReactNode) => void;
-declare function defineRoutes<R extends RoutesRecord>(record: R): Routes<R>;
-//#endregion
-export { Match, NavigablePatternOf, PatternOf, RouteComponent, RouteNode, RouteOf, Routes, RoutesRecord, defineRoutes, setBoundaryOutlet };
+export declare const setBoundaryOutlet: (render: () => ReactNode) => void;
+export declare function defineRoutes<R extends RoutesRecord>(record: R): Routes<R>;
+//#endregion

package/dist/define-routes.mjs

@@ -1,6 +1,6 @@
 import { isGroupKey, joinPattern, normalizePathname } from "./paths.mjs";
 import { RouteErrorBoundary } from "./boundary.mjs";
-import { createElement } from "react";
+import { Suspense, createElement } from "react";
 //#region src/define-routes.ts
 const isBranch = (node) => typeof node === "object" && "children" in node;
 /**
@@ -14,6 +14,18 @@ const boundaryFor = (fallback) => {
 	const Boundary = ({ children }) => createElement(RouteErrorBoundary, { fallback }, children === void 0 ? outlet() : children);
 	return Boundary;
 };
+/**
+* A branch's `loading` becomes an element of the stack too — after the
+* layout and inside the error boundary, so what the boundary catches is what
+* the fallback stood in for. A plain `<Suspense>`: a page change under one
+* already showing keeps the page on screen while the next one loads, as
+* every page change does, and the fallback shows while it first streams in
+* and when a navigation mounts it anew.
+*/
+const loadingFor = (Fallback) => {
+	const Loading = ({ children }) => createElement(Suspense, { fallback: createElement(Fallback) }, children === void 0 ? outlet() : children);
+	return Loading;
+};
 const decode = (value) => {
 	try {
 		return decodeURIComponent(value);
@@ -43,7 +55,8 @@ function defineRoutes(record) {
 				const below = [
 					...stack,
 					...node.layout === void 0 ? [] : [node.layout],
-					...node.error === void 0 ? [] : [boundaryFor(node.error)]
+					...node.error === void 0 ? [] : [boundaryFor(node.error)],
+					...node.loading === void 0 ? [] : [loadingFor(node.loading)]
 				];
 				walk(node.children, pattern === "/" ? "" : pattern, below);
 			} else {

package/dist/index.d.mts

@@ -1,10 +1,12 @@
+import { withBase, withoutBase } from "./base.mjs";
 import { ErrorComponent, ErrorProps } from "./boundary.mjs";
 import { ParamValue, ParamsOf, ParamsSchemaFor, ParsedParams, ParsedParamsMap, PathFor, SchemaOutput, StandardSchemaLike, normalizePathname } from "./paths.mjs";
-import { Match, NavigablePatternOf, PatternOf, RouteComponent, RouteNode, RouteOf, Routes, RoutesRecord, defineRoutes } from "./define-routes.mjs";
-import { Register, RegisteredNavigablePattern, RegisteredParams, RegisteredPattern } from "./register.mjs";
-import { NavigateToOptions, href, navigateTo } from "./links.mjs";
-import { PathnameProvider, usePathname } from "./location.mjs";
-import { MatchablePattern, matchPath, useMatch } from "./match.mjs";
-import { NavigationGeneration, NavigationHandler, useInterceptedNavigation } from "./navigation.mjs";
+import { Match, NavigablePath, NavigablePatternOf, PatternOf, RouteComponent, RouteNode, Routes, RoutesRecord, defineRoutes } from "./define-routes.mjs";
+import { LayoutProps, PageProps, Register, RegisteredNavigablePattern, RegisteredPageParams, RegisteredParams, RegisteredPattern, RouteContext } from "./register.mjs";
+import { BoundLinks, BoundParams, NavigateToOptions, bindParams, href, navigateTo } from "./links.mjs";
+import { BrowserPathname, PathnameProvider, usePathname } from "./location.mjs";
+import { MatchOptions, MatchablePattern, matchPath, useMatch } from "./match.mjs";
+import { isNotFound, notFound } from "./not-found.mjs";
+import { NavigationGeneration, NavigationHandler, useInterceptedNavigation, usePendingPathname } from "./navigation.mjs";
 import { Outlet, Router, useParams, useRoute } from "./router.mjs";
-export { type ErrorComponent, type ErrorProps, type Match, type MatchablePattern, type NavigablePatternOf, type NavigateToOptions, NavigationGeneration, type NavigationHandler, Outlet, type ParamValue, type ParamsOf, type ParamsSchemaFor, type ParsedParams, type ParsedParamsMap, type PathFor, PathnameProvider, type PatternOf, type Register, type RegisteredNavigablePattern, type RegisteredParams, type RegisteredPattern, type RouteComponent, type RouteNode, type RouteOf, Router, type Routes, type RoutesRecord, type SchemaOutput, type StandardSchemaLike, defineRoutes, href, matchPath, navigateTo, normalizePathname, useInterceptedNavigation, useMatch, useParams, usePathname, useRoute };
+export { type BoundLinks, type BoundParams, BrowserPathname, type ErrorComponent, type ErrorProps, type LayoutProps, type Match, type MatchOptions, type MatchablePattern, type NavigablePath, type NavigablePatternOf, type NavigateToOptions, NavigationGeneration, type NavigationHandler, Outlet, type PageProps, type ParamValue, type ParamsOf, type ParamsSchemaFor, type ParsedParams, type ParsedParamsMap, type PathFor, PathnameProvider, type PatternOf, type Register, type RegisteredNavigablePattern, type RegisteredPageParams, type RegisteredParams, type RegisteredPattern, type RouteComponent, type RouteContext, type RouteNode, Router, type Routes, type RoutesRecord, type SchemaOutput, type StandardSchemaLike, bindParams, defineRoutes, href, isNotFound, matchPath, navigateTo, normalizePathname, notFound, useInterceptedNavigation, useMatch, useParams, usePathname, usePendingPathname, useRoute, withBase, withoutBase };

package/dist/index.mjs

@@ -1,8 +1,10 @@
 import { normalizePathname } from "./paths.mjs";
-import { NavigationGeneration, useInterceptedNavigation } from "./navigation.mjs";
+import { withBase, withoutBase } from "./base.mjs";
+import { NavigationGeneration, useInterceptedNavigation, usePendingPathname } from "./navigation.mjs";
 import { defineRoutes } from "./define-routes.mjs";
-import { href, navigateTo } from "./links.mjs";
-import { PathnameProvider, usePathname } from "./location.mjs";
+import { bindParams, href, navigateTo } from "./links.mjs";
+import { BrowserPathname, PathnameProvider, usePathname } from "./location.mjs";
 import { matchPath, useMatch } from "./match.mjs";
+import { isNotFound, notFound } from "./not-found.mjs";
 import { Outlet, Router, useParams, useRoute } from "./router.mjs";
-export { NavigationGeneration, Outlet, PathnameProvider, Router, defineRoutes, href, matchPath, navigateTo, normalizePathname, useInterceptedNavigation, useMatch, useParams, usePathname, useRoute };
+export { BrowserPathname, NavigationGeneration, Outlet, PathnameProvider, Router, bindParams, defineRoutes, href, isNotFound, matchPath, navigateTo, normalizePathname, notFound, useInterceptedNavigation, useMatch, useParams, usePathname, usePendingPathname, useRoute, withBase, withoutBase };

package/dist/links.d.mts

@@ -1,8 +1,8 @@
-import { PathFor } from "./paths.mjs";
+import { ParamValue } from "./paths.mjs";
 import { RegisteredNavigablePattern, RegisteredParams } from "./register.mjs";
 //#region src/links.d.ts
 type HrefArgs<Params> = keyof Params extends never ? [] : [params: Readonly<Params & Record<never, never>>];
-type NavigateToOptions = {
+export type NavigateToOptions = {
   /**
    * `push` by default: going to a page is what the back button undoes —
    * the opposite default from a state refinement.
@@ -11,21 +11,50 @@ type NavigateToOptions = {
 };
 type NavigateToArgs<Params> = keyof Params extends never ? [options?: NavigateToOptions] : [params: Readonly<Params & Record<never, never>>, options?: NavigateToOptions];
 /**
- * Builds a concrete path from a pattern and its params — no route table
- * involved, which is why pages never import one. Params are inferred from
- * the pattern literal itself; `Register` adds the check that the pattern
- * exists in the app's table, and — under the framework — the type a page's
- * schema gave each param, so a link takes what the page received. The path
- * shape survives in the return type for typed-path consumers
- * (`@k8ordo/state`'s `Register` among them).
+ * Builds the URL a link points at from a pattern and its params — no route
+ * table involved, which is why pages never import one. Params are inferred
+ * from the pattern literal itself; `Register` adds the check that the
+ * pattern exists in the app's table, and — under the framework — the type a
+ * page's schema gave each param, so a link takes what the page received.
+ *
+ * What comes back is a URL, with Vite's `base` in front (`withBase`), not a
+ * pathname in the table's terms — which is why it is typed `string`: handed
+ * to something that adds the base itself, it would carry it twice.
  */
-declare const href: <P extends RegisteredNavigablePattern>(pattern: P, ...params: HrefArgs<RegisteredParams<P>>) => PathFor<P>;
+export declare const href: <P extends RegisteredNavigablePattern>(pattern: P, ...params: HrefArgs<RegisteredParams<P>>) => string;
 /**
  * Typed imperative navigation: `href` composed with
  * `navigation.navigate()`, returning the platform's own
  * `{ committed, finished }`. Changing pages goes through here; changing
  * state goes through `@k8ordo/state`'s `update()`.
  */
-declare const navigateTo: <P extends RegisteredNavigablePattern>(pattern: P, ...rest: NavigateToArgs<RegisteredParams<P>>) => ReturnType<Navigation['navigate']>;
-//#endregion
-export { NavigateToOptions, href, navigateTo };
+export declare const navigateTo: <P extends RegisteredNavigablePattern>(pattern: P, ...rest: NavigateToArgs<RegisteredParams<P>>) => ReturnType<Navigation['navigate']>;
+/** What a params source supplies: values with one URL spelling, by name. */
+export type BoundParams = Readonly<Record<string, ParamValue>>;
+/**
+ * The params a bound link still takes: what the source does not supply is
+ * required as before, and what it does supply may be given to override it.
+ */
+type Unbound<Params, Bound> = Omit<Params, keyof Bound> & Partial<Pick<Params, Extract<keyof Bound, keyof Params>>>;
+type BoundHrefArgs<Params, Bound> = Exclude<keyof Params, keyof Bound> extends never ? [params?: Readonly<Partial<Params> & Record<never, never>>] : [params: Readonly<Unbound<Params, Bound> & Record<never, never>>];
+type BoundNavigateToArgs<Params, Bound> = keyof Params extends never ? [options?: NavigateToOptions] : [...BoundHrefArgs<Params, Bound>, options?: NavigateToOptions];
+export type BoundLinks<Bound extends BoundParams> = {
+  readonly href: <P extends RegisteredNavigablePattern>(pattern: P, ...rest: BoundHrefArgs<RegisteredParams<P>, Bound>) => string;
+  readonly navigateTo: <P extends RegisteredNavigablePattern>(pattern: P, ...rest: BoundNavigateToArgs<RegisteredParams<P>, Bound>) => ReturnType<Navigation['navigate']>;
+};
+/**
+ * `href` and `navigateTo` with some params supplied by a function instead of
+ * by every call — a segment the whole application shares, such as a locale
+ * or a tenant. The source is read at each call, so a value that differs per
+ * request or per URL is read where it is current. Patterns keep their full
+ * spelling (`'/:locale/products'`), so the table's types apply unchanged and
+ * a bound param can still be given to point at another value.
+ *
+ * ```ts
+ * const { href, navigateTo } = bindParams(() => ({ locale: locales.getLocale() }));
+ * href('/:locale/products/:id', { id }); // locale comes from the source
+ * navigateTo('/:locale', { locale: 'en' }, { history: 'replace' }); // or is overridden
+ * ```
+ */
+export declare const bindParams: <const Bound extends BoundParams>(source: () => Bound) => BoundLinks<Bound>;
+//#endregion

package/dist/links.mjs

@@ -1,15 +1,19 @@
 import { buildHref } from "./paths.mjs";
+import { withBase } from "./base.mjs";
 //#region src/links.ts
+const navigate = (pattern, params, options) => navigation.navigate(withBase(buildHref(pattern, params)), { history: options?.history ?? "push" });
 /**
-* Builds a concrete path from a pattern and its params — no route table
-* involved, which is why pages never import one. Params are inferred from
-* the pattern literal itself; `Register` adds the check that the pattern
-* exists in the app's table, and — under the framework — the type a page's
-* schema gave each param, so a link takes what the page received. The path
-* shape survives in the return type for typed-path consumers
-* (`@k8ordo/state`'s `Register` among them).
+* Builds the URL a link points at from a pattern and its params — no route
+* table involved, which is why pages never import one. Params are inferred
+* from the pattern literal itself; `Register` adds the check that the
+* pattern exists in the app's table, and — under the framework — the type a
+* page's schema gave each param, so a link takes what the page received.
+*
+* What comes back is a URL, with Vite's `base` in front (`withBase`), not a
+* pathname in the table's terms — which is why it is typed `string`: handed
+* to something that adds the base itself, it would carry it twice.
 */
-const href = (pattern, ...params) => buildHref(pattern, params[0]);
+const href = (pattern, ...params) => withBase(buildHref(pattern, params[0]));
 /**
 * Typed imperative navigation: `href` composed with
 * `navigation.navigate()`, returning the platform's own
@@ -21,7 +25,37 @@ const navigateTo = (pattern, ...rest) => {
 	const args = rest;
 	const params = wantsParams ? args[0] : void 0;
 	const options = wantsParams ? args[1] : args[0];
-	return navigation.navigate(buildHref(pattern, params), { history: options?.history ?? "push" });
+	return navigate(pattern, params, options);
 };
+/**
+* `href` and `navigateTo` with some params supplied by a function instead of
+* by every call — a segment the whole application shares, such as a locale
+* or a tenant. The source is read at each call, so a value that differs per
+* request or per URL is read where it is current. Patterns keep their full
+* spelling (`'/:locale/products'`), so the table's types apply unchanged and
+* a bound param can still be given to point at another value.
+*
+* ```ts
+* const { href, navigateTo } = bindParams(() => ({ locale: locales.getLocale() }));
+* href('/:locale/products/:id', { id }); // locale comes from the source
+* navigateTo('/:locale', { locale: 'en' }, { history: 'replace' }); // or is overridden
+* ```
+*/
+const bindParams = (source) => ({
+	href: (pattern, ...rest) => withBase(buildHref(pattern, {
+		...source(),
+		...rest[0]
+	})),
+	navigateTo: (pattern, ...rest) => {
+		const wantsParams = pattern.includes(":");
+		const args = rest;
+		const params = wantsParams ? args[0] : void 0;
+		const options = wantsParams ? args[1] : args[0];
+		return navigate(pattern, {
+			...source(),
+			...params
+		}, options);
+	}
+});
 //#endregion
-export { href, navigateTo };
+export { bindParams, href, navigateTo };

package/dist/location.d.mts

@@ -8,13 +8,30 @@ import { ReactNode } from "react";
  * `<Router>` supplies this on its own. Under the framework the mode's runtime
  * supplies it; an application never writes this itself.
  */
-declare const PathnameProvider: ({ pathname, children }: {
+export declare const PathnameProvider: ({ pathname, children }: {
   pathname: string;
   children: ReactNode;
 }) => ReactNode;
 /**
- * Where the browser currently is, as a pathname — the one axis this package
- * owns. It reads the platform rather than a table, so it works the same in a
+ * Below this, a server render has no pathname to give: `usePathname` — and
+ * `useMatch`, which reads it — asks for the browser with `use(browser())`, so
+ * the nearest `<Suspense>` is left for the browser to render. Under
+ * `@k8ordo/framework` a fallback.tsx renders inside it; an application never
+ * writes this itself.
+ */
+export declare const BrowserPathname: ({ children }: {
+  children: ReactNode;
+}) => ReactNode;
+/**
+ * The document's pathname in the table's terms — Vite's `base` removed. A
+ * document outside its own base is a deployment that went wrong, and the
+ * pathname is shown as it is rather than failing the render over it.
+ */
+export declare const appPathname: () => string;
+/**
+ * Where the browser currently is, as a pathname in the table's terms — the
+ * one axis this package owns, with Vite's `base` removed so it compares with
+ * the patterns. It reads the platform rather than a table, so it works the same in a
  * client application and under the framework, where there is no route table
  * in the browser at all.
  *
@@ -26,6 +43,5 @@ declare const PathnameProvider: ({ pathname, children }: {
  * every search change would defeat `@k8ordo/state`'s keyed subscriptions, and
  * the split at the `?` is the whole boundary between the two packages.
  */
-declare function usePathname(): string;
-//#endregion
-export { PathnameProvider, usePathname };
+export declare function usePathname(): string;
+//#endregion

package/dist/location.mjs

@@ -1,8 +1,12 @@
 "use client";
 import { normalizePathname } from "./paths.mjs";
+import { withoutBase } from "./base.mjs";
 import { createContext, use, useMemo, useSyncExternalStore } from "react";
+import { browser } from "react-dom";
 import { jsx } from "react/jsx-runtime";
 //#region src/location.tsx
+/** Below `BrowserPathname`: the render has no pathname, the browser does. */
+const IN_BROWSER = Symbol("k8ordo.browser-pathname");
 const ServerPathname = createContext(null);
 /**
 * The pathname the render started from. A client component's first render can
@@ -19,16 +23,33 @@ const PathnameProvider = ({ pathname, children }) => {
 		children
 	});
 };
+/**
+* Below this, a server render has no pathname to give: `usePathname` — and
+* `useMatch`, which reads it — asks for the browser with `use(browser())`, so
+* the nearest `<Suspense>` is left for the browser to render. Under
+* `@k8ordo/framework` a fallback.tsx renders inside it; an application never
+* writes this itself.
+*/
+const BrowserPathname = ({ children }) => /* @__PURE__ */ jsx(ServerPathname, {
+	value: IN_BROWSER,
+	children
+});
 const subscribe = (onChange) => {
 	navigation.addEventListener("currententrychange", onChange);
 	return () => {
 		navigation.removeEventListener("currententrychange", onChange);
 	};
 };
-const readPathname = () => normalizePathname(location.pathname);
 /**
-* Where the browser currently is, as a pathname — the one axis this package
-* owns. It reads the platform rather than a table, so it works the same in a
+* The document's pathname in the table's terms — Vite's `base` removed. A
+* document outside its own base is a deployment that went wrong, and the
+* pathname is shown as it is rather than failing the render over it.
+*/
+const appPathname = () => normalizePathname(withoutBase(location.pathname) ?? location.pathname);
+/**
+* Where the browser currently is, as a pathname in the table's terms — the
+* one axis this package owns, with Vite's `base` removed so it compares with
+* the patterns. It reads the platform rather than a table, so it works the same in a
 * client application and under the framework, where there is no route table
 * in the browser at all.
 *
@@ -42,10 +63,12 @@ const readPathname = () => normalizePathname(location.pathname);
 */
 function usePathname() {
 	const fromServer = use(ServerPathname);
-	return useSyncExternalStore(subscribe, readPathname, () => {
-		if (fromServer === null) throw new Error("usePathname needs <Router> above it, or a page rendered by @k8ordo/static or @k8ordo/server");
+	if (fromServer === IN_BROWSER) use(browser("usePathname reads the URL in the browser here: the server render was for a pathname no visitor is at"));
+	return useSyncExternalStore(subscribe, appPathname, () => {
+		if (fromServer === IN_BROWSER) return appPathname();
+		if (fromServer === null) throw new Error("usePathname needs <Router> above it, or a page rendered by @k8ordo/framework");
 		return fromServer;
 	});
 }
 //#endregion
-export { PathnameProvider, usePathname };
+export { BrowserPathname, PathnameProvider, appPathname, usePathname };

package/dist/match.d.mts

@@ -7,20 +7,28 @@ import { RegisteredNavigablePattern, RegisteredPattern } from "./register.mjs";
  * to know which section of the site is showing. The pattern's own page is
  * not below it: `/x/*` matches `/x/y` and not `/x`.
  */
-type MatchablePattern = RegisteredPattern | `${RegisteredNavigablePattern}/*`;
+export type MatchablePattern = RegisteredPattern | `${RegisteredNavigablePattern}/*`;
+export type MatchOptions = {
+  /**
+   * For a `/*` pattern: count the pattern's own page as well, so `/x/*`
+   * answers `/x` too — what a section link asks when it wants to be marked
+   * on the index as much as below it. Off by default, where `/x/*` is
+   * strictly below.
+   */
+  readonly inclusive?: boolean;
+};
 /**
  * Whether a pathname is the one a pattern names, and with which params. Pure
  * and table-free — the pattern is checked against `Register`, the pathname
  * is whatever the caller holds — which is why it works where no table is
  * mounted, under the framework included.
  */
-declare const matchPath: <P extends MatchablePattern>(pattern: P, pathname: string) => ParamsOf<P> | null;
+export declare const matchPath: <P extends MatchablePattern>(pattern: P, pathname: string, options?: MatchOptions) => ParamsOf<P> | null;
 /**
  * `matchPath` against where the browser is. It re-renders when the pathname
  * changes and never on the search, like `usePathname` it is built on — so a
  * sidebar can ask "is a page under `/docs/*` showing" without a table in the
  * browser, which is the question `useRoute` cannot answer under the framework.
  */
-declare function useMatch<P extends MatchablePattern>(pattern: P): ParamsOf<P> | null;
-//#endregion
-export { MatchablePattern, matchPath, useMatch };
+export declare function useMatch<P extends MatchablePattern>(pattern: P, options?: MatchOptions): ParamsOf<P> | null;
+//#endregion