vinext 1.3.0 → 1.4.0

package/dist/shims/metadata.js

@@ -23,12 +23,23 @@ async function resolveModuleViewport(mod, params = {}, searchParams, parent = Pr
 			params: asyncParams,
 			searchParams: makeThenableParams(searchParams, searchParamsObserver)
 		});
-		return await mod.generateViewport(props, parent);
+		return await callSegmentResolver(mod.generateViewport, props, parent);
 	}
 	if (mod.viewport && typeof mod.viewport === "object") return mod.viewport;
 	return null;
 }
 /**
+* Call a segment's generateMetadata() or generateViewport() with `parent`, as
+* Next.js's getResult does for both.
+* https://github.com/vercel/next.js/blob/canary/packages/next/src/lib/metadata/resolve-metadata.ts (getResult)
+*/
+function callSegmentResolver(resolver, props, parent) {
+	if (!(Reflect.get(resolver, USE_CACHE_FUNCTION_SYMBOL) === true)) return resolver(props, parent);
+	const acceptsSecondArgument = Reflect.get(resolver, USE_CACHE_ACCEPTS_SECOND_ARGUMENT_SYMBOL);
+	if (!(typeof acceptsSecondArgument === "boolean" ? acceptsSecondArgument : resolver.length >= 2)) return resolver(props);
+	return parent.then(() => resolver(props, parent));
+}
+/**
 * Merge viewport configs from multiple sources (layouts + page).
 * Later entries override earlier ones.
 */
@@ -120,11 +131,8 @@ function resolveThemeColor(themeColor) {
 /**
 * Merge metadata from multiple sources (layouts + page).
 *
-* The list is ordered [rootLayout, nestedLayout, ..., page].
-* Title template from layouts applies to the page title but NOT to
-* the segment that defines the template itself. `title.absolute`
-* skips all templates. `title.default` is the fallback when no
-* child provides a title.
+* The list is ordered [rootLayout, nestedLayout, ..., page], with titles
+* resolved as {@link mergeMetadataEntries} does.
 *
 * Shallow merge: later entries override earlier ones (per Next.js docs).
 */
@@ -151,6 +159,10 @@ function resolveStringTitle(title) {
 	if (typeof title === "string") return title;
 	if (title && typeof title === "object") return title.absolute ?? title.default ?? void 0;
 }
+/** The text a social title renders, a raw `{ default }` title's default if it is not resolved. */
+function renderedTitle(title) {
+	return title && typeof title === "object" ? title.absolute || title.default : title;
+}
 function applyTitleTemplate(template, title) {
 	return template ? template.replace(/%s/g, title) : title;
 }
@@ -222,23 +234,47 @@ function postProcessMetadata(merged) {
 /**
 * Merge metadata from multiple sources (layouts + page).
 *
-* The list is ordered [rootLayout, nestedLayout, ..., page].
-* Title template from layouts applies to the page title but NOT to
-* the segment that defines the template itself. `title.absolute`
-* skips all templates. `title.default` is the fallback when no
-* child provides a title.
+* The list is ordered [rootLayout, nestedLayout, ..., page]. Like Next.js's
+* accumulateMetadata, each title resolves with the template of the title
+* before it: a `title.template` wraps later titles, not its own entry's
+* `title.default`, and a plain-string title, or one without a template,
+* clears it. An `isPage` entry passes on the template it received.
+* `title.absolute` skips all templates.
 *
 * For top-level keys, later entries override earlier ones. `other` custom meta
 * tags are the exception: Next.js merges those across segments.
+* https://github.com/vercel/next.js/blob/canary/packages/next/src/lib/metadata/resolve-metadata.ts (accumulateMetadata)
 */
 function mergeMetadataEntries(entries) {
+	return mergeEntries(entries, false);
+}
+/**
+* Merge metadata into the `parent` a later segment's resolver receives. Like
+* {@link mergeMetadataEntries}, except the title stays resolved as Next.js's
+* `{ absolute, template }`, so `(await parent).title?.absolute` reads the
+* title so far. `template` is the last title's own, the one the next title
+* gets, so merging this parent with later entries resolves their titles as
+* the full merge does.
+* https://github.com/vercel/next.js/blob/canary/packages/next/src/lib/metadata/resolvers/resolve-title.ts
+*/
+function mergeParentMetadataEntries(entries) {
+	return mergeEntries(entries, true);
+}
+const SOCIAL_TITLE_KEYS = ["openGraph", "twitter"];
+function titleTemplateOf(title) {
+	return typeof title === "object" && title ? title.template ?? null : null;
+}
+function mergeEntries(entries, resolvedTitle) {
 	if (entries.length === 0) return {};
 	const merged = {};
-	let parentTemplate;
+	const titleTemplates = {
+		title: null,
+		openGraph: null,
+		twitter: null
+	};
+	let stashedTemplates = { ...titleTemplates };
 	for (const entry of entries) {
 		const meta = entry.metadata;
-		const isPage = Boolean(entry.isPage);
-		const contributesTitle = entry.contributesTitle !== false;
 		for (const key of Object.keys(meta)) {
 			if (key === "title") continue;
 			const incoming = meta[key];
@@ -249,8 +285,36 @@ function mergeMetadataEntries(entries) {
 			};
 			else merged[key] = incoming;
 		}
-		if (contributesTitle && meta.title !== void 0) merged.title = resolveTitle(meta.title, parentTemplate);
-		if (contributesTitle && !isPage && meta.title && typeof meta.title === "object" && meta.title.template) parentTemplate = meta.title.template;
+		if (meta.title !== void 0) {
+			merged.title = resolveTitle(meta.title, stashedTemplates.title ?? void 0);
+			titleTemplates.title = titleTemplateOf(meta.title);
+		}
+		for (const key of SOCIAL_TITLE_KEYS) {
+			if (!Object.hasOwn(meta, key)) continue;
+			const social = meta[key];
+			titleTemplates[key] = titleTemplateOf(social?.title);
+			merged[key] = social ? {
+				...social,
+				title: resolveTitle(social.title, stashedTemplates[key] ?? void 0)
+			} : null;
+		}
+		if (!entry.isPage) stashedTemplates = { ...titleTemplates };
+	}
+	if (resolvedTitle) {
+		if (Object.hasOwn(merged, "title")) merged.title = {
+			absolute: resolveStringTitle(merged.title) ?? "",
+			template: titleTemplates.title
+		};
+		for (const key of SOCIAL_TITLE_KEYS) {
+			const social = merged[key];
+			if (social) merged[key] = {
+				...social,
+				title: {
+					absolute: resolveStringTitle(social.title) ?? "",
+					template: titleTemplates[key]
+				}
+			};
+		}
 	}
 	return merged;
 }
@@ -268,13 +332,10 @@ async function resolveModuleMetadata(mod, params = {}, searchParams, parent = Pr
 	if (typeof mod.generateMetadata === "function") {
 		const generateMetadata = mod.generateMetadata;
 		const asyncParams = makeThenableParams(params);
-		const props = searchParams === void 0 ? withUseCacheLayoutMarker(generateMetadata, { params: asyncParams }) : withUseCachePageMarker(generateMetadata, {
+		return await callSegmentResolver(generateMetadata, searchParams === void 0 ? withUseCacheLayoutMarker(generateMetadata, { params: asyncParams }) : withUseCachePageMarker(generateMetadata, {
 			params: asyncParams,
 			searchParams: makeThenableParams(searchParams, searchParamsObserver)
-		});
-		const isUseCacheFunction = Reflect.get(generateMetadata, USE_CACHE_FUNCTION_SYMBOL) === true;
-		const acceptsSecondArgument = Reflect.get(generateMetadata, USE_CACHE_ACCEPTS_SECOND_ARGUMENT_SYMBOL);
-		return await (!isUseCacheFunction || (typeof acceptsSecondArgument === "boolean" ? acceptsSecondArgument : generateMetadata.length >= 2) ? generateMetadata(props, parent) : generateMetadata(props));
+		}), parent);
 	}
 	if (mod.metadata && typeof mod.metadata === "object") return mod.metadata;
 	return null;
@@ -544,9 +605,10 @@ function MetadataHead({ metadata, pathname = "/", trailingSlash, streamedIconKey
 	}
 	if (metadata.openGraph) {
 		const og = metadata.openGraph;
-		if (og.title) elements.push(/* @__PURE__ */ jsx("meta", {
+		const ogTitle = renderedTitle(og.title);
+		if (ogTitle) elements.push(/* @__PURE__ */ jsx("meta", {
 			property: "og:title",
-			content: og.title
+			content: ogTitle
 		}, key++));
 		if (og.description) elements.push(/* @__PURE__ */ jsx("meta", {
 			property: "og:description",
@@ -607,24 +669,61 @@ function MetadataHead({ metadata, pathname = "/", trailingSlash, streamedIconKey
 				}
 			}
 		}
-		if (og.videos) for (const video of og.videos) {
-			elements.push(/* @__PURE__ */ jsx("meta", {
-				property: "og:video",
-				content: resolveUrl(video.url)
-			}, key++));
-			if (video.width) elements.push(/* @__PURE__ */ jsx("meta", {
-				property: "og:video:width",
-				content: String(video.width)
-			}, key++));
-			if (video.height) elements.push(/* @__PURE__ */ jsx("meta", {
-				property: "og:video:height",
-				content: String(video.height)
+		if (og.videos) {
+			const videos = normalizeUrlDescriptorEntries(og.videos, (url) => ({ url }));
+			for (const video of videos) {
+				if (video.url) elements.push(/* @__PURE__ */ jsx("meta", {
+					property: "og:video",
+					content: stringifyUrl(video.url)
+				}, key++));
+				if (video.secureUrl) elements.push(/* @__PURE__ */ jsx("meta", {
+					property: "og:video:secure_url",
+					content: stringifyUrl(video.secureUrl)
+				}, key++));
+				if (video.type) elements.push(/* @__PURE__ */ jsx("meta", {
+					property: "og:video:type",
+					content: video.type
+				}, key++));
+				if (video.width) elements.push(/* @__PURE__ */ jsx("meta", {
+					property: "og:video:width",
+					content: String(video.width)
+				}, key++));
+				if (video.height) elements.push(/* @__PURE__ */ jsx("meta", {
+					property: "og:video:height",
+					content: String(video.height)
+				}, key++));
+			}
+		}
+		if (og.audio) {
+			const audios = normalizeUrlDescriptorEntries(og.audio, (url) => ({ url }));
+			for (const audio of audios) {
+				if (audio.url) elements.push(/* @__PURE__ */ jsx("meta", {
+					property: "og:audio",
+					content: stringifyUrl(audio.url)
+				}, key++));
+				if (audio.secureUrl) elements.push(/* @__PURE__ */ jsx("meta", {
+					property: "og:audio:secure_url",
+					content: stringifyUrl(audio.secureUrl)
+				}, key++));
+				if (audio.type) elements.push(/* @__PURE__ */ jsx("meta", {
+					property: "og:audio:type",
+					content: audio.type
+				}, key++));
+			}
+		}
+		const ogListTags = [
+			["og:email", og.emails],
+			["og:phone_number", og.phoneNumbers],
+			["og:fax_number", og.faxNumbers],
+			["og:locale:alternate", og.alternateLocale]
+		];
+		for (const [property, value] of ogListTags) {
+			if (!value) continue;
+			for (const content of Array.isArray(value) ? value : [value]) elements.push(/* @__PURE__ */ jsx("meta", {
+				property,
+				content
 			}, key++));
 		}
-		if (og.audio) for (const audio of og.audio) elements.push(/* @__PURE__ */ jsx("meta", {
-			property: "og:audio",
-			content: resolveUrl(audio.url)
-		}, key++));
 	}
 	if (metadata.twitter) {
 		const tw = metadata.twitter;
@@ -640,9 +739,10 @@ function MetadataHead({ metadata, pathname = "/", trailingSlash, streamedIconKey
 			name: "twitter:site:id",
 			content: tw.siteId
 		}, key++));
-		if (tw.title) elements.push(/* @__PURE__ */ jsx("meta", {
+		const twTitle = renderedTitle(tw.title);
+		if (twTitle) elements.push(/* @__PURE__ */ jsx("meta", {
 			name: "twitter:title",
-			content: tw.title
+			content: twTitle
 		}, key++));
 		if (tw.description) elements.push(/* @__PURE__ */ jsx("meta", {
 			name: "twitter:description",
@@ -867,4 +967,4 @@ function MetadataHead({ metadata, pathname = "/", trailingSlash, streamedIconKey
 	return /* @__PURE__ */ jsx(Fragment$1, { children: elements });
 }
 //#endregion
-export { DEFAULT_VIEWPORT, MetadataHead, ViewportHead, mergeMetadata, mergeMetadataEntries, mergeViewport, postProcessMetadata, renderMetadataToHtml, resolveModuleMetadata, resolveModuleViewport };
+export { DEFAULT_VIEWPORT, MetadataHead, ViewportHead, mergeMetadata, mergeMetadataEntries, mergeParentMetadataEntries, mergeViewport, postProcessMetadata, renderMetadataToHtml, resolveModuleMetadata, resolveModuleViewport };

package/dist/shims/navigation-errors.d.ts

@@ -58,4 +58,5 @@ export declare function isDynamicServerError(error: unknown): error is DynamicSe
  * them. This covers the categories vinext can currently produce.
  */
 export declare function unstable_rethrow(error: unknown): void;
-//#endregion
+//#endregion
+export {};

package/dist/shims/navigation-server.js

@@ -1,3 +1,3 @@
-import { GLOBAL_ACCESSORS_KEY, ServerInsertedHTMLContext, _registerStateAccessors, clearClientHydrationContext, clearServerInsertedHTML, flushServerInsertedHTML, getBfcacheIdMapContext, getBfcacheSegmentIdContext, getLayoutSegmentContext, getNavigationContext, registerServerInsertedHTMLCallback, renderServerInsertedHTML, setNavigationContext } from "./navigation-context-state.js";
 import { BailoutToCSRError, DynamicServerError, HTTP_ERROR_FALLBACK_ERROR_CODE, RedirectType, decodeRedirectError, forbidden, getAccessFallbackHTTPStatus, isBailoutToCSRError, isDynamicServerError, isHTTPAccessFallbackError, isNextRouterError, isRedirectError, notFound, permanentRedirect, redirect, unauthorized, unstable_rethrow } from "./navigation-errors.js";
+import { GLOBAL_ACCESSORS_KEY, ServerInsertedHTMLContext, _registerStateAccessors, clearClientHydrationContext, clearServerInsertedHTML, flushServerInsertedHTML, getBfcacheIdMapContext, getBfcacheSegmentIdContext, getLayoutSegmentContext, getNavigationContext, registerServerInsertedHTMLCallback, renderServerInsertedHTML, setNavigationContext } from "./navigation-context-state.js";
 export { BailoutToCSRError, DynamicServerError, GLOBAL_ACCESSORS_KEY, HTTP_ERROR_FALLBACK_ERROR_CODE, RedirectType, ServerInsertedHTMLContext, _registerStateAccessors, clearClientHydrationContext, clearServerInsertedHTML, decodeRedirectError, flushServerInsertedHTML, forbidden, getAccessFallbackHTTPStatus, getBfcacheIdMapContext, getBfcacheSegmentIdContext, getLayoutSegmentContext, getNavigationContext, isBailoutToCSRError, isDynamicServerError, isHTTPAccessFallbackError, isNextRouterError, isRedirectError, notFound, permanentRedirect, redirect, registerServerInsertedHTMLCallback, renderServerInsertedHTML, setNavigationContext, unauthorized, unstable_rethrow };

package/dist/shims/navigation.d.ts

@@ -1,13 +1,14 @@
 import { AppRouterScrollIntent } from "./app-router-scroll-state.js";
-import { NavigationRuntimeVisibleCommitMode } from "../client/navigation-runtime.js";
+import { AppRouterInstance, NavigateOptions, PrefetchOptions as PrefetchOptions$1 } from "./internal/app-router-context.js";
+import { AppRoutePrefetchPolicy } from "./internal/app-route-prefetch-policy.js";
 import { AppElements } from "../server/app-elements-wire.js";
 import "../server/app-elements.js";
-import { AppRouterInstance, NavigateOptions, PrefetchOptions as PrefetchOptions$1 } from "./internal/app-router-context.js";
 import { ReadonlyURLSearchParams } from "./readonly-url-search-params.js";
 import { AppRscRenderMode } from "../server/app-rsc-render-mode.js";
 import { GLOBAL_ACCESSORS_KEY, NavigationContext, NavigationStateAccessors, SegmentMap, ServerInsertedHTMLContext, _registerStateAccessors, clearServerInsertedHTML, flushServerInsertedHTML, getBfcacheIdMapContext, getBfcacheSegmentIdContext, getLayoutSegmentContext, getNavigationContext, renderServerInsertedHTML, setNavigationContext } from "./navigation-context-state.js";
 import { BailoutToCSRError, DynamicServerError, HTTP_ERROR_FALLBACK_ERROR_CODE, RedirectType, decodeRedirectError, forbidden, getAccessFallbackHTTPStatus, isBailoutToCSRError, isDynamicServerError, isHTTPAccessFallbackError, isNextRouterError, isRedirectError, notFound, permanentRedirect, redirect, unauthorized, unstable_rethrow } from "./navigation-errors.js";
 import { UnrecognizedActionError, unstable_isUnrecognizedActionError } from "./unrecognized-action-error.js";
+import { NavigationRuntimeVisibleCommitMode } from "../client/navigation-runtime.js";
 import * as React$1 from "react";
 import { Params } from "@vinext/types/next/upstream/dist/server/request/params";
 //#region src/shims/navigation.d.ts
@@ -49,6 +50,12 @@ export type CachedRscResponse = {
   mountedSlotsHeader?: string | null;
   paramsHeader: string | null;
   preparedElements?: AppElements;
+  /**
+   * When the payload arrived from the server. A navigation that commits a
+   * prefetched payload keeps the prefetch's time, so a later full prefetch
+   * judges the data by its age, not by the navigation that reused it.
+   */
+  receivedAt?: number;
   /**
    * Streamed `redirect()` side-channel headers. A replayed snapshot must keep
    * them so the navigation follows the redirect instead of decoding the
@@ -67,7 +74,13 @@ export type PrefetchOptions = {
 export type PrefetchCacheKind = "loading-shell" | "navigation" | "route-tree";
 export type PrefetchCacheEntry = {
   cacheForNavigation?: boolean;
+  /**
+   * Set while a full prefetch would be kept as learning-only if its page
+   * renders dynamically. A hover upgrade turns it into a full prefetch.
+   */
+  dynamicStaleTime?: "learning-only" | "full-prefetch";
   expiresAt?: number;
+  fallbackTtlMs?: number;
   invalidationTimer?: ReturnType<typeof setTimeout>;
   mountedSlotsHeader?: string | null;
   onInvalidateCallbacks?: Set<() => void>;
@@ -116,6 +129,10 @@ export declare function hasPrefetchCacheEntryForNavigation(rscUrl: string, inter
   additionalRscUrls?: readonly string[];
   notifyInvalidation?: boolean;
   onInvalidate?: () => void;
+  /** Called with the matched entry, and the key it was found under, when it is reused. */
+  onReuse?: (entry: PrefetchCacheEntry, cacheKey: string) => void;
+  /** Whether an in-flight entry counts as reusable. Defaults to true. */
+  reusePending?: boolean;
 }): boolean;
 /**
  * Return whether the exact learning-only Link prefetch is still usable.
@@ -124,8 +141,36 @@ export declare function hasPrefetchCacheEntryForNavigation(rscUrl: string, inter
  */
 export declare function hasFreshLearningOnlyPrefetchCacheEntry(rscUrl: string, interceptionContext?: string | null): boolean;
 export declare function hasSearchAgnosticPrefetchShellForRoute(rscUrl: string, interceptionContext?: string | null, mountedSlotsHeader?: string | null): boolean;
-export declare function discardLearningOnlyPrefetchCacheEntry(rscUrl: string, interceptionContext?: string | null): boolean;
-export declare function invalidatePrefetchCache(): void;
+export declare function discardLearningOnlyPrefetchCacheEntry(rscUrl: string, interceptionContext?: string | null, mountedSlotsHeader?: string | null): boolean;
+/**
+ * Make a prefetch reusable by a navigation, as an `unstable_dynamicOnHover`
+ * hover does. A pending one that would be kept as learning-only becomes a full
+ * prefetch and takes the full-prefetch lifetime. One already kept as
+ * learning-only because its page rendered dynamically is left for the full
+ * prefetch to replace: Next.js refetches it with `FetchStrategy.Full`, so the
+ * page reflects the cookies and headers at hover time.
+ */
+export declare function promotePrefetchCacheEntryForNavigation(cacheKey: string, entry: PrefetchCacheEntry): void;
+export type InvalidatePrefetchCacheOptions = {
+  /** Prefetch the visible links again right away. Defaults to true. */
+  pingVisibleLinks?: boolean;
+};
+export declare function invalidatePrefetchCache(options?: InvalidatePrefetchCacheOptions): void;
+/**
+ * Evict the prefetch entries that may hold dynamic data, for a Server Action
+ * that called `refresh()`. Like Next.js's dynamic-only revalidation, which
+ * evicts its BFCache but keeps its prefetch cache, this keeps route trees,
+ * static prefetches and full prefetches. It drops navigation responses, and
+ * automatic prefetches whose page rendered dynamically or hasn't finished
+ * rendering, including those only kept to learn a route: Next.js's automatic
+ * prefetches never hold dynamic data.
+ */
+export declare function invalidateDynamicPrefetchCache(): void;
+/**
+ * Notify the prefetches that stood in for a visited response (see
+ * `hasNavigationFreshVisitedResponse`), as the visited responses are cleared.
+ */
+export declare function invalidateVisitedResponsePrefetches(): void;
 /**
  * Prevent completed navigation responses from becoming authoritative again
  * after restoring a history snapshot. Explicit Link/router prefetches remain
@@ -133,7 +178,21 @@ export declare function invalidatePrefetchCache(): void;
  * responses retain the cache reuse licensed by Next's segment cache.
  */
 export declare function disableNavigationResponsePrefetchCacheReuse(): void;
-export declare function seedPrefetchResponseSnapshot(rscUrl: string, snapshot: CachedRscResponse, interceptionContext?: string | null, mountedSlotsHeader?: string | null, fallbackTtlMs?: number, reuseAfterHistoryRestore?: boolean): void;
+export declare function seedPrefetchResponseSnapshot(rscUrl: string, snapshot: CachedRscResponse, interceptionContext?: string | null, mountedSlotsHeader?: string | null, fallbackTtlMs?: number, reuseAfterHistoryRestore?: boolean, expiresAt?: number): void;
+/**
+ * Fulfill a full prefetch from the visited response of an earlier navigation,
+ * as Next.js does from its BFCache, instead of issuing a request. The data is
+ * fresh for the static stale time from the navigation, not the dynamic one
+ * (`attemptToFulfillDynamicSegmentFromBFCache`).
+ */
+export declare function seedFullPrefetchFromVisitedResponse(rscUrl: string, interceptionContext: string | null, mountedSlotsHeader: string | null, additionalRscUrls?: readonly string[], onInvalidate?: () => void): boolean;
+/**
+ * Whether a navigation to the URL would reuse the response of an earlier one,
+ * so a prefetch has nothing to fetch. Like Next.js, whose navigation keeps the
+ * route and its segments for `staleTimes.dynamic`. `onInvalidate` fires when
+ * that reuse ends.
+ */
+export declare function hasNavigationFreshVisitedResponse(rscUrl: string, interceptionContext: string | null, mountedSlotsHeader: string | null, additionalRscUrls?: readonly string[], onInvalidate?: () => void): boolean;
 export declare function deletePrefetchResponseSnapshot(rscUrl: string, snapshot: CachedRscResponse, interceptionContext?: string | null): void;
 /**
  * Store a prefetched RSC response in the cache by snapshotting it to an
@@ -206,7 +265,7 @@ export declare function fetchRouteTreeGatedPrefetch(options: {
  */
 export declare function prefetchRscResponse(rscUrl: string, fetchPromise: Promise<Response>, interceptionContext?: string | null, mountedSlotsHeader?: string | null, options?: PrefetchOptions, behavior?: {
   cacheForNavigation?: boolean;
-  dynamicStaleTime?: "verbatim" | "full-prefetch" | "ignore";
+  dynamicStaleTime?: AppRoutePrefetchPolicy["dynamicStaleTime"];
   fallbackTtlMs?: number;
   optimisticRouteShell?: boolean;
   prefetchKind?: PrefetchCacheKind;
@@ -251,10 +310,33 @@ type ClientNavigationState = {
   originalPushState: typeof window.history.pushState;
   originalReplaceState: typeof window.history.replaceState;
   patchInstalled: boolean;
+  routerHistoryWriteDepth: number;
+  routerHistoryWrite: RouterHistoryWrite | null;
   hasPendingNavigationUpdate: boolean;
   suppressUrlNotifyCount: number;
   navigationSnapshotActiveCount: number;
 };
+type RouterHistoryWrite = {
+  method: "pushState" | "replaceState";
+  data: unknown;
+  url: string | URL;
+  href: string;
+  land: RouterHistoryWriteLanding | undefined;
+  threw: boolean;
+  landed: boolean;
+};
+/**
+ * Runs as a router history write lands, after any writes a history wrapper
+ * installed after boot made before forwarding it. Returns the data to write
+ * (re-stamped when those writes moved the traversal indices) and a commit to
+ * run once the write succeeds, before any write the wrapper makes after it. A
+ * wrapper installed before boot is the original method called after `land`, so
+ * writes it makes through the live methods are not accounted for.
+ */
+export type RouterHistoryWriteLanding = (data: unknown) => {
+  data: unknown;
+  commit: () => void;
+};
 type CommitClientNavigationStateOptions = {
   releaseSnapshot?: boolean;
 };
@@ -328,8 +410,8 @@ export declare function useParams<T extends Params = Params>(): T | null;
  * must opt in explicitly if they also own an activated render snapshot.
  */
 export declare function commitClientNavigationState(navId?: number, options?: CommitClientNavigationStateOptions): void;
-export declare function pushHistoryStateWithoutNotify(data: unknown, unused: string, url?: string | URL | null): void;
-export declare function replaceHistoryStateWithoutNotify(data: unknown, unused: string, url?: string | URL | null): void;
+export declare function pushHistoryStateWithoutNotify(data: unknown, unused: string, url?: string | URL | null, land?: RouterHistoryWriteLanding): void;
+export declare function replaceHistoryStateWithoutNotify(data: unknown, unused: string, url?: string | URL | null, land?: RouterHistoryWriteLanding): void;
 /**
  * Save the current scroll position into the current history state.
  * Called before every navigation to enable scroll restoration on back/forward.
@@ -343,6 +425,11 @@ export declare function applyAppRouterScrollFallback(intent: AppRouterScrollInte
  * Navigate to a URL, handling external URLs, hash-only changes, and RSC navigation.
  */
 export declare function navigateClientSide(href: string, mode: "push" | "replace", scroll: boolean, programmaticTransition?: boolean, visibleCommitMode?: NavigationRuntimeVisibleCommitMode): Promise<void>;
+/**
+ * Called by the App Router browser entry for each RSC navigation it runs.
+ * Returns a release callback for the navigation's settlement.
+ */
+export declare function trackAppRouterNavigationInFlight(): () => void;
 /**
  * Public App Router instance, exposed for the browser entry so it can wire
  * `window.next.router` to the same singleton returned from `useRouter()`.