@timber-js/app 0.2.0-alpha.15 → 0.2.0-alpha.151

package/dist/_chunks/walkers-DvWDj453.js

@@ -0,0 +1,790 @@
+import { n as classifyUrlSegment } from "./segment-classify-CDDRVKs7.js";
+import { a as parseExistingSchemaKeys, r as findSchemaFile } from "./cli-schema-sync-DJDdyEae.js";
+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/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, 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: node.segmentName,
+			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.
+*/
+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 = readFileCached(filePath);
+		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;
+}
+/**
+* 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) {
+		if (classifyUrlSegment(node.segmentName).kind !== "static") 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, validateSchemaAgainstRoutes as i, collectInterceptionRewrites as n, readFileCached as o, collectDynamicSegmentsFromTree as r, collectLeafRoutes as t };
+
+//# sourceMappingURL=walkers-DvWDj453.js.map