@timber-js/app 0.2.0-alpha.19 → 0.2.0-alpha.191

package/src/routing/scanner.ts

@@ -18,42 +18,24 @@ import type {
   ScannerConfig,
   InterceptionMarker,
 } from './types.js';
-import { DEFAULT_PAGE_EXTENSIONS, INTERCEPTION_MARKERS } from './types.js';
-import { classifyMetadataRoute, isDynamicMetadataExtension } from '#/server/metadata-routes.js';
-
-/**
- * Pattern matching encoded path delimiters that must be rejected during route discovery.
- * %2F / %2f (forward slash) and %5C / %5c (backslash) can cause route collisions
- * when decoded. See design/13-security.md §"Encoded separators rejected".
- */
-const ENCODED_SEPARATOR_PATTERN = /%(?:2[fF]|5[cC])/;
-
-/**
- * Pattern matching encoded null bytes (%00) that must be rejected.
- * See design/13-security.md §"Null bytes rejected".
- */
-const ENCODED_NULL_PATTERN = /%00/;
+import { classifySegment, effectiveUrlSegment } from './segment-classify.js';
+import { validateInterceptionPlacement, computeInterceptedBase } from './interception.js';
+import { validateRouteGroupCollisions } from './collision-spaces.js';
+import { validateSlotPlacement } from './slot-placement.js';
+import { DEFAULT_PAGE_EXTENSIONS } from './types.js';
+import { classifyMetadataRoute, isDynamicMetadataExtension } from '../server/metadata-routes.js';
+import { swallow } from '../server/logger.js';
+import { ENCODED_SEPARATOR_RE, NULL_BYTE_RE } from '../server/canonicalize.js';
 
 /**
  * File convention names that use pageExtensions (can be .tsx, .ts, .jsx, .js, .mdx, etc.)
  */
 const PAGE_EXT_CONVENTIONS = new Set(['page', 'layout', 'error', 'default', 'denied']);
 
-/**
- * Legacy compat status-code files.
- * Maps legacy file name → HTTP status code for the fallback chain.
- * See design/10-error-handling.md §"Fallback Chain".
- */
-const LEGACY_STATUS_FILES: Record<string, number> = {
-  'not-found': 404,
-  'forbidden': 403,
-  'unauthorized': 401,
-};
-
 /**
  * File convention names that are always .ts/.tsx (never .mdx etc.)
  */
-const FIXED_CONVENTIONS = new Set(['middleware', 'access', 'route', 'prerender', 'search-params']);
+const FIXED_CONVENTIONS = new Set(['middleware', 'access', 'route']);
 
 /**
  * Status-code file patterns:
@@ -83,15 +65,45 @@ export function scanRoutes(appDir: string, config: ScannerConfig = {}): RouteTre
     tree.proxy = proxyFile;
   }
 
+  // Check for global-error.{tsx,ts,jsx,js} at app root.
+  // Tier 2 error page — renders standalone (no layouts) when no segment-level
+  // error file is found. See design/10-error-handling.md §"Tier 2".
+  const globalErrorFile = findPageExtFile(appDir, 'global-error', extSet);
+  if (globalErrorFile) {
+    tree.globalError = globalErrorFile;
+  }
+
   // Scan the root directory's files
   scanSegmentFiles(appDir, tree.root, extSet);
 
   // Scan children recursively
   scanChildren(appDir, tree.root, extSet);
 
+  // Validate: every parallel slot sits where a renderer reaches it. First,
+  // because a slot nested inside another slot never renders, and a collision
+  // reported from inside one would send the author to fix an ambiguity between
+  // two pages that were both already dead.
+  validateSlotPlacement(tree.root);
+
   // Validate: detect route group collisions (different groups producing pages at the same URL)
   validateRouteGroupCollisions(tree.root);
 
+  // Validate: detect duplicate param names in nested dynamic segments
+  // e.g., /[id]/items/[id] — same param name in ancestor and descendant
+  validateDuplicateParamNames(tree.root);
+
+  // Validate: detect same param name used with different bracket forms
+  // e.g., [id] in one route and [...id] in another
+  validateUniqueBracketForms(tree.root);
+
+  // Validate: detect affixed dynamic siblings with equal specificity
+  // e.g., a-[id] and [slug]-b both have prefix+suffix length = 2
+  validateAffixedSiblingConflicts(tree.root);
+
+  // Validate: intercepting routes must be direct children of a parallel slot —
+  // the slot resolver is the only thing that can render one.
+  validateInterceptionPlacement(tree.root);
+
   return tree;
 }
 
@@ -104,106 +116,24 @@ function createSegmentNode(
   urlPath: string,
   paramName?: string,
   interceptionMarker?: InterceptionMarker,
-  interceptedSegmentName?: string
+  interceptedSegmentName?: string,
+  paramPrefix?: string,
+  paramSuffix?: string
 ): SegmentNode {
   return {
     segmentName,
     segmentType,
     urlPath,
     paramName,
+    paramPrefix,
+    paramSuffix,
     interceptionMarker,
     interceptedSegmentName,
     children: [],
-    slots: new Map(),
+    slots: {},
   };
 }
 
-/**
- * Classify a directory name into its segment type.
- */
-export function classifySegment(dirName: string): {
-  type: SegmentType;
-  paramName?: string;
-  interceptionMarker?: InterceptionMarker;
-  interceptedSegmentName?: string;
-} {
-  // Private folder: _name (excluded from routing)
-  if (dirName.startsWith('_')) {
-    return { type: 'private' };
-  }
-
-  // Parallel route slot: @name
-  if (dirName.startsWith('@')) {
-    return { type: 'slot' };
-  }
-
-  // Intercepting routes: (.)name, (..)name, (...)name, (..)(..)name
-  // Check before route groups since intercepting markers also start with (
-  const interception = parseInterceptionMarker(dirName);
-  if (interception) {
-    return {
-      type: 'intercepting',
-      interceptionMarker: interception.marker,
-      interceptedSegmentName: interception.segmentName,
-    };
-  }
-
-  // Route group: (name)
-  if (dirName.startsWith('(') && dirName.endsWith(')')) {
-    return { type: 'group' };
-  }
-
-  // Optional catch-all: [[...name]]
-  if (dirName.startsWith('[[...') && dirName.endsWith(']]')) {
-    const paramName = dirName.slice(5, -2);
-    return { type: 'optional-catch-all', paramName };
-  }
-
-  // Catch-all: [...name]
-  if (dirName.startsWith('[...') && dirName.endsWith(']')) {
-    const paramName = dirName.slice(4, -1);
-    return { type: 'catch-all', paramName };
-  }
-
-  // Dynamic: [name]
-  if (dirName.startsWith('[') && dirName.endsWith(']')) {
-    const paramName = dirName.slice(1, -1);
-    return { type: 'dynamic', paramName };
-  }
-
-  return { type: 'static' };
-}
-
-/**
- * Parse an interception marker from a directory name.
- *
- * Returns the marker and the remaining segment name, or null if not an
- * intercepting route. Markers are checked longest-first to avoid (..)
- * matching before (..)(..).
- *
- * Examples:
- *   "(.)photo"      → { marker: "(.)", segmentName: "photo" }
- *   "(..)feed"      → { marker: "(..)", segmentName: "feed" }
- *   "(...)photos"   → { marker: "(...)", segmentName: "photos" }
- *   "(..)(..)admin" → { marker: "(..)(..)", segmentName: "admin" }
- *   "(marketing)"   → null (route group, not interception)
- */
-function parseInterceptionMarker(
-  dirName: string
-): { marker: InterceptionMarker; segmentName: string } | null {
-  for (const marker of INTERCEPTION_MARKERS) {
-    if (dirName.startsWith(marker)) {
-      const rest = dirName.slice(marker.length);
-      // Must have a segment name after the marker, and the rest must not
-      // be empty or end with ) (which would be a route group like "(auth)")
-      if (rest.length > 0 && !rest.endsWith(')')) {
-        return { marker, segmentName: rest };
-      }
-    }
-  }
-  return null;
-}
-
 /**
  * Compute the URL path for a child segment given its parent's URL path.
  * Route groups, slots, and intercepting routes do NOT add URL depth.
@@ -225,7 +155,8 @@ function scanSegmentFiles(dirPath: string, node: SegmentNode, extSet: Set<string
   let entries: string[];
   try {
     entries = readdirSync(dirPath);
-  } catch {
+  } catch (err) {
+    swallow(err, `scanSegmentFiles: unreadable directory ${dirPath}`, { level: 'warn' });
     return;
   }
 
@@ -244,47 +175,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 'prerender':
-          node.prerender = file;
-          break;
-        case 'search-params':
-          node.searchParams = file;
-          break;
+    // Fixed conventions (middleware, access, route) — 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';
+      const existing = node[key];
+      if (existing) {
+        throwDuplicateConvention(name, existing.filePath, fullPath);
       }
+      node[key] = { filePath: fullPath, extension: ext };
       continue;
     }
 
@@ -292,50 +202,56 @@ function scanSegmentFiles(dirPath: string, node: SegmentNode, extSet: Set<string
     // Recognized regardless of pageExtensions — .json is a data format, not a page extension.
     if (STATUS_CODE_PATTERN.test(name) && ext === 'json') {
       if (!node.jsonStatusFiles) {
-        node.jsonStatusFiles = new Map();
+        node.jsonStatusFiles = {};
       }
-      node.jsonStatusFiles.set(name, { filePath: fullPath, extension: ext });
+      node.jsonStatusFiles[name] = { filePath: fullPath, extension: ext };
       continue;
     }
 
     // Status-code files (401.tsx, 4xx.tsx, 503.tsx, 5xx.tsx)
     if (STATUS_CODE_PATTERN.test(name) && extSet.has(ext)) {
       if (!node.statusFiles) {
-        node.statusFiles = new Map();
+        node.statusFiles = {};
       }
-      node.statusFiles.set(name, { filePath: fullPath, extension: ext });
-      continue;
-    }
-
-    // Legacy compat files (not-found.tsx, forbidden.tsx, unauthorized.tsx)
-    if (name in LEGACY_STATUS_FILES && extSet.has(ext)) {
-      if (!node.legacyStatusFiles) {
-        node.legacyStatusFiles = new Map();
+      const existing = node.statusFiles[name];
+      if (existing) {
+        throwDuplicateConvention(name, existing.filePath, fullPath);
       }
-      node.legacyStatusFiles.set(name, { filePath: fullPath, extension: ext });
+      node.statusFiles[name] = { filePath: fullPath, extension: ext };
       continue;
     }
 
     // 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) {
+      if (!metaInfo.nestable && node.segmentName !== '') {
+        throw new Error(
+          `Build error: '${name}' is a root-only metadata convention and must be in the app root directory.\n` +
+            `  File: ${fullPath}\n` +
+            `  Move this file to the app root (not a route group or nested segment).`
+        );
+      }
       if (!node.metadataRoutes) {
-        node.metadataRoutes = new Map();
+        node.metadataRoutes = {};
       }
-      const existing = node.metadataRoutes.get(name);
+      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) {
-          node.metadataRoutes.set(name, { filePath: fullPath, extension: ext });
+        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 {
-        node.metadataRoutes.set(name, { filePath: fullPath, extension: ext });
+        node.metadataRoutes[name] = { filePath: fullPath, extension: ext };
       }
     }
   }
@@ -351,6 +267,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.
  */
@@ -358,7 +294,8 @@ function scanChildren(dirPath: string, parentNode: SegmentNode, extSet: Set<stri
   let entries: string[];
   try {
     entries = readdirSync(dirPath);
-  } catch {
+  } catch (err) {
+    swallow(err, `scanChildren: unreadable directory ${dirPath}`, { level: 'warn' });
     return;
   }
 
@@ -374,24 +311,31 @@ function scanChildren(dirPath: string, parentNode: SegmentNode, extSet: Set<stri
     // Reject directories with encoded path delimiters or null bytes.
     // These can cause route collisions when decoded at the URL boundary.
     // See design/13-security.md §"Encoded separators rejected" and §"Null bytes rejected".
-    if (ENCODED_SEPARATOR_PATTERN.test(entry)) {
+    if (ENCODED_SEPARATOR_RE.test(entry)) {
       throw new Error(
-        `Build error: directory name contains an encoded path delimiter (%%2F or %%5C).\n` +
+        `Build error: directory name contains an encoded path delimiter (%2F or %5C).\n` +
           `  Directory: ${fullPath}\n` +
           `Encoded separators in directory names cause route collisions when decoded. ` +
           `Rename the directory to remove the encoded delimiter.`
       );
     }
-    if (ENCODED_NULL_PATTERN.test(entry)) {
+    if (NULL_BYTE_RE.test(entry)) {
       throw new Error(
-        `Build error: directory name contains an encoded null byte (%%00).\n` +
+        `Build error: directory name contains an encoded null byte (%00).\n` +
           `  Directory: ${fullPath}\n` +
           `Encoded null bytes in directory names are not allowed. ` +
           `Rename the directory to remove the null byte encoding.`
       );
     }
 
-    const { type, paramName, interceptionMarker, interceptedSegmentName } = classifySegment(entry);
+    const {
+      type,
+      paramName,
+      paramPrefix,
+      paramSuffix,
+      interceptionMarker,
+      interceptedSegmentName,
+    } = classifySegment(entry);
 
     // Skip private folders — underscore-prefixed dirs are excluded from routing
     if (type === 'private') continue;
@@ -403,7 +347,9 @@ function scanChildren(dirPath: string, parentNode: SegmentNode, extSet: Set<stri
       urlPath,
       paramName,
       interceptionMarker,
-      interceptedSegmentName
+      interceptedSegmentName,
+      paramPrefix,
+      paramSuffix
     );
 
     // Scan this segment's files
@@ -412,10 +358,10 @@ function scanChildren(dirPath: string, parentNode: SegmentNode, extSet: Set<stri
     // Recurse into subdirectories
     scanChildren(fullPath, childNode, extSet);
 
-    // Attach to parent: slots go into slots map, everything else is a child
+    // Attach to parent: slots go into slots record, everything else is a child
     if (type === 'slot') {
       const slotName = entry.slice(1); // remove @
-      parentNode.slots.set(slotName, childNode);
+      parentNode.slots[slotName] = childNode;
     } else {
       parentNode.children.push(childNode);
     }
@@ -423,63 +369,245 @@ function scanChildren(dirPath: string, parentNode: SegmentNode, extSet: Set<stri
 }
 
 /**
- * Validate that route groups don't produce conflicting pages/routes at the same URL path.
+ * Validate that no route chain contains duplicate dynamic param names.
  *
- * 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.
+ * Example violation:
+ *   app/[id]/items/[id]/page.tsx — 'id' appears twice in the ancestor chain.
  *
- * 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).
+ * 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 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);
+function validateDuplicateParamNames(root: SegmentNode): void {
+  walkForDuplicateParams(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.
+ * Recursively walk the segment tree, tracking seen param names → segment paths.
+ * Throws on the first duplicate found.
  */
-function collectRoutableLeaves(
+function walkForDuplicateParams(node: SegmentNode, seen: Map<string, string>): void {
+  // Read through the effective identity so an intercepting directory is seen
+  // as the segment it intercepts: the scanner leaves `paramName` unset on
+  // `(.)[id]`, so a validator reading the node directly is blind to a param
+  // the resolver goes on to bind — `@modal/(.)[id]/[id]` would pass here and
+  // then silently overwrite the outer `id` at match time, where the ordinary
+  // `/[id]/[id]` is rejected. See TIM-1288.
+  const { paramName } = effectiveUrlSegment(node);
+
+  // If this node introduces a param name, check for duplicates
+  if (paramName) {
+    const existing = seen.get(paramName);
+    if (existing) {
+      throw new Error(
+        `[timber] Duplicate param name '${paramName}' in route chain.\n` +
+          `  First defined at: ${existing}\n` +
+          `  Duplicate at: ${node.urlPath || '/'}\n` +
+          `  Rename one of the segments to avoid ambiguity.`
+      );
+    }
+    // Add to seen for descendants (use a new Map to avoid polluting siblings)
+    seen = new Map(seen);
+    seen.set(paramName, node.urlPath || '/');
+  }
+
+  // Recurse into children (they inherit the accumulated params)
+  for (const child of node.children) {
+    walkForDuplicateParams(child, seen);
+  }
+
+  // A slot INHERITS the ancestor params rather than starting fresh: a slot
+  // child may not reuse a name its owner already bound
+  // (`app/gallery/[id]/@modal/[id]` is rejected). The copy is so sibling
+  // slots don't see each other's names, not so the chain is reset.
+  //
+  // Whether that rule is right is a separate question — slot params are
+  // merged over the main route's at read time, so a collision is defined
+  // rather than ambiguous — but changing it would change every slot.
+  // Tracked as TIM-1287; do not "fix" this by making the map fresh without
+  // deciding that.
+  for (const slotNode of Object.values(node.slots)) {
+    walkForDuplicateParams(slotNode, new Map(seen));
+  }
+}
+
+/**
+ * Validate that each param name uses a single bracket form across the entire route tree.
+ *
+ * Different bracket forms produce different types:
+ *   [id]      → string
+ *   [...id]   → string[]
+ *   [[...id]] → string[] | undefined
+ *
+ * If the same param name appears with multiple forms, the no-argument
+ * getSegmentParams() / useSegmentParams() return type becomes ambiguous.
+ *
+ * Same name + same form across different routes is fine and expected.
+ */
+function validateUniqueBracketForms(root: SegmentNode): void {
+  const forms = new Map<string, { segmentType: SegmentType; urlPath: string }>();
+  collectBracketForms(root, forms);
+}
+
+function collectBracketForms(
   node: SegmentNode,
-  seen: Map<string, { filePath: string; segmentPath: string }>,
-  segmentPath: string,
-  insideSlot: boolean
+  forms: Map<string, { segmentType: SegmentType; urlPath: string }>
 ): void {
-  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) {
+  // Effective identity, so `(.)[...rest]` is compared as the catch-all it
+  // intercepts rather than skipped as an 'intercepting' node (TIM-1288).
+  const { paramName, segmentType } = effectiveUrlSegment(node);
+
+  if (paramName && segmentType !== 'static' && segmentType !== 'group') {
+    const existing = forms.get(paramName);
+    if (existing && existing.segmentType !== segmentType) {
+      const bracketExamples: Record<string, string> = {
+        'dynamic': `[${paramName}]`,
+        'catch-all': `[...${paramName}]`,
+        'optional-catch-all': `[[...${paramName}]]`,
+      };
+      throw new Error(
+        `[timber] Param name '${paramName}' uses multiple bracket forms.\n` +
+          `  ${bracketExamples[existing.segmentType] ?? existing.segmentType} at: ${existing.urlPath}\n` +
+          `  ${bracketExamples[segmentType] ?? segmentType} at: ${node.urlPath || '/'}\n` +
+          `  Each param name must use a single bracket form across all routes.\n` +
+          `  Rename one of the segments to fix this (e.g., [${paramName}] → [${paramName}Id]).`
+      );
+    }
+    if (!existing) {
+      forms.set(paramName, {
+        segmentType,
+        urlPath: node.urlPath || '/',
+      });
+    }
+  }
+
+  for (const child of node.children) {
+    collectBracketForms(child, forms);
+  }
+  for (const slotNode of Object.values(node.slots)) {
+    collectBracketForms(slotNode, forms);
+  }
+}
+
+/**
+ * Validate that no sibling affixed dynamic segments have equal specificity.
+ *
+ * Among affixed siblings, longer combined prefix+suffix length wins. When two
+ * siblings tie (same total affix length), the router would fall back to
+ * filesystem scan order — which is platform-dependent. This is a build error.
+ *
+ * Route groups are URL-transparent, so affixed segments inside different groups
+ * at the same level still conflict with each other.
+ *
+ * Ambiguity requires the two segments to be candidates for the *same* URL
+ * part, which is narrower than "same parent" once interception is involved:
+ *
+ * - Plain children and intercepting children never compete. They are resolved
+ *   by different walks — `findSlotMatch` matches the slot subtree (where
+ *   `tree-match.ts` ignores intercepting nodes outright) and
+ *   `findInterceptingMatch` builds a synthetic parent holding only
+ *   interceptors.
+ * - Two interceptors compete only at the same anchor. `(.)a-[id]` and
+ *   `(..)[slug]-b` in one slot are based at different URL depths, so no
+ *   pathname reaches both, and `anchorIndex` rejects the one whose base does
+ *   not match the target. Grouping them together would fail the build for a
+ *   pair that can never be ambiguous.
+ *
+ * So candidates are keyed by the position they contend for, then by affix
+ * length. See design/07-routing.md §"Priority" and §"Intercepting Routes".
+ */
+function validateAffixedSiblingConflicts(node: SegmentNode): void {
+  const affixed = collectEffectiveAffixed(node);
+
+  if (affixed.length >= 2) {
+    const byLength = new Map<string, SegmentNode[]>();
+    for (const child of affixed) {
+      // `\0` as the separator, written as the escape rather than a literal
+      // byte: a raw NUL in the source makes git and grep treat this file as
+      // binary. A contention key is a URL path, which cannot contain one, so
+      // the two halves of the key can never run together.
+      const key = `${contentionKey(node, child)}\0${affixLengthOf(child)}`;
+      const group = byLength.get(key);
+      if (group) {
+        group.push(child);
+      } else {
+        byLength.set(key, [child]);
+      }
+    }
+
+    for (const [, group] of byLength) {
+      if (group.length >= 2) {
         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.`
+          `Build error: ambiguous affixed dynamic siblings with equal specificity.\n` +
+            `  Parent: ${node.urlPath || '/'}\n` +
+            `  Segments: ${group.map((s) => s.segmentName).join(', ')}\n` +
+            `  Combined prefix+suffix length: ${affixLengthOf(group[0]!)}\n` +
+            `The router cannot deterministically choose between these — filesystem scan order is platform-dependent.\n` +
+            `Rename one segment to give it a longer or shorter combined affix.`
         );
       }
-      seen.set(node.urlPath, { filePath: routableFile.filePath, segmentPath: currentPath });
     }
   }
 
-  // Recurse into children
   for (const child of node.children) {
-    collectRoutableLeaves(child, seen, currentPath, insideSlot);
+    validateAffixedSiblingConflicts(child);
+  }
+  for (const slotNode of Object.values(node.slots)) {
+    validateAffixedSiblingConflicts(slotNode);
   }
+}
+
+/**
+ * The URL position a child contends for, as a comparable key.
+ *
+ * Plain children contend for the parent's next part. An intercepting child
+ * contends for a part determined by its marker's intercepted base, so two
+ * markers of different depth are simply different positions — and two markers
+ * that compute the *same* base do contend, which is why the key is the base
+ * rather than the marker (`(..)` and `(...)` under `/feed` both base at `/`).
+ *
+ * `groupByInterceptedAnchor` (`routing/interception.ts`) is the canonical
+ * statement of that grouping — it is what the resolver walks and what the
+ * collision validator checks. This computes the same key from the same
+ * `computeInterceptedBase` rather than calling it, because affix ambiguity is
+ * decided per *child* and `collectEffectiveAffixed` looks through route groups,
+ * so the two do not partition the same set of nodes.
+ */
+function contentionKey(parent: SegmentNode, child: SegmentNode): string {
+  if (child.segmentType !== 'intercepting') return 'child';
+  return `intercept:${computeInterceptedBase(parent.urlPath, child.interceptionMarker ?? '(.)')}`;
+}
+
+/** Combined affix length of a node, read through its effective identity. */
+function affixLengthOf(node: SegmentNode): number {
+  const { paramPrefix, paramSuffix } = effectiveUrlSegment(node);
+  return (paramPrefix?.length ?? 0) + (paramSuffix?.length ?? 0);
+}
 
-  // Recurse into slots — each slot is its own parallel route space
-  for (const [, slotNode] of node.slots) {
-    collectRoutableLeaves(slotNode, seen, currentPath, true);
+/**
+ * Collect affixed dynamic segments that are effective children of a node.
+ * Route groups are URL-transparent, so we look through them recursively.
+ *
+ * Segments are read through `effectiveUrlSegment`, so an intercepting
+ * directory counts as the affixed segment it intercepts: `(.)a-[id]` is
+ * `a-[id]`. The proxy the slot resolver builds hands those affixes to
+ * `matchUrlParts`, whose equal-length sort is not stable across equal
+ * specificity — so two intercepting siblings with the same combined affix
+ * length would resolve by filesystem enumeration order, which is precisely
+ * what this validator exists to prevent for ordinary siblings (TIM-1288).
+ */
+function collectEffectiveAffixed(node: SegmentNode): SegmentNode[] {
+  const result: SegmentNode[] = [];
+  for (const child of node.children) {
+    const { segmentType, paramPrefix, paramSuffix } = effectiveUrlSegment(child);
+    if (segmentType === 'dynamic' && (paramPrefix || paramSuffix)) {
+      result.push(child);
+    } else if (segmentType === 'group') {
+      result.push(...collectEffectiveAffixed(child));
+    }
   }
+  return result;
 }
 
 /**
@@ -498,3 +626,25 @@ function findFixedFile(dirPath: string, name: string): RouteFile | undefined {
   }
   return undefined;
 }
+
+/**
+ * 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: string,
+  name: string,
+  extSet: Set<string>
+): RouteFile | undefined {
+  for (const ext of extSet) {
+    const fullPath = join(dirPath, `${name}.${ext}`);
+    try {
+      if (statSync(fullPath).isFile()) {
+        return { filePath: fullPath, extension: ext };
+      }
+    } catch {
+      // File doesn't exist
+    }
+  }
+  return undefined;
+}