@qzsy/vinext 0.1.7

package/dist/server/app-browser-error.d.ts

@@ -0,0 +1,13 @@
+//#region src/server/app-browser-error.d.ts
+type VinextHydrateRootErrorInfo = {
+  componentStack?: string;
+  errorBoundary?: unknown;
+};
+type HydrateRootErrorHandler = (error: unknown, errorInfo: VinextHydrateRootErrorInfo) => void;
+declare function createOnUncaughtError(): HydrateRootErrorHandler;
+declare function createProdOnCaughtError(onImplicitRootError: HydrateRootErrorHandler): HydrateRootErrorHandler;
+declare function createDevOnCaughtError(onCaughtError: HydrateRootErrorHandler, onImplicitRootError: HydrateRootErrorHandler): HydrateRootErrorHandler;
+declare function prodOnCaughtError(error: unknown, errorInfo: VinextHydrateRootErrorInfo): void;
+declare function prodOnRecoverableError(error: unknown): void;
+//#endregion
+export { createDevOnCaughtError, createOnUncaughtError, createProdOnCaughtError, prodOnCaughtError, prodOnRecoverableError };

package/dist/server/app-browser-error.js

@@ -0,0 +1,52 @@
+import { isUnknownRecord } from "../utils/record.js";
+import { isNavigationSignalError } from "../utils/navigation-signal.js";
+//#region src/server/app-browser-error.ts
+function isImplicitRootErrorBoundary(errorInfo) {
+	if (!isUnknownRecord(errorInfo.errorBoundary)) return false;
+	const props = errorInfo.errorBoundary.props;
+	return isUnknownRecord(props) && props.isImplicitRootErrorBoundary === true;
+}
+function logCaughtError(error, errorInfo) {
+	console.error(error);
+	if (errorInfo?.componentStack) console.error("The above error occurred in a React component:\n" + errorInfo.componentStack);
+}
+function reportGlobalError(error) {
+	if (typeof globalThis.reportError === "function") {
+		globalThis.reportError(error);
+		return;
+	}
+	console.error(error);
+}
+function createOnUncaughtError() {
+	return (error) => {
+		reportGlobalError(error);
+	};
+}
+function createProdOnCaughtError(onImplicitRootError) {
+	return (error, errorInfo) => {
+		if (isNavigationSignalError(error)) return;
+		if (isImplicitRootErrorBoundary(errorInfo)) {
+			onImplicitRootError(error, errorInfo);
+			return;
+		}
+		logCaughtError(error, errorInfo);
+	};
+}
+function createDevOnCaughtError(onCaughtError, onImplicitRootError) {
+	return (error, errorInfo) => {
+		if (isImplicitRootErrorBoundary(errorInfo)) {
+			onImplicitRootError(error, errorInfo);
+			return;
+		}
+		onCaughtError(error, errorInfo);
+	};
+}
+function prodOnCaughtError(error, errorInfo) {
+	if (isNavigationSignalError(error)) return;
+	logCaughtError(error, errorInfo);
+}
+function prodOnRecoverableError(error) {
+	reportGlobalError(error instanceof Error && error.cause !== void 0 ? error.cause : error);
+}
+//#endregion
+export { createDevOnCaughtError, createOnUncaughtError, createProdOnCaughtError, prodOnCaughtError, prodOnRecoverableError };

package/dist/server/app-browser-history-controller.d.ts

@@ -0,0 +1,104 @@
+import { BfcacheIdMap, HistoryTraversalIntent } from "./app-history-state.js";
+import { AppRouterState } from "./app-browser-state.js";
+import { HistoryUpdateMode } from "./app-browser-navigation-controller.js";
+
+//#region src/server/app-browser-history-controller.d.ts
+/**
+ * Visible router-state metadata at the instant a hash-only navigation commits.
+ * `null` means the browser router tree has not committed yet, so the controller
+ * falls back to reading the same facts off the live history entry.
+ */
+type VisibleNavigationMetadata = {
+  bfcacheIds: BfcacheIdMap | null;
+  previousNextUrl: string | null;
+};
+type AppBrowserHistoryControllerDeps = {
+  initialHistoryState: unknown;
+  maxHistoryStateSnapshots: number; /** Reads `window.history.state`. Injected so the controller stays unit-testable. */
+  readHistoryState: () => unknown; /** Reads `window.location.href`. Injected so the controller stays unit-testable. */
+  readCurrentHref: () => string; /** Wraps `pushHistoryStateWithoutNotify(state, "", href)`. */
+  pushHistoryState: (state: unknown, href: string) => void; /** Wraps `replaceHistoryStateWithoutNotify(state, "", href)`. */
+  replaceHistoryState: (state: unknown, href: string) => void;
+  readVisibleNavigationMetadata: () => VisibleNavigationMetadata | null;
+};
+/**
+ * Candidate visible state resolved from a restorable history snapshot, handed to
+ * the entry's approved-visible-restore callback. The controller resolves the
+ * candidate and owns the traversal-index commit; the entry owns the actual
+ * `AppBrowserNavigationController.restoreHistorySnapshotVisibleState()` call and
+ * the `ApprovedVisibleCommit` boundary.
+ */
+type RestorableSnapshotCandidate = {
+  state: AppRouterState;
+  beforeCommit: () => void;
+};
+type RestoreHistorySnapshotOptions = {
+  historyState: unknown;
+  stageClientParams: (params: Record<string, string | string[]>) => void;
+  approveVisibleRestore: (candidate: RestorableSnapshotCandidate) => boolean;
+};
+type CommitNavigationHistoryOptions = {
+  bfcacheIds: BfcacheIdMap;
+  href: string;
+  historyUpdateMode: HistoryUpdateMode | undefined;
+  previousNextUrl: string | null;
+  targetHistoryIndex?: number | null;
+  stageClientParams: () => void;
+};
+/**
+ * Owns App Router browser-history metadata and traversal bookkeeping behind a
+ * typed seam: traversal index allocation/commit, push/replace/traverse/hash-only
+ * history-state writes, BFCache epoch/snapshot invalidation through
+ * `RestorableClientStateController`, and restorable-snapshot candidate
+ * resolution.
+ *
+ * Ownership boundary: this is not a second router or visible-state authority. It
+ * resolves history facts and delegates visible restoration through an injected
+ * approved-commit callback. It never sets router state directly, never imports
+ * `applyApprovedVisibleCommit()`, and never bypasses the `ApprovedVisibleCommit`
+ * boundary owned by `AppBrowserNavigationController`.
+ */
+declare class AppBrowserHistoryController {
+  #private;
+  constructor(deps: AppBrowserHistoryControllerDeps);
+  get currentHistoryTraversalIndex(): number | null;
+  allocateNavigationHistoryTraversalIndex(historyUpdateMode: HistoryUpdateMode | undefined): number | null;
+  commitHistoryTraversalIndex(index: number | null): void;
+  commitTraversalIndexFromHistoryState(historyState: unknown): void;
+  resolveTraversalIntent(historyState: unknown): HistoryTraversalIntent;
+  readCurrentBfcacheVersionHistoryIds(historyState: unknown): BfcacheIdMap | null;
+  isCacheInvalidationGuarded(): boolean;
+  isCurrentBfcacheVersion(historyState: unknown): boolean;
+  beginCacheInvalidationGuard(): () => void;
+  invalidateRestorableClientState(): void;
+  rememberHistoryStateSnapshot(state: AppRouterState): void;
+  commitHashOnlyNavigation(href: string, historyUpdateMode: HistoryUpdateMode, scroll: boolean): void;
+  /**
+   * Writes the history entry for an approved push/replace/traverse commit and
+   * advances the traversal index. `stageClientParams` runs at the exact point it
+   * ran inline in the browser-entry commit effect so client-param staging stays
+   * ordered relative to the history write. Mirrors Next.js committing tree state
+   * into the history entry during the navigation commit.
+   */
+  commitNavigationHistory(options: CommitNavigationHistoryOptions): void;
+  syncCurrentHistoryStatePreviousNextUrl(previousNextUrl: string | null, bfcacheIds?: BfcacheIdMap | null): void;
+  /** Initial history write performed before hydration starts. */
+  writeBootstrapHistoryMetadata(): void;
+  /** History write performed on the first committed (hydrated) render. */
+  writeHydratedHistoryMetadata(options: {
+    bfcacheIds: BfcacheIdMap;
+    previousNextUrl: string | null;
+  }): void;
+  /**
+   * Resolves a restorable snapshot candidate for the given history entry and
+   * commits the traversal index after, and only after, the injected
+   * approved-visible-restore callback succeeds. The traversal-index commit and
+   * client-param staging run inside `beforeCommit`, which the
+   * `AppBrowserNavigationController` invokes only once the `ApprovedVisibleCommit`
+   * is approved. Returns false when no snapshot is restorable or the restore is
+   * not approved.
+   */
+  restoreHistorySnapshot(options: RestoreHistorySnapshotOptions): boolean;
+}
+//#endregion
+export { AppBrowserHistoryController, RestorableSnapshotCandidate };

package/dist/server/app-browser-history-controller.js

@@ -0,0 +1,210 @@
+import { RestorableClientStateController, createHistoryStateWithNavigationMetadata, readHistoryStateBfcacheIds, readHistoryStatePreviousNextUrl, readHistoryStateTraversalIndex, resolveHistoryTraversalIntent } from "./app-history-state.js";
+//#region src/server/app-browser-history-controller.ts
+function stripVinextScrollState(state) {
+	if (!state || typeof state !== "object") return state;
+	const nextState = {};
+	for (const [key, value] of Object.entries(state)) {
+		if (key === "__vinext_scrollX" || key === "__vinext_scrollY") continue;
+		nextState[key] = value;
+	}
+	return Object.keys(nextState).length > 0 ? nextState : null;
+}
+/**
+* Owns App Router browser-history metadata and traversal bookkeeping behind a
+* typed seam: traversal index allocation/commit, push/replace/traverse/hash-only
+* history-state writes, BFCache epoch/snapshot invalidation through
+* `RestorableClientStateController`, and restorable-snapshot candidate
+* resolution.
+*
+* Ownership boundary: this is not a second router or visible-state authority. It
+* resolves history facts and delegates visible restoration through an injected
+* approved-commit callback. It never sets router state directly, never imports
+* `applyApprovedVisibleCommit()`, and never bypasses the `ApprovedVisibleCommit`
+* boundary owned by `AppBrowserNavigationController`.
+*/
+var AppBrowserHistoryController = class {
+	#restorableClientState;
+	#readHistoryState;
+	#readCurrentHref;
+	#pushHistoryState;
+	#replaceHistoryState;
+	#readVisibleNavigationMetadata;
+	#currentHistoryTraversalIndex;
+	#nextHistoryTraversalIndex;
+	constructor(deps) {
+		this.#readHistoryState = deps.readHistoryState;
+		this.#readCurrentHref = deps.readCurrentHref;
+		this.#pushHistoryState = deps.pushHistoryState;
+		this.#replaceHistoryState = deps.replaceHistoryState;
+		this.#readVisibleNavigationMetadata = deps.readVisibleNavigationMetadata;
+		this.#restorableClientState = new RestorableClientStateController({
+			initialHistoryState: deps.initialHistoryState,
+			maxHistoryStateSnapshots: deps.maxHistoryStateSnapshots
+		});
+		this.#currentHistoryTraversalIndex = readHistoryStateTraversalIndex(deps.initialHistoryState) ?? 0;
+		this.#nextHistoryTraversalIndex = this.#currentHistoryTraversalIndex;
+	}
+	get currentHistoryTraversalIndex() {
+		return this.#currentHistoryTraversalIndex;
+	}
+	allocateNavigationHistoryTraversalIndex(historyUpdateMode) {
+		switch (historyUpdateMode) {
+			case "push": return this.#nextHistoryTraversalIndex + 1;
+			case "replace": return this.#currentHistoryTraversalIndex;
+			case void 0: return null;
+			default: throw new Error("[vinext] Unknown history update mode: " + String(historyUpdateMode));
+		}
+	}
+	commitHistoryTraversalIndex(index) {
+		this.#currentHistoryTraversalIndex = index;
+		if (index !== null) this.#nextHistoryTraversalIndex = Math.max(this.#nextHistoryTraversalIndex, index);
+	}
+	commitTraversalIndexFromHistoryState(historyState) {
+		this.commitHistoryTraversalIndex(readHistoryStateTraversalIndex(historyState));
+	}
+	resolveTraversalIntent(historyState) {
+		return resolveHistoryTraversalIntent({
+			currentHistoryIndex: this.#currentHistoryTraversalIndex,
+			historyState
+		});
+	}
+	readCurrentBfcacheVersionHistoryIds(historyState) {
+		return this.#restorableClientState.readCurrentBfcacheVersionHistoryIds(historyState);
+	}
+	isCacheInvalidationGuarded() {
+		return this.#restorableClientState.isCacheInvalidationGuarded();
+	}
+	isCurrentBfcacheVersion(historyState) {
+		return this.#restorableClientState.isCurrentBfcacheVersion(historyState);
+	}
+	beginCacheInvalidationGuard() {
+		return this.#restorableClientState.beginCacheInvalidationGuard();
+	}
+	invalidateRestorableClientState() {
+		this.#restorableClientState.invalidateClientState();
+	}
+	rememberHistoryStateSnapshot(state) {
+		this.#restorableClientState.rememberHistoryStateSnapshot({
+			historyIndex: this.#currentHistoryTraversalIndex,
+			state
+		});
+	}
+	commitHashOnlyNavigation(href, historyUpdateMode, scroll) {
+		const navigationHistoryIndex = this.allocateNavigationHistoryTraversalIndex(historyUpdateMode);
+		const historyState = this.#readHistoryState();
+		const visible = this.#readVisibleNavigationMetadata();
+		const previousNextUrl = visible ? visible.previousNextUrl : readHistoryStatePreviousNextUrl(historyState);
+		const bfcacheIds = visible ? visible.bfcacheIds : this.#restorableClientState.readCurrentBfcacheVersionHistoryIds(historyState);
+		const nextHistoryState = createHistoryStateWithNavigationMetadata(this.#createHashOnlyNavigationBaseHistoryState(historyUpdateMode, scroll), {
+			bfcacheIds,
+			bfcacheVersion: bfcacheIds === null ? void 0 : this.#restorableClientState.currentBfcacheVersion,
+			previousNextUrl,
+			traversalIndex: navigationHistoryIndex
+		});
+		if (historyUpdateMode === "replace") this.#replaceHistoryState(nextHistoryState, href);
+		else this.#pushHistoryState(nextHistoryState, href);
+		this.commitHistoryTraversalIndex(navigationHistoryIndex);
+	}
+	#createHashOnlyNavigationBaseHistoryState(historyUpdateMode, scroll) {
+		if (historyUpdateMode !== "replace") return null;
+		const historyState = this.#readHistoryState();
+		return scroll ? stripVinextScrollState(historyState) : historyState;
+	}
+	/**
+	* Writes the history entry for an approved push/replace/traverse commit and
+	* advances the traversal index. `stageClientParams` runs at the exact point it
+	* ran inline in the browser-entry commit effect so client-param staging stays
+	* ordered relative to the history write. Mirrors Next.js committing tree state
+	* into the history entry during the navigation commit.
+	*/
+	commitNavigationHistory(options) {
+		const currentHref = this.#readCurrentHref();
+		const origin = new URL(currentHref).origin;
+		const targetHref = new URL(options.href, origin).href;
+		const preserveExistingState = options.historyUpdateMode === "replace";
+		const navigationHistoryIndex = options.targetHistoryIndex !== void 0 ? options.targetHistoryIndex : this.allocateNavigationHistoryTraversalIndex(options.historyUpdateMode);
+		const historyState = createHistoryStateWithNavigationMetadata(preserveExistingState ? this.#readHistoryState() : null, {
+			bfcacheIds: options.bfcacheIds,
+			bfcacheVersion: this.#restorableClientState.currentBfcacheVersion,
+			previousNextUrl: options.previousNextUrl,
+			traversalIndex: navigationHistoryIndex
+		});
+		let wroteHistoryState = false;
+		if (options.historyUpdateMode === "replace" && currentHref !== targetHref) {
+			options.stageClientParams();
+			this.#replaceHistoryState(historyState, options.href);
+			wroteHistoryState = true;
+			this.commitHistoryTraversalIndex(navigationHistoryIndex);
+		} else if (options.historyUpdateMode === "push" && currentHref !== targetHref) {
+			options.stageClientParams();
+			this.#pushHistoryState(historyState, options.href);
+			wroteHistoryState = true;
+			this.commitHistoryTraversalIndex(navigationHistoryIndex);
+		}
+		if (!wroteHistoryState) {
+			this.syncCurrentHistoryStatePreviousNextUrl(options.previousNextUrl, options.bfcacheIds);
+			options.stageClientParams();
+			if (options.targetHistoryIndex !== void 0) this.commitHistoryTraversalIndex(options.targetHistoryIndex);
+		}
+	}
+	syncCurrentHistoryStatePreviousNextUrl(previousNextUrl, bfcacheIds) {
+		if (this.#isHistoryStateNavigationMetadataInSync(this.#readHistoryState(), previousNextUrl, bfcacheIds)) return;
+		const nextHistoryState = createHistoryStateWithNavigationMetadata(this.#readHistoryState(), {
+			bfcacheIds,
+			bfcacheVersion: bfcacheIds === void 0 ? void 0 : this.#restorableClientState.currentBfcacheVersion,
+			previousNextUrl
+		});
+		this.#replaceHistoryState(nextHistoryState, this.#readCurrentHref());
+		if (this.#isHistoryStateNavigationMetadataInSync(this.#readHistoryState(), previousNextUrl, bfcacheIds)) return;
+		this.#replaceHistoryState(nextHistoryState, this.#readCurrentHref());
+	}
+	#isHistoryStateNavigationMetadataInSync(state, previousNextUrl, bfcacheIds) {
+		return readHistoryStatePreviousNextUrl(state) === previousNextUrl && (bfcacheIds === void 0 || areBfcacheIdMapsEqual(readHistoryStateBfcacheIds(state), bfcacheIds) && this.#restorableClientState.isCurrentBfcacheVersion(state));
+	}
+	/** Initial history write performed before hydration starts. */
+	writeBootstrapHistoryMetadata() {
+		this.#replaceHistoryState(createHistoryStateWithNavigationMetadata(this.#readHistoryState(), {
+			previousNextUrl: null,
+			traversalIndex: this.#currentHistoryTraversalIndex
+		}), this.#readCurrentHref());
+	}
+	/** History write performed on the first committed (hydrated) render. */
+	writeHydratedHistoryMetadata(options) {
+		this.#replaceHistoryState(createHistoryStateWithNavigationMetadata(this.#readHistoryState(), {
+			bfcacheIds: options.bfcacheIds,
+			bfcacheVersion: this.#restorableClientState.currentBfcacheVersion,
+			previousNextUrl: options.previousNextUrl,
+			traversalIndex: this.#currentHistoryTraversalIndex
+		}), this.#readCurrentHref());
+	}
+	/**
+	* Resolves a restorable snapshot candidate for the given history entry and
+	* commits the traversal index after, and only after, the injected
+	* approved-visible-restore callback succeeds. The traversal-index commit and
+	* client-param staging run inside `beforeCommit`, which the
+	* `AppBrowserNavigationController` invokes only once the `ApprovedVisibleCommit`
+	* is approved. Returns false when no snapshot is restorable or the restore is
+	* not approved.
+	*/
+	restoreHistorySnapshot(options) {
+		const decision = this.#restorableClientState.resolveHistoryStateSnapshotRestore(options.historyState);
+		if (decision.kind === "skip") return false;
+		return options.approveVisibleRestore({
+			state: decision.state,
+			beforeCommit: () => {
+				this.commitHistoryTraversalIndex(decision.targetHistoryIndex);
+				options.stageClientParams(decision.state.navigationSnapshot.params);
+			}
+		});
+	}
+};
+function areBfcacheIdMapsEqual(a, b) {
+	if (a === b) return true;
+	if (a === null || b === null) return false;
+	const aEntries = Object.entries(a);
+	const bEntries = Object.entries(b);
+	if (aEntries.length !== bEntries.length) return false;
+	return aEntries.every(([key, value]) => b[key] === value);
+}
+//#endregion
+export { AppBrowserHistoryController };

package/dist/server/app-browser-hydration.d.ts

@@ -0,0 +1,32 @@
+import { ReactFormState, hydrateRoot } from "react-dom/client";
+
+//#region src/server/app-browser-hydration.d.ts
+type HydrateRootOptions = NonNullable<Parameters<typeof hydrateRoot>[2]>;
+type HydrateRoot = typeof hydrateRoot;
+type HydrateRootContainer = Parameters<HydrateRoot>[0];
+type HydrateRootChildren = Parameters<HydrateRoot>[1];
+type HydrateRootReturn = ReturnType<HydrateRoot>;
+type HydrateRootCaughtErrorHandler = NonNullable<HydrateRootOptions["onCaughtError"]>;
+type HydrateRootUncaughtErrorHandler = NonNullable<HydrateRootOptions["onUncaughtError"]>;
+type HydrateRootRecoverableErrorHandler = NonNullable<HydrateRootOptions["onRecoverableError"]>;
+type StartTransition = (action: () => void) => void;
+declare const RSC_FORM_STATE_GLOBAL = "__VINEXT_RSC_FORM_STATE__";
+type FormStateGlobal = {
+  [RSC_FORM_STATE_GLOBAL]?: ReactFormState;
+};
+declare function consumeInitialFormState(global: FormStateGlobal): ReactFormState | null;
+declare function createVinextHydrateRootOptions(options: {
+  formState: ReactFormState | null;
+  onCaughtError?: HydrateRootCaughtErrorHandler;
+  onRecoverableError?: HydrateRootRecoverableErrorHandler;
+  onUncaughtError: HydrateRootUncaughtErrorHandler;
+}): HydrateRootOptions;
+declare function hydrateRootInTransition(options: {
+  children: HydrateRootChildren;
+  container: HydrateRootContainer;
+  hydrateRoot: HydrateRoot;
+  options: HydrateRootOptions;
+  startTransition: StartTransition;
+}): HydrateRootReturn;
+//#endregion
+export { RSC_FORM_STATE_GLOBAL, consumeInitialFormState, createVinextHydrateRootOptions, hydrateRootInTransition };

package/dist/server/app-browser-hydration.js

@@ -0,0 +1,29 @@
+//#region src/server/app-browser-hydration.ts
+const RSC_FORM_STATE_GLOBAL = "__VINEXT_RSC_FORM_STATE__";
+function consumeInitialFormState(global) {
+	const formState = global["__VINEXT_RSC_FORM_STATE__"] ?? null;
+	delete global[RSC_FORM_STATE_GLOBAL];
+	return formState;
+}
+function createVinextHydrateRootOptions(options) {
+	const hydrateOptions = {
+		formState: options.formState,
+		...options.onRecoverableError ? { onRecoverableError: options.onRecoverableError } : {},
+		onUncaughtError: options.onUncaughtError
+	};
+	if (options.onCaughtError) return {
+		...hydrateOptions,
+		onCaughtError: options.onCaughtError
+	};
+	return hydrateOptions;
+}
+function hydrateRootInTransition(options) {
+	let root;
+	options.startTransition(() => {
+		root = options.hydrateRoot(options.container, options.children, options.options);
+	});
+	if (root === void 0) throw new Error("[vinext] React.startTransition did not synchronously start hydration");
+	return root;
+}
+//#endregion
+export { RSC_FORM_STATE_GLOBAL, consumeInitialFormState, createVinextHydrateRootOptions, hydrateRootInTransition };

package/dist/server/app-browser-interception-context.d.ts

@@ -0,0 +1,24 @@
+import { RouteManifest } from "../routing/app-route-graph.js";
+
+//#region src/server/app-browser-interception-context.d.ts
+type ResolveManifestNavigationInterceptionContextOptions = {
+  basePath: string;
+  currentPathname: string;
+  routeManifest: RouteManifest | null;
+  targetPathname: string;
+};
+/**
+ * Resolve the first-hop interception context from declared route topology.
+ *
+ * This is intentionally manifest-only: it lets a normal browser navigation
+ * ask the server for an intercepted payload when the current URL is a declared
+ * interception source for the target URL, without reintroducing snapshot
+ * topology as route/layout/slot authority.
+ *
+ * When multiple manifest interceptions match, the first one wins. That order
+ * is owned by the deterministic route graph builder.
+ */
+declare function resolveManifestNavigationInterceptionContext(options: ResolveManifestNavigationInterceptionContextOptions): string | null;
+declare function resolveMiddlewareRewriteNavigationInterceptionContext(options: ResolveManifestNavigationInterceptionContextOptions): string | null;
+//#endregion
+export { resolveManifestNavigationInterceptionContext, resolveMiddlewareRewriteNavigationInterceptionContext };

package/dist/server/app-browser-interception-context.js

@@ -0,0 +1,43 @@
+import { splitPathnameForRouteMatch } from "../routing/utils.js";
+import { stripBasePath } from "../utils/base-path.js";
+import { matchRoutePattern, matchRoutePatternPrefix, matchRoutePatternWithOptionalDynamicSegments } from "../routing/route-pattern.js";
+//#region src/server/app-browser-interception-context.ts
+/**
+* Resolve the first-hop interception context from declared route topology.
+*
+* This is intentionally manifest-only: it lets a normal browser navigation
+* ask the server for an intercepted payload when the current URL is a declared
+* interception source for the target URL, without reintroducing snapshot
+* topology as route/layout/slot authority.
+*
+* When multiple manifest interceptions match, the first one wins. That order
+* is owned by the deterministic route graph builder.
+*/
+function resolveManifestNavigationInterceptionContext(options) {
+	if (options.routeManifest === null) return null;
+	const currentPathname = stripBasePath(options.currentPathname, options.basePath);
+	const targetPathname = stripBasePath(options.targetPathname, options.basePath);
+	const sourceParts = splitPathnameForRouteMatch(currentPathname);
+	const targetParts = splitPathnameForRouteMatch(targetPathname);
+	for (const interception of options.routeManifest.segmentGraph.interceptions.values()) {
+		if (!matchRoutePatternPrefix(sourceParts, interception.sourcePatternParts)) continue;
+		if (matchRoutePattern(targetParts, interception.targetPatternParts) === null) continue;
+		return currentPathname;
+	}
+	return null;
+}
+function resolveMiddlewareRewriteNavigationInterceptionContext(options) {
+	if (options.routeManifest === null) return null;
+	const currentPathname = stripBasePath(options.currentPathname, options.basePath);
+	const targetPathname = stripBasePath(options.targetPathname, options.basePath);
+	const sourceParts = splitPathnameForRouteMatch(currentPathname);
+	const targetParts = splitPathnameForRouteMatch(targetPathname);
+	for (const interception of options.routeManifest.segmentGraph.interceptions.values()) {
+		if (!matchRoutePatternPrefix(sourceParts, interception.sourcePatternParts)) continue;
+		if (!matchRoutePatternWithOptionalDynamicSegments(targetParts, interception.targetPatternParts)) continue;
+		return currentPathname;
+	}
+	return null;
+}
+//#endregion
+export { resolveManifestNavigationInterceptionContext, resolveMiddlewareRewriteNavigationInterceptionContext };

package/dist/server/app-browser-mpa-navigation.d.ts

@@ -0,0 +1,16 @@
+import { HistoryUpdateMode } from "./app-browser-navigation-controller.js";
+
+//#region src/server/app-browser-mpa-navigation.d.ts
+type AppBrowserMpaNavigationWindow = {
+  location: Pick<Location, "assign" | "replace">;
+  requestAnimationFrame?: (callback: FrameRequestCallback) => unknown;
+  setTimeout(callback: () => void, timeout: number): unknown;
+};
+declare function hasPendingAppRouterPageRedirect(targetDocument: unknown): boolean;
+declare class AppBrowserMpaNavigationScheduler {
+  #private;
+  reset(): void;
+  navigate(targetWindow: AppBrowserMpaNavigationWindow, href: string, historyUpdateMode: HistoryUpdateMode): void;
+}
+//#endregion
+export { AppBrowserMpaNavigationScheduler, AppBrowserMpaNavigationWindow, hasPendingAppRouterPageRedirect };

package/dist/server/app-browser-mpa-navigation.js

@@ -0,0 +1,42 @@
+//#region src/server/app-browser-mpa-navigation.ts
+const NEXT_APP_ROUTER_PAGE_REDIRECT_MARKER_ID = "__next-page-redirect";
+function hasPendingAppRouterPageRedirect(targetDocument) {
+	if (typeof targetDocument !== "object" || targetDocument === null) return false;
+	if (!("getElementById" in targetDocument)) return false;
+	const { getElementById } = targetDocument;
+	if (typeof getElementById !== "function") return false;
+	return getElementById.call(targetDocument, NEXT_APP_ROUTER_PAGE_REDIRECT_MARKER_ID) !== null;
+}
+var AppBrowserMpaNavigationScheduler = class {
+	#pendingNavigation = null;
+	#nextToken = 0;
+	reset() {
+		this.#pendingNavigation = null;
+	}
+	navigate(targetWindow, href, historyUpdateMode) {
+		const pendingNavigation = this.#pendingNavigation;
+		if (pendingNavigation?.href === href && pendingNavigation.historyUpdateMode === historyUpdateMode) return;
+		const token = this.#nextToken + 1;
+		this.#nextToken = token;
+		this.#pendingNavigation = {
+			href,
+			historyUpdateMode,
+			token
+		};
+		const navigate = () => {
+			const currentNavigation = this.#pendingNavigation;
+			if (currentNavigation?.href !== href || currentNavigation.historyUpdateMode !== historyUpdateMode || currentNavigation.token !== token) return;
+			if (historyUpdateMode === "replace") targetWindow.location.replace(href);
+			else targetWindow.location.assign(href);
+		};
+		if (typeof targetWindow.requestAnimationFrame === "function") {
+			targetWindow.requestAnimationFrame(() => {
+				targetWindow.setTimeout(navigate, 0);
+			});
+			return;
+		}
+		targetWindow.setTimeout(navigate, 0);
+	}
+};
+//#endregion
+export { AppBrowserMpaNavigationScheduler, hasPendingAppRouterPageRedirect };