vinext 1.2.0 → 1.3.0

package/dist/plugins/worker-image-imports.js

@@ -1,10 +1,9 @@
 import path, { toSlash } from "../deps/.pnpm/pathslash@0.1.0/deps/pathslash/dist/index.js";
-import { staticStringValue, walkAst } from "./ast-utils.js";
+import { parseModuleRecord, quotedStringAt } from "./ast-utils.js";
 import { magicStringTransformResult } from "./transform-result.js";
 import { appendDeploymentIdQuery } from "../utils/deployment-id.js";
 import { NODE_MODULES_PATH_RE, stripViteModuleQuery } from "../utils/path.js";
 import fs from "node:fs";
-import { parseAst } from "vite";
 import MagicString from "magic-string";
 //#region src/plugins/worker-image-imports.ts
 const WORKER_IMAGE_METADATA_PREFIX = "\0vinext-worker-image-meta:";
@@ -70,24 +69,19 @@ function createWorkerImageImportsPlugin(options = {}) {
 			},
 			async handler(code, id) {
 				const sourceId = toSlash(stripViteModuleQuery(id));
-				let ast;
-				try {
-					ast = parseAst(code, { lang: /\.(?:[cm]?ts)$/.test(sourceId) ? "ts" : "tsx" });
-				} catch {
-					return null;
-				}
+				const record = parseModuleRecord(code, /\.(?:[cm]?ts)$/.test(sourceId) ? "ts" : "tsx");
+				if (!record) return null;
 				const output = new MagicString(code);
 				const imageImports = [];
-				walkAst(ast, (node) => {
-					if (node.type === "ImportExpression" && node.source.type === "Literal" && typeof node.source.value === "string" && WORKER_IMAGE_EXTENSION_RE.test(node.source.value)) {
-						imageImports.push({
-							end: node.end,
-							importPath: node.source.value,
-							start: node.start
-						});
-						return false;
-					}
-				});
+				for (const dynamicImport of record.dynamicImports) {
+					const importPath = quotedStringAt(code, dynamicImport.moduleRequest);
+					if (importPath === null || !WORKER_IMAGE_EXTENSION_RE.test(importPath)) continue;
+					imageImports.push({
+						end: dynamicImport.end,
+						importPath,
+						start: dynamicImport.start
+					});
+				}
 				let changed = false;
 				for (const imageImport of imageImports) {
 					const resolved = await this.resolve(imageImport.importPath, sourceId, { skipSelf: true });
@@ -107,23 +101,26 @@ function createWorkerImageImportsPlugin(options = {}) {
 				if (!options.deploymentId) return null;
 				const chunkSpecifiers = new Set([...chunk.imports, ...chunk.dynamicImports].map((target) => workerChunkSpecifier(chunk.fileName, target)));
 				if (chunkSpecifiers.size === 0) return null;
-				let ast;
-				try {
-					ast = parseAst(code);
-				} catch {
-					return null;
-				}
+				const record = parseModuleRecord(code, "js");
+				if (!record) return null;
+				const sources = [
+					...record.staticImports.map((statement) => statement.moduleRequest),
+					...record.staticExports.flatMap((statement) => statement.entries[0]?.moduleRequest ?? []),
+					...record.dynamicImports.map((dynamicImport) => {
+						const value = quotedStringAt(code, dynamicImport.moduleRequest);
+						return value === null ? [] : {
+							...dynamicImport.moduleRequest,
+							value
+						};
+					})
+				].flat();
 				const output = new MagicString(code);
 				let changed = false;
-				walkAst(ast, (node) => {
-					const source = node.type === "ImportExpression" || node.type === "ImportDeclaration" || node.type === "ExportNamedDeclaration" || node.type === "ExportAllDeclaration" ? node.source : null;
-					const specifier = staticStringValue(source);
-					if (specifier !== null && chunkSpecifiers.has(specifier) && source) {
-						output.overwrite(source.start, source.end, JSON.stringify(appendDeploymentIdQuery(specifier, options.deploymentId)));
-						changed = true;
-						return false;
-					}
-				});
+				for (const source of sources) {
+					if (!chunkSpecifiers.has(source.value)) continue;
+					output.overwrite(source.start, source.end, JSON.stringify(appendDeploymentIdQuery(source.value, options.deploymentId)));
+					changed = true;
+				}
 				if (!changed) return null;
 				return magicStringTransformResult(output);
 			}
@@ -131,4 +128,4 @@ function createWorkerImageImportsPlugin(options = {}) {
 	};
 }
 //#endregion
-export { createWorkerImageImportsPlugin };
+export { WORKER_IMAGE_METADATA_PREFIX, createWorkerImageImportsPlugin };

package/dist/plugins/worker-use-server.js

@@ -1,10 +1,12 @@
 import path, { toSlash } from "../deps/.pnpm/pathslash@0.1.0/deps/pathslash/dist/index.js";
 import { escapeRegExp } from "../utils/regex.js";
+import { parseProgramAsync } from "./ast-utils.js";
 import { magicStringTransformResult } from "./transform-result.js";
+import { USE_CACHE_PLUGIN_NAME as PLUGIN_NAME } from "./use-cache-callable.js";
 import { createRequire } from "node:module";
 import fs from "node:fs";
 import { pathToFileURL } from "node:url";
-import { parseAstAsync, transformWithOxc } from "vite";
+import { isCSSRequest, transformWithOxc } from "vite";
 //#region src/plugins/worker-use-server.ts
 const WORKER_REFERENCE_RUNTIME_ID = "\0vinext:worker-server-reference";
 const WORKER_REFERENCE_RUNTIME_ID_RE = /^\0vinext:worker-server-reference$/;
@@ -60,12 +62,14 @@ async function createWorkerUseServerPlugins(options) {
 	const browserRuntime = pathToFileURL(rscRequire.resolve("@vitejs/plugin-rsc/react/browser")).href;
 	const [transforms, rscCore] = await Promise.all([importRscModule("@vitejs/plugin-rsc/transforms"), importRscModule("@vitejs/plugin-rsc/core/plugin")]);
 	let manager;
+	let useCacheApi;
 	const useServerPlugin = {
 		name: "vinext:worker-use-server",
 		async configResolved(config) {
 			// @vitejs/plugin-rsc's plugin API (and its reference manager) lives.
 			const mainConfig = config.mainConfig;
 			manager = (await options.rscPluginModule).getPluginApi(mainConfig ?? config)?.manager;
+			useCacheApi = (mainConfig ?? config).plugins.find((plugin) => plugin.name === PLUGIN_NAME)?.api;
 		},
 		resolveId: {
 			filter: { id: WORKER_REFERENCE_RUNTIME_ID_RE },
@@ -78,7 +82,7 @@ async function createWorkerUseServerPlugins(options) {
 		transform: {
 			filter: { code: "use server" },
 			async handler(code, id) {
-				let ast = await parseAstAsync(code);
+				let ast = await parseProgramAsync(code);
 				if (!transforms.hasDirective(ast.body, "use server")) return null;
 				if (!manager) throw new Error("vinext: cannot compile a \"use server\" module in a Web Worker without @vitejs/plugin-rsc.");
 				const expanded = await withPositionedError(this, () => transforms.transformExpandExportAll({
@@ -90,12 +94,12 @@ async function createWorkerUseServerPlugins(options) {
 						if (!isPlainFilePath(target)) throw new Error(`vinext: a "use server" module imported by a Web Worker cannot \`export *\` from ${JSON.stringify(target)}; re-export its names explicitly.`);
 						this.addWatchFile(target);
 						const source = await fs.promises.readFile(target, "utf-8");
-						return parseAstAsync((await transformWithOxc(source, target, { sourcemap: false })).code);
+						return parseProgramAsync((await transformWithOxc(source, target, { sourcemap: false })).code);
 					}
 				}));
 				if (expanded) {
 					code = expanded.code;
-					ast = await parseAstAsync(code);
+					ast = await parseProgramAsync(code);
 				}
 				const { referenceKey } = manager.serverReferences.resolve(id, "rsc");
 				const runtime = uniqueBinding(code, "$$vinextWorkerReference");
@@ -111,19 +115,39 @@ async function createWorkerUseServerPlugins(options) {
 			}
 		}
 	};
+	const useCachePlugin = {
+		name: "vinext:worker-use-cache",
+		transform: {
+			filter: { code: "use cache" },
+			async handler(code, id) {
+				if (isCSSRequest(id)) return null;
+				const api = useCacheApi;
+				if (!api) throw new Error("vinext: cannot compile a \"use cache\" module in a Web Worker without vinext's \"use cache\" plugin.");
+				const runtime = uniqueBinding(code, "$$vinextWorkerReference");
+				const output = await withPositionedError(this, () => api.transformWorkerModule(code, id, (referenceId, name) => `${runtime}(${JSON.stringify(referenceId)}, ${JSON.stringify(name)})`));
+				if (!output) return null;
+				output.prepend(`import { createWorkerServerReference as ${runtime} } from ${JSON.stringify(WORKER_REFERENCE_RUNTIME_ID)};\n`);
+				return magicStringTransformResult(output);
+			}
+		}
+	};
 	const patchHook = rscCore.default().find((plugin) => plugin.name === "rsc:patch-react-server-dom-webpack")?.transform;
 	if (!patchHook || typeof patchHook !== "object") throw new Error("vinext: @vitejs/plugin-rsc no longer exposes its Flight client patch plugin.");
 	const flightClientDir = path.dirname(rscRequire.resolve("@vitejs/plugin-rsc/vendor/react-server-dom/client.browser"));
-	return [{
-		name: "vinext:worker-patch-react-server-dom",
-		transform: {
-			filter: {
-				id: new RegExp(`^${escapeRegExp(`${toSlash(flightClientDir)}/`)}`),
-				code: "__webpack_require__"
-			},
-			handler: patchHook.handler
-		}
-	}, useServerPlugin];
+	return [
+		{
+			name: "vinext:worker-patch-react-server-dom",
+			transform: {
+				filter: {
+					id: new RegExp(`^${escapeRegExp(`${toSlash(flightClientDir)}/`)}`),
+					code: "__webpack_require__"
+				},
+				handler: patchHook.handler
+			}
+		},
+		useCachePlugin,
+		useServerPlugin
+	];
 }
 //#endregion
 export { createWorkerUseServerPlugins };

package/dist/routing/app-route-graph.d.ts

@@ -275,7 +275,7 @@ type RouteManifestRouteHandler = {
   routeId: string;
   pattern: string;
 };
-type RouteManifestLayout = {
+export type RouteManifestLayout = {
   id: string;
   treePath: string;
   patternParts: readonly string[];

package/dist/routing/browser-route-manifest.d.ts

@@ -0,0 +1,43 @@
+import { GraphVersion, RouteManifest, RouteManifestInterception, RouteManifestLayout, RouteManifestRootBoundary, RouteManifestRoute, RouteManifestSlotBinding } from "./app-route-graph.js";
+//#region src/routing/browser-route-manifest.d.ts
+export type BrowserRouteManifestRoute = Pick<RouteManifestRoute, "id" | "patternParts" | "isDynamic" | "paramNames" | "rootBoundaryId" | "pageId" | "layoutIds" | "slotIds">;
+type BrowserRouteManifestLayout = Pick<RouteManifestLayout, "id" | "patternParts" | "rootBoundaryId">;
+type BrowserRouteManifestSlotBinding = Pick<RouteManifestSlotBinding, "id" | "routeId" | "slotId" | "ownerLayoutId" | "state" | "routeSegments" | "slotPatternParts" | "slotParamNames">;
+export type BrowserRouteManifestInterception = Pick<RouteManifestInterception, "id" | "sourcePatternParts" | "targetPatternParts" | "slotId" | "ownerLayoutId" | "targetRouteId">;
+type BrowserRouteManifestRootBoundary = Pick<RouteManifestRootBoundary, "id" | "treePath">;
+/**
+ * The part of the RouteManifest the browser navigation runtime reads: the
+ * maps and fields the navigation planner, optimistic routing and interception
+ * context resolution use.
+ */
+export type BrowserRouteManifest = {
+  graphVersion: GraphVersion;
+  segmentGraph: {
+    routes: ReadonlyMap<string, BrowserRouteManifestRoute>;
+    layouts: ReadonlyMap<string, BrowserRouteManifestLayout>;
+    slotBindings: ReadonlyMap<string, BrowserRouteManifestSlotBinding>;
+    interceptions: ReadonlyMap<string, BrowserRouteManifestInterception>;
+    interceptionsBySlotId: ReadonlyMap<string, readonly BrowserRouteManifestInterception[]>;
+    rootBoundaries: ReadonlyMap<string, BrowserRouteManifestRootBoundary>;
+  };
+};
+/**
+ * JSON form of `BrowserRouteManifest`. Every map is keyed by its values' `id`,
+ * so maps travel as arrays of values in map order. A route omits `id` when it
+ * is `route:` plus its pattern, and `interceptionsBySlotId` lists interception
+ * ids instead of repeating the interceptions.
+ */
+export type BrowserRouteManifestWire = {
+  graphVersion: string;
+  routes: (Omit<BrowserRouteManifestRoute, "id"> & {
+    id?: string;
+  })[];
+  layouts: BrowserRouteManifestLayout[];
+  slotBindings: BrowserRouteManifestSlotBinding[];
+  interceptions: BrowserRouteManifestInterception[];
+  interceptionsBySlotId: [slotId: string, interceptionIds: string[]][];
+  rootBoundaries: BrowserRouteManifestRootBoundary[];
+};
+export declare function toBrowserRouteManifestWire(routeManifest: RouteManifest): BrowserRouteManifestWire;
+export declare function decodeBrowserRouteManifest(wire: BrowserRouteManifestWire): BrowserRouteManifest;
+//#endregion

package/dist/routing/browser-route-manifest.js

@@ -0,0 +1,195 @@
+import { buildOptimisticRouteTrie } from "./optimistic-route-trie.js";
+//#region src/routing/browser-route-manifest.ts
+function createRouteIdFromPatternParts(patternParts) {
+	return `route:/${patternParts.join("/")}`;
+}
+/**
+* Route matching precedence of one pattern part, lower wins: the URL ending
+* here, then a static, dynamic, catch-all and optional catch-all part.
+*/
+function patternPartRank(part) {
+	if (part === void 0) return 0;
+	if (!part.startsWith(":")) return 1;
+	if (part.endsWith("+")) return 3;
+	if (part.endsWith("*")) return 4;
+	return 2;
+}
+/**
+* Whether the router sends a URL pathname that both patterns match to the
+* route handler: it wins at the first part whose kind differs. Two patterns
+* that never differ would be the same route shape, which cannot hold both a
+* handler and a page.
+*/
+function routeHandlerOutranks(handler, rendered) {
+	for (let index = 0;; index++) {
+		const handlerRank = patternPartRank(handler[index]);
+		const renderedRank = patternPartRank(rendered[index]);
+		if (handlerRank !== renderedRank) return handlerRank < renderedRank;
+		if (handlerRank === 0 || handlerRank >= 3) return false;
+	}
+}
+/**
+* Whether the optimistic trie of the rendered routes predicts a rendered
+* route that the route handler outranks for some URL pathname the handler
+* pattern matches. The trie match descends one path and only backtracks to a
+* catch-all on its way up, so this follows that path for every URL: a param
+* segment either names one of the node's static children or none of them,
+* and a catch-all takes any number of such segments.
+*/
+function triePredictsOutrankedRoute(trie, handler) {
+	const lastPart = handler.at(-1);
+	const isCatchAll = lastPart?.startsWith(":") === true && /[+*]$/.test(lastPart);
+	const fixedLength = isCatchAll ? handler.length - 1 : handler.length;
+	const minLength = lastPart?.endsWith("+") === true ? handler.length : fixedLength;
+	const predict = (route) => route === null ? {
+		outranked: false,
+		unmatched: true
+	} : {
+		outranked: routeHandlerOutranks(handler, route.patternParts),
+		unmatched: false
+	};
+	const afterOtherSegment = (node, depth) => {
+		const dynamic = node.dynamicChild ? predictFrom(node.dynamicChild.node, depth) : {
+			outranked: false,
+			unmatched: true
+		};
+		if (!dynamic.unmatched) return dynamic;
+		const fallback = predict(node.catchAllChild?.route ?? node.optionalCatchAllChild?.route ?? null);
+		return {
+			outranked: dynamic.outranked || fallback.outranked,
+			unmatched: fallback.unmatched
+		};
+	};
+	const predictFrom = (node, depth) => {
+		const predictions = {
+			outranked: false,
+			unmatched: false
+		};
+		const add = (more) => {
+			predictions.outranked ||= more.outranked;
+			predictions.unmatched ||= more.unmatched;
+		};
+		if (isCatchAll ? depth >= minLength : depth === fixedLength) add(predict(node.route ?? node.optionalCatchAllChild?.route ?? null));
+		if (depth < fixedLength && !handler[depth].startsWith(":")) {
+			const child = node.staticChildren.get(handler[depth]);
+			add(child ? predictFrom(child, depth + 1) : afterOtherSegment(node, depth + 1));
+		} else if (depth < fixedLength || isCatchAll) {
+			for (const child of node.staticChildren.values()) add(predictFrom(child, depth + 1));
+			add(afterOtherSegment(node, depth + 1));
+		}
+		return predictions;
+	};
+	return predictFrom(trie, 0).outranked;
+}
+/**
+* The browser only needs a route handler where the optimistic route trie of
+* the rendered routes would predict a route the handler outranks: the matcher
+* must find the handler there instead of rendering that route's shell. Any
+* other handler URL matches no rendered route on the client, or one the
+* router prefers, and its non-Flight response already turns the navigation
+* into a document load, so shipping its path would only publish the app's
+* API surface (issue #3624).
+*/
+function selectBrowserRoutes(routes) {
+	const allRoutes = [...routes];
+	const renderedTrie = buildOptimisticRouteTrie(allRoutes.filter((route) => route.routeHandlerId === null));
+	return allRoutes.filter((route) => route.routeHandlerId === null || triePredictsOutrankedRoute(renderedTrie, route.patternParts));
+}
+/**
+* The graph records the browser receives: the shipped routes, the rendered
+* routes' slot bindings, and the layouts and root boundaries those and the
+* interceptions reach. A shipped route handler only stops an optimistic
+* match, and its non-Flight response never renders a tree, so it ships as a
+* bare pattern; its layouts, slots and root boundary would only name its
+* directories.
+*/
+function selectBrowserGraph(graph) {
+	const routes = selectBrowserRoutes(graph.routes.values()).map((route) => route.routeHandlerId === null ? route : {
+		...route,
+		layoutIds: [],
+		rootBoundaryId: null,
+		slotIds: []
+	});
+	const renderedRouteIds = new Set(routes.filter((route) => route.routeHandlerId === null).map((route) => route.id));
+	const slotBindings = [...graph.slotBindings.values()].filter((binding) => renderedRouteIds.has(binding.routeId));
+	const layoutIds = /* @__PURE__ */ new Set([
+		...routes.flatMap((route) => route.layoutIds),
+		...slotBindings.flatMap((binding) => binding.ownerLayoutId ?? []),
+		...[...graph.interceptions.values()].flatMap((interception) => interception.ownerLayoutId ?? [])
+	]);
+	const layouts = [...graph.layouts.values()].filter((layout) => layoutIds.has(layout.id));
+	const rootBoundaryIds = new Set([...routes, ...layouts].flatMap((record) => record.rootBoundaryId ?? []));
+	return {
+		routes,
+		layouts,
+		slotBindings,
+		rootBoundaries: [...graph.rootBoundaries.values()].filter((rootBoundary) => rootBoundaryIds.has(rootBoundary.id))
+	};
+}
+function toBrowserRouteManifestWire(routeManifest) {
+	const graph = routeManifest.segmentGraph;
+	const browserGraph = selectBrowserGraph(graph);
+	return {
+		graphVersion: routeManifest.graphVersion,
+		routes: browserGraph.routes.map((route) => ({
+			...route.id === createRouteIdFromPatternParts(route.patternParts) ? {} : { id: route.id },
+			patternParts: route.patternParts,
+			isDynamic: route.isDynamic,
+			paramNames: route.paramNames,
+			rootBoundaryId: route.rootBoundaryId,
+			pageId: route.pageId,
+			layoutIds: route.layoutIds,
+			slotIds: route.slotIds
+		})),
+		layouts: browserGraph.layouts.map((layout) => ({
+			id: layout.id,
+			patternParts: layout.patternParts,
+			rootBoundaryId: layout.rootBoundaryId
+		})),
+		slotBindings: browserGraph.slotBindings.map((binding) => ({
+			id: binding.id,
+			routeId: binding.routeId,
+			slotId: binding.slotId,
+			ownerLayoutId: binding.ownerLayoutId,
+			state: binding.state,
+			routeSegments: binding.routeSegments,
+			slotPatternParts: binding.slotPatternParts,
+			slotParamNames: binding.slotParamNames
+		})),
+		interceptions: Array.from(graph.interceptions.values(), (interception) => ({
+			id: interception.id,
+			sourcePatternParts: interception.sourcePatternParts,
+			targetPatternParts: interception.targetPatternParts,
+			slotId: interception.slotId,
+			ownerLayoutId: interception.ownerLayoutId,
+			targetRouteId: interception.targetRouteId
+		})),
+		interceptionsBySlotId: Array.from(graph.interceptionsBySlotId, ([slotId, interceptions]) => [slotId, interceptions.map((interception) => interception.id)]),
+		rootBoundaries: browserGraph.rootBoundaries.map((rootBoundary) => ({
+			id: rootBoundary.id,
+			treePath: rootBoundary.treePath
+		}))
+	};
+}
+function mapById(values) {
+	return new Map(values.map((value) => [value.id, value]));
+}
+function decodeBrowserRouteManifest(wire) {
+	const interceptions = mapById(wire.interceptions);
+	return {
+		graphVersion: wire.graphVersion,
+		segmentGraph: {
+			routes: mapById(wire.routes.map((route) => ({
+				...route,
+				id: route.id ?? createRouteIdFromPatternParts(route.patternParts)
+			}))),
+			layouts: mapById(wire.layouts),
+			slotBindings: mapById(wire.slotBindings),
+			interceptions,
+			interceptionsBySlotId: new Map(wire.interceptionsBySlotId.map(([slotId, interceptionIds]) => [slotId, interceptionIds.flatMap((id) => interceptions.get(id) ?? [])])),
+			rootBoundaries: mapById(wire.rootBoundaries)
+		}
+	};
+}
+//#endregion
+export { decodeBrowserRouteManifest, toBrowserRouteManifestWire };

package/dist/routing/hashed-route-patterns.d.ts

@@ -0,0 +1,4 @@
+//#region src/routing/hashed-route-patterns.d.ts
+export declare function hashRoutePatternParts(patternParts: readonly string[]): string[];
+export declare function hashRoutePathname(pathname: string): string;
+//#endregion

package/dist/routing/hashed-route-patterns.js

@@ -0,0 +1,22 @@
+import { splitPathnameForRouteMatch } from "./utils.js";
+import { fnv1a64 } from "../utils/hash.js";
+//#region src/routing/hashed-route-patterns.ts
+/**
+* Hybrid App/Pages clients need App route handler patterns only to decide
+* route ownership, so they receive them with every static segment hashed and
+* never see the handlers' paths in plain text (issue #3624). Dynamic parts
+* stay as they are, so a hashed pattern matches a hashed URL with the usual
+* route trie. A collision can only add a false handler match, which sends the
+* navigation to the document.
+*/
+function hashRouteSegment(segment) {
+	return fnv1a64(segment).slice(0, 8);
+}
+function hashRoutePatternParts(patternParts) {
+	return patternParts.map((part) => part.startsWith(":") ? part : hashRouteSegment(part));
+}
+function hashRoutePathname(pathname) {
+	return "/" + splitPathnameForRouteMatch(pathname).map(hashRouteSegment).join("/");
+}
+//#endregion
+export { hashRoutePathname, hashRoutePatternParts };

package/dist/routing/optimistic-route-trie.d.ts

@@ -0,0 +1,27 @@
+//#region src/routing/optimistic-route-trie.d.ts
+type OptimisticTrieRoute = {
+  readonly patternParts: readonly string[];
+};
+export type OptimisticRouteTrieNode<Route extends OptimisticTrieRoute> = {
+  catchAllChild: {
+    paramName: string;
+    route: Route;
+  } | null;
+  dynamicChild: {
+    node: OptimisticRouteTrieNode<Route>;
+    paramName: string;
+  } | null;
+  optionalCatchAllChild: {
+    paramName: string;
+    route: Route;
+  } | null;
+  route: Route | null;
+  staticChildren: Map<string, OptimisticRouteTrieNode<Route>>;
+};
+export type OptimisticRouteTrieMatch<Route extends OptimisticTrieRoute> = {
+  params: Record<string, string | string[]>;
+  route: Route;
+};
+export declare function buildOptimisticRouteTrie<Route extends OptimisticTrieRoute>(routes: Iterable<Route>, onDynamicSegmentConflict?: (existingParamName: string, part: string) => void): OptimisticRouteTrieNode<Route>;
+export declare function matchOptimisticRouteTrie<Route extends OptimisticTrieRoute>(trie: OptimisticRouteTrieNode<Route>, urlParts: readonly string[]): OptimisticRouteTrieMatch<Route> | null;
+//#endregion

package/dist/routing/optimistic-route-trie.js

@@ -0,0 +1,102 @@
+import { buildParams } from "./utils.js";
+//#region src/routing/optimistic-route-trie.ts
+function createNode() {
+	return {
+		catchAllChild: null,
+		dynamicChild: null,
+		optionalCatchAllChild: null,
+		route: null,
+		staticChildren: /* @__PURE__ */ new Map()
+	};
+}
+function buildOptimisticRouteTrie(routes, onDynamicSegmentConflict) {
+	const root = createNode();
+	for (const route of routes) {
+		let node = root;
+		const parts = route.patternParts;
+		if (parts.length === 0) {
+			node.route ??= route;
+			continue;
+		}
+		for (const [index, part] of parts.entries()) {
+			const isTerminal = index === parts.length - 1;
+			if (part.startsWith(":") && part.endsWith("+")) {
+				if (isTerminal && node.catchAllChild === null) node.catchAllChild = {
+					paramName: part.slice(1, -1),
+					route
+				};
+				break;
+			}
+			if (part.startsWith(":") && part.endsWith("*")) {
+				if (isTerminal && node.optionalCatchAllChild === null) node.optionalCatchAllChild = {
+					paramName: part.slice(1, -1),
+					route
+				};
+				break;
+			}
+			if (part.startsWith(":")) {
+				const paramName = part.slice(1);
+				if (node.dynamicChild === null) node.dynamicChild = {
+					node: createNode(),
+					paramName
+				};
+				else if (node.dynamicChild.paramName !== paramName) onDynamicSegmentConflict?.(node.dynamicChild.paramName, part);
+				node = node.dynamicChild.node;
+				if (isTerminal) node.route ??= route;
+				continue;
+			}
+			let staticChild = node.staticChildren.get(part);
+			if (staticChild === void 0) {
+				staticChild = createNode();
+				node.staticChildren.set(part, staticChild);
+			}
+			node = staticChild;
+			if (isTerminal) node.route ??= route;
+		}
+	}
+	return root;
+}
+function matchNode(node, urlParts, index, entries) {
+	if (index === urlParts.length) {
+		if (node.route !== null) return {
+			route: node.route,
+			params: buildParams(entries)
+		};
+		if (node.optionalCatchAllChild !== null) return {
+			route: node.optionalCatchAllChild.route,
+			params: buildParams(entries)
+		};
+		return null;
+	}
+	const segment = urlParts[index];
+	const staticChild = node.staticChildren.get(segment);
+	if (staticChild !== void 0) return matchNode(staticChild, urlParts, index + 1, entries);
+	if (node.dynamicChild !== null) {
+		entries.push([node.dynamicChild.paramName, segment]);
+		const match = matchNode(node.dynamicChild.node, urlParts, index + 1, entries);
+		if (match !== null) return match;
+		entries.pop();
+	}
+	if (node.catchAllChild !== null) {
+		const params = buildParams(entries);
+		params[node.catchAllChild.paramName] = urlParts.slice(index);
+		return {
+			route: node.catchAllChild.route,
+			params
+		};
+	}
+	if (node.optionalCatchAllChild !== null) {
+		const params = buildParams(entries);
+		params[node.optionalCatchAllChild.paramName] = urlParts.slice(index);
+		return {
+			route: node.optionalCatchAllChild.route,
+			params
+		};
+	}
+	return null;
+}
+function matchOptimisticRouteTrie(trie, urlParts) {
+	return matchNode(trie, urlParts, 0, []);
+}
+//#endregion
+export { buildOptimisticRouteTrie, matchOptimisticRouteTrie };

package/dist/routing/route-validation.d.ts

@@ -1,9 +1,14 @@
 //#region src/routing/route-validation.d.ts
 /**
- * Dynamic route validation adapted from Next.js' sorted-routes implementation.
+ * Dynamic route validation and sorting adapted from Next.js' sorted-routes implementation.
  * Source:
  * https://github.com/vercel/next.js/blob/canary/packages/next/src/shared/lib/router/utils/sorted-routes.ts
  */
+/**
+ * Sort Next.js-format page paths (e.g. "/posts/[id]") into route-priority
+ * order, matching Next.js' `getSortedRoutes`.
+ */
+export declare function getSortedRoutes(pages: readonly string[]): string[];
 export declare function patternToNextFormat(pattern: string): string;
 export declare function validateRoutePatterns(patterns: readonly string[]): void;
 //#endregion