@qzsy/vinext 0.1.7

package/dist/routing/app-router.d.ts

@@ -0,0 +1,30 @@
+import { ValidFileMatcher } from "./file-matcher.js";
+import { AppRoute, AppRouteGraphRoute, RouteManifest, computeAppRouteStaticSiblings, computeRootParamNames, convertSegmentsToRouteParts } from "./app-route-graph.js";
+
+//#region src/routing/app-router.d.ts
+type AppRouteGraph = {
+  routes: AppRouteGraphRoute[];
+  routeManifest: RouteManifest;
+};
+declare function invalidateAppRouteCache(): void;
+/**
+ * Scan the app/ directory and return the route graph.
+ * TODO(#726): Layer 4 should consume this read model directly once the
+ * navigation planner owns route graph facts.
+ *
+ * @internal
+ */
+declare function appRouteGraph(appDir: string, pageExtensions?: readonly string[], matcher?: ValidFileMatcher): Promise<AppRouteGraph>;
+/**
+ * Scan the app/ directory and return a list of routes.
+ */
+declare function appRouter(appDir: string, pageExtensions?: readonly string[], matcher?: ValidFileMatcher): Promise<AppRouteGraphRoute[]>;
+/**
+ * Match a URL against App Router routes.
+ */
+declare function matchAppRoute(url: string, routes: AppRoute[]): {
+  route: AppRoute;
+  params: Record<string, string | string[]>;
+} | null;
+//#endregion
+export { type AppRoute, appRouteGraph, appRouter, computeAppRouteStaticSiblings, computeRootParamNames, convertSegmentsToRouteParts, invalidateAppRouteCache, matchAppRoute };

package/dist/routing/app-router.js

@@ -0,0 +1,59 @@
+import { createValidFileMatcher } from "./file-matcher.js";
+import { createRouteTrieCache, matchRouteWithTrie } from "./route-matching.js";
+import { buildAppRouteGraph, computeAppRouteStaticSiblings, computeRootParamNames, convertSegmentsToRouteParts } from "./app-route-graph.js";
+//#region src/routing/app-router.ts
+/**
+* App Router file-system routing.
+*
+* Scans the app/ directory following Next.js App Router conventions:
+* - app/page.tsx -> /
+* - app/about/page.tsx -> /about
+* - app/blog/[slug]/page.tsx -> /blog/:slug
+* - app/[...catchAll]/page.tsx -> /:catchAll+
+* - app/route.ts -> / (API route)
+* - app/(group)/page.tsx -> / (route groups are transparent)
+* - Layouts: app/layout.tsx wraps all children
+* - Loading: app/loading.tsx -> Suspense fallback
+* - Error: app/error.tsx -> ErrorBoundary
+* - Not Found: app/not-found.tsx
+*/
+let cachedGraph = null;
+let cachedAppDir = null;
+let cachedPageExtensionsKey = null;
+function invalidateAppRouteCache() {
+	cachedGraph = null;
+	cachedAppDir = null;
+	cachedPageExtensionsKey = null;
+}
+/**
+* Scan the app/ directory and return the route graph.
+* TODO(#726): Layer 4 should consume this read model directly once the
+* navigation planner owns route graph facts.
+*
+* @internal
+*/
+async function appRouteGraph(appDir, pageExtensions, matcher) {
+	matcher ??= createValidFileMatcher(pageExtensions);
+	const pageExtensionsKey = JSON.stringify(matcher.extensions);
+	if (cachedGraph && cachedAppDir === appDir && cachedPageExtensionsKey === pageExtensionsKey) return cachedGraph;
+	const graph = await buildAppRouteGraph(appDir, matcher);
+	cachedGraph = graph;
+	cachedAppDir = appDir;
+	cachedPageExtensionsKey = pageExtensionsKey;
+	return graph;
+}
+/**
+* Scan the app/ directory and return a list of routes.
+*/
+async function appRouter(appDir, pageExtensions, matcher) {
+	return (await appRouteGraph(appDir, pageExtensions, matcher)).routes;
+}
+const appTrieCache = createRouteTrieCache();
+/**
+* Match a URL against App Router routes.
+*/
+function matchAppRoute(url, routes) {
+	return matchRouteWithTrie(url, routes, appTrieCache);
+}
+//#endregion
+export { appRouteGraph, appRouter, computeAppRouteStaticSiblings, computeRootParamNames, convertSegmentsToRouteParts, invalidateAppRouteCache, matchAppRoute };

package/dist/routing/file-matcher.d.ts

@@ -0,0 +1,60 @@
+//#region src/routing/file-matcher.d.ts
+declare function normalizePageExtensions(pageExtensions?: readonly string[] | null): string[];
+type ValidFileMatcher = {
+  extensions: string[];
+  dottedExtensions: string[];
+  extensionRegex: RegExp;
+  isPageFile(filePath: string): boolean;
+  isAppRouterPage(filePath: string): boolean;
+  isAppRouterRoute(filePath: string): boolean;
+  isAppLayoutFile(filePath: string): boolean;
+  isAppDefaultFile(filePath: string): boolean;
+  stripExtension(filePath: string): string;
+};
+/**
+ * Ported in spirit from Next.js createValidFileMatcher:
+ * packages/next/src/server/lib/find-page-file.ts
+ */
+declare function createValidFileMatcher(pageExtensions?: readonly string[] | null): ValidFileMatcher;
+/** Check if a file exists with any configured page extension. */
+declare function findFileWithExtensions(basePath: string, matcher: ValidFileMatcher): boolean;
+/**
+ * Find a file by basename and configured page extension in a directory.
+ * Returns the first matching absolute path, or null if not found.
+ */
+declare function findFileWithExts(dir: string, name: string, matcher: ValidFileMatcher): string | null;
+/**
+ * Vite's default `resolve.extensions` covers `.tsx/.ts/.jsx/.js/.json` (and
+ * `.mjs/.mts`). When the user configures `pageExtensions` with values Vite
+ * does not know about — e.g. `["platform.tsx", "tsx", "mdx"]` from the
+ * Next.js `resolve-extensions` fixture — extensionless imports of those
+ * files fail to resolve, and the build crashes with "Custom deploy script
+ * failed: undefined (1)".
+ *
+ * Build the merged extension list that Vite should use:
+ *
+ *  1. User-configured pageExtensions go first (each prefixed with `.`) so
+ *     the user's priority wins. e.g. `.platform.tsx` resolves before `.tsx`.
+ *  2. Vite's defaults follow, with duplicates removed.
+ *
+ * The user's pageExtensions retain their relative order, which is what
+ * Next.js / Turbopack do via the `resolveExtensions` config option.
+ *
+ * See: cloudflare/vinext#1502
+ */
+declare function buildViteResolveExtensions(pageExtensions?: readonly string[] | null, viteDefaults?: readonly string[]): string[];
+/**
+ * Normalize an explicit Next.js resolver extension list for Vite.
+ *
+ * Unlike `pageExtensions`, both Turbopack's `resolveExtensions` and webpack's
+ * `resolve.extensions` replace their resolver defaults. The empty string is a
+ * webpack/Turbopack convention for trying the import exactly as written; Vite
+ * already does that before appending extensions, so it must be omitted here.
+ */
+declare function normalizeViteResolveExtensions(extensions: readonly string[]): string[];
+/**
+ * Use function-form exclude for Node < 22.14 compatibility.
+ */
+declare function scanWithExtensions(stem: string, cwd: string, extensions: readonly string[], exclude?: (name: string) => boolean): AsyncGenerator<string>;
+//#endregion
+export { ValidFileMatcher, buildViteResolveExtensions, createValidFileMatcher, findFileWithExtensions, findFileWithExts, normalizePageExtensions, normalizeViteResolveExtensions, scanWithExtensions };

package/dist/routing/file-matcher.js

@@ -0,0 +1,147 @@
+import { escapeRegExp } from "../utils/regex.js";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { glob } from "node:fs/promises";
+//#region src/routing/file-matcher.ts
+const DEFAULT_PAGE_EXTENSIONS = [
+	"tsx",
+	"ts",
+	"jsx",
+	"js"
+];
+function normalizePageExtensions(pageExtensions) {
+	if (!Array.isArray(pageExtensions) || pageExtensions.length === 0) return [...DEFAULT_PAGE_EXTENSIONS];
+	const filtered = pageExtensions.filter((ext) => typeof ext === "string").map((ext) => ext.trim().replace(/^\.+/, "")).filter((ext) => ext.length > 0);
+	return filtered.length > 0 ? [...filtered] : [...DEFAULT_PAGE_EXTENSIONS];
+}
+function buildExtensionGlob(stem, extensions) {
+	if (extensions.length === 1) return `${stem}.${extensions[0]}`;
+	return `${stem}.{${extensions.join(",")}}`;
+}
+/**
+* Ported in spirit from Next.js createValidFileMatcher:
+* packages/next/src/server/lib/find-page-file.ts
+*/
+function createValidFileMatcher(pageExtensions) {
+	const extensions = normalizePageExtensions(pageExtensions);
+	const dottedExtensions = extensions.map((ext) => `.${ext}`);
+	const extPattern = `(?:${extensions.map((ext) => escapeRegExp(ext)).join("|")})`;
+	const extensionRegex = new RegExp(`\\.${extPattern}$`);
+	const createLeafPattern = (fileNames) => {
+		const names = fileNames.length === 1 ? fileNames[0] : `(${fileNames.join("|")})`;
+		return new RegExp(`(^${names}|[\\\\/]${names})\\.${extPattern}$`);
+	};
+	const appRouterPageRegex = createLeafPattern(["page", "route"]);
+	const appRouterRouteRegex = createLeafPattern(["route"]);
+	const appLayoutRegex = createLeafPattern(["layout"]);
+	const appDefaultRegex = createLeafPattern(["default"]);
+	return {
+		extensions,
+		dottedExtensions,
+		extensionRegex,
+		isPageFile(filePath) {
+			return extensionRegex.test(filePath);
+		},
+		isAppRouterPage(filePath) {
+			return appRouterPageRegex.test(filePath);
+		},
+		isAppRouterRoute(filePath) {
+			return appRouterRouteRegex.test(filePath);
+		},
+		isAppLayoutFile(filePath) {
+			return appLayoutRegex.test(filePath);
+		},
+		isAppDefaultFile(filePath) {
+			return appDefaultRegex.test(filePath);
+		},
+		stripExtension(filePath) {
+			return filePath.replace(extensionRegex, "");
+		}
+	};
+}
+/** Check if a file exists with any configured page extension. */
+function findFileWithExtensions(basePath, matcher) {
+	return matcher.dottedExtensions.some((ext) => existsSync(basePath + ext));
+}
+/**
+* Find a file by basename and configured page extension in a directory.
+* Returns the first matching absolute path, or null if not found.
+*/
+function findFileWithExts(dir, name, matcher) {
+	for (const ext of matcher.dottedExtensions) {
+		const filePath = path.posix.join(dir, name + ext);
+		if (existsSync(filePath)) return filePath;
+	}
+	return null;
+}
+/**
+* Vite's default `resolve.extensions` covers `.tsx/.ts/.jsx/.js/.json` (and
+* `.mjs/.mts`). When the user configures `pageExtensions` with values Vite
+* does not know about — e.g. `["platform.tsx", "tsx", "mdx"]` from the
+* Next.js `resolve-extensions` fixture — extensionless imports of those
+* files fail to resolve, and the build crashes with "Custom deploy script
+* failed: undefined (1)".
+*
+* Build the merged extension list that Vite should use:
+*
+*  1. User-configured pageExtensions go first (each prefixed with `.`) so
+*     the user's priority wins. e.g. `.platform.tsx` resolves before `.tsx`.
+*  2. Vite's defaults follow, with duplicates removed.
+*
+* The user's pageExtensions retain their relative order, which is what
+* Next.js / Turbopack do via the `resolveExtensions` config option.
+*
+* See: cloudflare/vinext#1502
+*/
+function buildViteResolveExtensions(pageExtensions, viteDefaults = [
+	".mjs",
+	".js",
+	".mts",
+	".ts",
+	".jsx",
+	".tsx",
+	".json"
+]) {
+	const dotted = normalizePageExtensions(pageExtensions).map((ext) => `.${ext}`);
+	const seen = /* @__PURE__ */ new Set();
+	const result = [];
+	for (const ext of [...dotted, ...viteDefaults]) {
+		if (seen.has(ext)) continue;
+		seen.add(ext);
+		result.push(ext);
+	}
+	return result;
+}
+/**
+* Normalize an explicit Next.js resolver extension list for Vite.
+*
+* Unlike `pageExtensions`, both Turbopack's `resolveExtensions` and webpack's
+* `resolve.extensions` replace their resolver defaults. The empty string is a
+* webpack/Turbopack convention for trying the import exactly as written; Vite
+* already does that before appending extensions, so it must be omitted here.
+*/
+function normalizeViteResolveExtensions(extensions) {
+	const seen = /* @__PURE__ */ new Set();
+	const result = [];
+	for (const extension of extensions) {
+		const trimmed = extension.trim();
+		if (!trimmed) continue;
+		const dotted = trimmed.startsWith(".") ? trimmed : `.${trimmed}`;
+		if (seen.has(dotted)) continue;
+		seen.add(dotted);
+		result.push(dotted);
+	}
+	return result;
+}
+/**
+* Use function-form exclude for Node < 22.14 compatibility.
+*/
+async function* scanWithExtensions(stem, cwd, extensions, exclude) {
+	const pattern = buildExtensionGlob(stem, extensions);
+	for await (const file of glob(pattern, {
+		cwd,
+		...exclude ? { exclude } : {}
+	})) yield file;
+}
+//#endregion
+export { buildViteResolveExtensions, createValidFileMatcher, findFileWithExtensions, findFileWithExts, normalizePageExtensions, normalizeViteResolveExtensions, scanWithExtensions };

package/dist/routing/pages-router.d.ts

@@ -0,0 +1,48 @@
+import { ValidFileMatcher } from "./file-matcher.js";
+import { patternToNextFormat } from "./route-validation.js";
+
+//#region src/routing/pages-router.d.ts
+type Route = {
+  /** URL pattern, e.g. "/" or "/about" or "/posts/:id" */pattern: string; /** Pre-split pattern segments (computed once at scan time, reused per request) */
+  patternParts: string[]; /** Absolute file path to the page component */
+  filePath: string; /** Whether this is a dynamic route */
+  isDynamic: boolean; /** Parameter names for dynamic segments */
+  params: string[];
+};
+/**
+ * Invalidate cached routes for a given pages directory.
+ * Called by the file watcher when pages are added/removed.
+ */
+declare function invalidateRouteCache(pagesDir: string): void;
+/**
+ * Scan the pages/ directory and return a list of routes.
+ * Results are cached — call invalidateRouteCache() when files change.
+ *
+ * Follows Next.js Pages Router conventions:
+ * - pages/index.tsx -> /
+ * - pages/about.tsx -> /about
+ * - pages/posts/[id].tsx -> /posts/:id
+ * - pages/[...slug].tsx -> /:slug+
+ * - Ignores _app.tsx, _document.tsx, _error.tsx (Next.js special files)
+ * - Ignores pages/api/ (handled separately later)
+ */
+declare function pagesRouter(pagesDir: string, pageExtensions?: readonly string[], matcher?: ValidFileMatcher): Promise<Route[]>;
+/**
+ * Match a URL path against a route pattern.
+ * Returns the matched params or null if no match.
+ */
+declare function matchRoute(url: string, routes: Route[]): {
+  route: Route;
+  params: Record<string, string | string[]>;
+} | null;
+/**
+ * Scan the pages/api/ directory and return API routes.
+ * Results are cached — call invalidateRouteCache() when files change.
+ *
+ * Follows Next.js conventions:
+ * - pages/api/hello.ts -> /api/hello
+ * - pages/api/users/[id].ts -> /api/users/:id
+ */
+declare function apiRouter(pagesDir: string, pageExtensions?: readonly string[], matcher?: ValidFileMatcher): Promise<Route[]>;
+//#endregion
+export { Route, apiRouter, invalidateRouteCache, matchRoute, pagesRouter, patternToNextFormat };

package/dist/routing/pages-router.js

@@ -0,0 +1,163 @@
+import { decodeRouteSegment, sortRoutes } from "./utils.js";
+import { createValidFileMatcher, scanWithExtensions } from "./file-matcher.js";
+import { patternToNextFormat, validateRoutePatterns } from "./route-validation.js";
+import { createRouteTrieCache, matchRouteWithTrie } from "./route-matching.js";
+import path from "node:path";
+//#region src/routing/pages-router.ts
+/** Next.js special pages that should not produce routes. */
+const RESERVED_PAGE_NAMES = new Set([
+	"_app",
+	"_document",
+	"_error"
+]);
+const routeCache = /* @__PURE__ */ new Map();
+/**
+* Invalidate cached routes for a given pages directory.
+* Called by the file watcher when pages are added/removed.
+*/
+function invalidateRouteCache(pagesDir) {
+	for (const key of routeCache.keys()) if (key.startsWith(`pages:${pagesDir}:`) || key.startsWith(`api:${pagesDir}:`)) routeCache.delete(key);
+}
+/**
+* Scan the pages/ directory and return a list of routes.
+* Results are cached — call invalidateRouteCache() when files change.
+*
+* Follows Next.js Pages Router conventions:
+* - pages/index.tsx -> /
+* - pages/about.tsx -> /about
+* - pages/posts/[id].tsx -> /posts/:id
+* - pages/[...slug].tsx -> /:slug+
+* - Ignores _app.tsx, _document.tsx, _error.tsx (Next.js special files)
+* - Ignores pages/api/ (handled separately later)
+*/
+async function pagesRouter(pagesDir, pageExtensions, matcher) {
+	matcher ??= createValidFileMatcher(pageExtensions);
+	const cacheKey = `pages:${pagesDir}:${JSON.stringify(matcher.extensions)}`;
+	const cached = routeCache.get(cacheKey);
+	if (cached) return cached.promise;
+	const promise = scanPageRoutes(pagesDir, matcher);
+	routeCache.set(cacheKey, {
+		routes: [],
+		promise
+	});
+	const routes = await promise;
+	routeCache.set(cacheKey, {
+		routes,
+		promise
+	});
+	return routes;
+}
+async function scanPageRoutes(pagesDir, matcher) {
+	const routes = [];
+	for await (const file of scanWithExtensions("**/*", pagesDir, matcher.extensions, (name) => name === "api" || RESERVED_PAGE_NAMES.has(name))) {
+		const route = fileToRoute(file, pagesDir, matcher);
+		if (route) routes.push(route);
+	}
+	validateRoutePatterns(routes.map((route) => route.pattern));
+	sortRoutes(routes);
+	return routes;
+}
+/**
+* Convert a file path relative to pages/ into a Route.
+*/
+function fileToRoute(file, pagesDir, matcher) {
+	const withoutExt = matcher.stripExtension(file);
+	if (withoutExt === file) return null;
+	const segments = withoutExt.split(path.sep);
+	if (segments[segments.length - 1] === "index") segments.pop();
+	const params = [];
+	let isDynamic = false;
+	const urlSegments = [];
+	for (let i = 0; i < segments.length; i++) {
+		const segment = segments[i];
+		const catchAllMatch = segment.match(/^\[\.\.\.([^\]]+)\]$/);
+		if (catchAllMatch) {
+			if (i !== segments.length - 1) return null;
+			if (catchAllMatch[1].endsWith("+") || catchAllMatch[1].endsWith("*")) return null;
+			isDynamic = true;
+			params.push(catchAllMatch[1]);
+			urlSegments.push(`:${catchAllMatch[1]}+`);
+			continue;
+		}
+		const optionalCatchAllMatch = segment.match(/^\[\[\.\.\.([^\]]+)\]\]$/);
+		if (optionalCatchAllMatch) {
+			if (i !== segments.length - 1) return null;
+			if (optionalCatchAllMatch[1].endsWith("+") || optionalCatchAllMatch[1].endsWith("*")) return null;
+			isDynamic = true;
+			params.push(optionalCatchAllMatch[1]);
+			urlSegments.push(`:${optionalCatchAllMatch[1]}*`);
+			continue;
+		}
+		const dynamicMatch = segment.match(/^\[([^\]]+)\]$/);
+		if (dynamicMatch) {
+			if (dynamicMatch[1].endsWith("+") || dynamicMatch[1].endsWith("*")) return null;
+			isDynamic = true;
+			params.push(dynamicMatch[1]);
+			urlSegments.push(`:${dynamicMatch[1]}`);
+			continue;
+		}
+		urlSegments.push(decodeRouteSegment(segment));
+	}
+	const pattern = "/" + urlSegments.join("/");
+	if (segments.length === 1 && RESERVED_PAGE_NAMES.has(segments[0])) return null;
+	return {
+		pattern: pattern === "/" ? "/" : pattern,
+		patternParts: urlSegments.filter(Boolean),
+		filePath: path.join(pagesDir, file),
+		isDynamic,
+		params
+	};
+}
+const trieCache = createRouteTrieCache();
+/**
+* Match a URL path against a route pattern.
+* Returns the matched params or null if no match.
+*/
+function matchRoute(url, routes) {
+	return matchRouteWithTrie(url, routes, trieCache);
+}
+/**
+* Scan the pages/api/ directory and return API routes.
+* Results are cached — call invalidateRouteCache() when files change.
+*
+* Follows Next.js conventions:
+* - pages/api/hello.ts -> /api/hello
+* - pages/api/users/[id].ts -> /api/users/:id
+*/
+async function apiRouter(pagesDir, pageExtensions, matcher) {
+	matcher ??= createValidFileMatcher(pageExtensions);
+	const cacheKey = `api:${pagesDir}:${JSON.stringify(matcher.extensions)}`;
+	const cached = routeCache.get(cacheKey);
+	if (cached) return cached.promise;
+	const promise = scanApiRoutes(pagesDir, matcher);
+	routeCache.set(cacheKey, {
+		routes: [],
+		promise
+	});
+	const routes = await promise;
+	routeCache.set(cacheKey, {
+		routes,
+		promise
+	});
+	return routes;
+}
+async function scanApiRoutes(pagesDir, matcher) {
+	const apiDir = path.join(pagesDir, "api");
+	let files;
+	try {
+		files = [];
+		for await (const file of scanWithExtensions("**/*", apiDir, matcher.extensions)) files.push(file);
+	} catch {
+		files = [];
+	}
+	const routes = [];
+	for (const file of files) {
+		const route = fileToRoute(path.join("api", file), pagesDir, matcher);
+		if (route) routes.push(route);
+	}
+	validateRoutePatterns(routes.map((route) => route.pattern));
+	sortRoutes(routes);
+	return routes;
+}
+//#endregion
+export { apiRouter, invalidateRouteCache, matchRoute, pagesRouter, patternToNextFormat };

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

@@ -0,0 +1,27 @@
+import { TrieNode } from "./route-trie.js";
+
+//#region src/routing/route-matching.d.ts
+type RouteTrieCache<R extends {
+  patternParts: string[];
+}> = WeakMap<R[], TrieNode<R>>;
+declare function createRouteTrieCache<R extends {
+  patternParts: string[];
+}>(): RouteTrieCache<R>;
+/**
+ * Match a URL path against a list of routes via the shared preamble:
+ *   1. strip query string
+ *   2. trailing-slash normalize (preserving root "/")
+ *   3. run `normalizePathnameForRouteMatch`
+ *   4. split into url parts and look up via the (cached) trie
+ *
+ * Generic over the route shape; both Pages `Route` and App `AppRoute`
+ * satisfy `{ patternParts: string[] }`.
+ */
+declare function matchRouteWithTrie<R extends {
+  patternParts: string[];
+}>(url: string, routes: R[], cache: RouteTrieCache<R>): {
+  route: R;
+  params: Record<string, string | string[]>;
+} | null;
+//#endregion
+export { createRouteTrieCache, matchRouteWithTrie };

package/dist/routing/route-matching.js

@@ -0,0 +1,42 @@
+import { normalizePathnameForRouteMatch } from "./utils.js";
+import { buildRouteTrie, trieMatch } from "./route-trie.js";
+//#region src/routing/route-matching.ts
+/**
+* Shared route-match preamble used by both Pages Router and App Router.
+*
+* Both routers normalize URLs and call `trieMatch` with nearly-identical
+* preamble: strip query, trailing-slash normalize, run
+* `normalizePathnameForRouteMatch`, split into url parts, then look up via a
+* per-routes-array trie cache. This module factors that out so each router
+* just calls `matchRouteWithTrie(url, routes)`.
+*/
+function createRouteTrieCache() {
+	return /* @__PURE__ */ new WeakMap();
+}
+function getOrBuildTrie(cache, routes) {
+	let trie = cache.get(routes);
+	if (!trie) {
+		trie = buildRouteTrie(routes);
+		cache.set(routes, trie);
+	}
+	return trie;
+}
+/**
+* Match a URL path against a list of routes via the shared preamble:
+*   1. strip query string
+*   2. trailing-slash normalize (preserving root "/")
+*   3. run `normalizePathnameForRouteMatch`
+*   4. split into url parts and look up via the (cached) trie
+*
+* Generic over the route shape; both Pages `Route` and App `AppRoute`
+* satisfy `{ patternParts: string[] }`.
+*/
+function matchRouteWithTrie(url, routes, cache) {
+	const pathname = url.split("?")[0];
+	let normalizedUrl = pathname === "/" ? "/" : pathname.replace(/\/$/, "");
+	normalizedUrl = normalizePathnameForRouteMatch(normalizedUrl);
+	const urlParts = normalizedUrl.split("/").filter(Boolean);
+	return trieMatch(getOrBuildTrie(cache, routes), urlParts);
+}
+//#endregion
+export { createRouteTrieCache, matchRouteWithTrie };

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

@@ -0,0 +1,64 @@
+//#region src/routing/route-pattern.d.ts
+type RoutePatternParams = Record<string, string | string[]>;
+declare function routePatternParts(pathname: string): string[];
+declare function routePattern(pathname: string): string;
+declare function fillRoutePatternSegments(pathname: string, params: RoutePatternParams): string | null;
+declare function matchRoutePattern(urlParts: readonly string[], patternParts: readonly string[]): RoutePatternParams | null;
+declare function matchRoutePatternPrefix(pathParts: readonly string[], patternParts: readonly string[]): boolean;
+declare function matchRoutePatternWithOptionalDynamicSegments(pathParts: readonly string[], patternParts: readonly string[]): boolean;
+/**
+ * A single entry from `getStaticPaths().paths`.
+ *
+ * Next.js allows both shapes:
+ *   - a raw string path, e.g. `"/blog/hello"`
+ *   - an object `{ params, locale? }`
+ *
+ * See:
+ *   https://nextjs.org/docs/pages/api-reference/functions/get-static-paths
+ *   .nextjs-ref/packages/next/src/build/static-paths/pages.ts (the
+ *     `typeof entry === 'string'` branch around line 89, and the object
+ *     branch around line 132)
+ */
+type StaticPathsEntry = string | {
+  params?: RoutePatternParams;
+  locale?: string;
+} | null | undefined;
+/**
+ * Result of {@link normalizeStaticPathsEntry}: either a params object, or a
+ * descriptive error string the caller can surface as a per-route error result.
+ */
+type NormalizedStaticPathsEntry = {
+  params: RoutePatternParams;
+} | {
+  error: string;
+};
+/**
+ * Strip query string and a single trailing slash from a pathname.
+ *
+ * Mirrors the Next.js `removeTrailingSlash` helper used in
+ * `.nextjs-ref/packages/next/src/build/static-paths/pages.ts`. Kept here so
+ * both the build-time prerender and the request-time matchers normalize the
+ * same way.
+ */
+declare function normalizeStaticPathname(pathname: string): string;
+/**
+ * Normalize a single `getStaticPaths` entry into a `{ params }` object.
+ *
+ * Handles both Next.js-supported shapes:
+ *   - For a string entry, match it against `routePattern` to extract params,
+ *     mirroring `_routeMatcher(cleanedEntry)` in
+ *     `.nextjs-ref/packages/next/src/build/static-paths/pages.ts`. If the
+ *     string does not match the pattern, Next.js throws; we return an
+ *     `{ error }` result so the caller can record a per-route error instead
+ *     of crashing the build.
+ *   - For an object entry, require a `params` key (Next.js raises
+ *     "A required parameter (X) was not provided..." otherwise).
+ *
+ * Note: this intentionally does NOT strip a locale prefix. The build pipeline
+ * currently passes empty `locales` to `getStaticPaths`, so locale-prefixed
+ * string entries are not produced. If/when i18n is wired through prerender,
+ * locale handling should be added here, not duplicated at call sites.
+ */
+declare function normalizeStaticPathsEntry(entry: StaticPathsEntry, routePattern: string): NormalizedStaticPathsEntry;
+//#endregion
+export { RoutePatternParams, StaticPathsEntry, fillRoutePatternSegments, matchRoutePattern, matchRoutePatternPrefix, matchRoutePatternWithOptionalDynamicSegments, normalizeStaticPathname, normalizeStaticPathsEntry, routePattern, routePatternParts };