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

package/src/routing/interception.ts

@@ -17,26 +17,188 @@
  * See design/07-routing.md §"Intercepting Routes"
  */
 
-import type { SegmentNode, InterceptionMarker } from './types.js';
+import type { SegmentNode, InterceptionMarker, RouteFile } from './types.js';
+import { computeSegmentTreePaths, treePathDepth } from './segment-keys.js';
+import { classifyUrlSegment, effectiveUrlSegment } from './segment-classify.js';
+// Every collision space — the main tree, each slot, each intercepting subtree
+// — decides order-dependence with the same oracle, so the spaces cannot drift
+// on what counts as two pages answering one URL. See TIM-1308.
+import { findOrderDependentCollision, type ProbeLeaf } from './collision-probe.js';
 
-/** A conditional rewrite rule generated from an intercepting route. */
-export interface InterceptionRewrite {
+/** Fields shared by both interception shapes. */
+interface InterceptionRewriteBase {
   /**
    * The URL pattern that this rewrite intercepts (the target of navigation).
    * E.g., "/photo/[id]" for a (.)photo/[id] interception.
    */
   interceptedPattern: string;
   /**
-   * The URL prefix that the client must be navigating FROM for this rewrite
-   * to apply. Matched against the X-Timber-URL header.
-   * E.g., "/feed" for a (.)photo/[id] inside /feed/@modal/.
+   * The tree path of the segment that OWNS the slot holding this
+   * intercepting route (`computeSegmentTreePaths`, e.g. "/feed",
+   * "/(browse)", "/(browse)/feed", or "/" at the app root).
+   *
+   * The rewrite only applies when the source route — the page the user is
+   * navigating FROM — passes through that directory, because only then
+   * does the slot holding the intercepting page exist in the rendered
+   * tree. The server checks this by matching X-Timber-URL and testing its
+   * segment chain's tree paths for this value.
+   *
+   * Neither of the identities already in the codebase works here:
+   *
+   * - A **URL prefix** cannot express it. Route groups contribute nothing
+   *   to `urlPath`, so `(browse)/@detail/(...)x` and a genuinely
+   *   root-level `@modal/(...)x` both have prefix "/" while meaning very
+   *   different things.
+   * - A **state-tree key** (`computeSegmentKeys`) cannot either. It
+   *   qualifies a group with its ancestry but resets to `urlPath` at the
+   *   next URL-visible segment, so `(browse)/feed` and `(landing)/feed`
+   *   both key as "/feed" — and a navigation inside `(landing)/feed/…`
+   *   would reach `(browse)/feed`'s slot.
+   *
+   * Tree paths never reset, so two directories that render different
+   * layouts never share one. "/" as a scope means the app root, which
+   * every route passes through — preserving the intentional
+   * match-from-anywhere behavior of a root-level `(...)` interception
+   * (TIM-1006) without an exemption. See TIM-1279.
    */
-  interceptingPrefix: string;
+  interceptingScope: string;
+}
+
+/**
+ * A conditional rewrite rule generated from an intercepting route.
+ *
+ * `mode` records which of the two shapes the directory expresses, because the
+ * two render through entirely different mechanisms and the fields they need
+ * are not the same. It is a union rather than a flag so a reader cannot
+ * re-match `interceptingPrefix` on the shape that has no such pathname.
+ *
+ * See design/07-routing.md §"Intercepting Routes".
+ */
+export type InterceptionRewrite = SlotInterceptionRewrite | ChildrenInterceptionRewrite;
+
+/**
+ * A **modal overlay** interception — the intercepting directory is a direct
+ * child of a parallel slot (`feed/@modal/(.)photo/[id]`).
+ *
+ * The server re-matches the *source* route and the slot resolver finds the
+ * intercepting child inside the slot, so the intercepting page layers over
+ * the page the user was already on.
+ */
+export interface SlotInterceptionRewrite extends InterceptionRewriteBase {
+  mode: 'slot';
   /**
-   * Segments chain from root → intercepting leaf. Used to build the element
-   * tree when the interception is active.
+   * The pathname the server re-matches when this rewrite applies — the
+   * intercepting slot owner's URL path. E.g., "/feed" for a (.)photo/[id]
+   * inside /feed/@modal/.
+   *
+   * This is a build-time constant, never a client-supplied value: the
+   * X-Timber-URL header selects a rewrite but never becomes the rendered
+   * pathname.
    */
-  segmentPath: SegmentNode[];
+  interceptingPrefix: string;
+}
+
+/**
+ * A **sibling layout swap** interception — the intercepting directory is a
+ * direct child of an ordinary segment or route group
+ * (`(browse)/(...)[artistSlug]/…`).
+ *
+ * There is no overlay, no slot and no `default.tsx`: the intercepting page
+ * *replaces* `children` for the owner's layout chain. Nothing is re-matched
+ * either. The server resolves the owner by `interceptingScope` — a tree path,
+ * which identifies exactly one directory — and builds the rendered chain as
+ * `[…owner ancestors, interceptingNode, …its matched descendants]`. That is an
+ * ordinary segment chain, so `tree-builder.ts` renders it with no knowledge
+ * that interception happened.
+ *
+ * Resolving the owner from the tree rather than from a URL is what makes this
+ * shape work where the modal shape cannot: `interceptingPrefix` is
+ * URL-derived, and a route group contributes nothing to `urlPath`, so an owner
+ * like `app/(browse)/` serializes to "/" and re-matching it lands in whichever
+ * group owns the canonical page. A tree path never collapses (TIM-1280).
+ */
+export interface ChildrenInterceptionRewrite extends InterceptionRewriteBase {
+  mode: 'children';
+}
+
+/**
+ * A set of sibling interceptors that compete for one URL position.
+ *
+ * `base` is the intercepted base they share — the URL their own segments sit
+ * directly under — and `anchorIndex` is how many URL parts that base spans,
+ * which is the index in a target pathname their segments are matched at.
+ * Deeper anchors are more local and are tried first.
+ */
+export interface InterceptorAnchorGroup<TFile> {
+  base: string;
+  anchorIndex: number;
+  interceptors: SegmentNode<TFile>[];
+}
+
+/**
+ * Group an owner's intercepting children by the URL position they contend for.
+ *
+ * This is the definition of *which interceptors compete*, and it has exactly
+ * one caller shape on each side of the build: `findInterceptingMatch` resolves
+ * a group with one `matchUrlParts` walk, and
+ * `assertNoInterceptedPatternCollisions` validates the same group as one
+ * collision space. Written twice, the two would be free to disagree about what
+ * competes — and a resolver that walks a wider set than the validator checked
+ * is precisely the order-dependence the validator exists to reject (TIM-1310).
+ *
+ * Contention is keyed by the computed intercepted **base**, not by the marker:
+ * under an owner at `/feed`, `(..)` and `(...)` both base at `/` and are both
+ * matched at index 0, so they are one group. Different bases are different
+ * positions — a `(.)` interceptor can never claim a target that belongs to a
+ * `(..)` one beside it, because the base must also match the target's leading
+ * parts.
+ *
+ * The base is a URL *pattern*, so its length is its part count only because
+ * every pattern part stands for exactly one URL part. A catch-all in the base
+ * breaks that, and `assertInterceptedBaseIsCountable` rejects the shape at
+ * build time.
+ *
+ * A node missing either marker field is skipped, which `classifySegment` never
+ * produces — it sets both whenever it reports `'intercepting'`. Stating the
+ * filter here rather than defaulting the marker is what makes the validator and
+ * the resolver see the same set: such a node renders nothing either way, and a
+ * validator more permissive than the resolver would be checking a candidate
+ * that never competes while the resolver walks one nobody checked.
+ *
+ * `children` is read directly rather than flattened through route groups,
+ * matching both resolvers: the slot resolver reads `slotNode.children`, and an
+ * interceptor deeper inside a slot subtree is rejected by
+ * `validateInterceptionPlacement`. On the children path an interceptor under a
+ * route group is legal and the *group* is its owner, so it is grouped with that
+ * group's other interceptors — which is again exactly what the resolver walks,
+ * since it resolves the owner by tree path.
+ */
+export function groupByInterceptedAnchor<TFile>(
+  ownerUrlPath: string,
+  children: readonly SegmentNode<TFile>[]
+): InterceptorAnchorGroup<TFile>[] {
+  const byBase = new Map<string, InterceptorAnchorGroup<TFile>>();
+
+  for (const child of children) {
+    if (child.segmentType !== 'intercepting') continue;
+    if (!child.interceptionMarker || !child.interceptedSegmentName) continue;
+
+    const base = computeInterceptedBase(ownerUrlPath, child.interceptionMarker);
+    const group = byBase.get(base);
+    if (group) {
+      group.interceptors.push(child);
+    } else {
+      byBase.set(base, {
+        base,
+        anchorIndex: base === '/' ? 0 : base.slice(1).split('/').length,
+        interceptors: [child],
+      });
+    }
+  }
+
+  // Deepest anchor first: a `(.)` interception is the most local one and wins
+  // over a `(...)` that reaches the same page from the root.
+  return [...byBase.values()].sort((a, b) => b.anchorIndex - a.anchorIndex);
 }
 
 /**
@@ -44,34 +206,593 @@ export interface InterceptionRewrite {
  *
  * Walks the tree recursively. For each intercepting segment, computes the
  * intercepted URL based on the marker and the segment's position.
+ *
+ * The list is returned **deepest scope first**, which is what makes
+ * `findInterceptionMatch`'s first-match rule deterministic; see
+ * `sortByScopeDepth`.
  */
 export function collectInterceptionRewrites(root: SegmentNode): InterceptionRewrite[] {
   const rewrites: InterceptionRewrite[] = [];
-  walkForInterceptions(root, [root], rewrites);
-  return rewrites;
+  walkForInterceptions(root, [root], false, rewrites);
+  return sortByScopeDepth(rewrites);
+}
+
+/**
+ * Order the rewrites deepest scope first, so the request-time first-match rule
+ * resolves two applicable rewrites by *nesting* rather than by tree-walk order.
+ *
+ * `findInterceptionMatch` returns the first rewrite whose pattern matches the
+ * target and whose scope the source route reports. More than one can satisfy
+ * both, and the case is not exotic — an owner and a directory *beneath* it may
+ * each hold an interceptor for one URL:
+ *
+ * ```
+ * app/feed/(.)photo/page.tsx        scope /feed
+ * app/feed/(a)/(.)photo/page.tsx    scope /feed/(a)
+ * ```
+ *
+ * A page inside `(a)` renders both owners' layouts, so the client reports both
+ * tree paths and both scopes pass. Unsorted, the winner is whichever the
+ * filesystem enumerated first — renaming the group flips which page a click
+ * opens, the defect class TIM-1305/TIM-1308/TIM-1310 each rejected in a
+ * different space. Here it is an ambiguity between *rewrites* rather than
+ * between pages inside one walk, so no collision space sees it.
+ *
+ * **Deepest wins, and it is specified rather than rejected** because the shape
+ * is one a correct app writes on purpose: a nested layout refining the
+ * interception its parent declares, exactly as `groupByInterceptedAnchor`
+ * already prefers the deepest *anchor* within one owner. The two rules are the
+ * same preference — the more local interception is the author's more specific
+ * statement — applied at the two levels the mechanism has.
+ *
+ * Depth is counted on the **tree path**, the identity that never collapses
+ * (TIM-1279/TIM-1280); a `urlPath` prefix test would relate `(browse)` and
+ * `(landing)`, which render different layouts and share no chain. Two scopes on
+ * one rendered chain are strictly nested, so depth orders them totally, and two
+ * scopes that are *not* on one chain — sibling groups, `feed/(a)` beside
+ * `feed/(b)` — never both pass the scope check, so their relative order is not
+ * observable. That is why this sorts on depth alone rather than testing
+ * ancestry: it is a total order over the pairs that can compete, and it costs
+ * nothing per request.
+ *
+ * Sorting is stable, so rewrites sharing one scope keep tree-walk order. Equal
+ * scopes mean one owner, and of the three pairings that produces only one is an
+ * ambiguity — a children-path interceptor beside a slot one, tracked as
+ * TIM-1319. The enumeration is in design/07-routing.md §"Selection Between
+ * Owners" rather than repeated here, so there is one place to correct if a
+ * rewrite ever grows a field that makes two of them distinguishable.
+ */
+function sortByScopeDepth(rewrites: InterceptionRewrite[]): InterceptionRewrite[] {
+  return rewrites.sort(
+    (a, b) => treePathDepth(b.interceptingScope) - treePathDepth(a.interceptingScope)
+  );
+}
+
+/**
+ * Validate that every intercepting segment sits where it can actually render.
+ *
+ * There are exactly two positions a renderer exists for, and they are the two
+ * shapes interception has:
+ *
+ * 1. **Direct child of a parallel slot** — the modal overlay. The slot
+ *    resolver scans a slot node's *direct children* for an intercepting
+ *    segment (`server/slot-interception.ts`). Nothing between the slot and
+ *    the intercepting directory is allowed, because nothing walks it.
+ * 2. **Direct child of an ordinary segment or route group** — the sibling
+ *    layout swap (TIM-1280). The pipeline resolves the owner by tree path and
+ *    builds the rendered chain through the intercepting node itself
+ *    (`server/children-interception.ts`).
+ *
+ * Everywhere else, rewrite generation still emits a rewrite and nothing
+ * renders it: the rewrite matches the soft navigation, and the user is served
+ * the page they were already on under a changed URL (TIM-1278). The rejected
+ * positions are:
+ *
+ * - **Inside a slot subtree but not directly under the slot**
+ *   (`@modal/(inner)/(.)photo`). Neither renderer applies: the slot resolver
+ *   only reads direct children, and the children-path resolver builds a
+ *   *chain*, which cannot express a descent through a slot.
+ * - **Inside another intercepting subtree** (`(.)a/(.)b`). Left unvalidated
+ *   `collectLeavesWithRewrites` walks the inner one as an ordinary URL
+ *   segment and emits a pattern containing a literal "(.)b".
+ *
+ * Two further shapes are rejected here (TIM-1288). Both are about a catch-all,
+ * and both are specific to interception: elsewhere in the tree the same
+ * shapes are inert or fail safely, and the general "nothing below a catch-all
+ * is reachable" rule is tracked as TIM-1286.
+ *
+ * And one is specific to the children path: an owner chain that binds params
+ * (see `assertOwnerChainBindsNoParams`).
+ */
+export function validateInterceptionPlacement(root: SegmentNode): void {
+  walkForPlacement(root, '', {
+    parentIsSlot: false,
+    inSlotSubtree: false,
+    inInterceptingSubtree: false,
+    ancestorsBindParams: false,
+  });
+}
+
+/**
+ * Reject a children-path interception whose owner chain binds params.
+ *
+ * The rendered chain is `[…owner ancestors, interceptingNode, …descendants]`,
+ * and the only pathname available to bind params from is the **target** — the
+ * URL being navigated to. The intercepting subtree's own params come from it
+ * by construction. The owner chain's do not, in general:
+ *
+ * - With a climbing marker the owner's URL segments are not in the target at
+ *   all. `app/[team]/(..)photo/[id]` bases at "/", so the target is
+ *   `/photo/9` — there is no team value anywhere in it, and `[team]`'s layout
+ *   would render with the param it declares missing.
+ * - With `(.)` the base *is* the owner's `urlPath`, so the target's leading
+ *   parts would bind it. Supporting only that half means one marker behaves
+ *   differently from its siblings for reasons the author cannot see from the
+ *   directory names, so the rule is stated once, on the owner chain.
+ *
+ * A layout that silently renders without the param it declares is the failure
+ * this prevents; it is rejected where it can be explained rather than left to
+ * surface as `undefined` deep inside user code. Route groups and static
+ * segments bind nothing and are unrestricted, which is the whole motivating
+ * shape (`app/(browse)/(...)[artistSlug]/…`).
+ *
+ * The rule stops at a slot boundary: a slot-mode interception re-matches the
+ * *source* route, which supplies the owner's params, so a dynamic owner is
+ * fine there and always has been.
+ */
+/**
+ * Require a children-path interception's owner to have a `layout.tsx`.
+ *
+ * The scope is the owner's tree path, and the client reports which tree paths
+ * it has mounted from `X-Timber-Segments` — which carries **one entry per
+ * layout-bearing segment**, because those are the segments the client needs an
+ * outlet and a cache node for. `buildSegmentInfo` skips the rest.
+ *
+ * For the modal shape that set is exactly the set of possible scope owners, by
+ * construction: a slot is only resolved inside a rendering layout
+ * (`route-element-builder.ts`), so a layoutless segment can never own one. A
+ * children-path interception broke that equivalence — its owner is an ordinary
+ * directory and needs no layout.
+ *
+ * Left unchecked the result is a swap that works exactly once: the first soft
+ * navigation renders, then the client reports no such tree path, and the next
+ * navigation fails the scope check and falls back to the canonical page. That
+ * is fail-safe but silent, and the address-bar channel cannot recover it —
+ * once the swap is on screen the address holds the *intercepted* URL, which
+ * re-matches the canonical chain (the TIM-1282 problem, in the one shape the
+ * rendered-scope fix does not reach).
+ *
+ * Requiring the layout restores the invariant the state tree is built on
+ * rather than widening the wire format to carry segments that own no outlet
+ * and no payload. It also costs the author nothing they were not already
+ * doing: the point of this shape is to render inside the owner's own layout,
+ * so an owner with no layout has no chrome to preserve.
+ */
+function assertOwnerHasLayout(ownerPath: string, childPath: string): void {
+  const owner = ownerPath || '(app root)';
+  throw new Error(
+    `Build error: intercepting route whose owner has no layout.\n` +
+      `  Directory: app/${childPath}\n` +
+      `  Owner:     app/${owner}\n` +
+      `An intercepting directory outside a parallel slot renders inside its owner's ` +
+      `layout chain, and the owner must have a layout.tsx: the client reports which ` +
+      `directories it has mounted from its layout segments, and a scope it cannot ` +
+      `report would let the interception fire once and then silently stop.\n` +
+      `Add app/${owner}/layout.tsx (a pass-through returning {children} is enough), or ` +
+      `move the interception under a directory that has one.\n` +
+      `See design/07-routing.md §"Intercepting Routes".`
+  );
+}
+
+function assertOwnerChainBindsNoParams(childPath: string, marker: InterceptionMarker): void {
+  throw new Error(
+    `Build error: intercepting route under a dynamic segment.\n` +
+      `  Directory: app/${childPath}\n` +
+      `An intercepting directory outside a parallel slot renders inside its own ` +
+      `layout chain, and the only pathname available to bind params from is the ` +
+      `intercepted URL — which does not carry the values of the segments above ` +
+      `"${marker}".\n` +
+      `Move the interception so every directory above it is a static segment or a ` +
+      `route group, or place it inside a parallel slot (@modal/) to render it as an ` +
+      `overlay over the source route instead.\n` +
+      `See design/07-routing.md §"Intercepting Routes".`
+  );
+}
+
+/**
+ * Reject an intercepting route whose intercepted level is not well-defined.
+ *
+ * "One level up" is counted in URL segments, which works because every
+ * pattern part stands for exactly one URL part — except a catch-all, which
+ * stands for a number that varies per request. `anchorIndex` fixes the anchor
+ * at the base's pattern length, so with an owner at `/docs/[...path]` the
+ * interception resolves when the catch-all consumed exactly one segment
+ * (`/docs/a/photo/5`) and is dropped when it consumed more
+ * (`/docs/a/b/photo/5`), because the base no longer matches the target's
+ * leading parts.
+ *
+ * Dropping is fail-safe — the canonical route renders, as on hard navigation
+ * — so this is never a wrong page. But it is a modal that opens at one depth
+ * and silently does not at another, with nothing to tell the author why, and
+ * no request-time input can fix it: the only available source depth is
+ * `X-Timber-URL`, which is the browser's address bar, and once a modal is
+ * open that holds the *intercepted* URL rather than the source.
+ *
+ * So the shape is rejected where it can be explained. A marker that climbs
+ * *past* the catch-all is fine — `(..)` from `/docs/[...path]` bases at
+ * `/docs` — and so is `(...)`, which always bases at the root. The rule is on
+ * the *computed* base, not on having a catch-all anywhere above.
+ */
+function assertInterceptedBaseIsCountable(
+  child: SegmentNode,
+  ownerUrlPath: string,
+  childPath: string
+): void {
+  const marker = child.interceptionMarker ?? '(.)';
+  const base = computeInterceptedBase(ownerUrlPath, marker);
+  const baseParts = base === '/' ? [] : base.slice(1).split('/');
+  const ambiguous = baseParts.find((part) => {
+    const kind = classifyUrlSegment(part).kind;
+    return kind === 'catch-all' || kind === 'optional-catch-all';
+  });
+  if (!ambiguous) return;
+
+  throw new Error(
+    `Build error: intercepting route below a catch-all segment.\n` +
+      `  Directory: app/${childPath}\n` +
+      `  Intercepted base: ${base}\n` +
+      `A catch-all (${ambiguous}) matches a number of URL segments that varies per ` +
+      `request, so "${marker}" cannot identify which segment of a target pathname the ` +
+      `interception starts at — the modal would open at one depth and silently not at ` +
+      `another.\n` +
+      `Move the interception above the catch-all, or use a marker that climbs past it ` +
+      `((..) or (...)).\n` +
+      `See design/07-routing.md §"Intercepting Routes".`
+  );
+}
+
+/**
+ * Reject a catch-all inside an intercepting subtree that has directories
+ * below it.
+ *
+ * A catch-all consumes the whole remaining path, so nothing under it is
+ * reachable — `matchUrlParts` only accepts a catch-all as a terminal leaf and
+ * never descends past one. Rewrite generation is not so strict: it walks the
+ * subtree and emits `/feed/[...rest]/child`, and `pathnameMatchesPattern`
+ * returns as soon as it reaches the catch-all without ever looking at
+ * `child`. So the rewrite matches the navigation and then no renderer exists
+ * — the TIM-1278 failure mode reached by a different route, with the user
+ * served the page they were already on under a changed URL.
+ *
+ * The check covers the whole intercepting subtree, not just the intercepted
+ * segment: `(.)photo/[...rest]/child` emits `/feed/photo/[...rest]/child` and
+ * hijacks `/feed/photo/a/b` by exactly the same mechanism. And it does not
+ * exempt a catch-all that carries its own page — that one does render, but
+ * the rewrite generated for the unreachable descendant is broader than any
+ * route in the tree, so the tail modal fires on navigations no directory
+ * describes.
+ *
+ * Outside a slot the same shape merely 404s, which is why the general rule is
+ * tracked separately (TIM-1286); here it is unsafe, and it only became
+ * reachable when catch-all intercepted segments started matching at all
+ * (TIM-1281).
+ *
+ * The walk descends `children` and not `slots`, mirroring
+ * `collectLeavesWithRewrites` exactly: what this rejects is precisely the set
+ * of paths rewrite generation emits, so the two cannot disagree about which
+ * shapes exist. A slot nested inside an intercepting subtree produces no
+ * rewrite and so cannot hijack anything.
+ */
+function assertInterceptedCatchAllsAreTerminal(node: SegmentNode, nodePath: string): void {
+  const { segmentType, segmentName } = effectiveUrlSegment(node);
+  const isCatchAll = segmentType === 'catch-all' || segmentType === 'optional-catch-all';
+
+  if (isCatchAll && node.children.length > 0) {
+    throw new Error(
+      `Build error: catch-all with nested segments inside an intercepting route.\n` +
+        `  Directory: app/${nodePath}\n` +
+        `  Nested: ${node.children.map((c) => c.segmentName).join(', ')}\n` +
+        `A catch-all (${segmentName}) consumes every remaining URL segment, so nothing ` +
+        `below it can ever match — but the interception rewrite would still be generated ` +
+        `and would hijack the navigation with no page to render.\n` +
+        `Move the nested routes above the catch-all, or intercept a named segment instead.\n` +
+        `See design/07-routing.md §"Intercepting Routes".`
+    );
+  }
+
+  for (const child of node.children) {
+    assertInterceptedCatchAllsAreTerminal(child, `${nodePath}/${child.segmentName}`);
+  }
+}
+
+/**
+ * Reject two pages that answer one URL among the interceptors an owner
+ * resolves in a single walk.
+ *
+ * `validateRouteGroupCollisions` in the scanner returns early on an
+ * intercepting node, so nothing else validates in here. That exemption exists
+ * for a real reason — an interception's computed URL legitimately mirrors the
+ * canonical route it replaces, and interceptors at *different* anchors
+ * deliberately target one URL, which the resolver then orders (deepest anchor
+ * first). But the exemption was broader than its reason. Two shapes slip
+ * through it, and they are the same shape seen from two levels:
+ *
+ *   feed/(.)photo/(a)/page.tsx      feed/@modal/(.)[a]/page.tsx
+ *   feed/(.)photo/(b)/page.tsx      feed/@modal/(.)[b]/page.tsx
+ *
+ * Both pairs answer one URL, and in both `matchUrlParts` resolves the tie by
+ * whichever `children` array lists first — so the winner is whichever the
+ * filesystem enumerated first, and renaming a directory flips it. That is
+ * exactly what `validateRouteGroupCollisions` and
+ * `validateAffixedSiblingConflicts` exist to reject for ordinary siblings.
+ *
+ * **The collision space is the anchor group, not the directory.** An earlier
+ * revision ran once per intercepting directory, which sees the left-hand pair
+ * and not the right-hand one: those leaves live in two different directories.
+ * The space is `groupByInterceptedAnchor`'s output — the same grouping
+ * `findInterceptingMatch` hands to one `matchUrlParts` call — so what is
+ * validated together is exactly what is resolved together. Interceptors at
+ * different anchors stay independent, which is the documented case, and two
+ * slots on one owner are two owners and so two spaces.
+ *
+ * **Two checks, and the difference between them matters.** A duplicate
+ * intercepted *pattern* is decided by string equality, which is exact: two
+ * leaves with one pattern claim one set of URLs, whatever the precedence rules
+ * are. Everything else is decided by asking the matcher — `collision-probe.ts`,
+ * the same oracle the main tree and every slot use, so the spaces cannot
+ * disagree about whether a pair of pages collides.
+ *
+ * Not covered: two affixed dynamics that tie on specificity (`(x)/a-[id]` vs
+ * `(y)/[slug]-b`, ambiguous only for a part shaped `a-…-b`). No single probe
+ * URL exercises both, and `validateAffixedSiblingConflicts` already rejects
+ * that pair by affix length — including through groups, inside intercepting
+ * subtrees, and between two interceptors sharing an anchor.
+ *
+ * The shape applies to both interception mechanisms — a slot interceptor and a
+ * children-path one produce their leaves through the same walk, and both are
+ * resolved by `findInterceptingMatch` — so this is called from the one place in
+ * `walkForPlacement` that sees every owner regardless of position.
+ */
+function assertNoInterceptedPatternCollisions(owner: SegmentNode, ownerPath: string): void {
+  for (const group of groupByInterceptedAnchor(owner.urlPath, owner.children)) {
+    assertAnchorGroupHasNoCollisions(group, ownerPath);
+  }
+}
+
+/**
+ * The URL-matching identity of an intercepting node, as a node.
+ *
+ * `matchUrlParts` reads `segmentType` directly and knows nothing about
+ * interception, so a marker'd directory has to be handed to it under the
+ * identity of the segment it intercepts — `(.)[id]` as `[id]`. Priority
+ * ordering, affix stripping and catch-all handling then come from the shared
+ * walker rather than from a second classifier here.
+ *
+ * Shared with `findInterceptingMatch` for the same reason the grouping is: the
+ * collision space is the resolver's synthetic anchor parent, so its children
+ * have to carry the identity the resolver gives them or the validator would be
+ * probing a tree that does not match the one served. The caller keeps its own
+ * map back to the real node — the proxy is a matching identity, not a
+ * replacement (tree paths still need the directory name).
+ */
+export function interceptorProxy<TFile>(node: SegmentNode<TFile>): SegmentNode<TFile> {
+  return { ...node, ...effectiveUrlSegment(node) };
+}
+
+function assertAnchorGroupHasNoCollisions(
+  group: InterceptorAnchorGroup<RouteFile>,
+  ownerPath: string
+): void {
+  const { base } = group;
+  const owner = ownerPath || '(app root)';
+
+  // The space the resolver walks: a synthetic parent sitting at the anchor
+  // base, holding every interceptor of this group under its matching identity.
+  // `matchUrlParts` starts below this node, so the interceptors' own segments
+  // are matched parts here — which is what lets a probe reach across two
+  // directories and find the pair that competes.
+  const proxies = group.interceptors.map(interceptorProxy);
+  const anchorNode: SegmentNode = {
+    segmentName: '',
+    segmentType: 'static',
+    urlPath: base,
+    children: proxies,
+    slots: {},
+  };
+
+  const patterns = new Map<string, string>();
+  const probeLeaves: ProbeLeaf[] = [];
+
+  for (const proxy of proxies) {
+    // The proxy's name, not the directory's `interceptedSegmentName`: they are
+    // the same string, and this is the one `matchUrlParts` matches on, so the
+    // reported pattern and the probed URL cannot describe different segments.
+    const pattern = joinInterceptedBase(base, proxy.segmentName);
+    walkInterceptedLeaves(proxy, pattern, [proxy], (page, leaf) => {
+      // Two leaves whose intercepted pattern is the *same string* claim exactly
+      // the same set of URLs — one is ambiguous with the other, or dead. This
+      // needs no probe and no reasoning about precedence: identical patterns are
+      // identical URL sets by definition. It is the case route groups make easy
+      // to write, `(a)/page.tsx` beside `(b)/page.tsx`, and the one the main
+      // tree already rejects by comparing urlPath. Across two interceptors it
+      // is `(..)photo` beside `(...)photo` under `/feed`, which both base at
+      // `/` and both intercept the literal `photo`.
+      const duplicate = patterns.get(leaf.interceptedPattern);
+      if (duplicate) {
+        throw new Error(
+          `Build error: route collision between intercepting routes — two pages intercept the same URL.\n` +
+            `  Owner:            app/${owner}\n` +
+            `  Intercepted base: ${base}\n` +
+            `  URL:              ${leaf.interceptedPattern}\n` +
+            `  File 1:           ${duplicate}\n` +
+            `  File 2:           ${page.filePath}\n` +
+            `A route group is transparent for matching, so moving a page into one does not ` +
+            `give it a URL of its own — these two claim the same one. Rename or move one of ` +
+            `them.\n` +
+            `See design/07-routing.md §"Collisions Among Intercepting Routes".`
+        );
+      }
+      patterns.set(leaf.interceptedPattern, page.filePath);
+      probeLeaves.push({ filePath: page.filePath, chain: leaf.chain });
+    });
+  }
+
+  // Differently-spelled patterns that nonetheless compete: ask the matcher.
+  const collision = findOrderDependentCollision(anchorNode, probeLeaves, base);
+  if (collision) {
+    throw new Error(
+      `Build error: route collision between intercepting routes — two pages answer the same URL.\n` +
+        `  Owner:            app/${owner}\n` +
+        `  Intercepted base: ${base}\n` +
+        `  URL:              ${collision.url}\n` +
+        `  File 1:           ${collision.first}\n` +
+        `  File 2:           ${collision.second}\n` +
+        `Both match it, so which one renders would be decided by filesystem enumeration ` +
+        `order — renaming a route group can flip it. Rename or move one of them.\n` +
+        `Pages are compared by the URLs they match, not by how they are spelled: [id] and ` +
+        `[slug] match the same URLs, and an optional catch-all also matches with zero ` +
+        `segments.\n` +
+        `Intercepting directories based at *different* URLs may target one page — the ` +
+        `resolver tries the deepest first — so this rejects only an ambiguity among the ` +
+        `ones based at ${base}.\n` +
+        `See design/07-routing.md §"Collisions Among Intercepting Routes".`
+    );
+  }
+}
+
+/** What the walk knows about the position it is currently standing in. */
+interface PlacementContext {
+  /** `node` is itself a slot node, so its children are direct slot children. */
+  parentIsSlot: boolean;
+  /** `node` is at or below a slot node. */
+  inSlotSubtree: boolean;
+  /** `node` is inside an intercepting subtree. */
+  inInterceptingSubtree: boolean;
+  /** Some segment from the root down to `node`, inclusive, binds a param. */
+  ancestorsBindParams: boolean;
+}
+
+function walkForPlacement(node: SegmentNode, path: string, ctx: PlacementContext): void {
+  for (const child of node.children) {
+    const childPath = path ? `${path}/${child.segmentName}` : child.segmentName;
+
+    if (child.segmentType === 'intercepting') {
+      const marker = child.interceptionMarker ?? '(.)';
+
+      if (ctx.inInterceptingSubtree) {
+        throw new Error(
+          `Build error: intercepting route nested inside another intercepting route.\n` +
+            `  Directory: app/${childPath}\n` +
+            `An intercepting directory (${marker}) resolves against the URL its own parent ` +
+            `renders at, and an intercepting subtree has no such URL — nothing walks it, so ` +
+            `the rewrite would match the navigation and then have nothing to render.\n` +
+            `See design/07-routing.md §"Intercepting Routes".`
+        );
+      }
+
+      // Inside a slot, only a *direct* slot child is reachable: the slot
+      // resolver reads `slotNode.children` and stops. The children-path
+      // renderer cannot pick it up either — it builds a segment chain, which
+      // has no way to express a descent through a slot.
+      if (ctx.inSlotSubtree && !ctx.parentIsSlot) {
+        throw new Error(
+          `Build error: intercepting route inside a parallel slot but not directly under it.\n` +
+            `  Directory: app/${childPath}\n` +
+            `An intercepting directory (${marker}) inside an @slot must be a *direct* child of ` +
+            `that slot, e.g. app/feed/@modal/${child.segmentName}/page.tsx. The slot resolver ` +
+            `scans the slot's direct children only; elsewhere the rewrite would match the ` +
+            `navigation and then have nothing to render.\n` +
+            `See design/07-routing.md §"Intercepting Routes".`
+        );
+      }
+
+      // Outside a slot the intercepting page replaces `children` for the
+      // owner's own layout chain, so those layouts render against the
+      // intercepted URL — which carries no values for params declared above
+      // the interception.
+      if (!ctx.parentIsSlot && ctx.ancestorsBindParams) {
+        assertOwnerChainBindsNoParams(childPath, marker);
+      }
+
+      if (!ctx.parentIsSlot && !node.layout) {
+        assertOwnerHasLayout(path, childPath);
+      }
+
+      // `node` is the owner — the slot (whose urlPath is the owning segment's,
+      // since slots add no URL depth) or the ordinary segment holding the
+      // interception. The same input rewrite generation bases from.
+      assertInterceptedBaseIsCountable(child, node.urlPath, childPath);
+      assertInterceptedCatchAllsAreTerminal(child, childPath);
+    }
+
+    walkForPlacement(child, childPath, {
+      parentIsSlot: false,
+      // A slot subtree stays a slot subtree all the way down: the deeper
+      // positions are exactly the ones neither renderer reaches.
+      inSlotSubtree: ctx.inSlotSubtree,
+      inInterceptingSubtree: ctx.inInterceptingSubtree || child.segmentType === 'intercepting',
+      ancestorsBindParams: ctx.ancestorsBindParams || !!child.paramName,
+    });
+  }
+
+  // After every child has been recursed into, so a placement error inside any
+  // intercepting subtree is reported in preference to what it causes here — a
+  // nested interception leaves a node `matchUrlParts` cannot match at all, and
+  // the resulting nonsense below it is not what the author needs to be told
+  // about. This is per *owner* rather than per intercepting directory because
+  // the collision space is the anchor group; see
+  // `assertNoInterceptedPatternCollisions`.
+  assertNoInterceptedPatternCollisions(node, path);
+
+  for (const [slotName, slotNode] of Object.entries(node.slots)) {
+    walkForPlacement(slotNode, path ? `${path}/@${slotName}` : `@${slotName}`, {
+      parentIsSlot: true,
+      inSlotSubtree: true,
+      inInterceptingSubtree: ctx.inInterceptingSubtree,
+      // A slot-mode interception never binds owner params from the target —
+      // the pipeline re-matches the source route, which supplies them — so the
+      // rule stops at the slot boundary.
+      ancestorsBindParams: false,
+    });
+  }
 }
 
 /**
  * Recursively walk the segment tree to find intercepting routes.
+ *
+ * `ancestors` deliberately excludes slot nodes: a slot doesn't appear in a
+ * matched route chain, so the last entry is always the nearest chain-visible
+ * ancestor — the segment that owns the slot, and therefore the segment whose
+ * presence in the source route gates the interception.
+ *
+ * Intercepting nodes only ever appear as a direct child of a slot or of an
+ * ordinary chain segment in a valid tree; `validateInterceptionPlacement`
+ * rejects every other placement at scan time, so this walk never has to
+ * decide what an unrenderable intercepting node should generate.
+ *
+ * `parentIsSlot` is what distinguishes the two shapes, and it is the only
+ * input that does: the owner, the scope and the intercepted pattern are all
+ * computed identically either way.
  */
 function walkForInterceptions(
   node: SegmentNode,
   ancestors: SegmentNode[],
+  parentIsSlot: boolean,
   rewrites: InterceptionRewrite[]
 ): void {
   // Check children
   for (const child of node.children) {
     if (child.segmentType === 'intercepting' && child.interceptionMarker) {
       // Found an intercepting route — collect rewrites from its sub-tree
-      collectFromInterceptingNode(child, ancestors, rewrites);
+      collectFromInterceptingNode(child, ancestors, parentIsSlot, rewrites);
     } else {
-      walkForInterceptions(child, [...ancestors, child], rewrites);
+      walkForInterceptions(child, [...ancestors, child], false, rewrites);
     }
   }
 
   // Check slots (intercepting routes are typically inside slots like @modal)
-  for (const [, slot] of node.slots) {
-    walkForInterceptions(slot, ancestors, rewrites);
+  for (const slot of Object.values(node.slots)) {
+    walkForInterceptions(slot, ancestors, true, rewrites);
   }
 }
 
@@ -82,6 +803,7 @@ function walkForInterceptions(
 function collectFromInterceptingNode(
   interceptingNode: SegmentNode,
   ancestors: SegmentNode[],
+  parentIsSlot: boolean,
   rewrites: InterceptionRewrite[]
 ): void {
   const marker = interceptingNode.interceptionMarker!;
@@ -89,85 +811,190 @@ function collectFromInterceptingNode(
 
   // Compute the intercepted URL base based on the marker
   const parentUrlPath = ancestors[ancestors.length - 1].urlPath;
-  const interceptedBase = computeInterceptedBase(parentUrlPath, marker);
-  const interceptedUrlBase =
-    interceptedBase === '/' ? `/${segmentName}` : `${interceptedBase}/${segmentName}`;
+  const interceptedUrlBase = computeInterceptedUrlBase(parentUrlPath, marker, segmentName);
+
+  // The scope key and the re-match prefix both describe the same node — the
+  // interception's owner — so they are derived here together from one
+  // ancestor chain.
+  const ancestorPaths = computeSegmentTreePaths(ancestors);
+  const interceptingScope = ancestorPaths[ancestorPaths.length - 1];
 
   // Find all leaf pages in the intercepting sub-tree
-  collectLeavesWithRewrites(
-    interceptingNode,
-    interceptedUrlBase,
-    parentUrlPath,
-    [...ancestors, interceptingNode],
-    rewrites
-  );
+  const shape: InterceptionShape = parentIsSlot
+    ? { mode: 'slot', interceptingPrefix: parentUrlPath, interceptingScope }
+    : { mode: 'children', interceptingScope };
+  collectLeavesWithRewrites(interceptingNode, interceptedUrlBase, shape, rewrites);
 }
 
 /**
- * Recursively find leaf pages in an intercepting sub-tree and generate
- * rewrite rules for each.
+ * Everything about a rewrite except which URL it intercepts — one intercepting
+ * directory produces one of these and one rewrite per leaf page beneath it.
+ *
+ * Written as a union of `Omit`s rather than `Omit` of the union: `Omit` is not
+ * distributive, so the latter would silently collapse to the shapes' common
+ * fields and drop `interceptingPrefix`.
  */
-function collectLeavesWithRewrites(
+type InterceptionShape =
+  | Omit<SlotInterceptionRewrite, 'interceptedPattern'>
+  | Omit<ChildrenInterceptionRewrite, 'interceptedPattern'>;
+
+/**
+ * Walk an intercepting sub-tree and visit every page-bearing node with the URL
+ * pattern it is intercepted at, and URLs that reach it.
+ *
+ * Route groups are transparent, exactly as they are in the main tree — which
+ * is what makes two groups under one interceptor able to claim one URL, and is
+ * why the collision validator has to walk the same shape this does.
+ *
+ * Rewrite generation and that validator are the two callers. They share this
+ * walk rather than each having their own so they cannot disagree about which
+ * URLs an interceptor claims: a leaf the validator did not see is a rewrite
+ * nobody checked, and a leaf only the validator sees is a build error for a
+ * route that does not exist. Slots are not descended, here or in either caller
+ * — a slot nested inside an intercepting subtree produces no rewrite.
+ *
+ * That answers the rewrite question only, and the resolution question is
+ * answered elsewhere: `validateSlotsInsideInterceptingSubtree`
+ * (`collision-spaces.ts`) gives each such slot its own collision space, and
+ * `validateSlotPlacement` (`slot-placement.ts`) rejects the ones no renderer
+ * reaches. Between them the slots this walk skips are covered; do not conclude
+ * from the skip here that they are unvalidated (TIM-1308, TIM-1311).
+ *
+ * The walk reports the chain of URL-contributing nodes rather than building
+ * probe URLs itself: choosing a probe value means running the matcher over the
+ * whole subtree, which is the validator's business and not something rewrite
+ * generation should be paying for or passing dummy arguments around.
+ */
+function walkInterceptedLeaves(
   node: SegmentNode,
   interceptedUrlPath: string,
-  interceptingPrefix: string,
-  segmentPath: SegmentNode[],
-  rewrites: InterceptionRewrite[]
+  chain: SegmentNode[],
+  visit: (page: NonNullable<SegmentNode['page']>, leaf: InterceptedLeaf) => void
 ): void {
   if (node.page) {
-    rewrites.push({
-      interceptedPattern: interceptedUrlPath,
-      interceptingPrefix,
-      segmentPath: [...segmentPath],
-    });
+    // The page is handed over rather than the node so callers reading it do
+    // not need a non-null assertion to say what this branch already proved.
+    visit(node.page, { interceptedPattern: interceptedUrlPath, chain });
   }
 
   for (const child of node.children) {
-    const childUrl =
-      child.segmentType === 'group'
-        ? interceptedUrlPath
-        : `${interceptedUrlPath}/${child.segmentName}`;
-    collectLeavesWithRewrites(
+    const isGroup = child.segmentType === 'group';
+    walkInterceptedLeaves(
       child,
-      childUrl,
-      interceptingPrefix,
-      [...segmentPath, child],
-      rewrites
+      isGroup ? interceptedUrlPath : `${interceptedUrlPath}/${child.segmentName}`,
+      isGroup ? chain : [...chain, child],
+      visit
     );
   }
 }
 
+/** What one page-bearing node in an intercepting subtree claims. */
+interface InterceptedLeaf {
+  /** The URL pattern the rewrite carries — the author's own spelling. */
+  interceptedPattern: string;
+  /**
+   * The nodes from the intercepting directory down to this page that contribute
+   * URL parts — route groups excluded, since they are transparent for matching.
+   * Empty for the intercepting directory's own page.
+   */
+  chain: SegmentNode[];
+}
+
 /**
- * Compute the base URL that an intercepting route intercepts, given the
- * parent's URL path and the interception marker.
- *
- * - (.)  — same level: parent's URL path
- * - (..) — one level up: parent's parent URL path
- * - (...) — root level: /
- * - (..)(..) — two levels up: parent's grandparent URL path
+ * Recursively find leaf pages in an intercepting sub-tree and generate
+ * rewrite rules for each.
+ */
+function collectLeavesWithRewrites(
+  node: SegmentNode,
+  interceptedUrlPath: string,
+  shape: InterceptionShape,
+  rewrites: InterceptionRewrite[]
+): void {
+  walkInterceptedLeaves(node, interceptedUrlPath, [], (_page, leaf) => {
+    rewrites.push({ ...shape, interceptedPattern: leaf.interceptedPattern });
+  });
+}
+
+/**
+ * How many URL levels a marker climbs from the slot owner to reach the
+ * intercepted segment, or `'root'` for a marker that climbs all the way.
  *
  * Level counting operates on URL path segments, NOT filesystem directories.
  * Route groups and parallel slots are already excluded from urlPath (they
  * don't add URL depth), so (..) correctly climbs visible segments. This
  * avoids the Vinext bug where path.dirname() on filesystem paths would
  * waste climbs on invisible route groups.
+ *
+ * Used only by `computeInterceptedBase` below — both rewrite generation and
+ * the slot resolver go through that, so the arithmetic exists once.
  */
-function computeInterceptedBase(parentUrlPath: string, marker: InterceptionMarker): string {
+function interceptionClimb(marker: InterceptionMarker): number | 'root' {
   switch (marker) {
     case '(.)':
-      return parentUrlPath;
-    case '(..)': {
-      const parts = parentUrlPath.split('/').filter(Boolean);
-      parts.pop();
-      return parts.length === 0 ? '/' : `/${parts.join('/')}`;
-    }
+      return 0;
+    case '(..)':
+      return 1;
+    case '(..)(..)':
+      return 2;
     case '(...)':
-      return '/';
-    case '(..)(..)': {
-      const parts = parentUrlPath.split('/').filter(Boolean);
-      parts.pop();
-      parts.pop();
-      return parts.length === 0 ? '/' : `/${parts.join('/')}`;
-    }
+      return 'root';
   }
 }
+
+/**
+ * Compute the base URL that an intercepting route intercepts, given the
+ * parent's URL path and the interception marker.
+ *
+ * - (.)  — same level: parent's URL path
+ * - (..) — one level up: parent's parent URL path
+ * - (...) — root level: /
+ * - (..)(..) — two levels up: parent's grandparent URL path
+ *
+ * The result is a URL **pattern**, not a URL — `parentUrlPath` carries the
+ * directory names, so a dynamic ancestor appears as `/docs/[...path]`.
+ * Rewrite generation wants exactly that. The slot resolver imports this to
+ * locate the intercepted segment in a concrete target pathname, and must
+ * therefore account for a bracket part standing for a different number of
+ * URL parts than itself (TIM-1281).
+ *
+ * Climbing past the root clamps to `/` rather than erroring, so generation
+ * and resolution never disagree about what an over-reaching marker
+ * intercepts.
+ */
+/**
+ * The URL pattern an intercepting directory's own page sits at — its
+ * `computeInterceptedBase` joined with the segment it intercepts.
+ *
+ * The root case is why this is a function rather than a template literal at
+ * each caller: a base of `/` must not produce `//photo`. Rewrite generation
+ * and the collision validator both start their walk from this value, so the
+ * two describe the same URLs by construction.
+ */
+export function computeInterceptedUrlBase(
+  parentUrlPath: string,
+  marker: InterceptionMarker,
+  interceptedSegmentName: string
+): string {
+  return joinInterceptedBase(computeInterceptedBase(parentUrlPath, marker), interceptedSegmentName);
+}
+
+/**
+ * An intercepted base joined with one segment beneath it.
+ *
+ * The whole content of the "function rather than a template literal" rule
+ * above: a base of `/` must not produce `//photo`. The collision validator has
+ * the base in hand already (it groups by it) and joins through this rather than
+ * re-deriving it from an owner path, so both callers spell the root case once.
+ */
+export function joinInterceptedBase(base: string, segmentName: string): string {
+  return base === '/' ? `/${segmentName}` : `${base}/${segmentName}`;
+}
+
+export function computeInterceptedBase(parentUrlPath: string, marker: InterceptionMarker): string {
+  const climb = interceptionClimb(marker);
+  if (climb === 'root') return '/';
+
+  const parts = parentUrlPath.split('/').filter(Boolean);
+  for (let i = 0; i < climb; i++) parts.pop();
+  return parts.length === 0 ? '/' : `/${parts.join('/')}`;
+}