@timber-js/app 0.2.0-alpha.146 → 0.2.0-alpha.147

package/dist/server/rsc-entry/error-renderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error-renderer.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/error-renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE/D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAGlE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAYvD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAsHD;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,mBAAmB,EAAE,EAC/B,gBAAgB,EAAE,WAAW,EAAE,EAC/B,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,eAAe,EAAE,OAAO,EACxB,eAAe,EAAE,qBAAqB,EACtC,WAAW,CAAC,EAAE,eAAe,GAC5B,OAAO,CAAC,QAAQ,CAAC,CAwCnB;AAqID;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,OAAO,EACZ,WAAW,EAAE,mBAAmB,EAChC,eAAe,EAAE,OAAO,EACxB,eAAe,EAAE,qBAAqB,GACrC,OAAO,CAAC,QAAQ,CAAC,CAuCnB"}
+{"version":3,"file":"error-renderer.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/error-renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE/D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAGlE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAavD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;CAClB;AA0GD;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,mBAAmB,EAAE,EAC/B,gBAAgB,EAAE,WAAW,EAAE,EAC/B,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,eAAe,EAAE,OAAO,EACxB,eAAe,EAAE,qBAAqB,EACtC,WAAW,CAAC,EAAE,eAAe,GAC5B,OAAO,CAAC,QAAQ,CAAC,CAwCnB;AAqID;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,OAAO,EACZ,WAAW,EAAE,mBAAmB,EAChC,eAAe,EAAE,OAAO,EACxB,eAAe,EAAE,qBAAqB,GACrC,OAAO,CAAC,QAAQ,CAAC,CAuCnB"}

package/dist/server/status-code-resolver.d.ts

@@ -58,6 +58,12 @@ export interface SlotDeniedResolution<TFile> {
     /** How the file was matched. */
     kind: SlotDeniedKind;
 }
+/**
+ * Maps legacy file convention names to their corresponding HTTP status codes.
+ * Only used in the 4xx component fallback chain. Exported so the in-tree
+ * deny chain (deny-boundary.ts) uses the same mapping — see TIM-1081.
+ */
+export declare const LEGACY_FILE_TO_STATUS: Record<string, number>;
 /**
  * Resolve the status-code file to render for a given HTTP status code.
  *

package/dist/server/status-code-resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"status-code-resolver.d.ts","sourceRoot":"","sources":["../../src/server/status-code-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAIvD,4CAA4C;AAC5C,MAAM,MAAM,cAAc,GACtB,OAAO,GACP,UAAU,GACV,QAAQ,GACR,OAAO,CAAC;AAEZ,yDAAyD;AACzD,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,MAAM,CAAC;AAEpD,kEAAkE;AAClE,MAAM,WAAW,oBAAoB,CAAC,KAAK;IACzC,8BAA8B;IAC9B,IAAI,EAAE,KAAK,CAAC;IACZ,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,IAAI,EAAE,cAAc,CAAC;IACrB,8DAA8D;IAC9D,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,0CAA0C;AAC1C,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,SAAS,CAAC;AAElD,8CAA8C;AAC9C,MAAM,WAAW,oBAAoB,CAAC,KAAK;IACzC,0DAA0D;IAC1D,IAAI,EAAE,KAAK,CAAC;IACZ,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,gCAAgC;IAChC,IAAI,EAAE,cAAc,CAAC;CACtB;AA8DD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EACrC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,aAAa,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,EAC3C,MAAM,GAAE,gBAA8B,GACrC,oBAAoB,CAAC,KAAK,CAAC,GAAG,IAAI,CAKpC;AA0FD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EACrC,QAAQ,EAAE,WAAW,CAAC,KAAK,CAAC,GAC3B,oBAAoB,CAAC,KAAK,CAAC,GAAG,IAAI,CAYpC"}
+{"version":3,"file":"status-code-resolver.d.ts","sourceRoot":"","sources":["../../src/server/status-code-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAIvD,4CAA4C;AAC5C,MAAM,MAAM,cAAc,GACtB,OAAO,GACP,UAAU,GACV,QAAQ,GACR,OAAO,CAAC;AAEZ,yDAAyD;AACzD,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,MAAM,CAAC;AAEpD,kEAAkE;AAClE,MAAM,WAAW,oBAAoB,CAAC,KAAK;IACzC,8BAA8B;IAC9B,IAAI,EAAE,KAAK,CAAC;IACZ,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,IAAI,EAAE,cAAc,CAAC;IACrB,8DAA8D;IAC9D,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,0CAA0C;AAC1C,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,SAAS,CAAC;AAElD,8CAA8C;AAC9C,MAAM,WAAW,oBAAoB,CAAC,KAAK;IACzC,0DAA0D;IAC1D,IAAI,EAAE,KAAK,CAAC;IACZ,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,gCAAgC;IAChC,IAAI,EAAE,cAAc,CAAC;CACtB;AAID;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAIxD,CAAC;AAkDF;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EACrC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,aAAa,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,EAC3C,MAAM,GAAE,gBAA8B,GACrC,oBAAoB,CAAC,KAAK,CAAC,GAAG,IAAI,CAKpC;AA0FD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EACrC,QAAQ,EAAE,WAAW,CAAC,KAAK,CAAC,GAC3B,oBAAoB,CAAC,KAAK,CAAC,GAAG,IAAI,CAYpC"}

package/dist/server/utils/mdx-file.d.ts

@@ -0,0 +1,15 @@
+/**
+ * MDX file-path detection shared by error/deny rendering paths.
+ *
+ * MDX status and error files are server components — they cannot be passed
+ * as function props across the RSC→client boundary (e.g. to
+ * TimberErrorBoundary or ErrorReconstituter) and must be pre-rendered as
+ * elements with plain props instead.
+ *
+ * See design/10-error-handling.md §"Status-Code File Variants".
+ */
+/**
+ * Check if a file path ends with an MDX/markdown extension.
+ */
+export declare function isMdxFilePath(filePath: string): boolean;
+//# sourceMappingURL=mdx-file.d.ts.map

package/dist/server/utils/mdx-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mdx-file.d.ts","sourceRoot":"","sources":["../../../src/server/utils/mdx-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH;;GAEG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAIvD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.146",
+  "version": "0.2.0-alpha.147",
   "description": "Vite-native React framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",
@@ -163,4 +163,4 @@
   "engines": {
     "node": ">=22.12.0"
   }
-}
+}

package/src/client/error-boundary.tsx

@@ -255,7 +255,21 @@ export class TimberErrorBoundary extends Component<
 
     // Render the fallback component with the right props shape.
     if (parsed?.type === 'deny') {
+      // Status-code file boundaries (404.tsx, 4xx.tsx, …) get the documented
+      // 4xx props. error.tsx boundaries (no status filter) get their
+      // documented { error, digest, reset } contract — plus the deny extras
+      // for dual-shape implementations. Without the error prop, an error.tsx
+      // reading error.message crashes on deny fall-through. See TIM-1081.
+      if (this.props.status != null) {
+        return createElement(this.props.fallbackComponent as never, {
+          status: parsed.status,
+          dangerouslyPassData: parsed.data,
+        });
+      }
       return createElement(this.props.fallbackComponent as never, {
+        error,
+        digest: null,
+        reset: this.reset,
         status: parsed.status,
         dangerouslyPassData: parsed.data,
       });

package/src/client/error-reconstituter.tsx

@@ -33,6 +33,9 @@ export interface SerializableError {
  * - digest: plain JSON or null
  * - reset: undefined (only meaningful on client after boundary catch)
  * - component: client module reference (RSC Flight serializes as opaque ref)
+ * - status / dangerouslyPassData: set only when error.tsx serves a deny()
+ *   as the last entry in the 4xx fallback chain — forwarded so dual-shape
+ *   error.tsx implementations can branch on the deny status (TIM-1081)
  */
 interface ErrorReconstituterProps {
   error: SerializableError;
@@ -42,7 +45,11 @@ interface ErrorReconstituterProps {
     error: Error;
     digest: { code: string; data: unknown } | null;
     reset: (() => void) | undefined;
+    status?: number;
+    dangerouslyPassData?: unknown;
   }>;
+  status?: number;
+  dangerouslyPassData?: unknown;
 }
 
 /**
@@ -54,6 +61,8 @@ export function ErrorReconstituter({
   digest,
   reset,
   component,
+  status,
+  dangerouslyPassData,
 }: ErrorReconstituterProps): ReactNode {
   // Reconstitute a real Error so instanceof checks work in user code
   const error = Object.assign(new Error(serialized.message), {
@@ -61,5 +70,10 @@ export function ErrorReconstituter({
     ...(serialized.stack != null ? { stack: serialized.stack } : {}),
   });
 
-  return createElement(component, { error, digest, reset });
+  return createElement(component, {
+    error,
+    digest,
+    reset,
+    ...(status != null ? { status, dangerouslyPassData } : {}),
+  });
 }

package/src/routing/codegen-types.ts

@@ -21,6 +21,10 @@ export interface RouteEntry {
   searchParamsPagePath?: string;
   /** Whether this is an API route (route.ts) vs page route */
   isApiRoute: boolean;
+  /** Whether this entry lives inside a parallel slot (@name). Slot entries
+   *  share their parent's urlPath — urlPath-keyed emissions dedupe them,
+   *  preferring the non-slot entry. segmentPath-keyed emissions keep all. */
+  isSlotRoute?: boolean;
   /** Whether a global schema (app/schema.ts) exists for this app */
   hasSchema?: boolean;
 }

package/src/routing/codegen.ts

@@ -48,7 +48,7 @@ export function generateRouteMap(tree: RouteTree, options: CodegenOptions = {}):
   const hasSchema = options.hasSchema ?? detectSchema(options.appDir);
 
   const routes: RouteEntry[] = [];
-  collectRoutes(tree.root, [], [], '', routes, hasSchema);
+  collectRoutes(tree.root, [], [], '', routes, hasSchema, false);
 
   // Sort routes alphabetically for deterministic output
   routes.sort((a, b) => a.urlPath.localeCompare(b.urlPath));
@@ -82,7 +82,8 @@ function collectRoutes(
   ancestorParamsFiles: string[],
   parentTreePath: string,
   routes: RouteEntry[],
-  hasSchema: boolean
+  hasSchema: boolean,
+  insideSlot: boolean
 ): void {
   // Build the tree path (includes groups, slots — uniquely identifies this segment).
   // Root node has empty segmentName, producing treePath = ''.
@@ -156,6 +157,7 @@ function collectRoutes(
       params: resolvedParams,
       hasSearchParams: false,
       isApiRoute,
+      isSlotRoute: insideSlot,
       hasSchema,
     };
 
@@ -175,15 +177,63 @@ function collectRoutes(
 
   // Recurse into children
   for (const child of node.children) {
-    collectRoutes(child, params, nextAncestorFiles, treePath, routes, hasSchema);
+    collectRoutes(child, params, nextAncestorFiles, treePath, routes, hasSchema, insideSlot);
   }
 
   // Recurse into slots (they share the parent's URL path, but may have their own pages)
   for (const slot of Object.values(node.slots)) {
-    collectRoutes(slot, params, nextAncestorFiles, treePath, routes, hasSchema);
+    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: RouteEntry[]): RouteEntry[] {
+  const byPath = new Map<string, RouteEntry>();
+  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;
+    const routeWins =
+      (existing.isSlotRoute && !route.isSlotRoute) ||
+      (!!existing.isSlotRoute === !!route.isSlotRoute &&
+        route.segmentPath.localeCompare(existing.segmentPath) < 0);
+    if (routeWins) {
+      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.
  */
@@ -366,10 +416,14 @@ function formatDeclarationFile(
     lines.push('');
   }
 
+  // urlPath-keyed emissions use the deduped list (slot pages share their
+  // parent's urlPath); segmentPath-keyed emissions below keep all entries.
+  const uniqueByUrlPath = dedupeRoutesByUrlPath(routes);
+
   lines.push("declare module '@timber-js/app' {");
   lines.push('  interface Routes {');
 
-  for (const route of routes) {
+  for (const route of uniqueByUrlPath) {
     const paramsType = formatParamsType(route.params, importBase, hasSchema);
     const searchParamsType = formatSearchParamsType(route, importBase);
 
@@ -393,7 +447,10 @@ function formatDeclarationFile(
   lines.push('}');
   lines.push('');
 
-  const pageRoutes = routes.filter((r) => !r.isApiRoute);
+  // useQueryStates + typed Link are urlPath-keyed → deduped list.
+  const pageRoutes = uniqueByUrlPath.filter((r) => !r.isApiRoute);
+  // getSegmentParams / useSegmentParams are segmentPath-keyed → full list,
+  // so slot segments keep their own typed overloads.
   const dynamicRoutes = routes.filter((r) => r.params.length > 0);
 
   // Generate @timber-js/app/server augmentation — typed getSegmentParams

package/src/routing/scanner.ts

@@ -177,44 +177,26 @@ function scanSegmentFiles(dirPath: string, node: SegmentNode, extSet: Set<string
 
     // Page-extension conventions (page, layout, error, default, denied)
     if (PAGE_EXT_CONVENTIONS.has(name) && extSet.has(ext)) {
-      const file: RouteFile = { filePath: fullPath, extension: ext };
-      switch (name) {
-        case 'page':
-          node.page = file;
-          break;
-        case 'layout':
-          node.layout = file;
-          break;
-        case 'error':
-          node.error = file;
-          break;
-        case 'default':
-          node.default = file;
-          break;
-        case 'denied':
-          node.denied = file;
-          break;
+      const key = name as 'page' | 'layout' | 'error' | 'default' | 'denied';
+      const existing = node[key];
+      if (existing) {
+        throwDuplicateConvention(name, existing.filePath, fullPath);
       }
+      node[key] = { filePath: fullPath, extension: ext };
       continue;
     }
 
-    // Fixed conventions (middleware, access, route) — always .ts or .tsx
-    if (FIXED_CONVENTIONS.has(name) && /\.?[jt]sx?$/.test(ext)) {
-      const file: RouteFile = { filePath: fullPath, extension: ext };
-      switch (name) {
-        case 'middleware':
-          node.middleware = file;
-          break;
-        case 'access':
-          node.access = file;
-          break;
-        case 'route':
-          node.route = file;
-          break;
-        case 'params':
-          node.params = file;
-          break;
+    // Fixed conventions (middleware, access, route, params) — only
+    // .ts/.tsx/.js/.jsx, never pageExtensions like .mdx. The regex is
+    // anchored: mts/cts/mjs/cjs (and stray tail matches like `.foots`)
+    // are NOT recognized. See design/07-routing.md §"Page Extensions".
+    if (FIXED_CONVENTIONS.has(name) && /^[jt]sx?$/.test(ext)) {
+      const key = name as 'middleware' | 'access' | 'route' | 'params';
+      const existing = node[key];
+      if (existing) {
+        throwDuplicateConvention(name, existing.filePath, fullPath);
       }
+      node[key] = { filePath: fullPath, extension: ext };
       continue;
     }
 
@@ -233,6 +215,10 @@ function scanSegmentFiles(dirPath: string, node: SegmentNode, extSet: Set<string
       if (!node.statusFiles) {
         node.statusFiles = {};
       }
+      const existing = node.statusFiles[name];
+      if (existing) {
+        throwDuplicateConvention(name, existing.filePath, fullPath);
+      }
       node.statusFiles[name] = { filePath: fullPath, extension: ext };
       continue;
     }
@@ -242,6 +228,10 @@ function scanSegmentFiles(dirPath: string, node: SegmentNode, extSet: Set<string
       if (!node.legacyStatusFiles) {
         node.legacyStatusFiles = {};
       }
+      const existing = node.legacyStatusFiles[name];
+      if (existing) {
+        throwDuplicateConvention(name, existing.filePath, fullPath);
+      }
       node.legacyStatusFiles[name] = { filePath: fullPath, extension: ext };
       continue;
     }
@@ -249,6 +239,8 @@ function scanSegmentFiles(dirPath: string, node: SegmentNode, extSet: Set<string
     // Metadata route files (sitemap.ts, robots.ts, icon.tsx, opengraph-image.tsx, etc.)
     // Both static (.xml, .txt, .png, .ico, etc.) and dynamic (.ts, .tsx) files are recognized.
     // When both exist for the same base name, dynamic takes precedence.
+    // Two files of the SAME kind (static+static or dynamic+dynamic) are a
+    // build error — picking one by readdir order is platform-dependent.
     // See design/16-metadata.md §"Metadata Routes"
     const metaInfo = classifyMetadataRoute(entry);
     if (metaInfo) {
@@ -257,11 +249,13 @@ function scanSegmentFiles(dirPath: string, node: SegmentNode, extSet: Set<string
       }
       const existing = node.metadataRoutes[name];
       if (existing) {
-        // Dynamic > static precedence: only overwrite if the new file is dynamic
-        // or the existing file is static (dynamic always wins).
         const existingIsDynamic = isDynamicMetadataExtension(name, existing.extension);
         const newIsDynamic = isDynamicMetadataExtension(name, ext);
-        if (newIsDynamic || !existingIsDynamic) {
+        if (existingIsDynamic === newIsDynamic) {
+          throwDuplicateConvention(name, existing.filePath, fullPath);
+        }
+        // Dynamic > static precedence: overwrite only when the new file is dynamic.
+        if (newIsDynamic) {
           node.metadataRoutes[name] = { filePath: fullPath, extension: ext };
         }
       } else {
@@ -281,6 +275,26 @@ function scanSegmentFiles(dirPath: string, node: SegmentNode, extSet: Set<string
   }
 }
 
+/**
+ * Throw a build error for two files claiming the same convention slot in
+ * one segment (e.g. page.tsx + page.jsx). Which file readdir returns first
+ * is platform-dependent (APFS sorts entries, ext4 does not) — silently
+ * picking one would let macOS dev and Linux CI serve different
+ * implementations of the same route.
+ */
+function throwDuplicateConvention(
+  convention: string,
+  firstPath: string,
+  secondPath: string
+): never {
+  throw new Error(
+    `Build error: duplicate '${convention}' files in the same route segment.\n` +
+      `  File 1: ${firstPath}\n` +
+      `  File 2: ${secondPath}\n` +
+      `Each segment may define '${convention}' at most once. Remove one of the files.`
+  );
+}
+
 /**
  * Recursively scan child directories and build the segment tree.
  */
@@ -359,57 +373,60 @@ function scanChildren(dirPath: string, parentNode: SegmentNode, extSet: Set<stri
  * Two route groups like (auth)/login/page.tsx and (marketing)/login/page.tsx both claim
  * /login — the scanner must detect and reject this at build time.
  *
- * Parallel slots are excluded from collision detection — they intentionally coexist at
- * the same URL path as their parent (that's the whole point of parallel routes).
+ * Each parallel slot is validated as its OWN collision space: a slot's pages
+ * intentionally share URL paths with the parent tree (that's the point of
+ * parallel routes), but two route groups INSIDE one slot claiming the same
+ * URL — e.g. @side/(a)/x/page.tsx + @side/(b)/x/page.tsx — still collide.
  */
 function validateRouteGroupCollisions(root: SegmentNode): void {
   // Map from urlPath → { filePath, source } for the first page/route seen at that path
-  const seen = new Map<string, { filePath: string; segmentPath: string }>();
-  collectRoutableLeaves(root, seen, '', false);
+  collectRoutableLeaves(root, new Map(), '');
 }
 
 /**
  * Walk the segment tree and collect all routable leaves (page or route files),
- * throwing on collision. Slots are tracked in their own collision space since
- * they are parallel routes that intentionally share URL paths with their parent.
+ * throwing on collision. Each slot recurses with a FRESH collision map —
+ * slots are parallel routes that intentionally share URL paths with their
+ * parent tree, but collisions within a single slot are real errors.
  */
 function collectRoutableLeaves(
   node: SegmentNode,
   seen: Map<string, { filePath: string; segmentPath: string }>,
-  segmentPath: string,
-  insideSlot: boolean
+  segmentPath: string
 ): void {
+  // Intercepting routes are resolved by the slot resolver, not URL matching,
+  // and their computed urlPaths intentionally mirror other routes (e.g. two
+  // interceptors in one slot both produce /gallery/[id]). Skip them entirely.
+  if (node.segmentType === 'intercepting') return;
+
   const currentPath = segmentPath
     ? `${segmentPath}/${node.segmentName}`
     : node.segmentName || '(root)';
 
-  // Only check collisions for non-slot pages — slots intentionally share URL paths
-  if (!insideSlot) {
-    const routableFile = node.page ?? node.route;
-    if (routableFile) {
-      const existing = seen.get(node.urlPath);
-      if (existing) {
-        throw new Error(
-          `Build error: route collision — multiple route groups produce a page/route at the same URL path.\n` +
-            `  URL path: ${node.urlPath}\n` +
-            `  File 1:   ${existing.filePath} (via ${existing.segmentPath})\n` +
-            `  File 2:   ${routableFile.filePath} (via ${currentPath})\n` +
-            `Each URL path must map to exactly one page or route handler. ` +
-            `Rename or move one of the conflicting files.`
-        );
-      }
-      seen.set(node.urlPath, { filePath: routableFile.filePath, segmentPath: currentPath });
+  const routableFile = node.page ?? node.route;
+  if (routableFile) {
+    const existing = seen.get(node.urlPath);
+    if (existing) {
+      throw new Error(
+        `Build error: route collision — multiple route groups produce a page/route at the same URL path.\n` +
+          `  URL path: ${node.urlPath}\n` +
+          `  File 1:   ${existing.filePath} (via ${existing.segmentPath})\n` +
+          `  File 2:   ${routableFile.filePath} (via ${currentPath})\n` +
+          `Each URL path must map to exactly one page or route handler. ` +
+          `Rename or move one of the conflicting files.`
+      );
     }
+    seen.set(node.urlPath, { filePath: routableFile.filePath, segmentPath: currentPath });
   }
 
   // Recurse into children
   for (const child of node.children) {
-    collectRoutableLeaves(child, seen, currentPath, insideSlot);
+    collectRoutableLeaves(child, seen, currentPath);
   }
 
-  // Recurse into slots — each slot is its own parallel route space
+  // Recurse into slots — each slot gets a fresh map (its own collision space)
   for (const slotNode of Object.values(node.slots)) {
-    collectRoutableLeaves(slotNode, seen, currentPath, true);
+    collectRoutableLeaves(slotNode, new Map(), currentPath);
   }
 }