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

package/dist/plugins/routing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../../src/plugins/routing.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAiB,MAAM,MAAM,CAAC;AAoBlD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AA0F1D,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAmNxD"}
+{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../../src/plugins/routing.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAiB,MAAM,MAAM,CAAC;AAwBlD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AA2F1D,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAuNxD"}

package/dist/routing/segment-codegen.d.ts

@@ -1,23 +1,36 @@
 /**
- * _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 type { RouteTree } 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 declare function buildDirToRouteMap(tree: RouteTree, appDir: string): Map<string, string>;
+export declare function buildDirToRouteMap(tree: RouteTree, appDir: string): Map<string, SegmentInfo>;
 /**
- * Generate per-route _segment.d.ts files in .timber/types/ mirroring
+ * Generate the full $segment.d.ts content for a segment.
+ */
+export declare function generateSegmentDts(info: SegmentInfo): string;
+/**
+ * Generate per-route $segment.d.ts files in .timber/types/ mirroring
  * the app/ directory structure. These files are importable via TypeScript's
  * rootDirs feature.
  */

package/dist/routing/segment-codegen.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"segment-codegen.d.ts","sourceRoot":"","sources":["../../src/routing/segment-codegen.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAe,MAAM,YAAY,CAAC;AAEzD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAmBvF;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAqBf"}
+{"version":3,"file":"segment-codegen.d.ts","sourceRoot":"","sources":["../../src/routing/segment-codegen.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAe,MAAM,YAAY,CAAC;AAEzD,sDAAsD;AACtD,MAAM,WAAW,WAAW;IAC1B,qFAAqF;IACrF,KAAK,EAAE,MAAM,CAAC;IACd;sDACkD;IAClD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAuB5F;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAM5D;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAqBf"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.114",
+  "version": "0.2.0-alpha.115",
   "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/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/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/request-context.ts

@@ -115,7 +115,7 @@ 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.
+  // bugs like passing a child route's $segment to a parent layout.
   // See design/41-global-params.md §Runtime Validation
   if (route && isDebug() && store.matchedRoutePattern) {
     const expected = extractDynamicSegments(route);