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

package/src/routing/manifest-codegen.ts

@@ -160,11 +160,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.',

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';
@@ -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;
 }
 
@@ -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.
  *

package/src/routing/segment-keys.ts

@@ -0,0 +1,146 @@
+/**
+ * Segment key computation — the stable identity of a segment in the route tree.
+ *
+ * A segment key is the string that names a segment across the RSC/SSR/client
+ * boundary: it appears in the X-Timber-State-Tree header, the X-Timber-Segments
+ * header, SegmentOutlet props, the client segment cache, and (since TIM-1279)
+ * interception scoping.
+ *
+ * This module lives in `routing/` rather than `server/` because the keys are a
+ * property of the route tree itself — both the build-time scanner tree and the
+ * runtime manifest tree produce identical keys for the same directory, which is
+ * what lets a build-time value (an interception scope) be compared against a
+ * request-time matched chain.
+ *
+ * See design/19-client-navigation.md §"X-Timber-State-Tree Header"
+ */
+
+/**
+ * Segment node shape expected by computeSegmentKeys.
+ *
+ * Structurally satisfied by both `SegmentNode` (build time) and
+ * `ManifestSegmentNode` (request time) — keys depend only on the
+ * URL path and the segment classification, never on file payloads.
+ */
+export interface SegmentKeyInput {
+  urlPath: string;
+  segmentName?: string;
+  segmentType?: string;
+}
+
+/**
+ * Compute state-tree keys for a segment chain.
+ *
+ * Non-group segments use their urlPath as-is. Route groups accumulate
+ * ancestor group names to produce globally unique keys:
+ *   app/(a)/(shared)/dashboard → keys: ['/', '/(a)', '/(a)/(shared)', '/dashboard']
+ *
+ * **An intercepting segment switches the chain to name accumulation for good.**
+ * A children-path interception (TIM-1280) puts an intercepting node and its
+ * descendants into the *main* rendered chain, and their `urlPath`s are not
+ * URLs: interception adds no URL depth, so `app/(browse)/(...)[artistSlug]/[year]`
+ * carries `/` and `/[year]`. Keyed by urlPath the intercepting node would
+ * collide with its own owner, and `[year]` with any top-level `[year]` route —
+ * so a client that had one mounted would reuse the wrong cached layout. The
+ * switch is sticky rather than per-node because the *descendants* are where
+ * the false URLs are; the intercepting node alone is not the problem.
+ *
+ * This is the single source of truth for segment keys — used by the
+ * element builder (skip decisions, SegmentOutlet props), segment info
+ * (X-Timber-Segments header), the client cache/state tree, and
+ * interception scoping (`routing/interception.ts`).
+ */
+export function computeSegmentKeys(segments: SegmentKeyInput[]): string[] {
+  const keys: string[] = [];
+  let prevKey = '';
+  let insideIntercepting = false;
+
+  for (const segment of segments) {
+    if (segment.segmentType === 'intercepting') insideIntercepting = true;
+    if (segment.segmentType === 'group' || insideIntercepting) {
+      const base = prevKey === '/' ? '' : prevKey;
+      const key = `${base}/${segment.segmentName}`;
+      keys.push(key);
+      prevKey = key;
+    } else {
+      keys.push(segment.urlPath);
+      prevKey = segment.urlPath;
+    }
+  }
+
+  return keys;
+}
+
+/**
+ * Compute tree paths for a segment chain — the directory path of each segment
+ * with slots elided, e.g. `app/(browse)/feed` → `/(browse)/feed`.
+ *
+ * This is `computeSegmentKeys` with the group branch applied to *every*
+ * segment rather than only to groups. That one difference is the whole point:
+ * `computeSegmentKeys` resets to `urlPath` at each URL-visible segment, so
+ * `(browse)/feed` and `(landing)/feed` both key as `/feed`. Two directories
+ * that render different layouts must not share an identity.
+ *
+ * Used for interception scoping (`routing/interception.ts`), where the
+ * question is "does this route pass through *that* directory?" — not "does it
+ * render this URL?". Not interchangeable with `computeSegmentKeys`: the state
+ * tree is keyed by URL on purpose, because the client caches by URL.
+ */
+export function computeSegmentTreePaths(segments: SegmentKeyInput[]): string[] {
+  const paths: string[] = [];
+  let prev = '';
+
+  for (const segment of segments) {
+    const name = segment.segmentName ?? '';
+    if (!name) {
+      // The app root — no directory name of its own.
+      paths.push('/');
+      prev = '/';
+      continue;
+    }
+    const base = prev === '/' ? '' : prev;
+    const path = `${base}/${name}`;
+    paths.push(path);
+    prev = path;
+  }
+
+  return paths;
+}
+
+/**
+ * The directory names a tree path is built from — `/` is none, `/feed/(a)` is
+ * `['feed', '(a)']`.
+ *
+ * The inverse of the walk above, and it lives beside it so the format is
+ * stated once: `findChainByTreePath` (`server/children-interception.ts`) walks
+ * these names back down the tree to the directory the path addresses, and
+ * `treePathDepth` counts them. Both are readings of the same string, and a
+ * reader that disagreed with the producer about what separates two names
+ * resolves an interception to the wrong node or to none.
+ */
+export function treePathNames(treePath: string): string[] {
+  return treePath === '/' ? [] : treePath.slice(1).split('/');
+}
+
+/**
+ * How many directories a tree path names — `/` is 0, `/feed` is 1,
+ * `/feed/(a)` is 2.
+ *
+ * Two tree paths on a single rendered chain are strictly nested, so on that
+ * chain depth orders them totally — which is what makes it usable as "the
+ * deeper of these two directories" wherever a route passes through both
+ * (`routing/interception.ts`).
+ */
+export function treePathDepth(treePath: string): number {
+  return treePathNames(treePath).length;
+}
+
+/**
+ * Compute a unique key for a parallel route slot.
+ * Format: `{parentSegmentId}/@{slotName}`, e.g. `/@sidebar` or `/dashboard/@modal`.
+ */
+export function computeSlotKey(parentSegmentId: string, slotName: string): string {
+  const name = slotName.startsWith('@') ? slotName : `@${slotName}`;
+  const prefix = parentSegmentId === '/' ? '' : parentSegmentId;
+  return `${prefix}/${name}`;
+}

package/src/routing/slot-placement.ts

@@ -0,0 +1,97 @@
+/**
+ * Parallel slot placement.
+ *
+ * One rule: a slot is resolved only for a segment on the **matched route
+ * chain**, and a slot's own subtree is never on that chain. So a slot declared
+ * anywhere inside another slot's subtree can never render, and is rejected at
+ * build time rather than left as a directory the author will keep editing.
+ *
+ * See design/07-routing.md §"Parallel Routes".
+ */
+
+import type { SegmentNode } from './types.js';
+
+/**
+ * Reject every parallel slot that no renderer reaches.
+ *
+ * **Where slots are resolved.** Two places read `segment.slots`, and both walk
+ * the main route chain: `route-element-builder.ts` (the RSC render) and
+ * `tree-builder.ts`. Neither is reachable from inside a slot. The slot's own
+ * subtree is rendered by `slot-resolver.ts`, which walks the slot's matched
+ * chain to apply that chain's layouts, error boundaries and access gates
+ * (`wrapWithIntermediateSegments`, `wrapWithLayout`) and never reads `.slots`
+ * on any of those nodes. So `app/feed/@modal/photo/@side/page.tsx` and
+ * everything below it is dead: the file is scanned, typed, code-split and
+ * shipped, and no request can render it.
+ *
+ * That is the TIM-1278 failure — a directory that silently never renders —
+ * and the reason it is a build error rather than a documented limit is that
+ * nothing at request time can report it. A slot that does not match renders
+ * `default.tsx` or `null`, which is exactly what a slot the resolver never
+ * looked at also produces, so the author sees the *designed* behaviour of a
+ * non-matching slot and has no signal to distinguish it from a slot that
+ * cannot match at all.
+ *
+ * **Interception is incidental.** TIM-1311 arrived as
+ * `feed/@modal/(.)photo/@side`, and the interception contributes nothing: the
+ * identical `feed/@modal/photo/@side` never renders either, for the same
+ * reason and with no marker anywhere. Rejecting only the intercepting spelling
+ * would have drawn a line the author cannot see from the directory names.
+ *
+ * The children-path interception shape is **not** affected and must not be:
+ * its intercepting node joins the main chain (`server/children-interception.ts`
+ * splices `[…owner ancestors, interceptingNode, …descendants]` into an ordinary
+ * `RouteMatch`), so `route-element-builder.ts` resolves slots on it and below
+ * it exactly as it does for any other chain segment. `(browse)/(...)photo/[id]/@side`
+ * renders; `feed/@modal/(.)photo/@side` does not. The discriminator is the slot
+ * boundary, which is what this walk tracks — not the marker.
+ */
+export function validateSlotPlacement(root: SegmentNode): void {
+  walkForSlotPlacement(root, '', null);
+}
+
+/**
+ * `enclosingSlotPath` is the `app/`-relative path of the nearest slot at or
+ * above `node`, or null on the main chain. It is carried rather than recomputed
+ * so the error can name the slot that swallows the offender — "this is inside
+ * @modal" is the part of the diagnosis the author cannot see from the offending
+ * path alone.
+ */
+function walkForSlotPlacement(
+  node: SegmentNode,
+  path: string,
+  enclosingSlotPath: string | null
+): void {
+  for (const [slotName, slotNode] of Object.entries(node.slots)) {
+    const slotPath = path ? `${path}/@${slotName}` : `@${slotName}`;
+    if (enclosingSlotPath !== null) {
+      throwNestedSlot(slotPath, enclosingSlotPath);
+    }
+    walkForSlotPlacement(slotNode, slotPath, slotPath);
+  }
+
+  for (const child of node.children) {
+    walkForSlotPlacement(
+      child,
+      path ? `${path}/${child.segmentName}` : child.segmentName,
+      enclosingSlotPath
+    );
+  }
+}
+
+function throwNestedSlot(slotPath: string, enclosingSlotPath: string): never {
+  throw new Error(
+    `Build error: parallel slot nested inside another parallel slot.\n` +
+      `  Directory: app/${slotPath}\n` +
+      `  Inside:    app/${enclosingSlotPath}\n` +
+      `A parallel slot is resolved only for a segment on the matched route chain, and a ` +
+      `slot's own subtree is never on that chain — the slot resolver walks the slot's ` +
+      `matched chain to apply its layouts, error boundaries and access gates, and never ` +
+      `looks at slots declared inside it. So app/${slotPath} and everything below it can ` +
+      `never render, and no request-time signal can tell you: an unreachable slot ` +
+      `produces exactly what a slot that simply did not match produces.\n` +
+      `Declare the slot on a segment of the main route chain instead, or move its pages ` +
+      `into app/${enclosingSlotPath}'s own subtree.\n` +
+      `See design/07-routing.md §"Parallel Routes".`
+  );
+}

package/src/routing/walkers.ts

@@ -49,6 +49,12 @@ export interface CollectLeafRoutesOptions {
  *   entries (the build report deduplicates by URL afterward).
  * - Parallel slots are skipped unless `includeSlots: true` (slots
  *   share their parent's URL and are not addressable on their own).
+ * - Intercepting subtrees are skipped unconditionally. They render only
+ *   on soft navigation and add no URL depth, so their computed `urlPath`s
+ *   are not addresses — listing them would advertise routes (`/[year]`)
+ *   that no request can reach. This matches every other consumer of the
+ *   tree that produces URLs: the sitemap generator, the static generator,
+ *   prerendering and the prebuilt-payload builder all skip them too.
  * - Result is sorted by `urlPath` for deterministic output.
  */
 export function collectLeafRoutes<TFile>(
@@ -68,6 +74,8 @@ function walk<TFile>(
   result: LeafRoute<TFile>[],
   includeSlots: boolean
 ): void {
+  if (node.segmentType === 'intercepting') return;
+
   const currentChain = [...chain, node];
   const path = node.urlPath || '/';