@qzsy/vinext 0.1.7

package/dist/routing/route-pattern.js

@@ -0,0 +1,165 @@
+import { decodeMatchedParams } from "./utils.js";
+//#region src/routing/route-pattern.ts
+function routePatternPart(segment) {
+	if (segment.startsWith("[[...") && segment.endsWith("]]")) return `:${segment.slice(5, -2)}*`;
+	if (segment.startsWith("[...") && segment.endsWith("]")) return `:${segment.slice(4, -1)}+`;
+	if (segment.startsWith("[") && segment.endsWith("]")) return `:${segment.slice(1, -1)}`;
+	return segment;
+}
+function routePatternParts(pathname) {
+	return pathname.split("/").filter(Boolean).map(routePatternPart);
+}
+function routePattern(pathname) {
+	const parts = routePatternParts(pathname);
+	return parts.length > 0 ? `/${parts.join("/")}` : "";
+}
+function appendParamValue(target, value) {
+	if (Array.isArray(value)) {
+		for (const entry of value) target.push(entry);
+		return;
+	}
+	target.push(value);
+}
+function fillRoutePatternSegments(pathname, params) {
+	const segments = pathname.split("/").filter(Boolean);
+	const resolvedSegments = [];
+	for (const segment of segments) {
+		if (segment.startsWith("[[...") && segment.endsWith("]]")) {
+			const value = params[segment.slice(5, -2)];
+			if (value !== void 0 && value !== "") {
+				if (Array.isArray(value) && value.length === 0) continue;
+				appendParamValue(resolvedSegments, value);
+			}
+			continue;
+		}
+		if (segment.startsWith("[...") && segment.endsWith("]")) {
+			const value = params[segment.slice(4, -1)];
+			if (value === void 0 || (Array.isArray(value) ? value.length === 0 : value === "")) return null;
+			appendParamValue(resolvedSegments, value);
+			continue;
+		}
+		if (segment.startsWith("[") && segment.endsWith("]")) {
+			const value = params[segment.slice(1, -1)];
+			if (typeof value === "string") {
+				resolvedSegments.push(value);
+				continue;
+			}
+			if (Array.isArray(value) && value.length > 0) {
+				if (value.length > 1) return null;
+				resolvedSegments.push(value[0]);
+				continue;
+			}
+			return null;
+		}
+		resolvedSegments.push(segment);
+	}
+	return resolvedSegments.length > 0 ? `/${resolvedSegments.join("/")}` : "/";
+}
+function matchRoutePattern(urlParts, patternParts) {
+	const params = Object.create(null);
+	function matchFrom(urlIndex, patternIndex) {
+		if (patternIndex === patternParts.length) return urlIndex === urlParts.length;
+		const patternPart = patternParts[patternIndex];
+		if (patternPart.startsWith(":") && (patternPart.endsWith("+") || patternPart.endsWith("*"))) {
+			const paramName = patternPart.slice(1, -1);
+			const minLength = patternPart.endsWith("+") ? 1 : 0;
+			for (let endIndex = urlIndex + minLength; endIndex <= urlParts.length; endIndex++) {
+				const value = urlParts.slice(urlIndex, endIndex);
+				if (value.length > 0) params[paramName] = value;
+				else delete params[paramName];
+				if (matchFrom(endIndex, patternIndex + 1)) return true;
+			}
+			delete params[paramName];
+			return false;
+		}
+		if (patternPart.startsWith(":")) {
+			if (urlIndex >= urlParts.length) return false;
+			const paramName = patternPart.slice(1);
+			params[paramName] = urlParts[urlIndex];
+			if (matchFrom(urlIndex + 1, patternIndex + 1)) return true;
+			delete params[paramName];
+			return false;
+		}
+		if (urlIndex >= urlParts.length || urlParts[urlIndex] !== patternPart) return false;
+		return matchFrom(urlIndex + 1, patternIndex + 1);
+	}
+	if (!matchFrom(0, 0)) return null;
+	decodeMatchedParams(params);
+	return params;
+}
+function matchRoutePatternPrefix(pathParts, patternParts) {
+	let pathIndex = 0;
+	for (let patternIndex = 0; patternIndex < patternParts.length; patternIndex++) {
+		const patternPart = patternParts[patternIndex];
+		const isTerminal = patternIndex === patternParts.length - 1;
+		if (patternPart.startsWith(":") && patternPart.endsWith("+")) return isTerminal && pathParts.length - pathIndex >= 1;
+		if (patternPart.startsWith(":") && patternPart.endsWith("*")) return isTerminal;
+		if (pathIndex >= pathParts.length) return false;
+		if (patternPart.startsWith(":")) {
+			pathIndex++;
+			continue;
+		}
+		if (pathParts[pathIndex] !== patternPart) return false;
+		pathIndex++;
+	}
+	return true;
+}
+function matchRoutePatternWithOptionalDynamicSegments(pathParts, patternParts) {
+	function matchFrom(pathIndex, patternIndex) {
+		if (patternIndex === patternParts.length) return pathIndex === pathParts.length;
+		const patternPart = patternParts[patternIndex];
+		if (patternPart.startsWith(":") && (patternPart.endsWith("+") || patternPart.endsWith("*"))) {
+			const minLength = patternPart.endsWith("+") ? 1 : 0;
+			for (let endIndex = pathIndex + minLength; endIndex <= pathParts.length; endIndex++) if (matchFrom(endIndex, patternIndex + 1)) return true;
+			return false;
+		}
+		if (patternPart.startsWith(":")) return matchFrom(pathIndex, patternIndex + 1) || pathIndex < pathParts.length && matchFrom(pathIndex + 1, patternIndex + 1);
+		if (pathIndex >= pathParts.length || pathParts[pathIndex] !== patternPart) return false;
+		return matchFrom(pathIndex + 1, patternIndex + 1);
+	}
+	return matchFrom(0, 0);
+}
+/**
+* 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.
+*/
+function normalizeStaticPathname(pathname) {
+	const noQuery = pathname.split("?")[0];
+	return noQuery === "/" ? "/" : noQuery.replace(/\/$/, "");
+}
+/**
+* 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.
+*/
+function normalizeStaticPathsEntry(entry, routePattern) {
+	if (entry === null || entry === void 0) return { error: `getStaticPaths returned a ${entry === null ? "null" : "undefined"} entry` };
+	if (typeof entry === "string") {
+		const matched = matchRoutePattern(normalizeStaticPathname(entry).split("/").filter(Boolean), routePattern.split("/").filter(Boolean));
+		if (!matched) return { error: `The provided path \`${entry}\` from getStaticPaths does not match the route pattern \`${routePattern}\`.` };
+		return { params: matched };
+	}
+	if (typeof entry !== "object") return { error: `getStaticPaths entry must be a string or an object, got ${typeof entry}` };
+	const { params } = entry;
+	if (params === void 0 || params === null) return { error: `getStaticPaths entry is missing the \`params\` key for pattern \`${routePattern}\`. Return either a string path or { params: { ... } }.` };
+	return { params };
+}
+//#endregion
+export { fillRoutePatternSegments, matchRoutePattern, matchRoutePatternPrefix, matchRoutePatternWithOptionalDynamicSegments, normalizeStaticPathname, normalizeStaticPathsEntry, routePattern, routePatternParts };

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

@@ -0,0 +1,67 @@
+//#region src/routing/route-trie.d.ts
+/**
+ * Trie (prefix tree) for O(depth) route matching.
+ *
+ * Replaces the O(n) linear scan over pre-sorted routes with a trie-based
+ * lookup. Priority is enforced by traversal order at each node:
+ *   1. Static child (exact segment match) — highest priority
+ *   2. Dynamic child (single-segment param) — medium
+ *   3. Catch-all (1+ remaining segments) — low
+ *   4. Optional catch-all (0+ remaining segments) — lowest
+ *
+ * Backtracking via recursive DFS ensures that dead-end static/dynamic
+ * branches fall through to catch-all alternatives.
+ */
+type TrieNode<R> = {
+  staticChildren: Map<string, TrieNode<R>>;
+  dynamicChild: {
+    paramName: string;
+    node: TrieNode<R>;
+  } | null;
+  catchAllChild: {
+    paramName: string;
+    route: R;
+  } | null;
+  optionalCatchAllChild: {
+    paramName: string;
+    route: R;
+  } | null;
+  route: R | null;
+};
+/**
+ * Build a trie from pre-sorted routes.
+ *
+ * Routes must have a `patternParts` property (string[] of URL segments).
+ * Pattern segment conventions:
+ *   - `:name`  — dynamic segment
+ *   - `:name+` — catch-all (1+ segments)
+ *   - `:name*` — optional catch-all (0+ segments)
+ *   - anything else — static segment
+ *
+ * First route to claim a terminal position wins (routes are pre-sorted
+ * by precedence, so insertion order preserves correct priority).
+ */
+declare function buildRouteTrie<R extends {
+  patternParts: string[];
+}>(routes: R[]): TrieNode<R>;
+/**
+ * Match a URL against the trie.
+ *
+ * Returns decoded param values — `decodeURIComponent` is applied to
+ * individual param entries so that `%2F` → `/`, `%23` → `#`, etc.
+ * Segment boundaries (the original `/` splits) are preserved by the
+ * upstream normalization layer; this step only decodes the captured
+ * param strings the caller sees.
+ *
+ * Mirrors Next.js route-matcher.ts:25-27.
+ *
+ * @param root - Trie root built by `buildRouteTrie`
+ * @param urlParts - Pre-split URL segments (no empty strings)
+ * @returns Match result with route and extracted params, or null
+ */
+declare function trieMatch<R>(root: TrieNode<R>, urlParts: string[]): {
+  route: R;
+  params: Record<string, string | string[]>;
+} | null;
+//#endregion
+export { TrieNode, buildRouteTrie, trieMatch };

package/dist/routing/route-trie.js

@@ -0,0 +1,143 @@
+import { buildParams, decodeMatchedParams } from "./utils.js";
+//#region src/routing/route-trie.ts
+function createNode() {
+	return {
+		staticChildren: /* @__PURE__ */ new Map(),
+		dynamicChild: null,
+		catchAllChild: null,
+		optionalCatchAllChild: null,
+		route: null
+	};
+}
+/**
+* Build a trie from pre-sorted routes.
+*
+* Routes must have a `patternParts` property (string[] of URL segments).
+* Pattern segment conventions:
+*   - `:name`  — dynamic segment
+*   - `:name+` — catch-all (1+ segments)
+*   - `:name*` — optional catch-all (0+ segments)
+*   - anything else — static segment
+*
+* First route to claim a terminal position wins (routes are pre-sorted
+* by precedence, so insertion order preserves correct priority).
+*/
+function buildRouteTrie(routes) {
+	const root = createNode();
+	for (const route of routes) {
+		const parts = route.patternParts;
+		if (parts.length === 0) {
+			if (root.route === null) root.route = route;
+			continue;
+		}
+		let node = root;
+		for (let i = 0; i < parts.length; i++) {
+			const part = parts[i];
+			if (part.endsWith("+") && part.startsWith(":")) {
+				if (i !== parts.length - 1) break;
+				const paramName = part.slice(1, -1);
+				if (node.catchAllChild === null) node.catchAllChild = {
+					paramName,
+					route
+				};
+				break;
+			}
+			if (part.endsWith("*") && part.startsWith(":")) {
+				if (i !== parts.length - 1) break;
+				const paramName = part.slice(1, -1);
+				if (node.optionalCatchAllChild === null) node.optionalCatchAllChild = {
+					paramName,
+					route
+				};
+				break;
+			}
+			if (part.startsWith(":")) {
+				const paramName = part.slice(1);
+				if (node.dynamicChild === null) node.dynamicChild = {
+					paramName,
+					node: createNode()
+				};
+				node = node.dynamicChild.node;
+				if (i === parts.length - 1) {
+					if (node.route === null) node.route = route;
+				}
+				continue;
+			}
+			let child = node.staticChildren.get(part);
+			if (!child) {
+				child = createNode();
+				node.staticChildren.set(part, child);
+			}
+			node = child;
+			if (i === parts.length - 1) {
+				if (node.route === null) node.route = route;
+			}
+		}
+	}
+	return root;
+}
+/**
+* Match a URL against the trie.
+*
+* Returns decoded param values — `decodeURIComponent` is applied to
+* individual param entries so that `%2F` → `/`, `%23` → `#`, etc.
+* Segment boundaries (the original `/` splits) are preserved by the
+* upstream normalization layer; this step only decodes the captured
+* param strings the caller sees.
+*
+* Mirrors Next.js route-matcher.ts:25-27.
+*
+* @param root - Trie root built by `buildRouteTrie`
+* @param urlParts - Pre-split URL segments (no empty strings)
+* @returns Match result with route and extracted params, or null
+*/
+function trieMatch(root, urlParts) {
+	const result = match(root, urlParts, 0, []);
+	if (result) decodeMatchedParams(result.params);
+	return result;
+}
+function match(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) {
+		const result = match(staticChild, urlParts, index + 1, entries);
+		if (result !== null) return result;
+	}
+	if (node.dynamicChild !== null) {
+		entries.push([node.dynamicChild.paramName, segment]);
+		const result = match(node.dynamicChild.node, urlParts, index + 1, entries);
+		if (result !== null) return result;
+		entries.pop();
+	}
+	if (node.catchAllChild !== null) {
+		const remaining = urlParts.slice(index);
+		const params = buildParams(entries);
+		params[node.catchAllChild.paramName] = remaining;
+		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;
+}
+//#endregion
+export { buildRouteTrie, trieMatch };

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

@@ -0,0 +1,10 @@
+//#region src/routing/route-validation.d.ts
+/**
+ * Dynamic route validation 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
+ */
+declare function patternToNextFormat(pattern: string): string;
+declare function validateRoutePatterns(patterns: readonly string[]): void;
+//#endregion
+export { patternToNextFormat, validateRoutePatterns };

package/dist/routing/route-validation.js

@@ -0,0 +1,101 @@
+import { removeTrailingSlash } from "../utils/base-path.js";
+//#region src/routing/route-validation.ts
+/**
+* Dynamic route validation 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
+*/
+var UrlNode = class UrlNode {
+	placeholder = true;
+	children = /* @__PURE__ */ new Map();
+	slugName = null;
+	restSlugName = null;
+	optionalRestSlugName = null;
+	insert(urlPath) {
+		this.insertSegments(urlPath.split("/").filter(Boolean), [], false);
+	}
+	insertSegments(urlPaths, slugNames, isCatchAll) {
+		if (urlPaths.length === 0) {
+			this.placeholder = false;
+			return;
+		}
+		if (isCatchAll) throw new Error("Catch-all must be the last part of the URL.");
+		let nextSegment = urlPaths[0];
+		if (nextSegment.startsWith("[") && nextSegment.endsWith("]")) {
+			let segmentName = nextSegment.slice(1, -1);
+			let isOptional = false;
+			if (segmentName.startsWith("[") && segmentName.endsWith("]")) {
+				segmentName = segmentName.slice(1, -1);
+				isOptional = true;
+			}
+			if (segmentName.startsWith("…")) throw new Error(`Detected a three-dot character ('…') at ('${segmentName}'). Did you mean ('...')?`);
+			if (segmentName.startsWith("...")) {
+				segmentName = segmentName.substring(3);
+				isCatchAll = true;
+			}
+			if (segmentName.startsWith("[") || segmentName.endsWith("]")) throw new Error(`Segment names may not start or end with extra brackets ('${segmentName}').`);
+			if (segmentName.startsWith(".")) throw new Error(`Segment names may not start with erroneous periods ('${segmentName}').`);
+			const handleSlug = (previousSlug, nextSlug) => {
+				if (previousSlug !== null && previousSlug !== nextSlug) throw new Error(`You cannot use different slug names for the same dynamic path ('${previousSlug}' !== '${nextSlug}').`);
+				for (const slug of slugNames) {
+					if (slug === nextSlug) throw new Error(`You cannot have the same slug name "${nextSlug}" repeat within a single dynamic path`);
+					if (slug.replace(/\W/g, "") === nextSegment.replace(/\W/g, "")) throw new Error(`You cannot have the slug names "${slug}" and "${nextSlug}" differ only by non-word symbols within a single dynamic path`);
+				}
+				slugNames.push(nextSlug);
+			};
+			if (isCatchAll) if (isOptional) {
+				if (this.restSlugName !== null) throw new Error(`You cannot use both an required and optional catch-all route at the same level ("[...${this.restSlugName}]" and "${urlPaths[0]}" ).`);
+				handleSlug(this.optionalRestSlugName, segmentName);
+				this.optionalRestSlugName = segmentName;
+				nextSegment = "[[...]]";
+			} else {
+				if (this.optionalRestSlugName !== null) throw new Error(`You cannot use both an optional and required catch-all route at the same level ("[[...${this.optionalRestSlugName}]]" and "${urlPaths[0]}").`);
+				handleSlug(this.restSlugName, segmentName);
+				this.restSlugName = segmentName;
+				nextSegment = "[...]";
+			}
+			else {
+				if (isOptional) throw new Error(`Optional route parameters are not yet supported ("${urlPaths[0]}").`);
+				handleSlug(this.slugName, segmentName);
+				this.slugName = segmentName;
+				nextSegment = "[]";
+			}
+		}
+		let child = this.children.get(nextSegment);
+		if (!child) {
+			child = new UrlNode();
+			this.children.set(nextSegment, child);
+		}
+		child.insertSegments(urlPaths.slice(1), slugNames, isCatchAll);
+	}
+	assertOptionalCatchAllSpecificity(prefix = "/") {
+		if (!this.placeholder && this.optionalRestSlugName !== null) {
+			const route = prefix === "/" ? "/" : prefix.slice(0, -1);
+			throw new Error(`You cannot define a route with the same specificity as a optional catch-all route ("${route}" and "${route}[[...${this.optionalRestSlugName}]]").`);
+		}
+		for (const [segment, child] of this.children) {
+			const nextPrefixSegment = segment === "[]" ? `[${this.slugName}]` : segment === "[...]" ? `[...${this.restSlugName}]` : segment === "[[...]]" ? `[[...${this.optionalRestSlugName}]]` : segment;
+			child.assertOptionalCatchAllSpecificity(`${prefix}${nextPrefixSegment}/`);
+		}
+	}
+};
+function patternToNextFormat(pattern) {
+	if (pattern === "/") return "/";
+	return pattern.replace(/:([^/]+?)\+(?=\/|$)/g, "[...$1]").replace(/:([^/]+?)\*(?=\/|$)/g, "[[...$1]]").replace(/:([^/]+?)(?=\/|$)/g, "[$1]");
+}
+function normalizeRoutePattern(pattern) {
+	return removeTrailingSlash(pattern);
+}
+function validateRoutePatterns(patterns) {
+	const root = new UrlNode();
+	const seenPatterns = /* @__PURE__ */ new Set();
+	for (const pattern of patterns) {
+		const normalizedPattern = normalizeRoutePattern(pattern);
+		if (seenPatterns.has(normalizedPattern)) throw new Error(`You cannot have two routes that resolve to the same path ("${normalizedPattern}").`);
+		seenPatterns.add(normalizedPattern);
+		root.insert(patternToNextFormat(normalizedPattern));
+	}
+	root.assertOptionalCatchAllSpecificity();
+}
+//#endregion
+export { patternToNextFormat, validateRoutePatterns };

package/dist/routing/utils.d.ts

@@ -0,0 +1,117 @@
+//#region src/routing/utils.d.ts
+/**
+ * Sort routes by precedence — lower score sorts first (higher priority), with a
+ * lexicographic tiebreaker on the pattern for determinism. Sorts in place and
+ * returns the same array (mirrors `Array.prototype.sort`).
+ *
+ * `routePrecedence` is a pure function of the pattern, so each pattern's score
+ * is computed exactly once up front (decorate-sort) instead of ~2·log n times
+ * by a comparator that re-parses on every comparison. The `localeCompare`
+ * tiebreaker already guarantees a total order, so the result is byte-identical
+ * to comparing precedence inline.
+ *
+ * Usage: sortRoutes(routes)
+ */
+declare function sortRoutes<T extends {
+  pattern: string;
+}>(routes: T[]): T[];
+/**
+ * Single source of truth for hybrid App/Pages route ownership.
+ *
+ * Mirrors Next.js's DefaultRouteMatcherManager ordering: Pages providers
+ * are registered before App providers, then merged dynamic matchers sort
+ * together. Returns the router that should own a request/navigation to
+ * a URL that matched BOTH routers.
+ *
+ * Centralised so the server's request handling and the client's link /
+ * prefetch / programmatic-navigation paths all reach the same owner for
+ * the same (pages pattern, app pattern) pair. This intentionally implements
+ * Next.js's segment-tree ordering directly instead of vinext's broader
+ * `sortRoutes()` score heuristic. It only arbitrates two routes that already
+ * matched the same URL; each router's own trie ordering remains unchanged.
+ *
+ * Usage:
+ *   compareHybridRoutePatterns("/:slug", true, "/:slug", true)  // → "pages"
+ *   compareHybridRoutePatterns("/_sites/:slug*", true, "/:slug*", true)  // → "pages"
+ *   compareHybridRoutePatterns("/:path+", true, "/dashboard", false)  // → "app"
+ *   compareHybridRoutePatterns("/", false, "/", false)  // → "app"
+ */
+declare function compareHybridRoutePatterns(pagesPattern: string, pagesIsDynamic: boolean, appPattern: string, appIsDynamic: boolean): "app" | "pages";
+/**
+ * Decode a filesystem or URL path segment while preserving encoded path delimiters.
+ * Mirrors Next.js segment-wise decoding so "%5F" becomes "_" but "%2F" stays "%2F".
+ */
+declare function decodeRouteSegment(segment: string): string;
+/**
+ * Normalize a pathname for route matching by decoding each segment independently.
+ * This prevents encoded slashes from turning into real path separators.
+ */
+declare function normalizePathnameForRouteMatch(pathname: string): string;
+declare function splitPathnameForRouteMatch(pathname: string): string[];
+/**
+ * Strict pathname normalization for live request handling.
+ * Throws on malformed percent-encoding so callers can return 400.
+ */
+declare function normalizePathnameForRouteMatchStrict(pathname: string): string;
+/**
+ * Build a params object from ordered entries, preserving insertion order.
+ *
+ * Used by trie matchers to reconstruct the params Record after collecting
+ * entries in declaration order via DFS backtracking. Object.create(null)
+ * avoids prototype pollution.
+ *
+ * @param entries - Ordered [paramName, value] tuples from forward traversal
+ */
+declare function buildParams(entries: Array<[string, string | string[]]>): Record<string, string | string[]>;
+/**
+ * Decode captured route params with `decodeURIComponent`, mirroring Next.js
+ * route-matcher.ts:25-27. Mutates the params object in place. Catch-all
+ * arrays are decoded element-wise. Malformed escapes are preserved (the
+ * strict normalization layer rejects them at the request boundary).
+ */
+declare function decodeMatchedParams(params: Record<string, string | string[]>): void;
+/**
+ * Check whether a path segment is invisible in the URL (route groups, parallel
+ * slots, "."). Single source of truth shared by the route graph (Node) and
+ * browser-side bfcache identity logic. Lives in this browser-safe utils module
+ * so importing it does not drag node:path/node:fs into the client bundle.
+ */
+declare function isInvisibleSegment(segment: string): boolean;
+/** Split a pathname into its non-empty segments without decoding. */
+declare function splitPathSegments(pathname: string): string[];
+/**
+ * Catch-all filesystem segment, e.g. `[...slug]`. Browser-safe predicate shared
+ * with the route graph's segment parsing (dynamicParamNameFromSegment) so the
+ * bracket conventions live in one place. The length guard rejects empty names
+ * (`[...]`).
+ */
+declare function isCatchAllSegment(segment: string): boolean;
+/**
+ * Optional-catch-all filesystem segment, e.g. `[[...slug]]`. Unlike a catch-all,
+ * this matches zero or more URL segments.
+ */
+declare function isOptionalCatchAllSegment(segment: string): boolean;
+/**
+ * Count how many pathname segments a tree path's *visible* segments consume,
+ * given the total number of pathname segments available.
+ *
+ * This is the minimal pure slice of the canonical filesystem-segment →
+ * URL-segment mapping in `app-route-graph.ts` (`convertSegmentsToRouteParts`),
+ * extracted here so browser-side bfcache identity logic can share it without
+ * importing the Node-bound route graph module. `convertSegmentsToRouteParts`
+ * remains the source of truth for how each segment kind maps to a URL part.
+ *
+ * Each ordinary visible segment (static or `[x]`) consumes exactly one pathname
+ * segment. A catch-all (`[...x]`) is terminal and consumes every remaining
+ * pathname segment. An optional-catch-all (`[[...x]]`) is also terminal but may
+ * match zero segments, so it consumes only the remaining pathname segments
+ * (which is zero once preceding segments have already consumed the pathname) —
+ * never more than are actually present.
+ *
+ * @param visibleTreePathSegments URL-visible tree-path segments (callers must
+ *   pre-filter invisible segments via `isInvisibleSegment`).
+ * @param pathnameSegmentCount Total number of pathname segments available.
+ */
+declare function countConsumedPathnameSegments(visibleTreePathSegments: readonly string[], pathnameSegmentCount: number): number;
+//#endregion
+export { buildParams, compareHybridRoutePatterns, countConsumedPathnameSegments, decodeMatchedParams, decodeRouteSegment, isCatchAllSegment, isInvisibleSegment, isOptionalCatchAllSegment, normalizePathnameForRouteMatch, normalizePathnameForRouteMatchStrict, sortRoutes, splitPathSegments, splitPathnameForRouteMatch };