@kasperpeulen/vitest-plugin-nextjs 0.0.0-stage → 0.1.0-alpha.1

package/dist/page.d.ts

@@ -0,0 +1,112 @@
+import { Opened } from "./registry.js";
+import { PageStore } from "./page-store.js";
+import { NodeOnPage } from "./node-on-page.js";
+import { HistoryEntry } from "./document.js";
+import { ShellErrorAnswer } from "./ssr.js";
+
+//#region src/page.d.ts
+/**
+ * A navigation without a page of the app, which has the router, under
+ * Vitest: a component that a test file with `"use client"` rendered has none.
+ */
+declare function noRouter(url: URL): Error;
+/**
+ * A page of the app, from the first line of its load until it is left, with
+ * the node of `renderServer()` on it, and where it reports its errors. Its
+ * load makes it part by part, and each part that would outlive the page says
+ * how it is released. Leaving stops the load at once, and releases the
+ * parts, the last first.
+ */
+declare class Page {
+  #private;
+  readonly errors: unknown[];
+  readonly nodeOnPage?: NodeOnPage | undefined;
+  /** Whether the page renders in the app kept from the page before: see `kept`. */
+  readonly inKeptApp: boolean;
+  /** Aborts as the page is left: what the load does takes it. */
+  readonly signal: AbortSignal;
+  constructor(errors: unknown[], nodeOnPage?: NodeOnPage | undefined, /** Whether the page renders in the app kept from the page before: see `kept`. */
+
+  inKeptApp?: boolean);
+  /** Whether the page is open: from when its client starts until it is left. */
+  get open(): boolean;
+  /**
+   * Runs `release` as the page is left: before what the load made before
+   * it. As `defer()` of a `DisposableStack`.
+   */
+  defer(release: () => void): void;
+  /**
+   * Opens the page: its client starts. Leaving waits for `started` to
+   * settle, at most `startTimeout`, before it releases what the page holds.
+   * `stopped` runs once the start is over for the page: once `started` has
+   * settled, or once leaving stops waiting for it.
+   */
+  starts(started: Promise<unknown>, stopped: () => void): void;
+  /**
+   * Leaves the page: `by` is what leaves it, for its node. Stops its load at
+   * once. Resolves once what the page holds is released, or rejects with the
+   * first error of a release, after every release has run. A page still
+   * starting after `startTimeout` is released once it has stopped, and
+   * `reportError()` gets that error: leaving resolves without it. Once:
+   * leaving it again gets the same promise.
+   */
+  leave(by: string): Promise<void>;
+}
+/**
+ * Leaves the page of the kept app that is open, as `leavePage()` does with
+ * `by`, and then the kept app: a test file ends with them. The app goes also
+ * after a page that could not be left, and the first error rejects.
+ */
+declare function leaveKeptAppWithPage(by: string): Promise<void>;
+/** The page that is open: see `Page.open`. */
+declare function currentPage(): Page | undefined;
+type Opening = {
+  container?: Element;
+  opened: Opened;
+  headers: Headers;
+  cookie: string | null; /** For a node: what `rerender()` waits for. */
+  nodeOnPage?: NodeOnPage; /** What stops the load: see `RequestOptions.signal` in index.ts. */
+  signal?: AbortSignal; /** Where the page, and the pages the app loads from it, report their errors. */
+  errors: unknown[];
+  /**
+   * Renders the page in the app of the page before, if it is kept, and else
+   * keeps the app it starts for the pages after it: see `kept`. A page of
+   * `keepApp` without HTML of the server.
+   */
+  inKeptApp?: boolean;
+};
+type PageDocument = {
+  response: Response;
+  html: string;
+  after?: HistoryEntry;
+  payload?: Uint8Array<ArrayBuffer>;
+};
+declare function loadPage(url: URL, request: RequestInit | PageDocument, from: PageStore, opening?: Opening): Promise<Response>;
+/** The Flight payload in the scripts of a document of Next. */
+declare function payloadInDocument(html: string): Uint8Array;
+/**
+ * How the server would have answered the document of the page of a Flight
+ * payload, had it rendered its HTML, by the errors in the payload (see
+ * `shellErrorAnswer()` in ssr.ts): the first `redirect()`, wherever it is in
+ * the tree, as Next's router follows it (its RedirectBoundary), else the
+ * status of the first other error. Undefined for a payload without an error.
+ * A path of the app's has the app's `basePath` before it, which `redirect()`
+ * takes without it, as Next's server puts it in the `Location` of the 307 of
+ * a document.
+ */
+declare function renderFailureOf(payload: Uint8Array, answerOf: (digest: string) => ShellErrorAnswer): ShellErrorAnswer | undefined;
+/**
+ * A navigation of the app without its router, as a browser makes it: a
+ * `<form>`, an `<a>` that React does not handle, `location.assign()`. The
+ * page that is open stays until the answer is there, and for good when the
+ * answer is a download (downloads.ts). Else the answer is the next page,
+ * which needs a page of the app to navigate in. `downloadRequest` is the
+ * navigation's, and `from` the store of the browser context it is in. With
+ * `push` the next page gets an entry of the history of its own, as after a
+ * link or a form in a browser. Else it takes the entry of the page, as
+ * after a reload or `location.replace()`.
+ */
+declare function navigate(url: URL, init: RequestInit, downloadRequest: string | null, from: PageStore, push: boolean): Promise<void>;
+declare function leavePage(by: string): Promise<void>;
+//#endregion
+export { Page, currentPage, leaveKeptAppWithPage, leavePage, loadPage, navigate, noRouter, payloadInDocument, renderFailureOf };

package/dist/page.js

@@ -0,0 +1,549 @@
+import { loadsNothing, registry } from "./registry.js";
+import { speedFeature } from "./speed-features.js";
+import { loadedSsrLayer, ssrLayer } from "./server-layers.js";
+import { leftTheApp, sendRequest, setOpenPage, setRouterOutlivesPage, unlessAborted } from "./app-requests.js";
+import { keepProperties, loadDocument, unloadDocument, unloadKeptApp } from "./document.js";
+import { callServerWithoutPage } from "./client-graph.js";
+import { download, downloadName } from "./downloads.js";
+import { recordListeners, recordMessageChannels } from "./leftovers.js";
+import { resetAsyncLocalStorage } from "@kasperpeulen/vitest-plugin-rsc/internal/async-local-storage";
+import { routing } from "virtual:vitest-plugin-rsc/next-manifest";
+import { checkFetchedModules, createEnvironmentRunner, environmentModule, forgetHeardVersions, versionOfModules } from "@kasperpeulen/vitest-plugin-rsc/internal/utils";
+//#region src/page.ts
+const startTimeout = 2e4;
+const setTimeout = globalThis.setTimeout;
+const clearTimeout = globalThis.clearTimeout;
+/**
+* A navigation without a page of the app, which has the router, under
+* Vitest: a component that a test file with `"use client"` rendered has none.
+*/
+function noRouter(url) {
+	return /* @__PURE__ */ new Error(`vitest-plugin-rsc: a link or a form navigated to ${url.href}, and there is no page of the app to navigate in: no page of renderServer() is open, and a test file with "use client" has none. Test navigation in a page of renderServer(), in a test file without "use client".`);
+}
+/**
+* A page of the app, from the first line of its load until it is left, with
+* the node of `renderServer()` on it, and where it reports its errors. Its
+* load makes it part by part, and each part that would outlive the page says
+* how it is released. Leaving stops the load at once, and releases the
+* parts, the last first.
+*/
+var Page = class {
+	errors;
+	nodeOnPage;
+	inKeptApp;
+	#load = new AbortController();
+	/** Aborts as the page is left: what the load does takes it. */
+	signal = this.#load.signal;
+	#releases = [];
+	#started;
+	#stopped = () => {};
+	#left;
+	constructor(errors, nodeOnPage, inKeptApp = false) {
+		this.errors = errors;
+		this.nodeOnPage = nodeOnPage;
+		this.inKeptApp = inKeptApp;
+	}
+	/** Whether the page is open: from when its client starts until it is left. */
+	get open() {
+		return this.#started !== void 0 && !this.signal.aborted;
+	}
+	/**
+	* Runs `release` as the page is left: before what the load made before
+	* it. As `defer()` of a `DisposableStack`.
+	*/
+	defer(release) {
+		this.#releases.push(release);
+	}
+	/**
+	* Opens the page: its client starts. Leaving waits for `started` to
+	* settle, at most `startTimeout`, before it releases what the page holds.
+	* `stopped` runs once the start is over for the page: once `started` has
+	* settled, or once leaving stops waiting for it.
+	*/
+	starts(started, stopped) {
+		this.#started = started.then(stopped, stopped);
+		this.#stopped = stopped;
+	}
+	/**
+	* Leaves the page: `by` is what leaves it, for its node. Stops its load at
+	* once. Resolves once what the page holds is released, or rejects with the
+	* first error of a release, after every release has run. A page still
+	* starting after `startTimeout` is released once it has stopped, and
+	* `reportError()` gets that error: leaving resolves without it. Once:
+	* leaving it again gets the same promise.
+	*/
+	leave(by) {
+		return this.#left ??= this.#leave(by);
+	}
+	async #leave(by) {
+		if (this.inKeptApp && this.open) dispatchPageTransition("pagehide");
+		this.#load.abort(new DOMException("The page was left before it had loaded.", "AbortError"));
+		this.nodeOnPage?.left(by);
+		const released = (this.#started ?? Promise.resolve()).then(() => this.#release());
+		let timeout;
+		const stopped = await Promise.race([released.then(() => true, () => true), new Promise((resolve) => timeout = setTimeout(resolve, startTimeout, false))]);
+		clearTimeout(timeout);
+		if (stopped) return released;
+		console.warn(`vitest-plugin-rsc: the page that was left was still loading its client code ${startTimeout / 1e3}s later. The next page loads anyway.`);
+		this.#stopped();
+		released.catch(reportError);
+	}
+	#release() {
+		let failed;
+		for (const release of this.#releases.splice(0).reverse()) try {
+			release();
+		} catch (error) {
+			failed ??= { error };
+		}
+		if (failed) throw failed.error;
+	}
+};
+let current;
+let kept;
+/**
+* Leaves the kept app, if any: its root, its module graph, what its modules
+* left behind as they loaded, and what its code added to the `<head>` go.
+* Once its page is left: see `leavePage()`, and `leaveKeptAppWithPage()`.
+* Not `withGlobals` once the app after it has started, whose they are then.
+*/
+function leaveKeptApp(withGlobals = true) {
+	const app = kept;
+	kept = void 0;
+	setRouterOutlivesPage(false);
+	try {
+		app?.leave();
+	} finally {
+		unloadKeptApp(withGlobals);
+	}
+}
+/**
+* Leaves the page of the kept app that is open, as `leavePage()` does with
+* `by`, and then the kept app: a test file ends with them. The app goes also
+* after a page that could not be left, and the first error rejects.
+*/
+async function leaveKeptAppWithPage(by) {
+	let failed;
+	try {
+		if (current?.inKeptApp) await leavePage(by);
+	} catch (error) {
+		failed = { error };
+	}
+	try {
+		leaveKeptApp();
+	} catch (error) {
+		failed ??= { error };
+	}
+	if (failed) throw failed.error;
+}
+function releaseAll(releases) {
+	let failed;
+	for (const release of releases.splice(0).reverse()) try {
+		release();
+	} catch (error) {
+		failed ??= { error };
+	}
+	if (failed) throw failed.error;
+}
+/** The page that is open: see `Page.open`. */
+function currentPage() {
+	return current?.open ? current : void 0;
+}
+async function loadPage(url, request, from, opening) {
+	const errors = opening?.errors ?? currentPage()?.errors ?? [];
+	const inKeptApp = opening ? opening.inKeptApp === true : currentPage()?.inKeptApp === true;
+	const leaving = leavePage(opening ? "another renderServer()" : "a page load of the app");
+	const page = current = new Page(errors, opening?.nodeOnPage, inKeptApp);
+	const loading = (async () => {
+		await leaving;
+		page.signal.throwIfAborted();
+		if (!speedFeature("cacheDevServer")) forgetHeardVersions();
+		const changed = opening && inKeptApp && kept && kept.modules !== await versionOfModules("react_client");
+		page.signal.throwIfAborted();
+		if (!inKeptApp || !kept || changed) leaveKeptApp();
+		if (opening?.container?.hasChildNodes()) throw new Error("vitest-plugin-rsc: the container of a node has to be empty. The node is hydrated in it, and leaving the node empties it.");
+		const opened = registry.opened = opening?.opened;
+		if (opening) {
+			from.headers = opening.headers;
+			if (opening.cookie !== null) from.seed(opening.cookie);
+		}
+		try {
+			return await openPage(page, url, request, from, opening);
+		} catch (error) {
+			if (opened && registry.opened === opened && !page.signal.aborted) registry.opened = void 0;
+			throw error;
+		}
+	})();
+	if (!opening?.signal) return loading;
+	return unlessAborted(loading, opening.signal, () => {
+		if (current === page) leavePage("the signal of renderServer()").catch(reportError);
+	});
+}
+async function openPage(page, url, request, from, opening) {
+	const { signal } = page;
+	const superseded = () => signal.throwIfAborted();
+	const send = (target, init) => sendPageLoad(target, init, {
+		from,
+		navigation: "test"
+	}, signal);
+	const requestDocument = async (init) => {
+		try {
+			const response = await send(url, init);
+			superseded();
+			return await readDocument(response, (what) => `${what}, which is not a page to open. Use handleRequest() to assert on the response itself.`);
+		} catch (error) {
+			superseded();
+			throw error;
+		}
+	};
+	const byFlight = page.inKeptApp && kept !== void 0 && speedFeature("flightLoads");
+	const withoutHtml = !("html" in request) && (byFlight || opening?.opened.ssr === false) ? await requestWithoutHtml(url, request, byFlight, send, signal) : void 0;
+	superseded();
+	const { response, html, after, payload } = withoutHtml ?? ("html" in request ? request : await requestDocument(request));
+	superseded();
+	let container = opening?.container;
+	if (opening && new URL(response.url).pathname !== opening.opened.pathname) {
+		registry.opened = void 0;
+		container = void 0;
+		opening.nodeOnPage?.replaced();
+	}
+	if (/^\s*<!doctype/i.test(html)) {
+		container = void 0;
+		if (!opening?.opened.node?.layouts) opening?.nodeOnPage?.replaced();
+	}
+	const startsApp = !(page.inKeptApp && kept);
+	const modules = startsApp && page.inKeptApp ? await versionOfModules("react_client") : 0;
+	if (startsApp) await checkFetchedModules();
+	superseded();
+	const forgetReact = await loadDocument(html, response.url, container, after, page.inKeptApp);
+	superseded();
+	const { inKeptApp } = page;
+	if (inKeptApp && kept) {
+		await startInKeptApp(page, kept.client, payload);
+		superseded();
+		return response;
+	}
+	const appReleases = [];
+	const deferForApp = (release) => inKeptApp ? appReleases.push(release) : page.defer(release);
+	const runner = createEnvironmentRunner("react_client");
+	deferForApp(() => void runner.close());
+	const browserRequire = (id) => registry.loadBrowserModule?.(id) ?? loadsNothing();
+	registry.browserRequire = browserRequire;
+	deferForApp(() => {
+		if (registry.browserRequire === browserRequire) registry.browserRequire = loadsNothing;
+	});
+	const leftovers = [recordListeners(window), recordMessageChannels()];
+	for (const leftover of leftovers) deferForApp(() => leftover.remove());
+	const loaded = () => leftovers.forEach((leftover) => leftover.stop());
+	const started = (async () => {
+		try {
+			const client = await runner.import(environmentModule("react_client", "@kasperpeulen/vitest-plugin-nextjs/client"));
+			superseded();
+			const { unmount, leaveApp } = await client.start(loaded, container, signal, opening?.nodeOnPage, page.errors, inKeptApp);
+			page.defer(() => {
+				try {
+					forgetReact();
+				} finally {
+					unmount();
+				}
+			});
+			if (!inKeptApp) return;
+			appReleases.push(leaveApp);
+			const marks = Reflect.ownKeys(document).filter((key) => typeof key === "string" && (key.startsWith("__reactContainer$") || key.startsWith("_reactListening")));
+			keepProperties(document, marks);
+			leaveKeptApp(false);
+			kept = {
+				client,
+				modules,
+				leave() {
+					keepProperties(document);
+					try {
+						releaseAll(appReleases);
+					} finally {
+						for (const key of marks) Reflect.deleteProperty(document, key);
+					}
+				}
+			};
+			setRouterOutlivesPage(true);
+		} catch (error) {
+			releaseAll(appReleases);
+			throw error;
+		}
+	})();
+	page.starts(started, loaded);
+	setOpenPage(signal);
+	try {
+		await started;
+	} catch (error) {
+		superseded();
+		throw error;
+	}
+	superseded();
+	return response;
+}
+function dispatchPageTransition(type) {
+	window.dispatchEvent(new PageTransitionEvent(type, { persisted: false }));
+}
+async function startInKeptApp(page, client, payload) {
+	const { signal } = page;
+	dispatchPageTransition("pageshow");
+	const started = client.renderAgain(signal, page.errors, payload).then(({ unmount }) => page.defer(unmount));
+	page.starts(started, () => {});
+	setOpenPage(signal);
+	try {
+		await started;
+	} catch (error) {
+		signal.throwIfAborted();
+		throw error;
+	}
+}
+async function sendPageLoad(url, init, sending, signal) {
+	checkFetchedModules().catch(() => {});
+	signal.throwIfAborted();
+	return sendRequest(new registry.Request(url, {
+		...init,
+		signal
+	}), sending);
+}
+const flightDocument = "<!DOCTYPE html><html id=\"__next_error__\"><head></head><body></body></html>";
+async function requestWithoutHtml(url, init, byFlight, send, signal) {
+	const headers = new Headers(init.headers);
+	if (byFlight) headers.set("rsc", "1");
+	const request = {
+		...init,
+		headers
+	};
+	try {
+		const loaded = await followPage(await send(url, request), (target) => send(target, request), request, byFlight ? readFlight : readDocumentWithoutHtml);
+		signal.throwIfAborted();
+		if ("html" in loaded) return loaded;
+		return await readDocument(loaded.response, (what) => `${what}, which is not a page to open. Use handleRequest() to assert on the response itself.`);
+	} catch (error) {
+		signal.throwIfAborted();
+		throw error;
+	}
+}
+const isFlight = (response) => /^text\/x-component\b/i.test(response.headers.get("content-type") ?? "");
+async function readFlight(response) {
+	if (!isFlight(response)) return void 0;
+	const payload = new Uint8Array(await response.arrayBuffer());
+	return {
+		document: {
+			response,
+			html: flightDocument,
+			payload
+		},
+		payload
+	};
+}
+async function readDocumentWithoutHtml(response) {
+	if (!/^text\/html\b/i.test(response.headers.get("content-type") ?? "")) return void 0;
+	const html = await response.text();
+	return {
+		document: {
+			response,
+			html
+		},
+		payload: payloadInDocument(html)
+	};
+}
+const documentScripts = /<script\b[^>]*>([^<]*)<\/script>/g;
+const pushOfPayload = "self.__next_f.push(";
+/** The Flight payload in the scripts of a document of Next. */
+function payloadInDocument(html) {
+	const encoder = new TextEncoder();
+	const chunks = [];
+	for (const [, script = ""] of html.matchAll(documentScripts)) {
+		if (!script.startsWith(pushOfPayload)) continue;
+		const [kind, data = ""] = JSON.parse(script.slice(19, -1));
+		if (kind === 1) chunks.push(encoder.encode(data));
+		else if (kind === 3) chunks.push(Uint8Array.from(atob(data), (c) => c.charCodeAt(0)));
+	}
+	const payload = new Uint8Array(chunks.reduce((length, chunk) => length + chunk.length, 0));
+	chunks.reduce((offset, chunk) => (payload.set(chunk, offset), offset + chunk.length), 0);
+	return payload;
+}
+async function followPage(response, send, init, read) {
+	let redirected = response.redirected;
+	for (let redirects = 0;;) {
+		const page = await read(response);
+		if (!page) return { response: pageResponse(response, response.body, redirected) };
+		const { shellErrorAnswer } = await ssrLayer();
+		const failure = renderFailureOf(page.payload, shellErrorAnswer);
+		if (failure?.location === void 0) {
+			const { document } = page;
+			const status = response.status === 200 ? failure?.status : void 0;
+			const body = document.payload ?? document.html;
+			return {
+				...document,
+				response: pageResponse(response, body, redirected, status)
+			};
+		}
+		const target = new URL(failure.location, response.url);
+		if (target.origin !== window.location.origin) throw leftTheApp(target);
+		if (++redirects > 20) throw new Error(`vitest-plugin-rsc: too many redirects for ${response.url}. The last one was to ${target.href}.`);
+		if (init.body instanceof ReadableStream) throw new TypeError("fetch failed", { cause: /* @__PURE__ */ new Error(`vitest-plugin-rsc: ${response.url} redirected to ${target.href}, and the body of its request is a stream, which cannot be sent again.`) });
+		redirected = true;
+		response = await send(target);
+	}
+}
+function pageResponse(response, body, redirected, status = response.status) {
+	if ((response.redirected || !redirected) && status === response.status) return response;
+	const { statusText, headers, url } = response;
+	return Object.defineProperties(new registry.Response(body, {
+		status,
+		statusText,
+		headers
+	}), {
+		url: { value: url },
+		redirected: { value: redirected || response.redirected }
+	});
+}
+const errorRows = /(?:^|\n)[0-9a-f]+:E(\{.*)/g;
+/**
+* How the server would have answered the document of the page of a Flight
+* payload, had it rendered its HTML, by the errors in the payload (see
+* `shellErrorAnswer()` in ssr.ts): the first `redirect()`, wherever it is in
+* the tree, as Next's router follows it (its RedirectBoundary), else the
+* status of the first other error. Undefined for a payload without an error.
+* A path of the app's has the app's `basePath` before it, which `redirect()`
+* takes without it, as Next's server puts it in the `Location` of the 307 of
+* a document.
+*/
+function renderFailureOf(payload, answerOf) {
+	let failure;
+	for (const [, row] of new TextDecoder().decode(payload).matchAll(errorRows)) {
+		let digest;
+		try {
+			digest = JSON.parse(row).digest;
+		} catch {
+			continue;
+		}
+		if (typeof digest !== "string") continue;
+		const answer = answerOf(digest);
+		const { location } = answer;
+		if (location !== void 0) return {
+			...answer,
+			location: location.startsWith("/") ? routing.basePath + location : location
+		};
+		failure ??= answer;
+	}
+	return failure;
+}
+async function readDocument(response, notAPage) {
+	const contentType = response.headers.get("content-type") ?? "";
+	if (!/^text\/html\b/i.test(contentType)) {
+		await response.body?.cancel();
+		const what = `${response.url} responded with ${contentType || "no content type"}`;
+		throw new Error(`vitest-plugin-rsc: ${notAPage(what)}`);
+	}
+	return {
+		response,
+		html: await response.text()
+	};
+}
+let navigating = new AbortController();
+let withoutPage = new AbortController();
+/**
+* A navigation of the app without its router, as a browser makes it: a
+* `<form>`, an `<a>` that React does not handle, `location.assign()`. The
+* page that is open stays until the answer is there, and for good when the
+* answer is a download (downloads.ts). Else the answer is the next page,
+* which needs a page of the app to navigate in. `downloadRequest` is the
+* navigation's, and `from` the store of the browser context it is in. With
+* `push` the next page gets an entry of the history of its own, as after a
+* link or a form in a browser. Else it takes the entry of the page, as
+* after a reload or `location.replace()`.
+*/
+async function navigate(url, init, downloadRequest, from, push) {
+	const page = currentPage();
+	const signals = [page?.signal ?? withoutPage.signal];
+	if (downloadRequest === null) {
+		navigating.abort(new DOMException("Another navigation took the place of this one.", "AbortError"));
+		navigating = new AbortController();
+		signals.push(navigating.signal);
+	}
+	const signal = AbortSignal.any(signals);
+	const byFlight = downloadRequest === null && page?.inKeptApp === true && kept !== void 0 && speedFeature("flightLoads") && (init.method ?? "GET").toUpperCase() === "GET";
+	const send = (target, flight) => {
+		const headers = new Headers(init.headers);
+		if (flight) headers.set("rsc", "1");
+		return sendPageLoad(target, {
+			...init,
+			headers
+		}, {
+			from,
+			navigation: "app",
+			opened: page?.inKeptApp ? {
+				pathname: target.pathname,
+				proxy: true,
+				ssr: false
+			} : void 0,
+			network: downloadRequest === null ? void 0 : () => registry.network(url, {
+				...init,
+				signal
+			})
+		}, signal);
+	};
+	let loaded;
+	try {
+		let response = await send(url, byFlight);
+		signal.throwIfAborted();
+		if (page?.inKeptApp && downloadRequest === null) {
+			const followed = await followPage(response, (target) => send(target, byFlight), init, byFlight ? readFlight : readDocumentWithoutHtml);
+			signal.throwIfAborted();
+			if ("html" in followed) loaded = followed;
+			else response = followed.response;
+		}
+		if (!loaded) {
+			const name = downloadName(response, downloadRequest);
+			if (name !== void 0) return await download(response, name, signal);
+			if (!page) {
+				await response.body?.cancel();
+				throw noRouter(url);
+			}
+			loaded = await readDocument(response, (what) => `the app navigated to a URL that is not a page: ${what}. A browser would show it in place of the app, which a test cannot do. A route handler that answers with a file to save says so with Content-Disposition: attachment, or a link with download.`);
+			signal.throwIfAborted();
+		}
+	} catch (error) {
+		signal.throwIfAborted();
+		throw error;
+	}
+	await loadPage(url, {
+		...loaded,
+		after: entryOf(push)
+	}, from);
+}
+const entryOf = (push) => push ? {
+	url: window.location.href,
+	state: window.history.state
+} : void 0;
+let leaving = Promise.resolve();
+function leavePage(by) {
+	const left = current;
+	current = void 0;
+	withoutPage.abort(new DOMException("The test moved on before it was done.", "AbortError"));
+	withoutPage = new AbortController();
+	const pageLeft = left?.leave(by);
+	const gone = leaving.catch(() => {}).then(async () => {
+		try {
+			await pageLeft;
+		} finally {
+			try {
+				unloadDocument();
+			} finally {
+				try {
+					await loadedSsrLayer()?.settleRequests();
+				} finally {
+					registry.opened = void 0;
+					setOpenPage(void 0);
+					globalThis.__viteRscCallServer = callServerWithoutPage;
+					resetAsyncLocalStorage();
+				}
+			}
+		}
+	});
+	leaving = gone;
+	return gone;
+}
+//#endregion
+export { Page, currentPage, leaveKeptAppWithPage, leavePage, loadPage, navigate, noRouter, payloadInDocument, renderFailureOf };

package/dist/paths.d.ts

@@ -0,0 +1,13 @@
+import { NextProject } from "./project.js";
+import { Plugin } from "vite";
+
+//#region src/paths.d.ts
+/**
+ * The files that the `paths` have for a request, in order: TypeScript takes
+ * the pattern with the longest prefix. Not a declaration file, which is for
+ * the types only.
+ */
+declare function candidatesOf(paths: NonNullable<NextProject["paths"]>, request: string): string[];
+declare function createPathsPlugin(getProject: () => NextProject): Plugin;
+//#endregion
+export { candidatesOf, createPathsPlugin };