@timber-js/app 0.2.0-alpha.96 → 0.2.0-alpha.98

package/src/plugins/build-report.ts

@@ -17,6 +17,7 @@ import { gzipSync } from 'node:zlib';
 import type { Plugin, Logger } from 'vite';
 import type { PluginContext } from '../plugin-context.js';
 import type { SegmentNode, RouteTree } from '../routing/types.js';
+import { collectLeafRoutes } from '../routing/walkers.js';
 import { formatSize } from '../utils/format.js';
 
 // ─── Public types ─────────────────────────────────────────────────────────
@@ -83,33 +84,23 @@ interface RouteInfo {
 /**
  * Walk the route tree and collect all leaf routes (pages + API endpoints).
  *
- * Parallel slots (`@artists`, `@shows`, etc.) are intentionally skipped —
- * they render alongside the parent page at the same URL and are not
- * separately URL-addressable. Their JS is captured in shared/layout chunks.
+ * Wraps the shared `collectLeafRoutes` walker (TIM-848). Parallel slots
+ * (`@artists`, `@shows`, etc.) are intentionally skipped — they render
+ * alongside the parent page at the same URL and are not separately
+ * URL-addressable. Their JS is captured in shared/layout chunks.
  *
  * After collection, entries are deduplicated by URL path so that overlapping
  * route groups (e.g. `(browse)` and `(marketing)` both producing `/`) only
- * appear once. The entry with the largest route-specific size wins.
+ * appear once. The entry with the longest segment chain (most specific
+ * match) wins.
  */
 export function collectRoutes(tree: RouteTree): RouteInfo[] {
-  const routes: RouteInfo[] = [];
-
-  function walk(node: SegmentNode, chain: SegmentNode[]): void {
-    const currentChain = [...chain, node];
-    const path = node.urlPath || '/';
-
-    if (node.page) {
-      routes.push({ path, segments: currentChain, entryFilePath: node.page.filePath });
-    }
-    if (node.route) {
-      routes.push({ path, segments: currentChain, entryFilePath: node.route.filePath });
-    }
-
-    // Recurse into child segments only — skip parallel slots (node.slots)
-    for (const child of node.children) walk(child, currentChain);
-  }
-
-  walk(tree.root, []);
+  const leaves = collectLeafRoutes(tree.root);
+  const routes: RouteInfo[] = leaves.map((leaf) => ({
+    path: leaf.urlPath,
+    segments: leaf.segments,
+    entryFilePath: leaf.page?.filePath ?? leaf.route?.filePath ?? null,
+  }));
 
   // Deduplicate entries with the same URL path (e.g. from overlapping route groups).
   // Keep the entry with the longest segment chain (most specific match).

package/src/plugins/dev-404-page.ts

@@ -13,6 +13,9 @@
  * Design doc: 21-dev-server.md, 07-routing.md
  */
 
+import type { SegmentNode } from '../routing/types.js';
+import { collectLeafRoutes } from '../routing/walkers.js';
+
 // ─── Types ──────────────────────────────────────────────────────────────────
 
 interface RouteInfo {
@@ -22,54 +25,25 @@ interface RouteInfo {
   type: 'page' | 'route';
 }
 
-/** Minimal segment node shape — matches ManifestSegmentNode. */
-interface SegmentNode {
-  segmentName: string;
-  segmentType: string;
-  urlPath: string;
-  page?: { filePath: string };
-  route?: { filePath: string };
-  children: SegmentNode[];
-  slots: Record<string, SegmentNode> | Map<string, SegmentNode>;
-}
-
 // ─── Route Collection ───────────────────────────────────────────────────────
 
 /**
- * Collect all routable paths from the manifest tree.
+ * Collect all routable paths from a route tree (build-time scanner output
+ * or runtime route manifest).
  *
- * Walks the segment tree and collects paths for segments that have
- * a page or route handler.
+ * Wraps the shared `collectLeafRoutes` walker (TIM-848). Includes parallel
+ * slots so the dev 404 page can list slot pages too — they aren't
+ * separately addressable, but they're still useful to know about when
+ * debugging a missing route.
  */
-export function collectRoutes(root: SegmentNode): RouteInfo[] {
+export function collectRoutes<TFile>(root: SegmentNode<TFile>): RouteInfo[] {
+  const leaves = collectLeafRoutes(root, { includeSlots: true });
   const routes: RouteInfo[] = [];
-  walkRoutes(root, routes);
-  return routes.sort((a, b) => a.path.localeCompare(b.path));
-}
-
-function walkRoutes(node: SegmentNode, routes: RouteInfo[]): void {
-  if (node.page) {
-    routes.push({ path: node.urlPath || '/', type: 'page' });
-  }
-  if (node.route) {
-    routes.push({ path: node.urlPath || '/', type: 'route' });
-  }
-
-  for (const child of node.children) {
-    walkRoutes(child, routes);
-  }
-
-  // Handle both Map and plain object for slots
-  const slots = node.slots;
-  if (slots instanceof Map) {
-    for (const [, slotNode] of slots) {
-      walkRoutes(slotNode, routes);
-    }
-  } else if (slots && typeof slots === 'object') {
-    for (const key of Object.keys(slots)) {
-      walkRoutes((slots as Record<string, SegmentNode>)[key]!, routes);
-    }
+  for (const leaf of leaves) {
+    if (leaf.page) routes.push({ path: leaf.urlPath, type: 'page' });
+    if (leaf.route) routes.push({ path: leaf.urlPath, type: 'route' });
   }
+  return routes;
 }
 
 // ─── String Similarity ──────────────────────────────────────────────────────

package/src/plugins/routing.ts

@@ -116,7 +116,7 @@ export function timberRouting(ctx: PluginContext): Plugin {
           segmentType: 'static',
           urlPath: '/',
           children: [],
-          slots: new Map(),
+          slots: {},
         },
       };
       return;
@@ -326,7 +326,7 @@ function generateSearchParamsRegistryModule(tree: RouteTree): string {
       }
     }
     for (const child of node.children) walk(child);
-    for (const [, slot] of node.slots) walk(slot);
+    for (const slot of Object.values(node.slots)) walk(slot);
   }
   walk(tree.root);
 
@@ -482,9 +482,9 @@ function generateManifestModule(tree: RouteTree, viteRoot: string): string {
     // Runtime registration happens in the route loader using the page module.
 
     // Status-code files
-    if (node.statusFiles && node.statusFiles.size > 0) {
+    if (node.statusFiles && Object.keys(node.statusFiles).length > 0) {
       const statusEntries: string[] = [];
-      for (const [code, file] of node.statusFiles) {
+      for (const [code, file] of Object.entries(node.statusFiles)) {
         const v = addImport(file);
         statusEntries.push(
           `${nextIndent}    ${JSON.stringify(code)}: { load: ${v}, filePath: ${JSON.stringify(file.filePath)} }`
@@ -494,9 +494,9 @@ function generateManifestModule(tree: RouteTree, viteRoot: string): string {
     }
 
     // JSON status-code files
-    if (node.jsonStatusFiles && node.jsonStatusFiles.size > 0) {
+    if (node.jsonStatusFiles && Object.keys(node.jsonStatusFiles).length > 0) {
       const jsonEntries: string[] = [];
-      for (const [code, file] of node.jsonStatusFiles) {
+      for (const [code, file] of Object.entries(node.jsonStatusFiles)) {
         const v = addImport(file);
         jsonEntries.push(
           `${nextIndent}    ${JSON.stringify(code)}: { load: ${v}, filePath: ${JSON.stringify(file.filePath)} }`
@@ -506,9 +506,9 @@ function generateManifestModule(tree: RouteTree, viteRoot: string): string {
     }
 
     // Legacy status files
-    if (node.legacyStatusFiles && node.legacyStatusFiles.size > 0) {
+    if (node.legacyStatusFiles && Object.keys(node.legacyStatusFiles).length > 0) {
       const legacyEntries: string[] = [];
-      for (const [name, file] of node.legacyStatusFiles) {
+      for (const [name, file] of Object.entries(node.legacyStatusFiles)) {
         const v = addImport(file);
         legacyEntries.push(
           `${nextIndent}    ${JSON.stringify(name)}: { load: ${v}, filePath: ${JSON.stringify(file.filePath)} }`
@@ -520,9 +520,9 @@ function generateManifestModule(tree: RouteTree, viteRoot: string): string {
     }
 
     // Metadata route files (sitemap.ts, robots.ts, icon.tsx, etc.)
-    if (node.metadataRoutes && node.metadataRoutes.size > 0) {
+    if (node.metadataRoutes && Object.keys(node.metadataRoutes).length > 0) {
       const metaEntries: string[] = [];
-      for (const [name, file] of node.metadataRoutes) {
+      for (const [name, file] of Object.entries(node.metadataRoutes)) {
         const v = addImport(file);
         metaEntries.push(
           `${nextIndent}    ${JSON.stringify(name)}: { load: ${v}, filePath: ${JSON.stringify(file.filePath)} }`
@@ -540,9 +540,11 @@ function generateManifestModule(tree: RouteTree, viteRoot: string): string {
     }
 
     // Parallel slots
-    if (node.slots.size > 0) {
+    const slotKeys = Object.keys(node.slots);
+    if (slotKeys.length > 0) {
       const slotEntries: string[] = [];
-      for (const [slotName, slotNode] of node.slots) {
+      for (const slotName of slotKeys) {
+        const slotNode = node.slots[slotName]!;
         slotEntries.push(
           `${nextIndent}    ${JSON.stringify(slotName)}: ${serializeNode(slotNode, nextIndent + '  ')}`
         );

package/src/routing/codegen.ts

@@ -149,7 +149,7 @@ function collectRoutes(
   }
 
   // Recurse into slots (they share the parent's URL path, but may have their own pages)
-  for (const [, slot] of node.slots) {
+  for (const slot of Object.values(node.slots)) {
     collectRoutes(slot, params, nextAncestorFiles, routes);
   }
 }

package/src/routing/convention-lint.ts

@@ -89,7 +89,7 @@ function hasAnyRoutable(node: SegmentNode): boolean {
   for (const child of node.children) {
     if (hasAnyRoutable(child)) return true;
   }
-  for (const [, slot] of node.slots) {
+  for (const slot of Object.values(node.slots)) {
     if (hasAnyRoutable(slot)) return true;
   }
   return false;
@@ -105,7 +105,7 @@ function hasAnyPage(node: SegmentNode): boolean {
   for (const child of node.children) {
     if (hasAnyPage(child)) return true;
   }
-  for (const [, slot] of node.slots) {
+  for (const slot of Object.values(node.slots)) {
     if (hasAnyPage(slot)) return true;
   }
   return false;
@@ -173,7 +173,7 @@ function checkRouteExports(node: SegmentNode, warnings: ConventionWarning[]): vo
   for (const child of node.children) {
     checkRouteExports(child, warnings);
   }
-  for (const [, slot] of node.slots) {
+  for (const slot of Object.values(node.slots)) {
     checkRouteExports(slot, warnings);
   }
 }
@@ -249,7 +249,7 @@ function checkDefaultExports(node: SegmentNode, warnings: ConventionWarning[]):
   for (const child of node.children) {
     checkDefaultExports(child, warnings);
   }
-  for (const [, slot] of node.slots) {
+  for (const slot of Object.values(node.slots)) {
     checkDefaultExports(slot, warnings);
   }
 }

package/src/routing/index.ts

@@ -1,4 +1,4 @@
-export { scanRoutes, classifySegment } from './scanner.js';
+export { scanRoutes } from './scanner.js';
 export { generateRouteMap } from './codegen.js';
 export type { CodegenOptions } from './codegen.js';
 export type {
@@ -12,5 +12,7 @@ export type {
 export { DEFAULT_PAGE_EXTENSIONS, INTERCEPTION_MARKERS } from './types.js';
 export { collectInterceptionRewrites } from './interception.js';
 export type { InterceptionRewrite } from './interception.js';
-export { classifyUrlSegment } from './segment-classify.js';
-export type { UrlSegment } from './segment-classify.js';
+export { classifyUrlSegment, classifySegment } from './segment-classify.js';
+export type { UrlSegment, SegmentClassification } from './segment-classify.js';
+export { collectLeafRoutes } from './walkers.js';
+export type { LeafRoute, CollectLeafRoutesOptions } from './walkers.js';

package/src/routing/interception.ts

@@ -70,7 +70,7 @@ function walkForInterceptions(
   }
 
   // Check slots (intercepting routes are typically inside slots like @modal)
-  for (const [, slot] of node.slots) {
+  for (const slot of Object.values(node.slots)) {
     walkForInterceptions(slot, ancestors, rewrites);
   }
 }

package/src/routing/link-codegen.ts

@@ -130,21 +130,33 @@ export function formatLinkCatchAllOverloads(): string[] {
   lines.push(`    }): import('react').JSX.Element`);
 
   // (2) Computed/variable href — non-literal `string` only.
+  //
   // `string extends H` is true only when H is the wide `string` type,
-  // not a specific literal. Literal internal paths (typos) that don't
-  // match any per-route signature collapse to `never` here, but since
-  // this block is NOT the "last overload" at resolution time, TS
-  // instead reports the error from the per-route block — which now
-  // says `Type '"/typo"' is not assignable to type '"/products/[id]"'`
-  // or similar per-route-specific guidance.
+  // not a specific literal. For literal hrefs, this overload must NOT
+  // be selectable so the per-route discriminated union (block 1) is
+  // the resolution target.
+  //
+  // TIM-833 follow-up: the previous shape used `string extends H ? {...} : never`
+  // on the WHOLE props type. For literal H, that collapsed `props` to
+  // `never`, and JSX type inference then read `(never).children` as
+  // `never` — producing the misleading
+  // `'children' prop expects type 'never' which requires multiple
+  // children, but only a single child was provided` (TS2745) error,
+  // which buried the actual prop-mismatch message under a noise diagnostic.
+  //
+  // Fix: move the `: never` from the whole props onto just the `href`
+  // field. The overload remains uncallable for literal H (since `"/x"`
+  // is not assignable to `never`), but `children` retains its real
+  // `ReactNode` type so JSX inference no longer collapses to never.
+  // The diagnostic surface becomes: TS reports the per-route block's
+  // error chain (the helpful "Type 'number' is not assignable to type
+  // 'string'" message) WITHOUT a leading TS2745 noise line.
   lines.push(`    <H extends string>(`);
-  lines.push(`      props: string extends H`);
-  lines.push(`        ? ${baseProps} & {`);
-  lines.push(`            href: H`);
-  lines.push(`            segmentParams?: Record<string, string | number | string[]>`);
-  lines.push(`            searchParams?: ${catchAllSearchParams}`);
-  lines.push(`          }`);
-  lines.push(`        : never`);
+  lines.push(`      props: ${baseProps} & {`);
+  lines.push(`        href: string extends H ? H : never`);
+  lines.push(`        segmentParams?: Record<string, string | number | string[]>`);
+  lines.push(`        searchParams?: ${catchAllSearchParams}`);
+  lines.push(`      }`);
   lines.push(`    ): import('react').JSX.Element`);
 
   lines.push('  }');

package/src/routing/scanner.ts

@@ -18,8 +18,8 @@ import type {
   ScannerConfig,
   InterceptionMarker,
 } from './types.js';
-import { classifyUrlSegment } from './segment-classify.js';
-import { DEFAULT_PAGE_EXTENSIONS, INTERCEPTION_MARKERS } from './types.js';
+import { classifySegment } from './segment-classify.js';
+import { DEFAULT_PAGE_EXTENSIONS } from './types.js';
 import { classifyMetadataRoute, isDynamicMetadataExtension } from '../server/metadata-routes.js';
 
 /**
@@ -127,86 +127,10 @@ function createSegmentNode(
     interceptionMarker,
     interceptedSegmentName,
     children: [],
-    slots: new Map(),
+    slots: {},
   };
 }
 
-/**
- * Classify a directory name into its segment type.
- */
-export function classifySegment(dirName: string): {
-  type: SegmentType;
-  paramName?: string;
-  interceptionMarker?: InterceptionMarker;
-  interceptedSegmentName?: string;
-} {
-  // Private folder: _name (excluded from routing)
-  if (dirName.startsWith('_')) {
-    return { type: 'private' };
-  }
-
-  // Parallel route slot: @name
-  if (dirName.startsWith('@')) {
-    return { type: 'slot' };
-  }
-
-  // Intercepting routes: (.)name, (..)name, (...)name, (..)(..)name
-  // Check before route groups since intercepting markers also start with (
-  const interception = parseInterceptionMarker(dirName);
-  if (interception) {
-    return {
-      type: 'intercepting',
-      interceptionMarker: interception.marker,
-      interceptedSegmentName: interception.segmentName,
-    };
-  }
-
-  // Route group: (name)
-  if (dirName.startsWith('(') && dirName.endsWith(')')) {
-    return { type: 'group' };
-  }
-
-  // Bracket-syntax segments: [param], [...param], [[...param]]
-  // Delegated to the shared character-based classifier. If you change
-  // bracket syntax, update segment-classify.ts — not here.
-  const urlSeg = classifyUrlSegment(dirName);
-  if (urlSeg.kind !== 'static') {
-    return { type: urlSeg.kind, paramName: urlSeg.name };
-  }
-
-  return { type: 'static' };
-}
-
-/**
- * Parse an interception marker from a directory name.
- *
- * Returns the marker and the remaining segment name, or null if not an
- * intercepting route. Markers are checked longest-first to avoid (..)
- * matching before (..)(..).
- *
- * Examples:
- *   "(.)photo"      → { marker: "(.)", segmentName: "photo" }
- *   "(..)feed"      → { marker: "(..)", segmentName: "feed" }
- *   "(...)photos"   → { marker: "(...)", segmentName: "photos" }
- *   "(..)(..)admin" → { marker: "(..)(..)", segmentName: "admin" }
- *   "(marketing)"   → null (route group, not interception)
- */
-function parseInterceptionMarker(
-  dirName: string
-): { marker: InterceptionMarker; segmentName: string } | null {
-  for (const marker of INTERCEPTION_MARKERS) {
-    if (dirName.startsWith(marker)) {
-      const rest = dirName.slice(marker.length);
-      // Must have a segment name after the marker, and the rest must not
-      // be empty or end with ) (which would be a route group like "(auth)")
-      if (rest.length > 0 && !rest.endsWith(')')) {
-        return { marker, segmentName: rest };
-      }
-    }
-  }
-  return null;
-}
-
 /**
  * Compute the URL path for a child segment given its parent's URL path.
  * Route groups, slots, and intercepting routes do NOT add URL depth.
@@ -292,27 +216,27 @@ function scanSegmentFiles(dirPath: string, node: SegmentNode, extSet: Set<string
     // Recognized regardless of pageExtensions — .json is a data format, not a page extension.
     if (STATUS_CODE_PATTERN.test(name) && ext === 'json') {
       if (!node.jsonStatusFiles) {
-        node.jsonStatusFiles = new Map();
+        node.jsonStatusFiles = {};
       }
-      node.jsonStatusFiles.set(name, { filePath: fullPath, extension: ext });
+      node.jsonStatusFiles[name] = { filePath: fullPath, extension: ext };
       continue;
     }
 
     // Status-code files (401.tsx, 4xx.tsx, 503.tsx, 5xx.tsx)
     if (STATUS_CODE_PATTERN.test(name) && extSet.has(ext)) {
       if (!node.statusFiles) {
-        node.statusFiles = new Map();
+        node.statusFiles = {};
       }
-      node.statusFiles.set(name, { filePath: fullPath, extension: ext });
+      node.statusFiles[name] = { filePath: fullPath, extension: ext };
       continue;
     }
 
     // Legacy compat files (not-found.tsx, forbidden.tsx, unauthorized.tsx)
     if (name in LEGACY_STATUS_FILES && extSet.has(ext)) {
       if (!node.legacyStatusFiles) {
-        node.legacyStatusFiles = new Map();
+        node.legacyStatusFiles = {};
       }
-      node.legacyStatusFiles.set(name, { filePath: fullPath, extension: ext });
+      node.legacyStatusFiles[name] = { filePath: fullPath, extension: ext };
       continue;
     }
 
@@ -323,19 +247,19 @@ function scanSegmentFiles(dirPath: string, node: SegmentNode, extSet: Set<string
     const metaInfo = classifyMetadataRoute(entry);
     if (metaInfo) {
       if (!node.metadataRoutes) {
-        node.metadataRoutes = new Map();
+        node.metadataRoutes = {};
       }
-      const existing = node.metadataRoutes.get(name);
+      const existing = node.metadataRoutes[name];
       if (existing) {
         // Dynamic > static precedence: only overwrite if the new file is dynamic
         // or the existing file is static (dynamic always wins).
         const existingIsDynamic = isDynamicMetadataExtension(name, existing.extension);
         const newIsDynamic = isDynamicMetadataExtension(name, ext);
         if (newIsDynamic || !existingIsDynamic) {
-          node.metadataRoutes.set(name, { filePath: fullPath, extension: ext });
+          node.metadataRoutes[name] = { filePath: fullPath, extension: ext };
         }
       } else {
-        node.metadataRoutes.set(name, { filePath: fullPath, extension: ext });
+        node.metadataRoutes[name] = { filePath: fullPath, extension: ext };
       }
     }
   }
@@ -412,10 +336,10 @@ function scanChildren(dirPath: string, parentNode: SegmentNode, extSet: Set<stri
     // Recurse into subdirectories
     scanChildren(fullPath, childNode, extSet);
 
-    // Attach to parent: slots go into slots map, everything else is a child
+    // Attach to parent: slots go into slots record, everything else is a child
     if (type === 'slot') {
       const slotName = entry.slice(1); // remove @
-      parentNode.slots.set(slotName, childNode);
+      parentNode.slots[slotName] = childNode;
     } else {
       parentNode.children.push(childNode);
     }
@@ -477,7 +401,7 @@ function collectRoutableLeaves(
   }
 
   // Recurse into slots — each slot is its own parallel route space
-  for (const [, slotNode] of node.slots) {
+  for (const slotNode of Object.values(node.slots)) {
     collectRoutableLeaves(slotNode, seen, currentPath, true);
   }
 }
@@ -525,7 +449,7 @@ function walkForDuplicateParams(node: SegmentNode, seen: Map<string, string>): v
 
   // Slots are independent parallel routes — start fresh param tracking
   // (a slot's params don't conflict with the main route's params)
-  for (const [, slotNode] of node.slots) {
+  for (const slotNode of Object.values(node.slots)) {
     walkForDuplicateParams(slotNode, new Map(seen));
   }
 }

package/src/routing/segment-classify.ts

@@ -1,15 +1,20 @@
 /**
- * Shared URL segment classifier.
+ * Shared segment classifier — both URL tokens and filesystem directory names.
  *
- * Single-pass character parser that classifies a route segment token
- * (e.g. "dashboard", "[id]", "[...slug]", "[[...path]]") into a typed
- * discriminated union. Used by both server-side routing and client-side
- * Link interpolation.
+ * `classifyUrlSegment(token)` is a pure single-pass character parser that
+ * classifies a route segment token (e.g. "dashboard", "[id]", "[...slug]",
+ * "[[...path]]") into a typed discriminated union. NO regex, NO Node.js-only
+ * APIs — safe to import from browser code (used by `Link` interpolation).
  *
- * NO regex. NO Node.js-only APIs. Safe to import from browser code.
+ * `classifySegment(dirName)` is the build-time directory-name classifier
+ * used by the scanner. It recognizes timber-only conventions (private
+ * `_*`, parallel `@*`, route groups `(name)`, intercepting routes
+ * `(.)`/`(..)`/`(...)`/`(..)(..)`) and delegates bracket syntax to
+ * `classifyUrlSegment`. It is the **single source of truth** for what
+ * counts as a routing segment — there is no separate copy in the
+ * scanner. (TIM-848.)
  *
- * Malformed input (unclosed brackets, empty names, etc.) falls through
- * to { kind: 'static' } — the safe default.
+ * Malformed input falls through to `{ kind: 'static' }` — the safe default.
  *
  * If you change the bracket syntax, update ONLY this file. Every
  * consumer imports from here.
@@ -17,6 +22,9 @@
  * See design/07-routing.md §"Route Segments"
  */
 
+import type { InterceptionMarker, SegmentType } from './types.js';
+import { INTERCEPTION_MARKERS } from './types.js';
+
 export type UrlSegment =
   | { kind: 'static'; value: string }
   | { kind: 'dynamic'; name: string }
@@ -87,3 +95,94 @@ export function classifyUrlSegment(token: string): UrlSegment {
   }
   return { kind: 'dynamic', name };
 }
+
+// ─── Directory-name classifier (build-time scanner) ─────────────────────────
+
+/** Result of classifying a filesystem directory name. */
+export interface SegmentClassification {
+  type: SegmentType;
+  paramName?: string;
+  interceptionMarker?: InterceptionMarker;
+  interceptedSegmentName?: string;
+}
+
+/**
+ * Classify a directory name into its segment type.
+ *
+ * Recognizes all timber file-system conventions in priority order:
+ *   1. Private folders: `_name` (excluded from routing)
+ *   2. Parallel route slots: `@name`
+ *   3. Intercepting routes: `(.)name`, `(..)name`, `(...)name`, `(..)(..)name`
+ *   4. Route groups: `(name)`
+ *   5. Bracket syntax: `[id]`, `[...slug]`, `[[...path]]` (delegated to
+ *      `classifyUrlSegment`)
+ *   6. Static: anything else
+ *
+ * If you change the bracket syntax, update only `classifyUrlSegment`.
+ * If you change the directory-prefix conventions, update this function.
+ */
+export function classifySegment(dirName: string): SegmentClassification {
+  // Private folder: _name (excluded from routing)
+  if (dirName.startsWith('_')) {
+    return { type: 'private' };
+  }
+
+  // Parallel route slot: @name
+  if (dirName.startsWith('@')) {
+    return { type: 'slot' };
+  }
+
+  // Intercepting routes: (.)name, (..)name, (...)name, (..)(..)name
+  // Check before route groups since intercepting markers also start with (
+  const interception = parseInterceptionMarker(dirName);
+  if (interception) {
+    return {
+      type: 'intercepting',
+      interceptionMarker: interception.marker,
+      interceptedSegmentName: interception.segmentName,
+    };
+  }
+
+  // Route group: (name)
+  if (dirName.startsWith('(') && dirName.endsWith(')')) {
+    return { type: 'group' };
+  }
+
+  // Bracket-syntax segments: [param], [...param], [[...param]]
+  const urlSeg = classifyUrlSegment(dirName);
+  if (urlSeg.kind !== 'static') {
+    return { type: urlSeg.kind, paramName: urlSeg.name };
+  }
+
+  return { type: 'static' };
+}
+
+/**
+ * Parse an interception marker from a directory name.
+ *
+ * Returns the marker and the remaining segment name, or null if not an
+ * intercepting route. Markers are checked longest-first to avoid `(..)`
+ * matching before `(..)(..)`.
+ *
+ * Examples:
+ *   "(.)photo"      → { marker: "(.)", segmentName: "photo" }
+ *   "(..)feed"      → { marker: "(..)", segmentName: "feed" }
+ *   "(...)photos"   → { marker: "(...)", segmentName: "photos" }
+ *   "(..)(..)admin" → { marker: "(..)(..)", segmentName: "admin" }
+ *   "(marketing)"   → null (route group, not interception)
+ */
+function parseInterceptionMarker(
+  dirName: string
+): { marker: InterceptionMarker; segmentName: string } | null {
+  for (const marker of INTERCEPTION_MARKERS) {
+    if (dirName.startsWith(marker)) {
+      const rest = dirName.slice(marker.length);
+      // Must have a segment name after the marker, and the rest must not
+      // be empty or end with ) (which would be a route group like "(auth)")
+      if (rest.length > 0 && !rest.endsWith(')')) {
+        return { marker, segmentName: rest };
+      }
+    }
+  }
+  return null;
+}