@timber-js/app 0.2.0-alpha.18 → 0.2.0-alpha.181

package/dist/_chunks/walkers-BtTlKviE.js

@@ -0,0 +1,1002 @@
+import { n as classifyUrlSegment } from "./segment-classify-Byy425ng.js";
+import { n as findSchemaFile, r as parseExistingSchemaKeys } from "./cli-schema-sync-D3naS3eH.js";
+import { parseAst } from "vite";
+import { join, posix, relative } from "node:path";
+import { existsSync, readFileSync, statSync } from "node:fs";
+//#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;
+}
+/**
+* Build a TypeScript type expression for a single param using the global
+* schema's InferCodecType. Falls back to the param's base type when
+* schema doesn't declare this param (schemas are opt-in per key).
+*
+* Uses `infer` to extract the codec value rather than direct indexing
+* because TypeScript doesn't narrow index validity inside a conditional
+* type's true branch — `typeof schema.segmentParams[K]` produces TS2538
+* even when the condition proves K is a valid key. In .d.ts files that
+* error is suppressed and the type silently becomes `any`.
+*/
+function buildSchemaParamType(p, fallback) {
+	return `typeof schema['segmentParams'] extends Record<${JSON.stringify(p.bracketName)}, infer V> ? InferCodecType<V> : ${fallback ?? p.type}`;
+}
+/**
+* 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/file-cache.ts
+var cache = /* @__PURE__ */ new Map();
+/**
+* Read a file's text content, returning a cached copy when the file
+* hasn't been modified since the last read (checked via mtime + size).
+*
+* Falls back to a fresh read on any stat/read error.
+*/
+function readFileCached(filePath) {
+	try {
+		const stat = statSync(filePath);
+		const entry = cache.get(filePath);
+		if (entry && entry.mtimeMs === stat.mtimeMs && entry.size === stat.size) return entry.content;
+		const content = readFileSync(filePath, "utf-8");
+		cache.set(filePath, {
+			mtimeMs: stat.mtimeMs,
+			size: stat.size,
+			content
+		});
+		return content;
+	} catch {
+		cache.delete(filePath);
+		return readFileSync(filePath, "utf-8");
+	}
+}
+//#endregion
+//#region src/routing/export-detect.ts
+/**
+* AST-based export detection for route files.
+*
+* Uses Vite's `parseAst` (backed by oxc) to precisely detect named and
+* default exports, replacing the regex-based approach that was fragile
+* with TypeScript syntax (type exports, `as` aliases, comments, etc.).
+*/
+function tryParse(source) {
+	try {
+		return parseAst(source, { lang: "tsx" });
+	} catch {
+		return null;
+	}
+}
+/**
+* Collect all named export identifiers from a parsed program.
+* Handles: `export function X`, `export const X`, `export { X }`,
+* `export { X } from '...'`, `export { Y as X }`.
+*/
+function collectNamedExports(program) {
+	const names = /* @__PURE__ */ new Set();
+	for (const stmt of program.body) {
+		if (stmt.type !== "ExportNamedDeclaration") continue;
+		if (stmt.exportKind === "type") continue;
+		if (stmt.declaration) {
+			if (stmt.declaration.id?.name) names.add(stmt.declaration.id.name);
+			if (stmt.declaration.declarations) {
+				for (const decl of stmt.declaration.declarations) if (decl.id?.name) names.add(decl.id.name);
+			}
+		}
+		if (stmt.specifiers) for (const spec of stmt.specifiers) {
+			if (spec.exportKind === "type") continue;
+			if (spec.exported?.name && spec.exported.name !== "default") names.add(spec.exported.name);
+		}
+	}
+	return names;
+}
+/**
+* Check whether a program has a default export.
+* Handles: `export default ...`, `export { X as default }`,
+* `export { default } from '...'`.
+*/
+function hasDefaultExport(program) {
+	for (const stmt of program.body) {
+		if (stmt.type === "ExportDefaultDeclaration") return true;
+		if (stmt.type === "ExportNamedDeclaration" && stmt.specifiers) {
+			for (const spec of stmt.specifiers) if (spec.exported?.name === "default") return true;
+		}
+	}
+	return false;
+}
+/**
+* Check whether a program has any bare `export * from '...'` declarations.
+* Excludes `export * as X from '...'` (namespace re-exports) since those
+* create a namespace object, not individual top-level exports.
+*/
+function hasStarExport(program) {
+	return program.body.some((stmt) => stmt.type === "ExportAllDeclaration" && !stmt.exported && stmt.exportKind !== "type");
+}
+/**
+* Check if a file exports a specific named export.
+* Returns false if the file doesn't exist or can't be parsed.
+*/
+function fileHasExport(filePath, exportName) {
+	if (!existsSync(filePath)) return false;
+	try {
+		const program = tryParse(readFileCached(filePath));
+		if (!program) return false;
+		return collectNamedExports(program).has(exportName);
+	} catch {
+		return false;
+	}
+}
+/**
+* Check if a file has any of the given named exports.
+* Returns the set of matching export names.
+*/
+function fileHasAnyExport(filePath, exportNames) {
+	const matches = /* @__PURE__ */ new Set();
+	try {
+		const program = tryParse(readFileCached(filePath));
+		if (!program) return matches;
+		const exports = collectNamedExports(program);
+		for (const name of exportNames) if (exports.has(name)) matches.add(name);
+	} catch {}
+	return matches;
+}
+/**
+* Check if a file has a default export.
+* Returns false if the file doesn't exist or can't be parsed.
+*/
+function fileHasDefaultExport(filePath) {
+	if (!existsSync(filePath)) return false;
+	try {
+		const program = tryParse(readFileCached(filePath));
+		if (!program) return false;
+		return hasDefaultExport(program);
+	} catch {
+		return false;
+	}
+}
+/**
+* Check if a file has any `export * from '...'` declarations.
+* Returns false if the file doesn't exist or can't be parsed.
+*/
+function fileHasStarExport(filePath) {
+	if (!existsSync(filePath)) return false;
+	try {
+		const program = tryParse(readFileCached(filePath));
+		if (!program) return false;
+		return hasStarExport(program);
+	} catch {
+		return false;
+	}
+}
+function extractLiteralValue(node) {
+	if (!node) return void 0;
+	const n = node;
+	if (n.type === "Literal") return n.value;
+	if (n.type === "UnaryExpression" && n.operator === "-" && n.argument?.type === "Literal") return -n.argument.value;
+	if (n.type === "ArrayExpression") {
+		const elements = n.elements;
+		if (!elements) return void 0;
+		const result = [];
+		for (const el of elements) {
+			const v = extractLiteralValue(el);
+			if (v === void 0) return void 0;
+			result.push(v);
+		}
+		return result;
+	}
+}
+function extractObjectLiteral(node) {
+	if (node.type !== "ObjectExpression") return void 0;
+	const props = node.properties;
+	if (!props) return void 0;
+	const result = {};
+	for (const prop of props) {
+		const p = prop;
+		if (p.type === "SpreadElement") return void 0;
+		if (p.type !== "Property" || p.computed) return void 0;
+		const key = p.key?.type === "Identifier" ? p.key.name : p.key?.type === "Literal" ? String(p.key.value) : void 0;
+		if (!key) return void 0;
+		const value = extractLiteralValue(p.value);
+		if (value === void 0) return void 0;
+		result[key] = value;
+	}
+	return result;
+}
+/**
+* Extract the value of `export const prerender` from a file.
+* Returns undefined if the file doesn't export `prerender` or can't be parsed.
+*
+* Supports:
+*   export const prerender = true;
+*   export const prerender = false;
+*   export const prerender = { ttl: 3600, tags: ['docs'] };
+*/
+function getPrerenderExport(filePath) {
+	if (!existsSync(filePath)) return void 0;
+	try {
+		const program = tryParse(readFileCached(filePath));
+		if (!program) return void 0;
+		for (const stmt of program.body) {
+			if (stmt.type !== "ExportNamedDeclaration") continue;
+			if (stmt.exportKind === "type") continue;
+			if (!stmt.declaration) continue;
+			const decl = stmt.declaration;
+			if (decl.type !== "VariableDeclaration") continue;
+			const declarations = decl.declarations;
+			if (!declarations) continue;
+			for (const d of declarations) {
+				if (d.id?.name !== "prerender" || !d.init) continue;
+				const init = d.init;
+				if (init.type === "Literal" && typeof init.value === "boolean") return init.value;
+				if (init.type === "ObjectExpression") {
+					const obj = extractObjectLiteral(init);
+					if (!obj) return void 0;
+					const result = {};
+					if ("ttl" in obj && typeof obj.ttl === "number") result.ttl = obj.ttl;
+					if ("tags" in obj && Array.isArray(obj.tags) && obj.tags.every((t) => typeof t === "string")) result.tags = obj.tags;
+					return result;
+				}
+				return;
+			}
+		}
+		return;
+	} catch {
+		return;
+	}
+}
+/**
+* Check if a file starts with a specific directive (e.g. "use client").
+* Directives are string literal expression statements at the top of the file.
+*/
+function fileHasDirective(filePath, directive) {
+	if (!existsSync(filePath)) return false;
+	try {
+		const program = tryParse(readFileCached(filePath));
+		if (!program) return false;
+		for (const stmt of program.body) {
+			if (stmt.type !== "ExpressionStatement") break;
+			const expr = stmt.expression;
+			if (expr?.type !== "Literal" || typeof expr.value !== "string") break;
+			if (expr.value === directive) return true;
+		}
+		return false;
+	} catch {
+		return false;
+	}
+}
+//#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) => {
+		const seg = classifyUrlSegment(part);
+		switch (seg.kind) {
+			case "catch-all":
+			case "optional-catch-all": return "${string}";
+			case "dynamic": return `${seg.prefix ?? ""}\${string}${seg.suffix ?? ""}`;
+			default: 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, hasSchema) {
+	if (params.length === 0) return "{}";
+	return `{ ${params.map((p) => {
+		const fallback = p.type === "string" ? "string | number" : p.type;
+		const codecType = hasSchema ? buildSchemaParamType(p, fallback) : buildCodecChainType(p, importBase, fallback);
+		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, hasSchema) {
+	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, hasSchema)}` : "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 hasSchema = options.hasSchema ?? detectSchema(options.appDir);
+	const routes = [];
+	collectRoutes(tree.root, [], [], "", routes, hasSchema, false);
+	routes.sort((a, b) => a.urlPath.localeCompare(b.urlPath));
+	return formatDeclarationFile(routes, options.outputDir ?? options.appDir, hasSchema, options.appDir);
+}
+/** Schema file extensions to check, in priority order. */
+var SCHEMA_EXTENSIONS = [
+	".ts",
+	".tsx",
+	".js",
+	".jsx"
+];
+/**
+* Detect whether app/schema.{ts,tsx,js,jsx} exists.
+*/
+function detectSchema(appDir) {
+	if (!appDir) return false;
+	return SCHEMA_EXTENSIONS.some((ext) => existsSync(join(appDir, `schema${ext}`)));
+}
+/**
+* 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, parentTreePath, routes, hasSchema, insideSlot) {
+	const treePath = node.segmentName ? `${parentTreePath}/${node.segmentName}` : parentTreePath;
+	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,
+			bracketName: bracketNameForSegment(node),
+			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,
+				bracketName: p.bracketName,
+				type: p.type,
+				codecFilePaths
+			};
+		});
+		const entry = {
+			urlPath: node.urlPath,
+			segmentPath: treePath || "/",
+			params: resolvedParams,
+			hasSearchParams: false,
+			isApiRoute,
+			isSlotRoute: insideSlot,
+			hasSchema
+		};
+		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, treePath, routes, hasSchema, insideSlot);
+	for (const slot of Object.values(node.slots)) collectRoutes(slot, params, nextAncestorFiles, treePath, routes, hasSchema, true);
+}
+/**
+* Dedupe route entries by urlPath for urlPath-keyed emissions (the Routes
+* interface, useQueryStates overloads, and typed Link variants).
+*
+* Parallel-slot pages share their parent's urlPath; emitting one entry per
+* slot page produced duplicate interface keys (TS2300/TS2717 under
+* skipLibCheck:false) and duplicate overloads. The non-slot entry is the
+* canonical one; when only slot entries exist (parent has no page), the
+* lexicographically smallest segmentPath wins so output is independent of
+* slot scan order. A slot's searchParams definition is carried onto the
+* merged entry when the canonical entry has none — never silently dropped.
+*
+* segmentPath-keyed emissions (getSegmentParams, useSegmentParams,
+* TimberSegmentParams) must NOT use this — segmentPaths are already unique
+* and slot entries feed those APIs directly.
+*/
+function dedupeRoutesByUrlPath(routes) {
+	const byPath = /* @__PURE__ */ new Map();
+	for (const route of routes) {
+		const existing = byPath.get(route.urlPath);
+		if (!existing) {
+			byPath.set(route.urlPath, route);
+			continue;
+		}
+		let winner = existing;
+		let loser = route;
+		if (existing.isSlotRoute && !route.isSlotRoute || !!existing.isSlotRoute === !!route.isSlotRoute && route.segmentPath.localeCompare(existing.segmentPath) < 0) {
+			winner = route;
+			loser = existing;
+		}
+		if (!winner.hasSearchParams && loser.hasSearchParams) winner = {
+			...winner,
+			hasSearchParams: true,
+			searchParamsPagePath: loser.searchParamsPagePath
+		};
+		byPath.set(route.urlPath, winner);
+	}
+	return [...byPath.values()];
+}
+/**
+* Determine the TypeScript type for a segment's param.
+*/
+/**
+* Derive the bracket key for schema/codegen lookup.
+* For bare segments like `[id]` this is the segmentName itself.
+* For affixed segments like `img-[id].png` this is `[id]` — the bare bracket form.
+*/
+function bracketNameForSegment(node) {
+	if (node.paramPrefix || node.paramSuffix) return `[${node.paramName}]`;
+	return node.segmentName;
+}
+function paramTypeForSegment(segmentType) {
+	switch (segmentType) {
+		case "catch-all": return "string[]";
+		case "optional-catch-all": return "string[] | undefined";
+		default: return "string";
+	}
+}
+/**
+* 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;
+}
+/**
+* Emit the schema-based type exports: TimberSegmentParams, TimberRoute,
+* AllSegmentParams, RoutesWithParams.
+*
+* These types use InferCodecType references so they stay in sync with
+* the schema without hardcoding resolved types.
+*
+* Design doc: design/41-global-params.md §Codegen Output
+*/
+function formatSchemaTypes(routes) {
+	const lines = [];
+	lines.push("/** Union of all valid route patterns. */");
+	lines.push("export type TimberRoute = keyof TimberSegmentParams;");
+	lines.push("");
+	lines.push("/** Maps each segment path to its accumulated segment params. */");
+	lines.push("export interface TimberSegmentParams {");
+	for (const route of routes) if (route.params.length === 0) lines.push(`  '${route.segmentPath}': {};`);
+	else {
+		lines.push(`  '${route.segmentPath}': {`);
+		for (const p of route.params) lines.push(`    ${p.name}: ${buildSchemaParamType(p)};`);
+		lines.push("  };");
+	}
+	lines.push("}");
+	lines.push("");
+	lines.push("/** All segment params (union of all route params). */");
+	lines.push("export type AllSegmentParams = {");
+	lines.push("  [K in keyof TimberSegmentParams as TimberSegmentParams[K] extends Record<string, never>");
+	lines.push("    ? never");
+	lines.push("    : K]: TimberSegmentParams[K];");
+	lines.push("} extends infer U");
+	lines.push("  ? { [K in keyof U[keyof U]]: U[keyof U][K] }");
+	lines.push("  : never;");
+	lines.push("");
+	lines.push("/** Filters TimberRoute to routes whose accumulated params include all listed keys. */");
+	lines.push("export type RoutesWithParams<K extends keyof AllSegmentParams> = {");
+	lines.push("  [R in TimberRoute]: K extends keyof TimberSegmentParams[R] ? R : never;");
+	lines.push("}[TimberRoute];");
+	return lines;
+}
+/**
+* Format the collected routes into a TypeScript declaration file.
+*/
+function formatDeclarationFile(routes, importBase, hasSchema, appDir) {
+	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("");
+	if (hasSchema) {
+		const schemaImport = appDir && importBase ? "./" + relative(importBase, join(appDir, "schema")).replace(/\\/g, "/") : "../app/schema";
+		lines.push(`import type schema from '${schemaImport}';`);
+		lines.push("import type { InferCodecType, SegmentParamCodec } from '@timber-js/app/params';");
+		lines.push("");
+		const allBracketKeys = /* @__PURE__ */ new Set();
+		for (const route of routes) for (const p of route.params) allBracketKeys.add(p.bracketName);
+		if (allBracketKeys.size > 0) {
+			lines.push("declare module '@timber-js/app/params' {");
+			lines.push("  interface ValidDynamicSegmentKeysRegistry {");
+			for (const key of [...allBracketKeys].sort()) lines.push(`    ${JSON.stringify(key)}: true;`);
+			lines.push("  }");
+			lines.push("}");
+			lines.push("");
+		}
+		lines.push("type _AssertSchemaValues = {");
+		lines.push("  [K in keyof typeof schema['segmentParams']]: typeof schema['segmentParams'][K] extends SegmentParamCodec ? true : ['Error: value for', K, 'is not a valid Codec or Standard Schema'];");
+		lines.push("};");
+		lines.push("type _EnforceSchemaValues<_T extends Record<string, true> = _AssertSchemaValues> = true;");
+		lines.push("");
+	}
+	if (!hasSchema) {
+		lines.push(emitResolveSegmentFieldHelper());
+		lines.push("");
+	}
+	const uniqueByUrlPath = dedupeRoutesByUrlPath(routes);
+	lines.push("declare module '@timber-js/app' {");
+	lines.push("  interface Routes {");
+	for (const route of uniqueByUrlPath) {
+		const paramsType = formatParamsType(route.params, importBase, hasSchema);
+		const searchParamsType = formatSearchParamsType(route, importBase);
+		lines.push(`    '${route.urlPath}': {`);
+		lines.push(`      segmentParams: ${paramsType}`);
+		lines.push(`      searchParams: ${searchParamsType}`);
+		lines.push(`    }`);
+	}
+	lines.push("  }");
+	if (hasSchema) {
+		lines.push("");
+		lines.push(...formatSchemaTypes(routes).map((l) => `  ${l}`));
+	}
+	lines.push("}");
+	lines.push("");
+	const pageRoutes = uniqueByUrlPath.filter((r) => !r.isApiRoute);
+	const dynamicRoutes = routes.filter((r) => r.params.length > 0);
+	if (dynamicRoutes.length > 0) {
+		lines.push("declare module '@timber-js/app/server' {");
+		if (hasSchema) lines.push("  import type { AllSegmentParams } from '@timber-js/app'");
+		for (const route of dynamicRoutes) {
+			const paramsType = formatParamsType(route.params, importBase, hasSchema);
+			lines.push(`  export function getSegmentParams(segmentPath: '${route.segmentPath}'): ${paramsType}`);
+		}
+		lines.push(hasSchema ? "  export function getSegmentParams(): Partial<AllSegmentParams>" : "  export function getSegmentParams(): Record<string, string | string[]>");
+		lines.push("}");
+		lines.push("");
+	}
+	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'");
+		if (hasSchema) lines.push("  import type { AllSegmentParams } from '@timber-js/app'");
+		lines.push("");
+		if (dynamicRoutes.length > 0) {
+			for (const route of dynamicRoutes) {
+				const paramsType = formatParamsType(route.params, importBase, hasSchema);
+				lines.push(`  export function useSegmentParams(segmentPath: '${route.segmentPath}'): ${paramsType}`);
+			}
+			lines.push(hasSchema ? "  export function useSegmentParams(): Partial<AllSegmentParams>" : "  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, hasSchema));
+			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, hasSchema) {
+	if (params.length === 0) return "{}";
+	return `{ ${params.map((p) => {
+		const codecType = hasSchema ? buildSchemaParamType(p) : 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/schema-validation.ts
+/**
+* Schema key/value validation against the filesystem route tree.
+*
+* Runs at codegen time (build + dev) to catch mismatches between
+* app/schema.ts keys and the actual dynamic segments on disk.
+*
+* Design doc: design/41-global-params.md
+*/
+/**
+* Collect all unique bracket-keyed dynamic segment names from a route tree.
+* Returns entries like '[artistSlug]', '[...slug]', '[[...topic]]'.
+*/
+function collectDynamicSegmentsFromTree(tree) {
+	const segments = /* @__PURE__ */ new Set();
+	walkTree(tree.root, segments);
+	return segments;
+}
+function walkTree(node, segments) {
+	if (node.paramName && node.segmentName) {
+		const classified = classifyUrlSegment(node.segmentName);
+		if (classified.kind !== "static") if (classified.kind === "dynamic" && (classified.prefix || classified.suffix)) segments.add(`[${classified.name}]`);
+		else segments.add(node.segmentName);
+	}
+	for (const child of node.children) walkTree(child, segments);
+	for (const slot of Object.values(node.slots)) walkTree(slot, segments);
+}
+/**
+* Extract the param name from a bracket key.
+* '[id]' → 'id', '[...slug]' → 'slug', '[[...topic]]' → 'topic'
+*/
+function extractParamName(bracketKey) {
+	const seg = classifyUrlSegment(bracketKey);
+	if (seg.kind === "static") return null;
+	return seg.name;
+}
+/**
+* Validate schema keys against the filesystem route tree.
+*
+* Returns warnings for:
+* - Stale keys: schema keys that don't match any filesystem segment
+* - Bracket form mismatches: same param name, different bracket form
+* - Missing keys: filesystem segments not registered in schema (informational)
+*/
+function validateSchemaAgainstRoutes(tree, appDir) {
+	const schemaPath = findSchemaFile(appDir);
+	if (!schemaPath) return [];
+	const schemaKeys = parseExistingSchemaKeys(readFileCached(schemaPath));
+	if (schemaKeys.length === 0) return [];
+	return validateKeys(schemaKeys, collectDynamicSegmentsFromTree(tree));
+}
+/**
+* Core validation: compare schema keys against filesystem segments.
+* Exported separately for testing without filesystem dependencies.
+*/
+function validateKeys(schemaKeys, filesystemSegments) {
+	const warnings = [];
+	const fsParamToKey = /* @__PURE__ */ new Map();
+	for (const fsKey of filesystemSegments) {
+		const name = extractParamName(fsKey);
+		if (name) fsParamToKey.set(name, fsKey);
+	}
+	const schemaParamNames = /* @__PURE__ */ new Set();
+	for (const schemaKey of schemaKeys) {
+		const schemaParamName = extractParamName(schemaKey);
+		if (!schemaParamName) continue;
+		schemaParamNames.add(schemaParamName);
+		if (filesystemSegments.has(schemaKey)) continue;
+		const fsKey = fsParamToKey.get(schemaParamName);
+		if (fsKey) warnings.push({
+			type: "bracket-mismatch",
+			key: schemaKey,
+			filesystemKey: fsKey,
+			message: `Schema key '${schemaKey}' does not match filesystem bracket form '${fsKey}'. Update the schema key to '${fsKey}'.`
+		});
+		else warnings.push({
+			type: "stale-key",
+			key: schemaKey,
+			message: `Schema key '${schemaKey}' does not match any dynamic segment in the filesystem. Remove it from app/schema.ts or create the corresponding route segment.`
+		});
+	}
+	for (const fsKey of filesystemSegments) {
+		const name = extractParamName(fsKey);
+		if (name && !schemaParamNames.has(name)) warnings.push({
+			type: "missing-key",
+			key: fsKey,
+			message: `Dynamic segment '${fsKey}' has no codec in app/schema.ts (defaults to string). Run: timber schema sync`
+		});
+	}
+	return warnings;
+}
+//#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, rewrites);
+}
+/**
+* Recursively find leaf pages in an intercepting sub-tree and generate
+* rewrite rules for each.
+*/
+function collectLeavesWithRewrites(node, interceptedUrlPath, interceptingPrefix, rewrites) {
+	if (node.page) rewrites.push({
+		interceptedPattern: interceptedUrlPath,
+		interceptingPrefix
+	});
+	for (const child of node.children) collectLeavesWithRewrites(child, child.segmentType === "group" ? interceptedUrlPath : `${interceptedUrlPath}/${child.segmentName}`, interceptingPrefix, 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 { generateRouteMap as a, fileHasDirective as c, getPrerenderExport as d, validateSchemaAgainstRoutes as i, fileHasExport as l, collectInterceptionRewrites as n, fileHasAnyExport as o, collectDynamicSegmentsFromTree as r, fileHasDefaultExport as s, collectLeafRoutes as t, fileHasStarExport as u };
+
+//# sourceMappingURL=walkers-BtTlKviE.js.map