aberdeen 1.17.0 → 2.0.0

package/src/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Default browser entry point for Aberdeen.
+ *
+ * It exports a ready-to-use Aberdeen instance (`A`) bound to the global `window`, so you can
+ * `import A from 'aberdeen'` and start building UI with zero setup. Advanced users (and the
+ * `aberdeen/server` SSR entry) can instead import {@link createA} to create instances bound to a
+ * specific window, including multiple isolated instances.
+ */
+export { createA } from "./aberdeen.js";
+export type { Aberdeen, WindowLike, InitOptions, ValueRef, PromiseProxy } from "./aberdeen.js";
+import { createA } from "./aberdeen.js";
+
+export default createA(typeof window !== "undefined" ? (window as any) : undefined);

package/src/prediction.ts

@@ -1,21 +1,18 @@
-import {
-	defaultEmitHandler,
-	withEmitHandler,
-	EMPTY,
-	MAP_SIZE_SYMBOL,
-} from "./aberdeen.js";
-import type { TargetType } from "./aberdeen.js";
+// This module operates on a specific Aberdeen instance, which is passed as the first argument
+// (`A`) to its public functions. `A` provides the emit handlers and the EMPTY/MAP_SIZE_SYMBOL
+// markers it needs.
+type Aberdeen = any;
 
 /**
  * Represents a set of changes that can be applied to proxied objects.
  * This is an opaque type - its internal structure is not part of the public API.
  * @private
  */
-export type Patch = Map<TargetType, Map<any, [any, any]>>;
+export type Patch = Map<any, Map<any, [any, any]>>;
 
-function recordPatch(func: () => void): Patch {
+function recordPatch(A: Aberdeen, func: () => void): Patch {
 	const recordingPatch = new Map();
-	withEmitHandler((target, index, newData, oldData) => {
+	A.withEmitHandler((target: any, index: any, newData: any, oldData: any) => {
 		addToPatch(recordingPatch, target, index, newData, oldData);
 	}, func);
 	return recordingPatch;
@@ -23,7 +20,7 @@ function recordPatch(func: () => void): Patch {
 
 function addToPatch(
 	patch: Patch,
-	collection: TargetType,
+	collection: any,
 	index: any,
 	newData: any,
 	oldData: any,
@@ -39,10 +36,10 @@ function addToPatch(
 	else collectionMap.set(index, [newData, oldData0]);
 }
 
-function emitPatch(patch: Patch) {
+function emitPatch(A: Aberdeen, patch: Patch) {
 	for (const [collection, collectionMap] of patch) {
 		for (const [index, [newData, oldData]] of collectionMap) {
-			defaultEmitHandler(collection, index, newData, oldData);
+			A.defaultEmitHandler(collection, index, newData, oldData);
 		}
 	}
 }
@@ -61,11 +58,12 @@ function mergePatch(target: Patch, source: Patch, reverse = false) {
 	}
 }
 
-function silentlyApplyPatch(patch: Patch, force = false): boolean {
+function silentlyApplyPatch(A: Aberdeen, patch: Patch, force = false): boolean {
+	const EMPTY = A.EMPTY;
 	for (const [collection, collectionMap] of patch) {
 		for (const [index, [newData, oldData]] of collectionMap) {
 			// MAP_SIZE_SYMBOL is synthetic - size is derived from add/delete operations
-			if (index === MAP_SIZE_SYMBOL) continue;
+			if (index === A.MAP_SIZE_SYMBOL) continue;
 			const actualData =
 				collection instanceof Map
 					? collection.has(index)
@@ -76,7 +74,7 @@ function silentlyApplyPatch(patch: Patch, force = false): boolean {
 						: EMPTY;
 			if (actualData !== oldData) {
 				if (force)
-					setTimeout(() => {
+					(A.window?.setTimeout ?? setTimeout)(() => {
 						throw new Error(
 							`Applying invalid patch: data ${String(actualData)} is unequal to expected old data ${String(oldData)} for index ${String(index)}`,
 						);
@@ -87,7 +85,7 @@ function silentlyApplyPatch(patch: Patch, force = false): boolean {
 	}
 	for (const [collection, collectionMap] of patch) {
 		for (const [index, [newData, oldData]] of collectionMap) {
-			if (index === MAP_SIZE_SYMBOL) continue;
+			if (index === A.MAP_SIZE_SYMBOL) continue;
 			if (collection instanceof Map) {
 				if (newData === EMPTY) collection.delete(index);
 				else collection.set(index, newData);
@@ -106,15 +104,16 @@ const appliedPredictions: Array<Patch> = [];
  * Run the provided function, while treating all changes to Observables as predictions,
  * meaning they will be reverted when changes come back from the server (or some other
  * async source).
+ * @param A The Aberdeen instance (the default export of `aberdeen`, or one from `init`).
  * @param predictFunc The function to run. It will generally modify some Observables
  * 	to immediately reflect state (as closely as possible) that we expect the server
  *  to communicate back to us later on.
  * @returns A `Patch` object. Don't modify it. This is only meant to be passed to `applyCanon`.
  */
-export function applyPrediction(predictFunc: () => void): Patch {
-	const patch = recordPatch(predictFunc);
+export function applyPrediction(A: Aberdeen, predictFunc: () => void): Patch {
+	const patch = recordPatch(A, predictFunc);
 	appliedPredictions.push(patch);
-	emitPatch(patch);
+	emitPatch(A, patch);
 	return patch;
 }
 
@@ -127,6 +126,7 @@ export function applyPrediction(predictFunc: () => void): Patch {
  *
  * All of this is done such that redraws are only triggered if the overall effect is an
  * actual change to an `Observable`.
+ * @param A The Aberdeen instance (the default export of `aberdeen`, or one from `init`).
  * @param canonFunc The function to run without any predictions applied. This will typically
  *  make authoritative changes to the data, based on a server response.
  * @param dropPredictions An optional list of predictions (as returned by `applyPrediction`)
@@ -134,22 +134,23 @@ export function applyPrediction(predictFunc: () => void): Patch {
  *  you'd want to drop the prediction that was done for that request.
  */
 export function applyCanon(
+	A: Aberdeen,
 	canonFunc?: () => void,
 	dropPredictions: Array<Patch> = [],
 ) {
 	const resultPatch = new Map();
 	for (const prediction of appliedPredictions)
 		mergePatch(resultPatch, prediction, true);
-	silentlyApplyPatch(resultPatch, true);
+	silentlyApplyPatch(A, resultPatch, true);
 
 	for (const prediction of dropPredictions) {
 		const pos = appliedPredictions.indexOf(prediction);
 		if (pos >= 0) appliedPredictions.splice(pos, 1);
 	}
-	if (canonFunc) mergePatch(resultPatch, recordPatch(canonFunc));
+	if (canonFunc) mergePatch(resultPatch, recordPatch(A, canonFunc));
 
 	for (let idx = 0; idx < appliedPredictions.length; idx++) {
-		if (silentlyApplyPatch(appliedPredictions[idx])) {
+		if (silentlyApplyPatch(A, appliedPredictions[idx])) {
 			mergePatch(resultPatch, appliedPredictions[idx]);
 		} else {
 			appliedPredictions.splice(idx, 1);
@@ -157,5 +158,5 @@ export function applyCanon(
 		}
 	}
 
-	emitPatch(resultPatch);
+	emitPatch(A, resultPatch);
 }

package/src/route.ts

@@ -1,5 +1,3 @@
-import A, {leakScope} from "./aberdeen.js";
-
 type NavType = "load" | "back" | "forward" | "go" | "push";
 
 /**
@@ -28,13 +26,148 @@ export interface Route {
 	nav: NavType;
 }
 
-let log: (...args: any) => void = () => {};
+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>,
+}>;
+
+/**
+ * The router API returned by {@link init}, bound to a specific Aberdeen instance's window.
+ */
+export interface RouteApi {
+	/**
+	* 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).
+	*/
+	current: Route;
+	/**
+	 * 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 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"});
+	* ```
+	*/
+	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 Route}, 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;
+	/**
+	 * Run the router's browser-dependent setup: sync the `route` proxy to the current URL,
+	 * start listening for `popstate`, and start the observers that keep the browser URL in sync
+	 * with `route`. Safe to call multiple times (subsequent calls are no-ops).
+	 *
+	 * This runs automatically on import in a browser. Outside a browser it is a no-op until a
+	 * window has been provided via `setWindow`, after which you should call it yourself (or call
+	 * `reset` to re-sync to a new request URL). See the `aberdeen/server` SSR entry point.
+	 * @internal
+	 */
+	initRouter(): 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;
+}
 
 /**
- * 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`.
+ * 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 setLog(value: boolean | ((...args: any[]) => void)) {
+export function init(A: any): RouteApi {
+
+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) {
@@ -44,18 +177,20 @@ export function setLog(value: boolean | ((...args: any[]) => void)) {
 	}
 }
 
-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;
+// The window/location/history are resolved lazily (rather than captured at import time) so
+// that this module can be imported in a non-browser environment and have a window injected
+// later via `setWindow` (see the `aberdeen/server` SSR entry point).
+const windowE = () => A.window;
+const locationE = () => A.window.location;
+const historyE = () => A.window.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);
+		path: locationE().pathname,
+		hash: locationE().hash,
+		search: Object.fromEntries(new URLSearchParams(locationE().search)),
+		state: 	historyE().state?.state || {},
+	}, "load", (historyE().state?.stack?.length || 0) + 1);
 }
 
 /**
@@ -106,13 +241,6 @@ function toCanonRoute(target: Partial<Route>, nav: NavType, depth: number): Rout
 }
 
 
-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>;
 
@@ -121,10 +249,10 @@ 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) {
+		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}`);
+			throw new Error(`Unexpected external URL: ${url.host} != ${locationE().host}`);
 		}
 		target = {
 			path: url.pathname,
@@ -147,29 +275,9 @@ function targetToPartial(target: RouteTarget, undefinedOnExternal: boolean=false
 }
 
 
-/**
-* 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 {
+function go(target: RouteTarget, nav: NavType = "go"): void {
 	pendingGoOffset = 0;
-	const stack: string[] = historyE.state?.stack || [];
+	const stack: string[] = historyE().state?.stack || [];
 
 	prevStack = stack.concat(JSON.stringify(A.unproxy(current)));
 	
@@ -177,32 +285,12 @@ export function go(target: RouteTarget, nav: NavType = "go"): void {
 	A.copy(current, newRoute);
 	
 	log(nav, newRoute);
-	historyE.pushState({state: newRoute.state, stack: prevStack}, "", getUrl(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 {
+function matchCurrent(target: RouteTarget): boolean {
 	const partial = targetToPartial(target, true);
 	if (!partial) return false; // External link
 
@@ -221,31 +309,15 @@ export function matchCurrent(target: RouteTarget): boolean {
 	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 {
+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 {
+function back(target: RouteTarget = {}): void {
 	const partial = targetToPartial(target);
-	const stack: string[] = historyE.state?.stack || [];
+	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]);
@@ -262,16 +334,9 @@ export function back(target: RouteTarget = {}): void {
 	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 {
+function up(stripCount: number = 1): void {
 	const currentP = A.unproxy(current).p;
-	const stack: string[] = historyE.state?.stack || [];
+	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]);
@@ -291,25 +356,22 @@ export function up(stripCount: number = 1): void {
 
 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.
+// 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(() => {
+	(A.window.setTimeout ?? setTimeout)(() => {
 		if (pendingGoOffset) {
 			const offset = pendingGoOffset;
 			pendingGoOffset = 0;
-			historyE.go(offset);
+			historyE().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: Route = A.proxy({}) as Route;
 
 // Proxied object with keys for the current path and "k=v" search pairs.
 // Used by matchCurrent to subscribe only to relevant route changes.
@@ -319,22 +381,28 @@ 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
  * */
-export function reset() {
-	prevStack = historyE.state?.stack || [];
+function reset() {
+	prevStack = historyE().state?.stack || [];
 	const initRoute = getRouteFromBrowser();
 	log('initial', initRoute);
 	A.copy(A.unproxy(current), initRoute);
 }
-reset();
+let routerInited = false;
+
+function initRouter() {
+	if (routerInited || !A.window) return;
+	routerInited = true;
 
-// Handle browser history back and forward
-windowE.addEventListener("popstate", function(event: PopStateEvent) {
+	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 || [];
+	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]) {
@@ -351,7 +419,7 @@ windowE.addEventListener("popstate", function(event: PopStateEvent) {
 });
 
 // Make sure these observers are never cleaned up, not even by `unmountAll`.
-leakScope(() => {
+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(() => {
@@ -361,16 +429,16 @@ leakScope(() => {
 	// Do a replaceState based on changes to A.proxy
 	A(() => {
 		// First normalize `route`
-		const stack = historyE.state?.stack || [];
+		const stack = historyE().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 !== locationE.pathname + locationE.search + locationE.hash || !equal(historyE.state, state, false)) {
+		if (url !== locationE().pathname + locationE().search + locationE().hash || !equal(historyE().state, state, false)) {
 			log('replaceState', newRoute, state, url);
-			historyE.replaceState(state, "", url);
+			historyE().replaceState(state, "", url);
 		}
 	});
 
@@ -384,18 +452,13 @@ leakScope(() => {
 		A.copy(currentRouteParts, n);
 	});
 });
+}
 
+// Initialise immediately in a browser; a no-op (until `setWindow`) on the server.
+initRouter();
 
-/**
-* 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") {
+
+function persistScroll(name = "main") {
 	const el = A()!;
 	A('scroll=', onScroll);
 	
@@ -413,23 +476,7 @@ export function persistScroll(name = "main") {
 	}
 }
 
-/**
- * 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() {
+function interceptLinks() {
 	A({
 		click: handleEvent,
 		keydown: handleKeyEvent,
@@ -471,3 +518,6 @@ export function interceptLinks() {
 		go(href);
 	}
 }
+
+	return { current, setLog, go, matchCurrent, push, back, up, reset, initRouter, persistScroll, interceptLinks } as unknown as RouteApi;
+}