@timber-js/app 0.2.0-alpha.1 → 0.2.0-alpha.100

package/dist/_chunks/walkers-Tg0Alwcg.js

@@ -0,0 +1,850 @@
+import { r as DEFAULT_PAGE_EXTENSIONS, t as classifySegment } from "./segment-classify-BjfuctV2.js";
+import { a as isDynamicMetadataExtension, n as classifyMetadataRoute } from "./metadata-routes-BU684ls2.js";
+import { h as swallow } from "./logger-0m8MsKdc.js";
+import { basename, extname, join, posix, relative } from "node:path";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+//#region src/routing/scanner.ts
+/**
+* Route discovery scanner.
+*
+* Pure function: (appDir, config) → RouteTree
+*
+* Scans the app/ directory and builds a segment tree recognizing all
+* timber.js file conventions. Does NOT handle request matching — this
+* is discovery only.
+*/
+/**
+* Pattern matching encoded path delimiters that must be rejected during route discovery.
+* %2F / %2f (forward slash) and %5C / %5c (backslash) can cause route collisions
+* when decoded. See design/13-security.md §"Encoded separators rejected".
+*/
+var ENCODED_SEPARATOR_PATTERN = /%(?:2[fF]|5[cC])/;
+/**
+* Pattern matching encoded null bytes (%00) that must be rejected.
+* See design/13-security.md §"Null bytes rejected".
+*/
+var ENCODED_NULL_PATTERN = /%00/;
+/**
+* File convention names that use pageExtensions (can be .tsx, .ts, .jsx, .js, .mdx, etc.)
+*/
+var PAGE_EXT_CONVENTIONS = new Set([
+	"page",
+	"layout",
+	"error",
+	"default",
+	"denied"
+]);
+/**
+* Legacy compat status-code files.
+* Maps legacy file name → HTTP status code for the fallback chain.
+* See design/10-error-handling.md §"Fallback Chain".
+*/
+var LEGACY_STATUS_FILES = {
+	"not-found": 404,
+	"forbidden": 403,
+	"unauthorized": 401
+};
+/**
+* File convention names that are always .ts/.tsx (never .mdx etc.)
+*/
+var FIXED_CONVENTIONS = new Set([
+	"middleware",
+	"access",
+	"route",
+	"params"
+]);
+/**
+* Status-code file patterns:
+* - Exact 3-digit codes: 401.tsx, 429.tsx, 503.tsx
+* - Category catch-alls: 4xx.tsx, 5xx.tsx
+*/
+var STATUS_CODE_PATTERN = /^(\d{3}|[45]xx)$/;
+/**
+* Scan the app/ directory and build the route tree.
+*
+* @param appDir - Absolute path to the app/ directory
+* @param config - Scanner configuration
+* @returns The complete route tree
+*/
+function scanRoutes(appDir, config = {}) {
+	const pageExtensions = config.pageExtensions ?? DEFAULT_PAGE_EXTENSIONS;
+	const extSet = new Set(pageExtensions);
+	const tree = { root: createSegmentNode("", "static", "/") };
+	const proxyFile = findFixedFile(appDir, "proxy");
+	if (proxyFile) tree.proxy = proxyFile;
+	const globalErrorFile = findPageExtFile(appDir, "global-error", extSet);
+	if (globalErrorFile) tree.globalError = globalErrorFile;
+	scanSegmentFiles(appDir, tree.root, extSet);
+	scanChildren(appDir, tree.root, extSet);
+	validateRouteGroupCollisions(tree.root);
+	validateDuplicateParamNames(tree.root);
+	return tree;
+}
+/**
+* Create an empty segment node.
+*/
+function createSegmentNode(segmentName, segmentType, urlPath, paramName, interceptionMarker, interceptedSegmentName) {
+	return {
+		segmentName,
+		segmentType,
+		urlPath,
+		paramName,
+		interceptionMarker,
+		interceptedSegmentName,
+		children: [],
+		slots: {}
+	};
+}
+/**
+* Compute the URL path for a child segment given its parent's URL path.
+* Route groups, slots, and intercepting routes do NOT add URL depth.
+*/
+function computeUrlPath(parentUrlPath, dirName, segmentType) {
+	if (segmentType === "group" || segmentType === "slot" || segmentType === "intercepting") return parentUrlPath;
+	return `${parentUrlPath === "/" ? "" : parentUrlPath}/${dirName}`;
+}
+/**
+* Scan a directory for file conventions and populate the segment node.
+*/
+function scanSegmentFiles(dirPath, node, extSet) {
+	let entries;
+	try {
+		entries = readdirSync(dirPath);
+	} catch (err) {
+		swallow(err, `scanSegmentFiles: unreadable directory ${dirPath}`, { level: "warn" });
+		return;
+	}
+	for (const entry of entries) {
+		const fullPath = join(dirPath, entry);
+		try {
+			if (statSync(fullPath).isDirectory()) continue;
+		} catch {
+			continue;
+		}
+		const ext = extname(entry).slice(1);
+		const name = basename(entry, `.${ext}`);
+		if (PAGE_EXT_CONVENTIONS.has(name) && extSet.has(ext)) {
+			const file = {
+				filePath: fullPath,
+				extension: ext
+			};
+			switch (name) {
+				case "page":
+					node.page = file;
+					break;
+				case "layout":
+					node.layout = file;
+					break;
+				case "error":
+					node.error = file;
+					break;
+				case "default":
+					node.default = file;
+					break;
+				case "denied":
+					node.denied = file;
+					break;
+			}
+			continue;
+		}
+		if (FIXED_CONVENTIONS.has(name) && /\.?[jt]sx?$/.test(ext)) {
+			const file = {
+				filePath: fullPath,
+				extension: ext
+			};
+			switch (name) {
+				case "middleware":
+					node.middleware = file;
+					break;
+				case "access":
+					node.access = file;
+					break;
+				case "route":
+					node.route = file;
+					break;
+				case "params":
+					node.params = file;
+					break;
+			}
+			continue;
+		}
+		if (STATUS_CODE_PATTERN.test(name) && ext === "json") {
+			if (!node.jsonStatusFiles) node.jsonStatusFiles = {};
+			node.jsonStatusFiles[name] = {
+				filePath: fullPath,
+				extension: ext
+			};
+			continue;
+		}
+		if (STATUS_CODE_PATTERN.test(name) && extSet.has(ext)) {
+			if (!node.statusFiles) node.statusFiles = {};
+			node.statusFiles[name] = {
+				filePath: fullPath,
+				extension: ext
+			};
+			continue;
+		}
+		if (name in LEGACY_STATUS_FILES && extSet.has(ext)) {
+			if (!node.legacyStatusFiles) node.legacyStatusFiles = {};
+			node.legacyStatusFiles[name] = {
+				filePath: fullPath,
+				extension: ext
+			};
+			continue;
+		}
+		if (classifyMetadataRoute(entry)) {
+			if (!node.metadataRoutes) node.metadataRoutes = {};
+			const existing = node.metadataRoutes[name];
+			if (existing) {
+				const existingIsDynamic = isDynamicMetadataExtension(name, existing.extension);
+				if (isDynamicMetadataExtension(name, ext) || !existingIsDynamic) node.metadataRoutes[name] = {
+					filePath: fullPath,
+					extension: ext
+				};
+			} else node.metadataRoutes[name] = {
+				filePath: fullPath,
+				extension: ext
+			};
+		}
+	}
+	if (node.route && node.page) throw new Error(`Build error: route.ts and page.* cannot coexist in the same segment.\n  route.ts: ${node.route.filePath}\n  page:     ${node.page.filePath}\nA URL is either an API endpoint or a rendered page, not both.`);
+}
+/**
+* Recursively scan child directories and build the segment tree.
+*/
+function scanChildren(dirPath, parentNode, extSet) {
+	let entries;
+	try {
+		entries = readdirSync(dirPath);
+	} catch (err) {
+		swallow(err, `scanChildren: unreadable directory ${dirPath}`, { level: "warn" });
+		return;
+	}
+	for (const entry of entries) {
+		const fullPath = join(dirPath, entry);
+		try {
+			if (!statSync(fullPath).isDirectory()) continue;
+		} catch {
+			continue;
+		}
+		if (ENCODED_SEPARATOR_PATTERN.test(entry)) throw new Error(`Build error: directory name contains an encoded path delimiter (%%2F or %%5C).\n  Directory: ${fullPath}\nEncoded separators in directory names cause route collisions when decoded. Rename the directory to remove the encoded delimiter.`);
+		if (ENCODED_NULL_PATTERN.test(entry)) throw new Error(`Build error: directory name contains an encoded null byte (%%00).\n  Directory: ${fullPath}\nEncoded null bytes in directory names are not allowed. Rename the directory to remove the null byte encoding.`);
+		const { type, paramName, interceptionMarker, interceptedSegmentName } = classifySegment(entry);
+		if (type === "private") continue;
+		const childNode = createSegmentNode(entry, type, computeUrlPath(parentNode.urlPath, entry, type), paramName, interceptionMarker, interceptedSegmentName);
+		scanSegmentFiles(fullPath, childNode, extSet);
+		scanChildren(fullPath, childNode, extSet);
+		if (type === "slot") {
+			const slotName = entry.slice(1);
+			parentNode.slots[slotName] = childNode;
+		} else parentNode.children.push(childNode);
+	}
+}
+/**
+* Validate that route groups don't produce conflicting pages/routes at the same URL path.
+*
+* Two route groups like (auth)/login/page.tsx and (marketing)/login/page.tsx both claim
+* /login — the scanner must detect and reject this at build time.
+*
+* Parallel slots are excluded from collision detection — they intentionally coexist at
+* the same URL path as their parent (that's the whole point of parallel routes).
+*/
+function validateRouteGroupCollisions(root) {
+	collectRoutableLeaves(root, /* @__PURE__ */ new Map(), "", false);
+}
+/**
+* Walk the segment tree and collect all routable leaves (page or route files),
+* throwing on collision. Slots are tracked in their own collision space since
+* they are parallel routes that intentionally share URL paths with their parent.
+*/
+function collectRoutableLeaves(node, seen, segmentPath, insideSlot) {
+	const currentPath = segmentPath ? `${segmentPath}/${node.segmentName}` : node.segmentName || "(root)";
+	if (!insideSlot) {
+		const routableFile = node.page ?? node.route;
+		if (routableFile) {
+			const existing = seen.get(node.urlPath);
+			if (existing) throw new Error(`Build error: route collision — multiple route groups produce a page/route at the same URL path.\n  URL path: ${node.urlPath}\n  File 1:   ${existing.filePath} (via ${existing.segmentPath})\n  File 2:   ${routableFile.filePath} (via ${currentPath})\nEach URL path must map to exactly one page or route handler. Rename or move one of the conflicting files.`);
+			seen.set(node.urlPath, {
+				filePath: routableFile.filePath,
+				segmentPath: currentPath
+			});
+		}
+	}
+	for (const child of node.children) collectRoutableLeaves(child, seen, currentPath, insideSlot);
+	for (const slotNode of Object.values(node.slots)) collectRoutableLeaves(slotNode, seen, currentPath, true);
+}
+/**
+* Validate that no route chain contains duplicate dynamic param names.
+*
+* Example violation:
+*   app/[id]/items/[id]/page.tsx — 'id' appears twice in the ancestor chain.
+*
+* Route groups are transparent — params accumulate through them.
+* Slots are independent — duplicate detection does NOT cross slot boundaries.
+*
+* See design/07-routing.md §"Duplicate Param Name Detection"
+*/
+function validateDuplicateParamNames(root) {
+	walkForDuplicateParams(root, /* @__PURE__ */ new Map());
+}
+/**
+* Recursively walk the segment tree, tracking seen param names → segment paths.
+* Throws on the first duplicate found.
+*/
+function walkForDuplicateParams(node, seen) {
+	if (node.paramName) {
+		const existing = seen.get(node.paramName);
+		if (existing) throw new Error(`[timber] Duplicate param name '${node.paramName}' in route chain.\n  First defined at: ${existing}\n  Duplicate at: ${node.urlPath || "/"}\n  Rename one of the segments to avoid ambiguity.`);
+		seen = new Map(seen);
+		seen.set(node.paramName, node.urlPath || "/");
+	}
+	for (const child of node.children) walkForDuplicateParams(child, seen);
+	for (const slotNode of Object.values(node.slots)) walkForDuplicateParams(slotNode, new Map(seen));
+}
+/**
+* Find a fixed-extension file (proxy.ts) in a directory.
+*/
+function findFixedFile(dirPath, name) {
+	for (const ext of ["ts", "tsx"]) {
+		const fullPath = join(dirPath, `${name}.${ext}`);
+		try {
+			if (statSync(fullPath).isFile()) return {
+				filePath: fullPath,
+				extension: ext
+			};
+		} catch {}
+	}
+}
+/**
+* Find a file using the configured page extensions (tsx, ts, jsx, js, mdx, etc.).
+* Used for app-root conventions like global-error that aren't per-segment.
+*/
+function findPageExtFile(dirPath, name, extSet) {
+	for (const ext of extSet) {
+		const fullPath = join(dirPath, `${name}.${ext}`);
+		try {
+			if (statSync(fullPath).isFile()) return {
+				filePath: fullPath,
+				extension: ext
+			};
+		} catch {}
+	}
+}
+//#endregion
+//#region src/routing/codegen-shared.ts
+/**
+* Shared codegen helpers — import-path computation, codec chain type
+* builder, and searchParams type formatter.
+*
+* Extracted from `codegen.ts` so `link-codegen.ts` can use the same
+* helpers without a cyclic import.
+*/
+/**
+* Compute a relative import specifier for a codec/page file, stripping
+* the .ts/.tsx extension and resolving against the codegen output dir.
+*/
+function codecImportPath(codecFilePath, importBase) {
+	const absPath = codecFilePath.replace(/\.(ts|tsx)$/, "");
+	if (importBase) return "./" + relative(importBase, absPath).replace(/\\/g, "/");
+	return "./" + posix.basename(absPath);
+}
+/** Name of the shared helper type emitted at the top of the .d.ts. */
+var RESOLVE_SEGMENT_FIELD_TYPE_NAME = "_TimberResolveSegmentField";
+/**
+* Helper type emitted once at the top of the generated `.d.ts` and
+* referenced by every codec-chain conditional. Without this shared
+* helper, the inline expansion would duplicate the fallback branch on
+* every step and grow O(2^N) in chain depth (a single deep nested route
+* could blow up the file size and TS performance). With the helper,
+* each step reuses the named type and growth is O(N).
+*
+* The helper is a 2-arg conditional: given a typeof import expression
+* (`Def`), a key (`K`), and a fallback (`F`), it returns `T[K]` if
+* `Def extends ParamsDefinition<T>` and `K extends keyof T`, otherwise
+* `F`. The codec chain composes calls to this helper.
+*/
+function emitResolveSegmentFieldHelper() {
+	return [
+		`type ${RESOLVE_SEGMENT_FIELD_TYPE_NAME}<Def, K extends string, F> =`,
+		`  Def extends import('@timber-js/app/segment-params').ParamsDefinition<infer T>`,
+		`    ? K extends keyof T ? T[K] : F`,
+		`    : F;`
+	].join("\n");
+}
+/**
+* Build a TypeScript type expression that resolves a single param's
+* codec by walking a chain of params.ts files in priority order.
+*
+* Each entry in the chain emits one application of the shared
+* `_TimberResolveSegmentField` helper type. Composing N applications
+* grows linearly with chain depth (O(N) characters), unlike an inline
+* conditional that would duplicate the fallback in each branch and
+* grow O(2^N).
+*
+* The closest match (position 0 in the chain) is checked first; if its
+* `segmentParams` definition declares the key, its inferred type wins.
+* Otherwise we fall through to the next entry, and finally to the
+* provided fallback. See TIM-834.
+*/
+function buildCodecChainType(p, importBase, fallback) {
+	const files = p.codecFilePaths;
+	if (!files || files.length === 0) return fallback;
+	const key = JSON.stringify(p.name);
+	let inner = fallback;
+	for (let i = files.length - 1; i >= 0; i--) inner = `${RESOLVE_SEGMENT_FIELD_TYPE_NAME}<(typeof import('${codecImportPath(files[i], importBase)}'))['segmentParams'], ${key}, ${inner}>`;
+	return inner;
+}
+/**
+* Format the searchParams type for a route entry.
+*
+* When a page.tsx (or params.ts) exports searchParams, we reference its
+* inferred type via an import type. The import path is relative to
+* `importBase` (the directory where the .d.ts will be written). When
+* importBase is undefined, falls back to a bare relative path.
+*/
+function formatSearchParamsType(route, importBase) {
+	if (route.hasSearchParams && route.searchParamsPagePath) return `(typeof import('${codecImportPath(route.searchParamsPagePath, importBase)}'))['searchParams'] extends import('@timber-js/app/search-params').SearchParamsDefinition<infer T> ? T : never`;
+	return "{}";
+}
+//#endregion
+//#region src/routing/link-codegen.ts
+/** Shared Link base-props type literal used in every emitted call signature. */
+var LINK_BASE_PROPS_TYPE = "Omit<import('react').AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> & { prefetch?: boolean; scroll?: boolean; preserveSearchParams?: true | string[]; onNavigate?: import('./client/link.js').OnNavigateHandler; children?: import('react').ReactNode }";
+/**
+* Build a TypeScript template literal pattern for a dynamic route.
+* e.g. '/products/[id]'        → '/products/${string}'
+*      '/blog/[...slug]'       → '/blog/${string}'
+*      '/docs/[[...path]]'     → '/docs/${string}' (also matches /docs)
+*      '/[org]/[repo]'         → '/${string}/${string}'
+*/
+function buildResolvedPattern(route) {
+	return route.urlPath.split("/").map((part) => {
+		if (part.startsWith("[[...") && part.endsWith("]]")) return "${string}";
+		if (part.startsWith("[...") && part.endsWith("]")) return "${string}";
+		if (part.startsWith("[") && part.endsWith("]")) return "${string}";
+		return part;
+	}).join("/");
+}
+/**
+* Format the segmentParams type for Link overloads.
+*
+* Link params accept `string | number` for single dynamic segments
+* (convenience — values are stringified at runtime). Catch-all and
+* optional catch-all remain `string[]` / `string[] | undefined`.
+*
+* When the segment's params chain (TIM-834) declares a typed codec, the
+* inferred type from the codec wins via a nested conditional.
+*/
+function formatLinkParamsType(params, importBase) {
+	if (params.length === 0) return "{}";
+	return `{ ${params.map((p) => {
+		const codecType = buildCodecChainType(p, importBase, p.type === "string" ? "string | number" : p.type);
+		return `${p.name}: ${codecType}`;
+	}).join("; ")} }`;
+}
+/**
+* Catch-all call signatures for `<Link>` — external hrefs and computed
+* `string` variables. Emitted from codegen in a SEPARATE
+* `declare module` block (declared AFTER the per-route block) so the TS
+* "later overload set ordered first" rule places these catch-all
+* signatures ahead of per-route in resolution order, leaving per-route
+* as the final overload whose error message is reported on failure.
+*
+* The conditional `string extends H ? ... : never` protection preserves
+* TIM-624's guarantee that unknown internal path literals don't match
+* the catch-all — typos like `<Link href="/typo" />` still error.
+*/
+function formatLinkCatchAllOverloads() {
+	const lines = [];
+	const baseProps = LINK_BASE_PROPS_TYPE;
+	const catchAllSearchParams = "{ definition: SearchParamsDefinition<Record<string, unknown>>; values: Record<string, unknown> } | Record<string, unknown>";
+	const externalHref = "`http://${string}` | `https://${string}` | `mailto:${string}` | `tel:${string}` | `ftp://${string}` | `//${string}` | `#${string}` | `?${string}`";
+	lines.push("  // Typed Link overloads — catch-all (block 2 / emitted second)");
+	lines.push("  interface LinkFunction {");
+	lines.push(`    (props: ${baseProps} & {`);
+	lines.push(`      href: ${externalHref}`);
+	lines.push(`      segmentParams?: Record<string, unknown>`);
+	lines.push(`      searchParams?: ${catchAllSearchParams}`);
+	lines.push(`    }): import('react').JSX.Element`);
+	lines.push(`    <H extends string>(`);
+	lines.push(`      props: ${baseProps} & {`);
+	lines.push(`        href: string extends H ? H : never`);
+	lines.push(`        segmentParams?: Record<string, string | number | string[]>`);
+	lines.push(`        searchParams?: ${catchAllSearchParams}`);
+	lines.push(`      }`);
+	lines.push(`    ): import('react').JSX.Element`);
+	lines.push("  }");
+	return lines;
+}
+/**
+* Generate typed per-route Link call signatures via LinkFunction
+* interface merging.
+*
+* TIM-835: This emits a SINGLE call signature whose props is a
+* discriminated union keyed on `href`. TypeScript narrows the union by
+* the literal `href` at the call site, then checks the rest of the
+* props against the matched variant. When `segmentParams` or
+* `searchParams` is wrong, TS reports the error against the matched
+* variant — naming the user's actual `href` and the offending field.
+*
+* Before TIM-835, this function emitted N separate per-route overloads
+* (one per route, sometimes two for dynamic routes). When ALL overloads
+* failed, TS would pick an arbitrary failed overload (heuristically the
+* "last tried") to render the diagnostic, often pointing at a route
+* completely unrelated to the one the user wrote. The discriminated
+* union sidesteps overload-resolution heuristics entirely.
+*
+* Open property shapes (`Record<string, unknown>` instead of `never`)
+* for `segmentParams` on routes that don't declare them keep generic
+* `LinkProps`-spreading wrappers compiling. (Aligned with TIM-833.)
+*
+* TIM-832: this function still emits the per-route block FIRST and the
+* catch-all block follows, so per-route remains the LAST overload set in
+* resolution order — the one TS reports against on failure. With a
+* discriminated union there is only one call signature in this block,
+* so the resolved-template-vs-pattern ordering reduces to placing the
+* pattern variant before the resolved-template variant inside the union.
+*/
+function formatTypedLinkOverloads(routes, importBase) {
+	const lines = [];
+	const baseProps = LINK_BASE_PROPS_TYPE;
+	const variants = [];
+	for (const route of routes) {
+		const hasDynamicParams = route.params.length > 0;
+		const paramsProp = hasDynamicParams ? `segmentParams: ${formatLinkParamsType(route.params, importBase)}` : "segmentParams?: Record<string, unknown>";
+		const searchParamsType = route.hasSearchParams ? formatSearchParamsType(route, importBase) : null;
+		const patternSearchParamsProp = searchParamsType ? `searchParams?: Partial<${searchParamsType}>` : "searchParams?: Record<string, unknown>";
+		variants.push(`${baseProps} & { href: '${route.urlPath}'; ${paramsProp}; ${patternSearchParamsProp} }`);
+		if (hasDynamicParams) {
+			const templatePattern = buildResolvedPattern(route);
+			if (templatePattern) {
+				const resolvedSearchParamsProp = searchParamsType ? `searchParams?: { definition: SearchParamsDefinition<${searchParamsType}>; values: Partial<${searchParamsType}> }` : "searchParams?: Record<string, unknown>";
+				variants.push(`${baseProps} & { href: \`${templatePattern}\`; segmentParams?: Record<string, never>; ${resolvedSearchParamsProp} }`);
+			}
+		}
+	}
+	lines.push("  interface LinkFunction {");
+	if (variants.length === 0) {
+		lines.push("  }");
+		return lines;
+	}
+	lines.push("    (");
+	lines.push("      props:");
+	for (const variant of variants) lines.push(`        | (${variant})`);
+	lines.push(`    ): import('react').JSX.Element`);
+	lines.push("  }");
+	return lines;
+}
+//#endregion
+//#region src/routing/codegen.ts
+/**
+* Route map codegen.
+*
+* Walks the scanned RouteTree and generates a TypeScript declaration file
+* mapping every route to its params and searchParams shapes.
+*
+* This runs at build time and in dev (regenerated on file changes).
+* No runtime overhead — purely static type generation.
+*/
+/**
+* Generate a TypeScript declaration file string from a scanned route tree.
+*
+* The output is a `declare module '@timber-js/app'` block containing the Routes
+* interface that maps every route path to its params and searchParams shape.
+*/
+function generateRouteMap(tree, options = {}) {
+	const routes = [];
+	collectRoutes(tree.root, [], [], routes);
+	routes.sort((a, b) => a.urlPath.localeCompare(b.urlPath));
+	return formatDeclarationFile(routes, options.outputDir ?? options.appDir);
+}
+/**
+* Recursively walk the segment tree and collect route entries.
+*
+* A route entry is created for any segment that has a `page` or `route` file.
+* Params accumulate from ancestor dynamic segments.
+*/
+function collectRoutes(node, ancestorParams, ancestorParamsFiles, routes) {
+	const ownParamsFile = node.params && fileHasExport(node.params.filePath, "segmentParams") ? node.params.filePath : void 0;
+	const params = [...ancestorParams];
+	if (node.paramName) {
+		const legacyFallback = ownParamsFile ? void 0 : findLegacyParamsExport(node);
+		params.push({
+			name: node.paramName,
+			type: paramTypeForSegment(node.segmentType),
+			legacyCodecFilePath: legacyFallback
+		});
+	}
+	const nextAncestorFiles = ownParamsFile ? [...ancestorParamsFiles, ownParamsFile] : ancestorParamsFiles;
+	const isPage = !!node.page;
+	const isApiRoute = !!node.route;
+	if (isPage || isApiRoute) {
+		const leafFirstChain = nextAncestorFiles.length > 0 ? [...nextAncestorFiles].reverse() : [];
+		const resolvedParams = params.map((p) => {
+			const codecFilePaths = leafFirstChain.length > 0 ? leafFirstChain : p.legacyCodecFilePath ? [p.legacyCodecFilePath] : void 0;
+			return {
+				name: p.name,
+				type: p.type,
+				codecFilePaths
+			};
+		});
+		const entry = {
+			urlPath: node.urlPath,
+			params: resolvedParams,
+			hasSearchParams: false,
+			isApiRoute
+		};
+		if (isPage) {
+			if (node.params && fileHasExport(node.params.filePath, "searchParams")) {
+				entry.hasSearchParams = true;
+				entry.searchParamsPagePath = node.params.filePath;
+			} else if (node.page && fileHasExport(node.page.filePath, "searchParams")) {
+				entry.hasSearchParams = true;
+				entry.searchParamsPagePath = node.page.filePath;
+			}
+		}
+		routes.push(entry);
+	}
+	for (const child of node.children) collectRoutes(child, params, nextAncestorFiles, routes);
+	for (const slot of Object.values(node.slots)) collectRoutes(slot, params, nextAncestorFiles, routes);
+}
+/**
+* Determine the TypeScript type for a segment's param.
+*/
+function paramTypeForSegment(segmentType) {
+	switch (segmentType) {
+		case "catch-all": return "string[]";
+		case "optional-catch-all": return "string[] | undefined";
+		default: return "string";
+	}
+}
+/**
+* Check if a file exports a specific named export.
+*
+* Uses a lightweight regex check — not full AST parsing. The actual type
+* extraction happens via the TypeScript compiler in the generated .d.ts.
+*/
+function fileHasExport(filePath, exportName) {
+	if (!existsSync(filePath)) return false;
+	try {
+		const content = readFileSync(filePath, "utf-8");
+		const e = exportName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+		return new RegExp(`export\\s+(const|let|var)\\s+${e}\\b`).test(content) || new RegExp(`export\\s*\\{[^}]*\\b${e}\\b[^}]*\\}`).test(content);
+	} catch {
+		return false;
+	}
+}
+/**
+* Find a legacy `segmentParams` export on layout.tsx or page.tsx.
+*
+* Backward-compat shim: TIM-508 made params.ts the canonical location
+* for `segmentParams`. Layout/page exports are still accepted for the
+* OWN segment only (not inherited by descendants — see TIM-834).
+*/
+function findLegacyParamsExport(node) {
+	if (node.layout && fileHasExport(node.layout.filePath, "segmentParams")) return node.layout.filePath;
+	if (node.page && fileHasExport(node.page.filePath, "segmentParams")) return node.page.filePath;
+}
+/**
+* Format the collected routes into a TypeScript declaration file.
+*/
+function formatDeclarationFile(routes, importBase) {
+	const lines = [];
+	lines.push("// This file is auto-generated by timber.js route map codegen.");
+	lines.push("// Do not edit manually. Regenerated on build and in dev mode.");
+	lines.push("");
+	lines.push("export {};");
+	lines.push("");
+	lines.push(emitResolveSegmentFieldHelper());
+	lines.push("");
+	lines.push("declare module '@timber-js/app' {");
+	lines.push("  interface Routes {");
+	for (const route of routes) {
+		const paramsType = formatParamsType(route.params, importBase);
+		const searchParamsType = formatSearchParamsType(route, importBase);
+		lines.push(`    '${route.urlPath}': {`);
+		lines.push(`      segmentParams: ${paramsType}`);
+		lines.push(`      searchParams: ${searchParamsType}`);
+		lines.push(`    }`);
+	}
+	lines.push("  }");
+	lines.push("}");
+	lines.push("");
+	const pageRoutes = routes.filter((r) => !r.isApiRoute);
+	const dynamicRoutes = routes.filter((r) => r.params.length > 0);
+	if (dynamicRoutes.length > 0 || pageRoutes.length > 0) {
+		lines.push("declare module '@timber-js/app/client' {");
+		lines.push("  import type { SearchParamsDefinition, SetParams, QueryStatesOptions, SearchParamCodec } from '@timber-js/app/search-params'");
+		lines.push("");
+		if (dynamicRoutes.length > 0) {
+			for (const route of dynamicRoutes) {
+				const paramsType = formatParamsType(route.params, importBase);
+				lines.push(`  export function useSegmentParams(route: '${route.urlPath}'): ${paramsType}`);
+			}
+			lines.push("  export function useSegmentParams(): Record<string, string | string[]>");
+			lines.push("");
+		}
+		if (pageRoutes.length > 0) {
+			lines.push(...formatUseQueryStatesOverloads(pageRoutes, importBase));
+			lines.push("");
+		}
+		if (pageRoutes.length > 0) {
+			lines.push("  // Typed Link overloads — per-route (block 1 / emitted first)");
+			lines.push(...formatTypedLinkOverloads(pageRoutes, importBase));
+			lines.push("");
+		}
+		lines.push("}");
+		lines.push("");
+	}
+	lines.push("declare module '@timber-js/app/client' {");
+	lines.push("  import type { SearchParamsDefinition } from '@timber-js/app/search-params'");
+	lines.push("");
+	lines.push(...formatLinkCatchAllOverloads());
+	lines.push("}");
+	lines.push("");
+	return lines.join("\n");
+}
+/**
+* Format the params type for a route entry.
+*/
+function formatParamsType(params, importBase) {
+	if (params.length === 0) return "{}";
+	return `{ ${params.map((p) => {
+		const codecType = buildCodecChainType(p, importBase, p.type);
+		return `${p.name}: ${codecType}`;
+	}).join("; ")} }`;
+}
+/**
+* Generate useQueryStates overloads.
+*
+* For each page route:
+* - Routes with search-params.ts get a typed overload returning the inferred T
+* - Routes without search-params.ts get an overload returning [{}, SetParams<{}>]
+*
+* A fallback overload for standalone codecs (existing API) is emitted last.
+*/
+function formatUseQueryStatesOverloads(routes, importBase) {
+	const lines = [];
+	for (const route of routes) {
+		const searchParamsType = route.hasSearchParams ? formatSearchParamsType(route, importBase) : "{}";
+		lines.push(`  export function useQueryStates<R extends '${route.urlPath}'>(route: R, options?: QueryStatesOptions): [${searchParamsType}, SetParams<${searchParamsType}>]`);
+	}
+	lines.push("  export function useQueryStates<T extends Record<string, unknown>>(codecs: { [K in keyof T]: SearchParamCodec<T[K]> }, options?: QueryStatesOptions): [T, SetParams<T>]");
+	return lines;
+}
+//#endregion
+//#region src/routing/interception.ts
+/**
+* Collect all interception rewrite rules from the route tree.
+*
+* Walks the tree recursively. For each intercepting segment, computes the
+* intercepted URL based on the marker and the segment's position.
+*/
+function collectInterceptionRewrites(root) {
+	const rewrites = [];
+	walkForInterceptions(root, [root], rewrites);
+	return rewrites;
+}
+/**
+* Recursively walk the segment tree to find intercepting routes.
+*/
+function walkForInterceptions(node, ancestors, rewrites) {
+	for (const child of node.children) if (child.segmentType === "intercepting" && child.interceptionMarker) collectFromInterceptingNode(child, ancestors, rewrites);
+	else walkForInterceptions(child, [...ancestors, child], rewrites);
+	for (const slot of Object.values(node.slots)) walkForInterceptions(slot, ancestors, rewrites);
+}
+/**
+* For an intercepting segment, find all leaf pages in its sub-tree and
+* generate rewrite rules for each.
+*/
+function collectFromInterceptingNode(interceptingNode, ancestors, rewrites) {
+	const marker = interceptingNode.interceptionMarker;
+	const segmentName = interceptingNode.interceptedSegmentName;
+	const parentUrlPath = ancestors[ancestors.length - 1].urlPath;
+	const interceptedBase = computeInterceptedBase(parentUrlPath, marker);
+	collectLeavesWithRewrites(interceptingNode, interceptedBase === "/" ? `/${segmentName}` : `${interceptedBase}/${segmentName}`, parentUrlPath, [...ancestors, interceptingNode], rewrites);
+}
+/**
+* Recursively find leaf pages in an intercepting sub-tree and generate
+* rewrite rules for each.
+*/
+function collectLeavesWithRewrites(node, interceptedUrlPath, interceptingPrefix, segmentPath, rewrites) {
+	if (node.page) rewrites.push({
+		interceptedPattern: interceptedUrlPath,
+		interceptingPrefix,
+		segmentPath: [...segmentPath]
+	});
+	for (const child of node.children) collectLeavesWithRewrites(child, child.segmentType === "group" ? interceptedUrlPath : `${interceptedUrlPath}/${child.segmentName}`, interceptingPrefix, [...segmentPath, child], rewrites);
+}
+/**
+* Compute the base URL that an intercepting route intercepts, given the
+* parent's URL path and the interception marker.
+*
+* - (.)  — same level: parent's URL path
+* - (..) — one level up: parent's parent URL path
+* - (...) — root level: /
+* - (..)(..) — two levels up: parent's grandparent URL path
+*
+* Level counting operates on URL path segments, NOT filesystem directories.
+* Route groups and parallel slots are already excluded from urlPath (they
+* don't add URL depth), so (..) correctly climbs visible segments. This
+* avoids the Vinext bug where path.dirname() on filesystem paths would
+* waste climbs on invisible route groups.
+*/
+function computeInterceptedBase(parentUrlPath, marker) {
+	switch (marker) {
+		case "(.)": return parentUrlPath;
+		case "(..)": {
+			const parts = parentUrlPath.split("/").filter(Boolean);
+			parts.pop();
+			return parts.length === 0 ? "/" : `/${parts.join("/")}`;
+		}
+		case "(...)": return "/";
+		case "(..)(..)": {
+			const parts = parentUrlPath.split("/").filter(Boolean);
+			parts.pop();
+			parts.pop();
+			return parts.length === 0 ? "/" : `/${parts.join("/")}`;
+		}
+	}
+}
+//#endregion
+//#region src/routing/walkers.ts
+/**
+* Walk a segment tree and collect every leaf with a `page` or `route`
+* handler. Generic over `TFile` so it works on both the build-time
+* scanner output and the runtime manifest tree.
+*
+* - Pages and route handlers at the same URL produce two distinct
+*   entries (the build report deduplicates by URL afterward).
+* - Parallel slots are skipped unless `includeSlots: true` (slots
+*   share their parent's URL and are not addressable on their own).
+* - Result is sorted by `urlPath` for deterministic output.
+*/
+function collectLeafRoutes(root, options = {}) {
+	const { includeSlots = false } = options;
+	const result = [];
+	walk(root, [], result, includeSlots);
+	result.sort((a, b) => a.urlPath.localeCompare(b.urlPath));
+	return result;
+}
+function walk(node, chain, result, includeSlots) {
+	const currentChain = [...chain, node];
+	const path = node.urlPath || "/";
+	if (node.page) result.push({
+		urlPath: path,
+		segments: currentChain,
+		page: node.page
+	});
+	if (node.route) result.push({
+		urlPath: path,
+		segments: currentChain,
+		route: node.route
+	});
+	for (const child of node.children) walk(child, currentChain, result, includeSlots);
+	if (includeSlots) for (const slotNode of Object.values(node.slots)) walk(slotNode, currentChain, result, includeSlots);
+}
+//#endregion
+export { scanRoutes as i, collectInterceptionRewrites as n, generateRouteMap as r, collectLeafRoutes as t };
+
+//# sourceMappingURL=walkers-Tg0Alwcg.js.map