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

package/src/routing/manifest-codegen.ts

@@ -31,12 +31,7 @@ const SINGLE_FILE_KEYS = [
 
 // ── Record-shaped conventions ───────────────────────────────────────────
 // Each entry maps to a node property that holds Record<string, RouteFile>.
-const RECORD_FILE_KEYS = [
-  'statusFiles',
-  'jsonStatusFiles',
-  'legacyStatusFiles',
-  'metadataRoutes',
-] as const;
+const RECORD_FILE_KEYS = ['statusFiles', 'jsonStatusFiles', 'metadataRoutes'] as const;
 
 const SCHEMA_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx'];
 
@@ -165,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';
@@ -29,17 +32,6 @@ import { ENCODED_SEPARATOR_RE, NULL_BYTE_RE } from '../server/canonicalize.js';
  */
 const PAGE_EXT_CONVENTIONS = new Set(['page', 'layout', 'error', 'default', 'denied']);
 
-/**
- * Legacy compat status-code files.
- * Maps legacy file name → HTTP status code for the fallback chain.
- * See design/10-error-handling.md §"Fallback Chain".
- */
-const LEGACY_STATUS_FILES: Record<string, number> = {
-  'not-found': 404,
-  'forbidden': 403,
-  'unauthorized': 401,
-};
-
 /**
  * File convention names that are always .ts/.tsx (never .mdx etc.)
  */
@@ -87,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);
 
@@ -102,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;
 }
 
@@ -219,19 +221,6 @@ function scanSegmentFiles(dirPath: string, node: SegmentNode, extSet: Set<string
       continue;
     }
 
-    // Legacy compat files (not-found.tsx, forbidden.tsx, unauthorized.tsx)
-    if (name in LEGACY_STATUS_FILES && extSet.has(ext)) {
-      if (!node.legacyStatusFiles) {
-        node.legacyStatusFiles = {};
-      }
-      const existing = node.legacyStatusFiles[name];
-      if (existing) {
-        throwDuplicateConvention(name, existing.filePath, fullPath);
-      }
-      node.legacyStatusFiles[name] = { filePath: fullPath, extension: ext };
-      continue;
-    }
-
     // Metadata route files (sitemap.ts, robots.ts, icon.tsx, opengraph-image.tsx, etc.)
     // Both static (.xml, .txt, .png, .ico, etc.) and dynamic (.ts, .tsx) files are recognized.
     // When both exist for the same base name, dynamic takes precedence.
@@ -379,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.
  *
@@ -462,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.`
@@ -475,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)
@@ -483,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));
   }
@@ -512,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 || '/',
       });
     }
@@ -554,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]);
       }
     }
 
@@ -577,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.`
         );
@@ -593,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}`;
+}