@timber-js/app 0.2.0-alpha.185 → 0.2.0-alpha.187

package/src/routing/link-codegen.ts

@@ -24,13 +24,24 @@
  */
 
 import type { ParamEntry, RouteEntry } from './codegen-types.js';
-import {
-  buildCodecChainType,
-  buildSchemaParamType,
-  formatSearchParamsType,
-} from './codegen-shared.js';
+import { buildSchemaParamType } from './codegen-shared.js';
 import { classifyUrlSegment } from './segment-classify.js';
 
+/**
+ * The `searchParams` prop type, emitted identically on every Link variant
+ * — per-route pattern, resolved template, and catch-all.
+ *
+ * TIM-1343: there is no per-route narrowing any more. `params.ts` is gone,
+ * so codegen has no definition to read a `SearchParamsDefinition<T>` from.
+ * Type safety moved to the value's construction site instead: callers write
+ * `definition.buildSearchParams({ ... })`, which checks `Partial<T>` there
+ * and returns a query STRING — the only shape that survives the RSC Flight
+ * boundary. A plain record is the uncodec'd escape hatch. See `client/link.tsx` §"searchParams prop shapes".
+ *
+ * Declared once so the three emission sites cannot drift apart.
+ */
+export const SEARCH_PARAMS_PROP_TYPE = 'string | Record<string, unknown>';
+
 /** Shared Link base-props type literal used in every emitted call signature. */
 export const 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 }";
@@ -71,23 +82,18 @@ export function buildResolvedPattern(route: RouteEntry): string | null {
  * (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.
+ * With a global schema, the schema codec's inferred type wins. Without
+ * one, a URL segment is a raw string (widened to string | number for
+ * Link convenience) — per-segment codec chains were deleted in TIM-1342.
  */
-export function formatLinkParamsType(
-  params: ParamEntry[],
-  importBase?: string,
-  hasSchema?: boolean
-): string {
+export function formatLinkParamsType(params: ParamEntry[], hasSchema?: boolean): string {
   if (params.length === 0) {
     return '{}';
   }
 
   const fields = params.map((p) => {
     const fallback = p.type === 'string' ? 'string | number' : p.type;
-    const codecType = hasSchema
-      ? buildSchemaParamType(p, fallback)
-      : buildCodecChainType(p, importBase, fallback);
+    const codecType = hasSchema ? buildSchemaParamType(p, fallback) : fallback;
     return `${p.name}: ${codecType}`;
   });
   return `{ ${fields.join('; ')} }`;
@@ -109,15 +115,7 @@ export function formatLinkCatchAllOverloads(): string[] {
   const lines: string[] = [];
   const baseProps = LINK_BASE_PROPS_TYPE;
 
-  // TIM-830: the catch-all signatures accept EITHER the legacy
-  // `{ definition, values }` wrapper OR a flat `Record<string, unknown>`
-  // values object. External/computed hrefs can't be looked up in the
-  // runtime registry, so the wrapped form is still the reliable path;
-  // the flat form is kept permissive for callers migrating from typed-
-  // route hrefs to computed strings. `resolveHref` discriminates at
-  // runtime via the presence of a `definition` key.
-  const catchAllSearchParams =
-    '{ definition: SearchParamsDefinition<Record<string, unknown>>; values: Record<string, unknown> } | Record<string, unknown>';
+  const catchAllSearchParams = SEARCH_PARAMS_PROP_TYPE;
 
   // ExternalHref inlined here rather than referenced as an exported
   // alias so the generated .d.ts stands alone without source imports.
@@ -207,11 +205,7 @@ export function formatLinkCatchAllOverloads(): string[] {
  * so the resolved-template-vs-pattern ordering reduces to placing the
  * pattern variant before the resolved-template variant inside the union.
  */
-export function formatTypedLinkOverloads(
-  routes: RouteEntry[],
-  importBase?: string,
-  hasSchema?: boolean
-): string[] {
+export function formatTypedLinkOverloads(routes: RouteEntry[], hasSchema?: boolean): string[] {
   const lines: string[] = [];
   const baseProps = LINK_BASE_PROPS_TYPE;
 
@@ -234,52 +228,25 @@ export function formatTypedLinkOverloads(
     // segmentParams. `Record<string, unknown>` keeps generic spreads
     // compiling and gives a readable error if a non-object is passed.
     const paramsProp = hasDynamicParams
-      ? `segmentParams: ${formatLinkParamsType(route.params, importBase, hasSchema)}`
+      ? `segmentParams: ${formatLinkParamsType(route.params, hasSchema)}`
       : 'segmentParams?: Record<string, unknown>';
 
-    const searchParamsType = route.hasSearchParams
-      ? formatSearchParamsType(route, importBase)
-      : null;
-    // TIM-830: pattern href uses the FLAT `Partial<T>` shape — the
-    // runtime registry is keyed by the un-interpolated pattern.
-    //
-    // TIM-833: when the route has NO searchParams definition, use
-    // `Record<string, unknown>` (open shape) instead of
-    // `Record<string, never>` so generic `LinkProps`-spreading wrappers
-    // compile. The trade-off vs the original TIM-835 strict shape is
-    // that excess searchParams keys on a no-def route no longer raise
-    // a type error — but those keys are runtime no-ops anyway, and
-    // wrapper compatibility is the more common pain point. Routes WITH
-    // a searchParams definition still get strict `Partial<T>` typing.
-    const patternSearchParamsProp = searchParamsType
-      ? `searchParams?: Partial<${searchParamsType}>`
-      : 'searchParams?: Record<string, unknown>';
+    // TIM-1343: searchParams is no longer typed per-route. There is no
+    // convention file to read a definition from, so codegen has nothing to
+    // narrow with — the value is either a URLSearchParams built by
+    // `definition.buildSearchParams()` (which type-checks its own
+    // `Partial<T>` at that call) or a plain String()-coerced record.
+    const searchParamsProp = `searchParams?: ${SEARCH_PARAMS_PROP_TYPE}`;
 
     // Pattern variant FIRST (more specific).
     variants.push(
-      `${baseProps} & { href: '${route.urlPath}'; ${paramsProp}; ${patternSearchParamsProp} }`
+      `${baseProps} & { href: '${route.urlPath}'; ${paramsProp}; ${searchParamsProp} }`
     );
 
     // Resolved-template variant SECOND (looser, matches interpolated hrefs).
     if (hasDynamicParams) {
       const templatePattern = buildResolvedPattern(route);
       if (templatePattern) {
-        // TIM-830: resolved-template href keeps the WRAPPED
-        // `{ definition, values }` shape — the registry can't be looked
-        // up by an already-interpolated href.
-        //
-        // TIM-833: searchParams falls back to `Record<string, unknown>`
-        // (was `Record<string, never>`) when the route has no
-        // definition, mirroring the pattern-variant change above. The
-        // resolved-template `segmentParams` is intentionally KEPT as
-        // `Record<string, never>` below to preserve TIM-835's
-        // pattern-variant typo detection: loosening segmentParams here
-        // would let the resolved-template variant shadow the pattern
-        // variant on literal pattern hrefs and silently swallow keyed
-        // typos like `<Link href="/[id]" segmentParams={{ idz: 1 }} />`.
-        const resolvedSearchParamsProp = searchParamsType
-          ? `searchParams?: { definition: SearchParamsDefinition<${searchParamsType}>; values: Partial<${searchParamsType}> }`
-          : 'searchParams?: Record<string, unknown>';
         // TIM-835: `Record<string, never>` for segmentParams forbids ANY
         // provided keys on the resolved-template variant. Without this,
         // the resolved-template would shadow the pattern variant for
@@ -288,7 +255,7 @@ export function formatTypedLinkOverloads(
         // and the looser variant would silently swallow segmentParams
         // type errors.
         variants.push(
-          `${baseProps} & { href: \`${templatePattern}\`; segmentParams?: Record<string, never>; ${resolvedSearchParamsProp} }`
+          `${baseProps} & { href: \`${templatePattern}\`; segmentParams?: Record<string, never>; ${searchParamsProp} }`
         );
       }
     }

package/src/routing/manifest-codegen.ts

@@ -1,6 +1,6 @@
 /**
  * Route manifest codegen — generates virtual module source for the route
- * manifest, search-params registry, and global schema.
+ * manifest and the global schema loader.
  *
  * Extracted from plugins/routing.ts to keep it under the 500-line budget.
  * See design/18-build-system.md §"Virtual Modules".
@@ -11,7 +11,6 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { collectInterceptionRewrites } from './interception.js';
-import { fileHasExport } from './export-detect.js';
 import type { RouteTree, SegmentNode, RouteFile } from './types.js';
 
 // ── Single-file conventions ─────────────────────────────────────────────
@@ -26,7 +25,6 @@ const SINGLE_FILE_KEYS = [
   'error',
   'default',
   'denied',
-  'params',
 ] as const;
 
 // ── Record-shaped conventions ───────────────────────────────────────────
@@ -107,10 +105,6 @@ export function generateManifestModule(tree: RouteTree, viteRoot: string): strin
       }
     }
 
-    // searchParams is now a named export from page.tsx, not a separate file.
-    // The page module's searchParams export is loaded via the page's lazy import.
-    // Runtime registration happens in the route loader using the page module.
-
     // Record-shaped conventions — table-driven
     for (const key of RECORD_FILE_KEYS) {
       const record = node[key];
@@ -160,11 +154,13 @@ export function generateManifestModule(tree: RouteTree, viteRoot: string): strin
     globalErrorLine = `  globalError: { load: ${v}, filePath: ${JSON.stringify(tree.globalError.filePath)} },`;
   }
 
+  // Serialize the rewrite objects wholesale — an explicit field list here
+  // silently drops any field added to InterceptionRewrite, and the guard that
+  // reads it would then fall back to matching too broadly. InterceptionRewrite
+  // is plain JSON data by construction (no file references, no functions).
   const rewrites = collectInterceptionRewrites(tree.root);
   const rewritesLine =
-    rewrites.length > 0
-      ? `  interceptionRewrites: ${JSON.stringify(rewrites.map((r) => ({ interceptedPattern: r.interceptedPattern, interceptingPrefix: r.interceptingPrefix })))},`
-      : '';
+    rewrites.length > 0 ? `  interceptionRewrites: ${JSON.stringify(rewrites)},` : '';
 
   const code = [
     '// Auto-generated route manifest — do not edit.',
@@ -188,58 +184,6 @@ export function generateManifestModule(tree: RouteTree, viteRoot: string): strin
   return code;
 }
 
-// ── Search-params registry ──────────────────────────────────────────────
-
-/**
- * Walk the route tree and collect every page that exports a
- * `searchParams` definition, then emit a module that statically imports
- * each export and registers it into the shared search-params registry.
- */
-export function generateSearchParamsRegistryModule(tree: RouteTree): string {
-  const entries: Array<{ urlPath: string; filePath: string }> = [];
-
-  function walk(node: SegmentNode): void {
-    if (node.page) {
-      if (node.params && fileHasSearchParamsExport(node.params.filePath)) {
-        entries.push({ urlPath: node.urlPath, filePath: node.params.filePath });
-      } else if (fileHasSearchParamsExport(node.page.filePath)) {
-        entries.push({ urlPath: node.urlPath, filePath: node.page.filePath });
-      }
-    }
-    for (const child of node.children) walk(child);
-    for (const slot of Object.values(node.slots)) walk(slot);
-  }
-  walk(tree.root);
-
-  entries.sort((a, b) => a.urlPath.localeCompare(b.urlPath));
-
-  const lines: string[] = [];
-  lines.push('// Auto-generated search-params registry — do not edit.');
-  lines.push('// Generated by timber-routing plugin (TIM-830).');
-  lines.push('');
-  lines.push("import { registerSearchParams } from '@timber-js/app/search-params';");
-  lines.push('');
-
-  entries.forEach((entry, i) => {
-    lines.push(`import { searchParams as r${i} } from ${JSON.stringify(entry.filePath)};`);
-  });
-  lines.push('');
-
-  entries.forEach((entry, i) => {
-    lines.push(`registerSearchParams(${JSON.stringify(entry.urlPath)}, r${i});`);
-  });
-  lines.push('');
-
-  lines.push('export {};');
-  lines.push('');
-
-  return lines.join('\n');
-}
-
-function fileHasSearchParamsExport(filePath: string): boolean {
-  return fileHasExport(filePath, 'searchParams');
-}
-
 // ── Schema module ───────────────────────────────────────────────────────
 
 /**

package/src/routing/scanner.ts

@@ -18,7 +18,10 @@ import type {
   ScannerConfig,
   InterceptionMarker,
 } from './types.js';
-import { classifySegment } from './segment-classify.js';
+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';
@@ -32,7 +35,7 @@ const PAGE_EXT_CONVENTIONS = new Set(['page', 'layout', 'error', 'default', 'den
 /**
  * File convention names that are always .ts/.tsx (never .mdx etc.)
  */
-const FIXED_CONVENTIONS = new Set(['middleware', 'access', 'route', 'params']);
+const FIXED_CONVENTIONS = new Set(['middleware', 'access', 'route']);
 
 /**
  * Status-code file patterns:
@@ -76,6 +79,12 @@ export function scanRoutes(appDir: string, config: ScannerConfig = {}): RouteTre
   // 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);
 
@@ -91,6 +100,10 @@ export function scanRoutes(appDir: string, config: ScannerConfig = {}): RouteTre
   // 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;
 }
 
@@ -171,12 +184,12 @@ function scanSegmentFiles(dirPath: string, node: SegmentNode, extSet: Set<string
       continue;
     }
 
-    // Fixed conventions (middleware, access, route, params) — only
+    // 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' | 'params';
+      const key = name as 'middleware' | 'access' | 'route';
       const existing = node[key];
       if (existing) {
         throwDuplicateConvention(name, existing.filePath, fullPath);
@@ -355,69 +368,6 @@ function scanChildren(dirPath: string, parentNode: SegmentNode, extSet: Set<stri
   }
 }
 
-/**
- * Validate that route groups don't produce conflicting pages/routes at the same URL path.
- *
- * 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.
- *
- * 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
-  collectRoutableLeaves(root, new Map(), '');
-}
-
-/**
- * Walk the segment tree and collect all routable leaves (page or route files),
- * 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
-): 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)';
-
-  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);
-  }
-
-  // Recurse into slots — each slot gets a fresh map (its own collision space)
-  for (const slotNode of Object.values(node.slots)) {
-    collectRoutableLeaves(slotNode, new Map(), currentPath);
-  }
-}
-
 /**
  * Validate that no route chain contains duplicate dynamic param names.
  *
@@ -438,12 +388,20 @@ function validateDuplicateParamNames(root: SegmentNode): void {
  * Throws on the first duplicate found.
  */
 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 (node.paramName) {
-    const existing = seen.get(node.paramName);
+  if (paramName) {
+    const existing = seen.get(paramName);
     if (existing) {
       throw new Error(
-        `[timber] Duplicate param name '${node.paramName}' in route chain.\n` +
+        `[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.`
@@ -451,7 +409,7 @@ function walkForDuplicateParams(node: SegmentNode, seen: Map<string, string>): v
     }
     // Add to seen for descendants (use a new Map to avoid polluting siblings)
     seen = new Map(seen);
-    seen.set(node.paramName, node.urlPath || '/');
+    seen.set(paramName, node.urlPath || '/');
   }
 
   // Recurse into children (they inherit the accumulated params)
@@ -459,8 +417,16 @@ function walkForDuplicateParams(node: SegmentNode, seen: Map<string, string>): v
     walkForDuplicateParams(child, seen);
   }
 
-  // Slots are independent parallel routes — start fresh param tracking
-  // (a slot's params don't conflict with the main route's params)
+  // 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));
   }
@@ -488,25 +454,29 @@ function collectBracketForms(
   node: SegmentNode,
   forms: Map<string, { segmentType: SegmentType; urlPath: string }>
 ): void {
-  if (node.paramName && node.segmentType !== 'static' && node.segmentType !== 'group') {
-    const existing = forms.get(node.paramName);
-    if (existing && existing.segmentType !== node.segmentType) {
+  // 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': `[${node.paramName}]`,
-        'catch-all': `[...${node.paramName}]`,
-        'optional-catch-all': `[[...${node.paramName}]]`,
+        'dynamic': `[${paramName}]`,
+        'catch-all': `[...${paramName}]`,
+        'optional-catch-all': `[[...${paramName}]]`,
       };
       throw new Error(
-        `[timber] Param name '${node.paramName}' uses multiple bracket forms.\n` +
+        `[timber] Param name '${paramName}' uses multiple bracket forms.\n` +
           `  ${bracketExamples[existing.segmentType] ?? existing.segmentType} at: ${existing.urlPath}\n` +
-          `  ${bracketExamples[node.segmentType] ?? node.segmentType} at: ${node.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., [${node.paramName}] → [${node.paramName}Id]).`
+          `  Rename one of the segments to fix this (e.g., [${paramName}] → [${paramName}Id]).`
       );
     }
     if (!existing) {
-      forms.set(node.paramName, {
-        segmentType: node.segmentType,
+      forms.set(paramName, {
+        segmentType,
         urlPath: node.urlPath || '/',
       });
     }
@@ -530,20 +500,39 @@ function collectBracketForms(
  * Route groups are URL-transparent, so affixed segments inside different groups
  * at the same level still conflict with each other.
  *
- * See design/07-routing.md §"Priority"
+ * 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<number, SegmentNode[]>();
+    const byLength = new Map<string, SegmentNode[]>();
     for (const child of affixed) {
-      const len = (child.paramPrefix?.length ?? 0) + (child.paramSuffix?.length ?? 0);
-      const group = byLength.get(len);
+      // `\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(len, [child]);
+        byLength.set(key, [child]);
       }
     }
 
@@ -553,7 +542,7 @@ function validateAffixedSiblingConflicts(node: SegmentNode): void {
           `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: ${(group[0]!.paramPrefix?.length ?? 0) + (group[0]!.paramSuffix?.length ?? 0)}\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.`
         );
@@ -569,16 +558,52 @@ function validateAffixedSiblingConflicts(node: SegmentNode): void {
   }
 }
 
+/**
+ * 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);
+}
+
 /**
  * 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) {
-    if (child.segmentType === 'dynamic' && (child.paramPrefix || child.paramSuffix)) {
+    const { segmentType, paramPrefix, paramSuffix } = effectiveUrlSegment(child);
+    if (segmentType === 'dynamic' && (paramPrefix || paramSuffix)) {
       result.push(child);
-    } else if (child.segmentType === 'group') {
+    } else if (segmentType === 'group') {
       result.push(...collectEffectiveAffixed(child));
     }
   }

package/src/routing/segment-classify.ts

@@ -192,6 +192,63 @@ export function classifySegment(dirName: string): SegmentClassification {
   return { type: 'static' };
 }
 
+/**
+ * The URL-matching identity of a segment node.
+ *
+ * For every node except an intercepting one this is the node itself. An
+ * intercepting node is different: its directory name carries a marker
+ * (`(.)photo`, `(.)[id]`), so the node's own `segmentType` is
+ * `'intercepting'` and the bracket syntax of the segment it intercepts was
+ * never classified. Everything that has to reason about *the URL part this
+ * node stands for* — matching it, and keying its param for codec coercion —
+ * needs that classification.
+ *
+ * Deriving it here, from `interceptedSegmentName`, keeps interception out
+ * of `classifySegment`'s output and out of the serialized manifest: there
+ * is no second copy of the classification to drift from this one. The
+ * returned `segmentName` is the intercepted name (`photo`, `[id]`), NOT the
+ * node's directory name — callers that need the directory name for tree
+ * paths must keep reading the node. See TIM-1281.
+ */
+export interface UrlSegmentIdentity {
+  segmentName: string;
+  segmentType: SegmentType;
+  paramName?: string;
+  paramPrefix?: string;
+  paramSuffix?: string;
+}
+
+export function effectiveUrlSegment(node: {
+  segmentName: string;
+  segmentType: SegmentType;
+  paramName?: string;
+  paramPrefix?: string;
+  paramSuffix?: string;
+  interceptedSegmentName?: string;
+}): UrlSegmentIdentity {
+  if (node.segmentType !== 'intercepting' || !node.interceptedSegmentName) {
+    return {
+      segmentName: node.segmentName,
+      segmentType: node.segmentType,
+      paramName: node.paramName,
+      paramPrefix: node.paramPrefix,
+      paramSuffix: node.paramSuffix,
+    };
+  }
+
+  const seg = classifyUrlSegment(node.interceptedSegmentName);
+  if (seg.kind === 'static') {
+    return { segmentName: seg.value, segmentType: 'static' };
+  }
+  return {
+    segmentName: node.interceptedSegmentName,
+    segmentType: seg.kind,
+    paramName: seg.name,
+    paramPrefix: seg.kind === 'dynamic' ? seg.prefix : undefined,
+    paramSuffix: seg.kind === 'dynamic' ? seg.suffix : undefined,
+  };
+}
+
 /**
  * Parse an interception marker from a directory name.
  *