@timber-js/app 0.2.0-alpha.9 → 0.2.0-alpha.90

package/dist/_chunks/{interception-BOoWmLUA.js → interception-DRlhJWbu.js}

@@ -1,6 +1,7 @@
-import { a as isDynamicMetadataExtension, n as classifyMetadataRoute } from "./metadata-routes-Cjmvi3rQ.js";
-import { existsSync, readdirSync, statSync } from "node:fs";
+import { t as classifyUrlSegment } from "./segment-classify-BDNn6EzD.js";
+import { a as isDynamicMetadataExtension, n as classifyMetadataRoute } from "./metadata-routes-DS3eKNmf.js";
 import { basename, extname, join, posix, relative } from "node:path";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 //#region src/routing/types.ts
 /** All recognized interception markers, ordered longest-first for parsing. */
 var INTERCEPTION_MARKERS = [
@@ -65,8 +66,7 @@ var FIXED_CONVENTIONS = new Set([
 	"middleware",
 	"access",
 	"route",
-	"prerender",
-	"search-params"
+	"params"
 ]);
 /**
 * Status-code file patterns:
@@ -87,9 +87,12 @@ function scanRoutes(appDir, config = {}) {
 	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;
 }
 /**
@@ -120,17 +123,10 @@ function classifySegment(dirName) {
 		interceptedSegmentName: interception.segmentName
 	};
 	if (dirName.startsWith("(") && dirName.endsWith(")")) return { type: "group" };
-	if (dirName.startsWith("[[...") && dirName.endsWith("]]")) return {
-		type: "optional-catch-all",
-		paramName: dirName.slice(5, -2)
-	};
-	if (dirName.startsWith("[...") && dirName.endsWith("]")) return {
-		type: "catch-all",
-		paramName: dirName.slice(4, -1)
-	};
-	if (dirName.startsWith("[") && dirName.endsWith("]")) return {
-		type: "dynamic",
-		paramName: dirName.slice(1, -1)
+	const urlSeg = classifyUrlSegment(dirName);
+	if (urlSeg.kind !== "static") return {
+		type: urlSeg.kind,
+		paramName: urlSeg.name
 	};
 	return { type: "static" };
 }
@@ -224,11 +220,8 @@ function scanSegmentFiles(dirPath, node, extSet) {
 				case "route":
 					node.route = file;
 					break;
-				case "prerender":
-					node.prerender = file;
-					break;
-				case "search-params":
-					node.searchParams = file;
+				case "params":
+					node.params = file;
 					break;
 			}
 			continue;
@@ -338,6 +331,34 @@ function collectRoutableLeaves(node, seen, segmentPath, insideSlot) {
 	for (const [, slotNode] of 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 node.slots) walkForDuplicateParams(slotNode, new Map(seen));
+}
+/**
 * Find a fixed-extension file (proxy.ts) in a directory.
 */
 function findFixedFile(dirPath, name) {
@@ -351,6 +372,21 @@ function findFixedFile(dirPath, name) {
 		} 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.ts
 /**
@@ -370,7 +406,7 @@ function findFixedFile(dirPath, name) {
 */
 function generateRouteMap(tree, options = {}) {
 	const routes = [];
-	collectRoutes(tree.root, [], options.appDir, routes);
+	collectRoutes(tree.root, [], routes);
 	routes.sort((a, b) => a.urlPath.localeCompare(b.urlPath));
 	return formatDeclarationFile(routes, options.outputDir ?? options.appDir);
 }
@@ -380,12 +416,16 @@ function generateRouteMap(tree, options = {}) {
 * 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, appDir, routes) {
+function collectRoutes(node, ancestorParams, routes) {
 	const params = [...ancestorParams];
-	if (node.paramName) params.push({
-		name: node.paramName,
-		type: paramTypeForSegment(node.segmentType)
-	});
+	if (node.paramName) {
+		const codecFile = findParamsExport(node);
+		params.push({
+			name: node.paramName,
+			type: paramTypeForSegment(node.segmentType),
+			codecFilePath: codecFile
+		});
+	}
 	const isPage = !!node.page;
 	const isApiRoute = !!node.route;
 	if (isPage || isApiRoute) {
@@ -395,17 +435,19 @@ function collectRoutes(node, ancestorParams, appDir, routes) {
 			hasSearchParams: false,
 			isApiRoute
 		};
-		if (appDir && isPage) {
-			const searchParamsFile = findSearchParamsFile(resolveSegmentDir(appDir, node));
-			if (searchParamsFile) {
+		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.searchParamsAbsPath = searchParamsFile;
+				entry.searchParamsPagePath = node.page.filePath;
 			}
 		}
 		routes.push(entry);
 	}
-	for (const child of node.children) collectRoutes(child, params, appDir, routes);
-	for (const [, slot] of node.slots) collectRoutes(slot, params, appDir, routes);
+	for (const child of node.children) collectRoutes(child, params, routes);
+	for (const [, slot] of node.slots) collectRoutes(slot, params, routes);
 }
 /**
 * Determine the TypeScript type for a segment's param.
@@ -418,28 +460,32 @@ function paramTypeForSegment(segmentType) {
 	}
 }
 /**
-* Resolve the absolute directory path for a segment node.
+* Check if a file exports a specific named export.
 *
-* Reconstructs the filesystem path by walking from appDir through
-* the segment names encoded in the urlPath, accounting for groups and slots.
-*/
-function resolveSegmentDir(appDir, node) {
-	const file = node.page ?? node.route;
-	if (file) {
-		const parts = file.filePath.split("/");
-		parts.pop();
-		return parts.join("/");
+* 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;
 	}
-	return appDir;
 }
 /**
-* Find a search-params.ts file in a directory.
-*/
-function findSearchParamsFile(dirPath) {
-	for (const ext of ["ts", "tsx"]) {
-		const candidate = join(dirPath, `search-params.${ext}`);
-		if (existsSync(candidate)) return candidate;
-	}
+* Find which file exports `segmentParams` for a dynamic segment.
+*
+* Priority: params.ts (convention file) > layout > page.
+* params.ts is the canonical location (TIM-508). Layout/page fallback
+* exists for backward compat during migration.
+*/
+function findParamsExport(node) {
+	if (node.params && fileHasExport(node.params.filePath, "segmentParams")) return node.params.filePath;
+	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.
@@ -454,10 +500,10 @@ function formatDeclarationFile(routes, importBase) {
 	lines.push("declare module '@timber-js/app' {");
 	lines.push("  interface Routes {");
 	for (const route of routes) {
-		const paramsType = formatParamsType(route.params);
+		const paramsType = formatParamsType(route.params, importBase);
 		const searchParamsType = formatSearchParamsType(route, importBase);
 		lines.push(`    '${route.urlPath}': {`);
-		lines.push(`      params: ${paramsType}`);
+		lines.push(`      segmentParams: ${paramsType}`);
 		lines.push(`      searchParams: ${searchParamsType}`);
 		lines.push(`    }`);
 	}
@@ -465,13 +511,6 @@ function formatDeclarationFile(routes, importBase) {
 	lines.push("}");
 	lines.push("");
 	const pageRoutes = routes.filter((r) => !r.isApiRoute);
-	if (pageRoutes.length > 0) {
-		lines.push("declare module '@timber-js/app/server' {");
-		lines.push("  import type { Routes } from '@timber-js/app'");
-		lines.push("  export function searchParams<R extends keyof Routes>(): Promise<Routes[R]['searchParams']>");
-		lines.push("}");
-		lines.push("");
-	}
 	const dynamicRoutes = routes.filter((r) => r.params.length > 0);
 	if (dynamicRoutes.length > 0 || pageRoutes.length > 0) {
 		lines.push("declare module '@timber-js/app/client' {");
@@ -479,10 +518,10 @@ function formatDeclarationFile(routes, importBase) {
 		lines.push("");
 		if (dynamicRoutes.length > 0) {
 			for (const route of dynamicRoutes) {
-				const paramsType = formatParamsType(route.params);
-				lines.push(`  export function useParams(route: '${route.urlPath}'): ${paramsType}`);
+				const paramsType = formatParamsType(route.params, importBase);
+				lines.push(`  export function useSegmentParams(route: '${route.urlPath}'): ${paramsType}`);
 			}
-			lines.push("  export function useParams(): Record<string, string | string[]>");
+			lines.push("  export function useSegmentParams(): Record<string, string | string[]>");
 			lines.push("");
 		}
 		if (pageRoutes.length > 0) {
@@ -490,33 +529,58 @@ function formatDeclarationFile(routes, importBase) {
 			lines.push("");
 		}
 		if (pageRoutes.length > 0) {
-			lines.push("  // Typed Link props per route");
+			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) {
+function formatParamsType(params, importBase) {
 	if (params.length === 0) return "{}";
-	return `{ ${params.map((p) => `${p.name}: ${p.type}`).join("; ")} }`;
+	return `{ ${params.map((p) => {
+		if (p.codecFilePath) {
+			const absPath = p.codecFilePath.replace(/\.(ts|tsx)$/, "");
+			let importPath;
+			if (importBase) importPath = "./" + relative(importBase, absPath).replace(/\\/g, "/");
+			else importPath = "./" + posix.basename(absPath);
+			const codecType = `(typeof import('${importPath}'))['segmentParams'] extends import('@timber-js/app/segment-params').ParamsDefinition<infer T> ? T[${JSON.stringify(p.name)}] : ${p.type}`;
+			return `${p.name}: ${codecType}`;
+		}
+		return `${p.name}: ${p.type}`;
+	}).join("; ")} }`;
 }
 /**
-* Format the params type for Link props.
+* Format the params 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`.
 *
-* See design/07-routing.md §"Typed params and searchParams on <Link>"
+* Uses DIRECT types (not conditional) to preserve excess property checking.
 */
-function formatLinkParamsType(params) {
+function formatLinkParamsType(params, importBase) {
 	if (params.length === 0) return "{}";
 	return `{ ${params.map((p) => {
+		if (p.codecFilePath) {
+			const absPath = p.codecFilePath.replace(/\.(ts|tsx)$/, "");
+			let importPath;
+			if (importBase) importPath = "./" + relative(importBase, absPath).replace(/\\/g, "/");
+			else importPath = "./" + posix.basename(absPath);
+			const codecType = `(typeof import('${importPath}'))['segmentParams'] extends import('@timber-js/app/segment-params').ParamsDefinition<infer T> ? T[${JSON.stringify(p.name)}] : ${p.type}`;
+			return `${p.name}: ${codecType}`;
+		}
 		const type = p.type === "string" ? "string | number" : p.type;
 		return `${p.name}: ${type}`;
 	}).join("; ")} }`;
@@ -524,17 +588,17 @@ function formatLinkParamsType(params) {
 /**
 * Format the searchParams type for a route entry.
 *
-* When a search-params.ts exists, we reference its inferred type via an import type.
+* When a page.tsx 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.searchParamsAbsPath) {
-		const absPath = route.searchParamsAbsPath.replace(/\.(ts|tsx)$/, "");
+	if (route.hasSearchParams && route.searchParamsPagePath) {
+		const absPath = route.searchParamsPagePath.replace(/\.(ts|tsx)$/, "");
 		let importPath;
 		if (importBase) importPath = "./" + relative(importBase, absPath).replace(/\\/g, "/");
 		else importPath = "./" + posix.basename(absPath);
-		return `(typeof import('${importPath}'))['default'] extends import('@timber-js/app/search-params').SearchParamsDefinition<infer T> ? T : never`;
+		return `(typeof import('${importPath}'))['searchParams'] extends import('@timber-js/app/search-params').SearchParamsDefinition<infer T> ? T : never`;
 	}
 	return "{}";
 }
@@ -557,41 +621,99 @@ function formatUseQueryStatesOverloads(routes, importBase) {
 	return lines;
 }
 /**
-* Generate typed Link overloads.
+* 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("/");
+}
+/** 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 }";
+/**
+* TIM-832: 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.
 *
-* For each page route, we generate a Link function overload that:
-* - Constrains href to the route pattern
-* - Types the params prop based on dynamic segments
-* - Types the searchParams prop based on search-params.ts (if present)
+* 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?: never`);
+	lines.push(`      searchParams?: ${catchAllSearchParams}`);
+	lines.push(`    }): import('react').JSX.Element`);
+	lines.push(`    <H extends string>(`);
+	lines.push(`      props: string extends H`);
+	lines.push(`        ? ${baseProps} & {`);
+	lines.push(`            href: H`);
+	lines.push(`            segmentParams?: Record<string, string | number | string[]>`);
+	lines.push(`            searchParams?: ${catchAllSearchParams}`);
+	lines.push(`          }`);
+	lines.push(`        : never`);
+	lines.push(`    ): import('react').JSX.Element`);
+	lines.push("  }");
+	return lines;
+}
+/**
+* Generate typed per-route Link call signatures via LinkFunction
+* interface merging.
 *
-* Routes without dynamic segments accept href as a literal string with no params.
-* Routes with dynamic segments require a params prop.
+* Each call signature uses DIRECT types (not conditional types) for
+* segmentParams, preserving TypeScript's excess property checking.
+* Interface merging is the only reliable way to add "overloads" via
+* module augmentation — function overloads can't be augmented.
+*
+* TIM-832: this function emits ONLY the per-route block. The catch-all
+* block is emitted separately by `formatLinkCatchAllOverloads` inside a
+* second `declare module` so TS overload ordering reports per-route
+* errors (see `formatDeclarationFile`).
 */
 function formatTypedLinkOverloads(routes, importBase) {
 	const lines = [];
+	const baseProps = LINK_BASE_PROPS_TYPE;
+	lines.push("  interface LinkFunction {");
 	for (const route of routes) {
 		const hasDynamicParams = route.params.length > 0;
-		const paramsType = formatLinkParamsType(route.params);
+		const paramsProp = hasDynamicParams ? `segmentParams: ${formatLinkParamsType(route.params, importBase)}` : "segmentParams?: never";
 		const searchParamsType = route.hasSearchParams ? formatSearchParamsType(route, importBase) : null;
+		const patternSearchParamsProp = searchParamsType ? `searchParams?: Partial<${searchParamsType}>` : "searchParams?: never";
 		if (hasDynamicParams) {
-			const spProp = searchParamsType ? `searchParams?: { definition: SearchParamsDefinition<${searchParamsType}>; values: Partial<${searchParamsType}> }` : `searchParams?: never`;
-			lines.push(`  export function Link(props: Omit<import('react').AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> & {`);
-			lines.push(`    href: '${route.urlPath}'`);
-			lines.push(`    params: ${paramsType}`);
-			lines.push(`    ${spProp}`);
-			lines.push(`    prefetch?: boolean; scroll?: boolean; children?: import('react').ReactNode`);
-			lines.push(`  }): import('react').JSX.Element`);
-		} else {
-			const spProp = searchParamsType ? `searchParams?: { definition: SearchParamsDefinition<${searchParamsType}>; values: Partial<${searchParamsType}> }` : `searchParams?: never`;
-			lines.push(`  export function Link(props: Omit<import('react').AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> & {`);
-			lines.push(`    href: '${route.urlPath}'`);
-			lines.push(`    params?: never`);
-			lines.push(`    ${spProp}`);
-			lines.push(`    prefetch?: boolean; scroll?: boolean; children?: import('react').ReactNode`);
-			lines.push(`  }): import('react').JSX.Element`);
+			const templatePattern = buildResolvedPattern(route);
+			if (templatePattern) {
+				const resolvedSearchParamsProp = searchParamsType ? `searchParams?: { definition: SearchParamsDefinition<${searchParamsType}>; values: Partial<${searchParamsType}> }` : "searchParams?: never";
+				lines.push(`    (props: ${baseProps} & {`);
+				lines.push(`      href: \`${templatePattern}\``);
+				lines.push(`      segmentParams?: never`);
+				lines.push(`      ${resolvedSearchParamsProp}`);
+				lines.push(`    }): import('react').JSX.Element`);
+			}
 		}
+		lines.push(`    (props: ${baseProps} & {`);
+		lines.push(`      href: '${route.urlPath}'`);
+		lines.push(`      ${paramsProp}`);
+		lines.push(`      ${patternSearchParamsProp}`);
+		lines.push(`    }): import('react').JSX.Element`);
 	}
-	lines.push(`  export function Link(props: import('./client/link.js').LinkProps): import('react').JSX.Element`);
+	lines.push("  }");
 	return lines;
 }
 //#endregion
@@ -673,4 +795,4 @@ function computeInterceptedBase(parentUrlPath, marker) {
 //#endregion
 export { DEFAULT_PAGE_EXTENSIONS as a, scanRoutes as i, generateRouteMap as n, INTERCEPTION_MARKERS as o, classifySegment as r, collectInterceptionRewrites as t };
 
-//# sourceMappingURL=interception-BOoWmLUA.js.map
+//# sourceMappingURL=interception-DRlhJWbu.js.map