aberdeen 1.17.1 → 2.0.1

package/src/route.ts

@@ -1,11 +1,9 @@
-import A, {leakScope} from "./aberdeen.js";
-
 type NavType = "load" | "back" | "forward" | "go" | "push";
 
 /**
 * The class for the global `route` object.
 */
-export interface Route {
+export interface RouteState {
 	/** The current path of the URL as a string. For instance `"/"` or `"/users/123/feed"`. Paths are normalized to always start with a `/` and never end with a `/` (unless it's the root path). */
 	path: string;
 	/** An convenience array containing path segments, mapping to `path`. For instance `[]` (for `"/"`) or `['users', '123', 'feed']` (for `"/users/123/feed"`). */
@@ -28,446 +26,474 @@ export interface Route {
 	nav: NavType;
 }
 
-let log: (...args: any) => void = () => {};
+type RouteTarget = string | (string|number)[] | Partial<Omit<Omit<RouteState,"p">,"search"> & {
+	/** An convenience array containing path segments, mapping to `path`. For instance `[]` (for `"/"`) or `['users', 123, 'feed']` (for `"/users/123/feed"`). Values may be integers but will be converted to strings.*/
+	p: (string|number)[],
+	/** The query string interpreted as search parameters. So `"a=x&b=y"` becomes `{a: "x", b: "y", c: 42}`. Values may be integers but will be converted to strings. */
+	search: Record<string,string|number>,
+}>;
 
 /**
- * Configure logging on route changes.
- * @param value `true` to enable logging to console, `false` to disable logging, or a custom logging function. Defaults to `false`.
+ * The router API returned by {@link createRoute}, bound to a specific Aberdeen instance's window.
  */
-export function setLog(value: boolean | ((...args: any[]) => void)) {
-	if (value === true) {
-		log = console.log.bind(console, 'aberdeen router');
-	} else if (value === false) {
-		log = () => {};
-	} else {
-		log = value;
-	}
-}
-
-declare const ABERDEEN_FAKE_WINDOW: Window | undefined;
-const windowE = typeof ABERDEEN_FAKE_WINDOW !== 'undefined'? ABERDEEN_FAKE_WINDOW : window;
-const locationE = windowE.location;
-const historyE = windowE.history;
-
-function getRouteFromBrowser(): Route {
-	return toCanonRoute({
-		path: locationE.pathname,
-		hash: locationE.hash,
-		search: Object.fromEntries(new URLSearchParams(locationE.search)),
-		state: 	historyE.state?.state || {},
-	}, "load", (historyE.state?.stack?.length || 0) + 1);
+export interface RouteApi {
+	/**
+	* The global {@link RouteState} object reflecting the current URL and browser history state. Changes you make to this affect the current browser history item (modifying the URL if needed).
+	*/
+	current: RouteState;
+	/**
+	 * Configure logging on route changes.
+	 * @param value `true` to enable logging to console, `false` to disable logging, or a custom logging function. Defaults to `false`.
+	 */
+	setLog(value: boolean | ((...args: any[]) => void)): void;
+	/**
+	* Navigate to a new URL by pushing a new history entry.
+	* 
+	* Note that this happens synchronously, immediately updating `route` and processing any reactive updates based on that.
+	* 
+	* @param target A subset of the {@link RouteState} properties to navigate to. If neither `p` nor `path` is given, the current path is used. For other properties, an empty/default value is assumed if not given. For convenience:
+	* - You may pass a string instead of an object, which is interpreted as the `path`.
+	* - You may pass an array instead of an object, which is interpreted as the `p` array.
+	* - If you pass `p`, it may contain numbers, which will be converted to strings.
+	* - If you pass `search`, its values may be numbers, which will be converted to strings.
+	* 
+	* Examples:
+	* ```js
+	* // Navigate to /users/123
+	* route.go("/users/123");
+	* 
+	* // Navigate to /users/123?tab=feed#top
+	* route.go({p: ["users", 123], search: {tab: "feed"}, hash: "top"});
+	* ```
+	*/
+	go(target: RouteTarget, nav?: NavType): void;
+	/**
+	 * Returns `true` if the current route matches `target`.
+	 *
+	 * Path must match exactly. Any search params specified in `target` must be present
+	 * in the current URL, but extra params in the current URL are allowed.
+	 *
+	 * Reactive: only reevaluates when the path changes to/from the target path, and
+	 * when target k/v search pairs are (un)set.
+	 * 
+	 * Primary usage: 'active' status for menu items.
+	 *
+	 * @example
+	 * ```js
+	 * // This example assumes interceptLinks() has been called
+	 * A('a.my-button text=Users href=/users .is-active=', route.matchCurrent('/users'));
+	 * 
+	 * // Alternatively a route object can be given
+	 * route.matchCurrent({path: '/users', search: {tab: 'profile'}});
+	 * ```
+	 */
+	matchCurrent(target: RouteTarget): boolean;
+	/**
+	 * Modify the current route by merging `target` into it (using {@link aberdeen!Aberdeen.merge | A.merge}), pushing a new history entry.
+	 * 
+	 * This is useful for things like opening modals or side panels, where you want a browser back action to return to the previous state.
+	 * 
+	 * @param target Same as for {@link go}, but merged into the current route instead deleting all state.
+	 * @param nav The navigation type to use. Defaults to `undefined`, meaning the navigation type is unchanged from the current route,
+	 *  preventing unwanted page transition animations.
+	 */
+	push(target: RouteTarget, nav?: NavType): void;
+	/**
+	 * Try to go back in history to the first entry that matches the given target. If none is found, the given state will replace the current page. This is useful for "cancel" or "close" actions that should return to the previous page if possible, but create a new page if not (for instance when arriving at the current page through a direct link).
+	 * 
+	 * Consider using {@link up} to go up in the path hierarchy.
+	 * 
+	 * @param target The target route to go back to. May be a subset of {@link RouteState}, or a string (for `path`), or an array of strings (for `p`).
+	 */
+	back(target?: RouteTarget): void;
+	/**
+	* Navigate up in the path hierarchy, by going back to the first history entry
+	* that has a shorter path than the current one. If there's none, we just shorten
+	* the current path.
+	* 
+	* Note that going back in browser history happens asynchronously, so `route` will not be updated immediately.
+	*/
+	up(stripCount?: number): void;
+	/** @internal */
+	reset(): void;
+	/**
+	* Restore and store the vertical and horizontal scroll position for
+	* the parent element to the page state.
+	*
+	* @param {string} name - A unique (within this page) name for this
+	* scrollable element. Defaults to 'main'.
+	*
+	* The scroll position will be persisted in `route.aux.scroll.<name>`.
+	*/
+	persistScroll(name?: string): void;
+	/**
+	 * Intercept clicks and Enter key presses on links (`<a>` tags) and use Aberdeen routing
+	 * instead of browser navigation for local paths (paths without a protocol or host).
+	 * 
+	 * This allows you to use regular HTML anchor tags for navigation without needing to
+	 * manually attach click handlers to each link.
+	 * 
+	 * @example
+	 * ```js
+	 * // In your root component:
+	 * route.interceptLinks();
+	 * 
+	 * // Now you can use regular anchor tags:
+	 * A('a text=About href=/corporate/about');
+	 * ```
+	 */
+	interceptLinks(): void;
 }
 
 /**
-* Deep compare `a` and `b`. If `partial` is true, objects contained in `b` may be a subset
-* of their counterparts in `a` and still be considered equal.
-*/
-function equal(a: any, b: any, partial: boolean): boolean {
-	if (a===b) return true;
-	if (typeof a !== "object" || !a || typeof b !== "object" || !b) return false; // otherwise they would have been equal
-	if (a.constructor !== b.constructor) return false;
-	if (b instanceof Array) {
-		if (a.length !== b.length) return false;
-		for(let i = 0; i < b.length; i++) {
-			if (!equal(a[i], b[i], partial)) return false;
-		}
-	} else {
-		for(const k of Object.keys(b)) {
-			if (!equal(a[k], b[k], partial)) return false;
+ * Initialise routing for an Aberdeen instance and return the router API, bound to that
+ * instance's window. In the browser, use the default instance: `init(A)`. For server-side
+ * rendering, pass the instance provided by `aberdeen/server`'s render callback.
+ *
+ * @param A An Aberdeen instance (the default export of `aberdeen`, or one from `init`).
+ */
+export function createRoute(A: any): RouteApi {
+
+	const window = A.window;
+	const location = window.location;
+	const history = window.history;
+
+	let log: (...args: any) => void = () => {};
+
+	function setLog(value: boolean | ((...args: any[]) => void)) {
+		if (value === true) {
+			log = console.log.bind(console, 'aberdeen router');
+		} else if (value === false) {
+			log = () => {};
+		} else {
+			log = value;
 		}
-		if (!partial) {
-			for(const k of Object.keys(a)) {
-				if (!b.hasOwnProperty(k)) return false;
+	}
+
+	function getRouteFromBrowser(): RouteState {
+		return toCanonRoute({
+			path: location.pathname,
+			hash: location.hash,
+			search: Object.fromEntries(new URLSearchParams(location.search)),
+			state: 	history.state?.state || {},
+		}, "load", (history.state?.stack?.length || 0) + 1);
+	}
+
+	/**
+	* Deep compare `a` and `b`. If `partial` is true, objects contained in `b` may be a subset
+	* of their counterparts in `a` and still be considered equal.
+	*/
+	function equal(a: any, b: any, partial: boolean): boolean {
+		if (a===b) return true;
+		if (typeof a !== "object" || !a || typeof b !== "object" || !b) return false; // otherwise they would have been equal
+		if (a.constructor !== b.constructor) return false;
+		if (b instanceof Array) {
+			if (a.length !== b.length) return false;
+			for(let i = 0; i < b.length; i++) {
+				if (!equal(a[i], b[i], partial)) return false;
+			}
+		} else {
+			for(const k of Object.keys(b)) {
+				if (!equal(a[k], b[k], partial)) return false;
+			}
+			if (!partial) {
+				for(const k of Object.keys(a)) {
+					if (!b.hasOwnProperty(k)) return false;
+				}
 			}
 		}
+		return true;
 	}
-	return true;
-}
-
-function getUrl(target: Route) {
-	const search = new URLSearchParams(target.search).toString();
-	return (search ? `${target.path}?${search}` : target.path) + target.hash;
-}
 
-function toCanonRoute(target: Partial<Route>, nav: NavType, depth: number): Route {
-	let path = target.path || (target.p || []).join("/") || "/";
-	path = (""+path).replace(/\/+$/, "");
-	if (!path.startsWith("/")) path = `/${path}`;
-	
-	return {
-		path,
-		hash: target.hash && target.hash !=="#" ? (target.hash.startsWith("#") ? target.hash : "#" + target.hash) : "",
-		p: path.length > 1 ? path.slice(1).replace(/\/+$/, "").split("/") : [],
-		nav,
-		search: typeof target.search === 'object' && target.search ? A.clone(target.search) : {},
-		state: typeof target.state === 'object' && target.state ? A.clone(target.state) : {},
-		depth,
-	};
-}
+	function getUrl(target: RouteState) {
+		const search = new URLSearchParams(target.search).toString();
+		return (search ? `${target.path}?${search}` : target.path) + target.hash;
+	}
 
+	function toCanonRoute(target: Partial<RouteState>, nav: NavType, depth: number): RouteState {
+		let path = target.path || (target.p || []).join("/") || "/";
+		path = (""+path).replace(/\/+$/, "");
+		if (!path.startsWith("/")) path = `/${path}`;
+		
+		return {
+			path,
+			hash: target.hash && target.hash !=="#" ? (target.hash.startsWith("#") ? target.hash : "#" + target.hash) : "",
+			p: path.length > 1 ? path.slice(1).replace(/\/+$/, "").split("/") : [],
+			nav,
+			search: typeof target.search === 'object' && target.search ? A.clone(target.search) : {},
+			state: typeof target.state === 'object' && target.state ? A.clone(target.state) : {},
+			depth,
+		};
+	}
 
-type RouteTarget = string | (string|number)[] | Partial<Omit<Omit<Route,"p">,"search"> & {
-	/** An convenience array containing path segments, mapping to `path`. For instance `[]` (for `"/"`) or `['users', 123, 'feed']` (for `"/users/123/feed"`). Values may be integers but will be converted to strings.*/
-	p: (string|number)[],
-	/** The query string interpreted as search parameters. So `"a=x&b=y"` becomes `{a: "x", b: "y", c: 42}`. Values may be integers but will be converted to strings. */
-	search: Record<string,string|number>,
-}>;
 
-function targetToPartial(target: RouteTarget, undefinedOnExternal: true): Partial<Route> | undefined;
-function targetToPartial(target: RouteTarget): Partial<Route>;
+	function targetToPartial(target: RouteTarget, undefinedOnExternal: true): Partial<RouteState> | undefined;
+	function targetToPartial(target: RouteTarget): Partial<RouteState>;
 
 
-function targetToPartial(target: RouteTarget, undefinedOnExternal: boolean=false) {
-	// Convert shortcut values to objects
-	if (typeof target === 'string') {
-		// Parse using URL to handle both absolute and relative paths correctly		
-		const url = new URL(target, locationE.href);
-		if (url.host !== locationE.host) {
-			if (undefinedOnExternal) return;
-			throw new Error(`Unexpected external URL: ${url.host} != ${locationE.host}`);
+	function targetToPartial(target: RouteTarget, undefinedOnExternal: boolean=false) {
+		// Convert shortcut values to objects
+		if (typeof target === 'string') {
+			// Parse using URL to handle both absolute and relative paths correctly		
+			const url = new URL(target, location.href);
+			if (url.host !== location.host) {
+				if (undefinedOnExternal) return;
+				throw new Error(`Unexpected external URL: ${url.host} != ${location.host}`);
+			}
+			target = {
+				path: url.pathname,
+				search: Object.fromEntries(url.searchParams),
+				hash: url.hash,
+			};
+		} else if (target instanceof Array) {
+			target = {p: target};
 		}
-		target = {
-			path: url.pathname,
-			search: Object.fromEntries(url.searchParams),
-			hash: url.hash,
-		};
-	} else if (target instanceof Array) {
-		target = {p: target};
-	}
-	// Convert numbers in p and search to strings
-	if (target.p) {
-		target.p = target.p.map(String);
-	}
-	if (target.search) {
-		for(const key of Object.keys(target.search)) {
-			target.search[key] = String(target.search[key]);
+		// Convert numbers in p and search to strings
+		if (target.p) {
+			target.p = target.p.map(String);
 		}
+		if (target.search) {
+			for(const key of Object.keys(target.search)) {
+				target.search[key] = String(target.search[key]);
+			}
+		}
+		return target as Partial<RouteState>;
 	}
-	return target as Partial<Route>;
-}
 
 
-/**
-* Navigate to a new URL by pushing a new history entry.
-* 
-* Note that this happens synchronously, immediately updating `route` and processing any reactive updates based on that.
-* 
-* @param target A subset of the {@link Route} properties to navigate to. If neither `p` nor `path` is given, the current path is used. For other properties, an empty/default value is assumed if not given. For convenience:
-* - You may pass a string instead of an object, which is interpreted as the `path`.
-* - You may pass an array instead of an object, which is interpreted as the `p` array.
-* - If you pass `p`, it may contain numbers, which will be converted to strings.
-* - If you pass `search`, its values may be numbers, which will be converted to strings.
-* 
-* Examples:
-* ```js
-* // Navigate to /users/123
-* route.go("/users/123");
-* 
-* // Navigate to /users/123?tab=feed#top
-* route.go({p: ["users", 123], search: {tab: "feed"}, hash: "top"});
-* ```
-*/
-export function go(target: RouteTarget, nav: NavType = "go"): void {
-	pendingGoOffset = 0;
-	const stack: string[] = historyE.state?.stack || [];
-
-	prevStack = stack.concat(JSON.stringify(A.unproxy(current)));
-	
-	const newRoute: Route = toCanonRoute(targetToPartial(target), nav, prevStack.length + 1);
-	A.copy(current, newRoute);
-	
-	log(nav, newRoute);
-	historyE.pushState({state: newRoute.state, stack: prevStack}, "", getUrl(newRoute));
-	
-	A.runQueue();
-}
-
-/**
- * Returns `true` if the current route matches `target`.
- *
- * Path must match exactly. Any search params specified in `target` must be present
- * in the current URL, but extra params in the current URL are allowed.
- *
- * Reactive: only reevaluates when the path changes to/from the target path, and
- * when target k/v search pairs are (un)set.
- * 
- * Primary usage: 'active' status for menu items.
- *
- * @example
- * ```js
- * // This example assumes interceptLinks() has been called
- * A('a.my-button text=Users href=/users .is-active=', route.matchCurrent('/users'));
- * 
- * // Alternatively a route object can be given
- * route.matchCurrent({path: '/users', search: {tab: 'profile'}});
- * ```
- */
-export function matchCurrent(target: RouteTarget): boolean {
-	const partial = targetToPartial(target, true);
-	if (!partial) return false; // External link
+	function go(target: RouteTarget, nav: NavType = "go"): void {
+		pendingGoOffset = 0;
+		const stack: string[] = history.state?.stack || [];
 
-	if (partial.path != null || partial.p != null) {
-		let path = partial.path || (partial.p || []).join("/") || "/";
-		path = (""+path).replace(/\/+$/, "");
-		if (!path.startsWith("/")) path = `/${path}`;
-		if (!currentRouteParts[path]) return false;
+		prevStack = stack.concat(JSON.stringify(A.unproxy(current)));
+		
+		const newRoute: RouteState = toCanonRoute(targetToPartial(target), nav, prevStack.length + 1);
+		A.copy(current, newRoute);
+		
+		log(nav, newRoute);
+		history.pushState({state: newRoute.state, stack: prevStack}, "", getUrl(newRoute));
+		
+		A.runQueue();
 	}
 
-	if (partial.search) {
-		for(const [k,v] of Object.entries(partial.search)) {
-			if (!currentRouteParts[`${k}=${v}`]) return false;
+	function matchCurrent(target: RouteTarget): boolean {
+		const partial = targetToPartial(target, true);
+		if (!partial) return false; // External link
+
+		if (partial.path != null || partial.p != null) {
+			let path = partial.path || (partial.p || []).join("/") || "/";
+			path = (""+path).replace(/\/+$/, "");
+			if (!path.startsWith("/")) path = `/${path}`;
+			if (!currentRouteParts[path]) return false;
 		}
+
+		if (partial.search) {
+			for(const [k,v] of Object.entries(partial.search)) {
+				if (!currentRouteParts[`${k}=${v}`]) return false;
+			}
+		}
+		return true;
 	}
-	return true;
-}
 
-/**
- * Modify the current route by merging `target` into it (using {@link aberdeen.merge | A.merge}), pushing a new history entry.
- * 
- * This is useful for things like opening modals or side panels, where you want a browser back action to return to the previous state.
- * 
- * @param target Same as for {@link go}, but merged into the current route instead deleting all state.
- * @param nav The navigation type to use. Defaults to `undefined`, meaning the navigation type is unchanged from the current route,
- *  preventing unwanted page transition animations.
- */
-export function push(target: RouteTarget, nav?: NavType): void {
-	const c = A.clone(A.unproxy(current));
-	A.merge(c, targetToPartial(target));
-	go(c, nav || c.nav);
-}
+	function push(target: RouteTarget, nav?: NavType): void {
+		const c = A.clone(A.unproxy(current));
+		A.merge(c, targetToPartial(target));
+		go(c, nav || c.nav);
+	}
 
-/**
- * Try to go back in history to the first entry that matches the given target. If none is found, the given state will replace the current page. This is useful for "cancel" or "close" actions that should return to the previous page if possible, but create a new page if not (for instance when arriving at the current page through a direct link).
- * 
- * Consider using {@link up} to go up in the path hierarchy.
- * 
- * @param target The target route to go back to. May be a subset of {@link Route}, or a string (for `path`), or an array of strings (for `p`).
- */
-export function back(target: RouteTarget = {}): void {
-	const partial = targetToPartial(target);
-	const stack: string[] = historyE.state?.stack || [];
-	const effectiveLen = stack.length + pendingGoOffset;
-	for(let i = effectiveLen - 1; i >= 0; i--) {
-		const histRoute: Route = JSON.parse(stack[i]);
-		if (equal(histRoute, partial, true)) {
-			const pages = i - effectiveLen;
-			log(`back`, pages, histRoute);
-			scheduleHistoryGo(pages);
-			return;
+	function back(target: RouteTarget = {}): void {
+		const partial = targetToPartial(target);
+		const stack: string[] = history.state?.stack || [];
+		const effectiveLen = stack.length + pendingGoOffset;
+		for(let i = effectiveLen - 1; i >= 0; i--) {
+			const histRoute: RouteState = JSON.parse(stack[i]);
+			if (equal(histRoute, partial, true)) {
+				const pages = i - effectiveLen;
+				log(`back`, pages, histRoute);
+				scheduleHistoryGo(pages);
+				return;
+			}
 		}
-	}
 
-	const newRoute = toCanonRoute(partial, "back", effectiveLen + 1);
-	log(`back not found, replacing`, partial);
-	A.copy(current, newRoute);
-}
+		const newRoute = toCanonRoute(partial, "back", effectiveLen + 1);
+		log(`back not found, replacing`, partial);
+		A.copy(current, newRoute);
+	}
 
-/**
-* Navigate up in the path hierarchy, by going back to the first history entry
-* that has a shorter path than the current one. If there's none, we just shorten
-* the current path.
-* 
-* Note that going back in browser history happens asynchronously, so `route` will not be updated immediately.
-*/
-export function up(stripCount: number = 1): void {
-	const currentP = A.unproxy(current).p;
-	const stack: string[] = historyE.state?.stack || [];
-	const effectiveLen = stack.length + pendingGoOffset;
-	for(let i = effectiveLen - 1; i >= 0; i--) {
-		const histRoute: Route = JSON.parse(stack[i]);
-		if (histRoute.p.length < currentP.length && equal(histRoute.p, currentP.slice(0, histRoute.p.length), false)) {
-			// This route is shorter and matches the start of the current path
-			log(`up to ${i+1} / ${effectiveLen}`, histRoute);
-			scheduleHistoryGo(i - effectiveLen);
-			return;
+	function up(stripCount: number = 1): void {
+		const currentP = A.unproxy(current).p;
+		const stack: string[] = history.state?.stack || [];
+		const effectiveLen = stack.length + pendingGoOffset;
+		for(let i = effectiveLen - 1; i >= 0; i--) {
+			const histRoute: RouteState = JSON.parse(stack[i]);
+			if (histRoute.p.length < currentP.length && equal(histRoute.p, currentP.slice(0, histRoute.p.length), false)) {
+				// This route is shorter and matches the start of the current path
+				log(`up to ${i+1} / ${effectiveLen}`, histRoute);
+				scheduleHistoryGo(i - effectiveLen);
+				return;
+			}
 		}
+		// Replace current route with /
+		const newRoute = toCanonRoute({p: currentP.slice(0, currentP.length - stripCount)}, "back", effectiveLen + 1);
+		log(`up not found, replacing`, newRoute);
+		A.copy(current, newRoute);
 	}
-	// Replace current route with /
-	const newRoute = toCanonRoute({p: currentP.slice(0, currentP.length - stripCount)}, "back", effectiveLen + 1);
-	log(`up not found, replacing`, newRoute);
-	A.copy(current, newRoute);
-}
 
 
-let prevStack: string[];
+	let prevStack: string[];
 
-// Track pending historyE.go() offset. Multiple back()/up() calls before the event loop
-// processes them are batched into a single historyE.go() via queueMicrotask.
-let pendingGoOffset = 0;
+	// Track pending historyE().go() offset. Multiple back()/up() calls before the event loop
+	// processes them are batched into a single historyE().go() via queueMicrotask.
+	let pendingGoOffset = 0;
 
-function scheduleHistoryGo(delta: number) {
-	pendingGoOffset += delta;
-	setTimeout(() => {
-		if (pendingGoOffset) {
-			const offset = pendingGoOffset;
-			pendingGoOffset = 0;
-			historyE.go(offset);
-		}
-	}, 0);
-}
+	function scheduleHistoryGo(delta: number) {
+		pendingGoOffset += delta;
+		(A.window.setTimeout ?? setTimeout)(() => {
+			if (pendingGoOffset) {
+				const offset = pendingGoOffset;
+				pendingGoOffset = 0;
+				history.go(offset);
+			}
+		}, 0);
+	}
 
-/**
-* The global {@link Route} object reflecting the current URL and browser history state. Changes you make to this affect the current browser history item (modifying the URL if needed).
-*/
-export const current: Route = A.proxy({}) as Route;
+	const current: RouteState = A.proxy({}) as RouteState;
+
+	// Proxied object with keys for the current path and "k=v" search pairs.
+	// Used by matchCurrent to subscribe only to relevant route changes.
+	const currentRouteParts = A.proxy({} as Record<string,true>);
+
+	/**
+	 * Reset the router to its initial state, based on the current browser state. Intended for testing purposes only.
+	 * @internal
+	 * */
+	function reset() {
+		prevStack = history.state?.stack || [];
+		const initRoute = getRouteFromBrowser();
+		log('initial', initRoute);
+		A.copy(A.unproxy(current), initRoute);
+	}
 
-// Proxied object with keys for the current path and "k=v" search pairs.
-// Used by matchCurrent to subscribe only to relevant route changes.
-const currentRouteParts = A.proxy({} as Record<string,true>);
+	reset();
 
-/**
- * Reset the router to its initial state, based on the current browser state. Intended for testing purposes only.
- * @internal
- * */
-export function reset() {
-	prevStack = historyE.state?.stack || [];
-	const initRoute = getRouteFromBrowser();
-	log('initial', initRoute);
-	A.copy(A.unproxy(current), initRoute);
-}
-reset();
-
-// Handle browser history back and forward
-windowE.addEventListener("popstate", function(event: PopStateEvent) {
-	pendingGoOffset = 0;
-	const newRoute = getRouteFromBrowser();
-	
-	// If the stack length changes, and at least the top-most shared entry is the same,
-	// we'll interpret this as a "back" or "forward" navigation.
-	const stack: string[] = historyE.state?.stack || [];
-	if (stack.length !== prevStack.length) {
-		const maxIndex = Math.min(prevStack.length, stack.length) - 1;
-		if (maxIndex < 0 || stack[maxIndex] === prevStack[maxIndex]) {
-			newRoute.nav = stack.length < prevStack.length ? "back" : "forward";
+	// Handle browser history back and forward
+	window.addEventListener("popstate", function(event: PopStateEvent) {
+		pendingGoOffset = 0;
+		const newRoute = getRouteFromBrowser();
+		
+		// If the stack length changes, and at least the top-most shared entry is the same,
+		// we'll interpret this as a "back" or "forward" navigation.
+		const stack: string[] = history.state?.stack || [];
+		if (stack.length !== prevStack.length) {
+			const maxIndex = Math.min(prevStack.length, stack.length) - 1;
+			if (maxIndex < 0 || stack[maxIndex] === prevStack[maxIndex]) {
+				newRoute.nav = stack.length < prevStack.length ? "back" : "forward";
+			}
 		}
-	}
-	// else nav will be "load"
-	
-	prevStack = stack;
-	log('popstate', newRoute);
-	A.copy(current, newRoute);
-	
-	A.runQueue();
-});
-
-// Make sure these observers are never cleaned up, not even by `unmountAll`.
-leakScope(() => {
-	// Sync `p` to `path`. We need to do this in a separate, higher-priority observer,
-	// so that setting `route.p` will not be immediately overruled by the pre-existing `route.path`.
-	A(() => {
-		current.path = "/" + Array.from(current.p).join("/");
-	});
-
-	// Do a replaceState based on changes to A.proxy
-	A(() => {
-		// First normalize `route`
-		const stack = historyE.state?.stack || [];
-		const newRoute = toCanonRoute(current, A.unproxy(current).nav, stack.length + 1);
+		// else nav will be "load"
+		
+		prevStack = stack;
+		log('popstate', newRoute);
 		A.copy(current, newRoute);
 		
-		// Then replace the current browser state if something actually changed
-		const state = {state: newRoute.state, stack};
-		const url = getUrl(newRoute);
-		if (url !== locationE.pathname + locationE.search + locationE.hash || !equal(historyE.state, state, false)) {
-			log('replaceState', newRoute, state, url);
-			historyE.replaceState(state, "", url);
-		}
+		A.runQueue();
 	});
 
-	// Keep currentRouteParts in sync with the current path and search params.
-	A(() => {
-		const n = {} as Record<string,true>;
-		n[current.path] = true;
-		for(const [k,v] of Object.entries(current.search)) {
-			n[`${k}=${v}`] = true;
-		}
-		A.copy(currentRouteParts, n);
+	// Make sure these observers are never cleaned up, not even by `unmountAll`.
+	A.leakScope(() => {
+		// Sync `p` to `path`. We need to do this in a separate, higher-priority observer,
+		// so that setting `route.p` will not be immediately overruled by the pre-existing `route.path`.
+		A(() => {
+			current.path = "/" + Array.from(current.p).join("/");
+		});
+
+		// Do a replaceState based on changes to A.proxy
+		A(() => {
+			// First normalize `route`
+			const stack = history.state?.stack || [];
+			const newRoute = toCanonRoute(current, A.unproxy(current).nav, stack.length + 1);
+			A.copy(current, newRoute);
+			
+			// Then replace the current browser state if something actually changed
+			const state = {state: newRoute.state, stack};
+			const url = getUrl(newRoute);
+			if (url !== location.pathname + location.search + location.hash || !equal(history.state, state, false)) {
+				log('replaceState', newRoute, state, url);
+				history.replaceState(state, "", url);
+			}
+		});
+
+		// Keep currentRouteParts in sync with the current path and search params.
+		A(() => {
+			const n = {} as Record<string,true>;
+			n[current.path] = true;
+			for(const [k,v] of Object.entries(current.search)) {
+				n[`${k}=${v}`] = true;
+			}
+			A.copy(currentRouteParts, n);
+		});
 	});
-});
-
-
-/**
-* Restore and store the vertical and horizontal scroll position for
-* the parent element to the page state.
-*
-* @param {string} name - A unique (within this page) name for this
-* scrollable element. Defaults to 'main'.
-*
-* The scroll position will be persisted in `route.aux.scroll.<name>`.
-*/
-export function persistScroll(name = "main") {
-	const el = A()!;
-	A('scroll=', onScroll);
-	
-	const restore = A.unproxy(current).state.scroll?.[name];
-	if (restore) {
-		log("restoring scroll", name, restore);
-		Object.assign(el, restore);
-	}
-	
-	function onScroll() {
-		(current.state.scroll ||= {})[name] = {
-			scrollTop: el.scrollTop,
-			scrollLeft: el.scrollLeft,
-		};
-	}
-}
 
-/**
- * Intercept clicks and Enter key presses on links (`<a>` tags) and use Aberdeen routing
- * instead of browser navigation for local paths (paths without a protocol or host).
- * 
- * This allows you to use regular HTML anchor tags for navigation without needing to
- * manually attach click handlers to each link.
- * 
- * @example
- * ```js
- * // In your root component:
- * route.interceptLinks();
- * 
- * // Now you can use regular anchor tags:
- * A('a text=About href=/corporate/about');
- * ```
- */
-export function interceptLinks() {
-	A({
-		click: handleEvent,
-		keydown: handleKeyEvent,
-	});
-	
-	function handleKeyEvent(e: KeyboardEvent) {
-		if (e.key === "Enter") {
-			handleEvent(e);
-		}
-	}
-	
-	function handleEvent(e: Event) {
-		// Find the closest <a> tag
-		let target = e.target as HTMLElement | null;
-		while (target && target.tagName?.toUpperCase() !== "A") {
-			target = target.parentElement;
-		}
-		
-		if (!target) return;
+	function persistScroll(name = "main") {
+		const el = A()!;
+		A('scroll=', onScroll);
 		
-		const anchor = target as HTMLAnchorElement;
-		const href = anchor.getAttribute("href");
-		
-		if (!href) return;
-		
-		// Skip hash-only links
-		if (href.startsWith("#")) return;
-		
-		// Skip if it has a protocol or is protocol-relative (// or contains : before any / ? #)
-		if (href.startsWith("//") || /^[^/?#]+:/.test(href)) return;
+		const restore = A.unproxy(current).state.scroll?.[name];
+		if (restore) {
+			log("restoring scroll", name, restore);
+			Object.assign(el, restore);
+		}
 		
-		// Skip if the link has target or download attribute
-		if (anchor.getAttribute("target") || anchor.getAttribute("download")) return;
+		function onScroll() {
+			(current.state.scroll ||= {})[name] = {
+				scrollTop: el.scrollTop,
+				scrollLeft: el.scrollLeft,
+			};
+		}
+	}
+
+	function interceptLinks() {
+		A({
+			click: handleEvent,
+			keydown: handleKeyEvent,
+		});
 		
-		// Skip if modifier keys are pressed (Ctrl/Cmd click to open in new tab)
-		if (typeof MouseEvent !== 'undefined' && e instanceof MouseEvent && (e.ctrlKey || e.metaKey || e.shiftKey)) return;
+		function handleKeyEvent(e: KeyboardEvent) {
+			if (e.key === "Enter") {
+				handleEvent(e);
+			}
+		}
 		
-		e.preventDefault();
-		go(href);
+		function handleEvent(e: Event) {
+			// Find the closest <a> tag
+			let target = e.target as HTMLElement | null;
+			while (target && target.tagName?.toUpperCase() !== "A") {
+				target = target.parentElement;
+			}
+			
+			if (!target) return;
+			
+			const anchor = target as HTMLAnchorElement;
+			const href = anchor.getAttribute("href");
+			
+			if (!href) return;
+			
+			// Skip hash-only links
+			if (href.startsWith("#")) return;
+			
+			// Skip if it has a protocol or is protocol-relative (// or contains : before any / ? #)
+			if (href.startsWith("//") || /^[^/?#]+:/.test(href)) return;
+			
+			// Skip if the link has target or download attribute
+			if (anchor.getAttribute("target") || anchor.getAttribute("download")) return;
+			
+			// Skip if modifier keys are pressed (Ctrl/Cmd click to open in new tab)
+			if (typeof MouseEvent !== 'undefined' && e instanceof MouseEvent && (e.ctrlKey || e.metaKey || e.shiftKey)) return;
+			
+			e.preventDefault();
+			go(href);
+		}
 	}
+
+	return { current, setLog, go, matchCurrent, push, back, up, reset, persistScroll, interceptLinks } as RouteApi;
 }