@k8ordo/router 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Koki Sakano
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,113 @@
+# @k8ordo/router
+
+The URL's pathname axis, owned. One route table is the application's pathname
+schema, and from it come the types, the matching, the links, and the
+navigation — over the Navigation API and URLPattern. Search params and
+history-entry state are not its business; those belong to `@k8ordo/state`,
+and the division is the URL's own `?`.
+
+Like every [k8ordo](https://ordo.k8o.me) package it assumes React 19 and Server
+Components, uses only what has reached Baseline newly available, and ships no
+polyfills or legacy fallbacks.
+
+- **Documentation**: https://ordo.k8o.me/router
+- **Design guide**: [docs/GUIDE.md](docs/GUIDE.md) — shipped inside this package
+
+## Installation
+
+```bash
+npm install @k8ordo/router
+# or
+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.
+
+## 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 |
+
+No runtime dependencies. The Navigation API and URLPattern are the platform's.
+
+## Quick Start
+
+```ts
+// routes.ts — the pathname schema, in one place
+import { defineRoutes } from '@k8ordo/router';
+
+export const routes = defineRoutes({
+  '/': Home,
+  '/products': {
+    layout: Shell,
+    error: ProductsError, // shown inside Shell when what is below throws
+    children: { '/': ProductList, '/:id': ProductPage },
+  },
+  '/*': NotFound,
+});
+```
+
+```tsx
+// app.tsx — mounted once; layouts render what they wrap through <Outlet />
+import { Outlet, Router } from '@k8ordo/router';
+
+export const App = () => <Router routes={routes} />;
+export const Shell = () => (
+  <section>
+    <nav>…</nav>
+    <Outlet />
+  </section>
+);
+```
+
+```tsx
+// anywhere — from the pattern string alone, never importing the table
+import { href, navigateTo, useMatch, useParams } from '@k8ordo/router';
+
+<a href={href('/products/:id', { id })}>…</a>; // a plain <a> is a client navigation
+navigateTo('/products'); // push; the back button undoes it
+const { id } = useParams('/products/:id'); // typed from the pattern
+const inProducts = useMatch('/products/*'); // which section is showing
+```
+
+Augment `Register` once (`interface Register { routes: typeof routes }`) and
+every pattern is checked against the table. The [design guide](docs/GUIDE.md)
+covers the grammar (params, wildcards, route groups, declaration order), what
+navigation guarantees (`finished` after the tree is on screen, scroll to top
+or fragment on a new page, superseded navigations abort), error boundaries in
+the table, and how the framework reuses the navigation half.
+
+## AI Agent Documentation
+
+The docs ship **inside the package**, so an agent always reads the exact
+version you installed — there is no snapshot to copy or re-sync on upgrade.
+
+Point your agent at them once by pasting this into your project's `CLAUDE.md` /
+`AGENTS.md`:
+
+```markdown
+Use `@k8ordo/router` for routing. Before touching routes or links, read
+`node_modules/@k8ordo/router/docs/GUIDE.md`. The route table is the one
+place the pathname space is declared; pages build links with
+`href(pattern, params)` from the pattern string and never import the table.
+There is no `<Link>` — a plain `<a>` is a client navigation. Search params
+are `@k8ordo/state`'s, never the router's.
+```
+
+What each surface gives an agent:
+
+| Surface                    | Where                                          |
+| -------------------------- | ---------------------------------------------- |
+| Design guide (entry point) | `node_modules/@k8ordo/router/docs/GUIDE.md`    |
+| Docs index for LLMs        | `docs/llms.txt` · https://ordo.k8o.me/llms.txt |
+| Markdown twin on the web   | https://ordo.k8o.me/router/docs/GUIDE.md       |
+
+## License
+
+MIT License - see [LICENSE](https://github.com/k35o/k8ordo/blob/main/LICENSE) for details.

package/dist/boundary.d.mts

@@ -0,0 +1,24 @@
+import { ComponentType, ReactNode } from "react";
+//#region src/boundary.d.ts
+/**
+ * What a route table's `error` component receives: what was thrown, and a
+ * way to try the subtree again in place.
+ */
+type ErrorProps = {
+  readonly error: unknown;
+  readonly reset: () => void;
+};
+type ErrorComponent = ComponentType<ErrorProps>;
+type CatchProps = {
+  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.
+ */
+declare const RouteErrorBoundary: ({ fallback, children }: CatchProps) => ReactNode;
+//#endregion
+export { ErrorComponent, ErrorProps, RouteErrorBoundary };

package/dist/boundary.mjs

@@ -0,0 +1,44 @@
+"use client";
+import { NavigationGeneration } from "./navigation.mjs";
+import { Component, Suspense, createElement, use } from "react";
+//#region src/boundary.tsx
+var Catch = class extends Component {
+	state = {
+		error: void 0,
+		failed: false
+	};
+	static getDerivedStateFromError(error) {
+		return {
+			error,
+			failed: true
+		};
+	}
+	reset = () => {
+		this.setState({
+			error: void 0,
+			failed: false
+		});
+	};
+	render() {
+		if (!this.state.failed) return this.props.children;
+		return createElement(this.props.fallback, {
+			error: this.state.error,
+			reset: this.reset
+		});
+	}
+};
+/**
+* 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.
+*/
+const RouteErrorBoundary = ({ fallback, children }) => {
+	const generation = use(NavigationGeneration);
+	return createElement(Suspense, { fallback: null }, createElement(Catch, {
+		key: generation,
+		fallback
+	}, children));
+};
+//#endregion
+export { RouteErrorBoundary };

package/dist/define-routes.d.mts

@@ -0,0 +1,67 @@
+import { ErrorComponent } from "./boundary.mjs";
+import { Join, PathFor } from "./paths.mjs";
+import { ComponentType, ReactNode } from "react";
+//#region src/define-routes.d.ts
+/**
+ * Any component, whatever props it declares. The table is written once and
+ * rendered by different renderers — a client app renders leaves with no
+ * props, the framework hands server components their `params` and layouts
+ * 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>;
+/**
+ * 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`.
+ */
+type RouteNode = RouteComponent | {
+  layout?: RouteComponent;
+  error?: ErrorComponent;
+  children: RoutesRecord;
+};
+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;
+/** Patterns a link can point at — wildcards are matched, never linked. */
+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.
+ */
+type RouteOf<D> = D extends Routes<infer R> ? PathFor<NavigablePatternOf<R>> : never;
+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> = {
+  kind: 'routes';
+  /** The table as passed. */
+  record: R;
+  /**
+   * Matches a pathname in declaration order, first match wins — precedence
+   * is what you wrote, not a specificity ranking to second-guess. The one
+   * operation that needs the table's value: links and navigation build from
+   * the pattern string alone (`href` / `navigateTo`), so only `<Router>`
+   * ever holds this object.
+   *
+   * `accept` lets the caller decline a match, in which case the walk goes
+   * on to the next pattern as if this one had not fit — a param a schema
+   * refuses is a pathname the pattern does not answer, and what answers it
+   * instead is whatever the table declares next, the catch-all included.
+   */
+  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 };

package/dist/define-routes.mjs

@@ -0,0 +1,84 @@
+import { isGroupKey, joinPattern, normalizePathname } from "./paths.mjs";
+import { RouteErrorBoundary } from "./boundary.mjs";
+import { createElement } from "react";
+//#region src/define-routes.ts
+const isBranch = (node) => typeof node === "object" && "children" in node;
+/**
+* A branch's `error` becomes an element of the stack — after the layout, so
+* it wraps what the layout wraps. It takes what any renderer passes and
+* renders what it is given; a renderer that passes nothing (the client
+* router, which nests through `<Outlet />`) is told so by the absence of
+* `children`, and the boundary leaves the hole to the next element.
+*/
+const boundaryFor = (fallback) => {
+	const Boundary = ({ children }) => createElement(RouteErrorBoundary, { fallback }, children === void 0 ? outlet() : children);
+	return Boundary;
+};
+const decode = (value) => {
+	try {
+		return decodeURIComponent(value);
+	} catch {
+		return value;
+	}
+};
+/**
+* What a boundary renders when a renderer hands it no children. Set once by
+* the client router, which is the one renderer that nests by context rather
+* than by prop; the framework always passes `children`.
+*/
+let outlet = () => null;
+const setBoundaryOutlet = (render) => {
+	outlet = render;
+};
+function defineRoutes(record) {
+	const entries = [];
+	const seen = /* @__PURE__ */ new Set();
+	const walk = (current, prefix, stack) => {
+		for (const [key, node] of Object.entries(current)) {
+			if (!key.startsWith("/")) throw new TypeError(`route pattern "${key}" must start with "/"`);
+			if (key.includes("(") && !isGroupKey(key)) throw new TypeError(`route group "${key}" must be "/(name)" and nothing else — a regular expression is not part of the grammar`);
+			if (isGroupKey(key) && !isBranch(node)) throw new TypeError(`route group "${key}" must have children`);
+			const pattern = joinPattern(prefix, key);
+			if (isBranch(node)) {
+				const below = [
+					...stack,
+					...node.layout === void 0 ? [] : [node.layout],
+					...node.error === void 0 ? [] : [boundaryFor(node.error)]
+				];
+				walk(node.children, pattern === "/" ? "" : pattern, below);
+			} else {
+				if (seen.has(pattern)) throw new TypeError(`route pattern "${pattern}" is declared twice`);
+				seen.add(pattern);
+				entries.push({
+					pattern,
+					matcher: new URLPattern({ pathname: pattern }),
+					stack: [...stack, node]
+				});
+			}
+		}
+	};
+	walk(record, "", []);
+	const match = (pathname, accept) => {
+		const normalized = normalizePathname(pathname);
+		for (const entry of entries) {
+			const result = entry.matcher.exec({ pathname: normalized });
+			if (result === null) continue;
+			const params = {};
+			for (const [name, value] of Object.entries(result.pathname.groups)) if (!/^\d+$/u.test(name) && value !== void 0) params[name] = decode(value);
+			const found = {
+				pattern: entry.pattern,
+				params,
+				stack: entry.stack
+			};
+			if (accept === void 0 || accept(found)) return found;
+		}
+		return null;
+	};
+	return {
+		kind: "routes",
+		record,
+		match
+	};
+}
+//#endregion
+export { defineRoutes, setBoundaryOutlet };

package/dist/index.d.mts

@@ -0,0 +1,10 @@
+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 { 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 };

package/dist/index.mjs

@@ -0,0 +1,8 @@
+import { normalizePathname } from "./paths.mjs";
+import { NavigationGeneration, useInterceptedNavigation } from "./navigation.mjs";
+import { defineRoutes } from "./define-routes.mjs";
+import { href, navigateTo } from "./links.mjs";
+import { PathnameProvider, usePathname } from "./location.mjs";
+import { matchPath, useMatch } from "./match.mjs";
+import { Outlet, Router, useParams, useRoute } from "./router.mjs";
+export { NavigationGeneration, Outlet, PathnameProvider, Router, defineRoutes, href, matchPath, navigateTo, normalizePathname, useInterceptedNavigation, useMatch, useParams, usePathname, useRoute };

package/dist/links.d.mts

@@ -0,0 +1,31 @@
+import { PathFor } 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 = {
+  /**
+   * `push` by default: going to a page is what the back button undoes —
+   * the opposite default from a state refinement.
+   */
+  history?: 'push' | 'replace';
+};
+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).
+ */
+declare const href: <P extends RegisteredNavigablePattern>(pattern: P, ...params: HrefArgs<RegisteredParams<P>>) => PathFor<P>;
+/**
+ * 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 };

package/dist/links.mjs

@@ -0,0 +1,27 @@
+import { buildHref } from "./paths.mjs";
+//#region src/links.ts
+/**
+* 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).
+*/
+const href = (pattern, ...params) => buildHref(pattern, params[0]);
+/**
+* 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()`.
+*/
+const 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 navigation.navigate(buildHref(pattern, params), { history: options?.history ?? "push" });
+};
+//#endregion
+export { href, navigateTo };

package/dist/location.d.mts

@@ -0,0 +1,31 @@
+import { ReactNode } from "react";
+//#region src/location.d.ts
+/**
+ * The pathname the render started from. A client component's first render can
+ * happen where there is no Navigation API — on the server, and again during
+ * hydration — so the value has to arrive from the renderer that did know it.
+ *
+ * `<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 }: {
+  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
+ * client application and under the framework, where there is no route table
+ * in the browser at all.
+ *
+ * It is not `useRoute`: this answers "what is the URL", which a navigation
+ * link needs, while `useRoute` answers "which route won", which only a table
+ * can say.
+ *
+ * The search string is deliberately absent. A component that re-rendered on
+ * 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 };

package/dist/location.mjs

@@ -0,0 +1,51 @@
+"use client";
+import { normalizePathname } from "./paths.mjs";
+import { createContext, use, useMemo, useSyncExternalStore } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/location.tsx
+const ServerPathname = createContext(null);
+/**
+* The pathname the render started from. A client component's first render can
+* happen where there is no Navigation API — on the server, and again during
+* hydration — so the value has to arrive from the renderer that did know it.
+*
+* `<Router>` supplies this on its own. Under the framework the mode's runtime
+* supplies it; an application never writes this itself.
+*/
+const PathnameProvider = ({ pathname, children }) => {
+	const value = useMemo(() => normalizePathname(pathname), [pathname]);
+	return /* @__PURE__ */ jsx(ServerPathname, {
+		value,
+		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
+* client application and under the framework, where there is no route table
+* in the browser at all.
+*
+* It is not `useRoute`: this answers "what is the URL", which a navigation
+* link needs, while `useRoute` answers "which route won", which only a table
+* can say.
+*
+* The search string is deliberately absent. A component that re-rendered on
+* every search change would defeat `@k8ordo/state`'s keyed subscriptions, and
+* the split at the `?` is the whole boundary between the two packages.
+*/
+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");
+		return fromServer;
+	});
+}
+//#endregion
+export { PathnameProvider, usePathname };

package/dist/match.d.mts

@@ -0,0 +1,26 @@
+import { ParamsOf } from "./paths.mjs";
+import { RegisteredNavigablePattern, RegisteredPattern } from "./register.mjs";
+//#region src/match.d.ts
+/**
+ * A pattern from the table, or a table pattern followed by `/*` to mean
+ * "everything below it" — the shape a navigation asks about when it wants
+ * 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}/*`;
+/**
+ * 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;
+/**
+ * `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 };

package/dist/match.mjs

@@ -0,0 +1,35 @@
+"use client";
+import { normalizePathname } from "./paths.mjs";
+import { usePathname } from "./location.mjs";
+//#region src/match.ts
+const decode = (value) => {
+	try {
+		return decodeURIComponent(value);
+	} catch {
+		return value;
+	}
+};
+/**
+* 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.
+*/
+const matchPath = (pattern, pathname) => {
+	const result = new URLPattern({ pathname: pattern }).exec({ pathname: normalizePathname(pathname) });
+	if (result === null) return null;
+	const params = {};
+	for (const [name, value] of Object.entries(result.pathname.groups)) if (!/^\d+$/u.test(name) && value !== void 0) params[name] = decode(value);
+	return params;
+};
+/**
+* `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.
+*/
+function useMatch(pattern) {
+	return matchPath(pattern, usePathname());
+}
+//#endregion
+export { matchPath, useMatch };

package/dist/navigation.d.mts

@@ -0,0 +1,69 @@
+//#region src/navigation.d.ts
+/**
+ * What the decision below reads. Spelled out rather than taking the event,
+ * because a `NavigateEvent` cannot be constructed in a test — its destination
+ * is not constructible — and this decision is the whole contract with the
+ * platform.
+ */
+type NavigationFacts = Pick<NavigateEvent, 'canIntercept' | 'hashChange' | 'downloadRequest' | 'navigationType'> & {
+  readonly formData: FormData | null;
+};
+/**
+ * Whether this navigation is the application's to handle at all.
+ *
+ * A reload is a request for a fresh document, and a POST submission carries a
+ * body only the server can act on: intercepting either means silently doing
+ * nothing where the platform would have done the obvious thing. A GET form
+ * has no `formData`, so the search-shaped navigations `@k8ordo/state` builds
+ * still come through here.
+ */
+declare const isOurs: (event: NavigationFacts) => boolean;
+type NavigationHandler<T> = {
+  /**
+   * Whether this navigation is the application's to handle. Answered
+   * synchronously, because that is the only moment the platform lets anyone
+   * intercept. Saying no leaves a real document load — and a real 404 — to
+   * the server.
+   */
+  claim: (url: URL) => boolean;
+  /** Produces whatever the application renders for this URL. */
+  load: (url: URL, signal: AbortSignal) => T | Promise<T>;
+  /** Applies it. Called inside a transition. */
+  apply: (value: T) => void;
+};
+/**
+ * Where the viewport goes once the new page is on screen. A traversal is the
+ * browser's to restore, so it carries no instruction; a fragment scrolls to
+ * its target; anything else starts at the top, the way a document load does.
+ */
+type ScrollPlan = {
+  kind: 'top';
+} | {
+  kind: 'fragment';
+  id: string;
+};
+declare const scrollPlanFor: (navigationType: NavigationType, hash: string) => ScrollPlan | null;
+/**
+ * Which navigation put the tree on screen — a number that changes exactly
+ * when a new tree is applied, and not when only the URL moved. It is the
+ * identity an error boundary keys on: leaving the page that failed is what
+ * should clear the failure, and the URL commits before the tree arrives, so
+ * the pathname would clear it one render too early and let the old tree
+ * fail again under the new key.
+ */
+declare const NavigationGeneration: import("react").Context<number>;
+/**
+ * The navigation half of the router, on its own: intercept, load, apply in a
+ * transition, and resolve the platform's handler only once the new tree is on
+ * screen — which is what makes `navigation.navigate().finished` mean "the
+ * page is showing", and what `@k8ordo/state`'s `update().finished` inherits.
+ *
+ * What gets loaded is the caller's business: a route table match for a plain
+ * client app, an RSC payload under the framework. Neither has to teach this
+ * hook anything about the other.
+ */
+declare function useInterceptedNavigation<T>(handler: NavigationHandler<T>): {
+  readonly generation: number;
+};
+//#endregion
+export { NavigationFacts, NavigationGeneration, NavigationHandler, ScrollPlan, isOurs, scrollPlanFor, useInterceptedNavigation };