@k8ordo/router 0.1.0 → 1.1.0

package/dist/match.mjs

@@ -15,7 +15,12 @@ const decode = (value) => {
 * is whatever the caller holds — which is why it works where no table is
 * mounted, under the framework included.
 */
-const matchPath = (pattern, pathname) => {
+const matchPath = (pattern, pathname, options) => {
+	if (options?.inclusive === true && pattern.endsWith("/*")) {
+		const own = pattern.slice(0, -2);
+		const index = matchPath(own === "" ? "/" : own, pathname);
+		if (index !== null) return index;
+	}
 	const result = new URLPattern({ pathname: pattern }).exec({ pathname: normalizePathname(pathname) });
 	if (result === null) return null;
 	const params = {};
@@ -28,8 +33,8 @@ const matchPath = (pattern, pathname) => {
 * 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());
+function useMatch(pattern, options) {
+	return matchPath(pattern, usePathname(), options);
 }
 //#endregion
 export { matchPath, useMatch };

package/dist/navigation.d.mts

@@ -5,7 +5,7 @@
  * is not constructible — and this decision is the whole contract with the
  * platform.
  */
-type NavigationFacts = Pick<NavigateEvent, 'canIntercept' | 'hashChange' | 'downloadRequest' | 'navigationType'> & {
+export type NavigationFacts = Pick<NavigateEvent, 'canIntercept' | 'hashChange' | 'downloadRequest' | 'navigationType'> & {
   readonly formData: FormData | null;
 };
 /**
@@ -17,8 +17,8 @@ type NavigationFacts = Pick<NavigateEvent, 'canIntercept' | 'hashChange' | 'down
  * has no `formData`, so the search-shaped navigations `@k8ordo/state` builds
  * still come through here.
  */
-declare const isOurs: (event: NavigationFacts) => boolean;
-type NavigationHandler<T> = {
+export declare const isOurs: (event: NavigationFacts) => boolean;
+export type NavigationHandler<T> = {
   /**
    * Whether this navigation is the application's to handle. Answered
    * synchronously, because that is the only moment the platform lets anyone
@@ -28,42 +28,84 @@ type NavigationHandler<T> = {
   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. */
+  /**
+   * Applies it, as an ordinary update and not inside a transition. Render
+   * what it sets through `useDeferredValue`: the new page then renders in the
+   * background, the previous one stays on screen while it suspends, and a
+   * `<ViewTransition>` animates the swap.
+   */
   apply: (value: T) => void;
+  /**
+   * Whether a navigation that keeps the pathname on screen still has to
+   * load — the page showing reads the search, and the search moved. Without
+   * one, such a navigation is a state change: nothing loads. With one, it
+   * loads and applies like a page change, but as a state change otherwise:
+   * no scroll, no focus reset, no transition types.
+   */
+  refresh?: (url: URL) => boolean;
 };
 /**
  * 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 = {
+export type ScrollPlan = {
   kind: 'top';
 } | {
   kind: 'fragment';
   id: string;
 };
-declare const scrollPlanFor: (navigationType: NavigationType, hash: string) => ScrollPlan | null;
+export declare const scrollPlanFor: (navigationType: NavigationType, hash: string) => ScrollPlan | null;
+/**
+ * What a `<ViewTransition>` in the application learns about the navigation
+ * that changed the tree: `navigation` names any page change, and the second
+ * tag carries the kind the platform reported — `push`, `replace` or
+ * `traverse` — so a back button can animate the other way from a link. The
+ * router is the one place these can be said, because it is the one holding
+ * the event when the tree is applied.
+ */
+export declare const transitionTypesFor: (navigationType: NavigationType) => readonly string[];
+/**
+ * Where a page change in progress is going, as a pathname in the table's
+ * terms, or `null` when none is. The URL commits before the new page
+ * arrives — `usePathname` already names the destination — and the previous
+ * page stays on screen while the next one loads; this is what tells the two
+ * apart, for a link that marks itself as loading or a bar across the top. It
+ * clears when the new page is on screen, and when the navigation is given up.
+ * A state change (the search, the entry) is not a page change and sets
+ * nothing. A server render has no navigation in progress: `null`.
+ */
+export declare function usePendingPathname(): string | 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.
+ * when a new tree is applied, and not when only the URL moved. It is what an
+ * error boundary clears its failure on: leaving the page that failed is what
+ * should clear it, 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.
  */
-declare const NavigationGeneration: import("react").Context<number>;
+export 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.
+ * The navigation half of the router, on its own: intercept, load, apply, 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".
+ * A navigation that keeps the pathname on screen — `@k8ordo/state`'s
+ * `update()` — is intercepted with no handler, so its `finished` settles as
+ * soon as the navigation commits.
+ *
+ * The new tree renders at the lane `useDeferredValue` gives it, not in a
+ * transition. While any async action is pending, React holds every
+ * transition until that action ends — so an action awaiting `finished` would
+ * be waiting on itself, and a page change started beside an unrelated action
+ * would wait for it. A deferred render keeps what a transition gave (the old
+ * page stays while the new one suspends, and `<ViewTransition>` animates it)
+ * without joining the action.
  *
  * 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>): {
+export declare function useInterceptedNavigation<T>(handler: NavigationHandler<T>): {
   readonly generation: number;
 };
-//#endregion
-export { NavigationFacts, NavigationGeneration, NavigationHandler, ScrollPlan, isOurs, scrollPlanFor, useInterceptedNavigation };
+//#endregion

package/dist/navigation.mjs

@@ -1,6 +1,7 @@
 "use client";
 import { normalizePathname } from "./paths.mjs";
-import { createContext, startTransition, useEffect, useRef, useState } from "react";
+import { withoutBase } from "./base.mjs";
+import { addTransitionType, createContext, startTransition, useDeferredValue, useEffect, useEffectEvent, useLayoutEffect, useRef, useState, useSyncExternalStore } from "react";
 //#region src/navigation.ts
 /**
 * Whether this navigation is the application's to handle at all.
@@ -26,6 +27,15 @@ const scrollPlanFor = (navigationType, hash) => {
 	}
 	return { kind: "top" };
 };
+/**
+* What a `<ViewTransition>` in the application learns about the navigation
+* that changed the tree: `navigation` names any page change, and the second
+* tag carries the kind the platform reported — `push`, `replace` or
+* `traverse` — so a back button can animate the other way from a link. The
+* router is the one place these can be said, because it is the one holding
+* the event when the tree is applied.
+*/
+const transitionTypesFor = (navigationType) => ["navigation", `navigation-${navigationType}`];
 const applyScroll = (plan) => {
 	if (plan.kind === "fragment") {
 		const selector = `#${CSS.escape(plan.id)}, [name=${JSON.stringify(plan.id)}]`;
@@ -41,66 +51,126 @@ const applyScroll = (plan) => {
 	});
 };
 /**
+* The pathname a page change is loading, in the table's terms — `null` when
+* none is. One per document, like the navigation it follows: there is one
+* intercepting host, and a pending indicator anywhere reads the same answer.
+*/
+let pendingPathname = null;
+const pendingListeners = /* @__PURE__ */ new Set();
+const setPendingPathname = (value) => {
+	if (pendingPathname === value) return;
+	pendingPathname = value;
+	for (const listener of pendingListeners) listener();
+};
+const subscribePending = (onChange) => {
+	pendingListeners.add(onChange);
+	return () => {
+		pendingListeners.delete(onChange);
+	};
+};
+/**
+* Where a page change in progress is going, as a pathname in the table's
+* terms, or `null` when none is. The URL commits before the new page
+* arrives — `usePathname` already names the destination — and the previous
+* page stays on screen while the next one loads; this is what tells the two
+* apart, for a link that marks itself as loading or a bar across the top. It
+* clears when the new page is on screen, and when the navigation is given up.
+* A state change (the search, the entry) is not a page change and sets
+* nothing. A server render has no navigation in progress: `null`.
+*/
+function usePendingPathname() {
+	return useSyncExternalStore(subscribePending, () => pendingPathname, () => 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.
+* when a new tree is applied, and not when only the URL moved. It is what an
+* error boundary clears its failure on: leaving the page that failed is what
+* should clear it, 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.
 */
 const NavigationGeneration = createContext(-1);
 /**
-* 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.
+* The navigation half of the router, on its own: intercept, load, apply, 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".
+* A navigation that keeps the pathname on screen — `@k8ordo/state`'s
+* `update()` — is intercepted with no handler, so its `finished` settles as
+* soon as the navigation commits.
+*
+* The new tree renders at the lane `useDeferredValue` gives it, not in a
+* transition. While any async action is pending, React holds every
+* transition until that action ends — so an action awaiting `finished` would
+* be waiting on itself, and a page change started beside an unrelated action
+* would wait for it. A deferred render keeps what a transition gave (the old
+* page stays while the new one suspends, and `<ViewTransition>` animates it)
+* without joining the action.
 *
 * 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.
 */
 function useInterceptedNavigation(handler) {
-	const latest = useRef(handler);
-	latest.current = handler;
+	const claim = useEffectEvent((url) => handler.claim(url));
+	const refresh = useEffectEvent((url) => handler.refresh?.(url) ?? false);
+	const load = useEffectEvent((url, signal) => handler.load(url, signal));
+	const apply = useEffectEvent((value) => {
+		handler.apply(value);
+	});
 	const pending = useRef(/* @__PURE__ */ new Map());
 	const count = useRef(0);
 	const [applied, setApplied] = useState(-1);
+	const onScreen = useDeferredValue(applied);
 	const shown = useRef(null);
+	const latest = useRef(-1);
 	useEffect(() => {
 		shown.current = normalizePathname(location.pathname);
 		const onNavigate = (event) => {
 			if (!isOurs(event)) return;
 			const url = new URL(event.destination.url);
 			const pathname = normalizePathname(url.pathname);
-			if (pathname === shown.current) {
+			const inPlace = pathname === shown.current;
+			if (inPlace && !refresh(url)) {
 				event.intercept({
 					scroll: "manual",
 					focusReset: "manual"
 				});
 				return;
 			}
-			if (!latest.current.claim(url)) return;
+			if (!claim(url)) return;
 			const id = count.current++;
-			const scroll = scrollPlanFor(event.navigationType, url.hash);
+			latest.current = id;
+			setPendingPathname(normalizePathname(withoutBase(url.pathname) ?? url.pathname));
+			const settled = () => {
+				if (latest.current === id) setPendingPathname(null);
+			};
+			const scroll = inPlace ? null : scrollPlanFor(event.navigationType, url.hash);
 			event.intercept({
-				scroll: scroll === null ? "after-transition" : "manual",
+				...inPlace ? { focusReset: "manual" } : {},
+				scroll: scroll === null && !inPlace ? "after-transition" : "manual",
 				handler: async () => {
-					const value = await latest.current.load(url, event.signal);
+					event.signal.addEventListener("abort", settled, { once: true });
+					let value;
+					try {
+						value = await load(url, event.signal);
+					} catch (error) {
+						settled();
+						throw error;
+					}
 					if (event.signal.aborted) throw event.signal.reason;
 					await new Promise((resolve, reject) => {
 						pending.current.set(id, {
 							resolve,
-							scroll
+							scroll,
+							types: inPlace ? [] : transitionTypesFor(event.navigationType)
 						});
 						event.signal.addEventListener("abort", () => {
 							pending.current.delete(id);
 							reject(event.signal.reason);
 						}, { once: true });
-						startTransition(() => {
-							shown.current = pathname;
-							latest.current.apply(value);
-							setApplied(id);
-						});
+						shown.current = pathname;
+						apply(value);
+						setApplied(id);
 					});
 				}
 			});
@@ -110,14 +180,22 @@ function useInterceptedNavigation(handler) {
 			navigation.removeEventListener("navigate", onNavigate);
 		};
 	}, []);
-	useEffect(() => {
-		const entry = pending.current.get(applied);
+	useLayoutEffect(() => {
+		const entry = pending.current.get(onScreen);
 		if (entry === void 0) return;
-		pending.current.delete(applied);
+		pending.current.delete(onScreen);
 		if (entry.scroll !== null) applyScroll(entry.scroll);
+		if (latest.current === onScreen) setPendingPathname(null);
 		entry.resolve();
-	}, [applied]);
-	return { generation: applied };
+	}, [onScreen]);
+	useLayoutEffect(() => {
+		if (applied === onScreen) return;
+		const types = pending.current.get(applied)?.types ?? [];
+		startTransition(() => {
+			for (const type of types) addTransitionType(type);
+		});
+	}, [applied, onScreen]);
+	return { generation: onScreen };
 }
 //#endregion
-export { NavigationGeneration, isOurs, scrollPlanFor, useInterceptedNavigation };
+export { NavigationGeneration, isOurs, scrollPlanFor, transitionTypesFor, useInterceptedNavigation, usePendingPathname };

package/dist/not-found.d.mts

@@ -0,0 +1,11 @@
+//#region src/not-found.d.ts
+/**
+ * Says, from a page, that its pathname is not a page after all — the
+ * product the id names does not exist. Thrown, so the lines after it never
+ * run. Under `@k8ordo/framework` the nearest
+ * `not-found.tsx` answers instead, under a 404.
+ */
+export declare function notFound(): never;
+/** Whether a thrown value is what `notFound()` throws. */
+export declare const isNotFound: (value: unknown) => boolean;
+//#endregion

package/dist/not-found.mjs

@@ -0,0 +1,28 @@
+//#region src/not-found.ts
+/**
+* Branded with a registry symbol rather than recognised by class: the page
+* that throws it and the framework that catches it may hold two copies of
+* this package — the framework bundles what it runs — and two copies of a
+* class are two classes. `Symbol.for` is the one identity both share.
+*/
+const BRAND = Symbol.for("k8ordo.not-found");
+var NotFound = class extends Error {
+	[BRAND] = true;
+	constructor() {
+		super("not found");
+		this.name = "NotFound";
+	}
+};
+/**
+* Says, from a page, that its pathname is not a page after all — the
+* product the id names does not exist. Thrown, so the lines after it never
+* run. Under `@k8ordo/framework` the nearest
+* `not-found.tsx` answers instead, under a 404.
+*/
+function notFound() {
+	throw new NotFound();
+}
+/** Whether a thrown value is what `notFound()` throws. */
+const isNotFound = (value) => typeof value === "object" && value !== null && value[BRAND] === true;
+//#endregion
+export { isNotFound, notFound };

package/dist/paths.d.mts

@@ -3,20 +3,20 @@
  * The type half of the route table: everything here is derived from the
  * pattern strings by inference alone — no code generation. A pattern like
  * `'/:locale/products/:id'` yields its params (`{ locale, id }`), its
- * concrete-path type (`` `/${string}/products/${string}` ``), and its place
- * in the app-wide route union.
+ * concrete-path type (`` `/${string}/products/${string}` ``), and whether a
+ * path handed in fits it.
  */
-type SegParam<Segment extends string> = Segment extends `:${infer Name}` ? Record<Name, string> : Record<never, never>;
+type SegParam<Segment extends string> = Segment extends `:${infer Name}` ? Record<Name, string> : object;
 type SegListParams<Rest extends string> = Rest extends `${infer Segment}/${infer Tail}` ? SegParam<Segment> & SegListParams<Tail> : SegParam<Rest>;
 /** `'/:locale/products/:id'` → `{ locale: string; id: string }` */
-type ParamsOf<Pattern extends string> = Pattern extends `/${infer Rest}` ? SegListParams<Rest> : Record<never, never>;
+export type ParamsOf<Pattern extends string> = Pattern extends `/${infer Rest}` ? SegListParams<Rest> : object;
 /**
  * The shape every validation library agrees on (Standard Schema): a value
  * under `~standard` whose `types` carry the input and output. Only the
  * output is read here — the router itself never runs a schema; the framework
  * does, and this package only has to type what comes out.
  */
-type StandardSchemaLike<Output = unknown> = {
+export type StandardSchemaLike<Output = unknown> = {
   readonly '~standard': {
     readonly types?: {
       readonly output: Output;
@@ -24,26 +24,43 @@ type StandardSchemaLike<Output = unknown> = {
   };
 };
 /** What a schema produces. */
-type SchemaOutput<Schema> = Schema extends StandardSchemaLike<infer Output> ? Output : never;
+export type SchemaOutput<Schema> = Schema extends StandardSchemaLike<infer Output> ? Output : never;
 /**
  * A schema a route file may declare for the params its pattern names: its
  * output is an object whose keys are a subset of those params — a key the
  * pattern does not name has nothing to validate.
  */
-type ParamsSchemaFor<Pattern extends string> = StandardSchemaLike<Partial<Record<keyof ParamsOf<Pattern> & string, unknown>>>;
-type MergedOutput<Schemas extends readonly unknown[]> = Schemas extends readonly [infer Head, ...infer Tail] ? Omit<MergedOutput<Tail>, keyof SchemaOutput<Head>> & SchemaOutput<Head> : Record<never, never>;
+export type ParamsSchemaFor<Pattern extends string> = StandardSchemaLike<Partial<Record<keyof ParamsOf<Pattern> & string, unknown>>>;
+type MergedOutput<Schemas extends readonly unknown[]> = Schemas extends readonly [infer Head, ...infer Tail] ? Omit<MergedOutput<Tail>, keyof SchemaOutput<Head>> & SchemaOutput<Head> : object;
 /**
  * A pattern's params after the schemas along its stack have run — outer
  * layouts first, the page last — each replacing the strings it names with
  * what it produced. Params no schema names stay strings.
  */
-type ParsedParams<Pattern extends string, Schemas extends readonly unknown[]> = Omit<ParamsOf<Pattern>, keyof MergedOutput<Schemas>> & MergedOutput<Schemas>;
+export type ParsedParams<Pattern extends string, Schemas extends readonly unknown[]> = Omit<ParamsOf<Pattern>, keyof MergedOutput<Schemas>> & MergedOutput<Schemas>;
 /** `{ '/products/:id': [schema, …] }` → `{ '/products/:id': { id: number } }` */
-type ParsedParamsMap<Schemas extends Record<string, readonly unknown[]>> = { [Pattern in keyof Schemas & string]: ParsedParams<Pattern, Schemas[Pattern]>; };
+export type ParsedParamsMap<Schemas extends Record<string, readonly unknown[]>> = { [Pattern in keyof Schemas & string]: ParsedParams<Pattern, Schemas[Pattern]>; };
 type SegPath<Segment extends string> = Segment extends `:${string}` ? string : Segment;
 type SegListPath<Rest extends string> = Rest extends `${infer Segment}/${infer Tail}` ? `${SegPath<Segment>}/${SegListPath<Tail>}` : SegPath<Rest>;
 /** `'/:locale/products/:id'` → `` `/${string}/products/${string}` `` */
-type PathFor<Pattern extends string> = Pattern extends `/${infer Rest}` ? `/${SegListPath<Rest>}` : never;
+export type PathFor<Pattern extends string> = Pattern extends `/${infer Rest}` ? `/${SegListPath<Rest>}` : never;
+/**
+ * One segment of a path against one segment of a pattern, the way URLPattern
+ * reads a `:param`: any single segment that is not empty. A `${string}` in
+ * the path — a param built into a template literal — counts as one segment.
+ */
+type SegmentFits<Segment extends string, PatternSegment extends string> = PatternSegment extends `:${string}` ? Segment extends '' ? false : true : Segment extends PatternSegment ? true : false;
+type SegmentsFit<Rest extends string, PatternRest extends string> = Rest extends `${infer Segment}/${infer Tail}` ? PatternRest extends `${infer PatternSegment}/${infer PatternTail}` ? SegmentFits<Segment, PatternSegment> extends true ? SegmentsFit<Tail, PatternTail> : false : false : PatternRest extends `${string}/${string}` ? false : SegmentFits<Rest, PatternRest>;
+type FitsAny<Path extends string, Pattern extends string> = Pattern extends `/${infer PatternRest}` ? Path extends `/${infer Rest}` ? SegmentsFit<Rest, PatternRest> : false : never;
+/**
+ * `Path` when one of `Patterns` matches it segment by segment, `never` when
+ * none does. A union of paths keeps only the members that match.
+ *
+ * The path is checked against the patterns, never collected into a union of
+ * `PathFor` each pattern: `/:locale` would put `/${string}` in that union,
+ * and `/${string}` takes every path there is.
+ */
+export type PathMatching<Path extends string, Patterns extends string> = Path extends string ? true extends FitsAny<Path, Patterns> ? Path : never : never;
 /**
  * Keys that address the parent's own place instead of a place below it:
  * `'/'` (the branch's index) and `'/(name)'` (a group, which structures the
@@ -51,17 +68,17 @@ type PathFor<Pattern extends string> = Pattern extends `/${infer Rest}` ? `/${Se
  */
 type Transparent<Key extends string> = Key extends '/' ? true : Key extends `/(${string})` ? true : false;
 /** Composes a parent prefix with a child key. */
-type Join<Prefix extends string, Key extends string> = Transparent<Key> extends true ? Prefix extends '' ? '/' : Prefix : `${Prefix}${Key}`;
-declare const isGroupKey: (key: string) => boolean;
-declare const joinPattern: (prefix: string, key: string) => string;
+export type Join<Prefix extends string, Key extends string> = Transparent<Key> extends true ? Prefix extends '' ? '/' : Prefix : `${Prefix}${Key}`;
+export declare const isGroupKey: (key: string) => boolean;
+export declare const joinPattern: (prefix: string, key: string) => string;
 /**
  * URLPattern treats `/products` and `/products/` as different pathnames; the
  * router does not. Everything is matched against the slashless canonical
  * form, root excepted.
  */
-declare const normalizePathname: (pathname: string) => string;
+export declare const normalizePathname: (pathname: string) => string;
 /** What a param value may be on the way into a link: anything with one spelling. */
-type ParamValue = string | number | bigint | boolean;
-declare const buildHref: (pattern: string, params: Readonly<Record<string, unknown>> | undefined) => string;
+export type ParamValue = string | number | bigint | boolean;
+export declare const buildHref: (pattern: string, params: Readonly<Record<string, unknown>> | undefined) => string;
 //#endregion
-export { Join, ParamValue, ParamsOf, ParamsSchemaFor, ParsedParams, ParsedParamsMap, PathFor, SchemaOutput, StandardSchemaLike, buildHref, isGroupKey, joinPattern, normalizePathname };
+export {};

package/dist/register.d.mts

@@ -1,5 +1,6 @@
 import { ParamValue, ParamsOf } from "./paths.mjs";
 import { NavigablePatternOf, PatternOf, Routes, RoutesRecord } from "./define-routes.mjs";
+import { ReactNode } from "react";
 //#region src/register.d.ts
 /**
  * The app-side hook for the route table's type. An application augments this
@@ -18,15 +19,18 @@ import { NavigablePatternOf, PatternOf, Routes, RoutesRecord } from "./define-ro
  * forms. Declared as an interface — the one exception to the repository's
  * type-only rule — because declaration merging is the entire mechanism.
  */
-interface Register {}
-/** Every pattern in the registered table; any `/`-pattern before Register. */
-type RegisteredPattern = Register extends {
+export interface Register {}
+/**
+ * Every leaf pattern in the registered table — each page and each `/*`, not a
+ * prefix with no page of its own; any `/`-pattern before Register.
+ */
+export type RegisteredPattern = Register extends {
   routes: Routes<infer R extends RoutesRecord>;
-} ? PatternOf<R> : `/${string}`;
+} ? { [K in PatternOf<R>]: K; }[PatternOf<R>] : `/${string}`;
 /** Linkable patterns of the registered table (wildcards excluded). */
-type RegisteredNavigablePattern = Register extends {
+export type RegisteredNavigablePattern = Register extends {
   routes: Routes<infer R extends RoutesRecord>;
-} ? NavigablePatternOf<R> : `/${string}`;
+} ? { [K in NavigablePatternOf<R>]: K; }[NavigablePatternOf<R>] : `/${string}`;
 type RegisteredParamsMap = Register extends {
   params: infer M;
 } ? M : null;
@@ -36,11 +40,78 @@ type LooseParamsOf<P extends string> = { [K in keyof ParamsOf<P>]: ParamValue; }
  * A pattern's params as a link takes them: where the registered `params`
  * map — written by the framework from the schemas the route files declared
  * — says a page receives something, a link takes that same value (a number
- * in, a number's one spelling out); a param no schema covers takes anything
- * with one spelling. Before `Register` is augmented — a client application
- * that has not, or the framework's generated file not yet written — the
- * same loose shape applies, so a link written for a schema still compiles.
+ * in, a number's one spelling out), and a param those schemas leave alone is
+ * the string the page receives. A pattern no schema covers at all takes
+ * anything with one spelling in every param. Before `Register` is augmented
+ * — a client application that has not, or the framework's generated file
+ * not yet written — the same loose shape applies, so a link written for a
+ * schema still compiles.
+ */
+export type RegisteredParams<P extends string> = RegisteredParamsMap extends null ? LooseParamsOf<P> : P extends keyof RegisteredParamsMap ? Omit<LooseParamsOf<P>, keyof RegisteredParamsMap[P]> & RegisteredParamsMap[P] : LooseParamsOf<P>;
+/**
+ * What a page under this pattern receives as `params`: the schemas' output
+ * where the framework ran one (the registered `params` map, written by the
+ * generator), and the strings the URL carried elsewhere.
+ */
+export type RegisteredPageParams<P extends string> = Register extends {
+  params: infer M;
+} ? P extends keyof M ? M[P] : ParamsOf<P> : ParamsOf<P>;
+/**
+ * The request a route file receives — under the framework's server mode only, where the
+ * generated `Register` says so. A build into files has none, and a page that
+ * reads it fails to type-check there rather than at run time.
+ */
+type RequestProps = Register extends {
+  request: infer R;
+} ? {
+  readonly request: R;
+} : object;
+/**
+ * The search a page receives — only a page that declared what it reads, by
+ * exporting `search` (the generated `Register` says which, and what it
+ * reads into). Every other page never sees the search.
+ */
+type SearchProps<P extends string> = P extends keyof RegisteredSearch ? {
+  readonly search: RegisteredSearch[P];
+} : object;
+type RegisteredSearch = Register extends {
+  search: infer M;
+} ? M : object;
+/**
+ * The props a `page.tsx` receives under the framework, by the pattern its
+ * directory puts it under: `params` typed by the schemas along its stack,
+ * the `pathname` this render is for, in server mode the `request`,
+ * and for a page that exports `search`, the `search` it reads. The generated
+ * table checks the same thing at the import, so a page may equally declare
+ * its props inline; this is the spelling that names the pattern once and
+ * lets the schema say the rest.
+ */
+export type PageProps<P extends RegisteredPattern> = {
+  readonly params: RegisteredPageParams<P>;
+  readonly pathname: string;
+} & RequestProps & SearchProps<P>;
+/**
+ * The props a `layout.tsx` receives, by the prefix every route below it
+ * shares — only where the table also has a page at that prefix, since the
+ * constraint is a page pattern; a layout with no page of its own declares
+ * its props inline. Its params are strings whatever it declared: a
+ * `not-found.tsx` renders under it whether or not its schemas accepted, and
+ * a typed value there would be a lie.
+ */
+export type LayoutProps<P extends RegisteredPattern> = {
+  readonly params: ParamsOf<P>;
+  readonly pathname: string;
+  readonly children: ReactNode;
+} & RequestProps;
+/**
+ * What a `route.ts` method export receives under the framework, by the
+ * pattern its directory puts it under: the request, and `params` typed by
+ * the schemas along its stack — the same as a page receives. Mode-free: a
+ * build into files calls `GET` with a request of its own.
  */
-type RegisteredParams<P extends string> = RegisteredParamsMap extends null ? LooseParamsOf<P> : P extends keyof RegisteredParamsMap ? Omit<LooseParamsOf<P>, keyof RegisteredParamsMap[P]> & RegisteredParamsMap[P] : LooseParamsOf<P>;
+export type RouteContext<P extends RegisteredPattern> = {
+  readonly request: Request;
+  readonly params: RegisteredPageParams<P>;
+};
 //#endregion
-export { Register, RegisteredNavigablePattern, RegisteredParams, RegisteredPattern };
+export {};

package/dist/router.d.mts

@@ -4,7 +4,7 @@ import { RegisteredPattern } from "./register.mjs";
 import { FC, ReactNode } from "react";
 //#region src/router.d.ts
 /** Renders the next element of the matched stack — a layout's hole. */
-declare const Outlet: FC;
+export declare const Outlet: FC;
 /**
  * Mounts a route table on the Navigation API: every same-origin navigation
  * that the table claims is handled in the client, and the rest is left to the
@@ -15,18 +15,24 @@ declare const Outlet: FC;
  * shared is `useInterceptedNavigation` and the `<PathnameProvider>` this
  * mounts.
  */
-declare function Router({ routes }: {
+export declare function Router({ routes }: {
   routes: Routes;
 }): ReactNode;
-/** The winning pattern and its params, untyped — `useParams` narrows. */
-declare function useRoute(): Pick<Match, 'pattern' | 'params'>;
+/**
+ * The winning pattern and its params, untyped — `useParams` narrows. It reads
+ * the match `<Router>` provides, so under `@k8ordo/framework`, which mounts
+ * no `<Router>`, a page receives `params` as a prop and a component below it
+ * reads them with `useMatch`.
+ */
+export declare function useRoute(): Pick<Match, 'pattern' | 'params'>;
 /**
  * Typed params for the pattern this component believes it renders under —
  * inferred from the pattern literal, verified against `Register`, and read
  * from context at runtime, so no component imports the route table. The
  * belief is checked: rendering under any other pattern throws instead of
- * silently returning params of the wrong shape.
+ * silently returning params of the wrong shape. Like `useRoute`, it needs a
+ * `<Router>` above it: under `@k8ordo/framework` a page receives `params` as
+ * a prop, and a component below it reads them with `useMatch`.
  */
-declare function useParams<P extends RegisteredPattern>(pattern: P): ParamsOf<P>;
-//#endregion
-export { Outlet, Router, useParams, useRoute };
+export declare function useParams<P extends RegisteredPattern>(pattern: P): ParamsOf<P>;
+//#endregion