vinext 1.3.0 → 1.3.1

package/dist/shims/default-not-found.js

@@ -1,59 +1,23 @@
+import { HTTPAccessErrorFallback } from "./http-access-error-fallback.js";
 import React from "react";
 //#region src/shims/default-not-found.tsx
 /**
 * Ported from Next.js's built-in default not-found component:
 *   https://github.com/vercel/next.js/blob/canary/packages/next/src/client/components/builtin/not-found.tsx
-*   https://github.com/vercel/next.js/blob/canary/packages/next/src/client/components/http-access-fallback/error-fallback.tsx
 *
 * Rendered when an App Router request resolves to a 404 and the user has not
 * supplied their own `app/not-found.tsx` (or `app/global-not-found.tsx`).
-* Matches Next.js's `HTTPAccessErrorFallback` exactly: a centered 404 / message
-* pair with minified theme CSS and dark-mode media query.
 *
 * The message string `"This page could not be found."` (note the trailing
 * period) is the canonical body asserted by Next.js's deploy suite
 * (`test/e2e/app-dir/prefetching-not-found/prefetching-not-found.test.ts`,
 * `test/e2e/basepath/error-pages.test.ts`).
 */
-const styles = {
-	error: {
-		fontFamily: "system-ui,\"Segoe UI\",Roboto,Helvetica,Arial,sans-serif,\"Apple Color Emoji\",\"Segoe UI Emoji\"",
-		height: "100vh",
-		textAlign: "center",
-		display: "flex",
-		flexDirection: "column",
-		alignItems: "center",
-		justifyContent: "center"
-	},
-	desc: { display: "inline-block" },
-	h1: {
-		display: "inline-block",
-		margin: "0 20px 0 0",
-		padding: "0 23px 0 0",
-		fontSize: 24,
-		fontWeight: 500,
-		verticalAlign: "top",
-		lineHeight: "49px"
-	},
-	h2: {
-		fontSize: 14,
-		fontWeight: 400,
-		lineHeight: "49px",
-		margin: 0
-	}
-};
-const STATUS = 404;
-const MESSAGE = "This page could not be found.";
-/**
-* Mirrors `<HTTPAccessErrorFallback status={404} message="This page could not be found." />`
-* from Next.js. Kept in sync with the upstream component's structure so HTML
-* snapshot diffs between Next.js and vinext stay minimal.
-*/
 function DefaultNotFound() {
-	return React.createElement(React.Fragment, null, React.createElement("title", null, `${STATUS}: ${MESSAGE}`), React.createElement("div", { style: styles.error }, React.createElement("div", null, React.createElement("style", { dangerouslySetInnerHTML: { __html: "body{color:#000;background:#fff;margin:0}.next-error-h1{border-right:1px solid rgba(0,0,0,.3)}@media (prefers-color-scheme:dark){body{color:#fff;background:#000}.next-error-h1{border-right:1px solid rgba(255,255,255,.3)}}" } }), React.createElement("h1", {
-		className: "next-error-h1",
-		style: styles.h1
-	}, STATUS), React.createElement("div", { style: styles.desc }, React.createElement("h2", { style: styles.h2 }, MESSAGE)))));
+	return React.createElement(HTTPAccessErrorFallback, {
+		status: 404,
+		message: "This page could not be found."
+	});
 }
 //#endregion
 export { DefaultNotFound as default };

package/dist/shims/default-unauthorized.d.ts

@@ -0,0 +1,4 @@
+import React from "react";
+//#region src/shims/default-unauthorized.d.ts
+export default function DefaultUnauthorized(): React.ReactElement;
+//#endregion

package/dist/shims/default-unauthorized.js

@@ -0,0 +1,18 @@
+import { HTTPAccessErrorFallback } from "./http-access-error-fallback.js";
+import React from "react";
+//#region src/shims/default-unauthorized.tsx
+/**
+* Ported from Next.js's built-in default unauthorized component:
+*   https://github.com/vercel/next.js/blob/canary/packages/next/src/client/components/builtin/unauthorized.tsx
+*
+* Rendered when `unauthorized()` is called and no `app/unauthorized.tsx`
+* boundary catches it.
+*/
+function DefaultUnauthorized() {
+	return React.createElement(HTTPAccessErrorFallback, {
+		status: 401,
+		message: "You're not authorized to access this page."
+	});
+}
+//#endregion
+export { DefaultUnauthorized as default };

package/dist/shims/error-boundary.d.ts

@@ -78,12 +78,47 @@ type NotFoundBoundaryProps = {
   fallback: React.ReactNode;
   children: React.ReactNode;
   resetKey?: string | null;
+  /** A parallel slot boundary's id, which the document may render caught. */
+  caughtId?: string;
 };
+type NotFoundBoundaryInnerProps = {
+  pathname: string | null;
+  initiallyNotFound?: boolean;
+} & NotFoundBoundaryProps;
+type NotFoundBoundaryState = {
+  notFound: boolean;
+  previousPathname: string | null;
+  previousResetKey: string | null;
+};
+/**
+ * Inner class component that catches notFound() errors and renders the
+ * not-found.tsx fallback. Resets when the pathname or the caller's segment
+ * reset key changes.
+ *
+ * The ErrorBoundary above re-throws notFound errors so they propagate up to this
+ * boundary. This must be placed above the ErrorBoundary in the component tree.
+ */
+export declare class NotFoundBoundaryInner extends React.Component<NotFoundBoundaryInnerProps, NotFoundBoundaryState> {
+  constructor(props: NotFoundBoundaryInnerProps);
+  componentDidMount(): void;
+  static getDerivedStateFromProps(props: NotFoundBoundaryInnerProps, state: NotFoundBoundaryState): NotFoundBoundaryState | null;
+  static getDerivedStateFromError(error: unknown): Partial<NotFoundBoundaryState>;
+  render(): string | number | bigint | boolean | React.JSX.Element | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | Iterable<React.ReactNode> | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | React.ReactPortal | null | undefined> | null | undefined;
+}
+/**
+ * Fallback for a page-level access boundary whose file belongs to an ancestor
+ * layout. Rethrowing from the fallback hands the signal to the next boundary
+ * up, so that layout's copy renders in place of the layouts below it while the
+ * page-level boundary keeps the element shape sibling routes share.
+ */
+export declare function HttpAccessFallbackPassthrough({ status }: {
+  status: 401 | 403 | 404;
+}): never;
 /**
  * Wrapper that reads the current pathname and passes it to the inner class
- * component. Segment reset keys own App Router remount semantics when present.
+ * component.
  */
-export declare function NotFoundBoundary({ fallback, children, resetKey }: NotFoundBoundaryProps): React.JSX.Element;
+export declare function NotFoundBoundary({ fallback, children, resetKey, caughtId }: NotFoundBoundaryProps): React.JSX.Element;
 type ForbiddenBoundaryProps = {
   fallback: React.ReactNode;
   children: React.ReactNode;
@@ -144,4 +179,5 @@ export declare class DevRecoveryBoundary extends React.Component<DevRecoveryBoun
   componentDidCatch(): void;
   render(): React.ReactNode;
 }
-//#endregion
+//#endregion
+export {};

package/dist/shims/error-boundary.js

@@ -1,11 +1,12 @@
 "use client";
 import { isNavigationSignalError } from "../utils/navigation-signal.js";
-import { decodeRedirectError, isRedirectError } from "./navigation-errors.js";
+import { decodeRedirectError, forbidden, isRedirectError, notFound, unauthorized } from "./navigation-errors.js";
 import "./navigation-server.js";
 import { isRedirectToCurrentUrl, useErrorBoundaryPathname, useErrorBoundaryRouter } from "./error-boundary-navigation.js";
 import DefaultGlobalError from "./default-global-error.js";
 import { handleAppNavigationFailure } from "../client/app-nav-failure-handler.js";
 import { VINEXT_DEV_ERROR_RECOVERY_EVENT } from "../utils/dev-error-recovery-event.js";
+import { consumeCaughtNotFoundBoundary, useCaughtNotFoundBoundary } from "./caught-not-found-boundaries.js";
 import React from "react";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 //#region src/shims/error-boundary.tsx
@@ -29,11 +30,8 @@ function readBoundaryResetState(props) {
 		previousResetKey: normalizeBoundaryResetKey(props.resetKey)
 	};
 }
-function shouldResetBoundary(nextResetState, previousResetState) {
-	const nextResetKey = normalizeBoundaryResetKey(nextResetState.previousResetKey);
-	const previousResetKey = normalizeBoundaryResetKey(previousResetState.previousResetKey);
-	if (nextResetKey !== null || previousResetKey !== null) return nextResetKey !== previousResetKey;
-	return nextResetState.previousPathname !== previousResetState.previousPathname;
+function shouldResetSegmentBoundary(nextResetState, previousResetState) {
+	return nextResetState.previousPathname !== previousResetState.previousPathname || normalizeBoundaryResetKey(nextResetState.previousResetKey) !== normalizeBoundaryResetKey(previousResetState.previousResetKey);
 }
 function addDevErrorRecoveryListener(listener) {
 	if (typeof window === "undefined") return;
@@ -136,7 +134,7 @@ var ErrorBoundaryInner = class extends React.Component {
 			error: null,
 			...nextResetState
 		};
-		if (state.error && shouldResetBoundary(nextResetState, state)) return {
+		if (state.error && shouldResetSegmentBoundary(nextResetState, state)) return {
 			error: null,
 			...nextResetState
 		};
@@ -196,8 +194,8 @@ function GlobalErrorBoundary({ fallback, children }) {
 }
 /**
 * Inner class component that catches notFound() errors and renders the
-* not-found.tsx fallback. Resets on the caller's segment reset key when one is
-* provided, otherwise falls back to pathname changes for legacy callers.
+* not-found.tsx fallback. Resets when the pathname or the caller's segment
+* reset key changes.
 *
 * The ErrorBoundary above re-throws notFound errors so they propagate up to this
 * boundary. This must be placed above the ErrorBoundary in the component tree.
@@ -206,13 +204,16 @@ var NotFoundBoundaryInner = class extends React.Component {
 	constructor(props) {
 		super(props);
 		this.state = {
-			notFound: false,
+			notFound: props.initiallyNotFound === true,
 			...readBoundaryResetState(props)
 		};
 	}
+	componentDidMount() {
+		if (this.props.initiallyNotFound === true) consumeCaughtNotFoundBoundary(this.props.caughtId);
+	}
 	static getDerivedStateFromProps(props, state) {
 		const nextResetState = readBoundaryResetState(props);
-		if (state.notFound && shouldResetBoundary(nextResetState, state)) return {
+		if (state.notFound && shouldResetSegmentBoundary(nextResetState, state)) return {
 			notFound: false,
 			...nextResetState
 		};
@@ -237,15 +238,29 @@ var NotFoundBoundaryInner = class extends React.Component {
 	}
 };
 /**
+* Fallback for a page-level access boundary whose file belongs to an ancestor
+* layout. Rethrowing from the fallback hands the signal to the next boundary
+* up, so that layout's copy renders in place of the layouts below it while the
+* page-level boundary keeps the element shape sibling routes share.
+*/
+function HttpAccessFallbackPassthrough({ status }) {
+	if (status === 403) forbidden();
+	if (status === 401) unauthorized();
+	notFound();
+}
+/**
 * Wrapper that reads the current pathname and passes it to the inner class
-* component. Segment reset keys own App Router remount semantics when present.
+* component.
 */
-function NotFoundBoundary({ fallback, children, resetKey }) {
+function NotFoundBoundary({ fallback, children, resetKey, caughtId }) {
 	const pathname = useErrorBoundaryPathname();
+	const initiallyNotFound = useCaughtNotFoundBoundary(caughtId);
 	return /* @__PURE__ */ jsx(NotFoundBoundaryInner, {
 		pathname,
 		resetKey,
 		fallback,
+		caughtId,
+		initiallyNotFound,
 		children
 	});
 }
@@ -259,7 +274,7 @@ var ForbiddenBoundaryInner = class extends React.Component {
 	}
 	static getDerivedStateFromProps(props, state) {
 		const nextResetState = readBoundaryResetState(props);
-		if (state.forbidden && shouldResetBoundary(nextResetState, state)) return {
+		if (state.forbidden && shouldResetSegmentBoundary(nextResetState, state)) return {
 			forbidden: false,
 			...nextResetState
 		};
@@ -301,7 +316,7 @@ var UnauthorizedBoundaryInner = class extends React.Component {
 	}
 	static getDerivedStateFromProps(props, state) {
 		const nextResetState = readBoundaryResetState(props);
-		if (state.unauthorized && shouldResetBoundary(nextResetState, state)) return {
+		if (state.unauthorized && shouldResetSegmentBoundary(nextResetState, state)) return {
 			unauthorized: false,
 			...nextResetState
 		};
@@ -374,4 +389,4 @@ var DevRecoveryBoundary = class extends React.Component {
 	}
 };
 //#endregion
-export { DevRecoveryBoundary, ErrorBoundary, ErrorBoundaryInner, ForbiddenBoundary, ForbiddenBoundaryInner, GlobalErrorBoundary, NotFoundBoundary, RedirectBoundary, RedirectErrorBoundary, SerializedErrorBoundary, UnauthorizedBoundary, UnauthorizedBoundaryInner };
+export { DevRecoveryBoundary, ErrorBoundary, ErrorBoundaryInner, ForbiddenBoundary, ForbiddenBoundaryInner, GlobalErrorBoundary, HttpAccessFallbackPassthrough, NotFoundBoundary, NotFoundBoundaryInner, RedirectBoundary, RedirectErrorBoundary, SerializedErrorBoundary, UnauthorizedBoundary, UnauthorizedBoundaryInner };

package/dist/shims/font-google.js

@@ -1,2 +1 @@
-import googleFonts, { buildGoogleFontsUrl, createFontLoader, getSSRFontLinks, getSSRFontPreloads, getSSRFontStyles } from "./font-google-base.js";
-export { buildGoogleFontsUrl, createFontLoader, googleFonts as default, getSSRFontLinks, getSSRFontPreloads, getSSRFontStyles };
+export { buildGoogleFontsUrl, createFontLoader, default, getSSRFontLinks, getSSRFontPreloads, getSSRFontStyles } from "./font-google-base.js";

package/dist/shims/font-utils.d.ts

@@ -47,9 +47,10 @@ export declare function resolveGoogleFontStyle(style: string | string[] | undefi
 export declare function resolveSingleFaceStyle(input: FontFaceStyleInput): FontStyle;
 export declare function formatFontClassRule(className: string, style: FontStyle): string;
 /**
- * Determine the MIME type for a font file based on its extension.
+ * Determine the preload `type` for a font file based on its extension.
  * Uses endsWith() only to avoid false positives from substring matches
- * (e.g. ".woff" matching ".woff2").
+ * (e.g. ".woff" matching ".woff2"). Matches Next.js, which emits
+ * `font/${ext}` for every font preload (including `font/eot`).
  */
 export declare function getFontMimeType(pathOrUrl: string): string;
 //#endregion

package/dist/shims/font-utils.js

@@ -92,15 +92,17 @@ function formatFontClassRule(className, style) {
 	].join("; ")}; }\n`;
 }
 /**
-* Determine the MIME type for a font file based on its extension.
+* Determine the preload `type` for a font file based on its extension.
 * Uses endsWith() only to avoid false positives from substring matches
-* (e.g. ".woff" matching ".woff2").
+* (e.g. ".woff" matching ".woff2"). Matches Next.js, which emits
+* `font/${ext}` for every font preload (including `font/eot`).
 */
 function getFontMimeType(pathOrUrl) {
 	if (pathOrUrl.endsWith(".woff2")) return "font/woff2";
 	if (pathOrUrl.endsWith(".woff")) return "font/woff";
 	if (pathOrUrl.endsWith(".ttf")) return "font/ttf";
-	if (pathOrUrl.endsWith(".otf")) return "font/opentype";
+	if (pathOrUrl.endsWith(".otf")) return "font/otf";
+	if (pathOrUrl.endsWith(".eot")) return "font/eot";
 	return "font/woff2";
 }
 //#endregion

package/dist/shims/form.js

@@ -161,7 +161,7 @@ const Form = forwardRef(function Form(props, ref) {
 					const cacheKey = AppElementsWire.encodeCacheKey(rscUrl, interceptionContext);
 					const prefetched = getPrefetchedUrls();
 					if (prefetched.has(cacheKey)) return;
-					if (hasPrefetchCacheEntryForNavigation(rscUrl, interceptionContext, mountedSlotsHeader)) return;
+					if (hasPrefetchCacheEntryForNavigation(rscUrl, interceptionContext, mountedSlotsHeader, { reusePending: false })) return;
 					prefetched.add(cacheKey);
 					const fetchPromise = fetch(rscUrl, {
 						headers,

package/dist/shims/http-access-error-fallback.d.ts

@@ -0,0 +1,7 @@
+import React from "react";
+//#region src/shims/http-access-error-fallback.d.ts
+export declare function HTTPAccessErrorFallback({ status, message }: {
+  status: number;
+  message: string;
+}): React.ReactElement;
+//#endregion

package/dist/shims/http-access-error-fallback.js

@@ -0,0 +1,47 @@
+import React from "react";
+//#region src/shims/http-access-error-fallback.tsx
+/**
+* Ported from Next.js's built-in HTTP access fallback UI:
+*   https://github.com/vercel/next.js/blob/canary/packages/next/src/client/components/http-access-fallback/error-fallback.tsx
+*   https://github.com/vercel/next.js/blob/canary/packages/next/src/client/components/styles/access-error-styles.ts
+*
+* Shared by the built-in not-found, forbidden and unauthorized pages: a
+* centered status / message pair with minified theme CSS and dark-mode media
+* query. Kept in sync with the upstream component's structure so HTML
+* snapshot diffs between Next.js and vinext stay minimal.
+*/
+const styles = {
+	error: {
+		fontFamily: "system-ui,\"Segoe UI\",Roboto,Helvetica,Arial,sans-serif,\"Apple Color Emoji\",\"Segoe UI Emoji\"",
+		height: "100vh",
+		textAlign: "center",
+		display: "flex",
+		flexDirection: "column",
+		alignItems: "center",
+		justifyContent: "center"
+	},
+	desc: { display: "inline-block" },
+	h1: {
+		display: "inline-block",
+		margin: "0 20px 0 0",
+		padding: "0 23px 0 0",
+		fontSize: 24,
+		fontWeight: 500,
+		verticalAlign: "top",
+		lineHeight: "49px"
+	},
+	h2: {
+		fontSize: 14,
+		fontWeight: 400,
+		lineHeight: "49px",
+		margin: 0
+	}
+};
+function HTTPAccessErrorFallback({ status, message }) {
+	return React.createElement(React.Fragment, null, React.createElement("title", null, `${status}: ${message}`), React.createElement("div", { style: styles.error }, React.createElement("div", null, React.createElement("style", { dangerouslySetInnerHTML: { __html: "body{color:#000;background:#fff;margin:0}.next-error-h1{border-right:1px solid rgba(0,0,0,.3)}@media (prefers-color-scheme:dark){body{color:#fff;background:#000}.next-error-h1{border-right:1px solid rgba(255,255,255,.3)}}" } }), React.createElement("h1", {
+		className: "next-error-h1",
+		style: styles.h1
+	}, status), React.createElement("div", { style: styles.desc }, React.createElement("h2", { style: styles.h2 }, message)))));
+}
+//#endregion
+export { HTTPAccessErrorFallback };

package/dist/shims/image.d.ts

@@ -4,27 +4,6 @@ import { ImageLoader, ImageProps as ImageProps$1, StaticImageData, StaticRequire
 //#region src/shims/image.d.ts
 export type ImageLoaderProps = Parameters<ImageLoader>[0];
 export type ImageProps = ImageProps$1;
-declare const Image: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.ImgHTMLAttributes<HTMLImageElement>, HTMLImageElement>, "alt" | "height" | "loading" | "ref" | "src" | "srcSet" | "width"> & {
-  src: string | import("@vinext/types/next/upstream/dist/shared/lib/get-img-props").StaticImport;
-  alt: string;
-  width?: number | `${number}`;
-  height?: number | `${number}`;
-  fill?: boolean;
-  loader?: ImageLoader;
-  quality?: number | `${number}`;
-  preload?: boolean;
-  priority?: boolean;
-  loading?: "eager" | "lazy" | undefined;
-  placeholder?: import("@vinext/types/next/upstream/dist/shared/lib/get-img-props").PlaceholderValue;
-  blurDataURL?: string;
-  unoptimized?: boolean;
-  overrideSrc?: string;
-  onLoadingComplete?: import("@vinext/types/next/upstream/dist/shared/lib/get-img-props").OnLoadingComplete;
-  layout?: string;
-  objectFit?: string;
-  objectPosition?: string;
-  lazyBoundary?: string;
-  lazyRoot?: string;
-} & React.RefAttributes<HTMLImageElement>>;
+declare const Image: React.ForwardRefExoticComponent<ImageProps & React.RefAttributes<HTMLImageElement>>;
 //#endregion
 export { type ImageLoader, type StaticImageData, type StaticRequire, Image as default, getImageProps, imageOptimizationUrl };

package/dist/shims/internal/app-prefetch-fetch-queue.d.ts

@@ -4,8 +4,14 @@ export declare function releaseAppPrefetchFetchSlot(response: Response): void;
  * Low-priority App Router prefetches share a small request queue. The consumer
  * must either snapshot the returned Response with snapshotRscResponse() or call
  * releaseAppPrefetchFetchSlot() when it drops the response without consuming it.
+ *
+ * `isWanted` is checked when a queued request reaches a free slot. Returning
+ * false drops it without fetching, like a cancelled Next.js prefetch task. A
+ * navigation that promotes the request skips the check.
  */
-export declare function scheduleAppPrefetchFetch(fetcher: (signal: AbortSignal) => Promise<Response>, priority: "low" | "high"): Promise<Response>;
+export declare function scheduleAppPrefetchFetch(fetcher: (signal: AbortSignal) => Promise<Response>, priority: "low" | "high", isWanted?: () => boolean): Promise<Response>;
+/** Cancel a prefetch request that is still waiting for a slot; never aborts one in flight. */
+export declare function cancelQueuedAppPrefetchFetch(promise: Promise<Response>): void;
 /** Cancel a queued or in-flight prefetch request. No-op once it has settled. */
 export declare function cancelAppPrefetchFetch(promise: Promise<Response> | undefined): void;
 /**
@@ -19,6 +25,20 @@ export declare function cancelAppPrefetchFetch(promise: Promise<Response> | unde
  * cap instead of waiting for a slot.
  *
  * No-op when the request has already started or was never queued.
+ *
+ * Also records a claim, live while `isCurrent` returns true, until the returned
+ * function releases it; see `isAppPrefetchFetchClaimed`.
+ */
+export declare function promoteAppPrefetchFetch(promise: Promise<Response> | undefined, isCurrent?: () => boolean): () => void;
+/**
+ * Whether a current navigation is waiting on this prefetch. A staged prefetch
+ * (route tree, then payload) hands navigation a promise that wraps its queued
+ * requests, so promotion cannot reach them; they check this instead before
+ * dropping themselves.
+ *
+ * `claimedBy` limits this to claims made up to that `getAppPrefetchFetchClaimSequence()`.
  */
-export declare function promoteAppPrefetchFetch(promise: Promise<Response> | undefined): void;
+export declare function isAppPrefetchFetchClaimed(promise: Promise<Response> | undefined, claimedBy?: number): boolean;
+/** The sequence number of the latest claim on any prefetch. */
+export declare function getAppPrefetchFetchClaimSequence(): number;
 //#endregion

package/dist/shims/internal/app-prefetch-fetch-queue.js

@@ -5,6 +5,12 @@ const MAX_DEFAULT_APP_PREFETCH_REQUESTS = 4;
 const defaultAppPrefetchQueue = [];
 /** Lets a consumer promote or cancel the request behind a promise it already holds. */
 const appPrefetchFetchControls = /* @__PURE__ */ new WeakMap();
+/**
+* Navigations waiting on a promise, each live while it is current, with the
+* sequence number it was claimed at.
+*/
+const appPrefetchFetchClaims = /* @__PURE__ */ new WeakMap();
+let appPrefetchFetchClaimSequence = 0;
 let activeDefaultAppPrefetchRequests = 0;
 let defaultAppPrefetchDrainScheduled = false;
 function drainDefaultAppPrefetchQueue() {
@@ -31,8 +37,12 @@ function releaseAppPrefetchFetchSlot(response) {
 * Low-priority App Router prefetches share a small request queue. The consumer
 * must either snapshot the returned Response with snapshotRscResponse() or call
 * releaseAppPrefetchFetchSlot() when it drops the response without consuming it.
+*
+* `isWanted` is checked when a queued request reaches a free slot. Returning
+* false drops it without fetching, like a cancelled Next.js prefetch task. A
+* navigation that promotes the request skips the check.
 */
-function scheduleAppPrefetchFetch(fetcher, priority) {
+function scheduleAppPrefetchFetch(fetcher, priority, isWanted) {
 	const controller = new AbortController();
 	if (priority === "high") {
 		const promise = fetcher(controller.signal);
@@ -47,7 +57,13 @@ function scheduleAppPrefetchFetch(fetcher, priority) {
 	let started = false;
 	const promise = new Promise((resolve, reject) => {
 		rejectPromise = reject;
-		runner = () => {
+		runner = (promoted = false) => {
+			if (!promoted && isWanted?.() === false) {
+				appPrefetchFetchControls.delete(promise);
+				activeDefaultAppPrefetchRequests -= 1;
+				reject(new DOMException("Prefetch is no longer wanted", "AbortError"));
+				return;
+			}
 			started = true;
 			let didRelease = false;
 			const release = () => {
@@ -73,25 +89,31 @@ function scheduleAppPrefetchFetch(fetcher, priority) {
 			}
 		};
 	});
+	const cancelQueued = () => {
+		if (started) return;
+		const index = defaultAppPrefetchQueue.indexOf(runner);
+		if (index === -1) return;
+		defaultAppPrefetchQueue.splice(index, 1);
+		appPrefetchFetchControls.delete(promise);
+		controller.abort();
+		rejectPromise(controller.signal.reason);
+	};
 	defaultAppPrefetchQueue.push(runner);
 	appPrefetchFetchControls.set(promise, {
 		runner,
+		cancelQueued,
 		cancel: () => {
-			if (started) {
-				controller.abort();
-				return;
-			}
-			const index = defaultAppPrefetchQueue.indexOf(runner);
-			if (index === -1) return;
-			defaultAppPrefetchQueue.splice(index, 1);
-			appPrefetchFetchControls.delete(promise);
-			controller.abort();
-			rejectPromise(controller.signal.reason);
+			if (started) controller.abort();
+			else cancelQueued();
 		}
 	});
 	scheduleDefaultAppPrefetchDrain();
 	return promise;
 }
+/** Cancel a prefetch request that is still waiting for a slot; never aborts one in flight. */
+function cancelQueuedAppPrefetchFetch(promise) {
+	appPrefetchFetchControls.get(promise)?.cancelQueued?.();
+}
 /** Cancel a queued or in-flight prefetch request. No-op once it has settled. */
 function cancelAppPrefetchFetch(promise) {
 	if (promise === void 0) return;
@@ -108,16 +130,47 @@ function cancelAppPrefetchFetch(promise) {
 * cap instead of waiting for a slot.
 *
 * No-op when the request has already started or was never queued.
+*
+* Also records a claim, live while `isCurrent` returns true, until the returned
+* function releases it; see `isAppPrefetchFetchClaimed`.
 */
-function promoteAppPrefetchFetch(promise) {
-	if (promise === void 0) return;
+function promoteAppPrefetchFetch(promise, isCurrent = () => true) {
+	if (promise === void 0) return () => {};
+	let claims = appPrefetchFetchClaims.get(promise);
+	if (claims === void 0) {
+		claims = /* @__PURE__ */ new Map();
+		appPrefetchFetchClaims.set(promise, claims);
+	}
+	claims.set(isCurrent, ++appPrefetchFetchClaimSequence);
+	const release = () => {
+		claims.delete(isCurrent);
+	};
 	const runner = appPrefetchFetchControls.get(promise)?.runner;
-	if (runner === void 0) return;
+	if (runner === void 0) return release;
 	const index = defaultAppPrefetchQueue.indexOf(runner);
-	if (index === -1) return;
+	if (index === -1) return release;
 	defaultAppPrefetchQueue.splice(index, 1);
 	activeDefaultAppPrefetchRequests += 1;
-	runner();
+	runner(true);
+	return release;
+}
+/**
+* Whether a current navigation is waiting on this prefetch. A staged prefetch
+* (route tree, then payload) hands navigation a promise that wraps its queued
+* requests, so promotion cannot reach them; they check this instead before
+* dropping themselves.
+*
+* `claimedBy` limits this to claims made up to that `getAppPrefetchFetchClaimSequence()`.
+*/
+function isAppPrefetchFetchClaimed(promise, claimedBy = Infinity) {
+	const claims = promise && appPrefetchFetchClaims.get(promise);
+	if (!claims) return false;
+	for (const [isCurrent, sequence] of claims) if (sequence <= claimedBy && isCurrent()) return true;
+	return false;
+}
+/** The sequence number of the latest claim on any prefetch. */
+function getAppPrefetchFetchClaimSequence() {
+	return appPrefetchFetchClaimSequence;
 }
 //#endregion
-export { cancelAppPrefetchFetch, promoteAppPrefetchFetch, releaseAppPrefetchFetchSlot, scheduleAppPrefetchFetch };
+export { cancelAppPrefetchFetch, cancelQueuedAppPrefetchFetch, getAppPrefetchFetchClaimSequence, isAppPrefetchFetchClaimed, promoteAppPrefetchFetch, releaseAppPrefetchFetchSlot, scheduleAppPrefetchFetch };

package/dist/shims/internal/app-route-prefetch-policy.d.ts

@@ -16,16 +16,27 @@ export type AppRoutePrefetchPolicy = {
    * How the dynamic stale-time signal affects this prefetch. Navigation data
    * takes it verbatim, explicit full prefetches fall back to the static window
    * only when it is zero, and loading shells ignore it because their contents
-   * are static.
+   * are static. "learning-only" keeps a dynamic render out of navigation reuse
+   * and holds it for the static window instead.
    */
-  dynamicStaleTime: "verbatim" | "full-prefetch" | "ignore";
+  dynamicStaleTime: "verbatim" | "full-prefetch" | "ignore" | "learning-only";
   fallbackTtl: "dynamic" | "static";
   prefetchShellFirst: boolean;
+  /**
+   * The route renders dynamically (`rendersDynamically`), so the prefetch
+   * never renders its page: an href with search params fetches the loading
+   * shell instead of the page with empty search params.
+   */
+  rendersDynamically?: true;
   /** Fetch the route tree before the concrete page segment. */
   requiresRouteTreePrefetch?: true;
   shouldPrefetch: boolean;
 };
 export declare function canAutoPrefetchFullAppRoute(href: string): boolean;
-export declare function resolveAutoAppRoutePrefetch(href: string): AppRoutePrefetchPolicy;
+/**
+ * `interceptionContext` is the prefetch's interception context
+ * (`getPrefetchInterceptionContext`).
+ */
+export declare function resolveAutoAppRoutePrefetch(href: string, interceptionContext?: string | null): AppRoutePrefetchPolicy;
 export declare function resolveFullAppRoutePrefetch(): AppRoutePrefetchPolicy;
 //#endregion