@timber-js/app 0.2.0-alpha.114 → 0.2.0-alpha.116

package/dist/server/pipeline-phases.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline-phases.d.ts","sourceRoot":"","sources":["../../src/server/pipeline-phases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAoBH,OAAO,EAA2C,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEpG,OAAO,EAAqB,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC7E,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAKrF,UAAU,aAAa;IACrB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,mBAAmB,CAAC;CACpC;AAID;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,aAAa,EACvB,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,YAAY,CAAC,CAavB;AAID;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,cAAc,EACtB,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,eAAe,EAAE,OAAO,EACxB,oBAAoB,EAAE,OAAO,EAC7B,aAAa,EAAE,aAAa,GAC3B,OAAO,CAAC,YAAY,CAAC,CA6DvB;AAID;;;GAGG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,cAAc,EACtB,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,eAAe,EAAE,OAAO,EACxB,oBAAoB,EAAE,OAAO,EAC7B,EAAE,iBAAiB,EAAE,YAAY,EAAE,EAAE,aAAa,GACjD,OAAO,CAAC,YAAY,CAAC,CAkBvB;AAID;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,cAAc,EACtB,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,QAAQ,CAAC,CA0PnB"}
+{"version":3,"file":"pipeline-phases.d.ts","sourceRoot":"","sources":["../../src/server/pipeline-phases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAoBH,OAAO,EAA2C,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEpG,OAAO,EAAqB,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC7E,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAKrF,UAAU,aAAa;IACrB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,mBAAmB,CAAC;CACpC;AAID;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,aAAa,EACvB,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,YAAY,CAAC,CAavB;AAID;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,cAAc,EACtB,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,eAAe,EAAE,OAAO,EACxB,oBAAoB,EAAE,OAAO,EAC7B,aAAa,EAAE,aAAa,GAC3B,OAAO,CAAC,YAAY,CAAC,CA6DvB;AAID;;;GAGG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,cAAc,EACtB,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,eAAe,EAAE,OAAO,EACxB,oBAAoB,EAAE,OAAO,EAC7B,EAAE,iBAAiB,EAAE,YAAY,EAAE,EAAE,aAAa,GACjD,OAAO,CAAC,YAAY,CAAC,CAkBvB;AAID;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,cAAc,EACtB,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,QAAQ,CAAC,CA4PnB"}

package/dist/server/request-context.d.ts

@@ -40,16 +40,16 @@ export declare function getSearchParams(): URLSearchParams;
 /**
  * Returns the current request's coerced segment params.
  *
- * The optional `_route` argument exists only for TypeScript narrowing —
- * it does not affect the runtime return value. Pass a route pattern
- * (e.g. `'/[artistSlug]/[year]'`) to narrow the return type to the
- * exact params shape for that route.
+ * The optional `segmentPath` argument exists only for TypeScript narrowing —
+ * it does not affect the runtime return value. Pass a segment path
+ * (e.g. `'/(browse)/[artistSlug]/[year]'`) to narrow the return type to the
+ * exact params shape for that segment.
  *
- * Without a route argument, returns all coerced params with optional types.
+ * Without an argument, returns all coerced params with optional types.
  *
  * See design/41-global-params.md §Function Signatures
  */
-export declare function getSegmentParams(route?: string): Record<string, string | string[]>;
+export declare function getSegmentParams(segmentPath?: string): Record<string, string | string[]>;
 /**
  * Set the segment params on the current request context.
  * Called by the pipeline after route matching and param coercion.
@@ -58,12 +58,12 @@ export declare function getSegmentParams(route?: string): Record<string, string
  */
 export declare function setSegmentParams(params: Record<string, string | string[]>): void;
 /**
- * Store the matched route pattern (e.g. '/[artistSlug]/[year]') for
- * dev-mode route mismatch validation in getSegmentParams().
+ * Store the matched segment path (e.g. '/(browse)/[artistSlug]/[year]') for
+ * dev-mode validation in getSegmentParams().
  *
  * @internal — framework use only
  */
-export declare function setMatchedRoutePattern(pattern: string): void;
+export declare function setMatchedSegmentPath(segmentPath: string): void;
 /**
  * Returns the raw search string from the current request URL (e.g. "?foo=bar").
  * Synchronous — safe for use in `redirect()` which throws synchronously.

package/dist/server/request-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"request-context.d.ts","sourceRoot":"","sources":["../../src/server/request-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,iBAAiB,EAA4B,MAAM,mBAAmB,CAAC;AAOhF,OAAO,EAAE,iBAAiB,EAAE,CAAC;AAQ7B;;;;;GAKG;AACH,wBAAgB,UAAU,IAAI,eAAe,CAS5C;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG1D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,eAAe,CASjD;AAaD;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAkClF;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAMhF;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAI5D;AAkBD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAG/C;AAID;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,IAAI,CAChC,OAAO,EACP,KAAK,GAAG,KAAK,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,MAAM,CAAC,QAAQ,CACnF,CAAC;AAIF;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAmBrE;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAK9D;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAK1C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAmBhE"}
+{"version":3,"file":"request-context.d.ts","sourceRoot":"","sources":["../../src/server/request-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,iBAAiB,EAA4B,MAAM,mBAAmB,CAAC;AAOhF,OAAO,EAAE,iBAAiB,EAAE,CAAC;AAQ7B;;;;;GAKG;AACH,wBAAgB,UAAU,IAAI,eAAe,CAS5C;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG1D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,eAAe,CASjD;AAaD;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAkCxF;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,IAAI,CAMhF;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAI/D;AAkBD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAG/C;AAID;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,IAAI,CAChC,OAAO,EACP,KAAK,GAAG,KAAK,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,MAAM,CAAC,QAAQ,CACnF,CAAC;AAIF;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAmBrE;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAK9D;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAK1C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAmBhE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.114",
+  "version": "0.2.0-alpha.116",
   "description": "Vite-native React framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",

package/src/client/use-segment-params.ts

@@ -115,15 +115,15 @@ export function notifyParamsListeners(): void {
  * When called outside a React component (e.g., in test assertions),
  * falls back to the module-level snapshot.
  *
- * @overload Typed — when a known route path is passed, returns the
+ * @overload Typed — when a known segment path is passed, returns the
  *   exact params shape from the generated Routes interface.
  * @overload Fallback — returns the generic params record.
  */
 export function useSegmentParams<R extends keyof Routes>(
-  route: R
+  segmentPath: R
 ): Routes[R] extends { segmentParams: infer P } ? P : Record<string, string | string[]>;
-export function useSegmentParams(route?: string): Record<string, string | string[]>;
-export function useSegmentParams(_route?: string): Record<string, string | string[]> {
+export function useSegmentParams(segmentPath?: string): Record<string, string | string[]>;
+export function useSegmentParams(_segmentPath?: string): Record<string, string | string[]> {
   // Try reading from NavigationContext (client-side, inside React tree).
   // During SSR, no NavigationProvider is mounted, so this returns null.
   // When called outside a React component, useContext throws — caught below.

package/src/plugins/routing.ts

@@ -15,7 +15,11 @@ import { join } from 'node:path';
 import { scanRoutes } from '../routing/scanner.js';
 import { generateRouteMap } from '../routing/codegen.js';
 import { collectInterceptionRewrites } from '../routing/interception.js';
-import { buildDirToRouteMap, writeSegmentTypes } from '../routing/segment-codegen.js';
+import {
+  buildDirToRouteMap,
+  writeSegmentTypes,
+  type SegmentInfo,
+} from '../routing/segment-codegen.js';
 import {
   collectDynamicSegments,
   findSchemaFile,
@@ -56,12 +60,13 @@ const RESOLVED_SEARCH_PARAMS_REGISTRY_ID = `\0${SEARCH_PARAMS_REGISTRY_ID}`;
 const SCHEMA_ID = 'virtual:timber-schema';
 const RESOLVED_SCHEMA_ID = `\0${SCHEMA_ID}`;
 
-// TIM-935: _segment virtual module prefix.
+// TIM-935: $segment virtual module prefix.
+// Resolved ID encodes segment info as JSON after the prefix.
 //
 // Each route directory gets a virtual module that exports the route
-// pattern string. `import { route } from './_segment'` resolves to
-// `\0_segment:<route-pattern>` which returns `export const route = '...'`.
-const SEGMENT_PREFIX = '\0_segment:';
+// and segmentPath. `import { route, segmentPath } from './$segment'`
+// resolves to `\0$segment:<json>`.
+const SEGMENT_PREFIX = '\0$segment:';
 
 /**
  * File convention names we track for changes that require manifest regeneration.
@@ -122,8 +127,8 @@ export function timberRouting(ctx: PluginContext): Plugin {
   /** Track warned files to avoid repeating warnings on rescan. */
   const warnedFiles = new Set<string>();
 
-  /** Maps absolute filesystem directory → route pattern for _segment resolution. */
-  let dirToRoute: Map<string, string> = new Map();
+  /** Maps absolute filesystem directory → segment info for $segment resolution. */
+  let dirToRoute: Map<string, SegmentInfo> = new Map();
 
   function rescan(): void {
     // Check app/ directory exists before scanning
@@ -204,19 +209,19 @@ export function timberRouting(ctx: PluginContext): Plugin {
         return RESOLVED_SCHEMA_ID;
       }
 
-      // TIM-935: _segment virtual module.
-      // Resolves `import { route } from './_segment'` based on the
+      // TIM-935: $segment virtual module.
+      // Resolves `import { route } from './$segment'` based on the
       // importing file's directory in the app/ tree.
       if (
         importer &&
-        (cleanId === './_segment' || cleanId === './_segment.js' || cleanId === './_segment.ts')
+        (cleanId === './$segment' || cleanId === './$segment.js' || cleanId === './$segment.ts')
       ) {
         // Strip \0 prefix from importer if present
         const cleanImporter = importer.startsWith('\0') ? importer.slice(1) : importer;
         const importerDir = cleanImporter.substring(0, cleanImporter.lastIndexOf('/'));
-        const routePattern = dirToRoute.get(importerDir);
-        if (routePattern !== undefined) {
-          return `${SEGMENT_PREFIX}${routePattern}`;
+        const segmentInfo = dirToRoute.get(importerDir);
+        if (segmentInfo !== undefined) {
+          return `${SEGMENT_PREFIX}${JSON.stringify(segmentInfo)}`;
         }
       }
 
@@ -249,10 +254,14 @@ export function timberRouting(ctx: PluginContext): Plugin {
         return generateSchemaModule(ctx.appDir);
       }
 
-      // TIM-935: _segment virtual module — exports the route pattern string.
+      // TIM-935: $segment virtual module — exports route and segmentPath.
       if (id.startsWith(SEGMENT_PREFIX)) {
-        const routePattern = id.slice(SEGMENT_PREFIX.length);
-        return `export const route = ${JSON.stringify(routePattern)};\n`;
+        const info: SegmentInfo = JSON.parse(id.slice(SEGMENT_PREFIX.length));
+        return [
+          `export const ROUTE = ${JSON.stringify(info.route)};`,
+          `export const SEGMENT_PATH = ${JSON.stringify(info.segmentPath)};`,
+          '',
+        ].join('\n');
       }
 
       return null;
@@ -383,7 +392,7 @@ function invalidateManifest(server: ViteDevServer): void {
       }
     }
 
-    // TIM-935: Invalidate all _segment virtual modules (prefixed \0_segment:)
+    // TIM-935: Invalidate all $segment virtual modules (prefixed \0$segment:)
     for (const mod of env.moduleGraph.idToModuleMap.values()) {
       if (mod.id?.startsWith(SEGMENT_PREFIX)) {
         env.moduleGraph.invalidateModule(mod);

package/src/routing/codegen-types.ts

@@ -10,6 +10,9 @@
 export interface RouteEntry {
   /** URL path pattern (e.g. "/products/[id]") */
   urlPath: string;
+  /** Full tree path including groups and slots (e.g. "/(browse)/[artistSlug]/@shows/[year]").
+   *  Uniquely identifies a segment — unlike urlPath which strips groups/slots. */
+  segmentPath: string;
   /** Accumulated params from all ancestor dynamic segments */
   params: ParamEntry[];
   /** Whether the page.tsx exports searchParams */

package/src/routing/codegen.ts

@@ -48,7 +48,7 @@ export function generateRouteMap(tree: RouteTree, options: CodegenOptions = {}):
   const hasSchema = options.hasSchema ?? detectSchema(options.appDir);
 
   const routes: RouteEntry[] = [];
-  collectRoutes(tree.root, [], [], routes, hasSchema);
+  collectRoutes(tree.root, [], [], '', routes, hasSchema);
 
   // Sort routes alphabetically for deterministic output
   routes.sort((a, b) => a.urlPath.localeCompare(b.urlPath));
@@ -80,9 +80,13 @@ function collectRoutes(
   node: SegmentNode,
   ancestorParams: ParamEntry[],
   ancestorParamsFiles: string[],
+  parentTreePath: string,
   routes: RouteEntry[],
   hasSchema: boolean
 ): void {
+  // Build the tree path (includes groups, slots — uniquely identifies this segment).
+  // Root node has empty segmentName, producing treePath = ''.
+  const treePath = node.segmentName ? `${parentTreePath}/${node.segmentName}` : parentTreePath;
   // TIM-834: Identify this segment's own params.ts (if it has a
   // segmentParams export). The full chain of params.ts files in the
   // route ancestry is threaded down via `ancestorParamsFiles`; codec
@@ -148,6 +152,7 @@ function collectRoutes(
 
     const entry: RouteEntry = {
       urlPath: node.urlPath,
+      segmentPath: treePath || '/',
       params: resolvedParams,
       hasSearchParams: false,
       isApiRoute,
@@ -170,12 +175,12 @@ function collectRoutes(
 
   // Recurse into children
   for (const child of node.children) {
-    collectRoutes(child, params, nextAncestorFiles, routes, hasSchema);
+    collectRoutes(child, params, nextAncestorFiles, treePath, routes, hasSchema);
   }
 
   // Recurse into slots (they share the parent's URL path, but may have their own pages)
   for (const slot of Object.values(node.slots)) {
-    collectRoutes(slot, params, nextAncestorFiles, routes, hasSchema);
+    collectRoutes(slot, params, nextAncestorFiles, treePath, routes, hasSchema);
   }
 }
 
@@ -245,14 +250,14 @@ function formatSchemaTypes(routes: RouteEntry[]): string[] {
   lines.push('/** Union of all valid route patterns. */');
   lines.push('export type TimberRoute = keyof TimberSegmentParams;');
   lines.push('');
-  lines.push('/** Maps each route pattern to its accumulated segment params. */');
+  lines.push('/** Maps each segment path to its accumulated segment params. */');
   lines.push('export interface TimberSegmentParams {');
 
   for (const route of routes) {
     if (route.params.length === 0) {
-      lines.push(`  '${route.urlPath}': {};`);
+      lines.push(`  '${route.segmentPath}': {};`);
     } else {
-      lines.push(`  '${route.urlPath}': {`);
+      lines.push(`  '${route.segmentPath}': {`);
       for (const p of route.params) {
         lines.push(`    ${p.name}: ${buildSchemaParamType(p)};`);
       }
@@ -356,7 +361,9 @@ function formatDeclarationFile(
     lines.push("declare module '@timber-js/app/server' {");
     for (const route of dynamicRoutes) {
       const paramsType = formatParamsType(route.params, importBase, hasSchema);
-      lines.push(`  export function getSegmentParams(route: '${route.urlPath}'): ${paramsType}`);
+      lines.push(
+        `  export function getSegmentParams(segmentPath: '${route.segmentPath}'): ${paramsType}`
+      );
     }
     lines.push('  export function getSegmentParams(): Record<string, string | string[]>');
     lines.push('}');
@@ -372,11 +379,13 @@ function formatDeclarationFile(
     );
     lines.push('');
 
-    // useParams overloads
+    // useSegmentParams overloads
     if (dynamicRoutes.length > 0) {
       for (const route of dynamicRoutes) {
         const paramsType = formatParamsType(route.params, importBase, hasSchema);
-        lines.push(`  export function useSegmentParams(route: '${route.urlPath}'): ${paramsType}`);
+        lines.push(
+          `  export function useSegmentParams(segmentPath: '${route.segmentPath}'): ${paramsType}`
+        );
       }
       lines.push('  export function useSegmentParams(): Record<string, string | string[]>');
       lines.push('');

package/src/routing/segment-codegen.ts

@@ -1,47 +1,72 @@
 /**
- * _segment type generation and directory-to-route mapping.
+ * $segment type generation and directory-to-route mapping.
  *
- * Generates per-route _segment.d.ts files in .timber/types/ that mirror
+ * Generates per-route $segment.d.ts files in .timber/types/ that mirror
  * the app/ directory structure. TypeScript's rootDirs feature makes these
- * importable as './_segment' from route files.
+ * importable as './$segment' from route files.
  *
- * Design doc: design/41-global-params.md §The _segment Module
+ * Design doc: design/41-global-params.md §The $segment Module
  */
 
 import { writeFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import type { RouteTree, SegmentNode } from './types.js';
 
+/** Info carried per directory for type generation. */
+export interface SegmentInfo {
+  /** The URL route pattern (groups and slots stripped). e.g. '/[artistSlug]/[year]' */
+  route: string;
+  /** The full tree path including groups and slots — uniquely identifies a segment.
+   *  e.g. '/(browse)/[artistSlug]/@shows/[year]' */
+  segmentPath: string;
+}
+
 /**
- * Build a map of absolute filesystem directory → route pattern.
- * Used by resolveId to map a _segment import's importer to the correct route.
+ * Build a map of absolute filesystem directory → segment info.
+ * Used by resolveId to map a $segment import's importer to the correct route,
+ * and by writeSegmentTypes to generate per-route $segment.d.ts files.
  *
  * Walks every segment (not just leaves) so layouts and middleware
- * at any depth can import _segment.
+ * at any depth can import $segment.
  */
-export function buildDirToRouteMap(tree: RouteTree, appDir: string): Map<string, string> {
-  const map = new Map<string, string>();
+export function buildDirToRouteMap(tree: RouteTree, appDir: string): Map<string, SegmentInfo> {
+  const map = new Map<string, SegmentInfo>();
 
-  function walk(node: SegmentNode, fsPath: string): void {
-    const routePattern = node.urlPath || '/';
-    map.set(fsPath, routePattern);
+  function walk(node: SegmentNode, fsPath: string, treePath: string): void {
+    map.set(fsPath, {
+      route: node.urlPath || '/',
+      segmentPath: treePath || '/',
+    });
 
     for (const child of node.children) {
       const childDir = join(fsPath, child.segmentName);
-      walk(child, childDir);
+      const childTreePath = `${treePath}/${child.segmentName}`;
+      walk(child, childDir, childTreePath);
     }
     for (const [slotName, slotNode] of Object.entries(node.slots)) {
-      const slotDir = join(fsPath, slotName);
-      walk(slotNode, slotDir);
+      const slotDir = join(fsPath, `@${slotName}`);
+      const slotTreePath = `${treePath}/@${slotName}`;
+      walk(slotNode, slotDir, slotTreePath);
     }
   }
 
-  walk(tree.root, appDir);
+  walk(tree.root, appDir, '');
   return map;
 }
 
 /**
- * Generate per-route _segment.d.ts files in .timber/types/ mirroring
+ * Generate the full $segment.d.ts content for a segment.
+ */
+export function generateSegmentDts(info: SegmentInfo): string {
+  return [
+    `export const ROUTE: '${info.route}';`,
+    `export const SEGMENT_PATH: '${info.segmentPath}';`,
+    '',
+  ].join('\n');
+}
+
+/**
+ * Generate per-route $segment.d.ts files in .timber/types/ mirroring
  * the app/ directory structure. These files are importable via TypeScript's
  * rootDirs feature.
  */
@@ -57,15 +82,15 @@ export async function writeSegmentTypes(
   const map = buildDirToRouteMap(routeTree, appDir);
 
   const writes: Promise<void>[] = [];
-  for (const [fsDir, routePattern] of map) {
+  for (const [fsDir, info] of map) {
     // Mirror the app/ structure under .timber/types/
     const relDir = fsDir.slice(appDir.length); // e.g. '/[artistSlug]/[year]'
     const segmentDir = join(typesBase, relDir);
-    const segmentPath = join(segmentDir, '_segment.d.ts');
-    const content = `export const route: '${routePattern}';\n`;
+    const segmentFile = join(segmentDir, '$segment.d.ts');
+    const content = generateSegmentDts(info);
 
     writes.push(
-      mkdir(segmentDir, { recursive: true }).then(() => writeFile(segmentPath, content, 'utf-8'))
+      mkdir(segmentDir, { recursive: true }).then(() => writeFile(segmentFile, content, 'utf-8'))
     );
   }
 

package/src/server/als-registry.ts

@@ -60,12 +60,13 @@ export interface RequestContextStore {
    */
   segmentParams?: Record<string, string | string[]>;
   /**
-   * The matched route pattern (e.g. '/[artistSlug]/[year]').
-   * Set by the pipeline alongside segmentParams. Used by
-   * getSegmentParams() for dev-mode route mismatch validation.
+   * The matched segment path (e.g. '/(browse)/[artistSlug]/[year]').
+   * Includes route groups and parallel slots — uniquely identifies the
+   * segment in the route tree. Set by the pipeline alongside segmentParams.
+   * Used by getSegmentParams() for dev-mode validation.
    * See design/41-global-params.md §Runtime Validation
    */
-  matchedRoutePattern?: string;
+  matchedSegmentPath?: string;
   /** Outgoing Set-Cookie entries (name → serialized value + options). Last write wins. */
   cookieJar: Map<string, CookieEntry>;
   /** Whether the response has flushed (headers committed). */

package/src/server/pipeline-phases.ts

@@ -20,7 +20,7 @@ import {
   applyRequestHeaderOverlay,
   setMutableCookieContext,
   setSegmentParams,
-  setMatchedRoutePattern,
+  setMatchedSegmentPath,
 } from './request-context.js';
 import { withSpan } from './tracing.js';
 import { logRenderError } from './logger.js';
@@ -419,12 +419,14 @@ export async function handleRequest(
   // See design/07-routing.md §"params.ts — Convention File for Typed Params"
   setSegmentParams(match.segmentParams);
 
-  // Store the matched route pattern for dev-mode validation in getSegmentParams().
-  // The leaf segment's urlPath is the accumulated route pattern.
-  const leaf = match.segments[match.segments.length - 1];
-  if (leaf) {
-    setMatchedRoutePattern(leaf.urlPath);
-  }
+  // Store the matched segment path for dev-mode validation in getSegmentParams().
+  // Build the tree path from the segment chain (includes groups and slots).
+  const segmentPath =
+    match.segments
+      .map((s) => s.segmentName)
+      .filter(Boolean)
+      .join('/') || '/';
+  setMatchedSegmentPath(segmentPath.startsWith('/') ? segmentPath : `/${segmentPath}`);
 
   // Bypass middleware for synthetic re-render requests built by the
   // action-dispatch wrapper after a no-JS form validation failure.

package/src/server/request-context.ts

@@ -89,16 +89,16 @@ _setGetSegmentParamsFn(getSegmentParams);
 /**
  * Returns the current request's coerced segment params.
  *
- * The optional `_route` argument exists only for TypeScript narrowing —
- * it does not affect the runtime return value. Pass a route pattern
- * (e.g. `'/[artistSlug]/[year]'`) to narrow the return type to the
- * exact params shape for that route.
+ * The optional `segmentPath` argument exists only for TypeScript narrowing —
+ * it does not affect the runtime return value. Pass a segment path
+ * (e.g. `'/(browse)/[artistSlug]/[year]'`) to narrow the return type to the
+ * exact params shape for that segment.
  *
- * Without a route argument, returns all coerced params with optional types.
+ * Without an argument, returns all coerced params with optional types.
  *
  * See design/41-global-params.md §Function Signatures
  */
-export function getSegmentParams(route?: string): Record<string, string | string[]> {
+export function getSegmentParams(segmentPath?: string): Record<string, string | string[]> {
   const store = requestContextAls.getStore();
   if (!store) {
     throw new Error(
@@ -113,18 +113,18 @@ export function getSegmentParams(route?: string): Record<string, string | string
     );
   }
 
-  // Dev-mode validation: warn when the route argument expects dynamic
-  // segments that don't exist on the actual matched route. This catches
-  // bugs like passing a child route's _segment to a parent layout.
+  // Dev-mode validation: warn when the segment path expects dynamic
+  // segments that don't exist on the actual matched segment. This catches
+  // bugs like passing a child segment's $segment to a parent layout.
   // See design/41-global-params.md §Runtime Validation
-  if (route && isDebug() && store.matchedRoutePattern) {
-    const expected = extractDynamicSegments(route);
-    const actual = extractDynamicSegments(store.matchedRoutePattern);
+  if (segmentPath && isDebug() && store.matchedSegmentPath) {
+    const expected = extractDynamicSegments(segmentPath);
+    const actual = extractDynamicSegments(store.matchedSegmentPath);
     const missing = expected.filter((s) => !actual.includes(s));
 
     if (missing.length > 0) {
       console.warn(
-        `[timber] getSegmentParams('${route}') called but current route is '${store.matchedRoutePattern}'\n` +
+        `[timber] getSegmentParams('${segmentPath}') called but current segment is '${store.matchedSegmentPath}'\n` +
           `  Missing params: ${missing.join(', ')}\n` +
           `  These will be undefined at runtime despite the type annotation.`
       );
@@ -149,15 +149,15 @@ export function setSegmentParams(params: Record<string, string | string[]>): voi
 }
 
 /**
- * Store the matched route pattern (e.g. '/[artistSlug]/[year]') for
- * dev-mode route mismatch validation in getSegmentParams().
+ * Store the matched segment path (e.g. '/(browse)/[artistSlug]/[year]') for
+ * dev-mode validation in getSegmentParams().
  *
  * @internal — framework use only
  */
-export function setMatchedRoutePattern(pattern: string): void {
+export function setMatchedSegmentPath(segmentPath: string): void {
   const store = requestContextAls.getStore();
   if (!store) return; // non-throwing — optional diagnostic
-  store.matchedRoutePattern = pattern;
+  store.matchedSegmentPath = segmentPath;
 }
 
 /**